pi-apexlang 0.2.2 → 0.4.0

package/skills/apexlang/templates/region-components/cards/cards._common.md

@@ -15,8 +15,15 @@ Standardize the output shape, variable contracts, metadata lookup anchors, and g
 2. Keep cards metadata lookup anchored on region type `Cards` and the `column-card` child template.
 3. When cards display images, use the native cards `media` block with exactly one source-specific value mapping: `blobColumn`, `urlColumn`, or `imageUrl`.
 4. Emit `blobAttributes` only when `media.source: blobColumn` is selected; use it only for supported companion metadata column aliases.
-5. Emit media presentation properties only for meaningful non-default values: `position: first | background`, `appearance: square | widescreen`, and `sizing: cover`.
-6. When cards need row navigation, emit native Cards `action` blocks with `label`, `layout.sequence`, and declarative `behavior.target`; native Cards actions must not emit `position`.
+5. Direct-source media must emit `advancedFormatting: false`, `position: first | body | background`, and `sizing: fit | cover`; `appearance: square | widescreen` is optional.
+6. When cards need row navigation, emit an action `type`, `layout.sequence`, `behavior.type`, and its matching target. Only `type: button` emits a `label` and `layout.position: primary | secondary`. Keep each action's sequence explicit so full-card and decision-button ordering is deterministic.
+7. Before rendering, freeze a source-to-attribute plan for title, subtitle, body, secondary body, row identity, icon, image, badge, link, and conditional style. Each requested role must resolve to an SQL projection alias or authoritative REST data-profile column.
+8. Emit `componentAppearance.layout: grid`, `float`, or `horizontal` from explicit layout intent. Emit `gridColumns` only with `layout: grid` for an explicit `2`, `3`, `4`, or `5` column requirement, and use `cssClasses` only for a proven container class.
+9. When Cards need dynamic refresh, name the trigger and Cards region static ID, use the supported dynamic-action Refresh capability, and submit every page item read by the refreshed source.
+10. Do not generate Faceted Search, Smart Filters, search items, facets, filter blocks, or filter orchestration as part of the visual-summary Cards pattern.
+11. Apply the authenticated-page baseline, use an existing region authorization scheme when Cards data is more restricted than the page, escape every untrusted advanced-formatting substitution with `!HTML`, and authorize every navigation target independently.
+12. For REST-backed Cards, reference a declared shared REST Data Source, HTTPS REST Data Source Server, and Web Credential; never emit credentials or literal endpoints in the Cards region, and require `advanced.validForUrls` to contain the exact resolved server plus source-path prefix.
+13. Emit exactly one complete Cards source shape. SQL requires `location: localDatabase`, `type: sqlQuery`, and `sqlQuery`; REST requires `location: restSource` and `restSource: @alias` with no SQL source properties.
 
 # Variable Contract
 
@@ -28,40 +35,80 @@ Standardize the output shape, variable contracts, metadata lookup anchors, and g
 | layout.sequence | yes | number | Region order. |
 | layout.slot | yes | enum | Page slot. |
 | appearance.templateOptions | optional | array | Use the accepted values from `cards._template_options.md`, such as `style-a`, `style-b`, or `style-c`. Do not substitute emitted CSS class strings. |
-| componentAppearance.gridColumns | optional | enum | Forces a 2-, 3-, 4-, or 5-column cards grid. Emit only when the prompt explicitly specifies a grid column count; otherwise omit the entire `componentAppearance` block. |
+| componentAppearance.layout | yes | enum | Use explicit `grid`, `float`, or `horizontal` intent; `gridColumns` applies only to `grid`. |
+| componentAppearance.gridColumns | optional | enum | Forces a 2-, 3-, 4-, or 5-column cards grid. Omit only this property for automatic responsive sizing. |
+| componentAppearance.cssClasses | optional | array | Classes applied to the Cards container. Use only for a proven class requirement; prefer native layout and template options. |
 | card.primaryKeyColumn1 | optional | string | Primary-key column used in the card block; maps to the native cards `primaryKeyColumn1` property. |
+| card.primaryKeyColumn2 | optional | string | Second primary-key column when the source has a composite identity; requires `card.primaryKeyColumn1`. |
+| card.cssClasses | optional | array | Conditional per-row card classes. Reference exactly one source-projected alias proven to return only `u-normal`, `u-hot`, `u-info`, `u-success`, `u-warning`, `u-danger`, or `NULL`. |
+| security.authorizationScheme | optional | reference | Existing shared authorization scheme required when Cards data is more restricted than the page. Never invent the alias. |
 | title.column | conditional | string | Primary card title column when the title uses direct column rendering instead of `htmlExpression`. |
-| title.advancedFormatting | conditional | boolean | Required and must be `true` when `title.htmlExpression` is emitted. Omit it when `title.column` is used. |
+| title.advancedFormatting | yes | boolean | Use `false` with `column`; use `true` with `htmlExpression`. |
 | subtitle.column | conditional | string | Secondary label column when the subtitle uses direct column rendering instead of `htmlExpression`. |
-| subtitle.advancedFormatting | conditional | boolean | Required and must be `true` when `subtitle.htmlExpression` is emitted. Omit it when `subtitle.column` is used. |
-| body.advancedFormatting | conditional | boolean | Required and must be `true` when `body.htmlExpression` is emitted. Omit it when `body.column` is used. |
-| iconAndBadge.iconSource | optional | string | Selects the icon mode: `iconClass`, `iconClassColumn`, or `initials`. |
+| subtitle.advancedFormatting | conditional | boolean | Required when subtitle is emitted: `false` with `column`, `true` with `htmlExpression`. |
+| body.advancedFormatting | conditional | boolean | Required when body is emitted: `false` with `column`, `true` with `htmlExpression`. |
+| iconAndBadge.iconSource | optional | string | `iconClass`, `iconClassColumn`, `initials`, `imageUrl`, or `imageBlobColumn`. |
 | iconAndBadge.iconColumn | optional | string | Required when `iconSource` is `iconClassColumn` or `initials`; points to the SQL column that supplies the value. |
 | iconAndBadge.iconCssClasses | optional | string | Optional CSS classes for the icon item. When `iconSource` is `iconClass`, this value is required and must include a Font APEX icon class prefixed with `fa `. |
+| iconAndBadge.imageColumn | conditional | string | Required for `iconSource: imageBlobColumn`. |
+| iconAndBadge.imageUrl | conditional | string | Required for `iconSource: imageUrl`. |
+| iconAndBadge.iconPosition | conditional | enum | Required whenever `iconSource` is set: `top`, `start`, or `end`. |
 | iconAndBadge.iconDescription | optional | string | Brief description of the icon item. |
 | iconAndBadge.badgeColumn | optional | string | Required when badge mode is used; points to the SQL column that supplies the badge metric or status. |
 | iconAndBadge.badgeLabel | optional | string | Optional label shown with the badge. |
-| iconAndBadge.badgeCssClasses | optional | string | Optional CSS classes that augment the badge. |
+| iconAndBadge.badgeCssClasses | optional | array | Optional CSS classes that augment the badge. |
 | title | yes | object | Column-based or htmlExpression title. Emit either `column` or `htmlExpression`, not both. When using `htmlExpression`, emit `advancedFormatting: true`. |
 | subtitle | optional | object | Column-based or htmlExpression subtitle. Emit either `column` or `htmlExpression`, not both. When using `htmlExpression`, emit `advancedFormatting: true`. |
 | body | optional | object | Column-based or htmlExpression body. Emit either `column` or `htmlExpression`, not both. When using `htmlExpression`, emit `advancedFormatting: true`. |
-| secondaryBody.advancedFormatting | conditional | boolean | Required and must be `true` when `secondaryBody.htmlExpression` is emitted. Omit it when `secondaryBody.column` is used. |
+| secondaryBody.advancedFormatting | conditional | boolean | Required when secondary body is emitted: `false` with `column`, `true` with `htmlExpression`. |
 | secondaryBody | optional | object | Supplemental content. Emit either `column` or `htmlExpression`, not both. When using `htmlExpression`, emit `advancedFormatting: true`. |
 | media.source | conditional | enum | Use `blobColumn`, `urlColumn`, or `imageUrl` according to the image source. |
 | media.blobColumn | conditional | string | Required only when `media.source: blobColumn`; SQL projection alias for the raw BLOB image column. |
 | media.urlColumn | conditional | string | Required only when `media.source: urlColumn`; SQL projection alias containing image URLs. |
-| media.url | conditional | string | Required only when `media.source: imageUrl`; static image URL or APEX substitution such as `&IMAGE_URL_COLUMN.`. |
-| media.position | optional | enum | Non-default media position: `first` or `background`. |
+| media.url | conditional | string | Required only when `media.source: imageUrl`; use an application-static relative URL or an evidenced, allowlisted HTTPS source. Reject active-content and protocol-relative schemes. |
+| media.advancedFormatting | conditional | boolean | Required when media is emitted; use `false` for native image sources. |
+| media.position | conditional | enum | Required when media is emitted: `first`, `body`, or `background`. |
 | media.appearance | optional | enum | Non-default media appearance: `square` or `widescreen`. |
-| media.sizing | optional | enum | Non-default media sizing: `cover`. |
+| media.sizing | conditional | enum | Required for a native media source: `fit` or `cover`. |
+| media.imageDescription | optional | string | Accessible image description sourced from trusted text or a projected description alias. |
 | blobAttributes.mimeTypeColumn | optional | string | SQL projection alias for the image MIME type column; valid only with `media.source: blobColumn`. |
 | blobAttributes.lastUpdatedColumn | optional | string | SQL projection alias for the image last-updated column; valid only with `media.source: blobColumn`. |
-| action.label | conditional | string | Required when a Cards action is emitted. Keep the label concise. |
+| action.type | conditional | enum | Required for an action: `button`, `fullCard`, `title`, `subtitle`, or `media`. |
+| action.label | conditional | string | Required only for `action.type: button`; omit for all other action types. |
 | action.layout.sequence | conditional | number | Required when a Cards action is emitted. |
+| action.layout.position | conditional | enum | Required only for `action.type: button`: `primary` or `secondary`. |
+| action.behavior.type | conditional | enum | Required for an action; use `redirectThisApp` for same-app Cards navigation. |
 | action.behavior.target.page | conditional | number | Target page for the row navigation action. |
 | action.behavior.target.items | conditional | object | Target page item mappings. Derive target page item and source column mappings from the UX contract, form PK metadata, or schema FK/PK evidence. |
+| action.appearance.displayType | optional | enum | Button-only presentation: `text`, `icon`, or `textWithIcon`. `icon` is required for the latter two. |
+| action.appearance.icon | conditional | string | Button icon required when `appearance.displayType` is `icon` or `textWithIcon`. |
+| action.appearance.hot | optional | boolean | Button-only hot presentation flag. |
+| action.appearance.cssClasses | optional | array | Button-only presentation classes; prefer native display options first. |
+| action.advanced.staticId | optional | string | Explicit action static ID. |
+| action.serverSideCondition | optional | object | Compiler-backed server-side condition; use its matching conditional fields and `executeCondition` for all types except `never`. |
+| action.triggerAction.action | conditional | string | Nested supported UI action reference required when `behavior.type: triggerAction`; omit navigation target properties in that behavior. |
 | columns | not supported | n/a | Do not emit report-style child `column (...)` blocks for cards regions unless a future compiler contract explicitly proves support. |
 
+# Source-to-Attribute Mapping
+
+Create this compact plan before selecting the SQL or REST template:
+
+| Requested role | Evidence and mapping rule |
+|---|---|
+| Title | Required. Map one proven alias/profile column to `title.column`; use `htmlExpression` only for required composition. |
+| Subtitle/body/secondary body | Optional. Map only requested roles and omit unmapped blocks. |
+| Primary key | Use a proven stable identity field for navigation and whenever BLOB media requires `card.primaryKeyColumn1`. |
+| Icon | Use a pinned fixed Font APEX icon, a proven icon-class column, or a proven initials column. |
+| Image | Select exactly one BLOB, URL-column, or direct-URL media shape. |
+| Badge | Map a proven status or metric column through `iconAndBadge.badgeColumn`. |
+| Link | Prove the target page, target item, and projected source key before emitting the action. |
+| Conditional style | Project an allowlisted semantic class token and map it to `card.cssClasses` after active-build compiler confirmation. |
+
+- For `localDatabase/sqlQuery`, every mapped alias must appear in the SQL projection and every database object/column must have authoritative object evidence.
+- For `restSource`, the shared REST Data Source and complete data profile must already exist or be generated from an authoritative specification/response. Map the profile's actual column names; do not infer JSON paths.
+- If a requested required role remains unresolved, stop with `Missing Inputs`. Omit unresolved optional roles rather than inventing aliases.
+- Prefer direct column mappings with `advancedFormatting: false`. When advanced formatting is necessary, set it to `true`, omit `column`, and use escaped `&COLUMN!HTML.` substitutions for text.
+
 # Output Template – Full
 
 ```apexlang
@@ -79,13 +126,21 @@ region {{regionStaticId}} (
     primaryKeyColumn1: {{card.primaryKeyColumn1}}
   }
   media {
+    advancedFormatting: false
     source: {{media.source}}
     {{media.sourceValueProperty}}: {{media.sourceValue}}
+    position: {{media.position}}
+    sizing: {{media.sizing}}
   }
   blobAttributes {
     mimeTypeColumn: {{blobAttributes.mimeTypeColumn}}
     lastUpdatedColumn: {{blobAttributes.lastUpdatedColumn}}
   }
+  componentAppearance {
+    layout: {{componentAppearance.layout}}
+    gridColumns: {{componentAppearance.gridColumns}}
+    cssClasses: {{componentAppearance.cssClasses}}
+  }
 )
 ```
 
@@ -103,8 +158,11 @@ Use exactly one of these source-specific shapes when a Cards region needs media:
 
 ```apexlang
 media {
+    advancedFormatting: false
     source: blobColumn
     blobColumn: <BLOB_COLUMN_ALIAS>
+    position: first
+    sizing: cover
 }
 blobAttributes {
     mimeTypeColumn: <MIME_TYPE_COLUMN_ALIAS>
@@ -114,23 +172,27 @@ blobAttributes {
 
 ```apexlang
 media {
+    advancedFormatting: false
     source: urlColumn
     urlColumn: <URL_COLUMN_ALIAS>
+    position: first
+    sizing: cover
 }
 ```
 
 ```apexlang
 media {
+    advancedFormatting: false
     source: imageUrl
     url: <STATIC_IMAGE_URL_OR_COLUMN_SUBSTITUTION>
+    position: first
+    sizing: cover
 }
 ```
 
-## Non-Default Media Presentation
-
-Default media presentation is represented by omission: do not emit any APEXlang-side `position`, `appearance`, or `sizing` property for default Cards media. Emit these properties only when the user or spec explicitly asks for a non-default media presentation. Never emit `position: first`, `appearance: square`, or `sizing: cover` just to mirror APEX defaults.
+## Media Presentation
 
-When a non-default presentation is required, add only the needed supported properties inside the same `media` block:
+For native media sources, default to `position: first` and `sizing: cover`. Use the other grammar-backed values only when the design calls for them:
 
 ```apexlang
 position: first
@@ -144,11 +206,12 @@ Use this native Cards action shape when each card row should navigate to a targe
 
 ```apexlang
 action action (
-    label: {{actionLabel}}
+    type: fullCard
     layout {
         sequence: {{actionSequence}}
     }
     behavior {
+        type: redirectThisApp
         target: {
             page: {{targetPage}}
             items: {
@@ -160,7 +223,31 @@ action action (
 )
 ```
 
-Prefer the declarative `behavior.target` object for Cards row navigation. Use `behavior.targetUrl`, `behavior.type`, or `behavior.linkAttributes` only when direct compiler truth proves the selected runtime supports the required non-declarative behavior. Native Cards actions must not emit `position`; `position` belongs to template-component actions such as Content Row, not native Cards actions.
+Use `fullCard`, `title`, `subtitle`, or `media` for non-button navigation; these types omit `label` and `layout.position`. A button action instead requires both `label` and `layout.position: primary | secondary` and may add a native `appearance` block. `behavior.type: redirectThisApp` requires the declarative `behavior.target` object; `redirectOtherApp` also requires `target`, `redirectUrl` requires `targetUrl`, and `triggerAction` emits neither navigation target property but requires a nested supported UI action reference:
+
+```apexlang
+action action (
+    type: button
+    label: Approve
+    layout {
+        position: primary
+        sequence: 20
+    }
+    appearance {
+        displayType: textWithIcon
+        icon: fa-check
+        hot: true
+    }
+    behavior {
+        type: triggerAction
+    }
+    triggerAction approve-action (
+        action: approve
+    )
+)
+```
+
+Use `advanced { staticId: ... }` and `serverSideCondition { ... }` only when the corresponding action requirement is evidenced. If full-card and decision-button actions coexist, document precedence and evidence-backed conditions. Do not infer business-condition exclusivity.
 
 Derive `{{targetPageItem}}` and `{{sourceColumn}}` from one of these evidence sources before emitting the action:
 
@@ -168,6 +255,55 @@ Derive `{{targetPageItem}}` and `{{sourceColumn}}` from one of these evidence so
 - Target form primary-key item metadata.
 - Schema FK/PK evidence tying the source row to the target page entity.
 
+# Icon Source Shapes
+
+When `iconSource` is present, always emit `iconPosition: top | start | end` and exactly one matching source-value property:
+
+| iconSource | Required source-value property |
+|---|---|
+| `iconClass` | `iconCssClasses` |
+| `iconClassColumn` | `iconColumn` |
+| `initials` | `iconColumn` |
+| `imageUrl` | `imageUrl` |
+| `imageBlobColumn` | `imageColumn` |
+
+Badge-only cards omit `iconSource`, all icon source-value properties, and `iconPosition`; they may still emit `badgeColumn`, `badgeLabel`, and `badgeCssClasses`.
+
+# Conditional Style Shape
+
+Conditional styling is source-driven and bounded:
+
+1. Derive the token through trusted SQL `CASE`/literal logic or an authoritative REST profile enum; a raw end-user or service-provided class column is not evidence.
+2. Permit only `u-normal`, `u-hot`, `u-info`, `u-success`, `u-warning`, `u-danger`, or `NULL`.
+3. Map the projected alias to `card.cssClasses`, for example `["&CARD_CSS_CLASSES."]`, only after active-build compiler confirmation.
+4. Keep status text in `badgeColumn` even when a conditional class is also present.
+
+Do not accept arbitrary class names from end-user input, invent Universal Theme classes, concatenate CSS in HTML expressions, or render badge HTML when the native badge contract is sufficient. If the active compiler exposes no safe property for the requested conditional style, keep the semantic status visible as text/badge content and stop before inventing a workaround.
+
+# Dynamic Refresh Shape
+
+- A refresh plan must identify the event source, the Cards region static ID, and any page items read by the Cards source.
+- Use the compiler-supported dynamic-action Refresh capability and target only the Cards region.
+- For SQL that binds page items, emit those items in `source.pageItemsToSubmit` so Ajax refresh sees current browser state.
+- After a modal create/edit flow, refresh Cards on dialog close when the changed row can affect the visible result set.
+- Do not add polling, JavaScript refresh code, or an `autoRefresh` block unless the request explicitly requires polling and compiler truth proves the exact active-build shape.
+- Load and emit the exact Cards-owned `cards.refresh-on-change.md` or `cards.refresh-after-dialog.md` template. Refresh actions emit `execution.sequence` and `fireOnInit: false`; they do not emit action-level `execution.event` or `itemsToSubmit` settings.
+
+# Security Shape
+
+- Require authenticated access for business-data Cards pages. If the Cards source is more restricted than the page, emit `security { authorizationScheme: @<EXISTING_ALIAS> }` on the region.
+- Authorization is independent at each boundary: Cards visibility, action availability, target page/process, and REST service authorization. A hidden action never replaces target authorization.
+- Advanced HTML expressions use `&COLUMN!HTML.` for every database or REST text value. Reject raw HTML/script/event attributes and unescaped substitutions.
+- Prefer same-app declarative targets. Literal external URLs require HTTPS; reject HTTP, substitutions in external targets, `javascript:`, `data:`, protocol-relative URLs, embedded credentials, path traversal, and unrestricted user-supplied destinations.
+- Prove SQL media URL columns through literal or `CASE` projection results. For REST media URL columns, record `authoritative-profile-url-prefixes: [...]` in `comments.comments`, using exact HTTPS prefixes or `application-static-relative`.
+- REST credentials belong to shared APEX Web Credentials, with `advanced.validForUrls` restricted to the exact resolved server plus source-path prefix. Never emit tokens, passwords, API keys, authorization headers, or secret query parameters in page or region APEXlang.
+
+# Responsive Layout Shape
+
+- Emit `componentAppearance.layout: grid`, `float`, or `horizontal` from explicit intent. Omit `gridColumns` for `float` and `horizontal`; with `grid`, emit it only for an explicit fixed count of `2`, `3`, `4`, or `5`.
+- Use `componentAppearance.cssClasses` only for a proven container class requirement; prefer native layout and template options.
+- Do not invent breakpoints, row spans, or CSS overrides to force the Cards layout.
+
 # Conditional Rendering Rules
 
 - For BLOB-backed Cards images, project the raw BLOB expression in SQL for display only, keep companion image metadata columns projected when available, define `card.primaryKeyColumn1`, and emit `media { source: blobColumn blobColumn: <BLOB_COLUMN_ALIAS> }`.
@@ -175,14 +311,14 @@ Derive `{{targetPageItem}}` and `{{sourceColumn}}` from one of these evidence so
 - When companion metadata columns are available for a BLOB-backed Cards image, emit `blobAttributes { mimeTypeColumn: <MIME_TYPE_ALIAS> lastUpdatedColumn: <LAST_UPDATED_ALIAS> }` after the `media` block.
 - Emit `blobAttributes` if and only if `media.source: blobColumn` is present. Do not emit `blobAttributes` for non-BLOB media sources or when the Cards region has no `media` block.
 - For URL-column Cards images, project the URL column in SQL and emit `media { source: urlColumn urlColumn: <URL_COLUMN_ALIAS> }`.
-- For direct image URL Cards images, emit `media { source: imageUrl url: <STATIC_IMAGE_URL_OR_COLUMN_SUBSTITUTION> }`; `url` may be a hard static URL or a substitution such as `&IMAGE_URL_COLUMN.`.
+- For direct image URL Cards images, emit `media { source: imageUrl url: <APPLICATION_STATIC_RELATIVE_URL> }` only after URL policy validation. Use `urlColumn` for a projected URL, and require its SQL expression or authoritative REST profile constraint to prove an application-static relative path or an allowlisted HTTPS origin.
 - In any Cards `media` block, emit at most one source-specific value property: `blobColumn` with `source: blobColumn`, `urlColumn` with `source: urlColumn`, or `url` with `source: imageUrl`.
-- Default media presentation emits no APEXlang-side `position`, `appearance`, or `sizing` property.
-- Emit `position`, `appearance`, and `sizing` only for explicit non-default media presentation requirements. Accepted values are `position: first | background`, `appearance: square | widescreen`, and `sizing: cover`.
-- Never emit `position: first`, `appearance: square`, or `sizing: cover` just to mirror APEX defaults.
+- Direct-source media emits `advancedFormatting: false`, required `position: first | body | background`, and required `sizing: fit | cover`; default to `first` and `cover`.
 - Keep BLOB-backed media attributes in the dedicated `media` block. Do not model Cards BLOB images with report-style `column (...)` blocks or report BLOB length expressions.
 - Use card-level actions only when the owning design requires row navigation.
-- Native Cards actions use `label` plus declarative `behavior.target`; do not emit `position`, `slot`, or template-component action placement properties.
+- Native Cards actions use the type-conditional action contract: button actions require `label` and `layout.position`; full-card/title/subtitle/media actions omit both. Button presentation may use `appearance.displayType`, `icon`, `hot`, and `cssClasses`; actions may use `advanced.staticId` and `serverSideCondition`. Declarative same-app `behavior.target` is preferred.
+- `behavior.type: triggerAction` requires a nested `triggerAction` child with `action`, and omits both `target` and `targetUrl`. Redirect behaviors use only their matching target property.
+- If full-card and decision-button interactions compete, document the intended precedence and evidence-backed business conditions in the UX contract; do not infer exclusivity from action declarations alone.
 - Every source column referenced in a Cards action item mapping such as `&{{sourceColumn}}.` must be projected by the Cards source.
 - Default card-region display style uses the base cards template with no additional style token in `appearance.templateOptions`.
 - If the design calls for Style A, add `style-a` to `appearance.templateOptions`.
@@ -195,20 +331,24 @@ Derive `{{targetPageItem}}` and `{{sourceColumn}}` from one of these evidence so
 - If `iconAndBadge.iconSource` is `iconClass`, then `iconAndBadge.iconCssClasses` is required and must reference a Font APEX icon class prefixed with `fa `.
 - If `iconAndBadge.iconSource` is `iconClassColumn`, then `iconAndBadge.iconColumn` is required and should point to a SQL column that stores the icon class.
 - If `iconAndBadge.iconSource` is `initials`, then `iconAndBadge.iconColumn` is required and should point to a SQL column that stores the initials.
+- If `iconAndBadge.iconSource` is `imageUrl`, then `iconAndBadge.imageUrl` is required.
+- If `iconAndBadge.iconSource` is `imageBlobColumn`, then `iconAndBadge.imageColumn` is required.
+- Whenever `iconAndBadge.iconSource` is set, `iconAndBadge.iconPosition: top | start | end` is required.
 - If badge mode is used, then `iconAndBadge.badgeColumn` is required while `iconAndBadge.badgeLabel` and `iconAndBadge.badgeCssClasses` remain optional.
-- If `title.column` is emitted, omit `title.htmlExpression` and omit `title.advancedFormatting`.
+- If `title.column` is emitted, set `title.advancedFormatting: false` and omit `title.htmlExpression`.
 - If `title.htmlExpression` is emitted, then `title.advancedFormatting` must also be emitted with value `true`, and `title.column` must be omitted.
-- If `subtitle.column` is emitted, omit `subtitle.htmlExpression` and omit `subtitle.advancedFormatting`.
+- If `subtitle.column` is emitted, set `subtitle.advancedFormatting: false` and omit `subtitle.htmlExpression`.
 - If `subtitle.htmlExpression` is emitted, then `subtitle.advancedFormatting` must also be emitted with value `true`, and `subtitle.column` must be omitted.
-- If `body.column` is emitted, omit `body.htmlExpression` and omit `body.advancedFormatting`.
+- If `body.column` is emitted, set `body.advancedFormatting: false` and omit `body.htmlExpression`.
 - If `body.htmlExpression` is emitted, then `body.advancedFormatting` must also be emitted with value `true`, and `body.column` must be omitted.
-- If `secondaryBody.column` is emitted, omit `secondaryBody.htmlExpression` and omit `secondaryBody.advancedFormatting`.
+- If `secondaryBody.column` is emitted, set `secondaryBody.advancedFormatting: false` and omit `secondaryBody.htmlExpression`.
 - If `secondaryBody.htmlExpression` is emitted, then `secondaryBody.advancedFormatting` must also be emitted with value `true`, and `secondaryBody.column` must be omitted.
 - Inside cards `title.htmlExpression`, `subtitle.htmlExpression`, `body.htmlExpression`, and `secondaryBody.htmlExpression`, use APEX substitution strings in the `&COLUMN.` form, not `#COLUMN#`.
 - Prefer escaped substitutions such as `&COLUMN!HTML.` when inserting user or database text into cards `htmlExpression`.
-- Emit `componentAppearance.gridColumns` only when the prompt explicitly specifies a fixed cards grid width or card column count.
-- Otherwise omit the entire `componentAppearance` block and allow cards to auto-determine column count.
-- If emitted, `componentAppearance.gridColumns` must be one of `2`, `3`, `4`, or `5`.
+- Emit `componentAppearance.layout: grid`, `float`, or `horizontal` only from explicit layout intent; emit `gridColumns` only for `layout: grid` and an explicit fixed cards grid width or card column count.
+- If emitted, `componentAppearance.gridColumns` must be one of `2`, `3`, `4`, or `5`; omit it for `float` and `horizontal`.
+- When Cards refresh depends on page items, every bind item must appear in `source.pageItemsToSubmit`.
+- Conditional styling must use a projected allowlisted token mapped through compiler-confirmed `card.cssClasses`; otherwise retain semantic badge/text content without the requested style.
 - Do not add report-style child `column (...)` blocks to cards regions. Cards column mapping is expressed through native cards blocks such as `card`, `title`, `subtitle`, `body`, `secondaryBody`, and `iconAndBadge`.
 - When a Cards region displays a BLOB image, `media.blobColumn` must reference the raw BLOB projection alias from the region SQL.
 - When `blobAttributes` is emitted, every referenced metadata alias must be projected by the same SQL source.
@@ -220,17 +360,16 @@ Derive `{{targetPageItem}}` and `{{sourceColumn}}` from one of these evidence so
 - Use `appearance.template: @/cards-container` for cards regions.
 - Emit at most one of `style-a`, `style-b`, or `style-c` for any one cards region.
 - Keep `templateOptions` to exact accepted values. `style-a` is valid when documented; `t-CardsRegion--styleA` is not.
-- Do not emit `componentAppearance.gridColumns` with values outside `2`, `3`, `4`, or `5`.
 - Ensure all referenced columns exist in the selected source.
 - Do not leave image-bearing source columns unmapped when the requested cards design explicitly calls for images or thumbnails.
 - Do not emit a generic `image` block for cards regions in this runtime; use the native `media` block instead.
 - Do not render a cards badge as ad-hoc HTML when the same outcome can be expressed with native `iconAndBadge.badgeColumn`, `badgeLabel`, and `badgeCssClasses`.
 - Do not emit cards identity or pagination properties unless explicitly confirmed by the active compiler contract.
 - Do not use report-only cards properties such as `performance.maxRowsToProcess`.
-- Do not emit `position` on native Cards actions.
-- Do not add media properties beyond `source`, `blobColumn`, `urlColumn`, `url`, `position`, `appearance`, and `sizing`, or `blobAttributes` properties beyond `mimeTypeColumn` and `lastUpdatedColumn`, unless compiler-backed truth proves them for the active runtime.
+- Emit `layout.position` only for `action.type: button`; it is required for buttons and invalid for the other Cards action types. Keep `layout.sequence` numeric and explicit for every Cards action.
+- Do not generate Faceted Search, Smart Filters, search fields, facets, filter blocks, or filter-specific dynamic actions under the visual-summary Cards pattern. If filtering/search is requested, route to that owning page pattern and use Cards only as its results region.
+- Do not implement Cards refresh with ad-hoc JavaScript when the native dynamic-action Refresh capability satisfies the requirement.
+- Keep media properties within the grammar-backed set: `advancedFormatting`, `htmlExpression`, `source`, `blobColumn`, `urlColumn`, `url`, `position`, `appearance`, `sizing`, `cssClasses`, and `imageDescription`; keep `blobAttributes` to `mimeTypeColumn` and `lastUpdatedColumn`.
 - Keep HTML expressions small and escaped when output includes user data.
-- Do not emit `title.htmlExpression` or `subtitle.htmlExpression` without `advancedFormatting: true`.
-- Do not emit `body.htmlExpression` or `secondaryBody.htmlExpression` without `advancedFormatting: true`.
-- Do not use `#COLUMN#` tokens inside cards `title.htmlExpression`, `subtitle.htmlExpression`, `body.htmlExpression`, or `secondaryBody.htmlExpression`; use `&COLUMN.` substitution strings instead.
+- Never place REST credentials, endpoint literals, or authentication headers in a Cards source. Reference the existing shared REST Data Source alias and validate its Web Credential URL restriction separately.
 - Metadata export lookup: search for `Cards`, `column-card`, and card attribute names used by the owning region.

package/skills/apexlang/templates/region-components/cards/cards._index.md

@@ -15,4 +15,5 @@ Primary routing entrypoint for `cards` region templates.
 
 1. Load this file.
 2. Load `cards._common.md`.
-3. Load one scenario template in this folder.
+3. Load one SQL or REST source scenario template in this folder.
+4. When Cards refresh is requested, additionally load exactly one Cards-owned refresh template matching the trigger.

package/skills/apexlang/templates/region-components/cards/cards.refresh-after-dialog.md

@@ -0,0 +1,46 @@
+---
+templateId: region.cards.refresh-after-dialog
+componentType: dynamicAction
+version: 1.0
+imports:
+  - cards._common
+description: Refresh one Cards region after a modal dialog closes.
+---
+
+# Purpose
+
+Refresh a Cards result set after its modal create/edit flow closes, while keeping the behavior isolated from shared Dynamic Action templates.
+
+# Output Template
+
+```apexlang
+dynamicAction {{dynamicActionStaticId}} (
+    name: {{name}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    when {
+        event: apexafterclosedialog
+        selectionType: region
+        region: @{{dialogLaunchRegionStaticId}}
+    }
+    action {{action.name}} (
+        action: refresh
+        affectedElements {
+            selectionType: region
+            region: @{{cardsRegionStaticId}}
+        }
+        execution {
+            sequence: {{action.execution.sequence}}
+            fireOnInit: false
+        }
+    )
+)
+```
+
+# Guardrails
+
+- Resolve the dialog-launch region and target Cards region aliases before rendering.
+- Use `apexafterclosedialog` for successful dialog-close refresh. Do not invent event aliases.
+- If the refreshed Cards source reads parent-page items, list them on its `source.pageItemsToSubmit`.
+- Do not emit action-level `execution.event`, Refresh-action `itemsToSubmit`, JavaScript refresh code, or unrelated region targets.

package/skills/apexlang/templates/region-components/cards/cards.refresh-on-change.md

@@ -0,0 +1,58 @@
+---
+templateId: region.cards.refresh-on-change
+componentType: dynamicAction
+version: 1.0
+imports:
+  - cards._common
+description: Refresh one Cards region when one or more page items change.
+---
+
+# Purpose
+
+Add a targeted, declarative Refresh dynamic action to a Cards page without changing the shared Dynamic Action templates used by other region families.
+
+# Cards Source Companion Shape
+
+When the Cards SQL or REST operation reads the trigger items, emit the same exact aliases on the Cards source:
+
+```apexlang
+source {
+    pageItemsToSubmit: {{source.pageItemsToSubmit}}
+}
+```
+
+`source.pageItemsToSubmit` is an array. It must include every page-item bind read by the refreshed Cards source.
+
+# Output Template
+
+```apexlang
+dynamicAction {{dynamicActionStaticId}} (
+    name: {{name}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    when {
+        event: change
+        selectionType: items
+        items: {{when.items}}
+    }
+    action {{action.name}} (
+        action: refresh
+        affectedElements {
+            selectionType: region
+            region: @{{cardsRegionStaticId}}
+        }
+        execution {
+            sequence: {{action.execution.sequence}}
+            fireOnInit: false
+        }
+    )
+)
+```
+
+# Guardrails
+
+- Resolve every trigger item and the Cards region static ID before rendering.
+- Target exactly one Cards region. Use separate actions only when the request explicitly names additional targets.
+- Put page-item submission on the Cards `source.pageItemsToSubmit`; do not emit `itemsToSubmit` settings on the Refresh action.
+- Do not emit action-level `execution.event`, JavaScript refresh code, polling, Faceted Search, or Smart Filters orchestration.

package/skills/apexlang/templates/region-components/cards/cards.rest-source.md

@@ -27,52 +27,88 @@ region {{regionStaticId}} (
   }
   card {
     primaryKeyColumn1: {{card.primaryKeyColumn1}}
+    primaryKeyColumn2: {{card.primaryKeyColumn2}}
+    cssClasses: {{card.cssClasses}}
   }
   title {
-    column: {{title.column}}
-    htmlExpression: {{title.htmlExpression}}
     advancedFormatting: {{title.advancedFormatting}}
+    {{title.valueProperty}}: {{title.value}}
   }
   subtitle {
-    column: {{subtitle.column}}
-    htmlExpression: {{subtitle.htmlExpression}}
     advancedFormatting: {{subtitle.advancedFormatting}}
+    {{subtitle.valueProperty}}: {{subtitle.value}}
   }
   body {
-    column: {{body.column}}
-    htmlExpression: {{body.htmlExpression}}
     advancedFormatting: {{body.advancedFormatting}}
+    {{body.valueProperty}}: {{body.value}}
   }
   secondaryBody {
-    column: {{secondaryBody.column}}
-    htmlExpression: {{secondaryBody.htmlExpression}}
     advancedFormatting: {{secondaryBody.advancedFormatting}}
+    {{secondaryBody.valueProperty}}: {{secondaryBody.value}}
   }
   media {
+    advancedFormatting: false
     source: {{media.source}}
-    blobColumn: {{media.blobColumn}}
-    urlColumn: {{media.urlColumn}}
-    accessibleDescription: {{media.accessibleDescription}}
+    {{media.sourceValueProperty}}: {{media.sourceValue}}
+    position: {{media.position}}
+    sizing: {{media.sizing}}
+    imageDescription: {{media.imageDescription}}
+  }
+  blobAttributes {
+    mimeTypeColumn: {{blobAttributes.mimeTypeColumn}}
+    lastUpdatedColumn: {{blobAttributes.lastUpdatedColumn}}
+  }
+  iconAndBadge {
+    iconSource: {{iconAndBadge.iconSource}}
+    {{iconAndBadge.sourceValueProperty}}: {{iconAndBadge.sourceValue}}
+    iconPosition: {{iconAndBadge.iconPosition}}
+    iconDescription: {{iconAndBadge.iconDescription}}
+    badgeColumn: {{iconAndBadge.badgeColumn}}
+    badgeLabel: {{iconAndBadge.badgeLabel}}
+    badgeCssClasses: {{iconAndBadge.badgeCssClasses}}
+  }
+  messages {
+    whenNoDataFound: {{messages.whenNoDataFound}}
+    noDataFoundIcon: {{messages.noDataFoundIcon}}
   }
   componentAppearance {
+    layout: {{componentAppearance.layout}}
     gridColumns: {{componentAppearance.gridColumns}}
+    cssClasses: {{componentAppearance.cssClasses}}
   }
 )
 ```
 
+The `valueProperty` placeholders are schematic. Content blocks emit `advancedFormatting: false` plus `column`, or `advancedFormatting: true` plus `htmlExpression`. Direct-source media emits `advancedFormatting: false`, required `position`, required `sizing`, and exactly one matching pair: `blobColumn` for `source: blobColumn`, `urlColumn` for `source: urlColumn`, or `url` for `source: imageUrl`. Emit `blobAttributes` only with `blobColumn` media. Append the native Cards action shape from `cards._common.md` only when a proven card target is requested; button presentation may use `appearance`, actions may use `advanced` and `serverSideCondition`, and `triggerAction` uses a nested child while omitting navigation targets.
+
 # Conditional Rendering Rules
 
-- If `title.column` is emitted, omit `title.htmlExpression` and omit `title.advancedFormatting`.
+- Resolve the existing REST Data Source, its REST Data Source Server, Web Credential, and authoritative data profile before rendering. Every title, subtitle, body, secondary-body, identity, icon, media, badge, link, or conditional-style field must use an actual profile column.
+- Omit `card.cssClasses` unless conditional per-row styling is explicitly requested. When used, map exactly one authoritative profile column constrained to `u-normal`, `u-hot`, `u-info`, `u-success`, `u-warning`, `u-danger`, or `NULL`; record that exact finite set in the profile column's `comments.comments` as `authoritative-profile-enum: [...]`. A missing enum marker or free-form service field is not safe class evidence.
+- For a REST media URL column, record `authoritative-profile-url-prefixes: [...]` in that profile column's `comments.comments`. List exact HTTPS prefixes, or use `application-static-relative` only when the service contract guarantees relative application-static paths.
+
+- If `title.column` is emitted, set `title.advancedFormatting: false` and omit `title.htmlExpression`.
 - If `title.htmlExpression` is emitted, `title.advancedFormatting` must also be emitted with value `true`, and `title.column` must be omitted.
-- If `subtitle.column` is emitted, omit `subtitle.htmlExpression` and omit `subtitle.advancedFormatting`.
+- If `subtitle.column` is emitted, set `subtitle.advancedFormatting: false` and omit `subtitle.htmlExpression`.
 - If `subtitle.htmlExpression` is emitted, `subtitle.advancedFormatting` must also be emitted with value `true`, and `subtitle.column` must be omitted.
-- If `body.column` is emitted, omit `body.htmlExpression` and omit `body.advancedFormatting`.
+- If `body.column` is emitted, set `body.advancedFormatting: false` and omit `body.htmlExpression`.
 - If `body.htmlExpression` is emitted, `body.advancedFormatting` must also be emitted with value `true`, and `body.column` must be omitted.
-- If `secondaryBody.column` is emitted, omit `secondaryBody.htmlExpression` and omit `secondaryBody.advancedFormatting`.
+- If `secondaryBody.column` is emitted, set `secondaryBody.advancedFormatting: false` and omit `secondaryBody.htmlExpression`.
 - If `secondaryBody.htmlExpression` is emitted, `secondaryBody.advancedFormatting` must also be emitted with value `true`, and `secondaryBody.column` must be omitted.
 - Omit the `media` block unless the cards design explicitly includes images or thumbnails.
-- When `media` is emitted, use `media.source: blobColumn` for BLOB-backed images and `media.source: urlColumn` for projected image URL columns.
+- When `media` is emitted, set `advancedFormatting: false`, emit required `position` and `sizing`, and use exactly one matching source/value shape: `blobColumn`/`blobColumn`, `urlColumn`/`urlColumn`, or `imageUrl`/`url`.
+- Emit `blobAttributes` only for `media.source: blobColumn` and only with metadata columns present in the REST data profile.
 - Inside cards `title.htmlExpression`, `subtitle.htmlExpression`, `body.htmlExpression`, and `secondaryBody.htmlExpression`, use `&COLUMN.` substitution strings, not `#COLUMN#`.
-- Omit the `componentAppearance` block by default.
-- Emit `componentAppearance.gridColumns` only when the prompt explicitly specifies a fixed card column count.
+- Emit `componentAppearance.layout: grid`, `float`, or `horizontal` from explicit layout intent. Emit `gridColumns` only with `layout: grid` and an explicit fixed card column count; otherwise omit it. Use `componentAppearance.cssClasses` only for a proven Cards-container class.
 - If emitted, `componentAppearance.gridColumns` must be one of `2`, `3`, `4`, or `5`.
+- If full-card and decision-button actions coexist, document interaction precedence and evidence-backed business conditions rather than inferring exclusivity.
+- When refresh depends on page items accepted by the REST operation, emit those items in `source.pageItemsToSubmit` and target the Cards static ID with the native Refresh dynamic-action capability.
+- Do not add filtering/search regions or filter orchestration in this Cards template. Route that composition to its owning Faceted Search or Smart Filters pattern.
+
+# REST Security Gate
+
+- `source.restSource` must be an existing shared REST Data Source alias with an authoritative data profile; never substitute an endpoint URL.
+- Keep passwords, tokens, API keys, Authorization headers, and secret query parameters in an APEX Web Credential, never in the Cards artifact.
+- Require a declared `restDataSourceServer` with a literal HTTPS `endpointUrl.url`. Require the REST Data Source `authentication.credentials` reference to resolve to a declared `webCredential`, and require its `advanced.validForUrls` to include the exact resolved server plus `source.urlPathPrefix`. Stop with `Missing Inputs` if any link is absent or broader than the required prefix.
+- Treat media URL fields as untrusted. The authoritative profile contract must constrain them to documented HTTPS origins or application-static relative paths and reject `javascript:`, `data:`, protocol-relative, embedded-credential, and user-controlled redirect values.
+- Apply page authentication, an existing Cards region authorization scheme when required, and independent authorization on navigation targets and server-side operations.