@ticatec/uniface-element 0.2.0 → 0.2.1

package/docs/buttons/cn/TextButton.md

@@ -0,0 +1,163 @@
+# TextButton 组件
+
+`TextButton` 组件针对纯文本按钮进行了优化，采用最小化样式。
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import TextButton from '@ticatec/uniface-element/TextButton';
+  
+  const handleCancel = async (event: MouseEvent) => {
+    // 处理取消操作
+  };
+</script>
+
+<TextButton 
+  label="取消"
+  type="secondary"
+  onClick={handleCancel}
+/>
+```
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import TextButton from '@ticatec/uniface-element/TextButton';
+  
+  const actions = {
+    save: async () => { /* 保存逻辑 */ },
+    delete: async () => { /* 删除逻辑 */ },
+    cancel: async () => { /* 取消逻辑 */ }
+  };
+</script>
+
+<!-- 不同按钮类型 -->
+<TextButton label="主要操作" type="primary" onClick={actions.save} />
+<TextButton label="次要操作" type="secondary" onClick={actions.cancel} />
+<TextButton label="危险操作" type="third" onClick={actions.delete} />
+
+<!-- 不同大小 -->
+<TextButton label="大号" size="big" onClick={actions.save} />
+<TextButton label="普通" size="medium" onClick={actions.save} />
+<TextButton label="小号" size="mini" onClick={actions.save} />
+
+<!-- 带自定义内容 -->
+<TextButton type="primary" onClick={actions.save}>
+  <i class="icon_google_check"></i> 确认更改
+</TextButton>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `label` | `string` | `''` | 按钮文本标签 |
+| `type` | `ButtonType` | `'default'` | 视觉样式变体 |
+| `size` | `'big' \| 'medium' \| 'mini'` | `'medium'` | 按钮大小 |
+| `disabled` | `boolean` | `false` | 禁用按钮交互 |
+| `style` | `string` | `''` | 自定义 CSS 样式 |
+| `onClick` | `MouseClickHandler` | - | 异步点击事件处理器 |
+
+## 样式变体
+
+### ButtonType 选项
+
+```typescript
+type ButtonType = 'default' | 'primary' | 'secondary' | 'third' | 'forth';
+```
+
+### 视觉外观
+
+- **default**: 标准中性按钮外观
+- **primary**: 强调主要操作的按钮（通常为蓝色）
+- **secondary**: 次要操作按钮（通常为灰色）
+- **third**: 替代样式（通常用于警告/注意）
+- **forth**: 附加样式变体
+
+### 大小变体
+
+- **big**: 大按钮尺寸，用于突出操作
+- **medium**: 标准按钮尺寸，适用于大多数使用场景
+- **mini**: 小按钮尺寸，用于紧凑界面
+
+## 使用场景
+
+TextButton 组件特别适合以下场景：
+
+- 对话框中的取消/确认操作
+- 导航链接样式的按钮
+- 内联操作按钮
+- 表单中的辅助操作
+
+## 最佳实践
+
+### 在对话框中使用
+
+```svelte
+<script lang="ts">
+  import TextButton from '@ticatec/uniface-element/TextButton';
+  
+  const handleCancel = async () => {
+    closeDialog();
+  };
+  
+  const handleConfirm = async () => {
+    await saveChanges();
+    closeDialog();
+  };
+</script>
+
+<div class="dialog-actions">
+  <TextButton label="取消" type="secondary" onClick={handleCancel} />
+  <TextButton label="确认" type="primary" onClick={handleConfirm} />
+</div>
+
+<style>
+  .dialog-actions {
+    display: flex;
+    gap: 12px;
+    justify-content: flex-end;
+    margin-top: 16px;
+  }
+</style>
+```
+
+### 作为内联操作
+
+```svelte
+<div class="content-item">
+  <span class="item-text">项目名称</span>
+  <div class="item-actions">
+    <TextButton label="编辑" type="primary" size="mini" onClick={editItem} />
+    <TextButton label="删除" type="third" size="mini" onClick={deleteItem} />
+  </div>
+</div>
+
+<style>
+  .content-item {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 8px 0;
+  }
+  
+  .item-actions {
+    display: flex;
+    gap: 8px;
+  }
+</style>
+```
+
+## API 参考
+
+### MouseClickHandler 类型
+
+```typescript
+type MouseClickHandler = (event: MouseEvent) => Promise<void>;
+```
+
+### 点击节流
+
+TextButton 组件实现了自动点击节流，具有 500ms 冷却时间，以防止意外的双击并确保正确的异步操作处理。

package/docs/buttons/en/ActionBar.md

@@ -0,0 +1,459 @@
+# ActionBar Component
+
+The `ActionBar` component provides a container for organizing multiple button actions with consistent spacing and layout.
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  const actions: ButtonActions = [
+    {
+      label: "Save",
+      type: "primary",
+      icon: "icon_google_save",
+      handler: async () => {
+        await saveChanges();
+      }
+    },
+    {
+      label: "Cancel",
+      type: "secondary",
+      handler: async () => {
+        closeDialog();
+      }
+    }
+  ];
+</script>
+
+<ActionBar buttons={actions} />
+```
+
+## Advanced Usage
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  let isProcessing = false;
+  
+  const formActions: ButtonActions = [
+    {
+      label: "Reset",
+      type: "default",
+      icon: "icon_google_undo",
+      handler: async () => {
+        resetForm();
+      }
+    },
+    null, // Separator
+    {
+      label: "Preview",
+      type: "secondary",
+      icon: "icon_google_visibility",
+      handler: async () => {
+        showPreview();
+      }
+    },
+    {
+      label: isProcessing ? "Processing..." : "Submit",
+      type: "primary",
+      icon: "icon_google_send",
+      disabled: isProcessing,
+      handler: async () => {
+        isProcessing = true;
+        try {
+          await submitForm();
+        } finally {
+          isProcessing = false;
+        }
+      }
+    }
+  ];
+</script>
+
+<ActionBar 
+  buttons={formActions} 
+  gap={12}
+  style="padding: 16px; justify-content: flex-end;"
+/>
+```
+
+## ActionBar with Custom Content
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import Button from '@ticatec/uniface-element/Button';
+</script>
+
+<!-- When no buttons prop is provided, slot content is used -->
+<ActionBar gap={16} style="padding: 20px;">
+  <Button label="Custom Action 1" type="primary" onClick={action1} />
+  <Button label="Custom Action 2" type="secondary" onClick={action2} />
+  <Button label="Custom Action 3" type="default" onClick={action3} />
+</ActionBar>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `buttons` | `ButtonActions` | `[]` | Array of button configurations |
+| `style` | `string` | `''` | Custom CSS styles |
+| `gap` | `number` | `8` | Button spacing in pixels |
+
+## API Reference
+
+### ButtonAction Interface
+
+```typescript
+interface ButtonAction {
+  /** Button label text */
+  label: string;
+  
+  /** Whether button is disabled */
+  disabled?: boolean;
+  
+  /** Icon class (e.g., Google Material Icons) */
+  icon?: string;
+  
+  /** Button type for styling */
+  type?: ButtonType;
+  
+  /** Click event handler */
+  handler?: MouseClickHandler;
+}
+
+type ButtonActions = Array<ButtonAction | null>;
+```
+
+### MouseClickHandler Type
+
+```typescript
+type MouseClickHandler = (event: MouseEvent) => Promise<void>;
+```
+
+## Usage Examples
+
+### Dialog Actions
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  export let onSave: () => Promise<void>;
+  export let onCancel: () => void;
+  
+  const dialogActions: ButtonActions = [
+    {
+      label: "Cancel",
+      type: "secondary",
+      handler: async () => {
+        onCancel();
+      }
+    },
+    {
+      label: "Save Changes",
+      type: "primary",
+      icon: "icon_google_save",
+      handler: async () => {
+        await onSave();
+      }
+    }
+  ];
+</script>
+
+<div class="dialog-footer">
+  <ActionBar buttons={dialogActions} style="justify-content: flex-end;" />
+</div>
+```
+
+### Form Action Bar
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  let formData = {};
+  let isSubmitting = false;
+  let isDraft = false;
+  
+  const formActions: ButtonActions = [
+    {
+      label: "Reset",
+      type: "default",
+      handler: async () => {
+        formData = {};
+      }
+    },
+    null, // Separator
+    {
+      label: isDraft ? "Saving..." : "Save Draft",
+      type: "secondary",
+      icon: "icon_google_save",
+      disabled: isDraft,
+      handler: async () => {
+        isDraft = true;
+        try {
+          await saveDraft(formData);
+        } finally {
+          isDraft = false;
+        }
+      }
+    },
+    {
+      label: isSubmitting ? "Submitting..." : "Submit",
+      type: "primary",
+      icon: "icon_google_send",
+      disabled: isSubmitting,
+      handler: async () => {
+        isSubmitting = true;
+        try {
+          await submitForm(formData);
+        } finally {
+          isSubmitting = false;
+        }
+      }
+    }
+  ];
+</script>
+
+<form>
+  <!-- Form fields here -->
+  
+  <div class="form-footer">
+    <ActionBar 
+      buttons={formActions} 
+      gap={12}
+      style="justify-content: flex-end; margin-top: 24px;"
+    />
+  </div>
+</form>
+```
+
+### Toolbar Implementation
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  let selectedItems = [];
+  
+  const toolbarActions: ButtonActions = [
+    {
+      label: "Select All",
+      icon: "icon_google_check_box",
+      type: "default",
+      handler: async () => {
+        selectAll();
+      }
+    },
+    null, // Separator
+    {
+      label: "Export",
+      icon: "icon_google_download",
+      type: "secondary",
+      disabled: selectedItems.length === 0,
+      handler: async () => {
+        await exportItems(selectedItems);
+      }
+    },
+    {
+      label: "Delete Selected",
+      icon: "icon_google_delete",
+      type: "third",
+      disabled: selectedItems.length === 0,
+      handler: async () => {
+        if (confirm(`Delete ${selectedItems.length} items?`)) {
+          await deleteItems(selectedItems);
+        }
+      }
+    }
+  ];
+</script>
+
+<div class="toolbar">
+  <div class="toolbar-info">
+    {selectedItems.length} items selected
+  </div>
+  <ActionBar buttons={toolbarActions} />
+</div>
+
+<style>
+  .toolbar {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 12px;
+    border-bottom: 1px solid #eee;
+  }
+  
+  .toolbar-info {
+    color: #666;
+    font-size: 14px;
+  }
+</style>
+```
+
+### Card Action Bar
+
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+  import type { ButtonActions } from '@ticatec/uniface-element';
+  
+  export let item: any;
+  export let onEdit: (item: any) => Promise<void>;
+  export let onShare: (item: any) => Promise<void>;
+  export let onDelete: (item: any) => Promise<void>;
+  
+  const cardActions: ButtonActions = [
+    {
+      label: "Edit",
+      icon: "icon_google_edit",
+      type: "primary",
+      handler: async () => {
+        await onEdit(item);
+      }
+    },
+    {
+      label: "Share",
+      icon: "icon_google_share",
+      type: "secondary",
+      handler: async () => {
+        await onShare(item);
+      }
+    },
+    {
+      label: "Delete",
+      icon: "icon_google_delete",
+      type: "third",
+      handler: async () => {
+        if (confirm("Are you sure you want to delete this item?")) {
+          await onDelete(item);
+        }
+      }
+    }
+  ];
+</script>
+
+<div class="card">
+  <div class="card-content">
+    <!-- Card content -->
+  </div>
+  
+  <div class="card-actions">
+    <ActionBar buttons={cardActions} gap={8} />
+  </div>
+</div>
+
+<style>
+  .card {
+    border: 1px solid #e0e0e0;
+    border-radius: 8px;
+    overflow: hidden;
+  }
+  
+  .card-content {
+    padding: 16px;
+  }
+  
+  .card-actions {
+    padding: 12px 16px;
+    background: #f8f9fa;
+    border-top: 1px solid #e0e0e0;
+  }
+</style>
+```
+
+## Best Practices
+
+### Use Separators to Group Actions
+
+Use `null` values as separators to organize related actions:
+
+```svelte
+<script lang="ts">
+  const editorActions: ButtonActions = [
+    // File operations group
+    { label: "New", icon: "icon_google_add", handler: newFile },
+    { label: "Open", icon: "icon_google_folder_open", handler: openFile },
+    { label: "Save", icon: "icon_google_save", handler: saveFile },
+    
+    null, // Separator
+    
+    // Edit operations group
+    { label: "Undo", icon: "icon_google_undo", handler: undo },
+    { label: "Redo", icon: "icon_google_redo", handler: redo },
+    
+    null, // Separator
+    
+    // Primary action
+    { label: "Publish", type: "primary", icon: "icon_google_publish", handler: publish }
+  ];
+</script>
+```
+
+### Use Appropriate Spacing
+
+Adjust button spacing based on interface density:
+
+```svelte
+<!-- Compact interface -->
+<ActionBar buttons={actions} gap={4} />
+
+<!-- Standard interface -->
+<ActionBar buttons={actions} gap={8} />
+
+<!-- Spacious interface -->
+<ActionBar buttons={actions} gap={16} />
+```
+
+### Responsive Design
+
+Consider hiding or simplifying actions on small screens:
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  
+  let isMobile = false;
+  
+  onMount(() => {
+    const checkMobile = () => {
+      isMobile = window.innerWidth < 768;
+    };
+    
+    checkMobile();
+    window.addEventListener('resize', checkMobile);
+    
+    return () => window.removeEventListener('resize', checkMobile);
+  });
+  
+  $: responsiveActions = isMobile 
+    ? [
+        { label: "Save", type: "primary", handler: save },
+        { label: "Cancel", type: "secondary", handler: cancel }
+      ]
+    : [
+        { label: "Reset", type: "default", handler: reset },
+        null,
+        { label: "Preview", type: "secondary", handler: preview },
+        { label: "Save", type: "primary", handler: save },
+        { label: "Cancel", type: "secondary", handler: cancel }
+      ];
+</script>
+
+<ActionBar buttons={responsiveActions} />
+```
+
+## Click Throttling
+
+All buttons in ActionBar implement automatic click throttling with a 500ms cooldown to prevent accidental double-clicks and ensure proper async operation handling.