@refinedev/core 4.0.0

package/src/hooks/show/useShow.ts

@@ -0,0 +1,183 @@
+import React, { useState } from "react";
+import { QueryObserverResult, UseQueryOptions } from "@tanstack/react-query";
+
+import { useOne, useResourceWithRoute, useRouterContext } from "@hooks";
+
+import {
+    ResourceRouterParams,
+    BaseRecord,
+    GetOneResponse,
+    SuccessErrorNotification,
+    MetaQuery,
+    LiveModeProps,
+    BaseKey,
+    HttpError,
+    IResourceItem,
+} from "../../interfaces";
+import { useRouterType } from "@contexts/router-picker";
+import { useParsed } from "@hooks/router/use-parsed";
+import { pickResource } from "@definitions/helpers/pick-resource";
+import { useResource } from "../resource/useResource";
+import { pickNotDeprecated } from "@definitions/helpers";
+
+export type useShowReturnType<TData extends BaseRecord = BaseRecord> = {
+    queryResult: QueryObserverResult<GetOneResponse<TData>>;
+    showId?: BaseKey;
+    setShowId: React.Dispatch<React.SetStateAction<BaseKey | undefined>>;
+};
+
+export type useShowProps<
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+> = {
+    /**
+     * Resource name for API data interactions
+     * @default Reads `:resource` from the URL
+     */
+    resource?: string;
+    /**
+     * Data item ID for API data interactions
+     * @default Reads `:id` from the URL
+     */
+    id?: BaseKey;
+    /**
+     * react-query's [useQuery](https://tanstack.com/query/v4/docs/reference/useQuery) options
+     */
+    queryOptions?: UseQueryOptions<GetOneResponse<TData>, HttpError>;
+    /**
+     * Additional meta data to pass to the data provider's `getOne`
+     */
+    meta?: MetaQuery;
+    /**
+     * Additional meta data to pass to the data provider's `getOne`
+     * @deprecated `metaData` is deprecated with refine@4, refine will pass `meta` instead, however, we still support `metaData` for backward compatibility.
+     */
+    metaData?: MetaQuery;
+    /**
+     * Target data provider name for API call to be made
+     * @default `"default"`
+     */
+    dataProviderName?: string;
+} & LiveModeProps &
+    SuccessErrorNotification;
+
+/**
+ * `useShow` hook allows you to fetch the desired record.
+ * It uses `getOne` method as query function from the dataProvider that is
+ * passed to {@link https://refine.dev/docs/api-references/components/refine-config `<Refine>`}.
+ *
+ * @see {@link https://refine.dev/docs/core/hooks/show/useShow} for more details.
+ */
+export const useShow = <
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+>({
+    resource: resourceFromProp,
+    id,
+    successNotification,
+    errorNotification,
+    meta,
+    metaData,
+    liveMode,
+    onLiveEvent,
+    dataProviderName,
+    queryOptions,
+}: useShowProps<TData, TError> = {}): useShowReturnType<TData> => {
+    const routerType = useRouterType();
+    const { resources } = useResource();
+    const { useParams } = useRouterContext();
+    const { resource: resourceFromRouter, id: idFromRouter } = useParsed();
+
+    const { resource: legacyResourceFromRoute, id: legacyIdFromParams } =
+        useParams<ResourceRouterParams>();
+
+    const newResourceNameFromRouter = resourceFromRouter?.name;
+
+    /** We only accept `id` from URL params if `resource` is not explicitly passed. */
+    /** This is done to avoid sending wrong requests for custom `resource` and an async `id` */
+    const defaultId =
+        !resourceFromProp ||
+        resourceFromProp ===
+            (routerType === "legacy"
+                ? legacyResourceFromRoute
+                : newResourceNameFromRouter)
+            ? id ??
+              (routerType === "legacy" ? legacyIdFromParams : idFromRouter)
+            : id;
+
+    const [showId, setShowId] = useState<BaseKey | undefined>(defaultId);
+
+    React.useEffect(() => {
+        if (defaultId !== showId) {
+            setShowId(defaultId);
+        }
+    }, [defaultId]);
+
+    /** `resourceName` fallback value depends on the router type */
+    const resourceName =
+        resourceFromProp ??
+        (routerType === "legacy"
+            ? legacyResourceFromRoute
+            : newResourceNameFromRouter);
+
+    let resource: IResourceItem | undefined;
+
+    const resourceWithRoute = useResourceWithRoute();
+
+    if (routerType === "legacy") {
+        if (resourceName) {
+            resource = resourceWithRoute(resourceName);
+        }
+    } else {
+        /** If `resource` is provided by the user, then try to pick the resource of create a dummy one */
+        if (resourceFromProp) {
+            const picked = pickResource(resourceFromProp, resources);
+            if (picked) {
+                resource = picked;
+            } else {
+                resource = {
+                    name: resourceFromProp,
+                    route: resourceFromProp,
+                };
+            }
+        } else {
+            /** If `resource` is not provided, check the resource from the router params */
+            if (typeof resourceFromRouter === "string") {
+                const picked = pickResource(resourceFromRouter, resources);
+                if (picked) {
+                    resource = picked;
+                } else {
+                    resource = {
+                        name: resourceFromRouter,
+                        route: resourceFromRouter,
+                    };
+                }
+            } else {
+                /** If `resource` is passed as an IResourceItem, use it or `resource` is undefined and cannot be inferred. */
+                resource = resourceFromRouter;
+            }
+        }
+    }
+
+    const queryResult = useOne<TData>({
+        resource: resource?.name,
+        id: showId ?? "",
+        queryOptions: {
+            enabled: showId !== undefined,
+            ...queryOptions,
+        },
+        successNotification,
+        errorNotification,
+        meta: pickNotDeprecated(meta, metaData),
+        metaData: pickNotDeprecated(meta, metaData),
+        liveMode,
+        onLiveEvent,
+        dataProviderName,
+    });
+
+    return {
+        queryResult,
+        showId,
+        setShowId,
+    };
+};

package/src/hooks/translate/index.ts

@@ -0,0 +1,3 @@
+export { useSetLocale } from "./useSetLocale";
+export { useTranslate } from "./useTranslate";
+export { useGetLocale } from "./useGetLocale";

package/src/hooks/translate/useGetLocale.ts

@@ -0,0 +1,16 @@
+import { useContext, useCallback } from "react";
+import { TranslationContext } from "@contexts/translation";
+
+export type UseGetLocaleType = () => () => string | undefined;
+
+/**
+ * If you need to know the current locale, refine provides the `useGetLocale` hook.
+ * It returns the `getLocale` method from `i18nProvider` under the hood.
+ *
+ * @see {@link https://refine.dev/docs/core/hooks/translate/useGetLocale} for more details.
+ */
+export const useGetLocale: UseGetLocaleType = () => {
+    const { i18nProvider } = useContext(TranslationContext);
+
+    return useCallback(() => i18nProvider?.getLocale(), []);
+};

package/src/hooks/translate/useSetLocale.ts

@@ -0,0 +1,14 @@
+import { useCallback, useContext } from "react";
+import { TranslationContext } from "@contexts/translation";
+
+/**
+ * If you need to change the locale at runtime, refine provides the `useSetLocale` hook.
+ * It returns the changeLocale method from `i18nProvider` under the hood.
+ *
+ * @see {@link https://refine.dev/docs/core/hooks/translate/useSetLocale} for more details.
+ */
+export const useSetLocale = () => {
+    const { i18nProvider } = useContext(TranslationContext);
+
+    return useCallback((lang: string) => i18nProvider?.changeLocale(lang), []);
+};

package/src/hooks/translate/useTranslate.ts

@@ -0,0 +1,40 @@
+import { useContext, useMemo } from "react";
+import { TranslationContext } from "@contexts/translation";
+
+/**
+ * If you need to translate the texts in your own components, refine provides the `useTranslate` hook.
+ * It returns the translate method from `i18nProvider` under the hood.
+ *
+ * @see {@link https://refine.dev/docs/core/hooks/translate/useTranslate} for more details.
+ */
+export const useTranslate = () => {
+    const { i18nProvider } = useContext(TranslationContext);
+
+    const fn = useMemo(() => {
+        function translate(
+            key: string,
+            options?: any,
+            defaultMessage?: string,
+        ): string;
+        function translate(key: string, defaultMessage?: string): string;
+
+        function translate(
+            key: string,
+            options?: string | any,
+            defaultMessage?: string,
+        ) {
+            return (
+                i18nProvider?.translate(key, options, defaultMessage) ??
+                defaultMessage ??
+                (typeof options === "string" &&
+                typeof defaultMessage === "undefined"
+                    ? options
+                    : key)
+            );
+        }
+
+        return translate;
+    }, [i18nProvider]);
+
+    return fn;
+};

package/src/hooks/useSelect/index.ts

@@ -0,0 +1,280 @@
+import { useCallback, useMemo, useState } from "react";
+import { QueryObserverResult, UseQueryOptions } from "@tanstack/react-query";
+import uniqBy from "lodash/uniqBy";
+import debounce from "lodash/debounce";
+import get from "lodash/get";
+
+import { useList, useMany } from "@hooks";
+import {
+    CrudSorting,
+    Option,
+    BaseRecord,
+    GetManyResponse,
+    GetListResponse,
+    CrudFilters,
+    SuccessErrorNotification,
+    HttpError,
+    LiveModeProps,
+    BaseKey,
+    Pagination,
+    MetaQuery,
+    Prettify,
+} from "../../interfaces";
+import { pickNotDeprecated } from "@definitions/helpers";
+import { pickResource } from "@definitions/helpers/pick-resource";
+import { useResource } from "../resource/useResource/index";
+
+export type UseSelectProps<TData, TError> = {
+    /**
+     * Resource name for API data interactions
+     */
+    resource: string;
+    /**
+     * Set the option's value
+     * @default `"title"`
+     */
+    optionLabel?: keyof TData extends string ? keyof TData : never;
+    /**
+     * Set the option's label value
+     * @default `"id"`
+     */
+    optionValue?: keyof TData extends string ? keyof TData : never;
+    /**
+     * Allow us to sort the options
+     * @deprecated Use `sorters` instead
+     */
+    sort?: CrudSorting;
+    /**
+     * Allow us to sort the options
+     */
+    sorters?: CrudSorting;
+    /**
+     * Resource name for API data interactions
+     */
+    filters?: CrudFilters;
+    /**
+     * Adds extra `options`
+     */
+    defaultValue?: BaseKey | BaseKey[];
+    /**
+     * The number of milliseconds to delay
+     * @default `300`
+     */
+    debounce?: number;
+    /**
+     * react-query [useQuery](https://react-query.tanstack.com/reference/useQuery) options
+     */
+    queryOptions?: UseQueryOptions<GetListResponse<TData>, TError>;
+    /**
+     * Pagination option from [`useList()`](/docs/api-reference/core/hooks/data/useList/)
+     * @type {  current?: number; pageSize?: number;}
+     * @default `undefined`
+     */
+    pagination?: Prettify<
+        Omit<Pagination, "mode"> & {
+            /**
+             * Whether to use server side pagination or not.
+             * @default "off"
+             */
+            mode?: Pagination["mode"];
+        }
+    >;
+    /**
+     * Disabling pagination option from [`useList()`](/docs/api-reference/core/hooks/data/useList/)
+     * @type boolean
+     * @default `false`
+     * @deprecated `hasPagination` is deprecated, use `pagination.mode` instead.
+     */
+    hasPagination?: boolean;
+    /**
+     * react-query [useQuery](https://react-query.tanstack.com/reference/useQuery) options
+     */
+    defaultValueQueryOptions?: UseQueryOptions<GetManyResponse<TData>, TError>;
+    /**
+     * If defined, this callback allows us to override all filters for every search request.
+     * @default `undefined`
+     */
+    onSearch?: (value: string) => CrudFilters;
+    /**
+     * Additional meta data to pass to the `useMany` from the data provider
+     */
+    meta?: MetaQuery;
+    /**
+     * Additional meta data to pass to the `useMany` from the data provider
+     * @deprecated `metaData` is deprecated with refine@4, refine will pass `meta` instead, however, we still support `metaData` for backward compatibility.
+     */
+    metaData?: MetaQuery;
+    /**
+     * If there is more than one `dataProvider`, you should use the `dataProviderName` that you will use.
+     * @default `default`
+     */
+    dataProviderName?: string;
+    /**
+     * Amount of records to fetch in select box list.
+     * @deprecated use [`pagination`](https://refine.dev/docs/api-reference/core/interfaceReferences/#pagination) instead
+     * @default `undefined`
+     */
+    fetchSize?: number;
+} & SuccessErrorNotification &
+    LiveModeProps;
+
+export type UseSelectReturnType<TData extends BaseRecord = BaseRecord> = {
+    queryResult: QueryObserverResult<GetListResponse<TData>>;
+    defaultValueQueryResult: QueryObserverResult<GetManyResponse<TData>>;
+    onSearch: (value: string) => void;
+    options: Option[];
+};
+
+export const useSelect = <
+    TData extends BaseRecord = BaseRecord,
+    TError extends HttpError = HttpError,
+>(
+    props: UseSelectProps<TData, TError>,
+): UseSelectReturnType<TData> => {
+    const [search, setSearch] = useState<CrudFilters>([]);
+    const [options, setOptions] = useState<Option[]>([]);
+    const [selectedOptions, setSelectedOptions] = useState<Option[]>([]);
+
+    const {
+        resource: resourceFromProps,
+        sort,
+        sorters,
+        filters = [],
+        optionLabel = "title",
+        optionValue = "id",
+        debounce: debounceValue = 300,
+        successNotification,
+        errorNotification,
+        defaultValueQueryOptions: defaultValueQueryOptionsFromProps,
+        queryOptions,
+        fetchSize,
+        pagination,
+        hasPagination = false,
+        liveMode,
+        defaultValue = [],
+        onLiveEvent,
+        onSearch: onSearchFromProp,
+        liveParams,
+        meta,
+        metaData,
+        dataProviderName,
+    } = props;
+
+    const { resources } = useResource();
+
+    /**
+     * Since `identifier` is an optional but prioritized way to match resources, users can provide identifier instead of resource name.
+     */
+    const pickedResource = pickResource(resourceFromProps, resources);
+
+    const resource = pickedResource?.name ?? resourceFromProps;
+
+    const defaultValues = Array.isArray(defaultValue)
+        ? defaultValue
+        : [defaultValue];
+
+    const defaultValueQueryOnSuccess = useCallback(
+        (data: GetManyResponse<TData>) => {
+            setSelectedOptions(
+                data.data.map((item) => ({
+                    label: get(item, optionLabel) as string,
+                    value: get(item, optionValue) as string,
+                })),
+            );
+        },
+        [optionLabel, optionValue],
+    );
+
+    const defaultValueQueryOptions =
+        defaultValueQueryOptionsFromProps ?? (queryOptions as any);
+
+    const defaultValueQueryResult = useMany<TData, TError>({
+        resource,
+        ids: defaultValues,
+        queryOptions: {
+            ...defaultValueQueryOptions,
+            enabled:
+                defaultValues.length > 0 &&
+                (defaultValueQueryOptionsFromProps?.enabled ?? true),
+            onSuccess: (data) => {
+                defaultValueQueryOnSuccess(data);
+                defaultValueQueryOptions?.onSuccess?.(data);
+            },
+        },
+        meta: pickNotDeprecated(meta, metaData),
+        metaData: pickNotDeprecated(meta, metaData),
+        liveMode: "off",
+        dataProviderName,
+    });
+
+    const defaultQueryOnSuccess = useCallback(
+        (data: GetListResponse<TData>) => {
+            {
+                setOptions(
+                    data.data.map((item) => ({
+                        label: get(item, optionLabel) as string,
+                        value: get(item, optionValue) as string,
+                    })),
+                );
+            }
+        },
+        [optionLabel, optionValue],
+    );
+
+    const queryResult = useList<TData, TError>({
+        resource,
+        sorters: pickNotDeprecated(sorters, sort),
+        filters: filters.concat(search),
+        pagination: {
+            current: pagination?.current,
+            pageSize: pagination?.pageSize ?? fetchSize,
+            mode: pagination?.mode,
+        },
+        hasPagination,
+        queryOptions: {
+            ...queryOptions,
+            onSuccess: (data) => {
+                defaultQueryOnSuccess(data);
+                queryOptions?.onSuccess?.(data);
+            },
+        },
+        successNotification,
+        errorNotification,
+        meta: pickNotDeprecated(meta, metaData),
+        metaData: pickNotDeprecated(meta, metaData),
+        liveMode,
+        liveParams,
+        onLiveEvent,
+        dataProviderName,
+    });
+
+    const onSearch = (value: string) => {
+        if (onSearchFromProp) {
+            setSearch(onSearchFromProp(value));
+            return;
+        }
+
+        if (!value) {
+            setSearch([]);
+            return;
+        } else {
+            setSearch([
+                {
+                    field: optionLabel,
+                    operator: "contains",
+                    value,
+                },
+            ]);
+        }
+    };
+
+    return {
+        queryResult,
+        defaultValueQueryResult,
+        options: useMemo(
+            () => uniqBy([...options, ...selectedOptions], "value"),
+            [options, selectedOptions],
+        ),
+        onSearch: debounce(onSearch, debounceValue),
+    };
+};