@refinedev/core 4.48.0 → 4.49.1

package/src/hooks/form/types.ts

@@ -0,0 +1,249 @@
+import { Dispatch, SetStateAction } from "react";
+import { QueryObserverResult, UseQueryOptions } from "@tanstack/react-query";
+
+import {
+  OptimisticUpdateMapType,
+  UseUpdateProps,
+  UseUpdateReturnType,
+} from "../data/useUpdate";
+import { UseCreateProps, UseCreateReturnType } from "../data/useCreate";
+import {
+  UseLoadingOvertimeOptionsProps,
+  UseLoadingOvertimeReturnType,
+} from "../useLoadingOvertime";
+import {
+  BaseKey,
+  BaseRecord,
+  CreateResponse,
+  GetOneResponse,
+  HttpError,
+  IQueryKeys,
+  MetaQuery,
+  MutationMode,
+  UpdateResponse,
+} from "../../contexts/data/types";
+import { LiveModeProps } from "../../contexts/live/types";
+import { SuccessErrorNotification } from "../../contexts/notification/types";
+import { Action } from "../../contexts/router/types";
+
+export type FormAction = Extract<Action, "create" | "edit" | "clone">;
+
+export type RedirectAction =
+  | Extract<Action, "create" | "edit" | "list" | "show">
+  | false;
+
+/**
+ * @deprecated use RedirectAction type instead
+ */
+export type RedirectionTypes = RedirectAction;
+
+export type AutoSaveProps<TVariables> = {
+  autoSave?: {
+    enabled: boolean;
+    debounce?: number;
+    onFinish?: (values: TVariables) => TVariables;
+    invalidateOnUnmount?: boolean;
+    invalidateOnClose?: boolean;
+  };
+};
+
+export type AutoSaveReturnType<
+  TData extends BaseRecord = BaseRecord,
+  TError extends HttpError = HttpError,
+  TVariables = {},
+> = {
+  autoSaveProps: Pick<
+    UseUpdateReturnType<TData, TError, TVariables>,
+    "data" | "error" | "status"
+  >;
+  onFinishAutoSave: (
+    values: TVariables,
+  ) => Promise<UpdateResponse<TData> | void>;
+};
+
+export type AutoSaveIndicatorElements = Partial<
+  Record<"success" | "error" | "loading" | "idle", React.ReactNode>
+>;
+
+export type ActionParams = {
+  /**
+   * Type of the form mode
+   * @default Action that it reads from route otherwise "create" is used
+   */
+  action?: FormAction;
+};
+
+type ActionFormProps<
+  TQueryFnData extends BaseRecord = BaseRecord,
+  TError extends HttpError = HttpError,
+  TVariables = {},
+  TData extends BaseRecord = TQueryFnData,
+  TResponse extends BaseRecord = TData,
+  TResponseError extends HttpError = TError,
+> = {
+  /**
+   * Resource name for API data interactions
+   * @default Resource name that it reads from route
+   */
+  resource?: string;
+  /**
+   * Record id for fetching
+   * @default Id that it reads from the URL
+   */
+  id?: BaseKey;
+  /**
+   * Page to redirect after a succesfull mutation
+   * @type `"show" | "edit" | "list" | "create" | false`
+   * @default `"list"`
+   */
+  redirect?: RedirectAction;
+  /**
+   * Metadata query for dataProvider
+   */
+  meta?: MetaQuery;
+  /**
+   * Metadata query for dataProvider
+   * @deprecated `metaData` is deprecated with refine@4, refine will pass `meta` instead, however, we still support `metaData` for backward compatibility.
+   */
+  metaData?: MetaQuery;
+  /**
+   * Metadata to pass for the `useOne` query
+   */
+  queryMeta?: MetaQuery;
+  /**
+   * Metadata to pass for the mutation (`useCreate` for `create` and `clone` actions, `useUpdate` for `edit` action)
+   */
+  mutationMeta?: MetaQuery;
+  /**
+   * [Determines when mutations are executed](/advanced-tutorials/mutation-mode.md)
+   * @default `"pessimistic"*`
+   */
+  mutationMode?: MutationMode;
+  /**
+   * Called when a mutation is successful
+   */
+  onMutationSuccess?: (
+    data: CreateResponse<TResponse> | UpdateResponse<TResponse>,
+    variables: TVariables,
+    context: any,
+    isAutoSave?: boolean,
+  ) => void;
+  /**
+   * Called when a mutation encounters an error
+   */
+  onMutationError?: (
+    error: TResponseError,
+    variables: TVariables,
+    context: any,
+    isAutoSave?: boolean,
+  ) => void;
+  /**
+   * Duration to wait before executing mutations when `mutationMode = "undoable"`
+   * @default `5000*`
+   */
+  undoableTimeout?: number;
+  /**
+   * If there is more than one `dataProvider`, you should use the `dataProviderName` that you will use.
+   */
+  dataProviderName?: string;
+  /**
+   * You can use it to manage the invalidations that will occur at the end of the mutation.
+   * @type  `all`, `resourceAll`, `list`, `many`, `detail`, `false`
+   * @default `["list", "many", "detail"]`
+   */
+  invalidates?: Array<keyof IQueryKeys>;
+  /**
+   * react-query's [useQuery](https://tanstack.com/query/v4/docs/reference/useQuery) options of useOne hook used while in edit mode.
+   */
+  queryOptions?: UseQueryOptions<
+    GetOneResponse<TQueryFnData>,
+    TError,
+    GetOneResponse<TData>
+  >;
+  /**
+   * react-query's [useMutation](https://tanstack.com/query/v4/docs/reference/useMutation) options of useCreate hook used while submitting in create and clone modes.
+   */
+  createMutationOptions?: UseCreateProps<
+    TResponse,
+    TResponseError,
+    TVariables
+  >["mutationOptions"];
+  /**
+   * react-query's [useMutation](https://tanstack.com/query/v4/docs/reference/useMutation) options of useUpdate hook used while submitting in edit mode.
+   */
+  updateMutationOptions?: UseUpdateProps<
+    TResponse,
+    TResponseError,
+    TVariables
+  >["mutationOptions"];
+  /**
+   * If you customize the [`optimisticUpdateMap`](https://refine.dev/docs/api-reference/core/hooks/data/useUpdateMany/#optimisticupdatemap) option, you can use it to manage the invalidations that will occur at the end of the mutation.
+   * @default {
+   *   list: true,
+   *   many: true,
+   *   detail: true,
+   * }
+   */
+  optimisticUpdateMap?: OptimisticUpdateMapType<TResponse, TVariables>;
+} & SuccessErrorNotification<
+  UpdateResponse<TResponse> | CreateResponse<TResponse>,
+  TResponseError,
+  { id: BaseKey; values: TVariables } | TVariables
+> &
+  ActionParams &
+  LiveModeProps;
+
+export type UseFormProps<
+  TQueryFnData extends BaseRecord = BaseRecord,
+  TError extends HttpError = HttpError,
+  TVariables = {},
+  TData extends BaseRecord = TQueryFnData,
+  TResponse extends BaseRecord = TData,
+  TResponseError extends HttpError = TError,
+> = ActionFormProps<
+  TQueryFnData,
+  TError,
+  TVariables,
+  TData,
+  TResponse,
+  TResponseError
+> &
+  ActionParams &
+  LiveModeProps &
+  UseLoadingOvertimeOptionsProps &
+  AutoSaveProps<TVariables>;
+
+export type UseFormReturnType<
+  TQueryFnData extends BaseRecord = BaseRecord,
+  TError extends HttpError = HttpError,
+  TVariables = {},
+  TData extends BaseRecord = TQueryFnData,
+  TResponse extends BaseRecord = TData,
+  TResponseError extends HttpError = TError,
+> = {
+  id?: BaseKey;
+  setId: Dispatch<SetStateAction<BaseKey | undefined>>;
+  queryResult?: QueryObserverResult<GetOneResponse<TData>, TError>;
+  mutationResult:
+    | UseUpdateReturnType<TResponse, TResponseError, TVariables>
+    | UseCreateReturnType<TResponse, TResponseError, TVariables>;
+  formLoading: boolean;
+  onFinish: (
+    values: TVariables,
+  ) => Promise<CreateResponse<TResponse> | UpdateResponse<TResponse> | void>;
+  redirect: (
+    redirect: RedirectAction,
+    idFromFunction?: BaseKey | undefined,
+    routeParams?: Record<string, string | number>,
+  ) => void;
+} & UseLoadingOvertimeReturnType &
+  AutoSaveReturnType<TResponse, TResponseError, TVariables>;
+
+export type FormWithSyncWithLocationParams = {
+  /**
+   * If true, the form will be synced with the location.
+   * If an object is passed, the key property will be used as the key for the query params.
+   * By default, query params are placed under the key, `${resource.name}-${action}`.
+   */
+  syncWithLocation?: boolean | { key?: string; syncId?: boolean };
+};

package/src/hooks/i18n/index.ts

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

package/src/hooks/i18n/useGetLocale.ts

@@ -0,0 +1,17 @@
+import { useCallback, useContext } from "react";
+
+import { I18nContext } from "@contexts/i18n";
+
+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/api-reference/core/hooks/translate/useGetLocale} for more details.
+ */
+export const useGetLocale: UseGetLocaleType = () => {
+  const { i18nProvider } = useContext(I18nContext);
+
+  return useCallback(() => i18nProvider?.getLocale(), []);
+};

package/src/hooks/i18n/useSetLocale.ts

@@ -0,0 +1,15 @@
+import { useCallback, useContext } from "react";
+
+import { I18nContext } from "@contexts/i18n";
+
+/**
+ * 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/api-reference/core/hooks/translate/useSetLocale} for more details.
+ */
+export const useSetLocale = () => {
+  const { i18nProvider } = useContext(I18nContext);
+
+  return useCallback((lang: string) => i18nProvider?.changeLocale(lang), []);
+};

package/src/hooks/i18n/useTranslate.ts

@@ -0,0 +1,40 @@
+import { useContext, useMemo } from "react";
+
+import { I18nContext } from "@contexts/i18n";
+
+/**
+ * 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/api-reference/core/hooks/translate/useTranslate} for more details.
+ */
+export const useTranslate = () => {
+  const { i18nProvider } = useContext(I18nContext);
+
+  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/i18n/useTranslation.tsx

@@ -0,0 +1,24 @@
+import { useGetLocale } from "./useGetLocale";
+import { useSetLocale } from "./useSetLocale";
+import { useTranslate } from "./useTranslate";
+
+/**
+ * It combines `useTranslate`, `useSetLocale` and `useGetLocale` hooks for a better developer experience.
+ * It returns `i18nProvider` methods under the hood.
+ * @returns `translate` method to translate the texts.
+ * @returns `changeLocale` method to change the locale
+ * @returns `getLocale` method to get the current locale.
+ *
+ * @see {@link https://refine.dev/docs/i18n/i18n-provider/} for more details.
+ */
+export const useTranslation = () => {
+  const translate = useTranslate();
+  const changeLocale = useSetLocale();
+  const getLocale = useGetLocale();
+
+  return {
+    translate,
+    changeLocale,
+    getLocale,
+  };
+};

package/src/hooks/import/index.tsx

@@ -1,16 +1,19 @@
 import { useEffect, useState } from "react";
-import { parse, ParseConfig } from "papaparse";
+
 import chunk from "lodash/chunk";
+import papaparse from "papaparse";
 
-import { useCreate, useCreateMany, useMeta, useResource } from "@hooks";
-import { MapDataFn, BaseRecord, HttpError, MetaQuery } from "../../interfaces";
 import {
   importCSVMapper,
-  sequentialPromises,
   pickNotDeprecated,
+  sequentialPromises,
 } from "@definitions";
+import { useCreate, useCreateMany, useMeta, useResource } from "@hooks";
+
+import { BaseRecord, HttpError, MetaQuery } from "../../contexts/data/types";
 import { UseCreateReturnType } from "../../hooks/data/useCreate";
 import { UseCreateManyReturnType } from "../../hooks/data/useCreateMany";
+import { MapDataFn } from "../export/types";
 
 export type ImportSuccessResult<TVariables, TData> = {
   request: TVariables[];
@@ -58,7 +61,7 @@ export type ImportOptions<
    * Custom Papa Parse options.
    * @type [`ParseConfig`](https://www.papaparse.com/docs)
    */
-  paparseOptions?: ParseConfig;
+  paparseOptions?: papaparse.ParseConfig;
   /**
    * Requests batch size. If it is 1, all records are sent one by one. By default, it is [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) to send all records in one batch. If it is more than 1, `createMany` should be implemented on DataProvider.
    */
@@ -205,7 +208,7 @@ export const useImport = <
     handleCleanup();
     return new Promise<CreatedValuesType<TVariables, TData>[]>((resolve) => {
       setIsLoading(true);
-      parse(file as any, {
+      papaparse.parse(file as any, {
         complete: async ({ data }: { data: unknown[][] }) => {
           const values = importCSVMapper(data, mapData);
 

package/src/hooks/index.ts

@@ -3,7 +3,7 @@ export * from "./data";
 export * from "./live";
 export * from "./resource";
 export * from "./notification";
-export * from "./translate";
+export * from "./i18n";
 export * from "./refine";
 export * from "./export";
 export * from "./form";
@@ -13,7 +13,7 @@ export * from "./show";
 export * from "./import";
 export * from "./modal";
 export * from "./router";
-export { useRouterType } from "../contexts/router-picker";
+export { useRouterType } from "../contexts/router/picker";
 export * from "./legacy-router";
 export * from "./accessControl";
 export * from "./useSelect";
@@ -24,3 +24,7 @@ export * from "./breadcrumb";
 export * from "./menu";
 export * from "./useMeta";
 export * from "./useLoadingOvertime";
+export * from "./useKeys";
+export * from "./use-refine-options";
+export * from "./use-resource-params";
+export * from "./button";

package/src/hooks/invalidate/index.tsx

@@ -1,14 +1,15 @@
 import { useCallback } from "react";
+
 import {
   InvalidateOptions,
   InvalidateQueryFilters,
   useQueryClient,
 } from "@tanstack/react-query";
 
-import { useResource } from "@hooks/resource";
 import { pickDataProvider } from "@definitions";
-import { BaseKey, IQueryKeys } from "../../interfaces";
-import { useKeys } from "@hooks/useKeys";
+import { useKeys, useResource } from "@hooks";
+
+import { BaseKey, IQueryKeys } from "../../contexts/data/types";
 
 export type UseInvalidateProp = {
   resource?: string;

package/src/hooks/legacy-router/useRouterContext.ts

@@ -1,8 +1,9 @@
 import { useContext } from "react";
-import { RouterContext, defaultProvider } from "@contexts/legacy-router";
+
+import { LegacyRouterContext, defaultProvider } from "@contexts/router/legacy";
 
 export const useRouterContext = () => {
-  const routerContextValues = useContext(RouterContext);
+  const routerContextValues = useContext(LegacyRouterContext);
 
   const { useHistory, useLocation, useParams, Prompt, Link, routes } =
     routerContextValues ?? defaultProvider;

package/src/hooks/live/useLiveMode/index.ts

@@ -1,7 +1,10 @@
 import { useContext } from "react";
-import { LiveModeProps, IRefineContext } from "../../../interfaces";
+
 import { RefineContext } from "@contexts/refine";
 
+import { LiveModeProps } from "../../../contexts/live/types";
+import { IRefineContext } from "../../../contexts/refine/types";
+
 export const useLiveMode = (
   liveMode: LiveModeProps["liveMode"],
 ): LiveModeProps["liveMode"] => {

package/src/hooks/live/usePublish/index.ts

@@ -1,10 +1,10 @@
 import { useContext } from "react";
 
 import { LiveContext } from "@contexts/live";
-import { ILiveContext } from "../../../interfaces";
+import { LiveProvider } from "../../../contexts/live/types";
 
-export const usePublish: () => NonNullable<ILiveContext>["publish"] = () => {
-  const liveContext = useContext<ILiveContext>(LiveContext);
+export const usePublish: () => NonNullable<LiveProvider>["publish"] = () => {
+  const { liveProvider } = useContext(LiveContext);
 
-  return liveContext?.publish;
+  return liveProvider?.publish;
 };

package/src/hooks/live/useResourceSubscription/index.ts

@@ -1,19 +1,19 @@
+import { useContext, useEffect } from "react";
+
 import { LiveContext } from "@contexts/live";
 import { RefineContext } from "@contexts/refine";
 import { useInvalidate } from "@hooks/invalidate";
 import { useResource } from "@hooks/resource";
-import { useContext, useEffect } from "react";
+
 import {
   BaseKey,
-  CrudFilters,
-  CrudSorting,
-  ILiveContext,
-  IRefineContext,
-  LiveEvent,
-  LiveModeProps,
+  CrudFilter,
+  CrudSort,
   MetaQuery,
   Pagination,
-} from "../../../interfaces";
+} from "../../../contexts/data/types";
+import { LiveEvent, LiveModeProps } from "../../../contexts/live/types";
+import { IRefineContext } from "../../../contexts/refine/types";
 
 export type UseResourceSubscriptionProps = {
   channel: string;
@@ -36,9 +36,9 @@ export type UseResourceSubscriptionProps = {
     /**
      * @deprecated `sort` is deprecated. Use `sorters` instead.
      */
-    sort?: CrudSorting;
-    sorters?: CrudSorting;
-    filters?: CrudFilters;
+    sort?: CrudSort[];
+    sorters?: CrudSort[];
+    filters?: CrudFilter[];
     subscriptionType: "useList" | "useOne" | "useMany";
     [key: string]: any;
   };
@@ -52,9 +52,7 @@ export type UseResourceSubscriptionProps = {
   meta?: MetaQuery & { dataProviderName?: string };
 } & LiveModeProps;
 
-export type PublishType = {
-  (event: LiveEvent): void;
-};
+export type PublishType = (event: LiveEvent) => void;
 
 export const useResourceSubscription = ({
   resource: resourceFromProp,
@@ -69,7 +67,7 @@ export const useResourceSubscription = ({
 }: UseResourceSubscriptionProps): void => {
   const { resource, identifier } = useResource(resourceFromProp);
 
-  const liveDataContext = useContext<ILiveContext>(LiveContext);
+  const { liveProvider } = useContext(LiveContext);
   const {
     liveMode: liveModeFromContext,
     onLiveEvent: onLiveEventContextCallback,
@@ -106,7 +104,7 @@ export const useResourceSubscription = ({
     };
 
     if (liveMode && liveMode !== "off" && enabled) {
-      subscription = liveDataContext?.subscribe({
+      subscription = liveProvider?.subscribe({
         channel,
         params: {
           resource: resource?.name,
@@ -124,7 +122,7 @@ export const useResourceSubscription = ({
 
     return () => {
       if (subscription) {
-        liveDataContext?.unsubscribe(subscription);
+        liveProvider?.unsubscribe(subscription);
       }
     };
   }, [enabled]);

package/src/hooks/live/useSubscription/index.ts

@@ -1,15 +1,15 @@
 import { useContext, useEffect } from "react";
 
 import { LiveContext } from "@contexts/live";
+
 import {
   BaseKey,
-  CrudFilters,
-  CrudSorting,
-  ILiveContext,
-  LiveEvent,
+  CrudFilter,
+  CrudSort,
   MetaQuery,
   Pagination,
-} from "../../../interfaces";
+} from "../../../contexts/data/types";
+import { LiveEvent } from "../../../contexts/live/types";
 
 export type UseSubscriptionProps = {
   /**
@@ -49,9 +49,9 @@ export type UseSubscriptionProps = {
     /**
      * @deprecated `sort` is deprecated, use `sorters` instead.
      */
-    sort?: CrudSorting;
-    sorters?: CrudSorting;
-    filters?: CrudFilters;
+    sort?: CrudSort[];
+    sorters?: CrudSort[];
+    filters?: CrudFilter[];
     subscriptionType?: "useList" | "useOne" | "useMany";
     resource?: string;
     [key: string]: any;
@@ -72,13 +72,13 @@ export const useSubscription = ({
   dataProviderName = "default",
   meta,
 }: UseSubscriptionProps): void => {
-  const liveDataContext = useContext<ILiveContext>(LiveContext);
+  const { liveProvider } = useContext(LiveContext);
 
   useEffect(() => {
     let subscription: any;
 
     if (enabled) {
-      subscription = liveDataContext?.subscribe({
+      subscription = liveProvider?.subscribe({
         channel,
         params,
         types,
@@ -93,7 +93,7 @@ export const useSubscription = ({
 
     return () => {
       if (subscription) {
-        liveDataContext?.unsubscribe(subscription);
+        liveProvider?.unsubscribe(subscription);
       }
     };
   }, [enabled]);

package/src/hooks/menu/useMenu.tsx

@@ -1,14 +1,16 @@
 import React from "react";
-import { useTranslate, useResource, useParsed, useRouterContext } from "..";
-import { useUserFriendlyName, pickNotDeprecated } from "@definitions";
-import { useRouterType } from "../../contexts/router-picker";
-import { createResourceKey } from "../../definitions/helpers/menu/create-resource-key";
-import { useGetToPath } from "../router/use-get-to-path/index";
+
+import { pickNotDeprecated, useUserFriendlyName } from "@definitions";
 import { getParentResource } from "@definitions/helpers/router";
+
+import { useParsed, useResource, useRouterContext, useTranslate } from "..";
+import { useRouterType } from "../../contexts/router/picker";
+import { createResourceKey } from "../../definitions/helpers/menu/create-resource-key";
 import {
   FlatTreeItem,
   createTree,
 } from "../../definitions/helpers/menu/create-tree";
+import { useGetToPath } from "../router/use-get-to-path/index";
 
 type UseMenuReturnType = {
   defaultOpenKeys: string[];
@@ -44,7 +46,7 @@ const getCleanPath = (pathname: string) => {
  * @see {@link https://refine.dev/docs/api-reference/core/hooks/ui/useMenu} for more details.
  */
 export const useMenu = (
-  { meta, hideOnMissingParameter }: UseMenuProps = {
+  { meta, hideOnMissingParameter = true }: UseMenuProps = {
     hideOnMissingParameter: true,
   },
 ): UseMenuReturnType => {

package/src/hooks/navigation/index.ts

@@ -1,12 +1,14 @@
-import { useRouterContext, useResource } from "@hooks";
-import { BaseKey, IResourceItem, MetaDataQuery } from "../../interfaces";
-import { useGo } from "@hooks/router/use-go";
-import { useParsed } from "@hooks/router/use-parsed";
-import { useRouterType } from "@contexts/router-picker";
-import { getActionRoutesFromResource } from "@definitions/helpers/router";
+import { useRouterType } from "@contexts/router/picker";
 import { pickResource } from "@definitions/helpers/pick-resource";
+import { getActionRoutesFromResource } from "@definitions/helpers/router";
 import { composeRoute } from "@definitions/helpers/router/compose-route";
+import { useResource, useRouterContext } from "@hooks";
 import { useBack } from "@hooks/router/use-back";
+import { useGo } from "@hooks/router/use-go";
+import { useParsed } from "@hooks/router/use-parsed";
+
+import { BaseKey, MetaDataQuery } from "../../contexts/data/types";
+import { IResourceItem } from "../../contexts/resource/types";
 
 export type HistoryType = "push" | "replace";