@ssa-ui-kit/core 3.16.1 → 3.16.3

package/dist/components/DatePicker/components/ClearButton.d.ts

@@ -0,0 +1,9 @@
+import { Interpolation, Theme } from '@emotion/react';
+export type ClearButtonProps = {
+    onClick: () => void;
+    ariaLabel: string;
+    dataTestId: string;
+    className?: string;
+    css?: Interpolation<Theme>;
+};
+export declare const ClearButton: ({ onClick, ariaLabel, dataTestId, className, css: cssProp, }: ClearButtonProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/DatePicker/components/DatePickerTimePanel.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hours and minutes columns shown beside the calendar when `showTimePicker`
+ * is set, matching the Figma `Day & Time Picker` pop-up.
+ *
+ * The hours and minutes columns scroll independently, so reaching a late hour
+ * doesn't drag the minutes list out of view. Each is centred on its own
+ * selected value when the popover opens.
+ */
+export declare const DatePickerTimePanel: () => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/DatePicker/components/index.d.ts

@@ -1,8 +1,10 @@
+export * from './ClearButton';
 export * from './DatePickerTrigger';
 export * from './DatePickerCalendar';
 export * from './DatePickerContent';
 export * from './DatePickerMonthsSwitch';
 export * from './DatePickerHeader';
+export * from './DatePickerTimePanel';
 export * from './DaysView';
 export * from './MonthsView';
 export * from './YearsView';

package/dist/components/DatePicker/constants.d.ts

@@ -17,6 +17,19 @@ export declare const INVALID_DATE = "Invalid date";
 export declare const FULL_DATE_LENGTH = 10;
 export declare const FULL_MONTH_DATE_LENGTH = 7;
 export declare const FULL_YEAR_DATE_LENGTH = 4;
+/**
+ * Time support is layered on top of a date format rather than being a separate
+ * set of formats, so `showTimePicker` works with any picker type without
+ * widening the shared `DateFormat` union (which `JsonSchemaForm` validates
+ * against).
+ */
+export declare const TIME_MASK_FORMAT_SUFFIX = " HH:mm";
+export declare const TIME_MASK_SUFFIX = " __:__";
+export declare const TIME_LENGTH = 6;
+export declare const HOURS_IN_DAY = 24;
+export declare const MINUTES_IN_HOUR = 60;
+/** 15-minute steps by default; pass `minuteStep={1}` for the Figma-literal list. */
+export declare const DEFAULT_MINUTE_STEP = 15;
 export declare const PICKER_TYPE: {
     readonly DAYS: "days";
     readonly MONTHS: "months";

package/dist/components/DatePicker/hooks/useDatePicker.d.ts

@@ -1,7 +1,7 @@
 import { DateTime } from 'luxon';
 import { DatePickerProps } from '../types';
-export declare const useDatePicker: ({ dateMin, dateMax, name, defaultValue, format: propFormat, maskOptions, pickerType, onOpen, onClose, onError, onChange, value: externalValue, }: DatePickerProps) => {
-    format: import("../../JsonSchemaForm/utils").DateFormat;
+export declare const useDatePicker: ({ dateMin, dateMax, name, defaultValue, format: propFormat, maskOptions, pickerType, onOpen, onClose, onError, onChange, value: externalValue, showTimePicker, }: DatePickerProps) => {
+    format: string;
     formatIndexes: {
         day: number;
         month: number;
@@ -13,7 +13,14 @@ export declare const useDatePicker: ({ dateMin, dateMax, name, defaultValue, for
     dateMaxDT: DateTime<true> | DateTime<false>;
     dateTime: DateTime<boolean> | undefined;
     isOpen: boolean;
+    isDirty: boolean;
     inputValue: any;
+    resetToDefault: () => void;
+    setTime: ({ hour, minute }: {
+        hour?: number;
+        minute?: number;
+    }) => void;
+    showTimePicker: boolean;
     calendarViewDateTime: DateTime<boolean> | undefined;
     maskInputRef: import("react").MutableRefObject<HTMLInputElement>;
     calendarType: import("../../JsonSchemaForm/utils").PickerCalendarType;

package/dist/components/DatePicker/styles.d.ts

@@ -1,3 +1,51 @@
+/**
+ * Which edge of a highlighted range a cell sits on. Drives the cell's corner
+ * rounding so start/end cells form a single connected pill with the range
+ * cells between them, matching the Figma `Range Selected Start/End` variants.
+ *
+ * - **`start`** — rounded on the left only
+ * - **`end`** — rounded on the right only
+ * - **`both`** — a standalone selection (or a one-cell range), fully rounded
+ */
+export type RangeEdge = 'start' | 'end' | 'both';
+export declare const getCellRadius: (rangeEdge: RangeEdge | undefined, isHighlighted: boolean) => "6px" | "6px 0 0 6px" | "0 6px 6px 0" | "0";
+/**
+ * Works out which edge of a highlighted range a selected cell sits on.
+ *
+ * A range only has distinct edges when both anchors exist, so without an
+ * active range (or when both anchors land on the same cell) the cell is
+ * fully rounded. `mode` says which anchor *this* picker holds, which is what
+ * decides whether its own value rounds on the left or the right.
+ */
+export declare const getRangeEdge: ({ isFirstSelected, isSecondSelected, isRangeActive, mode, }: {
+    isFirstSelected: boolean;
+    isSecondSelected: boolean;
+    isRangeActive: boolean;
+    mode?: "dateFrom" | "dateTo";
+}) => RangeEdge | undefined;
+/**
+ * Time panel shown beside the calendar. Figma lays the hours and minutes out
+ * as rows of two 56×40 cells with an 8px gap; two scrolling columns in one
+ * scroll container produce the same result while keeping the lists independent.
+ */
+export declare const TimePanel: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Each column scrolls on its own so the hours list can be moved without
+ * dragging the minutes along with it.
+ */
+export declare const TimeColumn: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const TimeCell: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    isSelected: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const DaysViewCell: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;
@@ -13,25 +61,22 @@ export declare const DaysViewCell: import("@emotion/styled").StyledComponent<{
 } & {
     isCalendarDateNow: boolean;
     isCalendarDateSelected: boolean;
-    isCalendarFirstDateSelected?: boolean;
-    isCalendarSecondDateSelected?: boolean;
     isHighlighted: boolean;
+    rangeEdge?: RangeEdge;
 }, {}, {}>;
 export declare const YearsViewCell: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;
 } & {
-    isCalendarYear: boolean;
-    isCalendarFirstDateSelected?: boolean;
-    isCalendarSecondDateSelected?: boolean;
+    isCalendarDateSelected: boolean;
     isHighlighted: boolean;
+    rangeEdge?: RangeEdge;
 }, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const MonthsViewCell: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;
 } & {
-    isCalendarMonth: boolean;
-    isCalendarFirstDateSelected?: boolean;
-    isCalendarSecondDateSelected?: boolean;
+    isCalendarDateSelected: boolean;
     isHighlighted: boolean;
+    rangeEdge?: RangeEdge;
 }, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

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

@@ -13,6 +13,9 @@ import type { PickerCalendarType, DateFormat } from '../JsonSchemaForm/utils/dat
  * - **`days`** — `mm/dd/yyyy` (or `dd/mm/yyyy`), day-level selection
  * - **`months`** — `mm/yyyy`, month-level selection
  * - **`years`** — `yyyy`, year-level selection
+ *
+ * With **`showTimePicker`** the granularity drops to `startOf('minute')` instead, so the
+ * selected hours and minutes survive on the emitted **`Date`**.
  */
 export type PickerType = (typeof PICKER_TYPE)[keyof typeof PICKER_TYPE];
 /**
@@ -22,6 +25,9 @@ export type PickerType = (typeof PICKER_TYPE)[keyof typeof PICKER_TYPE];
  * - **`mm/dd/yyyy`** | **`dd/mm/yyyy`** — day pickers
  * - **`mm/yyyy`** — month picker
  * - **`yyyy`** — year picker
+ *
+ * Always date-only: **`showTimePicker`** appends **` HH:mm`** internally rather than being
+ * spelled out here, so this union stays compatible with **`JsonSchemaForm`** validation.
  */
 export type DatePickerFormat = DateFormat;
 /**
@@ -127,11 +133,41 @@ export interface DatePickerProps {
      * Helper text below the field (shown with validation message when present).
      */
     helperText?: string;
+    /**
+     * Renders the field in its **success** state (green border and helper text).
+     * A validation error always wins, so a field with an error is never shown
+     * as successful.
+     * @default false
+     */
+    success?: boolean;
     /**
      * Whether the trailing calendar icon button is shown.
      * @default true
      */
     showCalendarIcon?: boolean;
+    /**
+     * Adds an hours/minutes panel beside the calendar and appends **`HH:mm`** to
+     * the field's format and mask. The emitted **`Date`** keeps its time instead
+     * of being floored to the start of the day.
+     *
+     * Selecting a day no longer closes the popover when this is on — otherwise
+     * the time panel would be unreachable. The popover closes on outside click.
+     * @default false
+     */
+    showTimePicker?: boolean;
+    /**
+     * Increment between selectable minutes, in minutes. Must divide 60.
+     * Use **`1`** to match the design's full 0–59 list.
+     * @default 15
+     */
+    minuteStep?: number;
+    /**
+     * Whether the trailing **clear** (×) button is shown. It appears only while
+     * the field differs from **`defaultValue`**, and restores that value when
+     * clicked — so with no **`defaultValue`** it simply empties the field.
+     * @default false
+     */
+    showClearButton?: boolean;
     /**
      * Last **Date** emitted from **onChange**; used with **`highlightDates`** for range styling
      * in the calendar (e.g. paired with another picker’s value).
@@ -162,6 +198,7 @@ export interface DatePickerProps {
         trigger?: {
             input?: string;
             calendarIcon?: string;
+            clearButton?: string;
         };
         monthsSwitch?: {
             wrapper?: string;
@@ -172,8 +209,9 @@ export interface DatePickerProps {
         label?: string;
     };
     /**
-     * Called with the selected **`Date`** (Luxon-normalized to start of day/month/year), or
-     * **undefined** when the field is cleared or invalid.
+     * Called with the selected **`Date`** (Luxon-normalized to start of day/month/year — or to
+     * the start of the **minute** when **`showTimePicker`** is set), or **undefined** when the
+     * field is cleared or invalid.
      */
     onChange?: (date?: Date) => void;
     /**
@@ -214,7 +252,20 @@ export interface DatePickerProps {
  * Most consumers should use **DatePicker** only; this type documents hooks and subcomponents
  * that read context.
  */
-export interface DatePickerContextProps extends Omit<DatePickerProps, 'dateMin' | 'dateMax'> {
+export interface DatePickerContextProps extends Omit<DatePickerProps, 'dateMin' | 'dateMax' | 'format'> {
+    /**
+     * Resolved display format. Unlike the **`format`** prop this may carry a
+     * **` HH:mm`** suffix when **`showTimePicker`** is set, so it is a plain
+     * string rather than the date-only **`DatePickerFormat`** union.
+     */
+    format: string;
+    /**
+     * Commits an hour and/or minute onto the selected date, preserving the day.
+     */
+    setTime?: (time: {
+        hour?: number;
+        minute?: number;
+    }) => void;
     /**
      * Ref applied to the masked **input** (merged: mask ref + forwarded ref from **DatePicker**).
      */
@@ -223,6 +274,16 @@ export interface DatePickerContextProps extends Omit<DatePickerProps, 'dateMin'
      * Whether the calendar popover is open.
      */
     isOpen: boolean;
+    /**
+     * Whether the current value differs from **`defaultValue`**. Drives the
+     * clear button's visibility.
+     */
+    isDirty?: boolean;
+    /**
+     * Restores **`defaultValue`** (or empties the field when there isn't one),
+     * clearing any validation error and emitting **`onChange`**.
+     */
+    resetToDefault?: () => void;
     /**
      * Active calendar surface: days grid, months, or years.
      */

package/dist/components/DateRangePicker/components/DatesListWrapper.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Wraps the date grid and styles the "range you are about to pick" preview
+ * band that appears between a selected anchor and the currently hovered cell.
+ *
+ * The band is a translucent fill with a hairline top/bottom rule, capped with
+ * a rounded corner at each end — so which cell is the left cap and which is
+ * the right depends on the direction being previewed:
+ *
+ * - **`hover-range-from`** — hovering *before* the start anchor, so the
+ *   hovered cell is the left cap and the selected anchor is the right.
+ * - **`hover-range-to`** — hovering *after* the end anchor, so the selected
+ *   anchor is the left cap and the hovered cell is the right.
+ */
 export declare const DatesListWrapper: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;

package/dist/components/DateRangePicker/hooks/useDateRangePicker.d.ts

@@ -27,6 +27,8 @@ export declare const useDateRangePicker: ({ dateMin, dateMax, name: _name, forma
     currentIndex: number;
     currentCalendarViewDT: DateTime;
     isOpen: boolean;
+    isDirty: boolean;
+    resetToDefault: () => void;
     status?: "error" | "success" | "basic";
     inputFromRef: ReturnType<typeof useMergeRefs<HTMLInputElement | null>>;
     inputToRef: ReturnType<typeof useMergeRefs<HTMLInputElement | null>>;

package/dist/components/DateRangePicker/hooks/useRangeSelection.d.ts

@@ -16,5 +16,6 @@ export declare const useRangeSelection: ({ createNewDate, getComparisonFormat, }
         isCalendarSecondDateSelected: boolean;
         isCalendarDateSelected: boolean;
     };
+    isRangeActive: boolean;
 };
 export {};

package/dist/components/DateRangePicker/styles.d.ts

@@ -1,39 +1,4 @@
-export declare const DaysViewCell: import("@emotion/styled").StyledComponent<{
-    theme?: import("@emotion/react").Theme;
-    as?: React.ElementType;
-} & {
-    direction?: import("../Wrapper").WrapperDirection;
-    alignItems?: import("../Wrapper").WrapperAlignItems;
-    justifyContent?: import("../Wrapper").WrapperJustifyContent;
-    fade?: boolean;
-    fadeDelay?: number;
-    isVisible?: boolean;
-} & import("../..").CommonProps & import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & {
-    theme?: import("@emotion/react").Theme;
-} & {
-    isCalendarDateNow: boolean;
-    isCalendarDateSelected: boolean;
-    isCalendarFirstDateSelected?: boolean;
-    isCalendarSecondDateSelected?: boolean;
-    isHighlighted: boolean;
-}, {}, {}>;
-export declare const YearsViewCell: import("@emotion/styled").StyledComponent<{
-    theme?: import("@emotion/react").Theme;
-    as?: React.ElementType;
-} & {
-    isCalendarYear: boolean;
-    isCalendarFirstDateSelected?: boolean;
-    isCalendarSecondDateSelected?: boolean;
-    isHighlighted: boolean;
-}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
-export declare const MonthsViewCell: import("@emotion/styled").StyledComponent<{
-    theme?: import("@emotion/react").Theme;
-    as?: React.ElementType;
-} & {
-    isCalendarFirstDateSelected?: boolean;
-    isCalendarSecondDateSelected?: boolean;
-    isHighlighted: boolean;
-}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export { DaysViewCell, YearsViewCell, MonthsViewCell, getCellRadius, getRangeEdge, type RangeEdge, } from '../DatePicker/styles';
 export declare const TriggerWrapper: import("@emotion/styled").StyledComponent<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;

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

@@ -124,6 +124,14 @@ export interface DateRangePickerProps {
      * @default true
      */
     showCalendarIcon?: boolean;
+    /**
+     * Shows the trailing **clear** (×) button. It appears only while either
+     * field differs from **`defaultValue`**, and restores the whole range to
+     * that default when clicked — so with no **`defaultValue`** it empties both
+     * fields.
+     * @default false
+     */
+    showClearButton?: boolean;
     /**
      * **days** | **months** | **years** — drives default **format**, mask, and calendar chrome.
      * @default 'days'
@@ -148,6 +156,7 @@ export interface DateRangePickerProps {
             inputTo?: string;
             arrowIcon?: string;
             calendarIcon?: string;
+            clearButton?: string;
         };
         calendar?: string;
         label?: string;
@@ -211,6 +220,16 @@ export interface DateRangePickerContextProps extends Omit<DateRangePickerProps,
      * Whether the calendar popover is open.
      */
     isOpen: boolean;
+    /**
+     * Whether either field differs from **`defaultValue`**. Drives the clear
+     * button's visibility.
+     */
+    isDirty?: boolean;
+    /**
+     * Restores the whole range to **`defaultValue`** (or empties both fields
+     * when there isn't one) and emits **`onChange`**.
+     */
+    resetToDefault?: () => void;
     /**
      * **Luxon** date for the calendar header / navigation (current visible month or year).
      */

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

@@ -94,5 +94,5 @@ import { DropdownProps } from './types';
  *
  * @see https://www.w3.org/WAI/ARIA/apg/example-index/combobox/combobox-select-only.html
  */
-declare const Dropdown: <T extends DropdownOptionProps>({ selectedItem, isDisabled, isOpen: isInitOpen, children, onChange: handleChange, className, placeholder, maxHeight, avatarBorder, dropdownProps: componentProps, }: DropdownProps<T>) => import("@emotion/react/jsx-runtime").JSX.Element;
+declare const Dropdown: <T extends DropdownOptionProps>({ selectedItem, isDisabled, isOpen: isInitOpen, children, onChange: handleChange, className, placeholder, maxHeight, avatarBorder, label, helperText, errors, success, icon, dropdownProps: componentProps, }: DropdownProps<T>) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Dropdown;

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

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { FieldError } from 'react-hook-form';
 import { Interpolation, Theme } from '@emotion/react';
 import { DropdownOptionProps } from '../DropdownOptions';
 import { CommonProps } from '../../types/emotion';
@@ -99,6 +100,31 @@ export interface DropdownProps<P extends DropdownOptionProps> extends CommonProp
      * @default false
      */
     avatarBorder?: boolean;
+    /**
+     * Label text displayed above the dropdown
+     */
+    label?: string;
+    /**
+     * Helper text displayed below the dropdown
+     * Shown when no errors are present
+     */
+    helperText?: string;
+    /**
+     * React Hook Form field error object
+     * Used to display validation error messages
+     */
+    errors?: FieldError;
+    /**
+     * Whether to display success state styling
+     * When true, status is set to 'success'
+     * @default false
+     */
+    success?: boolean;
+    /**
+     * Leading icon shown in the toggle button when no selected item avatar is present.
+     * Ignored once an item with an `avatar` is selected — the avatar always takes priority.
+     */
+    icon?: IconProps['name'];
     /**
      * Props object for sub-components
      * Allows fine-grained control over component parts

package/dist/components/DropdownToggle/DropdownToggle.d.ts

@@ -3,6 +3,6 @@ import { DropdownToggleProps } from './types';
 export declare const DropdownToggleBase: import("@emotion/styled").StyledComponent<{
     theme?: Theme;
     as?: React.ElementType;
-} & Pick<DropdownToggleProps, "colors" | "disabled" | "isOpen" | "isMultiple" | "selectedCount">, import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {}>;
-declare const DropdownToggle: ({ onClick, onFocus, isOpen, isMultiple, selectedCount, disabled, children, ariaLabelledby, ariaControls, colors, className, ...restProps }: DropdownToggleProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+} & Pick<DropdownToggleProps, "colors" | "disabled" | "status" | "isOpen" | "isMultiple" | "selectedCount">, import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {}>;
+declare const DropdownToggle: ({ onClick, onFocus, isOpen, isMultiple, selectedCount, disabled, children, ariaLabelledby, ariaControls, colors, status, className, ...restProps }: DropdownToggleProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default DropdownToggle;

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

@@ -16,6 +16,7 @@ export interface DropdownToggleProps extends CommonProps, Omit<React.ButtonHTMLA
     colors?: Array<string | undefined>;
     className?: string;
     selectedCount?: number;
+    status?: 'basic' | 'error' | 'success';
 }
 export interface MultipleStylesProps {
     theme: Theme;

package/dist/components/Pagination/PaginationContext.d.ts

@@ -23,12 +23,22 @@ export declare const usePaginationContext: () => PaginationContextProps;
  *
  * @example
  * ```tsx
+ * // Uncontrolled
  * <PaginationContextProvider selectedPage={1} defaultPerPage={25}>
  *   <Pagination pagesCount={10} />
  * </PaginationContextProvider>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Controlled - parent owns page/perPage state
+ * const [page, setPage] = useState(1);
+ * <PaginationContextProvider page={page} onPageChange={setPage}>
+ *   <Pagination pagesCount={10} />
+ * </PaginationContextProvider>
+ * ```
+ *
  * @see {@link Pagination} - Child component that uses this context
  * @see {@link usePaginationContext} - Hook to access context values
  */
-export declare const PaginationContextProvider: ({ selectedPage, defaultPerPage, children, }: PaginationContextProviderProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const PaginationContextProvider: ({ selectedPage, defaultPerPage, page: controlledPage, perPage: controlledPerPage, onPageChange, onPerPageChange, children, }: PaginationContextProviderProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/components/Pagination/components/RowsPerPageDropdown/types.d.ts

@@ -30,6 +30,7 @@ export interface RowsPerPageDropdownProps extends CommonProps {
     /**
      * Currently selected number of rows per page
      * Must match a value in rowsPerPageList
+     * @default the `perPage` value from PaginationContextProvider
      */
     selectedItem?: number;
     /**

package/dist/components/Pagination/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from './useControllableState';

package/dist/components/Pagination/hooks/useControllableState.d.ts

@@ -0,0 +1,37 @@
+import { Dispatch, SetStateAction } from 'react';
+interface UseControllableStateProps<T> {
+    /**
+     * Controlled value. When provided (not `undefined`), the hook always
+     * reflects this value and never writes to its own internal state.
+     */
+    value?: T;
+    /**
+     * Initial value used for internal state when `value` is `undefined`
+     * (uncontrolled mode).
+     */
+    defaultValue: T;
+    /**
+     * Called with the next value whenever the setter is invoked, whether
+     * controlled or uncontrolled.
+     */
+    onChange?: (value: T) => void;
+    /**
+     * Name used in the dev-mode warning when a component switches between
+     * controlled and uncontrolled across renders.
+     */
+    name?: string;
+}
+/**
+ * useControllableState - Backs a value that can be either controlled by a
+ * parent (via `value`/`onChange`) or managed internally (via `defaultValue`).
+ *
+ * Mirrors the standard React controlled/uncontrolled input pattern: passing
+ * `value` opts into controlled mode, where the returned value always matches
+ * the prop and the setter only calls `onChange` (no internal state is
+ * written). Omitting `value` falls back to internal state seeded from
+ * `defaultValue`.
+ *
+ * @internal
+ */
+export declare const useControllableState: <T>({ value: controlledValue, defaultValue, onChange, name, }: UseControllableStateProps<T>) => [T, Dispatch<SetStateAction<T>>];
+export {};

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

@@ -210,21 +210,59 @@ export interface PaginationContextProps {
  *
  * @example
  * ```tsx
+ * // Uncontrolled - provider manages its own state
  * <PaginationContextProvider selectedPage={1} defaultPerPage={25}>
  *   <Pagination pagesCount={10} />
  * </PaginationContextProvider>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled - parent owns page/perPage state
+ * const [page, setPage] = useState(1);
+ * <PaginationContextProvider page={page} onPageChange={setPage}>
+ *   <Pagination pagesCount={10} />
+ * </PaginationContextProvider>
+ * ```
  */
 export interface PaginationContextProviderProps {
     /**
      * Initial selected page number (1-indexed)
+     * Ignored once `page` is provided (controlled mode)
      */
     selectedPage?: number;
     /**
      * Default number of items per page
+     * Ignored once `perPage` is provided (controlled mode)
      * @default 10
      */
     defaultPerPage?: number;
+    /**
+     * Controlled current page number (1-indexed)
+     * When provided, the provider stops managing page state internally and
+     * always reflects this value; pair with `onPageChange` to react to
+     * navigation.
+     */
+    page?: number;
+    /**
+     * Controlled number of items per page
+     * When provided, the provider stops managing perPage state internally and
+     * always reflects this value; pair with `onPerPageChange` to react to
+     * changes.
+     */
+    perPage?: number;
+    /**
+     * Called whenever the page changes (arrow clicks, page buttons, manual
+     * page input). Required to actually change the page when `page` is
+     * controlled, since the provider no longer updates its own state.
+     */
+    onPageChange?: (page: number) => void;
+    /**
+     * Called whenever perPage changes (rows per page dropdown). Required to
+     * actually change perPage when `perPage` is controlled, since the
+     * provider no longer updates its own state.
+     */
+    onPerPageChange?: (perPage: number) => void;
     /**
      * Child components that use pagination context
      * Must include Pagination component