@strato-admin/core 0.1.1 → 0.3.0

package/dist/ra-core/src/controller/usePaginationState.d.ts

@@ -0,0 +1,33 @@
+import { PaginationPayload } from '../types';
+/**
+ * @typedef PaginationProps
+ * @type {Object}
+ * @property {number} page: The page number.
+ * @property {number} perPage: The number of item per page.
+ * @property {Function} setPage: Set the page number
+ * @property {Function} setPerPage: Set the per page number
+ * @property {Function} setPagination: Set page and perPage pagination numbers
+ */
+export interface PaginationHookResult {
+    page: number;
+    perPage: number;
+    pagination: PaginationPayload;
+    setPage: (page: number) => void;
+    setPerPage: (perPage: number) => void;
+    setPagination: (pagination: PaginationPayload) => void;
+}
+/**
+ * Hooks to provide pagination state (page and perPage)
+ *
+ * @example
+ *
+ * const { page, setPage, perPage, setPerPage } = usePagination(initialPerPage);
+ *
+ * @param {number} initialPagination the initial value per page
+ * @returns {PaginationHookResult} The pagination props
+ */
+declare const _default: (initialPagination?: {
+    perPage?: number;
+    page?: number;
+}) => PaginationHookResult;
+export default _default;

package/dist/ra-core/src/controller/usePaginationState.js

@@ -0,0 +1,45 @@
+import { useEffect, useReducer, useCallback, useRef } from 'react';
+const paginationReducer = (prevState, nextState) => {
+    return {
+        ...prevState,
+        ...nextState,
+    };
+};
+const defaultPagination = {
+    page: 1,
+    perPage: 25,
+};
+/**
+ * Hooks to provide pagination state (page and perPage)
+ *
+ * @example
+ *
+ * const { page, setPage, perPage, setPerPage } = usePagination(initialPerPage);
+ *
+ * @param {number} initialPagination the initial value per page
+ * @returns {PaginationHookResult} The pagination props
+ */
+export default (initialPagination = {}) => {
+    const [pagination, setPagination] = useReducer(paginationReducer, {
+        ...defaultPagination,
+        ...initialPagination,
+    });
+    const isFirstRender = useRef(true);
+    const setPerPage = useCallback(perPage => setPagination({ perPage, page: 1 }), []);
+    const setPage = useCallback(page => setPagination({ page }), []);
+    useEffect(() => {
+        if (isFirstRender.current) {
+            isFirstRender.current = false;
+            return;
+        }
+        setPerPage(initialPagination.perPage || 25);
+    }, [initialPagination.perPage, setPerPage]);
+    return {
+        page: pagination.page,
+        perPage: pagination.perPage,
+        pagination,
+        setPage,
+        setPerPage,
+        setPagination,
+    };
+};

package/dist/ra-core/src/controller/usePrevNextController.d.ts

@@ -0,0 +1,127 @@
+import { UseQueryOptions } from '@tanstack/react-query';
+import { FilterPayload, RaRecord, SortPayload } from '../types';
+/**
+ * A hook used to fetch the previous and next record identifiers for a given record and resource.
+ *
+ * It fetches the list of records according to the filters
+ * and the sort order configured in the list, and merges
+ * the filters and the sorting order passed as props.
+ *
+ * usePrevNextController can be used anywhere a record context is provided
+ * (often inside a `<Show>` or `<Edit>` component).
+ *
+ * @example <caption>Simple usage</caption>
+ *
+ * import { usePrevNextControllerProps } from '@strato-admin/ra-core';
+ * const {
+ *         hasPrev,
+ *         hasNext,
+ *         prevPath,
+ *         nextPath,
+ *         index,
+ *         total,
+ *         error,
+ *         isPending,
+ *     } = usePrevNextController(props);
+ *
+ * @example <caption>Custom PrevNextButton</caption>
+ *
+ * import { UsePrevNextControllerProps, useTranslate } from '@strato-admin/ra-core';
+ * import NavigateBefore from '@mui/icons-material/NavigateBefore';
+ * import NavigateNext from '@mui/icons-material/NavigateNext';
+ * import ErrorIcon from '@mui/icons-material/Error';
+ * import { Link } from 'react-router-dom';
+ * import { CircularProgress, IconButton } from '@mui/material';
+ *
+ * const MyPrevNextButtons = props => {
+ *     const {
+ *         hasPrev,
+ *         hasNext,
+ *         nextPath,
+ *         prevPath,
+ *         index,
+ *         total,
+ *         error,
+ *         isPending,
+ *     } = usePrevNextController(props);
+ *
+ *     const translate = useTranslate();
+ *
+ *     if (isPending) {
+ *         return <CircularProgress size={14} />;
+ *     }
+ *
+ *     if (error) {
+ *         return (
+ *             <ErrorIcon
+ *                 color="error"
+ *                 fontSize="small"
+ *                 titleAccess="error"
+ *                 aria-errormessage={error.message}
+ *             />
+ *         );
+ *     }
+ *
+ *     return (
+ *         <ul>
+ *             <li>
+ *                 <IconButton
+ *                     component={hasPrev ? Link : undefined}
+ *                     to={navigateToPrev}
+ *                     aria-label={translate("strato.navigation.previous')}
+ *                     disabled={!hasPrev}
+ *                 >
+ *                     <NavigateBefore />
+ *                 </IconButton>
+ *             </li>
+ *             {typeof index === 'number' && (
+ *                 <li>
+ *                     {index + 1} / {total}
+ *                 </li>
+ *             )}
+ *             <li>
+ *                 <IconButton
+ *                     component={hasNext ? Link : undefined}
+ *                     to={navigateToNext}
+ *                     aria-label={translate("strato.navigation.next')}
+ *                     disabled={!hasNext}
+ *                 >
+ *                     <NavigateNext />
+ *                 </IconButton>
+ *             </li>
+ *         </ul>
+ *     );
+ * };
+ */
+export declare const usePrevNextController: <RecordType extends RaRecord = any>(props: UsePrevNextControllerProps<RecordType>) => UsePrevNextControllerResult;
+export interface UsePrevNextControllerProps<RecordType extends RaRecord = any> {
+    linkType?: 'edit' | 'show';
+    storeKey?: string | false;
+    limit?: number;
+    filter?: FilterPayload;
+    filterDefaultValues?: FilterPayload;
+    sort?: SortPayload;
+    resource?: string;
+    queryOptions?: Omit<UseQueryOptions<{
+        data: RecordType[];
+        total?: number;
+        pageInfo?: {
+            hasNextPage?: boolean;
+            hasPreviousPage?: boolean;
+        };
+    }>, 'queryFn' | 'queryKey'> & {
+        meta?: any;
+    };
+}
+export type UsePrevNextControllerResult = {
+    isFetching: boolean;
+    isLoading: boolean;
+    isPending: boolean;
+    hasPrev: boolean;
+    hasNext: boolean;
+    prevPath: string | undefined;
+    nextPath: string | undefined;
+    index: number | undefined;
+    total: number | undefined;
+    error?: any;
+};

package/dist/ra-core/src/controller/usePrevNextController.js

@@ -0,0 +1,215 @@
+import { useQuery, useQueryClient, } from '@tanstack/react-query';
+import { useResourceContext } from '../core';
+import { useDataProvider } from '../dataProvider';
+import { useStore } from '../store';
+import { SORT_ASC } from './list';
+import { useRecordContext } from './record';
+import { useCreatePath } from '../routing';
+/**
+ * A hook used to fetch the previous and next record identifiers for a given record and resource.
+ *
+ * It fetches the list of records according to the filters
+ * and the sort order configured in the list, and merges
+ * the filters and the sorting order passed as props.
+ *
+ * usePrevNextController can be used anywhere a record context is provided
+ * (often inside a `<Show>` or `<Edit>` component).
+ *
+ * @example <caption>Simple usage</caption>
+ *
+ * import { usePrevNextControllerProps } from '@strato-admin/ra-core';
+ * const {
+ *         hasPrev,
+ *         hasNext,
+ *         prevPath,
+ *         nextPath,
+ *         index,
+ *         total,
+ *         error,
+ *         isPending,
+ *     } = usePrevNextController(props);
+ *
+ * @example <caption>Custom PrevNextButton</caption>
+ *
+ * import { UsePrevNextControllerProps, useTranslate } from '@strato-admin/ra-core';
+ * import NavigateBefore from '@mui/icons-material/NavigateBefore';
+ * import NavigateNext from '@mui/icons-material/NavigateNext';
+ * import ErrorIcon from '@mui/icons-material/Error';
+ * import { Link } from 'react-router-dom';
+ * import { CircularProgress, IconButton } from '@mui/material';
+ *
+ * const MyPrevNextButtons = props => {
+ *     const {
+ *         hasPrev,
+ *         hasNext,
+ *         nextPath,
+ *         prevPath,
+ *         index,
+ *         total,
+ *         error,
+ *         isPending,
+ *     } = usePrevNextController(props);
+ *
+ *     const translate = useTranslate();
+ *
+ *     if (isPending) {
+ *         return <CircularProgress size={14} />;
+ *     }
+ *
+ *     if (error) {
+ *         return (
+ *             <ErrorIcon
+ *                 color="error"
+ *                 fontSize="small"
+ *                 titleAccess="error"
+ *                 aria-errormessage={error.message}
+ *             />
+ *         );
+ *     }
+ *
+ *     return (
+ *         <ul>
+ *             <li>
+ *                 <IconButton
+ *                     component={hasPrev ? Link : undefined}
+ *                     to={navigateToPrev}
+ *                     aria-label={translate("strato.navigation.previous')}
+ *                     disabled={!hasPrev}
+ *                 >
+ *                     <NavigateBefore />
+ *                 </IconButton>
+ *             </li>
+ *             {typeof index === 'number' && (
+ *                 <li>
+ *                     {index + 1} / {total}
+ *                 </li>
+ *             )}
+ *             <li>
+ *                 <IconButton
+ *                     component={hasNext ? Link : undefined}
+ *                     to={navigateToNext}
+ *                     aria-label={translate("strato.navigation.next')}
+ *                     disabled={!hasNext}
+ *                 >
+ *                     <NavigateNext />
+ *                 </IconButton>
+ *             </li>
+ *         </ul>
+ *     );
+ * };
+ */
+export const usePrevNextController = (props) => {
+    const { linkType = 'edit', storeKey, limit = 1000, sort: initialSort = { field: 'id', order: SORT_ASC }, filter: permanentFilter = {}, filterDefaultValues = {}, queryOptions = {
+        staleTime: 5 * 60 * 1000,
+    }, } = props;
+    const record = useRecordContext(props);
+    const resource = useResourceContext(props);
+    const createPath = useCreatePath();
+    if (!resource) {
+        throw new Error(`useNextPrevController was called outside of a ResourceContext and without a resource prop. You must set the resource prop.`);
+    }
+    const [storedParams] = useStore(storeKey || `${resource}.listParams`, {
+        filter: filterDefaultValues,
+        order: initialSort.order,
+        sort: initialSort.field,
+        page: 1,
+        perPage: 10,
+        displayedFilters: {},
+    });
+    const dataProvider = useDataProvider();
+    const queryClient = useQueryClient();
+    const pagination = { page: 1, perPage: limit };
+    const sort = {
+        field: storedParams.sort,
+        order: storedParams.order,
+    };
+    const filter = { ...storedParams.filter, ...permanentFilter };
+    const { meta, ...otherQueryOptions } = queryOptions;
+    const params = { pagination, sort, filter, meta };
+    // try to use data from the cache first
+    const queryData = queryClient.getQueryData([
+        resource,
+        'getList',
+        {
+            ...params,
+            pagination: {
+                page: storedParams.page,
+                perPage: storedParams.perPage,
+            },
+        },
+    ]);
+    const recordIndexInQueryData = queryData?.data?.findIndex(r => r.id === record?.id);
+    const isRecordIndexFirstInNonFirstPage = recordIndexInQueryData === 0 && storedParams.page > 1;
+    const isRecordIndexLastInNonLastPage = queryData?.data && queryData?.total
+        ? recordIndexInQueryData === queryData?.data?.length - 1 &&
+            storedParams.page < queryData?.total / storedParams.perPage
+        : undefined;
+    const canUseCacheData = record &&
+        queryData?.data &&
+        recordIndexInQueryData !== -1 &&
+        !isRecordIndexFirstInNonFirstPage &&
+        !isRecordIndexLastInNonLastPage;
+    // If the previous and next ids are not in the cache, fetch the entire list.
+    // This is necessary e.g. when coming directly to a detail page,
+    // without displaying the list first
+    const { data, error, isFetching, isLoading, isPending } = useQuery({
+        queryKey: [resource, 'getList', params],
+        queryFn: queryParams => {
+            return dataProvider.getList(resource, {
+                ...params,
+                signal: dataProvider.supportAbortSignal === true
+                    ? queryParams.signal
+                    : undefined,
+            });
+        },
+        enabled: !canUseCacheData,
+        ...otherQueryOptions,
+    });
+    const finalData = canUseCacheData ? queryData.data : data?.data || [];
+    if (!record || (isPending && !canUseCacheData))
+        return {
+            isFetching: true,
+            isLoading: true,
+            isPending: true,
+            prevPath: undefined,
+            nextPath: undefined,
+            index: undefined,
+            total: undefined,
+            hasPrev: false,
+            hasNext: false,
+        };
+    const ids = finalData.map(record => record.id);
+    const index = ids.indexOf(record.id);
+    const previousId = typeof ids[index - 1] !== 'undefined' ? ids[index - 1] : null; // could be 0
+    const nextId = index !== -1 && index < ids.length - 1 ? ids[index + 1] : null;
+    return {
+        hasPrev: previousId !== null,
+        hasNext: nextId !== null,
+        prevPath: previousId !== null
+            ? createPath({
+                type: linkType,
+                resource,
+                id: previousId,
+            })
+            : undefined,
+        nextPath: nextId !== null
+            ? createPath({
+                type: linkType,
+                resource,
+                id: nextId,
+            })
+            : undefined,
+        index: index === -1
+            ? undefined
+            : index +
+                (canUseCacheData
+                    ? (storedParams.perPage ?? 0) *
+                        ((storedParams.page ?? 1) - 1)
+                    : 0),
+        total: canUseCacheData ? queryData?.total : data?.total,
+        error,
+        isFetching: canUseCacheData ? false : isFetching,
+        isLoading: canUseCacheData ? false : isLoading,
+        isPending: canUseCacheData ? false : isPending,
+    };
+};

package/dist/ra-core/src/controller/useReference.d.ts

@@ -0,0 +1,49 @@
+import { RaRecord, Identifier } from '../types';
+import { UseGetManyHookValue } from '../dataProvider';
+import { UseQueryOptions } from '@tanstack/react-query';
+interface UseReferenceProps<RecordType extends RaRecord = any, ErrorType = Error> {
+    id: Identifier;
+    reference: string;
+    options?: Omit<UseQueryOptions<RecordType[], ErrorType>, 'queryFn' | 'queryKey'> & {
+        meta?: any;
+    };
+}
+export interface UseReferenceResult<RecordType extends RaRecord = any, ErrorType = Error> {
+    isLoading: boolean;
+    isPaused?: boolean;
+    isPending: boolean;
+    isPlaceholderData?: boolean;
+    isFetching: boolean;
+    referenceRecord?: RecordType;
+    error?: ErrorType | null;
+    refetch: UseGetManyHookValue<RecordType, ErrorType>['refetch'];
+}
+/**
+ * @typedef UseReferenceResult
+ * @type {Object}
+ * @property {boolean} isFetching: boolean indicating if the reference is loading
+ * @property {boolean} isLoading: boolean indicating if the reference has loaded at least once
+ * @property {Object} referenceRecord: the referenced record.
+ */
+/**
+ * Fetch reference record, and return it when available
+ *
+ * The reference prop should be the name of one of the <Resource> components
+ * added as <Admin> child.
+ *
+ * @example
+ *
+ * const { isLoading, referenceRecord } = useReference({
+ *     id: 7,
+ *     reference: 'users',
+ * });
+ *
+ * @param {Object} option
+ * @param {string} option.reference The linked resource name
+ * @param {string} option.id The id of the reference
+ * @param {Object} option.options Options passed to the dataProvider
+ *
+ * @returns {UseReferenceResult} The reference record
+ */
+export declare const useReference: <RecordType extends RaRecord = RaRecord, ErrorType = Error>({ reference, id, options, }: UseReferenceProps<RecordType, ErrorType>) => UseReferenceResult<RecordType, ErrorType>;
+export {};

package/dist/ra-core/src/controller/useReference.js

@@ -0,0 +1,42 @@
+import { useGetManyAggregate } from '../dataProvider';
+/**
+ * @typedef UseReferenceResult
+ * @type {Object}
+ * @property {boolean} isFetching: boolean indicating if the reference is loading
+ * @property {boolean} isLoading: boolean indicating if the reference has loaded at least once
+ * @property {Object} referenceRecord: the referenced record.
+ */
+/**
+ * Fetch reference record, and return it when available
+ *
+ * The reference prop should be the name of one of the <Resource> components
+ * added as <Admin> child.
+ *
+ * @example
+ *
+ * const { isLoading, referenceRecord } = useReference({
+ *     id: 7,
+ *     reference: 'users',
+ * });
+ *
+ * @param {Object} option
+ * @param {string} option.reference The linked resource name
+ * @param {string} option.id The id of the reference
+ * @param {Object} option.options Options passed to the dataProvider
+ *
+ * @returns {UseReferenceResult} The reference record
+ */
+export const useReference = ({ reference, id, options = {}, }) => {
+    const { meta, ...otherQueryOptions } = options;
+    const { data, error, isLoading, isFetching, isPaused, isPending, isPlaceholderData, refetch, } = useGetManyAggregate(reference, { ids: [id], meta }, otherQueryOptions);
+    return {
+        referenceRecord: error ? undefined : data ? data[0] : undefined,
+        refetch,
+        error,
+        isLoading,
+        isFetching,
+        isPaused,
+        isPending,
+        isPlaceholderData,
+    };
+};

package/dist/ra-core/src/controller/useSortState.d.ts

@@ -0,0 +1,61 @@
+import { SortPayload } from '../types';
+export interface SortProps {
+    setSortField: (field: SortPayload['field']) => void;
+    setSortOrder: (order: SortPayload['order']) => void;
+    setSort: (sort: SortPayload) => void;
+    sort: SortPayload;
+}
+export declare const defaultSort: {
+    readonly field: "";
+    readonly order: "ASC";
+};
+/**
+ * Set the sort { field, order }
+ * @name setSort
+ * @function
+ * @param {SortPayload} sort the sort object
+ */
+/**
+ * Set the sort field, swap the order if the field is the same
+ * @name setSortField
+ * @function
+ * @param {string} field the sort field
+ */
+/**
+ * Set the sort order
+ * @name setSortOrder
+ * @function
+ * @param {string} order The sort order, either ASC or DESC
+ */
+/**
+ * @typedef SortProps
+ * @type {Object}
+ * @property {Object} sort: the sort object.
+ * @property {string} sort.field: the sort object.
+ * @property {'ASC' | 'DESC'} sort.order: the sort object.
+ * @property {setSort} setSort
+ * @property {setSortField} setSortField
+ * @property {setSortOrder} setSortOrder
+ */
+/**
+ * Hooks to provide sort state
+ *
+ * @example
+ *
+ * const { sort, setSort, setSortField, setSortOrder } = useSort({
+ *      field: 'name',
+ *      order: 'ASC',
+ * });
+ *
+ * setSort({ field: 'name', order: 'ASC' });
+ * // is the same as
+ * setSortField('name');
+ * setSortOrder('ASC');
+ *
+ * @param {Object} initialSort
+ * @param {string} initialSort.field The initial sort field
+ * @param {string} initialSort.order The initial sort order
+ * @returns {SortProps} The sort props
+ */
+declare const useSortState: (initialSort?: SortPayload) => SortProps;
+export default useSortState;

package/dist/ra-core/src/controller/useSortState.js

@@ -0,0 +1,96 @@
+import { useReducer, useEffect, useRef, useCallback } from 'react';
+import { SORT_ASC, SORT_DESC } from './list/queryReducer';
+const sortReducer = (state, action) => {
+    switch (action.type) {
+        case 'SET_SORT':
+            return action.payload;
+        case 'SET_SORT_FIELD': {
+            const field = action.payload;
+            const order = state.field === field
+                ? state.order === SORT_ASC
+                    ? SORT_DESC
+                    : SORT_ASC
+                : SORT_ASC;
+            return { field, order };
+        }
+        case 'SET_SORT_ORDER': {
+            const order = action.payload;
+            if (!state.field) {
+                throw new Error('cannot change the order on an undefined sort field');
+            }
+            return {
+                field: state.field,
+                order,
+            };
+        }
+        default:
+            return state;
+    }
+};
+export const defaultSort = { field: '', order: 'ASC' };
+/**
+ * Set the sort { field, order }
+ * @name setSort
+ * @function
+ * @param {SortPayload} sort the sort object
+ */
+/**
+ * Set the sort field, swap the order if the field is the same
+ * @name setSortField
+ * @function
+ * @param {string} field the sort field
+ */
+/**
+ * Set the sort order
+ * @name setSortOrder
+ * @function
+ * @param {string} order The sort order, either ASC or DESC
+ */
+/**
+ * @typedef SortProps
+ * @type {Object}
+ * @property {Object} sort: the sort object.
+ * @property {string} sort.field: the sort object.
+ * @property {'ASC' | 'DESC'} sort.order: the sort object.
+ * @property {setSort} setSort
+ * @property {setSortField} setSortField
+ * @property {setSortOrder} setSortOrder
+ */
+/**
+ * Hooks to provide sort state
+ *
+ * @example
+ *
+ * const { sort, setSort, setSortField, setSortOrder } = useSort({
+ *      field: 'name',
+ *      order: 'ASC',
+ * });
+ *
+ * setSort({ field: 'name', order: 'ASC' });
+ * // is the same as
+ * setSortField('name');
+ * setSortOrder('ASC');
+ *
+ * @param {Object} initialSort
+ * @param {string} initialSort.field The initial sort field
+ * @param {string} initialSort.order The initial sort order
+ * @returns {SortProps} The sort props
+ */
+const useSortState = (initialSort = defaultSort) => {
+    const [sort, dispatch] = useReducer(sortReducer, initialSort);
+    const isFirstRender = useRef(true);
+    useEffect(() => {
+        if (isFirstRender.current) {
+            isFirstRender.current = false;
+            return;
+        }
+        dispatch({ type: 'SET_SORT', payload: initialSort });
+    }, [initialSort.field, initialSort.order]); // eslint-disable-line react-hooks/exhaustive-deps
+    return {
+        setSort: useCallback((sort) => dispatch({ type: 'SET_SORT', payload: sort }), [dispatch]),
+        setSortField: useCallback((field) => dispatch({ type: 'SET_SORT_FIELD', payload: field }), [dispatch]),
+        setSortOrder: useCallback((order) => dispatch({ type: 'SET_SORT_ORDER', payload: order }), [dispatch]),
+        sort,
+    };
+};
+export default useSortState;