@vef-framework-react/starter 2.2.2 → 2.4.0

package/dist/es/hooks/use-route-full-path.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import { useMemo as e } from "react";
 import { useLocation as t, useRouter as n } from "@tanstack/react-router";
 //#region src/hooks/use-route-full-path.ts

package/dist/es/index.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import { ACCESS_DENIED_ROUTE_ID as e, ACCESS_DENIED_ROUTE_PATH as t, INDEX_ROUTE_ID as n, INDEX_ROUTE_PATH as r, LOGIN_ROUTE_ID as i, LOGIN_ROUTE_PATH as a } from "./constants/router.js";
 import { useAppStore as o } from "./stores/app.js";
 import { useTabStore as s } from "./stores/tab.js";

package/dist/es/routes/access-denied.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import "../constants/router.js";
 import { AccessDenied as e } from "../components/access-denied/index.js";
 //#region src/routes/access-denied.ts

package/dist/es/routes/index.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import "./access-denied.js";
 import "./layout.js";
 import "./login.js";

package/dist/es/routes/layout.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import { ACCESS_DENIED_ROUTE_PATH as e, LOGIN_ROUTE_PATH as t } from "../constants/router.js";
 import { useAppStore as n } from "../stores/app.js";
 import { Error as r } from "../components/error/index.js";
@@ -37,38 +37,40 @@ function p(e) {
 function m(e) {
 	return e.filter((e) => e.type !== "view").map((e) => Object.freeze(p(e)));
 }
-function h({ fetchUserInfo: o, ...p }) {
-	function h() {
+function h({ fetchUserInfo: o, beforeLoad: p, loader: h, ...g }) {
+	function _() {
 		return /* @__PURE__ */ c(i, {
-			...p,
+			...g,
 			children: /* @__PURE__ */ c(l, {})
 		});
 	}
 	return {
-		beforeLoad: ({ location: r }) => {
-			let { isAuthenticated: i, userMenuMap: a } = n.getState();
-			if (!i) throw u({
+		beforeLoad: async (r) => {
+			let { location: i } = r, { isAuthenticated: a, userMenuMap: o } = n.getState();
+			if (!a) throw u({
 				to: t,
-				search: { redirect: r.href }
+				search: { redirect: i.href }
 			});
-			if (a && !a.has(r.pathname)) throw u({
+			if (o && !o.has(i.pathname)) throw u({
 				to: e,
 				replace: !0
 			});
+			return await p?.(r) ?? {};
 		},
-		loader: async ({ location: t }) => {
-			let { permTokens: r, ...i } = await o(), { menus: a } = i, s = Object.freeze(d(a)), c = Object.freeze(f(a)), l = Object.freeze(m(a));
+		loader: async (t) => {
+			let { location: r } = t, { permissionTokens: i, ...a } = await o(), { menus: s } = a, c = Object.freeze(d(s)), l = Object.freeze(f(s)), p = Object.freeze(m(s));
 			if (n.setState({
 				...n.getState(),
-				userInfo: Object.freeze(i),
-				userMenuMap: s,
-				menuPathMap: c,
-				menuItems: l,
-				permTokens: Object.freeze(new Set(r))
-			}), !s.has(t.pathname)) throw u({
+				userInfo: Object.freeze(a),
+				userMenuMap: c,
+				menuPathMap: l,
+				menuItems: p,
+				permissionTokens: Object.freeze(new Set(i))
+			}), !c.has(r.pathname)) throw u({
 				to: e,
 				replace: !0
 			});
+			if (h) return await h(t);
 		},
 		pendingComponent: () => /* @__PURE__ */ c(s, {
 			description: "页面玩命加载中, 请稍后...",
@@ -77,7 +79,7 @@ function h({ fetchUserInfo: o, ...p }) {
 		}),
 		errorComponent: r,
 		notFoundComponent: a,
-		component: h,
+		component: _,
 		staleTime: Infinity,
 		shouldReload: !1
 	};

package/dist/es/routes/login.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import "../constants/router.js";
 import { useAppStore as e } from "../stores/app.js";
 import { Login as t } from "../components/login/index.js";

package/dist/es/routes/root.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import { useAppStore as e } from "../stores/app.js";
 import { jsx as t } from "@emotion/react/jsx-runtime";
 import { Outlet as n, useLocation as r, useRouteContext as i } from "@tanstack/react-router";

package/dist/es/stores/app.js

@@ -1,12 +1,16 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import { createPersistedStore as e } from "@vef-framework-react/core";
 //#region src/stores/app.ts
-var t = e(() => ({ isAuthenticated: !1 }), {
+var t = e(() => ({
+	isAuthenticated: !1,
+	custom: {}
+}), {
 	name: "app",
 	storage: "local",
-	selector: ({ isAuthenticated: e, authTokens: t }) => ({
+	selector: ({ isAuthenticated: e, custom: t, authTokens: n }) => ({
 		isAuthenticated: e,
-		authTokens: t
+		custom: t,
+		authTokens: n
 	})
 });
 //#endregion

package/dist/es/stores/index.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import "./app.js";
 import "./tab.js";
 import "./theme.js";

package/dist/es/stores/tab.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import "../constants/router.js";
 import { createPersistedStore as e, originalState as t } from "@vef-framework-react/core";
 //#region src/stores/tab.ts

package/dist/es/stores/theme.js

@@ -1,4 +1,4 @@
-/*! @vef-framework-react/starter v2.2.2 made by Venus | 2026-05-18T12:44:01.943Z */
+/*! @vef-framework-react/starter v2.4.0 made by Venus | 2026-06-15T15:10:34.000Z */
 import { createPersistedStore as e } from "@vef-framework-react/core";
 import { omit as t } from "@vef-framework-react/shared";
 //#region src/stores/theme.ts
@@ -15,6 +15,8 @@ var n = {
 	isColorBlindMode: !1,
 	isMenuAccordionMode: !0,
 	menuLayout: "vertical",
+	isTabsVisible: !0,
+	isDarkSidebar: !0,
 	isSidebarCollapsed: !1,
 	isMainContentMaximum: !1
 }, r = e(() => ({

package/dist/types/{components → src/components}/base-layout/props.d.ts

@@ -63,6 +63,12 @@ export interface BaseLayoutProps extends PropsWithChildren {
      * The class of the sidebar.
      */
     sidebarClassName?: string;
+    /**
+     * Whether the sidebar sits below the header (mixed layout) instead of
+     * spanning the full height. When enabled, the header stays full-width and the
+     * sidebar starts at the header's bottom edge.
+     */
+    isSidebarBelowHeader?: boolean;
     /**
      * The main content maximum state.
      */

package/dist/types/{components → src/components}/base-layout/styles.d.ts

@@ -3,6 +3,7 @@ export declare const layout: SerializedStyles;
 export declare const header: SerializedStyles;
 export declare const tabs: SerializedStyles;
 export declare const sidebar: SerializedStyles;
+export declare const sidebarBelowHeader: SerializedStyles;
 export declare const sidebarGap: SerializedStyles;
 export declare const main: SerializedStyles;
 export declare const footer: SerializedStyles;

package/dist/types/{components → src/components}/index.d.ts

@@ -2,7 +2,7 @@ export { AccessDenied } from './access-denied';
 export { App, type AppProps } from './app';
 export { BaseLayout, type BaseLayoutProps } from './base-layout';
 export { Error } from './error';
-export { Layout, type LayoutProps } from './layout';
+export { Layout, type AppItem, type LayoutProps, type UserMenuItem } from './layout';
 export { Login, type LoginChallenge, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginParams, type LoginProps, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams } from './login';
 export { NProgress, nProgressEventEmitter } from './n-progress';
 export { NotFound } from './not-found';

package/dist/types/src/components/layout/components/contour-pattern.d.ts

@@ -0,0 +1,5 @@
+interface ContourPatternProps {
+    isSidebarCollapsed?: boolean;
+}
+export declare function ContourPattern({ isSidebarCollapsed }: ContourPatternProps): React.JSX.Element;
+export {};

package/dist/types/src/components/layout/components/header/app-switcher.d.ts

@@ -0,0 +1,10 @@
+import { Awaitable } from '@vef-framework-react/shared';
+import { AppItem } from '../../props';
+interface AppSwitcherProps {
+    apps: AppItem[];
+    currentAppId?: string;
+    onAppChange?: (appId: string) => Awaitable<void>;
+    className?: string;
+}
+export declare function AppSwitcher({ apps, currentAppId, onAppChange, className }: AppSwitcherProps): React.JSX.Element;
+export {};

package/dist/types/src/components/layout/components/header/header-pattern.d.ts

@@ -0,0 +1 @@
+export declare function HeaderPattern(): React.JSX.Element;

package/dist/types/src/components/layout/components/header/index.d.ts

@@ -0,0 +1,10 @@
+import { LayoutProps } from '../../props';
+interface HeaderProps extends Pick<LayoutProps, "title" | "logo" | "headerActions" | "userMenuItems" | "onUserMenuClick" | "onLogout" | "apps" | "currentAppId" | "onAppChange"> {
+    /**
+     * Whether to show the sidebar collapse toggle. True when a collapsible sidebar exists
+     * (vertical always; mixed only when the active section has a submenu).
+     */
+    showMenuBurger: boolean;
+}
+export declare function Header({ title, logo, headerActions, userMenuItems, onUserMenuClick, onLogout, apps, currentAppId, onAppChange, showMenuBurger }: HeaderProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/src/components/layout/components/header/mixed-menu.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Top header menu for the mixed layout: renders only the first-level entries
+ * and switches the active section (and thus the sidebar) on select.
+ */
+export declare function MixedMenu(): React.JSX.Element;

package/dist/types/{components → src/components}/layout/components/logo.d.ts

@@ -3,6 +3,10 @@ import { Except } from '@vef-framework-react/shared';
 import { LayoutProps } from '../props';
 interface LogoProps extends Except<LinkComponentProps, "to" | "title">, Pick<LayoutProps, "title" | "logo"> {
     isTitleVisible?: boolean;
+    /**
+     * Render the logo in white, for placement on a colored (primary) surface.
+     */
+    inverted?: boolean;
 }
-export declare function Logo({ isTitleVisible, title, logo, ...props }: LogoProps): React.JSX.Element;
+export declare function Logo({ isTitleVisible, inverted, title, logo, ...props }: LogoProps): React.JSX.Element;
 export {};

package/dist/types/src/components/layout/components/menu.d.ts

@@ -0,0 +1,19 @@
+import { MenuItem, Orientation } from '@vef-framework-react/components';
+interface MenuProps {
+    layout: Orientation;
+    isSidebarCollapsed?: boolean;
+    /**
+     * Menu items to render. Defaults to the full tree from the app store.
+     */
+    items?: readonly MenuItem[];
+    /**
+     * Selected keys override. Defaults to the current route's full path.
+     */
+    selectedKeys?: string[];
+    /**
+     * Select handler override. Defaults to navigating to the picked menu.
+     */
+    onSelectMenu?: (key: string) => void;
+}
+export declare function Menu({ layout, isSidebarCollapsed, items, selectedKeys, onSelectMenu }: MenuProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/{components → src/components}/layout/components/search/keyboard.d.ts

@@ -1,4 +1,4 @@
-import { PropsWithChildren, ReactNode, default as React } from 'react';
+import { PropsWithChildren, ReactNode } from 'react';
 interface KeyboardProps extends PropsWithChildren {
     icon: ReactNode;
 }

package/dist/types/src/components/layout/components/sidebar.d.ts

@@ -0,0 +1,21 @@
+import { MenuItem } from '@vef-framework-react/components';
+import { LayoutProps } from '../props';
+interface SidebarProps extends Pick<LayoutProps, "logo" | "title"> {
+    /**
+     * Whether the sidebar renders on the dark brand surface (vertical layout
+     * only). Adds the contour artwork at the bottom; the surface itself is
+     * styled by the layout's `sidebarDark` class.
+     */
+    isDark?: boolean;
+    isSidebarCollapsed?: boolean;
+    /**
+     * Menu items to render. Defaults to the full tree from the app store.
+     */
+    items?: readonly MenuItem[];
+    /**
+     * Whether to render the logo. Disabled in mixed layout (logo is in the header).
+     */
+    showLogo?: boolean;
+}
+export declare function Sidebar({ isDark, isSidebarCollapsed, logo, title, items, showLogo }: SidebarProps): React.JSX.Element;
+export {};

package/dist/types/{components → src/components}/layout/components/theme-config/menu-layout-card.d.ts

@@ -1,7 +1,7 @@
-import { Orientation } from '@vef-framework-react/components';
 import { ComponentProps } from 'react';
+import { MenuLayoutMode } from '../../../../stores';
 interface MenuLayoutCardProps extends ComponentProps<"div"> {
-    mode: Orientation;
+    mode: MenuLayoutMode;
 }
 export declare function MenuLayoutCard({ mode, ...props }: MenuLayoutCardProps): React.JSX.Element;
 export {};

package/dist/types/{components → src/components}/layout/hooks/index.d.ts

@@ -1,3 +1,4 @@
 export { useColorSchemeUpdater } from './use-color-scheme-updater';
 export { useMenuNavigate } from './use-menu-navigate';
+export { useMixedMenu, type UseMixedMenuResult } from './use-mixed-menu';
 export { useTabNavigate } from './use-tab-navigate';

package/dist/types/src/components/layout/hooks/use-mixed-menu.d.ts

@@ -0,0 +1,31 @@
+import { MenuItem } from '@vef-framework-react/components';
+export interface UseMixedMenuResult {
+    /**
+     * First-level menu entries, flattened for the top header.
+     */
+    topLevelItems: MenuItem[];
+    /**
+     * Path of the first-level section the current route belongs to.
+     */
+    activeSectionKey?: string;
+    /**
+     * Children of the active section, rendered in the sidebar.
+     */
+    sectionItems?: MenuItem[];
+    /**
+     * Whether the active section has a sidebar to show.
+     */
+    hasSectionMenu: boolean;
+    /**
+     * Navigate into a top-level section's first reachable leaf.
+     */
+    selectTopSection: (key: string) => void;
+}
+/**
+ * Derive the data the mixed menu layout needs from the current route: the
+ * flattened first-level items for the header, the active first-level section,
+ * and that section's children for the sidebar.
+ *
+ * @returns The derived mixed-menu data
+ */
+export declare function useMixedMenu(): UseMixedMenuResult;

package/dist/types/src/components/layout/index.d.ts

@@ -0,0 +1,3 @@
+import { LayoutProps } from './props';
+export declare function Layout({ title, logo, headerActions, userMenuItems, onUserMenuClick, onLogout, apps, currentAppId, onAppChange, children }: LayoutProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export { type AppItem, type LayoutProps, type UserMenuItem } from './props';

package/dist/types/src/components/layout/props.d.ts

@@ -0,0 +1,79 @@
+import { DropdownMenuItem } from '@vef-framework-react/components';
+import { Awaitable, DistributedOmit } from '@vef-framework-react/shared';
+import { PropsWithChildren, ReactNode } from 'react';
+/**
+ * A {@link DropdownMenuItem} with `onClick` / `onTitleClick` stripped — clicks
+ * on user menu items are always routed through `LayoutProps.onUserMenuClick`
+ * by item key, so per-item handlers would be silently ignored.
+ */
+export type UserMenuItem = DistributedOmit<DropdownMenuItem, "onClick" | "onTitleClick">;
+/**
+ * A selectable sub-application shown in the Layout's app switcher. Shaped as a
+ * plain record so it can be hydrated straight from an API response (no JSX).
+ */
+export interface AppItem {
+    /**
+     * Stable identifier, handed back to {@link LayoutProps.onAppChange}.
+     */
+    id: string;
+    /**
+     * Display name.
+     */
+    name: string;
+    /**
+     * Optional one-line description (e.g. shown as a tooltip).
+     */
+    description?: string;
+    /**
+     * Optional icon name, resolved through `DynamicIcon` (a kebab-case lucide
+     * name such as `"layout-dashboard"`). A string, not a node, so it survives a
+     * JSON round-trip from the backend.
+     */
+    icon?: string;
+}
+/**
+ * The props for the Layout component.
+ */
+export interface LayoutProps extends PropsWithChildren {
+    /**
+     * The title of the layout.
+     */
+    title?: ReactNode;
+    /**
+     * The logo of the layout.
+     */
+    logo?: ReactNode;
+    /**
+     * The actions of the header.
+     */
+    headerActions?: ReactNode;
+    /**
+     * Extra items appended to the user dropdown menu. They render before the
+     * built-in items (e.g. logout), with an automatic divider in between.
+     */
+    userMenuItems?: UserMenuItem[];
+    /**
+     * Handles clicks on user menu items. The built-in `logout` key is owned by
+     * the framework and never forwarded; all other keys are delivered here.
+     */
+    onUserMenuClick?: (key: string) => void;
+    /**
+     * The logout api function.
+     */
+    onLogout?: () => Awaitable<void>;
+    /**
+     * Sub-applications the user can switch between. When non-empty, an app
+     * switcher appears next to the logo. Each system supplies its own apps —
+     * the framework only renders the control and reports the selection.
+     */
+    apps?: AppItem[];
+    /**
+     * The id of the currently active app, highlighted in the switcher.
+     */
+    currentAppId?: string;
+    /**
+     * Called when the user picks a different app. The project performs the
+     * actual switch (e.g. persist the choice, then reload or re-route the shell).
+     */
+    onAppChange?: (appId: string) => Awaitable<void>;
+}

package/dist/types/{components → src/components}/layout/styles.d.ts

@@ -1,2 +1,3 @@
 import { SerializedStyles } from '@emotion/serialize';
 export declare const sidebar: SerializedStyles;
+export declare const sidebarDark: SerializedStyles;

package/dist/types/{index.d.ts → src/index.d.ts}

@@ -1,6 +1,6 @@
-export { type LoginChallenge, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginParams, type LoginProps, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams } from './components';
+export { type AppItem, type LoginChallenge, type LoginChallengeRenderer, type LoginChallengeRendererProps, type LoginChallengeRenderers, type LoginParams, type LoginProps, type LoginResult, type PasswordLoginParams, type ResolveChallengeParams, type UserMenuItem } from './components';
 export { ACCESS_DENIED_ROUTE_ID, ACCESS_DENIED_ROUTE_PATH, INDEX_ROUTE_ID, INDEX_ROUTE_PATH, LOGIN_ROUTE_ID, LOGIN_ROUTE_PATH } from './constants';
 export { createApiClient, createApp, createRouter, dispatchCustomEvent, emitAccessDenied, emitUnauthenticated, extractQueryParams, handleClientLogout, noopMutationFn, setupAppVersionNotification, type ApiClientOptions, type AppChangelog, type AppVersionNotificationOptions, type RouterOptions } from './helpers';
-export { createAccessDeniedRouteOptions, createLayoutRouteOptions, createLoginRouteOptions, createRootRouteOptions } from './routes';
-export { useAppStore, useTabStore, useThemeStore, type AppState, type ColorScheme, type Tab, type TabState, type ThemeColors, type ThemeState } from './stores';
+export { createAccessDeniedRouteOptions, createLayoutRouteOptions, createLoginRouteOptions, createRootRouteOptions, type LayoutBeforeLoadArgs, type LayoutLoaderArgs } from './routes';
+export { useAppStore, useTabStore, useThemeStore, type AppState, type ColorScheme, type MenuLayoutMode, type Tab, type TabState, type ThemeColors, type ThemeState } from './stores';
 export type * from './types';

package/dist/types/{routes → src/routes}/index.d.ts

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

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

@@ -0,0 +1,25 @@
+import { RouteLoaderFn, RouteOptions } from '@tanstack/react-router';
+import { AnyObject, Awaitable, EmptyObject, Except } from '@vef-framework-react/shared';
+import { LayoutProps, Error, NotFound } from '../components';
+import { UserInfo } from '../types';
+export type LayoutBeforeLoadArgs = Parameters<NonNullable<RouteOptions<unknown, any, any>["beforeLoad"]>>[0];
+type BaseLayoutLoaderArgs = Parameters<RouteLoaderFn<unknown, any, any>>[0];
+export type LayoutLoaderArgs<TBeforeLoadContext extends AnyObject = EmptyObject> = Except<BaseLayoutLoaderArgs, "context"> & {
+    context: BaseLayoutLoaderArgs["context"] & TBeforeLoadContext;
+};
+interface LayoutRouteOptions<TBeforeLoadContext extends AnyObject = EmptyObject, TLoaderData = void> extends Except<LayoutProps, "children"> {
+    fetchUserInfo: () => Awaitable<UserInfo>;
+    beforeLoad?: (args: LayoutBeforeLoadArgs) => Awaitable<TBeforeLoadContext | void>;
+    loader?: (args: LayoutLoaderArgs<TBeforeLoadContext>) => Awaitable<TLoaderData>;
+}
+export declare function createLayoutRouteOptions<TBeforeLoadContext extends AnyObject = EmptyObject, TLoaderData = void>({ fetchUserInfo, beforeLoad, loader, ...layoutProps }: LayoutRouteOptions<TBeforeLoadContext, TLoaderData>): {
+    beforeLoad: (args: LayoutBeforeLoadArgs) => Promise<TBeforeLoadContext>;
+    loader: (args: LayoutLoaderArgs<TBeforeLoadContext>) => Promise<TLoaderData | undefined>;
+    pendingComponent: () => import("@emotion/react/jsx-runtime").JSX.Element;
+    errorComponent: typeof Error;
+    notFoundComponent: typeof NotFound;
+    component: () => import("@emotion/react/jsx-runtime").JSX.Element;
+    staleTime: number;
+    shouldReload: boolean;
+};
+export {};

package/dist/types/{stores → src/stores}/app.d.ts

@@ -1,14 +1,15 @@
 import { MenuItem } from '@vef-framework-react/components';
 import { AuthTokens, UseBoundStoreWithPersist } from '@vef-framework-react/core';
 import { Except } from '@vef-framework-react/shared';
-import { UserInfo, UserMenu } from '../types';
+import { AppCustomState, UserInfo, UserMenu } from '../types';
 export interface AppState {
     isAuthenticated: boolean;
     authTokens?: Readonly<AuthTokens>;
-    userInfo?: Readonly<Except<UserInfo, "permTokens">>;
+    userInfo?: Readonly<Except<UserInfo, "permissionTokens">>;
     userMenuMap?: Readonly<Map<string, Readonly<UserMenu>>>;
     menuPathMap?: Readonly<Map<string, readonly string[]>>;
     menuItems?: ReadonlyArray<Readonly<MenuItem>>;
-    permTokens?: Readonly<Set<string>>;
+    permissionTokens?: Readonly<Set<string>>;
+    custom: AppCustomState;
 }
 export declare const useAppStore: UseBoundStoreWithPersist<AppState>;

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

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

package/dist/types/{stores → src/stores}/theme.d.ts

@@ -2,6 +2,14 @@ import { Orientation, SemanticColor } from '@vef-framework-react/components';
 import { UseBoundStoreWithPersist } from '@vef-framework-react/core';
 export type ColorScheme = "system" | "light" | "dark";
 export type ThemeColors = Record<SemanticColor, string>;
+/**
+ * The menu layout mode.
+ *
+ * - `vertical`: menu lives in the left sidebar.
+ * - `horizontal`: menu lives in the top header.
+ * - `mixed`: first-level menu in the top header, its children in the left sidebar.
+ */
+export type MenuLayoutMode = Orientation | "mixed";
 export interface ThemeState {
     isThemeConfigVisible: boolean;
     colorScheme: ColorScheme;
@@ -9,7 +17,13 @@ export interface ThemeState {
     isGrayscaleMode: boolean;
     isColorBlindMode: boolean;
     isMenuAccordionMode: boolean;
-    menuLayout: Orientation;
+    menuLayout: MenuLayoutMode;
+    isTabsVisible: boolean;
+    /**
+     * Render the sidebar as a dark brand surface. Only takes effect in the
+     * `vertical` menu layout; other layouts keep the light sidebar.
+     */
+    isDarkSidebar: boolean;
     isSidebarCollapsed: boolean;
     isMainContentMaximum: boolean;
 }

package/dist/types/{types → src/types}/common.d.ts

@@ -1,4 +1,4 @@
-import { LiteralUnion, MaybeNull } from '@vef-framework-react/shared';
+import { AnyObject, LiteralUnion, MaybeNull } from '@vef-framework-react/shared';
 export type Gender = "male" | "female" | "unknown";
 export type UserMenuType = LiteralUnion<"directory" | "menu" | "view" | "report", string>;
 export interface UserMenu {
@@ -19,6 +19,9 @@ export interface UserMenu {
  * @example
  * declare module "@vef-framework-react/starter" {
  *   interface Register {
+ *     appCustomState: {
+ *       appId?: string;
+ *     };
  *     userDetails: {
  *       department: string;
  *       organization: string;
@@ -35,6 +38,9 @@ export interface UserMenu {
  */
 export interface Register {
 }
+export type AppCustomState = Register extends {
+    appCustomState: infer T extends AnyObject;
+} ? T : AnyObject;
 /**
  * Default shape of `UserInfo['details']` before projects augment `Register`.
  */
@@ -63,7 +69,7 @@ export interface UserInfo {
     name: string;
     gender: Gender;
     avatar?: MaybeNull<string>;
-    permTokens: string[];
+    permissionTokens: string[];
     menus: UserMenu[];
     details: ResolvedUserDetails;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vef-framework-react/starter",
   "type": "module",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "private": false,
   "description": "Starter for VEF framework",
   "author": {
@@ -54,20 +54,20 @@
     "react-dom": ">=19"
   },
   "dependencies": {
-    "@ant-design/icons": "^6.2.2",
+    "@ant-design/icons": "^6.2.5",
     "@emotion/react": "^11.14.0",
     "@tanem/react-nprogress": "^6.0.3",
     "compare-versions": "^6.1.1",
-    "lucide-react": "^1.16.0"
+    "lucide-react": "^1.17.0"
   },
   "devDependencies": {
-    "@tanstack/react-router": "^1.170.1",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "@vef-framework-react/components": "2.2.2",
-    "@vef-framework-react/core": "2.2.2",
-    "@vef-framework-react/shared": "2.2.2",
-    "@vef-framework-react/hooks": "2.2.2"
+    "@tanstack/react-router": "^1.170.15",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "@vef-framework-react/core": "2.4.0",
+    "@vef-framework-react/hooks": "2.4.0",
+    "@vef-framework-react/shared": "2.4.0",
+    "@vef-framework-react/components": "2.4.0"
   },
   "scripts": {
     "clean": "rimraf dist",

package/dist/cjs/_internal/_rolldown/runtime.cjs

@@ -1 +0,0 @@
-var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));exports.__toESM=s;