pi-apexlang 0.1.0

package/skills/apexlang/templates/region-components/chart/chart.stock.md

@@ -0,0 +1,52 @@
+---
+templateId: region.chart.stock
+componentType: region
+version: 1.0
+imports:
+  - chart._common.md
+  - chart._series._common.md
+  - chart._axis._common.md
+description: Stock chart scenario with variable-driven OHLC series and axis contracts.
+---
+
+# Purpose
+
+Variable-driven stock chart scenario with configurable overview and zoom behavior.
+
+---
+
+# Output Template – Full
+
+```apexlang
+region {{chartRegion.staticId}} (
+  name: {{chartRegion.name}}
+  type: chart
+  layout {
+    sequence: {{layout.sequence}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    template: {{appearance.template}}
+    templateOptions: {{appearance.templateOptions}}
+  }
+  chart {
+    type: {{chart.type}}
+    initialZooming: {{chart.initialZooming}}
+    {{chart.options}}
+  }
+  legend {
+    {{legend}}
+  }
+
+  {{seriesBlocks}}
+
+  {{axisBlocks}}
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Render `{{seriesBlocks}}` using `chart._series._common.md`.
+- Render `{{axisBlocks}}` using `chart._axis._common.md`.

package/skills/apexlang/templates/region-components/chart/config/README.md

@@ -0,0 +1,19 @@
+# Chart Configuration Templates
+
+## Purpose
+This directory is reserved for chart configuration modules that may be added under the chart template family.
+
+## What is in this directory
+
+- No chart configuration module files are currently present.
+- The parent chart family lives in `templates/region-components/chart/`.
+
+## How to use this directory
+
+- Do not load this directory by default.
+- Only add or load files here when a chart scenario needs reusable configuration modules that do not belong in the top-level chart variants or feature files.
+- Use the parent chart README as the main guide for the chart family.
+
+## Maintenance
+- If configuration modules are added later, list them here and explain when to use them.
+- If this directory remains intentionally empty long-term, keep that fact explicit so readers do not assume files are missing.

package/skills/apexlang/templates/region-components/chart/features/chart.feature-3d-effect.md

@@ -0,0 +1,36 @@
+---
+
+templateId: chart.feature.3d-effect
+componentType: chart-feature
+version: 1.0
+imports:
+  - ../chart._common.md
+description: Adds drop shadow and bar gap to simulate a 3D effect on column/bar charts.
+---
+
+# Purpose
+
+
+# Example Snippet
+
+```apexlang
+chartAppearance {
+    shadow {
+        color: #000000
+        offsetX: 4
+        offsetY: 4
+        opacity: 0.4
+    }
+    gapRatio: 0.4
+}
+```
+
+# Usage Notes
+
+- Apply inside the target chart region after selecting a compatible chart type (bar/column/combination).
+- Tune `offsetX`, `offsetY`, and `opacity` to balance the effect with your theme.
+- Remove the block entirely for flatter presentation when accessibility or clarity would suffer.
+
+# References
+
+- Related module: `charts/config/config-data-label-formatting.md`

package/skills/apexlang/templates/region-components/chart/features/chart.feature-chart-links.md

@@ -0,0 +1,53 @@
+---
+templateId: chart.feature.chart-links
+componentType: chart-feature
+version: 1.0
+imports:
+  - ../chart._common.md
+description: Adds link targets to chart data points using SQL-generated URLs.
+---
+
+# Purpose
+
+
+# Usage
+
+1. Add a SQL column that returns the desired URL (e.g., `apex_page.get_url`).
+2. Map the column through `columnMapping.link`.
+3. Ensure navigation targets respect security (checksums, authorization).
+
+# Example Snippet
+
+```apexlang
+series FEATURE_CHART_LINKS (
+    name: Sales
+
+    source {
+        type: sqlQuery
+        sqlQuery:
+            ```sql
+            select product_name,
+                   sum(quantity) total_quantity,
+                   apex_page.get_url(p_page => 10,
+                                      p_items => 'P10_PRODUCT',
+                                      p_values => product_name) as detail_link
+              from eba_demo_chart_orders
+             group by product_name
+            ```
+    }
+
+    columnMapping {
+        label: PRODUCT_NAME
+        value: TOTAL_QUANTITY
+        link: DETAIL_LINK
+    }
+)
+```
+
+# Notes
+
+- When linking to other applications, ensure appropriate authorization schemes and session handling.
+- Combine with region actions (refresh, modal launch) to keep navigation consistent with UX guidelines.
+
+# References
+

package/skills/apexlang/templates/region-components/chart/features/chart.feature-combination.md

@@ -0,0 +1,78 @@
+---
+templateId: chart.feature.combination
+componentType: chart-feature
+version: 1.0
+imports:
+  - ../chart._common.md
+description: Mixes bar, area, and line series within a combination chart region.
+---
+
+# Purpose
+
+
+# Usage
+
+- Apply this pattern when demonstrating how multiple chart series types can be displayed together.
+- Pair with `chart._common.md` for guardrails and with `chart-dashboard-combination.md` for full region context.
+
+# Example Snippet
+
+```apexlang
+region FEATURE_COMBINATION (
+    name: Combination Chart (Bar + Line + Area)
+    type: chart
+
+    layout {
+        sequence: 10
+        slot: BODY
+    }
+
+    appearance {
+        template: @/standard
+        templateOptions: [
+            #DEFAULT#
+            t-Region--scrollBody
+        ]
+    }
+
+    chart {
+        type: combination
+    }
+
+    series FEATURE_AREA (
+        name: Area Series
+        type: area
+        columnMapping {
+            label: LABEL
+            value: AREA_VAL
+        }
+    )
+
+    series FEATURE_BAR (
+        name: Bar Series
+        type: bar
+        columnMapping {
+            label: LABEL
+            value: BAR_VAL
+        }
+    )
+
+    series FEATURE_LINE (
+        name: Line Series
+        type: line
+        columnMapping {
+            label: LABEL
+            value: LINE_VAL
+        }
+    )
+)
+```
+
+# Notes
+
+- Ensure each series specifies its type (`type: area|bar|line`).
+- Adjust ordering and legend entries to match UX requirements.
+
+# References
+
+- Related scenario – `chart-dashboard-combination.md`

package/skills/apexlang/templates/region-components/chart/features/chart.feature-custom-tooltip.md

@@ -0,0 +1,34 @@
+---
+
+/*
+  Chart Feature: Customizing Tooltip Labels
+  Highlights
+  - Uses `series.labelTooltip` to show formatted values.
+  - Demonstrates tooltip text controlled by SQL columns.
+*/
+
+series FEATURE_CUSTOM_TOOLTIP (
+  name: Orders
+
+  source {
+    type: sqlQuery
+    sqlQuery:
+      ```sql
+      select product_name,
+             quantity,
+             to_char(quantity, '999,990') as tooltip_text
+        from eba_demo_chart_orders
+       where customer = 'Acme Store'
+      ```
+  }
+
+  columnMapping {
+    label: PRODUCT_NAME
+    value: QUANTITY
+    labelTooltip: TOOLTIP_TEXT
+  }
+
+  label {
+    show: true
+  }
+)

package/skills/apexlang/templates/region-components/chart/features/chart.feature-data-densification.md

@@ -0,0 +1,40 @@
+---
+
+/*
+  Chart Feature: Data Densification with Window Function
+  Highlights
+  - Demonstrates filling gaps in time series using analytic functions.
+  - Returns zero rows with generated dates for missing periods.
+*/
+
+series FEATURE_DATA_DENSIFICATION (
+  name: Orders by Month
+
+  source {
+    type: sqlQuery
+    sqlQuery:
+      ```sql
+      with monthly_sales as (
+        select trunc(order_date, 'MM') month_start,
+               sum(order_total)        sales
+          from eba_demo_chart_orders
+         group by trunc(order_date, 'MM')
+      ),
+      range_of_months as (
+        select add_months(min(month_start), level - 1) as month_start
+          from monthly_sales
+       connect by level <= months_between(max(month_start), min(month_start)) + 1
+      )
+      select r.month_start,
+             nvl(m.sales, 0) sales
+        from range_of_months r
+        left join monthly_sales m on m.month_start = r.month_start
+       order by 1
+      ```
+  }
+
+  columnMapping {
+    label: MONTH_START
+    value: SALES
+  }
+)

package/skills/apexlang/templates/region-components/chart/features/chart.feature-declarative-font.md

@@ -0,0 +1,29 @@
+---
+
+/*
+  Chart Feature: Declarative Font Formatting
+  Highlights
+  - Uses declarative label formatting to adjust font family, size, and color.
+  - Keeps axis metadata on the canonical contract while formatting data labels without custom JS.
+*/
+
+label FEATURE_FONT_LABEL (
+  show: true
+  position: insideBarEdge
+  fontSize: 18
+  fontFamily: "Times New Roman"
+  fontColor: #0B3D91
+)
+
+axis FEATURE_FONT_AXIS_Y (
+  name: y
+  title: Sales
+  value {
+    format: decimal
+    decimalPlaces: 0
+    formatScaling: none
+  }
+  majorTicks {
+    show: true
+  }
+)

package/skills/apexlang/templates/region-components/chart/features/chart.feature-legend-plug-in.md

@@ -0,0 +1,55 @@
+---
+
+/*
+  Chart Feature: Legend Plug-in for Shared Series
+  Highlights
+  - Integrates Oracle JET Legend plug-in to show series across multiple charts.
+  - Legend rows filter linked charts by matching series names.
+  - Charts hide their built-in legend to rely on the shared plug-in.
+*/
+
+region FEATURE_LEGEND_PLUGIN (
+  name: Legend
+  type: plugin/APEXLANG$3677104480606292197
+
+  layout {
+    sequence: 10
+    slot: BODY
+  }
+
+  source {
+    sqlQuery:
+      ```sql
+      select distinct customer,
+             'Filter: ' || customer description
+        from eba_demo_chart_orders
+       order by customer
+      ```
+  }
+
+  appearance {
+    template: @/standard
+    templateOptions: [
+      #DEFAULT#
+      t-Region--hideHeader js-addHiddenHeadingRoleDesc
+      t-Region--noUI
+      t-Region--scrollBody
+      t-Form--noPadding
+      margin-top-none
+      margin-bottom-sm
+      margin-left-none
+      margin-right-none
+    ]
+  }
+
+  advanced {
+    customAttributes: "style=\"width:100%; height:100px;\""
+  }
+
+  settings {
+    APEXLANG$3677104673964292202: APEXLANG$3677105068779292203
+    APEXLANG$3677106042803292204: APEXLANG$3677106420707292204
+  }
+)
+
+/* Linked charts share identical series names and set legend.show: false */

package/skills/apexlang/templates/region-components/chart/features/chart.feature-series-color.md

@@ -0,0 +1,43 @@
+---
+
+/*
+  Chart Feature: Series Color via SQL
+  Highlights
+  - Sets slice colors using a SQL column alias.
+  - Keeps legend synchronized by referencing the alias in `appearance.color`.
+*/
+
+series FEATURE_SERIES_COLOR (
+  name: Products
+
+  source {
+    type: sqlQuery
+    sqlQuery:
+      ```sql
+      select product_name,
+             list_price,
+             case product_name
+               when 'Apples'    then 'green'
+               when 'Bananas'   then 'yellow'
+               when 'Grapes'    then 'purple'
+               when 'Cantaloupe'then 'orange'
+               when 'Dates'     then '#791b19'
+             end as series_color
+        from eba_demo_chart_products
+      ```
+  }
+
+  columnMapping {
+    label: PRODUCT_NAME
+    value: LIST_PRICE
+  }
+
+  appearance {
+    color: &SERIES_COLOR.
+  }
+
+  label {
+    show: true
+    position: outsideSlice
+  }
+)

package/skills/apexlang/templates/region-components/chart/features/chart.feature-zoom-scroll.md

@@ -0,0 +1,30 @@
+---
+
+/*
+  Chart Feature: Zoom and Scroll Behavior
+  Highlights
+  - Enables zoom and scroll with delayed redraw for smoother UX.
+  - Shows overview pane to provide context while zoomed.
+*/
+
+chart FEATURE_ZOOM_SCROLL (
+  type: line
+)
+
+chartLayout {
+  height: 400
+}
+
+settings {
+  zoomAndScroll: delayed
+  initialZooming: first
+}
+
+overview {
+  show: true
+}
+
+dataCursor {
+  cursor: true
+  behavior: smooth
+}

package/skills/apexlang/templates/region-components/classic-report/README.md

@@ -0,0 +1,32 @@
+# Classic Report Templates
+
+## Purpose
+Canonical guidance for the `classic-report` region family, including shared contract loading and supported scenario variants.
+
+## Usage
+- Load `classic-report._common.md` first to align variable contracts, guardrails, and required inputs.
+- Load `classic-report._columns._common.md` for the canonical column contract used by all classic-report variants.
+- Use `classic-report._columns.format-template.md` for formatting rules and reference examples when choosing column masks/alignment.
+- Classic Report regions must emit both `appearance { template: @/standard ... }` for the region wrapper and `componentAppearance { template: @/standard ... }` for the report component template unless a scenario documents a wrapper override.
+- Contextual Info Classic Reports use `appearance.template: @/contextual-info` with `templateOptions` exactly `#DEFAULT#`, `t-Region--hideHeader js-addHiddenHeadingRoleDesc`, and `t-Region--noUI`.
+- Default Classic Report component template options are `#DEFAULT#`, `t-Report--stretch`, and `t-Report--horizontalBorders`. Do not emit alternating-row tokens (`t-Report--altRowsDefault` or `t-Report--staticRowColors`) or row highlight by default.
+- 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
+- `classic-report._common.md`
+- `classic-report._columns._common.md`
+- `classic-report._columns.format-template.md`
+- `classic-report.ao-notifications.md`
+- `classic-report.context-info-column-based.md`
+- `classic-report.contextual-info-row-based.md`
+- `classic-report.percent-graph-columns.md`
+- `classic-report.rest-data-source-and-query-param.md`
+- `classic-report.rest-data-source.md`
+- `classic-report.standard.md`
+- `classic-report.suggestions-simple-list.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/classic-report/classic-report._columns._common.md

@@ -0,0 +1,160 @@
+---
+templateId: region.classic-report.columns.common
+componentType: region
+version: 1.0
+description: Shared column contract for classic report regions.
+---
+
+# Purpose
+
+Standardize `column` variable contracts, output shape, and guardrails for all classic-report variants.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `classic-report._common.md` before using this columns contract.
+2. Align each column with the SQL projection order and data semantics.
+3. Omit optional nested blocks when their variables are not provided.
+4. Emit each column as a multiline child block; never collapse `layout { sequence: ... }` onto one line.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| column.name | yes | string | Column static identifier. |
+| column.reportColumnQueryId | yes | number | Must map to SQL projection position. |
+| column.derivedColumn | yes | enum | Usually `N` unless derived. |
+| column.type | optional | enum | `plainText`, `plainTextBasedOnLov`, `richText`, `link`, `image`, `downloadBlob`, `hidden`, `percentGraph`. Required as `link` when a column-level `link {}` block is emitted. |
+| column.heading | optional | string | Heading text shown to users. Omit it entirely when `column.type: hidden`. |
+| column.headingAlignment | optional | enum | `start`, `center`, `end`. |
+| column.sequence | yes | number | Display order. |
+| column.columnAlignment | optional | enum | `start`, `center`, `end`. |
+| column.formatMask | optional | string | Numeric/date formatting mask. |
+| column.columnFormatting.htmlExpression | optional | string | Column-level HTML rendering expression for presentation formatting. |
+| column.settings.format | optional | enum | Optional text formatting metadata when a non-default column type requires it. |
+| column.comments | required by default | string | Descriptive metadata string for `comments { comments: ... }` on business-significant, derived, status, and action columns; include the required attributes `Display Label`, `Display in Report`, `Display in Form`, `Format Mask`, `Value Required`, `Read Only`, `Primary Display Column`, and `Authorization Scheme`, with optional leading `Summary`. |
+| column.security.authorizationScheme | optional | string | Existing authorization alias. |
+| column.link.target | optional | object or string | For same-application links, use a declarative target object with `page`, `items`, and `clearCache`. In `target.items`, use `#COLUMN_ALIAS#` for current report-row values and `&ITEM.` only for page/app/session substitutions. Use string URLs only for explicit URL mode or component families that require URL strings. |
+| column.link.linkText | optional | string | Link label/substitution text. |
+| column.link.linkAttributes | optional | string | HTML attributes for rendered link. |
+| column.lov.type | optional | enum | LOV type for `plainTextBasedOnLov`. |
+| column.lov.sharedComponent | optional | string | Existing shared LOV alias. |
+| column.appearance.backgroundColor | optional | color | Percent graph background color. |
+| column.appearance.foregroundColor | optional | color | Percent graph foreground color. |
+| column.sorting.defaultSequence | optional | number | Default sort order for classic report column. |
+
+---
+
+# Output Template – Full
+
+```apexlang
+column {{column.name}} (
+  reportColumnQueryId: {{column.reportColumnQueryId}}
+  derivedColumn: {{column.derivedColumn}}
+  type: {{column.type}}
+  heading {
+    heading: {{column.heading}}
+    alignment: {{column.headingAlignment}}
+  }
+  layout {
+    sequence: {{column.sequence}}
+    columnAlignment: {{column.columnAlignment}}
+  }
+  appearance {
+    formatMask: {{column.formatMask}}
+    backgroundColor: {{column.appearance.backgroundColor}}
+    foregroundColor: {{column.appearance.foregroundColor}}
+  }
+  columnFormatting {
+    htmlExpression: {{column.columnFormatting.htmlExpression}}
+  }
+  settings {
+    format: {{column.settings.format}}
+  }
+  comments {
+    comments: {{column.comments}}
+  }
+  security {
+    authorizationScheme: @{{column.security.authorizationScheme}}
+  }
+  link {
+    target: {
+      page: {{column.link.target.page}}
+      items: {
+        {{column.link.target.items}}
+      }
+      clearCache: {{column.link.target.clearCache}}
+    }
+    linkText: {{column.link.linkText}}
+    linkAttributes: {{column.link.linkAttributes}}
+  }
+  lov {
+    type: {{column.lov.type}}
+    lov: @{{column.lov.sharedComponent}}
+  }
+
+Example report-row item mapping:
+
+```apexlang
+  link {
+    target: {
+      page: 15
+      items: {
+        P15_PRODUCT_ID: #PRODUCT_ID#
+        P15_MODE: &P1_MODE.
+      }
+      clearCache: 15
+    }
+    linkText: View
+  }
+```
+  sorting {
+    defaultSequence: {{column.sorting.defaultSequence}}
+  }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Omit `type` when default rendering is sufficient.
+- Do not omit `type: link` when a Classic Report column emits a column-level `link {}` block.
+- Omit `heading.alignment` and `layout.columnAlignment` when alignment is not specified.
+- Do not omit the `layout` block or `layout.sequence`; the live compiler requires explicit column ordering.
+- Omit `appearance` unless one or more of `formatMask`, `backgroundColor`, `foregroundColor` is provided.
+- Omit `columnFormatting` when no HTML rendering expression is required.
+- Omit `settings` unless `column.settings.format` is provided.
+- Do not emit a `source` block for classic-report columns in this runtime; keep source metadata in the region SQL and the column contract blocks above.
+- Omit `comments` only for hidden technical columns or when a documented exemption applies.
+- Omit `security` when column-level authorization is not required.
+- Omit `link` unless column type is `link` or link behavior is explicitly requested.
+- For same-application column links, render `link.target` as a declarative object. Do not use scalar `f?p=...` or SQL-generated `apex_page.get_url(...)` unless URL mode is explicitly selected.
+- Omit `lov` unless using `plainTextBasedOnLov`.
+- Omit `sorting` unless default sorting is explicitly requested.
+- Omit `heading` when the `type` is `hidden`.
+- For visible Classic Report columns, keep explicit headings and make the PK decision explicit: declarative navigation when row navigation is intended, otherwise hidden technical PK handling.
+
+---
+
+# Guardrails
+
+- `column.reportColumnQueryId` must remain synchronized with SQL projection order.
+- Keep `layout.sequence` as a multiline nested block on every generated column.
+- Keep `column.type` compatible with classic-report supported types.
+- When a Classic Report column contains `link {}`, emit top-level `type: link`; a link block without the matching column type is invalid generated output.
+- Do not emit `source { databaseColumn: ... dataType: ... }` on classic-report columns in this runtime; that shape belongs to other column families such as interactive grid or template-driven columns.
+- Hidden Classic Report columns must not emit `heading {}`; keep this rule separate from Interactive Report, where hidden columns still require headings.
+- Use only existing authorization schemes and LOV aliases.
+- When `comments` is emitted, keep it as a single string literal inside `comments { comments: ... }`.
+- Emit `comments { comments: ... }` by default for business-significant, derived, status, and action columns instead of treating the block as opt-in metadata.
+- The required attributes are `Display Label`, `Display in Report`, `Display in Form`, `Format Mask`, `Value Required`, `Read Only`, `Primary Display Column`, and `Authorization Scheme`.
+- Include `Summary` only when a short leading business-intent sentence materially helps maintenance.
+- When `Summary` is present, keep the stable order `Summary`, `Display Label`, `Display in Report`, `Display in Form`, `Format Mask`, `Value Required`, `Read Only`, `Primary Display Column`, `Authorization Scheme`.
+- Mirror executable settings such as `appearance.formatMask` and `security.authorizationScheme` when those blocks are emitted.
+- When using `columnFormatting.htmlExpression`, do not emit `type: richText`.
+- For `columnFormatting.htmlExpression`, leave plain text type implicit unless a non-default type is required.
+- Keep report SQL data-only; emit presentation markup only through `columnFormatting.htmlExpression` per `references/policies/memory-bank/30-pages/apex.report-column-rendering.md`.