@aceshooting/lyra-ui 2.0.0 → 2.1.0

package/dist/components/dialog/dialog.js

@@ -9,74 +9,74 @@ import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { lockScroll } from '../../internal/scroll-lock.js';
+import { activateOverlay } from '../../internal/overlay-manager.js';
 import { nextId, srOnly } from '../../internal/a11y.js';
+import { closeIcon } from '../../internal/icons.js';
 import { styles } from './dialog.styles.js';
-const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
 const HEADING_SELECTOR = 'h1, h2, h3, h4, h5, h6, [role="heading"]';
-// Shadow-piercing so a slotted custom element's real focusable target (e.g.
-// an <input> inside its own shadow root) is found even though the host tag
-// itself doesn't match FOCUSABLE_SELECTOR. Deliberately duplicated from
-// lyra-widget's identical helper rather than imported/shared -- widget's
-// fullscreen mode is a separate feature and this component must not depend
-// on it (see the module doc in dialog.ts's authoring notes).
-function collectFocusable(el) {
-    const result = [];
-    if (el.matches(FOCUSABLE_SELECTOR)) {
-        result.push(el);
-    }
-    if (el instanceof HTMLSlotElement) {
-        for (const assigned of el.assignedElements({ flatten: true })) {
-            result.push(...collectFocusable(assigned));
-        }
-        return result;
-    }
-    const container = el.shadowRoot ?? el;
-    for (const child of Array.from(container.children)) {
-        result.push(...collectFocusable(child));
-    }
-    return result;
-}
-/** Whether `el` is actually laid out/paintable -- `checkVisibility()` (falling
- *  back to `getClientRects().length` where unsupported) correctly follows
- *  flattened-tree/slot assignment, unlike `offsetParent`. Mirrors
- *  lyra-widget's identical helper. */
-function isRendered(el) {
-    return el.checkVisibility ? el.checkVisibility() : el.getClientRects().length > 0;
-}
 /**
  * `<lyra-dialog>` — a general-purpose modal/overlay. `role="dialog"`,
  * focus-trapped while open, dismissible via Escape or a backdrop click, and
- * scroll-locks the document for as long as it's open. Chrome stays minimal —
- * no built-in title bar or close button; a consumer supplies a heading and
- * any close affordance itself via the default/`footer` slots.
+ * scroll-locks the document for as long as it's open. Chrome stays minimal by
+ * default — no built-in title bar or close button; a consumer supplies a
+ * heading and any close affordance itself via the default/`footer` slots.
+ * `heading`/`closable` are an opt-in convenience for the common case where
+ * hand-building that chrome isn't worth it (see below).
  *
- * Accessible name: if a heading element (`h1`–`h6` or `[role="heading"]`) is
- * a *direct child* (not inside `slot="footer"`), its text content becomes
- * `aria-label` on the panel. Otherwise, when `label` is set, an invisible
- * (`.sr-only`, exposed as the `label` part) element carrying that text is
- * rendered inside the panel and `aria-labelledby` points at it instead.
- * Either way `label` itself never renders visible chrome — a slotted heading
- * is what a sighted user sees; `::part(label)` can be restyled to make the
- * sr-only text visible too, if a consumer wants that instead of slotting a
- * heading.
+ * Accessible name / visible header, in priority order:
+ * 1. If a heading element (`h1`–`h6` or `[role="heading"]`) is a *direct
+ *    child* (not inside `slot="footer"`), its text content becomes
+ *    `aria-label` on the panel — unchanged, and takes priority over `heading`
+ *    below so an existing consumer that already slots its own heading keeps
+ *    rendering it exactly as before.
+ * 2. Otherwise, when `heading` is set, a visible header row (`part="header"`)
+ *    renders containing that text (`part="heading"`), which becomes the
+ *    `aria-labelledby` target.
+ * 3. Otherwise, when `label` is set, an invisible (`.sr-only`, exposed as the
+ *    `label` part) element carrying that text is rendered inside the panel
+ *    and `aria-labelledby` points at it instead.
+ * Only one of cases 2/3 ever renders at a time, so exactly one element ever
+ * claims `aria-labelledby`. `label` itself never renders visible chrome on
+ * its own — `::part(label)` can be restyled to make the sr-only text visible,
+ * or `heading` can be set instead, if a consumer wants visible chrome without
+ * slotting a real heading element.
  *
- * The heading case deliberately uses `aria-label` (a copied string) rather
- * than `aria-labelledby` pointing at the heading's `id`: the heading is
+ * The slotted-heading case deliberately uses `aria-label` (a copied string)
+ * rather than `aria-labelledby` pointing at the heading's `id`: the heading is
  * *light-DOM* content while `[part="panel"]` lives in this element's
  * *shadow* tree, and an ID-reference attribute can't resolve across that
  * boundary (verified against axe's `aria-dialog-name` rule) — unlike the
- * `label`-prop case above, where the sr-only element is rendered inside the
- * same shadow root it labels, so `aria-labelledby` there is safe.
+ * `heading`/`label`-prop cases above, where the target element is rendered
+ * inside the same shadow root it labels, so `aria-labelledby` there is safe.
+ *
+ * `closable` renders a close (X) button in the header row (creating one, with
+ * no heading text, if `heading` is unset) that closes the dialog via the same
+ * `close()` path as Escape/backdrop-dismiss, with reason `'close-button'`.
+ *
+ * Stacking: opening one `<lyra-dialog>` while another is already open (e.g. a
+ * `confirm()` launched from within an already-open dialog) is supported --
+ * Escape and the Tab focus trap only ever act on the topmost open dialog, so
+ * dialogs beneath it stay open and untouched until the one on top closes.
  *
  * @customElement lyra-dialog
  * @slot - The dialog body.
  * @slot footer - Action buttons, rendered in a bottom row.
  * @event lyra-dialog-close - `detail: DialogCloseReason`. Fired whenever the
- *   dialog is dismissed via Escape, a backdrop click, or a `close()` call.
+ *   dialog is dismissed via Escape, a backdrop click, the built-in close
+ *   button (`closable`), a `close()` call, or (with reason `'unmount'`)
+ *   removal from the DOM by anything else while still open.
  * @csspart backdrop - The full-viewport scrim behind the panel.
- * @csspart panel - The dialog panel itself (`role="dialog"` while open).
+ * @csspart panel - The dialog panel itself (`role="dialog"` while open). Its
+ *   max-inline-size is controlled by the `--lyra-dialog-max-width` custom
+ *   property (default `32rem`).
+ * @csspart header - The header row, rendered when `heading` is set (and no
+ *   heading is slotted) and/or `closable` is `true`.
+ * @csspart heading - The visible `heading`-text element inside `header`,
+ *   rendered only when `heading` is set and no heading is slotted.
+ * @csspart close-button - The built-in close button, rendered inside `header`
+ *   only when `closable` is `true`.
  * @csspart label - The invisible `label`-text element used for
- *   `aria-labelledby` when no heading is slotted.
+ *   `aria-labelledby` when no heading is slotted and `heading` is unset.
  * @csspart body - The wrapper around the default slot.
  * @csspart footer - The wrapper around the `footer` slot.
  */
@@ -87,8 +87,14 @@ export class LyraDialog extends LyraElement {
         this.open = false;
         /** Accessible name used when no heading is slotted — see the class doc for the full fallback order. */
         this.label = '';
+        /** Renders a built-in close (X) button in the header row (creating one,
+         *  with no heading text, if `heading` is unset), wired to the same
+         *  `close()` path Escape/backdrop-dismiss already use, with reason
+         *  `'close-button'`. */
+        this.closable = false;
         this.hasFooterSlot = false;
         this.srLabelId = nextId('dialog-label');
+        this.headingId = nextId('dialog-heading');
         this.onDefaultSlotChange = () => {
             this.detectHeading();
         };
@@ -96,34 +102,10 @@ export class LyraDialog extends LyraElement {
             this.hasFooterSlot = e.target.assignedElements({ flatten: true }).length > 0;
         };
         this.onBackdropClick = () => {
-            this.close('backdrop');
+            this.overlay?.dismissBackdrop();
         };
-        this.onDocKeyDown = (e) => {
-            if (!this.open)
-                return;
-            if (e.key === 'Escape') {
-                e.preventDefault();
-                this.close('escape');
-                return;
-            }
-            if (e.key !== 'Tab')
-                return;
-            const focusable = this.getFocusableElements();
-            if (focusable.length === 0) {
-                e.preventDefault();
-                return;
-            }
-            const first = focusable[0];
-            const last = focusable[focusable.length - 1];
-            const active = this.getActiveElement();
-            if (e.shiftKey && active === first) {
-                e.preventDefault();
-                last.focus();
-            }
-            else if (!e.shiftKey && active === last) {
-                e.preventDefault();
-                first.focus();
-            }
+        this.onCloseButtonClick = () => {
+            this.close('close-button');
         };
     }
     static { this.styles = [LyraElement.styles, srOnly, styles]; }
@@ -134,35 +116,18 @@ export class LyraDialog extends LyraElement {
         }
         if (changed.has('open')) {
             if (this.open) {
-                // Captured here (before render) rather than from a click event on
-                // some specific internal control -- unlike lyra-widget's fullscreen
-                // toggle, a dialog's trigger typically lives *outside* the
-                // component entirely, so "whatever had focus right before open"
-                // is the only generally correct definition of "the trigger".
-                const active = this.getActiveElement();
-                this.lastTrigger = active instanceof HTMLElement ? active : undefined;
-                this.releaseScrollLock = lockScroll();
-                document.addEventListener('keydown', this.onDocKeyDown);
+                this.activateOverlay();
             }
             else {
-                this.releaseScrollLock?.();
-                this.releaseScrollLock = undefined;
-                document.removeEventListener('keydown', this.onDocKeyDown);
+                this.deactivateOverlay();
             }
         }
     }
-    // Runs after render (not willUpdate) so [part="panel"] has already landed
-    // in the DOM before the fallback .focus() call below can rely on it --
-    // mirrors lyra-widget's identical ordering rationale for its fullscreen mode.
+    // Runs after render so the manager can resolve the panel and its composed
+    // focus targets, including controls projected through either slot.
     updated(changed) {
         if (changed.has('open') && this.open) {
-            const first = this.getFocusableElements()[0];
-            if (first) {
-                first.focus();
-            }
-            else {
-                this.shadowRoot?.querySelector('[part="panel"]')?.focus();
-            }
+            this.overlay?.focusInitial();
         }
     }
     connectedCallback() {
@@ -171,16 +136,40 @@ export class LyraDialog extends LyraElement {
         // instance) fires disconnectedCallback then connectedCallback
         // synchronously with no update in between, so willUpdate never reruns to
         // notice `open` is still true -- restore the scroll lock/trap it dropped.
-        if (this.hasUpdated && this.open && !this.releaseScrollLock) {
-            this.releaseScrollLock = lockScroll();
-            document.addEventListener('keydown', this.onDocKeyDown);
+        if (this.hasUpdated && this.open) {
+            if (this.overlay?.isActive()) {
+                this.overlay.resume();
+                this.releaseScrollLock ??= lockScroll(this.ownerDocument);
+            }
+            else {
+                this.activateOverlay();
+            }
+            queueMicrotask(() => this.overlay?.focusInitial());
         }
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.releaseScrollLock?.();
         this.releaseScrollLock = undefined;
-        document.removeEventListener('keydown', this.onDocKeyDown);
+        this.overlay?.suspend();
+        if (this.open) {
+            // A reparent (drag-and-drop moving this same element instance to a new
+            // parent) fires disconnectedCallback immediately followed by a
+            // synchronous connectedCallback, with no turn of the event loop in
+            // between -- deferring this check a microtask lets that case
+            // short-circuit here once isConnected is true again, so only a genuine
+            // removal (the element still disconnected once microtasks flush) ever
+            // reaches the assignment below. Without this, removing an open dialog
+            // any way other than its own close() (a consumer's own DOM cleanup, a
+            // parent re-render that drops it, etc.) never fires
+            // `lyra-dialog-close`, so e.g. confirm()'s returned promise hangs forever.
+            queueMicrotask(() => {
+                if (!this.isConnected && this.open) {
+                    this.open = false;
+                    this.emit('lyra-dialog-close', 'unmount');
+                }
+            });
+        }
     }
     // Only direct children are scanned -- a heading nested several layers deep
     // (or inside a slotted custom element's own shadow root) is left to the
@@ -197,43 +186,43 @@ export class LyraDialog extends LyraElement {
     /**
      * Close the dialog and return focus to whatever had it before the dialog
      * opened. `reason` is forwarded as the `lyra-dialog-close` detail --
-     * built-in triggers pass `'escape'`/`'backdrop'`; a consumer's own close
-     * affordance (e.g. a footer Cancel button) should call this directly with
-     * its own reason string, so every dismissal path funnels through the same
-     * event instead of the consumer having to also toggle `open` itself.
+     * built-in triggers pass `'escape'`/`'backdrop'`/`'close-button'`; a
+     * consumer's own close affordance (e.g. a footer Cancel button) should
+     * call this directly with its own reason string, so every dismissal path
+     * funnels through the same event instead of the consumer having to also
+     * toggle `open` itself.
      */
     close(reason = 'api') {
         if (!this.open)
             return;
         this.open = false;
         this.emit('lyra-dialog-close', reason);
-        this.lastTrigger?.focus();
     }
-    // Bounds Tab/Shift+Tab to the panel while open. Order follows the default
-    // (body) slot, then the footer slot -- the same order the flattened tree
-    // already tabs through.
-    getFocusableElements() {
-        const root = this.shadowRoot;
-        if (!root)
-            return [];
-        const fromSlot = (selector) => {
-            const slot = root.querySelector(selector);
-            return slot ? slot.assignedElements({ flatten: true }).flatMap(collectFocusable) : [];
-        };
-        return [...fromSlot('slot:not([name])'), ...fromSlot('slot[name="footer"]')].filter(isRendered);
+    activateOverlay() {
+        if (this.overlay?.isActive())
+            return;
+        this.releaseScrollLock ??= lockScroll(this.ownerDocument);
+        this.overlay = activateOverlay({
+            host: this,
+            panel: () => this.shadowRoot?.querySelector('[part="panel"]') ?? null,
+            onEscape: () => this.close('escape'),
+            onBackdrop: () => this.close('backdrop'),
+        });
     }
-    getActiveElement() {
-        let active = document.activeElement;
-        while (active) {
-            const inner = active.shadowRoot?.activeElement ?? null;
-            if (!inner)
-                break;
-            active = inner;
-        }
-        return active;
+    deactivateOverlay() {
+        this.releaseScrollLock?.();
+        this.releaseScrollLock = undefined;
+        this.overlay?.deactivate();
+        this.overlay = undefined;
     }
     render() {
-        const useSrLabel = !this.headingText && this.label.length > 0;
+        // Priority order (see class doc): a slotted heading always wins; only
+        // when there isn't one does `heading` get a turn, then `label`'s
+        // sr-only fallback -- never more than one of the two below claims
+        // aria-labelledby for the same panel.
+        const useHeadingProp = !this.headingText && !!this.heading;
+        const useSrLabel = !this.headingText && !useHeadingProp && this.label.length > 0;
+        const showHeader = useHeadingProp || this.closable;
         return html `
       <div part="backdrop" @click=${this.onBackdropClick}></div>
       <div
@@ -241,12 +230,33 @@ export class LyraDialog extends LyraElement {
         role=${this.open ? 'dialog' : nothing}
         aria-modal=${this.open ? 'true' : nothing}
         aria-label=${this.headingText ?? nothing}
-        aria-labelledby=${useSrLabel ? this.srLabelId : nothing}
+        aria-labelledby=${useHeadingProp ? this.headingId : useSrLabel ? this.srLabelId : nothing}
         tabindex="-1"
       >
         ${useSrLabel
             ? html `<span id=${this.srLabelId} part="label" class="sr-only">${this.label}</span>`
             : nothing}
+        ${showHeader
+            ? html `
+              <div part="header">
+                ${useHeadingProp
+                ? html `<span id=${this.headingId} part="heading">${this.heading}</span>`
+                : nothing}
+                ${this.closable
+                ? html `
+                      <button
+                        part="close-button"
+                        type="button"
+                        aria-label="Close"
+                        @click=${this.onCloseButtonClick}
+                      >
+                        ${closeIcon()}
+                      </button>
+                    `
+                : nothing}
+              </div>
+            `
+            : nothing}
         <div part="body">
           <slot @slotchange=${this.onDefaultSlotChange}></slot>
         </div>
@@ -263,6 +273,12 @@ __decorate([
 __decorate([
     property()
 ], LyraDialog.prototype, "label", void 0);
+__decorate([
+    property()
+], LyraDialog.prototype, "heading", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'closable' })
+], LyraDialog.prototype, "closable", void 0);
 __decorate([
     state()
 ], LyraDialog.prototype, "hasFooterSlot", void 0);

package/dist/components/dialog/dialog.styles.js

@@ -9,7 +9,7 @@ export const styles = css `
     display: none;
     position: fixed;
     inset: 0;
-    z-index: 1000;
+    z-index: var(--lyra-overlay-stack-index, 1000);
     align-items: center;
     justify-content: center;
     padding: var(--lyra-space-l);
@@ -26,7 +26,10 @@ export const styles = css `
     position: relative;
     display: flex;
     flex-direction: column;
-    max-inline-size: min(32rem, 100%);
+    /* --lyra-dialog-max-width lets a consumer widen/narrow the panel per
+       instance (e.g. inline on the host) without overriding the whole rule --
+       same convention as lyra-media-card's --lyra-media-card-max-height. */
+    max-inline-size: min(var(--lyra-dialog-max-width, 32rem), 100%);
     max-block-size: 100%;
     background: var(--lyra-color-surface);
     border: 1px solid var(--lyra-color-border);
@@ -34,6 +37,47 @@ export const styles = css `
     box-shadow: var(--lyra-shadow);
     overflow: auto;
   }
+  [part='header'] {
+    display: flex;
+    align-items: center;
+    gap: var(--lyra-space-s);
+    padding: var(--lyra-space-m) var(--lyra-space-l);
+    border-block-end: 1px solid var(--lyra-color-border);
+  }
+  [part='heading'] {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    margin: 0;
+    font-weight: 600;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  [part='close-button'] {
+    flex: 0 0 auto;
+    margin-inline-start: auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-inline-size: var(--lyra-icon-button-size);
+    min-block-size: var(--lyra-icon-button-size);
+    border: none;
+    background: transparent;
+    color: var(--lyra-color-text-quiet);
+    border-radius: var(--lyra-radius);
+    cursor: pointer;
+  }
+  [part='close-button']:hover {
+    background: var(--lyra-color-brand-quiet);
+    color: var(--lyra-color-brand);
+  }
+  [part='close-button']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+  [part='close-button'] svg {
+    display: block;
+  }
   [part='body'] {
     padding: var(--lyra-space-l);
     overflow: auto;

package/dist/components/dock-panel/dock-panel.d.ts

@@ -87,8 +87,16 @@ export declare class LyraDockPanel extends LyraElement {
     resizable: boolean;
     private drag;
     private readonly contentId;
+    private containerResizeObserver?;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** Creates (idempotently) and (re-)observes the containing element with a
+     *  `ResizeObserver` that just requests a re-render on every callback --
+     *  `containerPx()`/`currentSizePx()` already read the live DOM on every
+     *  render, so there's no separate cached value to update here, only the
+     *  render that was otherwise never being triggered. A no-op when not yet
+     *  connected (no `parentElement`). */
+    private armContainerResizeObserver;
     protected willUpdate(changed: PropertyValues): void;
     /** `'inline'` for the `start`/`end` edges (resizing changes `inline-size`), `'block'` for
      *  `top`/`bottom` (resizing changes `block-size`). */

package/dist/components/dock-panel/dock-panel.js

@@ -177,6 +177,7 @@ export class LyraDockPanel extends LyraElement {
     connectedCallback() {
         super.connectedCallback();
         this.applyHostSize();
+        this.armContainerResizeObserver();
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -185,6 +186,19 @@ export class LyraDockPanel extends LyraElement {
         window.removeEventListener('pointerup', this.onPointerUp);
         window.removeEventListener('pointercancel', this.onPointerUp);
         window.removeEventListener('lostpointercapture', this.onPointerUp);
+        this.containerResizeObserver?.disconnect();
+    }
+    /** Creates (idempotently) and (re-)observes the containing element with a
+     *  `ResizeObserver` that just requests a re-render on every callback --
+     *  `containerPx()`/`currentSizePx()` already read the live DOM on every
+     *  render, so there's no separate cached value to update here, only the
+     *  render that was otherwise never being triggered. A no-op when not yet
+     *  connected (no `parentElement`). */
+    armContainerResizeObserver() {
+        if (!this.parentElement)
+            return;
+        this.containerResizeObserver ??= new ResizeObserver(() => this.requestUpdate());
+        this.containerResizeObserver.observe(this.parentElement);
     }
     // Applied in willUpdate (before render), not updated (after render): the
     // handle's aria-valuenow is computed during render from the host's own
@@ -275,7 +289,7 @@ export class LyraDockPanel extends LyraElement {
         if (this.edge === 'bottom')
             return this.collapsed ? -90 : 90;
         const pinnedPhysicalEnd = this.edge === 'end' ? !isRtl(this) : isRtl(this);
-        return this.collapsed === pinnedPhysicalEnd ? 0 : 180;
+        return this.collapsed !== pinnedPhysicalEnd ? 0 : 180;
     }
     handleTemplate() {
         if (!this.resizable || this.collapsed)

package/dist/components/dock-panel/dock-panel.styles.js

@@ -19,11 +19,25 @@ export const styles = css `
   :host([edge='start']),
   :host([edge='end']) {
     block-size: 100%;
-    min-inline-size: var(--lyra-dock-panel-collapsed-size);
   }
   :host([edge='top']),
   :host([edge='bottom']) {
     inline-size: 100%;
+  }
+  /* The collapsed-rail floor only applies once actually collapsed -- scoped
+     here rather than to the bare [edge] selectors above, so it can never
+     override a smaller explicit min-size (resolved in JS by
+     resolveBoundsPx()) while expanded. An unconditional floor here would
+     silently win over a min-size below the rail token's width, since a CSS
+     min-inline-size/min-block-size always wins over an inline size style
+     regardless of what value applySize() computed and announced via
+     aria-valuenow. */
+  :host([edge='start'][collapsed]),
+  :host([edge='end'][collapsed]) {
+    min-inline-size: var(--lyra-dock-panel-collapsed-size);
+  }
+  :host([edge='top'][collapsed]),
+  :host([edge='bottom'][collapsed]) {
     min-block-size: var(--lyra-dock-panel-collapsed-size);
   }
 

package/dist/components/document-preview/document-preview.d.ts

@@ -40,6 +40,13 @@ export type DocumentPreviewStatus = 'idle' | 'converting' | 'ready' | 'error';
  * that a *rendering* failure and a host's own state machine are different
  * concerns.
  *
+ * Every `src` is validated for the DOM/API sink that consumes it. Text
+ * fetches and image sources allow relative URLs plus `http:`, `https:`,
+ * `blob:`, and `data:`. Download links deliberately exclude `data:` because
+ * following a `data:text/html` URL can create an active document. Unsafe or
+ * malformed URLs never reach `fetch()`, an image `src`, or an anchor `href`;
+ * they render a non-interactive fallback/error instead.
+ *
  * Accessibility: the `"converting"` state (no numeric `progress`) is a
  * `role="status"` region wrapping a visually-hidden "Converting document…"
  * string. This is a *plain* static region, not routed through
@@ -61,10 +68,10 @@ export type DocumentPreviewStatus = 'idle' | 'converting' | 'ready' | 'error';
  *   component doesn't natively support (i.e. whenever format dispatch would
  *   otherwise fall through to "generic"). Ignored while `mime-type` resolves
  *   to `text`/`image` dispatch, or while `status` is `"converting"`/`"error"`.
- * @event lyra-download - `detail: { src, filename }` — fired when the
- *   generic-download fallback's link is activated. The browser download
- *   itself needs no JS (a plain `<a download>` handles it); this is purely
- *   for a host that wants to observe/log the download.
+ * @event lyra-download - `detail: { src, filename }` — fired when the safe
+ *   generic-download fallback link is activated. The browser download itself
+ *   needs no JS (a plain `<a download>` handles it); this is purely for a host
+ *   that wants to observe/log the download.
  * @event lyra-render-error - `detail: { error }` — fired when this
  *   component's own `text/*`/`application/json` `fetch(src)` fails. Distinct
  *   from `status="error"`, which is entirely host-driven (see the class
@@ -75,13 +82,14 @@ export type DocumentPreviewStatus = 'idle' | 'converting' | 'ready' | 'error';
  * @csspart body - The wrapper around whichever content is currently showing (text/image preview, the generic fallback, the spinner, or the error message).
  * @csspart spinner - The converting/loading indicator — indeterminate (`role="status"`) or, once numeric progress is known, a determinate `role="progressbar"`. Used both for `status="converting"` and for this component's own in-flight text fetch.
  * @csspart error - The error message region (`role="alert"`) — used both for `status="error"` and for a failed text fetch.
- * @csspart download-link - The `<a download>` affordance in the generic fallback. Only rendered when `src` is set.
+ * @csspart download-link - The `<a download>` affordance in the generic fallback. Only rendered when `src` is set and safe for link navigation.
  */
 export declare class LyraDocumentPreview extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
     /** URL to fetch (for `text`/`application/json`) or display (`image`, or as
-     *  the generic fallback's download `href`). Optional — gracefully absent
-     *  while, e.g., a conversion is still in progress. */
+     *  the generic fallback's download `href`). The value is validated against
+     *  a sink-specific scheme allowlist before use. Optional — gracefully
+     *  absent while, e.g., a conversion is still in progress. */
     src: string;
     /** Drives format dispatch — see the class doc. */
     mimeType: string;