pi-apexlang 0.2.2 → 0.4.0

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

@@ -0,0 +1,174 @@
+---
+templateId: region.media-list.common
+componentType: region
+version: 2.0
+description: Composite compiler-column and curated-policy contract for standalone Media List partial and report regions.
+---
+
+# Purpose
+
+Define `themeTemplateComponent/mediaList` using target-build-resolved report columns plus curated Universal Theme policy for settings, nested Avatar/Badge composition, interactions, grouping, responsive layouts, accessibility, security, and edge-case behavior.
+
+# Compiler and Theme Evidence
+
+- The Universal Theme export supplies an option inventory; it is not structural compiler evidence.
+- The export inventory supports `partial` and `report`, one `link` action position, and no action templates.
+- Resolve the active target build's task-scoped grammar contract before choosing report-column syntax.
+- Settings, Avatar/Badge properties, actions, and grouping come from the curated Media List component policy, not from compiler report-column grammar. The generated contract identifies each authority in `capability_provenance`.
+- The current compiler target resolves named report columns, while the current curated policy exposes no grouping/nested-size surface. A compiler change alone does not enable policy-owned features.
+- Media List settings and values: `media-list._template_options.md`.
+- Nested Avatar and Badge settings: `../avatar/avatar._template_options.md` and `../badge/badge._template_options.md`.
+
+# Capability Resolution Gate (MANDATORY)
+
+1. Load `component-contracts/<build>.json` for the selected runtime target. Use repository `assets/component-attributes.json` only as the documented fallback for its recorded build.
+2. Resolve `region.column` under `region.type=themeTemplateComponent/mediaList` and the report's concrete non-null `region.source.location` through the task-scoped grammar contract.
+3. Select exactly one resolved column variant. A named variant uses its declaration identifier and accepted source properties; an unnamed variant uses only its accepted direct/source properties. Never merge the two.
+4. Resolve settings, Avatar/Badge properties, actions, and grouping from the selected curated component policy. Theme-export rows are inventory evidence until incorporated into that policy.
+5. When grouping, nested size, or another policy-owned capability is requested but absent from the curated policy, stop with an unsupported-capability result. Do not infer it from compiler column metadata.
+6. When the report-column contract is missing or resolves multiple structural alternatives, or the applicable curated policy is unknown, stop with Missing Inputs.
+7. Run local validation against the generated composite `component-contracts/<build>.json`. Verify its `capability_provenance` before treating a capability as compiler-derived.
+
+# Generation Rules (MANDATORY)
+
+1. Emit `type: themeTemplateComponent/mediaList` and select exactly one `componentAppearance.display`: `partial` or `report`.
+2. Emit native page-region `layout {}` and `appearance {}` blocks. Top-level regions use `slot: body`; nested regions require a verified `parentRegion` and use `regionBody` by default (or explicitly supported `subRegions`) under an existing `@/standard` or `@/content-block` parent. Never create or infer a parent.
+3. Require `settings.title`. In report mode, map `title` and optional `description` with bare source aliases because their metadata type is `sessionStateValue`; do not use `&COLUMN_NAME.` syntax for these selectors.
+4. In report mode, require a verified data source and one compiler-resolved child column for every delivered projection. Emit exactly the declaration, required properties, blocks, and datatypes selected by the active grammar contract.
+5. For a named variant, keep the declaration identifier and accepted database-column mapping synchronized. For an unnamed variant, use the accepted column-name/visibility properties. Apply a primary-key or identity property only when the active column contract exposes it.
+6. For SQL-backed reports, keep `source.sqlQuery` free of `ORDER BY` and emit deterministic top-level `orderBy {}`. Use projected aliases only. The supported report adapter is `location: localDatabase` plus `type: sqlQuery`; unsupported source requests stop with Missing Inputs.
+7. Preserve the full compiler-supported source contract selected by the owning data-source workflow. Require authoritative evidence for every object and field before object-specific generation.
+8. Keep SQL and other sources data-only. Do not generate HTML, links, icons, Badge markup, or Avatar markup in source expressions.
+9. Enable Avatar with `settings.displayAvatar: true` and configure it in `plugin-avatar`. Omit both when Avatar is not requested.
+10. Enable Badge with `settings.displayBadge: true` and configure it in `plugin-badge`. Omit both when Badge is not requested.
+11. Apply the shared Avatar accessibility, URL, icon, and type/payload rules. Canonical Media List image generation is limited to the proven application-managed URL-column scenario; do not infer BLOB contracts.
+12. Apply the shared Badge static-label, value datatype, semantic-state, icon, and color-independent meaning rules.
+13. Emit grouping only in report mode and only when the curated component policy exposes a report-group block. Use its exact title/icon property names, require a safe title, and put a dynamic group-title alias first in ordering so groups remain contiguous.
+14. Emit at most one `action`, with `position: link`, numeric `layout.sequence`, and no `template`. Allow only a reviewed structured `redirectThisApp` target; reject `triggerAction` until validator-visible ownership by a dynamic action is available.
+15. Reject arbitrary URL navigation, `targetUrl`, `linkAttributes`, inline event handlers, invented focus behavior, and unresolved row-context mappings.
+16. Apply region authorization with an existing shared scheme when visibility is restricted. A navigation target or triggered behavior must enforce the same or stricter authorization independently.
+17. Keep native Universal Theme responsiveness. Omit `settings.layout` for the normal single-column flow; select a grid or horizontal layout only from the accepted inventory and only when the owning container width supports it.
+18. Omit `settings.applyThemeColors` to inherit its `true` default. Emit `false` only when the requested design intentionally disables Universal Theme row colors.
+19. Do not emit unsupported row selection, pagination, action templates, nested properties, custom structural CSS, or custom HTML rendering. Optional nested Avatar/Badge properties must be present in the curated Media List policy, not merely in their standalone owner contracts.
+20. Do not synthesize an empty row for a zero-row result. Route a required empty state to an independently supported page/region pattern.
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| `regionStaticId` | yes | identifier | Stable region identifier. |
+| `name` | yes | string | Useful visible heading/landmark name. |
+| `componentAppearance.display` | yes | enum | `partial` or `report`. |
+| `source` | report | block | Verified compiler-supported data source. |
+| `layout.parentRegion` | nested only | reference | Existing parent resolved by static ID or normalized reference. |
+| `layout.slot` | yes | enum | `body` at page level; `regionBody` by default or explicitly supported `subRegions` when nested. |
+| `orderBy` | SQL report | block | Deterministic static or item-controlled ordering. |
+| `settings.title` | yes | session-state selector | Bare report source alias or existing partial-mode session-state value. |
+| `settings.description` | no | session-state selector | Bare report source alias or existing partial-mode session-state value. |
+| `settings.displayAvatar` | no | boolean | `true` only when `plugin-avatar` is emitted. |
+| `settings.displayBadge` | no | boolean | `true` only when `plugin-badge` is emitted. |
+| `settings.applyThemeColors` | report-only | boolean | Omit for the native `true` default; emit `false` only by explicit design intent. |
+| `settings.layout` | report-only | enum | `2ColumnGrid`, `3ColumnGrid`, `4ColumnGrid`, `5ColumnGrid`, or `horizontalSpan`. |
+| `settings.size` | report-only | enum | `large`. |
+| `plugin-avatar` | conditional | block | Shared Avatar type/payload and only the nested properties exposed by the curated Media List policy. |
+| `plugin-badge` | conditional | block | Static label, source value, and only the nested properties exposed by the curated Media List policy. |
+| `plugin-grouping` | conditional capability | block | Report-only; exact title/icon properties come from the curated Media List policy. |
+| `action` | no | child component | At most one `link` action with sequence and a structured same-app redirect. |
+| `column variant` | report | compiler contract | Exact named or unnamed declaration selected for the active target. |
+| `column source alias` | report | source alias | Uppercase projected alias represented through the selected variant's mapping property. |
+| `column.layout.sequence` | report | number | Stable source-order sequence when required or allowed by the active column contract. |
+| `column.source.dataType` | report | enum | Exact target-build-supported datatype. |
+| `column identity` | conditional | compiler property | Apply only when the active variant exposes a primary-key/identity or visibility property. |
+| `security.authorizationScheme` | conditional | reference | Existing region authorization scheme. |
+
+# Output Template – Report Mode
+
+```apexlang
+region {{regionStaticId}} (
+    name: {{name}}
+    type: themeTemplateComponent/mediaList
+    source {
+        location: {{sourceLocation}}
+        type: sqlQuery
+        sqlQuery:
+            ```sql
+            {{source.sqlQuery}}
+            ```
+    }
+    orderBy {
+        type: staticValue
+        orderByClause: {{orderBy.orderByClause}}
+    }
+    layout {
+        {{parentRegionProperty}}
+        sequence: {{layout.sequence}}
+        slot: {{layout.slot}}
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    componentAppearance {
+        display: report
+    }
+    settings {
+        title: {{settings.titleColumn}}
+        {{descriptionProperty}}
+        {{displayAvatarProperty}}
+        {{displayBadgeProperty}}
+        {{applyThemeColorsProperty}}
+        {{layoutProperty}}
+        {{sizeProperty}}
+    }
+    {{pluginAvatarBlock}}
+    {{pluginBadgeBlock}}
+    {{policyApprovedGroupingBlock}}
+    {{securityBlock}}
+    {{compilerResolvedColumnBlocks}}
+    {{linkAction}}
+)
+```
+
+# Conditional Rendering Rules
+
+- In partial mode, omit report-only `source`, `orderBy`, child columns, layout, size, and theme-color settings unless a future curated policy explicitly enables them.
+- In report mode, require source coverage and include every projection once through the single active compiler-selected column shape.
+- Use bare aliases for `settings.title`, `settings.description`, `plugin-avatar.initials`, `plugin-avatar.image.urlColumn`, `plugin-badge.value`, and `plugin-badge.state` when they select report columns.
+- Use `&COLUMN_NAME.` only for free-text properties that support substitution, such as dynamic Avatar descriptions.
+- Emit exactly one Avatar type payload. Meaningful Avatars require a description; decorative Avatars omit it and add `AVATAR_PURPOSE_DECORATIVE` to region comments.
+- Omit Badge state unless semantic state was explicitly requested and proven to return exact lowercase `danger`, `warning`, `success`, or `info` values.
+- Omit grouping and optional nested properties unless requested and exposed by the selected curated policy.
+- Omit the action when items are informational. Never emit more than one action.
+- Omit optional layout/appearance attributes instead of serializing empty placeholders or guessed defaults.
+
+# Responsive and Accessibility Contract
+
+- The region name and native Standard region header provide the section heading and landmark context.
+- Default/no-layout output follows the native one-column Media List flow and is the safest narrow-container choice.
+- Use two or three columns for normal body widths. Use four or five only in verified wide containers. `horizontalSpan` intentionally keeps one horizontal row and therefore requires explicit wide-layout intent.
+- Do not solve wrapping, spacing, alignment, or visibility with invented CSS. Native Universal Theme handles item wrapping and focus indication.
+- Meaningful Avatar content has human-readable alternative text. Decorative Avatar content is hidden from assistive technology while text remains available.
+- Badge state color never carries the only meaning; retain a meaningful value and, when context requires it, `displayLabel: true` with a concise static label.
+- Native link behavior remains keyboard operable and gets its accessible name from the Media List item content. Do not replace it with an inline handler.
+
+# Security and Edge Cases
+
+- Keep output raw-data-only and declaratively rendered. Do not disable escaping or pass HTML through title, description, Badge, or icon fields.
+- Validate every source object, projected field, action target, target item, authorization alias, icon, and state mapping.
+- Treat null optional descriptions and badges as data concerns; do not generate conditional DSL structure per row.
+- Keep stable deterministic ordering for duplicate titles, normally by appending a verified identity alias as a tie-breaker.
+- For action context, project the key through the active Media List column variant, apply its supported identity/visibility property, and use it only in the structured target mapping.
+- If a dynamic Avatar description cannot be proven plain-text and meaningful, stop with Missing Inputs.
+
+# Validation Checklist
+
+- Region type and display mode are exact and supported.
+- Required title mapping exists and report mappings use bare aliases.
+- SQL has no embedded `ORDER BY`; top-level ordering references projected aliases.
+- Every report projection has one column using the exact declaration and mappings selected by the active target-build grammar contract.
+- Named and unnamed column variants are never mixed; identity/visibility properties are emitted only when exposed by the selected variant.
+- Avatar and Badge toggles match their plugin blocks and satisfy their owning contracts.
+- Layout, region size, nested size, shape, style, state, grouping, and icon values exist in both theme inventory and the selected curated component policy.
+- A requested policy-owned capability absent from the selected curated policy is reported as unsupported rather than inferred from compiler column metadata.
+- At most one `link` action exists; it has numeric sequence, no template, no unsafe URL/attributes, and verified authorization/row mappings.
+- Unsupported row selection, pagination, HTML rendering, BLOB Avatar, and structural CSS are absent.

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

@@ -0,0 +1,50 @@
+---
+templateId: region.media-list.index
+componentType: region
+version: 2.0
+imports:
+  - media-list._common.md
+description: Routing entrypoint for complete standalone Media List partial and report generation.
+---
+
+# Purpose
+
+Select the narrowest composite-contract Media List scenario without confusing the native template component with a shared-list region using `listTemplate: @/media-list`.
+
+`create a Media List template` selects this direct component, including case and hyphen variations. Explicit List-region or Classic Report wording selects that host owner instead. Generic `list template` wording without the Media List alias selects the shared-list region.
+
+# Load Order
+
+1. Load `media-list._common.md`.
+2. Load exactly one primary scenario.
+3. Add `media-list.report-avatar-badge.md` only when Avatar or Badge content is requested.
+4. Add `media-list.report-link.md` or `media-list.report-layouts.md` only for the corresponding explicit feature.
+5. Add `media-list.report-grouped.md` only after the selected curated component policy proves grouping support.
+6. Load the owning option inventories only for emitted attributes.
+
+# Scenario Routing
+
+- One non-report item: `media-list.partial.md`
+- Base multi-row report: `media-list.report-base.md`
+- Avatar and/or Badge rows: `media-list.report-avatar-badge.md`
+- Row navigation or verified trigger interaction: `media-list.report-link.md`
+- Native report grouping: `media-list.report-grouped.md`, only after its capability gate passes
+- Multi-column, horizontal, large, or theme-color variants: `media-list.report-layouts.md`
+
+# Composition Routing
+
+- Combine feature scenario fragments only with the shared block order in `media-list._common.md`.
+- Avatar visibility belongs in `settings.displayAvatar`; Avatar configuration belongs in `plugin-avatar`.
+- Badge visibility belongs in `settings.displayBadge`; Badge configuration belongs in `plugin-badge`.
+- Media List layout, size, and `applyThemeColors` belong in `settings` and are report-only.
+
+# Unsupported Routing
+
+- Do not route custom HTML rendering, custom CSS structure, arbitrary external URLs, multiple actions, action templates, row selection, pagination, or BLOB Avatar images to this pack.
+- Do not emit report grouping or nested properties merely because theme metadata advertises them; require the selected curated component policy. Require the active target-build grammar contract only for the report-column variant.
+- Use the exact Media List column declaration selected for the active target. Never mix named `source.databaseColumn` columns with unnamed `columnName`/`show` columns.
+- Route shared-list navigation to `region-components/list`, not this standalone data-backed component.
+
+# Authorization Routing
+
+When the owning page restricts visibility, require the exact existing shared authorization scheme. A navigable target must enforce the same or stricter access independently. Stop with Missing Inputs rather than guessing either contract.

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

@@ -2,10 +2,14 @@
 
 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 Media List.
+Apply component- and report-scope values through `settings`, Avatar values through `plugin-avatar`, and Badge values through `plugin-badge`. Treat this file as theme inventory only; emit a property only after it is represented in the selected curated Media List component policy.
+Load `../avatar/avatar._template_options.md` and `../badge/badge._template_options.md` for the shared substructures used by Media List.
 Emit only exact accepted values from this inventory. Do not concatenate adjacent values into one token and do not substitute labels or implementation details.
 
+`title`, `description`, `displayAvatar`, and `displayBadge` are valid in partial and report mode when accepted by the curated policy. `applyThemeColors`, `layout`, and `size` are report-only. Omit `applyThemeColors` to inherit its `true` default. Use the native default/no-layout flow for narrow containers; select a multi-column or horizontal layout only when the owning container width supports it. Emit nested Avatar/Badge `size` only if the curated Media List plugin block exposes it.
+
+Every nested Avatar/Badge icon must resolve to the build-pinned Font APEX index. In report mode, Media List `title`, `description`, Avatar initials/URL-column image, and Badge value/state use bare projected aliases. In partial mode, page-item-shaped selectors must name declared session-state items, and Badge state must be a proven allowlisted static value.
+
 When a row includes `values=`, pass the left-hand side of each `name=>return_value` pair.
 
 ## Media List (`mediaList`)
@@ -20,3 +24,5 @@ Supported: `PARTIAL:REPORT`
 - `size` | prompt=`Size` | type=`SELECT LIST` | scope=`REPORT` | required=`false` | default=`--` | group=`--` | depends=`--` | values=`large=>t-MediaList--large force-fa-lg`
 - `groupIcon` | prompt=`Icon` | type=`ICON` | scope=`REPORT_GROUP` | required=`false` | default=`--` | group=`Grouping` | depends=`groupTitle NOT_NULL`
 - `groupTitle` | prompt=`Title` | type=`HTML` | scope=`REPORT_GROUP` | required=`false` | default=`--` | group=`Grouping` | depends=`--`
+
+The two `REPORT_GROUP` rows above preserve the complete theme inventory. They become a generation surface only when the curated component policy exposes a compatible report-group block and exact property names.

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

@@ -0,0 +1,50 @@
+---
+templateId: region.media-list.partial
+componentType: region
+version: 1.0
+imports:
+  - media-list._common.md
+description: Single-item Media List partial using existing session-state values.
+---
+
+# Purpose
+
+Render one Media List item without report-only source, grouping, layout, or column metadata.
+
+# Output Template
+
+```apexlang
+region {{regionStaticId}} (
+    name: {{name}}
+    type: themeTemplateComponent/mediaList
+    layout {
+        {{parentRegionProperty}}
+        sequence: {{layout.sequence}}
+        slot: {{layout.slot}}
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    componentAppearance {
+        display: partial
+    }
+    settings {
+        title: {{titleSessionStateValue}}
+        {{descriptionProperty}}
+    }
+    {{securityBlock}}
+)
+```
+
+# Conditional Rendering Rules
+
+- Bind title and optional description only to literal values or existing session-state values selected by the owning partial-mode contract.
+- Omit `source`, `orderBy`, report columns, `plugin-grouping`, `applyThemeColors`, `layout`, and `size` settings.
+- Avatar, Badge, and link behavior may be added only through their shared conditional blocks when their values and authorization are resolved.
+
+# Validation Checklist
+
+- Display mode is exactly `partial`.
+- No report-only block or setting is present.
+- The title is nonempty and its session-state source exists when dynamic.

package/skills/apexlang/templates/template-components/media-list/media-list.report-avatar-badge.md

@@ -0,0 +1,76 @@
+---
+templateId: region.media-list.report-avatar-badge
+componentType: region
+version: 1.0
+imports:
+  - media-list._common.md
+description: Media List report with optional Avatar and Badge composition.
+---
+
+# Purpose
+
+Add native Avatar and/or Badge content without changing the base report source, ordering, appearance, or compiler-resolved column contract.
+
+# Output Template
+
+```apexlang
+settings {
+    title: {{titleColumn}}
+    {{descriptionProperty}}
+    {{displayAvatarProperty}}
+    {{displayBadgeProperty}}
+}
+
+{{#if displayAvatar}}
+plugin-avatar {
+    type: {{avatar.type}}
+    {{avatarPayload}}
+    {{avatarDescriptionProperty}}
+    shape: {{avatar.shape}}
+    {{avatarSizeProperty}}
+}
+{{/if}}
+
+{{#if displayBadge}}
+plugin-badge {
+    label: {{badge.label}}
+    value: {{badge.valueColumn}}
+    {{badgeStateProperty}}
+    {{badgeIconProperty}}
+    {{badgeDisplayLabelProperty}}
+    {{badgeStyleProperty}}
+    {{badgeShapeProperty}}
+    {{badgeSizeProperty}}
+}
+{{/if}}
+```
+
+# Avatar Variants
+
+- Initials: `type: initials` plus bare projected `initials: {{avatarInitialsColumn}}`.
+- Icon: `type: icon` plus one static allowlisted `icon: {{fontApexIcon}}`.
+- Image: `type: image` plus `image: { type: urlColumn urlColumn: {{avatarUrlColumn}} }`, where the projected URL is built only from `:APP_FILES` or `:APEX_FILES` and a static relative path.
+- Emit exactly one payload. Meaningful Avatars require a human-readable description; dynamic descriptions use `&{{avatarDescriptionColumn}}.` plus evidence in region comments. Decorative Avatars omit the description and use `AVATAR_PURPOSE_DECORATIVE`.
+
+# Badge Variants
+
+- Keep `label` concise, static, plain text, and meaningful because its metadata is raw-rendered.
+- Map `value` with a bare projected alias. Supported value datatypes are `varchar2`, `number`, `date`, `intervalYearToMonth`, and `intervalDayToSecond`.
+- Omit state by default. When explicitly requested, map a `varchar2` alias proven to return only `danger`, `warning`, `success`, or `info`.
+- Use `displayLabel: true` when the surrounding title/description does not already explain the Badge value. Color must never be the only state cue.
+- Icons are static Font APEX values; dynamic icon class strings are not supported.
+
+# Conditional Rendering Rules
+
+- `settings.displayAvatar: true` and `plugin-avatar` are emitted together or both omitted.
+- `settings.displayBadge: true` and `plugin-badge` are emitted together or both omitted.
+- Add one compiler-resolved Media List column for every Avatar/Badge mapping. Auxiliary Avatar URL/description and Badge state fields remain source mappings consumed only by their plugin properties.
+- Emit `plugin-avatar.size` or `plugin-badge.size` only when the selected curated Media List policy exposes that nested property and accepts the selected value; otherwise omit it.
+- Load and apply the shared Avatar and Badge owner contracts; do not copy their named child-column shape.
+
+# Validation Checklist
+
+- Toggle and plugin blocks are consistent.
+- Avatar type/payload, description, URL, and icon values satisfy the shared Avatar rules.
+- Badge label, value datatype, optional state, icon, and display semantics satisfy the shared Badge rules.
+- Every nested mapping resolves to a projected Media List column in the active compiler-selected shape.

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

@@ -0,0 +1,71 @@
+---
+templateId: region.media-list.report-base
+componentType: region
+version: 2.0
+imports:
+  - media-list._common.md
+description: Base standalone Media List report with title, optional description, deterministic ordering, and compiler-resolved report columns.
+---
+
+# Purpose
+
+Render a native multi-row Media List without Avatar, Badge, grouping, or interaction.
+
+# Output Template
+
+```apexlang
+region {{regionStaticId}} (
+    name: {{name}}
+    type: themeTemplateComponent/mediaList
+    source {
+        location: localDatabase
+        type: sqlQuery
+        sqlQuery:
+            ```sql
+            {{source.sqlQuery}}
+            ```
+    }
+    orderBy {
+        type: staticValue
+        orderByClause: {{orderBy.orderByClause}}
+    }
+    layout {
+        {{parentRegionProperty}}
+        sequence: {{layout.sequence}}
+        slot: {{layout.slot}}
+    }
+    appearance {
+        template: @/standard
+        templateOptions: #DEFAULT#
+    }
+    componentAppearance {
+        display: report
+    }
+    settings {
+        title: {{titleColumn}}
+        {{descriptionProperty}}
+    }
+    {{securityBlock}}
+    {{compilerResolvedIdentityColumnBlock}}
+    {{compilerResolvedTitleColumnBlock}}
+    {{compilerResolvedDescriptionColumnBlock}}
+    {{compilerResolvedRemainingColumnBlocks}}
+)
+```
+
+# Conditional Rendering Rules
+
+- `settings.title` uses the bare projected alias and the matching title column is `varchar2`.
+- When description is requested, set `descriptionProperty` to `description: {{descriptionColumn}}` and emit one matching `varchar2` column block.
+- Omit the description setting and column together when the report has no description field.
+- Keep the identity field source-backed and apply the active contract's identity/visibility property when one exists; it is an ordering/action-context tie-breaker, not a rendered template value.
+- Emit `source.type: databaseColumn` when the active target-build column contract marks the property required. A compiler default value does not permit omission by itself; stop only for a genuine grammar-versus-requiredness mismatch.
+- Add every remaining source projection once using the same compiler-resolved Media List column shape.
+- Keep deterministic ordering stable for duplicate titles by including a verified identity alias as the final tie-breaker.
+
+# Validation Checklist
+
+- Title and optional description aliases are explicitly projected and declared.
+- Every projected source field has one matching column using the active target-build declaration and required mappings.
+- No Avatar, Badge, grouping, or action block is emitted.
+- SQL contains raw data and no `ORDER BY` or presentation HTML.

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

@@ -0,0 +1,40 @@
+---
+templateId: region.media-list.report-grouped
+componentType: region
+version: 3.0
+imports:
+  - media-list._common.md
+description: Capability-gated native Media List report grouping.
+---
+
+# Purpose
+
+Generate native Media List report grouping only when the selected curated component policy exposes a validated report-group structure.
+
+# Capability Gate
+
+- Confirm `plugin-grouping` is an allowed Media List block from `curated-component-policy` in `component-contracts/<build>.json`.
+- Resolve the exact required/optional grouping property names from that policy; do not assume `groupTitle`, `title`, `groupIcon`, or `icon` across policy revisions.
+- Confirm the selected title property accepts the required dynamic/plain-text mapping and live validation recognizes the emitted block.
+- If any condition is unresolved, stop with an unsupported-capability result for the selected target. Do not synthesize grouping with HTML or CSS.
+
+# Output Template
+
+```apexlang
+{{policyApprovedGroupingBlock}}
+```
+
+# Conditional Rendering Rules
+
+- Use grouping only in report mode after the capability gate passes.
+- Dynamic title mappings must reference a projected `varchar2` alias using the exact substitution/property contract selected for the target.
+- Put the group-title alias first in deterministic static ordering so equal groups remain contiguous.
+- An optional group icon must use the policy's accepted icon property and one static allowlisted Font APEX icon.
+- Universal Theme supplies semantic group headings; do not place HTML in SQL or grouping values.
+
+# Validation Checklist
+
+- The curated component policy proves the grouping block and every emitted property.
+- Group rows remain contiguous because ordering starts with the grouping alias.
+- Group title data is safe plain text and the optional icon is static and allowlisted.
+- A target without grouping support produces `MEDIA_LIST_CAPABILITY_UNSUPPORTED_001` rather than compiler-invalid APEXlang.

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

@@ -0,0 +1,50 @@
+---
+templateId: region.media-list.report-layouts
+componentType: region
+version: 1.0
+imports:
+  - media-list._common.md
+description: Native Media List report layout, size, and theme-color choices.
+---
+
+# Purpose
+
+Apply curated Universal Theme presentation choices without custom CSS.
+
+# Output Template
+
+```apexlang
+settings {
+    title: {{titleColumn}}
+    {{descriptionProperty}}
+    {{layoutProperty}}
+    {{sizeProperty}}
+    {{applyThemeColorsProperty}}
+}
+```
+
+# Responsive Selection Matrix
+
+| Intent/container | Setting |
+|------------------|---------|
+| Narrow region or unspecified width | Omit `layout` for the native single-column flow. |
+| Normal body width with compact items | `layout: 2ColumnGrid` or `3ColumnGrid`. |
+| Verified wide body/dashboard lane | `layout: 4ColumnGrid` or `5ColumnGrid`. |
+| Explicit one-row, non-wrapping presentation in a wide container | `layout: horizontalSpan`. |
+| Explicitly larger item treatment | `size: large`. |
+| Native Avatar/Badge row colors | Omit `applyThemeColors` because its default is `true`. |
+| Explicit neutral row colors | `applyThemeColors: false`. |
+
+# Conditional Rendering Rules
+
+- Layout, size, and theme colors are report-only.
+- Emit exactly one layout token from the accepted inventory; never pass the underlying CSS return value.
+- Do not combine multiple grid layouts or add custom breakpoint classes.
+- Treat `horizontalSpan` as deliberate wide-layout intent because it keeps items in one horizontal row.
+- Use Universal Theme defaults for wrapping, spacing, and focus behavior.
+
+# Validation Checklist
+
+- Every emitted value exists in `media-list._template_options.md`.
+- The selected layout matches the verified owning container width.
+- No custom structural CSS is introduced.

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

@@ -0,0 +1,53 @@
+---
+templateId: region.media-list.report-link
+componentType: region
+version: 1.0
+imports:
+  - media-list._common.md
+description: Media List report with its single native link action.
+---
+
+# Purpose
+
+Make each Media List item navigable using the component's only action position.
+
+# Output Template
+
+```apexlang
+action {{actionId}} (
+    position: link
+    layout {
+        sequence: {{action.sequence}}
+    }
+    behavior {
+        type: redirectThisApp
+        target: {
+            page: {{targetPageId}}
+            items: {
+                {{targetItem}}: &{{sourceKeyColumn}}.
+            }
+        }
+    }
+    {{actionSecurityBlock}}
+)
+```
+
+# Interaction Contract
+
+- Use `redirectThisApp` and a structured target whose page, item, and row-key mapping all exist.
+- Do not emit `triggerAction`; the current validator cannot prove the required owning dynamic action.
+
+# Conditional Rendering Rules
+
+- Emit at most one action and keep `position: link`.
+- Always emit numeric `layout.sequence`; the live compiler requires it.
+- Omit `template`; Media List exposes no action templates.
+- Do not emit `targetUrl`, `linkAttributes`, external destinations, inline handlers, or custom keyboard/focus code.
+- Project the row key through the active compiler-selected column shape and apply its identity property when supported; the template renders only fields selected by its settings/plugin mappings.
+- Apply the same or stricter authorization at the target/trigger boundary; region visibility is not access control.
+
+# Validation Checklist
+
+- Action position, cardinality, sequence, and behavior are valid.
+- Target page/item and `&SOURCE_KEY.` mapping are resolved and authorized.
+- Native item content supplies an understandable accessible link name.

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

@@ -6,32 +6,47 @@ Canonical Metric Card template pack for `themeTemplateComponent/metricCard`, usi
 ## Usage
 - Load `metric-card._common.md` first for variable contract and generation guardrails.
 - Use `metric-card._index.md` to confirm the routing entrypoint and load order.
-- Metric Card regions always emit `type: themeTemplateComponent/metricCard` with `componentAppearance.display: report`.
+- Metric Card regions emit `type: themeTemplateComponent/metricCard` with `componentAppearance.display: partial` or `report`.
 - Metric Card regions should always emit a region `appearance {}` block.
 - Dashboard KPI strips default to `template: @/blank-with-attributes` so the Metric Card has no visible standard region chrome.
 - Use `template: @/standard` only when the design explicitly needs a titled or landmarked visible region wrapper.
 - Emit `advanced { htmlDomId: ... }` only when external page logic must target a known region DOM id; native runtime behavior does not require it.
-- Column source mappings use the `column-metric-card` child template.
+- Column source mappings use the compiler-resolved `column-f` child production.
 - Metric Card child columns support the documented `column.source.dataType` inventory in `metric-card._common.md`; emit those tokens exactly.
 - Report-mode Metric Card requires explicit child `column (...)` metadata for every delivered source projection. Do not satisfy the compiler minimum by adding only one column when the source projects more than one field.
+- Every emitted child column declares `source.databaseColumn` and `source.dataType`; emit `primaryKey: true` only for an identity column when row identity is needed.
 - Metric Card `settings` expose more than `title` and `metric`; use `meta`, the CSS-class hooks, and layout/item CSS properties from `metric-card._template_options.md` when the design needs them.
+- `layout` and `itemCssClasses` are report-only. Partial mode also omits grouping, row selection, messages, and pagination.
+- Metric Card `settings.metric` is required. Query-column-backed `title`, `metric`, and `meta` values use `&COLUMN_NAME.` substitution syntax.
 - Metric Card may also use `plugin-avatar`, `plugin-badge`, and `rowSelection` in accepted scenarios. Do not force those property names to mirror child-column names; they are value hooks, not a second column declaration system.
 - For Metric Card avatar rendering, use `plugin-avatar.displayAvatar` plus the typed avatar payload inside `plugin-avatar`.
+- Metric Card owns its nested avatar position/alignment/style/shape/size values; do not substitute the standalone Avatar region settings inventory.
+- Avatar `style: subtle` is accepted only for icon and initials types; image avatars omit style.
 - Do not emit `settings.displayAvatar` for Metric Card; use `plugin-avatar.displayAvatar` instead.
 - For Metric Card badge rendering, use `plugin-badge.displayBadge` plus badge fields inside `plugin-badge`.
+- When a Metric Card Badge is emitted, include both `label` and `value`; source-backed selector attributes use bare projected aliases and optional states follow the Badge allowlist.
 - Do not emit `settings.displayBadge` for Metric Card; use `plugin-badge.displayBadge` instead.
 - Metric Card `rowSelection` can also be focus-only. Use `focusOnly` with no page-item bindings, `singleSelection` with `currentSelectionPageItem`, or `multipleSelection` with both `currentSelectionPageItem` and `selectAllPageItem`.
+- Report mode supports no-data messages and `pagination.entitiesPerPage`; do not emit pagination `type` or `showTotalCount`.
 - When Metric Card uses any `rowSelection` mode, one child column must carry `source.primaryKey: true`.
+- Metric Card exposes one row-level action position, `link`. Use a declarative target and do not emit an action template because the component defines no action templates.
+- Keep the region authenticated through the page baseline. Add region/action authorization only when a stricter existing authorization scheme is required; never invent an authorization alias.
 - A single Metric Card region can render multiple cards from multiple source rows.
 - When one region must show several independent metrics, prefer a normalized multi-row SQL source. The default pattern is `UNION ALL` across one SELECT per metric so every row projects the same aliases in the same order.
 - Load `metric-card._template_options.md` for Metric Card-specific layout and grouping values.
-- Load `../avatar._template_options.md` for accepted Metric Card avatar value inventory.
-- Load `../badge._template_options.md` for accepted Metric Card badge value inventory.
+- Load `metric-card.report-avatar-badge.md` for nested Avatar/Badge permutations and `metric-card._template_options.md` for their Metric Card-specific values.
+- Load `metric-card.permutations.md` when generating a QA application that must cover every APEX 26.1 Metric Card branch and enum.
 
 ## Template Catalog
 - `metric-card._common.md`
 - `metric-card._index.md`
 - `metric-card._template_options.md`
+- `metric-card.partial-minimal.md`
+- `metric-card.report-minimal.md`
+- `metric-card.report-avatar-badge.md`
+- `metric-card.report-link.md`
+- `metric-card.report-grouping-selection.md`
+- `metric-card.permutations.md`
 
 ## Maintenance
 - Keep this README synchronized with actual files in this directory.