@ticatec/uniface-element 0.2.0 → 0.2.2

package/docs/navigation/cn/progressstepbar.md

@@ -0,0 +1,299 @@
+# ProgressStepBar 步骤进度条组件
+
+ProgressStepBar 组件提供多步骤流程的可视化展示，显示每个步骤的当前状态和进度。
+
+## 功能特性
+
+- **多步骤可视化**：显示多个顺序步骤的进度
+- **状态指示器**：每个步骤的等待、处理中和已完成状态
+- **灵活布局**：支持水平和垂直两种方向
+- **可定制样式**：可配置背景色和样式
+- **步骤信息**：支持标题和可选的备注说明
+
+## 导入
+
+```typescript
+import { ProgressStepBar, ProgressStep, ProgressStepStatus } from '@ticatec/uniface-element/ProgressStepBar';
+```
+
+## 基本用法
+
+### 水平步骤条
+
+```svelte
+<script>
+  import { ProgressStepBar, ProgressStepStatus } from '@ticatec/uniface-element/ProgressStepBar';
+  
+  const steps = [
+    {
+      topic: "账户设置",
+      comment: "创建您的档案",
+      status: ProgressStepStatus.Completed
+    },
+    {
+      topic: "身份验证",
+      comment: "验证您的邮箱",
+      status: ProgressStepStatus.Processing
+    },
+    {
+      topic: "完善资料",
+      comment: "添加个人详情",
+      status: ProgressStepStatus.Pending
+    }
+  ];
+</script>
+
+<ProgressStepBar 
+  {steps} 
+  direction="horizontal" 
+/>
+```
+
+### 垂直步骤条
+
+```svelte
+<script>
+  import { ProgressStepBar, ProgressStepStatus } from '@ticatec/uniface-element/ProgressStepBar';
+  
+  const workflowSteps = [
+    {
+      topic: "审阅文档",
+      status: ProgressStepStatus.Completed
+    },
+    {
+      topic: "经理审批",
+      status: ProgressStepStatus.Processing
+    },
+    {
+      topic: "最终处理",
+      status: ProgressStepStatus.Pending
+    }
+  ];
+</script>
+
+<ProgressStepBar 
+  steps={workflowSteps} 
+  direction="vertical"
+  backgroundColor="#f8f9fa"
+/>
+```
+
+## API 参考
+
+### 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `steps` | `Array<ProgressStep>` | 必需 | 步骤对象数组 |
+| `direction` | `'vertical' \| 'horizontal'` | `'horizontal'` | 布局方向 |
+| `backgroundColor` | `string` | `'var(--uniface-progress-step-bar-bg, #ffffff)'` | 背景颜色 |
+| `style` | `string` | `''` | 附加CSS样式 |
+
+### ProgressStep 接口
+
+```typescript
+interface ProgressStep {
+  topic: string;          // 步骤标题
+  comment?: string;       // 可选的步骤描述
+  status: ProgressStepStatus; // 当前状态
+}
+```
+
+### ProgressStepStatus 枚举
+
+```typescript
+enum ProgressStepStatus {
+  Pending = 'pending',       // 未开始
+  Processing = 'processing', // 当前活动
+  Completed = 'completed'    // 已完成
+}
+```
+
+## 详细示例
+
+### 电商结账流程
+
+```svelte
+<script>
+  import { ProgressStepBar, ProgressStepStatus } from '@ticatec/uniface-element/ProgressStepBar';
+  
+  let checkoutSteps = [
+    {
+      topic: "购物车",
+      comment: "查看您的商品",
+      status: ProgressStepStatus.Completed
+    },
+    {
+      topic: "配送信息",
+      comment: "输入配送详情",
+      status: ProgressStepStatus.Completed
+    },
+    {
+      topic: "支付",
+      comment: "选择支付方式",
+      status: ProgressStepStatus.Processing
+    },
+    {
+      topic: "确认",
+      comment: "审核并完成",
+      status: ProgressStepStatus.Pending
+    }
+  ];
+  
+  const nextStep = () => {
+    const currentIndex = checkoutSteps.findIndex(step => 
+      step.status === ProgressStepStatus.Processing
+    );
+    
+    if (currentIndex >= 0 && currentIndex < checkoutSteps.length - 1) {
+      checkoutSteps[currentIndex].status = ProgressStepStatus.Completed;
+      checkoutSteps[currentIndex + 1].status = ProgressStepStatus.Processing;
+      checkoutSteps = [...checkoutSteps]; // 触发响应式更新
+    }
+  };
+</script>
+
+<div class="checkout-container">
+  <ProgressStepBar steps={checkoutSteps} />
+  <button on:click={nextStep}>下一步</button>
+</div>
+```
+
+### 表单向导与验证
+
+```svelte
+<script>
+  import { ProgressStepBar, ProgressStepStatus } from '@ticatec/uniface-element/ProgressStepBar';
+  
+  let formSteps = [
+    {
+      topic: "个人信息",
+      comment: "姓名、邮箱、电话",
+      status: ProgressStepStatus.Processing
+    },
+    {
+      topic: "地址详情",
+      comment: "配送和账单地址",
+      status: ProgressStepStatus.Pending
+    },
+    {
+      topic: "偏好设置",
+      comment: "通信设置",
+      status: ProgressStepStatus.Pending
+    }
+  ];
+  
+  let currentStepIndex = 0;
+  
+  const completeCurrentStep = () => {
+    if (currentStepIndex < formSteps.length) {
+      formSteps[currentStepIndex].status = ProgressStepStatus.Completed;
+      
+      if (currentStepIndex < formSteps.length - 1) {
+        currentStepIndex++;
+        formSteps[currentStepIndex].status = ProgressStepStatus.Processing;
+      }
+      
+      formSteps = [...formSteps];
+    }
+  };
+</script>
+
+<div class="form-wizard">
+  <ProgressStepBar 
+    steps={formSteps} 
+    direction="horizontal"
+    style="margin-bottom: 20px;"
+  />
+  
+  <div class="step-content">
+    <h3>{formSteps[currentStepIndex]?.topic}</h3>
+    <p>{formSteps[currentStepIndex]?.comment}</p>
+    
+    {#if currentStepIndex < formSteps.length}
+      <button on:click={completeCurrentStep}>
+        完成步骤
+      </button>
+    {/if}
+  </div>
+</div>
+```
+
+### 文件上传流程
+
+```svelte
+<script>
+  import { ProgressStepBar, ProgressStepStatus } from '@ticatec/uniface-element/ProgressStepBar';
+  
+  let uploadSteps = [
+    {
+      topic: "选择文件",
+      status: ProgressStepStatus.Completed
+    },
+    {
+      topic: "上传",
+      comment: "传输文件中...",
+      status: ProgressStepStatus.Processing
+    },
+    {
+      topic: "处理",
+      comment: "分析内容",
+      status: ProgressStepStatus.Pending
+    },
+    {
+      topic: "完成",
+      comment: "文件就绪",
+      status: ProgressStepStatus.Pending
+    }
+  ];
+  
+  const simulateUpload = async () => {
+    // 模拟上传过程
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    uploadSteps[1].status = ProgressStepStatus.Completed;
+    uploadSteps[2].status = ProgressStepStatus.Processing;
+    uploadSteps = [...uploadSteps];
+    
+    // 模拟处理
+    await new Promise(resolve => setTimeout(resolve, 1500));
+    uploadSteps[2].status = ProgressStepStatus.Completed;
+    uploadSteps[3].status = ProgressStepStatus.Processing;
+    uploadSteps = [...uploadSteps];
+    
+    // 完成
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    uploadSteps[3].status = ProgressStepStatus.Completed;
+    uploadSteps = [...uploadSteps];
+  };
+</script>
+
+<ProgressStepBar 
+  steps={uploadSteps} 
+  direction="vertical"
+/>
+<button on:click={simulateUpload}>开始上传</button>
+```
+
+## 最佳实践
+
+1. **清晰的步骤名称**：使用描述性、面向操作的步骤标题
+2. **有用的备注**：为每个步骤提供上下文说明
+3. **逻辑进展**：确保步骤遵循自然的顺序
+4. **状态管理**：保持状态更新与实际进度同步
+5. **用户指导**：显示用户在每个步骤中的期望操作
+6. **错误处理**：考虑如何处理步骤失败或验证错误
+7. **响应式设计**：在不同屏幕尺寸上测试两种方向
+
+## 样式提示
+
+- 在步骤之间使用一致的间距和排版
+- 考虑使用自定义CSS变量进行主题集成
+- 测试状态指示器的可见性和对比度
+- 确保移动界面有足够的触摸目标
+
+## 无障碍访问说明
+
+- 步骤进展提供清晰的视觉反馈
+- 状态变化通过样式和定位表示
+- 在实现自定义交互时考虑为屏幕阅读器添加ARIA标签
+- 确保状态指示器有足够的颜色对比度

package/docs/navigation/en/breadcrumb.md

@@ -0,0 +1,291 @@
+# Breadcrumb Component
+
+The Breadcrumb component provides hierarchical navigation that shows the user's current location within the application structure and allows navigation back to parent levels.
+
+## Features
+
+- **Hierarchical Navigation**: Shows the path from root to current location
+- **Customizable Separator**: Configurable separator character between items
+- **Click Navigation**: Click handlers for navigating to parent levels
+- **Flexible Data Structure**: Support for custom data objects
+- **Styling Support**: Custom styles and CSS integration
+
+## Import
+
+```typescript
+import { Breadcrumbs, Breadcrumb } from '@ticatec/uniface-element/Breadcrumbs';
+```
+
+## Basic Usage
+
+### Simple Breadcrumb
+
+```svelte
+<script>
+  import Breadcrumbs from '@ticatec/uniface-element/Breadcrumbs';
+  
+  const breadcrumbItems = [
+    { label: "Home", data: { route: "/" } },
+    { label: "Products", data: { route: "/products" } },
+    { label: "Electronics", data: { route: "/products/electronics" } },
+    { label: "Laptops", data: { route: "/products/electronics/laptops" } }
+  ];
+  
+  const handleItemClick = (data) => (event) => {
+    console.log('Navigate to:', data.route);
+    // Handle navigation logic here
+  };
+</script>
+
+<Breadcrumbs 
+  items={breadcrumbItems}
+  onItemClick={handleItemClick}
+/>
+```
+
+### Custom Separator
+
+```svelte
+<script>
+  import Breadcrumbs from '@ticatec/uniface-element/Breadcrumbs';
+  
+  const pathItems = [
+    { label: "Dashboard", data: { id: 1 } },
+    { label: "User Management", data: { id: 2 } },
+    { label: "Edit Profile", data: { id: 3 } }
+  ];
+  
+  const navigate = (data) => (event) => {
+    console.log('Navigating to item:', data.id);
+  };
+</script>
+
+<Breadcrumbs 
+  items={pathItems}
+  separator=">"
+  onItemClick={navigate}
+  style="padding: 10px; background: #f5f5f5;"
+/>
+```
+
+## API Reference
+
+### Props
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `items` | `Array<Breadcrumb>` | `[]` | Array of breadcrumb items |
+| `separator` | `string` | `"/"` | Separator character between items |
+| `onItemClick` | `(item: any) => (event: MouseEvent) => void` | required | Click handler function |
+| `style` | `string` | `''` | Additional CSS styles |
+
+### Breadcrumb Interface
+
+```typescript
+interface Breadcrumb {
+  label: string;  // Display text
+  data: any;      // Associated data object
+}
+```
+
+## Advanced Examples
+
+### File System Navigation
+
+```svelte
+<script>
+  import Breadcrumbs from '@ticatec/uniface-element/Breadcrumbs';
+  
+  let currentPath = [
+    { label: "Documents", data: { path: "/documents", type: "folder" } },
+    { label: "Projects", data: { path: "/documents/projects", type: "folder" } },
+    { label: "WebApp", data: { path: "/documents/projects/webapp", type: "folder" } },
+    { label: "src", data: { path: "/documents/projects/webapp/src", type: "folder" } }
+  ];
+  
+  const navigateToPath = (data) => (event) => {
+    // Find the index of the clicked item
+    const clickedIndex = currentPath.findIndex(item => item.data.path === data.path);
+    
+    if (clickedIndex >= 0) {
+      // Truncate the path to the clicked item
+      currentPath = currentPath.slice(0, clickedIndex + 1);
+      console.log('Navigated to:', data.path);
+      
+      // In a real app, you'd update your file browser state here
+    }
+  };
+  
+  const addFolder = () => {
+    currentPath = [...currentPath, { 
+      label: "components", 
+      data: { path: currentPath[currentPath.length - 1].data.path + "/components", type: "folder" }
+    }];
+  };
+</script>
+
+<div class="file-navigator">
+  <Breadcrumbs 
+    items={currentPath}
+    separator="/"
+    onItemClick={navigateToPath}
+    style="font-family: monospace; background: #f8f8f8; padding: 8px; border-radius: 4px;"
+  />
+  
+  <button on:click={addFolder}>Add Components Folder</button>
+</div>
+```
+
+### E-commerce Category Navigation
+
+```svelte
+<script>
+  import Breadcrumbs from '@ticatec/uniface-element/Breadcrumbs';
+  
+  let categoryPath = [
+    { label: "All Categories", data: { categoryId: null, slug: "" } }
+  ];
+  
+  const categories = [
+    { id: 1, name: "Electronics", parent: null, slug: "electronics" },
+    { id: 2, name: "Computers", parent: 1, slug: "computers" },
+    { id: 3, name: "Laptops", parent: 2, slug: "laptops" },
+    { id: 4, name: "Gaming Laptops", parent: 3, slug: "gaming-laptops" }
+  ];
+  
+  const navigateToCategory = (data) => (event) => {
+    if (data.categoryId === null) {
+      // Navigate to root
+      categoryPath = [categoryPath[0]];
+    } else {
+      // Find the clicked category and rebuild path
+      const clickedIndex = categoryPath.findIndex(
+        item => item.data.categoryId === data.categoryId
+      );
+      
+      if (clickedIndex >= 0) {
+        categoryPath = categoryPath.slice(0, clickedIndex + 1);
+      }
+    }
+    
+    console.log('Category path updated:', categoryPath);
+  };
+  
+  const drillDownCategory = (categoryId) => {
+    const category = categories.find(c => c.id === categoryId);
+    if (category) {
+      categoryPath = [...categoryPath, {
+        label: category.name,
+        data: { categoryId: category.id, slug: category.slug }
+      }];
+    }
+  };
+</script>
+
+<div class="category-navigation">
+  <Breadcrumbs 
+    items={categoryPath}
+    separator="›"
+    onItemClick={navigateToCategory}
+    style="margin-bottom: 15px;"
+  />
+  
+  <div class="category-actions">
+    <button on:click={() => drillDownCategory(1)}>Go to Electronics</button>
+    <button on:click={() => drillDownCategory(2)}>Go to Computers</button>
+    <button on:click={() => drillDownCategory(3)}>Go to Laptops</button>
+    <button on:click={() => drillDownCategory(4)}>Go to Gaming</button>
+  </div>
+</div>
+```
+
+### Multi-step Form Navigation
+
+```svelte
+<script>
+  import Breadcrumbs from '@ticatec/uniface-element/Breadcrumbs';
+  
+  const formSteps = [
+    { id: 1, name: "Account Info", completed: true },
+    { id: 2, name: "Personal Details", completed: true },
+    { id: 3, name: "Preferences", completed: false },
+    { id: 4, name: "Confirmation", completed: false }
+  ];
+  
+  let currentStepId = 3;
+  
+  // Build breadcrumb from completed steps + current step
+  $: breadcrumbItems = formSteps
+    .filter((step, index) => step.completed || step.id === currentStepId)
+    .map(step => ({
+      label: step.name,
+      data: { stepId: step.id, completed: step.completed }
+    }));
+  
+  const navigateToStep = (data) => (event) => {
+    // Only allow navigation to completed steps
+    if (data.completed) {
+      currentStepId = data.stepId;
+      console.log('Navigated to step:', data.stepId);
+    }
+  };
+  
+  const completeCurrentStep = () => {
+    const step = formSteps.find(s => s.id === currentStepId);
+    if (step) {
+      step.completed = true;
+      
+      // Move to next uncompleted step
+      const nextStep = formSteps.find(s => !s.completed);
+      if (nextStep) {
+        currentStepId = nextStep.id;
+      }
+    }
+  };
+</script>
+
+<div class="form-breadcrumb">
+  <Breadcrumbs 
+    items={breadcrumbItems}
+    separator="→"
+    onItemClick={navigateToStep}
+    style="background: linear-gradient(90deg, #e3f2fd, #bbdefb); padding: 10px; border-radius: 8px;"
+  />
+  
+  <div class="form-controls">
+    <p>Current Step: {formSteps.find(s => s.id === currentStepId)?.name}</p>
+    <button on:click={completeCurrentStep}>Complete Step</button>
+  </div>
+</div>
+```
+
+## Best Practices
+
+1. **Clear Labels**: Use descriptive, concise labels that clearly indicate the location
+2. **Logical Hierarchy**: Ensure breadcrumbs reflect actual application structure
+3. **Clickable Parents**: Make parent levels clickable for easy navigation
+4. **Current Item Behavior**: The last item typically shouldn't be clickable (represents current location)
+5. **Responsive Design**: Consider how breadcrumbs appear on mobile devices
+6. **Consistent Separators**: Use appropriate separators for your design system
+7. **Performance**: Avoid rebuilding breadcrumbs unnecessarily
+
+## Styling Notes
+
+- The component renders each item with a separator prefix
+- The last item (current location) has click handler set to null
+- Custom styles can be applied via the `style` prop
+- Consider using CSS for hover effects on clickable items
+
+## Accessibility Considerations
+
+- Breadcrumbs provide context about page location
+- Click handlers should provide keyboard support
+- Consider ARIA labels for screen readers
+- Ensure sufficient color contrast for text and separators
+
+## Integration Tips
+
+- Use with routing libraries to sync with URL structure
+- Combine with page titles for better user orientation
+- Consider auto-generating from route configurations
+- Test truncation behavior for very long paths