@aceshooting/lyra-ui 5.0.0 → 5.2.0

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

@@ -0,0 +1,196 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-phone-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/phone-input/phone-input.js';` (registers the tag; side-effect import)
+- **Class** `LyraPhoneInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** `@aceshooting/lyra-flags`, `libphonenumber-js` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-phone-input`
+
+A form-associated, country-aware telephone field. The submitted `value` is either canonical E.164
+(for example `+352621123456`) or `''` while the editable input is empty, incomplete, or invalid.
+Numbering-plan metadata and national formatting stay outside Lyra's base bundle: supply a
+synchronous `PhoneNumberAdapter`, or lazily create one from a `libphonenumber-js`-compatible module
+with `loadLibphonenumberAdapter()`. Without an adapter, already-international E.164 input still
+normalizes and validates; national input remains editable with `incomplete` validity.
+
+The country selector keeps the real native `<select>` (localized full country names in its popup,
+native mobile pickers, keyboard type-ahead) but stretches it invisibly over a compact decorative
+trigger showing the selected alpha-2 code plus a design-system chevron — long country names never
+clip the closed control and the adjacent calling code isn't repeated. With `flags`, the trigger
+also shows the selected country's `<lr-flag>`.
+
+**Types:**
+
+```ts
+type PhoneNumberStatus = 'empty' | 'incomplete' | 'invalid' | 'valid';
+
+interface PhoneCountry {
+  code: string;         // ISO 3166-1 alpha-2
+  callingCode: string;  // no leading "+"
+  label?: string;       // overrides Intl.DisplayNames
+}
+
+interface PhoneNumberParseResult {
+  status: PhoneNumberStatus;
+  e164?: string;       // required for status: 'valid'
+  formatted?: string;  // best-effort editable display text
+  country?: string;    // detected ISO alpha-2 code
+}
+
+interface PhoneNumberAdapter {
+  readonly countries?: readonly PhoneCountry[];
+  parse(input: string, country?: string): PhoneNumberParseResult;
+}
+```
+
+**Properties:**
+
+- `value: string = ''` — canonical E.164 form/submission value. A programmatic assignment is parsed
+  and normalized synchronously but emits no user event.
+- `name: string = ''`, `disabled: boolean = false`, `required: boolean = false` — native-like
+  form-control properties supplied by `FormAssociated`; inherited disabled fieldsets are included
+  through `effectiveDisabled`.
+- `adapter?: PhoneNumberAdapter` (attribute: false) — synchronous numbering-plan parser/formatter.
+  No metadata implementation is imported by the component itself.
+- `countries: readonly PhoneCountry[] = []` (attribute: false) — explicit selector rows; takes
+  precedence over `adapter.countries`.
+- `defaultCountry: string = ''` (attribute `default-country`) — selected when `country` has not been
+  set explicitly.
+- `flags: boolean = false` (reflected) — show the selected country's flag in the country trigger as
+  `<lr-flag variant="compact" aria-label="">` (decorative; the native select already announces the
+  country name). The `<lr-flag>` element definition is registered lazily the first time any
+  `lr-phone-input` enables this, so nothing flag-related is bundled while it stays off. Flag
+  *artwork* still follows the standalone `<lr-flag>` contract: install the optional
+  `@aceshooting/lyra-flags` peer and import
+  `@aceshooting/lyra-ui/components/media/flag/flag-peer.js` once; without that registration the
+  trigger simply omits the image. The open popup list stays text-only — a native `<option>` cannot
+  contain elements.
+- `country: string` — current uppercase ISO alpha-2 selection; falls back to `defaultCountry`, then
+  the first explicit/adapter country. Changing the country reparses the editable number.
+- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`) —
+  visible form-field chrome; each has a matching named slot.
+- `placeholder: string = ''` — forwarded to the native telephone input.
+- `spellcheck: boolean = true`, `autocapitalize: string = ''`, `autoCorrect: string = ''`
+  (attribute `autocorrect`) — forwarded to the internal telephone input's own `spellcheck`/
+  `autocapitalize`/`autocorrect`; `spellcheck="false"` is parsed as `false` via a string-aware
+  converter (Lit's default presence-based boolean converter would otherwise treat any attribute
+  value, including the literal string `"false"`, as `true`).
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — forwarded to the internal
+  telephone input. Name precedence is host `aria-label`, `phoneLabel`, visible `label`, then
+  `placeholder`.
+- `phoneLabel: string = ''` (attribute `phone-label`) — explicit accessible-name override for the
+  native telephone input.
+- `countryLabel: string = 'Select'` (attribute `country-label`) — country-selector accessible name;
+  the untouched default routes through the shared localized `select` message.
+- `incompleteText: string = 'The value is invalid.'` (attribute `incomplete-text`) — validation
+  message for dial-like input that can still become valid with more digits. The untouched default
+  routes through the shared localized `valueInvalid` message.
+- `invalidText: string = 'The value is invalid.'` (attribute `invalid-text`) — completed-invalid
+  message, localized through the same shared key while left at its default.
+- `autocomplete: string = 'tel'`, `inputmode: 'tel'|'numeric'|'text' = 'tel'`,
+  `enterkeyhint: string = ''` — forwarded to the internal `<input type="tel">`.
+- readonly `input: HTMLInputElement | undefined` — the internal native telephone input.
+- readonly `inputValue: string` — editable formatted/partial text, which remains available even when
+  canonical `value` is `''`.
+- `selectionStart`, `selectionEnd`, and `selectionDirection` — native selection getters/setters
+  forwarded to the telephone input
+- readonly `phoneStatus: PhoneNumberStatus` — current parse state. The host also reflects it through
+  `data-phone-status`.
+- readonly `form`, `labels`, `validity`, `validationMessage`, `willValidate`, and
+  `effectiveDisabled` — the shared form-associated native-like getters.
+
+**Validity:** empty + `required` sets `valueMissing`; incomplete dial-like input sets `badInput`;
+completed-invalid input sets `typeMismatch`; valid E.164 input clears all three. Partial or invalid
+text remains in `inputValue`/the native input so validation never makes a number impossible to edit,
+but its canonical submitted `value` is blank. Native validation feedback is anchored to the
+telephone input, not the adjacent country selector.
+
+**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and `setRangeText()`
+forward to the native telephone input. Range-text edits reparse the number and synchronize the
+canonical value, form value, and validity.
+`setFormValue(value)`, `checkValidity()`, and `reportValidity()` come from `FormAssociated`.
+`form.reset()` restores the original declarative `value` and the default country.
+
+**Events:**
+
+- `input` — every user edit and country change.
+- `change` — native telephone-input commit timing and every country change.
+- `focus` / `blur` — bubbling, composed bridges for the internal native input's non-crossing focus
+  events.
+
+`input`/`change` detail is
+`{ value: string; inputValue: string; country: string; valid: boolean; status: PhoneNumberStatus }`.
+Programmatic property assignments and form reset/state restoration are silent.
+
+**Slots:** `label`, `hint`, `error`, `country-prefix` (optional visual before the country selector,
+such as a consumer-owned `<lr-flag>`; no flag package is imported automatically).
+
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `country-prefix`, `country`
+(the selector region: invisible native select layered over the visual trigger), `country-select`,
+`country-trigger` (visible, `aria-hidden` closed-state box), `flag` (the `<lr-flag>`, only with
+`flags`), `country-code` (selected alpha-2 code, `data-placeholder` when no country exists),
+`expand-icon`, `calling-code`, `input`, `hint`, `error`.
+
+**Themeable custom properties:** shared tokens only. The phone-number input and calling code are
+deliberately `dir="ltr"`/isolated because telephone numbers are algorithmic content; surrounding
+form chrome and the country selector inherit LTR/RTL and use logical spacing/borders.
+
+**Optional peer deps:** `libphonenumber-js` is declared optional but never imported by Lyra itself.
+For full national parsing/formatting, install it in the consuming app and pass it through the
+consumer-supplied lazy loader below. Because the import expression lives in consumer code, no
+numbering metadata enters a bundle that does not opt in.
+
+```ts
+import '@aceshooting/lyra-ui/components/forms/phone-input/phone-input.js';
+import { loadLibphonenumberAdapter } from
+  '@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js';
+
+const phone = document.querySelector('lr-phone-input');
+phone.adapter = await loadLibphonenumberAdapter(() => import('libphonenumber-js/min'));
+```
+
+```html
+<lr-phone-input
+  name="mobile"
+  label="Mobile number"
+  hint="Used only for account security"
+  default-country="LU"
+  required
+></lr-phone-input>
+```
+
+```ts
+// Country flags in the trigger (optional): same peer contract as a standalone <lr-flag>.
+import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';
+```
+
+```html
+<lr-phone-input label="Mobile number" flags default-country="LU"></lr-phone-input>
+```
+
+**Known gotchas:**
+
+- An adapter's `parse()` method is synchronous because it runs on every keystroke. Load any optional
+  module first, then assign the resolved adapter. Adapter exceptions degrade to the E.164-only
+  fallback rather than breaking editing.
+- A valid adapter result must include an E.164-shaped `e164`; a malformed "valid" result is treated
+  as invalid instead of entering form submission.
+- Country names use `Intl.DisplayNames` and fall back to the ISO code; set `PhoneCountry.label` for
+  a product-specific name. Calling codes are data, not derived by the component.
+- The component never imports `@aceshooting/lyra-flags` itself, with `flags` or without. `flags`
+  lazily registers only the `<lr-flag>` element; the artwork resolver comes from the consumer's own
+  `flag-peer.js` import (plus the installed peer package), so forgetting either shows a flagless
+  trigger rather than erroring. `country-prefix` remains available for a fully consumer-owned
+  adornment instead.
+- The visible trigger (`country-trigger` and everything inside it) is `aria-hidden` by design; the
+  layered native select is the accessible control. Don't move interactive content into those parts
+  via `::part` styling tricks, and don't expect the flag inside the open popup list — a native
+  `<option>` is text-only.
+
+---

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

@@ -0,0 +1,72 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-pie-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/pie-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraPieChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/pie-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-doughnut-chart`, `lr-radar-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-playback.md

@@ -0,0 +1,74 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-playback`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/playback/playback.js';` (registers the tag; side-effect import)
+- **Class** `LyraPlayback`, also available unregistered from `@aceshooting/lyra-ui/components/media/playback/playback.class.js`
+- **Family** `components/media/` — 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-playback`
+
+Steps an index through `[0, length)` on a fixed interval — play/pause for time-series scrubbing.
+
+**Properties:**
+- `length: number = 0`
+- `index: number = 0`
+- `intervalMs: number = 900` (attribute `interval-ms`)
+- `playing: boolean = false` (reflected)
+- `loop: boolean = true`
+- `hidden: boolean = false` (reflected; re-declared over the native IDL property so Lit's
+  change-tracking sees it and auto-pauses on `hidden = true`)
+
+**Methods:** `play()`, `pause()`, `toggle()`, `next()`, `previous()`, `goTo(index: number)` — all
+idempotent/clamped; `length <= 1` is a no-op degenerate case. `focus(options?)` and `blur()` forward
+to the play button.
+
+**Events:** `lr-play`, `lr-pause` (no detail), `lr-step` (`detail: { index }`, fired on every
+tick and manual step); internal `focus`/`blur` are bridged as bubbling, composed host events.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `play-button`, `slider`
+
+**Themeable custom properties:** `--lr-playback-icon-size` (default
+`calc(var(--lr-icon-button-size) * 0.35)` — the play/pause glyph's size; applied as the button's
+`font-size`, and the inline SVG renders at `1em`); plus shared tokens `--lr-space-s`,
+`--lr-color-border`, `--lr-color-surface`, `--lr-color-text`, `--lr-color-brand`,
+`--lr-icon-button-size` (the play button's box), `--lr-opacity-disabled` (play button/slider
+dimming at `length <= 1`), `--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-playback length="24" interval-ms="500"></lr-playback>
+<script>
+  const pb = document.querySelector('lr-playback');
+  pb.addEventListener('lr-step', (e) => renderFrame(e.detail.index));
+</script>
+```
+
+**Known gotchas:**
+- `index` is now re-clamped into `[0, length)` as soon as `length` shrinks (in `willUpdate()`, not
+  waiting for the next `tick()`/`goTo()`/`next()`/`previous()` call) — setting `el.length = 2` while
+  `el.index = 7` immediately pulls `index` back to `1`, and playback auto-pauses if `length` drops
+  to `<= 1` while playing (the play button and slider would otherwise both become disabled with no
+  way to stop it — both are `?disabled` whenever `length <= 1`, not just the button).
+- `intervalMs` is live-reactive mid-playback: ticking is a self-rescheduling `setTimeout` (not one
+  long-lived `setInterval`), so `intervalMs` is re-read fresh before every tick — changing
+  `interval-ms` while `playing` takes effect on the very next step instead of only after a
+  pause/play cycle.
+- `length` and `index` are normalized to finite non-negative integer counts, with `index` clamped
+  into `[0, length)`; fractional, negative, `NaN`, infinite, and oversized values cannot poison
+  end conditions or the slider.
+- `interval-ms` is clamped to the 16ms floor and the browser's finite timer ceiling: a non-finite or
+  lower value ticks at 16ms, while an oversized value uses the timer ceiling. Each distinct invalid
+  value is warned once (deduplicated per value, not a single once-ever flag).
+- No `aria-valuetext`/visible "N of M" position label on the range input.
+- Calling `play()`/`pause()` programmatically (not via the button) gives no `aria-live`
+  announcement of the Play/Pause state change.
+
+---

package/llms/components/lr-polar-area-chart.md

@@ -0,0 +1,72 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-polar-area-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/polar-area-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraPolarAreaChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/polar-area-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-radar-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-policy-summary.md

@@ -0,0 +1,43 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-policy-summary`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/policy-summary/policy-summary.js';` (registers the tag; side-effect import)
+- **Class** `LyraPolicySummary`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/policy-summary/policy-summary.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-policy-summary`
+
+Read-only list of guardrail, permission, privacy, and tool-policy decisions with accessible
+allow, deny, or needs-review explanations.
+
+**Properties:** `decisions: PolicyDecision[] = []` (attribute: false) — `PolicyDecision { id: string;
+category: PolicyDecisionCategory; label: string; state: PolicyDecisionState; explanation: string;
+detail?: string }`, with `PolicyDecisionCategory = 'guardrail' | 'permission' | 'privacy' | 'tool'`
+and `PolicyDecisionState = 'allow' | 'deny' | 'needs-review'` (all three exported here). `label` is
+host-supplied data rendered as-is, never localized (a rule name, or a tool name for `category:
+'tool'`). `explanation` is an **always-visible** plain-text reason — `state` is never conveyed by
+color alone; it tones the badge and callout as `allow` → success, `deny` → danger, `needs-review` →
+warning. `detail` is optional richer evidence (matched rule text, policy id) revealed through
+progressive disclosure. Controlled and never mutated — pass a new array to update it.
+
+**Events:** none. Read-only and display-only: this component never mutates a decision and offers no
+resolve/acknowledge action — see `lr-tool-approval-dialog`/`lr-confirm-bar` for a real approve/deny
+gate.
+
+**CSS parts:** `base`, `empty`, `summary`, `count`, `state-badge`,
+`list`, `decision`, `decision-header`, `category`, `label`, `detail`, `explanation`.
+
+**Themeable custom properties:** `--lr-policy-summary-count-allow-color` (default
+`var(--lr-color-success)`), `--lr-policy-summary-count-deny-color` (default
+`var(--lr-color-danger)`) and `--lr-policy-summary-count-needs-review-color` (default
+`var(--lr-color-warning)`) — the text color of each state's count in the summary strip. All three
+follow the state-scoped-property convention described under `lr-span-waterfall`: inline `var()`
+fallbacks rather than `:host` declarations, so each can be set on the element or on any ancestor.
+They exist because `::part(count)[data-state='deny']` is invalid CSS — Shadow Parts forbids an
+attribute selector after `::part()` — so retoning one state's count otherwise meant overriding the
+library-wide status tokens and repainting every other surface reading them.

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

@@ -0,0 +1,75 @@
+<!-- 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:** `--lr-poll-status-due-bg` (default `var(--lr-color-success)`) —
+background of `indicator` while `data-due` is set. Component-scoped indirection over the shared
+`--lr-color-success` token, so a consumer can retheme just this due-state indicator without
+repainting every other component that reuses the same shared success token. Plus shared tokens —
+`--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`.