pi-apexlang 0.1.0

package/skills/apexlang/templates/region-components/form/form._items._common.md

@@ -0,0 +1,102 @@
+---
+templateId: region.form.items.common
+componentType: region
+version: 1.0
+imports:
+  - form._common.md
+description: Shared contract for form page items linked to a form region.
+---
+
+# Purpose
+
+Standardize reusable form item blocks so scenario templates can render item definitions from variables instead of fixed demo items.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- `items`
+
+## Item Fields
+
+- `item.staticId`
+- `item.type`
+- `item.region`
+- `item.sequence`
+- `item.slot` for items rendered in the form region body should be `regionBody`
+- `item.source.column`
+- `item.source.dataType`
+
+## Required PK Item Fields
+
+- `item.source.primaryKey: true` for every primary-key item mapped to a form region
+
+## Optional Item Fields
+
+- `item.label.*`
+- `item.layout.*`
+- `item.appearance.*`
+- `item.settings.*`
+- `item.validation.*`
+- `item.lov.*`
+- `item.security.*`
+
+---
+
+# Output Template – Item Block
+
+```apexlang
+pageItem {{item.staticId}} (
+  type: {{item.type}}
+  label {
+    label: {{item.label.label}}
+    alignment: {{item.label.alignment}}
+  }
+  layout {
+    sequence: {{item.sequence}}
+    region: @{{item.region}}
+    slot: {{item.slot}}
+    alignment: {{item.layout.alignment}}
+  }
+  appearance {
+    template: {{item.appearance.template}}
+    templateOptions: {{item.appearance.templateOptions}}
+    width: {{item.appearance.width}}
+  }
+  settings {
+    sendOnPageSubmit: {{item.settings.sendOnPageSubmit}}
+  }
+  validation {
+    valueRequired: {{item.validation.valueRequired}}
+  }
+  lov {
+    type: {{item.lov.type}}
+    staticValues: {{item.lov.staticValues}}
+  }
+  source {
+    formRegion: @{{item.region}}
+    column: {{item.source.column}}
+    dataType: {{item.source.dataType}}
+    primaryKey: {{item.source.primaryKey}}
+  }
+  security {
+    sessionStateProtection: {{item.security.sessionStateProtection}}
+  }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Omit optional blocks when values are not provided.
+- Do not emit `appearance.width` for item types whose schema forbids it; `displayOnly` supports only `appearance.template` and `appearance.templateOptions`.
+- For `displayOnly`, always emit `settings { sendOnPageSubmit: false }` by default.
+- Keep each item mapped to exactly one form region via `item.region`.
+- For items rendered inside the main form region body, emit `layout.slot: regionBody` instead of `BODY`.
+- Every form region must have at least one source-mapped primary-key item; emit `primaryKey: true` on each PK item.
+- Do not emit `primaryKey: false` for non-PK items; omit the property unless the item is a true primary key.
+- Keep item static IDs, labels, and LOV values variable-driven.
+- When visible item-template `templateOptions` are present, use the `static_id` values documented in `../../items/items._common.md`.

package/skills/apexlang/templates/region-components/form/form._processes._common.md

@@ -0,0 +1,39 @@
+---
+templateId: region.form.processes.common
+componentType: template
+version: 1.0
+imports:
+  - form._common.md
+description: Shared process linkage contract for form scenario templates.
+---
+
+# Purpose
+
+Keep process placeholders explicit and reusable across form scenarios while process implementation details stay in business-logic templates.
+
+---
+
+# Variable Contract
+
+## Optional Variables
+
+- `processes.formInitialization`
+- `processes.automaticRowProcessing`
+- `processes.additional`
+
+---
+
+# Output Template – Process Placeholders
+
+```apexlang
+{{processes.formInitialization}}
+{{processes.automaticRowProcessing}}
+{{processes.additional}}
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Render placeholders only when corresponding process templates are required.
+- Use `business-logic/processes/*` templates for executable process blocks.

package/skills/apexlang/templates/region-components/form/form._template_options.md

@@ -0,0 +1,24 @@
+# Form Region Template Options
+
+Use the listed `static_id` as the exact value to pass in the region's `templateOptions`.
+Example: `templateOptions: [stick-to-bottom-for-mobile]`
+`#DEFAULT#` remains a standalone entry when used. Do not concatenate it with another token or substitute CSS class strings for the documented accepted value.
+
+## Buttons Container (`buttons-container`)
+Preset: none
+
+- Stick to Bottom for Mobile | `static_id=stick-to-bottom-for-mobile` | `css=t-ButtonRegion--stickToBottom` | `group=--`
+- No Padding | `static_id=no-padding` | `css=t-ButtonRegion--noPadding` | `group=Body Padding`
+- Slim Padding | `static_id=slim-padding` | `css=t-ButtonRegion--slimPadding` | `group=Body Padding`
+- Borderless | `static_id=borderless` | `css=t-ButtonRegion--noBorder` | `group=Style`
+- Remove UI Decoration | `static_id=remove-ui-decoration` | `css=t-ButtonRegion--noUI` | `group=Style`
+
+## Item Container (`item-container`)
+Preset: none
+
+- Stack on Mobile | `static_id=stack-on-mobile` | `css=t-ItemContainer--stackMobile` | `group=--`
+- Wrap Items | `static_id=wrap-items` | `css=t-ItemContainer--wrap` | `group=--`
+- Center | `static_id=center` | `css=t-ItemContainer--alignCenter` | `group=Alignment`
+- End | `static_id=end` | `css=t-ItemContainer--alignEnd` | `group=Alignment`
+- Start | `static_id=start` | `css=t-ItemContainer--alignStart` | `group=Alignment`
+- Stretch | `static_id=stretch` | `css=t-ItemContainer--alignStretch` | `group=Alignment`

package/skills/apexlang/templates/region-components/form/form.basic.md

@@ -0,0 +1,106 @@
+---
+templateId: region.form.basic
+componentType: region
+version: 1.0
+imports:
+  - form._common.md
+  - form._items._common.md
+  - form._processes._common.md
+description: Table-backed form scenario using variable-driven item and process placeholders.
+---
+
+# Purpose
+
+Form scenario for local database sources with reusable item and process placeholders.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `form._common.md`, `form._items._common.md`, and `form._processes._common.md` before use.
+2. Keep item, button, and process definitions variable-driven; do not inline demo literals.
+3. Pair with `business-logic/processes/form-initialization` and `form-automatic-row-processing` when automatic DML is enabled.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- `regionStaticId`
+- `name`
+- `source.location`
+- `layout.sequence`
+- `layout.slot`
+- `appearance.template`
+- `formItems` (from `form._items._common.md`)
+
+## Optional Variables
+
+- `source.tableName`
+- `source.type`
+- `source.sqlQuery`
+- `source.plsqlFunctionBody`
+- `appearance.templateOptions`
+- `edit.*`
+- `serverSideCondition.*`
+- `security.*`
+- `formButtons`
+- `formProcesses` (from `form._processes._common.md`)
+
+---
+
+# Output Template – Full
+
+```apexlang
+region {{regionStaticId}} (
+  name: {{name}}
+  type: form
+  source {
+    location: {{source.location}}
+    tableName: {{source.tableName}}
+    sqlQuery:
+      ```sql
+      {{source.sqlQuery}}
+      ```
+    plsqlFunctionBody:
+      ```plsql
+      {{source.plsqlFunctionBody}}
+      ```
+  }
+  layout {
+    sequence: {{layout.sequence}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    template: {{appearance.template}}
+    templateOptions: {{appearance.templateOptions}}
+  }
+  edit {
+    enabled: {{edit.enabled}}
+  }
+  serverSideCondition {
+    type: {{serverSideCondition.type}}
+    item: {{serverSideCondition.item}}
+    {{serverSideCondition.comparisonAttribute}}: {{serverSideCondition.comparisonValue}}
+  }
+  security {
+    authorizationScheme: @{{security.authorizationScheme}}
+  }
+)
+
+{{formItems}}
+
+{{formButtons}}
+
+{{formProcesses}}
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Render `{{formItems}}` using `form._items._common.md`.
+- Render `{{formProcesses}}` using `form._processes._common.md`.
+- Omit optional blocks that are not required for the selected source type.
+- For the standard table-backed path, emit `source.tableName` only and omit `source.type`.

package/skills/apexlang/templates/region-components/form/form.dialog-buttons.md

@@ -0,0 +1,45 @@
+---
+templateId: region.form.dialog-buttons
+componentType: region
+version: 1.0
+imports:
+  - form._common.md
+description: Companion dialog-buttons region generated with dialog forms.
+---
+
+# Purpose
+
+Document the generated static-content button container used with dialog forms.
+
+# Generation Rules (MANDATORY)
+
+1. Load `form._common.md` first.
+2. Use this companion region only for dialog-form scenarios.
+3. Keep icon-placement defaults on the generated button declarations; the `@/buttons-container` region itself does not carry `t-Button--iconLeft` or `t-Button--iconRight`.
+
+# Variable Contract
+
+## Required Variables
+
+- `layout.slot`
+- `appearance.template`
+
+# Output Template – Full
+
+```apexlang
+region buttons (
+  name: Buttons
+  type: staticContent
+  layout {
+    slot: dialogFooter
+  }
+  appearance {
+    template: @/buttons-container
+  }
+)
+```
+
+# Conditional Rendering Rules
+
+- Keep this as a support region, not a replacement for the primary form region.
+- Apply icon-position template options only on icon-plus-text buttons associated with this region.

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

@@ -0,0 +1,88 @@
+---
+templateId: region.form.rest-source
+componentType: region
+version: 1.0
+imports:
+  - form._common.md
+  - form._items._common.md
+  - form._processes._common.md
+description: REST-backed form scenario using variable-driven item and process placeholders.
+---
+
+# Purpose
+
+Form scenario for REST Data Source-backed forms with reusable item and process placeholders.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `form._common.md`, `form._items._common.md`, and `form._processes._common.md` before use.
+2. Confirm the REST source supports required operations before enabling automatic DML.
+3. Keep REST aliases, item mappings, and process wiring variable-driven.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- `regionStaticId`
+- `name`
+- `source.location` (use `restSource`)
+- `source.restSource`
+- `layout.sequence`
+- `layout.slot`
+- `appearance.template`
+- `formItems` (from `form._items._common.md`)
+
+## Optional Variables
+
+- `appearance.templateOptions`
+- `edit.*`
+- `security.*`
+- `formButtons`
+- `formProcesses` (from `form._processes._common.md`)
+
+---
+
+# Output Template – Full
+
+```apexlang
+region {{regionStaticId}} (
+  name: {{name}}
+  type: form
+  source {
+    location: {{source.location}}
+    restSource: @{{source.restSource}}
+  }
+  layout {
+    sequence: {{layout.sequence}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    template: {{appearance.template}}
+    templateOptions: {{appearance.templateOptions}}
+  }
+  edit {
+    enabled: {{edit.enabled}}
+  }
+  security {
+    authorizationScheme: @{{security.authorizationScheme}}
+  }
+)
+
+{{formItems}}
+
+{{formButtons}}
+
+{{formProcesses}}
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Render `{{formItems}}` using `form._items._common.md`.
+- Render `{{formProcesses}}` using `form._processes._common.md`.
+- Omit optional blocks not required by the target REST implementation.

package/skills/apexlang/templates/region-components/help-text/README.md

@@ -0,0 +1,18 @@
+# Help Text Templates
+
+## Purpose
+Canonical guidance for the `help-text` region family, including shared contract loading and supported scenario variants.
+
+## Usage
+- Load `help-text._common.md` first to align variable contracts, guardrails, and required inputs.
+- Choose a scenario variant matching the requested interaction pattern, data source type, and page composition context.
+- Preserve canonical path references and markdown-first conventions when updating workflow or registry links.
+
+## Template Catalog
+- `help-text._common.md`
+- `help-text.standard.md`
+
+## Maintenance
+- Keep this README synchronized with actual files in the directory.
+- Update catalogs and usage notes whenever templates are added, removed, or renamed.
+- Keep family guidance aligned with page-level standards in memory-bank rules and with scenario coverage in this folder.

package/skills/apexlang/templates/region-components/help-text/help-text._common.md

@@ -0,0 +1,29 @@
+---
+templateId: region.help-text.common
+componentType: region
+version: 1.0
+description: Shared contract for help-text regions and page help snippets.
+---
+
+# Purpose
+
+Standardize inline help-text regions and optional page-level help content.
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| regionStaticId | yes | string | Help text region static id. |
+| name | yes | string | Region name. |
+| appearance.template | optional | string | Default to `@/standard` for inline help regions unless a documented shell is required. |
+| headerAndFooter.headerText | optional | string | Optional region header. |
+| headerAndFooter.footerText | optional | string | Optional region footer. |
+| pageHelp.helpText | optional | string | Optional page-level help text. |
+| textMessageKey | optional | string | Shared message key for translations. |
+
+# Guardrails
+
+- Keep inline help concise and actionable.
+- Route reusable content through shared text messages when localization is required.
+- Do not duplicate long guidance in both inline and page-level help unless explicitly requested.
+- Use `appearance.template: @/standard` as the default help-region shell.

package/skills/apexlang/templates/region-components/help-text/help-text._index.md

@@ -0,0 +1,18 @@
+---
+templateId: help-text.index
+componentType: template
+version: 1.0
+imports:
+  - help-text._common.md
+description: Routing entrypoint for help-text templates.
+---
+
+# Purpose
+
+Primary routing entrypoint for `help-text` templates.
+
+# Load Order
+
+1. Load this file.
+2. Load `help-text._common.md`.
+3. Load one scenario template in this folder.

package/skills/apexlang/templates/region-components/help-text/help-text.standard.md

@@ -0,0 +1,44 @@
+---
+templateId: region.help-text.standard
+componentType: region
+version: 1.0
+imports:
+  - help-text._common
+description: Standard help-text region with optional page help and preview JSON contract.
+---
+
+# Output Template
+
+```
+region {{regionStaticId}} (
+  name: {{name}}
+  type: helpText
+  layout {
+    sequence: {{layout.sequence}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    template: {{appearance.template}}
+    templateOptions: #DEFAULT#
+  }
+  headerAndFooter {
+    headerText: {{headerAndFooter.headerText}}
+    footerText: {{headerAndFooter.footerText}}
+  }
+)
+```
+
+# Batch Preview JSON Skeleton
+
+```json
+{
+  "target": "P1_SAMPLE_ITEM",
+  "scope": "item",
+  "textMessageKey": "ITEM.P1_SAMPLE_ITEM.HELP",
+  "inlineHelp": { "text": "Short inline help." },
+  "detailedHelp": { "text": "Longer guidance for users." },
+  "authoritativeSource": "Column comment",
+  "localization": ["en"],
+  "notes": "Keep inline help concise."
+}
+```

package/skills/apexlang/templates/region-components/interactive-grid/README.md

@@ -0,0 +1,31 @@
+# Interactive Grid Templates
+
+## Purpose
+Canonical guidance for the `interactive-grid` region family, including shared contract loading and supported scenario variants.
+
+## Usage
+- Load `interactive-grid._index.md` first.
+- Load `interactive-grid._common.md` next to align variable contracts, guardrails, and required inputs.
+- Load `interactive-grid._columns._common.md` for canonical grid column contract blocks.
+- Load `interactive-grid._saved-report._common.md` for shared saved report contract blocks.
+- Load one scenario variant matching the requested interaction pattern and data source type.
+- Every Interactive Grid must include at least one saved report. Load the saved-report and columns partials so the generated region emits a baseline `savedReport PRIMARY` plus explicit `displayColumn` coverage for the grid and single-row view.
+- Treat saved-report refreshes as metadata-only unless packaged metadata proves broader Interactive Grid DSL drift:
+  - aggregate import metadata now flows through the `create_ig_rpt_agg_apexlang` path
+  - aggregate metadata keeps view/static-id parameters structurally visible when the accepted contract exposes them
+  - chart `Sort By` defaults to `LABEL`, so explicit non-default values exclude `LABEL`
+- Use the optional `componentAdvanced.initJavaScriptFunction` block only when JavaScript initialization is required; keep it wrapped in ` ```javascript-browser ` and return `options`.
+- Preserve canonical path references and markdown-first conventions when updating workflow or registry links.
+
+## Template Catalog
+- `interactive-grid._index.md`
+- `interactive-grid._common.md`
+- `interactive-grid._columns._common.md`
+- `interactive-grid._saved-report._common.md`
+- `interactive-grid.standard.md`
+- `interactive-grid.region.md`
+
+## Maintenance
+- Keep this README synchronized with actual files in the directory.
+- Update catalogs and usage notes whenever templates are added, removed, or renamed.
+- Keep family guidance aligned with page-level standards in memory-bank rules and with scenario coverage in this folder.

package/skills/apexlang/templates/region-components/interactive-grid/interactive-grid._columns._common.md

@@ -0,0 +1,101 @@
+---
+templateId: region.interactive-grid.columns.common
+componentType: region
+version: 1.0
+description: Shared column contract for interactive grid regions.
+---
+
+# Purpose
+
+Standardize `column` variable contracts, output shape, and guardrails for interactive-grid variants.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `interactive-grid._common.md` before using this columns contract.
+2. Ensure one column maps to the region key column and can be marked as primary key in source metadata.
+3. Omit optional nested blocks when their variables are not provided.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| column.name | yes | string | Column static identifier. |
+| column.type | yes | enum | Grid item type (`textField`, `numberField`, `datePicker`, `textarea`, etc.). |
+| column.heading | optional | string | Column heading text. |
+| column.headingAlignment | optional | enum | `start`, `center`, `end`. |
+| column.sequence | yes | number | Display sequence. |
+| column.columnAlignment | optional | enum | `start`, `center`, `end`. |
+| column.databaseColumn | optional | string | Backing DB column name. |
+| column.dataType | optional | string | Source data type. |
+| column.primaryKey | optional | boolean | Primary key indicator for the key column. |
+| column.maxLength | optional | number | Validation max length. |
+| column.sessionStateDataType | optional | string | Session state type for large text columns. `session`, `user`|
+| column.columnFormatting.htmlExpression | optional | string | Column markup rendering expression. |
+| column.columnFilter.lovType | optional | enum | Filter LOV behavior. |
+| column.columnFilter.performanceImpactingOperators | optional | array | Performance-impacting operators list. |
+
+---
+
+# Output Template – Full
+
+```apexlang
+column {{column.name}} (
+  type: {{column.type}}
+  heading {
+    heading: {{column.heading}}
+    alignment: {{column.headingAlignment}}
+  }
+  layout {
+    sequence: {{column.sequence}}
+    columnAlignment: {{column.columnAlignment}}
+  }
+  source {
+    databaseColumn: {{column.databaseColumn}}
+    dataType: {{column.dataType}}
+    primaryKey: {{column.primaryKey}}
+  }
+  validation {
+    maxLength: {{column.maxLength}}
+  }
+  sessionState {
+    dataType: {{column.sessionStateDataType}}
+  }
+  columnFormatting {
+    htmlExpression: {{column.columnFormatting.htmlExpression}}
+  }
+  columnFilter {
+    lovType: {{column.columnFilter.lovType}}
+    performanceImpactingOperators: {{column.columnFilter.performanceImpactingOperators}}
+  }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Omit `heading` when no heading values are provided.
+- Omit `heading.alignment` and `layout.columnAlignment` when not provided.
+- Omit `source` unless at least one source attribute is provided.
+- Omit `validation` unless `column.maxLength` is provided.
+- Omit `sessionState` unless `column.sessionStateDataType` is provided.
+- Omit `columnFormatting` unless `column.columnFormatting.htmlExpression` is provided.
+- Omit `columnFilter` unless one or more filter attributes are provided.
+- Do not emit Classic Report-only `reportColumnQueryId`, `derivedColumn`, or `type: link` on Interactive Grid columns.
+- Do not emit Interactive Report column-level `link {}` blocks on Interactive Grid columns unless compiler-backed metadata for the active build proves a supported grid column navigation shape.
+- Do not emit column-level `appearance`, `comments`, or `security` blocks unless the active machine-readable schema explicitly allows them; surface guidance or authorization at page/region level when no column hook exists.
+
+---
+
+# Guardrails
+
+- Keep column ordering deterministic and aligned with end-user workflows.
+- Use `column.primaryKey: true` on the column that matches the grid key column.
+- Keep performance-impacting operators minimal and intentional.
+- When using `columnFormatting.htmlExpression`, do not emit `type: richText`; keep plain text implicit.
+- Keep SQL data-only; emit report markup via `columnFormatting.htmlExpression` per `references/policies/memory-bank/30-pages/apex.report-column-rendering.md`.
+- Keep saved-report `displayColumn` coverage separate from column definition shape; saved-report metadata does not imply column-level link/navigation support.