@aceshooting/lyra-ui 5.0.0 → 5.1.0

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

@@ -0,0 +1,145 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-chat-message`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/chat-message/chat-message.js';` (registers the tag; side-effect import)
+- **Class** `LyraChatMessage`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/chat-message/chat-message.class.js`
+- **Family** `components/conversation/` — 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-chat-message`
+
+A role-based message bubble *shell* for a chat/agent conversation surface. It renders none of the
+message content itself — the default slot carries whatever a consumer wants to display (plain text,
+a `<lr-markdown>`, a custom template, anything) and this component only supplies the surrounding
+chrome: alignment/coloring by `role`, an avatar/badges header row, an optional collapse toggle, an
+attachments strip, and a status-aware footer (a live-updating status dot + text, the formatted
+`timestamp`, a built-in retry affordance for `status="failed"`, and an `actions` slot for everything
+else). No built-in copy button is rendered — slot a copy control into `actions` and fire
+`lr-copy` (`detail: { text: string }`) from it if you want one (matching `<lr-json-viewer>`'s
+and `<lr-code-block>`'s copy-affordance event name/shape, for anything listening at the
+conversation-surface level).
+
+**Properties:**
+- `role: ChatMessageRole = 'assistant'` (`'user' | 'assistant' | 'system'`) — reflects to
+  `data-role`, **not** the bare `role` attribute (those role strings aren't valid ARIA role tokens
+  and reflecting to `role` would collide with the element's own ARIA role); a plain `role="..."`
+  attribute set directly in markup is ignored entirely
+- `status: ChatMessageStatus = 'sent'` (`'sending' | 'sent' | 'failed' | 'streaming'`, reflected) —
+  drives the footer's status dot/text, `status="failed"`'s danger treatment on the bubble, and the
+  built-in retry button
+- `timestamp?: Date | string` (attribute: false) — accepts a `Date` or anything `new Date()` can
+  parse; invalid input is treated the same as unset (no timestamp rendered)
+- `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the default
+  `hour:minute` (`Intl.DateTimeFormat`, runtime locale) rendering of `timestamp`
+- `collapsible: boolean = false` (reflected) — shows the built-in collapse/expand toggle in the header
+- `collapsed: boolean = false` (reflected) — whether the message body is hidden; effective whenever
+  set, independent of `collapsible` (which only controls whether the toggle button itself is
+  rendered) — mirrors `lr-widget`'s identical `collapsible`/`collapsed` pair
+- `attachmentsPosition: 'before'|'after' = 'after'` (attribute `attachments-position`) — places the
+  `attachments` slot before or after the message body; both the visual and reading order follow it
+- `actionsOutsideBubble: boolean = false` (attribute `actions-outside-bubble`, reflected) — renders
+  the `actions` slot's content as a sibling immediately after `[part="bubble"]` instead of nested
+  inside `[part="footer"]`'s own padding/background box, for a consumer whose action row (e.g. a
+  hover-reveal copy button) must sit visually outside the bubble's chrome
+- `messageId: string = ''` (attribute `message-id`, reflected) — optional stable application id;
+  included in `lr-retry` detail when the built-in retry control is activated
+
+**Events:** `lr-retry` (`detail: { messageId?: string }`; fired by the built-in retry button, only
+rendered when `status="failed"`), `lr-collapse-toggle` (`detail: boolean`, the new `collapsed` state — fired when
+the user activates the built-in collapse button)
+
+**Slots:** default (the message body), `avatar` (an avatar/icon for the message author), `badges`
+(small status/metric chips — e.g. token count, latency, model name — entirely app-supplied), `actions`
+(action controls such as copy/retry, rendered at the end of the footer), `attachments` (file/image
+attachment chips, rendered below the message body), `failure` (only meaningful while
+`status="failed"`: host-supplied content — typically a `role="alert"` banner plus its own retry
+control — that replaces the built-in status text, retry button, and live-region announcement
+entirely; unset, `status="failed"` renders exactly as before)
+
+**CSS parts:** `bubble`, `header` (hidden entirely when nothing is in it), `avatar`, `badges`,
+`collapse-button` (only rendered when `collapsible`), `body` (hidden while `collapsed`),
+`attachments`, `footer` (hidden entirely when nothing is in it), `status-indicator` (a small
+decorative `aria-hidden` dot, absent while `status="sent"`), `status-text` (the visible text twin of
+`status-indicator`), `timestamp`, `retry-button` (only rendered when `status="failed"` and the
+`failure` slot is empty), `actions` (rendered inside the footer by default; a sibling immediately
+after `bubble` when `actionsOutsideBubble` is set), `failure` (`display: contents` wrapper for the
+`failure` slot; contributes no box when the slot is empty)
+
+**Themeable custom properties:** `--lr-chat-message-max-width` (default `80%` — the bubble's max
+inline size; component-specific, no shared width token exists), four role-scoped bubble color
+properties:
+
+- `--lr-chat-message-bubble-bg` (default `var(--lr-color-surface)`) — bubble fill for every role
+  except `user`.
+- `--lr-chat-message-bubble-color` (default `var(--lr-color-text)`) — bubble text color for those
+  same roles.
+- `--lr-chat-message-user-bubble-bg` (default `var(--lr-color-brand-quiet)`) — bubble fill for
+  `data-role="user"`.
+- `--lr-chat-message-user-bubble-color` (default `var(--lr-color-text)`) — bubble text color for
+  `data-role="user"`.
+
+Prefer these over re-pointing the shared token a default happens to reference. Overriding
+`--lr-color-brand-quiet` on the host also retints `[part='collapse-button']:hover` within this same
+component, and which shared token backs each role's fill is not a stable contract — it changed
+between 4.x and 5.0.0, which silently turned one consumer's inner-surface scrim into the whole
+bubble (near-black text on `rgba(0,0,0,0.22)`, visible only by eye). These four are that stable
+contract.
+
+Plus shared tokens `--lr-space-xs/-m`, `--lr-color-border`, `--lr-color-surface`,
+`--lr-color-brand-quiet`, `--lr-color-brand`, `--lr-color-text-quiet`, `--lr-color-danger`,
+`--lr-color-danger-quiet`, `--lr-radius`, `--lr-icon-button-size`, `--lr-focus-ring-*`,
+`--lr-transition-fast`, and `--lr-transition-ambient` (default `1.8s ease-in-out`) — the
+streaming-indicator pulse animation's cycle, the same shared compound token
+`<lr-typing-indicator>` uses.
+
+`[part=bubble]`'s background resolves through `--lr-color-surface`. If your own panel/container
+background already maps to that same token, override `[part=bubble]`'s background explicitly (e.g.
+via `::part(bubble)`) so message bubbles stay visually distinct from the surrounding panel.
+
+**Optional peer deps:** none. Internally renders a `<lr-live-region>` (a first-party sibling
+component, auto-imported alongside this one, not an npm peer) for the status-transition
+announcements described below.
+
+```html
+<lr-chat-message data-role="assistant" status="streaming">
+  <span slot="avatar">🤖</span>
+  <span slot="badges">gpt-5.4 · 1.2s</span>
+  <lr-markdown content="Here's what I found…"></lr-markdown>
+  <button slot="actions">Copy</button>
+</lr-chat-message>
+<script>
+  document.querySelector('lr-chat-message').addEventListener('lr-retry', () => resend());
+</script>
+```
+
+Accessibility of `status`: the current status is always available as plain visible text
+(`[part="status-text"]`), never color alone. A transition *to* `"failed"`, or *from* `"streaming"` to
+`"sent"` (a stream finishing), is additionally announced through the internal `<lr-live-region>` —
+`"failed"` announces assertively (`"Message failed to send."`), a streaming→sent completion announces
+politely (`"Message complete."`) — so a screen-reader user not currently focused on this message
+still learns about it. No other status transition is announced (e.g. `streaming`→`sending`, or
+`sending`→`sent` without having passed through `streaming`, produce no announcement). This differs
+from `<lr-typing-indicator>`'s deliberately simpler `role="status"` approach, appropriate there
+since that component only ever announces once (its own mount); this component's `status` can flip
+between several values across a single element's lifetime.
+
+**Known gotchas:**
+- mounting a message with `status="failed"` (or any other non-`"sent"` status) already set does
+  **not** announce anything — only a genuine *later* transition (`changed.get('status') !==
+  undefined`, i.e. not the very first update) triggers the live-region announcement.
+- `lr-retry` fires with no detail payload at all (`undefined`), not e.g. `{ status: 'failed' }`.
+- the header/footer/avatar/badges/attachments/actions wrappers are shown/hidden via the `hidden`
+  attribute, not conditional templating. Whether each slot currently has content is checked once via
+  a light-DOM children scan on the very first update (`willUpdate`, gated on `!this.hasUpdated`) and
+  thereafter only via each slot's own `slotchange` listener — content added directly with
+  `appendChild` after first paint still triggers native `slotchange`, so this works transparently,
+  but any code that manually re-parents already-slotted nodes without a real slot-assignment change
+  won't refresh the corresponding wrapper's visibility.
+- `role` intentionally reflects to `data-role`; CSS or selectors that key off role must target
+  `[data-role="user"]` etc., not `[role="user"]`.
+
+---

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

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-chat-viewport`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/chat-viewport/chat-viewport.js';` (registers the tag; side-effect import)
+- **Class** `LyraChatViewport`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/chat-viewport/chat-viewport.class.js`
+- **Family** `components/conversation/` — 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-chat-viewport`
+
+The transcript scroll container: owns stick-to-bottom behavior while an answer streams, the "jump to
+latest" pill, and the unread divider. Two supported content shapes, auto-detected: ordinary element
+children (typically `lr-chat-message`s — *slotted mode*), or exactly one `lr-virtual-list`
+(*virtual mode*, detected via `instanceof`). In virtual mode this component defers all scrolling to
+the slotted list's own `scrollToIndex()`. Follow/release state machine: while `follow` is engaged,
+content growth re-scrolls to the end; release happens only on a user-intent gesture (wheel,
+touchmove, scrollbar-drag, or PageUp/ArrowUp/Home while the log region has focus) that leaves the
+view more than `bottomThreshold` from the end — a scroll caused by this component's own programmatic
+scrolling, or by a layout shift, never releases it. Reaching the bottom again by any means re-engages
+`follow`. The internal log defaults to `live="off"`, which avoids announcing every streaming token;
+consumers that append complete messages at an announcement-safe cadence can opt into `polite` or
+`assertive`.
+
+**Properties:** `follow: boolean = true` (reflected) — component-managed stick-to-bottom state,
+host-writable: setting `true` scrolls to the end and re-engages following, setting `false` releases
+it. `bottomThreshold: number = 24` (attribute `bottom-threshold`) — px distance from the end still
+counted as "at bottom." `unreadStartIndex: number | null = null` (attribute `unread-start-index`) —
+index of the first unread item (element-child index in slotted mode, `items` index in virtual mode);
+`null` disables both the divider and the pill's unread count. `live: 'off' | 'polite' | 'assertive' =
+'off'` (reflected) — live-region policy forwarded to the internal `role="log"`; keep `off` for
+token-by-token streaming and opt in only when messages are committed at an announcement-safe cadence.
+`label: string = ''` — accessible name
+for the log region, defaults to the localized `chatViewportLabel`. `accessibleLabel: string | null =
+null` (attribute `aria-label`) — host `aria-label`, forwarded to the internal `role="log"` element
+(an `aria-label` left on the host itself names nothing, since the log role lives inside the shadow
+root); wins over `label` and the localized default.
+
+**Methods:** `scrollToBottom(options?)` — scrolls to the end and re-engages `follow`; default
+`smooth`, forced to `auto` under `prefers-reduced-motion`. `scrollToUnread(options?)` — scrolls the
+unread divider to the top of the view, resolving `false` when `unreadStartIndex` is `null`/out of
+range; does not re-engage `follow`.
+
+**Events:** `lr-follow-change` — `detail: { following }`, fired whenever `follow` flips (user
+scroll-up release, or reaching the bottom again). Never fired for the initial mount state.
+
+**Slots:** default — the transcript: ordinary element children, or exactly one `lr-virtual-list`.
+
+**CSS parts:** `base` (the positioning root), `scroll` (the scroll container, `role="log"`,
+`tabindex="0"`; in virtual mode it stops scrolling itself but keeps the role), `content` (the
+slotted-content wrapper the growth observers watch), `jump-pill` (the built-in jump-to-latest button,
+absent while `follow` is engaged), `unread-divider` (the "New messages" separator, slotted mode
+only).
+
+Renders no messages and computes no unread state itself — the host supplies `unreadStartIndex`; no
+virtualization of its own (`lr-virtual-list`); not a generic overflow surface (`lr-scroller`); no
+message semantics (`lr-chat-message`).
+
+```html
+<lr-chat-viewport unread-start-index="12" @lr-follow-change=${(e) => console.log(e.detail.following)}>
+  <lr-chat-message role="user">…</lr-chat-message>
+  <lr-chat-message role="assistant" status="streaming">
+    <lr-streaming-text streaming .content=${partial}></lr-streaming-text>
+  </lr-chat-message>
+</lr-chat-viewport>
+<lr-chat-composer status="streaming"></lr-chat-composer>
+```

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

@@ -0,0 +1,21 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-checkbox-group`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/checkbox-group/checkbox-group.js';` (registers the tag; side-effect import)
+- **Class** `LyraCheckboxGroup`, also available unregistered from `@aceshooting/lyra-ui/components/forms/checkbox-group/checkbox-group.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-checkbox-group`
+
+A form-associated collection of `<lr-checkbox>` children. Its `value` is a `string[]`; each
+selected value is submitted under `name` and `required` requires at least one selection.
+
+**Properties:** `label`, `hint`, `errorText`, `value`, `name`, `required`, `disabled`, and
+`accessibleLabel` (`aria-label`). **Slots:** default checkboxes, `label`, `hint`, `error`.
+**Events:** `input`, `change`, and `lr-change` with `{ value: string[] }`.
+**CSS parts:** `form-control`, `form-control-label`, `options`, `hint`, `error`.

package/llms/components/lr-checkbox.md

@@ -0,0 +1,79 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-checkbox`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/checkbox/checkbox.js';` (registers the tag; side-effect import)
+- **Class** `LyraCheckbox`, also available unregistered from `@aceshooting/lyra-ui/components/forms/checkbox/checkbox.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-checkbox`
+
+A boolean form control. `role="checkbox"` with an `aria-checked` that can also be `"mixed"`, and a
+visual box/checkmark. Structurally the same idea as `<lr-switch>` (form-associated via
+`ElementInternals`, click and Space toggle) but with checkbox semantics.
+
+**Properties:**
+- `checked: boolean = false` (reflected)
+- `indeterminate: boolean = false` (reflected) — visual-only mixed state; does not affect `checked`,
+  and is cleared back to `false` by any user interaction (click or keyboard), matching native
+  `<input type="checkbox">`
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
+- `name: string = ''`
+- `value: string = 'on'` — only contributed to form submission while `checked` (a native checkbox
+  submits nothing at all, not even an empty string, while unchecked)
+
+**Events:** user toggles emit bubbling/composed `input`, then `change`, then the compatibility
+`lr-change` alias (`detail: { checked: boolean }`). Programmatic `.checked` assignments are
+silent. Internal `focus`/`blur` are re-dispatched as bubbling, composed host events.
+
+**Methods:** `focus(options?)` and `blur()` forward to the internal checkbox control.
+
+**Slots:** default — label text, rendered next to the box. Clicking it toggles the checkbox, the
+same as clicking a native checkbox's associated `<label>`. If left empty, set `aria-label` on the
+host so the control still has an accessible name.
+
+**CSS parts:** `base` (the whole interactive control, `role="checkbox"`), `box` (the small square
+showing the checkmark/indeterminate dash), `checkmark` (the checkmark or indeterminate-dash glyph),
+`label` (wrapper around the default slot)
+
+**Themeable custom properties:** shared tokens only — `--lr-space-s`, `--lr-icon-button-size`,
+`--lr-color-border/-surface/-on-brand/-brand/-text/-danger`, `--lr-radius`,
+`--lr-transition-fast`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-checkbox name="terms" required>Accept the terms and conditions</lr-checkbox>
+<script type="module">
+  document
+    .querySelector('lr-checkbox')
+    .addEventListener('lr-change', (e) => console.log(e.detail.checked));
+</script>
+```
+
+Form-associated via a directly-attached `ElementInternals` (not the shared `FormAssociated` mixin,
+whose `value` accessor assumes a plain string default flow) with its own hand-rolled
+`updateValidity()` — same shape as `<lr-combobox>`'s and `<lr-switch>`'s direct-`ElementInternals`
+handling.
+Session-history/autofill restoration uses four explicit state tokens: `checked`, `unchecked`,
+`checked/indeterminate`, and `unchecked/indeterminate`. This preserves both public booleans while
+keeping an unchecked control distinguishable from a checked control whose submitted value is an
+empty string. Restoration updates state, form data, and validity synchronously without firing
+`lr-change`.
+
+**Known gotchas:**
+- `formResetCallback()` restores `checked` to whatever the declarative `checked` attribute parsed to
+  at first connect — captured once via a one-shot flag (not from `attributeChangedCallback` alone,
+  since `checked` reflects and that would wrongly re-capture on every later user toggle). A later
+  `el.checked = true` assignment never redefines the reset default.
+- `indeterminate` is visual-only and silently clears on any user click/keypress — a consumer relying
+  on it staying `true` after a user interacts with the box will be surprised.
+- The rendered `aria-label` is copied from the host's own `aria-label` attribute at render time; if
+  neither that nor slotted label text is present, the control has no accessible name.
+
+---

package/llms/components/lr-checkpoint.md

@@ -0,0 +1,48 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-checkpoint`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/checkpoint/checkpoint.js';` (registers the tag; side-effect import)
+- **Class** `LyraCheckpoint`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/checkpoint/checkpoint.class.js`
+- **Family** `components/conversation/` — 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-checkpoint`
+
+An inline conversation restore point: a labeled marker between messages whose Restore affordance
+confirms inline, then hands the host a `lr-restore` event. This component persists and restores
+nothing itself — host state in, events out. Not a handoff or plain rule
+(`lr-handoff-divider`/`lr-divider`); not branch navigation across regenerated variants
+(`lr-branch-picker`); not recorded-run playback (`lr-playback`).
+
+**Properties:** `checkpointId: string = ''` (attribute `checkpoint-id`) — opaque id echoed in the
+`lr-restore` event detail. `label: string = ''` — checkpoint name; the localized `checkpointLabel`
+fallback renders while empty. `timestamp?: Date | string` (attribute: false) — optional creation
+time, rendered as `<time datetime>`, default `hour:minute` in `effectiveLocale`; invalid strings are
+treated as unset. `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the
+default rendering. `restorable: boolean = true` — when `false`, renders a plain marker with no
+button. `confirmRestore: boolean = true` (attribute `confirm-restore`) — gates the event behind an
+inline confirm step; a string-aware converter parses `confirm-restore="false"` correctly from plain
+HTML. `restoring: boolean = false` (reflected) — host-set busy state: the Restore button becomes
+`aria-disabled="true"` with a spinner beside the localized "Restoring…" text.
+
+**Slots:** default — optional supplemental content under the marker row (e.g. what changed since
+this point).
+
+**Events:** `lr-restore` — `detail: { checkpointId, label }`; fired on Restore activation, after
+the inline confirm when `confirmRestore` is on. Not cancelable.
+
+**CSS parts:** `base` (`role="group"`), `line` (each of the two flanking rules), `icon` (bookmark
+glyph), `label`, `timestamp`, `restore-button` (only while `restorable`), `confirm-group`,
+`confirm-prompt`, `confirm-button`, `cancel-button`.
+
+**Themeable custom properties:** `--lr-checkpoint-spin-duration` (default `1s`) — duration of one
+restoring-spinner rotation; stopped under reduced motion.
+
+```html
+<lr-checkpoint checkpoint-id="ck_18" label="Before refactor" .timestamp=${t}
+  @lr-restore=${(e) => restoreTo(e.detail.checkpointId)}></lr-checkpoint>
+```

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

@@ -0,0 +1,152 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-chip-group`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/chip/chip-group.js';` (registers the tag; side-effect import)
+- **Class** `LyraChipGroup`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/chip/chip-group.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-chip` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-chip` / `lr-chip-group`
+
+A small, content-agnostic pill for a short label: a tag, an active-filter/scope indicator, etc.
+Distinct from `<lr-attachment-chip>` (specifically file-shaped, with a thumbnail/size/upload-
+progress) — this pair carries no domain assumptions at all. `<lr-chip>` is a controlled component:
+clicking its remove (×) button only fires `lr-remove` — the chip never removes itself from the DOM
+on its own interaction, the same contract `<lr-attachment-chip>`/`<lr-conversation-item>`
+already follow.
+
+### `lr-chip`
+
+**Properties:**
+- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — standard visual-density
+  scale for typography, padding, gap, and icon size; `m` preserves the original chip dimensions
+- `tone: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected — tints the
+  whole pill using a loud-color-on-quiet-tint convention; `neutral` has no dedicated token pair, so
+  it falls back to a plain bordered-surface look)
+- `removable: boolean = false` (reflected — shows the remove (×) button)
+- `selected: boolean = false` (reflected) — opt-in toggle/pressed mode: when set, `[part='base']`
+  itself becomes focusable and keyboard-activatable (Enter/Space, mirroring native `<button>`
+  behavior), reflects `aria-pressed` (explicitly `"false"`, not omitted, whenever toggle mode is
+  active but unpressed), and toggles on click/activation, emitting `lr-chip-select`.
+  Has no effect (no interactive semantics added to `[part='base']`) when combined with `removable`,
+  since the remove button already nests inside `[part='base']` — a focusable descendant of a
+  `role="button"` ancestor isn't allowed there, and this component's two real use cases (a
+  chart-series visibility toggle, a category filter chip) never need both at once. `false` (the
+  default, with `toggleable` also left at its default) reproduces the exact passive-label-pill
+  output.
+- `toggleable: boolean = false` (reflected) — explicit opt-in into `selected`'s toggle/pressed
+  interactive mode, independent of `selected`'s own current value. Setting `selected` to `true` at
+  any point opts in automatically and keeps `toggleable` `true` from then on (enough for a chip that
+  starts already pressed) — set `toggleable` directly instead for a chip that must be clickable from
+  the outset while starting **unselected**, e.g. an initially-inactive category filter chip, since
+  `selected`'s own default (`false`) can't otherwise be distinguished from "never opted in".
+- `value?: string` — opaque consumer bookkeeping value, never read, validated, or rendered by this
+  component itself, only ever echoed back verbatim (including `undefined` if never set) in
+  `lr-remove`'s detail
+
+**Events:** `lr-remove` (`detail: { value }` — the remove (×) button was activated via click or
+Enter/Space while focused; only rendered/reachable while `removable`), `lr-chip-select`
+(`detail: { value, selected }` — fired on click, or Enter/Space while focused, when `selected` mode
+is active and `removable` is not set; the chip has already toggled its own `selected` state by the
+time this fires)
+
+**Slots:** default (the chip's label content), `icon` (optional leading icon or status dot; nothing
+reserved for it — no extra gap — when left empty)
+
+**CSS parts:** `base` (the pill's root container), `icon` (wrapper around the `icon` slot; hidden
+entirely while empty), `label` (wrapper around the default slot), `remove-button` (the remove (×)
+affordance, only rendered while `removable`)
+
+**Themeable custom properties:** `--lr-chip-accent`, `--lr-chip-bg`, `--lr-chip-border`
+(component-local trio swapped per `tone` rather than repeating background/color/border per part per
+tone; default `var(--lr-color-text)` / `var(--lr-color-surface)` / `var(--lr-color-border)` —
+mirrors the same accent/bg/border vocabulary `<lr-tool-call-chip>`/`<lr-attachment-chip>` use),
+`--lr-chip-pressed-border` (border color while pressed/selected — falls back to
+`--lr-chip-accent`), `--lr-chip-pressed-bg` (background color while pressed/selected — falls
+back to `--lr-chip-bg`), the density quintet `--lr-chip-font-size`, `--lr-chip-padding-block`,
+`--lr-chip-padding-inline`, `--lr-chip-gap`, `--lr-chip-icon-size` (all five are rewritten by each
+`:host([size])` rule, so setting one directly on the element overrides that step of the scale; the
+`m` defaults are `--lr-font-size-sm` / `--lr-size-0-25rem` / `--lr-space-s` / `--lr-space-xs` /
+`--lr-font-size-sm`), plus shared tokens (`--lr-space-xs`, `--lr-space-s`,
+`--lr-color-brand`/`-brand-quiet`, `--lr-color-success`/`-success-quiet`,
+`--lr-color-warning`/`-warning-quiet`, `--lr-color-danger`/`-danger-quiet`,
+`--lr-icon-button-size`, `--lr-focus-ring-width`, `--lr-focus-ring-color`,
+`--lr-focus-ring-offset`, `--lr-transition-fast`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-chip
+  toggleable
+  selected
+  style="--lr-chip-bg: var(--lr-color-surface); --lr-chip-pressed-bg: var(--lr-color-warning-quiet)"
+>
+  Priority filter
+</lr-chip>
+```
+
+### `lr-chip-group`
+
+A flex-wrap container for a set of `<lr-chip>` children — plain light-DOM composition, direct
+children are the chips (the same shape `<lr-split>`'s panels / `<lr-source-list>`'s cards take,
+no `.items` array prop).
+
+**Properties:**
+- `maxVisible?: number` (attribute `max-visible`) — maximum number of assigned children shown before
+  the rest collapse behind a "+N" indicator; flattened slot-forwarded children count the same as
+  direct children. Unset means no limit
+
+**Events:** `lr-overflow-toggle` (`detail: { expanded }` — the overflow indicator was activated,
+revealing or re-collapsing the excess children; fires only from that click, i.e. only when
+`max-visible` is actually causing an overflow state — never as a side effect of `max-visible`/
+children changing on their own)
+
+**Slots:** default (`<lr-chip>` elements, or any content, though the chip pairing is the intended
+usage)
+
+**CSS parts:** `base` (the flex-wrap container, holds both the slot and the overflow indicator),
+`overflow-indicator` (the "+N" / "Show less" toggle button; only rendered while `max-visible` is
+actively causing an overflow — a locally-styled pill, not an instantiated real `<lr-chip>`)
+
+**Themeable custom properties:** shared tokens only (`--lr-space-xs`, `--lr-space-s`,
+`--lr-color-border`, `--lr-color-surface`, `--lr-color-text-quiet`, `--lr-color-text`,
+`--lr-color-brand`, `--lr-focus-ring-width`, `--lr-focus-ring-color`,
+`--lr-focus-ring-offset`, `--lr-transition-fast`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-chip-group max-visible="3">
+  <lr-chip removable value="draft">Draft</lr-chip>
+  <lr-chip tone="success" removable value="reviewed">Reviewed</lr-chip>
+  <lr-chip tone="warning">Needs input</lr-chip>
+  <lr-chip tone="danger">Blocked</lr-chip>
+</lr-chip-group>
+<script type="module">
+  const group = document.querySelector('lr-chip-group');
+  group.addEventListener('lr-overflow-toggle', (e) => console.log(e.detail.expanded));
+  group.querySelectorAll('lr-chip').forEach((chip) => chip.addEventListener('lr-remove', (e) => console.log(e.detail.value)));
+</script>
+```
+
+Since CSS alone can't parameterize `:nth-child` on a runtime prop, `<lr-chip-group>` reaches
+directly into the light DOM and sets each excess child's own `hidden` property once `max-visible` is
+exceeded — the same approach `<lr-split>` uses to set each panel's inline `flex`/`order`, rather
+than a stylesheet-only solution.
+
+**Known gotchas:**
+- `<lr-chip>`'s accessible remove-button label ("Remove {text}") is computed only from the default
+  slot's own text content — text living inside the (decorative) `icon` slot doesn't leak into it.
+- `<lr-chip-group>` silently un-expands (`expanded` resets to `false`, with no event firing) if a
+  consumer raises `max-visible` past the current child count while already expanded — only an actual
+  click on the overflow indicator fires `lr-overflow-toggle`.
+- `<lr-chip-group>`'s overflow indicator is its own locally-styled pill, not an instantiated
+  `<lr-chip>` in its shadow DOM — don't expect `<lr-chip>`'s CSS parts or custom properties to
+  reach it.
+
+---