pi-apexlang 0.2.2 → 0.4.0

package/skills/apexlang/templates/template-components/badge/badge._common.md

@@ -0,0 +1,183 @@
+---
+templateId: region.badge.common
+componentType: region
+version: 1.0
+description: Shared contract for standalone report-mode Badge template-component regions.
+---
+
+# Purpose
+
+Document generation of a data-backed Badge region emitted as `themeTemplateComponent/badge`.
+
+# Scope
+
+In scope: report-mode Badge regions, verified data sources, Badge attributes, the optional `link` action, region/column authorization, security, and governance.
+
+Out of scope: custom Badge template-component authoring and attaching Badge as a partial component inside another component.
+
+# Generation Rules (MANDATORY)
+
+1. Emit `type: themeTemplateComponent/badge` and `componentAppearance.display: report`.
+2. Use any compiler-supported data-backed report source and preserve its exact `source.location` and `source.type` contract. The 26.1 matrix is `localDatabase` or `restEnabledSql` with `tableView`, `sqlQuery`, `functionBody`, or `propertyGraph`; plus `restSource`, `jsonDualityView`, `jsonSource`, and `sampleData`, whose locations select their source shape without `source.type`. Prefer a direct table/view source for a simple verified object, `sqlQuery` for joins or computed values, and an authoritative external-source contract when data is external.
+3. Require authoritative evidence for every referenced object and column before generating object-specific source code.
+4. Map `settings.label` and `settings.value`; both are required by the Badge template metadata.
+5. Keep `settings.label` static and concise because Badge label metadata uses raw rendering. Do not bind a source column, substitution token, or other runtime input into the label.
+6. Map the `sessionStateValue` settings `value` and `state` with bare source-column aliases such as `BADGE_VALUE` and `BADGE_STATE`. Do not wrap those aliases in `&COLUMN_NAME.` substitution syntax; APEX can resolve the substitution during import and then render the resolved text as a quoted column reference.
+7. Emit one explicit child `column (...)` for every delivered source projection. Each source-backed child column uses `source.type: databaseColumn`, `source.databaseColumn`, and an exact compiler-supported `source.dataType`.
+8. Treat `settings.state` as explicit user intent. When the user does not request a semantic state, omit `settings.state`, the state projection, and the state child column so the native Badge renders its normal state. When the user does request a state, use any compiler-supported source whose projected state column guarantees exact lowercase `danger`, `warning`, `success`, or `info`. For `sqlQuery`, require every branch and an explicit `ELSE` to return an allowlisted value. For table/view, REST, remote, or other sources, require authoritative upstream enum/constraint evidence; local lint verifies the mapping and `varchar2` datatype but cannot infer arbitrary runtime row values.
+9. Emit `icon`, `displayLabel`, `style`, `shape`, and `size` only when required. Before assigning any Badge icon, load and consult the pinned Font APEX 26.1 catalogue; the icon must contain exactly one catalogue icon, with at most one optional `fa` base class and unique optional catalogue-listed modifiers. Never use a column mapping, substitution, unresolved template value, or concatenated class fragment.
+10. Badge supports at most one action in the `link` position. Every emitted action must include a numeric `layout.sequence`, which the live compiler requires for region actions. Badge has no action templates. Do not invent button/menu templates or additional positions.
+11. Use a reviewed structured `behavior.target` for Badge navigation. The local Badge policy rejects `targetUrl` because the repository has no application-specific destination allowlist; do not weaken this by passing an external destination through a column or substitution.
+12. Do not emit Badge `linkAttributes`. Custom attributes and inline event handlers are rejected; implement behavior through the reviewed structured action target.
+13. Apply `security.authorizationScheme` to the Badge region when visibility requires a verified authorization scheme. A link target must independently enforce the same or stricter authorization; hiding the Badge is not access control.
+14. Keep output escaping enabled by default. Never generate HTML markup in SQL for the Badge value, label, state, or icon.
+15. Use the native region template and options for composition. Do not invent CSS classes to reproduce Badge structure or state styling.
+16. Keep deterministic ordering in top-level `orderBy {}` for multi-row Badge regions; do not place `ORDER BY` inside `source.sqlQuery`.
+
+# Data Source Contract
+
+- Direct table/view: use for a simple verified object with direct Badge mappings; an explicitly requested mapped state column requires authoritative enum/check-constraint evidence.
+- `sqlQuery`: use for joins, computed Badge values/states, bind predicates, or aliases needed by the presentation contract; local lint proves literal and `CASE` state results.
+- `functionBody`, `propertyGraph`, `restSource`, `jsonDualityView`, `jsonSource`, `sampleData`, and remote variants require an authoritative source contract, verified returned fields, and explicit upstream state-value guarantees when `settings.state` is mapped.
+- Project only fields needed for label, value, optional state/icon, link context, deterministic ordering, and row identity.
+- A link that passes row context requires a deterministic verified key column.
+- Do not generate a source-free Badge region. The separate no-source region error is outside this component workflow.
+
+# Attribute Contract
+
+| Attribute | Required | Accepted value or mapping | Security note |
+|---|---:|---|---|
+| `settings.label` | yes | Non-empty plain static text only | Metadata renders the label raw; column mappings, substitutions, binds, unresolved template values, HTML, and event attributes are rejected. |
+| `settings.value` | yes | Bare source-column alias such as `BADGE_VALUE` | Do not use `&BADGE_VALUE.`; value metadata strips HTML, but SQL must still return raw data rather than markup. |
+| `settings.state` | no | Bare source-column alias whose values are restricted to `danger`, `warning`, `success`, or `info`; emit only when the user requests a semantic state | Do not use `&BADGE_STATE.`; treat the returned values as an allowlisted semantic token. |
+| `settings.icon` | no | Exactly one pinned Font APEX icon with optional catalog modifiers | Do not accept dynamic values, duplicate base/modifier tokens, multiple icons, or arbitrary class fragments. |
+| `settings.displayLabel` | no | boolean | Enable when the label adds meaning not already clear from context. |
+| `settings.style` | no | `outline` or `subtle` | Omit to inherit the containing template default. |
+| `settings.shape` | no | `circular`, `rounded`, or `square` | Omit to inherit the containing template default. |
+| `settings.size` | no | `small`, `medium`, or `large` | Omit to inherit the containing template default. |
+
+# Column Data Types
+
+The child column mapped by `settings.value` must use an APEX 26.1 Badge-supported value datatype: `varchar2`, `number`, `date`, `intervalYearToMonth`, or `intervalDayToSecond`. The child column mapped by `settings.state` must use `varchar2`. Auxiliary projected columns may use any compiler-supported template-component datatype.
+
+# Action Contract
+
+- Omit the action when the Badge is informational.
+- When navigation is required, emit at most one `action` with `position: link`.
+- Give every action a deterministic numeric `layout.sequence`.
+- Same-app targets must resolve to an existing authorized page and pass only verified item mappings.
+- Use a structured target. Do not emit `targetUrl` or `linkAttributes` for Badge actions.
+- Never treat Badge visibility as proof that the current user can access the target page or underlying row.
+- Badge has no action-template inventory; omit `action.template`.
+
+# Patterns
+
+- Status list: static label plus a source-backed value and allowlisted state.
+- Count/category list: source-backed value with an optional static label, no action by default.
+- Authorized drilldown: source-backed Badge with one `link` action passing a verified row key to an existing authorized page.
+
+# Anti-Patterns
+
+- Static HTML or Classic Report markup that imitates a Badge.
+- HTML-generating SQL for colors, labels, icons, or links.
+- Arbitrary state values used as CSS classes.
+- A dynamic label sourced from untrusted user HTML.
+- A Badge link to an unresolved page, guessed item, or unrestricted external URL.
+- A Badge action with `linkAttributes`, an inline event handler, or `targetUrl` without an application-specific allowlist.
+- Adding a button/menu action template; Badge exposes only the `link` action position.
+- Omitting `layout.sequence` from a Badge action; the live compiler requires it.
+- Omitting child columns for fields projected by a report-mode source.
+- Using region visibility as the only authorization check.
+
+# Output Template – Report Mode
+
+```apexlang
+region {{regionStaticId}} (
+    name: {{name}}
+    type: themeTemplateComponent/badge
+    layout {
+        sequence: {{layout.sequence}}
+        slot: body
+        startNewLayout: false
+        startNewRow: true
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    componentAppearance {
+        display: report
+    }
+{{source.block}}
+    settings {
+        label: {{settings.label}}
+        value: {{settings.valueColumn}}
+        {{#if settings.stateColumn}}
+        state: {{settings.stateColumn}}
+        {{/if}}
+        icon: {{settings.icon}}
+        displayLabel: {{settings.displayLabel}}
+        style: {{settings.style}}
+        shape: {{settings.shape}}
+        size: {{settings.size}}
+    }
+    orderBy {
+        type: staticValue
+        orderByClause: {{orderByClause}}
+    }
+    security {
+        authorizationScheme: {{security.authorizationScheme}}
+    }
+    column {{column.name}} (
+        layout {
+            sequence: {{column.layout.sequence}}
+        }
+        source {
+            type: databaseColumn
+            databaseColumn: {{column.source.databaseColumn}}
+            dataType: {{column.source.dataType}}
+            primaryKey: {{column.source.primaryKey}}
+        }
+    )
+    {{columns}}
+    {{linkAction}}
+)
+```
+
+# Conditional Rendering Rules
+
+- Omit optional settings rather than emitting unsupported or empty values.
+- Omit `settings.state`, its source projection, and its child column unless the user explicitly requests a semantic state.
+- Omit `orderBy` only when the source is guaranteed to return one row and ordering is irrelevant.
+- Emit `security.authorizationScheme` only when a verified scheme exists; do not invent an alias.
+- Emit the link action only when the destination and row-context mapping are resolved.
+- Mark one source column `primaryKey: true` when a row-level link or row identity requires it.
+
+The `{{#if settings.stateColumn}}` block is a conditional template fragment: render its contents only when semantic state is explicitly requested. It keeps the state mapping visible in the contract while omitting the setting when state is unspecified. Project that alias in the source and add its `varchar2` child column through `{{columns}}` when the fragment is rendered.
+
+# Security and Governance
+
+- Keep the page authenticated under the application baseline and use a verified region authorization scheme for narrower visibility.
+- Enforce authorization again on the target page and in protected data access; region hiding alone is insufficient.
+- Return raw data from SQL. Do not disable escaping or embed HTML to obtain Badge styling.
+- Keep labels static because the Badge label renderer is raw according to the template profile.
+- Allowlist state and icon tokens. Do not concatenate user-controlled strings into CSS classes or navigation URLs.
+- Validate every source object, projected column, target page, target item, and authorization alias before generation.
+
+# Validation Checklist
+
+- Region type is `themeTemplateComponent/badge` and display mode is `report`.
+- `settings.label` and `settings.value` are present.
+- `settings.label` is trusted static text; it does not contain a source-column or template substitution.
+- `settings.value` and optional `settings.state` use bare projected source-column aliases.
+- The value column uses only `varchar2`, `number`, `date`, `intervalYearToMonth`, or `intervalDayToSecond`.
+- Every projected field has an explicit child column with an exact compiler-supported data type.
+- Optional style, shape, and size values come from `badge._template_options.md`.
+- When state is requested, the mapped projected column is `varchar2` and its source contract guarantees exact lowercase `danger`, `warning`, `success`, or `info`; SQL literals and `CASE` expressions additionally require an explicit allowlisted `ELSE`.
+- When state is not requested, no state setting, state projection, or state child column is emitted.
+- Any assigned icon is selected from the pinned Font APEX catalogue and contains exactly one catalogue icon, at most one `fa` base class, and unique catalogue-listed modifiers.
+- Badge actions do not contain `targetUrl`, `linkAttributes`, or inline event handlers.
+- At most one action is present; it uses `position: link`, defines numeric `layout.sequence`, omits `template`, and has a resolved target.
+- Region and target authorization are independently enforced.
+- SQL contains raw values rather than HTML and does not contain `ORDER BY`.
+- No partial-component attachment or custom Badge template authoring was introduced.

package/skills/apexlang/templates/template-components/badge/badge._index.md

@@ -0,0 +1,20 @@
+---
+templateId: region.badge.index
+componentType: region
+version: 1.0
+imports:
+  - badge._common.md
+  - badge._template_options.md
+description: Routing entrypoint for standalone Badge template-component regions.
+---
+
+# Purpose
+
+Primary routing entrypoint for standalone report-mode `themeTemplateComponent/badge` regions.
+
+# Load Order
+
+1. Load this file.
+2. Load `badge._common.md`.
+3. Load `badge._template_options.md`.
+4. Load exactly one matching scenario file.

package/skills/apexlang/templates/template-components/badge/badge.report-link.md

@@ -0,0 +1,66 @@
+---
+templateId: badge.report-link
+componentType: templateComponent
+imports:
+  - badge._common.md
+version: 1.0
+description: Report-mode Badge with its single supported link action.
+---
+
+# Purpose
+
+Render a Badge whose row navigates to a resolved same-application target.
+
+# Output Template
+
+```apexlang
+region {{regionStaticId}} (
+    name: {{name}}
+    type: themeTemplateComponent/badge
+    componentAppearance {
+        display: report
+    }
+    source {
+        location: localDatabase
+        type: sqlQuery
+        sqlQuery: ```
+{{source.sqlQuery}}
+```
+    }
+    settings {
+        label: {{settings.label}}
+        value: {{settings.valueColumn}}
+    }
+    action {{actionId}} (
+        position: link
+        layout {
+            sequence: {{action.sequence}}
+        }
+        behavior {
+            type: redirectThisApp
+            target: {
+                page: {{targetPageId}}
+                items: {
+                    {{targetItem}}: &{{sourceKeyColumn}}.
+                }
+            }
+        }
+    )
+    {{columns}}
+)
+```
+
+# Conditional Rendering Rules
+
+- Use this scenario only when the target page, target item, and source key are resolved.
+- Omit `action.template`; Badge has no action templates.
+- Set a deterministic numeric `action.layout.sequence`; the live compiler requires it.
+- Add the complete verified source plus explicit column contract from `badge._common.md`.
+
+# Validation Checklist
+
+- Action position is exactly `link`.
+- Action includes numeric `layout.sequence`.
+- Target is a structured same-application target.
+- Source key is projected and marked as the row identity when required.
+- Target page applies the same or stricter authorization than the Badge visibility rule.

package/skills/apexlang/templates/template-components/badge/badge.report-minimal.md

@@ -0,0 +1,76 @@
+---
+templateId: badge.report-minimal
+componentType: templateComponent
+imports:
+  - badge._common.md
+version: 1.0
+description: Minimal informational report-mode Badge with explicit source columns.
+---
+
+# Purpose
+
+Render one or more informational Badges without navigation.
+
+# Output Template
+
+```apexlang
+region {{regionStaticId}} (
+    name: {{name}}
+    type: themeTemplateComponent/badge
+    componentAppearance {
+        display: report
+    }
+    source {
+        location: localDatabase
+        type: sqlQuery
+        sqlQuery: ```
+{{source.sqlQuery}}
+```
+    }
+    settings {
+        label: {{settings.label}}
+        value: {{settings.valueColumn}}
+        {{#if settings.stateColumn}}
+        state: {{settings.stateColumn}}
+        {{/if}}
+    }
+    column {{valueColumnId}} (
+        layout {
+            sequence: 10
+        }
+        source {
+            type: databaseColumn
+            databaseColumn: {{valueColumnName}}
+            dataType: varchar2
+            primaryKey: false
+        }
+    )
+    {{#if settings.stateColumn}}
+    column {{stateColumnId}} (
+        layout {
+            sequence: 20
+        }
+        source {
+            type: databaseColumn
+            databaseColumn: {{stateColumnName}}
+            dataType: varchar2
+            primaryKey: false
+        }
+    )
+    {{/if}}
+)
+```
+
+# Conditional Rendering Rules
+
+- Omit the state setting and state column when no semantic state is required.
+- The `{{#if settings.stateColumn}}` blocks are conditional template fragments: render their contents only when semantic state is explicitly requested. They retain the exact state setting and child-column contract while omitting both when state is unspecified.
+- Add one child column for every additional projected field.
+- Add top-level deterministic `orderBy` when multiple rows are returned.
+
+# Validation Checklist
+
+- Label and value are present.
+- Value/state mappings resolve to projected aliases.
+- No action is emitted.
+- State output is allowlisted when used.

package/skills/apexlang/templates/template-components/comments/README.md

@@ -0,0 +1,20 @@
+# Comments Templates
+
+Canonical Universal Theme Comments template-component guidance.
+
+## Usage
+
+- Load `comments._index.md` first.
+- Load `comments._common.md` for the shared generation contract.
+- Load `comments._template_options.md` only when Comments attributes or enum values are requested.
+- Choose the canonical SQL report or a single permutation branch after source mappings are proven.
+- Follow `references/domains/template-components/comments.md` for compiler authority and unsupported metadata.
+
+## Template Catalog
+
+- `comments._index.md`
+- `comments._common.md`
+- `comments._template_options.md`
+- `comments.apex-task-comments.md`
+- `comments.partial-column.md`
+- `comments.permutations.md`

package/skills/apexlang/templates/template-components/comments/comments._common.md

@@ -0,0 +1,43 @@
+---
+templateId: comments.common
+componentType: templateComponent
+version: 1.0
+description: Shared canonical contract for Comments template-component generation.
+---
+
+# Purpose
+
+Define the shared source, appearance, settings, nested-Avatar, optional report behavior, and column contract for Comments regions.
+
+# Generation Rules (MANDATORY)
+
+1. Use `type: themeTemplateComponent/comments` and `componentAppearance.display: partial` or `report`.
+2. Every Comments region must include `source`, `componentAppearance`, and `settings`.
+3. Map required `settings.userName` and `settings.commentText`, plus optional `settings.date`, directly to declared uppercase child-column identifiers. In report mode, use an accepted enum for required `settings.style`; omit `settings.style` in partial mode. `attributes`, `commentClass`, `alignment`, and `applyThemeColors` are optional.
+4. Keep explicit child `column (...)` declarations aligned with every projected report source column and its data type.
+5. Enable Avatar rendering only through `settings.displayAvatar`; keep the flag synchronized with `plugin-avatar` presence.
+6. When Avatar is enabled, emit `plugin-avatar.type` and `plugin-avatar.shape`, plus exactly one payload matching `icon`, `image`, or `initials`.
+7. Use a dedicated projected initials column, not the full user-name column. Do not treat the inventory's `sampleDataValue: INITIALS` as proof that `sampleData: tasks` exposes an `INITIALS` column; target-build runtime evidence rejects that identifier. For Tasks-backed initials, use a verified SQL projection such as `AVATAR_INITIALS` or omit the initials branch. URL-column images must use a declared varchar2 column containing only an application-managed static-file URL.
+8. Partial-mode Comments must use a source proven to return at most one row. For SQL sources, include an explicit `fetch first 1 row only` or equivalent `rownum` bound. Partial mode must omit `settings.style` and must not emit the report-only `rowSelection`, `performance`, `pagination`, `entityTitle`, `messages`, or `advanced` blocks. Report-mode Comments requires `settings.style` and may use those compiler-confirmed blocks. Omit `rowSelection` for the no-selection behavior; when selection is requested, use `focusOnly`, `singleSelection`, or `multipleSelection`.
+9. Comments supports compiler-proven actions at `actions`, `avatarLink`, and `userNameLink`. Use root `position`, `label` only for `actions`, a numeric `layout.sequence`, and a structured `behavior.target`; omit the stale `template` and `behavior.type` properties. A separate standalone Badge region is not a badge on each Comments row.
+10. Do not emit nested `plugin-badge` or `plugin-grouping` blocks. A direct APEX 26.1 probe rejects `plugin-grouping.groupTitle` and `plugin-grouping.groupIcon` as invalid application-source properties, so grouping is explicitly unsupported for generated APEXlang. A separate standalone Badge region is not a badge on each Comments row.
+11. Keep `settings.attributes` free of scriptable markup and event handlers. Keep `settings.commentClass` to static CSS tokens or a declared varchar2 source-column mapping; do not emit substitution-driven classes.
+12. Use `comments._template_options.md` as attribute inventory only. Compiler-backed APEXlang legality remains authoritative.
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| source | yes | block | Use a supported source mode with verified mappings. |
+| componentAppearance.display | yes | enum | `partial` or `report`. |
+| settings.userName | yes | column | Verified user-name column. |
+| settings.commentText | yes | column | Verified comment-text column. |
+| settings.style | report only | enum | Required for `report`; omit for `partial`. Values: `basic` or `chatSpeechBubbles`. |
+| settings.date | optional | column | Verified date or timestamp column. |
+| settings.displayAvatar | optional | boolean | Must agree with `plugin-avatar` presence. |
+| plugin-avatar | conditional | block | Required only when Avatar display is enabled. |
+| column | conditional | child component | Required for report projections and every referenced mapping. |
+
+# Authority Boundary
+
+The Universal Theme export includes grouping and action metadata that the current APEXlang compiler rejects. Follow the Comments workflow and target-build compiler validation for any structure not shown by the canonical fixtures.

package/skills/apexlang/templates/template-components/comments/comments._index.md

@@ -0,0 +1,25 @@
+---
+templateId: template-component.comments.index
+componentType: template-component
+version: 1.0
+imports:
+  - comments._common.md
+description: Routing entrypoint for Comments template-component regions.
+---
+
+# Purpose
+
+Select the narrowest supported Comments report or partial configuration.
+
+# Load Order
+
+1. Load `comments._common.md`.
+2. Load `comments.apex-task-comments.md` as the canonical report example.
+3. Load `comments.partial-column.md` when Comments is requested as an Interactive Report column.
+4. Load `comments.permutations.md` only when a conditional Avatar, chat, or partial region variant is requested.
+5. Load `comments._template_options.md` only when attribute or enum evidence is required.
+6. Load the shared Avatar inventory only when nested Avatar rendering is enabled.
+
+# Authority
+
+Use the Comments workflow for compiler-backed legality. Theme-export `REPORT` and `REPORT_GROUP` metadata is inventory evidence only.

package/skills/apexlang/templates/template-components/{comments._template_options.md → comments/comments._template_options.md}

@@ -3,8 +3,9 @@
 These entries come from `create_plugin_attribute` and `create_plugin_attr_value`, not from `wwv_flow_template_options`.
 
 Apply these values through the owning component's settings plus the shared avatar owner file when avatar rendering is enabled.
-Load `avatar._template_options.md` for the shared avatar substructure used by Comments.
+Load `../avatar/avatar._template_options.md` for the shared avatar substructure used by Comments.
 Emit only exact accepted values from this inventory. Do not concatenate adjacent values into one token and do not substitute labels or implementation details.
+Rows scoped to `REPORT` or `REPORT_GROUP` record Universal Theme export metadata only; they do not by themselves prove an APEXlang emission shape. Emit report rows only where the curated Comments contract and target compiler permit them, and do not emit `REPORT_GROUP` rows because the pinned compiler exposes no supported Comments grouping block.
 
 When a row includes `values=`, pass the left-hand side of each `name=>return_value` pair.
 

package/skills/apexlang/templates/template-components/comments/comments.apex-task-comments.md

@@ -0,0 +1,77 @@
+---
+templateId: comments.apex-task-comments
+componentType: region
+version: 1.0
+description: SQL-backed Comments example using the user-confirmed APEX_TASK_COMMENTS source.
+object_evidence_source: user_asserted
+---
+
+# Output Template
+
+```apexlang
+region comments (
+    name: Comments
+    type: themeTemplateComponent/comments
+    source {
+        location: localDatabase
+        type: sqlQuery
+        sqlQuery:
+            ```sql
+            select created_by as user_name,
+                   text as comment_text,
+                   created_on as comment_date
+              from apex_task_comments
+             order by created_on desc
+            ```
+    }
+    layout {
+        sequence: 10
+        slot: body
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    accessibility {
+        landmarkType: region
+    }
+    componentAppearance {
+        display: report
+    }
+    settings {
+        userName: USER_NAME
+        commentText: COMMENT_TEXT
+        date: COMMENT_DATE
+        style: basic
+    }
+    column USER_NAME (
+        layout {
+            sequence: 10
+        }
+        source {
+            databaseColumn: USER_NAME
+            dataType: varchar2
+        }
+    )
+    column COMMENT_TEXT (
+        layout {
+            sequence: 20
+        }
+        source {
+            databaseColumn: COMMENT_TEXT
+            dataType: varchar2
+        }
+    )
+    column COMMENT_DATE (
+        layout {
+            sequence: 30
+        }
+        source {
+            databaseColumn: COMMENT_DATE
+            dataType: date
+        }
+    )
+)
+```
+
+Use this source only with the confirmed `APEX_TASK_COMMENTS` object and columns. Add a nested Avatar only through one compiler-supported branch from `comments.permutations.md`. Grouping is unsupported. Add an action only at `actions`, `avatarLink`, or `userNameLink` using the compiler-proven action shape from the Comments workflow.

package/skills/apexlang/templates/template-components/comments/comments.partial-column.md

@@ -0,0 +1,120 @@
+---
+templateId: comments.partial-column
+componentType: column
+version: 1.0
+description: Partial Comments template component used as an Interactive Report column.
+---
+
+# Purpose
+
+Render one Comments entity per Interactive Report row. The column is the partial Comments context; it does not emit the region-only report blocks or `settings.style`.
+
+# Output Template
+
+```apexlang
+region comments_ir_column (
+    name: Comments Interactive Report Column
+    type: interactiveReport
+    source {
+        location: sampleData
+        sampleData: tasks
+    }
+    layout {
+        sequence: 10
+        slot: body
+    }
+    appearance {
+        template: @/interactive-report
+        templateOptions: #DEFAULT#
+    }
+    column ASSIGNED_TO_NAME (
+        type: plainText
+        heading {
+            heading: Author
+        }
+        layout {
+            sequence: 10
+        }
+        source {
+            dataType: STRING
+        }
+    )
+    column TASK_NAME (
+        type: plainText
+        heading {
+            heading: Comment
+        }
+        layout {
+            sequence: 20
+        }
+        source {
+            dataType: STRING
+        }
+    )
+    column COMMENTS (
+        type: themeTemplateComponent/comments
+        heading {
+            heading: Comments
+        }
+        layout {
+            sequence: 30
+        }
+        source {
+            dataType: STRING
+        }
+        settings {
+            userName: ASSIGNED_TO_NAME
+            commentText: TASK_NAME
+        }
+        action comments-column-action (
+            position: actions
+            label: Open comment
+            layout {
+                sequence: 40
+            }
+            behavior {
+                target: {
+                    page: 1
+                }
+            }
+        )
+        action comments-column-avatar-link (
+            position: avatarLink
+            layout {
+                sequence: 50
+            }
+            behavior {
+                target: {
+                    page: 1
+                }
+            }
+        )
+        action comments-column-user-link (
+            position: userNameLink
+            layout {
+                sequence: 60
+            }
+            behavior {
+                target: {
+                    page: 1
+                }
+            }
+        )
+    )
+)
+```
+
+# Conditional Rendering Rules
+
+- Keep `type: themeTemplateComponent/comments` on the `column COMMENTS` block.
+- Include `heading`, `layout.sequence`, `source.dataType`, and `settings.userName` / `settings.commentText` on the Comments column.
+- Actions may be attached to the column at `actions`, `avatarLink`, or `userNameLink`; use `layout.sequence` and structured `behavior.target`.
+- Declare every mapped value as a sibling Interactive Report column and keep its source datatype compatible with the mapping.
+- Treat the column as partial: omit `settings.style`, `componentAppearance`, `rowSelection`, pagination, performance, entity-title, messages, and advanced blocks.
+- Add `settings.date` only when a sibling date or timestamp column is projected. Avatar settings use the same display toggle and nested payload contract as a partial Comments region.
+
+# Validation Checklist
+
+- The enclosing Interactive Report source projects all mapped sibling columns.
+- The Comments column does not use `source.databaseColumn`, `source.sqlExpression`, or a report-only setting.
+- No guessed grouping or nested Badge structure is emitted.