@aceshooting/lyra-ui 6.1.0 → 7.0.0

package/dist/components/charts/chart/chart.class.js

@@ -10,10 +10,15 @@ import { styleMap } from 'lit/directives/style-map.js';
 import { LyraElement } from '../../../internal/lyra-element.js';
 import { nextId, srOnly } from '../../../internal/a11y.js';
 import { prefersReducedMotion } from '../../../internal/motion.js';
-import { loadChartJs, loadChartJsWithZoom } from './chart-loader.js';
+import { ThemeWatcher } from '../../../internal/theme-watcher.js';
+import { loadChartJs, loadChartJsWithZoom, loadChartJsWithDataLabels } from './chart-loader.js';
 import { styles } from './chart.styles.js';
 import '../../overlays/skeleton/skeleton.class.js';
-import { getNumberFormat } from '../../../internal/intl-cache.js';
+import { getListFormat, getNumberFormat } from '../../../internal/intl-cache.js';
+import { escapeCsvField } from '../../utility/export-button/csv.js';
+import { trueDefaultBooleanFromAttributeConverter as trueDefaultBooleanConverter } from '../../../internal/converters.js';
+import { resolveCanvasColor, seriesPalette, translucentAreaColor } from './chart-colors.js';
+export { seriesPalette } from './chart-colors.js';
 const CHART_TYPES = new Set([
     'line',
     'bar',
@@ -39,18 +44,6 @@ function normalizeChartType(value) {
         ? value
         : 'line';
 }
-/** `true`-defaulting boolean attribute converter for `beginAtZero` -- identical shape/rationale to
- *  `<lr-checkpoint>`'s own `trueDefaultBooleanConverter`, duplicated locally per this library's
- *  convention of not sharing these tiny converters across independently-consumable component
- *  files. Lit's default presence-based `type: Boolean` can never be set back to `false` from a
- *  plain-HTML attribute once the property's own default is `true` (removing an attribute that was
- *  never present fires no `attributeChangedCallback`), so `fromAttribute` checks the literal
- *  string instead. */
-const trueDefaultBooleanConverter = {
-    fromAttribute(value) {
-        return value !== 'false';
-    },
-};
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -67,23 +60,6 @@ const FALLBACK_TICK_COLOR = '#6b7280';
 const FALLBACK_LEGEND_COLOR = '#1a1a1a';
 const FALLBACK_TOOLTIP_BG = '#fff';
 const FALLBACK_TOOLTIP_TEXT = '#1a1a1a';
-// Light-mode defaults of --lr-color-chart-1..8 (see internal/tokens.styles.ts), the same
-// categorical ramp <lr-lite-chart>'s DEFAULT_PALETTE draws from. Used to give a series with
-// no explicit `color` a themed, theme-visible default instead of Chart.js's own hardcoded
-// near-black (rgba(0,0,0,.1)) fill, which is invisible on the dark theme — grid/tick/legend
-// were already themed via themeColors(), but the data series itself was not. Only the literal
-// fallbacks here are reached when getComputedStyle can't resolve the custom properties (host
-// detached); a live host resolves the real, dark-aware values in seriesPalette() below.
-const FALLBACK_SERIES_PALETTE = [
-    '#8250df',
-    '#bf3989',
-    '#0a7d91',
-    '#57606a',
-    '#b083f5',
-    '#f470b8',
-    '#52d6e8',
-    '#c9d1d9',
-];
 /**
  * Recursively merges `override` onto `base`, matching JSON-merge semantics:
  * plain objects are merged key-by-key at every depth; arrays, functions, and
@@ -125,7 +101,9 @@ function deepMerge(base, override, seen = new WeakMap()) {
 }
 /**
  * `<lr-chart>` — the core Chart.js wrapper every other `lr-*-chart` tag
- * subclasses. Requires the optional peer deps `chart.js` + `chartjs-plugin-zoom`.
+ * subclasses. Requires the optional peer dep `chart.js`; `chartjs-plugin-zoom`
+ * (for `zoom`) and `chartjs-plugin-datalabels` (for `data-labels`/`stack-totals`)
+ * are further optional peers loaded only on demand.
  *
  * **API mirror note:** the real `wa-chart` docs page
  * (https://webawesome.com/docs/components/chart/) documents a `config:
@@ -144,8 +122,8 @@ function deepMerge(base, override, seen = new WeakMap()) {
  *
  * @customElement lr-chart
  * @event lr-zoom - `detail: { zoomed }`.
- * @event lr-point-click - Fired when a click lands on (or nearest,
- *   intersect-only — see `handlePointClick()`) a data point/segment.
+ * @event lr-point-click - Fired when pointer input lands on a data point/segment, when a generated
+ *   data-table value is activated, or when Enter/Space activates the keyboard-current canvas datum.
  *   `detail: { datasetIndex: number, index: number, label: string |
  *   undefined, value: unknown }`.
  * @csspart base - The chart wrapper.
@@ -176,8 +154,9 @@ function deepMerge(base, override, seen = new WeakMap()) {
  *   doughnut and pie totals.
  */
 export class LyraChart extends LyraElement {
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
     constructor() {
-        super(...arguments);
+        super();
         this.type = 'line';
         this.labels = [];
         this.datasets = [];
@@ -201,6 +180,22 @@ export class LyraChart extends LyraElement {
         this.horizontal = false;
         /** Stacks the `x`/`y`(/`y2`) scale entries `buildScales()` returns; only meaningful for `bar` and `line` types. */
         this.stacked = false;
+        /**
+         * Draws each data point's value on the chart via the optional
+         * `chartjs-plugin-datalabels` peer. Unset (the default) leaves labels off for
+         * this chart; the peer is attached only to instances that opt in, and
+         * `buildConfig()` keeps its per-chart options disabled until this is set. The
+         * screen-reader equivalent is the always-present data table (see
+         * `show-data-table`); labels are a purely visual, canvas-only addition.
+         */
+        this.dataLabels = false;
+        /**
+         * When the chart is `stacked` (bar/line only), draws the per-category stack
+         * total above each stack, via the same optional `chartjs-plugin-datalabels`
+         * peer as `data-labels`. Null/undefined points are skipped; a category whose
+         * every value is null shows no total. Unset (the default) draws nothing.
+         */
+        this.stackTotals = false;
         /** True until the lazy-loaded `chart.js` peer dependency has settled (success or failure). */
         this.loading = true;
         /**
@@ -212,6 +207,13 @@ export class LyraChart extends LyraElement {
         // inject a stubbed loader before the element ever connects -- matches map/docx-viewer's own
         // `loadLibrary` field/rationale exactly.
         this.loadLibrary = (withZoom) => withZoom ? loadChartJsWithZoom() : loadChartJs();
+        // Invalidates a lazy-load callback when this element disconnects/reconnects. Without a
+        // generation token, two connectedCallback() calls around one in-flight import can both settle
+        // against the reconnected element and construct/reconfigure the chart from stale lifecycle
+        // state.
+        this.loadGeneration = 0;
+        this.zoomLoadGeneration = 0;
+        this.dataLabelsLoadGeneration = 0;
         this.zoomed = false;
         this.visible = true;
         this.autoLegendPosition = 'right';
@@ -223,8 +225,44 @@ export class LyraChart extends LyraElement {
         // driving the plugin so that re-entrant callback is ignored.
         this.suppressZoomComplete = false;
         this.descriptionId = nextId('chart-description');
+        this.datumStatusId = nextId('chart-datum-status');
+        this.keyboardDatumIndex = 0;
+        this.keyboardDatumAnnouncement = '';
+        // Redraws (re-resolving `--lr-chart-*` via getComputedStyle, since canvas can't read var())
+        // when prefers-color-scheme flips or an ancestor's theme attribute mutates. The controller
+        // registers itself with the host via addController(); redraw only once a chart exists.
+        new ThemeWatcher(this, () => {
+            if (this.chart)
+                this.refreshTheme();
+        });
+    }
+    /**
+     * Appends one streamed category to numeric `data` series and optionally keeps only the newest
+     * `maxPoints` categories. Point-based scatter/bubble series are left unchanged because their
+     * x/y coordinates need a richer host-defined append contract.
+     */
+    appendData(label, values, maxPoints = 0) {
+        const limit = Number.isFinite(maxPoints) ? Math.max(0, Math.floor(maxPoints)) : 0;
+        const labels = [...this.labels, label];
+        const datasets = this.datasets.map((series, index) => series.points
+            ? series
+            : { ...series, data: [...(series.data ?? []), values[index] ?? null] });
+        this.labels = limit > 0 ? labels.slice(-limit) : labels;
+        this.datasets = limit > 0
+            ? datasets.map((series) => (series.points ? series : { ...series, data: series.data?.slice(-limit) }))
+            : datasets;
+    }
+    /** Returns a spreadsheet-safe CSV snapshot of the chart's label/data series. */
+    exportData(format) {
+        if (format === 'png')
+            return this.chart?.toBase64Image?.() ?? '';
+        const header = ['label', ...this.datasets.map((series) => series.label)].map(escapeCsvField).join(',');
+        const rowCount = Math.max(this.labels.length, ...this.datasets.map((series) => series.data?.length ?? series.points?.length ?? 0), 0);
+        const rows = Array.from({ length: rowCount }, (_, index) => [this.labels[index] ?? '', ...this.datasets.map((series) => series.points?.[index]?.y ?? series.data?.[index] ?? '')]
+            .map(escapeCsvField)
+            .join(','));
+        return [header, ...rows].join('\r\n');
     }
-    static { this.styles = [LyraElement.styles, styles, srOnly]; }
     connectedCallback() {
         super.connectedCallback();
         if (typeof ResizeObserver !== 'undefined') {
@@ -235,9 +273,10 @@ export class LyraChart extends LyraElement {
             this.resizeObserver.observe(this);
         }
         this.updateAutoLegendPosition();
+        const generation = ++this.loadGeneration;
         const load = this.loadLibrary(this.zoom);
         void load.then((mod) => {
-            if (!this.isConnected)
+            if (generation !== this.loadGeneration || !this.isConnected)
                 return;
             this.loading = false;
             if (!mod) {
@@ -248,6 +287,20 @@ export class LyraChart extends LyraElement {
             this.chartJsModule = mod;
             this.draw();
         });
+        // `data-labels`/`stack-totals` need the optional `chartjs-plugin-datalabels`
+        // peer registered before the plugin's `datalabels` options in `buildConfig()`
+        // take effect. Load it in parallel with the core (both memoized), then
+        // redraw once it's registered — mirrors the `zoom` on-demand load and its
+        // generation + `isConnected` guard against a disconnect mid-import.
+        if (this.needsDataLabels) {
+            const dlGeneration = ++this.dataLabelsLoadGeneration;
+            void loadChartJsWithDataLabels().then((result) => {
+                if (dlGeneration !== this.dataLabelsLoadGeneration || !this.isConnected || !this.needsDataLabels) {
+                    return;
+                }
+                this.applyDataLabelsPlugin(result?.plugin);
+            });
+        }
         if (typeof IntersectionObserver !== 'undefined') {
             this.intersectionObserver = new IntersectionObserver((entries) => {
                 const wasVisible = this.visible;
@@ -262,10 +315,35 @@ export class LyraChart extends LyraElement {
         super.disconnectedCallback();
         this.resizeObserver?.disconnect();
         this.resizeObserver = undefined;
+        this.loadGeneration += 1;
+        this.zoomLoadGeneration += 1;
+        this.dataLabelsLoadGeneration += 1;
         this.chart?.destroy();
         this.chart = undefined;
         this.intersectionObserver?.disconnect();
     }
+    /**
+     * Called once the `chartjs-plugin-datalabels` peer resolves. Chart.js reads a
+     * config's inline `plugins: [...]` array ONLY at construction — the in-place
+     * `chart.data`/`chart.options` update path in `draw()` never picks up a plugin
+     * added later. So on a cold load (plugin resolves after the chart was already
+     * built) or a `data-labels`/`stack-totals` turn-on, the live chart must be
+     * torn down and rebuilt for the per-instance plugin to actually attach. Guards
+     * on the plugin being newly present so a redraw that already includes it (or a
+     * feature that's since been turned back off) doesn't needlessly rebuild.
+     */
+    applyDataLabelsPlugin(plugin) {
+        this.dataLabelsPlugin = plugin;
+        if (plugin && this.needsDataLabels && this.chart) {
+            // Force reconstruction: a live chart built without the plugin can't gain
+            // it through chart.update(). destroy() + clearing builtType makes the next
+            // draw() take the `new Chart()` branch, which reads config.plugins.
+            this.chart.destroy();
+            this.chart = undefined;
+            this.builtType = undefined;
+        }
+        this.draw();
+    }
     /**
      * Resets a stale `zoomed` flag before the render pass that's about to call
      * `draw()`: a `type` (or `config.type` override) change that lands on a
@@ -329,11 +407,26 @@ export class LyraChart extends LyraElement {
         // dynamic import is in flight — without this guard, `draw()` would
         // construct a new, leaked `Chart` bound to the now-detached canvas once
         // the import resolves.
-        if (changed.has('zoom') && this.zoom) {
-            void loadChartJsWithZoom().then(() => {
-                if (!this.isConnected)
+        if (changed.has('zoom')) {
+            const zoomGeneration = ++this.zoomLoadGeneration;
+            if (this.zoom) {
+                void loadChartJsWithZoom().then(() => {
+                    if (zoomGeneration !== this.zoomLoadGeneration || !this.isConnected || !this.zoom)
+                        return;
+                    this.draw();
+                });
+            }
+        }
+        // `data-labels`/`stack-totals` can turn on after connect (like `zoom`) — load
+        // the plugin on demand and redraw once it's registered, with the same
+        // generation + `isConnected` guard against a disconnect mid-import.
+        if ((changed.has('dataLabels') || changed.has('stackTotals')) && this.needsDataLabels) {
+            const dlGeneration = ++this.dataLabelsLoadGeneration;
+            void loadChartJsWithDataLabels().then((result) => {
+                if (dlGeneration !== this.dataLabelsLoadGeneration || !this.isConnected || !this.needsDataLabels) {
                     return;
-                this.draw();
+                }
+                this.applyDataLabelsPlugin(result?.plugin);
             });
         }
         const contentChanged = [
@@ -352,6 +445,8 @@ export class LyraChart extends LyraElement {
             'beginAtZero',
             'horizontal',
             'stacked',
+            'dataLabels',
+            'stackTotals',
             'config',
             'zoom',
             'locale',
@@ -365,15 +460,30 @@ export class LyraChart extends LyraElement {
         this.draw();
     }
     seriesToDataset(s, index, palette, effectiveType) {
-        const colors = Array.isArray(s.color) ? s.color : s.color ? [s.color] : undefined;
+        const colors = Array.isArray(s.color)
+            ? s.color.map((color) => resolveCanvasColor(this, color, palette[index % palette.length] ?? 'transparent'))
+            : s.color
+                ? [resolveCanvasColor(this, s.color, palette[index % palette.length] ?? 'transparent')]
+                : undefined;
         // Default a color-less series to the categorical palette, keyed by dataset index (matching
-        // <lr-lite-chart>). pie/doughnut carry one series whose *slices* each need a distinct color,
-        // so those default to an array cycled across the palette; every other family is one color
-        // per series. Only applied when the caller gave no `color` — an explicit `color` still wins.
+        // <lr-lite-chart>). pie/doughnut/polarArea carry one series whose *slices* each need a distinct
+        // color, so those default to an array cycled across the palette; every other family is one
+        // color per series. Only applied when the caller gave no `color` — an explicit `color` still wins.
         const fallback = palette.length ? palette[index % palette.length] : undefined;
-        const sliceColors = (effectiveType === 'pie' || effectiveType === 'doughnut') && palette.length
+        const sliceColors = (effectiveType === 'pie' || effectiveType === 'doughnut' || effectiveType === 'polarArea') && palette.length
             ? (s.points ?? s.data ?? []).map((_, i) => palette[i % palette.length])
             : undefined;
+        const fill = s.fill ?? this.area;
+        const backgroundColor = colors ?? sliceColors ?? fallback;
+        const datasetType = s.type ?? effectiveType;
+        const segmentColors = s.segmentColors?.map((color) => resolveCanvasColor(this, color, colors?.[0] ?? fallback ?? 'transparent'));
+        const resolvedBackgroundColor = datasetType === 'line' && fill
+            ? Array.isArray(backgroundColor)
+                ? backgroundColor.map((color) => translucentAreaColor(this, color))
+                : backgroundColor
+                    ? translucentAreaColor(this, backgroundColor)
+                    : backgroundColor
+            : backgroundColor;
         return {
             label: s.label,
             data: s.points ?? s.data ?? [],
@@ -391,13 +501,24 @@ export class LyraChart extends LyraElement {
             // series over a bar chart of the *same* effective family) is passed
             // through.
             type: s.type,
-            fill: s.fill ?? this.area,
+            fill,
             borderWidth: s.width ?? 2,
             borderDash: s.dash ? [4, 4] : undefined,
-            backgroundColor: colors ?? sliceColors ?? fallback,
+            backgroundColor: resolvedBackgroundColor,
             borderColor: colors?.[0] ?? fallback,
-            pointBackgroundColor: s.pointColors,
+            pointBackgroundColor: s.pointColors?.map((color) => resolveCanvasColor(this, color, colors?.[0] ?? fallback ?? 'transparent')),
             pointRadius: s.pointRadius,
+            // `segment` is Chart.js's per-line-segment scriptable-options hook (line controller only),
+            // keyed by the segment's *starting* point index. Only spread in when the series actually
+            // sets `segmentColors`, so a series without it produces the exact dataset object it always
+            // did — Chart.js treats a present-but-inert `segment` key differently from an absent one.
+            ...(segmentColors?.length
+                ? {
+                    segment: {
+                        borderColor: (ctx) => segmentColors[ctx.p0DataIndex % segmentColors.length],
+                    },
+                }
+                : {}),
             yAxisID: s.axis === 'y2' ? 'y2' : 'y',
         };
     }
@@ -419,28 +540,130 @@ export class LyraChart extends LyraElement {
             tooltipText: cs.getPropertyValue('--lr-chart-tooltip-text').trim() || FALLBACK_TOOLTIP_TEXT,
         };
     }
+    /** Whether this chart wants the optional `chartjs-plugin-datalabels` peer loaded — either to draw
+     *  per-point data labels or per-stack totals. */
+    get needsDataLabels() {
+        return this.dataLabels || this.stackTotals;
+    }
+    /**
+     * `options.plugins.datalabels`. Always emitted so the chart also stays inert if
+     * a consumer independently registers the peer globally — returns `{ display: false }`
+     * unless `data-labels`/`stack-totals` is set. The label
+     * color is resolved via `getComputedStyle` (the same `themeColors()` tick
+     * color) because Chart.js paints to canvas and cannot read `var()`.
+     *
+     * `stackTotals` draws once per category: the plugin fires per (dataset, point),
+     * so a total is shown only on the topmost stacked dataset of each axis and its
+     * formatter returns the null-aware `computeStackTotals()` value (blank when the
+     * whole category is null). When only `dataLabels` is set, each point shows its
+     * own value; a null/non-finite point renders blank.
+     */
+    datalabelsOptions(theme, effectiveType) {
+        if (!this.needsDataLabels)
+            return { display: false };
+        const stackTotalsActive = this.stackTotals && (effectiveType === 'bar' || effectiveType === 'line');
+        // The topmost dataset per axis carries the stack total (drawn above the stack).
+        const topDatasetIndexByAxis = new Map();
+        if (stackTotalsActive) {
+            this.datasets.forEach((s, i) => topDatasetIndexByAxis.set(s.axis === 'y2' ? 'y2' : 'y', i));
+        }
+        const totalsByAxis = stackTotalsActive
+            ? { y: this.computeStackTotals('y'), y2: this.computeStackTotals('y2') }
+            : undefined;
+        return {
+            color: theme.tick,
+            // Totals sit above the stack; plain point labels center on the point.
+            align: stackTotalsActive ? 'end' : 'center',
+            anchor: stackTotalsActive ? 'end' : 'center',
+            display: (context) => {
+                const datasetIndex = context.datasetIndex;
+                const axis = this.datasets[datasetIndex]?.axis === 'y2' ? 'y2' : 'y';
+                if (stackTotalsActive) {
+                    // Only the topmost dataset of each axis draws, and only where the
+                    // category total is non-null.
+                    if (topDatasetIndexByAxis.get(axis) !== datasetIndex)
+                        return this.dataLabels;
+                    const total = totalsByAxis?.[axis][context.dataIndex];
+                    if (total == null)
+                        return this.dataLabels;
+                    return true;
+                }
+                return this.dataLabels;
+            },
+            formatter: (value, context) => {
+                const datasetIndex = context.datasetIndex;
+                const axis = this.datasets[datasetIndex]?.axis === 'y2' ? 'y2' : 'y';
+                if (stackTotalsActive && topDatasetIndexByAxis.get(axis) === datasetIndex) {
+                    const total = totalsByAxis?.[axis][context.dataIndex];
+                    if (total != null)
+                        return this.formatDataLabel(total);
+                }
+                const numeric = typeof value === 'number' ? value : Number(value?.y ?? value);
+                if (numeric == null || !Number.isFinite(numeric))
+                    return '';
+                return this.formatDataLabel(numeric);
+            },
+        };
+    }
+    /** Locale/format a data-label number through the same `valueFormatter` the axis/tooltip use, so a
+     *  drawn label matches the rest of the chart; falls back to a plain locale string. The formatter
+     *  runs in the `'tooltip'` context — the closest semantic match to an on-point value label, so a
+     *  consumer formatter that branches on context behaves predictably rather than seeing `undefined`. */
+    formatDataLabel(value) {
+        if (this.valueFormatter) {
+            const formatted = this.valueFormatter(value, 'tooltip');
+            if (formatted != null)
+                return String(formatted);
+        }
+        return value.toLocaleString(this.effectiveLocale);
+    }
+    /**
+     * Per-category stack totals for the datasets on axis `axisId` (`'y'`/`'y2'`),
+     * or `null` for a category whose every value is null/undefined (so no total
+     * is drawn there rather than a misleading `0`). Reads the same per-point
+     * values as the sr-only data table, null-aware — canvas draws these via the
+     * datalabels plugin, but the numbers themselves stay screen-reader available
+     * through `renderDataTable()`.
+     */
+    computeStackTotals(axisId = 'y') {
+        const members = this.datasets.filter((s) => (s.axis === 'y2' ? 'y2' : 'y') === axisId);
+        const categoryCount = members.reduce((max, s) => Math.max(max, (s.points ?? s.data ?? []).length), this.labels.length);
+        const totals = [];
+        for (let i = 0; i < categoryCount; i++) {
+            let sum = 0;
+            let any = false;
+            for (const s of members) {
+                const raw = s.points ? s.points[i]?.y : s.data?.[i];
+                if (raw == null || !Number.isFinite(raw))
+                    continue;
+                sum += raw;
+                any = true;
+            }
+            totals.push(any ? sum : null);
+        }
+        return totals;
+    }
     /**
      * Resolves the categorical series palette (`--lr-color-chart-1..8`, declared in
-     * `internal/tokens.styles.ts` with their own dark-theme ramp) via `getComputedStyle` —
+     * `internal/tokens.styles.ts` as indirections through `--lr-theme-color-chart-1..8`, with their
+     * own dark-theme ramp) via `getComputedStyle` —
      * same canvas-can't-read-`var()` constraint as `themeColors()`, and the same source
      * `<lr-lite-chart>` draws its default palette from. Feeds `seriesToDataset()` a concrete,
      * theme-aware default color for any series that sets no `color` of its own. Falls back to
      * the light-mode literals only if the custom properties can't be resolved (host detached).
+     *
+     * Public so app code can color its own chart-adjacent UI (legends, KPI tiles, annotations
+     * fed through the raw `config` passthrough) from the same resolved ramp the chart itself
+     * uses, instead of hand-resolving `--lr-color-chart-N` and drifting out of sync with the
+     * active theme. Returns a fresh array on every call — mutating it does not affect the chart.
      */
     seriesPalette() {
-        const cs = getComputedStyle(this);
-        const palette = [];
-        for (let i = 1; i <= FALLBACK_SERIES_PALETTE.length; i++) {
-            const value = cs.getPropertyValue(`--lr-color-chart-${i}`).trim();
-            if (value)
-                palette.push(value);
-        }
-        return palette.length ? palette : FALLBACK_SERIES_PALETTE;
+        return seriesPalette(this);
     }
-    tickOptions(theme) {
+    tickOptions(theme, kind = 'value') {
         return {
             color: theme.tick,
-            ...(this.valueFormatter
+            ...(this.valueFormatter && kind === 'value'
                 ? { callback: (value) => this.formatValue(value, 'tick') }
                 : {}),
         };
@@ -464,7 +687,7 @@ export class LyraChart extends LyraElement {
             return {
                 r: {
                     beginAtZero: this.beginAtZero,
-                    ticks: this.tickOptions(theme),
+                    ticks: { ...this.tickOptions(theme), showLabelBackdrop: false },
                     grid: { color: theme.grid },
                     angleLines: { color: theme.grid },
                     pointLabels: { color: theme.tick },
@@ -481,7 +704,7 @@ export class LyraChart extends LyraElement {
             x: {
                 type: effectiveType === 'scatter' || effectiveType === 'bubble' ? 'linear' : 'category',
                 title: { display: !!this.xLabel, text: this.xLabel, color: theme.tick },
-                ticks: this.tickOptions(theme),
+                ticks: this.tickOptions(theme, effectiveType === 'scatter' || effectiveType === 'bubble' ? 'value' : 'category'),
                 grid: { color: theme.grid },
                 stacked,
             },
@@ -530,7 +753,93 @@ export class LyraChart extends LyraElement {
         const { datasetIndex, index } = hit;
         const label = chart.data.labels?.[index];
         const value = chart.data.datasets[datasetIndex]?.data?.[index] ?? null;
-        this.emit('lr-point-click', { datasetIndex, index, label, value });
+        this.activateDatum({ datasetIndex, index, label, value });
+    }
+    chartDatums() {
+        const chartData = this.chart?.data;
+        const labels = chartData?.labels ?? this.labels;
+        const datasets = chartData?.datasets ??
+            this.datasets.map((series) => ({ data: series.points ?? series.data ?? [] }));
+        const datums = [];
+        datasets.forEach((dataset, datasetIndex) => {
+            const values = dataset.data ?? [];
+            values.forEach((value, index) => {
+                if (value == null)
+                    return;
+                if (typeof value === 'number' && !Number.isFinite(value))
+                    return;
+                datums.push({ datasetIndex, index, label: labels[index], value });
+            });
+        });
+        return datums;
+    }
+    datumDisplayValue(value) {
+        const numeric = typeof value === 'number'
+            ? value
+            : typeof value === 'object' && value !== null
+                ? Number(value.y ??
+                    value.r ??
+                    value.x)
+                : Number(value);
+        return Number.isFinite(numeric) ? getNumberFormat(this.effectiveLocale).format(numeric) : String(value);
+    }
+    datumAnnouncement(datum, position, total) {
+        const series = String(this.chart?.data?.datasets?.[datum.datasetIndex]?.label ?? this.datasets[datum.datasetIndex]?.label) ||
+            this.localize('chartSeriesLabel');
+        return this.localize('liteChartMarkSummary', undefined, {
+            series,
+            label: datum.label ??
+                this.localize('chartPointLabel', undefined, {
+                    n: getNumberFormat(this.effectiveLocale).format(datum.index + 1),
+                }),
+            value: this.datumDisplayValue(datum.value),
+            index: getNumberFormat(this.effectiveLocale).format(position + 1),
+            total: getNumberFormat(this.effectiveLocale).format(total),
+        });
+    }
+    activateDatum(datum) {
+        const datums = this.chartDatums();
+        const position = datums.findIndex((candidate) => candidate.datasetIndex === datum.datasetIndex && candidate.index === datum.index);
+        if (position >= 0) {
+            this.keyboardDatumIndex = position;
+            this.keyboardDatumAnnouncement = this.datumAnnouncement(datum, position, datums.length);
+        }
+        this.emit('lr-point-click', datum);
+    }
+    onCanvasFocus() {
+        const datums = this.chartDatums();
+        if (!datums.length)
+            return;
+        this.keyboardDatumIndex = Math.min(this.keyboardDatumIndex, datums.length - 1);
+        this.keyboardDatumAnnouncement = this.datumAnnouncement(datums[this.keyboardDatumIndex], this.keyboardDatumIndex, datums.length);
+    }
+    onCanvasKeyDown(event) {
+        const datums = this.chartDatums();
+        if (!datums.length)
+            return;
+        this.keyboardDatumIndex = Math.min(this.keyboardDatumIndex, datums.length - 1);
+        if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            this.activateDatum(datums[this.keyboardDatumIndex]);
+            return;
+        }
+        const rtl = this.effectiveDirection === 'rtl';
+        const forward = rtl ? 'ArrowLeft' : 'ArrowRight';
+        const backward = rtl ? 'ArrowRight' : 'ArrowLeft';
+        let next = this.keyboardDatumIndex;
+        if (event.key === forward || event.key === 'ArrowDown')
+            next = Math.min(datums.length - 1, next + 1);
+        else if (event.key === backward || event.key === 'ArrowUp')
+            next = Math.max(0, next - 1);
+        else if (event.key === 'Home')
+            next = 0;
+        else if (event.key === 'End')
+            next = datums.length - 1;
+        else
+            return;
+        event.preventDefault();
+        this.keyboardDatumIndex = next;
+        this.keyboardDatumAnnouncement = this.datumAnnouncement(datums[next], next, datums.length);
     }
     /**
      * `config.type` (if set) overrides the attribute `type` post-merge — this
@@ -577,7 +886,15 @@ export class LyraChart extends LyraElement {
         return labels.map((item) => {
             const value = this.legendValue(item, chart);
             const formatted = this.formatValue(value, 'legend');
-            return formatted === value || formatted === undefined ? item : { ...item, text: `${item.text}: ${formatted}` };
+            return formatted === value || formatted === undefined
+                ? item
+                : {
+                    ...item,
+                    text: this.localize('chartValueLabel', undefined, {
+                        label: String(item.text),
+                        value: String(formatted),
+                    }),
+                };
         });
     }
     tooltipLabel(context) {
@@ -586,7 +903,12 @@ export class LyraChart extends LyraElement {
         const formatted = this.formatValue(rawValue, 'tooltip');
         if (formatted === rawValue || formatted === undefined)
             return undefined;
-        return context.dataset?.label ? `${context.dataset.label}: ${formatted}` : String(formatted);
+        return context.dataset?.label
+            ? this.localize('chartValueLabel', undefined, {
+                label: String(context.dataset.label),
+                value: String(formatted),
+            })
+            : String(formatted);
     }
     updateAutoLegendPosition() {
         const width = this.getBoundingClientRect().width || this.clientWidth;
@@ -645,6 +967,13 @@ export class LyraChart extends LyraElement {
                 labels: this.labels,
                 datasets: this.datasets.map((s, i) => this.seriesToDataset(s, i, palette, effectiveType)),
             },
+            // `chartjs-plugin-datalabels` is registered PER-INSTANCE (only on charts
+            // that need it) rather than globally, because a global registration draws
+            // on — and breaks the next update of — every other chart on the page.
+            // Only added when the peer has actually loaded and the feature is on.
+            ...(this.needsDataLabels && this.dataLabelsPlugin
+                ? { plugins: [this.dataLabelsPlugin] }
+                : {}),
             options: {
                 locale: this.effectiveLocale,
                 responsive: true,
@@ -700,6 +1029,13 @@ export class LyraChart extends LyraElement {
                             limits: { x: { min: 'original', max: 'original' } },
                         }
                         : undefined,
+                    // `chartjs-plugin-datalabels`, once attached to a chart, draws on EVERY
+                    // dataset by default. This options block is ALWAYS present and defaults
+                    // `display: false` so that even a chart the plugin somehow reaches
+                    // (e.g. a consumer registering it globally themselves) stays inert
+                    // unless `data-labels`/`stack-totals` is set. This library attaches the
+                    // plugin per-instance (the `plugins` array above), never globally.
+                    datalabels: this.datalabelsOptions(theme, effectiveType),
                 },
                 onResize: (chart) => this.updateChartArea(chart),
                 scales: this.buildScales(effectiveType, theme),
@@ -712,7 +1048,18 @@ export class LyraChart extends LyraElement {
         // level (see `deepMerge` above), letting consumers override or extend a
         // single nested key (e.g. `config.options.scales.y.min`) without
         // clobbering the rest of the generated sibling object.
-        return deepMerge(generated, this.config);
+        const merged = deepMerge(generated, this.config);
+        // `deepMerge` replaces arrays wholesale, so a consumer `config.plugins`
+        // would drop the per-instance data-labels plugin the generated config added
+        // (silently disabling `data-labels`/`stack-totals`). Concatenate it back —
+        // the consumer's inline plugins AND the built-in data-labels plugin both run.
+        if (this.needsDataLabels && this.dataLabelsPlugin) {
+            const mergedPlugins = Array.isArray(merged.plugins) ? merged.plugins : [];
+            if (!mergedPlugins.includes(this.dataLabelsPlugin)) {
+                merged.plugins = [...mergedPlugins, this.dataLabelsPlugin];
+            }
+        }
+        return merged;
     }
     draw() {
         if (!this.chartJsModule || !this.canvasEl)
@@ -775,12 +1122,13 @@ export class LyraChart extends LyraElement {
     }
     /**
      * Forces a redraw so `themeColors()` re-reads the `--lr-chart-*` custom
-     * properties from the current computed style. No global theme-broadcast
-     * event exists anywhere in lyra-ui (nothing to subscribe to here) — this
-     * is the escape hatch for a consumer's own theme-toggle handler to call
-     * directly when it flips e.g. a `data-theme` attribute upstream that
-     * doesn't otherwise change any `lr-chart` property, so Lit's reactive
-     * update loop has nothing of its own to trigger `draw()` on.
+     * properties from the current computed style. A {@link ThemeWatcher} now
+     * calls this automatically when `prefers-color-scheme` flips or an ancestor's
+     * `class`/`style`/`data-theme`/`data-color-scheme` attribute mutates, so a
+     * consumer flipping an upstream theme attribute no longer has to. It remains
+     * public as the manual escape hatch for theme changes those signals can't
+     * observe (e.g. a same-attribute value swap the observer already covers is
+     * handled, but a fully out-of-band restyle is not).
      */
     refreshTheme() {
         this.draw();
@@ -818,7 +1166,7 @@ export class LyraChart extends LyraElement {
             }
             return this.localize('chartSummary', undefined, {
                 label: series.label,
-                count: values.length,
+                count: this.formatSummaryValue(values.length),
                 min: this.formatSummaryValue(min),
                 max: this.formatSummaryValue(max),
                 trend,
@@ -847,10 +1195,25 @@ export class LyraChart extends LyraElement {
         <tbody>
           ${Array.from({ length: rowCount }, (_, index) => html `
             <tr>
-              <th scope="row">${this.labels[index] ?? this.localize('chartPointLabel', undefined, { n: index + 1 })}</th>
-              ${this.datasets.map((series) => {
+              <th scope="row">${this.labels[index] ?? this.localize('chartPointLabel', undefined, {
+            n: this.formatSummaryValue(index + 1),
+        })}</th>
+              ${this.datasets.map((series, datasetIndex) => {
             const value = series.points ? series.points[index]?.y : series.data?.[index];
-            return html `<td>${value == null || !Number.isFinite(value) ? this.localize('noData') : value}</td>`;
+            if (value == null || !Number.isFinite(value)) {
+                return html `<td>${this.localize('noData')}</td>`;
+            }
+            const detail = {
+                datasetIndex,
+                index,
+                label: this.labels[index],
+                value: series.points?.[index] ?? value,
+            };
+            return html `<td><button
+                  type="button"
+                  tabindex=${this.showDataTable ? '0' : '-1'}
+                  @click=${() => this.activateDatum(detail)}
+                >${this.formatSummaryValue(value)}</button></td>`;
         })}
             </tr>
           `)}
@@ -858,6 +1221,9 @@ export class LyraChart extends LyraElement {
       </table>
     `;
     }
+    hasCustomDataTable() {
+        return Array.from(this.children).some((child) => child.getAttribute('slot') === 'data-table');
+    }
     render() {
         if (this.loading) {
             return html `
@@ -873,11 +1239,22 @@ export class LyraChart extends LyraElement {
         </div>
       `;
         }
-        const label = this.accessibleName(this.datasets.map((d) => d.label).join(', ') || this.localize('chart'));
+        const seriesLabels = this.datasets.map((d) => d.label);
+        const label = this.accessibleName((seriesLabels.length
+            ? getListFormat(this.effectiveLocale, { type: 'conjunction' }).format(seriesLabels)
+            : '') || this.localize('chart'));
         const description = this.chartDescription();
         return html `
       <div part="base">
-        <canvas part="canvas" role="img" aria-label=${label} aria-describedby=${this.descriptionId}></canvas>
+        <canvas
+          part="canvas"
+          role="img"
+          tabindex="0"
+          aria-label=${label}
+          aria-describedby="${this.descriptionId} ${this.datumStatusId}"
+          @focus=${this.onCanvasFocus}
+          @keydown=${this.onCanvasKeyDown}
+        ></canvas>
         <div
           part="center"
           style=${styleMap(this.resolvedChartArea
@@ -890,9 +1267,12 @@ export class LyraChart extends LyraElement {
           <slot name="center"></slot>
         </div>
         <p part="description" id=${this.descriptionId} class="sr-only">${description}</p>
+        <p id=${this.datumStatusId} class="sr-only" aria-live="polite">
+          ${this.keyboardDatumAnnouncement}
+        </p>
         <div part="data-table">
-          <slot name="data-table"></slot>
-          ${this.renderDataTable()}
+          <slot name="data-table" @slotchange=${() => this.requestUpdate()}></slot>
+          ${this.hasCustomDataTable() ? nothing : this.renderDataTable()}
         </div>
         ${this.zoom && this.zoomed
             ? html `<button part="reset-zoom-button" type="button" @click=${() => this.resetZoom()}>
@@ -957,6 +1337,12 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], LyraChart.prototype, "stacked", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'data-labels' })
+], LyraChart.prototype, "dataLabels", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'stack-totals' })
+], LyraChart.prototype, "stackTotals", void 0);
 __decorate([
     property({ attribute: false })
 ], LyraChart.prototype, "config", void 0);
@@ -978,6 +1364,9 @@ __decorate([
 __decorate([
     state()
 ], LyraChart.prototype, "autoLegendPosition", void 0);
+__decorate([
+    state()
+], LyraChart.prototype, "keyboardDatumAnnouncement", void 0);
 /**
  * Installs a read-only `type` accessor pair on a `LyraChart` subclass's
  * prototype, locking it to `value` — assigning `.type` afterwards (attribute