@aceshooting/lyra-ui 17.0.0 → 18.1.0

package/llms/components/lr-button.md

@@ -373,10 +373,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

package/llms/components/lr-card.md

@@ -73,7 +73,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

package/llms/components/lr-combobox.md

@@ -167,6 +167,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

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

@@ -21,7 +21,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>`,
@@ -42,6 +45,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
@@ -78,8 +82,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
@@ -93,6 +110,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
@@ -222,11 +243,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
@@ -245,6 +268,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
@@ -274,6 +311,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
@@ -438,12 +477,89 @@ const filters: LyraFilterBarFilterDefinition[] = [
 The custom renderer returns a Lit `TemplateResult`; the filter bar places it in its
 `filter-control` part and re-renders it whenever the controlled value or validation state changes.
 
+### Chip-only filters
+
+Use `type: 'chip'` when the value is already owned by a widget elsewhere on the page — a calendar
+heatmap cell, a map selection, a chart brush — and the bar's job is only to *show* that the filter
+is applied and to let the user take it off. Unlike `type: 'custom'`, which still renders a control
+inside the toolbar, a chip-only filter renders **no control and no toolbar cell at all**: no `field`
+wrapper is emitted for it, so `lr-filter-bar::part(field)` and `::part(field-<filterId>)` never
+match one and a bar whose filters are *all* chip-only shows no empty column — its `controls` row
+still holds the reset button (the "clear all" action such a bar needs), the `end` slot, and the
+loading spinner, exactly like a bar with no filters at all.
+
+Everything else is unchanged from any other filter type. The value lives in `value` under its own
+filter ID, rides every `lr-input`/`lr-reset` detail, counts toward `hasActiveFilters` (so it enables
+the reset button) and toward `invalidFilterIds` when the definition is `required`, renders a
+removable active-filter chip subject to `activeFiltersDisplay`, and is cleared both by removing that
+chip and by `reset()`. A `required` chip-only filter is honoured in **bookkeeping only**: it joins
+`invalidFilterIds`, fails `checkValidity()` and moves `lr-validity-change`, but renders no inline
+error, because the bar renders no element of its own for it — the owning widget is responsible for
+its own error affordance. The inherited `placeholder` is inert here for the same reason it is for
+`type: 'custom'`: there is no field to place it in.
+
+A chip-only definition adds three optional fields of its own:
+
+```ts
+type: 'chip';
+formatValue?: (value: LyraFilterBarFieldValue, locale: string) => string;
+clearValue?: LyraFilterBarFieldValue;
+isEmpty?: (value: LyraFilterBarFieldValue) => boolean;
+```
+
+`formatValue` produces the chip's text, and its `locale` argument is the bar's `effectiveLocale` —
+the same locale every built-in type's own chip formatting and a custom adapter's `formatValue`
+already receive, and the reason a chip-only value (normally an already-formatted string such as a
+localized date) can be localized by the caller. That output is caller data, so — like a filter's
+own label — the bar never routes it through its own localization. Omitted, the fallback ladder is
+the one a custom adapter's omitted `formatValue` uses: a string array renders as a localized
+conjunction list, anything else renders verbatim through `String(value)`, and an unset value renders
+as the empty string. Verbatim is exact: a chip-only value is never run through the date branch that
+localizes a `'date'`/`'date-range'` chip, so an ISO day is not silently reformatted and a value
+containing a slash is not mangled.
+
+`clearValue` is what a chip removal (and `clearFilter()`) writes, defaulting to the empty string —
+what every non-multi built-in type writes. Declare an empty array for an array-valued chip-only
+filter. `isEmpty` overrides the built-in emptiness rule (absent, `false`, the empty string and the
+empty array are empty; everything else is set). **A domain sentinel must pair the two**: declaring
+a sentinel clear value without a matching `isEmpty` leaves the bar reading the "cleared" value as
+still set, so it keeps rendering a chip for it — the identical pairing a custom adapter's own
+`clearValue`/`isEmpty` documents. With the pair declared, the sentinel is never stored in `value`
+(cleared keys are omitted) and an absent key reads back as the sentinel for the owning widget.
+
+```ts
+const filters: LyraFilterBarFilterDefinition[] = [
+  { filterId: "query", label: "Query", type: "text" },
+  {
+    filterId: "day",
+    label: "Day",
+    type: "chip",
+    formatValue: (value, locale) =>
+      new Intl.DateTimeFormat(locale, {
+        dateStyle: "medium",
+        timeZone: "UTC",
+      }).format(new Date(`${String(value)}T00:00:00Z`)),
+  },
+];
+
+// The calendar heatmap beside the bar owns the value; the bar only shows and removes it.
+heatmap.addEventListener("app-select-day", (event) => {
+  const { isoDate } = (event as CustomEvent<{ isoDate: string }>).detail;
+  bar.value = { ...bar.value, day: isoDate };
+});
+bar.addEventListener("lr-input", (event) => {
+  const { value } = (event as LyraFilterBarInputEvent).detail;
+  heatmap.selectedDay = (value["day"] as string | undefined) ?? "";
+});
+```
+
 **TypeScript:** `LyraFilterBar<Defs extends readonly LyraFilterBarFilterDefinition[] =
 readonly LyraFilterBarFilterDefinition[]>` — `value` and the `lr-input`/`lr-reset` detail `value`
 narrow to a record keyed per `filterId`, whose value type follows that filter's own definition (a
 `'select'`, a non-`multiple` `'combobox'`, `'text'`, `'date'`, and `'date-range'` narrow to
 `string`; a `'checkbox-menu'` and a `multiple: true` `'combobox'` narrow to `readonly string[]`; a
-`'custom'` filter keeps the full unconstrained field value). Declare the schema with `as const
+`'custom'` filter keeps the full unconstrained field value, and so does a `'chip'` filter, whose
+value is owned by a widget this component never renders). Declare the schema with `as const
 satisfies readonly LyraFilterBarFilterDefinition[]` and type the element as
 `LyraFilterBar<typeof FILTERS>` to pick it up. Types only; the runtime is unchanged, and an untyped
 `<lr-filter-bar>` keeps today's `LyraFilterBarValue` (`Readonly<Record<string, string | readonly

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

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

package/llms/components/lr-map.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** `maplibre-gl` — see `llms/peers.md`
-- **Themeable via** 20 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 26 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`
 
 ---
@@ -72,18 +72,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
@@ -364,7 +418,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.
 
@@ -380,7 +435,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?,
@@ -402,9 +474,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`.
@@ -429,6 +507,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
@@ -460,6 +570,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`.

package/llms/components/lr-option.md

@@ -167,6 +167,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

package/llms/components/lr-select.md

@@ -85,7 +85,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 = ''`
@@ -124,13 +128,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"
@@ -182,7 +214,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

package/llms/components/lr-streaming-text-core.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** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
-- **Themeable via** 2 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 13 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -59,8 +59,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