@aceshooting/lyra-ui 25.3.1 → 25.5.0

package/llms/components/lr-histogram.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 16 parts, 37 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 17 parts, 39 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -28,6 +28,11 @@ Bins `values` into `bins` equal-width buckets and renders as a bar chart (extend
   chart-wide accessible-name meaning.
 - inherits `lr-chart`'s full surface, including `scaleType` (`scale-type`) and `annotations` —
   a logarithmic frequency axis and threshold/band markers both apply to a histogram
+- `syncGroup: string = ''` (attribute `sync-group`) — inherited exact category coordination for its
+  vertical categorical bar configuration; see
+  [Synchronized categorical charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md#synchronized-categorical-charts). Matches use the generated
+  bucket range strings, so different bin boundaries do not match unless their labels are exactly
+  equal. Horizontal or continuous-x raw configurations do not participate.
 - `labels`/`datasets`/`type` are **derived, read-only** (installed as getter/setter pairs on the
   prototype; direct writes are silently ignored) — `labels`/`datasets` are computed from
   `values`/`bins` (memoized per instance, keyed by reference equality on `values` plus the
@@ -59,12 +64,15 @@ bar controller and dataset legend even with `legend-mode="datum"`.
 **Slots:** default JSON configuration script, `data-table`, `center`.
 
 **CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
+`sync-crosshair` (inherited decorative category line during synchronization; the native canvas
+tooltip has no CSS part),
 `reset-zoom-button`, `description`, `notices`, `data-table`, `data-table-toggle`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
 rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load; the
 failure transition is announced through the shared document-level light-DOM assertive sink —
 inherited from `LyraChart`, unaffected by the binning logic).
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
+`--lr-chart-sync-crosshair-color`, `--lr-chart-sync-crosshair-width`,
 `--lr-chart-tick-color`, `--lr-chart-tick-font-size`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
 `--lr-chart-tooltip-color`, `--lr-chart-legend-item-hover-bg`,
 `--lr-chart-legend-item-active-bg`, `--lr-chart-data-table-button-hover-bg`,

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 16 parts, 37 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 17 parts, 39 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -21,6 +21,13 @@ Each is `LyraChart` with a named default `type` — respectively `line`, `bar`,
 `radar`, `polarArea`, `bubble`, `scatter`. In parity with the mirrored tags, `type` remains writable
 and accepts the full `LyraChartType` vocabulary; the tag name is a convenient default, not a lock.
 
+`syncGroup: string = ''` (attribute `sync-group`) is inherited. The default vertical categorical
+`lr-line-chart` and `lr-bar-chart` configurations can participate in
+[Synchronized categorical charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md#synchronized-categorical-charts). The other six default chart
+types leave it inert; changing `type` or raw `config` to an admitted vertical categorical bar/line
+configuration enables participation regardless of the tag. Horizontal or continuous-x
+configurations remain outside synchronization.
+
 Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
 and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
 of every entry in these lists.**
@@ -51,12 +58,15 @@ Radial category legends additionally emit `lr-datum-visibility-change-request` (
 **Slots:** default JSON configuration script, `data-table`, `center`.
 
 **CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
+`sync-crosshair` (inherited decorative category line, rendered only for an admitted synchronized
+configuration; the native canvas tooltip has no CSS part),
 `reset-zoom-button`, `description`, `notices`, `data-table`, `data-table-toggle`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
 rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load; the
 failure transition is announced through the shared document-level light-DOM assertive sink — see
 `llms/components/lr-chart.md`).
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
+`--lr-chart-sync-crosshair-color`, `--lr-chart-sync-crosshair-width`,
 `--lr-chart-tick-color`, `--lr-chart-tick-font-size`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
 `--lr-chart-tooltip-color`, `--lr-chart-legend-item-hover-bg`,
 `--lr-chart-legend-item-active-bg`, `--lr-chart-data-table-button-hover-bg`,

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

@@ -9,17 +9,21 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 18 parts, 19 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 20 parts, 23 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
 
 ## `lr-lite-chart`
 
+`syncGroup: string = ''` (attribute `sync-group`) opts into
+[Synchronized categorical charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md#synchronized-categorical-charts). Its DOM `sync-crosshair` and
+`sync-tooltip` parts use the shared crosshair and tooltip tokens described there.
+
 A dependency-free bar/line chart — plain SVG/DOM rendering, zero peer dependencies (unlike
 `lr-chart`, which wraps `chart.js`). For a project whose architecture forbids a charting
 dependency outright: covers grouped/stacked bars, multi-series lines, per-point click, and hover
-tooltips (native SVG `<title>`, no positioning JS) — not a full `lr-chart` replacement (no
+tooltips (native SVG `<title>` by default, positioned text tooltips in a sync group) — not a full `lr-chart` replacement (no
 zoom/pan, no pie/doughnut/radar/scatter/bubble types, no horizontal/dual-y-axis, no raw-config
 passthrough). Not a subclass of `LyraChart`.
 
@@ -31,7 +35,7 @@ shape to express. A per-series stack-group id would also need the hand-rolled SV
 pass (linear/sqrt/log stack compression, `minBarHeight`) to track independent running offsets per
 group instead of one per category, which is a materially larger, higher-risk change than this
 component's existing single-stack model. `tooltipTitleFormatter`/`tooltipFooterFormatter` are
-similarly absent: this component's hover tooltip is a native SVG `<title>` on each mark — one
+similarly absent: this component's default hover tooltip is a native SVG `<title>` on each mark — one
 self-contained string per mark, generated by `pointText` — not a Chart.js-style multi-item tooltip
 with separate title/body/footer regions for several datasets sharing a hovered category, so there
 is no "every item in the tooltip" surface to hook a title or footer formatter onto.
@@ -275,7 +279,9 @@ instead of materializing an unbounded hidden DOM or SVG tree.
 **Slots:** `data-table` — optional consumer-provided complete, paginated, or virtualized accessible
 data alternative.
 
-**CSS parts:** `base`, `description`, `grid-line`, `axis-label`, `axis-title`, `bar` and `point` (each carries
+**CSS parts:** `base`, `description`, `grid-line`, `axis-label`, `axis-title`,
+`sync-crosshair` (decorative synchronized category line), `sync-tooltip` (noninteractive positioned
+text tooltip while `syncGroup` is active), `bar` and `point` (each carries
 `data-selected` when its category index is in `selectedIndices`, with explicit pressed state on every
 mark), `line`, `legend`, `legend-item`, `legend-swatch`, `legend-text` (extra per-item text after
 the series label, rendered only when `legendText` is set), `live-region` (the current mark
@@ -303,6 +309,10 @@ suppresses the generated sample and notice.
 
 **Themeable custom properties:** `--lr-chart-height` (same public host-level property and precedence
 as `lr-chart`; it always wins over the `height` property's private fallback);
+`--lr-chart-sync-crosshair-color` (default `var(--lr-color-text)`) and
+`--lr-chart-sync-crosshair-width` (default `var(--lr-border-width-thin)`) style the synchronized
+category line; `--lr-chart-tooltip-bg` (default `var(--lr-color-surface)`) and
+`--lr-chart-tooltip-color` (default `var(--lr-color-text)`) style the positioned synchronized tooltip;
 `--lr-chart-grid-color`, `--lr-chart-tick-color`, `--lr-chart-tick-font-size` (default
 `var(--lr-font-size-2xs)`), `--lr-chart-legend-color` — same token
 *names* as `lr-chart`, so a host already theming `lr-chart` themes this for free;

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [forms](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/forms.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 15 parts, 25 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 17 parts, 25 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -20,8 +20,8 @@ A closed-list locale switcher over the library's own locale registry. First-part
 Web Awesome equivalent). With `locales` unset (the default), the offered rows are exactly
 `getRegisteredLyraLocales()` — every locale with strings registered via `registerLyraLocale()`,
 plus `en` — kept live via `subscribeLyraLocaleRegistry()`. Built directly on `lr-select`'s
-trigger-button/`aria-activedescendant` listbox technique, not composed from it — a plain closed
-list, no filter/free-text mode.
+trigger-button/`aria-activedescendant` listbox technique, not composed from it. Optional
+`searchable` adds a text filter; free text never becomes a locale selection.
 
 Host `aria-describedby` references resolve onto the role=combobox trigger before its local error and
 hint guidance. The relationship tracks missing IDs, target replacement, removal/reinsertion,
@@ -52,6 +52,18 @@ readonly LyraLocaleEntry[]`, `LyraLocaleEntry { tag: string; label?: string; cou
   the catalog while the listbox is open keeps keyboard navigation valid: an active row beyond the
   new end is rehomed to the last remaining row. Arrow/Home/End/typeahead changes scroll the active
   owned option into nearest view after render; replacement and disconnect cancel stale scrolls.
+- `searchable: boolean = false` — add a search field inside the open menu. Substring matching
+  ignores case and accents across language tags, native names, localized names and caller labels;
+  for example, `eng` finds English. Filtering emits no selection events and does not invoke a
+  locale loader. Arrow keys and Enter select an offered match; ordinary text editing and IME
+  composition remain native. Empty results show localized guidance. Closing, disabling, resetting,
+  reconnecting or turning search off clears unfinished filtering. The default keeps the existing
+  compact list without an input.
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`),
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`), `spellcheck: boolean = false`,
+  `autocapitalize: string = ''`, `autocorrect: boolean = true` — native guidance for the filter.
+  The readonly `input: HTMLInputElement | null` exposes it in searchable mode. After directly
+  editing `input.value`, dispatch a native `input` event to update the matches.
 - `topLayer: boolean = false` (attribute `top-layer`, reflected) — same contract as `<lr-popover>`:
   always shows the open listbox in the browser top layer, placed `fixed` whatever the positioning
   strategy resolves to, so it paints above a sibling surface stacked higher than a `z-index`ed fixed
@@ -177,7 +189,9 @@ visually hidden in flag-only mode), `listbox`, `option`, `option-flag` (present
 `optionDisplay` is `label-tag`, and absent from the DOM entirely under `optionDisplay="label"`),
 `expand-icon`,
 `hint`, `error`, `load-status` (the optional localized loading or failure message), and
-`load-retry` (the retry button shown after a locale load fails).
+`load-retry` (the retry button shown after a locale load fails), `search-input` (the opt-in
+filter) and `empty` (the no-match message). Search uses the localized `localePickerSearchLabel`
+and `localePickerEmpty` string keys.
 
 **The required marker.** `required` with a non-empty `label` paints the library's shared marker on
 `[part="form-control-label"]` — the one `::after` rule described under "The required-field marker"

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

@@ -9,6 +9,6 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 16 parts, 37 custom properties — see `lr-line-chart.md`
+- **Themeable via** 17 parts, 39 custom properties — see `lr-line-chart.md`
 - **Documented with** `lr-line-chart`: see [lr-line-chart.md](./lr-line-chart.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`

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

@@ -9,6 +9,6 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 16 parts, 37 custom properties — see `lr-line-chart.md`
+- **Themeable via** 17 parts, 39 custom properties — see `lr-line-chart.md`
 - **Documented with** `lr-line-chart`: see [lr-line-chart.md](./lr-line-chart.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`

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

@@ -9,6 +9,6 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 16 parts, 37 custom properties — see `lr-line-chart.md`
+- **Themeable via** 17 parts, 39 custom properties — see `lr-line-chart.md`
 - **Documented with** `lr-line-chart`: see [lr-line-chart.md](./lr-line-chart.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`

package/llms/components/lr-reorder-list.md

@@ -126,6 +126,11 @@ row content for the repeated move-action names.
   effective owner state. Corresponding custom states include `:state(at-start)`, `:state(at-end)`,
   `:state(list-disabled)`, `:state(pending)`, and `:state(busy)`.
 
+Each move control also carries its localized `moveUp` or `moveDown` action as an `aria-label`
+fallback. The reflected `ariaLabelledByElements` relationship retains the full action and row name
+and takes precedence in supporting browsers. Automation tools that omit reflected element references
+may report only the action fallback; repeated actions can be located within their owning row.
+
 **Events:** `lr-move-request` (`detail: { direction: 'up' | 'down' }` — a move button was activated
 while not disabled; handled by the parent `<lr-reorder-list>`, which performs the actual move)
 

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

@@ -9,6 +9,6 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 16 parts, 37 custom properties — see `lr-line-chart.md`
+- **Themeable via** 17 parts, 39 custom properties — see `lr-line-chart.md`
 - **Documented with** `lr-line-chart`: see [lr-line-chart.md](./lr-line-chart.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`

package/llms/components/lr-select.md

@@ -32,6 +32,29 @@ Session-history/autofill restoration assigns the stored string through the same
 value/form/validity path as a programmatic value write and does not emit `input`, `change`, or
 `lr-change`.
 
+**Selecting options in browser tests.** The light-DOM `<lr-option>` children supply option data;
+the clickable rows are rendered inside `<lr-select>`'s shadow-root listbox as
+`[part="option"][role="option"]`, each with a `data-value` matching its represented value.
+Click the trigger to open the listbox, then target a rendered row. For example, in Playwright:
+
+```ts
+const select = page.locator('lr-select[name="country"]');
+await select.getByRole('combobox').click();
+await select.getByRole('option', { name: 'France' }).click();
+// When the label is localized or otherwise variable, target its value instead:
+await select.getByRole('combobox').click();
+await select.locator('[part="option"][data-value="fr"]').click();
+```
+
+For an in-page component test with a `LyraSelect` element, the public
+`@aceshooting/lyra-ui/testing` `chooseOption(selectElement, 'fr')` driver opens the listbox,
+clicks its first rendered row with that value, and awaits the component update. It also works in
+DOM test environments without Playwright; see [interaction drivers](shared/testing-and-utilities.md#driving-a-components-real-activation-path-interaction-drivers).
+
+Playwright's locators enter the open shadow root. A light-DOM `lr-option[value="fr"]` has no
+clickable box in this picker. If multiple options share a value, `data-value` matches every
+occurrence; narrow by accessible name or assert their order before choosing an occurrence.
+
 Mounted `option.selected` assignments update the picker value and form submission immediately,
 including deselection and equal-value writes. Duplicate-valued options retain their individual
 occurrence identities. These programmatic writes emit no user input/change event.
@@ -236,6 +259,12 @@ renders the same localized `loading` text in place of `placeholder`, so a consum
 hand-write a conditional placeholder bound to the same flag and re-localize, in its own catalogue,
 the string this control already owns.
 
+When not loading, before the browser first reads the option slot, including during SSR, a committed
+value renders as its raw code without an unavailable badge, synthetic unknown option, or custom unknown label.
+After hydration observes the slot, real option labels and genuine unmatched-value feedback resolve
+normally; an observed empty slot is an empty catalog. Server rendering does not inspect browser
+slot assignments or provide an interactive popup without JavaScript.
+
 **Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal trigger button.
 `show()` and `hide()` return `Promise<void>` and resolve after `lr-after-show`/`lr-after-hide` once
 the matching transition settles. `getForm()` returns the browser-resolved form owner, including an

package/llms/components/lr-time-zone-picker.md

@@ -0,0 +1,56 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-time-zone-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/lr-time-zone-picker.js';` (stable tag alias; registers the tag)
+- **Class** `LyraTimeZonePicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/time-zone-picker/time-zone-picker.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Status** `experimental` since `25.5.0` — see the maturity and deprecation policy in `llms/shared.md`
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [forms](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/forms.md)
+- **Deprecations** none
+- **Optional peers** none
+- **Themeable via** 11 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-time-zone-picker`
+
+A form-associated identifier selector. Import
+`@aceshooting/lyra-ui/components/lr-time-zone-picker.js`. It follows the
+[shared field contract](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/components/lr-country-picker.md),
+with `.timeZones` accepting
+`LyraTimeZoneCatalog = readonly string[] | readonly LyraTimeZoneEntry[]`.
+Default options are `UTC` followed by the runtime's supported primary IANA identifiers, or only
+`UTC` when that catalog API is unavailable. Supply the same explicit catalog on server and client
+when their time-zone data may differ. `value=''` selects nothing automatically.
+
+Identifiers are trimmed and case-sensitive, limited to 256 characters, and never canonicalized.
+Caller catalogs can retain aliases or custom identifiers. Default labels replace underscores
+with spaces; `label` overrides provide other display names, and `searchable` matches both.
+Selection does not change the application's time zone or calculate offsets, clocks or daylight
+saving transitions. Catalog types and `getTimeZoneCodes()` are documented in the
+[catalog helper reference](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/forms.md#country-time-zone-and-unit-catalog-helpers).
+
+**Field API:** `label`, `hint`, `errorText` (`error-text`), `placeholder`, `accessibleLabel`
+(`aria-label`), `name`, `form`, `value`, `defaultValue`, `required`, `disabled`, `customError`
+(`custom-error`), `size`, `clearable`, `searchable`, `topLayer` (`top-layer`),
+`positioningStrategy` (`positioning-strategy`), `autocomplete`, `inputMode` (`inputmode`),
+`enterKeyHint` (`enterkeyhint`), `spellcheck`, `autocapitalize`, `autocorrect`, and readonly `input`.
+Defaults and form/editing methods follow the
+[shared contract](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/components/lr-country-picker.md), including
+`getForm()`, `checkValidity()`, `reportValidity()`, `setCustomValidity(message)` and
+`resetValidity()` for the owning form and consumer validation messages.
+
+**Events:** `input`, `lr-input`, `change`, `lr-change`, `focus`, `blur`, `lr-invalid`.
+**Slots:** `label`, `hint`, `error`.
+**CSS parts:** `form-control`, `form-control-label`, `hint`, `error`, `select-trigger`,
+`select-display-input`, `select-listbox`, `select-option`, `select-option-sub`, `select-group-label`,
+`select-clear-button`.
+
+```html
+<script type="module">
+  import '@aceshooting/lyra-ui/components/lr-time-zone-picker.js';
+</script>
+<lr-time-zone-picker name="zone" label="Time zone" value="UTC" searchable></lr-time-zone-picker>
+```

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

@@ -0,0 +1,54 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-unit-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/lr-unit-picker.js';` (stable tag alias; registers the tag)
+- **Class** `LyraUnitPicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/unit-picker/unit-picker.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Status** `experimental` since `25.5.0` — see the maturity and deprecation policy in `llms/shared.md`
+- **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [forms](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/forms.md)
+- **Deprecations** none
+- **Optional peers** none
+- **Themeable via** 11 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-unit-picker`
+
+A form-associated measurement-unit selector. Import
+`@aceshooting/lyra-ui/components/lr-unit-picker.js`. It follows the
+[shared field contract](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/components/lr-country-picker.md),
+with `.units` accepting
+`LyraUnitCatalog = readonly string[] | readonly LyraUnitEntry[]`.
+The default catalog contains the 45 standard ECMA-402 simple units. `value=''` selects nothing;
+identifiers are trimmed and case-sensitive, limited to 256 characters. Caller catalogs may include
+custom or compound units. `Intl.NumberFormat` resolves localized singular names and short symbols;
+unsupported identifiers fall back to their code. Literal `label` and `symbol` overrides, including
+empty strings, take precedence. `searchable` matches identifiers, localized/literal names and
+symbols. Selection edits no amount and performs no unit conversion. Catalog types and name
+resolution are documented in the
+[catalog helper reference](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/forms.md#country-time-zone-and-unit-catalog-helpers).
+
+**Field API:** `label`, `hint`, `errorText` (`error-text`), `placeholder`, `accessibleLabel`
+(`aria-label`), `name`, `form`, `value`, `defaultValue`, `required`, `disabled`, `customError`
+(`custom-error`), `size`, `clearable`, `searchable`, `topLayer` (`top-layer`),
+`positioningStrategy` (`positioning-strategy`), `autocomplete`, `inputMode` (`inputmode`),
+`enterKeyHint` (`enterkeyhint`), `spellcheck`, `autocapitalize`, `autocorrect`, and readonly `input`.
+Defaults and form/editing methods follow the
+[shared contract](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/components/lr-country-picker.md), including
+`getForm()`, `checkValidity()`, `reportValidity()`, `setCustomValidity(message)` and
+`resetValidity()` for the owning form and consumer validation messages.
+
+**Events:** `input`, `lr-input`, `change`, `lr-change`, `focus`, `blur`, `lr-invalid`.
+**Slots:** `label`, `hint`, `error`.
+**CSS parts:** `form-control`, `form-control-label`, `hint`, `error`, `select-trigger`,
+`select-display-input`, `select-listbox`, `select-option`, `select-option-sub`, `select-group-label`,
+`select-clear-button`.
+
+```html
+<script type="module">
+  import '@aceshooting/lyra-ui/components/lr-unit-picker.js';
+</script>
+<lr-unit-picker name="unit" label="Measurement unit" value="meter" searchable></lr-unit-picker>
+```

package/llms/index.md

@@ -2,7 +2,7 @@
 
 # Component index
 
-303 custom elements, grouped by the source family they live in.
+307 custom elements, grouped by the source family they live in.
 
 **Reading one component.** Its reference file path is derived from the tag — no search needed:
 `llms/components/<tag>.md` (e.g. `llms/components/lr-table.md`): import path, optional peers,
@@ -30,7 +30,7 @@ and testing and utilities (`llms/shared/testing-and-utilities.md`). The combined
 compatibility guide remains at `llms/shared.md`. Design tokens: `llms/tokens.md`.
 Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.md`.
 
-## Form controls & inputs — `components/forms/` (31)
+## Form controls & inputs — `components/forms/` (35)
 
 - `lr-combobox` · lr-combobox.js · `stable` since `4.0.0` — a filterable single/multi select that combines a text input with a listbox.
 - `lr-option` · lr-option.js · `stable` since `4.0.0` — a selectable option for `<lr-combobox>` and `<lr-select>`.
@@ -63,6 +63,10 @@ Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.m
 - `lr-locale-picker` · lr-locale-picker.js · `stable` since `6.0.0` — a closed-list locale switcher over the library's own locale registry.
 - `lr-toggle` · lr-toggle.js · `experimental` since `21.0.0` — a two-state button that owns its `pressed` state.
 - `lr-toggle-group` · lr-toggle-group.js · `experimental` since `21.0.0` — a set of `<lr-toggle>` children behind one tab stop.
+- `lr-currency-picker` · lr-currency-picker.js · `experimental` since `25.5.0` — a form-associated currency-code selector.
+- `lr-country-picker` · lr-country-picker.js · `experimental` since `25.5.0` — a form-associated country and territory selector.
+- `lr-time-zone-picker` · lr-time-zone-picker.js · `experimental` since `25.5.0` — a form-associated time-zone identifier selector.
+- `lr-unit-picker` · lr-unit-picker.js · `experimental` since `25.5.0` — a form-associated measurement-unit identifier selector.
 
 ## Data display, dashboards & flow canvas — `components/data/` (26)
 

package/llms/peers.md

@@ -52,14 +52,14 @@ for the page.
 | `emoji-picker-element-data` | `^1.8.0` | `lr-emoji-picker` |
 | `epubjs` | `^0.3.93` | `lr-ebook-viewer` |
 | `ical.js` | `^2.2.1` | `lr-calendar-viewer` |
-| `katex` | `^0.18.4` | `lr-agent-workspace`, `lr-dashboard-grid`, `lr-eval-run`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts`, `lr-notebook-viewer`, `lr-rag-answer`, `lr-streaming-text`, `lr-streaming-text-core`, `lr-widget-renderer` |
+| `katex` | `^0.18.4 \|\| ^0.19.0` | `lr-agent-workspace`, `lr-dashboard-grid`, `lr-eval-run`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts`, `lr-notebook-viewer`, `lr-rag-answer`, `lr-streaming-text`, `lr-streaming-text-core`, `lr-widget-renderer` |
 | `libphonenumber-js` | `>=1.11.0 <2` | _(not referenced by any component)_ |
 | `mammoth` | `^1.12.1` | `lr-docx-viewer` |
 | `maplibre-gl` | `>=5 <7` | `lr-geojson-viewer`, `lr-map` |
 | `marked` | `^18.0.11` | `lr-agent-workspace`, `lr-dashboard-grid`, `lr-eval-run`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts`, `lr-notebook-viewer`, `lr-rag-answer`, `lr-streaming-text`, `lr-streaming-text-core`, `lr-widget-renderer` |
 | `papaparse` | `^5.7.0` | `lr-csv-viewer`, `lr-dataset-viewer` |
 | `pdfjs-dist` | `^6.3.289` | `lr-pdf-viewer` |
-| `postal-mime` | `^3.0.1 || ^4.0.0` | `lr-email-viewer` |
+| `postal-mime` | `^3.0.1 \|\| ^4.0.0` | `lr-email-viewer` |
 | `qrcode` | `^1.5.4` | `lr-qr-code` |
 | `react` | `>=19 <20` | type-only `@aceshooting/lyra-ui/custom-elements-jsx` entry (no runtime import) |
 | `shiki` | `^4.4.3` | `lr-agent-workspace`, `lr-change-review`, `lr-code-block`, `lr-code-block-core`, `lr-dashboard-grid`, `lr-diff-view`, `lr-document-compare`, `lr-eval-result`, `lr-eval-run`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts`, `lr-notebook-viewer`, `lr-rag-answer`, `lr-streaming-text`, `lr-streaming-text-core`, `lr-widget-renderer` |

package/llms/shared/events-and-types.md

@@ -584,7 +584,9 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-control-group': LyraControlGroupReactProps;
   'lr-conversation-item': LyraConversationItemReactProps;
   'lr-copy-button': LyraCopyButtonReactProps;
+  'lr-country-picker': LyraCountryPickerReactProps;
   'lr-csv-viewer': LyraCsvViewerReactProps;
+  'lr-currency-picker': LyraCurrencyPickerReactProps;
   'lr-dashboard-grid': LyraDashboardGridReactProps;
   'lr-data-grid': LyraDataGridReactProps;
   'lr-dataset-viewer': LyraDatasetViewerReactProps;
@@ -781,6 +783,7 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-thread-list': LyraThreadListReactProps;
   'lr-time-input': LyraTimeInputReactProps;
   'lr-time-range': LyraTimeRangeReactProps;
+  'lr-time-zone-picker': LyraTimeZonePickerReactProps;
   'lr-timeline': LyraTimelineReactProps;
   'lr-timeline-item': LyraTimelineItemReactProps;
   'lr-toast': LyraToastReactProps;
@@ -803,6 +806,7 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-tree': LyraTreeReactProps;
   'lr-tree-item': LyraTreeItemReactProps;
   'lr-typing-indicator': LyraTypingIndicatorReactProps;
+  'lr-unit-picker': LyraUnitPickerReactProps;
   'lr-usage-badge': LyraUsageBadgeReactProps;
   'lr-video': LyraVideoReactProps;
   'lr-video-playlist': LyraVideoPlaylistReactProps;
@@ -1012,7 +1016,9 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-control-group': LyraComponentTypeMap['lr-control-group']['element'];
   'lr-conversation-item': LyraComponentTypeMap['lr-conversation-item']['element'];
   'lr-copy-button': LyraComponentTypeMap['lr-copy-button']['element'];
+  'lr-country-picker': LyraComponentTypeMap['lr-country-picker']['element'];
   'lr-csv-viewer': LyraComponentTypeMap['lr-csv-viewer']['element'];
+  'lr-currency-picker': LyraComponentTypeMap['lr-currency-picker']['element'];
   'lr-dashboard-grid': LyraComponentTypeMap['lr-dashboard-grid']['element'];
   'lr-data-grid': LyraComponentTypeMap['lr-data-grid']['element'];
   'lr-dataset-viewer': LyraComponentTypeMap['lr-dataset-viewer']['element'];
@@ -1209,6 +1215,7 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-thread-list': LyraComponentTypeMap['lr-thread-list']['element'];
   'lr-time-input': LyraComponentTypeMap['lr-time-input']['element'];
   'lr-time-range': LyraComponentTypeMap['lr-time-range']['element'];
+  'lr-time-zone-picker': LyraComponentTypeMap['lr-time-zone-picker']['element'];
   'lr-timeline': LyraComponentTypeMap['lr-timeline']['element'];
   'lr-timeline-item': LyraComponentTypeMap['lr-timeline-item']['element'];
   'lr-toast': LyraComponentTypeMap['lr-toast']['element'];
@@ -1231,6 +1238,7 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-tree': LyraComponentTypeMap['lr-tree']['element'];
   'lr-tree-item': LyraComponentTypeMap['lr-tree-item']['element'];
   'lr-typing-indicator': LyraComponentTypeMap['lr-typing-indicator']['element'];
+  'lr-unit-picker': LyraComponentTypeMap['lr-unit-picker']['element'];
   'lr-usage-badge': LyraComponentTypeMap['lr-usage-badge']['element'];
   'lr-video': LyraComponentTypeMap['lr-video']['element'];
   'lr-video-playlist': LyraComponentTypeMap['lr-video-playlist']['element'];
@@ -1317,7 +1325,9 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-control-group': LyraControlGroupSvelteProps;
   'lr-conversation-item': LyraConversationItemSvelteProps;
   'lr-copy-button': LyraCopyButtonSvelteProps;
+  'lr-country-picker': LyraCountryPickerSvelteProps;
   'lr-csv-viewer': LyraCsvViewerSvelteProps;
+  'lr-currency-picker': LyraCurrencyPickerSvelteProps;
   'lr-dashboard-grid': LyraDashboardGridSvelteProps;
   'lr-data-grid': LyraDataGridSvelteProps;
   'lr-dataset-viewer': LyraDatasetViewerSvelteProps;
@@ -1514,6 +1524,7 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-thread-list': LyraThreadListSvelteProps;
   'lr-time-input': LyraTimeInputSvelteProps;
   'lr-time-range': LyraTimeRangeSvelteProps;
+  'lr-time-zone-picker': LyraTimeZonePickerSvelteProps;
   'lr-timeline': LyraTimelineSvelteProps;
   'lr-timeline-item': LyraTimelineItemSvelteProps;
   'lr-toast': LyraToastSvelteProps;
@@ -1536,6 +1547,7 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-tree': LyraTreeSvelteProps;
   'lr-tree-item': LyraTreeItemSvelteProps;
   'lr-typing-indicator': LyraTypingIndicatorSvelteProps;
+  'lr-unit-picker': LyraUnitPickerSvelteProps;
   'lr-usage-badge': LyraUsageBadgeSvelteProps;
   'lr-video': LyraVideoSvelteProps;
   'lr-video-playlist': LyraVideoPlaylistSvelteProps;
@@ -1734,7 +1746,9 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-control-group': LyraControlGroupVueProps;
   'lr-conversation-item': LyraConversationItemVueProps;
   'lr-copy-button': LyraCopyButtonVueProps;
+  'lr-country-picker': LyraCountryPickerVueProps;
   'lr-csv-viewer': LyraCsvViewerVueProps;
+  'lr-currency-picker': LyraCurrencyPickerVueProps;
   'lr-dashboard-grid': LyraDashboardGridVueProps;
   'lr-data-grid': LyraDataGridVueProps;
   'lr-dataset-viewer': LyraDatasetViewerVueProps;
@@ -1931,6 +1945,7 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-thread-list': LyraThreadListVueProps;
   'lr-time-input': LyraTimeInputVueProps;
   'lr-time-range': LyraTimeRangeVueProps;
+  'lr-time-zone-picker': LyraTimeZonePickerVueProps;
   'lr-timeline': LyraTimelineVueProps;
   'lr-timeline-item': LyraTimelineItemVueProps;
   'lr-toast': LyraToastVueProps;
@@ -1953,6 +1968,7 @@ These named interfaces and helper signatures are available to typed integrations
   'lr-tree': LyraTreeVueProps;
   'lr-tree-item': LyraTreeItemVueProps;
   'lr-typing-indicator': LyraTypingIndicatorVueProps;
+  'lr-unit-picker': LyraUnitPickerVueProps;
   'lr-usage-badge': LyraUsageBadgeVueProps;
   'lr-video': LyraVideoVueProps;
   'lr-video-playlist': LyraVideoPlaylistVueProps;

package/llms/shared/imports-and-registration.md

@@ -157,7 +157,7 @@ The entry points, then:
   but it is not an exhaustive promise that every component-owned type or future export is present.
   Prefer the owning component entry in application code, both for the smallest bundle and the
   complete contract of that component.
-- **`all.js` compatibility entry.** `import '@aceshooting/lyra-ui/all.js';` registers the 288
+- **`all.js` compatibility entry.** `import '@aceshooting/lyra-ui/all.js';` registers the 292
   root-included tags — everything **except** the 15 inventory-designated optional-peer-family tags:
   `lr-chart` and its 8 typed subclasses (`lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`,
   `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`,

package/llms/shared/styles-and-tokens.md

@@ -1135,12 +1135,18 @@ The public `--lr-theme-surface-opacity` input accepts 0 through 1. Lower opacity
 of the backdrop; the default foreground qualification covers 70%, while a custom lower setting
 cannot guarantee contrast against every backdrop. Solid and accessibility preferences retain
 opaque fills regardless of this input.
-Quiet text, necessary control edges, focus indicators and transparent actions gain a local
+Necessary control borders use the effective painted opacity: their glass adjustment grows as
+transparency increases and disappears at 100% opacity. Ordinary and strong borders share this
+adjustment; decorative borders and explicit component border overrides keep their own tokens.
+Quiet text, focus indicators and transparent actions retain their separate local
 contrast-qualified foreground; opaque accent fills retain their own on-colours. Supported chrome
 includes app rails, navigation menus, menubars, menus and their context-menu composition, popovers,
 selection toolbars, toast items and the owned playback-rate toolbar of `lr-av-player`. Nested glass
 chrome is opaque, preventing repeated blur. Independently promoted menus and modal panels start a
-new material root. Content cards and editing fields remain opaque.
+new material root. Surface-colored outlined card and disclosure interiors let nested Lyra
+controls use their solid border colors while preserving the enclosing edge against glass.
+Filled accent interiors retain qualification. Native descendants retain inherited public color
+aliases. Custom translucent content fills require the author to choose suitable control borders.
 A design panel can offer a Glass opacity range from 0–100%, shown when the selected surface is
 Glass. Start and reset it at 70%; convert the displayed percentage to the public token's 0–1 range.
 Apply this CSS input independently of look overrides: `setLyraStyle()` does not accept surface

package/llms/shared/testing-and-utilities.md

@@ -397,6 +397,8 @@ arrowPadding?: number; hoverBridge?: HTMLElement; onPlaced?: (result: PlacementR
   `validationMessage`, and `willValidate`; `setFormValue(next)`; `getForm()`; `checkValidity()`;
   `reportValidity()`; `setCustomValidity(message)`; `resetValidity()`; `formResetCallback()`; and
   `formStateRestoreCallback(state, reason)`.
+  Writing `null` to `defaultValue` removes its markup value and resets the default to the adapter's
+  empty value; reading it still returns `TValue`. This does not overwrite a dirty live value.
   The exact callable signatures are `attachInternalsSafely(host: HTMLElement): ElementInternals`,
   `createFallbackInternals(): ElementInternals`, `createStringArrayFormDataState(name: string,
 values: readonly string[]): FormData`, `readStringArrayFormDataState(state: string | File |
@@ -409,7 +411,8 @@ toFormValue(value: TValue): FormSubmissionValue; toFormState?(value: TValue):
 FormSubmissionValue; isEmpty?(value: TValue): boolean; fromAttribute?(attribute: string): TValue;
 toAttribute?(value: TValue): string | null; fromFormState?(state: FormSubmissionValue): TValue }`
   and `FormAssociatedInterface<TValue> { internals: ElementInternals; get name(): string; set
-name(next: string | null); value: TValue; defaultValue: TValue; customError: string | null;
+name(next: string | null); value: TValue; get defaultValue(): TValue;
+set defaultValue(next: TValue | null); customError: string | null;
 disabled: boolean; required: boolean; readonly effectiveDisabled: boolean; get form():
 HTMLFormElement | null; set form(owner: FormOwnerValue); readonly labels: NodeList; readonly
 validity: ValidityState; readonly validationMessage: string; readonly willValidate: boolean;