@aceshooting/lyra-ui 9.1.1 → 11.0.0

package/llms/components/lr-scatter-chart.md

@@ -7,8 +7,8 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 16 parts, 35 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -25,7 +25,8 @@ and behavior there. **See `llms/components/lr-chart.md` for the details, code ex
 of every entry in these lists.**
 
 **Properties:** `description`, `grid`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `max`, `min`, `plugins`, `stacked`, `withoutAnimation` (`without-animation`),
+(`legend-position`), `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
+`stacked`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
@@ -43,7 +44,7 @@ complete `hiddenDatasets` snapshot).
 **Slots:** default JSON configuration script, `data-table`, `center`.
 
 **CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
-`reset-zoom-button`, `description`, `notices`, `data-table`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
+`reset-zoom-button`, `description`, `notices`, `data-table`, `data-table-toggle`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
 rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load; the
 failure transition is announced through the shared document-level light-DOM assertive sink — see
 `llms/components/lr-chart.md`).
@@ -52,7 +53,8 @@ failure transition is announced through the shared document-level light-DOM asse
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
 `--lr-chart-tooltip-text`, `--lr-chart-legend-item-hover-bg`,
 `--lr-chart-legend-item-active-bg`, `--lr-chart-data-table-button-hover-bg`,
-`--lr-chart-data-table-button-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
+`--lr-chart-data-table-button-active-bg`, `--lr-chart-data-table-toggle-hover-bg`,
+`--lr-chart-data-table-toggle-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
 `--lr-chart-reset-zoom-button-active-bg`, `--lr-chart-canvas-hover-outline-width`, and
 `--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — all inherited from `LyraChart`, identical in meaning and default (see
 `lr-chart` above); each of the eight variants below reads the same set, so one rule retunes them
@@ -66,7 +68,7 @@ together. The mirrored hooks are `--border-color-1`,
 `zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
-<lr-bar-chart legend></lr-bar-chart>
+<lr-bar-chart></lr-bar-chart>
 <lr-pie-chart></lr-pie-chart>
 <script>
   document.querySelector('lr-bar-chart').labels = ['A', 'B'];

package/llms/components/lr-sequence-strip.md

@@ -85,16 +85,30 @@ readonly color, readonly label? }`; `color`
   per-category only. The marker count is reported as its own clause rather than folded into any
   category's count. Unset (the default) changes nothing: no extra legend row, no extra summary clause
 
+- `selectedIndex: number = -1` (attribute `selected-index`) — the currently selected item, or `-1`
+  for none. **Controlled:** activating a cell emits `lr-item-activate` and does *not* move the
+  selection itself, so the consumer stays the single source of truth and the strip cannot drift from
+  a playback index it does not own (its natural companion is `lr-sequence-playback`). Mirrors the
+  shape `lr-lite-chart`'s `selectedIndices` and `lr-heatmap`'s `selectedCell` already establish. An
+  out-of-range or non-integer value selects nothing. The selected cell carries `aria-current="true"`
+  and `data-selected`; the selection is drawn as a ring rather than a background change, because a
+  cell's background is data (its category colour) and tinting it would misreport the category
+
 The single-member `orientation: 'horizontal'` property was **removed in 9.0.0**: nothing read it and
 the stylesheet never mentioned it, so the reflected attribute styled nothing. Delete the attribute;
 the strip has always laid out horizontally.
 
-**Events:** none.
+**Events:** `lr-item-activate` — `detail: { index: number; id: string; item: SequenceStripItem }`,
+fired when a cell is clicked or activated with Enter/Space on the roving-tabindex focus. Not
+cancelable: nothing in the component branches on `defaultPrevented`. Bubbles and composed, like every
+library event.
 
 **Slots:** none.
 
 **CSS parts:** `base` (the root strip, `role="list"`), `cell` (each item's `role="listitem"` cell,
-background-colored by its category and carrying the roving `tabindex`), `marker` (the small bottom
+background-colored by its category, carrying the roving `tabindex`, and activatable by click or
+Enter/Space — it has a pointer cursor plus paired hover/press treatments, and `[data-selected]` when
+it is `selectedIndex`), `marker` (the small bottom
 marker on a cell whose item sets `marker: true`), `tooltip` (the detail tooltip showing the active
 item's label, hidden until a cell is hovered or focused),
 `legend` (the static category key rendered below the strip when `showLegend` is set — `aria-hidden`,

package/llms/components/lr-slider.md

@@ -204,6 +204,7 @@ Mapped aliases are also live: `--thumb-size`, `--thumb-width`, `--thumb-height`,
 
 ```html
 <lr-slider
+  id="temperature-slider"
   name="temperature"
   min="0"
   max="2"
@@ -212,14 +213,11 @@ Mapped aliases are also live: `--thumb-size`, `--thumb-width`, `--thumb-height`,
   hint="Higher values make replies more varied."
   with-markers
   with-tooltip
-  .valueAsNumber=${0.7}
-  .valueFormatter=${(value, handle) => `${value * 100}%`}
-  @lr-input=${(e) => setDraftTemperature(e.detail.value)}
-  @lr-change=${(e) => commitTemperature(e.detail.value)}
 ></lr-slider>
 
 <!-- Two handles, vertical. A name submits two `price` entries. -->
 <lr-slider
+  id="price-slider"
   range
   name="price"
   orientation="vertical"
@@ -229,8 +227,17 @@ Mapped aliases are also live: `--thumb-size`, `--thumb-width`, `--thumb-height`,
   min-value="200"
   max-value="800"
   label="Price"
-  @lr-change=${(e) => applyPriceFilter(e.detail.minValue, e.detail.maxValue)}
 ></lr-slider>
+<script type="module">
+  const temperature = document.getElementById("temperature-slider");
+  temperature.valueAsNumber = 0.7;
+  temperature.valueFormatter = (value, handle) => `${value * 100}%`;
+  temperature.addEventListener("lr-input", (e) => setDraftTemperature(e.detail.value));
+  temperature.addEventListener("lr-change", (e) => commitTemperature(e.detail.value));
+
+  const price = document.getElementById("price-slider");
+  price.addEventListener("lr-change", (e) => applyPriceFilter(e.detail.minValue, e.detail.maxValue));
+</script>
 ```
 
 An unset `value` starts at numeric `0`, clamped into the configured domain and step grid. A reset

package/llms/components/lr-sparkline.md

@@ -6,7 +6,7 @@
 - **Class** `LyraSparkline`, also available unregistered from `@aceshooting/lyra-ui/components/data/sparkline/sparkline.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecated part** `base` since `8.0.0`; use part `::part(sparkline)`; removal not before `10.0.0` — The sparkline part names the rendered SVG wrapper unambiguously; base remains on that same node during the compatibility window.
+- **Deprecated part** `base` since `8.0.0`; use part `::part(sparkline)`; removal not before `10.0.0` — The sparkline part names the rendered SVG wrapper unambiguously; base remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-sparkline` still publishes its own deprecated `base` part, so this alias is removed only when upstream's is.
 - **Optional peers** none
 - **Themeable via** 6 parts, 4 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`

package/llms/components/lr-suggestion-chips.md

@@ -58,7 +58,12 @@ Enter/Space activate. Renders inside an internal `lr-scroller` (`orientation="ho
 `hide-scrollbar`) unless `wrap` is set.
 
 ```html
-<lr-suggestion-chips .suggestions=${followUps}
-  @lr-suggestion-select=${(e) => (composer.value = e.detail.label)}></lr-suggestion-chips>
+<lr-suggestion-chips></lr-suggestion-chips>
 <lr-chat-composer></lr-chat-composer>
+<script type="module">
+  const chips = document.querySelector("lr-suggestion-chips");
+  const composer = document.querySelector("lr-chat-composer");
+  chips.suggestions = followUps;
+  chips.addEventListener("lr-suggestion-select", (e) => (composer.value = e.detail.label));
+</script>
 ```

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

@@ -6,8 +6,7 @@
 - **Class** `LyraSwatchPicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecated property** `label` / `label` since `8.2.3`; use property `aria-label="…"`; removal not before `10.0.0` — accessibleLabel names the accessibility-only value explicitly while label remains a compatibility alias.
-- **Deprecated property** `options` since `8.2.3`; use property `.items = […]`; removal not before `10.0.0` — items follows the shared collection vocabulary while options remains a compatibility alias over the same immutable snapshot.
+- **Deprecations** none
 - **Optional peers** none
 - **Themeable via** 4 parts, 8 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`
@@ -49,9 +48,10 @@ gemstone?: GemstoneKey }`; a valid CSS `color` is used as the
   the selected glow/shine defaults.
 - `accessibleLabel: string = ''` (attribute `aria-label`) — accessible name copied to the internal
   `role="radiogroup"`; attribute presence wins, including an explicitly empty name.
-- `options` and `SwatchOption` remain compatibility aliases for `items` and `SwatchPickerItem`;
-  new code uses the canonical sibling radiogroup vocabulary. The former invisible `label` IDL also
-  remains as a compatibility fallback after `aria-label`/`accessibleLabel`.
+- The 9.x compatibility aliases were removed in 10.0.0: `options` is `items`, the exported
+  `SwatchOption` type is `SwatchPickerItem`, and the former invisible `label` IDL is
+  `accessibleLabel`/`aria-label`. The canonical sibling radiogroup vocabulary is now the only
+  spelling.
 - `disabled: boolean = false` (reflected) — locks the whole picker. Every swatch renders as a real
   `disabled` `<button>`, so it leaves the tab sequence and cannot be activated; arrow/Home/End
   navigation and host `click()` become no-ops; and the swatches dim to `--lr-opacity-disabled` with

package/llms/components/lr-switch.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 11 parts, 12 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 12 parts, 12 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`
 
 ---
@@ -86,7 +86,10 @@ restores the current default before making the control pristine again.
 - `help-text` — Shoelace alias for the same hint surface.
 - `error` — custom error content.
 
-**CSS parts:** `form-control` (the outer wrapper around the switch, error and hint), `base` /
+**CSS parts:** `form-control` (the outer wrapper around the switch, error and hint), `row` (the row
+wrapping the switch owner and the label as siblings — the node to size or align when laying out a
+column of switches, since `base`/`switch` below is only the track box and its inline size tracks the
+track rather than the row), `base` /
 `switch` / `wrapper` (the semantic interactive `role="switch"` owner; the rich label is its
 sibling), `track` / `control` (the
 pill-shaped background), `thumb` (the circular knob), `label` (wrapper around the default slot),

package/llms/components/lr-table.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 34 parts, 15 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 34 parts, 18 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`
 
 ---
@@ -220,7 +220,13 @@ cell: (row) => unknown }` —
 - `groupLabel?: (key: string | number, rows: readonly T[]) => unknown` (attribute: false) — custom group
   header content; without it, the group key is rendered as text
 - `expandedContent?: (row: T) => unknown` (attribute: false) — enables a leading expand toggle and
-  renders a full-width detail row beneath expanded records
+  renders a full-width detail row beneath expanded records. The returned content renders inside
+  the component's shadow root, behind the `expanded-cell` part — page CSS cannot reach it, and
+  `::part(expanded-cell)` only reaches the wrapping `<td>` itself, not the descendants this
+  callback returns (the same `::part()` limitation a column's `cell(row)` anchors run into, see
+  `--lr-table-cell-link-color` below). Style such content by returning already-styled elements —
+  inline `style`, or elements that reference this table's own `--lr-*` design tokens, which
+  inherit across the shadow boundary like any custom property
 - `canExpand?: (row: T) => boolean` (attribute: false) — optional per-row gate for expansion
 - `expandedRowKeys: ReadonlySet<string | number> = new Set()` (attribute: false) — consumer-controlled
   expanded state bounded to 10,000 keys; malformed and whitespace-only string keys are omitted while valid
@@ -272,7 +278,11 @@ sort properties; server mode leaves them controlled. Other events are `lr-row-cl
 (`detail: { row }`), `lr-load-more` (fired on the "load more" button),
 `lr-priority-columns-visibility-change` (frozen readonly `detail: { visible }`), and `lr-row-expand-toggle`
 (`detail: { row, rowKey }`; the table does not mutate `expandedRowKeys`), and
-`lr-selection-change` (frozen readonly `detail: { rowKeys }`) when selection is enabled, `lr-filter-change`
+`lr-selection-change` (frozen readonly `detail: { rowKeys }`, not cancelable) when selection is
+enabled — fired both from a row activation and from a `selectionMode` flip to `'single'` that coerces
+an existing multi-row selection down to one key (skipped on the very first render, since an
+already-inconsistent initial `selectionMode`/`selectedRowKeys` pairing is a starting state, not a
+live transition), `lr-filter-change`
 (frozen readonly `detail: { text }`), and `lr-page-change` (frozen readonly `detail: { page }`) from the
 filter/pagination surfaces, and `lr-cell-edit` (`detail: { row, columnKey, value }`) for editable
 columns, and `lr-column-resize` (`detail: { columnKey, width }`, `width` in CSS pixels) on every pointer or
@@ -321,7 +331,23 @@ no-rows states return the empty element as the shadow root's own root, with no `
 wrapper around it — `::part(base)` does not apply in those two states, only in the filtered-to-zero
 one — and that `empty` disappears entirely once the `empty` slot is filled.
 
-**Themeable custom properties:** `--lr-table-max-height` (default `none`; controls the scrollable
+- `scrollMode: 'self' | 'page' = 'self'` (attribute `scroll-mode`, reflected) — which element
+  scrolls when the table overflows. `'self'` makes `[part="base"]` the scroll container, which is
+  what pairs with `--lr-table-max-height` and makes the sticky header pin inside the table's own
+  viewport. `'page'` hands scrolling back to the document. Needed because a scroll container clips
+  **both** axes — CSS offers no way to scroll one and not the other — so an *uncapped* table that is
+  still `overflow: auto` becomes a sticky containing block that never scrolls, and its header
+  scrolls away with the page. With `'page'` the header's nearest scrollport is the page, so it pins
+  there; the cost is that a table wider than its host overflows the page instead of scrolling
+  inside itself. Named `scrollMode` rather than `scroll` because a `scroll` property would shadow
+  `Element.prototype.scroll()`
+
+**Themeable custom properties:** `--lr-table-cell-color` (default `inherit`),
+`--lr-table-cell-link-color` (default `var(--lr-color-brand)`) and
+`--lr-table-cell-link-hover-color` — an anchor returned from a column's `cell(row)` renders inside
+the component's shadow root, where page CSS cannot reach it and `::part()` cannot select past the
+first compound selector to reach it either, so without these it computes to the UA default link
+blue; set `revert` for the UA default. `--lr-table-max-height` (default `none`; controls the scrollable
 body's `max-block-size`). `--lr-table-heat-tint-lo` (default `var(--lr-color-brand-quiet)`) and
 `--lr-table-heat-tint-hi` (default `var(--lr-color-brand)`) — the `color-mix()` ramp endpoints
 for heat-tint mode's per-cell background, consulted only on columns/rows that define `heatValue`;

package/llms/components/lr-terminal.md

@@ -61,7 +61,9 @@ default the component creates a plain-text `Blob`/object URL and activates a syn
 `<a download>`; `preventDefault()` suppresses that built-in download so the host can substitute
 server-side or other handling),
 `lr-follow-change` (`detail: { following }`), `lr-search-change` (`detail: { query, matchCount,
-activeIndex }`), `lr-highlight-activate` (`detail: { highlightId }`), and `lr-text-select` (`detail: {
+matchCountExact, activeIndex }`; `matchCountExact` is `false` once a search hits the 10,000-match
+ceiling, marking `matchCount` as a lower bound rather than an exact total),
+`lr-highlight-activate` (`detail: { highlightId }`), and `lr-text-select` (`detail: {
 text, anchor, rects }`).
 
 **CSS parts:** `base`, `toolbar` (only rendered when copy/download are enabled), `copy-button`,

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

@@ -193,14 +193,14 @@ short one, and falls back to exactly `24rem` in an auto-height container.
 style the pinned band with `lr-thread-list::part(group-sticky)`.
 
 ```html
-<lr-thread-list
-  searchable
-  sticky-groups
-  .threads=${threads}
-  active-conversation-id=${activeThreadId}
-  .rowActions=${['pin', 'archive', 'delete']}
-  @lr-select=${(e) => openThread(e.detail.conversationId)}
-></lr-thread-list>
+<lr-thread-list searchable sticky-groups></lr-thread-list>
+<script type="module">
+  const list = document.querySelector("lr-thread-list");
+  list.threads = threads;
+  list.activeConversationId = activeThreadId;
+  list.rowActions = ["pin", "archive", "delete"];
+  list.addEventListener("lr-select", (e) => openThread(e.detail.conversationId));
+</script>
 ```
 
 Composed with `lr-multi-split` (or `lr-app-rail` + `lr-responsive-panel`): thread-list in the start

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

@@ -30,7 +30,12 @@ than adding outer padding around the buttons.
 - `value: string` (also accepts a `Date` or `null` when assigned) — strict `HH:mm`, optional
   `:ss`/`.sss`; `Date` reads local clock fields without timezone conversion. Invalid strings and
   `null` normalize to `''`. `valueAsNumber` is milliseconds since midnight (`NaN` while blank),
-  and `valueAsDate` applies the clock fields to today's local date (`null` while blank).
+  and `valueAsDate` applies the clock fields to today's local date (`null` while blank). Both are
+  settable, like the native `<input type="time">` properties they mirror: assigning `valueAsNumber`
+  sets `value` from the same scale, and out-of-range or non-finite figures clear the field rather
+  than wrapping into a different time; assigning `valueAsDate` reads the same local clock fields
+  back off the Date, so it round-trips with the getter, and `null`/an invalid Date clears. Both
+  assignments are silent, again like the native properties.
 - `defaultValue`, `name`, `form`, `disabled`, `required`, `customError`, `getForm()`,
   `checkValidity()`, `reportValidity()`, `setCustomValidity()`, and `resetValidity()` use the shared form-control
   contract. Reset restores the current declarative `value` default; `readonly` remains focusable

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

@@ -30,6 +30,30 @@ opposite default from `lr-stepper`; `horizontal` makes `[part='base']` a horizon
 (the `role="list"` element is in the shadow root and never inherits a host attribute). Read-only
 `itemCount: number` is the live count of direct default-slot `<lr-timeline-item>` children;
 unrelated slotted elements and text nodes are ignored.
+`scale: 'flow' | 'time' = 'flow'` (attribute `scale`, type `LyraTimelineScale`) chooses how items
+are distributed along the main axis. `'flow'` is the default even sequence, where `timestamp` is
+rendered as text but carries no positional meaning. `'time'` positions each item at its true
+proportion of the range, so a gap of weeks and a gap of decades stop looking identical. `'time'`
+needs a definite extent to distribute along — `--lr-timeline-time-extent` (default
+`var(--lr-size-20rem)`), applied as `block-size` when vertical and `inline-size` when horizontal —
+because items are absolutely positioned and a percentage against an auto-sized track resolves to
+zero. `collision: 'overlap' | 'stack' = 'overlap'` (attribute `collision`, type `LyraTimelineCollision`)
+chooses what `scale="time"` does with items landing on nearly the same position: `'overlap'` leaves
+them stacked on one another, `'stack'` steps each colliding item one lane along the **cross** axis
+(indent per lane: `--lr-timeline-collision-offset`, default `var(--lr-space-l)`), which is what a
+dense chronology needs — items within 1.5% of the axis of each other count as colliding, and an
+isolated item returns to lane 0 rather than inheriting a preceding run's depth. There is
+deliberately no `'cluster'` mode: collapsing coincident items into one expandable marker needs a
+selection model and click events this passive component does not have.
+`rangeStart` / `rangeEnd` (`Date | string | number`, attribute: false) pin the axis instead of
+deriving it from the earliest/latest item; a reversed or non-finite pair falls back to the derived
+range. An item with no parseable `timestamp` (including one supplied only through the `timestamp`
+slot, which carries no machine-readable instant) keeps document order and is spread evenly, so a
+partially-timestamped list degrades rather than stacking at the origin. Items sharing an instant
+overlap rather than being fanned into lanes: lane assignment, brushing, zooming and per-event
+selection belong to a denser component than this deliberately passive one. Positions are written to
+each child as a private `--_lr-timeline-item-offset` custom property and removed again on a switch
+back to `'flow'`, so the component still never alters its children's content or structure.
 
 **`lr-timeline-item` properties:** `timestamp?: Date | string | number` (attribute: false — `Date`
 isn't attribute-serializable; invalid input normalizes to unset and renders no timestamp UI),

package/llms/components/lr-timeline.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 1 part, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 1 part, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-timeline-item` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -30,6 +30,30 @@ opposite default from `lr-stepper`; `horizontal` makes `[part='base']` a horizon
 (the `role="list"` element is in the shadow root and never inherits a host attribute). Read-only
 `itemCount: number` is the live count of direct default-slot `<lr-timeline-item>` children;
 unrelated slotted elements and text nodes are ignored.
+`scale: 'flow' | 'time' = 'flow'` (attribute `scale`, type `LyraTimelineScale`) chooses how items
+are distributed along the main axis. `'flow'` is the default even sequence, where `timestamp` is
+rendered as text but carries no positional meaning. `'time'` positions each item at its true
+proportion of the range, so a gap of weeks and a gap of decades stop looking identical. `'time'`
+needs a definite extent to distribute along — `--lr-timeline-time-extent` (default
+`var(--lr-size-20rem)`), applied as `block-size` when vertical and `inline-size` when horizontal —
+because items are absolutely positioned and a percentage against an auto-sized track resolves to
+zero. `collision: 'overlap' | 'stack' = 'overlap'` (attribute `collision`, type `LyraTimelineCollision`)
+chooses what `scale="time"` does with items landing on nearly the same position: `'overlap'` leaves
+them stacked on one another, `'stack'` steps each colliding item one lane along the **cross** axis
+(indent per lane: `--lr-timeline-collision-offset`, default `var(--lr-space-l)`), which is what a
+dense chronology needs — items within 1.5% of the axis of each other count as colliding, and an
+isolated item returns to lane 0 rather than inheriting a preceding run's depth. There is
+deliberately no `'cluster'` mode: collapsing coincident items into one expandable marker needs a
+selection model and click events this passive component does not have.
+`rangeStart` / `rangeEnd` (`Date | string | number`, attribute: false) pin the axis instead of
+deriving it from the earliest/latest item; a reversed or non-finite pair falls back to the derived
+range. An item with no parseable `timestamp` (including one supplied only through the `timestamp`
+slot, which carries no machine-readable instant) keeps document order and is spread evenly, so a
+partially-timestamped list degrades rather than stacking at the origin. Items sharing an instant
+overlap rather than being fanned into lanes: lane assignment, brushing, zooming and per-event
+selection belong to a denser component than this deliberately passive one. Positions are written to
+each child as a private `--_lr-timeline-item-offset` custom property and removed again on a switch
+back to `'flow'`, so the component still never alters its children's content or structure.
 
 **`lr-timeline-item` properties:** `timestamp?: Date | string | number` (attribute: false — `Date`
 isn't attribute-serializable; invalid input normalizes to unset and renders no timestamp UI),

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

@@ -46,11 +46,16 @@ each list mutation; native events have no detail and both aliases carry a frozen
 Native `FocusEvent` `focus`/`blur` are relayed once from the draft and inline editor, preserving
 `relatedTarget`. `lr-add`
 (`detail: { value, values }`, where `value` is the final added token and `values` is the frozen,
-readonly, complete ordered and deduplicated set of tokens added by that commit),
+readonly, complete ordered and deduplicated set of tokens added by that commit — cancelable as of
+10.0.0; `preventDefault()` keeps the tokens out of `value` and leaves the typed draft text in the
+input unchanged so the user can correct it, rather than clearing it),
 `lr-remove`
 (`detail: { value, index }` — cancelable; `preventDefault()` keeps the token in `value`
 unchanged), and `lr-token-edit`
-(`detail: { value, previousValue, index }` — an existing token was edited in place and committed).
+(`detail: { value, previousValue, index }` — an existing token is about to be edited in place —
+cancelable as of 10.0.0; `preventDefault()` keeps the token in `value` unchanged and leaves the
+inline editor open with the user's edited text intact, rather than closing and discarding it).
+All three mutators now share one veto contract; previously only `lr-remove` could be vetoed.
 `lr-invalid` (no detail) is emitted once as a bubbling/composed alias when native validity fails.
 **CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `token`, `token-label` (the
 token's text, doubling as the roving-focus edit trigger — rendered only while `editable`),

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

@@ -112,15 +112,14 @@ other text-entry surface in the library provides), plus shared tokens
 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>
+<lr-tool-approval-dialog tool-name="send_email"></lr-tool-approval-dialog>
 <script type="module">
-  document.querySelector('lr-tool-approval-dialog').open = true;
+  const dialog = document.querySelector("lr-tool-approval-dialog");
+  dialog.args = { to: "ops@example.com", subject: "Deploy finished" };
+  dialog.addEventListener("lr-approve", (e) => runTool(e.detail.args));
+  dialog.addEventListener("lr-deny", () => console.log("denied"));
+  dialog.addEventListener("lr-close", (e) => console.log("closed:", e.detail));
+  dialog.open = true;
 </script>
 ```
 

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

@@ -86,11 +86,15 @@ referenced: `--lr-color-text-quiet`, `--lr-color-surface`, `--lr-color-border`,
   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>
+<script type="module">
+  document
+    .querySelector("lr-tool-call-chip")
+    .addEventListener("lr-tool-call-chip-select", (e) => openDetail(e.detail.callId));
+</script>
 ```
 
 The default slot's tooltip is positioned with the same `internal/positioner.js` `place()` helper

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

@@ -168,20 +168,22 @@ form: `--lr-space-l/-xs/-s`, `--lr-color-border`, `--lr-radius`, `--lr-color-sur
 dependencies of this package imported directly, not optional peers.
 
 ```html
-<lr-tool-param-form
-  .schema=${{
-    type: 'object',
+<lr-tool-param-form></lr-tool-param-form>
+<script type="module">
+  const form = document.querySelector("lr-tool-param-form");
+  form.schema = {
+    type: "object",
     properties: {
-      title: { type: 'string', title: 'Title' },
-      attendees: { type: 'string', enum: ['team', 'everyone'], default: 'team' },
-      allDay: { type: 'boolean', title: 'All day' },
+      title: { type: "string", title: "Title" },
+      attendees: { type: "string", enum: ["team", "everyone"], default: "team" },
+      allDay: { type: "boolean", title: "All day" },
     },
-    required: ['title'],
-  }}
-  .value=${draftArgs}
-  @lr-input=${(e) => (draftArgs = e.detail.value)}
-  @lr-validity-change=${(e) => (formIsValid = e.detail.valid)}
-></lr-tool-param-form>
+    required: ["title"],
+  };
+  form.value = draftArgs;
+  form.addEventListener("lr-input", (e) => (draftArgs = e.detail.value));
+  form.addEventListener("lr-validity-change", (e) => (formIsValid = e.detail.valid));
+</script>
 ```
 
 This component owns no Submit/Cancel/Approve chrome — a consumer composes it inside their own dialog

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

@@ -74,20 +74,22 @@ tokens `--lr-color-surface/-border/-text-quiet/-brand/-brand-quiet/-success/-suc
 **Optional peer deps:** none.
 
 ```html
-<lr-tool-result-dialog
-  tool-name="run_query"
-  status="success"
-  duration-ms="1240"
-  ?open=${dialogOpen}
-  @lr-close=${(e) => (dialogOpen = false)}
-  @lr-maximize-change=${(e) => console.log('maximized:', e.detail.maximized)}
->
+<lr-tool-result-dialog tool-name="run_query" status="success" duration-ms="1240">
   <lr-tab-group slot="body">
     <div slot="preview" label="Preview">…</div>
-    <div slot="json" label="JSON"><lr-json-viewer .data=${result}></lr-json-viewer></div>
+    <div slot="json" label="JSON"><lr-json-viewer></lr-json-viewer></div>
   </lr-tab-group>
   <button slot="footer">Rerun</button>
 </lr-tool-result-dialog>
+<script type="module">
+  const dialog = document.querySelector("lr-tool-result-dialog");
+  dialog.querySelector("lr-json-viewer").data = result;
+  dialog.open = true;
+  dialog.addEventListener("lr-close", () => (dialog.open = false));
+  dialog.addEventListener("lr-maximize-change", (e) =>
+    console.log("maximized:", e.detail.maximized)
+  );
+</script>
 ```
 
 While open, `[part="panel"]` takes `role="dialog"` + `aria-modal="true"` with `aria-labelledby`

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

@@ -78,12 +78,13 @@ of course pull in whatever they need (a charting library, a markdown renderer),
 the lazy `load()` path in the registry exists for.
 
 ```html
-<lr-tool-result-view
-  tool-name="get_weather"
-  .result=${{ tempC: 21, condition: 'cloudy' }}
-  .args=${{ city: 'Brussels' }}
-  @lr-render-error=${(e) => console.warn('renderer failed', e.detail)}
-></lr-tool-result-view>
+<lr-tool-result-view tool-name="get_weather"></lr-tool-result-view>
+<script type="module">
+  const view = document.querySelector("lr-tool-result-view");
+  view.result = { tempC: 21, condition: "cloudy" };
+  view.args = { city: "Brussels" };
+  view.addEventListener("lr-render-error", (e) => console.warn("renderer failed", e.detail));
+</script>
 ```
 
 ### `registerToolRenderer()` and the tool-renderer registry (`registry.ts`)

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

@@ -102,23 +102,25 @@ assigned elements.
 dependencies of this package imported directly, not optional peers.
 
 ```html
-<lr-tool-select-dialog
-  label="Select tools"
-  .tools=${[
-    { id: 'search', name: 'Web search', category: 'Research' },
-    { id: 'python', name: 'Python', category: 'Code', description: 'Run sandboxed Python' },
-    { id: 'admin', name: 'Admin console', disabled: true, disabledReason: 'Requires admin approval' },
-  ]}
-  .selectedToolIds=${enabledToolIds}
-  ?use-defaults=${usingDefaults}
-  ?open=${dialogOpen}
-  @lr-change=${(e) => updateTools(e.detail.selectedToolIds, e.detail.useDefaults)}
-  @lr-close=${() => (dialogOpen = false)}
->
-  <button slot="footer" @click=${(e) => e.target.closest('lr-tool-select-dialog').close('done')}>
-    Done
-  </button>
+<lr-tool-select-dialog label="Select tools">
+  <button slot="footer" id="done-btn">Done</button>
 </lr-tool-select-dialog>
+<script type="module">
+  const dialog = document.querySelector("lr-tool-select-dialog");
+  dialog.tools = [
+    { id: "search", name: "Web search", category: "Research" },
+    { id: "python", name: "Python", category: "Code", description: "Run sandboxed Python" },
+    { id: "admin", name: "Admin console", disabled: true, disabledReason: "Requires admin approval" },
+  ];
+  dialog.selectedToolIds = enabledToolIds;
+  dialog.useDefaults = usingDefaults;
+  dialog.open = true;
+  dialog.addEventListener("lr-change", (e) =>
+    updateTools(e.detail.selectedToolIds, e.detail.useDefaults)
+  );
+  dialog.addEventListener("lr-close", () => (dialog.open = false));
+  dialog.querySelector("#done-btn").addEventListener("click", () => dialog.close("done"));
+</script>
 ```
 
 `useDefaults` is a single top-level switch: while `true`, every per-tool checkbox renders disabled

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

@@ -23,9 +23,11 @@ columns. Consumes the same `LyraSpan[]` as `<lr-span-waterfall>`.
 under `lr-span-waterfall` above (exported from `trace-tree/span.ts`); hierarchy comes from
 `parentId`, and a span whose `parentId` is missing or doesn't resolve within the same array renders
 as a root rather than being dropped. `activeSpanId: string | null = null`
-(attribute `active-span-id`), `label: string = ''`, `showTokens: boolean = false` (attribute
+(attribute `active-span-id`), `label?: string`, `showTokens: boolean = false` (attribute
 `show-tokens`) — surfaces `tokensIn`/`tokensOut`, `showCost: boolean = false` (attribute
 `show-cost`) — surfaces `costText`, and `hideBars: boolean = false` (attribute `hide-bars`).
+`label` is an optional accessible-name override for the `role="tree"` element: omission localizes
+the default, and any supplied string — including `''` — is rendered verbatim.
 Token counts render only when finite and non-negative; invalid metrics are omitted rather than
 reaching `Intl.NumberFormat`. A row's accessible name includes its optional `detail` text as well
 as its name/status/metrics, and updates when the supplied span data changes. Every trace view uses

package/llms/components/lr-usage-badge.md

@@ -53,6 +53,9 @@ describable), `summary`, `tokens-in`, `tokens-out`, `cost`, `latency`, `tooltip`
     cost-text="$0.012"
     latency-ms="2350"
   ></lr-usage-badge>
-  <lr-markdown .content="${answer}"></lr-markdown>
+  <lr-markdown></lr-markdown>
 </lr-chat-message>
+<script type="module">
+  document.querySelector("lr-chat-message lr-markdown").content = answer;
+</script>
 ```

package/llms/components/lr-video-playlist.md

@@ -6,7 +6,7 @@
 - **Class** `LyraVideoPlaylist`, also available unregistered from `@aceshooting/lyra-ui/components/media/video-playlist/video-playlist.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Status** `experimental` since `8.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecated part** `base` since `8.0.0`; use part `::part(video-playlist)`; removal not before `10.0.0` — The video-playlist part identifies the root component explicitly; base remains on the same root node for migration compatibility.
+- **Deprecated part** `base` since `8.0.0`; use part `::part(video-playlist)`; removal not before `10.0.0` — The video-playlist part identifies the root component explicitly; base remains on the same root node for migration compatibility. That version is a policy floor, not a plan: `wa-video-playlist` still publishes its own deprecated `base` part, so this alias is removed only when upstream's is.
 - **Optional peers** `dompurify` — see `llms/peers.md`
 - **Themeable via** 7 parts, 2 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`