pi-apexlang 0.2.2 → 0.4.0

package/skills/apexlang/templates/template-components/metric-card/metric-card.report-grouping-selection.md

@@ -0,0 +1,131 @@
+---
+templateId: metric-card.report-grouping-selection
+componentType: templateComponent
+imports:
+  - metric-card.common
+  - metric-card.report-minimal
+version: 1.0
+description: Report-mode Metric Card with deterministic grouping and optional native row selection.
+---
+
+# Purpose
+
+Generate grouped Metric Cards or selection-enabled Metric Cards with stable row identity and correctly typed same-page items.
+
+# Grouped Output Template
+
+```apx
+region {{regionStaticId}} (
+    type: themeTemplateComponent/metricCard
+    orderBy {
+        type: staticValue
+        orderByClause: {{groupColumn}} asc, {{primaryKeyColumn}} asc
+    }
+    componentAppearance {
+        display: report
+    }
+    settings {
+        title: &{{settings.titleColumn}}.
+        metric: &{{settings.metricColumn}}.
+    }
+    plugin-grouping {
+        groupTitle: {{grouping.title}}
+        groupIcon: {{grouping.icon}}
+    }
+    column {{groupColumn}} (
+        layout {
+            sequence: 10
+        }
+        appearance {
+            group: true
+        }
+        source {
+            databaseColumn: {{groupColumn}}
+            dataType: varchar2
+        }
+    )
+)
+```
+
+# Selection Templates
+
+```apx
+rowSelection {
+    type: focusOnly
+}
+```
+
+```apx
+rowSelection {
+    type: singleSelection
+    currentSelectionPageItem: {{selection.currentItem}}
+}
+
+pageItem {{selection.currentItem}} (
+    type: hidden
+    layout {
+        sequence: {{selection.currentItemSequence}}
+        slot: regionBody
+    }
+    security {
+        sessionStateProtection: unrestricted
+    }
+    comments {
+        comments: Same-page dynamic-action ownership: native Metric Card selection updates this client-owned UI state after render, so checksum-based SSP would block the intended flow.
+    }
+)
+```
+
+```apx
+rowSelection {
+    type: multipleSelection
+    currentSelectionPageItem: {{selection.currentItem}}
+    selectAllPageItem: {{selection.selectAllItem}}
+}
+
+pageItem {{selection.currentItem}} (
+    type: hidden
+    layout {
+        sequence: {{selection.currentItemSequence}}
+        slot: regionBody
+    }
+    security {
+        sessionStateProtection: unrestricted
+    }
+    comments {
+        comments: Same-page dynamic-action ownership: native Metric Card selection updates this client-owned UI state after render, so checksum-based SSP would block the intended flow.
+    }
+)
+
+pageItem {{selection.selectAllItem}} (
+    type: checkbox
+    label {
+        label: Select All
+        alignment: left
+    }
+    help {
+        helpText: Select or clear all metric cards.
+    }
+    layout {
+        sequence: {{selection.selectAllItemSequence}}
+        region: @{{selection.toolbarRegion}}
+        slot: regionBody
+    }
+)
+```
+
+# Conditional Rendering Rules
+
+- Use grouping and selection only when requested; they are independent features.
+- Grouping requires at least one child column with `appearance.group: true` and top-level static ordering beginning with every grouped column in declaration order. The `plugin-grouping` block is optional when no custom group title/icon is needed.
+- `groupIcon` requires `groupTitle`.
+- Every selection mode requires a child column with `source.primaryKey: true`.
+- `focusOnly` emits no page-item bindings.
+- `singleSelection` uses a same-page hidden current-selection item with documented `sessionStateProtection: unrestricted` and no select-all item.
+- `multipleSelection` uses the same protected-by-classification hidden current-selection item plus a checkbox or switch select-all item.
+
+# Validation Checklist
+
+- Group columns lead deterministic ordering.
+- Selection item names resolve to page items of the required types.
+- Exactly one stable identity column is marked as the primary key for ordinary single-key sources.

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

@@ -0,0 +1,66 @@
+---
+templateId: metric-card.report-link
+componentType: templateComponent
+imports:
+  - metric-card.common
+  - metric-card.report-minimal
+version: 1.0
+description: Report-mode Metric Card with a declarative row link.
+---
+
+# Purpose
+
+Add compiler-backed row navigation to each Metric Card.
+
+# Output Template
+
+```apx
+region {{regionStaticId}} (
+    type: themeTemplateComponent/metricCard
+    componentAppearance {
+        display: report
+    }
+    settings {
+        title: &{{settings.titleColumn}}.
+        metric: &{{settings.metricColumn}}.
+    }
+    action open-details (
+        position: link
+        layout {
+            sequence: 10
+        }
+        behavior {
+            type: redirectThisApp
+            target: {
+                page: {{target.pageId}}
+                items: {
+                    {{target.itemName}}: &{{target.sourceKeyColumn}}.
+                }
+            }
+        }
+        security {
+            authorizationScheme: {{action.authorizationScheme}}
+        }
+    )
+)
+```
+
+# Conditional Rendering Rules
+
+- Use only `position: link`.
+- Omit `template` and `label`; Metric Card exposes no action templates and the link position does not request a label.
+- Include the source key in the query and child columns. Mark it as `source.primaryKey: true` when stable row identity is required.
+- Omit action security when page authentication is sufficient. Otherwise reference an existing authorization scheme.
+- Use a declarative target for same-app navigation. Do not build `f?p=` strings or inline JavaScript URLs.
+- Use `redirectOtherApp` with a declarative `target` for a different APEX application.
+- Use `redirectUrl` only with a reviewed safe `targetUrl`; omit `target`. Reject dangerous schemes, protocol-relative URLs, control characters, wholly dynamic destinations, and substitutions outside query parameters. Keep the scheme, host, path, and fragment static.
+- Optional `linkAttributes` must be static and must not contain inline event handlers, URL-bearing attributes, scriptable CSS, or unsafe URL schemes. A new-window target also requires `rel="noopener"` or `rel="noreferrer"`.
+- Use `triggerAction` only when a matching event consumer/dynamic action exists; omit both `target` and `targetUrl`.
+
+# Validation Checklist
+
+- Target page and item mappings are explicit.
+- Every `&COLUMN.` action mapping is projected by the source.
+- Action has deterministic layout sequence and declarative behavior.
+- Any `targetUrl` is reviewed and safe, with substitutions limited to query parameters; any `linkAttributes` are static and contain no inline handlers or URL override.
+- Authorization alias, when present, already exists in the target application.

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

@@ -0,0 +1,97 @@
+---
+templateId: metric-card.report-minimal
+componentType: templateComponent
+imports:
+  - metric-card.common
+version: 1.0
+description: Minimal report-mode Metric Card with source-backed title and metric values.
+---
+
+# Purpose
+
+Render one or more Metric Cards from a normalized report source using native title, metric, and meta attributes.
+
+# Output Template
+
+````apx
+region {{regionStaticId}} (
+    name: {{name}}
+    type: themeTemplateComponent/metricCard
+    source {
+        location: localDatabase
+        type: sqlQuery
+        sqlQuery:
+            ```sql
+            {{source.sqlQuery}}
+            ```
+    }
+    layout {
+        sequence: {{layout.sequence}}
+        slot: body
+    }
+    appearance {
+        template: @/blank-with-attributes
+        templateOptions: #DEFAULT#
+    }
+    componentAppearance {
+        display: report
+    }
+    settings {
+        title: &{{settings.titleColumn}}.
+        metric: &{{settings.metricColumn}}.
+        meta: &{{settings.metaColumn}}.
+        layout: {{settings.layout}}
+    }
+    column {{settings.titleColumn}} (
+        layout {
+            sequence: 10
+        }
+        appearance {
+            group: false
+        }
+        source {
+            databaseColumn: {{settings.titleColumn}}
+            dataType: varchar2
+        }
+    )
+    column {{settings.metricColumn}} (
+        layout {
+            sequence: 20
+        }
+        appearance {
+            group: false
+        }
+        source {
+            databaseColumn: {{settings.metricColumn}}
+            dataType: {{metricColumn.dataType}}
+        }
+    )
+    column {{settings.metaColumn}} (
+        layout {
+            sequence: 30
+        }
+        appearance {
+            group: false
+        }
+        source {
+            databaseColumn: {{settings.metaColumn}}
+            dataType: varchar2
+        }
+    )
+)
+````
+
+# Conditional Rendering Rules
+
+- `settings.metric` is required.
+- Omit `settings.title`, `settings.meta`, and their columns when the design does not need them.
+- Use `&COLUMN.` substitution for query-backed title, metric, and meta text.
+- Use one source row per card. Normalize independent metrics into the same aliases, typically with `UNION ALL`.
+- Replace the SQL metavariable only after every referenced database object and column has authoritative evidence. A literal `dual` smoke test is valid only for explicit test fixtures.
+
+# Validation Checklist
+
+- Every projected alias has a child column.
+- Metric data type matches the delivered projection.
+- Layout uses a supported Metric Card layout token.
+- SQL returns raw values and contains no presentation HTML.

package/skills/apexlang/templates/template-components/template-components.registry.json

@@ -4,19 +4,36 @@
     {
       "slug": "actions",
       "kind": "helper",
+      "readme": "actions/README.md",
       "index": "actions/actions._index.md",
       "common": "actions/actions._common.md",
+      "files": ["actions/actions._template_options.md"],
       "scenarios": [
         "actions/actions.inline-button.md",
         "actions/actions.menu-trigger.md",
         "actions/actions.nested-group.md"
       ]
     },
+    {
+      "slug": "avatar",
+      "kind": "template-component",
+      "readme": "avatar/README.md",
+      "index": "avatar/avatar._index.md",
+      "common": "avatar/avatar._common.md",
+      "files": ["avatar/avatar._template_options.md"],
+      "scenarios": [
+        "avatar/avatar.report-initials.md",
+        "avatar/avatar.report-icon.md",
+        "avatar/avatar.report-image-url-column.md"
+      ]
+    },
     {
       "slug": "button",
       "kind": "helper",
+      "readme": "button/README.md",
       "index": "button/button._index.md",
       "common": "button/button._common.md",
+      "files": ["button/button._template_options.md"],
       "scenarios": [
         "button/button.navigation.md",
         "button/button.hot-icon.md",
@@ -26,8 +43,10 @@
     {
       "slug": "content-row",
       "kind": "template-component",
+      "readme": "content-row/README.md",
       "index": "content-row/content-row._index.md",
       "common": "content-row/content-row._common.md",
+      "files": ["content-row/content-row._template_options.md"],
       "scenarios": [
         "content-row/content-row.partial-minimal.md",
         "content-row/content-row.partial-rich-content.md",
@@ -43,8 +62,78 @@
     {
       "slug": "metric-card",
       "kind": "template-component",
+      "readme": "metric-card/README.md",
       "index": "metric-card/metric-card._index.md",
-      "common": "metric-card/metric-card._common.md"
+      "common": "metric-card/metric-card._common.md",
+      "files": ["metric-card/metric-card._template_options.md"],
+      "scenarios": [
+        "metric-card/metric-card.partial-minimal.md",
+        "metric-card/metric-card.report-minimal.md",
+        "metric-card/metric-card.report-avatar-badge.md",
+        "metric-card/metric-card.report-link.md",
+        "metric-card/metric-card.report-grouping-selection.md",
+        "metric-card/metric-card.permutations.md"
+      ]
+    },
+    {
+      "slug": "badge",
+      "kind": "template-component",
+      "readme": "badge/README.md",
+      "index": "badge/badge._index.md",
+      "common": "badge/badge._common.md",
+      "files": ["badge/badge._template_options.md"],
+      "scenarios": [
+        "badge/badge.report-minimal.md",
+        "badge/badge.report-link.md"
+      ]
+    },
+    {
+      "slug": "comments",
+      "kind": "template-component",
+      "readme": "comments/README.md",
+      "index": "comments/comments._index.md",
+      "common": "comments/comments._common.md",
+      "files": ["comments/comments._template_options.md"],
+      "scenarios": [
+        "comments/comments.apex-task-comments.md",
+        "comments/comments.partial-column.md",
+        "comments/comments.permutations.md"
+      ]
+    },
+    {
+      "slug": "flexbox-container",
+      "kind": "template-component",
+      "readme": "flexbox-container/README.md",
+      "index": "flexbox-container/flexbox-container._index.md",
+      "files": ["flexbox-container/flexbox-container._template_options.md"]
+    },
+    {
+      "slug": "media-list",
+      "kind": "template-component",
+      "readme": "media-list/README.md",
+      "index": "media-list/media-list._index.md",
+      "common": "media-list/media-list._common.md",
+      "files": ["media-list/media-list._template_options.md"],
+      "scenarios": [
+        "media-list/media-list.partial.md",
+        "media-list/media-list.report-base.md",
+        "media-list/media-list.report-avatar-badge.md",
+        "media-list/media-list.report-link.md",
+        "media-list/media-list.report-grouped.md",
+        "media-list/media-list.report-layouts.md"
+      ]
+    },
+    {
+      "slug": "timeline",
+      "kind": "template-component",
+      "readme": "timeline/README.md",
+      "index": "timeline/timeline._index.md",
+      "common": "timeline/timeline._common.md",
+      "files": [
+        "timeline/timeline._template_options.md",
+        "timeline/timeline.report-sample-data.md",
+        "timeline/timeline.permutations.md"
+      ]
     }
   ]
 }

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

@@ -0,0 +1,19 @@
+# Timeline Templates
+
+Canonical Universal Theme Timeline template-component guidance.
+
+## Usage
+
+- Load `timeline._index.md` first.
+- Load `timeline._common.md` for the shared generation contract.
+- Load `timeline._template_options.md` only when validating Timeline attributes or enum values.
+- Choose the report sample or a single permutation branch after the source mappings are proven.
+- Follow `references/domains/template-components/timeline.md` for compiler authority and unsupported metadata.
+
+## Template Catalog
+
+- `timeline._index.md`
+- `timeline._common.md`
+- `timeline._template_options.md`
+- `timeline.report-sample-data.md`
+- `timeline.permutations.md`

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

@@ -0,0 +1,43 @@
+---
+templateId: timeline.common
+componentType: templateComponent
+version: 1.0
+description: Shared canonical contract for Timeline template-component generation.
+---
+
+# Purpose
+
+Define the shared source, appearance, settings, nested-component, and column contract for Timeline regions.
+
+# Generation Rules (MANDATORY)
+
+1. Use `type: themeTemplateComponent/timeline` and `componentAppearance.display: partial` or `report`.
+2. Every Timeline region must include `source`, `componentAppearance`, and `settings`.
+3. Map the required `settings.userName`, `settings.date`, and `settings.title` values to verified source columns. `settings.description` is optional.
+4. Keep explicit child `column (...)` declarations aligned with every projected report source column and its data type.
+5. Enable Avatar and Badge rendering only through `settings.displayAvatar` and `settings.displayBadge`; keep each flag synchronized with its nested block.
+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. URL-column images must use a declared varchar2 column containing only an application-managed static-file URL.
+8. When Badge is enabled, emit `plugin-badge.label` and `plugin-badge.value`; optional state, icon, display, style, and shape values must come from the family-local inventories.
+9. Do not emit report-level `applyThemeColors`, `style`, grouping, pagination type/count, messages, or actions until a target-build compiler contract proves those structures.
+10. Use `timeline._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.date | yes | column | Verified event date or date-range column. |
+| settings.title | yes | column | Verified event title column. |
+| settings.description | optional | column | Verified description column. |
+| settings.displayAvatar | optional | boolean | Must agree with `plugin-avatar` presence. |
+| settings.displayBadge | optional | boolean | Must agree with `plugin-badge` presence. |
+| plugin-avatar | conditional | block | Required only when Avatar display is enabled. |
+| plugin-badge | conditional | block | Required only when Badge display is enabled. |
+| column | conditional | child component | Required for report projections and every referenced mapping. |
+
+# Authority Boundary
+
+The Universal Theme export includes metadata that the current APEXlang compiler rejects. Follow the Timeline workflow and target-build compiler validation for any structure not shown by the canonical fixtures.

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

@@ -0,0 +1,24 @@
+---
+templateId: region.timeline.index
+componentType: region
+version: 1.0
+imports:
+  - timeline._common.md
+  - timeline._template_options.md
+description: Routing entrypoint for Timeline template-component regions.
+---
+
+# Purpose
+
+Select the narrowest supported Timeline report or partial configuration.
+
+# Load Order
+
+1. Load `timeline._common.md`.
+2. Load `timeline._template_options.md` when attribute or enum evidence is required.
+3. Load exactly one matching example: `timeline.report-sample-data.md` for the canonical report shape or `timeline.permutations.md` for conditional branches.
+4. Load the shared Avatar or Badge inventory only when the requested nested component is enabled.
+
+# Authority
+
+Use the Timeline workflow for compiler-backed legality. Theme-export `REPORT` and `REPORT_GROUP` metadata is inventory evidence only.

package/skills/apexlang/templates/template-components/{timeline._template_options.md → timeline/timeline._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 and badge owner files when those substructures are enabled.
-Load `avatar._template_options.md` and `badge._template_options.md` for the shared substructures used by Timeline.
+Load `../avatar/avatar._template_options.md` and `../badge/badge._template_options.md` for the shared substructures used by Timeline.
 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 prove an APEXlang emission shape. The current Timeline compiler contract rejects root report attributes and exposes no supported grouping block, so follow the Timeline workflow and do not emit those rows.
 
 When a row includes `values=`, pass the left-hand side of each `name=>return_value` pair.