@aceshooting/lyra-ui 9.1.1 → 11.0.0

package/llms/components/lr-accordion-item.md

@@ -6,7 +6,7 @@
 - **Class** `LyraAccordionItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/details/accordion-item.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecated part** `base` since `8.2.3`; use part `::part(accordion-item)`; removal not before `10.0.0` — The accordion-item part names the outer wrapper explicitly; base remains on that same node during the compatibility window.
+- **Deprecated part** `base` since `8.2.3`; use part `::part(accordion-item)`; removal not before `10.0.0` — The accordion-item part names the outer wrapper explicitly; base remains on that same node during the compatibility window. That version is a policy floor, not a plan: Web Awesome still publishes its own deprecated `base` part on `wa-accordion-item`, and a mirrored tag owes its whole upstream surface, so this alias is removed only when upstream's is.
 - **Optional peers** none
 - **Themeable via** 8 parts, 13 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-details`, `lr-accordion` (same section below)
@@ -91,11 +91,20 @@ the ladder doesn't cover is a two-line override rather than a fork.
 
 **Events:**
 
-- `lr-expand`, `lr-collapse`, `lr-after-expand`, `lr-after-collapse` — accordion group lifecycle.
+- `lr-expand`, `lr-collapse`, `lr-toggle-request`, `lr-after-expand`, `lr-after-collapse` —
+  accordion group lifecycle.
 - `lr-show`, `lr-hide`, `lr-toggle`, `lr-after-show`, `lr-after-hide` — Details lifecycle only.
 
 On the accordion, `lr-expand` and `lr-collapse` fire before a direct item changes, are cancelable,
-and carry `detail: { item }`. **Changed in 9.0.0:** `item` is now always a `LyraAccordionItem` —
+and carry `detail: { item }`. **New in 10.0.0:** a cancelable `lr-toggle-request`
+(`detail: { collapsed, item }`) fires alongside the matching directional event for every transition,
+including sibling auto-collapses in `single`/`single-collapsible` mode and `collapseAll()`. It carries
+the direction in the detail rather than the event name, matching `<lr-code-block>`/`<lr-chat-message>`'s
+`lr-toggle-request` convention, plus an `item` reference the single-panel siblings do not need (an
+accordion's toggling entity is one of several children, so the event target alone cannot identify it).
+`preventDefault()` on **either** event vetoes the transition — the two are a symmetric veto pair, not
+a primary and a notification. Note `<lr-thinking-panel>`'s own `lr-toggle-request` spells its detail
+`{ expanded }` rather than `{ collapsed }`; the two conventions are not fully unified. **Changed in 9.0.0:** `item` is now always a `LyraAccordionItem` —
 it could previously also be a `LyraDetails`. The exported `LyraAccordionPanel` union that spelled
 that has been removed; use `LyraAccordionItem`. An accepted transition finishes with the
 non-cancelable

package/llms/components/lr-accordion.md

@@ -91,11 +91,20 @@ the ladder doesn't cover is a two-line override rather than a fork.
 
 **Events:**
 
-- `lr-expand`, `lr-collapse`, `lr-after-expand`, `lr-after-collapse` — accordion group lifecycle.
+- `lr-expand`, `lr-collapse`, `lr-toggle-request`, `lr-after-expand`, `lr-after-collapse` —
+  accordion group lifecycle.
 - `lr-show`, `lr-hide`, `lr-toggle`, `lr-after-show`, `lr-after-hide` — Details lifecycle only.
 
 On the accordion, `lr-expand` and `lr-collapse` fire before a direct item changes, are cancelable,
-and carry `detail: { item }`. **Changed in 9.0.0:** `item` is now always a `LyraAccordionItem` —
+and carry `detail: { item }`. **New in 10.0.0:** a cancelable `lr-toggle-request`
+(`detail: { collapsed, item }`) fires alongside the matching directional event for every transition,
+including sibling auto-collapses in `single`/`single-collapsible` mode and `collapseAll()`. It carries
+the direction in the detail rather than the event name, matching `<lr-code-block>`/`<lr-chat-message>`'s
+`lr-toggle-request` convention, plus an `item` reference the single-panel siblings do not need (an
+accordion's toggling entity is one of several children, so the event target alone cannot identify it).
+`preventDefault()` on **either** event vetoes the transition — the two are a symmetric veto pair, not
+a primary and a notification. Note `<lr-thinking-panel>`'s own `lr-toggle-request` spells its detail
+`{ expanded }` rather than `{ collapsed }`; the two conventions are not fully unified. **Changed in 9.0.0:** `item` is now always a `LyraAccordionItem` —
 it could previously also be a `LyraDetails`. The exported `LyraAccordionPanel` union that spelled
 that has been removed; use `LyraAccordionItem`. An accepted transition finishes with the
 non-cancelable

package/llms/components/lr-agent-eval-dashboard.md

@@ -7,7 +7,7 @@
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `6.2.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 13 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`
 

package/llms/components/lr-agent-trace.md

@@ -31,7 +31,9 @@ hierarchical trace tree from one shared `spans` array.
   (`'agent' | 'llm' | 'tool' | 'retriever' | 'embedding' | 'other'`). Empty shows every kind;
   pre-settable (e.g. to hide `retriever`/`embedding` by default) and readable back after
   `lr-span-visibility-change`
-- `label: string = ''` — forwarded to the composed `lr-trace-tree`
+- `label?: string` — forwarded to the composed `lr-trace-tree`. Omission leaves that tree's own
+  `label` unset so it localizes its own default; any supplied string (including `''`) is
+  forwarded verbatim
 - `showTokens: boolean = false` (attribute `show-tokens`), `showCost: boolean = false` (attribute
   `show-cost`), `showBars: boolean = true` (attribute `show-bars`, renamed from `hideBars` in
   9.0.0 to match the positive polarity of its two siblings above — default inverted so the

package/llms/components/lr-agent-workspace.md

@@ -126,3 +126,23 @@ optional-peer fallback.
 
 Every public data/value property is controlled: forwarded child intents bubble without mutating
 `messages`, `composerValue`, selections, run state, or persistence-owned data inside the shell.
+
+**Only the transcript scrolls.** `[part='base']` is a three-row grid — header, conversation,
+composer — and only the middle row can shrink, so the composed `lr-chat-viewport` owns the
+scrolling and the chrome rows stay put at their content size. The trade: give the workspace less
+block-size than the chrome needs and the conversation row collapses to zero first, after which the
+header or composer is clipped with no scrollbar. That takes unusually large slotted chrome — a very
+tall `header-actions` toolbar, or a `composer` replacement much taller than the built-in one — and
+the region that supplied it caps and scrolls itself through the public parts:
+
+```css
+lr-agent-workspace::part(header) {
+  max-block-size: 4rem;
+  overflow: auto;
+}
+```
+
+The same applies to `::part(composer)`. Both declarations are needed: the cap keeps the grid track
+inside the workspace, and `overflow` makes the capped region scrollable instead of spilling. No
+component-owned custom property duplicates this, because a `::part()` rule from your tree already
+wins over the shadow stylesheet regardless of specificity.

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

@@ -75,9 +75,15 @@ ancestor. They exist because `::part(view-button)[aria-pressed='true']` is inval
 library-wide brand tokens as the only prior lever.
 
 ```html
-<lr-artifact-panel label="report.md" kind="document" .versions=${versions}
-  @lr-restore=${(e) => restoreVersion(e.detail.versionId)}>
-  <lr-markdown .content=${markdown}></lr-markdown>
-  <lr-code-block slot="code" language="markdown" .code=${markdown}></lr-code-block>
+<lr-artifact-panel label="report.md" kind="document">
+  <lr-markdown id="preview"></lr-markdown>
+  <lr-code-block slot="code" id="code" language="markdown"></lr-code-block>
 </lr-artifact-panel>
+<script type="module">
+  const panel = document.querySelector("lr-artifact-panel");
+  panel.versions = versions;
+  panel.querySelector("#preview").content = markdown;
+  panel.querySelector("#code").code = markdown;
+  panel.addEventListener("lr-restore", (e) => restoreVersion(e.detail.versionId));
+</script>
 ```

package/llms/components/lr-attachment-chip.md

@@ -22,7 +22,7 @@ to populate it: set `file` to a real `File` (fresh from a picker/drop), from whi
 `mime-type`/`thumbnail-src` props instead, for reconstructing a chip from server-persisted
 attachment metadata after a page reload, when no real `File` object exists any more. `file` always
 wins when both are present. When a real `File` or `preview-src` is available, the chip offers a
-localized action that emits a cancelable `lr-preview-request`; it never registers or owns a viewer
+localized action that emits a plain, non-cancelable `lr-preview-request`; it never registers or owns a viewer
 or overlay, so the host composes the desired preview surface.
 
 **Properties:**
@@ -81,9 +81,12 @@ derived from `` `${file.name}:${file.size}:${file.lastModified}` ``; when neithe
 generated internal id is used as a last resort.
 
 **Events:** `lr-remove` (`detail: { attachmentId }`, only rendered while `removable`), `lr-retry`
-(`detail: { attachmentId }`, only rendered while `status="error"`), and cancelable
-`lr-preview-request` (`detail: { attachmentId, name, mimeType, src }`). Preventing the preview
-request is a host veto point; the chip itself has no preview default action.
+(`detail: { attachmentId }`, only rendered while `status="error"`), and
+`lr-preview-request` (`detail: { attachmentId, name, mimeType, src }`) — a plain, non-cancelable
+notification that the preview action was activated. **Breaking in 10.0.0:** this event was
+advertised as cancelable, but the chip never read `defaultPrevented` and owns no preview default
+action to veto (it never registers or owns a viewer/overlay), so `preventDefault()` was a no-op.
+The flag is gone rather than left as a promise the component cannot keep.
 
 **Slots:** none.
 

package/llms/components/lr-attachment-trigger.md

@@ -74,10 +74,13 @@ hidden via CSS by default, exposed as a part only so a consumer can override tha
 **Optional peer deps:** none.
 
 ```html
-<lr-attachment-trigger .capabilities=${['files', 'image', 'camera']} accept=".pdf,.docx"
-  @lr-files=${(e) => queueFiles(e.detail.capability, e.detail.files)}
-  @lr-camera-request=${openCameraFlow}
-></lr-attachment-trigger>
+<lr-attachment-trigger accept=".pdf,.docx"></lr-attachment-trigger>
+<script type="module">
+  const trigger = document.querySelector("lr-attachment-trigger");
+  trigger.capabilities = ["files", "image", "camera"];
+  trigger.addEventListener("lr-files", (e) => queueFiles(e.detail.capability, e.detail.files));
+  trigger.addEventListener("lr-camera-request", openCameraFlow);
+</script>
 ```
 
 **Known gotchas:**

package/llms/components/lr-av-player.md

@@ -83,7 +83,9 @@ unsupported or unresolved targets report `false` through the return value and `l
 `lr-rate-change` (`detail: { rate }`), `lr-cue-change`
 (`detail: { readonly cueId, readonly index }`; `cueId` is `null` and `index` is `-1` when no cue is active),
 `lr-highlight-activate` (`detail: { highlightId }`), `lr-anchor-result` (`detail: {
-found }`), `lr-search-change` (`detail: { query, matchCount, activeIndex }`), and
+found }`), `lr-search-change` (`detail: { query, matchCount, matchCountExact, activeIndex }`;
+`matchCountExact` is always `true` — `search()` matches over the already-loaded `cues` array with no
+additional ceiling), and
 `lr-render-error` (`detail: { error }`). The native `ended`, `error`, `loadedmetadata`, `pause`,
 `play`, `timeupdate`, and `volumechange`
 events are also relayed exactly once from the host as native `Event` instances. Like the original

package/llms/components/lr-avatar.md

@@ -96,14 +96,14 @@ variant's quiet tint.
 <lr-avatar label="Assistant"><svg slot="icon" viewBox="0 0 24 24"><!-- role glyph --></svg></lr-avatar>
 
 <!-- Far down a long list: defer the request, fall back to a glyph, and report a broken URL. -->
-<lr-avatar
-  image="/users/7/photo.jpg"
-  label="Ada Lovelace"
-  loading="lazy"
-  @lr-error=${(e) => reportBrokenAvatar(e.detail.image)}
->
+<lr-avatar id="lazy-avatar" image="/users/7/photo.jpg" label="Ada Lovelace" loading="lazy">
   <svg slot="icon" viewBox="0 0 24 24"><!-- fallback glyph --></svg>
 </lr-avatar>
+<script type="module">
+  document
+    .getElementById("lazy-avatar")
+    .addEventListener("lr-error", (e) => reportBrokenAvatar(e.detail.image));
+</script>
 ```
 
 **Known gotchas:**

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

@@ -7,8 +7,8 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 16 parts, 35 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-line-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`
 
@@ -25,7 +25,8 @@ and behavior there. **See `llms/components/lr-chart.md` for the details, code ex
 of every entry in these lists.**
 
 **Properties:** `description`, `grid`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `max`, `min`, `plugins`, `stacked`, `withoutAnimation` (`without-animation`),
+(`legend-position`), `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
+`stacked`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
@@ -43,7 +44,7 @@ complete `hiddenDatasets` snapshot).
 **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-truncation`, `feature-warning`, `center`, `error` (neutral visible message
+`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`).
@@ -52,7 +53,8 @@ failure transition is announced through the shared document-level light-DOM asse
 `--lr-chart-tick-color`, `--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-reset-zoom-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-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
@@ -66,7 +68,7 @@ together. The mirrored hooks are `--border-color-1`,
 `zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
-<lr-bar-chart legend></lr-bar-chart>
+<lr-bar-chart></lr-bar-chart>
 <lr-pie-chart></lr-pie-chart>
 <script>
   document.querySelector('lr-bar-chart').labels = ['A', 'B'];

package/llms/components/lr-box-plot.md

@@ -7,8 +7,8 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `@sgratzl/chartjs-chart-boxplot`, `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 11 parts, 11 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Optional peers** `@sgratzl/chartjs-chart-boxplot`, `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 12 parts, 13 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`
 
 ---
@@ -46,6 +46,14 @@ browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
 - `formatter?: LyraChartFormatter`, `valueFormatter?: LyraChartValueFormatter` — numeric axis,
   tooltip, table, summary, and export formatting; the context-object formatter takes precedence
 - `showDataTable: boolean = false` (attribute `show-data-table`) — reveals the accessible data table
+- `dataTableToggle: boolean = false` (attribute `data-table-toggle`, new in 10.1.0) — renders a
+  localized disclosure button (`part="data-table-toggle"`) above the data table so a *sighted*
+  reader can reveal the numbers on demand. `showDataTable` alone is all-or-nothing, which left
+  consumers wrapping a duplicated table in their own `<details>`. With the toggle on,
+  `showDataTable` becomes the disclosure's **initial** state rather than its whole behavior; the
+  table stays in the DOM in both states, so assistive technology never loses it, and the button
+  carries `aria-expanded` plus `aria-controls` pointing at the `data-table` wrapper. Unset, nothing
+  renders and behavior is identical to before.
 
 **Methods:** `exportData('csv'|'png')` returns spreadsheet-safe summary rows or the current canvas
 PNG data URL. `refreshTheme()` re-reads canvas theme custom properties after an ancestor theme
@@ -84,7 +92,7 @@ detailed sample and notice, making it the escape hatch for complete data.
 
 **CSS parts:** `base`, `plot` (the fixed-height canvas region), `canvas`, `legend`,
 `legend-item`, `legend-item-hidden` (added to a legend item while its box series is hidden),
-`legend-swatch`, `description`, `data-table`, `error` (neutral visible message shown
+`legend-swatch`, `description`, `data-table`, `data-table-toggle` (the `dataTableToggle` disclosure button), `error` (neutral visible message shown
 instead of `canvas` when the optional box-plot peer fails to load; the failure transition is
 announced through the shared document-level light-DOM assertive sink), `data-truncation` (the
 bounded-alternative sampling notice)
@@ -101,7 +109,10 @@ so `--lr-theme-color-chart-*` retheming reaches box plots too. `--lr-chart-patte
 `--lr-chart-canvas-hover-outline-width` (default `var(--lr-border-width-thin)`) sizes the `canvas`
 hover outline, `--lr-chart-legend-item-active-bg` and `--lr-chart-legend-item-hover-bg` retune the
 pressed and hovered legend rows, and `--lr-chart-legend-side-max` caps a side legend — the same tokens and defaults as
-`lr-chart`.
+`lr-chart`. Its own `dataTableToggle` disclosure button carries box-plot-namespaced hooks rather
+than inheriting the chart pair, since its stylesheet is not a re-export:
+`--lr-box-plot-data-table-toggle-hover-bg` (defaults to `--lr-color-brand-quiet`) and
+`--lr-box-plot-data-table-toggle-active-bg` (defaults to its standard active color mix).
 
 **Forced colors:** under `forced-colors: active` the eight-color ramp is remapped onto the small
 repeating system-color cycle the platform exposes, so series 1/4/7 (and 2/5/8, 3/6) would otherwise

package/llms/components/lr-browser-frame.md

@@ -56,9 +56,13 @@ phase write queued while detached.
 viewport's aspect ratio.
 
 ```html
-<lr-browser-frame phase="streaming" url="https://example.com" .pings=${pings}
-  @lr-take-over=${(e) => setController(e.detail.controller)} @lr-stop=${() => stopSession()}
-></lr-browser-frame>
+<lr-browser-frame phase="streaming" url="https://example.com"></lr-browser-frame>
+<script type="module">
+  const frame = document.querySelector("lr-browser-frame");
+  frame.pings = pings;
+  frame.addEventListener("lr-take-over", (e) => setController(e.detail.controller));
+  frame.addEventListener("lr-stop", () => stopSession());
+</script>
 ```
 
 **Additional API surface:**

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

@@ -7,8 +7,8 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 16 parts, 35 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-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -25,7 +25,8 @@ and behavior there. **See `llms/components/lr-chart.md` for the details, code ex
 of every entry in these lists.**
 
 **Properties:** `description`, `grid`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `max`, `min`, `plugins`, `stacked`, `withoutAnimation` (`without-animation`),
+(`legend-position`), `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
+`stacked`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
@@ -43,7 +44,7 @@ complete `hiddenDatasets` snapshot).
 **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-truncation`, `feature-warning`, `center`, `error` (neutral visible message
+`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`).
@@ -52,7 +53,8 @@ failure transition is announced through the shared document-level light-DOM asse
 `--lr-chart-tick-color`, `--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-reset-zoom-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-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
@@ -66,7 +68,7 @@ together. The mirrored hooks are `--border-color-1`,
 `zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
-<lr-bar-chart legend></lr-bar-chart>
+<lr-bar-chart></lr-bar-chart>
 <lr-pie-chart></lr-pie-chart>
 <script>
   document.querySelector('lr-bar-chart').labels = ['A', 'B'];

package/llms/components/lr-calendar.md

@@ -29,8 +29,15 @@ title, readonly color?, readonly data? }`; `date` is an ISO `YYYY-MM-DD` string
 - `view: CalendarView = 'month'`, where `CalendarView = 'month' | 'agenda'` (reflected) — agenda
   lists the effective visible month's events, date-sorted. Foreign tokens normalize and reflect to
   `month`
-- `firstDayOfWeek: number = 1` (attribute `first-day-of-week`) — sanitized to a finite integer
-  (fallback `1`) and wrapped into `0`–`6`, so a malformed value can't drop days
+- `firstDayOfWeek: LyraCalendarFirstDayOfWeek = 'auto'` (attribute `first-day-of-week`) — which
+  weekday the grid starts on. **Breaking in 10.0.0:** the default was a hardcoded `1` (Monday)
+  regardless of locale; it now derives from the effective locale through the same
+  `resolveFirstDayOfWeek()` contract `<lr-date-picker>`/`<lr-date-input>` already use, so an unset
+  `<lr-calendar>` renders Sunday-first under `en-US` and Monday-first under `fr-FR` instead of
+  disagreeing with a date picker on the same page. **Also breaking in 10.0.0:** the bare `0`–`6`
+  integer form is gone; the value is now one of the shared weekday-name tokens (`'auto'`, then
+  `'sun'` through `'sat'`), which pins the week start independent of locale. Pass `'mon'` to keep
+  the pre-10.0.0 rendering.
 - `accessibleLabel: string = ''` (attribute `aria-label`) — names the host. The nested calendar
   section retains the localized purpose name rather than duplicating an authored host name; when
   set programmatically without a host attribute, this value names the section

package/llms/components/lr-card.md

@@ -116,6 +116,30 @@ former brand and active-mix values when unset.
 
 - every `appearance` renders on the _same_ `[part="base"]` element — there's no separate element per
   variant, so a `::part(base)` override applies uniformly regardless of `appearance`.
+- **a card clips, it does not scroll — and it never picks a scroll owner for you.** `[part='base']`
+  stretches to the host's allocated block-size and clips its overflow, which is what keeps a
+  full-bleed `media`/`image` child inside the rounded border. In an auto-sized row the card simply
+  grows and nothing is clipped; give it a _definite_ allocation (a fixed grid row, an explicit
+  `block-size`) and body content taller than that allocation is clipped silently, with no
+  scrollbar. Neither upstream card exposes an overflow, block-size, or scroll hook and neither does
+  this one: the public `body` part already carries the whole decision, and a `::part()` rule from
+  your tree wins over the shadow stylesheet regardless of specificity. A fixed-height tile that
+  must hold more content says so itself:
+
+  ```css
+  .tile-grid {
+    display: grid;
+    grid-template-rows: 12rem;
+  }
+  .tile-grid lr-card::part(body) {
+    overflow: auto;
+    overscroll-behavior: contain;
+  }
+  ```
+
+  `overflow` other than `visible` also zeroes the body's automatic minimum size, so that one
+  declaration is enough — the body shrinks into the tile and scrolls, and `max-block-size` /
+  `scrollbar-gutter` stay available on the same rule. The linked (`href`) card behaves identically.
 - slot-presence (`header`/`media`/`image`/`footer`/`actions`/`header-actions`/`footer-actions`) is
   tracked in JS, not via CSS `:empty` (a
   `[part]` wrapper always contains a literal `<slot>` child, so `:empty` never matches) — the same

package/llms/components/lr-chart.md

@@ -7,8 +7,8 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 16 parts, 35 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`
 
 ---
@@ -36,6 +36,32 @@ property).
 - `max: number | null = null`, `min: number | null = null` — finite value-axis bounds. They apply to
   the cartesian value axis selected by `indexAxis`, or the radial `r` scale; non-finite writes are
   omitted before Chart.js sees them
+- `annotations: readonly LyraChartAnnotation[] = []` (attribute: false) — declarative reference
+  lines and shaded bands: a threshold, an event year, a regime change, a highlighted period.
+  `LyraChartAnnotation { axis?: 'x' | 'y'; value?: number; from?: number; to?: number; label?:
+  string; tone?: LyraVariant }` — `tone` is the shared `LyraVariant` vocabulary
+  (`'neutral' | 'brand' | 'success' | 'warning' | 'danger'`), not a chart-local copy. A finite `value` renders
+  a reference line on that axis; a finite `from`/`to` pair renders a band bounded on that axis and
+  spanning the other. `axis` defaults to `'y'`. An entry with neither (or non-finite numbers) is
+  dropped rather than handed to Chart.js; a reversed range is normalized. Labelled entries are
+  included in the generated accessible description, mirroring `lr-heatmap` — the label is
+  consumer-supplied text and so is not localized, and an unlabelled line has no nameable meaning to
+  announce. Needs the optional `chartjs-plugin-annotation` peer, loaded on first actual demand, so a
+  page with no annotated charts never downloads it; without it the chart still renders and a single
+  console warning explains the no-op. The plugin is registered globally, like `chartjs-plugin-zoom`
+  and unlike `chartjs-plugin-datalabels`: it draws nothing unless a chart supplies annotation
+  options, so the registration is unobservable to charts that set none, and registration is also
+  what installs the plugin's own element defaults
+- `scaleType: 'linear' | 'logarithmic' = 'linear'` (attribute `scale-type`, type
+  `LyraChartScaleType`) — scale type for the **value** axis; the categorical axis is never
+  affected. `'logarithmic'` plots data spanning several orders of magnitude (prices, latency
+  percentiles, file sizes) honestly, where a linear axis collapses everything below the maximum
+  into the baseline. Inherited by `lr-line-chart`, `lr-scatter-chart` and `lr-bar-chart`, and
+  applied to the secondary `y2` axis too when one is present. A logarithmic axis cannot represent
+  zero (`log(0)` is `-Infinity`), so `beginAtZero` is not forwarded in that mode and non-positive
+  points are dropped by Chart.js's own log scale. Chart.js rejects an unregistered scale type at
+  construction, so `LogarithmicScale` is registered with the core — it ships inside the `chart.js`
+  module already loaded, adding no download weight
 - `plugins: LyraChartPlugin[] = []` — peer-neutral per-instance Chart.js plugin structures,
   combined without duplicates with Lyra's
   on-demand data-label plugin and any `config.plugins` entries
@@ -67,9 +93,9 @@ property).
   non-integer, negative, and out-of-range indexes are discarded. The component writes the accepted
   legend-toggle snapshot back to this property so a host can persist it, and a programmatic write
   reconciles Chart.js and the DOM legend silently without emitting either legend-visibility event.
-- `withoutLegend: boolean = false` (attribute `without-legend`) — the legend shows by default;
-  set this to hide it. Renders a wrapping DOM legend (when shown) whose keyboard-operable buttons
-  toggle dataset visibility. The DOM surface preserves long public labels that a canvas legend
+- `withoutLegend: boolean = false` (attribute `without-legend`, reflected) — the legend shows by
+  default; set this to hide it. Renders a wrapping DOM legend (when shown) whose keyboard-operable
+  buttons toggle dataset visibility. The DOM surface preserves long public labels that a canvas legend
   would clip. Its pressed state follows `hiddenDatasets` whenever that controlled snapshot is
   defined, otherwise the effective dataset's declarative `hidden` value before Chart.js is ready
   and across chart type/plugin rebuilds.
@@ -104,8 +130,6 @@ property).
   by radar/polar-area are out of scope)
 - `withoutAnimation: boolean = false` (attribute `without-animation`, reflected) — disables Chart.js
   construction animation; reduced-motion preference also disables it regardless of this value
-- `withoutLegend: boolean = false` (attribute `without-legend`, reflected) — hides the legend;
-  it wins over the positive `legend` alias
 - `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
@@ -138,6 +162,14 @@ property).
   ignored without evaluating script or exposing prototype-pollution keys to the merge.
 - `showDataTable: boolean = false` (attribute `show-data-table`) — makes the always-available
   accessible data table visible rather than screen-reader-only
+- `dataTableToggle: boolean = false` (attribute `data-table-toggle`, new in 10.1.0) — renders a
+  localized disclosure button (`part="data-table-toggle"`) above the data table so a *sighted*
+  reader can reveal the numbers on demand. `showDataTable` alone is all-or-nothing, which left
+  consumers wrapping a duplicated table in their own `<details>`. With the toggle on,
+  `showDataTable` becomes the disclosure's **initial** state rather than its whole behavior; the
+  table stays in the DOM in both states, so assistive technology never loses it, and the button
+  carries `aria-expanded` plus `aria-controls` pointing at the `data-table` wrapper. Unset, nothing
+  renders and behavior is identical to before.
 - `chartArea: LyraChartArea | undefined` (readonly) — current Chart.js chart-area geometry in
   canvas-local coordinates (`top`, `left`, `right`, `bottom`, `width`, `height`), when a chart is
   drawn
@@ -257,7 +289,7 @@ Chart.js escape hatch and is not rewritten by the simplified-surface sampler.
 wrapping DOM legend), `legend-item` (a dataset-visibility button), `legend-item-hidden` (added to
 that button while its dataset is hidden), `legend-swatch`,
 `reset-zoom-button`, `description`, `notices` (wrapper for nonfatal feature warnings and
-bounded-alternative truncation notices), `data-table`, `data-truncation` (the bounded-alternative
+bounded-alternative truncation notices), `data-table`, `data-table-toggle` (the `dataTableToggle` disclosure button), `data-truncation` (the bounded-alternative
 notice), `feature-warning` (a nonfatal missing optional-feature warning), `center` (the
 chart-area-centered wrapper for the `center` slot), `error` (neutral visible message rendered in
 place of `canvas` when the optional `chart.js` peer dependency fails to load; the failure transition
@@ -277,7 +309,9 @@ ancestor, not a shadow-tree descendant, since custom properties only cascade dow
 `y2Label` title text reuses `--lr-chart-tick-color` too — there's no separate title-color token),
 legend text, and tooltip background/text respectively; plus
 `--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`, and
+`--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` (the
+`dataTableToggle` disclosure button), and
 `--lr-chart-reset-zoom-button-hover-bg` / `--lr-chart-reset-zoom-button-active-bg` — independent
 background hooks for each DOM control's hover and pressed states. Hover defaults to
 `--lr-color-brand-quiet`; pressed defaults to its standard active color mix. Override one pair
@@ -339,7 +373,7 @@ requested enhancement is disabled and a localized static `feature-warning` is vi
 announced. In particular, unavailable data labels do not remove generated table totals.
 
 ```html
-<lr-chart type="line" x-label="Day" y-label="kWh" legend></lr-chart>
+<lr-chart type="line" x-label="Day" y-label="kWh"></lr-chart>
 <script>
   const c = document.querySelector('lr-chart');
   c.labels = ['Mon', 'Tue', 'Wed'];
@@ -384,7 +418,7 @@ announced. In particular, unavailable data labels do not remove generated table
   off-screen, property changes that would otherwise trigger a Chart.js redraw are skipped (and a
   single redraw fires once it re-enters the viewport). Independently, `updated()` only reaches
   Chart.js when at least one of `type`, `labels`, `datasets`, `description`, `grid`, `indexAxis`,
-  `label`, `hiddenDatasets`, `legend`, `legendPosition`, `min`, `max`, `plugins`, the internal resolved auto legend
+  `label`, `hiddenDatasets`, `legendPosition`, `min`, `max`, `plugins`, the internal resolved auto legend
   position, `valueFormatter`, `formatter`, `area`, `height`, `xLabel`, `yLabel`, `y2Label`, `beginAtZero`,
   `stacked`, any `without*` control, `dataLabels`, `stackTotals`, `config`, the parsed
   slotted config, `zoom`, `locale`, `strings`, or the internal loading state actually changed in

package/llms/components/lr-chat-viewport.md

@@ -93,11 +93,16 @@ component's existing requirement of a height-bounded parent, exactly as slotted
 inline style) still wins over the built-in one.
 
 ```html
-<lr-chat-viewport unread-start-index="12" @lr-follow-change=${(e) => console.log(e.detail.following)}>
+<lr-chat-viewport unread-start-index="12">
   <lr-chat-message message-role="user">…</lr-chat-message>
   <lr-chat-message message-role="assistant" status="streaming">
-    <lr-streaming-text streaming .content=${partial}></lr-streaming-text>
+    <lr-streaming-text streaming></lr-streaming-text>
   </lr-chat-message>
 </lr-chat-viewport>
 <lr-chat-composer status="streaming"></lr-chat-composer>
+<script type="module">
+  const viewport = document.querySelector("lr-chat-viewport");
+  viewport.querySelector("lr-streaming-text").content = partial;
+  viewport.addEventListener("lr-follow-change", (e) => console.log(e.detail.following));
+</script>
 ```

package/llms/components/lr-checkbox-group.md

@@ -85,15 +85,23 @@ option layout and defaults to `--lr-checkbox-group-option-gap`.
 `--lr-checkbox-group-invalid-border` (default `var(--lr-color-danger)`) independently retints the
 invalid option-collection border without changing other danger-colored surfaces.
 
-**`value` is a readonly defensive read-out of child state, not an input.** The children are the
-single source of truth. An internal sync recomputes `value` on every child toggle, programmatic
-child `checked`/`value`/`disabled` update, `slotchange`, `name`/`required` change, blur, and
-`form.reset()`. Mutating an obtained array cannot mutate the group.
+**`value` reads as a frozen defensive snapshot of child state, and assigning it mirrors back onto
+the children.** The children remain the single source of truth. An internal sync recomputes `value`
+on every child toggle, programmatic child `checked`/`value`/`disabled` update, `slotchange`,
+`name`/`required` change, blur, and `form.reset()`. Mutating an obtained array cannot mutate the
+group — assign a new array instead.
 Only a checkbox whose nearest `lr-checkbox-group` ancestor is this group contributes; a nested
 group owns its own descendants and form entries. `connectedCallback()` runs that sync before the
 first render.
 
-- **To preselect**, set `checked` on the children: `<lr-checkbox value="a" checked>`.
+Assigning checks every child whose `value` (defaulting to `'on'`) appears in the array and unchecks
+every other one; duplicate entries check that many same-valued children, and values naming no child
+are ignored. `null`/`undefined` clear the selection. It is controlled input, so it emits no
+`lr-change` — only user interaction does. An assignment made before the children exist (the shape of
+a `.value=${...}` binding on first render) is applied once they arrive.
+
+- **To preselect**, either set `checked` on the children (`<lr-checkbox value="a" checked>`) or
+  assign the group's `value`.
 - **To read the selection**, use this property or the `lr-change` event detail.
 - **Give every child a distinct `value`.** `<lr-checkbox>`'s `value` defaults to `'on'`, so a group
   of undifferentiated children submits several identical `FormData` entries and the submitted data

package/llms/components/lr-checkbox.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 14 parts, 10 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 15 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`
 
 ---
@@ -91,7 +91,10 @@ leaves the internal role's serialized attribute empty; browsers without the refl
 API keep the string fallback. The relationship tracks host attribute changes and clears when
 unset.
 
-**CSS parts:** `form-control` (outer checkbox/error/hint frame), `base` (compatibility name for the
+**CSS parts:** `form-control` (outer checkbox/error/hint frame), `row` (the row wrapping the
+checkbox owner and the label as siblings — the node to size or align when laying out a column of
+checkboxes, since `base`/`checkbox` below is only the control box and its inline size tracks the box
+rather than the row), `base` (compatibility name for the
 semantic owner; use `checkbox`), `checkbox` (the interactive `role="checkbox"` owner; it is the
 same node as `base`, while the rich default label is its sibling),
 `box` / `control` (the small square showing the checkmark/indeterminate dash; while active it also