@aceshooting/lyra-ui 1.0.1 → 1.1.0

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

@@ -5,10 +5,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { html, nothing } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, query } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { place } from '../../internal/positioner.js';
+import { nextId } from '../../internal/a11y.js';
 import { buildCsv, downloadBlob } from './csv.js';
 import { styles } from './export-button.styles.js';
 /**
@@ -20,7 +21,9 @@ import { styles } from './export-button.styles.js';
  * @event lyra-export - `detail: { format }`, cancelable — call `preventDefault()`
  *   to substitute the built-in client-side download with a server-generated one.
  * @event lyra-export-complete - Fired after a non-cancelled download completes.
- * @csspart trigger, menu, menu-item
+ * @csspart trigger - The button that triggers the export (or opens the format menu).
+ * @csspart menu - The format-choice menu, shown when more than one format is configured.
+ * @csspart menu-item - A single format option inside the menu.
  */
 export class LyraExportButton extends LyraElement {
     constructor() {
@@ -32,15 +35,47 @@ export class LyraExportButton extends LyraElement {
         this.disabled = false;
         this.label = 'Export';
         this.open = false;
+        this.menuId = nextId('export-menu');
+        /** Which menu item to focus the next time `open` flips true; reset after use. */
+        this.pendingMenuFocusIndex = 0;
         this.onDocPointer = (e) => {
             if (!e.composedPath().includes(this))
                 this.closeMenu();
         };
         this.onKeyDown = (e) => {
-            if (e.key === 'Escape' && this.open) {
-                e.preventDefault();
-                this.closeMenu();
-                this.renderRoot.querySelector('[part="trigger"]')?.focus();
+            if (e.key === 'Escape') {
+                if (this.open) {
+                    e.preventDefault();
+                    this.closeMenu();
+                    this.triggerEl?.focus();
+                }
+                return;
+            }
+            if (this.formats.length <= 1 || this.disabled)
+                return;
+            const items = this.menuItemEls();
+            const currentIndex = items.indexOf(e.target);
+            switch (e.key) {
+                case 'ArrowDown':
+                    e.preventDefault();
+                    this.focusMenuItemOnOpen(currentIndex === -1 ? 0 : currentIndex + 1);
+                    break;
+                case 'ArrowUp':
+                    e.preventDefault();
+                    this.focusMenuItemOnOpen(currentIndex === -1 ? items.length - 1 : currentIndex - 1);
+                    break;
+                case 'Home':
+                    if (this.open) {
+                        e.preventDefault();
+                        this.focusMenuItem(0);
+                    }
+                    break;
+                case 'End':
+                    if (this.open) {
+                        e.preventDefault();
+                        this.focusMenuItem(items.length - 1);
+                    }
+                    break;
             }
         };
     }
@@ -60,9 +95,29 @@ export class LyraExportButton extends LyraElement {
             return;
         this.open = false;
     }
+    menuItemEls() {
+        return Array.from(this.renderRoot.querySelectorAll('[part="menu-item"]'));
+    }
+    /** Focuses the menu item at `index` (clamped), if the menu is already open and rendered. */
+    focusMenuItem(index) {
+        const items = this.menuItemEls();
+        if (items.length === 0)
+            return;
+        items[Math.max(0, Math.min(items.length - 1, index))]?.focus();
+    }
+    /** Opens the menu (if closed) and focuses `index`, or moves focus there directly if already open. */
+    focusMenuItemOnOpen(index) {
+        if (this.open) {
+            this.focusMenuItem(index);
+        }
+        else {
+            this.pendingMenuFocusIndex = index;
+            this.openMenu();
+        }
+    }
     firstUpdated() {
-        // Single delegated listener catches Escape from the trigger button or
-        // any menu-item inside this shadow root.
+        // Single delegated listener catches Escape/Arrow/Home/End from the
+        // trigger button or any menu-item inside this shadow root.
         this.renderRoot.addEventListener('keydown', this.onKeyDown);
     }
     updated(changed) {
@@ -76,16 +131,31 @@ export class LyraExportButton extends LyraElement {
             // property), which bypasses openMenu() entirely.
             document.removeEventListener('pointerdown', this.onDocPointer);
             if (this.open) {
-                const anchor = this.renderRoot.querySelector('[part="trigger"]');
-                const menu = this.renderRoot.querySelector('[part="menu"]');
+                const anchor = this.triggerEl;
+                const menu = this.menuEl;
                 if (anchor && menu)
                     this.cleanup = place(anchor, menu);
                 document.addEventListener('pointerdown', this.onDocPointer);
+                this.focusMenuItem(this.pendingMenuFocusIndex);
+                this.pendingMenuFocusIndex = 0;
             }
         }
     }
+    /** 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);
+        return this.rows.map((row) => {
+            const picked = {};
+            for (const key of keys)
+                picked[key] = row[key];
+            return picked;
+        });
+    }
     doExport(format) {
         this.closeMenu();
+        this.triggerEl?.focus();
         const ev = this.emit('lyra-export', { format });
         if (ev.defaultPrevented)
             return;
@@ -93,7 +163,7 @@ export class LyraExportButton extends LyraElement {
             downloadBlob(buildCsv(this.rows, this.columns), `${this.filename}.csv`, 'text/csv;charset=utf-8;');
         }
         else {
-            downloadBlob(JSON.stringify(this.rows, null, 2), `${this.filename}.json`, 'application/json');
+            downloadBlob(JSON.stringify(this.rowsForExport(), null, 2), `${this.filename}.json`, 'application/json');
         }
         this.emit('lyra-export-complete', { format });
     }
@@ -113,12 +183,13 @@ export class LyraExportButton extends LyraElement {
         ?disabled=${this.disabled}
         aria-haspopup=${this.formats.length > 1 ? 'menu' : nothing}
         aria-expanded=${this.formats.length > 1 ? (this.open ? 'true' : 'false') : nothing}
+        aria-controls=${this.formats.length > 1 ? this.menuId : nothing}
         @click=${() => this.onTriggerClick()}
       >
         ${this.label}
       </button>
       ${this.formats.length > 1
-            ? html `<div part="menu" role="menu">
+            ? html `<div id=${this.menuId} part="menu" role="menu">
             ${this.formats.map((f) => html `<button
                   part="menu-item"
                   role="menuitem"
@@ -153,4 +224,10 @@ __decorate([
 __decorate([
     property({ type: Boolean, reflect: true })
 ], LyraExportButton.prototype, "open", void 0);
+__decorate([
+    query('[part="trigger"]')
+], LyraExportButton.prototype, "triggerEl", void 0);
+__decorate([
+    query('[part="menu"]')
+], LyraExportButton.prototype, "menuEl", void 0);
 defineElement('export-button', LyraExportButton);

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

@@ -4,3 +4,4 @@ export default meta;
 type Story = StoryObj;
 export declare const SingleFormat: Story;
 export declare const MultiFormatMenu: Story;
+export declare const Disabled: Story;

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

@@ -30,3 +30,8 @@ export const MultiFormatMenu = {
     ></lyra-export-button>
   `,
 };
+export const Disabled = {
+    render: () => html `
+    <lyra-export-button filename="demo" .rows=${rows} .columns=${columns} disabled></lyra-export-button>
+  `,
+};

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

@@ -30,7 +30,16 @@ export const styles = css `
   [part='menu'] {
     /* Closed state: invisible + slightly raised. visibility (not
        display:none) so opacity/transform can actually transition; hit-testing
-       and a11y exposure stay off since this part is already position:fixed. */
+       and a11y exposure stay off since this part is already position:fixed.
+       visibility deliberately isn't in the transition list below: a
+       transitioned property's computed value only settles to its new
+       target after the UA has run an actual style-change/rendering pass,
+       which lags behind a same-tick attribute write (e.g. updated()
+       synchronously focusing the first menu item right after flipping
+       open) -- that item would still resolve as visibility: hidden (and
+       so silently fail to focus) at the moment .focus() is called. Leaving
+       visibility untransitioned makes it apply immediately, in the same
+       synchronous style pass as the open attribute write. */
     visibility: hidden;
     position: fixed;
     z-index: 900;
@@ -44,8 +53,7 @@ export const styles = css `
     transform: translateY(-4px);
     transition:
       opacity var(--lyra-transition-fast),
-      transform var(--lyra-transition-fast),
-      visibility var(--lyra-transition-fast);
+      transform var(--lyra-transition-fast);
   }
   :host([open]) [part='menu'] {
     visibility: visible;

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

@@ -8,6 +8,12 @@
  * `file` may be a `DataTransferItem` cast as `File` (the dragenter-preview
  * call site, before the drop payload has real `File` objects) - unlike
  * `File`, `DataTransferItem` has no `.name`, only `.type`, so extension
- * patterns (`.csv`) can't be evaluated pre-drop and never match.
+ * patterns (`.csv`) can't be evaluated pre-drop. By default an unresolved
+ * extension pattern counts as no match, since that's the correct behavior
+ * once real `File` objects are available at drop time. Pass
+ * `assumeExtensionMatch: true` to instead treat an unresolved extension
+ * pattern as a possible match — this is what dragenter preview uses so it
+ * doesn't render a false "reject" state for accept lists that are
+ * extension-only, when the file may well be accepted once dropped.
  */
-export declare function matchesAccept(file: File, accept: string): boolean;
+export declare function matchesAccept(file: File, accept: string, assumeExtensionMatch?: boolean): boolean;

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

@@ -8,9 +8,15 @@
  * `file` may be a `DataTransferItem` cast as `File` (the dragenter-preview
  * call site, before the drop payload has real `File` objects) - unlike
  * `File`, `DataTransferItem` has no `.name`, only `.type`, so extension
- * patterns (`.csv`) can't be evaluated pre-drop and never match.
+ * patterns (`.csv`) can't be evaluated pre-drop. By default an unresolved
+ * extension pattern counts as no match, since that's the correct behavior
+ * once real `File` objects are available at drop time. Pass
+ * `assumeExtensionMatch: true` to instead treat an unresolved extension
+ * pattern as a possible match — this is what dragenter preview uses so it
+ * doesn't render a false "reject" state for accept lists that are
+ * extension-only, when the file may well be accepted once dropped.
  */
-export function matchesAccept(file, accept) {
+export function matchesAccept(file, accept, assumeExtensionMatch = false) {
     const parts = accept
         .split(',')
         .map((s) => s.trim().toLowerCase())
@@ -21,7 +27,7 @@ export function matchesAccept(file, accept) {
     const type = (file.type || '').toLowerCase();
     return parts.some((p) => {
         if (p.startsWith('.'))
-            return name !== undefined && name.endsWith(p);
+            return name === undefined ? assumeExtensionMatch : name.endsWith(p);
         if (p.endsWith('/*'))
             return type.startsWith(p.slice(0, -1));
         return type === p;

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

@@ -10,9 +10,11 @@ export interface RejectedFile {
  * where files ultimately get uploaded and processed anyway.
  *
  * @customElement lyra-file-input
- * @slot - Custom drop-zone content, overrides the `label` attribute.
+ * @slot - Custom drop-zone content, overrides the `label` attribute. The
+ * 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
+ * @csspart base, input, status
  */
 export declare class LyraFileInput extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -38,6 +40,7 @@ export declare class LyraFileInput extends LyraElement {
     private onDrop;
     private onInputChange;
     private onKeyDown;
+    private statusText;
     render(): TemplateResult;
 }
 declare global {

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

@@ -8,6 +8,7 @@ import { html, nothing } from 'lit';
 import { property, state, query } 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 './file-input.styles.js';
 import { matchesAccept } from './accept.js';
 /**
@@ -16,9 +17,11 @@ import { matchesAccept } from './accept.js';
  * where files ultimately get uploaded and processed anyway.
  *
  * @customElement lyra-file-input
- * @slot - Custom drop-zone content, overrides the `label` attribute.
+ * @slot - Custom drop-zone content, overrides the `label` attribute. The
+ * 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
+ * @csspart base, input, status
  */
 export class LyraFileInput extends LyraElement {
     constructor() {
@@ -80,13 +83,16 @@ export class LyraFileInput extends LyraElement {
             }
         };
     }
-    static { this.styles = [LyraElement.styles, styles]; }
-    isAllowed(file) {
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    isAllowed(file, isPreview = false) {
         if (this.forbiddenMimeTypes.includes(file.type))
             return 'type';
         if (this.allowedMimeTypes.length > 0 && !this.allowedMimeTypes.includes(file.type))
             return 'type';
-        if (this.accept && !matchesAccept(file, this.accept))
+        // During dragenter preview, `accept` extension patterns can't be evaluated (no
+        // `.name` yet) — treat them as a possible match rather than a guaranteed reject,
+        // so the preview doesn't flag a file that will in fact be accepted on drop.
+        if (this.accept && !matchesAccept(file, this.accept, isPreview))
             return 'type';
         // `file.size` is `undefined` on the synthetic `DataTransferItem`-cast objects
         // used during dragenter preview (real sizes aren't available until drop),
@@ -95,14 +101,14 @@ export class LyraFileInput extends LyraElement {
             return 'size';
         return 'ok';
     }
-    classify(fileList) {
+    classify(fileList, isPreview = false) {
         if (!this.multiple && fileList.length > 1) {
             return { files: [], rejected: fileList.map((file) => ({ file, reason: 'count' })) };
         }
         const files = [];
         const rejected = [];
         for (const f of fileList) {
-            const reason = this.isAllowed(f);
+            const reason = this.isAllowed(f, isPreview);
             if (reason === 'ok')
                 files.push(f);
             else
@@ -119,9 +125,16 @@ export class LyraFileInput extends LyraElement {
         this.inputEl?.click();
     }
     previewState(fileList) {
-        const { rejected } = this.classify(fileList);
+        const { rejected } = this.classify(fileList, true);
         return rejected.length > 0 ? 'reject' : 'accept';
     }
+    statusText() {
+        if (this.dragState === 'accept')
+            return 'Release to add the file.';
+        if (this.dragState === 'reject')
+            return 'This file type is not accepted.';
+        return '';
+    }
     render() {
         return html `
       <div
@@ -129,6 +142,7 @@ export class LyraFileInput extends LyraElement {
         role="button"
         tabindex=${this.disabled ? '-1' : '0'}
         aria-disabled=${this.disabled ? 'true' : nothing}
+        aria-label=${this.label}
         data-drag-state=${this.dragState}
         @dragenter=${this.onDragEnter}
         @dragover=${this.onDragOver}
@@ -139,6 +153,7 @@ export class LyraFileInput extends LyraElement {
       >
         <slot>${this.label}</slot>
       </div>
+      <div part="status" class="sr-only" role="status" aria-live="polite">${this.statusText()}</div>
       <input
         part="input"
         type="file"

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

@@ -3,3 +3,5 @@ declare const meta: Meta;
 export default meta;
 type Story = StoryObj;
 export declare const Default: Story;
+export declare const CustomSlotContent: Story;
+export declare const Disabled: Story;

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

@@ -8,3 +8,12 @@ export default meta;
 export const Default = {
     render: () => html `<lyra-file-input multiple accept=".csv,.xlsx"></lyra-file-input>`,
 };
+export const CustomSlotContent = {
+    render: () => html `<lyra-file-input multiple accept=".csv,.xlsx" label="Upload spreadsheets">
+      <strong>Drag spreadsheets here</strong>
+      <span>or click to browse (.csv, .xlsx)</span>
+    </lyra-file-input>`,
+};
+export const Disabled = {
+    render: () => html `<lyra-file-input disabled accept=".csv,.xlsx"></lyra-file-input>`,
+};

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

@@ -1,17 +1,40 @@
 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>;
+/**
+ * Resolves the optional peer dependency `@aceshooting/lyra-flags`'s `flagUrl`
+ * via the given importer (a real dynamic import by default). Uncached and
+ * dependency-injectable — unlike `loadFlagUrlResolver()` below — so the
+ * caught-error warning path is directly testable without needing to
+ * actually uninstall the package.
+ */
+export declare function loadFlagUrl(importFlags?: () => Promise<{
+    flagUrl: FlagUrlResolver;
+}>): Promise<FlagUrlResolver | null>;
 /**
  * `<lyra-flag>` — a country/language flag.
  *
  * Flag images are shipped by the optional peer package `@aceshooting/lyra-flags`,
  * not bundled into lyra-ui itself, so importing the core library pulls zero flag
  * weight. Give it a `country` (ISO 3166-1 alpha-2) or a `language` tag (mapped to
- * a representative country).
+ * a representative country). While that peer package's `flagUrl()` resolves (or
+ * if it isn't installed), the host carries `aria-busy="true"` and a skeleton
+ * placeholder renders in its place.
+ *
+ * **Bundle-size note:** `country`/`language` resolve through the peer package's
+ * `flagUrl(code)`, which is itself genuinely code-split per flag (see that
+ * package's docs) — using `<lyra-flag country="fr">` anywhere in an app ships
+ * only the flags actually requested at runtime, not all 249. If you already
+ * have a flag's URL at build time (e.g. from your own literal
+ * `import frUrl from '@aceshooting/lyra-flags/flags/fr.svg?url'`), pass it as
+ * `src` instead to skip the peer-package round trip (and its loading-skeleton
+ * flash) entirely.
  *
  * @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>
  * @csspart image - The underlying <img>.
  */
 export declare class LyraFlag extends LyraElement {
@@ -20,13 +43,34 @@ export declare class LyraFlag extends LyraElement {
     country?: string;
     /** BCP-47-ish language tag (e.g. `en`, `en-US`) resolved to a country flag. */
     language?: string;
-    /** Accessible label / `alt` text. Defaults to the uppercase code. */
+    /**
+     * A pre-resolved flag image URL — takes precedence over `country`/`language`
+     * and skips the `@aceshooting/lyra-flags` peer-package lookup (and its
+     * loading-skeleton round trip) entirely. See the class doc: mainly useful to
+     * avoid even the small per-flag async hop when you already have the URL at
+     * build time. `label` is effectively required alongside `src` — there's no
+     * `country`/`language` to derive a fallback `alt` from.
+     */
+    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).
+     */
     label?: string;
     /** Render as a circular flag. */
     round: boolean;
-    private src?;
+    private resolvedSrc?;
     /** True while the lazy-loaded `@aceshooting/lyra-flags` peer resolver is in flight. */
     private loading;
+    /**
+     * Bumped on every `willUpdate` pass; captured by each in-flight resolver
+     * `.then()` so a resolution for a `country`/`language` that's since changed
+     * (or been cleared) can recognize itself as stale and no-op instead of
+     * overwriting newer state.
+     */
+    private resolveToken;
     private get code();
     protected willUpdate(changed: PropertyValues<this>): void;
     protected updated(): void;
@@ -37,3 +81,4 @@ declare global {
         'lyra-flag': LyraFlag;
     }
 }
+export {};

package/dist/components/flag/flag.js

@@ -9,31 +9,34 @@ import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { styles } from './flag.styles.js';
-import { languageToCountry } from './language-map.js';
+import { ALPHA2_RE, languageToCountry } from './language-map.js';
 import '../skeleton/skeleton.js';
 /**
- * ISO 3166-1 alpha-2 country code: exactly two letters, case-insensitive.
- * The peer package `@aceshooting/lyra-flags` naively interpolates its `code`
- * argument into a `new URL('./flags/${code}.svg', ...)` with no validation
- * of its own — an unvalidated `country` containing `../` segments (e.g.
- * `../../etc`) can escape the intended flags/ directory. Anything that
- * doesn't match this shape is treated the same as an unknown/missing flag.
+ * Resolves the optional peer dependency `@aceshooting/lyra-flags`'s `flagUrl`
+ * via the given importer (a real dynamic import by default). Uncached and
+ * dependency-injectable — unlike `loadFlagUrlResolver()` below — so the
+ * caught-error warning path is directly testable without needing to
+ * actually uninstall the package.
  */
-const COUNTRY_CODE_RE = /^[a-z]{2}$/i;
+export async function loadFlagUrl(importFlags = () => import('@aceshooting/lyra-flags')) {
+    try {
+        return (await importFlags()).flagUrl;
+    }
+    catch {
+        console.warn("<lyra-flag> needs the optional peer dependency '@aceshooting/lyra-flags' to render " +
+            'flag images — install it with `pnpm add @aceshooting/lyra-flags`.');
+        return null;
+    }
+}
 let flagUrlResolver;
 /**
  * Lazily loads the optional peer dependency '@aceshooting/lyra-flags' once per
- * page. Resolves to `null` (with a one-time warning) if it isn't installed.
+ * page. Resolves to `null` (with a one-time warning, see `loadFlagUrl()`) if
+ * it isn't installed.
  */
 function loadFlagUrlResolver() {
     if (!flagUrlResolver) {
-        flagUrlResolver = import('@aceshooting/lyra-flags')
-            .then((mod) => mod.flagUrl)
-            .catch(() => {
-            console.warn("<lyra-flag> needs the optional peer dependency '@aceshooting/lyra-flags' to render " +
-                'flag images — install it with `pnpm add @aceshooting/lyra-flags`.');
-            return null;
-        });
+        flagUrlResolver = loadFlagUrl();
     }
     return flagUrlResolver;
 }
@@ -43,11 +46,23 @@ function loadFlagUrlResolver() {
  * Flag images are shipped by the optional peer package `@aceshooting/lyra-flags`,
  * not bundled into lyra-ui itself, so importing the core library pulls zero flag
  * weight. Give it a `country` (ISO 3166-1 alpha-2) or a `language` tag (mapped to
- * a representative country).
+ * a representative country). While that peer package's `flagUrl()` resolves (or
+ * if it isn't installed), the host carries `aria-busy="true"` and a skeleton
+ * placeholder renders in its place.
+ *
+ * **Bundle-size note:** `country`/`language` resolve through the peer package's
+ * `flagUrl(code)`, which is itself genuinely code-split per flag (see that
+ * package's docs) — using `<lyra-flag country="fr">` anywhere in an app ships
+ * only the flags actually requested at runtime, not all 249. If you already
+ * have a flag's URL at build time (e.g. from your own literal
+ * `import frUrl from '@aceshooting/lyra-flags/flags/fr.svg?url'`), pass it as
+ * `src` instead to skip the peer-package round trip (and its loading-skeleton
+ * flash) entirely.
  *
  * @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>
  * @csspart image - The underlying <img>.
  */
 export class LyraFlag extends LyraElement {
@@ -57,11 +72,18 @@ export class LyraFlag extends LyraElement {
         this.round = false;
         /** True while the lazy-loaded `@aceshooting/lyra-flags` peer resolver is in flight. */
         this.loading = true;
+        /**
+         * Bumped on every `willUpdate` pass; captured by each in-flight resolver
+         * `.then()` so a resolution for a `country`/`language` that's since changed
+         * (or been cleared) can recognize itself as stale and no-op instead of
+         * overwriting newer state.
+         */
+        this.resolveToken = 0;
     }
     static { this.styles = [LyraElement.styles, styles]; }
     get code() {
         if (this.country) {
-            return COUNTRY_CODE_RE.test(this.country) ? this.country.toLowerCase() : undefined;
+            return ALPHA2_RE.test(this.country) ? this.country.toLowerCase() : undefined;
         }
         if (this.language)
             return languageToCountry(this.language);
@@ -69,22 +91,32 @@ export class LyraFlag extends LyraElement {
     }
     willUpdate(changed) {
         // `this.hasUpdated` (not just `changed`) forces this body to run once on
-        // the very first update even when neither `country` nor `language` is
+        // the very first update even when none of `country`/`language`/`src` is
         // ever set: an unset optional property's first "assignment" is
-        // undefined -> undefined (no-op to Lit), so `changed.has('country')`
-        // would otherwise never become true for a `<lyra-flag>` that never
-        // receives a code, leaving `loading` stuck at its initial `true` forever.
-        if (this.hasUpdated && !changed.has('country') && !changed.has('language'))
+        // undefined -> undefined (no-op to Lit), so none of `changed.has(...)`
+        // would otherwise ever become true for a `<lyra-flag>` that never
+        // receives one, leaving `loading` stuck at its initial `true` forever.
+        if (this.hasUpdated && !changed.has('country') && !changed.has('language') && !changed.has('src'))
+            return;
+        const token = ++this.resolveToken; // invalidates any in-flight peer resolution either way
+        if (this.src) {
+            this.resolvedSrc = undefined;
+            this.loading = false;
             return;
+        }
         const code = this.code;
         if (!code) {
-            this.src = undefined;
+            this.resolvedSrc = undefined;
             this.loading = false;
             return;
         }
         this.loading = true;
-        void loadFlagUrlResolver().then((resolve) => {
-            this.src = resolve?.(code);
+        void loadFlagUrlResolver()
+            .then((resolve) => resolve?.(code))
+            .then((url) => {
+            if (token !== this.resolveToken)
+                return; // superseded by a later country/language/src change
+            this.resolvedSrc = url;
             this.loading = false;
         });
     }
@@ -97,10 +129,11 @@ export class LyraFlag extends LyraElement {
     render() {
         if (this.loading)
             return html `<lyra-skeleton variant="rect"></lyra-skeleton>`;
-        if (!this.src)
+        const url = this.src ?? this.resolvedSrc;
+        if (!url)
             return html ``;
         const alt = this.label ?? (this.code ?? '').toUpperCase();
-        return html `<img part="image" src=${this.src} alt=${alt} loading="lazy" decoding="async" />`;
+        return html `<img part="image" src=${url} alt=${alt} loading="lazy" decoding="async" />`;
     }
 }
 __decorate([
@@ -109,6 +142,9 @@ __decorate([
 __decorate([
     property()
 ], LyraFlag.prototype, "language", void 0);
+__decorate([
+    property()
+], LyraFlag.prototype, "src", void 0);
 __decorate([
     property()
 ], LyraFlag.prototype, "label", void 0);
@@ -117,7 +153,7 @@ __decorate([
 ], LyraFlag.prototype, "round", void 0);
 __decorate([
     state()
-], LyraFlag.prototype, "src", void 0);
+], LyraFlag.prototype, "resolvedSrc", void 0);
 __decorate([
     state()
 ], LyraFlag.prototype, "loading", void 0);

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

@@ -12,7 +12,7 @@ export const styles = css `
     block-size: 100%;
     inline-size: 100%;
     border-radius: var(--lyra-flag-radius, 2px);
-    box-shadow: 0 0 0 1px rgb(0 0 0 / 0.08) inset;
+    box-shadow: 0 0 0 1px var(--lyra-color-border) inset;
     object-fit: cover;
   }
   :host([round]) {