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

package/README.md

@@ -8,11 +8,11 @@ This toolkit provides assets for use within a React project and a Storybook inst
 
 ## Toolkit philosophy and scope
 
-The intent of this toolkit is to provide a React-based implementation of the Pantheon Design System (PDS) with a focus on semantics, accessibility, visual design, and user-interface design.
+The toolkit provides a React implementation of the Pantheon Design System (PDS) focused on semantics, accessibility, visual design, and user-interface design.
 
-This toolkit should not contain processes or mechanisms used for data manipulation, business logic, or similar. Therefore, processes such as form handling, routing, and language translation should be handled within the application that is consuming the toolkit.
+The toolkit does not include data manipulation, business logic, form handling, routing, or language translation. These concerns are handled by the consuming application.
 
-Each component will contain a documentation page within Storybook that provides usage notes, implementation instructions, and expected data structure for that particular component.
+Each component has a documentation page within Storybook that provides usage notes, implementation instructions, and expected data structure.
 
 ### Content within components
 

package/dist/components/Avatar/Avatar.d.ts

@@ -21,10 +21,14 @@ export interface AvatarProps extends ComponentPropsWithoutRef<'div'> {
      * A link element using the router of your choice. Leave empty for no link.
      */
     linkContent?: ReactNode;
+    /**
+     * Avatar shape.
+     */
+    shape?: 'circle' | 'square';
     /**
      * Avatar size.
      */
-    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    size?: 'xs' | 's' | 'm' | 'l';
     /**
      * Unique ID associated with the avatar. Can be workspace ID, user ID, email, etc.
      */
@@ -33,4 +37,4 @@ export interface AvatarProps extends ComponentPropsWithoutRef<'div'> {
 /**
  * Avatar UI component
  */
-export declare const Avatar: ({ ariaLabel, className, hasUserFallback, imageSrc, linkContent, size, uniqueId, ...props }: AvatarProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Avatar: ({ ariaLabel, className, hasUserFallback, imageSrc, linkContent, shape, size, uniqueId, ...props }: AvatarProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/ComparisonList/ComparisonList.d.ts

@@ -9,6 +9,7 @@ export interface ListItems {
     text: string;
     type: 'included' | 'notIncluded' | 'addon';
 }
+export type ComparisonListSize = 's' | 'm';
 export interface ComparisonListProps extends ComponentPropsWithoutRef<'div'> {
     /**
      * Additional class names
@@ -30,6 +31,14 @@ export interface ComparisonListProps extends ComponentPropsWithoutRef<'div'> {
      * Render the icon labels for screen readers.
      */
     renderTypeLabels?: boolean;
+    /**
+     * Whether to show the border on list items.
+     */
+    showBorder?: boolean;
+    /**
+     * Size variant.
+     */
+    size?: ComparisonListSize;
     /**
      * Icon labels
      */
@@ -38,5 +47,5 @@ export interface ComparisonListProps extends ComponentPropsWithoutRef<'div'> {
 /**
  * ComparisonList UI component
  */
-export declare const ComparisonList: ({ className, listItems, listLabel, moreLink, renderTypeLabels, typeLabels, ...props }: ComparisonListProps) => import("react/jsx-runtime").JSX.Element;
+export declare const ComparisonList: ({ className, listItems, listLabel, moreLink, renderTypeLabels, showBorder, size, typeLabels, ...props }: ComparisonListProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Dropdown/Dropdown.d.ts

@@ -0,0 +1,140 @@
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import { UseDropdownOptions } from '../../utilities/hooks/useDropdown';
+import './dropdown.css';
+export interface DropdownProps extends UseDropdownOptions {
+    /**
+     * Dropdown sub-components (Trigger, Panel, etc.).
+     */
+    children?: ReactNode;
+    /**
+     * Additional class names for the root wrapper.
+     */
+    className?: string;
+    /**
+     * Use inline-block display instead of block.
+     * Useful when the dropdown trigger should size to its content
+     * (e.g., UserMenu, MenuButton) rather than fill the parent width.
+     */
+    inline?: boolean;
+}
+/**
+ * Root Dropdown component. Provides dropdown context to sub-components.
+ */
+export declare const Dropdown: {
+    ({ children, className, inline, ...options }: DropdownProps): import("react/jsx-runtime").JSX.Element;
+    Trigger: ({ children, className, showTriggerIcon, ...props }: DropdownTriggerProps) => import("react/jsx-runtime").JSX.Element;
+    Panel: ({ children, className, ...props }: DropdownPanelProps) => import("react/jsx-runtime").JSX.Element;
+    Item: ({ children, className, description, disabled, icon, index, isActive, isCritical, onClick, trailingIcon, ...props }: DropdownItemProps) => import("react/jsx-runtime").JSX.Element;
+    Heading: ({ children, className, ...props }: DropdownHeadingProps) => import("react/jsx-runtime").JSX.Element;
+    Separator: ({ className, ...props }: DropdownSeparatorProps) => import("react/jsx-runtime").JSX.Element;
+    Filter: ({ className, filterIcon, label, noResultsText, onFilterChange, placeholder, showNoResults, ...props }: DropdownFilterProps) => import("react/jsx-runtime").JSX.Element;
+};
+export interface DropdownTriggerProps extends ComponentPropsWithoutRef<'button'> {
+    /**
+     * Trigger content (label text, icon, etc.).
+     */
+    children?: ReactNode;
+    /**
+     * Additional class names.
+     */
+    className?: string;
+    /**
+     * Show a directional icon on the trigger that indicates the dropdown can be expanded.
+     */
+    showTriggerIcon?: boolean;
+}
+export interface DropdownPanelProps extends ComponentPropsWithoutRef<'ul'> {
+    /**
+     * Panel content (Items, Headings, Separators, Filter, etc.).
+     */
+    children?: ReactNode;
+    /**
+     * Additional class names.
+     */
+    className?: string;
+}
+export interface DropdownItemProps extends ComponentPropsWithoutRef<'li'> {
+    /**
+     * Item content — label text, or a link element for navigation items.
+     */
+    children?: ReactNode;
+    /**
+     * Additional class names.
+     */
+    className?: string;
+    /**
+     * Secondary text displayed below the label.
+     */
+    description?: ReactNode;
+    /**
+     * Disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * Leading content — PDSIcon name, or custom ReactNode (Avatar, etc.).
+     */
+    icon?: ReactNode;
+    /**
+     * Index of this item in the list (required for keyboard navigation).
+     */
+    index: number;
+    /**
+     * Selected or current state.
+     */
+    isActive?: boolean;
+    /**
+     * Destructive action styling.
+     */
+    isCritical?: boolean;
+    /**
+     * Trailing content — check icon, lock icon, or custom ReactNode.
+     */
+    trailingIcon?: ReactNode;
+}
+export interface DropdownHeadingProps extends ComponentPropsWithoutRef<'li'> {
+    /**
+     * Heading text.
+     */
+    children?: ReactNode;
+    /**
+     * Additional class names.
+     */
+    className?: string;
+}
+export interface DropdownSeparatorProps extends ComponentPropsWithoutRef<'li'> {
+    /**
+     * Additional class names.
+     */
+    className?: string;
+}
+export type DropdownFilterIcon = 'filter' | 'none' | 'search';
+export interface DropdownFilterProps extends ComponentPropsWithoutRef<'li'> {
+    /**
+     * Additional class names.
+     */
+    className?: string;
+    /**
+     * Icon to display inside the filter input.
+     */
+    filterIcon?: DropdownFilterIcon;
+    /**
+     * Label for the filter input (screen readers).
+     */
+    label?: string;
+    /**
+     * Text shown when no items match the filter.
+     */
+    noResultsText?: string;
+    /**
+     * Callback when the filter value changes.
+     */
+    onFilterChange?: (value: string) => void;
+    /**
+     * Placeholder text for the filter input.
+     */
+    placeholder?: string;
+    /**
+     * Whether to show the "no results" message.
+     */
+    showNoResults?: boolean;
+}

package/dist/components/Dropdown/DropdownSelectedIcon.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Selected-state check mark icon for dropdown items.
+ * Used alongside the pds-dropdown__selected-icon CSS class.
+ */
+export declare const DropdownSelectedIcon: ({ className, }: {
+    className?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FileDiff/FileDiff.d.ts

@@ -23,7 +23,7 @@ export interface FileDiffProps extends ComponentPropsWithoutRef<'div'> {
     /**
      * Object with strings for tooltips and screen reader labels.
      */
-    labelStrings?: {
+    translationStrings?: {
         additions?: string;
         deletions?: string;
         linesChanged?: string;
@@ -32,4 +32,4 @@ export interface FileDiffProps extends ComponentPropsWithoutRef<'div'> {
 /**
  * FileDiff UI component
  */
-export declare const FileDiff: ({ additions, className, componentWidth, deletions, labelStrings, ...props }: FileDiffProps) => import("react/jsx-runtime").JSX.Element;
+export declare const FileDiff: ({ additions, className, componentWidth, deletions, translationStrings, ...props }: FileDiffProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/IdentityBlock/IdentityBlock.d.ts

@@ -0,0 +1,37 @@
+import { ComponentPropsWithoutRef } from 'react';
+import { AvatarProps } from '../Avatar/Avatar';
+import './identity-block.css';
+/**
+ * Prop types for IdentityBlock
+ */
+export interface IdentityBlockProps extends ComponentPropsWithoutRef<'div'> {
+    /**
+     * Props to pass to the Avatar component.
+     */
+    avatarProps?: AvatarProps;
+    /**
+     * Additional class names
+     */
+    className?: string;
+    /**
+     * When true, only the avatar is shown (text is hidden).
+     */
+    isSidebarCollapsed?: boolean;
+    /**
+     * When true, displays a smaller avatar with only the primary text.
+     * Secondary text is not rendered even if provided.
+     */
+    isSingleLine?: boolean;
+    /**
+     * First line of text (e.g., organization name).
+     */
+    primaryText?: string;
+    /**
+     * Second line of text (e.g., user name).
+     */
+    secondaryText?: string;
+}
+/**
+ * IdentityBlock UI component
+ */
+export declare const IdentityBlock: ({ avatarProps, className, isSidebarCollapsed, isSingleLine, primaryText, secondaryText, ...props }: IdentityBlockProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/Popover/Popover.d.ts

@@ -58,8 +58,12 @@ export interface PopoverProps extends Omit<ComponentPropsWithoutRef<'div'>, 'con
      * The icon to use as the trigger.
      */
     triggerIcon?: 'circleInfo' | 'circleQuestion';
+    /**
+     * Size of the trigger icon. Uses PDS Icon sizing.
+     */
+    triggerIconSize?: 's' | 'm' | 'l';
 }
 /**
  * Popover UI component
  */
-export declare const Popover: ({ className, classNameContainer, closeButtonLabel, content, customTrigger, hasCloseButton, offsetValue, onClose, placement, popoverIsOpen, setPopoverIsOpen, title, triggerAccessibleText, triggerIcon, ...props }: PopoverProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Popover: ({ className, classNameContainer, closeButtonLabel, content, customTrigger, hasCloseButton, offsetValue, onClose, placement, popoverIsOpen, setPopoverIsOpen, title, triggerAccessibleText, triggerIcon, triggerIconSize, ...props }: PopoverProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SiteDashboardHeading/SiteDashboardHeading.d.ts

@@ -36,7 +36,7 @@ export interface SiteDashboardHeadingProps extends ComponentPropsWithoutRef<'div
     /**
      * Site plan level.
      */
-    sitePlanLevel?: SitePlanLevel;
+    sitePlanLevel?: SitePlanLevel | (string & {});
     /**
      * Site type.
      */

package/dist/components/SiteFooter/SiteFooter.d.ts

@@ -0,0 +1,38 @@
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import { ContainerWidth } from '../../libs/types/custom-types';
+import './site-footer.css';
+export interface SiteFooterProps extends ComponentPropsWithoutRef<'footer'> {
+    /**
+     * HTML element to render. Use 'footer' for standalone usage or 'div' when nested inside another footer landmark.
+     */
+    as?: 'footer' | 'div';
+    /**
+     * Footer content.
+     */
+    children?: ReactNode;
+    /**
+     * Additional class names
+     */
+    className?: string;
+    /**
+     * PDS container width.
+     */
+    containerWidth?: ContainerWidth;
+    /**
+     * Should the footer have a top border?
+     */
+    hasTopBorder?: boolean;
+    /**
+     * Legal policy links.
+     */
+    legalLinks?: Array<'privacy' | 'dataSubjectRequest' | 'cookiePolicy' | 'termsOfUse' | 'acceptableUse' | 'accessibilityStatement'>;
+    /**
+     * The background color of the surface this footer is placed on.
+     * Use 'secondary' to strengthen the internal divider border when the footer sits on a secondary background.
+     */
+    surfaceColor?: 'default' | 'secondary';
+}
+/**
+ * SiteFooter UI component
+ */
+export declare const SiteFooter: ({ as: Element, children, className, containerWidth, hasTopBorder, legalLinks, surfaceColor, ...props }: SiteFooterProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SortableList/SortableList.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { SortableListProps } from './types';
+import './sortable-list.css';
+export interface SortableListHandle {
+    /** Reverts the list to the order it was in when drag mode was last enabled. */
+    resetToSnapshot: () => void;
+}
+export declare const SortableList: React.ForwardRefExoticComponent<SortableListProps & React.RefAttributes<SortableListHandle>>;

package/dist/components/SortableList/SortableListHeader.d.ts

@@ -0,0 +1,7 @@
+import type { SortableListColumn, SortableListHeaderProps } from './types';
+import './sortable-list.css';
+interface SortableListHeaderInternalProps {
+    columns?: SortableListColumn[];
+}
+export declare const SortableListHeader: ({ children, className, columns, ...props }: SortableListHeaderProps & SortableListHeaderInternalProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/SortableList/SortableRow.d.ts

@@ -0,0 +1,16 @@
+import type { SortableListColumn, SortableRowProps } from './types';
+import './sortable-list.css';
+interface SortableRowInternalProps {
+    columns?: SortableListColumn[];
+    depth?: number;
+    hasChildren?: boolean;
+    isDragActive?: boolean;
+    isDragging?: boolean;
+    isDropTarget?: boolean;
+    isExpanded?: boolean;
+    isProjectedParent?: boolean;
+    onToggleExpand?: () => void;
+    projectedDepthDelta?: number;
+}
+export declare const SortableRow: ({ children, className, columns, depth, hasChildren, id, isDragActive, isDragging: _isDraggingProp, isDropTarget, isExpanded, isLocked, isProjectedParent, onToggleExpand, projectedDepthDelta, ...props }: SortableRowProps & SortableRowInternalProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/SortableList/sortable-utils.d.ts

@@ -0,0 +1,19 @@
+import type { FlattenedNode, SortableTreeNode } from './types';
+/**
+ * Flatten a tree into a list suitable for dnd-kit's SortableContext.
+ * Only includes nodes whose ancestors are all expanded.
+ */
+export declare function flattenTree(items: SortableTreeNode[], expandedIds: Set<string>, parentId?: string | null, depth?: number, ancestorIds?: string[]): FlattenedNode[];
+/**
+ * Rebuild a tree from a flat list of nodes.
+ */
+export declare function buildTree(flatNodes: FlattenedNode[]): SortableTreeNode[];
+/**
+ * Find a node by id in a tree.
+ */
+export declare function findItem(items: SortableTreeNode[], id: string): SortableTreeNode | undefined;
+/**
+ * Calculate the projected depth during a drag based on horizontal pointer offset.
+ * Returns the clamped depth the item would land at if dropped.
+ */
+export declare function getProjectedDepth(flatNodes: FlattenedNode[], activeId: string, overId: string, dragOffsetX: number, indentSize: number, maxDepth: number, activeNodeDepth?: number): number;

package/dist/components/SortableList/types.d.ts

@@ -0,0 +1,142 @@
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+export interface SortableTreeNode {
+    [key: string]: unknown;
+    children?: SortableTreeNode[];
+    id: string;
+}
+export interface FlattenedNode {
+    ancestorIds: string[];
+    data: SortableTreeNode;
+    depth: number;
+    hasChildren: boolean;
+    id: string;
+    index: number;
+    isExpanded: boolean;
+    parentId: string | null;
+}
+export interface SortableListColumn {
+    /**
+     * Unique identifier for this column. Used as the slot name in SortableRow.
+     */
+    id: string;
+    /**
+     * Display label for the column header. Also used as the visually-hidden
+     * label for screen readers inside each row cell.
+     */
+    label: string;
+    /**
+     * CSS width value for the column (e.g., '1fr', '10rem', '150px').
+     */
+    width: string;
+}
+export type ReorderMode = 'always' | 'toggle' | 'disabled';
+export interface SortableRowMeta {
+    depth: number;
+    hasChildren: boolean;
+    index: number;
+    isDragging: boolean;
+    isExpanded: boolean;
+    isLocked: boolean;
+    toggleExpand: () => void;
+}
+export interface SortableListProps extends ComponentPropsWithoutRef<'div'> {
+    /**
+     * Content for the header area. Typically a SortableListHeader.
+     */
+    children?: ReactNode;
+    /**
+     * Additional class names.
+     */
+    className?: string;
+    /**
+     * Column definitions for grid-based layout. Defines widths, labels,
+     * and slot names used by both the header and row content areas.
+     * When omitted, the row content area uses a plain flex layout.
+     */
+    columns?: SortableListColumn[];
+    /**
+     * Initial tree data (uncontrolled mode).
+     */
+    defaultItems?: SortableTreeNode[];
+    /**
+     * Function to extract a human-readable label from an item for screen reader
+     * announcements (e.g. "Picked up Home page. Position 1 of 5."). Defaults to
+     * using the item's id.
+     */
+    getItemLabel?: (item: SortableTreeNode) => string;
+    /**
+     * Whether drag is currently enabled. Only relevant when reorderMode='toggle'.
+     * Controlled externally (e.g., by a UtilityBar lock/unlock button).
+     */
+    isDragEnabled?: boolean;
+    /**
+     * Function that returns true for items whose position should be fixed.
+     * Locked items cannot be dragged and cannot be displaced by other items
+     * moving around them. Use this for items that must always remain at the
+     * top or bottom of the list (e.g. a Home page that is always first).
+     * Does not prevent other items from being nested inside the locked item —
+     * use isNestingLocked for that.
+     */
+    isItemLocked?: (item: SortableTreeNode) => boolean;
+    /**
+     * Function that returns true for items that should not accept nested
+     * children. Items matching this function can still be moved to a new
+     * position; they just cannot be used as a parent during drag-and-drop.
+     */
+    isNestingLocked?: (item: SortableTreeNode) => boolean;
+    /**
+     * Tree-structured data (controlled mode).
+     */
+    items?: SortableTreeNode[];
+    /**
+     * Maximum nesting depth allowed. 0 = flat list, no nesting.
+     */
+    maxDepth?: 0 | 1 | 2 | 3 | 4 | 5;
+    /**
+     * Callback when items are reordered. Receives the new tree structure.
+     */
+    onReorder?: (items: SortableTreeNode[]) => void;
+    /**
+     * Render function for each row. Receives the item data and tree metadata.
+     */
+    renderRow: (item: SortableTreeNode, meta: SortableRowMeta) => ReactNode;
+    /**
+     * Controls drag-and-drop availability.
+     * - 'always': drag handles always visible (default).
+     * - 'toggle': drag state controlled externally via isDragEnabled prop.
+     * - 'disabled': no dragging, no handles, read-only list.
+     */
+    reorderMode?: ReorderMode;
+    /**
+     * Custom screen reader instructions for drag operations.
+     */
+    screenReaderInstructions?: string;
+}
+export interface SortableRowProps extends ComponentPropsWithoutRef<'div'> {
+    /**
+     * Child elements — the consumer-defined row content.
+     */
+    children: ReactNode;
+    /**
+     * Additional class names.
+     */
+    className?: string;
+    /**
+     * Unique identifier for this row. Must match an item id.
+     */
+    id: string;
+    /**
+     * Prevents this row from being dragged or receiving drops.
+     */
+    isLocked?: boolean;
+}
+export interface SortableListHeaderProps extends ComponentPropsWithoutRef<'div'> {
+    /**
+     * Child elements assigned to named slots.
+     */
+    children?: ReactNode;
+    /**
+     * Additional class names.
+     */
+    className?: string;
+}

package/dist/components/SortableList/useSortableTree.d.ts

@@ -0,0 +1,18 @@
+import type { FlattenedNode, SortableTreeNode } from './types';
+interface UseSortableTreeOptions {
+    defaultItems?: SortableTreeNode[];
+    isDragEnabled?: boolean;
+    items?: SortableTreeNode[];
+    onReorder?: (items: SortableTreeNode[]) => void;
+}
+export declare function useSortableTree({ defaultItems, isDragEnabled, items: controlledItems, onReorder, }: UseSortableTreeOptions): {
+    currentItems: SortableTreeNode[];
+    expandedIds: Set<string>;
+    expandItem: (id: string) => void;
+    flatNodes: FlattenedNode[];
+    handleReorder: (updatedFlat: FlattenedNode[]) => void;
+    resetToSnapshot: () => void;
+    sortableIds: string[];
+    toggleExpand: (id: string) => void;
+};
+export {};

package/dist/components/{RefreshChecker/RefreshChecker.d.ts → StatusChecker/StatusChecker.d.ts}

@@ -1,17 +1,7 @@
 import { ComponentPropsWithoutRef } from 'react';
-import './refresh-checker.css';
-/**
- * Enum for RefreshChecker states
- */
-export declare enum RefreshCheckerState {
-    CHECKED = "checked",
-    DEFAULT = "default",
-    WORKING = "working"
-}
-/**
- * Prop types for RefreshChecker
- */
-interface RefreshCheckerProps extends ComponentPropsWithoutRef<'div'> {
+import './status-checker.css';
+export type StatusCheckerState = 'checked' | 'default' | 'working';
+export interface StatusCheckerProps extends ComponentPropsWithoutRef<'div'> {
     /**
      * Alignment of the component. Default is left.
      */
@@ -45,10 +35,6 @@ interface RefreshCheckerProps extends ComponentPropsWithoutRef<'div'> {
     /**
      * State of the component
      */
-    state?: `${RefreshCheckerState}`;
+    state?: StatusCheckerState;
 }
-/**
- * RefreshChecker UI component
- */
-export declare const RefreshChecker: ({ alignment, className, componentWidth, labelStrings, lastChecked, onCheck, state, ...props }: RefreshCheckerProps) => import("react/jsx-runtime").JSX.Element;
-export {};
+export declare const StatusChecker: ({ alignment, className, componentWidth, labelStrings, lastChecked, onCheck, state, ...props }: StatusCheckerProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/StatusIndicator/StatusIndicator.d.ts

@@ -13,11 +13,11 @@ export interface StatusIndicatorProps extends ComponentPropsWithoutRef<'div'> {
     /**
      * Sets the size
      */
-    size?: 'sm' | 'md';
+    size?: 'xs' | 's';
     /**
      * Sets status type
      */
-    type: Exclude<StatusType, 'discovery'> | 'neutral' | 'new' | 'working';
+    type: StatusType | 'disabled' | 'neutral' | 'working';
 }
 /**
  * StatusIndicator UI component