@aceshooting/lyra-ui 5.0.0 → 5.1.0

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

@@ -0,0 +1,123 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-toast-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/toast/toast-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraToastItem`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/toast/toast-item.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-toast` (same section below)
+- **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`
+
+One per page recommended — the region.
+
+**Properties:**
+- `placement: ToastPlacement = 'top-end'` (reflected) — one of `'top-start'|'top-center'|'top-end'|
+  'bottom-start'|'bottom-center'|'bottom-end'`
+
+**Methods:** `async create(message: string, options?: ToastCreateOptions): Promise<LyraToastItem>` —
+`ToastCreateOptions = { variant?, duration?, size?, withIcon? }`
+
+**Events:** none.
+
+**Slots:** default (`<lr-toast-item>` children)
+
+**CSS parts:** `stack`
+
+**Themeable custom properties:** `--lr-toast-gap` (default `var(--lr-space-s)`),
+`--lr-toast-width` (default `28rem`) — set directly on the `<lr-toast>` element.
+
+**Optional peer deps:** none.
+
+### `lr-toast-item`
+
+A single notification.
+
+**Properties:**
+- `duration: number = 5000` (ms; `Infinity` or `<= 0` disables auto-dismiss)
+- `size: 'xs'|'s'|'m'|'l'|'xl' = 'm'` (reflected — drives both `--lr-toast-padding` and the toast's own
+  font-size via `:host([size=...])`, from a compact `xs` up to a roomier `xl`)
+- `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.
+
+**Events:** `lr-show`, `lr-after-show`, `lr-hide`, `lr-after-hide`
+
+**Slots:** default (message), `icon`
+
+**CSS parts:** `toast-item`, `accent`, `icon`, `content`, `close-button`
+
+**Themeable custom properties:** `--lr-toast-accent-width` (4px),
+`--lr-toast-show-duration`/`--lr-toast-hide-duration`
+(`var(--lr-transition-base, 180ms ease-out)` — 180ms by default, matching the JS-side show/hide
+animation timer, which is not itself reading this token), `--lr-toast-padding`
+(`var(--lr-space-m)`), `--lr-toast-font-size` (`1rem`) — both are auto-swapped per `size`, from a
+compact `xs` up to a roomier `xl` — `--lr-toast-accent-color` (defaults to `--lr-color-border`,
+auto-swapped per `variant` to `--lr-color-brand/-success/-warning/-danger`).
+
+**Optional peer deps:** none.
+
+`role` is chosen automatically per `variant`: `"alert"` for `danger`/`warning`, `"status"`
+otherwise — re-evaluated on every `variant` change, not just at first render, so reassigning
+`variant` to `danger`/`warning` after creation is announced as an interruption instead of keeping
+its original, now-stale role. 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.
+
+### `toast()`
+
+From the `toaster` controller — the ergonomic entry point, no manual `<lr-toast>` mounting
+needed:
+
+```ts
+import { toast } from '@aceshooting/lyra-ui';
+
+toast('Saved');
+toast({ message: 'Deleted', variant: 'danger', action: { label: 'Undo', onClick: (item) => {/*...*/} } });
+```
+
+`toast(input: ToastOptions | string): ToastHandle` where
+`ToastOptions = ToastCreateOptions & { message: string; placement?: ToastPlacement; action?: { label: string; onClick: (item: LyraToastItem) => void } }`,
+and `ToastHandle = { item: Promise<LyraToastItem>; dismiss: () => void }`. Lazily mounts (and
+re-mounts if removed) **one singleton `<lr-toast>` region per distinct `placement`** on
+`document.body` — a `toast()` call targeting one placement never relocates toasts already showing
+at another, since `placement` is a per-call option rather than a single global region's setting.
+
+```html
+<script type="module">
+  import { toast } from '@aceshooting/lyra-ui';
+  document.getElementById('save-btn').addEventListener('click', () => toast('Saved!'));
+</script>
+```
+
+**Known gotchas:**
+- possible nested live-region double-announcement: the stack region is
+  `role="status" aria-live="polite"` **and** each `lr-toast-item` independently self-assigns its
+  own `role` (`status`/`alert`) — nesting live regions can cause some screen readers to announce a
+  new toast twice. Plausible from the code, unverified against real AT.
+- the close button's accessible name is derived from the toast's own message text (`"Close: <first
+  40 chars>…"`, falling back to bare `"Close"` only when the toast has no text content) 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.
+- 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.
+- Prefer the `toast()` helper over manually creating `<lr-toast>`/`<lr-toast-item>` — it already
+  handles the singleton-region and remount-if-removed logic.
+
+---

package/llms/components/lr-toast.md

@@ -0,0 +1,123 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-toast`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/toast/toast.js';` (registers the tag; side-effect import)
+- **Class** `LyraToast`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/toast/toast.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-toast-item` (same section below)
+- **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`
+
+One per page recommended — the region.
+
+**Properties:**
+- `placement: ToastPlacement = 'top-end'` (reflected) — one of `'top-start'|'top-center'|'top-end'|
+  'bottom-start'|'bottom-center'|'bottom-end'`
+
+**Methods:** `async create(message: string, options?: ToastCreateOptions): Promise<LyraToastItem>` —
+`ToastCreateOptions = { variant?, duration?, size?, withIcon? }`
+
+**Events:** none.
+
+**Slots:** default (`<lr-toast-item>` children)
+
+**CSS parts:** `stack`
+
+**Themeable custom properties:** `--lr-toast-gap` (default `var(--lr-space-s)`),
+`--lr-toast-width` (default `28rem`) — set directly on the `<lr-toast>` element.
+
+**Optional peer deps:** none.
+
+### `lr-toast-item`
+
+A single notification.
+
+**Properties:**
+- `duration: number = 5000` (ms; `Infinity` or `<= 0` disables auto-dismiss)
+- `size: 'xs'|'s'|'m'|'l'|'xl' = 'm'` (reflected — drives both `--lr-toast-padding` and the toast's own
+  font-size via `:host([size=...])`, from a compact `xs` up to a roomier `xl`)
+- `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.
+
+**Events:** `lr-show`, `lr-after-show`, `lr-hide`, `lr-after-hide`
+
+**Slots:** default (message), `icon`
+
+**CSS parts:** `toast-item`, `accent`, `icon`, `content`, `close-button`
+
+**Themeable custom properties:** `--lr-toast-accent-width` (4px),
+`--lr-toast-show-duration`/`--lr-toast-hide-duration`
+(`var(--lr-transition-base, 180ms ease-out)` — 180ms by default, matching the JS-side show/hide
+animation timer, which is not itself reading this token), `--lr-toast-padding`
+(`var(--lr-space-m)`), `--lr-toast-font-size` (`1rem`) — both are auto-swapped per `size`, from a
+compact `xs` up to a roomier `xl` — `--lr-toast-accent-color` (defaults to `--lr-color-border`,
+auto-swapped per `variant` to `--lr-color-brand/-success/-warning/-danger`).
+
+**Optional peer deps:** none.
+
+`role` is chosen automatically per `variant`: `"alert"` for `danger`/`warning`, `"status"`
+otherwise — re-evaluated on every `variant` change, not just at first render, so reassigning
+`variant` to `danger`/`warning` after creation is announced as an interruption instead of keeping
+its original, now-stale role. 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.
+
+### `toast()`
+
+From the `toaster` controller — the ergonomic entry point, no manual `<lr-toast>` mounting
+needed:
+
+```ts
+import { toast } from '@aceshooting/lyra-ui';
+
+toast('Saved');
+toast({ message: 'Deleted', variant: 'danger', action: { label: 'Undo', onClick: (item) => {/*...*/} } });
+```
+
+`toast(input: ToastOptions | string): ToastHandle` where
+`ToastOptions = ToastCreateOptions & { message: string; placement?: ToastPlacement; action?: { label: string; onClick: (item: LyraToastItem) => void } }`,
+and `ToastHandle = { item: Promise<LyraToastItem>; dismiss: () => void }`. Lazily mounts (and
+re-mounts if removed) **one singleton `<lr-toast>` region per distinct `placement`** on
+`document.body` — a `toast()` call targeting one placement never relocates toasts already showing
+at another, since `placement` is a per-call option rather than a single global region's setting.
+
+```html
+<script type="module">
+  import { toast } from '@aceshooting/lyra-ui';
+  document.getElementById('save-btn').addEventListener('click', () => toast('Saved!'));
+</script>
+```
+
+**Known gotchas:**
+- possible nested live-region double-announcement: the stack region is
+  `role="status" aria-live="polite"` **and** each `lr-toast-item` independently self-assigns its
+  own `role` (`status`/`alert`) — nesting live regions can cause some screen readers to announce a
+  new toast twice. Plausible from the code, unverified against real AT.
+- the close button's accessible name is derived from the toast's own message text (`"Close: <first
+  40 chars>…"`, falling back to bare `"Close"` only when the toast has no text content) 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.
+- 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.
+- Prefer the `toast()` helper over manually creating `<lr-toast>`/`<lr-toast-item>` — it already
+  handles the singleton-region and remount-if-removed logic.
+
+---

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

@@ -0,0 +1,31 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-token-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/token-input/token-input.js';` (registers the tag; side-effect import)
+- **Class** `LyraTokenInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/token-input/token-input.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-token-input`
+
+An editable form-associated token list. Enter, comma, or blur commits a token; Backspace removes
+the last token. `value` is a `string[]` and repeated values are submitted under `name`.
+
+**Properties:** `value`, `label`, `hint`, `errorText` (`error-text`), `placeholder`, `name`,
+`required`, `disabled`, `accessibleLabel` (attribute `aria-label` — forwarded to the internal text
+input), `allowDuplicates` (`allow-duplicates`, default `false`), and `delimiter` (default `','`).
+**Slots:** `label`, `hint`, `error`.
+**Events:** `input`, `change`, `lr-add` (`detail: { value }`), and `lr-remove`
+(`detail: { value, index }`).
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `token`, `remove` (the
+per-token remove button, floored at the shared `--lr-icon-button-size` tap size around a compact
+glyph), `input`, `hint`, `error`. `focus()` and `blur()` forward to the internal text input.
+
+**Themeable custom properties:** `--lr-token-input-input-inline-size` (the editable input's
+`flex-basis` inside the wrapped token row; undeclared by default, falling back inline to
+`--lr-size-8rem`) and `--lr-token-input-min-input-inline-size` (default `--lr-size-4rem`, the floor
+that input keeps once tokens have consumed the row).

package/llms/components/lr-tool-approval-dialog.md

@@ -0,0 +1,131 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-tool-approval-dialog`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/tool-approval-dialog/tool-approval-dialog.js';` (registers the tag; side-effect import)
+- **Class** `LyraToolApprovalDialog`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-approval-dialog/tool-approval-dialog.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-tool-approval-dialog`
+
+A human-in-the-loop gate: presents one proposed tool/function call (`toolName` + `args`) and blocks an
+agent from executing it until a person explicitly approves or denies it, with an optional inline
+"edit the arguments before approving" step. First-party invention (no Web Awesome equivalent). It
+keeps its own panel template rather than nesting `<lr-dialog>`, so it has no dependency on the
+general-purpose dialog component, while its modal behavior participates in the shared overlay stack.
+
+Approve/Deny/Edit are built-in chrome, not a `footer` slot a consumer must assemble — there is exactly
+one correct action set for "approve this call". The `footer` slot is offered only for *supplementary*
+content alongside those buttons (e.g. a "remember this choice for this tool" checkbox); its content
+renders at the start of the action row, before Deny/Edit/Approve.
+
+**Exported types:**
+- `ToolApprovalDialogCloseReason = 'escape' | 'backdrop' | 'approve' | 'deny' | 'api' | string` — the
+  `lr-close` detail; `'escape'`/`'backdrop'`/`'approve'`/`'deny'` come from the dialog's own built-in
+  dismiss triggers, any other string is whatever a caller passes to `close()` directly.
+
+**Properties:**
+- `open: boolean = false` (reflected) — set this (or call `close()`) to dismiss; there is no separate
+  `show()`/`hide()` pair
+- `toolName: string = ''` (attribute `tool-name`) — the proposed call's name, e.g. `web_search`;
+  drives the heading and the dialog's accessible name
+- `args: unknown = {}` (attribute: false) — the proposed call's arguments, rendered via
+  `<lr-json-viewer>` read-only, or stringified into a `<textarea>` while editing
+- `editable: boolean = true` (reflected) — whether an "Edit" affordance is offered at all (assign
+  `false` via a PROPERTY binding, e.g. `.editable=${false}` — a `?editable=${false}`
+  boolean-attribute binding cannot override a true default). When `false`, `args` is always shown
+  read-only and can never be changed before approval.
+- `spellcheck: boolean = false`, `autocapitalize: string = 'off'`,
+  `autoCorrect: string = 'off'` (attribute `autocorrect`), `autocomplete: string = 'off'`,
+  `wrap: 'hard'|'soft'|'off' = 'soft'`, `inputMode: string = ''` (attribute `inputmode`),
+  and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the raw-JSON
+  textarea; the defaults keep browser editing assistance from changing JSON text
+- `spellcheck: boolean = false`, `autocapitalize: string = 'off'`, `autoCorrect: string = 'off'`
+  (`autocorrect`), `autocomplete: string = 'off'`, `wrap: 'hard'|'soft'|'off' = 'soft'`,
+  `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''` (`enterkeyhint`) —
+  forwarded to the raw-JSON `<textarea>` while editing.
+
+**Methods:** `close(reason: ToolApprovalDialogCloseReason = 'api'): void` — closes the dialog, emits
+`lr-close` with `reason`, and returns focus to whatever had it before the dialog opened; a no-op if
+already closed.
+
+**Events:** `lr-approve` (`detail: { args: unknown }` — the current, already-parsed arguments: the
+original `args` prop, or the user's edited-and-validated version if an edit was in progress; always
+followed by `lr-close` with reason `'approve'`), `lr-deny` (no detail — `this.emit('lr-deny')` is
+called with no second argument, so per the DOM spec's `CustomEventInit` default, `event.detail` is
+`null`, not `undefined`; always followed by `lr-close` with reason `'deny'`), `lr-close`
+(`detail: ToolApprovalDialogCloseReason` — fired exactly once per dismissal, via Escape, a backdrop
+click, the Approve/Deny buttons, or a `close()` call)
+
+**Slots:** `footer` — optional supplementary content (e.g. a "remember this choice" checkbox),
+rendered before the built-in Deny/Edit/Approve buttons.
+
+**CSS parts:** `backdrop`, `panel`, `header`, `tool-name`, `body`, `args-view`, `args-editor`, `error`,
+`footer`, `deny-button`, `edit-button`, `approve-button`
+
+**Themeable custom properties:** `--lr-tool-approval-dialog-overlay-color` (default
+`rgb(0 0 0 / 0.5)` — the backdrop scrim color; component-specific since no shared overlay token
+exists), `--lr-tool-approval-dialog-mono-font` (default `ui-monospace, SFMono-Regular, Menlo,
+Consolas, monospace` — used by both `tool-name` and the raw-JSON editor), plus shared tokens
+`--lr-space-xs/-s/-m/-l`, `--lr-color-surface`, `--lr-color-border`, `--lr-radius`,
+`--lr-shadow`, `--lr-color-brand`, `--lr-color-on-brand`, `--lr-color-danger`,
+`--lr-color-text`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
+
+**Optional peer deps:** none — internally renders `<lr-json-viewer>`, a bundled dependency of this
+package, not an optional peer.
+
+```html
+<lr-tool-approval-dialog
+  tool-name="send_email"
+  .args=${{ to: 'ops@example.com', subject: 'Deploy finished' }}
+  @lr-approve=${(e) => runTool(e.detail.args)}
+  @lr-deny=${() => console.log('denied')}
+  @lr-close=${(e) => console.log('closed:', e.detail)}
+></lr-tool-approval-dialog>
+<script type="module">
+  document.querySelector('lr-tool-approval-dialog').open = true;
+</script>
+```
+
+While `editable`, an Edit button swaps the read-only `<lr-json-viewer>` for a plain `<textarea>`
+pre-filled with `JSON.stringify(args, null, 2)`. Every keystroke re-validates with `JSON.parse` — the
+Approve button is `disabled` for as long as the current textarea content fails to parse, so a
+malformed edit can never be silently approved as either the broken text or a stale copy of the
+original args. The same button relabels to "Cancel" while editing; clicking it discards the draft
+entirely and returns to the read-only view of the *original* `args` — there is no separate "save"
+step independent of Approve itself. Both `editing` and any in-progress draft reset back to the
+read-only view every time the dialog transitions from closed to open, so a reused instance never
+leaks one proposal's half-finished edit into the next.
+
+Initial focus deliberately does *not* land on Approve: approving a tool call is a consequential,
+potentially irreversible action, so a user who opens the dialog and reflexively presses Enter/Space
+before reading anything should deny, not approve. Deny gets the initial focus instead — the same
+"focus the safe action" convention a native destructive-confirmation dialog typically follows for its
+own Cancel button. Tab/Shift+Tab are bounded to the panel's own focusable content, and
+`<lr-json-viewer>`'s internal controls plus slotted custom-element controls are found through the
+shared composed-tree focus traversal used by the other modal families.
+
+**Known gotchas:**
+- `editable` defaults to `true` and reflects — see the property note above about overriding it with a
+  property binding, not a boolean-attribute binding.
+- `lr-deny` has no detail payload: its `event.detail` is `null`, not `undefined`.
+- a consumer flipping `editable` off while an edit is already in progress automatically exits edit mode
+  and discards the draft, so an unreachable "Cancel" affordance is never left stranded on screen.
+- reconnecting the element while still `open` (e.g. a drag-and-drop reparent that keeps the same
+  instance) resumes its shared overlay registration and re-acquires the ref-counted scroll lock
+  dropped in `disconnectedCallback` — `willUpdate()` alone wouldn't otherwise notice, since
+  disconnect/reconnect fire back-to-back with no update in between.
+- the Approve button's native `disabled` attribute (while the draft is invalid JSON) automatically
+  excludes it from the shared Tab trap, whose focusable-set computation skips disabled controls.
+- the raw-JSON `args-editor` textarea always hardcodes `spellcheck="false"`, `autocapitalize="off"`,
+  and `autocorrect="off"` — not exposed as configurable properties, unlike `<lr-textarea>`'s/
+  `<lr-chat-composer>`'s passthrough props — since its content is always JSON, never prose; without
+  this a mobile browser (notably iOS Safari, which defaults textarea `autocapitalize` to
+  `'sentences'`) could auto-capitalize or auto-correct key/value text as the user edits, silently
+  corrupting the JSON.
+
+---

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

@@ -0,0 +1,101 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-tool-call-chip`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/tool-call-chip/tool-call-chip.js';` (registers the tag; side-effect import)
+- **Class** `LyraToolCallChip`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-call-chip/tool-call-chip.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-tool-call-chip`
+
+A compact inline pill representing one tool/function call an agent made mid-conversation, e.g.
+`web_search: Searching web…` with a `running` spinner. First-party invention (no Web Awesome
+equivalent). It owns no detail surface of its own — activating it (click or Enter/Space while
+focused) fires `lr-tool-call-chip-select`; a consumer wires that to opening a
+`<lr-tool-result-dialog>` (or anything else) at the call site, keeping the chip reusable wherever
+a compact call summary is useful, with or without a detail surface behind it.
+
+**Properties:**
+- `name: string = ''` — the tool/function name, e.g. `web_search`
+- `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
+- `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
+- `icon: string = ''` — literal icon hint (e.g. an emoji) rendered when the `icon` slot is empty;
+  ignored once anything is assigned to `slot="icon"`
+- `callId: string = ''` (attribute `call-id`) — unique identifier for this invocation, echoed back
+  in `lr-tool-call-chip-select`'s detail so a listener can correlate the click with the call it fired for
+
+**Events:** `lr-tool-call-chip-select` (`detail: { name: string; callId: string }`) — fired on
+click or Enter/Space activation of the pill. The deprecated `lr-tool-chip-select` alias is fired
+alongside it for one minor compatibility cycle.
+
+**Slots:** default (rich tooltip/detail content — e.g. the tool's raw arguments or a short preview —
+shown in a floating tooltip on hover/focus; nothing renders at all, no hover affordance, when this
+slot is empty), `icon` (overrides the built-in per-status glyph entirely via native slot-fallback
+content — assigned content wins; otherwise the `icon` prop is rendered as a literal hint; otherwise
+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`),
+`status-text`, `duration`, `tooltip` (the floating detail popup, only meaningful while open)
+
+**Themeable custom properties:** `--lr-tool-call-chip-spin` (default `1s linear` — 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 internal per-status variables reassigned by this component's own
+`:host([status="…"])` rules (e.g. `pending` → `--lr-color-text-quiet`/`--lr-color-surface`/
+`--lr-color-border`; `running` → brand; `success` → success; `error` → danger; `denied` → warning),
+so a page-level override loses to them for every non-default status — they are not a practical
+public theming hook. Shared tokens
+referenced: `--lr-color-text-quiet`, `--lr-color-surface`, `--lr-color-border`,
+`--lr-color-brand`/`-brand-quiet`, `--lr-color-success`/`-success-quiet`,
+`--lr-color-danger`/`-danger-quiet`, `--lr-color-warning`/`-warning-quiet`, `--lr-color-text`,
+`--lr-space-xs/-s/-m`, `--lr-radius`, `--lr-shadow`, `--lr-focus-ring-*`,
+`--lr-transition-fast`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-tool-call-chip
+  name="web_search"
+  category="research"
+  status="running"
+  summary="Searching web…"
+  duration-ms="820"
+  call-id="call_123"
+  @lr-tool-call-chip-select=${(e) => openDetail(e.detail.callId)}
+>
+  <pre slot="icon" style="display:none"></pre>
+  <code>{"query": "lyra ui components"}</code>
+</lr-tool-call-chip>
+```
+
+The default slot's tooltip is positioned with the same `internal/positioner.js` `place()` helper
+`<lr-combobox>` uses for its listbox (`placement: 'top-start'`), and appears/disappears instantly
+on hover/focus/blur/mouseleave with no fade transition and no "pointer moved into the tooltip"
+tracking — it's documented as read-only preview content, not an interactive surface meant to retain
+focus of its own. `denied` gets its own warning-toned glyph and color (a policy rejection, not a
+runtime failure) distinct from `error`'s danger tone, matching `<lr-tool-result-dialog>`'s
+identical status vocabulary so a call reads the same way in both places. Duration formatting is
+sub-1000ms `"820ms"`, else trimmed to at most one decimal of seconds (`"1.5s"`, `"2s"`).
+
+**Known gotchas:**
+- the default slot is checked for emptiness by scanning `Array.from(this.children)` for elements
+  once on first update, then kept in sync via `slotchange` — only *element* children count (a bare
+  text node assigned to the default slot won't trigger the tooltip)
+- `aria-label` on the host element (if you set one) wins over the component's own generated
+  accessible label (`"name — summary — Status — duration"`); otherwise that generated string is
+  what's announced
+- Escape only dismisses the tooltip when it's open; it does not fire any event or otherwise affect
+  `status`/`open` state, since the chip has no "open" state of its own beyond the tooltip
+
+---