import{type TemplateResult,type PropertyValues}from'lit';import{LyraElement}from'../../../internal/lyra-element.js';import'../../overlays/skeleton/skeleton.class.js';export type LyraFlagFidelity='compact'|'standard'|'detailed';export type LyraFlagShape='rect'|'circle';export type LyraFlagUrlResolver=(code:string,options?:{variant?:LyraFlagFidelity;})=>Promise<string|undefined>;
/**
* Resolves the optional peer dependency `@aceshooting/lyra-flags`'s `flagUrl`
* via the given importer. 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<unknown>):Promise<LyraFlagUrlResolver|null>;
/**
* Resolves `@aceshooting/lyra-flags`'s `createFlagUrlResolver` via the given importer and calls
* it once, the bulk-resolution twin of `loadFlagUrl()` above. Backs `flag-peer-bulk.js` — the
* opt-in alternative to `flag-peer.js` for a page that renders most/all flags at once, where one
* shared `flagUrls()` fetch beats resolving every `<lr-flag>` instance independently. Same
* dependency-injectable, uncached shape as `loadFlagUrl()`, for the same testability reason.
*/
export declare function loadBulkFlagUrl(importFlags:()=>Promise<unknown>):Promise<LyraFlagUrlResolver|null>;
/** Install an optional flag resolver supplied by a peer-registration entry. */
export declare function setFlagUrlResolver(value:LyraFlagUrlResolver|Promise<LyraFlagUrlResolver|null> |null):void;
/**
* `<lr-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). While that peer package's `flagUrl()` resolves,
* the host carries `aria-busy="true"`; a decorative skeleton and ordinary, non-live localized
* loading text render in its place. A missing or failed peer resolver fails closed with a localized visible error and a
* shared light-DOM assertive announcement, plus a one-time `console.warn` naming the code and the
* `flag-peer.js` import that registers a resolver -- the visible error alone cannot tell a
* developer that the fix is a missing import rather than missing flag data;
* an installed resolver returning no URL for an unknown code remains a valid
* empty result.
*
* **Bundle-size note:** `country`/`language` resolve through the peer package's
* `flagUrl(code)`, which lazily fetches one requested flag at runtime. A
* bundler may still emit the complete reachable lazy-chunk graph; use a
* literal asset subpath import when the deployment artifact must be pruned.
* If every `<lr-flag>` in your app is pinned to the same `fidelity` (no
* per-instance switching), register `@aceshooting/lyra-flags/standard`/`/compact`/`/detailed` with
* `setFlagUrlResolver()` instead of importing `flag-peer.js` (which always registers the full
* three-tier resolver) — the tier-specific entry excludes the other two tiers' generated loader
* maps from the reachable graph; see that package's README for the exact shape.
* 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.
*
* **Rendering many flags at once** (a country table, a picker listing every locale): resolve every
* code up front with `@aceshooting/lyra-flags`'s `flagUrls()` (one call, returns `{code: url}` for
* all 249 flags) and pass results through `src`, instead of letting each `<lr-flag>` instance
* independently call `flagUrl()` — this skips one peer-resolution round trip per instance. Image
* fetches themselves are unaffected either way (each flag is a distinct asset; there is no sprite).
* Or import `flag-peer-bulk.js` instead of `flag-peer.js` (never both) to get this automatically,
* registering a resolver backed by one shared `flagUrls()` call — worthwhile only when the page
* renders most/all flags; a page with a handful pays an unneeded 249-entry fetch.
* When that page ALSO leaves every `<lr-flag>` on the default `fidelity="standard"`, import
* `flag-peer-bulk-standard.js` instead: it registers the same bulk resolver through the peer
* package's tier-committed `@aceshooting/lyra-flags/standard` entry, so the detailed and compact
* tiers' lazy-chunk graphs never become reachable (measured at +15.8MB of emitted assets on a real
* production build with a 156-country flag column). It is committed to one tier, so
* `fidelity="compact"/"detailed"` on an individual element resolves to that code's standard asset
* — a silent no-op, not an error; use `flag-peer-bulk.js` when per-instance fidelity must be
* honoured.
*
* **Sizing:** the host has no intrinsic `width` — it sizes from `font-size` (`block-size: 1em`,
* `inline-size` derived from `--lr-flag-aspect-ratio` via CSS `aspect-ratio`), so `<lr-flag>` scales
* naturally with surrounding text (e.g. `style="font-size: 2rem"`). Do not set `width`/`inline-size`
* directly: making both axes definite defeats `aspect-ratio` (which only participates when at most
* one axis is definite per the CSS sizing spec), squashing the image instead of scaling it.
*
* The ~65 flags whose design includes a detailed coat of arms/seal/emblem (e.g. `es`, `pt`) ship
* three fidelity tiers; choose one with `fidelity`: `"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 `fidelity`'s own
* doc.
*
* @customElement lr-flag
* @example <lr-flag country="fr"></lr-flag>
* @example <lr-flag language="en" label="English"></lr-flag>
* @example <lr-flag src=${frUrl} label="French"></lr-flag>
* @example <lr-flag country="es" fidelity="compact"></lr-flag>
* @example <lr-flag country="es" fidelity="detailed" shape="circle"></lr-flag>
* @csspart image - The underlying <img>.
* @slot fallback - Rendered in place of the flag when `country`/`language` cannot resolve to a
*   current flag (an unassigned, historical, or malformed code). Wins over the `fallback` property.
*   Distinct from the peer-resolver failure that produces `[part="error"]`: an unresolvable code is
*   data, not a defect.
* @csspart fallback-image - The `fallback` property's placeholder image, when no `fallback` slot
*   content is supplied. It uses the same frame sizing, object fit, and shape clipping as `image`.
* @csspart error - Ordinary localized visible error rendered when the optional peer resolver is
*   unavailable or fails; each fresh resolution failure appends the same localized message to the
*   shared light-DOM assertive announcement sink.
* @cssprop [--lr-flag-aspect-ratio=4 / 3] - Rectangular flag aspect ratio.
* @cssprop [--lr-flag-object-fit=cover] - How the image fits its flag frame.
* @cssprop --lr-flag-radius - Rectangular flag corner radius.
* @status stable
* @since 4.0.0
*/
export declare class LyraFlag extends LyraElement{static styles:import("lit").CSSResultGroup[];
/** ISO 3166-1 alpha-2 country code (e.g. `fr`, `us`). Takes precedence over `language`. */
country?:string;
/**
* Placeholder image URL rendered in place of a flag when the code cannot resolve — a historical
* or defunct state in a longitudinal dataset, say. Unset renders the `fallback` slot's content
* instead, or nothing at all, so the element still occupies its normal footprint in a table or
* card grid rather than showing error wording.
*/
fallback?:string;
/** BCP-47-ish language tag (e.g. `en`, `en-US`) resolved to a country flag. */
language?:string;
/**
* 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 used when `aria-label` is unset. 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;private _shape;
/** Flag crop geometry. Invalid runtime values normalize to `rect`. */
get shape():LyraFlagShape;set shape(value:LyraFlagShape);
/**
* 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.
*/
private _fidelity;get fidelity():LyraFlagFidelity;set fidelity(value:LyraFlagFidelity);
/** The normalized tier sent to the optional peer resolver. */
private get effectiveFidelity();private sourceState;private resolverGeneration;private errorAnnouncementSink?;private sourceRestartPending;private activeSourceRequest;
/**
* 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 readonly onResolverGeneration;
/** True while the effective source is resolving or its native image is loading. */
get loading():boolean;private get code();
/**
* True when the component has a `country`/`language` to resolve but no flag can be produced for
* it — an unassigned, historical, or malformed code. Distinct from the peer-resolver failure that
* drives `data-error`: a dissolved federation in a longitudinal dataset is *data*, not a bug, and
* a consumer needs to style the two apart.
*/
private get unresolved();connectedCallback():void;disconnectedCallback():void;adoptedCallback():void;private syncErrorAnnouncementSink;private releaseErrorAnnouncementSink;private announceLoadError;private setSourceState;private failSource;private onImageLoad;private onImageError;protected willUpdate(changed:PropertyValues):void;protected updated(changed:PropertyValues):void;render():TemplateResult;}declare global{interface HTMLElementTagNameMap{'lr-flag':LyraFlag;}}