@strato-admin/core 0.1.0 → 0.3.0

package/dist/ra-core/src/controller/saveContext/useRegisterMutationMiddleware.js

@@ -0,0 +1,18 @@
+import { useEffect } from 'react';
+import { useSaveContext } from './useSaveContext';
+/**
+ * Internal hook that registers a middleware for the save function in the current SaveContext.
+ * @param callback The middleware function.
+ */
+export const useRegisterMutationMiddleware = (callback) => {
+    const { registerMutationMiddleware, unregisterMutationMiddleware } = useSaveContext();
+    useEffect(() => {
+        if (!registerMutationMiddleware || !unregisterMutationMiddleware) {
+            return;
+        }
+        registerMutationMiddleware(callback);
+        return () => {
+            unregisterMutationMiddleware(callback);
+        };
+    }, [callback, registerMutationMiddleware, unregisterMutationMiddleware]);
+};

package/dist/ra-core/src/controller/saveContext/useSaveContext.d.ts

@@ -0,0 +1,14 @@
+import { SaveContextValue } from './SaveContext';
+/**
+ * Get the save() function and its status
+ *
+ * Used in forms.
+ *
+ * @example
+ *
+ * const {
+ *     save,
+ *     saving
+ * } = useSaveContext();
+ */
+export declare const useSaveContext: <PropsType extends SaveContextValue = SaveContextValue>(_props?: PropsType) => SaveContextValue;

package/dist/ra-core/src/controller/saveContext/useSaveContext.js

@@ -0,0 +1,17 @@
+import { useContext } from 'react';
+import { SaveContext } from './SaveContext';
+/**
+ * Get the save() function and its status
+ *
+ * Used in forms.
+ *
+ * @example
+ *
+ * const {
+ *     save,
+ *     saving
+ * } = useSaveContext();
+ */
+export const useSaveContext = (_props) => {
+    return useContext(SaveContext);
+};

package/dist/ra-core/src/controller/show/ShowBase.d.ts

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import { RaRecord } from '../../types';
+import { ShowControllerProps, ShowControllerResult } from './useShowController';
+import { ReactNode } from 'react';
+/**
+ * Call useShowController and put the value in a ShowContext
+ *
+ * Base class for <Show> components, without UI.
+ *
+ * Accepts any props accepted by useShowController:
+ * - id: The record identifier
+ * - resource: The resource
+ *
+ * @example // Custom show layout
+ *
+ * const PostShow = () => (
+ *     <ShowBase resource="posts">
+ *         <Grid container>
+ *             <Grid item xs={8}>
+ *                 <SimpleForm>
+ *                     ...
+ *                 </SimpleForm>
+ *             </Grid>
+ *             <Grid item xs={4}>
+ *                 Show instructions...
+ *             </Grid>
+ *         </Grid>
+ *         <div>
+ *             Post related links...
+ *         </div>
+ *     </ShowBase>
+ * );
+ */
+export declare const ShowBase: <RecordType extends RaRecord = any>({ authLoading, loading, offline, error, redirectOnError, children, render, ...props }: ShowBaseProps<RecordType>) => import("react/jsx-runtime").JSX.Element;
+export interface ShowBaseProps<RecordType extends RaRecord = RaRecord> extends ShowControllerProps<RecordType> {
+    authLoading?: ReactNode;
+    loading?: ReactNode;
+    offline?: ReactNode;
+    error?: ReactNode;
+    children?: React.ReactNode;
+    render?: (props: ShowControllerResult<RecordType>) => React.ReactNode;
+}

package/dist/ra-core/src/controller/show/ShowBase.js

@@ -0,0 +1,72 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useShowController, } from './useShowController';
+import { ShowContextProvider } from './ShowContextProvider';
+import { OptionalResourceContextProvider } from '../../core';
+import { useIsAuthPending } from '../../auth';
+/**
+ * Call useShowController and put the value in a ShowContext
+ *
+ * Base class for <Show> components, without UI.
+ *
+ * Accepts any props accepted by useShowController:
+ * - id: The record identifier
+ * - resource: The resource
+ *
+ * @example // Custom show layout
+ *
+ * const PostShow = () => (
+ *     <ShowBase resource="posts">
+ *         <Grid container>
+ *             <Grid item xs={8}>
+ *                 <SimpleForm>
+ *                     ...
+ *                 </SimpleForm>
+ *             </Grid>
+ *             <Grid item xs={4}>
+ *                 Show instructions...
+ *             </Grid>
+ *         </Grid>
+ *         <div>
+ *             Post related links...
+ *         </div>
+ *     </ShowBase>
+ * );
+ */
+export const ShowBase = ({ authLoading, loading, offline, error, redirectOnError, children, render, ...props }) => {
+    const hasError = error !== false && error !== undefined;
+    const controllerProps = useShowController({
+        ...props,
+        redirectOnError: redirectOnError ?? (hasError ? false : undefined),
+    });
+    const isAuthPending = useIsAuthPending({
+        resource: controllerProps.resource,
+        action: 'show',
+    });
+    if (!render && !children) {
+        throw new Error('<ShowBase> requires either a `render` prop or `children` prop');
+    }
+    const { isPaused, isPending, error: errorState } = controllerProps;
+    const showAuthLoading = isAuthPending &&
+        !props.disableAuthentication &&
+        authLoading !== false &&
+        authLoading !== undefined;
+    const showLoading = !isPaused &&
+        ((!props.disableAuthentication && isAuthPending) || isPending) &&
+        loading !== false &&
+        loading !== undefined;
+    const showOffline = isPaused && isPending && offline !== false && offline !== undefined;
+    const showError = errorState && hasError;
+    return (
+    // We pass props.resource here as we don't need to create a new ResourceContext if the props is not provided
+    _jsx(OptionalResourceContextProvider, { value: props.resource, children: _jsx(ShowContextProvider, { value: controllerProps, children: showAuthLoading
+                ? authLoading
+                : showLoading
+                    ? loading
+                    : showOffline
+                        ? offline
+                        : showError
+                            ? error
+                            : render
+                                ? render(controllerProps)
+                                : children }) }));
+};

package/dist/ra-core/src/controller/show/ShowContext.d.ts

@@ -0,0 +1,20 @@
+import { ShowControllerResult } from './useShowController';
+/**
+ * Context to store the result of the useShowController() hook.
+ *
+ * Use the useShowContext() hook to read the context. That's what the Show components do in react-admin.
+ *
+ * @example
+ *
+ * import { useShowController, ShowContextProvider } from '@strato-admin/ra-core';
+ *
+ * const Show = props => {
+ *     const controllerProps = useShowController(props);
+ *     return (
+ *         <ShowContextProvider value={controllerProps}>
+ *             ...
+ *         </ShowContextProvider>
+ *     );
+ * };
+ */
+export declare const ShowContext: import("react").Context<ShowControllerResult | null>;

package/dist/ra-core/src/controller/show/ShowContext.js

@@ -0,0 +1,21 @@
+import { createContext } from 'react';
+/**
+ * Context to store the result of the useShowController() hook.
+ *
+ * Use the useShowContext() hook to read the context. That's what the Show components do in react-admin.
+ *
+ * @example
+ *
+ * import { useShowController, ShowContextProvider } from '@strato-admin/ra-core';
+ *
+ * const Show = props => {
+ *     const controllerProps = useShowController(props);
+ *     return (
+ *         <ShowContextProvider value={controllerProps}>
+ *             ...
+ *         </ShowContextProvider>
+ *     );
+ * };
+ */
+export const ShowContext = createContext(null);
+ShowContext.displayName = 'ShowContext';

package/dist/ra-core/src/controller/show/ShowContextProvider.d.ts

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react';
+import { ShowControllerResult } from './useShowController';
+/**
+ * Create a Show Context.
+ *
+ * @example
+ *
+ * const MyShow = (props) => {
+ *     const controllerProps = useShowController(props);
+ *     return (
+ *         <ShowContextProvider value={controllerProps}>
+ *             <MyShowView>
+ *         </ShowContextProvider>
+ *     );
+ * };
+ *
+ * const MyShowView = () => {
+ *     const record = useRecordContext();
+ * }
+ *
+ * @see ShowContext
+ * @see RecordContext
+ */
+export declare const ShowContextProvider: ({ children, value, }: {
+    children: ReactNode;
+    value: ShowControllerResult;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/ra-core/src/controller/show/ShowContextProvider.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RecordContextProvider } from '../record/RecordContext';
+import { ShowContext } from './ShowContext';
+/**
+ * Create a Show Context.
+ *
+ * @example
+ *
+ * const MyShow = (props) => {
+ *     const controllerProps = useShowController(props);
+ *     return (
+ *         <ShowContextProvider value={controllerProps}>
+ *             <MyShowView>
+ *         </ShowContextProvider>
+ *     );
+ * };
+ *
+ * const MyShowView = () => {
+ *     const record = useRecordContext();
+ * }
+ *
+ * @see ShowContext
+ * @see RecordContext
+ */
+export const ShowContextProvider = ({ children, value, }) => (_jsx(ShowContext.Provider, { value: value, children: _jsx(RecordContextProvider, { value: value && value.record, children: children }) }));

package/dist/ra-core/src/controller/show/ShowController.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { RaRecord } from '../../types';
+import { ShowControllerProps, ShowControllerResult } from './useShowController';
+/**
+ * Render prop version of the useShowController hook
+ *
+ * @see useShowController
+ * @example
+ *
+ * const ShowView = () => <div>...</div>
+ * const MyShow = () => (
+ *     <ShowController>
+ *         {controllerProps => <ShowView {...controllerProps} {...props} />}
+ *     </ShowController>
+ * );
+ */
+export declare const ShowController: <RecordType extends RaRecord = any, ErrorType = Error>({ children, ...props }: {
+    children: (params: ShowControllerResult<RecordType, ErrorType>) => ReactNode;
+} & ShowControllerProps<RecordType, ErrorType>) => ReactNode;

package/dist/ra-core/src/controller/show/ShowController.js

@@ -0,0 +1,18 @@
+import { useShowController, } from './useShowController';
+/**
+ * Render prop version of the useShowController hook
+ *
+ * @see useShowController
+ * @example
+ *
+ * const ShowView = () => <div>...</div>
+ * const MyShow = () => (
+ *     <ShowController>
+ *         {controllerProps => <ShowView {...controllerProps} {...props} />}
+ *     </ShowController>
+ * );
+ */
+export const ShowController = ({ children, ...props }) => {
+    const controllerProps = useShowController(props);
+    return children(controllerProps);
+};

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

@@ -0,0 +1,6 @@
+export * from './ShowBase';
+export * from './ShowContext';
+export * from './ShowContextProvider';
+export * from './ShowController';
+export * from './useShowController';
+export * from './useShowContext';

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

@@ -0,0 +1,6 @@
+export * from './ShowBase';
+export * from './ShowContext';
+export * from './ShowContextProvider';
+export * from './ShowController';
+export * from './useShowController';
+export * from './useShowContext';

package/dist/ra-core/src/controller/show/useShowContext.d.ts

@@ -0,0 +1,12 @@
+import { RaRecord } from '../../types';
+import { ShowControllerResult } from './useShowController';
+/**
+ * Hook to read the show controller props from the ShowContext.
+ *
+ * Used within a <ShowContextProvider> (e.g. as a descendent of <Show>).
+ *
+ * @returns {ShowControllerResult} create controller props
+ *
+ * @see useShowController for how it is filled
+ */
+export declare const useShowContext: <RecordType extends RaRecord = any, ErrorType = Error>() => ShowControllerResult<RecordType, ErrorType>;

package/dist/ra-core/src/controller/show/useShowContext.js

@@ -0,0 +1,19 @@
+import { useContext } from 'react';
+import { ShowContext } from './ShowContext';
+/**
+ * Hook to read the show controller props from the ShowContext.
+ *
+ * Used within a <ShowContextProvider> (e.g. as a descendent of <Show>).
+ *
+ * @returns {ShowControllerResult} create controller props
+ *
+ * @see useShowController for how it is filled
+ */
+export const useShowContext = () => {
+    const context = useContext(ShowContext);
+    // Props take precedence over the context
+    if (!context) {
+        throw new Error('useShowContext must be used inside a ShowContextProvider');
+    }
+    return context;
+};

package/dist/ra-core/src/controller/show/useShowController.d.ts

@@ -0,0 +1,75 @@
+import { RaRecord } from '../../types';
+import { UseGetOneHookValue, UseGetOneOptions } from '../../dataProvider';
+import { RedirectionSideEffect } from '../../routing';
+/**
+ * Prepare data for the Show view.
+ *
+ * useShowController does a few things:
+ * - it grabs the id from the URL and the resource name from the ResourceContext,
+ * - it fetches the record via useGetOne,
+ * - it prepares the page title.
+ *
+ * @param {Object} props The props passed to the Show component.
+ *
+ * @return {Object} controllerProps Fetched data and callbacks for the Show view
+ *
+ * @example
+ *
+ * import { useShowController } from 'react-admin';
+ * import ShowView from './ShowView';
+ *
+ * const MyShow = () => {
+ *     const controllerProps = useShowController();
+ *     return <ShowView {...controllerProps} />;
+ * };
+ *
+ * @example // useShowController can also take its parameters from props
+ *
+ * import { useShowController } from 'react-admin';
+ * import ShowView from './ShowView';
+ *
+ * const MyShow = () => {
+ *     const controllerProps = useShowController({ resource: 'posts', id: 1234 });
+ *     return <ShowView {...controllerProps} />;
+ * };
+ */
+export declare const useShowController: <RecordType extends RaRecord = any, ErrorType = Error>(props?: ShowControllerProps<RecordType, ErrorType>) => ShowControllerResult<RecordType, ErrorType>;
+export interface ShowControllerProps<RecordType extends RaRecord = any, ErrorType = Error> {
+    disableAuthentication?: boolean;
+    id?: RecordType['id'];
+    queryOptions?: UseGetOneOptions<RecordType, ErrorType>;
+    resource?: string;
+    redirectOnError?: RedirectionSideEffect;
+}
+export interface ShowControllerBaseResult<RecordType extends RaRecord = any> {
+    defaultTitle?: string;
+    isFetching: boolean;
+    isLoading: boolean;
+    isPaused?: boolean;
+    isPlaceholderData?: boolean;
+    redirectOnError?: RedirectionSideEffect;
+    resource: string;
+    record?: RecordType;
+    refetch: UseGetOneHookValue<RecordType>['refetch'];
+}
+export interface ShowControllerLoadingResult<RecordType extends RaRecord = any> extends ShowControllerBaseResult<RecordType> {
+    record: undefined;
+    error: null;
+    isPending: true;
+}
+export interface ShowControllerLoadingErrorResult<RecordType extends RaRecord = any, TError = Error> extends ShowControllerBaseResult<RecordType> {
+    record: undefined;
+    error: TError;
+    isPending: false;
+}
+export interface ShowControllerRefetchErrorResult<RecordType extends RaRecord = any, TError = Error> extends ShowControllerBaseResult<RecordType> {
+    record: RecordType;
+    error: TError;
+    isPending: false;
+}
+export interface ShowControllerSuccessResult<RecordType extends RaRecord = any> extends ShowControllerBaseResult<RecordType> {
+    record: RecordType;
+    error: null;
+    isPending: false;
+}
+export type ShowControllerResult<RecordType extends RaRecord = any, ErrorType = Error> = ShowControllerLoadingResult<RecordType> | ShowControllerLoadingErrorResult<RecordType, ErrorType> | ShowControllerRefetchErrorResult<RecordType, ErrorType> | ShowControllerSuccessResult<RecordType>;

package/dist/ra-core/src/controller/show/useShowController.js

@@ -0,0 +1,110 @@
+import { useAuthenticated, useRequireAccess } from '../../auth';
+import { useGetOne, } from '../../dataProvider';
+import { useTranslate } from '../../i18n';
+import { useRedirect, useParams } from '../../routing';
+import { useNotify } from '../../notification';
+import { useResourceContext, useGetResourceLabel, useGetRecordRepresentation, } from '../../core';
+/**
+ * Prepare data for the Show view.
+ *
+ * useShowController does a few things:
+ * - it grabs the id from the URL and the resource name from the ResourceContext,
+ * - it fetches the record via useGetOne,
+ * - it prepares the page title.
+ *
+ * @param {Object} props The props passed to the Show component.
+ *
+ * @return {Object} controllerProps Fetched data and callbacks for the Show view
+ *
+ * @example
+ *
+ * import { useShowController } from 'react-admin';
+ * import ShowView from './ShowView';
+ *
+ * const MyShow = () => {
+ *     const controllerProps = useShowController();
+ *     return <ShowView {...controllerProps} />;
+ * };
+ *
+ * @example // useShowController can also take its parameters from props
+ *
+ * import { useShowController } from 'react-admin';
+ * import ShowView from './ShowView';
+ *
+ * const MyShow = () => {
+ *     const controllerProps = useShowController({ resource: 'posts', id: 1234 });
+ *     return <ShowView {...controllerProps} />;
+ * };
+ */
+export const useShowController = (props = {}) => {
+    const { disableAuthentication = false, id: propsId, queryOptions = {}, redirectOnError = DefaultRedirectOnError, } = props;
+    const resource = useResourceContext(props);
+    if (!resource) {
+        throw new Error(`useShowController requires a non-empty resource prop or context`);
+    }
+    const { isPending: isPendingAuthenticated } = useAuthenticated({
+        enabled: !disableAuthentication,
+    });
+    const { isPending: isPendingCanAccess } = useRequireAccess({
+        action: 'show',
+        resource,
+        enabled: !disableAuthentication && !isPendingAuthenticated,
+    });
+    const getRecordRepresentation = useGetRecordRepresentation(resource);
+    const translate = useTranslate();
+    const notify = useNotify();
+    const redirect = useRedirect();
+    const { id: routeId } = useParams();
+    if (!routeId && !propsId) {
+        throw new Error('useShowController requires an id prop or a route with an /:id? parameter.');
+    }
+    const id = propsId != null ? propsId : routeId;
+    const { meta, ...otherQueryOptions } = queryOptions;
+    const { data: record, error, isLoading, isFetching, isPaused, isPending, isPlaceholderData, refetch, } = useGetOne(resource, { id, meta }, {
+        enabled: (!isPendingAuthenticated && !isPendingCanAccess) ||
+            disableAuthentication,
+        onError: () => {
+            notify("strato.notification.item_doesnt_exist', {
+                type: 'error',
+            });
+            redirect(redirectOnError, resource, id);
+        },
+        retry: false,
+        ...otherQueryOptions,
+    });
+    // eslint-disable-next-line eqeqeq
+    if (record && record.id && record.id != id) {
+        throw new Error(`useShowController: Fetched record's id attribute (${record.id}) must match the requested 'id' (${id})`);
+    }
+    const getResourceLabel = useGetResourceLabel();
+    const recordRepresentation = getRecordRepresentation(record);
+    const defaultTitle = translate(`resources.${resource}.page.show`, {
+        id,
+        record,
+        recordRepresentation: typeof recordRepresentation === 'string'
+            ? recordRepresentation
+            : '',
+        _: translate("strato.page.show', {
+            name: getResourceLabel(resource, 1),
+            id,
+            record,
+            recordRepresentation: typeof recordRepresentation === 'string'
+                ? recordRepresentation
+                : '',
+        }),
+    });
+    return {
+        defaultTitle,
+        error,
+        isLoading,
+        isFetching,
+        isPaused,
+        isPending,
+        isPlaceholderData,
+        record,
+        redirectOnError,
+        refetch,
+        resource,
+    };
+};
+const DefaultRedirectOnError = 'list';

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

@@ -0,0 +1,46 @@
+import { FilterPayload } from '../types';
+interface UseFilterStateOptions {
+    filterToQuery?: (v: string) => FilterPayload;
+    permanentFilter?: FilterPayload;
+    debounceTime?: number;
+}
+/**
+ * @typedef UseFilterStateProps
+ * @property {Object} filter: The filter object.
+ * @property {setFilter} setFilter: Update the filter with the given string
+ */
+interface UseFilterStateProps {
+    filter: FilterPayload;
+    setFilter: (v: string) => void;
+}
+/**
+ * Hooks to provide filter state and setFilter which updates the query part of the filter
+ *
+ * @example
+ *
+ * const { filter, setFilter } = useFilter({
+ *      filterToQuery: v => ({ query: v }),
+ *      permanentFilter: { foo: 'bar' },
+ *      debounceTime: 500,
+ * });
+ * // filter initial value:
+ * {
+ *      query: '',
+ *      foo: 'bar'
+ * }
+ *  // after updating filter
+ *  setFilter('needle');
+ *  {
+ *      query: 'needle',
+ *      foo: 'bar'
+ *  }
+ *
+ * @param {Object} option
+ * @param {Function} option.filterToQuery Function to convert the filter string to a filter object. Defaults to v => ({ q: v }).
+ * @param {Object} option.permanentFilter Permanent filter to be merged with the filter string. Defaults to {}.
+ * @param {number} option.debounceTime Time in ms between filter updates - used to debounce the search. Defaults to 500ms.
+ *
+ * @returns {UseFilterStateOptions} The filter props
+ */
+declare const _default: ({ filterToQuery, permanentFilter, debounceTime, }: UseFilterStateOptions) => UseFilterStateProps;
+export default _default;

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

@@ -0,0 +1,70 @@
+import { useEffect, useRef, useCallback, useState } from 'react';
+import debounce from 'lodash/debounce.js';
+import isEqual from 'lodash/isEqual.js';
+const defaultFilter = {};
+const defaultFilterToQuery = (v) => ({ q: v });
+/**
+ * Hooks to provide filter state and setFilter which updates the query part of the filter
+ *
+ * @example
+ *
+ * const { filter, setFilter } = useFilter({
+ *      filterToQuery: v => ({ query: v }),
+ *      permanentFilter: { foo: 'bar' },
+ *      debounceTime: 500,
+ * });
+ * // filter initial value:
+ * {
+ *      query: '',
+ *      foo: 'bar'
+ * }
+ *  // after updating filter
+ *  setFilter('needle');
+ *  {
+ *      query: 'needle',
+ *      foo: 'bar'
+ *  }
+ *
+ * @param {Object} option
+ * @param {Function} option.filterToQuery Function to convert the filter string to a filter object. Defaults to v => ({ q: v }).
+ * @param {Object} option.permanentFilter Permanent filter to be merged with the filter string. Defaults to {}.
+ * @param {number} option.debounceTime Time in ms between filter updates - used to debounce the search. Defaults to 500ms.
+ *
+ * @returns {UseFilterStateOptions} The filter props
+ */
+export default ({ filterToQuery = defaultFilterToQuery, permanentFilter = {}, debounceTime = 500, }) => {
+    const permanentFilterProp = useRef(permanentFilter);
+    const latestValue = useRef(undefined);
+    const [filter, setFilterValue] = useState({
+        ...permanentFilter,
+        ...filterToQuery(''),
+    });
+    // Developers often pass an object literal as permanent filter
+    // e.g. <ReferenceInput source="book_id" reference="books" filter={{ is_published: true }}>
+    // The effect should execute again when the parent component updates the filter value,
+    // but not when the object literal describes the same values. Therefore,
+    // we use JSON.stringify(permanentFilter) in the `useEffect` and `useCallback`
+    // dependencies instead of permanentFilter.
+    const permanentFilterSignature = JSON.stringify(permanentFilter);
+    useEffect(() => {
+        if (!isEqual(permanentFilterProp.current, permanentFilter)) {
+            permanentFilterProp.current = permanentFilter;
+            setFilterValue({
+                ...permanentFilter,
+                ...filterToQuery(latestValue.current || ''),
+            });
+        }
+    }, [permanentFilterSignature, permanentFilterProp, filterToQuery]); // eslint-disable-line react-hooks/exhaustive-deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const setFilter = useCallback(debounce((value) => {
+        setFilterValue({
+            ...permanentFilter,
+            ...filterToQuery(value),
+        });
+        latestValue.current = value;
+    }, debounceTime), [permanentFilterSignature]);
+    return {
+        filter: filter ?? defaultFilter,
+        setFilter,
+    };
+};