@aceshooting/lyra-ui 2.0.0 → 2.1.0

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

@@ -9,6 +9,7 @@ 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 { safeFetchUrl, safeLinkHref, safeMediaSrc } from '../../internal/safe-url.js';
 import { styles } from './document-preview.styles.js';
 const IDLE_TEXT_FETCH = { kind: 'idle' };
 function classifyFormat(mimeType) {
@@ -110,6 +111,13 @@ function icon(paths) {
  * 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
@@ -131,10 +139,10 @@ function icon(paths) {
  *   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
@@ -145,14 +153,15 @@ function icon(paths) {
  * @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 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. */
+         *  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. */
         this.src = '';
         /** Drives format dispatch — see the class doc. */
         this.mimeType = '';
@@ -189,8 +198,9 @@ export class LyraDocumentPreview extends LyraElement {
         if (!this.hasUpdated) {
             this.hasUnsupportedSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'unsupported');
         }
+        const safeTextSrc = safeFetchUrl(this.src);
         const shouldFetchText = classifyFormat(this.mimeType) === 'text' &&
-            this.src !== '' &&
+            safeTextSrc !== null &&
             this.status !== 'converting' &&
             this.status !== 'error';
         if (shouldFetchText) {
@@ -201,7 +211,7 @@ export class LyraDocumentPreview extends LyraElement {
                 changed.has('src') ||
                 changed.has('mimeType') ||
                 (changed.has('status') && this.textFetch.kind === 'idle')) {
-                void this.fetchText(this.src);
+                void this.fetchText(safeTextSrc);
             }
         }
         else if (this.textFetch.kind !== 'idle') {
@@ -269,7 +279,9 @@ export class LyraDocumentPreview extends LyraElement {
     }
     renderTextPreview() {
         if (this.src === '')
-            return html `<pre class="text"></pre>`;
+            return html `<p class="empty-note">No document to display.</p>`;
+        if (safeFetchUrl(this.src) === null)
+            return this.renderError('Document URL is not allowed.');
         switch (this.textFetch.kind) {
             case 'loaded':
                 return html `<pre class="text">${this.textFetch.text}</pre>`;
@@ -284,19 +296,23 @@ export class LyraDocumentPreview extends LyraElement {
     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'} />`;
+        const src = safeMediaSrc(this.src);
+        if (src === null)
+            return this.renderDownloadFallback();
+        return html `<img src=${src} alt=${this.filename || 'Document preview'} />`;
     }
     renderDownloadFallback() {
         const label = this.filename || 'this file';
+        const href = safeLinkHref(this.src);
         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 !== ''
+        ${href !== null
             ? html `
               <a
                 part="download-link"
-                href=${this.src}
+                href=${href}
                 download=${this.filename || ''}
                 @click=${this.onDownloadClick}
               >

package/dist/components/empty/empty.d.ts

@@ -30,8 +30,7 @@ export declare class LyraEmpty extends LyraElement {
     private hasActions;
     protected willUpdate(): void;
     firstUpdated(): void;
-    private checkIconSlot;
-    private checkActionsSlot;
+    private reconcileSlotHidden;
     private onIconSlotChange;
     private onActionsSlotChange;
     render(): TemplateResult;

package/dist/components/empty/empty.js

@@ -42,10 +42,12 @@ export class LyraEmpty extends LyraElement {
         this.hasIcon = false;
         this.hasActions = false;
         this.onIconSlotChange = (e) => {
-            this.checkIconSlot(e.target);
+            const slot = e.target;
+            this.hasIcon = slot.assignedElements({ flatten: true }).length > 0;
         };
         this.onActionsSlotChange = (e) => {
-            this.checkActionsSlot(e.target);
+            const slot = e.target;
+            this.hasActions = slot.assignedElements({ flatten: true }).length > 0;
         };
     }
     static { this.styles = [LyraElement.styles, styles]; }
@@ -64,17 +66,21 @@ export class LyraEmpty extends LyraElement {
     }
     firstUpdated() {
         // Fallback reconciliation against the fully-resolved slot assignment
-        // (handles slot-forwarding and any browser where `slotchange` doesn't
-        // fire for content present at parse/upgrade time). A no-op in the
-        // common case since `willUpdate` already set the correct value above.
-        this.checkIconSlot(this.shadowRoot.querySelector('slot:not([name])'));
-        this.checkActionsSlot(this.shadowRoot.querySelector('slot[name="actions"]'));
+        // (handles slot-forwarding — where `this.children` in `willUpdate` above
+        // are forwarding `<slot>` elements rather than the real projected
+        // content, e.g. a wrapper component's own default slot re-slotted into
+        // ours — and any browser where `slotchange` doesn't fire for content
+        // present at parse/upgrade time). This corrects the `hidden` attribute
+        // on the wrapper elements directly rather than through
+        // `hasIcon`/`hasActions`, so this one-shot correction doesn't need to
+        // schedule and wait out a second Lit render pass; the reactive state is
+        // left as `willUpdate` set it and continues to drive only the ongoing
+        // `slotchange` path below.
+        this.reconcileSlotHidden(this.shadowRoot.querySelector('slot:not([name])'), this.shadowRoot.querySelector('[part="icon"]'));
+        this.reconcileSlotHidden(this.shadowRoot.querySelector('slot[name="actions"]'), this.shadowRoot.querySelector('[part="actions"]'));
     }
-    checkIconSlot(slot) {
-        this.hasIcon = slot.assignedElements({ flatten: true }).length > 0;
-    }
-    checkActionsSlot(slot) {
-        this.hasActions = slot.assignedElements({ flatten: true }).length > 0;
+    reconcileSlotHidden(slot, wrapper) {
+        wrapper.toggleAttribute('hidden', slot.assignedElements({ flatten: true }).length === 0);
     }
     render() {
         return html `

package/dist/components/empty/empty.styles.js

@@ -44,9 +44,6 @@ export const styles = css `
   [part='description']:empty {
     display: none;
   }
-  [part='actions'] {
-    margin-block-start: var(--lyra-space-s);
-  }
   [part='actions'][hidden] {
     display: none;
   }

package/dist/components/export-button/export-button.d.ts

@@ -18,10 +18,16 @@ export type ExportFormat = 'csv' | 'json';
 export declare class LyraExportButton extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
     rows: Record<string, unknown>[];
+    /** Column allow-list (and CSV header labels) for both export formats. Left
+     *  at its default empty array, both formats fall back to the union of the
+     *  rows' own keys instead (see `effectiveColumns()`), rather than CSV
+     *  degrading to a blank file while only JSON had a fallback. */
     columns: CsvColumn[];
     filename: string;
     formats: ExportFormat[];
     disabled: boolean;
+    /** Trigger button text, also feeds the format menu's `aria-label` (as
+     *  "`${label} format`") so assistive tech gets an accessible name for it. */
     label: string;
     open: boolean;
     private triggerEl?;
@@ -42,6 +48,12 @@ export declare class LyraExportButton extends LyraElement {
     private onKeyDown;
     protected firstUpdated(): void;
     protected updated(changed: PropertyValues): void;
+    /** Falls back to the union of the rows' own keys when `columns` is left at
+     *  its default empty array, so an unconfigured export still produces a
+     *  proper header + data file instead of blank lines. Both `rowsForExport()`
+     *  and the CSV branch of `doExport()` share this same fallback, rather than
+     *  only the JSON path having one. */
+    private effectiveColumns;
     /** Applies the same `columns` allow-list CSV exports use, so JSON can't leak fields CSV hides. */
     private rowsForExport;
     private doExport;

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

@@ -29,10 +29,16 @@ export class LyraExportButton extends LyraElement {
     constructor() {
         super(...arguments);
         this.rows = [];
+        /** Column allow-list (and CSV header labels) for both export formats. Left
+         *  at its default empty array, both formats fall back to the union of the
+         *  rows' own keys instead (see `effectiveColumns()`), rather than CSV
+         *  degrading to a blank file while only JSON had a fallback. */
         this.columns = [];
         this.filename = 'export';
         this.formats = ['csv'];
         this.disabled = false;
+        /** Trigger button text, also feeds the format menu's `aria-label` (as
+         *  "`${label} format`") so assistive tech gets an accessible name for it. */
         this.label = 'Export';
         this.open = false;
         this.menuId = nextId('export-menu');
@@ -76,6 +82,12 @@ export class LyraExportButton extends LyraElement {
                         this.focusMenuItem(items.length - 1);
                     }
                     break;
+                case 'Tab':
+                    // No preventDefault -- native Tab navigation proceeds untouched, only
+                    // the now-stale open menu closes (mirrors lyra-menu's identical
+                    // Tab handling).
+                    this.closeMenu();
+                    break;
             }
         };
     }
@@ -143,11 +155,24 @@ export class LyraExportButton extends LyraElement {
             }
         }
     }
+    /** Falls back to the union of the rows' own keys when `columns` is left at
+     *  its default empty array, so an unconfigured export still produces a
+     *  proper header + data file instead of blank lines. Both `rowsForExport()`
+     *  and the CSV branch of `doExport()` share this same fallback, rather than
+     *  only the JSON path having one. */
+    effectiveColumns() {
+        if (this.columns.length > 0)
+            return this.columns;
+        const keys = new Set();
+        for (const row of this.rows) {
+            for (const key of Object.keys(row))
+                keys.add(key);
+        }
+        return Array.from(keys, (key) => ({ key, label: key }));
+    }
     /** Applies the same `columns` allow-list CSV exports use, so JSON can't leak fields CSV hides. */
     rowsForExport() {
-        if (this.columns.length === 0)
-            return this.rows;
-        const keys = this.columns.map((c) => c.key);
+        const keys = this.effectiveColumns().map((c) => c.key);
         return this.rows.map((row) => {
             const picked = {};
             for (const key of keys)
@@ -156,13 +181,15 @@ export class LyraExportButton extends LyraElement {
         });
     }
     doExport(format) {
+        if (this.disabled)
+            return;
         this.closeMenu();
         this.triggerEl?.focus();
         const ev = this.emit('lyra-export', { format });
         if (ev.defaultPrevented)
             return;
         if (format === 'csv') {
-            downloadBlob(buildCsv(this.rows, this.columns), `${this.filename}.csv`, 'text/csv;charset=utf-8;');
+            downloadBlob(buildCsv(this.rows, this.effectiveColumns()), `${this.filename}.csv`, 'text/csv;charset=utf-8;');
         }
         else {
             downloadBlob(JSON.stringify(this.rowsForExport(), null, 2), `${this.filename}.json`, 'application/json');
@@ -191,11 +218,12 @@ export class LyraExportButton extends LyraElement {
         ${this.label}
       </button>
       ${this.formats.length > 1
-            ? html `<div id=${this.menuId} part="menu" role="menu">
+            ? html `<div id=${this.menuId} part="menu" role="menu" aria-label="${this.label} format">
             ${this.formats.map((f) => html `<button
                   part="menu-item"
                   role="menuitem"
                   type="button"
+                  ?disabled=${this.disabled}
                   @click=${() => this.doExport(f)}
                 >
                   ${f.toUpperCase()}

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

@@ -77,11 +77,15 @@ export const styles = css `
     cursor: pointer;
     border-radius: var(--lyra-radius);
   }
-  [part='menu-item']:hover {
+  [part='menu-item']:hover:not(:disabled) {
     background: var(--lyra-color-brand-quiet);
   }
   [part='menu-item']:focus-visible {
     outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
     outline-offset: var(--lyra-focus-ring-offset);
   }
+  [part='menu-item']:disabled {
+    opacity: var(--lyra-opacity-disabled);
+    cursor: not-allowed;
+  }
 `;

package/dist/components/file-input/accept.js

@@ -28,6 +28,8 @@ export function matchesAccept(file, accept, assumeExtensionMatch = false) {
     return parts.some((p) => {
         if (p.startsWith('.'))
             return name === undefined ? assumeExtensionMatch : name.endsWith(p);
+        if (p === '*/*')
+            return true;
         if (p.endsWith('/*'))
             return type.startsWith(p.slice(0, -1));
         return type === p;

package/dist/components/file-input/file-input.d.ts

@@ -14,7 +14,9 @@ export interface RejectedFile {
  * accessible name always comes from `label`, so icon-only slot content
  * remains announced correctly.
  * @event lyra-files - `detail: { files, rejected }`, fired on drop and manual selection.
- * @csspart base, input, status
+ * @csspart base - The dropzone's root, clickable/focusable container.
+ * @csspart input - The visually-hidden native `<input type="file">`.
+ * @csspart status - The visually-hidden live region announcing drag accept/reject state.
  */
 export declare class LyraFileInput extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -25,7 +27,14 @@ export declare class LyraFileInput extends LyraElement {
     forbiddenMimeTypes: string[];
     maxFileSize: number;
     label: string;
+    /** Message announced after an accepted selection; `{count}` is replaced by
+     * the number of accepted files. */
+    acceptedMessage: string;
+    /** Message announced after rejected files; `{count}` is replaced by the
+     * number of rejected files. */
+    rejectedMessage: string;
     private dragState;
+    private resultStatus;
     private inputEl?;
     private dragCounter;
     private isAllowed;

package/dist/components/file-input/file-input.js

@@ -21,7 +21,9 @@ import { matchesAccept } from './accept.js';
  * accessible name always comes from `label`, so icon-only slot content
  * remains announced correctly.
  * @event lyra-files - `detail: { files, rejected }`, fired on drop and manual selection.
- * @csspart base, input, status
+ * @csspart base - The dropzone's root, clickable/focusable container.
+ * @csspart input - The visually-hidden native `<input type="file">`.
+ * @csspart status - The visually-hidden live region announcing drag accept/reject state.
  */
 export class LyraFileInput extends LyraElement {
     constructor() {
@@ -33,20 +35,30 @@ export class LyraFileInput extends LyraElement {
         this.forbiddenMimeTypes = [];
         this.maxFileSize = 0;
         this.label = 'Drop files here or click to browse';
+        /** Message announced after an accepted selection; `{count}` is replaced by
+         * the number of accepted files. */
+        this.acceptedMessage = '{count} file(s) added.';
+        /** Message announced after rejected files; `{count}` is replaced by the
+         * number of rejected files. */
+        this.rejectedMessage = '{count} file(s) rejected.';
         this.dragState = 'default';
+        this.resultStatus = '';
         this.dragCounter = 0;
         this.onDragEnter = (e) => {
+            e.preventDefault();
             if (this.disabled)
                 return;
-            e.preventDefault();
             this.dragCounter++;
             const items = e.dataTransfer ? [...e.dataTransfer.items].filter((i) => i.kind === 'file') : [];
             this.dragState = items.length ? this.previewState(items) : 'default';
         };
         this.onDragOver = (e) => {
+            // Always suppress the browser's default drop action (e.g. navigating the
+            // whole page to the dropped file), even while disabled — only the
+            // subsequent classification/emit logic is gated on `disabled`.
+            e.preventDefault();
             if (this.disabled)
                 return;
-            e.preventDefault();
         };
         this.onDragLeave = (e) => {
             if (this.disabled)
@@ -57,9 +69,11 @@ export class LyraFileInput extends LyraElement {
                 this.dragState = 'default';
         };
         this.onDrop = (e) => {
+            // Same rationale as `onDragOver`: prevent the browser's default drop
+            // action unconditionally, before the `disabled` gate.
+            e.preventDefault();
             if (this.disabled)
                 return;
-            e.preventDefault();
             this.dragCounter = 0;
             this.dragState = 'default';
             const files = [...(e.dataTransfer?.files ?? [])];
@@ -118,10 +132,18 @@ export class LyraFileInput extends LyraElement {
     }
     emitFiles(fileList) {
         const { files, rejected } = this.classify(fileList);
+        const messages = [];
+        if (files.length)
+            messages.push(this.acceptedMessage.replace('{count}', String(files.length)));
+        if (rejected.length)
+            messages.push(this.rejectedMessage.replace('{count}', String(rejected.length)));
+        this.resultStatus = messages.join(' ');
         this.emit('lyra-files', { files, rejected });
     }
     /** Programmatically open the native file picker. */
     openPicker() {
+        if (this.disabled)
+            return;
         this.inputEl?.click();
     }
     previewState(fileList) {
@@ -133,7 +155,7 @@ export class LyraFileInput extends LyraElement {
             return 'Release to add the file.';
         if (this.dragState === 'reject')
             return 'This file type is not accepted.';
-        return '';
+        return this.resultStatus;
     }
     render() {
         return html `
@@ -188,9 +210,18 @@ __decorate([
 __decorate([
     property()
 ], LyraFileInput.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'accepted-message' })
+], LyraFileInput.prototype, "acceptedMessage", void 0);
+__decorate([
+    property({ attribute: 'rejected-message' })
+], LyraFileInput.prototype, "rejectedMessage", void 0);
 __decorate([
     state()
 ], LyraFileInput.prototype, "dragState", void 0);
+__decorate([
+    state()
+], LyraFileInput.prototype, "resultStatus", void 0);
 __decorate([
     query('input[type="file"]')
 ], LyraFileInput.prototype, "inputEl", void 0);

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

@@ -1,7 +1,7 @@
 import { type TemplateResult, type PropertyValues } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
 import '../skeleton/skeleton.js';
-type FlagVariant = 'compact' | 'standard' | 'detailed';
+export type FlagVariant = 'compact' | 'standard' | 'detailed';
 type FlagUrlResolver = (code: string, options?: {
     variant?: FlagVariant;
 }) => Promise<string | undefined>;

package/dist/components/flag/flag.js

@@ -28,6 +28,14 @@ export async function loadFlagUrl(importFlags = () => import('@aceshooting/lyra-
         return null;
     }
 }
+/**
+ * One `Intl.DisplayNames` instance per locale, shared across every `<lyra-flag>` on the page.
+ * Constructing one is an ICU locale-data lookup, and `displayNameFor()` runs on every `render()`
+ * pass for a flag without an explicit `label` (e.g. toggling `round`), not just on country/language
+ * change -- multi-flag lists (language pickers, country lists) would otherwise pay this cost once
+ * per element per render. Mirrors the module-level caching `flagUrlResolver` already gets above.
+ */
+const displayNamesCache = new Map();
 /**
  * Resolves an ISO 3166-1 alpha-2 region code to a human-readable, localized
  * display name (e.g. `'FR'` -> `'France'`) via `Intl.DisplayNames`, for use as
@@ -38,7 +46,13 @@ export async function loadFlagUrl(importFlags = () => import('@aceshooting/lyra-
  */
 function displayNameFor(code) {
     try {
-        return new Intl.DisplayNames([navigator.language], { type: 'region' }).of(code.toUpperCase()) ?? code.toUpperCase();
+        const locale = navigator.language;
+        let dn = displayNamesCache.get(locale);
+        if (!dn) {
+            dn = new Intl.DisplayNames([locale], { type: 'region' });
+            displayNamesCache.set(locale, dn);
+        }
+        return dn.of(code.toUpperCase()) ?? code.toUpperCase();
     }
     catch {
         return code.toUpperCase();

package/dist/components/flag/flag.styles.js

@@ -11,7 +11,7 @@ export const styles = css `
     display: block;
     block-size: 100%;
     inline-size: 100%;
-    border-radius: var(--lyra-flag-radius, 2px);
+    border-radius: var(--lyra-flag-radius, calc(var(--lyra-radius) * 0.33));
     box-shadow: 0 0 0 1px var(--lyra-color-border) inset;
     object-fit: cover;
   }

package/dist/components/flag/language-map.d.ts

@@ -17,6 +17,9 @@ export declare const ALPHA2_RE: RegExp;
 export declare const LANGUAGE_TO_COUNTRY: Record<string, string>;
 /**
  * Resolve a BCP-47-ish language tag to a flag country code.
- * A region subtag wins (`en-US` → `us`); otherwise the base language is mapped.
+ * A region subtag wins (`en-US` → `us`); otherwise the base language is mapped. The region subtag
+ * isn't always in the second position -- a script subtag (e.g. `zh-Hant-TW`, ISO 15924, always 4
+ * letters) can sit between the base language and the region, so every subtag after the base is
+ * scanned for the first 2-letter alpha match rather than assuming it's always `parts[1]`.
  */
 export declare function languageToCountry(language: string): string | undefined;

package/dist/components/flag/language-map.js

@@ -61,13 +61,16 @@ export const LANGUAGE_TO_COUNTRY = {
 };
 /**
  * Resolve a BCP-47-ish language tag to a flag country code.
- * A region subtag wins (`en-US` → `us`); otherwise the base language is mapped.
+ * A region subtag wins (`en-US` → `us`); otherwise the base language is mapped. The region subtag
+ * isn't always in the second position -- a script subtag (e.g. `zh-Hant-TW`, ISO 15924, always 4
+ * letters) can sit between the base language and the region, so every subtag after the base is
+ * scanned for the first 2-letter alpha match rather than assuming it's always `parts[1]`.
  */
 export function languageToCountry(language) {
     const parts = language.toLowerCase().split(/[-_]/);
     const base = parts[0];
-    const region = parts[1];
-    if (region && ALPHA2_RE.test(region))
+    const region = parts.slice(1).find((part) => ALPHA2_RE.test(part));
+    if (region)
         return region;
     return LANGUAGE_TO_COUNTRY[base];
 }

package/dist/components/gauge/gauge.d.ts

@@ -6,7 +6,11 @@ export type GaugeType = 'radial' | 'linear';
  * generic gauge widget exists in Web Awesome.
  *
  * @customElement lyra-gauge
- * @csspart base, track, fill, value, label
+ * @csspart base - The root `<svg>`.
+ * @csspart track - The background track arc/line.
+ * @csspart fill - The animated fill arc/line.
+ * @csspart value - The value text.
+ * @csspart label - The label text.
  */
 export declare class LyraGauge extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -18,7 +22,12 @@ export declare class LyraGauge extends LyraElement {
     /** Imperative override for the displayed/announced value text, e.g. `'72°F'` for a raw `value` of `72`.
      * An empty string is treated the same as unset and falls back to the numeric `value`. */
     valueLabel?: string;
+    private get domain();
     private get ratio();
+    /** The text rendered/announced for the current value: `valueLabel` when set,
+     * else the numeric `value`, blanked (like the ARIA attributes and fill) when
+     * `value` is non-finite (NaN/undefined/Infinity/-Infinity). */
+    private get displayText();
     protected willUpdate(): void;
     private renderRadial;
     private renderLinear;

package/dist/components/gauge/gauge.js

@@ -8,6 +8,7 @@ import { html, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
+import { finiteNumber } from '../../internal/numbers.js';
 import { styles } from './gauge.styles.js';
 // Radial gauge sweeps 270° (like a speedometer), leaving a 90° gap at the bottom.
 const SWEEP_DEG = 270;
@@ -44,7 +45,11 @@ const RADIAL_ARC_LENGTH = (SWEEP_DEG / 360) * 2 * Math.PI * RADIUS;
  * generic gauge widget exists in Web Awesome.
  *
  * @customElement lyra-gauge
- * @csspart base, track, fill, value, label
+ * @csspart base - The root `<svg>`.
+ * @csspart track - The background track arc/line.
+ * @csspart fill - The animated fill arc/line.
+ * @csspart value - The value text.
+ * @csspart label - The label text.
  */
 export class LyraGauge extends LyraElement {
     constructor() {
@@ -56,23 +61,37 @@ export class LyraGauge extends LyraElement {
         this.label = '';
     }
     static { this.styles = [LyraElement.styles, styles]; }
+    // Normalizes a reversed min > max domain by swapping lo/hi, but only once
+    // both bounds are finite -- shared by `ratio` (fill geometry) and
+    // `willUpdate` (aria-value* trio) so the two can never silently diverge.
+    get domain() {
+        const min = finiteNumber(this.min, 0);
+        const max = finiteNumber(this.max, 100);
+        return { lo: Math.min(min, max), hi: Math.max(min, max) };
+    }
     get ratio() {
-        if (!Number.isFinite(this.value) || !Number.isFinite(this.min) || !Number.isFinite(this.max))
+        if (!Number.isFinite(this.value))
+            return 0;
+        const { lo, hi } = this.domain;
+        if (!Number.isFinite(lo) || !Number.isFinite(hi))
             return 0;
-        const lo = Math.min(this.min, this.max);
-        const hi = Math.max(this.min, this.max);
         const span = hi - lo || 1;
         return Math.min(1, Math.max(0, (this.value - lo) / span));
     }
+    /** The text rendered/announced for the current value: `valueLabel` when set,
+     * else the numeric `value`, blanked (like the ARIA attributes and fill) when
+     * `value` is non-finite (NaN/undefined/Infinity/-Infinity). */
+    get displayText() {
+        return this.valueLabel || (!Number.isFinite(this.value) ? '' : String(this.value));
+    }
     willUpdate() {
         this.setAttribute('role', 'meter');
-        const finiteTrio = Number.isFinite(this.value) && Number.isFinite(this.min) && Number.isFinite(this.max);
         // Normalize a reversed min > max domain the same way `ratio` does, so the
         // announced aria-value* trio always agrees with the visual fill instead
         // of aria-valuenow pinning to one bound regardless of `value` (and
         // aria-valuemin/valuemax reporting an inverted, invalid ARIA range).
-        const lo = Number.isFinite(this.min) && Number.isFinite(this.max) ? Math.min(this.min, this.max) : this.min;
-        const hi = Number.isFinite(this.min) && Number.isFinite(this.max) ? Math.max(this.min, this.max) : this.max;
+        const { lo, hi } = this.domain;
+        const finiteTrio = Number.isFinite(this.value) && Number.isFinite(lo) && Number.isFinite(hi);
         if (finiteTrio) {
             const clamped = Math.min(hi, Math.max(lo, this.value));
             this.setAttribute('aria-valuenow', String(clamped));
@@ -98,7 +117,7 @@ export class LyraGauge extends LyraElement {
             this.removeAttribute('aria-valuetext');
     }
     renderRadial() {
-        const text = this.valueLabel || (isNaN(this.value) ? '' : String(this.value));
+        const text = this.displayText;
         // Dashoffset counts down from the full arc length (nothing revealed) to 0
         // (whole sweep revealed) as ratio goes 0 -> 1 — the classic "draw an SVG
         // path" technique, which transitions smoothly via plain CSS.
@@ -117,7 +136,7 @@ export class LyraGauge extends LyraElement {
     </svg>`;
     }
     renderLinear() {
-        const text = this.valueLabel || (isNaN(this.value) ? '' : String(this.value));
+        const text = this.displayText;
         const dashoffset = LINEAR_LENGTH * (1 - this.ratio);
         return html `<svg part="base" viewBox="0 0 100 20" preserveAspectRatio="none">
       <line part="track" x1="0" y1=${LINEAR_BAR_Y} x2="100" y2=${LINEAR_BAR_Y} stroke-width=${LINEAR_STROKE}></line>