` 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. |
| `` | `` | |
Neither old name is registered as an alias. A tag that silently keeps working under its old name is
how a rename looks finished while half of it is inert.
### Component contract moves and default changes
Two existing tags now carry the mapped contract their names promise. Rename the old behavior when
that is what the application needs:
| 7.x behavior | 8.0.0 destination | What the old tag means now |
| ------------------------------------------------ | ------------------------ | -------------------------------------------------------------------------------- |
| Browser-native `` | `` | `` is the locale-aware segmented field and popup. |
| Slotted/image `` pan and zoom | `` | `` is a sandboxed iframe preview with discrete zoom controls. |
The following changes do not require a tag rename, but code that relied on the former default or
exact TypeScript/event shape needs an explicit update:
- `.value` is typed `string | string[]`; `multiple` opts into the array-valued runtime
mode. Narrow the value after checking `multiple` rather than assuming a string.
- A bare `` now uses `appearance="accent"`. Write `appearance="filled"` to preserve the
former visual tier.
- `` no longer adds a reveal button unless `password-toggle` is present,
and `` leaves native spin buttons visible unless `without-spin-buttons`
(or `no-spin-buttons`) is present.
- `` now defaults `page-size` to `10`, not `20`; its page-change detail also includes
`pageSize`, and the cancelable `lr-before-page-change` precedes it.
- `` defaults to `effect="none"`, not `pulse`; `` defaults
`child-list` to false, not true.
- `` and `` default an unset date to the construction-time current
instant. `` uses decimal `unit-step="1000"`; write `1024` to retain the former
scaling.
- `` emits cancelable `lr-show`/`lr-hide` before state changes and settles the new
after-events after motion. `` replaces `delay` with independent `show-delay` and
`hide-delay`.
- Slider input/change details now include the active thumb and full value/range context. Readers of
`detail.value` continue to work; exact one-key object assertions must accept the wider shape.
The component-family reference documents every aligned default beside the affected property. The
contract-aware migration report identifies upstream-origin rewrites; the separate `lyra-v7`
profile described below makes the former popup/popover/tooltip defaults explicit.
The exact registration imports for the new and moved surfaces are:
```js
import "@aceshooting/lyra-ui/components/lr-page.js";
import "@aceshooting/lyra-ui/components/lr-video.js";
import "@aceshooting/lyra-ui/components/lr-video-playlist.js";
import "@aceshooting/lyra-ui/components/lr-native-time-input.js";
import "@aceshooting/lyra-ui/components/lr-pan-zoom.js";
```
### Attribute and property renames
Each row is a mechanical rewrite in your own markup or CSS. Three of them also change what happens
when the attribute is _absent_, so grep for the tag as well as for the old attribute.
| 7.x | 8.0.0 | What to check |
| -------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `` | `` | Polarity un-inverted, so the default flips: a backdrop click no longer dismisses a dialog unless you opt in. `` inherits this. |
| `` | `` | Same flip: the localized "showing XβY of Z" row is now opt-in. |
| `` | `` | Leaving `total` unset renders the empty state, so a missed rename is visible rather than silent. |
| `` | `` | |
| `` | default `start` β `end` | A drawer with no `placement` now enters from the logical end edge; write `placement="start"` to keep the old side. |
| `` `::part(fill)` | `::part(indicator)` | Rename the selector in your own CSS; the old part name matches nothing and fails silently. |
| `` | `` | The deprecated boolean is gone. |
| ``, `` | `bytes` | These were byte counts wearing the name of the size ladder. |
| `` / `min-size` / `max-size` | `extent` / `min-extent` / `max-extent` | Same reason: a CSS length along the docked axis, not a size step. |
``'s `with-clear` is no longer marked deprecated. Both upstream spellings of the clear
button β `with-clear` and `clearable` β are now first-class on ``, `` and
`` alike, so there is nothing to rewrite in either direction.
### Security-preserving differences
Some upstream behavior is intentionally not made automatic:
- `` sanitizes every fetched or same-page fragment, has no script-executing mode, and
defaults `mode` to `same-origin` instead of `cors`. A migration that depends on cross-origin or
script execution remains unchanged with a location-aware warning. Its post-sanitization
transclusion is network-silent and non-interactive: anchors remain only for resolvable
same-document `#fragment` links (rebased per include instance); every other navigation or
resource attribute, including `href`, `src`, `srcset`, `action`, `ping`, and `poster`, is stripped,
so images do not load. Form-control and custom-element wrappers are unwrapped to safe ordinary
text or children, while controls with no passive content are removed.
- Link-like Lyra controls always contribute `noopener noreferrer` to `rel` whenever `target` is set,
and always strip `opener`. Author `rel` tokens are merged rather than ignored, so `nofollow`, `me`
and `license` survive the rename β `` and `` therefore migrate
automatically as of 9.0.0. `` still derives `rel` from `target` alone.
- `` rejects active/non-embeddable URL schemes, always renders a sandbox, and
will not combine `allow-scripts` with `allow-same-origin`. `` validates media and
thumbnail URLs and byte-caps remote thumbnail VTT input.
These are deliberate fail-closed contracts. The migration report records them instead of emitting
markup that appears converted while weakening the application's security boundary.
### One styling vocabulary
`variant`, `tone` and `kind` used to mean the same thing on different components, and `appearance`
meant two unrelated things. There is now one name per concept, library-wide.
- **`tone` β `variant`** on ``, ``, `` and ``,
and on ``'s entry objects β along with its `tone-dot*` CSS parts, now
`variant-dot*`. No alias for any of them.
- **`appearance="card|plain"` β `frame="card|plain"`** on the thirteen container components that had
it (``, ``, ``, ``, ``,
``, ``, ``, ``,
``, ``, ``, ``).
`appearance` now means how a control fills itself and nothing else:
`accent | filled | outlined | filled-outlined | plain`.
- **``'s default `appearance` is now `accent`**, and `filled` is a genuinely quieter tier.
The two used to render identically for every variant except neutral.
- **`size` accepts both ladders everywhere** β this library's `2xs|xs|s|m|l|xl` and the upstream
`small|medium|large` β so a migrated `size="small"` needs no rewrite.
- **``, `` and `` are no longer unconditionally pill-shaped.** They
default to a rounded rectangle; add `pill` for the old fully-rounded ends.
### Tokens and theming
- **`theme.css` now declares cascade layers**: `@layer lr-base, lr-theme, lr-utilities, lr-overrides`,
with the tokens in `lr-theme`. Any _unlayered_ declaration of yours now beats every Lyra one
regardless of specificity or load order, so a plain `:root { --lr-theme-β¦ }` override always wins
with no `!important`. If you already wrap your overrides in your own `@layer`, they now sort
relative to `lr-theme` rather than losing to an unlayered `:root` β name your layer in an
`@layer` statement after importing `theme.css`, or move those rules out of a layer entirely.
- **`--lr-font-size-md` is removed**; use `--lr-font-size-m`. The two were the same value under two
names, which is why `` rendered `size="m"` and `size="l"` at identical text sizes.
- **Compound motion tokens are split into duration and easing** (`--lr-duration-*` +
`--lr-easing-*`). The compound `--lr-transition-*` tokens still resolve, composed from the two.
- **Shadows are five tiered steps** (`--lr-shadow-xs` β¦ `--lr-shadow-xl`), declared per mode with
much heavier dark-mode alphas, because a single near-black step against a near-black surface is not
a luminance difference at all. `--lr-shadow` still resolves (to the `m` step) and a theme that set
`--lr-theme-shadow-color` keeps working; a theme that overrode `--lr-shadow` directly should move to
the step it meant.
- **Hover and press are a color mix, not `filter: brightness()`** β tune them library-wide with
`--lr-color-mix-hover` / `--lr-color-mix-active` against `--lr-color-mix-partner`.
`--lr-hover-brightness` still resolves but no component reads it.
- **New `--lr-color-surface-overlay`** for modal panels (the page surface in light mode, lighter than
the page in dark), a **new `--lr-terminal-bg-*` set** for ANSI background colors, and a new
`--lr-form-control-*` tier (`height`, `font-size`, `padding-inline`, `padding-block`, `gap`,
`radius`) β one ladder shared by every control, retuned per `size` step.
- Colors moved where the generated ramp put them, including the brand seed. Restoring the old hex
values by hand would reintroduce the contrast failures the ramp exists to prevent.
- The value-named `--lr-size-` tokens are unchanged and still resolve, but the family is
frozen: existing entries may disappear as call sites find a semantic home, and none will be added.
Don't build new theming on them β reach for `--lr-space-*`, `--lr-radius*`, `--lr-font-size-*` or
`--lr-form-control-*` instead.
### Localization
**Pluralized messages are now CLDR category objects** selected through `Intl.PluralRules`, replacing
the paired `` + `Plural` convention. A catalog passed to `registerLyraLocale()`, or a
per-instance `.strings`, that used the old pair must be rewritten β with that locale's real
categories, which for Russian is four and for Arabic six:
```ts
// 7.x
registerLyraLocale("en", {
toolCount: "{count} tool",
toolCountPlural: "{count} tools",
});
// 8.0.0
registerLyraLocale("en", {
toolCount: { one: "{count} tool", other: "{count} tools" },
});
```
Twelve translation catalogs now ship as side-effect-only modules, so a common locale no longer needs a
hand-written catalog at all:
```js
import "@aceshooting/lyra-ui/translations/fr.js"; // also ar, de, es, fa, he, it, ja, pt-BR, ro, ru, zh-CN
```
Each locale also ships as twelve smaller per-family slices, so an app using only a handful of
components can import just those families instead of the whole catalog:
```js
import "@aceshooting/lyra-ui/translations/fr/forms.js";
import "@aceshooting/lyra-ui/translations/fr/data.js";
import "@aceshooting/lyra-ui/translations/fr/shared.js"; // cross-cutting strings, import alongside any family
```
`fa` and `he` are complete RTL catalogs. Locale lookup applies the normal regional fallback, so
`fa-IR` resolves through `fa` and `he-IL` through `he`; set `dir="rtl"` on the document or an
ancestor so layout and directional keyboard behavior follow the chosen language.
### Packaging
- **`@aceshooting/lyra-ui/internal/*` is no longer a published subpath.** The supported helpers moved
to `@aceshooting/lyra-ui/utilities/*` (one module per helper, or the whole set from
`@aceshooting/lyra-ui/utilities`), which now also carries `FormAssociated` and `groupByRecency` β
previously reachable only through the side-effectful root barrel. Rewrite
`@aceshooting/lyra-ui/internal/positioner.js` as `@aceshooting/lyra-ui/utilities/positioner.js`,
and likewise for `a11y`, `announcer`, `icons`, `layered-layout`, `lyra-element`,
`overlay-manager`, `prefix` and `scroll-lock`. Anything else that lived under `internal/` was never
a public API and has no replacement subpath.
## Migrating from Web Awesome or Shoelace
The "Mirrors" column records a design/API relationship, not blanket permission to rename a tag.
Every pinned Web Awesome and Shoelace component has a machine-readable migration classification:
`exact`, `rewritten`, `warning-required`, `conceptual-only`, or `unsupported`. Only `exact` and fully
specified `rewritten` mappings are changed automatically. The other three remain untouched and are
reported with their source location, so an incomplete migration cannot leave inert public members
behind while appearing to have succeeded.
Where the two upstreams disagree on a name for the same thing, Lyra accepts both spellings rather
than forcing a rewrite. The clear button is the clearest case: Web Awesome spells it `with-clear`,
Shoelace spells it `clearable`, and ``, `` and `` each honour both.
Neither spelling is deprecated, and neither needs rewriting in either direction β whichever one your
markup already carries keeps working.
The same compatibility rule applies when the upstreams disagree on a property's write type.
`lr-input.autocorrect` and `lr-textarea.autocorrect` always read as booleans, matching Web Awesome.
Input also accepts Shoelace's `'off'`/`'on'` property writes; Textarea accepts its wider string
surface, normalizing `'off'`/`'false'` to `false` and other strings to `true`. Both render the native
attribute canonically as `autocorrect="off"` or `autocorrect="on"`.
Icon tags and attributes can be renamed mechanically, but icon names are a separate vocabulary.
Lyra's dependency-free default library contains only `add`, `check`, `close`, `search`, `menu`,
`chevron-left`, `chevron-right`, `chevron-down`, `calendar`, `command`, and `trash`; any other
migrated ``, ``, or `` name renders no glyph. The migration CLI
reports `BEHAVIOR_REVIEW_REQUIRED` for those tags. Replace each name explicitly or register the
required vocabulary with `registerIconLibrary('default', { resolver })`.
`lr-option` likewise keeps live/default selection separate: the `selected` attribute initializes
`defaultSelected` and the parent control's reset default (property writes intentionally do not
reflect), while `selected` is property-only live state. Selecting an option at runtime never
rewrites the declarative default.
```html
```
**Automating the safe subset.** The package ships the version-matched `lyra-ui-migrate` CLI. It
reads a compact packaged projection of the validated component inventory, applies only
contract-recorded tag/member/default/registration-import rewrites, and can write a stable JSON
report for CI or human review. Replace `` with the exact Lyra version you are migrating to:
```bash
npx --package @aceshooting/lyra-ui@ lyra-ui-migrate --check \
--report=migration.json path/to/your/src
npx --package @aceshooting/lyra-ui@ lyra-ui-migrate path/to/your/src
```
The supported package identities are `@awesome.me/webawesome` and `@awesome.me/webawesome-pro`
for Web Awesome, plus `@shoelace-style/shoelace`. Directory targets include HTML, standalone CSS,
JavaScript, TypeScript, JSX, Vue, Svelte, MDX, and Markdown files.
The report records file, line, column, migration origin, tag/member, action, target, and warning code.
Supported side-effect component deep imports are routed through the target's inventory registration
module. Proven, tier-compatible root registration closures use `@aceshooting/lyra-ui/all.js`;
root-excluded targets receive granular registration imports instead. An automatic-looking tag with
no matching side-effect registration in the scanned target set stays unchanged with
`REGISTRATION_CLOSURE_REQUIRED`; include the registration-owning entry file in the scan rather than
accepting an inert `lr-*` result. A mapped target with optional runtime dependencies adds an
`OPTIONAL_PEER_REQUIRED` entry naming every package the consumer must install. Imports with
bindings, unknown subpaths, dynamic values, aliased component values that use a rewritten member,
unsafe security/default changes, conceptual mappings, and unsupported components remain unchanged
with an actionable warning. An aliased member blocks that mapping across the whole scanned target set
so the codemod never rewrites its registration import while leaving an old member behind. A second
run is byte-idempotent. Comments, prose, unrelated identifiers/packages, and partial strings are not
treated as component uses. `--check` never writes files and exits nonzero while a rewrite or warning
remains.
**Preserving Lyra 7 overlay defaults.** This is a separate, opt-in profile; the default command
above continues to scan only Web Awesome and Shoelace uses. Run it first in dry-run mode:
```bash
npx --package @aceshooting/lyra-ui@ lyra-ui-migrate --origin=lyra-v7 --dry-run \
--report=lyra-v7-migration.json path/to/your/src
```
The profile never renames an `lr-*` tag or import. It inserts attributes only when absent:
| Component | Lyra 7 behavior made explicit |
| -------------- | ------------------------------------------------------------------------------- |
| `` | `strategy="fixed"`, `placement="bottom-start"`, `distance="4"`, `flip`, `shift` |
| `` | `placement="bottom-start"`, `distance="4"`, `without-arrow` |
| `` | `distance="6"`, `without-arrow` |
Boolean `true` is emitted as canonical attribute presence; the positive inverse
`without-arrow` is used instead of serializing `arrow="false"`. Existing explicit values are
untouched. An opaque framework attribute spread or DOM alias blocks that component profile across
the scanned target set with a location-aware warning, so the tool cannot silently insert a default
beside a value it cannot see. Review or expand the dynamic value, rerun, then apply without
`--dry-run`; a final run should report no changes.
The inventory does not treat `dir` or `lang` as component-member drift: both are platform-global
HTML passthrough attributes. It likewise excludes Web Awesome's `did-ssr` hydration marker, which is
upstream runtime bookkeeping rather than an authored member to copy onto a Lyra component.
The same inventory reviews accessibility behavior separately from static API shape. Every one of
the 145 pinned upstream mappings names an upstream and Lyra behavior profile covering semantics,
naming, keyboard, focus, state, announcements, and motion. It stores the exact missing/additive
comparison and a rationale; an automatic mapping is rejected if its target profile drops a reviewed
behavior. These profiles summarize published public contracts and Lyra's authored contract plus
automated tests. They are not evidence of manual screen-reader, assistive-technology, or human
accessibility review; see [the accessibility evidence statement](../../docs/accessibility.md).
Shoelace is now a historical predecessor to Web Awesome, but its component vocabulary remains
familiar to many teams. The table below is a porting guide, not an automatic-rename allowlist; the
inventory classification and codemod report decide which individual uses are mechanically safe:
| Shoelace | Lyra | Migration note |
| ------------------------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | `` | Check `variant`, `appearance`, and loading behavior. |
| `` / `` | `` / `` | String `autocorrect` property writes remain accepted but read back as booleans; preserve the native editing/form contract and review label/error markup. |
| `` / `` | `` / `` | `defaultSelected`/the `selected` attribute is the reset default; live `selected` is property-only. Review option and value events. |
| `` / `` | `` / `` | Review close reasons, focus behavior, and slots. |
| `` / `` | `` / `` | Review appearance tokens and dismiss events. |
| `` | `` | Closed by default, with the same properties, slots, lifecycle, parts, and identity-preserving `toast()` contract under the `lr-` prefix. |
| `` / `` | `` / `` | Built-in status copy is localized through Lyra's runtime. |
For either migration, start with the codemod report. Update a package import or custom-element prefix
only for an automatic row, or after completing the manual port named by a warning; then run the
component's accessibility story and check its API notes for behavior that cannot be inferred from
the tag name alone. Lyra's own `--lr-theme-*` variables are the only theme inputs it reads. For a
staged Web Awesome migration, map existing values explicitly in application CSS; Lyra does not read
competitor token variables itself.
Everything else in the tables below β marked `β (extra)` β has no Web Awesome equivalent to
migrate _from_ in the first place, so there's nothing to rename: install the package and import
what you need (see Usage above). That's most of this library, including every dashboard atom
(stat cards, gauges, empty/skeleton states), the whole chart family, the temporal/graph/tree
components, ``, and the entire **Conversation & Agent UI** family (chat messages,
streaming text, tool-call chips/dialogs, citations, model/settings pickers, and more) β Web
Awesome has no chat/agent UI component family at all.
## Theming, internationalization & RTL
Every component is built on the same three guarantees, verified across the whole library rather
than opt-in per component:
**Theming.** Components read independent `--lr-theme-*` variables and standalone defaults. Lyra
does not depend on another library's theme or token namespace. For a ready-made light/dark base
theme, import `@aceshooting/lyra-ui/theme.css` once and toggle `.lr-light`/`.lr-dark` (or the
matching `data-lr-theme` attribute) on an ancestor:
```css
@import "@aceshooting/lyra-ui/theme.css";
```
Tooling can consume the canonical DTCG interchange document from
`@aceshooting/lyra-ui/design-tokens.json`. The generated
`@aceshooting/lyra-ui/design-tokens.css` entry supplies explicit light/dark fixture selectors for
previews and design-tool validation; it is not a replacement for the production `theme.css`.
```html
Save
```
**The resolved `--lr-color-*`/`--lr-space-*`/`--lr-radius`/`--lr-shadow-*`/`--lr-font-*` output
layer is declared only on each `lr-*` element's own shadow `:host`** β it is not readable from
plain application CSS or your own custom elements outside any `lr-*` shadow root (a rule like
`body { color: var(--lr-color-text) }` silently resolves to nothing, not an error). Set the
`--lr-theme-*` **input** layer shown below to retheme; see
[Where an override actually reaches](./llms/shared.md#where-an-override-actually-reaches) for
exactly how far each layer inherits.
Applications can override any `--lr-theme-*` input directly:
```css
:root {
--lr-theme-color-surface-default: #101827;
--lr-theme-color-text-normal: #f8fafc;
--lr-theme-color-brand-fill-loud: #60a5fa;
--lr-theme-font-size-m: 1rem;
--lr-theme-border-radius-m: 0.5rem;
}
```
`theme.css` declares `@layer lr-base, lr-theme, lr-utilities, lr-overrides` and puts its own tokens
in `lr-theme`, so an _unlayered_ rule of yours β like the `:root` block above β wins over every Lyra
declaration regardless of specificity or which stylesheet the bundler emitted first. The optional
`native.css` and `utilities.css` assets use `lr-base` and `lr-utilities`; `lr-overrides` remains
available for application rules. See [`llms/tokens.md`](./llms/tokens.md) for the complete shared token list.
Component-specific `--lr-*` custom properties remain available for local overrides.
Canvas components automatically repaint after observable theme attributes, stylesheet/link nodes,
CSSOM changes, adopted stylesheets, and relevant media-query changes. If an application theme engine
changes computed tokens through another mechanism, invalidate the owning browser realm explicitly:
```ts
import { invalidateLyraTheme } from "@aceshooting/lyra-ui/utilities/theme.js";
invalidateLyraTheme(); // global document realm
invalidateLyraTheme(shadowRoot); // realm owning this root, element, or document
```
The optional argument selects a realm, not a subtree. Calls are safe during SSR and coalesce into
each connected canvas consumer's normal redraw schedule.
**Optional light-DOM styles.** Import either bundle independently when an application wants Lyra's
token vocabulary outside component shadow roots:
```css
@import "@aceshooting/lyra-ui/native.css";
@import "@aceshooting/lyra-ui/utilities.css";
```
`native.css` styles only native descendants of an explicit `.lr-native` scope; it has no root reset
and does not style the scope marker itself. `utilities.css` provides exact, low-specificity `lr-*`
classes for layout, logical sizing, gap/alignment/wrap, prose/text, accessible hiding, FOUCE, and
`` mobile/desktop allocation helpers. Both are layered, tokenized, RTL-safe, and optional.
See [`llms/shared.md`](./llms/shared.md#optional-native-styles-and-css-utilities) for the complete
class inventory and override hooks.
**Frontend quality guarantees.** Every component is designed as a native custom element and tested
for the contract that applies to its shape: semantic roles and accessible names inside shadow DOM,
keyboard navigation, bubbling/composed public events, native form association and validity, logical
CSS for RTL, narrow-container layouts, reduced motion, and forced-colors behavior. Form controls
expose label, hint, error, focus, editing, reset, and validity behavior instead of hiding the useful
native contract behind a private input. Heavy integrations such as Chart.js, MapLibre, D3, Shiki,
Markdown, phone-number metadata, and flag artwork remain optional peer dependencies.
**Internationalization.** Every built-in string (button labels, status announcements,
`aria-label`s) resolves through a small runtime, in two ways you can combine:
```ts
import {
registerLyraLocale,
setLyraLocale,
} from "@aceshooting/lyra-ui/localization.js";
// App-wide: register translations once, anywhere in the app.
registerLyraLocale("fr", { close: "Fermer", retry: "RΓ©essayer" /* ... */ });
setLyraLocale("fr"); // or just set /an ancestor `lang` β components pick it up
```
The dedicated `localization.js` entry is side-effect-free: it does not register the component
graph. The package root continues to re-export the same runtime for compatibility, but importing
the root remains registration-free in v8.
```html
```
No rebuild, no per-locale bundle, no per-component API to learn β register the strings once and
every component that uses that key picks it up reactively, including ones added after your app's
first render.
Lyra's default messages are English fallbacks, while applications own the translated catalog. Date,
number, byte, relative-time, and calendar formatting use the browser's `Intl` APIs and the resolved
locale. Consumer-provided labels, values, file names, and message content are never altered by the
localization layer. The same runtime also covers accessible names, descriptions, validation messages,
live-region announcements, empty states, status labels, and action buttons; use `.strings` for a
component-specific override when needed.
**RTL.** Set `dir="rtl"` on `` or any ancestor β every component mirrors its layout
automatically via CSS logical properties and swaps directional keyboard navigation (e.g. the arrow
keys in a date grid or a roving-tabindex list) to match. `lang`/`locale` select translations and
`Intl` data but do not silently change writing direction; pair `lang="ar"`, `lang="he"`, or
`lang="fa"` with `dir="rtl"`. Components do not force their own `dir`, so they remain composable
inside mixed-direction layouts.
## Component status, versioning, and deprecation
Every component carries an explicit `stable` or `experimental` status plus the earliest published
`since` version in the manifest and generated reference. Stable components are production-ready.
Experimental components remain open to design review, but once published their public APIs receive
the same semver protection as stable components; experimental is not permission for a silent minor
release break.
Deprecation is separate metadata. A deprecated component or member names its replacement,
deprecation version, rationale, and earliest removal version. If deprecated in major version M, it
remains available for the complete M+1 line and cannot be removed before M+2. See
[`llms/shared.md`](./llms/shared.md#component-status-versioning-and-deprecation) for the full policy.
## SSR & Declarative Shadow DOM
Every Lyra entry point is server-safe under Node 20+ β the package root, `all.js`, the family
barrels, and every granular registration module alike. The `@aceshooting/lyra-ui/ssr-loader.js`
entry installs Lit's hydration hook before registering Lyra (it still pulls the whole `all.js`
closure, so it is unaffected by the 8.0.0 root split) and exports the machine-readable
`LYRA_SSR_SUPPORT_MATRIX`. New integrations that want granular registration can import
`@aceshooting/lyra-ui/hydration.js` first instead, then their own component modules. The matrix has
two explicit tiers:
- `render-and-hydrate` components emit Declarative Shadow DOM (DSD) and reuse that shadow root and
its nodes during browser hydration.
- `client-render` components preserve the host, serializable attributes, and light DOM in the
server response, then create their shadow DOM when the browser upgrades them. This tier covers
components whose initial render needs light-DOM traversal, layout, canvas, observers, or media
APIs that Lit's intentionally small server DOM does not emulate.
Configure Lit's server renderer with Lyra's fallback before `LitElementRenderer`:
```ts
import {
lyraSsrElementRenderers,
LYRA_SSR_SUPPORT_MATRIX,
} from "@aceshooting/lyra-ui/ssr-loader.js";
import { render, LitElementRenderer } from "@lit-labs/ssr";
import { collectResult } from "@lit-labs/ssr/lib/render-result.js";
import { html } from "lit";
const result = render(html`Dashboard`, {
elementRenderers: lyraSsrElementRenderers(LitElementRenderer),
});
const markup = await collectResult(result);
```
On the client, make the loader the first import that can reach Lit; it installs
`@lit-labs/ssr-client/lit-element-hydrate-support.js` before loading component definitions:
```ts
import {
diagnoseLyraHydration,
getLyraSsrMode,
} from "@aceshooting/lyra-ui/ssr-loader.js";
const diagnostics = await diagnoseLyraHydration(document);
```
Root-excluded optional-peer families still use their granular registration import after the loader;
the loader does not make optional peers eager. Property bindings cannot be serialized by a fallback
renderer, so express initial fallback state as attributes/light DOM or assign properties on the
client. A `render-and-hydrate` component whose rendering depends on something only a browser can
answer β its own light-DOM children, or a browser global such as `EyeDropper` β reproduces the
server's answer on the hydrating render and corrects itself on the very next update rather than
contradicting the markup it is hydrating, so a slotted override or an eyedropper button appears one
frame after hydration. A browser-only mount (no server markup) is unaffected and still renders the
final result the first time. Layout measurement, observers, canvas, and media playback start after hydration; remote
content remains client-only. CI renders every inventory tag, verifies both tiers, and crawls a real
Chromium DSD response (including `lr-page`) with strict hydration warnings/errors and DOM-identity
checks. The exported matrix is the authoritative per-tag list as components evolve.
## Framework integration (React, Vue, Angular, Svelte)
Lyra ships plain custom elements with no framework-specific wrapper package, so the friction is the
same friction any custom-element library has with a non-Lit framework, not anything Lyra-specific:
For tag, property, event, element-ref, and CSS-custom-property types in framework templates, import
the matching opt-in declaration entry once in your application's type graph:
```ts
import type {} from "@aceshooting/lyra-ui/custom-elements-jsx"; // React 19 / JSX
import type {} from "@aceshooting/lyra-ui/vue";
import type {} from "@aceshooting/lyra-ui/svelte";
```
These entry points are generated from the same Custom Elements Manifest as the editor metadata.
They contain types only: they add no runtime wrapper or framework dependency, and they do not
register elements. Keep importing the granular registration modules your application uses, for
example `import '@aceshooting/lyra-ui/components/lr-input.js'`.
- **Property vs. attribute binding.** A complex-typed property (an object, array, or function β e.g.
`.strings`, `.selectedRows`, `.markers`) must be bound as a JS _property_, not a stringified
attribute. Use Vue's `:prop` binding (or the `.prop` modifier), Angular's `[prop]="value"` template
binding, or a plain property assignment; Svelte's compiler binds to a matching element property
automatically when one exists, so `prop={value}` mostly just works. A bare `attr="value"` or string
interpolation only ever sets a string attribute β fine for `variant="brand"`, wrong for anything
non-string.
- **Angular needs `CUSTOM_ELEMENTS_SCHEMA`.** Angular's template compiler rejects unknown elements
and properties by default. Add `schemas: [CUSTOM_ELEMENTS_SCHEMA]` to the module (or standalone
component) that uses any `` tag so Angular stops trying to resolve it as an Angular
component.
- **Custom events need the framework's DOM event-binding syntax, not its component-event
shorthand.** A framework's usual event shorthand (Vue's `@event` on a _Vue component_, Angular's
`(event)` output binding) is wired for that framework's own event system; a plain custom element's
events are native `CustomEvent`s and need the same binding path used for native DOM events β
`onlr-change={handler}` in React 19, `@lr-change="handler"` in Vue,
`(lr-change)="handler()"` in Angular, or `onlr-change={handler}` in Svelte 5
(`on:lr-change={handler}` remains accepted by Svelte's legacy event-directive syntax). Use
`element.addEventListener('lr-change', handler)` directly when a template binding isn't
available. Lyra's own event names are consistently kebab-case (`lr-change`, `lr-cell-click`,
`lr-selection-change`, β¦) rather than camelCase, specifically to stay friendly to this binding
path β some other custom-element libraries use camelCase event names, which can silently fail to
bind in an in-DOM (non-compiled) Vue template because HTML attribute/directive names are
case-insensitive there; `addEventListener` works regardless of case either way.
## Editor autocomplete (VS Code, JetBrains)
TypeScript consumers already get tag/attribute completion for free from the generated
`HTMLElementTagNameMap`. Plain HTML, and in-DOM Vue or Angular templates, don't go through that type
graph, so this package also ships small editor data files generated from `custom-elements.json`:
`vscode-html-data.json` (tag and attribute completion, with slot and CSS-part reference tables in
each tag's hover description) and `vscode-css-data.json` (every `--lr-*` custom property). Point VS Code's
[`html.customData`](https://code.visualstudio.com/docs/languages/html#_html-custom-data) and
[`css.customData`](https://code.visualstudio.com/docs/languages/css#_css-custom-data) settings at
them β typically in a workspace `.vscode/settings.json` so the whole team picks it up:
```json
{
"html.customData": [
"./node_modules/@aceshooting/lyra-ui/vscode-html-data.json"
],
"css.customData": ["./node_modules/@aceshooting/lyra-ui/vscode-css-data.json"]
}
```
Both settings accept an array, so add these alongside any other custom-data files the workspace
already references. WebStorm/IntelliJ users get more from the bundled `web-types.json`, with no
extra configuration once the package is installed: tag, attribute, JS property (`.prop=${β¦}`), DOM
event (`@lr-event=${β¦}`), slot and custom-property completion. The property and event contributions
matter most here β these are Lit components, so the idiomatic binding style is `.prop=`/`@event=`
rather than attributes, and 865 public members are declared `attribute: false` and reachable no other
way. The VS Code custom-data format defines no properties/events/slots concept, so in
`vscode-html-data.json` those names remain reference prose in each tag's hover description. CSS-part
names are prose in both files.
Build tools can import the published manifest directly through its explicit package export:
```ts
import manifest from '@aceshooting/lyra-ui/custom-elements.json' with { type: 'json' };
```
A subclass declaration's `cssParts` is always fully flattened (everything inherited included), but
`attributes`/`members`/`events`/`slots`/`cssProperties` list only a declaration's own entries plus
any inherited entry it overrides β intentional, since a TypeScript/JS consumer already resolves the
rest through the generated `.d.ts` `extends` chain. Reading `custom-elements.json` directly for
those four kinds means walking each declaration's own `superclass` chain, or using the already-
resolved `web-types.json`/`vscode-html-data.json` above instead.
**Which tags a per-tag entry registers.** Each stable per-tag entry
(`@aceshooting/lyra-ui/components/lr-.js`) can, at import time, define more than one custom
element: importing `lr-table.js` also registers ``, ``, `` and
``, because `lr-table`'s registration entry imports those composed children's own
registration entries before defining `` itself. `custom-elements.json` has no field for
this β it declares one custom element per family source module, not per stable entry specifier β
so build tooling that needs to verify statically "does importing this specifier register that tag"
(a lint rule, a contract test, a bundler safety check) reads the generated `registrations.json`
instead:
```ts
import registrations from '@aceshooting/lyra-ui/registrations.json' with { type: 'json' };
const table = registrations.entries.find((entry) => entry.tag === 'lr-table');
table?.registers; // ['lr-empty', 'lr-pagination', 'lr-skeleton', 'lr-spinner', 'lr-table']
```
Each entry's `registers` is derived from the same transitive-import analysis
`scripts/check-component-dependencies.mjs` already performs (not a second hand-maintained list),
covers every published component, and is regenerated by `pnpm run registration-graph`.
## Components
The catalog below lists all 288 tags in the current Custom Elements Manifest, grouped by
capability. The manifest and live docs are the authoritative sources for the complete generated
API details.
**Form controls, toasts, sparkline, and flags**
| Component | Mirrors | Notes |
| -------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` + `` | `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` |
| `` | `wa-select` / `sl-select` | Closed-list single-select, button trigger (not a text input, no filtering); form-associated, shares `` with `lr-combobox` |
| `` | `wa-date-picker` | Inline calendar, single + range |
| `` | `wa-date-input` | Date field + calendar popover, form-associated |
| `` | β (extra) | Country-aware telephone field with canonical E.164 form values; numbering metadata is supplied through an optional adapter |
| `` + `` + `toast()` | `wa-toast` / `wa-toast-item` | Stacking notifications |
| `` | `wa-sparkline` | Zero-dependency inline SVG |
| `` | `wa-textarea` / `sl-textarea` | Form-associated multiline field with label/hint/error chrome, auto-resize, native editing passthrough, and caret APIs |
| `` | `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 |
| `` + `` | `wa-number-input` / `wa-time-input` | Numeric input and locale-aware segmented time input |
| `` | β (extra) | Preserved browser-native time field for Lyra 7 compatibility |
| `` | `wa-color-picker` / `sl-color-picker` | Form-associated native color picker with label/hint chrome |
| `` | `wa-checkbox-group` | Form-associated group of checkboxes with array values and group validation |
| `` | β (extra) | Editable, removable form-associated token list |
| `` + `` | `wa-icon` / `sl-icon` / `sl-icon-button` | Dependency-free SVG icons and accessible icon-only actions; migrated icon names outside the eleven-name built-in set require a registered library |
| `` | `wa-button` / `sl-button` | Generic action-button primitive (`variant`/`appearance`/`size`/`loading`), owns `type="submit"`/`"reset"` via its browser-resolved form owner, including an external owner named by `form` |
| `` + `` | `wa-radio` / `wa-radio-group` / `sl-radio` / `sl-radio-group` | Form-associated single-choice controls with roving arrow-key navigation and group validation; Lyra's group `name` defaults empty while Shoelace defaults to `option`, so the codemod inserts `name="option"` (set it for a manual rename) |
| `` | `sl-radio-button` | The same single-choice control rendered as a button; a `LyraRadio` subclass, so a `` accepts either tag and consecutive siblings collapse into one segmented control |
| `` | `wa-otp-input` | Form-associated one-time-code field β presentational segments over one real input, so paste, SMS autofill and mobile keyboards work natively and the control stays one tab stop |
| `` | `wa-spinner` / `sl-spinner` | Localized indeterminate busy indicator with reduced-motion support |
| `` + `` | `wa-progress-bar` / `wa-progress-ring` / `sl-progress-bar` / `sl-progress-ring` | Determinate or indeterminate progress indicators |
| `` | β (extra) | Country/language flags for i18n pickers β needs the optional peer `@aceshooting/lyra-flags` |
| `` | β (extra) | Closed-list locale switcher over the library's own locale registry (`getRegisteredLyraLocales()`) or an explicit `locales` catalog; selecting a row calls `setLyraLocale()` unless `lr-change` is cancelled |
**Additional media and interaction primitives**
| Component | Mirrors | Notes |
| -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------- |
| `` | `wa-animated-image` / `sl-animated-image` | Animated image playback with a captured still frame and reduced-motion support |
| `` | `wa-animation` / `sl-animation` | Web Animations API wrapper for declarative preset or custom animations |
| `` | β (extra) | Responsive avatar grouping with a localized overflow indicator |
| `` | `wa-include` / `sl-include` | Loads sanitized HTML or text content from a URL |
| `` | `wa-known-date` | Form-associated date entry control with separate day, month, and year fields |
| `` | β (extra) | Full-screen modal image viewer with navigation and pan/zoom |
| `` | `wa-qr-code` / `sl-qr-code` | Canvas QR renderer; needs the optional peer `qrcode` |
| `` | `wa-random-content` | Random, unique, or sequential slotted-content selection with autoplay |
| `` + `` | β (extra) | Vertical or horizontal chronological event layout |
| `` | β (extra) | Anchored onboarding tour with spotlight, keyboard navigation, and focus management |
**Dashboard atoms**
| Component | Mirrors | Notes |
| ---------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | β (extra) | Generic empty/no-data state |
| `` | `wa-skeleton` / `sl-skeleton` | Loading placeholder (pulse/sheen) |
| `` | `wa-scroller` | Responsive overflow surface with optional navigation controls |
| `` | `wa-resize-observer` / `sl-resize-observer` | Lifecycle-managed ResizeObserver for slotted elements |
| `` | `wa-intersection-observer` | Lifecycle-managed IntersectionObserver for slotted elements |
| `` | `wa-mutation-observer` / `sl-mutation-observer` | Lifecycle-managed MutationObserver for slotted elements |
| `` | β (extra) | KPI/stat card with trend pill and an optional breakdown row list; either can carry an `exactValue` shown as a hover/focus tooltip alongside the rounded/formatted display value |
| `` | `wa-data-grid` | Virtualized client/server data grid with sorting, filtering, grouping, selection, column controls, tree/detail rows, paging, CSV export, and the complete experimental 3.11 public surface |
| `` | β (extra) | Sort/select-aware data table with optional controlled filtering, client/server-friendly pagination, loading state, consumer-owned inline editing, expandable rows, sticky columns, and responsive `priority` columns |
| `` | `wa-pagination` | Controlled previous/next and validated page-jump navigation with a localized range summary, loading/empty states, RTL icons, and container-responsive stacking |
| `` | β (extra) | Radial, full-circle ring, or linear meter with a per-instance fill token |
| `` | β (extra) | Injection-safe CSV/JSON downloads plus event-handled custom format descriptors and controlled busy state |
| `` | `wa-copy-button` / `sl-copy-button` | Standalone icon-only copy-to-clipboard button for a plain text value, no positioning opinion |
| `` | β (extra) | Resizable multi-panel layout; one pane can opt into responsive `collapse` (`"start"`/`"end"`) to a fixed-width rail, then a floating overlay card, as the split's container narrows |
| `` | `wa-split-panel` / `sl-split-panel` | Exact two-pane split contract with named `start`/`end` content, percent/pixel positioning, primary-pane sizing, snapping, constraints, and an accessible divider |
| `` | β (extra) | Card shell with collapsible header, fullscreen, and customizable chrome |
| `` | β (extra) | Zero-dependency SVG word/tag cloud, spiral-placed by weight |
| `` + `` | `wa-badge` / `wa-tag` / `sl-badge` / `sl-tag` | Compact semantic status labels |
| `` | `sl-alert` | Closed-by-default inline alert with timed dismissal, countdown, and identity-preserving toast promotion |
| `` | `wa-callout` | Dismissible inline status, warning, and error message surface |
| `` | `wa-divider` / `sl-divider` | Horizontal or vertical semantic separator |
| `` | `wa-rating` / `sl-rating` | Keyboard-accessible star rating slider |
**Temporal & graph**
| Component | Mirrors | Notes |
| ------------------------------ | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | β (extra) | Two-handle brush/scrubber over a numeric domain |
| `` | β (extra) | Play/pause sequence index stepper over `itemCount`, with `currentIndex` and `lr-sequence-step` |
| `` | β (extra) | DPR-aware Canvas heatmap with matrix and calendar (`mode="calendar"`) layouts, `fit-to-width` responsive scaling |
| `` | β (extra) | Dependency-free conversion funnel: each stage a bar sized as its share of the FIRST stage, labelled with both its absolute value and its share, with per-stage drop-off and an optional comparison series normalized to its own first stage; plain HTML, so the accessible representation is the chart itself |
| `` | β (extra) | Compact, one-thin-cell-per-item strip visualizing a sequence of categorical states with an optional secondary per-cell marker β pure CSS/flex, no chart.js/SVG/canvas; a named roving `role="list"` whose `role="listitem"` cells support Arrow/Home/End navigation and controlled activation through click or Enter/Space (`lr-item-activate`) |
| `` | β (extra) | Force-directed node-link diagram with pan/zoom/drag, directed/styled relationship links, and rich accessible metadata β needs the optional peer deps `d3-force`, `d3-drag`, `d3-zoom`, `d3-selection` |
| `` + `` | `wa-tree` / `wa-tree-item` / `sl-tree` / `sl-tree-item` | Expand/collapse hierarchy with structured icon/label/description/badge rows, optional richer accessible labels, and APG tree keyboard navigation |
**Flow canvas β workflow & DAG diagramming**
| Component | Mirrors | Notes |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `` | β (extra) | Pannable/zoomable DAG workflow canvas β positions node cards, draws SVG edges, and runs a shared layered auto-layout for unpositioned nodes; readonly (viewer) by default, opt into editor gestures individually via `nodes-draggable`/`connectable`/`droppable`; a controlled component, never mutates `nodes`/`edges` itself |
| `` | β (extra) | The default workflow node card β header/body/toolbar chrome, tool-lifecycle `status` tones, and named connection-handle elements edges anchor to; purely presentational, used as `lr-flow-canvas`'s default card, a slotted override, or standalone |
| `` | β (extra) | Corner overview map of a `lr-flow-canvas` β scaled node rectangles plus a draggable viewport rectangle; resolves its target canvas via `for` (or the nearest ancestor) and reads geometry only from the canvas's `registerCompanion()` snapshots, never `nodes` directly |
| `` | β (extra) | The canvas's zoom-in/zoom-out, fit, and interaction-lock button cluster; drives only view state on a resolved `for` canvas, never touches `nodes`/`edges` |
| `` | β (extra) | Searchable, categorized node library for workflow editors β drag an item onto a canvas or place it by keyboard, emitting `lr-palette-place`/`lr-select`; never creates nodes or touches a canvas's data itself |
| `` | β (extra) | Execution-state companion for a `lr-flow-canvas` β pushes a `FlowRunDecorations` map into the resolved canvas and renders a compact "{done} of {total} steps complete" run-summary strip; pure pushed state, never executes or polls anything |
**Knowledge graph & RAG exploration**
| Component | Mirrors | Notes |
| ------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | β (extra) | Node-type legend for a paired `lr-graph` β one swatch/label/count row per node type, doubling as visibility filters via `lr-visibility-change`; never reads or writes a graph directly |
| `` | β (extra) | Knowledge-graph entity dossier card β type badge, description, key/value property rows, degree, community chip, and a built-in "focus in graph" action (`lr-entity-select`); never fetches or focuses a graph itself |
| `` | β (extra) | Inline `@entity` mention for agent prose β flow content, keyboard-focusable, with a hover/focus preview popover; the knowledge-graph sibling of `lr-citation-badge`, carrying ids through events only |
| `` | β (extra) | One entity's relationship rows β relation, direction, neighbor β with per-row navigate and expand-in-graph affordances; never computes neighbors itself or mutates a graph |
| `` | β (extra) | Compact, horizontally scrollable node β relation β node chain rendering "why A connects to B" (GraphRAG local-search reasoning paths); one-dimensional and presentational, no path finding |
| `` | β (extra) | GraphRAG community/cluster summary card β label, LLM summary excerpt, member count, member chips with overflow, and a drill-in action (`lr-drill`); doesn't own community rendering or membership fetching |
| `` | β (extra) | Ranked retrieved-chunks list β relevance score bars with tier tones, expandable chunk text, and a `lr-chunk-open` deep-link event that lands a chunk in `lr-document-viewer`; never fetches, ranks, or dedupes |
| `` | β (extra) | Checkbox tree/list scoping which sources ground the next answer β tri-state folders, select-all, type icons, search; deliberately not form-associated, an immediate app-state scoping panel wired through `lr-sources-change` |
| `` | β (extra) | Sectioned grounding-breakdown disclosure panel for one answer (Entities / Relationships / Communities / Text chunks), composing `lr-entity-chip`/`lr-path-strip`/`lr-community-card`/`lr-chunk-inspector`; pure projection and event conduit, no fetching |
| `` | β (extra) | Radial expandable topic tree (NotebookLM-style mind map) β zero-dependency SVG with a closed-form radial layout; hierarchy only, no cross-links, force simulation, communities, or edge labels (that's `lr-graph`) |
| `` | β (extra) | Orchestration-level surface for exploring a knowledge graph β the `lr-graph` canvas plus entity search, type filters, neighborhood expansion, pinned nodes, path finding between pins, and a details overlay; composes `lr-graph`, `lr-graph-legend`, `lr-entity-card`, `lr-neighbor-list`, `lr-path-strip`, and `lr-popover.showAt()` rather than re-implementing graph rendering itself |
| `` | β (extra) | Editor for a single typed relationship/path filter (`GraphQuery`) over a knowledge graph β start/end entity anchors, relationship-type and node-type pickers with a removable active-filter chip display, a traversal direction, a min/max hop range, validation, and a host-persisted saved-query list; a serializable query model for GraphRAG workflows |
| `` | β (extra) | Full entity detail surface β a persistent header (`lr-entity-card` plus a confidence `lr-stat`) above an `lr-tab-group` strip for Relationships (`lr-neighbor-list`), Supporting chunks (`lr-chunk-inspector`), and Provenance (`lr-provenance-panel`); pure layout, never fetches or mutates graph/document state |
| `` | β (extra) | Accessible SVG projection of host-provided embedding points with cluster coloring and a visible cluster legend, roving keyboard focus, and `lr-point-select`; it never filters points, computes embeddings, or owns dimensionality reduction |
**Retrieval & grounding**
| Component | Mirrors | Notes |
| ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | β (extra) | Query bar for a retrieval/RAG surface β query text, an active-filter/scope chip row, a vector/keyword/hybrid mode selector, and loading/error/empty status feedback; fully controlled, emits `lr-search` only and never performs retrieval itself |
| `` | β (extra) | Orchestration-level ranked-chunk-list surface β deduplication, optional grouping by source, multi-selection, pagination/infinite loading, and a compact/expanded presentation switch; composes an `lr-chunk-inspector` per row and an internal `lr-virtual-list` for large result sets |
| `` | β (extra) | Retrieval pipeline's stage timeline (query rewriting, embedding, retrieval, reranking, filtering) rendered through `lr-span-waterfall`, plus a disclosure list exposing each stage's evidence (chunks via `lr-chunk-inspector`, free-form text, and/or metadata); never fetches or computes retrieval results itself |
| `` | β (extra) | Claim-level scorecard for one generated answer β supported/unsupported claim counts, citation coverage, an optional confidence score, warnings, and (when supplied) a list of evidence citations; composes `lr-stat` and `lr-citation-badge`, pure projection and event conduit |
| `` | β (extra) | One claim's support verdict, score, citations, and evidence excerpts, with typed citation activation for opening the original source |
| `` | β (extra) | Inspection view of the exact context assembled for a model call β per-segment token estimates via `lr-context-meter`, source attribution via `lr-citation-badge`, copy/export affordances, and truncation-boundary/redaction-marker rendering; pure projection, never fetches, estimates, or redacts itself |
| `` | β (extra) | Grounded answer surface composing sanitized Markdown, claim-level grounding summary, citation badges, and source cards; controlled, localized, and emits citation/retry events without fetching data |
| `` | β (extra) | Side-by-side comparison of retrieval runs, including latency, hit count, score, and overlapping source identifiers; controlled and computation-free |
| `` | β (extra) | Aggregate RAG quality scorecard for groundedness, citation coverage, relevance, recall, latency, and cost, with per-case drill-in events |
**Knowledge base & document management**
| Component | Mirrors | Notes |
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `` | β (extra) | Source list for a retrieval knowledge base β sync status, indexing health, permissions, and per-row create/sync/pause/delete affordances; a controlled data view that never syncs or indexes anything itself, only presents `sources` and emits request-only events |
| `` | β (extra) | Controlled list of documents moving through an ingestion pipeline (upload β text extraction β chunking β embedding β indexing), each row showing its stage, progress, chunk/embedding counts, and a retry or cancel affordance; presentation only, virtualizes above `virtualizeAt` items |
| `` | β (extra) | Searchable, filterable inventory of documents with versions, tags, owners, freshness, and bulk selection; composes `lr-table` for the grid and `lr-input`/`lr-combobox` for search and tag-facet filtering β a controlled data view, no upload/sync/mutation of its own |
| `
