@nika-js/onlymap 0.4.0 → 0.4.2

package/dist/react.js

@@ -1,151 +1,144 @@
-var U = Object.defineProperty;
-var X = (e, t, s) => t in e ? U(e, t, { enumerable: !0, configurable: !0, writable: !0, value: s }) : e[t] = s;
-var A = (e, t, s) => X(e, typeof t != "symbol" ? t + "" : t, s);
-import { jsxs as Y, jsx as P } from "react/jsx-runtime";
-import { createContext as Z, useContext as ee, forwardRef as te, useRef as m, useState as W, useCallback as re, useMemo as T, useLayoutEffect as ne, useEffect as p, useImperativeHandle as se, useSyncExternalStore as H } from "react";
-import { MapController as oe, isStoreToken as le } from "@nika-js/onlymap";
-import { createPortal as G } from "react-dom";
-const J = Z(null);
-function K(e) {
-  const t = ee(J);
-  if (!t) throw new Error(`[onlymapjs] ${e} must be rendered inside <OmMap>.`);
-  return t;
+var Z = Object.defineProperty;
+var ee = (t, e, n) => e in t ? Z(t, e, { enumerable: !0, configurable: !0, writable: !0, value: n }) : t[e] = n;
+var B = (t, e, n) => ee(t, typeof e != "symbol" ? e + "" : e, n);
+import { jsxs as te, jsx as w } from "react/jsx-runtime";
+import { createContext as re, useContext as ne, forwardRef as se, useRef as m, useState as V, useCallback as oe, useMemo as x, useLayoutEffect as ie, useEffect as E, useImperativeHandle as ae, useSyncExternalStore as J } from "react";
+import { MANAGED_SLOTS as ce, slotContainerStyle as le, MapController as ue, parseWidgetStyle as de, resolveSlot as fe, isStoreToken as ye } from "@nika-js/onlymap";
+import { createPortal as Y } from "react-dom";
+const Q = re(null);
+function z(t) {
+  const e = ne(Q);
+  if (!e) throw new Error(`[onlymapjs] ${t} must be rendered inside <OmMap>.`);
+  return e;
 }
-function D(e, t) {
-  if (e === t) return !0;
-  const s = Object.keys(e ?? {}), r = Object.keys(t ?? {});
-  return s.length !== r.length ? !1 : s.every((a) => e[a] === t[a]);
+function W(t, e) {
+  if (t === e) return !0;
+  const n = Object.keys(t ?? {}), r = Object.keys(e ?? {});
+  return n.length !== r.length ? !1 : n.every((l) => t[l] === e[l]);
 }
-function ie(e, t) {
-  const { props: s, updateTriggers: r, ...a } = e, { props: u, updateTriggers: c, ...o } = t;
-  return D(a, o) && D(s, u) && D(r, c);
+function me(t, e) {
+  const { props: n, updateTriggers: r, ...l } = t, { props: d, updateTriggers: c, ...o } = e;
+  return W(l, o) && W(n, d) && W(r, c);
 }
-class ae {
-  constructor(t) {
-    A(this, "descriptors", /* @__PURE__ */ new Map());
-    this.controller = t;
+class ge {
+  constructor(e) {
+    B(this, "descriptors", /* @__PURE__ */ new Map());
+    this.controller = e;
   }
-  upsert(t) {
-    const s = this.descriptors.get(t.id);
-    s && ie(s, t) || (this.descriptors.set(t.id, t), this.controller.setLayers([...this.descriptors.values()]));
+  upsert(e) {
+    const n = this.descriptors.get(e.id);
+    n && me(n, e) || (this.descriptors.set(e.id, e), this.controller.setLayers([...this.descriptors.values()]));
   }
-  remove(t) {
-    this.descriptors.delete(t) && this.controller.setLayers([...this.descriptors.values()]);
+  remove(e) {
+    this.descriptors.delete(e) && this.controller.setLayers([...this.descriptors.values()]);
   }
 }
-const q = ["top-left", "top-right", "bottom-left", "bottom-right"];
-function ce(e) {
-  return {
-    position: "absolute",
-    [e.startsWith("top") ? "top" : "bottom"]: 10,
-    [e.endsWith("left") ? "left" : "right"]: 10,
-    display: "flex",
-    flexDirection: "column",
-    gap: 8,
-    alignItems: e.endsWith("left") ? "flex-start" : "flex-end",
-    zIndex: 20,
-    // The container never intercepts the map's pointer events; each
-    // <OmWidget> shell re-enables its own.
-    pointerEvents: "none"
-  };
-}
-function ue(e, t) {
-  return Object.entries(t).some(([s, r]) => r !== void 0 && e[s] !== r);
+const $ = ce, he = Object.fromEntries($.map((t) => [t, le(t)]));
+function be(t, e) {
+  return Object.entries(e).some(([n, r]) => r !== void 0 && t[n] !== r);
 }
-const ve = te(function(t, s) {
-  const { center: r, zoom: a, pitch: u, bearing: c, basemap: o, basemapKey: l, attribution: d, headless: f, className: w, style: L, children: b } = t, h = m(null), [n, S] = W(null), [g, C] = W(null), [O, E] = W({
-    "top-left": null,
-    "top-right": null,
-    "bottom-left": null,
-    "bottom-right": null
-  }), R = re((i) => {
-    C((y) => y === i ? y : i);
-  }, []), j = T(
+const Ce = se(function(e, n) {
+  const { center: r, zoom: l, pitch: d, bearing: c, basemap: o, basemapKey: a, attribution: f, headless: u, widgetStyle: v, widgetsHidden: L, className: h, style: b, children: g } = e, p = m(null), [s, R] = V(null), [S, T] = V(null), [O, k] = V(
+    () => Object.fromEntries($.map((i) => [i, null]))
+  ), j = oe((i) => {
+    T((y) => y === i ? y : i);
+  }, []), P = x(
     () => Object.fromEntries(
-      q.map((i) => [
+      $.map((i) => [
         i,
         (y) => {
-          E((M) => M[i] === y ? M : { ...M, [i]: y });
+          k((M) => M[i] === y ? M : { ...M, [i]: y });
         }
       ])
     ),
     []
-  ), k = m({ center: r, zoom: a, pitch: u, bearing: c });
-  k.current = { center: r, zoom: a, pitch: u, bearing: c };
-  const x = m(t.onReady);
-  x.current = t.onReady;
-  const v = m(t.onViewStateChange);
-  v.current = t.onViewStateChange;
-  const F = m(t.onRuntimeError);
-  F.current = t.onRuntimeError;
-  const $ = m(o);
-  $.current = o;
-  const z = m(void 0), Q = f ? JSON.stringify(f) : "";
-  ne(() => {
-    if (!h.current) return;
-    const i = k.current;
-    z.current = $.current;
-    const y = new oe(h.current, {
+  ), _ = m({ center: r, zoom: l, pitch: d, bearing: c });
+  _.current = { center: r, zoom: l, pitch: d, bearing: c };
+  const F = m(e.onReady);
+  F.current = e.onReady;
+  const C = m(e.onViewStateChange);
+  C.current = e.onViewStateChange;
+  const K = m(e.onRuntimeError);
+  K.current = e.onRuntimeError;
+  const A = m(o);
+  A.current = o;
+  const D = m(void 0), U = u ? JSON.stringify(u) : "";
+  ie(() => {
+    if (!p.current) return;
+    const i = _.current;
+    D.current = A.current;
+    const y = new ue(p.current, {
       center: i.center,
       zoom: i.zoom,
       pitch: i.pitch,
       bearing: i.bearing,
-      basemap: $.current,
-      basemapKey: l,
-      attribution: d,
-      headless: f ? f === !0 ? {} : f : void 0,
+      basemap: A.current,
+      basemapKey: a,
+      attribution: f,
+      headless: u ? u === !0 ? {} : u : void 0,
       onRuntimeError: (I) => {
-        var _;
-        return (_ = F.current) == null ? void 0 : _.call(F, I);
+        var q;
+        return (q = K.current) == null ? void 0 : q.call(K, I);
       }
     });
-    S(y);
+    R(y);
     let M = !0;
     return y.ready.then(() => {
       var I;
-      M && ((I = x.current) == null || I.call(x));
+      M && ((I = F.current) == null || I.call(F));
     }), () => {
-      M = !1, S(null), y.destroy();
+      M = !1, R(null), y.destroy();
     };
-  }, [Q]), p(() => {
-    !n || z.current === o || (z.current = o, n.setBasemap(o ?? null));
-  }, [n, o]), se(s, () => n, [n]), p(() => {
-    if (!n) return;
-    const i = { longitude: r == null ? void 0 : r[0], latitude: r == null ? void 0 : r[1], zoom: a, pitch: u, bearing: c };
-    ue(n.getViewState(), i) && n.setView(i);
-  }, [n, r == null ? void 0 : r[0], r == null ? void 0 : r[1], a, u, c]), p(() => {
+  }, [U]), E(() => {
+    !s || D.current === o || (D.current = o, s.setBasemap(o ?? null));
+  }, [s, o]), ae(n, () => s, [s]), E(() => {
+    if (!s) return;
+    const i = { longitude: r == null ? void 0 : r[0], latitude: r == null ? void 0 : r[1], zoom: l, pitch: d, bearing: c };
+    be(s.getViewState(), i) && s.setView(i);
+  }, [s, r == null ? void 0 : r[0], r == null ? void 0 : r[1], l, d, c]), E(() => {
     var i;
-    if (n)
-      return (i = v.current) == null || i.call(v, n.getViewState()), n.getStore("viewport").subscribe(() => {
+    if (s)
+      return (i = C.current) == null || i.call(C, s.getViewState()), s.getStore("viewport").subscribe(() => {
         var y;
-        return (y = v.current) == null ? void 0 : y.call(v, n.getViewState());
+        return (y = C.current) == null ? void 0 : y.call(C, s.getViewState());
       });
-  }, [n]);
-  const N = T(() => n ? new ae(n) : null, [n]), V = T(
-    () => n && N && g ? { controller: n, layers: N, overlayPane: g, corners: O } : null,
-    [n, N, g, O]
+  }, [s]);
+  const X = x(
+    () => ({
+      position: "absolute",
+      inset: 0,
+      zIndex: 20,
+      pointerEvents: "none",
+      opacity: "var(--om-widget-opacity, 1)",
+      ...L ? { visibility: "hidden" } : void 0,
+      ...v ? de(v).properties : void 0
+    }),
+    [v, L]
+  ), N = x(() => s ? new ge(s) : null, [s]), H = x(
+    () => s && N && S ? { controller: s, layers: N, overlayPane: S, corners: O } : null,
+    [s, N, S, O]
   );
-  return /* @__PURE__ */ Y("div", { className: w, style: { position: "relative", overflow: "hidden", ...L }, children: [
-    /* @__PURE__ */ P("div", { ref: h, style: { position: "absolute", inset: 0 } }),
-    /* @__PURE__ */ P(
+  return /* @__PURE__ */ te("div", { className: h, style: { position: "relative", overflow: "hidden", ...b }, children: [
+    /* @__PURE__ */ w("div", { ref: p, style: { position: "absolute", inset: 0 } }),
+    /* @__PURE__ */ w(
       "div",
       {
-        ref: R,
+        ref: j,
         style: { position: "absolute", top: 0, left: 0, zIndex: 10, pointerEvents: "none" }
       }
     ),
-    q.map((i) => /* @__PURE__ */ P(
+    /* @__PURE__ */ w("div", { "data-om-widget-layer": "", style: X, children: $.map((i) => /* @__PURE__ */ w(
       "div",
       {
-        "data-om-widget-corner": i,
-        ref: j[i],
-        style: ce(i)
+        "data-om-widget-slot": i,
+        ref: P[i],
+        style: he[i]
       },
       i
-    )),
-    V && /* @__PURE__ */ P(J.Provider, { value: V, children: b })
+    )) }),
+    H && /* @__PURE__ */ w(Q.Provider, { value: H, children: g })
   ] });
-}), fe = /* @__PURE__ */ new Set([
+}), ve = /* @__PURE__ */ new Set([
   "id",
   "type",
   "data",
@@ -165,58 +158,61 @@ const ve = te(function(t, s) {
   "onClick",
   "onHover"
 ]);
-function pe(e) {
-  const { controller: t, layers: s } = K("OmLayer"), { id: r } = e, a = {};
-  for (const [l, d] of Object.entries(e))
-    !fe.has(l) && d !== void 0 && (a[l] = d);
-  const u = {
+function xe(t) {
+  const { controller: e, layers: n } = z("OmLayer"), { id: r } = t, l = {};
+  for (const [a, f] of Object.entries(t))
+    !ve.has(a) && f !== void 0 && (l[a] = f);
+  const d = {
     id: r,
-    type: e.type,
-    data: e.data,
-    label: e.label,
-    color: e.color,
-    filterField: e.filterField,
-    filterRange: e.filterRange,
-    filterSoftRange: e.filterSoftRange,
-    filterCategoryField: e.filterCategoryField,
-    filterCategories: e.filterCategories,
-    source: e.source,
-    key: e.streamKey,
-    flush: e.flush,
-    refresh: e.refresh,
-    terrain: e.terrain,
-    updateTriggers: e.updateTriggers,
-    props: a
+    type: t.type,
+    data: t.data,
+    label: t.label,
+    color: t.color,
+    filterField: t.filterField,
+    filterRange: t.filterRange,
+    filterSoftRange: t.filterSoftRange,
+    filterCategoryField: t.filterCategoryField,
+    filterCategories: t.filterCategories,
+    source: t.source,
+    key: t.streamKey,
+    flush: t.flush,
+    refresh: t.refresh,
+    terrain: t.terrain,
+    updateTriggers: t.updateTriggers,
+    props: l
   };
-  p(() => {
-    s.upsert(u);
-  }), p(() => () => s.remove(r), [s, r]);
-  const c = m(e.onClick);
-  c.current = e.onClick;
-  const o = m(e.onHover);
-  return o.current = e.onHover, p(
-    () => t.watchPicks((l) => {
-      var d, f, w;
-      if (l === null) {
-        (d = o.current) == null || d.call(o, null);
+  E(() => {
+    n.upsert(d);
+  }), E(() => () => n.remove(r), [n, r]);
+  const c = m(t.onClick);
+  c.current = t.onClick;
+  const o = m(t.onHover);
+  return o.current = t.onHover, E(
+    () => e.watchPicks((a) => {
+      var f, u, v;
+      if (a === null) {
+        (f = o.current) == null || f.call(o, null);
         return;
       }
-      l.layerId === r && (l.type === "click" ? (f = c.current) == null || f.call(c, l) : (w = o.current) == null || w.call(o, l));
+      a.layerId === r && (a.type === "click" ? (u = c.current) == null || u.call(c, a) : (v = o.current) == null || v.call(o, a));
     }),
-    [t, r]
+    [e, r]
   ), null;
 }
-function Se({ position: e = "top-left", className: t, style: s, children: r }) {
-  const { corners: a } = K("OmWidget"), u = a[e];
-  return u ? G(
-    /* @__PURE__ */ P("div", { className: t, style: { pointerEvents: "auto", ...s }, children: r }),
-    u
+function Te({ position: t = "top-start", order: e, className: n, style: r, children: l }) {
+  const { corners: d } = z("OmWidget"), c = fe(t) ?? "top-start";
+  if (c === "manual")
+    return /* @__PURE__ */ w("div", { className: n, style: { pointerEvents: "auto", ...r }, children: l });
+  const o = d[c];
+  return o ? Y(
+    /* @__PURE__ */ w("div", { className: n, style: { pointerEvents: "auto", ...e !== void 0 ? { order: e } : void 0, ...r }, children: l }),
+    o
   ) : null;
 }
-function B(e, t) {
-  return !t || (e == null ? void 0 : e.layerId) === t;
+function G(t, e) {
+  return !e || (t == null ? void 0 : t.layerId) === e;
 }
-const de = {
+const pe = {
   "top-left": "translate(0, 0)",
   "top-center": "translate(-50%, 0)",
   "top-right": "translate(-100%, 0)",
@@ -227,52 +223,52 @@ const de = {
   "bottom-center": "translate(-50%, -100%)",
   "bottom-right": "translate(-100%, -100%)"
 };
-function Oe(e) {
-  const { controller: t, overlayPane: s } = K("OmOverlay"), r = m(null), a = m(void 0), u = m(e);
-  u.current = e;
-  const c = T(() => {
-    const b = t.getStore("selection");
-    let h, n, S = null;
+function Me(t) {
+  const { controller: e, overlayPane: n } = z("OmOverlay"), r = m(null), l = m(void 0), d = m(t);
+  d.current = t;
+  const c = x(() => {
+    const h = e.getStore("selection");
+    let b, g, p = null;
     return {
-      subscribe: b.subscribe,
+      subscribe: h.subscribe,
       getSnapshot: () => {
-        const g = b.getSnapshot(), { anchorFrom: C, layer: O } = u.current, E = `${C ?? ""}|${O ?? ""}`;
-        return (g !== h || E !== n) && (h = g, n = E, C === "selection" && B(g, O) && (S = g)), S;
+        const s = h.getSnapshot(), { anchorFrom: R, layer: S } = d.current, T = `${R ?? ""}|${S ?? ""}`;
+        return (s !== b || T !== g) && (b = s, g = T, R === "selection" && G(s, S) && (p = s)), p;
       }
     };
-  }, [t]), o = H(
+  }, [e]), o = J(
     c.subscribe,
     c.getSnapshot,
     c.getSnapshot
   );
-  p(
-    () => t.registerOverlay((b, h) => {
-      const n = r.current;
-      if (!n) return;
-      const { anchor: S, anchorFrom: g, layer: C, visible: O = !0, anchorOffset: E } = u.current;
-      let R;
-      if (g === "selection" ? (B(h, C) && (a.current = (h == null ? void 0 : h.coordinate) ?? void 0), R = a.current) : R = S, !O || !R || !b) {
-        n.style.visibility = "hidden";
+  E(
+    () => e.registerOverlay((h, b) => {
+      const g = r.current;
+      if (!g) return;
+      const { anchor: p, anchorFrom: s, layer: R, visible: S = !0, anchorOffset: T } = d.current;
+      let O;
+      if (s === "selection" ? (G(b, R) && (l.current = (b == null ? void 0 : b.coordinate) ?? void 0), O = l.current) : O = p, !S || !O || !h) {
+        g.style.visibility = "hidden";
         return;
       }
-      const [j, k, x] = b.project([R[0], R[1], 0]);
-      if (!(j >= 0 && j <= b.width && k >= 0 && k <= b.height) || x !== void 0 && x < 0) {
-        n.style.visibility = "hidden";
+      const [k, j, P] = h.project([O[0], O[1], 0]);
+      if (!(k >= 0 && k <= h.width && j >= 0 && j <= h.height) || P !== void 0 && P < 0) {
+        g.style.visibility = "hidden";
         return;
       }
-      n.style.visibility = "visible", n.style.transform = `translate(${j}px, ${k}px) ${de[E ?? "bottom-center"]}`;
+      g.style.visibility = "visible", g.style.transform = `translate(${k}px, ${j}px) ${pe[T ?? "bottom-center"]}`;
     }),
-    [t]
-  ), p(() => {
-    t.refreshOverlays();
+    [e]
+  ), E(() => {
+    e.refreshOverlays();
   });
-  const { children: l, className: d, style: f, interactive: w = !0 } = e, L = typeof l == "function" ? l(o) : l;
-  return G(
-    /* @__PURE__ */ P(
+  const { children: a, className: f, style: u, interactive: v = !0 } = t, L = typeof a == "function" ? a(o) : a;
+  return Y(
+    /* @__PURE__ */ w(
       "div",
       {
         ref: r,
-        className: d,
+        className: f,
         style: {
           position: "absolute",
           top: 0,
@@ -280,38 +276,38 @@ function Oe(e) {
           visibility: "hidden",
           // hidden until the first flush positions it — never flashes at the origin
           willChange: "transform",
-          pointerEvents: w ? "auto" : "none",
-          ...f
+          pointerEvents: v ? "auto" : "none",
+          ...u
         },
         children: L
       }
     ),
-    s
+    n
   );
 }
-function Re(e = []) {
-  const { controller: t } = K("useOmMap"), s = e.join(" "), r = T(() => {
-    const c = (s ? s.split(" ") : []).flatMap((l) => le(l) ? [t.getStore(l)] : (console.warn(`[onlymapjs] useOmMap: "${l}" is not a watch token on the React front-end — expected viewport, selection, layers, or data:<layerId>.`), []));
+function ke(t = []) {
+  const { controller: e } = z("useOmMap"), n = t.join(" "), r = x(() => {
+    const c = (n ? n.split(" ") : []).flatMap((a) => ye(a) ? [e.getStore(a)] : (console.warn(`[onlymapjs] useOmMap: "${a}" is not a watch token on the React front-end — expected viewport, selection, layers, or data:<layerId>.`), []));
     let o;
     return {
-      subscribe: (l) => {
-        const d = c.map((f) => f.subscribe(l));
+      subscribe: (a) => {
+        const f = c.map((u) => u.subscribe(a));
         return () => {
-          for (const f of d) f();
+          for (const u of f) u();
         };
       },
       getSnapshot: () => {
-        const l = c.map((d) => d.getSnapshot());
-        return (!o || l.some((d, f) => d !== o[f])) && (o = l), o;
+        const a = c.map((f) => f.getSnapshot());
+        return (!o || a.some((f, u) => f !== o[u])) && (o = a), o;
       }
     };
-  }, [t, s]), a = H(r.subscribe, r.getSnapshot, r.getSnapshot);
-  return T(() => t.buildCtx(), [t, a]);
+  }, [e, n]), l = J(r.subscribe, r.getSnapshot, r.getSnapshot);
+  return x(() => e.buildCtx(), [e, l]);
 }
 export {
-  pe as OmLayer,
-  ve as OmMap,
-  Oe as OmOverlay,
-  Se as OmWidget,
-  Re as useOmMap
+  xe as OmLayer,
+  Ce as OmMap,
+  Me as OmOverlay,
+  Te as OmWidget,
+  ke as useOmMap
 };

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * the build rootDir, and a `define` would need repeating across vite/vitest/
  * vite-node configs.
  */
-export declare const LIBRARY_VERSION = "0.4.0";
+export declare const LIBRARY_VERSION = "0.4.2";

package/dist/widget-layout.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Widget layout vocabulary (spec: "Widget Layout Manager") — the shared,
+ * framework-free half of the slot system: slot names, legacy-corner
+ * aliasing, per-slot flex layout parameters, and the `widget-style` token
+ * sugar parser. Both front-ends derive their containers from THIS table
+ * (the HTML lane as cssText, the React lane as CSSProperties) so the two
+ * lanes cannot drift on placement semantics.
+ *
+ * Names are LOGICAL and RTL-aware: `-start`/`-end` map to CSS
+ * `inset-inline-*` and flex alignment, so an RTL document mirrors the
+ * whole chrome without any per-widget work. Legacy corner names stay as
+ * aliases mapped logically (`top-left` → `top-start`), which means legacy
+ * manifests mirror correctly under RTL too — physical-corner fidelity is
+ * deliberately NOT preserved there.
+ */
+export declare const MANAGED_SLOTS: readonly ["top-start", "top-center", "top-end", "center-start", "center-end", "bottom-start", "bottom-center", "bottom-end"];
+export type ManagedSlot = (typeof MANAGED_SLOTS)[number];
+/** A widget's resolved placement: a managed slot, or the author-styled manual tier. */
+export type WidgetSlot = ManagedSlot | "manual";
+/** Legacy 4-corner vocabulary (pre-0.4.1) — accepted forever, mapped LOGICALLY. */
+export declare const LEGACY_POSITION_ALIASES: Readonly<Record<string, ManagedSlot>>;
+/** Every accepted `position` value (validation + html-data). */
+export declare const ALL_POSITION_VALUES: readonly string[];
+/**
+ * `position` attribute/prop → slot. Absent/empty → the default `top-start`
+ * (today's `top-left` default, aliased). Unknown values → null; callers
+ * warn and fall back to the default (validation carries the loud version).
+ */
+export declare function resolveSlot(raw: string | null | undefined): WidgetSlot | null;
+export interface SlotLayout {
+    /** Stack axis: edge-center slots run ALONG their edge (row); everything else stacks as a column. */
+    axis: "column" | "row";
+    block: "top" | "center" | "bottom";
+    inline: "start" | "center" | "end";
+}
+export declare function slotLayout(slot: ManagedSlot): SlotLayout;
+/**
+ * The slot container's styles as a camelCase style object — ONE builder for
+ * both front-ends (the React lane spreads it as CSSProperties; the HTML
+ * lane serializes it to cssText), so the lanes cannot drift on placement.
+ * Insets/gaps read the layout tokens with the pre-0.4.1 constants as
+ * fallbacks (12px inset, 8px gap), so a single-widget legacy corner renders
+ * pixel-identically. Containers never intercept the map's pointer events;
+ * each widget re-enables its own.
+ */
+export declare function slotContainerStyle(slot: ManagedSlot): Record<string, string | number>;
+/** The HTML lane's serialization of slotContainerStyle. */
+export declare function slotContainerCssText(slot: ManagedSlot): string;
+export declare const WIDGET_STYLE_KEY_NAMES: readonly string[];
+export interface WidgetStyleParse {
+    /** Custom property → CSS value, ready for style.setProperty. */
+    properties: Record<string, string>;
+    /** Unparseable entries (unknown key / non-numeric value) — validation's loud half; the live path skips them. */
+    errors: string[];
+}
+/**
+ * `widget-style="gap:10 opacity:0.9 inset-x:16"` → custom properties — the
+ * no-CSS token surface for agents/authors. Space-separated `key:value`
+ * pairs; numbers get `px` except opacity. One parser serves the live path
+ * (om-map attr → host properties) and validation.
+ */
+export declare function parseWidgetStyle(raw: string): WidgetStyleParse;

package/dist/widget-registry.d.ts

@@ -19,7 +19,27 @@ export interface WidgetHost {
 export interface WidgetImpl {
     /** Default watch tokens when the element has no `watch` attribute. */
     watch?: string[];
+    /**
+     * Compact button widget (spec: "Widget Layout Manager / Button
+     * clustering") — adjacent compact widgets in one slot auto-merge into a
+     * single visual control group (shared rounded container, dividers, one
+     * shadow). Per-widget opt-out: `cluster="false"`. Non-compact widgets
+     * (panels: legend, filter, search) never cluster.
+     */
+    compact?: boolean;
+    /**
+     * Never affected by hide-all (spec: "Widget Layout Manager / Hide-all") —
+     * `widgets-hidden` leaves this widget visible. Attribution declares it
+     * (license compliance) and so does the widgets-toggle button (it must
+     * stay clickable to un-hide). Third-party always-visible chrome sets it
+     * here rather than the core hardcoding a type list.
+     */
+    neverHides?: boolean;
     render(ctx: RuntimeContext, host: WidgetHost): void | Promise<void>;
 }
+/** Clusterable (spec: "Widget Layout Manager") — the type is compact AND the author didn't opt out. One predicate for the cluster pass AND the validation lint. */
+export declare function isClusterableWidget(el: Element): boolean;
+/** Exempt from hide-all — the type declares `neverHides` (attribution, widgets-toggle). */
+export declare function widgetNeverHides(type: string | null): boolean;
 export declare function registerWidget(name: string, impl: WidgetImpl): void;
 export declare function getWidget(name: string): WidgetImpl | undefined;