@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-date-picker.md

@@ -0,0 +1,226 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-date-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/date-picker/date-picker.js';` (registers the tag; side-effect import)
+- **Class** `LyraDatePicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/date-picker/date-picker.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-date-input` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-date-picker` / `lr-date-input` (+ `calendar-core.ts`)
+
+Mirrors the core `<wa-date-picker>`/`<wa-date-input>` API under `lr-`. **Value is always ISO
+8601**: `YYYY-MM-DD` (single) or `YYYY-MM-DD/YYYY-MM-DD` (range).
+
+### `lr-date-picker`
+
+Inline month-grid calendar, not form-associated (used standalone or embedded inside
+`lr-date-input`'s popover).
+
+**Properties:**
+- `value: string = ''`
+- `mode: 'single'|'range' = 'single'` — unknown runtime values fall back to `single`
+- `min: string = ''`
+- `max: string = ''`
+- `disabled: boolean = false` (reflected)
+- `readonly: boolean = false` (reflected)
+- `months: 1|2 = 1` — finite runtime values are truncated and clamped to `1..2`; non-finite
+  values fall back to `1`
+- `locale: string = ''` — malformed locale tags fall back to the platform locale
+- `firstDayOfWeek: string = 'auto'` (attribute `first-day-of-week` — see gotchas)
+- `weekdayFormat: 'narrow'|'short'|'long' = 'short'` (attribute `weekday-format`; unknown runtime
+  values fall back to `short`)
+- `disablePast: boolean = false` (attribute `disable-past`)
+- `disableFuture: boolean = false` (attribute `disable-future`)
+- `withOutsideDays: boolean = false` (attribute `with-outside-days`)
+- `previousLabel: string = 'Previous month'` (attribute `previous-label` — accessible label for the
+  previous-month nav button; override for a non-English `locale`)
+- `nextLabel: string = 'Next month'` (attribute `next-label` — accessible label for the next-month
+  nav button)
+
+**Getters:** `selection: { from: Date|null; to: Date|null }`, `valueAsDate: Date | null` (single
+mode only)
+
+**Methods:** `clear()`, `goToToday()`, `goToDate(date: string | Date)` (valid dates are clamped to
+`min`/`max` before navigating/focusing; invalid `Date` objects and strings are ignored)
+
+**Events:** `input` (during interaction — for range mode, fires after the first click of a pair),
+`change` (committed value)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `month`, `header`, `title`, `previous`, `next`, `weekdays`, `weekday`,
+`grid`, `week`, `day`, `day-outside`, `day-today`, `day-selected`, `day-range-start`,
+`day-range-end`, `day-range-inner`, `day-placeholder`
+
+**Themeable custom properties:** `--lr-cell-size` (default `2.25rem`, controls day-cell/grid-column
+size).
+
+**Optional peer deps:** none.
+
+### `lr-date-input`
+
+Text field + calendar popover, **form-associated** via the shared `FormAssociated` mixin (`name`,
+`value`, `disabled`, `required` all inherited).
+
+**Properties (own):**
+- `mode: 'single'|'range' = 'single'`
+- `min: string = ''`
+- `max: string = ''`
+- `readonly: boolean = false` (reflected; preserves the submitted value but bars required and
+  date-bound constraint validation until removed)
+- `open: boolean = false` (reflected)
+- `withClear: boolean = false` (attribute `with-clear`)
+- `label: string = ''`
+- `hint: string = ''`
+- `placeholder: string = ''`
+- `locale: string = ''` — malformed locale tags fall back to the platform locale
+- `months: 1|2 = 1` — finite runtime values are truncated and clamped to `1..2`; non-finite
+  values fall back to `1`
+- `firstDayOfWeek: string = 'auto'`
+- `weekdayFormat: 'narrow'|'short'|'long' = 'short'` — unknown runtime values fall back to `short`
+- `disablePast: boolean = false` (attribute `disable-past`)
+- `disableFuture: boolean = false` (attribute `disable-future`)
+- `withOutsideDays: boolean = false` (attribute `with-outside-days`)
+
+**Properties (own, continued):**
+- `errorText: string = ''` (attribute `error-text` — static error copy; overridden by slotted
+  `error` content when provided)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the internal
+  `<input>`'s computed accessible name; wins over `label`/`placeholder`/the localized `date`
+  fallback in that order. Attribute-reflects from a host-level `aria-label` so a plain-markup
+  consumer gets ARIA-name forwarding without setting a JS property.
+- `clearLabel: string = 'Clear'` (attribute `clear-label` — accessible label for the clear button)
+- `openLabel: string = 'Open calendar'` (attribute `open-label` — accessible label for the
+  calendar-toggle button)
+- `dialogLabel: string = 'Choose date'` (attribute `dialog-label` — accessible name for the
+  `role="dialog"` calendar popover)
+- `spellcheck: boolean = true` — forwarded to the internal `<input>`
+- `autocapitalize: string = ''` — forwarded to the internal `<input>`; empty omits the attribute
+- `autoCorrect: string = ''` (attribute `autocorrect`, Safari/WebKit-specific) — forwarded to the
+  internal `<input>`; empty omits the attribute. Named `autoCorrect` in JS/TS (not `autocorrect`)
+  to dodge a `lib.dom.d.ts` collision with `HTMLElement`'s own boolean `autocorrect` IDL member;
+  the wire attribute is still the plain `autocorrect` name
+- `autocomplete: string = ''`, `inputMode: string = ''` (attribute `inputmode`), and
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the internal date input
+- `autocomplete: string = ''`, `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''`
+  (`enterkeyhint`) — forwarded to the internal `<input>`.
+- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — visual size, matching
+  `lr-input`/`lr-select`/`lr-combobox`'s shared scale. Governs the field's padding and font-size;
+  the calendar-toggle and clear buttons keep a constant, accessible touch target at every size.
+  The default `m` tier is unchanged from this component's pre-`size` rendering.
+
+**Methods:** `show()`, `hide()`, `clear()`, `focus(options?)`, `blur()`, `select()`,
+`setSelectionRange()`, `setRangeText()` (all of the focus/selection methods forward to the internal
+native date `<input>`).
+
+**Getters:** `input: HTMLInputElement | undefined` — the internal native `<input>`, for direct DOM
+access.
+
+**Selection properties:** `selectionStart`, `selectionEnd`, and `selectionDirection` mirror the
+internal native date input.
+
+**Events:** `input`, `change`, `lr-show`, `lr-hide`, `lr-clear`, `blur` (re-dispatched from
+the internal `<input>`'s own `blur`, bubbling and composed unlike the native event), `focus`
+(re-dispatched from the internal `<input>`'s own `focus`, for the same reason as `blur`)
+
+**Slots:** `label`, `error` (overrides `errorText`), `hint`, plus two adornment slots:
+- `start` — content at the inline-start of the input row, before the text field.
+- `end` — content after the text field and the built-in clear action, and before the calendar
+  toggle, so consumer content never sits outboard of the calendar button.
+
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `start` and `end`
+(the two adornment-slot wrappers, each `hidden` while nothing is slotted into it), `clear-button`,
+`expand-button`, `expand-icon`, `popup`, `date-picker`, `error`, `hint`
+
+**Themeable custom properties:** `--lr-date-input-padding-block` (default `--lr-space-xs`) and
+`--lr-date-input-padding-inline` (default `--lr-space-s`) — the `input-wrapper`'s padding;
+`--lr-date-input-font-size` (default `inherit`) — the `input` part's font size;
+`--lr-date-input-control-min-height` (default `--lr-size-2-5rem`) — the `input-wrapper`'s block-size
+floor. All four are declared on `:host` and auto-swapped per `size`
+(`2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the `:host` defaults), using the same per-`size` values
+`lr-input` uses. Plus shared tokens.
+
+`--lr-date-input-control-height` pins an **exact** `input-wrapper` height (both floors and caps it).
+It is **undeclared by default**, so the row grows to fit its content — see "exact-height hatches"
+under `lr-input`. Pinning it *below* the calendar toggle's 24×24 target is safe: the toggle keeps
+its own `--lr-icon-button-size` floor and simply overflows a short row rather than shrinking, so
+WCAG 2.2 SC 2.5.8 is preserved either way.
+
+**Height parity with `lr-input` is density parity, not pixel parity.** The per-`size` padding and
+font-size scale is shared with `lr-input`, so the two look equally dense at a given `size` — but a
+same-`size` pair does **not** end up the same height, and code that assumes it will be
+disappointed at the small tiers. `[part='input-wrapper']` carries no intrinsic `min-block-size` of
+its own, while `[part='expand-button']` pins `min-block-size: var(--lr-icon-button-size)` that is
+deliberately **not** gated by `size` — the calendar toggle must keep a 24×24 touch target at every
+tier, and `lr-input`'s own password-toggle floors identically. So the row height is pinned
+transitively by that button: at `size="s"` an `lr-input` floors at `1.875rem`/30px, while an
+`lr-date-input` cannot go below roughly 40px plus its padding. Every default value of
+`--lr-date-input-control-min-height` sits below that transitive height, which means the floor is
+inert until you raise it past the button — a lower value changes nothing. To line the two controls
+up exactly, either raise `lr-input`'s floor to meet the date input, or lower
+`--lr-theme-icon-button-size` on a common ancestor (never below 24px).
+
+**Optional peer deps:** none.
+
+```html
+<lr-date-input id="di" label="Start date" with-clear name="start"></lr-date-input>
+<script type="module">
+  const di = document.getElementById('di');
+  di.value = '2026-07-10';
+  di.addEventListener('change', () => console.log(di.value)); // ISO string
+</script>
+```
+
+`calendar-core.ts` exports the pure date math both components share (**internal — not re-exported
+from the package root**, but worth knowing when reasoning about behavior): `parseISO`, `formatISO`,
+`isSameDay`, `addMonths`, `addMonthsClampingDay(date, n)` (like `addMonths` but clamps the result to
+the target month's last day instead of overflowing into the month after — e.g. Jan 31 + 1 month
+lands on Feb 28/29, not Mar 3; backs `lr-date-picker`'s PageUp/PageDown), `clampDate`,
+`monthMatrix(year, month, firstDayOfWeek)`, `weekdayLabels(firstDayOfWeek, format, locale)`,
+`monthTitle(year, month, locale)`, `resolveFirstDayOfWeek(value, locale?)`,
+`normalizeCalendarMode(value)`, `normalizeCalendarMonths(value)`, `normalizeWeekdayFormat(value)`,
+and `dateTimeFormat(locale, options)`.
+
+**Known gotchas:**
+- `first-day-of-week="auto"` now derives from `locale` when the runtime's `Intl.Locale` exposes
+  week-info (`weekInfo`/`getWeekInfo()`, still shifting between engines) — `resolveFirstDayOfWeek()`
+  only hardcodes Sunday as the fallback when that isn't available or `locale` is unset. A
+  French/German-locale user with a supporting runtime now gets the Monday-first grid their OS would
+  show; on an older runtime it still falls back to Sunday-first silently. **If you need a guaranteed
+  locale-correct week start regardless of runtime**, pass an explicit
+  `first-day-of-week="mon"` (accepted values: `sun`/`mon`/`tue`/`wed`/`thu`/`fri`/`sat`).
+- Runtime attribute/property inputs are normalized before calendar math or `Intl` formatting:
+  unsupported modes and weekday formats use their documented defaults, month counts cannot exceed
+  the two-grid API, malformed locale tags use the platform locale, and invalid `Date` objects do
+  not replace the current view.
+- (date-input only) — opening the calendar does not move focus into it: `Alt+ArrowDown` leaves focus
+  on the text input, and the expand button keeps focus when clicked. The focused opener is
+  remembered. Escape and a finalized calendar selection close the popup and return focus to that
+  same connected element; a direct `.open = false` also restores it when focus would otherwise
+  remain inside the now-hidden popup. Outside-pointer dismissal deliberately leaves focus at the
+  clicked target.
+- (date-input only) — typing an unparseable string and blurring/committing sets `badInput` via
+  `internals.setValidity()` and reverts the displayed text to the last valid commit. The visible
+  `<input part="input">` mirrors `required` through native `required`/`aria-required` and exposes
+  touched outer validity through `aria-invalid`; this includes required, bad-input, and range
+  failures owned by the form-associated host. A host `aria-label` is reactively forwarded to the
+  input, including later changes/removal, and takes precedence over the component's
+  label/placeholder fallback. Native validation attempts reveal `aria-invalid`; `form.reset()`
+  clears that touched presentation. A parseable typed date outside an active bound is committed
+  instead and reports the precise `rangeUnderflow`/`rangeOverflow` state.
+- (date-input only) — declarative, IDL, reset, and restored values are sanitized to exact ISO dates:
+  calendar-invalid or malformed strings become `''` (and therefore `valueMissing` when required),
+  while valid dates outside `min`/`max` or `disable-past`/`disable-future` remain submitted and expose
+  `rangeUnderflow`/`rangeOverflow`. Changes to these constraints, `mode`, and `readonly` recompute
+  validity synchronously; range mode validates both endpoints.
+- The grid keyboard pattern (Arrow/PageUp/PageDown/Home/End navigation with correct focus
+  sequencing) is implemented correctly and safe to rely on, as is the selected/range-day text color
+  (`--lr-color-on-brand`, not a hardcoded literal — safe to override `--lr-color-brand` without
+  losing contrast on selected-day text).
+
+---

package/llms/components/lr-details.md

@@ -0,0 +1,23 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-details`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/details/details.js';` (registers the tag; side-effect import)
+- **Class** `LyraDetails`, also available unregistered from `@aceshooting/lyra-ui/components/layout/details/details.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-accordion`, `lr-accordion-item` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-details`, `lr-accordion`, and `lr-accordion-item`
+
+`lr-details` is a native-semantics disclosure panel. `lr-accordion` coordinates slotted
+details panels and closes siblings unless `multiple` is true. `lr-accordion-item` is an
+accordion-compatible alias.
+
+**Properties:** `open`, `disabled`, and `summary` on details/items; `multiple` on accordion.
+**Events:** `lr-toggle` with `{ open }` from details/items. **Slots:** `summary` and default
+content on details/items; default panels on accordion. **CSS parts:** `base`, `summary`, `content`
+on details/items; `base` on accordion.

package/llms/components/lr-dialog.md

@@ -0,0 +1,185 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-dialog`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/dialog/dialog.js';` (registers the tag; side-effect import)
+- **Class** `LyraDialog`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/dialog/dialog.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-dialog` / `confirm()`
+
+General-purpose modal/overlay plus a promise-based confirmation helper built on top of it.
+
+### `lr-dialog`
+
+A modal/overlay: `role="dialog"`, focus-trapped while open, dismissible via Escape or a backdrop
+click, and scroll-locks the document for as long as it's open. Chrome stays minimal by default — no
+built-in title bar or close button; a consumer supplies a heading and any close affordance itself via
+the default/`footer` slots. `heading`/`closable` are an opt-in convenience for the common case where
+hand-building that chrome isn't worth it.
+
+**Properties:**
+- `open: boolean = false` (reflected) — there is no separate `show()`/`hide()` pair; set this (or
+  call `close()`)
+- `label: string = ''` — accessible name used only when no heading is slotted and `heading` is unset
+  (see below)
+- `heading?: string` — visible header text (rendered in `[part="header"]`/`[part="heading"]`), used
+  only when no light-DOM heading is slotted into the default slot; has no effect (renders nothing)
+  when a heading element *is* slotted, which keeps working completely unchanged either way
+- `closable: boolean = false` (attribute `closable`) — renders a built-in close (X) button in the
+  header row (creating one, with no heading text, if `heading` is unset), wired to the same
+  `close()` path Escape/backdrop-dismiss already use, with reason `'close-button'`
+- `noLightDismiss: boolean = false` (attribute `no-light-dismiss`) — prevents a backdrop click from
+  closing the dialog; Escape and explicit `close()` calls remain available
+
+Also settable as a plain `aria-label` attribute (not a public JS property): overrides the panel's
+computed accessible name outright, winning over every other source below (a slotted heading,
+`heading`, `label`) — matching `<lr-date-input>`'s `accessibleLabel` pattern. Left unset, the
+existing three-tier fallback below is unchanged.
+
+**Methods:** `close(reason: DialogCloseReason = 'api'): void` — closes the dialog, emits
+`lr-dialog-close` with `reason`, and returns focus to whatever had it right before the dialog
+opened. `DialogCloseReason = 'escape' | 'backdrop' | 'close-button' | 'api' | 'unmount' | string` —
+`'escape'`/`'backdrop'` are emitted by the dialog's own built-in dismiss triggers; `'close-button'`
+by the built-in header close button (rendered when `closable` is set); `'unmount'` is emitted
+automatically if the dialog is removed from the DOM while still `open` by anything other than its
+own `close()` (a consumer's own cleanup code, a parent re-render that drops it); any other string is
+whatever a caller passes (e.g. a footer Cancel button calling `dlg.close('cancel')`, or `confirm()`'s
+own `'confirm'`/`'cancel'`).
+
+**Events:** `lr-dialog-close` (`detail: DialogCloseReason`) — fired on every dismissal path
+(Escape, backdrop click, any `close()` call, or an `'unmount'` removal as above).
+
+**Stacking:** participates in the shared per-document overlay stack described above. A dialog can be
+stacked with another dialog or any other modal family; only the visually topmost overlay receives
+Escape, Tab trapping, or backdrop dismissal, while overlays beneath remain open until the top one
+closes.
+
+**Slots:** default (the dialog body), `footer` (action buttons, rendered in a bottom row, hidden
+entirely when empty)
+
+**CSS parts:** `backdrop` (the full-viewport scrim), `panel` (the dialog panel, `role="dialog"`
+while open; its max-inline-size is controlled by `--lr-dialog-max-width`), `header` (the header
+row, rendered when `heading` is set — and no heading is slotted — and/or `closable` is `true`),
+`heading` (the visible `heading`-text element inside `header`, rendered only when `heading` is set
+and no heading is slotted), `close-button` (the built-in close button inside `header`, rendered only
+when `closable` is `true`), `label` (the invisible label-text element used for `aria-labelledby`
+when no heading is slotted and `heading` is unset), `body` (wrapper around the default slot),
+`footer` (wrapper around the `footer` slot)
+
+**Themeable custom properties:** `--lr-dialog-overlay-color` (default `rgb(0 0 0 / 0.5)` — the
+backdrop scrim color; component-specific since no shared `--lr-*` overlay token exists),
+`--lr-dialog-width` (default unset/`auto` — the panel shrink-wraps to content, unchanged; set it
+for an assertive width instead), `--lr-dialog-max-width` (default `32rem` — the panel's
+max-inline-size cap, via `min(var(--lr-dialog-max-width, var(--lr-dialog-width, 32rem)), 100%)`;
+when `--lr-dialog-width` is set but `--lr-dialog-max-width` is left at its default, the cap falls
+back to the requested width itself — not the `32rem` default — so an assertive width isn't silently
+clipped; the viewport is still a hard limit either way), plus shared tokens `--lr-space-l/-m/-s`,
+`--lr-color-surface/-border`, `--lr-radius`, `--lr-shadow`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-dialog id="dlg">
+  <h2>Delete item?</h2>
+  <p>This cannot be undone.</p>
+  <div slot="footer">
+    <button id="cancel">Cancel</button>
+    <button id="confirm">Delete</button>
+  </div>
+</lr-dialog>
+<script type="module">
+  const dlg = document.getElementById('dlg');
+  dlg.open = true;
+  dlg.addEventListener('lr-dialog-close', (e) => console.log('closed:', e.detail));
+  document.getElementById('cancel').addEventListener('click', () => dlg.close('cancel'));
+</script>
+```
+
+Accessible name / visible header, in priority order: (0) if the host element itself has an
+`aria-label` attribute set, its value becomes `aria-label` on the panel outright, overriding every
+source below (including a slotted heading) and suppressing the visible header/`heading` row and the
+sr-only `label` element from rendering at all — the standard ARIA convention for a consumer that
+wants full control over the announced name regardless of whatever `heading`/`label` props are also
+set; (1) otherwise, if a heading element (`h1`–`h6` or
+`[role="heading"]`) is a *direct child* (not inside `slot="footer"`), its text content becomes
+`aria-label` on the panel — takes priority over `heading` below so an existing consumer that already
+slots its own heading keeps rendering it exactly as before; (2) otherwise, when `heading` is set, a
+visible header row (`[part="header"]`) renders containing that text (`[part="heading"]`), which
+becomes the `aria-labelledby` target; (3) otherwise, when `label` is set, an invisible (`.sr-only`,
+exposed as the `label` part) element carrying that text is rendered inside the panel and
+`aria-labelledby` points at it instead. Only one of cases 2/3 ever renders at a time. `label` itself
+never renders visible chrome on its own — `::part(label)` can be restyled to make the sr-only text
+visible, or `heading` can be set instead, for visible chrome without slotting a real heading element.
+The slotted-heading case (1) deliberately uses `aria-label` (a copied string) rather than
+`aria-labelledby` pointing at the heading's `id`, because the heading is light-DOM content while
+`[part="panel"]` lives in shadow DOM and an ID-reference attribute can't resolve across that
+boundary; cases 2/3 use `aria-labelledby` safely since their target renders inside the same shadow
+root it labels.
+
+**Known gotchas:**
+- `role="dialog"`/`aria-modal="true"` are only present on `[part="panel"]` while `open` is `true` —
+  inspecting closed markup won't show them.
+- Heading detection only rescans on `slotchange`, not on every render — mutating an already-slotted
+  heading's `textContent` in place (rather than replacing the node) won't retroactively update
+  `aria-label`; set `label` instead for a title that needs to change live.
+- Only *direct* children are scanned for a heading — one nested several layers deep, or inside a
+  slotted custom element's own shadow root, is left to the consumer to label explicitly via `label`.
+- 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 `open` was still `true` across the
+  move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in between, so
+  `willUpdate()` alone wouldn't otherwise notice.
+- Tab-trap focus order follows the default (body) slot, then the `footer` slot — the same order the
+  flattened tree already tabs through — and is resolved shadow-piercingly, so a slotted custom
+  element's real focusable target inside its own shadow root is found even though the host tag
+  itself isn't a native focusable element.
+
+### `confirm()`
+
+A drop-in async replacement for `window.confirm()`, built on `<lr-dialog>`.
+
+```ts
+import { confirm } from '@aceshooting/lyra-ui/components/overlays/dialog/confirm.js';
+
+const ok = await confirm({
+  title: 'Delete conversation?',
+  description: 'This cannot be undone.',
+  confirmLabel: 'Delete',
+  tone: 'danger',
+});
+if (ok) deleteConversation();
+```
+
+`confirm(options: ConfirmOptions): Promise<boolean>` where
+`ConfirmOptions = { title: string; description?: string; confirmLabel?: string /* = 'Confirm' */; cancelLabel?: string /* = 'Cancel' */; tone?: 'neutral' | 'danger' /* = 'neutral' */ }`.
+
+Resolves `true` only when the confirm button is pressed — Escape, a backdrop click, and the cancel
+button all resolve `false`. Mounts a transient `<lr-dialog>` on `document.body` for the duration
+of the call and removes it once settled, rather than reusing a persistent page-level region
+(contrast `lr-toast`'s `toaster.ts`): a confirmation modal has no stacking/queueing concerns —
+only one is ever meant to be open at a time — so a mount-and-remove per call keeps its lifetime
+trivially tied to the returned promise. `title` becomes a slotted `<h2>`, which per `<lr-dialog>`'s
+own heading-detection also drives the dialog's accessible name; `description`, if provided, becomes
+a slotted `<p>`. `tone: 'danger'` fills the confirm button with `--lr-color-danger` instead of
+`--lr-color-brand`, for destructive actions. Confirm/cancel buttons are plain inline-styled
+`<button>` elements (no shared button component exists in this library yet), but every color value
+used is still a `--lr-*` token reference, never a raw literal.
+
+**Known gotchas:**
+- Every dismissal path (confirm button, cancel button, Escape, backdrop click) funnels through
+  `<lr-dialog>`'s own `close()`/`lr-dialog-close` event, so there is exactly one place that
+  resolves the promise and tears the dialog down — a consumer never needs to (and shouldn't) call
+  `.remove()` itself.
+- The neutral confirm button pairs `--lr-color-on-brand` with `--lr-color-brand`; the danger
+  tone pairs `--lr-color-on-danger` with `--lr-color-danger`. Each token chains through Web
+  Awesome's matching `*-on-loud` semantic role and has contrast-tested standalone light/dark
+  fallbacks.
+- Importing `confirm` alone is enough to register `<lr-dialog>` — `confirm.ts` imports
+  `./dialog.js` for its side effect, so a consumer doesn't need a separate import for the dialog
+  element.
+
+---

package/llms/components/lr-diff-view.md

@@ -0,0 +1,86 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-diff-view`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/diff-view/diff-view.js';` (registers the tag; side-effect import)
+- **Class** `LyraDiffView`, also available unregistered from `@aceshooting/lyra-ui/components/utility/diff-view/diff-view.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** `shiki` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-diff-view`
+
+A real two-string line diff (a classic longest-common-subsequence dynamic program, not a Myers
+implementation), rendered as interleaved unified-diff output — not diff-flavored syntax highlighting
+over an already-formatted string (`<lr-code-block>`'s `language="diff"` only lexically colors a
+string the consumer already unified-diffed; it has no two-string-compare entry point of its own).
+First-party invention (no Web Awesome equivalent).
+
+**Properties:**
+- `oldText: string = ''` (attribute: false) — the "before" text. Default `''` renders an
+  all-additions diff of `newText`.
+- `newText: string = ''` (attribute: false) — the "after" text. Default `''` renders an
+  all-removals diff of `oldText`.
+- `copyable: boolean = false` — shows a copy-to-clipboard button for the full unified-diff text.
+  `false` (the default) renders no button.
+- `layout: 'unified' | 'split' = 'unified'` (reflected) — `'unified'` (the default) renders today's
+  single interleaved `<pre>`; `'split'` renders two side-by-side `[part="side"]` columns derived from
+  the same diff alignment.
+- `language: string = ''` — a shiki-recognized language id. Highlighting activates only when this
+  has a matching entry in `languages` — there is deliberately no default full-table
+  `lr-code-block`-style fallback, so this component never reaches shiki's ~200-language
+  dynamic-import table.
+- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — grammar definitions this
+  instance can highlight, same shape as `lr-code-block-core`'s own `languages`.
+- `contextLines: number | undefined` (attribute: `context-lines`) — keeps this many unchanged
+  lines around each change and collapses longer unchanged runs into a localized fold marker. The
+  default `undefined` shows every line; negative and non-finite values also disable folding.
+
+**Events:** `lr-copy` (`detail: { text: string }` — the full unified-diff text, fired on
+copy-button activation regardless of whether the clipboard write actually succeeded).
+
+**Slots:** none.
+
+**CSS parts:** `base` (the root wrapper), `line` (a single line; carries
+`data-type="equal"|"add"|"remove"|"empty"|"fold"` — `"empty"` is an unbalanced-replace placeholder cell in
+`layout="split"` and never carries a `+`/`-` prefix; `"fold"` is the localized unchanged-lines
+marker), `copy-button` (the copy affordance, only
+rendered while `copyable`), `side` (one column in `layout="split"`, `data-side="old"|"new"`).
+
+**Themeable custom properties:** `--lr-diff-view-font` (default `var(--lr-font-mono)`), plus
+shared tokens `--lr-color-border`/`-surface`/`-success`/`-success-quiet`/`-danger`/
+`-danger-quiet`/`-text`, `--lr-radius`, `--lr-space-xs`/`-s`, `--lr-font-size-sm`,
+`--lr-line-height-snug`, `--lr-focus-ring-*`.
+
+**Optional peer deps:** `shiki` (the same fine-grained `shiki/core`/`shiki/engine/oniguruma`/
+`shiki/wasm` subset `lr-code-block-core` uses, never `shiki`'s full ~200-language main entry point)
+— only loaded once both `language` and a matching `languages` entry are set; unset/unmatched leaves
+the plain unhighlighted diff text untouched.
+
+```html
+<lr-diff-view copyable></lr-diff-view>
+<script type="module">
+  const diff = document.querySelector('lr-diff-view');
+  diff.oldText = 'line one\nline two\nline three';
+  diff.newText = 'line one\nline TWO\nline three\nline four';
+  diff.addEventListener('lr-copy', (e) => console.log(e.detail.text));
+</script>
+```
+
+The package root also exports the pure `computeLineDiff(oldLines: string[], newLines: string[]):
+DiffOp[]` helper (plus the `DiffOp` type, `{ type: 'equal' | 'add' | 'remove'; text: string }`) — the
+same line-diff function this component's own `render()`/copy handler call, exposed standalone so a
+consumer can compute or unit-test the same alignment without instantiating the element at all.
+
+**Known gotchas:**
+- the alignment is a genuine O(n·m) longest-common-subsequence dynamic program over lines (split on
+  `\n`), not a naive "every removed line then every added line" — fine for a typical
+  tool-call/transcript-sized diff, but a very large pair of texts costs quadratic time/memory;
+  there's no line-count guard or chunking of its own.
+- `oldText`/`newText` are recomputed into the diff on every render — this component keeps no separate
+  cached diff state, so binding either property to something that changes on every keystroke
+  recomputes the whole alignment each time.
+
+---

package/llms/components/lr-divider.md

@@ -0,0 +1,28 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-divider`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/divider/divider.js';` (registers the tag; side-effect import)
+- **Class** `LyraDivider`, also available unregistered from `@aceshooting/lyra-ui/components/utility/divider/divider.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-divider`
+
+A semantic separator: renders `<hr part="base" role="separator" aria-orientation="…">`.
+
+**Properties:** `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected).
+
+**Events:** none. **Slots:** none. **CSS parts:** `base`.
+
+**Themeable custom properties:** shared tokens only — `--lr-color-border` (rule color),
+`--lr-border-width-thin` (thickness).
+
+The host is `display: block` when horizontal and `display: inline-block; block-size: 100%` when
+vertical, so a vertical divider fills its flex/grid row's height with no extra CSS — but it needs a
+parent that actually has a resolved height.
+
+---