@automattic/charts 4.13.0 → 4.15.0

package/dist/index.css

@@ -37,6 +37,7 @@
   --a8c-charts-border-radius-leaderboard-bar: 9999px;
   --a8c-charts-dimension-leaderboard-row-gap: var(--wpds-dimension-gap-md, 12px);
   --a8c-charts-dimension-leaderboard-column-gap: var(--wpds-dimension-gap-xs, 4px);
+  --a8c-charts-dimension-leaderboard-label-inset: var(--wpds-dimension-padding-sm, 8px);
   --a8c-charts-dimension-legend-column-gap: var(--wpds-dimension-gap-lg, 16px);
   --a8c-charts-dimension-legend-row-gap: var(--wpds-dimension-gap-sm, 8px);
 }
@@ -348,6 +349,37 @@
     transform: scaleX(1);
   }
 }
+
+.a8ccharts-97yN9W-bar-chart--stacked .visx-bar-group rect {
+  rx: 0;
+  animation: none;
+}
+
+.a8ccharts-97yN9W-bar-chart--stacked .visx-bar-group rect[data-stack-end="top"] {
+  clip-path: inset(0 round var(--a8c-charts-border-radius-bar-chart) var(--a8c-charts-border-radius-bar-chart) 0 0);
+}
+
+.a8ccharts-97yN9W-bar-chart--stacked .visx-bar-group rect[data-stack-end="right"] {
+  clip-path: inset(0 round 0 var(--a8c-charts-border-radius-bar-chart) var(--a8c-charts-border-radius-bar-chart) 0);
+}
+
+.a8ccharts-97yN9W-bar-chart--stacked .visx-bar-group rect[data-stack-end="bottom"] {
+  clip-path: inset(0 round 0 0 var(--a8c-charts-border-radius-bar-chart) var(--a8c-charts-border-radius-bar-chart));
+}
+
+.a8ccharts-97yN9W-bar-chart--stacked .visx-bar-group rect[data-stack-end="left"] {
+  clip-path: inset(0 round var(--a8c-charts-border-radius-bar-chart) 0 0 var(--a8c-charts-border-radius-bar-chart));
+}
+
+.a8ccharts-97yN9W-bar-chart--stacked.a8ccharts-97yN9W-bar-chart--animated .visx-bar-group {
+  transform-box: view-box;
+  animation: a8ccharts-97yN9W-rise var(--a8c-charts-motion-duration-entrance) var(--a8c-charts-motion-easing-entrance) both;
+}
+
+.a8ccharts-97yN9W-bar-chart--stacked.a8ccharts-97yN9W-bar-chart--animated-horizontal .visx-bar-group {
+  transform-box: view-box;
+  animation: a8ccharts-97yN9W-stretch var(--a8c-charts-motion-duration-entrance) var(--a8c-charts-motion-easing-entrance) both;
+}
 .a8ccharts-gx1_AW-selected-ring__far, .a8ccharts-gx1_AW-selected-ring__edge {
   fill: none;
 }
@@ -762,7 +794,7 @@
 }
 
 .a8ccharts-GovfoW-barWithLabelContainer.a8ccharts-GovfoW-is-overlay .a8ccharts-GovfoW-label {
-  padding-left: var(--wpds-dimension-padding-sm, 8px);
+  padding-inline-start: var(--a8c-charts-dimension-leaderboard-label-inset);
 }
 
 .a8ccharts-GovfoW-barWithLabelContainer.a8ccharts-GovfoW-is-overlay .a8ccharts-GovfoW-barTrack {

package/dist/index.d.cts

@@ -163,18 +163,16 @@ type LeaderboardEntryFields = {
    */
   previousValue?: number;
   /**
-   * Width of current bar, as % of the largest absolute value across rows. A negative share
-   * extends the bar from a shared zero point toward the inline start, for every row.
+   * Width of current bar, as %. Derived from the values when omitted; a passed value wins.
+   * A negative share extends the bar from a shared zero point toward the inline start, for every row.
    */
-  currentShare: number;
+  currentShare?: number;
   /**
-   * Width of previous bar, as % of the largest absolute value across rows. Omit when this
-   * row has no matching comparison-period value.
+   * Width of previous bar, as %. Derived from `previousValue` when omitted; a passed value wins.
    */
   previousShare?: number;
   /**
-   * Delta of the entry. Omit when the percentage change is unavailable, such
-   * as when the row has no comparison value or its previous value is zero.
+   * Percentage change. Derived from the values when omitted; a passed value wins.
    */
   delta?: number;
   /**
@@ -255,9 +253,9 @@ type BarStyles = {
   opacity?: number;
 };
 /**
- * How a bar chart places its series in a category. `grouped` puts each primary series in a slot of its own; `overlap` puts every primary in one slot and every comparison in a second, and overlaps the `group`s within each slot.
+ * How a bar chart places its series in a category. `grouped` puts each primary series in a slot of its own; `overlap` puts every primary in one slot and every comparison in a second, and overlaps the `group`s within each slot; `stacked` stacks every primary in one bar, the first series at the bottom.
  */
-type BarChartLayout = 'grouped' | 'overlap';
+type BarChartLayout = 'grouped' | 'overlap' | 'stacked';
 type MultipleDataPointsDate = {
   label: string;
   data: DataPointDate[];
@@ -369,6 +367,18 @@ type ChartTheme = {
     /** Stroke width for the sparkline line */
     strokeWidth?: number;
   };
+  /** Compact mode for `compactWhenShort` line, area and bar charts */
+  compactWhenShort?: {
+    /** Height (px) below which the chart turns compact */
+    below?: number;
+    /** Margin the chart defaults to while compact */
+    margin?: {
+      top?: number;
+      right?: number;
+      bottom?: number;
+      left?: number;
+    };
+  };
   /**
    * HeatmapChart settings. Cell gap, radius, value size and the selection ring come from
    * WPDS tokens in CSS, so only the compact sizing lives here.
@@ -398,6 +408,9 @@ type CompleteChartTheme = Required<ChartTheme> & {
   sparkline: Required<NonNullable<ChartTheme['sparkline']>> & {
     margin: Required<NonNullable<ChartTheme['sparkline']>['margin']>;
   };
+  compactWhenShort: Required<NonNullable<ChartTheme['compactWhenShort']>> & {
+    margin: Required<NonNullable<ChartTheme['compactWhenShort']>['margin']>;
+  };
   heatmapChart: Required<NonNullable<ChartTheme['heatmapChart']>>;
 };
 /**
@@ -447,6 +460,12 @@ type AxisOptions = {
    * so callers can force a specific axis (e.g. integer-only steps on a sparse chart).
    */
   tickValues?: ScaleInput<AxisScale>[];
+  /**
+   * Most decimal places a value-axis tick may carry, so labels rounded to that precision never repeat;
+   * an axis holding fewer than two steps widens to the nearest ones. Whole-number data always uses 0.
+   * Ignored on a log scale, or when `tickValues` or the value scale's `domain` is set. Line and bar charts only.
+   */
+  tickDecimals?: number;
   axisClassName?: string;
   axisLineClassName?: string;
   labelClassName?: string;
@@ -626,6 +645,17 @@ interface SeriesVisibilityProps {
    */
   defaultHiddenSeries?: readonly string[];
 }
+/**
+ * Compact mode for cartesian charts placed in short containers.
+ */
+interface CompactWhenShortProps {
+  /**
+   * Drop the axes, grid and legend, and default to `theme.compactWhenShort.margin`, while the
+   * chart is shorter than `theme.compactWhenShort.below`. Series hidden through the legend stay
+   * hidden until the chart is tall again. Horizontal bar charts ignore it.
+   */
+  compactWhenShort?: boolean;
+}
 /**
  * Base properties shared across all chart components
  */
@@ -785,7 +815,15 @@ type BaseLegendItem = {
   interactive?: boolean;
   /** Label of the series this static item describes; the item is left out while it is hidden. */
   describesSeries?: string;
-};
+} & ({
+  /** Pressed state of the toggle. */
+  pressed: boolean;
+  /** Makes an interactive legend item a toggle the consumer controls, instead of a series toggle. */
+  onToggle: () => void;
+} | {
+  pressed?: never;
+  onToggle?: never;
+});
 export declare const Legend: import("react").ForwardRefExoticComponent<Omit<BaseLegendProps, "items"> & {
   items?: BaseLegendItem[];
   chartId?: string;
@@ -925,7 +963,7 @@ type RenderLineGlyphProps<Datum extends object> = GlyphProps<Datum> & {
   glyphStyle?: SVGProps<SVGCircleElement>;
   position?: 'start' | 'end';
 };
-interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
+interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps, CompactWhenShortProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -978,7 +1016,7 @@ type TooltipDatum = {
   /** The series' reading, or null when the bucket has none. */
   value: number | null;
 };
-interface AreaChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
+interface AreaChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps, CompactWhenShortProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -1081,7 +1119,7 @@ type BandHighlightSelection = {
   width: number;
   height: number;
 };
-interface BarChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
+interface BarChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps, CompactWhenShortProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -1130,13 +1168,15 @@ type BarLegendOptions = Omit<ChartLegendOptions, 'seriesColors'> & {
 /**
  * Builds legend items that match `BarChart`'s bars in a layout, for a custom legend or a chart's own.
  *
- * @param data        - The series the chart draws.
+ * @param allData     - The chart's series; those the layout does not draw get no item.
  * @param options     - The legend options, and the layout the bars are drawn in.
  * @param legendShape - The shape of the legend swatches.
  * @return The legend items.
  */
-export declare function useBarLegendItems(data: SeriesData[], options?: BarLegendOptions, legendShape?: LegendShape<SeriesData[], number>): BaseLegendItem[];
+export declare function useBarLegendItems(allData: SeriesData[], options?: BarLegendOptions, legendShape?: LegendShape<SeriesData[], number>): BaseLegendItem[];
 interface BarListChartProps extends Exclude<BarChartProps, 'orientation' | 'size' | 'gridVisibility'> {
+  /** Bar lists are always horizontal, and horizontal bars ignore `compactWhenShort`. */
+  compactWhenShort?: never;
   options?: {
     /**
      * Scale for the y axis. Exclude the type property.
@@ -1603,6 +1643,11 @@ interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, '
    * Whether to overlay the label on top of bar
    */
   withOverlayLabel?: boolean;
+  /**
+   * How a negative value draws: `diverge` puts every row on a shared zero point, `clamp` draws it as an empty bar.
+   * @default 'diverge'
+   */
+  negativeBars?: 'diverge' | 'clamp';
   /**
    * Primary color for current period bars
    */

package/dist/index.d.ts

@@ -163,18 +163,16 @@ type LeaderboardEntryFields = {
    */
   previousValue?: number;
   /**
-   * Width of current bar, as % of the largest absolute value across rows. A negative share
-   * extends the bar from a shared zero point toward the inline start, for every row.
+   * Width of current bar, as %. Derived from the values when omitted; a passed value wins.
+   * A negative share extends the bar from a shared zero point toward the inline start, for every row.
    */
-  currentShare: number;
+  currentShare?: number;
   /**
-   * Width of previous bar, as % of the largest absolute value across rows. Omit when this
-   * row has no matching comparison-period value.
+   * Width of previous bar, as %. Derived from `previousValue` when omitted; a passed value wins.
    */
   previousShare?: number;
   /**
-   * Delta of the entry. Omit when the percentage change is unavailable, such
-   * as when the row has no comparison value or its previous value is zero.
+   * Percentage change. Derived from the values when omitted; a passed value wins.
    */
   delta?: number;
   /**
@@ -255,9 +253,9 @@ type BarStyles = {
   opacity?: number;
 };
 /**
- * How a bar chart places its series in a category. `grouped` puts each primary series in a slot of its own; `overlap` puts every primary in one slot and every comparison in a second, and overlaps the `group`s within each slot.
+ * How a bar chart places its series in a category. `grouped` puts each primary series in a slot of its own; `overlap` puts every primary in one slot and every comparison in a second, and overlaps the `group`s within each slot; `stacked` stacks every primary in one bar, the first series at the bottom.
  */
-type BarChartLayout = 'grouped' | 'overlap';
+type BarChartLayout = 'grouped' | 'overlap' | 'stacked';
 type MultipleDataPointsDate = {
   label: string;
   data: DataPointDate[];
@@ -369,6 +367,18 @@ type ChartTheme = {
     /** Stroke width for the sparkline line */
     strokeWidth?: number;
   };
+  /** Compact mode for `compactWhenShort` line, area and bar charts */
+  compactWhenShort?: {
+    /** Height (px) below which the chart turns compact */
+    below?: number;
+    /** Margin the chart defaults to while compact */
+    margin?: {
+      top?: number;
+      right?: number;
+      bottom?: number;
+      left?: number;
+    };
+  };
   /**
    * HeatmapChart settings. Cell gap, radius, value size and the selection ring come from
    * WPDS tokens in CSS, so only the compact sizing lives here.
@@ -398,6 +408,9 @@ type CompleteChartTheme = Required<ChartTheme> & {
   sparkline: Required<NonNullable<ChartTheme['sparkline']>> & {
     margin: Required<NonNullable<ChartTheme['sparkline']>['margin']>;
   };
+  compactWhenShort: Required<NonNullable<ChartTheme['compactWhenShort']>> & {
+    margin: Required<NonNullable<ChartTheme['compactWhenShort']>['margin']>;
+  };
   heatmapChart: Required<NonNullable<ChartTheme['heatmapChart']>>;
 };
 /**
@@ -447,6 +460,12 @@ type AxisOptions = {
    * so callers can force a specific axis (e.g. integer-only steps on a sparse chart).
    */
   tickValues?: ScaleInput<AxisScale>[];
+  /**
+   * Most decimal places a value-axis tick may carry, so labels rounded to that precision never repeat;
+   * an axis holding fewer than two steps widens to the nearest ones. Whole-number data always uses 0.
+   * Ignored on a log scale, or when `tickValues` or the value scale's `domain` is set. Line and bar charts only.
+   */
+  tickDecimals?: number;
   axisClassName?: string;
   axisLineClassName?: string;
   labelClassName?: string;
@@ -626,6 +645,17 @@ interface SeriesVisibilityProps {
    */
   defaultHiddenSeries?: readonly string[];
 }
+/**
+ * Compact mode for cartesian charts placed in short containers.
+ */
+interface CompactWhenShortProps {
+  /**
+   * Drop the axes, grid and legend, and default to `theme.compactWhenShort.margin`, while the
+   * chart is shorter than `theme.compactWhenShort.below`. Series hidden through the legend stay
+   * hidden until the chart is tall again. Horizontal bar charts ignore it.
+   */
+  compactWhenShort?: boolean;
+}
 /**
  * Base properties shared across all chart components
  */
@@ -785,7 +815,15 @@ type BaseLegendItem = {
   interactive?: boolean;
   /** Label of the series this static item describes; the item is left out while it is hidden. */
   describesSeries?: string;
-};
+} & ({
+  /** Pressed state of the toggle. */
+  pressed: boolean;
+  /** Makes an interactive legend item a toggle the consumer controls, instead of a series toggle. */
+  onToggle: () => void;
+} | {
+  pressed?: never;
+  onToggle?: never;
+});
 export declare const Legend: import("react").ForwardRefExoticComponent<Omit<BaseLegendProps, "items"> & {
   items?: BaseLegendItem[];
   chartId?: string;
@@ -925,7 +963,7 @@ type RenderLineGlyphProps<Datum extends object> = GlyphProps<Datum> & {
   glyphStyle?: SVGProps<SVGCircleElement>;
   position?: 'start' | 'end';
 };
-interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
+interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps, CompactWhenShortProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -978,7 +1016,7 @@ type TooltipDatum = {
   /** The series' reading, or null when the bucket has none. */
   value: number | null;
 };
-interface AreaChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
+interface AreaChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps, CompactWhenShortProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -1081,7 +1119,7 @@ type BandHighlightSelection = {
   width: number;
   height: number;
 };
-interface BarChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
+interface BarChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps, CompactWhenShortProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -1130,13 +1168,15 @@ type BarLegendOptions = Omit<ChartLegendOptions, 'seriesColors'> & {
 /**
  * Builds legend items that match `BarChart`'s bars in a layout, for a custom legend or a chart's own.
  *
- * @param data        - The series the chart draws.
+ * @param allData     - The chart's series; those the layout does not draw get no item.
  * @param options     - The legend options, and the layout the bars are drawn in.
  * @param legendShape - The shape of the legend swatches.
  * @return The legend items.
  */
-export declare function useBarLegendItems(data: SeriesData[], options?: BarLegendOptions, legendShape?: LegendShape<SeriesData[], number>): BaseLegendItem[];
+export declare function useBarLegendItems(allData: SeriesData[], options?: BarLegendOptions, legendShape?: LegendShape<SeriesData[], number>): BaseLegendItem[];
 interface BarListChartProps extends Exclude<BarChartProps, 'orientation' | 'size' | 'gridVisibility'> {
+  /** Bar lists are always horizontal, and horizontal bars ignore `compactWhenShort`. */
+  compactWhenShort?: never;
   options?: {
     /**
      * Scale for the y axis. Exclude the type property.
@@ -1603,6 +1643,11 @@ interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, '
    * Whether to overlay the label on top of bar
    */
   withOverlayLabel?: boolean;
+  /**
+   * How a negative value draws: `diverge` puts every row on a shared zero point, `clamp` draws it as an empty bar.
+   * @default 'diverge'
+   */
+  negativeBars?: 'diverge' | 'clamp';
   /**
    * Primary color for current period bars
    */