@persona/design-system 0.10.12 → 0.10.14

package/skills/ui-authoring/PATTERNS.md

@@ -11,7 +11,6 @@ Which pattern to use, and for what. Patterns with a dedicated doc link to
 | [Forms](../../patterns/Forms/Forms.mdx) | Labeled fields in a `Modal`, `RightPanel`, or page. Unlabeled controls (search, toolbars) stay as `Input` |
 | Stack / HStack | A heading above content, a cancel/save pair, a title next to an add button, or a wrapping row of tags |
 | EmptyStates | A list, table, or card has no items yet and you want to invite adding one |
-| Charting | Build charts with `recharts` and the experimental `@persona/design-system/components/Chart` pieces; colour series from the chart palettes, never hex |
 | Indicators | A record’s open, pending, completed, or failed state next to other content. An in-page notice the user shouldn’t miss (success, warning, error). Use `Toast` if it can auto-dismiss |
 | [SingleColumnLayout](../../patterns/PageLayout/SingleColumnLayout.mdx) | One page column under `PageHeader`, with optional tabs and a page notice. `width="wide"` uses the fluid grid |
 | [SplitColumnLayout](../../patterns/PageLayout/SplitColumnLayout.mdx) | An 8:4 main and aside page. Same optional regions. Stacks main then aside below 768px |
@@ -298,66 +297,3 @@ Message-only (no CTA):
 
 For `ListBox`, pass `emptyText="No items"` prop directly.
 For `Card.Section`, pass `empty={true}` to show the built-in empty state.
-
-
-
-## Charting
-
-Experimental (beta). Build charts with `recharts` (an optional peer, 2.x or 3.x) and the pieces in
-`@persona/design-system/components/Chart`. Full usage guidance comes later; until then see Storybook
-**Charts → Design** (Chart frame, Elements, Themes) and **Charts → Chart types** (Bar chart, Line
-chart).
-
-- `ChartFrame`: legend and plot layout, full width, 300px plot height by default.
-- `ChartLegend`: series key; with `onToggle` (and `useChartSeriesVisibility`) it shows and hides series.
-- `ChartPopover`: the content of a Recharts `<Tooltip>`.
-- `useChartStyles()`: PDS props for Recharts' grid, axes and tooltip cursor in a hand-built chart.
-- `useChartColors()` / `resolveSeriesColors()`: series colours from a chart palette.
-
-```tsx
-import {
-  ChartFrame,
-  ChartLegend,
-  ChartPopover,
-  CHART_PLOT_MARGIN,
-  useChartColors,
-  useChartStyles,
-} from '@persona/design-system/components/Chart';
-import { Bar, BarChart, CartesianGrid, ResponsiveContainer, Tooltip, XAxis, YAxis } from 'recharts';
-
-const colors = useChartColors().resolve(series); // { [series.key]: Color }
-const styles = useChartStyles();
-const items = series.map((s) => ({ ...s, color: colors[s.key] }));
-
-<ChartFrame aria-label='Tickets by status' legend={<ChartLegend items={items} />}>
-  <ResponsiveContainer width='100%' height='100%'>
-    <BarChart data={data} margin={CHART_PLOT_MARGIN}>
-      <Tooltip cursor={styles.barCursor} content={<ChartPopover series={items} />} />
-      <CartesianGrid {...styles.grid} />
-      <XAxis dataKey='month' {...styles.xAxis} />
-      <YAxis {...styles.yAxis} />
-      {items.map((s) => <Bar key={s.key} dataKey={s.key} name={s.label} fill={s.color} />)}
-    </BarChart>
-  </ResponsiveContainer>
-</ChartFrame>
-```
-
-### Palettes
-
-| Data | Palette (`useChartColors(palette)`) | Colours |
-|------|-------------------------------------|---------|
-| Distinct, unordered series (default) | `'qualitative'` | 12 |
-| Ordered magnitude in one hue | `'sequentialMono'` | 8 |
-| Values diverging around a midpoint | `'sequentialDivergent'` | 10 |
-
-Take Qualitative colours in palette order: the order is tuned for readability. Override a series
-only with a Persona token, `chartColor(Color.X)` or a `{ light, dark }` pair of tokens; never hex.
-
-**Legacy:** `ChartingColors.Sequential` and `ChartingColors.Categorical` from
-`@persona/design-tokens` are deprecated for new charts. Existing charts may keep them until they
-move to the palettes above.
-
-**Anti-patterns:**
-- Hardcoding hex values for series colours
-- Picking Qualitative colours out of order
-- Using `'sequentialMono'` for unordered categories

package/skills/ui-authoring/TOKENS.md

@@ -490,7 +490,8 @@ Apps embedded in the dashboard follow its mode with
 `<PDSProvider colorMode={readDocumentColorMode()}>` (`@persona/design-system/lib/colorMode`). That
 installs the semantic palette for PDS components and publishes it as `--pds-*` CSS variables
 (`FgPrimary` -> `var(--pds-fg-primary)`) for plain stylesheets. Wrap a subtree in
-`<ColorModeScope mode='dark'>` to render it in the other mode. Plain CSS inside a portaled overlay
+`<ColorModeScope mode='dark'>` to render it in the other mode, and read the mode in effect (for
+iframes, canvases or charts) with `useColorMode()`. Plain CSS inside a portaled overlay
 reads the `:root` variables, not the scope's. Don't copy these helpers into an app. See
 `tokens/README.md` ("Colour mode in apps").
 
@@ -702,35 +703,23 @@ const Menu = styled.div`
 
 ## Charts
 
-Experimental (beta). Colour chart series with the chart palettes from
-`@persona/design-system/components/Chart`: `useChartColors(palette)` (follows the PDS colour mode)
-or `resolveSeriesColors()`. See the Charting section of [PATTERNS.md](PATTERNS.md) and Storybook
-**Charts → Design → Themes**.
+Experimental (beta). Colour chart series with the chart palette tokens: `ChartingColors` from
+`@persona/design-tokens` (light), or `chartingLight` / `chartingDark` from
+`@persona/design-system/variables/charting`. `chartingColors(theme)` from
+`@persona/design-system/lib/semanticColor` returns the palettes for the theme's colour mode.
 
-| Need | Palette | Token palette | Colours |
-|------|---------|---------------|---------|
-| Distinct, unordered series (default) | `'qualitative'` | `ChartingColors.Qualitative` | 12 |
-| Ordered magnitude in one hue | `'sequentialMono'` | `ChartingColors.SequentialMono` | 8 |
-| Values diverging around a midpoint | `'sequentialDivergent'` | `ChartingColors.SequentialDivergent` | 10 |
+| Need | Token palette | Colours |
+|------|---------------|---------|
+| Distinct, unordered series (default) | `ChartingColors.Qualitative` | 12 |
+| Ordered magnitude in one hue | `ChartingColors.SequentialMono` | 8 |
+| Values diverging around a midpoint | `ChartingColors.SequentialDivergent` | 10 |
 
 - Take Qualitative colours in order; the order is tuned for readability.
-- Override a series only with a Persona token: `chartColor(Color.X)` or a `{ light, dark }` pair.
-  Never hex: `ChartColor` does not accept a hex string, and the `pds/semantic-color` lint rule
-  rejects it.
-
-```tsx
-import { useChartColors } from '@persona/design-system/components/Chart';
-
-const colors = useChartColors().resolve([
-  { key: 'approved', label: 'Approved' },
-  { key: 'declined', label: 'Declined' },
-]);
-<Bar dataKey='approved' fill={colors.approved} />;
-```
+- Override a series only with a Persona token, never hex; the `pds/semantic-color` lint rule
+  rejects hex.
 
 **Legacy (deprecated for new charts):** `ChartingColors.Sequential` (8) and
-`ChartingColors.Categorical` (14), also exposed under a colour mode through `chartingColors(theme)`
-from `@persona/design-system/lib/semanticColor`. Existing charts may keep them until they move to
+`ChartingColors.Categorical` (14), also exposed under a colour mode through `chartingColors(theme)`. Existing charts may keep them until they move to
 the palettes above.
 
 ## Token Verification

package/dist/ChartFrame.d.mts

@@ -1,61 +0,0 @@
-import { ChartLegendPosition } from "./chartFrameLayout.mjs";
-import { ChartLegendProps } from "./ChartLegend.mjs";
-import { ReactElement } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
-
-//#region src/components/Chart/ChartFrame.d.ts
-type ChartFrameLabel = {
-  'aria-label': string;
-  'aria-labelledby'?: never;
-} | {
-  'aria-labelledby': string;
-  'aria-label'?: never;
-};
-/** @experimental */
-type ChartFrameProps = ChartFrameLabel & {
-  /**
-   * The chart's legend. Pass `null` to omit it, e.g. for a single-series chart whose surrounding
-   * heading already names the series.
-   */
-  legend: ReactElement<ChartLegendProps> | null;
-  /**
-   * `'stack'` (default) puts the legend left-aligned above the plot; `'right'` puts it inline to
-   * the right of the plot, as wide as its longest label up to 200px (longer labels end in an
-   * ellipsis). The legend and plot are `Spacing[4]` apart when stacked and `Spacing[3]` apart inline.
-   */
-  legendPosition?: ChartLegendPosition;
-  /**
-   * Plot area height in px. Defaults to 300 (`CHART_DEFAULT_HEIGHT`). The plot always fills 100%
-   * of the frame's width, and the frame fills its container.
-   */
-  height?: number;
-  /**
-   * The plot: a Recharts chart, sized by the frame (e.g. wrapped in `ResponsiveContainer`). Give it
-   * `margin={CHART_PLOT_MARGIN}` so the frame's spacing is the only gap around the plot.
-   */
-  children: ReactElement; /** Applied to the root `<figure>`, e.g. to position or size the frame. */
-  className?: string;
-};
-/**
- * Lays out a chart: its legend and the plot area, `Spacing[4]` apart stacked (`Spacing[3]` inline), with the legend left-aligned
- * above the plot (`legendPosition='stack'`, the default) or inline on its right (`'right'`). The
- * frame has no header, border or surface of its own: titles, descriptions and controls belong to
- * the surrounding container (for example a `CardV2`), which also names the chart via
- * `aria-labelledby`.
- *
- * Size: the chart fills 100% of its container's width, and the plot is 300px tall
- * (`CHART_DEFAULT_HEIGHT`) unless `height` overrides it.
- *
- * @experimental Part of the in-progress PDS charting components; the API may change.
- */
-declare function ChartFrame({
-  legend,
-  legendPosition,
-  height,
-  children,
-  className,
-  ...label
-}: ChartFrameProps): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-export { ChartFrame, ChartFrame as default, ChartFrameProps };
-//# sourceMappingURL=ChartFrame.d.mts.map

package/dist/ChartLegend.d.mts

@@ -1,60 +0,0 @@
-import { Color } from "@persona/design-tokens";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
-
-//#region src/components/Chart/ChartLegend.d.ts
-/** One series in a {@link ChartLegend}. @experimental */
-interface ChartLegendItem<K extends string = string> {
-  key: K;
-  label: string;
-  /** The series colour, from `useChartColors().resolve(...)` or `resolveSeriesColors(...)`. */
-  color: Color;
-}
-/** A titled set of legend items, e.g. the series sharing an axis. @experimental */
-interface ChartLegendGroup<K extends string = string> {
-  key: string;
-  /** Shown above the group's items in uppercase mono text. */
-  label: string;
-  items: readonly ChartLegendItem<K>[];
-}
-/** Either flat `items` or titled `groups`; groups are optional. @experimental */
-type ChartLegendContent<K extends string = string> = {
-  items: readonly ChartLegendItem<K>[];
-  groups?: never;
-} | {
-  groups: readonly ChartLegendGroup<K>[];
-  items?: never;
-};
-/** @experimental */
-type ChartLegendProps<K extends string = string> = ChartLegendContent<K> & {
-  /** Keys of the series currently hidden. Pair with {@link useChartSeriesVisibility}. */hidden?: readonly K[];
-  /**
-   * Called with a series key when its legend item is clicked. When set, every item is a toggle
-   * button (`aria-pressed` is true while the series is shown); when omitted, the legend is static.
-   * Every series may be hidden.
-   */
-  onToggle?: (key: K) => void; /** Names the legend for assistive tech. Defaults to "Chart legend". */
-  'aria-label'?: string; /** Applied to the legend's root element (the list, or the group wrapper with `groups`). */
-  className?: string;
-};
-/**
- * The series key for a chart: a square colour swatch and a `TextMedium` label per series, laid out
- * in a row that wraps (a column when it sits right of the plot in a `ChartFrame`). With `onToggle`,
- * each item toggles its series; a hidden series keeps a filled swatch at 65% opacity and gets a
- * muted label.
- *
- * Pass `groups` instead of `items` for a grouped legend: groups stack `Spacing[2]` apart, each with
- * an uppercase mono title `Spacing[1]` above its row of items.
- *
- * @experimental Part of the in-progress PDS charting components; the API may change.
- */
-declare function ChartLegend<K extends string>({
-  items,
-  groups,
-  hidden,
-  onToggle,
-  'aria-label': ariaLabel,
-  className
-}: ChartLegendProps<K>): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-export { ChartLegend, ChartLegend as default, ChartLegendContent, ChartLegendGroup, ChartLegendItem, ChartLegendProps };
-//# sourceMappingURL=ChartLegend.d.mts.map

package/dist/ChartPopover.d.mts

@@ -1,155 +0,0 @@
-import { ReactNode } from "react";
-import { Color } from "@persona/design-tokens";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
-
-//#region src/components/Chart/ChartPopover.d.ts
-/**
- * The popover density. `'default'` is the standalone chart popover (256px wide). `'condensed'` is
- * for small charts inside table cells (210px wide): the same text, tighter padding and row gaps,
- * and never a total row.
- *
- * @experimental Part of the in-progress PDS charting components; the API may change.
- */
-type ChartPopoverSize = 'default' | 'condensed';
-/**
- * One series the popover may list. `series` sets the row order, the label and the swatch colour; a
- * Recharts payload entry is matched to a series by its `dataKey`.
- *
- * @experimental
- */
-interface ChartPopoverSeries<K extends string = string> {
-  key: K;
-  label: ReactNode;
-  /** The series colour token, e.g. from `useChartColors().resolve(...)`. Falls back to the payload colour. */
-  color?: Color;
-}
-/**
- * One Recharts tooltip payload entry, typed structurally so the same component accepts the
- * payloads of Recharts 2 (`TooltipProps`) and Recharts 3 (`TooltipContentProps`).
- *
- * @experimental
- */
-interface ChartPopoverPayloadEntry {
-  dataKey?: unknown;
-  name?: unknown;
-  value?: unknown;
-  color?: string;
-  fill?: string;
-  stroke?: string;
-  /** Set by Recharts 3 for a series rendered with `hide`. */
-  hide?: boolean;
-  /** Set for legend-inactive series. */
-  inactive?: boolean;
-  /** `'none'` marks an entry Recharts itself keeps out of its tooltip. */
-  type?: string;
-  payload?: unknown;
-}
-/** One rendered row. @experimental */
-interface ChartPopoverRow {
-  key: string;
-  label: ReactNode;
-  /** The swatch colour: a Persona chart colour token. */
-  color?: string;
-  value: number | string | null | undefined;
-}
-interface ChartPopoverPanelOwnProps<K extends string = string> {
-  /** The header, e.g. the formatted x-axis category. Omitted when empty. */
-  label?: ReactNode;
-  /** The rows, top to bottom. */
-  rows: readonly ChartPopoverRow[];
-  /** Formats each row value and the total. Defaults to locale number formatting. */
-  valueFormatter?: (value: number | string, seriesKey: K | 'total') => ReactNode;
-  /** Appends a total row summing the numeric values of the visible rows. Ignored when `condensed`. */
-  showTotal?: boolean;
-  /** Overrides the computed total. */
-  total?: number;
-  /** Label of the total row. Defaults to `'Total'`. */
-  totalLabel?: ReactNode;
-  /** Defaults to `'default'`. */
-  size?: ChartPopoverSize;
-  /**
-   * Popover width in px. Defaults to 256 (`'default'`) or 210 (`'condensed'`); pass a larger number
-   * for long series names. The height always follows the rows. Series names that still do not fit
-   * are truncated with an ellipsis; values never truncate or wrap.
-   */
-  width?: number;
-  /**
-   * The series the pointer is on (`useChartActiveSeries().activeSeries`). Its row stays at full
-   * strength and the other series rows drop to 65% opacity; the total row is unaffected.
-   */
-  activeSeries?: K;
-  className?: string;
-}
-/** @experimental */
-type ChartPopoverPanelProps<K extends string = string> = ChartPopoverPanelOwnProps<K>;
-/** @experimental */
-interface ChartPopoverProps<K extends string = string> extends Omit<ChartPopoverPanelOwnProps<K>, 'rows' | 'label'> {
-  /** Injected by Recharts `<Tooltip>`. */
-  active?: boolean;
-  /** Injected by Recharts `<Tooltip>`. */
-  payload?: readonly ChartPopoverPayloadEntry[];
-  /** Injected by Recharts `<Tooltip>`: the hovered category. */
-  label?: unknown;
-  /**
-   * The chart's series, in display order. Rows follow this order and only series listed here are
-   * shown. Without it, rows follow the payload order and use the payload's names and colours.
-   */
-  series?: readonly ChartPopoverSeries<K>[];
-  /** Series keys hidden by the legend; they get no row. */
-  hiddenSeries?: Iterable<K>;
-  /** Formats the header from the hovered category. Defaults to the category as is. */
-  labelFormatter?: (label: unknown, payload: readonly ChartPopoverPayloadEntry[]) => ReactNode;
-}
-/** Default popover widths in px (Figma). @experimental */
-declare const CHART_POPOVER_WIDTH: Record<ChartPopoverSize, number>;
-/**
- * The chart popover body: an optional header, one row per series (swatch, name, right-aligned
- * value) and an optional total row. Use it directly for a popover drawn outside Recharts; inside a
- * Recharts chart use {@link ChartPopover}.
- *
- * @experimental Part of the in-progress PDS charting components; the API may change.
- */
-declare function ChartPopoverPanel<K extends string = string>({
-  label,
-  rows,
-  valueFormatter,
-  showTotal,
-  total,
-  totalLabel,
-  size,
-  width,
-  activeSeries,
-  className
-}: ChartPopoverPanelProps<K>): _$react_jsx_runtime0.JSX.Element;
-/**
- * Builds the popover rows from a Recharts tooltip payload: drops hidden and inactive series, then
- * orders, labels and colours the rest by `series` (or keeps the payload order without it).
- *
- * @experimental
- */
-declare function chartPopoverRows<K extends string>(payload: readonly ChartPopoverPayloadEntry[], series?: readonly ChartPopoverSeries<K>[], hiddenSeries?: Iterable<K>): ChartPopoverRow[];
-/**
- * Chart popover (tooltip) content for Recharts 2 and 3. Pass it to `<Tooltip content={...} />`;
- * Recharts injects `active`, `payload` and `label`.
- *
- * ```tsx
- * const series = [{ key: 'approved', label: 'Approved', color: colors.approved }, ...];
- * <Tooltip cursor={false} content={<ChartPopover series={series} hiddenSeries={hidden} />} />
- * ```
- *
- * Renders nothing while inactive or when every series is hidden.
- *
- * @experimental Part of the in-progress PDS charting components; the API may change.
- */
-declare function ChartPopover<K extends string = string>({
-  active,
-  payload,
-  label,
-  series,
-  hiddenSeries,
-  labelFormatter,
-  ...panelProps
-}: ChartPopoverProps<K>): _$react_jsx_runtime0.JSX.Element | null;
-//#endregion
-export { CHART_POPOVER_WIDTH, ChartPopover, ChartPopoverPanel, ChartPopoverPanelProps, ChartPopoverPayloadEntry, ChartPopoverProps, ChartPopoverRow, ChartPopoverSeries, ChartPopoverSize, chartPopoverRows };
-//# sourceMappingURL=ChartPopover.d.mts.map