@aceshooting/lyra-ui 5.0.0 → 5.1.0

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

@@ -0,0 +1,201 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-date-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/date-picker/date-input.js';` (registers the tag; side-effect import)
+- **Class** `LyraDateInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/date-picker/date-input.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-date-picker` (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`
+
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `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. All three are
+declared on `:host` and auto-swapped per `size` (`2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the `:host`
+defaults), deliberately matching `lr-input`'s own per-`size` padding/font-size values so a
+same-`size` `lr-input` and `lr-date-input` end up height/density-matched. Plus shared tokens.
+
+**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-date-picker.md

@@ -0,0 +1,201 @@
+<!-- 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`
+
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `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. All three are
+declared on `:host` and auto-swapped per `size` (`2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the `:host`
+defaults), deliberately matching `lr-input`'s own per-`size` padding/font-size values so a
+same-`size` `lr-input` and `lr-date-input` end up height/density-matched. Plus shared tokens.
+
+**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.
+
+---