pi-apexlang 0.2.2 → 0.4.0

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

@@ -0,0 +1,425 @@
+---
+templateId: comments.permutations
+componentType: region
+version: 1.0
+description: Supported Comments settings and nested Avatar permutations using the user-confirmed APEX_TASK_COMMENTS source.
+object_evidence_source: user_asserted
+---
+
+# Supported Permutations
+
+Use one branch per generated region. These examples include only compiler-proven selection and action structures; grouping remains unsupported.
+
+```apexlang
+region comments_basic_report (
+    name: Basic 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
+        attributes: Posted comment
+        commentClass: comment-entry
+        displayAvatar: false
+        style: basic
+        alignment: inbound
+        applyThemeColors: true
+    }
+    performance {
+        lazyLoading: false
+    }
+    pagination {
+        type: page
+        entitiesPerPage: 15
+        showTotalCount: false
+    }
+    entityTitle {
+        singular: Comment
+        plural: Comments
+    }
+    messages {
+        whenNoDataFound: No comments found.
+    }
+    advanced {
+        htmlDomId: comments-basic-report
+    }
+    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
+        }
+    )
+)
+
+region comments_chat_icon_avatar (
+    name: Chat Comments with Icon Avatar
+    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: 20
+        slot: body
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    accessibility {
+        landmarkType: region
+    }
+    componentAppearance {
+        display: report
+    }
+    settings {
+        userName: USER_NAME
+        commentText: COMMENT_TEXT
+        date: COMMENT_DATE
+        displayAvatar: true
+        style: chatSpeechBubbles
+        alignment: outbound
+        applyThemeColors: false
+    }
+    plugin-avatar {
+        type: icon
+        icon: fa-user
+        description: Comment author
+        shape: circular
+    }
+    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
+        }
+    )
+)
+
+region comments_image_avatar (
+    name: Comments with Image Avatar
+    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,
+                   :APP_FILES || 'icons/app-icon-512.png' as avatar_url
+              from apex_task_comments
+             order by created_on desc
+            ```
+    }
+    layout {
+        sequence: 30
+        slot: body
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    accessibility {
+        landmarkType: region
+    }
+    componentAppearance {
+        display: report
+    }
+    settings {
+        userName: USER_NAME
+        commentText: COMMENT_TEXT
+        date: COMMENT_DATE
+        displayAvatar: true
+        style: basic
+    }
+    plugin-avatar {
+        type: image
+        image: {
+            type: urlColumn
+            urlColumn: AVATAR_URL
+        }
+        description: Comment author image
+        shape: rounded
+    }
+    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
+        }
+    )
+    column AVATAR_URL (
+        layout {
+            sequence: 40
+        }
+        source {
+            databaseColumn: AVATAR_URL
+            dataType: varchar2
+        }
+    )
+)
+
+region comments_initials_avatar (
+    name: Comments with Initials Avatar
+    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,
+                   upper(
+                       substr(trim(created_by), 1, 1) ||
+                       case
+                           when instr(trim(created_by), ' ') > 0 then
+                               substr(trim(created_by), instr(trim(created_by), ' ', -1) + 1, 1)
+                       end
+                   ) as avatar_initials
+              from apex_task_comments
+             order by created_on desc
+            ```
+    }
+    layout {
+        sequence: 40
+        slot: body
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    accessibility {
+        landmarkType: region
+    }
+    componentAppearance {
+        display: report
+    }
+    settings {
+        userName: USER_NAME
+        commentText: COMMENT_TEXT
+        date: COMMENT_DATE
+        displayAvatar: true
+        style: chatSpeechBubbles
+    }
+    plugin-avatar {
+        type: initials
+        initials: AVATAR_INITIALS
+        description: Comment author initials
+        shape: noShape
+    }
+    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
+        }
+    )
+    column AVATAR_INITIALS (
+        layout {
+            sequence: 40
+        }
+        source {
+            databaseColumn: AVATAR_INITIALS
+            dataType: varchar2
+        }
+    )
+)
+
+region comments_partial_square_avatar (
+    name: Partial Comment with Square Avatar
+    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
+             fetch first 1 row only
+            ```
+    }
+    layout {
+        sequence: 50
+        slot: body
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    accessibility {
+        landmarkType: region
+    }
+    componentAppearance {
+        display: partial
+    }
+    settings {
+        userName: USER_NAME
+        commentText: COMMENT_TEXT
+        date: COMMENT_DATE
+        displayAvatar: true
+    }
+    plugin-avatar {
+        type: icon
+        icon: fa-user
+        description: Comment author
+        shape: square
+        cssClasses: avatar-comment-author
+    }
+    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
+        }
+    )
+)
+```
+
+# Boundaries
+
+- `APEX_TASK_COMMENTS(CREATED_BY, TEXT, CREATED_ON)` is user-asserted evidence for these fixtures.
+- The image branch uses an application-managed static-file URL and a declared varchar2 child column.
+- The initials branch derives the first and last author-name initials into a dedicated projected column rather than hardcoding a value or mapping `USER_NAME` directly.
+- Do not combine the icon, image, and initials payloads in one `plugin-avatar` block.
+- Do not add nested Badge or grouping structures from the Universal Theme export. Comments supports the optional nested `plugin-avatar` structure plus compiler-proven `actions`, `avatarLink`, and `userNameLink` actions using a structured `behavior.target`.
+- Keep `settings.attributes` free of executable markup, event handlers, URL schemes, and substitutions. Keep `settings.commentClass` to static CSS tokens or a direct declared `varchar2` Comments column.

package/skills/apexlang/templates/template-components/content-row/README.md

@@ -7,7 +7,7 @@ Canonical Content Row template pack for `themeTemplateComponent/contentRow`, usi
 - Load `content-row._common.md` first for variable contract and generation guardrails.
 - Use `content-row._index.md` to pick the correct scenario template.
 - Load `content-row._template_options.md` for Content Row-specific settings, appearance, and grouping values.
-- Load `../avatar._template_options.md` and `../badge._template_options.md` for the shared avatar and badge substructures.
+- Load `../avatar/avatar._template_options.md` and `../badge/badge._template_options.md` for the shared avatar and badge substructures.
 - Avatar-capable Content Row scenarios use `settings.displayAvatar` plus `plugin-avatar` fields for type, initials/description, shape, size, and CSS classes.
 - Badge-capable Content Row scenarios use `settings.displayBadge` plus `plugin-badge` fields for label, value, state, style, shape, size, icon, position, and width.
 - SQL-backed template component regions must emit top-level `orderBy {}` and must not embed `ORDER BY` inside `source.sqlQuery`.

package/skills/apexlang/templates/template-components/content-row/content-row._common.md

@@ -24,7 +24,7 @@ Define the shared variable contract, guardrails, and output skeleton for Content
 9. Use `plugin-badge.icon` only for badge icon configuration when the prompt explicitly requests an icon.
 10. Use `plugin-badge.position` only for badge placement configuration when the prompt explicitly requests a start/end placement override.
 11. Close component blocks declared with parentheses (for example `action ... (` or `column ... (`) using `)` after nested blocks.
-12. Keep plugin attribute names and enumerated values aligned with `content-row._template_options.md`, `../avatar._template_options.md`, and `../badge._template_options.md`.
+12. Keep plugin attribute names and enumerated values aligned with `content-row._template_options.md`, `../avatar/avatar._template_options.md`, and `../badge/badge._template_options.md`.
 13. Content Row display settings that map to query columns must use `&COLUMN_NAME.` substitution syntax, for example `title: &ORDER_LABEL.`. Do not emit bare column aliases such as `title: ORDER_LABEL` for `overline`, `title`, `description`, or `miscellaneous`.
 14. Native row selection uses `rowSelection` in report mode. Use `type: focusOnly` for focus behavior without persisted selection state, `type: singleSelection` with `currentSelectionPageItem` for one selected row, or `type: multipleSelection` with both `currentSelectionPageItem` and `selectAllPageItem` for multi-select. The current-selection item should normally be a same-page hidden item that stores selected row value(s); the select-all item should be a same-page checkbox. `rowSelection.currentSelectionPageItem` is native selection state only and does not satisfy master-detail drill-down or parent-child context setting.
 15. SQL-backed Content Row regions must use top-level `orderBy {}` for deterministic ordering. Do not put `ORDER BY` inside `source.sqlQuery`.

package/skills/apexlang/templates/template-components/content-row/content-row._index.md

@@ -18,7 +18,7 @@ Use as the routing index for Content Row templates. Select a scenario based on d
 - Use avatar, badge, links, primary actions, grouping, and appearance scenario files only when those features are explicitly requested.
 - Use `content-row.report-grouping-selection.md` when native Content Row focus-only, single-row, or multiple-row selection is requested; it documents `rowSelection.currentSelectionPageItem` and the same-page hidden item that stores native selected row state.
 - Use `content-row.report-master-detail-full-row-link.md` when a Content Row parent list filters or drives child detail regions. Native `rowSelection.currentSelectionPageItem` alone is not sufficient for parent-child context setting.
-- Use `content-row._template_options.md`, `../avatar._template_options.md`, and `../badge._template_options.md` when validating Content Row plugin attribute names or allowed values.
+- Use `content-row._template_options.md`, `../avatar/avatar._template_options.md`, and `../badge/badge._template_options.md` when validating Content Row plugin attribute names or allowed values.
 - For SQL-backed Content Row scenarios, keep the SQL unordered and emit the region-level `orderBy {}` block from `content-row._common.md`.
 
 ## Scenario Routing

package/skills/apexlang/templates/template-components/content-row/content-row._template_options.md

@@ -3,7 +3,7 @@
 These entries come from `create_plugin_attribute` and `create_plugin_attr_value`, not from `wwv_flow_template_options`.
 
 Apply these values through `settings`, `plugin-appearance`, and `plugin-grouping`.
-Load `../avatar._template_options.md` and `../badge._template_options.md` for the shared avatar and badge substructures used by Content Row.
+Load `../avatar/avatar._template_options.md` and `../badge/badge._template_options.md` for the shared avatar and badge substructures used by Content Row.
 Emit only exact accepted values from this inventory. Do not concatenate adjacent values into one token and do not substitute labels or implementation details.
 
 When a row includes `values=`, pass the left-hand side of each `name=>return_value` pair.

package/skills/apexlang/templates/template-components/flexbox-container/README.md

@@ -0,0 +1,9 @@
+# Flexbox Container Templates
+
+Option inventory for the Universal Theme Flexbox Container template component.
+
+## Usage
+
+- Load `flexbox-container._index.md` before using the inventory.
+- Load `flexbox-container._template_options.md` only when its attributes or enum values are requested.
+- Use the compiler-backed component contract for emitted structure; this directory contains no scenario fixture.

package/skills/apexlang/templates/template-components/flexbox-container/flexbox-container._index.md

@@ -0,0 +1,13 @@
+---
+templateId: template-component.flexbox-container.index
+componentType: template-component
+version: 1.0
+imports:
+  - flexbox-container._template_options.md
+description: Routing entrypoint for Flexbox Container template-component options.
+---
+
+# Load Order
+
+1. Load `flexbox-container._template_options.md` when validating Flexbox Container options.
+2. Load the selected component workflow and compiler contract for emitted structure.

package/skills/apexlang/templates/template-components/media-list/README.md

@@ -0,0 +1,100 @@
+# Media List Templates
+
+## Purpose
+
+Canonical generation pack for the Universal Theme `themeTemplateComponent/mediaList` component in partial and report modes.
+
+Natural requests such as `create a Media List template` select this direct component. Generic `create a list template` requests select the shared-list region. Explicit `List-region Media List template` or `Classic Report Media List template` requests retain their named host owner; adding the word `template` alone does not select a different owner. See `media-list._index.md` for scenario selection.
+
+## Supported Surface
+
+- Partial mode for one Media List item backed by literals or existing session-state values.
+- Report mode for verified `localDatabase/sqlQuery` sources only. Unsupported REST, JSON, property-graph, function-body, and sample-data requests stop with Missing Inputs until an adapter exists.
+- Required title plus optional description.
+- Optional Avatar using the shared initials, Font APEX icon, or application-managed URL-column image contracts.
+- Optional Badge using a static label, source-backed value, optional semantic state, and optional Font APEX icon.
+- One optional `link` action using a reviewed same-application target.
+- Native `2ColumnGrid`, `3ColumnGrid`, `4ColumnGrid`, `5ColumnGrid`, and `horizontalSpan` layouts, optional `large` sizing, and Universal Theme colors.
+- Deterministic top-level ordering, exact report projection coverage, region/action authorization, and native responsive behavior.
+- Native grouping is not supported by the current curated Media List policy. Enable it only after an authoritative policy refresh exposes a report-group block and exact accepted properties.
+
+## Report-Column Target-Build Gate and Curated Feature Policy
+
+Media List uses a composite contract with an explicit authority boundary:
+
+- The active compiler/grammar metadata resolves only the report-column declaration, required properties, blocks, and datatypes.
+- The curated Universal Theme component policy governs Media List settings, `plugin-avatar`, `plugin-badge`, actions, and grouping. These capabilities are not inferred from the report-column grammar.
+- Generated `component-contracts/<build>.json` records this boundary in `capability_provenance` so consumers can distinguish `compiler-runtime-metadata` from `curated-component-policy`.
+
+Before generating a report:
+
+1. Load the active `component-contracts/<build>.json` produced by runtime preflight/validation.
+2. Resolve `region.column` with the task-scoped grammar contract under `region.type=themeTemplateComponent/mediaList` and a concrete non-null report-source location such as `region.source.location=localDatabase`.
+3. Emit exactly the declaration and properties selected by that contract. Named and unnamed column variants are mutually exclusive.
+4. Emit settings, Avatar/Badge properties, actions, and grouping only when the selected curated policy exposes their exact names and values.
+5. Treat an optional policy capability that is absent as unsupported. Compiler column resolution alone cannot enable it.
+6. Stop with Missing Inputs when the report-column contract is unavailable or ambiguous, or when the applicable curated policy cannot be identified.
+7. Run the grammar/compiler conformance probe for the selected target build. A compiler default is not optionality: emit `source.type: databaseColumn` when the selected column contract marks it required, even when the compiler also records the `DB_COLUMN` default. Any real grammar-versus-requiredness mismatch blocks generation.
+
+For nested placement, resolve an existing parent region's exact template and slot from the target catalog. Standard and Content Block parents support `regionBody` and `subRegions`; use `regionBody` by default. Page-level placement remains `body`.
+
+Pass the generated contract to local validation with `--component-attributes component-contracts/<build>.json`; do not relabel the repository fallback schema as a target-build contract.
+
+The repository baseline was live-validated with named report columns. That result is evidence for that target, not a universal rule:
+
+```apexlang
+column MEDIA_TITLE (
+    layout {
+        sequence: 20
+    }
+    source {
+        type: databaseColumn
+        databaseColumn: MEDIA_TITLE
+        dataType: varchar2
+    }
+)
+```
+
+For a target that selects this named variant, the declaration identifier and `source.databaseColumn` must match the exact projected alias, and `source.primaryKey: true` is allowed only when exposed by the active contract. If another target selects an unnamed variant, use its required direct properties instead. Never mix variants.
+
+## Usage
+
+1. Load the active target-build report-column contract and the selected curated Media List component policy.
+2. Load `media-list._common.md`.
+3. Load `media-list._index.md`.
+4. Select the narrowest scenario matching the requested mode and feature set.
+5. Load `media-list._template_options.md` for Media List settings.
+6. Load `../avatar/avatar._template_options.md` or `../badge/badge._template_options.md` only when that nested feature is enabled.
+
+## Scenario Catalog
+
+- `media-list.partial.md`
+- `media-list.report-base.md`
+- `media-list.report-avatar-badge.md`
+- `media-list.report-link.md`
+- `media-list.report-grouped.md` (capability-gated)
+- `media-list.report-layouts.md`
+
+## Design-System and Accessibility Rules
+
+- Use native Universal Theme rendering, layouts, shapes, sizes, states, and colors. Do not recreate Media List with Classic Report HTML or custom CSS.
+- Keep the native region heading unless the owning page contract intentionally uses a hidden-heading template option with the correct landmark behavior.
+- Meaningful Avatars require an accessible description; decorative Avatars use the shared `AVATAR_PURPOSE_DECORATIVE` marker and omit the description.
+- Badge color is supplemental. Its value and optional displayed label must communicate meaning without relying on state color alone.
+- Native link actions remain keyboard accessible. Do not add `linkAttributes`, inline handlers, or custom focus behavior.
+- Prefer the default single-column flow in narrow containers. Select multi-column layouts only when the owning page provides sufficient width; reserve `horizontalSpan` for an explicitly wide, non-wrapping presentation.
+
+## Edge-Case Rules
+
+- Zero-row sources remain zero rows; do not manufacture placeholder SQL rows. Route an explicit empty-state requirement to a separately supported page/region pattern.
+- Null descriptions are supported by omitting the description mapping when the entire scenario does not need it. Do not create row-dependent DSL structure.
+- Long titles and descriptions rely on Universal Theme wrapping. Do not truncate semantically important content with custom CSS.
+- Omit Avatar, Badge, grouping, layout, size, colors, and actions when they were not requested or the selected curated policy does not expose them.
+- Keep exactly one action. If multiple interactions are required, route to a component family that exposes the required action positions.
+- Stop with Missing Inputs when a source, column, destination, authorization scheme, icon, state mapping, or dynamic accessible description cannot be proven.
+
+## Maintenance
+
+- Keep this README, `media-list._index.md`, `media-list._template_options.md`, and `../template-components.registry.json` synchronized.
+- Keep the curated component policy and theme-export option inventory aligned with `query-valid-props.mjs --template-component mediaList`. Keep only report-column structural decisions aligned with the active task-scoped `region.column` grammar contract.
+- Update validator rules and regression coverage whenever the supported Media List surface changes.