@strato-admin/core 0.1.0 → 0.3.0

package/dist/ra-core/src/controller/list/useListParams.d.ts

@@ -0,0 +1,116 @@
+import { SortPayload, FilterPayload } from '../../types';
+export interface ListParams {
+    sort: string;
+    order: 'ASC' | 'DESC';
+    page: number;
+    perPage: number;
+    filter: any;
+    displayedFilters: any;
+}
+/**
+ * Get the list parameters (page, sort, filters) and modifiers.
+ *
+ * These parameters are merged from 3 sources:
+ *   - the query string from the URL
+ *   - the params stored in the state (from previous navigation)
+ *   - the options passed to the hook (including the filter defaultValues)
+ *
+ * @returns {Array} A tuple [parameters, modifiers].
+ * Destructure as [
+ *    { page, perPage, sort, order, filter, filterValues, displayedFilters, requestSignature },
+ *    { setFilters, hideFilter, showFilter, setPage, setPerPage, setSort }
+ * ]
+ *
+ * @example
+ *
+ * const [listParams, listParamsActions] = useListParams({
+ *      resource: 'posts',
+ *      location: location // From react-router. Injected to your component by react-admin inside a List
+ *      filterDefaultValues: {
+ *          published: true
+ *      },
+ *      sort: {
+ *          field: 'published_at',
+ *          order: 'DESC'
+ *      },
+ *      perPage: 25
+ * });
+ *
+ * const {
+ *      page,
+ *      perPage,
+ *      sort,
+ *      order,
+ *      filter,
+ *      filterValues,
+ *      displayedFilters,
+ *      requestSignature
+ * } = listParams;
+ *
+ * const {
+ *      setFilters,
+ *      hideFilter,
+ *      showFilter,
+ *      setPage,
+ *      setPerPage,
+ *      setSort,
+ * } = listParamsActions;
+ */
+export declare const useListParams: ({ debounce, disableSyncWithLocation, filterDefaultValues, perPage, resource, sort, storeKey, }: ListParamsOptions) => [Parameters, Modifiers];
+export declare const parseQueryFromLocation: ({ search }: {
+    search: any;
+}) => Partial<ListParams>;
+/**
+ * Check if user has already set custom sort, page, or filters for this list
+ *
+ * User params come from the store as the params props. By default,
+ * this object is:
+ *
+ * { filter: {}, order: null, page: 1, perPage: null, sort: null }
+ *
+ * To check if the user has custom params, we must compare the params
+ * to these initial values.
+ *
+ * @param {Object} params
+ */
+export declare const hasCustomParams: (params: ListParams) => any;
+/**
+ * Merge list params from 3 different sources:
+ *   - the query string
+ *   - the params stored in the state (from previous navigation)
+ *   - the props passed to the List component (including the filter defaultValues)
+ */
+export declare const getQuery: ({ queryFromLocation, params, filterDefaultValues, sort, perPage, }: {
+    queryFromLocation: any;
+    params: any;
+    filterDefaultValues: any;
+    sort: any;
+    perPage: any;
+}) => ListParams;
+export declare const getNumberOrDefault: (possibleNumber: string | number | undefined, defaultValue: number) => number;
+export interface ListParamsOptions {
+    debounce?: number;
+    disableSyncWithLocation?: boolean;
+    filterDefaultValues?: FilterPayload;
+    perPage?: number;
+    resource: string;
+    sort?: SortPayload;
+    storeKey?: string | false;
+}
+interface Parameters extends ListParams {
+    filterValues: object;
+    displayedFilters: {
+        [key: string]: boolean;
+    };
+    requestSignature: any[];
+}
+interface Modifiers {
+    changeParams: (action: any) => void;
+    setPage: (page: number) => void;
+    setPerPage: (pageSize: number) => void;
+    setSort: (sort: SortPayload) => void;
+    setFilters: (filters: any, displayedFilters?: any, debounce?: boolean) => void;
+    hideFilter: (filterName: string) => void;
+    showFilter: (filterName: string, defaultValue: any) => void;
+}
+export {};

package/dist/ra-core/src/controller/list/useListParams.js

@@ -0,0 +1,281 @@
+import { useCallback, useMemo, useEffect, useState, useRef } from 'react';
+import { parse, stringify } from 'query-string';
+import lodashDebounce from 'lodash/debounce.js';
+import { useStore } from '../../store';
+import { useNavigate, useLocation } from '../../routing';
+import queryReducer, { SET_FILTER, HIDE_FILTER, SHOW_FILTER, SET_PAGE, SET_PER_PAGE, SET_SORT, SORT_ASC, } from './queryReducer';
+import removeEmpty from '../../util/removeEmpty';
+import { useIsMounted } from '../../util/hooks';
+/**
+ * Get the list parameters (page, sort, filters) and modifiers.
+ *
+ * These parameters are merged from 3 sources:
+ *   - the query string from the URL
+ *   - the params stored in the state (from previous navigation)
+ *   - the options passed to the hook (including the filter defaultValues)
+ *
+ * @returns {Array} A tuple [parameters, modifiers].
+ * Destructure as [
+ *    { page, perPage, sort, order, filter, filterValues, displayedFilters, requestSignature },
+ *    { setFilters, hideFilter, showFilter, setPage, setPerPage, setSort }
+ * ]
+ *
+ * @example
+ *
+ * const [listParams, listParamsActions] = useListParams({
+ *      resource: 'posts',
+ *      location: location // From react-router. Injected to your component by react-admin inside a List
+ *      filterDefaultValues: {
+ *          published: true
+ *      },
+ *      sort: {
+ *          field: 'published_at',
+ *          order: 'DESC'
+ *      },
+ *      perPage: 25
+ * });
+ *
+ * const {
+ *      page,
+ *      perPage,
+ *      sort,
+ *      order,
+ *      filter,
+ *      filterValues,
+ *      displayedFilters,
+ *      requestSignature
+ * } = listParams;
+ *
+ * const {
+ *      setFilters,
+ *      hideFilter,
+ *      showFilter,
+ *      setPage,
+ *      setPerPage,
+ *      setSort,
+ * } = listParamsActions;
+ */
+export const useListParams = ({ debounce = 500, disableSyncWithLocation = false, filterDefaultValues, perPage = 10, resource, sort = defaultSort, storeKey = disableSyncWithLocation ? false : `${resource}.listParams`, }) => {
+    const location = useLocation();
+    const navigate = useNavigate();
+    const [localParams, setLocalParams] = useState(defaultParams);
+    // As we can't conditionally call a hook, if the storeKey is false,
+    // we'll ignore the params variable later on and won't call setParams either.
+    const [params, setParams] = useStore(storeKey || `${resource}.listParams`, defaultParams);
+    const tempParams = useRef(undefined);
+    const isMounted = useIsMounted();
+    const requestSignature = [
+        location.search,
+        resource,
+        storeKey,
+        JSON.stringify(!storeKey ? localParams : params),
+        JSON.stringify(filterDefaultValues),
+        JSON.stringify(sort),
+        perPage,
+        disableSyncWithLocation,
+    ];
+    const queryFromLocation = disableSyncWithLocation
+        ? {}
+        : parseQueryFromLocation(location);
+    const query = useMemo(() => getQuery({
+        queryFromLocation,
+        params: !storeKey ? localParams : params,
+        filterDefaultValues,
+        sort,
+        perPage,
+    }), requestSignature // eslint-disable-line react-hooks/exhaustive-deps
+    );
+    // if the location includes params (for example from a link like
+    // the categories products on the demo), we need to persist them in the
+    // store as well so that we don't lose them after a redirection back
+    // to the list
+    useEffect(() => {
+        if (Object.keys(queryFromLocation).length > 0) {
+            setParams(query);
+        }
+    }, [location.search]); // eslint-disable-line
+    const changeParams = useCallback(action => {
+        // do not change params if the component is already unmounted
+        // this is necessary because changeParams can be debounced, and therefore
+        // executed after the component is unmounted
+        if (!isMounted.current)
+            return;
+        if (!tempParams.current) {
+            // no other changeParams action dispatched this tick
+            tempParams.current = queryReducer(query, action);
+            // schedule side effects for next tick
+            setTimeout(() => {
+                if (!tempParams.current) {
+                    // the side effects were already processed by another changeParams
+                    return;
+                }
+                if (disableSyncWithLocation && !storeKey) {
+                    setLocalParams(tempParams.current);
+                }
+                else if (disableSyncWithLocation && !!storeKey) {
+                    setParams(tempParams.current);
+                }
+                else {
+                    // the useEffect above will apply the changes to the params in the store
+                    navigate({
+                        search: `?${stringify({
+                            ...tempParams.current,
+                            filter: JSON.stringify(tempParams.current.filter),
+                            displayedFilters: JSON.stringify(tempParams.current.displayedFilters),
+                        })}`,
+                    }, {
+                        state: {
+                            _scrollToTop: action.type === SET_PAGE,
+                        },
+                    });
+                }
+                tempParams.current = undefined;
+            }, 0);
+        }
+        else {
+            // side effects already scheduled, just change the params
+            tempParams.current = queryReducer(tempParams.current, action);
+        }
+    }, [...requestSignature, navigate] // eslint-disable-line react-hooks/exhaustive-deps
+    );
+    const setSort = useCallback((sort) => changeParams({
+        type: SET_SORT,
+        payload: sort,
+    }), [changeParams]);
+    const setPage = useCallback((newPage) => changeParams({ type: SET_PAGE, payload: newPage }), [changeParams]);
+    const setPerPage = useCallback((newPerPage) => changeParams({ type: SET_PER_PAGE, payload: newPerPage }), [changeParams]);
+    const filterValues = query.filter || emptyObject;
+    const displayedFilterValues = query.displayedFilters || emptyObject;
+    const debouncedSetFilters = lodashDebounce((filter, displayedFilters) => {
+        changeParams({
+            type: SET_FILTER,
+            payload: {
+                filter: removeEmpty(filter),
+                displayedFilters,
+            },
+        });
+    }, debounce);
+    const setFilters = useCallback((filter, displayedFilters = undefined, debounce = false) => debounce
+        ? debouncedSetFilters(filter, displayedFilters)
+        : changeParams({
+            type: SET_FILTER,
+            payload: {
+                filter: removeEmpty(filter),
+                displayedFilters,
+            },
+        }), [changeParams] // eslint-disable-line react-hooks/exhaustive-deps
+    );
+    const hideFilter = useCallback((filterName) => {
+        changeParams({
+            type: HIDE_FILTER,
+            payload: filterName,
+        });
+    }, [changeParams]);
+    const showFilter = useCallback((filterName, defaultValue) => {
+        changeParams({
+            type: SHOW_FILTER,
+            payload: {
+                filterName,
+                defaultValue,
+            },
+        });
+    }, [changeParams]);
+    return [
+        {
+            filterValues,
+            requestSignature,
+            ...query,
+            displayedFilters: displayedFilterValues,
+        },
+        {
+            changeParams,
+            setPage,
+            setPerPage,
+            setSort,
+            setFilters,
+            hideFilter,
+            showFilter,
+        },
+    ];
+};
+const parseObject = (query, field) => {
+    if (query[field] && typeof query[field] === 'string') {
+        try {
+            query[field] = JSON.parse(query[field]);
+        }
+        catch (err) {
+            delete query[field];
+        }
+    }
+};
+export const parseQueryFromLocation = ({ search }) => {
+    const query = parse(search);
+    parseObject(query, 'filter');
+    parseObject(query, 'displayedFilters');
+    return query;
+};
+/**
+ * Check if user has already set custom sort, page, or filters for this list
+ *
+ * User params come from the store as the params props. By default,
+ * this object is:
+ *
+ * { filter: {}, order: null, page: 1, perPage: null, sort: null }
+ *
+ * To check if the user has custom params, we must compare the params
+ * to these initial values.
+ *
+ * @param {Object} params
+ */
+export const hasCustomParams = (params) => {
+    return (params &&
+        params.filter &&
+        (Object.keys(params.filter).length > 0 ||
+            params.order != null ||
+            params.page !== 1 ||
+            params.perPage != null ||
+            params.sort != null));
+};
+/**
+ * Merge list params from 3 different sources:
+ *   - the query string
+ *   - the params stored in the state (from previous navigation)
+ *   - the props passed to the List component (including the filter defaultValues)
+ */
+export const getQuery = ({ queryFromLocation, params, filterDefaultValues, sort, perPage, }) => {
+    const query = Object.keys(queryFromLocation).length > 0
+        ? queryFromLocation
+        : hasCustomParams(params)
+            ? { ...params }
+            : { filter: filterDefaultValues || {} };
+    if (!query.sort) {
+        query.sort = sort.field;
+        query.order = sort.order;
+    }
+    if (query.perPage == null) {
+        query.perPage = perPage;
+    }
+    if (query.page == null) {
+        query.page = 1;
+    }
+    return {
+        ...query,
+        page: getNumberOrDefault(query.page, 1),
+        perPage: getNumberOrDefault(query.perPage, 10),
+    };
+};
+export const getNumberOrDefault = (possibleNumber, defaultValue) => {
+    if (typeof possibleNumber === 'undefined') {
+        return defaultValue;
+    }
+    const parsedNumber = typeof possibleNumber === 'string'
+        ? parseInt(possibleNumber, 10)
+        : possibleNumber;
+    return isNaN(parsedNumber) ? defaultValue : parsedNumber;
+};
+const emptyObject = {};
+const defaultSort = {
+    field: 'id',
+    order: SORT_ASC,
+};
+const defaultParams = {};

package/dist/ra-core/src/controller/list/useListSortContext.d.ts

@@ -0,0 +1,12 @@
+import { ListSortContextValue } from './ListSortContext';
+/**
+ * Hook to read the list sort controller props from the ListSortContext.
+ *
+ * Must be used within a <ListSortContextProvider> (e.g. as a descendent of <List>
+ * or <ListBase>).
+ *
+ * @returns {ListSortContextValue} list controller props
+ *
+ * @see useListController for how it is filled
+ */
+export declare const useListSortContext: () => ListSortContextValue;

package/dist/ra-core/src/controller/list/useListSortContext.js

@@ -0,0 +1,19 @@
+import { useContext } from 'react';
+import { ListSortContext } from './ListSortContext';
+/**
+ * Hook to read the list sort controller props from the ListSortContext.
+ *
+ * Must be used within a <ListSortContextProvider> (e.g. as a descendent of <List>
+ * or <ListBase>).
+ *
+ * @returns {ListSortContextValue} list controller props
+ *
+ * @see useListController for how it is filled
+ */
+export const useListSortContext = () => {
+    const context = useContext(ListSortContext);
+    if (!context) {
+        throw new Error('useListSortContext must be used inside a ListSortContextProvider');
+    }
+    return context;
+};

package/dist/ra-core/src/controller/list/useRecordSelection.d.ts

@@ -0,0 +1,32 @@
+import { RaRecord } from '../../types';
+type UseRecordSelectionWithResourceArgs = {
+    resource: string;
+    storeKey?: string;
+    disableSyncWithStore?: false;
+};
+type UseRecordSelectionWithNoStoreArgs = {
+    resource?: string;
+    storeKey?: string;
+    disableSyncWithStore: true;
+};
+export type UseRecordSelectionArgs = UseRecordSelectionWithResourceArgs | UseRecordSelectionWithNoStoreArgs;
+export type UseRecordSelectionResult<RecordType extends RaRecord = any> = [
+    RecordType['id'][],
+    {
+        select: (ids: RecordType['id'][]) => void;
+        unselect: (ids: RecordType['id'][], fromAllStoreKeys?: boolean) => void;
+        toggle: (id: RecordType['id']) => void;
+        clearSelection: (fromAllStoreKeys?: boolean) => void;
+    }
+];
+/**
+ * Get the list of selected items for a resource, and callbacks to change the selection
+ *
+ * @param args.resource The resource name, e.g. 'posts'
+ * @param args.storeKey The key to use to store selected items. Pass false to disable synchronization with the store.
+ * @param args.disableSyncWithStore Controls the selection synchronization with the store
+ *
+ * @returns {Object} Destructure as [selectedIds, { select, unselect, toggle, clearSelection }].
+ */
+export declare const useRecordSelection: <RecordType extends RaRecord = any>(args: UseRecordSelectionArgs) => UseRecordSelectionResult<RecordType>;
+export {};

package/dist/ra-core/src/controller/list/useRecordSelection.js

@@ -0,0 +1,93 @@
+import { useEffect, useMemo, useState } from 'react';
+import { useStore, useStoreContext } from '../../store';
+/**
+ * Get the list of selected items for a resource, and callbacks to change the selection
+ *
+ * @param args.resource The resource name, e.g. 'posts'
+ * @param args.storeKey The key to use to store selected items. Pass false to disable synchronization with the store.
+ * @param args.disableSyncWithStore Controls the selection synchronization with the store
+ *
+ * @returns {Object} Destructure as [selectedIds, { select, unselect, toggle, clearSelection }].
+ */
+export const useRecordSelection = (args) => {
+    const { resource = '', storeKey, disableSyncWithStore } = args;
+    const finalStoreKey = `${storeKey || resource}.selectedIds`;
+    const [localSelectionStore, setLocalSelectionStore] = useState(defaultIds);
+    // As we can't conditionally call a hook, if the disableSyncWithStore is true,
+    // we'll ignore the useStore values later on and won't call set functions either.
+    const [selectionStore, setSelectionStore] = useStore(finalStoreKey, defaultIds);
+    const [storeKeys, setStoreKeys] = useStore(`${resource}.selectedIds.storeKeys`, defaultStoreKeys);
+    useEffect(function addStoreKeyToStore() {
+        if (!disableSyncWithStore && storeKey) {
+            setStoreKeys(storeKeys => {
+                if (!storeKeys.includes(finalStoreKey)) {
+                    return [...storeKeys, finalStoreKey];
+                }
+                else {
+                    return storeKeys;
+                }
+            });
+        }
+    }, [disableSyncWithStore, finalStoreKey, setStoreKeys, storeKey]);
+    const { getItem, setItem } = useStoreContext();
+    const ids = disableSyncWithStore ? localSelectionStore : selectionStore;
+    const setStore = useMemo(() => disableSyncWithStore ? setLocalSelectionStore : setSelectionStore, [disableSyncWithStore, setSelectionStore]);
+    const selectionModifiers = useMemo(() => ({
+        select: (idsToSelect) => {
+            if (!idsToSelect)
+                return;
+            setStore(idsToSelect);
+        },
+        unselect(idsToRemove, fromAllStoreKeys) {
+            if (!idsToRemove || idsToRemove.length === 0)
+                return;
+            setStore(ids => ids.filter(id => !idsToRemove.includes(id)));
+            if (!disableSyncWithStore && fromAllStoreKeys) {
+                storeKeys
+                    .filter(storeKey => storeKey !== finalStoreKey)
+                    .forEach(storeKey => {
+                    const ids = getItem(storeKey);
+                    if (ids) {
+                        setItem(storeKey, ids.filter(id => !idsToRemove.includes(id)));
+                    }
+                });
+            }
+        },
+        toggle: (id) => {
+            if (typeof id === 'undefined')
+                return;
+            setStore(ids => {
+                if (!Array.isArray(ids))
+                    return [...ids];
+                const index = ids.indexOf(id);
+                const hasId = index > -1;
+                return hasId
+                    ? [...ids.slice(0, index), ...ids.slice(index + 1)]
+                    : [...ids, id];
+            });
+        },
+        clearSelection: (fromAllStoreKeys) => {
+            setStore(defaultIds);
+            if (!disableSyncWithStore && fromAllStoreKeys) {
+                storeKeys
+                    .filter(storeKey => storeKey !== finalStoreKey)
+                    .forEach(storeKey => {
+                    const ids = getItem(storeKey);
+                    if (ids) {
+                        setItem(storeKey, defaultIds);
+                    }
+                });
+            }
+        },
+    }), [
+        disableSyncWithStore,
+        finalStoreKey,
+        getItem,
+        setItem,
+        setStore,
+        storeKeys,
+    ]);
+    return [ids, selectionModifiers];
+};
+const defaultIds = [];
+const defaultStoreKeys = [];

package/dist/ra-core/src/controller/list/useSavedQueries.d.ts

@@ -0,0 +1,14 @@
+import { SortPayload } from '../../types';
+export declare const useSavedQueries: (resource: string) => [SavedQuery[], (value: SavedQuery[] | ((value: SavedQuery[]) => void), defaultValue?: SavedQuery[] | undefined) => void];
+export interface SavedQuery {
+    label: string;
+    value: {
+        filter?: any;
+        displayedFilters?: any[];
+        sort?: SortPayload;
+        perPage?: number;
+    };
+}
+export declare const extractValidSavedQueries: (savedQueries: SavedQuery[]) => SavedQuery[];
+export declare const areValidSavedQueries: (savedQueries: SavedQuery[]) => true | undefined;
+export declare const isValidSavedQuery: (savedQuery: SavedQuery) => boolean;

package/dist/ra-core/src/controller/list/useSavedQueries.js

@@ -0,0 +1,29 @@
+import { useStore } from '../../store/useStore';
+export const useSavedQueries = (resource) => {
+    return useStore(`${resource}.savedQueries`, []);
+};
+export const extractValidSavedQueries = (savedQueries) => {
+    if (Array.isArray(savedQueries)) {
+        return savedQueries.filter(query => isValidSavedQuery(query));
+    }
+    return [];
+};
+export const areValidSavedQueries = (savedQueries) => {
+    if (Array.isArray(savedQueries) &&
+        savedQueries.every(query => isValidSavedQuery(query))) {
+        return true;
+    }
+};
+export const isValidSavedQuery = (savedQuery) => {
+    if (savedQuery.label &&
+        typeof savedQuery.label === 'string' &&
+        savedQuery.value &&
+        typeof Array.isArray(savedQuery.value.displayedFilters) &&
+        typeof savedQuery.value.perPage === 'number' &&
+        typeof savedQuery.value.sort?.field === 'string' &&
+        typeof savedQuery.value.sort?.order === 'string' &&
+        typeof savedQuery.value.filter === 'object') {
+        return true;
+    }
+    return false;
+};

package/dist/ra-core/src/controller/list/useSelectAll.d.ts

@@ -0,0 +1,48 @@
+import { UseGetListOptions } from '../../dataProvider';
+import type { FilterPayload, RaRecord, SortPayload } from '../../types';
+/**
+ * Get a callback to select all records of a resource (capped by the limit parameter)
+ *
+ * @param {Object} params The hook parameters { resource, sort, filter }
+ * @returns {Function} handleSelectAll A function to select all items of a list
+ *
+ * @example
+ * import { List, Datagrid, BulkActionsToolbar, BulkDeleteButton, useListContext, useSelectAll } from 'react-admin';
+ *
+ * const MySelectAllButton = () => {
+ *   const { sort, filter } = useListContext();
+ *   const handleSelectAll = useSelectAll({ resource: 'posts', sort, filter });
+ *   const handleClick = () => handleSelectAll({
+ *       queryOptions: { meta: { foo: 'bar' } },
+ *       limit: 250,
+ *   });
+ *   return <button onClick={handleClick}>Select All</button>;
+ * };
+ *
+ * const PostBulkActionsToolbar = () => (
+ *     <BulkActionsToolbar actions={<MySelectAllButton/>}>
+ *         <BulkDeleteButton />
+ *     </BulkActionsToolbar>
+ * );
+ *
+ * export const PostList = () => (
+ *     <List>
+ *         <Datagrid bulkActionsToolbar={<PostBulkActionsToolbar />}>
+ *             ...
+ *         </Datagrid>
+ *     </List>
+ * );
+ */
+export declare const useSelectAll: (params: UseSelectAllParams) => UseSelectAllResult;
+export interface UseSelectAllParams {
+    resource?: string;
+    sort?: SortPayload;
+    filter?: FilterPayload;
+    storeKey?: string;
+    disableSyncWithStore?: boolean;
+}
+export interface HandleSelectAllParams<RecordType extends RaRecord = any> {
+    limit?: number;
+    queryOptions?: UseGetListOptions<RecordType>;
+}
+export type UseSelectAllResult = (options?: HandleSelectAllParams) => void;