@strato-admin/core 0.1.0 → 0.3.0

package/dist/ra-core/src/controller/field/useReferenceManyFieldController.js

@@ -0,0 +1,264 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import get from 'lodash/get.js';
+import isEqual from 'lodash/isEqual.js';
+import lodashDebounce from 'lodash/debounce.js';
+import { removeEmpty, useEvent } from '../../util';
+import { useDataProvider, useGetManyReference } from '../../dataProvider';
+import { useNotify } from '../../notification';
+import { DEFAULT_MAX_RESULTS } from '../list/useListController';
+import usePaginationState from '../usePaginationState';
+import { useRecordSelection } from '../list/useRecordSelection';
+import useSortState from '../useSortState';
+import { useResourceContext, useGetResourceLabel } from '../../core';
+import { useRecordContext } from '../record';
+import { defaultExporter } from '../../export';
+import { useTranslate } from '../../i18n';
+/**
+ * Fetch reference records, and return them when available
+ *
+ * Uses dataProvider.getManyReference() internally.
+ *
+ * @example // fetch the comments related to the current post
+ * const { isPending, data } = useReferenceManyFieldController({
+ *     reference: 'comments',
+ *     target: 'post_id',
+ *     record: { id: 123, title: 'hello, world' },
+ *     resource: 'posts',
+ * });
+ *
+ * @param {Object} props
+ * @param {string} props.reference The linked resource name. Required.
+ * @param {string} props.target The target resource key. Required.
+ * @param {Object} props.filter The filter applied on the recorded records list
+ * @param {number} props.page the page number
+ * @param {number} props.perPage the number of item per page
+ * @param {Object} props.record The current resource record
+ * @param {string} props.resource The current resource name
+ * @param {Object} props.sort the sort to apply to the referenced records
+ * @param {string} props.source The key of the linked resource identifier
+ * @param {UseQuery Options} props.queryOptions `react-query` options`
+ *
+ * @returns {ListControllerResult} The reference many props
+ */
+export const useReferenceManyFieldController = (props) => {
+    const { debounce = 500, reference, target, filter = defaultFilter, exporter = defaultExporter, source = 'id', page: initialPage, perPage: initialPerPage, sort: initialSort = { field: 'id', order: 'DESC' }, queryOptions = {}, } = props;
+    const notify = useNotify();
+    const translate = useTranslate();
+    const record = useRecordContext(props);
+    const resource = useResourceContext(props);
+    const dataProvider = useDataProvider();
+    const queryClient = useQueryClient();
+    const { meta, ...otherQueryOptions } = queryOptions;
+    // 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: reference,
+        storeKey: props.storeKey ?? `${resource}.${record?.id}.${reference}`,
+    });
+    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 => ({
+            ...previousState,
+            [filterName]: defaultValue,
+        }));
+    }, [setDisplayedFilters, setFilterValues]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const debouncedSetFilters = useCallback(lodashDebounce((filters, displayedFilters) => {
+        setFilterValues(removeEmpty(filters));
+        setDisplayedFilters(displayedFilters);
+        setPage(1);
+    }, debounce), [setDisplayedFilters, setFilterValues, setPage]);
+    const setFilters = useCallback((filters, displayedFilters, debounce = false) => {
+        if (debounce) {
+            debouncedSetFilters(filters, displayedFilters);
+        }
+        else {
+            setFilterValues(removeEmpty(filters));
+            setDisplayedFilters(displayedFilters);
+            setPage(1);
+        }
+    }, [setDisplayedFilters, setFilterValues, setPage, debouncedSetFilters]);
+    // handle filter prop change
+    useEffect(() => {
+        if (!isEqual(filter, filterRef.current)) {
+            filterRef.current = filter;
+            setFilterValues(filter);
+        }
+    }, [filter]);
+    const recordValue = get(record, source);
+    const { data, total, meta: responseMeta, pageInfo, error, isFetching, isLoading, isPaused, isPending, isPlaceholderData, refetch, } = useGetManyReference(reference, {
+        target,
+        id: recordValue,
+        pagination: { page, perPage },
+        sort,
+        filter: filterValues,
+        meta,
+    }, {
+        enabled: recordValue != null,
+        placeholderData: previousData => previousData,
+        onError: error => notify(typeof error === 'string'
+            ? error
+            : error?.message ||
+                "strato.notification.http_error', {
+            type: 'error',
+            messageArgs: {
+                _: typeof error === 'string'
+                    ? error
+                    : error?.message
+                        ? error.message
+                        : undefined,
+            },
+        }),
+        ...otherQueryOptions,
+    });
+    const onSelectAll = useEvent(async ({ limit = 250, queryOptions = {}, } = {}) => {
+        const { meta, onSuccess, onError } = queryOptions;
+        try {
+            const results = await queryClient.fetchQuery({
+                queryKey: [
+                    reference,
+                    'getManyReference',
+                    {
+                        target,
+                        id: get(record, source),
+                        pagination: { page: 1, perPage: limit },
+                        sort,
+                        filter,
+                        meta,
+                    },
+                ],
+                queryFn: () => dataProvider.getManyReference(reference, {
+                    target,
+                    id: get(record, source),
+                    pagination: { page: 1, perPage: limit },
+                    sort,
+                    filter,
+                    meta,
+                }),
+            });
+            const allIds = results.data?.map(({ id }) => id) || [];
+            selectionModifiers.select(allIds);
+            if (allIds.length === limit) {
+                notify("strato.message.select_all_limit_reached', {
+                    messageArgs: { max: limit },
+                    type: 'warning',
+                });
+            }
+            if (onSuccess) {
+                onSuccess(results);
+            }
+            return results.data;
+        }
+        catch (error) {
+            if (onError) {
+                onError(error);
+            }
+            notify("strato.notification.http_error', { type: 'warning' });
+        }
+    });
+    const getData = useEvent(async ({ maxResults, meta: metaOverride } = {}) => {
+        if (recordValue == null || total === 0) {
+            return [];
+        }
+        const limit = maxResults ?? (total != null ? total : DEFAULT_MAX_RESULTS);
+        const { data } = await queryClient.fetchQuery({
+            queryKey: [
+                reference,
+                'getManyReference',
+                {
+                    target,
+                    id: recordValue,
+                    pagination: { page: 1, perPage: limit },
+                    sort,
+                    filter: filterValues,
+                    meta: metaOverride ?? meta,
+                },
+            ],
+            queryFn: () => dataProvider.getManyReference(reference, {
+                target,
+                id: recordValue,
+                pagination: { page: 1, perPage: limit },
+                sort,
+                filter: filterValues,
+                meta: metaOverride ?? meta,
+            }),
+        });
+        return data;
+    });
+    const getResourceLabel = useGetResourceLabel();
+    const defaultTitle = translate(`resources.${reference}.page.list`, {
+        _: translate("strato.page.list', {
+            name: getResourceLabel(reference, 2),
+        }),
+    });
+    return {
+        sort,
+        data,
+        meta: responseMeta,
+        defaultTitle,
+        displayedFilters,
+        error,
+        exporter,
+        filterValues,
+        hideFilter,
+        isFetching,
+        isLoading,
+        isPaused,
+        isPending,
+        isPlaceholderData,
+        onSelect: selectionModifiers.select,
+        onSelectAll,
+        onToggleItem: selectionModifiers.toggle,
+        onUnselectItems,
+        page,
+        perPage,
+        refetch,
+        resource: reference,
+        selectedIds,
+        setFilters,
+        setPage,
+        setPerPage,
+        hasNextPage: pageInfo
+            ? pageInfo.hasNextPage
+            : total != null
+                ? page * perPage < total
+                : undefined,
+        hasPreviousPage: pageInfo ? pageInfo.hasPreviousPage : page > 1,
+        setSort,
+        showFilter,
+        total,
+        getData,
+    };
+};
+const defaultFilter = {};

package/dist/ra-core/src/controller/field/useReferenceOneFieldController.d.ts

@@ -0,0 +1,41 @@
+import { UseQueryOptions } from '@tanstack/react-query';
+import { RaRecord, SortPayload } from '../../types';
+import { UseReferenceResult } from '../useReference';
+export interface UseReferenceOneFieldControllerParams<RecordType extends RaRecord = any, ReferenceRecordType extends RaRecord = any, ErrorType = Error> {
+    reference: string;
+    target: string;
+    filter?: any;
+    queryOptions?: Omit<UseQueryOptions<{
+        data: ReferenceRecordType[];
+        total: number;
+    }, ErrorType>, 'queryFn' | 'queryKey'> & {
+        meta?: any;
+    };
+    record?: RecordType;
+    sort?: SortPayload;
+    source?: string;
+}
+/**
+ * Fetch a reference record in a one-to-one relationship, and return it when available
+ *
+ * The reference prop should be the name of one of the <Resource> components
+ * added as <Admin> child.
+ *
+ * @example
+ *
+ * const { data, isPending, error } = useReferenceOneFieldController({
+ *     record: { id: 7, name: 'James Joyce'}
+ *     reference: 'bios',
+ *     target: 'author_id',
+ * });
+ *
+ * @typedef {Object} UseReferenceOneFieldControllerParams
+ * @prop {Object} props.record The current resource record
+ * @prop {string} props.reference The linked resource name
+ * @prop {string} props.target The target resource key
+ * @prop {string} props.source The key current record identifier ('id' by default)
+ * @prop {Object} props.sort The sort to apply to the referenced records
+ * @prop {Object} props.filter The filter to apply to the referenced records
+ * @returns {UseReferenceResult} The request state. Destructure as { referenceRecord, isPending, error }.
+ */
+export declare const useReferenceOneFieldController: <RecordType extends RaRecord = any, ReferenceRecordType extends RaRecord = any, ErrorType = Error>(props: UseReferenceOneFieldControllerParams<RecordType, ReferenceRecordType, ErrorType>) => UseReferenceResult<ReferenceRecordType, ErrorType>;

package/dist/ra-core/src/controller/field/useReferenceOneFieldController.js

@@ -0,0 +1,67 @@
+import get from 'lodash/get.js';
+import { useRecordContext } from '../record';
+import { useGetManyReference } from '../../dataProvider';
+import { useNotify } from '../../notification';
+/**
+ * Fetch a reference record in a one-to-one relationship, and return it when available
+ *
+ * The reference prop should be the name of one of the <Resource> components
+ * added as <Admin> child.
+ *
+ * @example
+ *
+ * const { data, isPending, error } = useReferenceOneFieldController({
+ *     record: { id: 7, name: 'James Joyce'}
+ *     reference: 'bios',
+ *     target: 'author_id',
+ * });
+ *
+ * @typedef {Object} UseReferenceOneFieldControllerParams
+ * @prop {Object} props.record The current resource record
+ * @prop {string} props.reference The linked resource name
+ * @prop {string} props.target The target resource key
+ * @prop {string} props.source The key current record identifier ('id' by default)
+ * @prop {Object} props.sort The sort to apply to the referenced records
+ * @prop {Object} props.filter The filter to apply to the referenced records
+ * @returns {UseReferenceResult} The request state. Destructure as { referenceRecord, isPending, error }.
+ */
+export const useReferenceOneFieldController = (props) => {
+    const { reference, target, source = 'id', sort = { field: 'id', order: 'ASC' }, filter = {}, queryOptions = {}, } = props;
+    const record = useRecordContext(props);
+    const notify = useNotify();
+    const { meta, ...otherQueryOptions } = queryOptions;
+    const { data, error, isFetching, isLoading, isPaused, isPending, isPlaceholderData, refetch, } = useGetManyReference(reference, {
+        target,
+        id: get(record, source),
+        pagination: { page: 1, perPage: 1 },
+        sort,
+        filter,
+        meta,
+    }, {
+        enabled: !!record,
+        onError: error => notify(typeof error === 'string'
+            ? error
+            : error.message ||
+                "strato.notification.http_error', {
+            type: 'error',
+            messageArgs: {
+                _: typeof error === 'string'
+                    ? error
+                    : error?.message
+                        ? error.message
+                        : undefined,
+            },
+        }),
+        ...otherQueryOptions,
+    });
+    return {
+        referenceRecord: data ? data[0] : undefined,
+        error,
+        isFetching,
+        isLoading,
+        isPaused,
+        isPending,
+        isPlaceholderData,
+        refetch,
+    };
+};

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

@@ -0,0 +1,17 @@
+import useFilterState from './useFilterState';
+import useSortState, { SortProps } from './useSortState';
+import usePaginationState, { PaginationHookResult } from './usePaginationState';
+import { useCheckMinimumRequiredProps } from './checkMinimumRequiredProps';
+export type { PaginationHookResult, SortProps };
+export { useCheckMinimumRequiredProps, useFilterState, usePaginationState, useSortState, };
+export * from './button';
+export * from './create';
+export * from './edit';
+export * from './field';
+export * from './input';
+export * from './list';
+export * from './record';
+export * from './saveContext';
+export * from './show';
+export * from './useReference';
+export * from './usePrevNextController';

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

@@ -0,0 +1,16 @@
+import useFilterState from './useFilterState';
+import useSortState from './useSortState';
+import usePaginationState from './usePaginationState';
+import { useCheckMinimumRequiredProps } from './checkMinimumRequiredProps';
+export { useCheckMinimumRequiredProps, useFilterState, usePaginationState, useSortState, };
+export * from './button';
+export * from './create';
+export * from './edit';
+export * from './field';
+export * from './input';
+export * from './list';
+export * from './record';
+export * from './saveContext';
+export * from './show';
+export * from './useReference';
+export * from './usePrevNextController';

package/dist/ra-core/src/controller/input/ArrayInputBase.d.ts

@@ -0,0 +1,46 @@
+import { type ReactNode } from 'react';
+import type { InputProps } from '../../form/useInput';
+/**
+ * To edit arrays of data embedded inside a record, <ArrayInputBase> creates a list of sub-forms.
+ *
+ *  @example
+ *
+ *      import { ArrayInputBase } from '@strato-admin/ra-core';
+ *      import { SimpleFormIterator, DateInput, TextInput } from 'my-react-admin-ui';
+ *
+ *      <ArrayInputBase source="backlinks">
+ *          <SimpleFormIterator>
+ *              <DateInput source="date" />
+ *              <TextInput source="url" />
+ *          </SimpleFormIterator>
+ *      </ArrayInputBase>
+ *
+ * <ArrayInputBase> allows the edition of embedded arrays, like the backlinks field
+ * in the following post record:
+ *
+ * {
+ *   id: 123
+ *   backlinks: [
+ *         {
+ *             date: '2012-08-10T00:00:00.000Z',
+ *             url: 'http://example.com/foo/bar.html',
+ *         },
+ *         {
+ *             date: '2012-08-14T00:00:00.000Z',
+ *             url: 'https://blog.johndoe.com/2012/08/12/foobar.html',
+ *         }
+ *    ]
+ * }
+ *
+ * <ArrayInputBase> expects a single child, which must be a *form iterator* component.
+ * A form iterator is a component accepting a fields object as passed by
+ * react-hook-form-arrays's useFieldArray() hook, and defining a layout for
+ * an array of fields.
+ *
+ * @see {@link https://react-hook-form.com/docs/usefieldarray}
+ */
+export declare const ArrayInputBase: (props: ArrayInputBaseProps) => import("react/jsx-runtime").JSX.Element;
+export declare const getArrayInputError: (error: any) => any;
+export interface ArrayInputBaseProps extends Omit<InputProps, 'disabled' | 'readOnly'> {
+    children: ReactNode;
+}

package/dist/ra-core/src/controller/input/ArrayInputBase.js

@@ -0,0 +1,130 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+import { useEffect } from 'react';
+import { useFieldArray, useFormContext } from 'react-hook-form';
+import { composeSyncValidators } from '../../form/validation/validate';
+import { useGetValidationErrorMessage } from '../../form/validation/useGetValidationErrorMessage';
+import { useApplyInputDefaultValues } from '../../form/useApplyInputDefaultValues';
+import { useFormGroupContext } from '../../form/groups/useFormGroupContext';
+import { useFormGroups } from '../../form/groups/useFormGroups';
+import { OptionalResourceContextProvider, SourceContextProvider, useSourceContext, } from '../../core';
+import { ArrayInputContext } from './ArrayInputContext';
+/**
+ * To edit arrays of data embedded inside a record, <ArrayInputBase> creates a list of sub-forms.
+ *
+ *  @example
+ *
+ *      import { ArrayInputBase } from '@strato-admin/ra-core';
+ *      import { SimpleFormIterator, DateInput, TextInput } from 'my-react-admin-ui';
+ *
+ *      <ArrayInputBase source="backlinks">
+ *          <SimpleFormIterator>
+ *              <DateInput source="date" />
+ *              <TextInput source="url" />
+ *          </SimpleFormIterator>
+ *      </ArrayInputBase>
+ *
+ * <ArrayInputBase> allows the edition of embedded arrays, like the backlinks field
+ * in the following post record:
+ *
+ * {
+ *   id: 123
+ *   backlinks: [
+ *         {
+ *             date: '2012-08-10T00:00:00.000Z',
+ *             url: 'http://example.com/foo/bar.html',
+ *         },
+ *         {
+ *             date: '2012-08-14T00:00:00.000Z',
+ *             url: 'https://blog.johndoe.com/2012/08/12/foobar.html',
+ *         }
+ *    ]
+ * }
+ *
+ * <ArrayInputBase> expects a single child, which must be a *form iterator* component.
+ * A form iterator is a component accepting a fields object as passed by
+ * react-hook-form-arrays's useFieldArray() hook, and defining a layout for
+ * an array of fields.
+ *
+ * @see {@link https://react-hook-form.com/docs/usefieldarray}
+ */
+export const ArrayInputBase = (props) => {
+    const { children, defaultValue = [], resource: resourceFromProps, source: arraySource, validate, } = props;
+    const formGroupName = useFormGroupContext();
+    const formGroups = useFormGroups();
+    const parentSourceContext = useSourceContext();
+    const finalSource = parentSourceContext.getSource(arraySource);
+    const sanitizedValidate = Array.isArray(validate)
+        ? composeSyncValidators(validate)
+        : validate;
+    const getValidationErrorMessage = useGetValidationErrorMessage();
+    const { getValues } = useFormContext();
+    const fieldProps = useFieldArray({
+        name: finalSource,
+        rules: {
+            validate: async (value) => {
+                if (!sanitizedValidate)
+                    return true;
+                const error = await sanitizedValidate(value, getValues(), props);
+                if (!error)
+                    return true;
+                return getValidationErrorMessage(error);
+            },
+        },
+    });
+    useEffect(() => {
+        if (formGroups && formGroupName != null) {
+            formGroups.registerField(finalSource, formGroupName);
+        }
+        return () => {
+            if (formGroups && formGroupName != null) {
+                formGroups.unregisterField(finalSource, formGroupName);
+            }
+        };
+    }, [finalSource, formGroups, formGroupName]);
+    useApplyInputDefaultValues({
+        inputProps: { ...props, defaultValue },
+        isArrayInput: true,
+        fieldArrayInputControl: fieldProps,
+    });
+    // The SourceContext will be read by children of ArrayInput to compute their composed source and label
+    //
+    // <ArrayInput source="orders" /> => SourceContext is "orders"
+    //   <SimpleFormIterator> => SourceContext is "orders.0"
+    //     <DateInput source="date" /> => final source for this input will be "orders.0.date"
+    //   </SimpleFormIterator>
+    // </ArrayInput>
+    //
+    const sourceContext = React.useMemo(() => ({
+        // source is the source of the ArrayInput child
+        getSource: (source) => {
+            if (!source) {
+                // SimpleFormIterator calls getSource('') to get the arraySource
+                return parentSourceContext.getSource(arraySource);
+            }
+            // We want to support nesting and composition with other inputs (e.g. TranslatableInputs, ReferenceOneInput, etc),
+            // we must also take into account the parent SourceContext
+            //
+            // <ArrayInput source="orders" /> => SourceContext is "orders"
+            //   <SimpleFormIterator> => SourceContext is "orders.0"
+            //      <DateInput source="date" /> => final source for this input will be "orders.0.date"
+            //      <ArrayInput source="items" /> => SourceContext is "orders.0.items"
+            //          <SimpleFormIterator> => SourceContext is "orders.0.items.0"
+            //              <TextInput source="reference" /> => final source for this input will be "orders.0.items.0.reference"
+            //          </SimpleFormIterator>
+            //      </ArrayInput>
+            //   </SimpleFormIterator>
+            // </ArrayInput>
+            return parentSourceContext.getSource(`${arraySource}.${source}`);
+        },
+        // if Array source is items, and child source is name, .0.name => resources.orders.fields.items.name
+        getLabel: (source) => parentSourceContext.getLabel(`${arraySource}.${source}`),
+    }), [parentSourceContext, arraySource]);
+    return (_jsx(ArrayInputContext.Provider, { value: fieldProps, children: _jsx(OptionalResourceContextProvider, { value: resourceFromProps, children: _jsx(SourceContextProvider, { value: sourceContext, children: children }) }) }));
+};
+export const getArrayInputError = error => {
+    if (Array.isArray(error)) {
+        return undefined;
+    }
+    return error;
+};

package/dist/ra-core/src/controller/input/ArrayInputContext.d.ts

@@ -0,0 +1,9 @@
+import { UseFieldArrayReturn } from 'react-hook-form';
+/**
+ * A React context that provides access to an ArrayInput methods as provided by react-hook-form
+ * Useful to create custom array input iterators.
+ * @see {ArrayInput}
+ * @see {@link https://react-hook-form.com/docs/usefieldarray}
+ */
+export declare const ArrayInputContext: import("react").Context<ArrayInputContextValue | undefined>;
+export type ArrayInputContextValue = UseFieldArrayReturn;

package/dist/ra-core/src/controller/input/ArrayInputContext.js

@@ -0,0 +1,8 @@
+import { createContext } from 'react';
+/**
+ * A React context that provides access to an ArrayInput methods as provided by react-hook-form
+ * Useful to create custom array input iterators.
+ * @see {ArrayInput}
+ * @see {@link https://react-hook-form.com/docs/usefieldarray}
+ */
+export const ArrayInputContext = createContext(undefined);