@inf-monkeys-tech/monkeys-design 0.4.30 → 0.4.32

package/README.md

@@ -1,192 +1,76 @@
 # @inf-monkeys-tech/monkeys-design
 
-Monkeys Design 组件库 - 用于 OEM 定制的独立 UI 组件包
-
-## 概述
-
-这是一个为 Monkeys 平台设计的主题组件库，将 OEM 定制的 UI 组件从主项目中分离出来，实现：
-
-- **组件隔离**: 各 OEM 主题组件独立维护
-- **动态加载**: 根据 themeId 自动解析对应组件
-- **业务分离**: 纯 UI 组件，业务逻辑由主项目注入
-- **易于扩展**: 新增主题只需添加组件并注册，无需修改主项目
+Monkeys Design 是一个独立的 React 组件库，提供可复用的基础组件、数据展示组件、主题工具和样式资源。
 
 ## 安装
 
-本包发布在 npmjs public registry 上，可直接安装：
-
 ```bash
 yarn add @inf-monkeys-tech/monkeys-design
 ```
 
-## 快速开始
-
-### 在主项目中使用
-
-```tsx
-// 确保导入整个包以执行主题注册
-import * as uiThemes from '@inf-monkeys-tech/monkeys-design';
+或：
 
-const { DynamicComponent } = uiThemes;
-
-function LandingPageWrapper({ themeId }) {
-  return (
-    <DynamicComponent
-      themeId={themeId}
-      name="landing-page"
-      // 注入业务逻辑
-      isAuthenticated={isLoggedIn}
-      user={currentUser}
-      onEnterWorkbench={() => navigate('/workspace')}
-      onLogin={() => navigate('/login')}
-      onCardClick={(title) => handleNavigation(title)}
-    />
-  );
-}
+```bash
+npm install @inf-monkeys-tech/monkeys-design
 ```
 
-### 手动解析组件
+## 使用
 
-```tsx
-import { resolveComponent } from '@inf-monkeys-tech/monkeys-design';
-
-const LandingPage = resolveComponent('bsd', 'landing-page');
-
-if (LandingPage) {
-  return <LandingPage {...props} />;
-}
-```
-
-### 注册自定义主题
+从主入口导入通用能力：
 
 ```tsx
-import { registerTheme } from '@inf-monkeys-tech/monkeys-design';
-import { MyCustomLandingPage } from './MyCustomLandingPage';
-
-registerTheme('my-theme', {
-  'landing-page': MyCustomLandingPage,
-}, {
-  name: 'My Custom Theme',
-  description: 'A custom theme for my application',
-  version: '1.0.0',
-});
+import {
+  applyMonkeysTheme,
+  resolveMonkeysTheme,
+} from '@inf-monkeys-tech/monkeys-design';
 ```
 
-## 内置主题
-
-| 主题 ID | 名称 | 描述 |
-|---------|------|------|
-| `default` | Default Theme | 默认主题，提供基础落地页组件 |
-| `bsd` | BSD Theme | 波司登定制主题 |
-| `artist` | Artist Theme | 艺术家定制主题 |
-| `concept-design` | Concept Design Theme | 概念设计定制主题 |
-
-## 组件列表
-
-| 组件名 | 描述 | 支持主题 |
-|--------|------|----------|
-| `landing-page` | 落地页组件 | default, bsd, artist, concept-design |
-| `toolbox-panel` | 工具箱面板 | bsd |
-
-## Landing Page Props
+从子路径导入组件：
 
-各主题的 Landing Page 组件支持以下通用 props：
-
-```typescript
-interface LandingPageProps {
-  // 认证状态
-  isAuthenticated?: boolean;
-  user?: { name?: string; photo?: string } | null;
-
-  // 回调函数
-  onEnterWorkbench?: () => void;
-  onLogin?: () => void;
-  onCardClick?: (title: string) => void;
-  onQuickActionClick?: (name: string) => void;
+```tsx
+import {
+  BaseButton,
+  BasePanel,
+  type BaseAppearance,
+} from '@inf-monkeys-tech/monkeys-design/components/base';
 
-  // 自定义样式
-  className?: string;
-  style?: React.CSSProperties;
+const appearance: BaseAppearance = {
+  preset: 'admin',
+  radius: 'lg',
+  border: 'subtle',
+  background: 'soft',
+};
 
-  // 主题特定配置（可选）
-  featureCards?: FeatureCardData[];      // BSD
-  quickActions?: QuickActionData[];       // Artist, Concept
-  i18n?: { ... };                         // BSD
-  backgroundComponent?: React.ReactNode;  // Artist
+export function Example() {
+  return (
+    <BasePanel
+      appearance={appearance}
+      title="Design System"
+      description="Composable UI primitives for Monkeys products."
+      footer={<BaseButton appearance={appearance} label="Refresh" />}
+    >
+      Content stays in the consuming application.
+    </BasePanel>
+  );
 }
 ```
 
-## 开发指南
-
-### 环境准备
+## 包入口
 
-```bash
-# 安装依赖
-npm install
+| 路径 | 内容 |
+|------|------|
+| `@inf-monkeys-tech/monkeys-design` | 主入口，导出注册表、主题工具和公共类型 |
+| `@inf-monkeys-tech/monkeys-design/components/base` | 基础组件 |
+| `@inf-monkeys-tech/monkeys-design/components/data-explorer` | 数据展示与页面组合组件 |
+| `@inf-monkeys-tech/monkeys-design/components/login` | 登录相关 UI 组件 |
+| `@inf-monkeys-tech/monkeys-design/components/layout` | 布局组件 |
+| `@inf-monkeys-tech/monkeys-design/components/toolbar` | 工具栏组件 |
+| `@inf-monkeys-tech/monkeys-design/palette` | palette 工具 |
+| `@inf-monkeys-tech/monkeys-design/theme-system` | 主题解析与应用工具 |
 
-# 开发模式（监听变化自动重新构建）
-npm run dev
+## 基础组件
 
-# 构建生产版本
-npm run build
-
-# 类型检查
-npm run typecheck
-
-# 代码检查
-npm run lint
-
-# 启动组件展示站
-npm run storybook
-
-# 构建组件展示站静态产物
-npm run storybook:build
-```
-
-### 组件展示
-
-`@inf-monkeys-tech/monkeys-design` 现在内置了一个基于 Storybook 的展示入口，用来直接预览
-组件库里的通用组件，尤其是 `data-explorer` 这类偏组合式的页面组件。
-
-首批已提供的展示内容包括：
-
-- `Base Components/Theme`
-- `Base Components/Button`
-- `Base Components/Badge`
-- `Base Components/Panel`
-- `Base Components/Empty State`
-- `Base Components/Loading State`
-- `Base Components/Field`
-- `Base Components/Input`
-- `Base Components/Textarea`
-- `Base Components/Select`
-- `Base Components/Switch`
-- `Base Components/Notice`
-- `Base Components/Divider`
-- `Base Components/Section Header`
-- `Base Components/Tabs`
-- `Base Components/Segmented Control`
-- `Base Components/Progress`
-- `Base Components/Skeleton`
-- `Base Components/Avatar`
-- `Base Components/Toolbar`
-- `Base Components/Breadcrumb`
-- `Base Components/Pagination`
-- `Base Components/Description List`
-- `Base Components/Accordion`
-- `Base Components/Context Menu`
-- `Data Explorer/Display Card`
-- `Data Explorer/View Collection`
-- `Data Explorer/Tree`
-- `Data Explorer/Detail Shell`
-- `Data Explorer/Page`
-
-这些 stories 使用本地 mock data 和 mock callbacks，目标是让组件库本身可以像其
-它组件库一样直接浏览、对照和调试，而不依赖 `ui-admin` 或 `monkey` 的业务页。
-
-### 基础组件
-
-通用基础组件从 `components/base` 子路径导入：
+基础组件从 `components/base` 子路径导入：
 
 ```tsx
 import {
@@ -198,35 +82,78 @@ import {
   BasePanel,
   type BaseAppearance,
 } from '@inf-monkeys-tech/monkeys-design/components/base';
-
-const appearance: BaseAppearance = {
-  preset: 'admin',
-  radius: 'lg',
-  border: 'subtle',
-  background: 'soft',
-};
 ```
 
-`BaseAppearance` 负责基础组件的 preset、density、radius、border、background、
-slot 覆盖和 inline style 覆盖。业务仓库仍然负责请求、权限、路由、弹窗副作用和
-具体回调。
+当前包含：
+
+- `BaseButton`
+- `BaseBadge`
+- `BasePanel`
+- `BaseEmptyState`
+- `BaseLoadingState`
+- `BaseField`
+- `BaseInput`
+- `BaseTextarea`
+- `BaseSelect`
+- `BaseLayout`
+- `BaseLayoutPane`
+- `BaseLayoutSplit`
+- `BaseLayoutResizeHandle`
+- `BaseSwitch`
+- `BaseCheckbox`
+- `BaseRadioGroup`
+- `BaseDialog`
+- `BaseDropdownMenu`
+- `BaseTooltip`
+- `BaseTable`
+- `BaseTableFooterBar`
+- `BaseNotice`
+- `BaseDivider`
+- `BaseSectionHeader`
+- `BaseTabs`
+- `BaseSegmentedControl`
+- `BaseProgress`
+- `BaseSkeleton`
+- `BaseAvatar`
+- `BaseToolbar`
+- `BaseBreadcrumb`
+- `BasePagination`
+- `BaseDescriptionList`
+- `BaseAccordion`
+- `BaseContextMenu`
+
+`BaseAppearance` 用于控制 preset、density、radius、border、background、slot className 和 inline style 覆盖。
+
+`BaseLayout` 提供中立布局 primitives：`BaseLayout` 管 header/sidebar/main/aside/footer 区域，`BaseLayoutPane` 管主题化区域表面，`BaseLayoutSplit` 管固定或可调的左右/上下分割。`gap` 可显式控制区域间距，number 按 px，string 原样作为 CSS 长度；不传时继续使用 `BaseAppearance` 的主题间距。可调分割支持 `defaultSize`、受控 `size`、`minSize`、`maxSize` 和 `onSizeChange`；尺寸是否持久化仍由使用方控制。
+
+## Data Explorer
+
+`components/data-explorer` 提供面向数据密集页面的组合组件。组件库负责可复用的控制、展示、预览、详情和布局结构；数据请求、权限、路由、弹窗和业务动作由使用方控制。
+
+```tsx
+import {
+  DataExplorerView,
+  type DataExplorerViewDefinition,
+} from '@inf-monkeys-tech/monkeys-design/components/data-explorer';
+```
 
-`BaseContextMenu` 提供 Radix-backed 右键菜单基础件，支持 label、separator、
-icon、shortcut、disabled、tone、checkbox、radio group 和 submenu 等组合。菜单
-只负责基础交互与视觉 chrome；权限、确认弹窗、API 调用和路由跳转继续由使用方控制。
+常用组件包括：
 
-基础组件默认带有轻量动效，并避免大幅位置移动：按钮、分页、面包屑、面板和描述项主要使用
-颜色、背景、边框、阴影和透明度的平滑过渡；select 弹层、notice、tabs panel、accordion
-panel 使用淡入；select/accordion 图标和 Switch thumb 使用轻量 transform 过渡；progress 使用宽度过渡；
-skeleton/loading 使用脉冲或旋转加载反馈。可点击控件默认提供 pointer 光标，disabled 状态保留
-`cursor-not-allowed`。
-需要静态或更强品牌化效果时，可以通过 `BaseAppearance.slots` 或
-`BaseAppearance.styles` 覆盖。
+- `DataExplorerView`
+- `DataExplorerViewCollection`
+- `DataExplorerDisplayCard`
+- `DataExplorerDisplayCollectionView`
+- `DataExplorerDisplayActionMenu`
+- `DataExplorerDetailShell`
+- `DataExplorerImagePreview`
+- `DataExplorerToolbarShell`
+- `DataExplorerActionBar`
+- `DataExplorerTree`
+- `DataExplorerPage`
 
-### 主题系统
+## 主题系统
 
-`theme-system` 子路径提供统一的主题配置解析和 DOM 应用入口，用于把后端配置、
-品牌信息、palette tokens、基础组件外观和 data-explorer 外观收敛到一个对象。
+`theme-system` 提供主题配置解析和 DOM 应用入口，用于统一处理品牌信息、palette tokens、基础组件外观和 Data Explorer 外观。
 
 ```tsx
 import {
@@ -234,106 +161,66 @@ import {
   resolveMonkeysTheme,
 } from '@inf-monkeys-tech/monkeys-design/theme-system';
 
-const theme = resolveMonkeysTheme(systemConfig);
+const theme = resolveMonkeysTheme(config);
 
 applyMonkeysTheme(theme);
 
 <BasePanel appearance={theme.appearances.base.input} />;
 ```
 
-当前兼容 `theme.colors.primaryColor`、`theme.themeMode`、`theme.roundedSize`、
-`theme.logo`、`theme.favicon` 等 `/api/configs` 形态；也支持库内原生的
-`tokens`、`brand`、`appearances.base` 和 `appearances.dataExplorer`。
-`registerTheme` 仍只负责组件替换注册，不作为业务配置 API。
+支持的配置包括 `tokens`、`brand`、`appearances.base` 和 `appearances.dataExplorer`。也兼容 `colors.primaryColor`、`themeMode`、`roundedSize`、`logo`、`favicon` 等常见配置形态。
 
-### 目录结构
+## 样式资源
 
-```
-src/
-├── index.ts                    # 主入口，导出所有公共 API
-├── registry/                   # 组件注册表核心
-│   └── index.ts               # registerTheme, resolveComponent
-├── components/                 # 通用组件
-│   └── DynamicComponent.tsx   # 动态组件解析器
-└── themes/                     # 各主题组件
-    ├── default/               # 默认主题
-    │   ├── index.ts          # 主题注册入口
-    │   └── components/
-    │       └── LandingPage.tsx
-    ├── bsd/                   # BSD 主题
-    │   ├── index.ts
-    │   └── components/
-    │       ├── LandingPage.tsx
-    │       └── ToolboxPanel.tsx
-    ├── artist/                # Artist 主题
-    │   ├── index.ts
-    │   └── components/
-    │       └── LandingPage.tsx
-    └── concept/               # Concept Design 主题
-        ├── index.ts
-        └── components/
-            └── LandingPage.tsx
-```
+可从包内直接引用样式文件：
 
-### 新增主题
+```ts
+import '@inf-monkeys-tech/monkeys-design/styles/global.scss';
+import '@inf-monkeys-tech/monkeys-design/styles/workflow-nodes.css';
+```
 
-1. 在 `src/themes/` 下创建新的主题目录
-2. 创建组件文件和 `index.ts` 入口
-3. 在入口中使用 `registerTheme` 注册主题
-4. 在 `src/index.ts` 中导入新主题的入口文件
-5. 更新 `tsup.config.ts` 添加新的构建入口
+## Storybook
 
-示例：
+本仓库内置 Storybook，用于预览和调试组件：
 
-```typescript
-// src/themes/my-theme/index.ts
-import { registerTheme } from '../../registry';
-import { MyLandingPage } from './components/LandingPage';
+```bash
+npm run storybook
+```
 
-registerTheme('my-theme', {
-  'landing-page': MyLandingPage,
-}, {
-  name: 'My Theme',
-  version: '1.0.0',
-});
+构建静态 Storybook：
 
-export { MyLandingPage };
+```bash
+npm run storybook:build
 ```
 
-### 注意事项
+## 开发
 
-- **sideEffects**: `package.json` 中设置 `"sideEffects": true` 以防止 tree-shaking 移除主题注册代码
-- **导入方式**: 在主项目中使用 `import * as uiThemes` 确保所有主题注册代码被执行
-- **Vite 配置**: 在主项目的 `vite.config.ts` 中将此包添加到 `optimizeDeps.include`
+```bash
+# 安装依赖
+npm install
 
-## 发布新版本
+# 开发模式
+npm run dev
 
-> 首次发布需要 npmjs 账号拥有发布权限。
+# 构建生产产物
+npm run build
 
-### 1. 登录 npmjs
+# 类型检查
+npm run typecheck
 
-```bash
-npm login --registry=https://registry.npmjs.org/
-# Email: 你的邮箱
+# 代码检查
+npm run lint
 ```
 
-### 2. 更新版本号
-
-```bash
-# 根据改动类型选择：
-npm version patch   # 修复 bug：0.1.0 → 0.1.1
-npm version minor   # 新功能：  0.1.0 → 0.2.0
-npm version major   # 破坏性变更：0.1.0 → 1.0.0
-```
+## 发布
 
-### 3. 构建并发布
+> 需要 npmjs 账号拥有 `@inf-monkeys-tech` scope 的发布权限。
 
 ```bash
-yarn build && npm publish
+npm login --registry=https://registry.npmjs.org/
+npm version patch
+npm run build
+npm publish --registry=https://registry.npmjs.org/ --access public
 ```
 
-### 4. 在消费端更新
-
-```bash
-yarn upgrade @inf-monkeys-tech/monkeys-design
-```
+如果账号启用了浏览器钥匙串或 passkey，npm CLI 会给出一个浏览器验证链接。完成验证后发布会继续。