@aceshooting/lyra-ui 21.0.0 → 21.1.0

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

@@ -29,11 +29,17 @@ its content.
 **Properties:**
 
 - `name: string = ''` — the tool/function name, e.g. `web_search`
+- `displayName?: string` (attribute `display-name`, 21.1.0) — the application's own,
+  already-translated label for the tool (e.g. `Lecture d’un fichier`). It replaces `name` in the
+  visible `name` part and the chip's accessible name only; `lr-tool-call-chip-select` still reports
+  the raw `name`. Unset or empty shows `name`
 - `category: string = ''` — optional grouping label, e.g. `research`
-- `status: 'pending'|'running'|'success'|'error'|'denied' = 'pending'` (reflected) — drives the
-  glyph, accent color, and `status-text`; same status vocabulary as `<lr-tool-result-dialog>` so a
-  call's chip and its detail dialog always agree; unknown runtime values render the pending icon,
-  text, and accessible label instead of failing the update
+- `status: 'pending'|'running'|'success'|'error'|'denied'|'incomplete' = 'pending'` (reflected) —
+  drives the glyph, accent color, and `status-text`; same status vocabulary as
+  `<lr-tool-result-dialog>` so a call's chip and its detail dialog always agree; `incomplete`
+  (21.1.0) is a call that ended without a result (an interrupted stream, a cancelled run) and reads
+  `Incomplete` (`statusIncomplete`) with its own static glyph in the neutral `pending` tone; unknown
+  runtime values render the pending icon, text, and accessible label instead of failing the update
 - `summary: string = ''` — short human-readable status text, e.g. `Searching web…`
 - `durationMs?: number` (attribute `duration-ms`) — how long the call took, in milliseconds; the
   `duration` part is omitted entirely when unset
@@ -58,7 +64,7 @@ content — assigned content wins; otherwise the `icon` prop is rendered as a li
 the built-in glyph for the current `status` is used)
 
 **CSS parts:** `base` (the clickable `<button>`), `icon`, `label` (wrapper around `category`, `name`,
-`summary`), `category`, `name`, `summary`, `meta` (wrapper around `status-text` and `duration`),
+`summary`), `category`, `name` (the tool name, or `display-name` when set), `summary`, `meta` (wrapper around `status-text` and `duration`),
 `status-text`, `duration`, `tooltip` (the floating detail popup, only meaningful while open)
 
 **Themeable custom properties:** `--lr-tool-call-chip-spin` (default `var(--lr-transition-ambient)`,
@@ -66,7 +72,7 @@ i.e. `1.8s ease-in-out` at the shipped token value and `0.001ms linear` under
 `prefers-reduced-motion` — running-icon animation duration/timing) and `--lr-transition-ambient`
 (default `1.8s ease-in-out` — pending-icon pulse duration/timing).
 `--lr-tool-call-chip-accent`, `--lr-tool-call-chip-bg`, and `--lr-tool-call-chip-border` are public
-component hooks whose private defaults follow `status` (e.g. `pending` →
+component hooks whose private defaults follow `status` (e.g. `pending` and `incomplete` →
 `--lr-color-text-quiet`/`--lr-color-surface`/`--lr-color-border`; `running` → brand; `success` →
 success; `error` → danger; `denied` → warning). Set them on an ancestor to retheme a subtree or
 directly on one chip; either public value remains authoritative in every status. Shared tokens

package/llms/components/lr-tool-param-form.md

@@ -142,8 +142,9 @@ fired once up front at connect time and after every effective change; serializat
 publish their root message as `errors.base` and `formError`), and no-detail `focus`/`blur` events for
 generated native text/number inputs. The composed
 `<lr-select>` controls already bubble their own focus/blur bridges through the host.
-Nested control events (`input`, `change`, `lr-change`, select show/hide, and option mutation) are
-contained at the form boundary; consumers receive the single form-level `lr-input` contract.
+Nested control events (`input`, `change`, `lr-change`, the selects' `lr-show`/`lr-after-show`/
+`lr-hide`/`lr-after-hide`, and option mutation) are contained at the form boundary; consumers receive
+the single form-level `lr-input` contract.
 `lr-invalid` (no detail) is the bubbling/composed, cancelable alias emitted when the complete
 parameter form fails a native validity check; preventing it also prevents the native `invalid`
 event's default validation UI.

package/llms/components/lr-tool-result-dialog.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** 12 parts, 13 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 12 parts, 15 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`
 
 ---
@@ -39,8 +39,10 @@ title.
   cloning that name. A direct property assignment made without the attribute can name the panel
 - `toolName: string = ''` (attribute `tool-name`) — the tool's name, rendered prominently in the
   header
-- `status: 'pending'|'running'|'success'|'error'|'denied' = 'pending'` (reflected) — drives the
-  header's status badge; same status vocabulary as `<lr-tool-call-chip>`
+- `status: 'pending'|'running'|'success'|'error'|'denied'|'incomplete' = 'pending'` (reflected) —
+  drives the header's status badge; same status vocabulary as `<lr-tool-call-chip>`. `incomplete`
+  (21.1.0) is a call that ended without a result; its badge reads `Incomplete` in the neutral
+  pending look, through its own `--lr-tool-result-dialog-incomplete-*` pair
 - `durationMs?: number` (attribute `duration-ms`) — how long the call took, in milliseconds; omitted
   from the header entirely when unset
 - `maximized: boolean = false` (reflected) — near-fullscreen presentation of the same open dialog
@@ -143,5 +145,7 @@ Backdrop clicks leave the dialog open by default; add `light-dismiss` to opt in,
 - `--lr-tool-result-dialog-error-bg` — Error status background. Default: `var(--lr-color-danger-quiet)`.
 - `--lr-tool-result-dialog-denied-color` — Denied status foreground. Default: `var(--lr-color-warning)`.
 - `--lr-tool-result-dialog-denied-bg` — Denied status background. Default: `var(--lr-color-warning-quiet)`.
+- `--lr-tool-result-dialog-incomplete-color` — Incomplete status foreground (21.1.0). Default: `var(--lr-color-text-quiet)`.
+- `--lr-tool-result-dialog-incomplete-bg` — Incomplete status background (21.1.0). Default: `transparent`.
 
 ---

package/llms/components/lr-tool-result-view.md

@@ -49,7 +49,7 @@ Direction: a text fallback (`::part(fallback-text)`) uses `unicode-bidi: plainte
 - `copyable: boolean = false` (reflected) — shows a copy-to-clipboard affordance alongside the
   fallback view, for either `fallback` kind: forwarded to `<lr-json-viewer>`'s own `copyable` for
   `"json"`, or a `<lr-copy-button>` rendered next to the text for `"text"`.
-- `status: 'pending'|'running'|'success'|'error'|'denied' = 'success'` (reflected) — the outcome of
+- `status: 'pending'|'running'|'success'|'error'|'denied'|'incomplete' = 'success'` (reflected) — the outcome of
   the currently-rendered result, as reported by the matched renderer's own `context.reportStatus()`
   (see below). Reset to `'success'` immediately before every `render()` call, so a renderer that
   never calls `reportStatus` — including every pre-existing 2-arg renderer written before this
@@ -131,8 +131,9 @@ DirectToolRendererDefinition }>` and `render?: never` — lazy loader
 **`ToolRenderContext`** — the shape of `render()`'s 3rd argument:
 
 - `reportStatus: (status: ToolResultStatus) => void` — reports this render's outcome without
-  throwing. `ToolResultStatus` is `'pending' | 'running' | 'success' | 'error' | 'denied'`, the same
-  union `<lr-tool-result-dialog>`/`<lr-tool-call-chip>` use, re-exported from this module. Calling
+  throwing. `ToolResultStatus` is `'pending' | 'running' | 'success' | 'error' | 'denied' |
+  'incomplete'`, the same union `<lr-tool-result-dialog>`/`<lr-tool-call-chip>` use, re-exported
+  from this module. Calling
   it is entirely optional: a renderer that never calls it leaves `<lr-tool-result-view>`'s `status`
   property at its default, `'success'`. This threads through the lazy `load()` path exactly the
   same way — a `render()` resolved via `load()` receives the same 3rd `context` argument as one

package/llms/components/lr-tool-timeline.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** 17 parts, 13 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 17 parts, 14 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`
 
 ---
@@ -22,9 +22,9 @@ primitives, with retry counts and sensitive-field redaction.
 **Properties:**
 
 - `entries: readonly ToolTimelineEntry[] = []` (attribute: false) — `ToolTimelineEntry` **extends
-  `ToolInvocation` from `@aceshooting/lyra-ui/ai`** (`{ id: string; name: string; args:
-Record<string, unknown>; status: ToolCallStatus; result?: unknown; error?: string }`, where
-  `ToolCallStatus = 'pending' | 'running' | 'success' | 'error' | 'denied'`) with `{ startedAt?:
+  `ToolInvocation` from `@aceshooting/lyra-ui/ai`** (`{ id: string; name: string; displayName?:
+string; args: Record<string, unknown>; status: ToolCallStatus; result?: unknown; error?: string }`, where
+  `ToolCallStatus = 'pending' | 'running' | 'success' | 'error' | 'denied' | 'incomplete'`) with `{ startedAt?:
 number; endedAt?: number; retryCount?: number; redactedFields?: readonly string[]; needsApproval?: boolean;
 approved?: boolean; sourceKey?: string; icon?: string }`. `sourceKey` identifies the owning run or
   source generation when invocation ids can be reused; every expansion, activation, renderer error,
@@ -32,7 +32,12 @@ approved?: boolean; sourceKey?: string; icon?: string }`. `sourceKey` identifies
   are omitted; a blank optional `sourceKey` is treated as absent. Duplicate occurrences of the same
   pair are normalized before any lookup with a deterministic first-occurrence-wins policy. `icon` is a
   literal hint forwarded to the composed tool-call chip. A foreign runtime `status` normalizes once
-  to `pending` before both the timeline row and its composed chip render.
+  to `pending` before both the timeline row and its composed chip render. `displayName` (21.1.0),
+  the application's own translated tool label, is forwarded to the chip's `displayName` and names
+  the entry's details disclosure (`Details for Lecture d’un fichier`); an empty, omitted or
+  non-string value shows `name`. `name` still selects the result renderer, is still the `toolName`
+  in `lr-tool-render-error`, and still names the tool in the approval dialog, so the reviewer
+  authorizes the exact tool.
   Timestamps are epoch milliseconds; entries sort ascending by `startedAt`,
   and an entry with none sorts after every timed entry (keeping its relative position among other
   untimed ones) and renders no visible timestamp. `startedAt`+`endedAt` derive the `durationMs`
@@ -113,6 +118,8 @@ per-entry timeline marker dot's size, which also sets the entry grid's leading c
 `status="denied"` entry, decoupled from the pending-approval border color below so either can be
 retinted independently; `--lr-tool-timeline-pending-marker-color` (default
 `var(--lr-color-text-quiet)`) — rail-dot color for a `status="pending"` entry;
+`--lr-tool-timeline-incomplete-marker-color` (21.1.0, default `var(--lr-color-text-quiet)`) —
+rail-dot color for a `status="incomplete"` entry, independent of the pending one;
 `--lr-tool-timeline-pending-approval-border-color` (default
 `var(--lr-color-warning)`) — color of the entry body's leading border while that entry's
 `data-pending-approval` is `"true"`.

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

@@ -9,358 +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** 28 parts, 26 custom properties — see this component's own `@csspart`/`@cssprop` list below
-- **Documented with** `lr-tree` (same section below)
+- **Themeable via** 28 parts, 26 custom properties — see `lr-tree.md`
+- **Documented with** `lr-tree`: see [lr-tree.md](./lr-tree.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
-
----
-
-## `lr-tree` / `lr-tree-item`
-
-An expand/collapse hierarchy (document/graph navigation tree). Mirrors `wa-tree`/`wa-tree-item` and
-`sl-tree`/`sl-tree-item`.
-
-An otherwise unnamed data row receives its stable `id` as a semantic name. Usable `accessibleLabel`,
-visible label, description, badge content and explicit host naming retain precedence; the fallback
-changes neither visible content nor installed data. Blank visible labels remain supported.
-Declarative items receive no automatic ID fallback.
-
-**Renamed in 8.0.0 — breaking:** the child element is `<lr-tree-item>` (class `LyraTreeItem`), not
-`<lr-tree-node>`/`LyraTreeNode`. It was the only child element in the library whose tag diverged
-from both upstreams, so `wa-tree-item`/`sl-tree-item` markup had nothing to rename to. The shared
-data types moved to `tree-types.ts` to free the name and are still re-exported from `tree.js`. A
-leftover `<lr-tree-node>` is an unregistered tag: it never
-upgrades, `<lr-tree>` does not count it as an item at all, and the tree renders its empty state
-with the stale markup sitting inert in the light DOM — no error anywhere.
-
-**9.0 type/API cleanup:** rename the structured-data type `TreeItem` to `LyraTreeNodeData`, use
-`LyraVariant` for `TreeBadge.tone` instead of `TreeBadgeTone`, and replace a singular `badge` value
-with `badges: [{ text: String(value) }]`. The former item-controller fields (`activeId`, `ancestry`,
-`depth`, `setSize`, `posInSet`) and context setters were never consumer state; they are now private
-owner context maintained by `<lr-tree>`.
-
-**Two child models are accepted, and they never interleave.**
-
-- **Declarative** (mirrors the upstream markup, so a tag rename is the whole migration): write
-  nested `<lr-tree-item>` elements as light-DOM children, each carrying its own
-  `label`/`expanded`/`disabled`/`selected` attributes. `<lr-tree-item>` moves its nested children
-  onto an internal `children` slot itself, so you never write `slot=`.
-- **Data**: leave `<lr-tree>` empty and assign `data`, a `LyraTreeNodeData[]` of plain objects. This is this
-  library's own original shape and is where per-row icons, secondary descriptions and badges live —
-  the declarative model has none of those. `<lr-tree>` creates and reconciles the
-  `<lr-tree-item>` children by `id`, and each item renders its own subtree into its own shadow root.
-  Every reachable `LyraTreeNodeData.id` must be nonblank and globally unique. Malformed rows and
-  later duplicates are omitted before rendering; the first valid depth-first occurrence wins
-  and cannot receive focus, selection, expansion, or reorder requests. Supplying unique refreshed
-  data releases that fail-closed state.
-
-A tree containing any author-written `<lr-tree-item>` child is read purely as the declarative model
-and `data` is ignored. The empty state renders only when neither model has any items.
-
-Both child models use the same selection, roving-focus, checkbox-cascade, icon, and lazy-loading
-engine. The upstream lifecycle names are normalized to the library-wide `lr-` prefix;
-`lr-node-toggle` and `lr-node-select` remain as additive Lyra notifications. In multiple modes the
-tree role explicitly exposes `aria-multiselectable="true"` (and explicit `"false"` otherwise),
-while each treeitem host is the sole selected/checked/mixed semantic owner; checkbox-shaped chrome
-is decorative and cannot duplicate the row's accessible name.
-
-### `lr-tree`
-
-Implements the full WAI-ARIA treeitem keyboard pattern: a single owner-controlled roving `tabindex`
-across every reachable `<lr-tree-item>` and
-ArrowUp/Down/Right/Left/Home/End/Enter/Space handled by one delegated `keydown` listener (native
-`KeyboardEvent`s are `composed: true` and bubble across shadow-DOM boundaries, so a press inside a
-deeply-nested node's own shadow root still reaches it).
-
-**Properties:**
-
-- `data: readonly LyraTreeNodeData[] = []` (attribute: false) — the object child model; ignored
-  while any author-written `<lr-tree-item>` child is present. Assignment installs a detached,
-  recursively frozen snapshot: mutate caller data only before assignment, then reassign after
-  changes. Normalization accepts at most 1,000 valid nodes and 64 descendant levels, and lazily
-  inspects at most 10,000 root/child array positions globally in depth-first order. It never
-  invokes caller accessors and exposes `dataTruncated = true` when malformed or over-budget input
-  was omitted or the inspected-position ceiling was reached. Collapsed branches do not instantiate descendants; disclosure projects only normalized
-  children while `aria-setsize` preserves the declared sibling count. `LyraTreeNodeData` is
-  `{ readonly id: string; readonly label: string; readonly children?: readonly LyraTreeNodeData[];
-readonly selected?: boolean; readonly disabled?: boolean; readonly lazy?: boolean; readonly
-badges?: readonly TreeBadge[]; readonly icon?: unknown; readonly description?: string; readonly
-accessibleLabel?: string }`. `TreeBadge` is `{ readonly text: string; readonly tone?:
-LyraVariant; readonly label?: string }`. `badges` renders tone-mapped chips in order. A nonempty
-  `label` makes that chip a named `img`; when the override is omitted or empty, no generic role or
-  redundant `aria-label` is added and the visible `text` contributes to the treeitem name naturally.
-  `icon` renders as a decorative leading visual, `description` as secondary visible row text, and
-  `accessibleLabel` names the `role="treeitem"` host without changing its visible label. An
-  author-supplied host `aria-label` takes precedence by presence and is never overwritten or
-  removed by later object refreshes; removing the author attribute restores the current data name.
-  `id` is the event, roving-focus, reconciliation, and reorder identity and must be unique across
-  the complete reachable hierarchy; malformed rows, blank IDs and later duplicates are omitted as described above
-- `selection: 'single'|'multiple'|'leaf'|'leaf-multiple' = 'single'` — self-managed selection for
-  both child models. `single` selects one item; `leaf` selects one loaded leaf; `multiple` displays
-  checkboxes and cascades through enabled descendants; `leaf-multiple` applies that cascade only
-  to leaves. Partially-selected branches expose `indeterminate`
-- `label: string = ''` — accessible-name fallback for the tree; `role="tree"` lives on an internal
-  `[part="base"]` element. A host `aria-label` takes precedence by attribute presence, including an
-  explicit empty string; removing it restores the `label` fallback. External `aria-labelledby`
-  idrefs are not forwarded across the shadow boundary.
-- `reorderable: boolean = false` (reflected) — opts into keyboard reordering. Unset, no `lr-reorder`
-  is ever emitted, Ctrl/Cmd+Arrow behaves exactly like a plain Arrow press, and the internal live
-  region is not rendered at all.
-
-**Read-only getters:** `selectedItems: readonly LyraTreeItem[]` returns a new frozen snapshot of
-selected item elements in document order, including derived fully-selected parents in either
-multiple mode. `dataTruncated: boolean` reports bounded/malformed normalization as described above.
-
-**Keyboard:** ArrowDown/ArrowUp move the roving focus to the next/previous _visible_ node.
-ArrowRight expands a collapsed node (focus stays put; a second ArrowRight then steps into the first
-child) or moves into an already-expanded node's first child. ArrowLeft collapses an expanded node, or
-moves focus to its parent. Home/End jump to the first/last visible node. Enter/Space activate
-`select()` on the focused node. While `reorderable`, **Ctrl/Cmd**+ArrowUp/ArrowDown moves the focused
-node within its own parent's child list instead of navigating. Ctrl/Cmd rather than Alt: Alt+Arrow is
-browser back/forward on Windows and Linux. ArrowUp/ArrowDown are not direction-sensitive, so this
-binding is deliberately **not** RTL-swapped — "down" always means later in the sibling list.
-If a same-id data refresh disables an expanded branch, that reused branch collapses immediately;
-enabled descendants are never left visibly stranded outside this navigation walk.
-
-**`inert` excludes an item and its whole subtree from that walk, exactly as `disabled` does.**
-`role="treeitem"` and the roving `tabindex` both live on the `<lr-tree-item>` host itself, so an
-inert item literally refuses `focus()` — stepping the roving index onto one would leave focus behind
-on `<body>` and kill every later arrow press. Marking the focused item inert therefore moves the
-roving stop to the next reachable row instead of stranding it, and the state is observed live
-(`attributeFilter: ['selected', 'disabled', 'inert', 'lazy']`). Two deliberate limits:
-
-- **Only inertness _inside_ the tree counts** — the item's own `inert`, or that of an ancestor item
-  between it and the `<lr-tree>`. An inert ancestor _outside_ the tree (the page behind an open
-  modal) inerts every item uniformly, and excluding them all would empty the walk, null out
-  `activeId`, and leave the tree with no `tabindex="0"` stop for anything to restore once the dialog
-  closes. That case needs no handling: focus cannot be inside the tree at all.
-- **Selection ignores it.** An inert subtree is temporarily non-interactive, not deselected, so
-  `selectedItems` and the multiple-mode cascade are unchanged and a modal that inerts the page can
-  never silently wipe a tree's selection.
-
-**Methods:** `expandAll(): Promise<void>`, `collapseAll(): Promise<void>` (both iterative, bounded,
-and resolved only after the affected rendered item cascade settles).
-
-**Events:** `lr-selection-change` (`detail: { selection }`, where both the detail and selection
-snapshot are frozen) and `lr-reorder` (`detail: { nodeId, parentNodeId, fromIndex, toIndex }`, only while `reorderable`).
-Like every other event here it is a **request**: `data` is host-owned and is never mutated by this
-component, so nothing moves until the host reassigns a reordered `data` — focus then follows the
-moved node. The live region likewise announces a completed move only after the rendered sibling
-order confirms the exact requested swap. Ignored or rejected requests stay silent, and unrelated
-updates do not prematurely discard an asynchronously persisted request. `parentNodeId` is `null` for a
-top-level item, and `fromIndex`/`toIndex` are **sibling-scoped
-indices**, not positions in the flattened visible list. The move is constrained to one sibling list
-and never fires at a subtree boundary, so a reorder can never become a reparent: Ctrl+ArrowDown on
-the last child of a subtree is ambiguous (the visually next row is a top-level uncle, so "move down"
-could mean either "swap with the next sibling" — there is none — or "reparent up a level"), and
-reparenting is a structural edit with no keyboard affordance distinguishing the two. Such a request
-is simply not made: no event, no announcement, focus stays put. Item events listed below bubble
-through the tree as well.
-
-**Slots:** default — top-level `<lr-tree-item>` elements, each nesting its own children (the
-declarative model). Leave it empty and assign `data` for the object model; the same slot then holds
-the items `<lr-tree>` generates. `expand-icon` and `collapse-icon` provide tree-wide disclosure
-icons; an item-level slot with the same name takes precedence.
-
-**CSS parts:** `base` and `tree` are aliases on the same `role="tree"` root; `empty` is the
-empty-state message shown when neither child model has any items.
-
-**Themeable custom properties:** shared tokens `--lr-space-xs`/`-s`, `--lr-color-brand-quiet`,
-`--lr-color-text-quiet`, `--lr-color-border`, `--lr-color-border-subtle`, `--lr-color-text`,
-`--lr-radius`, `--lr-focus-ring-*` (row `:focus-visible` ring, driven by `:host(:focus-visible)`
-since the host itself is the focusable `role="treeitem"`), plus `--indent-size`, `--indent-guide-color`,
-`--indent-guide-offset`, `--indent-guide-style`, and `--indent-guide-width`.
-
-**Optional peer deps:** none.
-
-### `lr-tree-item`
-
-One row of the tree, in either child model. `role="treeitem"` (plus
-`aria-expanded`/`aria-level`/`aria-setsize`/`aria-posinset`/`aria-selected` and the roving
-`tabindex`, driven by `<lr-tree>`) live on the _host_ element itself, not an internal row `<div>` —
-so this node's own nested children (whether rendered in its own shadow root or projected from the
-light DOM, as further `role="group"` content) are genuine DOM descendants of the treeitem, matching
-the WAI-ARIA treeitem pattern's containment expectation.
-
-**Properties — declarative model** (write these as attributes; `item` data seeds the matching state
-when assigned):
-
-- `label: string = ''` — the row's label, used only when nothing is slotted into the default slot
-- `disabled: boolean = false` (reflected) — removes the item from roving focus and blocks
-  select/toggle activation
-- `selected: boolean = false` (reflected) — renders the selected state and is exposed as
-  `aria-selected`
-- `lazy: boolean = false` (reflected) — defers expansion, renders the spinner, and emits
-  `lr-lazy-load` until children arrive or `lazy` is cleared
-
-**Properties — data model:**
-
-- `item?: LyraTreeNodeData` (attribute: false) — the whole subtree as one object, normally assigned by
-  `<lr-tree>` from its `data`. An assigned `item` **wins** for label/disabled/children and seeds
-  `selected`/`lazy`; a refreshed object identity re-seeds those values. Light-DOM children are
-  ignored while `item` is assigned. Outside an owning tree, an omitted `item.selected` leaves
-  `aria-selected` off the host; an owning tree always publishes explicit true/false state. Assign
-  `undefined` to return safely to the declarative model and reset data-seeded selected/lazy state
-
-**Properties — shared:**
-
-- `expanded: boolean = false` (reflected)
-- `loading: boolean` (read-only) — a lazy expansion is waiting for children
-- `indeterminate: boolean` (read-only) — an enabled branch has some but not all selectable
-  descendants selected
-
-**Read-only getters** — each answers for whichever child model is in use, which is what lets
-`<lr-tree>` drive both with one implementation:
-
-- `nodeId: string` — this item's identity: `item.id` in the data model, or a generated per-element
-  id in the declarative one (where the markup carries no id of its own). It is the `nodeId` every
-  `lr-node-toggle` / `lr-node-select` / `lr-reorder` detail carries, and what the tree tracks its
-  roving tabindex by
-- `isDisabled: boolean` — `item.disabled` in the data model, the `disabled` property in the
-  declarative one
-- `nodeLabel: string` — this item's spoken name, used for the tree's reorder announcements: a host
-  `aria-label` is authoritative in both models
-  (including the component-owned stable-ID fallback for otherwise unnamed data rows); otherwise `item.accessibleLabel || item.label` in
-  the data model, or flattened accessibility-visible slotted label text (nested items excluded)
-  followed by the `label` fallback in the declarative one. Direct and forwarding-slot
-  text/ARIA/visibility mutations update the name
-- `hasChildren: boolean` — whether this node has at least one child in whichever model is in use.
-  Leaf nodes never expose `aria-expanded` and cannot expand or collapse. It also reports `false`
-  past the owner controller's 64-level bound, which stops runaway recursion; cyclic object graphs
-  are detected by private ancestry identity
-
-**Methods:** `expand()`, `collapse()` (each a no-op if already in that state, disabled, loading, or a leaf),
-`select()` (fires `lr-node-select`; a no-op while disabled), and host `click()` (forwards exactly
-once to the same selection path and is likewise disabled-gated). `childItems(): LyraTreeItem[]` returns
-this node's **direct** child `<lr-tree-item>` elements — from its own shadow root in the data model,
-from its own light-DOM children in the declarative one. A grandchild is not included; it lives under
-its own parent. `getChildrenItems({ includeDisabled = true } = {})` is the upstream-compatible
-public spelling over the same direct-child list.
-
-**Events:** `lr-node-toggle` (`detail: { nodeId, expanded }`, fired by `expand()`/`collapse()` — via
-the toggle button or ArrowRight/ArrowLeft), `lr-node-select` (`detail: { nodeId }`, fired by `select()`
-— via clicking anywhere in the row or Enter/Space) — dispatched from `lr-tree-item`,
-bubble/compose up through `lr-tree`'s light DOM. `lr-expand`/`lr-collapse` fire when a transition
-begins; `lr-after-expand`/`lr-after-collapse` fire after the matching themeable duration. Rapid
-opposite transitions and disconnects invalidate stale after-events. Collapse keeps the subtree
-mounted through its real opacity animation and removes it only when the animation completes;
-reduced motion settles immediately, and duration parsing is finite/nonnegative/timer-capped.
-`lr-lazy-load` requests data
-with `detail: { item, generation }`; `lr-lazy-change` reports `detail: { item, loading }` when the
-pending state starts or ends. Disabling or disconnecting an item invalidates the pending generation.
-
-**Slots:** default — the row's label content in the declarative model. `children` — where nested
-`<lr-tree-item>` children are projected; **assigned by the component**, so write the nested items in
-the default slot and never set `slot="children"` yourself. `expand-icon` and `collapse-icon`
-override the owning tree's corresponding icon for one item. The label/children slots are unused in
-the data model.
-
-Visual slot selection is separate from `nodeLabel` extraction: flattened element-only and visible
-`aria-hidden` content still chooses the authored slot instead of the `label` fallback, while hidden
-content is omitted from the spoken name. Host `aria-label` remains authoritative by presence.
-
-**CSS parts:** `base` and `tree-item` are aliases on the same outer wrapper around the row and child
-group; `row`, `toggle`, `icon`, `content`, `label`, `description`, `badge`, `group`, `item`,
-`item--disabled`, `item--expanded`, `item--indeterminate`, `item--selected`, `indentation`,
-`expand-button`, `spinner`, `spinner__base`, `children`, `checkbox`, `checkbox__base`,
-`checkbox__control`, `checkbox__control--checked`, `checkbox__control--indeterminate`,
-`checkbox__checked-icon`, `checkbox__indeterminate-icon`, and `checkbox__label`. `badge`
-is applied to every `item.badges` chip; chips carry
-`data-tone="neutral|brand|success|warning|danger"`. `icon` is `aria-hidden="true"`; `content`
-groups the primary label and optional wrapping secondary description while preserving one
-interactive treeitem per row. `icon`, `description` and `badge` render only in the data model —
-the declarative model has no icon/description/badge inputs, so a row written as markup renders
-`row`/`toggle`/`content`/`label` (and `group` while expanded) and nothing else.
-`item` and its four state aliases are real painted row containers: consumer background, border,
-padding, and opacity rules reach the visible row rather than a boxless wrapper.
-The enabled disclosure `toggle` has its own pointer-hover feedback in addition to the row's hover
-treatment; disabled toggles remain visually inert.
-In the data model, every recursively rendered child forwards this complete part list under the
-same names, so one selector on the outer item, such as `lr-tree-item::part(row)`, reaches matching
-parts at every rendered depth. Declarative children remain light-DOM hosts and can be matched
-directly as `<lr-tree-item>` elements.
-
-**Themeable custom properties:** `--indent-size` (default `var(--lr-space-l)`, applied once per
-nesting depth), `--indent-guide-color` (default `var(--lr-color-border-subtle)`),
-`--indent-guide-offset` (default `0`, the guide's block-axis inset at both ends),
-`--indent-guide-style` (default `solid`), and `--indent-guide-width` (default `0`); these mirrored
-properties are consumed directly by every `<lr-tree-item>` and may be set on an item or inherited
-from `<lr-tree>`. `--lr-tree-depth` is internal and set inline per row for indentation;
-`--show-duration`/`--hide-duration` both default through `--lr-duration-base`;
-`--lr-tree-selected-color` and `--lr-tree-selected-bg` for the selected row; and paired
-`--lr-tree-checkbox-checked-border-color`, `--lr-tree-checkbox-checked-bg`,
-`--lr-tree-checkbox-checked-color`, `--lr-tree-checkbox-indeterminate-border-color`,
-`--lr-tree-checkbox-indeterminate-bg`, and `--lr-tree-checkbox-indeterminate-color` independently
-theme the two multiple-selection checkbox states (brand border/background and on-brand glyph
-fallbacks). The selected-row background is also the base its hover/press mixes from, and each
-checkbox border token also paints that state's border under the pointer; and paired
-`--lr-tree-badge-{neutral|brand|success|warning|danger}-color` /
-`--lr-tree-badge-{neutral|brand|success|warning|danger}-bg` properties for each badge tone. Each
-badge property falls back to its corresponding shared semantic token. The expanded names are
-`--lr-tree-badge-neutral-color`, `--lr-tree-badge-neutral-bg`, `--lr-tree-badge-brand-color`,
-`--lr-tree-badge-brand-bg`, `--lr-tree-badge-success-color`, `--lr-tree-badge-success-bg`,
-`--lr-tree-badge-warning-color`, `--lr-tree-badge-warning-bg`, `--lr-tree-badge-danger-color`,
-and `--lr-tree-badge-danger-bg`.
-
-**Optional peer deps:** none.
-
-The data model — icons, descriptions and badges live here:
-
-```html
-<lr-tree></lr-tree>
-<script>
-  document.querySelector("lr-tree").data = [
-    {
-      id: "1",
-      label: "Root",
-      description: "Two child documents",
-      accessibleLabel: "Root, two child documents",
-      icon: document.createTextNode("◇"),
-      children: [
-        { id: "1a", label: "Child A" },
-        { id: "1b", label: "Child B", badges: [{ text: "3" }] },
-      ],
-    },
-  ];
-</script>
-```
-
-The declarative model — the same shape a renamed `wa-tree`/`sl-tree` subtree lands in, with no
-`slot=` anywhere and no `data` assignment:
-
-```html
-<lr-tree label="Documents">
-  <lr-tree-item label="Root" expanded>
-    <lr-tree-item label="Child A"></lr-tree-item>
-    <lr-tree-item label="Child B" disabled></lr-tree-item>
-  </lr-tree-item>
-</lr-tree>
-```
-
-**Known gotchas:**
-
-- all four previously-known ARIA gaps in this pair are fixed: the treeitem row is now genuinely
-  keyboard-operable with a roving tabindex and full arrow-key navigation (not just the expand/collapse
-  button); the expanded-children `role="group"` is now a real DOM descendant of its `role="treeitem"`
-  host rather than a shadow-DOM sibling; by-id reconciliation (preserving `expanded` state across
-  data reassignment) now applies at every depth via a keyed `repeat()`, not just depth 0; and
-  `role="tree"` now has an accessible name via the new `label` property.
-- `lr-tree`'s `getUpdateComplete()` cascades through owner-controlled descendants
-  `<lr-tree-item>`'s own `updateComplete` (see `update-cascade.ts`) so that code awaiting the
-  tree's `updateComplete` does not run before a reachable nested node has finished rendering its
-  roving `tabIndex`. The same 64-level/1,000-node work bounds apply to context, focus, selection,
-  and disclosure walks.
-- row enrichment is intentionally structured rather than an unrestricted renderer: use `icon`,
-  `label`, `description`, `badges`, and `accessibleLabel`. This keeps the host as the single
-  `role="treeitem"` interaction target and preserves the APG keyboard model.
-- `lr-file-tree` does **not** forward `reorderable`, and deliberately so: its `LyraTreeNodeData[]` is derived
-  from `nodes` on every render and keyed by filesystem path, an order it does not own.
-- in the declarative model, appending a child while the parent is collapsed still registers: a
-  `childList` MutationObserver assigns the `children` slot and requests an update, because
-  `slotchange` alone cannot see a child added to a slot that is not currently rendered. Editing a
-  label in place is picked up the same way.
-- a declarative row whose default slot holds only whitespace around its nested items still shows the
-  `label` attribute — indentation does not count as slotted label content, which is what makes the
-  common `<lr-tree-item label="…">` + nested-children shape render its label.
-
----

package/llms/index.md

@@ -5,9 +5,13 @@
 296 custom elements, grouped by the source family they live in.
 
 **Reading one component.** Its reference file path is derived from the tag — no search needed:
-`llms/components/<tag>.md` (e.g. `llms/components/lr-table.md`). Each is self-contained: import
-path, optional peers, properties, events, slots, CSS parts, themeable custom properties, a usage
-snippet, and known gotchas — a few hundred tokens instead of the whole catalog.
+`llms/components/<tag>.md` (e.g. `llms/components/lr-table.md`): import path, optional peers,
+properties, events, slots, CSS parts, themeable custom properties, a usage snippet, and known
+gotchas — a few hundred tokens instead of the whole catalog. A tag documented together with
+siblings (e.g. `lr-combobox` / `lr-option`) still gets its own generated facts (import path,
+class, status, deprecations, optional peers), but the properties, events, slots, usage snippet,
+and gotchas live once in the primary sibling's file; the secondary tag's file carries a one-line
+pointer to it instead of a duplicated copy.
 
 **Importing.** Registration paths are stable aliases derived from the tag:
 `import '@aceshooting/lyra-ui/components/lr-table.js';` registers `<lr-table>` and remains
@@ -236,7 +240,7 @@ Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.m
 - `lr-xml-viewer` · lr-xml-viewer.js · `stable` since `4.0.0` — collapsible, copyable, `DOMParser`-based tree view for XML documents, mirroring `lr-json-viewer`'s UX (`collapsed-depth`, `copyable`, str...
 - `lr-document-compare` · lr-document-compare.js · `stable` since `4.1.0` — side-by-side or inline comparison of two document versions, composed entirely from two existing primitives rather than reimplementing eit...
 - `lr-geojson-viewer` · lr-geojson-viewer.js · `stable` since `9.0.0` — document-registry bridge rendering a fetched GeoJSON file through `<lr-map>`'s `dataLayers`.
-- `lr-geojson-view` · lr-geojson-view.js · `stable` since `4.0.0` — Permanent compatibility class for the pre-v9 `lr-geojson-view` tag.
+- `lr-geojson-view` · lr-geojson-view.js · `stable` since `4.0.0` — Deprecated compatibility class for the pre-v9 `lr-geojson-view` tag.
 
 ## Conversation & chat UI — `components/conversation/` (34)
 
@@ -346,3 +350,17 @@ Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.m
 - `lr-claim-evidence` · lr-claim-evidence.js · `stable` since `7.0.0` — a controlled claim-by-claim grounding audit.
 - `lr-retrieval-compare` · lr-retrieval-compare.js · `stable` since `7.0.0` — a side-by-side retrieval/reranking workbench that makes rank, overlap, and dense/sparse/rerank/final score changes inspectable.
 - `lr-rag-eval-dashboard` · lr-rag-eval-dashboard.js · `stable` since `7.0.0` — a controlled RAG quality overview with current metric cards, per-metric trends, evaluation slices, and run history.
+
+## Deprecated package exports
+
+These package entry points and exported types still work but are deprecated. Each names its
+replacement and the earliest release that may remove it, under the deprecation policy in
+`llms/shared.md`.
+
+- **Deprecated entry point** `@aceshooting/lyra-ui/components/lr-geojson-view.js` since `21.1.0`; use entry point `import '@aceshooting/lyra-ui/components/lr-geojson-viewer.js';`; removal not before `23.0.0` — This tag-shaped route registers the deprecated lr-geojson-view alias (and, through it, lr-geojson-viewer). Import the lr-geojson-viewer route instead; this one keeps working unchanged through the 22.x line.
+- **Deprecated entry point** `@aceshooting/lyra-ui/components/viewers/geojson-view/geojson-view.class.js` since `21.1.0`; use entry point `import { LyraGeoJsonViewer } from '@aceshooting/lyra-ui/components/viewers/geojson-view/geojson-viewer.class.js';`; removal not before `23.0.0` — This route exists for the deprecated LyraGeojsonView alias class and its event map; its re-exports of LyraGeoJsonViewer and its types duplicate the canonical geojson-viewer class route. Import from that route instead; this one keeps working unchanged through the 22.x line.
+- **Deprecated entry point** `@aceshooting/lyra-ui/components/viewers/geojson-view/geojson-view.js` since `21.1.0`; use entry point `import '@aceshooting/lyra-ui/components/viewers/geojson-view/geojson-viewer.js';`; removal not before `23.0.0` — This route registers the deprecated lr-geojson-view alias and, as a side effect, lr-geojson-viewer. Import the geojson-viewer route to register the canonical tag alone; this one keeps working unchanged through the 22.x line.
+- **Deprecated entry point** `@aceshooting/lyra-ui/utilities/localization.js` since `21.1.0`; use entry point `import { bridgeLyraLocale, resolveLyraScopedString, subscribeLyraLocale } from '@aceshooting/lyra-ui/localization.js';`; removal not before `23.0.0` — The side-effect-free localization.js entry now re-exports every binding of this route (bridgeLyraLocale, resolveLyraScopedString, subscribeLyraLocale and the LyraLocaleBridgeOptions/LyraLocaleBridgeCleanup types), identical at runtime and in type, so one entry point carries the whole application-facing locale runtime. Changing the import specifier is the entire migration; this route keeps working unchanged through the 22.x line.
+- **Deprecated type** `DocumentFile` from `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js` since `21.1.0`; use type `import type { LyraDocumentFile } from '@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js';`; removal not before `23.0.0` — LyraDocumentFile is the structurally identical interface under the library's prefixed type naming, and each is assignable to the other. Exported signatures keep the unprefixed name until the removal, so no existing signature changes in a minor release.
+- **Deprecated type** `DocumentRendererDefinition` from `@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js` since `21.1.0`; use type `import type { LyraDocumentRendererDefinition } from '@aceshooting/lyra-ui/components/viewers/document-viewer/registry.js';`; removal not before `23.0.0` — LyraDocumentRendererDefinition is the same union under the library's prefixed type naming. Exported signatures keep the unprefixed name until the removal, so no existing signature changes in a minor release.
+- **Deprecated type** `LyraGeojsonViewEventMap` from `@aceshooting/lyra-ui/components/viewers/geojson-view/geojson-view.class.js` since `21.1.0`; use type `import type { LyraGeoJsonViewerEventMap } from '@aceshooting/lyra-ui/components/viewers/geojson-view/geojson-viewer.class.js';`; removal not before `23.0.0` — The event contract of the deprecated lr-geojson-view alias is exactly LyraGeoJsonViewerEventMap under a second name. The alias type keeps resolving to it, from this route and the package root, through the 22.x line.