@aceshooting/lyra-ui 21.0.0 → 21.1.0

package/llms/components/lr-map.md

@@ -33,7 +33,16 @@ modes use the same expression semantics at initial render and after a theme chan
 **Properties:**
 
 - `center: [number, number] = [0, 0]`
-- `zoom: number = 2`
+- `zoom: number = 2` — `center` and `zoom` are the declarative camera. Assigning either moves the
+  map without emitting anything. When the camera settles after a user gesture or `fitBounds()`, the
+  element writes that camera into both and reports it through `lr-map-view-change`, so its next
+  update never resets it, and a later, different assignment still moves the map. Assigning a value
+  the map already shows moves nothing, so echoing a reported camera back, however late, never stops
+  an animation or gesture. An assignment that does interrupt one (a fit still animating, a
+  gesture's inertia) applies the whole declared camera, `center` and `zoom` alike, so the axis you
+  did not assign is not left wherever the interrupted movement stopped; with nothing in flight,
+  only the assigned axis moves. Because both track the settled camera, a map rebuilt after a
+  disconnect/reconnect opens at the last settled camera rather than the originally declared one.
 - `renderWorldCopies?: boolean` (attribute: false) — forwarded to MapLibre when its map is
   constructed. Leave it unset to preserve MapLibre's own current default; set `false` before
   construction to stop repeating the world horizontally. This is a construction-time option, so a
@@ -448,6 +457,73 @@ shared `maplibre-gl` import without constructing a map or allocating a WebGL con
 `false` when the peer is unavailable, allowing an application to choose a fallback before connecting
 an element.
 
+`fitBounds(bounds: LyraMapBounds, options?: LyraMapFitBoundsOptions): boolean` frames a box
+`[[west, south], [east, north]]` in the viewport: the way to show every current marker, or a
+selected region, whenever the data set changes. Use it instead of calling the peer's own
+`fitBounds()` through `map`, which the element neither knows about nor reports. Once the camera
+settles, the element writes it into `center`/`zoom` and emits `lr-map-view-change` with
+`source: 'fit'`, so declarative state stays in sync and the element never resets the fitted camera.
+
+- `options.padding` — screen pixels kept clear around the box: one number for every side, or a
+  `LyraMapPadding { top?, right?, bottom?, left? }`. The sides are the viewport's physical sides in
+  both text directions, because the map's projected space is physical. A negative or non-finite
+  side counts as `0`. Defaults to `0`.
+- `options.maxZoom` — the highest zoom the fit may reach, so one marker or a tight cluster does not
+  zoom to the street. Clamped into `[0, 22]`; a non-finite value sets no ceiling.
+- `options.animate` — defaults to `true`. The camera never animates under
+  `prefers-reduced-motion: reduce`.
+- Latitudes lie in `[-90, 90]`, with `south <= north`, and longitudes in `[-180, 180]`. A box
+  crossing the antimeridian takes either of MapLibre's forms: `west > east`, or `east` unwrapped
+  past 180, up to one full turn east of `west` (`[[170, -10], [190, 10]]`, the form MapLibre's
+  `LngLatBounds` produces). A single point is a valid zero-size box; pair it with `maxZoom`.
+  Anything else (non-finite or non-number values, out-of-range coordinates, an inverted latitude
+  span, the wrong shape) returns `false` without moving or queueing anything, with a
+  development-mode warning.
+- Callable before the map exists, whether the peer is still loading or an off-screen map has not
+  been constructed yet. The most recent request is queued and applied without animation right
+  after construction, unless `center` or `zoom` has been given a different value since the call.
+  Re-assigning the value already held (a framework re-render building an equal array, say) keeps
+  the queued fit.
+- A `center`/`zoom` assignment made while a fit is still animating wins: the interrupted fit is
+  neither written back nor reported, and the camera lands on the whole declared `center`/`zoom`.
+- Returns `true` once the fit is running or queued, and `false` when the loaded peer cannot fit a
+  box. When the padded box cannot fit the map's current size (padding wider or taller than the
+  map), MapLibre leaves the camera where it is and logs its own warning: the call still returns
+  `true`, and no `lr-map-view-change` fires.
+
+There is deliberately no declarative `bounds` property. `center` and `zoom` already describe the
+camera; a third camera input would need a precedence rule against them, and a framework that
+rebuilds its arrays on every render would refit on every render, pulling the camera away from a user
+who has just panned. A one-shot command whose result lands in `center`/`zoom` keeps one camera input.
+
+```ts
+import type {
+  LyraMap,
+  LyraMapBounds,
+  LyraMapMarker,
+  LyraMapViewChangeDetail,
+} from '@aceshooting/lyra-ui/components/media/map/map.class.js';
+
+let camera: LyraMapViewChangeDetail | undefined;
+const mapEl = document.querySelector('lr-map') as LyraMap;
+mapEl.addEventListener('lr-map-view-change', (event) => {
+  // Keep the host's own camera state in step: { center, zoom, source }.
+  camera = event.detail;
+});
+
+function showMarkers(markers: LyraMapMarker[]): void {
+  mapEl.markers = markers;
+  if (markers.length === 0) return;
+  const lngs = markers.map((marker) => marker.lngLat[0]);
+  const lats = markers.map((marker) => marker.lngLat[1]);
+  const box: LyraMapBounds = [
+    [Math.min(...lngs), Math.min(...lats)],
+    [Math.max(...lngs), Math.max(...lats)],
+  ];
+  mapEl.fitBounds(box, { padding: 48, maxZoom: 14 });
+}
+```
+
 **Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`),
 `lr-map-legend-toggle` (**cancelable**; frozen `LyraMapLegendToggleDetail { value, visible,
 hiddenCategories }` — the activated row's category key, its proposed visibility, and the complete
@@ -480,7 +556,16 @@ separately because it is a synthetic aggregate rather than one of your features:
 is MapLibre's `point_count`/`point_count_abbreviated`/`cluster_id` properties, which is what a
 zoom-to-cluster handler reads. The count label is deliberately not hit-tested (it sits exactly on
 the circle already queried and would only make the label the topmost hit), and a `kind: 'heatmap'`
-layer is never queried at all — MapLibre returns no features for a rendered density surface
+layer is never queried at all — MapLibre returns no features for a rendered density surface.
+Also `lr-map-view-change` (non-cancelable; frozen `LyraMapViewChangeDetail { center, zoom, source }`,
+`source` being `LyraMapViewChangeSource = 'user' | 'fit'`), fired once each time the camera settles
+after a user gesture (drag, wheel, touch, keyboard, Shift+drag box zoom, or a standard peer
+navigation button) or a `fitBounds()` call. `center` is `[longitude, latitude]` with the longitude
+wrapped into `[-180, 180]`. The element has already written the camera into `center` and `zoom`
+when it fires, so a host that mirrors camera state assigns the detail back, at any later time,
+without moving the map. Assigning `center`/`zoom` reconciles without emitting it, so a controlled
+host cannot loop, and camera moves made directly through `map` are not reported — which is why
+`'user'` and `'fit'` are the only sources.
 
 The outer marker-activation detail is frozen, while an opaque marker `unsafeHtml` value remains the
 original supplied value at the MapLibre popup and marker-activation boundary. Treat it as trusted

package/llms/components/lr-markdown-core.md

@@ -7,7 +7,7 @@
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
-- **Deprecations** none
+- **Deprecated property** `codeBlockChrome` / `code-block-chrome` since `21.1.0`; use property `code-block-header`; removal not before `23.0.0` — code-block-chrome is a second spelling of code-block-header with identical behavior: either one enables the code-block header. One name per concept across the Markdown elements and the components that compose them removes a choice with no difference. It keeps enabling the header through the 22.x line, and setting it logs a one-time development warning.
 - **Optional peers** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
 - **Themeable via** 24 parts, 19 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`
@@ -53,8 +53,9 @@ instance's isolated peer-neutral configurable parser; `htmlMode: 'sanitize' | 'e
 `link-target`), `internalLinkPrefix: string = ''` (attribute `internal-link-prefix`),
 `headingOffset: number = 0` (attribute `heading-offset`), `streaming: boolean = false` (reflected),
 `streamingRender: MarkdownStreamingRender = 'plain'` (attribute `streaming-render`, not reflected),
-`codeBlockHeader: boolean = false` (attribute `code-block-header`) with its compatibility alias
-`codeBlockChrome: boolean = false` (attribute `code-block-chrome`),
+`codeBlockHeader: boolean = false` (attribute `code-block-header`) with its deprecated
+compatibility alias `codeBlockChrome: boolean = false` (attribute `code-block-chrome`; removal not
+before 23.0.0),
 `highlightCode: boolean = true` (attribute
 `highlight-code`), `languages: Record<string, ShikiLanguageSource> = {}` (attribute: false) —
 required, unlike `<lr-markdown>`'s optional `languages?:`; empty (the default) means every fenced
@@ -144,7 +145,7 @@ The Markdown part set also includes `task-list`, `task-item`, `task-item-checked
 `task-checkbox`, `table-wrapper`, `code-block-frame`, `code-block-copy-success`,
 `code-block-copy-error` and `streaming-tail`. `codeBlockHeader: boolean = false`
 (attribute `code-block-header`) enables the code-block header; `codeBlockChrome` (attribute
-`code-block-chrome`) is its compatibility alias. Successful and
+`code-block-chrome`) is its deprecated compatibility alias (removal not before 23.0.0). Successful and
 failed writes pass through as `lr-copy` and `lr-copy-error`, carrying the immutable clipboard
 outcome, bubbling and composed.
 

package/llms/components/lr-markdown.md

@@ -7,7 +7,7 @@
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
-- **Deprecations** none
+- **Deprecated property** `codeBlockChrome` / `code-block-chrome` since `21.1.0`; use property `code-block-header`; removal not before `23.0.0` — code-block-chrome is a second spelling of code-block-header with identical behavior: either one enables the code-block header. One name per concept across the Markdown elements and the components that compose them removes a choice with no difference. It keeps enabling the header through the 22.x line, and setting it logs a one-time development warning.
 - **Optional peers** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
 - **Themeable via** 24 parts, 19 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`
@@ -130,7 +130,9 @@ uses for its own `[part="body"]`.
   indented. It copies source text without the renderer's terminal newline, preserving leading tabs
   whenever they match the displayed code after expansion. Custom code renderers and pre-escaped
   code bypass it. `codeBlockChrome: boolean = false` (attribute `code-block-chrome`) is a
-  compatibility spelling; either property enables the header. Plain streaming defers headers until
+  deprecated compatibility spelling (removal not before 23.0.0; setting it logs a one-time
+  development warning): either property enables the header, so use `code-block-header`. Plain
+  streaming defers headers until
   settle; progressive streaming adds them to committed blocks. The button has a localized accessible
   name and native pointer title, with no custom tooltip on keyboard focus. In sanitize mode enabling
   the header also removes authored style elements and their CSS text to prevent visual copy

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

@@ -7,7 +7,7 @@
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
-- **Deprecations** none
+- **Deprecated event** `lr-before-media-download` since `21.1.0`; use event `addEventListener('lr-media-download-request', ...)`; removal not before `23.0.0` — Renamed to the library's dominant *-request veto-event convention. Both names fire from the same activation of a safe file anchor with an equal { src, filename } detail during the compatibility window, the canonical name first, and either may veto the native download/open. A veto through the alias logs a one-time development warning.
 - **Optional peers** none
 - **Themeable via** 5 parts, 4 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`
@@ -61,7 +61,8 @@ and later MIME values restore detection.
   button and the `kind="video"` `open-button` render `disabled`; a safe file chip's anchor loses
   its `href` and `download`, so it genuinely cannot fetch, and gains an explicit `role="link"` so
   its accessible name and `aria-current` stay valid on an element that no longer has an implicit
-  role. `lr-media-open` and `lr-before-media-download` stop firing from every path, `click()`
+  role. `lr-media-open`, `lr-media-download-request` and its deprecated `lr-before-media-download`
+  alias stop firing from every path, `click()`
   included, the action leaves the tab order, and it paints at `--lr-opacity-disabled` with a
   `not-allowed` cursor. Deliberately does NOT reach into the `kind="video"` player: `<video
   controls>` is media content with its own native transport, not this card's action. An
@@ -93,9 +94,13 @@ not exports from the component entry.
 **Events:** `lr-media-open` (`detail: LyraMediaCardOpenDetail { src: string; filename: string }`,
 noncancelable) notifies
 after image-card or video open-button activation; those kinds have no component-owned navigation,
-so a host decides what "open" means. `lr-before-media-download` carries the same detail and is
+so a host decides what "open" means. `lr-media-download-request` carries the same detail and is
 cancelable only for a safe file anchor immediately before its native download/open default; calling
-`preventDefault()` there suppresses that exact default. `detail.src` is whichever internally
+`preventDefault()` there suppresses that exact default. `lr-before-media-download` is its deprecated
+alias (removal not before 23.0.0): it still fires right after the canonical event from the same
+activation, with an equal but separate `detail`, and either event's `preventDefault()` vetoes the
+download/open. A veto through the alias logs a one-time development warning, so move listeners to
+`lr-media-download-request`. `detail.src` is whichever internally
 validated safe-URL sink actually rendered, not necessarily the raw `src` property verbatim — a
 whitespace-padded value is trimmed, so it matches the rendered sink.
 The former generic `lr-open` event is removed in v9: notification and veto phases now have distinct,
@@ -151,7 +156,7 @@ sizing), `--lr-focus-ring-*`, `--lr-transition-fast`.
     .addEventListener("lr-media-open", (e) => openLightbox(e.detail.src));
   document
     .getElementById("file-card")
-    .addEventListener("lr-before-media-download", (e) => shouldUseNativeDownload || e.preventDefault());
+    .addEventListener("lr-media-download-request", (e) => shouldUseNativeDownload || e.preventDefault());
 </script>
 ```
 

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

@@ -9,310 +9,6 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 12 parts, 13 custom properties — see this component's own `@csspart`/`@cssprop` list below
-- **Documented with** `lr-menu`, `lr-dropdown-item` (same section below)
+- **Themeable via** 12 parts, 13 custom properties — see `lr-menu.md`
+- **Documented with** `lr-menu`: see [lr-menu.md](./lr-menu.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
-
----
-
-## `lr-menu` / `lr-menu-item`
-
-The inline semantic menu mapped from Shoelace's `sl-menu`, plus its action-row element. A root
-`<lr-menu>` is always visible and owns the named `role="menu"` list, real roving DOM focus,
-wrapping keyboard navigation, type-ahead, and one canonical selection event. It deliberately has no
-trigger, positioned popup, root open state, placement API, or overlay lifecycle.
-
-Removing or disabling the remembered active item repairs the roving stop without taking focus from
-outside controls or the menu's header/footer. If the changed item held actual focus, focus moves to
-a valid survivor or through the existing owner dismissal path when none remain.
-
-For a menu button or other anchored overlay, compose the semantic controller inside
-`<lr-dropdown>`:
-
-```html
-<lr-dropdown label="Row actions">
-  <button slot="trigger" aria-label="Row actions">⋮</button>
-  <lr-menu>
-    <lr-menu-item value="edit">Edit</lr-menu-item>
-    <lr-menu-item value="delete" variant="danger">Delete</lr-menu-item>
-  </lr-menu>
-</lr-dropdown>
-```
-
-The dropdown shell owns trigger relationships, positioning, opening/closing, outside dismissal,
-focus return, and lifecycle events. The contained menu remains the sole semantic owner: its
-`header`/default/`footer` regions and named `role="menu"` list are preserved, while the outer popup
-is neutral. This is also the composition used for direct `<lr-dropdown-item>` children.
-
-### `lr-menu`
-
-**Properties:**
-
-- `label?: string` — accessible name for the `role="menu"` list. A host `aria-label`
-  attribute is authoritative, including `aria-label=""`; any supplied `label` follows (including `"Menu"` or
-  `""`),
-  then a containing dropdown's supplied fallback, then the localized menu label. Omission,
-  not comparison with an English sentinel, is what selects localization.
-- `dropdownOpen: boolean = false` (attribute: false) — the containing dropdown's controlled open
-  state, used to synchronize the menu interaction engine while it is rendered inside a popup.
-
-**Events:**
-
-- `lr-select` — cancelable, with `detail: { item }`. It originates exactly once at the menu that
-  owns the activated item, then bubbles unchanged through ancestor menus and a containing dropdown.
-  Preventing it anywhere keeps the current menu/submenu chain open. There are no
-  `lr-menu-select`, `lr-menu-item-select`, or nested-selection aliases.
-
-**Slots:** default (`<lr-menu-item>`/`<lr-dropdown-item>` plus semantic separators), `header`, and
-`footer`. Header and footer are composed controls or explanatory regions outside the
-`role="menu"` list, so filters, counts, or footer actions do not violate the menu required-child
-contract. Arbitrary non-item content in the default slot still renders, but is not enrolled as a
-menu item.
-
-**CSS parts:** `header`, `list`, and `footer`. Root `trigger` and `popup` parts do not exist;
-style those on `<lr-dropdown>` when using the overlay composition.
-
-**Themeable custom properties:** the standalone menu surface and a submenu's own surface paint from
-the **shared overlay-surface family** (16.0.0) — `--lr-overlay-surface` (default
-`var(--lr-color-surface-overlay)`), `--lr-overlay-border` (default `var(--lr-color-border-subtle)`),
-`--lr-overlay-radius` (default `var(--lr-radius)`) and, on the submenu only,
-`--lr-overlay-shadow-anchored` (default `var(--lr-shadow-m)`). None is declared on `:host`, so one
-declaration on `:root` (or on any ancestor, to scope it) retints this menu together with every other
-floating surface. A menu contained by `<lr-dropdown>` paints no surface of its own, so the family has
-no effect there — the dropdown's popup carries it. The header/footer dividing rules and a slotted
-`<hr>` deliberately stay outside the family on the decorative `--lr-color-border-subtle`: they
-separate content rather than draw the surface's edge. Otherwise shared spacing and motion tokens.
-Row chrome is controlled through the menu-item properties listed below.
-
-Width is a pair, applied to the standalone surface and to a submenu's own surface alike:
-`--lr-menu-max-inline-size` (default `var(--lr-size-20rem)`) and `--lr-menu-min-inline-size`
-(default `var(--lr-size-10rem)`). They move together — the floor wins over the ceiling, so capping
-alone cannot take a menu below 10rem. Neither is declared on `:host`, so an ancestor theme wrapper's
-value reaches the menu. The ceiling takes a length or a percentage; `100%` and `none` both uncap it
-to the container, and any other value outside `<length-percentage>` is treated as `none` rather than
-dropping the cap's safety terms. Those terms — the shared `--lr-popover-viewport-clamp` and the
-container allocation — are applied outside the name, so no value of the hook can make a menu wider
-than its container or the viewport. (That guarantee is enforced by a registered custom property, so
-an out-of-syntax value falls back cleanly instead of invalidating the whole declaration; an engine
-without `CSS.registerProperty` degrades to "use `100%`, not `none`".) A menu contained by
-`<lr-dropdown>` sizes from its dropdown and is unaffected by both names.
-
-**`--lr-positioning-strategy`** (16.0.0) — the private submenu surface reads this same cascading
-`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
-its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
-property on `<lr-menu>`; set the custom property on `:root`, a theme, or one clipping ancestor to
-change every unset submenu beneath it. A menu contained by `<lr-dropdown>` is positioned by the
-dropdown instead and is unaffected.
-
-**Methods:** no menu-specific public overlay methods. Use `<lr-dropdown>`'s `show()`/`hide()` and
-`open` state for an overlay. Menu-item submenu methods remain public because they drive a row's
-nested disclosure.
-
-**Keyboard and focus:** exactly one navigable row has `tabindex="0"`. ArrowDown/ArrowUp wrap;
-Home/End move to the first/last navigable row; Enter/Space activate; printable input performs
-locale-aware type-ahead. Rows that are disabled, loading, hidden, `aria-hidden`, inert, or inside an
-inert subtree are skipped. Navigation is repaired live when those states or light-DOM membership
-change. A root inline menu does not consume Escape or turn Tab into overlay dismissal; a containing
-dropdown owns those root-level behaviors.
-
-### `lr-menu-item`
-
-A focusable action row owned by `<lr-menu>`. The host itself carries `role="menuitem"` (or
-`menuitemcheckbox`/`menuitemradio`) and roving `tabindex`; `[part="base"]` is only the visual row.
-
-**Properties:**
-
-- `value: string = ''` — identifier available as `event.detail.item.value` on `lr-select`
-- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'small' | 'medium' | 'large' = 'm'`
-- `disabled: boolean = false`
-- `variant: 'default' | 'danger' = 'default'`
-- `type: 'normal' | 'checkbox' | 'radio' = 'normal'`
-- `checked: boolean = false` — meaningful only for `type="checkbox"`/`type="radio"`
-- `group?: string` — narrows a `type="radio"` item's exclusive-choice scope to only the other
-  radio items sharing this same string. Unset, the scope is every `type="radio"` item the same
-  owning `<lr-menu>` owns directly — a nested submenu's radio items belong to that submenu's own
-  `<lr-menu>` instead, so they're never in scope regardless of `group`. Meaningless for
-  `type="normal"`/`"checkbox"`
-- `loading: boolean = false`
-- `href?: string` — when set to a safe link URL (`http:`/`https:`/`blob:`/`mailto:`/relative; see
-  `safeLinkHref`, or `safeDownloadHref` when `download` is set, which drops `mailto:`),
-  `[part="base"]` renders as a real `<a href=…>` instead of a `<span>`, and activation (click, or
-  the owning menu's Enter/Space handling, which forwards through `click()` for a link item so the
-  anchor's own native default action runs) navigates there in addition to firing the usual
-  `select()`/`lr-select` contract. An unsafe/unparseable value falls back to the plain `<span>`,
-  matching `lr-button`'s identical fallback
-- `target?: string` — native anchor `target`, used only while `href` resolves to a link. Setting it
-  (e.g. `'_blank'`) always force-adds `noopener noreferrer` to the rendered anchor's `rel`,
-  matching `lr-button`'s identical pattern
-- `rel?: string` — independently settable author relationship tokens, no default. Author tokens are
-  merged rather than replaced: `opener` is always stripped, and whenever `target` is set the
-  non-removable `noopener noreferrer` floor is added, so a same-tab link (no `target`) keeps
-  exactly the author's tokens while a link opening a new context can never lose the guard
-- `download?: string` — native anchor `download` attribute, used only while `href` resolves to a
-  link. Presence narrows the safe-URL allowlist to `safeDownloadHref`'s, which drops `mailto:` — a
-  mail handoff names no retrievable bytes, so it cannot be a download target
-- `hasSubmenu: boolean` (read-only)
-- `submenuOpen: boolean = false` — transient live state; assigning it drives an existing submenu
-  without moving focus and disconnect resets it
-
-**Methods:**
-
-- `click(): void` forwards programmatic activation through the visual-row path
-- `select(): void` activates through the current owning menu; it is inert while disabled/loading
-- `openSubmenu(focus: 'first' | 'last' | 'none' = 'first'): Promise<void>`
-- `closeSubmenu(): Promise<void>`
-- `getTextLabel(): string` returns the accessibility-visible label used by type-ahead
-
-The computed name is derived from the row's own visible label and does not depend on whether the
-menu is currently displayed, so a row inside a closed dropdown — whose popup is `visibility:
-hidden` — is named the same as an open one, and `getTextLabel()` drives type-ahead either way.
-A row with no label text carries **no** `aria-label` attribute rather than an empty one, so the
-browser falls back to the row's own content; an `aria-label` or `aria-labelledby` you set yourself,
-including an explicitly empty value, still wins.
-
-A checkbox activation first emits cancelable `lr-menu-item-change` with the proposed
-`detail: { value, checked }`. Preventing that event retains the current checked state; the owning
-menu's canonical `lr-select` still follows. A submenu parent is a disclosure instead of an action:
-activation opens its submenu and emits neither checkbox-change nor selection.
-
-A `type="radio"` item works the same way, with exclusive-choice semantics layered on top:
-activating an already-checked radio is a no-op on `checked` — no `lr-menu-item-change`, no state
-change, matching native `<input type="radio">` — but still falls through to the owning menu's
-usual selection. Activating an unchecked radio fires `lr-menu-item-change` with
-`checked: true`; once not prevented, this item becomes `checked` and every other `type="radio"`
-item the same owning `<lr-menu>` owns directly whose `group` matches is unchecked directly
-(without an `lr-menu-item-change` of its own).
-
-**Events:**
-
-- `lr-menu-item-change` — cancelable checkbox/radio-state proposal; never fired when activating an
-  already-checked radio
-- `lr-menu-item-state-change` — internal navigation repair signal with
-  `detail: { disabled, hidden, inert }`; the owning menu consumes and contains it, so it does not
-  escape a menu or a composite wrapper as an apparent public event
-
-Item activation itself is private owner plumbing, not a public child event. Listen for `lr-select`
-on the owning menu.
-
-**Slots:** default label, `icon`, `prefix`, `details`, `suffix`, and `submenu`. Display slots are
-inert visual content; their accessibility-visible default-slot text names the focusable host. The
-submenu slot accepts either one nested `<lr-menu>` or direct mapped items. Long `details` and
-`suffix` content shrinks and ellipsizes within the allocated row in both directions rather than
-expanding the popup.
-
-**CSS parts:** `base`, `icon`, `prefix`, `label`, `details`, `suffix`, `checkmark`,
-`checked-icon`, `spinner`, `spinner__base`, `submenu-icon`, and `submenu`.
-
-**Themeable custom properties:** `--lr-menu-item-gap`, `--lr-menu-item-radius`,
-`--lr-menu-item-danger-color`, `--lr-menu-item-danger-hover-bg`,
-`--lr-menu-item-danger-active-bg`, `--lr-menu-item-checked-bg` (default `transparent`),
-`--lr-menu-item-checked-color` (default `inherit`), `--lr-menu-item-checked-font-weight` (default
-`inherit`), and `--submenu-offset`, plus shared size/focus/color/spacing tokens. The checked hooks
-apply to a `type="checkbox" checked` or `type="radio" checked` row's `[part="base"]`, matching the
-checked/selected-state hooks `<lr-option>`, `<lr-select>`, `<lr-combobox>`, and `<lr-tree-item>`
-already expose; unset, a checked row paints identically to an unchecked one.
-
-Four more row-chrome hooks land in 16.0.0, each an inline fallback so unset rendering is
-byte-identical: `--lr-menu-item-hover-bg` (default `var(--lr-color-brand-quiet)`) is the enabled
-row's fill under the pointer, and the pressed state mixes from that same value, so a retuned hover
-fill keeps its pressed step instead of snapping back to the brand default; `--lr-menu-item-active-bg`
-(default `color-mix(in oklab, var(--lr-menu-item-hover-bg, var(--lr-color-brand-quiet)),
-var(--lr-color-mix-partner) var(--lr-color-mix-active))`) overrides that pressed fill directly,
-matching `--lr-option-active-bg`'s equivalent hook — unset, the pressed row keeps mixing from
-`--lr-menu-item-hover-bg` exactly as before this hook existed; `--lr-menu-item-icon-color` (default
-`inherit`) recolours `[part="icon"]` without touching the label beside it, so it still follows the
-row while the row is disabled or `variant="danger"` unless you say otherwise; and
-`--lr-menu-item-min-height` (default `max(var(--lr-form-control-height), var(--lr-size-24px))`)
-sets the row's minimum block size for a denser or roomier menu, replacing a `::part(base)` rule per
-item. A value below the 24px floor is your call, exactly as it is when overriding the shared ladder
-itself.
-
-Any element assigned to `details` counts as content, including a shadow-rendered
-`<lr-kbd slot="details" keys="mod+t">` chip or an icon. An intentionally empty placeholder element
-also shows the part and reserves one `--lr-menu-item-gap`; whitespace-only text and empty forwarding
-slots keep the part hidden. This also applies to `lr-dropdown-item`.
-
-### Nested submenus
-
-Both supported authoring shapes use the `submenu` slot:
-
-```html
-<lr-menu label="Share actions">
-  <lr-menu-item value="share">
-    Share
-    <lr-menu slot="submenu" label="Share options">
-      <lr-menu-item value="email">Email</lr-menu-item>
-      <lr-menu-item value="link">Copy link</lr-menu-item>
-    </lr-menu>
-  </lr-menu-item>
-</lr-menu>
-```
-
-```html
-<lr-dropdown-item>
-  Share
-  <lr-dropdown-item slot="submenu" value="email">Email</lr-dropdown-item>
-  <lr-dropdown-item slot="submenu" value="link">Copy link</lr-dropdown-item>
-</lr-dropdown-item>
-```
-
-The submenu presentation is private to the parent row, not a second root-menu API. A submenu parent
-has `aria-haspopup="menu"`, explicit `aria-expanded="true|false"`, the transient
-`submenu-open` state, and a logical-direction chevron. Its submenu is named from the parent's
-accessible label unless the submenu supplies its own `aria-label` or non-default `label`.
-
-The into-branch and back-out arrow keys swap under RTL. Enter/Space and the into key open and focus
-the first child; the back-out key and Escape close only the innermost branch and return focus to its
-parent row. Pointer hover uses an intent delay, outside pointer dismissal closes the branch, and at
-most one branch per level is open. Selection bubbles as the same single `lr-select`; a non-vetoed
-selection closes the full nested chain.
-
-### `lr-dropdown-item`
-
-The Web Awesome-compatible name for the same item implementation. It shares all menu-item
-properties, slots, parts, methods, checkbox/radio/state events, roving focus, and canonical parent
-`lr-select` behavior. Its host also exposes native, non-bubbling, composed `focus` and `blur`
-events.
-
-**Attributes:** `href`, `target`, `rel`, and `download` — the same link-rendering properties
-documented above for `<lr-menu-item>`, settable directly in markup
-(`<lr-dropdown-item href="/settings" target="_blank">`). The `rel` guard is identical: author
-tokens merge rather than get replaced, `opener` is always stripped, and setting `target` force-adds
-the non-removable `noopener noreferrer` floor, so a same-tab link keeps exactly the author's tokens
-while a link opening a new context can never lose the guard.
-
-**Events:** native, non-bubbling, composed, non-cancelable `focus` and `blur` (`FocusEvent`) when
-the focusable host gains or loses focus, plus the shared menu-item events above.
-
-**Themeable custom properties:** every `<lr-menu-item>` hook above, including 16.0.0's
-`--lr-menu-item-hover-bg`, `--lr-menu-item-active-bg`, `--lr-menu-item-icon-color` and
-`--lr-menu-item-min-height`.
-`--lr-overlay-surface`, `--lr-overlay-border` and `--lr-overlay-radius` are listed on this tag
-because it shares a stylesheet directory with `<lr-menu>`, whose surface reads them; a dropdown item
-is a row **inside** that surface and paints no surface of its own, so setting them here is a no-op —
-set them on the menu or on any ancestor instead. The row's own corner stays `--lr-menu-item-radius`.
-
-`submenuOpen` reflects to canonical `submenu-open`. HTML normalizes Web Awesome's documented
-mixed-case spelling to `submenuopen`, so that lowercase token is a permanent compatibility alias.
-Adding either spelling opens the submenu and synchronizes the other; removing either closes it and
-removes both. Internal close paths — `closeSubmenu()`, Escape, outside dismissal, selection,
-replacement, and disconnect — clear both spellings, preventing a persistent alias from reopening a
-dismissed branch. An authored initial open request remains pending until submenu content connects.
-
-### 9.0 migration
-
-Root overlay behavior moved from `<lr-menu>` to `<lr-dropdown>`. Migrate mechanically:
-
-- Move a former menu `trigger` slot and menu `open`, `placement`, `anchor`, or
-  `close-on-escape-anywhere` policy to an enclosing `<lr-dropdown>`.
-- Replace `menu.show()`/`menu.hide()` and menu `lr-show`/`lr-hide` listeners with the equivalent
-  dropdown APIs/events.
-- Replace `lr-menu-select` (`detail.value`) and `lr-menu-item-select` listeners with one
-  `lr-select` listener on the menu or dropdown and read `event.detail.item`.
-- Replace menu `::part(trigger)`/`::part(popup)` rules with dropdown part styling. Menu
-  `header`/`list`/`footer` parts remain on the semantic controller.
-
-Standalone mapped `<sl-menu>` markup needs no wrapper: the mechanical `sl-` → `lr-` tag rename
-continues to produce an inline menu.
-
----

package/llms/components/lr-menu.md

@@ -7,7 +7,7 @@
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
-- **Deprecations** none
+- **Deprecated slot-content** default-slot content other than `<hr>`, `<lr-divider>`, `<lr-dropdown-item>`, `<lr-menu-item>`, `<lr-menu-label>` since `21.1.0`; use slot `slot="header" (or slot="footer")`; removal not before `23.0.0` — Content other than items, labels and separators renders inside role="menu" without a menu-item role and is skipped by roving focus; the header and footer slots render the same content outside the list with its native keyboard behavior. Content that lr-dropdown forwards into its own menu is not covered: it mirrors sl-dropdown's free-form default slot.
 - **Optional peers** none
 - **Themeable via** 3 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-menu-item`, `lr-dropdown-item` (same section below)
@@ -63,11 +63,14 @@ is neutral. This is also the composition used for direct `<lr-dropdown-item>` ch
   Preventing it anywhere keeps the current menu/submenu chain open. There are no
   `lr-menu-select`, `lr-menu-item-select`, or nested-selection aliases.
 
-**Slots:** default (`<lr-menu-item>`/`<lr-dropdown-item>` plus semantic separators), `header`, and
-`footer`. Header and footer are composed controls or explanatory regions outside the
-`role="menu"` list, so filters, counts, or footer actions do not violate the menu required-child
-contract. Arbitrary non-item content in the default slot still renders, but is not enrolled as a
-menu item.
+**Slots:** default (`<lr-menu-item>`/`<lr-dropdown-item>` rows, `<lr-menu-label>` captions, and
+`<hr>`/`<lr-divider>` separators), `header`, and `footer`. Header and footer are composed controls
+or explanatory regions outside the `role="menu"` list, so filters, counts, or footer actions do not
+violate the menu required-child contract. Any other default-slot content is deprecated (removal not
+before 23.0.0): it still renders, but inside `role="menu"` without a menu-item role and skipped by
+keyboard navigation, so move it to `slot="header"` or `slot="footer"`. Content that `lr-dropdown`
+forwards into its own menu is not covered: its default slot mirrors `sl-dropdown`'s free-form
+content.
 
 **CSS parts:** `header`, `list`, and `footer`. Root `trigger` and `popup` parts do not exist;
 style those on `<lr-dropdown>` when using the overlay composition.