pi-apexlang 0.2.2 → 0.4.0

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

@@ -17,18 +17,23 @@ Document the native metric-card region emitted as `themeTemplateComponent/metric
 4. For dashboard KPI strips, default `appearance.template` to `@/blank-with-attributes` so the Metric Card renders without visible standard region chrome.
 5. Use `@/standard` for Metric Card only when the requested design explicitly needs a titled or landmarked visible region wrapper.
 6. Emit `advanced { htmlDomId: ... }` only when external client code, dynamic actions, or other page logic must target a known region DOM id.
-7. Keep `display: report` in `componentAppearance`.
-8. Use `column-metric-card` for source-column mappings.
-9. Keep plugin attribute names and enumerated values aligned with `metric-card._template_options.md`, `../avatar._template_options.md`, and `../badge._template_options.md`.
-10. In report mode, treat child `column (...)` metadata as part of the emitted Metric Card source contract, not as an optional compiler appeasement detail.
+7. Set `componentAppearance.display` to `report` for multi-row report output or `partial` for one component without the report wrapper.
+8. Use the compiler-resolved `column-f` production for source-column mappings.
+9. Keep all Metric Card settings and nested avatar/badge/grouping values aligned with `metric-card._template_options.md`; the standalone Avatar and Badge inventories do not define Metric Card's nested groups.
+10. In report mode, treat child `column (...)` metadata as part of the emitted Metric Card source contract, not as an optional compiler appeasement detail. In partial mode, omit report-only settings and blocks.
 11. Emit explicit child `column (...)` metadata for every delivered source projection before finals. Do not satisfy the compiler by adding only one placeholder column when the source projects multiple columns.
 12. A single Metric Card region can render multiple cards. When the prompt asks for several independent metrics in one region, prefer a multi-row SQL source that normalizes the projections for each card, commonly by `UNION ALL`-ing one row per metric into a shared column shape.
-13. Metric Card `settings`, `plugin-avatar`, `plugin-badge`, and `rowSelection` expose more value hooks than just `title` and `metric`. Use the accepted property surface from `metric-card._template_options.md`, `../avatar._template_options.md`, and `../badge._template_options.md` when those behaviors are needed.
-14. Do not require settings property names to match child-column names one-for-one. Those properties may bind to literals, `&COLUMN_NAME.` substitutions, or other accepted placeholders; the child `column (...)` blocks still describe the delivered source projection.
-15. Metric Card avatar support is export-backed in this runtime through `plugin-avatar {}`. Use `plugin-avatar.displayAvatar` for visibility and keep avatar configuration in that block.
-16. Metric Card badge support is export-backed in this runtime through `plugin-badge {}`. Use `plugin-badge.displayBadge` for visibility and keep badge configuration in that block.
+13. Metric Card `settings`, `plugin-avatar`, `plugin-badge`, and `rowSelection` expose more value hooks than just `title` and `metric`. Use the accepted property surface from `metric-card._template_options.md` when those behaviors are needed.
+14. Do not require settings property names to match child-column names one-for-one. Rendered `settings.title`, `settings.metric`, and `settings.meta` may bind to literals or `&COLUMN_NAME.` substitutions. Source-selector attributes use bare delivered aliases: `plugin-avatar.initials`, `plugin-badge.value`, `plugin-badge.state`, and a source-backed `plugin-badge.label` must not use `&COLUMN_NAME.`.
+15. Metric Card avatar support is export-backed in this runtime through `plugin-avatar {}`. Use `plugin-avatar.displayAvatar` for visibility, emit exactly one payload matching `plugin-avatar.type`, and keep Metric Card-specific position/alignment/style/shape/size configuration in that block.
+16. Metric Card badge support is export-backed in this runtime through `plugin-badge {}`. Use `plugin-badge.displayBadge` for visibility and require both `plugin-badge.label` and `plugin-badge.value` when the block is emitted.
 17. When `rowSelection` is emitted with any non-null mode, at least one child `column (...)` must mark the row identity with `source.primaryKey: true`.
 18. For every emitted child column, set `source.dataType` to one exact token from the Metric Card Column Data Types inventory below.
+19. Always emit `settings.metric`; it is required by the APEX 26.1 Metric Card contract.
+20. Query-column-backed `settings.title`, `settings.metric`, and `settings.meta` values use `&COLUMN_NAME.` substitution syntax. Literal text remains valid.
+21. Metric Card exposes only `action.position: link`. Emit no action template because the component has no action templates.
+22. Use declarative action targets. Do not emit arbitrary JavaScript URLs, inline handlers, or unreviewed external URLs.
+23. Rely on authenticated page security by default. Add a region or action authorization only when requirements identify a stricter existing scheme; never invent an authorization alias.
 
 # Variable Contract
 
@@ -39,43 +44,65 @@ Document the native metric-card region emitted as `themeTemplateComponent/metric
 | type | yes | enum | Always `themeTemplateComponent/metricCard`. |
 | appearance.template | yes | alias | Region template alias such as `@/standard` or `@/blank-with-attributes`. |
 | appearance.templateOptions | optional | array/string | Template modifiers. Default to `#DEFAULT#` unless the chosen region template documents another accepted value. |
+| componentAppearance.display | yes | enum | `partial` or `report`. Use `partial` for one component and `report` for multiple report rows. |
 | advanced.htmlDomId | optional | string | Use only when external page logic must target a known rendered DOM id for the metric-card region. |
 | settings.title | optional | string | Title binding or static text. |
 | settings.titleCssClasses | optional | string | Optional title CSS classes. May be literal or substitution-backed. |
-| settings.metric | optional | string | Metric binding or static text. |
+| settings.metric | yes | string | Required metric binding or static text. Query-column mappings use `&COLUMN_NAME.`. |
 | settings.metricCssClasses | optional | string | Optional metric CSS classes. May be literal or substitution-backed. |
 | settings.meta | optional | string | Optional meta text/value binding. |
 | settings.metaCssClasses | optional | string | Optional meta CSS classes. May be literal or substitution-backed. |
-| settings.layout | optional | enum | Layout token from `metric-card._template_options.md`, for example `2Columns`, `3Columns`, `stacked`, or `overflow`. |
-| settings.itemCssClasses | optional | string | Optional per-card/item CSS classes when report layout needs them. |
+| settings.layout | report-only | enum | Layout token from `metric-card._template_options.md`, for example `2Columns`, `3Columns`, `stacked`, or `overflow`. Omit in partial mode. |
+| settings.itemCssClasses | report-only | string | Optional per-card/item CSS classes. Omit in partial mode. |
 | source.sqlQuery | conditional | string | When one Metric Card region must render several cards, prefer a multi-row query with one normalized row per card. `UNION ALL` across per-metric SELECTs is the default pattern when the metrics originate from separate aggregates. |
+| orderBy.type | conditional | enum | Grouped output uses `staticValue`. |
+| orderBy.orderByClause | conditional | string | Required for grouped output and starts with every grouped child column in grouping order. |
 | plugin-avatar.displayAvatar | optional | boolean | Enables avatar rendering for the metric card. Emit inside `plugin-avatar`, not inside `settings`. |
 | plugin-avatar.type | conditional | enum | Avatar type when avatar rendering is enabled. Supported values include `image`, `initials`, and `icon`. |
-| plugin-avatar.icon | conditional | string | Avatar icon mapping/value when `type` is `icon`. |
-| plugin-avatar.initials | conditional | string | Avatar initials mapping/value when `type` is `initials`. |
+| plugin-avatar.icon | conditional | string | Static build-pinned Font APEX icon or `&COLUMN.` substitution backed by a proven `varchar2` literal/CASE allowlist when `type` is `icon`. |
+| plugin-avatar.initials | conditional | source-column identifier | Required when `type` is `initials`. Use a bare delivered `varchar2` alias, not `&COLUMN.` substitution syntax. |
 | plugin-avatar.image.type | conditional | enum | Image source type when `plugin-avatar.type` is `image`. Supported values include `blobColumn`, `url`, and `urlColumn` when the owning source delivers the needed image payload. |
 | plugin-avatar.image.blobColumn | conditional | string | Image blob column when `plugin-avatar.image.type` is `blobColumn`. |
 | plugin-avatar.image.filenameColumn | conditional | string | Filename companion column when a blob-column avatar image is used. |
 | plugin-avatar.image.mimeTypeColumn | conditional | string | MIME-type companion column when a blob-column avatar image is used. |
 | plugin-avatar.image.lastUpdatedColumn | conditional | string | Last-updated companion column when a blob-column avatar image is used. |
+| plugin-avatar.image.url | conditional | string | Static application-managed image path using `#APP_FILES#` or `#APEX_FILES#` when image type is `url`. |
+| plugin-avatar.image.urlColumn | conditional | string | Projected `varchar2` URL column built in SQL from `:APP_FILES` or `:APEX_FILES` plus one static relative path. |
+| plugin-avatar.position | conditional | enum | Avatar position: `inline` or `top`. |
+| plugin-avatar.alignment | conditional | enum | Inline avatar alignment: `start`, `center`, or `end`; omit for `position: top`. |
+| plugin-avatar.shape | optional | enum | Metric Card avatar shape: `circular`, `noShape`, `rounded`, or `square`. |
+| plugin-avatar.size | optional | enum | Metric Card avatar size: `small`, `medium`, or `large`. |
+| plugin-avatar.style | optional | enum | `subtle`, only when avatar type is `icon` or `initials`; omit for `image`. |
 | plugin-badge.displayBadge | optional | boolean | Enables badge rendering for the metric card. Emit inside `plugin-badge`, not inside `settings`. |
-| plugin-badge.label | conditional | string | Badge label/value hook when badge rendering is enabled. |
-| plugin-badge.value | conditional | string | Badge value hook when badge rendering is enabled. |
-| plugin-badge.state | optional | string | Badge state/value hook when badge rendering is enabled. |
-| plugin-badge.icon | optional | string | Badge icon when the design calls for one. |
-| plugin-badge.style | optional | enum | Badge style token from `badge._template_options.md`, for example `subtle` or `outline`. |
-| plugin-badge.shape | optional | enum | Badge shape token from `badge._template_options.md`, for example `circular`, `rounded`, or `square`. |
-| plugin-badge.size | optional | enum | Badge size token from `badge._template_options.md`, for example `small`, `medium`, or `large`. |
+| plugin-badge.label | conditional | string/source-column identifier | Required when badge rendering is enabled. Use a bare alias when source-backed. |
+| plugin-badge.value | conditional | source-column identifier | Required when badge rendering is enabled. Use a bare delivered alias. |
+| plugin-badge.state | optional | source-column identifier | Optional `varchar2` alias whose values are restricted to `danger`, `warning`, `success`, or `info`. |
+| plugin-badge.icon | optional | string | Static build-pinned Font APEX icon when the design calls for one. |
+| plugin-badge.style | optional | enum | Metric Card Badge style token from `metric-card._template_options.md`, for example `subtle` or `outline`. |
+| plugin-badge.shape | optional | enum | Metric Card Badge shape token from `metric-card._template_options.md`, for example `circular`, `rounded`, or `square`. |
+| plugin-badge.size | optional | enum | Metric Card Badge size token from `metric-card._template_options.md`, for example `small`, `medium`, or `large`. |
 | plugin-badge.displayLabel | optional | boolean | Optional label visibility toggle when the design needs it. |
+| plugin-grouping.groupTitle | optional | string | Group title for grouped report output. |
+| plugin-grouping.groupIcon | optional | string | Static build-pinned Font APEX icon; emit only when a group title is present. |
 | rowSelection.type | optional | enum | Optional row-selection mode when the Metric Card region participates in row-selection behavior. Use `focusOnly`, `singleSelection`, or `multipleSelection`. |
 | rowSelection.currentSelectionPageItem | conditional | string | Current-selection page item for row-selection modes that persist selection state. Omit it for `focusOnly`. |
 | rowSelection.selectAllPageItem | conditional | string | Select-all page item for `multipleSelection`. Omit it for `focusOnly` and `singleSelection`. |
+| messages.whenNoDataFound | report-only | string | Optional no-data message. Omit in partial mode. |
+| messages.noDataFoundIcon | report-only | icon | Optional static Font APEX no-data icon. Omit in partial mode. |
+| pagination.entitiesPerPage | report-only | number | Optional report page size. This is the only supported Metric Card pagination property. |
 | column.name | conditional | string | Required for each explicit child column emitted in report mode. |
 | column.layout.sequence | conditional | number | Required for each emitted child column. |
-| column.source.databaseColumn | conditional | string | Required for each emitted child column. |
-| column.source.dataType | conditional | enum | Required for each emitted child column. Use one exact value from Metric Card Column Data Types. |
-| column.source.primaryKey | optional | boolean | Emit `true` only on the identity column when row identity matters. |
+| column.source.databaseColumn | required | identifier | Required for each emitted child column. |
+| column.source.dataType | required | enum | Use one exact Metric Card value. |
+| column.source.primaryKey | optional | boolean | Emit `true` only for a row-identity column when row identity is needed. |
 | columns | conditional | list | Required in report mode. Generate one explicit child `column (...)` block for every delivered source projection. |
+| action.position | conditional | enum | Metric Card row link position. The only supported value is `link`. |
+| action.layout.sequence | conditional | number | Required deterministic action sequence. |
+| action.behavior.type | conditional | enum | Row-link behavior: `redirectThisApp`, `redirectOtherApp`, `redirectUrl`, or `triggerAction`. |
+| action.behavior.target | conditional | object | Required for declarative application-page targets. |
+| action.behavior.targetUrl | conditional | string | Required for `redirectUrl`; use a reviewed relative URL or an `http`, `https`, `mailto`, or `tel` URL without an unsafe scheme. Keep any substitutions inside query parameters so the scheme, host, path, and fragment remain static. |
+| action.behavior.linkAttributes | optional | string | Static link attributes without inline event handlers, URL-bearing attributes, scriptable CSS, or unsafe dynamic substitutions. |
+| security.authorizationScheme | optional | alias | Existing stricter region authorization. Omit when page authentication is sufficient. |
 
 # Metric Card Column Data Types
 
@@ -107,7 +134,11 @@ region {{regionStaticId}} (
     templateOptions: {{appearance.templateOptions}}
   }
   componentAppearance {
-    display: report
+    display: {{componentAppearance.display}}
+  }
+  orderBy {
+    type: {{orderBy.type}}
+    orderByClause: {{orderBy.orderByClause}}
   }
   advanced {
     htmlDomId: {{advanced.htmlDomId}}
@@ -128,6 +159,15 @@ region {{regionStaticId}} (
     icon: {{pluginAvatar.icon}}
     initials: {{pluginAvatar.initials}}
     image: {{pluginAvatar.image}}
+    position: {{pluginAvatar.position}}
+    alignment: {{pluginAvatar.alignment}}
+    shape: {{pluginAvatar.shape}}
+    size: {{pluginAvatar.size}}
+    style: {{pluginAvatar.style}}
+  }
+  plugin-grouping {
+    groupTitle: {{pluginGrouping.groupTitle}}
+    groupIcon: {{pluginGrouping.groupIcon}}
   }
   plugin-badge {
     displayBadge: {{pluginBadge.displayBadge}}
@@ -140,11 +180,33 @@ region {{regionStaticId}} (
     size: {{pluginBadge.size}}
     displayLabel: {{pluginBadge.displayLabel}}
   }
+  action {{action.staticId}} (
+    position: link
+    layout {
+      sequence: {{action.layout.sequence}}
+    }
+    behavior {
+      type: {{action.behavior.type}}
+      target: {{action.behavior.target}}
+      targetUrl: {{action.behavior.targetUrl}}
+      linkAttributes: {{action.behavior.linkAttributes}}
+    }
+    security {
+      authorizationScheme: {{action.security.authorizationScheme}}
+    }
+  )
   rowSelection {
     type: {{rowSelection.type}}
     currentSelectionPageItem: {{rowSelection.currentSelectionPageItem}}
     selectAllPageItem: {{rowSelection.selectAllPageItem}}
   }
+  messages {
+    whenNoDataFound: {{messages.whenNoDataFound}}
+    noDataFoundIcon: {{messages.noDataFoundIcon}}
+  }
+  pagination {
+    entitiesPerPage: {{pagination.entitiesPerPage}}
+  }
   column {{column.name}} (
     layout {
       sequence: {{column.layout.sequence}}
@@ -156,6 +218,9 @@ region {{regionStaticId}} (
     }
   )
   {{columns}}
+  security {
+    authorizationScheme: {{security.authorizationScheme}}
+  }
 )
 ```
 
@@ -166,11 +231,18 @@ region {{regionStaticId}} (
 - Use `appearance.template: @/standard` only when the design explicitly needs a titled or landmarked visible region wrapper.
 - Keep avatar or meta blocks only when the owning design requires them.
 - Keep metric-card-specific layout settings in the `settings` block.
+- In partial mode, omit `settings.layout`, `settings.itemCssClasses`, `plugin-grouping`, `rowSelection`, `messages`, and `pagination`; APEX 26.1 rejects those report-scoped properties in partial mode.
 - Metric Card `settings` may include title/metric/meta bindings plus their CSS-class companions, layout tokens, and item-level CSS classes from `metric-card._template_options.md`.
-- Metric Card settings/plugin value hooks do not need to have the same names as child columns. Bind them to literals, `&COLUMN_NAME.` substitutions, or other accepted placeholders as needed.
-- For Metric Card avatar rendering, use `plugin-avatar.displayAvatar` for visibility and keep avatar configuration in `plugin-avatar`.
-- For `plugin-avatar.type: image`, emit the nested `image: { ... }` object using the accepted source mode. The export-backed blob-column shape is `type: blobColumn` plus `blobColumn`, `filenameColumn`, `mimeTypeColumn`, and `lastUpdatedColumn`.
-- For Metric Card badge rendering, use `plugin-badge.displayBadge` for visibility and keep badge configuration in `plugin-badge`.
+- Bind query-backed `settings.title`, `settings.metric`, and `settings.meta` text to `&COLUMN_NAME.` substitutions.
+- Metric Card rendered-text settings do not need to have the same names as child columns. Bind `settings.title`, `settings.metric`, and `settings.meta` to literals or `&COLUMN_NAME.` substitutions as needed; use bare aliases for source-selector plugin attributes.
+- For Metric Card avatar rendering, use `plugin-avatar.displayAvatar` for visibility and keep avatar configuration in `plugin-avatar`. Emit exactly one of `icon`, `initials`, or `image` to match `type`.
+- Avatar icons may be static Font APEX literals or `&COLUMN.` substitutions. A source-backed icon column must be `varchar2`, and every SQL literal or CASE result must be provable against the pinned Font APEX catalogue.
+- Use a bare projected `varchar2` alias for `plugin-avatar.initials`. Use `alignment` only with `position: inline`.
+- Emit `plugin-avatar.style: subtle` only for `type: icon` or `type: initials`; omit `style` for `type: image`.
+- For `plugin-avatar.type: image`, emit the nested `image: { ... }` object using the accepted source mode. The export-backed blob-column shape is `type: blobColumn` plus typed `blobColumn`, `filenameColumn`, `mimeTypeColumn`, and `lastUpdatedColumn` aliases. URL-column images must be projected from `:APP_FILES` or `:APEX_FILES` plus one static relative path; static URL images use the matching `#APP_FILES#` or `#APEX_FILES#` path.
+- For Metric Card badge rendering, use `plugin-badge.displayBadge` for visibility and keep badge configuration in `plugin-badge`. Emit both `label` and `value`; source-backed label/value/state selectors use bare projected aliases.
+- Keep optional badge state values restricted to lowercase `danger`, `warning`, `success`, or `info`, matching the Badge contract introduced by the standalone Badge implementation.
+- Keep `plugin-grouping` only for grouped report output. Emit a static catalogue-listed Font APEX `groupIcon` only with `groupTitle`, mark the grouping child column with `appearance.group: true`, and place grouped columns first in deterministic ordering.
 - Omit `advanced { htmlDomId: ... }` unless external page logic must target a known rendered DOM id. Native runtime behavior can use the generated region id without requiring an explicit `htmlDomId`.
 - A Metric Card region may render multiple cards from multiple result rows.
 - When the page needs several independent metrics in one Metric Card region, prefer a normalized multi-row source with one row per card.
@@ -178,10 +250,17 @@ region {{regionStaticId}} (
 - Do not emit `settings.displayAvatar` for Metric Card; use `plugin-avatar.displayAvatar` instead.
 - Do not emit `settings.displayBadge` for Metric Card; use `plugin-badge.displayBadge` instead.
 - Use `rowSelection` only when the Metric Card region truly participates in row-selection behavior; otherwise omit it.
+- In report mode, `messages` may contain only `whenNoDataFound` and `noDataFoundIcon`, and `pagination` may contain only `entitiesPerPage`.
 - For `rowSelection.type: focusOnly`, emit only the `type` property and no selection page items.
 - For `rowSelection.type: singleSelection`, emit `currentSelectionPageItem` and omit `selectAllPageItem`.
 - For `rowSelection.type: multipleSelection`, emit both `currentSelectionPageItem` and `selectAllPageItem`.
 - When any `rowSelection` mode is used, keep one child column marked with `source.primaryKey: true`.
+- Emit an `action` only when navigation or a trigger action is requested. Use `position: link`, include deterministic `layout.sequence`, and omit `template` and `label` because this Metric Card position supplies neither action templates nor a label feature.
+- Pair `redirectThisApp`/`redirectOtherApp` with `target`, pair `redirectUrl` with a reviewed `targetUrl`, and emit neither target property for `triggerAction`.
+- Reject unsafe `targetUrl` values, including `javascript:`, `data:`, `vbscript:`, protocol-relative URLs, control characters, and wholly dynamic destinations that cannot be reviewed. Allow substitutions only inside query parameters; the scheme, host, path, and fragment must remain static. Use structured targets instead of same-app `f?p=` URLs.
+- Keep `linkAttributes` static and reject inline event handlers, URL-bearing attributes such as `href`, scriptable CSS, unsafe URL schemes, and `target="_blank"` without `rel="noopener"` or `rel="noreferrer"`.
+- For a same-app target, use a declarative `behavior.target` object and pass row values with escaped `&COLUMN.` substitutions only from projected columns.
+- Omit region/action `security` when page authentication is sufficient. When stricter AuthZ is required, reference an existing authorization scheme and apply it at the narrowest relevant scope.
 - In report mode, emit explicit child `column (...)` metadata for every delivered source projection before finals.
 - Do not stop after the first compiler-satisfying child column when the source projects multiple fields.
 - For child column `source.dataType`, emit only exact values from the Metric Card Column Data Types inventory; do not normalize them to uppercase SQL names or Interactive Report `STRING`/`NUMBER`/`DATE` tokens.
@@ -189,5 +268,19 @@ region {{regionStaticId}} (
 
 # Guardrails
 
-- Metadata export lookup: search for `Metric Card`, `themeTemplateComponent/metricCard`, and `column-metric-card`.
+- Metadata export lookup: search for `Metric Card` and `themeTemplateComponent/metricCard`; compiler truth resolves its child columns to `column-f`.
 - If the requested Metric Card behavior depends on external page logic targeting the region container directly, treat the chosen region template plus optional `advanced.htmlDomId` as part of the runtime contract, not as incidental styling.
+- Do not place presentation HTML in the Metric Card SQL source. Project raw values and render them through native settings and action attributes.
+- Do not expose sensitive metrics solely by hiding card markup. Enforce access through authenticated pages, verified authorization schemes, and source predicates where row-level filtering is required.
+
+# Validation Checklist
+
+- `type` is `themeTemplateComponent/metricCard` and `componentAppearance.display` is `partial` or `report`.
+- Partial mode omits every report-scoped setting and block; report mode may use layout, grouping, selection, messages, and `pagination.entitiesPerPage`.
+- `settings.metric` is present; query-backed title/metric/meta mappings use `&COLUMN.` syntax.
+- Every source projection has a matching child `column (...)` with a valid Metric Card data type.
+- Optional layout, grouping, and row-selection values use compiler-backed enums.
+- Optional avatar and badge blocks satisfy their type/payload dependencies, selector mappings, data types, and compiler-backed enums.
+- Badge label/value are present whenever `displayBadge: true`; optional state values use the Badge allowlist.
+- Optional row navigation uses only `action.position: link`, a declarative behavior, and no action template.
+- Page authentication is present; any stricter region/action authorization references an existing scheme.

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

@@ -4,6 +4,7 @@ componentType: region
 version: 1.0
 imports:
   - metric-card._common.md
+  - metric-card.report-minimal.md
 description: Routing entrypoint for metric-card regions.
 ---
 
@@ -15,3 +16,8 @@ Primary routing entrypoint for `metric-card` region templates.
 
 1. Load this file.
 2. Load `metric-card._common.md`.
+3. Use `metric-card.partial-minimal.md` for one component without the report wrapper; otherwise default to `metric-card.report-minimal.md`.
+4. Load `metric-card.report-avatar-badge.md` only when nested Avatar or Badge content is requested.
+5. Load `metric-card.report-link.md` only when row navigation is requested.
+6. Load `metric-card.report-grouping-selection.md` only when grouping or native row selection is requested.
+7. Load `metric-card.permutations.md` only for QA, regression, or exhaustive permutation requests.

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

@@ -2,10 +2,13 @@
 
 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 Metric Card.
+Apply these values through `settings`, `plugin-avatar`, `plugin-badge`, and `plugin-grouping`.
 Emit only exact accepted values from this inventory. Do not concatenate adjacent values into one token and do not substitute labels or implementation details.
 
+`layout`, `itemCssClasses`, `plugin-grouping`, `rowSelection`, `messages`, and `pagination` are report-only. Omit them when `componentAppearance.display: partial`.
+
+For source-backed selector fields, use bare delivered aliases: `plugin-avatar.initials`, `plugin-badge.value`, and `plugin-badge.state` must not use `&COLUMN.` substitutions. A source-backed badge label also uses its bare delivered alias.
+
 When a row includes `values=`, pass the left-hand side of each `name=>return_value` pair.
 
 ## Metric Card (`metricCard`)
@@ -21,3 +24,45 @@ Supported: `PARTIAL:REPORT`
 - `itemCssClasses` | prompt=`Item CSS Classes` | type=`TEXT` | scope=`REPORT` | required=`false` | default=`--` | group=`Advanced` | depends=`--`
 - `groupIcon` | prompt=`Group Icon` | type=`ICON` | scope=`REPORT_GROUP` | required=`false` | default=`--` | group=`Grouping` | depends=`groupTitle NOT_NULL`
 - `groupTitle` | prompt=`Group Title` | type=`TEXT` | scope=`REPORT_GROUP` | required=`false` | default=`--` | group=`Grouping` | depends=`--`
+
+## Metric Card Avatar (`plugin-avatar`)
+
+- `displayAvatar` | prompt=`Display Avatar` | type=`YES NO` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Avatar` | depends=`--`
+- `type` | prompt=`Type` | type=`SELECT LIST` | scope=`COMPONENT` | required=`true` | default=`icon` | group=`Avatar` | depends=`displayAvatar EQUALS true` | values=`icon=>icon, image=>image, initials=>initials`
+- `icon` | prompt=`Icon` | type=`ICON` | scope=`COMPONENT` | required=`true` | default=`fa-line-chart` | group=`Avatar` | depends=`type EQUALS icon`
+- `image` | prompt=`Image` | type=`MEDIA` | scope=`COMPONENT` | required=`true` | default=`--` | group=`Avatar` | depends=`type EQUALS image`
+- `initials` | prompt=`Initials` | type=`SESSION STATE VALUE` | scope=`COMPONENT` | required=`true` | default=`--` | group=`Avatar` | depends=`type EQUALS initials`
+- `position` | prompt=`Position` | type=`SELECT LIST` | scope=`COMPONENT` | required=`true` | default=`top` | group=`Avatar` | depends=`displayAvatar EQUALS true` | values=`inline=>t-MetricCard-body--avatarPositionInline, top=>t-MetricCard-body--avatarPositionTop`
+- `alignment` | prompt=`Alignment` | type=`SELECT LIST` | scope=`COMPONENT` | required=`true` | default=`start` | group=`Avatar` | depends=`position EQUALS inline` | values=`center=>t-MetricCard-body--avatarAlignmentCenter, end=>t-MetricCard-body--avatarAlignmentEnd, start=>t-MetricCard-body--avatarAlignmentStart`
+- `shape` | prompt=`Shape` | type=`SELECT LIST` | scope=`COMPONENT` | required=`true` | default=`rounded` | group=`Avatar` | depends=`displayAvatar EQUALS true` | values=`circular=>t-Avatar--circle, noShape=>t-Avatar--noShape, rounded=>t-Avatar--rounded, square=>t-Avatar--square`
+- `size` | prompt=`Size` | type=`SELECT LIST` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Avatar` | depends=`displayAvatar EQUALS true` | values=`large=>t-Avatar--lg, medium=>t-Avatar--md, small=>t-Avatar--sm`
+- `style` | prompt=`Style` | type=`SELECT LIST` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Avatar` | depends=`type IN_LIST initials,icon` | values=`subtle=>t-MetricCard-avatar--subtle`
+
+## Metric Card Badge (`plugin-badge`)
+
+- `displayBadge` | prompt=`Display Badge` | type=`YES NO` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Badge` | depends=`--`
+- `label` | prompt=`Label` | type=`TEXT` | scope=`COMPONENT` | required=`true` | default=`--` | group=`Badge` | depends=`displayBadge EQUALS true`
+- `value` | prompt=`Value` | type=`SESSION STATE VALUE` | scope=`COMPONENT` | required=`true` | default=`--` | group=`Badge` | depends=`displayBadge EQUALS true`
+- `state` | prompt=`State` | type=`SESSION STATE VALUE` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Badge` | depends=`displayBadge EQUALS true`
+- `icon` | prompt=`Icon` | type=`ICON` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Badge` | depends=`displayBadge EQUALS true`
+- `displayLabel` | prompt=`Display Label` | type=`YES NO` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Badge` | depends=`displayBadge EQUALS true`
+- `style` | prompt=`Style` | type=`SELECT LIST` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Badge` | depends=`displayBadge EQUALS true` | values=`outline=>t-Badge--outline, subtle=>t-Badge--subtle`
+- `shape` | prompt=`Shape` | type=`SELECT LIST` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Badge` | depends=`displayBadge EQUALS true` | values=`circular=>t-Badge--circle, rounded=>t-Badge--rounded, square=>t-Badge--square`
+- `size` | prompt=`Size` | type=`SELECT LIST` | scope=`COMPONENT` | required=`false` | default=`--` | group=`Badge` | depends=`displayBadge EQUALS true` | values=`large=>t-Badge--lg, medium=>t-Badge--md, small=>t-Badge--sm`
+
+## Metric Card Actions
+
+- Supported action position: `link`
+- Action templates: none
+- Do not emit `action.template` or `action.label` for the row link.
+- Supported behavior variants are `redirectThisApp`/`redirectOtherApp` with `target`, `redirectUrl` with a reviewed safe `targetUrl`, and `triggerAction` with neither target property. In `targetUrl`, substitutions are limited to query parameters so the scheme, host, path, and fragment remain static. Optional `linkAttributes` must be static and free of inline handlers, URL-bearing attributes, scriptable CSS, and unsafe URL schemes.
+
+## APEX 26.1 Report-only Standard Blocks
+
+These properties are live-compiler-backed standard report properties rather than `create_plugin_attribute` entries:
+
+- `messages.whenNoDataFound`
+- `messages.noDataFoundIcon`
+- `pagination.entitiesPerPage`
+
+Do not emit pagination `type` or `showTotalCount`; APEX 26.1 rejects them for Metric Card. All three properties above must be omitted in partial mode.

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

@@ -0,0 +1,51 @@
+---
+templateId: metric-card.partial-minimal
+componentType: templateComponent
+imports:
+  - metric-card.common
+version: 1.0
+description: Minimal partial-mode Metric Card without report-only attributes.
+---
+
+# Purpose
+
+Render one Metric Card component without the report wrapper.
+
+# Output Template
+
+```apx
+region {{regionStaticId}} (
+    name: {{name}}
+    type: themeTemplateComponent/metricCard
+    layout {
+        sequence: {{layout.sequence}}
+        slot: body
+    }
+    appearance {
+        template: @/blank-with-attributes
+        templateOptions: #DEFAULT#
+    }
+    componentAppearance {
+        display: partial
+    }
+    settings {
+        title: {{settings.title}}
+        metric: {{settings.metric}}
+        meta: {{settings.meta}}
+    }
+)
+```
+
+# Conditional Rendering Rules
+
+- Keep `settings.metric`; omit unused optional component-scope text and CSS-class properties.
+- Component-scope Avatar, Badge, and `action.position: link` remain available when their complete conditional contracts are satisfied.
+- Omit `settings.layout`, `settings.itemCssClasses`, `plugin-grouping`, `rowSelection`, `messages`, and `pagination`; they are report-only.
+- Do not add report child columns unless a proven partial-mode source mapping actually requires them.
+
+# Validation Checklist
+
+- `componentAppearance.display` is `partial`.
+- No report-only property or block is present.
+- Avatar style is omitted for image avatars.
+- Any action uses only `position: link` and one valid declarative behavior branch.

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

@@ -0,0 +1,56 @@
+---
+templateId: metric-card.permutations
+componentType: region
+version: 1.0
+description: APEX 26.1 Metric Card permutation and regression coverage matrix.
+---
+
+# Purpose
+
+Define the finite branch and enum coverage required for a Metric Card QA application. This is a coverage contract, not a requirement to generate the full Cartesian product. Use pairwise pages so every accepted token and conditional branch is exercised at least once without duplicating equivalent combinations.
+
+# Output Template
+
+Generate native `themeTemplateComponent/metricCard` regions from the canonical partial and report scenarios. Each generated region must select one valid value from every enabled axis below and must not combine mutually exclusive payloads.
+
+| Axis | Required coverage |
+| --- | --- |
+| Display | `partial`, `report` |
+| Root text | required `metric`; optional title/meta and all three CSS-class hooks |
+| Report layout | omitted/default, `2Columns`, `3Columns`, `4Columns`, `5Columns`, `autoWrapping`, `overflow`, `stacked` |
+| Report item classes | omitted and one safe static class list |
+| Avatar type | omitted, static `icon`, source-backed `icon` with a proven Font APEX CASE mapping, `initials`, image `url`, image `urlColumn`, image `blobColumn` |
+| Avatar image path | static `#APP_FILES#` and `#APEX_FILES#`; source-backed `:APP_FILES` and `:APEX_FILES`; complete BLOB companion-column mapping |
+| Avatar position/alignment | omitted/default; `top`; `inline` with `start`, `center`, and `end` |
+| Avatar shape | omitted/default, `circular`, `noShape`, `rounded`, `square` |
+| Avatar size | omitted/default, `small`, `medium`, `large` |
+| Avatar style | omitted; `subtle` with icon; `subtle` with initials; never with image |
+| Badge core | omitted; enabled with static label; enabled with source-backed varchar2 label |
+| Badge value type | `varchar2`, `number`, `date`, `intervalYearToMonth`, `intervalDayToSecond` |
+| Badge state | omitted, `danger`, `warning`, `success`, `info` |
+| Badge visuals | icon omitted/present; displayLabel false/true; style omitted/`outline`/`subtle`; shape omitted/`circular`/`rounded`/`square`; size omitted/`small`/`medium`/`large` |
+| Grouping | omitted; group title; group title plus icon, grouped column, and leading static order |
+| Row selection | omitted, `focusOnly`, `singleSelection`, `multipleSelection` with the required identity and page-item bindings |
+| Messages | omitted; `whenNoDataFound`; `whenNoDataFound` plus `noDataFoundIcon` |
+| Pagination | omitted; `entitiesPerPage`; never `type` or `showTotalCount` |
+| Ordering | omitted when unnecessary; `staticValue`; `item` with a valid same-page item |
+| Link action | omitted; `redirectThisApp`; `redirectOtherApp`; safe `redirectUrl`; `triggerAction`, always at `position: link` and without an action template; safe static `linkAttributes` and unsafe URL/inline-handler rejection cases |
+| Column type | every delivered report projection uses one exact supported Metric Card column data type |
+| Region policy | blank wrapper default, explicit standard wrapper case, optional accessibility, condition, authorization, comments, and DOM id only when justified |
+
+# Conditional Rendering Rules
+
+- Partial pages cover only component-scope text/CSS properties, Avatar, Badge, and link action branches. Omit every report-only setting and block.
+- Report pages cover layout, item classes, grouping, selection, messages, pagination, source ordering, and explicit source-column metadata.
+- Use one Avatar payload per region. Image modes are separate cases; BLOB mode includes all four typed companion aliases.
+- `plugin-avatar.style: subtle` is legal only for icon or initials.
+- Use pairwise visual combinations for Avatar and Badge. The matrix must cover every value, but it must not create redundant copies of the same semantic branch.
+- Treat the Badge state allowlist and image URL safety rules as source contracts, not presentation-only checks.
+- Use `SYS.DUAL` only in an explicit QA fixture with `object_evidence_source: user_asserted`; production generation requires target schema evidence.
+
+# Validation Checklist
+
+- Every value and omission branch in the matrix appears in at least one generated page and in a page inventory.
+- Every page passes strict formatting, local validation, compiler-truth audit, and target-build `apex validate`.
+- Negative regression checks reject report-only properties in partial mode, pagination `type`/`showTotalCount`, image Avatar style, invalid Avatar payload combinations, unsafe image URLs, invalid Badge states, and incomplete action/selection/grouping dependencies.
+- The application is check-only unless the user explicitly chooses import after live validation passes.

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

@@ -0,0 +1,98 @@
+---
+templateId: metric-card.report-avatar-badge
+componentType: templateComponent
+imports:
+  - metric-card.common
+  - metric-card.report-minimal
+version: 1.0
+description: Report-mode Metric Card with compiler-backed nested Avatar and Badge attributes.
+---
+
+# Purpose
+
+Add an Avatar, a Badge, or both to source-backed Metric Card rows without substituting the standalone Avatar or Badge region contracts.
+
+# Output Template
+
+```apx
+region {{regionStaticId}} (
+    type: themeTemplateComponent/metricCard
+    componentAppearance {
+        display: report
+    }
+    settings {
+        title: &{{settings.titleColumn}}.
+        metric: &{{settings.metricColumn}}.
+    }
+    plugin-avatar {
+        displayAvatar: true
+        type: initials
+        initials: {{avatar.initialsColumn}}
+        position: inline
+        alignment: center
+        shape: rounded
+        size: medium
+        style: subtle
+    }
+    plugin-badge {
+        displayBadge: true
+        label: {{badge.label}}
+        value: {{badge.valueColumn}}
+        state: {{badge.stateColumn}}
+        icon: {{badge.icon}}
+        displayLabel: true
+        style: subtle
+        shape: rounded
+        size: medium
+    }
+    column {{avatar.initialsColumn}} (
+        layout {
+            sequence: {{avatar.initialsColumnSequence}}
+        }
+        source {
+            databaseColumn: {{avatar.initialsColumn}}
+            dataType: varchar2
+        }
+    )
+    column {{badge.valueColumn}} (
+        layout {
+            sequence: {{badge.valueColumnSequence}}
+        }
+        source {
+            databaseColumn: {{badge.valueColumn}}
+            dataType: {{badge.valueColumnDataType}}
+        }
+    )
+    column {{badge.stateColumn}} (
+        layout {
+            sequence: {{badge.stateColumnSequence}}
+        }
+        source {
+            databaseColumn: {{badge.stateColumn}}
+            dataType: varchar2
+        }
+    )
+)
+```
+
+# Conditional Rendering Rules
+
+- Emit `plugin-avatar` only when avatar content is requested. Set `displayAvatar: true`, select exactly one `type`, and emit only its matching payload: `icon`, `initials`, or `image`.
+- `plugin-avatar.initials` is a bare projected `varchar2` alias. It is not an `&COLUMN.` rendered-text substitution.
+- Avatar image payloads use the compiler-backed media object. BLOB mode maps a `blob` payload, `varchar2` filename and MIME type columns, and a date/timestamp last-updated column. URL modes use application-managed file paths only.
+- Use `alignment` only for `position: inline`. Omit it for `position: top`.
+- Use `style: subtle` only for icon or initials avatars. Omit Avatar style for image avatars.
+- Emit `plugin-badge` only when badge content is requested. Set `displayBadge: true` and always emit both `label` and `value`.
+- A source-backed badge label, badge value, and badge state use bare projected aliases. Source-backed labels are `varchar2`; static labels contain no HTML or event attributes. Omit `state` and its child column when no semantic state is requested.
+- Badge state data is `varchar2` and is restricted to lowercase `danger`, `warning`, `success`, or `info` by the source contract introduced for Badge support.
+- Avatar and Badge icons use the build-pinned Font APEX catalogue and the shared icon validation introduced by their standalone component implementations. Metric Card Avatar icons may use a proven `&COLUMN.` substitution; Badge icons remain static.
+- Omit optional visual properties instead of emitting empty values. Use only the exact Metric Card values documented in `metric-card._template_options.md`.
+- Add one explicit child column for every additional source projection, including image payload and link-context columns.
+
+# Validation Checklist
+
+- Avatar visibility, type, payload, position, alignment, shape, size, and style satisfy the Metric Card compiler profile.
+- Initials, Badge value, and optional Badge state resolve to explicitly declared child columns with compatible data types.
+- Badge label and value are present; optional state values use the Badge allowlist.
+- Source-backed selector attributes use bare aliases rather than `&COLUMN.` substitutions.
+- No standalone Avatar/Badge settings or duplicated template-option inventories are mixed into the Metric Card groups.