@aceshooting/lyra-ui 5.0.0 → 5.2.0

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

@@ -0,0 +1,223 @@
+<!-- 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 non-menu-item content slotted into the **default** slot, i.e.
+  rendered inside `[part="list"]`; item activation remains scoped to actual menu items. It has no
+  bearing on the `header`/`footer` slots, which sit outside the `role="menu"` list and always close
+  on Escape — so a menu that keeps its composed controls there never needs this property
+
+**Methods:** `show(focus: 'first' | 'last' = 'first')` opens the menu and moves roving focus to the
+first (or, with `'last'`, the last) non-disabled item; a no-op when already open.
+`hide(options?: { focusTrigger?: boolean })` closes it; a no-op when already closed. They are the
+imperative pair for the cases the slotted trigger can't express — a "Done"/"Apply" button *inside*
+the menu, a keyboard shortcut, a parent restoring UI state — without hand-reproducing the
+pending-focus bookkeeping. Both are deliberately thin: positioning, the outside-click listener, the
+`lr-show`/`lr-hide` events, and the initial focus move all stay in one place, so **writing `open`
+directly is fully supported and equivalent apart from the focus moves**. In particular the
+roving-tabindex reset is centralized, so a bare `el.open = false` also clears `activeIndex` and
+never leaves a stale `tabindex="0"` tab stop on the last active item. `hide()` never refocuses
+unless you ask: pass `{ focusTrigger: true }` for a dismissal with nowhere else for focus to land,
+and leave it off when the interaction that closed the menu already put focus somewhere the user
+chose (an outside click, a Tab out). Focus restoration lives in `hide()` rather than in the
+close branch precisely so teardown — disconnecting an open menu — can't steal focus.
+
+**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),
+`header` and `footer` (composed, deliberately non-menu-item content — a filter/search field, a
+section title, an "Apply"/"Done" button, a count — rendered above/below the items inside
+`[part="popup"]` but **outside** the `role="menu"` list. Both collapse to no box at all while
+unfilled, so a menu that uses neither renders exactly as it did before they existed)
+
+Put composed controls in `header`/`footer` rather than the default slot. Non-item content in the
+default slot still works and is not deprecated at runtime (no warning is emitted), but it sits
+inside `role="menu"`, where ARIA permits only
+`menuitem`/`menuitemradio`/`menuitemcheckbox`/`group`/`separator` children — anything else is an
+`aria-required-children` violation. It is also not Tab-reachable from an item, and needs
+`closeOnEscapeAnywhere` before Escape will close the menu. The named regions have none of those
+problems.
+
+**CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
+positioned floating panel), `header` (wrapper around the `header` slot, above the list and outside
+`role="menu"`; `display: none` while that slot is unfilled), `list` (the `role="menu"` container
+wrapping the default slot), `footer` (wrapper around the `footer` slot, below the list and outside
+`role="menu"`; `display: none` while that slot is unfilled)
+
+**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. The arrow keys,
+Home/End, Enter/Space and type-ahead only respond 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. Escape and Tab are the two deliberate exceptions.
+Escape from `header`/`footer` content always closes the menu and refocuses the trigger (mirroring
+`lr-popover`'s handling of arbitrary popup content), while Escape from non-item content in the
+*default* slot closes it only with `closeOnEscapeAnywhere` set. Tab never traps focus and never
+calls `preventDefault()` — the browser's own Tab navigation always proceeds untouched — and closes
+the menu only when focus is on its way *out* of `[part="popup"]`: with a focusable in the
+`header`/`footer` region on the far side of the keypress the menu stays open so native Tab can carry
+focus there, and with neither region filled Tab closes exactly as it always has. Tabbing past the
+popup's last focusable in either direction closes the menu, including from slotted non-item content
+— which previously left the menu open while focus walked out of the popup entirely. 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 never calls `preventDefault()` and never traps focus — the browser's own default Tab
+  navigation always proceeds untouched. It closes the menu only when Tab would leave
+  `[part="popup"]` entirely; when the `header`/`footer` region holds a focusable on the far side of
+  the keypress, the menu stays open instead and native Tab moves focus into it. With neither region
+  filled, Tab closes exactly as before.
+- Non-item content in the *default* slot is not Tab-reachable from an item — Tab from an
+  `<lr-menu-item>` still closes the menu when there is no `header`/`footer` focusable to move to,
+  even if a `<button>` is slotted alongside the items. Move such controls to `header`/`footer`.
+- `header`/`footer` emptiness is tracked from each slot's own `slotchange` and reflected on the host
+  as `data-has-header` / `data-has-footer` (plus `data-list-empty`, which suppresses the region
+  divider next to an empty list). They are internal styling hooks, not public API — don't set them
+  by hand — but they are why `[part="header"]`/`[part="footer"]` collapse cleanly: a
+  `[part]:empty` rule can never match a part that contains a slot, since Chromium counts the
+  whitespace-only text nodes Lit leaves there.
+- 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,52 @@
+<!-- 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`), `attachment-name` (an attachment's filename, inside `attachment-button`),
+`attachment-size` (an attachment's formatted file size, inside `attachment-button`), `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,95 @@
+<!-- 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`.
+
+Ships the same opt-in `label`/`hint`/`errorText` form-control chrome as `lr-select`/
+`lr-color-picker` (props + matching named slots + `form-control`/`form-control-label`/`hint`/
+`error` CSS parts) — left unset, none of that chrome renders.
+
+**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. `label: string = ''` — visible label rendered above the
+search/grid; unset renders no label chrome. When `label` (or the `label` slot) is set and
+`accessibleLabel`/a host `aria-label` is not, the grid's accessible name switches from the
+localized default to `aria-labelledby` pointing at the visible label. `hint: string = ''` —
+supporting text rendered below the search/grid; unset renders no hint chrome. `errorText: string =
+''` (attribute `error-text`) — validation-error text rendered below the hint (overridden by slotted
+`error` content when provided); unset renders no error chrome.
+
+**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.
+
+**Slots:** `label` (custom label content), `hint` (custom hint content), `error` (custom error
+content, overrides the `errorText` attribute when provided).
+
+**CSS parts:** `form-control` (the outer wrapper around label, `base`, error and hint),
+`form-control-label` (the visible label), `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), `hint` (the hint message), `error` (the
+error message). 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.
+
+`--lr-emoji-picker-active-bg` recolors the highlight behind the active/hovered emoji, falling back
+to `--lr-color-brand-quiet` when unset — so the default rendering is unchanged. Hover and
+keyboard-active deliberately share one declaration, so this single hook retints both consistently.
+It exists because `::part(emoji)[data-active]` is **invalid CSS** (an attribute selector cannot
+follow `::part()`), which previously left hijacking the shared `--lr-color-brand-quiet` token — and
+repainting everything else that reads it — as the only way in. Like `lr-time-range`'s preset
+properties, it is written as an inline `var()` fallback at the point of use rather than declared on
+`:host`, so a value set on **any ancestor** reaches it instead of being shadowed.
+
+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,59 @@
+<!-- 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),
+`--lr-empty-compact-gap` (default `--lr-space-2xs` — gap between the icon, heading, and description
+in compact mode; the non-compact layout's gap stays the plain shared `--lr-space-s` token, not
+independently themeable), 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.
+
+---

package/llms/components/lr-entity-card.md

@@ -0,0 +1,77 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-entity-card`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/entity-card/entity-card.js';` (registers the tag; side-effect import)
+- **Class** `LyraEntityCard`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/entity-card/entity-card.class.js`
+- **Family** `components/retrieval/` — 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-entity-card`
+
+A dossier card for one knowledge-graph entity: type badge, description, key/value property rows,
+degree, community chip, plus a built-in "focus in graph" action. Never fetches or focuses a graph
+itself — `lr-entity-activate` is a request a host routes into `lr-graph`'s own
+`focusNode(id, options?)`.
+
+**Properties:**
+- `entity: LyraEntity | null = null` (attribute: false) — `LyraEntity { id: string; label: string;
+  type?: string; description?: string; properties?: Record<string, string | number>; degree?:
+  number; communityId?: string }`; field names deliberately mirror `lr-graph`'s `GraphNode`
+  additions, so a graph node adapts into a `LyraEntity` with no mapping table; `null` renders the
+  empty state
+- `types: NodeTypeStyle[] = []` (attribute: false) — the same `lr-graph.nodeTypes`/
+  `lr-graph-legend.types` entry shape, resolving `entity.type` to a label/color/shape for the badge
+- `communityLabel: string = ''` (attribute `community-label`) — override text for the community chip
+- `showFocusButton: boolean = true` (attribute `show-focus-button`)
+- `compact: boolean = false` (reflected) — tighter root padding and row gap for dense contexts (a
+  dossier rendered in a sidebar, a result list) — the same convention as `lr-empty`'s `compact` and
+  as this component's sibling `lr-community-card`. Purely a density knob: the border and background
+  stay. `false` (the default) keeps the full card padding.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled, padded box; `'plain'`
+  removes the border, background, padding and corner radius, so a card nested inside a container
+  that already draws a border doesn't double the frame. `plain` wins over `compact` when both are
+  set — there is nothing left to tighten.
+
+**Events:** `lr-entity-activate` (`detail: { id }`, the built-in focus button was activated).
+
+**Slots:** default (extra body content below the property rows, e.g. a `lr-neighbor-list`),
+`actions` (extra header actions alongside the built-in focus button).
+
+**CSS parts:** `base`, `header`, `type-badge`, `title` (`role="heading" aria-level="3"` by default),
+`description`, `properties`, `property` (one key/value row), `degree`, `community`, `actions`,
+`focus-button`, `empty` (shown when `entity` is `null`).
+
+**Themeable custom properties:** `--lr-entity-card-compact-padding` (default `var(--lr-space-s)`) —
+`[part='base']`'s padding while `compact`; `--lr-entity-card-compact-gap` (default
+`var(--lr-space-xs)`) — the gap between `[part='base']`'s rows while `compact`. Both apply only in
+the `compact` state, so a dense card can be tuned without re-pointing shared spacing tokens for
+everything else. Otherwise shared tokens; a data-driven `entity.type` color is applied as
+sanitized inline `--lr-badge-*` overrides on the type badge only (the one "type color is
+data-driven by design" exception this library already grants graph nodes) — every other color comes
+from tokens.
+
+**Optional peer deps:** none.
+
+```html
+<lr-entity-card id="card"></lr-entity-card>
+<script>
+  document.getElementById('card').entity = {
+    id: 'e1', label: 'Ada Lovelace', type: 'person',
+    description: 'Mathematician', properties: { born: 1815 }, degree: 4,
+  };
+  document.getElementById('card').addEventListener('lr-entity-activate', (e) => graph.focusNode(e.detail.id));
+</script>
+```
+
+**Known gotchas:**
+- The type badge's data-driven background uses an 8% (not this codebase's usual 16%) quiet-tint mix
+  against `--lr-color-surface` — the lower percentage is required to hold WCAG AA 4.5:1 text
+  contrast for arbitrary, unvetted type colors (even 10% isn't safe margin for every hue in the
+  palette).
+
+---