@ticatec/uniface-element 0.3.18 → 0.3.20

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- ESLint and Prettier configuration for code quality
+- Dependency audit scripts for security checking
+- Comprehensive .gitignore for better repository management
+- CHANGELOG.md for tracking version changes
+
+### Changed
+- Moved runtime dependencies (@ticatec/i18n, dayjs, svelte-portal, @ticatec/uniface-google-material-icons) to dependencies section
+- Updated README with corrected import examples
+- Improved project structure and documentation
+
+### Fixed
+- Removed .DS_Store files from git tracking
+- Fixed incorrect component import syntax in README examples
+
+## [0.3.18] - 2025-01-XX
+
+### Added
+- Initial release of @ticatec/uniface-element
+- 50+ UI components for Svelte 5 applications
+- Full TypeScript support
+- Internationalization support (English and Chinese)
+- Comprehensive component documentation
+
+### Components
+- Layout Components: SidebarLayout, HeaderLayout, ClassicLayout, ColumnsLayout, RowsLayout
+- Form Components: TextEditor, NumberEditor, MemoEditor, DatePicker, etc.
+- Data Display: DataTable, ConciseDataTable, ListBox, TreeView
+- Feedback: Dialog, Toast, MessageBox, Drawer
+- Advanced: Transfer, AttachmentFiles, ImageFiles, PropertyEditor
+
+## [Previous Versions]
+
+For version history prior to 0.3.18, please refer to the git commit history.

package/COMPONENT_GUIDE.md

@@ -0,0 +1,441 @@
+# Uniface Element 组件使用指南
+
+本指南帮助你根据使用场景选择合适的组件。
+
+## 📋 目录
+
+- [布局组件](#布局组件)
+- [表单组件](#表单组件)
+- [数据展示](#数据展示)
+- [反馈组件](#反馈组件)
+- [导航组件](#导航组件)
+- [高级组件](#高级组件)
+
+---
+
+## 🏗️ 布局组件
+
+### 应用布局
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **SidebarLayout** | 需要左侧边栏的布局 | 可调整边栏宽度 |
+| **HeaderLayout** | 需要顶部标题栏的布局 | 固定顶部，内容滚动 |
+| **ClassicLayout** | 完整的应用布局 | 包含头部、侧边栏、主内容和页脚 |
+| **ColumnsLayout** | 多列布局 | 响应式列布局 |
+| **RowsLayout** | 多行布局 | 响应式行布局 |
+
+### 容器组件
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **Box** | 简单的容器 | 基础样式容器 |
+| **Card** | 卡片展示 | 带标题和内容的卡片 |
+| **Page** | 页面容器 | 全页面容器 |
+| **Accordion** | 折叠面板 | 可展开/折叠的内容区 |
+| **Split** | 可调整大小的分割区域 | 拖动调整面板大小 |
+| **Separator** | 分隔线 | 视觉分隔元素 |
+
+### 何时使用哪个布局组件？
+
+```
+需要整个应用布局？
+  ├── 有侧边栏？ → SidebarLayout
+  ├── 只有顶部栏？ → HeaderLayout
+  ├── 需要完整的经典布局？ → ClassicLayout
+  └── 需要多列/多行？ → ColumnsLayout / RowsLayout
+
+需要容器或分隔？
+  ├── 卡片展示？ → Card
+  ├── 可折叠内容？ → Accordion
+  ├── 可调整大小？ → Split
+  └── 简单分隔？ → Separator
+```
+
+---
+
+## 📝 表单组件
+
+### 基础输入
+| 组件 | 使用场景 | 输入类型 |
+|------|---------|---------|
+| **TextEditor** | 单行文本输入 | 文本、邮箱、网址等 |
+| **NumberEditor** | 数字输入 | 整数、小数 |
+| **MemoEditor** | 多行文本输入 | 长文本、备注 |
+| **TimeEditor** | 时间输入 | 时:分 |
+| **UnitNumberEditor** | 带单位的数字 | 金额、尺寸等 |
+
+### 选择组件
+| 组件 | 使用场景 | 选择方式 |
+|------|---------|---------|
+| **CheckBox** | 单个布尔选项 | 勾选框 |
+| **RadioButton** | 单选（多选一） | 单选按钮 |
+| **Switch** | 开关切换 | 开/关 |
+| **OptionsSelect** | 下拉单选 | 下拉框 |
+| **OptionsMultiSelect** | 下拉多选 | 多选下拉框 |
+| **CascadeOptionsSelect** | 级联选择 | 省市区等 |
+| **InputOptionsSelect** | 输入可选择 | 可输入也可选择 |
+
+### 日期和时间
+| 组件 | 使用场景 | 功能 |
+|------|---------|------|
+| **DatePicker** | 日期选择 | 选择日期 |
+| **DateTimePicker** | 日期时间选择 | 选择日期和时间 |
+| **DateRange** | 日期范围 | 开始和结束日期 |
+| **TimeEditor** | 时间选择 | 时:分选择 |
+
+### 文件和数据
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **AttachmentFiles** | 文件上传 | 支持多文件、进度显示 |
+| **ImageFiles** | 图片上传 | 专门处理图片 |
+| **LookupEditor** | 查找选择 | 弹窗查找选择 |
+| **Transfer** | 穿梭框 | 左右选择移动 |
+
+### 高级输入
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **SearchBox** | 搜索输入 | 带搜索图标 |
+| **CriteriaField** | 条件字段 | 多条件筛选 |
+| **NumberRange** | 数字范围 | 最小值-最大值 |
+| **PromptsTextEditor** | 提示文本输入 | 自动完成提示 |
+| **InlineCellEditor** | 单元格内编辑 | 表格内编辑 |
+
+### 表单布局
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **FormField** | 表单字段包装 | 标签、错误提示 |
+| **FlexForm** | 弹性表单 | 灵活布局 |
+| **GridForm** | 网格表单 | 对齐网格 |
+
+### 何时使用哪个表单组件？
+
+```
+文本输入？
+  ├── 单行文本 → TextEditor
+  ├── 多行文本 → MemoEditor
+  ├── 数字输入 → NumberEditor
+  ├── 带单位数字 → UnitNumberEditor
+  ├── 时间输入 → TimeEditor
+  └── 需要提示 → PromptsTextEditor
+
+选择输入？
+  ├── 是/否 → CheckBox / Switch
+  ├── 单选（多选一）→ RadioButton
+  ├── 下拉单选 → OptionsSelect
+  ├── 下拉多选 → OptionsMultiSelect
+  ├── 级联选择 → CascadeOptionsSelect
+  └── 可输入可选择 → InputOptionsSelect
+
+日期时间？
+  ├── 日期 → DatePicker
+  ├── 日期和时间 → DateTimePicker
+  ├── 日期范围 → DateRange
+  └── 时间 → TimeEditor
+
+文件数据？
+  ├── 普通文件 → AttachmentFiles
+  ├── 图片 → ImageFiles
+  ├── 查找选择 → LookupEditor
+  └── 左右选择 → Transfer
+```
+
+---
+
+## 📊 数据展示
+
+### 表格组件
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **DataTable** | 完整功能表格 | 分页、排序、选择 |
+| **ConciseDataTable** | 简洁表格 | 轻量级表格 |
+
+### 列表组件
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **ListBox** | 列表展示 | 选择列表 |
+| **TreeView** | 树形结构 | 分层数据 |
+
+### 进度指示
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **ProgressBar** | 进度条 | 水平/垂直进度 |
+| **ProgressStepBar** | 步骤进度 | 多步骤进度指示 |
+| **Navigator** | 向导导航 | 步骤导航器 |
+| **Tag** | 标签 | 状态标签 |
+
+### 何时使用哪个数据展示组件？
+
+```
+表格数据？
+  ├── 复杂表格（分页、排序）→ DataTable
+  └── 简单表格 → ConciseDataTable
+
+列表数据？
+  ├── 平面列表 → ListBox
+  └── 树形结构 → TreeView
+
+进度展示？
+  ├── 进度百分比 → ProgressBar
+  ├── 步骤进度 → ProgressStepBar / Navigator
+  └── 状态标签 → Tag
+```
+
+---
+
+## 💬 反馈组件
+
+### 对话框
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **Dialog** | 通用对话框 | 自定义内容 |
+| **CommonDialog** | 标准对话框 | 确认/取消按钮 |
+| **MessageBox** | 消息框 | 信息提示 |
+| **Drawer** | 抽屉 | 侧边滑出 |
+
+### 通知
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **Toast** | 消息提示 | 轻量级提示 |
+| **PopupHint** | 弹出提示 | 悬浮提示 |
+
+### 何时使用哪个反馈组件？
+
+```
+需要弹窗？
+  ├── 完整对话框 → Dialog
+  ├── 标准确认框 → CommonDialog / MessageBox
+  └── 侧边面板 → Drawer
+
+需要提示？
+  ├── 轻量消息 → Toast
+  └── 悬浮提示 → PopupHint
+```
+
+---
+
+## 🧭 导航组件
+
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **Breadcrumbs** | 面包屑导航 | 层级导航 |
+| **Tabs** | 标签页 | 内容分组 |
+| **NavigatorMenu** | 导航菜单 | 菜单导航 |
+| **ActionBar** | 操作栏 | 工具栏 |
+| **AppTopBar** | 应用顶部栏 | 顶部应用栏 |
+| **ContextMenu** | 右键菜单 | 上下文菜单 |
+| **Navigator** | 向导导航 | 步骤向导 |
+
+### 何时使用哪个导航组件？
+
+```
+导航类型？
+  ├── 层级导航 → Breadcrumbs
+  ├── 内容分组 → Tabs
+  ├── 菜单 → NavigatorMenu
+  ├── 步骤向导 → Navigator
+  └── 工具栏 → ActionBar / AppTopBar
+
+交互菜单？
+  └── 右键菜单 → ContextMenu
+```
+
+---
+
+## 🎨 按钮组件
+
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **Button** | 标准按钮 | 多种类型和样式 |
+| **IconButton** | 图标按钮 | 只显示图标 |
+| **TextButton** | 文本按钮 | 文本样式按钮 |
+
+### 按钮类型选择
+
+```
+按钮重要性？
+  ├── 主要操作 → type="primary"
+  ├── 次要操作 → type="secondary"
+  ├── 第三级 → type="third"
+  └── 危险操作 → 自定义样式
+
+按钮样式？
+  ├── 标准 → variant=""
+  ├── 纯净 → variant="plain"
+  └── 圆角 → variant="round"
+```
+
+---
+
+## 🔧 高级组件
+
+| 组件 | 使用场景 | 特点 |
+|------|---------|------|
+| **PropertyEditor** | 属性编辑 | 键值对编辑 |
+| **Pagination** | 分页 | 数据分页 |
+| **PaginationPanel** | 分页面板 | 完整分页控件 |
+| **color-picker** | 颜色选择 | 颜色选择器 |
+
+---
+
+## 🎯 场景化选择指南
+
+### 场景 1：用户注册表单
+```
+需要组件：
+├── Page - 页面容器
+├── FormField - 表单字段包装
+├── TextEditor - 用户名
+├── TextEditor - 邮箱
+├── PasswordEditor - 密码
+├── OptionsSelect - 国家/地区
+├── CheckBox - 同意条款
+└── Button - 提交按钮
+
+示例代码：
+import Page from '@ticatec/uniface-element/Page';
+import FormField from '@ticatec/uniface-element/FormField';
+import TextEditor from '@ticatec/uniface-element/TextEditor';
+import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+import CheckBox from '@ticatec/uniface-element/CheckBox';
+import Button from '@ticatec/uniface-element/Button';
+```
+
+### 场景 2：数据管理页面
+```
+需要组件：
+├── SidebarLayout - 应用布局
+├── DataTable - 数据表格
+├── SearchBox - 搜索框
+├── CriteriaField - 筛选条件
+├── Button - 新增/删除/编辑按钮
+├── Pagination - 分页
+└── Dialog - 编辑对话框
+```
+
+### 场景 3：设置页面
+```
+需要组件：
+├── Page - 页面容器
+├── Tabs - 分组设置
+├── FormField - 表单字段
+├── TextEditor - 文本设置
+├── NumberEditor - 数字设置
+├── Switch - 开关设置
+├── OptionsSelect - 选项设置
+└── Button - 保存按钮
+```
+
+### 场景 4：向导流程
+```
+需要组件：
+├── Page - 页面容器
+├── Navigator - 步骤导航
+├── FormField - 表单字段
+├── 各种表单组件 - 根据步骤需求
+└── Button - 上一步/下一步
+```
+
+### 场景 5：文件管理
+```
+需要组件：
+├── DataTable - 文件列表
+├── AttachmentFiles - 文件上传
+├── Button - 操作按钮
+├── SearchBox - 文件搜索
+├── CriteriaField - 文件筛选
+└── Dialog - 文件详情
+```
+
+---
+
+## 📌 快速决策树
+
+```
+你需要什么？
+
+1. 布局相关？
+   └─→ [布局组件](#布局组件)
+
+2. 收集用户输入？
+   └─→ [表单组件](#表单组件)
+
+3. 展示数据列表？
+   └─→ [数据展示](#数据展示)
+
+4. 用户反馈或通知？
+   └─→ [反馈组件](#反馈组件)
+
+5. 页面导航？
+   └─→ [导航组件](#导航组件)
+
+6. 触发操作？
+   └─→ [按钮组件](#按钮组件)
+
+7. 高级功能？
+   └─→ [高级组件](#高级组件)
+```
+
+---
+
+## 💡 最佳实践
+
+### 1. 组件组合模式
+
+```
+表单页面：
+Page → FormField → [具体输入组件]
+
+布局：
+SidebarLayout → Box → Card → [内容]
+
+数据管理：
+SidebarLayout → DataTable → Pagination → Dialog → FormField
+```
+
+### 2. 响应式考虑
+
+```
+桌面端优先：
+├── SidebarLayout - 完整侧边栏
+└── DataTable - 大表格
+
+移动端友好：
+├── HeaderLayout - 简化头部
+└── ConciseDataTable - 轻量表格
+```
+
+### 3. 无障碍访问
+
+```
+所有表单组件配合 FormField 使用
+按钮提供明确的 label
+对话框提供关闭按钮
+导航支持键盘操作
+```
+
+---
+
+## 🔍 组件查找速查表
+
+| 需求 | 组件 | 导入路径 |
+|------|------|---------|
+| 输入文本 | TextEditor | `@ticatec/uniface-element/TextEditor` |
+| 输入数字 | NumberEditor | `@ticatec/uniface-element/NumberEditor` |
+| 下拉选择 | OptionsSelect | `@ticatec/uniface-element/OptionsSelect` |
+| 选择日期 | DatePicker | `@ticatec/uniface-element/DatePicker` |
+| 上传文件 | AttachmentFiles | `@ticatec/uniface-element/AttachmentFiles` |
+| 数据表格 | DataTable | `@ticatec/uniface-element/DataTable` |
+| 弹窗对话框 | Dialog | `@ticatec/uniface-element/Dialog` |
+| 侧边抽屉 | Drawer | `@ticatec/uniface-element/Drawer` |
+| 消息提示 | Toast | `@ticatec/uniface-element/Toast` |
+| 按钮 | Button | `@ticatec/uniface-element/Button` |
+| 标签页 | Tabs | `@ticatec/uniface-element/Tabs` |
+| 分页 | Pagination | `@ticatec/uniface-element/Pagination` |
+
+---
+
+## 📚 相关文档
+
+- [组件 API 文档](./src/lib)
+- [示例代码](./src/routes/demo)
+- [贡献指南](./CONTRIBUTING.md)
+- [更新日志](./CHANGELOG.md)