@aceshooting/lyra-ui 1.1.0 → 2.0.0

package/dist/components/document-preview/document-preview.js

@@ -0,0 +1,372 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing, svg } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { srOnly } from '../../internal/a11y.js';
+import { styles } from './document-preview.styles.js';
+const IDLE_TEXT_FETCH = { kind: 'idle' };
+function classifyFormat(mimeType) {
+    const mt = mimeType.trim().toLowerCase();
+    if (mt.startsWith('text/') || mt === 'application/json')
+        return 'text';
+    if (mt.startsWith('image/'))
+        return 'image';
+    return 'generic';
+}
+// Mirrors the shared icon set's viewBox/stroke conventions
+// (internal/icons.ts's chevronIcon()/closeIcon()/etc.) without adding
+// document/download glyphs to that module -- it's off limits here -- so
+// these one-off icons still read as part of the same visual language as the
+// rest of the library's inline icons.
+const ICON_VIEW_BOX = '0 0 24 24';
+const ICON_STROKE_WIDTH = '1.75';
+/** A generic "document" glyph for the can't-preview-this fallback. Same
+ *  shape as `<lyra-attachment-chip>`'s local `fileGlyph()` -- duplicated
+ *  rather than imported (these are two independently consumable components)
+ *  but kept visually identical so an unpreviewable-file affordance reads the
+ *  same wherever it shows up in the library. */
+function fileGlyph() {
+    return svg `
+    <svg
+      width="1em"
+      height="1em"
+      viewBox=${ICON_VIEW_BOX}
+      fill="none"
+      stroke="currentColor"
+      stroke-width=${ICON_STROKE_WIDTH}
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    ><path d="M6 2h8l6 6v12a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2Z"></path><polyline points="14 2 14 8 20 8"></polyline></svg>
+  `;
+}
+/** A downward arrow into a tray -- the conventional "download" glyph. */
+function downloadIcon() {
+    return icon(svg `
+    <path d="M12 3v12"></path>
+    <polyline points="7 11 12 16 17 11"></polyline>
+    <path d="M4 18v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2"></path>
+  `);
+}
+function icon(paths) {
+    return svg `
+    <svg
+      width="1em"
+      height="1em"
+      viewBox=${ICON_VIEW_BOX}
+      fill="none"
+      stroke="currentColor"
+      stroke-width=${ICON_STROKE_WIDTH}
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    >${paths}</svg>
+  `;
+}
+/**
+ * `<lyra-document-preview>` — a format-dispatching viewer for one document/
+ * attachment, plus the visual state machine for an async server-side
+ * conversion a host app runs in front of it.
+ *
+ * Format dispatch is intentionally minimal (see this family's scope
+ * guidance): only `text/*`/`application/json` (plain, scrollable `<pre>` —
+ * no syntax highlighting; compose `<lyra-code-block>` yourself via the
+ * `unsupported` slot for that) and `image/*` (a contained `<img>`) render
+ * inline. Everything else — PDF, office documents, video, audio, or any
+ * unrecognized MIME type — falls back to a generic "can't preview this"
+ * state: a file glyph, a short message, and (when `src` is set) a native
+ * `<a download>` link. This is a deliberate ceiling, not a gap: this
+ * component ships a dispatch *shell*, not a format registry. The
+ * `unsupported` slot is the escape hatch for every format left out of the
+ * built-in three — plug in a PDF.js viewer, an office-doc renderer, a
+ * `<lyra-code-block>`, or anything else keyed off `mime-type` yourself.
+ *
+ * `status="converting"` is a second, independent axis from format dispatch.
+ * This component does not know your backend's conversion API shape and
+ * therefore owns none of the actual polling/fetch — a host that's converting
+ * a non-natively-previewable format server-side (e.g. .docx → .pdf) polls
+ * its own backend and updates `status`/`progress`/`src` here as that
+ * proceeds. This component only *visualizes* that state: an indeterminate
+ * spinner, or a determinate one once `progress` is supplied. Once the host
+ * flips `status` to `"ready"` (typically alongside a new `src`/`mime-type`
+ * pointing at the converted artifact), normal format dispatch resumes.
+ *
+ * The one piece of async work this component *does* own is fetching a
+ * `text/*`/`application/json` `src` itself (there's no other way to get a
+ * `<pre>`'s text content from a URL) — gated behind the same generation-
+ * counter guard `<lyra-tool-result-view>`'s `resolve()` uses, so a `src`
+ * reassigned mid-fetch can't have a stale response clobber a newer one. A
+ * failure here (network error, non-2xx response) renders inline via
+ * `[part="error"]` and fires `lyra-render-error`, independently of the
+ * host-owned `status` prop — mirrors `<lyra-markdown>`'s identical stance
+ * that a *rendering* failure and a host's own state machine are different
+ * concerns.
+ *
+ * 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
+ * `<lyra-live-region>`/`Announcer` — like `<lyra-typing-indicator>`'s
+ * identical judgement call (see that component's class doc), this only ever
+ * has one thing to announce (entering the state), not a rapidly-repeating
+ * stream of updates, so the coalescing machinery a high-frequency component
+ * needs would be pure overhead here. Once real `progress` is available, the
+ * region becomes a standard `role="progressbar"` instead, which is
+ * self-describing via `aria-valuenow` with no extra live-region wiring
+ * needed. `status="error"` renders `[part="error"]` as `role="alert"` — an
+ * assertive, one-shot failure notice, the same native-role shortcut
+ * `<lyra-live-region>`'s own `mode="assertive"` maps to, without requiring
+ * the announcer machinery here either.
+ *
+ * @customElement lyra-document-preview
+ * @slot unsupported - Escape hatch: when populated, its content renders
+ *   *instead of* the generic download fallback for any `mime-type` this
+ *   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-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
+ *   doc).
+ * @csspart base - The root container.
+ * @csspart header - The row above the body, holding `filename`. Hidden entirely when `filename` is unset.
+ * @csspart filename - The filename text.
+ * @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.
+ */
+export class LyraDocumentPreview extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** 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. */
+        this.src = '';
+        /** Drives format dispatch — see the class doc. */
+        this.mimeType = '';
+        /** Shown in the header and used as the download link's suggested filename. */
+        this.filename = '';
+        /** Host-owned lifecycle state. `"converting"` shows the spinner regardless
+         *  of `mime-type`/`src`; `"error"` shows `errorMessage` regardless of
+         *  either. `"idle"`/`"ready"` both resume normal format dispatch — this
+         *  component doesn't require a host that has no conversion step to ever
+         *  set `"ready"` explicitly. */
+        this.status = 'idle';
+        /** Shown (via `[part="error"]`) while `status="error"`. */
+        this.errorMessage = '';
+        /** A CSS length (e.g. `"24rem"`); once set, `[part="body"]` scrolls
+         *  internally past this height instead of growing the page — same
+         *  contract as `<lyra-json-viewer>`'s identically-named prop. */
+        this.maxHeight = '';
+        this.hasUnsupportedSlot = false;
+        this.textFetch = IDLE_TEXT_FETCH;
+        // Bumped on every fetchText() call so a stale in-flight fetch (superseded
+        // by a newer src/mime-type/status before it settles) can detect it's no
+        // longer current and skip writing its result over a more recent one --
+        // same guard <lyra-tool-result-view>'s resolve() uses.
+        this.fetchGeneration = 0;
+        this.onUnsupportedSlotChange = (e) => {
+            this.hasUnsupportedSlot = e.target.assignedElements({ flatten: true }).length > 0;
+        };
+        this.onDownloadClick = () => {
+            this.emit('lyra-download', { src: this.src, filename: this.filename });
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    willUpdate(changed) {
+        if (!this.hasUpdated) {
+            this.hasUnsupportedSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'unsupported');
+        }
+        const shouldFetchText = classifyFormat(this.mimeType) === 'text' &&
+            this.src !== '' &&
+            this.status !== 'converting' &&
+            this.status !== 'error';
+        if (shouldFetchText) {
+            // Refetch when the target itself changed, or when this just became
+            // fetchable (e.g. a "converting" -> "ready" transition) and nothing
+            // has been fetched yet -- but not on every unrelated property change.
+            if (!this.hasUpdated ||
+                changed.has('src') ||
+                changed.has('mimeType') ||
+                (changed.has('status') && this.textFetch.kind === 'idle')) {
+                void this.fetchText(this.src);
+            }
+        }
+        else if (this.textFetch.kind !== 'idle') {
+            // No longer applicable (format changed away from text, src cleared,
+            // or status moved to converting/error) -- invalidate any in-flight
+            // fetch and drop the stale result so a later re-entry starts clean.
+            this.fetchGeneration++;
+            this.textFetch = IDLE_TEXT_FETCH;
+        }
+    }
+    async fetchText(url) {
+        const generation = ++this.fetchGeneration;
+        this.textFetch = { kind: 'loading' };
+        try {
+            const response = await fetch(url);
+            if (!response.ok)
+                throw new Error(`${response.status} ${response.statusText}`);
+            const text = await response.text();
+            if (generation !== this.fetchGeneration)
+                return;
+            this.textFetch = { kind: 'loaded', text };
+        }
+        catch (error) {
+            if (generation !== this.fetchGeneration)
+                return;
+            const message = error instanceof Error ? error.message : 'Failed to load document.';
+            this.textFetch = { kind: 'error', message };
+            this.emit('lyra-render-error', { error });
+        }
+    }
+    /** Renders `[part="spinner"]` -- indeterminate (`role="status"` + a
+     *  visually-hidden label, per the class doc's accessibility note) when
+     *  `progressValue` is absent, or a `role="progressbar"` once it's a finite
+     *  0-100 number. Shared by the host-driven `"converting"` state and this
+     *  component's own in-flight text fetch (which never has a numeric
+     *  progress of its own to report). */
+    renderSpinner(label, progressValue) {
+        const hasProgress = progressValue != null && Number.isFinite(progressValue);
+        if (hasProgress) {
+            const clamped = Math.min(100, Math.max(0, progressValue));
+            const rounded = Math.round(clamped);
+            return html `
+        <div
+          part="spinner"
+          role="progressbar"
+          aria-valuenow=${rounded}
+          aria-valuemin="0"
+          aria-valuemax="100"
+          aria-label=${label}
+        >
+          <span class="ring determinate" style=${`--lyra-document-preview-progress:${clamped}`}></span>
+          <span class="spinner-text">${rounded}%</span>
+        </div>
+      `;
+        }
+        return html `
+      <div part="spinner" role="status">
+        <span class="ring" aria-hidden="true"></span>
+        <span class="sr-only">${label}</span>
+      </div>
+    `;
+    }
+    renderError(message) {
+        return html `<div part="error" role="alert">${message || 'Something went wrong.'}</div>`;
+    }
+    renderTextPreview() {
+        if (this.src === '')
+            return html `<pre class="text"></pre>`;
+        switch (this.textFetch.kind) {
+            case 'loaded':
+                return html `<pre class="text">${this.textFetch.text}</pre>`;
+            case 'error':
+                return this.renderError(this.textFetch.message);
+            case 'loading':
+            case 'idle':
+            default:
+                return this.renderSpinner('Loading document…');
+        }
+    }
+    renderImagePreview() {
+        if (this.src === '')
+            return html `<p class="empty-note">No image to display.</p>`;
+        return html `<img src=${this.src} alt=${this.filename || 'Document preview'} />`;
+    }
+    renderDownloadFallback() {
+        const label = this.filename || 'this file';
+        return html `
+      <div class="fallback">
+        <span class="fallback-icon" aria-hidden="true">${fileGlyph()}</span>
+        <p class="fallback-text">Preview not available for ${label}.</p>
+        ${this.src !== ''
+            ? html `
+              <a
+                part="download-link"
+                href=${this.src}
+                download=${this.filename || ''}
+                @click=${this.onDownloadClick}
+              >
+                ${downloadIcon()}<span>Download</span>
+              </a>
+            `
+            : nothing}
+      </div>
+    `;
+    }
+    /** The `<slot>` element renders unconditionally (not just while
+     *  `hasUnsupportedSlot`) so a slot-assignment change is always observable
+     *  via `slotchange` -- same reasoning as `<lyra-chat-message>`'s
+     *  always-rendered optional slots. */
+    renderGenericFallback() {
+        return html `
+      <slot name="unsupported" @slotchange=${this.onUnsupportedSlotChange}></slot>
+      ${this.hasUnsupportedSlot ? nothing : this.renderDownloadFallback()}
+    `;
+    }
+    renderBody() {
+        if (this.status === 'converting')
+            return this.renderSpinner('Converting document…', this.progress);
+        if (this.status === 'error')
+            return this.renderError(this.errorMessage);
+        switch (classifyFormat(this.mimeType)) {
+            case 'text':
+                return this.renderTextPreview();
+            case 'image':
+                return this.renderImagePreview();
+            default:
+                return this.renderGenericFallback();
+        }
+    }
+    render() {
+        return html `
+      <div part="base" style=${this.maxHeight ? `--lyra-document-preview-max-height:${this.maxHeight}` : nothing}>
+        <div part="header" ?hidden=${!this.filename}>
+          <span part="filename" title=${this.filename}>${this.filename}</span>
+        </div>
+        <div part="body">${this.renderBody()}</div>
+      </div>
+    `;
+    }
+}
+__decorate([
+    property()
+], LyraDocumentPreview.prototype, "src", void 0);
+__decorate([
+    property({ attribute: 'mime-type' })
+], LyraDocumentPreview.prototype, "mimeType", void 0);
+__decorate([
+    property()
+], LyraDocumentPreview.prototype, "filename", void 0);
+__decorate([
+    property({ reflect: true })
+], LyraDocumentPreview.prototype, "status", void 0);
+__decorate([
+    property({ type: Number })
+], LyraDocumentPreview.prototype, "progress", void 0);
+__decorate([
+    property({ attribute: 'error-message' })
+], LyraDocumentPreview.prototype, "errorMessage", void 0);
+__decorate([
+    property({ attribute: 'max-height' })
+], LyraDocumentPreview.prototype, "maxHeight", void 0);
+__decorate([
+    state()
+], LyraDocumentPreview.prototype, "hasUnsupportedSlot", void 0);
+__decorate([
+    state()
+], LyraDocumentPreview.prototype, "textFetch", void 0);
+defineElement('document-preview', LyraDocumentPreview);

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

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

package/dist/components/document-preview/document-preview.styles.js

@@ -0,0 +1,191 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+    /* Consumer-tunable scroll cap on [part='body'] -- 'none' means the
+       preview grows with its content until a caller opts into an internal
+       scrollbar, same contract as lyra-json-viewer's identical
+       --lyra-json-viewer-max-height. */
+    --lyra-document-preview-max-height: none;
+    /* No shared --wa-*/--lyra-* monospace token exists to resolve through
+       (same gap lyra-json-viewer's own --lyra-json-viewer-font documents) --
+       contained here so a host page can retheme it. */
+    --lyra-document-preview-font: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  }
+
+  [part='base'] {
+    display: flex;
+    flex-direction: column;
+    box-sizing: border-box;
+    border: 1px solid var(--lyra-color-border);
+    border-radius: var(--lyra-radius);
+    background: var(--lyra-color-surface);
+    overflow: hidden;
+  }
+
+  [part='header'] {
+    display: flex;
+    align-items: center;
+    gap: var(--lyra-space-s);
+    padding: var(--lyra-space-s) var(--lyra-space-m);
+    border-block-end: 1px solid var(--lyra-color-border);
+    background: var(--lyra-color-surface);
+  }
+  [part='header'][hidden] {
+    display: none;
+  }
+  [part='filename'] {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-weight: 600;
+    font-size: 0.875rem;
+    color: var(--lyra-color-text);
+  }
+
+  [part='body'] {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    min-block-size: 10rem;
+    max-block-size: var(--lyra-document-preview-max-height);
+    box-sizing: border-box;
+    overflow: auto;
+    flex: 1 1 auto;
+  }
+
+  /* -- text/*, application/json: plain, scrollable <pre> -----------------
+     No syntax highlighting -- see the class doc for why that's intentionally
+     out of scope here. */
+  pre.text {
+    align-self: stretch;
+    box-sizing: border-box;
+    margin: 0;
+    padding: var(--lyra-space-m);
+    font-family: var(--lyra-document-preview-font);
+    font-size: 0.8125rem;
+    line-height: 1.6;
+    white-space: pre;
+    overflow: auto;
+    color: var(--lyra-color-text);
+  }
+
+  /* -- image/* -------------------------------------------------------- */
+  [part='body'] img {
+    display: block;
+    max-inline-size: 100%;
+    max-block-size: 100%;
+    object-fit: contain;
+  }
+
+  .empty-note {
+    margin: 0;
+    padding: var(--lyra-space-m);
+    color: var(--lyra-color-text-quiet);
+    font-size: 0.875rem;
+  }
+
+  /* -- generic download fallback ------------------------------------- */
+  .fallback {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--lyra-space-s);
+    padding: var(--lyra-space-l);
+    text-align: center;
+  }
+  .fallback-icon {
+    display: inline-flex;
+    font-size: 2rem;
+    color: var(--lyra-color-text-quiet);
+  }
+  .fallback-icon svg {
+    display: block;
+  }
+  .fallback-text {
+    margin: 0;
+    color: var(--lyra-color-text-quiet);
+    font-size: 0.875rem;
+  }
+  [part='download-link'] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--lyra-space-xs);
+    padding: var(--lyra-space-xs) var(--lyra-space-m);
+    border-radius: var(--lyra-radius);
+    background: var(--lyra-color-brand);
+    color: var(--lyra-color-on-brand);
+    font: inherit;
+    font-weight: 600;
+    font-size: 0.8125rem;
+    text-decoration: none;
+    cursor: pointer;
+    transition: background-color var(--lyra-transition-fast);
+  }
+  [part='download-link']:hover {
+    background: color-mix(in srgb, var(--lyra-color-brand) 85%, black);
+  }
+  [part='download-link']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+  [part='download-link'] svg {
+    display: block;
+  }
+
+  /* -- spinner (converting / loading text) ----------------------------- */
+  [part='spinner'] {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--lyra-space-s);
+    padding: var(--lyra-space-l);
+  }
+  .ring {
+    display: inline-block;
+    inline-size: 2rem;
+    block-size: 2rem;
+    border-radius: 50%;
+    border: 3px solid var(--lyra-color-border);
+    border-block-start-color: var(--lyra-color-brand);
+    animation: lyra-document-preview-spin 0.8s linear infinite;
+  }
+  /* Determinate progress reuses the same ring shape but holds a fixed
+     rotation instead of spinning -- conic-gradient renders the actual fill,
+     so the ring visually communicates a real fraction rather than motion. */
+  .ring.determinate {
+    animation: none;
+    border-color: transparent;
+    background: conic-gradient(
+      var(--lyra-color-brand) calc(var(--lyra-document-preview-progress, 0) * 1%),
+      var(--lyra-color-border) 0
+    );
+    -webkit-mask: radial-gradient(farthest-side, transparent calc(100% - 3px), #000 calc(100% - 3px));
+    mask: radial-gradient(farthest-side, transparent calc(100% - 3px), #000 calc(100% - 3px));
+  }
+  .spinner-text {
+    color: var(--lyra-color-text-quiet);
+    font-size: 0.8125rem;
+    font-variant-numeric: tabular-nums;
+  }
+  @keyframes lyra-document-preview-spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .ring {
+      animation: none !important;
+    }
+  }
+
+  /* -- error ------------------------------------------------------------ */
+  [part='error'] {
+    margin: 0;
+    padding: var(--lyra-space-l);
+    color: var(--lyra-color-danger);
+    font-size: 0.875rem;
+    text-align: center;
+  }
+`;

package/dist/components/export-button/csv.js

@@ -2,7 +2,7 @@
 // reliably trigger spreadsheet formula evaluation) — guarding it forces text rendering on
 // ordinary negative numbers/currency. Per OWASP CSV-injection guidance, '-' is intentionally
 // excluded here.
-const UNSAFE_LEADING = /^[=+@\t\r]/;
+const UNSAFE_LEADING = /^[=+@\t\r\n]/;
 const NEEDS_QUOTING = /[",\r\n]/;
 /** Escapes a CSV field: quotes as needed, guards against formula injection. */
 export function escapeCsvField(value) {

package/dist/components/export-button/export-button.js

@@ -83,7 +83,9 @@ export class LyraExportButton extends LyraElement {
     disconnectedCallback() {
         super.disconnectedCallback();
         this.cleanup?.();
+        this.cleanup = undefined;
         document.removeEventListener('pointerdown', this.onDocPointer);
+        this.open = false;
     }
     openMenu() {
         if (this.open)

package/dist/components/flag/flag.d.ts

@@ -1,7 +1,10 @@
 import { type TemplateResult, type PropertyValues } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
 import '../skeleton/skeleton.js';
-type FlagUrlResolver = (code: string) => Promise<string | undefined>;
+type FlagVariant = 'compact' | 'standard' | 'detailed';
+type FlagUrlResolver = (code: string, options?: {
+    variant?: FlagVariant;
+}) => Promise<string | undefined>;
 /**
  * Resolves the optional peer dependency `@aceshooting/lyra-flags`'s `flagUrl`
  * via the given importer (a real dynamic import by default). Uncached and
@@ -31,10 +34,19 @@ export declare function loadFlagUrl(importFlags?: () => Promise<{
  * `src` instead to skip the peer-package round trip (and its loading-skeleton
  * flash) entirely.
  *
+ * The ~65 flags whose design includes a detailed coat of arms/seal/emblem (e.g. `es`, `pt`) ship
+ * three fidelity tiers; choose one with `variant`: `"compact"` (a tiny WebP raster for icon-scale
+ * use — menu items, language selectors, dense lists), the default `"standard"` (icon-optimized
+ * vector for card/row sizes), or `"detailed"` (the pristine full-detail vector for hero-scale
+ * display). A no-op for every other code — all tiers resolve to the same file. See `variant`'s own
+ * doc.
+ *
  * @customElement lyra-flag
  * @example <lyra-flag country="fr"></lyra-flag>
  * @example <lyra-flag language="en" label="English"></lyra-flag>
  * @example <lyra-flag src=${frUrl} label="French"></lyra-flag>
+ * @example <lyra-flag country="es" variant="compact"></lyra-flag>
+ * @example <lyra-flag country="es" variant="detailed"></lyra-flag>
  * @csspart image - The underlying <img>.
  */
 export declare class LyraFlag extends LyraElement {
@@ -53,14 +65,39 @@ export declare class LyraFlag extends LyraElement {
      */
     src?: string;
     /**
-     * Accessible label / `alt` text. Defaults to the uppercase *resolved country
-     * code* — for a `language`-only element (e.g. `language="en"`) that's the
-     * mapped country (`"GB"`), not the language tag itself (`"EN"`). Has no
-     * default when only `src` is given (no country/language to derive one from).
+     * Accessible label / `alt` text. Defaults to a localized, human-readable
+     * region name derived from the *resolved country code* via
+     * `Intl.DisplayNames` (e.g. `"United Kingdom"`) — for a `language`-only
+     * element (e.g. `language="en"`) that's the mapped country's display name,
+     * not the language tag itself. Falls back to the bare uppercase code if
+     * `Intl.DisplayNames` can't resolve it. Has no default when only `src` is
+     * given (no country/language to derive one from).
      */
     label?: string;
     /** Render as a circular flag. */
     round: boolean;
+    /**
+     * Which fidelity tier to load, for the ~65 `country`/`language` codes whose source art embeds a
+     * coat of arms/seal/emblem (for every other code all tiers are the same file, so this is a safe
+     * no-op):
+     * - `"compact"` — a tiny WebP raster for icon-scale use (menu items, language selectors, dense
+     *   lists; ~12–28px), where the emblem detail is invisible anyway.
+     * - `"standard"` (default) — the icon-optimized vector, for card/row sizes (~28–96px).
+     * - `"detailed"` — the pristine, full-detail vector, for rendering larger than icon scale (e.g.
+     *   a hero display) where the extra illustrative detail is actually visible.
+     *
+     * Has no effect when `src` is set — a pre-resolved URL is used as-is regardless. Takes precedence
+     * over the deprecated `detailed` boolean.
+     */
+    variant?: FlagVariant;
+    /**
+     * @deprecated Use `variant="detailed"` instead. Kept as an alias for one minor cycle; when
+     * `variant` is unset, `detailed` still maps to the detailed tier. Removed in the next major.
+     */
+    detailed: boolean;
+    /** The effective tier to request: an explicit `variant` wins; otherwise the deprecated
+     *  `detailed` boolean is honored; otherwise `"standard"`. */
+    private get effectiveVariant();
     private resolvedSrc?;
     /** True while the lazy-loaded `@aceshooting/lyra-flags` peer resolver is in flight. */
     private loading;