@aceshooting/lyra-ui 9.1.1 → 11.0.0

package/llms/components/lr-checkpoint.md

@@ -56,6 +56,10 @@ assigned to `animation-duration` alone. The spinner stops outright under
 `prefers-reduced-motion: reduce`.
 
 ```html
-<lr-checkpoint checkpoint-id="ck_18" label="Before refactor" .timestamp=${t}
-  @lr-restore=${(e) => restoreTo(e.detail.checkpointId)}></lr-checkpoint>
+<lr-checkpoint checkpoint-id="ck_18" label="Before refactor"></lr-checkpoint>
+<script type="module">
+  const checkpoint = document.querySelector("lr-checkpoint");
+  checkpoint.timestamp = t;
+  checkpoint.addEventListener("lr-restore", (e) => restoreTo(e.detail.checkpointId));
+</script>
 ```

package/llms/components/lr-combobox.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** 27 parts, 20 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 29 parts, 20 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-option` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -24,6 +24,24 @@ An `lr-option` row remains bounded by its owning listbox: the default label elli
 `start`/`end` (or `prefix`/`suffix`) adornment is capped at 40% of the row. Unbroken metadata
 therefore cannot widen a 320px LTR or RTL picker.
 
+**Adornments in the popup (fixed in 10.1.0).** Before 10.1.0 this paragraph described behavior the
+code did not have: `lr-combobox` builds its popup from normalized row *data* rather than from the
+light-DOM nodes, so a slotted `start`/`end`/`prefix`/`suffix` adornment had nowhere to land and
+simply never rendered — the documented slots and their documented parts were both dead inside the
+one component `lr-option` exists to feed. They now render. The nodes are **cloned** into the row
+(`option-start` / `option-end` parts, inert and `aria-hidden`, so they never join the option's
+accessible name), which means the author's own `<lr-option>` subtree is left exactly where they put
+it rather than being moved into a shadow root as a side effect of opening a dropdown:
+
+```html
+<lr-combobox label="Country">
+  <lr-option value="fr"><lr-flag slot="start" country="fr"></lr-flag>France</lr-option>
+  <lr-option value="mt"><lr-flag slot="start" country="mt"></lr-flag>Malta</lr-option>
+</lr-combobox>
+```
+
+An async `source` row can carry the same two fields (`start`, `end`) alongside its existing `icon`.
+
 ### `lr-combobox`
 
 **Properties:**
@@ -90,8 +108,21 @@ therefore cannot widen a 320px LTR or RTL picker.
   mapped IDLs `inputmode` and `enterkeyhint` delegate to the corresponding camel-case native
   properties
 - `inputValue: string` — the live filter input text; programmatic writes are event-silent
-- `maxOptionsVisible: number = 3` (attribute `max-options-visible` — caps how many selected tags
-  show before collapsing to `+N`)
+- `maxOptionsVisible: number = 3` (attribute `max-options-visible` — caps how many selected **tags**
+  show before collapsing to `+N`; nothing to do with the suggestion list, see the three-caps note
+  below)
+- `visibleOptions?: number` (attribute `visible-options`, new in 10.1.0) — bounds the popup to about
+  this many suggestion rows, leaving the rest reachable by scrolling. Purely presentational: every
+  row is still rendered. Measured from where row N actually starts rather than computed from a
+  token, because a row's height varies with `sub` lines, adornments and group labels. Unset imposes
+  no bound of its own and the listbox keeps exactly its previous max-height behavior; zero,
+  negative, and non-finite values normalize to unset rather than collapsing the popup
+
+**The three caps, which are easy to confuse.** `visibleOptions` caps how many suggestion rows are
+*visible* (presentation; the rest scroll). `maxRender` caps how many suggestion rows are *rendered
+at all* (performance; the rest do not exist and are summarized by `option-overflow`).
+`maxOptionsVisible` caps how many *selected tags* show in multi-select and never touches the
+suggestion list.
 - `emptyText?: string` (attribute `empty-text`) — omission displays localized `noMatches` (`"No
 matches"` in the built-in English locale); any supplied string, including `''`, renders verbatim
 - `loadingText?: string` (attribute `loading-text`) — shown while a `source` fetch is in flight;
@@ -154,9 +185,12 @@ every selection change and a `form.reset()` — like a native control, only anot
 **8.0 migration:** the former camel-case string property `autoCorrect` is not retained as a public
 alias. Set the boolean `autocorrect` IDL, or use `autocorrect="on"` / `autocorrect="off"` in markup.
 
-`ComboboxSourceRow = { readonly value: string; readonly label: string; readonly sub?: string; readonly icon?: unknown; readonly badge?: string |
+`ComboboxSourceRow = { readonly value: string; readonly label: string; readonly sub?: string; readonly icon?: unknown; readonly start?: unknown;
+readonly end?: unknown; readonly badge?: string |
 number; accessibleLabel?: string; data?: unknown; dotColor?: string; group?: string; disabled?:
-boolean }` — the row shape used by the async `source` path. `icon` renders as a decorative leading
+boolean }` — the row shape used by the async `source` path. `start` and `end` (new in 10.1.0) are
+the async counterparts of `<lr-option>`'s `start`/`end` adornment slots and render as the
+`option-start` / `option-end` parts, inert and aria-hidden exactly like `icon`. `icon` renders as a decorative leading
 visual whose rendered subtree stays visible but is inert and hidden from assistive technology;
 put independent actions outside it. `badge` renders as trailing metadata, `accessibleLabel` can
 provide richer spoken text than the visible label, and `data` is retained without being rendered
@@ -264,7 +298,9 @@ adornment-slot wrappers, each `hidden` while nothing is slotted into it), `tags`
 `lr-emoji-picker` so one rule styles every grouped list; it labels the `role="group"` wrapper here),
 `option`,
 `option-dot` (the leading status dot, when a row's `dotColor` is set), `option-icon` (the inert,
-aria-hidden decorative leading visual for an async row), `option-label`, `option-sub` (a row's
+aria-hidden decorative leading visual for an async row), `option-start` and `option-end` (the inert,
+aria-hidden adornments cloned from the source option's `start`/`prefix` and `end`/`suffix` slots, or
+from an async row's `start`/`end`), `option-label`, `option-sub` (a row's
 secondary line, when `sub` is set), `option-badge` (an async row's trailing metadata),
 `option-overflow` (the "+N more" indicator from `maxRender`), `error`, `hint`
 
@@ -337,7 +373,10 @@ box visibly (nothing is clipped or made unreachable), so leave it unset there.
 plain-text contract even when a separate WA `label` override is present.
 
 **Events:** `lr-option-change` — bubbles when the option's label or selectable data changes so
-its parent `lr-combobox` or `lr-select` can refresh its normalized option rows.
+its parent `lr-combobox` or `lr-select` can refresh its normalized option rows. It is a private
+child-to-parent refresh signal, not a picker event: the owning `lr-combobox`/`lr-select` consumes
+it and stops it, so it never reaches a listener on the picker host (whose own contract is
+`lr-change`/`lr-input`/`change`/`input`). Listen on the `<lr-option>` itself to observe it.
 
 **Slots:** default (visible label), `start`/`end` (WA adornments), and `prefix`/`suffix` (Shoelace
 aliases). `start` and `prefix` project into one leading wrapper; `end` and `suffix` project into one
@@ -433,6 +472,6 @@ synchronous and fires no `input`/`change`/`lr-change` event.
 
 **Additional API surface:**
 
-- `part="tag-label"` — The wrapping/ellipsis-safe selected-tag label.
+- `part="tag-label"` — The selected-tag label. Kept on one line and truncated with an ellipsis at `--tag-max-size` (default `var(--lr-size-5rem)`), rather than wrapped. Note that `lr-select`'s tag of the same name defaults to `var(--lr-size-12rem)`, so the same `--tag-max-size` value yields a wider tag there.
 
 ---

package/llms/components/lr-command-palette.md

@@ -55,7 +55,10 @@ row also makes it active.
 **Events:** `lr-open`, `lr-close` (both `detail: undefined`, cancelable — fired before the
 mutation, `preventDefault()` keeps the palette in its current open state), `lr-select`
 (`detail: { command }`, fired before the command's own `onSelect` runs and before the palette
-closes).
+closes), and no-detail `focus`/`blur` events re-dispatched from the host whenever the search input
+gains or loses focus. The `focus`/`blur` bridge is new in 10.0.0: native `focus`/`blur` neither
+bubble nor cross the shadow boundary, so a host-level `el.addEventListener('focus', …)` previously
+never fired at all.
 
 **Slots:** none.
 

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

@@ -109,9 +109,13 @@ repainting everything else that reads them.
 
 ```html
 <lr-tool-call-chip status="pending"></lr-tool-call-chip>
-<lr-confirm-bar tool-name="run_shell" .args=${args}
-  @lr-approve=${(e) => run(e.detail.args)} @lr-deny=${() => cancel()}
-></lr-confirm-bar>
+<lr-confirm-bar tool-name="run_shell"></lr-confirm-bar>
+<script type="module">
+  const bar = document.querySelector("lr-confirm-bar");
+  bar.args = args;
+  bar.addEventListener("lr-approve", (e) => run(e.detail.args));
+  bar.addEventListener("lr-deny", () => cancel());
+</script>
 ```
 
 An `lr-approve`/`lr-deny` listener that needs to await its own async work before finalizing calls

package/llms/components/lr-context-meter.md

@@ -71,17 +71,18 @@ sizes a legend chip on both axes. Otherwise the component consumes shared tokens
 **Optional peer deps:** none.
 
 ```html
-<lr-context-meter
-  label="128K context window"
-  total="128000"
-  .segments=${[
-    { label: 'System prompt', value: 2200, tone: 'neutral' },
-    { label: 'Conversation history', value: 61000, tone: 'brand' },
-    { label: 'Retrieved context', value: 30800, tone: 'warning' },
-  ]}
-></lr-context-meter>
-
-<lr-context-meter shape="ring" total="128000" .segments=${segments}></lr-context-meter>
+<lr-context-meter label="128K context window" total="128000"></lr-context-meter>
+
+<lr-context-meter shape="ring" total="128000"></lr-context-meter>
+<script type="module">
+  const [meter, ringMeter] = document.querySelectorAll("lr-context-meter");
+  meter.segments = [
+    { label: "System prompt", value: 2200, tone: "neutral" },
+    { label: "Conversation history", value: 61000, tone: "brand" },
+    { label: "Retrieved context", value: 30800, tone: "warning" },
+  ];
+  ringMeter.segments = segments;
+</script>
 ```
 
 An internal visually-hidden semantic node carries `role="meter"` plus `aria-valuenow`,

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

@@ -126,13 +126,16 @@ Plus shared tokens — `--lr-space-xs/-s/-m`, `--lr-radius`,
   conversation-id="sess_123"
   label="Q3 roadmap planning"
   excerpt="Let's revisit the timeline for the launch…"
-  .timestamp=${session.updatedAt}
-  ?active=${session.id === currentSessionId}
-  @lr-select=${(e) => openSession(e.detail.conversationId)}
-  @lr-rename=${(e) => renameSession(e.detail.conversationId, e.detail.label)}
 >
   <button slot="actions" aria-label="Delete conversation">✕</button>
 </lr-conversation-item>
+<script type="module">
+  const item = document.querySelector("lr-conversation-item");
+  item.timestamp = session.updatedAt;
+  item.active = session.id === currentSessionId;
+  item.addEventListener("lr-select", (e) => openSession(e.detail.conversationId));
+  item.addEventListener("lr-rename", (e) => renameSession(e.detail.conversationId, e.detail.label));
+</script>
 ```
 
 `role="button"` lives on `[part="select-button"]`, so the row has

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

@@ -31,9 +31,22 @@ Arabic/Persian display round-trips to the same ISO value.
 Inline month-grid calendar, not form-associated (used standalone or embedded inside
 `lr-date-input`'s popover).
 
-**Properties (27):**
+**Properties (28):**
 
 - `dayContent` (JS only): `LyraDatePickerDayContent | undefined`
+- `presets: LyraDateRangePreset[] = []` (JS only, new in 10.1.0) —
+  `LyraDateRangePreset { label: string; start: string; end: string }`, where `start`/`end` are ISO
+  `YYYY-MM-DD`. Renders a `[part="presets"]` quick-range button row above the calendar, for the
+  dashboard time-filter shape (Today / Last 7 days / Last 30 days / This month / All time).
+  **Range mode only** — a preset names two dates, so it is ignored for a single-date picker rather
+  than rendering a row that cannot do anything; unset renders nothing at all. Applying one commits
+  through the same path a two-click selection uses, so the ISO serialization, the `min`/`max`
+  clamping and the `input`-then-`change` pair are identical and a consumer's change handler cannot
+  tell them apart. A reversed preset normalizes; a malformed one is ignored rather than clearing the
+  current value, so a bad entry in a config-driven list never reads as "the user picked nothing".
+  The active button carries `aria-pressed="true"` and `data-active`. Deliberately the same
+  `label`/`start`/`end` shape as `<lr-time-range>`'s `TimeRangePreset`, so the library has one
+  preset vocabulary rather than two — the only difference is the unit (ISO dates, not numbers)
 - `disabled: boolean = false` (reflected)
 - `disabledDates: string | string[] | Date[] = ''` (attribute `disabled-dates`)
 - `disabledDaysOfWeek: string = ''` (attribute `disabled-days-of-week`)
@@ -85,11 +98,13 @@ values. `lr-focus-day` carries `{ date: Date }`, and `lr-view-change` carries `{
 
 **Custom states:** `disabled`, `range`, and `readonly`.
 
-**CSS parts (35):** `date-picker` / permanent compatibility name `base` (tokens on the same
+**CSS parts (37):** `date-picker` / permanent compatibility name `base` (tokens on the same
 visible shell; both names remain supported), `day`, `day-disabled`, `day-label`, `day-outside`,
 `day-placeholder`, `day-range-end`, `day-range-inner`, `day-range-preview`, `day-range-start`,
 `day-selected`, `day-today`, `day-weekend`, `footer`, `grid`, `header`, `month`, `month-label`,
 `months`, `nav`, `next`, `previous`, `title`, `view-cell`, `view-grid`, `view-item`,
+`presets` (the quick-range row), `preset-button` (one quick-range button; carries `data-active`
+while its range is the current value),
 `view-item-disabled`, `view-item-selected`, `view-item-today`, `view-row`, `weekday`, `weekdays`,
 `weeknumber`, and `weeknumbers`. Lyra additionally retains the existing `week` part.
 
@@ -331,6 +346,11 @@ and `dateTimeFormat(locale, options)`.
   `::part(previous):hover` still wins without `!important`.
 - `--lr-date-picker-nav-active-bg` — Pressed navigation background; defaults to the hover color
   mixed by `--lr-color-mix-active`.
+- `--lr-date-picker-preset-hover-bg`, `--lr-date-picker-preset-active-bg`, and
+  `--lr-date-picker-preset-selected-bg` (new in 10.1.0) — hover, pressed, and
+  currently-selected paint for a `presets` quick-range button. Defaults are
+  `var(--lr-color-brand-quiet)`, that hover colour mixed by `--lr-color-mix-active`, and
+  `var(--lr-color-brand)` respectively.
 - `--lr-date-picker-title-hover-color`, `--lr-date-picker-title-active-color`,
   `--lr-date-picker-title-active-bg`, and `--lr-date-picker-title-active-radius` — Month-title
   hover/press paint and pressed shape; defaults to brand, brand, brand-quiet, and

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

@@ -8,7 +8,7 @@
 - **Status** `experimental` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 36 parts, 27 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 38 parts, 30 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-date-input` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -31,9 +31,22 @@ Arabic/Persian display round-trips to the same ISO value.
 Inline month-grid calendar, not form-associated (used standalone or embedded inside
 `lr-date-input`'s popover).
 
-**Properties (27):**
+**Properties (28):**
 
 - `dayContent` (JS only): `LyraDatePickerDayContent | undefined`
+- `presets: LyraDateRangePreset[] = []` (JS only, new in 10.1.0) —
+  `LyraDateRangePreset { label: string; start: string; end: string }`, where `start`/`end` are ISO
+  `YYYY-MM-DD`. Renders a `[part="presets"]` quick-range button row above the calendar, for the
+  dashboard time-filter shape (Today / Last 7 days / Last 30 days / This month / All time).
+  **Range mode only** — a preset names two dates, so it is ignored for a single-date picker rather
+  than rendering a row that cannot do anything; unset renders nothing at all. Applying one commits
+  through the same path a two-click selection uses, so the ISO serialization, the `min`/`max`
+  clamping and the `input`-then-`change` pair are identical and a consumer's change handler cannot
+  tell them apart. A reversed preset normalizes; a malformed one is ignored rather than clearing the
+  current value, so a bad entry in a config-driven list never reads as "the user picked nothing".
+  The active button carries `aria-pressed="true"` and `data-active`. Deliberately the same
+  `label`/`start`/`end` shape as `<lr-time-range>`'s `TimeRangePreset`, so the library has one
+  preset vocabulary rather than two — the only difference is the unit (ISO dates, not numbers)
 - `disabled: boolean = false` (reflected)
 - `disabledDates: string | string[] | Date[] = ''` (attribute `disabled-dates`)
 - `disabledDaysOfWeek: string = ''` (attribute `disabled-days-of-week`)
@@ -85,11 +98,13 @@ values. `lr-focus-day` carries `{ date: Date }`, and `lr-view-change` carries `{
 
 **Custom states:** `disabled`, `range`, and `readonly`.
 
-**CSS parts (35):** `date-picker` / permanent compatibility name `base` (tokens on the same
+**CSS parts (37):** `date-picker` / permanent compatibility name `base` (tokens on the same
 visible shell; both names remain supported), `day`, `day-disabled`, `day-label`, `day-outside`,
 `day-placeholder`, `day-range-end`, `day-range-inner`, `day-range-preview`, `day-range-start`,
 `day-selected`, `day-today`, `day-weekend`, `footer`, `grid`, `header`, `month`, `month-label`,
 `months`, `nav`, `next`, `previous`, `title`, `view-cell`, `view-grid`, `view-item`,
+`presets` (the quick-range row), `preset-button` (one quick-range button; carries `data-active`
+while its range is the current value),
 `view-item-disabled`, `view-item-selected`, `view-item-today`, `view-row`, `weekday`, `weekdays`,
 `weeknumber`, and `weeknumbers`. Lyra additionally retains the existing `week` part.
 
@@ -331,6 +346,11 @@ and `dateTimeFormat(locale, options)`.
   `::part(previous):hover` still wins without `!important`.
 - `--lr-date-picker-nav-active-bg` — Pressed navigation background; defaults to the hover color
   mixed by `--lr-color-mix-active`.
+- `--lr-date-picker-preset-hover-bg`, `--lr-date-picker-preset-active-bg`, and
+  `--lr-date-picker-preset-selected-bg` (new in 10.1.0) — hover, pressed, and
+  currently-selected paint for a `presets` quick-range button. Defaults are
+  `var(--lr-color-brand-quiet)`, that hover colour mixed by `--lr-color-mix-active`, and
+  `var(--lr-color-brand)` respectively.
 - `--lr-date-picker-title-hover-color`, `--lr-date-picker-title-active-color`,
   `--lr-date-picker-title-active-bg`, and `--lr-date-picker-title-active-radius` — Month-title
   hover/press paint and pressed shape; defaults to brand, brand, brand-quiet, and

package/llms/components/lr-details.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-dialog.md

@@ -93,13 +93,19 @@ chrome remains visible. The fallback order appears below.
 - `lr-request-close` — cancelable request from a built-in affordance; detail source is
   `'close-button' | 'keyboard' | 'overlay'`. Veto stops the close lifecycle. Direct `close()` and
   `hide()` calls do not emit this request event.
-- `lr-dialog-close` — cancelable, with `detail: DialogCloseReason`; emitted after `lr-hide`
+- `lr-close` — cancelable, with `detail: DialogCloseReason`; emitted after `lr-hide`. The same name
+  is already used by `<lr-tool-select-dialog>`, `<lr-tool-result-dialog>`, and
+  `<lr-tool-approval-dialog>`, whose own docs describe an identical detail shape, so one listener
+  covers all of them. A listener calling `preventDefault()` vetoes the close. Also fired (with
+  reason `'unmount'`, non-cancelable there) when the dialog is removed from the DOM while still
+  open. **But the name is not dialog-scoped** — see the target-filtering note above; nine
+  components emit `lr-close`, and several are routinely nested inside a dialog.
 
 The two `lr-after-*` events are never cancelable.
 
 The open sequence is `lr-show` → `lr-initial-focus` (when focus would move) → `lr-after-show`; the
-direct close sequence is `lr-hide` → `lr-dialog-close` → `lr-after-hide`. A built-in dismissal
-prepends `lr-request-close`. **Both state pre-events fire _before_ the state changes**, so reading
+direct close sequence is `lr-hide` → `lr-close` → `lr-after-hide`.
+A built-in dismissal prepends `lr-request-close`. **Both state pre-events fire _before_ the state changes**, so reading
 `el.open` inside an `lr-show`/`lr-hide` handler returns the _old_ value — this is the polarity
 `wa-show`/`wa-hide` already had, and the opposite of what Lyra 7.x's own `lr-show`/`lr-hide` did on
 `lr-popover`/`lr-dropdown`. The `wa-*` → `lr-*` migration table treats the rename as mechanical, and
@@ -115,8 +121,8 @@ and easing. Under `prefers-reduced-motion: reduce`, registry timing flattens to
 frame and lifecycle remain intact. Passing `null` skips native interpolation but still emits the
 matching after-event before the method promise resolves. Because dialogs now animate on close too,
 `lr-after-hide` is normally deferred by roughly one animation. A removal while open emits
-`lr-hide`, `lr-dialog-close` (reason `'unmount'`) and `lr-after-hide` in that order, none of them
-cancelable, since the element is already gone.
+`lr-hide`, `lr-close` (reason `'unmount'`) and `lr-after-hide` in that
+order, none of them cancelable, since the element is already gone.
 
 **Stacking and the top layer:** an open dialog is promoted into the browser **top layer** (via
 `popover="manual"`), new in 8.0.0. That means it escapes every ancestor stacking context and every
@@ -205,7 +211,7 @@ Otherwise shared tokens include `--lr-space-l/-m/-s`, `--lr-color-surface/-borde
   dlg.addEventListener("lr-after-show", () =>
     console.log("enter animation done")
   );
-  dlg.addEventListener("lr-dialog-close", (e) =>
+  dlg.addEventListener("lr-close", (e) =>
     console.log("closed:", e.detail)
   );
   dlg.addEventListener("lr-after-hide", () =>
@@ -288,7 +294,7 @@ if (ok) deleteConversation();
 ```
 
 `confirm(options: ConfirmOptions): Promise<boolean>` where
-`ConfirmOptions = { title: string; description?: string; confirmLabel?: string /* = 'Confirm' */; cancelLabel?: string /* = 'Cancel' */; variant?: 'neutral' | 'danger' /* = 'neutral' */; tone?: 'neutral' | 'danger' /* @deprecated, use variant */ }`.
+`ConfirmOptions = { title: string; description?: string; confirmLabel?: string /* = 'Confirm' */; cancelLabel?: string /* = 'Cancel' */; variant?: 'neutral' | 'danger' /* = 'neutral' */ }`.
 
 Resolves `true` only when the confirm button is pressed — Escape, a backdrop click, and the cancel
 button all resolve `false`. It sets `lightDismiss = true` on its transient dialog explicitly, so the
@@ -299,8 +305,8 @@ of the call and removes it once settled, rather than reusing a persistent page-l
 stack, each tied to its own returned promise. `title` becomes a direct light-DOM `<h2>`, which per `<lr-dialog>`'s
 own heading-detection also drives the dialog's accessible name; `description`, if provided, becomes
 a direct light-DOM `<p>`. `variant: 'danger'` fills the confirm button with `--lr-color-danger`
-instead of `--lr-color-brand`, for destructive actions. The deprecated `tone` option is a one-major
-back-compat alias for `variant`; `variant` wins when both are set. Confirm/cancel actions deliberately use native
+instead of `--lr-color-brand`, for destructive actions. The deprecated `tone` option that preceded
+`variant` was removed in 10.0.0. Confirm/cancel actions deliberately use native
 inline-styled `<button>` elements so this helper does not register or import the broader button
 component; every color value is still a `--lr-*` token reference, never a raw literal. They carry the same interaction
 states as every other control in the library: a hover/pressed fill mixed toward
@@ -313,7 +319,7 @@ their `data-lr-confirm-action` attribute.
 **Known gotchas:**
 
 - Every dismissal path (confirm button, cancel button, Escape, backdrop click) funnels through
-  `<lr-dialog>`'s own `close()`/`lr-dialog-close` event, so there is exactly one place that
+  `<lr-dialog>`'s own `close()`/`lr-close` event, so there is exactly one place that
   resolves the promise and tears the dialog down — a consumer never needs to (and shouldn't) call
   `.remove()` itself. Because the close event is cancelable, `confirm()` waits through the full
   dispatch and remains pending/mounted when a listener calls `preventDefault()`.

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

@@ -112,19 +112,16 @@ being dragged. Plus shared tokens `--lr-color-surface`, `--lr-color-border`, `--
 
 ```html
 <div style="position: relative; block-size: 100vh;">
-  <lr-dock-panel
-    edge="end"
-    extent="320px"
-    min-extent="200px"
-    max-extent="480px"
-    collapsible
-    @lr-resize-input=${(e) => updateLayoutPreview(e.detail.extent)}
-    @lr-resize-change=${(e) => persistExtent(e.detail.extent)}
-    @lr-collapse-change=${(e) => console.log(e.detail.collapsed)}
-  >
+  <lr-dock-panel edge="end" extent="320px" min-extent="200px" max-extent="480px" collapsible>
     <div>Sidebar content — a chat thread list, an inspector, anything.</div>
   </lr-dock-panel>
 </div>
+<script type="module">
+  const panel = document.querySelector("lr-dock-panel");
+  panel.addEventListener("lr-resize-input", (e) => updateLayoutPreview(e.detail.extent));
+  panel.addEventListener("lr-resize-change", (e) => persistExtent(e.detail.extent));
+  panel.addEventListener("lr-collapse-change", (e) => console.log(e.detail.collapsed));
+</script>
 ```
 
 Pointer-drag-resize admits only a primary pointer using its primary button, then mirrors

package/llms/components/lr-document-preview.md

@@ -154,11 +154,11 @@ entry) or a third-party PDF/office-doc viewer, but neither is a dependency of th
 
 ```html
 <lr-document-preview
+  id="text-preview"
   filename="board-notes.txt"
   mime-type="text/plain"
   src="/files/board-notes.txt"
   max-height="24rem"
-  @lr-render-error=${(e) => console.error(e.detail.error)}
 ></lr-document-preview>
 
 <!-- A host driving its own server-side conversion -->
@@ -168,6 +168,11 @@ entry) or a third-party PDF/office-doc viewer, but neither is a dependency of th
 <lr-document-preview filename="deck.pptx" mime-type="application/vnd.ms-powerpoint" src="/files/deck.pptx">
   <lr-code-block slot="unsupported" language="text">Open in PowerPoint to preview.</lr-code-block>
 </lr-document-preview>
+<script type="module">
+  document
+    .getElementById("text-preview")
+    .addEventListener("lr-render-error", (e) => console.error(e.detail.error));
+</script>
 ```
 
 Accessibility: after the initial silent baseline, entering `"converting"` without numeric

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

@@ -53,8 +53,9 @@ value, without suppressing the visible `name` heading.
 
 - `lr-close` — `detail: DocumentViewerCloseReason`, the viewer shell dialog's dismissal reason.
   The event is emitted after the viewer sets `open` to `false`. A registered renderer may compose
-  its own descendant dialog; closing that inner dialog keeps its normal `lr-dialog-close` path and
-  does not close the document viewer.
+  its own descendant dialog; closing that inner dialog keeps its own `lr-close` path — the shell
+  guards on `event.target !== event.currentTarget` — and does not close the document viewer.
+  (`<lr-dialog>`'s close event was spelled `lr-dialog-close` before 10.0.0.)
 - `lr-download` — `detail: { src, filename }`, emitted when the native safe download action is
   activated. The browser download itself is handled by the link.
 - `lr-anchor-result` — `detail: { found }`. Emitted by this shell as `{ found: false }` once per

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

@@ -19,7 +19,7 @@ A modal panel anchored to one logical edge of the viewport. `LyraDrawer` extends
 inherits the entire dialog contract unchanged: focus trapping, Escape and opt-in backdrop dismissal,
 document scroll locking, browser **top-layer** promotion, overlay stacking, accessible naming, the
 `show()`/`hide()`/`close()` methods and the whole
-`lr-show`/`lr-after-show`/`lr-hide`/`lr-after-hide`/`lr-dialog-close` lifecycle. `contained` switches
+`lr-show`/`lr-after-show`/`lr-hide`/`lr-after-hide`/`lr-close` lifecycle. `contained` switches
 to an absolute, nonmodal panel inside the nearest containing block; only that mode, `placement`, and
 the slide animation are its own.
 
@@ -50,8 +50,8 @@ the slide animation are its own.
 promise settles after the matching `lr-after-*` event.
 
 **Events:** `lr-show` (cancelable), `lr-after-show`, `lr-hide` (cancelable), `lr-after-hide`, and
-`lr-initial-focus` (cancelable), `lr-request-close` (cancelable, detail source), and
-`lr-dialog-close` (`detail: DialogCloseReason`, cancelable) — all inherited unchanged from
+`lr-initial-focus` (cancelable), `lr-request-close` (cancelable, detail source), and `lr-close`
+(`detail: DialogCloseReason`, cancelable) — all inherited unchanged from
 `lr-dialog`; see that section for details and veto rules. `lr-after-show` /
 `lr-after-hide` fire once the slide animation has finished, so they are deferred by roughly one
 animation compared with the state flip.

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

@@ -17,7 +17,7 @@
 
 A dossier card for one knowledge-graph entity: type badge, description, key/value property rows,
 degree, community chip, plus a built-in "focus in graph" action. Never fetches or focuses a graph
-itself — `lr-entity-activate` is a request a host routes into `lr-graph`'s own
+itself — `lr-entity-select` is a request a host routes into `lr-graph`'s own
 `focusNode(id, options?)`.
 
 **Properties:**
@@ -42,7 +42,7 @@ number; communityId?: string }`; field names deliberately mirror `lr-graph`'s `L
   set — there is nothing left to tighten. The exported alias `EntityCardAppearance` is retained as a
   name for the same union.
 
-**Events:** `lr-entity-activate` (`detail: { entityId }`, the built-in focus button was activated).
+**Events:** `lr-entity-select` (`detail: { entityId }`, the built-in focus button was activated).
 
 **Slots:** default (extra body content below the property rows, e.g. a `lr-neighbor-list`),
 `actions` (extra header actions alongside the built-in focus button).
@@ -75,7 +75,7 @@ from tokens.
   };
   document
     .getElementById("card")
-    .addEventListener("lr-entity-activate", (e) =>
+    .addEventListener("lr-entity-select", (e) =>
       graph.focusNode(e.detail.entityId)
     );
 </script>

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

@@ -33,7 +33,7 @@ before the type template is composed, so it never produces a leading punctuation
 `, person`. An authored host `aria-label` intentionally names only the custom-element boundary;
 it is not copied onto the shadow button because host naming does not cross that boundary.
 
-**Events:** `lr-entity-activate` (`detail: { entityId }`, click, or Enter while focused),
+**Events:** `lr-entity-select` (`detail: { entityId }`, click, or Enter while focused),
 `lr-entity-open` (`detail: { entityId }`, dblclick, or Space while focused).
 
 **Slots:** default — rich preview content (typically a compact `lr-entity-card`), shown in a

package/llms/components/lr-entity-dossier.md

@@ -53,7 +53,10 @@ shape?: 'circle' | 'square' | 'diamond' }`, the `lr-graph.nodeTypes` entry shape
   `aria-label` names the dossier as a whole and is not cloned onto the strip
 
 **Events:** declares none of its own. Every composed child's event bubbles through unmodified
-(`composed: true`): `lr-entity-activate` (`detail: { entityId, occurrenceIndex? }`), `lr-node-expand` (`detail: { nodeId }`),
+(`composed: true`): `lr-entity-select` (`detail: { entityId }`, surfaced from the embedded entity
+card or neighbor list), `lr-entity-activate` (`detail: { entityId, occurrenceIndex? }` — surfaced
+from the embedded provenance panel's own community card or relationship path strip, the only
+source carrying `occurrenceIndex`), `lr-node-expand` (`detail: { nodeId }`),
 `lr-chunk-open` (`detail: { chunkId, sourceId, anchor? }`), `lr-expand` (`detail: { chunkId, expanded }`),
 `lr-toggle` (`detail: { section, expanded }`), and `lr-tab-show`
 (`detail: { tabId: LyraEntityDossierTab }`, where `LyraEntityDossierTab = 'relationships' | 'chunks'

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

@@ -6,8 +6,8 @@
 - **Class** `LyraFileInput`, also available unregistered from `@aceshooting/lyra-ui/components/media/file-input/file-input.class.js`
 - **Family** `components/media/` — 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(file-input)`; removal not before `10.0.0` — The file-input part names the interactive picker surface; base remains on that same node during the compatibility window.
-- **Deprecated part** `label` since `8.2.3`; use part `::part(form-control-label)`; removal not before `10.0.0` — The form-control-label part follows the shared form-control vocabulary; label remains on that same node during the compatibility window.
+- **Deprecated part** `base` since `8.2.3`; use part `::part(file-input)`; removal not before `10.0.0` — The file-input part names the interactive picker surface; base remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-file-input` still publishes its own deprecated `base` part, so this alias is removed only when upstream's is.
+- **Deprecated part** `label` since `8.2.3`; use part `::part(form-control-label)`; removal not before `10.0.0` — The form-control-label part follows the shared form-control vocabulary; label remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-file-input` still publishes its own deprecated `label` part, so this alias is removed only when upstream's is.
 - **Optional peers** none
 - **Themeable via** 22 parts, 17 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`