@aceshooting/lyra-ui 4.2.0 → 5.1.0

package/llms/components/lr-textarea.md

@@ -0,0 +1,111 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-textarea`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/textarea/textarea.js';` (registers the tag; side-effect import)
+- **Class** `LyraTextarea`, also available unregistered from `@aceshooting/lyra-ui/components/forms/textarea/textarea.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-textarea
+
+A multiline plain-text input primitive, form-associated (participates in native `<form>`
+submission/validation/reset via `name`/`value`/`disabled`/`required`/`checkValidity()`/
+`reportValidity()`). Ships an opt-in `label`/`hint`/`errorText` form-control chrome mirroring
+`lr-select` -- left unset, none of it renders.
+
+```html
+<lr-textarea placeholder="Notes" rows="4"></lr-textarea>
+```
+
+### Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `value` | `string` | `''` | The current text value. |
+| `rows` | `rows` | `number` | `3` | Visible text rows. |
+| `resize` | `resize` | `'none' \| 'vertical' \| 'both' \| 'auto'` | `'vertical'` | Native CSS `resize` behavior, plus `'auto'` (`ResizeObserver`-driven grow-to-content, no manual handle). |
+| `placeholder` | `placeholder` | `string` | `''` | Placeholder text. |
+| `label` | `label` | `string` | `''` | Visible label text. Unset: no label chrome renders. |
+| `hint` | `hint` | `string` | `''` | Hint text below the field. |
+| `errorText` | `error-text` | `string` | `''` | Error text below the field (overridden by slotted `error` content). |
+| `accessibleLabel` | `aria-label` | `string \| null` | `null` | Accessible-name override forwarded to the internal `<textarea>`; wins over `label`, `placeholder`, and the localized default. |
+| `spellcheck` | `spellcheck` | `boolean` | `true` | Forwarded to the native `<textarea>`. |
+| `autocapitalize` | `autocapitalize` | `string` | `''` | Forwarded to the native `<textarea>`; empty omits the attribute. |
+| `autoCorrect` | `autocorrect` | `string` | `''` | Forwarded to the native `<textarea>` (Safari/WebKit-specific); empty omits the attribute. |
+| `wrap` | `wrap` | `'hard' \| 'soft' \| 'off'` | `'soft'` | Native line-wrapping/submission behavior. |
+| `autocomplete` | `autocomplete` | `string` | `''` | Forwarded to the native `<textarea>`; empty omits the attribute. |
+| `inputMode` | `inputmode` | `string` | `''` | Virtual-keyboard input hint forwarded to the native `<textarea>`. |
+| `enterKeyHint` | `enterkeyhint` | `string` | `''` | Virtual-keyboard Enter-key hint forwarded to the native `<textarea>`. |
+| `name` | `name` | `string` | `''` | Form field name. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the control. |
+| `required` | `required` | `boolean` | `false` | Participates in native constraint validation. |
+
+The visible label, hint, and error live in the same shadow tree as the native control, so their
+generated ids safely drive the native `<label>`/`aria-describedby` relationships. Name precedence
+is `accessibleLabel`/host `aria-label`, visible `label`, `placeholder`, then the localized
+`textareaLabel` message. External `aria-labelledby`/`aria-describedby` idrefs are not copied across
+the shadow boundary.
+
+### Getters and selection properties
+
+- `input: HTMLTextAreaElement | null` — the internal native control.
+- `selectionStart: number | null`, `selectionEnd: number | null`, and
+  `selectionDirection: 'forward'|'backward'|'none'|null` — readable and writable passthroughs to
+  the native selection state.
+- The shared form-associated getters `form`, `labels`, `validity`, `validationMessage`,
+  `willValidate`, and `effectiveDisabled` are also available.
+
+### Methods
+
+| Method | Description |
+| --- | --- |
+| `focus(options?)` / `blur()` | Focus or blur the internal native control. |
+| `select()` | Select all text. |
+| `setSelectionRange(start, end, direction?)` | Set the native selection range and optional direction. |
+| `setRangeText(replacement, start?, end?, selectMode?)` | Apply a native range edit, then synchronize the component `value`, form value, validity, and auto-grown size without emitting a user event. |
+| `setFormValue(value)` | Set the reactive and submitted value synchronously. |
+| `checkValidity()` / `reportValidity()` | Run native constraint validation through `ElementInternals`. |
+
+### Events
+
+| Event | Detail | Description |
+| --- | --- | --- |
+| `lr-input` | `{ value: string }` | Fired on every user-driven edit. |
+| `lr-change` | `{ value: string }` | Fired on native `change` timing (blur after a committed edit). |
+| `blur` | none | Re-dispatched from the internal native `<textarea>`'s own `blur` -- bubbling and composed, unlike the native event. |
+| `focus` | none | Re-dispatched from the internal native `<textarea>`'s own `focus`, for the same reason as `blur`. |
+
+Programmatic property assignments, selection changes, `setRangeText()`, form reset, and form-state
+restoration are silent. User edits update `value`, submitted form data, and required validity before
+the corresponding `lr-input`/`lr-change` event is dispatched. `form.reset()` restores the
+original declarative `value`, matching native `defaultValue` behavior.
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| `label` | Custom label content. |
+| `hint` | Custom hint content. |
+| `error` | Custom error content. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `form-control` | The outer wrapper around label, textarea, error and hint. |
+| `form-control-label` | The `<label>` element. |
+| `textarea` | The native `<textarea>` element. |
+| `hint` | The hint message. |
+| `error` | The error message. |
+
+### Themeable custom properties
+
+- `--lr-textarea-max-block-size` (default `none`) — bounds `resize="auto"`; content beyond the
+  bound scrolls inside the native textarea. Auto-resize remeasures after user edits, programmatic
+  `value`/`rows` changes, range edits, and container-width changes.
+
+---

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

@@ -0,0 +1,93 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-thinking-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/thinking-panel/thinking-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraThinkingPanel`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/thinking-panel/thinking-panel.class.js`
+- **Family** `components/agent-tools/` — 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-thinking-panel`
+
+A collapsible panel for an AI agent's intermediate reasoning/"thinking" transcript, kept visually
+and semantically distinct from its final response. First-party invention (no Web Awesome
+equivalent). Same collapsible header-button-plus-region shape as `<lr-source-list>`; the default
+slot is entirely free-form (a consumer-composed `<lr-streaming-text>`, `<lr-markdown>`, or
+plain text) — this component has no dependency on either.
+
+**Properties:**
+- `label: string = 'Thinking'`
+- `expanded: boolean = false` (reflected) — starts collapsed, matching `<lr-source-list>`'s
+  default.
+- `mode: 'live' | 'post-hoc' = 'live'` (reflected) — `'live'` while reasoning is actively streaming
+  in; `'post-hoc'` once it's complete and being reviewed after the fact. Drives two concrete
+  behavior differences, see prose below.
+- `durationMs?: number` (attribute `duration-ms`) — how long the reasoning took. Omitted entirely
+  (nothing rendered in `'post-hoc'`, a pulsing placeholder in `'live'`) while unset.
+
+**Methods:** `scrollToBottom(): void` — scrolls `[part="body"]` to its current bottom immediately
+(no smooth-scroll animation). Safe to call directly, e.g. from a host that wants to force a
+jump-to-latest action of its own.
+
+**Events:** `lr-toggle` (`detail: { expanded: boolean }`, same event name and shape as
+`<lr-source-list>`'s own `lr-toggle`) — fired whenever the header button is activated.
+
+**Slots:** default (the reasoning/thinking content; entirely free-form)
+
+**CSS parts:** `base`, `header`, `label`, `duration`, `toggle`, `body`
+
+**Themeable custom properties:** `--lr-thinking-panel-max-block-size` (default `16rem` —
+consumer-overridable cap on how tall `[part="body"]` grows before it scrolls internally; not
+exposed as a component property since it's a pure layout knob, not something a template branches
+on), plus shared `--lr-color-border`/`-surface`/`-text`/`-text-quiet`/`-brand`/`-brand-quiet`,
+`--lr-space-xs`/`-s`/`-m`, `--lr-radius`, `--lr-focus-ring-width`/`-color`/`-offset`,
+`--lr-transition-fast`/`-base`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-thinking-panel label="Reasoning" mode="live" expanded>
+  <lr-streaming-text content="Considering the user's constraints…" streaming></lr-streaming-text>
+</lr-thinking-panel>
+
+<lr-thinking-panel label="Reasoning" mode="post-hoc" duration-ms="4200">
+  <p>Finished reasoning, collapsed by default.</p>
+</lr-thinking-panel>
+```
+
+`mode` drives two concrete behavior differences, not just a styling hook. **Header hint:** while
+`duration-ms` is unset, `'live'` shows a pulsing "Thinking…" placeholder in `[part="duration"]`;
+`'post-hoc'` shows nothing there. Once `duration-ms` is set, both modes show the same static
+"Thought for …" text. **Auto-scroll:** only `'live'` mode auto-follows new content appended to the
+default slot while `expanded`; `'post-hoc'` never scrolls on its own.
+
+Live-mode auto-scroll ("stick to bottom") is the classic chat-transcript convention: while
+`mode="live"` and `expanded`, new content keeps the panel scrolled to its latest line — unless the
+user has manually scrolled up to re-read earlier content (tracked via a `scroll` listener on
+`[part="body"]`: every user-driven scroll records whether the body was left within 48px of its own
+max scroll position, and only a mutation that arrives while that's still true triggers a follow-up
+scroll). Opening an already-`'live'` panel — or a still-`expanded` panel later becoming `'live'` —
+always resets this to "anchored" and jumps to the latest content. New content is detected via a `MutationObserver` on this element's own light DOM
+(`childList`+`subtree`+`characterData`), not `slotchange`, since streamed reasoning typically
+appends chunks to an existing node's `textContent` rather than re-slotting a whole new element per
+token; scroll-to-bottom calls are coalesced to at most one per animation frame under a fast token
+stream.
+
+**Known gotchas:**
+- The `MutationObserver` only watches this element's own light-DOM subtree — it cannot see a
+  mutation that happens entirely inside a slotted custom element's own shadow root (e.g. a
+  `<lr-markdown>` re-rendering its shadow tree after a `content` change). A slotted element whose
+  own internal updates should drive auto-scroll needs to append/mutate visible light-DOM text
+  itself (as `<lr-streaming-text>` does), or the host can call `scrollToBottom()` directly.
+- Either half of the pair can trigger the jump-to-bottom/reset-stickiness behavior, as long as the
+  *other* half already holds: an `expanded` transition to `true` while `mode` is already `'live'`,
+  **or** a `mode` transition to `'live'` while the panel is already `expanded`, both jump to the
+  bottom and reset stickiness. Only a change that leaves the panel in some other combination
+  (collapsed, or `mode !== 'live'`) skips it.
+- The sticky-bottom flag starts `true` internally, so a panel that mounts already `expanded` and
+  `mode="live"` follows its very first content mutation even before any `scroll` event has fired.
+
+---

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

@@ -0,0 +1,97 @@
+<!-- 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. `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"`).
+
+**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`, `row` (all exported across the internal `lr-virtual-list` shadow
+boundary), 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).
+
+```html
+<lr-thread-list
+  searchable
+  .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,53 @@
+<!-- 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-padding-block`, `--lr-input-padding-inline` and
+`--lr-input-font-size` (the last three swap per `size`).
+
+**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,91 @@
+<!-- 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:** shared tokens only — `--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-*`. No component-local tokens.
+
+**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.