@aceshooting/lyra-ui 1.2.0 → 2.0.0

package/dist/components/markdown/markdown-loader.d.ts

@@ -0,0 +1,34 @@
+import type * as MarkedModule from 'marked';
+import type DOMPurifyApi from 'dompurify';
+/**
+ * The two optional peers `<lyra-markdown>` needs, loaded independently (see
+ * `loadMarkdownAndSanitizer()`). Either half can be `undefined` on its own —
+ * a consumer who only installs `marked` (having explicitly opted out of
+ * sanitization via `sanitize="false"`) is a valid, supported combination.
+ */
+export interface MarkdownDeps {
+    marked: typeof MarkedModule | undefined;
+    DOMPurify: typeof DOMPurifyApi | undefined;
+}
+/**
+ * Independently loads the optional peer dependencies `marked` (Markdown
+ * parsing) and `dompurify` (HTML sanitizing), mirroring `chart-loader.ts`'s
+ * `loadChartAndZoom()` shape for two independent optional peers. A partial
+ * install — most usefully `marked` alone, for a consumer who has explicitly
+ * set `sanitize="false"` and doesn't need `dompurify` at all — degrades to
+ * "that one half is missing" rather than failing outright. Exported (in
+ * addition to the cached `loadMarkdownDeps()` below) so both failure paths —
+ * and the real caught error each one logs — are directly testable without
+ * needing to actually uninstall either package.
+ */
+export declare function loadMarkdownAndSanitizer(importMarked?: () => Promise<typeof MarkedModule>, importDompurify?: () => Promise<{
+    default: typeof DOMPurifyApi;
+}>): Promise<MarkdownDeps>;
+/**
+ * Lazily loads `marked` + `dompurify` once per page (see
+ * `loadMarkdownAndSanitizer()` for why each is loaded and caught
+ * independently). Cached the same way `chart-loader.ts`/`map-loader.ts`
+ * cache their promise, so every `<lyra-markdown>` instance on a page shares
+ * one load.
+ */
+export declare function loadMarkdownDeps(): Promise<MarkdownDeps>;

package/dist/components/markdown/markdown-loader.js

@@ -0,0 +1,43 @@
+let deps;
+/**
+ * Independently loads the optional peer dependencies `marked` (Markdown
+ * parsing) and `dompurify` (HTML sanitizing), mirroring `chart-loader.ts`'s
+ * `loadChartAndZoom()` shape for two independent optional peers. A partial
+ * install — most usefully `marked` alone, for a consumer who has explicitly
+ * set `sanitize="false"` and doesn't need `dompurify` at all — degrades to
+ * "that one half is missing" rather than failing outright. Exported (in
+ * addition to the cached `loadMarkdownDeps()` below) so both failure paths —
+ * and the real caught error each one logs — are directly testable without
+ * needing to actually uninstall either package.
+ */
+export async function loadMarkdownAndSanitizer(importMarked = () => import('marked'), importDompurify = () => import('dompurify')) {
+    let marked;
+    try {
+        marked = await importMarked();
+    }
+    catch (err) {
+        console.warn('<lyra-markdown> needs the optional peer dependency `marked` to parse Markdown — install it with `pnpm add marked`:', err);
+    }
+    let DOMPurify;
+    try {
+        DOMPurify = (await importDompurify()).default;
+    }
+    catch (err) {
+        console.warn('<lyra-markdown> needs the optional peer dependency `dompurify` to sanitize rendered HTML — install it ' +
+            'with `pnpm add dompurify`. Until then, content only renders when `sanitize="false"` is explicitly set:', err);
+    }
+    return { marked, DOMPurify };
+}
+/**
+ * Lazily loads `marked` + `dompurify` once per page (see
+ * `loadMarkdownAndSanitizer()` for why each is loaded and caught
+ * independently). Cached the same way `chart-loader.ts`/`map-loader.ts`
+ * cache their promise, so every `<lyra-markdown>` instance on a page shares
+ * one load.
+ */
+export function loadMarkdownDeps() {
+    if (!deps) {
+        deps = loadMarkdownAndSanitizer();
+    }
+    return deps;
+}

package/dist/components/markdown/markdown.d.ts

@@ -0,0 +1,81 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+/**
+ * `<lyra-markdown>` — sanitized Markdown-to-HTML rendering (GFM tables,
+ * fenced code blocks, links, blockquotes) built on the optional peer
+ * dependencies `marked` (parsing) and `dompurify` (sanitizing), both
+ * lazy-loaded via `markdown-loader.ts` on first connect.
+ *
+ * Rendering never ships unsanitized or broken markup silently:
+ * - If `marked` fails to load, or throws while parsing malformed input, the
+ *   component falls back to plain text (`white-space: pre-wrap`, no HTML
+ *   parsing at all) and fires `lyra-render-error`.
+ * - If `sanitize` is `true` (the default) and `dompurify` fails to load, the
+ *   component *also* falls back to plain text + `lyra-render-error` — it
+ *   never renders marked's raw HTML output when sanitization was requested
+ *   (or defaulted to) but is unavailable, even though `marked` itself loaded
+ *   fine.
+ * - If `sanitize` is explicitly `false`, marked's raw output renders as-is
+ *   regardless of whether `dompurify` is installed — the consumer opted out
+ *   of sanitization, so `dompurify`'s absence is irrelevant to that path.
+ *
+ * `heading`/`code`/`blockquote`/`table`/`link` tokens are rendered through a
+ * `marked` renderer override that injects `part="..."` attributes directly
+ * into the produced HTML — a single pass, not a second DOM walk after
+ * insertion.
+ *
+ * @customElement lyra-markdown
+ * @event lyra-link-click - Fired (and the click prevented) when a rendered
+ *   link's `href` starts with `internal-link-prefix`. `detail: { href:
+ *   string, internal: true }`. Ordinary external links navigate normally
+ *   (in `link-target`) and never fire this event.
+ * @event lyra-render-error - Fired whenever rendering falls back to plain
+ *   text. `detail: { error: unknown }`.
+ * @csspart content - The wrapper around the rendered (or plain-text
+ *   fallback) output.
+ * @csspart heading - Every rendered `<h1>`–`<h6>`.
+ * @csspart code-block - Every rendered fenced/indented `<pre>`.
+ * @csspart link - Every rendered `<a>`.
+ * @csspart table - Every rendered `<table>`.
+ * @csspart blockquote - Every rendered `<blockquote>`.
+ */
+export declare class LyraMarkdown extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** The Markdown source to render. */
+    content: string;
+    /** Sanitize marked's HTML output with DOMPurify before rendering. See the
+     *  class doc for what happens when this is `true` (the default) but the
+     *  `dompurify` peer isn't installed. */
+    sanitize: boolean;
+    /** Enable GitHub-flavored Markdown (tables, strikethrough, autolinks, task lists). */
+    gfm: boolean;
+    /** `target` applied to every rendered `<a>`; `rel="noopener noreferrer"` is
+     *  always added alongside it regardless of this value. */
+    linkTarget: string;
+    /** When set, a rendered link whose `href` starts with this prefix is
+     *  treated as internal — its click is intercepted and reported via
+     *  `lyra-link-click` instead of navigating. Empty (the default) means
+     *  every link is treated as external. */
+    internalLinkPrefix: string;
+    /** Forward-compatible hint for a dedicated streaming renderer expected to
+     *  build on this component later (coalescing partial tokens as they
+     *  arrive) — setting it has no rendering effect yet. Reflects so a
+     *  consumer can already target `lyra-markdown[streaming]` in CSS ahead of
+     *  that behavior landing. */
+    streaming: boolean;
+    private renderedHtml;
+    private deps?;
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(): void;
+    private renderMarkdown;
+    private applyFallback;
+    private parseMarkdown;
+    private onContentClick;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-markdown': LyraMarkdown;
+    }
+}

package/dist/components/markdown/markdown.js

@@ -0,0 +1,284 @@
+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, state } from 'lit/decorators.js';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { loadMarkdownDeps } from './markdown-loader.js';
+import { styles } from './markdown.styles.js';
+const HTML_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch] ?? ch);
+}
+/**
+ * Mirrors marked's own default `link()` renderer's defensive href guard: a
+ * malformed percent-escape or lone UTF-16 surrogate in the raw href throws
+ * inside `encodeURI`, and marked's default renderer responds by dropping the
+ * anchor (rendering the link text alone) rather than emitting a broken
+ * `href`. `encodeURI`'s *return value* is discarded on purpose, not applied —
+ * calling it a second time on an already-percent-encoded URL (the common
+ * case for a real markdown link) would double-encode every existing `%XX`
+ * escape.
+ */
+function isValidHref(href) {
+    try {
+        encodeURI(href);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `<lyra-markdown>` — sanitized Markdown-to-HTML rendering (GFM tables,
+ * fenced code blocks, links, blockquotes) built on the optional peer
+ * dependencies `marked` (parsing) and `dompurify` (sanitizing), both
+ * lazy-loaded via `markdown-loader.ts` on first connect.
+ *
+ * Rendering never ships unsanitized or broken markup silently:
+ * - If `marked` fails to load, or throws while parsing malformed input, the
+ *   component falls back to plain text (`white-space: pre-wrap`, no HTML
+ *   parsing at all) and fires `lyra-render-error`.
+ * - If `sanitize` is `true` (the default) and `dompurify` fails to load, the
+ *   component *also* falls back to plain text + `lyra-render-error` — it
+ *   never renders marked's raw HTML output when sanitization was requested
+ *   (or defaulted to) but is unavailable, even though `marked` itself loaded
+ *   fine.
+ * - If `sanitize` is explicitly `false`, marked's raw output renders as-is
+ *   regardless of whether `dompurify` is installed — the consumer opted out
+ *   of sanitization, so `dompurify`'s absence is irrelevant to that path.
+ *
+ * `heading`/`code`/`blockquote`/`table`/`link` tokens are rendered through a
+ * `marked` renderer override that injects `part="..."` attributes directly
+ * into the produced HTML — a single pass, not a second DOM walk after
+ * insertion.
+ *
+ * @customElement lyra-markdown
+ * @event lyra-link-click - Fired (and the click prevented) when a rendered
+ *   link's `href` starts with `internal-link-prefix`. `detail: { href:
+ *   string, internal: true }`. Ordinary external links navigate normally
+ *   (in `link-target`) and never fire this event.
+ * @event lyra-render-error - Fired whenever rendering falls back to plain
+ *   text. `detail: { error: unknown }`.
+ * @csspart content - The wrapper around the rendered (or plain-text
+ *   fallback) output.
+ * @csspart heading - Every rendered `<h1>`–`<h6>`.
+ * @csspart code-block - Every rendered fenced/indented `<pre>`.
+ * @csspart link - Every rendered `<a>`.
+ * @csspart table - Every rendered `<table>`.
+ * @csspart blockquote - Every rendered `<blockquote>`.
+ */
+export class LyraMarkdown extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** The Markdown source to render. */
+        this.content = '';
+        /** Sanitize marked's HTML output with DOMPurify before rendering. See the
+         *  class doc for what happens when this is `true` (the default) but the
+         *  `dompurify` peer isn't installed. */
+        this.sanitize = true;
+        /** Enable GitHub-flavored Markdown (tables, strikethrough, autolinks, task lists). */
+        this.gfm = true;
+        /** `target` applied to every rendered `<a>`; `rel="noopener noreferrer"` is
+         *  always added alongside it regardless of this value. */
+        this.linkTarget = '_blank';
+        /** When set, a rendered link whose `href` starts with this prefix is
+         *  treated as internal — its click is intercepted and reported via
+         *  `lyra-link-click` instead of navigating. Empty (the default) means
+         *  every link is treated as external. */
+        this.internalLinkPrefix = '';
+        /** Forward-compatible hint for a dedicated streaming renderer expected to
+         *  build on this component later (coalescing partial tokens as they
+         *  arrive) — setting it has no rendering effect yet. Reflects so a
+         *  consumer can already target `lyra-markdown[streaming]` in CSS ahead of
+         *  that behavior landing. */
+        this.streaming = false;
+        // `null` covers both "the optional peers are still loading" and "a render
+        // attempt just fell back after a failure" — the two states intentionally
+        // look identical (plain text, see render()) since a consumer distinguishes
+        // them via `lyra-render-error`, not a visual difference.
+        this.renderedHtml = null;
+        // A single delegated listener on the content wrapper (not one per <a>) —
+        // the rendered markup is fully replaced on every content change, so a
+        // per-anchor listener would need re-attaching on every render anyway.
+        this.onContentClick = (e) => {
+            const prefix = this.internalLinkPrefix;
+            if (!prefix)
+                return;
+            const anchor = e.composedPath().find((el) => el instanceof HTMLAnchorElement);
+            if (!anchor)
+                return;
+            // Compared against the raw `href` *attribute*, not the `.href` IDL
+            // property — the property is always browser-resolved to an absolute URL
+            // (e.g. "https://example.com/docs") even for a relative/prefixed path,
+            // which would never match a relative `internal-link-prefix`.
+            const href = anchor.getAttribute('href') ?? '';
+            if (!href.startsWith(prefix))
+                return;
+            e.preventDefault();
+            this.emit('lyra-link-click', { href, internal: true });
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    connectedCallback() {
+        super.connectedCallback();
+        void loadMarkdownDeps().then((resolved) => {
+            this.deps = resolved;
+            this.renderMarkdown();
+        });
+    }
+    // Runs before render (not updated()) so mutating the `renderedHtml` state
+    // property below is absorbed into the *same* update cycle instead of
+    // scheduling a second one -- Lit's documented pattern for deriving one
+    // reactive property from a change to others.
+    willUpdate(changed) {
+        if (!this.deps) {
+            // Still loading the optional peers — the connectedCallback promise
+            // above calls renderMarkdown() itself once they resolve, using
+            // whatever property values are current at that time.
+            return;
+        }
+        if (changed.has('content') || changed.has('sanitize') || changed.has('gfm') || changed.has('linkTarget')) {
+            this.renderMarkdown();
+        }
+    }
+    updated() {
+        if (this.deps) {
+            this.removeAttribute('aria-busy');
+        }
+        else {
+            this.setAttribute('aria-busy', 'true');
+        }
+    }
+    renderMarkdown() {
+        const deps = this.deps;
+        if (!deps)
+            return;
+        if (!deps.marked) {
+            // markdown-loader.ts already logged the specific import failure.
+            this.applyFallback(new Error('<lyra-markdown> could not render: the "marked" peer dependency failed to load.'));
+            return;
+        }
+        let rawHtml;
+        try {
+            rawHtml = this.parseMarkdown(deps.marked);
+        }
+        catch (error) {
+            this.applyFallback(error);
+            return;
+        }
+        if (!this.sanitize) {
+            // Consumer explicitly opted out of sanitization — dompurify's
+            // presence or absence is irrelevant to this path.
+            this.renderedHtml = rawHtml;
+            return;
+        }
+        if (!deps.DOMPurify) {
+            const error = new Error('<lyra-markdown> could not render: sanitize is enabled (the default) but the "dompurify" peer ' +
+                'dependency failed to load — refusing to render unsanitized HTML. Install it with `pnpm add ' +
+                'dompurify`, or set sanitize="false" to explicitly opt out of sanitization.');
+            console.warn(error.message);
+            this.applyFallback(error);
+            return;
+        }
+        // `target` is not in DOMPurify's default attribute allowlist (unlike
+        // `part`/`rel`/`class`, which already are) — without ADD_ATTR here,
+        // every rendered link's target="..." would be silently stripped even
+        // though the anchor itself survives sanitization.
+        this.renderedHtml = deps.DOMPurify.sanitize(rawHtml, { ADD_ATTR: ['target'] });
+    }
+    applyFallback(error) {
+        this.renderedHtml = null;
+        this.emit('lyra-render-error', { error });
+    }
+    parseMarkdown(marked) {
+        const linkTarget = this.linkTarget || '_blank';
+        const instance = new marked.Marked();
+        // A fresh renderer per parse (rather than a shared/cached one) so it
+        // always closes over the *current* `linkTarget` — this property can
+        // change between renders, and marked's `.use()` otherwise persists
+        // whatever renderer it was given for the lifetime of the instance.
+        instance.use({
+            renderer: {
+                heading(token) {
+                    return `<h${token.depth} part="heading">${this.parser.parseInline(token.tokens)}</h${token.depth}>\n`;
+                },
+                code(token) {
+                    const lang = (token.lang ?? '').trim().split(/\s+/)[0] ?? '';
+                    const body = `${token.text.replace(/\n$/, '')}\n`;
+                    const text = token.escaped ? body : escapeHtml(body);
+                    const cls = lang ? ` class="language-${escapeHtml(lang)}"` : '';
+                    return `<pre part="code-block"><code${cls}>${text}</code></pre>\n`;
+                },
+                blockquote(token) {
+                    return `<blockquote part="blockquote">\n${this.parser.parse(token.tokens)}</blockquote>\n`;
+                },
+                table(token) {
+                    let headerRow = '';
+                    for (const cell of token.header)
+                        headerRow += this.tablecell(cell);
+                    let bodyRows = '';
+                    for (const row of token.rows) {
+                        let rowHtml = '';
+                        for (const cell of row)
+                            rowHtml += this.tablecell(cell);
+                        bodyRows += this.tablerow({ text: rowHtml });
+                    }
+                    const thead = `<thead>\n${this.tablerow({ text: headerRow })}</thead>\n`;
+                    const tbody = bodyRows ? `<tbody>${bodyRows}</tbody>\n` : '';
+                    return `<table part="table">\n${thead}${tbody}</table>\n`;
+                },
+                link(token) {
+                    const text = this.parser.parseInline(token.tokens);
+                    if (!isValidHref(token.href))
+                        return text;
+                    const titleAttr = token.title ? ` title="${escapeHtml(token.title)}"` : '';
+                    return (`<a part="link" href="${escapeHtml(token.href)}"${titleAttr} ` +
+                        `target="${escapeHtml(linkTarget)}" rel="noopener noreferrer">${text}</a>`);
+                },
+            },
+        });
+        return instance.parse(this.content, { gfm: this.gfm, async: false });
+    }
+    render() {
+        const isFallback = this.renderedHtml === null;
+        return html `
+      <div part="content" ?data-fallback=${isFallback} @click=${this.onContentClick}>
+        ${isFallback ? this.content : unsafeHTML(this.renderedHtml)}
+      </div>
+    `;
+    }
+}
+__decorate([
+    property()
+], LyraMarkdown.prototype, "content", void 0);
+__decorate([
+    property({ type: Boolean })
+], LyraMarkdown.prototype, "sanitize", void 0);
+__decorate([
+    property({ type: Boolean })
+], LyraMarkdown.prototype, "gfm", void 0);
+__decorate([
+    property({ attribute: 'link-target' })
+], LyraMarkdown.prototype, "linkTarget", void 0);
+__decorate([
+    property({ attribute: 'internal-link-prefix' })
+], LyraMarkdown.prototype, "internalLinkPrefix", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraMarkdown.prototype, "streaming", void 0);
+__decorate([
+    state()
+], LyraMarkdown.prototype, "renderedHtml", void 0);
+defineElement('markdown', LyraMarkdown);

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

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

package/dist/components/markdown/markdown.styles.js

@@ -0,0 +1,82 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+    /* Contained here (rather than left as a bare font-family literal) so a
+       host page can retheme it -- same rationale as lyra-json-viewer's
+       identical --lyra-json-viewer-font, no shared --wa-*/--lyra-*
+       monospace token exists to resolve through. */
+    --lyra-markdown-font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    line-height: 1.6;
+  }
+  [part='content'] {
+    overflow-wrap: break-word;
+  }
+  /* Shared by both the "still loading" and "fell back after a failure"
+     states -- see the renderedHtml field doc in markdown.ts. */
+  [part='content'][data-fallback] {
+    white-space: pre-wrap;
+    font-family: inherit;
+  }
+  [part='content'] > :first-child {
+    margin-block-start: 0;
+  }
+  [part='content'] > :last-child {
+    margin-block-end: 0;
+  }
+  [part='heading'] {
+    line-height: 1.25;
+    margin-block: var(--lyra-space-l) var(--lyra-space-s);
+  }
+  [part='content'] p,
+  [part='content'] ul,
+  [part='content'] ol {
+    margin-block: 0 var(--lyra-space-s);
+  }
+  [part='content'] code {
+    font-family: var(--lyra-markdown-font-mono);
+    font-size: 0.875em;
+    background: var(--lyra-color-brand-quiet);
+    border-radius: 0.1875rem;
+    padding: 0.125rem 0.3125rem;
+  }
+  [part='code-block'] {
+    margin-block: 0 var(--lyra-space-s);
+    padding: var(--lyra-space-s) var(--lyra-space-m);
+    border-radius: var(--lyra-radius);
+    background: var(--lyra-color-brand-quiet);
+    overflow-x: auto;
+  }
+  [part='code-block'] code {
+    padding: 0;
+    background: none;
+    font-size: 0.8125rem;
+    line-height: 1.5;
+  }
+  [part='link'] {
+    color: var(--lyra-color-brand);
+    text-underline-offset: 0.125rem;
+  }
+  [part='blockquote'] {
+    margin-block: 0 var(--lyra-space-s);
+    margin-inline: 0;
+    padding-inline-start: var(--lyra-space-m);
+    border-inline-start: 3px solid var(--lyra-color-border);
+    color: var(--lyra-color-text-quiet);
+  }
+  [part='table'] {
+    border-collapse: collapse;
+    margin-block: 0 var(--lyra-space-s);
+    inline-size: 100%;
+  }
+  [part='table'] th,
+  [part='table'] td {
+    border: 1px solid var(--lyra-color-border);
+    padding: var(--lyra-space-xs) var(--lyra-space-s);
+    text-align: start;
+  }
+  [part='table'] th {
+    background: var(--lyra-color-brand-quiet);
+    font-weight: 600;
+  }
+`;

package/dist/components/media-card/media-card.d.ts

@@ -0,0 +1,122 @@
+import { type TemplateResult } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+export type MediaCardKind = 'image' | 'video' | 'file';
+export interface MediaCardOpenDetail {
+    src: string;
+    filename: string;
+}
+/** Validates `url` is safe to assign as an `<img>`/`<video>` `src`. Returns
+ *  the trimmed url when safe, `null` otherwise -- see the "safe-URL
+ *  checking" comment above for the `data:` judgement call and why `URL` is
+ *  used instead of a regex. */
+export declare function safeMediaSrc(url: string): string | null;
+/** Validates `url` is safe to assign as an `<a href>` -- stricter than
+ *  `safeMediaSrc()`, see the "safe-URL checking" comment above. Returns the
+ *  trimmed url when safe, `null` otherwise. */
+export declare function safeLinkHref(url: string): string | null;
+/**
+ * `<lyra-media-card>` — a lightweight inline preview for one already-sent,
+ * already-available attachment inside a rendered chat message body (e.g.
+ * plugged into `<lyra-chat-message>`'s `attachments` slot, or embedded
+ * directly by a markdown/message renderer). Distinct from two other,
+ * similarly-named components in this family: `<lyra-document-preview>` is a
+ * fuller viewer with header chrome and an async server-side-conversion
+ * state machine (`status="converting"`), and `<lyra-attachment-chip>` is a
+ * pre-send queued-file chip with upload progress. This component has
+ * neither concern — it only ever shows a `src` that's already final.
+ *
+ * **Format dispatch.** `kind` selects `'image'` (a plain `<img>`), `'video'`
+ * (a plain `<video controls>`), or `'file'` (an icon + filename chip with a
+ * download/open affordance). Leave `kind` unset to auto-detect from
+ * `mime-type` (`image/*` / `video/*` / anything else -> `'file'`);
+ * explicitly setting `kind` always wins over detection.
+ *
+ * **Safe-URL checking.** `src` is validated before it's ever assigned to an
+ * `<img>`/`<video>` `src` or an `<a href>` — only `http:`/`https:`/`blob:`
+ * (plus `data:` for a *media* `src` only) or a scheme-relative/relative URL
+ * with no scheme at all pass; anything else (`javascript:`, `vbscript:`,
+ * and similarly suspicious schemes) is rejected. See `safeMediaSrc()` /
+ * `safeLinkHref()` and their shared "safe-URL checking" comment for exactly
+ * why `data:` gets two different answers depending on which DOM sink it's
+ * headed for, and why the check is built on `new URL()` rather than a
+ * hand-rolled scheme regex. An `image`/`video` `kind` whose `src` fails the
+ * media-src check falls back to the generic file-chip rendering (which then
+ * separately re-validates `src` against the stricter href allowlist for its
+ * own download affordance) — this is the "plain preview unavailable state"
+ * a dangerous URL degrades to, rather than ever reaching a real media/anchor
+ * sink.
+ *
+ * **The `video` case renders its open affordance separately from `base`.**
+ * `image`/`file` wrap their *entire* card in one native `<button>`/`<a>` —
+ * safe because an `<img>` and a plain icon+text chip have no interactive
+ * content of their own to conflict with. A `<video controls>` element is
+ * itself interactive content (its own play/seek/volume controls), and HTML
+ * forbids nesting interactive content inside a `<button>`/`<a>` — doing so
+ * anyway would also make every click on the video's own controls bubble up
+ * and spuriously fire `lyra-open`. So for `kind="video"`, `base` is a plain,
+ * non-interactive wrapper around `[part="media"]`, and a small separate
+ * `[part="open-button"]` (not one of this component's originally-scoped
+ * parts, added as the "explicit view/open affordance" the class is free to
+ * provide) is the thing that actually fires `lyra-open`.
+ *
+ * **Navigation.** This component never navigates on its own for `image`/
+ * `video` — activating the card only fires `lyra-open`; a host decides what
+ * "open" means (a lightbox, a new tab, whatever). The `file`-chip case is
+ * the one exception: when `src` passes the (stricter) href safety check, the
+ * chip is a real `<a href download>` so a bare drop-in still does something
+ * useful — but `lyra-open` fires first and is `cancelable`; a host that
+ * calls `preventDefault()` on it suppresses that default download/open so it
+ * can substitute its own handling instead.
+ *
+ * @customElement lyra-media-card
+ * @event lyra-open - The card (or, for `kind="video"`, its `open-button`)
+ * was activated. `detail: { src, filename }`. Cancelable — see the class
+ * doc's "Navigation" section for what calling `preventDefault()` on it does
+ * in the `file`-chip case.
+ * @csspart base - The root interactive/container element. A `<button>` for
+ * `kind="image"`, a plain wrapper `<div>` for `kind="video"`, and either an
+ * `<a>` (when `src` passes the href safety check) or a plain `<span>`
+ * (otherwise) for the `file`-chip fallback.
+ * @csspart media - The `<img>` or `<video>` element.
+ * @csspart file-icon - The generic file glyph, shown only in the file-chip fallback.
+ * @csspart filename - The filename text, shown only in the file-chip fallback.
+ * @csspart open-button - The explicit "open" affordance rendered next to
+ * `[part="media"]` for `kind="video"` only — see the class doc.
+ */
+export declare class LyraMediaCard extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** The media URL. Always re-validated against a safe-scheme allowlist
+     *  before use — see the class doc. */
+    src: string;
+    /** Explicit format dispatch. Leave unset to auto-detect from `mime-type`. */
+    kind?: MediaCardKind;
+    /** Drives auto-detection when `kind` is unset. */
+    mimeType: string;
+    /** Shown in the file-chip fallback, used as the download link's suggested
+     *  filename, and folded into the accessible name of the whole card. */
+    filename: string;
+    /** Alt text for the image case (and reused as a video label fallback).
+     *  Falls back to `filename`, then a generic per-kind description. */
+    alt: string;
+    /** Effective kind used for rendering — `kind` if explicitly set,
+     *  otherwise detected from `mime-type`. */
+    private get resolvedKind();
+    private get displayFilename();
+    /** Accessible name for the card's own actionable element (`base` or, for
+     *  video, `open-button`) — always phrased as the action it performs. */
+    private get accessibleLabel();
+    private get imgAlt();
+    private get videoLabel();
+    private emitOpen;
+    private onActivate;
+    private onLinkClick;
+    private renderImage;
+    private renderVideo;
+    private renderFileFallback;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-media-card': LyraMediaCard;
+    }
+}