@aceshooting/lyra-ui 16.0.0 → 17.0.0

package/llms/components/lr-chart.md

@@ -92,8 +92,14 @@ structured points retain their y-value formatting.
 - `labels: readonly string[] = []` (attribute: false)
 - `datasets: readonly LyraChartSeries[] = []` (attribute: false) — `LyraChartSeries { readonly
   label: string; readonly data?: readonly (number|null)[]; readonly points?: readonly
-  LyraChartPoint[]; readonly color?: string|readonly string[]; ... }`. The deprecated `Series` and
-  `ChartPoint` names were removed in 9.0.0 — import `LyraChartSeries`/`LyraChartPoint` instead.
+  LyraChartPoint[]; readonly color?: string|readonly string[]; readonly stack?: string; ... }`. The
+  deprecated `Series` and `ChartPoint` names were removed in 9.0.0 — import
+  `LyraChartSeries`/`LyraChartPoint` instead.
+  - `stack` is a Chart.js dataset `stack` group id: series sharing one `stack` value on the same
+    (stacked) axis accumulate into one stack; a different id starts an independent stack Chart.js
+    draws side by side with the first on that axis. Omitted series share one implicit group, so
+    every chart written before `stack` existed sums exactly as it always did. Only meaningful on an
+    axis that is actually stacked — see `stacked`/`stackedAxes` below.
   `LyraChartPoint { readonly x: number; readonly
   y: number; readonly r?: number; readonly label?: string }`: `r` is the bubble
   radius, and the optional per-point `label` is retained by events, CSV export, keyboard
@@ -188,6 +194,16 @@ structured points retain their y-value formatting.
   and the stack's own `axis`, but no `datasetIndex` and no `seriesLabel` — naming the topmost
   series would make a unit-switching formatter render that one series' unit for a cross-series
   number. `lr-lite-chart`'s total cells drop the same two fields.
+- `tooltipTitleFormatter?: LyraChartTooltipGroupFormatter` (attribute: false) — tooltip title
+  formatter (e.g. a scatter point's own name). `LyraChartTooltipGroupFormatter = (items:
+  readonly LyraChartFormatterContext[]) => string`: unlike `formatter`, which runs once per item,
+  this runs once per tooltip render and receives every hovered item's context at once (one entry
+  per dataset the tooltip covers, each in the same shape `formatter`'s `'tooltip'` surface already
+  produces). Unset (the default) leaves Chart.js's own default title — the shared category label.
+- `tooltipFooterFormatter?: LyraChartTooltipGroupFormatter` (attribute: false) — tooltip footer
+  formatter (e.g. a category's stack total under the items), in the same shape and calling
+  convention as `tooltipTitleFormatter`. Unset (the default) leaves Chart.js's own default: no
+  footer.
 - `area: boolean = false` — chart-wide default for whether line-type series fill the region under
   their line; a series's own `fill` overrides it, rendered with a translucent version of its color
 - `zoom: boolean = false` — wheel/drag/pinch zoom on the `x` axis only (pan disabled, and the zoom
@@ -202,6 +218,14 @@ structured points retain their y-value formatting.
 - `stacked: boolean = false` — stacks the `x`/`y`(/`y2`) scale entries `buildScales()` returns; only
   meaningful for `bar`/`line` types (scatter/bubble's linear `x` scale and the radial `r` scale used
   by radar/polar-area are out of scope)
+- `stackedAxes?: Partial<Record<'y' | 'y2', boolean>>` (attribute: false) — per-value-axis override
+  of `stacked`, keyed by `'y'`/`'y2'`. An axis absent from this record — including every axis when
+  the whole property is unset — falls back to `stacked`, so a chart that never sets this renders
+  byte-identically to before. Lets a `stacked` bar series on the primary axis sit next to an
+  unstacked overlay series on `y2` (via `LyraChartSeries.axis: 'y2'`): e.g. `stacked` plus
+  `stackedAxes: { y2: false }`. The shared categorical axis (`x` for a vertical bar/line, or `y`
+  under a horizontal `indexAxis`) has no entry of its own — it always mirrors the resolved `'y'`
+  value, matching Chart.js's own paired index/value-scale stacking contract.
 - `withoutAnimation: boolean = false` (attribute `without-animation`, reflected) — disables Chart.js
   construction animation; reduced-motion preference also disables it regardless of this value
 - `withoutTooltip: boolean = false` (attribute `without-tooltip`, reflected) — disables the
@@ -214,14 +238,20 @@ structured points retain their y-value formatting.
   `feature-warning` plus assertive announcement explains the nonfatal limitation. The screen-reader
   equivalent is the always-present accessible data table (`show-data-table` makes it visible) —
   labels are a purely visual, canvas-only addition and add no new a11y surface.
-- `stackTotals: boolean = false` (attribute `stack-totals`) — with `stacked` (bar/line only), draws
-  the per-category stack total above each stack, via the same `chartjs-plugin-datalabels` peer.
-  Null/undefined points are skipped; a category whose every value is null shows no total (not
-  `0`). The generated accessible table receives the same formatted total column; a dual-axis stack
-  receives separately labelled primary- and secondary-axis total columns. The table totals do not
-  depend on the optional visual-label peer being installed. If that peer is unavailable, the chart
-  retains its core rendering and generated table totals while a localized nonfatal warning explains
-  that the canvas labels cannot be drawn.
+- `stackTotals: boolean = false` (attribute `stack-totals`) — on an actually-stacked axis (`stacked`
+  or `stackedAxes`, bar/line only), draws the per-category stack total above each stack, via the
+  same `chartjs-plugin-datalabels` peer. Computed per `LyraChartSeries.stack` group as well as per
+  axis: two stack groups sharing one axis each get their own total, drawn above their own topmost
+  dataset, and a dataset on an axis that isn't stacked (e.g. an unstacked `stackedAxes` overlay)
+  never gets one. Null/undefined points are skipped; a category whose every value is null shows no
+  total (not `0`). The generated accessible table receives one formatted total column per stacked
+  axis (a dual-axis stack gets separately labelled primary- and secondary-axis columns); with
+  multiple stack groups on one axis, that column still totals only the implicit group of series
+  that never set their own `stack` id — a per-group breakdown is available programmatically but not
+  yet surfaced as extra table columns. The table totals do not depend on the optional visual-label
+  peer being installed. If that peer is unavailable, the chart retains its core rendering and
+  generated table totals while a localized nonfatal warning explains that the canvas labels cannot
+  be drawn.
 - `config?: LyraChartConfiguration` (attribute: false) — peer-neutral configuration structurally
   compatible with Chart.js's `ChartConfiguration`, deep-merged over the generated
   config; any nested key wins without clobbering sibling generated keys. This is the raw Chart.js
@@ -542,8 +572,9 @@ announced. In particular, unavailable data labels do not remove generated table
   pending. Independently, `updated()` only reaches
   Chart.js when at least one of `type`, `labels`, `datasets`, `description`, `grid`, `axes`, `compact`, `indexAxis`,
   `label`, `hiddenDatasets`, `legendPosition`, `min`, `max`, `plugins`, the internal resolved auto legend
-  position, `valueFormatter`, `formatter`, `area`, `height`, `xLabel`, `yLabel`, `y2Label`, `beginAtZero`,
-  `stacked`, any `without*` control, `dataLabels`, `stackTotals`, `config`, the parsed
+  position, `valueFormatter`, `formatter`, `tooltipTitleFormatter`, `tooltipFooterFormatter`, `area`,
+  `height`, `xLabel`, `yLabel`, `y2Label`, `beginAtZero`,
+  `stacked`, `stackedAxes`, any `without*` control, `dataLabels`, `stackTotals`, `config`, the parsed
   slotted config, `zoom`, `locale`, `strings`, or the internal loading state actually changed in
   that update (so an
   unrelated property/state update, or a bare `requestUpdate()`, draws nothing). Resize callbacks

package/llms/components/lr-citation-badge.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** 4 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **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`
 
 ---
@@ -75,6 +75,12 @@ The anchored source-preview popover is a floating surface and paints from the **
 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 source-preview popover 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-citation-badge>`; set the custom property on `:root`, a theme, or one clipping
+ancestor to change every unset citation badge beneath it.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-code-block.md

@@ -123,6 +123,27 @@ header gap — a rule that sets `display` on it must qualify itself with `:not([
 `line-button` (a gutter line-number button, only rendered while `activatableLines` and `lineNumbers`
 are both set)
 
+**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only action is a composed
+`<lr-icon-button>`, so the part naming that action 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`).
+
+**Border reaches the composed copy control the same way background/color/radius do.** This
+component paints no resting border of its own, so it relays no `--_lr-icon-button-border-default`
+into the copy control's private fallback tier — but that absence is not a gap. The public
+`--lr-icon-button-border` (and its `-hover`/`-active` variants) is the FIRST arm of the token
+chain, resolved by ordinary custom-property inheritance regardless of whether this component
+relays a default for that same property, so setting it on this element or an ancestor reaches the
+copy control exactly as the background/color/radius tokens do. A component with no resting
+border simply has no default to relay, which is different from border theming being broken. Size
+remains the one exception that does not cross this way: use `--lr-theme-icon-button-size`, never
+`--lr-icon-button-size`, as noted above.
+
 **Themeable custom properties:** `--lr-code-block-max-height` (default `none` — an independently
 settable scroll cap; a `max-height` attribute writes the same property inline on `body` and wins),
 `--lr-code-block-font` (default

package/llms/components/lr-color-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** 43 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 43 parts, 34 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`
 
 ---
@@ -90,12 +90,15 @@ and:
   applies to the whole string, function names included (`RGB(255, 0, 0)`)
 - `swatches: string | string[] | LyraColorPickerSwatch[] = ''` — a predefined palette, given as a
   `;`-separated string, an array of colour strings, or an array of
-  `{ color: string; label?: string }` objects. Any colour the picker can parse is accepted; blank
-  entries are dropped. An entry that is _not_ parseable is kept in the list and still renders a
-  swatch — it just paints no colour (the bare checkerboard) and clicking it does nothing, so filter
-  the palette yourself if that matters. `label` becomes the swatch's accessible name; a missing,
-  empty, or whitespace-only label falls back to announcing the raw colour string. The palette
-  container renders only while the normalized list is non-empty
+  `{ color: string; label?: string; disabled?: boolean }` objects. Any colour the picker can parse
+  is accepted; blank entries are dropped. An entry that is _not_ parseable is kept in the list and
+  still renders a swatch — it just paints no colour (the bare checkerboard) and clicking it does
+  nothing, so filter the palette yourself if that matters. `label` becomes the swatch's accessible
+  name; a missing, empty, or whitespace-only label falls back to announcing the raw colour string.
+  `disabled` marks that one swatch non-actionable, independent of the whole control's own
+  `disabled`: it renders a genuinely disabled `<button>` (no tab stop, no hover/press affordance)
+  and clicking it commits nothing; omitted or `false` renders the swatch exactly as before this
+  field existed. The palette container renders only while the normalized list is non-empty
 - `withoutFormatToggle: boolean = false` (attribute `without-format-toggle`) — removes the button
   that cycles between formats. `noFormatToggle` (`no-format-toggle`) is the Shoelace spelling and
   reaches the same behavior; either one wins
@@ -279,6 +282,8 @@ of authoring `positioning-strategy`/`hoist` on each instance.
   `var(--lr-color-brand)`.
 - `--lr-color-picker-selected-check-color` — Checkmark on the selected palette swatch. Default:
   `var(--lr-color-surface)`.
+- `--lr-color-picker-swatch-disabled-opacity` — Opacity of a palette swatch whose own entry sets
+  `disabled`. Default: `0.5`.
 
 ```html
 <lr-color-picker

package/llms/components/lr-combobox.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** 33 parts, 31 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 33 parts, 32 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-option` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.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-confirm-bar.md

@@ -82,13 +82,21 @@ real overlays use.
 `returnFocusTo: ConfirmBarReturnFocusTarget = null` (attribute: false) — where focus goes once a
 decision lands, instead of parking on `[part="status"]`.
 `ConfirmBarReturnFocusTarget = HTMLElement | null | (() => HTMLElement | null)`; the thunk form is
-resolved at handoff time, because a host that swaps a focused control out for this bar often
-re-creates that control on the way back. It applies to every path that reaches a decision, a
-`pending` decision finalized externally included. A named target that is missing, detached, `inert`,
-or otherwise refuses focus falls back to `[part="status"]` rather than to `<body>` — an `inert`
-element refuses `focus()` silently. Left unset, the handoff is byte-identical to the shipped one.
-The pending state is deliberately *not* affected: while a decision is awaiting resolution, focus
-still parks on `[part="status"]`, because that is not the return journey yet.
+called at handoff time, because a host that swaps a focused control out for this bar often
+re-creates that control on the way back — and, because every supported host framework re-renders
+asynchronously relative to that synchronous handoff, the control frequently does not exist yet at
+that first call. When the first call does not yet name a live, focusable element, the same handoff
+calls the thunk again once the host has had a real chance to react (its own re-render committed),
+and moves focus there if it has since appeared and nothing else has claimed focus in the meantime —
+this is what makes the swap-a-trigger-for-this-bar case actually work, rather than only working when
+the host happens to re-create its control before the decision lands. A plain element value is
+resolved once, synchronously, and never retried: it names something that either already exists or
+never will. It applies to every path that reaches a decision, a `pending` decision finalized
+externally included. A named target that is missing, detached, `inert`, or otherwise refuses focus
+falls back to `[part="status"]` rather than to `<body>` — an `inert` element refuses `focus()`
+silently. Left unset, the handoff is byte-identical to the shipped one. The pending state is
+deliberately *not* affected: while a decision is awaiting resolution, focus still parks on
+`[part="status"]`, because that is not the return journey yet.
 
 **Slots:** default — supplementary body content between the heading and the actions (e.g. a
 `lr-diff-view`). `footer` — extra content at the start of the action row.
@@ -213,3 +221,24 @@ bar.addEventListener("lr-approve", (e) => {
     }); // bounce back, retry
 });
 ```
+
+A host that reveals this bar in place of a control it just hid — the `returnFocusTo` motivating
+case — does not need to order that swap relative to the line above. A reactive host's own re-render
+(replacing this bar with its trigger again) runs on its own update cycle, which lands asynchronously
+either way, so `returnFocusTo`'s thunk is written to be called twice: once immediately, in case the
+control already exists, and once more after the host has had a chance to react if the first call
+found nothing yet:
+
+```ts
+bar.returnFocusTo = () => document.querySelector('[data-action="delete"]');
+bar.addEventListener("lr-approve", (e) => {
+  e.preventDefault();
+  runApproval(e.detail.args)
+    .then(() => {
+      bar.decision = "approved"; // the host's own state clear can happen before or after this
+    })
+    .catch(() => {
+      bar.pending = null;
+    });
+});
+```

package/llms/components/lr-context-meter.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, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 17 parts, 10 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`
 
 ---
@@ -26,9 +26,13 @@ used" summary.
 **Properties:**
 
 - `segments: ContextMeterSegment[] = []` (attribute: false, JS-only) — `{ label: string; value:
-number; tone?: 'brand' | 'success' | 'warning' | 'danger' | 'neutral'; color?: string }[]`. `value` is an _absolute_
+number; tone?: 'brand' | 'success' | 'warning' | 'danger' | 'neutral'; color?: string; disabled?:
+boolean }[]`. `value` is an _absolute_
   quantity measured against `total`, never a pre-computed percentage.
   `color`, when supplied, is a sanitized arbitrary CSS color that takes precedence over `tone`.
+  `disabled`, when set, marks that band non-actionable while `interactive` is set: its control
+  renders genuinely disabled (no tab stop, no hover/press affordance) and activating it emits no
+  `lr-segment-activate`.
 - `total: number = 0` — the full capacity segments are measured against (e.g. a model's context
   window size).
 - `shape: ContextMeterShape = 'bar'` (`'bar' | 'ring'`, reflected) — the v9 geometry name;
@@ -95,7 +99,14 @@ color hook as `segment`) and `legend-label`, plus `legend-value` and `legend-per
 matching `legendDisplay` settings. While `interactive` is set, `segment` and `legend-item` are
 `<button>`s (a `role="button"` arc under `shape="ring"`) and a selected one carries a second part
 token — `segment-selected` / `legend-item-selected` — because nothing but a pseudo-class may follow
-`::part()`, so the state has to live in the part name
+`::part()`, so the state has to live in the part name. Two further state tokens join them, and they
+compose: `segment-empty` / `legend-item-empty` on a band whose `value` is 0, and
+`segment-disabled` / `legend-item-disabled` on a band whose `segments` entry sets `disabled`. The
+empty pair is DERIVED and carries no built-in treatment — it is the hook for your own "nothing in
+this bucket" styling, and a zero band stays actionable. The disabled pair is DECLARED: that control
+renders genuinely disabled (no tab stop, no hover or press affordance) and activating it emits no
+`lr-segment-activate`. Inertness is never inferred from a zero value, because a zero band is
+legitimately clickable in a budget meter
 
 **Themeable custom properties:** `--lr-context-meter-segment-color` is set per segment when its
 `color` field is supplied, and is read by both `segment` and its matching `legend-swatch` so the
@@ -116,7 +127,9 @@ selected band stays visibly selected exactly while it is being pointed at or foc
 ring stays intact. `--lr-context-meter-selected-arc-stroke` (default `16`, in this component's
 `0 0 100 100` viewBox units) is the stroke width of a selected `ring`-shape arc: every arc shares
 one bounding box, so a selected arc reports itself by thickening in place rather than by an outline
-that would trace the whole ring identically for every selection. Otherwise the component consumes shared tokens
+that would trace the whole ring identically for every selection.
+`--lr-context-meter-disabled-opacity` (default `var(--lr-opacity-disabled)`) dims a band or legend row whose entry sets
+`disabled`; the band keeps its own colour, since that colour is the datum. Otherwise the component consumes shared tokens
 `--lr-space-xs`, `--lr-color-text-quiet`, `--lr-font`, `--lr-radius`, `--lr-color-border`,
 `--lr-color-brand`, `--lr-color-success`, `--lr-color-warning`, `--lr-color-danger`,
 `--lr-transition-base`.

package/llms/components/lr-date-input.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** 22 parts, 23 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 22 parts, 24 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-date-picker` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -336,6 +336,12 @@ state hooks are `--lr-date-input-action-hover-color`, `--lr-date-input-action-ho
 `--lr-date-input-action-active-radius` for the pressed state. They inherit from theme ancestors;
 direct values on `lr-date-input` win without retuning library-wide tokens.
 
+`--lr-positioning-strategy` (16.0.0) — the calendar 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-date-input>`; set the custom property on `:root`, a theme, or one clipping
+ancestor to change every unset date input beneath it.
+
 **Optional peer deps:** none.
 
 ```html

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

@@ -336,6 +336,12 @@ state hooks are `--lr-date-input-action-hover-color`, `--lr-date-input-action-ho
 `--lr-date-input-action-active-radius` for the pressed state. They inherit from theme ancestors;
 direct values on `lr-date-input` win without retuning library-wide tokens.
 
+`--lr-positioning-strategy` (16.0.0) — the calendar 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-date-input>`; set the custom property on `:root`, a theme, or one clipping
+ancestor to change every unset date input beneath it.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-dialog.md

@@ -193,6 +193,27 @@ focusable control _inside_ the body, and the body itself is used only when there
 focus. So a dialog full of form controls behaves exactly as before, and a dialog full of text is now
 scrollable with the arrow keys, Page Up/Down and Home/End once Tab reaches it.
 
+**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only action is a composed
+`<lr-icon-button>`, so the part naming that action 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`).
+
+**Border reaches the composed close control the same way background/color/radius do.** This
+component paints no resting border of its own, so it relays no `--_lr-icon-button-border-default`
+into the close control's private fallback tier — but that absence is not a gap. The public
+`--lr-icon-button-border` (and its `-hover`/`-active` variants) is the FIRST arm of the token
+chain, resolved by ordinary custom-property inheritance regardless of whether this component
+relays a default for that same property, so setting it on this element or an ancestor reaches the
+close control exactly as the background/color/radius tokens do. A component with no resting
+border simply has no default to relay, which is different from border theming being broken. Size
+remains the one exception that does not cross this way: use `--lr-theme-icon-button-size`, never
+`--lr-icon-button-size`, as noted above.
+
 **Themeable custom properties:** mapped aliases are `--backdrop-filter`, `--width`, `--spacing`,
 `--header-spacing`, `--body-spacing`, `--footer-spacing`, `--show-duration`, and
 `--hide-duration`. The individual region properties override `--spacing`; mapped properties in

package/llms/components/lr-doughnut-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-drawer.md

@@ -84,6 +84,16 @@ controls, rendered before the built-in close button), `footer` — all inherited
 Names grouped together are aliases on the same functional node; `close-button__control` is the
 composed `<lr-icon-button>`'s own native `<button>`, inherited from `lr-dialog` as of 16.0.0.
 
+**Migrating a pre-16.0.0 `::part()` rule.** This component's icon-only action is a composed
+`<lr-icon-button>`, so the part naming that action 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`).
+
 **Themeable custom properties:** mapped `--size` controls the active axis. For start/end drawers,
 the inherited `--width` and `--lr-dialog-width` remain compatibility fallbacks when neither
 `--size` nor `--lr-drawer-width` is set, and `--lr-dialog-max-width` remains an effective cap,

package/llms/components/lr-drop-zone.md

@@ -39,16 +39,25 @@ reimplemented.
 - `maxFileSize: number = 0` (attribute `max-file-size` — bytes; `0` disables the check), `maxFiles:
   number = 0` (attribute `max-files`), `maxTotalSize: number = 0` (attribute `max-total-size`) —
   identical contract and invalid-override fail-safe fallback to `lr-file-input`'s own three limits.
-  Since this component retains nothing between drops, `maxFiles`/`maxTotalSize` always cover only
-  the current drop (there is no persisted count/total to add).
+  Since this component retains nothing of its own between drops, `maxFiles`/`maxTotalSize` would
+  otherwise always cover only the current drop — `heldFileCount`/`heldTotalSize` below are what let
+  a cumulative cap span separate drops.
+- `heldFileCount: number = 0` (attribute `held-file-count`) and `heldTotalSize: number = 0`
+  (attribute `held-total-size`) — externally held baseline added to the running count/byte-total
+  `maxFiles`/`maxTotalSize` evaluate against, identical contract to `lr-file-input`'s own
+  `heldFileCount`/`heldTotalSize`: `0` (the default) means "nothing held" and reproduces prior
+  behavior exactly, and a negative, `NaN`, or `Infinity` override is normalized to `0` via
+  `finiteCount` rather than corrupting every later comparison.
 - `readonly dragging: boolean` — `true` during an active drag session
 
 **Events:** `lr-files` (`detail: LyraDropZoneFilesDetail`, with fresh frozen readonly `files` and
-`rejected` arrays and frozen rejected-file records, fired on drop; immutable `File` objects retain
-identity) — typed as `LyraDropZoneFilesEvent`, so `event.target`/`event.currentTarget` are
-`LyraDropZone` without a cast. `LyraDropZoneRejectedFile = { readonly file: File; readonly reason:
-'type' | 'count' | 'size' | 'directory' | 'read' | 'limit' | 'maxFiles' | 'maxTotalSize' }`, the
-same reason vocabulary as `lr-file-input`'s `LyraFileInputRejectedFile`.
+`rejected` arrays and frozen rejected-file records, plus `remainingFiles`/`remainingTotalSize`
+reporting the allowance still left under `maxFiles`/`maxTotalSize` after this drop (`null` while
+that limit is unset), fired on drop; immutable `File` objects retain identity) — typed as
+`LyraDropZoneFilesEvent`, so `event.target`/`event.currentTarget` are `LyraDropZone` without a
+cast. `LyraDropZoneRejectedFile = { readonly file: File; readonly reason: 'type' | 'count' | 'size'
+| 'directory' | 'read' | 'limit' | 'maxFiles' | 'maxTotalSize' }`, the same reason vocabulary as
+`lr-file-input`'s `LyraFileInputRejectedFile`.
 
 **Slots:** the default slot is the wrapped region, rendered as ordinary light DOM; `overlay`
 overrides the localized accept/reject overlay text.

package/llms/components/lr-dropdown-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-entity-chip.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, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 3 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`
 
 ---
@@ -56,6 +56,12 @@ The anchored detail popover is a floating surface and paints from the **shared o
 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 preview popover 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-entity-chip>`; set the custom property on `:root`, a theme, or one clipping
+ancestor to change every unset entity chip beneath it.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-export-button.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, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 6 parts, 5 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`
 
 ---
@@ -104,6 +104,12 @@ The menu popup is a floating surface and paints from the **shared overlay-surfac
 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 format menu 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-export-button>`; set the custom property on `:root`, a theme, or one clipping ancestor to
+change every unset export button beneath it.
+
 **Optional peer deps:** none.
 
 ```html

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

@@ -53,14 +53,23 @@ enabled buttons retain pointer feedback.
   update them by assigning a new collection.
 - `maxFileSize: number = 0` (attribute `max-file-size` — bytes; `0` disables the check)
 - `maxFiles: number = 0` (attribute `max-files`) — largest total file count accepted, counting
-  retained files plus the current batch; `0` disables the check. An excess file in the batch is
-  rejected with reason `'maxFiles'`, in the same `[part="rejection"]` shape as `maxFileSize`. While
-  `nonRetaining` is set, the count covers only the current batch (there is no externally-held count
-  to add).
+  retained files (unless `nonRetaining`) plus `heldFileCount` plus the current batch; `0` disables
+  the check. An excess file in the batch is rejected with reason `'maxFiles'`, in the same
+  `[part="rejection"]` shape as `maxFileSize`.
 - `maxTotalSize: number = 0` (attribute `max-total-size`) — largest combined byte size accepted,
-  summing retained files plus the current batch; `0` disables the check. Same rejection-UI shape and
-  fail-safe invalid-override behavior as `maxFileSize` (see gotchas). Same `nonRetaining` batch-only
-  scoping as `maxFiles`.
+  summing retained files (unless `nonRetaining`) plus `heldTotalSize` plus the current batch; `0`
+  disables the check. Same rejection-UI shape and fail-safe invalid-override behavior as
+  `maxFileSize` (see gotchas).
+- `heldFileCount: number = 0` (attribute `held-file-count`) — externally held file count added to
+  the running count `maxFiles` evaluates against, in both retaining and `nonRetaining` modes — the
+  numeric counterpart of `valuePresent`, for a cumulative cap (e.g. a server-backed upload limit)
+  that spans separate picker sessions rather than resetting to what this control alone can see. `0`
+  (the default) means "nothing held" and reproduces prior behavior exactly. A negative, `NaN`, or
+  `Infinity` override is normalized to `0` via `finiteCount` rather than corrupting every later
+  comparison or permanently blocking every future file.
+- `heldTotalSize: number = 0` (attribute `held-total-size`) — externally held byte total added to
+  the running size `maxTotalSize` evaluates against, in both retaining and `nonRetaining` modes.
+  Same contract, default, and invalid-input normalization as `heldFileCount`.
 - `nonRetaining: boolean = false` (reflected, attribute `non-retaining`) — opt-in mode where an
   accepted selection still fires `lr-files`/`input`/`change` but is never written to `files` or
   rendered as a built-in `[part="file"]` row. For a host that persists files elsewhere and renders
@@ -139,9 +148,11 @@ enabled buttons retain pointer feedback.
 host `change`; programmatic `files` writes are silent (both still fire while `nonRetaining` is set,
 even though `files` itself is not written in that mode). `lr-files` (`detail:
 LyraFileInputFilesDetail`, with fresh frozen readonly `files` and `rejected` arrays and frozen
-rejected-file records, fired on both drop and manual file-picker selection; immutable `File` objects
-retain identity) — typed as `LyraFileInputFilesEvent`, so `event.target`/`event.currentTarget` are
-`LyraFileInput` without a cast. `LyraFileInputRejectedFile = { readonly file: File; readonly reason:
+rejected-file records, plus `remainingFiles`/`remainingTotalSize` reporting the allowance still left
+under `maxFiles`/`maxTotalSize` after this batch (`null` while that limit is unset), fired on both
+drop and manual file-picker selection; immutable `File` objects retain identity) — typed as
+`LyraFileInputFilesEvent`, so `event.target`/`event.currentTarget` are `LyraFileInput` without a
+cast. `LyraFileInputRejectedFile = { readonly file: File; readonly reason:
 'type' | 'count' | 'size' | 'directory' | 'read' | 'limit' | 'maxFiles' | 'maxTotalSize' }`: `'type'`
 from `accept`/`allowedMimeTypes`/`forbiddenMimeTypes`, `'count'` when a single-file input
 (`multiple` unset) receives more than one file (in which case _all_ files are rejected, none