@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-progress-ring.md

@@ -0,0 +1,26 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-progress-ring`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/progress/progress-ring.js';` (registers the tag; side-effect import)
+- **Class** `LyraProgressRing`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/progress/progress-ring.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-progress-ring`
+
+A circular progress indicator with the same value contract as `lr-progress-bar`.
+
+**Properties:** `value: number = 0`, `max: number = 100`, `indeterminate: boolean = false`
+(reflected), and `accessibleLabel: string = ''` (attribute `accessible-label`; unset falls back to
+the localized "Progress"). Non-finite/out-of-range `value`/`max` are normalized (`max <= 0` falls
+back to `100`, `value` clamps to `[0, max]`) rather than producing NaN geometry.
+**Slots:** default — replaces the built-in center label, which otherwise renders the rounded
+percentage (and nothing at all while `indeterminate`).
+**CSS parts:** `base`, `track`, `indicator`, `label`.
+**Themeable custom properties:** `--lr-progress-ring-size` (default `--lr-size-2-5rem` — the
+ring's inline and block size) and `--lr-progress-duration` (default `1.2s` — the indeterminate spin
+period, shared with `lr-progress-bar`'s sweep).

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

@@ -0,0 +1,58 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-provenance-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/provenance-panel/provenance-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraProvenancePanel`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/provenance-panel/provenance-panel.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-provenance-panel`
+
+The grounding breakdown for one answer: a sectioned disclosure panel (Entities / Relationships /
+Communities / Text chunks) composing this family's own pieces. The chat ↔ graph ↔ document glue
+component. Pure projection + event conduit: no fetching, no graph/viewer imports, no persistence.
+
+**Properties:**
+- `provenance: LyraProvenance | null = null` (attribute: false) — `LyraProvenance { entities?:
+  LyraEntity[]; relationships?: { path: LyraPathElement[] }[]; communities?: LyraCommunity[]; chunks?:
+  LyraChunk[] }`; each present array renders through the matching sibling component (`lr-entity-
+  chip` row, one `lr-path-strip` per relationship, `lr-community-card`, `lr-chunk-inspector`);
+  `null` or every section empty renders the overall empty state
+- `types: NodeTypeStyle[] = []` (attribute: false) — forwarded to the Entities section's chips
+- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
+  forwarded to the Text chunks section's `lr-chunk-inspector`
+- `label: string = ''`
+
+**Events:** `lr-toggle` (`detail: { section, expanded }`, a section header was toggled —
+`section` is `'entities' | 'relationships' | 'communities' | 'chunks'`).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `section`, `header` (a section's disclosure `<button>`), `count` (a section's
+item-count badge), `body` (`hidden` while collapsed), `empty` (shown when every section is empty).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-provenance-panel></lr-provenance-panel>
+<script>
+  document.querySelector('lr-provenance-panel').provenance = {
+    entities: [{ id: 'e1', label: 'Ada Lovelace', type: 'person' }],
+    chunks: [{ id: 'c1', text: 'Revenue grew 12%…', score: 0.91, sourceId: 'doc-1' }],
+  };
+</script>
+```
+
+**Known gotchas:**
+- Composes `lr-entity-chip`, `lr-path-strip`, `lr-community-card`, and `lr-chunk-inspector`
+  directly rather than reimplementing their rendering — events from those inner components (e.g.
+  `lr-entity-activate`, `lr-chunk-open`) still bubble/compose up through this panel's light DOM
+  for the host to handle in one place.
+
+---

package/llms/components/lr-push-to-talk.md

@@ -0,0 +1,57 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-push-to-talk`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/push-to-talk/push-to-talk.js';` (registers the tag; side-effect import)
+- **Class** `LyraPushToTalk`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/push-to-talk/push-to-talk.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-push-to-talk`
+
+A mic capture button owning the full `getUserMedia` + `MediaRecorder` lifecycle: permission request,
+recording, optional chunked streaming, teardown. The one place in this library that touches the
+microphone — no SDK, no LiveKit/ElevenLabs import, native browser APIs only. `mode="hold"` (the
+default) is a press-and-hold gesture; `mode="toggle"` is click-to-start/click-to-stop with
+`aria-pressed`. Escape cancels the in-progress take in either mode.
+
+**Properties:** `mode: 'hold' | 'toggle' = 'hold'` (reflected), `timesliceMs: number = 0` (attribute
+`timeslice-ms`) — `> 0` passes a timeslice to `MediaRecorder.start()` and emits `lr-record-chunk` per
+slice, `mimeType: string = ''` (attribute `mime-type`) — a `MediaRecorder` MIME type, `deviceId:
+string = ''` (attribute `device-id`) — a specific input device, `audioConstraints?:
+MediaTrackConstraints` (attribute: false) — merged into the `getUserMedia` audio constraints,
+`levelEvents: boolean = false` (attribute `level-events`) — opt in to `lr-level`, `maxDurationMs:
+number = 0` (attribute `max-duration-ms`) — auto-stop cap, `0` disables it, `showTimer: boolean =
+true` (attribute `show-timer`), `disabled: boolean = false` (reflected), plus two readonly
+properties: `state: 'idle' | 'requesting' | 'denied' | 'recording' | 'error' = 'idle'` (reflected to
+`data-state`) and `stream: MediaStream | null` (the live capture stream, assignable straight onto
+`lr-audio-visualizer.stream`).
+
+**Methods:** `start()`, `stop()`, and `cancel()` drive the capture lifecycle imperatively (mirroring
+the pointer/keyboard gestures).
+
+**Slots:** `icon` (replaces the default mic glyph) and `recording-icon` (replaces the default
+recording-state pulse glyph).
+
+**Events:** `lr-record-start` (`detail: { stream: MediaStream }`), `lr-record-chunk` (`detail: { blob:
+Blob }`, only when `timeslice-ms > 0`), `lr-record-stop` (`detail: { blob: Blob; durationMs: number
+}`), `lr-record-cancel` (no detail), `lr-record-error` (`detail: { error: unknown }`), `lr-level`
+(`detail: { level: number }` — 0–1 amplitude, opt-in via `level-events`), and `lr-state-change`
+(`detail: { state: 'idle' | 'requesting' | 'denied' | 'recording' | 'error' }`).
+
+**CSS parts:** `trigger` (the capture button), `icon`, `pulse` (rendered only while recording),
+`timer` (the `M:SS` elapsed-time readout, only while recording and `show-timer`), and `status`
+(visible status text for the `requesting`/`denied`/`error`/unsupported states).
+
+**Themeable custom properties:** `--lr-push-to-talk-size` (default `var(--lr-size-3rem)`) — the
+trigger button's inline and block size. `--lr-push-to-talk-recording-color` (default
+`var(--lr-color-danger)`) — the border and text color of `[part='trigger']` while `state` is
+`recording`; it recolors only the recording treatment and leaves every other danger-toned surface on
+the page untouched. Like the library's other state hooks it is an inline `var()` fallback at the
+point of use rather than a `:host` declaration, so it can be set on the element or on any ancestor —
+`::part(trigger)[data-state='recording']` is invalid CSS (Shadow Parts forbids an attribute selector
+after `::part()`), so re-pointing the shared `--lr-color-danger` token was previously the only way,
+and it repainted every other danger surface with it.

package/llms/components/lr-qr-code.md

@@ -0,0 +1,20 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-qr-code`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/qr-code/qr-code.js';` (registers the tag; side-effect import)
+- **Class** `LyraQrCode`, also available unregistered from `@aceshooting/lyra-ui/components/media/qr-code/qr-code.class.js`
+- **Family** `components/media/` — see `llms/index.md` for its siblings
+- **Optional peers** `qrcode` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-qr-code`
+
+Renders `value` as a QR code using the optional `qrcode` peer dependency. **Properties:** `value`, `label`,
+`size`, `radius`, and `errorCorrection` (`error-correction`, `L`/`M`/`Q`/`H`). The canvas owns `role="img"`;
+its accessible name uses `label`, host `aria-label`, then `value`. Empty values render an empty state.
+**CSS parts:** `base`, `canvas`, `empty`, `loading`, and `error`. **CSS custom properties:**
+`--lr-qr-code-fill` and `--lr-qr-code-background`. Call `refreshTheme()` after external theme changes
+when the computed QR colors need to be redrawn immediately.

package/llms/components/lr-query-builder.md

@@ -0,0 +1,21 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-query-builder`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/query-builder/query-builder.js';` (registers the tag; side-effect import)
+- **Class** `LyraQueryBuilder`, also available unregistered from `@aceshooting/lyra-ui/components/data/query-builder/query-builder.class.js`
+- **Family** `components/data/` — 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-query-builder`
+
+Composable structured-query builder for tabular or dashboard data: condition rows combined with an
+AND/OR combinator.
+
+**Properties:** `fields`, `value`, `disabled`, `addCondition`, `removeCondition`. **Events:**
+`lr-input`, `lr-add-condition`, `lr-remove-condition`. **CSS parts:** `base`, `conditions`,
+`condition`, `field-select`, `operator-select`, `value`, `combinator`, `add-button`,
+`remove-button`, `empty`.

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

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

package/llms/components/lr-radio-group.md

@@ -0,0 +1,25 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-radio-group`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/radio/radio-group.js';` (registers the tag; side-effect import)
+- **Class** `LyraRadioGroup`, also available unregistered from `@aceshooting/lyra-ui/components/forms/radio/radio-group.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-radio-group`
+
+A labeled, keyboard-navigable group of `lr-radio` controls. Arrow keys, Home, and End move
+focus; arrow navigation selects the next enabled radio.
+
+**Properties:** `label`, `hint`, `errorText` (`error-text`), `name`, `required`, `disabled`, and
+`aria-label` (through `accessibleLabel`).
+
+**Events:** `lr-change` with `{ value, radio }`.
+
+**Slots:** default radios, `label`, `hint`, `error`.
+
+**CSS parts:** `base`, `label`, `hint`, `error`.

package/llms/components/lr-radio.md

@@ -0,0 +1,39 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-radio`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/radio/radio.js';` (registers the tag; side-effect import)
+- **Class** `LyraRadio`, also available unregistered from `@aceshooting/lyra-ui/components/forms/radio/radio.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-radio`
+
+A form-associated single-choice control. Use it alone or inside `lr-radio-group`.
+
+**Properties:** `checked`, `disabled`, `required`, `name`, and `value` (all reflected where
+applicable). A selected radio submits its value through `ElementInternals`.
+`effectiveRequired` exposes the required state inherited from a containing radio group. `focus()`,
+`blur()`, and `click()` forward to the internal radio control.
+
+**Events:** native-style composed `input` and `change`, plus `lr-change` with
+`{ checked, value }`.
+
+**Slots:** default label content.
+
+**CSS parts:** `base`, `circle`, `dot`, `label`.
+
+**Themeable custom properties:** `--lr-radio-label-indent` — the inline distance from the control's
+start edge to the start of the label text, i.e. the circle's own floor plus the gap beside it,
+defaulting to `calc(min(var(--lr-icon-button-size), 1.75rem) + var(--lr-space-s))`. The rendered
+gap is derived from it, so the advertised value and the real offset cannot drift; setting it on the
+element (or on `lr-radio` in your own stylesheet) moves the label. Exactly the same knob, defaults,
+purpose, and sideways-inheritance caveat as `--lr-checkbox-label-indent` — see `lr-checkbox` above
+for the formula to align a sibling hint element.
+
+```html
+<lr-radio name="format" value="json">JSON</lr-radio>
+```

package/llms/components/lr-random-content.md

@@ -0,0 +1,62 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-random-content`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/random-content/random-content.js';` (registers the tag; side-effect import)
+- **Class** `LyraRandomContent`, also available unregistered from `@aceshooting/lyra-ui/components/utility/random-content/random-content.class.js`
+- **Family** `components/utility/` — 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-random-content`
+
+Shows a chosen subset of its slotted children and hides the rest — A/B copy testing, testimonial
+rotation, varying marketing copy per render or interval — with no custom JS beyond slotting the
+candidates. Selection is applied by setting `hidden` + `aria-hidden` directly on the light-DOM
+children; nothing is moved or cloned.
+
+**Properties:**
+- `items: number = 1` — how many children are shown **simultaneously**; a count, not the pool.
+  Normalized to a finite integer clamped to `[1, poolSize]`
+- `mode: 'unique' | 'random' | 'sequence' = 'unique'` — `'random'` re-rolls freely (repeats
+  possible); `'unique'` retries up to 10 times to avoid re-picking the previous selection (only
+  when the pool is larger than `items`); `'sequence'` walks the pool in order with a wrapping cursor
+- `animation: 'none' | 'fade' | 'fade-up' | 'fade-down' | 'fade-left' | 'fade-right' = 'none'`
+  (reflected) — entrance effect applied to a child the instant it becomes shown
+- `autoplay: boolean = false` (reflected)
+- `autoplayInterval: number = 3000` (attribute `autoplay-interval`) — clamped to a 1000 ms floor
+
+**Methods:** `randomize(): HTMLElement[]` — re-selects using the current `mode`, applies
+`hidden`/`aria-hidden`, emits `lr-content-change`, and returns the elements now shown. Does **not**
+reset or restart the autoplay timer.
+
+**Events:** `lr-content-change` (`detail: { items: HTMLElement[] }` — the exact elements now shown,
+in display order). Fires on first render, on `randomize()`, on a real slot-content change, and on
+each autoplay tick; never when the eligible pool is empty.
+
+**Slots:** default — the candidate pool. Only direct **element** children are eligible.
+
+**CSS parts:** `base` — the wrapper around the default slot; carries `role="status"`,
+`aria-atomic="true"`, and `aria-live="polite"`, downgraded to `aria-live="off"` while `autoplay` is
+on (a self-rotating region announcing on every tick would be spam). A host `aria-label` attribute is
+forwarded onto it.
+
+**Themeable custom properties:** `--lr-random-content-animation-duration` (default `300ms`),
+`--lr-random-content-animation-easing` (default `ease`),
+`--lr-random-content-animation-translate` (default `--lr-size-0-5em` — travel distance for the four
+directional `fade-*` effects).
+
+**Known gotchas:**
+- There is no built-in trigger UI (no next/previous/shuffle button) and therefore no keyboard
+  interaction: selection changes only via `autoplay` or `randomize()`.
+- Autoplay is suppressed entirely under `prefers-reduced-motion: reduce`, and whenever the eligible
+  pool has fewer than 2 children. The preference is re-observed live, not just read once.
+- `fade-left`/`fade-right` are physical-direction transforms (upstream naming), deliberately **not**
+  mirrored under `:dir(rtl)` — they are not previous/next navigational semantics.
+- The entrance animation targets `::slotted(*)`, which the library-wide reduced-motion rule cannot
+  reach (it only covers the shadow tree), so this component guards it with its own media query.
+- The host is `display: block`. For an inline text-fragment swap inside a sentence, override
+  `lr-random-content { display: inline; }` from outside; `display: contents` is deliberately not
+  used (a11y-tree inconsistencies across engines).

package/llms/components/lr-rating.md

@@ -0,0 +1,21 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-rating`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/rating/rating.js';` (registers the tag; side-effect import)
+- **Class** `LyraRating`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/rating/rating.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-rating`
+
+A keyboard-accessible star rating control with slider semantics. **Properties:** `value`, `max`,
+`precision`, `readonly`, `disabled`, and `accessibleLabel` (`aria-label`). **Events:**
+`lr-change` with `{ value }`. **CSS parts:** `base`, `star`, `star-fill` (the filled overlay
+inside each star, clipped to the fractional `precision` value). **Themeable custom properties:**
+`--lr-rating-fill` (default `--lr-color-warning` — filled-star color), `--lr-rating-empty-color`
+(default `--lr-color-border` — unfilled-star color), and `--lr-rating-size` (default
+`--lr-font-size-xl` — star size).

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

@@ -0,0 +1,31 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-relative-time`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/format/relative-time.js';` (registers the tag; side-effect import)
+- **Class** `LyraRelativeTime`, also available unregistered from `@aceshooting/lyra-ui/components/utility/format/relative-time.class.js`
+- **Family** `components/utility/` — 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-relative-time`
+
+`Intl.RelativeTimeFormat` output ("3 hours ago", "in 2 days"), relative to `Date.now()` at render.
+Text-only host — no CSS parts, events, or own tokens; locale resolution and `Intl`-instance caching
+are as described under `lr-format-number` above.
+
+**Properties:**
+- `date: string | number | Date = ''` — the target instant; past values format as "ago"
+- `unit: 'second'|'minute'|'hour'|'day'|'week'|'month'|'quarter'|'year'|'auto' = 'auto'` — `'auto'`
+  picks the largest unit whose own length fits inside the elapsed time, then rounds; naming a unit
+  forces it (so a 90-minute delta with `unit="day"` rounds to "today"/0 days)
+- `numeric: 'always' | 'auto' = 'auto'` — `Intl`'s own option: `'auto'` allows "yesterday"/"tomorrow"
+  in place of "1 day ago"/"in 1 day"; `'always'` keeps the numeric phrasing
+- `sync: boolean = false` — re-renders on a fixed 30-second interval so the text stays current. The
+  interval is cleared on disconnect and restarted whenever `date`/`unit`/`numeric`/`locale` changes.
+  Not adaptive: a "3 seconds ago" readout still only updates every 30 s
+
+**Slots:** none — an unparseable `date` renders the empty string, with no fallback-content hook
+(unlike the three `lr-format-*` components above).

package/llms/components/lr-resize-observer.md

@@ -0,0 +1,25 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-resize-observer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/resize-observer/resize-observer.js';` (registers the tag; side-effect import)
+- **Class** `LyraResizeObserver`, also available unregistered from `@aceshooting/lyra-ui/components/utility/resize-observer/resize-observer.class.js`
+- **Family** `components/utility/` — 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-resize-observer`
+
+Lifecycle-managed wrapper around the native `ResizeObserver`. It observes all element children in
+the default slot and emits a composed event, while adding no layout of its own.
+
+**Properties:** `disabled: boolean = false` (reflected) and `box: 'content-box' | 'border-box' |
+'device-pixel-content-box' = 'content-box'` (reflected).
+
+**Events:** `lr-resize` with `{ entries: ResizeObserverEntry[] }` in `detail`.
+
+**Slots:** default observed elements. **CSS parts:** `base`.
+
+---

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

@@ -0,0 +1,116 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-responsive-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/responsive-panel/responsive-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraResponsivePanel`, also available unregistered from `@aceshooting/lyra-ui/components/layout/responsive-panel/responsive-panel.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-responsive-panel`
+
+The same slotted content either docked inline in the page's normal layout flow (desktop) or
+presented as a full-screen/bottom-sheet overlay (mobile), depending on viewport width. First-party
+invention (no Web Awesome equivalent). Typical uses: a settings panel or a conversation-history
+sidebar that's a permanent docked pane on a wide screen but a modal on a phone.
+
+**Properties:**
+- `open: boolean = false` (reflected) — in the inline presentation this just means visible/mounted;
+  in the overlay presentation this is the actual modal open/closed state.
+- `mode: ResponsivePanelMode = 'auto'` (reflected) — `'auto'` tracks `mobile-breakpoint` live;
+  `'inline'`/`'overlay'` force that presentation regardless of viewport width.
+- `variant: ResponsivePanelVariant = 'fullscreen'` (reflected) — only affects the overlay
+  presentation's visual treatment: `'fullscreen'` covers the whole viewport; `'bottom-sheet'` slides
+  up from the bottom and doesn't cover the full height. Has no visual effect while the effective
+  presentation resolves to `'inline'`.
+- `label: string = ''` — accessible name for the overlay presentation's `role="dialog"`, used
+  verbatim when set. When empty, falls back to the `header` slot's content: a heading element
+  (`h1`–`h6` or `[role="heading"]`) among the slotted header content wins if present, otherwise the
+  header slot's combined text content is used (mirrors `lr-dialog`'s `detectHeading()` fallback,
+  via `aria-label` rather than `aria-labelledby` since the header content is light DOM while
+  `[part="panel"]` is in shadow DOM). A panel opened with neither `label` nor header content still
+  renders `role="dialog"` with no accessible name. Unused in the inline presentation, which has no
+  dialog semantics to name.
+- `mobileBreakpoint: string = '768px'` (attribute `mobile-breakpoint`) — CSS length passed to
+  `matchMedia` as `(max-width: <this>)` to decide, in `mode="auto"`, whether the effective
+  presentation is `'overlay'` (below/at this width) or `'inline'` (above it).
+
+**Methods:** `close(reason: ResponsivePanelCloseReason = 'api'): void` — closes the panel (sets
+`open = false`), emits `lr-close` with `reason`, and — only in the overlay presentation — returns
+focus to whichever element triggered the open. No-op if already closed. Built-in overlay triggers
+call this with `'escape'`/`'backdrop'`; a consumer's own close affordance (a footer button, a docked
+panel's own toggle) should call it directly with its own reason string.
+
+**Events:** `lr-close` (`detail: ResponsivePanelCloseReason` = `'escape'|'backdrop'|'api'|string`;
+fired by the overlay presentation's built-in dismiss triggers — Escape, backdrop click — and by any
+`close()` call, in either presentation; a plain `open = false` property write does **not** fire it,
+only going through `close()` counts as a dismissal), `lr-mode-change`
+(`detail: ResponsivePanelModeChangeDetail` = `{ mode: ResponsivePanelEffectiveMode }`; fired whenever
+the *effective* mode — not the `mode` prop's possibly-`'auto'` literal value — changes between
+`'inline'` and `'overlay'`; never fired on the initial render, only for a live change thereafter).
+
+**Slots:** default (the panel body), `header` (optional header content, rendered above the body),
+`footer` (optional footer content, e.g. action buttons, rendered below the body).
+
+**CSS parts:** `base`, `backdrop`, `panel`, `header`, `body`, `footer` (`backdrop` is only rendered
+in the overlay presentation).
+
+**Themeable custom properties:** `--lr-responsive-panel-overlay-color` (default
+`var(--lr-color-overlay)` — the overlay presentation's backdrop scrim color),
+`--lr-responsive-panel-sheet-max-block-size` (default `85dvh`, falling back to `85vh` where `dvh`
+isn't supported — the maximum height of a `variant="bottom-sheet"` overlay panel, so a long sheet
+stops short of the top of the viewport instead of covering it; it has no effect on
+`variant="fullscreen"` or on the inline presentation), plus shared tokens (`--lr-color-border`, `--lr-color-surface`,
+`--lr-space-*`, `--lr-radius`, `--lr-shadow`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-responsive-panel id="settings-panel" label="Settings" variant="bottom-sheet" mobile-breakpoint="768px">
+  <span slot="header"><h2>Settings</h2></span>
+  <div>Panel body content — a form, a list, anything.</div>
+  <span slot="footer"><button onclick="document.getElementById('settings-panel').close()">Done</button></span>
+</lr-responsive-panel>
+```
+
+Breakpoint detection uses `matchMedia('(max-width: ' + mobileBreakpoint + ')')`, re-evaluated live
+while connected — resizing/rotating a device that crosses the breakpoint while `mode="auto"` (the
+default) updates the effective presentation without unmounting or re-creating the slotted content.
+Inline and overlay presentations share the same shadow DOM, so slotted content and scroll position
+survive the transition. Focus already inside the panel is preserved. If focus is outside when an
+open inline panel becomes an overlay, focus moves to the first composed focus target (falling back
+to the panel), so it cannot remain behind `aria-modal="true"`. Closing restores the element captured
+when the panel originally opened, even when that original open happened inline. The overlay
+presentation participates in the shared modal stack rather than nesting a `<lr-dialog>`.
+
+The package root also exports the pure `resolveEffectiveMode(mode: ResponsivePanelMode,
+belowBreakpoint: boolean): ResponsivePanelEffectiveMode` resolver — renamed on export to
+`resolveResponsivePanelEffectiveMode` to avoid a name collision — alongside the
+`ResponsivePanelMode`/`ResponsivePanelEffectiveMode`/`ResponsivePanelVariant`/
+`ResponsivePanelCloseReason`/`ResponsivePanelModeChangeDetail` types. It's the same logic the
+element's internal `matchMedia` listener calls: `'inline'`/`'overlay'` pass straight through
+unchanged; `'auto'` resolves to `'overlay'` when `belowBreakpoint` is true, `'inline'` otherwise —
+exposed standalone so a consumer can compute or unit-test the same resolution without a real browser
+window.
+
+**Known gotchas:**
+- assigning `open` directly still does not emit `lr-close`; use `close()` when the dismissal
+  event/reason is required. While overlay chrome is active, however, the `true` → `false` state
+  transition restores opener focus regardless of whether it came from `close()`, a property write,
+  or attribute removal.
+- crossing inline → overlay while already open preserves focus that is already inside and moves
+  outside focus into the panel; do not expect focus to remain on page content behind the modal.
+- `variant="bottom-sheet"` has no visible effect at all while the effective presentation is
+  `'inline'` — it only changes the overlay presentation's anchoring/height.
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
+  shared overlay registration and re-acquires the scroll lock if overlay chrome was still active
+  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
+  between, so `willUpdate()` alone wouldn't otherwise notice.
+- the exported pure function is named `resolveEffectiveMode` in the component module but re-exported
+  from the package root as `resolveResponsivePanelEffectiveMode` — importing the un-prefixed name
+  from `@aceshooting/lyra-ui` will fail.
+
+---