@ticatec/topside-elements 1.0.0

package/dist/feedback/progress-bar/ProgressBar.svelte

@@ -0,0 +1,150 @@
+<script lang="ts">
+    import {ProgressStatus} from "./ProgressStatus";
+
+    type ProgressBarType = "circular" | "linear";
+
+    interface Props {
+        progress?: number;
+        /** 圆形进度条直径（px） */
+        diameter?: number;
+        /** 形状：circular / linear */
+        variant?: ProgressBarType;
+        /** 线形进度条高度（px） */
+        thickness?: number;
+        showText?: boolean;
+        status?: ProgressStatus;
+    }
+
+    let {
+        progress = 0,
+        diameter = 100,
+        variant = "circular",
+        thickness = 5,
+        showText = true,
+        status = ProgressStatus.progressing
+    }: Props = $props();
+
+    // 防御性归一化：把外部可能传入的非法值 clamp 到合法范围。
+    // - progress: 限定 [0, 100]，过滤 NaN / Infinity（避免 SVG 出现 "NaN" 属性、文本出现 "NaN%"）
+    // - diameter / thickness: 至少为 0；radius 额外保证非负，避免 diameter < thickness 时圆弧无法绘制
+    const safeProgress = $derived(
+        Number.isFinite(progress) ? Math.max(0, Math.min(100, progress)) : 0
+    );
+    const safeSize = $derived(Number.isFinite(diameter) && diameter > 0 ? diameter : 0);
+    const safeHeight = $derived(Number.isFinite(thickness) && thickness > 0 ? thickness : 0);
+    const radius = $derived(Math.max(0, (safeSize - safeHeight) / 2));
+    const circumference = $derived(2 * Math.PI * radius);
+    const offset = $derived(circumference * (1 - safeProgress / 100));
+
+    const getCurrentColor = (value: ProgressStatus): string => {
+        switch (value) {
+            case ProgressStatus.successful:
+                return 'var(--topside-progress-bar-success-color, #2DC071)';
+            case ProgressStatus.failure:
+                return 'var(--topside-progress-bar-failure-color, #FF685B)';
+            case ProgressStatus.canceled:
+                return 'var(--topside-progress-bar-canceled-color, #FFC53D)';
+            default:
+                return 'var(--topside-progress-bar-color, #22BDFF)';
+        }
+    };
+
+    const strokeColor = $derived(getCurrentColor(status));
+</script>
+
+{#if variant === "circular"}
+    <svg width={safeSize} height={safeSize} viewBox="0 0 {safeSize} {safeSize}">
+        <circle cx={safeSize / 2} cy={safeSize / 2} r={radius} fill="none"
+                stroke="var(--topside-progress-bar-bg, #E2E8F0)" stroke-width={safeHeight}/>
+        <circle
+                cx={safeSize / 2} cy={safeSize / 2} r={radius}
+                fill="none" stroke={strokeColor} stroke-width={safeHeight}
+                stroke-linecap="round"
+                stroke-dasharray={circumference}
+                stroke-dashoffset={offset}
+                transform="rotate(-90 {safeSize / 2} {safeSize / 2})"
+        />
+        {#if showText}
+            <text x="50%" y="50%" text-anchor="middle" dominant-baseline="middle"
+                  font-size="{status === ProgressStatus.progressing ? '1em' : '2em'}"
+                  fill={strokeColor}>
+                {#if status == ProgressStatus.successful}
+                    ✔
+                {:else if status == ProgressStatus.failure}
+                    &#x2715;
+                {:else if status == ProgressStatus.canceled}
+                    !
+                {:else}
+                    {safeProgress}%
+                {/if}
+            </text>
+        {/if}
+    </svg>
+{:else}
+    <div class="topside-progress-container {status}">
+        <div class="progress-bar" style="width: 100%; height: {safeHeight}px;">
+            <div class="progress-fill" style="width: {safeProgress}%"></div>
+        </div>
+        {#if showText}
+            <span class="progress-text">
+                {#if status == ProgressStatus.successful}
+                    ✔
+                {:else if status == ProgressStatus.failure}
+                    &#x2715;
+                {:else}
+                    {safeProgress}%
+                {/if}
+            </span>
+        {/if}
+    </div>
+{/if}
+
+<style>
+    .topside-progress-container {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+    }
+
+    .progress-bar {
+        background: var(--topside-progress-bar-bg, #E2E8F0);
+        border-radius: 10px;
+        overflow: hidden;
+        transition: width 0.5s ease;
+    }
+
+    .progress-fill {
+        background: var(--topside-progress-bar-color, #22BDFF);
+        height: 100%;
+        transition: width 0.5s ease;
+    }
+
+    .progress-text {
+        font-size: 1.0em;
+        color: var(--topside-progress-bar-text-color, #374151);
+    }
+
+    .topside-progress-container.successful .progress-fill {
+        background-color: var(--topside-progress-bar-success-color, #2DC071);
+    }
+
+    .topside-progress-container.successful .progress-text {
+        color: var(--topside-progress-bar-success-color, #2DC071);
+    }
+
+    .topside-progress-container.failure .progress-fill {
+        background-color: var(--topside-progress-bar-failure-color, #FF685B);
+    }
+
+    .topside-progress-container.failure .progress-text {
+        color: var(--topside-progress-bar-failure-color, #FF685B);
+    }
+
+    .topside-progress-container.canceled .progress-fill {
+        background-color: var(--topside-progress-bar-canceled-color, #FFC53D);
+    }
+
+    .topside-progress-container.canceled .progress-text {
+        color: var(--topside-progress-bar-canceled-color, #FFC53D);
+    }
+</style>

package/dist/feedback/progress-bar/ProgressBar.svelte.d.ts

@@ -0,0 +1,16 @@
+import { ProgressStatus } from "./ProgressStatus";
+type ProgressBarType = "circular" | "linear";
+interface Props {
+    progress?: number;
+    /** 圆形进度条直径（px） */
+    diameter?: number;
+    /** 形状：circular / linear */
+    variant?: ProgressBarType;
+    /** 线形进度条高度（px） */
+    thickness?: number;
+    showText?: boolean;
+    status?: ProgressStatus;
+}
+declare const ProgressBar: import("svelte").Component<Props, {}, "">;
+type ProgressBar = ReturnType<typeof ProgressBar>;
+export default ProgressBar;

package/dist/feedback/progress-bar/ProgressStatus.d.ts

@@ -0,0 +1,6 @@
+export declare enum ProgressStatus {
+    progressing = "progressing",
+    successful = "successful",
+    failure = "failure",
+    canceled = "canceled"
+}

package/dist/feedback/progress-bar/ProgressStatus.js

@@ -0,0 +1,8 @@
+export var ProgressStatus;
+(function (ProgressStatus) {
+    ProgressStatus["progressing"] = "progressing";
+    ProgressStatus["successful"] = "successful";
+    ProgressStatus["failure"] = "failure";
+    ProgressStatus["canceled"] = "canceled";
+})(ProgressStatus || (ProgressStatus = {}));
+;

package/dist/feedback/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/topside-elements
+```
+
+## Import
+
+```typescript
+import ProgressBar, { ProgressStatus } from "@ticatec/topside-elements/ProgressBar";
+```
+
+## Basic Usage
+
+### Circular Progress Bar
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/topside-elements/ProgressBar";
+  
+  let progress = 65;
+  let status = ProgressStatus.progressing;
+</script>
+
+<ProgressBar {progress} {status} />
+```
+
+### Linear Progress Bar
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/topside-elements/ProgressBar";
+  
+  let progress = 45;
+  let status = ProgressStatus.progressing;
+</script>
+
+<ProgressBar type="linear" {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" \| "linear"` | `"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/topside-elements/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="linear" 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 */
+  --topside-progress-bar-color: #22BDFF;
+  
+  /* Background color */
+  --topside-progress-bar-bg: #E2E8F0;
+  
+  /* Success state color */
+  --topside-progress-bar-success-color: #2DC071;
+  
+  /* Failure state color */
+  --topside-progress-bar-failure-color: #FF685B;
+  
+  /* Canceled state color */
+  --topside-progress-bar-canceled-color: #FFC532;
+}
+```
+
+## Styling Examples
+
+### Custom Theme
+
+```css
+.custom-progress {
+  --topside-progress-bar-color: #8B5CF6;
+  --topside-progress-bar-success-color: #10B981;
+  --topside-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/topside-elements/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/topside-elements/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="linear" 
+  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/feedback/progress-bar/README_CN.md

@@ -0,0 +1,242 @@
+# ProgressBar 进度条
+
+一个灵活的进度指示器组件，支持圆形和线性显示模式，具有可自定义的状态和样式。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import ProgressBar, { ProgressStatus } from "@ticatec/topside-elements/ProgressBar";
+```
+
+## 基本用法
+
+### 圆形进度条
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/topside-elements/ProgressBar";
+  
+  let progress = 65;
+  let status = ProgressStatus.progressing;
+</script>
+
+<ProgressBar {progress} {status} />
+```
+
+### 线性进度条
+
+```svelte
+<script>
+  import ProgressBar, { ProgressStatus } from "@ticatec/topside-elements/ProgressBar";
+  
+  let progress = 45;
+  let status = ProgressStatus.progressing;
+</script>
+
+<ProgressBar type="linear" {progress} {status} />
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `progress` | `number` | `0` | 进度值（0-100） |
+| `size` | `number` | `100` | 圆形进度条的大小 |
+| `type` | `"circular" \| "linear"` | `"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/topside-elements/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="linear" height={2} progress={40} />
+```
+
+### 不显示文本
+
+```svelte
+<ProgressBar progress={80} showText={false} />
+```
+
+## CSS 自定义属性
+
+组件使用 CSS 自定义属性进行主题定制：
+
+```css
+:root {
+  /* 默认进度颜色 */
+  --topside-progress-bar-color: #22BDFF;
+  
+  /* 背景颜色 */
+  --topside-progress-bar-bg: #E2E8F0;
+  
+  /* 成功状态颜色 */
+  --topside-progress-bar-success-color: #2DC071;
+  
+  /* 失败状态颜色 */
+  --topside-progress-bar-failure-color: #FF685B;
+  
+  /* 取消状态颜色 */
+  --topside-progress-bar-canceled-color: #FFC532;
+}
+```
+
+## 样式示例
+
+### 自定义主题
+
+```css
+.custom-progress {
+  --topside-progress-bar-color: #8B5CF6;
+  --topside-progress-bar-success-color: #10B981;
+  --topside-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/topside-elements/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/topside-elements/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="linear" 
+  progress={uploadProgress} 
+  status={uploadStatus} 
+  height={6}
+/>
+```
+
+## 无障碍访问
+
+- 为屏幕阅读器使用适当的 ARIA 属性
+- 文本内容根据状态变化，提供更好的无障碍访问
+- 颜色变化伴随符号变化，适合色盲用户
+- 所有状态都保持适当的对比度
+
+## 最佳实践
+
+1. **进度范围**: 保持进度值在 0-100 之间
+2. **状态管理**: 根据操作结果适当更新状态
+3. **视觉反馈**: 使用不同的状态提供清晰的用户反馈
+4. **响应式设计**: 考虑使用基于百分比的尺寸实现响应式布局
+5. **颜色无障碍**: 不要仅依赖颜色来传达状态信息
+
+## 浏览器支持
+
+- 支持 SVG 的现代浏览器（圆形类型）
+- CSS 自定义属性支持
+- 兼容 Svelte 5+
+
+## 相关组件
+
+- `ProgressStepBar` - 多步骤进度指示器
+- `Button` - 用于触发显示进度的操作
+- `Dialog` - 在模态框中显示进度

package/dist/feedback/progress-bar/index.d.ts

@@ -0,0 +1,4 @@
+import ProgressBar from "./ProgressBar.svelte";
+import { ProgressStatus } from "./ProgressStatus.js";
+export default ProgressBar;
+export { ProgressStatus };

package/dist/feedback/progress-bar/index.js

@@ -0,0 +1,4 @@
+import ProgressBar from "./ProgressBar.svelte";
+import { ProgressStatus } from "./ProgressStatus.js";
+export default ProgressBar;
+export { ProgressStatus };