@vef-framework/starter 1.0.135 → 2.0.2

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

@@ -0,0 +1,24 @@
+/**
+ * The route path of the login page.
+ */
+export declare const LOGIN_ROUTE_PATH = "/login";
+/**
+ * The route id of the login page.
+ */
+export declare const LOGIN_ROUTE_ID = "/_common/login";
+/**
+ * The route path of the index page.
+ */
+export declare const INDEX_ROUTE_PATH = "/";
+/**
+ * The route id of the index page.
+ */
+export declare const INDEX_ROUTE_ID = "/_layout";
+/**
+ * The route path of the access denied page.
+ */
+export declare const ACCESS_DENIED_ROUTE_PATH = "/access-denied";
+/**
+ * The route id of the access denied page.
+ */
+export declare const ACCESS_DENIED_ROUTE_ID = "/_common/access-denied";

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

@@ -0,0 +1,8 @@
+/**
+ * The prefix of the storage key.
+ */
+export declare const STORAGE_KEY_PREFIX_STORE = "__VEF_STORE__";
+/**
+ * The suffix of the storage key.
+ */
+export declare const STORAGE_KEY_SUFFIX_STORE = "__";

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

@@ -0,0 +1,8 @@
+/**
+ * Global symbol for marking pagination metadata in request parameters.
+ */
+export declare const SYMBOL_PAGINATION: unique symbol;
+/**
+ * Global symbol for marking sort/order metadata in request parameters.
+ */
+export declare const SYMBOL_SORT: unique symbol;

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

@@ -0,0 +1,9 @@
+import { AnyRouter } from '@tanstack/react-router';
+import { HttpClientOptions, QueryClientOptions, ApiClient } from '@vef-framework/core';
+import { Awaitable } from '@vef-framework/shared';
+export interface ApiClientOptions {
+    getRouter: () => Awaitable<AnyRouter>;
+    http: Pick<HttpClientOptions, "baseUrl" | "timeout" | "okCode" | "tokenExpiredCode" | "refreshToken">;
+    query?: Pick<QueryClientOptions, "gcTime" | "staleTime">;
+}
+export declare function createApiClient({ getRouter, http, query }: ApiClientOptions): ApiClient;

package/dist/types/helpers/app-version.d.ts

@@ -0,0 +1,88 @@
+import { ReactNode } from 'react';
+/**
+ * Application changelog structure
+ */
+export interface AppChangelog {
+    /**
+     * Version number
+     */
+    version: string;
+    /**
+     * Release date
+     */
+    date?: string;
+    /**
+     * Detailed description
+     */
+    description?: string;
+    /**
+     * List of changes in this version
+     */
+    changes?: string[];
+}
+/**
+ * Configuration options for app version notification
+ */
+export interface AppVersionNotificationOptions {
+    /**
+     * Whether to enable automatic update detection
+     *
+     * Recommended to set this to `import.meta.env.PROD` in your application,
+     * so it only runs in production builds.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Base path for all requests (e.g., "/app", "/static")
+     *
+     * This will be prepended to all URL requests for index.html and changelog.json
+     *
+     * @default "/"
+     */
+    basePath?: string;
+    /**
+     * The interval (in seconds) to check for updates
+     *
+     * @default 60
+     */
+    checkInterval?: number;
+    /**
+     * Custom notification title
+     */
+    title?: ReactNode;
+    /**
+     * Custom notification description
+     */
+    description?: ReactNode;
+    /**
+     * Custom confirm button text
+     */
+    confirmText?: ReactNode;
+    /**
+     * Custom cancel button text
+     */
+    cancelText?: ReactNode;
+    /**
+     * Callback when user confirms update
+     */
+    onConfirm?: () => void;
+    /**
+     * Callback when user cancels update
+     */
+    onCancel?: () => void;
+}
+/**
+ * Setup automatic app version notification
+ *
+ * This function monitors for app version changes by comparing the current version
+ * with the version in the deployed HTML file. When a new version is detected,
+ * it shows a notification prompting the user to refresh the page.
+ *
+ * The version is obtained from the `<meta name="app-version">` tag in the HTML.
+ * It uses semantic versioning comparison via the `compare-versions` library.
+ *
+ * @param options - Configuration options
+ * @returns A cleanup function to stop version checking
+ */
+export declare function setupAppVersionNotification(options?: AppVersionNotificationOptions): (() => void) | undefined;

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

@@ -0,0 +1,24 @@
+import { AnyRouter, RegisteredRouter } from '@tanstack/react-router';
+import { AppProps, UseRouterContext } from '../components';
+/**
+ * Configuration options for creating an app instance
+ */
+export interface AppOptions<TRouter extends AnyRouter = RegisteredRouter, TDehydrated extends Record<string, any> = Record<string, any>> {
+    /**
+     * Whether to enable React's StrictMode for development checks
+     */
+    strictMode?: boolean;
+    /**
+     * Custom hook for accessing router context
+     */
+    useRouterContext?: UseRouterContext<TRouter, TDehydrated>;
+}
+/**
+ * Create the app
+ *
+ * @returns The app
+ */
+export declare function createApp<TRouter extends AnyRouter = RegisteredRouter, TDehydrated extends Record<string, any> = Record<string, any>>({ strictMode, useRouterContext }?: AppOptions<TRouter, TDehydrated>): {
+    render(props: AppProps): void;
+    unmount(): void;
+};

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

@@ -0,0 +1,7 @@
+import { AnyRouter } from '@tanstack/react-router';
+/**
+ * Handles the client logout process.
+ *
+ * @param router - The router instance.
+ */
+export declare function handleClientLogout(router: AnyRouter): Promise<void>;

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

@@ -0,0 +1,16 @@
+import { EventEmitter } from '@vef-framework/shared';
+export declare const eventEmitter: EventEmitter<{
+    __vef_reload_page_event: string;
+}>;
+/**
+ * Dispatch a custom event.
+ *
+ * @param type - The type of event to dispatch.
+ */
+export declare function dispatchCustomEvent<T = any>(type: string, options?: CustomEventInit<T>): boolean;
+/**
+ * Reload the page.
+ *
+ * @param key - The key of the page to reload.
+ */
+export declare function reloadPage(key: string): void;

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

@@ -0,0 +1,7 @@
+export { createApiClient, type ApiClientOptions } from './api';
+export { createApp } from './app';
+export { setupAppVersionNotification, type AppChangelog, type AppVersionNotificationOptions } from './app-version';
+export { handleClientLogout } from './auth';
+export { dispatchCustomEvent, eventEmitter, reloadPage } from './event';
+export { extractQueryParams, noopMutationFn } from './query';
+export { createRouter, type RouterOptions } from './router';

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

@@ -0,0 +1,33 @@
+import { PaginationParams } from '@vef-framework/core';
+import { MaybeUndefined } from '@vef-framework/shared';
+import { OrderSpec } from '../types';
+import { SYMBOL_PAGINATION, SYMBOL_SORT } from '../constants';
+/**
+ * A no-operation mutation function that immediately resolves with undefined.
+ *
+ * This is useful as a placeholder mutation function in scenarios where a mutation
+ * is required by the type system but no actual operation should be performed.
+ *
+ * @template TResult - The expected result type of the mutation (defaults to unknown)
+ * @template TArgs - The argument types accepted by the mutation function (defaults to unknown[])
+ * @param _args - Arguments that are ignored (prefixed with _ to indicate intentional non-use)
+ * @returns A promise that immediately resolves to undefined cast as TResult
+ */
+export declare function noopMutationFn<TResult = unknown, TArgs extends any[] = unknown[]>(..._args: TArgs): Promise<TResult>;
+export declare namespace noopMutationFn {
+    var key: string;
+}
+/**
+ * Extracts pagination and sort metadata from query parameters.
+ *
+ * Separates the special symbol-keyed fields (pagination and sort) from the rest
+ * of the query parameters, making it easier to work with API requests.
+ *
+ * @param queryParams - The query parameters object containing pagination and sort symbols
+ * @returns An object with three properties: params (remaining parameters), pagination, and sort
+ */
+export declare function extractQueryParams<TParams extends Record<string | symbol, any>>(queryParams: TParams): {
+    params: Omit<TParams, typeof SYMBOL_PAGINATION | typeof SYMBOL_SORT>;
+    pagination: MaybeUndefined<PaginationParams>;
+    sort: MaybeUndefined<OrderSpec[]>;
+};

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

@@ -0,0 +1,28 @@
+import { AnyRouteWithContext } from '@tanstack/react-router';
+import { RouterContext } from '../types';
+import { RouterCore } from '@tanstack/router-core';
+import { RouterHistory } from '@tanstack/history';
+/**
+ * The options for creating a router.
+ */
+export interface RouterOptions {
+    /**
+     * The history mode to use.
+     */
+    history: "hash" | "browser";
+    /**
+     * The route tree to create the router from.
+     */
+    routeTree: AnyRouteWithContext<RouterContext>;
+    /**
+     * The context to use for the router.
+     */
+    context: RouterContext;
+}
+/**
+ * Creates a router.
+ *
+ * @param options The options for creating the router.
+ * @returns The created router.
+ */
+export declare function createRouter({ history, routeTree, context }: RouterOptions): RouterCore<AnyRouteWithContext<RouterContext>, "never", true, RouterHistory, Record<string, any>>;

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

@@ -0,0 +1 @@
+export { useRouteFullPath } from './use-route-full-path';

package/dist/types/hooks/use-route-full-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Get the full path of the current route.
+ *
+ * @returns The full path of the current route.
+ */
+export declare function useRouteFullPath(): string;

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export { createCrudKit, Crud, CrudPage, FlexCard, FormDrawer, FormModal, OperationButtonGroup, Page, ProSearch, ProTable, ProTableSubscriber, useViewportHeight, type CrudActionButtonGroupProps, type CrudBasicFormScene, type CrudBasicSceneFormValues, type CrudFormMutationFns, type CrudFormScene, type CrudOperationButtonGroupProps, type CrudPageProps, type CrudProps, type FlexCardProps, type FormDrawerProps, type FormModalProps, type LoginParams, type LoginResult, type OperationButtonGroupProps, type OperationColumnConfig, type PageProps, type PaginatedQueryParams, type ParamsWithPagination, type ParamsWithSort, type ProSearchProps, type ProTableProps, type ProTableRef, type ProTableState, type ProTableSubscriberProps, type QueryParams, type RowSelectionConfig } from './components';
+export * from './constants';
+export * from './helpers';
+export * from './routes';
+export * from './stores';
+export type * from './types';

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

@@ -0,0 +1 @@
+export type { AuthTokens } from '@vef-framework/core';

package/dist/types/routes/access-denied.d.ts

@@ -0,0 +1,13 @@
+import { AnyRouter, ParsedLocation } from '@tanstack/react-router';
+import { AccessDenied } from '../components';
+/**
+ * Creates the route options for the access denied page.
+ *
+ * @returns The options of the access denied route.
+ */
+export declare function createAccessDeniedRouteOptions(getRouter: () => AnyRouter): {
+    readonly component: typeof AccessDenied;
+    readonly beforeLoad: ({ location }: {
+        location: ParsedLocation;
+    }) => void;
+};

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

@@ -0,0 +1,4 @@
+export { createAccessDeniedRouteOptions } from './access-denied';
+export { createLayoutRouteOptions } from './layout';
+export { createLoginRouteOptions } from './login';
+export { createRootRouteOptions } from './root';

package/dist/types/routes/layout.d.ts

@@ -0,0 +1,25 @@
+import { ParsedLocation } from '@tanstack/react-router';
+import { Awaitable, Except } from '@vef-framework/shared';
+import { LayoutProps, Error, NotFound } from '../components';
+import { UserInfo } from '../types';
+/**
+ * Creates options for a route that renders the `Layout` component.
+ *
+ * @returns The options for the layout route.
+ */
+export declare function createLayoutRouteOptions({ fetchUserInfo, ...layoutProps }: Except<LayoutProps, "children"> & {
+    fetchUserInfo: () => Awaitable<UserInfo>;
+}): {
+    readonly beforeLoad: ({ location }: {
+        location: ParsedLocation;
+    }) => void;
+    readonly loader: ({ location }: {
+        location: ParsedLocation;
+    }) => Promise<void>;
+    readonly pendingComponent: () => import("@emotion/react/jsx-runtime").JSX.Element;
+    readonly errorComponent: typeof Error;
+    readonly notFoundComponent: typeof NotFound;
+    readonly component: () => import("@emotion/react/jsx-runtime").JSX.Element;
+    readonly staleTime: number;
+    readonly shouldReload: false;
+};

package/dist/types/routes/login.d.ts

@@ -0,0 +1,18 @@
+import { LoginProps } from '../components';
+import { z } from '@vef-framework/shared';
+/**
+ * The options for the login route.
+ *
+ * @param props The props for the login component.
+ */
+export declare function createLoginRouteOptions(props: LoginProps): {
+    readonly validateSearch: z.ZodObject<{
+        redirect: z.ZodCatch<z.ZodDefault<z.ZodOptional<z.ZodString>>>;
+    }, z.core.$strip>;
+    readonly beforeLoad: ({ search }: {
+        search: {
+            redirect: string;
+        };
+    }) => void;
+    readonly component: () => import("@emotion/react/jsx-runtime").JSX.Element;
+};

package/dist/types/routes/root.d.ts

@@ -0,0 +1,13 @@
+interface RootProps {
+    appTitle: string;
+}
+/**
+ * Create the root route.
+ *
+ * @returns The root route.
+ */
+export declare function createRootRouteOptions({ appTitle }: RootProps): {
+    readonly component: () => import("@emotion/react/jsx-runtime").JSX.Element;
+    readonly ssr: false;
+};
+export {};

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

@@ -0,0 +1,38 @@
+import { MenuItem } from '@vef-framework/components';
+import { AuthTokens, UseBoundStoreWithPersist } from '@vef-framework/core';
+import { Except } from '@vef-framework/shared';
+import { UserInfo, UserMenu } from '../types';
+/**
+ * The state of the app.
+ */
+export interface AppState {
+    /**
+     * Whether the user is authenticated.
+     */
+    isAuthenticated: boolean;
+    /**
+     * The authenticated tokens of the user.
+     */
+    authTokens?: Readonly<AuthTokens>;
+    /**
+     * The user info of the user.
+     */
+    userInfo?: Readonly<Except<UserInfo, "permTokens">>;
+    /**
+     * The menu mappings of the user.
+     */
+    userMenuMap?: Readonly<Map<string, Readonly<UserMenu>>>;
+    /**
+     * The menu path mappings of the user.
+     */
+    menuPathMap?: Readonly<Map<string, readonly string[]>>;
+    /**
+     * The menu items of the user.
+     */
+    menuItems?: ReadonlyArray<Readonly<MenuItem>>;
+    /**
+     * The permission tokens of the user.
+     */
+    permTokens?: Readonly<Set<string>>;
+}
+export declare const useAppStore: UseBoundStoreWithPersist<AppState>;

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

@@ -0,0 +1,6 @@
+export { useAppStore } from './app';
+export type { AppState } from './app';
+export { useTabStore } from './tab';
+export type { Tab, TabState } from './tab';
+export { useThemeStore } from './theme';
+export type { ColorScheme, ThemeColors, ThemeState } from './theme';

package/dist/types/stores/tab.d.ts

@@ -0,0 +1,73 @@
+import { AnyObject } from '@vef-framework/shared';
+import { UseBoundStoreWithPersist } from '@vef-framework/core';
+/**
+ * The tab item.
+ */
+export interface Tab {
+    /**
+     * The id of the tab.
+     */
+    id: string;
+    /**
+     * The full path of the tab.
+     */
+    fullPath: string;
+    /**
+     * The params of the tab.
+     */
+    params: AnyObject;
+    /**
+     * The search of the tab.
+     */
+    search: AnyObject;
+    /**
+     * The label of the tab.
+     */
+    label: string;
+}
+/**
+ * The state of the tab store.
+ */
+export interface TabState {
+    /**
+     * The currently active tab id.
+     */
+    activeTabId?: string;
+    /**
+     * The list of all tabs.
+     */
+    tabs: Tab[];
+    /**
+     * Set the active tab id.
+     */
+    setActiveTabId: (id: string) => void;
+    /**
+     * Set the list of all tabs.
+     */
+    setTabs: (tabs: Tab[]) => void;
+    /**
+     * Add a new tab to the tab list.
+     */
+    addTab: (tab: Tab) => void;
+    /**
+     * Remove a tab by its id.
+     */
+    removeTab: (id: string, navigate: (tab?: Tab) => void) => void;
+    /**
+     * Remove all tabs from the tab list.
+     */
+    removeAllTabs: (navigate: (tab?: Tab) => void) => void;
+    /**
+     * Remove all tabs except the specified tab.
+     */
+    removeAllTabsExcept: (id: string, navigate: (tab?: Tab) => void) => void;
+    /**
+     * Remove tabs to the left of the specified tab.
+     */
+    removeLeftTabs: (id: string, navigate: (tab?: Tab) => void) => void;
+    /**
+     * Remove tabs to the right of the specified tab.
+     */
+    removeRightTabs: (id: string, navigate: (tab?: Tab) => void) => void;
+}
+export declare const useTabStore: UseBoundStoreWithPersist<TabState>;

package/dist/types/stores/theme.d.ts

@@ -0,0 +1,46 @@
+import { Orientation, SemanticColor } from '@vef-framework/components';
+import { UseBoundStoreWithPersist } from '@vef-framework/core';
+export type ColorScheme = "system" | "light" | "dark";
+export type ThemeColors = Record<SemanticColor, string>;
+/**
+ * The state of the theme.
+ */
+export interface ThemeState {
+    /**
+     * Whether the theme config is open
+     */
+    isThemeConfigVisible: boolean;
+    /**
+     * The current color scheme (system, light, or dark)
+     */
+    colorScheme: ColorScheme;
+    /**
+     * The semantic color mappings for the current theme
+     */
+    colors: ThemeColors;
+    /**
+     * Whether grayscale mode is enabled for accessibility
+     */
+    isGrayscaleMode: boolean;
+    /**
+     * Whether color blind mode is enabled for accessibility
+     */
+    isColorBlindMode: boolean;
+    /**
+     * Whether the menu is displayed in accordion mode
+     */
+    isMenuAccordionMode: boolean;
+    /**
+     * The layout orientation of the menu (horizontal or vertical)
+     */
+    menuLayout: Orientation;
+    /**
+     * The sidebar collapsed state.
+     */
+    isSidebarCollapsed: boolean;
+    /**
+      * The main content maximum state.
+      */
+    isMainContentMaximum: boolean;
+}
+export declare const useThemeStore: UseBoundStoreWithPersist<ThemeState>;

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

@@ -0,0 +1,67 @@
+/**
+ * Base entity interface that all API entities should extend.
+ *
+ * @template TId - The type of the ID fields (id, createdBy, updatedBy). Defaults to string.
+ * @template TDate - The type of the date fields (createdAt, updatedAt). Defaults to string.
+ *
+ * @remarks
+ * This interface provides common audit fields that are automatically
+ * populated by the backend ORM for tracking entity lifecycle.
+ *
+ * @example
+ * Basic usage with default types (string):
+ * ```typescript
+ * interface User extends BaseEntity {
+ *   username: string;
+ *   email: string;
+ * }
+ * ```
+ *
+ * @example
+ * Custom Id type (number):
+ * ```typescript
+ * interface Product extends BaseEntity<number> {
+ *   name: string;
+ *   price: number;
+ * }
+ * ```
+ *
+ * @example
+ * Custom ID and date types:
+ * ```typescript
+ * interface Order extends BaseEntity<number, Date> {
+ *   orderNumber: string;
+ *   total: number;
+ * }
+ * ```
+ */
+export interface BaseEntity<TId = string, TDate = string> {
+    /**
+     * The unique identifier (primary key)
+     */
+    id: TId;
+    /**
+     * The timestamp when this entity was created
+     */
+    createdAt: TDate;
+    /**
+     * The ID of the user who created this entity
+     */
+    createdBy: TId;
+    /**
+     * The name of the user who created this entity
+     */
+    createdByName: string;
+    /**
+     * The timestamp when this entity was last updated
+     */
+    updatedAt: TDate;
+    /**
+     * The ID of the user who last updated this entity
+     */
+    updatedBy: TId;
+    /**
+     * The name of the user who last updated this entity
+     */
+    updatedByName: string;
+}