Simplify the development of custom List views

packages/ra-core/src/controller/ListContext.tsx

@@ -0,0 +1,54 @@
+import { createContext } from 'react';
+import { ListControllerProps } from './useListController';
+
+/**
+ * Context to store the result of the useListController() hook.
+ *
+ * Use the useListContext() hook to read the context.
+ *
+ * @see useListController
+ * @see useListContext
+ *
+ * @example
+ *
+ * import { useListController, ListContext } from 'ra-core';
+ *
+ * const List = props => {
+ *     const controllerProps = useListController(props);
+ *     return (
+ *         <ListContext.Provider value={controllerProps}>
+ *             ...
+ *         </ListContext.Provider>
+ *     );
+ * };
+ */
+const ListContext = createContext<ListControllerProps>({
+    basePath: null,
+    currentSort: null,
+    data: null,
+    defaultTitle: null,
+    displayedFilters: null,
+    filterValues: null,
+    hasCreate: null,
+    hideFilter: null,
+    ids: null,
+    loaded: null,
+    loading: null,
+    onSelect: null,
+    onToggleItem: null,
+    onUnselectItems: null,
+    page: null,
+    perPage: null,
+    resource: null,
+    selectedIds: null,
+    setFilters: null,
+    setPage: null,
+    setPerPage: null,
+    setSort: null,
+    showFilter: null,
+    total: null,
+});
+
+ListContext.displayName = 'ListContext';
+
+export default ListContext;

packages/ra-core/src/controller/field/ReferenceManyFieldController.tsx

@@ -6,13 +6,13 @@ import useSortState from '../useSortState';
 import usePaginationState from '../usePaginationState';
 
 interface ChildrenFuncParams {
+    basePath: string;
     currentSort: Sort;
     data: RecordMap;
     ids: Identifier[];
     loaded: boolean;
     page: number;
     perPage: number;
-    referenceBasePath: string;
     setPage: (page: number) => void;
     setPerPage: (perPage: number) => void;
     setSort: (field: string) => void;
@@ -60,7 +60,7 @@ export const ReferenceManyFieldController: FunctionComponent<Props> = ({
         data,
         ids,
         loaded,
-        referenceBasePath,
+        basePath: referenceBasePath,
         total,
     } = useReferenceManyFieldController({
         resource,
@@ -82,7 +82,7 @@ export const ReferenceManyFieldController: FunctionComponent<Props> = ({
         loaded,
         page,
         perPage,
-        referenceBasePath,
+        basePath: referenceBasePath,
         setPage,
         setPerPage,
         setSort: setSortField,

packages/ra-core/src/controller/field/useReferenceManyFieldController.ts

@@ -1,8 +1,10 @@
 import get from 'lodash/get';
+import { useCallback } from 'react';
 
-import { Record, Sort, RecordMap, Identifier } from '../../types';
+import { useSafeSetState, removeEmpty } from '../../util';
 import { useGetManyReference } from '../../dataProvider';
 import { useNotify } from '../../sideEffect';
+import { Record, Sort, RecordMap, Identifier } from '../../types';
 
 /**
  * @typedef ReferenceManyProps
@@ -13,12 +15,30 @@ import { useNotify } from '../../sideEffect';
  * @property {string | false} referenceBasePath base path of the related record
  * @property {number} total records
  */
-export interface ReferenceManyProps {
-    data: RecordMap;
+export interface ReferenceManyProps<RecordType = Record> {
+    basePath: string;
+    currentSort: Sort;
+    data: RecordMap<RecordType>;
+    defaultTitle: string;
+    displayedFilters: any;
+    filterValues: any;
+    hasCreate: boolean;
+    hideFilter: (filterName: string) => void;
     ids: Identifier[];
-    loaded: boolean;
     loading: boolean;
-    referenceBasePath: string;
+    loaded: boolean;
+    onSelect: (ids: Identifier[]) => void;
+    onToggleItem: (id: Identifier) => void;
+    onUnselectItems: () => void;
+    page: number;
+    perPage: number;
+    resource: string;
+    selectedIds: Identifier[];
+    setFilters: (filters: any, displayedFilters: any) => void;
+    setPage: (page: number) => void;
+    setPerPage: (page: number) => void;
+    setSort: (sort: string, order?: string) => void;
+    showFilter: (filterName: string, defaultValue: any) => void;
     total: number;
 }
 
@@ -84,12 +104,105 @@ const useReferenceManyFieldController = ({
     filter = defaultFilter,
     source,
     basePath,
-    page,
-    perPage,
-    sort = { field: 'id', order: 'DESC' },
+    page: initialPage,
+    perPage: initialPerPage,
+    sort: initialSort = { field: 'id', order: 'DESC' },
 }: Options): ReferenceManyProps => {
-    const referenceId = get(record, source);
     const notify = useNotify();
+
+    // pagination logic
+    const [page, setPage] = useSafeSetState<number>(initialPage);
+    const [perPage, setPerPage] = useSafeSetState<number>(initialPerPage);
+
+    // sort logic
+    const [sort, setSortObject] = useSafeSetState<Sort>(initialSort);
+    const setSort = useCallback(
+        (field: string, order: string = 'ASC') => {
+            setSortObject(previousState => ({
+                field,
+                order:
+                    field === previousState.field
+                        ? previousState.order === 'ASC'
+                            ? 'DESC'
+                            : 'ASC'
+                        : order,
+            }));
+            setPage(1);
+        },
+        [setPage, setSortObject]
+    );
+
+    // selection logic
+    const [selectedIds, setSelectedIds] = useSafeSetState<Identifier[]>([]);
+    const onSelect = useCallback(
+        (newIds: Identifier[]) => {
+            setSelectedIds(newIds);
+        },
+        [setSelectedIds]
+    );
+    const onToggleItem = useCallback(
+        (id: Identifier) => {
+            setSelectedIds(previousState => {
+                const index = previousState.indexOf(id);
+                if (index > -1) {
+                    return [
+                        ...previousState.slice(0, index),
+                        ...previousState.slice(index + 1),
+                    ];
+                } else {
+                    return [...previousState, id];
+                }
+            });
+        },
+        [setSelectedIds]
+    );
+    const onUnselectItems = useCallback(() => {
+        setSelectedIds([]);
+    }, [setSelectedIds]);
+
+    // filter logic
+    const [displayedFilters, setDisplayedFilters] = useSafeSetState<{
+        [key: string]: boolean;
+    }>({});
+    const [filterValues, setFilterValues] = useSafeSetState<{
+        [key: string]: any;
+    }>(filter);
+    const hideFilter = useCallback(
+        (filterName: string) => {
+            setDisplayedFilters(previousState => {
+                const { [filterName]: _, ...newState } = previousState;
+                return newState;
+            });
+            setFilterValues(previousState => {
+                const { [filterName]: _, ...newState } = previousState;
+                return newState;
+            });
+        },
+        [setDisplayedFilters, setFilterValues]
+    );
+    const showFilter = useCallback(
+        (filterName: string, defaultValue: any) => {
+            setDisplayedFilters(previousState => ({
+                previousState,
+                [filterName]: true,
+            }));
+            setFilterValues(previousState => ({
+                previousState,
+                [filterName]: defaultValue,
+            }));
+        },
+        [setDisplayedFilters, setFilterValues]
+    );
+    const setFilters = useCallback(
+        (filters, displayedFilters) => {
+            setFilterValues(removeEmpty(filters));
+            setDisplayedFilters(displayedFilters);
+            setPage(1);
+        },
+        [setDisplayedFilters, setFilterValues, setPage]
+    );
+
+    const referenceId = get(record, source);
     const { data, ids, total, loading, loaded } = useGetManyReference(
         reference,
         target,
@@ -109,14 +222,30 @@ const useReferenceManyFieldController = ({
         }
     );
 
-    const referenceBasePath = basePath.replace(resource, reference);
-
     return {
+        basePath: basePath.replace(resource, reference),
+        currentSort: sort,
         data,
+        defaultTitle: null,
+        displayedFilters,
+        filterValues,
+        hasCreate: false,
+        hideFilter,
         ids,
         loaded,
         loading,
-        referenceBasePath,
+        onSelect,
+        onToggleItem,
+        onUnselectItems,
+        page,
+        perPage,
+        resource,
+        selectedIds,
+        setFilters,
+        setPage,
+        setPerPage,
+        setSort,
+        showFilter,
         total,
     };
 };

packages/ra-core/src/controller/index.ts

@@ -1,6 +1,7 @@
 import CreateController from './CreateController';
 import EditController from './EditController';
 import ListController from './ListController';
+import ListContext from './ListContext';
 import ShowController from './ShowController';
 import useRecordSelection from './useRecordSelection';
 import useVersion from './useVersion';
@@ -13,6 +14,7 @@ import useListController, {
     sanitizeListRestProps,
     ListControllerProps,
 } from './useListController';
+import useListContext from './useListContext';
 import useEditController, { EditControllerProps } from './useEditController';
 import useCreateController, {
     CreateControllerProps,
@@ -27,6 +29,7 @@ export {
     CreateController,
     EditController,
     ListController,
+    ListContext,
     ShowController,
     useCheckMinimumRequiredProps,
     useListController,
@@ -40,6 +43,7 @@ export {
     useSortState,
     usePaginationState,
     useReference,
+    useListContext,
     useListParams,
     ListControllerProps,
     EditControllerProps,

packages/ra-core/src/controller/useListContext.ts

@@ -0,0 +1,20 @@
+import { useContext } from 'react';
+
+import ListContext from './ListContext';
+
+/**
+ * Hook to read the list controller props.
+ *
+ * Must be used within a <ListContext.Provider>
+ */
+const useListContext = () => {
+    const context = useContext(ListContext);
+    if (!context.basePath) {
+        throw new Error(
+            'This component must be used inside a <ListContext.Provider>'
+        );
+    }
+    return context;
+};
+
+export default useListContext;

packages/ra-core/src/controller/useListController.ts

@@ -11,7 +11,7 @@ import useRecordSelection from './useRecordSelection';
 import useVersion from './useVersion';
 import { useTranslate } from '../i18n';
 import { SORT_ASC } from '../reducer/admin/resource/list/queryReducer';
-import { CRUD_GET_LIST, ListParams } from '../actions';
+import { CRUD_GET_LIST } from '../actions';
 import { useNotify } from '../sideEffect';
 import { Sort, RecordMap, Identifier, ReduxState, Record } from '../types';
 import useGetList from '../dataProvider/useGetList';
@@ -21,20 +21,18 @@ export interface ListProps {
     filter?: object;
     filters?: ReactElement<any>;
     filterDefaultValues?: object;
-    pagination?: ReactElement<any>;
     perPage?: number;
     sort?: Sort;
     // the props managed by react-admin
-    basePath: string;
+    basePath?: string;
     debounce?: number;
     hasCreate?: boolean;
     hasEdit?: boolean;
     hasList?: boolean;
     hasShow?: boolean;
     location?: Location;
     path?: string;
-    query: ListParams;
-    resource: string;
+    resource?: string;
     [key: string]: any;
 }
 
@@ -70,7 +68,6 @@ export interface ListControllerProps<RecordType = Record> {
     setSort: (sort: string, order?: string) => void;
     showFilter: (filterName: string, defaultValue: any) => void;
     total: number;
-    version: number;
 }
 
 /**
@@ -115,7 +112,6 @@ const useListController = <RecordType = Record>(
     const location = useLocation();
     const translate = useTranslate();
     const notify = useNotify();
-    const version = useVersion();
 
     const [query, queryModifiers] = useListParams({
         resource,
@@ -225,7 +221,6 @@ const useListController = <RecordType = Record>(
         setSort: queryModifiers.setSort,
         showFilter: queryModifiers.showFilter,
         total: typeof total === 'undefined' ? defaultTotal : total,
-        version,
     };
 };
 

packages/ra-core/src/export/ExporterContext.ts

@@ -3,7 +3,7 @@ import { createContext } from 'react';
 import { Exporter } from '../types';
 import defaultExporter from './defaultExporter';
 
-const ExporterContext = createContext<Exporter>(defaultExporter);
+const ExporterContext = createContext<Exporter | false>(defaultExporter);
 
 ExporterContext.displayName = 'ExporterContext';