@aceshooting/lyra-ui 2.13.0 → 3.1.0

package/llms-full.txt

@@ -1,18 +1,14 @@
 # @aceshooting/lyra-ui — LLM API Reference
 
-`@aceshooting/lyra-ui` is a library of free, clean-room [Lit](https://lit.dev) web components — a
-companion to [Web Awesome](https://webawesome.com) that reimplements selected Web Awesome **Pro**
-components as open-source equivalents (documented compatible tag shape, attributes, slots, events,
-and CSS parts under a `lyra-` prefix instead of `wa-`), plus a number of extras that have no Web Awesome
-counterpart at all (dashboard atoms, temporal/graph widgets, chart wrappers, a map component, a
-file dropzone). It is **token-compatible with Web Awesome**: every component's stylesheet resolves
-through Web Awesome's `--wa-*` design tokens first, falling back to its own `--lyra-*` tokens, so
-components read as native inside a Web Awesome-themed app and are equally usable standalone with no
-theme at all. This document is the complete, component-by-component API reference intended for
-coding assistants integrating the library; for install instructions, the full component catalog, and
-the `<wa-*>` → `<lyra-*>` migration notes, see the package [README](./README.md) — or the shorter
-curated index at [`llms.txt`](./llms.txt) if you just need the shape of the library before diving in
-here.
+`@aceshooting/lyra-ui` is a free, independent, MIT-licensed [Lit](https://lit.dev) web-component
+library and an open-source alternative to Shoelace and Web Awesome. It combines accessible form
+controls, layout and overlay primitives, dashboards, charts, data visualization, and Conversation &
+Agent UI. Selected components retain documented Web Awesome-compatible public names under a `lyra-`
+prefix to make migration easier, but Lyra has its own implementation, design tokens, localization
+runtime, RTL behavior, and release surface. It has no runtime dependency on either project. This is
+the complete component-by-component API reference for coding assistants integrating the library; for
+installation, the full catalog, and Web Awesome/Shoelace migration notes, see the package
+[README](./README.md) — or the shorter curated index at [`llms.txt`](./llms.txt).
 
 Component entry points such as `components/empty/empty.js` register their custom-element tag.
 Every component also exposes a matching `.class.js` entry for subclassing or type-directed
@@ -38,6 +34,7 @@ composition without registration; for example, `components/empty/empty.class.js`
   `lyra-thinking-panel`, `lyra-generation-status`, `lyra-code-block`, `lyra-tool-approval-dialog`,
   `lyra-tool-param-form`, `lyra-menu`/`lyra-menu-item`, `lyra-chip`/`lyra-chip-group`,
   `lyra-model-settings-panel`, `lyra-context-meter`, `lyra-dock-panel`, `lyra-document-preview`,
+  `lyra-document-viewer`, `lyra-docx-viewer`, `lyra-email-viewer`, `lyra-calendar-viewer`, `lyra-archive-viewer`,
   `lyra-media-card`, `lyra-attachment-trigger`, `lyra-kbd`, `lyra-result-card`/`lyra-result-field`,
   `lyra-avatar`, `lyra-card`, `lyra-stepper`, `lyra-segmented`, `lyra-diff-view`, `lyra-poll-status`,
   `lyra-code-block-core` (needs the optional peer `shiki`)
@@ -105,21 +102,22 @@ Not a custom element itself — infrastructure every `lyra-*` component in the l
   `lyra-citation-badge`, and `lyra-menu` (which resolves its `placement` through
   `rtlAwarePlacement()` first — see `rtl.ts` below — before handing it to `place()`).
 - **`tokens.styles.ts` → `tokens`** (a `css` template prepended to every component's stylesheet) —
-  the whole design-token layer. Every value chains through a `--wa-*` Web Awesome token first, with
-  a hard-coded fallback, e.g. `--lyra-color-brand: var(--wa-color-brand-fill-loud, #0969da)`. Full
+  the whole design-token layer. Every value chains through an independent `--lyra-theme-*` custom
+  property and finally a hard-coded fallback, e.g. `--lyra-color-brand: var(--lyra-theme-color-brand-fill-loud, #0969da)`.
+  Full
   set: `--lyra-color-surface / -text / -text-quiet / -border / -brand / -brand-quiet / -success /
   -success-quiet / -warning / -warning-quiet / -danger / -danger-quiet`,
   `--lyra-color-on-brand / -on-success / -on-warning / -on-danger` (paired
   text/icon colors for content painted on the corresponding solid semantic fill; standalone light
-  and dark fallbacks choose a contrasting foreground for each fill, while a Web Awesome theme can
-  provide its own `*-on-loud` values), `--lyra-space-xs / -s / -m / -l`, `--lyra-radius`, `--lyra-shadow`,
+  and dark fallbacks choose a contrasting foreground for each fill, while a consumer's own theme
+  can provide its own `*-on-loud` values), `--lyra-space-xs / -s / -m / -l`, `--lyra-radius`, `--lyra-shadow`,
   `--lyra-font`, `--lyra-transition-fast` / `-base` (motion timing every animating component should
   share), `--lyra-opacity-disabled` (one shared disabled-state opacity), `--lyra-focus-ring-width` /
   `-color` / `-offset` (every `:focus-visible` rule should reference these), `--lyra-icon-button-size`
   (minimum tappable box for icon-only buttons; the glyph itself doesn't grow). Also sets
   `:host([hidden]) { display: none !important; }`, an inherited `box-sizing: border-box` reset, and
   a `prefers-color-scheme: dark` fallback that re-points the color tokens' hard-coded defaults at a
-  dark palette (only takes effect when no real `--wa-*` theme value is present).
+  dark palette (only takes effect when no real `--lyra-theme-*` value is set).
 - **`prefix.ts`** — `LYRA_PREFIX = 'lyra'`; `tag(name)` → `` `lyra-${name}` ``; `defineElement(name,
   ctor)` — idempotent `customElements.define`, safe if a module is evaluated twice.
 - **`a11y.ts`** — `nextId(scope)`: monotonic id generator (e.g. `nextId('combobox-list')` →
@@ -544,6 +542,10 @@ Text field + calendar popover, **form-associated** via the shared `FormAssociate
   internal `<input>`; empty omits the attribute. Named `autoCorrect` in JS/TS (not `autocorrect`)
   to dodge a `lib.dom.d.ts` collision with `HTMLElement`'s own boolean `autocorrect` IDL member;
   the wire attribute is still the plain `autocorrect` name
+- `autocomplete: string = ''`, `inputMode: string = ''` (attribute `inputmode`), and
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the internal date input
+- `autocomplete: string = ''`, `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''`
+  (`enterkeyhint`) — forwarded to the internal `<input>`.
 
 **Methods:** `show()`, `hide()`, `clear()`
 
@@ -720,15 +722,14 @@ original declarative `value`, matching native `defaultValue` behavior.
 
 ## `lyra-button`
 
-A generic action-button primitive, the `lyra-*` equivalent of a plain `wa-button`. Renders an
-internal native `<button>` (this library has no runtime dependency on Web Awesome); `type="submit"`/
+A generic action-button primitive. Renders an internal native `<button>`; `type="submit"`/
 `type="reset"` are handled by the component itself via the host's own `closest('form')`, since a
 shadow-internal native button doesn't participate in an ancestor form's submission on its own.
 
 **Properties:**
 - `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected)
 - `appearance: 'accent' | 'filled' | 'outlined' | 'plain' = 'filled'` (reflected) — `'accent'` is a
-  loud, high-contrast filled tier (equivalent to `wa-button`'s own runtime-default appearance),
+  loud, high-contrast filled tier,
   distinct from `'filled'` for `variant="neutral"` specifically (`'filled'` reads the ambient
   surface color there; `'accent'` reads a solid neutral fill)
 - `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected)
@@ -737,7 +738,11 @@ shadow-internal native button doesn't participate in an ancestor form's submissi
   clearing `disabled`
 - `disabled: boolean = false` (reflected)
 
-**Getters/methods:** `focus(options?)`/`blur()` — forwarded to the internal native `<button>`.
+The shared `m` size uses `--lyra-font-size-m`. The internal button follows the host's inline size through `--lyra-button-width` (default
+`100%`), and the size scale is exposed through `--lyra-button-size-xs/-s/-m/-l/-xl`.
+
+**Getters/methods:** `click()`, `focus(options?)`, and `blur()` — forwarded to the internal native
+`<button>`; `click()` also runs the component's submit/reset behavior.
 
 **Events:** none (a plain native `click` bubbles and composes through the shadow boundary
 unmodified; disabled while `disabled` or `loading`).
@@ -746,11 +751,12 @@ unmodified; disabled while `disabled` or `loading`).
 
 **CSS parts:** `base`, `label`, `start`, `end`, `spinner` (present only while `loading`).
 
-**Themeable custom properties:** `--lyra-button-accent`, `--lyra-button-fill`,
+**Themeable custom properties:** `--lyra-button-width`, `--lyra-button-size-xs/-s/-m/-l/-xl`,
+`--lyra-button-accent`, `--lyra-button-fill`,
 `--lyra-button-on-fill`, `--lyra-button-border` (each swapped by the active `variant`, default
 `neutral` falls back to plain text/surface/border tokens), `--lyra-button-accent-fill`,
 `--lyra-button-accent-on-fill` (the `appearance="accent"` fill/foreground pair; `neutral` falls
-back to `--wa-color-neutral-fill-loud`/`-on-loud`, every other variant reuses that variant's own
+back to `--lyra-color-neutral`/`--lyra-color-on-neutral`, every other variant reuses that variant's own
 loud fill token), `--lyra-button-hover-brightness` (default `1.08`, the `:hover` filter intensity),
 `--lyra-button-active-scale` (default `0.9875`, the `:active` press-scale, disabled under
 `prefers-reduced-motion`).
@@ -1880,6 +1886,9 @@ itself (absent for `'wide'`/`collapse="none"`); and the `lyra-split-collapse-cha
 divider adjacent to the collapsed panel is drag/keyboard-disabled (`aria-disabled="true"`) while
 collapsed. `collapse="none"` (the default) is byte-for-byte identical to pre-collapse-feature behavior.
 
+`dividerLabel?: (index: number, panelCount: number) => string` (attribute: false) customizes the
+localized accessible label generated for each auto-inserted divider.
+
 **Events:** `lyra-resize` (`detail: { sizes }`, fired on every drag step/release **and** every
 keyboard step), `lyra-split-collapse-change` (`detail: { state: 'wide'|'rail'|'floating' }`, fired only
 on a real `collapse`-state transition, never on every resize/render),
@@ -1959,6 +1968,8 @@ position) survives the transition.
   sidebar/toolbar visible during fullscreen
 - `compact: boolean = false` (reflected) — tighter header/body padding, same convention as
   `lyra-empty`'s `compact`
+- `backdropInset: string = ''` (attribute `backdrop-inset`) — overrides the fullscreen backdrop's
+  CSS `inset` independently from `fullscreenInset`; when empty, it follows `fullscreenInset`
 - `views: WidgetView[] = []` (attribute: false) — named alternate views for the panel body, e.g. a
   chart/table toggle inside the same card chrome; `WidgetView { id: string; label: string; icon?:
   TemplateResult }`. Each entry gets a header toggle button (`[part='view-toggle']`) and a
@@ -1987,7 +1998,7 @@ empty), `label-group` (wrapper around the label and sublabel), `label`, `sublabe
 `backdrop`
 
 **Themeable custom properties:** `--lyra-widget-overlay-color` (default `rgb(0 0 0 / 0.5)` — the
-fullscreen backdrop scrim color; component-specific since no shared `--wa-*`/`--lyra-*` overlay token
+fullscreen backdrop scrim color; component-specific since no shared `--lyra-*` overlay token
 exists), plus shared tokens (`--lyra-space-*`, `--lyra-color-border/-surface/-text-quiet`,
 `--lyra-radius`, `--lyra-shadow`, `--lyra-icon-button-size`, `--lyra-focus-ring-*`).
 
@@ -2269,10 +2280,15 @@ A Canvas-rendered heatmap with a DPR-aware, resize-aware redraw loop, in one of
 `"matrix"` (default — a `rowLabels` × `colLabels` grid of `values`) or `"calendar"` (a
 GitHub-style Sunday–Saturday × week grid built from `days`, colored by quartile bucket rather than
 the matrix mode's continuous ramp). Every cell is independently addressable despite being
-canvas-drawn (no per-cell DOM node): a `pointermove` hit-test over the canvas shows `[part="tooltip"]`
+canvas-drawn (no per-cell DOM node by default): a `pointermove` hit-test over the canvas shows `[part="tooltip"]`
 with that cell's label + value; the canvas is `tabindex="0"` with arrow-key roving focus (a stroked
 ring redrawn over the focused cell on every draw, plus `[part="live-region"]` announcing it); and a
-click, or Enter/Space on the focused cell, fires `lyra-cell-click`.
+  click, or Enter/Space on the focused cell, fires `lyra-cell-click`.
+
+Set `accessibleCells: true` (`accessible-cells`) to opt into a native-button overlay for each
+interactive matrix/calendar cell. The overlay uses localized `aria-label`s, explicit
+`aria-pressed="true"|"false"` from the controlled `selectedCell`, and roving tabindex/arrow-key
+focus; it continues to emit `lyra-cell-click` and leaves selection state consumer-controlled.
 
 **Properties:**
 - `rowLabels: string[] = []` (attribute: false — matrix mode only)
@@ -2312,6 +2328,11 @@ click, or Enter/Space on the focused cell, fires `lyra-cell-click`.
   announcement when the focused cell is the selection. Purely a controlled property — mirrors
   `<lyra-lite-chart>`'s `selectedIndex`, this component never mutates it itself. Unset (the default,
   `null`) reproduces today's exact output.
+- `accessibleCells: boolean = false` (attribute `accessible-cells`) — renders `[part="cells"]` with
+  one `[part="cell"]` native button per interactive cell. Buttons expose localized `aria-label`s,
+  explicit `aria-pressed` state from `selectedCell`, and a roving tabindex; the canvas becomes
+  `aria-hidden` while this mode is enabled. The property is opt-in so the default canvas mode keeps
+  its low DOM footprint.
 - `cellText?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string` (attribute: false) —
   formats the per-cell hover tooltip and keyboard live-region announcement text; receives the cell
   position (`{ row, col }` in matrix mode, `{ week, weekday }` in calendar mode) and its value.
@@ -2370,7 +2391,8 @@ force a redraw manually.
 
 **Slots:** none.
 
-**CSS parts:** `base`, `canvas`, `tooltip` (hover tooltip, positioned over the hovered cell),
+**CSS parts:** `base`, `canvas`, `cells` (opt-in per-cell overlay), `cell` (one opt-in native cell
+button), `tooltip` (hover tooltip, positioned over the hovered cell),
 `live-region` (visually-hidden `role="status" aria-live="polite"` element announcing the
 keyboard-focused cell), `legend`, `legend-lo`, `legend-hi`, `legend-annotation` (one per labeled
 `annotations` entry)
@@ -2623,6 +2645,8 @@ descendants of the treeitem, matching the WAI-ARIA treeitem pattern's containmen
 - `setSize: number = 1`, `posInSet: number = 1` (attribute: false) — this node's `aria-setsize`/
   `aria-posinset` values among its siblings, pushed down from `<lyra-tree>`; normally set internally,
   not by consumers
+- `hasChildren: boolean` (read-only getter) — reports whether `item.children` contains at least one
+  child; leaf nodes never expose `aria-expanded` and cannot expand or collapse
 
 **Methods:** `expand()`, `collapse()` (each a no-op if already in that state, or a leaf), `select()`
 (fires `lyra-node-select`).
@@ -3169,6 +3193,10 @@ parsing (that's left entirely to the host).
 - `label: string = 'Drop files here or click to browse'`
 - `accessibleLabel: string = ''` (attribute `aria-label`) — overrides `label` as the internal
   dropzone/button accessible name without changing visible copy
+- `acceptedMessage: string = '{count} file(s) added.'` (attribute `accepted-message`) — live-region
+  message after an accepted selection; `{count}` is replaced with the accepted count
+- `rejectedMessage: string = '{count} file(s) rejected.'` (attribute `rejected-message`) — live-region
+  message after rejected files; `{count}` is replaced with the rejected count
 
 **Methods:** `openPicker()` programmatically opens the native file dialog; `focus(options?)`
 forwards to the interactive dropzone.
@@ -3464,6 +3492,8 @@ hand-building that chrome isn't worth it.
 - `closable: boolean = false` (attribute `closable`) — renders a built-in close (X) button in the
   header row (creating one, with no heading text, if `heading` is unset), wired to the same
   `close()` path Escape/backdrop-dismiss already use, with reason `'close-button'`
+- `noLightDismiss: boolean = false` (attribute `no-light-dismiss`) — prevents a backdrop click from
+  closing the dialog; Escape and explicit `close()` calls remain available
 
 Also settable as a plain `aria-label` attribute (not a public JS property): overrides the panel's
 computed accessible name outright, winning over every other source below (a slotted heading,
@@ -3501,7 +3531,7 @@ when no heading is slotted and `heading` is unset), `body` (wrapper around the d
 `footer` (wrapper around the `footer` slot)
 
 **Themeable custom properties:** `--lyra-dialog-overlay-color` (default `rgb(0 0 0 / 0.5)` — the
-backdrop scrim color; component-specific since no shared `--wa-*`/`--lyra-*` overlay token exists),
+backdrop scrim color; component-specific since no shared `--lyra-*` overlay token exists),
 `--lyra-dialog-width` (default unset/`auto` — the panel shrink-wraps to content, unchanged; set it
 for an assertive width instead), `--lyra-dialog-max-width` (default `32rem` — the panel's
 max-inline-size cap, via `min(var(--lyra-dialog-max-width, var(--lyra-dialog-width, 32rem)), 100%)`;
@@ -4161,7 +4191,7 @@ fenced/indented `<pre>`), `link` (every rendered `<a>`), `table` (every rendered
 
 **Themeable custom properties:** `--lyra-markdown-font-mono` (default `ui-monospace, SFMono-Regular,
 Menlo, Consolas, monospace` — the code/code-block font; component-specific since no shared
-`--wa-*`/`--lyra-*` monospace token exists), plus shared tokens `--lyra-space-xs/-s/-m/-l`,
+`--lyra-*` monospace token exists), plus shared tokens `--lyra-space-xs/-s/-m/-l`,
 `--lyra-color-brand-quiet`, `--lyra-color-brand`, `--lyra-color-border`, `--lyra-color-text-quiet`,
 `--lyra-radius`.
 
@@ -4243,6 +4273,8 @@ conversation-surface level).
 - `collapsed: boolean = false` (reflected) — whether the message body is hidden; effective whenever
   set, independent of `collapsible` (which only controls whether the toggle button itself is
   rendered) — mirrors `lyra-widget`'s identical `collapsible`/`collapsed` pair
+- `attachmentsPosition: 'before'|'after' = 'after'` (attribute `attachments-position`) — places the
+  `attachments` slot before or after the message body; both the visual and reading order follow it
 
 **Events:** `lyra-retry` (no detail payload; fired by the built-in retry button, only rendered when
 `status="failed"`), `lyra-collapse-toggle` (`detail: boolean`, the new `collapsed` state — fired when
@@ -4875,6 +4907,8 @@ wins when both are present.
   indeterminate state, and filename context so translators can reorder every value
 - `uploadFailedLabel: string = 'Upload failed'` (attribute `upload-failed-label`) — visible status
   text shown for `status="error"`; override for i18n/locale
+- `untitledLabel: string = 'Untitled file'` (attribute `untitled-label`) — fallback filename and
+  tooltip when neither `file` nor `name` supplies a name
 
 The component identifies *which* attachment a `lyra-remove`/`lyra-retry` event is about via the
 platform's own `id` attribute/property rather than a second, differently-named prop. Set `id="..."`
@@ -5369,6 +5403,11 @@ emitting `lyra-change`.
   `<input>`'s own `autocorrect` (Safari/WebKit-specific); empty omits the attribute. Named
   `autoCorrect` in JS purely to dodge a `lib.dom.d.ts` typing collision — the wire attribute is
   still plain `autocorrect`.
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`), and
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the free-text input;
+  they have no effect in closed-dropdown mode
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''`
+  (`enterkeyhint`) — forwarded to the free-text mode's native `<input>`.
 - `name: string = ''` (reflected)
 - `disabled: boolean = false` (reflected)
 - `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
@@ -5573,6 +5612,9 @@ shared overlay stack. First-party invention (no Web Awesome equivalent).
 - `searchPlaceholder: string = 'Search tools…'` (attribute `search-placeholder`)
 - `filter: ToolSelectFilter | null = null` (attribute: false) — overrides the built-in
   case-insensitive name/description substring match.
+- `autocomplete: string = ''`, `spellcheck: boolean = true`, `autocapitalize: string = ''`,
+  `autoCorrect: string = ''` (`autocorrect`), `inputMode: string = ''` (`inputmode`), and
+  `enterKeyHint: string = ''` (`enterkeyhint`) — forwarded to the search `<input>`.
 
 **Methods:** `close(reason: ToolSelectDialogCloseReason = 'api'): void` — closes the dialog, emits
 `lyra-close` with `reason`, and returns focus to whatever had it before the dialog opened.
@@ -6556,9 +6598,10 @@ something that announces state *transitions* instead. The Stop button gets a nor
 ## `lyra-code-block`
 
 Fenced code display with optional lazy syntax highlighting and a copy button. First-party invention
-(no Web Awesome equivalent). No highlighting grammar ships in the component itself — it lazy-loads
-the optional peer dependency `shiki` (see `code-loader.ts`) for the actual tokenizing, and degrades
-to a plain `<pre><code>` when that peer isn't installed or `language` is unset/unrecognized. That
+(no Web Awesome equivalent). It lazy-loads the optional peer dependency `shiki` (see
+`code-loader.ts`) for the actual tokenizing, and includes a compact GreyCat/GCL grammar because
+Shiki does not bundle one. It falls back to a plain `<pre><code>` when that peer isn't installed or
+`language` is unset/unrecognized. That
 fallback is the *default* rendering path, not a degraded one: unhighlighted code is perfectly usable,
 and it's what every instance renders at zero extra bytes until shiki resolves.
 
@@ -6566,7 +6609,10 @@ and it's what every instance renders at zero extra bytes until shiki resolves.
 - `code: string = ''` — the raw source text
 - `language: string = ''` — a shiki-recognized language id or alias (e.g. `"javascript"`, `"python"`,
   `"json"`); when unset, or when shiki doesn't recognize it, the code renders as plain unhighlighted
-  text regardless of whether shiki itself is available
+  text regardless of whether shiki itself is available. Shiki's bundled catalog covers most common
+  programming, markup, data, and configuration languages, including Python, C, C++, C#, Java,
+  JavaScript, TypeScript, HTML, CSS, JSON, SQL, Go, Rust, YAML, Markdown, and shell scripts. Lyra
+  also includes a built-in GreyCat grammar; use `"gcl"` or `"greycat"` for GreyCat source.
 - `filename: string = ''` — shown in the header, when set
 - `accessibleLabel: string = ''` (attribute `aria-label`) — names the internal focusable code-body
   region; otherwise a localized filename/language description is generated
@@ -6578,6 +6624,8 @@ and it's what every instance renders at zero extra bytes until shiki resolves.
   cannot override a true default)
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
   code scrolls internally past this height instead of growing the page
+- `lineNumbers: boolean = false` (attribute `line-numbers`, reflected) — displays one-based line
+  numbers for both highlighted output and the plain-text fallback
 - `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — a map of language id to an
   already-imported shiki grammar module (e.g. `{ bash: bashGrammar }` from a module-scope
   `import bash from 'shiki/langs/bash.mjs'`). When `language` matches a key here, highlighting is
@@ -6586,6 +6634,8 @@ and it's what every instance renders at zero extra bytes until shiki resolves.
   for that language — an additive, opt-in escape hatch for a build scoped to just the languages a
   consumer actually needs. A `language` absent from this map (or `languages` left unset) falls back
   to the default dynamic-import path unchanged.
+- `languagesOnly: boolean = false` (attribute `languages-only`) — skips the default shiki loader;
+  use when every requested language is supplied through `languages`
 
 **Events:** `lyra-copy` (`detail: { text: string }` — always the raw `code` value, never the
 highlighted HTML, and always fires regardless of whether the actual OS clipboard write succeeded),
@@ -6599,7 +6649,7 @@ button is activated, same event name/shape convention as `<lyra-thinking-panel>`
 
 **Themeable custom properties:** `--lyra-code-block-max-height` (default `none` — the consumer-tunable
 scroll cap; only takes effect once `max-height` is set), `--lyra-code-block-font` (default
-`ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` — no shared `--wa-*`/`--lyra-*` monospace
+`ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` — no shared `--lyra-*` monospace
 token exists to resolve through), plus shared tokens `--lyra-color-border`, `--lyra-radius`,
 `--lyra-color-surface`, `--lyra-space-xs/-s/-m`, `--lyra-font`, `--lyra-color-text-quiet`,
 `--lyra-color-text`, `--lyra-color-brand`/`-brand-quiet`, `--lyra-transition-fast`,
@@ -6625,6 +6675,9 @@ highlighting).
 ></lyra-code-block>
 ```
 
+Set `line-numbers` when source context benefits from numbered lines. The option does not change the
+raw `code` value or the `lyra-copy` event payload.
+
 A `<lyra-skeleton variant="rect">` placeholder (with `aria-busy="true"` on the host) stands in only
 while shiki itself is loading for the very first time on the page and `language` is set — it is
 deliberately *not* shown again for a later per-language grammar fetch (that's typically fast, and the
@@ -6688,6 +6741,8 @@ toggle, the loading-skeleton behavior while the fine-grained highlighter resolve
 - `copyable: boolean = true` (reflected) — shows the copy-to-clipboard button.
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
   code scrolls internally past this height instead of growing the page.
+- `lineNumbers: boolean = false` (attribute `line-numbers`, reflected) — displays one-based line
+  numbers for highlighted and plain output.
 - `languages: Record<string, ShikiLanguageInput> = {}` (attribute: false) — grammar definitions this
   instance can highlight, e.g. `{ json: jsonGrammar }` (import from `shiki/langs/<name>.mjs`). Empty
   (the default) never highlights at all — every `language` renders the plain-text fallback.
@@ -6819,6 +6874,15 @@ renders at the start of the action row, before Deny/Edit/Approve.
   `false` via a PROPERTY binding, e.g. `.editable=${false}` — a `?editable=${false}`
   boolean-attribute binding cannot override a true default). When `false`, `args` is always shown
   read-only and can never be changed before approval.
+- `spellcheck: boolean = false`, `autocapitalize: string = 'off'`,
+  `autoCorrect: string = 'off'` (attribute `autocorrect`), `autocomplete: string = 'off'`,
+  `wrap: 'hard'|'soft'|'off' = 'soft'`, `inputMode: string = ''` (attribute `inputmode`),
+  and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the raw-JSON
+  textarea; the defaults keep browser editing assistance from changing JSON text
+- `spellcheck: boolean = false`, `autocapitalize: string = 'off'`, `autoCorrect: string = 'off'`
+  (`autocorrect`), `autocomplete: string = 'off'`, `wrap: 'hard'|'soft'|'off' = 'soft'`,
+  `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''` (`enterkeyhint`) —
+  forwarded to the raw-JSON `<textarea>` while editing.
 
 **Methods:** `close(reason: ToolApprovalDialogCloseReason = 'api'): void` — closes the dialog, emits
 `lyra-close` with `reason`, and returns focus to whatever had it before the dialog opened; a no-op if
@@ -7062,6 +7126,10 @@ menu, an avatar menu, or a history row's overflow menu. Uses the WAI-ARIA "menu
   a no-op for existing consumers), matching `lyra-select`/`lyra-model-select`'s
   `this.getAttribute('aria-label') || <computed default>` precedence
 
+- `closeOnEscapeAnywhere: boolean = false` (attribute `close-on-escape-anywhere`) — lets Escape
+  close the menu when focus is on slotted non-menu-item content inside the popup; item activation
+  remains scoped to actual menu items
+
 **Events:** `lyra-show` (no detail — fires only when `open` transitions to `true`, not for markup
 that renders `open` true from the start), `lyra-hide` (same first-render guard, opposite
 transition), `lyra-menu-select` (`detail: { value }` — a consolidated re-fire of the activated
@@ -7724,6 +7792,304 @@ available, the region becomes a standard `role="progressbar"` instead, self-desc
 
 ---
 
+## `lyra-document-viewer`
+
+A dialog-hosted, format-dispatching full viewer for one document or attachment. It uses a pluggable
+renderer registry and falls back to `<lyra-document-preview>` when no renderer matches the file's MIME
+type. First-party invention.
+
+**Properties:**
+- `open: boolean = false` (reflected) — opens or closes the viewer dialog.
+- `name: string = ''` — display name passed to the renderer and used as the dialog heading.
+- `mimeType: string = ''` (attribute `mime-type`) — MIME type used for exact renderer dispatch.
+- `src: string = ''` — source URL passed to the selected renderer or the fallback preview.
+- `registry?: DocumentRendererRegistry` (attribute: false) — optional per-instance registry override;
+  the module-level registry is used when unset.
+
+**Events:**
+- `lyra-close` — `detail: DocumentViewerCloseReason`, the nested dialog's dismissal reason. The
+  event is emitted after the viewer sets `open` to `false`.
+
+**CSS parts:** `body` — wrapper around the active renderer, loading/error state, or fallback preview.
+
+**Renderer registry exports:**
+- `DocumentFile` — `{ name: string; mimeType: string; src: string }`, the value passed to renderers.
+- `DocumentRendererDefinition` — optional `render(file)`, `matches(file)`, and lazy `load()` hooks.
+- `DocumentRendererRegistry` — `Map<string, DocumentRendererDefinition>`.
+- `registerDocumentRenderer(key, definition)` — adds or replaces a default-registry entry.
+- `findDocumentRenderer(file, registry?)` — checks an exact MIME-type key, then the first matching
+  `matches()` entry in registration order.
+- `loadDocumentRenderer(definition)` — resolves and identity-caches a lazy definition; rejected loads
+  are retried on the next call.
+
+```html
+<lyra-document-viewer
+  open
+  name="report.pdf"
+  mime-type="application/pdf"
+  src="/files/report.pdf"
+></lyra-document-viewer>
+```
+
+Register a renderer once during application setup. The definition may load a heavy optional viewer
+only when a matching document is opened:
+
+```ts
+import { registerDocumentRenderer } from '@aceshooting/lyra-ui';
+
+registerDocumentRenderer('application/x-example', {
+  render: (file) => `Preview: ${file.name}`,
+});
+```
+
+When no renderer matches, the viewer renders `<lyra-document-preview>`, which handles text and images
+inline and provides a safe generic fallback for other formats.
+
+## `lyra-docx-viewer`
+
+Fetches a `.docx` Word document as an `ArrayBuffer`, converts it to semantic HTML with the optional
+`mammoth` peer, sanitizes that HTML through the optional `dompurify` peer, and renders the result.
+Mammoth preserves document structure such as headings, paragraphs, lists, tables, and images; it is
+not intended to reproduce pixel-exact Word page layout. There is no unsanitized rendering escape
+hatch: if `dompurify` is unavailable, rendering is blocked even when Mammoth converted successfully.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `maxHeight` caps
+the scrollable document body.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching, conversion, sanitization, or a
+non-fatal Mammoth conversion message occurs.
+
+**CSS parts:** `base`, `body`, `content`, `spinner`, and `error`.
+
+**Optional peer dependencies:** install `mammoth` and `dompurify` with `pnpm add mammoth dompurify`.
+The component registers a lazy `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
+renderer with `<lyra-document-viewer>` and matches `.docx` filenames when the MIME type is generic.
+
+```html
+<lyra-docx-viewer src="/files/report.docx" name="report.docx" max-height="32rem"></lyra-docx-viewer>
+```
+
+## `lyra-email-viewer`
+
+Fetches and parses `.eml` messages with the optional `postal-mime` peer. HTML message bodies are
+sanitized through the existing optional `dompurify` peer before rendering; plain-text messages
+remain available without DOMPurify. Attachments are listed as filename/type/size metadata and their
+content is never rendered by this component.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching or parsing fails.
+
+**CSS parts:** `base`, `headers`, `from-label`, `from`, `to-label`, `to`, `subject-label`, `subject`,
+`date-label`, `date`, `body`, `body-html`, `body-text`, `attachments`, `attachments-label`,
+`attachment-list`, `attachment-item`, `spinner`, and `error`.
+
+**Optional peer dependencies:** install `postal-mime` and `dompurify` with
+`pnpm add postal-mime dompurify`. The component registers `message/rfc822` and falls back to
+matching `.eml` filenames in `<lyra-document-viewer>`.
+
+## `lyra-calendar-viewer`
+
+Fetches and parses `.ics` calendars with the optional `ical.js` peer and renders each VEVENT as
+plain text, including its title, start/end time, location, and description. No HTML is injected.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching or parsing fails.
+
+**CSS parts:** `base`, `body`, `event-list`, `event`, `event-summary`, `event-time`, `event-location`,
+`event-description`, `spinner`, and `error`.
+
+**Optional peer dependency:** install `ical.js` with `pnpm add ical.js`. The component registers
+`text/calendar` and falls back to matching `.ics` filenames in `<lyra-document-viewer>`.
+
+## `lyra-archive-viewer`
+
+Lists entry names and human-readable uncompressed sizes inside a `.zip` archive using the optional
+`jszip` peer. It is listing-only: entry content is never rendered or previewed. Files are measured
+through JSZip's public async API, so every file is decompressed once up front to obtain its size;
+there is no cheaper public uncompressed-size API. The list composes `<lyra-virtual-list>` for large
+archives.
+
+**Properties:** `src` and `name` are strings.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching or parsing fails.
+
+**CSS parts:** `base`, `entry`, `entry-icon`, `entry-name`, `entry-size`, `spinner`, and `error`.
+
+**Exports:** `ArchiveEntry` — `{ name: string; dir: boolean; size: number }`.
+
+**Optional peer dependency:** install `jszip` with `pnpm add jszip`. The lazy registry registers
+`application/zip` and `application/x-zip-compressed`, with a `.zip` filename fallback, and imports
+the viewer only when a matching archive is opened. `.tar`, `.rar`, and other archive formats fall
+through to `<lyra-document-preview>`'s generic download fallback.
+
+## `lyra-ebook-viewer`
+
+Renders EPUB ebooks through the optional `epubjs` peer. `src` is fetched as an `ArrayBuffer`, and
+epub.js renders the reading area into its stable `mount` element, using an internal iframe for
+chapter content.
+
+**Properties:** `src` and `name` are strings. `accessibleLabel` (attribute `aria-label`) overrides
+the reading region's accessible name.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching, opening, or rendering fails.
+
+**CSS parts:** `base`, `toolbar`, `previous-button`, `next-button`, `previous-icon`, `next-icon`,
+`mount`, and `error`.
+
+**Optional peer dependency:** install `epubjs` with `pnpm add epubjs`. The document-viewer registry
+matches `application/epub+zip` and `.epub` filenames.
+
+## `lyra-pptx-viewer`
+
+Best-effort client-side PPTX viewer backed by the optional `@aiden0z/pptx-renderer` peer. A
+localized fidelity notice is always visible because animations, equations, embedded objects,
+speaker notes, and several advanced effects are not rendered.
+
+**Properties:** `src`, `name`, and `label` are strings. A host `aria-label` also names the viewer
+region when `label` is unset.
+
+**Methods:** `goToSlide(index)` returns a promise and navigates the mounted presentation.
+
+**Events:** `lyra-load` (`detail: { slideCount }`), `lyra-slide-change` (`detail: { index, count }`),
+and `lyra-render-error` with `detail.error`.
+
+**CSS parts:** `base`, `header`, `name`, `notice`, `error`, `nav`, `previous-button`,
+`previous-icon`, `slide-count`, `next-button`, `next-icon`, and `container`.
+
+**Optional peer dependency:** install `@aiden0z/pptx-renderer` with
+`pnpm add @aiden0z/pptx-renderer`. The registry matches the official PPTX MIME type and `.pptx`
+filenames.
+
+## `lyra-file-icon`
+
+Localized, tokenized file-format badge for surrounding upload rows, cards, selectors, and viewer
+headers. The companion `getFileTypeMetadata(mimeType, fileName?)` utility covers common document,
+spreadsheet, presentation, code, archive, image, audio, and video formats. An explicit known MIME
+type wins; filename extension fallback is used only for an empty or `application/octet-stream`
+MIME type. Unknown values return a generic file result.
+
+**Properties:** `mimeType` (attribute `mime-type`), `name`, `label`, `decorative`, and
+`variant: 'icon' | 'label'`.
+
+**CSS parts:** `base`, `icon`, and `label`.
+
+**Exports:** `LyraFileTypeMetadata`, `LyraFileTypeIcon`, `LyraFileTypeCategory`,
+`getFileTypeMetadata()`, and `registerFileTypeMetadata()` for application-specific mappings.
+
+```html
+<lyra-file-icon mime-type="application/pdf" variant="label"></lyra-file-icon>
+```
+
+## `lyra-svg-viewer`
+
+Fetches an SVG document, sanitizes it with the optional `dompurify` peer, and renders it inline.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `maxHeight` caps
+the scrollable body.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching or sanitizing fails.
+
+**CSS parts:** `base`, `body`, `svg`, `spinner`, and `error`.
+
+**Optional peer dependency:** `dompurify`.
+
+## `lyra-html-viewer`
+
+Fetches an HTML document, sanitizes it with the optional `dompurify` peer, and renders the safe markup
+inside a bounded, scrollable body.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching or sanitizing fails.
+
+**CSS parts:** `base`, `body`, `html`, `spinner`, and `error`.
+
+**Optional peer dependency:** `dompurify`.
+
+## `lyra-dataset-viewer`
+
+Fetches tab-, pipe-, or delimiter-separated text and renders an accessible table using the optional
+`papaparse` peer. The document registry matches `.tsv`, `.psv`, and `.dat` filenames.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching or parsing fails.
+
+**CSS parts:** `base`, `body`, `table`, `spinner`, and `error`.
+
+**Exports:** `DatasetTable` is `{ fields: string[]; rows: Record<string, string>[] }`.
+
+**Optional peer dependency:** `papaparse`.
+
+## `lyra-contact-viewer`
+
+Fetches a vCard document and renders one accessible card per contact. The document registry matches
+`.vcf` filenames and common `FN`, `N`, `ORG`, `TEL`, `EMAIL`, and `ADR` fields are displayed.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching or parsing fails.
+
+**CSS parts:** `base`, `body`, `contact`, `contact-name`, `contact-org`, `contact-tel`,
+`contact-email`, `contact-adr`, `spinner`, and `error`.
+
+**Exports:** `parseVCards()` and the `VCardName`, `VCardTypedValue`, `VCardAddress`, and `VCardContact`
+types.
+
+## `lyra-pdf-viewer`
+
+Fetches a PDF and renders its pages with the optional `pdfjs-dist` peer. Pages are virtualized through
+`lyra-virtual-list`, and PDF.js's selectable text layer is positioned over each rendered canvas.
+
+**Properties:** `src` and `name` are strings. `page: number = 1` is the one-based current page and
+`zoom: number = 1` is clamped to `0.25`–`4`.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching, parsing, or rendering fails;
+`lyra-page-change` with `{ page, pageCount }`; and `lyra-zoom-change` with `{ zoom }`.
+
+**Methods:** `nextPage()`, `previousPage()`, `zoomIn()`, and `zoomOut()` update the corresponding
+controlled state within its supported range.
+
+**CSS parts:** `base`, `toolbar`, `page-indicator`, `zoom-indicator`, `pages`, `page`, `text-layer`,
+`spinner`, and `error`.
+
+**Optional peer dependency:** install `pdfjs-dist` with `pnpm add pdfjs-dist`. The component registers
+a lazy `application/pdf` renderer with `<lyra-document-viewer>` so the PDF library is loaded only when
+a PDF is opened.
+
+## `lyra-spreadsheet-viewer`
+
+Fetches and renders `.xlsx` and `.xls` workbooks with the optional `xlsx` (SheetJS) peer. Multiple
+worksheets render through a `<lyra-tabs>` switcher, and body rows use `<lyra-virtual-list>`.
+
+**Properties:** `src` and `name` are strings.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching or parsing fails.
+
+**CSS parts:** `base`, `tabs`, `sheet`, `header-row`, `data-row`, `cell`, `rows`, `spinner`, and
+`error`.
+
+**Optional peer dependency:** install `xlsx` with `pnpm add xlsx`. The registry matches the official
+`.xlsx` and `.xls` MIME types and filename extensions.
+
+## `lyra-csv-viewer`
+
+Fetches CSV text, parses quoted fields with the optional `papaparse` peer, and virtualizes body rows.
+
+**Properties:** `src` and `name` are strings. `hasHeaderRow: boolean = true` (attribute
+`has-header-row`) controls whether the first parsed row is rendered as a sticky header.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching or parsing reports an error.
+
+**CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `rows`, `spinner`, and `error`.
+
+**Optional peer dependency:** install `papaparse` with `pnpm add papaparse`. The registry matches
+`text/csv` and `.csv` filenames.
+
+---
+
 ## `lyra-media-card`
 
 A lightweight inline preview for one already-sent, already-available attachment inside a rendered
@@ -7843,6 +8209,8 @@ capability as a row.
   `'Attach files'`); only affects the single-capability button (`[part='trigger']`) — the
   multi-capability menu's own trigger keeps its fixed `'Add attachment'` label regardless. Unset
   (the default) keeps the built-in English default.
+- `triggerTitle?: string` (attribute `trigger-title`) — forwards a sighted-user hover tooltip to
+  both the single-capability and multi-capability trigger buttons
 
 **Events:** `lyra-pick` (`detail: { capability: 'files' | 'image'; files: FileList }`) — fired once a
 file-backed capability's hidden input produces a real selection. The `FileList` is an independent
@@ -8228,9 +8596,11 @@ markup.
 
 ## `lyra-callout`
 
-An inline status, warning, or error surface.
+An inline status, warning, or error surface. Set `inline` for lightweight reactive form or mutation
+errors without panel chrome.
 
-**Properties:** `variant`, `heading`, `closable`, `open`, and `accessibleLabel` (`accessible-label`).
+**Properties:** `variant`, `heading`, `closable`, `inline`, `open`, and `accessibleLabel`
+(`accessible-label`).
 
 **Events:** cancelable `lyra-close`; the callout hides after the event unless a listener calls
 `preventDefault()`.
@@ -8297,6 +8667,30 @@ properties `name`, `value`, `disabled`, and `required`, plus `label`, `hint`, an
 
 These apply across the whole library rather than to any one component:
 
+- **Independence and migration.** Lyra has no runtime, theme, or design-token dependency on
+  Shoelace or Web Awesome. The documented `wa-*` comparisons are migration references only; Lyra's
+  own `lyra-*` tokens, events, localization runtime, and implementation are the source of truth.
+  For a staged Web Awesome migration, map existing external theme-input values to `--lyra-theme-*` explicitly
+  in application CSS instead of relying on an implicit compatibility layer.
+
+- **Internationalization.** Built-in UI copy, accessible names, descriptions, validation messages,
+  status announcements, and empty/loading states resolve through `localize()` and the locale runtime.
+  Register an application catalog with `registerLyraLocale()` or override one instance with
+  `.strings`; locale fallback is exact locale, base language, then English. Date, number, byte,
+  relative-time, and calendar output uses `Intl`. Consumer data and slotted content are never
+  translated automatically.
+
+- **RTL and direction.** Direction is inherited from `dir`/`lang`; components do not force their own
+  direction. CSS logical properties mirror layout, while directional keyboard and pointer math
+  consults the effective direction. Test both LTR and RTL for any component with horizontal order,
+  start/end placement, drag deltas, or previous/next navigation.
+
+- **Accessibility and responsive behavior.** Semantic roles live on the shadow-DOM element that owns
+  them, with explicit false states for toggle/selection/expansion ARIA attributes and deliberate
+  host-name forwarding. Form-associated controls preserve `ElementInternals`, reset, validity,
+  focus, and native editing behavior. Reusable layouts respond to their allocated container, and
+  decorative/infinite motion simplifies under `prefers-reduced-motion: reduce`.
+
 - **Packaging.** `custom-elements.json` is now in `package.json`'s `files` allowlist and
   regenerated by a `prepack` script (`pnpm run manifest`) before publish, so a manifest-driven IDE/
   tooling integration (e.g. custom-elements-manifest-based autocomplete) does see an up-to-date copy