@aceshooting/lyra-ui 16.0.0 → 17.0.0

package/llms/components/lr-filter-bar.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 26 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 29 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`
 
 ---
@@ -23,6 +23,38 @@ omitted independently, while supplied empty strings remain valid. A custom defin
 adapter and a callable `render`; a rejected definition does not reserve its filter ID. Valid
 siblings remain available. Exceptions thrown by an admitted trusted renderer still propagate.
 
+**Lean registration entry.** `components/layout/filter-bar/filter-bar.js` (the default entry)
+eagerly imports every composed control this bar could possibly render — `<lr-select>`,
+`<lr-combobox>`, `<lr-dropdown>` + `<lr-dropdown-item>` (the `'checkbox-menu'` branch),
+`<lr-date-input>`, `<lr-input>`, `<lr-chip>`/`<lr-chip-group>` (the active-filter row), and
+`<lr-button>`/`<lr-spinner>` (the reset action and the loading status) — because `filters` is a
+runtime value it cannot inspect ahead of time. A bar that only ever declares `'select'`/`'text'`
+filters still pays for `<lr-combobox>` and `<lr-date-input>` through that entry: a measured ~69.5 kB
+gzip more than importing only what it uses. A consumer who knows their own filter `type`s ahead of
+time can import `components/layout/filter-bar/filter-bar-register.js` instead, which registers
+`<lr-filter-bar>` and nothing else, then import each composed control's own registration entry for
+the filter `type`s actually declared:
+
+| Filter `type` | Registration entry |
+| --- | --- |
+| `'select'` | `components/forms/select/select.js` |
+| `'combobox'` | `components/forms/combobox/combobox.js` |
+| `'checkbox-menu'` | `components/overlays/overlay/dropdown.js` **and** `components/layout/menu/dropdown-item.js` |
+| `'date'` / `'date-range'` | `components/forms/date-picker/date-input.js` |
+| `'text'` | `components/forms/input/input.js` |
+
+Two more are unconditional regardless of which filter `type`s are declared: `<lr-button>` renders
+the reset action on every bar, and `<lr-chip>`/`<lr-chip-group>` render the active-filter row
+whenever any filter has a value (further gated by `activeFiltersDisplay`, but never provably absent
+for a generic bar) — `components/forms/button/button.js` and `components/overlays/chip/chip.js` +
+`components/overlays/chip/chip-group.js`. `<lr-spinner>`
+(`components/overlays/spinner/spinner.js`) is the one built-in dependency the lean entry omits even
+though every bar could use it: `loading` is a plain boolean any consumer can leave unset entirely,
+unlike a filter `type`, which `filters` always names outright — import it too if the bar ever sets
+`loading`. A filter definition whose `type` has no matching import above renders no usable control
+until something else registers it, the same trade `icon-button-register.js` documents for
+`<lr-icon-button>`'s own `icon`/`src` attribute.
+
 **Properties:**
 
 - `filters: readonly LyraFilterBarFilterDefinition[] = []` (attribute: false) — filter schema in
@@ -47,8 +79,20 @@ siblings remain available. Exceptions thrown by an admitted trusted renderer sti
 - `loading: boolean = false` (reflected) — shows the status spinner and disables reset while leaving
   filters editable.
 - `hasActiveFilters: boolean` (read-only) — whether any configured filter currently has a value.
+  Drives the reset button's own disabled state; unaffected by `activeFiltersDisplay`.
 - `invalidFilterIds: readonly string[]` (read-only) — immutable ids of required filters whose
   values are unset.
+- `activeFiltersDisplay: 'all' | 'changed' | 'hidden' = 'all'` (reflected, attribute
+  `active-filters-display`) — which currently-active filters render as removable chips in the row
+  below the fields. `'all'` (the default, and this component's only behavior before this property
+  existed) shows one chip per non-empty filter, including one sitting at its own `defaultValue`.
+  `'changed'` shows a chip only for a filter whose value differs from its own `defaultValue` — so a
+  bar whose defaults narrow the view on load does not claim the user narrowed it — and a filter with
+  no declared `defaultValue` counts as changed as soon as it has any value at all. `'hidden'` never
+  renders the row. Array values compare against `defaultValue` positionally (same length, same entry
+  at each index), matching this component's only other array-equality precedent (a custom adapter's
+  own `clearValue` comparison); a `'date-range'` value is a single composed string, so it compares
+  like any other string. Removing a chip always clears that filter, unaffected by this property.
 
 The composed reset action uses `lr-button`'s default `m` size tier, matching the default rendered
 height of adjacent select, combobox, input, and date fields instead of introducing a shorter action
@@ -77,12 +121,13 @@ action) rendered inside `controls`, next to the reset button. Hidden and claimin
 space while nothing is slotted.
 
 **CSS parts:** `base`, `controls`, `field`, `field-<filterId>`, `end`, `filter-control`,
-`filter-control-label`, `filter-control-field`, `filter-control-input`, `filter-control-start`,
-`filter-control-end`, `filter-control-listbox`, `filter-control-option`, `filter-control-tags`,
-`filter-control-tag`, `filter-control-tag-label`, `filter-control-clear-button`,
-`filter-control-expand-button`, `filter-control-expand-icon`, `filter-control-popup`,
-`filter-control-error`, `filter-control-hint`, `active-filters`, `chips`, `chip`, `reset-button`,
-`status`.
+`filter-control-label`, `filter-control-label-group`, `filter-control-field`,
+`filter-control-input`, `filter-control-start`, `filter-control-end`, `filter-control-listbox`,
+`filter-control-option`, `filter-control-tags`, `filter-control-tag`, `filter-control-tag-label`,
+`filter-control-tag-remove-button`, `filter-control-tag-remove-button-base`,
+`filter-control-clear-button`, `filter-control-expand-button`, `filter-control-expand-icon`,
+`filter-control-popup`, `filter-control-error`, `filter-control-hint`, `active-filters`, `chips`,
+`chip`, `reset-button`, `status`.
 
 The `filter-control-*` parts are semantic aliases forwarded from each built-in control's shadow
 surface. `filter-control-field` consistently reaches the select trigger, combobox container, or
@@ -90,9 +135,23 @@ text/date input wrapper; `filter-control-input` reaches the corresponding displa
 Listbox/option aliases apply to select and combobox filters, `filter-control-tags`/
 `filter-control-tag`/`filter-control-tag-label` apply to a `multiple` combobox filter's selected-tag
 chips (`filter-control-tag-label` is capped by that control's own `--tag-max-size`), and
-expand-button/popup apply to date filters. This lets a consumer theme the composed tier from
+expand-button/popup apply to date filters. `filter-control-tag-remove-button`/
+`filter-control-tag-remove-button-base` reach a selected tag's own remove button and its inner icon
+wrapper — the same reach a standalone `lr-combobox`/`lr-select` consumer already has, now available
+from `lr-filter-bar` too, for a consumer re-skinning filter tags as pills who needs the remove
+target inside one to be stylable. This lets a consumer theme the composed tier from
 `lr-filter-bar::part(...)` without depending on the built-in control type selected by a filter
 definition. Custom renderers retain ownership of their own part forwarding.
+
+A `multiple` `'combobox'` filter collapses past its own `max-options-visible` (3 by default, an
+`<lr-combobox>` property this component does not forward) into a localized "+N" overflow indicator,
+the same substance as `lr-select`'s own `multiple`-mode overflow chip. The one remaining difference:
+`lr-select`'s overflow chip carries a second, distinguishing `tag-overflow` part
+(`part="tag tag-overflow tag__base"`) so a consumer can style just that chip; `lr-combobox`'s
+overflow chip carries only the plain `tag` part, with no equivalent token to forward as
+`filter-control-tag-overflow`. Adding one is `<lr-combobox>`'s own surface to grow, not something
+`lr-filter-bar`'s `exportparts` can manufacture for a part its composed child never renders — noted
+here as a known, deliberate gap rather than silently undocumented.
 On a `'checkbox-menu'` filter, `filter-control-field` is the trigger button's own frame — the
 element inside `<lr-button>` that draws the border, background and radius, not the chrome-less
 button host, so a `::part(filter-control-field) { border-color: … }` rule works there exactly as it
@@ -101,7 +160,19 @@ a definition `icon` lands), `filter-control-input` is its selection summary, `fi
 is the trigger's own label text (not a stacked label above the control), `filter-control-listbox` is
 the dropdown's popup surface, `filter-control-option` is one `role="menuitemcheckbox"` row, and
 `filter-control-error` is the revealed required message — rendered by the bar itself, because the
-composed dropdown has no error chrome of its own.
+composed dropdown has no error chrome of its own. The trigger also renders a `with-caret` disclosure
+chevron, matching `lr-select`'s own — forwarded as `filter-control-expand-icon`, the same name a
+select/combobox/date-input filter's own chevron already uses, so one consumer rule styles every
+filter type's expand icon. `filter-control-label-group` reaches the trigger's own label wrapper —
+the flex row this component lays `filter-control-label` and `filter-control-input` out in, which
+also grows to fill the stretched trigger (via `with-caret`) so its content starts at the leading
+edge instead of centring; no other filter type renders this part, since every other type's label and
+input are two independent elements with no shared wrapper of their own. This component does not
+render a stacked label above a `'checkbox-menu'` field the way every other built-in type does:
+every other type's stacked label is rendered by the composed control itself, and there is no
+equivalent shared "stacked label" template inside `<lr-filter-bar>` for this branch to reuse without
+inventing a new one, so `labelVisibility` keeps its narrower meaning here (whether the trigger's own
+baked-in label text is visible or screen-reader-only).
 
 `field` wraps one filter's composed control and its validation spacer inside `controls`; its
 flex-basis is themeable via `--lr-filter-bar-field-basis` (default `var(--lr-size-12rem)`).
@@ -119,12 +190,17 @@ alone, exactly as before this part existed, rather than risking a `part` attribu
 space-separated token list fabricates an unrelated second token.
 
 A `'select'`, `'combobox'` or `'checkbox-menu'` filter's required `options` entries are
-`LyraFilterBarOption { value, label, icon?, searchText? }`. `searchText` is extra text the option
-also matches on, forwarded verbatim to `<lr-option>`'s own `search-text`, so a row can keep a short
-visible `label` ("Urgent") while still matching a long canonical key ("SEV-1 production outage").
-It affects a `'combobox'` filter only: the attribute is written on every choice type's `<lr-option>`,
-but `<lr-select>`'s listbox type-ahead matches the option's `label` alone and never reads it, and a
-`'checkbox-menu'` has no text entry to match against.
+`LyraFilterBarOption { value, label, icon?, searchText?, disabled? }`. `searchText` is extra text
+the option also matches on, forwarded verbatim to `<lr-option>`'s own `search-text`, so a row can
+keep a short visible `label` ("Urgent") while still matching a long canonical key ("SEV-1
+production outage"). It affects a `'combobox'` filter only: the attribute is written on every
+choice type's `<lr-option>`, but `<lr-select>`'s listbox type-ahead matches the option's `label`
+alone and never reads it, and a `'checkbox-menu'` has no text entry to match against. `disabled`
+marks the option non-actionable: forwarded to `<lr-option disabled>` for `'select'`/`'combobox'`
+and to the composed `<lr-dropdown-item disabled>` for `'checkbox-menu'`, so the row renders
+genuinely disabled (no tab/roving stop, no hover/press affordance) and arrow-key navigation already
+steps past it, since that is the composed control's own existing `disabled` behavior. Omitted or
+`false` renders the option exactly as before this field existed.
 `icon` is optional Lit content — a status dot, a type glyph, a flag — rendered into the composed
 `<lr-option>`'s own `start` slot as inert, `aria-hidden` chrome, so it never joins the option's
 accessible name:

package/llms/components/lr-flow-canvas.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 29 parts, 14 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 29 parts, 15 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -47,14 +47,19 @@ import type {
 **Properties:**
 
 - `nodes: readonly FlowNode[] = []` (attribute: false) — each record has readonly `id`, optional
-  `type`, `position`, `data`, `accessibleLabel`, `inputs`, and `outputs`. A missing `position` opts
-  into layered layout. String `data.label` and `data.description` feed the declarative fallback
-  card. Assignment takes a detached, deeply frozen snapshot of plain arrays/records, omitting blank
-  ids and later duplicates first-wins before layout, focus, selection, gestures, companion
-  snapshots, and events. At most the first 10,000 source nodes are retained, with finite nested
-  depth/entry budgets; reassign `nodes` after changes. Replacing the model cancels node-drag and
-  connect gestures whose ids belonged to the old model and silently prunes selected ids that no
-  longer exist.
+  `type`, `position`, `data`, `accessibleLabel`, `inputs`, `outputs`, and `disabled`. A missing
+  `position` opts into layered layout. String `data.label` and `data.description` feed the
+  declarative fallback card. Assignment takes a detached, deeply frozen snapshot of plain
+  arrays/records, omitting blank ids and later duplicates first-wins before layout, focus,
+  selection, gestures, companion snapshots, and events. At most the first 10,000 source nodes are
+  retained, with finite nested depth/entry budgets; reassign `nodes` after changes. Replacing the
+  model cancels node-drag and connect gestures whose ids belonged to the old model and silently
+  prunes selected ids that no longer exist. `disabled` marks a node non-actionable: it keeps its
+  position and card content but cannot be selected/activated by click or keyboard, roving-tabindex
+  navigation (arrow keys, Home/End) steps past it, it cannot be dragged even while
+  `nodes-draggable`, and it is excluded from starting or receiving a new connection while
+  `connectable` (an edge already touching it is left alone). Omitted or `false` renders the node
+  exactly as before this field existed.
 - `edges: readonly FlowEdge[] = []` (attribute: false) — readonly `id`, `source`, `target`, optional
   handle ids, optional drawn `label`, and optional `tone: LyraVariant`. The canonical brand value is
   `brand`; the former `accent` value and `FlowEdgeTone` alias are not part of this contract. Blank
@@ -220,5 +225,7 @@ four above. Set it to `transparent` to opt out of the hover treatment.
 - `part="edge-hit-area"` — The transparent wide pointer target behind an edge.
 - `part="node-control"` — The visually hidden, roving selection button for a node.
 - `--lr-flow-canvas-node-selected-outline-color` — Outline color of a selected node. Default: `var(--lr-color-brand)`.
+- `--lr-flow-canvas-node-disabled-opacity` — Opacity of a node whose `FlowNode` entry sets
+  `disabled`. Default: `var(--lr-opacity-disabled)`.
 
 ---

package/llms/components/lr-gauge.md

@@ -42,6 +42,12 @@ explicitly empty labels remain empty and later labels render normally.
 - `valueText?: string` (attribute `value-text` — overrides both the visible text and the host's
   `aria-valuetext`; an empty string is treated the same as unset and falls back to the numeric
   `value` while removing `aria-valuetext`)
+- `showValue: boolean = true` (attribute `show-value`, not reflected) — whether the decorative
+  `part="value"` caption renders at all; `show-value="false"` omits it the same way an empty
+  `label` already omits `part="label"`. `aria-valuenow`/`aria-valuetext` and the host's accessible
+  name are unaffected either way, since the caption itself is always `aria-hidden`. Mirrors
+  `<lr-progress-bar>`'s/`<lr-progress-ring>`'s own `showValue` name and meaning; the default here
+  is `true` (a gauge's whole purpose is showing the reading it announces) where theirs is `false`.
 - `variant: LyraProgressVariant = 'brand'` (reflected) — the same shared semantic-tone vocabulary
   `<lr-progress-bar>` uses (`'neutral'|'brand'|'success'|'warning'|'danger'`). The fallback color
   whenever `thresholds` is empty or matches nothing.
@@ -58,7 +64,8 @@ explicitly empty labels remain empty and later labels render normally.
 
 **Slots:** none.
 
-**CSS parts:** `base` (the `<svg>`), `track`, `fill`, `value`, `label`
+**CSS parts:** `base` (the `<svg>`), `track`, `fill`, `value` (rendered only while `showValue` is
+true), `label` (rendered only while `label` is non-empty)
 
 **Themeable custom properties:** `--lr-gauge-fill` (fill stroke; overrides `variant`/`thresholds`
 entirely and falls back to the effective variant's shared semantic token —
@@ -75,6 +82,15 @@ entirely and falls back to the effective variant's shared semantic token —
   style="--lr-gauge-fill: var(--lr-color-success)"
 ></lr-gauge>
 <lr-gauge shape="linear" value="0.4" max="1" value-text="72°F"></lr-gauge>
+<!-- compact dashboard meter: a slim, captionless, thresholded row -->
+<lr-gauge
+  shape="linear"
+  size="xs"
+  show-value="false"
+  aria-label="Spend"
+  value="84"
+  max="100"
+></lr-gauge>
 <!-- automatic threshold coloring: same rule, opposite direction -->
 <lr-gauge id="cpu" value="82" label="CPU"></lr-gauge>
 <script>
@@ -118,7 +134,11 @@ entirely and falls back to the effective variant's shared semantic token —
 - no documented component-specific sizing custom property. The host box is fixed em values
   (`8em` radial/ring, `12em`/`1.5em` linear) against the host font size, so `size` is the supported
   way to step it; for a dimension off the ladder, set plain CSS `width`/`height` (or `font-size`)
-  on the element instead.
+  on the element instead. The value/label captions are `em`-sized against that same host font-size,
+  so they shrink right along with the frame at a smaller tier or a smaller host `font-size` —
+  combine a small tier (or a small host `font-size`) with `show-value="false"` for a slim,
+  thresholded dashboard meter, matching `<lr-progress-bar size="xs">`'s footprint but with
+  `role="meter"` and one `thresholds` array instead of a hand-written ratio-to-variant mapping.
 - Divide-by-zero guarded, and radial/linear share one component via the `shape`
   attribute.
 - non-finite `value` text remains blank unless `valueText` supplies a truthful fallback; that

package/llms/components/lr-histogram.md

@@ -37,9 +37,10 @@ Bins `values` into `bins` equal-width buckets and renders as a bar chart (extend
   (`index-axis`), `hiddenDatasets`, `hiddenDatums`, `legendPosition` (`legend-position`),
   `legendMode` (`legend-mode`), `legendDisplay` (`legend-display`), `max`, `min`, `plugins`,
   `withoutAnimation` (`without-animation`), `withoutLegend` (`without-legend`), `withoutTooltip`
-  (`without-tooltip`), `valueFormatter`, `formatter`, `area`, `zoom`, `config`, `height`, `xLabel` (`x-label`),
+  (`without-tooltip`), `valueFormatter`, `formatter`, `tooltipTitleFormatter`,
+  `tooltipFooterFormatter`, `area`, `zoom`, `config`, `height`, `xLabel` (`x-label`),
   `yLabel` (`y-label`), `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`),
-  `stacked`, `dataLabels` (`data-labels`), `stackTotals` (`stack-totals`), `showDataTable`
+  `stacked`, `stackedAxes`, `dataLabels` (`data-labels`), `stackTotals` (`stack-totals`), `showDataTable`
   (`show-data-table`), `dataTableToggle` (`data-table-toggle`), `chartArea` (readonly).
 
 **Methods:** `resetZoom()`, `refreshTheme()`, and `renderChart()` are inherited; `appendSamples(values,
@@ -103,5 +104,9 @@ their semantics, defaults, and gotchas.
 - `values`/`bins`/`seriesLabel` changes join the inherited connected-and-visible redraw path. There is no
   second post-update refresh, so a same-tick disconnect cannot recreate Chart.js on a detached
   canvas and off-screen sample updates do not repaint it.
+- calling `binValues()` directly (not through `<lr-histogram>`, which always passes its own
+  resolved `effectiveLocale`) with an omitted `locale` (or `'auto'`) now resolves to the page's
+  active `setLyraLocale()` locale instead of a hardcoded `'en'`, matching `utilities/format.ts`'s
+  helpers; an app that never calls `setLyraLocale()` sees no change, and an explicit tag still wins.
 
 ---

package/llms/components/lr-icon-button.md

@@ -123,16 +123,24 @@ DOM while at least one top-level slotted element needs the bare-geometry fallbac
 **Themeable custom properties:** `--lr-icon-button-size` (default `2.5rem`) is the **minimum**
 tappable inline and block size of the native button — a floor, not a fixed size. Content larger
 than it grows the button and keeps its own aspect ratio; a small glyph pads out to it. It is a
-library-wide token (declared on `:root` by the token layer, and the shared minimum tappable size
+library-wide token (declared on every `lr-*` host by the shared token layer, and the shared minimum tappable size
 that several other components size their icon-only controls against), so overriding
 `--lr-theme-icon-button-size` globally resizes all of them together. Keep the resolved value at or
-above 24px — see `llms/shared.md`. Lowering the floor for a dense action row (directly via
-`--lr-icon-button-size`, or via `--lr-theme-icon-button-size` on an ancestor to reach a
+above 24px — see `llms/shared.md`. **`--lr-icon-button-size` is element-scoped, unlike every other
+token in this section:** the shared token layer re-declares it on every `lr-*` host's own `:host`,
+so a rule that sets `--lr-icon-button-size` on an ancestor wrapper is reset the moment it crosses
+into any intervening `lr-*` component and never reaches a `<lr-icon-button>` composed inside it
+(e.g. one slotted through `<lr-popover>`). The only two levers that actually reach it are: setting
+`--lr-icon-button-size` directly on the icon button element itself, where no intervening component
+sits between the rule and the property; or setting `--lr-theme-icon-button-size` on an ancestor,
+which the shared layer reads through `var()` at every level and which therefore reaches a
 `<lr-icon-button>` composed inside another component, e.g. `<lr-copy-button>`/
-`<lr-message-actions>`) is safe even below 24px: a coarse-pointer/no-hover media rule floors the
-RENDERED hit area back at 2.75rem/44px regardless of how far the override lowered it, so the
-control stays comfortably tappable the moment the pointer reaching it is a finger rather than a
-mouse. `--lr-icon-button-radius` (default `--lr-radius`) is the
+`<lr-message-actions>`. Lowering the floor for a dense action row through either lever is safe even
+below 24px: a coarse-pointer/no-hover media rule floors the RENDERED hit area back at 2.75rem/44px
+regardless of how far the override lowered it, so the control stays comfortably tappable the moment
+the pointer reaching it is a finger rather than a mouse. `--lr-icon-button-radius` (default
+`--lr-radius`) is not re-declared anywhere in the shared layer, so — like every other token below —
+it inherits normally from an ancestor even through an intervening component; it is the
 `[part='button']` corner radius, retunable without a `::part(button)` rule — the same
 `--lr-button-radius` pattern; `lr-icon-button` has no `size` tiers, so there is no per-tier gap
 counterpart to it. The internal control sets `font: inherit`, so an `em`-sized slotted glyph takes

package/llms/components/lr-input.md

@@ -153,7 +153,9 @@ writes remain valid and read back as booleans. Markup uses `autocorrect="on"` /
   before. Omitted, `0`, or a non-finite value means no debounce at all: `lr-input-settled` never
   fires. A pending debounce is flushed immediately by `change`/Enter/blur (so a blur never drops
   the last keystroke) and cancelled with no stray settle by disconnection, the built-in clear
-  button, and a programmatic `value` write. Shares its `DebounceController` primitive with
+  button, and a programmatic `value` write that changes the value. A write of the value already
+  held leaves it pending, so a framework binding that writes the just-typed value back on each
+  render (the controlled-input pattern) still settles. Shares its `DebounceController` primitive with
   `lr-filter-bar`'s own per-filter `debounce` and with `lr-textarea`'s identical property
 - `name`/`disabled`/`required` (from `FormAssociated`)
 

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

@@ -28,9 +28,10 @@ of every entry in these lists.**
 **Properties:** `description`, `grid`, `axes`, `compact`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
 (`legend-position`), `hiddenDatums`, `legendMode` (`legend-mode`), `legendDisplay` (`legend-display`),
 `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
-`stacked`, `withoutAnimation` (`without-animation`),
+`stacked`, `stackedAxes`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
-`yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
+`yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`,
+`tooltipTitleFormatter`, `tooltipFooterFormatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
 (`data-labels`), `stackTotals` (`stack-totals`), `config`, `showDataTable`
 (`show-data-table`), `dataTableToggle` (`data-table-toggle`), `chartArea` (readonly), and `chart`.

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

@@ -23,6 +23,19 @@ tooltips (native SVG `<title>`, no positioning JS) — not a full `lr-chart` rep
 zoom/pan, no pie/doughnut/radar/scatter/bubble types, no horizontal/dual-y-axis, no raw-config
 passthrough). Not a subclass of `LyraChart`.
 
+Deliberate omissions, assessed and not implemented: `lr-chart`'s per-series `LyraChartSeries.stack`
+group and per-axis `stackedAxes` have no `lr-lite-chart` counterpart. `stacked` here is already
+chart-wide only (see below) and this component has exactly one value scale — no `y2` — so "an
+unstacked overlay on a second axis," the motivating case for `stackedAxes`, has no equivalent
+shape to express. A per-series stack-group id would also need the hand-rolled SVG bar-geometry
+pass (linear/sqrt/log stack compression, `minBarHeight`) to track independent running offsets per
+group instead of one per category, which is a materially larger, higher-risk change than this
+component's existing single-stack model. `tooltipTitleFormatter`/`tooltipFooterFormatter` are
+similarly absent: this component's hover tooltip is a native SVG `<title>` on each mark — one
+self-contained string per mark, generated by `pointText` — not a Chart.js-style multi-item tooltip
+with separate title/body/footer regions for several datasets sharing a hovered category, so there
+is no "every item in the tooltip" surface to hook a title or footer formatter onto.
+
 **Properties:**
 - `type: LyraLiteChartType = 'bar'` — `'bar' | 'line'`
 - `labels: readonly string[] = []` (attribute: false)

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 13 parts, 24 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 13 parts, 25 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`
 
 ---
@@ -159,6 +159,12 @@ this listbox together with every other floating surface. `--lr-overlay-radius` r
 only as the middle arm of this component's own `--lr-locale-picker-radius`, which still wins when
 set: a component-scoped override outranks the shared family, never the other way round.
 
+`--lr-positioning-strategy` (16.0.0) — the listbox reads this same cascading `absolute`/`fixed`
+override documented on `<lr-popover>` when it is (re)positioned, falling back to its own `fixed`
+default when nothing is set. There is no per-instance `positioning-strategy` property on
+`<lr-locale-picker>`; set the custom property on `:root`, a theme, or one clipping ancestor to
+change every unset locale picker beneath it.
+
 **Optional peer deps:** none directly — each row's `<lr-flag>` degrades to an empty render (no
 peer warning duplication; `lr-flag` itself already logs one) when the optional
 `@aceshooting/lyra-flags` package isn't installed and `showFlags` is left on.

package/llms/components/lr-mention-popover.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 6 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 6 parts, 7 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`
 
 ---
@@ -41,6 +41,11 @@ preserving null readback; an explicitly empty query remains empty.
   pre-`query`-filtering. Assignment takes a shallow frozen snapshot. Runtime rows without a string
   `label` remain in that diagnostic snapshot but are omitted from filtering/rendering before the
   built-in or custom predicate runs, so one malformed provider row cannot take down valid siblings.
+  An entry's `disabled` marks that row non-actionable: `aria-disabled="true"` replaces its
+  selected/active affordances, activating it (click, or Enter/Tab while highlighted) commits
+  nothing and emits no `lr-mention-select`, and ArrowDown/ArrowUp highlighting -- including the
+  default pre-highlighted first row -- steps past it instead of landing on it. Omitted or `false`
+  renders the row exactly as before this field existed.
 - `query: string = ''` — the text typed since the trigger character; drives the built-in filtering
   (see `filter`).
 - `open: boolean = false` (reflected)
@@ -85,7 +90,7 @@ preserving null readback; an explicitly empty query remains empty.
   disconnect/adoption, a newer transfer, or failed ownership resolves `false` without moving focus.
 
 **Exported types:** `LyraMentionItem { suggestionId: string; label: string; description?: string;
-icon?: string }`; `LyraMentionFilter = (item: LyraMentionItem, query: string) => boolean`;
+icon?: string; disabled?: boolean }`; `LyraMentionFilter = (item: LyraMentionItem, query: string) => boolean`;
 `LyraMentionFocusOptions { ownsFocus?: () => boolean }`;
 `LyraMentionSelectDetail { suggestionId: string; index: number; label: string }`.
 
@@ -106,7 +111,9 @@ renders `open="false"` on first paint)
 `var(--lr-color-brand-quiet)`) — background of the hovered or `[data-active]`
 (keyboard-highlighted) suggestion row. Component-scoped indirection over the shared
 `--lr-color-brand-quiet` token, so a consumer can retheme just this highlighted/active row without
-repainting every other component that reuses the same shared token. Plus shared tokens —
+repainting every other component that reuses the same shared token.
+`--lr-mention-popover-option-disabled-opacity` (default `0.5`) — opacity of a row whose `items`
+entry sets `disabled`. Plus shared tokens —
 `--lr-space-xs`/`-s`/`-m` (popup padding,
 row padding/gap), `--lr-radius`
 (row corners — the popup's own corner is the overlay family's, below),
@@ -123,6 +130,12 @@ The popup is a floating surface and paints from the **shared overlay-surface fam
 declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
 surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.
 
+`--lr-positioning-strategy` (16.0.0) — the popup reads this same cascading `absolute`/`fixed`
+override documented on `<lr-popover>` when it is (re)positioned, falling back to its own `fixed`
+default when nothing is set. There is no per-instance `positioning-strategy` property on
+`<lr-mention-popover>`; set the custom property on `:root`, a theme, or one clipping ancestor to
+change every unset mention popover beneath it.
+
 **Optional peer deps:** none.
 
 ```html

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

@@ -97,6 +97,13 @@ an out-of-syntax value falls back cleanly instead of invalidating the whole decl
 without `CSS.registerProperty` degrades to "use `100%`, not `none`".) A menu contained by
 `<lr-dropdown>` sizes from its dropdown and is unaffected by both names.
 
+**`--lr-positioning-strategy`** (16.0.0) — the private submenu surface reads this same cascading
+`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
+its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
+property on `<lr-menu>`; set the custom property on `:root`, a theme, or one clipping ancestor to
+change every unset submenu beneath it. A menu contained by `<lr-dropdown>` is positioned by the
+dropdown instead and is unaffected.
+
 **Methods:** no menu-specific public overlay methods. Use `<lr-dropdown>`'s `show()`/`hide()` and
 `open` state for an overlay. Menu-item submenu methods remain public because they drive a row's
 nested disclosure.

package/llms/components/lr-menu.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 3 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 3 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-menu-item`, `lr-dropdown-item` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -97,6 +97,13 @@ an out-of-syntax value falls back cleanly instead of invalidating the whole decl
 without `CSS.registerProperty` degrades to "use `100%`, not `none`".) A menu contained by
 `<lr-dropdown>` sizes from its dropdown and is unaffected by both names.
 
+**`--lr-positioning-strategy`** (16.0.0) — the private submenu surface reads this same cascading
+`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
+its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
+property on `<lr-menu>`; set the custom property on `:root`, a theme, or one clipping ancestor to
+change every unset submenu beneath it. A menu contained by `<lr-dropdown>` is positioned by the
+dropdown instead and is unaffected.
+
 **Methods:** no menu-specific public overlay methods. Use `<lr-dropdown>`'s `show()`/`hide()` and
 `open` state for an overlay. Menu-item submenu methods remain public because they drive a row's
 nested disclosure.

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

@@ -89,3 +89,13 @@ or an ancestor, or reach a built-in's composed native control directly through
 `::part(regenerate-button__control)` / `::part(edit-button__control)`. A coarse-pointer/no-hover
 media rule then floors the rendered hit area at 2.75rem/44px regardless of how far a dense-row
 override lowered it, so the shrink is safe on a touch device.
+
+**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only actions are composed
+`<lr-icon-button>`s, so a part naming one of them now names the composed child's HOST, which paints
+nothing. A `border`, `background` or `border-radius` set on it is silently dead — only `color` still
+appears to work, because it inherits, which makes such a rule look half-alive rather than broken.
+Set `--lr-icon-button-background`/`-color`/`-border`/`-radius` (and their `-hover`/`-active`
+variants) on this element or an ancestor instead: the composed control reads those public tokens
+ahead of any default this component supplies. For SIZE use `--lr-theme-icon-button-size`, not
+`--lr-icon-button-size` — every `LyraElement` re-declares the latter on its own `:host`, so it never
+reaches a composed child (see `llms/tokens.md`).

package/llms/components/lr-model-select.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 15 parts, 25 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 15 parts, 26 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`
 
 ---
@@ -42,7 +42,11 @@ focus move.
 
 **Exported types:**
 
-- `LyraCatalogEntry { id: string; label: string }` — the shared minimum row vocabulary.
+- `LyraCatalogEntry { id: string; label: string; disabled?: boolean }` — the shared minimum row
+  vocabulary. `disabled` marks a row non-actionable: `aria-disabled="true"` replaces its
+  selected/active affordances, activating it (click or keyboard) commits nothing and changes no
+  state, and arrow-key/Home/End active-descendant navigation steps past it instead of landing on
+  it. Omitted or `false` renders the row exactly as before this field existed.
 - `LyraCatalog<T extends LyraCatalogEntry = LyraCatalogEntry> = readonly string[] | readonly T[]`
   — a homogeneous catalog shared by model-select, voice-picker, and composed controls. String
   shorthand uses the same string for both id and label; readonly tuples/arrays are accepted. Ids
@@ -236,7 +240,8 @@ use, not on `:host`, so it isn't tied to `size`. The selected row
 `--lr-model-select-option-selected-border` and `--lr-model-select-option-selected-color` (both
 `var(--lr-color-brand)`), and `--lr-model-select-option-selected-font-weight`
 (`var(--lr-font-weight-semibold)`), all inline `var()` fallbacks so the selected row is rethemeable
-without hijacking `--lr-color-brand`. `--lr-model-select-max-inline-size` (default
+without hijacking `--lr-color-brand`. `--lr-model-select-option-disabled-opacity` (default `0.5`)
+— opacity of an option row whose catalog entry sets `disabled`. `--lr-model-select-max-inline-size` (default
 `var(--lr-size-24rem)`) publishes the host's own width ceiling, which was previously a hard-wired
 literal: set a length to retune it, or `none` to let the control fill its container the way
 `lr-select` does. Like every other name here it is read as a `var()` fallback and never declared on

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

@@ -39,7 +39,14 @@ properties apply. `step` is native seconds; `showPicker()`, `stepUp()`, and `ste
 native-wrapper behavior. The control row carries `base input-wrapper time-input` part tokens on one
 node. Its native picker UI and AM/PM presentation are browser-owned and intentionally unstyled.
 The inherited `--lr-input-*` theme inputs therefore remain configurable from an ancestor theme
-wrapper without being shadowed by the subclass.
+wrapper without being shadowed by the subclass. Among those inherited properties and methods:
+`defaultValue: string = ''` (attribute `value`, reflected) is the reset value, and
+`customError: string | null = null` (attribute `custom-error`, reflected) is a consumer-supplied
+validation message. `getForm()` returns the browser-resolved form owner, including an external
+owner selected by `form`; `setCustomValidity(message)` sets or clears `customError` without
+discarding intrinsic validity; `resetValidity()` clears only that consumer layer and recomputes
+the current intrinsic constraints, leaving `value`/`defaultValue` and prior interaction state
+unchanged.
 
 **Events:** native-style `input` and `change`; bubbling, composed `focus` and `blur` bridges; the
 `lr-input` / `lr-change` aliases with `{ value }`;

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

@@ -46,7 +46,14 @@ action-height ladder as `lr-input` instead of remaining at the default tier for
 identical meaning. This component changes the mapped defaults to `appearance='outlined'`,
 `inputMode='numeric'`, and `step=1`. `clearable` (and its `with-clear` spelling),
 `passwordVisible` (`password-visible`), and `minlength`/`maxlength`/`pattern` are inherited but
-inert — see gotchas.
+inert — see gotchas. Also inherited from `lr-input`, with identical meaning:
+`defaultValue: string = ''` (attribute `value`, reflected) — the reset value; and
+`customError: string | null = null` (attribute `custom-error`, reflected) — a consumer-supplied
+validation message. `getForm()` returns the browser-resolved form owner, including an external
+owner selected by `form`; `setCustomValidity(message)` sets or clears `customError` without
+discarding intrinsic validity; `resetValidity()` clears only that consumer layer and recomputes
+the current intrinsic constraints, leaving `value`/`defaultValue` and prior interaction state
+unchanged.
 
 Stepper switches:
 

package/llms/components/lr-option.md

@@ -155,6 +155,18 @@ An async `source` row can carry the same two fields (`start`, `end`) alongside i
   that window instead, since the value is not yet known to be unmatched at all
 - `appearance: 'filled' | 'outlined' | 'filled-outlined' = 'outlined'` (reflected)
 - `placement: 'top' | 'bottom' = 'bottom'` (reflected; flip/shift can still keep the listbox in view)
+- `positioningStrategy: PlaceStrategy = 'fixed'` (attribute `positioning-strategy`, reflected) —
+  the CSS positioning scheme the listbox is laid out with, spelled the same as on `lr-select`,
+  `lr-popover`, `lr-dropdown`, `lr-tooltip` and `lr-color-picker`. `fixed` is this control's
+  default and what it has always rendered: it positions against the viewport and escapes most
+  clipping ancestors, which suits a typeahead list that usually sits inside a scrollable region.
+  `absolute` positions against the nearest containing block and scrolls with it. An unsupported
+  value resolves to the default. Like `placement`, a change takes effect the next time the listbox
+  opens. When the instance sets nothing, the cascading `--lr-positioning-strategy` custom property
+  (`absolute`/`fixed`, set on `:root`, a theme, or one clipping ancestor) is honoured ahead of the
+  default; an explicit instance value always wins. There is deliberately no `hoist` alias here:
+  unlike on `lr-select`, where it is Shoelace's established spelling, it would be a boolean
+  defaulting to `true`, so its attribute could only ever express the value the control already has
 - `clearable: boolean = false` (reflected) — displays the clear button while there is something to
   clear on **either** axis this control owns: a committed selection, or _visible_ filter text. See
   "the clear button covers two axes" below

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

@@ -154,6 +154,12 @@ The exact-320px RTL story covers an eight-cell row and an unbroken localized lab
 horizontal reachability for every cell.
 The internal role token `--lr-otp-input-segment-size` supplies that `2.5em` default and can be
 retuned through `--lr-theme-otp-input-segment-size` when the `--segment-size` override is absent.
+Like `--lr-icon-button-size`, `--lr-otp-input-segment-size` is element-scoped: the shared token
+layer re-declares it on every `lr-*` host, so a rule that sets it on an ancestor wrapper is reset at
+the first intervening `lr-*` component and never reaches a nested `<lr-otp-input>`. Set it directly
+on the element, or set `--lr-theme-otp-input-segment-size` on an ancestor to resize every OTP input
+in the subtree at once — the retained per-cell hooks below are not re-declared anywhere in the
+shared layer and inherit normally.
 
 The retained per-cell hooks are `--lr-otp-input-segment-fill` (default `transparent`),
 `--lr-otp-input-segment-border-color` (default `var(--lr-color-border)`), and

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

@@ -28,9 +28,10 @@ of every entry in these lists.**
 **Properties:** `description`, `grid`, `axes`, `compact`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
 (`legend-position`), `hiddenDatums`, `legendMode` (`legend-mode`), `legendDisplay` (`legend-display`),
 `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
-`stacked`, `withoutAnimation` (`without-animation`),
+`stacked`, `stackedAxes`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
-`yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
+`yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`,
+`tooltipTitleFormatter`, `tooltipFooterFormatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
 (`data-labels`), `stackTotals` (`stack-totals`), `config`, `showDataTable`
 (`show-data-table`), `dataTableToggle` (`data-table-toggle`), `chartArea` (readonly), and `chart`.