@aceshooting/lyra-ui 9.1.1 → 11.0.0

package/llms/components/lr-flag.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** `@aceshooting/lyra-flags` — see `llms/peers.md`
-- **Themeable via** 2 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 3 parts, 3 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`
 
 ---
@@ -20,7 +20,16 @@ Country/language flag image. Flag artwork ships in a **separate, optional peer p
 
 **Properties:**
 
-- `country?: string` (ISO 3166-1 alpha-2, e.g. `"fr"` — takes precedence over `language`)
+- `country?: string` (ISO 3166-1 **alpha-2 or alpha-3**, e.g. `"fr"` or `"FRA"` — takes
+  precedence over `language`). Length alone disambiguates the two code spaces, so no format hint
+  is needed: a 2-letter value is alpha-2, a 3-letter value is alpha-3. Alpha-3 support exists
+  because public statistical sources (World Bank, UN, IMF, most open-data portals) key country
+  records on alpha-3; the 249 officially-assigned mappings are packed as a ~1.2 KB fixed-width
+  string and expanded lazily on the first alpha-3 lookup, so an alpha-2-only app never pays for
+  them. Withdrawn and user-assigned codes deliberately do not map to a successor state — they
+  take the unresolved path below
+- `fallback?: string` — placeholder image URL rendered when the code cannot resolve to a current
+  flag. The `fallback` slot wins over it
 - `language?: string` (BCP-47-ish tag, e.g. `"en"`/`"en-US"`, resolved to a representative country
   via `languageToCountry()`)
 - `src?: string` (a pre-resolved flag image URL — takes precedence over `country`/`language` and
@@ -45,11 +54,17 @@ authoring types are `LyraFlagShape`, `LyraFlagFidelity`, and `LyraFlagUrlResolve
 
 **Events:** none.
 
-**Slots:** none.
+**Slots:** `fallback` — rendered in place of the flag when `country`/`language` cannot resolve to a
+current flag (an unassigned, historical, or malformed code). Wins over the `fallback` property.
 
-**CSS parts:** `image` (the underlying `<img>`, exposed once native loading succeeds), `error`
+**CSS parts:** `image` (the underlying `<img>`, exposed once native loading succeeds),
+`fallback-image` (the `fallback` property's placeholder, when no slot content is supplied), `error`
 (contained localized visible text rendered when URL validation, peer resolution, or native image
-loading fails). The host reflects the terminal error state with `data-error`.
+loading fails). The host reflects the terminal error state with `data-error`, and an unresolvable
+code with `data-unresolved`. **The two are deliberately distinct:** a dissolved federation or
+unrecognized territory in a longitudinal dataset is *data*, not a defect, so it renders the neutral
+fallback (occupying its normal footprint in a table or card grid) rather than localized error
+wording that reads to a user as a bug. Style the two states apart with those attributes.
 
 **Themeable custom properties:** `--lr-flag-radius` (default `calc(var(--lr-radius) * 0.33)` —
 rectangular corner radius), `--lr-flag-aspect-ratio` (default `4 / 3`), and
@@ -59,8 +74,10 @@ rectangular corner radius), `--lr-flag-aspect-ratio` (default `4 / 3`), and
 image when `country` or `language` is used. Import
 `@aceshooting/lyra-ui/components/media/flag/flag-peer.js` once to opt into
 that resolver; a pre-resolved `src` works without the peer registration entry. If the peer is not
-installed, the component fails closed with localized visible `[part="error"]` text and a shared
-light-DOM assertive announcement (see gotchas).
+installed — or if `flag-peer.js` was simply never imported, which looks identical from the page —
+the component fails closed with localized visible `[part="error"]` text, a shared light-DOM
+assertive announcement, and a one-time `console.warn` naming the unresolved code and this import
+(see gotchas).
 
 Also exported from the package root:
 `languageToCountry(language: string): string | undefined` and the `LANGUAGE_TO_COUNTRY` lookup
@@ -146,7 +163,12 @@ import "@aceshooting/lyra-ui/components/media/flag/flag-peer.js";
   `[data-lr-live-region="assertive"]` sink, so the shadow chrome itself is not live and identical
   retries remain separate additions. The failure also produces a one-time `console.warn`
   once the resolver rejects (lazy `import()`, cached module-wide so the warning fires only once per
-  page even with many `<lr-flag>` instances). An _empty_ template is a different, non-error outcome:
+  page even with many `<lr-flag>` instances). A **separate** one-time `console.warn` covers the
+  commonest setup mistake — `country`/`language` set while no resolver was ever registered, i.e.
+  `flag-peer.js` was not imported. It names the offending code and that import path, because the
+  visible `[part="error"]` state alone is indistinguishable from missing flag data. It is armed
+  once per resolver-registration generation, so a table of many flags warns once.
+  An _empty_ template is a different, non-error outcome:
   the peer resolved fine but returned no URL for that code (e.g. `country="zz"`) — no `[part="error"]`,
   no `<img>`, no warning.
 - Rendering is async even when the peer _is_ installed: `src` resolves after an `import()` +

package/llms/components/lr-heatmap.md

@@ -69,6 +69,35 @@ weekdayLabelText?: (jsWeekday:number)=>string|undefined; monthLabelText?:
   measured `clientWidth` on every draw/resize instead of the fixed `cell-size`, so the grid actually
   fills the available width; now applies to calendar mode as well as matrix mode — see gotchas for
   the default, non-`fit-to-width` behavior)
+- `rowLabelWidth?: number | 'auto'` (attribute `row-label-width`, reflected) — width, in CSS px, of
+  the **matrix** row-label gutter, or `'auto'` to measure the widest label and size the gutter to
+  fit (never below the built-in `60`, never above 40% of the host width, so one long label cannot
+  squeeze out the cells it describes). Unset keeps the built-in `60`, so no existing chart reflows.
+  Independently of this, a label too wide for the resolved gutter is truncated with an ellipsis
+  rather than clipped mid-glyph — clipping read as a rendering fault, truncation reads as "there is
+  more here". `cellText` still carries the full label to the tooltip and the keyboard announcement.
+  A malformed value is ignored rather than collapsing the gutter. Calendar mode is unaffected; it
+  has its own fixed weekday gutter
+- `colLabelHeight?: number | 'auto'` (attribute `col-label-height`, not reflected, `'auto'` new in
+  10.1.0) — height, in CSS px, of the matrix column-label band, or `'auto'` to measure the labels
+  and size the band to fit them. Under a non-zero `colLabelRotation` the measurement projects each
+  label's width through the rotation, which is what makes a rotated axis usable without hand-tuning
+  a magic number. Never below the built-in `20`, and bounded above by a sanity ceiling so a
+  pathological label cannot produce an absurd canvas. Note this deliberately does **not** use
+  `rowLabelWidth`'s "40% of the host" rule: the row gutter steals width from the cells and so must
+  be bounded relative to them, whereas the canvas simply grows taller for this band and the cells
+  keep their size. Unset keeps the built-in `20`, so no existing chart reflows. A malformed value is
+  ignored
+- `colLabelRotation?: number` (attribute `col-label-rotation`, new in 10.1.0) — rotation, in
+  degrees, applied to matrix column labels. Unset or `0` paints them horizontally exactly as before.
+  In a dense matrix the per-column width is far narrower than a typical label, so horizontal labels
+  collide with their neighbours; `45` or `90` is the standard remedy. Each label rotates about an
+  anchor at its own column's centre with the label's *end* at that anchor, so it leans back over the
+  columns to its left and the last column's label cannot overflow the canvas. Values outside
+  `[0, 90]` clamp into that range and non-finite values normalize to `0`. Pair with
+  `colLabelHeight="auto"` to have the band size itself to the rotated extent. **Not mirrored under
+  `dir="rtl"`** — both grid modes deliberately retain physical LTR geometry, so leaning one axis'
+  labels the other way would be incoherent
 - `maxCellSize?: number` (attribute `max-cell-size`) — ceiling, in CSS px, on the cell size
   `fitToWidth` derives from the host width, in **both** modes. Exists because `fitToWidth` divides
   the _whole_ host width across the grid, so a 5-week calendar or a 3-column matrix in a wide pane
@@ -86,6 +115,23 @@ weekdayLabelText?: (jsWeekday:number)=>string|undefined; monthLabelText?:
   color ramp via `sqrtStep()` instead of mapping linearly; in calendar mode, the default `'linear'`
   still buckets by quartile (`quartileBucket()`, unchanged), while `'sqrt'` instead compresses via the
   same `sqrtStep()` magnitude compression as matrix mode, so one heavy day doesn't wash out the rest
+- `domain?: [number, number]` (attribute: false) — pins the color ramp's input domain instead of
+  deriving it from the data's own extremes, so two heatmaps of comparable data can share a scale
+  rather than each normalizing to its own min/max. A reversed pair is normalized; a degenerate or
+  non-finite one falls back to the derived range
+- `midpoint?: number` — anchors a diverging ramp's neutral color on this value rather than at the
+  middle of the domain, scaling the two halves independently (`lo`→0, `midpoint`→0.5, `hi`→1). A
+  midpoint outside the resolved domain degrades to plain normalization rather than distorting the
+  ramp
+- **Signed data.** Setting either `domain` or `midpoint` opts the component into signed data, where
+  only a **non-finite** value is no-data. With neither set (the default), a negative value is
+  no-data — matching the long-documented `-1` sentinel, since a matrix of counts has no meaningful
+  negative. Declaring a domain or midpoint is what disambiguates "a real negative" from "the
+  sentinel", so signed datasets render their negative half instead of dropping it. In signed mode a
+  structurally absent matrix cell reads as `NaN` so it stays no-data while a real `-1` beside it
+  renders on the ramp; in default mode an absent cell still resolves to `-1`, keeping `valueAt()`
+  and the `lr-cell-click` payload unchanged. `scale="sqrt"` rejects negatives in both modes — a
+  square root of a negative has no meaning
 - `bucketCount: number = 5` (attribute `bucket-count` — calendar mode only; non-finite values fall
   back to 5, while finite values are floored and clamped to 2–256 before the color-ramp allocation)
 - `annotations: readonly HeatmapAnnotation[] = []` (attribute: false) — `HeatmapAnnotation { row?: number;

package/llms/components/lr-histogram.md

@@ -7,8 +7,8 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 16 parts, 35 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`
 
 ---
@@ -25,6 +25,8 @@ Bins `values` into `bins` equal-width buckets and renders as a bar chart (extend
 - `seriesLabel: string = ''` (attribute `series-label`) — dataset label used for the
   legend/tooltip/table; empty falls back to localized "Frequency". Inherited `label` keeps its
   chart-wide accessible-name meaning.
+- inherits `lr-chart`'s full surface, including `scaleType` (`scale-type`) and `annotations` —
+  a logarithmic frequency axis and threshold/band markers both apply to a histogram
 - `labels`/`datasets`/`type` are **derived, read-only** (installed as getter/setter pairs on the
   prototype; direct writes are silently ignored) — `labels`/`datasets` are computed from
   `values`/`bins` (memoized per instance, keyed by reference equality on `values` plus the
@@ -50,7 +52,7 @@ maxSamples?)` appends finite raw samples and optionally retains only the newest
 **Slots:** default JSON configuration script, `data-table`, `center`.
 
 **CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
-`reset-zoom-button`, `description`, `notices`, `data-table`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
+`reset-zoom-button`, `description`, `notices`, `data-table`, `data-table-toggle`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
 rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load; the
 failure transition is announced through the shared document-level light-DOM assertive sink —
 inherited from `LyraChart`, unaffected by the binning logic).
@@ -59,7 +61,8 @@ inherited from `LyraChart`, unaffected by the binning logic).
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
 `--lr-chart-tooltip-text`, `--lr-chart-legend-item-hover-bg`,
 `--lr-chart-legend-item-active-bg`, `--lr-chart-data-table-button-hover-bg`,
-`--lr-chart-data-table-button-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
+`--lr-chart-data-table-button-active-bg`, `--lr-chart-data-table-toggle-hover-bg`,
+`--lr-chart-data-table-toggle-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
 `--lr-chart-reset-zoom-button-active-bg`, `--lr-chart-canvas-hover-outline-width`, and
 `--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — inherited from `LyraChart`, identical in meaning, together with the
 mirrored `--border-color-1`,

package/llms/components/lr-icon.md

@@ -6,7 +6,7 @@
 - **Class** `LyraIcon`, also available unregistered from `@aceshooting/lyra-ui/components/utility/icon/icon.class.js`
 - **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`
-- **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.
+- **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.
 - **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`

package/llms/components/lr-json-schema-viewer.md

@@ -21,7 +21,8 @@ It intentionally does not fetch remote references or validate values.
 
 **Properties:** clone-owned, bounded, frozen `schema: JsonSchemaNode | null = null` and
 `issues: readonly SchemaValidationIssue[] = []` (attribute: false); reassign a new schema record or
-issue array after changes. `selectedPath: string = ''` (attribute `selected-path`);
+issue array after changes. `selectedPath: string | null = null` (attribute `selected-path`) —
+`null` means no selection, while the empty string is the valid JSON Pointer for the schema root;
 `maxDepth: number = 20` (attribute `max-depth`, clamped to 100); `label: string = ''`.
 
 **Exported types:** `JsonSchemaNode` covers `$ref`, type/title/description, properties/items,

package/llms/components/lr-knowledge-graph-explorer.md

@@ -79,9 +79,14 @@ same self-toggle-then-emit contract `lr-graph-legend` uses, so every feature wor
 - `lr-hidden-types-change` (`detail: { hiddenTypes: string[] }`) — a node type's visibility changed
   via the composed legend. Follows the same self-toggle-then-emit contract as `lr-pin-change`/
   `lr-search-change`, so reassigning back is optional.
-- `lr-search-change` (`detail: { searchQuery: string }`) — the user typed in the toolbar's search
-  box. Already self-applied before emitting, so reassigning back is optional; a direct host
-  assignment to `searchQuery` stays silent.
+- `lr-search-change` (`detail: { query: string; matchCount: number; matchCountExact: boolean }`) —
+  the user typed in the toolbar's search box. `query` is the canonical `LyraSearchChangeDetail`
+  field name. `matchCount` is the same live node-filter total the result list and its live-region
+  announcement already compute (`0` while the query is empty). `matchCountExact` is always `true` —
+  this component's node filter has no truncating ceiling, unlike a paginated text-search viewer.
+  There is no `activeIndex`: this is a live node filter, not a cursor-based search. The component
+  has already applied the query to its own `searchQuery` property before emitting, so reassigning
+  it back is optional and a direct host assignment stays silent.
 - Bubbling straight through from composed children, unmodified: `lr-node-click`
   (`detail: { nodeId, x, y }`), `lr-link-click` (`detail: { sourceNodeId, targetNodeId, linkId? }`), `lr-community-click`
   (`detail: { communityId }`), `lr-node-expand` (`detail: { nodeId }`, from `lr-graph` and/or `lr-neighbor-list`),

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

@@ -6,7 +6,7 @@
 - **Class** `LyraKnownDate`, also available unregistered from `@aceshooting/lyra-ui/components/utility/known-date/known-date.class.js`
 - **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`
-- **Deprecated part** `label` since `8.0.0`; use part `::part(form-control-label)`; removal not before `10.0.0` — The form-control-label part matches the shared form-control vocabulary; label remains on that same node during the compatibility window.
+- **Deprecated part** `label` since `8.0.0`; use part `::part(form-control-label)`; removal not before `10.0.0` — The form-control-label part matches the shared form-control vocabulary; label remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-known-date` still publishes its own deprecated `label` part, so this alias is removed only when upstream's is.
 - **Optional peers** none
 - **Themeable via** 17 parts, 13 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`
@@ -119,7 +119,9 @@ assigned nodes update the announcement without requiring the wrapper component t
 
 The `label` part alias was deprecated in 8.0.0 in favor of the shared form vocabulary
 `form-control-label`. Both names remain on the same node during the compatibility window; use
-`::part(form-control-label)` in new CSS. The alias will not be removed before 10.0.0.
+`::part(form-control-label)` in new CSS. Removal is not scheduled: Web Awesome still publishes its
+own deprecated `label` part on `<wa-known-date>`, and a mirrored tag owes its whole upstream
+surface, so the alias goes only when upstream's does.
 
 **The required marker.** The `*` the legend grows while `required` is the library's shared
 required-field marker, and it takes the same three consumer-settable properties every other

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

@@ -7,8 +7,8 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 16 parts, 35 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -25,7 +25,8 @@ and behavior there. **See `llms/components/lr-chart.md` for the details, code ex
 of every entry in these lists.**
 
 **Properties:** `description`, `grid`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `max`, `min`, `plugins`, `stacked`, `withoutAnimation` (`without-animation`),
+(`legend-position`), `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
+`stacked`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
@@ -43,7 +44,7 @@ complete `hiddenDatasets` snapshot).
 **Slots:** default JSON configuration script, `data-table`, `center`.
 
 **CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-item-hidden`, `legend-swatch`,
-`reset-zoom-button`, `description`, `notices`, `data-table`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
+`reset-zoom-button`, `description`, `notices`, `data-table`, `data-table-toggle`, `data-truncation`, `feature-warning`, `center`, `error` (neutral visible message
 rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load; the
 failure transition is announced through the shared document-level light-DOM assertive sink — see
 `llms/components/lr-chart.md`).
@@ -52,7 +53,8 @@ failure transition is announced through the shared document-level light-DOM asse
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
 `--lr-chart-tooltip-text`, `--lr-chart-legend-item-hover-bg`,
 `--lr-chart-legend-item-active-bg`, `--lr-chart-data-table-button-hover-bg`,
-`--lr-chart-data-table-button-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
+`--lr-chart-data-table-button-active-bg`, `--lr-chart-data-table-toggle-hover-bg`,
+`--lr-chart-data-table-toggle-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
 `--lr-chart-reset-zoom-button-active-bg`, `--lr-chart-canvas-hover-outline-width`, and
 `--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — all inherited from `LyraChart`, identical in meaning and default (see
 `lr-chart` above); each of the eight variants below reads the same set, so one rule retunes them
@@ -66,7 +68,7 @@ together. The mirrored hooks are `--border-color-1`,
 `zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
-<lr-bar-chart legend></lr-bar-chart>
+<lr-bar-chart></lr-bar-chart>
 <lr-pie-chart></lr-pie-chart>
 <script>
   document.querySelector('lr-bar-chart').labels = ['A', 'B'];

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

@@ -7,7 +7,7 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 17 parts, 16 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`
 
@@ -103,11 +103,21 @@ passthrough). Not a subclass of `LyraChart`.
 - `valueAxisGutter?: number` (attribute `value-axis-gutter`) — value-axis gutter width.
 - `barGapRatio?: number` (attribute `bar-gap-ratio`) — overrides the internal 0.2 `BAR_GROUP_GAP`
   fraction of a category slot left as a gap between categories. Unset keeps the fixed 0.2.
-- `scale: 'linear' | 'sqrt' = 'linear'` (bar type only) — `'sqrt'` maps a bar's value to height via
-  `Math.sqrt(value / domainMax)` instead of the standard linear `niceDomain` fraction (mirroring
-  `lr-heatmap`'s matrix-mode `sqrt` scale), so a skewed dataset's smaller bars aren't washed out
-  by one dominant value; gridlines/tick labels stay on the linear domain either way, and `type="line"`
-  ignores it entirely.
+- `scale: 'linear' | 'sqrt' | 'logarithmic' = 'linear'` — `'sqrt'` (**bar type only**) maps a bar's
+  value to height via `Math.sqrt(value / domainMax)` instead of the standard linear `niceDomain`
+  fraction (mirroring `lr-heatmap`'s matrix-mode `sqrt` scale), so a skewed dataset's smaller bars
+  aren't washed out by one dominant value; under `'sqrt'` gridlines/tick labels stay on the linear
+  domain and `type="line"` ignores it entirely.
+  `'logarithmic'` is the base-10 value axis for data spanning several orders of magnitude, where a
+  linear axis collapses everything below the maximum into the baseline. Unlike `'sqrt'` it applies
+  to **bars, line points and gridlines alike**, since a log axis whose gridlines stayed linear
+  would misrepresent the plot. Its lower bound is the smallest *positive* datum rather than the
+  linear `lo`: `beginAtZero` defaults to true, so `lo` is normally `0`, which has no logarithm —
+  deriving the floor from the data is what makes a 1…1000 series span three even decades instead of
+  collapsing onto one. Values at or below that floor (including zero and negatives, which have no
+  real logarithm) pin to the axis floor rather than producing `-Infinity` geometry, and a degenerate
+  domain falls back to the linear fraction. `lr-chart`'s own `scaleType` is the Chart.js-backed
+  equivalent for the full charts.
 - `withoutValueAxis: boolean = false` (attribute `without-value-axis`) — suppresses gridlines and
   value-axis tick labels; x-axis category labels remain.
 - `selectedIndices: readonly number[] = []` (attribute: false) — applies to every interactive data mark for

package/llms/components/lr-map.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** `maplibre-gl` — see `llms/peers.md`
-- **Themeable via** 12 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 15 parts, 5 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`
 
 ---
@@ -31,6 +31,22 @@ operations. Its runtime value is the underlying MapLibre map.
   style-required failure and makes no tile/style request. Assign a hosted vector/raster style from
   a provider whose terms fit your application, or an explicitly network-silent style for local
   geometry.
+- `legendGradient: readonly (readonly [number, string])[] = []` (attribute: false, type
+  `LyraMapLegendGradientStop[]`) — renders the legend as a **continuous** gradient bar with endpoint
+  captions instead of (or alongside) the discrete `legend` swatches, which is the standard key for a
+  choropleth whose `interpolate` fill is itself a continuous ramp. Takes the same `[value, color]`
+  stop shape as `choropleth.stops`, so the usual assignment is `map.legendGradient =
+  myChoropleth.stops` and the key cannot drift from the layer it describes. Stops are sorted
+  ascending, bounded to 64, and filtered to finite values carrying a CSS-parsable color; fewer than
+  two usable stops render no bar at all, since a one-stop "gradient" is a flat block that describes
+  nothing. Each stop sits at its true proportion of the value range, so the bar shows the ramp the
+  expression actually produces rather than evenly spacing unevenly-spaced values. Part names
+  (`legend-gradient`, `legend-lo`, `legend-hi`) mirror `lr-heatmap`'s gradient legend, and the bar
+  is `aria-hidden`/`inert` with the captions carrying the meaning. Mirrors under RTL
+- `legendGradientLoLabel: string | null = null` (attribute `legend-gradient-lo-label`),
+  `legendGradientHiLabel: string | null = null` (attribute `legend-gradient-hi-label`) — override
+  the endpoint captions, which otherwise default to the lowest/highest stop value in the component's
+  own locale-aware numeric formatting
 - `legend: readonly LyraMapLegendEntry[] = []` (attribute: false) — immutable defensive snapshots
   of `LyraMapLegendEntry { readonly color: string; readonly label: string; readonly pattern:
 LyraMapLegendPattern }`, where `LyraMapLegendPattern` is `'solid' | 'diagonal' | 'dots' |
@@ -42,10 +58,27 @@ omittedCount, truncatedLabelCount, truncated }` result for the latest assignment
   projection renders a localized visible `1–N of M items` summary rather than silently claiming
   the bounded rows are complete.
 - `choropleth?: LyraMapChoroplethLayer` (attribute: false) — `LyraMapChoroplethLayer { sourceId:
-string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, string][] }` (interpolated
+string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, string][]; interpolation?:
+'linear' | 'logarithmic' | 'step'; stepBaseColor?: string }` (interpolated
   fill-color expression from `field`'s value against `stops`; `stops` must contain at least one
   `[value, color]` pair — an empty array is ignored, leaving whatever fill layer already exists, if
-  any, untouched, rather than being applied)
+  any, untouched, rather than being applied).
+  `interpolation` (type `LyraMapChoroplethInterpolation`, default `'linear'`) chooses how the colour
+  is interpolated between stops. `'logarithmic'` compresses the ramp, which is what a heavy-tailed
+  quantity — price, population, income — needs: on a linear ramp every value below the maximum falls
+  into the first colour band, so the map reads as one flat colour plus a couple of outliers. It
+  emits maplibre's own `['interpolate', ['exponential', 0.25], …]`, exposing an existing capability
+  rather than adding one (maplibre has no `['log']` interpolation type; a sub-1 exponential base is
+  the documented way to weight a ramp toward the low end). **`stops` stay in the data's own units
+  under either mode**, so the legend keeps reading in real values instead of log units — no
+  pre-transforming to log10 and hand-relabelling the legend back.
+  `'step'` (new in 10.1.0) emits maplibre's `['step', …]` instead of `['interpolate', …]`, giving
+  **discrete bands rather than a continuous ramp**. Use it whenever the legend advertises a fixed
+  set of ranges with one swatch each: a ramp would put colours on the map that appear nowhere in the
+  legend, and would render two regions in the same advertised band as visibly different colours
+  (`legendGradient` covers the opposite case, a gradient legend). `stepBaseColor` is the colour for
+  values below the first threshold, which `['step', …]` requires; it defaults to the first stop's own
+  colour, so a legend whose first band starts at the data minimum needs no extra configuration
 - `markers: LyraMapMarker[] = []` (attribute: false) — `LyraMapMarker { id?: string; lngLat:
 [number, number]; color?: string; label?: string; unsafeHtml?: string }`; an explicit `id` is
   trimmed and must be nonempty, and the first marker for an explicit ID wins. Markers are reconciled
@@ -67,11 +100,21 @@ string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, strin
 - `dataLayers: LyraMapGeoJsonDataLayer[] = []` (attribute: false) —
   `LyraMapGeoJsonDataLayer { sourceId: string; geojson: GeoJSON.Feature |
 GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
-'danger' | 'neutral' }`. `sourceId` is trimmed and must be nonempty; the first layer for a
+'danger' | 'neutral'; color?: string; strokeColor?: string }`. `sourceId` is trimmed and must be nonempty; the first layer for a
   `sourceId` wins and blank or later duplicate records are ignored. Each retained entry adds one
   GeoJSON source plus three geometry-filtered layers
   (fill, line, and circle, so a mixed `FeatureCollection` renders correctly), colored from the
-  matching `--lr-color-*` token (`tone` defaults to `'accent'` → `--lr-color-brand`). The component
+  matching `--lr-color-*` token (`tone` defaults to `'accent'` → `--lr-color-brand`).
+  `color` and `strokeColor` (both new in 10.1.0) override that per surface — `color` paints the
+  polygon fill, `strokeColor` the line and circle layers, falling back to `color` and then to `tone`.
+  They are separable because a fill and its outline want opposite things on a
+  choropleth-plus-overlay map, and the difference is measurable rather than aesthetic: the fill
+  competes for area with the choropleth beside it and has to sit quiet, while the 1px outline
+  competes with nothing and is the only thing keeping a no-data region's shape readable once the
+  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.
+  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
   from overwriting or removing a same-named source supplied by `mapStyle`. Independent of
@@ -80,6 +123,37 @@ GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
   persists across a `dataLayers` reassignment gets its GeoJSON updated in place (`setData()`), one
   that's dropped has its private source/layers removed, and a genuinely new `sourceId` gets new
   resources — nothing leaks on removal, style change, or disconnect.
+- `maxBounds: LyraMapBounds | null = null` (attribute: false) — box the map may not pan outside,
+  `[[west, south], [east, north]]`. Prefer it over calling `map.setMaxBounds()` through the `.map`
+  escape hatch: constraining the camera can wedge maplibre-gl at a sub-1 fractional zoom in a wide
+  container, leaving `getZoom()` returning `null` permanently, every frame throwing from inside the
+  peer's own matrix math, and the canvas never painting again — a blank map, with nothing thrown at
+  the call site to attribute it to. This property applies the same call, then reads the camera back
+  and reverts (restoring zoom and centre) if it did not survive, so the worst case is an
+  unconstrained map plus a dev-mode warning. A malformed box is rejected rather than clamped
+
+**Choropleth and `dataLayers` updates are diffed before they reach the peer.** `setData()`
+unconditionally re-tiles and repaints an entire source, which is invisible on a static map and
+expensive on an animated one. When an update changes only feature *properties* — the values driving
+the colour ramp — the component emits maplibre-gl's incremental `updateData()` instead. The fast
+path is deliberately strict, and needs all of: the same feature count, a `string`/`number` `id` on
+every feature in the same order, and geometry that is the **same object** as last time (not merely
+deep-equal). Structurally comparing polygon rings would cost about what the re-tile costs, and a
+false positive would paint stale geometry. Reuse your geometry objects across frames — the
+efficient way to build an animation anyway — and the fast path applies; otherwise it falls back to
+`setData()` with no change in behaviour. Peers predating `updateData()` always take the old path.
+
+**Feature properties are tiled, and therefore bounded in numeric magnitude.** MapLibre GL tiles
+every GeoJSON source through a worker into a protobuf vector tile, so a property carrying a huge
+integer throws *inside that worker* — "Given varint doesn't fit into 10 bytes". That throw is not
+catchable by your app and not a rejected promise; it reaches you only as an opaque message on
+`lr-map`'s own error handler, while the rest of the layer still paints, so one bad feature in a
+large collection is invisible until someone walks the data by hand. Both `choropleth.geojson` and
+`dataLayers[].geojson` are now pre-scanned (first 10,000 features) and any numeric property beyond
+`Number.MAX_SAFE_INTEGER` draws a dev-mode warning naming the feature and the property. Carry a
+reduced figure in the feature — a log, a bucket, an index — and keep the exact value in your own
+payload beside the map.
+
 - `label: string = ''` — purpose-specific accessible name for MapLibre's actual focusable canvas.
   A nonempty host `aria-label` remains on the host and is not duplicated onto the canvas; the canvas
   uses `label` or the localized map name. An explicitly empty host `aria-label` is preserved as an
@@ -102,13 +176,20 @@ shared `maplibre-gl` import without constructing a map or allocating a WebGL con
 an element.
 
 **Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`), `lr-map-click`
-(frozen `detail: { readonly lngLat: readonly [lng, lat], readonly feature? }`; the tuple and any
-hit GeoJSON feature are detached and recursively frozen — feature is only populated if a
-choropleth fill layer exists and was hit)
+(frozen `detail: { readonly lngLat: readonly [lng, lat], readonly feature?, readonly origin?,
+readonly sourceId? }`; the tuple and any hit GeoJSON feature are detached and recursively frozen).
+`feature` resolves against the choropleth fill layer **and** every applied `dataLayers`
+fill/line/circle layer, topmost first — so a shape painted through `dataLayers` is identifiable
+instead of being indistinguishable from empty space. `origin` is `'choropleth'` or `'data-layer'`,
+and `sourceId` carries the authored `dataLayers[].sourceId` for a data-layer hit; both are
+`undefined` whenever `feature` is
 
-**Slots:** none.
+**Slots:** `legend` — custom legend content, rendered inside the legend panel's own layout so it
+stays positioned with the map instead of floating beside it. Supplying it opens the panel even
+when `legend` and `legendGradient` are both empty.
 
-**CSS parts:** `base`, `container`, `legend`, `legend-swatch`, `legend-limit`, `marker`, `popup`,
+**CSS parts:** `base`, `container`, `legend`, `legend-swatch`, `legend-gradient`, `legend-lo`,
+`legend-hi`, `legend-limit`, `marker`, `popup`,
 `popup-content`, `popup-close-button`, `attribution`, `attribution-toggle`, `error`.
 `legend` is a localized `role="group"` containing a real list associated to the map canvas with
 `aria-describedby`; each entry is a `listitem`, decorative swatches are inert/accessibility-hidden,

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

@@ -36,8 +36,9 @@ support (`highlights`, `activeHighlightId`, `scrollToAnchor()`, the `lr-highligh
 section above for the full write-up of shared behavior.
 
 **Properties:** `content: string = ''`, `tabSize: number = 4` (attribute `tab-size`) — the same
-finite-integer-guarded leading-indentation expansion used by `<lr-markdown>`; values outside 1–32
-or non-finite values fall back to `4`, independently of rendered code's
+finite-integer-guarded leading-indentation expansion used by `<lr-markdown>`; finite values are
+clamped to `[1, 32]` (`0` becomes `1`, `33` becomes `32`), and only non-finite values (`NaN`,
+`Infinity`) fall back to `4`, independently of rendered code's
 `--lr-code-block-tab-size`; `marked: LyraMarkedParser | undefined` (readonly, no attribute) — this
 instance's isolated peer-neutral configurable parser; `htmlMode: 'sanitize' | 'escape' | 'trusted' =
 'sanitize'` (attribute `html-mode`), `gfm: boolean = true`, `linkTarget: string | null = '_blank'` (attribute

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

@@ -30,13 +30,18 @@ final.
 - `mimeType: string = ''` (attribute `mime-type`) — drives auto-detection when `kind` is unset.
 - `filename: string = ''` — shown in the file-chip fallback, used as the download link's suggested
   filename, and folded into the accessible name.
-- `alt: string = ''` — alt text for the image case (and reused as a video label fallback). Falls
-  back to `filename`, then a generic per-kind description.
-- `accessibleLabel: string = ''` (attribute `aria-label`) — a declarative attribute names the host
-  as a whole while its nested button/link keeps a purpose-specific localized action name. A
-  property-only assignment can override the nested action when no host label is present. Image alt
-  text and the native video's own purpose label remain independent; an explicitly empty host still
-  leaves every interactive descendant named.
+- `alt?: string` — alt text for the image case (and reused as a video label fallback). Unset falls
+  back to `filename`, then a generic per-kind description. An explicit `alt=""` survives to the
+  rendered `<img alt="">`, which is the HTML idiom for a decorative image — same contract as
+  `<lr-image-viewer>` and `<lr-document-preview>`. The `<video>` case is deliberately outside that
+  carve-out: an empty `alt` there still falls through to `filename`/the generic description, because
+  an empty accessible name would leave an interactive player unnamed rather than mark it decorative.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — a declarative attribute names
+  the host as a whole while its nested button/link keeps a purpose-specific localized action name. A
+  property-only assignment can override the nested action when no host label is present. An explicit
+  empty string behaves like the unset `null` default — both fall through to the generated
+  purpose-specific name. Image alt text and the native video's own purpose label remain independent;
+  an explicitly empty host still leaves every interactive descendant named.
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"16rem"`); once set,
   overrides the `--lr-media-card-max-height` custom property for this instance only (applied
   inline on `[part="base"]`, so it reliably wins over a `:host{}`-declared default from outside the
@@ -102,12 +107,23 @@ sizing), `--lr-focus-ring-*`, `--lr-transition-fast`.
 **Optional peer deps:** none.
 
 ```html
-<lr-media-card kind="image" src="https://example.com/photo.jpg" alt="Screenshot" filename="photo.jpg"
-  @lr-media-open=${(e) => openLightbox(e.detail.src)}
-></lr-media-card>
-<lr-media-card kind="file" src="https://example.com/report.pdf" filename="report.pdf"
-  @lr-before-media-download=${(e) => shouldUseNativeDownload || e.preventDefault()}
+<lr-media-card
+  id="image-card"
+  kind="image"
+  src="https://example.com/photo.jpg"
+  alt="Screenshot"
+  filename="photo.jpg"
 ></lr-media-card>
+<lr-media-card id="file-card" kind="file" src="https://example.com/report.pdf" filename="report.pdf">
+</lr-media-card>
+<script type="module">
+  document
+    .getElementById("image-card")
+    .addEventListener("lr-media-open", (e) => openLightbox(e.detail.src));
+  document
+    .getElementById("file-card")
+    .addEventListener("lr-before-media-download", (e) => shouldUseNativeDownload || e.preventDefault());
+</script>
 ```
 
 **Safe-URL checking.** `src` is validated by internal sink-specific helpers before it's

package/llms/components/lr-message-parts.md

@@ -74,7 +74,8 @@ import "@aceshooting/lyra-ui/components/conversation/message-parts/message-parts
 - `lr-copy` event — Passthrough from rendered JSON content.
 - `lr-highlight-activate` event — Passthrough from rendered Markdown.
 - `lr-link-click` event — Passthrough from rendered Markdown.
-- `lr-preview-request` event — Cancelable passthrough from a rendered attachment.
+- `lr-preview-request` event — Passthrough from a rendered attachment. Not cancelable as of 10.0.0:
+  `<lr-attachment-chip>` dropped the flag, since it owns no preview default action to veto.
 - `lr-remove` event — Passthrough from a rendered attachment.
 - `lr-render-error` event — Passthrough from rendered Markdown, tool-result, or widget content.
 - `lr-retry` event — Passthrough from a rendered attachment.

package/llms/components/lr-model-select.md

@@ -225,19 +225,18 @@ shared tokens — `--lr-space-xs/-s`, `--lr-color-border/-surface/-brand/-brand-
 **Optional peer deps:** none.
 
 ```html
-<lr-model-select
-  provider="openai"
-  .catalog=${[
-    { id: 'gpt-4o', label: 'GPT-4o', icon: '✦' },
-    { id: 'gpt-4o-mini', label: 'GPT-4o mini' },
-  ]}
-  value="gpt-4o"
-  placeholder="Choose a model…"
-  @lr-change=${(e) => setModel(e.detail.value, e.detail.inCatalog)}
-></lr-model-select>
+<lr-model-select provider="openai" value="gpt-4o" placeholder="Choose a model…"></lr-model-select>
 
 <!-- No fixed catalog yet: falls back to free-text entry -->
 <lr-model-select provider="ollama" placeholder="Type a model id…" allow-custom></lr-model-select>
+<script type="module">
+  const select = document.querySelector("lr-model-select");
+  select.catalog = [
+    { id: "gpt-4o", label: "GPT-4o", icon: "✦" },
+    { id: "gpt-4o-mini", label: "GPT-4o mini" },
+  ];
+  select.addEventListener("lr-change", (e) => setModel(e.detail.value, e.detail.inCatalog));
+</script>
 ```
 
 **Known gotchas:**