@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/markdown/markdown.js

@@ -0,0 +1,389 @@
+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, getMarkdownDepsIfLoaded } 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 `cleanUrl()`: 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` —
+ * returning `null` here lets the caller do the same. The
+ * `.replace(/%25/g, '%')` compensates for `encodeURI` re-escaping the `%` of
+ * an href that was already percent-encoded (the common case for a real
+ * markdown link) — without it, every existing `%XX` escape would become
+ * `%25XX`, double-encoding it.
+ */
+function cleanHref(href) {
+    try {
+        return encodeURI(href).replace(/%25/g, '%');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `<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.
+ *
+ * That same plain-text fallback rendering (`data-fallback` on the `content`
+ * part) is also, unconditionally and by default, a brief *transient* state on
+ * every connect, not just a failure path: `connectedCallback()`'s dynamic
+ * `import()` of `marked`/`dompurify` (see `markdown-loader.ts`) is
+ * asynchronous, so the very first paint of any `<lyra-markdown>` on a page
+ * shows plain text for at least one microtask — even when both peers are
+ * already installed and load without error — until that import resolves and
+ * a second render replaces it with the real Markdown output. Set
+ * `eager-load` to skip that window once the shared dependency cache is
+ * already warm; see that property's doc for exactly what "warm" requires.
+ *
+ * `heading`/`code`/`blockquote`/`table`/`link`/`image` 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>` (shifted by
+ *   `heading-offset`).
+ * @csspart code-block - Every rendered fenced/indented `<pre>`.
+ * @csspart link - Every rendered `<a>`.
+ * @csspart table - Every rendered `<table>`.
+ * @csspart blockquote - Every rendered `<blockquote>`.
+ * @csspart img - Every rendered `<img>`.
+ */
+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>`, with `rel="noopener
+         *  noreferrer"` always added alongside it whenever a `target` is emitted.
+         *  `'_blank'` (the default) preserves today's exact output. Set to `null`
+         *  (or the empty string, e.g. via the `link-target=""` attribute) to omit
+         *  `target`/`rel` entirely, so rendered links open in the same tab. */
+        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 = '';
+        /** Added to every rendered heading's source `token.depth` before emitting
+         *  `<h${depth}>` — e.g. `heading-offset="2"` renders a source `#` as
+         *  `<h3>` and a source `##` as `<h4>`. The result is clamped to `[1, 6]`
+         *  (a source `######` with a positive offset stays at `<h6>` rather than
+         *  overflowing past the HTML heading levels; the floor at `1` is
+         *  defensive, since this property is meant to be additive-only). `0`
+         *  (the default) preserves today's exact `<h${token.depth}>` output. */
+        this.headingOffset = 0;
+        /** When `true`, `connectedCallback()` skips awaiting `loadMarkdownDeps()`'s
+         *  dynamic `import()` if the shared `marked`/`dompurify` module cache (see
+         *  `markdown-loader.ts`'s `getMarkdownDepsIfLoaded()`) has *already*
+         *  resolved — e.g. because an earlier `<lyra-markdown>` instance on the
+         *  page already finished loading, or the consumer primed the cache
+         *  directly by calling `loadMarkdownDeps()` themselves at startup — and
+         *  renders synchronously instead. When the cache isn't warm yet (most
+         *  notably: the very first `<lyra-markdown>` ever connected on a page,
+         *  since nothing has called `loadMarkdownDeps()` before it), this still
+         *  falls back to the normal async path — a dynamic `import()` can't be
+         *  made synchronous, so this is a fast path for the common "already warm"
+         *  case, not a hard guarantee. `false` (the default) is byte-identical to
+         *  today: always the async `import()`, fallback-text window included. */
+        this.eagerLoad = false;
+        /** 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();
+        if (this.eagerLoad) {
+            // Only takes this synchronous path when the shared module cache has
+            // *already* settled (see getMarkdownDepsIfLoaded()'s doc) -- otherwise
+            // falls through to the same async path as the default below, since a
+            // dynamic import() can't be made synchronous from scratch.
+            const alreadyLoaded = getMarkdownDepsIfLoaded();
+            if (alreadyLoaded) {
+                this.deps = alreadyLoaded;
+                this.renderMarkdown();
+                return;
+            }
+        }
+        void loadMarkdownDeps().then((resolved) => {
+            // The (module-cached, page-lifetime) loadMarkdownDeps() promise can
+            // resolve after this instance was removed from the DOM -- e.g. an
+            // <lyra-markdown> inside a conditionally-rendered chat message or a
+            // virtualized list. Without this guard, a detached instance would
+            // still have its `deps` set and renderMarkdown() called, mutating the
+            // @state() renderedHtml property and scheduling a Lit update no one
+            // will ever see. Mirrors chart.ts's own connectedCallback() guard for
+            // the identical race.
+            if (!this.isConnected)
+                return;
+            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') ||
+            changed.has('headingOffset')) {
+            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) {
+        // Falsy (`null` or `''`) means the consumer explicitly opted out of
+        // target="..."/rel="..." on rendered links -- see the linkTarget doc.
+        // The default '_blank' is already truthy, so this preserves today's
+        // exact output when the property is left unset.
+        const linkTarget = this.linkTarget;
+        const headingOffset = this.headingOffset;
+        const instance = new marked.Marked();
+        // A fresh renderer per parse (rather than a shared/cached one) so it
+        // always closes over the *current* `linkTarget`/`headingOffset` — these
+        // properties 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) {
+                    // Clamped to [1, 6]: a positive offset can never push a heading
+                    // past <h6> (there is no <h7>), and the floor at 1 is defensive
+                    // since headingOffset is meant to be additive-only (0 is the only
+                    // documented non-positive value).
+                    const depth = Math.min(6, Math.max(1, token.depth + headingOffset));
+                    return `<h${depth} part="heading">${this.parser.parseInline(token.tokens)}</h${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) {
+                    // Built directly here (rather than delegating to the inherited
+                    // tablecell()) so a scope="col" can be added -- marked's own
+                    // default tablecell() never emits it, and without it a screen
+                    // reader can't reliably associate a data cell with its column
+                    // header beyond the simplest table.
+                    let headerRow = '';
+                    for (const cell of token.header) {
+                        const text = this.parser.parseInline(cell.tokens);
+                        const alignAttr = cell.align ? ` align="${cell.align}"` : '';
+                        headerRow += `<th scope="col"${alignAttr}>${text}</th>`;
+                    }
+                    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);
+                    const href = cleanHref(token.href);
+                    if (href === null)
+                        return text;
+                    const titleAttr = token.title ? ` title="${escapeHtml(token.title)}"` : '';
+                    const targetAttr = linkTarget
+                        ? ` target="${escapeHtml(linkTarget)}" rel="noopener noreferrer"`
+                        : '';
+                    return `<a part="link" href="${escapeHtml(href)}"${titleAttr}${targetAttr}>${text}</a>`;
+                },
+                image(token) {
+                    // Mirrors marked's own default image() renderer (alt text
+                    // re-rendered through the plain textRenderer so nested emphasis/
+                    // strong/etc. inside the alt collapses to plain text, href run
+                    // through the same cleanHref() the link() override above uses)
+                    // with a part="img" added.
+                    const altText = this.parser.parseInline(token.tokens, this.parser.textRenderer);
+                    const href = cleanHref(token.href);
+                    if (href === null)
+                        return escapeHtml(altText);
+                    const titleAttr = token.title ? ` title="${escapeHtml(token.title)}"` : '';
+                    return `<img part="img" src="${escapeHtml(href)}" alt="${escapeHtml(altText)}"${titleAttr}>`;
+                },
+            },
+        });
+        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: Number, attribute: 'heading-offset' })
+], LyraMarkdown.prototype, "headingOffset", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'eager-load' })
+], LyraMarkdown.prototype, "eagerLoad", 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,88 @@
+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: calc(var(--lyra-radius) * 0.5);
+    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;
+  }
+  /* Keeps an oversized source image from overflowing the content wrapper --
+     matches the overflow-wrap: break-word guard on [part='content'] above,
+     which only covers text, not replaced elements like <img>. */
+  [part='img'] {
+    max-width: 100%;
+  }
+  [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,130 @@
+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` for an `<img>`/`<video>` source. Kept as a public wrapper
+ * so existing imports and generated API metadata remain stable. */
+export declare function safeMediaSrc(url: string): string | null;
+/** Validates `url` for the library's download/open link sinks. Kept as a
+ * public wrapper so existing imports and generated API metadata remain stable. */
+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. `safeMediaSrc()` and
+ * `safeLinkHref()` share a platform-URL-based validator; their sink-specific
+ * allowlists explain why `data:` gets two different answers depending on
+ * where it is used. An `image`/`video` `kind` whose `src` fails the
+ * media-src check falls back to the generic file-chip rendering — this is
+ * the "plain preview unavailable state" a dangerous URL degrades to, rather
+ * than ever reaching a real media/anchor sink. That fallback also re-checks
+ * `src` against the stricter href allowlist for its own download affordance,
+ * but since the href allowlist is a strict subset of the media-src allowlist,
+ * that re-check can only ever change the outcome for a direct/auto-detected
+ * `kind="file"` `src` — an `image`/`video` `src` that already failed the
+ * wider media-src check necessarily fails the narrower href check too, so
+ * the fallback for those two kinds is always the plain, unclickable `span`.
+ *
+ * **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;
+    /** A CSS length (e.g. `"16rem"`); once set, overrides the
+     *  `--lyra-media-card-max-height` custom property for this instance only —
+     *  same contract as `<lyra-document-preview>`'s identically-named prop. */
+    maxHeight: 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();
+    /** Per-instance override for `--lyra-media-card-max-height`, applied
+     *  inline on `[part="base"]` -- the only mechanism that reliably wins
+     *  over the `:host{}`-declared default from outside the shadow root. */
+    private get baseStyle();
+    private emitOpen;
+    private onActivate;
+    private onLinkClick;
+    private renderImage;
+    private renderVideo;
+    private renderFileFallback;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-media-card': LyraMediaCard;
+    }
+}