@cdx-ui/components 0.3.5 → 0.3.6

package/docs/components/pie-chart/content.md

@@ -0,0 +1,493 @@
+# Pie Chart (https://design.candescent.com/docs/components/pie-chart)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/charts-piechart--default)
+
+`PieChart` takes MUI X–shaped `series`: one series with a `data` array of `{ id, value, label?, color? }` slices. Give every slice a stable `id`; keys, selection, and animation follow it. The [Insights Overview](https://design.candescent.com/docs/patterns/dashboard/content.md#insights-overview) pattern uses a small donut as a progress ring and a donut with a list legend.
+
+```tsx
+import { PieChart } from '@cdx-ui/components';
+```
+
+## Basic
+
+A filled pie with a wrapping chip legend under the chart (`legendLayout="wrap"`). Each chip is the name and share. Hover a slice, or press and hold it on touch screens, for the tooltip.
+
+```tsx
+import { PieChart } from '@cdx-ui/components';
+import { SPENDING } from './_data';
+
+export default function PieChartBasicDemo() {
+  return <PieChart series={[{ id: 'spending', data: SPENDING }]} />;
+}
+```
+
+## Sizes
+
+`size` picks a preset plot box: `sm`, `md`, `lg` (the default), or `xl`. `width` and `height` override one side.
+
+```tsx
+import { useState } from 'react';
+import { Box, PieChart, Slider, VStack } from '@cdx-ui/components';
+import { VISITS } from './_data';
+
+const SIZES = ['sm', 'md', 'lg', 'xl'] as const;
+
+export default function PieChartSizesDemo() {
+  const [index, setIndex] = useState(2);
+  const size = SIZES[index] ?? 'lg';
+
+  return (
+    <VStack space="2xl" className="w-full items-center">
+      <Box className="w-full max-w-xs">
+        <Slider
+          value={index}
+          onChange={setIndex}
+          min={0}
+          max={SIZES.length - 1}
+          step={1}
+          accessibilityLabel="Chart size"
+        >
+          <Slider.Rail>
+            <Slider.Track />
+          </Slider.Rail>
+          <Slider.Thumb>
+            <Slider.Popup>{size}</Slider.Popup>
+          </Slider.Thumb>
+          <Slider.MarkerGroup>
+            <Slider.Marker />
+          </Slider.MarkerGroup>
+        </Slider>
+      </Box>
+      <PieChart
+        key={size}
+        series={[
+          { id: 'visits', data: VISITS, innerRadius: '60%', paddingAngle: 2, cornerRadius: 4 },
+        ]}
+        size={size}
+      />
+    </VStack>
+  );
+}
+```
+
+## Donut
+
+A series `innerRadius` above `0` opens a hole for `centerLabel`. `paddingAngle` leaves a gap between slices in degrees; `cornerRadius` rounds the cut ends.
+
+```tsx
+import { Box, PieChart, Text } from '@cdx-ui/components';
+import { SPENDING } from './_data';
+
+export default function PieChartDonutDemo() {
+  return (
+    <PieChart
+      series={[
+        { id: 'spending', data: SPENDING, innerRadius: '68%', paddingAngle: 2, cornerRadius: 6 },
+      ]}
+      centerLabel={
+        <Box className="items-center">
+          <Text size="xs" color="secondary">
+            Total
+          </Text>
+          <Text weight="medium">$3,872.64</Text>
+        </Box>
+      }
+    />
+  );
+}
+```
+
+## Slice colors
+
+A slice's `color` takes a chart token (`simple-*`, `categorical-*`) or a severity token (`danger`, `warning`, `success`, `info`). Give severity tokens only to the slices the reader should act on, and keep the rest in the brand family. A slice without `color` takes the next `categorical-1`…`6` slot.
+
+```tsx
+import { Box, PieChart, Text } from '@cdx-ui/components';
+
+export default function PieChartColorsDemo() {
+  return (
+    <PieChart
+      series={[
+        {
+          id: 'charges',
+          innerRadius: '68%',
+          paddingAngle: 2,
+          cornerRadius: 6,
+          data: [
+            { id: 'purchases', label: 'Purchases', value: 1240, color: 'simple-primary' },
+            { id: 'interest', label: 'Interest', value: 310, color: 'warning' },
+            { id: 'late-fees', label: 'Late fees', value: 140, color: 'danger' },
+          ],
+        },
+      ]}
+      centerLabel={
+        <Box className="items-center">
+          <Text size="xs" color="secondary">
+            Late fees
+          </Text>
+          <Text weight="medium">$140</Text>
+        </Box>
+      }
+      accessibilityLabel="Card charges this statement. Late fees were $140."
+    />
+  );
+}
+```
+
+## Legend list
+
+`legendLayout="list"` is the spending-breakdown pattern: name on the left, amount and share on the right. The series `valueFormatter` paints the amount column. It is a `(value, context) => string`, not a currency prop.
+
+```tsx
+import { Box, PieChart, Text } from '@cdx-ui/components';
+import { formatUsdValue, SPENDING } from './_data';
+
+export default function PieChartLegendListDemo() {
+  return (
+    <PieChart
+      series={[
+        {
+          id: 'spending',
+          data: SPENDING,
+          innerRadius: '68%',
+          paddingAngle: 2,
+          cornerRadius: 6,
+          valueFormatter: formatUsdValue,
+        },
+      ]}
+      legendLayout="list"
+      centerLabel={
+        <Box className="items-center">
+          <Text size="xs" color="secondary">
+            Total
+          </Text>
+          <Text weight="medium">$3,872.64</Text>
+        </Box>
+      }
+    />
+  );
+}
+```
+
+## Legend placement
+
+`legendPlacement` matches Drawer (`top`, `bottom`, `left`, `right`). Left and right are swatch plus name only; `legendLayout` is ignored. Switch placements to compare them.
+
+```tsx
+import { useState } from 'react';
+import {
+  Box,
+  PieChart,
+  Text,
+  ToggleButton,
+  VStack,
+  type PieChartLegendPlacement,
+} from '@cdx-ui/components';
+import { SPENDING } from './_data';
+
+const PLACEMENTS: readonly PieChartLegendPlacement[] = ['top', 'bottom', 'left', 'right'];
+
+const LABELS: Record<PieChartLegendPlacement, string> = {
+  top: 'Top',
+  bottom: 'Bottom',
+  left: 'Left',
+  right: 'Right',
+};
+
+export default function PieChartLegendPlacementDemo() {
+  const [placement, setPlacement] = useState<PieChartLegendPlacement>('right');
+
+  return (
+    <VStack space="3xl" className="w-full items-center">
+      <ToggleButton.Group
+        type="single"
+        value={placement}
+        onValueChange={(value) => {
+          const next = PLACEMENTS.find((item) => item === value);
+          if (next) {
+            setPlacement(next);
+          }
+        }}
+        aria-label="Legend placement"
+        className="self-center"
+      >
+        {PLACEMENTS.map((item) => (
+          <ToggleButton key={item} value={item}>
+            <ToggleButton.Label>{LABELS[item]}</ToggleButton.Label>
+          </ToggleButton>
+        ))}
+      </ToggleButton.Group>
+      <PieChart
+        series={[
+          { id: 'spending', data: SPENDING, innerRadius: '68%', paddingAngle: 2, cornerRadius: 6 },
+        ]}
+        size="md"
+        legendPlacement={placement}
+        centerLabel={
+          <Box className="items-center">
+            <Text size="xs" color="secondary">
+              Total
+            </Text>
+            <Text weight="medium">$3,872.64</Text>
+          </Box>
+        }
+      />
+    </VStack>
+  );
+}
+```
+
+## Format value
+
+`valueFormatter` formats the amount in the legend, tooltip, and screen reader text; `context.location` says which (`label`, `tooltip`, `a11y`). `shareFormatter` formats the share column the same way.
+
+```tsx
+import { PieChart } from '@cdx-ui/components';
+import { VISITS } from './_data';
+
+export default function PieChartFormatValueDemo() {
+  return (
+    <PieChart
+      series={[
+        {
+          id: 'visits',
+          label: 'Visits',
+          data: VISITS,
+          innerRadius: '68%',
+          valueFormatter: (value) => (value === null ? '' : `${String(value)} visits`),
+          shareFormatter: (share) => `${(share * 100).toFixed(1)}%`,
+        },
+      ]}
+      legendLayout="list"
+      centerLabel="246"
+    />
+  );
+}
+```
+
+## Locale
+
+`locale` sets the default number and percent format. `localeText` replaces generated strings such as the screen reader summary.
+
+```tsx
+import { PieChart } from '@cdx-ui/components';
+import { SPENDING } from './_data';
+
+export default function PieChartLocaleDemo() {
+  return (
+    <PieChart
+      series={[{ id: 'ausgaben', data: SPENDING, innerRadius: '68%' }]}
+      legendLayout="list"
+      locale="de-DE"
+      localeText={{
+        pieChartSummary: (slices) =>
+          `Kreisdiagramm. ${slices.map((slice) => `${slice.label} ${slice.formattedValue}`).join(', ')}.`,
+      }}
+    />
+  );
+}
+```
+
+## Selectable
+
+Pass `selectedItem` and `onSelectedItemChange` (or `defaultSelectedItem`) to dim unselected slices. The item is `{ seriesId, dataIndex }`; pressing the selected slice again reports `null`.
+
+Hovering or focusing a slice or legend row previews it without changing the selection; click, tap, or Enter commits. Pass `centerLabel` as a function to follow that preview: it receives the active slice (`id`, `dataIndex`, `label`, `value`, `percentage`), falling back to the selected one, or `null` when neither exists.
+
+```tsx
+import { useState } from 'react';
+import { Box, PieChart, Text, VStack, type ChartSelectedItem } from '@cdx-ui/components';
+import { formatUsd, SPENDING } from './_data';
+
+export default function PieChartSelectableDemo() {
+  const [selectedItem, setSelectedItem] = useState<ChartSelectedItem>({
+    seriesId: 'spending',
+    dataIndex: 0,
+  });
+
+  return (
+    <VStack space="md" className="w-full">
+      <Text size="sm" color="secondary">
+        {selectedItem ? (SPENDING[selectedItem.dataIndex]?.label ?? 'None') : 'None'}
+      </Text>
+      <PieChart
+        series={[
+          { id: 'spending', data: SPENDING, innerRadius: '68%', paddingAngle: 2, cornerRadius: 6 },
+        ]}
+        selectedItem={selectedItem}
+        onSelectedItemChange={setSelectedItem}
+        centerLabel={(slice) =>
+          slice ? (
+            <Box className="items-center">
+              <Text size="xs" color="secondary">
+                {slice.label}
+              </Text>
+              <Text weight="medium">{formatUsd(slice.value)}</Text>
+            </Box>
+          ) : null
+        }
+      />
+    </VStack>
+  );
+}
+```
+
+## Data change
+
+Slices tween to their new shares when `data` changes. Keep each slice's `id` stable: animation follows it, so a reordered slice moves to its new position instead of remounting. Pass `animation="disable-all"` to draw the final state; Reduce Motion and `GlobalAnimationSettingsProvider` `disable-all` also turn it off.
+
+```tsx
+import { useState } from 'react';
+import { Button, HStack, PieChart, VStack } from '@cdx-ui/components';
+import { SPENDING } from './_data';
+
+export default function PieChartDataChangeDemo() {
+  const [step, setStep] = useState(0);
+  const [reversed, setReversed] = useState(false);
+  const shifted = SPENDING.map((slice, index) => ({
+    ...slice,
+    value: SPENDING[(index + step) % SPENDING.length]?.value ?? slice.value,
+  }));
+  const data = reversed ? [...shifted].reverse() : shifted;
+
+  return (
+    <VStack space="lg" className="w-full items-center">
+      <PieChart
+        series={[{ id: 'spending', data, innerRadius: '68%', paddingAngle: 2, cornerRadius: 6 }]}
+      />
+      <HStack space="sm" className="flex-wrap justify-center">
+        <Button
+          variant="outline"
+          onPress={() => {
+            setStep((prev) => prev + 1);
+          }}
+        >
+          <Button.Label>Shift data</Button.Label>
+        </Button>
+        <Button
+          variant="outline"
+          onPress={() => {
+            setReversed((prev) => !prev);
+          }}
+        >
+          <Button.Label>Reverse order</Button.Label>
+        </Button>
+      </HStack>
+    </VStack>
+  );
+}
+```
+
+## API
+
+### PieChart
+
+Draws the first series as a pie or donut, with an optional legend, tooltip, and selection.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Additional Uniwind/Tailwind classes, merged after the root's own styles. |
+| `accessibilityLabel?` | `string` | — | Names the plot image. Defaults to `localeText.pieChartSummary` over labels and shares. Not applied when `hideLegend` on a selectable chart makes each slice a button. |
+| `series` | `readonly PieChartSeries[]` | — | Pie series. Only the first renders; more than one logs a development warning. The pie diameter is the shorter side of the `size` / `width` / `height` box. |
+| `hideLegend?` | `boolean` | `false` | Hides the category legend. With the legend hidden, a selectable chart makes each slice a button; otherwise the plot is one image with a generated summary. |
+| `legendLayout?` | `'wrap' \| 'list'` | `'wrap'` | How legend items are laid out when `legendPlacement` is `top` or `bottom`. `wrap` is centered chips (`Housing 46%`). `list` is full-width rows: name on the left, formatted value and share on the right, with a hairline between rows. Ignored when the legend is on the left or right. |
+| `legendPlacement?` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Where the legend sits relative to the plot, matching Drawer `placement`. `top` / `bottom` use `legendLayout`. `left` / `right` are swatch + name only (no amount, no percent). |
+| `tooltip?` | `ChartTooltipProps` | `{ trigger: 'item' }` | `item` shows the slice under the pointer or keyboard focus (on touch, the slice under the finger until it lifts). `axis` behaves like `item` because a pie has no axis. `none` hides the tooltip. |
+| `centerLabel?` | `ReactNode \| ((slice: PieChartActiveSlice \| null) => ReactNode)` | — | Content in the donut hole. A string becomes styled `Text`. Pass a `View` for stacked copy such as “Total” over an amount. Pass a function to follow the active slice: it receives the hovered or focused slice, else the selected one, else `null` — return the total for `null`. |
+| `selectedItem?` | `ChartSelectedItem` | — | Controlled selected slice: `{ seriesId, dataIndex }`, where `dataIndex` counts skipped slices. Pass `null` to clear the selection while staying controlled. |
+| `defaultSelectedItem?` | `ChartSelectedItem` | — | Initial selected slice when `selectedItem` is omitted. |
+| `onSelectedItemChange?` | `((item: ChartSelectedItem) => void)` | — | Called when a slice or legend row is pressed. Pressing the selected slice again reports `null`. Providing this, `selectedItem`, or `defaultSelectedItem` makes the chart selectable. |
+| `locale?` | `string` | — | BCP 47 locale for default value and share formatting. Defaults to the `@cdx-ui/formatters` locale. |
+| `localeText?` | `Partial<ChartLocaleText>` | — | Overrides for generated strings such as the screen reader summary. |
+| `animation?` | `'disable-all'` | — | Slices sweep in clockwise on mount and tween to new shares when `data` changes. Pass `'disable-all'` to draw the final state. Reduce Motion and `GlobalAnimationSettingsProvider` `disable-all` also turn it off. |
+| `size?` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'lg'` | Plot box. Named sizes set both width and height; `width` / `height` override one side. |
+| `width?` | `number` | — | Pixel width. Overrides the `size` width. |
+| `height?` | `number` | — | Pixel height. Overrides the `size` height. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute       | Values            | Description                                                                               |
+| --------------- | ----------------- | ----------------------------------------------------------------------------------------- |
+| `data-selected` | `true` \| `false` | On each `pie-chart-legend-item` of a selectable chart; `true` on the selected slice's row |
+
+### PieChartSeries
+
+One entry of `series`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type?` | `'pie'` | — | Series kind. Optional while `PieChart` only draws pies. |
+| `data` | `readonly PieChartValue[]` | — | Slices, drawn clockwise from 12 o'clock in array order. |
+| `innerRadius?` | `number \| `${number}%`` | `0` | Hole radius. A number is pixels; a string such as `'68%'` is a percent of the outer radius. `0` is a full pie. Clamped to 85% of the outer radius. |
+| `paddingAngle?` | `number` | `0` | Degrees between neighboring slices. Skipped on slices too thin to fit it. |
+| `cornerRadius?` | `number` | `0` | Rounds slice corners in pixels. Donuts round all four corners; pies round the outer edge. Clamped so thin slices stay valid. |
+| `shareFormatter?` | `PieShareFormatter` | — | Formats the legend share column and the share in screen reader text. MUI X has no share column, so there is no MUI name. Defaults to a whole percent for `locale`. |
+| `id` | `string` | — | Stable id. `selectedItem.seriesId` and tooltip items refer to it. |
+| `label?` | `string` | — | Series name. Bar and line charts show it in the legend, tooltip, and screen reader text. A pie chart only prefixes tooltip values with it; slice labels name the legend and slices. |
+| `valueFormatter?` | `ChartValueFormatter` | — | Formats this series' values for tooltips and screen reader text, plus bar value labels, line marker values, and a pie's legend value column. `context.location` says where. On charts with axes it wins over the value axis `valueFormatter`. |
+
+### PieChartValue
+
+One slice in a series `data`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | — | Stable slice id. React keys and animation follow it, so a reordered slice moves to its new position instead of the slices morphing by index. |
+| `value` | `number` | — | Must be a positive finite number. Zero, negative, and `NaN` slices are skipped so they cannot break an arc; `dataIndex` still counts them. |
+| `label?` | `string` | — | Legend, tooltip, and screen reader name. Defaults to `id`. |
+| `color?` | `'danger' \| 'warning' \| 'success' \| 'info' \| 'simple-primary' \| 'simple-secondary' \| 'simple-tertiary' \| 'categorical-1' \| 'categorical-2' \| 'categorical-3' \| 'categorical-4' \| 'categorical-5' \| 'categorical-6'` | — | Chart token for this slice. Defaults to the next `categorical-1`…`6` slot. |
+
+### PieChartActiveSlice
+
+What a function `centerLabel` receives.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | — | The slice `id`. |
+| `dataIndex` | `number` | — | Index into the series `data`, including slices that were skipped. |
+| `label` | `string` | — | The slice `label`, or its `id` when it has none. |
+| `value` | `number` | — | The raw slice `value`, unformatted. |
+| `percentage` | `number` | — | Share of the visible total, from 0 to 1. |
+
+### Coming from MUI X
+
+`PieChart` follows the MUI X Charts pie API. It is not a wrap of `@mui/x-charts`, and no MUI type appears in its signature.
+
+| MUI X                                  | Forge UI                                                      | Notes                                                                                                                       |
+| -------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `series` (`PieSeriesType[]`)           | `series` (`PieChartSeries[]`)                                 | Named like `BarChartSeries` and `LineChartSeries`. Only the first series renders.                                           |
+| `series[].data` (`PieValueType[]`)     | `series[].data` (`PieChartValue[]`)                           | `id` is a `string`. `color` is a `ChartColor` token, not a CSS color.                                                       |
+| `series[].id`                          | `series[].id`                                                 | `selectedItem.seriesId` refers to it.                                                                                       |
+| `series[].innerRadius`                 | `series[].innerRadius`                                        | Pixels, or a percent string of the outer radius (`'68%'`).                                                                  |
+| `series[].outerRadius`                 | `size`, `width`, `height`                                     | The pie fills the shorter side of the chart box.                                                                            |
+| `series[].paddingAngle`                | `series[].paddingAngle`                                       | Degrees.                                                                                                                    |
+| `series[].cornerRadius`                | `series[].cornerRadius`                                       | Pixels.                                                                                                                     |
+| `series[].valueFormatter`              | `series[].valueFormatter`                                     | Receives the number and `{ location, seriesId, dataIndex }`, not the slice object.                                          |
+| `series[].arcLabel`                    | `series[].shareFormatter`                                     | `PieChart` draws no arc labels; the share lives in the legend. MUI X has no share column, so there is no MUI name to reuse. |
+| `highlightedItem`, `onHighlightChange` | `selectedItem`, `onSelectedItemChange`, `defaultSelectedItem` | Selection is shared with `BarChart` and `LineChart`. Hover previews are internal.                                           |
+| `hideLegend`                           | `hideLegend`                                                  | Same meaning.                                                                                                               |
+| `slotProps.legend.position`            | `legendPlacement`                                             | MUI X splits position into `vertical` and `horizontal`. Forge uses one side, matching Drawer `placement`.                   |
+| `slotProps.legend.direction`           | `legendLayout`                                                | `wrap` and `list` are layouts MUI X does not have: `list` adds the amount and share columns.                                |
+| `slotProps.tooltip.trigger`            | `tooltip.trigger`                                             | Default `'item'`. `'axis'` acts like `'item'`; a pie has no axis.                                                           |
+| `localeText`                           | `localeText`, `locale`                                        | `locale` drives the default number and percent format.                                                                      |
+| `skipAnimation`                        | `animation="disable-all"`                                     | Same prop as every animated Forge component.                                                                                |
+| —                                      | `centerLabel`                                                 | Content in the donut hole. MUI X composes a custom label element instead.                                                   |
+
+## Anatomy
+
+| `data-slot`             | Element          |
+| ----------------------- | ---------------- |
+| `pie-chart`             | Root             |
+| `pie-chart-plot`        | Plot             |
+| `pie-chart-center`      | Donut hole label |
+| `pie-chart-tooltip`     | Tooltip          |
+| `pie-chart-legend`      | Legend           |
+| `pie-chart-legend-item` | Legend row       |
+
+## Accessibility
+
+The plot is one image named by `accessibilityLabel`, or by `localeText.pieChartSummary` over each slice's label and share. On a selectable chart, each legend row is a button named by its label and share (in `list` layout, its value too). Focus or hover previews the slice and opens the tooltip; Enter, Space, or a press toggles the selection. A static legend is read as plain text, and the tooltip is always hidden from assistive technology. With `hideLegend`, a selectable chart makes the slices the buttons instead; the plot is then no longer an image, so `accessibilityLabel` is not applied.
+
+On native, the buttons announce their selected state. The center label is always hidden from VoiceOver and TalkBack, and the slices are too unless they are buttons, so a total shown only in `centerLabel` is not announced; include it in the summary.
+
+On web, the buttons do not expose a selected state to screen readers; selection shows visually and as `data-selected` on legend rows. Slice buttons are not in the Tab order, so keep the legend when keyboard users need to select.

package/docs/components/progress-segmented/content.md

@@ -2,7 +2,7 @@
 
 Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=449-449), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-progresssegmented--default)
 
-A single (non-compound) component for step-based progress. Pair with a visible step label when WCAG 1.4.1 color-independence is required.
+A single (non-compound) component for step-based progress. Pair with a visible step label when WCAG 1.4.1 color-independence is required. To show a list of named steps instead of a compact meter, use [`Stepper`](https://design.candescent.com/docs/components/stepper/content.md).
 
 ```tsx
 import { ProgressSegmented } from '@cdx-ui/components';