@aceshooting/lyra-ui 2.0.0 → 2.1.0

package/dist/components/json-viewer/json-viewer.d.ts

@@ -1,4 +1,4 @@
-import { type TemplateResult } from 'lit';
+import { type TemplateResult, type PropertyValues } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
 /**
  * `<lyra-json-viewer>` — a collapsible, copyable tree view for an arbitrary
@@ -17,10 +17,10 @@ import { LyraElement } from '../../internal/lyra-element.js';
  * @csspart toolbar - The wrapper around the top-level copy button (only rendered when `copyable`).
  * @csspart tree - The wrapper around the rendered node tree.
  * @csspart key - An object property key or array index label.
- * @csspart value - A primitive value's text -- carries `data-type` (`string`/`number`/`boolean`/`null`/`undefined`) for per-type coloring, and `data-match` while it matches `search`.
+ * @csspart value - A primitive value's text -- carries `data-type` (`string`/`number`/`boolean`/`null`/`undefined`, or `circular` for a self-reference marker in place of a re-visited container's subtree) for per-type coloring, and `data-match` while it matches `search`.
  * @csspart bracket - A `{`, `}`, `[`, or `]` delimiter.
  * @csspart toggle - A container node's expand/collapse button (hidden, but present for row alignment, on leaf/empty nodes).
- * @csspart copy-button - A copy-to-clipboard button -- the top-level one (in `toolbar`) or a per-node one (only rendered when `copyable`).
+ * @csspart copy-button - A copy-to-clipboard button -- the top-level one (in `toolbar`, labelled "Copy JSON to clipboard") or a per-node one (only rendered when `copyable`; labelled with its own key/type, e.g. "Copy age", so assistive tech can tell rows apart).
  */
 export declare class LyraJsonViewer extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -34,16 +34,33 @@ export declare class LyraJsonViewer extends LyraElement {
     copyable: boolean;
     /** Case-insensitive substring match against keys/values; matches are highlighted and their ancestors auto-expanded. */
     search: string;
-    /** Per-path (`JSON.stringify(path)`) explicit expand/collapse, overriding the `collapsedDepth`/search defaults once a node's toggle has been used. */
+    /**
+     * Per-path (`JSON.stringify(path)`) explicit expand/collapse, overriding
+     * the `collapsedDepth`/search defaults once a node's toggle has been used.
+     * Pruned in `willUpdate()` (to the paths still reachable in the tree)
+     * whenever `data` changes, so a long-lived instance bound to reshaping
+     * data -- this component's own stated streaming use case -- doesn't
+     * accumulate one entry per path ever toggled for the life of the instance.
+     */
     private expandedOverrides;
+    /** Memoized result of the last `computeSearch()` walk -- see `willUpdate()`. */
+    private searchState;
     private isExpanded;
     private toggleNode;
     private writeClipboard;
     private copy;
-    /** Builds the key/value-match sets and the ancestor-paths-of-a-match set that `search` drives. */
+    /**
+     * Builds the key/value-match sets, the ancestor-paths-of-a-match set that
+     * `search` drives, and the full set of path keys reachable in the tree
+     * (`paths`, used to prune `expandedOverrides` -- see `willUpdate()`).
+     * Guards against a self-referencing `data` the same way `renderNode()`
+     * does: a container value already on the current recursion path is
+     * treated as a leaf instead of being walked again.
+     */
     private computeSearch;
     private renderCopyButton;
     private renderNode;
+    protected willUpdate(changed: PropertyValues): void;
     render(): TemplateResult;
 }
 declare global {

package/dist/components/json-viewer/json-viewer.js

@@ -15,6 +15,7 @@ const EMPTY_SEARCH = {
     keyMatches: new Set(),
     valueMatches: new Set(),
     forceExpand: new Set(),
+    paths: new Set(),
 };
 function isPlainContainer(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -46,7 +47,12 @@ function valueType(value) {
 function formatPrimitive(value, type) {
     switch (type) {
         case 'string':
-            return JSON.stringify(value);
+            // `type` here also covers valueType()'s function/symbol/bigint
+            // fallback (see the comment there) -- JSON.stringify() throws a
+            // TypeError for a BigInt, so only an actual string gets the
+            // quoted/escaped treatment; everything else falls back to a plain
+            // String() coercion, which renders "sensibly" without throwing.
+            return typeof value === 'string' ? JSON.stringify(value) : String(value);
         case 'null':
             return 'null';
         case 'undefined':
@@ -77,10 +83,10 @@ function previewText(value, type, count) {
  * @csspart toolbar - The wrapper around the top-level copy button (only rendered when `copyable`).
  * @csspart tree - The wrapper around the rendered node tree.
  * @csspart key - An object property key or array index label.
- * @csspart value - A primitive value's text -- carries `data-type` (`string`/`number`/`boolean`/`null`/`undefined`) for per-type coloring, and `data-match` while it matches `search`.
+ * @csspart value - A primitive value's text -- carries `data-type` (`string`/`number`/`boolean`/`null`/`undefined`, or `circular` for a self-reference marker in place of a re-visited container's subtree) for per-type coloring, and `data-match` while it matches `search`.
  * @csspart bracket - A `{`, `}`, `[`, or `]` delimiter.
  * @csspart toggle - A container node's expand/collapse button (hidden, but present for row alignment, on leaf/empty nodes).
- * @csspart copy-button - A copy-to-clipboard button -- the top-level one (in `toolbar`) or a per-node one (only rendered when `copyable`).
+ * @csspart copy-button - A copy-to-clipboard button -- the top-level one (in `toolbar`, labelled "Copy JSON to clipboard") or a per-node one (only rendered when `copyable`; labelled with its own key/type, e.g. "Copy age", so assistive tech can tell rows apart).
  */
 export class LyraJsonViewer extends LyraElement {
     constructor() {
@@ -91,8 +97,17 @@ export class LyraJsonViewer extends LyraElement {
         this.copyable = false;
         /** Case-insensitive substring match against keys/values; matches are highlighted and their ancestors auto-expanded. */
         this.search = '';
-        /** Per-path (`JSON.stringify(path)`) explicit expand/collapse, overriding the `collapsedDepth`/search defaults once a node's toggle has been used. */
+        /**
+         * Per-path (`JSON.stringify(path)`) explicit expand/collapse, overriding
+         * the `collapsedDepth`/search defaults once a node's toggle has been used.
+         * Pruned in `willUpdate()` (to the paths still reachable in the tree)
+         * whenever `data` changes, so a long-lived instance bound to reshaping
+         * data -- this component's own stated streaming use case -- doesn't
+         * accumulate one entry per path ever toggled for the life of the instance.
+         */
         this.expandedOverrides = new Map();
+        /** Memoized result of the last `computeSearch()` walk -- see `willUpdate()`. */
+        this.searchState = EMPTY_SEARCH;
     }
     static { this.styles = [LyraElement.styles, styles]; }
     isExpanded(pathKey, depth, forceExpand) {
@@ -123,50 +138,70 @@ export class LyraJsonViewer extends LyraElement {
         }
     }
     copy(value) {
-        const text = value === undefined ? 'undefined' : JSON.stringify(value, null, 2);
+        const text = value === undefined
+            ? 'undefined'
+            : // A BigInt anywhere inside `value` (not just at the root) throws a
+                // TypeError from the default JSON.stringify() serializer the same
+                // way formatPrimitive()'s unguarded call used to -- the replacer
+                // downgrades it to its decimal string form instead.
+                JSON.stringify(value, (_key, v) => (typeof v === 'bigint' ? v.toString() : v), 2);
         this.writeClipboard(text);
         this.emit('lyra-copy', { text });
     }
-    /** Builds the key/value-match sets and the ancestor-paths-of-a-match set that `search` drives. */
+    /**
+     * Builds the key/value-match sets, the ancestor-paths-of-a-match set that
+     * `search` drives, and the full set of path keys reachable in the tree
+     * (`paths`, used to prune `expandedOverrides` -- see `willUpdate()`).
+     * Guards against a self-referencing `data` the same way `renderNode()`
+     * does: a container value already on the current recursion path is
+     * treated as a leaf instead of being walked again.
+     */
     computeSearch() {
         const query = this.search.trim().toLowerCase();
-        if (!query)
-            return EMPTY_SEARCH;
         const keyMatches = new Set();
         const valueMatches = new Set();
         const forceExpand = new Set();
+        const paths = new Set();
+        const ancestors = new WeakSet();
         const markAncestors = (path) => {
             for (let i = path.length - 1; i >= 0; i--)
                 forceExpand.add(JSON.stringify(path.slice(0, i)));
         };
         const walk = (value, path, keyLabel) => {
             const pathKey = JSON.stringify(path);
-            let hit = false;
-            if (keyLabel !== undefined && keyLabel.toLowerCase().includes(query)) {
-                keyMatches.add(pathKey);
-                hit = true;
-            }
+            paths.add(pathKey);
             const type = valueType(value);
-            if (type !== 'object' && type !== 'array' && formatPrimitive(value, type).toLowerCase().includes(query)) {
-                valueMatches.add(pathKey);
-                hit = true;
+            if (query) {
+                let hit = false;
+                if (keyLabel !== undefined && keyLabel.toLowerCase().includes(query)) {
+                    keyMatches.add(pathKey);
+                    hit = true;
+                }
+                if (type !== 'object' && type !== 'array' && formatPrimitive(value, type).toLowerCase().includes(query)) {
+                    valueMatches.add(pathKey);
+                    hit = true;
+                }
+                if (hit)
+                    markAncestors(path);
+            }
+            if ((type === 'object' || type === 'array') && !ancestors.has(value)) {
+                ancestors.add(value);
+                for (const [k, v] of entriesOf(value))
+                    walk(v, [...path, k], String(k));
+                ancestors.delete(value);
             }
-            if (hit)
-                markAncestors(path);
-            for (const [k, v] of entriesOf(value))
-                walk(v, [...path, k], String(k));
         };
         walk(this.data, []);
-        return { keyMatches, valueMatches, forceExpand };
+        return { keyMatches, valueMatches, forceExpand, paths };
     }
-    renderCopyButton(value) {
+    renderCopyButton(value, label) {
         if (!this.copyable)
             return nothing;
         return html `
       <button
         part="copy-button"
         type="button"
-        aria-label="Copy value"
+        aria-label="Copy ${label ?? 'value'}"
         @click=${(e) => {
             e.stopPropagation();
             this.copy(value);
@@ -176,10 +211,15 @@ export class LyraJsonViewer extends LyraElement {
       </button>
     `;
     }
-    renderNode(value, path, keyLabel, depth, search) {
+    renderNode(value, path, keyLabel, depth, search, ancestors) {
         const pathKey = JSON.stringify(path);
         const type = valueType(value);
-        const isContainer = type === 'object' || type === 'array';
+        // A container value already on the current recursion path (i.e. `data`
+        // self-references, directly or through a longer cycle) gets rendered as
+        // a leaf marker instead of recursing again -- recursing would blow the
+        // stack instead of degrading gracefully.
+        const isCircular = (type === 'object' || type === 'array') && ancestors.has(value);
+        const isContainer = (type === 'object' || type === 'array') && !isCircular;
         const entries = isContainer ? entriesOf(value) : [];
         const hasEntries = entries.length > 0;
         const expanded = hasEntries && this.isExpanded(pathKey, depth, search.forceExpand);
@@ -187,6 +227,17 @@ export class LyraJsonViewer extends LyraElement {
         const toggleLabel = keyLabel ?? (type === 'array' ? 'array' : type === 'object' ? 'object' : 'value');
         const openBracket = type === 'array' ? '[' : '{';
         const closeBracket = type === 'array' ? ']' : '}';
+        // Computed eagerly -- in this same synchronous call, rather than left for
+        // lit-html's `repeat` directive to invoke lazily during commit -- so the
+        // `ancestors.add()`/`.delete()` pair below brackets exactly the values on
+        // the real recursive descent through *this* subtree, regardless of
+        // whenever lit-html itself gets around to resolving the directive.
+        let childRows = [];
+        if (isContainer && expanded) {
+            ancestors.add(value);
+            childRows = entries.map(([k, v]) => this.renderNode(v, [...path, k], String(k), depth + 1, search, ancestors));
+            ancestors.delete(value);
+        }
         const headRow = html `
       <div class="row" style=${indentStyle}>
         <button
@@ -205,18 +256,24 @@ export class LyraJsonViewer extends LyraElement {
             ? html `<span part="key" ?data-match=${search.keyMatches.has(pathKey)}>${keyLabel}</span
               ><span class="colon">:</span>`
             : nothing}
-        ${isContainer
+        ${isCircular
             ? html `
               <span part="bracket">${openBracket}</span>
-              ${hasEntries && !expanded
-                ? html `<span class="preview">${previewText(value, type, entries.length)}</span>`
-                : nothing}
-              ${!expanded ? html `<span part="bracket">${closeBracket}</span>` : nothing}
+              <span part="value" data-type="circular">Circular reference</span>
+              <span part="bracket">${closeBracket}</span>
             `
-            : html `<span part="value" data-type=${type} ?data-match=${search.valueMatches.has(pathKey)}
-              >${formatPrimitive(value, type)}</span
-            >`}
-        ${this.renderCopyButton(value)}
+            : isContainer
+                ? html `
+                <span part="bracket">${openBracket}</span>
+                ${hasEntries && !expanded
+                    ? html `<span class="preview">${previewText(value, type, entries.length)}</span>`
+                    : nothing}
+                ${!expanded ? html `<span part="bracket">${closeBracket}</span>` : nothing}
+              `
+                : html `<span part="value" data-type=${type} ?data-match=${search.valueMatches.has(pathKey)}
+                >${formatPrimitive(value, type)}</span
+              >`}
+        ${this.renderCopyButton(value, toggleLabel)}
       </div>
     `;
         // Always returned from this one call site, with a single conditional
@@ -231,7 +288,7 @@ export class LyraJsonViewer extends LyraElement {
       ${isContainer && expanded
             ? html `
             <div class="children">
-              ${repeat(entries, ([k]) => JSON.stringify([...path, k]), ([k, v]) => this.renderNode(v, [...path, k], String(k), depth + 1, search))}
+              ${repeat(entries, ([k]) => JSON.stringify([...path, k]), (_entry, i) => childRows[i])}
             </div>
             <div class="row" style=${indentStyle}>
               <span class="toggle-space" aria-hidden="true"></span>
@@ -241,8 +298,29 @@ export class LyraJsonViewer extends LyraElement {
             : nothing}
     `;
     }
+    willUpdate(changed) {
+        if (!this.hasUpdated || changed.has('data') || changed.has('search')) {
+            const next = this.computeSearch();
+            if (!this.hasUpdated || changed.has('data')) {
+                // A path with no entry in `next.paths` no longer exists anywhere in
+                // the new tree, so its override has nothing left to apply to --
+                // dropping it here (rather than never, as before) is what keeps a
+                // long-lived instance bound to reshaping data from accumulating one
+                // Map entry per distinct path ever toggled over its whole lifetime.
+                let pruned = null;
+                for (const key of this.expandedOverrides.keys()) {
+                    if (!next.paths.has(key)) {
+                        pruned ??= new Map(this.expandedOverrides);
+                        pruned.delete(key);
+                    }
+                }
+                if (pruned)
+                    this.expandedOverrides = pruned;
+            }
+            this.searchState = next;
+        }
+    }
     render() {
-        const search = this.computeSearch();
         return html `
       <div part="base" style=${this.maxHeight ? `--lyra-json-viewer-max-height:${this.maxHeight}` : nothing}>
         ${this.copyable
@@ -257,7 +335,7 @@ export class LyraJsonViewer extends LyraElement {
               </button>
             </div>`
             : nothing}
-        <div part="tree">${this.renderNode(this.data, [], undefined, 0, search)}</div>
+        <div part="tree">${this.renderNode(this.data, [], undefined, 0, this.searchState, new WeakSet())}</div>
       </div>
     `;
     }

package/dist/components/json-viewer/json-viewer.styles.js

@@ -132,7 +132,8 @@ export const styles = css `
     color: var(--lyra-color-warning);
   }
   [part='value'][data-type='null'],
-  [part='value'][data-type='undefined'] {
+  [part='value'][data-type='undefined'],
+  [part='value'][data-type='circular'] {
     color: var(--lyra-color-text-quiet);
     font-style: italic;
   }

package/dist/components/kbd/kbd.js

@@ -111,6 +111,17 @@ function detectIsMac() {
 // little cost, however small) from re-detecting it on every <lyra-kbd>
 // instance or every re-render.
 const IS_MAC = detectIsMac();
+// The one "is there real content" predicate shared by both the initial
+// synchronous seed (willUpdate, reading light-DOM childNodes) and the
+// runtime slotchange handler (reading assignedNodes) — using two different
+// predicates for the same question let them disagree: a text-only check
+// would seed correctly for whitespace-only text but (wrongly) treat a
+// content-less icon element as empty, and a node-count-only check would
+// treat *any* assigned node — including a whitespace-only text node — as
+// real content. Counting every element node as real content (regardless of
+// its own text) while requiring non-whitespace text from text nodes gets
+// both cases right in one place.
+const hasRealContent = (nodes) => Array.from(nodes).some((n) => n.nodeType === Node.ELEMENT_NODE || (n.textContent ?? '').trim().length > 0);
 /**
  * `<lyra-kbd>` — a small chip representing a keyboard shortcut, rendering
  * the platform-appropriate glyph for cross-platform modifier keys (⌘ on
@@ -162,13 +173,13 @@ export class LyraKbd extends LyraElement {
         // 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;
+            this.hasCustomContent = hasRealContent(e.target.assignedNodes({ flatten: true }));
         };
     }
     static { this.styles = [LyraElement.styles, styles]; }
     willUpdate() {
         if (!this.hasUpdated) {
-            this.hasCustomContent = Array.from(this.childNodes).some((n) => (n.textContent ?? '').trim().length > 0);
+            this.hasCustomContent = hasRealContent(this.childNodes);
         }
     }
     render() {
@@ -185,15 +196,21 @@ export class LyraKbd extends LyraElement {
         // 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.
+        // the single spelled-out aria-label below. An empty `keys` (and no
+        // explicit override) renders nothing visible, so it's marked
+        // aria-hidden instead of exposed as a nameless image.
+        //
+        // role/aria-hidden are both derived from this same `ariaLabel` value
+        // (rather than each independently re-deriving "is there a label" from
+        // tokens.length/explicitLabel) so role="img" can never be absent while
+        // aria-label is present — that combination is an aria-prohibited-attr
+        // violation (a nameless-but-labeled, role-less element).
         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}
+        role=${ariaLabel ? 'img' : nothing}
+        aria-hidden=${ariaLabel ? nothing : 'true'}
         aria-label=${ariaLabel || nothing}
       >
         ${tokens.map((t, i) => html `

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

@@ -50,7 +50,14 @@ export type LiveRegionMode = 'polite' | 'assertive';
 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. */
+     *  (role="alert") interrupts. Mirrors native `aria-live` semantics.
+     *
+     *  `write()` also applies `role`/`aria-live` imperatively at announce time
+     *  (not only through this property's template binding) so a caller that
+     *  sets `mode` and immediately force-announces in the same synchronous
+     *  turn -- e.g. a stream-status transition -- gets the new urgency and the
+     *  new text landing together, rather than the text beating Lit's
+     *  re-render to the DOM. */
     mode: LiveRegionMode;
     /** Throttle window in ms — see `Announcer` in `internal/announcer.ts`. */
     throttleMs: number;
@@ -58,6 +65,7 @@ export declare class LyraLiveRegion extends LyraElement {
     private lastWritten;
     private regionEl?;
     private reannounceHandle?;
+    private reannounceView?;
     private pendingWrite?;
     constructor();
     protected updated(changed: PropertyValues): void;
@@ -72,6 +80,7 @@ export declare class LyraLiveRegion extends LyraElement {
      */
     announce(text: string, options?: AnnounceOptions): void;
     private write;
+    private cancelReannounce;
     render(): TemplateResult;
 }
 declare global {

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

@@ -61,7 +61,14 @@ export class LyraLiveRegion extends LyraElement {
     constructor() {
         super();
         /** `polite` (role="status") waits for the user to be idle; `assertive`
-         *  (role="alert") interrupts. Mirrors native `aria-live` semantics. */
+         *  (role="alert") interrupts. Mirrors native `aria-live` semantics.
+         *
+         *  `write()` also applies `role`/`aria-live` imperatively at announce time
+         *  (not only through this property's template binding) so a caller that
+         *  sets `mode` and immediately force-announces in the same synchronous
+         *  turn -- e.g. a stream-status transition -- gets the new urgency and the
+         *  new text landing together, rather than the text beating Lit's
+         *  re-render to the DOM. */
         this.mode = 'polite';
         /** Throttle window in ms — see `Announcer` in `internal/announcer.ts`. */
         this.throttleMs = 500;
@@ -94,10 +101,8 @@ export class LyraLiveRegion extends LyraElement {
     disconnectedCallback() {
         super.disconnectedCallback();
         this.announcer.cancel();
-        if (this.reannounceHandle !== undefined) {
-            cancelAnimationFrame(this.reannounceHandle);
-            this.reannounceHandle = undefined;
-        }
+        this.pendingWrite = undefined;
+        this.cancelReannounce();
     }
     /**
      * Queue `text` for announcement. Calls arriving within `throttle-ms` of
@@ -115,6 +120,13 @@ export class LyraLiveRegion extends LyraElement {
             this.pendingWrite = text;
             return;
         }
+        // A same-text reannounce frame still in flight is now stale the moment
+        // any new write() call comes in -- if it fired later it would clobber
+        // whatever text this call is about to land with the older, already-
+        // superseded string. Cancel it up front so at most one reannounce is
+        // ever pending and it can never overwrite a newer announcement.
+        this.cancelReannounce();
+        const assertive = this.mode === 'assertive';
         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
@@ -122,17 +134,41 @@ export class LyraLiveRegion extends LyraElement {
             // (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.
+            //
+            // role/aria-live are set imperatively here (not left to Lit's
+            // template binding) so a caller that sets `mode` and immediately
+            // force-announces -- e.g. stream-status's announceTransition() --
+            // gets the new urgency in the same synchronous operation as the text,
+            // rather than racing Lit's async re-render.
+            region.setAttribute('role', assertive ? 'alert' : 'status');
+            region.setAttribute('aria-live', assertive ? 'assertive' : 'polite');
             region.textContent = '';
-            this.reannounceHandle = requestAnimationFrame(() => {
+            const view = region.ownerDocument.defaultView;
+            if (!view) {
+                region.textContent = text;
+                return;
+            }
+            this.reannounceView = view;
+            this.reannounceHandle = view.requestAnimationFrame(() => {
                 this.reannounceHandle = undefined;
+                this.reannounceView = undefined;
                 region.textContent = text;
             });
         }
         else {
+            region.setAttribute('role', assertive ? 'alert' : 'status');
+            region.setAttribute('aria-live', assertive ? 'assertive' : 'polite');
             region.textContent = text;
         }
         this.lastWritten = text;
     }
+    cancelReannounce() {
+        if (this.reannounceHandle === undefined)
+            return;
+        this.reannounceView?.cancelAnimationFrame(this.reannounceHandle);
+        this.reannounceHandle = undefined;
+        this.reannounceView = undefined;
+    }
     render() {
         const assertive = this.mode === 'assertive';
         return html `<div

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

@@ -41,10 +41,22 @@ export interface MapMarker {
  * choropleth GeoJSON layer, plus a raw `map` escape hatch. Requires the
  * optional peer dep `maplibre-gl` (consumers also import its CSS once).
  *
+ * The underlying `maplibregl.Map` — and the WebGL context it opens — isn't
+ * constructed until this element is first visible in the viewport (tracked
+ * via `IntersectionObserver`), even once the `maplibre-gl` peer dependency
+ * has finished loading. Browsers hard-cap concurrent WebGL contexts per
+ * page, so a grid/dashboard of many `<lyra-map>` instances only constructs
+ * the ones actually on-screen instead of racing to exhaust that budget the
+ * instant each one mounts. `map` stays `undefined` (and `lyra-map-load`
+ * doesn't fire) until construction actually happens.
+ *
  * @customElement lyra-map
  * @event lyra-map-load - Fired once the underlying maplibregl.Map loads.
  * @event lyra-map-click - `detail: { lngLat, feature? }`.
- * @csspart base, container, legend, legend-swatch
+ * @csspart base - The map wrapper.
+ * @csspart container - The maplibre container.
+ * @csspart legend - The map legend.
+ * @csspart legend-swatch - A legend color swatch.
  *
  * ⚠️ The default `mapStyle` (when unset) uses OpenStreetMap's demo tile
  * server, which is not suitable for production traffic — see the
@@ -61,6 +73,8 @@ export declare class LyraMap extends LyraElement {
     markers: MapMarker[];
     /** True until the lazy-loaded `maplibre-gl` peer dependency has settled (success or failure). */
     private loading;
+    private visible;
+    private intersectionObserver?;
     private containerEl?;
     private _map?;
     private _styleLoaded;
@@ -74,6 +88,15 @@ export declare class LyraMap extends LyraElement {
     get map(): import('maplibre-gl').Map | undefined;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * Constructs the underlying `maplibregl.Map` — called once both the
+     * lazy-loaded `maplibre-gl` module has resolved and this element has been
+     * observed intersecting the viewport, whichever settles last. Idempotent
+     * (a no-op once `_map` already exists), so it's safe to call from both the
+     * `connectedCallback()` load path and the visibility path in `updated()`
+     * below without risking a double construction.
+     */
+    private tryConstructMap;
     protected updated(changed: PropertyValues): void;
     private applyChoropleth;
     /** Removes whatever choropleth layer/source is currently applied, if any. */