@aceshooting/lyra-ui 21.0.0 → 21.1.0

package/llms/components/lr-dropdown-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, 16 custom properties — see this component's own `@csspart`/`@cssprop` list below
-- **Documented with** `lr-menu`, `lr-menu-item` (same section below)
+- **Themeable via** 12 parts, 16 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-dropdown.md

@@ -92,6 +92,12 @@ its surface.
   inherits `<lr-popover>`'s `trigger`/`showDelay`/`hideDelay`/`hoverBridge`, and honors the
   cascading `--lr-positioning-strategy` custom property ahead of this mirrored `absolute` default
   when neither spelling is authored on the instance.
+- `topLayer: boolean = false` (attribute `top-layer`, reflected) — inherited from `<lr-popover>`:
+  always shows the open menu in the browser top layer, placed `fixed` whatever
+  `positioning-strategy`/`hoist` say, so a dropdown in a `z-index`ed fixed header opens above a
+  sibling surface stacked higher. Submenus of a promoted menu stay above the sibling surface too.
+  Unset, a dropdown is promoted only when a trapping ancestor forces it (see **Anchored overlays
+  and the top layer**).
 - `containingElement?: HTMLElement` (property only) — an external element that counts as inside for
   light-dismiss handling.
 - `arrow`, `withoutArrow` (`without-arrow`), `arrowPlacement`, `arrowPadding`, and `accessibleLabel`

package/llms/components/lr-flag.md

@@ -93,7 +93,15 @@ 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). Only the table's own entries are eligible for base-language fallback;
-inherited object members such as `constructor` resolve to `undefined`. Also exported:
+inherited object members such as `constructor` resolve to `undefined`. A region-less tag whose
+script subtag implies a different likely region than its bare language takes that region instead of
+the table default, so Traditional and Simplified Chinese never share a flag: `zh-Hant` → `tw` while
+`zh` and `zh-Hans` → `cn`. The rule is not specific to Chinese: `zh-Hanb` and `zh-Bopo` → `tw`, and
+`kk-Arab` (Kazakh in Arabic script, as written in China) → `cn` rather than the `kk` default of `kz`;
+pass `country` when a different flag is wanted. A script that implies the language's own likely
+region keeps the table's convention (`en-Latn` → `gb`), a language with no table entry stays
+unresolved, and an engine without `Intl.Locale` likely-subtags data uses the table default. Also
+exported:
 `localeNativeName(tag: string): string`.
 
 `localeNativeName()` returns a BCP-47 tag's **endonym** — the locale's name written in that locale

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

@@ -50,7 +50,10 @@ owns none of that.
 
 **Slots:** default (body content), `icon` (leading header glyph), `header` (replaces the built-in
 heading row entirely), `toolbar` (action row at the block-end edge; revealed by hover/focus on
-hover-capable devices and always visible with a coarse pointer or no hover).
+hover-capable devices and always visible with a coarse pointer or no hover; it also stays revealed
+while an `lr-dropdown`, `lr-popover` or `lr-context-menu` opened from it is open, because that menu
+sits in the browser top layer, where Chromium and WebKit stop matching `:hover`/`:focus-within` on
+the node).
 
 **CSS parts:** `base` (the row wrapping the input handles, the card and the output handles — it
 carries no card chrome of its own), `card` (the bordered, filled node card), `header`, `icon`,

package/llms/components/lr-geojson-view.md

@@ -7,95 +7,8 @@
 - **Family** `components/viewers/` — 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)
-- **Deprecations** none
+- **Deprecated component** `lr-geojson-view` since `21.1.0`; use component `<lr-geojson-viewer>`; removal not before `23.0.0` — lr-geojson-view is the pre-v9 name of lr-geojson-viewer and adds no behavior of its own; it survives only as a distinct subclass so both names can share one registry. This reverses the earlier promise to keep the alias permanently: the tag, the LyraGeojsonView class and its geojson-view routes keep working unchanged through the 22.x line, and connecting the tag logs a one-time development warning.
 - **Optional peers** `maplibre-gl` — see `llms/peers.md`
-- **Themeable via** 7 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
-- **Documented with** `lr-geojson-viewer` (same section below)
+- **Themeable via** 7 parts, 1 custom property — see `lr-geojson-viewer.md`
+- **Documented with** `lr-geojson-viewer`: see [lr-geojson-viewer.md](./lr-geojson-viewer.md).
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
-
----
-
-## `lr-geojson-viewer` / `lr-geojson-view`
-
-Document-registry bridge that fetches, validates, and renders a GeoJSON file through `<lr-map>`'s
-`dataLayers`. The canonical class is `LyraGeoJsonViewer`; the pre-v9 `lr-geojson-view` tag and
-`LyraGeojsonView` class name remain compatibility aliases. The document registry renders the
-canonical tag and matches `application/geo+json` and `.geojson` filenames.
-
-Validates the parsed JSON is a `Feature`/`FeatureCollection`/bare geometry (one of `Point`,
-`LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, `MultiPolygon`, `GeometryCollection`) before
-rendering; anything else renders the localized `geojsonViewInvalid` error. On success, it walks every
-value and object key first, rejecting more than 50,000 graph units, nesting beyond 64 levels, more
-than 2 Mi UTF-16 units of aggregate keys/string values, or more than 4 Mi UTF-16 units of formatted
-metadata before serialization or peer handoff. It then walks every coordinate under a separate
-10,000-position ceiling to compute a bounding box and fits a `center`/`zoom` to it (a Web-Mercator-fit
-approximation weighting latitude span ~2x, with 40% padding), then hands the parsed value to
-`<lr-map>` as a single `dataLayers` entry (`sourceId: 'lr-geojson'`). When the optional
-`maplibre-gl` peer isn't installed, it falls back to a status line plus a `<lr-json-viewer
-collapsed-depth="2">` of the raw value instead of the map.
-
-The root owns the named `region` landmark while loading, in fallback/error/idle states, and while a
-lazy map initializes. After `lr-map-load`, landmark ownership transfers to the map canvas so there
-is exactly one named region. Serialized metadata is locally inline-scrollable, preventing long
-unbroken values from widening a 320px allocation.
-
-**Properties:** `src: string = ''` — URL to fetch and parse. `name: string = ''` — accessible label,
-used as `<lr-map>`'s `label` and the root's `aria-label` (falling back to the localized
-`geojsonViewLabel` when unset). A host `aria-label` takes precedence over `name`.
-`maxHeight: string = ''` (attribute `max-height`) is a CSS length that caps `[part="base"]` —
-covering the loaded map, the serialized metadata, and the missing-peer fallback alike — by writing
-`--lr-geojson-viewer-max-height` inline on it; invalid CSS `max-height` values, declaration breaks,
-and `url()` are ignored. The shared
-text-viewer contract adds `highlights`, `activeHighlightId`, `anchor`, and
-`anchorKinds` (`['text-quote', 'fragment']`), plus `search()`, `searchNext()`, `searchPrevious()`,
-`clearSearch()`, and `scrollToAnchor()` for the ordinary-DOM serialized feature metadata and status
-text, independent of whether the optional map peer is available. Fragment resolution is an exact
-DOM `id` lookup, but the generated metadata, status, and map output define no fragment ids, so a
-fragment jump reports `found: false`. Use a text-quote anchor for serialized metadata.
-
-**Events:**
-
-- `lr-render-error` — `detail: { error }` — fetch, parse, shape-validation, or missing-map capability
-  failure. A missing optional MapLibre peer also keeps the serialized metadata fallback visible.
-- `lr-search-change` — `detail: { query: string; matchCount: number; matchCountExact: boolean; activeIndex: number }` — fired
-  whenever serialized-metadata search state changes.
-- `lr-anchor-result` — `detail: { found: boolean }` — fired after an `anchor` assignment or
-  `scrollToAnchor()` call is applied.
-- `lr-text-select` — `detail: TextSelectDetail` (`{ text: string; anchor: LyraAnchor | null; rects:
-DOMRect[] }`) — fired after a selection ends inside the serialized metadata.
-
-`lr-highlight-activate` is not part of this registry bridge's event contract: serialized-metadata
-highlights are passive and cannot be activated.
-
-The three shared text-viewer events bubble and compose and are non-cancelable.
-
-**CSS parts:** `base` (the root container with explicit `aria-busy="true"|"false"`), `status` (the
-ordinary feature-count line, shown only in the `<lr-map>` path; a successful transition uses the
-shared document-level polite sink), `metadata` (selectable/searchable serialized GeoJSON `<pre>`,
-rendered in both map and fallback paths), `missing-library` (the missing-`maplibre-gl` callout shown
-alongside the `lr-json-viewer` fallback; its transition uses the shared document-level assertive
-sink), `error` (ordinary visible error text; later transitions use the same assertive sink),
-`spinner` (a decorative skeleton plus an ordinary visually-hidden localized label; later loading
-transitions use the shared document-level polite sink), and `anchor-live-region` (an aria-hidden,
-non-live shadow mirror of the latest anchor-jump message; the spoken copy is appended to the shared
-document-level polite sink only while the viewer and its composed ancestors are exposed to the
-accessibility tree). No active live semantics are rendered in the viewer's shadow tree.
-
-Those states carry the same visual tones the rest of this family uses rather than plain inherited
-body text: `error` is `--lr-color-danger` (matching `lr-docx-viewer`/`lr-email-viewer`/
-`lr-html-viewer`), `missing-library` is `--lr-color-warning` -- a missing optional peer is a degraded
-but working state, since the `lr-json-viewer` fallback below it still renders the data, not a failure
--- and `status` is the quiet `--lr-color-text-quiet` metadata tone.
-
-**Themeable custom properties:** `--lr-geojson-viewer-max-height` (default `none`) — maximum block
-size of `[part="base"]`, matching every other viewer in this family. It is also settable via the
-`maxHeight` property, which writes this token inline on `[part="base"]`.
-
-The canonical tag is registered by importing `geojson-viewer/geojson-viewer.js`; the permanent
-compatibility tag and old deep route remain available through `geojson-view/geojson-view.js`.
-Remote
-resources are capped at 25 MB; exceeding it surfaces the localized `documentPreviewResourceTooLarge`
-message instead of the map. Lyra supports MapLibre v5 and v6; consumers must import its CSS.
-MapLibre v5's standard build includes its worker, while v6 is ESM-only, requires WebGL2, and needs
-its module-worker URL configured for the bundler before this viewer constructs the nested map. See
-`llms/components/lr-map.md` for the Vite v6 example and the other bundler variants.

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

@@ -18,9 +18,13 @@
 ## `lr-geojson-viewer` / `lr-geojson-view`
 
 Document-registry bridge that fetches, validates, and renders a GeoJSON file through `<lr-map>`'s
-`dataLayers`. The canonical class is `LyraGeoJsonViewer`; the pre-v9 `lr-geojson-view` tag and
-`LyraGeojsonView` class name remain compatibility aliases. The document registry renders the
-canonical tag and matches `application/geo+json` and `.geojson` filenames.
+`dataLayers`. The canonical class is `LyraGeoJsonViewer`. The pre-v9 `lr-geojson-view` tag, its
+`LyraGeojsonView` class and `LyraGeojsonViewEventMap` type are deprecated compatibility aliases
+(removal not before 23.0.0; this replaces the earlier promise to keep them permanently): they keep
+working unchanged until then, and connecting `lr-geojson-view` logs a one-time development warning.
+Rename them to `lr-geojson-viewer`, `LyraGeoJsonViewer` and `LyraGeoJsonViewerEventMap`. The
+document registry renders the canonical tag and matches `application/geo+json` and `.geojson`
+filenames.
 
 Validates the parsed JSON is a `Feature`/`FeatureCollection`/bare geometry (one of `Point`,
 `LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, `MultiPolygon`, `GeometryCollection`) before
@@ -91,8 +95,12 @@ but working state, since the `lr-json-viewer` fallback below it still renders th
 size of `[part="base"]`, matching every other viewer in this family. It is also settable via the
 `maxHeight` property, which writes this token inline on `[part="base"]`.
 
-The canonical tag is registered by importing `geojson-viewer/geojson-viewer.js`; the permanent
-compatibility tag and old deep route remain available through `geojson-view/geojson-view.js`.
+The canonical tag is registered by importing `components/lr-geojson-viewer.js` (deep route
+`components/viewers/geojson-view/geojson-viewer.js`). The deprecated `components/lr-geojson-view.js`,
+`components/viewers/geojson-view/geojson-view.js` and `geojson-view.class.js` routes register or
+export the alias (the registration routes also register `lr-geojson-viewer`) and keep working until
+their removal, no earlier than 23.0.0; an application importing one of them only to register the
+canonical tag switches to `components/lr-geojson-viewer.js`.
 Remote
 resources are capped at 25 MB; exceeding it surfaces the localized `documentPreviewResourceTooLarge`
 message instead of the map. Lyra supports MapLibre v5 and v6; consumers must import its CSS.

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

@@ -108,7 +108,10 @@ sibling of it, not piped through `<lr-icon>`: the internal `<lr-icon>` mounts on
 set, so with `icon` left empty your content is the button's only child. That is what lets a
 complete element — an `<svg>`, an `<img>`, an `<lr-flag>` — render at its own natural aspect ratio
 instead of being forced into a 1:1 box. Setting both `icon` and slotted content renders both, side
-by side; that is a valid composition, not a fallback.
+by side; that is a valid composition, not a fallback. No wrapper sits between the slot and the
+native control, and that control declares no overflow clip. A glow painted around slotted content
+therefore keeps its full silhouette instead of being cut to the glyph's box. The
+`gemstoneAccentPicker` trigger's `gemstoneSelectedGlyphStyles` halo relies on this.
 
 **Bare SVG geometry fallback:** slotted bare SVG _geometry_ (`path`, `circle`, `rect`, `line`,
 `polygon`, `polyline`, `ellipse`, `g`, `use`) with no `icon` set and no enclosing `<svg>` of its

package/llms/components/lr-icon.md

@@ -7,7 +7,9 @@
 - **Family** `components/utility/` — 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)
+- **Deprecated css-property** `--lr-icon-fixed-width` since `21.1.0`; use host-css-property `inline-size (the same value, on the fixed-width icons only)`; removal not before `23.0.0` — This property only sizes the box while the deprecated fixed-width attribute is set, so it shares that attribute's removal window. A host inline-size declaration reproduces the wider box without a component-specific custom property; a glyph wider than 1em then keeps its intrinsic width instead of being squeezed to 1em.
 - **Deprecated property** `autoWidth` / `auto-width` since `8.0.0`; use property `canvas="auto"`; removal not before `10.0.0` — autoWidth is a boolean compatibility spelling that cannot express fixed canvas sizes; canvas covers both automatic and explicit sizing. That version is a policy floor, not a plan: `wa-icon` still publishes its own deprecated `auto-width` attribute, so this alias is removed only when upstream's is.
+- **Deprecated property** `fixedWidth` / `fixed-width` since `21.1.0`; use host-css-property `inline-size: var(--lr-size-1-5em) on that icon (or the --lr-icon-fixed-width value it used)`; removal not before `23.0.0` — fixed-width predates the mirrored canvas vocabulary, whose default fixed canvas already gives every icon the same 1.25em box so a column of icons lines its labels up. Where the wider 1.5em box matters, a host inline-size reproduces it, except that a glyph wider than 1em keeps its intrinsic width instead of being squeezed to 1em. Neither pinned upstream publishes fixed-width, so it is a Lyra-only spelling.
 - **Optional peers** `dompurify` — see `llms/peers.md`
 - **Themeable via** 4 parts, 45 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`
@@ -63,9 +65,14 @@ Pairs with `lr-icon-button` (see `llms/components/lr-icon-button.md`).
   `flip`, `flip-360`, `shake`, `spin`, `spin-pulse`, `spin-reverse`, `spin-snap`, `spin-snap-4`,
   `spin-snap-8`, `buzz`, `wag`, `float`, `swing`, or `jello`. Every treatment stops under
   `prefers-reduced-motion: reduce`.
-- `fixedWidth: boolean = false` (attribute `fixed-width`, reflected) — widens the icon _box_ to
-  `--lr-icon-fixed-width` while the glyph keeps `--lr-icon-size` and centres inside it, so a column
-  of differently-shaped icons lines its labels up.
+- `fixedWidth: boolean = false` (attribute `fixed-width`, reflected, deprecated; removal not before
+  23.0.0) — widens the icon _box_ to `--lr-icon-fixed-width` while the glyph's svg is pinned to
+  `--lr-icon-size` (1em by default) and centres inside it, so a column of differently-shaped icons
+  lines its labels up. It keeps working unchanged, and setting it logs a one-time development
+  warning. Omit it: the default canvas already gives every icon the same 1.25em box. For the wider
+  1.5em box set `lr-icon { inline-size: var(--lr-size-1-5em); }` on the host instead. One geometry
+  difference: a glyph wider than 1em keeps its intrinsic width (up to the box) instead of being
+  squeezed to 1em.
 
 **Events:**
 
@@ -100,8 +107,9 @@ source tree.
 - `--lr-icon-size` (unset by default) — when supplied, overrides both canvas dimensions. Without
   it, the selected `canvas` uses the font-relative sizes above. Stroke color is `currentColor` and
   the host is `color: inherit`, so color comes from surrounding text with no configuration.
-- `--lr-icon-fixed-width` (default `--lr-size-1-5em`) — inline size of the box while `fixed-width`
-  is set.
+- `--lr-icon-fixed-width` (default `--lr-size-1-5em`; deprecated together with `fixed-width`,
+  removal not before 23.0.0) — inline size of the box while `fixed-width` is set. Set `inline-size`
+  on the host instead.
 - `--lr-icon-rotate` (default `0deg`), `--lr-icon-flip-x` and `--lr-icon-flip-y` (default `1` each) —
   the transform inputs. `--lr-icon-rotate` is written inline from the `rotate` property and the flip
   factors are set to `-1` by `flip`, so set those properties rather than these tokens.
@@ -169,7 +177,7 @@ unregisterIconLibrary("material"); // icons using it revert to the built-in glyp
   name="star"
   label="Favourite"
 ></lr-icon>
-<lr-icon library="material" name="delete" fixed-width></lr-icon>
+<lr-icon library="material" name="delete"></lr-icon>
 <lr-icon name="search" canvas="square" animation="beat"></lr-icon>
 ```
 

package/llms/components/lr-input.md

@@ -220,8 +220,15 @@ and cancellation rules. Never fires while `debounce` is unset, `0`, or non-finit
 `prefix` (alias of `start`), `suffix` (alias of `end`),
 `clear-button` (non-empty clearable `text`/`search` inputs only),
 `hint`/`form-control-help-text` (compatibility names on the same hint node), and `error`.
-Long `start`/`end` adornments shrink and ellipsize inside their flex allocation rather than
-widening a narrow field; label, hint, and error text wrap at unbroken boundaries. The
+In a constrained row the native field gives up its spare width first, so a short adornment such
+as a measurement unit (`kWh`) stays whole beside a narrow value. While a `start` or `end` adornment
+is shown the field keeps a four-character floor; only then do the adornments shrink: each is
+capped at half the row, and genuinely long adornments ellipsize inside that allocation rather than
+widening a narrow field. The floor holds against the fixed clear, password-toggle and stepper
+actions too, so a row with an adornment that is narrower than those actions plus the floor
+overflows rather than hiding the value. A row without adornments has no floor: its field still
+yields entirely to those actions. A shrink-to-fit container still sizes the field to its native
+intrinsic width. Label, hint, and error text wrap at unbroken boundaries. The
 `Narrow RTL (320px)` story exercises both adornments with a clear action and localized long copy.
 
 **The required marker.** `required` with a non-empty `label` paints the library's shared marker on

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

@@ -67,7 +67,9 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
   them side by side; ignored for `type="line"`
 - `tickFormat?: (value: number) => string` (attribute: false) — formats a y-axis tick value for
   display (e.g. `(v) => \`$${v.toFixed(2)}\`` for currency, or a duration formatter for `"42s"`).
-  Falls back to the built-in "nice numbers" formatter when unset.
+  Falls back to the built-in "nice numbers" formatter when unset. The returned string is painted
+  bidi-isolated, so `2.4 MiB/s` keeps its number-unit order under `dir="rtl"` (see
+  [Formatted labels in right-to-left layouts](#formatted-labels-in-right-to-left-layouts)).
 - `formatter?: LyraChartFormatter` (attribute: false) — family-wide context-object formatter used
   by visual/tooltips, spoken text, legends, tables, and CSV export. It takes precedence over the
   older surface-specific hooks, which remain available as compatibility fallbacks.
@@ -125,14 +127,20 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
   actually render *text*: after the global record sampler runs, it selects from those retained
   categories, always shows the first and last sampled label, and roughly evenly distributes the
   rest between them. A number is authoritative up to the number of sampled categories. `'auto'`
-  derives the cap after each resize from the resolved plot width and widest rendered caller label,
-  using the same deterministic 7px-per-
-  character estimate as label ellipsis plus 10px of lane breathing room. It therefore responds to
-  either `layout` mode without DOM text measurement or browser-specific font metrics. Unset (the
-  default) renders every label, unchanged. Each rendered category label is allocation-aware:
-  narrow/long text is ellipsized before paint, with the complete caller label retained as its
-  accessible name. Independently, the global 1,000-record safety sampler may bound both marks and
-  labels for very large category×series input.
+  re-selects after each resize from the resolved tick positions and the widest rendered caller
+  label, using the same deterministic 7px-per-character estimate as label ellipsis. Whenever the
+  first and last labels fit side by side, it keeps at least 10px of breathing room between every
+  adjacent pair of labels; when even those two do not fit, only they remain and label ellipsis
+  prevents overlap. Each label is measured where it paints: centered on its tick, except the first
+  and last category, which anchor toward the plot interior (mirrored under RTL) and so occupy their
+  whole width on the inner side of their tick. Label centers are spaced evenly between those two
+  boundary labels, so neither boundary pair is crowded. A `barX` that reorders the ticks away from
+  source order falls back to the width-only cap (plot width divided by the widest label plus 10px).
+  It therefore responds to either `layout` mode without DOM text measurement or browser-specific
+  font metrics. Unset (the default) renders every label, unchanged. Each rendered category label
+  is allocation-aware: narrow/long text is ellipsized before paint, with the complete caller label
+  retained as its accessible name. Independently, the global 1,000-record safety sampler may bound
+  both marks and labels for very large category×series input.
 - `barX?: (index: number) => number` (attribute: false, bar type only) — overrides the internal
   per-category x-origin formula (`plotX + i * slot`) used by both bars and their axis labels, so a
   consumer can pixel-align this chart's bars with a sibling `<lr-heatmap>` calendar's week columns