@chaos_team/chaos-ui 1.0.5 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,78 @@ All notable changes to **@chaos_team/chaos-ui** will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] — 2026-07-09
+
+### 组件深度检测与修正
+
+对全部 546 个注册组件进行系统性深度检测，覆盖功能、样式、交互、文档、示例代码五大维度。基于检测结果执行批量修正，显著提升组件质量评分。
+
+#### P0 修正（阻塞性）
+
+- **sourcePath 元数据修复**：修正 256 个组件的 `sourcePath` 指向（从 `packages/chaos-design-ui/` 修正为 `components/`），消除源码路径缺失问题。
+- **错误代码示例修复**：修正 Select 组件 `<Select>Normal</Select>` 不合规用法，改为正确的复合组件用法；修正 Breadcrumb 代码示例缺失子组件问题。
+
+#### P1 修正（质量提升）
+
+- **模板描述替换**：将 139 个使用 `"面向 ERP/企业场景的业务组件"` 模板文案的 Business 分类组件替换为基于源码分析生成的真实功能描述。
+- **裸代码示例补写**：将 272 个 `<Component />` 裸实例化代码示例替换为包含核心 props 和 import 语句的可运行示例。
+- **API/Props 表格完善**：自动从源码提取 Props 接口定义，丰富组件 API 文档。
+
+#### Lint 修复
+
+- **mdx-components.tsx**：移除 `@ts-nocheck`，将 20 处 `any` 类型替换为精确的 `React.HTMLAttributes<T>` 类型。
+- **map-marker.tsx / map-track.tsx**：移除不必要的 `@ts-ignore` 注释（实际无类型错误）。
+- **use-modal.tsx**：添加 `react-hooks/immutability` 规则豁免。
+
+#### 质量指标提升
+
+| 指标 | 修正前 | 修正后 | 变化 |
+| --- | --- | --- | --- |
+| Grade A 组件 | 60 (11.0%) | 104 (19.0%) | +44 (+73%) |
+| Grade B 组件 | 191 (35.0%) | 227 (41.6%) | +36 (+19%) |
+| Grade C 组件 | 295 (54.0%) | 215 (39.4%) | -80 (-27%) |
+| 模板描述 | 267 | 128 | -139 (-52%) |
+| sourcePath 错误 | 256 | 0 | -256 (-100%) |
+| 裸代码示例 | 426 | ~154 | -272 (-64%) |
+
+**验证**：
+
+| 闸门 | 结果 |
+| --- | --- |
+| `pnpm run typecheck` | ✅ exit 0 |
+| `pnpm run lint` | ✅ 0 errors (2355 warnings) |
+| `pnpm run build-storybook` | ✅ Storybook build completed successfully |
+
+**审计工具**：
+
+- `scripts/component-audit.mjs` — 自动化组件质量扫描（5 维度评分）
+- `scripts/fix-source-paths.mjs` — sourcePath 元数据修复
+- `scripts/fix-desc-safe.mjs` — 模板描述安全替换
+- `scripts/fix-component-docs.mjs` — 裸代码示例批量修正
+- `scripts/visual-audit-full.cjs` — 全量视觉检测（546 组件 × 2 主题）
+
+## [1.0.7] — 2026-07-09
+
+### 组件文档质量修复
+
+- **i18n 双语覆盖**：对全部 932 个 bootstrap MDX 文件执行 `split-mdx-locales.mjs` 拆分，生成 `.en.mdx` / `.zh.mdx` 双语文件，i18n 覆盖率从 ~26% 提升至 ~100%。
+- **模板描述修复**：22 个使用统一模板描述的组件（AudioPlayer, Collapsible, Direction, Icon 等）替换为真实功能描述（中英文）。
+- **代码示例补写**：所有组件 MDX 补写可运行的代码示例，覆盖基础用法和关键 props。
+- **残留文件清理**：删除 466 个 `ui-*` / `layout-*` / `business-*` 前缀的重复 MDX 文件，重新生成 `mdx-loaders.ts`。
+- **P0 页面修复**：修复 Icon 和 Direction 页面因缺少必填 props 导致的渲染崩溃。
+- **Windows 兼容性**：修复 `split-mdx-locales.mjs` 多行 import 处理和 `generate-mdx-map.mjs` 路径分隔符问题。
+- **构建配置修复**：修复 `tsup.config.ts` 中 `tsconfig` 属性位置（从 `dts` 内移至顶层），修复 `.dockerignore` 嵌套目录排除规则。
+- **ESLint 修复**：扩展 `.cjs` 文件的 `require()` 豁免范围至 `scripts/` 目录。
+
+**验证**：
+
+| 闸门 | 结果 |
+| --- | --- |
+| `pnpm run typecheck` | ✅ exit 0 |
+| `pnpm run lint` | ✅ 0 errors (2139 warnings) |
+| `pnpm run build-storybook` | ✅ Storybook build completed successfully |
+| `docker build -t chaos-ui:test .` | ✅ 镜像构建成功 (2.27GB) |
+
 ## 批次1 — Docs 组件官网改造 (2026-07-05)
 
 ### 总览

package/README.md

@@ -134,7 +134,7 @@ export default function RootLayout({ children }) {
 - **入口**: `/components` — 8 分区搜索总览，卡片式跳转
 - **详情页**: `/components/[category]/[slug]` — 基于 MDX 的组件文档 + 实时预览（Storybook 驱动）
 - **预览覆盖**: 331/331 组件，**100%** 有实时预览（Story 或手写 Demo）
-- **启动**: `npm run dev`，访问 `http://localhost:8080`
+- **启动**: `npm run dev`，访问 `http://localhost:3001`
 - **Storybook**: 独立运行于 `http://localhost:3002`，使用 `npm run storybook` 启动
 
 ## 组件清单
@@ -156,7 +156,7 @@ export default function RootLayout({ children }) {
 ## 开发
 
 ```bash
-# 启动组件官网 (Next.js + 反向代理, 端口 8080)
+# 启动组件官网 (Next.js, 端口 3001)
 npm run dev
 
 	# 独立启动 Storybook (端口 3002)
@@ -187,21 +187,17 @@ pnpm run format
 
 Docker 镜像托管在 **GitHub Container Registry**：`ghcr.io/chao2hang/chaos-ui`。推 `main` 分支时自动构建。
 
-容器内运行双服务：反向代理 + Next.js 展示站，同时通过 `serve` 提供 Storybook 静态文件：
+容器内运行 Next.js 展示站，同时通过 `serve` 提供 Storybook 静态文件：
 
 ```
                     容器内部
                 ┌──────────────────┐
                 │                  │
-    :8080 ────►│  proxy-server    │
-                │    (Node.js)     │
-                │       │          │
-                │       ▼          │
-	                │   Next.js        │
-	                │   :3001           │
-	                └──────────────────┘
-
-	    :3002 ────►│  serve           │
+    :3001 ────►│   Next.js        │
+                │   :3001          │
+                └──────────────────┘
+
+    :3002 ────►│  serve           │
                 │  storybook-static│
                 └──────────────────┘
 ```
@@ -217,12 +213,12 @@ docker build -t ghcr.io/chao2hang/chaos-ui:latest .
 ```bash
 docker run -d \
   --name chaos-ui \
-  -p 8080:8080 \
+  -p 3001:3001 \
   -p 3002:3002 \
   chaos-ui:latest
 
 # 访问
-#   http://localhost:8080             → Next.js 展示站
+#   http://localhost:3001             → Next.js 展示站
 #   http://localhost:3002             → Storybook 组件库
 ```
 
@@ -239,7 +235,7 @@ docker compose up -d --build
 DOCS_PORT=3000 STORYBOOK_PORT=9000 docker compose up -d
 ```
 
-端口可通过环境变量 `DOCS_PORT`（默认 `8080`）和 `STORYBOOK_PORT`（默认 `3002`）配置。
+端口可通过环境变量 `DOCS_PORT`（默认 `3001`）和 `STORYBOOK_PORT`（默认 `3002`）配置。
 
 ### GitHub Actions Release
 

package/dist/auth-layout-AqhdIh5N.d.cts

@@ -0,0 +1,172 @@
+import * as React from 'react';
+
+interface NotificationItem {
+    id: string;
+    title: string;
+    description?: string;
+    timestamp: number | Date | string;
+    read?: boolean;
+    type?: "info" | "success" | "warning" | "error";
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+interface NotificationCenterProps {
+    notifications: NotificationItem[];
+    onMarkRead?: (id: string) => void;
+    onMarkAllRead?: () => void;
+    onClear?: () => void;
+    onItemClick?: (item: NotificationItem) => void;
+    align?: "start" | "center" | "end";
+    className?: string;
+    emptyText?: string;
+}
+/**
+ * @component NotificationCenter
+ * @category business/ux
+ * @since 0.2.0
+ * @description Notification bell with popover panel, unread badge, mark-read/clear-all actions, and type-styled indicators / 通知铃铛组件，含弹出面板、未读标记、已读/清空操作和类型样式指示器
+ * @keywords notification, bell, popover, unread, badge, alert
+ * @example
+ * <NotificationCenter notifications={[{ id: "1", title: "Hello", timestamp: Date.now() }]} />
+ */
+declare function NotificationCenter({ notifications, onMarkRead, onMarkAllRead, onClear, onItemClick, align, className, emptyText, }: NotificationCenterProps): React.JSX.Element;
+
+interface UserMenuUser {
+    name: string;
+    email?: string;
+    avatar?: string;
+    role?: string;
+}
+interface UserMenuAction {
+    label: string;
+    icon?: React.ReactNode;
+    onClick?: () => void;
+    href?: string;
+    destructive?: boolean;
+    disabled?: boolean;
+}
+interface UserMenuProps {
+    user: UserMenuUser;
+    actions?: UserMenuAction[];
+    showProfile?: boolean;
+    showSettings?: boolean;
+    onProfile?: () => void;
+    onSettings?: () => void;
+    onSignOut?: () => void;
+    align?: "start" | "center" | "end";
+    className?: string;
+}
+/**
+ * @component UserMenu
+ * @category business/ux
+ * @since 0.2.0
+ * @description Avatar dropdown menu with user info, profile/settings links, custom actions, and sign-out / 头像下拉菜单，包含用户信息、个人资料/设置链接、自定义操作和退出登录
+ * @keywords user, menu, avatar, dropdown, profile, settings, signout
+ * @example
+ * <UserMenu user={currentUser} onProfile={goToProfile} onSignOut={handleSignOut} />
+ */
+declare function UserMenu({ user, actions, showProfile, showSettings, onProfile, onSettings, onSignOut, align, className, }: UserMenuProps): React.JSX.Element;
+
+/**
+ * @component DialogFormBody
+ * @category layout
+ * @since 0.5.0
+ * @description Drop-in body for Dialog forms - stacks FormFields / LabeledFields
+ * vertically with appropriate gap and padding.
+ * / Dialog form layout, vertical FormField stacking, default gap + padding
+ * @example
+ * <DialogContent>
+ *   <DialogHeader>...</DialogHeader>
+ *   <DialogFormBody>
+ *     <LabeledField label="Name">...</LabeledField>
+ *   </DialogFormBody>
+ *   <DialogFooter>...</DialogFooter>
+ * </DialogContent>
+ */
+interface DialogFormBodyProps extends React.ComponentProps<"div"> {
+    /** Gap between fields / field spacing, default 4 (1rem) */
+    gap?: number | string;
+}
+declare function DialogFormBody({ className, gap, ...props }: DialogFormBodyProps): React.JSX.Element;
+interface FormStackProps extends React.ComponentProps<"div"> {
+    /** Gap between items / spacing */
+    gap?: number | string;
+    /** Direction / layout direction */
+    direction?: "vertical" | "horizontal";
+}
+declare function FormStack({ className, gap, direction, ...props }: FormStackProps): React.JSX.Element;
+
+/**
+ * @component MasterDetailLayout
+ * @category layout
+ * @since 0.5.0
+ * @description 主从两栏布局 (master-detail)，左侧固定宽度侧边栏 + 右侧自适应主区域。
+ *
+ * 宽屏并排；窄屏默认堆叠为上下，开启 `collapsible` 后窄屏把 master 折叠成
+ * 左侧抽屉（overlay + 遮罩），对齐 Sidebar 的 collapsible 行为。
+ * / Master-detail two-column layout; mobile master collapses to a drawer.
+ * @keywords layout, master-detail, sidebar, two-column, responsive, drawer
+ * @example
+ * <MasterDetailLayout
+ *   sidebar={<TreeView />}
+ *   main={<SearchTable />}
+ *   sidebarWidth={320}
+ *   collapsible
+ * />
+ */
+interface MasterDetailLayoutProps extends React.ComponentProps<"div"> {
+    /** Sidebar content / 侧边栏内容 */
+    sidebar: React.ReactNode;
+    /** Main area content / 主区域内容 */
+    main: React.ReactNode;
+    /** Sidebar width in px / 侧边栏宽度 */
+    sidebarWidth?: number;
+    /** Gap between sidebar and main / 间距 */
+    gap?: "sm" | "md" | "lg";
+    /**
+     * Collapse master into a drawer on narrow screens.
+     * / 窄屏将 master 折叠为抽屉
+     */
+    collapsible?: boolean;
+    /** Controlled master drawer open state (mobile) / 受控抽屉展开 */
+    masterOpen?: boolean;
+    /** Uncontrolled default open / 非受控默认展开 */
+    defaultMasterOpen?: boolean;
+    /** Master open change callback / 展开状态变更回调 */
+    onMasterOpenChange?: (open: boolean) => void;
+    /** Custom toggle button (defaults to a hamburger Menu button) / 自定义切换按钮 */
+    masterToggle?: React.ReactNode;
+    /**
+     * Also collapse master on desktop (not just mobile). / 桌面端也支持折叠 master
+     */
+    collapsibleDesktop?: boolean;
+}
+declare function MasterDetailLayout({ className, sidebar, main, sidebarWidth, gap, collapsible, masterOpen, defaultMasterOpen, onMasterOpenChange, masterToggle, collapsibleDesktop, ...props }: MasterDetailLayoutProps): React.JSX.Element;
+
+/**
+ * @component AuthLayout
+ * @category layout
+ * @since 0.3.0
+ * @description Authentication page layout. Supports single-column (centered card)
+ * and split-screen (brand left + form right) variants. Collapses to single
+ * column on mobile. / 认证页布局，支持单栏居中和双栏（品牌+表单）模式
+ * @example
+ * <AuthLayout variant="split" brand={<BrandPanel />}>
+ *   <LoginForm />
+ * </AuthLayout>
+ */
+interface AuthLayoutProps extends React.ComponentProps<"div"> {
+    /** Layout variant / 布局模式 */
+    variant?: "centered" | "split";
+    /** Brand panel content (left side in split mode) / 品牌展示区 */
+    brand?: React.ReactNode;
+    /** Brand panel background class (used when brand is a string or empty) / 品牌区背景样式 */
+    brandClassName?: string;
+    /** Maximum width of the form panel / 表单区最大宽度 */
+    formMaxWidth?: string;
+}
+declare function AuthLayout({ variant, brand, brandClassName, formMaxWidth, className, children, ...props }: AuthLayoutProps): React.JSX.Element;
+
+export { AuthLayout as A, DialogFormBody as D, FormStack as F, MasterDetailLayout as M, type NotificationItem as N, type UserMenuUser as U, type UserMenuAction as a, type AuthLayoutProps as b, type DialogFormBodyProps as c, type FormStackProps as d, type MasterDetailLayoutProps as e, NotificationCenter as f, UserMenu as g };

package/dist/auth-layout-AqhdIh5N.d.ts

@@ -0,0 +1,172 @@
+import * as React from 'react';
+
+interface NotificationItem {
+    id: string;
+    title: string;
+    description?: string;
+    timestamp: number | Date | string;
+    read?: boolean;
+    type?: "info" | "success" | "warning" | "error";
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+interface NotificationCenterProps {
+    notifications: NotificationItem[];
+    onMarkRead?: (id: string) => void;
+    onMarkAllRead?: () => void;
+    onClear?: () => void;
+    onItemClick?: (item: NotificationItem) => void;
+    align?: "start" | "center" | "end";
+    className?: string;
+    emptyText?: string;
+}
+/**
+ * @component NotificationCenter
+ * @category business/ux
+ * @since 0.2.0
+ * @description Notification bell with popover panel, unread badge, mark-read/clear-all actions, and type-styled indicators / 通知铃铛组件，含弹出面板、未读标记、已读/清空操作和类型样式指示器
+ * @keywords notification, bell, popover, unread, badge, alert
+ * @example
+ * <NotificationCenter notifications={[{ id: "1", title: "Hello", timestamp: Date.now() }]} />
+ */
+declare function NotificationCenter({ notifications, onMarkRead, onMarkAllRead, onClear, onItemClick, align, className, emptyText, }: NotificationCenterProps): React.JSX.Element;
+
+interface UserMenuUser {
+    name: string;
+    email?: string;
+    avatar?: string;
+    role?: string;
+}
+interface UserMenuAction {
+    label: string;
+    icon?: React.ReactNode;
+    onClick?: () => void;
+    href?: string;
+    destructive?: boolean;
+    disabled?: boolean;
+}
+interface UserMenuProps {
+    user: UserMenuUser;
+    actions?: UserMenuAction[];
+    showProfile?: boolean;
+    showSettings?: boolean;
+    onProfile?: () => void;
+    onSettings?: () => void;
+    onSignOut?: () => void;
+    align?: "start" | "center" | "end";
+    className?: string;
+}
+/**
+ * @component UserMenu
+ * @category business/ux
+ * @since 0.2.0
+ * @description Avatar dropdown menu with user info, profile/settings links, custom actions, and sign-out / 头像下拉菜单，包含用户信息、个人资料/设置链接、自定义操作和退出登录
+ * @keywords user, menu, avatar, dropdown, profile, settings, signout
+ * @example
+ * <UserMenu user={currentUser} onProfile={goToProfile} onSignOut={handleSignOut} />
+ */
+declare function UserMenu({ user, actions, showProfile, showSettings, onProfile, onSettings, onSignOut, align, className, }: UserMenuProps): React.JSX.Element;
+
+/**
+ * @component DialogFormBody
+ * @category layout
+ * @since 0.5.0
+ * @description Drop-in body for Dialog forms - stacks FormFields / LabeledFields
+ * vertically with appropriate gap and padding.
+ * / Dialog form layout, vertical FormField stacking, default gap + padding
+ * @example
+ * <DialogContent>
+ *   <DialogHeader>...</DialogHeader>
+ *   <DialogFormBody>
+ *     <LabeledField label="Name">...</LabeledField>
+ *   </DialogFormBody>
+ *   <DialogFooter>...</DialogFooter>
+ * </DialogContent>
+ */
+interface DialogFormBodyProps extends React.ComponentProps<"div"> {
+    /** Gap between fields / field spacing, default 4 (1rem) */
+    gap?: number | string;
+}
+declare function DialogFormBody({ className, gap, ...props }: DialogFormBodyProps): React.JSX.Element;
+interface FormStackProps extends React.ComponentProps<"div"> {
+    /** Gap between items / spacing */
+    gap?: number | string;
+    /** Direction / layout direction */
+    direction?: "vertical" | "horizontal";
+}
+declare function FormStack({ className, gap, direction, ...props }: FormStackProps): React.JSX.Element;
+
+/**
+ * @component MasterDetailLayout
+ * @category layout
+ * @since 0.5.0
+ * @description 主从两栏布局 (master-detail)，左侧固定宽度侧边栏 + 右侧自适应主区域。
+ *
+ * 宽屏并排；窄屏默认堆叠为上下，开启 `collapsible` 后窄屏把 master 折叠成
+ * 左侧抽屉（overlay + 遮罩），对齐 Sidebar 的 collapsible 行为。
+ * / Master-detail two-column layout; mobile master collapses to a drawer.
+ * @keywords layout, master-detail, sidebar, two-column, responsive, drawer
+ * @example
+ * <MasterDetailLayout
+ *   sidebar={<TreeView />}
+ *   main={<SearchTable />}
+ *   sidebarWidth={320}
+ *   collapsible
+ * />
+ */
+interface MasterDetailLayoutProps extends React.ComponentProps<"div"> {
+    /** Sidebar content / 侧边栏内容 */
+    sidebar: React.ReactNode;
+    /** Main area content / 主区域内容 */
+    main: React.ReactNode;
+    /** Sidebar width in px / 侧边栏宽度 */
+    sidebarWidth?: number;
+    /** Gap between sidebar and main / 间距 */
+    gap?: "sm" | "md" | "lg";
+    /**
+     * Collapse master into a drawer on narrow screens.
+     * / 窄屏将 master 折叠为抽屉
+     */
+    collapsible?: boolean;
+    /** Controlled master drawer open state (mobile) / 受控抽屉展开 */
+    masterOpen?: boolean;
+    /** Uncontrolled default open / 非受控默认展开 */
+    defaultMasterOpen?: boolean;
+    /** Master open change callback / 展开状态变更回调 */
+    onMasterOpenChange?: (open: boolean) => void;
+    /** Custom toggle button (defaults to a hamburger Menu button) / 自定义切换按钮 */
+    masterToggle?: React.ReactNode;
+    /**
+     * Also collapse master on desktop (not just mobile). / 桌面端也支持折叠 master
+     */
+    collapsibleDesktop?: boolean;
+}
+declare function MasterDetailLayout({ className, sidebar, main, sidebarWidth, gap, collapsible, masterOpen, defaultMasterOpen, onMasterOpenChange, masterToggle, collapsibleDesktop, ...props }: MasterDetailLayoutProps): React.JSX.Element;
+
+/**
+ * @component AuthLayout
+ * @category layout
+ * @since 0.3.0
+ * @description Authentication page layout. Supports single-column (centered card)
+ * and split-screen (brand left + form right) variants. Collapses to single
+ * column on mobile. / 认证页布局，支持单栏居中和双栏（品牌+表单）模式
+ * @example
+ * <AuthLayout variant="split" brand={<BrandPanel />}>
+ *   <LoginForm />
+ * </AuthLayout>
+ */
+interface AuthLayoutProps extends React.ComponentProps<"div"> {
+    /** Layout variant / 布局模式 */
+    variant?: "centered" | "split";
+    /** Brand panel content (left side in split mode) / 品牌展示区 */
+    brand?: React.ReactNode;
+    /** Brand panel background class (used when brand is a string or empty) / 品牌区背景样式 */
+    brandClassName?: string;
+    /** Maximum width of the form panel / 表单区最大宽度 */
+    formMaxWidth?: string;
+}
+declare function AuthLayout({ variant, brand, brandClassName, formMaxWidth, className, children, ...props }: AuthLayoutProps): React.JSX.Element;
+
+export { AuthLayout as A, DialogFormBody as D, FormStack as F, MasterDetailLayout as M, type NotificationItem as N, type UserMenuUser as U, type UserMenuAction as a, type AuthLayoutProps as b, type DialogFormBodyProps as c, type FormStackProps as d, type MasterDetailLayoutProps as e, NotificationCenter as f, UserMenu as g };