@robot-admin/layout 3.1.0 → 3.2.0

package/dist/vue/index.d.cts

@@ -0,0 +1,1181 @@
+import * as pinia from 'pinia';
+import * as vue from 'vue';
+import { VNode, App, InjectionKey, ComputedRef, WritableComputedRef, Component, MaybeRefOrGetter, Ref } from 'vue';
+import { RouteLocationNormalizedLoaded } from 'vue-router';
+
+/** 与具体主题实现无关的标准主题模式。 */
+type ThemeMode = "light" | "dark" | "system";
+/** 内置布局模式。 */
+type LayoutMode = "side" | "top" | "mix" | "mix-top" | "reverse-horizontal-mix" | "card-layout";
+/** 菜单展开方式。 */
+type MenuExpandMode = "inline" | "panel";
+/** 页面动画类型。 */
+type TransitionType = "fade" | "slide" | "zoom" | "none";
+/** 圆角大小。 */
+type BorderRadiusSize = "small" | "medium" | "large";
+/** 标签页风格。 */
+type TagsViewStyle = "default" | "card" | "smart";
+/** UI 无关的布局设置协议。 */
+interface SettingsState {
+    themeMode: ThemeMode;
+    primaryColor: string;
+    borderRadius: BorderRadiusSize;
+    transitionType: TransitionType;
+    enableTransition: boolean;
+    layoutMode: LayoutMode;
+    menuExpandMode: MenuExpandMode;
+    collapsed: boolean;
+    fixedHeader: boolean;
+    showBreadcrumb: boolean;
+    showBreadcrumbIcon: boolean;
+    showTagsView: boolean;
+    tagsViewHeight: number;
+    tagsViewStyle: TagsViewStyle;
+    showFooter: boolean;
+    sidebarWidth: number;
+    sidebarCollapsedWidth: number;
+    headerHeight: number;
+    enableHotkeys: boolean;
+    /** @deprecated 包版本不应参与配置迁移，请使用 SETTINGS_CONFIG_SCHEMA_VERSION。 */
+    version: string;
+}
+/** 主题预设方案。 */
+interface ThemePreset {
+    name: string;
+    description?: string;
+    icon: string;
+    primaryColor: string;
+    settings?: Partial<Omit<SettingsState, "themeMode" | "layoutMode" | "primaryColor">>;
+}
+/** Settings Store 初始化选项。 */
+interface SettingsStoreOptions {
+    id?: string;
+    defaults?: Partial<SettingsState>;
+    onThemeModeChange?: (mode: ThemeMode) => void | Promise<void>;
+    /** 是否自动同步 CSS 变量；默认 true，微前端可关闭后自行绑定作用域。 */
+    syncCssVariables?: boolean;
+}
+/** 由宿主应用实现的高副作用操作。 */
+interface SettingsDrawerActions {
+    clearCache?: () => void | Promise<void>;
+    reloadPage?: () => void;
+}
+/** 布局模式展示信息。 */
+interface LayoutInfo {
+    mode: LayoutMode;
+    label: string;
+    description: string;
+    icon: string;
+}
+/** 预设颜色。 */
+interface PresetColor {
+    name: string;
+    value: string;
+}
+
+/** 当前导入导出配置格式版本。 */
+declare const SETTINGS_CONFIG_SCHEMA_VERSION: 1;
+interface LayoutVisualEffects {
+    gray?: boolean;
+    colorWeak?: boolean;
+    watermark?: {
+        enabled: boolean;
+        text: string;
+    };
+}
+/** 经校验后可原子应用的布局配置。 */
+interface LayoutSettingsConfig extends LayoutVisualEffects {
+    schemaVersion?: number;
+    settings?: Partial<SettingsState>;
+}
+/** 校验需要跨字段判断的布局尺寸约束。 */
+declare function assertLayoutSettingsRelationships(settings: Pick<SettingsState, "sidebarCollapsedWidth" | "sidebarWidth">): void;
+/**
+ * 校验来自配置文件等不可信来源的设置。
+ * 未知键为向前兼容而忽略；已知键的非法值会让整次导入失败。
+ */
+declare function sanitizeSettingsPatch(input: unknown): Partial<SettingsState>;
+/**
+ * 一次性校验完整导入文件。此函数不修改任何响应式状态或浏览器 API，
+ * 消费方可以在成功返回后再原子应用结果。
+ */
+declare function sanitizeLayoutSettingsConfig(input: unknown): LayoutSettingsConfig;
+/**
+ * 调整颜色亮度。
+ * @returns 调整后的 #rrggbb；输入非法时原样返回。
+ */
+declare function adjustColor(color: string, amount: number): string;
+
+/**
+ * 布局和设置系统 - 常量定义
+ */
+
+declare const PRESET_COLORS: PresetColor[];
+declare const THEME_PRESETS: ThemePreset[];
+declare const LAYOUT_MODES: LayoutInfo[];
+declare const BORDER_RADIUS_MAP: {
+    readonly small: "4px";
+    readonly medium: "6px";
+    readonly large: "8px";
+};
+declare const TRANSITION_MAP: {
+    readonly fade: "fade-transform";
+    readonly slide: "fade-slide";
+    readonly zoom: "fade-zoom";
+    readonly none: "";
+};
+declare const DEFAULT_SETTINGS: SettingsState;
+/** Color swatches for color picker */
+declare const COLOR_SWATCHES: string[];
+
+/**
+ * @robot-admin/layout
+ *
+ * 菜单路由相关类型定义
+ * 从主项目提取的通用菜单类型，供布局骨架和消费方共用
+ */
+
+/**
+ * 菜单项类型
+ * - `group` 分组
+ * - `divider` 分割线
+ * - `item` 普通菜单项
+ */
+type MenuItemType = "group" | "divider" | "item";
+/** 可由宿主通过交叉类型安全扩展的菜单元数据。 */
+interface MenuMeta extends Record<string, unknown> {
+    /** 页面标题 */
+    title?: string;
+    /** 菜单项的图标 */
+    icon?: string;
+    /** 是否在菜单中隐藏 */
+    hidden?: boolean;
+    /** 是否固定在标签栏 */
+    affix?: boolean;
+    /** 是否缓存该页面 */
+    keepAlive?: boolean;
+    /** 是否全屏显示 */
+    full?: boolean;
+    /** 外部链接 URL */
+    link?: string;
+}
+/**
+ * 菜单选项的详细类型定义
+ */
+interface MenuOptions<TMeta extends MenuMeta = MenuMeta> {
+    /** 菜单项类型（分组/分割线） */
+    type?: MenuItemType;
+    /** 唯一标识 */
+    key?: string;
+    /** 菜单跳转路径 */
+    path?: string;
+    /** 菜单名称（可对应路由名） */
+    name?: string;
+    /** 菜单项对应的组件名称 */
+    component?: string;
+    /** 重定向路径 */
+    redirect?: string;
+    /** 菜单显示的文本 */
+    label?: string;
+    /** 图标 */
+    icon?: string | (() => VNode) | VNode;
+    /** 是否禁用此菜单项 */
+    disabled?: boolean;
+    /** 元数据 */
+    meta?: TMeta;
+    /** 子菜单 */
+    children?: MenuOptions<TMeta>[];
+}
+/**
+ * 标签栏项类型定义
+ */
+interface MenuTag {
+    /** 标签项对应的路由路径 */
+    path: string;
+    /** 标签显示的标题（已翻译） */
+    title: string;
+    /** 原始标题（中文，用于重新翻译） */
+    originalTitle?: string;
+    /** 显示的图标 */
+    icon?: string;
+    /** 标签相关元数据 */
+    meta?: {
+        /** 是否固定在标签栏 */
+        affix?: boolean;
+    };
+}
+
+/**
+ * 初始化布局系统
+ *
+ * @example
+ * ```ts
+ * import { setupLayout } from '@robot-admin/layout/vue'
+ * setupLayout(app, {
+ *   onThemeModeChange: async (mode) => {
+ *     const themeStore = useThemeStore()
+ *     await themeStore.setMode(mode)
+ *   }
+ * })
+ * ```
+ */
+declare function setupLayout(app: App, options?: SettingsStoreOptions): pinia.StoreDefinition<string, Pick<{
+    defaults: Readonly<{
+        themeMode: ThemeMode;
+        primaryColor: string;
+        borderRadius: BorderRadiusSize;
+        transitionType: TransitionType;
+        enableTransition: boolean;
+        layoutMode: LayoutMode;
+        menuExpandMode: MenuExpandMode;
+        collapsed: boolean;
+        fixedHeader: boolean;
+        showBreadcrumb: boolean;
+        showBreadcrumbIcon: boolean;
+        showTagsView: boolean;
+        tagsViewHeight: number;
+        tagsViewStyle: TagsViewStyle;
+        showFooter: boolean;
+        sidebarWidth: number;
+        sidebarCollapsedWidth: number;
+        headerHeight: number;
+        enableHotkeys: boolean;
+        version: string;
+    }>;
+    themeMode: vue.Ref<ThemeMode, ThemeMode>;
+    primaryColor: vue.Ref<string, string>;
+    borderRadius: vue.Ref<BorderRadiusSize, BorderRadiusSize>;
+    transitionType: vue.Ref<TransitionType, TransitionType>;
+    enableTransition: vue.Ref<boolean, boolean>;
+    layoutMode: vue.Ref<LayoutMode, LayoutMode>;
+    menuExpandMode: vue.Ref<MenuExpandMode, MenuExpandMode>;
+    collapsed: vue.Ref<boolean, boolean>;
+    fixedHeader: vue.Ref<boolean, boolean>;
+    showBreadcrumb: vue.Ref<boolean, boolean>;
+    showBreadcrumbIcon: vue.Ref<boolean, boolean>;
+    showTagsView: vue.Ref<boolean, boolean>;
+    tagsViewHeight: vue.Ref<number, number>;
+    tagsViewStyle: vue.Ref<TagsViewStyle, TagsViewStyle>;
+    showFooter: vue.Ref<boolean, boolean>;
+    sidebarWidth: vue.Ref<number, number>;
+    sidebarCollapsedWidth: vue.Ref<number, number>;
+    headerHeight: vue.Ref<number, number>;
+    enableHotkeys: vue.Ref<boolean, boolean>;
+    version: vue.Ref<string, string>;
+    borderRadiusValue: vue.ComputedRef<"4px" | "6px" | "8px">;
+    transitionName: vue.ComputedRef<"" | "fade-transform" | "fade-slide" | "fade-zoom">;
+    shouldEnableTransition: vue.ComputedRef<boolean>;
+    settingsState: vue.ComputedRef<SettingsState>;
+    syncCSSVariables: () => void | undefined;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    resetSettings: () => void;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    toggleCollapse: () => void;
+}, "themeMode" | "layoutMode" | "primaryColor" | "borderRadius" | "transitionType" | "enableTransition" | "menuExpandMode" | "collapsed" | "fixedHeader" | "showBreadcrumb" | "showBreadcrumbIcon" | "showTagsView" | "tagsViewHeight" | "tagsViewStyle" | "showFooter" | "sidebarWidth" | "sidebarCollapsedWidth" | "headerHeight" | "enableHotkeys" | "version" | "defaults">, Pick<{
+    defaults: Readonly<{
+        themeMode: ThemeMode;
+        primaryColor: string;
+        borderRadius: BorderRadiusSize;
+        transitionType: TransitionType;
+        enableTransition: boolean;
+        layoutMode: LayoutMode;
+        menuExpandMode: MenuExpandMode;
+        collapsed: boolean;
+        fixedHeader: boolean;
+        showBreadcrumb: boolean;
+        showBreadcrumbIcon: boolean;
+        showTagsView: boolean;
+        tagsViewHeight: number;
+        tagsViewStyle: TagsViewStyle;
+        showFooter: boolean;
+        sidebarWidth: number;
+        sidebarCollapsedWidth: number;
+        headerHeight: number;
+        enableHotkeys: boolean;
+        version: string;
+    }>;
+    themeMode: vue.Ref<ThemeMode, ThemeMode>;
+    primaryColor: vue.Ref<string, string>;
+    borderRadius: vue.Ref<BorderRadiusSize, BorderRadiusSize>;
+    transitionType: vue.Ref<TransitionType, TransitionType>;
+    enableTransition: vue.Ref<boolean, boolean>;
+    layoutMode: vue.Ref<LayoutMode, LayoutMode>;
+    menuExpandMode: vue.Ref<MenuExpandMode, MenuExpandMode>;
+    collapsed: vue.Ref<boolean, boolean>;
+    fixedHeader: vue.Ref<boolean, boolean>;
+    showBreadcrumb: vue.Ref<boolean, boolean>;
+    showBreadcrumbIcon: vue.Ref<boolean, boolean>;
+    showTagsView: vue.Ref<boolean, boolean>;
+    tagsViewHeight: vue.Ref<number, number>;
+    tagsViewStyle: vue.Ref<TagsViewStyle, TagsViewStyle>;
+    showFooter: vue.Ref<boolean, boolean>;
+    sidebarWidth: vue.Ref<number, number>;
+    sidebarCollapsedWidth: vue.Ref<number, number>;
+    headerHeight: vue.Ref<number, number>;
+    enableHotkeys: vue.Ref<boolean, boolean>;
+    version: vue.Ref<string, string>;
+    borderRadiusValue: vue.ComputedRef<"4px" | "6px" | "8px">;
+    transitionName: vue.ComputedRef<"" | "fade-transform" | "fade-slide" | "fade-zoom">;
+    shouldEnableTransition: vue.ComputedRef<boolean>;
+    settingsState: vue.ComputedRef<SettingsState>;
+    syncCSSVariables: () => void | undefined;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    resetSettings: () => void;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    toggleCollapse: () => void;
+}, "borderRadiusValue" | "transitionName" | "shouldEnableTransition" | "settingsState">, Pick<{
+    defaults: Readonly<{
+        themeMode: ThemeMode;
+        primaryColor: string;
+        borderRadius: BorderRadiusSize;
+        transitionType: TransitionType;
+        enableTransition: boolean;
+        layoutMode: LayoutMode;
+        menuExpandMode: MenuExpandMode;
+        collapsed: boolean;
+        fixedHeader: boolean;
+        showBreadcrumb: boolean;
+        showBreadcrumbIcon: boolean;
+        showTagsView: boolean;
+        tagsViewHeight: number;
+        tagsViewStyle: TagsViewStyle;
+        showFooter: boolean;
+        sidebarWidth: number;
+        sidebarCollapsedWidth: number;
+        headerHeight: number;
+        enableHotkeys: boolean;
+        version: string;
+    }>;
+    themeMode: vue.Ref<ThemeMode, ThemeMode>;
+    primaryColor: vue.Ref<string, string>;
+    borderRadius: vue.Ref<BorderRadiusSize, BorderRadiusSize>;
+    transitionType: vue.Ref<TransitionType, TransitionType>;
+    enableTransition: vue.Ref<boolean, boolean>;
+    layoutMode: vue.Ref<LayoutMode, LayoutMode>;
+    menuExpandMode: vue.Ref<MenuExpandMode, MenuExpandMode>;
+    collapsed: vue.Ref<boolean, boolean>;
+    fixedHeader: vue.Ref<boolean, boolean>;
+    showBreadcrumb: vue.Ref<boolean, boolean>;
+    showBreadcrumbIcon: vue.Ref<boolean, boolean>;
+    showTagsView: vue.Ref<boolean, boolean>;
+    tagsViewHeight: vue.Ref<number, number>;
+    tagsViewStyle: vue.Ref<TagsViewStyle, TagsViewStyle>;
+    showFooter: vue.Ref<boolean, boolean>;
+    sidebarWidth: vue.Ref<number, number>;
+    sidebarCollapsedWidth: vue.Ref<number, number>;
+    headerHeight: vue.Ref<number, number>;
+    enableHotkeys: vue.Ref<boolean, boolean>;
+    version: vue.Ref<string, string>;
+    borderRadiusValue: vue.ComputedRef<"4px" | "6px" | "8px">;
+    transitionName: vue.ComputedRef<"" | "fade-transform" | "fade-slide" | "fade-zoom">;
+    shouldEnableTransition: vue.ComputedRef<boolean>;
+    settingsState: vue.ComputedRef<SettingsState>;
+    syncCSSVariables: () => void | undefined;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    resetSettings: () => void;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    toggleCollapse: () => void;
+}, "syncCSSVariables" | "applyPreset" | "resetSettings" | "updateThemeMode" | "toggleCollapse">>;
+
+/**
+ * 创建设置管理 Store
+ * @param options - 配置选项
+ */
+declare function createSettingsStore(options?: SettingsStoreOptions): pinia.StoreDefinition<string, Pick<{
+    /** 当前 Store 实例实际使用的默认值。 */
+    defaults: Readonly<{
+        themeMode: ThemeMode;
+        primaryColor: string;
+        borderRadius: BorderRadiusSize;
+        transitionType: TransitionType;
+        enableTransition: boolean;
+        layoutMode: LayoutMode;
+        menuExpandMode: MenuExpandMode;
+        collapsed: boolean;
+        fixedHeader: boolean;
+        showBreadcrumb: boolean;
+        showBreadcrumbIcon: boolean;
+        showTagsView: boolean;
+        tagsViewHeight: number;
+        tagsViewStyle: TagsViewStyle;
+        showFooter: boolean;
+        sidebarWidth: number;
+        sidebarCollapsedWidth: number;
+        headerHeight: number;
+        enableHotkeys: boolean;
+        version: string;
+    }>;
+    themeMode: vue.Ref<ThemeMode, ThemeMode>;
+    primaryColor: vue.Ref<string, string>;
+    borderRadius: vue.Ref<BorderRadiusSize, BorderRadiusSize>;
+    transitionType: vue.Ref<TransitionType, TransitionType>;
+    enableTransition: vue.Ref<boolean, boolean>;
+    layoutMode: vue.Ref<LayoutMode, LayoutMode>;
+    menuExpandMode: vue.Ref<MenuExpandMode, MenuExpandMode>;
+    collapsed: vue.Ref<boolean, boolean>;
+    fixedHeader: vue.Ref<boolean, boolean>;
+    showBreadcrumb: vue.Ref<boolean, boolean>;
+    showBreadcrumbIcon: vue.Ref<boolean, boolean>;
+    showTagsView: vue.Ref<boolean, boolean>;
+    tagsViewHeight: vue.Ref<number, number>;
+    tagsViewStyle: vue.Ref<TagsViewStyle, TagsViewStyle>;
+    showFooter: vue.Ref<boolean, boolean>;
+    sidebarWidth: vue.Ref<number, number>;
+    sidebarCollapsedWidth: vue.Ref<number, number>;
+    headerHeight: vue.Ref<number, number>;
+    enableHotkeys: vue.Ref<boolean, boolean>;
+    version: vue.Ref<string, string>;
+    borderRadiusValue: vue.ComputedRef<"4px" | "6px" | "8px">;
+    transitionName: vue.ComputedRef<"" | "fade-transform" | "fade-slide" | "fade-zoom">;
+    shouldEnableTransition: vue.ComputedRef<boolean>;
+    settingsState: vue.ComputedRef<SettingsState>;
+    syncCSSVariables: () => void | undefined;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    resetSettings: () => void;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    toggleCollapse: () => void;
+}, "themeMode" | "layoutMode" | "primaryColor" | "borderRadius" | "transitionType" | "enableTransition" | "menuExpandMode" | "collapsed" | "fixedHeader" | "showBreadcrumb" | "showBreadcrumbIcon" | "showTagsView" | "tagsViewHeight" | "tagsViewStyle" | "showFooter" | "sidebarWidth" | "sidebarCollapsedWidth" | "headerHeight" | "enableHotkeys" | "version" | "defaults">, Pick<{
+    /** 当前 Store 实例实际使用的默认值。 */
+    defaults: Readonly<{
+        themeMode: ThemeMode;
+        primaryColor: string;
+        borderRadius: BorderRadiusSize;
+        transitionType: TransitionType;
+        enableTransition: boolean;
+        layoutMode: LayoutMode;
+        menuExpandMode: MenuExpandMode;
+        collapsed: boolean;
+        fixedHeader: boolean;
+        showBreadcrumb: boolean;
+        showBreadcrumbIcon: boolean;
+        showTagsView: boolean;
+        tagsViewHeight: number;
+        tagsViewStyle: TagsViewStyle;
+        showFooter: boolean;
+        sidebarWidth: number;
+        sidebarCollapsedWidth: number;
+        headerHeight: number;
+        enableHotkeys: boolean;
+        version: string;
+    }>;
+    themeMode: vue.Ref<ThemeMode, ThemeMode>;
+    primaryColor: vue.Ref<string, string>;
+    borderRadius: vue.Ref<BorderRadiusSize, BorderRadiusSize>;
+    transitionType: vue.Ref<TransitionType, TransitionType>;
+    enableTransition: vue.Ref<boolean, boolean>;
+    layoutMode: vue.Ref<LayoutMode, LayoutMode>;
+    menuExpandMode: vue.Ref<MenuExpandMode, MenuExpandMode>;
+    collapsed: vue.Ref<boolean, boolean>;
+    fixedHeader: vue.Ref<boolean, boolean>;
+    showBreadcrumb: vue.Ref<boolean, boolean>;
+    showBreadcrumbIcon: vue.Ref<boolean, boolean>;
+    showTagsView: vue.Ref<boolean, boolean>;
+    tagsViewHeight: vue.Ref<number, number>;
+    tagsViewStyle: vue.Ref<TagsViewStyle, TagsViewStyle>;
+    showFooter: vue.Ref<boolean, boolean>;
+    sidebarWidth: vue.Ref<number, number>;
+    sidebarCollapsedWidth: vue.Ref<number, number>;
+    headerHeight: vue.Ref<number, number>;
+    enableHotkeys: vue.Ref<boolean, boolean>;
+    version: vue.Ref<string, string>;
+    borderRadiusValue: vue.ComputedRef<"4px" | "6px" | "8px">;
+    transitionName: vue.ComputedRef<"" | "fade-transform" | "fade-slide" | "fade-zoom">;
+    shouldEnableTransition: vue.ComputedRef<boolean>;
+    settingsState: vue.ComputedRef<SettingsState>;
+    syncCSSVariables: () => void | undefined;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    resetSettings: () => void;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    toggleCollapse: () => void;
+}, "borderRadiusValue" | "transitionName" | "shouldEnableTransition" | "settingsState">, Pick<{
+    /** 当前 Store 实例实际使用的默认值。 */
+    defaults: Readonly<{
+        themeMode: ThemeMode;
+        primaryColor: string;
+        borderRadius: BorderRadiusSize;
+        transitionType: TransitionType;
+        enableTransition: boolean;
+        layoutMode: LayoutMode;
+        menuExpandMode: MenuExpandMode;
+        collapsed: boolean;
+        fixedHeader: boolean;
+        showBreadcrumb: boolean;
+        showBreadcrumbIcon: boolean;
+        showTagsView: boolean;
+        tagsViewHeight: number;
+        tagsViewStyle: TagsViewStyle;
+        showFooter: boolean;
+        sidebarWidth: number;
+        sidebarCollapsedWidth: number;
+        headerHeight: number;
+        enableHotkeys: boolean;
+        version: string;
+    }>;
+    themeMode: vue.Ref<ThemeMode, ThemeMode>;
+    primaryColor: vue.Ref<string, string>;
+    borderRadius: vue.Ref<BorderRadiusSize, BorderRadiusSize>;
+    transitionType: vue.Ref<TransitionType, TransitionType>;
+    enableTransition: vue.Ref<boolean, boolean>;
+    layoutMode: vue.Ref<LayoutMode, LayoutMode>;
+    menuExpandMode: vue.Ref<MenuExpandMode, MenuExpandMode>;
+    collapsed: vue.Ref<boolean, boolean>;
+    fixedHeader: vue.Ref<boolean, boolean>;
+    showBreadcrumb: vue.Ref<boolean, boolean>;
+    showBreadcrumbIcon: vue.Ref<boolean, boolean>;
+    showTagsView: vue.Ref<boolean, boolean>;
+    tagsViewHeight: vue.Ref<number, number>;
+    tagsViewStyle: vue.Ref<TagsViewStyle, TagsViewStyle>;
+    showFooter: vue.Ref<boolean, boolean>;
+    sidebarWidth: vue.Ref<number, number>;
+    sidebarCollapsedWidth: vue.Ref<number, number>;
+    headerHeight: vue.Ref<number, number>;
+    enableHotkeys: vue.Ref<boolean, boolean>;
+    version: vue.Ref<string, string>;
+    borderRadiusValue: vue.ComputedRef<"4px" | "6px" | "8px">;
+    transitionName: vue.ComputedRef<"" | "fade-transform" | "fade-slide" | "fade-zoom">;
+    shouldEnableTransition: vue.ComputedRef<boolean>;
+    settingsState: vue.ComputedRef<SettingsState>;
+    syncCSSVariables: () => void | undefined;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    resetSettings: () => void;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    toggleCollapse: () => void;
+}, "syncCSSVariables" | "applyPreset" | "resetSettings" | "updateThemeMode" | "toggleCollapse">>;
+/**
+ * 默认的设置 Store（使用默认配置）
+ */
+declare const useSettingsStore: pinia.StoreDefinition<string, Pick<{
+    /** 当前 Store 实例实际使用的默认值。 */
+    defaults: Readonly<{
+        themeMode: ThemeMode;
+        primaryColor: string;
+        borderRadius: BorderRadiusSize;
+        transitionType: TransitionType;
+        enableTransition: boolean;
+        layoutMode: LayoutMode;
+        menuExpandMode: MenuExpandMode;
+        collapsed: boolean;
+        fixedHeader: boolean;
+        showBreadcrumb: boolean;
+        showBreadcrumbIcon: boolean;
+        showTagsView: boolean;
+        tagsViewHeight: number;
+        tagsViewStyle: TagsViewStyle;
+        showFooter: boolean;
+        sidebarWidth: number;
+        sidebarCollapsedWidth: number;
+        headerHeight: number;
+        enableHotkeys: boolean;
+        version: string;
+    }>;
+    themeMode: vue.Ref<ThemeMode, ThemeMode>;
+    primaryColor: vue.Ref<string, string>;
+    borderRadius: vue.Ref<BorderRadiusSize, BorderRadiusSize>;
+    transitionType: vue.Ref<TransitionType, TransitionType>;
+    enableTransition: vue.Ref<boolean, boolean>;
+    layoutMode: vue.Ref<LayoutMode, LayoutMode>;
+    menuExpandMode: vue.Ref<MenuExpandMode, MenuExpandMode>;
+    collapsed: vue.Ref<boolean, boolean>;
+    fixedHeader: vue.Ref<boolean, boolean>;
+    showBreadcrumb: vue.Ref<boolean, boolean>;
+    showBreadcrumbIcon: vue.Ref<boolean, boolean>;
+    showTagsView: vue.Ref<boolean, boolean>;
+    tagsViewHeight: vue.Ref<number, number>;
+    tagsViewStyle: vue.Ref<TagsViewStyle, TagsViewStyle>;
+    showFooter: vue.Ref<boolean, boolean>;
+    sidebarWidth: vue.Ref<number, number>;
+    sidebarCollapsedWidth: vue.Ref<number, number>;
+    headerHeight: vue.Ref<number, number>;
+    enableHotkeys: vue.Ref<boolean, boolean>;
+    version: vue.Ref<string, string>;
+    borderRadiusValue: vue.ComputedRef<"4px" | "6px" | "8px">;
+    transitionName: vue.ComputedRef<"" | "fade-transform" | "fade-slide" | "fade-zoom">;
+    shouldEnableTransition: vue.ComputedRef<boolean>;
+    settingsState: vue.ComputedRef<SettingsState>;
+    syncCSSVariables: () => void | undefined;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    resetSettings: () => void;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    toggleCollapse: () => void;
+}, "themeMode" | "layoutMode" | "primaryColor" | "borderRadius" | "transitionType" | "enableTransition" | "menuExpandMode" | "collapsed" | "fixedHeader" | "showBreadcrumb" | "showBreadcrumbIcon" | "showTagsView" | "tagsViewHeight" | "tagsViewStyle" | "showFooter" | "sidebarWidth" | "sidebarCollapsedWidth" | "headerHeight" | "enableHotkeys" | "version" | "defaults">, Pick<{
+    /** 当前 Store 实例实际使用的默认值。 */
+    defaults: Readonly<{
+        themeMode: ThemeMode;
+        primaryColor: string;
+        borderRadius: BorderRadiusSize;
+        transitionType: TransitionType;
+        enableTransition: boolean;
+        layoutMode: LayoutMode;
+        menuExpandMode: MenuExpandMode;
+        collapsed: boolean;
+        fixedHeader: boolean;
+        showBreadcrumb: boolean;
+        showBreadcrumbIcon: boolean;
+        showTagsView: boolean;
+        tagsViewHeight: number;
+        tagsViewStyle: TagsViewStyle;
+        showFooter: boolean;
+        sidebarWidth: number;
+        sidebarCollapsedWidth: number;
+        headerHeight: number;
+        enableHotkeys: boolean;
+        version: string;
+    }>;
+    themeMode: vue.Ref<ThemeMode, ThemeMode>;
+    primaryColor: vue.Ref<string, string>;
+    borderRadius: vue.Ref<BorderRadiusSize, BorderRadiusSize>;
+    transitionType: vue.Ref<TransitionType, TransitionType>;
+    enableTransition: vue.Ref<boolean, boolean>;
+    layoutMode: vue.Ref<LayoutMode, LayoutMode>;
+    menuExpandMode: vue.Ref<MenuExpandMode, MenuExpandMode>;
+    collapsed: vue.Ref<boolean, boolean>;
+    fixedHeader: vue.Ref<boolean, boolean>;
+    showBreadcrumb: vue.Ref<boolean, boolean>;
+    showBreadcrumbIcon: vue.Ref<boolean, boolean>;
+    showTagsView: vue.Ref<boolean, boolean>;
+    tagsViewHeight: vue.Ref<number, number>;
+    tagsViewStyle: vue.Ref<TagsViewStyle, TagsViewStyle>;
+    showFooter: vue.Ref<boolean, boolean>;
+    sidebarWidth: vue.Ref<number, number>;
+    sidebarCollapsedWidth: vue.Ref<number, number>;
+    headerHeight: vue.Ref<number, number>;
+    enableHotkeys: vue.Ref<boolean, boolean>;
+    version: vue.Ref<string, string>;
+    borderRadiusValue: vue.ComputedRef<"4px" | "6px" | "8px">;
+    transitionName: vue.ComputedRef<"" | "fade-transform" | "fade-slide" | "fade-zoom">;
+    shouldEnableTransition: vue.ComputedRef<boolean>;
+    settingsState: vue.ComputedRef<SettingsState>;
+    syncCSSVariables: () => void | undefined;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    resetSettings: () => void;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    toggleCollapse: () => void;
+}, "borderRadiusValue" | "transitionName" | "shouldEnableTransition" | "settingsState">, Pick<{
+    /** 当前 Store 实例实际使用的默认值。 */
+    defaults: Readonly<{
+        themeMode: ThemeMode;
+        primaryColor: string;
+        borderRadius: BorderRadiusSize;
+        transitionType: TransitionType;
+        enableTransition: boolean;
+        layoutMode: LayoutMode;
+        menuExpandMode: MenuExpandMode;
+        collapsed: boolean;
+        fixedHeader: boolean;
+        showBreadcrumb: boolean;
+        showBreadcrumbIcon: boolean;
+        showTagsView: boolean;
+        tagsViewHeight: number;
+        tagsViewStyle: TagsViewStyle;
+        showFooter: boolean;
+        sidebarWidth: number;
+        sidebarCollapsedWidth: number;
+        headerHeight: number;
+        enableHotkeys: boolean;
+        version: string;
+    }>;
+    themeMode: vue.Ref<ThemeMode, ThemeMode>;
+    primaryColor: vue.Ref<string, string>;
+    borderRadius: vue.Ref<BorderRadiusSize, BorderRadiusSize>;
+    transitionType: vue.Ref<TransitionType, TransitionType>;
+    enableTransition: vue.Ref<boolean, boolean>;
+    layoutMode: vue.Ref<LayoutMode, LayoutMode>;
+    menuExpandMode: vue.Ref<MenuExpandMode, MenuExpandMode>;
+    collapsed: vue.Ref<boolean, boolean>;
+    fixedHeader: vue.Ref<boolean, boolean>;
+    showBreadcrumb: vue.Ref<boolean, boolean>;
+    showBreadcrumbIcon: vue.Ref<boolean, boolean>;
+    showTagsView: vue.Ref<boolean, boolean>;
+    tagsViewHeight: vue.Ref<number, number>;
+    tagsViewStyle: vue.Ref<TagsViewStyle, TagsViewStyle>;
+    showFooter: vue.Ref<boolean, boolean>;
+    sidebarWidth: vue.Ref<number, number>;
+    sidebarCollapsedWidth: vue.Ref<number, number>;
+    headerHeight: vue.Ref<number, number>;
+    enableHotkeys: vue.Ref<boolean, boolean>;
+    version: vue.Ref<string, string>;
+    borderRadiusValue: vue.ComputedRef<"4px" | "6px" | "8px">;
+    transitionName: vue.ComputedRef<"" | "fade-transform" | "fade-slide" | "fade-zoom">;
+    shouldEnableTransition: vue.ComputedRef<boolean>;
+    settingsState: vue.ComputedRef<SettingsState>;
+    syncCSSVariables: () => void | undefined;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    resetSettings: () => void;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    toggleCollapse: () => void;
+}, "syncCSSVariables" | "applyPreset" | "resetSettings" | "updateThemeMode" | "toggleCollapse">>;
+/** 默认设置 Store 实例类型，供组件注入或显式传入。 */
+type SettingsStoreInstance = ReturnType<typeof useSettingsStore>;
+
+/** 布局内置导航可以安全消费的标准菜单项。 */
+type LayoutMenuItem<TMeta extends MenuMeta = MenuMeta> = Omit<MenuOptions<TMeta>, "children" | "key" | "meta" | "path"> & {
+    key: string;
+    path: string;
+    meta: TMeta & {
+        title: string;
+    };
+    children?: LayoutMenuItem<TMeta>[];
+};
+/**
+ * 非破坏地统一 path/key、label/meta.title 与字符串图标来源。
+ * 缺少稳定路径或 key 的节点不会进入导航，避免意外跳转到根路由。
+ */
+declare function normalizeLayoutMenus<TMeta extends MenuMeta = MenuMeta>(menus: readonly MenuOptions<TMeta>[]): LayoutMenuItem<TMeta>[];
+
+/**
+ * @robot-admin/layout
+ *
+ * 布局上下文 - Provide/Inject 机制
+ * 消费方通过 provide 注入数据，骨架组件通过 inject 读取
+ * 实现布局骨架与业务数据的完全解耦
+ */
+
+/**
+ * 品牌配置
+ */
+interface LayoutBrandConfig {
+    /** 品牌名称，如 'Robot Admin' */
+    name?: string;
+    /** 品牌副标题，如 '机器人管理系统' */
+    subtitle?: string;
+    /** Logo 地址（图片或视频） */
+    logoSrc?: string;
+    /** Logo 类型 */
+    logoType?: "video" | "image";
+    /** Logo 尺寸 */
+    logoSize?: number;
+    /** 首页路径，默认 '/home' */
+    homePath?: string;
+    /** 页脚版权文本 */
+    copyright?: string;
+}
+/**
+ * 布局上下文数据接口
+ * 骨架组件通过 inject 获取这些数据
+ */
+interface LayoutContext {
+    /** 菜单列表数据 */
+    menus: ComputedRef<MenuOptions[]>;
+    /** 是否为暗色模式 */
+    isDark: ComputedRef<boolean>;
+    /** 当前布局模式 */
+    layoutMode: ComputedRef<LayoutMode>;
+    /** 侧边栏折叠状态；提供后由容器和宿主头部共享同一数据源 */
+    collapsed?: WritableComputedRef<boolean>;
+    /** 菜单展开方式 */
+    menuExpandMode?: ComputedRef<MenuExpandMode>;
+    /** 侧边栏宽度 (px) */
+    sidebarWidth: ComputedRef<number>;
+    /** 侧边栏折叠后宽度 (px) */
+    sidebarCollapsedWidth: ComputedRef<number>;
+    /** 是否显示页脚 */
+    showFooter: ComputedRef<boolean>;
+    /** 是否显示标签页 */
+    showTagsView: ComputedRef<boolean>;
+    /** 标签页高度 (px) */
+    tagsViewHeight: ComputedRef<number>;
+    /** 头部高度 (px) */
+    headerHeight: ComputedRef<number>;
+    /** 过渡动画名称 */
+    transitionName: ComputedRef<string>;
+    /** 是否显示面包屑 */
+    showBreadcrumb: ComputedRef<boolean>;
+    /** 是否显示面包屑图标 */
+    showBreadcrumbIcon: ComputedRef<boolean>;
+    /** 是否固定头部 */
+    fixedHeader: ComputedRef<boolean>;
+    /** 品牌信息 */
+    brand: LayoutBrandConfig;
+    /**
+     * 自定义图标组件（如 @iconify/vue 的 Icon 组件）
+     * 用于布局内部组件渲染菜单图标
+     * 组件需接受 name (string) 和 size (number) 两个 props
+     * 如果不提供，将使用 CSS class 渲染图标
+     */
+    iconComponent?: Component;
+}
+/**
+ * 布局上下文 Injection Key
+ */
+declare const LAYOUT_CONTEXT_KEY: InjectionKey<LayoutContext>;
+/** 当前布局使用的设置 Store，支持自定义 Store id 与多实例。 */
+declare const LAYOUT_SETTINGS_KEY: InjectionKey<SettingsStoreInstance>;
+/** 侧边栏折叠控制器。 */
+interface MenuCollapseHandlers {
+    isCollapsed: ComputedRef<boolean>;
+    handleCollapsedChange: (collapsed: boolean) => void;
+}
+declare const MENU_COLLAPSE_KEY: InjectionKey<MenuCollapseHandlers>;
+/**
+ * 抽屉菜单统一控制器
+ * 解决 MenuTrigger 与 DrawerMenu 各自拥有独立定时器导致的
+ * "鼠标从 trigger 移到 drawer 过程中 drawer 被关闭"问题
+ */
+interface DrawerHandlers {
+    /** 显示抽屉并取消所有待执行的隐藏操作 */
+    show: () => void;
+    /** 启动延迟隐藏（300ms） */
+    startHide: () => void;
+    /** 立即隐藏抽屉（如导航跳转后） */
+    hide: () => void;
+}
+/**
+ * 抽屉菜单控制器 Injection Key
+ */
+declare const DRAWER_HANDLER_KEY: InjectionKey<DrawerHandlers>;
+/**
+ * 在骨架组件中获取布局上下文
+ *
+ * @throws 如果没有 provide LayoutContext 会抛出错误
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * // 在包的骨架组件内部使用
+ * const ctx = useLayoutContext()
+ * const menus = ctx.menus
+ * const isDark = ctx.isDark
+ * </script>
+ * ```
+ */
+declare function useLayoutContext(): LayoutContext;
+/** 在组件 setup 中提供布局上下文，避免消费方直接操作 InjectionKey。 */
+declare function provideLayoutContext(context: LayoutContext): LayoutContext;
+/**
+ * 默认品牌配置
+ */
+declare const DEFAULT_BRAND_CONFIG: Required<LayoutBrandConfig>;
+
+/**
+ * 布局桥接所需的最小设置协议。
+ *
+ * 默认 Pinia Store 天然满足该协议，宿主也可以传入其他响应式 Store，
+ * 避免上下文助手与具体状态管理实现强绑定。
+ */
+interface LayoutSettingsSource {
+    layoutMode: LayoutMode;
+    collapsed: boolean;
+    menuExpandMode: MenuExpandMode;
+    sidebarWidth: number;
+    sidebarCollapsedWidth: number;
+    showFooter: boolean;
+    showTagsView: boolean;
+    tagsViewHeight: number;
+    headerHeight: number;
+    transitionName: string;
+    showBreadcrumb: boolean;
+    showBreadcrumbIcon: boolean;
+    fixedHeader: boolean;
+}
+/** 创建标准布局上下文所需的最小宿主适配。 */
+interface CreateLayoutContextOptions {
+    /** 布局设置 Store，可使用默认 Store 或 createSettingsStore() 创建的实例。 */
+    settings: LayoutSettingsSource;
+    /** 宿主菜单；支持普通值、Ref、ComputedRef 或 getter。 */
+    menus: MaybeRefOrGetter<MenuOptions[]>;
+    /** 宿主暗色状态；支持普通值、Ref、ComputedRef 或 getter。 */
+    isDark: MaybeRefOrGetter<boolean>;
+    /** 品牌信息，未提供的字段使用包内安全默认值。 */
+    brand?: LayoutBrandConfig;
+    /** 布局内部用于渲染菜单图标的宿主组件。 */
+    iconComponent?: Component;
+}
+/**
+ * 将最小宿主输入转换为完整 LayoutContext。
+ *
+ * 保留底层 LayoutContext 作为高级扩展协议，同时避免普通接入重复桥接 Store 字段。
+ */
+declare function createLayoutContext(options: CreateLayoutContextOptions): LayoutContext;
+/** 在组件 setup 中创建并提供标准布局上下文。 */
+declare function provideLayout(options: CreateLayoutContextOptions): LayoutContext;
+
+/** KeepAlive 缓存选项 */
+interface LayoutCacheOptions {
+    /** 最大缓存数量，默认 20 */
+    maxCacheCount?: number;
+    /** 是否输出缓存调试日志，默认 false */
+    enableDevLog?: boolean;
+    /** 是否暴露调试方法到 window，默认 false */
+    exposeToWindow?: boolean;
+}
+/** KeepAlive 仅接受具名组件，并由路由 meta.keepAlive 明确开启。 */
+declare function shouldCacheRoute(route: Pick<RouteLocationNormalizedLoaded, "name" | "meta">): route is Pick<RouteLocationNormalizedLoaded, "name" | "meta"> & {
+    name: string;
+};
+/**
+ * 统一的 KeepAlive 缓存管理 composable
+ *
+ * @param options - 缓存配置选项
+ * @returns 缓存视图列表和管理方法
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useLayoutCache } from '@robot-admin/layout/vue'
+ *
+ * const { cachedViews, maxCacheCount } = useLayoutCache({ maxCacheCount: 30 })
+ * </script>
+ *
+ * <template>
+ *   <KeepAlive :include="cachedViews" :max="maxCacheCount">
+ *     <RouterView />
+ *   </KeepAlive>
+ * </template>
+ * ```
+ */
+declare function useLayoutCache(options?: LayoutCacheOptions): {
+    cachedViews: vue.Ref<string[], string[]>;
+    maxCacheCount: vue.Ref<number, number>;
+    addCache: (name: string) => void;
+    removeCache: (name: string) => void;
+    clearAllCache: () => void;
+};
+
+/**
+ * @robot-admin/layout
+ *
+ * 菜单拆分 Composable - 通用的一级/二级菜单拆分逻辑
+ * 用于 Mix / MixTop / ReverseHorizontalMix 等需要菜单拆分的布局
+ */
+
+interface UseMenuSplitOptions {
+    /** 菜单数据（响应式） */
+    menus: MaybeRefOrGetter<readonly MenuOptions[]>;
+    /** 是否使用悬浮式二级菜单（C_MixLayout 的 toggle 模式） */
+    floatingSecondMenu?: MaybeRefOrGetter<boolean>;
+}
+interface UseMenuSplitReturn {
+    /** 当前激活的一级菜单路径 */
+    activeFirstMenu: Ref<string>;
+    /** 当前激活的一级菜单完整数据 */
+    activeFirstMenuItem: ComputedRef<MenuOptions | undefined>;
+    /** 当前一级菜单对应的二级菜单列表 */
+    currentSecondMenus: ComputedRef<MenuOptions[]>;
+    /** 悬浮的菜单项（C_MixLayout 使用） */
+    hoveredMenuItem: Ref<MenuOptions | null>;
+    /** 实际展示的菜单项（hovered 优先，fallback 到 active） */
+    displayMenuItem: ComputedRef<MenuOptions | null>;
+    /** 是否显示悬浮二级菜单（C_MixLayout 使用） */
+    showSecondMenu: Ref<boolean>;
+    /** 处理一级菜单点击 */
+    handleFirstMenuClick: (item: MenuOptions) => void;
+    /** 处理二级菜单点击 */
+    handleSecondMenuClick: (item: MenuOptions) => void;
+    /** 检查路由是否匹配菜单项 */
+    isMenuItemActive: (menuPath: string | undefined) => boolean;
+}
+/** 判断当前路径是否等于菜单路径或位于其子路径下。 */
+declare function isPathSegmentPrefix(menuPath: string | undefined, currentPath: string): boolean;
+/**
+ * 菜单拆分 Composable
+ *
+ * 提供一级/二级菜单拆分状态管理、路由自动匹配、菜单点击处理。
+ * 供 C_MixLayout / C_MixTopLayout / C_ReverseHorizontalMixLayout 共用。
+ *
+ * @example
+ * ```ts
+ * const menuSplit = useMenuSplit({
+ *   menus: ctx.menus,
+ *   floatingSecondMenu: computed(() => layoutMode.value === 'mix'),
+ * })
+ * ```
+ */
+declare function useMenuSplit(options: UseMenuSplitOptions): UseMenuSplitReturn;
+
+/** 响应式菜单测量选项。 */
+interface UseResponsiveMenuOptions {
+    data: MaybeRefOrGetter<readonly MenuOptions[]>;
+    /** 溢出菜单按钮和安全间距占用的宽度，默认 95px。 */
+    overflowReserve?: number;
+    /** ResizeObserver 触发后的防抖时间，默认 100ms。 */
+    debounceMs?: number;
+}
+/** 按现有菜单字号与间距估算单项宽度。 */
+declare function estimateMenuItemWidth(item: MenuOptions): number;
+/** 计算指定容器内可直接展示的菜单项数量。 */
+declare function calculateVisibleMenuCount(items: readonly MenuOptions[], containerWidth: number, overflowReserve?: number): number;
+/**
+ * UI 框架无关的响应式菜单测量逻辑。
+ * Naive UI 和 Element Plus 适配器只负责把 visible/hidden 数据渲染出来。
+ */
+declare function useResponsiveMenu(options: UseResponsiveMenuOptions): {
+    containerRef: vue.Ref<HTMLElement | undefined, HTMLElement | undefined>;
+    hiddenItems: vue.Ref<{
+        type?: MenuItemType | undefined;
+        key?: string | undefined;
+        path?: string | undefined;
+        name?: string | undefined;
+        component?: string | undefined;
+        redirect?: string | undefined;
+        label?: string | undefined;
+        icon?: (string | (() => vue.VNode) | vue.VNode) | undefined;
+        disabled?: boolean | undefined;
+        meta?: {
+            [x: string]: unknown;
+            title?: string | undefined;
+            icon?: string | undefined;
+            hidden?: boolean | undefined;
+            affix?: boolean | undefined;
+            keepAlive?: boolean | undefined;
+            full?: boolean | undefined;
+            link?: string | undefined;
+        } | undefined;
+        children?: /*elided*/ any[] | undefined;
+    }[], MenuOptions<MenuMeta>[] | {
+        type?: MenuItemType | undefined;
+        key?: string | undefined;
+        path?: string | undefined;
+        name?: string | undefined;
+        component?: string | undefined;
+        redirect?: string | undefined;
+        label?: string | undefined;
+        icon?: (string | (() => vue.VNode) | vue.VNode) | undefined;
+        disabled?: boolean | undefined;
+        meta?: {
+            [x: string]: unknown;
+            title?: string | undefined;
+            icon?: string | undefined;
+            hidden?: boolean | undefined;
+            affix?: boolean | undefined;
+            keepAlive?: boolean | undefined;
+            full?: boolean | undefined;
+            link?: string | undefined;
+        } | undefined;
+        children?: /*elided*/ any[] | undefined;
+    }[]>;
+    refresh: () => void;
+    visibleItems: vue.Ref<{
+        type?: MenuItemType | undefined;
+        key?: string | undefined;
+        path?: string | undefined;
+        name?: string | undefined;
+        component?: string | undefined;
+        redirect?: string | undefined;
+        label?: string | undefined;
+        icon?: (string | (() => vue.VNode) | vue.VNode) | undefined;
+        disabled?: boolean | undefined;
+        meta?: {
+            [x: string]: unknown;
+            title?: string | undefined;
+            icon?: string | undefined;
+            hidden?: boolean | undefined;
+            affix?: boolean | undefined;
+            keepAlive?: boolean | undefined;
+            full?: boolean | undefined;
+            link?: string | undefined;
+        } | undefined;
+        children?: /*elided*/ any[] | undefined;
+    }[], MenuOptions<MenuMeta>[] | {
+        type?: MenuItemType | undefined;
+        key?: string | undefined;
+        path?: string | undefined;
+        name?: string | undefined;
+        component?: string | undefined;
+        redirect?: string | undefined;
+        label?: string | undefined;
+        icon?: (string | (() => vue.VNode) | vue.VNode) | undefined;
+        disabled?: boolean | undefined;
+        meta?: {
+            [x: string]: unknown;
+            title?: string | undefined;
+            icon?: string | undefined;
+            hidden?: boolean | undefined;
+            affix?: boolean | undefined;
+            keepAlive?: boolean | undefined;
+            full?: boolean | undefined;
+            link?: string | undefined;
+        } | undefined;
+        children?: /*elided*/ any[] | undefined;
+    }[]>;
+};
+
+/** 返回宿主图标组件；未配置时使用零依赖 CSS class 渲染器。 */
+declare function useLayoutIcon(): Component;
+
+/** 宿主没有实现可选高副作用操作。 */
+declare class LayoutActionUnavailableError extends Error {
+    constructor(action: keyof SettingsDrawerActions);
+}
+interface SettingsControllerOptions {
+    store: SettingsStoreInstance;
+    actions?: SettingsDrawerActions;
+    maxImportBytes?: number;
+    /** 灰度/色弱 class 的作用元素；默认 document.documentElement。 */
+    visualRoot?: HTMLElement | null;
+    /** 水印挂载容器；默认 document.body。 */
+    watermarkContainer?: HTMLElement | null;
+    watermarkText?: string;
+    onVisualEffectError?: (message: string) => void;
+}
+interface ExportedLayoutSettings extends LayoutSettingsConfig {
+    schemaVersion: typeof SETTINGS_CONFIG_SCHEMA_VERSION;
+    exportTime: string;
+}
+/**
+ * SettingsDrawer 的 UI 框架无关控制器。
+ *
+ * 负责配置事务、导入导出和页面级视觉效果；Naive UI / Element Plus
+ * 适配器只处理组件渲染、消息和确认框。
+ * 在 Vue setup/effect scope 内会自动清理；在作用域外创建时应调用返回值的 dispose()。
+ */
+declare function useSettingsController(options: SettingsControllerOptions): {
+    applyImportedConfig: (input: unknown) => Promise<LayoutSettingsConfig>;
+    applyPreset: (preset: ThemePreset) => Promise<void>;
+    clearCache: () => Promise<void>;
+    colorWeakMode: vue.Ref<boolean, boolean>;
+    createExportConfig: () => ExportedLayoutSettings;
+    dispose: () => void;
+    downloadConfig: () => boolean;
+    grayMode: vue.Ref<boolean, boolean>;
+    importFile: (file: Pick<File, "size" | "text">) => Promise<LayoutSettingsConfig>;
+    reloadPage: () => void;
+    resetAll: () => Promise<void>;
+    resetAppearance: () => Promise<void>;
+    resetLayout: () => void;
+    systemInfo: vue.ComputedRef<{
+        browser: string;
+        os: string;
+        resolution: string;
+        pixelRatio: string;
+        language: string;
+        timezone: string;
+    }>;
+    updateThemeMode: (mode: ThemeMode) => Promise<void>;
+    watermarkEnabled: vue.Ref<boolean, boolean>;
+    watermarkText: vue.Ref<string, string>;
+};
+
+interface LayoutCssVariableSource {
+    primaryColor: MaybeRefOrGetter<string>;
+    borderRadiusValue: MaybeRefOrGetter<string>;
+    sidebarWidth: MaybeRefOrGetter<number>;
+    sidebarCollapsedWidth: MaybeRefOrGetter<number>;
+    headerHeight: MaybeRefOrGetter<number>;
+    tagsViewHeight: MaybeRefOrGetter<number>;
+}
+interface LayoutStyleDeclaration {
+    getPropertyValue(name: string): string;
+    removeProperty(name: string): string;
+    setProperty(name: string, value: string): void;
+}
+interface LayoutCssVariableTarget {
+    style: LayoutStyleDeclaration;
+}
+interface LayoutCssVariableOptions {
+    /** 变量写入目标；默认 document.documentElement。 */
+    target?: MaybeRefOrGetter<LayoutCssVariableTarget | null | undefined>;
+    /** 同时维护 3.x 无前缀变量，默认 false。 */
+    legacyAliases?: boolean;
+}
+interface LayoutCssVariableBinding {
+    dispose: () => void;
+    sync: () => void;
+}
+/**
+ * 将响应式设置绑定到指定样式作用域，并在 dispose 时精确恢复原值。
+ */
+declare function bindLayoutCssVariables(source: LayoutCssVariableSource, options?: LayoutCssVariableOptions): LayoutCssVariableBinding;
+/** setup 作用域内使用的自动清理版本。 */
+declare function useLayoutCssVariables(source: LayoutCssVariableSource, options?: LayoutCssVariableOptions): LayoutCssVariableBinding;
+
+export { BORDER_RADIUS_MAP, type BorderRadiusSize, COLOR_SWATCHES, type CreateLayoutContextOptions, DEFAULT_BRAND_CONFIG, DEFAULT_SETTINGS, DRAWER_HANDLER_KEY, type DrawerHandlers, type ExportedLayoutSettings, LAYOUT_CONTEXT_KEY, LAYOUT_MODES, LAYOUT_SETTINGS_KEY, LayoutActionUnavailableError, type LayoutBrandConfig, type LayoutCacheOptions, type LayoutContext, type LayoutCssVariableBinding, type LayoutCssVariableOptions, type LayoutCssVariableSource, type LayoutCssVariableTarget, type LayoutInfo, type LayoutMenuItem, type LayoutMode, type LayoutSettingsConfig, type LayoutSettingsSource, type LayoutStyleDeclaration, type LayoutVisualEffects, MENU_COLLAPSE_KEY, type MenuCollapseHandlers, type MenuExpandMode, type MenuItemType, type MenuMeta, type MenuOptions, type MenuTag, PRESET_COLORS, type PresetColor, SETTINGS_CONFIG_SCHEMA_VERSION, type SettingsControllerOptions, type SettingsDrawerActions, type SettingsState, type SettingsStoreInstance, type SettingsStoreOptions, THEME_PRESETS, TRANSITION_MAP, type TagsViewStyle, type ThemeMode, type ThemePreset, type TransitionType, type UseMenuSplitOptions, type UseMenuSplitReturn, type UseResponsiveMenuOptions, adjustColor, assertLayoutSettingsRelationships, bindLayoutCssVariables, calculateVisibleMenuCount, createLayoutContext, createSettingsStore, estimateMenuItemWidth, isPathSegmentPrefix, normalizeLayoutMenus, provideLayout, provideLayoutContext, sanitizeLayoutSettingsConfig, sanitizeSettingsPatch, setupLayout, shouldCacheRoute, useLayoutCache, useLayoutContext, useLayoutCssVariables, useLayoutIcon, useMenuSplit, useResponsiveMenu, useSettingsController, useSettingsStore };