@aceshooting/lyra-ui 25.3.0 → 25.4.0

package/llms/components/lr-avatar.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [media](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/media.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 4 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 4 parts, 7 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`
 
 ---
@@ -88,9 +88,14 @@ initials track the circle instead of staying one fixed size across every tier. `
 (default `var(--lr-radius-pill)`) — corner radius of the container. Its private default follows
 `shape` (`var(--lr-radius-pill)` for `circle`, `var(--lr-radius)` for `rounded`, `0` for `square`);
 an inherited or direct public value overrides uniformly across every shape, the same way
-`--lr-avatar-size` spans every size tier. Every public value
+`--lr-avatar-size` spans every size tier. `--lr-avatar-border` (default `none`) — border shorthand
+on `base`, applying to image, glyph and initials avatars in every shape. Border-box sizing keeps
+the border inside the outer diameter set by `--size`, `--lr-avatar-size` or the size ladder;
+image content fills the remaining inner area. Forced colors preserves the system-color boundary
+instead of the normal token border. Existing `::part(base)` border customization remains supported.
+Every public value
 above can be inherited from an ancestor or set directly on the avatar and remains authoritative
-across size/variant states. Plus shared tokens
+across size/variant states in normal color modes. Plus shared tokens
 `--lr-radius`/`-pill`, `--lr-font-weight-semibold`.
 
 The variant colors are deliberately **not** the library's generic quiet-fill/on-quiet-text pairing:
@@ -103,6 +108,7 @@ variant's quiet tint.
 <lr-avatar initials="JS" variant="brand"></lr-avatar>
 <lr-avatar image="/users/42/photo.jpg" label="Jane Smith" size="large" shape="rounded"></lr-avatar>
 <lr-avatar label="Assistant"><svg slot="icon" viewBox="0 0 24 24"><!-- role glyph --></svg></lr-avatar>
+<lr-avatar initials="JS" style="--lr-avatar-border: var(--lr-border-width-medium) solid var(--lr-color-border)"></lr-avatar>
 
 <!-- Far down a long list: defer the request, fall back to a glyph, and report a broken URL. -->
 <lr-avatar id="lazy-avatar" image="/users/7/photo.jpg" label="Ada Lovelace" loading="lazy">

package/llms/components/lr-bar-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-bubble-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-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
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -233,6 +233,10 @@ structured points retain their y-value formatting.
   value, matching Chart.js's own paired index/value-scale stacking contract.
 - `withoutAnimation: boolean = false` (attribute `without-animation`, reflected) — disables Chart.js
   construction animation; reduced-motion preference also disables it regardless of this value
+- `syncGroup: string = ''` (attribute `sync-group`) — opt-in exact category coordination; see
+  [Synchronized categorical charts](https://github.com/aceshooting/lyra-ui/blob/main/packages/lyra-ui/llms/charts.md#synchronized-categorical-charts). Only effective vertical
+  categorical bar/line configurations participate; other types, horizontal charts and continuous
+  x scales keep this setting inert. Core keeps its native canvas tooltip and existing tooltip tokens.
 - `withoutTooltip: boolean = false` (attribute `without-tooltip`, reflected) — disables the
   Chart.js tooltip plugin for this instance
 - `dataLabels: boolean = false` (attribute `data-labels`) — draws each point's value on the chart via
@@ -432,7 +436,9 @@ notice, so use that escape hatch when the complete data set needs pagination, vi
 another application-owned presentation. Explicit `config.data` is the deliberate full-fidelity
 Chart.js escape hatch and is not rewritten by the simplified-surface sampler.
 
-**CSS parts:** `base`, `plot` (the fixed-height canvas/overlay region), `canvas`, `legend` (the
+**CSS parts:** `base`, `plot` (the fixed-height canvas/overlay region), `canvas`,
+`sync-crosshair` (decorative category line during an admitted synchronized interaction; the native
+canvas tooltip has no CSS part), `legend` (the
 wrapping DOM legend), `legend-item` (a dataset/category visibility button), `legend-item-hidden`
 (added while the dataset/category is hidden), `legend-swatch`,
 `reset-zoom-button`, `description`, `notices` (wrapper for nonfatal feature warnings and
@@ -448,6 +454,9 @@ legend grows the host in normal flow. The `height` property writes only a privat
 public token wins across valid, invalid, and unset `height` updates. Set it on the host or an
 ancestor, not a shadow-tree descendant, since custom properties only cascade downward);
 `--lr-chart-grid-color` (default `var(--lr-color-border-subtle)`),
+`--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-tick-color` (default `var(--lr-color-text-quiet)`), `--lr-chart-legend-color`
 (default `var(--lr-color-text)`), `--lr-chart-tooltip-bg` (default `var(--lr-color-surface)`),
 `--lr-chart-tooltip-color` (default `var(--lr-color-text)`) — each resolved fresh via

package/llms/components/lr-doughnut-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-heatmap.md

@@ -83,9 +83,17 @@ weekdayLabelWidth?: number|'auto'; weekdayLabelText?: (jsWeekday:number)=>string
 - `cellSize: number = 22` (attribute `cell-size` — default `22` in matrix mode, `11` in calendar
   mode when left unset; explicitly setting it now governs both modes' per-cell size alike, and it's
   ignored in either mode when `fitToWidth` is set)
+- `rowHeight?: number` (attribute `row-height`) — independent matrix vertical row pitch in CSS
+  pixels, including its trailing `cellGapY` separator. Unset, removed, `null`, `undefined`, and
+  non-finite values restore square rows from the effective `cellSize`; finite values
+  clamp to the `1`–`4096` range. This bounds numeric outliers; browser canvas limits still apply
+  to the complete grid. `fitToWidth`, `minCellSize`, and `maxCellSize` continue to govern column pitch.
+  Calendar mode ignores it and preserves its existing square geometry. With `accessibleCells`,
+  width and height independently preserve the accessible target floor; dense columns can therefore
+  overflow even when fitting is requested.
 - `cellGapX: number = 1` / `cellGapY: number = 1` (attributes `cell-gap-x` / `cell-gap-y`) —
   trailing horizontal/vertical gaps in CSS pixels. In matrix mode they are subtracted from the
-  square `cellSize` pitch. Negative values clamp to zero, non-finite values use `1`, and oversized
+  horizontal `cellSize` / vertical `rowHeight ?? cellSize` pitch. Negative values clamp to zero, non-finite values use `1`, and oversized
   gaps leave at least one painted pixel. Custom geometry with `accessibleCells` grows the minimum
   pitch and caps gaps to preserve the `--lr-icon-button-size` target floor. In calendar mode they
   are opt-in: only an explicitly set property or attribute replaces the calendar's original `2px`
@@ -374,10 +382,11 @@ otherwise keep private. For the case that motivated it — a frozen header or gu
 matrix — prefer `stickyLabels`, which freezes the band inside the component and needs no mirror at
 all; the getter remains the way to align a *separate* element (a sibling chart, a custom overlay)
 with the grid. `LyraHeatmapMatrixGeometryChangeDetail` contains `padLeft`, `padTop`, and `cellSize`
-(the square pitch), plus optional `cellWidth`, `cellHeight`, and `cellRadius` for custom matrix
+(the horizontal pitch), plus optional `rowHeight` when vertical pitch differs and optional
+`cellWidth`, `cellHeight`, and `cellRadius` for custom matrix
 presentation. When those optional fields are absent, painted width/height are `cellSize - 1` and
 radius is zero. The getter and geometry-change event always share one frozen snapshot, including
-changes to the resolved gaps/radius.
+changes to the resolved row pitch, gaps, and radius. Use `rowHeight ?? cellSize` to position rows.
 
 `calendarGeometry: Readonly<LyraHeatmapCalendarGeometry> | undefined` (read-only; assignment is
 ignored) is the calendar-mode counterpart: the frozen snapshot of the last calendar draw with
@@ -394,6 +403,10 @@ selection, `lr-cell-activate`, and `cellText` keep working with no matrix rebuil
 
 For a fluid day/hour matrix, keep all 24 hour strings in `data.colLabels` and use
 `fit-to-width cell-gap-x="1" cell-gap-y="2" cell-radius="2" col-label-interval="3"`.
+For a dense matrix with 144 time columns and 20 rows, use `fit-to-width row-height="28"` to fit
+columns while keeping readable rows. Row height includes the trailing separator and stays `28px`
+when the host resizes. The existing `minCellSize` floor and accessible target sizes can require
+horizontal overflow in a narrow allocation; choose `sticky-labels` when you want a scrollport.
 For a single fluid square cell, use `fit-to-width` with equal horizontal and vertical gaps.
 
 **Events:** `lr-selection-change` (not cancelable; frozen readonly `HeatmapSelectionChangeDetail { selectedCells, source }` proposal in multiple mode, with `source: 'pointer' | 'keyboard' | 'row' | 'column'`; accept it by assigning `selectedCells`). `lr-cell-activate` (fired on click, or Enter/Space on the keyboard-focused cell —

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

@@ -222,11 +222,11 @@ A compact header can set `trigger-display="flag"` and
 Import `@aceshooting/lyra-ui/components/media/flag/flag-peer.js` to register the optional flag
 resolver. Menu labels stay visible; a per-entry `country` override also reaches the compact trigger.
 
-Option rows keep at least the medium control height (`--lr-form-control-height-m`, normally
-`2.25rem`), including `option-display="label"` and a small flag trigger. Larger control tiers,
-coarse-pointer control heights, larger text, and the optional tag line can grow the rows beyond
-that floor. The listbox keeps its scrolling height limit; `size` does not make language rows
-smaller than the medium floor.
+Option rows keep at least `--lr-size-3rem` (normally `3rem`, or 48px at a 16px root size),
+including `option-display="label"`, compact density, and a small flag trigger. Block padding is
+`--lr-space-s`; long native labels wrap and rows grow with the text. Larger medium/current control
+height tokens and the optional tag line can also grow rows beyond that floor. The listbox keeps
+its scrolling height limit; `size` controls the trigger rather than shrinking language choices.
 
 ```html
 <lr-locale-picker label="Language"></lr-locale-picker>

package/llms/components/lr-menu.md

@@ -265,6 +265,10 @@ has `aria-haspopup="menu"`, explicit `aria-expanded="true|false"`, the transient
 `submenu-open` state, and a logical-direction chevron. Its submenu is named from the parent's
 accessible label unless the submenu supplies its own `aria-label` or non-default `label`.
 
+Submenus prefer the inline end of their parent and flip to the other side when necessary. When
+neither side has enough space, they can open above or below the parent, keeping their labels
+readable within the viewport instead of shrinking to the remaining strip beside a wide menu.
+
 The into-branch and back-out arrow keys swap under RTL. Enter/Space and the into key open and focus
 the first child; the back-out key and Escape close only the innermost branch and return focus to its
 parent row. Pointer hover uses an intent delay, outside pointer dismissal closes the branch, and at

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/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/styles-and-tokens.md

@@ -505,7 +505,8 @@ page you are on — that is what keeps two overlapping surfaces reading in the c
 
 ### Cascade layers
 
-`theme.css` declares its layer order up front, then puts all of its own tokens in `lr-theme`:
+`theme.css` declares its layer order up front, with base inputs in `lr-theme` and built-in profile
+rules in the `lr-theme-preset` sublayers:
 
 ```css
 @layer lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides;
@@ -513,9 +514,10 @@ page you are on — that is what keeps two overlapping surfaces reading in the c
 
 - **`lr-base`** — contains the explicitly scoped native-element rules only when the optional
   `native.css` asset is imported.
-- **`lr-theme`** — where every `--lr-theme-*` token `theme.css` ships is declared.
-- **`lr-theme-preset`** — the compatibility layer name that holds optional look stylesheets, such as
-  [`looks/shadcn.css`](#the-shadcn-look--looksshadcncss). Empty unless one is imported.
+- **`lr-theme`** — contains the base theme inputs and token resolvers.
+- **`lr-theme-preset`** — the compatibility layer name for look, density, surface, accent and mode
+  rules. `theme.css` already supplies the built-in Shadcn, Glass and Emerald profile here; optional
+  look stylesheets add their own rules to the same sublayers.
 - **`lr-utilities`** — contains exact `lr-*` classes only when the optional `utilities.css` asset is
   imported.
 - **`lr-overrides`** — named so an application can opt its own rules into a defined position
@@ -574,17 +576,25 @@ reason.
 
 ### The shadcn look — looks/shadcn.css
 
-Import the base resolver and the optional look stylesheet, then select the look on the scope that should receive it:
+`theme.css` already installs Shadcn as the built-in default and supports explicit
+`data-lr-look="shadcn"` scopes. Import it once; the separate Shadcn sheet is unnecessary for this
+profile:
 
 ~~~ts
 import "@aceshooting/lyra-ui/theme.css";
-import "@aceshooting/lyra-ui/looks/shadcn.css";
 import { setLyraStyle } from "@aceshooting/lyra-ui/theme.js";
 
 setLyraStyle({ look: "shadcn" });
 ~~~
 
-The stylesheet declares values only under data-lr-look="shadcn". It composes with the independent mode, surface, density, and accent axes. For a local region, set data-lr-look="shadcn" on that region or use applyLyraStyleScope(). A nested data-lr-mode="dark" still changes mode without changing the look.
+Shadcn composes with the independent mode, surface, density and accent axes. For a local region,
+set data-lr-look="shadcn" on that region or use applyLyraStyleScope(). A nested data-lr-mode="dark"
+still changes mode without changing the look.
+
+The separate `looks/shadcn.css` sheet remains compatible. Besides the same scoped look values, it
+adds legacy `.light` and `.dark` mode aliases inside a Shadcn scope. Import that sheet only when
+those aliases are needed; prefer `data-lr-mode`, `data-lr-theme` or `.lr-light`/`.lr-dark` for new
+code. Explicit Lyra mode selectors on the same element take precedence over the compatibility aliases.
 
 The look sets --lr-theme-* inputs, so no component API changes. Its rules use Lyra's named cascade layers: unlayered application rules still win, and runtime accent ramps still take precedence over look values for the roles they paint. Import order between theme.css and looks/shadcn.css does not change the layer order.
 
@@ -602,7 +612,9 @@ Override the look through an unlayered application rule or the lr-overrides laye
 }
 ~~~
 
-The former global themes/shadcn.css facade and its data-lr-theme-preset behavior have been removed. Use looks/shadcn.css and the data-lr-look axis for new styling.
+The former global themes/shadcn.css facade and its data-lr-theme-preset behavior have been removed.
+Use theme.css and the data-lr-look axis for new styling; looks/shadcn.css is needed only for the
+compatibility aliases above.
 
 ### Where an override actually reaches
 
@@ -845,7 +857,7 @@ bytes; build plugins must not prepend the bootstrap ahead of it.
 
 For a strict CSP that disallows inline scripts, the package also publishes theme-bootstrap.js, a classic script asset with identical bytes. Load it synchronously after the charset declaration and before stylesheets. Its optional data-lr-theme-storage-key and data-lr-theme-attributes attributes select an application-owned storage key or mode-attribute list; values are validated and fall back to defaults when invalid.
 
-**Migrating the retired theme facade.** New code uses setLyraStyle() and getLyraStyle(). Map old auto mode to system, an old surface reference color to accentBackground, and an old token map to overrides; review custom CSS colors that share a gemstone name before choosing a named accent. Replace preset definitions with a LyraLook plus explicit style choices. Replace selectors for data-lr-theme-preset with the actual axis they need, such as data-lr-look="shadcn". Import looks/shadcn.css in place of the removed fixed themes/shadcn.css facade and select the look with setLyraStyle({ look: "shadcn" }) or a scoped data-lr-look attribute. Listen for lr-style-change and read event.detail.style and event.detail.changed; the old theme and preset events are no longer emitted. For the complete project-by-project sequence, see [Upgrading from v23 to v24](v23-to-v24-migration.md).
+**Migrating the retired theme facade.** New code uses setLyraStyle() and getLyraStyle(). Map old auto mode to system, an old surface reference color to accentBackground, and an old token map to overrides; review custom CSS colors that share a gemstone name before choosing a named accent. Replace preset definitions with a LyraLook plus explicit style choices. Replace selectors for data-lr-theme-preset with the actual axis they need, such as data-lr-look="shadcn". Import theme.css in place of the removed fixed themes/shadcn.css facade and select the look with setLyraStyle({ look: "shadcn" }) or a scoped data-lr-look attribute. Listen for lr-style-change and read event.detail.style and event.detail.changed; the old theme and preset events are no longer emitted. For the complete project-by-project sequence, see [Upgrading from v23 to v24](v23-to-v24-migration.md).
 
 Historical v1 stored records remain readable by the runtime and bootstrap. The removed JavaScript functions, preset subpaths, preset event, root marker, and fixed stylesheet are not available in the current API.
 
@@ -897,10 +909,8 @@ mode and accent; the axes compose independently.
 
 ```js
 import '@aceshooting/lyra-ui/theme.css';
-import '@aceshooting/lyra-ui/looks/shadcn.css';
 import '@aceshooting/lyra-ui/looks/material.css';
 import '@aceshooting/lyra-ui/density.css';
-import '@aceshooting/lyra-ui/surfaces/glass.css';
 import '@aceshooting/lyra-ui/accents.css';
 import { setLyraStyle, resetLyraStyle, applyLyraStyleScope } from '@aceshooting/lyra-ui/theme.js';
 
@@ -918,7 +928,8 @@ inherit), without persistence or global events; clearing preserves later author
 reports requested axes and resolved mode.
 
 Set `data-lr-look`, `data-lr-surface`, `data-lr-density`, `data-lr-mode` and `data-lr-accent`
-directly if needed. Stylesheet look ids need their sheet; arbitrary ids neither load nor register.
+directly if needed. Shadcn and Lyra are included in `theme.css`; other stylesheet look ids need
+their optional sheet. Arbitrary ids neither load nor register.
 `defineLyraLook({ id, tokens })` defines a validated immutable runtime look;
 `lyraLookCss()` from `theme/look-css.js` creates CSS without DOM access. In app-owned shadow roots
 with local boundaries, install `theme.css` and selected sheets; selectors stop at roots, inheritance
@@ -1124,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