@aceshooting/lyra-ui 21.0.0 → 21.1.0

package/llms/components/lr-tag.md

@@ -9,181 +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** 7 parts, 24 custom properties — see this component's own `@csspart`/`@cssprop` list below
-- **Documented with** `lr-badge` (same section below)
+- **Themeable via** 7 parts, 24 custom properties — see `lr-badge.md`
+- **Documented with** `lr-badge`: see [lr-badge.md](./lr-badge.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
-
----
-
-## `lr-badge` and `lr-tag`
-
-Compact status labels. `LyraTag` extends `LyraBadge`, so the two share one visual contract; `lr-tag`
-adds tag semantics and an optional remove affordance. Both are static text by default, matching the
-mirrored upstreams and avoiding repeated announcements when a category badge is re-rendered.
-Authors can opt a genuinely changing badge into live semantics with `role="status"`; that and every
-other author-supplied role remain authoritative across updates, hydration, and reconnect.
-
-**Visual break in 8.0.0 — a badge is no longer a pill by default.** Both components used to render
-fully-rounded ends unconditionally. `--lr-badge-radius` now defaults to `var(--lr-radius)` (a rounded
-rectangle) and the pill treatment moved behind the new opt-in `pill` boolean. Existing markup keeps
-its corner radius only if you add `pill`, or set `--lr-badge-radius: var(--lr-radius-pill)` once at
-the app level.
-
-**Properties** (all are declared by `lr-badge` and inherited by `lr-tag`; `lr-tag` adds the
-`variant="text"` spelling plus `withRemove` / `removable`):
-
-- `variant: 'neutral' | 'brand' | 'primary' | 'success' | 'warning' | 'danger' = 'neutral'`
-  (reflected) — the semantic palette. `primary` renders through the same brand palette while
-  remaining `primary` on property reads, selectors, serialization and reflection. `lr-tag`
-  additionally accepts and preserves `text`, rendering the neutral plain treatment.
-- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large' = 'm'` (reflected) — the same visual-density scale
-  `<lr-chip>` uses, for typography/padding/minimum block size; `m` preserves the original badge
-  dimensions. Both short and long upstream spellings round-trip verbatim while resolving to the
-  same private effective size for rendering.
-- `appearance: 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' = 'filled-outlined'`
-  (reflected) — **new in 8.0.0.** The second visual axis: `variant` picks the palette, `appearance`
-  decides how much of it lands on the fill, the border and the text. `filled-outlined` (the default)
-  is quiet tint + loud border + loud text, i.e. exactly the pre-8.0.0 treatment; `filled` drops the
-  border, `outlined` drops the fill, `accent` fills solidly with on-loud text, and `plain` drops both
-  fill and border while keeping the label color. The border-less appearances use a `transparent`
-  border rather than `none`, so switching appearance never changes the badge's layout box.
-- `pill: boolean = false` (reflected) — **new in 8.0.0.** Fully-rounded ends instead of the default
-  rounded rectangle; see the visual break above. Since it defaults to `false`, `pill="false"` is not
-  a way to switch it off — remove the attribute, or assign `.pill = false`.
-- `attention: 'none' | 'pulse' | 'bounce' = 'none'` (reflected) — **new in 8.0.0.** An opt-in,
-  infinitely-looping attention animation for a badge that has to be noticed: `pulse` draws an
-  expanding ring, `bounce` hops the surface vertically (block-direction, so it needs no RTL
-  mirroring). Both stop outright — not merely shorten — under `prefers-reduced-motion: reduce`.
-  The default does not materialize an attribute; an explicit `attention="none"` is authoritative
-  and suppresses the `pulse` shorthand.
-- `pulse: boolean = false` (reflected) — upstream-compatible shorthand for the pulse attention
-  treatment while the `attention` attribute is omitted. Any explicit attention value wins. Lyra's
-  intentional `variant="neutral"` and `appearance="filled-outlined"` defaults remain unchanged
-  because the two pinned upstreams disagree on both defaults.
-- `withRemove: boolean = false` (attribute `with-remove`, reflected) — **`lr-tag` only, new in
-  8.0.0.** Renders the remove affordance. `lr-badge` never renders one, even if the attribute is
-  present on the markup.
-- `removable: boolean = false` (attribute `removable`) — **`lr-tag` only.** Shoelace-compatible
-  alias for `withRemove`; reading either property reports the shared state. Either authored
-  attribute keeps removal enabled until both are absent. Assigning `false` through either property
-  clears both attributes, while assigning `true` reflects that property's own spelling.
-
-**Events:** `lr-remove` — noncancelable, no detail, bubbles and composes. Emitted by `lr-tag` only (a
-badge emits nothing at all) when the remove button is activated by click or by Enter/Space while
-focused; it is a real native `<button>`, so both come for free. Only rendered, and therefore only
-fired, while `withRemove` / `removable` is set, and the event's `target` is the tag itself.
-
-Like `<lr-chip>`, a removable `lr-tag` is controlled: activation only announces the request. The
-tag remains connected even if a listener calls `preventDefault()` (the event is not cancelable),
-and the consumer removes it by updating the collection that rendered it.
-
-If that controlled listener synchronously removes the focused tag, or a direct property write
-removes its action, focus moves to the nearest available composed action. Focus explicitly moved by
-the listener is preserved.
-
-For a removable tag, `focus(options?)`, `blur()`, and `click()` delegate to its native remove
-button. A plain tag's `click()` retains native `HTMLElement.click()` behavior and dispatches one
-host `click`; its `focus()` has no delegated target. Setting `withRemove` / `removable` false
-revokes remove-button focus and activation synchronously before the outgoing button is rerendered,
-so same-task `click()` uses the plain host behavior instead of firing `lr-remove`. `blur()` remains
-available during that same-task window so it can release the stale focused button; after render
-there is no owner to blur.
-
-**Slots:** default (the label), `start` (content before the label, typically an icon) and `end`
-(content after it) — both new in 8.0.0. Each wrapper collapses entirely (`display: none`, so no
-stray gap) while its slot is empty, and is seeded from the light-DOM children before the first
-render so declarative content never flashes hidden for a frame. Mark purely decorative slotted
-content `aria-hidden`.
-
-**CSS parts:** `base` and `badge` are aliases on the same badge/tag surface; `start` and `end` (the slot wrappers, hidden entirely
-while empty), `content` (the wrapper around the default slot — this is the part that truncates with
-an ellipsis, deliberately not `base`, so the tag's oversized remove hit target can overhang the
-compact surface without being clipped), and `remove-button` (`lr-tag` only, rendered only while
-`withRemove` / `removable`). The button also carries Shoelace's `remove-button__base` alias, so
-either part name styles the same native button.
-
-**Themeable custom properties.** Three layers, so a consumer can retune one without restating the
-others. Public hooks are consumed through private use-site defaults instead of being redeclared on
-the host, so values set directly or inherited from a theme ancestor both win. The same contract
-reaches `lr-tag` unchanged.
-
-_Overrides_ — undeclared by default, so they still inherit from a consumer's own ancestor rule, and
-win over whatever `variant`/`appearance` resolved: `--lr-badge-background` (falls back to
-`--lr-badge-fill`), `--lr-badge-border` (falls back to `--lr-badge-stroke`), `--lr-badge-color`
-(falls back to `--lr-badge-text`).
-
-_Palette — what `variant` chooses_ (new in 8.0.0): `--lr-badge-tint` (private default
-`var(--lr-color-surface)`, the quiet fill; each non-neutral variant changes that private default to
-`var(--lr-color-fill-quiet)`, which the shared variants sheet has already re-pointed at that
-variant's row of the semantic grid), `--lr-badge-solid` (private default
-`var(--lr-color-fill-loud)`, the loud fill used by `appearance="accent"`), `--lr-badge-edge`
-(private default `var(--lr-color-border-subtle)`, the border color), `--lr-badge-ink` (private default
-`var(--lr-color-text)`, the text color) and
-`--lr-badge-on-solid` (default `var(--lr-color-on-loud)`, the text color that stays legible on
-`--lr-badge-solid`). An inherited or direct public palette value remains authoritative. Neutral is
-the only variant whose border and text colors differ, which is why `-edge` and `-ink` are separate
-slots rather than one loud color.
-
-_Surface — what `appearance` routes onto the box_ (new in 8.0.0): `--lr-badge-fill` (default
-`var(--lr-badge-tint)`), `--lr-badge-stroke` (default `var(--lr-badge-edge)`) and `--lr-badge-text`
-(default `var(--lr-badge-ink)`). Set one of these to retune a single appearance without touching the
-palette.
-
-_Density and shape:_ `--lr-badge-font-size` (default `var(--lr-font-size-sm)`),
-`--lr-badge-padding-inline` (default `var(--lr-space-s)`) and `--lr-badge-min-height` (default
-`var(--lr-size-1-25rem)`) — the trio each private effective-size rule rewrites to that step's font size,
-inline padding and minimum block size; the `m` defaults above exactly reproduce the pre-`size` fixed
-badge treatment. `--lr-badge-gap` (default `var(--lr-space-2xs)`, new in 8.0.0) is the space between
-the `start` slot, the label and the `end` slot — it collapses on its own when a wrapper is empty,
-because the empty wrapper is `display: none` rather than zero-width. `--lr-badge-radius` (default
-`var(--lr-radius)`; `pill` raises it to `var(--lr-radius-pill)`) is `[part='base']`'s corner radius,
-retunable without a `::part(base)` rule and, unlike the density trio, does not vary by `size` — the
-same `--lr-button-radius` pattern.
-
-_Attention_ (all new in 8.0.0): `--lr-badge-attention-duration` (default
-`var(--lr-duration-ambient)` — one cycle of the animation), `--lr-badge-attention-easing` (default
-`var(--lr-easing-emphasized)` — kept a separate token from the duration so the `animation` shorthand
-expands to exactly one timing function), `--lr-badge-pulse-color` (default
-`color-mix(in srgb, currentColor 40%, transparent)` — the expanding ring's color; upstream alias
-`--pulse-color`),
-`--lr-badge-pulse-spread` (default `var(--lr-size-0-25rem)` — how far the ring expands) and
-`--lr-badge-bounce-distance` (default `var(--lr-size-0-1875rem)` — the hop's peak travel).
-
-_`lr-tag`'s own two_ (new in 8.0.0): `--lr-tag-remove-radius` (default `var(--lr-badge-radius)`, so
-retuning the tag's corner retunes the remove button's with it) and
-`--lr-tag-remove-hover-background` (default `color-mix(in srgb, currentColor 16%, transparent)` —
-the remove button's `:hover` fill).
-
-**Known gotchas:**
-
-- The remove button's hit target meets the shared `--lr-icon-button-size` minimum in both axes while
-  the visible glyph stays compact. Its full allocation participates in layout with no negative
-  margins, so adjacent compact tags retain disjoint targets.
-- Its accessible name is computed from the default slot's own text ("Remove {label}", localized;
-  bare "Remove" for a label-less tag) and re-derived live when that text changes. Text inside the
-  decorative `start`/`end` slots never leaks into it. Visible accessible text, forwarding-slot
-  reassignment and external assigned-node mutations stay synchronized; hidden/inert/CSS-hidden/
-  `aria-hidden` branches are excluded. A host `aria-label`, including an explicit empty value,
-  names a single aggregate `role="group"`; it is not copied to the nested action. The remove button
-  retains its purpose-specific visible-label/localized-fallback name.
-- `appearance` and `variant` are orthogonal: `appearance="plain"` on `variant="danger"` still reads
-  as danger, because the palette is chosen before the surface routing.
-
-```html
-<lr-badge variant="success" appearance="accent" pill size="s">
-  <svg slot="start" aria-hidden="true" width="12" height="12">
-    <!-- icon -->
-  </svg>
-  Live
-</lr-badge>
-
-<lr-tag variant="brand" appearance="outlined" with-remove>Design</lr-tag>
-<script type="module">
-  import "@aceshooting/lyra-ui/components/overlays/badge/badge.js";
-  import "@aceshooting/lyra-ui/components/overlays/badge/tag.js";
-
-  document.querySelector("lr-tag").addEventListener("lr-remove", (e) => {
-    e.target.remove(); // in an app, update the backing collection instead
-  });
-</script>
-```

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 41 parts, 20 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 42 parts, 20 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`
 
 ---
@@ -127,8 +127,11 @@ ancestor `--lr-positioning-strategy` still wins), and a trapped `fixed` menu ope
 outside the list, in the browser top layer where the native Popover API exists, in left-to-right
 and right-to-left documents, with no consumer CSS. A promoted menu whose trigger scrolls out of the
 list is hidden until the trigger returns. Where the Popover API is absent, the row holding an open
-`lr-dropdown` stops transforming while it is open, so its menu is still not clipped. Unset renders
-only the built-in
+`lr-dropdown` stops transforming while it is open, so its menu is still not clipped. While such a
+menu is open its row carries `row-item-base-menu-open` (see the parts below) and keeps its built-in
+hover tint. Arrow, Home and End keys a returned control already handled (`lr-menu` moving between
+its own items, a dropdown trigger opening its menu) stay with that control rather than also moving
+focus to another row. Unset renders only the built-in
 `rowActions`.
 `renderStart?: (thread: LyraChatThread) => TemplateResult` (attribute: false) — renders non-interactive
 start-side content in each virtualized row. `renderExcerpt?: (thread: LyraChatThread) => TemplateResult`
@@ -211,10 +214,30 @@ reach callback-rendered descendants through these parts). `row-excerpt` wraps `r
 output, which is slotted into the row item's own `excerpt` slot.
 
 Data mode additionally forwards each row `<lr-conversation-item>`'s own parts under a `row-item-`
-prefix: `row-item-base`, `row-item-active-indicator`, `row-item-select-button`, `row-item-start`, `row-item-content`,
+prefix: `row-item-base`, `row-item-base-menu-open`, `row-item-active-indicator`, `row-item-select-button`, `row-item-start`, `row-item-content`,
 `row-item-label`, `row-item-label-input`, `row-item-rename-button`, `row-item-excerpt`,
 `row-item-meta`, `row-item-timestamp`, `row-item-actions`.
 
+**Row menu-open state:** `row-item-base-menu-open` is carried by `row-item-base` while a menu that
+`renderActions` opened from that row (`lr-dropdown`, `lr-popover` or `lr-context-menu`) is open,
+however it was opened. That menu sits in the browser top layer, where Chromium and WebKit stop
+matching `:hover` and `:focus-within` on the row while the pointer or keyboard focus is inside it.
+A menu trigger revealed on row hover or focus must key on this state too, or it hides while its own
+menu is open — and a `display`-based reveal hides the menu with it, because an open menu is
+concealed once its trigger stops being measurable. `::part()` cannot be followed by a descendant,
+so carry the reveal to `row-actions` through an inherited custom property:
+
+```css
+lr-thread-list::part(row-item-base):hover,
+lr-thread-list::part(row-item-base):focus-within,
+lr-thread-list::part(row-item-base-menu-open) {
+  --app-row-actions-opacity: 1;
+}
+lr-thread-list::part(row-actions) {
+  opacity: var(--app-row-actions-opacity, 0);
+}
+```
+
 **Themeable excerpt highlights:** `<mark>` descendants returned by `renderExcerpt` use
 `--lr-thread-list-excerpt-highlight-background` (default `var(--lr-color-warning-quiet)`),
 `--lr-thread-list-excerpt-highlight-foreground` (default `inherit`),

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

@@ -9,124 +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** 11 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
-- **Documented with** `lr-timeline` (same section below)
+- **Themeable via** 11 parts, 8 custom properties — see `lr-timeline.md`
+- **Documented with** `lr-timeline`: see [lr-timeline.md](./lr-timeline.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
-
----
-
-## `lr-timeline` and `lr-timeline-item`
-
-Read-only chronological sequence by default. `lr-timeline` is a `role="list"` flex container; each
-`lr-timeline-item` is a light-DOM child that sets `role="listitem"` on itself and renders its own
-marker plus the trailing rail segment reaching toward the next item's marker. The last item's rail is
-suppressed purely in CSS (`::slotted([role='listitem']:last-child)`) — no JS coordination anywhere.
-Items have no keyboard navigation or selection model: a passive record display, by design (an
-item's `title`/`description` routinely hold focusable content, so wrapping the row in `role="button"`
-would trip `nested-interactive`). The opt-in clustered time scale adds only native count-marker
-buttons; it does not make the individual rows interactive.
-
-Horizontal time layouts using `collision="overlap"` or `collision="stack"` allocate their block size
-from the actual item content and lane offsets. The height follows content growth, shrinkage, and
-changes in lane count. `--lr-timeline-time-extent` still controls only the main-axis distance, and
-horizontal scrolling retains clipping on the cross axis. Cluster mode keeps its existing sizing
-behavior.
-
-**`lr-timeline` properties:** `orientation: 'vertical' | 'horizontal' = 'vertical'` — note the
-opposite default from `lr-stepper`; `horizontal` makes `[part='base']` a horizontally scrollable row.
-`accessibleLabel?: string` (attribute `aria-label`) overrides the localized `"Timeline"` name —
-omitting it reads back `undefined` and falls back to that default, while an explicitly empty
-`aria-label` stays empty
-(the `role="list"` element is in the shadow root and never inherits a host attribute). Read-only
-`itemCount: number` is the live count of default-slot `<lr-timeline-item>` assignments (including
-flattened forwarding slots); unrelated slotted elements and text nodes are ignored.
-`scale: 'flow' | 'time' = 'flow'` (attribute `scale`, type `LyraTimelineScale`) chooses how items
-are distributed along the main axis. `'flow'` is the default even sequence, where `timestamp` is
-rendered as text but carries no positional meaning. `'time'` positions each item at its true
-proportion of the range, so a gap of weeks and a gap of decades stop looking identical. `'time'`
-needs a definite extent to distribute along — `--lr-timeline-time-extent` (default
-`var(--lr-size-20rem)`), applied as `block-size` when vertical and `inline-size` when horizontal —
-because items are absolutely positioned and a percentage against an auto-sized track resolves to
-zero. `collision: 'overlap' | 'stack' | 'cluster' = 'overlap'` (attribute `collision`, type
-`LyraTimelineCollision`) chooses what `scale="time"` does with items landing on nearly the same
-position: `'overlap'` leaves them stacked on one another, `'stack'` steps each colliding item one
-lane along the **cross** axis (indent per lane: `--lr-timeline-collision-offset`, default
-`var(--lr-space-l)`), and `'cluster'` replaces every group of at least two colliding items with one
-count marker. The group's first member in author order becomes its representative and renders the
-button in that item's existing list/Tab position; the remaining members are hidden, so visual,
-semantic, and keyboard order do not diverge merely because clustering is enabled. Stack mode and
-the cluster floor treat items within 1.5% of the axis as colliding.
-Cluster mode widens that floor to the rendered count action's footprint on the currently allocated
-axis, then reclusters when the allocation or rendered action size changes, so interactive marker
-hit areas do not overlap.
-Cluster windows are bounded from their first sorted position rather than transitively chaining every
-dense neighbour, so a large history becomes a useful sequence of markers rather than one axis-wide
-cluster. An isolated item remains an ordinary timeline item. Activating a count marker is a
-notification only; it never expands or selects items internally.
-`rangeStart` / `rangeEnd` (`Date | string | number`, attribute: false) pin the axis instead of
-deriving it from the earliest/latest item; a reversed or non-finite pair falls back to the derived
-range. An item with no parseable `timestamp` (including one supplied only through the `timestamp`
-slot, which carries no machine-readable instant) keeps document order and is spread evenly, so a
-partially-timestamped list degrades rather than stacking at the origin. Reassigning an item's
-`timestamp` reclusters without requiring a slot mutation. Positions are written to
-each child as a private `--_lr-timeline-item-offset` custom property and removed again on a switch
-back to `'flow'`. Cluster mode adds and removes a private visibility marker on non-representative
-members and temporarily changes only the representative item's shadow presentation; switching
-mode, shrinking the data, or disconnecting restores every ordinary row. If regrouping would remove
-the focused row content or count action, focus moves to the replacement cluster action, the first
-surviving item action, or the timeline list as a programmatic fallback.
-
-**`lr-timeline-item` properties:** `timestamp?: Date | string | number` (attribute: false — `Date`
-isn't attribute-serializable; invalid input normalizes to unset and renders no timestamp UI),
-`sync: boolean = false` (forwarded to the internal `<lr-relative-time>`; no effect when the
-`timestamp` slot is filled), `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' =
-'neutral'` (marker tone), `active: boolean = false` (reflected — a static marker ring plus an
-optional pulse disabled under `prefers-reduced-motion: reduce`, with explicit `aria-current="true"`
-or `"false"` on the host).
-
-**Events:** `lr-timeline` emits `lr-cluster-activate` when a `collision="cluster"` marker is
-activated by pointer, Enter, or Space. Its non-cancelable, bubbling, composed
-`detail: LyraTimelineClusterActivateDetail` is `{ items: readonly LyraTimelineItem[] }`: a fresh
-frozen snapshot of the cluster members in document order, preserving each element's identity.
-`LyraTimelineClusterActivateDetail {
-  items: readonly LyraTimelineItem[];
-}`
-Use it to open a consumer-owned popover, dialog, or detail view. `lr-timeline-item` emits no events.
-Read the reactive `itemCount` property after changing assigned items; the internal slot's
-non-composed `slotchange` event is not a host-level public signal.
-
-**Slots:** `lr-timeline`'s default slot holds the items, in display order. On an item the **default
-slot is the title** (there is no `title` slot), plus `marker-icon` (marker glyph override; an empty
-slot falls back to a color-coded dot), `timestamp` (wins outright over the
-`timestamp` property whenever it has assigned content), and `description` (its part is hidden
-entirely when empty).
-
-**CSS parts:** timeline `base` — the `role="list"` flex container (no separate `list` part). Item:
-`cluster` — the native count button rendered while that item represents a cluster, with a 40px
-minimum action surface; `cluster-count` — its painted count pill; `base`, `track`
-(marker + rail spine, always the opposite axis from `base`), `marker`
-(`aria-hidden="true"`, decorative), `rail` (the connecting segment; `visibility: hidden` rather than
-removed on the last item, so marker alignment stays consistent), `content`, `header` (flex row
-wrapping `title` and `timestamp`; wraps at narrow widths rather than truncating), `title`,
-`timestamp` (hidden when there's nothing to show), `description`.
-
-**Themeable custom properties:** `--lr-timeline-gap` (default `var(--lr-space-l)`) — declared on
-`lr-timeline` but consumed inside each item via inheritance across the slot boundary; it is both the
-inter-item spacing and the length each rail bridges. `--lr-timeline-cluster-size` (default
-`var(--lr-size-2rem)`) sizes the painted count pill, `--lr-timeline-cluster-bg` (default
-`var(--lr-color-brand)`) sets its background, and `--lr-timeline-cluster-color` (default
-`var(--lr-color-on-brand)`) sets its foreground. `--lr-scroll-fade-size` (default `2rem`) controls
-each horizontal-overflow edge fade; forced-colors mode removes the masks while retaining native
-scrolling. On the item: `--lr-timeline-marker-size`
-(default `var(--lr-size-1-25rem)`, both dimensions so the dot stays circular),
-`--lr-timeline-rail-width` (default `var(--lr-border-width-medium)`), `--lr-timeline-rail-color`
-(default `var(--lr-color-border-subtle)`), `--lr-timeline-marker-color` (default
-`var(--lr-color-text-quiet)`, with a private default that changes per `variant`), and
-`--lr-timeline-active-ring-color`
-(defaults to the effective marker color). All five item hooks inherit from theme
-ancestors; setting one directly on an item wins over both the inherited value and variant default.
-
-Version 9 removes the legacy item `icon` slot; migrate marker glyphs to `slot="marker-icon"`.
-Timeline orientation/rail coordination now uses private implementation-prefixed cross-shadow
-properties. The only supported spacing input remains `--lr-timeline-gap`; stop overriding the five
-former `--lr-timeline-item-*` plumbing names.

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

@@ -9,227 +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** 12 parts, 16 custom properties — see this component's own `@csspart`/`@cssprop` list below
-- **Documented with** `lr-toast` (same section below)
+- **Themeable via** 12 parts, 16 custom properties — see `lr-toast.md`
+- **Documented with** `lr-toast`: see [lr-toast.md](./lr-toast.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
-
----
-
-## `lr-toast` / `lr-toast-item` / `toast()`
-
-Stacking toast/notification region. Mirrors `<wa-toast>`/`<wa-toast-item>` under `lr-`.
-
-### `lr-toast`
-
-A placement-specific region. The imperative helper maintains one region for each
-`ownerDocument` + `placement` pair; manually authored regions remain independent.
-
-**Properties:**
-
-- `placement: LyraToastPlacement = 'top-end'` (reflected) — one of `'top-start'|'top-center'|'top-end'|
-'bottom-start'|'bottom-center'|'bottom-end'`. Every placement resolves inside one logical usable
-  rectangle whose four edges are the greater of `--lr-space-l` and the matching safe-area token.
-  Start/end follow direction, center placements use that rectangle's midpoint even when the inline
-  safe-area insets are asymmetric, and an oversized stack is capped to its usable inline size.
-
-**Methods:** `create(options: LyraToastOptions): Promise<LyraToastItem>` is the canonical form;
-`create(message: string, options?: LyraToastCreateOptions)` remains as a compatibility overload.
-`LyraToastOptions` contains `message`, optional `placement`, `ownerDocument`, `variant`, `duration`,
-`size`, `withIcon`, `icon`, and `action`; `LyraToastCreateOptions` omits `message` and `placement`.
-`icon` accepts text, a DOM node, a Lit template, or a target-document factory returning one of
-those. Strings are always text, never HTML; cross-document nodes are imported into the region's
-document. `action` creates a native button from `{ label, onClick }`. The options' `ownerDocument`,
-and `placement`, when supplied directly to a region, must match that region. Calling `create()`
-while the region is detached rejects immediately instead of leaving a render-dependent promise pending. `size` accepts
-the canonical `2xs`/`xs`/`s`/`m`/`l`/`xl` values plus `small`/`medium`/`large`; either spelling is
-preserved by the created item's getter and reflected attribute.
-
-**Live members:** `stack: HTMLElement | null` returns the rendered `[part="stack"]` element, or
-`null` before the render root is populated. Its identity remains stable across ordinary updates and
-reconnection.
-
-The region keeps exactly three items active. Later items enter a hidden, inert FIFO queue capped at
-twenty; their show lifecycle and auto-dismiss timer do not start until promotion. Removing an active
-item promotes the oldest queued item. A visible standalone item moved into a full region is
-deactivated and timer-paused without replaying `lr-show`, then resumes from its remaining duration
-when promoted; its progress ring resumes at the same elapsed fraction as that JavaScript countdown.
-The visible stack is safe-area bounded and vertically scrollable, so all three active items and their
-controls remain keyboard-reachable even with long localized content.
-
-**Events:** `lr-toast-overflow` (noncancelable, `detail: { count: number }`) reports how many oldest
-queued items were discarded when admission exceeded the twenty-item queue. Losses in one synchronous
-burst coalesce into one event and one localized polite announcement; `create()` retains its existing
-promise/result contract.
-
-**Slots:** default (`<lr-toast-item>` children)
-
-**CSS parts:** `stack`
-
-**CSS custom states:** `visible` while at least one `lr-toast-item` is present in the region.
-
-**Themeable custom properties:** `--lr-toast-gap` (default `var(--lr-space-s)`),
-`--lr-toast-width` (default `var(--lr-size-28rem)`) — set directly on the `<lr-toast>` element.
-The mapped `--gap` and `--width` names are compatibility aliases for those two Lyra-prefixed
-properties; an explicitly set Lyra-prefixed property continues to take precedence.
-Every `<lr-toast-item>` property below is also documented on the region, because custom properties
-inherit into the items slotted inside it: one declaration on `<lr-toast>` retunes the whole stack.
-
-**Optional peer deps:** none.
-
-### `lr-toast-item`
-
-A single notification.
-
-**Properties:**
-
-- `duration: number = 5000` (ms; `Infinity` or `<= 0` disables auto-dismiss)
-- `size: '2xs'|'xs'|'s'|'m'|'l'|'xl'|'small'|'medium'|'large' = 'm'` (reflected — drives both `--lr-toast-padding` and the
-  toast's own font-size through a private effective-size mapping, from a compact `2xs` up to a roomier `xl`;
-  valid property and attribute writes round-trip without changing spelling)
-- `variant: 'brand'|'success'|'warning'|'danger'|'neutral' = 'neutral'` (reflected)
-- `withIcon: boolean = false` (attribute `with-icon`)
-
-**Methods:** `async hide(): Promise<void>` — plays the hide animation, then removes itself from the
-DOM. `toastItemElement: HTMLElement | null` exposes the live `[part="toast-item"]` surface (or
-`null` before rendering) and remains the same node across ordinary updates/reconnection.
-
-**Events:** `lr-show`, `lr-after-show`, `lr-hide`, `lr-after-hide`. `lr-show` and `lr-hide` are the
-cancelable before-transition veto points. The item stays hidden and inert throughout `lr-show`;
-vetoing its initial request releases it from the region without an after-event or timer. Re-entering
-the same show/hide request from its own before-event coalesces onto that request, so the outer veto
-remains authoritative and the lifecycle event fires once. Vetoing an auto-dismiss expiry leaves the
-item visible and restarts the full current normalized `duration`; repeated vetoes retry at that same
-interval. Vetoing a manual `hide()` leaves any active countdown at its current elapsed position. An
-accepted show or hide interrupted by disconnection resumes after reconnection and emits its matching
-`lr-after-*` event exactly once; no terminal event fires while the item is detached.
-
-**Slots:** default (message), `icon`
-
-**CSS parts:** `toast-item`, `accent`, `icon`, `content`, `close-button`, `close-icon`,
-`close-icon__svg`, `progress-ring`, `progress-ring__base`, `progress-ring__indicator`,
-`progress-ring__label`, `progress-ring__track`. The progress-ring tree is rendered for a finite,
-positive auto-dismiss duration and surrounds the close glyph; its indicator pauses alongside the
-auto-dismiss timer on hover or focus.
-
-**Themeable custom properties:** `--lr-toast-accent-width` (default `var(--lr-size-4px)`),
-`--lr-toast-show-duration`/`--lr-toast-hide-duration`
-(`var(--lr-transition-base, 180ms ease-out)` — the show/hide lifecycle reads the resolved computed
-transition duration and uses it for its completion fallback), `--lr-toast-padding`
-(`var(--lr-space-m)`) and `--lr-toast-font-size` (`var(--lr-font-size-m)`) — their private defaults
-follow `size`, from a compact `2xs` up to a roomier `xl` — and `--lr-toast-accent-color` (default
-`var(--lr-color-border)`, with a private default that follows `variant` to that variant's loud
-fill). Inherited or direct public values remain authoritative across every size and variant.
-
-`--lr-toast-item-gap` (default `var(--lr-space-s)`) controls the gap between the item's icon,
-message, and close action; `--lr-toast-item-radius` (default `var(--lr-radius)`) controls the item
-surface and accent-bar start corners. They are deliberately separate from `--lr-toast-gap`, which
-continues to control only the region's stack spacing.
-
-The close button's four inherited state hooks are `--lr-toast-close-button-hover-bg` (default
-`transparent`), `--lr-toast-close-button-hover-color` (default `var(--lr-color-text)`),
-`--lr-toast-close-button-active-bg` (default `color-mix(in oklab, transparent,
-var(--lr-color-mix-partner) var(--lr-color-mix-active))`), and
-`--lr-toast-close-button-active-color` (default `var(--lr-color-text)`). Each is an inline fallback
-at the relevant state, so setting one on the item or an ancestor rethemes only that close-button
-state rather than the item surface, other close states, or the region stack.
-
-The mapped names `--accent-width`, `--show-duration`, `--hide-duration`, and `--padding` alias their
-respective Lyra-prefixed properties. Setting the Lyra-prefixed form explicitly wins over its alias.
-
-**Optional peer deps:** none.
-
-Once a non-vetoed toast starts showing, its normalized message is appended to Lyra's pre-mounted,
-shared light-DOM announcement sink: assertive for `danger`/`warning`, polite otherwise. Changing a
-visible toast between those urgency levels announces that message at the new urgency. The visible
-item and stack themselves remain ordinary content, so an icon, action, and close button never become
-part of an atomic live announcement. Auto-dismiss timer **pauses** on `pointerenter`/`focusin`, **resumes**
-on `pointerleave`/`focusout`, with real elapsed-time bookkeeping (WCAG 2.2.1 timing-adjustable) —
-hover and focus are tracked as independent pause reasons, so releasing only one (e.g. the pointer
-leaves while focus remains, or vice versa) keeps the timer paused until _neither_ holds it anymore.
-A `duration` change while the timer is actively counting down reschedules it immediately against
-the new value instead of waiting for the next pause/resume cycle. A vetoed timer expiry restarts
-that full normalized value; if hover/focus or a disconnect begins during the veto event, the retry
-stays paused and starts from the full value only after the item resumes/reconnects.
-Accessible message extraction follows same-root `aria-labelledby` references and observes their
-targets, lookup roots, and every open shadow root actually traversed for text, including targets
-outside the toast subtree. Traversal is bounded; when a ceiling is reached, the announcement carries
-an explicit ellipsis and the close action uses the localized truncated-context template instead of
-silently treating the bounded prefix as whole. If no prefix fits before a ceiling, both surfaces use
-the localized `toastContentIncomplete` fallback so the missing content remains explicit.
-
-### `toast()`
-
-From the `toaster` controller — the ergonomic entry point, no manual `<lr-toast>` mounting
-needed:
-
-```ts
-import { toast } from "@aceshooting/lyra-ui/components/overlays/toast/toaster.js";
-
-toast("Saved");
-toast({
-  message: "Deleted",
-  variant: "danger",
-  icon: (ownerDocument) => ownerDocument.createTextNode("!"),
-  action: {
-    label: "Undo",
-    onClick: (item) => {
-      /*...*/
-    },
-  },
-});
-```
-
-`toast(input: LyraToastOptions | string): ToastHandle`, where
-`ToastHandle = { item: Promise<LyraToastItem>; dismiss: () => void }`. The canonical options are
-shared byte-for-byte with the region's object-form `create()`, including `ownerDocument`, safe icon
-payloads/factories, actions, and the long `small`/`medium`/`large` size aliases. It lazily mounts
-(and re-mounts if removed) **one singleton `<lr-toast>` region per distinct `ownerDocument` and
-`placement`** on that document's body — a call targeting one placement/document never relocates
-toasts already showing in another. A foreign document must have the toast elements registered in
-its own custom-element registry; otherwise the returned `item` promise rejects explicitly.
-
-```html
-<script type="module">
-  import { toast } from "@aceshooting/lyra-ui/components/overlays/toast/toaster.js";
-  document
-    .getElementById("save-btn")
-    .addEventListener("click", () => toast("Saved!"));
-</script>
-```
-
-**Known gotchas:**
-
-- the stack and each visible item have no live-region role. Their normalized message is appended as
-  one child of a shared non-atomic light-DOM sink at the variant's urgency; icon, action, and close
-  controls remain outside that sink. Later meaningful message changes add only the changed normalized
-  message, and appending an action does not re-announce it.
-- the close button's accessible name is derived from the toast's own message text (the first 40
-  grapheme clusters when it must be shortened, falling back to bare `"Close"` only when the toast
-  has no text content and extraction completed) rather than a bare `"Close"` on every instance — useful when several toasts
-  are stacked and a screen-reader or switch-access user needs to tell their close buttons apart
-  without activating one first. On a legacy engine without `Intl.Segmenter`, it retains the whole
-  label rather than splitting a grapheme. The localized `closeWithTruncatedContext` template owns
-  truncation punctuation and word order. Rich non-interactive message markup contributes its text,
-  named-slot/icon and actionable content do not, and live message text mutations or reassignment
-  update the name through nested forwarding slots. Hidden, inert, CSS-hidden and `aria-hidden`
-  message branches are excluded. Same-root external `aria-labelledby` targets and the open shadow
-  roots traversed for their text remain synchronized across reconnect, replacement, and adoption.
-  A bounded traversal prefix is explicitly marked as incomplete; if no prefix is available, the
-  localized `toastContentIncomplete` fallback keeps both the announcement and close name truthful.
-  Observation, animation frames, elapsed-time clocks and completion/auto-dismiss timers follow the
-  item's owner window after iframe adoption and cancel through the same window that scheduled them.
-- pause/resume-on-hover/focus (the component's main accessibility differentiator), including the
-  independent-hover-vs-focus pause reasons above, now has regression test coverage.
-- `hide()` is idempotent (a second call while already hiding is a no-op) and `[part="close-button"]`
-  gets `aria-disabled="true"` once hiding starts, so a stray extra click/Enter during the hide
-  animation can't re-enter it. A disconnect during that animation pauses completion; reconnecting
-  the same item resumes it and emits/removes exactly once.
-- When the focused close/action control's toast finishes hiding, focus moves to an adjacent toast's
-  close control, or back to the connected element that held focus before the toast when no adjacent
-  item remains.
-- Prefer the `toast()` helper over manually creating `<lr-toast>`/`<lr-toast-item>` — it already
-  handles the singleton-region and remount-if-removed logic. The helper and `lr-alert.toast()` never
-  fall back to an unbounded unknown region in an owner document where the controller is unregistered;
-  unavailable alert requests are removed and their existing `Promise<void>` settles.
-
----

package/llms/components/lr-tool-call-block.md

@@ -31,11 +31,19 @@ progress, and `No data` only for a terminal status.
 **Properties:**
 
 - `name: string = ''` — tool name; an empty name renders the localized generic `Tool call` label
+- `displayName?: string` (attribute `display-name`, 21.1.0) — the application's own,
+  already-translated label for the tool. It replaces `name` inside the localized header verb only
+  (`Used Lecture d’un fichier`), so the status wording stays localized; `name` still selects the
+  result renderer and is still reported in `lr-render-error`. Unset or empty shows `name`; a
+  `label` override replaces the whole header, this included
 - `callId: string = ''` (attribute `call-id`) — invocation id echoed in `lr-toggle` and
   `lr-render-error` details
 - `status: ToolCallStatus = 'pending'` (reflected, including the default) —
-  `'pending'|'running'|'success'|'error'|'denied'`; selects the header verb, glyph and accent.
-  Values outside the set normalize and reflect as `pending`
+  `'pending'|'running'|'success'|'error'|'denied'|'incomplete'`; selects the header verb, glyph
+  and accent. `incomplete` (21.1.0) is a call that ended without a result (an interrupted stream, a
+  cancelled run): it reads `Did not finish using {name}` (`toolCallBlockHeaderIncomplete`), or
+  `Incomplete` (`statusIncomplete`) in `status-text` beside a `label`, with a static glyph and the
+  neutral accent. Values outside the set normalize and reflect as `pending`
 - `expanded: boolean = false` (reflected) — whether the details are shown
 - `label?: string` — header override, used verbatim (including `''`); when set, the localized
   status text renders beside it in `status-text`. Unset renders the localized status verb
@@ -86,7 +94,8 @@ set), `duration` (only while finite), `body` (the disclosed region), `args`, `ar
   header/body divider
 - `--lr-tool-call-block-radius` (default `var(--lr-radius)`) — card radius
 - `--lr-tool-call-block-accent` — status glyph colour; its private default follows `status`
-  (`--lr-color-text-quiet`, then brand while running, success, danger on error, warning when denied)
+  (`--lr-color-text-quiet` while pending or incomplete, then brand while running, success, danger
+  on error, warning when denied)
 - `--lr-tool-call-block-error-color` (default `var(--lr-color-danger)`) — error section text
 
 The running glyph spins and the pending glyph pulses at `--lr-transition-ambient`; both stop under