@ticatec/uniface-element 0.3.23 → 5.0.0

package/dist/general/separator/README_CN.md

@@ -0,0 +1,203 @@
+# Separator 分隔线组件
+
+一条**竖直**分隔线 —— 固定 1px 宽，高度可控。专门放在 flex 行的子项之间做视觉分隔。
+
+> **不要用来画水平线。** 本组件渲染的是 1px 宽、N px 高的竖条。如果要在上下堆叠的区块之间画水平线，请用普通 `<div style="height: 1px; background: ..."></div>` 或 `<hr>`。
+
+## 功能特性
+
+- **竖直分隔**：固定 1px 宽，高度可配置
+- **主题令牌**：颜色由 `--uniface-separator-color` CSS 变量驱动
+- **便于覆盖**：`style` 属性追加在 `height` 之后，任何内联 CSS 都能盖掉默认值
+- **不扰动布局**：`position: relative`，在 flex/grid 父容器里很老实
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import Separator from '@ticatec/uniface-element/Separator';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Separator from '@ticatec/uniface-element/Separator';
+</script>
+
+<div style="display: flex; align-items: center; gap: 16px;">
+  <span>左侧</span>
+  <Separator />
+  <span>右侧</span>
+</div>
+```
+
+默认 `height="24px"`，所以是 1px 宽、24px 高的竖条。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `height` | `string` | `'24px'` | 分隔线的 CSS 高度值（如 `'24px'`、`'60px'`、`'100%'`） |
+| `style` | `string` | `undefined` | 额外的内联 CSS。追加在 `height` 之后，因此可以覆盖高度、颜色等 |
+
+## 事件
+
+无。
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="uniface-separator" style="height: 24px; {你的 style}"></div>
+```
+
+内置样式：
+
+```css
+.uniface-separator {
+  position: relative;
+  width: 1px;
+  background-color: var(--uniface-separator-color, #E2E8F0);
+}
+```
+
+### CSS 自定义属性
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `--uniface-separator-color` | `#E2E8F0` | 分隔线的背景色 |
+
+全局设置即可主题化所有 Separator；也可以局部作用域：
+
+```css
+:root {
+  --uniface-separator-color: #d1d5db;
+}
+
+/* 仅在深色工具栏内 */
+.dark-toolbar {
+  --uniface-separator-color: #475569;
+}
+```
+
+## 基本示例
+
+### 默认高度（24px）
+
+```svelte
+<div style="display: flex; align-items: center; gap: 16px;">
+  <span>A</span>
+  <Separator />
+  <span>B</span>
+</div>
+```
+
+### 自定义高度
+
+```svelte
+<div style="display: flex; align-items: center; gap: 16px; height: 80px;">
+  <span>项</span>
+  <Separator height="60px" />   <!-- 比行高短 -->
+  <span>项</span>
+  <Separator height="100%" />   <!-- 占满行高 -->
+  <span>项</span>
+</div>
+```
+
+### 自定义颜色
+
+```svelte
+<Separator style="background-color: #e53e3e;" />
+```
+
+或通过主题令牌：
+
+```svelte
+<div style="--uniface-separator-color: #e53e3e;">
+  <Separator />
+</div>
+```
+
+## 详细示例
+
+### 工具栏分隔
+
+最经典的用法：在工具栏的按钮组之间画分隔线。
+
+```svelte
+<script>
+  import Separator from '@ticatec/uniface-element/Separator';
+  import IconButton from '@ticatec/uniface-element/IconButton';
+</script>
+
+<div style="display: flex; align-items: center; gap: 8px; padding: 8px;">
+  <!-- 文件组 -->
+  <IconButton icon="icon_google_create_new_folder" />
+  <IconButton icon="icon_google_save" />
+  <IconButton icon="icon_google_open_in_new" />
+
+  <Separator />
+
+  <!-- 编辑组 -->
+  <IconButton icon="icon_google_content_copy" />
+  <IconButton icon="icon_google_content_paste" />
+  <IconButton icon="icon_google_content_cut" />
+
+  <Separator />
+
+  <!-- 危险组 -->
+  <IconButton icon="icon_google_delete" />
+</div>
+```
+
+### 页头布局
+
+把页头切成左右两区：
+
+```svelte
+<header style="display: flex; align-items: center; gap: 24px; height: 56px;">
+  <div class="brand">我的应用</div>
+  <Separator height="32px" />
+  <nav class="menu">...</nav>
+  <div style="flex: 1 1 auto;"></div>   <!-- 弹簧 -->
+  <Separator height="32px" />
+  <div class="user">你好，Henry</div>
+</header>
+```
+
+### 用 `style` 强行覆盖
+
+`style` 追加在 `height` 之后，所以后写的会赢 —— 可以覆盖高度、颜色，甚至宽度：
+
+```svelte
+<!-- 更高 + 红色 -->
+<Separator style="height: 48px; background-color: #ef4444;" />
+
+<!-- 虚线竖条 -->
+<Separator style="height: 100%; width: 0; border-left: 1px dashed #94a3b8; background: transparent;" />
+```
+
+## 最佳实践
+
+1. **用于水平排列的子项之间** —— 1px 宽就是为这个场景设计的
+2. **不要用于水平分割线** —— 上下堆叠的区块之间用 `<hr>` 或 1px 高的 `<div>`
+3. **同一工具栏/页头内高度保持一致**（统一 `24px` 或统一 `60%`）
+4. **颜色走 CSS 变量**而不是逐个 `style`，方便全局换肤
+
+## 无障碍访问
+
+- 纯装饰，没有交互语义
+- 外壳是 `<div>`，无 ARIA 属性，屏幕阅读器会忽略
+- 不要指望 Separator 单独表达区块边界，配合语义化标题或 `<section>` 使用
+
+## 相关组件
+
+- [Button](../button/README_CN.md) —— 标准按钮（工具栏里常和 Separator 搭配）
+- [IconButton](../button/IconButton_README_CN.md) —— 圆形图标按钮，工具栏里常见的 Separator 邻居

package/dist/general/separator/Separator.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+
+    interface Props {
+        height?: string;
+        style?: string;
+    }
+
+    let {
+        height = '24px',
+        style
+    }: Props = $props();
+
+</script>
+
+<div class="uniface-separator" style="height: {height}; {style};">
+
+</div>
+<style>
+    .uniface-separator {
+        position: relative;
+        width: 1px;
+        background-color: var(--uniface-separator-color, #E2E8F0);
+    }
+</style>

package/dist/general/separator/Separator.svelte.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    height?: string;
+    style?: string;
+}
+declare const Separator: import("svelte").Component<Props, {}, "">;
+type Separator = ReturnType<typeof Separator>;
+export default Separator;

package/dist/general/split/README.md

@@ -0,0 +1,312 @@
+# Split Component
+
+A draggable divider that resizes the panel you bind it to. Sits between two adjacent panels in a flex container; dragging the divider updates the bound panel's `width` or `height` inline style.
+
+> **Naming gotcha**: `direction` describes the **visual orientation of the divider bar**, not the layout direction of the panels.
+> - `direction="vertical"` → a *vertical bar* (1px wide, full height) → goes between **left/right** panels (flex row).
+> - `direction="horizontal"` → a *horizontal bar* (full width, 1px tall) → goes between **top/bottom** panels (flex column).
+
+## Features
+
+- **Drag-to-resize**: mouse-driven resizing of the bound panel
+- **Two orientations**: vertical bar (default) for left/right splits, horizontal bar for top/bottom splits
+- **Adjustable thickness**: `width` prop controls the bar's px thickness
+- **Reverse mode**: for when the bound panel is on the right/bottom of the divider
+- **Fixed mode**: omit `bindingPanel` to render a non-interactive visual divider
+- **Min size guard**: bound panel can't be dragged below 5px
+- **Theme token**: color via `--uniface-dividing-line-color`
+- **Cleanup on unmount**: in-flight drag is cancelled if the component is destroyed mid-drag
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import Split from '@ticatec/uniface-element/Split';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let leftPanel: HTMLElement;
+</script>
+
+<!-- Two side-by-side panels separated by a vertical bar -->
+<div style="display: flex; height: 300px;">
+  <div bind:this={leftPanel} style="flex: 0 0 200px; background: #f0f0f0;">
+    Left Panel
+  </div>
+  <Split bindingPanel={leftPanel} direction="vertical" />
+  <div style="flex: 1 1 auto; background: #e0e0e0;">
+    Right Panel
+  </div>
+</div>
+```
+
+Drag the bar; the left panel's width updates in real time. The right panel (with `flex: 1`) absorbs the remaining space.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `direction` | `'vertical' \| 'horizontal'` | `'vertical'` | Visual orientation of the bar. `vertical` = thin tall bar (for left/right splits); `horizontal` = thin wide bar (for top/bottom splits). |
+| `width` | `number` | `2` | Thickness of the bar in pixels |
+| `bindingPanel` | `HTMLElement \| undefined` | `undefined` | The panel to resize. Omit to render a fixed, non-draggable divider. |
+| `reverse` | `boolean` | `false` | Flip drag direction. Use when the bound panel sits to the **right/below** the divider (so dragging away from it grows it). |
+| `onResizeEnd` | `(size: number) => void` | `undefined` | Fired once when a drag ends; receives the bound panel's final `clientWidth` or `clientHeight` in px. Not fired for fixed dividers. |
+
+## Events
+
+| Event | Signature | Description |
+|-------|-----------|-------------|
+| `onResizeEnd` | `(size: number) => void` | Fired on `mouseup` after a drag. Useful for persisting the size. Not fired if the divider is fixed. |
+
+The component does **not** emit intermediate events during the drag — it mutates `bindingPanel.style.width` / `.height` directly on every `mousemove`.
+
+## Direction → Layout Cheat Sheet
+
+| You want… | Container | `direction` |
+|-----------|----------|-------------|
+| Left ↔ Right panels | `display: flex` (row) | `'vertical'` |
+| Top ↕ Bottom panels | `display: flex; flex-direction: column` | `'horizontal'` |
+
+## Basic Examples
+
+### Left / Right Split (vertical bar)
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let leftPanel: HTMLElement;
+</script>
+
+<div style="display: flex; height: 400px;">
+  <div bind:this={leftPanel} style="flex: 0 0 250px; padding: 16px; background: #f5f5f5;">
+    <h3>Left</h3>
+    <p>Drag the bar to resize me.</p>
+  </div>
+
+  <Split bindingPanel={leftPanel} direction="vertical" width={4} />
+
+  <div style="flex: 1 1 auto; padding: 16px; background: #e8e8e8;">
+    <h3>Right</h3>
+    <p>I absorb the remaining space.</p>
+  </div>
+</div>
+```
+
+### Top / Bottom Split (horizontal bar)
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let topPanel: HTMLElement;
+</script>
+
+<div style="display: flex; flex-direction: column; height: 400px;">
+  <div bind:this={topPanel} style="flex: 0 0 150px; padding: 16px; background: #f5f5f5;">
+    <h3>Top</h3>
+  </div>
+
+  <Split bindingPanel={topPanel} direction="horizontal" width={4} />
+
+  <div style="flex: 1 1 auto; padding: 16px; background: #e8e8e8;">
+    <h3>Bottom</h3>
+  </div>
+</div>
+```
+
+### Persisting Size
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let sidebar: HTMLElement;
+  let savedWidth = $state(250);
+
+  async function persist(width: number) {
+    savedWidth = width;
+    await fetch('/api/prefs', { method: 'POST', body: JSON.stringify({ sidebarWidth: width }) });
+  }
+</script>
+
+<div style="display: flex; height: 100vh;">
+  <div bind:this={sidebar} style="flex: 0 0 {savedWidth}px; ...">Sidebar</div>
+  <Split bindingPanel={sidebar} direction="vertical" onResizeEnd={persist} />
+  <div style="flex: 1 1 auto;">Main</div>
+</div>
+```
+
+## Detailed Examples
+
+### Resizing the *Right* Panel (reverse mode)
+
+By default the bound panel is to the **left** of the divider (drag right = grow). If the bound panel is to the **right**, use `reverse`:
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let rightPanel: HTMLElement;
+</script>
+
+<div style="display: flex; height: 300px;">
+  <div style="flex: 1 1 auto; background: #e0e0e0;">Left (absorbs remainder)</div>
+
+  <Split bindingPanel={rightPanel} direction="vertical" reverse onResizeEnd={(w) => console.log('right width:', w)} />
+
+  <div bind:this={rightPanel} style="flex: 0 0 200px; background: #f0f0f0;">Right</div>
+</div>
+```
+
+### Three-Pane IDE Layout
+
+Sidebar | Editor | Details, all resizable. Two dividers, both bound to the panel on their **left**:
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let sidebar: HTMLElement;
+  let editor: HTMLElement;
+</script>
+
+<div style="display: flex; height: 100vh;">
+  <div bind:this={sidebar} style="flex: 0 0 220px; background: #1e293b; color: #e2e8f0;">
+    Sidebar
+  </div>
+
+  <Split bindingPanel={sidebar} direction="vertical" width={4} />
+
+  <div bind:this={editor} style="flex: 1 1 0; background: #0f172a; color: #e2e8f0;">
+    Editor
+  </div>
+
+  <Split bindingPanel={editor} direction="vertical" width={4} />
+
+  <div style="flex: 0 0 320px; background: #111827; color: #e2e8f0;">
+    Details
+  </div>
+</div>
+```
+
+`reverse` is not needed here because both bound panels (`sidebar`, `editor`) are to the **left** of their respective dividers. Use `reverse` only when the bound panel is on the right/bottom.
+
+### Fixed (Non-Resizable) Divider
+
+Omit `bindingPanel`:
+
+```svelte
+<div style="display: flex; height: 300px;">
+  <div style="flex: 1 1 auto; background: #f0f0f0;">Panel 1</div>
+  <Split direction="vertical" width={1} />   <!-- fixed: no bindingPanel -->
+  <div style="flex: 1 1 auto; background: #e0e0e0;">Panel 2</div>
+</div>
+```
+
+Fixed dividers get the `fixed` class → `pointer-events: none; cursor: default`. The hover/active states are also suppressed.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div
+  class="uniface-divider {direction}"     <!-- + 'fixed' if no bindingPanel -->
+  class:fixed
+  style="height: 2px" or "width: 2px"     <!-- depends on direction -->
+  role="separator"
+  aria-orientation="{direction}"
+  aria-label="Resize handle"
+  tabindex="0"
+  onmousedown={startDrag}
+/>
+```
+
+Built-in styles:
+
+```css
+.uniface-divider {
+  background-color: var(--uniface-dividing-line-color, #CBD5E1);
+  flex: 0 0 auto;          /* don't grow or shrink */
+  transition: background-color 0.2s ease;
+}
+
+.uniface-divider.vertical {
+  height: 100%;
+  cursor: col-resize;
+}
+
+.uniface-divider.horizontal {
+  width: 100%;
+  cursor: row-resize;
+}
+
+.uniface-divider.fixed {
+  cursor: default;
+  pointer-events: none;
+}
+
+.uniface-divider:hover {
+  /* darken 20% via color-mix */
+  background-color: color-mix(in srgb, var(--uniface-dividing-line-color, #CBD5E1) 80%, #000);
+}
+
+.uniface-divider:active {
+  transition: none;        /* no animation lag during drag */
+}
+```
+
+### CSS Custom Properties
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--uniface-dividing-line-color` | `#CBD5E1` | Background color of the bar (hover state darkens it 20%) |
+
+```css
+:root {
+  --uniface-dividing-line-color: #d4d4d8;
+}
+.dark-theme {
+  --uniface-dividing-line-color: #3f3f46;
+}
+```
+
+## Behavior Notes
+
+- **Mouse only.** The drag uses `mousedown` / `mousemove` / `mouseup`. Touch events are not handled — on touch devices the divider will not respond to finger drags.
+- **Min size**: bound panel clamped to ≥5px (won't collapse to zero).
+- **Document-level listeners**: `mousemove` and `mouseup` are attached to `document` during a drag, so the cursor can wander outside the bar without losing the grab.
+- **Body cursor override**: `document.body.style.cursor` is set to `col-resize` / `row-resize` during the drag and reset on `mouseup`.
+- **Cleanup**: if the component is destroyed mid-drag, `onDestroy` calls `stopDrag` to remove listeners and reset the cursor.
+- **Direct style mutation**: the bound panel's `style.width` or `style.height` is written directly — no React-style state round-trip. This keeps dragging smooth even with heavy panel contents.
+- **No resize-start event**: there's `onResizeEnd` only. If you need to track live sizing, attach a `ResizeObserver` to the bound panel yourself.
+
+## Accessibility
+
+- `role="separator"`, `aria-orientation`, `aria-label="Resize handle"`, `tabindex="0"` are set on the divider.
+- **Keyboard support is partial**: the divider is focusable but the component does **not** handle arrow-key events. Dragging requires a mouse. If you need keyboard resizing, layer your own `keydown` handler on a wrapping element.
+- For fixed dividers, consider `aria-disabled="true"` if the visual still looks interactive.
+
+## Best Practices
+
+1. **`bind:this` the panel** — `bindingPanel` needs a real DOM reference, not a CSS selector.
+2. **Match `direction` to your flex layout** — vertical bar for `flex-direction: row`, horizontal bar for `flex-direction: column`.
+3. **Use `reverse` when the bound panel is on the far side** of the divider (right of a vertical bar / below a horizontal bar).
+4. **Give the absorbent panel `flex: 1 1 auto`** so it takes up the slack as the bound panel grows/shrinks.
+5. **Persist via `onResizeEnd`**, not on every drag frame (avoid `onResize`-style intermediate callbacks — they aren't emitted anyway).
+6. **For non-resizable visual gaps, omit `bindingPanel`** rather than disabling a bound divider.
+
+## Related Components
+
+- [Separator](../separator/README.md) — pure-decoration 1px vertical line (non-interactive)