@refinedev/core 4.48.0 → 4.49.0

package/src/hooks/router/use-router-misuse-warning/index.ts

@@ -1,8 +1,8 @@
 import { checkRouterPropMisuse } from "@definitions/helpers/check-router-prop-misuse";
 import React from "react";
-import { RouterBindings } from "src/interfaces";
+import { RouterProvider } from "../../../contexts/router/types";
 
-export const useRouterMisuseWarning = (value?: RouterBindings) => {
+export const useRouterMisuseWarning = (value?: RouterProvider) => {
   const warned = React.useRef(false);
 
   React.useEffect(() => {

package/src/hooks/router/use-to-path/index.ts

@@ -1,4 +1,5 @@
-import { Action, IResourceItem } from "../../../interfaces";
+import { IResourceItem } from "../../../contexts/resource/types";
+import { Action } from "../../../contexts/router/types";
 import { useGetToPath } from "../use-get-to-path";
 
 type UseToPathParams = {

package/src/hooks/show/index.ts

@@ -1 +1,92 @@
-export * from "./useShow";
+import warnOnce from "warn-once";
+import { useMeta, useOne, useResourceParams, useLoadingOvertime } from "@hooks";
+import { pickNotDeprecated } from "@definitions/helpers";
+
+import type { UseShowProps, UseShowReturnType } from "./types";
+import { BaseKey, BaseRecord, HttpError } from "../../contexts/data/types";
+
+export type {
+  UseShowProps,
+  UseShowReturnType,
+  useShowProps,
+  useShowReturnType,
+} from "./types";
+
+/**
+ * `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/core/refine-component `<Refine>`}.
+ *
+ * @see {@link https://refine.dev/docs/data/hooks/use-show} for more details.
+ *
+ * @typeParam TQueryFnData - Result data returned by the query function. Extends {@link https://refine.dev/docs/core/interface-references/#baserecord `BaseRecord`}
+ * @typeParam TError - Custom error object that extends {@link https://refine.dev/docs/core/interface-references/#httperror `HttpError`}
+ * @typeParam TData - Result data returned by the `select` function. Extends {@link https://refine.dev/docs/core/interface-references/#baserecord `BaseRecord`}. Defaults to `TQueryFnData`
+ *
+ */
+export const useShow = <
+  TQueryFnData extends BaseRecord = BaseRecord,
+  TError extends HttpError = HttpError,
+  TData extends BaseRecord = TQueryFnData,
+>({
+  resource: resourceFromProp,
+  id,
+  meta,
+  metaData,
+  queryOptions,
+  overtimeOptions,
+  ...useOneProps
+}: UseShowProps<TQueryFnData, TError, TData> = {}): UseShowReturnType<
+  TData,
+  TError
+> => {
+  const {
+    resource,
+    identifier,
+    id: showId,
+    setId: setShowId,
+  } = useResourceParams({
+    id,
+    resource: resourceFromProp,
+  });
+
+  const getMeta = useMeta();
+
+  const combinedMeta = getMeta({
+    resource,
+    meta: pickNotDeprecated(meta, metaData),
+  });
+
+  warnOnce(
+    Boolean(resourceFromProp) && !showId,
+    idWarningMessage(identifier, showId),
+  );
+
+  const queryResult = useOne<TQueryFnData, TError, TData>({
+    resource: identifier,
+    id: showId ?? "",
+    queryOptions: {
+      enabled: showId !== undefined,
+      ...queryOptions,
+    },
+    meta: combinedMeta,
+    metaData: combinedMeta,
+    ...useOneProps,
+  });
+
+  const { elapsedTime } = useLoadingOvertime({
+    isLoading: queryResult.isFetching,
+    interval: overtimeOptions?.interval,
+    onInterval: overtimeOptions?.onInterval,
+  });
+
+  return {
+    queryResult,
+    showId,
+    setShowId,
+    overtime: { elapsedTime },
+  };
+};
+
+const idWarningMessage = (identifier?: string, id?: BaseKey) =>
+  `[useShow]: resource: "${identifier}", id: ${id} \n\nIf you don't use the \`setShowId\` method to set the \`showId\`, you should pass the \`id\` prop to \`useShow\`. Otherwise, \`useShow\` will not be able to infer the \`id\` from the current URL. \n\nSee https://refine.dev/docs/data/hooks/use-show/#resource`;

package/src/hooks/show/types.ts

@@ -0,0 +1,92 @@
+import React from "react";
+
+import type {
+  QueryObserverResult,
+  UseQueryOptions,
+} from "@tanstack/react-query";
+
+import type {
+  UseLoadingOvertimeOptionsProps,
+  UseLoadingOvertimeReturnType,
+} from "../useLoadingOvertime";
+import {
+  BaseKey,
+  BaseRecord,
+  GetOneResponse,
+  HttpError,
+  MetaQuery,
+  Prettify,
+} from "../../contexts/data/types";
+import { LiveModeProps } from "../../contexts/live/types";
+import { SuccessErrorNotification } from "../../contexts/notification/types";
+
+export type UseShowReturnType<
+  TData extends BaseRecord = BaseRecord,
+  TError extends HttpError = HttpError,
+> = {
+  queryResult: QueryObserverResult<GetOneResponse<TData>, TError>;
+  showId?: BaseKey;
+  setShowId: React.Dispatch<React.SetStateAction<BaseKey | undefined>>;
+} & UseLoadingOvertimeReturnType;
+
+export type UseShowProps<
+  TQueryFnData extends BaseRecord = BaseRecord,
+  TError extends HttpError = HttpError,
+  TData extends BaseRecord = TQueryFnData,
+> = {
+  /**
+   * 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<TQueryFnData>,
+    TError,
+    GetOneResponse<TData>
+  >;
+  /**
+   * 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<
+    GetOneResponse<TData>,
+    TError,
+    Prettify<{ id?: BaseKey } & MetaQuery>
+  > &
+  UseLoadingOvertimeOptionsProps;
+
+/**
+ * @deprecated use `UseShowReturnType` instead
+ */
+export type useShowReturnType<
+  TData extends BaseRecord = BaseRecord,
+  TError extends HttpError = HttpError,
+> = UseShowReturnType<TData, TError>;
+
+/**
+ * @deprecated use `UseShowProps` instead
+ */
+export type useShowProps<
+  TQueryFnData extends BaseRecord = BaseRecord,
+  TError extends HttpError = HttpError,
+  TData extends BaseRecord = TQueryFnData,
+> = UseShowProps<TQueryFnData, TError, TData>;

package/src/hooks/show/useShow.ts

@@ -1,25 +1,26 @@
 import React, { useState } from "react";
+
 import { QueryObserverResult, UseQueryOptions } from "@tanstack/react-query";
 import warnOnce from "warn-once";
 
+import { pickNotDeprecated } from "@definitions/helpers";
 import { useMeta, useOne } from "@hooks";
 
 import {
+  BaseKey,
   BaseRecord,
   GetOneResponse,
-  SuccessErrorNotification,
-  MetaQuery,
-  LiveModeProps,
-  BaseKey,
   HttpError,
+  MetaQuery,
   Prettify,
-} from "../../interfaces";
+} from "../../contexts/data/types";
+import { LiveModeProps } from "../../contexts/live/types";
+import { SuccessErrorNotification } from "../../contexts/notification/types";
 import { useResource } from "../resource/useResource";
-import { pickNotDeprecated } from "@definitions/helpers";
 import {
-  useLoadingOvertime,
   UseLoadingOvertimeOptionsProps,
   UseLoadingOvertimeReturnType,
+  useLoadingOvertime,
 } from "../useLoadingOvertime";
 
 export type useShowReturnType<

package/src/hooks/use-refine-options/index.tsx

@@ -0,0 +1,8 @@
+import { RefineContext } from "@contexts/refine";
+import React from "react";
+
+export const useRefineOptions = () => {
+  const { options } = React.useContext(RefineContext);
+
+  return options;
+};

package/src/hooks/use-resource-params/index.ts

@@ -0,0 +1,89 @@
+import React from "react";
+
+import { useId } from "./use-id";
+import { useAction } from "./use-action";
+import { useResource } from "../resource";
+import { BaseKey } from "../../contexts/data/types";
+import { IResourceItem } from "../../contexts/resource/types";
+import { Action } from "../../contexts/router/types";
+import { FormAction } from "../form/types";
+
+type Props = {
+  id?: BaseKey;
+  resource?: string;
+  action?: Action;
+};
+
+type ResourceParams = {
+  id?: BaseKey;
+  setId: React.Dispatch<React.SetStateAction<BaseKey | undefined>>;
+  resource?: IResourceItem;
+  action?: Action;
+  identifier?: string;
+  formAction: FormAction;
+};
+
+/**
+ * Interactions in Refine has 3 main parameters: resource, action and id.
+ *
+ * This hook is used to manage these parameters based on below conditions and outputs the final parameters.
+ *
+ * `resource`: The resource to be used. (either the identifier or the name of the resource)
+ * - If a `resource` is provided, it will be used (even if it's not defined in the <Refine/> component)
+ * - If a `resource` is not provided, it will be inferred from the route.
+ * `id`: The `id` of the record to be used.
+ * - If an `id` is provided, it will be used.
+ * - If an `id` is not provided, it will either be inferred from the route or will be `undefined`.
+ * -- If a custom resource is provided and it's different from the inferred resource, the id will be undefined.
+ * -- If a custom resource is provided and it's same as the inferred resource, the id will be inferred from the route.
+ * -- If a custom resource is not provided, the id will be inferred from the route.
+ * `action`: The action to be used.
+ * - If an `action` is provided, it will be used.
+ * - If an `action` is not provided, it will be inferred from the route.
+ * `formAction`: The action to be used in the form.
+ * - `formAction` can only be "edit", "clone" or "create".
+ * - If action is "edit" or "clone", `formAction` will be the same as action.
+ * - Same as `id`, if passed resource is different from inferred resource, `formAction` will fallback to "create" and ignore the action from the route.
+ */
+export function useResourceParams(props?: Props): ResourceParams {
+  const { select, identifier: inferredIdentifier } = useResource();
+  const resourceToCheck = props?.resource ?? inferredIdentifier;
+  const { identifier = undefined, resource = undefined } = resourceToCheck
+    ? select(resourceToCheck, true)
+    : {};
+
+  const isSameResource = inferredIdentifier === identifier;
+  const inferredId = useId();
+  const action = useAction(props?.action);
+
+  const defaultId = React.useMemo(() => {
+    if (!isSameResource) return props?.id;
+
+    return props?.id ?? inferredId;
+  }, [isSameResource, props?.id, inferredId]);
+
+  const [id, setId] = React.useState<BaseKey | undefined>(defaultId);
+
+  React.useEffect(() => setId(defaultId), [defaultId]);
+
+  const formAction = React.useMemo(() => {
+    if (!isSameResource && !props?.action) {
+      return "create";
+    }
+
+    if (action === "edit" || action === "clone") {
+      return action;
+    }
+
+    return "create";
+  }, [action, isSameResource, props?.action]);
+
+  return {
+    id,
+    setId,
+    resource,
+    action,
+    identifier,
+    formAction,
+  };
+}

package/src/hooks/use-resource-params/use-action/index.tsx

@@ -0,0 +1,27 @@
+import { useParsed } from "../../router/use-parsed";
+import { useRouterContext } from "../../legacy-router/useRouterContext";
+import { Action } from "../../../contexts/router/types";
+import { useRouterType } from "../../../contexts/router/picker";
+import { ResourceRouterParams } from "../../../contexts/router/legacy/types";
+
+/**
+ * Returns the action from the router regardless of the router type.
+ * In legacy routers, `useParsed` won't work and in the new router bindings, `useParams` won't work.
+ * To make it easier to get the action from the router, this hook can be used.
+ *
+ * Additionally, if an action is provided as a parameter, it will be used instead of the inferred action.
+ *
+ * @internal usage only
+ */
+export const useAction = (action?: Action) => {
+  const routerType = useRouterType();
+  const { useParams } = useRouterContext();
+
+  const parsed = useParsed();
+  const legacyParams = useParams<Partial<ResourceRouterParams>>();
+
+  const inferredAction =
+    routerType === "legacy" ? legacyParams.action : parsed.action;
+
+  return action ?? inferredAction;
+};

package/src/hooks/use-resource-params/use-id/index.tsx

@@ -0,0 +1,26 @@
+import { useParsed } from "../../router/use-parsed";
+import { useRouterContext } from "../../legacy-router/useRouterContext";
+import { BaseKey } from "../../../contexts/data/types";
+import { useRouterType } from "../../../contexts/router/picker";
+import { ResourceRouterParams } from "../../../contexts/router/legacy/types";
+
+/**
+ * Returns the id from the router regardless of the router type.
+ * In legacy routers, `useParsed` won't work and in the new router bindings, `useParams` won't work.
+ * To make it easier to get the id from the router, this hook can be used.
+ *
+ * Additionally, if an id is provided as a parameter, it will be used instead of the inferred id.
+ *
+ * @internal usage only
+ */
+export const useId = (id?: BaseKey) => {
+  const routerType = useRouterType();
+  const { useParams } = useRouterContext();
+
+  const parsed = useParsed();
+  const legacyParams = useParams<Partial<ResourceRouterParams>>();
+
+  const inferredId = routerType === "legacy" ? legacyParams.id : parsed.id;
+
+  return id ?? inferredId;
+};

package/src/hooks/useMeta/index.ts

@@ -1,6 +1,8 @@
-import { useParsed } from "@hooks/router";
 import { sanitizeResource } from "@definitions/helpers/sanitize-resource";
-import { IResourceItem, MetaQuery } from "../../interfaces";
+import { useParsed } from "@hooks/router";
+
+import { MetaQuery } from "../../contexts/data/types";
+import { IResourceItem } from "../../contexts/resource/types";
 
 /**
  * Hook that returns a function to get meta.

package/src/hooks/useSelect/index.ts

@@ -1,32 +1,34 @@
 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 uniqBy from "lodash/uniqBy";
 
+import { pickNotDeprecated } from "@definitions/helpers";
 import { useList, useMany, useMeta } from "@hooks";
+
 import {
-  CrudSorting,
+  BaseKey,
   BaseOption,
   BaseRecord,
-  GetManyResponse,
+  CrudFilter,
+  CrudSort,
   GetListResponse,
-  CrudFilters,
-  SuccessErrorNotification,
+  GetManyResponse,
   HttpError,
-  LiveModeProps,
-  BaseKey,
-  Pagination,
   MetaQuery,
+  Pagination,
   Prettify,
-} from "../../interfaces";
-import { pickNotDeprecated } from "@definitions/helpers";
-import { useResource } from "../resource/useResource/index";
+} from "../../contexts/data/types";
+import { LiveModeProps } from "../../contexts/live/types";
+import { SuccessErrorNotification } from "../../contexts/notification/types";
 import { BaseListProps } from "../data/useList";
+import { useResource } from "../resource/useResource/index";
 import {
-  useLoadingOvertime,
   UseLoadingOvertimeOptionsProps,
   UseLoadingOvertimeReturnType,
+  useLoadingOvertime,
 } from "../useLoadingOvertime";
 
 export type UseSelectProps<TQueryFnData, TError, TData> = {
@@ -66,15 +68,15 @@ export type UseSelectProps<TQueryFnData, TError, TData> = {
    * Allow us to sort the options
    * @deprecated Use `sorters` instead
    */
-  sort?: CrudSorting;
+  sort?: CrudSort[];
   /**
    * Allow us to sort the options
    */
-  sorters?: CrudSorting;
+  sorters?: CrudSort[];
   /**
    * Resource name for API data interactions
    */
-  filters?: CrudFilters;
+  filters?: CrudFilter[];
   /**
    * Adds extra `options`
    */
@@ -124,7 +126,7 @@ export type UseSelectProps<TQueryFnData, TError, TData> = {
    * If defined, this callback allows us to override all filters for every search request.
    * @default `undefined`
    */
-  onSearch?: (value: string) => CrudFilters;
+  onSearch?: (value: string) => CrudFilter[];
   /**
    * Additional meta data to pass to the `useMany` from the data provider
    */
@@ -186,7 +188,7 @@ export const useSelect = <
 >(
   props: UseSelectProps<TQueryFnData, TError, TData>,
 ): UseSelectReturnType<TData, TError, TOption> => {
-  const [search, setSearch] = useState<CrudFilters>([]);
+  const [search, setSearch] = useState<CrudFilter[]>([]);
   const [options, setOptions] = useState<TOption[]>([]);
   const [selectedOptions, setSelectedOptions] = useState<TOption[]>([]);
 
@@ -290,17 +292,15 @@ export const useSelect = <
 
   const defaultQueryOnSuccess = useCallback(
     (data: GetListResponse<TData>) => {
-      {
-        setOptions(
-          data.data.map(
-            (item) =>
-              ({
-                label: getOptionLabel(item),
-                value: getOptionValue(item),
-              }) as TOption,
-          ),
-        );
-      }
+      setOptions(
+        data.data.map(
+          (item) =>
+            ({
+              label: getOptionLabel(item),
+              value: getOptionValue(item),
+            }) as TOption,
+        ),
+      );
     },
     [optionLabel, optionValue],
   );