pi-apexlang 0.1.0

package/skills/apexlang/templates/shared-components/task-definitions/approve-request.example.md

@@ -0,0 +1,196 @@
+---
+templateId: shared-components.task-definitions.approve-request.example
+componentType: markdown-apexlang-example
+version: 1.0
+migrationNote: preserved from previous standalone template example
+---
+
+# Approve Request Example
+
+## Purpose
+
+Markdown-preserved APEXlang example. Use this file for syntax and structure only after loading the family `_index.md` and `_common.md` contract.
+
+## Example
+
+```apexlang
+/* create this component under shared-components/task-definitions/taskDefinitionName.apx
+     - taskDefinitionName could be a valid suitable name   
+     - Outcome-driven (Approve / Reject).
+     - Used for authorization and governance.
+     - All the substitutition strings should follow the format &LOAN_ACCOUNT_NO. , don't enclose it within #
+     - Strictly use action component group to perform any post approval or completion action once the task has been completed.
+
+   
+   Common Use Cases
+   ----------------
+   - Order approval
+   - Budget approval
+   - Access approval
+
+   Outcomes
+   -------------------
+   - APPROVE
+   - REJECT
+
+   Parameter rules
+   -------------------
+   - Do not use advanced.required; it is not a valid property for task parameters.
+
+   Completion handling rules
+   -------------------
+   - Do not create page-level sendEmail processes for task completion.
+   - Implement completion logic in the task definition action with execution.onEvent: complete.
+   - If email is required, send it from this action using APEX_MAIL or sendEMail action under onEvent: complete .
+  
+   When determining participants for an Human Task:
+
+   1. DO NOT hardcode usernames.
+   2. DO NOT assume :APP_USER is the approver.
+   3. ALWAYS resolve approvers from configured user tables.
+   4. Find the appropriate approver/supervisor based on the user tables and roles.
+   5. Fail safely if no approver is found.
+   6. Validate the SQL or PL/SQL code blocks. 
+
+Note: Prefer the structured `advanced { detailsPage: { ... } }` object form shown in this task-definition family. Do not default to a string `f?p=...` value when creating new task definitions. Keep the details page aligned with the task-details page family and pass the task id through the mapped page item.
+*/
+taskDefinition CHECKER_APPROVAL (
+    name: Loan Approval
+    type: approval
+    task {
+        subject: Loan Approval Required – &LOAN_ACCOUNT_NO.
+    }
+    advanced {
+        detailsPage: {
+            page: 20
+            items: {
+                P20_TASK_ID: &TASK_ID.
+            }
+            clearCache: 20
+            action: resetPagination
+        }
+    }
+    source {
+        type: sqlQuery
+        sqlQuery: select * from loan_master where loan_id = :APEX$TASK_PK
+    }
+
+    parameter DISBURSED_AMOUNT (
+        label {
+            label: Disbursed Amount
+        }
+        value {
+            required: false
+        }
+    )
+
+    
+
+    action loan-approved (
+        name: Loan Approved
+        type: executeCode
+        source {
+            plsqlCode: 
+                ```plsql
+                begin
+                UPDATE loan_master
+                SET status = :APEX$TASK_OUTCOME
+                WHERE loan_id = :APEX$TASK_PK;
+                
+                
+                INSERT INTO loan_checker_action (
+                loan_id, checker_user, action)
+                values(
+                :APEX$TASK_PK,:APEX$TASK_OWNER,:APEX$TASK_OUTCOME);
+                end;
+                
+                ```
+        }
+        execution {
+            onEvent: complete
+            outcome: approved
+            sequence: 10
+        }
+        successMessage {
+            successMessage: Loan Approved successfully.
+        }
+    )
+
+    action loan-rejected (
+        name: Loan Rejected
+        type: executeCode
+        source {
+            plsqlCode: 
+                ```plsql
+                begin
+                UPDATE loan_master
+                SET status = :APEX$TASK_OUTCOME
+                WHERE loan_id = :APEX$TASK_PK;
+                
+                
+                INSERT INTO loan_checker_action (
+                loan_id, checker_user, action)
+                values(
+                :APEX$TASK_PK,:APEX$TASK_OWNER,:APEX$TASK_OUTCOME);
+                end;
+                
+                ```
+        }
+        execution {
+            onEvent: complete
+            outcome: rejected
+            sequence: 20
+        }
+        successMessage {
+            successMessage: Loan rejected successfully.
+        }
+    )
+     action send-email (
+        name: Send Email
+        type: sendEMail
+        emailHeader {
+            to: &P12_CUSTOMER_EMAIL.
+        }
+        emailTemplate {
+            emailTemplate: @order-confirmation
+            placeholderValues: 
+                ```
+                {
+                    "ORDER_NUMBER":"&P12_ORDER_ID.",
+                    "CUSTOMER_NAME":"&P12_CUSTOMER_NAME.",
+                    "ORDER_DATE":"&P12_ORDER_DATE.",
+                    "SHIP_TO":"",
+                    "SHIPPING_ADDRESS_LINE_1":"",
+                    "SHIPPING_ADDRESS_LINE_2":"",
+                    "ITEMS_ORDERED":"",
+                    "ORDER_TOTAL":"&P12_TOTAL_AMT.",
+                    "ORDER_URL":"","MY_APPLICATION_LINK":""
+                }
+                ```
+        }
+        emailAttachments {
+            attachmentSql: 
+                ```sql
+                select file_blob blob_column,
+                       file_name,
+                       mime_type,
+                       null content_id
+                  from order_files
+                 where order_id = :APEX$TASK_PK
+                ```
+        }
+        execution {
+            onEvent: complete
+            sequence: 20
+        }
+    )
+
+    participant (
+        value {
+            type: expression
+            plsqlExpression: loan_workflow_api.get_checker(:APEX$TASK_PK)
+        }
+    )
+
+)
+```

package/skills/apexlang/templates/shared-components/task-definitions/task-definitions._common.md

@@ -0,0 +1,62 @@
+---
+templateId: shared-components.task-definitions.common
+componentType: shared-component
+version: 1.0
+description: Canonical contract for Human Task definitions (approval and action types).
+---
+
+# Purpose
+Define human task shared components with explicit outcomes, participant resolution, completion actions, and details-page linking.
+
+# Required Inputs
+- task definition static ID and name
+- task type (`approval` or `action`)
+- details page target page and task-id item mapping
+- participant resolution query
+
+# Guardrails
+- Do not hardcode usernames.
+- Completion handling belongs in task actions.
+- Keep details-page linkage aligned with task-details page template family.
+- Treat successful APEX import behavior and proven imported task-definition artifacts in the active target app as higher authority than stale markdown examples.
+- Prefer the structured `advanced { detailsPage: { ... } }` object form used throughout this task-definition family. Do not default to a string `f?p=...` `detailsPage` value for new task definitions.
+- For ordinary approver/owner resolution, start with a minimal `participant ( value { ... } )` block. Add participant `type:` overrides only when the workflow explicitly needs special roles such as `businessAdministrator`.
+- Keep new task definitions minimal first: `name`, top-level `type`, `task { subject ... }`, optional `source { ... }`, `advanced { detailsPage: { ... } }`, and one or more `participant` blocks. Add `deadline`, `parameter`, and `action` blocks only when requirements call for them.
+
+# Proven Shape
+
+Use this baseline shape for new task definitions unless a proven imported example requires more:
+
+```apexlang
+taskDefinition TASK_NAME (
+    name: Task Name
+    type: approval
+    task {
+        subject: Task Subject
+    }
+    advanced {
+        detailsPage: {
+            page: 10
+            items: {
+                P10_TASK_ID: &TASK_ID.
+            }
+            clearCache: 10
+            action: resetPagination
+        }
+    }
+
+    participant (
+        value {
+            type: expression
+            plsqlExpression: some_package.get_participant(:APEX$TASK_PK)
+        }
+    )
+)
+```
+
+# Debugging Notes
+
+- If import succeeds but worksheet lint still raises `ORA-40441: JSON syntax error` on line 1 for a standalone `taskDefinition` file, treat the import-success path as authoritative and compare against imported task-definition artifacts in the active target app before changing the artifact.
+- If a new task definition fails import, compare it directly against:
+  - imported task-definition artifacts that already work in the same target app
+  - the structured `detailsPage` object form and minimal `participant` patterns shown in this family

package/skills/apexlang/templates/shared-components/task-definitions/task-definitions._index.md

@@ -0,0 +1,19 @@
+---
+templateId: task-definitions.index
+componentType: template
+version: 1.0
+imports:
+  - task-definitions._common.md
+description: Routing entrypoint for task-definitions templates.
+---
+
+# Purpose
+
+Primary routing entrypoint for `task-definitions` templates.
+
+# Load Order
+
+1. Load this file.
+2. Load `task-definitions._common.md`.
+3. Load one scenario template in this folder.
+4. When drafting or debugging a real task definition, inspect imported task-definition artifacts that already work in the active target app when such artifacts exist.

package/skills/apexlang/templates/shared-components/task-definitions/task-definitions.action-task.md

@@ -0,0 +1,9 @@
+---
+templateId: shared-components.task-definitions.action-task
+componentType: shared-component
+version: 1.0
+imports:
+  - task-definitions._common.md
+---
+
+Action-task variant for completion-driven manual operational tasks.

package/skills/apexlang/templates/shared-components/task-definitions/task-definitions.approve-request.md

@@ -0,0 +1,9 @@
+---
+templateId: shared-components.task-definitions.approve-request
+componentType: shared-component
+version: 1.0
+imports:
+  - task-definitions._common.md
+---
+
+Approval-task variant with explicit approve/reject outcomes and completion actions.

package/skills/apexlang/templates/shared-components/translations/translations._common.md

@@ -0,0 +1,31 @@
+---
+templateId: shared-components.translations.common
+componentType: shared-component
+version: 1.0
+description: Shared terminology and guardrails for APEX text-message translations.
+---
+
+# Purpose
+
+Standardize terminology and guardrails for text-message translation generation and usage.
+
+# Terminology
+
+- `textMessage`: shared translation entry authored in APEXlang.
+- `textMessage identifier`: the canonical message key after `textMessage`; reuse it across language variants of the same logical message.
+- `message.text`: nested runtime text payload inside the `message {}` block.
+- `message.language`: required language code inside the `message {}` block.
+- `message.usedInJavaScript`: optional JavaScript-consumption flag inside the `message {}` block.
+- `comments.comments`: optional builder note inside the `comments {}` block.
+- message-key substitution: component-side reference such as `&APP_TEXT$MESSAGE_KEY.`.
+
+# Guardrails
+
+- Use one canonical vocabulary everywhere: `textMessage`, `message.text`, `message.language`, `message.usedInJavaScript`, and `comments.comments`.
+- Keep the `textMessage` identifier stable across language variants.
+- Do not append locale or language suffixes to the `textMessage` identifier; use `message.language` as the only language discriminator for translated `textMessage` blocks.
+- For app/page localization workflows, user-facing component copy must be consumed through message-key substitutions backed by shared text messages.
+- Do not satisfy localization requests by inlining translated literals directly into labels, titles, help text, confirmations, breadcrumbs, static content, or similar user-facing component attributes when a shared text message should be used.
+- Omit optional fields rather than rendering empty placeholders.
+- Treat `comments.comments` as builder-only notes, never runtime copy.
+- Keep consumption examples focused on substitution usage; do not redefine the authoring contract there.

package/skills/apexlang/templates/shared-components/translations/translations._index.md

@@ -0,0 +1,50 @@
+---
+templateId: shared-components.translations.index
+componentType: shared-component
+version: 1.0
+imports:
+  - translations._common.md
+  - translations.text-messages._common.md
+description: Canonical entrypoint for APEX text-message translation authoring and consumption patterns.
+---
+
+# Purpose
+
+Document the complete APEX text-message translation flow in one family:
+- define `textMessage` entries
+- apply those message keys in component attributes
+
+# Load Order
+
+1. Load this file.
+2. Load `translations._common.md` for terminology and guardrails.
+3. Load `translations.text-messages._common.md` for the text-message authoring contract.
+4. Load the `.example.md` files in this folder only when you need concrete syntax patterns.
+
+# Canonical Files
+
+- `translations.text-messages._common.md` — required fields, optional fields, and output skeleton for text-message authoring.
+- `translations.text-messages.permutations.example.md` — representative message permutations across languages and field combinations.
+- `translations.text-messages.consumption.example.md` — examples showing how components reference shared text-message keys.
+- App/page localization runs emit `shared-components/messages.apx` and rewire user-facing component copy to substitutions such as `&APP_TEXT$KEY.`.
+
+# Compiler-Validated Shape
+
+- For full-application examples, use `app IDENTIFIER (` with a nested `name:` attribute, not `application (...)`.
+- The accepted `textMessage` structure is the nested form validated against APEX 26.1:
+  - `message { text: ... language: ... }`
+  - optional `message { usedInJavaScript: true }`
+  - optional `comments { comments: ... }`
+- Emit `message.text` as a direct scalar value. Do not wrap `message.text` in fenced ````text` blocks.
+- Do not use legacy top-level properties such as `staticId:` or a separate `attributes {}` block under `textMessage`.
+- Treat `translations.text-messages.permutations.example.md` as the concrete syntax reference for authoring examples.
+
+# Mental Model
+
+- `globalization { translationMethod: textMessages }` turns on text-message translation for the application.
+- Each `textMessage` block defines one localized value for a shared message key carried by the `textMessage` identifier itself.
+- Components consume those shared message keys through substitution strings such as `&APP_TEXT$MESSAGE_KEY.`.
+- Consumption examples belong to this family; they are not a separate translation subsystem.
+- Plain-language requests such as `translate my app` or `make this page available in another language` should resolve to this model: create or reuse shared text-message keys, generate language variants, and rewire component text to substitutions.
+- They must not be implemented by replacing component attributes with direct translated literals.
+- Direct translated literals left in component attributes are a failed localization outcome.

package/skills/apexlang/templates/shared-components/translations/translations.text-messages._common.md

@@ -0,0 +1,80 @@
+---
+templateId: shared-components.translations.text-messages.common
+componentType: shared-component
+version: 1.0
+imports:
+  - translations._common.md
+description: Canonical shared contract for authoring APEX text-message translations.
+---
+
+# Purpose
+
+Define the variable contract and output skeleton for APEX applications that use `translationMethod: textMessages`.
+For app/page localization runs, the generated text-message artifact is `shared-components/messages.apx`.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| application.name | yes | string | Application label rendered inside the top-level `app` block as the `name:` attribute. |
+| application.alias | yes | string | Application identifier rendered after the `app` keyword. Use uppercase letters, digits, and underscores only. |
+| application.translationMethod | yes | enum | Always `textMessages`. |
+| messageBlocks | yes | list | One or more `textMessage` blocks. |
+| messageBlocks[].staticId | yes | string | Canonical message identifier rendered after the `textMessage` keyword. Reuse across languages for the same logical message. |
+| messageBlocks[].message.text | yes | string | Message content. This is the translatable payload and must render as a direct scalar `text: "..."` value inside the nested `message {}` block. |
+| messageBlocks[].attributes.language | yes | string | Required language code for every message block, including the primary language. Render it as `language:` inside the nested `message {}` block. |
+| messageBlocks[].attributes.usedInJavaScript | optional | boolean | Render it as `usedInJavaScript:` inside the nested `message {}` block only when the message is intended for `apex.lang.*` use in JavaScript. |
+| messageBlocks[].comments.comments | optional | string or text block | Builder-only notes. Render inside the nested `comments {}` block. |
+
+---
+
+# Output Template – Full
+
+```apex
+app {{application.alias}} (
+    name: {{application.name}}
+    globalization {
+        translationMethod: textMessages
+    }
+)
+
+{{messageBlocks}}
+```
+
+```apex
+textMessage {{messageBlocks[].staticId}} (
+    message {
+        text: "{{messageBlocks[].message.text}}"
+        language: {{messageBlocks[].attributes.language}}
+        usedInJavaScript: {{messageBlocks[].attributes.usedInJavaScript}}
+    }
+    comments {
+        comments:
+            ```text
+            {{messageBlocks[].comments.comments}}
+            ```
+    }
+)
+```
+
+---
+
+# Authoring Rules
+
+- Keep output variable-driven with `{{...}}` placeholders only; do not embed fixed sample values in the markdown contract.
+- Expand `{{messageBlocks}}` into one or more `textMessage` blocks.
+- Use the compiler-valid `app IDENTIFIER (...)` form for any top-level application wrapper examples.
+- Render `globalization { translationMethod: textMessages }` when the application is explicitly using text-message translation.
+- Emit the text-message payload into `shared-components/messages.apx` for app/page localization runs.
+- Render `message.text` as a direct scalar value such as `text: "Save changes"`. Do not emit fenced ````text` blocks for `message.text`.
+- Render `message.language` explicitly for every variant, including the primary language.
+- Omit `message.usedInJavaScript` when false or not required.
+- Omit the `comments {}` block when no builder note is needed.
+- Keep the leading `textMessage` identifier stable for every language variant of the same logical message.
+- Do not append the locale to the `textMessage` identifier. Language-specific variants must share one canonical message key and differ only by `message.language`.
+- Use fenced text blocks only for `comments.comments` when multiline builder notes are needed.
+- Do not add export-only internals such as `reference_id` or `version_scn`.
+- Keep this contract focused on text-message authoring; translation application mappings and dynamic translations are out of scope.
+- Do not treat direct translated literals in component attributes as acceptable localization output.

package/skills/apexlang/templates/shared-components/translations/translations.text-messages.consumption.example.md

@@ -0,0 +1,69 @@
+---
+templateId: shared-components.translations.translations.text-messages.consumption.example
+componentType: markdown-apexlang-example
+version: 1.0
+migrationNote: preserved from previous standalone template example
+---
+
+# Translations.Text Messages.Consumption Example
+
+## Purpose
+
+Markdown-preserved APEXlang example. Use this file for syntax and structure only after loading the family `_index.md` and `_common.md` contract.
+
+## Example
+
+```apexlang
+// Template: Consume Text Messages in Components
+// Purpose: Replace hard-coded page and component text with shared text-message keys.
+// Usage: Copy relevant sections and substitute page numbers, static IDs, item names, and message keys.
+
+page 42 (
+    name: &APP_TEXT$MESSAGE_KEY_PAGE_NAME.
+    title: &APP_TEXT$MESSAGE_KEY_PAGE_TITLE.
+
+    help {
+        helpText: &APP_TEXT$MESSAGE_KEY_PAGE_HELP.
+    }
+
+    region REGION_STATIC_ID (
+        name: &APP_TEXT$MESSAGE_KEY_REGION_TITLE.
+        type: staticContent
+        source {
+            htmlCode:
+                ```html
+                <p>&APP_TEXT$MESSAGE_KEY_REGION_BODY.</p>
+                <p class="u-muted">&APP_TEXT$MESSAGE_KEY_REGION_FOOTNOTE.</p>
+                ```
+        }
+        help {
+            helpText: &APP_TEXT$MESSAGE_KEY_REGION_HELP.
+        }
+    )
+
+    region ORDERS_REPORT (
+        name: &APP_TEXT$MESSAGE_KEY_REPORT_TITLE.
+        type: classicReport
+        messages {
+            whenNoDataFound: &APP_TEXT$MESSAGE_KEY_NO_DATA.
+        }
+    )
+)
+
+pageItem P42_TEXTFIELD (
+    type: textField
+    label {
+        label: &APP_TEXT$MESSAGE_KEY_ITEM_LABEL.
+    }
+    help {
+        helpText: &APP_TEXT$MESSAGE_KEY_ITEM_HELP.
+    }
+)
+
+button SAVE (
+    label: &APP_TEXT$MESSAGE_KEY_BUTTON_LABEL.
+    confirmation {
+        message: &APP_TEXT$MESSAGE_KEY_BUTTON_CONFIRM.
+    }
+)
+```

package/skills/apexlang/templates/shared-components/translations/translations.text-messages.permutations.example.md

@@ -0,0 +1,81 @@
+---
+templateId: shared-components.translations.translations.text-messages.permutations.example
+componentType: markdown-apexlang-example
+version: 1.0
+migrationNote: preserved from previous standalone template example
+---
+
+# Translations.Text Messages.Permutations Example
+
+## Purpose
+
+Markdown-preserved APEXlang example. Use this file for syntax and structure only after loading the family `_index.md` and `_common.md` contract.
+
+## Example
+
+```apexlang
+app TEXT_MESSAGE_PERMUTATIONS (
+    name: Text Message Translation Permutations
+    globalization {
+        translationMethod: textMessages
+    }
+)
+
+textMessage PAGE_42_TITLE (
+    message {
+        text: "Operations Console"
+        language: en
+    }
+)
+
+textMessage PAGE_42_TITLE (
+    message {
+        text: "オペレーションコンソール"
+        language: ja
+    }
+)
+
+textMessage REPORT_NO_DATA (
+    message {
+        text: "No matching work items were found."
+        language: en
+    }
+)
+
+textMessage REPORT_NO_DATA (
+    message {
+        text: "一致する作業項目は見つかりませんでした。"
+        language: ja
+    }
+)
+
+textMessage SAVE_ACTION (
+    message {
+        text: "Save changes"
+        language: en
+        usedInJavaScript: true
+    }
+)
+
+textMessage SAVE_ACTION (
+    message {
+        text: "変更を保存"
+        language: ja
+        usedInJavaScript: true
+    }
+)
+
+textMessage GREETING_WITH_SUBSTITUTION (
+    message {
+        text: "Hello %0, you have %1 pending tasks."
+        language: en
+    }
+)
+
+textMessage GREETING_WITH_SUBSTITUTION (
+    message {
+        text: "こんにちは %0 さん。保留中のタスクが %1 件あります。"
+        language: ja
+    }
+)
+```

package/skills/apexlang/templates/template-components/README.md

@@ -0,0 +1,57 @@
+# Template Components Templates
+
+## Purpose
+Catalog of canonical markdown-first template-component families and their routing entrypoints.
+
+## Usage
+- Load the primary markdown contract or index in the relevant family directory before selecting scenario details.
+- Choose a scenario variant matching the requested display mode, interaction pattern, and composition context.
+- Use the dedicated owner `*_template_options.md` file when the request changes helper/template-component plugin attributes or settings.
+- When a row includes `values=`, pass the left-hand side of each `name=>return_value` pair, not the emitted CSS or return token.
+- Use `template-components.registry.json` for tooling discovery and preserve markdown-first conventions when updating workflow or registry links.
+- For report-type template components, use explicit child `column (...)` structures by default and keep them aligned with the delivered region source projection.
+  This default applies to Content Row, Metric Card, Media List, and Comments. Do not satisfy the compiler by adding only one placeholder child column when the source projects multiple fields.
+- For any template component that emits `rowSelection` with a non-null mode, mark one child column as the identity column with `source.primaryKey: true`.
+
+## Template Catalog
+- `actions/`
+- `button/`
+- `content-row/`
+- `metric-card/`
+- `avatar._template_options.md`
+- `badge._template_options.md`
+- `comments._template_options.md`
+- `flexbox-container._template_options.md`
+- `media-list._template_options.md`
+- `timeline._template_options.md`
+- `template-components.registry.json`
+
+## Maintenance
+- Keep this README synchronized with actual files in the directory.
+- Update catalogs and usage notes whenever template families are added, removed, or renamed.
+- Keep family guidance aligned with page-level standards in memory-bank rules and with scenario coverage in this folder.
+
+## Template Option Ownership
+
+These inventories come from `create_plugin_attribute` and `create_plugin_attr_value`, not from `wwv_flow_template_options`.
+
+- `actions/actions._template_options.md`
+  - Owns `actions`
+- `button/button._template_options.md`
+  - Owns `button`
+- `content-row/content-row._template_options.md`
+  - Owns `contentRow`
+- `metric-card/metric-card._template_options.md`
+  - Owns `metricCard`
+- `avatar._template_options.md`
+  - Owns shared `avatar` settings used by multiple template components
+- `badge._template_options.md`
+  - Owns shared `badge` settings used by multiple template components
+- `comments._template_options.md`
+  - Owns `comments`
+- `flexbox-container._template_options.md`
+  - Owns `flexboxContainer`
+- `media-list._template_options.md`
+  - Owns `mediaList`
+- `timeline._template_options.md`
+  - Owns `timeline`