pi-apexlang 0.1.0

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

@@ -0,0 +1,152 @@
+---
+templateId: region.map.common
+componentType: region
+version: 1.1
+description: Shared family contract for Oracle APEX map regions. Covers the region shell and qualifier-dependent geometry mapping (sdoGeometry, geojson, longitudeLatitude).
+---
+
+# Purpose
+
+Standardize the Oracle APEX Maps surface using the attached `MapsLang.apx` structure as the canonical declarative pattern for page-level and region-level map authoring in this repo.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `references/policies/memory-bank/30-pages/apex.map-page.md` before drafting map-region output.
+2. Keep region and layer guidance separated; layer-specific contracts belong in `map.layer._common.md` and `map.layer.*.md`.
+3. Use `map.standard.md` for the default single-layer point map, and load focused scenario files only when the request needs them.
+4. Keep output templates variable-driven; sample values belong in prose examples, not in reusable skeletons.
+5. Treat geometry mapping as explicit declarative metadata using `geometryColumnDataType`.
+6. Default map regions to `appearance.template: @/standard` unless a documented scenario explicitly requires another shell.
+
+---
+
+# Component Family
+
+| Component | Repo anchor | APEXlang target | Notes |
+|----------|-------------|-----------------|-------|
+| Map page pattern | `core/modules/create_app_wiz/wwv_flow_create_app.plb`, `core/wwv_flow_map_region_dev.sql` | `page (...)` scaffold containing a `type: map` region | Builder/Create Page pattern that seeds one map region and one initial layer. |
+| Map region | `builder/f4411/application/shared_components/plugins/region_type/map_region.sql` | `region (...)` with `type: map` | Native region plugin `MAP_REGION`. |
+| Map layer | `core/apex_install_pe_data.sql` (`MAP_LAYER`) | `layer (...)` child block | One or more layers under a map region. |
+| Map background | `core/apex_install_pe_data.sql` (`MAP_BACKGROUND`) | `mapBackground (...)` shared component | Referenced from a region when `tileLayerType` uses shared backgrounds. |
+| Runtime region API | `images/libraries/apex/widget.spatialMap.js` | `apex.region( regionId )` | JS-only surface for runtime manipulation and events. |
+
+---
+
+# Shared Compatibility Rules
+
+| Concern | Supported contract |
+|--------|--------------------|
+| Built-in background mode | `tileLayerType` = `default` or `custom` using built-in background maps. |
+| Shared background mode | `tileLayerType` = `shared`, selecting one or two `mapBackground` shared components. |
+| Layer source | Declarative child-layer `source` supports three modes: `tableName`, typed `sqlQuery`, and typed `functionBody`. |
+| Local geometry types | `longitudeLatitude`, `sdoGeometry`, or `geojson`. |
+| Remote geometry types | `geojson` and `longitudeLatitude`. |
+| Layer types | Multiple layer scenarios remain supported; use the scenario file that matches the requested shape. |
+| Initial position modes | `staticValues`, `sqlQuery`, or `queryResults`. |
+| Bounding box modes | none, `staticValues`, or `sqlQuery`. |
+
+---
+
+# Naming Rules
+
+- Region examples use `type: map`.
+- Child layer examples use `layer`.
+- Shared background examples use `mapBackground`.
+- Shared link-helper examples use `linkTargetType` plus lower-camel helper names derived from `LINK_TARGET_IN_APP`, `LINK_TARGET_IN_DIFF_APP`, and `LINK_TARGET_URL`.
+- Enum spellings follow explicit `p_apexlang_name` overrides when present:
+  - bbox type: `staticValues`, `sqlQuery`
+  - map background type: `raster`, `vector`
+- Boolean examples use `true` and `false`, matching the repo seed metadata overrides.
+
+---
+
+# Region-Level Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| `regionStaticId` | yes | string | Identifier used after the `region` keyword. |
+| `name` | yes | string | Builder display name. |
+| `layout.sequence` | yes | number | Region order in the page slot. |
+| `layout.slot` | yes | enum | Slot the region occupies. |
+| `appearance.template` | optional | string | Default to `@/standard`. |
+| `map.height` | optional | number | Map widget height emitted inside `map { height: ... }`. |
+| `tileLayerType` | optional | enum | `default`, `custom`, or `shared`. |
+| `standardTileLayer` | conditional | enum or component ref | Built-in background for `custom`, or shared `mapBackground` for `shared`. |
+| `darkModeTileLayer` | optional | enum or component ref | Optional dark-mode override. |
+| `navigationBarType` | optional | enum | `none`, `small`, or `full`. |
+| `navigationBarPosition` | conditional | enum | `start` or `end`; only when navigation bar is not `none`. |
+| `controls.options` | optional | list | Region feature list such as `scaleBar`, `browserLocation`, or `infiniteMap`. |
+| `initialPositionAndZoom` | optional | block | SQL-driven or static viewport contract for the initial map position. |
+| `boundingBox` | optional | block | Static or SQL-derived viewport bounds. For static bounds, emit `type`, `minLongitude`, `minLatitude`, `maxLongitude`, and `maxLatitude` inside the block. Hidden when `infiniteMap` is enabled. |
+| `showLegend` | optional | boolean | Region-level legend toggle. |
+| `legendPosition` | conditional | enum | `start`, `end`, or `selector`. |
+| `attributes.messagesPosition` | optional | enum | `above`, `below`, or `selector`. |
+| `unitSystem` | optional | enum | `metric`, `imperial`, or `item`. |
+| `lazyLoading` | optional | boolean | Required for per-layer vector tiles. |
+| `customStyles` | optional | text | Custom SVG shape definitions used by point layers. |
+| `layers` | conditional | list | One or more child `layer` blocks. |
+
+---
+
+# Cross-Surface Guardrails
+
+- Distinguish the two vector-tile controls:
+  - app/plugin-level `useVectorTileLayers` governs supported built-in background maps
+  - per-layer `useVectorTiles` governs feature-data fetching as PBF vector tiles
+- `useVectorTiles` is a layer data-fetch optimization. It is not a styling shortcut and does not relax source-location or geometry restrictions.
+- `queryResults` initial positioning is intentionally still visible even though it conflicts with `useVectorTiles`; Builder enforces the rejection through callback validation rather than by hiding the property.
+- `INFINITE_MAP` disables bbox authoring metadata.
+- Multi-marker maps should fit the data, not center on an average point. Do not use `avg(latitude)` / `avg(longitude)` with a fixed zoom level for store/customer/location maps; use `boundingBox` with min/max coordinates or another query-results viewport pattern.
+- Fixed `initialZoomlevelColumn` values are appropriate only for a requirement-backed single geography or known one-location viewport.
+- `MAP_HAS_SPATIAL_INDEX` is a performance hint, not a guarantee that a spatial index will always be used.
+- The layer link contract uses `linkTargetType` plus helper properties under the `LINK_TARGET_` prefix rather than a single raw `linkTarget` payload.
+- Runtime mutation methods and popup helpers must be documented separately from declarative metadata because they exist only after the widget initializes in the browser.
+- Child map layers keep `tableName` as the preferred standard path. For non-table sources, emit `source.type: sqlQuery` with `source.sqlQuery`, or `source.type: functionBody` with `source.plsqlFunctionBody` for advanced fallback cases. Legacy bare `source.sqlQuery` remains accepted for backward compatibility but is not the preferred emitted form for new examples.
+
+---
+
+# Geometry Mapping Vocabulary
+
+Use `geometryColumnDataType` in the attached-style map contracts:
+
+| Value | Meaning |
+|-------|---------|
+| `longitudeLatitude` | Separate longitude and latitude columns. |
+| `sdoGeometry` | One spatial geometry column. |
+| `geojson` | One GeoJSON column. |
+
+## Region Shell Output Template
+
+```apexlang
+region {{regionStaticId}} (
+  name: {{name}}
+  type: map
+  layout {
+    sequence: {{layout.sequence}}
+    slot: {{layout.slot}}
+  }
+  appearance {
+    template: @/standard
+    templateOptions: #DEFAULT#
+  }
+  {{layer}}
+)
+```
+
+- Keep controls and region attributes on the region shell and keep geometry mapping inside `initialPositionAndZoom` and `columnMapping`.
+- Metadata export lookup: search for `Map` plus the attached-style block names such as `initialPositionAndZoom`, `source`, and `columnMapping`.
+
+---
+
+# Source Anchors
+
+- `core/apex_install_pe_data.sql`
+- `core/modules/create_app_wiz/wwv_flow_create_app.plb`
+- `builder/f4411/application/shared_components/plugins/region_type/map_region.sql`
+- `core/wwv_flow_map_region.sql`
+- `core/wwv_flow_map_region_dev.sql`
+- `core/wwv_flow_spatial_api.sql`
+- `images/apex_ui/js/pe.callbacks.js`
+- `images/libraries/apex/widget.spatialMap.js`

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

@@ -0,0 +1,54 @@
+---
+templateId: map.index
+componentType: template
+version: 1.1
+imports:
+  - map._common.md
+  - map.layer._common.md
+description: Routing entrypoint for map templates.
+---
+
+# Purpose
+
+Primary routing entrypoint for `map` templates.
+
+# Load Groups
+
+- Family contract: `map._common.md`
+- Layer contract: `map.layer._common.md`
+- Baseline region scenario: `map.standard.md`
+- Page-example entrypoint when the request is page-scaffold-first: `../../page-examples/map-page/map-page._index.md`
+- Region scenarios:
+  - `map.region.background-custom.md`
+  - `map.region.background-shared.md`
+  - `map.region.init-position-sql.md`
+  - `map.region.bbox-static.md`
+  - `map.region.bbox-sql.md`
+  - `map.region.browser-location.md`
+- Geometry qualifier files (load one per map region):
+  - `map.longitude-latitude.md`
+  - `map.sdo-geometry.md`
+  - `map.geojson.md`
+- Layer scenarios:
+  - `map.layer.points.md`
+  - `map.layer.points.sql-query.md`
+  - `map.layer.points.function-body.md`
+  - `map.layer.lines.md`
+  - `map.layer.polygons.md`
+  - `map.layer.heat-map.md`
+  - `map.layer.extruded-polygons.md`
+- Companion references:
+  - `map.backgrounds.md`
+  - `map.runtime-api.md`
+
+# Load Order
+
+1. Load this file.
+2. Load `map._common.md`.
+3. Load `map.layer._common.md` when authoring one or more `layer` blocks.
+4. Load one region scenario template in this folder.
+5. Load one or more layer scenario templates when the chosen region needs non-standard layer behavior.
+7. Load `map.backgrounds.md` when `tileLayerType` uses shared backgrounds.
+8. Load `map.runtime-api.md` only for browser-side API or event behavior.
+
+When the request starts from a page pattern rather than a standalone map region, route through `../../page-examples/map-page/map-page._index.md` first and preserve the attached-style structure: `body`, `initialPositionAndZoom`, declarative `source { ... }`, and `columnMapping.geometryColumnDataType`. Keep table-backed layers as the standard baseline, emit typed `source.type: sqlQuery` for new SQL-backed layers, and reserve `source.type: functionBody` for advanced fallback cases.

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

@@ -0,0 +1,78 @@
+---
+templateId: map.backgrounds
+componentType: template
+version: 1.0
+description: Shared Oracle APEX map-background guidance covering raster, vector, and OGC WMS backgrounds plus API-key and subscription behavior.
+---
+
+# Purpose
+
+Document the `mapBackground` shared component family: raster XYZ tile layers, vector tile-layer style definitions, OGC WMS backgrounds, API-key derivation, HTTP headers, zoom limits, and subscription behavior.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Description |
+|------|----------|------|-------------|
+| `name` | yes | string | Shared-component display name. |
+| `staticId` | yes | string | Application-unique static ID. |
+| `type` | yes | enum | `raster`, `vector`, or OGC WMS. |
+| `url` | yes | string | Background URL. |
+| `attribution` | conditional | text | Used for raster and OGC WMS backgrounds. |
+| `apiKeyType` | optional | enum | none, static value, or web credential. |
+| `apiKey` | conditional | string | Static API-key value. |
+| `apiKeyCredential` | conditional | credential ref | URL Query String Web Credential. |
+| `httpHeaders` | optional | text | Key-value pairs, one per line. |
+| `minZoomLevel` / `maxZoomLevel` | optional | number | Background zoom limits. |
+| subscription fields | optional | subscription | Shared-component subscription metadata. |
+
+---
+
+# Template
+
+```apexlang
+mapBackground {{staticId}} (
+  name: {{name}}
+  staticId: {{staticId}}
+  type: {{type}}
+  url: {{url}}
+  attribution: {{attribution}}
+  apiKeyType: {{apiKeyType}}
+  apiKey: {{apiKey}}
+  apiKeyCredential: {{apiKeyCredential}}
+  httpHeaders: {{httpHeaders}}
+  minZoomLevel: {{minZoomLevel}}
+  maxZoomLevel: {{maxZoomLevel}}
+)
+```
+
+---
+
+# Region Reference Guidance
+
+Use shared backgrounds from a map region when `tileLayerType` selects the shared-component path. The region then chooses one background for standard mode and optionally another for dark mode through the shared background references.
+
+---
+
+# Guardrails
+
+- `type: vector`
+  - The URL must point to a `style.json`-style definition for the vector tile layer.
+- `type: raster`
+  - The URL should resolve XYZ tiles and may include the `{api-key}` placeholder.
+- OGC WMS
+  - Provide the URL with the required WMS parameters except `BBOX`, `WIDTH`, `HEIGHT`, `REQUEST`, `FORMAT`, and `SRS/CRS`; the map region adds those automatically.
+- `attribution` only applies to raster and OGC WMS backgrounds in the current seed metadata.
+- `apiKeyType: webCredential`
+  - The credential must be a URL Query String Web Credential.
+- Background vector-tile usage is still subject to the application-scoped native plugin setting `useVectorTileLayers`.
+
+---
+
+# Source Anchors
+
+- `core/apex_install_pe_data.sql`
+- `core/wwv_flow_imp_shared.sql`
+- `core/gen_api_pkg.plb`
+- `core/wwv_flow_map_region_dev.sql`

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

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

package/skills/apexlang/templates/region-components/map/map.layer._common.md

@@ -0,0 +1,171 @@
+---
+templateId: region.map.layer.common
+componentType: region
+version: 1.0
+imports:
+  - map._common.md
+description: Shared layer contract for Oracle APEX map regions using the attached declarative layer structure.
+---
+
+# Purpose
+
+Standardize `layer` variable contracts, output shape, geometry rules, popup behavior, and source-mode choices for all map-layer scenarios while keeping the standard structure aligned with `MapsLang.apx`.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `map._common.md` before using this layer contract.
+2. Use this file for shared layer rules; keep layer-type-specific behavior in `map.layer.*.md`.
+3. Keep region-level concerns such as tile-layer selection, bbox, and initial position in the region scenario files.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| `name` | yes | string | Unique within the parent map region. |
+| `staticId` | yes | string | Identifier used after the `layer` keyword. |
+| `layout.sequence` | yes | number | Region-owned layer order. |
+| `source.tableName` | conditional | source | Table-backed source mode. Leave `source.type` unset for this canonical simple path. |
+| `source.type` | conditional | enum | Required for typed non-table source modes. Supported values: `sqlQuery`, `functionBody`. |
+| `source.sqlQuery` | conditional | sql | Required when `source.type: sqlQuery`. Legacy bare `source { sqlQuery: ... }` remains accepted for existing artifacts during transition, but new examples should emit the typed form. |
+| `source.plsqlFunctionBody` | conditional | plsql | Required when `source.type: functionBody`. Must return SQL text and is an advanced fallback rather than the preferred default. |
+| `columnMapping.geometryColumnDataType` | yes | enum | `longitudeLatitude`, `sdoGeometry`, or `geojson`. |
+| `columnMapping.geometryColumn` / `columnMapping.longitudeColumn` / `columnMapping.latitudeColumn` | conditional | column | Shape depends on `geometryColumnDataType`. |
+| `columnMapping.primaryKeyColumn` | optional | column | Stable feature identity when needed by the scenario. |
+| `tooltip.column` | optional | column | Standard tooltip source for the layer. |
+| scenario-specific properties | optional | mixed | Additional line, polygon, heat-map, or 3D properties belong in the dedicated layer scenario files. |
+
+---
+
+# Output Template – Table-Backed
+
+```apexlang
+layer {{layer.staticId}} (
+  name: {{layer.name}}
+  layout {
+    sequence: {{layer.layout.sequence}}
+  }
+  source {
+    tableName: {{layer.source.tableName}}
+  }
+  columnMapping {
+    geometryColumnDataType: {{layer.columnMapping.geometryColumnDataType}}
+    geometryColumn: {{layer.columnMapping.geometryColumn}}
+    longitudeColumn: {{layer.columnMapping.longitudeColumn}}
+    latitudeColumn: {{layer.columnMapping.latitudeColumn}}
+    primaryKeyColumn: {{layer.columnMapping.primaryKeyColumn}}
+  }
+  tooltip {
+    column: {{layer.tooltip.column}}
+  }
+)
+```
+
+## Output Template – Typed SQL Query
+
+```apexlang
+layer {{layer.staticId}} (
+  name: {{layer.name}}
+  layout {
+    sequence: {{layer.layout.sequence}}
+  }
+  source {
+    type: sqlQuery
+    sqlQuery:
+      ```sql
+      {{layer.source.sqlQuery}}
+      ```
+  }
+  columnMapping {
+    geometryColumnDataType: {{layer.columnMapping.geometryColumnDataType}}
+    geometryColumn: {{layer.columnMapping.geometryColumn}}
+    longitudeColumn: {{layer.columnMapping.longitudeColumn}}
+    latitudeColumn: {{layer.columnMapping.latitudeColumn}}
+    primaryKeyColumn: {{layer.columnMapping.primaryKeyColumn}}
+  }
+  tooltip {
+    column: {{layer.tooltip.column}}
+  }
+)
+```
+
+## Output Template – Function Body
+
+```apexlang
+layer {{layer.staticId}} (
+  name: {{layer.name}}
+  layout {
+    sequence: {{layer.layout.sequence}}
+  }
+  source {
+    type: functionBody
+    plsqlFunctionBody:
+      ```plsql
+      {{layer.source.plsqlFunctionBody}}
+      ```
+  }
+  columnMapping {
+    geometryColumnDataType: {{layer.columnMapping.geometryColumnDataType}}
+    geometryColumn: {{layer.columnMapping.geometryColumn}}
+    longitudeColumn: {{layer.columnMapping.longitudeColumn}}
+    latitudeColumn: {{layer.columnMapping.latitudeColumn}}
+    primaryKeyColumn: {{layer.columnMapping.primaryKeyColumn}}
+  }
+  tooltip {
+    column: {{layer.tooltip.column}}
+  }
+)
+```
+
+---
+
+# Source-Location Matrix
+
+| Source shape | Main use | Key guardrails |
+|-------------|----------|----------------|
+| `source { tableName: ... }` | Simplest standard map layer | Preferred for the canonical pattern and remains untyped. |
+| `source { type: sqlQuery sqlQuery: ... }` | Custom SQL-backed layer | Preferred emitted form for new SQL-backed map layers. Legacy bare `source { sqlQuery: ... }` is transitional compatibility only. |
+| `source { type: functionBody plsqlFunctionBody: ... }` | Advanced function-backed layer | Use only when table-backed and plain SQL-backed layer sources cannot express the requirement cleanly. |
+
+---
+
+# Geometry Matrix
+
+| Geometry type | Supported when | Notes |
+|--------------|----------------|-------|
+| `sdoGeometry` | Layers use a single spatial column | The column must contain spatial objects. |
+| `geojson` | Layers use a single GeoJSON column | Column may be `VARCHAR2`, `CLOB`, or `BLOB`. |
+| `longitudeLatitude` | Layers expose separate longitude and latitude columns | Standard point-map path in the attached canonical example. |
+
+---
+
+# Popup, Link, And Legend Rules
+
+- Heat-map layers do not expose the normal tooltip, link, or info-window paths.
+- Use `tooltip { column: ... }` as the default popup path for the attached-style standard layer.
+- Context-sensitive SQL-backed layers must use live-valid refresh/session-state patterns for the active compiler. Do not emit unsupported map-layer `source.pageItemsToSubmit`, and do not use `v()`/`nv()` session-state reads as a workaround.
+- Marker edit/open behavior must use a declarative layer `link` with target page and item mappings, backed by `columnMapping.primaryKeyColumn`.
+- Keep line, polygon, and 3D display-specific metadata in the dedicated scenario templates rather than re-expanding the shared base layer shape.
+- `functionBody` is supported for map layers, but it is an advanced escape hatch:
+  - it must return SQL text
+  - it must not perform DML or transaction control
+  - prefer `tableName` first, then typed `sqlQuery`, and use `functionBody` only when those two modes are insufficient
+
+---
+
+# Vector-Tile Guardrails
+
+- Advanced vector-tile-specific properties are intentionally omitted from the attached canonical standard layer shape.
+- If a future runtime or import requirement needs them back, restore them in a dedicated advanced map-layer scenario instead of widening the standard attached-style template.
+
+---
+
+# Source Anchors
+
+- `core/apex_install_pe_data.sql`
+- `core/wwv_flow_imp_page.sql`
+- `core/gen_api_pkg.plb`
+- `images/apex_ui/js/pe.callbacks.js`

package/skills/apexlang/templates/region-components/map/map.layer.extruded-polygons.md

@@ -0,0 +1,74 @@
+---
+templateId: region.map.layer.extruded-polygons
+componentType: region
+version: 1.0
+imports:
+  - map._common.md
+  - map.layer._common.md
+description: Extruded-polygon guidance for Oracle APEX Maps.
+---
+
+# Purpose
+
+Document 3D polygon-layer behavior for Maps: extruded polygon geometry, height-by-value rendering, extrusion unit metadata, and polygon-style fill rules.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- `layer.staticId`
+- `layer.name`
+- `layer.layerType` (use `extrudedPolygons`)
+- `layer.layout.sequence`
+- `layer.source.tableName`
+- `layer.columnMapping.geometryColumnDataType`
+- `layer.feature3dValueColumn`
+- `layer.feature3dValueUnit`
+
+## Optional Variables
+
+- `layer.featureFillColor`
+- `layer.featureFillOpacity`
+- `layer.featureStrokeColor`
+- `layer.featureStrokeWidth`
+
+---
+
+# Template
+
+```apexlang
+layer {{layer.staticId}} (
+  name: {{layer.name}}
+  layerType: extrudedPolygons
+  layout {
+    sequence: {{layer.layout.sequence}}
+  }
+  source {
+    tableName: {{layer.source.tableName}}
+    sqlQuery:
+      ```sql
+      {{layer.source.sqlQuery}}
+      ```
+  }
+  columnMapping {
+    geometryColumnDataType: {{layer.columnMapping.geometryColumnDataType}}
+    geometryColumn: {{layer.columnMapping.geometryColumn}}
+    primaryKeyColumn: {{layer.columnMapping.primaryKeyColumn}}
+  }
+  feature3dValueColumn: {{layer.feature3dValueColumn}}
+  feature3dValueUnit: {{layer.feature3dValueUnit}}
+  featureFillColor: {{layer.featureFillColor}}
+  featureFillOpacity: {{layer.featureFillOpacity}}
+)
+```
+
+---
+
+# Guardrails
+
+- `feature3dValueColumn` is required for `POLYGON_3D`.
+- `feature3dValueUnit` becomes required once the extrusion value column is set.
+- Use polygon geometry for the layer source; extrusion metadata is not a substitute for valid polygon geometry.
+- Extruded polygons share the same fill-color-spectrum rules as normal polygon layers.

package/skills/apexlang/templates/region-components/map/map.layer.heat-map.md

@@ -0,0 +1,73 @@
+---
+templateId: region.map.layer.heat-map
+componentType: region
+version: 1.0
+imports:
+  - map._common.md
+  - map.layer._common.md
+description: Heat-map guidance for Oracle APEX Maps.
+---
+
+# Purpose
+
+Document heat-map behavior for Maps: point-density rendering, heat-map color schemes, and the restrictions that remove normal tooltip, link, and info-window options from heat-map layers.
+
+---
+
+# Variable Contract
+
+## Required Variables
+
+- `layer.staticId`
+- `layer.name`
+- `layer.layerType` (use `heatMap`)
+- `layer.layout.sequence`
+- `layer.source.tableName`
+- `layer.columnMapping.geometryColumnDataType`
+
+## Optional Variables
+
+- `layer.featureHeatmapValueColumn`
+- `layer.layerHeatmapSpectrumType`
+- `layer.layerHeatmap*Name`
+- `layer.layerHeatmapCustomSpectrum`
+
+---
+
+# Template
+
+```apexlang
+layer {{layer.staticId}} (
+  name: {{layer.name}}
+  layerType: heatMap
+  layout {
+    sequence: {{layer.layout.sequence}}
+  }
+  source {
+    tableName: {{layer.source.tableName}}
+    sqlQuery:
+      ```sql
+      {{layer.source.sqlQuery}}
+      ```
+  }
+  columnMapping {
+    geometryColumnDataType: {{layer.columnMapping.geometryColumnDataType}}
+    geometryColumn: {{layer.columnMapping.geometryColumn}}
+    longitudeColumn: {{layer.columnMapping.longitudeColumn}}
+    latitudeColumn: {{layer.columnMapping.latitudeColumn}}
+    primaryKeyColumn: {{layer.columnMapping.primaryKeyColumn}}
+  }
+  featureHeatmapValueColumn: {{layer.featureHeatmapValueColumn}}
+  layerHeatmapSpectrumType: {{layer.layerHeatmapSpectrumType}}
+  layerHeatmapCustomSpectrum: {{layer.layerHeatmapCustomSpectrum}}
+)
+```
+
+---
+
+# Guardrails
+
+- Heat maps are point-only in practice. If the source uses `sdoGeometry` or `geojson`, it must still return point objects.
+- Heat-map layers do not expose the normal tooltip, link-target, or info-window metadata paths.
+- `featureHeatmapValueColumn` is optional. Without it, the widget derives color intensity from point density alone.
+- Use high-contrast color ramps and avoid problematic red-green-only schemes.