@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/Pagination/paginationProvider.tsx

@@ -0,0 +1,234 @@
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+
+export type CurrentPaginationState = Omit<
+    PaginationState,
+    'goToNextPage' | 'goToPage' | 'headInfoUpdateCallback' | 'onPageChange' | 'onPageSizeChange' | 'setPageSize'
+>;
+export type PageSizeOptions = number | 'all';
+
+type CommonValues = {
+    /**
+     * This prop allows you to control how the urls for the links are formatted.
+     *
+     * By default, they're just `?page=PAGE`,
+     * (omitted as necessary)
+     * but you can append to that using this object.
+     *
+     * @see https://developers.google.com/search/docs/specialty/ecommerce/pagination-and-incremental-page-loading#avoid-indexing-variations
+     */
+    extraQueryParams?: Record<string, string>;
+    /**
+     * The path of the current location
+     *
+     * IE if url = example.com/search?page=3
+     * `path` = /search
+     */
+    path: string;
+};
+
+export type PaginationState = CommonValues & {
+    /**
+     * Defacto method of changing pages. Does not route.
+     * See PaginationProvider's `onPageChange` to handle these changes.
+     *
+     * Pagination components use this.
+     *
+     * @param page Page number to go to
+     */
+    goToPage: (page: number) => void;
+    /**
+     * Default page size.
+     */
+    initialPageSize: PageSizeOptions;
+    /**
+     * Passes down the `itemCount` given to PaginationProvider
+     */
+    itemCount: number;
+    /**
+     * This should always be one indexed
+     *
+     * Remember pages are `1` indexed NOT `0` indexed.
+     */
+    page: number;
+    /** The total number of pages */
+    pageCount: number;
+    /** The current page size */
+    pageSize: PageSizeOptions;
+    /** The current page size options. */
+    pageSizeOptions: PageSizeOptions[];
+    /**
+     * Defacto method of changing page size.
+     * See PaginationProvider's `onPageSizeChange` to handle these changes.
+     *
+     * Pagination components use this. (None implemented right now)
+     *
+     * @param page Page number to jump to
+     */
+    setPageSize: (pageSize: PageSizeOptions) => void;
+};
+
+const PaginationContext = createContext<PaginationState>({
+    extraQueryParams: {},
+    goToPage: () => 0,
+    initialPageSize: 24,
+    itemCount: 1,
+    page: 1,
+    pageCount: 1,
+    pageSize: 24,
+    pageSizeOptions: [],
+    path: '',
+    setPageSize: () => 0,
+});
+
+type Props = CommonValues & {
+    children: ReactNode;
+    /** The current page number. This is used if you wish to control the page number externally.*/
+    currentPage?: number;
+    /**
+     * The current page size. Use this to control page size externally (e.g. from URL params).
+     * Mirrors `currentPage` behaviour — when this value changes, the internal `pageSize` state
+     * updates to match without remounting the provider.
+     *
+     * **Note**: `onPageSizeChange` is not fired when `currentPageSize` drives the update. Adjusting currentPage is the user/developer responsibility.
+     */
+    currentPageSize?: PageSizeOptions;
+    /**
+     * Default value for page. Does not affect anything past the first render.
+     *
+     * Remember pages are `1` indexed NOT `0` indexed.
+     */
+    initialPage?: number;
+    /**
+     * Default value for pageSize. Does not affect anything past the first render.
+     */
+    initialPageSize?: PageSizeOptions;
+    /**
+     * The total number of items you're paginating over. This is usually provided by the API.
+     *
+     * Internally, it's only used to determine the number of pages with `Math.ceil(itemCount / pageSize)`
+     */
+    itemCount: number;
+    /**
+     * Callback that runs when something changes page. Useful for updating your API call / routing.
+     *
+     * You can also just listen with the `usePagination` hook.
+     */
+    onPageChange?: (currentPaginationState: CurrentPaginationState) => void;
+    /**
+     * Callback that runs when something changes pageSize. Useful for updating your API call / routing.
+     *
+     * You can also just listen with the `usePagination` hook.
+     */
+    onPageSizeChange?: (currentPaginationState: CurrentPaginationState) => void;
+    /**  */
+    pageSizeOptions?: PageSizeOptions[];
+};
+
+/**
+ * `1` based pagination logic provider
+ */
+export const PaginationProvider = ({
+    children,
+    currentPage,
+    currentPageSize,
+    extraQueryParams,
+    initialPage = 1,
+    initialPageSize = 24,
+    itemCount,
+    onPageChange,
+    onPageSizeChange,
+    pageSizeOptions = [],
+    path,
+}: Props) => {
+    const [page, setPage] = useState<number>(Math.max(initialPage, 1));
+    const [pageSize, _setPageSize] = useState<PageSizeOptions>(initialPageSize);
+
+    const pageCount = useMemo(
+        () => (pageSize === 'all' ? 1 : Math.max(Math.ceil(itemCount / pageSize), 1)),
+        [itemCount, pageSize]
+    );
+
+    const dataValues = useMemo(
+        () => ({
+            extraQueryParams,
+            initialPageSize,
+            itemCount,
+            page,
+            pageCount,
+            pageSize,
+            pageSizeOptions,
+            path,
+        }),
+        [extraQueryParams, initialPageSize, itemCount, page, pageCount, pageSize, path, pageSizeOptions]
+    );
+
+    // If page is changed externally, update the page number to reflect the current page inside the component
+    // This will changed the component to be more controlled.
+    useEffect(() => {
+        if (currentPage && currentPage !== page) {
+            setPage(currentPage);
+        }
+    }, [currentPage, page]);
+
+    useEffect(() => {
+        if (currentPageSize !== undefined && currentPageSize !== pageSize) {
+            _setPageSize(currentPageSize);
+        }
+    }, [currentPageSize, pageSize]);
+
+    const goToPage = useCallback(
+        (newPage: number) => {
+            setPage(newPage);
+            onPageChange?.({ ...dataValues, page: newPage });
+        },
+        [dataValues, onPageChange]
+    );
+
+    const setPageSize = useCallback(
+        (newPageSize: PageSizeOptions) => {
+            _setPageSize(newPageSize);
+
+            // Set page to highest possible page if we're on a page that's too high
+            if (newPageSize === 'all') {
+                setPage(1);
+            } else {
+                // Make sure page is least 1 since we're doing 1 indexed.
+                const newPageCount = Math.max(Math.ceil(itemCount / newPageSize), 1);
+
+                if (page > newPageCount) {
+                    setPage(newPageCount);
+                }
+            }
+
+            onPageSizeChange?.({ ...dataValues, pageSize: newPageSize });
+        },
+        [dataValues, itemCount, onPageSizeChange, page]
+    );
+
+    const value: PaginationState = useMemo(
+        () => ({
+            ...dataValues,
+            goToPage,
+            setPageSize,
+        }),
+        [dataValues, goToPage, setPageSize]
+    );
+
+    return <PaginationContext.Provider value={value}>{children}</PaginationContext.Provider>;
+};
+
+/**
+ * Provides access to all these values
+ * ```tsx
+ * goToPage: (page: number) => void;
+ * initialPageSize: PageSizeOptions; // number | 'all'
+ * items: number;
+ * page: number;
+ * pageCount: number;
+ * pageSize: PageSizeOptions; // number | 'all'
+ * setPageSize: (pageSize: PageSizeOptions) => void;
+ * ```
+ *
+ * @see https://developers.google.com/search/docs/specialty/ecommerce/pagination-and-incremental-page-loading
+ */
+export const usePagination = () => useContext(PaginationContext);

package/src/Pagination/utils.tsx

@@ -0,0 +1,36 @@
+import { cloneDeep, merge } from 'es-toolkit';
+import { useCallback } from 'react';
+
+import { CurrentPaginationState, usePagination } from './paginationProvider';
+
+export const usePaginationQueryParams = () => {
+    const currentPaginationState = usePagination();
+
+    const buildQueryParams = useCallback(
+        (newState: Partial<CurrentPaginationState>): string => {
+            const { extraQueryParams, page, path } = merge(cloneDeep(currentPaginationState), newState);
+
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- hammer-parity: params values are stringified below regardless of source type
+            const params: Record<string, any> = {
+                ...extraQueryParams,
+            };
+
+            if (page !== 1) {
+                params.page = page;
+            }
+
+            if (Object.keys(params).length === 0) {
+                return path;
+            }
+
+            const cleanedParams = Object.fromEntries(
+                Object.entries(params).map(([key, value]) => [key, value.toString()])
+            );
+
+            return `${path.startsWith('/') ? '' : '/'}${path}?${new URLSearchParams(cleanedParams).toString()}`;
+        },
+        [currentPaginationState]
+    );
+
+    return buildQueryParams;
+};