@aceshooting/lyra-ui 7.6.0 → 7.7.0

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

@@ -99,6 +99,18 @@ function deepMerge(base, override, seen = new WeakMap()) {
     }
     return result;
 }
+function isChartPoint(value) {
+    if (!isPlainObject(value))
+        return false;
+    return Number.isFinite(value['x']) && Number.isFinite(value['y']);
+}
+function labelText(value) {
+    if (value == null)
+        return '';
+    if (Array.isArray(value))
+        return value.map(labelText).join(' ');
+    return String(value);
+}
 /**
  * `<lr-chart>` — the core Chart.js wrapper every other `lr-*-chart` tag
  * subclasses. Requires the optional peer dep `chart.js`; `chartjs-plugin-zoom`
@@ -125,19 +137,23 @@ function deepMerge(base, override, seen = new WeakMap()) {
  * @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 }`.
+ *   undefined, value: unknown }`. For scatter/bubble data, `label` prefers the per-point label and
+ *   `value` is the complete typed `ChartPoint` (`x`, `y`, optional `r`, optional `label`).
  * @csspart base - The chart wrapper.
+ * @csspart plot - The fixed-height canvas/overlay region.
  * @csspart canvas - The Chart.js canvas.
+ * @csspart legend - The wrapping DOM legend rendered when `legend` is set.
+ * @csspart legend-item - A keyboard-operable series visibility toggle.
+ * @csspart legend-swatch - The resolved series-color swatch in a legend item.
  * @csspart reset-zoom-button - The reset-zoom control when zoom is active.
  * @csspart description - The accessible chart summary.
  * @csspart data-table - The optional generated or slotted data table.
  * @csspart center - The chart-area-centered overlay wrapper for the `center` slot.
  * @csspart error - `role="alert"` message shown instead of `canvas` when the optional `chart.js`
  *   peer dependency is not installed.
- * @cssprop [--lr-chart-height=var(--lr-size-280px)] - The host's `block-size`. Set on the host
- *   element from the `height` property on every change (custom properties only cascade downward,
- *   so it cannot be set from inside the shadow root); a host-level override is overwritten the
- *   next time `height` changes.
+ * @cssprop [--lr-chart-height=var(--lr-size-280px)] - The plot region's `block-size` and the
+ *   host's minimum block size. A visible data table or wrapping DOM legend grows the host in
+ *   normal flow instead of overlapping following content. Set on the host from `height`.
  * @cssprop [--lr-chart-grid-color=var(--lr-color-border)] - Grid-line color. Resolved via
  *   `getComputedStyle` on every draw (Chart.js paints to canvas and cannot consume `var()`).
  * @cssprop [--lr-chart-tick-color=var(--lr-color-text-quiet)] - Axis tick-label color; also used
@@ -240,13 +256,91 @@ export class LyraChart extends LyraElement {
                 this.refreshTheme();
         });
     }
+    /**
+     * The single data model used by every chart surface. `config.data` follows the same merge rule
+     * as the Chart.js render config: an explicit labels/datasets array replaces the generated array,
+     * while an omitted member falls back to the simplified property surface.
+     */
+    effectiveData() {
+        const generated = {
+            labels: this.labels,
+            datasets: this.datasets.map((series) => ({
+                ...series,
+                data: series.points ?? series.data ?? [],
+                yAxisID: series.axis === 'y2' ? 'y2' : 'y',
+            })),
+        };
+        const override = this.config?.data;
+        const merged = isPlainObject(override)
+            ? deepMerge(generated, override)
+            : generated;
+        return {
+            labels: Array.isArray(merged.labels) ? merged.labels : [],
+            datasets: Array.isArray(merged.datasets)
+                ? merged.datasets.filter(isPlainObject)
+                : [],
+        };
+    }
+    hasExplicitConfigData() {
+        return isPlainObject(this.config) && Object.prototype.hasOwnProperty.call(this.config, 'data');
+    }
+    datasetLabel(dataset, index) {
+        return labelText(dataset.label) || this.localize('chartPointLabel', undefined, {
+            n: getNumberFormat(this.effectiveLocale).format(index + 1),
+        });
+    }
+    datasetValues(dataset) {
+        return Array.isArray(dataset.data) ? dataset.data : [];
+    }
+    isPointDataset(dataset) {
+        const values = this.datasetValues(dataset);
+        return (this.effectiveType() === 'scatter' ||
+            this.effectiveType() === 'bubble' ||
+            values.some(isChartPoint));
+    }
     /**
      * 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.
+     * `maxPoints` categories. An explicitly supplied `config.data` member is updated at that same
+     * source; generated members continue to update `labels`/`datasets`, preserving generated styling.
+     * Point-based scatter/bubble series are left unchanged because their x/y/r 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;
+        if (this.hasExplicitConfigData()) {
+            const effective = this.effectiveData();
+            const labels = [...effective.labels, label];
+            const currentData = isPlainObject(this.config?.data) ? this.config.data : {};
+            const explicitLabels = Array.isArray(currentData['labels']);
+            const explicitDatasets = Array.isArray(currentData['datasets']);
+            const nextLabels = limit > 0 ? labels.slice(-limit) : labels;
+            if (!explicitLabels)
+                this.labels = nextLabels.map(labelText);
+            if (!explicitDatasets) {
+                const datasets = this.datasets.map((series, index) => {
+                    if (series.points)
+                        return series;
+                    const data = [...(series.data ?? []), values[index] ?? null];
+                    return { ...series, data: limit > 0 ? data.slice(-limit) : data };
+                });
+                this.datasets = datasets;
+            }
+            if (explicitLabels || explicitDatasets) {
+                const nextData = { ...currentData };
+                if (explicitLabels)
+                    nextData['labels'] = nextLabels;
+                if (explicitDatasets) {
+                    nextData['datasets'] = effective.datasets.map((dataset, index) => {
+                        if (this.isPointDataset(dataset))
+                            return dataset;
+                        const data = [...this.datasetValues(dataset), values[index] ?? null];
+                        return { ...dataset, data: limit > 0 ? data.slice(-limit) : data };
+                    });
+                }
+                this.config = { ...this.config, data: nextData };
+            }
+            return;
+        }
         const labels = [...this.labels, label];
         const datasets = this.datasets.map((series, index) => series.points
             ? series
@@ -256,23 +350,83 @@ export class LyraChart extends LyraElement {
             ? 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. */
+    /**
+     * Returns a spreadsheet-safe CSV snapshot of the effective chart data. Point datasets expand to
+     * x/y and, when present, radius/per-point-label columns so export never flattens point meaning.
+     */
     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(','));
+        const effective = this.effectiveData();
+        const columns = effective.datasets.map((dataset, datasetIndex) => {
+            const values = this.datasetValues(dataset);
+            const label = this.datasetLabel(dataset, datasetIndex);
+            const points = values.filter(isChartPoint);
+            return {
+                dataset,
+                label,
+                point: this.isPointDataset(dataset),
+                radius: points.some((point) => point.r != null),
+                pointLabel: points.some((point) => point.label != null),
+            };
+        });
+        const header = [
+            'label',
+            ...columns.flatMap((column) => column.point
+                ? [
+                    `${column.label} x`,
+                    `${column.label} y`,
+                    ...(column.radius ? [`${column.label} r`] : []),
+                    ...(column.pointLabel ? [`${column.label} label`] : []),
+                ]
+                : [column.label]),
+        ].map(escapeCsvField).join(',');
+        const rowCount = Math.max(effective.labels.length, ...effective.datasets.map((dataset) => this.datasetValues(dataset).length), 0);
+        const rows = Array.from({ length: rowCount }, (_, index) => {
+            const firstPoint = effective.datasets
+                .map((dataset) => this.datasetValues(dataset)[index])
+                .find(isChartPoint);
+            const label = labelText(effective.labels[index]) || firstPoint?.label || '';
+            return [
+                label,
+                ...columns.flatMap((column) => {
+                    const value = this.datasetValues(column.dataset)[index];
+                    if (!column.point)
+                        return [value ?? ''];
+                    if (!isChartPoint(value)) {
+                        return ['', '', ...(column.radius ? [''] : []), ...(column.pointLabel ? [''] : [])];
+                    }
+                    return [
+                        value.x,
+                        value.y,
+                        ...(column.radius ? [value.r ?? ''] : []),
+                        ...(column.pointLabel ? [value.label ?? ''] : []),
+                    ];
+                }),
+            ].map(escapeCsvField).join(',');
+        });
         return [header, ...rows].join('\r\n');
     }
     connectedCallback() {
         super.connectedCallback();
         if (typeof ResizeObserver !== 'undefined') {
-            this.resizeObserver = new ResizeObserver(() => {
-                this.updateAutoLegendPosition();
-                this.draw();
+            this.resizeObserver = new ResizeObserver((entries) => {
+                const width = entries[0]?.contentRect.width ?? this.getBoundingClientRect().width;
+                if (Number.isFinite(width) &&
+                    this.lastObservedInlineSize !== undefined &&
+                    Math.abs(width - this.lastObservedInlineSize) < 0.5) {
+                    return;
+                }
+                this.lastObservedInlineSize = width;
+                if (this.resizeDrawFrame !== undefined)
+                    return;
+                this.resizeDrawFrame = requestAnimationFrame(() => {
+                    this.resizeDrawFrame = undefined;
+                    // A changed auto position schedules the same visibility-gated draw through `updated()`.
+                    // Avoid drawing once here and again in that reactive pass.
+                    if (!this.updateAutoLegendPosition())
+                        this.drawIfVisible();
+                });
             });
             this.resizeObserver.observe(this);
         }
@@ -289,7 +443,7 @@ export class LyraChart extends LyraElement {
             }
             this.loadFailed = false;
             this.chartJsModule = mod;
-            this.draw();
+            this.drawIfVisible();
         });
         // `data-labels`/`stack-totals` need the optional `chartjs-plugin-datalabels`
         // peer registered before the plugin's `datalabels` options in `buildConfig()`
@@ -310,7 +464,7 @@ export class LyraChart extends LyraElement {
                 const wasVisible = this.visible;
                 this.visible = entries[0]?.isIntersecting ?? true;
                 if (this.visible && !wasVisible)
-                    this.draw();
+                    this.drawIfVisible();
             });
             this.intersectionObserver.observe(this);
         }
@@ -319,6 +473,10 @@ export class LyraChart extends LyraElement {
         super.disconnectedCallback();
         this.resizeObserver?.disconnect();
         this.resizeObserver = undefined;
+        if (this.resizeDrawFrame !== undefined)
+            cancelAnimationFrame(this.resizeDrawFrame);
+        this.resizeDrawFrame = undefined;
+        this.lastObservedInlineSize = undefined;
         this.loadGeneration += 1;
         this.zoomLoadGeneration += 1;
         this.dataLabelsLoadGeneration += 1;
@@ -338,6 +496,7 @@ export class LyraChart extends LyraElement {
      */
     applyDataLabelsPlugin(plugin) {
         this.dataLabelsPlugin = plugin;
+        let rebuilt = false;
         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
@@ -345,8 +504,14 @@ export class LyraChart extends LyraElement {
             this.chart.destroy();
             this.chart = undefined;
             this.builtType = undefined;
+            rebuilt = true;
         }
-        this.draw();
+        this.drawIfVisible();
+        // A rebuild resets Chart.js's per-instance visibility metadata to the configured `hidden`
+        // flags. Nothing reactive changes after the async plugin resolves, so refresh the DOM legend
+        // explicitly instead of leaving its pre-rebuild aria-pressed state stale.
+        if (rebuilt && this.legend)
+            this.requestUpdate();
     }
     /**
      * Resets a stale `zoomed` flag before the render pass that's about to call
@@ -385,11 +550,8 @@ export class LyraChart extends LyraElement {
         // its own load/draw sequence, so nothing is lost by bailing out here.
         if (!this.isConnected)
             return;
-        if (this.loading)
-            this.setAttribute('aria-busy', 'true');
-        else
-            this.removeAttribute('aria-busy');
-        // `--lr-chart-height` is read by `:host`'s `block-size` in
+        this.setAttribute('aria-busy', String(this.loading));
+        // `--lr-chart-height` is read by the plot region and host minimum size in
         // `chart.styles.ts`. Custom properties only cascade downward (host ->
         // shadow tree), never upward from a shadow-tree descendant back to the
         // host, so this must be set on the host element itself, not on the
@@ -419,7 +581,7 @@ export class LyraChart extends LyraElement {
                 void loadChartJsWithZoom().then(() => {
                     if (zoomGeneration !== this.zoomLoadGeneration || !this.isConnected || !this.zoom)
                         return;
-                    this.draw();
+                    this.drawIfVisible();
                 });
             }
         }
@@ -435,7 +597,29 @@ export class LyraChart extends LyraElement {
                 this.applyDataLabelsPlugin(result?.plugin);
             });
         }
-        const contentChanged = [
+        const contentChanged = this.chartContentChanged(changed);
+        // `this.locale`/`this.strings` above only catch an explicit property write on this element
+        // itself -- an inherited `dir`/`lang` flip on an ancestor changes `effectiveDirection()`/
+        // `effectiveLocale()` (which `buildScales()`/`buildConfig()` read directly) without touching
+        // any tracked property here, so it has to be detected by comparing against what was actually
+        // last drawn instead.
+        const effectiveDirection = this.effectiveDirection;
+        const effectiveLocale = this.effectiveLocale;
+        const contextChanged = (this.lastDrawnDirection !== undefined && this.lastDrawnDirection !== effectiveDirection) ||
+            (this.lastDrawnLocale !== undefined && this.lastDrawnLocale !== effectiveLocale);
+        this.lastDrawnDirection = effectiveDirection;
+        this.lastDrawnLocale = effectiveLocale;
+        if (!contentChanged && !contextChanged)
+            return;
+        this.drawIfVisible();
+    }
+    /**
+     * Subclass extension point for derived reactive inputs. Keeping this gate in the normal
+     * visibility-checked update path prevents subclasses such as histogram from issuing a second,
+     * unconditional post-update redraw.
+     */
+    chartContentChanged(changed) {
+        return [
             'type',
             'labels',
             'datasets',
@@ -459,22 +643,6 @@ export class LyraChart extends LyraElement {
             'strings',
             'loading',
         ].some((name) => changed.has(name));
-        // `this.locale`/`this.strings` above only catch an explicit property write on this element
-        // itself -- an inherited `dir`/`lang` flip on an ancestor changes `effectiveDirection()`/
-        // `effectiveLocale()` (which `buildScales()`/`buildConfig()` read directly) without touching
-        // any tracked property here, so it has to be detected by comparing against what was actually
-        // last drawn instead.
-        const effectiveDirection = this.effectiveDirection;
-        const effectiveLocale = this.effectiveLocale;
-        const contextChanged = (this.lastDrawnDirection !== undefined && this.lastDrawnDirection !== effectiveDirection) ||
-            (this.lastDrawnLocale !== undefined && this.lastDrawnLocale !== effectiveLocale);
-        this.lastDrawnDirection = effectiveDirection;
-        this.lastDrawnLocale = effectiveLocale;
-        if (!contentChanged && !contextChanged)
-            return;
-        if (!this.visible)
-            return; // becoming visible again triggers its own draw() via the observer above
-        this.draw();
     }
     seriesToDataset(s, index, palette, effectiveType) {
         const colors = Array.isArray(s.color)
@@ -578,11 +746,12 @@ export class LyraChart extends LyraElement {
     datalabelsOptions(theme, effectiveType) {
         if (!this.needsDataLabels)
             return { display: false };
+        const datasets = this.effectiveData().datasets;
         const stackTotalsActive = this.stackTotals && this.stacked && (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));
+            datasets.forEach((dataset, index) => topDatasetIndexByAxis.set(dataset.yAxisID === 'y2' || dataset.axis === 'y2' ? 'y2' : 'y', index));
         }
         const totalsByAxis = stackTotalsActive
             ? { y: this.computeStackTotals('y'), y2: this.computeStackTotals('y2') }
@@ -594,7 +763,8 @@ export class LyraChart extends LyraElement {
             anchor: stackTotalsActive ? 'end' : 'center',
             display: (context) => {
                 const datasetIndex = context.datasetIndex;
-                const axis = this.datasets[datasetIndex]?.axis === 'y2' ? 'y2' : 'y';
+                const dataset = datasets[datasetIndex];
+                const axis = dataset?.yAxisID === 'y2' || dataset?.axis === 'y2' ? 'y2' : 'y';
                 if (stackTotalsActive) {
                     // Only the topmost dataset of each axis draws, and only where the
                     // category total is non-null.
@@ -609,7 +779,8 @@ export class LyraChart extends LyraElement {
             },
             formatter: (value, context) => {
                 const datasetIndex = context.datasetIndex;
-                const axis = this.datasets[datasetIndex]?.axis === 'y2' ? 'y2' : 'y';
+                const dataset = datasets[datasetIndex];
+                const axis = dataset?.yAxisID === 'y2' || dataset?.axis === 'y2' ? 'y2' : 'y';
                 if (stackTotalsActive && topDatasetIndexByAxis.get(axis) === datasetIndex) {
                     const total = totalsByAxis?.[axis][context.dataIndex];
                     if (total != null)
@@ -643,17 +814,19 @@ export class LyraChart extends LyraElement {
      * 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 effective = this.effectiveData();
+        const members = effective.datasets.filter((dataset) => (dataset.yAxisID === 'y2' || dataset.axis === 'y2' ? 'y2' : 'y') === axisId);
+        const categoryCount = members.reduce((max, dataset) => Math.max(max, this.datasetValues(dataset).length), effective.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))
+            for (const dataset of members) {
+                const value = this.datasetValues(dataset)[i];
+                const numeric = isChartPoint(value) ? value.y : value;
+                if (numeric == null || !Number.isFinite(numeric))
                     continue;
-                sum += raw;
+                sum += numeric;
                 any = true;
             }
             totals.push(any ? sum : null);
@@ -711,7 +884,7 @@ export class LyraChart extends LyraElement {
                 },
             };
         }
-        const hasY2 = this.datasets.some((s) => s.axis === 'y2');
+        const hasY2 = this.effectiveData().datasets.some((dataset) => dataset.yAxisID === 'y2' || dataset.axis === 'y2');
         const rtl = this.effectiveDirection === 'rtl';
         // `stacked` only applies to bar/line-family charts sharing a categorical
         // axis, per the design spec — scatter/bubble's linear x scale and the
@@ -768,8 +941,10 @@ export class LyraChart extends LyraElement {
         if (!hit)
             return;
         const { datasetIndex, index } = hit;
-        const label = chart.data.labels?.[index];
         const value = chart.data.datasets[datasetIndex]?.data?.[index] ?? null;
+        const label = isChartPoint(value) && value.label !== undefined
+            ? value.label
+            : labelText(chart.data.labels?.[index]) || undefined;
         this.activateDatum({ datasetIndex, index, label, value });
     }
     chartDatums() {
@@ -785,12 +960,28 @@ export class LyraChart extends LyraElement {
                     return;
                 if (typeof value === 'number' && !Number.isFinite(value))
                     return;
-                datums.push({ datasetIndex, index, label: labels[index], value });
+                datums.push({
+                    datasetIndex,
+                    index,
+                    label: isChartPoint(value) && value.label !== undefined
+                        ? value.label
+                        : labelText(labels[index]) || undefined,
+                    value,
+                });
             });
         });
         return datums;
     }
     datumDisplayValue(value) {
+        if (isChartPoint(value)) {
+            const numberFormat = getNumberFormat(this.effectiveLocale);
+            const coordinates = [
+                `x=${numberFormat.format(value.x)}`,
+                `y=${numberFormat.format(value.y)}`,
+                ...(value.r == null ? [] : [`r=${numberFormat.format(value.r)}`]),
+            ].join(', ');
+            return value.label ? `${value.label} (${coordinates})` : coordinates;
+        }
         const numeric = typeof value === 'number'
             ? value
             : typeof value === 'object' && value !== null
@@ -930,8 +1121,10 @@ export class LyraChart extends LyraElement {
     updateAutoLegendPosition() {
         const width = this.getBoundingClientRect().width || this.clientWidth;
         const next = width > 0 && width < 480 ? 'bottom' : 'right';
-        if (next !== this.autoLegendPosition)
-            this.autoLegendPosition = next;
+        if (next === this.autoLegendPosition)
+            return false;
+        this.autoLegendPosition = next;
+        return true;
     }
     legendPositionForConfig() {
         return this.legendPosition === 'auto' ? this.autoLegendPosition : this.legendPosition;
@@ -1009,7 +1202,9 @@ export class LyraChart extends LyraElement {
                 onClick: (event, _elements, chart) => this.handlePointClick(event, chart),
                 plugins: {
                     legend: {
-                        display: this.legend,
+                        // A canvas legend cannot wrap one long public label; the DOM legend rendered below
+                        // preserves the full text, normal-flow containment, keyboard access, and toggling.
+                        display: false,
                         position: this.legendPositionForConfig(),
                         labels: {
                             color: theme.legend,
@@ -1026,7 +1221,7 @@ export class LyraChart extends LyraElement {
                         // Chart.js's tooltip plugin has no per-dataset `tooltip.enabled`
                         // — `Series.noTooltip` is implemented here instead, via the one
                         // mechanism the core tooltip plugin actually reads.
-                        filter: (item) => !this.datasets[item.datasetIndex]?.noTooltip,
+                        filter: (item) => !this.effectiveData().datasets[item.datasetIndex]?.noTooltip,
                     },
                     zoom: this.zoom
                         ? {
@@ -1084,39 +1279,40 @@ export class LyraChart extends LyraElement {
         const config = this.buildConfig();
         const effectiveType = config.type;
         if (this.chart && this.builtType === effectiveType) {
-            // Chart.js tracks per-dataset legend-toggled visibility by dataset INDEX against its own
-            // internal metadata, separate from `chart.data.datasets` itself -- a full reassignment of
-            // `chart.data` on every reactive update (as every live-polling consumer's parent naturally
-            // produces) would otherwise silently reset every hidden series back to visible.
+            // Chart.js tracks per-dataset legend-toggled visibility by dataset INDEX as a nullable
+            // metadata override, separate from each dataset's configured `hidden` value -- a full
+            // reassignment of `chart.data` on every reactive update (as every live-polling consumer's
+            // parent naturally produces) would otherwise silently reset an explicit legend choice.
             // Only snapshot indices the chart already has metadata for -- `this.datasets` reflects the
             // *new* series count, so mapping over it (instead of the chart's own prior dataset count)
-            // would query isDatasetVisible() for a not-yet-existing index, get back its "not explicitly
-            // visible" default, and then setDatasetVisibility(i, false) below would enforce that default
-            // as a real hidden state -- permanently hiding a series the moment it's added.
+            // would query metadata for a not-yet-existing index and fabricate state for a series that
+            // has not been added yet.
             const priorDatasetCount = this.chart.data.datasets?.length ?? 0;
-            const priorVisibility = Array.from({ length: priorDatasetCount }, (_, i) => this.chart.isDatasetVisible(i));
+            const priorVisibilityOverrides = Array.from({ length: priorDatasetCount }, (_, i) => this.chart.getDatasetMeta(i).hidden);
             this.chart.data = config.data;
             this.chart.options = config.options ?? {};
             this.chart.update('none');
             this.updateChartArea(this.chart);
-            // The mirror-image guard of the one above: a shrinking update can leave `priorVisibility`
-            // longer than the new dataset list, and Chart.js fabricates metadata for an out-of-range index
-            // instead of throwing -- skip any index the shrunk list no longer has instead of polluting
-            // internal per-dataset state for a series that's gone.
+            // The mirror-image guard of the one above: a shrinking update can leave the prior override
+            // list longer than the new dataset list, and Chart.js fabricates metadata for an out-of-range
+            // index instead of throwing -- skip any index the shrunk list no longer has instead of
+            // polluting internal per-dataset state for a series that's gone.
             const currentDatasetCount = this.chart.data.datasets?.length ?? 0;
-            let restoredHiddenState = false;
-            priorVisibility.forEach((visible, i) => {
+            let restoredVisibilityOverride = false;
+            priorVisibilityOverrides.forEach((hidden, i) => {
                 if (i >= currentDatasetCount)
                     return;
-                if (!visible) {
-                    this.chart.setDatasetVisibility(i, false);
-                    restoredHiddenState = true;
+                // `null` means there was no user override: the replacement dataset's own `hidden`
+                // configuration must win. Boolean metadata represents an explicit legend show/hide.
+                if (typeof hidden === 'boolean') {
+                    this.chart.setDatasetVisibility(i, !hidden);
+                    restoredVisibilityOverride = true;
                 }
             });
             // setDatasetVisibility() only flips internal metadata -- it does not repaint on its own (unlike
             // hide()/show()) -- so without a follow-up update() the canvas would keep showing the series as
             // visible until some unrelated future draw() call happens to run.
-            if (restoredHiddenState)
+            if (restoredVisibilityOverride)
                 this.chart.update('none');
             return;
         }
@@ -1125,6 +1321,11 @@ export class LyraChart extends LyraElement {
         this.builtType = effectiveType;
         this.updateChartArea(this.chart);
     }
+    drawIfVisible() {
+        if (!this.isConnected || !this.visible)
+            return;
+        this.draw();
+    }
     /** Reset any active zoom/pan back to the original view. */
     resetZoom() {
         this.suppressZoomComplete = true;
@@ -1148,12 +1349,16 @@ export class LyraChart extends LyraElement {
      * handled, but a fully out-of-band restyle is not).
      */
     refreshTheme() {
-        this.draw();
+        this.drawIfVisible();
+        // The wrapping DOM legend carries a concrete, computed swatch color too; refresh its
+        // template without turning the resulting empty-property update into another canvas draw.
+        if (this.legend)
+            this.requestUpdate();
     }
-    seriesValues(series) {
-        if (series.points)
-            return series.points.map((point) => point.y).filter((value) => Number.isFinite(value));
-        return (series.data ?? []).filter((value) => value != null && Number.isFinite(value));
+    seriesValues(dataset) {
+        return this.datasetValues(dataset)
+            .map((value) => isChartPoint(value) ? value.y : value)
+            .filter((value) => typeof value === 'number' && Number.isFinite(value));
     }
     formatSummaryValue(value) {
         return getNumberFormat(this.effectiveLocale).format(value);
@@ -1162,9 +1367,10 @@ export class LyraChart extends LyraElement {
         return this.valueFormatter?.(value, 'table') ?? this.formatSummaryValue(value);
     }
     tableStackAxes() {
-        if (!this.stackTotals || !this.stacked || (this.type !== 'bar' && this.type !== 'line'))
+        const type = this.effectiveType();
+        if (!this.stackTotals || !this.stacked || (type !== 'bar' && type !== 'line'))
             return [];
-        const present = new Set(this.datasets.map((series) => (series.axis === 'y2' ? 'y2' : 'y')));
+        const present = new Set(this.effectiveData().datasets.map((dataset) => dataset.yAxisID === 'y2' || dataset.axis === 'y2' ? 'y2' : 'y'));
         return ['y', 'y2'].filter((axis) => present.has(axis));
     }
     tableStackTotalLabel(axis, axisCount) {
@@ -1181,10 +1387,12 @@ export class LyraChart extends LyraElement {
     chartDescription() {
         if (this.accessibleDescription)
             return this.accessibleDescription;
-        const summaries = this.datasets.map((series) => {
-            const values = this.seriesValues(series);
+        const datasets = this.effectiveData().datasets;
+        const summaries = datasets.map((dataset, index) => {
+            const seriesLabel = this.datasetLabel(dataset, index);
+            const values = this.seriesValues(dataset);
             if (!values.length)
-                return this.localize('chartSeriesNoData', undefined, { label: series.label });
+                return this.localize('chartSeriesNoData', undefined, { label: seriesLabel });
             const first = values[0];
             const last = values[values.length - 1];
             const trend = last > first
@@ -1198,13 +1406,19 @@ export class LyraChart extends LyraElement {
                 min = Math.min(min, value);
                 max = Math.max(max, value);
             }
-            return this.localize('chartSummary', undefined, {
-                label: series.label,
+            const summary = this.localize('chartSummary', undefined, {
+                label: seriesLabel,
                 count: this.formatSummaryValue(values.length),
                 min: this.formatSummaryValue(min),
                 max: this.formatSummaryValue(max),
                 trend,
             });
+            const pointDetails = this.datasetValues(dataset)
+                .filter(isChartPoint)
+                .map((point) => this.datumDisplayValue(point));
+            return pointDetails.length
+                ? [summary, ...pointDetails].join(this.localize('chartSummarySeparator'))
+                : summary;
         });
         return summaries.length
             ? this.localize('chartSummaryWithData', undefined, {
@@ -1216,7 +1430,8 @@ export class LyraChart extends LyraElement {
             : this.localize('chartSummaryEmpty', undefined, { type: this.localizedChartType() });
     }
     renderDataTable() {
-        const rowCount = Math.max(this.labels.length, ...this.datasets.map((series) => (series.points ? series.points.length : series.data?.length ?? 0)), 0);
+        const effective = this.effectiveData();
+        const rowCount = Math.max(effective.labels.length, ...effective.datasets.map((dataset) => this.datasetValues(dataset).length), 0);
         const stackAxes = this.tableStackAxes();
         const stackTotals = new Map(stackAxes.map((axis) => [axis, this.computeStackTotals(axis)]));
         return html `
@@ -1225,32 +1440,41 @@ export class LyraChart extends LyraElement {
         <thead>
           <tr>
             <th scope="col">${this.localize('chartCategory')}</th>
-            ${this.datasets.map((series) => html `<th scope="col">${series.label}</th>`)}
+            ${effective.datasets.map((dataset, index) => html `<th scope="col">${this.datasetLabel(dataset, index)}</th>`)}
             ${stackAxes.map((axis) => html `<th scope="col">${this.tableStackTotalLabel(axis, stackAxes.length)}</th>`)}
           </tr>
         </thead>
         <tbody>
           ${Array.from({ length: rowCount }, (_, index) => html `
             <tr>
-              <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];
-            if (value == null || !Number.isFinite(value)) {
+              <th scope="row">${labelText(effective.labels[index]) ||
+            effective.datasets
+                .map((dataset) => this.datasetValues(dataset)[index])
+                .find(isChartPoint)?.label ||
+            this.localize('chartPointLabel', undefined, {
+                n: this.formatSummaryValue(index + 1),
+            })}</th>
+              ${effective.datasets.map((dataset, datasetIndex) => {
+            const datum = this.datasetValues(dataset)[index];
+            const value = isChartPoint(datum) ? datum.y : datum;
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
                 return html `<td>${this.localize('noData')}</td>`;
             }
             const detail = {
                 datasetIndex,
                 index,
-                label: this.labels[index],
-                value: series.points?.[index] ?? value,
+                label: isChartPoint(datum) && datum.label !== undefined
+                    ? datum.label
+                    : labelText(effective.labels[index]) || undefined,
+                value: datum,
             };
             return html `<td><button
                   type="button"
                   tabindex=${this.showDataTable ? '0' : '-1'}
                   @click=${() => this.activateDatum(detail)}
-                >${this.formatTableValue(value)}</button></td>`;
+                >${isChartPoint(datum)
+                ? this.datumDisplayValue(datum)
+                : this.formatTableValue(value)}</button></td>`;
         })}
               ${stackAxes.map((axis) => {
             const total = stackTotals.get(axis)?.[index];
@@ -1267,6 +1491,88 @@ export class LyraChart extends LyraElement {
     hasCustomDataTable() {
         return Array.from(this.children).some((child) => child.getAttribute('slot') === 'data-table');
     }
+    legendTextFor(dataset, datasetIndex) {
+        const label = this.datasetLabel(dataset, datasetIndex);
+        if (!this.valueFormatter)
+            return label;
+        const values = this.datasetValues(dataset)
+            .map((value) => isChartPoint(value) ? value.y : Number(value))
+            .filter(Number.isFinite);
+        if (!values.length)
+            return label;
+        const value = values.reduce((sum, item) => sum + item, 0);
+        const formatted = this.formatValue(value, 'legend');
+        return formatted === value || formatted === undefined
+            ? label
+            : this.localize('chartValueLabel', undefined, {
+                label,
+                value: String(formatted),
+            });
+    }
+    legendColor(dataset, datasetIndex) {
+        const palette = this.seriesPalette();
+        const fallback = palette[datasetIndex % palette.length] ?? 'transparent';
+        const rawCandidate = dataset.backgroundColor ?? dataset.borderColor ?? dataset.color;
+        const candidate = Array.isArray(rawCandidate) ? rawCandidate[0] : rawCandidate;
+        return typeof candidate === 'string'
+            ? resolveCanvasColor(this, candidate, fallback)
+            : fallback;
+    }
+    toggleDataset(datasetIndex) {
+        if (!this.chart)
+            return;
+        const visible = this.chart.isDatasetVisible(datasetIndex);
+        this.chart.setDatasetVisibility(datasetIndex, !visible);
+        this.chart.update('none');
+        this.requestUpdate();
+    }
+    legendDatasetVisible(dataset, datasetIndex) {
+        const configuredVisible = dataset.hidden !== true;
+        // With no instance, or when the upcoming draw must replace it for a new effective type, the
+        // new Chart.js metadata will derive visibility directly from the effective dataset.
+        if (!this.chart || this.builtType !== this.effectiveType())
+            return configuredVisible;
+        const renderedDatasetCount = this.chart.data.datasets?.length ?? 0;
+        if (datasetIndex >= renderedDatasetCount)
+            return configuredVisible;
+        // An explicit legend toggle lives on Chart.js metadata and survives the in-place draw path.
+        // Without one, the upcoming dataset's own `hidden` flag is the post-draw source of truth.
+        const metadata = this.chart.getDatasetMeta?.(datasetIndex);
+        return typeof metadata?.hidden === 'boolean'
+            ? this.chart.isDatasetVisible(datasetIndex)
+            : configuredVisible;
+    }
+    renderLegend() {
+        if (!this.legend)
+            return nothing;
+        const effective = this.effectiveData();
+        return html `
+      <div
+        part="legend"
+        role="group"
+        data-position=${this.legendPositionForConfig()}
+        aria-label=${this.accessibleName(this.localize('chart'))}
+      >
+        ${effective.datasets.map((dataset, index) => {
+            const visible = this.legendDatasetVisible(dataset, index);
+            return html `
+            <button
+              part="legend-item"
+              type="button"
+              aria-pressed=${visible ? 'true' : 'false'}
+              @click=${() => this.toggleDataset(index)}
+            >
+              <span
+                part="legend-swatch"
+                style="background-color:${this.legendColor(dataset, index)}"
+              ></span>
+              <span>${this.legendTextFor(dataset, index)}</span>
+            </button>
+          `;
+        })}
+      </div>
+    `;
+    }
     render() {
         if (this.loading) {
             return html `
@@ -1282,33 +1588,46 @@ export class LyraChart extends LyraElement {
         </div>
       `;
         }
-        const seriesLabels = this.datasets.map((d) => d.label);
+        const effective = this.effectiveData();
+        const seriesLabels = effective.datasets.map((dataset, index) => this.datasetLabel(dataset, index));
         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"
-          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
+      <div
+        part="base"
+        data-legend-position=${this.legend ? this.legendPositionForConfig() : nothing}
+      >
+        <div part="plot">
+          <canvas
+            part="canvas"
+            role="application"
+            aria-roledescription=${this.localize('chart')}
+            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
             ? {
                 left: `${this.resolvedChartArea.left + this.resolvedChartArea.width / 2}px`,
                 top: `${this.resolvedChartArea.top + this.resolvedChartArea.height / 2}px`,
             }
             : { left: '50%', top: '50%' })}
-        >
-          <slot name="center"></slot>
+          >
+            <slot name="center"></slot>
+          </div>
+          ${this.zoom && this.zoomed
+            ? html `<button part="reset-zoom-button" type="button" @click=${() => this.resetZoom()}>
+                ${this.localize('resetZoom')}
+              </button>`
+            : nothing}
         </div>
+        ${this.renderLegend()}
         <p part="description" id=${this.descriptionId} class="sr-only">${description}</p>
         <p id=${this.datumStatusId} class="sr-only" aria-live="polite">
           ${this.keyboardDatumAnnouncement}
@@ -1317,11 +1636,6 @@ export class LyraChart extends LyraElement {
           <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()}>
-              ${this.localize('resetZoom')}
-            </button>`
-            : nothing}
       </div>
     `;
     }