@aceshooting/lyra-ui 28.1.6 → 29.0.0

package/llms/components/lr-map.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [media](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/media.md)
 - **Deprecations** none
-- **Optional peers** `maplibre-gl` — see `llms/peers.md`
+- **Optional peers** `@aceshooting/lyra-map`, `maplibre-gl` — see `llms/peers.md`
 - **Themeable via** 26 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -16,7 +16,8 @@
 
 ## `lr-map`
 
-A `maplibre-gl` wrapper with a declarative legend, a single choropleth GeoJSON fill layer, markers,
+A MapLibre-compatible wrapper using the optional `@aceshooting/lyra-map` modular engine by default,
+with a declarative legend, a single choropleth GeoJSON fill layer, markers,
 and additive `dataLayers` — plain GeoJSON, natively clustered points, or a heatmap density surface —
 plus a peer-neutral `map` getter for common imperative operations. Its runtime value is the
 underlying MapLibre map. The component observes its own map-container allocation and calls the
@@ -32,6 +33,11 @@ modes use the same expression semantics at initial render and after a theme chan
 
 **Properties:**
 
+- `engine: LyraMapEngine = 'modular'` — selects the optional `@aceshooting/lyra-map` companion.
+  Set `engine="maplibre"` before connecting to explicitly use the full canonical `maplibre-gl`
+  peer. A missing selected engine shows a localized fallback; it never selects another engine.
+  Later changes take effect after disconnect/reconnect. Native compatibility includes the full
+  engine payload and is a separate opt-in from the modular default.
 - `center: [number, number] = [0, 0]`
 - `zoom: number = 2` — `center` and `zoom` are the declarative camera. Assigning either moves the
   map without emitting anything. When the camera settles after a user gesture or `fitBounds()`, the
@@ -457,18 +463,33 @@ payload beside the map.
 `LyraMapPointRadiusInterpolation`, `LyraMapPointIcon`, `LyraMapPointIconMode`,
 `LyraMapPointIconLineCap`, `LyraMapPointIconLineJoin`, `LyraMapMarker`, `LyraMapMarkerActivationDetail`,
 `LyraMapMarkerActivationSource`, `LyraMapLegendToggleDetail`, `LyraMapLegendPanelToggleDetail`,
-`LyraMapStyleSpecification`, and `LyraMapInstance`.
+`LyraMapStyleSpecification`, `LyraMapEngine`, `LyraMapFeatureRequirements`, and `LyraMapInstance`.
 
 **Getters:** `map: LyraMapInstance | undefined` → the underlying runtime `maplibregl.Map`, exposed
 through the peer-neutral `getCanvas()`, `getCenter()`, `getZoom()`, `setCenter()`, `setZoom()`, and
 `resize()` subset so merely importing Lyra does not require `maplibre-gl` declarations. A consumer
 that installed the optional peer and needs its full imperative API can explicitly narrow the runtime
-value to `maplibregl.Map`.
-
-**Methods:** `LyraMap.preload(): Promise<boolean>` is a static optional-peer warm-up that starts the
-shared `maplibre-gl` import without constructing a map or allocating a WebGL context. It resolves to
-`false` when the peer is unavailable, allowing an application to choose a fallback before connecting
-an element.
+value to the selected engine's `Map` type. `LyraMapInstance.prepareFeatures?()` is present on the
+modular engine and absent on canonical MapLibre, so guard it or narrow to the companion `Map`
+before calling. Identity is preserved: `.map` is the engine instance, not a proxy.
+
+The modular engine automatically prepares initial and replacement style requirements, including
+projection and terrain. `<lr-map>` additionally awaits per-map main-thread and worker readiness
+before adding generated choropleth or `dataLayers` sources and layers. New heatmap, clustering, and
+symbol requirements are prepared when introduced. Failed or superseded preparations never apply
+stale overlays, and disconnect aborts outstanding preparation.
+
+For direct imperative mutations, call `await map.prepareFeatures(requirements, { signal })` with
+actual `sources`, `layers`, `projection`, and `terrain` descriptors before introducing new families
+through synchronous `addSource`, `addLayer`, `setProjection`, or `setTerrain` calls. Requirements use
+`LyraMapFeatureRequirements`; `signal` is optional. A map constructed with `style: null` is initialized
+by this per-map method before those mutations. Global `prepareStyle()` warms main modules only;
+it does not replace per-map worker readiness. Same-family updates remain synchronous after readiness.
+
+**Methods:** `LyraMap.preload(engine: LyraMapEngine = 'modular'): Promise<boolean>` starts the selected
+optional-peer import without constructing a map or allocating a WebGL context. Pass `'maplibre'`
+for an explicitly native element. It resolves to `false` when the selected peer is unavailable,
+allowing an application to choose a fallback before connecting an element.
 
 `fitBounds(bounds: LyraMapBounds, options?: LyraMapFitBoundsOptions): boolean` frames a box
 `[[west, south], [east, north]]` in the viewport: the way to show every current marker, or a
@@ -616,7 +637,7 @@ A swatch rendering an entry's `icon` carries `data-icon="true"`, paints the glyp
 own colour through `currentColor`, and drops the colour block, its border and the `pattern`
 overlay — all three would sit on top of the shape they identify. The glyph stays decorative: the row's
 visible label carries its meaning. That association is advertised only while it is true — while
-the optional `maplibre-gl` peer is still loading, and after any failure, there is no map
+the selected optional map peer is still loading, and after any failure, there is no map
 container in the tree, so `legend` withholds `aria-controls` rather than leaving a dangling
 idref.
 Under `legendInteractive`, a row carrying a `value` wraps its swatch and label in a
@@ -663,8 +684,9 @@ peer unavailable, owner-realm WebGL2 unavailable, or initialization failed. A po
 appended to the document's pre-mounted `[data-lr-live-region="assertive"]` sink rather than making
 shadow chrome live; raw caught errors are never exposed.
 
-**Standard peer controls:** after `lr-map-load`, narrow `.map` to the installed MapLibre peer
-and use `addControl(new NavigationControl(), 'bottom-right')` and
+**Standard peer controls:** after `lr-map-load`, narrow `.map` to the selected engine's `Map`.
+For the default engine, import `NavigationControl` from `@aceshooting/lyra-map/controls/navigation`
+and `ScaleControl` from `@aceshooting/lyra-map/controls/scale`, then use `addControl(new NavigationControl(), 'bottom-right')` and
 `addControl(new ScaleControl({ unit: 'metric' }), 'bottom-left')`. No document-level peer CSS or
 shadow-root modification is needed: navigation buttons, compass glyph, scale bar and control
 corners are styled with Lyra tokens. The corners follow inline start/end under RTL. The legend
@@ -712,20 +734,32 @@ var(--lr-color-brand-quiet), var(--lr-color-mix-partner) var(--lr-color-mix-acti
   control group), `--lr-color-border-subtle` (popup, legend and legend-limit rule edges),
   `--lr-shadow`, `--lr-radius`.
 
-**Optional peer deps:** `maplibre-gl` `>=5 <7` (lazy-loaded). `<lr-map>` styles MapLibre's
-generated canvas, marker, popup, and control DOM inside its shadow root; a page-level MapLibre
-stylesheet is neither required nor able to reach those nodes. MapLibre v5's standard build includes
-its worker. MapLibre v6 is ESM-only, requires WebGL2, and additionally needs its module-worker URL
-configured for the bundler once — the component cannot choose a bundler-specific worker URL. For
-Vite with v6:
+**Optional peer deps:** the default is `@aceshooting/lyra-map` `^1.0.0` (lazy-loaded). Install and
+configure the companion's Vite plugin so the engine and module worker share the same emitted
+feature graph:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { lyraMapWorkerPlugin } from '@aceshooting/lyra-map/vite';
+export default defineConfig({ plugins: [lyraMapWorkerPlugin()] });
+```
+
+The plugin disables document module-preload helpers for chunks also imported by workers. See the
+companion README for Rollup/Rolldown integration or the explicit `setWorkerUrl()` override. Missing
+worker configuration fails visibly. Importing the companion during SSR is safe; worker creation
+occurs in the browser.
+
+`<lr-map>` styles the generated canvas, marker, popup, and control DOM inside its shadow root;
+a page-level map stylesheet is neither required nor able to reach those nodes. The explicit
+`engine="maplibre"` choice uses the separate optional `maplibre-gl` `>=5 <7` peer. Canonical v6 needs
+its own bundler-specific module-worker URL; v5's standard build includes its worker.
+
+With the default companion configured:
 
 ```html
 <lr-map center="[2.35, 48.85]" zoom="10"></lr-map>
 <script type="module">
-  import { setWorkerUrl } from "maplibre-gl";
-  import workerUrl from "maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url";
-  setWorkerUrl(workerUrl);
-
   const m = document.querySelector("lr-map");
   m.mapStyle = { version: 8, sources: {}, layers: [] }; // explicit, network-silent baseline
   m.choropleth = {
@@ -752,8 +786,9 @@ Vite with v6:
 </script>
 ```
 
-Webpack, esbuild, Rollup, and direct-browser ESM use different worker URL forms; use MapLibre's ESM
-installation guide for the matching setup:
+For the explicit canonical engine, configure its worker before connecting the element. For example,
+Vite with MapLibre v6 uses `setWorkerUrl` from `maplibre-gl` with a URL imported from
+`maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url`. Other bundlers use different forms; see
 https://maplibre.org/maplibre-gl-js/docs/#esm.
 
 **Known gotchas:**
@@ -798,7 +833,7 @@ undefined`, or changing `choropleth.sourceId` to a different value, now calls `r
   (notably `url(...)`, which `background` also accepts and would otherwise fetch as soon as the
   swatch renders). The required `pattern` remains distinct in forced colors through solid, dashed,
   dotted, and double border/shape encodings.
-- while the `maplibre-gl` peer is resolving, the host/base expose `aria-busy="true"` and show a
+- while the selected map peer is resolving, the host/base expose `aria-busy="true"` and show a
   decorative `<lr-skeleton shape="rect" announce="false">` in place of the map container.
   Ordinary sr-only text preserves the localized `loading` label without creating a shadow live
   region.

package/llms/index.md

@@ -193,7 +193,7 @@ Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.m
 
 - `lr-flag` · lr-flag.js · `stable` since `4.0.0` — a country/language flag.
 - `lr-sequence-playback` · lr-sequence-playback.js · `stable` since `9.0.0` — steps a current index through `[0, itemCount)` on a fixed interval (play/pause), the common building block behind ad-hoc play-timers in t...
-- `lr-map` · lr-map.js · `stable` since `4.0.0` — a maplibre-gl wrapper with a declarative legend, choropleth GeoJSON layer, markers, and additive `dataLayers` GeoJSON overlays (arbitrary...
+- `lr-map` · lr-map.js · `stable` since `4.0.0` — a modular MapLibre-compatible wrapper with a declarative legend, choropleth GeoJSON layer, markers, and additive `dataLayers` GeoJSON ove...
 - `lr-drop-zone` · lr-drop-zone.js · `experimental` since `16.0.0` — - a drag-and-drop region wrapper with no file input of its own.
 - `lr-file-input` · lr-file-input.js · `stable` since `4.0.0` — a drag-drop + click-to-browse file dropzone.
 - `lr-image-comparer` · lr-image-comparer.js · `stable` since `4.0.0` — compares two slotted surfaces with a keyboard- accessible range divider.

package/llms/peers.md

@@ -2,14 +2,14 @@
 
 # Optional peer dependencies
 
-All 30 peers are **optional**: nothing here is needed to install or use the library,
+All 31 peers are **optional**: nothing here is needed to install or use the library,
 but they have two deliberately different roles.
 
 **Framework declaration peers (3).** React, Svelte, and Vue are compile-time peers
 only when a project imports their matching opt-in declaration entry. Those entry points emit empty
 JavaScript, no component imports these frameworks, and Lyra ships no runtime wrapper.
 
-**Component-loaded peers (27).** No component imports one eagerly. Install a
+**Component-loaded peers (28).** No component imports one eagerly. Install a
 peer only when you use a component that needs it.
 
 **How they load.** Most component-loaded peers resolve through a dynamic `import()` on first use.
@@ -38,7 +38,8 @@ for the page.
 | Peer | Range | Needed by |
 |---|---|---|
 | `@aceshooting/lyra-flags` | `^2.3.0` | _(loaded by a shared internal module)_ |
-| `@aceshooting/lyra-translations` | `^28.1.6` | _(not referenced by any component)_ |
+| `@aceshooting/lyra-map` | `^1.0.0` | `lr-geojson-viewer`, `lr-map` |
+| `@aceshooting/lyra-translations` | `^29.0.0` | _(not referenced by any component)_ |
 | `@aiden0z/pptx-renderer` | `^1.3.0` | `lr-pptx-viewer` |
 | `@sgratzl/chartjs-chart-boxplot` | `^4.0.0` | `lr-box-plot` |
 | `chart.js` | `^4.0.1` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |

package/llms/shared/ai-and-peers.md

@@ -118,7 +118,7 @@ preferred in production.
 
 ## Optional peer dependencies
 
-All 30 peers are optional, in two groups. The 27 component-facing peers remain outside the default
+All 31 peers are optional, in two groups. The 28 component-facing peers remain outside the default
 install; components load them on demand where applicable. React, Svelte, and Vue are
 compile-time-only peers for their matching
 opt-in declaration entries (`custom-elements-jsx`, `svelte`, and `vue`): those entries emit empty
@@ -134,7 +134,7 @@ adapter (`loadLibphonenumberAdapter()`) rather than importing `libphonenumber-js
 ### Experimental DOCX editing companion
 
 Use `@aceshooting/lyra-docs` for editing; `lr-docx-viewer` remains a viewer in Lyra UI.
-The companion uses optional `@docx-editor.dev/core@2.27.0`. Its installed README owns
+The companion bundles a lazily loaded document engine. Its installed README owns
 installation, admission limits, lifecycle, exact supported structures and save receipts.
 
 ```ts
@@ -149,7 +149,8 @@ replace-and-advance, Outline, Checks and Review panels, table formatting and loc
 image tools. `createDocxSession({ mount })` supports a host-owned toolbar; it requires a
 connected empty light-DOM mount. Both routes expose `can()`/`execute()`, `find()`/
 `selectMatch()`/`replaceMatch()`, `outline()`/`selectOutlineItem()`, `inspectDocument()`/
-`selectDiagnostic()`, and `review()`/`selectReviewItem()`. Query rows are copied, bounded
+`selectDiagnostic()`, and `review()`/`selectReviewItem()`. Await `execute()` before inspecting its
+result or issuing a dependent command; it includes any required feature preparation. Query rows are copied, bounded
 and revision-scoped; refresh after edits and pass the returned `expectedRevision` when
 navigating. Queries do not save or fetch. Inspection covers body metadata only; capability
 fields `preserved`, `renderable` and `editable` remain `unverified`, and the report is not

package/llms/shared/imports-and-registration.md

@@ -164,7 +164,7 @@ The entry points, then:
   `lr-scatter-chart`), `lr-box-plot`, `lr-histogram`, `lr-map`, `lr-graph`,
   `lr-knowledge-graph-explorer` and `lr-geojson-viewer`. Those always need their own subpath import,
   from `all.js` exactly as from the root — the entry deliberately preserves the optional-peer
-  isolation contract rather than putting `chart.js`, `maplibre-gl`, or the `d3-*` set on the
+  isolation contract rather than putting `chart.js`, `@aceshooting/lyra-map`, `maplibre-gl`, or the `d3-*` set on the
   critical path of every install. It is the one import that defeats tree-shaking.
   (Server-side, `@aceshooting/lyra-ui/ssr/all.js` is the counterpart that _does_ register the
   complete inventory, optional-peer families included; see "SSR and declarative shadow DOM".)

package/llms/shared.md

@@ -163,7 +163,7 @@ The entry points, then:
   `lr-scatter-chart`), `lr-box-plot`, `lr-histogram`, `lr-map`, `lr-graph`,
   `lr-knowledge-graph-explorer` and `lr-geojson-viewer`. Those always need their own subpath import,
   from `all.js` exactly as from the root — the entry deliberately preserves the optional-peer
-  isolation contract rather than putting `chart.js`, `maplibre-gl`, or the `d3-*` set on the
+  isolation contract rather than putting `chart.js`, `@aceshooting/lyra-map`, `maplibre-gl`, or the `d3-*` set on the
   critical path of every install. It is the one import that defeats tree-shaking.
   (Server-side, `@aceshooting/lyra-ui/ssr/all.js` is the counterpart that _does_ register the
   complete inventory, optional-peer families included; see "SSR and declarative shadow DOM".)
@@ -2706,7 +2706,7 @@ preferred in production.
 
 ## Optional peer dependencies
 
-All 30 peers are optional, in two groups. The 27 component-facing peers remain outside the default
+All 31 peers are optional, in two groups. The 28 component-facing peers remain outside the default
 install; components load them on demand where applicable. React, Svelte, and Vue are
 compile-time-only peers for their matching
 opt-in declaration entries (`custom-elements-jsx`, `svelte`, and `vue`): those entries emit empty
@@ -2722,7 +2722,7 @@ adapter (`loadLibphonenumberAdapter()`) rather than importing `libphonenumber-js
 ### Experimental DOCX editing companion
 
 Use `@aceshooting/lyra-docs` for editing; `lr-docx-viewer` remains a viewer in Lyra UI.
-The companion uses optional `@docx-editor.dev/core@2.27.0`. Its installed README owns
+The companion bundles a lazily loaded document engine. Its installed README owns
 installation, admission limits, lifecycle, exact supported structures and save receipts.
 
 ```ts
@@ -2737,7 +2737,8 @@ replace-and-advance, Outline, Checks and Review panels, table formatting and loc
 image tools. `createDocxSession({ mount })` supports a host-owned toolbar; it requires a
 connected empty light-DOM mount. Both routes expose `can()`/`execute()`, `find()`/
 `selectMatch()`/`replaceMatch()`, `outline()`/`selectOutlineItem()`, `inspectDocument()`/
-`selectDiagnostic()`, and `review()`/`selectReviewItem()`. Query rows are copied, bounded
+`selectDiagnostic()`, and `review()`/`selectReviewItem()`. Await `execute()` before inspecting its
+result or issuing a dependent command; it includes any required feature preparation. Query rows are copied, bounded
 and revision-scoped; refresh after edits and pass the returned `expectedRevision` when
 navigating. Queries do not save or fetch. Inspection covers body metadata only; capability
 fields `preserved`, `renderable` and `editable` remain `unverified`, and the report is not