@ssa-ui-kit/core 3.16.2 → 3.16.3

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

package/dist/index.js

@@ -54353,10 +54353,47 @@ const ROWS_PER_PAGE_LIST = [{
 }];
 const DEFAULT_SELECTED_INDEX = 1;
 const DEFAULT_PER_PAGE_VALUE = ROWS_PER_PAGE_LIST[DEFAULT_SELECTED_INDEX].value;
+;// ./src/components/Pagination/hooks/useControllableState.ts
+
+/**
+ * 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
+ */
+const useControllableState = ({
+  value: controlledValue,
+  defaultValue,
+  onChange,
+  name = 'value'
+}) => {
+  const [uncontrolledValue, setUncontrolledValue] = (0,external_react_namespaceObject.useState)(defaultValue);
+  const isControlled = controlledValue !== undefined;
+  const value = isControlled ? controlledValue : uncontrolledValue;
+  const isControlledRef = (0,external_react_namespaceObject.useRef)(isControlled);
+  if (false) // removed by dead control flow
+{}
+  isControlledRef.current = isControlled;
+  const setValue = (0,external_react_namespaceObject.useCallback)(next => {
+    const resolved = typeof next === 'function' ? next(value) : next;
+    if (!isControlled) {
+      setUncontrolledValue(resolved);
+    }
+    onChange?.(resolved);
+  }, [isControlled, onChange, value]);
+  return [value, setValue];
+};
 ;// ./src/components/Pagination/PaginationContext.tsx
 
 
 
+
 /**
  * Pagination context
  * Provides page state and navigation functions to child components
@@ -54384,21 +54421,53 @@ const usePaginationContext = () => (0,external_react_namespaceObject.useContext)
  *
  * @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
  */
 const PaginationContextProvider = ({
   selectedPage,
   defaultPerPage = DEFAULT_PER_PAGE_VALUE,
+  page: controlledPage,
+  perPage: controlledPerPage,
+  onPageChange,
+  onPerPageChange,
   children
 }) => {
-  const [perPage, setPerPage] = (0,external_react_namespaceObject.useState)(defaultPerPage);
-  const [page, setPage] = (0,external_react_namespaceObject.useState)(selectedPage);
+  // `page` can be `undefined` (no page selected yet), but the public
+  // `onPageChange` callback only ever needs to handle real page numbers -
+  // Pagination never navigates to an undefined page.
+  const handlePageChange = (0,external_react_namespaceObject.useCallback)(value => {
+    if (value !== undefined) {
+      onPageChange?.(value);
+    }
+  }, [onPageChange]);
+  const [page, setPage] = useControllableState({
+    value: controlledPage,
+    defaultValue: selectedPage,
+    onChange: handlePageChange,
+    name: 'page'
+  });
+  const [perPage, setPerPage] = useControllableState({
+    value: controlledPerPage,
+    defaultValue: defaultPerPage,
+    onChange: onPerPageChange,
+    name: 'perPage'
+  });
   return (0,jsx_runtime_namespaceObject.jsx)(PaginationContext.Provider, {
     value: {
       page,
@@ -54461,7 +54530,7 @@ const PaginationContextProvider = ({
  */
 
 const RowsPerPageDropdown = ({
-  selectedItem = DEFAULT_PER_PAGE_VALUE,
+  selectedItem,
   rowsPerPageList = ROWS_PER_PAGE_LIST,
   rowsPerPageText = 'Rows per page',
   dropdownPosition,
@@ -54469,11 +54538,12 @@ const RowsPerPageDropdown = ({
 }) => {
   const theme = (0,react_namespaceObject.useTheme)();
   const {
+    perPage,
     setPerPage
   } = usePaginationContext();
   const selectedItemForDropdown = rowsPerPageList.find(({
     value
-  }) => value === selectedItem) || rowsPerPageList[0];
+  }) => value === (selectedItem ?? perPage)) || rowsPerPageList[0];
   const onChange = ({
     value
   }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssa-ui-kit/core",
-  "version": "3.16.2",
+  "version": "3.16.3",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -39,8 +39,8 @@
     "luxon": "3.5.0",
     "plotly.js": "3.0.0",
     "react-plotly.js": "2.6.0",
-    "@ssa-ui-kit/utils": "^3.16.2",
-    "@ssa-ui-kit/hooks": "^3.16.2"
+    "@ssa-ui-kit/hooks": "^3.16.3",
+    "@ssa-ui-kit/utils": "^3.16.3"
   },
   "devDependencies": {
     "@emotion/css": "11.13.5",