@aceshooting/lyra-ui 5.0.0 → 5.2.0

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

@@ -0,0 +1,62 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-csv-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/csv-viewer/csv-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraCsvViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/csv-viewer/csv-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `papaparse` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-csv-viewer`
+
+Fetches CSV text, parses quoted fields with the optional `papaparse` peer, and virtualizes body rows.
+
+Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses the raw file grid, 1-based, with the
+header row included whenever `has-header-row` is set; `scrollToAnchor()` scrolls the addressed
+row/column into view via the virtualized list's `active-id`. `highlights` paint as a focusable
+`part="cell-highlight"`.
+
+**Properties:** `src` and `name` are strings. `hasHeaderRow: boolean = true` (attribute
+`has-header-row`) controls whether the first parsed row is rendered as a sticky header.
+`maxHeight: string = ''` (attribute `max-height`) is a CSS length that caps the scrollable body —
+setting it writes `--lr-csv-viewer-max-height` inline on `[part="base"]`. `anchorKinds` is a
+readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for the shared
+anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count via a case-insensitive substring match over
+the same stringified cell values `cell()` renders, ordered row then column (empty/whitespace query
+behaves like `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches
+(wrapping, resolving `false` when there are none); `clearSearch()` clears the query, matches, and
+painted marks.
+
+**Events:** `lr-render-error` with `detail.error` when fetching or parsing reports an error.
+`lr-highlight-activate` (`detail: { id }`) — a `highlights` cell was clicked or activated via
+Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
+`scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, activeIndex }`) — from
+`search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
+
+**CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a cell covered by
+a `highlights` entry), `rows`, `spinner`, and `error`. `data-row`, `cell` and `cell-highlight` are
+rendered inside the internal `<lr-virtual-list>` and forwarded via `exportparts`, so
+`lr-csv-viewer::part(cell)` reaches them from a consumer stylesheet.
+
+**Themeable custom properties:** `--lr-csv-viewer-max-height` (default `none`) — maximum block size
+of `[part="body"]` before it scrolls internally; also settable via the `maxHeight` property, which
+writes this token inline on `[part="base"]`. `--lr-csv-viewer-highlight-color` (default
+`var(--lr-color-brand)`) — the outline color of a `cell-highlight` cell. The component writes it
+inline (as `var(--lr-color-warning, var(--lr-color-brand))`) on the cell matching
+`activeHighlightId`, since a `[data-active]` selector can't be chained onto the
+`::part(cell-highlight)` the cell reaches this component's stylesheet through; a custom property
+inherits across that boundary instead.
+
+**Optional peer dependency:** install `papaparse` with `pnpm add papaparse`. The registry matches
+`text/csv` and `.csv` filenames.
+
+Remote resources are capped at 25 MB, and the parsed table at 10,000 rows and 1,000 columns;
+exceeding any of these surfaces the localized `documentPreviewResourceTooLarge` message instead of
+the table.
+
+---

package/llms/components/lr-dashboard-grid.md

@@ -0,0 +1,34 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-dashboard-grid`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.js';` (registers the tag; side-effect import)
+- **Class** `LyraDashboardGrid`, also available unregistered from `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-dashboard-grid`
+
+Responsive, keyboard-accessible controlled widget grid. It positions layout entries and emits
+move, resize, collision, and layout-change requests; the host owns persistence and applies updates.
+
+**Properties:** `layout: DashboardCell[] = []` (attribute: false, never mutated by the component),
+`columns: number = 12`, `rowHeight: number = 80` (px, also the row snap pitch), `gap: number = 8`
+(px, both axes), `collision: 'reject' | 'push' | 'overlap' = 'reject'`, `cellsDraggable: boolean = false`
+(attribute `cells-draggable` — pointer drag plus Ctrl/Cmd+Arrow), `cellsResizable: boolean = false`
+(attribute `cells-resizable` — the resize handle plus Ctrl/Cmd+Shift+Arrow), `locked: boolean =
+false` (reflected — disables every gesture grid-wide), `accessibleLabel: string | null = null`
+(attribute `aria-label`, falls back to a localized grid name).
+
+**Events:** `lr-cell-move` (`detail: { id, position, previous }`), `lr-cell-resize`
+(`detail: { id, size, previous }`), `lr-collision` (`detail: { id, collidedWith, policy, accepted }`),
+`lr-layout-change` (`detail: { layout }`, the full proposed layout after an accepted change).
+**Slots:** `cell-{id}`. **CSS parts:** `base`, `cell`, `empty`, `resize-handle`, `live-region`.
+
+**Themeable custom properties:** `--lr-dashboard-grid-columns`, `--lr-dashboard-grid-row-height`,
+and `--lr-dashboard-grid-gap` back the CSS Grid's `grid-template-columns`/`grid-auto-rows`/`gap`.
+The `columns`/`rowHeight`/`gap` properties write them inline on `[part='base']` on every render, so
+overriding them from a stylesheet has no effect — set the properties instead.

package/llms/components/lr-data-grid.md

@@ -0,0 +1,55 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-data-grid`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/data-grid/data-grid.js';` (registers the tag; side-effect import)
+- **Class** `LyraDataGrid`, also available unregistered from `@aceshooting/lyra-ui/components/data/data-grid/data-grid.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-data-grid`
+
+Keyboard-navigable data grid with typed `columns` and `rows`, sortable headers, roving cell focus,
+loading/empty states, and responsive horizontal overflow.
+
+**Properties:**
+- `columns: DataGridColumn<T>[] = []` (attribute: false) — `{ key, label, width?, sortable?,
+  value? }`; `width` becomes the header cell's `inline-size`, `value(row)` overrides the default
+  `row[key]` lookup
+- `rows: T[] = []` (attribute: false)
+- `rowKey: (row: T, index: number) => string | number = (_row, index) => index` (attribute: false)
+- `selectedKey: string | number | null = null` (attribute: false) — compared against `rowKey(row, i)`
+  to set `[part='row'][data-selected]` and `aria-selected`
+- `sortKey: string = ''`, `sortDirection: 'ascending' | 'descending' = 'ascending'`
+  (attribute: false) — the grid updates both on header activation and emits `lr-sort`, but never
+  reorders `rows`; sorting stays the consumer's job
+- `loading: boolean = false` (reflected) — replaces the body with a localized "loading" row
+- `emptyText: string = ''` (attribute `empty-text`) — empty-state text; falls back to the localized
+  `noData`
+- `accessibleLabel: string = ''` (attribute `aria-label`) — names the `role="grid"` table; falls back
+  to the localized `dataGridLabel`
+
+**Keyboard:** exactly one cell is tabbable. Arrows move the roving focus (Left/Right are swapped
+under RTL), Home/End jump to the first/last column of the current row, Enter/Space activate the row.
+The focus position is re-clamped whenever `rows`/`columns` shrink, so the grid can't lose its tab stop.
+
+**Events:** `lr-row-click` (`detail: { row }`, click or Enter/Space), `lr-selection-change`
+(`detail: { row }`, emitted alongside it after `selectedKey` updates), `lr-cell-focus`
+(`detail: { row, column }`, `column` is the column `key`), `lr-sort` (`detail: { key, direction }`,
+`sortable` columns only; re-activating the active column flips `direction`).
+
+**Slots:** none.
+
+**CSS parts:** `viewport` (the scrolling bordered wrapper), `grid` (the `<table role="grid">`),
+`header` (each sticky `<th>`), `row`, `cell`, `empty` (the loading / no-data cell).
+
+**Themeable custom properties:** `--lr-data-grid-row-selected-bg` (default
+`var(--lr-color-brand-quiet)`) — the background of the selected row's cells. It is an inline `var()`
+fallback at its point of use rather than a `:host` declaration, so it can be set on the element *or
+any ancestor*. It exists because Shadow Parts forbids an attribute selector after `::part()` —
+`::part(row)[aria-selected='true']` is invalid CSS — leaving the library-wide
+`--lr-color-brand-quiet` token as the only prior lever, which repaints every other surface reading
+it. `lr-table` exposes the equivalent knob as `--lr-table-row-selected-bg`.

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

@@ -0,0 +1,63 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-dataset-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/dataset-viewer/dataset-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraDatasetViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/dataset-viewer/dataset-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `papaparse` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-dataset-viewer`
+
+Fetches tab-, pipe-, or delimiter-separated text and renders a virtualized, accessible table (a
+`role="table"` container with a sticky `role="row"` header, composed with `<lr-virtual-list
+item-role="row">` for the body) using the optional `papaparse` peer. The document registry matches
+`.tsv`, `.psv`, and `.dat` filenames.
+
+Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses the raw file grid, 1-based, with the
+header row always occupying row 1 (this component always parses with a header row, so the first row
+is never part of the virtualized body); `scrollToAnchor()` scrolls the addressed row into view via
+the virtualized list's `active-id`. `highlights` paint as a `part="cell-highlight"` cell wrapping a
+focusable `part="cell-highlight-action"` native button, keeping the ARIA table tree intact.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `anchorKinds` is
+a readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for the shared
+anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count via a case-insensitive substring search over
+every body cell's raw string value, ordered row then column (empty/whitespace query behaves like
+`clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches (wrapping,
+resolving `false` when there are none); `clearSearch()` clears the query, matches, and cursor.
+
+**Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
+`lr-highlight-activate` (`detail: { id }`) — a `highlights` cell was clicked or activated via
+Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
+`scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, activeIndex }`) — from
+`search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
+
+**CSS parts:** `base`, `body`, `table`, `header-row`, `header-cell`, `data-row`, `cell`,
+`cell-highlight` (a `role="cell"` covered by a `highlights` entry; wraps the action button),
+`cell-highlight-action` (the native button filling a highlighted cell — focusable, emits
+`lr-highlight-activate` on click or Enter/Space), `spinner`, and `error`. `data-row`, `cell`,
+`cell-highlight` and `cell-highlight-action` render inside the internal `<lr-virtual-list>` and are
+forwarded via `exportparts`, so `lr-dataset-viewer::part(cell)` reaches them from a consumer
+stylesheet.
+
+**Exports:** `DatasetTable` is `{ fields: string[]; rows: Record<string, string>[] }`.
+
+**Themeable custom properties:** `--lr-dataset-viewer-max-height` (default `none`) — maximum block
+size of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+`--lr-dataset-viewer-highlight-color` (default `var(--lr-color-brand)`) — the outline color of a
+`cell-highlight` cell. The component writes it inline (as
+`var(--lr-color-warning, var(--lr-color-brand))`) on the cell matching `activeHighlightId`, since a
+`[data-active]` selector can't be chained onto the `::part(cell-highlight)` the cell reaches this
+component's stylesheet through; a custom property inherits across that boundary instead.
+
+**Optional peer dependency:** `papaparse`.
+
+Remote resources are capped at 25 MB, and the parsed table at 10,000 rows and 1,000 columns (the
+same shared default as `lr-csv-viewer`/`lr-spreadsheet-viewer`); exceeding either surfaces the
+localized `documentPreviewResourceTooLarge` message instead of the table.

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

@@ -0,0 +1,226 @@
+<!-- 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`, 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).
+
+---