pi-apexlang 0.1.0

package/skills/apexlang/templates/buttons/README.md

@@ -0,0 +1,31 @@
+# Buttons Templates
+
+## Purpose
+Canonical button templates partitioned by action type so workflows can load only what a request needs.
+
+## Usage
+- Load `buttons._common.md` first for shared contract and guardrails.
+- Load `buttons._index.md` next to route intent to one primary action template.
+- Load exactly one primary variant template by `behavior.action`.
+- Load overlays only when requested (`confirmation`, `server-side-condition`, `appearance-icon`).
+- Resolve allowed button `templateOptions` from the inventory in `buttons._common.md`; pass the accepted emitted UT class value (for example `t-Button--iconLeft`), not a caller-facing alias or `static_id` such as `left`.
+- For `@/text-with-icon` buttons with `icon`, default icon placement to `t-Button--iconLeft`; use `t-Button--iconRight` only by explicit request, and do not add either option to `@/icon` buttons.
+- Use `buttons.registry.json` when tooling needs a machine-readable catalog for this family.
+
+## Template Catalog
+- `buttons._common.md`
+- `buttons._index.md`
+- `buttons.submit.md`
+- `buttons.redirect-this-app.md`
+- `buttons.redirect-other-app.md`
+- `buttons.defined-by-da.md`
+- `buttons.trigger-action.md`
+- `buttons.menu.md`
+- `buttons.confirmation.md`
+- `buttons.server-side-condition.md`
+- `buttons.appearance-icon.md`
+- `buttons.registry.json`
+
+## Maintenance
+- Keep this README synchronized with actual files in this directory.
+- Keep action mappings aligned with `assets/rules-mapping.json` and `skills/*` registries.

package/skills/apexlang/templates/buttons/buttons._common.md

@@ -0,0 +1,159 @@
+---
+templateId: buttons.common
+componentType: button
+version: 1.0
+description: Canonical shared contract for button templates.
+---
+
+# Purpose
+
+Define the shared variable contract, guardrails, and base skeleton used by all button templates.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `references/policies/memory-bank/40-components/apex.buttons.md` before drafting buttons.
+2. Validate action-specific requirements before rendering (`target`, `databaseAction`, `confirmation`, nested structures).
+3. Use only server-side condition types from `references/policies/memory-bank/20-data/apex.logic.md`.
+4. Resolve button template-option emitted values from the inventory in this file whenever `appearance.templateOptions` is present.
+5. Do not invent CSS classes; keep button presentation within documented templates and template options.
+6. Keep `layout.slot` valid for the referenced region template.
+   For breadcrumb/header-region Create buttons, use the region's `CREATE` slot rather than the login/wizard `next` slot.
+7. When `layout.column` or `layout.columnSpan` is used, validate them only within the button's local `layout.region + layout.slot` scope.
+8. For `behavior.action: redirectThisApp`, render `behavior.target` as a declarative `target: { ... }` property object; do not emit scalar `f?p=...` URL strings.
+9. When `appearance.buttonTemplate: @/text-with-icon` includes `appearance.icon`, include exactly one icon-position template option: default to `t-Button--iconLeft`, or use `t-Button--iconRight` only when explicitly requested.
+10. Do not add `t-Button--iconLeft` or `t-Button--iconRight` to `appearance.buttonTemplate: @/icon`; icon-only buttons have no text side to position against.
+
+---
+
+# Variable Contract
+
+
+| Name                          | Required    | Type         | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------------- | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| buttonStaticId                | yes         | string       | Static identifier used in `button <id> (...)`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| buttonName                    | yes         | string       | Stable internal name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| label                         | yes         | string       | User-facing label.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| layout.sequence               | yes         | number       | Position in slot ordering.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| layout.region                 | yes         | alias        | Region static ID alias (for example `@FORM_REGION`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| layout.slot                   | yes         | enum         | Must be valid for parent region template.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| layout.column                 | optional    | number       | Local column position within the parent region + slot scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| layout.columnSpan             | optional    | number       | Local span within the parent region + slot scope; row total must stay within 12.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| appearance.buttonTemplate     | yes         | enum         | `@/text`, `@/text-with-icon`, `@/icon`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| appearance.templateOptions    | optional    | array/string | Include `#DEFAULT#` when present as its own entry and use only the variant-specific accepted emitted values documented in the inventory below. For `@/text-with-icon` with `appearance.icon`, include exactly one of `t-Button--iconLeft` or `t-Button--iconRight`, defaulting to left. Do not concatenate tokens or use aliases/static_ids.                                                                                                                                                                                                                                              |
+| appearance.icon               | conditional | string       | Allowed only for `@/text-with-icon` or `@/icon`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| appearance.hot                | optional    | boolean      | Primary visual treatment; this is the DSL property used when the prompt asks for a primary button.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| appearance.showAsDisabled     | optional    | boolean      | Render disabled state while keeping behavior explicit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| behavior.action               | yes         | enum         | `submitPage`, `redirectThisApp`, `redirectOtherApp`, `definedByDynamicAction`, `triggerAction`, `menu`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| behavior.target               | conditional | object       | Required for redirect actions only. For `redirectThisApp`, use a declarative `target: { ... }` object with `page`, `items`, `clearCache`, `action`, and `request`; do not use scalar `f?p=...` strings.                                                                                                                                                                                                                                                                                                                                                                                           |
+| behavior.target.page          | conditional | number       | If a same-app link is needed, set to the page ID of the target page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| behavior.target.items         | conditional | object       | If a link is needed, set to a set of value-attribute pairs of page items and values they are to be set. Attributes can be in `&ITEM.` syntax if they represent a column or a literal. For example: items: { P1_ID: &P1_ID. P1_VAL: 100 }                                                                                                                                                                                                                                                                                                                                                         |
+| behavior.target.clearCache    | conditional | string       | List of comma-separated page numbers; used to clear the session cache of each page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| behavior.target.action        | conditional | string       | Use when performing an additional action on the page. Valid values are:- `clearRegions` : Completely tears down all session settings and customizations (like filters, aggregates, and highlights), reverting the region to the absolute default state.- `resetRegions` : Reverts the region back to its last saved state (e.g., the default report settings) while often preserving pagination or specific saved report metadata.- `resetPagination` : resets the pagination for all reports on the target pageIn most cases, this will be either omitted entirely or set to `resetPagination` |
+| behavior.target.request       | conditional | string       | Context of actions typically refers to the **Request Value** sent during a page submission to trigger specific server-side processes; often used to simulate pressing a button                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| behavior.databaseAction       | conditional | enum         | `insert`, `update`, `delete`; submit DML only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| behavior.requiresConfirmation | yes         | boolean      | If true, include `confirmation`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| behavior.warnOnUnsavedChanges | conditional | enum         | `doNotCheck` or `false`; omit for `definedByDynamicAction`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| confirmation.message          | conditional | string       | Required when `requiresConfirmation=true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| confirmation.style            | conditional | enum         | `danger`, `info`, `success`, `warning`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| serverSideCondition.type      | optional    | enum         | Use values from logic catalog only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| serverSideCondition.*         | conditional | varies       | Include only attributes required by selected condition type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| security.authorizationScheme  | optional    | alias        | Must exist in app shared components.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+
+
+---
+
+# Base Skeleton
+
+```apexlang
+button {{buttonStaticId}} (
+  buttonName: {{buttonName}}
+  label: {{label}}
+  layout {
+    sequence: {{layout.sequence}}
+    region: {{layout.region}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    buttonTemplate: {{appearance.buttonTemplate}}
+    templateOptions: {{appearance.templateOptions}}
+    icon: {{appearance.icon}}
+    hot: {{appearance.hot}}
+    showAsDisabled: {{appearance.showAsDisabled}}
+  }
+  behavior {
+    action: {{behavior.action}}
+    target: {
+        page: {{behavior.target.page}}
+        items: {
+            {{behavior.target.items}}
+        }
+        clearCache: {{behavior.target.clearCache}}
+        action: {{behavior.target.action}}
+        request: {{behavior.target.request}}
+    }
+    databaseAction: {{behavior.databaseAction}}
+    requiresConfirmation: {{behavior.requiresConfirmation}}
+    warnOnUnsavedChanges: {{behavior.warnOnUnsavedChanges}}
+  }
+  confirmation {
+    message: {{confirmation.message}}
+    style: {{confirmation.style}}
+  }
+  serverSideCondition {
+    type: {{serverSideCondition.type}}
+  }
+  security {
+    authorizationScheme: {{security.authorizationScheme}}
+  }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Always include: identity, layout, appearance.buttonTemplate, behavior.action, behavior.requiresConfirmation.
+- `target` only when action is `redirectThisApp` or `redirectOtherApp`.
+- `databaseAction` only when action is `submitPage` with DML intent.
+- If `requiresConfirmation=true`, include `confirmation` with both `message` and `style`; otherwise omit it.
+- Omit `warnOnUnsavedChanges` when action is `definedByDynamicAction`.
+- Include `icon` only when template is icon-capable.
+- If the template is `@/text-with-icon` and `icon` is present, include exactly one of `t-Button--iconLeft` or `t-Button--iconRight`; default to `t-Button--iconLeft`.
+- If the template is `@/icon`, do not include left/right icon-position options.
+- Render `serverSideCondition` and `security` only when explicitly required.
+- If `behavior.action` = `redirectThisApp`, render a declarative `target: { ... }` object. Never render `target: f?p=...` for same-application redirects.
+
+---
+
+# Theme 42 Button Template Options
+
+Use the listed emitted value as the exact value to pass in the button's `templateOptions`.
+Do not pass caller-facing aliases/static_ids such as `push`, `left`, or `right`.
+Example:
+```apexlang
+templateOptions: [
+  #DEFAULT#
+  t-Button--hoverIconPush
+  t-Button--iconLeft
+]
+```
+
+## Icon (`icon`)
+
+- Push | emitted=`t-Button--hoverIconPush` | source id=`push` | group=Icon Hover Animation
+- Spin | emitted=`t-Button--hoverIconSpin` | source id=`spin` | group=Icon Hover Animation
+
+## Text (`text`)
+
+- none
+
+## Text with Icon (`text-with-icon`)
+
+- Hide Icon on Desktop | emitted=`t-Button--desktopHideIcon` | source id=`hide-icon-on-desktop` | group=--
+- Hide Label on Mobile | emitted=`t-Button--mobileHideLabel` | source id=`hide-label-on-mobile` | group=--
+- Push | emitted=`t-Button--hoverIconPush` | source id=`push` | group=Icon Hover Animation
+- Spin | emitted=`t-Button--hoverIconSpin` | source id=`spin` | group=Icon Hover Animation
+- Left | emitted=`t-Button--iconLeft` | source id=`left` | group=Icon Position | default when `icon` is present
+- Right | emitted=`t-Button--iconRight` | source id=`right` | group=Icon Position | explicit override only

package/skills/apexlang/templates/buttons/buttons._index.md

@@ -0,0 +1,29 @@
+---
+templateId: buttons.index
+component: button
+dependsOn:
+  - buttons.common
+version: 1.0
+description: Entry point and intent router for button templates.
+---
+
+## Purpose
+Use this index as the canonical dispatcher for button templates. Load `buttons._common.md` first, then load exactly one primary action variant template.
+
+## Intent Router (Minimal Load)
+- Submit button (`submitPage`, save/create/update/delete): `@/buttons/buttons.submit.md`
+- Redirect in same app (`redirectThisApp`): `@/buttons/buttons.redirect-this-app.md`
+- Redirect to another app (`redirectOtherApp`): `@/buttons/buttons.redirect-other-app.md`
+- Button controlled by dynamic action (`definedByDynamicAction`): `@/buttons/buttons.defined-by-da.md`
+- Trigger action button (`triggerAction`): `@/buttons/buttons.trigger-action.md`
+- Menu button with entries (`menu`): `@/buttons/buttons.menu.md`
+
+## Overlay Templates (Load only when asked)
+- Confirmation emphasis/custom wording: `@/buttons/buttons.confirmation.md`
+- Server-side condition specifics: `@/buttons/buttons.server-side-condition.md`
+- Icon and appearance refinement: `@/buttons/buttons.appearance-icon.md`
+
+## Rules
+- Do not load all button variants for a single request.
+- Choose one primary action variant first; overlays are optional and additive.
+- Keep all generated button attributes consistent with `references/policies/memory-bank/40-components/apex.buttons.md` and `assets/component-policies.json`.

package/skills/apexlang/templates/buttons/buttons.appearance-icon.md

@@ -0,0 +1,29 @@
+---
+templateId: buttons.appearance-icon
+componentType: button
+version: 1.0
+description: Optional icon and appearance overlay for icon-capable button templates.
+---
+
+## Use When
+- User requests icon-based appearance or primary/disabled styling.
+
+## Block
+```apexlang
+appearance {
+  buttonTemplate: {{appearance.buttonTemplate}}
+  hot: {{appearance.hot}}
+  showAsDisabled: {{appearance.showAsDisabled}}
+  templateOptions: [
+    {{appearance.templateOptions}}
+  ]
+  icon: {{appearance.icon}}
+}
+```
+
+## Notes
+- Primary button wording in prompts maps to `hot: true` in emitted DSL.
+- Use icon only with `@/text-with-icon` or `@/icon`.
+- For `@/text-with-icon` with `icon`, include exactly one icon-position option: default to `t-Button--iconLeft`, or use `t-Button--iconRight` only when explicitly requested.
+- For `@/icon`, do not include `t-Button--iconLeft` or `t-Button--iconRight`.
+- Use canonical emitted button templateOptions values such as `t-Button--iconLeft` and `t-Button--hoverIconPush`, not aliases/static_ids such as `left` or `push`.

package/skills/apexlang/templates/buttons/buttons.confirmation.md

@@ -0,0 +1,17 @@
+---
+templateId: buttons.confirmation
+componentType: button
+version: 1.0
+description: Optional confirmation overlay for button variants.
+---
+
+## Use When
+- User requests confirmation before action execution.
+
+## Block
+```apexlang
+confirmation {
+  message: {{confirmation.message}}
+  style: {{confirmation.style}}
+}
+```

package/skills/apexlang/templates/buttons/buttons.defined-by-da.md

@@ -0,0 +1,36 @@
+---
+templateId: buttons.defined-by-da
+componentType: button
+version: 1.0
+description: Button variant whose behavior is defined by dynamic actions.
+---
+
+## Use When
+- User asks for a button handled by dynamic action logic.
+
+## Template
+```apexlang
+button {{buttonStaticId}} (
+  buttonName: {{buttonName}}
+  label: {{label}}
+  layout {
+    sequence: {{layout.sequence}}
+    region: {{layout.region}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    buttonTemplate: {{appearance.buttonTemplate}}
+    templateOptions: [
+      {{appearance.templateOptions}}
+    ]
+    icon: {{appearance.icon}}
+  }
+  behavior {
+    action: definedByDynamicAction
+    requiresConfirmation: {{behavior.requiresConfirmation}}
+  }
+)
+```
+
+## Notes
+- Do not include `warnOnUnsavedChanges` for this action type.

package/skills/apexlang/templates/buttons/buttons.menu.md

@@ -0,0 +1,43 @@
+---
+templateId: buttons.menu
+componentType: button
+version: 1.0
+description: Menu button variant with nested menu entries.
+---
+
+## Use When
+- User asks for a menu button with child entries.
+
+## Template
+```apexlang
+button {{buttonStaticId}} (
+  buttonName: {{buttonName}}
+  label: {{label}}
+  layout {
+    sequence: {{layout.sequence}}
+    region: {{layout.region}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    buttonTemplate: {{appearance.buttonTemplate}}
+    templateOptions: [
+      {{appearance.templateOptions}}
+    ]
+    icon: {{appearance.icon}}
+  }
+  behavior {
+    action: menu
+  }
+
+  menu {{menuEntry.staticId}} (
+    label: {{menuEntry.label}}
+    layout {
+      sequence: {{menuEntry.sequence}}
+    }
+    behavior {
+      type: {{menuEntry.type}}
+      target: {{menuEntry.target}}
+    }
+  )
+)
+```

package/skills/apexlang/templates/buttons/buttons.redirect-other-app.md

@@ -0,0 +1,35 @@
+---
+templateId: buttons.redirect-other-app
+componentType: button
+version: 1.0
+description: Redirect button variant to navigate to another application.
+---
+
+## Use When
+- User requests cross-application navigation.
+
+## Template
+```apexlang
+button {{buttonStaticId}} (
+  buttonName: {{buttonName}}
+  label: {{label}}
+  layout {
+    sequence: {{layout.sequence}}
+    region: {{layout.region}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    buttonTemplate: {{appearance.buttonTemplate}}
+    templateOptions: [
+      {{appearance.templateOptions}}
+    ]
+    icon: {{appearance.icon}}
+  }
+  behavior {
+    action: redirectOtherApp
+    target: {{behavior.target}}
+    requiresConfirmation: {{behavior.requiresConfirmation}}
+    warnOnUnsavedChanges: {{behavior.warnOnUnsavedChanges}}
+  }
+)
+```

package/skills/apexlang/templates/buttons/buttons.redirect-this-app.md

@@ -0,0 +1,41 @@
+---
+templateId: buttons.redirect-this-app
+componentType: button
+version: 1.0
+description: Redirect button variant to navigate within the current application.
+---
+
+## Use When
+- User requests navigation to another page in the same app.
+
+## Template
+```apexlang
+button {{buttonStaticId}} (
+  buttonName: {{buttonName}}
+  label: {{label}}
+  layout {
+    sequence: {{layout.sequence}}
+    region: {{layout.region}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    buttonTemplate: {{appearance.buttonTemplate}}
+    templateOptions: {{appearance.templateOptions}}
+    icon: {{appearance.icon}}
+  }
+  behavior {
+    action: redirectThisApp
+    target: {
+        page: {{behavior.target.page}}
+        items: {
+            {{behavior.target.items}}
+        }
+        clearCache: {{behavior.target.clearCache}}
+        action: {{behavior.target.action}}
+        request: {{behavior.target.request}}
+    }
+    requiresConfirmation: {{behavior.requiresConfirmation}}
+    warnOnUnsavedChanges: {{behavior.warnOnUnsavedChanges}}
+  }
+)
+```

package/skills/apexlang/templates/buttons/buttons.registry.json

@@ -0,0 +1,33 @@
+{
+  "version": 1,
+  "entries": [
+    {
+      "slug": "root-readme",
+      "file": "README.md"
+    },
+    {
+      "slug": "root-contract",
+      "index": "buttons._index.md",
+      "common": "buttons._common.md"
+    },
+    {
+      "slug": "primary-templates",
+      "examples": [
+        "buttons.submit.md",
+        "buttons.redirect-this-app.md",
+        "buttons.redirect-other-app.md",
+        "buttons.defined-by-da.md",
+        "buttons.trigger-action.md",
+        "buttons.menu.md"
+      ]
+    },
+    {
+      "slug": "overlay-templates",
+      "examples": [
+        "buttons.confirmation.md",
+        "buttons.server-side-condition.md",
+        "buttons.appearance-icon.md"
+      ]
+    }
+  ]
+}

package/skills/apexlang/templates/buttons/buttons.server-side-condition.md

@@ -0,0 +1,22 @@
+---
+templateId: buttons.server-side-condition
+componentType: button
+version: 1.0
+description: Optional server-side condition overlay for button variants.
+---
+
+## Use When
+- User requests conditional rendering/execution.
+
+## Block
+```apexlang
+serverSideCondition {
+  type: {{serverSideCondition.type}}
+  item: {{serverSideCondition.item}}
+  {{serverSideCondition.comparisonAttribute}}: {{serverSideCondition.comparisonValue}}
+}
+```
+
+## Notes
+- Include only attributes required by the selected condition type.
+- Map `comparisonAttribute` to `value` for equality/request checks and to `list` for `itemIsInColonDelimitedList` / `itemIsNotInColonDelimitedList`.

package/skills/apexlang/templates/buttons/buttons.submit.md

@@ -0,0 +1,39 @@
+---
+templateId: buttons.submit
+componentType: button
+version: 1.0
+description: Submit page button variant, optionally with databaseAction for DML.
+---
+
+## Use When
+- User requests save/create/update/delete submit behavior.
+
+## Template
+```apexlang
+button {{buttonStaticId}} (
+  buttonName: {{buttonName}}
+  label: {{label}}
+  layout {
+    sequence: {{layout.sequence}}
+    region: {{layout.region}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    buttonTemplate: {{appearance.buttonTemplate}}
+    templateOptions: [
+      {{appearance.templateOptions}}
+    ]
+    icon: {{appearance.icon}}
+  }
+  behavior {
+    action: submitPage
+    databaseAction: {{behavior.databaseAction}}
+    requiresConfirmation: {{behavior.requiresConfirmation}}
+    warnOnUnsavedChanges: doNotCheck
+  }
+)
+```
+
+## Notes
+- Include `databaseAction` only for DML intent.
+- Add confirmation block only when required.

package/skills/apexlang/templates/buttons/buttons.trigger-action.md

@@ -0,0 +1,37 @@
+---
+templateId: buttons.trigger-action
+componentType: button
+version: 1.0
+description: Button variant that triggers nested actions.
+---
+
+## Use When
+- User requests triggerAction behavior (for example download or execute server-side code).
+
+## Template
+```apexlang
+button {{buttonStaticId}} (
+  buttonName: {{buttonName}}
+  label: {{label}}
+  layout {
+    sequence: {{layout.sequence}}
+    region: {{layout.region}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    buttonTemplate: {{appearance.buttonTemplate}}
+    templateOptions: [
+      {{appearance.templateOptions}}
+    ]
+    icon: {{appearance.icon}}
+  }
+  behavior {
+    action: triggerAction
+    requiresConfirmation: {{behavior.requiresConfirmation}}
+  }
+
+  triggerAction {{triggerAction.staticId}} (
+    action: {{triggerAction.action}}
+  )
+)
+```