@aceshooting/lyra-ui 21.0.0 → 21.1.0

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

@@ -9,91 +9,6 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **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
-- **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart` (same section below)
+- **Themeable via** 16 parts, 37 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`
-
----
-
-## Typed subclasses: `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`
-
-Each is `LyraChart` with a named default `type` — respectively `line`, `bar`, `pie`, `doughnut`,
-`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.
-
-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.**
-
-**Properties:** `description`, `grid`, `axes`, `compact`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `hiddenDatums`, `legendMode` (`legend-mode`), `legendDisplay` (`legend-display`),
-`max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
-`stacked`, `stackedAxes`, `withoutAnimation` (`without-animation`),
-`withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
-`yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`,
-`tooltipTitleFormatter`, `tooltipFooterFormatter`, `area`, `zoom`,
-`height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
-(`data-labels`), `stackTotals` (`stack-totals`), `config`, `showDataTable`
-(`show-data-table`), `dataTableToggle` (`data-table-toggle`), `chartArea` (readonly), and `chart`.
-`type` differs only in its initial value.
-
-**Methods:** `appendData(label, values, maxPoints?)`, `exportData('csv' | 'png')`, `renderChart()`, `resetZoom()`,
-`refreshTheme()`.
-
-**Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-datum-activate`, `lr-point-click` (`detail: { datasetIndex,
-index, label, value }`), `lr-legend-visibility-change-request` (cancelable), and
-`lr-legend-visibility-change` (commit; both legend events carry `datasetIndex`, `visible`, and the
-complete `hiddenDatasets` snapshot). `lr-before-legend-visibility-change` is a **deprecated** alias
-of `lr-legend-visibility-change-request` (removal not before 21.0.0).
-Radial category legends additionally emit `lr-datum-visibility-change-request` (cancelable) and
-`lr-datum-visibility-change`, carrying `index`, `visible` and the frozen `hiddenDatums` snapshot.
-`lr-before-datum-visibility-change` is a **deprecated** alias of `lr-datum-visibility-change-request`
-(removal not before 21.0.0).
-
-**Slots:** default JSON configuration script, `data-table`, `center`.
-
-**CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
-`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-tick-color`, `--lr-chart-tick-font-size`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
-`--lr-chart-tooltip-text`, `--lr-chart-legend-item-hover-bg`,
-`--lr-chart-legend-item-active-bg`, `--lr-chart-data-table-button-hover-bg`,
-`--lr-chart-data-table-button-active-bg`, `--lr-chart-data-table-toggle-hover-bg`,
-`--lr-chart-data-table-toggle-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
-`--lr-chart-reset-zoom-button-active-bg`, `--lr-chart-canvas-hover-outline-width`, and
-`--lr-chart-canvas-hover-outline-color`, `--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — all inherited from `LyraChart`, identical in meaning and default (see
-`lr-chart` above); each of the eight variants below reads the same set, so one rule retunes them
-together. The mirrored hooks are `--border-color-1`,
-`--border-color-2`, `--border-color-3`, `--border-color-4`, `--border-color-5`,
-`--border-color-6`, `--fill-color-1`, `--fill-color-2`, `--fill-color-3`, `--fill-color-4`,
-`--fill-color-5`, `--fill-color-6`, `--border-radius`, `--border-width`, `--grid-border-width`,
-`--grid-color`, `--line-border-width`, and `--point-radius`, also identical to the core chart.
-
-**Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
-`zoom` is set, `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set, and
-`chartjs-plugin-annotation` only once `annotations` contains a usable entry.
-
-```html
-<lr-bar-chart></lr-bar-chart>
-<lr-pie-chart></lr-pie-chart>
-<script>
-  document.querySelector('lr-bar-chart').labels = ['A', 'B'];
-  document.querySelector('lr-bar-chart').datasets = [{ label: 'Count', data: [4, 9] }];
-
-  document.querySelector('lr-pie-chart').labels = ['A', 'B', 'C'];
-  document.querySelector('lr-pie-chart').datasets = [{ label: 'Share', data: [30, 45, 25], color: ['#2563eb', '#16a34a', '#dc2626'] }];
-</script>
-```
-
-**Known gotchas (in addition to the core `lr-chart` list in `llms/components/lr-chart.md`):**
-- Changing `type` after construction may rebuild the underlying Chart.js instance; any active zoom
-  state is reset and announced before the new type renders.
-- `lr-bubble-chart` consumes the exported `LyraChartPoint` shape directly. Set `x`/`y`, optional `r`
-  for bubble radius, and optional `label` for the point-level accessible/event/export label; no
-  runtime cast is needed.
-
----

package/llms/components/lr-selection-toolbar.md

@@ -64,8 +64,10 @@ movement starts from the action that received the event rather than stale contro
 private so controlled rect updates cannot be silently overridden by stale authored CSS.
 **Themeable custom properties:** `--lr-selection-toolbar-placement-gap` (default
 `var(--lr-space-s)`) is the non-negative distance from the selection and from viewport edges while
-the toolbar avoids collisions. It accepts unitless pixel values and `px`, `rem`, and `em` values; unsupported
-values fall back to the default and negative values clamp to `0`. Collision math uses the active
+the toolbar avoids collisions. It accepts unitless pixel values, `px`, `rem`, and `em` values, and
+CSS length math (`calc()`, `min()`, `max()`, `clamp()`) resolved in its live theme scope. Percentages
+have no placement-gap basis. Invalid values fall back to the default and negative values clamp to
+`0`. Collision math uses the active
 `visualViewport` bounds and offsets when available, including after visual-viewport changes.
 
 The toolbar is a floating surface and paints from the **shared overlay-surface family** (16.0.0):

package/llms/components/lr-source-card.md

@@ -9,190 +9,6 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 5 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
-- **Documented with** `lr-source-list` (same section below)
+- **Themeable via** 5 parts, 3 custom properties — see `lr-source-list.md`
+- **Documented with** `lr-source-list`: see [lr-source-list.md](./lr-source-list.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
-
----
-
-## `lr-source-list` / `lr-source-card`
-
-A collapsible "Sources" panel for one chat message (`lr-source-list`) that groups a set of
-`lr-source-card` entries. First-party invention (no Web Awesome equivalent). Cards are meant to be
-direct light-DOM children of the list (plain composition — no `.items` array prop, the same shape
-`<lr-multi-split>`'s panels take), though `lr-source-card` renders and functions fine standalone.
-
-### `lr-source-list`
-
-**Properties:**
-
-- `expanded: boolean = false` (reflected) — whether the card list is currently shown. Starts
-  collapsed by default so a message's sources don't eat vertical space until asked for.
-- `label?: string` — header text used when `label-plural` isn't set, e.g. `"Sources"`.
-- `labelPlural: string = ''` (attribute `label-plural`) — fully consumer-built, already-pluralized
-  header summary, e.g. `"3 sources"` or `"1 source"`; this component never counts or pluralizes on
-  its own. Takes precedence over `label` when both are set. If neither is set, the header falls back
-  to the localized `sourceListDefaultLabel` string (English default: `"Sources"`).
-- `compact: boolean = false` (reflected) — tighter header and list padding/gap, for a panel
-  rendered repeatedly down a message transcript — same convention as this list's own slotted
-  `lr-source-card` children's `compact`. Purely a density knob: the outer border and surface stay,
-  so pair it with `frame="plain"` to remove card chrome.
-- `frame: LyraFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
-  vocabulary (`'card' | 'plain'`). `'card'` (the default) keeps the bordered, filled outer
-  container. `'plain'` removes that outer border, background, and corner radius so a list nested
-  inside existing message chrome does not double it. Plain preserves the header/list divider and
-  whichever regular or compact padding applies.
-
-**Getters:** `sourceCount: number` — read-only, live-updated count of the currently-slotted children,
-handy for building a `label-plural` string reactively, e.g. `` list.labelPlural = `${list.sourceCount} sources` ``.
-
-**Events:** `lr-toggle` (`detail: { expanded: boolean }`) — the header was activated, expanding or
-collapsing the list.
-
-**Slots:** default — `<lr-source-card>` elements, neutral `<div>`/`<span>` wrappers, or
-author-owned `role="listitem"` entries. When every assigned child is one of those list-compatible
-forms, `[part="list"]` supplies `role="list"` and neutral, unroled children temporarily receive
-`role="listitem"`. Native controls and children with another explicit or native semantic role retain
-their own semantics; their presence omits list/listitem roles rather than creating an invalid ARIA
-list context. When every assigned child returns to this list-compatible allowlist, the
-list/listitem semantics return.
-
-**CSS parts:** `base` (outer container), `header` (the clickable `<button>` toggling `expanded`),
-`toggle` (the chevron indicator inside the header), `list` (wrapper around the default slot, `hidden`
-while collapsed).
-
-**Themeable custom properties:** `--lr-source-list-compact-header-padding` (default
-`var(--lr-space-2xs) var(--lr-space-s)`) and `--lr-source-list-compact-header-gap` (default
-`var(--lr-space-2xs)`) — `[part="header"]` padding/gap while `compact`; `--lr-source-list-compact-gap`
-(default `var(--lr-space-2xs)`) and `--lr-source-list-compact-list-padding` (default
-`var(--lr-space-s)`) — `[part="list"]` gap/padding while `compact`. All four are inline `var()`
-fallbacks at their point of use, so any can be set on the element or an ancestor. Otherwise shared
-tokens — `--lr-color-border`, `--lr-color-border-subtle`, `--lr-color-surface`,
-`--lr-color-text`, `--lr-color-brand` / `-brand-quiet`, `--lr-radius`, `--lr-space-xs`/`-s`/
-`-m`, `--lr-transition-fast`, `--lr-focus-ring-*`.
-
-**Optional peer deps:** none.
-
-### `lr-source-card`
-
-**Properties:**
-
-- `sourceId: string = ''` (attribute `source-id`) — stable identifier matching a
-  `<lr-citation-badge>` elsewhere on the page.
-- `title: string = ''` — the source's display title, e.g. a filename. Falls back to `"Untitled
-source"` when empty.
-- `page?: string | number` — optional page reference, e.g. `12` or `"iv"`, rendered as-is (never
-  parsed/validated as a number), appended to the title as `" — p. {page}"`.
-- `href?: string` — optional URL, echoed back (unopened) in `lr-open`'s detail.
-- `compact: boolean = false` (reflected) — tighter root padding and row gap, for the dense citation
-  lists these cards usually render in — the same convention as `lr-empty`'s `compact`. Purely a
-  density knob: the border and background stay. `false` (the default) keeps the full card padding.
-- `frame: LyraFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
-  vocabulary (`'card' | 'plain'`). `'card'` (the default) keeps the bordered, filled, padded box;
-  `'plain'` removes the border, background, padding and corner radius, so a card inside a
-  `<lr-source-list>` (or any container already drawing its own border/dividers) doesn't double it.
-  `plain` wins over `compact` when both are set — nothing left to tighten. The title and toggle keep
-  their brand color and hover underline under `plain`, since neither ever depended on the card
-  chrome. Use the shared `LyraFrame` type when authoring this property.
-- `disabled: boolean = false` (reflected) — turns off this card's OWN controls. The `title` button
-  and the "Show more"/"Show less" `toggle` both render `disabled`, so neither one can emit `lr-open`
-  or `lr-expand` and neither remains in the tab order, and the card paints at
-  `--lr-opacity-disabled` with a `not-allowed` cursor on both. The one `lr-expand` a disabled card
-  can still emit is the automatic collapse when the `full` slot empties while expanded — that
-  reports a state change the card genuinely made, exactly as it does when enabled. Both buttons
-  carry the native `:disabled`, so `::part(title):disabled` / `::part(toggle):disabled` restyle the
-  disabled affordance from outside. Every self-rendered sub-control is
-  gated, not just the primary one: a card whose title is inert but whose disclosure toggle still
-  expands reads as half-broken rather than disabled. Slotted `excerpt`/`full` content stays yours
-  to disable. Not form-associated, so an ancestor `<fieldset disabled>` does not cascade here.
-- `aria-pressed` and `aria-current` (attributes only) — forwarded reactively onto the `title`
-  button, the control that carries this card's action, the same mechanism `<lr-button>` and
-  `<lr-icon-button>` use. `aria-pressed` accepts `'true' | 'false' | 'mixed'`; `aria-current`
-  accepts `'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'`. Anything outside
-  those sets is dropped rather than passed through. The `toggle` button never receives either — it
-  already owns `aria-expanded` for its own disclosure state, and two conflicting state claims on
-  one control is worse than one. This is what lets a single-select citation list announce which
-  source is the active one.
-
-**Events:**
-
-- `lr-expand` (`detail: { sourceId: string; expanded: boolean }`) — the per-card "Show
-  more"/"Show less" toggle was activated. Unrelated to the parent `lr-source-list`'s own
-  expand/collapse, which only ever hides/shows the _set_ of cards, never a single card's own content.
-- `lr-open` (`detail: { sourceId: string; href?: string }`) — the title was activated. This
-  component never navigates on its own (a controlled component, the same convention
-  `<lr-tool-call-chip>`'s `lr-tool-call-chip-select` follows); a listener decides what "open"
-  means.
-
-**Slots:** `excerpt` (a short preview; when left empty, the `excerpt` part collapses away entirely —
-its wrapper is `hidden`, not just visually empty), `full` (the complete source text/chunk, hidden
-behind the "Show more"/"Show less" toggle — when left empty, no toggle renders at all; removing all
-`full`-slotted content while expanded auto-collapses it back).
-
-**CSS parts:** `base` (outer container), `title` (the clickable title/page heading, a `<button>`),
-`excerpt` (wrapper around the `excerpt` slot, `hidden` when the slot has no assigned content), `full`
-(wrapper around the `full` slot, `hidden` while collapsed), `toggle` (the "Show more"/"Show less"
-button — only rendered when the `full` slot has content).
-
-**Themeable custom properties:** `--lr-source-card-bg` (default `var(--lr-color-surface)`) —
-`[part='base']`'s RESTING background, the companion to the `compact` tier's levers below;
-`frame='plain'` still drops the fill entirely. `--lr-source-card-compact-padding` (default
-`var(--lr-space-xs)`) —
-`[part='base']`'s padding while `compact`; `--lr-source-card-compact-gap` (default
-`var(--lr-space-2xs)`) — the gap between `[part='base']`'s rows while `compact`. Both apply only in
-the `compact` state, so a dense citation list can be tuned without re-pointing shared spacing tokens
-elsewhere. Plus shared tokens — `--lr-color-border-subtle`, `--lr-color-surface`,
-`--lr-color-text` / `-text-quiet`, `--lr-color-brand`, `--lr-radius`, `--lr-space-xs`/`-s`,
-`--lr-focus-ring-*`.
-
-**Optional peer deps:** none.
-
-```html
-<lr-source-list label-plural="2 sources">
-  <lr-source-card source-id="doc-1" title="annual_report.pdf" page="12">
-    <span slot="excerpt">Revenue grew 12% year over year...</span>
-    <span slot="full"
-      >Revenue grew 12% year over year, driven primarily by...</span
-    >
-  </lr-source-card>
-  <lr-source-card source-id="doc-2" title="q3_notes.md">
-    <span slot="excerpt">No matching full-text chunk for this source.</span>
-  </lr-source-card>
-</lr-source-list>
-<script type="module">
-  // Elsewhere, a <lr-citation-badge>'s activation handler can scroll to and
-  // highlight the matching card -- neither component needs extra API surface
-  // for that, only source-id to be targeted by:
-  document.addEventListener("lr-citation-activate", (e) => {
-    const card = document.querySelector(
-      `lr-source-card[source-id="${e.detail.sourceId}"]`
-    );
-    card?.scrollIntoView({ block: "center" });
-  });
-</script>
-```
-
-`lr-source-list` removes the card list from the accessibility tree (not just visually hides it)
-while collapsed, via the native `hidden` attribute on `[part="list"]` — a screen reader user tabbing
-past the header never lands on off-screen source cards they can't currently see. Both components
-track slot presence in JS state (`slottedCount` on the list, `hasFullSlot` on the card) rather than
-relying on CSS `:empty`, since a `[part]` wrapper always contains a literal `<slot>` child regardless
-of assigned content; both also reconcile that state in `firstUpdated()` as a fallback for slot-
-forwarding scenarios or engines that don't fire `slotchange` for content already present at parse
-time.
-
-**Known gotchas:**
-
-- `lr-source-list` does not automatically build an “N sources” plural summary: provide
-  `labelPlural` when that is wanted. Its no-label fallback is localized through
-  `sourceListDefaultLabel`, and a per-instance `.strings` override reaches the rendered header.
-- `lr-source-card`'s own expand/collapse (`full` slot, `lr-expand` event) is completely
-  independent of the parent list's `expanded`/`lr-toggle` — collapsing the list doesn't reset an
-  individual card's `fullExpanded` state, and there is no cross-talk between the two components at
-  all beyond DOM nesting.
-- `lr-source-card` actively strips a bare host-level `title` attribute right after Lit syncs it into
-  the `title` property — otherwise the whole card would grow an unsolicited native tooltip repeating
-  the title text on hover. Set `title` only as a property/attribute meant to become the rendered
-  heading; don't rely on it surviving as a DOM attribute afterward.
-
----

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

@@ -58,7 +58,9 @@ string; mimeType?: string; name?: string; children?: LyraSourceEntry[] }`; flat
 **Events:** `lr-sources-change` (`detail: { selectedSourceIds }`, the complete updated leaf-id array,
 fired after every toggle including select-all. Also fired when a `sources` reassignment prunes a
 previously-selected id that is no longer a valid leaf. Not fired when a consumer sets
-`selectedSourceIds` directly; that assignment is normalized silently).
+`selectedSourceIds` directly; that assignment is normalized silently). The select-all checkbox's
+own `lr-checkbox-toggle-request`, native `input`/`change`, and `lr-input`/`lr-change` stay inside
+the component; `lr-sources-change` is the host-level report of that toggle.
 
 **Slots:** none.
 

package/llms/components/lr-sparkline.md

@@ -7,6 +7,8 @@
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
+- **Deprecated css-property** `--lr-sparkline-stroke-width` since `21.1.0`; use css-property `--line-width (the same value, declared on lr-sparkline itself)`; removal not before `23.0.0` — --lr-sparkline-stroke-width predates the mirrored Web Awesome --line-width and is read only as its fallback, so it has no effect wherever --line-width is set. Scope the replacement to lr-sparkline, because the unprefixed --line-width also reaches any other element that reads it. It keeps working through the 22.x line; a stylesheet cannot be observed using it, so it never logs a warning.
+- **Deprecated part** `area` since `21.1.0`; use part `::part(fill)`; removal not before `23.0.0` — area is a Lyra-only alias for the mirrored fill part on the same path; fill is the Web Awesome name. The area token stays on that path through the 22.x line; a stylesheet cannot be observed using a part, so it never logs a warning.
 - **Deprecated part** `base` since `8.0.0`; use part `::part(sparkline)`; removal not before `10.0.0` — The sparkline part names the rendered SVG wrapper unambiguously; base remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-sparkline` still publishes its own deprecated `base` part, so this alias is removed only when upstream's is.
 - **Optional peers** none
 - **Themeable via** 6 parts, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
@@ -56,14 +58,17 @@ space-separated samples restores the attribute-driven path.
 **Slots:** none.
 
 **CSS parts:** `sparkline` and deprecated `base` are aliases on the same outer SVG, `fill` is the
-area path for solid/gradient appearance, `line` is the stroke path. Additive aliases are `area` on
-the same fill path and `bar` on each extension-mode rectangle.
+area path for solid/gradient appearance, `line` is the stroke path, and the additive `bar` is each
+extension-mode rectangle. `area` is a deprecated alias of `fill` on the same path (removal not
+before 23.0.0); use `::part(fill)`.
 
 **Themeable custom properties:** `--fill-color` (area/gradient stop color), `--line-color` (stroke
 color), and `--line-width` (stroke width). Each reads through the live CSS cascade; line/fill
 default to the selected `trend`'s semantic Lyra tokens and `--line-width` falls back through the
-compatibility `--lr-sparkline-stroke-width` to `--lr-border-width-medium`. No canvas bridge or
-manual refresh is needed.
+deprecated `--lr-sparkline-stroke-width` (removal not before 23.0.0) to `--lr-border-width-medium`.
+Replace that alias with `--line-width` scoped to the element (`lr-sparkline { --line-width: 2px; }`),
+since the unprefixed name also reaches any other element that reads it. No canvas bridge or manual
+refresh is needed. Styling hooks cannot be observed, so neither deprecated alias logs a warning.
 
 **Optional peer deps:** none.
 

package/llms/components/lr-split-panel.md

@@ -7,7 +7,7 @@
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `8.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
-- **Deprecations** none
+- **Deprecated part** `split-panel` since `21.1.0`; use part `::part(base)`; removal not before `23.0.0` — split-panel is a Lyra-only second token on the same outer wrapper as base. Neither pinned wa-split-panel nor sl-split-panel publishes a wrapper part, so base, the root part name used across the library, remains the single supported spelling. The removal-not-before version is a policy floor, not a plan: should either upstream publish a component-named wrapper part, this alias stays for as long as upstream ships it.
 - **Optional peers** none
 - **Themeable via** 6 parts, 10 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`
@@ -66,9 +66,11 @@ custom-handle content inside the separator; its assigned subtree is inert, so th
 the sole pointer/keyboard resize control). Under RTL, logical start/end and horizontal pointer/arrow
 behavior mirror together; vertical behavior does not invert.
 
-**CSS parts:** `base split-panel` (both tokens are on the same outer wrapper), `start panel` and
+**CSS parts:** `base split-panel` (both tokens are on the same outer wrapper; `split-panel` is a
+deprecated alias of `base`, removal not before 23.0.0, so style `::part(base)`), `start panel` and
 `end panel` (each pane exposes its individual token plus the shared `panel` token), `divider`
-(focusable `role="separator"`, with value/min/max and disabled ARIA state).
+(focusable `role="separator"`, with value/min/max and disabled ARIA state). The deprecated part
+still matches until its removal; being a stylesheet selector, it logs no runtime warning.
 
 **Themeable custom properties:** `--divider-width` (default `4px`), `--divider-hit-area` (requested
 default `12px`, with Lyra's `--lr-icon-button-size` minimum target remaining the floor), `--min`

package/llms/components/lr-stat.md

@@ -7,7 +7,7 @@
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
-- **Deprecations** none
+- **Deprecated slot** default slot since `21.1.0`; use slot `slot="start"`; removal not before `23.0.0` — start is the library-wide adornment slot and already takes precedence when both are filled; retiring the unnamed icon alias stops an unnamed child from silently becoming the leading icon. lr-stat has no upstream counterpart, so no mirrored slot is affected.
 - **Optional peers** none
 - **Themeable via** 14 parts, 18 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`
@@ -94,8 +94,9 @@ value: string; readonly exactValue?: string }`; at most the first 10,000 rows ar
 
 **Events:** none.
 
-**Slots:** `start` (canonical leading icon), default (legacy leading-icon alias, retained as the
-fallback; `start` takes precedence when both are filled), `caption` (rich caption content —
+**Slots:** `start` (canonical leading icon), default (deprecated leading-icon alias, removal not
+before 23.0.0: it still renders while `start` is empty and `start` takes precedence when both are
+filled; move the icon to `slot="start"`), `caption` (rich caption content —
 overrides the `caption` attribute when slotted content is provided), `spark` (a sparkline, e.g. `<lr-sparkline
 slot="spark">`, or other compact trend visual — `lr-stat` only reserves the slot and doesn't
 render one itself), `sub` (rich sub-line content — overrides the `sub` attribute when slotted content

package/llms/components/lr-streaming-text-core.md

@@ -7,7 +7,7 @@
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Status** `experimental` since `16.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
-- **Deprecations** none
+- **Deprecated property** `codeBlockChrome` / `code-block-chrome` since `21.1.0`; use property `code-block-header`; removal not before `23.0.0` — code-block-chrome is a second spelling of code-block-header with identical behavior: either one enables the code-block headers of the composed Markdown element, which now always receives code-block-header. One name per concept removes a choice with no difference. It keeps enabling the headers through the 22.x line, and setting it logs a one-time development warning.
 - **Optional peers** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
 - **Themeable via** 25 parts, 2 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`
@@ -48,12 +48,14 @@ attribute names, and defaults described under `<lr-streaming-text>`'s own **Prop
 `rel="noopener noreferrer"` whenever a `target` is emitted); `internalLinkPrefix: string = ''`
 (attribute `internal-link-prefix`); `headingOffset: number = 0` (attribute `heading-offset`);
 `streamingRender: MarkdownStreamingRender = 'plain'` (attribute `streaming-render`, not reflected);
-`codeBlockHeader: boolean = false` (attribute `code-block-header`) and its compatibility alias
-`codeBlockChrome: boolean = false` (attribute `code-block-chrome`); `highlightCode: boolean = true`
+`codeBlockHeader: boolean = false` (attribute `code-block-header`) and its deprecated
+compatibility alias `codeBlockChrome: boolean = false` (attribute `code-block-chrome`; removal not
+before 23.0.0); `highlightCode: boolean = true`
 (attribute `highlight-code`); `headingAnchors: boolean = false` (attribute `heading-anchors`);
 `math: boolean = false`; `maxHeight: string = ''` (attribute `max-height`). All are forwarded to
 the composed `<lr-markdown-core>`, with matching behavior and defaults. `streamingRender` controls
-progressive output, and `codeBlockHeader` (or its `codeBlockChrome` alias) enables the localized
+progressive output, and `codeBlockHeader` (or its deprecated `codeBlockChrome` alias, which reaches
+the composed element as `codeBlockHeader`) enables the localized
 code label and source-copy action.
 
 **Exported helper:** `looksLikeMarkdown(text: string): boolean` — the same standalone heuristic
@@ -104,6 +106,6 @@ The Markdown part set also includes `task-list`, `task-item`, `task-item-checked
 `task-checkbox`, `table-wrapper`, `code-block-frame`, `code-block-copy-success`,
 `code-block-copy-error` and `streaming-tail`. `codeBlockHeader: boolean = false`
 (attribute `code-block-header`) enables the code-block header; `codeBlockChrome` (attribute
-`code-block-chrome`) is its compatibility alias. Successful and
+`code-block-chrome`) is its deprecated compatibility alias (removal not before 23.0.0). Successful and
 failed writes pass through as `lr-copy` and `lr-copy-error`, carrying the immutable clipboard
 outcome, bubbling and composed.

package/llms/components/lr-streaming-text.md

@@ -7,7 +7,7 @@
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
-- **Deprecations** none
+- **Deprecated property** `codeBlockChrome` / `code-block-chrome` since `21.1.0`; use property `code-block-header`; removal not before `23.0.0` — code-block-chrome is a second spelling of code-block-header with identical behavior: either one enables the code-block headers of the composed Markdown element, which now always receives code-block-header. One name per concept removes a choice with no difference. It keeps enabling the headers through the 22.x line, and setting it logs a one-time development warning.
 - **Optional peers** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
 - **Themeable via** 25 parts, 2 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`
@@ -61,9 +61,11 @@ properties existed:
 - `headingOffset: number = 0` (attribute `heading-offset`) — forwarded to the composed
   `<lr-markdown>`'s own `headingOffset`.
 - `streamingRender: MarkdownStreamingRender = 'plain'` (attribute `streaming-render`, not reflected)
-  and `codeBlockHeader: boolean = false` (attribute `code-block-header`), with its compatibility
-  alias `codeBlockChrome: boolean = false` (attribute `code-block-chrome`) — forwarded to the
-  composed Markdown element. Their settled-block streaming behavior, code-copy behavior, and defaults match
+  and `codeBlockHeader: boolean = false` (attribute `code-block-header`), with its deprecated
+  compatibility alias `codeBlockChrome: boolean = false` (attribute `code-block-chrome`; removal not
+  before 23.0.0; setting it logs a one-time development warning) — forwarded to the composed
+  Markdown element, which receives either header option as its own `codeBlockHeader`. Their
+  settled-block streaming behavior, code-copy behavior, and defaults match
   `<lr-markdown>`; see its **Properties** section above.
   Use `streaming-render="progressive"` with `content-mode="markdown"`: in `auto` mode the element
   switches from plain text to Markdown when detection first succeeds, which replaces the displayed
@@ -159,7 +161,8 @@ showing the previous stream's stale final content for the length of the window.
 
 Rendering itself is never reimplemented here: Markdown mode composes `<lr-markdown>` directly,
 forwarding this component's own `streaming` through as that component's `streaming` hint prop,
-  `streamingRender`, `codeBlockHeader`, `codeBlockChrome`, `languages` verbatim, and the rest of `<lr-markdown>`'s
+  `streamingRender`, `codeBlockHeader` (on when either this element's `codeBlockHeader` or its
+  deprecated `codeBlockChrome` is), `languages` verbatim, and the rest of `<lr-markdown>`'s
   configuration surface verbatim too (`tabSize`, `htmlMode`, `gfm`, `linkTarget`,
   `internalLinkPrefix`, `headingOffset`, `highlightCode`, `headingAnchors`, `math`, `maxHeight` —
   see **Properties** above); plain-text mode
@@ -190,6 +193,6 @@ The Markdown part set also includes `task-list`, `task-item`, `task-item-checked
 `task-checkbox`, `table-wrapper`, `code-block-frame`, `code-block-copy-success`,
 `code-block-copy-error` and `streaming-tail`. `codeBlockHeader: boolean = false`
 (attribute `code-block-header`) enables the code-block header; `codeBlockChrome` (attribute
-`code-block-chrome`) is its compatibility alias. Successful and
+`code-block-chrome`) is its deprecated compatibility alias (removal not before 23.0.0). Successful and
 failed writes pass through as `lr-copy` and `lr-copy-error`, carrying the immutable clipboard
 outcome, bubbling and composed.

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

@@ -212,4 +212,134 @@ class AccentTrigger extends LitElement {
   tuning the gap and hit size small enough to avoid wrapping is a guess that breaks at the next
   swatch added.
 
+### gemstoneAccentPicker — the signature accent selector
+
+`gemstoneAccentPicker` names the canonical composition of `lr-icon-button`, `lr-popover`, and
+`lr-swatch-picker mode="gemstone"`. It is a **pattern name, not an exported component or tag**.
+Use it for application accent selection: a glowing current-gem trigger, one compact
+“Gemstone: selected name” caption, and all nine canonical gemstones, in `GEMSTONE_KEYS` order, in
+one row. Localize the caption, trigger, dialog, radiogroup, and item names. Omit introductory copy
+and a second selected-name paragraph.
+
+The consuming Lit component imports these granular entries and lists
+`gemstoneSelectedGlyphStyles` in its `static styles` ahead of the CSS that follows.
+`components/forms/icon-button/icon-button-register.js` can replace `icon-button.js` when no icon
+button in the application uses `icon` or `src`:
+
+```ts
+import '@aceshooting/lyra-ui/components/forms/icon-button/icon-button.js';
+import '@aceshooting/lyra-ui/components/overlays/overlay/popover.js';
+import '@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.js';
+import {
+  GEMSTONE_KEYS,
+  GEMSTONES,
+  gemstoneGlyph,
+  gemstoneSelectedGlyphStyles,
+  type GemstoneKey,
+} from '@aceshooting/lyra-ui/theme/gemstones.js';
+```
+
+`--accent-color`, `--caption-color`, and `--text-color` are application-owned theme tokens.
+`--lr-overlay-max-inline-size` lifts the popup's default 20rem cap so the 20rem palette plus the
+popover's own padding fits. Both `--lr-gemstone-selected-*` values reach the trigger glyph and the
+picker's checked glyph alike: a 0.42rem halo at 92% of the accent. Leave
+`--lr-gemstone-selected-shine-duration` unset to keep the default 1.8s shine. The
+`--lr-icon-button-*` values keep the trigger free of a rectangular fill at rest, on hover, and
+while pressed:
+
+```css
+.gemstone-accent-picker {
+  --lr-overlay-max-inline-size: 22rem;
+  --lr-gemstone-selected-color: color-mix(in srgb, var(--accent-color) 92%, transparent);
+  --lr-gemstone-selected-blur: .42rem;
+}
+.gemstone-accent-picker lr-icon-button {
+  --lr-icon-button-background: transparent;
+  --lr-icon-button-background-hover: transparent;
+  --lr-icon-button-background-active: transparent;
+  --lr-icon-button-border: none;
+}
+.gem { display: inline-flex; inline-size: 1.15rem; block-size: 1.15rem; }
+.gem svg { inline-size: 100%; block-size: 100%; }
+.palette {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: .15rem;
+  inline-size: 20rem;
+  padding: .3rem;
+}
+.heading {
+  margin: .2rem .3rem .5rem;
+  color: var(--caption-color);
+  font-size: .75rem;
+  font-weight: 600;
+}
+.name { color: var(--text-color); }
+.palette lr-swatch-picker {
+  padding: 0 .3rem .3rem;
+  --lr-swatch-picker-hit-size: 1.75rem;
+  --lr-swatch-picker-wrap: nowrap;
+  --lr-swatch-picker-gap: .25rem;
+}
+@media (max-width: 30rem) {
+  .palette { inline-size: auto; }
+  .palette lr-swatch-picker {
+    --lr-swatch-picker-hit-size: 1.5rem;
+    --lr-swatch-picker-gap: .125rem;
+  }
+}
+```
+
+At the default 16px root font size, `1.75rem`/`.25rem` give 28px targets with 4px gaps, and
+`1.5rem`/`.125rem` give 24px targets with 2px gaps. Below 30rem the palette shrinks to its row, so
+the popup fits a 320px viewport without scrolling. A `calc(100dvw - 2.5rem)` palette overflows the
+popup by 2px there. Apply `data-lr-gemstone-selected` to the transparent glyph wrapper, not the
+whole trigger, so the halo follows the gem's silhouette. The focus ring belongs to keyboard focus;
+do not add a permanent circular selection border. Leave the popover's default content padding and
+arrow intact.
+
+This Lit template assumes `selected` is a `GemstoneKey`. `accentLabel` names the dialog and the
+radiogroup. `triggerLabel(name)` (“Accent color: Ruby”), `captionLabel` (“Gemstone:”, with the
+locale's own separator), and `translateGemstone()` come from the application's catalog.
+`onAccentChange()` validates the string and updates application state:
+
+```ts
+// Build once per locale. A new array on every render re-creates every swatch and briefly blurs
+// the focused one.
+const items = GEMSTONE_KEYS.map((key) => ({
+  value: key,
+  color: GEMSTONES[key].fill,
+  label: translateGemstone(key),
+  gemstone: key,
+}));
+
+const name = translateGemstone(selected);
+html`
+  <lr-popover class="gemstone-accent-picker" placement="bottom-end"
+    popup-role="dialog" aria-label=${accentLabel}>
+    <lr-icon-button slot="trigger" label=${triggerLabel(name)}>
+      <span class="gem" data-lr-gemstone-selected aria-hidden="true">${gemstoneGlyph(GEMSTONES[selected].fill)}</span>
+    </lr-icon-button>
+    <div class="palette">
+      <p class="heading">${captionLabel} <span class="name">${name}</span></p>
+      <lr-swatch-picker mode="gemstone" aria-label=${accentLabel}
+        .items=${items} .value=${selected}
+        @lr-change=${(event: CustomEvent<{ value: string }>) => onAccentChange(event.detail.value)}>
+      </lr-swatch-picker>
+    </div>
+  </lr-popover>
+`;
+```
+
+The parts already supply the behavior, so do not re-implement it. The picker is a roving-tabindex
+`radiogroup` with `aria-checked` and a `:focus-visible` ring per swatch, and its Arrow keys swap
+under RTL. The popover keeps `bottom-end` on the logical end under RTL and returns focus to the
+trigger on Escape. `gemstoneSelectedGlyphStyles` stops the shine under
+`prefers-reduced-motion: reduce`. Verify 320px and desktop layouts, enlarged text, and both color
+modes. In a sidebar or settings panel, the caption and row may appear inline with the same glow
+and spacing; use the compact tier when the container is narrow and allow wrapping if even that
+tier cannot fit. Never shrink targets below 24px. Application theme application, default accent,
+validation, and persistence remain caller-owned.
+
 ---