@aceshooting/lyra-ui 16.0.0 → 18.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`
 
 ---
@@ -21,7 +21,43 @@ Dashboard filter row that composes Lyra inputs and removable chips, with reset a
 Choice option entries must expose string `value` and `label` data fields; malformed entries are
 omitted independently, while supplied empty strings remain valid. A custom definition requires its
 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.
+siblings remain available. Exceptions thrown by an admitted trusted renderer still propagate. A
+chip-only definition requires neither options nor an adapter — a stable filter ID and a label are
+the whole schema, since a malformed `formatValue`/`isEmpty` still has a correct fallback and so is
+guarded where it is used rather than rejected outright.
+
+**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` |
+| `'chip'` | none — renders no control |
+
+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:**
 
@@ -47,8 +83,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 +125,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 +139,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 +164,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 +194,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:
@@ -146,7 +226,9 @@ same-named counterparts (with `combobox`'s `multiple` opting into a multi-value
 `'date'`/`'date-range'` both map to `<lr-date-input>` (single vs. `mode="range"`), and `'text'` maps
 to `<lr-input>` for an open-ended free-text query rather than a closed choice set. A `'text'`
 filter's value is the raw query string, verbatim, and its chip shows exactly that string — the same
-text the user typed, not a truncated or normalized form.
+text the user typed, not a truncated or normalized form. `'chip'` is the one type that renders no
+control at all (see **Chip-only filters** below): its value belongs to a widget elsewhere on the
+page, so the bar renders only its active-filter chip and gives it no toolbar cell.
 
 Every built-in (non-`'custom'`) filter definition additionally accepts optional `size: LyraSize`,
 `icon: unknown` and `labelVisibility: 'visible' | 'hidden'` fields, and every one whose composed
@@ -362,12 +444,89 @@ const filters: LyraFilterBarFilterDefinition[] = [
 The custom renderer returns a Lit `TemplateResult`; the filter bar places it in its
 `filter-control` part and re-renders it whenever the controlled value or validation state changes.
 
+### Chip-only filters
+
+Use `type: 'chip'` when the value is already owned by a widget elsewhere on the page — a calendar
+heatmap cell, a map selection, a chart brush — and the bar's job is only to *show* that the filter
+is applied and to let the user take it off. Unlike `type: 'custom'`, which still renders a control
+inside the toolbar, a chip-only filter renders **no control and no toolbar cell at all**: no `field`
+wrapper is emitted for it, so `lr-filter-bar::part(field)` and `::part(field-<filterId>)` never
+match one and a bar whose filters are *all* chip-only shows no empty column — its `controls` row
+still holds the reset button (the "clear all" action such a bar needs), the `end` slot, and the
+loading spinner, exactly like a bar with no filters at all.
+
+Everything else is unchanged from any other filter type. The value lives in `value` under its own
+filter ID, rides every `lr-input`/`lr-reset` detail, counts toward `hasActiveFilters` (so it enables
+the reset button) and toward `invalidFilterIds` when the definition is `required`, renders a
+removable active-filter chip subject to `activeFiltersDisplay`, and is cleared both by removing that
+chip and by `reset()`. A `required` chip-only filter is honoured in **bookkeeping only**: it joins
+`invalidFilterIds`, fails `checkValidity()` and moves `lr-validity-change`, but renders no inline
+error, because the bar renders no element of its own for it — the owning widget is responsible for
+its own error affordance. The inherited `placeholder` is inert here for the same reason it is for
+`type: 'custom'`: there is no field to place it in.
+
+A chip-only definition adds three optional fields of its own:
+
+```ts
+type: 'chip';
+formatValue?: (value: LyraFilterBarFieldValue, locale: string) => string;
+clearValue?: LyraFilterBarFieldValue;
+isEmpty?: (value: LyraFilterBarFieldValue) => boolean;
+```
+
+`formatValue` produces the chip's text, and its `locale` argument is the bar's `effectiveLocale` —
+the same locale every built-in type's own chip formatting and a custom adapter's `formatValue`
+already receive, and the reason a chip-only value (normally an already-formatted string such as a
+localized date) can be localized by the caller. That output is caller data, so — like a filter's
+own label — the bar never routes it through its own localization. Omitted, the fallback ladder is
+the one a custom adapter's omitted `formatValue` uses: a string array renders as a localized
+conjunction list, anything else renders verbatim through `String(value)`, and an unset value renders
+as the empty string. Verbatim is exact: a chip-only value is never run through the date branch that
+localizes a `'date'`/`'date-range'` chip, so an ISO day is not silently reformatted and a value
+containing a slash is not mangled.
+
+`clearValue` is what a chip removal (and `clearFilter()`) writes, defaulting to the empty string —
+what every non-multi built-in type writes. Declare an empty array for an array-valued chip-only
+filter. `isEmpty` overrides the built-in emptiness rule (absent, `false`, the empty string and the
+empty array are empty; everything else is set). **A domain sentinel must pair the two**: declaring
+a sentinel clear value without a matching `isEmpty` leaves the bar reading the "cleared" value as
+still set, so it keeps rendering a chip for it — the identical pairing a custom adapter's own
+`clearValue`/`isEmpty` documents. With the pair declared, the sentinel is never stored in `value`
+(cleared keys are omitted) and an absent key reads back as the sentinel for the owning widget.
+
+```ts
+const filters: LyraFilterBarFilterDefinition[] = [
+  { filterId: "query", label: "Query", type: "text" },
+  {
+    filterId: "day",
+    label: "Day",
+    type: "chip",
+    formatValue: (value, locale) =>
+      new Intl.DateTimeFormat(locale, {
+        dateStyle: "medium",
+        timeZone: "UTC",
+      }).format(new Date(`${String(value)}T00:00:00Z`)),
+  },
+];
+
+// The calendar heatmap beside the bar owns the value; the bar only shows and removes it.
+heatmap.addEventListener("app-select-day", (event) => {
+  const { isoDate } = (event as CustomEvent<{ isoDate: string }>).detail;
+  bar.value = { ...bar.value, day: isoDate };
+});
+bar.addEventListener("lr-input", (event) => {
+  const { value } = (event as LyraFilterBarInputEvent).detail;
+  heatmap.selectedDay = (value["day"] as string | undefined) ?? "";
+});
+```
+
 **TypeScript:** `LyraFilterBar<Defs extends readonly LyraFilterBarFilterDefinition[] =
 readonly LyraFilterBarFilterDefinition[]>` — `value` and the `lr-input`/`lr-reset` detail `value`
 narrow to a record keyed per `filterId`, whose value type follows that filter's own definition (a
 `'select'`, a non-`multiple` `'combobox'`, `'text'`, `'date'`, and `'date-range'` narrow to
 `string`; a `'checkbox-menu'` and a `multiple: true` `'combobox'` narrow to `readonly string[]`; a
-`'custom'` filter keeps the full unconstrained field value). Declare the schema with `as const
+`'custom'` filter keeps the full unconstrained field value, and so does a `'chip'` filter, whose
+value is owned by a widget this component never renders). Declare the schema with `as const
 satisfies readonly LyraFilterBarFilterDefinition[]` and type the element as
 `LyraFilterBar<typeof FILTERS>` to pick it up. Types only; the runtime is unchanged, and an untyped
 `<lr-filter-bar>` keeps today's `LyraFilterBarValue` (`Readonly<Record<string, string | readonly

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

@@ -69,7 +69,8 @@ button whose purpose isn't generic.
 Host `aria-haspopup` and `aria-expanded` values are forwarded reactively to the shadow-internal
 native button. `aria-pressed` (`true`, `false`, `mixed`) supports icon-only toggle actions such as
 mute, favorite, or pin, and reaches the `<button>` rendering only — a link icon-button (`href` set)
-never receives it, since `role="link"` has no pressed state; `aria-current` (`page`, `step`,
+never receives it, since `role="link"` has no pressed state (that carve-out arrived in **16.0.0**;
+earlier versions forwarded it onto the anchor too); `aria-current` (`page`, `step`,
 `location`, `date`, `time`, `true`, `false`) is global and supports current-item icon buttons such
 as an active nav/pagination target in both renderings. Both follow attribute
 changes, removal, and button/link replacement without changing the native role of an enabled
@@ -123,16 +124,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.