pi-apexlang 0.1.0

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

@@ -0,0 +1,66 @@
+---
+templateId: region.map.browser-location
+componentType: region
+version: 1.0
+imports:
+  - map._common.md
+description: Map region scenario using browser-location-assisted initial positioning in the attached map structure.
+---
+
+# Purpose
+
+Document browser-location-assisted initial positioning and the associated session behavior.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- `regionStaticId`
+- `name`
+- `layout.sequence`
+- `layout.slot`
+- `controls.options` (must include `browserLocation`)
+- `initialPositionAndZoom.type`
+- `initialPositionAndZoom.fromBrowser`
+
+## Optional Variables
+
+- `initialPositionAndZoom.zoomType`
+- `map.height`
+- `mapStatusItem`
+
+---
+
+# Output Template – Full
+
+```apexlang
+region {{regionStaticId}} (
+  name: {{name}}
+  type: map
+  map {
+    height: {{map.height}}
+  }
+  layout {
+    sequence: {{layout.sequence}}
+    slot: {{layout.slot}}
+  }
+  controls {
+    options: {{controls.options}}
+  }
+  initialPositionAndZoom {
+    type: {{initialPositionAndZoom.type}}
+    zoomType: {{initialPositionAndZoom.zoomType}}
+    fromBrowser: {{initialPositionAndZoom.fromBrowser}}
+  }
+  mapStatusItem: {{mapStatusItem}}
+)
+```
+
+---
+
+# Guardrails
+
+- `initialPositionAndZoom.fromBrowser` 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

@@ -0,0 +1,77 @@
+---
+templateId: region.map.init-position-sql
+componentType: region
+version: 1.0
+imports:
+  - map._common.md
+description: Map region scenario with SQL-driven `initialPositionAndZoom` metadata.
+---
+
+# Purpose
+
+Document SQL-driven initial positioning for map regions using the attached `initialPositionAndZoom` block shape.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- `regionStaticId`
+- `name`
+- `layout.sequence`
+- `layout.slot`
+- `initialPositionAndZoom.sqlQuery`
+- `initialPositionAndZoom.geometryColumnDataType`
+
+## Optional Variables
+
+- `initialPositionAndZoom.initialGeometrySdogeomColumn`
+- `initialPositionAndZoom.initialGeometryGeojsonColumn`
+- `initialPositionAndZoom.initialLongitudeColumn`
+- `initialPositionAndZoom.initialLatitudeColumn`
+- `initialPositionAndZoom.initialZoomlevelColumn`
+- `map.height`
+
+---
+
+# Output Template – Full
+
+```apexlang
+region {{regionStaticId}} (
+  name: {{name}}
+  type: map
+  map {
+    height: {{map.height}}
+  }
+  layout {
+    sequence: {{layout.sequence}}
+    slot: {{layout.slot}}
+  }
+  initialPositionAndZoom {
+    type: sqlQuery
+    sqlQuery:
+      ```sql
+      {{initialPositionAndZoom.sqlQuery}}
+      ```
+    geometryColumnDataType: {{initialPositionAndZoom.geometryColumnDataType}}
+    initialGeometrySdogeomColumn: {{initialPositionAndZoom.initialGeometrySdogeomColumn}}
+    initialGeometryGeojsonColumn: {{initialPositionAndZoom.initialGeometryGeojsonColumn}}
+    initialLongitudeColumn: {{initialPositionAndZoom.initialLongitudeColumn}}
+    initialLatitudeColumn: {{initialPositionAndZoom.initialLatitudeColumn}}
+    initialZoomlevelColumn: {{initialPositionAndZoom.initialZoomlevelColumn}}
+  }
+)
+```
+
+---
+
+# Guardrails
+
+- `geometryColumnDataType: sdoGeometry` requires `initialGeometrySdogeomColumn`.
+- `geometryColumnDataType: geojson` requires `initialGeometryGeojsonColumn`.
+- `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.
+- Do not use this scenario to center a multi-marker map on `avg(latitude)` / `avg(longitude)` with a fixed zoom. For store/customer/location maps with more than one marker, use SQL-derived `boundingBox` instead so the initial viewport fits the data.
+- Use fixed zoom only for a requirement-backed single known geography or one-location map.

package/skills/apexlang/templates/region-components/map/map.runtime-api.md

@@ -0,0 +1,102 @@
+---
+templateId: map.runtime-api
+componentType: template
+version: 1.0
+description: Runtime JavaScript API for Oracle APEX Maps.
+---
+
+# Purpose
+
+Document the runtime JS API exposed by the rendered map region through `apex.region( regionId )`.
+
+This file is a runtime reference only. It is not a declarative APEXlang region template.
+
+---
+
+# Public Region Methods
+
+| Method | Since | Notes |
+|--------|-------|-------|
+| `refresh()` | 21.2 | Re-fetch layer data. |
+| `focus()` | 21.2 | Focus the map canvas. |
+| `getLayers()` | 21.2 | Returns the current layer objects without `activePopups`. |
+| `getLayerIdByName( name )` | 21.2 | Resolve a layer ID by its current name. |
+| `getFeature( layerId, featureId )` | 21.2 | Returns one feature from the target layer. |
+| `addFeature( layerId, feature )` | 21.2 | Adds a feature to a non-vector-tile layer. |
+| `updateFeature( layerId, feature )` | 21.2 | Updates a feature on a non-vector-tile layer. |
+| `removeFeature( layerId, featureId )` | 21.2 | Removes a feature from a non-vector-tile layer. |
+| `displayPopup( type, layerId, featureId, focusAfterOpen, lngLat )` | 21.2 | Opens a tooltip or info window. |
+| `closeTooltip()` | 21.2 | Closes the current tooltip. |
+| `closeInfoWindow( layerId, featureId )` | 21.2 | Closes one info window. |
+| `closeAllInfoWindows( layerId? )` | 21.2 | Closes all info windows or all windows on one layer. |
+| `getMapBboxAndZoomLevel()` | 21.2 | Returns bbox and zoom. |
+| `getMapCenterAndZoomLevel()` | 21.2 | Returns center and zoom. |
+| `getMapPitchAndBearing()` | 21.2 | Returns pitch and bearing. |
+| `setZoomLevel( zoom )` | 21.2 | Sets the map zoom level. |
+| `setCenter( [lng, lat] )` | 21.2 | Re-centers the map and triggers the changed flow. |
+| `getMapObject()` | 21.2 | Returns the underlying MapLibre map object. |
+| `getCircle()` | 21.2 | Returns the current circle GeoJSON polygon. |
+| `clearCircle()` | 21.2 | Clears the current circle. |
+| `reset()` | 21.2 | Resets the map instance. |
+| `getMapStatus()` | 21.2 | Returns bbox, zoom, pitch, and bearing together. |
+| `showLayer( nameOrId )` | 26.1 | Shows a layer by name or ID. |
+| `hideLayer( nameOrId )` | 26.1 | Hides a layer by name or ID. |
+| `moveLayer( layerId, beforeLayerId? )` | 26.1 | Reorders a layer in the z-stack. |
+
+---
+
+# Events
+
+| jQuery event | Runtime name | Payload |
+|-------------|--------------|---------|
+| `spatialmapinitialized` | `initialized` | No extra payload. Fires when the map is fully initialized. |
+| `spatialmapclick` | `click` | `{ lat, lng }` |
+| `spatialmapobjectclick` | `objectclick` | Feature or cluster payload including `id`, `lat`, `lng`, `tooltip`, `infoWindow`, `cluster_id`, `point_count` as applicable. |
+| `spatialmapchanged` | `changed` | `{ changeType, layers, bbox, zoom, pitch, bearing, circle }` |
+
+`changed.changeType` can be one of:
+- `map-drag`
+- `map-zoom`
+- `toggle-layer`
+- `map-rotate`
+- `circle-drawn`
+- `circle-removed`
+- `feature-added`
+- `feature-removed`
+- `feature-updated`
+
+---
+
+# Example
+
+```javascript
+const mapRegion = apex.region( "R_EMP_MAP" );
+
+mapRegion.refresh();
+
+$( "#R_EMP_MAP" ).on( "spatialmapobjectclick", function( event, data ) {
+  if ( data.id ) {
+    console.log( "Clicked feature", data.id );
+  }
+} );
+
+mapRegion.showLayer( "Employees" );
+```
+
+---
+
+# Runtime Guardrails
+
+- `getMapObject()` exposes the underlying MapLibre object. Code that depends on MapLibre internals may not be forward compatible.
+- `addFeature`, `updateFeature`, and `removeFeature` reject vector-tile layers.
+- `displayPopup()` requires explicit `{ lng, lat }` coordinates for non-point geometries because the widget does not calculate popup placement for arbitrary shapes.
+- `spatialmapchanged` also fires when the circle tool is used.
+- `showLayer`, `hideLayer`, and `moveLayer` are runtime APIs added in 26.1.
+
+---
+
+# Source Anchors
+
+- `images/libraries/apex/widget.spatialMap.js`
+- `images/libraries/apex/tests/widget.spatialMap_test.html`
+- `images/apex_ui/js/code-editor/types/browser/types.d.ts`

package/skills/apexlang/templates/region-components/map/map.sdo-geometry.md

@@ -0,0 +1,36 @@
+---
+templateId: region.map.sdo-geometry
+componentType: region
+version: 1.0
+imports:
+  - map._common.md
+description: SDO geometry qualifier for map regions.
+---
+
+# Purpose
+
+Map-region variant for SDO geometry sources.
+
+# Generation Rules (MANDATORY)
+
+1. Load `map._common.md` first.
+2. Use this variant when the source column is an SDO geometry column.
+
+# Variable Contract
+
+## Required Variables
+
+- `qualifier`
+- `layer.geometryColumn`
+
+# Output Template – Full
+
+```apexlang
+layer {
+  geometryColumn: {{layer.geometryColumn}}
+}
+```
+
+# Conditional Rendering Rules
+
+- Keep the qualifier explicit as `sdoGeometry`.

package/skills/apexlang/templates/region-components/map/map.standard.md

@@ -0,0 +1,120 @@
+---
+templateId: region.map.standard
+componentType: region
+version: 1.0
+imports:
+  - map._common.md
+  - map.layer._common.md
+description: Standard map region with one declarative table-backed point layer using the attached map structure.
+---
+
+# Purpose
+
+Baseline map-region scenario for the default authoring path: a single declarative point layer using `initialPositionAndZoom`, table-backed `source { tableName: ... }`, and `geometryColumnDataType: longitudeLatitude`.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `map._common.md`, `map.layer._common.md`, and `references/policies/memory-bank/30-pages/apex.map-page.md` before use.
+2. Use this template only for the simplest table-backed point-map flow.
+3. Move bbox, SQL-driven initial position, shared backgrounds, browser-location behavior, and non-point layers into the dedicated scenario files.
+4. For `initialPositionAndZoom.type: sqlQuery`, make the SQL select-list aliases exactly match the emitted `initialLongitudeColumn`, `initialLatitudeColumn`, and optional `initialZoomlevelColumn` names.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- `regionStaticId`
+- `name`
+- `layout.sequence`
+- `layout.slot`
+- `initialPositionAndZoom.sqlQuery`
+- `initialPositionAndZoom.geometryColumnDataType`
+- `initialPositionAndZoom.initialLongitudeColumn`
+- `initialPositionAndZoom.initialLatitudeColumn`
+- `layer.staticId`
+- `layer.name`
+- `layer.layout.sequence`
+- `layer.source.tableName`
+- `layer.columnMapping.geometryColumnDataType`
+- `layer.columnMapping.longitudeColumn`
+- `layer.columnMapping.latitudeColumn`
+
+## Optional Variables
+
+- `map.height`
+- `controls.options`
+- `attributes.messagesPosition`
+- `tooltip.column`
+
+Use `map.layer.points.sql-query.md` or `map.layer.points.function-body.md` when the point layer source is not table-backed.
+
+---
+
+# Output Template
+
+```apexlang
+region {{regionStaticId}} (
+  name: {{name}}
+  type: map
+  map {
+    height: {{map.height}}
+  }
+  layout {
+    sequence: {{layout.sequence}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    template: @/standard
+    templateOptions: #DEFAULT#
+  }
+  controls {
+    options: {{controls.options}}
+  }
+  initialPositionAndZoom {
+    type: sqlQuery
+    sqlQuery:
+      ```sql
+      {{initialPositionAndZoom.sqlQuery}}
+      ```
+    geometryColumnDataType: {{initialPositionAndZoom.geometryColumnDataType}}
+    initialLongitudeColumn: {{initialPositionAndZoom.initialLongitudeColumn}}
+    initialLatitudeColumn: {{initialPositionAndZoom.initialLatitudeColumn}}
+    initialZoomlevelColumn: {{initialPositionAndZoom.initialZoomlevelColumn}}
+  }
+  attributes {
+    messagesPosition: {{attributes.messagesPosition}}
+  }
+  layer {{layer.staticId}} (
+    name: {{layer.name}}
+    layout {
+      sequence: {{layer.layout.sequence}}
+    }
+    source {
+      tableName: {{layer.source.tableName}}
+    }
+    columnMapping {
+      geometryColumnDataType: {{layer.columnMapping.geometryColumnDataType}}
+      longitudeColumn: {{layer.columnMapping.longitudeColumn}}
+      latitudeColumn: {{layer.columnMapping.latitudeColumn}}
+    }
+    tooltip {
+      column: {{tooltip.column}}
+    }
+  )
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Omit `map` when the default map height is acceptable.
+- Omit `controls` when no control options are requested.
+- Use `map.region.*.md` files for region-level edge cases.
+- Use `map.layer.*.md` files for point, line, polygon, heat-map, or extruded-polygon details beyond this baseline.
+- Keep this standard scenario table-backed. For non-table point layers, switch to the dedicated typed SQL or function-body point-layer scenarios instead of widening this baseline example.
+- Keep SQL-driven initial position metadata and the SQL select-list synchronized. `initialZoomlevelColumn` stays optional, but if emitted it must match a returned alias.

package/skills/apexlang/templates/region-components/region-components.registry.json

@@ -0,0 +1,117 @@
+{
+  "version": 1,
+  "entries": [
+    {
+      "slug": "legacy-history",
+      "file": "LEGACY.md"
+    },
+    {
+      "slug": "breadcrumb",
+      "path": "breadcrumb/",
+      "readme": "breadcrumb/README.md",
+      "index": "breadcrumb/breadcrumb._index.md"
+    },
+    {
+      "slug": "calendar",
+      "path": "calendar/",
+      "readme": "calendar/README.md",
+      "index": "calendar/calendar._index.md"
+    },
+    {
+      "slug": "cards",
+      "path": "cards/",
+      "readme": "cards/README.md",
+      "index": "cards/cards._index.md"
+    },
+    {
+      "slug": "chart",
+      "path": "chart/",
+      "readme": "chart/README.md",
+      "index": "chart/chart._index.md"
+    },
+    {
+      "slug": "classic-report",
+      "path": "classic-report/",
+      "readme": "classic-report/README.md",
+      "index": "classic-report/classic-report._index.md"
+    },
+    {
+      "slug": "collapsible-region",
+      "path": "collapsible-region/",
+      "readme": "collapsible-region/README.md",
+      "index": "collapsible-region/collapsible-region._index.md"
+    },
+    {
+      "slug": "dynamic-content",
+      "path": "dynamic-content/",
+      "readme": "dynamic-content/README.md",
+      "index": "dynamic-content/dynamic-content._index.md"
+    },
+    {
+      "slug": "faceted-search",
+      "path": "faceted-search/",
+      "readme": "faceted-search/README.md",
+      "index": "faceted-search/faceted-search._index.md"
+    },
+    {
+      "slug": "form",
+      "path": "form/",
+      "readme": "form/README.md",
+      "index": "form/form._index.md"
+    },
+    {
+      "slug": "help-text",
+      "path": "help-text/",
+      "readme": "help-text/README.md",
+      "index": "help-text/help-text._index.md"
+    },
+    {
+      "slug": "list",
+      "path": "list/",
+      "readme": "list/README.md",
+      "index": "list/list._index.md"
+    },
+    {
+      "slug": "interactive-grid",
+      "path": "interactive-grid/",
+      "readme": "interactive-grid/README.md",
+      "index": "interactive-grid/interactive-grid._index.md"
+    },
+    {
+      "slug": "interactive-report",
+      "path": "interactive-report/",
+      "readme": "interactive-report/README.md",
+      "index": "interactive-report/interactive-report._index.md"
+    },
+    {
+      "slug": "map",
+      "path": "map/",
+      "readme": "map/README.md",
+      "index": "map/map._index.md"
+    },
+    {
+      "slug": "region-display-selector",
+      "path": "region-display-selector/",
+      "readme": "region-display-selector/README.md",
+      "index": "region-display-selector/region-display-selector._index.md"
+    },
+    {
+      "slug": "search-config",
+      "path": "search-config/",
+      "readme": "search-config/README.md",
+      "index": "search-config/search-config._index.md"
+    },
+    {
+      "slug": "smart-filter-search",
+      "path": "smart-filter-search/",
+      "readme": "smart-filter-search/README.md",
+      "index": "smart-filter-search/smart-filter-search._index.md"
+    },
+    {
+      "slug": "static-content",
+      "path": "static-content/",
+      "readme": "static-content/README.md",
+      "index": "static-content/static-content._index.md"
+    }
+  ]
+}

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

@@ -0,0 +1,18 @@
+# Region Display Selector Templates
+
+## Purpose
+Canonical guidance for the `region-display-selector` region family, including shared contract loading and supported scenario variants.
+
+## 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.
+- 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`
+
+## 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/region-display-selector/region-display-selector._common.md

@@ -0,0 +1,20 @@
+---
+templateId: region.region-display-selector.common
+componentType: region
+version: 1.0
+description: Shared contract for region display selector patterns.
+---
+
+# 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`. |
+
+# Guardrails
+
+- Each toggled region must explicitly set `advanced.regionDisplaySelector: true`.
+- Keep toggled regions in stable layout order for deterministic tab behavior.

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

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

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

@@ -0,0 +1,14 @@
+---
+templateId: region.region-display-selector.standard
+componentType: region
+version: 1.0
+imports:
+  - region-display-selector._common
+description: Standard RDS control region with multiple toggled content regions.
+---
+
+# Pattern
+
+- Create RDS control region (`type: regionDisplaySelector`) in target slot.
+- Mark each controlled region with `advanced { regionDisplaySelector: true }`.
+- Optionally enable `displayRegionIcons` and `rememberSelection`.

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

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

package/skills/apexlang/templates/region-components/search-config/search-config._common.md

@@ -0,0 +1,22 @@
+---
+templateId: region.search-config.common
+componentType: region
+version: 1.0
+description: Shared contract for search regions using searchConfig.
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| searchRegionStaticId | yes | string | Search region static id. |
+| searchPageItem | yes | string | Page item capturing search text. |
+| searchSource.searchConfig | yes | ref | Shared search configuration reference. |
+| headerRegion | optional | ref | Header region when search item is in PLUGIN_SEARCH slot. |
+| appearance.template | optional | string | Default to `@/standard` for the search-config region shell. |
+
+# Guardrails
+
+- `settings.searchPageItem` must reference an existing page item.
+- `searchSource.searchConfig` must reference a valid shared search configuration component.
+- Use `appearance.template: @/standard` unless the surrounding page pattern documents a different shell.

package/skills/apexlang/templates/region-components/search-config/search-config._index.md

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

package/skills/apexlang/templates/region-components/search-config/search-config.standard.md

@@ -0,0 +1,28 @@
+---
+templateId: region.search-config.standard
+componentType: region
+version: 1.0
+imports:
+  - search-config._common
+description: Standard search region wired to page item and shared searchConfig.
+---
+
+# Output Template
+
+```
+region {{searchRegionStaticId}} (
+  name: {{name}}
+  type: search
+  layout {
+    sequence: {{layout.sequence}}
+    slot: {{layout.slot}}
+  }
+  settings {
+    searchPageItem: {{settings.searchPageItem}}
+  }
+  searchSource {{searchSource.staticId}} (
+    name: {{searchSource.name}}
+    searchConfig: @{{searchSource.searchConfig}}
+  )
+)
+```