gridsmith-ui 0.17.2 → 0.17.3

package/dist/charts.d.ts

@@ -2,6 +2,24 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+/**
+ * Sprint 25.9, A3 — what a chart's category axis holds, and how its labels fit. No Recharts here: the charts entry and
+ * the tests import it, and it never measures on its own (the measurer is handed in).
+ *
+ * - `categoryKind(labels)`: "scale" when every non-empty label is a date, a time, a period or a number, else "names".
+ *   Anchored patterns only — never `Date.parse`, which V8 lets read "Tier 1", "Sprint 1" and "Northern Region 2" as dates.
+ * - `createAxisMeasurer(el)`: canvas text widths in the axis's resolved font, read from a probe that carries
+ *   `font-size: var(--ds-font-size-xs)`, so a `calc()` token (`calc(16px * .75)`, a 14 px base) measures right.
+ * - `fitLabel(name, width, measure)`: one line; else two lines split at a space; else "…" on the second. Never drops it.
+ */
+type CategoryKind = "names" | "scale";
+/**
+ * Whether a category axis holds names or a scale (dates, times, periods, numbers). Every non-empty label must match an
+ * anchored pattern to be "scale"; an all-empty set is "scale". LineChart and AreaChart are always "scale"; BarChart and
+ * CompositeChart guess with this, and their `categoryKind` prop overrides the guess.
+ */
+declare function categoryKind(labels: ReadonlyArray<unknown>): CategoryKind;
+
 type XAxisInterval = number | "preserveStart" | "preserveEnd" | "preserveStartEnd" | "equidistantPreserveStart";
 
 interface BarDef {
@@ -17,23 +35,38 @@ interface BarDef {
 }
 interface BarChartProps {
     /**
-     * Which category ticks show. Leave it out: the chart measures its widest label with the chart's font and labels every
-     * k-th category from the first, the last only when it falls on the step (Sprint 25.4 C-11, decision 7). A number
-     * labels every Nth category instead. The Recharts strings ("preserveStartEnd") are accepted for compatibility and
-     * mean the same measured labelling — they never hand the ticks back to Recharts' thinning (round 13).
+     * Which category ticks show on an axis of dates or numbers. Leave it out: the chart measures its widest label with
+     * the chart's font and labels every k-th category from the first, the last only when it falls on the step (Sprint
+     * 25.4 C-11, decision 7). A number labels every Nth category instead. The Recharts strings ("preserveStartEnd") are
+     * accepted for compatibility and mean the same measured labelling (round 13). A names axis is never thinned.
      */
     xAxisInterval?: XAxisInterval;
     data: Record<string, unknown>[];
     bars: BarDef[];
     xAxisKey: string;
-    height?: "sm" | "md" | "lg" | number;
+    /**
+     * "auto" (the default): the chart sizes itself — sideways, a row per category; upright, two wide to one high. A
+     * preset or a number overrides it; inside a ChartContainer, the container's own height wins.
+     */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     /** Every bar without a stackId joins one stack. */
     stacked?: boolean;
+    /**
+     * Bars running sideways, one row per category. Leave it out: an upright chart of names turns itself sideways when a
+     * name would be cut to fewer than six characters, and back when there's room (D8). true or false forces either.
+     */
     horizontal?: boolean;
+    /**
+     * What the categories are. "names" are never skipped: each wraps onto two lines, then ends with "…", with the full
+     * name on hover. "scale" (dates, times, numbers) is labelled at an even step. Leave it out: guessed from the labels.
+     */
+    categoryKind?: "names" | "scale";
     showGrid?: boolean;
     showTooltip?: boolean;
     showLegend?: boolean;
+    /** The category axis's title, as drawn upright (below it). A sideways chart puts the category title above its names. */
     xAxisLabel?: string;
+    /** The value axis's title, drawn horizontally above the axis. */
     yAxisLabel?: string;
     animated?: boolean;
     "aria-label"?: string;
@@ -57,13 +90,15 @@ interface LineChartProps {
     data: Record<string, unknown>[];
     lines: LineDef[];
     xAxisKey: string;
-    height?: "sm" | "md" | "lg" | number;
+    /** "auto" (the default): two wide to one high. A preset or a number overrides it; a ChartContainer's own height wins. */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     curved?: boolean;
     showDots?: boolean;
     showGrid?: boolean;
     showTooltip?: boolean;
     showLegend?: boolean;
     xAxisLabel?: string;
+    /** The value axis's title, drawn horizontally above the axis. */
     yAxisLabel?: string;
     animated?: boolean;
     "aria-label"?: string;
@@ -86,7 +121,8 @@ interface AreaChartProps {
     data: Record<string, unknown>[];
     areas: AreaDef[];
     xAxisKey: string;
-    height?: "sm" | "md" | "lg" | number;
+    /** "auto" (the default): two wide to one high. A preset or a number overrides it; a ChartContainer's own height wins. */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     stacked?: boolean;
     curved?: boolean;
     showGrid?: boolean;
@@ -94,6 +130,7 @@ interface AreaChartProps {
     showLegend?: boolean;
     gradient?: boolean;
     xAxisLabel?: string;
+    /** The value axis's title, drawn horizontally above the axis. */
     yAxisLabel?: string;
     animated?: boolean;
     "aria-label"?: string;
@@ -107,7 +144,8 @@ interface PieChartProps {
         value: number;
         [key: string]: unknown;
     }[];
-    height?: "sm" | "md" | "lg" | number;
+    /** "auto" (the default): square. A preset or a number overrides it; a ChartContainer's own height wins. */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     donut?: boolean;
     showTooltip?: boolean;
     showLegend?: boolean;
@@ -120,17 +158,21 @@ declare const PieChart: react.ForwardRefExoticComponent<PieChartProps & react.Re
 
 interface CompositeChartProps {
     /**
-     * Which category ticks show. Leave it out: the chart measures its widest label with the chart's font and labels every
-     * k-th category from the first, the last only when it falls on the step (Sprint 25.4 C-11, decision 7). A number
-     * labels every Nth category instead. The Recharts strings ("preserveStartEnd") are accepted for compatibility and
-     * mean the same measured labelling — they never hand the ticks back to Recharts' thinning (round 13).
+     * Which category ticks show on an axis of dates or numbers. Leave it out: the chart measures its widest label with
+     * the chart's font and labels every k-th category from the first, the last only when it falls on the step (Sprint
+     * 25.4 C-11, decision 7). A number labels every Nth category instead. The Recharts strings ("preserveStartEnd") are
+     * accepted for compatibility and mean the same measured labelling (round 13). A names axis is never thinned.
      */
     xAxisInterval?: XAxisInterval;
     data: Record<string, unknown>[];
     bars: BarDef[];
     lines: LineDef[];
     xAxisKey: string;
-    height?: "sm" | "md" | "lg" | number;
+    /**
+     * "auto" (the default): two wide to one high; sideways, a row per category. A preset or a number overrides it; a
+     * ChartContainer's own height wins.
+     */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     /** Every bar without a stackId joins one stack; lines draw over it (Sprint 25.7, C4). A bar's stackId works too. */
     stacked?: boolean;
     /**
@@ -139,10 +181,22 @@ interface CompositeChartProps {
      * reads against the stack's own scale. An explicit value wins.
      */
     dualAxis?: boolean;
+    /**
+     * What the categories are. "names" are never skipped: each wraps onto two lines, then ends with "…", with the full
+     * name on hover. "scale" (dates, times, numbers) is labelled at an even step. Leave it out: guessed from the labels.
+     */
+    categoryKind?: "names" | "scale";
+    /**
+     * Bars running sideways, one row per category, with the lines crossing the rows. Leave it out: a chart of names turns
+     * itself sideways when a name would be cut to fewer than six characters, and back when there's room (D8). true or
+     * false forces either.
+     */
+    horizontal?: boolean;
     showGrid?: boolean;
     showTooltip?: boolean;
     showLegend?: boolean;
     xAxisLabel?: string;
+    /** The value axis's title, drawn horizontally above the axis. */
     yAxisLabel?: string;
     animated?: boolean;
     "aria-label"?: string;
@@ -161,8 +215,10 @@ interface ScatterSeries {
 interface ScatterChartProps {
     data: ScatterSeries[];
     xLabel?: string;
+    /** The value axis's title, drawn horizontally above the axis. */
     yLabel?: string;
-    height?: "sm" | "md" | "lg" | number;
+    /** "auto" (the default): two wide to one high. A preset or a number overrides it; a ChartContainer's own height wins. */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     showGrid?: boolean;
     showTooltip?: boolean;
     showLegend?: boolean;
@@ -180,7 +236,8 @@ interface RadarChartProps {
     data: Record<string, unknown>[];
     dataKeys: RadarDataKey[];
     axisKey: string;
-    height?: "sm" | "md" | "lg" | number;
+    /** "auto" (the default): square. A preset or a number overrides it; a ChartContainer's own height wins. */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     filled?: boolean;
     showDots?: boolean;
     showTooltip?: boolean;
@@ -198,7 +255,8 @@ interface RadialBarChartProps {
         max?: number;
         [key: string]: unknown;
     }[];
-    height?: "sm" | "md" | "lg" | number;
+    /** "auto" (the default): square. A preset or a number overrides it; a ChartContainer's own height wins. */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     showTooltip?: boolean;
     showLegend?: boolean;
     showLabels?: boolean;
@@ -216,8 +274,10 @@ interface FunnelChartProps {
         value: number;
         [key: string]: unknown;
     }[];
-    height?: "sm" | "md" | "lg" | number;
+    /** "auto" (the default): a row per stage. A preset or a number overrides it; a ChartContainer's own height wins. */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     showTooltip?: boolean;
+    /** Kept for compatibility: a funnel has no legend, its labels name the stages (Recharts gives it no legend entries). */
     showLegend?: boolean;
     showLabels?: boolean;
     animated?: boolean;
@@ -234,7 +294,8 @@ interface TreemapNode {
 }
 interface TreemapChartProps {
     data: TreemapNode[];
-    height?: "sm" | "md" | "lg" | number;
+    /** "auto" (the default): two wide to one high. A preset or a number overrides it; a ChartContainer's own height wins. */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     showTooltip?: boolean;
     animated?: boolean;
     "aria-label"?: string;
@@ -253,7 +314,8 @@ interface SankeyChartProps {
             value: number;
         }[];
     };
-    height?: "sm" | "md" | "lg" | number;
+    /** "auto" (the default): two wide to one high. A preset or a number overrides it; a ChartContainer's own height wins. */
+    height?: "auto" | "sm" | "md" | "lg" | number;
     showTooltip?: boolean;
     animated?: boolean;
     "aria-label"?: string;
@@ -277,11 +339,13 @@ declare const Sparkline: react.ForwardRefExoticComponent<SparklineProps & react.
 
 interface ChartContainerProps {
     /**
-     * "fill" (Sprint 25.7, C4): the container fills its row — beside a table in a grid or a flex row — with the chart
-     * placed absolutely inside a minimum-height area, so it adds no height of its own: the row takes the table's height,
-     * and the chart grows and shrinks with it.
+     * "auto" (the default): the chart sizes itself from its type and its data (Sprint 25.9, A2) — a row per item for
+     * sideways bars and funnels, two wide to one high for charts over dates or numbers, square for round charts — and in
+     * a row its frame matches the tallest block while the chart grows only to its bound. "fill" means the same as "auto".
+     * A preset (sm, md, lg) or a number of px sets this chart's height instead, and beats the chart's own.
      */
-    height?: "sm" | "md" | "lg" | "fill";
+    height?: "auto" | "fill" | "sm" | "md" | "lg" | number;
+    /** The insight, as a heading (h3) in the card-title style, never cut. The chart's graphic is named by it. */
     title?: string;
     loading?: boolean;
     emptyState?: ReactNode;
@@ -294,4 +358,4 @@ declare function ChartContainer({ height, title, loading, emptyState, variant, c
 
 declare function useChartColors(count: number, soft?: boolean): string[];
 
-export { AreaChart, type AreaChartProps, type AreaDef, BarChart, type BarChartProps, type BarDef, ChartContainer, CompositeChart, type CompositeChartProps, FunnelChart, type FunnelChartProps, LineChart, type LineChartProps, type LineDef, PieChart, type PieChartProps, RadarChart, type RadarChartProps, type RadarDataKey, RadialBarChart, type RadialBarChartProps, SankeyChart, type SankeyChartProps, ScatterChart, type ScatterChartProps, type ScatterSeries, Sparkline, type SparklineProps, TreemapChart, type TreemapChartProps, type TreemapNode, useChartColors };
+export { AreaChart, type AreaChartProps, type AreaDef, BarChart, type BarChartProps, type BarDef, ChartContainer, CompositeChart, type CompositeChartProps, FunnelChart, type FunnelChartProps, LineChart, type LineChartProps, type LineDef, PieChart, type PieChartProps, RadarChart, type RadarChartProps, type RadarDataKey, RadialBarChart, type RadialBarChartProps, SankeyChart, type SankeyChartProps, ScatterChart, type ScatterChartProps, type ScatterSeries, Sparkline, type SparklineProps, TreemapChart, type TreemapChartProps, type TreemapNode, categoryKind, useChartColors };