` children. The library's own `slot`/`label` panel-attribute shape was **removed in 9.0.0** — rewrite each former `` child as one `` plus one ``, and fold each former `slot=\"x-icon\"` sibling's content into that ``'s own default slot (mark a decorative glyph `aria-hidden`, since the tab derives its accessible name from that content). A leftover `slot`/`label` child is skipped silently: the strip renders empty. |\n| `` | `` | |\n\nNeither old name is registered as an alias. A tag that silently keeps working under its old name is\nhow a rename looks finished while half of it is inert.\n\n### Component contract moves and default changes\n\nTwo existing tags now carry the mapped contract their names promise. Rename the old behavior when\nthat is what the application needs:\n\n| 7.x behavior | 8.0.0 destination | What the old tag means now |\n| ------------------------------------------------ | ------------------------ | -------------------------------------------------------------------------------- |\n| Browser-native `` | `` | `` is the locale-aware segmented field and popup. |\n| Slotted/image `` pan and zoom | `` | `` is a sandboxed iframe preview with discrete zoom controls. |\n\nThe following changes do not require a tag rename, but code that relied on the former default or\nexact TypeScript/event shape needs an explicit update:\n\n- `.value` is typed `string | string[]`; `multiple` opts into the array-valued runtime\n mode. Narrow the value after checking `multiple` rather than assuming a string.\n- A bare `` now uses `appearance=\"accent\"`. Write `appearance=\"filled\"` to preserve the\n former visual tier.\n- `` no longer adds a reveal button unless `password-toggle` is present,\n and `` leaves native spin buttons visible unless `without-spin-buttons`\n (or `no-spin-buttons`) is present.\n- `` now defaults `page-size` to `10`, not `20`; its page-change detail also includes\n `pageSize`, and the cancelable `lr-before-page-change` precedes it.\n- `` defaults to `effect=\"none\"`, not `pulse`; `` defaults\n `child-list` to false, not true.\n- `` and `` default an unset date to the construction-time current\n instant. `` uses decimal `unit-step=\"1000\"`; write `1024` to retain the former\n scaling.\n- `` emits cancelable `lr-show`/`lr-hide` before state changes and settles the new\n after-events after motion. `` replaces `delay` with independent `show-delay` and\n `hide-delay`.\n- Slider input/change details now include the active thumb and full value/range context. Readers of\n `detail.value` continue to work; exact one-key object assertions must accept the wider shape.\n\nThe component-family reference documents every aligned default beside the affected property. The\ncontract-aware migration report identifies upstream-origin rewrites; the separate `lyra-v7`\nprofile described below makes the former popup/popover/tooltip defaults explicit.\n\nThe exact registration imports for the new and moved surfaces are:\n\n```js\nimport \"@aceshooting/lyra-ui/components/lr-page.js\";\nimport \"@aceshooting/lyra-ui/components/lr-video.js\";\nimport \"@aceshooting/lyra-ui/components/lr-video-playlist.js\";\nimport \"@aceshooting/lyra-ui/components/lr-native-time-input.js\";\nimport \"@aceshooting/lyra-ui/components/lr-pan-zoom.js\";\n```\n\n### Attribute and property renames\n\nEach row is a mechanical rewrite in your own markup or CSS. Three of them also change what happens\nwhen the attribute is _absent_, so grep for the tag as well as for the old attribute.\n\n| 7.x | 8.0.0 | What to check |\n| -------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `` | `` | Polarity un-inverted, so the default flips: a backdrop click no longer dismisses a dialog unless you opt in. `` inherits this. |\n| `` | `` | Same flip: the localized \"showing X–Y of Z\" row is now opt-in. |\n| `` | `` | Leaving `total` unset renders the empty state, so a missed rename is visible rather than silent. |\n| `` | `` | |\n| `` | default `start` → `end` | A drawer with no `placement` now enters from the logical end edge; write `placement=\"start\"` to keep the old side. |\n| `` `::part(fill)` | `::part(indicator)` | Rename the selector in your own CSS; the old part name matches nothing and fails silently. |\n| `` | `` | The deprecated boolean is gone. |\n| ``, `` | `bytes` | These were byte counts wearing the name of the size ladder. |\n| `` / `min-size` / `max-size` | `extent` / `min-extent` / `max-extent` | Same reason: a CSS length along the docked axis, not a size step. |\n\n``'s `with-clear` is no longer marked deprecated. Both upstream spellings of the clear\nbutton — `with-clear` and `clearable` — are now first-class on ``, `` and\n`` alike, so there is nothing to rewrite in either direction.\n\n### Security-preserving differences\n\nSome upstream behavior is intentionally not made automatic:\n\n- `` sanitizes every fetched or same-page fragment, has no script-executing mode, and\n defaults `mode` to `same-origin` instead of `cors`. A migration that depends on cross-origin or\n script execution remains unchanged with a location-aware warning. Its post-sanitization\n transclusion is network-silent and non-interactive: anchors remain only for resolvable\n same-document `#fragment` links (rebased per include instance); every other navigation or\n resource attribute, including `href`, `src`, `srcset`, `action`, `ping`, and `poster`, is stripped,\n so images do not load. Form-control and custom-element wrappers are unwrapped to safe ordinary\n text or children, while controls with no passive content are removed.\n- Link-like Lyra controls always contribute `noopener noreferrer` to `rel` whenever `target` is set,\n and always strip `opener`. Author `rel` tokens are merged rather than ignored, so `nofollow`, `me`\n and `license` survive the rename — `` and `` therefore migrate\n automatically as of 9.0.0. `` still derives `rel` from `target` alone.\n- `` rejects active/non-embeddable URL schemes, always renders a sandbox, and\n will not combine `allow-scripts` with `allow-same-origin`. `` validates media and\n thumbnail URLs and byte-caps remote thumbnail VTT input.\n\nThese are deliberate fail-closed contracts. The migration report records them instead of emitting\nmarkup that appears converted while weakening the application's security boundary.\n\n### One styling vocabulary\n\n`variant`, `tone` and `kind` used to mean the same thing on different components, and `appearance`\nmeant two unrelated things. There is now one name per concept, library-wide.\n\n- **`tone` → `variant`** on ``, ``, `` and ``,\n and on ``'s entry objects — along with its `tone-dot*` CSS parts, now\n `variant-dot*`. No alias for any of them.\n- **`appearance=\"card|plain\"` → `frame=\"card|plain\"`** on the thirteen container components that had\n it (``, ``, ``, ``, ``,\n ``, ``, ``, ``,\n ``, ``, ``, ``).\n `appearance` now means how a control fills itself and nothing else:\n `accent | filled | outlined | filled-outlined | plain`.\n- **``'s default `appearance` is now `accent`**, and `filled` is a genuinely quieter tier.\n The two used to render identically for every variant except neutral.\n- **`size` accepts both ladders everywhere** — this library's `2xs|xs|s|m|l|xl` and the upstream\n `small|medium|large` — so a migrated `size=\"small\"` needs no rewrite.\n- **``, `` and `` are no longer unconditionally pill-shaped.** They\n default to a rounded rectangle; add `pill` for the old fully-rounded ends.\n\n### Tokens and theming\n\n- **`theme.css` now declares cascade layers**: `@layer lr-base, lr-theme, lr-utilities, lr-overrides`,\n with the tokens in `lr-theme`. Any _unlayered_ declaration of yours now beats every Lyra one\n regardless of specificity or load order, so a plain `:root { --lr-theme-… }` override always wins\n with no `!important`. If you already wrap your overrides in your own `@layer`, they now sort\n relative to `lr-theme` rather than losing to an unlayered `:root` — name your layer in an\n `@layer` statement after importing `theme.css`, or move those rules out of a layer entirely.\n- **`--lr-font-size-md` is removed**; use `--lr-font-size-m`. The two were the same value under two\n names, which is why `` rendered `size=\"m\"` and `size=\"l\"` at identical text sizes.\n- **Compound motion tokens are split into duration and easing** (`--lr-duration-*` +\n `--lr-easing-*`). The compound `--lr-transition-*` tokens still resolve, composed from the two.\n- **Shadows are five tiered steps** (`--lr-shadow-xs` … `--lr-shadow-xl`), declared per mode with\n much heavier dark-mode alphas, because a single near-black step against a near-black surface is not\n a luminance difference at all. `--lr-shadow` still resolves (to the `m` step) and a theme that set\n `--lr-theme-shadow-color` keeps working; a theme that overrode `--lr-shadow` directly should move to\n the step it meant.\n- **Hover and press are a color mix, not `filter: brightness()`** — tune them library-wide with\n `--lr-color-mix-hover` / `--lr-color-mix-active` against `--lr-color-mix-partner`.\n `--lr-hover-brightness` still resolves but no component reads it.\n- **New `--lr-color-surface-overlay`** for modal panels (the page surface in light mode, lighter than\n the page in dark), a **new `--lr-terminal-bg-*` set** for ANSI background colors, and a new\n `--lr-form-control-*` tier (`height`, `font-size`, `padding-inline`, `padding-block`, `gap`,\n `radius`) — one ladder shared by every control, retuned per `size` step.\n- Colors moved where the generated ramp put them, including the brand seed. Restoring the old hex\n values by hand would reintroduce the contrast failures the ramp exists to prevent.\n- The value-named `--lr-size-` tokens are unchanged and still resolve, but the family is\n frozen: existing entries may disappear as call sites find a semantic home, and none will be added.\n Don't build new theming on them — reach for `--lr-space-*`, `--lr-radius*`, `--lr-font-size-*` or\n `--lr-form-control-*` instead.\n\n### Localization\n\n**Pluralized messages are now CLDR category objects** selected through `Intl.PluralRules`, replacing\nthe paired `` + `Plural` convention. A catalog passed to `registerLyraLocale()`, or a\nper-instance `.strings`, that used the old pair must be rewritten — with that locale's real\ncategories, which for Russian is four and for Arabic six:\n\n```ts\n// 7.x\nregisterLyraLocale(\"en\", {\n toolCount: \"{count} tool\",\n toolCountPlural: \"{count} tools\",\n});\n\n// 8.0.0\nregisterLyraLocale(\"en\", {\n toolCount: { one: \"{count} tool\", other: \"{count} tools\" },\n});\n```\n\nTen translation catalogs now ship as side-effect-only modules, so a common locale no longer needs a\nhand-written catalog at all:\n\n```js\nimport \"@aceshooting/lyra-ui/translations/fr.js\"; // also ar, de, es, fa, he, ja, pt-BR, ru, zh-CN\n```\n\n`fa` and `he` are complete RTL catalogs. Locale lookup applies the normal regional fallback, so\n`fa-IR` resolves through `fa` and `he-IL` through `he`; set `dir=\"rtl\"` on the document or an\nancestor so layout and directional keyboard behavior follow the chosen language.\n\n### Packaging\n\n- **`@aceshooting/lyra-ui/internal/*` is no longer a published subpath.** The supported helpers moved\n to `@aceshooting/lyra-ui/utilities/*` (one module per helper, or the whole set from\n `@aceshooting/lyra-ui/utilities`), which now also carries `FormAssociated` and `groupByRecency` —\n previously reachable only through the side-effectful root barrel. Rewrite\n `@aceshooting/lyra-ui/internal/positioner.js` as `@aceshooting/lyra-ui/utilities/positioner.js`,\n and likewise for `a11y`, `announcer`, `icons`, `layered-layout`, `lyra-element`,\n `overlay-manager`, `prefix` and `scroll-lock`. Anything else that lived under `internal/` was never\n a public API and has no replacement subpath.\n\n## Migrating from Web Awesome or Shoelace\n\nThe \"Mirrors\" column records a design/API relationship, not blanket permission to rename a tag.\nEvery pinned Web Awesome and Shoelace component has a machine-readable migration classification:\n`exact`, `rewritten`, `warning-required`, `conceptual-only`, or `unsupported`. Only `exact` and fully\nspecified `rewritten` mappings are changed automatically. The other three remain untouched and are\nreported with their source location, so an incomplete migration cannot leave inert public members\nbehind while appearing to have succeeded.\n\nWhere the two upstreams disagree on a name for the same thing, Lyra accepts both spellings rather\nthan forcing a rewrite. The clear button is the clearest case: Web Awesome spells it `with-clear`,\nShoelace spells it `clearable`, and ``, `` and `` each honour both.\nNeither spelling is deprecated, and neither needs rewriting in either direction — whichever one your\nmarkup already carries keeps working.\n\nThe same compatibility rule applies when the upstreams disagree on a property's write type.\n`lr-input.autocorrect` and `lr-textarea.autocorrect` always read as booleans, matching Web Awesome.\nInput also accepts Shoelace's `'off'`/`'on'` property writes; Textarea accepts its wider string\nsurface, normalizing `'off'`/`'false'` to `false` and other strings to `true`. Both render the native\nattribute canonically as `autocorrect=\"off\"` or `autocorrect=\"on\"`.\n\nIcon tags and attributes can be renamed mechanically, but icon names are a separate vocabulary.\nLyra's dependency-free default library contains only `add`, `check`, `close`, `search`, `menu`,\n`chevron-left`, `chevron-right`, `chevron-down`, `calendar`, `command`, and `trash`; any other\nmigrated ``, ``, or `` name renders no glyph. The migration CLI\nreports `BEHAVIOR_REVIEW_REQUIRED` for those tags. Replace each name explicitly or register the\nrequired vocabulary with `registerIconLibrary('default', { resolver })`.\n\n`lr-option` likewise keeps live/default selection separate: the `selected` attribute initializes\n`defaultSelected` and the parent control's reset default (property writes intentionally do not\nreflect), while `selected` is property-only live state. Selecting an option at runtime never\nrewrites the declarative default.\n\n```html\n\n \n\n\n\n\n \n\n```\n\n**Automating the safe subset.** The package ships the version-matched `lyra-ui-migrate` CLI. It\nreads a compact packaged projection of the validated component inventory, applies only\ncontract-recorded tag/member/default/registration-import rewrites, and can write a stable JSON\nreport for CI or human review. Replace `` with the exact Lyra version you are migrating to:\n\n```bash\nnpx --package @aceshooting/lyra-ui@ lyra-ui-migrate --check \\\n --report=migration.json path/to/your/src\nnpx --package @aceshooting/lyra-ui@ lyra-ui-migrate path/to/your/src\n```\n\nThe supported package identities are `@awesome.me/webawesome` and `@awesome.me/webawesome-pro`\nfor Web Awesome, plus `@shoelace-style/shoelace`. Directory targets include HTML, standalone CSS,\nJavaScript, TypeScript, JSX, Vue, Svelte, MDX, and Markdown files.\n\nThe report records file, line, column, migration origin, tag/member, action, target, and warning code.\nSupported side-effect component deep imports are routed through the target's inventory registration\nmodule. Proven, tier-compatible root registration closures use `@aceshooting/lyra-ui/all.js`;\nroot-excluded targets receive granular registration imports instead. An automatic-looking tag with\nno matching side-effect registration in the scanned target set stays unchanged with\n`REGISTRATION_CLOSURE_REQUIRED`; include the registration-owning entry file in the scan rather than\naccepting an inert `lr-*` result. A mapped target with optional runtime dependencies adds an\n`OPTIONAL_PEER_REQUIRED` entry naming every package the consumer must install. Imports with\nbindings, unknown subpaths, dynamic values, aliased component values that use a rewritten member,\nunsafe security/default changes, conceptual mappings, and unsupported components remain unchanged\nwith an actionable warning. An aliased member blocks that mapping across the whole scanned target set\nso the codemod never rewrites its registration import while leaving an old member behind. A second\nrun is byte-idempotent. Comments, prose, unrelated identifiers/packages, and partial strings are not\ntreated as component uses. `--check` never writes files and exits nonzero while a rewrite or warning\nremains.\n\n**Preserving Lyra 7 overlay defaults.** This is a separate, opt-in profile; the default command\nabove continues to scan only Web Awesome and Shoelace uses. Run it first in dry-run mode:\n\n```bash\nnpx --package @aceshooting/lyra-ui@ lyra-ui-migrate --origin=lyra-v7 --dry-run \\\n --report=lyra-v7-migration.json path/to/your/src\n```\n\nThe profile never renames an `lr-*` tag or import. It inserts attributes only when absent:\n\n| Component | Lyra 7 behavior made explicit |\n| -------------- | ------------------------------------------------------------------------------- |\n| `` | `strategy=\"fixed\"`, `placement=\"bottom-start\"`, `distance=\"4\"`, `flip`, `shift` |\n| `` | `placement=\"bottom-start\"`, `distance=\"4\"`, `without-arrow` |\n| `` | `distance=\"6\"`, `without-arrow` |\n\nBoolean `true` is emitted as canonical attribute presence; the positive inverse\n`without-arrow` is used instead of serializing `arrow=\"false\"`. Existing explicit values are\nuntouched. An opaque framework attribute spread or DOM alias blocks that component profile across\nthe scanned target set with a location-aware warning, so the tool cannot silently insert a default\nbeside a value it cannot see. Review or expand the dynamic value, rerun, then apply without\n`--dry-run`; a final run should report no changes.\n\nThe inventory does not treat `dir` or `lang` as component-member drift: both are platform-global\nHTML passthrough attributes. It likewise excludes Web Awesome's `did-ssr` hydration marker, which is\nupstream runtime bookkeeping rather than an authored member to copy onto a Lyra component.\n\nThe same inventory reviews accessibility behavior separately from static API shape. Every one of\nthe 145 pinned upstream mappings names an upstream and Lyra behavior profile covering semantics,\nnaming, keyboard, focus, state, announcements, and motion. It stores the exact missing/additive\ncomparison and a rationale; an automatic mapping is rejected if its target profile drops a reviewed\nbehavior. These profiles summarize published public contracts and Lyra's authored contract plus\nautomated tests. They are not evidence of manual screen-reader, assistive-technology, or human\naccessibility review; see [the accessibility evidence statement](../../docs/accessibility.md).\n\nShoelace is now a historical predecessor to Web Awesome, but its component vocabulary remains\nfamiliar to many teams. The table below is a porting guide, not an automatic-rename allowlist; the\ninventory classification and codemod report decide which individual uses are mechanically safe:\n\n| Shoelace | Lyra | Migration note |\n| ------------------------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `` | `` | Check `variant`, `appearance`, and loading behavior. |\n| `` / `` | `` / `` | String `autocorrect` property writes remain accepted but read back as booleans; preserve the native editing/form contract and review label/error markup. |\n| `` / `` | `` / `` | `defaultSelected`/the `selected` attribute is the reset default; live `selected` is property-only. Review option and value events. |\n| `` / `` | `` / `` | Review close reasons, focus behavior, and slots. |\n| `` / `` | `` / `` | Review appearance tokens and dismiss events. |\n| `` | `` | Closed by default, with the same properties, slots, lifecycle, parts, and identity-preserving `toast()` contract under the `lr-` prefix. |\n| `` / `` | `` / `` | Built-in status copy is localized through Lyra's runtime. |\n\nFor either migration, start with the codemod report. Update a package import or custom-element prefix\nonly for an automatic row, or after completing the manual port named by a warning; then run the\ncomponent's accessibility story and check its API notes for behavior that cannot be inferred from\nthe tag name alone. Lyra's own `--lr-theme-*` variables are the only theme inputs it reads. For a\nstaged Web Awesome migration, map existing values explicitly in application CSS; Lyra does not read\ncompetitor token variables itself.\n\nEverything else in the tables below — marked `— (extra)` — has no Web Awesome equivalent to\nmigrate _from_ in the first place, so there's nothing to rename: install the package and import\nwhat you need (see Usage above). That's most of this library, including every dashboard atom\n(stat cards, gauges, empty/skeleton states), the whole chart family, the temporal/graph/tree\ncomponents, ``, and the entire **Conversation & Agent UI** family (chat messages,\nstreaming text, tool-call chips/dialogs, citations, model/settings pickers, and more) — Web\nAwesome has no chat/agent UI component family at all.\n\n## Theming, internationalization & RTL\n\nEvery component is built on the same three guarantees, verified across the whole library rather\nthan opt-in per component:\n\n**Theming.** Components read independent `--lr-theme-*` variables and standalone defaults. Lyra\ndoes not depend on another library's theme or token namespace. For a ready-made light/dark base\ntheme, import `@aceshooting/lyra-ui/theme.css` once and toggle `.lr-light`/`.lr-dark` (or the\nmatching `data-lr-theme` attribute) on an ancestor:\n\n```css\n@import \"@aceshooting/lyra-ui/theme.css\";\n```\n\nTooling can consume the canonical DTCG interchange document from\n`@aceshooting/lyra-ui/design-tokens.json`. The generated\n`@aceshooting/lyra-ui/design-tokens.css` entry supplies explicit light/dark fixture selectors for\npreviews and design-tool validation; it is not a replacement for the production `theme.css`.\n\n```html\n\n Save\n\n```\n\n**The resolved `--lr-color-*`/`--lr-space-*`/`--lr-radius`/`--lr-shadow-*`/`--lr-font-*` output\nlayer is declared only on each `lr-*` element's own shadow `:host`** — it is not readable from\nplain application CSS or your own custom elements outside any `lr-*` shadow root (a rule like\n`body { color: var(--lr-color-text) }` silently resolves to nothing, not an error). Set the\n`--lr-theme-*` **input** layer shown below to retheme; see\n[Where an override actually reaches](./llms/shared.md#where-an-override-actually-reaches) for\nexactly how far each layer inherits.\n\nApplications can override any `--lr-theme-*` input directly:\n\n```css\n:root {\n --lr-theme-color-surface-default: #101827;\n --lr-theme-color-text-normal: #f8fafc;\n --lr-theme-color-brand-fill-loud: #60a5fa;\n --lr-theme-font-size-m: 1rem;\n --lr-theme-border-radius-m: 0.5rem;\n}\n```\n\n`theme.css` declares `@layer lr-base, lr-theme, lr-utilities, lr-overrides` and puts its own tokens\nin `lr-theme`, so an _unlayered_ rule of yours — like the `:root` block above — wins over every Lyra\ndeclaration regardless of specificity or which stylesheet the bundler emitted first. The optional\n`native.css` and `utilities.css` assets use `lr-base` and `lr-utilities`; `lr-overrides` remains\navailable for application rules. See [`llms/tokens.md`](./llms/tokens.md) for the complete shared token list.\nComponent-specific `--lr-*` custom properties remain available for local overrides.\n\nCanvas components automatically repaint after observable theme attributes, stylesheet/link nodes,\nCSSOM changes, adopted stylesheets, and relevant media-query changes. If an application theme engine\nchanges computed tokens through another mechanism, invalidate the owning browser realm explicitly:\n\n```ts\nimport { invalidateLyraTheme } from \"@aceshooting/lyra-ui/utilities/theme.js\";\n\ninvalidateLyraTheme(); // global document realm\ninvalidateLyraTheme(shadowRoot); // realm owning this root, element, or document\n```\n\nThe optional argument selects a realm, not a subtree. Calls are safe during SSR and coalesce into\neach connected canvas consumer's normal redraw schedule.\n\n**Optional light-DOM styles.** Import either bundle independently when an application wants Lyra's\ntoken vocabulary outside component shadow roots:\n\n```css\n@import \"@aceshooting/lyra-ui/native.css\";\n@import \"@aceshooting/lyra-ui/utilities.css\";\n```\n\n`native.css` styles only native descendants of an explicit `.lr-native` scope; it has no root reset\nand does not style the scope marker itself. `utilities.css` provides exact, low-specificity `lr-*`\nclasses for layout, logical sizing, gap/alignment/wrap, prose/text, accessible hiding, FOUCE, and\n`` mobile/desktop allocation helpers. Both are layered, tokenized, RTL-safe, and optional.\nSee [`llms/shared.md`](./llms/shared.md#optional-native-styles-and-css-utilities) for the complete\nclass inventory and override hooks.\n\n**Frontend quality guarantees.** Every component is designed as a native custom element and tested\nfor the contract that applies to its shape: semantic roles and accessible names inside shadow DOM,\nkeyboard navigation, bubbling/composed public events, native form association and validity, logical\nCSS for RTL, narrow-container layouts, reduced motion, and forced-colors behavior. Form controls\nexpose label, hint, error, focus, editing, reset, and validity behavior instead of hiding the useful\nnative contract behind a private input. Heavy integrations such as Chart.js, MapLibre, D3, Shiki,\nMarkdown, phone-number metadata, and flag artwork remain optional peer dependencies.\n\n**Internationalization.** Every built-in string (button labels, status announcements,\n`aria-label`s) resolves through a small runtime, in two ways you can combine:\n\n```ts\nimport {\n registerLyraLocale,\n setLyraLocale,\n} from \"@aceshooting/lyra-ui/localization.js\";\n\n// App-wide: register translations once, anywhere in the app.\nregisterLyraLocale(\"fr\", { close: \"Fermer\", retry: \"Réessayer\" /* ... */ });\nsetLyraLocale(\"fr\"); // or just set /an ancestor `lang` — components pick it up\n```\n\nThe dedicated `localization.js` entry is side-effect-free: it does not register the component\ngraph. The package root continues to re-export the same runtime for compatibility, but importing\nthe root remains registration-free in v8.\n\n```html\n\n\n```\n\nNo rebuild, no per-locale bundle, no per-component API to learn — register the strings once and\nevery component that uses that key picks it up reactively, including ones added after your app's\nfirst render.\n\nLyra's default messages are English fallbacks, while applications own the translated catalog. Date,\nnumber, byte, relative-time, and calendar formatting use the browser's `Intl` APIs and the resolved\nlocale. Consumer-provided labels, values, file names, and message content are never altered by the\nlocalization layer. The same runtime also covers accessible names, descriptions, validation messages,\nlive-region announcements, empty states, status labels, and action buttons; use `.strings` for a\ncomponent-specific override when needed.\n\n**RTL.** Set `dir=\"rtl\"` on `` or any ancestor — every component mirrors its layout\nautomatically via CSS logical properties and swaps directional keyboard navigation (e.g. the arrow\nkeys in a date grid or a roving-tabindex list) to match. `lang`/`locale` select translations and\n`Intl` data but do not silently change writing direction; pair `lang=\"ar\"`, `lang=\"he\"`, or\n`lang=\"fa\"` with `dir=\"rtl\"`. Components do not force their own `dir`, so they remain composable\ninside mixed-direction layouts.\n\n## Component status, versioning, and deprecation\n\nEvery component carries an explicit `stable` or `experimental` status plus the earliest published\n`since` version in the manifest and generated reference. Stable components are production-ready.\nExperimental components remain open to design review, but once published their public APIs receive\nthe same semver protection as stable components; experimental is not permission for a silent minor\nrelease break.\n\nDeprecation is separate metadata. A deprecated component or member names its replacement,\ndeprecation version, rationale, and earliest removal version. If deprecated in major version M, it\nremains available for the complete M+1 line and cannot be removed before M+2. See\n[`llms/shared.md`](./llms/shared.md#component-status-versioning-and-deprecation) for the full policy.\n\n## SSR & Declarative Shadow DOM\n\nEvery Lyra entry point is server-safe under Node 20+ — the package root, `all.js`, the family\nbarrels, and every granular registration module alike. The `@aceshooting/lyra-ui/ssr-loader.js`\nentry installs Lit's hydration hook before registering Lyra (it still pulls the whole `all.js`\nclosure, so it is unaffected by the 8.0.0 root split) and exports the machine-readable\n`LYRA_SSR_SUPPORT_MATRIX`. New integrations that want granular registration can import\n`@aceshooting/lyra-ui/hydration.js` first instead, then their own component modules. The matrix has\ntwo explicit tiers:\n\n- `render-and-hydrate` components emit Declarative Shadow DOM (DSD) and reuse that shadow root and\n its nodes during browser hydration.\n- `client-render` components preserve the host, serializable attributes, and light DOM in the\n server response, then create their shadow DOM when the browser upgrades them. This tier covers\n components whose initial render needs light-DOM traversal, layout, canvas, observers, or media\n APIs that Lit's intentionally small server DOM does not emulate.\n\nConfigure Lit's server renderer with Lyra's fallback before `LitElementRenderer`:\n\n```ts\nimport {\n lyraSsrElementRenderers,\n LYRA_SSR_SUPPORT_MATRIX,\n} from \"@aceshooting/lyra-ui/ssr-loader.js\";\nimport { render, LitElementRenderer } from \"@lit-labs/ssr\";\nimport { collectResult } from \"@lit-labs/ssr/lib/render-result.js\";\nimport { html } from \"lit\";\n\nconst result = render(html`Dashboard`, {\n elementRenderers: lyraSsrElementRenderers(LitElementRenderer),\n});\nconst markup = await collectResult(result);\n```\n\nOn the client, make the loader the first import that can reach Lit; it installs\n`@lit-labs/ssr-client/lit-element-hydrate-support.js` before loading component definitions:\n\n```ts\nimport {\n diagnoseLyraHydration,\n getLyraSsrMode,\n} from \"@aceshooting/lyra-ui/ssr-loader.js\";\n\nconst diagnostics = await diagnoseLyraHydration(document);\n```\n\nRoot-excluded optional-peer families still use their granular registration import after the loader;\nthe loader does not make optional peers eager. Property bindings cannot be serialized by a fallback\nrenderer, so express initial fallback state as attributes/light DOM or assign properties on the\nclient. A `render-and-hydrate` component whose rendering depends on something only a browser can\nanswer — its own light-DOM children, or a browser global such as `EyeDropper` — reproduces the\nserver's answer on the hydrating render and corrects itself on the very next update rather than\ncontradicting the markup it is hydrating, so a slotted override or an eyedropper button appears one\nframe after hydration. A browser-only mount (no server markup) is unaffected and still renders the\nfinal result the first time. Layout measurement, observers, canvas, and media playback start after hydration; remote\ncontent remains client-only. CI renders every inventory tag, verifies both tiers, and crawls a real\nChromium DSD response (including `lr-page`) with strict hydration warnings/errors and DOM-identity\nchecks. The exported matrix is the authoritative per-tag list as components evolve.\n\n## Framework integration (React, Vue, Angular, Svelte)\n\nLyra ships plain custom elements with no framework-specific wrapper package, so the friction is the\nsame friction any custom-element library has with a non-Lit framework, not anything Lyra-specific:\n\nFor tag, property, event, element-ref, and CSS-custom-property types in framework templates, import\nthe matching opt-in declaration entry once in your application's type graph:\n\n```ts\nimport type {} from \"@aceshooting/lyra-ui/custom-elements-jsx\"; // React 19 / JSX\nimport type {} from \"@aceshooting/lyra-ui/vue\";\nimport type {} from \"@aceshooting/lyra-ui/svelte\";\n```\n\nThese entry points are generated from the same Custom Elements Manifest as the editor metadata.\nThey contain types only: they add no runtime wrapper or framework dependency, and they do not\nregister elements. Keep importing the granular registration modules your application uses, for\nexample `import '@aceshooting/lyra-ui/components/lr-input.js'`.\n\n- **Property vs. attribute binding.** A complex-typed property (an object, array, or function — e.g.\n `.strings`, `.selectedRows`, `.markers`) must be bound as a JS _property_, not a stringified\n attribute. Use Vue's `:prop` binding (or the `.prop` modifier), Angular's `[prop]=\"value\"` template\n binding, or a plain property assignment; Svelte's compiler binds to a matching element property\n automatically when one exists, so `prop={value}` mostly just works. A bare `attr=\"value\"` or string\n interpolation only ever sets a string attribute — fine for `variant=\"brand\"`, wrong for anything\n non-string.\n- **Angular needs `CUSTOM_ELEMENTS_SCHEMA`.** Angular's template compiler rejects unknown elements\n and properties by default. Add `schemas: [CUSTOM_ELEMENTS_SCHEMA]` to the module (or standalone\n component) that uses any `` tag so Angular stops trying to resolve it as an Angular\n component.\n- **Custom events need the framework's DOM event-binding syntax, not its component-event\n shorthand.** A framework's usual event shorthand (Vue's `@event` on a _Vue component_, Angular's\n `(event)` output binding) is wired for that framework's own event system; a plain custom element's\n events are native `CustomEvent`s and need the same binding path used for native DOM events —\n `onlr-change={handler}` in React 19, `@lr-change=\"handler\"` in Vue,\n `(lr-change)=\"handler()\"` in Angular, or `onlr-change={handler}` in Svelte 5\n (`on:lr-change={handler}` remains accepted by Svelte's legacy event-directive syntax). Use\n `element.addEventListener('lr-change', handler)` directly when a template binding isn't\n available. Lyra's own event names are consistently kebab-case (`lr-change`, `lr-cell-click`,\n `lr-selection-change`, …) rather than camelCase, specifically to stay friendly to this binding\n path — some other custom-element libraries use camelCase event names, which can silently fail to\n bind in an in-DOM (non-compiled) Vue template because HTML attribute/directive names are\n case-insensitive there; `addEventListener` works regardless of case either way.\n\n## Editor autocomplete (VS Code, JetBrains)\n\nTypeScript consumers already get tag/attribute completion for free from the generated\n`HTMLElementTagNameMap`. Plain HTML, and in-DOM Vue or Angular templates, don't go through that type\ngraph, so this package also ships small editor data files generated from `custom-elements.json`:\n`vscode-html-data.json` (tag and attribute completion, with slot and CSS-part reference tables in\neach tag's hover description) and `vscode-css-data.json` (every `--lr-*` custom property). Point VS Code's\n[`html.customData`](https://code.visualstudio.com/docs/languages/html#_html-custom-data) and\n[`css.customData`](https://code.visualstudio.com/docs/languages/css#_css-custom-data) settings at\nthem — typically in a workspace `.vscode/settings.json` so the whole team picks it up:\n\n```json\n{\n \"html.customData\": [\n \"./node_modules/@aceshooting/lyra-ui/vscode-html-data.json\"\n ],\n \"css.customData\": [\"./node_modules/@aceshooting/lyra-ui/vscode-css-data.json\"]\n}\n```\n\nBoth settings accept an array, so add these alongside any other custom-data files the workspace\nalready references. WebStorm/IntelliJ users get more from the bundled `web-types.json`, with no\nextra configuration once the package is installed: tag, attribute, JS property (`.prop=${…}`), DOM\nevent (`@lr-event=${…}`), slot and custom-property completion. The property and event contributions\nmatter most here — these are Lit components, so the idiomatic binding style is `.prop=`/`@event=`\nrather than attributes, and 865 public members are declared `attribute: false` and reachable no other\nway. The VS Code custom-data format defines no properties/events/slots concept, so in\n`vscode-html-data.json` those names remain reference prose in each tag's hover description. CSS-part\nnames are prose in both files.\n\nBuild tools can import the published manifest directly through its explicit package export:\n\n```ts\nimport manifest from '@aceshooting/lyra-ui/custom-elements.json' with { type: 'json' };\n```\n\nA subclass declaration's `cssParts` is always fully flattened (everything inherited included), but\n`attributes`/`members`/`events`/`slots`/`cssProperties` list only a declaration's own entries plus\nany inherited entry it overrides — intentional, since a TypeScript/JS consumer already resolves the\nrest through the generated `.d.ts` `extends` chain. Reading `custom-elements.json` directly for\nthose four kinds means walking each declaration's own `superclass` chain, or using the already-\nresolved `web-types.json`/`vscode-html-data.json` above instead.\n\n## Components\n\nThe catalog below lists all 285 tags in the current Custom Elements Manifest, grouped by\ncapability. The manifest and live docs are the authoritative sources for the complete generated\nAPI details.\n\n**Form controls, toasts, sparkline, and flags**\n\n| Component | Mirrors | Notes |\n| -------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `` + `` | `wa-combobox` / `wa-option` / `sl-option` | Filterable single/multi select, form-associated; options separate live `selected` from attribute-backed/reset `defaultSelected`; `xs`–`xl` sizing; async rich rows and retained selection payloads via `source`/`selectedRows`; virtual scrolling with `max-render` |\n| `` | `wa-select` / `sl-select` | Closed-list single-select, button trigger (not a text input, no filtering); form-associated, shares `` with `lr-combobox` |\n| `` | `wa-date-picker` | Inline calendar, single + range |\n| `` | `wa-date-input` | Date field + calendar popover, form-associated |\n| `` | — (extra) | Country-aware telephone field with canonical E.164 form values; numbering metadata is supplied through an optional adapter |\n| `` + `` + `toast()` | `wa-toast` / `wa-toast-item` | Stacking notifications |\n| `` | `wa-sparkline` | Zero-dependency inline SVG |\n| `` | `wa-textarea` / `sl-textarea` | Form-associated multiline field with label/hint/error chrome, auto-resize, native editing passthrough, and caret APIs |\n| `` | `wa-input` / `sl-input` | Form-associated single-line field (`text`/`password`/`email`/`number`/`time`/`search`/`date`/`datetime-local`/`tel`/`url`) with label/hint/error chrome and a built-in password-visibility toggle |\n| `` + `` | `wa-number-input` / `wa-time-input` | Numeric input and locale-aware segmented time input |\n| `` | — (extra) | Preserved browser-native time field for Lyra 7 compatibility ","readmeFilename":"README.md"}
![\"Lyra](\"https://raw.githubusercontent.com/aceshooting/lyra-ui/main/.github/readme/lyra-mark.svg\")
\n \n