@honua/app-platform 0.0.20-alpha.0

package/controls/basemap-switcher.js

@@ -0,0 +1,379 @@
+/**
+ * `<honua-basemap-switcher>` — framework-free custom element that switches a
+ * MapLibre map between exclusive basemap definitions (issue #274).
+ *
+ * The element renders an accessible radio group (one radio per base) inside
+ * shadow DOM with structural-only CSS and `::part()` hooks, and delegates all
+ * style mutations to {@link HonuaBasemapStyleBinding}. It never imports
+ * `maplibre-gl` or the SDK core, so the `@honua/sdk-js/controls` entry stays
+ * independent of the core bundle.
+ *
+ * ## Wiring
+ * - `element.map = map` (any MapLibre `Map`) or `element.connect(map)`;
+ * - declaratively via `for="<honua-map id>"` — the element resolves the map
+ *   from a sibling element exposing a `.map` property (e.g. `<honua-map>`)
+ *   and also listens for the `honua-map-ready` event, matching the idiom of
+ *   the `web-components` entry.
+ *
+ * ## Attributes
+ * - `bases` — JSON array of {@link HonuaBasemapDefinition} (property `bases`
+ *   is preferred for non-trivial configs).
+ * - `value` — id of the base to activate; reflected on selection changes.
+ * - `for` — id of the map-providing element, see Wiring.
+ * - `label` — accessible name of the radio group (default "Basemaps").
+ *
+ * ## Events
+ * - `change` — `CustomEvent<HonuaBasemapSwitcherChangeDetail>` (bubbles,
+ *   composed) whenever the active base changes: user interaction,
+ *   programmatic `value` assignment, or the initial/default activation.
+ *
+ * ## CSS parts
+ * - `group` — the radio-group container (button-group layout).
+ * - `radio` — each base button.
+ * - `radio-active` — additionally present on the active base's button.
+ *
+ * ## Accessibility
+ * Radio-group semantics (`role="radiogroup"` / `role="radio"`,
+ * `aria-checked`) with roving tabindex; ArrowLeft/ArrowUp and
+ * ArrowRight/ArrowDown move and select, Home/End jump to the first/last
+ * base, Space/Enter select the focused base.
+ */
+import { HonuaBasemapStyleBinding } from "./basemap-style-binding.js";
+import { HTMLElementBase, escapeAttribute, escapeHtml, globalDom, listenForHonuaMapReady, resolveHonuaMapFromContext, } from "./element-utils.js";
+import { HonuaLegendElement } from "./legend.js";
+import { HonuaSwipeControlElement } from "./swipe-control.js";
+/**
+ * Custom element implementing the exclusive basemap switcher. Registered as
+ * `honua-basemap-switcher` by {@link defineHonuaControls} (which runs
+ * automatically on import when a `customElements` registry exists).
+ */
+export class HonuaBasemapSwitcherElement extends HTMLElementBase {
+    static get observedAttributes() {
+        return ["bases", "value", "for", "label"];
+    }
+    #binding = new HonuaBasemapStyleBinding();
+    #requestedValue;
+    #disposeMapReadyListener;
+    #rendered = false;
+    /**
+     * The MapLibre map driven by this control. Assigning a map applies the
+     * current selection to it; assigning `undefined` detaches and removes every
+     * layer/source the control added.
+     */
+    get map() {
+        return this.#binding.map;
+    }
+    set map(map) {
+        this.#binding.setMap(map);
+        if (map)
+            this.#ensureActive();
+    }
+    /** Wires the control to a MapLibre map. Equivalent to setting `.map`. */
+    connect(map) {
+        this.map = map;
+    }
+    /** The registered base definitions. */
+    get bases() {
+        return this.#binding.bases;
+    }
+    set bases(bases) {
+        const previousActive = this.#binding.activeId;
+        this.#binding.setBases(bases);
+        this.#rendered = false;
+        this.render();
+        if (previousActive !== undefined && this.#binding.activeId === undefined) {
+            // The previously active base was removed; fall back to a valid base.
+            this.#ensureActive(previousActive);
+        }
+        else {
+            this.#ensureActive();
+        }
+    }
+    /**
+     * Id of the active base. Assigning a registered base id activates it (and
+     * dispatches `change` when the selection actually changes); assignments
+     * are remembered and honored once matching bases arrive.
+     */
+    get value() {
+        return this.#binding.activeId ?? this.#requestedValue;
+    }
+    set value(value) {
+        if (value === undefined)
+            return;
+        this.select(value);
+    }
+    /**
+     * Activates the base with the given id. Returns `true` when the id matched
+     * a registered base. Dispatches `change` when the active base changed.
+     */
+    select(baseId) {
+        const previous = this.#binding.activeId;
+        if (previous === baseId) {
+            this.#requestedValue = undefined;
+            return true;
+        }
+        const base = this.bases.find((candidate) => candidate.id === baseId);
+        if (!base || !this.#binding.activate(baseId)) {
+            this.#requestedValue = baseId;
+            return false;
+        }
+        this.#requestedValue = undefined;
+        this.#reflectValue(baseId);
+        this.#updateSelectionDom();
+        this.#dispatchChange({
+            value: baseId,
+            ...(previous !== undefined ? { previousValue: previous } : {}),
+            kind: base.kind,
+        });
+        return true;
+    }
+    attributeChangedCallback(name, _oldValue, newValue) {
+        if (name === "bases") {
+            const parsed = parseBases(newValue);
+            if (parsed)
+                this.bases = parsed;
+            return;
+        }
+        if (name === "value") {
+            if (newValue !== null && newValue !== this.#binding.activeId)
+                this.select(newValue);
+            return;
+        }
+        if (name === "for") {
+            this.#resolveMapFromContext();
+            return;
+        }
+        if (name === "label") {
+            this.#rendered = false;
+            this.render();
+        }
+    }
+    connectedCallback() {
+        this.#ensureShadowRoot();
+        this.#listenForMapReady();
+        this.#resolveMapFromContext();
+        this.render();
+        this.#ensureActive();
+    }
+    disconnectedCallback() {
+        this.#disposeMapReadyListener?.();
+        this.#disposeMapReadyListener = undefined;
+    }
+    /**
+     * Applies the pending `value` (attribute or property assignment made before
+     * bases were registered), falling back to the first base so the map is
+     * never left without an active base once wiring completes.
+     */
+    #ensureActive(removedActiveId) {
+        if (this.#binding.activeId !== undefined || this.bases.length === 0)
+            return;
+        const requested = this.#requestedValue ?? (typeof this.getAttribute === "function" ? this.getAttribute("value") : null);
+        if (requested !== null && requested !== undefined && requested !== removedActiveId && this.select(requested))
+            return;
+        const first = this.bases[0];
+        if (first)
+            this.select(first.id);
+    }
+    // ── map wiring (matches the web-components `for` + ready-event idiom) ──
+    #listenForMapReady() {
+        if (this.#disposeMapReadyListener)
+            return;
+        this.#disposeMapReadyListener = listenForHonuaMapReady(this, (map) => {
+            const forId = typeof this.getAttribute === "function" ? this.getAttribute("for") : null;
+            if (!forId && this.map)
+                return;
+            this.map = map;
+        });
+    }
+    #resolveMapFromContext() {
+        if (this.map)
+            return;
+        const map = resolveHonuaMapFromContext(this);
+        if (map)
+            this.map = map;
+    }
+    // ── rendering ──────────────────────────────────────────────
+    #ensureShadowRoot() {
+        if (!this.shadowRoot && typeof this.attachShadow === "function") {
+            this.attachShadow({ mode: "open" });
+        }
+    }
+    render() {
+        const root = this.shadowRoot;
+        if (!root)
+            return;
+        if (this.#rendered) {
+            this.#updateSelectionDom();
+            return;
+        }
+        const label = (typeof this.getAttribute === "function" ? this.getAttribute("label") : null) ?? "Basemaps";
+        root.innerHTML = `
+      <style>${structuralStyles()}</style>
+      <div part="group" class="group" role="radiogroup" aria-label="${escapeAttribute(label)}">
+        ${this.bases
+            .map((base) => `
+          <button
+            type="button"
+            part="radio"
+            class="radio"
+            role="radio"
+            aria-checked="false"
+            tabindex="-1"
+            data-base-id="${escapeAttribute(base.id)}"
+            data-kind="${escapeAttribute(base.kind)}"
+          >${escapeHtml(base.label)}</button>
+        `)
+            .join("")}
+      </div>
+    `;
+        this.#rendered = true;
+        this.#bindGroup(root);
+        this.#updateSelectionDom();
+    }
+    #bindGroup(root) {
+        root.querySelectorAll("button[data-base-id]").forEach((button) => {
+            button.addEventListener("click", () => {
+                const baseId = button.dataset.baseId;
+                if (baseId)
+                    this.select(baseId);
+            });
+        });
+        root.querySelector(".group")?.addEventListener("keydown", (event) => {
+            this.#onGroupKeydown(event);
+        });
+    }
+    #onGroupKeydown(event) {
+        const radios = this.#radios();
+        if (radios.length === 0)
+            return;
+        const activeIndex = Math.max(0, radios.findIndex((radio) => radio.dataset.baseId === this.#binding.activeId));
+        let nextIndex;
+        switch (event.key) {
+            case "ArrowRight":
+            case "ArrowDown":
+                nextIndex = (activeIndex + 1) % radios.length;
+                break;
+            case "ArrowLeft":
+            case "ArrowUp":
+                nextIndex = (activeIndex - 1 + radios.length) % radios.length;
+                break;
+            case "Home":
+                nextIndex = 0;
+                break;
+            case "End":
+                nextIndex = radios.length - 1;
+                break;
+            default:
+                return;
+        }
+        event.preventDefault();
+        const next = radios[nextIndex];
+        const baseId = next?.dataset.baseId;
+        if (!baseId)
+            return;
+        this.select(baseId);
+        next.focus();
+    }
+    /** Roving tabindex + checked state, updated in place to preserve focus. */
+    #updateSelectionDom() {
+        const radios = this.#radios();
+        if (radios.length === 0)
+            return;
+        const activeId = this.#binding.activeId;
+        const fallbackTabStop = radios.some((radio) => radio.dataset.baseId === activeId) ? undefined : radios[0];
+        for (const radio of radios) {
+            const isActive = radio.dataset.baseId === activeId;
+            radio.setAttribute("aria-checked", String(isActive));
+            radio.setAttribute("part", isActive ? "radio radio-active" : "radio");
+            radio.tabIndex = isActive || radio === fallbackTabStop ? 0 : -1;
+        }
+    }
+    #radios() {
+        const root = this.shadowRoot;
+        if (!root || typeof root.querySelectorAll !== "function")
+            return [];
+        return [...root.querySelectorAll("button[data-base-id]")];
+    }
+    #reflectValue(baseId) {
+        if (typeof this.setAttribute !== "function" || typeof this.getAttribute !== "function")
+            return;
+        if (this.getAttribute("value") !== baseId)
+            this.setAttribute("value", baseId);
+    }
+    #dispatchChange(detail) {
+        if (!globalDom.CustomEvent || typeof this.dispatchEvent !== "function")
+            return;
+        this.dispatchEvent(new globalDom.CustomEvent("change", { bubbles: true, composed: true, detail }));
+    }
+}
+/**
+ * Registers the controls-entry custom elements (`honua-basemap-switcher`,
+ * `honua-legend`, `honua-swipe-control`). Invoked automatically on import when
+ * a global `customElements` registry is present; call explicitly when using a
+ * scoped registry.
+ *
+ * Registrations are skipped for tag names that are already defined. In
+ * particular the `web-components` entry registers its own (controller-driven)
+ * `honua-legend`; whichever entry is imported first owns that tag.
+ *
+ * `honua-layer-list` is intentionally NOT registered here — it collides with
+ * the `web-components` kit's own controller-driven `honua-layer-list`, so it is
+ * opt-in via {@link defineHonuaLayerList}.
+ */
+export function defineHonuaControls(registry = globalDom.customElements) {
+    if (!registry)
+        return;
+    if (!registry.get("honua-basemap-switcher")) {
+        registry.define("honua-basemap-switcher", HonuaBasemapSwitcherElement);
+    }
+    if (!registry.get("honua-legend")) {
+        registry.define("honua-legend", HonuaLegendElement);
+    }
+    if (!registry.get("honua-swipe-control")) {
+        registry.define("honua-swipe-control", HonuaSwipeControlElement);
+    }
+}
+if (globalDom.customElements) {
+    defineHonuaControls(globalDom.customElements);
+}
+function parseBases(value) {
+    if (!value)
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed))
+            return undefined;
+        return parsed.flatMap((item) => {
+            if (!item || typeof item !== "object")
+                return [];
+            const candidate = item;
+            if (typeof candidate.id !== "string" || typeof candidate.label !== "string")
+                return [];
+            return [
+                {
+                    id: candidate.id,
+                    label: candidate.label,
+                    kind: isBasemapKind(candidate.kind) ? candidate.kind : "vector",
+                    sources: candidate.sources && typeof candidate.sources === "object" ? candidate.sources : {},
+                    layers: Array.isArray(candidate.layers)
+                        ? candidate.layers.filter((layer) => typeof layer?.id === "string")
+                        : [],
+                },
+            ];
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function isBasemapKind(value) {
+    return value === "vector" || value === "raster" || value === "raster-dem-composite";
+}
+/** Structural-only styles; theme via `::part(group)` / `::part(radio)` / `::part(radio-active)`. */
+function structuralStyles() {
+    return `
+    :host { display: inline-block; }
+    .group { display: inline-flex; flex-wrap: wrap; }
+    .radio { font: inherit; cursor: pointer; }
+  `;
+}

package/controls/element-utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Internal helpers shared by the controls-entry custom elements.
+ *
+ * Controls never import `maplibre-gl` or the SDK core, and they must load
+ * safely under Node (no DOM): `globalDom` exposes the optional browser
+ * globals, and `HTMLElementBase` substitutes an empty class when
+ * `HTMLElement` is unavailable so element classes can still be unit-tested
+ * headlessly.
+ *
+ * The map-wiring helpers implement the `for="<honua-map id>"` idiom shared by
+ * every control: resolve the map from a sibling element exposing a `.map`
+ * property, and listen for the `honua-map-ready` event (matching the
+ * `web-components` entry).
+ *
+ * @module
+ */
+export declare const globalDom: typeof globalThis & {
+    HTMLElement?: typeof HTMLElement;
+    CustomEvent?: typeof CustomEvent;
+    customElements?: CustomElementRegistry;
+};
+export declare const HTMLElementBase: typeof HTMLElement;
+/**
+ * Minimal element surface required by the wiring helpers. Real elements
+ * always satisfy it; headless test stubs only need `getAttribute`.
+ */
+export interface HostElementLike {
+    getAttribute?(name: string): string | null;
+    getRootNode?(): Node;
+}
+/** Event target used for `honua-map-ready` listening: the element's root (document or shadow root), falling back to `document`. */
+export declare function rootEventTarget(element: HostElementLike): EventTarget | undefined;
+/**
+ * Subscribes to `honua-map-ready` events on the element's root and invokes
+ * `assign` with the announced map. When the element has a `for` attribute,
+ * only events from the element with that id are honored. Returns a dispose
+ * function, or `undefined` when no event target exists (e.g. under Node).
+ */
+export declare function listenForHonuaMapReady(element: HostElementLike, assign: (map: unknown) => void): (() => void) | undefined;
+/**
+ * Resolves the map from the element referenced by the `for` attribute (an
+ * element exposing a `.map` property, e.g. `<honua-map>`), or `undefined`
+ * when the attribute is absent or the host has no map yet.
+ */
+export declare function resolveHonuaMapFromContext(element: HostElementLike): unknown;
+export declare function escapeHtml(value: string): string;
+export declare function escapeAttribute(value: string): string;
+//# sourceMappingURL=element-utils.d.ts.map

package/controls/element-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-utils.d.ts","sourceRoot":"","sources":["../../../src/controls/element-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,SAAS,EAAiB,OAAO,UAAU,GAAG;IACzD,WAAW,CAAC,EAAE,OAAO,WAAW,CAAC;IACjC,WAAW,CAAC,EAAE,OAAO,WAAW,CAAC;IACjC,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,OAAO,WAAkF,CAAC;AAExH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3C,WAAW,CAAC,IAAI,IAAI,CAAC;CACtB;AAED,mIAAmI;AACnI,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,GAAG,SAAS,CAIjF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAC7B,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAY1B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAY5E;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/controls/element-utils.js

@@ -0,0 +1,78 @@
+/**
+ * Internal helpers shared by the controls-entry custom elements.
+ *
+ * Controls never import `maplibre-gl` or the SDK core, and they must load
+ * safely under Node (no DOM): `globalDom` exposes the optional browser
+ * globals, and `HTMLElementBase` substitutes an empty class when
+ * `HTMLElement` is unavailable so element classes can still be unit-tested
+ * headlessly.
+ *
+ * The map-wiring helpers implement the `for="<honua-map id>"` idiom shared by
+ * every control: resolve the map from a sibling element exposing a `.map`
+ * property, and listen for the `honua-map-ready` event (matching the
+ * `web-components` entry).
+ *
+ * @module
+ */
+export const globalDom = globalThis;
+export const HTMLElementBase = globalDom.HTMLElement ?? class {
+};
+/** Event target used for `honua-map-ready` listening: the element's root (document or shadow root), falling back to `document`. */
+export function rootEventTarget(element) {
+    const root = element.getRootNode?.();
+    if (root && "addEventListener" in root)
+        return root;
+    return typeof document !== "undefined" ? document : undefined;
+}
+/**
+ * Subscribes to `honua-map-ready` events on the element's root and invokes
+ * `assign` with the announced map. When the element has a `for` attribute,
+ * only events from the element with that id are honored. Returns a dispose
+ * function, or `undefined` when no event target exists (e.g. under Node).
+ */
+export function listenForHonuaMapReady(element, assign) {
+    const target = rootEventTarget(element);
+    if (!target)
+        return undefined;
+    const listener = (event) => {
+        const detail = event.detail;
+        if (!detail?.map)
+            return;
+        const forId = typeof element.getAttribute === "function" ? element.getAttribute("for") : null;
+        if (forId && event.target?.id !== forId)
+            return;
+        assign(detail.map);
+    };
+    target.addEventListener("honua-map-ready", listener);
+    return () => target.removeEventListener("honua-map-ready", listener);
+}
+/**
+ * Resolves the map from the element referenced by the `for` attribute (an
+ * element exposing a `.map` property, e.g. `<honua-map>`), or `undefined`
+ * when the attribute is absent or the host has no map yet.
+ */
+export function resolveHonuaMapFromContext(element) {
+    if (typeof element.getAttribute !== "function")
+        return undefined;
+    const forId = element.getAttribute("for");
+    if (!forId)
+        return undefined;
+    const root = element.getRootNode?.();
+    const host = root && "getElementById" in root
+        ? root.getElementById(forId)
+        : typeof document !== "undefined"
+            ? document.getElementById(forId)
+            : null;
+    return host?.map;
+}
+export function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+export function escapeAttribute(value) {
+    return escapeHtml(value);
+}

package/controls/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Native Honua UI control kit (`@honua/sdk-js/controls`) — optional,
+ * framework-free custom elements for apps built on the native lane
+ * (HonuaClient + MapLibre). Tracked by issue #274; ships the basemap
+ * switcher, the legend, and the layer list.
+ *
+ * This entry is intentionally independent of the SDK core bundle (the same
+ * posture as `@honua/sdk-js/esri-compat`): it imports nothing from
+ * `src/core`/`src/runtime` and has no dependency on `maplibre-gl` — controls
+ * drive any MapLibre `Map` through a duck-typed interface.
+ *
+ * Importing this module registers the basemap switcher, legend, and swipe
+ * control when a browser `customElements` registry is present. Node imports are
+ * safe; call `defineHonuaControls()` explicitly when using a scoped registry.
+ * The layer list is opt-in via {@link defineHonuaLayerList} because its tag
+ * (`honua-layer-list`) collides with the `web-components` kit's own
+ * controller-driven element.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver
+ *   contract — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+import "./basemap-switcher.js";
+import "./swipe-control.js";
+export { HonuaBasemapStyleBinding } from "./basemap-style-binding.js";
+export { HonuaBasemapSwitcherElement, defineHonuaControls } from "./basemap-switcher.js";
+export { HonuaLayerListElement, defineHonuaLayerList } from "./layer-list.js";
+export { HonuaLegendDeriveError, deriveLegendEntries } from "./legend-derive.js";
+export type { HonuaLegendDeriveErrorCode } from "./legend-derive.js";
+export { HonuaLegendElement } from "./legend.js";
+export { HonuaSwipeControlElement, defineHonuaSwipeControl } from "./swipe-control.js";
+export type { HonuaBasemapDefinition, HonuaBasemapKind, HonuaBasemapLayerSpecification, HonuaBasemapSwitcherChangeDetail, HonuaBasemapSwitcherMap, HonuaLayerListChangeDetail, HonuaLayerListMap, HonuaLayerListOverlay, HonuaLegendEntry, HonuaLegendMap, HonuaLegendSection, HonuaLegendSwatchColor, HonuaLegendSwatchShape, HonuaSwipeChangeDetail, HonuaSwipeMap, HonuaSwipeOrientation, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/controls/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/controls/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,uBAAuB,CAAC;AAC/B,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACjF,YAAY,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AACvF,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,8BAA8B,EAC9B,gCAAgC,EAChC,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/controls/index.js

@@ -0,0 +1,30 @@
+/**
+ * Native Honua UI control kit (`@honua/sdk-js/controls`) — optional,
+ * framework-free custom elements for apps built on the native lane
+ * (HonuaClient + MapLibre). Tracked by issue #274; ships the basemap
+ * switcher, the legend, and the layer list.
+ *
+ * This entry is intentionally independent of the SDK core bundle (the same
+ * posture as `@honua/sdk-js/esri-compat`): it imports nothing from
+ * `src/core`/`src/runtime` and has no dependency on `maplibre-gl` — controls
+ * drive any MapLibre `Map` through a duck-typed interface.
+ *
+ * Importing this module registers the basemap switcher, legend, and swipe
+ * control when a browser `customElements` registry is present. Node imports are
+ * safe; call `defineHonuaControls()` explicitly when using a scoped registry.
+ * The layer list is opt-in via {@link defineHonuaLayerList} because its tag
+ * (`honua-layer-list`) collides with the `web-components` kit's own
+ * controller-driven element.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver
+ *   contract — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+import "./basemap-switcher.js";
+import "./swipe-control.js";
+export { HonuaBasemapStyleBinding } from "./basemap-style-binding.js";
+export { HonuaBasemapSwitcherElement, defineHonuaControls } from "./basemap-switcher.js";
+export { HonuaLayerListElement, defineHonuaLayerList } from "./layer-list.js";
+export { HonuaLegendDeriveError, deriveLegendEntries } from "./legend-derive.js";
+export { HonuaLegendElement } from "./legend.js";
+export { HonuaSwipeControlElement, defineHonuaSwipeControl } from "./swipe-control.js";

package/controls/layer-list.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `<honua-layer-list>` — framework-free custom element rendering a checkbox
+ * row per overlay so users can toggle MapLibre overlay layers on and off
+ * (issue #280, closing umbrella #274).
+ *
+ * Each overlay groups one or more style layer ids; toggling a row writes each
+ * layer's `visibility` layout property (`"visible"` / `"none"`) on the map.
+ * The element never imports `maplibre-gl` or the SDK core — it drives any
+ * MapLibre `Map` through the duck-typed {@link HonuaLayerListMap} interface,
+ * keeping the `@honua/sdk-js/controls` entry independent of the core bundle.
+ *
+ * ## Input modes
+ * - **Property** (preferred) — assign the `overlays` property a
+ *   {@link HonuaLayerListOverlay} array.
+ * - **Attribute** — set the `overlays` attribute to a JSON array of the same
+ *   shape (matching how `<honua-basemap-switcher>` accepts `bases` JSON).
+ *
+ * ## Wiring
+ * - `element.map = map` (any MapLibre `Map`) or `element.connect(map)`;
+ * - declaratively via `for="<honua-map id>"` — same idiom as
+ *   `<honua-basemap-switcher>` / `<honua-legend>` (resolves `.map` from the
+ *   referenced element and listens for `honua-map-ready`).
+ *
+ * ## Reactivity
+ * - With the `auto-refresh` attribute the element subscribes to the map's
+ *   `styledata` event while connected and re-syncs each checkbox's checked
+ *   state from the map's current `visibility` (external style edits,
+ *   visibility toggled elsewhere, layers seeded later).
+ *
+ * ## Attributes
+ * - `overlays` — JSON array of {@link HonuaLayerListOverlay} (the `overlays`
+ *   property is preferred for non-trivial configs).
+ * - `for` — id of the map-providing element, see Wiring.
+ * - `label` — accessible name of the list (default "Layers").
+ * - `auto-refresh` — boolean; see Reactivity.
+ *
+ * ## CSS parts
+ * `root`, `row`, `checkbox`, `label`, and `badge` (the "not seeded" hint
+ * shown on a disabled row whose style layers are all missing). Structural CSS
+ * only — theme via `::part()`.
+ *
+ * ## Accessibility
+ * Rows are real `<label>` + `<input type="checkbox">` pairs; an overlay whose
+ * style layers are all missing renders disabled with a `badge` part/slot.
+ */
+import { HTMLElementBase } from "./element-utils.js";
+import type { HonuaLayerListMap, HonuaLayerListOverlay } from "./types.js";
+/**
+ * Custom element implementing the overlay layer list. Registered as
+ * `honua-layer-list` by `defineHonuaControls` (which runs automatically on
+ * import of the controls entry when a `customElements` registry exists).
+ */
+export declare class HonuaLayerListElement extends HTMLElementBase {
+    #private;
+    static get observedAttributes(): string[];
+    /** The MapLibre map this list toggles overlay visibility on. */
+    get map(): HonuaLayerListMap | undefined;
+    set map(map: HonuaLayerListMap | undefined);
+    /** Wires the list to a MapLibre map. Equivalent to setting `.map`. */
+    connect(map: HonuaLayerListMap): void;
+    /** The registered overlay definitions. */
+    get overlays(): readonly HonuaLayerListOverlay[];
+    set overlays(overlays: readonly HonuaLayerListOverlay[]);
+    /** Refresh automatically on the map's `styledata` event. Reflects `auto-refresh`. */
+    get autoRefresh(): boolean;
+    set autoRefresh(value: boolean);
+    /** Re-syncs checkbox state from the map and re-renders. */
+    refresh(): void;
+    /**
+     * Shows or hides the overlay with the given id, writing each of its style
+     * layers' `visibility`. Returns `true` when the overlay was found and at
+     * least one of its layers exists on the map. Dispatches `change`.
+     */
+    setVisible(overlayId: string, visible: boolean): boolean;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected render(): void;
+}
+/**
+ * Registers the layer-list custom element (`honua-layer-list`). Skips the
+ * registration when the tag is already defined.
+ *
+ * Unlike the other controls-kit elements, this is **opt-in** and is NOT run by
+ * the blanket `defineHonuaControls()` / module-load auto-registration. The
+ * `web-components` entry ships its own (controller-driven) `honua-layer-list`
+ * under the same tag, and that kit auto-registers on import. Auto-registering
+ * the controls variant too would let it silently win the tag in apps that load
+ * both kits (the order is import-dependent), so callers who want the native,
+ * overlay-definition-driven layer list register it explicitly:
+ *
+ * ```ts
+ * import { defineHonuaLayerList } from "@honua/sdk-js/controls";
+ * defineHonuaLayerList();
+ * ```
+ */
+export declare function defineHonuaLayerList(registry?: CustomElementRegistry): void;
+//# sourceMappingURL=layer-list.d.ts.map