@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-poll-status.md

@@ -0,0 +1,71 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-poll-status`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/poll-status/poll-status.js';` (registers the tag; side-effect import)
+- **Class** `LyraPollStatus`, also available unregistered from `@aceshooting/lyra-ui/components/utility/poll-status/poll-status.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-poll-status`
+
+A "next scheduled refresh" countdown with a built-in pause control: a ticking `M:SS` display counting
+down to the next scheduled action, a "Refreshing…" state at zero, and a pause/resume toggle.
+First-party invention (no Web Awesome equivalent); the closest existing component,
+`<lr-stream-status>`, is scoped to transport/connection-health phases, a different concern from a
+scheduled-interval countdown — this mirrors its internal `<lr-live-region>` composition for
+accessible phase-transition announcements.
+
+**Properties:**
+- `nextInMs?: number` (attribute `next-in-ms`) — milliseconds until the next scheduled action, as of
+  whenever this was last set; setting it (re)starts the countdown from "now." Unset (the default)
+  shows no countdown.
+- `active: boolean = true` (reflected) — whether the poll cycle is running at all.
+- `paused: boolean = false` (reflected) — user-toggled pause; while `true`, the countdown display
+  freezes and `lr-poll-due` never fires.
+
+**Events:** `lr-poll-due` (no detail — fired once when the countdown reaches zero, not fired while
+`paused`), `lr-pause-change` (`detail: boolean` — fired when `paused` changes via the built-in
+button).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `indicator` (the pulsing status dot), `countdown` (the `M:SS`, or
+"Refreshing…", text), `pause-button` (the built-in pause/resume toggle).
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-font-size-sm`,
+`--lr-color-text-quiet`, `--lr-color-brand`, `--lr-color-success`, `--lr-radius`/`-pill`,
+`--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-poll-status next-in-ms="30000"></lr-poll-status>
+<script type="module">
+  const status = document.querySelector('lr-poll-status');
+  status.addEventListener('lr-poll-due', () => refreshData());
+  status.addEventListener('lr-pause-change', (e) => console.log('paused:', e.detail));
+</script>
+```
+
+Internally, a 1-second ticker re-derives the remaining time from a captured target timestamp (rather
+than a naive per-tick decrement), so the countdown stays accurate even if the tab was backgrounded
+and timers were throttled. Reassigning `nextInMs` at any time restarts the countdown from that new
+value; pausing/resuming, or toggling `active`, starts or stops the ticker without discarding the
+current remaining time. Phase transitions ("Paused.", "Resumed.", "Refreshing now.") are announced
+via an internal `<lr-live-region>` in polite mode.
+
+**Known gotchas:**
+- there's no built-in "reset" or "extend" method beyond reassigning `nextInMs` — a host that wants to
+  push the deadline back out on user activity re-sets `nextInMs` itself.
+- `active="false"` and `paused` both stop the ticker independently, but only `paused` fires
+  `lr-pause-change` — that event is scoped to the built-in pause button's own toggle, not to
+  `active`.
+- the countdown rounds up to the nearest whole second, so it never shows a literal "0:00" — the
+  display jumps straight from a small count (e.g. "0:01") to "Refreshing…" once the deadline is
+  actually reached.
+
+---

package/llms/components/lr-popover.md

@@ -0,0 +1,31 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-popover`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/overlay/popover.js';` (registers the tag; side-effect import)
+- **Class** `LyraPopover`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/overlay/popover.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-popover`
+
+A click-triggered, light-dismiss floating surface positioned with the shared Floating UI positioner.
+
+**Properties:** `open`, `placement`, `distance`, `accessibleLabel` (`aria-label`), and `popupRole` (`popup-role`).
+**Methods:** `showAt(rect: { x, y, width?, height?, contextElement? }, options?: { returnFocusTo?:
+HTMLElement })` opens the popover anchored to an arbitrary rectangle instead of the slotted
+`trigger` — for a graph node, a canvas pixel, a chart datum, or any other non-DOM location
+(`width`/`height` default to `0`, a point). Escape and light-dismiss return focus to
+`options.returnFocusTo` when supplied, or skip focus-return entirely otherwise, since a virtual
+anchor has no `.focus()`. The virtual anchor has no DOM node of its own for `autoUpdate()` to
+track ancestor scroll/resize against — pass `rect.contextElement` (a real, still-connected element
+near the virtual point) when one is available to give it something to observe; otherwise, or when
+the anchor point moves on its own (e.g. a graph pan/zoom tick), re-call `showAt()` with fresh
+coordinates to re-anchor — the popover stays open across such a call. A popover that never calls
+`showAt()` behaves exactly as before.
+**Events:** `lr-show`, `lr-hide`. **Slots:** `trigger`, default content. **CSS parts:** `trigger`,
+`popup`, `content`. **Themeable custom properties:** `--lr-overlay-max-inline-size` (default
+`--lr-size-20rem` — maximum inline size of the popup).

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

@@ -0,0 +1,35 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-pptx-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraPptxViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/pptx-viewer/pptx-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `@aiden0z/pptx-renderer` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-pptx-viewer`
+
+Best-effort client-side PPTX viewer backed by the optional `@aiden0z/pptx-renderer` peer. A
+localized fidelity notice is always visible because animations, equations, embedded objects,
+speaker notes, and several advanced effects are not rendered.
+
+**Properties:** `src`, `name`, and `label` are strings. A host `aria-label` also names the viewer
+region when `label` is unset.
+
+**Methods:** `goToSlide(index)` returns a promise and navigates the mounted presentation.
+
+**Events:** `lr-load` (`detail: { slideCount }`), `lr-slide-change` (`detail: { index, count }`),
+and `lr-render-error` with `detail.error`.
+
+**CSS parts:** `base`, `header`, `name`, `notice`, `error`, `nav`, `previous-button`,
+`previous-icon`, `slide-count`, `next-button`, `next-icon`, and `container`.
+
+**Optional peer dependency:** install `@aiden0z/pptx-renderer` with
+`pnpm add @aiden0z/pptx-renderer`. The registry matches the official PPTX MIME type and `.pptx`
+filenames.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the presentation.

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

@@ -0,0 +1,22 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-progress-bar`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/progress/progress-bar.js';` (registers the tag; side-effect import)
+- **Class** `LyraProgressBar`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/progress/progress-bar.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-bar`
+
+A determinate or indeterminate progress bar.
+
+**Properties:** `value`, `max`, `indeterminate`, `variant`, `showValue` (`show-value`), and
+`accessibleLabel` (`accessible-label`).
+The rendered progressbar exposes `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` when
+determinate.
+
+**Slots:** `label`. **CSS parts:** `base`, `track`, `indicator`, `label`.

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,50 @@
+<!-- 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.

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,70 @@
+<!-- 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`.
+
+**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,31 @@
+<!-- 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()`
+and `blur()` 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`.
+
+```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`.
+
+---