@aceshooting/lyra-ui 17.0.0 → 18.1.0

package/llms-full.txt

@@ -1218,6 +1218,47 @@ code. See each control's own reference page for its exact pair.
   `lr-select`. It is a _floor_, not a fixed size. Keep the resolved value **at or above 24px**
   (WCAG 2.2 SC 2.5.8 target size); the default leaves headroom. Lowering it below that shrinks
   every affordance in the library at once.
+- **`--lr-icon-button-size-scope`** resizes icon buttons for **one subtree** instead of the whole
+  application. Set it on any wrapper; it inherits past intervening components and reaches every
+  icon-only control below it. Three names, three scopes — pick by how far you want the change to
+  reach:
+
+  | Property | Scope | Set it on |
+  | --- | --- | --- |
+  | `--lr-theme-icon-button-size` | application-wide | `:root`, or any ancestor |
+  | `--lr-icon-button-size-scope` | one subtree | the wrapper you want affected |
+  | `--lr-icon-button-size` | one element | the icon-only control itself |
+
+  `--lr-theme-icon-button-size` wins wherever both ancestor inputs are set. `--lr-icon-button-size`
+  is **element-scoped on purpose** and is not a wrapper knob: every component re-declares it on its
+  own host so the touch-target floor can apply per element, so a value set on a wrapper is replaced
+  at the first component in between and never reaches anything nested inside one. That behaviour is
+  unchanged — use `--lr-icon-button-size-scope` for the wrapper case.
+
+  ```css
+  /* A dense toolbar, without touching the rest of the app. */
+  .message-toolbar {
+    --lr-icon-button-size-scope: 1.75rem;
+  }
+  ```
+
+  The coarse-pointer floor still applies to both ancestor inputs: on a touch device (`hover: none`
+  or `pointer: coarse`) a resolved value below `2.75rem` is raised back to it, so the new subtree
+  knob is not a way around WCAG 2.2 SC 2.5.8 — a deliberately dense desktop toolbar still becomes
+  tappable on a phone.
+- **`--lr-color-surface-overlay` follows `--lr-theme-color-surface-default` in both modes.** It is
+  the panel colour behind every floating surface — dropdowns, listboxes, menus, toasts, popovers,
+  dialogs, and the `lr-app-rail` mobile drawer. In light mode it resolves straight to
+  `--lr-color-surface`, so a re-skinned page surface carries them all with it. Dark mode cannot
+  resolve to the page surface — panel and page would be the same near-black, and an open dialog
+  would read as a scrim with text floating on it and no panel at all — so it is **derived** from
+  the page surface instead: `color-mix(in srgb, var(--lr-color-surface) 85%, #8bade2)`, which lifts
+  the panel a fixed amount above whatever the base happens to be. One
+  `--lr-theme-color-surface-default` override therefore re-skins every floating surface in dark
+  mode too, and the elevation delta survives the re-skin. At the built-in dark base the pair still
+  resolves to the same panel colour it always has, so no existing dark theme moves.
+  `--lr-theme-color-surface-overlay` still wins outright when you set it — reach for it only when
+  you want a panel colour unrelated to the page surface.
 - **Aligning your own content next to a checkbox or radio.** `--lr-checkbox-label-indent` /
   `--lr-radio-label-indent` publish the label offset, but custom properties inherit _down_, not
   sideways, so a sibling node in your tree cannot read them off the control. Compute the same
@@ -1821,8 +1862,8 @@ silently defeats a registered catalog — omit it, or pass `undefined`.
 
 ### Ready-made catalogs: `@aceshooting/lyra-ui/translations/<locale>.js`
 
-Eleven full catalogs ship with the package — **`ar`, `de`, `es`, `fa`, `fr`, `he`, `it`, `ja`,
-`pt-BR`, `ru`, `zh-CN`** — each covering every key in `LYRA_DEFAULT_STRINGS`. They are
+Twelve full catalogs ship with the package — **`ar`, `de`, `es`, `fa`, `fr`, `he`, `it`, `ja`,
+`pt-BR`, `ro`, `ru`, `zh-CN`** — each covering every key in `LYRA_DEFAULT_STRINGS`. They are
 **side-effect-only modules**: import one bare, read nothing from it, and it calls
 `registerLyraLocale()` for you.
 
@@ -1833,11 +1874,14 @@ import "@aceshooting/lyra-ui/translations/fa.js"; // fa-IR falls back to this ba
 import "@aceshooting/lyra-ui/translations/he.js"; // he-IL falls back to this base catalog
 import "@aceshooting/lyra-ui/translations/it.js"; // Italian
 import "@aceshooting/lyra-ui/translations/pt-BR.js"; // also serves pt and pt-PT
+import "@aceshooting/lyra-ui/translations/ro.js"; // Romanian
 import "@aceshooting/lyra-ui/translations/zh-CN.js"; // also serves zh, zh-Hans and zh-Hans-CN
 ```
 
 Persian and Hebrew use CLDR plural categories (`fa`: `one`/`other`; `he`:
-`one`/`two`/`other`); Italian uses a non-default set too (`it`: `one`/`many`/`other`). `ar`, `fa`
+`one`/`two`/`other`); Italian uses a non-default set too (`it`: `one`/`many`/`other`), and so does
+Romanian (`ro`: `one`/`few`/`other`, where `few` covers `0` and `2`-`19` and `other` is the
+`de`-requiring form from `20` upward). `ar`, `fa`
 and `he` declare `dir: 'rtl'`, so `getLyraLocaleDirection()`
 answers for them (and for `ar-EG`, `fa-IR`, `he-IL`) — but locale selection still does not _force_
 writing direction: set `dir="rtl"` on the page or an ancestor yourself.
@@ -4928,6 +4972,17 @@ An async `source` row can carry the same two fields (`start`, `end`) alongside i
   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
+- `sync?: PlaceSync` (reflected) — copies the trigger's width, height, or both onto the listbox,
+  spelled the same as on `lr-dropdown`/`lr-popup`/`lr-popover`. Unset (the default), the listbox
+  sizes to its own content, clamped between `--lr-size-12rem` and `--lr-size-28rem`, exactly as
+  before. `sync="width"` drops that content-based clamp so a full-width trigger with short option
+  labels gets a listbox that aligns to its own edges instead of floating narrower in the middle.
+  A synced listbox is capped on `--lr-positioner-available-inline-size` **alone** — the space the
+  positioner actually measured beside the anchor, which still keeps an over-wide trigger from
+  pushing it off-screen. `--lr-popover-viewport-clamp` does **not** apply to a synced listbox — its
+  92vw default used to shorten the listbox against its own trigger in exactly the full-width case
+  `sync` exists for, and `lr-popup` never applied it either. It still applies with `sync` unset.
+  Like `placement`, a change takes effect the next time the listbox opens
 - `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
@@ -5512,7 +5567,11 @@ exactly like the multi-option case, until the trigger is actually activated.
 
 **Properties:**
 
-- `placeholder: string = ''`
+- `placeholder: string = ''` — text shown on the trigger while nothing is selected, and the
+  trigger's accessible name when neither a host `aria-label` nor a `label` supplies one. One
+  exception to "an empty selection always shows this": while `loading` is `true` the trigger shows
+  the localized `loading` text instead — see `loading` below. The accessible name is unaffected
+  either way
 - `disabled: boolean = false` (reflected)
 - `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
 - `name: string = ''`
@@ -5551,13 +5610,41 @@ exactly like the multi-option case, until the trigger is actually activated.
   authored, the listbox is actually placed with the cascading `--lr-positioning-strategy` custom
   property honored ahead of that default — see the listbox's own **Themeable custom properties**
   below
+- `sync?: PlaceSync` (reflected) — copies the trigger's width, height, or both onto the listbox,
+  spelled and typed the same as on `lr-popup`/`lr-popover`/`lr-dropdown`/`lr-combobox`
+  (`'width' | 'height' | 'both'`). Unset (the default), the listbox sizes to its own content,
+  clamped between `--lr-size-12rem` and `min(--lr-popover-viewport-clamp, --lr-size-28rem)`,
+  exactly as before. `sync="width"` drops that content-based clamp so a full-width trigger with
+  short option labels gets a listbox that aligns to its own edges instead of floating narrower in
+  the middle. A synced listbox is capped on `--lr-positioner-available-inline-size` **alone** — the
+  space the positioner actually measured beside the trigger, which still keeps an over-wide trigger
+  from pushing it off-screen; `--lr-popover-viewport-clamp` does **not** apply to a synced listbox,
+  and still does with `sync` unset. Assignment while open repositions in place without closing;
+  unsetting it releases the inline width the positioner wrote
 - `showUnknownOption: boolean = false` (attribute `show-unknown-option`, reflected) — appends every
   committed value that no `<lr-option>` claims to the end of the listbox as a synthetic, badged,
   keyboard-reachable, re-selectable row. Off by default
 - `getUnknownLabel?: (value: string) => string` (attribute: false) — renders the label for a
   committed value that matches no option, everywhere it appears (trigger, `multiple` tag, synthetic
   row). `getTag` cannot serve this case: it is handed a matched option and there is none. A blank
-  return falls back to the raw value
+  return falls back to the raw value. Not consulted while `loading` suppresses that same value —
+  see below
+- `loading: boolean = false` (reflected) — whether a committed value's real label may still be
+  pending because its `<lr-option>` catalog hasn't arrived yet (e.g. an async fetch still in
+  flight). While `true`, a committed value that currently matches no option renders the localized
+  `loading` placeholder in the trigger label or the relevant `multiple` tag instead of the raw
+  value, with no `notInCatalog`/`[part='unknown-value']` badge and no synthetic
+  `showUnknownOption` listbox row — "not yet resolved" is a different state from "known to be
+  missing". It covers an **empty** selection too: with nothing selected — a create form whose
+  catalogue is still being fetched, or an edit form whose saved selection is legitimately empty —
+  the trigger renders that same localized text in place of `placeholder`, from the same `loading`
+  message key, so both halves of a pending state read the same words and one
+  `registerLyraLocale()` translation reaches both. Nothing to re-localize in the consuming app.
+  With `loading` false an empty selection renders `placeholder` exactly as before. The trigger's
+  accessible name never changes for this: a host `aria-label` wins, then `label`, then
+  `placeholder`, then the localized `select` fallback. A value already matching a live option is
+  unaffected. Never mutates `value`/`selectedOptions` itself, and does not itself disable the
+  trigger — pair it with `disabled` when the control should also be non-interactive while pending
 - `filled: boolean = false` (reflected) — Shoelace alias for the filled trigger treatment
 - `autofocus: boolean = false` / `title: string = ''` — forwarded to the internal trigger
 - `multiple: boolean = false` (reflected) — several options selectable at once; see "Multi-select"
@@ -5609,7 +5696,17 @@ from a removed option, or a programmatic assignment with a typo) still commits
 stays fully reachable through `value`/`selectedOptions` — but renders a dashed/italic
 `[part='unknown-value']` badge next to the trigger label, or on the relevant `multiple`-mode tag,
 instead of an unexplained bare label, mirroring `<lr-model-select>`'s synthetic "not in catalog"
-stale-value row — see `--lr-select-unknown-value-border-style`/`-color` below.
+stale-value row — see `--lr-select-unknown-value-border-style`/`-color` below. Set `loading` while
+that same value's own `<lr-option>` catalog simply hasn't arrived yet (unlike `<lr-combobox>`,
+`<lr-select>` has no async `source` of its own, so this is consumer-driven rather than automatic):
+a still-unmatched value then renders the localized `loading` placeholder instead of the raw value,
+with no `unknown-value` badge and no synthetic `showUnknownOption` row, since it is not yet known
+to be missing. Once the matching option mounts, the real label renders on the next render with no
+`value`/`selectedOptions` re-assignment needed, whether or not `loading` is also flipped back to
+`false`. The same flag covers the other half of that state: with **nothing** selected the trigger
+renders the same localized `loading` text in place of `placeholder`, so a consumer never has to
+hand-write a conditional placeholder bound to the same flag and re-localize, in its own catalogue,
+the string this control already owns.
 
 **Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal trigger button.
 `show()` and `hide()` return `Promise<void>` and resolve after `lr-after-show`/`lr-after-hide` once
@@ -6909,10 +7006,11 @@ box no matter what tier or override is in play.
   For toggle buttons, host `aria-pressed="true|false|mixed"` reaches the focused native button —
   BUTTONS only. A link button (`href` set) never receives it, because `role="link"` does not support
   `aria-pressed`; remove `href` and the same host attribute starts reaching the `<button>` that
-  replaces the anchor. Navigation can use the global
-  `aria-current="page|step|location|date|time|true|false"`, which does reach the anchor. Both states
-  update reactively, including native `ariaPressed`/`ariaCurrent` property assignments, attribute
-  removal and `href` changes. Empty or unsupported tokens are omitted. The native button/link role
+  replaces the anchor. That link carve-out arrived in **16.0.0** — before it, `aria-pressed` was
+  forwarded onto the anchor as well, asserting a state `role="link"` does not have. Navigation can
+  use the global `aria-current="page|step|location|date|time|true|false"`, which does reach the
+  anchor. Both states update reactively, including native `ariaPressed`/`ariaCurrent` property
+  assignments, attribute removal and `href` changes. Empty or unsupported tokens are omitted. The native button/link role
   remains unchanged for an enabled control: use pressed state for button toggles and current state
   for navigation links. A DISABLED link button drops `href` (so it genuinely cannot navigate) and
   therefore also drops the anchor's implicit role, so it renders an explicit `role="link"` — without
@@ -6992,7 +7090,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
@@ -7053,15 +7152,23 @@ above 24px — see `llms/shared.md`. **`--lr-icon-button-size` is element-scoped
 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
+(e.g. one slotted through `<lr-popover>`). The three 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
+sits between the rule and the property; setting `--lr-icon-button-size-scope` on any ancestor to
+resize one subtree; or setting `--lr-theme-icon-button-size` on an ancestor to resize the whole
+application. The shared layer reads the latter two through `var()` at every level, so both reach a
 `<lr-icon-button>` composed inside another component, e.g. `<lr-copy-button>`/
-`<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-message-actions>` -- see `llms/shared.md` for the full scope table.
+
+Lowering the floor for a dense action row below 24px is safe **only through the two ancestor
+levers**. The coarse-pointer/no-hover media rule reads those, and floors the RENDERED hit area back
+at 2.75rem/44px however far the override lowered it, so the control stays comfortably tappable the
+moment the pointer reaching it is a finger rather than a mouse. It does **not** rescue
+`--lr-icon-button-size` set directly on the element: that declaration comes from the outer tree and
+outranks the shadow tree's own `:host` rule, so the media rule never wins and the rendered hit area
+is exactly the value set -- `--lr-icon-button-size: 1rem` really does render a 16px target under a
+coarse pointer, which fails WCAG 2.2 SC 2.5.8. Prefer `--lr-icon-button-size-scope` when the intent
+is a denser row; reach for the element-scoped name only as a deliberate, localized trade-off. `--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
@@ -18109,6 +18216,17 @@ list's `base` scroll container exposes horizontal scrolling for that explicit op
   number `56` and fixes every row to that many pixels. Property callers assign a number, not a
   numeric string. Anything else (non-numeric, zero, negative, non-finite) safely canonicalizes to
   `'auto'` rather than throwing.
+- `rowProjection: 'shadow' | 'light' = 'shadow'` (attribute `row-projection`) — where
+  `renderItem`'s output is instantiated. `'shadow'` (default) stamps it inside this component's own
+  shadow root, so only inherited custom properties and the public row parts reach it. `'light'`
+  renders the windowed rows into the host's own light DOM instead, assigned into the shadow viewport
+  through internal named slots, so ordinary document CSS styles a virtualized row exactly as it
+  styles the same row unvirtualized. The component keeps owning windowing, measurement, spacer
+  sizing, `scrollToIndex()`, the external-scroller mode and the ARIA contract either way, and
+  positioning stays on the shadow-side `[part="row"]` wrapper that document CSS cannot select — so
+  consumer styles can never break windowing. Any other value canonicalizes to `'shadow'`. Left
+  unset, the rendered output is byte-identical to before and the host's light DOM stays empty.
+  See **Light-DOM row projection** below for the trade-offs it carries.
 - `itemRole: 'listitem' | 'row' = 'listitem'` (attribute `item-role`) — `'listitem'` (default)
   preserves the plain `role="list"`/`role="listitem"` mapping with `aria-setsize`/`aria-posinset`.
   `'row'` additionally maps `[part="base"]` to `role="rowgroup"`, `[part="spacer"]` to
@@ -18363,6 +18481,48 @@ default estimate with sparse `ResizeObserver` measurements for rows that have ac
   decides: groups render before the rows, so an active row wins while (and only while) it needs to,
   which is right — a group header is a non-interactive `pointer-events: none` label.
 
+### Light-DOM row projection
+
+`rowProjection="light"` exists for one shape: an application whose list rows are already styled by
+its own global stylesheet, and which therefore could not adopt virtualization without rehoming a
+dozen descendant rules per row into a new custom element or a growing set of custom properties. In
+projection mode the windowed rows render into the host's own light DOM, so ordinary document CSS
+reaches row content directly.
+
+Positioning, measurement and semantics stay where they were. The `[part="row"]` wrapper remains in
+the shadow root and keeps `position: absolute`, the per-frame `transform`, `role`, `aria-setsize`/
+`aria-posinset` (or `aria-rowindex`) and the `ResizeObserver` box — document CSS cannot select it,
+so consumer styles can never break windowing. The whole part vocabulary (`base`, `spacer`, `row`,
+`group`, `sticky-group`) keeps matching in both modes, and `row-height="auto"` still measures
+projected content because the light row is an ordinary in-flow child of that wrapper.
+
+`projectedRows: HTMLElement[]` returns the projected light-DOM row wrappers in item order, and is
+empty outside projection mode. The exported type is `LyraVirtualListRowProjection`; the reserved
+attributes marking library-owned light-DOM nodes are exported as `VIRTUAL_LIST_ROW_ATTRIBUTE`
+(`data-lr-virtual-list-row`) and `VIRTUAL_LIST_STICKY_ATTRIBUTE` (`data-lr-virtual-list-sticky`).
+
+**Known gotchas, all inherent to handing the cascade back to the consumer:**
+
+- **One component-owned wrapper sits between the host and your markup.** A slot cannot assign a text
+  node or a multi-root fragment by attribute, so each row's content lives inside a wrapper carrying
+  `data-lr-virtual-list-row`. Descendant selectors (`lr-virtual-list .row-title`) port unchanged;
+  child combinators (`lr-virtual-list > .row`), `:nth-child`, `:first-child` and sibling combinators
+  written against the unvirtualized markup do not. `:nth-child` on the wrappers reflects the current
+  *window*, not the item index.
+- **`closest('[part="row"]')` stops resolving.** A delegated listener on the host now sees an
+  un-retargeted `event.target` inside the light DOM. Use `closest('[data-lr-virtual-list-row]')`.
+- **The document cascade now reaches row content**, including resets and element-level rules that
+  previously could not, so a projected row can look different from the same row in shadow mode.
+- **Per-row light-DOM state does not survive a disconnect/reconnect.** Disconnect removes the
+  projected rows completely (no rows, no markers, no anchor left behind), so a reparenting move
+  rebuilds them. Scroll position, measurements and the window are unaffected — they live in
+  component state, not in the rows.
+- **Projection activates one task after hydration.** A server render has no DOM to project into, so
+  the first window is shadow-rendered, hydration matches the server markup, and the rows then swap
+  into the light DOM on the next task.
+- **A row taken out of flow collapses its wrapper.** `position: fixed`/`absolute` or
+  `display: none` on your own row leaves nothing for the wrapper to measure.
+
 ---
 
 ## `lr-app-rail`
@@ -19600,7 +19760,8 @@ to `<wa-card>`'s contract, staying slot-compatible with `lr-result-card` where t
 - `aria-pressed` and `aria-current` (attributes only) — forwarded reactively onto the native
   control the card actually renders, the same mechanism `<lr-button>` and `<lr-icon-button>` use.
   `aria-pressed` accepts `'true' | 'false' | 'mixed'` and reaches the `activation-button` only —
-  `link` has no pressed state, so a linked card never receives it. The global `aria-current`
+  `link` has no pressed state, so a linked card never receives it — the same **16.0.0** carve-out
+  `<lr-button>` and `<lr-icon-button>` took. The global `aria-current`
   accepts `'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'` and reaches both the
   activation button and the stretched link. Anything outside those sets is dropped rather than
   passed through, so a typo never reaches the accessibility tree. This is what lets a single-select
@@ -20374,7 +20535,10 @@ 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>`,
@@ -20395,6 +20559,7 @@ the filter `type`s actually declared:
 | `'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
@@ -20431,8 +20596,21 @@ until something else registers it, the same trade `icon-button-register.js` docu
 - `disabled: boolean = false` (reflected) — disables every filter control and reset action.
 - `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`.
+- `hasActiveFilters: boolean` (read-only) — whether any configured filter currently has a value,
+  including one sitting at its own declared `defaultValue`. Drives the reset button's own disabled
+  state in every `activeFiltersDisplay` mode except `'changed'`; the getter itself is unaffected by
+  `activeFiltersDisplay`.
+- `hasChangedFilters: boolean` (read-only) — whether any filter's value differs from its own
+  declared `defaultValue`, using the same equality `activeFiltersDisplay: 'changed'` filters its
+  chip row on: a `readonly string[]` default compares positionally, everything else compares with
+  `Object.is`. This is the counterpart to `hasActiveFilters`, not a synonym — a bar whose filters
+  were all declared with non-empty defaults and never touched reads `hasActiveFilters === true` and
+  `hasChangedFilters === false`, because a bar whose defaults narrow the view on load has not been
+  narrowed by the user. A filter with no declared `defaultValue` counts as changed the moment it
+  holds any value at all (there is nothing for it to still equal), and clearing a filter that *does*
+  declare one counts as changed too, since `reset()` would restore it — which is the one case where
+  this getter and the `'changed'` chip row differ, the row's entries being non-empty by
+  construction. Always live, never cached.
 - `invalidFilterIds: readonly string[]` (read-only) — immutable ids of required filters whose
   values are unset.
 - `activeFiltersDisplay: 'all' | 'changed' | 'hidden' = 'all'` (reflected, attribute
@@ -20446,6 +20624,10 @@ until something else registers it, the same trade `icon-button-register.js` docu
   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.
+  `'changed'` additionally gates the reset button on `hasChangedFilters` instead of
+  `hasActiveFilters`, so an untouched defaults-only bar — which renders no chip in this mode — no
+  longer offers an enabled reset that would change nothing. Enablement under `'all'` and `'hidden'`
+  is unchanged, `disabled`/`loading` still win in every mode, and `reset()` itself is untouched.
 
 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
@@ -20575,11 +20757,13 @@ 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
-control ships a clear action also accepts `clearable: boolean`. They are forwarded verbatim to that
+`icon: unknown` and `labelVisibility: 'visible' | 'hidden' | 'auto'` fields, and every one whose
+composed control ships a clear action also accepts `clearable: boolean`. They are forwarded verbatim to that
 control's own same-named property — `icon` into its `start` slot exactly like a choice option's own
 `icon`, rendered inert and `aria-hidden`; `clearable` reaching `<lr-date-input>` under its own
 `with-clear` spelling, since that control has no `clearable`. `'text'` also accepts
@@ -20598,6 +20782,20 @@ so a compact toolbar row still names every field for assistive technology; visua
 `::part(filter-control-label)` in CSS, the only previous option, removed the accessible name along
 with the text.
 
+`labelVisibility: 'auto'` is the width-dependent middle between the two. It renders exactly what
+`'visible'` renders — the same stacked label element, the same accessible name computed from it, no
+`aria-label` and no placeholder fallback — and the bar's own stylesheet visually clips that label
+once the bar's allocation drops below `30rem`. The threshold is a container query on the host, so it
+reads the bar's own allocated width, not the viewport's: the same definitions render labelled across
+a dashboard and unlabelled in a 320px side panel, dialog or split pane, with no host-side breakpoint
+logic. The label element is never removed at any width, so the field's accessible name is identical
+in both states, and `'auto'` deliberately does not route the name onto the control the way
+`'hidden'` does — doing so would name a wide-allocation field twice. A `'checkbox-menu'` filter
+participates through its own trigger label run, the same one `'hidden'` already clips there. The
+threshold is fixed rather than themeable: a CSS container query's prelude cannot read a custom
+property (`var()` is not substituted in an at-rule prelude), so a `--lr-*` hook for it would parse
+and silently never apply.
+
 `'combobox'` also accepts the same `debounce?: number` (ms) `'text'` already had: it coalesces a
 burst of rapid selection changes (picks, a multi-select toggle, an
 `allowCustomValue`/`allowCreate` commit, or the clear action) into one delayed commit. Unlike
@@ -20627,6 +20825,8 @@ makes that text visually hidden — never removed — so the button keeps its ac
 one case where the hidden label would be the *only* thing the button says (hidden routing, no
 declared `placeholder`, nothing selected) the label routes to the visible summary instead of being
 emitted twice, so the trigger's accessible name stays "Teams", never "Teams Teams".
+`labelVisibility: 'auto'` clips that same trigger label run, and only below the `30rem` threshold —
+the label run is always emitted under `'auto'`, since nothing is routed to the summary there.
 
 Because its trigger is a button rather than a field, a `required` `'checkbox-menu'` deliberately
 renders **no** required asterisk and sets **no** `aria-invalid`: the shared required marker has no
@@ -20791,12 +20991,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
@@ -21218,6 +21495,19 @@ These named interfaces and helper signatures are available to typed integrations
     readonly defaultValue?: string | readonly string[] | boolean;
   }`
   Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
+  `LyraFilterBarChipDefinition extends LyraFilterBarDefinitionBase {
+    readonly type: 'chip';
+    readonly formatValue?: (value: LyraFilterBarFieldValue, locale: string) => string;
+    readonly clearValue?: LyraFilterBarFieldValue;
+    readonly isEmpty?: (value: LyraFilterBarFieldValue) => boolean;
+    // Inherited from LyraFilterBarDefinitionBase.
+    readonly filterId: string;
+    readonly label: string;
+    readonly placeholder?: string;
+    readonly required?: boolean;
+    readonly defaultValue?: string | readonly string[] | boolean;
+  }`
+  Import: `@aceshooting/lyra-ui/components/layout/filter-bar/filter-bar.class.js`.
   `LyraFilterBarCustomControlAdapter {
     readonly valueFromEvent: (event: Event) => LyraFilterBarFieldValue;
     readonly clearValue: LyraFilterBarFieldValue;
@@ -27027,18 +27317,72 @@ LyraMapLegendPattern }`, where `LyraMapLegendPattern` is `'solid' | 'diagonal' |
 'crosshatch'`. Pattern is required so color is never the sole category cue. At most 100 valid
   rows, 256 characters per label, and 8,192 aggregate label characters are retained; colors are
   bounded before validation. The overlay scrolls within the map allocation.
+  A row may also carry its own `value`: the category key that row stands for — the same string a
+  `point.colors`/`point.icons` entry matches against `point.field`/`point.iconField`. It is
+  trimmed, bounded to 256 characters (sliced, never ellipsized, so a bounded key still matches) and
+  **retained** in the canonical readback; a non-string, empty or whitespace-only key leaves no
+  `value` property on the frozen row at all. It is what makes a row operable under
+  `legendInteractive`, and it does not count toward the label budget.
   A row may also carry `icon`, deliberately the same record a `point.icons` entry uses — hand the
   legend the very icon object its point layer renders and the key shows the symbol drawn on the
-  map instead of describing it in colour alone. The point layer's category key (`value`) is
-  accepted so a pass-through needs no reshaping, and is left out of the canonical readback;
+  map instead of describing it in colour alone. The **icon record's own** `value` is a separate
+  field from the row-level one above: it is accepted so a pass-through needs no reshaping, and it
+  is still left out of the canonical readback. A row's key is never derived from its glyph's, which
+  would silently make a row interactive that the author never marked;
   `path`, `viewBox`, `mode`, `strokeWidth`, `lineCap` and `lineJoin` keep their point-icon meaning
   and their point-icon defaults, and the same validation applies (path data only, at most 8,192
   characters, positive `viewBox` dimensions). An unusable record is dropped and that row keeps
   rendering its colour swatch, exactly as a row that supplies no `icon` does.
+  A row may finally carry a `group`: the section it belongs to, for a key that describes two
+  layers at once and otherwise could not say which rows belong to which. The rule is pinned
+  rather than inferred: **consecutive** entries sharing an identical `group` render as one section
+  — a visible heading plus a `role="group"` that heading names — an entry with **no** `group`
+  keeps its **declared** position rather than being hoisted above or sunk below a section, and a
+  `group` that reappears after an interruption opens a *second* section rather than reordering
+  rows to merge them. Declaration order is the one thing the legend never rewrites, because the
+  order is itself information about the map. `group` is caller-supplied **data**: it renders
+  verbatim and is never resolved through the locale catalogue. It is trimmed and bounded to 256
+  characters (ellipsized, since it is rendered prose rather than a key matched against
+  `point.field`); a non-string, empty or whitespace-only value leaves no `group` property on the
+  frozen row at all, so an empty string means "ungrouped" instead of an empty heading. Like the
+  row-level `value`, it does not count toward the aggregate label budget — the rendered total is
+  already finite and stated: at most one heading per rendered row, so at most 100 of them. A
+  section is not a row: the 100-row cap and the `legend-limit` summary count rows, never sections.
 - readonly `legendProjection: LyraMapLegendProjection` — frozen `{ inputCount, renderedCount,
 omittedCount, truncatedLabelCount, truncated }` result for the latest assignment. A truncated
   projection renders a localized visible `1–N of M items` summary rather than silently claiming
   the bounded rows are complete.
+- `legendInteractive: boolean = false` (attribute `legend-interactive`, reflected) — opt-in: turns
+  every legend row that carries a `value` into a keyboard-operable visibility toggle, and leaves a
+  row without one inert. Unset, the legend renders exactly the read-only key it rendered before —
+  no `button`, no extra attribute, and no extra MapLibre paint key. Each toggle is an independently
+  tabbable native `button`, so Enter and Space are the platform's own activation and there is no
+  roving tabindex: a 100-row interactive legend contributes 100 tab stops, exactly as a 100-series
+  `lr-chart` legend does. Each interactive row also grows to the shared `--lr-icon-button-size`
+  hit-area floor (WCAG 2.5.8), which the panel's existing `max-block-size` and scrolling contain.
+- `legendCollapsible: boolean = false` (attribute `legend-collapsible`, reflected) — opt-in: renders
+  a `legend-disclosure` `button` inside the panel that collapses the key down to its header, so a
+  large legend stops permanently covering part of the map. Unset, the panel renders exactly what it
+  rendered before — no button, no `id` minted on the row list, and no `hidden` attribute anywhere.
+  Collapsing hides the gradient bar, the rows, the `legend-limit` summary and the trailing `legend`
+  slot; the `legend-start` slot and the disclosure itself stay visible, so a slotted header survives
+  the collapse and the control that restores the key is never what the collapse hides.
+- `legendOpen: boolean = true` (attribute `legend-open`, reflected) — whether a `legendCollapsible`
+  panel is expanded. It defaults **open**, so adding only `legendCollapsible` never hides an existing
+  key, and it does nothing at all while `legendCollapsible` is unset. Because it is a
+  `true`-defaulting boolean it uses a custom attribute converter, so `legend-open="false"` parses —
+  the bare presence-based boolean form cannot express `false` at all — and the reflection follows the
+  same converter: open (the default) reflects as an **absent** attribute and collapsed reflects as
+  `legend-open="false"`. It is controlled public state and survives a disconnect/reconnect. Assigning
+  it programmatically reconciles the rendered panel and emits nothing.
+- `hiddenCategories: readonly string[] = []` (attribute: false) — the complete controlled set of
+  muted category keys, mirroring `lr-chart`'s `hiddenDatasets`. Clone-owned and frozen; non-string,
+  empty, whitespace-only and duplicate entries are dropped (first occurrence wins, matching
+  `point.colors`), and at most 100 keys are retained. Honoured on the **first** render and the
+  first MapLibre paint, not only after a user toggle, so a host can restore a saved selection. An
+  empty array deliberately means every category is visible. It is controlled public state and
+  survives a disconnect/reconnect. A hidden key that matches no category is harmless. Assigning it
+  programmatically emits nothing.
 - `choropleth?: LyraMapChoroplethLayer` (attribute: false) — `LyraMapChoroplethLayer { sourceId:
 string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, string][]; interpolation?:
 'linear' | 'logarithmic' | 'step'; stepBaseColor?: string }` (interpolated
@@ -27319,7 +27663,8 @@ payload beside the map.
 `LyraMapHeatmapZoomValue`, `LyraMapLineOptions`, `LyraMapPointOptions`, `LyraMapPointRadiusOptions`,
 `LyraMapPointRadiusInterpolation`, `LyraMapPointIcon`, `LyraMapPointIconMode`,
 `LyraMapPointIconLineCap`, `LyraMapPointIconLineJoin`, `LyraMapMarker`, `LyraMapMarkerActivationDetail`,
-`LyraMapMarkerActivationSource`, `LyraMapStyleSpecification`, and `LyraMapInstance`.
+`LyraMapMarkerActivationSource`, `LyraMapLegendToggleDetail`, `LyraMapLegendPanelToggleDetail`,
+`LyraMapStyleSpecification`, and `LyraMapInstance`.
 The former `LegendEntry`, `ChoroplethLayer`, `GeoJsonDataLayer`, and `MapMarker` names are removed
 in v9 rather than retained as aliases.
 
@@ -27335,7 +27680,24 @@ shared `maplibre-gl` import without constructing a map or allocating a WebGL con
 an element.
 
 **Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`),
-`lr-map-marker-activate` (non-cancelable; frozen `LyraMapMarkerActivationDetail { id, lngLat,
+`lr-map-legend-toggle` (**cancelable**; frozen `LyraMapLegendToggleDetail { value, visible,
+hiddenCategories }` — the activated row's category key, its proposed visibility, and the complete
+proposed hidden set in the order it would be committed, with the array detached and frozen so a
+listener cannot mutate the component's state through it). `preventDefault()` is a genuine veto, not
+a notification: `hiddenCategories` is not written, the row's `aria-pressed` does not change, the
+MapLibre paint is untouched, and nothing is announced — which is exactly what a host needs to own
+the set and assign its own value instead. There is deliberately no second, confirmation event: the
+committed state is `hiddenCategories`, which the host already observes, so a paired before/after
+vocabulary would be permanent public surface nobody asked for. The event is a DOM-interaction
+proposal only, so a programmatic `hiddenCategories` assignment reconciles without emitting it.
+Also `lr-map-legend-panel-toggle` (**cancelable**; frozen `LyraMapLegendPanelToggleDetail { open }` —
+the proposed `legendOpen` value), fired once when the `legendCollapsible` disclosure is activated by
+pointer or by Enter/Space. It is the *panel's* disclosure, not a *category's* visibility, so it
+deliberately does not reuse `lr-map-legend-toggle`. `preventDefault()` is the same genuine veto:
+`legendOpen` is not written, the rendered rows and the disclosure's `aria-expanded` do not change,
+so a host can own the open state and assign its own value from `event.detail.open`. A programmatic
+`legendOpen` assignment reconciles without emitting it, so a controlled host cannot loop.
+Also `lr-map-marker-activate` (non-cancelable; frozen `LyraMapMarkerActivationDetail { id, lngLat,
 marker, source }`; `id` is the trimmed explicit identity or `undefined`, `marker` is the accepted
 declarative snapshot, and `source` is `'pointer' | 'keyboard'`), and `lr-map-click`
 (frozen `detail: { readonly lngLat: readonly [lng, lat], readonly feature?, readonly origin?,
@@ -27357,9 +27719,15 @@ markup as described above.
 
 **Slots:** `legend` — custom legend content, rendered inside the legend panel's own layout so it
 stays positioned with the map instead of floating beside it. Supplying it opens the panel even
-when `legend` and `legendGradient` are both empty.
-
-**CSS parts:** `base`, `container`, `legend`, `legend-swatch`, `legend-gradient`, `legend-lo`,
+when `legend` and `legendGradient` are both empty. `legend-start` — the same extension point at the
+**top** of the panel: it renders ahead of the gradient bar and every projected row, where `legend`
+renders after them, so a host-authored panel header is no longer forced to be a footer. Content in
+it alone opens the panel too, and neither slot is ever made interactive by `legendInteractive`,
+which only reaches rows projected from `legend`.
+
+**CSS parts:** `base`, `container`, `legend`, `legend-disclosure`, `legend-disclosure-icon`,
+`legend-group`, `legend-group-heading`, `legend-swatch`, `legend-toggle`,
+`legend-toggle-hidden`, `legend-gradient`, `legend-lo`,
 `legend-hi`, `legend-limit`, `marker`, `popup`,
 `popup-content`, `popup-close-button`, `attribution`, `attribution-toggle`, `navigation`,
 `zoom-in`, `zoom-out`, `compass`, `scale`, `error`.
@@ -27384,6 +27752,38 @@ visible label carries its meaning. That association is advertised only while it
 the optional `maplibre-gl` peer is still loading, and after any failure, there is no map
 container in the tree, so `legend` withholds `aria-controls` rather than leaving a dangling
 idref.
+Under `legendInteractive`, a row carrying a `value` wraps its swatch and label in a
+`legend-toggle` `button` with `aria-pressed` rendered as the literal `"true"`/`"false"` — never
+omitted, because a missing attribute reports "not a toggle button" rather than "unpressed". The
+button's accessible name is its own visible label (caller-supplied data, so deliberately not
+localized), scoped by the legend's own localized group name; no `aria-label` restates the state,
+which would make assistive tech announce it twice. A hidden row's button additionally carries the
+`legend-toggle-hidden` token — state lives in the part name, so `::part(legend-toggle-hidden)` is a
+reachable hook — and dims only its `aria-hidden` swatch while re-colouring the label through the
+quiet text token, so the label keeps AA contrast rather than fading with the whole button. In
+forced colors the hidden row falls back to `line-through`, which survives a system-color collapse.
+Each activation is announced through the shared light-DOM polite live region, using the same
+`legendTypeShown`/`legendTypeHidden` strings `lr-graph-legend` announces with.
+Under `legendCollapsible`, `legend-disclosure` is a native `button` whose **visible localized text
+is its accessible name** and whose `aria-expanded` renders the literal `"true"`/`"false"` — never
+omitted — with `aria-controls` naming the row list in the same shadow root (idrefs do not cross
+shadow boundaries, so this is deliberately not an idref into the light DOM). It carries the shared
+`--lr-icon-button-size` hit-area floor, and `legend-disclosure-icon` is the decorative chevron it
+rotates: the shared icon set ships one right-pointing glyph and asks callers to rotate the wrapping
+part, so collapsed points along the reading direction and expanded points down in both directions.
+The rotation runs on `--lr-transition-fast`, which the token layer already flattens under
+`prefers-reduced-motion`. A collapsed panel hides its gradient, rows, `legend-limit` summary and
+trailing `legend` slot with the plain `hidden` attribute, so they leave layout, the accessibility
+tree and the tab order together.
+When at least one entry carries a `group`, each consecutive run renders inside `legend-group`
+(`role="group"`, named by its own `legend-group-heading` through `aria-labelledby`) and **each run
+gets its own `role="list"`**, because a `list` may only own `listitem`s — a `group` sitting directly
+inside the outer list is an `aria-required-children`/`aria-required-parent` violation. The outer
+container therefore drops its own `role` in that case; a legend with no groups keeps the single
+`role="list"` it has always had. Row `aria-posinset`/`aria-setsize` stay whole-key values inside a
+section: `aria-setsize` already reports the *input* count so a bounded key stays honest, and a
+dropped row carries no attributable group, so a section adds a labelled sub-region without
+renumbering the key.
 `legend-limit` is the localized bounded-projection summary. The five peer-chrome parts project
 stable Lyra names onto MapLibre-generated DOM without erasing peer-supplied part tokens;
 `marker` retains a 24px minimum target in both axes even when a peer/custom marker has no intrinsic
@@ -27415,6 +27815,15 @@ integration; there is no declarative controls property.
 - `--lr-map-choropleth-fill-opacity` (default `0.75`) — fill opacity for the declarative
   `choropleth` layer and polygon fills in every `dataLayers` entry. It intentionally inherits from
   an ancestor, so one scoped declaration rethemes every nested map without setting each host.
+- `--lr-map-hidden-category-opacity` (default `0.15`) — opacity a category listed in
+  `hiddenCategories` is muted to in the rendered MapLibre paint: `circle-opacity` and
+  `circle-stroke-opacity` on the points layer and `icon-opacity` on the point-icon symbol layer.
+  Like the fill-opacity token it is read from the resolved cascade on every paint, because MapLibre
+  draws to a WebGL canvas the CSS cascade never reaches, and it inherits from an ancestor. A
+  `kind: 'heatmap'` entry is out of scope: a density surface has no per-category field to mute.
+- `--lr-map-legend-hidden-swatch-opacity` (default `0.5`) — opacity of a hidden interactive legend
+  row's decorative swatch. Only the `aria-hidden` swatch dims; the label re-colours through
+  `--lr-color-text-quiet` instead, so it never drops below 4.5:1.
 - `--lr-map-popup-close-button-hover-bg` (default `var(--lr-color-brand-quiet)`) and
   `--lr-map-popup-close-button-hover-color` (default `var(--lr-color-brand)`) — hover background
   and foreground of `popup-close-button`.
@@ -30116,6 +30525,7 @@ These named interfaces and helper signatures are available to typed integrations
     readonly label: string;
     readonly pattern: LyraMapLegendPattern;
     readonly icon?: LyraMapPointIcon | Omit<LyraMapPointIcon, 'value'>;
+    readonly group?: string;
   }`
   Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
   `LyraMapLegendProjection {
@@ -30141,6 +30551,16 @@ These named interfaces and helper signatures are available to typed integrations
     readonly source: LyraMapMarkerActivationSource;
   }`
   Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
+  `LyraMapLegendToggleDetail {
+    readonly value: string;
+    readonly visible: boolean;
+    readonly hiddenCategories: readonly string[];
+  }`
+  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
+  `LyraMapLegendPanelToggleDetail {
+    readonly open: boolean;
+  }`
+  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
   `LyraMapStyleSpecification {
     readonly version: 8;
     readonly sources: Readonly<Record<string, unknown>>;
@@ -36100,7 +36520,12 @@ never see that update happen. See `<lr-thinking-panel>`'s own reference at `llms
 
 **Slots:** none — content renders from `content`, not a slot.
 
-**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`)
+**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`), plus every part
+`<lr-markdown>` documents forwarded verbatim (no aliasing — none collides with `base`/`cursor`)
+from the composed `<lr-markdown>` in Markdown mode via `exportparts`: `content`, `heading`,
+`paragraph`, `list`, `code-block`, `inline-code`, `link`, `table`, `blockquote`, `img`, `math`. A
+host-level `lr-streaming-text::part(link)`/`::part(img)` rule reaches the rendered `<a>`/`<img>`
+exactly as the same rule does applied directly to `<lr-markdown>`.
 
 **Themeable custom properties:** `--lr-inline-cursor-width` (default
 `var(--lr-size-0-125rem)`, the shared inline cursor width), `--lr-inline-cursor-height` (default
@@ -36214,8 +36639,12 @@ share one implementation.
 
 **Slots:** none — content renders from `content`, not a slot.
 
-**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`) — identical to
-`<lr-streaming-text>`'s own.
+**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`), plus every part
+`<lr-markdown-core>` documents forwarded verbatim from the composed `<lr-markdown-core>` in
+Markdown mode via `exportparts`: `content`, `heading`, `paragraph`, `list`, `code-block`,
+`inline-code`, `link`, `table`, `blockquote`, `img`, `math` — the identical forwarded list
+`<lr-streaming-text>` documents, since `<lr-markdown>` and `<lr-markdown-core>` share the same
+documented part vocabulary.
 
 **Themeable custom properties:** `--lr-inline-cursor-width` (default `var(--lr-size-0-125rem)`) and
 `--lr-inline-cursor-height` (default `var(--lr-size-1em)`) — the same shared inline-cursor tokens