@mxmweb/zui 1.3.4 → 1.3.5

package/README.md

@@ -0,0 +1,413 @@
+# @mxmweb/zui
+
+一个现代化的 React UI 组件库，提供完整的主题系统和丰富的组件集合。
+
+## 📦 包结构
+
+ZUI 采用模块化设计，包含以下子包：
+- **@mxmweb/zui-theme** (v2.1.x) - 主题系统包
+- **@mxmweb/zui-elements** (v1.1.x) - 基础元素组件
+- **@mxmweb/zui-components** (v1.1.x) - 复杂业务组件
+- **@mxmweb/zui-layouts** (v1.1.x) - 布局容器组件
+- **@mxmweb/zui-icons** (v1.x) - 图标组件包
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# 安装主包（推荐）
+npm install @mxmweb/zui
+
+# 或者安装子包（按需安装）
+npm install @mxmweb/zui-theme @mxmweb/zui-elements @mxmweb/zui-components @mxmweb/zui-layouts @mxmweb/zui-icons
+```
+
+### 依赖要求
+
+确保你的项目已安装以下依赖：
+
+```json
+{
+  "dependencies": {
+    "react": ">=18.0.0 <20.0.0",
+    "react-dom": ">=18.0.0 <20.0.0",
+    "styled-components": "^6.0.0"
+  }
+}
+```
+
+**可选依赖**（根据使用的组件）：
+```json
+{
+  "dependencies": {
+    "animejs": "^3.0.0",           // 动画组件需要
+    "antd": "^5.0.0",              // 表单组件需要
+    "lucide-react": "^0.456.0"     // 图标组件需要
+  }
+}
+```
+
+### 基础使用
+
+```tsx
+import React from 'react';
+import { ThemeProvider, Button, GoogleNavbar } from '@mxmweb/zui';
+import '@mxmweb/zui/style.css';
+
+// 自定义主题
+const customTheme = {
+  colors: {
+    primary: '#007bff',
+    background: '#ffffff',
+    text: '#333333'
+  },
+  space: {
+    radius: '8px',
+    padding: '16px'
+  }
+};
+
+function App() {
+  return (
+    <ThemeProvider theme={customTheme}>
+      <div>
+        <GoogleNavbar 
+          items={[
+            { key: 'home', name: '首页', icon: '🏠' },
+            { key: 'about', name: '关于', icon: 'ℹ️' }
+          ]}
+        />
+        <Button mode="primary" label="点击我" />
+      </div>
+    </ThemeProvider>
+  );
+}
+
+export default App;
+```
+
+## 🎨 主题系统
+
+ZUI 提供强大的主题系统，支持 3 级优先级：
+
+1. **用户 styles** - 最高优先级
+2. **useTheme 上下文** - 中等优先级  
+3. **默认主题** - 基础优先级
+
+### 主题配置
+
+```tsx
+import { ThemeProvider, useTheme } from '@mxmweb/zui';
+
+// 全局主题配置
+const globalTheme = {
+  theme: {
+    colors: {
+      primary: '#007bff',
+      secondary: '#6c757d',
+      success: '#28a745',
+      error: '#dc3545',
+      background: '#ffffff',
+      text: '#333333',
+      border: '#dee2e6'
+    },
+    space: {
+      radius: '8px',
+      padding: '16px'
+    },
+    fonts: {
+      heading: {
+        family: 'PingFang SC, Microsoft YaHei, Arial, sans-serif',
+        size: '16px',
+        weight: '600'
+      },
+      body: {
+        family: 'PingFang SC, Microsoft YaHei, Arial, sans-serif',
+        size: '14px',
+        weight: '400'
+      }
+    }
+  },
+  mode: 'light' // 或 'dark'
+};
+
+// 组件级主题覆盖
+function MyComponent() {
+  const globalTheme = useTheme();
+  
+  const customStyles = {
+    theme: {
+      colors: {
+        primary: '#ff6b6b' // 覆盖全局主题
+      }
+    }
+  };
+
+  return (
+    <Button 
+      mode="primary" 
+      label="自定义按钮"
+      styles={customStyles} // 最高优先级
+    />
+  );
+}
+```
+
+## 📚 组件文档
+
+### 基础元素 (@mxmweb/zui-elements)
+
+#### Button 按钮
+```tsx
+import { Button } from '@mxmweb/zui';
+
+<Button 
+  mode="primary"        // 'primary' | 'default' | 'error' | 'text'
+  label="按钮文字"
+  icon={<Icon />}      // 可选图标
+  disabled={false}     // 禁用状态
+  loading={false}      // 加载状态
+  onClick={() => {}}   // 点击事件
+  styles={customStyles} // 自定义样式
+/>
+```
+
+#### DropdownMenu 下拉菜单
+```tsx
+import { DropdownMenu } from '@mxmweb/zui';
+
+<DropdownMenu
+  actions={[
+    { key: 'edit', label: '编辑', icon: <EditIcon /> },
+    { key: 'delete', label: '删除', icon: <DeleteIcon />, type: 'divider' },
+    { key: 'more', label: '更多' }
+  ]}
+  onAction={(key) => console.log(key)}
+  direction="bottom"   // 'top' | 'bottom'
+  styles={customStyles}
+/>
+```
+
+### 复杂组件 (@mxmweb/zui-components)
+
+#### GoogleNavbar 导航栏
+```tsx
+import { GoogleNavbar } from '@mxmweb/zui';
+
+<GoogleNavbar
+  items={[
+    { 
+      key: 'home', 
+      name: '首页', 
+      icon: '🏠',
+      activeIcon: '🏡',
+      path: '/home',
+      badge: 5
+    }
+  ]}
+  activePath="/home"
+  open={true}
+  onOpenChange={(open) => {}}
+  onItemClick={(item) => {}}
+  logo={<Logo />}
+  styles={customStyles}
+/>
+```
+
+#### DynamicTable 动态表格
+```tsx
+import { DynamicTable } from '@mxmweb/zui';
+
+<DynamicTable
+  columns={[
+    { id: 'name', title: '姓名', type: 'text' },
+    { id: 'age', title: '年龄', type: 'number' },
+    { id: 'status', title: '状态', type: 'status' }
+  ]}
+  dataSource={[
+    { id: '1', data: [
+      { columnId: 'name', value: '张三' },
+      { columnId: 'age', value: 25 }
+    ]}
+  ]}
+  allowMultiSelect={true}
+  viewBehavior="pagination"
+  styles={customStyles}
+/>
+```
+
+#### Uploader 文件上传
+```tsx
+import { Uploader } from '@mxmweb/zui';
+
+<Uploader
+  multiple={true}
+  accept="image/*"
+  maxSize={10} // MB
+  url="/api/upload"
+  autoUpload={true}
+  itemForm={[
+    { name: 'title', label: '标题', type: 'text' },
+    { name: 'description', label: '描述', type: 'textarea' }
+  ]}
+  eventsEmit={(event, data) => {
+    console.log(event, data);
+  }}
+  styles={customStyles}
+/>
+```
+
+### 布局容器 (@mxmweb/zui-layouts)
+
+#### DashboardContainer 仪表板容器
+```tsx
+import { DashboardContainer } from '@mxmweb/zui';
+
+<DashboardContainer
+  title="仪表板"
+  description="系统概览"
+  breadcrumbs={[
+    { id: 'home', label: '首页', path: '/' },
+    { id: 'dashboard', label: '仪表板' }
+  ]}
+  dockItems={navItems}
+  goBack={() => history.back()}
+  eventsEmit={{
+    onBreadcrumbClick: (item, index) => {},
+    onGoBack: () => {},
+    onTitleClick: () => {}
+  }}
+  styles={customStyles}
+>
+  <YourContent />
+</DashboardContainer>
+```
+
+#### DockContainer 全屏容器
+```tsx
+import { DockContainer } from '@mxmweb/zui';
+
+<DockContainer
+  backgroundImage="/bg.jpg"
+  backgroundColor="#1a1a1a"
+  header={<Header />}
+  dockItems={dockItems}
+  dockActiveMode="single"
+  eventsEmit={{
+    onDockItemClick: (item, index) => {},
+    onDockActiveChange: (activeId, item) => {}
+  }}
+  styles={customStyles}
+>
+  <YourContent />
+</DockContainer>
+```
+
+## 🔧 高级配置
+
+### 按需导入
+
+```tsx
+// 只导入需要的组件
+import { Button, DropdownMenu } from '@mxmweb/zui-elements';
+import { GoogleNavbar, DynamicTable } from '@mxmweb/zui-components';
+import { DashboardContainer } from '@mxmweb/zui-layouts';
+import { ThemeProvider } from '@mxmweb/zui-theme';
+```
+
+### TypeScript 支持
+
+所有组件都提供完整的 TypeScript 类型定义：
+
+```tsx
+import type { 
+  ButtonProps, 
+  DropdownMenuAction,
+  GoggleNavItem,
+  DynamicTableColumn,
+  Styles,
+  AppTheme 
+} from '@mxmweb/zui';
+```
+
+### 样式覆盖
+
+```tsx
+// 全局样式覆盖
+const globalStyles = {
+  theme: {
+    colors: {
+      primary: '#your-color'
+    }
+  }
+};
+
+<ThemeProvider theme={globalStyles}>
+  <App />
+</ThemeProvider>
+
+// 组件级样式覆盖
+<Button 
+  styles={{
+    theme: {
+      colors: {
+        primary: '#component-specific-color'
+      }
+    }
+  }}
+/>
+```
+
+## 📋 版本兼容性
+
+| 包名 | 当前版本 | React | Node | 主要特性 |
+|------|----------|-------|------|----------|
+| @mxmweb/zui | 1.3.4 | >=18 <20 | >=22 | 聚合包 |
+| @mxmweb/zui-theme | 2.1.3 | >=18 <20 | >=22 | 主题系统 |
+| @mxmweb/zui-elements | 1.1.4 | >=18 <20 | >=22 | 基础组件 |
+| @mxmweb/zui-components | 1.1.2 | >=18 <20 | >=22 | 业务组件 |
+| @mxmweb/zui-layouts | 1.1.2 | >=18 <20 | >=22 | 布局容器 |
+
+## 🛠️ 开发指南
+
+### 本地开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/mxmweb/zui.git
+cd zui
+
+# 安装依赖
+pnpm install
+
+# 启动开发服务器
+pnpm dev
+
+# 构建所有包
+pnpm build:all
+
+# 发布包
+pnpm publish
+```
+
+### 贡献指南
+
+1. Fork 仓库
+2. 创建功能分支
+3. 提交更改
+4. 推送到分支
+5. 创建 Pull Request
+
+## 📄 许可证
+
+MIT License - 详见 [LICENSE](LICENSE) 文件
+
+## 🤝 支持
+
+- 📧 邮箱：mxm.web.develop@gmail.com
+- 🐛 问题反馈：[GitHub Issues](https://github.com/mxmweb/zui/issues)
+
+---
+
+**ZUI** - 让 React 开发更简单、更高效！

package/package.json

@@ -5,7 +5,7 @@
   "style": "assets/style.css",
   "types": "cluster_enter.d.ts",
   "private": false,
-  "version": "1.3.4",
+  "version": "1.3.5",
   "author": "hanfeng_Zhang",
   "type": "module",
   "scripts": {