@aceshooting/lyra-ui 4.2.0 → 5.1.0

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

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-line-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/line-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraLineChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/line-chart.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **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`
+
+---
+
+## Typed subclasses: `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`
+
+Each is `LyraChart` with `type` locked to a fixed value — respectively `line`, `bar`, `pie`,
+`doughnut`, `radar`, `polarArea`, `bubble`, `scatter` — via a real `get`/`set` accessor pair the
+shared `lockChartType()` helper installs on the subclass's own prototype (`declare type: '…'`
+narrows the TS type at compile time; the runtime lock is the `Object.defineProperty` pair alongside
+it — the same helper `lr-histogram` uses), not merely a class-field default a later assignment
+could still override.
+
+Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
+and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
+of every entry in these lists.**
+
+**Properties:** `labels`, `datasets`, `legend`, `legendPosition` (attribute `legend-position`),
+`valueFormatter`, `area`, `zoom`, `height`, `xLabel` (`x-label`), `yLabel` (`y-label`), `y2Label`
+(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `config`, `accessibleLabel`
+(`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
+(`show-data-table`), `chartArea` (readonly). `type` is the only member that differs: read-only,
+locked to this tag's value.
+
+**Methods:** `resetZoom()`, `refreshTheme()`.
+
+**Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-point-click` (`detail: { datasetIndex,
+index, label, value }`).
+
+**Slots:** `data-table`, `center`.
+
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`.
+
+**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
+`--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
+`--lr-chart-tooltip-text`.
+
+**Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
+`zoom` is set.
+
+```html
+<lr-bar-chart legend></lr-bar-chart>
+<lr-pie-chart></lr-pie-chart>
+<script>
+  document.querySelector('lr-bar-chart').labels = ['A', 'B'];
+  document.querySelector('lr-bar-chart').datasets = [{ label: 'Count', data: [4, 9] }];
+
+  document.querySelector('lr-pie-chart').labels = ['A', 'B', 'C'];
+  document.querySelector('lr-pie-chart').datasets = [{ label: 'Share', data: [30, 45, 25], color: ['#2563eb', '#16a34a', '#dc2626'] }];
+</script>
+```
+
+**Known gotchas (in addition to the core `lr-chart` list in `llms/components/lr-chart.md`):**
+- `type` truly is locked per subclass: `<lr-pie-chart type="bar">` or `el.type = 'bar'` at runtime
+  is a genuine no-op (the accessor's setter silently ignores the write), not a footgun like a plain
+  overridden class-field default would be.
+- `lr-bubble-chart` needs `Series.points` entries with an `x`/`y`/`r` triple, but `Series.points`
+  is typed as `{x, y, label?}[]` with no `r` field — cast the array through `as unknown as
+  Series['points']` (or a local `BubblePoint` type) when constructing bubble data.
+
+---

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

@@ -0,0 +1,143 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-lite-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/lite-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraLiteChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/lite-chart.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-lite-chart`
+
+A dependency-free bar/line chart — plain SVG/DOM rendering, zero peer dependencies (unlike
+`lr-chart`, which wraps `chart.js`). For a project whose architecture forbids a charting
+dependency outright: covers grouped/stacked bars, multi-series lines, per-point click, and hover
+tooltips (native SVG `<title>`, no positioning JS) — not a full `lr-chart` replacement (no
+zoom/pan, no pie/doughnut/radar/scatter/bubble types, no horizontal/dual-y-axis, no raw-config
+passthrough). Not a subclass of `LyraChart`.
+
+**Properties:**
+- `type: LyraLiteChartType = 'bar'` — `'bar' | 'line'`
+- `labels: string[] = []` (attribute: false)
+- `datasets: LiteSeries[] = []` (attribute: false) — `LiteSeries { label: string; data:
+  (number|null)[]; color?: string }`
+- `legend: boolean = false`
+- `height: string = '280px'`
+- `xLabel: string = ''` (attribute `x-label`)
+- `yLabel: string = ''` (attribute `y-label`)
+- `beginAtZero: boolean = true` (attribute `begin-at-zero`)
+- `stacked: boolean = false` — sums each category's bars into one segmented bar instead of grouping
+  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.
+- `layout: 'fit' | 'scroll' = 'fit'` (reflected) — `'fit'` (default) is the original squeeze-the-
+  whole-plot-to-host-width behavior, unchanged. `'scroll'` gives bars a fixed `barWidth` instead: plot
+  content width becomes `categoryCount * barWidth` (can exceed the host's measured width), and
+  `[part='base']` becomes horizontally `overflow-x: auto` so the user scrolls to see every bar at a
+  legible fixed width instead of them compressing as category count grows. Bar type only.
+- `barWidth: number = 32` (attribute `bar-width`, px) — each bar's fixed width in `layout="scroll"`
+  mode; ignored in the default `'fit'` mode.
+- `maxLabels?: number` (attribute `max-labels`, type Number) — decimates which category axis labels
+  actually render *text* when `labels.length > maxLabels` (bars themselves are never decimated, only
+  their axis `<text>` labels): always shows the first and last label, and roughly evenly distributes
+  the rest between them. Works in either `layout` mode. Unset (the default) renders every label,
+  unchanged.
+- `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
+  (see that component's own `columnX`) by supplying the same coordinate function to both. Unset (the
+  default) is the original formula, unchanged.
+- `pointText?: (label: string, value: number, datasetIndex: number) => string` (attribute: false) —
+  overrides the per-bar/per-point `<title>`/`aria-label` tooltip text (mirrors `lr-heatmap`'s
+  `cellText`). Falls back to the built-in raw-value template when unset.
+- `legendText?: (label: string, datasetIndex: number) => string` (attribute: false) — appends
+  formatter-supplied text (e.g. a value or percentage share) after each series' label in the
+  built-in legend row, mirroring `pointText`/`tickFormat`'s opt-in-hook convention. Falls back to
+  the label alone when unset; no-op while `legend` is `false`.
+- `roundedBars: boolean = false` (attribute `rounded-bars`, bar type only) — draws each bar as a
+  rounded-top-corner shape instead of a square-cornered `<rect>`.
+- `skipZero: boolean = false` (attribute `skip-zero`, bar type only) — omits a bar entirely (no
+  mark/tabindex/tooltip) for a value that is exactly `0`; `null`/non-finite values are always
+  skipped regardless.
+- `padLeft?: number` (attribute `pad-left`) — overrides the internal 36px `PAD_LEFT` plot-left-
+  padding constant. Unset keeps the fixed 36px.
+- `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.
+- `hideAxis: boolean = false` (attribute `hide-axis`) — suppresses gridlines/y-axis tick labels
+  altogether; x-axis category labels (rendered separately) are unaffected.
+- `selectedIndex: number[] = []` (attribute: false) — category indexes to mark `data-selected` on
+  every bar/segment at that index, across every dataset — e.g. to highlight a whole selected week's
+  column in a stacked chart. Empty (the default) reproduces the exact existing output: no bar
+  carries `data-selected`. This component takes no opinion on what the highlight looks like, only
+  which bars it applies to — style it via `::part(bar)[data-selected]`.
+- `minBarHeight?: number` (attribute `min-bar-height`) — optional minimum visible bar height for
+  small non-zero values
+- `accessibleLabel?: string` (attribute `accessible-label`) — SVG accessible-name override; a host
+  `aria-label` wins
+
+**Events:** `lr-point-click` — fired when a bar/point is activated (click, or Enter/Space while
+focused). `detail: { datasetIndex: number, index: number, label: string | undefined, value: number
+| null }` — same shape as `lr-chart`'s `lr-point-click`.
+
+The axis gutter/title and y-axis labels mirror to logical start under RTL. Built-in mark summaries
+are complete localized templates and format values with `effectiveLocale`.
+
+**Performance:** `render()` recomputes the grid/marks on every update rather than memoizing against a
+content signature — `datasets`/`labels` can hold callbacks (`tickFormat`, `barX`) or arbitrary,
+possibly circular or BigInt-bearing application data that a fingerprint can't serialize safely, so a
+fresh, small SVG render is cheaper and more correct than a lossy cache.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `grid-line`, `axis-label`, `axis-title`, `bar` (each bar rect; carries
+`data-selected` when its category index is in `selectedIndex`), `line`, `point`, `legend`,
+`legend-item`, `legend-swatch`, `legend-text` (extra per-item text after the series label,
+rendered only when `legendText` is set), `live-region` (the current mark announcement for keyboard
+users), `data-list` (a visually hidden list of all plotted data points).
+
+**Themeable custom properties:** `--lr-chart-height` (same host-level property as `lr-chart`);
+`--lr-chart-grid-color`, `--lr-chart-tick-color`, `--lr-chart-legend-color` — same token
+*names* as `lr-chart`, so a host already theming `lr-chart` themes this for free;
+`--lr-lite-chart-selected-outline-color` (default `var(--lr-color-brand)`) — the stroke drawn on
+`[part='bar'][data-selected]`, i.e. bars whose category index is in `selectedIndex` (bars only;
+`[part='point']` is never marked `data-selected`, and the stroke width is a fixed 2px). Unlike
+`lr-chart` (canvas-rendered, needs `getComputedStyle`-based re-theming on every draw), this is
+plain SVG/DOM and reads these via native CSS `var()` — no JS-side resolution step, and no
+`refreshTheme()` method needed (there's nothing to go stale).
+
+**Optional peer deps:** none. This is the point of the component.
+
+```html
+<lr-lite-chart type="bar" stacked legend x-label="Week" y-label="Commits"></lr-lite-chart>
+<script>
+  const c = document.querySelector('lr-lite-chart');
+  c.labels = ['W1', 'W2', 'W3', 'W4'];
+  c.datasets = [
+    { label: 'Docs', data: [4, 6, 3, 8] },
+    { label: 'Bugs', data: [3, 2, 5, 4] },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- No `horizontal` mode (unlike `lr-chart`) — deliberately cut from scope, not a stub: bars are
+  always vertical.
+- No dual y-axis (`Series.axis: 'y2'`) — every series shares one y-axis/domain.
+- Series colors default to a fixed built-in 8-color categorical palette (round-robin by dataset
+  index) when `color` is unset — not configurable beyond passing `color` per series.
+- Bar/point elements are real focusable DOM nodes (`tabindex="0" role="button"`, each with its own
+  `aria-label`), so the `<svg>` itself uses `role="group"`, not `role="img"` — an "img" role would
+  conflict with genuinely interactive descendants (axe's `nested-interactive` rule).
+- Tick values use a standard "nice numbers" (1/2/5 × 10ⁿ) rounding step, not exact data min/max —
+  intentional (readable axis labels), matches how most charting libraries pick tick steps.
+
+---

package/llms/components/lr-live-region.md

@@ -0,0 +1,105 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-live-region`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/live-region/live-region.js';` (registers the tag; side-effect import)
+- **Class** `LyraLiveRegion`, also available unregistered from `@aceshooting/lyra-ui/components/utility/live-region/live-region.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-live-region` (+ internal `Announcer`)
+
+A throttled screen-reader announcement helper, split into a DOM-free coalescing engine
+(`internal/announcer.ts`'s `Announcer` class) and a real custom element that wraps it.
+
+### Internal: `Announcer` (`internal/announcer.ts`)
+
+Not a custom element — pure timing/coalescing logic with no DOM dependency, composed by
+`<lr-live-region>` (below) and intended for reuse by any other component that needs throttled
+announcements (a stream-status indicator, a tool-call chip's status transitions, a chat message's
+streaming state).
+
+Streaming UIs (token-by-token chat responses, progress ticks, etc.) naturally produce far more
+candidate announcements than a screen-reader user can usefully absorb — reading every incremental
+chunk aloud is spam, not information. `Announcer` collapses a burst of `announce()` calls arriving
+within `throttleMs` of the *first* call in that burst down to a single trailing-edge flush of the
+latest text: superseded intermediate text is dropped outright, never queued or concatenated.
+
+- `new Announcer(options: AnnouncerOptions)` where
+  `AnnouncerOptions = { throttleMs?: number /* = 500 */; onFlush: (text: string) => void }`.
+- `announce(text: string, options?: AnnounceOptions)` where `AnnounceOptions = { force?: boolean }` —
+  queues `text`, overwriting whatever an earlier call in the same burst queued. Only the *first*
+  call of a burst schedules the flush timer, so the deadline stays anchored to that first call
+  rather than being pushed back by every subsequent call. `{ force: true }` bypasses any
+  in-progress window and flushes immediately, so a terminal message (e.g. "response complete") is
+  never swallowed mid-burst.
+- `cancel()` — drops any pending (not yet flushed) text without invoking `onFlush`.
+- `pendingText: string | undefined` — the latest text awaiting flush, if a burst is in progress.
+- `isPending: boolean` — whether a flush is currently scheduled.
+- `throttleMs` — a plain public field, safe to change between bursts; a flush already scheduled
+  keeps the deadline it was scheduled with.
+
+### `lr-live-region`
+
+A visually-hidden ARIA live region that throttles and coalesces announcements instead of relaying
+every call verbatim, by composing an internal `Announcer`. A consumer typically mounts one
+`<lr-live-region>` per page/surface (much like `<lr-toast>` is one region per placement) and
+keeps a reference to call `announce()` from application code or a parent component.
+
+**Properties:**
+- `mode: 'polite' | 'assertive' = 'polite'` (reflected) — `'polite'` renders `role="status"` +
+  `aria-live="polite"` (waits for the user to be idle); `'assertive'` renders `role="alert"` +
+  `aria-live="assertive"` (interrupts)
+- `throttleMs: number = 500` (attribute `throttle-ms`) — the coalescing window; see `Announcer`
+  above
+
+**Methods:** `announce(text: string, options?: AnnounceOptions): void` — queues `text` for
+announcement through the internal `Announcer`; `{ force: true }` bypasses the current throttle
+window and flushes immediately.
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `region` — the visually-hidden element carrying `role`/`aria-live`/`aria-atomic="true"`.
+
+**Themeable custom properties:** none component-specific — the region is hidden via the shared
+`.sr-only` helper class (`internal/a11y.ts`), not tokenized CSS.
+
+**Optional peer deps:** none.
+
+```html
+<!-- once, near the root of a page/surface -->
+<lr-live-region id="live" mode="polite"></lr-live-region>
+<script type="module">
+  const live = document.getElementById('live');
+  // streaming tokens: fine to call on every chunk, only the trailing state lands
+  live.announce(`${partialText} …`);
+  // stream finished: always announced, even mid-throttle-window
+  live.announce('Response complete', { force: true });
+</script>
+```
+
+A parent Lit component would instead hold the reference via `@query('lr-live-region')`.
+
+**Known gotchas:**
+- Re-announcing text identical to what was last written is special-cased: screen readers announce a
+  live region only on text-content *change*, so the component clears `textContent` first and
+  re-sets it on the next animation frame (not the same tick, which can coalesce into nothing ever
+  appearing to change) to give assistive tech a real empty-to-populated transition to observe. The
+  frame is scheduled and canceled through the region's own document window, including after the
+  element is adopted into an iframe.
+- The region's DOM is tracked outside Lit's own template bindings (`write()` mutates
+  `regionEl.textContent` directly) — an `announce()`/flush landing before `firstUpdated()` has run
+  (e.g. a consumer creates, appends, and calls `announce()` synchronously) is buffered and applied
+  on the next `firstUpdated()` rather than dropped.
+- `disconnectedCallback()` cancels any pending (unflushed) announcement, any before-first-render
+  buffered write, and any in-flight re-announce animation-frame callback — an element removed before
+  a deferred write lands silently drops it, including across a later reconnect.
+- Changing `throttle-ms` updates the live `Announcer`'s window immediately, but a flush already
+  scheduled under the old window keeps the deadline it was scheduled with.
+
+---

package/llms/components/lr-map.md

@@ -0,0 +1,127 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-map`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/map/map.js';` (registers the tag; side-effect import)
+- **Class** `LyraMap`, also available unregistered from `@aceshooting/lyra-ui/components/media/map/map.class.js`
+- **Family** `components/media/` — see `llms/index.md` for its siblings
+- **Optional peers** `maplibre-gl` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-map`
+
+A `maplibre-gl` wrapper with a declarative legend, a single choropleth GeoJSON fill layer, markers,
+and additive plain-GeoJSON `dataLayers`, plus a raw `map` escape hatch for anything unexposed.
+
+**Properties:**
+- `center: [number, number] = [0, 0]`
+- `zoom: number = 2`
+- `mapStyle: StyleSpecification | string = DEFAULT_STYLE` (attribute: false) — the default is a
+  basic OSM raster tile style pointing at **OpenStreetMap's shared demo tile server**. Fine for
+  local development, but its usage policy forbids bulk/production traffic, requires an identifying
+  User-Agent, and rate-limits or IP-blocks non-compliant clients
+  (https://operations.osmfoundation.org/policies/tiles/). **Production apps must pass their own
+  `mapStyle`** — a hosted vector/raster style from a tile provider you have a plan with.
+- `legend: LegendEntry[] = []` (attribute: false) — `LegendEntry { color: string; label: string }`
+  (discrete swatch rows only, no continuous gradient bar)
+- `choropleth?: ChoroplethLayer` (attribute: false) — `ChoroplethLayer { sourceId: string; geojson:
+  GeoJSON.FeatureCollection; field: string; stops: [number, 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)
+- `markers: MapMarker[] = []` (attribute: false) — `MapMarker { id?: string; lngLat: [number,
+  number]; color?: string; label?: string; unsafeHtml?: string }`; reconciled by `id` (falling back
+  to a `lng,lat` key, disambiguated by occurrence order for duplicate-coordinate id-less markers,
+  when `id` is omitted) so an unchanged marker isn't torn down and recreated on every `markers`
+  reassignment — its `lngLat` **and** its popup content (`unsafeHtml`/`label`, in that precedence)
+  are both updated in place, and the popup is removed if a later update sets neither. `unsafeHtml` is
+  rendered via `Popup.setHTML()` — **raw markup, inline event handlers included** — only pass trusted
+  content, sanitize anything derived from user input first; prefer `label` (`Popup.setText()`,
+  escaped) when the content is plain text. A marker whose `color` changes for a persisting `id`
+  can't be recolored in place (no `Marker.setColor()`) and is torn down/reconstructed instead — see
+  gotchas.
+- `dataLayers: GeoJsonDataLayer[] = []` (attribute: false) — `GeoJsonDataLayer { sourceId: string;
+  geojson: GeoJSON.Feature | GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
+  'danger' | 'neutral' }`. Each entry adds one GeoJSON source plus three layers
+  (`${sourceId}-fill`/`${sourceId}-line`/`${sourceId}-circle`, filtered by geometry type so a mixed
+  `FeatureCollection` renders correctly across all three), colored from the matching `--lr-color-*`
+  token (`tone` defaults to `'accent'` → `--lr-color-brand`). Independent of `choropleth` — no
+  `field`/`stops` color-interpolation, just the geometry rendered in a flat tone; use `choropleth`
+  instead when you need a data-driven color ramp. Reconciled by `sourceId` the same way `choropleth`
+  is: an entry whose `sourceId` persists across a `dataLayers` reassignment gets its GeoJSON updated
+  in place (`setData()`), one that's dropped has its source/layers removed, and a genuinely new
+  `sourceId` gets a new source/layers — nothing leaks on removal, style change, or disconnect.
+- `label: string = ''` — accessible name for the map region, applied as `[part="base"]`'s
+  `aria-label`. A plain `aria-label` attribute on the host itself is honored as a fallback when
+  `label` is left unset, matching `lr-slider`/`lr-checkbox`/`lr-switch`; with neither set, it
+  falls back to the localized `'map'` message.
+
+**Getters:** `map` → the raw `maplibregl.Map` instance.
+
+**Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`), `lr-map-click`
+(`detail: { lngLat: [lng, lat], feature? }` — feature only populated if a choropleth fill layer
+exists and was hit)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `container`, `legend`, `legend-swatch`
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs/-s`, `--lr-color-surface`,
+`--lr-color-border`, `--lr-shadow`, `--lr-radius`.
+
+**Optional peer deps:** `maplibre-gl` (lazy-loaded; consumer must **separately** `import
+'maplibre-gl/dist/maplibre-gl.css'` once — the component does not do this for you).
+
+```html
+<lr-map center="[2.35, 48.85]" zoom="10"></lr-map>
+<script>
+  import 'maplibre-gl/dist/maplibre-gl.css';
+  const m = document.querySelector('lr-map');
+  m.choropleth = {
+    sourceId: 'regions',
+    geojson: myGeoJson,
+    field: 'value',
+    stops: [[0, '#cde2fb'], [100, '#0969da']],
+  };
+  m.legend = [{ color: '#cde2fb', label: 'Low' }, { color: '#0969da', label: 'High' }];
+  m.markers = [{ lngLat: [2.29, 48.86], label: 'Eiffel Tower' }];
+  m.addEventListener('lr-map-click', (e) => console.log(e.detail.feature?.properties));
+</script>
+```
+
+**Known gotchas:**
+- clearing or swapping the choropleth no longer leaks the old layer: setting `choropleth =
+  undefined`, or changing `choropleth.sourceId` to a different value, now calls `removeLayer`/
+  `removeSource` on whatever was previously applied before adding the new one (or nothing, if
+  cleared).
+- `mapStyle` changes after construction now call `setStyle()` (in addition to `center`/`zoom`
+  already calling `setCenter`/`setZoom`) — the choropleth and `dataLayers` are both automatically
+  re-applied once the new style's own `'style.load'` fires, since a style change wipes every
+  layer/source maplibre-gl knows about.
+- Point markers now have a declarative API (`markers`, above) with popup support — the `.map` escape
+  hatch and manual `new maplibregl.Marker()` are no longer the only way to place pins.
+- a marker whose `color` changes for a persisting `id` is torn down and reconstructed (maplibre-gl's
+  `Marker` has no `setColor()`) rather than mutated in place — this also closes any popup the user
+  currently has open on that marker (a fresh, closed `Popup` is built for the new instance); an
+  accepted side effect of the reconstruction fallback, not a bug.
+- No click-select visual highlight on choropleth features (no `setFeatureState` call) — clicking
+  only fires the event, no built-in visual feedback. Popups are still only reachable declaratively
+  through `markers`' `unsafeHtml`/`label` — a choropleth-feature click still has no built-in popup,
+  only the raw `lr-map-click` event.
+- `LegendEntry.color` is validated against a strict CSS-color-syntax allowlist before being applied
+  to the legend swatch's `background`, rejecting anything that isn't recognizable color syntax
+  (notably `url(...)`, which `background` also accepts and would otherwise fetch as soon as the
+  swatch renders).
+- while the `maplibre-gl` peer is resolving, the host shows a `<lr-skeleton variant="rect">` with
+  `aria-busy="true"` in place of the map container.
+- construction of the real `maplibregl.Map` (and its WebGL context) is additionally gated on this
+  element being observed intersecting the viewport (`IntersectionObserver`), independent of whether
+  the `maplibre-gl` peer has already loaded — an off-screen `<lr-map>` swaps its skeleton for the
+  empty `[part="container"]` div as soon as the peer resolves, but `map` stays `undefined` and
+  `lr-map-load` never fires until the element is actually scrolled into view. Deliberate: caps
+  concurrent WebGL contexts when many `<lr-map>`s sit in one dashboard/grid. Skipped entirely
+  (constructs immediately once the peer loads) when `IntersectionObserver` itself is unavailable.
+
+---

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

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-markdown-core`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/markdown/markdown-core.js';` (registers the tag; side-effect import)
+- **Class** `LyraMarkdownCore`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/markdown/markdown-core.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-markdown-core`
+
+A build-lean sibling of `<lr-markdown>` above, for a consumer whose `languages` map already covers
+every language it will ever render — mirrors `<lr-code-block-core>`'s relationship to
+`<lr-code-block>`. Where `<lr-markdown>` unconditionally calls `loadShikiHighlighter()` — the
+default ~200-language dynamic-import table loader, whose bundled lookup table a bundler can't
+statically narrow away even when a consumer's `languagesOnly` flag makes it unreachable at runtime —
+this component's own module never imports or calls that function at all; it only ever calls
+`loadShikiHighlighterCore(languages)`, so a consumer importing this entry point instead of
+`markdown.js` gets a build genuinely free of shiki's full language table.
+
+A fenced code block whose language isn't a key in `languages` always renders the plain-text fallback
+— there is no default/full-table highlighter here to fall back to, the same default (not degraded)
+rendering path as `<lr-code-block-core>`'s identical contract. Every other capability — GFM tables,
+links, blockquotes, images, heading anchors, `getHeadingTree()`, `fragment`/`text-quote` anchor-target
+support (`highlights`, `activeHighlightId`, `scrollToAnchor()`, the `lr-highlight-activate`/
+`lr-text-select`/`lr-anchor-result` events), math via the optional `katex` peer, the sanitize/
+`escapeHtml`/streaming fallback matrix and known gotchas — is identical to `<lr-markdown>`; see that
+section above for the full write-up of shared behavior. There is no `languagesOnly` property here —
+meaningless without a full-table fallback to gate, matching `<lr-code-block-core>` having none
+either.
+
+**Properties:** `content: string = ''`, `sanitize: boolean = true`, `escapeHtml: boolean = false`
+(attribute `escape-html`), `gfm: boolean = true`, `linkTarget: string | null = '_blank'` (attribute
+`link-target`), `internalLinkPrefix: string = ''` (attribute `internal-link-prefix`),
+`headingOffset: number = 0` (attribute `heading-offset`), `eagerLoad: boolean = false` (attribute
+`eager-load`), `streaming: boolean = false` (reflected), `highlightCode: boolean = true` (attribute
+`highlight-code`), `languages: Record<string, ShikiLanguageInput> = {}` (attribute: false) — required,
+unlike `<lr-markdown>`'s optional `languages?:`; empty (the default) means every fenced block stays
+unhighlighted permanently, `headingAnchors: boolean = false` (attribute `heading-anchors`),
+`math: boolean = false`, `anchorKinds: readonly ('fragment' | 'text-quote')[]` (readonly).
+
+**Methods:** `getHeadingTree()` — same contract as `<lr-markdown>`'s own.
+
+**Events:** `lr-link-click`, `lr-render-error`, `lr-highlight-activate`, `lr-text-select`,
+`lr-anchor-result` — identical detail shapes to `<lr-markdown>`'s own.
+
+**Slots:** none — content comes from the `content` property, not light-DOM children.
+
+**CSS parts:** `content`, `heading`, `paragraph`, `list`, `code-block`, `inline-code`, `link`,
+`table`, `blockquote`, `img`, `math` — identical to `<lr-markdown>`'s own parts.
+
+**Optional peer deps:** `marked`, `dompurify` (both lazy-loaded, same as `<lr-markdown>`), `katex`
+(for `math`). Does *not* depend on the full `shiki` package's default entry point — only
+`shiki/core`/`shiki/engine/oniguruma`/`shiki/langs/*`, the same fine-grained subset
+`<lr-code-block-core>` depends on.
+
+```html
+<lr-markdown-core
+  content="# Report&#10;&#10;\`\`\`python&#10;print('hi')&#10;\`\`\`"
+  .languages=${{ python }}
+></lr-markdown-core>
+<script type="module">
+  import python from 'shiki/langs/python.mjs';
+</script>
+```
+
+---