@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-thread-list.md

@@ -0,0 +1,157 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-thread-list`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/thread-list/thread-list.js';` (registers the tag; side-effect import)
+- **Class** `LyraThreadList`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/thread-list/thread-list.class.js`
+- **Family** `components/conversation/` — 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-thread-list`
+
+The conversation sidebar: a grouped, searchable list of chat sessions with pin/archive/delete/rename
+affordances. *Data mode* (non-empty `threads`, or empty `threads` with nothing slotted) renders every
+row as a `lr-conversation-item` inside an internal `lr-virtual-list` — virtualized by
+construction, scroll position and per-row state survive a `threads` replacement; zero rows renders
+the built-in empty state. *Slotted mode* (empty `threads` *and* real slotted content) renders
+host-supplied `lr-conversation-item`s from the default slot as-is: no grouping, virtualization, or
+row actions in that mode. No thread CRUD or persistence — every mutation
+(`lr-thread-pin`/`-archive`/`-delete`/`-rename`) is a controlled event carrying the *requested* new
+state; the host mutates `threads`.
+
+**Properties:** `threads: ChatThread[] = []` (attribute: false) — `ChatThread { id: string; title:
+string; excerpt?: string; timestamp?: Date | string; pinned?: boolean; archived?: boolean }`
+(exported here). `activeId: string = ''` (attribute `active-id`) — data mode:
+marks the matching row `active`/`aria-current` and scrolls it into view. `searchable: boolean =
+false` (reflected) — shows the built-in search field. `filter?: (thread, query) => boolean`
+(attribute: false) — overrides the default case-insensitive `title` + `excerpt` substring match.
+`grouping: 'date' | 'custom' | 'none' = 'date'` — data mode: bucket rows under localized date headers
+(Pinned/Today/Yesterday/Previous 7 days/Previous 30 days/one bucket per month/Archived), use the
+arbitrary grouping callbacks below, or render a flat list. `groupBy?: (thread: ChatThread) => string`
+(attribute: false) derives each group id in `grouping="custom"`; omitting it leaves the custom mode
+flat. `formatGroup?: (id: string, threads: ChatThread[]) => string | TemplateResult` (attribute:
+false) renders non-interactive custom group-label content. `groupOrder?: string[] | ((a: string, b:
+string) => number)` (attribute: false) supplies an explicit order or comparator; ids omitted from an
+array follow in first-seen order. `collapsedGroupIds: string[] = []` (attribute: false) is the
+controlled collapsed state for both date and custom groups. A collapsed group's header remains in
+the virtual list while its conversation rows are removed from the virtual-list item/measurement
+set; `lr-group-toggle` requests the matching state change. `rowActions: ThreadRowAction[] = []`
+(attribute: false, each `'pin' | 'archive' | 'delete'`) —
+data mode only: built-in icon buttons rendered into each row's `actions` slot. `showArchived: boolean
+= false` (attribute `show-archived`, reflected) — data mode: include `archived` threads (in their own
+trailing group). `editable: boolean = true` (reflected) — forwarded to each data-mode row's inline
+rename. `compact: boolean = false` (reflected) — data mode only: forwarded to each row
+`lr-conversation-item`'s own `compact`, tightening every row's padding and gaps from one attribute
+(the density itself lives on the row item; retune it through
+`--lr-conversation-item-compact-padding`/`-gap` on this element or any ancestor). Slotted mode is a
+deliberate no-op — that mode renders host-supplied items as-is, so the host sets `compact` on its own
+items there, the same division of responsibility slotted mode already has for every other row
+property. `stickyGroups: boolean = false` (attribute `sticky-groups`, reflected) — data mode: pins
+the current date/custom group's header to the top of the scroll viewport while its rows are in view,
+pushing it off as the next group's header arrives. Group headers are ordinary virtualized rows, so
+this renders an `aria-hidden` copy of the header into the internal `lr-virtual-list`'s sticky layer:
+the real row keeps the `role="heading"`/`aria-level` semantics and the tab order (the copy's toggle
+is not a second tab stop), while the pinned copy stays clickable and requests the same
+`lr-group-toggle` collapse. Default `false` renders exactly as before; `grouping="none"` has no
+headers to pin, so it is a no-op there. `label: string = ''` — accessible name for the list region,
+defaults to the localized `threadListLabel`. `wrapRow?: (thread: ChatThread, row: TemplateResult) =>
+TemplateResult` (attribute: false) — data mode only: wraps each row's built-in
+`lr-conversation-item` with host-supplied content that has no home in the item's own `title`/`excerpt`/`meta`/`actions` surface (e.g. a leading purpose
+icon — the item has no default slot to receive one); unset renders the built-in row unwrapped.
+`renderActions?: (thread: ChatThread) => TemplateResult` (attribute: false) — data mode only:
+appends host-supplied content (re-invoked per row on every render, e.g. a `lr-menu` with custom
+actions) after the built-in `rowActions` output in each row's `actions` slot; events it fires reach
+the host normally and never trigger `lr-select`. Unset renders only the built-in `rowActions`.
+`renderLeading?: (thread: ChatThread) => TemplateResult` (attribute: false) — renders non-interactive
+leading content in each virtualized row. `renderMeta?: (thread: ChatThread) => TemplateResult`
+(attribute: false) — appends structured metadata in the row's meta region.
+`renderRowContent?: (thread: ChatThread) => TemplateResult` (attribute: false) — replaces the
+conversation item's title/excerpt/meta content area with custom non-interactive row content.
+`formatGroupLabel?: (key: ThreadBucketKey, date?: Date) => string` (attribute: false) — overrides
+built-in date-group labels (use `formatGroup` for custom groups). `formatDate?: (date: Date) =>
+string` (attribute: false) — overrides month-group date formatting. `wrapRow` remains wholly
+host-owned and therefore receives no library-added wrapper part; use the focused `row-*` hook parts
+or add the host's own styling hook inside that callback.
+
+**Slots:** default — slotted mode only: host-supplied `lr-conversation-item`s, rendered in order.
+`empty` — replaces the built-in empty state.
+
+**Events:** (data mode; slotted mode only ever fires `lr-filter-change`) `lr-select` (`detail: {
+id }`), `lr-thread-pin` (`detail: { id, pinned }` — the requested new state), `lr-thread-archive`
+(`detail: { id, archived }`), `lr-thread-delete` (`detail: { id }`, no built-in confirmation),
+`lr-thread-rename` (`detail: { id, title }`, re-emitted from the row's `lr-rename`),
+`lr-filter-change` (`detail: { text, matchCount }`), `lr-group-toggle` (`detail: { id, collapsed }` —
+controlled intent; native group buttons provide Enter/Space activation and explicit
+`aria-expanded="true"|"false"`). `searchable` only: `blur`/`focus` (no detail) — re-dispatched from
+the internal search `<input>`'s own `blur`/`focus`, bubbling and composed unlike the native events,
+which are neither.
+
+**CSS parts:** `base`, `search`/`search-input` (the search field wrapper and `<input
+type="search">`), `list` (the list region), `empty`, `viewport` (the actual internal virtual-list
+scroll container, suitable for scrollbar styling), `row-action` (a built-in pin/archive/delete icon
+button), `pin-glyph` (the small pin indicator on a pinned row), `group-header`, `group-toggle`,
+`group-label`, `group-icon`, `group-sticky` (`sticky-groups` only: the pinned copy of the current
+group's header, exported from the internal `lr-virtual-list`'s sticky layer — it wraps a full copy of
+the `group-header`/`group-toggle`/`group-label`/`group-icon` markup, so those parts style the real
+header row and the pinned copy alike, and the band itself is where a shadow or bottom border
+belongs), `row` (all exported across the internal `lr-virtual-list` shadow
+boundary), `row-wrapper` (the wrapper around `wrapRow` output, only present when `wrapRow` is set;
+row-only — group headers are never passed through `wrapRow`, so they never carry it), and
+`row-leading`/`row-content`/`row-meta`/`row-actions` (the library-owned wrappers around
+their corresponding render-hook output; inherited fonts, layout values, and theme custom properties
+reach callback-rendered descendants through these parts).
+
+Data mode additionally forwards each row `<lr-conversation-item>`'s own parts under a `row-item-`
+prefix: `row-item-base`, `row-item-option`, `row-item-leading`, `row-item-content`,
+`row-item-title`, `row-item-title-input`, `row-item-rename-button`, `row-item-excerpt`,
+`row-item-meta`, `row-item-timestamp`, `row-item-actions`.
+
+**Keep the two prefixes straight — they are different surfaces.** The `row-*` parts wrap *this*
+component's own render-callback output (`wrapRow`, `renderLeading`, `renderRowContent`,
+`renderMeta`, `renderActions`); the `row-item-*` parts are the row item's *internals*. Row density
+in particular lives in `row-item-base`'s padding and `row-item-title`'s font size, so
+`::part(row-item-base)` is the supported way to build a dense sidebar.
+
+For plain row density, prefer the `compact` property above — it forwards straight to the row item's
+own density knob. The `row-item-*` parts remain the lever for tuning beyond it (a different font
+size, a different padding ratio):
+
+```css
+lr-thread-list::part(row-item-base) { padding-block: 0.25rem; }
+lr-thread-list::part(row-item-title) { font-size: 0.8125rem; }
+```
+
+Do **not** reach for `::part(row) { --lr-theme-space-s: … }` instead. That is a whole-subtree
+retheme: it shrinks everything nested inside the row, including the items of a `renderActions` menu,
+which pushes their touch targets below the accessible minimum. The `row-item-*` parts exist so row
+density can be tuned without that blast radius.
+
+**Sizing:** the internal list fills whatever height this component is given, with no consumer CSS —
+`[part='viewport']` is the real scroll container, and it falls back to `lr-virtual-list`'s own `24rem`
+default only when the container has no resolvable height. This is deliberately *not* implemented by
+setting `--lr-virtual-list-height: 100%`: that percentage resolves against this host, which is a flex
+item, so in an auto-height container it chains to `auto` and the viewport either collapses to zero
+(with no rows) or grows to the full un-virtualized content height (with rows) — defeating
+virtualization in both directions. Instead the list host is made a column flex container, which turns
+the shipped `24rem` into a *flex-basis*: it grows to fill a bounded pane, shrinks below `24rem` in a
+short one, and falls back to exactly `24rem` in an auto-height container.
+
+`sticky-groups` keeps the current date group's header visible while scrolling through a long sidebar;
+style the pinned band with `lr-thread-list::part(group-sticky)`.
+
+```html
+<lr-thread-list
+  searchable
+  sticky-groups
+  .threads=${threads}
+  active-id=${activeThreadId}
+  .rowActions=${['pin', 'archive', 'delete']}
+  @lr-select=${(e) => openThread(e.detail.id)}
+></lr-thread-list>
+```
+
+Composed with `lr-split` (or `lr-app-rail` + `lr-responsive-panel`): thread-list in the start
+pane driving `activeId`, `lr-chat-viewport` + `lr-chat-composer` in the main pane.

package/llms/components/lr-time-input.md

@@ -0,0 +1,54 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-time-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/input/time-input.js';` (registers the tag; side-effect import)
+- **Class** `LyraTimeInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/input/time-input.class.js`
+- **Family** `components/forms/` — 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-time-input`
+
+A migration-friendly time alias of `lr-input` — the same subclassing shape as `lr-number-input`,
+with the constructor and `connectedCallback()` setting `type = 'time'`. Its only own API is a
+re-typed `min`/`max` pair (below); every other property, event, slot and part is `lr-input`'s.
+
+**Properties:** `size` (`2xs`…`xl`), `placeholder`, `readonly`, `label`, `hint`, `errorText`
+(`error-text`), `accessibleLabel` (`aria-label`), `autocomplete`, `spellcheck`, `autocapitalize`,
+`autoCorrect` (`autocorrect`), `inputMode` (`inputmode`), and `enterKeyHint` (`enterkeyhint`).
+`clearable` and `passwordVisible` (`password-visible`) are inherited but inert, exactly as on
+`lr-number-input`.
+
+`step` is forwarded verbatim to the native time input, where it means seconds (`step="1"` reveals
+the seconds field, `'any'` disables step validation).
+
+`min?: string | number` / `max?: string | number` (attributes `min`/`max`, both defaulting to
+`undefined` — no bound) are re-declared here with a converter that forwards the attribute verbatim
+instead of `lr-input`'s numeric parsing, so they take the native `<input type="time">` literal form:
+`min="09:00"`, or `min="09:00:30"` alongside a seconds-precision `step`. Attribute and property are
+interchangeable (`el.min = '09:00'` needs no cast), removing the attribute clears the bound, and the
+native input's own constraint validation reports `rangeUnderflow`/`rangeOverflow` through
+`checkValidity()`.
+
+**Events:** `input`/`change` (native-style, composed), `lr-input`/`lr-change`
+(`detail: { value }`), `focus`/`blur` (re-dispatched bubbling + composed), and `lr-clear`
+(inherited, never fired here).
+
+**Slots:** `label`, `hint`, `error`, `start`, `end`.
+
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `start`, `end`,
+`hint`, `error`, plus the inherited, never-rendered `clear-button` and `password-toggle`.
+
+**Themeable custom properties:** inherited from `lr-input`, identical in meaning —
+`--lr-input-control-min-height`, `--lr-input-control-height`, `--lr-input-padding-block`,
+`--lr-input-padding-inline` and `--lr-input-font-size` (all but `--lr-input-control-height` swap
+per `size`; that one stays undeclared until you pin an exact row height).
+
+**Known gotchas:** the same two as `lr-number-input` — the inert clear/password surface, and `type`
+only being re-forced on connect. The native `type="time"` UI (spinners, AM/PM, picker) is the
+browser's own and is not restyled by Lyra.
+
+---

package/llms/components/lr-time-range.md

@@ -0,0 +1,107 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-time-range`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/time-range/time-range.js';` (registers the tag; side-effect import)
+- **Class** `LyraTimeRange`, also available unregistered from `@aceshooting/lyra-ui/components/forms/time-range/time-range.class.js`
+- **Family** `components/forms/` — 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-time-range`
+
+A two-handle brush/scrubber over a numeric domain (no date logic — callers map their own time axis
+onto `[min, max]`). Form-associated (`static formAssociated = true`, via `ElementInternals`): an
+ancestor `<fieldset disabled>` disables both handles and every preset button through an internal
+`effectiveDisabled` getter, the same way it would a native `<input>`, without ever mutating the
+consumer-facing `disabled` property/attribute itself.
+
+**Properties:**
+- `min: number = 0`
+- `max: number = 100`
+- `start: number = 0`
+- `end: number = 100`
+- `step: number = 1`
+- `disabled: boolean = false` (reflected)
+- `startLabel: string = 'Range start'` (attribute `start-label`) — `aria-label` for the start handle
+- `endLabel: string = 'Range end'` (attribute `end-label`) — `aria-label` for the end handle
+- `presets: TimeRangePreset[] = []` (attribute: false) — `TimeRangePreset { label: string; start:
+  number; end: number }`; optional discrete presets (e.g. "Last 7 days") rendered as a
+  `[part="presets"]` button row above the track — purely additive, the continuous brush is
+  unaffected and both interaction modes coexist; picking one sets both handles and emits the same
+  `lr-input`/`lr-change` pair a committed drag or keyboard step would
+
+**Events:** `lr-input` (fired continuously while dragging or on each arrow/Home/End/PageUp/
+PageDown key press, `detail: { start, end }`), `lr-change` (fired on pointer release /
+key-up-commit, or when a preset button is clicked, `detail: { start, end }`)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `track`, `range`, `handle-start`, `handle-end`, `presets`, `preset-button`
+
+**Themeable custom properties:** mostly shared tokens — `--lr-color-border`, `--lr-color-brand`,
+`--lr-color-surface`, `--lr-shadow` (track/handles), `--lr-opacity-disabled` (`:host([disabled])`
+dimming), plus (for `presets`) `--lr-color-text`, `--lr-color-on-brand` (the active preset
+button's text), `--lr-radius`, `--lr-space-xs/-s`, `--lr-transition-fast`,
+`--lr-focus-ring-*`.
+
+Three component-local properties recolor the **active** preset button independently of the shared
+palette: `--lr-time-range-preset-active-bg` (falls back to `--lr-color-brand`),
+`--lr-time-range-preset-active-border-color` (falls back to `--lr-color-brand`), and
+`--lr-time-range-preset-active-color` (falls back to `--lr-color-on-brand`). Unset, each resolves
+to exactly the token the rule used before they existed, so the default rendering is unchanged.
+
+They exist because the active preset is marked with an attribute on a part, and
+`::part(preset-button)[data-active]` is **invalid CSS** — an attribute selector cannot follow
+`::part()`. Without these, recoloring just the active preset meant hijacking the shared
+`--lr-color-brand`/`--lr-color-on-brand` tokens and repainting everything else that reads them.
+
+They are written as **inline `var()` fallbacks at the point of use, never declared on `:host`** —
+deliberately, because a `:host` declaration would shadow any value an ancestor set. Setting one on
+any ancestor of the `<lr-time-range>` therefore reaches it. (The same technique is used for
+`lr-emoji-picker`'s `--lr-emoji-picker-active-bg`.)
+
+**Optional peer deps:** none.
+
+```html
+<lr-time-range min="0" max="1440" start="480" end="1020" step="15"></lr-time-range>
+<script>
+  document.querySelector('lr-time-range')
+    .addEventListener('lr-change', (e) => console.log(e.detail.start, e.detail.end));
+</script>
+```
+
+**Known gotchas:**
+- Keyboard support now matches the full WAI-ARIA APG slider pattern: ArrowUp/Right and ArrowDown/Left
+  move by `step` (RTL-aware — under `direction: rtl` the forward/backward keys swap so they still
+  track the visually-adjacent direction), PageUp/PageDown move by `step * 10`, and Home/End jump to
+  that handle's actual *reachable* bound — clamped by the sibling handle's current value, not the
+  component's full `[min, max]` domain, so Home/End on the `end` handle can't jump past `start` (and
+  vice versa). Pointer-drag is RTL-aware the same way (mirrors the drag ratio under `direction:
+  rtl`).
+- A disabled handle now gets `aria-disabled="true"` in addition to losing `tabindex` — a
+  screen-reader user exploring by virtual cursor no longer hears it announced as a live, adjustable
+  slider.
+- `aria-valuemin`/`aria-valuemax` on each handle report that handle's reachable sub-range (bounded by
+  its sibling), not the full domain — matching what Home/End actually jump to.
+- No `aria-valuetext`: only raw numeric `aria-valuenow` is exposed (omitted entirely, rather than a
+  literal `"NaN"`, if `start`/`end` is non-finite), no hook for a human-readable (e.g. formatted
+  date/time) equivalent of the mapped domain.
+- Handles a `min > max` domain, a non-positive/non-finite `step`, and disabled-mid-drag/
+  disconnect-mid-drag correctly (tested) — safe to rely on those edge cases. Concurrent drags are
+  tracked per `pointerId` (not a single scalar), so a two-finger touch — one finger per handle —
+  moves both independently instead of the second pointer hijacking which handle the first pointer's
+  moves apply to; `pointercancel`/`lostpointercapture` (not just `pointerup`) both end a drag, same
+  fix as `lr-split`.
+- Non-finite domain/handle values use finite fallback geometry, and non-finite or negative steps are
+  treated as unstepped; invalid values never become `NaN`/`Infinity` CSS or ARIA strings.
+- `startLabel`/`endLabel` only override each handle's `aria-label`; they don't affect
+  `aria-valuenow`/`aria-valuemin`/`aria-valuemax` (still raw numbers) or any visible text.
+- An ancestor `<fieldset disabled>` toggling is reflected via `formDisabledCallback` into
+  `effectiveDisabled` (tracked separately from the consumer's own `disabled`), so re-enabling the
+  fieldset correctly restores a handle that had `disabled` set explicitly by the consumer, and vice
+  versa — mirrors `lr-combobox`'s identical pattern.
+
+---

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

@@ -0,0 +1,65 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-timeline-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/timeline/timeline-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraTimelineItem`, also available unregistered from `@aceshooting/lyra-ui/components/data/timeline/timeline-item.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-timeline` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-timeline` and `lr-timeline-item`
+
+Read-only chronological sequence. `lr-timeline` is a `role="list"` flex container; each
+`lr-timeline-item` is a light-DOM child that sets `role="listitem"` on itself and renders its own
+marker plus the trailing rail segment reaching toward the next item's marker. The last item's rail is
+suppressed purely in CSS (`::slotted([role='listitem']:last-child)`) — no JS coordination anywhere.
+Neither element has events, keyboard navigation, or a selection model: a passive record display, by
+design (an item's `title`/`description` routinely hold focusable content, so wrapping the row in
+`role="button"` would trip `nested-interactive`).
+
+**`lr-timeline` properties:** `orientation: 'vertical' | 'horizontal' = 'vertical'` — note the
+opposite default from `lr-stepper`; `horizontal` makes `[part='base']` a horizontally scrollable row.
+`accessibleLabel: string = ''` (attribute `aria-label`) overrides the localized `"Timeline"` name
+(the `role="list"` element is in the shadow root and never inherits a host attribute). Read-only
+`itemCount: number` is the live default-slot child count.
+
+**`lr-timeline-item` properties:** `timestamp?: Date | string | number` (attribute: false — `Date`
+isn't attribute-serializable; invalid input normalizes to unset and renders no timestamp UI),
+`sync: boolean = false` (forwarded to the internal `<lr-relative-time>`; no effect when the
+`timestamp` slot is filled), `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' =
+'neutral'` (marker tone), `active: boolean = false` (reflected — pulsing marker, disabled under
+`prefers-reduced-motion: reduce`, plus `aria-current="true"` on the host, removed entirely while
+inactive).
+
+**Events:** none on either element. Listen to the native `slotchange` if you need item-count changes.
+
+**Slots:** `lr-timeline`'s default slot holds the items, in display order. On an item the **default
+slot is the title** (there is no `title` slot), plus `icon` (marker glyph override; falls back to a
+color-coded dot), `timestamp` (wins outright over the `timestamp` property whenever it has assigned
+content), and `description` (its part is hidden entirely when empty).
+
+**CSS parts:** timeline `base` — the `role="list"` flex container (no separate `list` part). Item:
+`base`, `track` (marker + rail spine, always the opposite axis from `base`), `marker`
+(`aria-hidden="true"`, decorative), `rail` (the connecting segment; `visibility: hidden` rather than
+removed on the last item, so marker alignment stays consistent), `content`, `header` (flex row
+wrapping `title` and `timestamp`; wraps at narrow widths rather than truncating), `title`,
+`timestamp` (hidden when there's nothing to show), `description`.
+
+**Themeable custom properties:** `--lr-timeline-gap` (default `var(--lr-space-l)`) — declared on
+`lr-timeline` but consumed inside each item via inheritance across the slot boundary; it is both the
+inter-item spacing and the length each rail bridges. On the item: `--lr-timeline-marker-size`
+(default `var(--lr-size-1-25rem)`, both dimensions so the dot stays circular),
+`--lr-timeline-rail-width` (default `var(--lr-border-width-medium)`), `--lr-timeline-rail-color`
+(default `var(--lr-color-border)`), `--lr-timeline-marker-color` (default
+`var(--lr-color-text-quiet)`, swapped per `variant`; setting it directly on an item wins over the
+variant default).
+
+**Internal, not public:** `--lr-timeline-item-direction`, `--lr-timeline-item-track-direction`,
+`--lr-timeline-item-gap-block-end` and `--lr-timeline-item-gap-inline-end` (set by `lr-timeline`'s
+`:host` / `:host([orientation='horizontal'])` rules), plus `--lr-timeline-item-rail-visibility` (set
+by its `::slotted(:last-child)` rule) propagate orientation and last-item state across the slot
+boundary. Overriding any of them breaks layout rather than merely restyling it.

package/llms/components/lr-timeline.md

@@ -0,0 +1,65 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-timeline`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/timeline/timeline.js';` (registers the tag; side-effect import)
+- **Class** `LyraTimeline`, also available unregistered from `@aceshooting/lyra-ui/components/data/timeline/timeline.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-timeline-item` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-timeline` and `lr-timeline-item`
+
+Read-only chronological sequence. `lr-timeline` is a `role="list"` flex container; each
+`lr-timeline-item` is a light-DOM child that sets `role="listitem"` on itself and renders its own
+marker plus the trailing rail segment reaching toward the next item's marker. The last item's rail is
+suppressed purely in CSS (`::slotted([role='listitem']:last-child)`) — no JS coordination anywhere.
+Neither element has events, keyboard navigation, or a selection model: a passive record display, by
+design (an item's `title`/`description` routinely hold focusable content, so wrapping the row in
+`role="button"` would trip `nested-interactive`).
+
+**`lr-timeline` properties:** `orientation: 'vertical' | 'horizontal' = 'vertical'` — note the
+opposite default from `lr-stepper`; `horizontal` makes `[part='base']` a horizontally scrollable row.
+`accessibleLabel: string = ''` (attribute `aria-label`) overrides the localized `"Timeline"` name
+(the `role="list"` element is in the shadow root and never inherits a host attribute). Read-only
+`itemCount: number` is the live default-slot child count.
+
+**`lr-timeline-item` properties:** `timestamp?: Date | string | number` (attribute: false — `Date`
+isn't attribute-serializable; invalid input normalizes to unset and renders no timestamp UI),
+`sync: boolean = false` (forwarded to the internal `<lr-relative-time>`; no effect when the
+`timestamp` slot is filled), `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' =
+'neutral'` (marker tone), `active: boolean = false` (reflected — pulsing marker, disabled under
+`prefers-reduced-motion: reduce`, plus `aria-current="true"` on the host, removed entirely while
+inactive).
+
+**Events:** none on either element. Listen to the native `slotchange` if you need item-count changes.
+
+**Slots:** `lr-timeline`'s default slot holds the items, in display order. On an item the **default
+slot is the title** (there is no `title` slot), plus `icon` (marker glyph override; falls back to a
+color-coded dot), `timestamp` (wins outright over the `timestamp` property whenever it has assigned
+content), and `description` (its part is hidden entirely when empty).
+
+**CSS parts:** timeline `base` — the `role="list"` flex container (no separate `list` part). Item:
+`base`, `track` (marker + rail spine, always the opposite axis from `base`), `marker`
+(`aria-hidden="true"`, decorative), `rail` (the connecting segment; `visibility: hidden` rather than
+removed on the last item, so marker alignment stays consistent), `content`, `header` (flex row
+wrapping `title` and `timestamp`; wraps at narrow widths rather than truncating), `title`,
+`timestamp` (hidden when there's nothing to show), `description`.
+
+**Themeable custom properties:** `--lr-timeline-gap` (default `var(--lr-space-l)`) — declared on
+`lr-timeline` but consumed inside each item via inheritance across the slot boundary; it is both the
+inter-item spacing and the length each rail bridges. On the item: `--lr-timeline-marker-size`
+(default `var(--lr-size-1-25rem)`, both dimensions so the dot stays circular),
+`--lr-timeline-rail-width` (default `var(--lr-border-width-medium)`), `--lr-timeline-rail-color`
+(default `var(--lr-color-border)`), `--lr-timeline-marker-color` (default
+`var(--lr-color-text-quiet)`, swapped per `variant`; setting it directly on an item wins over the
+variant default).
+
+**Internal, not public:** `--lr-timeline-item-direction`, `--lr-timeline-item-track-direction`,
+`--lr-timeline-item-gap-block-end` and `--lr-timeline-item-gap-inline-end` (set by `lr-timeline`'s
+`:host` / `:host([orientation='horizontal'])` rules), plus `--lr-timeline-item-rail-visibility` (set
+by its `::slotted(:last-child)` rule) propagate orientation and last-item state across the slot
+boundary. Overriding any of them breaks layout rather than merely restyling it.

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

@@ -0,0 +1,123 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-toast-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/toast/toast-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraToastItem`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/toast/toast-item.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-toast` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-toast` / `lr-toast-item` / `toast()`
+
+Stacking toast/notification region. Mirrors `<wa-toast>`/`<wa-toast-item>` under `lr-`.
+
+### `lr-toast`
+
+One per page recommended — the region.
+
+**Properties:**
+- `placement: ToastPlacement = 'top-end'` (reflected) — one of `'top-start'|'top-center'|'top-end'|
+  'bottom-start'|'bottom-center'|'bottom-end'`
+
+**Methods:** `async create(message: string, options?: ToastCreateOptions): Promise<LyraToastItem>` —
+`ToastCreateOptions = { variant?, duration?, size?, withIcon? }`
+
+**Events:** none.
+
+**Slots:** default (`<lr-toast-item>` children)
+
+**CSS parts:** `stack`
+
+**Themeable custom properties:** `--lr-toast-gap` (default `var(--lr-space-s)`),
+`--lr-toast-width` (default `28rem`) — set directly on the `<lr-toast>` element.
+
+**Optional peer deps:** none.
+
+### `lr-toast-item`
+
+A single notification.
+
+**Properties:**
+- `duration: number = 5000` (ms; `Infinity` or `<= 0` disables auto-dismiss)
+- `size: 'xs'|'s'|'m'|'l'|'xl' = 'm'` (reflected — drives both `--lr-toast-padding` and the toast's own
+  font-size via `:host([size=...])`, from a compact `xs` up to a roomier `xl`)
+- `variant: 'brand'|'success'|'warning'|'danger'|'neutral' = 'neutral'` (reflected)
+- `withIcon: boolean = false` (attribute `with-icon`)
+
+**Methods:** `async hide(): Promise<void>` — plays the hide animation, then removes itself from the
+DOM.
+
+**Events:** `lr-show`, `lr-after-show`, `lr-hide`, `lr-after-hide`
+
+**Slots:** default (message), `icon`
+
+**CSS parts:** `toast-item`, `accent`, `icon`, `content`, `close-button`
+
+**Themeable custom properties:** `--lr-toast-accent-width` (4px),
+`--lr-toast-show-duration`/`--lr-toast-hide-duration`
+(`var(--lr-transition-base, 180ms ease-out)` — 180ms by default, matching the JS-side show/hide
+animation timer, which is not itself reading this token), `--lr-toast-padding`
+(`var(--lr-space-m)`), `--lr-toast-font-size` (`1rem`) — both are auto-swapped per `size`, from a
+compact `xs` up to a roomier `xl` — `--lr-toast-accent-color` (defaults to `--lr-color-border`,
+auto-swapped per `variant` to `--lr-color-brand/-success/-warning/-danger`).
+
+**Optional peer deps:** none.
+
+`role` is chosen automatically per `variant`: `"alert"` for `danger`/`warning`, `"status"`
+otherwise — re-evaluated on every `variant` change, not just at first render, so reassigning
+`variant` to `danger`/`warning` after creation is announced as an interruption instead of keeping
+its original, now-stale role. Auto-dismiss timer **pauses** on `pointerenter`/`focusin`, **resumes**
+on `pointerleave`/`focusout`, with real elapsed-time bookkeeping (WCAG 2.2.1 timing-adjustable) —
+hover and focus are tracked as independent pause reasons, so releasing only one (e.g. the pointer
+leaves while focus remains, or vice versa) keeps the timer paused until *neither* holds it anymore.
+A `duration` change while the timer is actively counting down reschedules it immediately against
+the new value instead of waiting for the next pause/resume cycle.
+
+### `toast()`
+
+From the `toaster` controller — the ergonomic entry point, no manual `<lr-toast>` mounting
+needed:
+
+```ts
+import { toast } from '@aceshooting/lyra-ui';
+
+toast('Saved');
+toast({ message: 'Deleted', variant: 'danger', action: { label: 'Undo', onClick: (item) => {/*...*/} } });
+```
+
+`toast(input: ToastOptions | string): ToastHandle` where
+`ToastOptions = ToastCreateOptions & { message: string; placement?: ToastPlacement; action?: { label: string; onClick: (item: LyraToastItem) => void } }`,
+and `ToastHandle = { item: Promise<LyraToastItem>; dismiss: () => void }`. Lazily mounts (and
+re-mounts if removed) **one singleton `<lr-toast>` region per distinct `placement`** on
+`document.body` — a `toast()` call targeting one placement never relocates toasts already showing
+at another, since `placement` is a per-call option rather than a single global region's setting.
+
+```html
+<script type="module">
+  import { toast } from '@aceshooting/lyra-ui';
+  document.getElementById('save-btn').addEventListener('click', () => toast('Saved!'));
+</script>
+```
+
+**Known gotchas:**
+- possible nested live-region double-announcement: the stack region is
+  `role="status" aria-live="polite"` **and** each `lr-toast-item` independently self-assigns its
+  own `role` (`status`/`alert`) — nesting live regions can cause some screen readers to announce a
+  new toast twice. Plausible from the code, unverified against real AT.
+- the close button's accessible name is derived from the toast's own message text (`"Close: <first
+  40 chars>…"`, falling back to bare `"Close"` only when the toast has no text content) rather than
+  a bare `"Close"` on every instance — useful when several toasts are stacked and a screen-reader or
+  switch-access user needs to tell their close buttons apart without activating one first.
+- pause/resume-on-hover/focus (the component's main accessibility differentiator), including the
+  independent-hover-vs-focus pause reasons above, now has regression test coverage.
+- `hide()` is idempotent (a second call while already hiding is a no-op) and `[part="close-button"]`
+  gets `aria-disabled="true"` once hiding starts, so a stray extra click/Enter during the hide
+  animation can't re-enter it.
+- Prefer the `toast()` helper over manually creating `<lr-toast>`/`<lr-toast-item>` — it already
+  handles the singleton-region and remount-if-removed logic.
+
+---