@strato-admin/core 0.1.1 → 0.3.0

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

@@ -0,0 +1,55 @@
+import { Exporter, FilterPayload, RaRecord, SortPayload } from '../../types';
+import { ListControllerResult } from './useListController';
+/**
+ * Handle filtering, sorting and pagination on local data.
+ *
+ * Returns the data and callbacks expected by <ListContext>.
+ *
+ * @example
+ * const data = [
+ *     { id: 1, name: 'Arnold' },
+ *     { id: 2, name: 'Sylvester' },
+ *     { id: 3, name: 'Jean-Claude' },
+ * ]
+ *
+ * const MyComponent = () => {
+ *     const listContext = useList({ data });
+ *     return (
+ *         <ListContextProvider value={listContext}>
+ *             <Datagrid>
+ *                 <TextField source="id" />
+ *                 <TextField source="name" />
+ *             </Datagrid>
+ *         </ListContextProvider>
+ *     );
+ * };
+ *
+ * @param {UseListOptions} props
+ * @param {RaRecord[]} props.data An array of records
+ * @param {Boolean} props.isFetching: Optional. A boolean indicating whether the data is being loaded
+ * @param {Boolean} props.isLoading: Optional. A boolean indicating whether the data has been loaded at least once
+ * @param {Error | String} props.error: Optional. The error if any occurred while loading the data
+ * @param {Object} props.filter: Optional. An object containing the filters applied on the data
+ * @param {Number} props.page: Optional. The initial page index
+ * @param {Number} props.perPage: Optional. The initial page size
+ * @param {SortPayload} props.sort: Optional. The initial sort (field and order)
+ * @param {filterCallback} prop.filterCallback Optional. A function that allows you to make a custom filter
+ */
+export declare const useList: <RecordType extends RaRecord = any, ErrorType = Error>(props: UseListOptions<RecordType, ErrorType>) => UseListValue<RecordType, ErrorType>;
+export interface UseListOptions<RecordType extends RaRecord = any, ErrorType = Error> {
+    data?: RecordType[];
+    error?: ErrorType | null;
+    filter?: FilterPayload;
+    isFetching?: boolean;
+    isLoading?: boolean;
+    isPaused?: boolean;
+    isPending?: boolean;
+    isPlaceholderData?: boolean;
+    page?: number;
+    perPage?: number;
+    sort?: SortPayload;
+    resource?: string;
+    filterCallback?: (record: RecordType) => boolean;
+    exporter?: Exporter<RecordType> | false;
+}
+export type UseListValue<RecordType extends RaRecord = any, ErrorType = Error> = ListControllerResult<RecordType, ErrorType>;

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

@@ -0,0 +1,223 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import get from 'lodash/get.js';
+import isEqual from 'lodash/isEqual.js';
+import { removeEmpty } from '../../util';
+import { useResourceContext } from '../../core';
+import usePaginationState from '../usePaginationState';
+import useSortState from '../useSortState';
+import { useRecordSelection } from './useRecordSelection';
+import { flattenObject } from '../../dataProvider/fetch';
+import { defaultExporter } from '../../export';
+const refetch = () => {
+    throw new Error('refetch is not available for a ListContext built from useList based on local data');
+};
+/**
+ * Handle filtering, sorting and pagination on local data.
+ *
+ * Returns the data and callbacks expected by <ListContext>.
+ *
+ * @example
+ * const data = [
+ *     { id: 1, name: 'Arnold' },
+ *     { id: 2, name: 'Sylvester' },
+ *     { id: 3, name: 'Jean-Claude' },
+ * ]
+ *
+ * const MyComponent = () => {
+ *     const listContext = useList({ data });
+ *     return (
+ *         <ListContextProvider value={listContext}>
+ *             <Datagrid>
+ *                 <TextField source="id" />
+ *                 <TextField source="name" />
+ *             </Datagrid>
+ *         </ListContextProvider>
+ *     );
+ * };
+ *
+ * @param {UseListOptions} props
+ * @param {RaRecord[]} props.data An array of records
+ * @param {Boolean} props.isFetching: Optional. A boolean indicating whether the data is being loaded
+ * @param {Boolean} props.isLoading: Optional. A boolean indicating whether the data has been loaded at least once
+ * @param {Error | String} props.error: Optional. The error if any occurred while loading the data
+ * @param {Object} props.filter: Optional. An object containing the filters applied on the data
+ * @param {Number} props.page: Optional. The initial page index
+ * @param {Number} props.perPage: Optional. The initial page size
+ * @param {SortPayload} props.sort: Optional. The initial sort (field and order)
+ * @param {filterCallback} prop.filterCallback Optional. A function that allows you to make a custom filter
+ */
+export const useList = (props) => {
+    const { data, error, filter = defaultFilter, isFetching = false, isLoading = false, isPaused = false, isPending = false, isPlaceholderData = false, page: initialPage = 1, perPage: initialPerPage = 1000, sort: initialSort, filterCallback = defaultFilterCallback, exporter = defaultExporter, } = props;
+    const resource = useResourceContext(props);
+    const [finalItems, setFinalItems] = useState(() => ({
+        data,
+        total: data ? data.length : undefined,
+    }));
+    // pagination logic
+    const { page, setPage, perPage, setPerPage } = usePaginationState({
+        page: initialPage,
+        perPage: initialPerPage,
+    });
+    // sort logic
+    const { sort, setSort: setSortState } = useSortState(initialSort);
+    const setSort = useCallback((sort) => {
+        setSortState(sort);
+        setPage(1);
+    }, [setPage, setSortState]);
+    // selection logic
+    const [selectedIds, selectionModifiers] = useRecordSelection(resource
+        ? {
+            resource,
+        }
+        : { disableSyncWithStore: true });
+    const onUnselectItems = useCallback((fromAllStoreKeys) => {
+        return selectionModifiers.unselect(selectedIds, fromAllStoreKeys);
+    }, [selectedIds, selectionModifiers]);
+    // filter logic
+    const filterRef = useRef(filter);
+    const [displayedFilters, setDisplayedFilters] = useState({});
+    const [filterValues, setFilterValues] = useState(filter);
+    const hideFilter = useCallback((filterName) => {
+        setDisplayedFilters(previousState => {
+            const { [filterName]: _, ...newState } = previousState;
+            return newState;
+        });
+        setFilterValues(previousState => {
+            const { [filterName]: _, ...newState } = previousState;
+            return newState;
+        });
+    }, [setDisplayedFilters, setFilterValues]);
+    const showFilter = useCallback((filterName, defaultValue) => {
+        setDisplayedFilters(previousState => ({
+            ...previousState,
+            [filterName]: true,
+        }));
+        setFilterValues(previousState => removeEmpty({
+            ...previousState,
+            [filterName]: defaultValue,
+        }));
+    }, [setDisplayedFilters, setFilterValues]);
+    const setFilters = useCallback((filters, displayedFilters = undefined) => {
+        setFilterValues(removeEmpty(filters));
+        if (displayedFilters) {
+            setDisplayedFilters(displayedFilters);
+        }
+        setPage(1);
+    }, [setDisplayedFilters, setFilterValues, setPage]);
+    // handle filter prop change
+    useEffect(() => {
+        if (!isEqual(filter, filterRef.current)) {
+            filterRef.current = filter;
+            setFilterValues(filter);
+        }
+    }, [filter]);
+    const applyFilterAndSort = useCallback((records) => {
+        let tempData = records;
+        if (filterValues) {
+            const flattenFilterValues = flattenObject(filterValues);
+            tempData = records
+                .filter(record => Object.entries(flattenFilterValues).every(([filterName, filterValue]) => {
+                const recordValue = get(record, filterName);
+                const result = Array.isArray(recordValue)
+                    ? Array.isArray(filterValue)
+                        ? recordValue.some(item => filterValue.includes(item))
+                        : recordValue.includes(filterValue)
+                    : Array.isArray(filterValue)
+                        ? filterValue.includes(recordValue)
+                        : filterName === 'q' // special full-text filter
+                            ? Object.keys(record).some(key => typeof record[key] ===
+                                'string' &&
+                                record[key]
+                                    .toLowerCase()
+                                    .includes(filterValue.toLowerCase()))
+                            : filterValue == recordValue; // eslint-disable-line eqeqeq
+                return result;
+            }))
+                .filter(filterCallback);
+        }
+        if (sort.field) {
+            tempData = tempData.sort((a, b) => {
+                if (get(a, sort.field) > get(b, sort.field)) {
+                    return sort.order === 'ASC' ? 1 : -1;
+                }
+                if (get(a, sort.field) < get(b, sort.field)) {
+                    return sort.order === 'ASC' ? -1 : 1;
+                }
+                return 0;
+            });
+        }
+        return tempData;
+    }, [filterValues, filterCallback, sort.field, sort.order]);
+    // We do all the data processing (filtering, sorting, paginating) client-side
+    useEffect(() => {
+        if (isPending || !data)
+            return;
+        const filteredAndSorted = applyFilterAndSort(data);
+        const filteredLength = filteredAndSorted.length;
+        const paginatedData = filteredAndSorted.slice((page - 1) * perPage, page * perPage);
+        setFinalItems({
+            data: paginatedData,
+            total: filteredLength,
+        });
+    }, // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        JSON.stringify(data),
+        applyFilterAndSort,
+        isPending,
+        page,
+        perPage,
+        setFinalItems,
+    ]);
+    const onSelectAll = useCallback(() => {
+        const allIds = data?.map(({ id }) => id) || [];
+        selectionModifiers.select(allIds);
+    }, [data, selectionModifiers]);
+    const getData = useCallback(async ({ maxResults } = {}) => {
+        if (isPending || !data) {
+            return [];
+        }
+        const filteredAndSorted = applyFilterAndSort(data);
+        if (maxResults != null) {
+            return filteredAndSorted.slice(0, maxResults);
+        }
+        return filteredAndSorted;
+    }, [applyFilterAndSort, data, isPending]);
+    return {
+        sort,
+        data: isPending ? undefined : finalItems?.data ?? [],
+        defaultTitle: '',
+        error: error ?? null,
+        displayedFilters,
+        exporter,
+        filterValues,
+        hasNextPage: finalItems?.total == null
+            ? false
+            : page * perPage < finalItems.total,
+        hasPreviousPage: page > 1,
+        hideFilter,
+        isFetching,
+        isLoading,
+        isPaused,
+        isPending,
+        isPlaceholderData,
+        onSelect: selectionModifiers.select,
+        onSelectAll,
+        onToggleItem: selectionModifiers.toggle,
+        onUnselectItems,
+        page,
+        perPage,
+        resource: '',
+        refetch,
+        selectedIds,
+        setFilters,
+        setPage,
+        setPerPage,
+        setSort,
+        showFilter,
+        total: finalItems?.total,
+        getData,
+    };
+};
+const defaultFilter = {};
+const defaultFilterCallback = (record) => Boolean(record);

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

@@ -0,0 +1,59 @@
+import { ListControllerResult } from './useListController';
+import { RaRecord } from '../../types';
+/**
+ * Hook to read the list controller props from the ListContext.
+ *
+ * Used within a <ListContextProvider> (e.g. as a descendent of <List>).
+ *
+ * @returns {ListControllerResult} list controller props
+ *
+ * @see useListController for how it is filled
+ *
+ * @example // custom list view
+ *
+ * import { useListContext } from 'react-admin';
+ *
+ * const MyList = () => {
+ *     const { data, isPending } = useListContext();
+ *     if (isPending) {
+ *         return <>Loading...</>;
+ *     }
+ *     return (
+ *         <ul>
+ *             {data.map(record => (
+ *                 <li key={record.id}>{record.name}</li>
+ *             ))}
+ *         </ul>
+ *     );
+ * }
+ *
+ * @example // custom pagination
+ *
+ * import { useListContext } from 'react-admin';
+ * import { Button, Toolbar } from '@mui/material';
+ * import ChevronLeft from '@mui/icons-material/ChevronLeft';
+ * import ChevronRight from '@mui/icons-material/ChevronRight';
+ *
+ * const PrevNextPagination = () => {
+ *     const { page, perPage, total, setPage } = useListContext();
+ *     const nbPages = Math.ceil(total / perPage) || 1;
+ *     return (
+ *         nbPages > 1 &&
+ *             <Toolbar>
+ *                 {page > 1 &&
+ *                     <Button color="primary" key="prev" onClick={() => setPage(page - 1)}>
+ *                         <ChevronLeft />
+ *                         Prev
+ *                     </Button>
+ *                 }
+ *                 {page !== nbPages &&
+ *                     <Button color="primary" key="next" onClick={() => setPage(page + 1)}>
+ *                         Next
+ *                         <ChevronRight />
+ *                     </Button>
+ *                 }
+ *             </Toolbar>
+ *     );
+ * }
+ */
+export declare const useListContext: <RecordType extends RaRecord = any, ErrorType = Error>() => ListControllerResult<RecordType, ErrorType>;

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

@@ -0,0 +1,65 @@
+import { useContext } from 'react';
+import { ListContext } from './ListContext';
+/**
+ * Hook to read the list controller props from the ListContext.
+ *
+ * Used within a <ListContextProvider> (e.g. as a descendent of <List>).
+ *
+ * @returns {ListControllerResult} list controller props
+ *
+ * @see useListController for how it is filled
+ *
+ * @example // custom list view
+ *
+ * import { useListContext } from 'react-admin';
+ *
+ * const MyList = () => {
+ *     const { data, isPending } = useListContext();
+ *     if (isPending) {
+ *         return <>Loading...</>;
+ *     }
+ *     return (
+ *         <ul>
+ *             {data.map(record => (
+ *                 <li key={record.id}>{record.name}</li>
+ *             ))}
+ *         </ul>
+ *     );
+ * }
+ *
+ * @example // custom pagination
+ *
+ * import { useListContext } from 'react-admin';
+ * import { Button, Toolbar } from '@mui/material';
+ * import ChevronLeft from '@mui/icons-material/ChevronLeft';
+ * import ChevronRight from '@mui/icons-material/ChevronRight';
+ *
+ * const PrevNextPagination = () => {
+ *     const { page, perPage, total, setPage } = useListContext();
+ *     const nbPages = Math.ceil(total / perPage) || 1;
+ *     return (
+ *         nbPages > 1 &&
+ *             <Toolbar>
+ *                 {page > 1 &&
+ *                     <Button color="primary" key="prev" onClick={() => setPage(page - 1)}>
+ *                         <ChevronLeft />
+ *                         Prev
+ *                     </Button>
+ *                 }
+ *                 {page !== nbPages &&
+ *                     <Button color="primary" key="next" onClick={() => setPage(page + 1)}>
+ *                         Next
+ *                         <ChevronRight />
+ *                     </Button>
+ *                 }
+ *             </Toolbar>
+ *     );
+ * }
+ */
+export const useListContext = () => {
+    const context = useContext(ListContext);
+    if (!context) {
+        throw new Error('useListContext must be used inside a ListContextProvider');
+    }
+    return context;
+};

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

@@ -0,0 +1,44 @@
+import { ListControllerResult } from './useListController';
+import { RaRecord } from '../../types';
+/**
+ * Hook to read the list controller props from the ListContext.
+ *
+ * Mostly used within a <ListContext.Provider> (e.g. as a descendent of <List>
+ * or <ListBase>).
+ *
+ * But you can also use it without a <ListContext.Provider>. In this case, it is up to you
+ * to pass all the necessary props (see the list below).
+ *
+ * The given props will take precedence over context values.
+ *
+ * @typedef {Object} ListControllerProps
+ * @prop {Object}   data an array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }]
+ * @prop {integer}  total the total number of results for the current filters, excluding pagination. Useful to build the pagination controls. e.g. 23
+ * @prop {boolean}  isFetching boolean that is true on mount, and false once the data was fetched
+ * @prop {boolean}  isLoading boolean that is false until the data is available
+ * @prop {integer}  page the current page. Starts at 1
+ * @prop {Function} setPage a callback to change the page, e.g. setPage(3)
+ * @prop {integer}  perPage the number of results per page. Defaults to 25
+ * @prop {Function} setPerPage a callback to change the number of results per page, e.g. setPerPage(25)
+ * @prop {Object}   sort a sort object { field, order }, e.g. { field: 'date', order: 'DESC' }
+ * @prop {Function} setSort a callback to change the sort, e.g. setSort({ field : 'name', order: 'ASC' })
+ * @prop {Object}   filterValues a dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' }
+ * @prop {Function} setFilters a callback to update the filters, e.g. setFilters(filters, displayedFilters)
+ * @prop {Object}   displayedFilters a dictionary of the displayed filters, e.g. { title: true, nationality: true }
+ * @prop {Function} showFilter a callback to show one of the filters, e.g. showFilter('title', defaultValue)
+ * @prop {Function} hideFilter a callback to hide one of the filters, e.g. hideFilter('title')
+ * @prop {Array}    selectedIds an array listing the ids of the selected rows, e.g. [123, 456]
+ * @prop {Function} onSelect callback to change the list of selected rows, e.g. onSelect([456, 789])
+ * @prop {Function} onSelectAll callback to select all the records, e.g. onSelectAll({ limit: 50, queryOptions: { meta: { foo: 'bar' } } })
+ * @prop {Function} onToggleItem callback to toggle the selection of a given record based on its id, e.g. onToggleItem(456)
+ * @prop {Function} onUnselectItems callback to clear the selection, e.g. onUnselectItems();
+ * @prop {string}   defaultTitle the translated title based on the resource, e.g. 'Posts'
+ * @prop {string}   resource the resource name, deduced from the location. e.g. 'posts'
+ *
+ * @param {ListControllerProps} props Props passed to the useListContext hook
+ *
+ * @returns {ListControllerResult} list controller props
+ *
+ * @see useListController for how it is filled
+ */
+export declare const useListContextWithProps: <RecordType extends RaRecord = any>(props?: any) => Partial<ListControllerResult<RecordType>>;

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

@@ -0,0 +1,84 @@
+import { useContext, useMemo } from 'react';
+import defaults from 'lodash/defaults.js';
+import { ListContext } from './ListContext';
+/**
+ * Hook to read the list controller props from the ListContext.
+ *
+ * Mostly used within a <ListContext.Provider> (e.g. as a descendent of <List>
+ * or <ListBase>).
+ *
+ * But you can also use it without a <ListContext.Provider>. In this case, it is up to you
+ * to pass all the necessary props (see the list below).
+ *
+ * The given props will take precedence over context values.
+ *
+ * @typedef {Object} ListControllerProps
+ * @prop {Object}   data an array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }]
+ * @prop {integer}  total the total number of results for the current filters, excluding pagination. Useful to build the pagination controls. e.g. 23
+ * @prop {boolean}  isFetching boolean that is true on mount, and false once the data was fetched
+ * @prop {boolean}  isLoading boolean that is false until the data is available
+ * @prop {integer}  page the current page. Starts at 1
+ * @prop {Function} setPage a callback to change the page, e.g. setPage(3)
+ * @prop {integer}  perPage the number of results per page. Defaults to 25
+ * @prop {Function} setPerPage a callback to change the number of results per page, e.g. setPerPage(25)
+ * @prop {Object}   sort a sort object { field, order }, e.g. { field: 'date', order: 'DESC' }
+ * @prop {Function} setSort a callback to change the sort, e.g. setSort({ field : 'name', order: 'ASC' })
+ * @prop {Object}   filterValues a dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' }
+ * @prop {Function} setFilters a callback to update the filters, e.g. setFilters(filters, displayedFilters)
+ * @prop {Object}   displayedFilters a dictionary of the displayed filters, e.g. { title: true, nationality: true }
+ * @prop {Function} showFilter a callback to show one of the filters, e.g. showFilter('title', defaultValue)
+ * @prop {Function} hideFilter a callback to hide one of the filters, e.g. hideFilter('title')
+ * @prop {Array}    selectedIds an array listing the ids of the selected rows, e.g. [123, 456]
+ * @prop {Function} onSelect callback to change the list of selected rows, e.g. onSelect([456, 789])
+ * @prop {Function} onSelectAll callback to select all the records, e.g. onSelectAll({ limit: 50, queryOptions: { meta: { foo: 'bar' } } })
+ * @prop {Function} onToggleItem callback to toggle the selection of a given record based on its id, e.g. onToggleItem(456)
+ * @prop {Function} onUnselectItems callback to clear the selection, e.g. onUnselectItems();
+ * @prop {string}   defaultTitle the translated title based on the resource, e.g. 'Posts'
+ * @prop {string}   resource the resource name, deduced from the location. e.g. 'posts'
+ *
+ * @param {ListControllerProps} props Props passed to the useListContext hook
+ *
+ * @returns {ListControllerResult} list controller props
+ *
+ * @see useListController for how it is filled
+ */
+export const useListContextWithProps = (props) => {
+    const context = useContext(ListContext);
+    // Props take precedence over the context
+    return useMemo(() => defaults({}, props != null ? extractListContextProps(props) : {}, context), [context, props]);
+};
+/**
+ * Extract only the list controller props
+ *
+ * @param {Object} props Props passed to the useListContext hook
+ *
+ * @returns {ListControllerResult} List controller props
+ */
+const extractListContextProps = ({ sort, data, defaultTitle, displayedFilters, exporter, filterValues, hasCreate, hideFilter, isFetching, isLoading, isPending, onSelect, onSelectAll, onToggleItem, onUnselectItems, page, perPage, refetch, resource, selectedIds, setFilters, setPage, setPerPage, setSort, showFilter, total, }) => ({
+    sort,
+    data,
+    defaultTitle,
+    displayedFilters,
+    exporter,
+    filterValues,
+    hasCreate,
+    hideFilter,
+    isFetching,
+    isLoading,
+    isPending,
+    onSelect,
+    onSelectAll,
+    onToggleItem,
+    onUnselectItems,
+    page,
+    perPage,
+    refetch,
+    resource,
+    selectedIds,
+    setFilters,
+    setPage,
+    setPerPage,
+    setSort,
+    showFilter,
+    total,
+});