docs: Comprehensive intent-driven JSDoc for TicketComponent (#8554)

Author: tobiu

apps/portal/view/news/tickets/Component.mjs

@@ -10,6 +10,19 @@ const
     regexCommit        = /\b([0-9a-f]{7,40})\b/g;
 
 /**
+ * @summary The "Markdown Transformer" for GitHub Tickets.
+ *
+ * This component extends the standard ContentComponent to provide specialized rendering for GitHub Issues.
+ * Its primary responsibility is to parse the raw Markdown content (which includes custom Frontmatter and
+ * a pre-generated Timeline section) and transform it into a rich, interactive HTML structure.
+ *
+ * **Key Responsibilities:**
+ * 1. **Parsing Pipeline**: Extracts Frontmatter, Body, and the custom "Timeline" section from the raw Markdown.
+ * 2. **Rich Rendering**: Generates HTML for Status Badges, Labels, Commit Links, and User Mentions.
+ * 3. **Data Extraction**: As a side effect of rendering, it extracts structured data (`me.timelineData`)
+ *    representing every timeline event (comment, label change, close, etc.). This data is then
+ *    pushed to the `sections` store to drive the `TimelineCanvas` visualization.
+ *
  * @class Portal.view.news.tickets.Component
  * @extends Portal.view.shared.content.Component
  */
@@ -43,6 +56,9 @@ class Component extends ContentComponent {
      */
     #dateTimeFormatToday = null
     /**
+     * Temporary storage for the structured timeline data extracted during the parsing phase.
+     * This array is populated by `renderTimeline` and `modifyMarkdown` and then assigned
+     * to the `sections` store to drive the Canvas visualization.
      * @member {Object[]} timelineData=null
      * @private
      */
@@ -218,6 +234,19 @@ class Component extends ContentComponent {
     }
 
     /**
+     * The Main Parsing Pipeline.
+     *
+     * This method intercepts the raw markdown content before it is rendered and performs a multi-pass transformation:
+     * 1. **Extract Timeline**: Pulls out the raw `## Timeline` section to process it separately.
+     * 2. **Process Frontmatter**: Extracts metadata (labels, state, author) and removes the YAML block.
+     * 3. **Render Body**: Uses the superclass (marked.js) to convert the main issue body to HTML.
+     * 4. **Inject Title IDs**: Adds IDs to H1 tags for navigation.
+     * 5. **Generate Badges**: Creates HTML for Status/Label badges based on extracted metadata.
+     * 6. **Wrap Body**: Wraps the main issue body in a `timeline-item` structure so it appears as the first item.
+     * 7. **Re-Assemble**: Concatenates Frontmatter + Title + Timeline (with Body injected) into the final HTML.
+     *
+     * **Side Effect**: Populates `me.timelineData` and updates the `sections` store.
+     *
      * @param {String} content
      * @returns {String}
      */
@@ -348,6 +377,16 @@ class Component extends ContentComponent {
     }
 
     /**
+     * Parses the custom "Timeline" markdown section.
+     *
+     * Expects a line-based format generated by the build process:
+     * - Events: `- YYYY-MM-DDTHH:mm:ss @user action text...`
+     * - Comments: `### @user - YYYY-MM-DDTHH:mm:ss` followed by comment body.
+     *
+     * This method converts these lines into structured `timeline-item` HTML blocks
+     * and simultaneously populates `me.timelineData` with semantic data (color, icon, type)
+     * for each event.
+     *
      * @param {String} content
      * @returns {String}
      */