@eifi1/ui-kit 0.11.0 → 0.12.0

package/dist/components/pie-chart.js

@@ -0,0 +1,283 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { Pie, PieChart as RechartsPieChart, Sector } from "recharts";
+import { cn } from "../lib/cn.js";
+import { horizontalStep } from "../lib/direction.js";
+import { useKitLabels, useKitLocale } from "../i18n/kit-labels.js";
+import { paletteFor } from "../theme/chart-palette.js";
+import { ChartContainer, ChartTooltip, ChartTooltipContent } from "./chart.js";
+import { DEFAULT_PIE_CHART_LABELS } from "./pie-chart-labels.js";
+import { StaticLegend, ToggleLegend, toggleHidden } from "./toggle-legend.js";
+const PIE_CONFIG = {};
+const RADIAN = Math.PI / 180;
+function RedactedTooltipContent(props) {
+  return /* @__PURE__ */ jsx("div", { "data-private": true, children: /* @__PURE__ */ jsx(ChartTooltipContent, { ...props }) });
+}
+function PieChart({
+  data,
+  variant = "donut",
+  height = 300,
+  formatValue: formatValueProp,
+  sliceLabels = "percent",
+  minLabelShare = 0.04,
+  center = true,
+  centerLabel,
+  centerValue,
+  legend = "toggle",
+  hiddenSlices: hiddenProp,
+  onHiddenSlicesChange,
+  onSliceClick,
+  redact = false,
+  empty,
+  locale: localeProp,
+  labels: labelsProp,
+  className,
+  style,
+  ...rest
+}) {
+  const labels = useKitLabels("pieChart", DEFAULT_PIE_CHART_LABELS, labelsProp);
+  const locale = useKitLocale(localeProp);
+  const numberFormat = useMemo(() => new Intl.NumberFormat(locale), [locale]);
+  const percentFormats = useMemo(
+    () => ({
+      whole: new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 0 }),
+      fine: new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 })
+    }),
+    [locale]
+  );
+  const formatValue = useCallback(
+    (v) => formatValueProp ? formatValueProp(v) : numberFormat.format(v),
+    [formatValueProp, numberFormat]
+  );
+  const formatShare = useCallback(
+    (share) => (share < 0.1 ? percentFormats.fine : percentFormats.whole).format(share),
+    [percentFormats]
+  );
+  const [ownHidden, setOwnHidden] = useState(() => /* @__PURE__ */ new Set());
+  const hidden = hiddenProp ?? ownHidden;
+  const toggle = (key) => {
+    const next = toggleHidden(hidden, key);
+    if (hiddenProp === void 0) setOwnHidden(next);
+    onHiddenSlicesChange?.(next);
+  };
+  const { drawable, drawn, total, pieData } = useMemo(() => {
+    const drawable2 = data.map((slice, i) => ({ slice, value: slice.value, color: slice.color ?? paletteFor(i) })).filter(
+      (d) => typeof d.value === "number" && Number.isFinite(d.value) && d.value > 0
+    );
+    const shown = drawable2.filter((d) => !hidden.has(d.slice.key));
+    const total2 = shown.reduce((acc, d) => acc + d.value, 0);
+    const drawn2 = shown.map((d) => ({ ...d, share: total2 > 0 ? d.value / total2 : 0 }));
+    const pieData2 = drawn2.map((d) => ({
+      key: d.slice.key,
+      label: d.slice.label,
+      value: d.value,
+      fill: d.color
+    }));
+    return { drawable: drawable2, drawn: drawn2, total: total2, pieData: pieData2 };
+  }, [data, hidden]);
+  const [stop, setStop] = useState(0);
+  const [focused, setFocused] = useState(void 0);
+  const current = Math.min(stop, Math.max(0, drawn.length - 1));
+  const refs = useRef([]);
+  const focusedSlice = focused !== void 0 ? drawn[focused] : void 0;
+  const clickRef = useRef(onSliceClick);
+  useLayoutEffect(() => {
+    clickRef.current = onSliceClick;
+  });
+  const clickable = onSliceClick !== void 0;
+  const shape = useCallback(
+    (props) => {
+      const {
+        index,
+        isActive: _isActive,
+        tabIndex: _tabIndex,
+        animationElapsedTime: _elapsed,
+        isAnimating: _animating,
+        isEntrance: _entrance,
+        // recharts hands the shape its own React `key` among the props. Spread into
+        // JSX, a `key` inside a props object is a warning on every render (React 19),
+        // so it is lifted out here and passed on its own.
+        key,
+        ...sector
+      } = props;
+      const d = drawn[index];
+      if (!d) return /* @__PURE__ */ jsx(Sector, { ...sector }, key ?? void 0);
+      const onKeyDown = (event) => {
+        const step = horizontalStep(event.key, event.currentTarget);
+        let target;
+        if (step) target = index + step;
+        else if (event.key === "ArrowDown") target = index + 1;
+        else if (event.key === "ArrowUp") target = index - 1;
+        else if (event.key === "Home") target = 0;
+        else if (event.key === "End") target = drawn.length - 1;
+        if (target !== void 0) {
+          event.preventDefault();
+          refs.current[(target % drawn.length + drawn.length) % drawn.length]?.focus();
+        } else if (clickable && (event.key === "Enter" || event.key === " ")) {
+          event.preventDefault();
+          clickRef.current?.(d.slice.key, d.slice);
+        }
+      };
+      return /* @__PURE__ */ jsx(
+        "g",
+        {
+          ref: (node) => {
+            refs.current[index] = node;
+          },
+          role: clickable ? "button" : "img",
+          tabIndex: index === 0 ? 0 : -1,
+          "aria-label": labels.slice(d.slice.label, formatValue(d.value), formatShare(d.share)),
+          "data-slice": d.slice.key,
+          onKeyDown,
+          onFocus: () => {
+            setStop(index);
+            setFocused(index);
+          },
+          onBlur: () => setFocused(void 0),
+          className: "outline-none [&:focus-visible>path]:stroke-[var(--text-primary)]",
+          children: /* @__PURE__ */ jsx(Sector, { ...sector }, key ?? void 0)
+        }
+      );
+    },
+    [drawn, labels, formatValue, formatShare, clickable]
+  );
+  const label = useCallback(
+    (props) => {
+      const d = drawn[props.index ?? -1];
+      const cx = Number(props.cx);
+      const cy = Number(props.cy);
+      const radius = Number(props.outerRadius);
+      const mid = Number(props.midAngle);
+      if (!d || d.share < minLabelShare || ![cx, cy, radius, mid].every(Number.isFinite)) return null;
+      const r = radius + 10;
+      const x = cx + r * Math.cos(-mid * RADIAN);
+      const y = cy + r * Math.sin(-mid * RADIAN);
+      const isValue = sliceLabels === "value";
+      return /* @__PURE__ */ jsx(
+        "text",
+        {
+          x,
+          y,
+          textAnchor: x >= cx ? "start" : "end",
+          dominantBaseline: "central",
+          fontSize: 11,
+          fill: "var(--text-secondary)",
+          "data-private": redact && isValue ? "" : void 0,
+          style: { pointerEvents: "none" },
+          children: isValue ? formatValue(d.value) : formatShare(d.share)
+        }
+      );
+    },
+    [drawn, minLabelShare, sliceLabels, redact, formatValue, formatShare]
+  );
+  const withLabels = sliceLabels !== "none";
+  const outer = withLabels ? 72 : 88;
+  const inner = variant === "donut" ? Math.round(outer * 0.6) : 0;
+  const pie = useMemo(
+    () => /* @__PURE__ */ jsx(
+      Pie,
+      {
+        data: pieData,
+        dataKey: "value",
+        nameKey: "label",
+        cx: "50%",
+        cy: "50%",
+        outerRadius: `${outer}%`,
+        innerRadius: `${inner}%`,
+        startAngle: 90,
+        endAngle: -270,
+        stroke: "var(--bg-surface)",
+        strokeWidth: 2,
+        rootTabIndex: -1,
+        isAnimationActive: false,
+        shape,
+        label: withLabels ? label : false,
+        labelLine: false,
+        onClick: clickable ? (_entry, index) => {
+          const d = drawn[index];
+          if (d) clickRef.current?.(d.slice.key, d.slice);
+        } : void 0
+      }
+    ),
+    [pieData, drawn, shape, label, withLabels, outer, inner, clickable]
+  );
+  useEffect(() => {
+    refs.current.forEach((el, i) => el?.setAttribute("tabindex", i === current ? "0" : "-1"));
+  });
+  const legendEntries = drawable.map((d) => ({
+    key: d.slice.key,
+    label: d.slice.label,
+    color: d.color
+  }));
+  const emptyBox = /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: "flex items-center justify-center text-sm text-[var(--text-muted)]",
+      style: { height },
+      children: empty ?? labels.empty
+    }
+  );
+  if (drawable.length === 0) {
+    return /* @__PURE__ */ jsx("div", { ...rest, className: cn("w-full", className), style, children: emptyBox });
+  }
+  const Content = redact ? RedactedTooltipContent : ChartTooltipContent;
+  return /* @__PURE__ */ jsxs("div", { ...rest, className: cn("w-full", className), style, children: [
+    drawn.length === 0 ? (
+      // Every slice switched off: the legend below is how they come back.
+      emptyBox
+    ) : /* @__PURE__ */ jsxs("div", { role: "group", "aria-label": labels.slices, className: "relative", style: { height }, children: [
+      /* @__PURE__ */ jsx(
+        ChartContainer,
+        {
+          config: PIE_CONFIG,
+          className: cn("h-full", clickable && "[&_.recharts-pie-sector]:cursor-pointer"),
+          children: /* @__PURE__ */ jsxs(RechartsPieChart, { accessibilityLayer: false, children: [
+            /* @__PURE__ */ jsx(
+              ChartTooltip,
+              {
+                content: /* @__PURE__ */ jsx(
+                  Content,
+                  {
+                    hideLabel: true,
+                    valueFormatter: (v) => `${formatValue(v)} (${formatShare(total > 0 ? v / total : 0)})`
+                  }
+                )
+              }
+            ),
+            pie
+          ] })
+        }
+      ),
+      variant === "donut" && center && /* @__PURE__ */ jsxs(
+        "div",
+        {
+          "data-private": redact ? "" : void 0,
+          "aria-hidden": focusedSlice ? true : void 0,
+          className: "pointer-events-none absolute inset-0 flex flex-col items-center justify-center text-center",
+          children: [
+            /* @__PURE__ */ jsx("span", { className: "max-w-[40%] truncate text-xs text-[var(--text-muted)]", children: focusedSlice ? focusedSlice.slice.label : centerLabel ?? labels.total }),
+            /* @__PURE__ */ jsx("span", { className: "max-w-[40%] truncate text-lg font-semibold tabular-nums text-[var(--text-primary)]", children: focusedSlice ? formatValue(focusedSlice.value) : centerValue ?? formatValue(total) }),
+            focusedSlice && /* @__PURE__ */ jsx("span", { className: "text-xs tabular-nums text-[var(--text-muted)]", children: formatShare(focusedSlice.share) })
+          ]
+        }
+      )
+    ] }),
+    legend === "toggle" && /* @__PURE__ */ jsx(
+      ToggleLegend,
+      {
+        entries: legendEntries,
+        hidden,
+        onToggle: toggle,
+        showSingle: true,
+        className: "justify-center",
+        labels: { legend: labels.legend }
+      }
+    ),
+    legend === "static" && /* @__PURE__ */ jsx(StaticLegend, { entries: legendEntries, className: "justify-center", "aria-label": labels.legend })
+  ] });
+}
+export {
+  PieChart
+};
+//# sourceMappingURL=pie-chart.js.map

package/dist/components/pie-chart.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/pie-chart.tsx"],"sourcesContent":["// A part-to-whole chart: a donut (or a full pie), one slice per category, its ANGLE\n// the category's share of what is drawn. Lifted out of kastlan, where the dashboard's\n// occupancy card and the reports' maintenance card each drew a recharts `<Pie>` by\n// hand inside the kit's `ChartContainer` — with a legend that could not switch\n// anything, slices a keyboard could not reach, and colours from a local hex list.\n//\n// It uses the kit's own chart shell (`ChartContainer`, `ChartTooltipContent`) and\n// ramp (`paletteFor`), so it re-skins with the palette like every other chart, and the\n// kit's own legends (`ToggleLegend`, `StaticLegend`).\nimport { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from \"react\";\nimport type { ComponentProps, ComponentPropsWithoutRef, KeyboardEvent, ReactNode } from \"react\";\nimport { Pie, PieChart as RechartsPieChart, Sector } from \"recharts\";\nimport type { PieLabelRenderProps, PieSectorShapeProps } from \"recharts\";\nimport { cn } from \"../lib/cn\";\nimport { horizontalStep } from \"../lib/direction\";\nimport { useKitLabels, useKitLocale } from \"../i18n/kit-labels\";\nimport { paletteFor } from \"../theme/chart-palette\";\nimport { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from \"./chart\";\nimport { DEFAULT_PIE_CHART_LABELS, type PieChartLabels } from \"./pie-chart-labels\";\nimport { StaticLegend, ToggleLegend, toggleHidden, type LegendEntry } from \"./toggle-legend\";\n\n/** One slice. */\nexport interface PieChartSlice {\n  /** Stable key, handed back by {@link PieChartProps.onSliceClick} and used by the\n   *  legend's hidden set. Labels can collide; keys must not. */\n  key: string;\n  /** What the slice is called — in the legend, the tooltip and its accessible name. */\n  label: string;\n  /**\n   * The slice's size. A value that is not a positive finite number — `null` for a\n   * figure that is missing, a zero, a negative — is NOT drawn and not in the legend:\n   * an angle cannot be negative, and a zero-degree slice is one a pointer and a\n   * keyboard would both stop on to find nothing.\n   */\n  value: number | null | undefined;\n  /** Overrides the by-index palette colour (`paletteFor(i)`, `i` the slice's index in\n   *  `data` AS GIVEN) — a status that has a colour of its own. Any CSS colour. */\n  color?: string;\n}\n\n/**\n * Everything a `<div>` takes reaches the chart's root, so a test id or a `data-tour`\n * anchor can find it. `children` is the chart's own.\n */\nexport interface PieChartProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"children\"> {\n  data: readonly PieChartSlice[];\n  /** `\"donut\"` (default) leaves a hole with the total in it; `\"pie\"` is the full disc. */\n  variant?: \"donut\" | \"pie\";\n  /** Height of the plot in px (the legend is under it). Default 300. */\n  height?: number;\n  /** How a value is written in the tooltip, the slice's name, a `\"value\"` slice label\n   *  and the donut's total. Default: `Intl.NumberFormat` in `locale`. */\n  formatValue?: (value: number) => string;\n  /**\n   * What is written beside each slice: its share (`\"percent\"`, the default), its\n   * value, or nothing. Only on slices of at least {@link minLabelShare} — a label on a\n   * sliver sits on its neighbour's. The figure is in the tooltip and the slice's name\n   * either way.\n   */\n  sliceLabels?: \"percent\" | \"value\" | \"none\";\n  /** The smallest share (0–1) that gets a slice label. Default 0.04. */\n  minLabelShare?: number;\n  /** Draw the donut's centre: {@link centerLabel} over {@link centerValue}. Default\n   *  `true`; ignored for `variant=\"pie\"`, which has no centre to draw in. */\n  center?: boolean;\n  /** The caption in the donut's centre. Default: `labels.total`. */\n  centerLabel?: ReactNode;\n  /** The figure in the donut's centre. Default: the drawn total through `formatValue`. */\n  centerValue?: ReactNode;\n  /**\n   * The legend under the chart. `\"toggle\"` (default): each entry is a switch that\n   * takes its slice off the chart, and the percentages are then of what is left —\n   * the shares always read \"of this picture\". `\"static\"`: a key with nothing to press.\n   */\n  legend?: \"toggle\" | \"static\" | \"none\";\n  /** The slices switched off, for a caller that owns the set (a URL, a saved view).\n   *  Left out, the chart keeps its own. */\n  hiddenSlices?: ReadonlySet<string>;\n  /** Called with the new hidden set whenever the legend switches a slice. */\n  onHiddenSlicesChange?: (hidden: ReadonlySet<string>) => void;\n  /** A slice was activated — by click, or Enter/Space on a focused slice. Makes each\n   *  slice a `role=\"button\"`. */\n  onSliceClick?: (key: string, slice: PieChartSlice) => void;\n  /**\n   * Tag every figure ON SCREEN `data-private` — the tooltip bubble, the centre and\n   * `\"value\"` slice labels — so the host's demo-mode rule blurs it. A percentage alone\n   * reveals no amount, so `\"percent\"` labels stay readable, and the slices themselves\n   * are not tagged: a blurred ring is no picture at all.\n   */\n  redact?: boolean;\n  /** What to show with nothing to draw. Default: `labels.empty`. */\n  empty?: ReactNode;\n  /** BCP 47 tag for the numbers and percentages. Default: the provider's. */\n  locale?: string;\n  labels?: Partial<PieChartLabels>;\n}\n\n/** A slice as drawn: only the ones with a positive value, in `data` order. */\ninterface DrawnSlice {\n  slice: PieChartSlice;\n  value: number;\n  color: string;\n  /** Of what is drawn, 0–1. */\n  share: number;\n}\n\n// Slices carry their own `fill`, and `ChartTooltipContent` falls back to it for the\n// swatch, so no series config is needed — and none is wanted, because a config key is a\n// CSS identifier and a slice key is the caller's data (see `ChartStyle`).\nconst PIE_CONFIG: ChartConfig = {};\n\nconst RADIAN = Math.PI / 180;\n\n/** The shared tooltip with the bubble tagged `data-private` — see the treemap's\n *  `RedactedTooltipContent` for why it has to BE the element recharts clones. */\nfunction RedactedTooltipContent(props: ComponentProps<typeof ChartTooltipContent>) {\n  return (\n    <div data-private>\n      <ChartTooltipContent {...props} />\n    </div>\n  );\n}\n\n/**\n * Part-to-whole chart: a donut (or `variant=\"pie\"`), one slice per\n * {@link PieChartSlice}, coloured from the chart ramp by index.\n *\n * **Every slice is reachable from the keyboard.** The slices are ONE tab stop (a roving\n * tabindex, as in the kit's grids): ←/→ and ↑/↓ step to the next and previous slice —\n * clockwise from twelve o'clock, the order of the legend — with ←/→ following the\n * reading direction in RTL; Home/End go to the first and last. Each slice is named\n * \"Label: value (xx%)\" (`labels.slice`), because a colour and an angle are nothing a\n * screen reader can say, and focusing one reads it out in the donut's centre. With\n * `onSliceClick`, Enter and Space activate it as a click does.\n *\n * The legend switches slices off (`legend=\"toggle\"`); the percentages are always of\n * what is drawn. The plot is not mirrored in RTL (see `ChartContainer`); the legend\n * and the centre follow the page.\n *\n * With nothing to draw it says so (`empty`) rather than drawing an empty box.\n *\n * Needs `recharts`, like everything behind `@eifi1/ui-kit/chart`.\n */\nexport function PieChart({\n  data,\n  variant = \"donut\",\n  height = 300,\n  formatValue: formatValueProp,\n  sliceLabels = \"percent\",\n  minLabelShare = 0.04,\n  center = true,\n  centerLabel,\n  centerValue,\n  legend = \"toggle\",\n  hiddenSlices: hiddenProp,\n  onHiddenSlicesChange,\n  onSliceClick,\n  redact = false,\n  empty,\n  locale: localeProp,\n  labels: labelsProp,\n  className,\n  style,\n  ...rest\n}: PieChartProps) {\n  const labels = useKitLabels(\"pieChart\", DEFAULT_PIE_CHART_LABELS, labelsProp);\n  const locale = useKitLocale(localeProp);\n  const numberFormat = useMemo(() => new Intl.NumberFormat(locale), [locale]);\n  const percentFormats = useMemo(\n    () => ({\n      whole: new Intl.NumberFormat(locale, { style: \"percent\", maximumFractionDigits: 0 }),\n      fine: new Intl.NumberFormat(locale, { style: \"percent\", maximumFractionDigits: 1 }),\n    }),\n    [locale],\n  );\n  // Memoised, like everything the sectors are drawn from: they must not be rebuilt on\n  // this component's own re-renders (see `pie` below).\n  const formatValue = useCallback(\n    (v: number) => (formatValueProp ? formatValueProp(v) : numberFormat.format(v)),\n    [formatValueProp, numberFormat],\n  );\n  // One decimal under 10 %, where rounding to whole percents starts to lie — a slice\n  // of 0.4 % labelled \"0%\" says it is not there.\n  const formatShare = useCallback(\n    (share: number) => (share < 0.1 ? percentFormats.fine : percentFormats.whole).format(share),\n    [percentFormats],\n  );\n\n  const [ownHidden, setOwnHidden] = useState<ReadonlySet<string>>(() => new Set());\n  const hidden = hiddenProp ?? ownHidden;\n  const toggle = (key: string) => {\n    const next = toggleHidden(hidden, key);\n    if (hiddenProp === undefined) setOwnHidden(next);\n    onHiddenSlicesChange?.(next);\n  };\n\n  // Coloured by index into `data` AS GIVEN, before anything is dropped, so a slice\n  // keeps its colour when a neighbour is switched off or has no value.\n  const { drawable, drawn, total, pieData } = useMemo(() => {\n    const drawable = data\n      .map((slice, i) => ({ slice, value: slice.value, color: slice.color ?? paletteFor(i) }))\n      .filter((d): d is { slice: PieChartSlice; value: number; color: string } =>\n        typeof d.value === \"number\" && Number.isFinite(d.value) && d.value > 0,\n      );\n    const shown = drawable.filter((d) => !hidden.has(d.slice.key));\n    const total = shown.reduce((acc, d) => acc + d.value, 0);\n    const drawn: DrawnSlice[] = shown.map((d) => ({ ...d, share: total > 0 ? d.value / total : 0 }));\n    const pieData = drawn.map((d) => ({\n      key: d.slice.key,\n      label: d.slice.label,\n      value: d.value,\n      fill: d.color,\n    }));\n    return { drawable, drawn, total, pieData };\n  }, [data, hidden]);\n\n  // The roving tab stop, and the slice that has focus (which the centre reads out).\n  const [stop, setStop] = useState(0);\n  const [focused, setFocused] = useState<number | undefined>(undefined);\n  const current = Math.min(stop, Math.max(0, drawn.length - 1));\n  const refs = useRef<(SVGGElement | null)[]>([]);\n  const focusedSlice = focused !== undefined ? drawn[focused] : undefined;\n\n  // Read through a ref: the sectors are drawn once per `data`, and a caller's inline\n  // `onSliceClick` is a new function every render.\n  const clickRef = useRef(onSliceClick);\n  useLayoutEffect(() => {\n    clickRef.current = onSliceClick;\n  });\n  const clickable = onSliceClick !== undefined;\n\n  /**\n   * One sector, wrapped in its keyboard stop. recharts renders it inside a layer of its\n   * own that carries the pointer's hover and click, so those are untouched.\n   *\n   * Focus does NOT drive the recharts tooltip (`defaultIndex`), as it does in\n   * `SeriesChart`: an active pie sector is re-parented into an extra layer, which\n   * remounts this element and drops the focus it just took. The donut's centre is the\n   * keyboard's read-out instead.\n   */\n  const shape = useCallback(\n    (props: PieSectorShapeProps) => {\n      const {\n        index,\n        isActive: _isActive,\n        tabIndex: _tabIndex,\n        animationElapsedTime: _elapsed,\n        isAnimating: _animating,\n        isEntrance: _entrance,\n        // recharts hands the shape its own React `key` among the props. Spread into\n        // JSX, a `key` inside a props object is a warning on every render (React 19),\n        // so it is lifted out here and passed on its own.\n        key,\n        ...sector\n      } = props as PieSectorShapeProps & {\n        animationElapsedTime?: number;\n        isAnimating?: boolean;\n        isEntrance?: boolean;\n        key?: string | number | null;\n      };\n      const d = drawn[index];\n      if (!d) return <Sector key={key ?? undefined} {...sector} />;\n      const onKeyDown = (event: KeyboardEvent<SVGGElement>) => {\n        const step = horizontalStep(event.key, event.currentTarget);\n        let target: number | undefined;\n        if (step) target = index + step;\n        else if (event.key === \"ArrowDown\") target = index + 1;\n        else if (event.key === \"ArrowUp\") target = index - 1;\n        else if (event.key === \"Home\") target = 0;\n        else if (event.key === \"End\") target = drawn.length - 1;\n        if (target !== undefined) {\n          event.preventDefault();\n          // Round the circle: past the last slice is the first, as the eye goes.\n          refs.current[((target % drawn.length) + drawn.length) % drawn.length]?.focus();\n        } else if (clickable && (event.key === \"Enter\" || event.key === \" \")) {\n          event.preventDefault();\n          clickRef.current?.(d.slice.key, d.slice);\n        }\n      };\n      return (\n        <g\n          ref={(node) => {\n            refs.current[index] = node;\n          }}\n          role={clickable ? \"button\" : \"img\"}\n          // The first slice until the effect below moves the stop.\n          tabIndex={index === 0 ? 0 : -1}\n          aria-label={labels.slice(d.slice.label, formatValue(d.value), formatShare(d.share))}\n          data-slice={d.slice.key}\n          onKeyDown={onKeyDown}\n          onFocus={() => {\n            setStop(index);\n            setFocused(index);\n          }}\n          onBlur={() => setFocused(undefined)}\n          // CSS beats a presentation attribute, so this recolours the sector's own\n          // stroke for as long as it has keyboard focus.\n          className=\"outline-none [&:focus-visible>path]:stroke-[var(--text-primary)]\"\n        >\n          <Sector key={key ?? undefined} {...sector} />\n        </g>\n      );\n    },\n    [drawn, labels, formatValue, formatShare, clickable],\n  );\n\n  const label = useCallback(\n    (props: PieLabelRenderProps) => {\n      const d = drawn[props.index ?? -1];\n      const cx = Number(props.cx);\n      const cy = Number(props.cy);\n      const radius = Number(props.outerRadius);\n      const mid = Number(props.midAngle);\n      if (!d || d.share < minLabelShare || ![cx, cy, radius, mid].every(Number.isFinite)) return null;\n      const r = radius + 10;\n      const x = cx + r * Math.cos(-mid * RADIAN);\n      const y = cy + r * Math.sin(-mid * RADIAN);\n      const isValue = sliceLabels === \"value\";\n      return (\n        <text\n          x={x}\n          y={y}\n          textAnchor={x >= cx ? \"start\" : \"end\"}\n          dominantBaseline=\"central\"\n          fontSize={11}\n          fill=\"var(--text-secondary)\"\n          data-private={redact && isValue ? \"\" : undefined}\n          style={{ pointerEvents: \"none\" }}\n        >\n          {isValue ? formatValue(d.value) : formatShare(d.share)}\n        </text>\n      );\n    },\n    [drawn, minLabelShare, sliceLabels, redact, formatValue, formatShare],\n  );\n\n  const withLabels = sliceLabels !== \"none\";\n  // Room outside the ring for the labels, or the ring fills the box.\n  const outer = withLabels ? 72 : 88;\n  const inner = variant === \"donut\" ? Math.round(outer * 0.6) : 0;\n\n  /**\n   * The `<Pie>`, as ONE element for as long as what it draws is unchanged. recharts\n   * keys its sectors by an animation id that is renewed whenever the Pie's props object\n   * is — i.e. on every render of the Pie — so re-rendering it remounts every sector,\n   * the one with focus included, which dropped the focus to <body> on the very state\n   * update that focusing a slice makes. An unchanged element is one React does not\n   * re-render, so the sectors stay put, and the roving tab stop is moved on them in\n   * place (the effect below).\n   */\n  const pie = useMemo(\n    () => (\n      <Pie\n        data={pieData}\n        dataKey=\"value\"\n        nameKey=\"label\"\n        cx=\"50%\"\n        cy=\"50%\"\n        outerRadius={`${outer}%`}\n        innerRadius={`${inner}%`}\n        startAngle={90}\n        endAngle={-270}\n        // The card showing through between the slices, as the treemap's gutter.\n        stroke=\"var(--bg-surface)\"\n        strokeWidth={2}\n        rootTabIndex={-1}\n        isAnimationActive={false}\n        shape={shape}\n        label={withLabels ? label : false}\n        labelLine={false}\n        onClick={\n          clickable\n            ? (_entry: unknown, index: number) => {\n                const d = drawn[index];\n                if (d) clickRef.current?.(d.slice.key, d.slice);\n              }\n            : undefined\n        }\n      />\n    ),\n    [pieData, drawn, shape, label, withLabels, outer, inner, clickable],\n  );\n\n  // The roving tab stop, moved on the sectors in place (they are not re-rendered).\n  useEffect(() => {\n    refs.current.forEach((el, i) => el?.setAttribute(\"tabindex\", i === current ? \"0\" : \"-1\"));\n  });\n\n  const legendEntries: LegendEntry[] = drawable.map((d) => ({\n    key: d.slice.key,\n    label: d.slice.label,\n    color: d.color,\n  }));\n\n  const emptyBox = (\n    <div\n      className=\"flex items-center justify-center text-sm text-[var(--text-muted)]\"\n      style={{ height }}\n    >\n      {empty ?? labels.empty}\n    </div>\n  );\n\n  // Nothing drawable at all: no chart, and no legend of switches for nothing.\n  if (drawable.length === 0) {\n    return (\n      <div {...rest} className={cn(\"w-full\", className)} style={style}>\n        {emptyBox}\n      </div>\n    );\n  }\n\n  const Content = redact ? RedactedTooltipContent : ChartTooltipContent;\n\n  return (\n    <div {...rest} className={cn(\"w-full\", className)} style={style}>\n      {drawn.length === 0 ? (\n        // Every slice switched off: the legend below is how they come back.\n        emptyBox\n      ) : (\n        <div role=\"group\" aria-label={labels.slices} className=\"relative\" style={{ height }}>\n          <ChartContainer\n            config={PIE_CONFIG}\n            className={cn(\"h-full\", clickable && \"[&_.recharts-pie-sector]:cursor-pointer\")}\n          >\n            <RechartsPieChart accessibilityLayer={false}>\n              <ChartTooltip\n                content={\n                  <Content\n                    hideLabel\n                    valueFormatter={(v) =>\n                      `${formatValue(v)} (${formatShare(total > 0 ? v / total : 0)})`\n                    }\n                  />\n                }\n              />\n              {pie}\n            </RechartsPieChart>\n          </ChartContainer>\n          {variant === \"donut\" && center && (\n            <div\n              data-private={redact ? \"\" : undefined}\n              // While a slice has keyboard focus the centre reads it out — the\n              // keyboard's tooltip. Hidden from assistive technology then: the slice's\n              // own name has just said the same.\n              aria-hidden={focusedSlice ? true : undefined}\n              className=\"pointer-events-none absolute inset-0 flex flex-col items-center justify-center text-center\"\n            >\n              <span className=\"max-w-[40%] truncate text-xs text-[var(--text-muted)]\">\n                {focusedSlice ? focusedSlice.slice.label : (centerLabel ?? labels.total)}\n              </span>\n              <span className=\"max-w-[40%] truncate text-lg font-semibold tabular-nums text-[var(--text-primary)]\">\n                {focusedSlice ? formatValue(focusedSlice.value) : (centerValue ?? formatValue(total))}\n              </span>\n              {focusedSlice && (\n                <span className=\"text-xs tabular-nums text-[var(--text-muted)]\">\n                  {formatShare(focusedSlice.share)}\n                </span>\n              )}\n            </div>\n          )}\n        </div>\n      )}\n      {legend === \"toggle\" && (\n        <ToggleLegend\n          entries={legendEntries}\n          hidden={hidden}\n          onToggle={toggle}\n          showSingle\n          className=\"justify-center\"\n          labels={{ legend: labels.legend }}\n        />\n      )}\n      {legend === \"static\" && (\n        <StaticLegend entries={legendEntries} className=\"justify-center\" aria-label={labels.legend} />\n      )}\n    </div>\n  );\n}\n"],"mappings":"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","names":["drawable","total","drawn","pieData"]}

package/dist/components/progress-bar.d.ts

@@ -1,6 +1,14 @@
 import * as react from 'react';
 import { ComponentPropsWithoutRef, ReactNode } from 'react';
 
+/** The words a progress bar adds of its own. */
+interface ProgressBarLabels {
+    /** Shown after the value when `max={null}`: a quota with no ceiling. */
+    unlimited: string;
+    /** The `overage` line: how far past `max` the value is. `amount` is formatted. */
+    overLimit: (amount: string) => string;
+}
+declare const DEFAULT_PROGRESS_BAR_LABELS: ProgressBarLabels;
 /**
  * `income` / `expense` are the money pair (`--money-income` / `--money-expense`), the
  * names `Chip`, `StatTile` and `Sparkline` already use for them: a share bar of what
@@ -31,13 +39,27 @@ interface ProgressBarSegment {
     label?: ReactNode;
     /** A stable React key, when `label` is not a string. */
     key?: string;
+    /**
+     * List it in the `legend` but leave it out of the bar — its value, its share of the
+     * `aria-valuetext`, and the sum. keksdose's cut card (reports/cut-card:132) names
+     * EVERY bucket under its bar, the empty ones included, while the bar draws only the
+     * ones with a share: pass the empty buckets as `legendOnly` entries.
+     */
+    legendOnly?: boolean;
 }
 interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
     /** Where it stands. Leave it undefined for an INDETERMINATE bar — work is under way
      *  and nobody knows how much is left (an import that reports no count). */
     value?: number;
     min?: number;
-    max?: number;
+    /**
+     * The top of the scale (default 100). `null` is a quota with NO ceiling — kastlan's
+     * billing usage on an unlimited plan (usage-progress-bar:25): nothing to fill, so no
+     * bar is drawn; the label row shows the value and "Unlimited" (`progressBar.unlimited`)
+     * as plain text. `formatValue` is then called with `max` = `Infinity`; without it,
+     * the value is a plain number in the kit's locale.
+     */
+    max?: number | null;
     /**
      * `progress` (default): a task moving toward completion — `role="progressbar"`.
      * `meter`: a share of a known whole that is not going anywhere (budget used, disk
@@ -74,6 +96,25 @@ interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">, "childr
     /** With `segments`: a list under the bar naming each part with its swatch and value
      *  — the table view of the bar, in text tokens rather than the segment colour. */
     legend?: boolean;
+    /**
+     * What a legend row shows at its end, in place of the part's formatted value — which
+     * it is handed, with the segment and its index. keksdose's cut card shows the share
+     * AND a private outflow amount per bucket (cut-card:150), which one figure could not:
+     * `legendValue={(seg, share) => <>{share} <Amount … /></>}`.
+     */
+    legendValue?: (segment: ProgressBarSegment, formatted: string, index: number) => ReactNode;
+    /** A muted line under the bar — the plan's reset date, "3 of 5 seats in use". It
+     *  describes the bar (`aria-describedby`). */
+    hint?: ReactNode;
+    /**
+     * When `value` is past `max`, say by how much, in a danger-coloured line under the bar
+     * (kastlan usage-progress-bar:46): `true` prints `progressBar.overLimit` with the
+     * excess as a plain number; a function renders the line itself from the excess (a
+     * currency, "2 seats"). The bar stays full at `max` either way — colour it with
+     * `tone="danger"` if it should read as over. Ignored for `segments` and `max={null}`.
+     */
+    overage?: boolean | ((over: number) => ReactNode);
+    labels?: Partial<ProgressBarLabels>;
 }
 /**
  * A horizontal bar that fills toward `max`.
@@ -92,6 +133,6 @@ interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">, "childr
  * tokens.css's `.animate-indeterminate` class because that one is UNLAYERED, and an
  * unlayered rule beats every layered utility, `motion-reduce:animate-none` included.
  */
-declare function ProgressBar({ value, min, max, variant, label, showValue, formatValue, tone, size, locale, segments, legend, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...rest }: ProgressBarProps): react.JSX.Element;
+declare function ProgressBar({ value, min, max: maxProp, variant, label, showValue, formatValue, tone, size, locale, segments, legend, legendValue, hint, overage, labels, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...rest }: ProgressBarProps): react.JSX.Element;
 
-export { ProgressBar, type ProgressBarProps, type ProgressBarSegment, type ProgressBarSize, type ProgressBarTone };
+export { DEFAULT_PROGRESS_BAR_LABELS, ProgressBar, type ProgressBarLabels, type ProgressBarProps, type ProgressBarSegment, type ProgressBarSize, type ProgressBarTone };

package/dist/components/progress-bar.js

@@ -3,6 +3,10 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { useId } from "react";
 import { cn } from "../lib/cn.js";
 import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels.js";
+const DEFAULT_PROGRESS_BAR_LABELS = {
+  unlimited: "Unlimited",
+  overLimit: (amount) => `${amount} over the limit`
+};
 const FILL = {
   brand: "bg-[var(--brand)]",
   neutral: "bg-[var(--text-muted)]",
@@ -36,7 +40,7 @@ function segmentFills(segments) {
 function ProgressBar({
   value,
   min = 0,
-  max = 100,
+  max: maxProp = 100,
   variant = "progress",
   label,
   showValue = false,
@@ -46,26 +50,49 @@ function ProgressBar({
   locale,
   segments,
   legend = false,
+  legendValue,
+  hint,
+  overage,
+  labels,
   className,
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy,
   ...rest
 }) {
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const text = useKitLabels("progressBar", DEFAULT_PROGRESS_BAR_LABELS, labels);
   const kitLocale = useKitLocale(locale);
   const labelId = useId();
+  const hintId = useId();
+  const hintNode = hint != null ? /* @__PURE__ */ jsx("p", { id: hintId, "data-part": "hint", className: "mt-1 text-xs text-[var(--text-muted)]", children: hint }) : null;
+  if (maxProp === null) {
+    const shown = value === void 0 || !Number.isFinite(value) ? void 0 : formatValue ? formatValue(value, Infinity, min) : new Intl.NumberFormat(kitLocale).format(value);
+    return /* @__PURE__ */ jsxs("div", { ...rest, className: cn("min-w-0", className), "data-state": "unlimited", children: [
+      /* @__PURE__ */ jsxs("div", { className: "flex items-baseline gap-2 text-sm", children: [
+        label != null && /* @__PURE__ */ jsx("span", { id: labelId, className: "min-w-0 text-[var(--text-secondary)]", children: label }),
+        /* @__PURE__ */ jsxs("span", { "data-part": "unlimited", className: "ms-auto shrink-0 tabular-nums text-[var(--text-muted)]", children: [
+          shown !== void 0 && `${shown} \xB7 `,
+          text.unlimited
+        ] })
+      ] }),
+      hintNode
+    ] });
+  }
+  const max = maxProp;
   const stacked = segments !== void 0;
   const meter = stacked || variant === "meter";
   const span = max - min;
   const partValue = (v) => Number.isFinite(v) ? Math.max(0, v - min) : 0;
   const fills = stacked ? segmentFills(segments) : [];
-  const partTotal = stacked ? min + segments.reduce((sum, seg) => sum + partValue(seg.value), 0) : void 0;
+  const barParts = stacked ? segments.filter((seg) => !seg.legendOnly) : [];
+  const partTotal = stacked ? min + barParts.reduce((sum, seg) => sum + partValue(seg.value), 0) : void 0;
   const format = (v) => formatValue ? formatValue(v, max, min) : new Intl.NumberFormat(kitLocale, { style: "percent", maximumFractionDigits: 0 }).format(
     span <= 0 ? 0 : (Math.min(max, Math.max(min, v)) - min) / span
   );
-  const partTexts = stacked ? segments.map((seg) => {
-    const text = format(min + partValue(seg.value));
-    return typeof seg.label === "string" || typeof seg.label === "number" ? common.fieldValue(String(seg.label), text) : text;
+  const partTexts = stacked ? barParts.map((seg) => {
+    const text2 = format(min + partValue(seg.value));
+    return typeof seg.label === "string" || typeof seg.label === "number" ? common.fieldValue(String(seg.label), text2) : text2;
   }) : [];
   const current = partTotal ?? (value === void 0 || !Number.isFinite(value) ? meter ? min : void 0 : value);
   const indeterminate = current === void 0;
@@ -73,6 +100,9 @@ function ProgressBar({
   const fraction = clamped === void 0 || span <= 0 ? 0 : (clamped - min) / span;
   const valueText = clamped === void 0 ? void 0 : format(clamped);
   const ariaValueText = stacked && partTexts.length > 0 ? new Intl.ListFormat(kitLocale, { style: "short", type: "unit" }).format(partTexts) : valueText;
+  const over = overage && !stacked && value !== void 0 && Number.isFinite(value) && value > max ? value - max : 0;
+  const overageNode = over > 0 ? /* @__PURE__ */ jsx("p", { id: `${hintId}-over`, "data-part": "overage", className: "mt-1 text-xs text-[var(--danger)]", children: typeof overage === "function" ? overage(over) : text.overLimit(new Intl.NumberFormat(kitLocale).format(over)) }) : null;
+  const describedBy = [ariaDescribedBy, hintNode && hintId, overageNode && `${hintId}-over`].filter(Boolean).join(" ") || void 0;
   const labelledBy = ariaLabelledBy ?? (label != null ? labelId : void 0);
   const name = labelledBy ? void 0 : ariaLabel ?? (indeterminate ? common.loading : void 0);
   return /* @__PURE__ */ jsxs("div", { className: cn("min-w-0", className), "data-state": indeterminate ? "indeterminate" : "determinate", children: [
@@ -89,6 +119,7 @@ function ProgressBar({
         role: meter ? "meter" : "progressbar",
         "aria-label": name,
         "aria-labelledby": labelledBy,
+        "aria-describedby": describedBy,
         "aria-valuemin": indeterminate ? void 0 : min,
         "aria-valuemax": indeterminate ? void 0 : max,
         "aria-valuenow": clamped,
@@ -98,21 +129,23 @@ function ProgressBar({
         children: stacked ? (
           // The parts in a flex row with a 2px gap, so two neighbouring steps of one
           // hue are parted by the track rather than by their difference in lightness.
-          /* @__PURE__ */ jsx("div", { className: "flex h-full w-full gap-0.5", children: segments.map((seg, i) => /* @__PURE__ */ jsx(
-            "div",
-            {
-              "data-part": "segment",
-              className: cn(
-                "h-full shrink-0 rounded-full transition-[width] duration-300 motion-reduce:transition-none",
-                fills[i]
-              ),
-              style: {
-                width: `${span <= 0 ? 0 : partValue(seg.value) / span * 100}%`,
-                backgroundColor: seg.className ? void 0 : seg.color
-              }
-            },
-            seg.key ?? i
-          )) })
+          /* @__PURE__ */ jsx("div", { className: "flex h-full w-full gap-0.5", children: segments.map(
+            (seg, i) => seg.legendOnly ? null : /* @__PURE__ */ jsx(
+              "div",
+              {
+                "data-part": "segment",
+                className: cn(
+                  "h-full shrink-0 rounded-full transition-[width] duration-300 motion-reduce:transition-none",
+                  fills[i]
+                ),
+                style: {
+                  width: `${span <= 0 ? 0 : partValue(seg.value) / span * 100}%`,
+                  backgroundColor: seg.className ? void 0 : seg.color
+                }
+              },
+              seg.key ?? i
+            )
+          ) })
         ) : indeterminate ? /* @__PURE__ */ jsx(
           "div",
           {
@@ -152,11 +185,14 @@ function ProgressBar({
         }
       ),
       seg.label != null && /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-[var(--text-secondary)]", children: seg.label }),
-      /* @__PURE__ */ jsx("span", { className: "ms-auto shrink-0 text-xs tabular-nums text-[var(--text-muted)]", children: format(min + partValue(seg.value)) })
-    ] }, seg.key ?? i)) })
+      /* @__PURE__ */ jsx("span", { className: "ms-auto shrink-0 text-xs tabular-nums text-[var(--text-muted)]", children: legendValue ? legendValue(seg, format(min + partValue(seg.value)), i) : format(min + partValue(seg.value)) })
+    ] }, seg.key ?? i)) }),
+    overageNode,
+    hintNode
   ] });
 }
 export {
+  DEFAULT_PROGRESS_BAR_LABELS,
   ProgressBar
 };
 //# sourceMappingURL=progress-bar.js.map