@aceshooting/lyra-ui 16.0.0 → 18.0.0

package/dist/components/charts/chart/chart.class.d.ts

@@ -5,7 +5,15 @@ readonly r?:number;
 * Caller-owned per-point label retained verbatim by events/export and interpolated into the
 * localized whole-point message used by descriptions, tables, and keyboard announcements.
 */
-readonly label?:string;}export interface LyraChartSeries{readonly label:string;readonly data?:readonly(number|null)[];readonly points?:readonly LyraChartPoint[];readonly color?:string|readonly string[];readonly fill?:boolean;readonly width?:number;readonly dash?:boolean;readonly noTooltip?:boolean;readonly axis?:'y'|'y2';readonly pointColors?:readonly string[];
+readonly label?:string;}export interface LyraChartSeries{readonly label:string;readonly data?:readonly(number|null)[];readonly points?:readonly LyraChartPoint[];readonly color?:string|readonly string[];readonly fill?:boolean;readonly width?:number;readonly dash?:boolean;readonly noTooltip?:boolean;readonly axis?:'y'|'y2';
+/**
+* Chart.js dataset `stack` group id. Series sharing the same `stack` value on the same axis
+* accumulate into one stack; a different id starts an independent stack that Chart.js draws
+* side by side with the first on that same (stacked) axis. Omitted series default to Chart.js's
+* own ungrouped stack, matching every series's behavior before this existed. Only meaningful on
+* an axis that is actually stacked -- see `LyraChart.stacked`/`LyraChart.stackedAxes`.
+*/
+readonly stack?:string;readonly pointColors?:readonly string[];
 /**
 * Per-point radius. A single number applies to every point; an array (matching `data`'s
 * length) sets each point independently — passed straight through to Chart.js, which
@@ -63,11 +71,21 @@ readonly axis?:LyraChartFormatterAxis;
 * system for numeric stability with datasets whose finite values sum beyond
 * `Number.MAX_VALUE`, so it has no fixed public unit -- `percentage` alone is stable regardless.
 */
-readonly percentage?:number;}export type LyraChartFormatter=(context:LyraChartFormatterContext)=>string;export type LyraChartExportFormat='csv'|'png';export interface LyraChartArea{readonly top:number;readonly left:number;readonly right:number;readonly bottom:number;readonly width:number;readonly height:number;}
+readonly percentage?:number;}export type LyraChartFormatter=(context:LyraChartFormatterContext)=>string;
+/**
+* Tooltip title/footer formatter. Chart.js calls its own `title`/`footer` tooltip callbacks once
+* per tooltip render against every hovered item, not once per item like the label path -- so
+* unlike `LyraChartFormatter`, this receives every hovered item's context at once, each in the
+* same `LyraChartFormatterContext` shape `formatter`'s `'tooltip'` surface already produces (one
+* entry per dataset the tooltip covers, e.g. every stacked series sharing the hovered category).
+* The property itself being unset -- not the formatter's return value -- is what leaves Chart.js's
+* own default title (the shared category label) or default footer (none) in place.
+*/
+export type LyraChartTooltipGroupFormatter=(items:readonly LyraChartFormatterContext[])=>string;export type LyraChartExportFormat='csv'|'png';export interface LyraChartArea{readonly top:number;readonly left:number;readonly right:number;readonly bottom:number;readonly width:number;readonly height:number;}
 /** A Chart.js-compatible plugin shape without making `chart.js` a type dependency for consumers. */
 export interface LyraChartPlugin{readonly id:string;}
 /** Dataset configuration accepted by the raw `config` passthrough. */
-export interface LyraChartDatasetConfiguration{type?:string;label?:unknown;data?:unknown[];hidden?:boolean;axis?:string;yAxisID?:string;noTooltip?:boolean;fill?:unknown;backgroundColor?:unknown;borderColor?:unknown;borderRadius?:unknown;borderWidth?:unknown;borderDash?:unknown;color?:unknown;pointStyle?:unknown;pointBackgroundColor?:unknown;pointRadius?:unknown;segment?:unknown;}
+export interface LyraChartDatasetConfiguration{type?:string;label?:unknown;data?:unknown[];hidden?:boolean;axis?:string;yAxisID?:string;stack?:string;noTooltip?:boolean;fill?:unknown;backgroundColor?:unknown;borderColor?:unknown;borderRadius?:unknown;borderWidth?:unknown;borderDash?:unknown;color?:unknown;pointStyle?:unknown;pointBackgroundColor?:unknown;pointRadius?:unknown;segment?:unknown;}
 /** Data block accepted by the raw `config` passthrough. */
 export interface LyraChartDataConfiguration{labels?:unknown[];datasets?:LyraChartDatasetConfiguration[];}
 /**
@@ -357,6 +375,18 @@ get plugins():readonly LyraChartPlugin[];set plugins(value:readonly LyraChartPlu
 valueFormatter?:LyraChartValueFormatter;
 /** Unified context-object formatter for visual, tooltip, table/export, and spoken values. */
 formatter?:LyraChartFormatter;
+/**
+* Tooltip title formatter -- e.g. a scatter point's own name. Receives every item the hovered
+* tooltip covers, each in `formatter`'s `'tooltip'`-surface context shape. Unset (the default)
+* leaves Chart.js's own default title (the shared category label) in place.
+*/
+tooltipTitleFormatter?:LyraChartTooltipGroupFormatter;
+/**
+* Tooltip footer formatter -- e.g. a category's stack total under the items. Receives every
+* item the hovered tooltip covers, in the same shape as `tooltipTitleFormatter`. Unset (the
+* default) leaves Chart.js's own default (no footer).
+*/
+tooltipFooterFormatter?:LyraChartTooltipGroupFormatter;
 /** Chart-wide default fill-under-line setting for line-type series; a series's own `LyraChartSeries.fill` overrides it. */
 area:boolean;zoom:boolean;height:string;xLabel:string|null;yLabel:string|null;y2Label:string;beginAtZero:boolean;
 /** Makes the generated data table visible; it remains screen-reader available when false. */
@@ -382,6 +412,18 @@ private dataTableExpandedOverride;private readonly dataTableId;
 private get dataTableVisible();private toggleDataTable;
 /** Stacks the `x`/`y`(/`y2`) scale entries `buildScales()` returns; only meaningful for `bar` and `line` types. */
 stacked:boolean;
+/**
+* Per-value-axis override of `stacked`, keyed by `'y'`/`'y2'`. An axis absent from this record
+* -- including every axis when the whole property is unset -- falls back to the chart-wide
+* `stacked` value, which is what keeps a chart that never sets this byte-identical to before.
+* Lets a `stacked` bar series on the primary axis sit next to an unstacked overlay series on
+* `y2` (via `LyraChartSeries.axis: 'y2'`): set `stackedAxes` to `{ y2: false }` alongside
+* `stacked`, or spell out both axes explicitly. The shared categorical axis (`x` for a vertical
+* bar/line, or `y` when `indexAxis` is `'y'`) has no independent entry of its own -- it always
+* mirrors the resolved `'y'` value, matching Chart.js's own paired index/value-scale stacking
+* contract. Only meaningful for `bar`/`line` types, matching `stacked` itself.
+*/
+stackedAxes?:Partial<Record<'y'|'y2',boolean>>;
 /** Disables Chart.js animation. */
 withoutAnimation:boolean;
 /** Hides the legend. */
@@ -430,6 +472,14 @@ private _config?;private configSource;get config():LyraChartConfiguration|undefi
 /** Subclass hook for removing raw peer keys that contradict a derived public contract. */
 protected normalizeEffectiveConfig(config:LyraChartConfiguration|undefined):LyraChartConfiguration|undefined;private effectiveConfig;private onConfigSlotChange;
 /**
+* Reads the `config-slot`'s currently assigned `<script type="application/json">` and applies
+* it -- wired as the `slotchange` handler (via `onConfigSlotChange`) for every later mutation,
+* and called once more from `firstUpdated()` (see `collectInitialSlotAssignment`) to cover an
+* environment, or a real-browser timing race, where the slot's initial assignment never fires
+* `slotchange`.
+*/
+private collectConfigFromSlot;
+/**
 * 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.
@@ -464,7 +514,7 @@ private loading;
 * True once the optional `chart.js` peer failed to load (not installed) -- `render()` fails
 * closed into a visible `part="error"` and announces through the document-level sink.
 */
-private loadFailed;private loadLibrary;private loadZoomFeature;private loadDataLabelsFeature;private loadAnnotationFeature;private loadGeneration;private zoomLoadGeneration;private dataLabelsLoadGeneration;private annotationLoadGeneration;private zoomFeatureState;private dataLabelsFeatureState;private annotationFeatureState;private dataLabelsPlugin?;private annotationPlugin?;private stopAnnotationRegistrationWatch?;private zoomed;private visible;private intersectionObserver?;private intersectionGeneration;private reducedMotionQuery?;private reducedMotionWindow?;private canvasEl?;
+private loadFailed;private loadLibrary;private loadZoomFeature;private loadDataLabelsFeature;private loadAnnotationFeature;private loadGeneration;private zoomLoadGeneration;private dataLabelsLoadGeneration;private annotationLoadGeneration;private zoomFeatureState;private dataLabelsFeatureState;private annotationFeatureState;private dataLabelsPlugin?;private annotationPlugin?;private stopAnnotationRegistrationWatch?;private zoomed;private visible;private intersectionObserver?;private intersectionGeneration;private reducedMotionQuery?;private reducedMotionWindow?;private canvasEl?;private configSlotEl?;
 /** The current Chart.js instance. Read it only while the element is connected and loaded. */
 chart?:LyraChartInstance;private scaledSliceDatasets;private chartJsModule?;private resizeObserver?;private resizeDrawFrame?;private resizeDrawFrameOwner?;private lastObservedInlineSize?;private autoLegendPosition;private resolvedChartArea?;private chartAreaUpdateQueued;private builtType?;private builtPlugins;private visualDatasetSourceIndexes?;private visualRowSourceIndexes?;private suppressZoomComplete;private descriptionId;private keyboardDatumIndex;private keyboardDatumAnnouncement;
 /** Shared document-level regions that carry announcements. The visually hidden datum copy is an
@@ -513,7 +563,27 @@ private rebuildAfterAnnotationRegistration;private requestDataLabelsFeature;
 * in progress. Same rationale as `toast-item.ts`'s `willUpdate()`-vs-
 * `updated()` split.
 */
-protected willUpdate(changed:PropertyValues):void;protected updated(changed:PropertyValues):void;
+protected willUpdate(changed:PropertyValues):void;
+/**
+* happy-dom (through at least 20.14.5) never fires the default slot's INITIAL `slotchange` --
+* see `collectInitialSlotAssignment`'s own doc -- so an `<lr-chart>` whose
+* `<script type="application/json">` raw config already exists at connect (the ordinary
+* "render once data is ready" Lit pattern) would otherwise never pick it up. Collect once here
+* too, from the slot's current assignment; `collectConfigFromSlot()` simply recomputes and
+* overwrites `slottedConfig` from scratch each call, so a real browser firing the initial event
+* as well is naturally idempotent -- the second call reads back the same assigned elements and
+* writes the same value.
+* Deferred a microtask: `slottedConfig` is a reactive `@state`, so writing it synchronously
+* inside `firstUpdated()` -- after this same update has already been marked complete -- trips
+* Lit's "scheduled an update after an update completed" dev warning. A real `slotchange` event
+* runs this same collection from a task/microtask entirely outside the update cycle, which never
+* trips it; queuing a microtask here reproduces that same "outside the cycle" timing instead of
+* writing `slottedConfig` from inside it. Still guaranteed to land before any caller's own
+* `await el.updateComplete` continuation: that continuation is queued only once this update's
+* promise resolves, later in this same synchronous turn, so it always joins the microtask queue
+* behind the one queued here.
+*/
+protected firstUpdated(changed:PropertyValues):void;protected updated(changed:PropertyValues):void;
 /**
 * 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,
@@ -580,11 +650,13 @@ private annotationOptions;
 * 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.
+* `stackTotals` draws once per category per (axis, `LyraChartSeries.stack` group): the plugin
+* fires per (dataset, point), so a total is shown only on the topmost dataset of each group
+* whose OWN axis is actually stacked (`axisStacked()`) and its formatter returns the null-aware
+* `computeStackTotals()` value for that group (blank when the whole category is null). Two
+* stack groups sharing one axis each get their own total, drawn above their own topmost
+* dataset. When only `dataLabels` is set, or a dataset's axis isn't stacked, each point shows
+* its own value; a null/non-finite point renders blank.
 */
 private datalabelsOptions;
 /** Locale/format a data-label number through the same `valueFormatter` the axis/tooltip use, so a
@@ -593,12 +665,14 @@ private datalabelsOptions;
 *  consumer formatter that branches on context behaves predictably rather than seeing `undefined`. */
 private formatDataLabel;
 /**
-* 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()`.
+* Per-category stack totals for the datasets on axis `axisId` (`'y'`/`'y2'`) belonging to
+* `stackGroup` (a `LyraChartSeries.stack` id), or `null` for a category whose every value is
+* null/undefined (so no total is drawn there rather than a misleading `0`). `stackGroup`
+* defaults to `undefined` -- the implicit group every series without its own `stack` id
+* shares -- so an existing call site untouched by the per-series `stack` feature keeps summing
+* exactly the datasets it always did. 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()`.
 */
 private computeStackTotals;
 /**
@@ -621,6 +695,15 @@ private valueScaleType;
 /** `beginAtZero` for a value axis, suppressed on a logarithmic scale which cannot place zero. */
 private valueBeginAtZero;private scaleBounds;private gridAxisVisible;private axisVisible;
 /**
+* Resolves whether `axisId`'s scale should stack, folding `stackedAxes`'s per-axis override
+* over the chart-wide `stacked` default. `'x'` has no override of its own -- it mirrors the
+* resolved `'y'` value, since Chart.js's stacking contract needs the paired index and value
+* scales to agree (an unstacked value scale ignores an index scale marked `stacked`, and vice
+* versa). Every axis falls back to `stacked` when `stackedAxes` (or its own entry) is unset,
+* which is what keeps a chart that never sets `stackedAxes` byte-identical to before.
+*/
+private axisStacked;
+/**
 * Builds `options.scales` for the effective chart type: no scale at all for
 * pie/doughnut (a proportional-area chart has no axis), the single radial
 * `r` scale Chart.js v4 uses for radar/polarArea, and the cartesian
@@ -695,7 +778,24 @@ private sourceDatumFormatterMetadata;
 private stackTotalMetadata;
 /** `effective` is threaded in: `effectiveData()` rebuilds every label and dataset array, and this
 *  runs once per legend entry, so resolving it here would rebuild it N times per legend pass. */
-private legendValue;private legendLabels;private tooltipLabel;private updateAutoLegendPosition;private legendPositionForConfig;private legendPositionForLayout;
+private legendValue;private legendLabels;private tooltipLabel;
+/**
+* Resolves one hovered tooltip item into the unified formatter context, for
+* `tooltipTitleFormatter`/`tooltipFooterFormatter`. Mirrors `tooltipLabel()`'s raw-value and
+* rescaled-slice resolution so a hovered item's `value` means the same number on every tooltip
+* surface, but returns the context object itself rather than one rendered string -- title/footer
+* need every hovered item's context at once, not one item's formatted text. `undefined` for an
+* item with no numeric value, so it's dropped from the group rather than passed through as
+* `NaN`.
+*/
+private tooltipItemContext;
+/**
+* Runs `formatter` (`tooltipTitleFormatter`/`tooltipFooterFormatter`) against every hovered
+* item's context at once. `undefined` when the formatter itself is unset -- the caller uses that
+* to omit the Chart.js `title`/`footer` callback entirely, which leaves Chart.js's own default
+* in place -- or when no hovered item resolved a numeric value.
+*/
+private tooltipGroupText;private updateAutoLegendPosition;private legendPositionForConfig;private legendPositionForLayout;
 /**
 * The `data-legend-position` token that selects `[part='base']`'s grid template. Deliberately
 * *not* the physical side `legendPositionForLayout()` reports: CSS Grid numbers a two-column