@nika-js/onlymap 0.4.1 → 0.4.3

package/README.md

@@ -69,7 +69,7 @@ Or with no build step at all, straight from a CDN:
 
 The bare package URL serves `dist/onlymap.standalone.js`, a single-file bundle built for exactly this (jsDelivr too). Use a CDN that serves the package's raw files — **not** a rebundling CDN like esm.sh, which re-splits the bundle into duplicate copies of the deck.gl/luma.gl runtime and breaks every layer's shader compilation.
 
-Then `npx @nika-js/onlymap init` wires up VS Code IntelliSense and `!`-prefixed manifest snippets for your project. The library ships with 518 unit/behavioral tests and 41 Playwright GPU tests.
+Then `npx @nika-js/onlymap init` wires up VS Code IntelliSense and `!`-prefixed manifest snippets for your project. The library ships with 528 unit/behavioral tests and 45 Playwright GPU tests.
 
 The [examples](https://github.com/NikaGeospatial/onlymapjs/tree/main/examples) are the best tour: widgets, behaviors & overlays, basemaps, columnar/Arrow data, manual drawing, 3D models, scene lighting (with the native lighting widget), DEM terrain, a live WebSocket ship feed, and a polled driver fleet.
 
@@ -81,7 +81,7 @@ A handful of elements, one rule: **attributes are kebab-case versions of deck.gl
 |---|---|
 | `<om-map>` | The map. `center`, `zoom`, `pitch`, `bearing`; `basemap` takes a free preset (`positron`, `liberty`, `dark-matter`, `osm`, …), a style URL, or `"none"` (standalone canvas) — and switches **live**; `validate` for a live on-page error panel. |
 | `<om-layer>` | Any of **34 layer types** by name — all of deck.gl's core, geo, aggregation, and mesh layers (Scatterplot, GeoJson, Arc, Path, Heatmap, Hexagon, Trips, Tile, Tile3D, Scenegraph, …) plus the built-in `PopupLayer` for WebGL badges/labels at scale and the native `COGLayer` for GeoTIFF rasters. `id` required; `label`/`color` feed the legend. |
-| `<om-widget>` | UI panels. Built-ins: `legend` (symbology-aware: color scales render as gradient ramps or class ranges, categorical ternaries as discrete palettes), `layer-switcher`, `basemap-switcher`, `lighting`, `zoom-controls`, `undo-redo`, `scale-bar`, `attribution`, `filter`, `draw`, `vega-lite` (live charts). Or write your own inline with HTML + a `<script type="om/widget">`. **Placement is managed**: `position` takes one of 8 logical, RTL-aware slots (`top-start`, `top-center`, `top-end`, `center-start`, `center-end`, `bottom-start`, `bottom-center`, `bottom-end`; legacy corner names alias) — same-slot widgets stack with flush edges and a shared gap, `order` sets in-slot ordering, and `position="manual"` opts out entirely (a plain block you style yourself, even outside the map). Themeable from plain page CSS via custom properties: `om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }` (also `-muted`, `-border`, `-hover-bg`, `-accent`), plus layout tokens (`--om-widget-inset-x/-y`, `--om-widget-gap-x/-y`, `--om-widget-opacity`, `--om-widget-radius`) or the no-CSS sugar `<om-map widget-style="gap:10 opacity:0.9">`. |
+| `<om-widget>` | UI panels. Built-ins: `legend` (symbology-aware: color scales render as gradient ramps or class ranges, categorical ternaries as discrete palettes), `layer-switcher`, `basemap-switcher`, `lighting`, `zoom-controls`, `undo-redo`, `scale-bar`, `attribution`, `filter`, `draw`, `vega-lite` (live charts). Or write your own inline with HTML + a `<script type="om/widget">`. Adjacent compact button widgets (`zoom-controls`, `undo-redo`, `widgets-toggle`) **auto-cluster** into one control group (opt out per widget with `cluster="false"`), and `<om-map widgets-hidden>` / the `set-widgets-visible` action / `<om-widget type="widgets-toggle">` hide all chrome without destroying it — attribution never hides. **Placement is managed**: `position` takes one of 8 logical, RTL-aware slots (`top-start`, `top-center`, `top-end`, `center-start`, `center-end`, `bottom-start`, `bottom-center`, `bottom-end`; legacy corner names alias) — same-slot widgets stack with flush edges and a shared gap, `order` sets in-slot ordering, and `position="manual"` opts out entirely (a plain block you style yourself, even outside the map). A slot dims automatically while an open popup covers it (`widgets-dim="off"` to disable). Themeable from plain page CSS via custom properties: `om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }` (also `-muted`, `-border`, `-hover-bg`, `-accent`), plus layout tokens (`--om-widget-inset-x/-y`, `--om-widget-gap-x/-y`, `--om-widget-opacity`, `--om-widget-radius`) or the no-CSS sugar `<om-map widget-style="gap:10 opacity:0.9">`. |
 | `<om-overlay>` | Rich HTML anchored to a map location — a static `anchor="[lng, lat]"`, the current selection, or a feature's own geometry via `anchor-layer`/`anchor-feature-id`. `{{field}}` interpolates the picked feature, HTML-escaped by default. |
 | `<om-behavior>` | Declarative interactions: `on="click|hover|drag|load|data-loaded"` → a named action. |
 | `<om-story>` | A storyboard: `<om-step>` children fire actions on a timeline. Controlled by the `player` widget, behaviors, or `storyEl.play()/pause()/seek()`. |

package/dist/{LercDecode.es-B35eeLUh.js → LercDecode.es-peqB7bxk.js}

@@ -19,7 +19,7 @@ async function v(N = {}) {
   if (n) {
     const { createRequire: I } = await import(
       /*webpackIgnore:true*/
-      "./lerc-filCwJiM.js"
+      "./lerc-DEpGyngt.js"
     ).then((g) => g._);
     var O = I(import.meta.url);
   }

package/dist/{basemap--znNIrJq.js → basemap-BeKuGQJs.js}

@@ -1,4 +1,4 @@
-import { C as ny, L as sy, M as oy, m as ay, c as ka, z as oc, a as Sd, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-BKiyX-jQ.js";
+import { C as ny, L as sy, M as oy, m as ay, c as ka, z as oc, a as Sd, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-DzyVbu_T.js";
 const Cd = Math.PI / 180, gy = 180 / Math.PI;
 function em(Pe, Q = 0) {
   const ge = Math.min(180, Pe) * Cd;

package/dist/elements/om-map.d.ts

@@ -28,6 +28,15 @@ import type { Selection } from "../selection";
 import type { MapViewport } from "../basemap";
 interface OverlayHost {
     updatePosition(viewport: MapViewport | undefined, selection: Selection | null): void;
+    /**
+     * Screen rect for collision-dim (spec: "Overlap avoidance") — non-null
+     * only when the overlay is VISIBLE and participates in dimming. Returns
+     * null when hidden OR when it's transient runtime chrome (the internal
+     * hover tooltip / trace / draw preview): those glide constantly and must
+     * not flicker widgets. The map reads this off its registered host set
+     * rather than re-querying the DOM.
+     */
+    getVisibleRect(): DOMRect | null;
 }
 export declare class OmMapElement extends HTMLElementBase {
     private core;
@@ -57,7 +66,12 @@ export declare class OmMapElement extends HTMLElementBase {
     /** Library-owned stacking layer: one absolutely-positioned flex container per managed slot, created lazily. Rendering plumbing, never authored state. */
     private widgetLayer;
     private readonly slotContainers;
-    /** Is this node the widget layer or one of its slot containers? (Their childList churn is plumbing, not manifest edits.) */
+    /**
+     * Is this node layout plumbing (the widget layer, slot containers, or
+     * cluster wrappers)? Their childList churn is rendering, not manifest
+     * edits. om-widget elements themselves are NOT plumbing — their attribute
+     * edits stay manifest-visible.
+     */
     private isWidgetLayoutPlumbing;
     /**
      * Places an <om-widget> into its managed slot container (creating layer/
@@ -71,6 +85,32 @@ export declare class OmMapElement extends HTMLElementBase {
     /** The widget layer div — lazy, shared by slot containers AND the layout tokens (both lanes put tokens on the layer, never on an authored element). */
     private ensureWidgetLayer;
     slotWidgetInternal(el: HTMLElement, slot: WidgetSlot): void;
+    private clusterPassPending;
+    /** Re-entry guard: the pass's own reparenting fires connect callbacks that call back into scheduleClusterPass — self-inflicted, never re-schedule. */
+    private inClusterPass;
+    /** Microtask-coalesced: one pass per placement burst (boot slots N widgets). */
+    private scheduleClusterPass;
+    /**
+     * Re-derives cluster wrappers in every slot container: runs of ≥2
+     * adjacent compact widgets (in VISUAL order — `order` attr, then DOM)
+     * merge into one `data-om-cluster` wrapper div carrying the group's
+     * radius/shadow/divider look; the widgets' own shells flatten via the
+     * `clustered` class they toggle at render. Unwrap-then-rewrap per pass:
+     * wrappers are cheap plumbing divs, and idempotence beats bookkeeping.
+     * Members hidden by hide-all are excluded — a hidden widget can't cluster,
+     * so a group never leaves a ghost wrapper pill around invisible members.
+     * The re-entry guard is inline (the pass's own reparenting fires connect
+     * callbacks that call back into scheduleClusterPass — self-inflicted).
+     */
+    private runClusterPass;
+    /**
+     * `widgets-hidden` — visibility:hidden + pointer-events:none on every
+     * widget EXCEPT attribution and the toggle itself (attribution never
+     * hides — license compliance). Never removal: an open listbox or
+     * mid-scrub slider survives. Inline styles are history-excluded plumbing.
+     */
+    private applyWidgetsHidden;
+    private applyHiddenToWidget;
     /** Custom properties applied from widget-style — tracked so an edit reverts removed pairs to their defaults (CSSStyleDeclaration iteration of custom props is not portable). */
     private appliedWidgetStyleProps;
     /**
@@ -94,6 +134,17 @@ export declare class OmMapElement extends HTMLElementBase {
      * multiple viewport/selection changes per frame into one DOM pass).
      */
     private scheduleOverlayFlush;
+    /**
+     * Dynamic overlap avoidance (spec: "Widget Layout Manager / Overlap
+     * avoidance") — a slot container whose rect intersects an OPEN
+     * `<om-overlay>` popup is dimmed (`--om-widget-opacity-dimmed`, default
+     * 0.35) rather than repositioned. Own overlays only (issue Q1: foreign
+     * absolutely-positioned DOM is unknowable). `widgets-dim="off"` opts out.
+     * Real-geometry only — verified behaviorally in the layout audit, never
+     * modeled (headless has no rects; this no-ops there).
+     */
+    private dimSlotsAgainstOverlays;
+    private slotHasNeverHidesWidget;
     emit(event: string, payload?: Record<string, unknown>): void;
     /** Recenters (and optionally rezooms) the map — instant, not an animated fly. */
     flyTo(coords: [number, number], zoom?: number, opts?: {

package/dist/elements/om-overlay.d.ts

@@ -78,5 +78,13 @@ export declare class OmOverlayElement extends HTMLElementBase {
      * static `anchor="[lng,lat]"`), culls off-screen/behind-camera anchors,
      * and re-interpolates `{{field}}` tokens against the current selection.
      */
+    /**
+     * Screen rect for collision-dim (spec: "Overlap avoidance") — null when
+     * hidden (via COMPUTED visibility, so author CSS/class hiding counts too,
+     * not just our inline write) or when this is transient runtime chrome
+     * (`__onlymapjs-` tooltip/trace/draw preview, which glides on hover and
+     * must not flicker widgets). Only stable author popups drive dimming.
+     */
+    getVisibleRect(): DOMRect | null;
     updatePosition(viewport: MapViewport | undefined, selection: Selection | null): void;
 }

package/dist/html-data.d.ts

@@ -15,9 +15,9 @@ interface TagData {
     }[];
 }
 /** Hand-authored action list — validated against hasAction() in html-data.test.ts. */
-export declare const BUILTIN_ACTIONS: readonly ["toggle-layer", "zoom-in", "zoom-out", "filter-layer", "highlight-feature", "fade", "pulse", "populate", "trace", "story-play", "story-pause", "story-seek", "fly-to", "zoom-to-feature", "show-overlay", "hide-overlay", "show-tooltip", "hide-tooltip", "draw-mode", "draw-commit", "draw-cancel", "draw-delete", "draw-clear", "draw-config", "draw-save", "set-basemap", "set-lighting", "set-terrain", "undo", "redo"];
+export declare const BUILTIN_ACTIONS: readonly ["toggle-layer", "zoom-in", "zoom-out", "filter-layer", "highlight-feature", "fade", "pulse", "populate", "trace", "story-play", "story-pause", "story-seek", "fly-to", "zoom-to-feature", "show-overlay", "hide-overlay", "show-tooltip", "hide-tooltip", "draw-mode", "draw-commit", "draw-cancel", "draw-delete", "draw-clear", "draw-config", "draw-save", "set-basemap", "set-lighting", "set-terrain", "set-widgets-visible", "undo", "redo"];
 /** Hand-authored widget types — validated against the widget registry in html-data.test.ts. */
-export declare const BUILTIN_WIDGETS: readonly ["legend", "layer-switcher", "zoom-controls", "scale-bar", "attribution", "filter", "vega-lite", "player", "draw", "basemap-switcher", "lighting", "undo-redo"];
+export declare const BUILTIN_WIDGETS: readonly ["legend", "layer-switcher", "zoom-controls", "scale-bar", "attribution", "filter", "vega-lite", "player", "draw", "basemap-switcher", "lighting", "undo-redo", "widgets-toggle"];
 export declare function buildHtmlCustomData(): {
     version: number;
     tags: TagData[];

package/dist/{index-CHmCCmPV.js → index-BKU3HvOO.js}

@@ -1,4 +1,4 @@
-import { ai as Bt, ak as Xt, al as Yt, am as Us } from "./index-BKiyX-jQ.js";
+import { ai as Bt, ak as Xt, al as Yt, am as Us } from "./index-DzyVbu_T.js";
 import { w as gs, t as Hs, f as Ws, m as Qs } from "./mgrs-BY9bIvp4.js";
 import { c as Xs } from "./convert-arrow-schema-DrAihRf9.js";
 import { y as Ys, A as bt, a as Ks, z as Vs, R as Zs } from "./recordbatch-Bpc0uxFn.js";

package/dist/{index-C8twrrDP.js → index-BPKvpqIk.js}

@@ -1,5 +1,5 @@
-import { i as E, j as S, k as R, n as N, o as h, p as w, q as O, s as W, r as x, t as I, v as B, w as _, x as P, y as k, A as $, B as z, E as v, F, H as C, I as U, J as p, K as M } from "./index-BKiyX-jQ.js";
-import { N as $e, R as ze, _ as ve, O as Ce, P as Ue, Q as Me, S as je, T as De, U as Je, X as qe, Y as He, Z as Ve, $ as Ge, a0 as Ke, a1 as Qe, a2 as Xe, a3 as Ye, a4 as Ze, a5 as et, a6 as tt, a7 as nt, a8 as rt, a9 as at, aa as st, ab as ot } from "./index-BKiyX-jQ.js";
+import { i as E, j as S, k as R, n as N, o as h, p as w, q as O, s as W, r as x, t as I, v as B, w as _, x as P, y as k, A as $, B as z, E as v, F, H as C, I as U, J as p, K as M } from "./index-DzyVbu_T.js";
+import { N as $e, R as ze, _ as ve, O as Ce, P as Ue, Q as Me, S as je, T as De, U as Je, X as qe, Y as He, Z as Ve, $ as Ge, a0 as Ke, a1 as Qe, a2 as Xe, a3 as Ye, a4 as Ze, a5 as et, a6 as tt, a7 as nt, a8 as rt, a9 as at, aa as st, ab as ot } from "./index-DzyVbu_T.js";
 import { g as j, i as D } from "./table-accessors-CYWTzpQI.js";
 async function J(t, e, n = {}, r = {}) {
   const a = E(t), s = S.getWorkerFarm(n), { source: o } = n, c = { name: a, source: o };

package/dist/{index-_K3U-Ww1.js → index-DVnTYF5u.js}

@@ -1,4 +1,4 @@
-import { ae as Be, af as le, ag as ce, ah as De, ai as Oe, aj as ke } from "./index-BKiyX-jQ.js";
+import { ae as Be, af as le, ag as ce, ah as De, ai as Oe, aj as ke } from "./index-DzyVbu_T.js";
 import { y as ve, a as he, z as G, R as J, A as ue, C as Fe, F as je, n as xe, S as Ie, E as Ne } from "./recordbatch-Bpc0uxFn.js";
 import { g as V, a as fe, b as Le, c as Ue, d as Me, e as qe, m as Ve } from "./table-accessors-CYWTzpQI.js";
 import { c as $e } from "./convert-arrow-schema-DrAihRf9.js";

package/dist/{index-ClqgDar6.js → index-Dg8SKcgV.js}

@@ -1,4 +1,4 @@
-import { ac as _t, ad as Ct } from "./index-BKiyX-jQ.js";
+import { ac as _t, ad as Ct } from "./index-DzyVbu_T.js";
 function Yt(e, r, t = 2, i, o = "xy") {
   const s = r && r.length, l = s ? r[0] * t : e.length;
   let c = Ut(e, 0, l, t, !0, i && i[0], o);