@refinedev/core 4.47.2 → 4.49.0

package/src/contexts/resource/types.ts

@@ -0,0 +1,205 @@
+import { ComponentType, ReactNode } from "react";
+
+import { UseQueryResult } from "@tanstack/react-query";
+
+import { ILogData } from "../auditLog/types";
+
+/**
+ * Resource route components
+ */
+export type ResourceRouteComponent = ComponentType<
+  IResourceComponentsProps<any, any>
+>;
+
+export type ResourceRoutePath = string;
+
+export type ResourceRouteDefinition = {
+  path: ResourceRoutePath;
+  component: ResourceRouteComponent;
+};
+
+export type ResourceRouteComposition =
+  | ResourceRouteDefinition
+  | ResourceRoutePath
+  | ResourceRouteComponent;
+
+export interface IResourceComponents {
+  list?: ResourceRouteComposition;
+  create?: ResourceRouteComposition;
+  clone?: ResourceRouteComposition;
+  edit?: ResourceRouteComposition;
+  show?: ResourceRouteComposition;
+}
+
+export type AnyString = string & { __ignore?: never };
+
+export type ResourceAuditLogPermissions =
+  | "create"
+  | "update"
+  | "delete"
+  | AnyString;
+
+/** Resource `meta` */
+export interface KnownResourceMeta {
+  /**
+   * This is used when setting the document title, in breadcrumbs and `<Sider />` components.
+   * Therefore it will only work if the related components have implemented the `label` property.
+   */
+  label?: string;
+  /**
+   * Whether to hide the resource from the sidebar or not.
+   * This property is checked by the `<Sider />` components.
+   * Therefore it will only work if the `<Sider />` component has implemented the `hide` property.
+   */
+  hide?: boolean;
+  /**
+   * Dedicated data provider name for the resource.
+   * If not set, the default data provider will be used.
+   * You can use this property to pick a data provider for a resource when you have multiple data providers.
+   */
+  dataProviderName?: string;
+  /**
+   * To nest a resource under another resource, set the parent property to the name of the parent resource.
+   * This will work even if the parent resource is not explicitly defined.
+   */
+  parent?: string;
+  /**
+   * To determine if the resource has ability to delete or not.
+   */
+  canDelete?: boolean;
+  /**
+   * To permit the audit log for actions on the resource.
+   * @default All actions are permitted to be logged.
+   */
+  audit?: ResourceAuditLogPermissions[];
+  /**
+   * To pass `icon` to the resource.
+   */
+  icon?: ReactNode;
+}
+
+export interface DeprecatedOptions {
+  /**
+   * @deprecated Please use `audit` property instead.
+   */
+  auditLog?: {
+    permissions?: ResourceAuditLogPermissions[];
+  };
+  /**
+   * @deprecated Define the route in the resource components instead
+   */
+  route?: string;
+}
+
+export interface ResourceMeta extends KnownResourceMeta {
+  [key: string]: any;
+}
+
+export interface ResourceProps extends IResourceComponents {
+  name: string;
+  /**
+   * This property can be used to identify a resource. In some cases, `name` of the resource might be repeated in different resources.
+   * To avoid conflicts, you pass the `identifier` property to be used as the key of the resource.
+   * @default `name` of the resource
+   */
+  identifier?: string;
+  /**
+   * @deprecated This property is not used anymore.
+   */
+  key?: string;
+  /**
+   * @deprecated Please use the `meta` property instead.
+   */
+  options?: ResourceMeta & DeprecatedOptions;
+  /**
+   * To configure the resource, you can set `meta` properties. You can use `meta` to store any data related to the resource.
+   * There are some known `meta` properties that are used by the core and extension packages.
+   */
+  meta?: ResourceMeta & DeprecatedOptions;
+  /**
+   * @deprecated Please use the `meta.canDelete` property instead.
+   */
+  canDelete?: boolean;
+  /**
+   * @deprecated Please use the `meta.icon` property instead
+   */
+  icon?: ReactNode;
+  /**
+   * @deprecated Please use the `meta.parent` property instead
+   */
+  parentName?: string;
+}
+
+export interface RouteableProperties {
+  /**
+   * @deprecated Please use action props instead.
+   */
+  canCreate?: boolean;
+  /**
+   * @deprecated Please use action props instead.
+   */
+  canEdit?: boolean;
+  /**
+   * @deprecated Please use action props instead.
+   */
+  canShow?: boolean;
+  /**
+   * @deprecated Please use the `meta.canDelete` property instead.
+   */
+  canDelete?: boolean;
+}
+
+export interface IResourceComponentsProps<
+  TCrudData = any,
+  TLogQueryResult = ILogData,
+> extends RouteableProperties {
+  name?: string;
+  initialData?: TCrudData;
+  options?: ResourceMeta & DeprecatedOptions;
+  logQueryResult?: UseQueryResult<TLogQueryResult>;
+}
+
+export interface IResourceItem
+  extends IResourceComponents,
+    RouteableProperties,
+    ResourceProps {
+  /**
+   * @deprecated Please use the `meta.label` property instead.
+   */
+  label?: string;
+  /**
+   * @deprecated Please use action components and `getDefaultActionPath` helper instead.
+   */
+  route?: string;
+}
+
+export interface IResourceContext {
+  resources: IResourceItem[];
+}
+
+export type ResourceBindings = ResourceProps[];
+
+type MetaProps<TExtends = { [key: string]: any }> = ResourceMeta & TExtends;
+
+export interface RouteableProperties {
+  canCreate?: boolean;
+  canEdit?: boolean;
+  canShow?: boolean;
+  canDelete?: boolean;
+  canList?: boolean;
+}
+
+export interface IResourceContext {
+  resources: IResourceItem[];
+}
+
+/* Backward compatible version of 'TreeMenuItem' */
+export type ITreeMenu = IResourceItem & {
+  key?: string;
+  children: ITreeMenu[];
+};
+
+export type IMenuItem = IResourceItem & {
+  key: string;
+  route: string;
+};

package/src/contexts/router/index.tsx

@@ -1,17 +1,18 @@
 import React, { createContext, PropsWithChildren } from "react";
-import { RouterBindings } from "src/interfaces";
+import { RouterProvider } from "./types";
 
-const defaultBindings = {};
+const defaultRouterProvider = {};
 
-export const RouterBindingsContext =
-    createContext<RouterBindings>(defaultBindings);
+export const RouterContext = createContext<RouterProvider>(
+  defaultRouterProvider,
+);
 
-export const RouterBindingsProvider: React.FC<
-    PropsWithChildren<{ router?: RouterBindings }>
+export const RouterContextProvider: React.FC<
+  PropsWithChildren<{ router?: RouterProvider }>
 > = ({ children, router }) => {
-    return (
-        <RouterBindingsContext.Provider value={router ?? defaultBindings}>
-            {children}
-        </RouterBindingsContext.Provider>
-    );
+  return (
+    <RouterContext.Provider value={router ?? defaultRouterProvider}>
+      {children}
+    </RouterContext.Provider>
+  );
 };

package/src/contexts/router/legacy/index.tsx

@@ -0,0 +1,41 @@
+import React, { PropsWithChildren } from "react";
+
+import { ILegacyRouterContext } from "./types";
+
+export const defaultProvider: ILegacyRouterContext = {
+  useHistory: () => false,
+  useLocation: () => false,
+  useParams: () => ({}) as any,
+  Prompt: () => null,
+  Link: () => null,
+};
+
+export const LegacyRouterContext =
+  React.createContext<ILegacyRouterContext>(defaultProvider);
+
+export const LegacyRouterContextProvider: React.FC<
+  PropsWithChildren<Partial<ILegacyRouterContext>>
+> = ({
+  children,
+  useHistory,
+  useLocation,
+  useParams,
+  Prompt,
+  Link,
+  routes,
+}) => {
+  return (
+    <LegacyRouterContext.Provider
+      value={{
+        useHistory: useHistory ?? defaultProvider.useHistory,
+        useLocation: useLocation ?? defaultProvider.useLocation,
+        useParams: useParams ?? defaultProvider.useParams,
+        Prompt: Prompt ?? defaultProvider.Prompt,
+        Link: Link ?? defaultProvider.Link,
+        routes: routes ?? defaultProvider.routes,
+      }}
+    >
+      {children}
+    </LegacyRouterContext.Provider>
+  );
+};

package/src/contexts/router/legacy/types.ts

@@ -0,0 +1,50 @@
+import React from "react";
+
+import { Action } from "../types";
+
+export interface LegacyRouterProvider {
+  useHistory: () => {
+    push: (...args: any) => any;
+    replace: (...args: any) => any;
+    goBack: (...args: any) => any;
+  };
+  useLocation: () => {
+    search: string;
+    pathname: string;
+  };
+  useParams: <Params extends { [K in keyof Params]?: string } = {}>() => Params;
+  Prompt: React.FC<PromptProps>;
+  Link: React.FC<any>;
+  RouterComponent?: React.FC<any>;
+  routes?: any;
+}
+
+export interface ILegacyRouterContext {
+  useHistory: () => any;
+  useLocation: () => any;
+  useParams: <Params extends { [K in keyof Params]?: string } = {}>() => Params;
+  Prompt: React.FC<PromptProps>;
+  Link: React.FC<any>;
+  routes?: any;
+}
+
+export type PromptProps = {
+  message: string;
+  when?: boolean;
+  setWarnWhen?: (warnWhen: boolean) => void;
+};
+
+export type RouteAction = Exclude<Action, "list"> | undefined;
+
+export type ActionWithPage = Extract<Action, "show" | "create" | "edit">;
+
+export type ResourceRouterParams = {
+  resource: string;
+  id?: string;
+  action: RouteAction;
+};
+
+export type ResourceErrorRouterParams = {
+  resource: string;
+  action: ActionWithPage | undefined;
+};

package/src/contexts/router/picker/index.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+
+/**
+ * This context is used to determine which router to use.
+ *
+ * This is a temporary solution until we remove the legacy router.
+ */
+
+export const RouterPickerContext = React.createContext<"legacy" | "new">("new");
+
+export const RouterPickerProvider = RouterPickerContext.Provider;
+
+/**
+ * This is a temporary hook to determine which router to use.
+ * It will be removed once the legacy router is removed.
+ * @internal This is an internal hook.
+ */
+export const useRouterType = () => {
+  const value = React.useContext(RouterPickerContext);
+  return value;
+};

package/src/contexts/router/types.ts

@@ -0,0 +1,79 @@
+/**
+ * @author aliemir
+ *
+ * Router bindings interface, used to define the router bindings of refine.
+ *
+ * We're marking of the functions as optional, some features may not work properly but this is intentional.
+ * Users can choose to use the router bindings or not, or use their own router bindings.
+ * Leaving the control to the user is the best way to go.
+ *
+ * We're defining the functions as function generators, this is to allow the user to use hooks inside the functions.
+ *
+ * `go` function is used to navigate to a specific route. We're expecting a `GoConfig` object as the only parameter.
+ * Passing `query` as an object, will also let users to stringify the object as they like or ignore it completely or even use a custom logic to handle query strings.
+ *
+ * `back` function is used to navigate back to the previous route. It doesn't take any parameters.
+ * This one is a basic function for the back buttons, absence of this function can also hide the back button,
+ * but this depends on the UI package implementations.
+ *
+ * `parse` function is used to parse the current route, query parameters and other information.
+ * We're expecting this function to lead refine to the correct resource, action and id (again, not required but recommended).
+ * Also there's `params` property, which is used in data hooks and other places.
+ * This property has an interface to match but not restricted to it.
+ *
+ * Instead of a single `useNavigation` hook,
+ * we can separate those functions into three different hooks,
+ * `useGo`, `useBack` and `useParsed`
+ */
+
+import { BaseKey, CrudFilter, CrudSort } from "../data/types";
+import { IResourceItem } from "../resource/types";
+
+export type Action = "create" | "edit" | "list" | "show" | "clone";
+
+export type GoConfig = {
+  to?: string;
+  query?: Record<string, unknown>;
+  hash?: string;
+  options?: {
+    keepQuery?: boolean;
+    keepHash?: boolean;
+  };
+  type?: "push" | "replace" | "path";
+};
+
+export type ParsedParams<
+  TParams extends Record<string, any> = Record<string, any>,
+> = {
+  filters?: CrudFilter[];
+  sorters?: CrudSort[];
+  current?: number;
+  pageSize?: number;
+} & TParams;
+
+export type ParseResponse<
+  TParams extends Record<string, any> = Record<string, any>,
+> = {
+  params?: ParsedParams<TParams>;
+  resource?: IResourceItem;
+  id?: BaseKey;
+  action?: Action;
+  pathname?: string;
+};
+
+export type GoFunction = (config: GoConfig) => void | string;
+
+export type BackFunction = () => void;
+
+export type ParseFunction<
+  TParams extends Record<string, any> = Record<string, any>,
+> = () => ParseResponse<TParams>;
+
+export type RouterProvider = {
+  go?: () => GoFunction;
+  back?: () => BackFunction;
+  parse?: () => ParseFunction;
+  Link?: React.ComponentType<
+    React.PropsWithChildren<{ to: string; [prop: string]: any }>
+  >;
+};

package/src/contexts/undoableQueue/index.tsx

@@ -0,0 +1,82 @@
+import React, { createContext, useReducer, PropsWithChildren } from "react";
+
+import isEqual from "lodash/isEqual";
+
+import { UndoableQueue } from "../../components";
+import { ActionTypes, IUndoableQueue, IUndoableQueueContext } from "./types";
+
+export const UndoableQueueContext = createContext<IUndoableQueueContext>({
+  notifications: [],
+  notificationDispatch: () => false,
+});
+
+const initialState: IUndoableQueue[] = [];
+
+export const undoableQueueReducer = (state: IUndoableQueue[], action: any) => {
+  switch (action.type) {
+    case ActionTypes.ADD: {
+      const newState = state.filter((notificationItem: IUndoableQueue) => {
+        return !(
+          isEqual(notificationItem.id, action.payload.id) &&
+          notificationItem.resource === action.payload.resource
+        );
+      });
+
+      return [
+        ...newState,
+        {
+          ...action.payload,
+          isRunning: true,
+        },
+      ];
+    }
+    case ActionTypes.REMOVE:
+      return state.filter(
+        (notificationItem: IUndoableQueue) =>
+          !(
+            isEqual(notificationItem.id, action.payload.id) &&
+            notificationItem.resource === action.payload.resource
+          ),
+      );
+    case ActionTypes.DECREASE_NOTIFICATION_SECOND:
+      return state.map((notificationItem: IUndoableQueue) => {
+        if (
+          isEqual(notificationItem.id, action.payload.id) &&
+          notificationItem.resource === action.payload.resource
+        ) {
+          return {
+            ...notificationItem,
+            seconds: action.payload.seconds - 1000,
+          };
+        }
+        return notificationItem;
+      });
+    default:
+      return state;
+  }
+};
+
+export const UndoableQueueContextProvider: React.FC<PropsWithChildren> = ({
+  children,
+}) => {
+  const [notifications, notificationDispatch] = useReducer(
+    undoableQueueReducer,
+    initialState,
+  );
+
+  const notificationData = { notifications, notificationDispatch };
+
+  return (
+    <UndoableQueueContext.Provider value={notificationData}>
+      {children}
+      {typeof window !== "undefined"
+        ? notifications.map((notification) => (
+            <UndoableQueue
+              key={`${notification.id}-${notification.resource}-queue`}
+              notification={notification}
+            />
+          ))
+        : null}
+    </UndoableQueueContext.Provider>
+  );
+};

package/src/contexts/undoableQueue/types.ts

@@ -0,0 +1,22 @@
+import { BaseKey } from "../data/types";
+
+export enum ActionTypes {
+  ADD = "ADD",
+  REMOVE = "REMOVE",
+  DECREASE_NOTIFICATION_SECOND = "DECREASE_NOTIFICATION_SECOND",
+}
+
+export interface IUndoableQueue {
+  id: BaseKey;
+  resource: string;
+  cancelMutation: () => void;
+  doMutation: () => void;
+  seconds: number;
+  isRunning: boolean;
+  isSilent: boolean;
+}
+
+export interface IUndoableQueueContext {
+  notifications: IUndoableQueue[];
+  notificationDispatch: React.Dispatch<any>;
+}

package/src/contexts/unsavedWarn/index.tsx

@@ -1,17 +1,17 @@
-import React, { ReactNode, useState } from "react";
+import React, { useState, PropsWithChildren } from "react";
 
-import { IUnsavedWarnContext } from "./IUnsavedWarnContext";
+import { IUnsavedWarnContext } from "./types";
 
 export const UnsavedWarnContext = React.createContext<IUnsavedWarnContext>({});
 
-export const UnsavedWarnContextProvider: React.FC<{ children: ReactNode }> = ({
-    children,
+export const UnsavedWarnContextProvider: React.FC<PropsWithChildren> = ({
+  children,
 }) => {
-    const [warnWhen, setWarnWhen] = useState(false);
+  const [warnWhen, setWarnWhen] = useState(false);
 
-    return (
-        <UnsavedWarnContext.Provider value={{ warnWhen, setWarnWhen }}>
-            {children}
-        </UnsavedWarnContext.Provider>
-    );
+  return (
+    <UnsavedWarnContext.Provider value={{ warnWhen, setWarnWhen }}>
+      {children}
+    </UnsavedWarnContext.Provider>
+  );
 };

package/src/contexts/unsavedWarn/types.ts

@@ -0,0 +1,4 @@
+export interface IUnsavedWarnContext {
+  warnWhen?: boolean;
+  setWarnWhen?: (value: boolean) => void;
+}

package/src/definitions/helpers/async-debounce/index.ts

@@ -0,0 +1,67 @@
+import debounce from "lodash/debounce";
+
+// biome-ignore lint/suspicious/noExplicitAny: any is used to accept any function
+type Callbacks<T extends (...args: any) => any> = {
+  resolve?: (value: Awaited<ReturnType<T>>) => void;
+  // biome-ignore lint/suspicious/noExplicitAny: any is used to match the type of Promise.reject
+  reject?: (reason?: any) => void;
+};
+
+// biome-ignore lint/suspicious/noExplicitAny: any is used to accept any function
+type DebouncedFunction<T extends (...args: any) => any> = {
+  (...args: Parameters<T>): Promise<Awaited<ReturnType<T>>>;
+  flush: () => void;
+  cancel: () => void;
+};
+
+/**
+ * Debounces sync and async functions with given wait time. The debounced function returns a promise which can be awaited or catched.
+ * Only the last call of the debounced function will resolve or reject.
+ * Previous calls will be rejected with the given cancelReason.
+ *
+ * The original debounce function doesn't work well with async functions,
+ * It won't return a promise to resolve/reject and therefore it's not possible to await the result.
+ * This will always return a promise to handle and await the result.
+ * Previous calls will be rejected immediately after a new call made.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: any is used to accept any function
+export const asyncDebounce = <T extends (...args: any[]) => any>(
+  func: T,
+  wait = 1000,
+  cancelReason?: string,
+): DebouncedFunction<T> => {
+  let callbacks: Array<Callbacks<T>> = [];
+
+  const cancelPrevious = () => {
+    callbacks.forEach((cb) => cb.reject?.(cancelReason));
+    callbacks = [];
+  };
+
+  const debouncedFunc = debounce((...args: Parameters<T>) => {
+    const { resolve, reject } = callbacks.pop() || {};
+    Promise.resolve(func(...args))
+      .then(resolve)
+      .catch(reject);
+  }, wait);
+
+  const runner = (...args: Parameters<T>) => {
+    return new Promise<Awaited<ReturnType<T>>>((resolve, reject) => {
+      cancelPrevious();
+
+      callbacks.push({
+        resolve,
+        reject,
+      });
+
+      debouncedFunc(...args);
+    });
+  };
+
+  runner.flush = () => debouncedFunc.flush();
+  runner.cancel = () => {
+    debouncedFunc.cancel();
+    cancelPrevious();
+  };
+
+  return runner;
+};

package/src/definitions/helpers/check-router-prop-misuse/index.ts

@@ -1,30 +1,31 @@
-import { IRouterProvider, RouterBindings } from "src/interfaces";
+import { LegacyRouterProvider } from "../../../contexts/router/legacy/types";
+import { RouterProvider } from "../../../contexts/router/types";
 
 export const checkRouterPropMisuse = (
-    value: IRouterProvider | RouterBindings,
+  value: LegacyRouterProvider | RouterProvider,
 ) => {
-    // check if `routerProvider` prop is passed with legacy properties.
-    // If yes, console.warn the user to use `legacyRuterProvider` prop instead.
-    const bindings = ["go", "parse", "back", "Link"];
+  // check if `routerProvider` prop is passed with legacy properties.
+  // If yes, console.warn the user to use `legacyRuterProvider` prop instead.
+  const bindings = ["go", "parse", "back", "Link"];
 
-    // check if `value` contains properties other than `bindings`
-    const otherProps = Object.keys(value).filter(
-        (key) => !bindings.includes(key),
-    );
+  // check if `value` contains properties other than `bindings`
+  const otherProps = Object.keys(value).filter(
+    (key) => !bindings.includes(key),
+  );
 
-    const hasOtherProps = otherProps.length > 0;
+  const hasOtherProps = otherProps.length > 0;
 
-    if (hasOtherProps) {
-        console.warn(
-            `Unsupported properties are found in \`routerProvider\` prop. You provided \`${otherProps.join(
-                ", ",
-            )}\`. Supported properties are \`${bindings.join(
-                ", ",
-            )}\`. You may wanted to use \`legacyRouterProvider\` prop instead.`,
-        );
+  if (hasOtherProps) {
+    console.warn(
+      `Unsupported properties are found in \`routerProvider\` prop. You provided \`${otherProps.join(
+        ", ",
+      )}\`. Supported properties are \`${bindings.join(
+        ", ",
+      )}\`. You may wanted to use \`legacyRouterProvider\` prop instead.`,
+    );
 
-        return true;
-    }
+    return true;
+  }
 
-    return false;
+  return false;
 };