@vef-framework/core 1.0.134 → 2.0.0

package/dist/es/store/bound.js

@@ -0,0 +1,37 @@
+/*! @vef-framework/core v2.0.0 made with ❤️ by Venus | 2025-11-25T10:06:30.112Z */
+import { identity, constantCase } from '@vef-framework/shared';
+import { create } from 'zustand';
+import { subscribeWithSelector, persist, createJSONStorage } from 'zustand/middleware';
+import { immer } from 'zustand/middleware/immer';
+
+function createStore(initializer) {
+  const useStore = create()(
+    subscribeWithSelector(
+      immer(initializer)
+    )
+  );
+  return useStore;
+}
+function createPersistedStore(initializer, persistenceOptions) {
+  const {
+    name,
+    storage,
+    selector
+  } = persistenceOptions;
+  const useStore = create()(
+    subscribeWithSelector(
+      persist(
+        immer(initializer),
+        {
+          name: `__VEF_STORE__${constantCase(name)}__`,
+          version: 1,
+          storage: createJSONStorage(() => storage === "local" ? localStorage : sessionStorage),
+          partialize: selector ?? identity
+        }
+      )
+    )
+  );
+  return useStore;
+}
+
+export { createPersistedStore, createStore };

package/dist/es/store/index.js

@@ -0,0 +1,5 @@
+/*! @vef-framework/core v2.0.0 made with ❤️ by Venus | 2025-11-25T10:06:30.112Z */
+export { createPersistedStore, createStore } from './bound.js';
+export { createComponentStore } from './unbound.js';
+export { useDeep } from './use-deep.js';
+export { useShallow } from 'zustand/shallow';

package/dist/es/store/unbound.js

@@ -0,0 +1,70 @@
+/*! @vef-framework/core v2.0.0 made with ❤️ by Venus | 2025-11-25T10:06:30.112Z */
+import { jsx } from '@emotion/react/jsx-runtime';
+import { isPlainObject, mergeWith } from '@vef-framework/shared';
+import { useIsomorphicLayoutEffect } from 'motion/react';
+import { createContext, useRef, use } from 'react';
+import { createStore, useStore } from 'zustand';
+import { subscribeWithSelector } from 'zustand/middleware';
+import { immer } from 'zustand/middleware/immer';
+
+const contextCache = /* @__PURE__ */ new Map();
+function createComponentStore(name, initializer) {
+  const contextKey = `${name}StoreContext`;
+  let Context = contextCache.get(contextKey);
+  if (!Context) {
+    Context = createContext(null);
+    Context.displayName = contextKey;
+    contextCache.set(contextKey, Context);
+  }
+  function StoreProvider(props) {
+    const { children } = props;
+    const storeRef = useRef(null);
+    const storeInitializedRef = useRef(false);
+    const latestInitialStateRef = useRef(void 0);
+    latestInitialStateRef.current = props.initialState;
+    if (!storeRef.current || !storeInitializedRef.current) {
+      storeRef.current = createStore()(
+        subscribeWithSelector(
+          immer(initializer)
+        )
+      );
+      storeInitializedRef.current = true;
+    }
+    useIsomorphicLayoutEffect(() => {
+      if (!isPlainObject(latestInitialStateRef.current)) {
+        return;
+      }
+      if (storeRef.current) {
+        storeRef.current.setState((state) => {
+          mergeWith(
+            state,
+            latestInitialStateRef.current,
+            true
+          );
+        });
+      }
+    }, []);
+    return /* @__PURE__ */ jsx(Context, { value: storeRef.current, children });
+  }
+  function useStoreApi() {
+    const store = use(Context);
+    if (!store) {
+      const isDev = process.env.NODE_ENV === "development";
+      const errorMessage = `${name}Store is not found in the React context, please check if the store is wrapped in a ${name}StoreProvider`;
+      const devHint = isDev ? "\n\nDev hint: If you're seeing this error after hot reload, it might be a React Fast Refresh issue. Try refreshing the page." : "";
+      throw new Error(errorMessage + devHint);
+    }
+    return store;
+  }
+  function useStore$1(selector) {
+    const store = useStoreApi();
+    return useStore(store, selector);
+  }
+  return {
+    StoreProvider,
+    useStoreApi,
+    useStore: useStore$1
+  };
+}
+
+export { createComponentStore };

package/dist/es/store/use-deep.js

@@ -0,0 +1,13 @@
+/*! @vef-framework/core v2.0.0 made with ❤️ by Venus | 2025-11-25T10:06:30.112Z */
+import { isDeepEqual } from '@vef-framework/shared';
+import { useRef } from 'react';
+
+function useDeep(selector) {
+  const prevRef = useRef(null);
+  return (state) => {
+    const next = selector(state);
+    return isDeepEqual(prevRef.current, next) ? prevRef.current : prevRef.current = next;
+  };
+}
+
+export { useDeep };

package/dist/types/api/client.d.ts

@@ -0,0 +1,75 @@
+import { FetchQueryOptions, MutationOptions, QueryClient, QueryMeta } from '@tanstack/react-query';
+import { Awaitable, Except, If, IsNever, IsOptional } from '@vef-framework/shared';
+import { HttpClient } from '../http';
+import { ApiClientOptions, MutationFunction, QueryFunction, QueryKey } from './types';
+import { QUERY_CLIENT } from './constants';
+/**
+ * The API client.
+ */
+export declare class ApiClient {
+    #private;
+    /**
+     * The query client.
+     */
+    get [QUERY_CLIENT](): QueryClient;
+    /**
+     * Creates a new API client.
+     *
+     * @param options - The options for the API client.
+     */
+    constructor(options: ApiClientOptions);
+    /**
+     * Creates a new query function.
+     *
+     * @param key - The key of the query function.
+     * @param factory - The factory function.
+     * @returns The query function.
+     */
+    createQueryFn<TResult = unknown, TParams = never, TPageParam = never>(key: string, factory: (http: Readonly<HttpClient>) => (queryParams: TParams, pageParam: TPageParam, meta?: QueryMeta) => Awaitable<TResult>): QueryFunction<TResult, TParams, TPageParam>;
+    /**
+     * Creates a new mutation function.
+     *
+     * @param key - The key of the mutation function.
+     * @param factory - The factory function.
+     * @returns The mutation function.
+     */
+    createMutationFn<TResult = unknown, TParams = never>(key: string, factory: (http: Readonly<HttpClient>) => (params: TParams) => Awaitable<TResult>): MutationFunction<TResult, TParams>;
+    /**
+     * Fetches a query.
+     *
+     * @param options - The options for the query.
+     * @returns The result of the query.
+     */
+    fetchQuery<TQueryFnData = unknown, TData = TQueryFnData, TParams = unknown, TPageParam = never>(options: Except<FetchQueryOptions<TQueryFnData, Error, TData, QueryKey<TParams>, TPageParam>, "queryHash" | "queryKeyHashFn">): Promise<TData>;
+    /**
+     * Prefetches a query and stores the result in cache.
+     *
+     * @param options - The options for the query.
+     * @returns A promise that resolves when the prefetch is complete.
+     */
+    prefetchQuery<TQueryFnData = unknown, TData = TQueryFnData, TParams = unknown, TPageParam = never>(options: Except<FetchQueryOptions<TQueryFnData, Error, TData, QueryKey<TParams>, TPageParam>, "queryHash" | "queryKeyHashFn">): Promise<void>;
+    /**
+     * Executes a mutation outside of React components.
+     *
+     * This method allows you to execute mutations imperatively without using the `useMutation` hook.
+     * Useful for scenarios like login flows, event handlers, or any code outside React components.
+     *
+     * @template TData - The type of data returned by the mutation
+     * @template TParams - The type of parameters passed to the mutation function
+     * @template TOnMutateResult - The type of result returned by onMutate callback
+     *
+     * @param options - The mutation options including mutationFn, onSuccess, onError, etc.
+     * @param variables - The variables to pass to the mutation function. Omit this argument when the mutation does not require parameters.
+     * @remarks This reuses TanStack Query's imperative mutation execution so lifecycle callbacks (onMutate, onSuccess, etc.) still fire.
+     * @returns A promise that resolves with the mutation result
+     */
+    executeMutation<TData = unknown, TParams = unknown, TOnMutateResult = unknown>({ mutationFn, params, ...options }: Except<MutationOptions<TData, Error, TParams, TOnMutateResult>, "mutationKey" | "mutationFn"> & {
+        mutationFn: MutationFunction<TData, TParams>;
+    } & If<IsNever<TParams>, {
+        params?: never;
+    }, If<IsOptional<TParams>, {
+        params?: TParams;
+    }, {
+        params: TParams;
+    }>>): Promise<TData>;
+}

package/dist/types/api/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The proxied methods.
+ */
+export declare const PROXIED_METHODS: string[];
+/**
+ * The symbol for the query client.
+ */
+export declare const QUERY_CLIENT: unique symbol;

package/dist/types/api/helpers.d.ts

@@ -0,0 +1,9 @@
+import { ApiClientOptions } from './types';
+import { ApiClient } from './client';
+/**
+ * Creates a new API client.
+ *
+ * @param options - The options for the API client.
+ * @returns The API client.
+ */
+export declare function createApiClient(options: ApiClientOptions): ApiClient;

package/dist/types/api/index.d.ts

@@ -0,0 +1,4 @@
+export { ApiClient } from './client';
+export { QUERY_CLIENT } from './constants';
+export { createApiClient } from './helpers';
+export type * from './types';

package/dist/types/api/types.d.ts

@@ -0,0 +1,48 @@
+import { MutationFunction as MutationFunctionInternal, QueryFunction as QueryFunctionInternal } from '@tanstack/react-query';
+import { If, IsNever, Key } from '@vef-framework/shared';
+import { HttpClientOptions } from '../http';
+import { QueryClientOptions } from '../query';
+/**
+ * The options for the API client.
+ */
+export interface ApiClientOptions {
+    /**
+     * The options for the HTTP client.
+     */
+    http: HttpClientOptions;
+    /**
+     * The options for the query client.
+     */
+    query?: QueryClientOptions;
+}
+/**
+ * The key of the query.
+ *
+ * @param TParams - The parameters of the query.
+ */
+export type QueryKey<TParams = never> = readonly [Key, ...If<IsNever<TParams>, [], [TParams]>];
+/**
+ * The query function.
+ *
+ * @param TResult - The result of the query.
+ * @param TParams - The parameters of the query.
+ * @param TPageParam - The page parameter of the query.
+ */
+export interface QueryFunction<TData = unknown, TParams = never, TPageParam = never> extends QueryFunctionInternal<TData, QueryKey<TParams>, TPageParam> {
+    /**
+     * The API identifier.
+     */
+    key: Key;
+}
+/**
+ * The mutation function.
+ *
+ * @param TResult - The result of the mutation.
+ * @param TParams - The parameters of the mutation.
+ */
+export interface MutationFunction<TData = unknown, TParams = never> extends MutationFunctionInternal<TData, TParams> {
+    /**
+     * The API identifier.
+     */
+    key: Key;
+}

package/dist/types/auth/helpers.d.ts

@@ -0,0 +1,11 @@
+import { MaybeArray } from '@vef-framework/shared';
+import { PermissionCheckMode } from './types';
+/**
+ * Check if the user is authorized to access the resource identified by the permission token.
+ *
+ * @param hasPermission - The function to check if the user has the permission to access the resource identified by the token.
+ * @param permTokens - The permission tokens to check.
+ * @param checkMode - The check mode to use.
+ * @returns Whether the user is authorized to access the resource identified by the permission token.
+ */
+export declare function checkPermission(hasPermission: (token: string) => boolean, permTokens?: MaybeArray<string>, checkMode?: PermissionCheckMode): boolean;

package/dist/types/auth/index.d.ts

@@ -0,0 +1,2 @@
+export { checkPermission } from './helpers';
+export type * from './types';

package/dist/types/auth/types.d.ts

@@ -0,0 +1 @@
+export type PermissionCheckMode = "any" | "all";

package/dist/types/common/index.d.ts

@@ -0,0 +1 @@
+export type * from './types';

package/dist/types/common/types.d.ts

@@ -0,0 +1,95 @@
+import { AnyObject, EmptyObject, Except, Key } from '@vef-framework/shared';
+/**
+ * Pagination parameters for list queries.
+ * Used to specify which page and how many items per page to retrieve.
+ */
+export interface PaginationParams {
+    /**
+     * The page number, starting from 1
+     * @default 1
+     */
+    page?: number;
+    /**
+     * The number of items per page
+     * @default 15
+     */
+    size?: number;
+}
+/**
+ * Pagination result wrapper for paginated list responses.
+ * Contains the items for the current page and the total count across all pages.
+ *
+ * @template T - The type of items in the paginated list
+ */
+export interface PaginationResult<T = unknown> {
+    /**
+     * Total number of items across all pages
+     */
+    readonly total: number;
+    /**
+     * Items in the current page
+     */
+    readonly items: T[];
+}
+/**
+ * Base data option type for select, tree-select, cascader and other data-driven components.
+ *
+ * @template T - Additional custom fields that can be merged into the option
+ * @template M - Type of the metadata field
+ */
+export type DataOption<T = EmptyObject, M extends AnyObject = AnyObject> = T & {
+    /**
+     * Display text of the option
+     */
+    label: string;
+    /**
+     * Unique identifier of the option
+     */
+    value: Key;
+    /**
+     * Whether the option is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Additional description or help text for the option
+     */
+    description?: string;
+    /**
+     * Additional metadata for the option
+     */
+    meta?: M;
+    /**
+     * Child options for tree-like structures (e.g., TreeSelect, Cascader)
+     */
+    children?: Array<DataOption<T, M>>;
+};
+/**
+ * Data option with pinyin fields for Chinese character search and sorting.
+ * Extends {@link DataOption} with pinyin support to enable fuzzy search by pronunciation.
+ *
+ * @template T - Additional custom fields that can be merged into the option
+ * @template M - Type of the metadata field
+ */
+export type DataOptionWithPinyin<T = EmptyObject, M extends AnyObject = AnyObject> = Except<DataOption<T, M>, "children"> & {
+    /**
+     * Pinyin representation of the label
+     */
+    labelPinyin: string;
+    /**
+     * Initials of the pinyin representation of the label
+     */
+    labelPinyinInitials: string;
+    /**
+     * Pinyin representation of the description
+     */
+    descriptionPinyin?: string;
+    /**
+     * Initials of the pinyin representation of the description
+     */
+    descriptionPinyinInitials?: string;
+    /**
+     * Child options with pinyin support
+     */
+    children?: Array<DataOptionWithPinyin<T, M>>;
+};

package/dist/types/context/api-client.d.ts

@@ -0,0 +1,18 @@
+import { MaybeNull, SetFieldType } from '@vef-framework/shared';
+import { ComponentProps, Context } from 'react';
+import { ApiClient } from '../api';
+declare const Context: Context<MaybeNull<ApiClient>>;
+/**
+ * The provider for the API client.
+ *
+ * @param props - The props for the provider.
+ * @returns The provider for the API client.
+ */
+export declare function ApiClientProvider({ value, children }: SetFieldType<ComponentProps<typeof Context.Provider>, "value", ApiClient>): import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * The hook for the API client.
+ *
+ * @returns The API client.
+ */
+export declare function useApiClient(): ApiClient;
+export {};

package/dist/types/context/app.d.ts

@@ -0,0 +1,4 @@
+import { AppContext } from './types';
+import { Provider } from 'react';
+export declare const AppContextProvider: Provider<AppContext>;
+export declare function useAppContext(): AppContext;

package/dist/types/context/context-selector.d.ts

@@ -0,0 +1,44 @@
+import { ComponentType, PropsWithChildren } from 'react';
+/**
+ * Props for the selector context provider component
+ */
+export interface SelectorContextProviderProps<TValue> extends PropsWithChildren {
+    /**
+     * The value to provide to child components
+     */
+    value: TValue;
+}
+/**
+ * Context hook interface with optional selector support
+ */
+export interface UseSelectorContext<in out TValue> {
+    /**
+     * Use context without selector, returns the full value
+     */
+    <TStrictValue extends TValue = TValue>(): TStrictValue;
+    /**
+     * Use context with selector, returns the selected portion of the value
+     */
+    <TStrictValue extends TValue = TValue, TSelected = TStrictValue>(selector: (value: TStrictValue) => TSelected): NoInfer<TSelected>;
+}
+/**
+ * Result of creating a selector context
+ */
+export interface SelectorContextResult<TValue> {
+    /**
+     * Provider component to wrap child components
+     */
+    Provider: ComponentType<SelectorContextProviderProps<TValue>>;
+    /**
+     * Hook to access context value with optional selector
+     */
+    useContext: UseSelectorContext<TValue>;
+}
+/**
+ * Creates a context with selector support
+ * Allows consuming components to select specific parts of the context value for optimal re-rendering
+ *
+ * @param defaultValue - The default value for the context
+ * @returns An object containing the Provider component and useContext hook
+ */
+export declare function createContextWithSelector<TValue>(defaultValue: TValue): SelectorContextResult<TValue>;

package/dist/types/context/disabled.d.ts

@@ -0,0 +1,9 @@
+import { Provider } from 'react';
+/**
+ * A hook to get the disabled state.
+ */
+export declare function useDisabled(): boolean;
+/**
+ * A provider to provide the disabled state.
+ */
+export declare const DisabledProvider: Provider<boolean>;

package/dist/types/context/index.d.ts

@@ -0,0 +1,5 @@
+export { ApiClientProvider, useApiClient } from './api-client';
+export { AppContextProvider, useAppContext } from './app';
+export { createContextWithSelector, type SelectorContextProviderProps, type SelectorContextResult, type UseSelectorContext } from './context-selector';
+export { DisabledProvider, useDisabled } from './disabled';
+export type * from './types';

package/dist/types/context/types.d.ts

@@ -0,0 +1,27 @@
+import { QueryFunction } from '../api';
+import { DataOption } from '../common';
+/**
+ * The context of the vef app.
+ */
+export interface AppContext {
+    /**
+     * Whether the user is authorized to access the resource identified by the token.
+     *
+     * @example
+     * ```ts
+     * const isAuthorized = hasPermission("user:query");
+     * ```
+     *
+     * @param token - The permission token.
+     * @returns Whether the user has the permission to access the resource identified by the token.
+     */
+    hasPermission?: (token: string) => boolean;
+    /**
+     * The query function for the data dictionary.
+     */
+    dataDictQueryFn?: QueryFunction<DataOption[], string>;
+    /**
+     * The base URL for file access.
+     */
+    fileBaseUrl?: string;
+}

package/dist/types/dnd/index.d.ts

@@ -0,0 +1,6 @@
+export { AxisModifier, restrictShapeToBoundingRectangle, RestrictToHorizontalAxis, RestrictToVerticalAxis, SnapModifier } from '@dnd-kit/abstract/modifiers';
+export { RestrictToElement, RestrictToWindow } from '@dnd-kit/dom/modifiers';
+export { arrayMove as moveArrayItem, move as moveDragItem, arraySwap as swapArrayItem, swap as swapDragItem } from '@dnd-kit/helpers';
+export { DragDropProvider, DragOverlay, KeyboardSensor, PointerSensor, useDragDropMonitor, useDraggable, useDroppable, type DragDropEventHandlers, type DragDropEvents } from '@dnd-kit/react';
+export { useSortable } from '@dnd-kit/react/sortable';
+export { DragDropContext, Draggable, Droppable, type DragDropContextProps, type DraggableChildrenFn, type DraggableId, type DraggableLocation, type DraggableProps, type DraggableProvided, type DraggableProvidedDraggableProps, type DraggableProvidedDragHandleProps, type DraggableRubric, type DraggableStateSnapshot, type DroppableId, type DroppableProps, type DroppableProvided, type DroppableProvidedProps, type DroppableStateSnapshot, type DropResult, type OnBeforeCaptureResponder, type OnBeforeDragStartResponder, type OnDragEndResponder, type OnDragStartResponder, type OnDragUpdateResponder } from '@hello-pangea/dnd';

package/dist/types/http/client.d.ts

@@ -0,0 +1,144 @@
+import { AxiosProgressEvent } from 'axios';
+import { ApiResult, HttpClientOptions, RequestOptions } from './types';
+/**
+ * The header name for the skip authentication.
+ */
+export declare const skipAuthenticationHeader = "X-Skip-Authentication";
+/**
+ * The header value for the skip authentication.
+ */
+export declare const skipAuthenticationValue = "1";
+/**
+ * The HTTP client.
+ */
+export declare class HttpClient {
+    #private;
+    constructor(options: HttpClientOptions);
+    private initInterceptors;
+    /**
+     * Check if the code belongs to the target.
+     *
+     * @param code - The code.
+     * @param target - The target.
+     * @returns The result.
+     */
+    private isBelongsTo;
+    /**
+     * Handle the request.
+     *
+     * @param config - The axios request config.
+     * @returns The axios request config.
+     */
+    private handleRequest;
+    /**
+     * Handle the request error.
+     *
+     * @param error - The axios error.
+     */
+    private handleRequestError;
+    /**
+     * Handle the response.
+     *
+     * @param response - The axios response.
+     * @returns The axios response.
+     */
+    private handleResponse;
+    /**
+     * Handle the response error.
+     *
+     * @param error - The axios error.
+     */
+    private handleResponseError;
+    /**
+     * Injects access token into request Authorization header.
+     *
+     * @param config - The axios request config.
+     */
+    private setAccessToken;
+    /**
+     * Replace the path parameters in the URL.
+     *
+     * @param config - The axios request config.
+     * @returns The axios request config.
+     */
+    private replacePathParams;
+    /**
+     * Try to refresh the token using the provided refresh callback.
+     *
+     * @returns True if token refresh succeeded, false otherwise.
+     */
+    private tryRefreshToken;
+    /**
+     * Retry the request.
+     *
+     * @param config - The axios request config.
+     * @returns The axios response.
+     */
+    private retryRequest;
+    /**
+     * Get the resource.
+     *
+     * @param url - The url.
+     * @param options - The options for the request.
+     * @returns The response data.
+     */
+    get<R = unknown, P = unknown>(url: string, options?: RequestOptions & {
+        params?: P;
+    }): Promise<ApiResult<R>>;
+    /**
+     * Post the resource.
+     *
+     * @param url - The url.
+     * @param options - The options for the request.
+     * @returns The response data.
+     */
+    post<R = unknown, D = unknown, P = unknown>(url: string, options?: RequestOptions & {
+        data?: D;
+        params?: P;
+    }): Promise<ApiResult<R>>;
+    /**
+     * Update the resource.
+     *
+     * @param url - The url.
+     * @param options - The options for the request.
+     * @returns The response data.
+     */
+    put<R = unknown, D = unknown, P = unknown>(url: string, options?: RequestOptions & {
+        data?: D;
+        params?: P;
+    }): Promise<ApiResult<R>>;
+    /**
+     * Delete the resource.
+     *
+     * @param url - The url.
+     * @param options - The options for the request.
+     * @returns The response data.
+     */
+    delete<R = unknown, P = unknown>(url: string, options?: RequestOptions & {
+        params?: P;
+    }): Promise<ApiResult<R>>;
+    /**
+     * Upload the file.
+     *
+     * @param url - The url.
+     * @param options - The options for the request.
+     * @returns The response data.
+     */
+    upload<R = unknown, P = unknown>(url: string, options?: RequestOptions & {
+        params?: P;
+        data: FormData;
+        onProgress?: (event: AxiosProgressEvent) => void;
+    }): Promise<ApiResult<R>>;
+    /**
+     * Download the file.
+     *
+     * @param url - The url.
+     * @param options - The options for the request.
+     * @returns The response data.
+     */
+    download<P = unknown>(url: string, options?: RequestOptions & {
+        params?: P;
+        onProgress?: (progress: AxiosProgressEvent) => void;
+        filename?: string | ((filename: string) => string);
+    }): Promise<void>;
+}