@refinedev/core 4.0.0

package/src/interfaces/bindings/resource.ts

@@ -0,0 +1,178 @@
+import { ReactNode, ComponentType } from "react";
+import { UseQueryResult } from "@tanstack/react-query";
+import { ILogData } from "src/interfaces";
+
+/**
+ * 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[];

package/src/interfaces/bindings/router.ts

@@ -0,0 +1,73 @@
+/**
+ * @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 { CrudFilters, CrudSorting } from "@contexts/data/IDataContext";
+import { IResourceItem } from "./resource";
+import { Action, BaseKey } from "..";
+
+export type GoConfig = {
+    to?: string;
+    query?: Record<string, unknown>;
+    hash?: string;
+    options?: {
+        keepQuery?: boolean;
+        keepHash?: boolean;
+    };
+    type?: "push" | "replace" | "path";
+};
+
+export type ParsedParams = {
+    filters?: CrudFilters;
+    sorters?: CrudSorting;
+    current?: number;
+    pageSize?: number;
+    [key: string & { _ignore?: boolean }]: any;
+};
+
+export type ParseResponse = {
+    params?: ParsedParams;
+    resource?: IResourceItem;
+    id?: BaseKey;
+    action?: Action;
+    pathname?: string;
+};
+
+export type GoFunction = (config: GoConfig) => void | string;
+
+export type BackFunction = () => void;
+
+export type ParseFunction = () => ParseResponse;
+
+export type RouterBindings = {
+    go?: () => GoFunction;
+    back?: () => BackFunction;
+    parse?: () => ParseFunction;
+    Link?: React.ComponentType<
+        React.PropsWithChildren<{ to: string; [prop: string]: any }>
+    >;
+};

package/src/interfaces/customComponents.ts

@@ -0,0 +1,28 @@
+import React, { ReactNode } from "react";
+
+export type TitleProps = {
+    collapsed: boolean;
+};
+
+export type LayoutProps = {
+    Sider?: React.FC<{
+        Title?: React.FC<TitleProps>;
+        render?: (props: {
+            items: JSX.Element[];
+            logout: React.ReactNode;
+            dashboard: React.ReactNode;
+            collapsed: boolean;
+        }) => React.ReactNode;
+        meta?: Record<string, unknown>;
+    }>;
+    Header?: React.FC;
+    Title?: React.FC<TitleProps>;
+    Footer?: React.FC;
+    OffLayoutArea?: React.FC;
+    dashboard?: boolean;
+    children?: ReactNode;
+};
+
+export type DashboardPageProps<TCrudData = any> = {
+    initialData?: TCrudData;
+} & Record<any, any>;

package/src/interfaces/form-url-params.ts

@@ -0,0 +1,8 @@
+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/interfaces/index.ts

@@ -0,0 +1,86 @@
+import { IResourceItem } from "./bindings/resource";
+
+// contexts
+export * from "../contexts/data/IDataContext";
+export * from "../contexts/live/ILiveContext";
+export * from "../contexts/auth/IAuthContext";
+export * from "../contexts/refine/IRefineContext";
+export * from "../contexts/translation/ITranslationContext";
+export * from "../contexts/undoableQueue/IUndoableQueueContext";
+export * from "../contexts/resource/IResourceContext";
+export * from "../contexts/unsavedWarn/IUnsavedWarnContext";
+export * from "../contexts/legacy-router/IRouterContext";
+export * from "../contexts/accessControl/IAccessControlContext";
+export * from "../contexts/notification/INotificationContext";
+export * from "../contexts/auditLog/IAuditLogContext";
+
+export * from "../components/pages/login";
+
+// actions
+export * from "./actions";
+
+// notification
+export * from "./notification";
+
+// mutationMode
+export * from "./mutationMode";
+
+// mutationMode
+export * from "./HttpError";
+
+// custom components
+export * from "./customComponents";
+
+// resourceRouterParams
+export * from "./resourceRouterParams";
+
+// resourceErrorRouterParams
+export * from "./resourceErrorRouterParams";
+
+// mapData
+export * from "./mapDataFn";
+
+// successErrorNotification
+export * from "./successErrorNotification";
+
+//metaData
+export * from "./metaData";
+
+//queryKeys
+export * from "./queryKey";
+
+//metaData
+export * from "./live";
+
+//auditLog
+export * from "./auditLog";
+
+export type BaseKey = string | number;
+export type BaseRecord = {
+    id?: BaseKey;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: any;
+};
+export interface Option {
+    label: string;
+    value: string;
+}
+
+/* Backward compatible version of 'TreeMenuItem' */
+export type ITreeMenu = IResourceItem & {
+    key?: string;
+    children: ITreeMenu[];
+};
+
+export type IMenuItem = IResourceItem & {
+    key: string;
+    route: string;
+};
+
+export * from "./form-url-params";
+
+export * from "./auth";
+
+export * from "./bindings";
+
+export * from "./prettify";

package/src/interfaces/live/LiveEvent.ts

@@ -0,0 +1,11 @@
+import { BaseKey } from "..";
+
+export type LiveEvent = {
+    channel: string;
+    type: "deleted" | "updated" | "created" | "*" | string;
+    payload: {
+        ids?: BaseKey[];
+        [x: string]: any;
+    };
+    date: Date;
+};

package/src/interfaces/live/LiveModeProps.ts

@@ -0,0 +1,28 @@
+import { LiveEvent } from ".";
+import { BaseKey } from "..";
+
+export type LiveModeProps = {
+    /**
+     * Whether to update data automatically ("auto") or not ("manual") if a related live event is received. The "off" value is used to avoid creating a subscription.
+     * @type  [`"auto" | "manual" | "off"`](/docs/api-reference/core/providers/live-provider/#livemode)
+     * @default `"off"`
+     */
+    liveMode?: "auto" | "manual" | "off";
+    /**
+     * Callback to handle all related live events of this hook.
+     * @type [`(event: LiveEvent) => void`](/docs/api-reference/core/interfaceReferences/#livemodeprops)
+     * @default `undefined`
+     */
+    onLiveEvent?: (event: LiveEvent) => void;
+    /**
+     * Params to pass to liveProvider's subscribe method if liveMode is enabled.
+     * @type [`{ ids?: BaseKey[]; [key: string]: any; }`](/docs/api-reference/core/interfaceReferences/#livemodeprops)
+     * @default `undefined`
+     */
+    liveParams?: {
+        ids?: BaseKey[];
+        [key: string]: any;
+    };
+};
+
+export type ILiveModeContextProvider = LiveModeProps;

package/src/interfaces/live/index.ts

@@ -0,0 +1,2 @@
+export * from "./LiveEvent";
+export * from "./LiveModeProps";

package/src/interfaces/mapDataFn.ts

@@ -0,0 +1,3 @@
+export interface MapDataFn<TItem, TVariables> {
+    (item: TItem, index?: number, items?: TItem[]): TVariables;
+}

package/src/interfaces/metaData/fields.ts

@@ -0,0 +1,3 @@
+import { NestedField } from "./nestedField";
+
+export type Fields = Array<string | object | NestedField>;

package/src/interfaces/metaData/index.ts

@@ -0,0 +1,2 @@
+export * from "./metaDataQuery";
+export * from "./metaQuery";

package/src/interfaces/metaData/metaDataQuery.ts

@@ -0,0 +1,10 @@
+import { QueryFunctionContext } from "@tanstack/react-query";
+import { QueryBuilderOptions } from "./queryBuilderOptions";
+
+/**
+ * @deprecated `MetaDataQuery` is deprecated with refine@4, use `MetaQuery` instead, however, we still support `MetaDataQuery` for backward compatibility.
+ */
+export type MetaDataQuery = {
+    [k: string]: any;
+    queryContext?: Omit<QueryFunctionContext, "meta">;
+} & QueryBuilderOptions;

package/src/interfaces/metaData/metaQuery.ts

@@ -0,0 +1,7 @@
+import { QueryFunctionContext } from "@tanstack/react-query";
+import { QueryBuilderOptions } from "./queryBuilderOptions";
+
+export type MetaQuery = {
+    [k: string]: any;
+    queryContext?: Omit<QueryFunctionContext, "meta">;
+} & QueryBuilderOptions;

package/src/interfaces/metaData/nestedField.ts

@@ -0,0 +1,8 @@
+import { Fields } from "./fields";
+import { QueryBuilderOptions } from "./queryBuilderOptions";
+
+export type NestedField = {
+    operation: string;
+    variables: QueryBuilderOptions[];
+    fields: Fields;
+};

package/src/interfaces/metaData/queryBuilderOptions.ts

@@ -0,0 +1,8 @@
+import { VariableOptions } from "./variableOptions";
+import { Fields } from "./fields";
+
+export interface QueryBuilderOptions {
+    operation?: string;
+    fields?: Fields;
+    variables?: VariableOptions;
+}

package/src/interfaces/metaData/variableOptions.ts

@@ -0,0 +1,9 @@
+export type VariableOptions =
+    | {
+          type?: string;
+          name?: string;
+          value: any;
+          list?: boolean;
+          required?: boolean;
+      }
+    | { [k: string]: any };

package/src/interfaces/mutationMode.ts

@@ -0,0 +1,29 @@
+import {
+    BaseRecord,
+    GetListResponse,
+    GetOneResponse,
+    IQueryKeys,
+} from "../interfaces";
+import { QueryKey } from "@tanstack/react-query";
+
+export type MutationMode = "pessimistic" | "optimistic" | "undoable";
+
+export type QueryResponse<T = BaseRecord> =
+    | GetListResponse<T>
+    | GetOneResponse<T>;
+
+export type PreviousQuery<TData> = [QueryKey, TData | unknown];
+
+export type PrevContext<TData> = {
+    previousQueries: PreviousQuery<TData>[];
+    queryKey: IQueryKeys;
+};
+
+export type Context = {
+    previousQueries: ContextQuery[];
+};
+
+export type ContextQuery<T = BaseRecord> = {
+    query: QueryResponse<T>;
+    queryKey: QueryKey;
+};

package/src/interfaces/notification.ts

@@ -0,0 +1,10 @@
+import { BaseKey } from ".";
+export interface IUndoableQueue {
+    id: BaseKey;
+    resource: string;
+    cancelMutation: () => void;
+    doMutation: () => void;
+    seconds: number;
+    isRunning: boolean;
+    isSilent: boolean;
+}

package/src/interfaces/prettify.ts

@@ -0,0 +1,3 @@
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/src/interfaces/queryKey.ts

@@ -0,0 +1,23 @@
+import { QueryKey } from "@tanstack/react-query";
+
+import { UseListConfig } from "@hooks/data/useList";
+import { BaseKey, CrudFilters, CrudSorting, Pagination } from "src/interfaces";
+
+export interface IQueryKeys {
+    all: QueryKey;
+    resourceAll: QueryKey;
+    list: (
+        config?:
+            | UseListConfig
+            | {
+                  pagination?: Required<Pagination>;
+                  hasPagination?: boolean;
+                  sorters?: CrudSorting;
+                  filters?: CrudFilters;
+              }
+            | undefined,
+    ) => QueryKey;
+    many: (ids?: BaseKey[]) => QueryKey;
+    detail: (id?: BaseKey) => QueryKey;
+    logList: (meta?: Record<number | string, any>) => QueryKey;
+}

package/src/interfaces/resourceErrorRouterParams.ts

@@ -0,0 +1,6 @@
+import { ActionWithPage } from "./actions";
+
+export type ResourceErrorRouterParams = {
+    resource: string;
+    action: ActionWithPage | undefined;
+};

package/src/interfaces/resourceRouterParams.ts

@@ -0,0 +1,7 @@
+import { RouteAction } from "./actions";
+
+export type ResourceRouterParams = {
+    resource: string;
+    id?: string;
+    action: RouteAction;
+};

package/src/interfaces/successErrorNotification.ts

@@ -0,0 +1,33 @@
+import { OpenNotificationParams } from ".";
+
+export type SuccessErrorNotification<
+    TData = unknown,
+    TError = unknown,
+    TVariables = unknown,
+> = {
+    /**
+     * Success notification configuration to be displayed when the mutation is successful.
+     * @default '"There was an error creating resource (status code: `statusCode`)" or "Error when updating resource (status code: statusCode)"' 
+
+     */
+    successNotification?:
+        | OpenNotificationParams
+        | false
+        | ((
+              data?: TData,
+              values?: TVariables,
+              resource?: string,
+          ) => OpenNotificationParams);
+    /**
+     * Error notification configuration to be displayed when the mutation fails.
+     * @default '"There was an error creating resource (status code: `statusCode`)" or "Error when updating resource (status code: statusCode)"'
+     */
+    errorNotification?:
+        | OpenNotificationParams
+        | false
+        | ((
+              error?: TError,
+              values?: TVariables,
+              resource?: string,
+          ) => OpenNotificationParams);
+};

package/src/interfaces/telementry.ts

@@ -0,0 +1,14 @@
+export type ITelemetryData = {
+    providers: {
+        auth?: boolean;
+        data?: boolean;
+        router?: boolean;
+        notification?: boolean;
+        live?: boolean;
+        auditLog?: boolean;
+        i18n?: boolean;
+        accessControl?: boolean;
+    };
+    version: string;
+    resourceCount: number;
+};

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "include": ["src", "types"],
+    "extends": "../../tsconfig.build.json",
+    "compilerOptions": {
+        "rootDir": "./src",
+        "baseUrl": ".",
+        "importHelpers": false,
+        "paths": {
+            "@components/*": ["src/components/*"],
+            "@components": ["src/components"],
+            "@containers/*": ["src/containers/*"],
+            "@containers": ["src/containers"],
+            "@pages/*": ["src/pages/*"],
+            "@pages": ["src/pages"],
+            "@contexts/*": ["src/contexts/*"],
+            "@contexts": ["src/contexts"],
+            "@dataProviders/*": ["src/dataProviders/*"],
+            "@dataProviders": ["src/dataProviders"],
+            "@hooks/*": ["src/hooks/*"],
+            "@hooks": ["src/hooks"],
+            "@test/*": ["test/*"],
+            "@test": ["test"],
+            "@definitions/*": ["src/definitions/*"],
+            "@definitions": ["src/definitions"]
+        },
+        "typeRoots": ["./types", "../../node_modules/@types"]
+    }
+}