@skyux/charts 14.6.2 → 14.8.0

package/types/skyux-charts.d.ts

@@ -1,26 +1,421 @@
 import * as _angular_core from '@angular/core';
 import { TemplateRef } from '@angular/core';
+import { ChartType, ChartConfiguration } from 'chart.js';
 
 /**
+ * Defines the category axis of a chart. Its categories are shared by every
+ * series plotted against it, and each series' values align to them by index.
+ *
  * @preview
+ */
+declare class SkyChartAxisCategory {
+    /**
+     * The categories shared by every series plotted against this axis. Each
+     * series' values are aligned to these categories by index.
+     */
+    readonly categories: _angular_core.InputSignal<readonly (string | number)[]>;
+    /**
+     * Whether to hide the axis label.
+     */
+    readonly labelHidden: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * The text of the axis label.
+     */
+    readonly labelText: _angular_core.InputSignal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SkyChartAxisCategory, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SkyChartAxisCategory, "sky-chart-axis-category", never, { "categories": { "alias": "categories"; "required": true; "isSignal": true; }; "labelHidden": { "alias": "labelHidden"; "required": false; "isSignal": true; }; "labelText": { "alias": "labelText"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * How a chart formats its numeric values in axis labels, tooltips, and the
+ * data table. The `percent` format expects fractional values, so `0.25`
+ * displays as `25%`.
  *
- * The allowed heading levels for charts, corresponding to the semantic heading levels in HTML.
+ * @preview
  */
-type SkyChartHeadingLevel = 2 | 3 | 4 | 5;
+type SkyChartValueFormat = 'currency' | 'number' | 'percent';
 
 /**
+ * The scale type for a chart value axis. Use `logarithmic` when values span
+ * several orders of magnitude; otherwise use the default `linear` scale. Note
+ * that the `logarithmic` scale cannot display zero or negative values.
+ *
  * @preview
+ */
+type SkyChartValueScaleType = 'linear' | 'logarithmic';
+
+/**
+ * Defines the value axis of a chart, which scales the plotted series and
+ * formats their values in axis labels, tooltips, and the data table.
  *
- * The allowed heading styles for charts, corresponding to the font styles defined in the SKY UX design system.
+ * @preview
  */
-type SkyChartHeadingStyle = 2 | 3 | 4 | 5;
+declare class SkyChartAxisValue {
+    #private;
+    /**
+     * The ISO 4217 currency code used when `format` is `currency`. When unset,
+     * currency values format as `USD`.
+     */
+    readonly currencyCode: _angular_core.InputSignal<string | undefined>;
+    /**
+     * The number of decimal places to display. When unset, the format's
+     * locale-aware default is used (for example, two places for most
+     * currencies).
+     */
+    readonly digits: _angular_core.InputSignalWithTransform<number | undefined, unknown>;
+    /**
+     * How to format the axis values in axis labels, tooltips, and the data table.
+     * The `percent` format expects fractional values, so `0.25` displays as
+     * `25%`.
+     * @default 'number'
+     */
+    readonly format: _angular_core.InputSignal<SkyChartValueFormat>;
+    /**
+     * Whether to hide the axis label.
+     */
+    readonly labelHidden: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * The text of the axis label.
+     */
+    readonly labelText: _angular_core.InputSignal<string>;
+    /**
+     * The highest value to display on the axis. When unset, the axis scales to
+     * fit the plotted values.
+     */
+    readonly max: _angular_core.InputSignalWithTransform<number | undefined, unknown>;
+    /**
+     * The lowest value to display on the axis. When unset, the axis scales to
+     * fit the plotted values.
+     */
+    readonly min: _angular_core.InputSignalWithTransform<number | undefined, unknown>;
+    /**
+     * The scale type for the value axis.
+     * @default 'linear'
+     */
+    readonly scaleType: _angular_core.InputSignal<SkyChartValueScaleType>;
+    /**
+     * Formats a numeric value according to this axis's `format`, `currencyCode`,
+     * and the current locale.
+     * @internal
+     */
+    readonly formatValue: _angular_core.Signal<(value: number) => string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SkyChartAxisValue, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SkyChartAxisValue, "sky-chart-axis-value", never, { "currencyCode": { "alias": "currencyCode"; "required": false; "isSignal": true; }; "digits": { "alias": "digits"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "labelHidden": { "alias": "labelHidden"; "required": false; "isSignal": true; }; "labelText": { "alias": "labelText"; "required": true; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "scaleType": { "alias": "scaleType"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
 
 /**
+ * A Chart.js configuration with a required `options` object. Plot components
+ * always build a complete `options`, so requiring it here keeps the render
+ * loop free of undefined checks.
+ * @internal
+ */
+type SkyChartJsConfig<TType extends ChartType = ChartType> = ChartConfiguration<TType> & {
+    options: NonNullable<ChartConfiguration<TType>['options']>;
+};
+
+/**
+ * A tabular representation of a chart's plotted content, used to render the
+ * accessible data table.
+ * @internal
+ */
+interface SkyChartTable {
+    /**
+     * The label of the category axis, shown as the corner header of the table.
+     */
+    categoryLabel: string;
+    /**
+     * The category values, shown as the table's row headers.
+     */
+    categories: readonly (string | number)[];
+    /**
+     * The plotted series, shown as the table's columns.
+     */
+    series: SkyChartTableSeries[];
+}
+/**
+ * A single series within a chart's tabular representation.
+ * @internal
+ */
+interface SkyChartTableSeries {
+    /**
+     * The series label, shown as a column header.
+     */
+    label: string;
+    /**
+     * The series values, formatted for display and aligned to the categories by
+     * index.
+     */
+    values: readonly string[];
+}
+
+/**
+ * A localized, descriptive summary of a chart's plotted content, used as the
+ * accessible name of the chart figure. Each plot type supplies its own resource
+ * key and arguments so the wording can describe that type's shape (for example,
+ * a bar chart's series and categories).
+ * @internal
+ */
+interface SkyChartAccessibleSummary {
+    /**
+     * The resource key of the localized summary sentence.
+     */
+    resourceKey: string;
+    /**
+     * The positional arguments for the localized summary sentence.
+     */
+    args: (string | number)[];
+}
+
+/**
+ * The resolved, themed styling for a chart, grouped by feature. Chart.js
+ * renders to a canvas that cannot read CSS custom properties, so every SKY
+ * theme token the library depends on is resolved here — and only here — to a
+ * concrete value. This keeps the full set of tokens auditable in one place.
+ *
+ * When the SKY theme styles are not loaded, strings resolve to empty strings —
+ * which Chart.js treats as unset, rendering with its own defaults — and numbers
+ * to `NaN`. Every value otherwise has a default defined in the
+ * `sky-default-overrides` mixin in `chart.scss`, which applies in every
+ * non-modern context; the modern theme supplies the `--sky-*` tokens directly.
+ * @internal
+ */
+interface SkyChartThemeStyles {
+    font: {
+        family: string;
+        size: number;
+        weight: number;
+        emphasizedWeight: number;
+    };
+    text: {
+        color: string;
+        deemphasizedColor: string;
+        lineHeight: number;
+    };
+    height: {
+        /** The minimum chart height, in pixels. */
+        min: number;
+        /** The maximum chart height, in pixels. */
+        max: number;
+        /**
+         * The default chart height as a CSS `clamp()` expression, used by
+         * orientations whose height is not computed from their content.
+         */
+        default: string;
+    };
+    axis: {
+        lineColor: string;
+        gridlineColor: string;
+        tickLength: number;
+        /**
+         * The vertical gap between an axis title and its ticks.
+         */
+        titleGap: number;
+    };
+    series: {
+        categoricalPalette: string[];
+    };
+    /**
+     * The styling of the tooltip container and its contents.
+     */
+    tooltip: {
+        backgroundColor: string;
+        borderColor: string;
+        borderWidth: number;
+        cornerRadius: number;
+        inset: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+        /**
+         * The size of the color-swatch icon beside each tooltip line.
+         */
+        iconSize: number;
+        /**
+         * The gap between the color-swatch icon and its text.
+         */
+        iconGap: number;
+        /**
+         * The vertical gap between the tooltip title or footer and its body.
+         */
+        titleGap: number;
+        /**
+         * The vertical gap between tooltip body lines.
+         */
+        bodyGap: number;
+    };
+    bar: {
+        borderColor: string;
+        borderRadius: number;
+        /** Bar-layout sizing for a vertical (column) chart, in pixels. */
+        vertical: {
+            baseBarThickness: number;
+            minBarThickness: number;
+            maxBarThickness: number;
+        };
+        /** Bar-layout sizing for a horizontal chart, in pixels. */
+        horizontal: {
+            minBarThickness: number;
+            maxBarThickness: number;
+            minCategoryGap: number;
+        };
+    };
+}
+
+/**
+ * Base class for chart plot components (for example, `sky-chart-bar`). Owns the
+ * bridge that publishes each plot's tabular representation to the accessible
+ * data table, so every plot type shares the same lifecycle. Subclasses
+ * implement `getChartTable`, `getAccessibleSummary`, and their own rendering.
+ *
+ * Plots must be rendered inside `sky-chart`: the wrapper provides the data
+ * table bridge and the default-theme styling the plot resolves its themed
+ * values from.
+ * @internal
+ */
+declare abstract class SkyChartPlot {
+    #private;
+    constructor();
+    /**
+     * Builds the tabular representation of the plotted content for the accessible
+     * data table, or `undefined` when the plot has no data to represent.
+     */
+    protected abstract getChartTable(): SkyChartTable | undefined;
+    /**
+     * Builds the localized, descriptive summary used as the chart figure's
+     * accessible name, or `undefined` when the plot has no data to represent.
+     */
+    protected abstract getAccessibleSummary(): SkyChartAccessibleSummary | undefined;
+    /**
+     * Resolves the active theme's chart styling against this plot's element.
+     * Chart.js renders to a canvas that cannot read CSS variables, so themed
+     * tokens must be resolved to concrete values against the DOM.
+     */
+    protected getThemeStyles(): SkyChartThemeStyles;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SkyChartPlot, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SkyChartPlot, never, never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * The orientation of a bar chart's bars.
+ *
  * @preview
+ */
+type SkyChartBarOrientation = 'horizontal' | 'vertical';
+
+/**
+ * A single value plotted by a bar chart series: a number renders a standard
+ * bar measured from the value axis's baseline, a `[start, end]` tuple renders
+ * a floating bar spanning the two values, and `null` renders a gap.
  *
+ * @preview
+ */
+type SkyChartBarSeriesValue = number | readonly [number, number] | null;
+
+/**
+ * Defines a single series of values to plot on a bar chart, aligned to the
+ * category axis by index.
+ *
+ * @preview
+ */
+declare class SkyChartBarSeries {
+    /**
+     * The text that identifies this series in the legend and tooltips.
+     */
+    readonly labelText: _angular_core.InputSignal<string>;
+    /**
+     * The stack this series belongs to. When a bar chart's `seriesLayout`
+     * is `stacked`, series that share the same `stackId` value accumulate into
+     * a single bar per category, and series with different `stackId` values
+     * are placed side by side. Omit to stack every series into one bar per
+     * category. Has no effect when `seriesLayout` is `grouped`.
+     */
+    readonly stackId: _angular_core.InputSignal<string | undefined>;
+    /**
+     * The values for this series, aligned to the category axis categories by
+     * index. A number renders a standard bar measured from the value axis's
+     * baseline, a `[start, end]` tuple renders a floating bar spanning the two
+     * values, and a `null` value renders a gap in the chart and an empty cell
+     * in the data table.
+     */
+    readonly values: _angular_core.InputSignal<readonly SkyChartBarSeriesValue[]>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SkyChartBarSeries, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SkyChartBarSeries, "sky-chart-bar-series", never, { "labelText": { "alias": "labelText"; "required": true; "isSignal": true; }; "stackId": { "alias": "stackId"; "required": false; "isSignal": true; }; "values": { "alias": "values"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * How a bar chart arranges the bars of multiple series within each category.
+ * `grouped` places the series' bars side by side; `stacked` accumulates the
+ * bars into a single bar per category. Neither has a visible effect when the
+ * chart has a single series.
+ *
+ * @preview
+ */
+type SkyChartBarSeriesLayout = 'grouped' | 'stacked';
+
+/**
+ * Renders a bar chart from a category axis, a value axis, and one or more
+ * series.
+ *
+ * @preview
+ */
+declare class SkyChartBar extends SkyChartPlot {
+    #private;
+    /**
+     * The orientation of the bars.
+     * @default 'vertical'
+     */
+    readonly orientation: _angular_core.InputSignal<SkyChartBarOrientation>;
+    /**
+     * How the bars of multiple series are arranged within each category.
+     * `grouped` places the series' bars side by side; `stacked` accumulates the
+     * bars into a single bar per category. When `stacked`, assign each series a
+     * `stackId` value to subdivide the bar into side-by-side stacks (grouped,
+     * stacked bars). This has no visible effect when the chart has a single
+     * series.
+     * @default 'grouped'
+     */
+    readonly seriesLayout: _angular_core.InputSignal<SkyChartBarSeriesLayout>;
+    protected readonly categoryAxis: _angular_core.Signal<SkyChartAxisCategory | undefined>;
+    protected readonly valueAxis: _angular_core.Signal<SkyChartAxisValue | undefined>;
+    protected readonly series: _angular_core.Signal<readonly SkyChartBarSeries[]>;
+    constructor();
+    protected readonly chartJsConfig: _angular_core.Signal<SkyChartJsConfig<"bar"> | undefined>;
+    /**
+     * The height to apply to the rendered chart. Chart.js runs with
+     * `maintainAspectRatio: false`, so its container must be given an explicit
+     * height. Vertical charts use the themed default; horizontal charts grow
+     * with their content so every bar stays legible.
+     */
+    protected readonly chartHeight: _angular_core.Signal<string>;
+    protected getChartTable(): SkyChartTable | undefined;
+    protected getAccessibleSummary(): SkyChartAccessibleSummary | undefined;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SkyChartBar, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SkyChartBar, "sky-chart-bar", never, { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "seriesLayout": { "alias": "seriesLayout"; "required": false; "isSignal": true; }; }, {}, ["categoryAxis", "valueAxis", "series"], never, true, never>;
+}
+
+/**
+ * The allowed heading levels for charts, corresponding to the semantic heading levels in HTML.
+ *
+ * @preview
+ */
+type SkyChartHeadingLevel = 2 | 3 | 4 | 5;
+
+/**
+ * The allowed heading styles for charts, corresponding to the font styles defined in the SKY UX design system.
+ *
+ * @preview
+ */
+type SkyChartHeadingStyle = 2 | 3 | 4 | 5;
+
+/**
  * Provides a consistent heading, subheading, and layout wrapper for a chart.
+ *
+ * @preview
  */
 declare class SkyChart {
+    #private;
     /**
      * Whether to hide the chart's heading.
      */
@@ -56,17 +451,20 @@ declare class SkyChart {
      */
     readonly helpPopoverTitle: _angular_core.InputSignal<string | undefined>;
     /**
-     * Whether to hide the chart's subheading.
+     * Whether the chart's data is being loaded. When `true`, a wait overlay
+     * covers the chart's content area, which reserves the default chart height
+     * while no plot is rendered. The heading and help button stay interactive.
+     * @default false
      */
-    readonly subheadingHidden: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly loading: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /**
      * The text to display as the chart's subheading.
      */
     readonly subheadingText: _angular_core.InputSignal<string | undefined>;
-    protected readonly figureLabel: _angular_core.Signal<string>;
+    protected readonly figureLabel: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SkyChart, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SkyChart, "sky-chart", never, { "headingHidden": { "alias": "headingHidden"; "required": false; "isSignal": true; }; "headingLevel": { "alias": "headingLevel"; "required": false; "isSignal": true; }; "headingStyle": { "alias": "headingStyle"; "required": false; "isSignal": true; }; "headingText": { "alias": "headingText"; "required": true; "isSignal": true; }; "helpKey": { "alias": "helpKey"; "required": false; "isSignal": true; }; "helpPopoverContent": { "alias": "helpPopoverContent"; "required": false; "isSignal": true; }; "helpPopoverTitle": { "alias": "helpPopoverTitle"; "required": false; "isSignal": true; }; "subheadingHidden": { "alias": "subheadingHidden"; "required": false; "isSignal": true; }; "subheadingText": { "alias": "subheadingText"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SkyChart, "sky-chart", never, { "headingHidden": { "alias": "headingHidden"; "required": false; "isSignal": true; }; "headingLevel": { "alias": "headingLevel"; "required": false; "isSignal": true; }; "headingStyle": { "alias": "headingStyle"; "required": false; "isSignal": true; }; "headingText": { "alias": "headingText"; "required": true; "isSignal": true; }; "helpKey": { "alias": "helpKey"; "required": false; "isSignal": true; }; "helpPopoverContent": { "alias": "helpPopoverContent"; "required": false; "isSignal": true; }; "helpPopoverTitle": { "alias": "helpPopoverTitle"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "subheadingText": { "alias": "subheadingText"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
-export { SkyChart };
-export type { SkyChartHeadingLevel, SkyChartHeadingStyle };
+export { SkyChart, SkyChartAxisCategory, SkyChartAxisValue, SkyChartBar, SkyChartBarSeries };
+export type { SkyChartBarOrientation, SkyChartBarSeriesLayout, SkyChartBarSeriesValue, SkyChartHeadingLevel, SkyChartHeadingStyle, SkyChartValueFormat, SkyChartValueScaleType };