@tker-react/layout 0.2.0

package/README.md

@@ -0,0 +1,501 @@
+# @tker-react/layout
+
+React 后台管理布局框架，提供菜单、面包屑、标签页、侧边栏等布局能力。
+
+- **无内置 adapter**：不依赖特定 UI 库，所有 UI 渲染由使用者通过 adapter 组件控制
+- **React Context 共享状态**：`<Layout>` 内置 Provider，通过 `useLayout()` 管理状态
+- **路由解耦**：不直接依赖路由库，通过 `setNavigateAdapter` 和 `setActivePath` 与路由层对接
+
+## 安装
+
+```bash
+pnpm add @tker-react/layout
+```
+
+如果生产构建时样式丢失，手动导入 CSS：
+
+```ts
+import "@tker-react/layout/layout.css";
+```
+
+## 快速开始
+
+使用 TanStack Router 的完整示例，展示 App 入口、布局配置和路由同步。
+
+### 1. 创建 AppLayout
+
+```tsx
+// layouts/AppLayout.tsx
+import { Layout, useLayout } from "@tker-react/layout";
+import { Outlet, useRouter, useRouterState } from "@tanstack/react-router";
+import { useLayoutEffect } from "react";
+
+export function AppLayout() {
+    return (
+        <Layout>
+            <SetupLayout />
+            <Outlet />
+        </Layout>
+    );
+}
+
+function SetupLayout() {
+    const layout = useLayout();
+    const router = useRouter();
+    const pathname = useRouterState({ select: (s) => s.location.pathname });
+    const search = useRouterState({ select: (s) => s.location.searchStr });
+
+    // adapter 注册和菜单设置必须在 useLayoutEffect 中调用
+    useLayoutEffect(() => {
+        layout.setMenuAdapter(MenuAdapter);
+        layout.setBreadcrumbAdapter(BreadcrumbAdapter);
+        layout.setTabAdapter(TabAdapter);
+        layout.setLogoAdapter(LogoAdapter);
+        layout.setToolbarAdapter(ToolbarAdapter);
+        layout.setUserAvatarAdapter(UserAvatarAdapter);
+        layout.setMenus([
+            { path: "/dashboard", title: "仪表盘" },
+            {
+                path: "/users",
+                title: "用户管理",
+                children: [
+                    { path: "/users", title: "用户列表" },
+                    { path: "/users/detail", title: "用户详情" },
+                ],
+            },
+        ]);
+        layout.setHomePath("/dashboard");
+    }, []);
+
+    // setNavigateAdapter 存储 ref，可以直接在 render 中调用
+    layout.setNavigateAdapter((path) => router.navigate({ to: path }));
+
+    useLayoutEffect(() => {
+        layout.setActivePath(pathname, pathname + search);
+    }, [pathname, search]);
+
+    return null;
+}
+```
+
+> **注意**：`setXxxAdapter`、`setMenus` 等方法内部会调用 `setState`，必须在 `useLayoutEffect`（或 `useEffect`）中调用，不能在 render 期间直接调用，否则 React 会报 "Cannot update a component while rendering" 错误。`setNavigateAdapter` 只写 ref，可以在 render 中直接调用。
+
+### 2. 定义路由并挂载
+
+```tsx
+// router.tsx
+import { createRootRoute, createRoute, createRouter } from "@tanstack/react-router";
+import { AppLayout } from "./layouts/AppLayout";
+
+const rootRoute = createRootRoute({ component: AppLayout });
+
+const indexRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: "/",
+    component: Dashboard,
+});
+
+const dashboardRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: "/dashboard",
+    component: Dashboard,
+});
+
+const routeTree = rootRoute.addChildren([indexRoute, dashboardRoute]);
+
+export const router = createRouter({ routeTree });
+```
+
+```tsx
+// App.tsx
+import { RouterProvider } from "@tanstack/react-router";
+import { router } from "./router";
+
+export function App() {
+    return <RouterProvider router={router} />;
+}
+```
+
+### 3. 编写 adapter 组件
+
+adapter 组件接收 Layout 传入的 props，内部使用任意 UI 库渲染。以下是使用 shadcn/ui 的完整示例。
+
+#### Logo adapter
+
+```tsx
+// LogoAdapter.tsx
+import type { LogoAdapterProps } from "@tker-react/layout";
+
+function LogoAdapter({ collapsed }: LogoAdapterProps) {
+  return collapsed ? (
+    <div className="flex items-center justify-center h-full px-2">
+      <img src="/logo-sm.svg" alt="logo" className="w-6 h-6" />
+    </div>
+  ) : (
+    <div className="flex items-center gap-2 px-4 h-full">
+      <img src="/logo.svg" alt="logo" className="w-6 h-6" />
+      <span className="font-semibold text-sm">Admin</span>
+    </div>
+  );
+}
+```
+
+#### Menu adapter
+
+```tsx
+// MenuAdapter.tsx
+import type { MenuAdapterProps, MenuItem } from "@tker-react/layout";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";
+import { cn } from "@/lib/utils";
+
+function MenuAdapter({ menuData, activePath, collapsed, mode, onSelect }: MenuAdapterProps) {
+  if (mode === "top") {
+    return (
+      <nav className="flex items-center gap-1 h-full">
+        {menuData.map((item) => (
+          <button
+            key={item.path}
+            onClick={() => onSelect(item.path)}
+            className={cn(
+              "px-3 py-1 text-sm rounded-md",
+              activePath === item.path ? "bg-accent text-accent-foreground" : "hover:bg-muted"
+            )}
+          >
+            {item.icon && <item.icon className="w-4 h-4 inline mr-1" />}
+            {item.title || item.path}
+          </button>
+        ))}
+      </nav>
+    );
+  }
+
+  return (
+    <nav className="flex flex-col gap-1 p-2 overflow-y-auto">
+      {menuData.map((item) => (
+        <MenuItemRenderer
+          key={item.path}
+          item={item}
+          activePath={activePath}
+          collapsed={collapsed}
+          onSelect={onSelect}
+        />
+      ))}
+    </nav>
+  );
+}
+
+function MenuItemRenderer({
+  item,
+  activePath,
+  collapsed,
+  onSelect,
+  depth = 0,
+}: {
+  item: MenuItem;
+  activePath: string;
+  collapsed: boolean;
+  onSelect: (path: string) => void;
+  depth?: number;
+}) {
+  const hasChildren = item.children && item.children.length > 0;
+
+  if (hasChildren) {
+    return (
+      <Collapsible>
+        <CollapsibleTrigger
+          className={cn(
+            "flex items-center w-full rounded-md text-sm hover:bg-muted px-2 py-1.5",
+            !collapsed && "gap-2"
+          )}
+          style={{ paddingLeft: collapsed ? undefined : `${8 + depth * 12}px` }}
+        >
+          {item.icon && <item.icon className="w-4 h-4 shrink-0" />}
+          {!collapsed && (
+            <>
+              <span className="flex-1 text-left">{item.title || item.path}</span>
+              <ChevronDown className="w-3 h-3" />
+            </>
+          )}
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          {item.children!.map((child) => (
+            <MenuItemRenderer
+              key={child.path}
+              item={child}
+              activePath={activePath}
+              collapsed={collapsed}
+              onSelect={onSelect}
+              depth={depth + 1}
+            />
+          ))}
+        </CollapsibleContent>
+      </Collapsible>
+    );
+  }
+
+  return (
+    <button
+      onClick={() => onSelect(item.path)}
+      className={cn(
+        "flex items-center rounded-md text-sm px-2 py-1.5",
+        activePath === item.path
+          ? "bg-accent text-accent-foreground"
+          : "hover:bg-muted",
+        !collapsed && "gap-2"
+      )}
+      style={{ paddingLeft: collapsed ? undefined : `${8 + depth * 12}px` }}
+    >
+      {item.icon && <item.icon className="w-4 h-4 shrink-0" />}
+      {!collapsed && (item.title || item.path)}
+    </button>
+  );
+}
+```
+
+#### Breadcrumb adapter
+
+```tsx
+// BreadcrumbAdapter.tsx
+import type { BreadcrumbAdapterProps } from "@tker-react/layout";
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbSeparator,
+} from "@/components/ui/breadcrumb";
+
+function BreadcrumbAdapter({ breadcrumbData, onSelect }: BreadcrumbAdapterProps) {
+  return (
+    <Breadcrumb>
+      <BreadcrumbList>
+        {breadcrumbData.map((item, index) => (
+          <div key={item.path} className="flex items-center gap-1">
+            <BreadcrumbItem>
+              <BreadcrumbLink
+                asChild
+                className={index === breadcrumbData.length - 1 ? "text-foreground" : ""}
+              >
+                <button
+                  onClick={() => onSelect(item.path)}
+                  disabled={index === breadcrumbData.length - 1}
+                >
+                  {item.title}
+                </button>
+              </BreadcrumbLink>
+            </BreadcrumbItem>
+            {index < breadcrumbData.length - 1 && <BreadcrumbSeparator />}
+          </div>
+        ))}
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}
+```
+
+#### Tab adapter
+
+```tsx
+// TabAdapter.tsx
+import type { TabAdapterProps } from "@tker-react/layout";
+import { cn } from "@/lib/utils";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "@/components/ui/dropdown-menu";
+
+function TabAdapter({
+  tabData,
+  activeTab,
+  onSelect,
+  onClose,
+  onCloseOther,
+  onCloseAll,
+  onRefresh,
+}: TabAdapterProps) {
+  return (
+    <div className="flex items-center h-9 bg-muted border-b">
+      <div className="flex-1 flex overflow-x-auto scrollbar-none">
+        {tabData.map((tab) => (
+          <div
+            key={tab.path}
+            onClick={() => onSelect(tab.path)}
+            className={cn(
+              "flex items-center gap-1 px-3 py-1 text-sm cursor-pointer border-r shrink-0",
+              tab.path === activeTab
+                ? "bg-background text-foreground"
+                : "text-muted-foreground hover:bg-muted-foreground/10"
+            )}
+          >
+            {tab.icon && <tab.icon className="w-3.5 h-3.5" />}
+            <span>{tab.title}</span>
+            {!tab.fixed && (
+              <button
+                onClick={(e) => { e.stopPropagation(); onClose(tab.path); }}
+                className="ml-1 rounded-full hover:bg-muted p-0.5"
+              >
+                <X className="w-3 h-3" />
+              </button>
+            )}
+          </div>
+        ))}
+      </div>
+      <button onClick={onRefresh} className="p-2 hover:bg-muted shrink-0">
+        <RotateCw className="w-3.5 h-3.5" />
+      </button>
+      <DropdownMenu>
+        <DropdownMenuTrigger className="p-2 hover:bg-muted shrink-0">
+          <ChevronDown className="w-3.5 h-3.5" />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem onClick={() => onCloseOther(activeTab)}>
+            关闭其他
+          </DropdownMenuItem>
+          <DropdownMenuItem onClick={() => onCloseAll()}>
+            关闭全部
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  );
+}
+```
+
+#### Toolbar adapter
+
+```tsx
+// ToolbarAdapter.tsx
+import { Button } from "@/components/ui/button";
+
+function ToolbarAdapter() {
+  return (
+    <div className="flex items-center gap-1 px-2">
+      <Button variant="ghost" size="icon" className="h-7 w-7">
+        <Search className="w-4 h-4" />
+      </Button>
+      <Button variant="ghost" size="icon" className="h-7 w-7">
+        <Bell className="w-4 h-4" />
+      </Button>
+      <Button variant="ghost" size="icon" className="h-7 w-7">
+        <Settings className="w-4 h-4" />
+      </Button>
+    </div>
+  );
+}
+```
+
+#### UserAvatar adapter
+
+```tsx
+// UserAvatarAdapter.tsx
+import type { UserAvatarAdapterProps } from "@tker-react/layout";
+import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+
+function UserAvatarAdapter({ onSettings, onLogout }: UserAvatarAdapterProps) {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger className="outline-none">
+        <Avatar className="h-7 w-7 cursor-pointer">
+          <AvatarImage src="/avatar.png" />
+          <AvatarFallback>U</AvatarFallback>
+        </Avatar>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-40">
+        <DropdownMenuItem onClick={onSettings}>
+          设置
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem onClick={onLogout}>
+          退出登录
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+```
+
+## 使用不同路由库
+
+以下展示 `SetupLayout` 组件中路由同步部分的写法。
+
+### TanStack Router
+
+```tsx
+// SetupLayout 中的路由同步部分
+const router = useRouter();
+const pathname = useRouterState({ select: (s) => s.location.pathname });
+const search = useRouterState({ select: (s) => s.location.searchStr });
+
+layout.setNavigateAdapter((path) => router.navigate({ to: path }));
+
+useLayoutEffect(() => {
+    layout.setActivePath(pathname, pathname + search);
+}, [pathname, search]);
+```
+
+### React Router v6+
+
+```tsx
+// SetupLayout 中的路由同步部分
+const location = useLocation();
+const navigate = useNavigate();
+
+layout.setNavigateAdapter((path) => navigate(path));
+
+useLayoutEffect(() => {
+    layout.setActivePath(location.pathname, location.pathname + location.search);
+}, [location.pathname, location.search]);
+```
+
+### Next.js App Router
+
+```tsx
+// SetupLayout 中的路由同步部分
+const pathname = usePathname();
+const searchParams = useSearchParams();
+const router = useRouter();
+
+layout.setNavigateAdapter((path) => router.push(path));
+
+const fullPath = pathname + (searchParams.toString() ? `?${searchParams}` : "");
+
+useLayoutEffect(() => {
+    layout.setActivePath(pathname, fullPath);
+}, [pathname, fullPath]);
+```
+
+## API
+
+### `useLayout()`
+
+| 方法 | 说明 |
+|------|------|
+| `setMenus(data)` | 设置菜单数据 |
+| `setActivePath(path, fullPath?)` | 设置当前激活路径，自动触发面包屑更新和标签页打开 |
+| `setMenuAdapter(component)` | 注册菜单适配器组件 |
+| `setTabAdapter(component)` | 注册标签页适配器组件 |
+| `setBreadcrumbAdapter(component)` | 注册面包屑适配器组件 |
+| `setLogoAdapter(component)` | 注册 Logo 适配器组件 |
+| `setToolbarAdapter(component)` | 注册工具栏适配器组件 |
+| `setUserAvatarAdapter(component)` | 注册用户头像适配器组件 |
+| `setNavigateAdapter(fn)` | 设置导航回调，Layout 内部点击菜单/tab/面包屑时调用 |
+| `toggleCollapse()` | 切换侧边栏折叠 |
+| `setLayoutMode(mode)` | 设置布局模式：`"side-menu"` 或 `"top-menu"` |
+| `setHomePath(path)` | 设置首页路径，首页 tab 固定在最左侧 |
+| `setMaxTabs(n)` | 设置最大标签页数量，超出后关闭最早的 |
+| `getFullPath(path)` | 根据菜单 path 获取存储的完整路径 |
+
+### Adapter 组件 Props
+
+| Adapter | Props |
+|---------|-------|
+| `menu` | `menuData`, `activePath`, `collapsed`, `mode` (`"side"|"top"`), `width`, `onSelect(path)` |
+| `tab` | `tabData`, `activeTab`, `onSelect(path)`, `onClose(path)`, `onCloseOther(path?)`, `onCloseAll()`, `onRefresh()`, `onSetFixed(path, fixed)` |
+| `breadcrumb` | `breadcrumbData`, `onSelect(path)` |
+| `logo` | `collapsed`, `width` |
+| `toolbar` | 无 props |
+| `userAvatar` | `onSettings?()`, `onLogout?()` |

package/dist/index.d.mts

@@ -0,0 +1,106 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
+
+interface LayoutProps {
+    children?: ReactNode;
+}
+declare function Layout({ children }: LayoutProps): react_jsx_runtime.JSX.Element;
+
+interface BreadcrumbItem {
+    path: string;
+    title: string;
+}
+
+interface MenuItem {
+    path: string;
+    title?: string;
+    label?: string;
+    name?: string;
+    icon?: ComponentType | string;
+    children?: MenuItem[];
+    [key: string]: any;
+}
+
+interface TabItem {
+    path: string;
+    title: string;
+    icon?: ComponentType | string;
+    fixed?: boolean;
+}
+
+interface LogoAdapterProps {
+    collapsed: boolean;
+    width: string;
+}
+interface MenuAdapterProps {
+    menuData: MenuItem[];
+    activePath: string;
+    collapsed: boolean;
+    mode: "side" | "top";
+    width: string;
+    onSelect: (path: string) => void;
+}
+interface BreadcrumbAdapterProps {
+    breadcrumbData: BreadcrumbItem[];
+    onSelect: (path: string) => void;
+}
+interface TabAdapterProps {
+    tabData: TabItem[];
+    activeTab: string;
+    onSelect: (path: string) => void;
+    onClose: (path: string) => void;
+    onCloseOther: (path?: string) => void;
+    onCloseAll: () => void;
+    onRefresh: () => void;
+    onSetFixed: (path: string, fixed: boolean) => void;
+}
+interface UserAvatarAdapterProps {
+    onSettings?: () => void;
+    onLogout?: () => void;
+}
+interface LayoutAdapters {
+    logo?: ComponentType<LogoAdapterProps>;
+    menu?: ComponentType<MenuAdapterProps>;
+    breadcrumb?: ComponentType<BreadcrumbAdapterProps>;
+    tab?: ComponentType<TabAdapterProps>;
+    toolbar?: ComponentType;
+    userAvatar?: ComponentType<UserAvatarAdapterProps>;
+}
+
+interface LayoutContextValue {
+    adapters: LayoutAdapters;
+    setMenuAdapter: (component: ComponentType<MenuAdapterProps>) => void;
+    setTabAdapter: (component: ComponentType<TabAdapterProps>) => void;
+    setBreadcrumbAdapter: (component: ComponentType<BreadcrumbAdapterProps>) => void;
+    setLogoAdapter: (component: ComponentType<LogoAdapterProps>) => void;
+    setToolbarAdapter: (component: ComponentType) => void;
+    setUserAvatarAdapter: (component: ComponentType<UserAvatarAdapterProps>) => void;
+    menuData: MenuItem[];
+    activePath: string;
+    collapsed: boolean;
+    expandedWidth: string;
+    collapsedWidth: string;
+    layoutMode: "side-menu" | "top-menu";
+    setMenus: (data: MenuItem[]) => void;
+    setActivePath: (path: string, fullPath?: string) => void;
+    toggleCollapse: () => void;
+    setCollapsed: (collapsed: boolean) => void;
+    setExpandedWidth: (width: string) => void;
+    setCollapsedWidth: (width: string) => void;
+    setLayoutMode: (mode: "side-menu" | "top-menu") => void;
+    isConcretePage: (path: string) => boolean;
+    getFullPath: (path: string) => string;
+    setNavigateAdapter: (fn: (path: string) => void) => void;
+    navigate: (path: string) => void;
+    homePath: string;
+    setHomePath: (path: string) => void;
+    maxTabs: number;
+    setMaxTabs: (max: number) => void;
+}
+declare function useLayoutContext(): LayoutContextValue;
+declare function LayoutProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+export { Layout, LayoutProvider, useLayoutContext as useLayout, useLayoutContext };
+export type { BreadcrumbAdapterProps, BreadcrumbItem, LayoutAdapters, LogoAdapterProps, MenuAdapterProps, MenuItem, TabAdapterProps, TabItem, UserAvatarAdapterProps };

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
+
+interface LayoutProps {
+    children?: ReactNode;
+}
+declare function Layout({ children }: LayoutProps): react_jsx_runtime.JSX.Element;
+
+interface BreadcrumbItem {
+    path: string;
+    title: string;
+}
+
+interface MenuItem {
+    path: string;
+    title?: string;
+    label?: string;
+    name?: string;
+    icon?: ComponentType | string;
+    children?: MenuItem[];
+    [key: string]: any;
+}
+
+interface TabItem {
+    path: string;
+    title: string;
+    icon?: ComponentType | string;
+    fixed?: boolean;
+}
+
+interface LogoAdapterProps {
+    collapsed: boolean;
+    width: string;
+}
+interface MenuAdapterProps {
+    menuData: MenuItem[];
+    activePath: string;
+    collapsed: boolean;
+    mode: "side" | "top";
+    width: string;
+    onSelect: (path: string) => void;
+}
+interface BreadcrumbAdapterProps {
+    breadcrumbData: BreadcrumbItem[];
+    onSelect: (path: string) => void;
+}
+interface TabAdapterProps {
+    tabData: TabItem[];
+    activeTab: string;
+    onSelect: (path: string) => void;
+    onClose: (path: string) => void;
+    onCloseOther: (path?: string) => void;
+    onCloseAll: () => void;
+    onRefresh: () => void;
+    onSetFixed: (path: string, fixed: boolean) => void;
+}
+interface UserAvatarAdapterProps {
+    onSettings?: () => void;
+    onLogout?: () => void;
+}
+interface LayoutAdapters {
+    logo?: ComponentType<LogoAdapterProps>;
+    menu?: ComponentType<MenuAdapterProps>;
+    breadcrumb?: ComponentType<BreadcrumbAdapterProps>;
+    tab?: ComponentType<TabAdapterProps>;
+    toolbar?: ComponentType;
+    userAvatar?: ComponentType<UserAvatarAdapterProps>;
+}
+
+interface LayoutContextValue {
+    adapters: LayoutAdapters;
+    setMenuAdapter: (component: ComponentType<MenuAdapterProps>) => void;
+    setTabAdapter: (component: ComponentType<TabAdapterProps>) => void;
+    setBreadcrumbAdapter: (component: ComponentType<BreadcrumbAdapterProps>) => void;
+    setLogoAdapter: (component: ComponentType<LogoAdapterProps>) => void;
+    setToolbarAdapter: (component: ComponentType) => void;
+    setUserAvatarAdapter: (component: ComponentType<UserAvatarAdapterProps>) => void;
+    menuData: MenuItem[];
+    activePath: string;
+    collapsed: boolean;
+    expandedWidth: string;
+    collapsedWidth: string;
+    layoutMode: "side-menu" | "top-menu";
+    setMenus: (data: MenuItem[]) => void;
+    setActivePath: (path: string, fullPath?: string) => void;
+    toggleCollapse: () => void;
+    setCollapsed: (collapsed: boolean) => void;
+    setExpandedWidth: (width: string) => void;
+    setCollapsedWidth: (width: string) => void;
+    setLayoutMode: (mode: "side-menu" | "top-menu") => void;
+    isConcretePage: (path: string) => boolean;
+    getFullPath: (path: string) => string;
+    setNavigateAdapter: (fn: (path: string) => void) => void;
+    navigate: (path: string) => void;
+    homePath: string;
+    setHomePath: (path: string) => void;
+    maxTabs: number;
+    setMaxTabs: (max: number) => void;
+}
+declare function useLayoutContext(): LayoutContextValue;
+declare function LayoutProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+export { Layout, LayoutProvider, useLayoutContext as useLayout, useLayoutContext };
+export type { BreadcrumbAdapterProps, BreadcrumbItem, LayoutAdapters, LogoAdapterProps, MenuAdapterProps, MenuItem, TabAdapterProps, TabItem, UserAvatarAdapterProps };

package/dist/index.mjs

@@ -0,0 +1,492 @@
+import "./layout.css";
+import { createContext, useContext, useRef, useCallback, useState, useMemo, useEffect } from 'react';
+
+function findMenuItemByPath(menuData, path) {
+  for (const item of menuData) {
+    if (item.path === path) {
+      return item;
+    }
+    if (item.children) {
+      const found = findMenuItemByPath(item.children, path);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+function getParentChain(menuData, path) {
+  const chain = [];
+  function traverse(items, target, ancestors) {
+    for (const item of items) {
+      if (item.path === target) {
+        chain.push(...ancestors, item);
+        return true;
+      }
+      if (item.children && traverse(item.children, target, [...ancestors, item])) {
+        return true;
+      }
+    }
+    return false;
+  }
+  traverse(menuData, path, []);
+  return chain;
+}
+function getMenuItemTitle(item) {
+  return item.title || item.label || item.name || item.path;
+}
+
+function generateBreadcrumb(menuData, activePath) {
+  const chain = getParentChain(menuData, activePath);
+  return chain.map((item) => ({
+    path: item.path,
+    title: getMenuItemTitle(item)
+  }));
+}
+
+const LayoutContext = createContext(null);
+function useLayoutContext() {
+  const ctx = useContext(LayoutContext);
+  if (!ctx) {
+    throw new Error("useLayoutContext \u5FC5\u987B\u5728 <Layout> \u5185\u90E8\u4F7F\u7528");
+  }
+  return ctx;
+}
+function LayoutProvider({ children }) {
+  const navigateRef = useRef(null);
+  const setNavigateAdapter = useCallback(
+    (fn) => {
+      navigateRef.current = fn;
+    },
+    []
+  );
+  const navigate = useCallback(
+    (path) => {
+      navigateRef.current?.(path);
+    },
+    []
+  );
+  const [adapters, setAdapters] = useState({});
+  const setMenuAdapter = useCallback(
+    (c) => setAdapters((prev) => prev.menu === c ? prev : { ...prev, menu: c }),
+    []
+  );
+  const setTabAdapter = useCallback(
+    (c) => setAdapters((prev) => prev.tab === c ? prev : { ...prev, tab: c }),
+    []
+  );
+  const setBreadcrumbAdapter = useCallback(
+    (c) => setAdapters((prev) => prev.breadcrumb === c ? prev : { ...prev, breadcrumb: c }),
+    []
+  );
+  const setLogoAdapter = useCallback(
+    (c) => setAdapters((prev) => prev.logo === c ? prev : { ...prev, logo: c }),
+    []
+  );
+  const setToolbarAdapter = useCallback(
+    (c) => setAdapters((prev) => prev.toolbar === c ? prev : { ...prev, toolbar: c }),
+    []
+  );
+  const setUserAvatarAdapter = useCallback(
+    (c) => setAdapters((prev) => prev.userAvatar === c ? prev : { ...prev, userAvatar: c }),
+    []
+  );
+  const [menuData, setMenuData] = useState([]);
+  const [activePath, setActivePathState] = useState("");
+  const [collapsed, setCollapsedState] = useState(false);
+  const [expandedWidth, setExpandedWidth] = useState("200px");
+  const [collapsedWidth, setCollapsedWidth] = useState("64px");
+  const [layoutMode, setLayoutMode] = useState(
+    "side-menu"
+  );
+  const setMenus = useCallback((data) => setMenuData(data), []);
+  const toggleCollapse = useCallback(
+    () => setCollapsedState((p) => !p),
+    []
+  );
+  const pathParamsMap = useRef(/* @__PURE__ */ new Map());
+  const storePathParams = useCallback((path, fullPath) => {
+    if (fullPath && fullPath !== path) {
+      pathParamsMap.current.set(path, fullPath);
+    }
+  }, []);
+  const getFullPath = useCallback(
+    (path) => pathParamsMap.current.get(path) || path,
+    []
+  );
+  const setActivePath = useCallback(
+    (path, fullPath) => {
+      setActivePathState(path);
+      if (fullPath) storePathParams(path, fullPath);
+    },
+    [storePathParams]
+  );
+  const isConcretePage = useCallback(
+    (path) => {
+      const item = findMenuItemByPath(menuData, path);
+      return !item?.children || item.children.length === 0;
+    },
+    [menuData]
+  );
+  const [homePath, setHomePathState] = useState("");
+  const [maxTabs, setMaxTabsState] = useState(10);
+  const setHomePath = useCallback((path) => {
+    setHomePathState(path);
+  }, []);
+  const setMaxTabs = useCallback((max) => {
+    setMaxTabsState(max);
+  }, []);
+  const value = useMemo(
+    () => ({
+      adapters,
+      setMenuAdapter,
+      setTabAdapter,
+      setBreadcrumbAdapter,
+      setLogoAdapter,
+      setToolbarAdapter,
+      setUserAvatarAdapter,
+      menuData,
+      activePath,
+      collapsed,
+      expandedWidth,
+      collapsedWidth,
+      layoutMode,
+      setMenus,
+      setActivePath,
+      toggleCollapse,
+      setCollapsed: setCollapsedState,
+      setExpandedWidth,
+      setCollapsedWidth,
+      setLayoutMode,
+      isConcretePage,
+      getFullPath,
+      setNavigateAdapter,
+      navigate,
+      homePath,
+      setHomePath,
+      maxTabs,
+      setMaxTabs
+    }),
+    [
+      adapters,
+      setMenuAdapter,
+      setTabAdapter,
+      setBreadcrumbAdapter,
+      setLogoAdapter,
+      setToolbarAdapter,
+      setUserAvatarAdapter,
+      menuData,
+      activePath,
+      collapsed,
+      expandedWidth,
+      collapsedWidth,
+      layoutMode,
+      setMenus,
+      setActivePath,
+      toggleCollapse,
+      isConcretePage,
+      getFullPath,
+      setNavigateAdapter,
+      navigate,
+      homePath,
+      setHomePath,
+      maxTabs,
+      setMaxTabs
+    ]
+  );
+  return /* @__PURE__ */ React.createElement(LayoutContext.Provider, { value }, children);
+}
+
+function LayoutAside() {
+  const {
+    adapters,
+    collapsed,
+    expandedWidth,
+    collapsedWidth,
+    menuData,
+    activePath,
+    layoutMode,
+    getFullPath,
+    navigate,
+    toggleCollapse
+  } = useLayoutContext();
+  const menuMode = layoutMode === "top-menu" ? "top" : "side";
+  const handleMenuSelect = useCallback(
+    (path) => {
+      const fullPath = getFullPath(path);
+      if (window.location.pathname + window.location.search === fullPath) return;
+      navigate(fullPath);
+    },
+    [getFullPath, navigate]
+  );
+  const MenuAdapter = adapters.menu;
+  if (!MenuAdapter) return null;
+  const asideWidth = collapsed ? collapsedWidth : expandedWidth;
+  return /* @__PURE__ */ React.createElement("aside", { className: "tker-layout-aside", style: { width: asideWidth } }, /* @__PURE__ */ React.createElement(
+    MenuAdapter,
+    {
+      menuData,
+      activePath,
+      collapsed,
+      mode: menuMode,
+      width: asideWidth,
+      onSelect: handleMenuSelect
+    }
+  ), /* @__PURE__ */ React.createElement(
+    "div",
+    {
+      className: "tker-layout-aside__toggle-btn",
+      onClick: toggleCollapse
+    },
+    collapsed ? /* @__PURE__ */ React.createElement("svg", { viewBox: "0 0 16 16", fill: "none", width: "16", height: "16" }, /* @__PURE__ */ React.createElement(
+      "path",
+      {
+        d: "M5.64645 3.14645C5.45118 3.34171 5.45118 3.65829 5.64645 3.85355L9.79289 8L5.64645 12.1464C5.45118 12.3417 5.45118 12.6583 5.64645 12.8536C5.84171 13.0488 6.15829 13.0488 6.35355 12.8536L10.8536 8.35355C11.0488 8.15829 11.0488 7.84171 10.8536 7.64645L6.35355 3.14645C6.15829 2.95118 5.84171 2.95118 5.64645 3.14645Z",
+        fill: "currentColor"
+      }
+    )) : /* @__PURE__ */ React.createElement("svg", { viewBox: "0 0 16 16", fill: "none", width: "16", height: "16" }, /* @__PURE__ */ React.createElement(
+      "path",
+      {
+        d: "M10.3536 3.14645C10.5488 3.34171 10.5488 3.65829 10.3536 3.85355L6.20711 8L10.3536 12.1464C10.5488 12.3417 10.5488 12.6583 10.3536 12.8536C10.1583 13.0488 9.84171 13.0488 9.64645 12.8536L5.14645 8.35355C4.95118 8.15829 4.95118 7.84171 5.14645 7.64645L9.64645 3.14645C9.84171 2.95118 10.1583 2.95118 10.3536 3.14645Z",
+        fill: "currentColor"
+      }
+    ))
+  ));
+}
+
+function LayoutContent({ children }) {
+  const {
+    adapters,
+    menuData,
+    activePath,
+    layoutMode,
+    homePath,
+    maxTabs,
+    getFullPath,
+    navigate
+  } = useLayoutContext();
+  const isTopMenu = layoutMode === "top-menu";
+  const [tabData, setTabData] = useState([]);
+  const [activeTab, setActiveTab] = useState("");
+  const [refreshKey, setRefreshKey] = useState(0);
+  const menuDataRef = useRef(menuData);
+  menuDataRef.current = menuData;
+  const activeTabRef = useRef(activeTab);
+  activeTabRef.current = activeTab;
+  useEffect(() => {
+    if (!activePath || activePath === "/") return;
+    setTabData((prev) => {
+      const exists = prev.find((t) => t.path === activePath);
+      if (exists) {
+        setActiveTab(activePath);
+        return prev;
+      }
+      return openTabInData(prev, activePath, {
+        homePath,
+        maxTabs,
+        menuData: menuDataRef.current
+      });
+    });
+    setActiveTab(activePath);
+  }, [activePath, homePath, maxTabs]);
+  const handleTabSelect = useCallback(
+    (path) => {
+      const fullPath = getFullPath(path);
+      if (window.location.pathname + window.location.search === fullPath) return;
+      navigate(fullPath);
+    },
+    [getFullPath, navigate]
+  );
+  const handleTabClose = useCallback(
+    (path) => {
+      setTabData((prev) => {
+        const tab = prev.find((t) => t.path === path);
+        if (tab?.fixed) return prev;
+        const idx = prev.findIndex((t) => t.path === path);
+        if (idx === -1) return prev;
+        const next = [...prev];
+        next.splice(idx, 1);
+        if (activeTabRef.current === path) {
+          const last = next[next.length - 1];
+          if (last) {
+            setActiveTab(last.path);
+            navigate(getFullPath(last.path));
+          } else if (homePath) {
+            setActiveTab(homePath);
+            navigate(homePath);
+          } else {
+            setActiveTab("");
+          }
+        }
+        return next;
+      });
+    },
+    [getFullPath, navigate, homePath]
+  );
+  const handleCloseOtherTabs = useCallback(
+    (path) => {
+      setTabData((prev) => {
+        const target = path || activeTabRef.current;
+        const filtered = prev.filter((t) => t.path === target || t.fixed);
+        setActiveTab(target);
+        return filtered;
+      });
+    },
+    []
+  );
+  const handleCloseAllTabs = useCallback(() => {
+    setTabData((prev) => {
+      const fixed = prev.filter((t) => t.fixed);
+      const first = fixed[0];
+      if (first) {
+        setActiveTab(first.path);
+        navigate(getFullPath(first.path));
+      } else {
+        setActiveTab("");
+      }
+      return fixed;
+    });
+  }, [getFullPath, navigate]);
+  const handleSetFixed = useCallback((path, fixed) => {
+    setTabData(
+      (prev) => prev.map((t) => t.path === path ? { ...t, fixed } : t)
+    );
+  }, []);
+  const handleRefresh = useCallback(() => {
+    setRefreshKey((k) => k + 1);
+  }, []);
+  const TabAdapter = adapters.tab;
+  return /* @__PURE__ */ React.createElement("main", { className: "tker-layout-content" }, !isTopMenu && TabAdapter && /* @__PURE__ */ React.createElement(
+    TabAdapter,
+    {
+      tabData,
+      activeTab,
+      onSelect: handleTabSelect,
+      onClose: handleTabClose,
+      onCloseOther: handleCloseOtherTabs,
+      onCloseAll: handleCloseAllTabs,
+      onRefresh: handleRefresh,
+      onSetFixed: handleSetFixed
+    }
+  ), /* @__PURE__ */ React.createElement("div", { className: "tker-layout-content__body", key: refreshKey }, children));
+}
+function openTabInData(tabData, path, config) {
+  const { homePath, maxTabs, menuData } = config;
+  const next = [...tabData];
+  if (homePath) {
+    const homeIdx = next.findIndex((t) => t.path === homePath);
+    if (homeIdx === -1) {
+      const homeMenuItem = findMenuItemByPath(menuData, homePath);
+      const homeTitle = homeMenuItem ? homeMenuItem.title || homePath : "\u9996\u9875";
+      next.unshift({
+        path: homePath,
+        title: homeTitle,
+        icon: homeMenuItem?.icon,
+        fixed: true
+      });
+    } else if (homeIdx > 0) {
+      const [homeTab] = next.splice(homeIdx, 1);
+      next.unshift(homeTab);
+    }
+  }
+  const exists = next.find((t) => t.path === path);
+  if (exists) return next;
+  const menuItem = findMenuItemByPath(menuData, path);
+  const title = menuItem ? menuItem.title || menuItem.label || menuItem.name || path : path;
+  const icon = menuItem?.icon;
+  const isHome = path === homePath;
+  if (!isHome) {
+    const nonFixed = next.filter((t) => !t.fixed);
+    if (nonFixed.length >= maxTabs) {
+      const oldest = nonFixed[0];
+      if (oldest) {
+        const oldestIdx = next.findIndex((t) => t.path === oldest.path);
+        next.splice(oldestIdx, 1);
+      }
+    }
+  }
+  if (isHome) {
+    next.unshift({ path, title, icon, fixed: true });
+  } else {
+    next.push({ path, title, icon, fixed: false });
+  }
+  return next;
+}
+
+function LayoutHeader() {
+  const {
+    adapters,
+    collapsed,
+    expandedWidth,
+    collapsedWidth,
+    menuData,
+    activePath,
+    layoutMode,
+    getFullPath,
+    isConcretePage,
+    navigate
+  } = useLayoutContext();
+  const isTopMenu = layoutMode === "top-menu";
+  const isSideMenu = layoutMode === "side-menu";
+  const breadcrumbData = useMemo(
+    () => generateBreadcrumb(menuData, activePath),
+    [menuData, activePath]
+  );
+  const handleMenuSelect = useCallback(
+    (path) => {
+      const fullPath = getFullPath(path);
+      if (window.location.pathname + window.location.search === fullPath) return;
+      navigate(fullPath);
+    },
+    [getFullPath, navigate]
+  );
+  const handleBreadcrumbSelect = useCallback(
+    (path) => {
+      if (!isConcretePage(path)) return;
+      const fullPath = getFullPath(path);
+      if (window.location.pathname + window.location.search === fullPath) return;
+      navigate(fullPath);
+    },
+    [getFullPath, navigate, isConcretePage]
+  );
+  const leftContent = isTopMenu ? ["logo", "menu"] : ["logo", "breadcrumb"];
+  const logoWidth = isSideMenu ? collapsed ? collapsedWidth : expandedWidth : expandedWidth;
+  const LogoAdapter = adapters.logo;
+  const MenuAdapter = adapters.menu;
+  const BreadcrumbAdapter = adapters.breadcrumb;
+  const ToolbarAdapter = adapters.toolbar;
+  const UserAvatarAdapter = adapters.userAvatar;
+  return /* @__PURE__ */ React.createElement("header", { className: "tker-layout-header" }, /* @__PURE__ */ React.createElement("div", { className: "tker-layout-header__left" }, LogoAdapter && leftContent.includes("logo") && /* @__PURE__ */ React.createElement(
+    "div",
+    {
+      className: "tker-layout-header__left-logo",
+      style: { width: logoWidth }
+    },
+    /* @__PURE__ */ React.createElement(LogoAdapter, { collapsed, width: logoWidth })
+  ), MenuAdapter && isTopMenu && /* @__PURE__ */ React.createElement(
+    MenuAdapter,
+    {
+      menuData,
+      activePath,
+      collapsed: false,
+      mode: "top",
+      width: logoWidth,
+      onSelect: handleMenuSelect
+    }
+  ), BreadcrumbAdapter && isSideMenu && /* @__PURE__ */ React.createElement(
+    BreadcrumbAdapter,
+    {
+      breadcrumbData,
+      onSelect: handleBreadcrumbSelect
+    }
+  )), /* @__PURE__ */ React.createElement("div", { className: "tker-layout-header__right" }, ToolbarAdapter && /* @__PURE__ */ React.createElement(ToolbarAdapter, null), UserAvatarAdapter && /* @__PURE__ */ React.createElement(UserAvatarAdapter, null)));
+}
+
+function LayoutInner({ children }) {
+  const { layoutMode } = useLayoutContext();
+  const isSideMenu = layoutMode === "side-menu";
+  return /* @__PURE__ */ React.createElement("div", { className: "tker-layout" }, /* @__PURE__ */ React.createElement(LayoutHeader, null), /* @__PURE__ */ React.createElement("div", { className: "tker-layout__body" }, isSideMenu && /* @__PURE__ */ React.createElement(LayoutAside, null), /* @__PURE__ */ React.createElement(LayoutContent, null, children)));
+}
+function Layout({ children }) {
+  return /* @__PURE__ */ React.createElement(LayoutProvider, null, /* @__PURE__ */ React.createElement(LayoutInner, null, children));
+}
+
+export { Layout, LayoutProvider, useLayoutContext as useLayout, useLayoutContext };

package/dist/layout.css

@@ -0,0 +1,93 @@
+.tker-layout {
+    display: flex;
+    flex-direction: column;
+    height: 100vh;
+    width: 100%;
+    overflow: hidden;
+}
+
+.tker-layout__body {
+    display: flex;
+    flex: 1;
+    overflow: hidden;
+    min-height: 0;
+}
+
+/* === Header === */
+
+.tker-layout-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    height: 48px;
+    background: #fff;
+    border-bottom: 1px solid #e8e8e8;
+    flex-shrink: 0;
+}
+
+.tker-layout-header__left,
+.tker-layout-header__right {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+}
+
+.tker-layout-header__left-logo {
+    border-right: 1px solid #e8e8e8;
+}
+
+/* === Aside === */
+
+.tker-layout-aside {
+    flex-shrink: 0;
+    height: 100%;
+    background: #fff;
+    border-right: 1px solid #e8e8e8;
+    transition: width 0.3s;
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+}
+
+.tker-layout-aside__toggle-btn {
+    cursor: pointer;
+    width: 24px;
+    height: 24px;
+    position: absolute;
+    top: 50%;
+    right: -12px;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 18px;
+    color: #333;
+    border: 1px solid #e8e8e8;
+    background-color: #fff;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.06);
+    transform: translateY(-50%);
+    z-index: 100;
+    transition: all 0.3s;
+}
+
+.tker-layout-aside__toggle-btn:hover {
+    color: #18a058;
+    border-color: #18a058;
+}
+
+/* === Content === */
+
+.tker-layout-content {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    background: rgb(250, 250, 252);
+}
+
+.tker-layout-content__body {
+    flex: 1;
+    padding: 8px;
+    overflow: auto;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@tker-react/layout",
+    "version": "0.2.0",
+    "private": false,
+    "license": "MIT",
+    "type": "module",
+    "scripts": {
+        "build": "pnpm unbuild"
+    },
+    "files": [
+        "dist"
+    ],
+    "sideEffects": [
+        "**/*.css"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "development": "./src/index.ts",
+            "default": "./dist/index.mjs"
+        },
+        "./layout.css": {
+            "development": "./src/styles/layout.css",
+            "default": "./dist/layout.css"
+        }
+    },
+    "publishConfig": {
+        "access": "public",
+        "exports": {
+            ".": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.mjs"
+            },
+            "./layout.css": {
+                "default": "./dist/layout.css"
+            }
+        }
+    },
+    "peerDependencies": {
+        "react": ">=18",
+        "react-dom": ">=18"
+    },
+    "devDependencies": {
+        "@tker-react/tsconfig": "workspace:*",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+    }
+}