@pantheon-systems/pds-toolkit-react 2.0.0-alpha.3 → 2.0.0-alpha.31

package/dist/components/charts/PieChart/PieChart.d.ts

@@ -0,0 +1,59 @@
+import { ComponentPropsWithoutRef } from 'react';
+import type { ColorPalette, LegendVariant } from '../shared/types';
+import '../shared/chart-wrapper.css';
+import './pie-chart.css';
+export type PieChartVariant = 'donut' | 'pie';
+export interface PieSlice {
+    /** Override default token color (CSS custom property or hex). Not theme-aware — use paletteIndex instead when possible. */
+    color?: string;
+    /** Display label for legend and tooltip */
+    label: string;
+    /** Pick a specific color from the selected palette by position (1-based). Theme-aware — automatically adjusts for light/dark mode. */
+    paletteIndex?: number;
+    /** Numeric value for this slice */
+    value: number;
+}
+export interface PieChartLabelStrings {
+    /** Accessible description for the hidden data table */
+    accessibleTableDescription?: string;
+    /** Heading for the empty state */
+    emptyStateHeading?: string;
+    /** Message body for the empty state */
+    emptyStateMessage?: string;
+    /** Loading label for screen readers */
+    loadingLabel?: string;
+}
+export interface PieChartProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+    /** Height of the chart area in pixels. Default: 300; 80 when isThumbnail. */
+    chartHeight?: number;
+    /** Maximum width of the component in pixels. Default: 80 when isThumbnail. */
+    chartWidth?: number;
+    /** Color palette to use for slice colors (default: 'categorical') */
+    colorPalette?: ColorPalette;
+    /** Slice data */
+    data: PieSlice[];
+    /** Show loading skeleton */
+    isLoading?: boolean;
+    /** Thumbnail mode — hides legend and tooltip, renders at a small fixed size. Individual show* props can override. */
+    isThumbnail?: boolean;
+    /** Translatable UI strings for i18n. Keys: accessibleTableDescription, emptyStateHeading, emptyStateMessage, loadingLabel. */
+    labelStrings?: PieChartLabelStrings;
+    /** Legend display style (default: 'inline') */
+    legendVariant?: LegendVariant;
+    /** Show accessible data table (visually hidden). Defaults to true. */
+    showAccessibleTable?: boolean;
+    /** Show legend below the chart. Defaults to true; false when isThumbnail is set. */
+    showLegend?: boolean;
+    /** Show tooltip on hover. Defaults to true; false when isThumbnail is set. */
+    showTooltip?: boolean;
+    /** Custom value formatter for legend items. Receives the slice value, total, and label. Defaults to showing percentage. */
+    valueFormatter?: (value: number, total: number, label: string) => string;
+    /** Chart variant (default: 'pie') */
+    variant?: PieChartVariant;
+}
+/**
+ * PieChart UI component
+ *
+ * Renders a responsive pie or donut chart showing proportional data across categories.
+ */
+export declare const PieChart: ({ chartHeight, chartWidth, className, colorPalette, data, isLoading, isThumbnail, labelStrings, legendVariant, showAccessibleTable, showLegend, showTooltip, valueFormatter, variant, ...props }: PieChartProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/charts/ProportionBar/ProportionBar.d.ts

@@ -0,0 +1,57 @@
+import { ComponentPropsWithoutRef } from 'react';
+import type { ColorPalette } from '../shared/types';
+import '../shared/chart-wrapper.css';
+import './proportion-bar.css';
+export interface ProportionSegment {
+    /** Override default token color (CSS custom property or hex). Not theme-aware — use paletteIndex instead when possible. */
+    color?: string;
+    /** Display label for legend and tooltip */
+    label: string;
+    /** Pick a specific color from the selected palette by position (1-based). Theme-aware — automatically adjusts for light/dark mode. */
+    paletteIndex?: number;
+    /** Numeric value for this segment */
+    value: number;
+}
+export interface ProportionBarLabelStrings {
+    /** Accessible description for the hidden data table */
+    accessibleTableDescription?: string;
+    /** Heading for the empty state */
+    emptyStateHeading?: string;
+    /** Message body for the empty state */
+    emptyStateMessage?: string;
+    /** Loading label for screen readers */
+    loadingLabel?: string;
+}
+export interface ProportionBarProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+    /** Height of the bar track in pixels (default: 16) */
+    barHeight?: number;
+    /** Maximum width of the component in pixels. The component is responsive and will shrink within this constraint. */
+    chartWidth?: number;
+    /** Color palette to use for segment colors (default: 'categorical') */
+    colorPalette?: ColorPalette;
+    /** Segment data — each segment has a label, numeric value, and optional color override */
+    data: ProportionSegment[];
+    /** Show loading skeleton */
+    isLoading?: boolean;
+    /** Thumbnail mode — hides legend and tooltip. Individual show* props can override. */
+    isThumbnail?: boolean;
+    /** Translatable UI strings for i18n. Keys: accessibleTableDescription, emptyStateHeading, emptyStateMessage, loadingLabel. */
+    labelStrings?: ProportionBarLabelStrings;
+    /** Alignment of the legend (default: 'left') */
+    legendAlignment?: 'center' | 'left';
+    /** Show accessible data table (visually hidden). Defaults to true. */
+    showAccessibleTable?: boolean;
+    /** Show legend below the bar. Defaults to true; false when isThumbnail is set. */
+    showLegend?: boolean;
+    /** Show tooltip on hover. Defaults to true; false when isThumbnail is set. */
+    showTooltip?: boolean;
+    /** Custom value formatter for legend items. Receives the segment value, total, and label. Defaults to showing percentage. */
+    valueFormatter?: (value: number, total: number, label: string) => string;
+}
+/**
+ * ProportionBar UI component
+ *
+ * Renders a single horizontal bar divided into colored segments, showing
+ * the composition of a total. Functions as a linearized pie chart.
+ */
+export declare const ProportionBar: ({ barHeight, chartWidth, className, colorPalette, data, isLoading, isThumbnail, labelStrings, legendAlignment, showAccessibleTable, showLegend, showTooltip, valueFormatter, ...props }: ProportionBarProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/charts/shared/ChartAccessibleTable.d.ts

@@ -0,0 +1,17 @@
+import type { ChartDataPoint, SeriesConfig } from './types';
+interface ChartAccessibleTableProps {
+    /** Chart data points */
+    data: ChartDataPoint[];
+    /** Accessible description for the table */
+    description: string;
+    /** Series definitions */
+    series: SeriesConfig[];
+    /** Optional value formatter */
+    valueFormatter?: (value: number) => string;
+}
+/**
+ * Renders a visually-hidden HTML table containing chart data
+ * for screen reader accessibility.
+ */
+export declare const ChartAccessibleTable: ({ data, description, series, valueFormatter, }: ChartAccessibleTableProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/charts/shared/ChartLegend.d.ts

@@ -0,0 +1,25 @@
+import type { ChartDataPoint, SeriesConfig } from './types';
+import './chart-legend.css';
+export type LegendVariant = 'inline' | 'table';
+interface ChartLegendProps {
+    /** Chart data — used to calculate totals for table variant */
+    data?: ChartDataPoint[];
+    /** Series definitions */
+    series: SeriesConfig[];
+    /** Colors resolved from tokens */
+    seriesColors: string[];
+    /** Table header for the totals column */
+    tableHeader?: string;
+    /** Formatter for total values in table variant */
+    valueFormatter?: (value: number) => string;
+    /** Legend display style (default: 'inline') */
+    variant?: LegendVariant;
+}
+/**
+ * ChartLegend component
+ *
+ * Renders a chart legend in either inline (horizontal list) or
+ * table (rows with totals) format.
+ */
+export declare const ChartLegend: ({ data, series, seriesColors, tableHeader, valueFormatter, variant, }: ChartLegendProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/charts/shared/ChartSkeleton.d.ts

@@ -0,0 +1,11 @@
+import type { LegendVariant } from './types';
+export interface ChartSkeletonProps {
+    /** Optional border radius for the skeleton bar area (e.g. 'var(--pds-border-radius-bar)'). When provided, a rectangular skeleton is clipped to this radius. */
+    borderRadius?: string;
+    height: number;
+    /** Alignment of the inline legend skeleton (default: 'center') */
+    legendAlignment?: 'center' | 'left';
+    legendVariant?: LegendVariant;
+    showLegend?: boolean;
+}
+export declare const ChartSkeleton: ({ borderRadius, height, legendAlignment, legendVariant, showLegend, }: ChartSkeletonProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/charts/shared/chart-colors.d.ts

@@ -0,0 +1,30 @@
+import { RefObject } from 'react';
+import type { ColorPalette } from './types';
+/**
+ * Strips fill-only steps from palettes that have them, returning only standalone-safe colors.
+ * Bar and line charts should always use this before rendering series colors.
+ */
+export declare const toStandaloneColors: (palette: ColorPalette, colors: string[]) => string[];
+/**
+ * Normalizes a paletteIndex for palettes that have fill-only steps.
+ * Clamps fill-only step numbers (e.g. 1–2 on sequential-iris/multi) to the first safe step,
+ * then adjusts for the slice offset so the number still maps correctly into the sliced array.
+ * Non-restricted palettes pass through unchanged.
+ */
+export declare const clampPaletteIndex: (palette: ColorPalette, paletteIndex: number | undefined) => number | undefined;
+/**
+ * Get color for a series by index, cycling through palette if needed.
+ * Priority: customColor (hex) > paletteIndex (theme-aware) > auto-assigned.
+ */
+export declare const getSeriesColor: (index: number, palette: string[], customColor?: string, paletteIndex?: number) => string;
+/**
+ * Resolve palette token colors from computed styles on an element.
+ * Falls back to hex values if tokens are not available.
+ */
+export declare const resolveTokenColors: (element: HTMLElement | null, paletteName: ColorPalette) => string[];
+/**
+ * Hook to resolve chart colors from design tokens at runtime.
+ * Falls back to hex values when tokens are not loaded (e.g., SSR).
+ * Re-resolves when the theme changes (via data-theme attribute).
+ */
+export declare const useChartColors: (containerRef: RefObject<HTMLElement | null>, paletteName?: ColorPalette) => string[];

package/dist/components/charts/shared/chart-styles.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared Recharts style configuration using PDS design tokens.
+ * Keeps all chart styling in one place rather than split between CSS and JS.
+ */
+export declare const axisTickStyle: {
+    fill: string;
+    fontFamily: string;
+    fontSize: string;
+};
+export declare const axisLabelStyle: {
+    fill: string;
+    fontFamily: string;
+    fontSize: string;
+    fontWeight: string;
+};
+export declare const gridStroke = "var(--pds-color-border-default)";

package/dist/components/charts/shared/formatters.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Format a number with K/M/B suffixes for chart axis labels.
+ */
+export declare const formatCompactNumber: (value: number) => string;
+/**
+ * Format a number with locale-aware thousand separators.
+ */
+export declare const formatLocaleNumber: (value: number) => string;
+/**
+ * Format a number as a percentage.
+ */
+export declare const formatPercent: (value: number) => string;

package/dist/components/charts/shared/types.d.ts

@@ -0,0 +1,128 @@
+import type { ReactNode } from 'react';
+export interface ChartDataPoint {
+    /** One or more numeric series values, keyed by series name */
+    [key: string]: number | string;
+    /** X-axis label */
+    label: string;
+}
+export type StrokeStyle = 'dashed' | 'solid';
+export interface SeriesConfig {
+    /** Override default token color (CSS custom property or hex). Not theme-aware — use paletteIndex for theme-aware overrides. */
+    color?: string;
+    /** Key matching a property in ChartDataPoint */
+    dataKey: string;
+    /** Display label for legend/tooltip */
+    label: string;
+    /** Pick a specific color from the selected palette by position (1-based). Theme-aware — automatically adjusts for light/dark mode. */
+    paletteIndex?: number;
+    /** Line style (LineChart only) */
+    strokeStyle?: StrokeStyle;
+}
+export interface ReferenceLineConfig {
+    /** Color override */
+    color?: string;
+    /** Display label */
+    label: string;
+    /** Line style */
+    strokeStyle?: StrokeStyle;
+    /** Y-axis value where line appears */
+    value: number;
+}
+export interface AnnotationConfig {
+    /** X-axis label value to annotate */
+    atLabel: string;
+    /** Color override */
+    color?: string;
+    /** Line style */
+    strokeStyle?: StrokeStyle;
+    /** Display text */
+    text: string;
+}
+export interface TimePeriodOption {
+    /** Display label ("Last 30 Days") */
+    label: string;
+    /** Value identifier */
+    value: string;
+}
+export type ColorPalette = 'categorical' | 'diverging-a' | 'diverging-b' | 'sequential-gray' | 'sequential-iris' | 'sequential-multi' | 'single' | 'status';
+export type LegendVariant = 'inline' | 'table';
+export interface TooltipEntry {
+    /** Series bar/line color */
+    color: string;
+    /** Series data key */
+    dataKey: string;
+    /** Series display name */
+    name: string;
+    /** Data value */
+    value: number;
+}
+export interface TooltipPayload {
+    /** All series entries for this x-axis position */
+    entries: TooltipEntry[];
+    /** X-axis label */
+    label: string;
+}
+export type YAxisDomainItem = number | string | ((dataMax: number) => number);
+export type YAxisDomain = [YAxisDomainItem, YAxisDomainItem];
+export interface ChartLabelStrings {
+    /** Accessible description for the hidden data table. */
+    accessibleTableDescription?: string;
+    /** Heading for the empty state. */
+    emptyStateHeading?: string;
+    /** Message body for the empty state. */
+    emptyStateMessage?: string;
+    /** Table header for the totals column when legendVariant is 'table'. */
+    legendTableHeader?: string;
+    /** Loading label for screen readers. */
+    loadingLabel?: string;
+}
+export interface BaseChartProps {
+    /** Height of the chart area in pixels. Does not include the legend, header, or accessible table. */
+    chartHeight?: number;
+    /** Maximum width of the chart component in pixels. The chart is responsive and will shrink within this constraint. */
+    chartWidth?: number;
+    /** Color palette to use for series colors (default: 'categorical') */
+    colorPalette?: ColorPalette;
+    /** Chart data points */
+    data: ChartDataPoint[];
+    /** Show loading state */
+    isLoading?: boolean;
+    /** Thumbnail mode — hides grid, axes, legend, tooltips, and reduces chart height. Individual show* props can override. */
+    isThumbnail?: boolean;
+    /** Translatable UI strings. Provide overrides for i18n. */
+    labelStrings?: ChartLabelStrings;
+    /** Legend display style (default: 'inline') */
+    legendVariant?: LegendVariant;
+    /** Callback when time period changes */
+    onTimePeriodChange?: (value: string) => void;
+    /** Currently selected time period */
+    selectedTimePeriod?: string;
+    /** Series definitions */
+    series: SeriesConfig[];
+    /** Show accessible data table (visually hidden). Defaults to true regardless of isThumbnail. */
+    showAccessibleTable?: boolean;
+    /** Show axis baseline lines. Defaults to true; false when isThumbnail is set. */
+    showAxisLines?: boolean;
+    /** Show grid lines. Defaults to true; false when isThumbnail is set. */
+    showGrid?: boolean;
+    /** Show legend. Defaults to true; false when isThumbnail is set. */
+    showLegend?: boolean;
+    /** Show tooltip on hover. Defaults to true; false when isThumbnail is set. */
+    showTooltip?: boolean;
+    /** Time period options for built-in selector */
+    timePeriodOptions?: TimePeriodOption[];
+    /** Custom tooltip renderer. Receives normalized payload and replaces the built-in tooltip. */
+    tooltipContent?: (payload: TooltipPayload) => ReactNode;
+    /** X-axis label */
+    xAxisLabel?: string;
+    /** How often to show x-axis ticks. A number n shows every nth tick (e.g. 1 = every other). Defaults to auto. */
+    xAxisTickInterval?: number | 'preserveStart' | 'preserveEnd' | 'preserveStartEnd';
+    /** Override the Y-axis scale bounds. Accepts a tuple of [min, max] where each can be a number, 'auto', 'dataMin', 'dataMax', or a function receiving the data max. */
+    yAxisDomain?: YAxisDomain;
+    /** Custom Y-axis tick formatter */
+    yAxisFormatter?: (value: number) => string;
+    /** Y-axis label */
+    yAxisLabel?: string;
+    /** How often to show y-axis ticks. A number n shows every nth tick (e.g. 1 = every other). Defaults to auto. */
+    yAxisTickInterval?: number | 'preserveStart' | 'preserveEnd' | 'preserveStartEnd';
+}

package/dist/components/empty-states/HorizontalEmptyState/HorizontalEmptyState.d.ts

@@ -1,6 +1,6 @@
 import { ComponentPropsWithoutRef, ReactNode } from 'react';
 import { HeadingLevel } from '../../../libs/types/custom-types';
-import { VideoEmbedProps } from '../../VideoEmbed/VideoEmbed';
+import { VideoEmbedProps } from '../../media/VideoEmbed/VideoEmbed';
 import './horizontal-empty-state.css';
 /**
  * Prop types for HorizontalEmptyState