@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-doughnut-chart.md

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-doughnut-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/doughnut-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraDoughnutChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/doughnut-chart.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## Typed subclasses: `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`
+
+Each is `LyraChart` with `type` locked to a fixed value — respectively `line`, `bar`, `pie`,
+`doughnut`, `radar`, `polarArea`, `bubble`, `scatter` — via a real `get`/`set` accessor pair the
+shared `lockChartType()` helper installs on the subclass's own prototype (`declare type: '…'`
+narrows the TS type at compile time; the runtime lock is the `Object.defineProperty` pair alongside
+it — the same helper `lr-histogram` uses), not merely a class-field default a later assignment
+could still override.
+
+Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
+and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
+of every entry in these lists.**
+
+**Properties:** `labels`, `datasets`, `legend`, `legendPosition` (attribute `legend-position`),
+`valueFormatter`, `area`, `zoom`, `height`, `xLabel` (`x-label`), `yLabel` (`y-label`), `y2Label`
+(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `config`, `accessibleLabel`
+(`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
+(`show-data-table`), `chartArea` (readonly). `type` is the only member that differs: read-only,
+locked to this tag's value.
+
+**Methods:** `resetZoom()`, `refreshTheme()`.
+
+**Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-point-click` (`detail: { datasetIndex,
+index, label, value }`).
+
+**Slots:** `data-table`, `center`.
+
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`.
+
+**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
+`--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
+`--lr-chart-tooltip-text`.
+
+**Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
+`zoom` is set.
+
+```html
+<lr-bar-chart legend></lr-bar-chart>
+<lr-pie-chart></lr-pie-chart>
+<script>
+  document.querySelector('lr-bar-chart').labels = ['A', 'B'];
+  document.querySelector('lr-bar-chart').datasets = [{ label: 'Count', data: [4, 9] }];
+
+  document.querySelector('lr-pie-chart').labels = ['A', 'B', 'C'];
+  document.querySelector('lr-pie-chart').datasets = [{ label: 'Share', data: [30, 45, 25], color: ['#2563eb', '#16a34a', '#dc2626'] }];
+</script>
+```
+
+**Known gotchas (in addition to the core `lr-chart` list in `llms/components/lr-chart.md`):**
+- `type` truly is locked per subclass: `<lr-pie-chart type="bar">` or `el.type = 'bar'` at runtime
+  is a genuine no-op (the accessor's setter silently ignores the write), not a footgun like a plain
+  overridden class-field default would be.
+- `lr-bubble-chart` needs `Series.points` entries with an `x`/`y`/`r` triple, but `Series.points`
+  is typed as `{x, y, label?}[]` with no `r` field — cast the array through `as unknown as
+  Series['points']` (or a local `BubblePoint` type) when constructing bubble data.
+
+---

package/llms/components/lr-drawer.md

@@ -0,0 +1,48 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-drawer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/drawer/drawer.js';` (registers the tag; side-effect import)
+- **Class** `LyraDrawer`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/drawer/drawer.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-drawer`
+
+A modal panel anchored to one edge of the viewport. It inherits the dialog overlay contract:
+focus trapping, Escape and optional backdrop dismissal, document scroll locking, overlay stacking,
+accessible naming, and the cancelable `lr-dialog-close` event.
+
+**Properties:**
+- `open: boolean = false` (attribute `open`, reflected) — controls visibility
+- `placement: 'start'|'end'|'top'|'bottom' = 'start'` (attribute `placement`, reflected)
+- `heading?: string`, `label: string`, `closable: boolean`, and `noLightDismiss: boolean` — inherited
+  dialog naming and dismissal options. A plain `aria-label` attribute on the host is honored too,
+  with the same priority-over-everything semantics documented under `lr-dialog` below
+
+**Events:** `lr-dialog-close` (`detail: DialogCloseReason`) — inherited unchanged from `lr-dialog`.
+
+**Slots:** default (drawer body), `footer` — inherited from `lr-dialog`.
+
+**CSS parts:** `backdrop`, `panel`, `header`, `heading`, `close-button`, `label`, `body`, `footer`.
+
+**Themeable custom properties:** `--lr-drawer-width` (default `--lr-size-24rem`; used by
+`placement="start"|"end"`, capped at `100%`), `--lr-drawer-height` (default `--lr-size-24rem`;
+used by `placement="top"|"bottom"`), `--lr-drawer-enter-x` / `--lr-drawer-enter-y` (the panel's
+entrance-animation translate offset — `-x` for start/end, `-y` for top/bottom; both default to
+`±--lr-size-1rem` and are set per `placement`, with `-x` explicitly flipped under `:dir(rtl)` since
+`translateX` is physical. Override to lengthen/shorten the slide-in; the animation is dropped
+entirely under `prefers-reduced-motion: reduce`). It also inherits `<lr-dialog>`'s own tokens —
+`--lr-dialog-overlay-color`, `--lr-dialog-width` and `--lr-dialog-max-width` — since `LyraDrawer`
+extends `LyraDialog`; the drawer's own width tokens take precedence for its panel.
+
+```html
+<lr-drawer open placement="end" heading="Filters" closable>
+  <lr-checkbox label="Only active"></lr-checkbox>
+</lr-drawer>
+```
+
+---

package/llms/components/lr-drilldown-panel.md

@@ -0,0 +1,25 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-drilldown-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraDrilldownPanel`, also available unregistered from `@aceshooting/lyra-ui/components/layout/drilldown-panel/drilldown-panel.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-drilldown-panel`
+
+Controlled navigation shell from a chart or table datum to related evidence, documents, entities,
+or agent runs. It renders a breadcrumb path and delegates category content to existing primitives.
+
+**Properties:** `path: DrilldownNode[] = []` and `types: NodeTypeStyle[] = []` (both attribute:
+false), `accessibleLabel: string | null = null` (attribute `aria-label` — names the nested
+`lr-tabs`; unset renders no `aria-label` at all, matching `lr-tabs`' own default),
+`communityLabel: string = ''` (attribute `community-label`), `showFocusButton: boolean = true`
+(attribute `show-focus-button`). **Events:**
+`lr-drilldown-navigate` (`detail: { id, index }`). **Slots:** `runs`. **CSS parts:** `base`,
+`breadcrumb`, `breadcrumb-item`, `breadcrumb-button`, `tabs`, `category`, `content`, `evidence-item`,
+`document-item`, `entity-item`, `empty`.

package/llms/components/lr-dropdown-item.md

@@ -0,0 +1,171 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-dropdown-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/menu/dropdown-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraDropdownItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/menu/dropdown-item.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-menu`, `lr-menu-item` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-menu` / `lr-menu-item`
+
+An anchored dropdown built around a consumer-supplied trigger element (typically an icon button)
+assigned to the `trigger` slot. First-party invention (no Web Awesome equivalent) — a close, drop-
+in-shaped replacement for reaching outside this library for a third-party dropdown to build a gear
+menu, an avatar menu, or a history row's overflow menu. Uses the WAI-ARIA "menu button" pattern —
+`role="menu"`/`role="menuitem"` with real roving DOM focus moving between actual focusable
+`<lr-menu-item>` rows — deliberately not a `role="listbox"`/`aria-activedescendant` shape (that's
+`<lr-select>`'s pattern instead).
+
+### `lr-menu`
+
+**Properties:**
+- `open: boolean = false` (reflected)
+- `placement?: Placement` (reflected — resolved through `rtlAwarePlacement()` (`internal/rtl.ts`),
+  then forwarded to `place()`; defaults to whatever `place()` itself defaults to. A `left`/`right`
+  side is mirrored under `dir="rtl"`, so e.g. `placement="left-start"` still anchors to the menu's
+  trailing edge instead of pinning to the physical left)
+- `label: string = 'Menu'` — accessible name for the `role="menu"` popup; override with something
+  specific (e.g. "Row actions") when a page has more than one menu. A host-level `aria-label`
+  attribute takes precedence over both this prop and the localized default (unset by default, so
+  a no-op for existing consumers), matching `lr-select`/`lr-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:** `lr-show` (no detail — fires only when `open` transitions to `true`, not for markup
+that renders `open` true from the start), `lr-hide` (same first-render guard, opposite
+transition), `lr-menu-select` (`detail: { value }` — a consolidated re-fire of the activated
+`<lr-menu-item>`'s own `lr-menu-item-select`; always followed by the menu closing and focus
+returning to the trigger)
+
+**Slots:** `trigger` (the consumer's own trigger element — first assigned element wins if several
+are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
+since those attributes belong on the actual interactive trigger, which lives outside this
+component's shadow root), default (`<lr-menu-item>` elements, plus optionally plain `<hr>`
+dividers between groups — native `<hr>` already carries an implicit `separator` role)
+
+**CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
+positioned floating panel), `list` (the `role="menu"` container wrapping the default slot)
+
+**Themeable custom properties:** shared tokens only (`--lr-color-surface`, `--lr-color-border`,
+`--lr-radius`, `--lr-shadow`, `--lr-space-xs`, `--lr-transition-fast`).
+
+**Optional peer deps:** none.
+
+### `lr-menu-item`
+
+Not meaningful standalone — it exists purely as `<lr-menu>`'s light-DOM child, the same
+relationship `<lr-option>` has to `<lr-combobox>`/`<lr-select>`. `role="menuitem"` and the
+roving `tabindex` both live on the host element itself (mirroring `<lr-tree-node>`), not an
+internal shadow-DOM button; `<lr-menu>` is the sole owner of this element's `tabIndex`.
+
+**Properties:**
+- `value: string = ''` — an id/value echoed back in the parent `<lr-menu>`'s `lr-menu-select`
+  detail
+- `disabled: boolean = false` (reflected — disables selection and excludes this item from
+  `<lr-menu>`'s roving-tabindex navigation entirely)
+- `destructive: boolean = false` (reflected — tints the row with `--lr-color-danger`, for a
+  dangerous action like "Delete")
+- `type: 'normal' | 'checkbox' = 'normal'` — `'checkbox'` (mirroring `wa-dropdown-item`'s identical
+  `type` option) renders `role="menuitemcheckbox"` in place of `role="menuitem"`, with `aria-checked`
+  reflecting `checked` and a checkmark glyph shown once `checked` is `true`. `'normal'` (the default)
+  renders and behaves exactly as before this option existed.
+- `checked: boolean = false` (reflected) — whether a `type="checkbox"` item is checked; meaningless
+  (ignored) for `type="normal"`
+
+**Methods:** `select(): void` — fires `lr-menu-item-select` (no-op while `disabled`). Called
+internally by this element's own click handler and by `<lr-menu>`'s Enter/Space keydown handling
+of the roving-focused item; also the cleanest way for a consumer/test to trigger selection
+programmatically instead of clicking the shadow-DOM `[part="base"]` element (see the gotcha below).
+For `type="checkbox"`, also toggles `checked` and fires `lr-menu-item-change` first.
+
+**Events:** `lr-menu-item-select` (no detail payload — `this.emit('lr-menu-item-select')` is
+called with no second argument, so `event.detail` is `null`, not `undefined`; fires on click, or
+when the parent `<lr-menu>`'s own Enter/Space keydown handling calls `select()` on the currently
+roving-focused item), `lr-menu-item-change` (`detail: { value, checked }` — fired when a
+`type="checkbox"` item is activated and its `checked` state toggled, in addition to — never instead
+of — `lr-menu-item-select`; never fired for `type="normal"`)
+
+**Slots:** default (the item's label content), `icon` (optional leading icon)
+
+**CSS parts:** `base` (the row — `role` lives on the host, not this part), `icon` (wrapper around
+the `icon` slot; not rendered/hidden entirely while the slot is empty), `label` (wrapper around the
+default slot), `checkmark` (the checkmark glyph shown when a `type="checkbox"` item is `checked`;
+not rendered at all for `type="normal"`)
+
+**Themeable custom properties:** shared tokens only (`--lr-radius`, `--lr-focus-ring-width`,
+`--lr-focus-ring-color`, `--lr-space-xs`, `--lr-space-s`, `--lr-color-brand-quiet`,
+`--lr-opacity-disabled`, `--lr-color-danger`, `--lr-color-danger-quiet`).
+
+**Optional peer deps:** none.
+
+### `lr-dropdown-item`
+
+Compatibility naming alias for `<lr-menu-item>`. It is a subclass of the same implementation,
+so `value`, `disabled`, `destructive`, `type`, `checked`, `select()`, checkbox events, and menu
+roving focus behave identically.
+
+**Slots:** default label content and optional `icon`.
+
+```html
+<lr-menu>
+  <button slot="trigger">Actions</button>
+  <lr-dropdown-item value="archive">Archive</lr-dropdown-item>
+</lr-menu>
+```
+
+```html
+<lr-menu label="Row actions">
+  <button slot="trigger" aria-label="More actions">⋮</button>
+  <lr-menu-item value="edit">Edit</lr-menu-item>
+  <lr-menu-item value="duplicate">Duplicate</lr-menu-item>
+  <hr />
+  <lr-menu-item value="delete" destructive>Delete</lr-menu-item>
+</lr-menu>
+<script type="module">
+  document.querySelector('lr-menu').addEventListener('lr-menu-select', (e) => console.log(e.detail.value));
+</script>
+```
+
+The popup is always rendered in the DOM (never `display:none`) so `.focus()` calls on its content
+work synchronously the instant it opens — closed state is conveyed via `visibility`/`opacity`
+instead. `visibility` is an inherited CSS property that pierces the `<slot>` projection boundary, so
+every closed-state `<lr-menu-item>` is automatically excluded from sequential (Tab-key)
+navigation with no separate JS bookkeeping. ArrowDown/ArrowUp *on the trigger while closed* also
+opens the menu, focusing the first/last non-disabled item respectively (mirrors native `<select>`).
+Once open, ArrowDown/ArrowUp move the roving focus among non-disabled items and wrap past either end
+(unlike `<lr-select>`'s clamped listbox nav); Home/End jump to the first/last non-disabled item;
+Enter/Space activate the focused item; Escape closes and refocuses the trigger; Tab closes without
+`preventDefault()`, letting the browser's own Tab navigation proceed untouched. All of this list-level
+keydown handling — Escape, Tab, the arrow keys, Home/End, and type-ahead alike — only responds when
+the triggering keydown event's own target is an actual `<lr-menu-item>` element; a keydown bubbling
+up from any other node inside the popup is ignored rather than misread as list navigation. A printable
+keypress runs type-ahead: roving focus jumps to the next non-disabled item whose text starts with the
+accumulated buffer (cycling from just after the active item, buffer resets ~500ms after the last
+keystroke) — mirrors `<lr-select>`'s identical listbox type-ahead. A click outside both the trigger
+and the open popup also closes it, but deliberately does *not* refocus the trigger — the outside
+click itself already moved focus somewhere the user chose.
+
+**Known gotchas:**
+- `<lr-menu-item>`'s click handler lives on an inner shadow-DOM element (`[part="base"]`), not the
+  host — calling `.click()` directly on the `<lr-menu-item>` host element in a test does **not**
+  trigger selection; either click (or dispatch on) the element returned by
+  `menuItemEl.shadowRoot.querySelector('[part="base"]')`, or just call the item's own `select()`
+  method directly.
+- `lr-show`/`lr-hide` are suppressed on the very first render even if `open` is already `true`
+  in markup — only later `open` transitions fire them.
+- `lr-menu-item-select` carries no detail payload (`event.detail === null`); read
+  `event.target.value` instead. `<lr-menu>`'s own re-fired `lr-menu-select` is the one that
+  carries `detail: { value }`.
+- Tab closes the menu without `preventDefault()` or focus trapping — the browser's own default Tab
+  navigation proceeds untouched, only the (now-stale) open state is cleared.
+- Only Escape and a committed selection refocus the trigger on close; a click outside does not.
+
+---

package/llms/components/lr-dropdown.md

@@ -0,0 +1,24 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-dropdown`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/overlay/dropdown.js';` (registers the tag; side-effect import)
+- **Class** `LyraDropdown`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/overlay/dropdown.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-dropdown`
+
+A menu-role popover for consumer-supplied action content. Compose `lr-menu` when full roving
+menu-item behavior is needed.
+
+**Properties:** `open`, `placement`, `distance`, `accessibleLabel` (`aria-label`), and `popupRole` (`popup-role`).
+`popupRole` is seeded to `'menu'` in the constructor — that is the only difference from `lr-popover`,
+whose whole surface (including `showAt()`) is inherited unchanged.
+**Events:** `lr-show`, `lr-hide` — inherited from `lr-popover`; neither fires for the initial render.
+**Slots:** `trigger`, default menu content. **CSS parts:** `trigger`, `popup`, `content`.
+**Themeable custom properties:** `--lr-overlay-max-inline-size` (default `--lr-size-20rem` —
+maximum inline size of the popup).

package/llms/components/lr-ebook-viewer.md

@@ -0,0 +1,60 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-ebook-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/ebook-viewer/ebook-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraEbookViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/ebook-viewer/ebook-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `epubjs` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-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. `location: string = ''` (not reflected — CFIs are long) is
+a CFI or spine href identifying the current reading position: set before the book finishes
+loading it's recorded and applied once ready, set after it applies immediately, and epub.js's own
+`relocated` event keeps it in sync with user navigation without re-triggering its own `display()`
+call. `anchorKinds` is a readonly `['cfi', 'text-quote']` (this viewer's supported `LyraAnchor.kind`
+values for the shared anchor-target contract).
+
+**Methods:** `getToc()` resolves the EPUB's own navigation document (`book.navigation.toc`,
+populated once `book.ready` resolves) flattened into document-ordered `EbookTocItem[]` (`{ id,
+label, href, level }`, `level` starting at 1 for a top-level entry, `id` falling back to `href`
+when a navigation entry has none), `[]` before a book has loaded. `search(query)` resolves the
+match count across every spine section, in document order, via epub.js's own `item.load()`/
+`item.find()`/`item.unload()` (empty/whitespace query behaves like `clearSearch()`; a newer
+`search()` call or a `src` change aborts an in-flight scan); `searchNext()`/`searchPrevious()`
+advance/step back through matches (wrapping, resolving `false` when there are none); `clearSearch()`
+clears the query, matches, and painted search annotation.
+
+**Events:** `lr-render-error` with `detail.error` when fetching, opening, or rendering fails;
+`lr-location-change` (`detail: { cfi, href }`) fired from epub.js's own `relocated` event;
+`lr-search-change` (`detail: { query, matchCount, activeIndex }`) from `search()`/`searchNext()`/
+`searchPrevious()`/`clearSearch()`.
+
+**CSS parts:** `base`, `toolbar`, `previous-button`, `next-button`, `previous-icon`, `next-icon`,
+`mount`, `error`, and `announcer` (the visually-hidden `role="status"` region search results
+announce through).
+
+**Optional peer dependency:** install `epubjs` with `pnpm add epubjs`. The document-viewer registry
+matches `application/epub+zip` and `.epub` filenames, declaring `{ anchors: ['cfi', 'text-quote'],
+search: true, textSelect: true }` capabilities.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the ebook.
+
+Adopts the shared anchor-target contract (`highlights`, `activeHighlightId`, `scrollToAnchor()`,
+events `lr-highlight-activate`/`lr-text-select`/`lr-anchor-result`): a `cfi` anchor displays
+directly via `rendition.display()`; a `text-quote` anchor resolves by scanning the spine with
+epub.js's own `item.find()`, since chapter content lives inside epub.js-owned iframes rather than
+this component's own shadow DOM — `lr-text-select` mirrors epub.js's own `selected` event for the
+same reason. `highlights` (kind `cfi`) paint via `rendition.annotations.highlight()` and are
+re-applied whenever the rendition is recreated (a `src` change, or a reconnect remount), since
+epub.js doesn't persist annotations across a fresh `renderTo()`.

package/llms/components/lr-email-viewer.md

@@ -0,0 +1,51 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-email-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraEmailViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/email-viewer/email-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `dompurify`, `postal-mime` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-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 and size only (the parsed
+`mimeType` never reaches the DOM) and their content is never rendered by this component. Each
+attachment row is a real `<button>` that emits `lr-attachment-open` with the decoded bytes; opening,
+downloading, or object-URL'ing them is the host's job (e.g.
+`URL.createObjectURL(new Blob([content], { type: mimeType }))` → `<lr-document-viewer>` → revoke on
+`lr-close`).
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the message.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `foldQuotes:
+boolean = false` (attribute `fold-quotes`) — collapses trailing quoted-reply text/HTML behind a
+localized show/hide toggle. `false` (the default) preserves the full body rendering.
+
+**Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
+`lr-attachment-open` — `detail: { attachment: { filename, mimeType, content? } }`, `content` a
+`Uint8Array` of the decoded attachment — an attachment button was activated.
+
+**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`, `attachment-button` (an attachment's open button, inside its
+`attachment-item`), `quoted` (a folded quoted-text block, hidden until expanded, only
+while `foldQuotes`), `quote-toggle` (the show/hide-quoted-text toggle button, only while `foldQuotes`),
+`spinner`, and `error`.
+
+**Themeable custom properties:** `--lr-email-viewer-max-height` (default `none`) — maximum block size
+of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+
+**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 `<lr-document-viewer>`. Deviates from the shared degraded-render
+contract: an absent `postal-mime` renders `[part="error"]` with the localized
+`emailViewerMissingParser` message (nothing is parseable without it), and an HTML-only message
+(no `text/plain` alternative) with `dompurify` absent renders the localized
+`documentViewerMissingSanitizer` message rather than silently showing an empty body.

package/llms/components/lr-emoji-picker.md

@@ -0,0 +1,71 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-emoji-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/emoji-picker/emoji-picker.js';` (registers the tag; side-effect import)
+- **Class** `LyraEmojiPicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/emoji-picker/emoji-picker.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** `emoji-picker-element-data` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-emoji-picker`
+
+A searchable, keyboard-navigable, form-associated emoji picker. `groups` is fully consumer-suppliable
+— the component ships no emoji data of its own — in the same "zero/optional-peer dependency" spirit
+as `<lr-lite-chart>`/`<lr-heatmap>`; an optional convenience auto-loader fetches a default set on
+connect from the `emoji-picker-element-data` peer, but only when `groups` hasn't already been
+supplied (an explicit empty array still counts as supplied and skips the auto-load).
+When the filtered set reaches 200 items, the grid automatically windows its visible rows while
+preserving the full option count through `aria-setsize`/`aria-posinset`.
+
+**Properties:** the shared form properties `name`, `value`, `disabled`, and `required`, plus
+`groups: EmojiPickerGroup[] = []` (attribute: false) — `EmojiPickerGroup { key, label, emojis:
+EmojiPickerItem[] }`, `EmojiPickerItem { emoji, name, shortcodes? }`; the search field matches `name`
+and every `shortcodes` entry, case-insensitively. Empty (the default, before the auto-loader
+resolves) renders just the search input and the empty state. `accessibleLabel` (`aria-label`)
+forwards a host-supplied accessible name to the internal `role="listbox"` grid; empty falls back to
+the localized default grid label.
+
+**Events:** `lr-change` with `detail: { emoji }` (an emoji was picked — click, or Enter/Space on
+the active grid cell; also sets `value`), plus the shared form `input`, `change`, `focus`, and `blur`.
+
+**Keyboard:** the grid is a roving-tabindex listbox (a single Tab stop — only the active emoji is
+tabbable). ArrowLeft/ArrowRight step the active item backward/forward following reading direction
+(swapped under RTL), ArrowUp/ArrowDown move by one visual row (measured from the live wrap layout),
+Home/End jump to the first/last item, and Enter/Space picks the active item. The search input is a
+`role="combobox"` over the same listbox: the arrow keys and Enter also work while focus stays in
+the input, with `aria-activedescendant` tracking the active option. Hovering an emoji with the
+pointer also moves the active item to it.
+
+**CSS parts:** `base`, `search` (`role="combobox"`), `grid` (`role="listbox"`, the scroll
+viewport), `group-label`, `emoji` (each emoji's own `role="option"` button), `empty` (shown when
+the search matches nothing). While windowing is active the rows are wrapped in `virtual-spacer`
+(full-height scroll spacer), `virtual-row` (one absolutely-positioned row), `virtual-label` (an
+`aria-hidden` spacer standing in for a row's missing `group-label`), and `virtual-items` (the row's
+emoji flex line).
+
+**Themeable custom properties:** `--lr-emoji-picker-item-size` (default `--lr-icon-button-size`,
+each emoji button's box), `--lr-emoji-picker-gap` (default `--lr-space-2xs`, the gap between
+emoji within a windowed row), and `--lr-emoji-picker-row-height` (default
+`calc(var(--lr-emoji-picker-item-size) + var(--lr-space-l))`, one windowed row's height). All three
+are also read back in JS to derive columns-per-row and row offsets for the windowed layout,
+resolved to real pixels by measuring hidden probe boxes the component's own stylesheet sizes from
+those same tokens — so any CSS length unit works, `rem`/`em` and `calc()` included, and the windowed
+geometry matches what is painted without expressing the tokens in `px`. The measurement is cached
+and re-derived only when the resolved pixels can actually change (a token override applied after the
+first render, a theme swap, a root or host font-size change feeding a `rem`/`em` value), never per
+frame.
+
+Two constraints remain. `--lr-emoji-picker-item-size` is clamped up to `--lr-icon-button-size`, the
+shared minimum tappable box: a smaller value does not shrink the button, and the windowed geometry
+follows the clamped, painted size. And windowed rows are absolutely positioned at the row-height
+pitch, so `--lr-emoji-picker-row-height` must stay at or above the item size plus the group-label
+band (`--lr-space-l`) — the default's own formula — or consecutive rows overlap. Columns per
+windowed row are additionally capped at 20 regardless of available width.
+
+**Optional peer dependency:** install `emoji-picker-element-data` with
+`pnpm add emoji-picker-element-data` for the built-in auto-loaded default emoji set — omit it and
+supply `groups` directly instead. The loader never throws; a missing or failed peer logs one
+`console.warn` and simply leaves `groups` empty.

package/llms/components/lr-empty.md

@@ -0,0 +1,56 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-empty`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/empty/empty.js';` (registers the tag; side-effect import)
+- **Class** `LyraEmpty`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/empty/empty.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-empty`
+
+First-party "no data" state (no Web Awesome equivalent).
+
+**Properties:**
+- `heading: string = ''`
+- `description: string = ''`
+- `compact: boolean = false` (reflected) — tighter, left-aligned rendering (less padding, a lighter
+  heading weight) for use inside a constrained space like a widget body or table cell, instead of
+  the centered/spacious full-page default
+
+**Events:** none.
+
+**Slots:** default (icon/illustration), `heading` (rich heading content, overrides the `heading`
+attribute), `description` (rich description content, overrides the `description` attribute),
+`actions` (buttons/links below the description)
+
+**CSS parts:** `base`, `icon`, `heading`, `description`, `actions`
+
+**Themeable custom properties:** `--lr-empty-compact-align` (compact mode only; defaults preserve
+the existing `flex-start` cross-axis and `start` text alignment, and `center` centers both),
+`--lr-empty-compact-padding` (default `--lr-space-xs` — padding used in compact mode), plus
+shared tokens (`--lr-space-xs/-s/-l`, `--lr-color-text-quiet/-border/-text`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-empty heading="No results" description="Try a different search.">
+  <svg slot="" ...></svg> <!-- default slot: any icon/illustration -->
+  <div slot="actions"><button>Clear filters</button></div>
+</lr-empty>
+<lr-empty compact heading="No results" description="Try a different search."
+  style="--lr-empty-compact-align: center"></lr-empty>
+```
+
+**Known gotchas:**
+- `[part="base"]` is `role="status" aria-live="polite"`, so a list/table transitioning to empty
+  does announce to screen readers — no extra wiring needed on the host's part.
+- Note: correctly works around the classic `:empty`-pseudo-class trap (a wrapper with a `<slot>`
+  inside can never match `:empty`) by tracking real slot assignment in JS (`hasIcon`/`hasActions`) —
+  `lr-table` reuses this component for its own empty-rows state, and `lr-stat` (below) now uses
+  the same JS-tracked-slot-state pattern for its own icon/caption wrappers.
+
+---