@ticatec/topside-elements 1.0.0

package/dist/layouts/action_bar/ActionBar.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+    import type {Snippet} from 'svelte';
+    import type {ButtonAction, ButtonActions} from '../../types';
+    import Button from "../../general/button";
+    import Separator from "../../general/separator";
+
+
+    interface Props {
+        /** 动作按钮列表，null 为分隔符 */
+        actions?: ButtonActions;
+        style?: string;
+        theme?: string;
+        children?: Snippet;
+    }
+
+    let {
+        actions = [],
+        style,
+        theme,
+        children
+    }: Props = $props();
+
+    const handleButtonClick = (button: ButtonAction) => {
+        return (event: MouseEvent) => {
+            button.handler?.(event);
+        };
+    };
+</script>
+
+<div class="topside-action-bar" {style} data-theme={theme}>
+    {#if children}
+        {@render children()}
+    {:else if actions}
+        {#each actions as button}
+            {#if button}
+                <Button
+                        label={button.label}
+                        icon={button.icon}
+                        tooltip={button.tooltip}
+                        disabled={button.disabled === true}
+                        type={button.type}
+                        onclick={handleButtonClick(button)}
+                />
+            {:else}
+                <Separator height="24px"/>
+            {/if}
+        {/each}
+    {/if}
+</div>
+
+<style>
+    .topside-action-bar {
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        justify-content: center;
+        width: fit-content;
+        gap: var(--topside-spacing-actionbar);
+    }
+</style>

package/dist/layouts/action_bar/ActionBar.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+import type { ButtonActions } from '../../types';
+interface Props {
+    /** 动作按钮列表，null 为分隔符 */
+    actions?: ButtonActions;
+    style?: string;
+    theme?: string;
+    children?: Snippet;
+}
+declare const ActionBar: import("svelte").Component<Props, {}, "">;
+type ActionBar = ReturnType<typeof ActionBar>;
+export default ActionBar;

package/dist/layouts/action_bar/ButtonAction.d.ts

@@ -0,0 +1 @@
+export type { ButtonAction, ButtonActions } from "../../types";

package/dist/layouts/action_bar/ButtonAction.js

@@ -0,0 +1 @@
+export {};

package/dist/layouts/action_bar/README.md

@@ -0,0 +1,304 @@
+# ActionBar Component
+
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `buttons` were removed in 5.1.0 (no compatibility aliases are kept).
+
+A horizontal row of action buttons, declared via a `actions` array (or a custom snippet). Use `null` entries in the array to drop a vertical separator between button groups.
+
+Built on top of [Button](../../general/button/README.md) and [Separator](../../general/separator/README.md).
+
+## Features
+
+- **Data-driven buttons**: declare actions as `ButtonAction[]`, the bar renders them
+- **Implicit separators**: `null` in the array → 24px-tall vertical Separator between groups
+- **Or snippet content**: pass children for full custom layout (overrides `actions` when both are set)
+- **Disabled per button**: `ButtonAction.disabled` flows through to the underlying Button
+- **All ButtonType variants**: `default` / `primary` / `secondary` / `third` / `forth`
+- **Tooltips**: `ButtonAction.tooltip` is forwarded as `data-tip` to Button
+- **Theme hook**: outer wrapper exposes `data-theme="{theme}"`
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import ActionBar, { type ButtonAction, type ButtonActions } from '@ticatec/topside-elements/ActionBar';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import ActionBar, { type ButtonAction } from '@ticatec/topside-elements/ActionBar';
+
+  const actions: (ButtonAction | null)[] = [
+    {
+      label: 'Save',
+      type: 'primary',
+      icon: 'icon_google_save',
+      handler: () => console.log('Save clicked')
+    },
+    {
+      label: 'Cancel',
+      type: 'secondary',
+      handler: () => console.log('Cancel clicked')
+    }
+  ];
+</script>
+
+<ActionBar actions={actions} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `actions` | `ButtonActions` (`Array<ButtonAction \| null>`) | `[]` | Declarative button list. `null` entries render as a vertical Separator. Ignored when `children` is provided. |
+| `style` | `string \| undefined` | `undefined` | Inline CSS on the outer wrapper |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper for scoped CSS overrides |
+| `children` | `Snippet \| undefined` | `undefined` | Custom content. **Takes precedence over `actions`** when both are provided. |
+
+> **Children precedence**: if you pass both `actions` and inline children, only the children render. The `actions` array is silently ignored.
+
+## ButtonAction
+
+```ts
+interface ButtonAction {
+  label: string;                    // Button text (required)
+  disabled?: boolean;               // Forwarded to Button.disabled
+  icon?: string;                    // Icon font class, rendered before label
+  type?: 'default' | 'primary' | 'secondary' | 'third' | 'forth';
+  tooltip?: string;                 // Forwarded to Button.tooltip (becomes data-tip)
+  handler?: (event: MouseEvent) => void;
+}
+
+type ButtonActions = Array<ButtonAction | null>;
+```
+
+`null` entries are not "missing buttons to filter out" — they are **explicit separators**. Don't `.filter(Boolean)` the array unless you actually want to strip the dividers.
+
+## Layout Defaults (Important)
+
+The outer `<div>` has:
+
+```css
+.topside-action-bar {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: center;   /* ← centered, not left/right */
+  width: fit-content;        /* ← shrinks to content, does NOT fill parent */
+  gap: var(--topside-spacing-actionbar);
+}
+```
+
+Two consequences:
+
+1. **The bar doesn't fill its container.** It's only as wide as the buttons. To get a full-width bar, override: `style="width: 100%;"`.
+2. **Buttons are centered.** For right-aligned form actions (Save / Cancel in a dialog footer), use `style="justify-content: flex-end; width: 100%;"`.
+
+## Examples
+
+### Basic
+
+```svelte
+<script>
+  const basicActions = [
+    { label: 'New',                       handler: createNew },
+    { label: 'Edit',                      handler: editItem },
+    { label: 'Delete', type: 'secondary', handler: deleteItem }
+  ];
+</script>
+
+<ActionBar actions={basicActions} />
+```
+
+### With Icons + Tooltips
+
+```svelte
+<script>
+  const iconActions = [
+    {
+      label: 'Save',
+      icon: 'icon_google_save',
+      type: 'primary',
+      tooltip: 'Save your changes (Ctrl+S)',
+      handler: save
+    },
+    {
+      label: 'Print',
+      icon: 'icon_google_print',
+      tooltip: 'Print document',
+      handler: print
+    }
+  ];
+</script>
+
+<ActionBar actions={iconActions} />
+```
+
+### With Separators Between Groups
+
+```svelte
+<script>
+  const actions = [
+    { label: 'Copy',  handler: copy },
+    { label: 'Paste', handler: paste },
+    null,                                        // ← renders <Separator>
+    { label: 'Delete', type: 'secondary', handler: remove }
+  ];
+</script>
+
+<ActionBar actions={actions} />
+```
+
+### Form Footer (Right-Aligned, Full-Width)
+
+```svelte
+<ActionBar
+  actions={[
+    { label: 'Save',   type: 'primary', handler: submit },
+    { label: 'Cancel',                  handler: cancel }
+  ]}
+  style="justify-content: flex-end; width: 100%; margin-top: 16px;"
+/>
+```
+
+### CRUD Toolbar
+
+```svelte
+<ActionBar actions={[
+  { label: 'Create', type: 'primary', handler: create },
+  { label: 'Edit',                    handler: edit },
+  { label: 'Delete', type: 'secondary', handler: remove },
+  null,
+  { label: 'Refresh', handler: refresh }
+]} />
+```
+
+### Custom Content (Snippet)
+
+Bypass `actions` entirely and render arbitrary content:
+
+```svelte
+<ActionBar>
+  <Button label="Custom"  type="primary" onclick={...} />
+  <Button label="Actions" type="secondary" onclick={...} />
+  <MyDropdown />
+</ActionBar>
+```
+
+(Content between the tags becomes the `children` snippet in Svelte 5 — no need for explicit `{#snippet}`.)
+
+### Dynamic Actions (Svelte 5 runes)
+
+```svelte
+<script lang="ts">
+  import ActionBar, { type ButtonAction } from '@ticatec/topside-elements/ActionBar';
+
+  let isEditing = $state(false);
+
+  const actions = $derived<(ButtonAction | null)[]>(
+    isEditing
+      ? [
+          { label: 'Save',   type: 'primary', handler: save },
+          { label: 'Cancel',                 handler: cancel }
+        ]
+      : [
+          { label: 'Edit',                   handler: startEdit },
+          { label: 'Delete', type: 'secondary', handler: remove }
+        ]
+  );
+</script>
+
+<ActionBar actions={actions} />
+```
+
+### Conditional Buttons (preserve separators)
+
+To conditionally show a button without dropping your separators, branch *inside* the entry — don't `.filter(Boolean)` the whole array or you'll strip the `null` dividers:
+
+```svelte
+<script lang="ts">
+  let hasPermission = $state(true);
+  let isLoading = $state(false);
+
+  // ✅ Keep nulls; only the conditional button toggles to null when missing.
+  const actions = $derived<(ButtonAction | null)[]>([
+    { label: 'Refresh', handler: refresh },
+    hasPermission
+      ? { label: 'Save',   type: 'primary',    disabled: isLoading, handler: save }
+      : null,
+    hasPermission
+      ? { label: 'Delete', type: 'secondary',  disabled: isLoading, handler: remove }
+      : null
+  ]);
+</script>
+
+<ActionBar actions={actions} />
+```
+
+> Note: if you want a "missing button" to render as *nothing* rather than a separator, wrap the whole ActionBar in your own `{#if}` instead.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="topside-action-bar" style="..." data-theme="...">
+  <!-- children OR actions: -->
+  <Button label="..." icon="..." tooltip="..." type="..." disabled={...} />
+  <div class="topside-separator" style="height: 24px;"></div>   <!-- null entry -->
+  <Button ... />
+</div>
+```
+
+### CSS Variable
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--topside-spacing-actionbar` | (from theme) | Gap between actions (and between button and separator) |
+
+Override globally:
+
+```css
+:root {
+  --topside-spacing-actionbar: 8px;
+}
+```
+
+### Per-instance Styling
+
+```svelte
+<!-- Left-aligned, full-width, with padding -->
+<ActionBar
+  actions={actions}
+  style="justify-content: flex-start; width: 100%; padding: 8px 12px; background: #f9fafb;"
+/>
+```
+
+## Accessibility
+
+The ActionBar itself is a plain `<div>` — semantics come from the rendered `<button>` elements inside:
+
+- Each action renders as a real `<button>`, so Tab / Shift+Tab / Enter / Space all work natively.
+- `ButtonAction.disabled={true}` propagates to `<button disabled>` and `tabindex="-1"`, removing it from the tab order.
+- The visible focus ring comes from Button's `:focus-visible` box-shadow.
+- The outer wrapper has no `role` — it's a presentational container.
+
+## Best Practices
+
+1. **Use `null` deliberately** for group separators; don't `.filter(Boolean)` the array unless you mean to strip them.
+2. **Override `justify-content` and `width`** when the centered + fit-content default doesn't fit (form footers, left-aligned toolbars).
+3. **Pick the right `type`**: `primary` for the main action, `secondary` for neutral/destructive, leave default for tertiary.
+4. **Disable, don't hide, during async work** so the user sees that the action exists but is temporarily unavailable (unless permissions say otherwise).
+5. **Prefer `actions` over snippet content** for data-driven toolbars — it's serialisable and easier to test.
+6. **Keep the array small**; for >8 actions, consider a dropdown menu instead of a wide action bar.
+
+## Related Components
+
+- [Button](../../general/button/README.md) — the underlying button rendered for each action
+- [Separator](../../general/separator/README.md) — the vertical divider used for `null` entries

package/dist/layouts/action_bar/README_CN.md

@@ -0,0 +1,304 @@
+# ActionBar 操作栏组件
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `buttons` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+一行水平排列的操作按钮，通过 `actions` 数组声明（或用 snippet 自定义）。数组里写 `null` 会在按钮组之间渲染一条竖直分隔线。
+
+基于 [Button](../../general/button/README_CN.md) 和 [Separator](../../general/separator/README_CN.md) 构建。
+
+## 功能特性
+
+- **数据驱动**：把操作声明为 `ButtonAction[]`，bar 自动渲染
+- **隐式分隔符**：数组里的 `null` → 24px 高的竖直 Separator
+- **或 snippet 内容**：传 children 做完全自定义布局（同时传 `actions` 和 children 时 children 优先）
+- **单按钮禁用**：`ButtonAction.disabled` 透传到底层 Button
+- **全部 ButtonType**：`default` / `primary` / `secondary` / `third` / `forth`
+- **tooltip**：`ButtonAction.tooltip` 以 `data-tip` 形式透传给 Button
+- **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import ActionBar, { type ButtonAction, type ButtonActions } from '@ticatec/topside-elements/ActionBar';
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import ActionBar, { type ButtonAction } from '@ticatec/topside-elements/ActionBar';
+
+  const actions: (ButtonAction | null)[] = [
+    {
+      label: '保存',
+      type: 'primary',
+      icon: 'icon_google_save',
+      handler: () => console.log('保存被点击')
+    },
+    {
+      label: '取消',
+      type: 'secondary',
+      handler: () => console.log('取消被点击')
+    }
+  ];
+</script>
+
+<ActionBar actions={actions} />
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `actions` | `ButtonActions`（`Array<ButtonAction \| null>`） | `[]` | 声明式按钮列表。`null` 项渲染为一条竖直 Separator。提供 `children` 时本字段被忽略 |
+| `style` | `string \| undefined` | `undefined` | 外层 wrapper 的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme`，便于作用域化 CSS 覆盖 |
+| `children` | `Snippet \| undefined` | `undefined` | 自定义内容。**同时提供 `actions` 时 children 优先** |
+
+> **children 优先**：同时传了 `actions` 和内联 children，只会渲染 children，`actions` 数组被静默忽略。
+
+## ButtonAction
+
+```ts
+interface ButtonAction {
+  label: string;                    // 按钮文字（必填）
+  disabled?: boolean;               // 透传给 Button.disabled
+  icon?: string;                    // 图标字体类名，渲染在文字之前
+  type?: 'default' | 'primary' | 'secondary' | 'third' | 'forth';
+  tooltip?: string;                 // 透传给 Button.tooltip（变成 data-tip）
+  handler?: (event: MouseEvent) => void;
+}
+
+type ButtonActions = Array<ButtonAction | null>;
+```
+
+`null` 项不是"待过滤的空位"，而是**显式的分隔符**。不要对整个数组 `.filter(Boolean)`，否则会把分隔符一起删掉。
+
+## 默认布局（重要）
+
+外层 `<div>` 的样式：
+
+```css
+.topside-action-bar {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: center;   /* ← 居中，不是左/右对齐 */
+  width: fit-content;        /* ← 缩到内容宽度，不会撑满父容器 */
+  gap: var(--topside-spacing-actionbar);
+}
+```
+
+两个后果：
+
+1. **bar 不会撑满父容器**，宽度只够装下按钮。要全宽 bar 必须覆盖：`style="width: 100%;"`
+2. **按钮居中**。表单底部的右对齐按钮组（对话框里的 Save / Cancel）要用 `style="justify-content: flex-end; width: 100%;"`
+
+## 示例
+
+### 基础
+
+```svelte
+<script>
+  const basicActions = [
+    { label: '新建',                       handler: createNew },
+    { label: '编辑',                       handler: editItem },
+    { label: '删除', type: 'secondary',    handler: deleteItem }
+  ];
+</script>
+
+<ActionBar actions={basicActions} />
+```
+
+### 带图标 + tooltip
+
+```svelte
+<script>
+  const iconActions = [
+    {
+      label: '保存',
+      icon: 'icon_google_save',
+      type: 'primary',
+      tooltip: '保存更改 (Ctrl+S)',
+      handler: save
+    },
+    {
+      label: '打印',
+      icon: 'icon_google_print',
+      tooltip: '打印文档',
+      handler: print
+    }
+  ];
+</script>
+
+<ActionBar actions={iconActions} />
+```
+
+### 组间加分隔符
+
+```svelte
+<script>
+  const actions = [
+    { label: '复制',  handler: copy },
+    { label: '粘贴',  handler: paste },
+    null,                                        // ← 渲染 <Separator>
+    { label: '删除', type: 'secondary', handler: remove }
+  ];
+</script>
+
+<ActionBar actions={actions} />
+```
+
+### 表单底部（右对齐 + 全宽）
+
+```svelte
+<ActionBar
+  actions={[
+    { label: '保存', type: 'primary', handler: submit },
+    { label: '取消',                  handler: cancel }
+  ]}
+  style="justify-content: flex-end; width: 100%; margin-top: 16px;"
+/>
+```
+
+### CRUD 工具栏
+
+```svelte
+<ActionBar actions={[
+  { label: '创建', type: 'primary', handler: create },
+  { label: '编辑',                  handler: edit },
+  { label: '删除', type: 'secondary', handler: remove },
+  null,
+  { label: '刷新', handler: refresh }
+]} />
+```
+
+### 自定义内容（snippet）
+
+完全绕开 `actions`，渲染任意内容：
+
+```svelte
+<ActionBar>
+  <Button label="自定义"  type="primary"   onclick={...} />
+  <Button label="操作"    type="secondary" onclick={...} />
+  <MyDropdown />
+</ActionBar>
+```
+
+（标签之间的内容会自动成为 Svelte 5 的 `children` snippet，不需要显式 `{#snippet}`。）
+
+### 动态操作（Svelte 5 runes）
+
+```svelte
+<script lang="ts">
+  import ActionBar, { type ButtonAction } from '@ticatec/topside-elements/ActionBar';
+
+  let isEditing = $state(false);
+
+  const actions = $derived<(ButtonAction | null)[]>(
+    isEditing
+      ? [
+          { label: '保存', type: 'primary', handler: save },
+          { label: '取消',                 handler: cancel }
+        ]
+      : [
+          { label: '编辑',                 handler: startEdit },
+          { label: '删除', type: 'secondary', handler: remove }
+        ]
+  );
+</script>
+
+<ActionBar actions={actions} />
+```
+
+### 条件按钮（保留分隔符）
+
+要条件性地显示某个按钮、又不破坏分隔符：在数组项**内部**做三元判断 —— 不要对整个数组 `.filter(Boolean)`，否则 `null` 分隔符会被一起删掉：
+
+```svelte
+<script lang="ts">
+  let hasPermission = $state(true);
+  let isLoading = $state(false);
+
+  // ✅ 保留 null；条件不满足时只是那一个按钮变 null
+  const actions = $derived<(ButtonAction | null)[]>([
+    { label: '刷新', handler: refresh },
+    hasPermission
+      ? { label: '保存', type: 'primary',    disabled: isLoading, handler: save }
+      : null,
+    hasPermission
+      ? { label: '删除', type: 'secondary',  disabled: isLoading, handler: remove }
+      : null
+  ]);
+</script>
+
+<ActionBar actions={actions} />
+```
+
+> 注意：如果想让"按钮不显示"渲染为**完全空白**而不是分隔符，自己在外面套 `{#if}` 控制是否渲染整个 ActionBar。
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="topside-action-bar" style="..." data-theme="...">
+  <!-- children 或 actions： -->
+  <Button label="..." icon="..." tooltip="..." type="..." disabled={...} />
+  <div class="topside-separator" style="height: 24px;"></div>   <!-- null 项 -->
+  <Button ... />
+</div>
+```
+
+### CSS 变量
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `--topside-spacing-actionbar` | （来自主题） | 按钮之间、按钮与分隔符之间的间距 |
+
+全局覆盖：
+
+```css
+:root {
+  --topside-spacing-actionbar: 8px;
+}
+```
+
+### 单实例样式
+
+```svelte
+<!-- 左对齐 + 全宽 + padding -->
+<ActionBar
+  actions={actions}
+  style="justify-content: flex-start; width: 100%; padding: 8px 12px; background: #f9fafb;"
+/>
+```
+
+## 无障碍访问
+
+ActionBar 本身是普通 `<div>` —— 语义来自内部渲染的 `<button>` 元素：
+
+- 每个操作渲染为真正的 `<button>`，Tab / Shift+Tab / Enter / Space 全部原生支持
+- `ButtonAction.disabled={true}` 透传到 `<button disabled>` 和 `tabindex="-1"`，从 Tab 序列移除
+- 可见焦点环来自 Button 的 `:focus-visible` box-shadow
+- 外层 wrapper 无 `role` —— 是纯表现层容器
+
+## 最佳实践
+
+1. **`null` 是显式分隔符**，不要无脑 `.filter(Boolean)` 把它一起删了
+2. **居中 + fit-content 默认不合适时覆盖 `justify-content` 和 `width`**（表单底部、左对齐工具栏）
+3. **`type` 用对**：主操作 `primary`，中性/危险 `secondary`，再次要的不写
+4. **异步期间 disable 而不是 hide**，让用户看到"操作存在但暂时不可用"（权限场景除外）
+5. **数据驱动工具栏优先用 `actions`**，可序列化、好测试
+6. **数组别太长**，超过 8 个操作考虑改成下拉菜单
+
+## 相关组件
+
+- [Button](../../general/button/README_CN.md) —— 每个操作渲染的底层按钮
+- [Separator](../../general/separator/README_CN.md) —— `null` 项渲染的竖直分隔线

package/dist/layouts/action_bar/index.d.ts

@@ -0,0 +1,5 @@
+import ActionBar from "./ActionBar.svelte";
+import type { ButtonActions } from "../../types";
+import type { ButtonAction } from "./ButtonAction";
+export default ActionBar;
+export type { ButtonActions, ButtonAction };

package/dist/layouts/action_bar/index.js

@@ -0,0 +1,2 @@
+import ActionBar from "./ActionBar.svelte";
+export default ActionBar;