@aceshooting/lyra-ui 5.1.0 → 5.2.0

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

@@ -128,17 +128,42 @@ internal native date input.
 the internal `<input>`'s own `blur`, bubbling and composed unlike the native event), `focus`
 (re-dispatched from the internal `<input>`'s own `focus`, for the same reason as `blur`)
 
-**Slots:** `label`, `error` (overrides `errorText`), `hint`
+**Slots:** `label`, `error` (overrides `errorText`), `hint`, plus two adornment slots:
+- `start` — content at the inline-start of the input row, before the text field.
+- `end` — content after the text field and the built-in clear action, and before the calendar
+  toggle, so consumer content never sits outboard of the calendar button.
 
-**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `clear-button`,
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `start` and `end`
+(the two adornment-slot wrappers, each `hidden` while nothing is slotted into it), `clear-button`,
 `expand-button`, `expand-icon`, `popup`, `date-picker`, `error`, `hint`
 
 **Themeable custom properties:** `--lr-date-input-padding-block` (default `--lr-space-xs`) and
 `--lr-date-input-padding-inline` (default `--lr-space-s`) — the `input-wrapper`'s padding;
-`--lr-date-input-font-size` (default `inherit`) — the `input` part's font size. All three are
-declared on `:host` and auto-swapped per `size` (`2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the `:host`
-defaults), deliberately matching `lr-input`'s own per-`size` padding/font-size values so a
-same-`size` `lr-input` and `lr-date-input` end up height/density-matched. Plus shared tokens.
+`--lr-date-input-font-size` (default `inherit`) — the `input` part's font size;
+`--lr-date-input-control-min-height` (default `--lr-size-2-5rem`) — the `input-wrapper`'s block-size
+floor. All four are declared on `:host` and auto-swapped per `size`
+(`2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the `:host` defaults), using the same per-`size` values
+`lr-input` uses. Plus shared tokens.
+
+`--lr-date-input-control-height` pins an **exact** `input-wrapper` height (both floors and caps it).
+It is **undeclared by default**, so the row grows to fit its content — see "exact-height hatches"
+under `lr-input`. Pinning it *below* the calendar toggle's 24×24 target is safe: the toggle keeps
+its own `--lr-icon-button-size` floor and simply overflows a short row rather than shrinking, so
+WCAG 2.2 SC 2.5.8 is preserved either way.
+
+**Height parity with `lr-input` is density parity, not pixel parity.** The per-`size` padding and
+font-size scale is shared with `lr-input`, so the two look equally dense at a given `size` — but a
+same-`size` pair does **not** end up the same height, and code that assumes it will be
+disappointed at the small tiers. `[part='input-wrapper']` carries no intrinsic `min-block-size` of
+its own, while `[part='expand-button']` pins `min-block-size: var(--lr-icon-button-size)` that is
+deliberately **not** gated by `size` — the calendar toggle must keep a 24×24 touch target at every
+tier, and `lr-input`'s own password-toggle floors identically. So the row height is pinned
+transitively by that button: at `size="s"` an `lr-input` floors at `1.875rem`/30px, while an
+`lr-date-input` cannot go below roughly 40px plus its padding. Every default value of
+`--lr-date-input-control-min-height` sits below that transitive height, which means the floor is
+inert until you raise it past the button — a lower value changes nothing. To line the two controls
+up exactly, either raise `lr-input`'s floor to meet the date input, or lower
+`--lr-theme-icon-button-size` on a common ancestor (never below 24px).
 
 **Optional peer deps:** none.
 

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

@@ -128,17 +128,42 @@ internal native date input.
 the internal `<input>`'s own `blur`, bubbling and composed unlike the native event), `focus`
 (re-dispatched from the internal `<input>`'s own `focus`, for the same reason as `blur`)
 
-**Slots:** `label`, `error` (overrides `errorText`), `hint`
+**Slots:** `label`, `error` (overrides `errorText`), `hint`, plus two adornment slots:
+- `start` — content at the inline-start of the input row, before the text field.
+- `end` — content after the text field and the built-in clear action, and before the calendar
+  toggle, so consumer content never sits outboard of the calendar button.
 
-**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `clear-button`,
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `start` and `end`
+(the two adornment-slot wrappers, each `hidden` while nothing is slotted into it), `clear-button`,
 `expand-button`, `expand-icon`, `popup`, `date-picker`, `error`, `hint`
 
 **Themeable custom properties:** `--lr-date-input-padding-block` (default `--lr-space-xs`) and
 `--lr-date-input-padding-inline` (default `--lr-space-s`) — the `input-wrapper`'s padding;
-`--lr-date-input-font-size` (default `inherit`) — the `input` part's font size. All three are
-declared on `:host` and auto-swapped per `size` (`2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the `:host`
-defaults), deliberately matching `lr-input`'s own per-`size` padding/font-size values so a
-same-`size` `lr-input` and `lr-date-input` end up height/density-matched. Plus shared tokens.
+`--lr-date-input-font-size` (default `inherit`) — the `input` part's font size;
+`--lr-date-input-control-min-height` (default `--lr-size-2-5rem`) — the `input-wrapper`'s block-size
+floor. All four are declared on `:host` and auto-swapped per `size`
+(`2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the `:host` defaults), using the same per-`size` values
+`lr-input` uses. Plus shared tokens.
+
+`--lr-date-input-control-height` pins an **exact** `input-wrapper` height (both floors and caps it).
+It is **undeclared by default**, so the row grows to fit its content — see "exact-height hatches"
+under `lr-input`. Pinning it *below* the calendar toggle's 24×24 target is safe: the toggle keeps
+its own `--lr-icon-button-size` floor and simply overflows a short row rather than shrinking, so
+WCAG 2.2 SC 2.5.8 is preserved either way.
+
+**Height parity with `lr-input` is density parity, not pixel parity.** The per-`size` padding and
+font-size scale is shared with `lr-input`, so the two look equally dense at a given `size` — but a
+same-`size` pair does **not** end up the same height, and code that assumes it will be
+disappointed at the small tiers. `[part='input-wrapper']` carries no intrinsic `min-block-size` of
+its own, while `[part='expand-button']` pins `min-block-size: var(--lr-icon-button-size)` that is
+deliberately **not** gated by `size` — the calendar toggle must keep a 24×24 touch target at every
+tier, and `lr-input`'s own password-toggle floors identically. So the row height is pinned
+transitively by that button: at `size="s"` an `lr-input` floors at `1.875rem`/30px, while an
+`lr-date-input` cannot go below roughly 40px plus its padding. Every default value of
+`--lr-date-input-control-min-height` sits below that transitive height, which means the floor is
+inert until you raise it past the button — a lower value changes nothing. To line the two controls
+up exactly, either raise `lr-input`'s floor to meet the date input, or lower
+`--lr-theme-icon-button-size` on a common ancestor (never below 24px).
 
 **Optional peer deps:** none.
 

package/llms/components/lr-document-preview.md

@@ -112,7 +112,15 @@ SFMono-Regular, Menlo, Consolas, monospace`) and `--lr-document-preview-spin-dur
 `0.8s`, stopped under reduced motion). `--lr-document-preview-progress` (default `0`) — a unitless
 0–100 number the determinate spinner's `conic-gradient` fill reads; written inline on the ring by
 the component itself from the clamped `progress` property, so overriding it only makes sense to
-repaint the fraction. Plus shared tokens
+repaint the fraction. `--lr-document-preview-active-border` (default
+`var(--lr-color-warning, var(--lr-color-brand))`) — the border color of the `[part='region-highlight']`
+matching `activeHighlightId` (image format only), deliberately distinct from the resting highlight
+border so the active region can be recolored without touching the rest. Like the library's other
+state hooks it is an inline `var()` fallback at the point of use rather than a `:host` declaration,
+so it can be set on the element or on any ancestor — `::part(region-highlight)[data-active]` is
+invalid CSS (Shadow Parts forbids an attribute selector after `::part()`), which previously left
+re-pointing the shared `--lr-color-warning`/`--lr-color-brand` tokens as the only lever, repainting
+every other element that read them. Plus shared tokens
 `--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-space-s/-m/-l/-xs`,
 `--lr-color-text`, `--lr-color-text-quiet`, `--lr-color-danger`, `--lr-color-brand`,
 `--lr-color-on-brand`, `--lr-focus-ring-width/-color/-offset`, `--lr-transition-fast`.

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

@@ -38,7 +38,9 @@ index, label, value }`).
 
 **Slots:** `data-table`, `center`.
 
-**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`.
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`,
+`error` (`role="alert"` message rendered in place of `canvas` when the optional `chart.js` peer
+dependency fails to load — see `llms/components/lr-chart.md`).
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,

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

@@ -36,8 +36,25 @@ menu, an avatar menu, or a history row's overflow menu. Uses the WAI-ARIA "menu
   `this.getAttribute('aria-label') || <computed default>` precedence
 
 - `closeOnEscapeAnywhere: boolean = false` (attribute `close-on-escape-anywhere`) — lets Escape
-  close the menu when focus is on slotted non-menu-item content inside the popup; item activation
-  remains scoped to actual menu items
+  close the menu when focus is on non-menu-item content slotted into the **default** slot, i.e.
+  rendered inside `[part="list"]`; item activation remains scoped to actual menu items. It has no
+  bearing on the `header`/`footer` slots, which sit outside the `role="menu"` list and always close
+  on Escape — so a menu that keeps its composed controls there never needs this property
+
+**Methods:** `show(focus: 'first' | 'last' = 'first')` opens the menu and moves roving focus to the
+first (or, with `'last'`, the last) non-disabled item; a no-op when already open.
+`hide(options?: { focusTrigger?: boolean })` closes it; a no-op when already closed. They are the
+imperative pair for the cases the slotted trigger can't express — a "Done"/"Apply" button *inside*
+the menu, a keyboard shortcut, a parent restoring UI state — without hand-reproducing the
+pending-focus bookkeeping. Both are deliberately thin: positioning, the outside-click listener, the
+`lr-show`/`lr-hide` events, and the initial focus move all stay in one place, so **writing `open`
+directly is fully supported and equivalent apart from the focus moves**. In particular the
+roving-tabindex reset is centralized, so a bare `el.open = false` also clears `activeIndex` and
+never leaves a stale `tabindex="0"` tab stop on the last active item. `hide()` never refocuses
+unless you ask: pass `{ focusTrigger: true }` for a dismissal with nowhere else for focus to land,
+and leave it off when the interaction that closed the menu already put focus somewhere the user
+chose (an outside click, a Tab out). Focus restoration lives in `hide()` rather than in the
+close branch precisely so teardown — disconnecting an open menu — can't steal focus.
 
 **Events:** `lr-show` (no detail — fires only when `open` transitions to `true`, not for markup
 that renders `open` true from the start), `lr-hide` (same first-render guard, opposite
@@ -49,10 +66,25 @@ returning to the trigger)
 are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
 since those attributes belong on the actual interactive trigger, which lives outside this
 component's shadow root), default (`<lr-menu-item>` elements, plus optionally plain `<hr>`
-dividers between groups — native `<hr>` already carries an implicit `separator` role)
+dividers between groups — native `<hr>` already carries an implicit `separator` role),
+`header` and `footer` (composed, deliberately non-menu-item content — a filter/search field, a
+section title, an "Apply"/"Done" button, a count — rendered above/below the items inside
+`[part="popup"]` but **outside** the `role="menu"` list. Both collapse to no box at all while
+unfilled, so a menu that uses neither renders exactly as it did before they existed)
+
+Put composed controls in `header`/`footer` rather than the default slot. Non-item content in the
+default slot still works and is not deprecated at runtime (no warning is emitted), but it sits
+inside `role="menu"`, where ARIA permits only
+`menuitem`/`menuitemradio`/`menuitemcheckbox`/`group`/`separator` children — anything else is an
+`aria-required-children` violation. It is also not Tab-reachable from an item, and needs
+`closeOnEscapeAnywhere` before Escape will close the menu. The named regions have none of those
+problems.
 
 **CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
-positioned floating panel), `list` (the `role="menu"` container wrapping the default slot)
+positioned floating panel), `header` (wrapper around the `header` slot, above the list and outside
+`role="menu"`; `display: none` while that slot is unfilled), `list` (the `role="menu"` container
+wrapping the default slot), `footer` (wrapper around the `footer` slot, below the list and outside
+`role="menu"`; `display: none` while that slot is unfilled)
 
 **Themeable custom properties:** shared tokens only (`--lr-color-surface`, `--lr-color-border`,
 `--lr-radius`, `--lr-shadow`, `--lr-space-xs`, `--lr-transition-fast`).
@@ -142,11 +174,19 @@ navigation with no separate JS bookkeeping. ArrowDown/ArrowUp *on the trigger wh
 opens the menu, focusing the first/last non-disabled item respectively (mirrors native `<select>`).
 Once open, ArrowDown/ArrowUp move the roving focus among non-disabled items and wrap past either end
 (unlike `<lr-select>`'s clamped listbox nav); Home/End jump to the first/last non-disabled item;
-Enter/Space activate the focused item; Escape closes and refocuses the trigger; Tab closes without
-`preventDefault()`, letting the browser's own Tab navigation proceed untouched. All of this list-level
-keydown handling — Escape, Tab, the arrow keys, Home/End, and type-ahead alike — only responds when
-the triggering keydown event's own target is an actual `<lr-menu-item>` element; a keydown bubbling
-up from any other node inside the popup is ignored rather than misread as list navigation. A printable
+Enter/Space activate the focused item; Escape closes and refocuses the trigger. The arrow keys,
+Home/End, Enter/Space and type-ahead only respond when the triggering keydown event's own target is
+an actual `<lr-menu-item>` element; a keydown bubbling up from any other node inside the popup is
+ignored rather than misread as list navigation. Escape and Tab are the two deliberate exceptions.
+Escape from `header`/`footer` content always closes the menu and refocuses the trigger (mirroring
+`lr-popover`'s handling of arbitrary popup content), while Escape from non-item content in the
+*default* slot closes it only with `closeOnEscapeAnywhere` set. Tab never traps focus and never
+calls `preventDefault()` — the browser's own Tab navigation always proceeds untouched — and closes
+the menu only when focus is on its way *out* of `[part="popup"]`: with a focusable in the
+`header`/`footer` region on the far side of the keypress the menu stays open so native Tab can carry
+focus there, and with neither region filled Tab closes exactly as it always has. Tabbing past the
+popup's last focusable in either direction closes the menu, including from slotted non-item content
+— which previously left the menu open while focus walked out of the popup entirely. A printable
 keypress runs type-ahead: roving focus jumps to the next non-disabled item whose text starts with the
 accumulated buffer (cycling from just after the active item, buffer resets ~500ms after the last
 keystroke) — mirrors `<lr-select>`'s identical listbox type-ahead. A click outside both the trigger
@@ -164,8 +204,20 @@ click itself already moved focus somewhere the user chose.
 - `lr-menu-item-select` carries no detail payload (`event.detail === null`); read
   `event.target.value` instead. `<lr-menu>`'s own re-fired `lr-menu-select` is the one that
   carries `detail: { value }`.
-- Tab closes the menu without `preventDefault()` or focus trapping — the browser's own default Tab
-  navigation proceeds untouched, only the (now-stale) open state is cleared.
+- Tab never calls `preventDefault()` and never traps focus — the browser's own default Tab
+  navigation always proceeds untouched. It closes the menu only when Tab would leave
+  `[part="popup"]` entirely; when the `header`/`footer` region holds a focusable on the far side of
+  the keypress, the menu stays open instead and native Tab moves focus into it. With neither region
+  filled, Tab closes exactly as before.
+- Non-item content in the *default* slot is not Tab-reachable from an item — Tab from an
+  `<lr-menu-item>` still closes the menu when there is no `header`/`footer` focusable to move to,
+  even if a `<button>` is slotted alongside the items. Move such controls to `header`/`footer`.
+- `header`/`footer` emptiness is tracked from each slot's own `slotchange` and reflected on the host
+  as `data-has-header` / `data-has-footer` (plus `data-list-empty`, which suppresses the region
+  divider next to an empty list). They are internal styling hooks, not public API — don't set them
+  by hand — but they are why `[part="header"]`/`[part="footer"]` collapse cleanly: a
+  `[part]:empty` rule can never match a part that contains a slot, since Chromium counts the
+  whitespace-only text nodes Lit leaves there.
 - Only Escape and a committed selection refocus the trigger on close; a click outside does not.
 
 ---

package/llms/components/lr-email-viewer.md

@@ -35,9 +35,10 @@ localized show/hide toggle. `false` (the default) preserves the full body render
 **CSS parts:** `base`, `headers`, `from-label`, `from`, `to-label`, `to`, `subject-label`, `subject`,
 `date-label`, `date`, `body`, `body-html`, `body-text`, `attachments`, `attachments-label`,
 `attachment-list`, `attachment-item`, `attachment-button` (an attachment's open button, inside its
-`attachment-item`), `quoted` (a folded quoted-text block, hidden until expanded, only
-while `foldQuotes`), `quote-toggle` (the show/hide-quoted-text toggle button, only while `foldQuotes`),
-`spinner`, and `error`.
+`attachment-item`), `attachment-name` (an attachment's filename, inside `attachment-button`),
+`attachment-size` (an attachment's formatted file size, inside `attachment-button`), `quoted` (a
+folded quoted-text block, hidden until expanded, only while `foldQuotes`), `quote-toggle` (the
+show/hide-quoted-text toggle button, only while `foldQuotes`), `spinner`, and `error`.
 
 **Themeable custom properties:** `--lr-email-viewer-max-height` (default `none`) — maximum block size
 of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.

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

@@ -20,13 +20,23 @@ supplied (an explicit empty array still counts as supplied and skips the auto-lo
 When the filtered set reaches 200 items, the grid automatically windows its visible rows while
 preserving the full option count through `aria-setsize`/`aria-posinset`.
 
+Ships the same opt-in `label`/`hint`/`errorText` form-control chrome as `lr-select`/
+`lr-color-picker` (props + matching named slots + `form-control`/`form-control-label`/`hint`/
+`error` CSS parts) — left unset, none of that chrome renders.
+
 **Properties:** the shared form properties `name`, `value`, `disabled`, and `required`, plus
 `groups: EmojiPickerGroup[] = []` (attribute: false) — `EmojiPickerGroup { key, label, emojis:
 EmojiPickerItem[] }`, `EmojiPickerItem { emoji, name, shortcodes? }`; the search field matches `name`
 and every `shortcodes` entry, case-insensitively. Empty (the default, before the auto-loader
 resolves) renders just the search input and the empty state. `accessibleLabel` (`aria-label`)
 forwards a host-supplied accessible name to the internal `role="listbox"` grid; empty falls back to
-the localized default grid label.
+the localized default grid label. `label: string = ''` — visible label rendered above the
+search/grid; unset renders no label chrome. When `label` (or the `label` slot) is set and
+`accessibleLabel`/a host `aria-label` is not, the grid's accessible name switches from the
+localized default to `aria-labelledby` pointing at the visible label. `hint: string = ''` —
+supporting text rendered below the search/grid; unset renders no hint chrome. `errorText: string =
+''` (attribute `error-text`) — validation-error text rendered below the hint (overridden by slotted
+`error` content when provided); unset renders no error chrome.
 
 **Events:** `lr-change` with `detail: { emoji }` (an emoji was picked — click, or Enter/Space on
 the active grid cell; also sets `value`), plus the shared form `input`, `change`, `focus`, and `blur`.
@@ -39,9 +49,14 @@ Home/End jump to the first/last item, and Enter/Space picks the active item. The
 the input, with `aria-activedescendant` tracking the active option. Hovering an emoji with the
 pointer also moves the active item to it.
 
-**CSS parts:** `base`, `search` (`role="combobox"`), `grid` (`role="listbox"`, the scroll
-viewport), `group-label`, `emoji` (each emoji's own `role="option"` button), `empty` (shown when
-the search matches nothing). While windowing is active the rows are wrapped in `virtual-spacer`
+**Slots:** `label` (custom label content), `hint` (custom hint content), `error` (custom error
+content, overrides the `errorText` attribute when provided).
+
+**CSS parts:** `form-control` (the outer wrapper around label, `base`, error and hint),
+`form-control-label` (the visible label), `base`, `search` (`role="combobox"`), `grid`
+(`role="listbox"`, the scroll viewport), `group-label`, `emoji` (each emoji's own `role="option"`
+button), `empty` (shown when the search matches nothing), `hint` (the hint message), `error` (the
+error message). While windowing is active the rows are wrapped in `virtual-spacer`
 (full-height scroll spacer), `virtual-row` (one absolutely-positioned row), `virtual-label` (an
 `aria-hidden` spacer standing in for a row's missing `group-label`), and `virtual-items` (the row's
 emoji flex line).
@@ -58,6 +73,15 @@ and re-derived only when the resolved pixels can actually change (a token overri
 first render, a theme swap, a root or host font-size change feeding a `rem`/`em` value), never per
 frame.
 
+`--lr-emoji-picker-active-bg` recolors the highlight behind the active/hovered emoji, falling back
+to `--lr-color-brand-quiet` when unset — so the default rendering is unchanged. Hover and
+keyboard-active deliberately share one declaration, so this single hook retints both consistently.
+It exists because `::part(emoji)[data-active]` is **invalid CSS** (an attribute selector cannot
+follow `::part()`), which previously left hijacking the shared `--lr-color-brand-quiet` token — and
+repainting everything else that reads it — as the only way in. Like `lr-time-range`'s preset
+properties, it is written as an inline `var()` fallback at the point of use rather than declared on
+`:host`, so a value set on **any ancestor** reaches it instead of being shadowed.
+
 Two constraints remain. `--lr-emoji-picker-item-size` is clamped up to `--lr-icon-button-size`, the
 shared minimum tappable box: a smaller value does not shrink the button, and the windowed geometry
 follows the clamped, painted size. And windowed rows are absolutely positioned at the row-height

package/llms/components/lr-empty.md

@@ -31,8 +31,11 @@ attribute), `description` (rich description content, overrides the `description`
 
 **Themeable custom properties:** `--lr-empty-compact-align` (compact mode only; defaults preserve
 the existing `flex-start` cross-axis and `start` text alignment, and `center` centers both),
-`--lr-empty-compact-padding` (default `--lr-space-xs` — padding used in compact mode), plus
-shared tokens (`--lr-space-xs/-s/-l`, `--lr-color-text-quiet/-border/-text`).
+`--lr-empty-compact-padding` (default `--lr-space-xs` — padding used in compact mode),
+`--lr-empty-compact-gap` (default `--lr-space-2xs` — gap between the icon, heading, and description
+in compact mode; the non-compact layout's gap stays the plain shared `--lr-space-s` token, not
+independently themeable), plus shared tokens (`--lr-space-xs/-s/-l`,
+`--lr-color-text-quiet/-border/-text`).
 
 **Optional peer deps:** none.
 

package/llms/components/lr-entity-card.md

@@ -27,6 +27,15 @@ itself — `lr-entity-activate` is a request a host routes into `lr-graph`'s own
   `lr-graph-legend.types` entry shape, resolving `entity.type` to a label/color/shape for the badge
 - `communityLabel: string = ''` (attribute `community-label`) — override text for the community chip
 - `showFocusButton: boolean = true` (attribute `show-focus-button`)
+- `compact: boolean = false` (reflected) — tighter root padding and row gap for dense contexts (a
+  dossier rendered in a sidebar, a result list) — the same convention as `lr-empty`'s `compact` and
+  as this component's sibling `lr-community-card`. Purely a density knob: the border and background
+  stay. `false` (the default) keeps the full card padding.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled, padded box; `'plain'`
+  removes the border, background, padding and corner radius, so a card nested inside a container
+  that already draws a border doesn't double the frame. `plain` wins over `compact` when both are
+  set — there is nothing left to tighten.
 
 **Events:** `lr-entity-activate` (`detail: { id }`, the built-in focus button was activated).
 
@@ -37,7 +46,11 @@ itself — `lr-entity-activate` is a request a host routes into `lr-graph`'s own
 `description`, `properties`, `property` (one key/value row), `degree`, `community`, `actions`,
 `focus-button`, `empty` (shown when `entity` is `null`).
 
-**Themeable custom properties:** shared tokens only; a data-driven `entity.type` color is applied as
+**Themeable custom properties:** `--lr-entity-card-compact-padding` (default `var(--lr-space-s)`) —
+`[part='base']`'s padding while `compact`; `--lr-entity-card-compact-gap` (default
+`var(--lr-space-xs)`) — the gap between `[part='base']`'s rows while `compact`. Both apply only in
+the `compact` state, so a dense card can be tuned without re-pointing shared spacing tokens for
+everything else. Otherwise shared tokens; a data-driven `entity.type` color is applied as
 sanitized inline `--lr-badge-*` overrides on the type badge only (the one "type color is
 data-driven by design" exception this library already grants graph nodes) — every other color comes
 from tokens.

package/llms/components/lr-env-list.md

@@ -25,3 +25,12 @@ the real unmasked value).
 **CSS parts:** `base` (the `<dl>` root), `name` (the `<dt>` text), `value-cell` (the `<dd>` wrapping
 an entry's value text and buttons), `value` (carries `data-masked`), `reveal-button`, and
 `copy-button`.
+
+**Themeable custom properties:** `--lr-env-list-reveal-active-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-env-list-reveal-active-border` (default
+`var(--lr-color-brand)`) — the background and border color of a pressed (revealed) reveal toggle.
+Both are inline `var()` fallbacks at their point of use rather than `:host` declarations, so either
+can be set on the element *or any ancestor*. They exist because
+`::part(reveal-button)[aria-pressed='true']` is invalid CSS — Shadow Parts forbids an attribute
+selector after `::part()` — so restyling the pressed state otherwise required overriding the
+library-wide brand tokens.

package/llms/components/lr-eval-dataset.md

@@ -34,7 +34,9 @@ Filterable and taggable evaluation-example list with add, remove, import, and ex
 
 **Events:** `lr-example-select` (`detail: { id: string | null }`), `lr-example-add-request`
 (`detail: undefined`), `lr-example-remove-request` (`detail: { id: string }`), `lr-import-request`
-(`detail: { files: File[] }`), `lr-export-request` (`detail: { format: string }`).
+(`detail: { files: File[] }`), `lr-export-request` (`detail: { format: string }`). `focus`/`blur` —
+re-dispatched (no detail) when the internal search field (only rendered while `searchable`) gains or
+loses focus, since native focus neither bubbles nor crosses the shadow boundary.
 
 **CSS parts:** `base`, `toolbar`, `search`, `search-input`, `tag-filter`, `grid`,
 `add-button`, `remove-button`, `import`, `export`.

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

@@ -49,7 +49,10 @@ built-in download completes), `lr-show`, `lr-hide` (format-menu visibility trans
 
 **CSS parts:** `trigger`, `menu`, `menu-item`, `format-label`, `format-description`
 
-**Themeable custom properties:** shared tokens only.
+**Themeable custom properties:** shared tokens only, including `--lr-popover-viewport-clamp`
+(default `92vw`) — the shared narrow-viewport ceiling the `menu`'s max-inline-size is `min()`ed
+against, alongside its own `20rem` cap and the positioner's available space. See `lr-tour` for the
+shared-clamp note.
 
 **Optional peer deps:** none.
 

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

@@ -27,6 +27,10 @@ parsing (that's left entirely to the host).
 - `maxFileSize: number = 0` (attribute `max-file-size` — bytes; `0` disables the check)
 - `directory: boolean = false` (reflected) — enables native directory selection where supported
 - `paste: boolean = true` (reflected) — accepts files pasted into the dropzone
+- `compact: boolean = false` (reflected) — tighter dropzone padding, gap and label font for
+  constrained spaces (a toolbar, a table cell) — the same convention as `lr-empty`'s `compact`. The
+  dashed border stays; only the internal spacing shrinks. `false` (the default) keeps the full
+  `--lr-space-l` dropzone.
 - `label: string = 'Drop files here or click to browse'`
 - `accessibleLabel: string = ''` (attribute `aria-label`) — overrides `label` as the internal
   dropzone/button accessible name without changing visible copy
@@ -53,9 +57,22 @@ announces correctly.
 **CSS parts:** `base`, `input`, `status` (a visually-hidden `role="status" aria-live="polite"`
 element carrying the drag accept/reject announcement)
 
-**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-space-l`,
+**Themeable custom properties:** `--lr-file-input-compact-padding` (default `var(--lr-space-s)`) —
+`[part='base']`'s padding while `compact`; `--lr-file-input-compact-gap` (default
+`var(--lr-space-2xs)`) — the gap between the dropzone's slotted children while `compact`; and
+`--lr-file-input-compact-font-size` (default `var(--lr-font-size-sm)`) — the label's font size while
+`compact`. All three apply only while `compact` is set, so they are the way to tune a dense dropzone
+without re-pointing shared spacing tokens for everything else on the page. The drag accept/reject
+highlight on `[part='base'][data-drag-state='accept'|'reject']` is independently overridable too:
+`--lr-file-input-accept-border-color` (default `var(--lr-color-success)`) and
+`--lr-file-input-accept-bg` (default `color-mix(in srgb, var(--lr-color-success) 8%, transparent)`)
+for the drag-accept state; `--lr-file-input-reject-border-color` (default `var(--lr-color-danger)`)
+and `--lr-file-input-reject-bg` (default `color-mix(in srgb, var(--lr-color-danger) 8%,
+transparent)`) for drag-reject. All four are inline `var()` fallbacks at the point of use, settable
+on the element or any ancestor, so a consumer can retint just this dropzone's drag highlight without
+hijacking the shared `--lr-color-success`/`--lr-color-danger` tokens used elsewhere. Plus shared
+tokens — `--lr-space-xs`, `--lr-space-l`,
 `--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-color-text-quiet`,
-`--lr-color-success` (drag-accept state), `--lr-color-danger` (drag-reject state),
 `--lr-focus-ring-width/-color/-offset` (`[part="base"]:focus-visible` outline),
 `--lr-opacity-disabled` (`:host([disabled])` dimming).
 

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

@@ -18,3 +18,26 @@ Dashboard filter row that composes Lyra inputs and removable chips, with reset a
 `invalidFilterIds`, `checkValidity`, `reportValidity`, `reset`. **Events:** `lr-input`, `lr-reset`,
 `lr-validity-change`. **CSS parts:** `base`, `controls`, `filter-control`, `active-filters`,
 `chips`, `chip`, `reset-button`, `status`.
+
+Each filter definition's `type` selects which existing Lyra input renders it — this component
+composes them and never invents a control of its own. `'select'`/`'combobox'` map to their
+same-named counterparts (with `combobox`'s `multiple` opting into a multi-value filter),
+`'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.
+
+A `'text'` filter is the one control that is **not** a fully controlled `.value=` binding.
+Re-rendering a text field from `value` mid-typing would push a stale value back in and drop the
+caret to the end, so the field owns its own value while the user types, and an external `value`
+write is synced back into it only once no edit is in flight (a host write, a chip removal, and
+`reset()` all take that path).
+
+`'text'` filters also accept an optional per-filter `debounce` (ms) — how long to wait after the
+last keystroke before committing the typed value to `value` and emitting a single `lr-input`, so a
+server-side query runs once per pause instead of once per character. Omitted, `0`, or a non-finite
+value means no debounce at all: every keystroke commits immediately. A pending debounce is always
+**flushed** by the field's own `change`/blur, so a blur never loses the last keystroke, and
+**cancelled outright** by `reset()`, by removing that filter's chip, and on disconnect — a stale
+keystroke can never overwrite a reset or fire after teardown. `debounce` is ignored for every other
+`type`, whose commits are discrete choices with nothing to debounce.

package/llms/components/lr-flag.md

@@ -58,7 +58,45 @@ installed, renders an empty template (see gotchas).
 Also exported from the package root:
 `languageToCountry(language: string): string | undefined` and the `LANGUAGE_TO_COUNTRY` lookup
 table (region subtag wins, e.g. `en-US` → `us`; plain `en` → `gb`; override the table per-app if you
-need different defaults).
+need different defaults), plus `localeNativeName(tag: string): string`.
+
+`localeNativeName()` returns a BCP-47 tag's **endonym** — the locale's name written in that locale
+itself (`'fr'` → `français`, `'pt-BR'` → `português (Brasil)`). That is what a language switcher
+should list, so a reader who understands none of the current UI language can still find their own.
+It derives from `Intl.DisplayNames`, so no name table ships with the library and results follow the
+browser's own ICU data; the underlying instance comes from a shared memoized cache, since a picker
+does one lookup per offered locale on every render pass. A tag with no display name resolves to the
+tag itself, and so does a structurally invalid one — `Intl.DisplayNames` throws a `RangeError` on
+those rather than falling back, and a language picker should degrade to showing the raw tag rather
+than tearing down the render. Pair it with `languageToCountry()` for the flag half of the same row.
+
+**Locale picker recipe.** A locale picker is a composition, not a component: `<lr-popover>` supplies
+the light-dismiss surface, `<lr-flag>` the country mark, `localeNativeName()` the endonym, and
+`aria-current="true"` marks the active choice. Which locales exist is the app's decision, so the app
+owns the list. Set `lang` on each row so assistive tech pronounces the endonym in its own language,
+and use `variant="compact"` at icon scale.
+
+```html
+<lr-popover placement="bottom-start">
+  <button slot="trigger">
+    <lr-flag language="fr" label="" style="height: 1rem"></lr-flag>
+    <span>français</span>
+  </button>
+  <ul role="list">
+    <!-- one <li><button lang="pt-BR" aria-current="false"> … </button></li> per offered locale -->
+  </ul>
+</lr-popover>
+```
+
+```js
+import { localeNativeName, languageToCountry } from '@aceshooting/lyra-ui';
+
+const rows = ['en', 'fr', 'de', 'pt-BR', 'ja', 'ar'].map((tag) => ({
+  tag,
+  name: localeNativeName(tag),   // endonym, e.g. "português (Brasil)"
+  country: languageToCountry(tag), // flag code for the same row
+}));
+```
 
 ```html
 <lr-flag country="fr" label="France"></lr-flag>

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

@@ -73,8 +73,21 @@ with a console warning), `top-start`, `top-end` (floating corner overlays), `bot
 `live-region`, `edge-list` (a visually hidden list of every edge).
 
 **Themeable custom properties:** `--lr-flow-canvas-grid-size` (default `8px`, dotted background
-spacing), `--lr-flow-canvas-march-duration` (default `var(--lr-transition-ambient)`, running-edge
-march animation duration).
+spacing — the canvas also writes it inline as `${grid}px` from the `grid` property, which wins over
+the stylesheet fallback whenever a grid is in effect), `--lr-flow-canvas-march-duration` (default
+`var(--lr-transition-ambient)`, running-edge march animation duration), and
+`--lr-flow-canvas-node-current-outline-color` (default `var(--lr-color-brand)`) — the outline color
+of the current (`aria-current`) node. Like every state-scoped custom property in this library it is
+an inline `var()` fallback at its point of use rather than a `:host` declaration, so it can be set on
+the element *or any ancestor*. It exists because Shadow Parts forbids an attribute selector after
+`::part()` — `::part(node)[aria-current='true']` is invalid CSS — so the current node could otherwise
+only be restyled by overriding the library-wide `--lr-color-brand` token, repainting everything else
+that reads it. The same restriction motivates three more state-scoped outline colors:
+`--lr-flow-canvas-node-connect-invalid-outline-color` (default `var(--lr-color-danger)`) — outline of
+a node that is an invalid connect-gesture drop target; `--lr-flow-canvas-node-connect-target-outline-color`
+(default `var(--lr-color-brand)`) — outline of a node that is a valid connect-gesture drop target; and
+`--lr-flow-canvas-drop-active-outline-color` (default `var(--lr-color-brand)`) — outline of the
+viewport itself while a palette item is dragged over it (`droppable`).
 
 **Optional peer deps:** none.
 

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

@@ -20,16 +20,23 @@ no editing commands live here.
 - `for: string = ''` — id of the target `lr-flow-canvas`; empty resolves to the nearest ancestor
 - `orientation: 'vertical' | 'horizontal' = 'vertical'` (reflected) — button-cluster layout axis
 - `hideLock: boolean = false` (attribute `hide-lock`) — omits the lock/unlock toggle button
+- `appearance: FlowControlsAppearance = 'card'` (reflected) — `'card' | 'plain'`; `'plain'` drops
+  `[part="base"]`'s border, background, padding, corner radius and its floating-surface `box-shadow`,
+  for a cluster placed in a host toolbar or panel that already draws its own surface. There is
+  deliberately no `compact`: the padding is already the smallest spacing step and the only remaining
+  room is the buttons' `--lr-icon-button-size` hit-area floor
 
 **Events:** none dispatched directly — each button calls the resolved canvas's own `zoomIn()`/
 `zoomOut()`/`fit()`, or toggles its `locked` property.
 
 **Slots:** default — extra host buttons appended to the cluster, styled by the same group.
 
-**CSS parts:** `base` (the `role="group"` wrapper), `zoom-in`, `zoom-out`, `fit`, `lock` (omitted
-when `hideLock`).
+**CSS parts:** `base` (the `role="group"` wrapper; drops its floating-surface chrome under
+`appearance="plain"`), `zoom-in`, `zoom-out`, `fit`, `lock` (omitted when `hideLock`).
 
-**Themeable custom properties:** shared tokens only.
+**Themeable custom properties:** shared tokens only — `--lr-icon-button-size` (each button's minimum
+hit area, unchanged by `appearance`), `--lr-shadow`, `--lr-color-surface`, `--lr-color-border`,
+`--lr-radius`, `--lr-space-2xs`, `--lr-focus-ring-width`/`-color`/`-offset`.
 
 **Optional peer deps:** none.
 
@@ -43,5 +50,9 @@ when `hideLock`).
 - `for` resolution is identical to `lr-flow-minimap`/`lr-flow-run-overlay`: an explicit id, else
   the nearest ancestor canvas — none of the three companions import `LyraFlowCanvas` as a value, only
   its types, so registration order between them and the canvas never matters.
+- `appearance="plain"` drops the `box-shadow` along with the border and background — unlike most
+  `plain` escapes in this library, which only reset the border/background/padding/radius. A lift
+  shadow with no surface under it reads as a stray smudge, so the whole floating-surface treatment
+  goes together (same as `lr-flow-run-overlay`'s `plain`).
 
 ---