@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/progress-bar/README.md

@@ -0,0 +1,242 @@
+# ProgressBar
+
+A flexible progress indicator component that supports both circular and linear display modes with customizable status states and styling.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+```
+
+## Basic Usage
+
+### Circular Progress Bar
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+  
+  let progress = 65;
+  let status = ProgressStatus.progressing;
+</script>
+
+<ProgressBar {progress} {status} />
+```
+
+### Linear Progress Bar
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+  
+  let progress = 45;
+  let status = ProgressStatus.progressing;
+</script>
+
+<ProgressBar type="liner" {progress} {status} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `progress` | `number` | `0` | Progress value (0-100) |
+| `size` | `number` | `100` | Size of the circular progress bar |
+| `type` | `"circular" \| "liner"` | `"circular"` | Display type of the progress bar |
+| `height` | `number` | `5` | Height/thickness of the progress bar |
+| `showText` | `boolean` | `true` | Whether to display progress text |
+| `status` | `ProgressStatus` | `ProgressStatus.progressing` | Current status of the progress |
+
+## ProgressStatus Enum
+
+```typescript
+enum ProgressStatus {
+  progressing = 'progressing',
+  successful = 'successful',
+  failure = 'failure',
+  canceled = 'canceled'
+}
+```
+
+## Status Indicators
+
+The progress bar displays different indicators based on the status:
+
+- **progressing**: Shows percentage (e.g., "65%")
+- **successful**: Shows checkmark (✔)
+- **failure**: Shows X mark (✕)
+- **canceled**: Shows exclamation mark (!)
+
+## Examples
+
+### Different Status States
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+</script>
+
+<!-- In progress -->
+<ProgressBar progress={75} status={ProgressStatus.progressing} />
+
+<!-- Successful completion -->
+<ProgressBar progress={100} status={ProgressStatus.successful} />
+
+<!-- Failed -->
+<ProgressBar progress={45} status={ProgressStatus.failure} />
+
+<!-- Canceled -->
+<ProgressBar progress={30} status={ProgressStatus.canceled} />
+```
+
+### Custom Sizing
+
+```svelte
+<!-- Large circular progress -->
+<ProgressBar size={150} height={8} progress={60} />
+
+<!-- Thin linear progress -->
+<ProgressBar type="liner" height={2} progress={40} />
+```
+
+### Without Text Display
+
+```svelte
+<ProgressBar progress={80} showText={false} />
+```
+
+## CSS Custom Properties
+
+The component uses CSS custom properties for theming:
+
+```css
+:root {
+  /* Default progress color */
+  --uniface-progress-bar-color: #22BDFF;
+  
+  /* Background color */
+  --uniface-progress-bar-bg: #E2E8F0;
+  
+  /* Success state color */
+  --uniface-progress-bar-success-color: #2DC071;
+  
+  /* Failure state color */
+  --uniface-progress-bar-failure-color: #FF685B;
+  
+  /* Canceled state color */
+  --uniface-progress-bar-canceled-color: #FFC532;
+}
+```
+
+## Styling Examples
+
+### Custom Theme
+
+```css
+.custom-progress {
+  --uniface-progress-bar-color: #8B5CF6;
+  --uniface-progress-bar-success-color: #10B981;
+  --uniface-progress-bar-failure-color: #EF4444;
+}
+```
+
+```svelte
+<div class="custom-progress">
+  <ProgressBar progress={70} />
+</div>
+```
+
+## Advanced Usage
+
+### Animated Progress
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+  
+  let progress = 0;
+  let status = ProgressStatus.progressing;
+  
+  onMount(() => {
+    const interval = setInterval(() => {
+      progress += 1;
+      if (progress >= 100) {
+        status = ProgressStatus.successful;
+        clearInterval(interval);
+      }
+    }, 50);
+    
+    return () => clearInterval(interval);
+  });
+</script>
+
+<ProgressBar {progress} {status} />
+```
+
+### Upload Progress Example
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+  
+  let uploadProgress = 0;
+  let uploadStatus = ProgressStatus.progressing;
+  
+  async function handleUpload() {
+    uploadProgress = 0;
+    uploadStatus = ProgressStatus.progressing;
+    
+    try {
+      // Simulate upload progress
+      for (let i = 0; i <= 100; i += 10) {
+        uploadProgress = i;
+        await new Promise(resolve => setTimeout(resolve, 200));
+      }
+      uploadStatus = ProgressStatus.successful;
+    } catch (error) {
+      uploadStatus = ProgressStatus.failure;
+    }
+  }
+</script>
+
+<ProgressBar 
+  type="liner" 
+  progress={uploadProgress} 
+  status={uploadStatus} 
+  height={6}
+/>
+```
+
+## Accessibility
+
+- Uses proper ARIA attributes for screen readers
+- Text content changes based on status for better accessibility
+- Color changes are accompanied by symbol changes for color-blind users
+- Proper contrast ratios maintained for all status states
+
+## Best Practices
+
+1. **Progress Range**: Keep progress values between 0-100
+2. **Status Management**: Update status appropriately based on operation outcome
+3. **Visual Feedback**: Use different status states to provide clear user feedback
+4. **Responsive Design**: Consider using percentage-based sizing for responsive layouts
+5. **Color Accessibility**: Don't rely solely on color to convey status information
+
+## Browser Support
+
+- Modern browsers with SVG support (for circular type)
+- CSS custom properties support
+- Compatible with Svelte 5+
+
+## Related Components
+
+- `ProgressStepBar` - Multi-step progress indicator
+- `Button` - For triggering operations that show progress
+- `Dialog` - For displaying progress in modal contexts

package/dist/progress-bar/README_CN.md

@@ -0,0 +1,242 @@
+# ProgressBar 进度条
+
+一个灵活的进度指示器组件，支持圆形和线性显示模式，具有可自定义的状态和样式。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+```
+
+## 基本用法
+
+### 圆形进度条
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+  
+  let progress = 65;
+  let status = ProgressStatus.progressing;
+</script>
+
+<ProgressBar {progress} {status} />
+```
+
+### 线性进度条
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+  
+  let progress = 45;
+  let status = ProgressStatus.progressing;
+</script>
+
+<ProgressBar type="liner" {progress} {status} />
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `progress` | `number` | `0` | 进度值（0-100） |
+| `size` | `number` | `100` | 圆形进度条的大小 |
+| `type` | `"circular" \| "liner"` | `"circular"` | 进度条的显示类型 |
+| `height` | `number` | `5` | 进度条的高度/厚度 |
+| `showText` | `boolean` | `true` | 是否显示进度文本 |
+| `status` | `ProgressStatus` | `ProgressStatus.progressing` | 进度的当前状态 |
+
+## ProgressStatus 枚举
+
+```typescript
+enum ProgressStatus {
+  progressing = 'progressing',  // 进行中
+  successful = 'successful',    // 成功
+  failure = 'failure',          // 失败
+  canceled = 'canceled'         // 已取消
+}
+```
+
+## 状态指示器
+
+进度条根据状态显示不同的指示器：
+
+- **进行中(progressing)**: 显示百分比（如 "65%"）
+- **成功(successful)**: 显示对勾标记（✔）
+- **失败(failure)**: 显示叉号标记（✕）
+- **已取消(canceled)**: 显示感叹号（!）
+
+## 示例
+
+### 不同状态
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+</script>
+
+<!-- 进行中 -->
+<ProgressBar progress={75} status={ProgressStatus.progressing} />
+
+<!-- 成功完成 -->
+<ProgressBar progress={100} status={ProgressStatus.successful} />
+
+<!-- 失败 -->
+<ProgressBar progress={45} status={ProgressStatus.failure} />
+
+<!-- 已取消 -->
+<ProgressBar progress={30} status={ProgressStatus.canceled} />
+```
+
+### 自定义尺寸
+
+```svelte
+<!-- 大型圆形进度条 -->
+<ProgressBar size={150} height={8} progress={60} />
+
+<!-- 细线性进度条 -->
+<ProgressBar type="liner" height={2} progress={40} />
+```
+
+### 不显示文本
+
+```svelte
+<ProgressBar progress={80} showText={false} />
+```
+
+## CSS 自定义属性
+
+组件使用 CSS 自定义属性进行主题定制：
+
+```css
+:root {
+  /* 默认进度颜色 */
+  --uniface-progress-bar-color: #22BDFF;
+  
+  /* 背景颜色 */
+  --uniface-progress-bar-bg: #E2E8F0;
+  
+  /* 成功状态颜色 */
+  --uniface-progress-bar-success-color: #2DC071;
+  
+  /* 失败状态颜色 */
+  --uniface-progress-bar-failure-color: #FF685B;
+  
+  /* 取消状态颜色 */
+  --uniface-progress-bar-canceled-color: #FFC532;
+}
+```
+
+## 样式示例
+
+### 自定义主题
+
+```css
+.custom-progress {
+  --uniface-progress-bar-color: #8B5CF6;
+  --uniface-progress-bar-success-color: #10B981;
+  --uniface-progress-bar-failure-color: #EF4444;
+}
+```
+
+```svelte
+<div class="custom-progress">
+  <ProgressBar progress={70} />
+</div>
+```
+
+## 高级用法
+
+### 动画进度
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+  
+  let progress = 0;
+  let status = ProgressStatus.progressing;
+  
+  onMount(() => {
+    const interval = setInterval(() => {
+      progress += 1;
+      if (progress >= 100) {
+        status = ProgressStatus.successful;
+        clearInterval(interval);
+      }
+    }, 50);
+    
+    return () => clearInterval(interval);
+  });
+</script>
+
+<ProgressBar {progress} {status} />
+```
+
+### 文件上传进度示例
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
+  
+  let uploadProgress = 0;
+  let uploadStatus = ProgressStatus.progressing;
+  
+  async function handleUpload() {
+    uploadProgress = 0;
+    uploadStatus = ProgressStatus.progressing;
+    
+    try {
+      // 模拟上传进度
+      for (let i = 0; i <= 100; i += 10) {
+        uploadProgress = i;
+        await new Promise(resolve => setTimeout(resolve, 200));
+      }
+      uploadStatus = ProgressStatus.successful;
+    } catch (error) {
+      uploadStatus = ProgressStatus.failure;
+    }
+  }
+</script>
+
+<ProgressBar 
+  type="liner" 
+  progress={uploadProgress} 
+  status={uploadStatus} 
+  height={6}
+/>
+```
+
+## 无障碍访问
+
+- 为屏幕阅读器使用适当的 ARIA 属性
+- 文本内容根据状态变化，提供更好的无障碍访问
+- 颜色变化伴随符号变化，适合色盲用户
+- 所有状态都保持适当的对比度
+
+## 最佳实践
+
+1. **进度范围**: 保持进度值在 0-100 之间
+2. **状态管理**: 根据操作结果适当更新状态
+3. **视觉反馈**: 使用不同的状态提供清晰的用户反馈
+4. **响应式设计**: 考虑使用基于百分比的尺寸实现响应式布局
+5. **颜色无障碍**: 不要仅依赖颜色来传达状态信息
+
+## 浏览器支持
+
+- 支持 SVG 的现代浏览器（圆形类型）
+- CSS 自定义属性支持
+- 兼容 Svelte 5+
+
+## 相关组件
+
+- `ProgressStepBar` - 多步骤进度指示器
+- `Button` - 用于触发显示进度的操作
+- `Dialog` - 在模态框中显示进度