@aceshooting/lyra-ui 25.1.0 → 25.3.0

package/dist/internal/package-metadata.d.ts

@@ -2,4 +2,4 @@
 * Generated from package.json by scripts/generate-package-metadata.mjs.
 * Run `pnpm package-metadata` after changing package identity or version.
 */
-export declare const LYRA_PACKAGE_NAME:'@aceshooting/lyra-ui';export declare const LYRA_PACKAGE_VERSION:'25.1.0';
+export declare const LYRA_PACKAGE_NAME:'@aceshooting/lyra-ui';export declare const LYRA_PACKAGE_VERSION:'25.3.0';

package/dist/internal/package-metadata.js

@@ -1 +1 @@
-const LYRA_PACKAGE_NAME="@aceshooting/lyra-ui",LYRA_PACKAGE_VERSION="25.1.0";export{LYRA_PACKAGE_NAME,LYRA_PACKAGE_VERSION};
+const LYRA_PACKAGE_NAME="@aceshooting/lyra-ui",LYRA_PACKAGE_VERSION="25.3.0";export{LYRA_PACKAGE_NAME,LYRA_PACKAGE_VERSION};

package/llms/components/lr-combobox.md

@@ -701,8 +701,10 @@ synchronous and fires no `input`/`change`/`lr-change` event.
 - `aria-required` reflects `required` immediately; `aria-invalid`, by contrast, only reflects
   **after the field has been touched** (first `blur`) — a `required` field with a validity error
   doesn't look invalid to assistive tech before that, by design (avoids flashing invalid styling on
-  first render). Blurring the input (Tab away) now also closes an open listbox, the same as a
-  native `<select>`'s popup, not just a click outside or Escape.
+  first render). Moving focus outside the combobox trigger (Tab away) closes an open listbox,
+  the same as a native `<select>`'s popup. Moving from the input to its clear button retains the
+  filter until the button activates; clearing returns focus to the input without changing whether
+  the listbox is open.
 - `dotColor`/`sub`/`group` are read from light-DOM `<lr-option>` children as before, but are also
   first-class fields on `ComboboxSourceRow` for the async `source` path — an async lookup can drive
   the same grouped/dot/sub-text rendering a static option list can.

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

@@ -99,7 +99,7 @@ readonly LyraLocaleEntry[]`, `LyraLocaleEntry { tag: string; label?: string; cou
 unset, selection commits synchronously without loading a catalog. Set it to `loadLyraLocale` from
 `@aceshooting/lyra-ui/locale-loader.js` to import the selected built-in catalog before committing.
 The loader accepts exact shipped canonical tags (equivalent casing/underscores normalize), shares
-concurrent requests, and permits retry after a failed import. `en` needs no import; an unshipped
+concurrent requests, and clears its promise cache after rejection. `en` needs no import; an unshipped
 regional tag rejects instead of claiming a translation. Importing the helper does not load a catalog
 or select the page locale. Supply an explicit `locales` list to offer catalogs before registration.
 
@@ -114,7 +114,11 @@ picker.localeLoader = loadLyraLocale;
 The unset callback preserves synchronous selection. A vetoed request never invokes the loader.
 While loading, the previous value stays committed and the trigger exposes `aria-busy`; a visible
 localized status and light-DOM announcement explain progress. Failure retains the value and offers
-Retry through a fresh request. An open listbox places above or below the full control and its
+Retry through a fresh callback invocation. Browsers may cache failed native module fetches, so
+Retry does not guarantee another network request. Retain the current locale and failure guidance;
+if a native import remains failed after connectivity returns, offer a user-initiated page reload
+after preserving unsaved work, or use an application-owned recoverable `localeLoader` transport.
+The picker never reloads automatically. An open listbox places above or below the full control and its
 failure guidance, including when `top-layer` is enabled, so it cannot cover Retry. Dismissing and
 reopening the listbox retains the failure guidance and the reachable retry action.
 New selection, host value/catalog/loader writes, reset, disablement,
@@ -218,6 +222,12 @@ A compact header can set `trigger-display="flag"` and
 Import `@aceshooting/lyra-ui/components/media/flag/flag-peer.js` to register the optional flag
 resolver. Menu labels stay visible; a per-entry `country` override also reaches the compact trigger.
 
+Option rows keep at least the medium control height (`--lr-form-control-height-m`, normally
+`2.25rem`), including `option-display="label"` and a small flag trigger. Larger control tiers,
+coarse-pointer control heights, larger text, and the optional tag line can grow the rows beyond
+that floor. The listbox keeps its scrolling height limit; `size` does not make language rows
+smaller than the medium floor.
+
 ```html
 <lr-locale-picker label="Language"></lr-locale-picker>
 <script type="module">

package/llms/components/lr-map.md

@@ -228,6 +228,9 @@ heatmap?: LyraMapHeatmapOptions; cluster?: LyraMapClusterOptions }`. `sourceId`
   fill is that faint. Deriving one from the other measured 1.41:1 against a light basemap — under
   WCAG 1.4.11's 3:1 floor for graphical objects. A `var(--lr-…)` reference is resolved against the
   host before it reaches MapLibre, which paints to a WebGL canvas and never sees the CSS cascade.
+  Data-layer, choropleth, cluster, and heatmap paint colors also accept modern CSS color functions
+  such as `color()`, `oklch()`, and `color-mix()`; Lyra resolves them to MapLibre-compatible sRGB
+  on application and theme repaint. An invalid explicit color falls back to the layer tone.
   The component
   assigns collision-free private MapLibre ids for those resources: `sourceId` is the stable
   declarative reconciliation key, **not** an id to retrieve from `map`. This prevents a data layer
@@ -248,7 +251,8 @@ heatmap?: LyraMapHeatmapOptions; cluster?: LyraMapClusterOptions }`. `sourceId`
   down to the layer ids and the point layer's filter.**
 
   `cluster?: LyraMapClusterOptions { radius?: number; maxZoom?: number; radiusSteps?: [number,
-number][]; colorSteps?: [number, string][]; countFont?: string[] }` turns the entry's source into a
+number][]; colorSteps?: [number, string][]; strokeColor?: string; countFont?: string[]; countColor?: string;
+countHaloColor?: string; countHaloWidth?: number }` turns the entry's source into a
   natively clustered one — `cluster`/`clusterRadius` (default 50)/`clusterMaxZoom` (default 14) on
   the source, plus a `${sourceId}-cluster` circle filtered on `has('point_count')`, a
   `${sourceId}-cluster-count` label, and a `${sourceId}-circle` layer for the points that stayed
@@ -261,10 +265,20 @@ number][]; colorSteps?: [number, string][]; countFont?: string[] }` turns the en
   resolution, where a `var(--lr-…)` reference in a `colorSteps` entry is resolved against the host
   before it reaches MapLibre (which paints to a WebGL canvas and never sees the CSS cascade), so a
   retheme moves the cluster breaks with everything else. No fill or line layer is created for a
-  clustered entry, because MapLibre's clustering keeps point features only. The count
-  label needs glyphs: a style that declares none gets the graduated circles without the numbers
+  clustered entry, because MapLibre's clustering keeps point features only. The cluster's optional
+  `strokeColor` overrides only the aggregate circle outline; omitted, invalid,
+  or removed values use the entry's `strokeColor`, then `color`, then `tone`. Individual points keep
+  the entry's own paint. The override accepts CSS colors and live host token references and updates
+  without rebuilding a retained clustered source. The count label needs glyphs: a style that
+  declares none gets the graduated circles without the numbers
   (adding a text layer against a glyph-less style paints nothing and only emits peer errors), and
   `countFont` names the font stack when your style's glyph source lacks MapLibre's spec default.
+  `countColor` overrides the on-tone label foreground, which is useful when `colorSteps` mixes light
+  and dark circles. `countHaloColor` adds an outline for contrast; `countHaloWidth` defaults to 1
+  CSS pixel with a halo color and is bounded to 0–3 (one quarter of the 12px label size). An
+  explicit width of 0 disables the outline. Both count colors accept CSS colors or `var(--lr-…)`
+  references resolved against the host on theme repaint. Omitting or removing these options
+  restores the previous on-tone label and halo-free default.
   Cluster options are baked into the source at creation time by MapLibre and have no setter, so
   changing them (or `kind`) rebuilds that one entry's source and layers; every other update still
   reconciles in place.

package/llms/components/lr-popover.md

@@ -127,6 +127,16 @@ If the import fails, leave the native disclosure visible and usable.
 - `anchor: Element | null = null` (property only) — positioning-only direct anchor, taking priority
   over `for` and the interaction owner but never receiving click listeners or generated ARIA; a
   `showAt()` virtual anchor still wins
+- `interactionBoundary: Element | null = null` (property only) — additional light-dismiss
+  containment for DOM anchoring. Pointer presses within this connected element and its composed
+  descendants keep the popup open, so a collection's own activation handler can change `.anchor`
+  without a hide/show cycle. Automatic DOM anchor tracking remains active. The boundary must belong
+  to the popover's document; detached or foreign-document elements are ignored. It supplies no
+  positioning, activation, generated ARIA, or focus return. Changes apply live, and configuration
+  persists across close and reconnect. Containment uses the event's composed path; when the
+  collection lives inside a closed shadow tree, supply its exposed host. Unset, existing dismissal
+  behavior is unchanged. Virtual `showAt()` anchors use only their independent per-call
+  `options.interactionBoundary`.
 - `withoutArrow: boolean = false` (attribute `without-arrow`, reflected) — suppresses the arrow
   that otherwise points at the anchor.
 - `arrowPlacement: 'anchor'|'start'|'end'|'center' = 'anchor'` (attribute `arrow-placement`) —

package/llms/components/lr-table.md

@@ -297,7 +297,8 @@ cell: (row) => unknown }` — `cell` is required for every `editTrigger` except
 - `groupLabel?: (key: string | number, rows: readonly T[]) => unknown` (attribute: false) — custom group
   header content; without it, the group key is rendered as text
 - `expandedContent?: (row: T) => unknown` (attribute: false) — enables a leading expand toggle and
-  renders a full-width detail row beneath expanded records. The returned content renders inside
+  renders a full-width detail row beneath expanded records. The visually empty toggle-column
+  header has the localized accessible name `details` (overridable through `.strings`). The returned content renders inside
   the component's shadow root, behind the `expanded-cell` part — page CSS cannot reach it, and
   `::part(expanded-cell)` only reaches the wrapping `<td>` itself, not the descendants this
   callback returns (the same `::part()` limitation a column's `cell(row)` anchors run into, see

package/llms/shared/imports-and-registration.md

@@ -274,7 +274,9 @@ registers nothing.
 - Optional-peer tags are skipped by default. `optionalPeers: ['dompurify', 'postal-mime']` enables
   a tag only when the allowlist contains **all** packages recorded for it; `optionalPeers: 'all'`
   is for an installation that deliberately provides the entire peer set. A failed import clears
-  its marker and in-flight cache, so a later scan or insertion can retry it.
+  its marker and in-flight cache, so a later scan or insertion can invoke the loader again.
+  Browser caching of failed native module fetches can still prevent a new network request;
+  clearing the loader cache does not clear the browser's module map.
 
 ```ts
 import { start, stop } from "@aceshooting/lyra-ui/autoloader.js";

package/llms/shared/localization-and-rtl.md

@@ -95,12 +95,17 @@ ships with Lyra. A delta's own registered-key list reports only its own authored
 
 **Optional lazy loading.** `loadLyraLocale(tag)` from `@aceshooting/lyra-ui/locale-loader.js`
 loads one complete built-in catalog without selecting the page locale. Tags that canonicalize to
-the same shipped catalog identity share one in-flight/completed import; failure permits retry. `en`
+the same shipped catalog identity share one in-flight/completed import. Rejection clears the
+helper's promise cache, but browsers may retain failed module fetches: another call need not make
+a new network request. `en`
 resolves without an import. A tag with no exact shipped identity, such as an unshipped regional
 variant, rejects instead of quietly loading another language. The optional loader is outside the
 default component and localization graphs. Assign it to `lr-locale-picker.localeLoader` with an
 explicit offered locale list to use the picker's loading, failure/retry and stale-selection
-protection; see the forms guide.
+protection; see the forms guide. Keep the current locale and failure guidance when loading fails.
+If a native import remains failed after connectivity returns, a user-initiated reload can recover;
+preserve unsaved work first. A custom `localeLoader` can use an application-owned recoverable
+transport. The helper neither reloads the page nor changes module URLs to bypass browser caching.
 
 **Lookup order for a tag.** Every message resolves through one chain, and `Intl.PluralRules`
 category selection walks the same chain, so the two can never disagree:

package/llms/shared/styles-and-tokens.md

@@ -829,10 +829,13 @@ The token grammar rejects CSS-wide keywords, control characters, unsafe punctuat
 
 **Saved styles and the no-flash bootstrap.** getLyraStyle() re-reads storage on each call, so a value written by another tab is visible. If storage is unavailable, the runtime reports its last applied style and continues applying changes without persistence. lyraThemeBootstrap is a self-contained IIFE string for a script in head before stylesheets; it restores the saved style before first paint. createLyraThemeBootstrap({ storageKey }) produces the same string for an application-owned key. Both runtime and bootstrap safely read v1 records using mode: "auto", surface, and tokens, translating them to the current style axes. Keep this reader when migrating old saved preferences; new writes use the current style record.
 
-The bootstrap string can be inlined with the application's CSP nonce or hash:
+Inline the bootstrap after an early UTF-8 declaration and before stylesheets, with the application's
+CSP nonce or hash. Keep the complete charset declaration within the HTML document's first 1024
+bytes; build plugins must not prepend the bootstrap ahead of it.
 
 ~~~html
 <head>
+  <meta charset="utf-8" />
   <script>
     /* server-inlines lyraThemeBootstrap here */
   </script>
@@ -840,7 +843,7 @@ The bootstrap string can be inlined with the application's CSP nonce or hash:
 </head>
 ~~~
 
-For a strict CSP that disallows inline scripts, the package also publishes theme-bootstrap.js, a classic script asset with identical bytes. Load it synchronously before stylesheets. Its optional data-lr-theme-storage-key and data-lr-theme-attributes attributes select an application-owned storage key or mode-attribute list; values are validated and fall back to defaults when invalid.
+For a strict CSP that disallows inline scripts, the package also publishes theme-bootstrap.js, a classic script asset with identical bytes. Load it synchronously after the charset declaration and before stylesheets. Its optional data-lr-theme-storage-key and data-lr-theme-attributes attributes select an application-owned storage key or mode-attribute list; values are validated and fall back to defaults when invalid.
 
 **Migrating the retired theme facade.** New code uses setLyraStyle() and getLyraStyle(). Map old auto mode to system, an old surface reference color to accentBackground, and an old token map to overrides; review custom CSS colors that share a gemstone name before choosing a named accent. Replace preset definitions with a LyraLook plus explicit style choices. Replace selectors for data-lr-theme-preset with the actual axis they need, such as data-lr-look="shadcn". Import looks/shadcn.css in place of the removed fixed themes/shadcn.css facade and select the look with setLyraStyle({ look: "shadcn" }) or a scoped data-lr-look attribute. Listen for lr-style-change and read event.detail.style and event.detail.changed; the old theme and preset events are no longer emitted. For the complete project-by-project sequence, see [Upgrading from v23 to v24](v23-to-v24-migration.md).
 

package/llms/shared.md

@@ -273,7 +273,9 @@ registers nothing.
 - Optional-peer tags are skipped by default. `optionalPeers: ['dompurify', 'postal-mime']` enables
   a tag only when the allowlist contains **all** packages recorded for it; `optionalPeers: 'all'`
   is for an installation that deliberately provides the entire peer set. A failed import clears
-  its marker and in-flight cache, so a later scan or insertion can retry it.
+  its marker and in-flight cache, so a later scan or insertion can invoke the loader again.
+  Browser caching of failed native module fetches can still prevent a new network request;
+  clearing the loader cache does not clear the browser's module map.
 
 ```ts
 import { start, stop } from "@aceshooting/lyra-ui/autoloader.js";
@@ -1637,10 +1639,13 @@ The token grammar rejects CSS-wide keywords, control characters, unsafe punctuat
 
 **Saved styles and the no-flash bootstrap.** getLyraStyle() re-reads storage on each call, so a value written by another tab is visible. If storage is unavailable, the runtime reports its last applied style and continues applying changes without persistence. lyraThemeBootstrap is a self-contained IIFE string for a script in head before stylesheets; it restores the saved style before first paint. createLyraThemeBootstrap({ storageKey }) produces the same string for an application-owned key. Both runtime and bootstrap safely read v1 records using mode: "auto", surface, and tokens, translating them to the current style axes. Keep this reader when migrating old saved preferences; new writes use the current style record.
 
-The bootstrap string can be inlined with the application's CSP nonce or hash:
+Inline the bootstrap after an early UTF-8 declaration and before stylesheets, with the application's
+CSP nonce or hash. Keep the complete charset declaration within the HTML document's first 1024
+bytes; build plugins must not prepend the bootstrap ahead of it.
 
 ~~~html
 <head>
+  <meta charset="utf-8" />
   <script>
     /* server-inlines lyraThemeBootstrap here */
   </script>
@@ -1648,7 +1653,7 @@ The bootstrap string can be inlined with the application's CSP nonce or hash:
 </head>
 ~~~
 
-For a strict CSP that disallows inline scripts, the package also publishes theme-bootstrap.js, a classic script asset with identical bytes. Load it synchronously before stylesheets. Its optional data-lr-theme-storage-key and data-lr-theme-attributes attributes select an application-owned storage key or mode-attribute list; values are validated and fall back to defaults when invalid.
+For a strict CSP that disallows inline scripts, the package also publishes theme-bootstrap.js, a classic script asset with identical bytes. Load it synchronously after the charset declaration and before stylesheets. Its optional data-lr-theme-storage-key and data-lr-theme-attributes attributes select an application-owned storage key or mode-attribute list; values are validated and fall back to defaults when invalid.
 
 **Migrating the retired theme facade.** New code uses setLyraStyle() and getLyraStyle(). Map old auto mode to system, an old surface reference color to accentBackground, and an old token map to overrides; review custom CSS colors that share a gemstone name before choosing a named accent. Replace preset definitions with a LyraLook plus explicit style choices. Replace selectors for data-lr-theme-preset with the actual axis they need, such as data-lr-look="shadcn". Import looks/shadcn.css in place of the removed fixed themes/shadcn.css facade and select the look with setLyraStyle({ look: "shadcn" }) or a scoped data-lr-look attribute. Listen for lr-style-change and read event.detail.style and event.detail.changed; the old theme and preset events are no longer emitted. For the complete project-by-project sequence, see [Upgrading from v23 to v24](v23-to-v24-migration.md).
 
@@ -2146,12 +2151,17 @@ ships with Lyra. A delta's own registered-key list reports only its own authored
 
 **Optional lazy loading.** `loadLyraLocale(tag)` from `@aceshooting/lyra-ui/locale-loader.js`
 loads one complete built-in catalog without selecting the page locale. Tags that canonicalize to
-the same shipped catalog identity share one in-flight/completed import; failure permits retry. `en`
+the same shipped catalog identity share one in-flight/completed import. Rejection clears the
+helper's promise cache, but browsers may retain failed module fetches: another call need not make
+a new network request. `en`
 resolves without an import. A tag with no exact shipped identity, such as an unshipped regional
 variant, rejects instead of quietly loading another language. The optional loader is outside the
 default component and localization graphs. Assign it to `lr-locale-picker.localeLoader` with an
 explicit offered locale list to use the picker's loading, failure/retry and stale-selection
-protection; see the forms guide.
+protection; see the forms guide. Keep the current locale and failure guidance when loading fails.
+If a native import remains failed after connectivity returns, a user-initiated reload can recover;
+preserve unsaved work first. A custom `localeLoader` can use an application-owned recoverable
+transport. The helper neither reloads the page nor changes module URLs to bypass browser caching.
 
 **Lookup order for a tag.** Every message resolves through one chain, and `Intl.PluralRules`
 category selection walks the same chain, so the two can never disagree:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aceshooting/lyra-ui",
-  "version": "25.1.0",
+  "version": "25.3.0",
   "description": "Free, independent Lit web components: an open-source alternative to Shoelace and Web Awesome with accessible forms, dashboards, charts, and agent UI.",
   "keywords": [
     "web-components",