@protonradio/proton-ui 0.11.1-beta.0 → 0.11.1

package/dist/index.d.ts

@@ -1,32 +1,29 @@
-import { AriaButtonProps } from 'react-aria';
-import { AriaDialogProps } from 'react-aria';
-import { AriaPopoverProps } from 'react-aria';
-import { AriaTableProps } from 'react-aria';
-import { ColumnProps } from '@react-stately/table';
+import { AriaAttributes } from 'react';
+import { AriaDialogProps } from '@react-aria/dialog';
+import { AriaPopoverProps } from '@react-aria/overlays';
 import { default as default_2 } from 'react';
 import { DOMProps } from '@react-types/shared';
 import { ForwardRefExoticComponent } from 'react';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
-import { OverlayTriggerProps } from 'react-stately';
-import { OverlayTriggerState } from 'react-stately';
-import { PressEvent } from 'react-aria';
+import { MouseEvent as MouseEvent_2 } from 'react';
+import { OverlayTriggerProps } from '@react-stately/overlays';
+import { OverlayTriggerState } from '@react-stately/overlays';
+import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
-import { RowProps } from '@react-stately/table';
-import { Section } from '@react-stately/table';
-import { Selection as Selection_2 } from 'react-stately';
-import { TableBodyProps } from '@react-stately/table';
-import { TableHeader } from '@react-stately/table';
-import { TableStateProps } from 'react-stately';
+import { Selection as Selection_2 } from '@react-types/shared';
+import { TableColumnData as TableColumnData_2 } from '../Table';
 import { TooltipProps as TooltipProps_2 } from 'react-aria-components';
 import { TooltipTriggerComponentProps } from 'react-aria-components';
 
 /**
  * ActionMenu to display a menu of actions.
  * Renders a list of actions as a focusable menu, or non-focusable children.
- * @interface ActionMenuProps
+ *
+ * API:
+ *  - {@link ActionMenuProps}
  */
-export declare const ActionMenu: ({ isOpen, selectionMode, selectedKeys, defaultSelectedKeys, disabledKeys, children, showCancel, cancelButtonText, actions, title, onSelectionChange, onClose, "data-testid": testId, menuId, }: ActionMenuProps) => JSX_2.Element;
+export declare const ActionMenu: ({ isOpen, selectionMode, selectedKeys, defaultSelectedKeys, disabledKeys, children, showCancel, cancelButtonText, actions, title, onSelectionChange, onClose, "data-testid": testId, }: ActionMenuProps) => JSX_2.Element;
 
 declare interface ActionMenuAction {
     key: string;
@@ -38,35 +35,63 @@ declare interface ActionMenuAction {
 }
 
 declare interface ActionMenuProps {
-    isOpen: boolean;
-    selectionMode?: "single" | "multiple" | "none";
-    selectedKeys?: string[];
-    defaultSelectedKeys?: string[];
-    disabledKeys?: string[];
+    /** The actions of the menu
+     * - type {@link ActionMenuAction}[]
+     */
+    actions?: ActionMenuAction[];
+    /** The text of the cancel button */
+    cancelButtonText?: string;
+    /** The children of the menu */
     children?: ReactNode | ((props: {
         close: () => void;
     }) => ReactNode);
-    showCancel?: boolean;
-    cancelButtonText?: string;
-    title?: string;
-    actions?: ActionMenuAction[];
+    /** The test id of the menu */
+    "data-testid"?: string;
+    /** The keys of the default selected items */
+    defaultSelectedKeys?: string[];
+    /** The keys of the disabled items */
+    disabledKeys?: string[];
+    /** Whether the menu is open
+     * @default false
+     */
+    isOpen: boolean;
+    /** The callback function to close the menu */
     onClose?: () => void;
+    /** The callback function to change the selection
+     * - type {@link Selection}
+     */
     onSelectionChange?: (keys: Selection_2) => void;
-    "data-testid"?: string;
-    menuId?: string;
+    /** The selection mode of the menu
+     * @default "single"
+     */
+    selectionMode?: "single" | "multiple" | "none";
+    /** The keys of the selected items */
+    selectedKeys?: string[];
+    /** Whether to show the cancel button */
+    showCancel?: boolean;
+    /** The title of the menu */
+    title?: string;
 }
 
+/**
+ * A badge component for displaying status, categories, or counts with various visual styles.
+ *
+ * API:
+ *  - {@link BadgeProps}
+ *  - extends {@link React.HTMLAttributes}
+ */
 export declare const Badge: ({ variant, children, ...props }: BadgeProps) => JSX_2.Element;
 
-export declare interface BadgeProps extends React.HTMLAttributes<HTMLDivElement> {
-    /**
-     * The badge's visual aesthetic.
-     */
-    variant?: BadgeVariant;
+declare interface BadgeProps extends React.HTMLAttributes<HTMLDivElement> {
     /**
      * The content to display within the badge.
      */
     children: ReactNode;
+    /**
+     * The badge's visual aesthetic.
+     * - type {@link BadgeVariant}
+     */
+    variant?: BadgeVariant;
 }
 
 export declare type BadgeVariant = "primary" | "secondary" | "transparent" | "success" | "warning" | "danger";
@@ -75,60 +100,96 @@ export declare const BadgeVariants: Record<BadgeVariant, BadgeVariant>;
 
 /**
  * A banner used to display a success, warning, or error message.
- * @interface BannerProps
+ *
+ * API:
+ *  - {@link BannerProps}
+ *  - extends {@link BannerIconProps}
  */
 export declare const Banner: {
     ({ variant, rounded, icon, compact, children, "data-testid": dataTestId, }: BannerProps): JSX_2.Element;
-    Title: ({ children, ...props }: {
-        children: ReactNode;
-    }) => JSX_2.Element;
-    Content: ({ children, ...props }: {
-        children: ReactNode;
-    }) => JSX_2.Element;
-    Icon: ({ children, icon, ...props }: BannerIconProps) => JSX_2.Element;
-    Action: ({ children, ...props }: ButtonProps) => JSX_2.Element;
-    Actions: default_2.FC<BannerActionsProps>;
-    icons: {
-        success: JSX_2.Element;
-        warning: JSX_2.Element;
-        danger: JSX_2.Element;
+    displayName: string;
+    /**
+     * Renders an h3 styled banner.
+     */
+    Title: {
+        ({ children, "data-testid": dataTestId, }: {
+            children: ReactNode;
+            "data-testid"?: string;
+        }): JSX_2.Element;
+        displayName: string;
     };
-    variants: {
-        readonly default: "default";
-        readonly success: "success";
-        readonly warning: "warning";
-        readonly danger: "danger";
+    /**
+     * Renders a p styled banner.
+     */
+    Content: {
+        ({ children, "data-testid": dataTestId, }: {
+            children: ReactNode;
+            "data-testid"?: string;
+        }): JSX_2.Element;
+        displayName: string;
+    };
+    /**
+     * Renders an icon inline with the banner title.
+     *
+     * API:
+     *  - {@link BannerIconProps}
+     */
+    Icon: {
+        ({ icon, "data-testid": dataTestId }: BannerIconProps): JSX_2.Element;
+        displayName: string;
+    };
+    /**
+     * Renders a Proton Button.
+     * - @prop buttonProps {@link ButtonProps}
+     */
+    Action: {
+        ({ children, ...buttonProps }: ButtonProps): JSX_2.Element;
+        displayName: string;
+    };
+    /**
+     * Renders Proton Buttons in a responsive actions grid.
+     */
+    Actions: {
+        ({ children }: {
+            children: ReactNode;
+        }): JSX_2.Element;
+        displayName: string;
     };
 };
 
-declare interface BannerActionsProps {
-    children: ReactNode;
-}
+export declare const BANNER_ICONS: {
+    success: JSX_2.Element;
+    warning: JSX_2.Element;
+    danger: JSX_2.Element;
+};
+
+export declare const BANNER_VARIANTS: {
+    readonly default: "default";
+    readonly success: "success";
+    readonly warning: "warning";
+    readonly danger: "danger";
+};
 
 declare interface BannerIconProps {
+    /**
+     * Optional custom icon or children for the icon area.
+     */
+    children?: ReactNode;
     /**
      * The icon to display in the banner.
-     * Can be a boolean to conditionally show or hide,
-     * or a ReactNode to provide a custom icon.
+     * Can be a boolean to conditionally show or hide, or a ReactNode to provide a custom icon.
      */
     icon?: boolean | ReactNode;
     /**
-     * Optional custom icon or children for the icon area.
+     * The data-testid to display within the banner.
      */
-    children?: ReactNode;
+    "data-testid"?: string;
 }
 
 declare interface BannerProps extends BannerIconProps {
-    /**
-     * The banner's visual aesthetic.
-     */
-    variant?: BannerVariant;
-    /**
-     * Round the corners of the banner.
-     */
-    rounded?: boolean;
     /**
      * Compact padding around the content of the banner.
+     * @default true
      */
     compact?: boolean;
     /**
@@ -139,10 +200,47 @@ declare interface BannerProps extends BannerIconProps {
      * The data-testid to display within the banner.
      */
     "data-testid"?: string;
+    /**
+     * Round the corners of the banner.
+     * @default true
+     */
+    rounded?: boolean;
+    /**
+     * The banner's visual aesthetic.
+     * - type {@link BannerVariant}
+     */
+    variant?: BannerVariant;
 }
 
 export declare type BannerVariant = "default" | "success" | "warning" | "danger";
 
+declare interface BaseDataTableProps<T = any> {
+    /** Array of column definitions
+     * - {@link DataTableColumn}
+     */
+    columns: DataTableColumn<T>[];
+    /** Array of data objects to display. Can be empty array for loading/empty states */
+    data?: T[] | null;
+    /** Loading state */
+    loading?: boolean;
+    /** Tombstone component to use when loading */
+    tombstoneComponent?: ReactNode;
+    /** Error state */
+    error?: boolean | string;
+    /** Table name/caption for accessibility. This provides essential context for screen readers. */
+    name: string;
+    /** Callback when a row is clicked */
+    onRowClick?: (row: T) => void;
+    /** Custom empty state message */
+    emptyMessage?: string;
+    /** Custom error message */
+    errorMessage?: string;
+    /** Number of skeleton rows to show in loading state */
+    loadingRows?: number;
+    /** Test ID for testing purposes */
+    "data-testid"?: string;
+}
+
 declare interface BaseInputProps {
     /**
      * onChange handler for the input
@@ -194,6 +292,7 @@ declare interface BaseInputProps {
     /**
      * The type attribute of the input element.
      * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/type
+     * @default "text"
      */
     type?: string;
     /**
@@ -201,17 +300,44 @@ declare interface BaseInputProps {
      * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#value
      */
     value?: string;
+    /**
+     * Whether the input is required.
+     * @default false
+     */
+    isRequired?: boolean;
+    /**
+     * Whether the input is read-only.
+     * @default false
+     */
+    isReadOnly?: boolean;
+    /**
+     * Called when the input is submitted (e.g. by pressing Enter).
+     */
+    onSubmit?: default_2.FormEventHandler<HTMLInputElement>;
+    /**
+     * Called when the input is cleared (e.g. by pressing Escape).
+     */
+    onClear?: () => void;
 }
 
 /**
- * A customizable button component that can render as either a button or anchor element
- * @interface ButtonProps
+ * A customizable button component that can render as either a button or anchor element.
+ *
+ * API:
+ *  - {@link ButtonProps}
  */
 export declare const Button: ForwardRefExoticComponent<ButtonProps & RefAttributes<HTMLAnchorElement | HTMLButtonElement>>;
 
+/**
+ * A radio button group component that allows selection of a single option from multiple choices.
+ *
+ * API:
+ *  - {@link ButtonGroupProps}
+ */
 export declare function ButtonGroup(props: ButtonGroupProps): JSX_2.Element;
 
 export declare namespace ButtonGroup {
+    var displayName: string;
     var Option: (props: ButtonGroupOptionProps) => JSX_2.Element;
 }
 
@@ -247,76 +373,88 @@ declare interface ButtonGroupProps {
     children?: React.ReactNode;
 }
 
-declare interface ButtonProps extends AriaButtonProps<"button"> {
+declare interface ButtonProps {
     /** The button's visual aesthetic
-     * @param {ButtonVariant} variant
+     * - type {@link ButtonVariant}
      */
     variant?: ButtonVariant;
     /** The size of the button
-     * @param {ButtonSize} size
-     * @default "fullWidth"
+     * - type {@link ButtonSize}
+     * @default "medium"
      */
     size?: ButtonSize;
     /** Should the button be full width?
-     * @param {boolean} fullWidth
+     * @default false
      */
     fullWidth?: boolean;
-    /** The prefix to display within the button
-     * @param {React.ReactNode} icon
-     */
+    /** The prefix to display within the button */
     icon?: React.ReactNode;
-    /** Should the button be non-interactive?
-     * @param {boolean} isDisabled
-     */
+    /** Should the button be non-interactive? */
     isDisabled?: boolean;
-    /** The URL that the button should link to. Turns the element into an `a` tag. If the URL is external, you should pass the entire URL to the `to` prop (e.g. `https://example.com`).
-     * @param {string} to
-     */
+    /** The URL that the button should link to. Turns the element into an `a` tag. If the URL is external, you should pass the entire URL to the `to` prop (e.g. `https://example.com`). */
     to?: string;
-    /** The target attribute for the link. Defaults to `_blank` if the URL is external.
-     * @param {string} target
-     */
+    /** The target attribute for the link. Defaults to `_blank` if the URL is external. */
     target?: "_blank" | "_self" | "_parent" | "_top" | string;
-    /** Called when the button is pressed (on release, not keydown)
-     * @param {(e: PressEvent) => void} onPress
-     */
-    onPress?: (e: PressEvent) => void;
-    /** The type of button
-     * @param {"button" | "submit" | "reset"} type
-     */
+    /** Called when the button is pressed (on release, not keydown) */
+    onPress?: (e: MouseEvent_2<HTMLButtonElement | HTMLAnchorElement>) => void;
+    /** The type of button */
     type?: "button" | "submit" | "reset";
-    /** The test ID for the button
-     * @param {string} dataTestId
-     */
+    /** The test ID for the button */
     "data-testid"?: string;
-    /** The content to display within the button
-     * @param {React.ReactNode} children
-     */
+    /** The content to display within the button */
     children?: React.ReactNode;
 }
 
-declare type ButtonSize = "small" | "medium" | "large" | "xlarge" | "2xlarge";
+export declare type ButtonSize = "small" | "medium" | "large" | "xlarge" | "2xlarge";
+
+export declare const ButtonSizes: Record<ButtonSize, ButtonSize>;
 
 export declare type ButtonVariant = "primary" | "secondary" | "success" | "danger" | "translucent";
 
+export declare const ButtonVariants: Record<ButtonVariant, ButtonVariant>;
+
+/**
+ * A button with a select menu.
+ *
+ * API:
+ *  - {@link ButtonWithSelectProps}
+ *  - extends {@link ButtonProps}
+ */
 export declare function ButtonWithSelect({ items, defaultValue, children, onSelectionChange, disabledKeys, selectedKey, icon, variant, fullWidth, onPress, ...buttonProps }: ButtonWithSelectProps): JSX_2.Element;
 
-declare type ButtonWithSelectProps = {
-    items: MenuItemType[];
+export declare namespace ButtonWithSelect {
+    var displayName: string;
+}
+
+declare interface ButtonWithSelectProps extends ButtonProps {
+    /**
+     * The default value of the select menu.
+     */
     defaultValue?: string;
-    children: default_2.ReactNode;
+    /**
+     * The keys of the disabled items.
+     */
+    disabledKeys?: string[];
+    /**
+     * The items to display in the select menu.
+     * - type {@link ActionMenuAction}
+     */
+    items: ActionMenuAction[];
+    /**
+     * The callback function to call when the selection changes.
+     */
     onSelectionChange?: (key: string) => void;
+    /**
+     * The key of the selected item.
+     */
     selectedKey?: string;
-    disabledKeys?: string[];
-} & ButtonProps;
-
-export declare const Cell: <T>(props: ProtonColumnProps<T>) => JSX.Element;
-
-export declare const Column: <T>(props: ProtonColumnProps<T>) => JSX.Element;
+}
 
 /**
  * Input with a button to copy value to the clipboard.
- * @interface CopyInputProps
+ *
+ * API:
+ *  - {@link CopyInputProps}
  */
 export declare function CopyInput({ name, value, isDisabled, onError, onSuccess, }: CopyInputProps): JSX_2.Element;
 
@@ -333,8 +471,34 @@ declare interface CopyInputProps {
     onSuccess?: () => void;
 }
 
+/**
+ * DataTable is a declarative wrapper around the base Table component that provides:
+ *
+ * API:
+ *  - {@link DataTableProps}
+ *  - {@link SortingConfig}
+ */
+export declare function DataTable<T = any>(props: DataTableProps<T>): JSX_2.Element;
+
+export declare interface DataTableColumn<T> {
+    /** id for the column */
+    id: string;
+    /** Header text or component */
+    header: ReactNode;
+    /** Function to render cell content from row data */
+    cell: (row: T) => ReactNode;
+    /** Whether this column should be hidden */
+    hidden?: boolean;
+}
+
+export declare type DataTableProps<T = any> = BaseDataTableProps<T> & SortingConfig<T>;
+
 /**
  * Intended use in overlay containers such as modals or popovers.
+ *
+ * API:
+ *  - {@link DialogProps}
+ *  - extends {@link AriaDialogProps}
  */
 export declare function Dialog({ title, children, ...props }: DialogProps): JSX_2.Element;
 
@@ -348,9 +512,10 @@ declare interface DialogProps extends AriaDialogProps {
  *
  * This component is designed to be used as a visual layer that sits on top of other content
  * to create a sense of depth or hierarchy in the UI. It uses the `--proton-control__background-color-light`
- * CSS variable which is theme-aware and will adapt to light, dark, and custom-dark themes.
+ * CSS variable which is theme-aware and will adapt to light, dark themes.
  *
- * @interface ElevationProps
+ * API:
+ *  - {@link ElevationProps}
  */
 export declare const Elevation: ({ children, hasPrimaryGradient, "data-testid": dataTestId, }: ElevationProps) => JSX_2.Element;
 
@@ -359,23 +524,29 @@ declare interface ElevationProps {
      * The content to be displayed within the elevation.
      */
     children?: ReactNode;
+    /**
+     * The data-testid attribute for testing purposes.
+     */
+    "data-testid"?: string;
     /**
      * Whether the elevation should have a background gradient.
      * @important only works in custom dark mode
      * @default false
      */
     hasPrimaryGradient?: boolean;
-    /**
-     * The data-testid attribute for testing purposes.
-     */
-    "data-testid"?: string;
 }
 
-export declare function Icon(props: Omit<IconProps, "svgContent">): JSX_2.Element;
+/**
+ * An icon component that displays SVG icons from a sprite sheet or inline.
+ *
+ * API:
+ *  - {@link IconProps}
+ */
+export declare function Icon(props: IconProps): JSX_2.Element;
 
 declare type IconID = "external-link" | "caret-down" | "caret-right" | "chevron-right" | "chevron-left" | "chevron-up" | "chevron-down";
 
-declare interface IconProps {
+export declare interface IconProps {
     /**
      * The spritesheet ID defined in the Icons spritesheet.
      */
@@ -392,7 +563,9 @@ declare interface IconProps {
 
 /**
  * ImageOverlay component for displaying an image with a blur effect.
- * @interface ImageBackgroundProps
+ *
+ * API:
+ *  - {@link ImageBackgroundProps}
  */
 export declare function ImageBackground({ image, imageUrl, onLoad, }: ImageBackgroundProps): JSX_2.Element;
 
@@ -418,13 +591,16 @@ declare interface ImageBackgroundProps {
 
 /**
  * A controlled and customizable input component with support for labels, prefixes, suffixes, and error states.
+ *
+ * API:
+ *  - {@link BaseInputProps}
  */
 export declare const Input: default_2.ForwardRefExoticComponent<BaseInputProps & default_2.RefAttributes<HTMLInputElement>>;
 
-declare type MenuItemType = ActionMenuAction;
-
 declare interface MenuProps {
-    /** Custom trigger component. If not provided, defaults to ellipsis icon */
+    /** Custom trigger component. If not provided, defaults to ellipsis icon.
+     * - @prop triggerProps {@link TriggerProps}
+     */
     renderTrigger?: (triggerProps: TriggerProps) => ReactNode;
     /** Size of the trigger icon
      * @default 24
@@ -432,9 +608,13 @@ declare interface MenuProps {
     size?: number;
     /** Title of the parent menu */
     title?: string;
-    /** Array of menu actions/items to display */
-    items: MenuItemType[];
-    /** Whether the menu is disabled */
+    /** Array of menu actions/items to display
+     * - type {@link ActionMenuAction}[]
+     */
+    items: ActionMenuAction[];
+    /** Whether the menu is disabled
+     * @default false
+     */
     disabled?: boolean;
     /** Callback when menu closes */
     onClose?: () => void;
@@ -442,8 +622,6 @@ declare interface MenuProps {
     triggerTestId?: string;
     /** Test ID for the menu */
     menuTestId?: string;
-    /** Can be used to target the menu element */
-    menuId?: string;
     /** Callback when a menu item is selected */
     onSelectionChange?: (key: string) => void;
     /** The key of the selected item */
@@ -452,19 +630,42 @@ declare interface MenuProps {
     disabledKeys?: string[];
 }
 
-export declare function MenuTrigger({ renderTrigger, size, title, items, disabled, onClose, triggerTestId, menuTestId, onSelectionChange, selectedKey, disabledKeys, menuId, }: MenuProps): JSX_2.Element;
+/**
+ * A component that displays either a popover menu or an action menu
+ * depending on the screen size when the menu trigger is pressed.
+ *
+ * API:
+ *  - {@link MenuProps}
+ */
+export declare function MenuTrigger({ renderTrigger, size, title, items, disabled, onClose, triggerTestId, menuTestId, onSelectionChange, selectedKey, disabledKeys, }: MenuProps): JSX_2.Element;
 
 export declare const Modal: (({ isOpen, onClose, title, subtitle, body, children, isOverlay, "data-testid": dataTestId, }: ModalProps) => JSX_2.Element) & {
+    /**
+     * Renders a h2 styled title
+     * */
     Title: ({ children }: {
         children: React.ReactNode;
     }) => JSX_2.Element;
+    /**
+     * Renders a h3 styled subtitle
+     * */
     Subtitle: ({ children }: {
         children: React.ReactNode;
     }) => JSX_2.Element;
+    /**
+     * Renders a div styled body
+     * */
     Body: ({ children }: {
         children: React.ReactNode;
     }) => JSX_2.Element;
-    Action: (props: ButtonProps) => JSX_2.Element;
+    /**
+     * Renders a Proton Button action
+     * - @prop buttonProps {@link ButtonProps}
+     * */
+    Action: (buttonProps: ButtonProps) => JSX_2.Element;
+    /**
+     * Renders a group of Proton Buttons
+     * */
     Actions: ({ children }: {
         children: React.ReactNode;
     }) => JSX_2.Element;
@@ -472,87 +673,40 @@ export declare const Modal: (({ isOpen, onClose, title, subtitle, body, children
 
 declare interface ModalProps {
     /**
-     * Controls the visibility of the modal
+     * Optional body text content for the modal
      * */
-    isOpen: boolean;
+    body?: string;
     /**
-     * Callback function when modal is closed
+     * Content to render inside the modal
      * */
-    onClose?: () => void;
+    children: React.ReactNode;
+    /**
+     * data-testid for the modal
+     * */
+    "data-testid"?: string;
+    /**
+     * Controls the visibility of the modal
+     * */
+    isOpen: boolean;
     /**
      * Whether to show the modal with an overlay background.
      * @default true
      * */
     isOverlay?: boolean;
     /**
-     * Optional title text for the modal header
+     * Callback function when modal is closed
      * */
-    title?: string;
+    onClose?: () => void;
     /**
      * Optional subtitle text below the modal title
      * */
     subtitle?: string;
     /**
-     * Optional body text content for the modal
-     * */
-    body?: string;
-    /**
-     * Content to render inside the modal
-     * */
-    children: React.ReactNode;
-    /**
-     * data-testid for the modal
+     * Optional title text for the modal header
      * */
-    "data-testid"?: string;
+    title?: string;
 }
 
-declare type Palette = {
-    BASE_COLOR: string;
-    BRAND: {
-        PRIMARY: string;
-        PRIMARY_LIGHT: string;
-        PRIMARY_SUPER_LIGHT: string;
-        SECONDARY: string;
-    };
-    PRIMARY: {
-        PRIMARY_SUPER_DARK: string;
-        PRIMARY_DARK: string;
-        PRIMARY_MEDIUM: string;
-        PRIMARY_MEDIUM_LIGHT: string;
-        PRIMARY_LIGHT: string;
-        PRIMARY_LIGHTEST: string;
-        PRIMARY_SUPER_LIGHT: string;
-    };
-    SECONDARY: {
-        SECONDARY_SUPER_DARK: string;
-        SECONDARY_DARK: string;
-        SECONDARY_MEDIUM: string;
-        SECONDARY_MEDIUM_LIGHT: string;
-        SECONDARY_LIGHT: string;
-        SECONDARY_LIGHTEST: string;
-        SECONDARY_SUPER_LIGHT: string;
-    };
-    SUCCESS: {
-        SUCCESS_DARK: string;
-        SUCCESS_MEDIUM: string;
-        SUCCESS_LIGHT: string;
-        SUCCESS_SUPER_LIGHT: string;
-    };
-    WARNING: {
-        WARNING_DARK: string;
-        WARNING_MEDIUM: string;
-        WARNING_LIGHT: string;
-        WARNING_SUPER_LIGHT: string;
-    };
-    DANGER: {
-        DANGER_SUPER_DARK: string;
-        DANGER_DARK: string;
-        DANGER_MEDIUM: string;
-        DANGER_LIGHT: string;
-        DANGER_SUPER_LIGHT: string;
-    };
-};
-
 /**
  * Popover is an unstyled popover component that handles positioning. It should be used
  * with the Dialog component to provide a styled popover.
@@ -560,52 +714,112 @@ declare type Palette = {
  * A popover displays interactive content in context with a trigger element.
  * A tooltip displays a description of an element on hover or focus.
  *
- * @interface PopoverProps
+ * @see {@link usePopoverTrigger} for a complete usage example
+ *
+ * API:
+ *  - {@link PopoverProps}
+ *  - extends {@link AriaPopoverProps}
  */
 export declare function Popover({ children, state, arrow, offset, ...props }: PopoverProps): JSX_2.Element;
 
 declare interface PopoverProps extends Omit<AriaPopoverProps, "popoverRef"> {
     /**
-     * Content to display within the popover.
+     * Whether to show an arrow on the popover.
      */
-    children: default_2.ReactNode;
+    arrow?: boolean;
     /**
-     * The `isOpen` state of the popover and the methods to toggle it.
+     * Content to display within the popover.
      */
-    state: OverlayTriggerState;
+    children: default_2.ReactNode;
     /**
      * Can optionally forward the ref to the popover.
      */
     popoverRef?: default_2.RefObject<HTMLDivElement>;
     /**
-     * Whether to show an arrow on the popover.
+     * The `isOpen` state of the popover and the methods to toggle it.
+     * - type {@link OverlayTriggerState}
      */
-    arrow?: boolean;
+    state: OverlayTriggerState;
 }
 
-export declare interface ProtonColumnProps<T> extends ColumnProps<T> {
-    align?: "left" | "center" | "right";
-    onClick?: (key: string) => void;
-}
+declare type ProtonColorScale = {
+    SUPER_DARK: string;
+    DARK: string;
+    MEDIUM: string;
+    MEDIUM_LIGHT: string;
+    LIGHT: string;
+    LIGHTEST: string;
+    SUPER_LIGHT: string;
+    WHITE: string;
+};
 
-export declare interface ProtonRowProps<T = object> extends RowProps<T> {
-    backgroundColor?: string;
-    onClick?: (key: string) => void;
-}
+declare type ProtonPalette = {
+    BASE_COLOR: string;
+    BRAND: {
+        PRIMARY: string;
+        PRIMARY_LIGHT: string;
+        PRIMARY_SUPER_LIGHT: string;
+        SECONDARY: string;
+        SECONDARY_LIGHT: string;
+        SECONDARY_SUPER_LIGHT: string;
+    };
+    PRIMARY: ProtonColorScale;
+    SECONDARY: ProtonColorScale;
+    GRAYSCALE: ProtonColorScale;
+};
 
-export declare interface ProtonTableBodyProps<T = object> extends TableBodyProps<T> {
-    showLines?: boolean;
+declare interface ProtonStyleSheet {
+    "--proton-control__background-color": string;
+    "--proton-control__background-color-light": string;
+    "--proton-control__text-color": string;
+    "--proton-control__title-color": string;
+    "--proton-control__border-color": string;
+    "--proton-control__shadow-color": string;
+    "--proton-control__hover-color": string;
+    "--proton-control__border-radius": string;
+    "--proton-control__interactive-color": string;
+    "--proton-color__primary": string;
+    "--proton-color__primary-light": string;
+    "--proton-color__primary-super-light": string;
+    "--proton-color__secondary": string;
+    "--proton-color__secondary-light": string;
+    "--proton-color__secondary-super-light": string;
+    "--proton-color__danger-super-dark": string;
+    "--proton-color__danger-dark": string;
+    "--proton-color__danger-medium": string;
+    "--proton-color__danger-light": string;
+    "--proton-color__danger-super-light": string;
+    "--proton-color__warning-dark": string;
+    "--proton-color__warning-medium": string;
+    "--proton-color__warning-light": string;
+    "--proton-color__warning-super-light": string;
+    "--proton-color__success-dark": string;
+    "--proton-color__success-medium": string;
+    "--proton-color__success-light": string;
+    "--proton-color__success-super-light": string;
+    "--proton-color__gray-super-dark": string;
+    "--proton-color__gray-dark": string;
+    "--proton-color__gray-medium": string;
+    "--proton-color__gray-medium-light": string;
+    "--proton-color__gray-light": string;
+    "--proton-color__gray-lightest": string;
+    "--proton-color__gray-super-light": string;
+    "--proton-color__white": string;
 }
 
-export declare const Row: <T = object>(props: ProtonRowProps<T>) => JSX.Element;
-
 /**
  * Base Overlay component for creating modal-like backgrounds.
- * @interface ScreenOverlayProps
+ *
+ * API:
+ *  - {@link ScreenOverlayProps}
  */
 export declare const ScreenOverlay: ForwardRefExoticComponent<Omit<ScreenOverlayProps, "ref"> & RefAttributes<HTMLDivElement>>;
 
 declare interface ScreenOverlayProps {
+    /**
+     * Children to render inside the overlay.
+     */
+    children?: React.ReactNode;
     /**
      * Whether to fade in the overlay.
      */
@@ -618,38 +832,43 @@ declare interface ScreenOverlayProps {
      * Ref to the overlay element.
      */
     ref?: React.RefObject<HTMLDivElement>;
-    /**
-     * Children to render inside the overlay.
-     */
-    children?: React.ReactNode;
 }
 
 /**
  * A search input component with optional clear functionality and URL parameter sync.
+ *
+ * API:
+ *  - {@link SearchInputProps}
+ *  - extends {@link BaseInputProps}
  */
 export declare const SearchInput: ({ name, placeholder, autoComplete, isClearable, isDisabled, error, defaultValue, value: controlledValue, "data-testid": testId, onChange, onClear, }: SearchInputProps) => JSX_2.Element;
 
 declare interface SearchInputProps extends Omit<BaseInputProps, "prefix" | "suffix" | "value" | "onChange" | "description" | "descriptionPosition" | "label"> {
+    /** The initial value of the input. */
+    defaultValue?: string;
     /** Should the clear button be shown when there is text? */
     isClearable?: boolean;
     /** Called when the input value changes. */
     onChange?: (value: string) => void;
     /** Called when the clear button is clicked. */
     onClear?: () => void;
-    /** The initial value of the input. */
-    defaultValue?: string;
     /** The current value of the input (for controlled usage) */
     value?: string;
 }
 
-export { Section }
-
 /**
  * A dropdown select menu that opens a popover on desktop and an action menu on mobile.
  * Supports controlled and uncontrolled modes.
+ *
+ * API:
+ *  - {@link SelectProps}
  */
 export declare function Select({ label, name, isDisabled, disabledKeys, selectedKey, onSelectionChange, defaultSelectedKey, onOpen, onClose, items, "data-testid": testId, }: SelectProps): JSX_2.Element;
 
+export declare namespace Select {
+    var displayName: string;
+}
+
 declare interface SelectItem {
     label: string;
     key: string;
@@ -657,36 +876,58 @@ declare interface SelectItem {
 }
 
 declare interface SelectProps {
-    /** The name of the select field */
-    name: string;
-    /** Label to display above the select
-     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#text
-     */
-    label?: string;
-    /** Whether the select is disabled */
-    isDisabled?: boolean;
     /** Array of keys that should be disabled
      * @example ["Thing 1", "Thing 2"]
      */
     disabledKeys?: string[];
-    /** Currently selected key */
-    selectedKey?: string;
-    /** Callback fired when selection changes */
-    onSelectionChange?: (key: string) => void;
     /** The key of the default selected item */
     defaultSelectedKey?: string;
-    /** Callback fired when the menu opens */
-    onOpen?: () => void;
-    /** Callback fired when the menu closes */
-    onClose?: () => void;
+    /** Test ID for the select */
+    "data-testid"?: string;
+    /** Whether the select is disabled */
+    isDisabled?: boolean;
     /** Array of items to display
      * @example [{ key: "thing-1", label: "Thing 1" }, { key: "thing-2", label: "Thing 2" }]
      */
     items: SelectItem[];
-    /** Test ID for the select */
-    "data-testid"?: string;
+    /** Label to display above the select
+     * @external https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#text
+     */
+    label?: string;
+    /** The name of the select field */
+    name: string;
+    /** Callback fired when the menu closes */
+    onClose?: () => void;
+    /** Callback fired when the menu opens */
+    onOpen?: () => void;
+    /** Callback fired when selection changes */
+    onSelectionChange?: (key: string) => void;
+    /** Currently selected key */
+    selectedKey?: string;
 }
 
+export declare type SortDirection = "ASC" | "DESC";
+
+declare type SortingConfig<T> = {
+    /** When sorting is enabled, all these props must be provided together. */
+    sortableColumns: string[];
+    sortedBy: string;
+    sortDirection: SortDirection;
+    onSort: (columnId: string, direction: SortDirection) => void;
+} | {
+    /** When no sorting is needed, none of these props should be provided */
+    sortableColumns?: never;
+    sortedBy?: never;
+    sortDirection?: never;
+    onSort?: never;
+};
+
+/**
+ * A toggle switch component for boolean state control with support for controlled and uncontrolled modes.
+ *
+ * API:
+ *  - {@link SwitchProps}
+ */
 export declare function Switch(props: SwitchProps): JSX_2.Element;
 
 declare interface SwitchProps {
@@ -717,21 +958,118 @@ declare interface SwitchProps {
     children?: React.ReactNode;
 }
 
-export declare function Table(props: TableProps): JSX_2.Element;
+/**
+ * Base Table component that renders data in rows and columns using collections.
+ *
+ * - Built-in keyboard navigation for interactive rows.
+ * - Full ARIA table semantics with proper roles, labels, and indices.
+ *
+ * API:
+ *  - {@link TableProps}
+ *
+ * @example
+ * ```tsx
+ * <Table caption="Employee Directory">
+ *   <Table.Header>
+ *     <Table.Column id="name">Name</Table.Column>
+ *   </Table.Header>
+ *   <Table.Body>
+ *     <Table.Row key="1">
+ *       <Table.Cell>Joe</Table.Cell>
+ *     </Table.Row>
+ *   </Table.Body>
+ * </Table>
+ * ```
+ */
+export declare const Table: (({ children, name }: TableProps) => JSX_2.Element) & {
+    /** Table header: {@link TableHeaderProps} */
+    Header: ({ ...props }: TableHeaderProps) => any;
+    /** Table column: {@link TableColumnProps} */
+    Column: ({ ...props }: TableColumnProps) => any;
+    /** Table body: {@link TableBodyProps} */
+    Body: ({ ...props }: TableBodyProps) => any;
+    /** Table row: {@link TableRowProps} */
+    Row: ({ ...props }: TableRowProps) => any;
+    /** Table cell: {@link TableCellProps} */
+    Cell: ({ ...props }: TableCellProps) => any;
+};
 
-export declare const TableBody: <T = object>(props: ProtonTableBodyProps<T>) => JSX.Element;
+export declare interface TableBodyProps {
+    children: TableRowElement | TableRowElement[];
+}
 
-export { TableHeader }
+declare const TableCell: ({ ...props }: TableCellProps) => any;
 
-declare interface TableProps extends AriaTableProps, TableStateProps<object> {
-    headerProps?: {
-        isHidden?: boolean;
-    };
+export declare type TableCellData = {
+    columnKey: string | number;
+    value: ReactNode;
+    colSpan?: number;
+};
+
+declare type TableCellElement = ReactElement<TableCellProps, typeof TableCell>;
+
+export declare interface TableCellProps {
+    columnKey?: string;
+    children?: ReactNode;
+    colSpan?: number;
+}
+
+export declare type TableCollection = ReturnType<typeof useTableCollection>;
+
+declare const TableColumn: ({ ...props }: TableColumnProps) => any;
+
+export declare type TableColumnData = {
+    key: string | number;
+    header: ReactNode;
+    isHidden?: boolean;
+    ariaSort?: AriaAttributes["aria-sort"];
+};
+
+declare type TableColumnElement = ReactElement<TableColumnProps, typeof TableColumn>;
+
+export declare interface TableColumnProps {
+    id: string;
+    children: ReactNode;
+    "aria-sort"?: AriaAttributes["aria-sort"];
+}
+
+export declare type TableData = {
+    columns: TableColumnData[];
+    rows: TableRowData[];
+};
+
+export declare interface TableHeaderProps {
+    children: TableColumnElement | TableColumnElement[];
+    isHidden?: boolean;
+}
+
+declare interface TableProps {
+    children: [ReactElement<TableHeaderProps>, ReactElement<TableBodyProps>];
+    /** Table name/caption for accessibility. Provides essential context for screen readers about table content. */
+    name: string;
+}
+
+declare const TableRow: ({ ...props }: TableRowProps) => any;
+
+export declare type TableRowData = {
+    key: string | number;
+    cells: TableCellData[];
+    onClick?: () => void;
+};
+
+declare type TableRowElement = ReactElement<TableRowProps, typeof TableRow>;
+
+export declare interface TableRowProps {
+    key?: string | number;
+    children: TableCellElement | TableCellElement[];
+    onClick?: () => void;
 }
 
 /**
  * A component that displays text with an ellipsis when it overflows its container.
- * @interface TextEllipsisProps
+ *
+ * API:
+ *  - {@link TextEllipsisProps}
  */
 export declare const TextEllipsis: ({ children, maxWidth, singleLine, lines, title, "data-testid": testId, }: TextEllipsisProps) => JSX_2.Element;
 
@@ -768,7 +1106,10 @@ declare interface TextEllipsisProps {
 
 /**
  * A component that displays text with emphasis. Provide tooltipProps to wrap the text in a tooltip trigger.
- * @interface TextEmphasisProps
+ *
+ * API:
+ *  - {@link TextEmphasisProps}
+ *  - extends {@link React.HTMLAttributes}
  */
 export declare const TextEmphasis: ({ to, children, tooltipProps, "data-testid": testId, }: TextEmphasisProps) => JSX_2.Element;
 
@@ -796,8 +1137,9 @@ declare type Theme = (typeof THEMES)[keyof typeof THEMES];
 declare interface ThemeContextType {
     theme: Theme;
     className: string;
-    style: ThemeVariables;
-    palette: Palette;
+    style: ProtonStyleSheet;
+    palette: ProtonPalette;
+    hasPalette?: boolean;
 }
 
 export declare const ThemeProvider: default_2.FC<ThemeProviderProps>;
@@ -805,67 +1147,40 @@ export declare const ThemeProvider: default_2.FC<ThemeProviderProps>;
 declare interface ThemeProviderProps {
     theme: Theme;
     children: ReactNode;
-    palette?: Palette;
+    palette?: ProtonPalette;
 }
 
 declare const THEMES: {
     readonly DARK: "dark";
-    readonly CUSTOM_DARK: "custom-dark";
     readonly LIGHT: "light";
 };
 
-declare interface ThemeVariables {
-    "--proton-control__background-color": string;
-    "--proton-control__background-color-light": string;
-    "--proton-control__text-color": string;
-    "--proton-control__border-color": string;
-    "--proton-control__shadow-color": string;
-    "--proton-color__primary": string;
-    "--proton-color__primary-light": string;
-    "--proton-color__primary-super-light": string;
-    "--proton-color__secondary": string;
-    "--proton-control__primary-super-dark": string;
-    "--proton-control__primary-dark": string;
-    "--proton-control__primary-medium": string;
-    "--proton-control__primary-medium-light": string;
-    "--proton-control__primary-light": string;
-    "--proton-control__primary-lightest": string;
-    "--proton-control__primary-super-light": string;
-    "--proton-control__secondary-super-dark": string;
-    "--proton-control__secondary-dark": string;
-    "--proton-control__secondary-medium": string;
-    "--proton-control__secondary-medium-light": string;
-    "--proton-control__secondary-light": string;
-    "--proton-control__secondary-lightest": string;
-    "--proton-control__secondary-super-light": string;
-}
-
 /**
- * A component that displays a loading tombstone. For use as a placeholder while loading content
- * @interface TombstoneProps
+ * A component that displays a loading tombstone. For use as a placeholder while loading content.
+ *
+ * API:
+ *  - {@link TombstoneProps}
  */
 export declare const Tombstone: ({ width, height, borderRadius, }: TombstoneProps) => JSX_2.Element;
 
 declare interface TombstoneProps {
     /**
-     * The width of the tombstone.
-     * @default "100%"
+     * The border radius of the tombstone.
+     * @default "4px"
      */
-    width?: string;
+    borderRadius?: string;
     /**
      * The height of the tombstone.
      * @default "1.5rem"
      */
     height?: string;
     /**
-     * The border radius of the tombstone.
-     * @default "4px"
+     * The width of the tombstone.
+     * @default "100%"
      */
-    borderRadius?: string;
+    width?: string;
 }
 
-export declare function Tooltip({ children, arrow, ...props }: TooltipProps): JSX_2.Element;
-
 export declare interface TooltipProps extends Omit<TooltipProps_2, "children"> {
     children: React.ReactNode;
     arrow?: boolean;
@@ -878,6 +1193,18 @@ export declare interface TooltipProps extends Omit<TooltipProps_2, "children"> {
  *
  * If you wish to disable the trigger click feature, you can set the `disableTriggerClick` prop.
  * This is useful when using an info only Tooltip that might wrap a clickable element.
+ *
+ * API:
+ *  - {@link TooltipTriggerProps}
+ *  - extends {@link TooltipProps}
+ *  - extends {@link TooltipTriggerComponentProps}
+ *
+ * @example
+ * ```tsx
+ <TooltipTrigger content={...} placement="top" arrow isDisabled={disabled}>
+ {children}
+ </TooltipTrigger>
+ * ```
  */
 export declare function TooltipTrigger({ children, delay, closeDelay, isDisabled, defaultOpen, onOpenChange, disableTriggerClick, content, ...tooltipProps }: TooltipTriggerProps): JSX_2.Element;
 
@@ -893,13 +1220,6 @@ export declare interface TooltipTriggerProps extends TooltipProps, TooltipTrigge
     disableTriggerClick?: boolean;
 }
 
-/**
- * A component that displays either a popover menu or an action menu
- * depending on the screen size when the menu trigger is pressed.
- *
- * @param {MenuProps} props - The props for the MenuTrigger component.
- * @returns {JSX.Element} - The MenuTrigger component.
- */
 declare interface TriggerProps {
     disabled?: boolean;
     isOpen?: boolean;
@@ -910,6 +1230,36 @@ declare interface TriggerProps {
 /**
  * Hook for creating a popover trigger. This hook manages the state and events for the popover
  * and popover trigger. For examples see Popover.stories.tsx.
+ *
+ * API:
+ *  - {@link OverlayTriggerProps}
+ *
+ * @example
+ * ```tsx
+ * let { buttonProps, overlayProps, buttonRef, state } = usePopoverTrigger();
+ *
+ * return (
+ *   <div>
+ *     <button {...buttonProps} ref={buttonRef}>
+ *       Trigger
+ *     </button>
+ *
+ *     {state.isOpen && (
+ *       <Popover
+ *         state={state}
+ *         triggerRef={buttonRef}
+ *         arrow={props.arrow}
+ *         offset={props.offset}
+ *         placement={props.placement}
+ *       >
+ *         <Dialog {...overlayProps} title="Popover">
+ *           Here is some popover content
+ *         </Dialog>
+ *       </Popover>
+ *     )}
+ *   </div>
+ * );
+ * ```
  */
 export declare function usePopoverTrigger(props?: OverlayTriggerProps): {
     buttonProps: default_2.ButtonHTMLAttributes<HTMLButtonElement>;
@@ -918,15 +1268,32 @@ export declare function usePopoverTrigger(props?: OverlayTriggerProps): {
     state: OverlayTriggerState;
 };
 
+/**
+ * Hook for managing table data structure and providing navigation methods
+ */
+export declare function useTableCollection(data: TableData): {
+    columns: TableColumnData_2[];
+    rows: TableRowData[];
+    size: number;
+    firstItem: TableRowData;
+    lastItem: TableRowData;
+    isHeaderHidden: boolean;
+    hasVisibleHeader: boolean;
+    getTotalRowCount: number;
+    getRowAriaIndex: (rowIndex: number) => number;
+    getItemByKey: (key: string | number) => TableRowData | null;
+    getItemAfter: (key: string | number) => TableRowData | null;
+    getItemBefore: (key: string | number) => TableRowData | null;
+    getItemIndex: (key: string | number) => number;
+};
+
 export declare const useTheme: () => ThemeContextType;
 
 /**
  * A waveform visualization component that displays audio data with interactive features.
  *
- * @component
- * @interface WaveformProps
- *
- * @returns {JSX.Element} A waveform visualization with optional timestamps and interactive features
+ * API:
+ *  - {@link WaveformProps}
  */
 export declare function Waveform({ data: waveformData, resolution, startDuration, endDuration, currentTime, showTimestamps, totalDuration, disabled, disabledMessage, onClick, "data-testid": testId, }: WaveformProps): JSX_2.Element;
 
@@ -936,6 +1303,14 @@ declare interface WaveformProps {
      * If not provided, uses a sample sine wave.
      */
     data?: number[];
+    /**
+     * Current playback position in seconds.
+     */
+    currentTime?: number;
+    /**
+     * Test ID for testing purposes.
+     */
+    "data-testid"?: string;
     /**
      * Whether the entire waveform is disabled.
      */
@@ -945,42 +1320,29 @@ declare interface WaveformProps {
      */
     disabledMessage?: string;
     /**
-     * Total duration of the audio in seconds.
+     * End time to display until in seconds.
      */
-    totalDuration: number;
+    endDuration?: number;
     /**
-     * Current playback position in seconds.
+     * Click handler that receives the clicked position (0-1) and event.
      */
-    currentTime?: number;
+    onClick?: (position: number, e: React.MouseEvent<HTMLDivElement>) => void;
     /**
      * Width in pixels of each waveform bar.
      */
     resolution?: number;
-    /**
-     * Start time to display from in seconds.
-     */
-    startDuration?: number;
-    /**
-     * End time to display until in seconds.
-     */
-    endDuration?: number;
     /**
      * Whether to show timestamp markers.
      */
     showTimestamps?: boolean;
     /**
-     * Click handler that receives the clicked position (0-1) and event.
+     * Start time to display from in seconds.
      */
-    onClick?: (position: number, e: React.MouseEvent<HTMLDivElement>) => void;
+    startDuration?: number;
     /**
-     * Test ID for testing purposes.
+     * Total duration of the audio in seconds.
      */
-    "data-testid"?: string;
+    totalDuration: number;
 }
 
 export { }
-
-
-declare namespace ButtonGroup {
-    var Option: (props: ButtonGroupOptionProps) => import("react/jsx-runtime").JSX.Element;
-}