@aceshooting/lyra-ui 1.2.0 → 2.0.0

package/dist/components/kbd/kbd.js

@@ -0,0 +1,214 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { styles } from './kbd.styles.js';
+// A deliberately small map — just the modifier-adjacent/navigation keys
+// common enough in real shortcuts to be worth a friendly glyph. Anything not
+// listed here (e.g. 'f1', 'k', a punctuation key) falls through to the
+// generic "render as typed, upper-case single letters" rule in
+// `shortcutTokenLabel` below, per this component's spec.
+//
+// 'plus'/'minus' exist specifically so a shortcut that includes a literal
+// "+" or "-" key (e.g. the classic zoom-in shortcut) has a way to say so:
+// the '+'-separated `keys` grammar can't itself carry a literal "+" token
+// (it's the delimiter), so callers spell it as the word instead.
+const NAMED_KEY_LABELS = {
+    enter: { visual: '↵', word: 'Enter' },
+    esc: { visual: 'Esc', word: 'Escape' },
+    escape: { visual: 'Esc', word: 'Escape' },
+    tab: { visual: 'Tab', word: 'Tab' },
+    space: { visual: 'Space', word: 'Space' },
+    backspace: { visual: '⌫', word: 'Backspace' },
+    delete: { visual: 'Del', word: 'Delete' },
+    home: { visual: 'Home', word: 'Home' },
+    end: { visual: 'End', word: 'End' },
+    pageup: { visual: 'PgUp', word: 'Page Up' },
+    pagedown: { visual: 'PgDn', word: 'Page Down' },
+    arrowup: { visual: '↑', word: 'Arrow Up' },
+    arrowdown: { visual: '↓', word: 'Arrow Down' },
+    arrowleft: { visual: '←', word: 'Arrow Left' },
+    arrowright: { visual: '→', word: 'Arrow Right' },
+    plus: { visual: '+', word: 'Plus' },
+    minus: { visual: '−', word: 'Minus' },
+};
+/**
+ * Resolves one `+`-separated token of a `keys` string to its rendered glyph
+ * and spelled-out word, given whether the shortcut is being shown on macOS.
+ *
+ * Exported as a pure function (parameterized on `isMac` rather than reading
+ * the module-scope platform constant directly) so both the macOS and
+ * non-macOS branches are directly unit-testable without having to spoof
+ * `navigator` in a browser test environment that only ever runs as one
+ * platform.
+ */
+export function shortcutTokenLabel(rawToken, isMac) {
+    const token = rawToken.trim();
+    const lower = token.toLowerCase();
+    // 'mod' is the platform-neutral primary modifier: Command on macOS,
+    // Control everywhere else. 'ctrl' is deliberately distinct — it always
+    // means the literal Control key, even on macOS, for shortcuts that are
+    // specifically Ctrl-based (e.g. terminal Ctrl+C) rather than
+    // platform-adapted.
+    if (lower === 'mod')
+        return isMac ? { visual: '⌘', word: 'Command' } : { visual: 'Ctrl', word: 'Control' };
+    if (lower === 'ctrl' || lower === 'control')
+        return { visual: 'Ctrl', word: 'Control' };
+    if (lower === 'alt')
+        return isMac ? { visual: '⌥', word: 'Option' } : { visual: 'Alt', word: 'Alt' };
+    if (lower === 'shift')
+        return { visual: '⇧', word: 'Shift' };
+    const named = NAMED_KEY_LABELS[lower];
+    if (named)
+        return named;
+    // Anything else renders as typed (preserving the caller's own casing),
+    // except a bare single letter/digit, which is upper-cased for a
+    // consistent key-cap look ('k' and 'K' both render 'K').
+    if (token.length === 1) {
+        const upper = token.toUpperCase();
+        return { visual: upper, word: upper };
+    }
+    return { visual: token, word: token };
+}
+/** Splits a `keys` string (e.g. `'mod+shift+p'`) into its resolved token
+ *  labels, dropping empty segments from stray/leading/trailing `+`s. */
+export function parseShortcut(keys, isMac) {
+    return keys
+        .split('+')
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0)
+        .map((t) => shortcutTokenLabel(t, isMac));
+}
+/**
+ * Detects macOS to decide whether `mod`/`alt` render their Mac glyphs (⌘/⌥)
+ * or their generic-platform text (Ctrl/Alt). Prefers the modern
+ * `navigator.userAgentData` (Client Hints) API when the browser exposes it,
+ * falling back through `navigator.platform` and finally a `navigator.userAgent`
+ * substring check — all three are deprecated/non-standard to varying
+ * degrees (`userAgentData` is Chromium-only so far; `platform` is
+ * long-deprecated; `userAgent` sniffing is a last resort) but remain, in
+ * combination, the practical cross-browser way to answer "is this macOS"
+ * today with no dependency.
+ */
+function detectIsMac() {
+    if (typeof navigator === 'undefined')
+        return false;
+    const uaData = navigator.userAgentData;
+    if (uaData?.platform)
+        return uaData.platform.toLowerCase().includes('mac');
+    if (navigator.platform)
+        return /mac/i.test(navigator.platform);
+    return /mac/i.test(navigator.userAgent ?? '');
+}
+// Computed once at module scope, not per-instance/per-render — a page's
+// platform never changes mid-session, so there is nothing to gain (and a
+// little cost, however small) from re-detecting it on every <lyra-kbd>
+// instance or every re-render.
+const IS_MAC = detectIsMac();
+/**
+ * `<lyra-kbd>` — a small chip representing a keyboard shortcut, rendering
+ * the platform-appropriate glyph for cross-platform modifier keys (⌘ on
+ * macOS, "Ctrl" elsewhere) from a single platform-neutral `keys` string.
+ *
+ * `keys` is a `+`-separated sequence of tokens, e.g. `"mod+k"` or
+ * `"mod+shift+p"`. Recognized modifier tokens: `mod` (the platform-neutral
+ * primary modifier — ⌘ on macOS, "Ctrl" elsewhere), `alt` (⌥ / "Alt"),
+ * `shift` (⇧ on every platform), and `ctrl` (always the literal Control
+ * key, distinct from `mod`, for a shortcut that's specifically Ctrl even on
+ * macOS). Any other token renders as typed, except a bare single
+ * letter/digit which is upper-cased, with a small built-in map of friendly
+ * labels for common named keys (`enter` → `↵`, `esc` → "Esc", the four
+ * arrow keys → arrow glyphs, plus `tab`/`space`/`backspace`/`delete`/`home`/
+ * `end`/`pageup`/`pagedown`/`plus`/`minus`). `enter` renders as its `↵`
+ * glyph (not the word "Enter") to match the other single-glyph modifier/
+ * arrow keys visually — its spelled-out word form still appears in the
+ * computed `aria-label`.
+ *
+ * Each token renders as its own key cap (`part="key"`); consecutive caps
+ * are joined by a small "+" separator between them, matching how most
+ * cross-platform shortcut documentation (including on macOS, despite the
+ * OS's own native shortcut hints usually running the glyphs together with
+ * no separator) reads unambiguously regardless of how many/which glyphs are
+ * involved.
+ *
+ * The default slot is not used for the normal glyph rendering above — it's
+ * an escape hatch for fully custom content (e.g. an icon instead of a text
+ * glyph) that, when non-empty, replaces the `keys`-driven rendering
+ * entirely and stops this component from asserting its own `aria-label`,
+ * leaving the slotted content to carry its own accessible name.
+ *
+ * @customElement lyra-kbd
+ * @slot - Optional override for fully custom key-cap content, replacing the
+ * `keys`-driven rendering. Leave empty to use `keys`.
+ * @csspart base - The chip's root element.
+ * @csspart key - Each rendered key cap (one per token in `keys`).
+ */
+export class LyraKbd extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** A `+`-separated shortcut, e.g. `'mod+k'`. See the class doc for the
+         *  full token grammar. */
+        this.keys = '';
+        // Real (non-whitespace) light-DOM content overrides the keys-driven
+        // rendering below — same "seed synchronously, refine on slotchange"
+        // pattern as lyra-checkbox's hasLabelSlot/lyra-citation-badge's
+        // hasPreviewSlot, so a declaratively-slotted override doesn't flash the
+        // keys rendering for one frame before the first slotchange event.
+        this.hasCustomContent = false;
+        this.onSlotChange = (e) => {
+            this.hasCustomContent = e.target.assignedNodes({ flatten: true }).length > 0;
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    willUpdate() {
+        if (!this.hasUpdated) {
+            this.hasCustomContent = Array.from(this.childNodes).some((n) => (n.textContent ?? '').trim().length > 0);
+        }
+    }
+    render() {
+        const explicitLabel = this.getAttribute('aria-label');
+        if (this.hasCustomContent) {
+            return html `
+        <span part="base" aria-label=${explicitLabel || nothing}>
+          <slot @slotchange=${this.onSlotChange}></slot>
+        </span>
+      `;
+        }
+        const tokens = parseShortcut(this.keys, IS_MAC);
+        // role="img" treats the chip as one opaque unit (matching
+        // lyra-context-meter's/lyra-chart's canvas usage of the same pattern):
+        // the individual glyphs and "+" separators aren't real words, so
+        // exposing them as separate accessible-tree text would read worse than
+        // the single spelled-out aria-label below. An empty `keys` renders
+        // nothing visible, so it's marked aria-hidden instead of exposed as a
+        // nameless image.
+        const ariaLabel = explicitLabel || tokens.map((t) => t.word).join('+');
+        return html `
+      <span
+        part="base"
+        role=${tokens.length > 0 ? 'img' : nothing}
+        aria-hidden=${tokens.length === 0 && !explicitLabel ? 'true' : nothing}
+        aria-label=${ariaLabel || nothing}
+      >
+        ${tokens.map((t, i) => html `
+            ${i > 0 ? html `<span class="sep" aria-hidden="true">+</span>` : nothing}
+            <span part="key">${t.visual}</span>
+          `)}
+        <slot @slotchange=${this.onSlotChange} hidden></slot>
+      </span>
+    `;
+    }
+}
+__decorate([
+    property()
+], LyraKbd.prototype, "keys", void 0);
+__decorate([
+    state()
+], LyraKbd.prototype, "hasCustomContent", void 0);
+defineElement('kbd', LyraKbd);

package/dist/components/kbd/kbd.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/kbd/kbd.styles.js

@@ -0,0 +1,52 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: inline-flex;
+    max-inline-size: 100%;
+    vertical-align: middle;
+  }
+
+  [part='base'] {
+    display: inline-flex;
+    align-items: center;
+    flex-wrap: wrap;
+    /* The body font, not a monospace stack — unlike lyra-code-block's own
+       local --lyra-code-block-font token, a key cap's content is mostly
+       single characters and modifier glyphs (⌘⇧⌥), which read more legibly
+       — and have more complete glyph coverage — in the UI font than in a
+       monospace stack that may not even ship those symbols. */
+    font-family: var(--lyra-font);
+    font-size: 0.8125rem;
+    line-height: 1.3;
+    color: var(--lyra-color-text-quiet);
+  }
+
+  [part='key'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    min-inline-size: 1.5em;
+    padding: 0.0625rem var(--lyra-space-xs);
+    border: 1px solid var(--lyra-color-border);
+    border-radius: calc(var(--lyra-radius) * 0.6);
+    background: var(--lyra-color-surface);
+    color: var(--lyra-color-text);
+    font-weight: 500;
+    /* A subtle bottom-weighted inset shadow reads as a slightly-raised
+       physical key cap rather than a flat label chip, echoing the
+       lyra-chip/lyra-checkbox box's own bordered-box treatment. */
+    box-shadow: inset 0 -1px 0 var(--lyra-color-border);
+  }
+
+  .sep {
+    margin-inline: 0.1875rem;
+    color: var(--lyra-color-text-quiet);
+    font-size: 0.75em;
+    user-select: none;
+  }
+
+  ::slotted(*) {
+    vertical-align: middle;
+  }
+`;

package/dist/components/live-region/live-region.d.ts

@@ -0,0 +1,81 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { type AnnounceOptions } from '../../internal/announcer.js';
+export type LiveRegionMode = 'polite' | 'assertive';
+/**
+ * `<lyra-live-region>` — a visually-hidden ARIA live region that throttles
+ * and coalesces announcements instead of relaying every call verbatim.
+ *
+ * Naive live regions plus token-by-token streaming text (a chat response, a
+ * progress readout, ...) equals screen-reader spam: every incremental chunk
+ * gets announced. This component wraps `Announcer`
+ * (`../../internal/announcer.js`) so callers can fire `announce()` as often
+ * as they like — only the latest text within each `throttle-ms` window
+ * actually reaches assistive tech, and a `{ force: true }` call (e.g. once a
+ * stream ends) always lands immediately regardless of any window in
+ * progress.
+ *
+ * A consumer typically mounts one `<lyra-live-region>` per page/surface
+ * (much like `<lyra-toast>` is one region per placement — see
+ * `../toast/toaster.ts`) and keeps a reference to call `announce()` from
+ * application code or a parent component:
+ *
+ * @example
+ * ```html
+ * <!-- once, near the root of a chat surface's shell -->
+ * <lyra-live-region id="chat-live" mode="polite"></lyra-live-region>
+ * ```
+ * ```ts
+ * const live = document.getElementById('chat-live') as LyraLiveRegion;
+ *
+ * // streaming tokens: fine to call on every chunk, only the trailing state lands
+ * live.announce(`${partialText} …`);
+ *
+ * // stream finished: always announced, even mid-throttle-window
+ * live.announce('Response complete', { force: true });
+ * ```
+ *
+ * A parent Lit component would instead hold the reference via `@query`:
+ * ```ts
+ * @query('lyra-live-region') private liveRegion!: LyraLiveRegion;
+ * ```
+ * and is exactly what later components in this family (a stream-status
+ * indicator, a tool-call chip's status transitions, a chat message's
+ * streaming state) are expected to do rather than hand-rolling their own
+ * `aria-live` element.
+ *
+ * @customElement lyra-live-region
+ * @csspart region - The visually-hidden element carrying `role`/`aria-live`.
+ */
+export declare class LyraLiveRegion extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** `polite` (role="status") waits for the user to be idle; `assertive`
+     *  (role="alert") interrupts. Mirrors native `aria-live` semantics. */
+    mode: LiveRegionMode;
+    /** Throttle window in ms — see `Announcer` in `internal/announcer.ts`. */
+    throttleMs: number;
+    private readonly announcer;
+    private lastWritten;
+    private regionEl?;
+    private reannounceHandle?;
+    private pendingWrite?;
+    constructor();
+    protected updated(changed: PropertyValues): void;
+    firstUpdated(): void;
+    disconnectedCallback(): void;
+    /**
+     * Queue `text` for announcement. Calls arriving within `throttle-ms` of
+     * the first call in a burst collapse to a single announcement of the
+     * latest text; pass `{ force: true }` to bypass the window and flush
+     * immediately (e.g. for a final/terminal message that must not be
+     * dropped).
+     */
+    announce(text: string, options?: AnnounceOptions): void;
+    private write;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-live-region': LyraLiveRegion;
+    }
+}

package/dist/components/live-region/live-region.js

@@ -0,0 +1,153 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { srOnly } from '../../internal/a11y.js';
+import { Announcer } from '../../internal/announcer.js';
+import { styles } from './live-region.styles.js';
+/**
+ * `<lyra-live-region>` — a visually-hidden ARIA live region that throttles
+ * and coalesces announcements instead of relaying every call verbatim.
+ *
+ * Naive live regions plus token-by-token streaming text (a chat response, a
+ * progress readout, ...) equals screen-reader spam: every incremental chunk
+ * gets announced. This component wraps `Announcer`
+ * (`../../internal/announcer.js`) so callers can fire `announce()` as often
+ * as they like — only the latest text within each `throttle-ms` window
+ * actually reaches assistive tech, and a `{ force: true }` call (e.g. once a
+ * stream ends) always lands immediately regardless of any window in
+ * progress.
+ *
+ * A consumer typically mounts one `<lyra-live-region>` per page/surface
+ * (much like `<lyra-toast>` is one region per placement — see
+ * `../toast/toaster.ts`) and keeps a reference to call `announce()` from
+ * application code or a parent component:
+ *
+ * @example
+ * ```html
+ * <!-- once, near the root of a chat surface's shell -->
+ * <lyra-live-region id="chat-live" mode="polite"></lyra-live-region>
+ * ```
+ * ```ts
+ * const live = document.getElementById('chat-live') as LyraLiveRegion;
+ *
+ * // streaming tokens: fine to call on every chunk, only the trailing state lands
+ * live.announce(`${partialText} …`);
+ *
+ * // stream finished: always announced, even mid-throttle-window
+ * live.announce('Response complete', { force: true });
+ * ```
+ *
+ * A parent Lit component would instead hold the reference via `@query`:
+ * ```ts
+ * @query('lyra-live-region') private liveRegion!: LyraLiveRegion;
+ * ```
+ * and is exactly what later components in this family (a stream-status
+ * indicator, a tool-call chip's status transitions, a chat message's
+ * streaming state) are expected to do rather than hand-rolling their own
+ * `aria-live` element.
+ *
+ * @customElement lyra-live-region
+ * @csspart region - The visually-hidden element carrying `role`/`aria-live`.
+ */
+export class LyraLiveRegion extends LyraElement {
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    constructor() {
+        super();
+        /** `polite` (role="status") waits for the user to be idle; `assertive`
+         *  (role="alert") interrupts. Mirrors native `aria-live` semantics. */
+        this.mode = 'polite';
+        /** Throttle window in ms — see `Announcer` in `internal/announcer.ts`. */
+        this.throttleMs = 500;
+        // The live region's own last-written text. Tracked separately from
+        // whatever Lit thinks the DOM looks like because `write()` mutates
+        // `regionEl.textContent` directly (outside Lit's template bindings) --
+        // see `write()` for why.
+        this.lastWritten = '';
+        // Built in the constructor (not a class-field initializer) so it reads
+        // `this.throttleMs` only after that property's own field initializer
+        // has already run and set the declared default.
+        this.announcer = new Announcer({
+            throttleMs: this.throttleMs,
+            onFlush: (text) => this.write(text),
+        });
+    }
+    updated(changed) {
+        if (changed.has('throttleMs')) {
+            this.announcer.throttleMs = this.throttleMs;
+        }
+    }
+    firstUpdated() {
+        this.regionEl = this.renderRoot.querySelector('[part="region"]') ?? undefined;
+        if (this.pendingWrite !== undefined) {
+            const text = this.pendingWrite;
+            this.pendingWrite = undefined;
+            this.write(text);
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.announcer.cancel();
+        if (this.reannounceHandle !== undefined) {
+            cancelAnimationFrame(this.reannounceHandle);
+            this.reannounceHandle = undefined;
+        }
+    }
+    /**
+     * Queue `text` for announcement. Calls arriving within `throttle-ms` of
+     * the first call in a burst collapse to a single announcement of the
+     * latest text; pass `{ force: true }` to bypass the window and flush
+     * immediately (e.g. for a final/terminal message that must not be
+     * dropped).
+     */
+    announce(text, options) {
+        this.announcer.announce(text, options);
+    }
+    write(text) {
+        const region = this.regionEl;
+        if (!region) {
+            this.pendingWrite = text;
+            return;
+        }
+        if (text === this.lastWritten) {
+            // Screen readers announce a live region on text-content *change* --
+            // re-writing the identical string is otherwise a silent no-op to
+            // assistive tech. Clearing first and re-setting on the next frame
+            // (rather than in the same task) gives the DOM an actual empty ->
+            // populated transition to observe instead of a same-tick clear+set
+            // that can coalesce into nothing ever appearing to change.
+            region.textContent = '';
+            this.reannounceHandle = requestAnimationFrame(() => {
+                this.reannounceHandle = undefined;
+                region.textContent = text;
+            });
+        }
+        else {
+            region.textContent = text;
+        }
+        this.lastWritten = text;
+    }
+    render() {
+        const assertive = this.mode === 'assertive';
+        return html `<div
+      part="region"
+      class="sr-only"
+      role=${assertive ? 'alert' : 'status'}
+      aria-live=${assertive ? 'assertive' : 'polite'}
+      aria-atomic="true"
+    ></div>`;
+    }
+}
+__decorate([
+    property({ reflect: true })
+], LyraLiveRegion.prototype, "mode", void 0);
+__decorate([
+    property({ type: Number, attribute: 'throttle-ms' })
+], LyraLiveRegion.prototype, "throttleMs", void 0);
+defineElement('live-region', LyraLiveRegion);

package/dist/components/live-region/live-region.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/live-region/live-region.styles.js

@@ -0,0 +1,10 @@
+import { css } from 'lit';
+export const styles = css `
+  /* The host contributes no box of its own -- \`.sr-only\` (composed in via
+     internal/a11y.ts's shared \`srOnly\`) already takes the single child out
+     of flow via absolute positioning, so a wrapping host box would just be
+     an empty, purposeless inline element sitting in the document. */
+  :host {
+    display: contents;
+  }
+`;

package/dist/components/map/map.d.ts

@@ -1,5 +1,4 @@
 import { type TemplateResult, type PropertyValues } from 'lit';
-import type { Map as MaplibreMap, StyleSpecification } from 'maplibre-gl';
 import { LyraElement } from '../../internal/lyra-element.js';
 import '../skeleton/skeleton.js';
 export interface LegendEntry {
@@ -30,10 +29,12 @@ export interface MapMarker {
     /**
      * Rendered as the marker's popup content via maplibre-gl's
      * `Popup.setHTML()` -- parsed as raw markup, inline event handlers
-     * included. Only ever pass trusted content; sanitize anything derived
-     * from user input before assigning it here.
+     * included. This is the library's one explicit unsafe-HTML escape hatch:
+     * only ever pass trusted content, and sanitize anything derived from user
+     * input before assigning it here. Prefer `label` (rendered via the safe
+     * `Popup.setText()`) whenever the content is plain text.
      */
-    html?: string;
+    unsafeHtml?: string;
 }
 /**
  * `<lyra-map>` — a maplibre-gl wrapper with a declarative legend and
@@ -54,7 +55,7 @@ export declare class LyraMap extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
     center: [number, number];
     zoom: number;
-    mapStyle: StyleSpecification | string;
+    mapStyle: import('maplibre-gl').StyleSpecification | string;
     legend: LegendEntry[];
     choropleth?: ChoroplethLayer;
     markers: MapMarker[];
@@ -67,9 +68,10 @@ export declare class LyraMap extends LyraElement {
     private _appliedFillLayerId?;
     private _maplibreModule?;
     private _markerInstances;
+    private _markerColors;
     private _connectGeneration;
     /** The raw `maplibregl.Map` instance — escape hatch for anything this wrapper doesn't expose. */
-    get map(): MaplibreMap | undefined;
+    get map(): import('maplibre-gl').Map | undefined;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;

package/dist/components/map/map.js

@@ -93,6 +93,14 @@ export class LyraMap extends LyraElement {
         // choropleth updates from ever re-running.
         this._styleLoaded = false;
         this._markerInstances = new Map();
+        // The installed maplibre-gl's `Marker` class has no `setColor()` (verified
+        // against its shipped `.d.ts` -- `color` is only ever consumed by the
+        // constructor), so an id-matched marker whose `color` changes can't be
+        // mutated in place; it has to be torn down and reconstructed instead. This
+        // tracks the color each currently-live marker instance was last
+        // constructed with, keyed the same as `_markerInstances`, so `applyMarkers`
+        // can detect that mismatch without re-deriving it from the DOM.
+        this._markerColors = new Map();
         // Bumped on every connectedCallback and captured by value in its
         // loadMaplibre().then() closure below. A disconnect immediately followed
         // by a reconnect (fast remounts, route/tab switches, etc.) before that
@@ -170,6 +178,7 @@ export class LyraMap extends LyraElement {
         for (const marker of this._markerInstances.values())
             marker.remove();
         this._markerInstances.clear();
+        this._markerColors.clear();
     }
     updated(changed) {
         if (this.loading)
@@ -281,31 +290,57 @@ export class LyraMap extends LyraElement {
         if (!map || !mod)
             return;
         const visible = new Set();
+        // Markers with no `id` used to key solely by `lngLat`, so two different
+        // id-less markers placed at the exact same coordinates collided onto one
+        // `_markerInstances` entry. An occurrence index (reset per render, per
+        // coordinate) makes same-coordinate id-less markers distinct while
+        // staying stable/consistent across re-renders as long as their relative
+        // order in `this.markers` doesn't change.
+        const coordCounts = new Map();
         for (const m of this.markers) {
-            const key = m.id ?? `${m.lngLat[0]},${m.lngLat[1]}`;
+            let key = m.id;
+            if (key == null) {
+                const coordKey = `${m.lngLat[0]},${m.lngLat[1]}`;
+                const occurrence = coordCounts.get(coordKey) ?? 0;
+                coordCounts.set(coordKey, occurrence + 1);
+                key = `${coordKey}#${occurrence}`;
+            }
             visible.add(key);
-            const existing = this._markerInstances.get(key);
+            let existing = this._markerInstances.get(key);
+            if (existing && this._markerColors.get(key) !== m.color) {
+                // `color` is baked into the marker's SVG at construction time with
+                // no way to mutate it afterwards -- fall through to the "no existing
+                // marker" branch below to reconstruct it instead. Note: this closes
+                // any popup the user currently has open on this marker (a fresh,
+                // closed Popup is built for the new instance) -- an accepted, narrow
+                // side effect of the reconstruction fallback, not a bug.
+                existing.remove();
+                this._markerInstances.delete(key);
+                this._markerColors.delete(key);
+                existing = undefined;
+            }
             if (!existing) {
                 const marker = new mod.Marker(m.color ? { color: m.color } : undefined).setLngLat(m.lngLat);
-                if (m.html || m.label) {
+                if (m.unsafeHtml || m.label) {
                     const popup = new mod.Popup({ offset: 12 });
-                    if (m.html)
-                        popup.setHTML(m.html);
+                    if (m.unsafeHtml)
+                        popup.setHTML(m.unsafeHtml);
                     else if (m.label)
                         popup.setText(m.label);
                     marker.setPopup(popup);
                 }
                 marker.addTo(map);
                 this._markerInstances.set(key, marker);
+                this._markerColors.set(key, m.color);
             }
             else {
                 existing.setLngLat(m.lngLat);
                 const popup = existing.getPopup();
-                if (m.html) {
+                if (m.unsafeHtml) {
                     if (popup)
-                        popup.setHTML(m.html);
+                        popup.setHTML(m.unsafeHtml);
                     else
-                        existing.setPopup(new mod.Popup({ offset: 12 }).setHTML(m.html));
+                        existing.setPopup(new mod.Popup({ offset: 12 }).setHTML(m.unsafeHtml));
                 }
                 else if (m.label) {
                     if (popup)
@@ -322,6 +357,7 @@ export class LyraMap extends LyraElement {
             if (!visible.has(key)) {
                 marker.remove();
                 this._markerInstances.delete(key);
+                this._markerColors.delete(key);
             }
         }
     }