pi-apexlang 0.2.2 → 0.4.0

package/skills/apexlang/templates/region-components/map/map.region.background-custom.md

@@ -21,19 +21,19 @@ Document the region-level background path where `tileLayerType` uses the built-i
 - `name`
 - `layout.sequence`
 - `layout.slot`
-- `tileLayerType` (use `custom`)
-- `standardTileLayer`
+- `map.background` (use `builtIn`)
+- `map.standard`
 
 ## Optional Variables
 
-- `darkModeTileLayer`
+- `map.darkMode`
 - `map.height`
-- `navigationBarType`
-- `navigationBarPosition`
-- `mapFeatures`
-- `showLegend`
-- `legendPosition`
-- `lazyLoading`
+- `controls.navigationBar`
+- `controls.navigationBarPosition`
+- `controls.options`
+- `legend.show`
+- `legend.position`
+- `performance.lazyLoading`
 
 ---
 
@@ -44,21 +44,27 @@ region {{regionStaticId}} (
   name: {{name}}
   type: map
   map {
+    background: builtIn
+    standard: {{map.standard}}
+    darkMode: {{map.darkMode}}
     height: {{map.height}}
   }
   layout {
     sequence: {{layout.sequence}}
     slot: {{layout.slot}}
   }
-  tileLayerType: custom
-  standardTileLayer: {{standardTileLayer}}
-  darkModeTileLayer: {{darkModeTileLayer}}
-  navigationBarType: {{navigationBarType}}
-  navigationBarPosition: {{navigationBarPosition}}
-  mapFeatures: {{mapFeatures}}
-  showLegend: {{showLegend}}
-  legendPosition: {{legendPosition}}
-  lazyLoading: {{lazyLoading}}
+  controls {
+    navigationBar: {{controls.navigationBar}}
+    navigationBarPosition: {{controls.navigationBarPosition}}
+    options: {{controls.options}}
+  }
+  legend {
+    show: {{legend.show}}
+    position: {{legend.position}}
+  }
+  performance {
+    lazyLoading: {{performance.lazyLoading}}
+  }
 )
 ```
 
@@ -66,6 +72,6 @@ region {{regionStaticId}} (
 
 # Guardrails
 
-- `tileLayerType: custom` selects built-in standard and dark-mode background names, not shared `mapBackground` components.
+- `map.background: builtIn` selects built-in standard and dark-mode background names, not shared `mapBackground` components.
 - The app/plugin attribute `useVectorTileLayers` still separately controls whether supported built-in backgrounds use vector tile layers behind the scenes.
 - Load `map.backgrounds.md` only when the request uses shared backgrounds instead of built-in background names.

package/skills/apexlang/templates/region-components/map/map.region.background-shared.md

@@ -22,16 +22,16 @@ Document the region-level background path where `tileLayerType` uses shared `map
 - `name`
 - `layout.sequence`
 - `layout.slot`
-- `tileLayerType` (use `shared`)
-- `standardTileLayer`
+- `map.background` (use `sharedComponent`)
+- `map.standard`
 
 ## Optional Variables
 
-- `darkModeTileLayer`
+- `map.darkMode`
 - `map.height`
-- `mapFeatures`
-- `showLegend`
-- `lazyLoading`
+- `controls.options`
+- `legend.show`
+- `performance.lazyLoading`
 
 ---
 
@@ -42,18 +42,24 @@ region {{regionStaticId}} (
   name: {{name}}
   type: map
   map {
+    background: sharedComponent
+    standard: @{{map.standard}}
+    darkMode: @{{map.darkMode}}
     height: {{map.height}}
   }
   layout {
     sequence: {{layout.sequence}}
     slot: {{layout.slot}}
   }
-  tileLayerType: shared
-  standardTileLayer: @{{standardTileLayer}}
-  darkModeTileLayer: @{{darkModeTileLayer}}
-  mapFeatures: {{mapFeatures}}
-  showLegend: {{showLegend}}
-  lazyLoading: {{lazyLoading}}
+  controls {
+    options: {{controls.options}}
+  }
+  legend {
+    show: {{legend.show}}
+  }
+  performance {
+    lazyLoading: {{performance.lazyLoading}}
+  }
 )
 ```
 
@@ -61,6 +67,6 @@ region {{regionStaticId}} (
 
 # Guardrails
 
-- `standardTileLayer` and `darkModeTileLayer` must reference existing `mapBackground` shared components.
+- `map.standard` and `map.darkMode` must reference existing `mapBackground` shared components.
 - Use `map.backgrounds.md` for API-key, WMS, raster, and vector background-specific guidance.
 - Shared backgrounds are the correct path when the request needs custom hosted tiles or shared reuse across multiple regions.

package/skills/apexlang/templates/region-components/map/map.region.bbox-sql.md

@@ -27,12 +27,12 @@ Document SQL-derived bounding-box authoring for map regions.
 
 ## Optional Variables
 
-- `boundingBox.sdoGeometryColumn`
-- `boundingBox.minLongitudeColumn`
-- `boundingBox.minLatitudeColumn`
-- `boundingBox.maxLongitudeColumn`
-- `boundingBox.maxLatitudeColumn`
-- `mapStatusItem`
+- `boundingBox.geometryColumn`
+- `boundingBox.minLongitude`
+- `boundingBox.minLatitude`
+- `boundingBox.maxLongitude`
+- `boundingBox.maxLatitude`
+- `boundingBox.currentBoundsItem`
 
 ---
 
@@ -53,13 +53,13 @@ region {{regionStaticId}} (
     {{boundingBox.sqlQuery}}
     ```
     geometryColumnDataType: {{boundingBox.geometryColumnDataType}}
-    sdoGeometryColumn: {{boundingBox.sdoGeometryColumn}}
-    minLongitudeColumn: {{boundingBox.minLongitudeColumn}}
-    minLatitudeColumn: {{boundingBox.minLatitudeColumn}}
-    maxLongitudeColumn: {{boundingBox.maxLongitudeColumn}}
-    maxLatitudeColumn: {{boundingBox.maxLatitudeColumn}}
+    geometryColumn: {{boundingBox.geometryColumn}}
+    minLongitude: {{boundingBox.minLongitude}}
+    minLatitude: {{boundingBox.minLatitude}}
+    maxLongitude: {{boundingBox.maxLongitude}}
+    maxLatitude: {{boundingBox.maxLatitude}}
+    currentBoundsItem: {{boundingBox.currentBoundsItem}}
   }
-  mapStatusItem: {{mapStatusItem}}
 )
 ```
 
@@ -67,7 +67,7 @@ region {{regionStaticId}} (
 
 # Guardrails
 
-- `boundingBox.geometryColumnDataType: sdoGeometry` requires `boundingBox.sdoGeometryColumn`.
+- `boundingBox.geometryColumnDataType: sdoGeometry` requires `boundingBox.geometryColumn`.
 - `boundingBox.geometryColumnDataType: longitudeLatitude` requires the min/max longitude and latitude column set.
 - Use bbox metadata only when `mapFeatures` does not include `infiniteMap`.
 - Use this scenario as the default viewport strategy for multi-marker longitude/latitude maps. Source the bounds from the same filtered dataset as the visible layer, for example `min(longitude)`, `min(latitude)`, `max(longitude)`, and `max(latitude)`.

package/skills/apexlang/templates/region-components/map/map.region.bbox-static.md

@@ -29,7 +29,7 @@ Document static bounding-box authoring for map regions.
 
 ## Optional Variables
 
-- `mapStatusItem`
+- `boundingBox.currentBoundsItem`
 - `map.height`
 
 ---
@@ -53,8 +53,8 @@ region {{regionStaticId}} (
     minLatitude: {{boundingBox.minLatitude}}
     maxLongitude: {{boundingBox.maxLongitude}}
     maxLatitude: {{boundingBox.maxLatitude}}
+    currentBoundsItem: {{boundingBox.currentBoundsItem}}
   }
-  mapStatusItem: {{mapStatusItem}}
 )
 ```
 

package/skills/apexlang/templates/region-components/map/map.region.browser-location.md

@@ -23,13 +23,11 @@ Document browser-location-assisted initial positioning and the associated sessio
 - `layout.slot`
 - `controls.options` (must include `browserLocation`)
 - `initialPositionAndZoom.type`
-- `initialPositionAndZoom.fromBrowser`
+- `initialPositionAndZoom.getPositionFromBrowser`
 
 ## Optional Variables
 
-- `initialPositionAndZoom.zoomType`
 - `map.height`
-- `mapStatusItem`
 
 ---
 
@@ -51,10 +49,8 @@ region {{regionStaticId}} (
   }
   initialPositionAndZoom {
     type: {{initialPositionAndZoom.type}}
-    zoomType: {{initialPositionAndZoom.zoomType}}
-    fromBrowser: {{initialPositionAndZoom.fromBrowser}}
+    getPositionFromBrowser: {{initialPositionAndZoom.getPositionFromBrowser}}
   }
-  mapStatusItem: {{mapStatusItem}}
 )
 ```
 
@@ -62,5 +58,5 @@ region {{regionStaticId}} (
 
 # Guardrails
 
-- `initialPositionAndZoom.fromBrowser` is available only when `controls.options` includes browser location support.
+- `initialPositionAndZoom.getPositionFromBrowser` is available only when `controls.options` includes browser location support.
 - Browser-derived initial positioning applies only to the first page load in the APEX session; the widget then remembers position across page requests in the same session.

package/skills/apexlang/templates/region-components/map/map.region.init-position-sql.md

@@ -26,8 +26,8 @@ Document SQL-driven initial positioning for map regions using the attached `init
 
 ## Optional Variables
 
-- `initialPositionAndZoom.initialGeometrySdogeomColumn`
-- `initialPositionAndZoom.initialGeometryGeojsonColumn`
+- `initialPositionAndZoom.geometryColumn`
+- `initialPositionAndZoom.geojsonColumn`
 - `initialPositionAndZoom.initialLongitudeColumn`
 - `initialPositionAndZoom.initialLatitudeColumn`
 - `initialPositionAndZoom.initialZoomlevelColumn`
@@ -53,10 +53,10 @@ region {{regionStaticId}} (
     sqlQuery:
       ```sql
       {{initialPositionAndZoom.sqlQuery}}
-      ```
+    ```
     geometryColumnDataType: {{initialPositionAndZoom.geometryColumnDataType}}
-    initialGeometrySdogeomColumn: {{initialPositionAndZoom.initialGeometrySdogeomColumn}}
-    initialGeometryGeojsonColumn: {{initialPositionAndZoom.initialGeometryGeojsonColumn}}
+    geometryColumn: {{initialPositionAndZoom.geometryColumn}}
+    geojsonColumn: {{initialPositionAndZoom.geojsonColumn}}
     initialLongitudeColumn: {{initialPositionAndZoom.initialLongitudeColumn}}
     initialLatitudeColumn: {{initialPositionAndZoom.initialLatitudeColumn}}
     initialZoomlevelColumn: {{initialPositionAndZoom.initialZoomlevelColumn}}
@@ -68,8 +68,8 @@ region {{regionStaticId}} (
 
 # Guardrails
 
-- `geometryColumnDataType: sdoGeometry` requires `initialGeometrySdogeomColumn`.
-- `geometryColumnDataType: geojson` requires `initialGeometryGeojsonColumn`.
+- `geometryColumnDataType: sdoGeometry` requires `geometryColumn`.
+- `geometryColumnDataType: geojson` requires `geojsonColumn`.
 - `geometryColumnDataType: longitudeLatitude` requires `initialLongitudeColumn` and `initialLatitudeColumn`.
 - For `type: sqlQuery`, the SQL select list must expose aliases that exactly match each configured `initial*Column` property.
 - `initialZoomlevelColumn` is optional in SQL mode, but when present the SQL must return that alias explicitly.

package/skills/apexlang/templates/region-components/region-display-selector/README.md

@@ -1,16 +1,19 @@
 # Region Display Selector Templates
 
 ## Purpose
-Canonical guidance for the `region-display-selector` region family, including shared contract loading and supported scenario variants.
+Canonical guidance for the native `regionDisplaySelector` region family. An RDS has no data source; it controls an explicit set of sibling page regions that opt in through `advanced.regionDisplaySelector: true`.
 
 ## Usage
 - Load `region-display-selector._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.
+- Load `region-display-selector.standard.md` for the canonical View Single Region example.
+- Load `region-display-selector.permutations.md` when selecting or testing mode, icon, Show All, or persistence combinations.
+- Follow `references/domains/page-components/regions/region-display-selector/workflow-region-display-selector.md` for controller/target selection and validation rules.
 - Preserve canonical path references and markdown-first conventions when updating workflow or registry links.
 
 ## Template Catalog
 - `region-display-selector._common.md`
 - `region-display-selector.standard.md`
+- `region-display-selector.permutations.md`
 
 ## Maintenance
 - Keep this README synchronized with actual files in the directory.

package/skills/apexlang/templates/region-components/region-display-selector/region-display-selector._common.md

@@ -5,16 +5,69 @@ version: 1.0
 description: Shared contract for region display selector patterns.
 ---
 
+# Attribute Contract
+
+The upstream APEX catalog is reference metadata for this family. Its five settings
+are split by scope: four are component-instance settings and `includeSlider` is an
+application setting. The catalog names and defaults are normalized to the
+APEXlang names below.
+
+| Catalog scope | Catalog/native setting | APEXlang name | Valid values | Catalog default | Generation-time policy |
+|------|----------|------|------|------|------|
+| Component | `rds_mode` / `mode` | `settings.mode` | `viewSingleRegion`, `scrollWindow` | `viewSingleRegion` | Emit explicitly. |
+| Component | `display_region_icons` | `settings.displayRegionIcons` | `true`, `false` | not declared | Emit explicitly. |
+| Component | `include_show_all` | `settings.includeShowAll` | `true`, `false` | `true` when active | Emit explicitly for `viewSingleRegion`; omit for `scrollWindow`. |
+| Component | `remember_selection` | `settings.rememberSelection` | `byUser`, `bySession`, `false` | `byUser` | Emit explicitly. |
+| Application | `include_slider` | `componentSetting NATIVE_DISPLAY_SELECTOR` → `settings.attributes.includeSlider` | `true`, `false` | `true` | Optional; emit only when explicitly requested. |
+
+Catalog defaults describe upstream metadata; they are not permission to omit
+required instance settings during deterministic generation. `includeSlider` is not
+an RDS controller setting and is not required for ordinary RDS page generation.
+
 # Variable Contract
 
 | Name | Required | Type | Notes |
 |------|----------|------|-------|
-| controlRegionStaticId | yes | string | RDS control region id. |
-| toggledRegions | yes | array | Regions that set `advanced.regionDisplaySelector: true`. |
-| settings.displayRegionIcons | optional | boolean | Displays target region icons. |
-| settings.rememberSelection | optional | enum | `bySession`, `byUser`, or `false`. |
+| controllerRegion | yes | object | Exactly one `type: regionDisplaySelector` region on the page. |
+| controllerRegionHtmlDomId | yes | string | Stable RDS controller DOM identifier emitted as `advanced.htmlDomId`. |
+| controlledRegions | yes | array | At least two explicitly selected sibling page regions. |
+| settings.mode | yes | enum | `viewSingleRegion` or `scrollWindow`. |
+| settings.displayRegionIcons | yes | boolean | When `true`, every controlled region supplies a valid `appearance.icon`. |
+| settings.includeShowAll | conditional | boolean | Required only for `viewSingleRegion`; omit for `scrollWindow`. |
+| settings.rememberSelection | yes | enum | `byUser`, `bySession`, or `false`. |
+| applicationSettings.includeSlider | optional | boolean | Application-scoped setting emitted through `componentSetting NATIVE_DISPLAY_SELECTOR`. |
+
+# Repository Implementation and Compiler Constraints
+
+The following rules are repository generation/validation constraints. They keep
+membership deterministic and must not be read as additional upstream catalog
+requirements.
+
+- The controller is a navigation region and must not define `source` or query data.
+- Create one controller per page. The RDS contract has no controller identifier on a target region, so multiple controllers create ambiguous membership.
+- Require at least two controlled regions and set `advanced.regionDisplaySelector: true` only on that explicit list.
+- Controlled regions may mix native and theme template component families when each selected region supports the `advanced.regionDisplaySelector` property in the active compiler contract.
+- Never opt the controller itself, a breadcrumb region, or a region placed in a header/breadcrumb slot into the selector.
+- Leave unrelated page regions at the default (`regionDisplaySelector` omitted or `false`).
+- Keep controlled regions in stable `layout.sequence` order; that order defines the selector order.
+- `viewSingleRegion` shows one selected region. `scrollWindow` leaves all controlled regions visible and scrolls to the selected region.
+- Emit `settings.includeShowAll` only for `viewSingleRegion`.
+- `rememberSelection: byUser` or `bySession` requires stable target-region DOM IDs in this repository's validator; `false` stores no selection.
+- When `displayRegionIcons: true`, reuse the shared `FA_ICON_REQUIRED_001` catalogue rule for every controlled region icon.
+- RDS visibility is presentation only. Preserve each controlled region's own authorization scheme and server-side condition.
+
+# Identifier Contract
+
+`staticId` and `htmlDomId` are not interchangeable. For `region` declarations in
+this compiler, including the RDS controller and targets, `advanced.htmlDomId` is
+authoritative. Use `advanced.htmlDomId`; `advanced.staticId` is rejected by direct
+target-build validation.
+`staticId` remains available only for component types whose own contracts declare
+it. Do not transfer an identifier property from another component kind to a
+region.
 
-# Guardrails
+# Authority Boundary
 
-- Each toggled region must explicitly set `advanced.regionDisplaySelector: true`.
-- Keep toggled regions in stable layout order for deterministic tab behavior.
+- APEX 26.1 native metadata identifies the plugin as `NATIVE_DISPLAY_SELECTOR` and stores `rds_mode` as `STANDARD` or `JUMP`.
+- The upstream catalog records application-scoped `include_slider` with default `true`; this repository exposes it through the shared `componentSetting` contract.
+- APEXlang uses the normalized values documented above. Direct compiler validation and target-build `apex validate` remain authoritative before completion.

package/skills/apexlang/templates/region-components/region-display-selector/region-display-selector._index.md

@@ -4,6 +4,8 @@ componentType: template
 version: 1.0
 imports:
   - region-display-selector._common.md
+  - region-display-selector.standard.md
+  - region-display-selector.permutations.md
 description: Routing entrypoint for region-display-selector templates.
 ---
 
@@ -15,4 +17,5 @@ Primary routing entrypoint for `region-display-selector` templates.
 
 1. Load this file.
 2. Load `region-display-selector._common.md`.
-3. Load one scenario template in this folder.
+3. Load `region-display-selector.standard.md` for generation.
+4. Load `region-display-selector.permutations.md` only when configuration coverage or a non-default mode is requested.

package/skills/apexlang/templates/region-components/region-display-selector/region-display-selector.permutations.md

@@ -0,0 +1,55 @@
+---
+templateId: region.region-display-selector.permutations
+componentType: region
+version: 1.0
+imports:
+  - region-display-selector._common
+description: Complete valid setting matrix for native Region Display Selector generation.
+---
+
+# Valid Configuration Matrix
+
+The valid matrix contains 18 combinations:
+
+- `viewSingleRegion`: 2 icon values x 2 Show All values x 3 persistence values = 12.
+- `scrollWindow`: 2 icon values x 3 persistence values = 6. `includeShowAll` must be omitted.
+
+| Mode | Display Region Icons | Include Show All | Remember Selection |
+|------|----------------------|------------------|--------------------|
+| `viewSingleRegion` | `false` or `true` | `false` or `true` | `false`, `bySession`, or `byUser` |
+| `scrollWindow` | `false` or `true` | omit | `false`, `bySession`, or `byUser` |
+
+# Scroll Window Settings
+
+Use the same controller and controlled-region structure from `region-display-selector.standard.md`, replacing only the settings block:
+
+```apexlang
+region section_selector (
+    name: Section Selector
+    type: regionDisplaySelector
+    layout {
+        sequence: 10
+        slot: body
+    }
+    appearance {
+        template: @/blank-with-attributes-no-grid
+        templateOptions: #DEFAULT#
+    }
+    settings {
+        mode: scrollWindow
+        displayRegionIcons: false
+        rememberSelection: bySession
+    }
+    advanced {
+        htmlDomId: section-selector
+    }
+)
+```
+
+# Invalid Combinations
+
+- Reject `includeShowAll` when `mode: scrollWindow`.
+- Reject a controller with fewer than two controlled regions.
+- Reject a controller that opts itself into RDS.
+- Reject breadcrumb and header-region targets.
+- Reject `displayRegionIcons: true` when any controlled region lacks `appearance.icon`.

package/skills/apexlang/templates/region-components/region-display-selector/region-display-selector.standard.md

@@ -4,11 +4,97 @@ componentType: region
 version: 1.0
 imports:
   - region-display-selector._common
-description: Standard RDS control region with multiple toggled content regions.
+description: Standard RDS controller with two explicitly selected content regions.
 ---
 
-# Pattern
+# View Single Region Pattern
 
-- Create RDS control region (`type: regionDisplaySelector`) in target slot.
-- Mark each controlled region with `advanced { regionDisplaySelector: true }`.
-- Optionally enable `displayRegionIcons` and `rememberSelection`.
+This data-free example uses two static content regions so it introduces no database-object assumptions.
+
+```apexlang
+page 10 (
+    name: Region Display Selector
+    alias: REGION-DISPLAY-SELECTOR
+    title: Region Display Selector
+    appearance {
+        pageTemplate: @/standard
+        templateOptions: #DEFAULT#
+    }
+    security {
+        authorizationScheme: mustNotBePublicUser
+        pageAccessProtection: argumentsMustHaveChecksum
+        formAutoComplete: false
+    }
+
+    region section_selector (
+        name: Section Selector
+        type: regionDisplaySelector
+        layout {
+            sequence: 10
+            slot: body
+        }
+        appearance {
+            template: @/blank-with-attributes-no-grid
+            templateOptions: #DEFAULT#
+        }
+        settings {
+            mode: viewSingleRegion
+            displayRegionIcons: true
+            includeShowAll: true
+            rememberSelection: byUser
+        }
+        advanced {
+            htmlDomId: section-selector
+        }
+    )
+
+    region summary (
+        name: Summary
+        type: staticContent
+        source {
+            htmlCode: Review the current summary.
+        }
+        layout {
+            sequence: 20
+            slot: body
+        }
+        appearance {
+            template: @/standard
+            templateOptions: #DEFAULT#
+            icon: fa-list
+        }
+        advanced {
+            htmlDomId: summary
+            regionDisplaySelector: true
+        }
+    )
+
+    region details (
+        name: Details
+        type: staticContent
+        source {
+            htmlCode: Review the current details.
+        }
+        layout {
+            sequence: 30
+            slot: body
+        }
+        appearance {
+            template: @/standard
+            templateOptions: #DEFAULT#
+            icon: fa-table
+        }
+        advanced {
+            htmlDomId: details
+            regionDisplaySelector: true
+        }
+    )
+)
+```
+
+# Required Behavior
+
+- Do not add `advanced.regionDisplaySelector` to `section_selector`.
+- The `summary` and `details` layout sequences determine their tab order.
+- If icons are disabled, the controlled regions may omit `appearance.icon`.
+- Do not use RDS selection as an authorization or server-side-condition replacement.

package/skills/apexlang/templates/region-components/smart-filter-search/README.md

@@ -4,9 +4,11 @@
 Canonical guidance for the `smart-filter-search` region family, including shared contract loading and supported scenario variants.
 
 ## Usage
-- Load `smart-filter-search._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.
+- Select the `smart-filter-search` construction pack before loading Markdown.
+- Load `smart-filter-search._common.md` to freeze the base-region, search-behavior, settings, security, and performance contracts.
+- Use `smart-filter-search.standard.md` only when its single-base-region and required search-child shape matches the request.
 - Preserve canonical path references and markdown-first conventions when updating workflow or registry links.
+- Use structured JSON for Generation Plan evidence; templates are not evidence.
 
 ## Template Catalog
 - `smart-filter-search._common.md`
@@ -16,3 +18,5 @@ Canonical guidance for the `smart-filter-search` region family, including shared
 - 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.
+- Keep ticket settings out of APEXlang output until property-level compiler evidence proves them for the target build.
+- Keep artifact rules, plan evidence, and runtime acceptance as separate layers.