pi-apexlang 0.1.0

package/skills/apexlang/templates/items/hidden-item/hidden-item.explicit-defaults.md

@@ -0,0 +1,75 @@
+---
+templateId: items.hidden-item.explicit-defaults
+componentType: item
+version: 1.0
+imports:
+  - hidden-item._common.md
+description: hidden-item variant explicit-defaults.
+---
+
+# Purpose
+
+Scenario overlay for `hidden-item` items focused on `explicit-defaults` behavior.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `hidden-item._common.md` and `templates/items/items._common.md` before using this overlay.
+2. Inherit the family contract and add only the scenario-specific placeholders listed below.
+3. Remove blocks that are not required by the final prompt before finalizing the item DSL.
+
+---
+
+# Variable Contract
+
+Inherits the full family contract from `hidden-item._common.md`. Base family requirements such as `itemName`, `layout.region`, and `layout.sequence` still apply.
+
+## Required Variables
+
+- None beyond the inherited family contract.
+
+## Optional Variables
+
+- `label.alignment`
+- `layout.slot`
+- `layout.alignment`
+- `appearance.templateOptions`
+- `security.sessionStateProtection`
+- `settings.valueProtected`
+
+---
+
+# Output Template
+
+```apexlang
+pageItem {{itemName}} (
+    type: hidden
+    layout {
+        sequence: {{layout.sequence}}
+        region: @{{layout.region}}
+        slot: {{layout.slot}}
+    }
+    settings {
+        valueProtected: {{settings.valueProtected}}
+    }
+    security {
+        sessionStateProtection: {{security.sessionStateProtection}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Show optional defaults only when the generator needs them visible in the final output.
+- Remove family-specific settings that are not relevant to the requested prompt.
+
+---
+
+# Guardrails
+
+- Keep `hidden-item._common.md` as the source of truth for reusable family rules.
+- Keep placeholder names aligned with the inherited family contract.
+- Do not reintroduce fixed demo wrappers, demo identifiers, or literal region names.

package/skills/apexlang/templates/items/hidden-item/hidden-item.minimal.md

@@ -0,0 +1,68 @@
+---
+templateId: items.hidden-item.minimal
+componentType: item
+version: 1.0
+imports:
+  - hidden-item._common.md
+description: hidden-item variant minimal.
+---
+
+# Purpose
+
+Scenario overlay for `hidden-item` items focused on `minimal` behavior.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `hidden-item._common.md` and `templates/items/items._common.md` before using this overlay.
+2. Inherit the family contract and add only the scenario-specific placeholders listed below.
+3. Remove blocks that are not required by the final prompt before finalizing the item DSL.
+
+---
+
+# Variable Contract
+
+Inherits the full family contract from `hidden-item._common.md`. Base family requirements such as `itemName`, `layout.region`, and `layout.sequence` still apply.
+
+## Required Variables
+
+- None beyond the inherited family contract.
+
+## Optional Variables
+
+- `security.sessionStateProtection` defaults to `checksumRequiredSessionLevel`
+
+---
+
+# Output Template
+
+```apexlang
+pageItem {{itemName}} (
+    type: hidden
+    layout {
+        sequence: {{layout.sequence}}
+        region: @{{layout.region}}
+        slot: {{layout.slot}}
+    }
+    security {
+        sessionStateProtection: checksumRequiredSessionLevel
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Do not omit the security block for hidden items in generated business pages.
+- Keep the item block minimal and rely on the inherited family contract for anything not shown here.
+- Remove optional blocks that are not populated by the final prompt.
+
+---
+
+# Guardrails
+
+- Keep `hidden-item._common.md` as the source of truth for reusable family rules.
+- Keep placeholder names aligned with the inherited family contract.
+- Do not reintroduce fixed demo wrappers, demo identifiers, or literal region names.

package/skills/apexlang/templates/items/image-upload/image-upload._common.md

@@ -0,0 +1,106 @@
+---
+templateId: items.imageUpload.common
+componentType: item
+version: 2.0
+canonicalDslType: imageUpload
+nativeType: NATIVE_IMAGE_UPLOAD
+description: Canonical contract for image-upload item templates.
+---
+
+# Purpose
+
+Define the canonical contract, conditional rules, and output skeleton for `image-upload` items.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `templates/items/items._common.md` first.
+2. Load `references/policies/memory-bank/40-components/apex.items.md` before drafting final item DSL.
+3. Use this family only for `imageUpload` semantics and remove attributes that belong to other item families.
+4. Keep scenario overlays in the family templates and keep reusable contract details in this common file.
+5. For compiler-valid 26.1 output, keep image-upload guidance to the generic page-item contract plus form binding fields that the compiler metadata still exposes. Do not emit stale upload-specific source metadata or stale item settings that the compiler no longer accepts for `imageUpload`.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|---|---|---|---|
+| itemName | yes | string | Page item static name such as `P10_STATUS`. |
+| type | yes | enum | Must be `imageUpload`. |
+| label.label | yes | string | Visible label text. |
+| label.alignment | optional | enum | Label alignment when the label is shown. |
+| layout.region | yes | alias | Host region static ID reference. |
+| layout.sequence | yes | number | Rendering sequence within the region. |
+| layout.slot | optional | enum | Region slot, typically `regionBody` for items rendered inside a host region. |
+| layout.alignment | optional | enum | Item alignment inside the slot. |
+| appearance.template | yes | alias | Family-appropriate template alias. |
+| appearance.templateOptions | optional | array/string | Template modifiers such as `#DEFAULT#` or compact options. |
+| validation.valueRequired | optional | boolean | Set when the item value is mandatory. |
+| source.formRegion | conditional | alias | Required for form-bound image uploads. |
+| source.column | conditional | string | Primary image payload column. |
+| source.dataType | conditional | enum | Data type for the stored image payload, typically BLOB. |
+| help.helpText | required by default | string | Builder help text or assistive guidance for visible user-facing image-upload items; omit only for hidden items or a documented exemption. |
+| security.sessionStateProtection | optional | enum | Session state protection policy. |
+| security.authorizationScheme | optional | alias | Authorization scheme alias when the item is conditionally visible. |
+
+---
+
+# Output Skeleton Template
+
+```apexlang
+pageItem {{itemName}} (
+    type: imageUpload
+    label {
+        label: {{label.label}}
+        alignment: {{label.alignment}}
+    }
+    layout {
+        sequence: {{layout.sequence}}
+        region: @{{layout.region}}
+        slot: {{layout.slot}}
+        alignment: {{layout.alignment}}
+    }
+    appearance {
+        template: {{appearance.template}}
+        templateOptions: {{appearance.templateOptions}}
+    }
+    validation {
+        valueRequired: {{validation.valueRequired}}
+    }
+    source {
+        formRegion: @{{source.formRegion}}
+        column: {{source.column}}
+        dataType: {{source.dataType}}
+    }
+    help {
+        helpText: {{help.helpText}}
+    }
+    security {
+        sessionStateProtection: {{security.sessionStateProtection}}
+        authorizationScheme: @{{security.authorizationScheme}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Remove unsupported or unused blocks before finalizing the DSL.
+- Omit `source {}` when the item is not bound to persisted data or a form region.
+- Do not emit legacy upload-only `settings {}` properties such as `storageType`, `displayAs`, `allowMultipleFiles`, `maxFileSize`, `displayDownloadLink`, `downloadLinkText`, `purgeFilesAt`, `dropzoneTitle`, `dropzoneDescription`, `maxWidth`, `maxHeight`, `allowCropping`, `aspectRatio`, `customAspectRatio`, `captureUsing`, or `previewSize` for `imageUpload`.
+- Do not emit legacy `source.mimeTypeColumn`, `source.filenameColumn`, or `source.blobLastUpdatedColumn` for `imageUpload`.
+- Emit `validation {}` only when the scenario requires declarative checks.
+- Keep the item aligned with generic page-item and form-binding properties that remain compiler-backed for `imageUpload`.
+
+---
+
+# Guardrails
+
+- Follow guardrails in `references/policies/memory-bank/00-guard/ai.guard.md`.
+- Do not invent unsupported attributes or UT classes.
+- Keep placeholder names aligned with `templates/items/items._common.md`.
+- Validate the storage strategy and metadata column mappings before finalizing upload items.
+- If a requested image-upload behavior depends on a property not covered here, query compiler-backed truth before emitting it.

package/skills/apexlang/templates/items/image-upload/image-upload._index.md

@@ -0,0 +1,23 @@
+---
+templateId: items.imageUpload.index
+componentType: item
+version: 1.0
+imports:
+  - image-upload._common.md
+description: Routing entrypoint for image-upload variants.
+---
+
+# Purpose
+
+Route `image-upload` requests to the correct variant markdown file.
+
+# Load Order
+
+1. Load this file.
+2. Load `image-upload._common.md`.
+3. Load one variant file listed below.
+
+# Variant Files
+- `image-upload.compact-template.md`
+- `image-upload.explicit-defaults.md`
+- `image-upload.minimal.md`

package/skills/apexlang/templates/items/image-upload/image-upload.compact-template.md

@@ -0,0 +1,79 @@
+---
+templateId: items.image-upload.compact-template
+componentType: item
+version: 1.0
+imports:
+  - image-upload._common.md
+description: image-upload variant compact-template.
+---
+
+# Purpose
+
+Scenario overlay for `image-upload` items focused on `compact-template` behavior.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `image-upload._common.md` and `templates/items/items._common.md` before using this overlay.
+2. Inherit the family contract and add only the scenario-specific placeholders listed below.
+3. Remove blocks that are not required by the final prompt before finalizing the item DSL.
+
+---
+
+# Variable Contract
+
+Inherits the full family contract from `image-upload._common.md`. Base family requirements such as `itemName`, `layout.region`, and `layout.sequence` still apply.
+
+## Required Variables
+
+- `appearance.templateOptions`
+
+## Optional Variables
+
+- `label.alignment`
+- `layout.slot`
+- `layout.alignment`
+- `security.sessionStateProtection`
+
+---
+
+# Output Template
+
+```apexlang
+pageItem {{itemName}} (
+    type: imageUpload
+    label {
+        label: {{label.label}}
+        alignment: {{label.alignment}}
+    }
+    layout {
+        sequence: {{layout.sequence}}
+        region: @{{layout.region}}
+        slot: {{layout.slot}}
+        alignment: {{layout.alignment}}
+    }
+    appearance {
+        template: {{appearance.template}}
+        templateOptions: {{appearance.templateOptions}}
+    }
+    security {
+        sessionStateProtection: {{security.sessionStateProtection}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Use `appearance.templateOptions` only when the requested control needs compact or condensed rendering.
+- Keep the rest of the item aligned with the inherited family contract.
+
+---
+
+# Guardrails
+
+- Keep `image-upload._common.md` as the source of truth for reusable family rules.
+- Keep placeholder names aligned with the inherited family contract.
+- Do not reintroduce fixed demo wrappers, demo identifiers, or literal region names.

package/skills/apexlang/templates/items/image-upload/image-upload.explicit-defaults.md

@@ -0,0 +1,80 @@
+---
+templateId: items.image-upload.explicit-defaults
+componentType: item
+version: 1.0
+imports:
+  - image-upload._common.md
+description: image-upload variant explicit-defaults.
+---
+
+# Purpose
+
+Scenario overlay for `image-upload` items focused on `explicit-defaults` behavior.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `image-upload._common.md` and `templates/items/items._common.md` before using this overlay.
+2. Inherit the family contract and add only the scenario-specific placeholders listed below.
+3. Remove blocks that are not required by the final prompt before finalizing the item DSL.
+
+---
+
+# Variable Contract
+
+Inherits the full family contract from `image-upload._common.md`. Base family requirements such as `itemName`, `layout.region`, and `layout.sequence` still apply.
+
+## Required Variables
+
+- None beyond the inherited family contract.
+
+## Optional Variables
+
+- `label.alignment`
+- `layout.slot`
+- `layout.alignment`
+- `appearance.templateOptions`
+- `security.sessionStateProtection`
+
+---
+
+# Output Template
+
+```apexlang
+pageItem {{itemName}} (
+    type: imageUpload
+    label {
+        label: {{label.label}}
+        alignment: {{label.alignment}}
+    }
+    layout {
+        sequence: {{layout.sequence}}
+        region: @{{layout.region}}
+        slot: {{layout.slot}}
+        alignment: {{layout.alignment}}
+    }
+    appearance {
+        template: {{appearance.template}}
+        templateOptions: {{appearance.templateOptions}}
+    }
+    security {
+        sessionStateProtection: {{security.sessionStateProtection}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Show optional defaults only when the generator needs them visible in the final output.
+- Do not reintroduce stale upload-only settings removed from the family contract.
+
+---
+
+# Guardrails
+
+- Keep `image-upload._common.md` as the source of truth for reusable family rules.
+- Keep placeholder names aligned with the inherited family contract.
+- Do not reintroduce fixed demo wrappers, demo identifiers, or literal region names.

package/skills/apexlang/templates/items/image-upload/image-upload.minimal.md

@@ -0,0 +1,73 @@
+---
+templateId: items.image-upload.minimal
+componentType: item
+version: 1.0
+imports:
+  - image-upload._common.md
+description: image-upload variant minimal.
+---
+
+# Purpose
+
+Scenario overlay for `image-upload` items focused on `minimal` behavior.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `image-upload._common.md` and `templates/items/items._common.md` before using this overlay.
+2. Inherit the family contract and add only the scenario-specific placeholders listed below.
+3. Remove blocks that are not required by the final prompt before finalizing the item DSL.
+
+---
+
+# Variable Contract
+
+Inherits the full family contract from `image-upload._common.md`. Base family requirements such as `itemName`, `layout.region`, and `layout.sequence` still apply.
+
+## Required Variables
+
+- None beyond the inherited family contract.
+
+## Optional Variables
+
+- `security.sessionStateProtection`
+
+---
+
+# Output Template
+
+```apexlang
+pageItem {{itemName}} (
+    type: imageUpload
+    label {
+        label: {{label.label}}
+    }
+    layout {
+        sequence: {{layout.sequence}}
+        region: @{{layout.region}}
+        slot: {{layout.slot}}
+    }
+    appearance {
+        template: {{appearance.template}}
+    }
+    security {
+        sessionStateProtection: {{security.sessionStateProtection}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Keep the item block minimal and rely on the inherited family contract for anything not shown here.
+- Remove optional blocks that are not populated by the final prompt.
+
+---
+
+# Guardrails
+
+- Keep `image-upload._common.md` as the source of truth for reusable family rules.
+- Keep placeholder names aligned with the inherited family contract.
+- Do not reintroduce fixed demo wrappers, demo identifiers, or literal region names.

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

@@ -0,0 +1,179 @@
+---
+templateId: items.common
+componentType: item
+version: 2.0
+description: Shared contract for Oracle APEX page items across item families.
+---
+
+# Purpose
+
+Define the shared variable contract, guardrails, and base `pageItem` skeleton used by all item-family templates.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `references/policies/memory-bank/40-components/apex.items.md` before drafting final item DSL.
+2. Resolve default visible item-template and label-treatment policy from `references/policies/memory-bank/40-components/apex.templates.md` before applying family-specific item rules.
+3. Start from `templates/items/items._index.md` and route to exactly one item family entrypoint.
+4. Resolve visible item-template option IDs from the inventory in this file whenever `appearance.templateOptions` is present.
+5. Use `itemName` as the canonical item identifier placeholder everywhere in `items/`.
+6. Keep output variable-driven and remove fixed demo identifiers, page wrappers, and region names.
+7. When Builder UI visibility conflicts with compiler-backed metadata, follow the compiler-valid property shape rather than assuming the Builder visibility state is authoritative.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|---|---|---|---|
+| itemName | yes | string | Page item static name such as `P10_STATUS`. |
+| type | yes | enum | Family-specific item type token such as `textField`, `selectList`, or `displayOnly`. |
+| label.* | conditional | variant | Label attributes when the family supports visible labels. |
+| layout.* | yes | variant | Placement attributes such as `region`, `sequence`, `slot`, and alignment. When `layout.region` is present, `layout.slot` should usually be the host region slot such as `regionBody`, not a page-level slot like `body`. `layout.labelColumnSpan` is an optional deliberate override when label-grid width must be controlled explicitly. |
+| appearance.* | conditional | variant | Template, template options, size hints, placeholder text, and format masks when supported. |
+| lov.* | conditional | variant | LOV source attributes for LOV-based item families. |
+| settings.* | optional | variant | Family-specific settings emitted by the routed family template. |
+| validation.* | optional | variant | Declarative validation attributes supported by the selected family. |
+| source.* | conditional | variant | Binding and persistence attributes when the item is tied to a form or stored value. |
+| help.helpText | required by default | string | Builder help text or assistive guidance for visible user-facing items; omit only for hidden items or a documented exemption. |
+| security.* | optional | variant | Session state protection and authorization settings. |
+
+---
+
+# Output Skeleton Template
+
+````apexlang
+pageItem {{itemName}} (
+    type: {{type}}
+    label {
+        label: {{label.label}}
+        alignment: {{label.alignment}}
+    }
+    layout {
+        sequence: {{layout.sequence}}
+        region: @{{layout.region}}
+        slot: {{layout.slot}}
+        alignment: {{layout.alignment}}
+        startNewRow: {{layout.startNewRow}}
+    }
+    appearance {
+        template: {{appearance.template}}
+        templateOptions: {{appearance.templateOptions}}
+        width: {{appearance.width}}
+        height: {{appearance.height}}
+        valuePlaceholder: {{appearance.valuePlaceholder}}
+        formatMask: {{appearance.formatMask}}
+    }
+    lov {
+        type: {{lov.type}}
+        staticValues: {{lov.staticValues}}
+        sqlQuery:
+            ```sql
+            {{lov.sqlQuery}}
+            ```
+        lov: @{{lov.lov}}
+        displayNullValue: {{lov.displayNullValue}}
+    }
+    settings {
+        {{settings.attributes}}
+    }
+    validation {
+        valueRequired: {{validation.valueRequired}}
+        minLength: {{validation.minLength}}
+        maxLength: {{validation.maxLength}}
+    }
+    source {
+        formRegion: @{{source.formRegion}}
+        column: {{source.column}}
+        dataType: {{source.dataType}}
+    }
+    help {
+        helpText: {{help.helpText}}
+    }
+    security {
+        sessionStateProtection: {{security.sessionStateProtection}}
+        authorizationScheme: @{{security.authorizationScheme}}
+    }
+)
+````
+
+---
+
+# Conditional Rendering Rules
+
+- Omit blocks that are unsupported by the routed family or unnecessary for the requested scenario.
+- Emit `layout.labelColumnSpan` only when a deliberate label-grid override is required. Use the canonical token `labelColumnSpan`; never emit the legacy alias `labelColSpan`.
+- Choose exactly one LOV source when the family supports LOVs.
+- For inline `lov.sqlQuery` definitions, return the display value first and the return value second.
+- Canonical inline LOV SQL shape:
+  ```sql
+  select [displayValue],
+         [returnValue]
+    from ...
+   where ...
+   order by ...
+  ```
+- Emit `source {}` only for form-bound or persisted items.
+- Keep `settings {}` reserved for family-specific attributes exposed by the routed family template.
+- When `layout.region` is present, use the host region slot rather than a page-level slot. The default for items rendered inside a standard host region is usually `regionBody`, not `body` or `BODY`.
+- Only apply validation.maxLength to text fields
+- Emit `help { helpText: ... }` by default for visible editable, filter/control, and other user-facing items unless the item is hidden or a documented exemption applies.
+
+---
+
+# Guardrails
+
+- Follow guardrails in `references/policies/memory-bank/00-guard/ai.guard.md`.
+- Styling workflows do not own item-template defaults; only apply styling overrides when the request explicitly includes styling work and the item/template contract allows it.
+- Do not invent unsupported attributes or UT classes.
+- Use only the documented visible item-template option IDs: optional variants currently have no extra options, while required variants allow `asterisk` and `inline-label`.
+- Keep `appearance.templateOptions` to exact accepted values only. `#DEFAULT#` is standalone when present; do not concatenate it with another token or swap in emitted CSS class strings.
+- Keep placeholder names and block ordering consistent across the entire `items/` folder.
+- Help text must follow the repo guidance layer: concise, useful, non-duplicative, and grounded in authoritative metadata when available; do not use placeholders or no-op copy.
+
+---
+
+# Folderization Rules
+
+- Family template entrypoints are always `items/<family>/<family>._common.md` plus either `standard.md` or the routed variant file.
+- Keep family folders in lowercase kebab-case.
+- Keep scenario-specific output blocks in the family files and keep shared rules in the corresponding family common file.
+
+---
+
+# Theme 42 Visible Item Template Options
+
+Use the listed `static_id` as the exact value to pass in the item's `templateOptions`.
+Example: `templateOptions: [asterisk]`
+
+## Hidden (`hidden`)
+
+- none
+
+## Optional (`optional`)
+
+- none
+
+## Optional - Above (`optional-above`)
+
+- none
+
+## Optional - Floating (`optional-floating`)
+
+- none
+
+## Required (`required`)
+
+- Asterisk | `static_id=asterisk` | `css=t-Form-fieldContainer--indicatorAsterisk` | `group=Required Indicator`
+- Inline Label | `static_id=inline-label` | `css=t-Form-fieldContainer--indicatorLabel` | `group=Required Indicator`
+
+## Required - Above (`required-above`)
+
+- Asterisk | `static_id=asterisk` | `css=t-Form-fieldContainer--indicatorAsterisk` | `group=Required Indicator`
+- Inline Label | `static_id=inline-label` | `css=t-Form-fieldContainer--indicatorLabel` | `group=Required Indicator`
+
+## Required - Floating (`required-floating`)
+
+- Asterisk | `static_id=asterisk` | `css=t-Form-fieldContainer--indicatorAsterisk` | `group=Required Indicator`
+- Inline Label | `static_id=inline-label` | `css=t-Form-fieldContainer--indicatorLabel` | `group=Required Indicator`