@pantheon-systems/pds-toolkit-react 2.0.0-alpha.7 → 2.0.0-alpha.71

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,31 @@
+import type { ChartDataPoint, SeriesConfig } from './types';
+import './chart-legend.css';
+export type LegendVariant = 'inline' | 'table';
+interface ChartLegendProps {
+    /**
+     * Hides the legend table from assistive technology. Set this when an
+     * accessible data table already discloses the same data, making the
+     * visible legend table purely a sighted-user convenience.
+     */
+    ariaHidden?: boolean;
+    /** 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: ({ ariaHidden, 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-blue) 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,24 @@
+/**
+ * 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)";
+/**
+ * Surface-color gap between touching marks (stacked bar segments). Draws as a
+ * stroke around each segment, but since adjacent segments share the exact
+ * same boundary line, the overlapping strokes read as a single thin gap
+ * rather than a border — see the dataviz "surface gap" spec.
+ */
+export declare const stackedSegmentGapStroke = "var(--pds-color-surface-default)";
+export declare const stackedSegmentGapWidth = 1;

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-blue' | 'sequential-gray' | '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
@@ -19,6 +19,13 @@ export interface HorizontalEmptyStateProps extends ComponentPropsWithoutRef<'div
      * This should be a Button, ButtonLink, or two items wrapped in a `pds-button-group` div.
      */
     ctaRegion?: ReactNode;
+    /**
+     * Adds inline-start padding to the content block so its text aligns with
+     * the content of cards placed below it (the image/video stays flush with
+     * the container edge). Opt in when this empty state sits directly above a
+     * row of cards; omit it when the component is used on its own.
+     */
+    hasIndentedContent?: boolean;
     /**
      * heading to explain the empty state.
      */
@@ -43,14 +50,12 @@ export interface HorizontalEmptyStateProps extends ComponentPropsWithoutRef<'div
      * Default is '40%'.
      */
     imageWidth?: string;
-    /**
-     * Will this be rendered within a panel?
-     * If true, the image and heading will be scaled down to fit within the panel.
-     */
-    isWithinPanel?: boolean;
     /**
      * Maximum width of the empty state container (CSS value, e.g., '1200px', '80rem', '90%').
-     * Default is '1200px'.
+     * Default is '100%', so the component fills whatever container it's
+     * placed in (the dashboard's `AppLayout` already constrains page width).
+     * Pass a narrower value for standalone, full-page usage with no other
+     * width constraint in place.
      */
     maxWidth?: string;
     /**
@@ -71,4 +76,4 @@ export interface HorizontalEmptyStateProps extends ComponentPropsWithoutRef<'div
 /**
  * HorizontalEmptyState UI component
  */
-export declare const HorizontalEmptyState: ({ alignment, className, ctaRegion, heading, headingLevel, image, imageMarginLeft, imageWidth, isWithinPanel, maxWidth, message, video, ...props }: HorizontalEmptyStateProps) => import("react/jsx-runtime").JSX.Element;
+export declare const HorizontalEmptyState: ({ alignment, className, ctaRegion, hasIndentedContent, heading, headingLevel, image, imageMarginLeft, imageWidth, maxWidth, message, video, ...props }: HorizontalEmptyStateProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/icons/Icon/Icon.d.ts

@@ -22,7 +22,7 @@ export interface IconProps extends ComponentPropsWithoutRef<'svg'> {
     /**
      * Which size of icon to render
      */
-    iconSize?: IconSize;
+    size?: IconSize;
     /**
      * Vertical align value
      */
@@ -31,4 +31,4 @@ export interface IconProps extends ComponentPropsWithoutRef<'svg'> {
 /**
  * A component used to display an icon.
  */
-export declare const Icon: ({ className, display, iconName, iconSize, style, verticalAlign, ...props }: IconProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Icon: ({ className, display, iconName, size, style, verticalAlign, ...props }: IconProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/icons/Icon/custom-icons.d.ts

@@ -26,7 +26,7 @@
  *   serialized by the generate script.
  *
  * Testing:
- * - Check the icon at all sizes (xs through 3xl) in Storybook
+ * - Check the icon at all sizes (s through 3xl) in Storybook
  * - Verify it looks balanced next to FA icons at the same size
  */
 import React from 'react';