@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/general/split/README_CN.md

@@ -0,0 +1,312 @@
+# Split 分割器组件
+
+一个可拖动的分隔条，用来调整绑定的那个面板的尺寸。放在 flex 容器里两个相邻面板之间，拖动会直接改写绑定面板的 `width` 或 `height` 内联样式。
+
+> **命名陷阱**：`direction` 描述的是**分隔条本身的视觉朝向**，不是面板的排布方向。
+> - `direction="vertical"` → 一根**竖条**（1px 宽，整高）→ 放在**左右**面板之间（flex row）。
+> - `direction="horizontal"` → 一根**横条**（整宽，1px 高）→ 放在**上下**面板之间（flex column）。
+
+## 功能特性
+
+- **拖拽调整**：鼠标拖动改变绑定面板尺寸
+- **两个方向**：竖条（默认，用于左右分栏）或横条（用于上下分栏）
+- **可调粗细**：`width` 属性控制条的像素厚度
+- **反向模式**：当绑定面板在分隔条的右侧/下方时使用
+- **固定模式**：省略 `bindingPanel` 即渲染为不可交互的视觉分隔条
+- **最小尺寸保护**：绑定面板不会被拖到 5px 以下
+- **主题令牌**：颜色由 `--uniface-dividing-line-color` 驱动
+- **销毁时清理**：组件在拖动过程中被销毁会自动取消拖动
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import Split from '@ticatec/uniface-element/Split';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let leftPanel: HTMLElement;
+</script>
+
+<!-- 两个左右面板，中间一根竖条 -->
+<div style="display: flex; height: 300px;">
+  <div bind:this={leftPanel} style="flex: 0 0 200px; background: #f0f0f0;">
+    左侧面板
+  </div>
+  <Split bindingPanel={leftPanel} direction="vertical" />
+  <div style="flex: 1 1 auto; background: #e0e0e0;">
+    右侧面板
+  </div>
+</div>
+```
+
+拖动分隔条，左侧面板的宽度实时变化。右侧面板（`flex: 1`）吸收剩余空间。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `direction` | `'vertical' \| 'horizontal'` | `'vertical'` | 分隔条的视觉朝向。`vertical` = 细高竖条（用于左右分栏）；`horizontal` = 细宽横条（用于上下分栏） |
+| `width` | `number` | `2` | 分隔条的像素厚度 |
+| `bindingPanel` | `HTMLElement \| undefined` | `undefined` | 要调整尺寸的面板。省略则渲染为固定不可拖的分隔条 |
+| `reverse` | `boolean` | `false` | 反转拖动方向。绑定面板在分隔条**右侧/下方**时使用（向远离面板的方向拖动使其变大） |
+| `onResizeEnd` | `(size: number) => void` | `undefined` | 一次拖动结束时触发一次，参数是绑定面板最终的 `clientWidth` 或 `clientHeight`（像素）。固定分隔条不会触发 |
+
+## 事件
+
+| 事件 | 签名 | 描述 |
+|------|------|------|
+| `onResizeEnd` | `(size: number) => void` | 拖动 `mouseup` 后触发，适合持久化尺寸。固定分隔条不触发 |
+
+组件**不**在拖动过程中发送中间事件 —— 每帧直接改写 `bindingPanel.style.width` / `.height`。
+
+## 方向 → 布局 对照表
+
+| 想要的效果 | 容器 | `direction` |
+|-----------|------|-------------|
+| 左 ↔ 右 面板 | `display: flex`（row） | `'vertical'` |
+| 上 ↕ 下 面板 | `display: flex; flex-direction: column` | `'horizontal'` |
+
+## 基本示例
+
+### 左右分栏（竖条）
+
+```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>左侧</h3>
+    <p>拖动中间的条调整我的宽度。</p>
+  </div>
+
+  <Split bindingPanel={leftPanel} direction="vertical" width={4} />
+
+  <div style="flex: 1 1 auto; padding: 16px; background: #e8e8e8;">
+    <h3>右侧</h3>
+    <p>我吸收剩余空间。</p>
+  </div>
+</div>
+```
+
+### 上下分栏（横条）
+
+```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>顶部</h3>
+  </div>
+
+  <Split bindingPanel={topPanel} direction="horizontal" width={4} />
+
+  <div style="flex: 1 1 auto; padding: 16px; background: #e8e8e8;">
+    <h3>底部</h3>
+  </div>
+</div>
+```
+
+### 持久化尺寸
+
+```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; ...">侧边栏</div>
+  <Split bindingPanel={sidebar} direction="vertical" onResizeEnd={persist} />
+  <div style="flex: 1 1 auto;">主内容</div>
+</div>
+```
+
+## 详细示例
+
+### 调整右侧面板尺寸（reverse 模式）
+
+默认情况下绑定面板在分隔条**左侧**（向右拖 = 变大）。如果绑定面板在**右侧**，用 `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;">左侧（吸收剩余空间）</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;">右侧</div>
+</div>
+```
+
+### 三栏 IDE 布局
+
+侧边栏 | 编辑器 | 详情，所有都可调。两根分隔条，都绑定左侧面板：
+
+```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;">
+    侧边栏
+  </div>
+
+  <Split bindingPanel={sidebar} direction="vertical" width={4} />
+
+  <div bind:this={editor} style="flex: 1 1 0; background: #0f172a; color: #e2e8f0;">
+    编辑器
+  </div>
+
+  <Split bindingPanel={editor} direction="vertical" width={4} />
+
+  <div style="flex: 0 0 320px; background: #111827; color: #e2e8f0;">
+    详情
+  </div>
+</div>
+```
+
+这里**不需要** `reverse`，因为两个绑定面板（`sidebar`、`editor`）都在各自分隔条的**左侧**。只有绑定面板在右侧/下方时才用 `reverse`。
+
+### 固定分隔条（不可拖动）
+
+省略 `bindingPanel`：
+
+```svelte
+<div style="display: flex; height: 300px;">
+  <div style="flex: 1 1 auto; background: #f0f0f0;">面板 1</div>
+  <Split direction="vertical" width={1} />   <!-- 固定：无 bindingPanel -->
+  <div style="flex: 1 1 auto; background: #e0e0e0;">面板 2</div>
+</div>
+```
+
+固定分隔条会加 `fixed` 类 → `pointer-events: none; cursor: default`，hover/active 状态也会失效。
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div
+  class="uniface-divider {direction}"     <!-- 无 bindingPanel 时再加 'fixed' -->
+  class:fixed
+  style="height: 2px" 或 "width: 2px"     <!-- 取决于 direction -->
+  role="separator"
+  aria-orientation="{direction}"
+  aria-label="Resize handle"
+  tabindex="0"
+  onmousedown={startDrag}
+/>
+```
+
+内置样式：
+
+```css
+.uniface-divider {
+  background-color: var(--uniface-dividing-line-color, #CBD5E1);
+  flex: 0 0 auto;          /* 不膨胀不收缩 */
+  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 {
+  /* color-mix 加深 20% */
+  background-color: color-mix(in srgb, var(--uniface-dividing-line-color, #CBD5E1) 80%, #000);
+}
+
+.uniface-divider:active {
+  transition: none;        /* 拖动时无动画延迟 */
+}
+```
+
+### CSS 自定义属性
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `--uniface-dividing-line-color` | `#CBD5E1` | 分隔条背景色（hover 时自动加深 20%） |
+
+```css
+:root {
+  --uniface-dividing-line-color: #d4d4d8;
+}
+.dark-theme {
+  --uniface-dividing-line-color: #3f3f46;
+}
+```
+
+## 行为说明
+
+- **仅鼠标。** 拖动用的是 `mousedown` / `mousemove` / `mouseup`。**不**处理 touch 事件，触屏设备上手指拖动不会响应。
+- **最小尺寸**：绑定面板夹到 ≥5px（不会塌成 0）。
+- **document 级监听**：拖动期间 `mousemove` 和 `mouseup` 挂在 `document` 上，光标移出分隔条也不会丢失拖动。
+- **body 光标覆盖**：拖动期间 `document.body.style.cursor` 被设为 `col-resize` / `row-resize`，`mouseup` 时还原。
+- **清理**：组件在拖动中被销毁时，`onDestroy` 会调 `stopDrag` 移除监听并还原光标。
+- **直接改 style**：绑定面板的 `style.width` 或 `style.height` 被直接写入 —— 不走 React 式状态。面板内容再重也不会卡。
+- **没有 resize-start 事件**：只有 `onResizeEnd`。需要实时跟尺寸的话，自己给绑定面板挂 `ResizeObserver`。
+
+## 无障碍访问
+
+- 分隔条上设置了 `role="separator"`、`aria-orientation`、`aria-label="Resize handle"`、`tabindex="0"`。
+- **键盘支持有限**：可聚焦，但组件**不**处理方向键。拖动必须用鼠标。需要键盘调整的话，自己在父元素上叠一层 `keydown`。
+- 固定分隔条如果视觉上还像可交互，建议加 `aria-disabled="true"`。
+
+## 最佳实践
+
+1. **`bind:this` 面板** —— `bindingPanel` 要的是真实 DOM 引用，不是 CSS 选择器
+2. **`direction` 要和 flex 布局匹配** —— `flex-direction: row` 配竖条，`flex-direction: column` 配横条
+3. **绑定面板在远端时用 `reverse`** （竖条的右侧 / 横条的下方）
+4. **吸收面板给 `flex: 1 1 auto`**，这样绑定面板变大变小时它能补足剩余空间
+5. **持久化走 `onResizeEnd`**，不要每帧回调（中间事件本来也不会发）
+6. **不需要可拖动时省略 `bindingPanel`**，不要绑一个再禁用
+
+## 相关组件
+
+- [Separator](../separator/README_CN.md) —— 纯装饰的 1px 竖线（无交互）

package/dist/general/split/Split.svelte

@@ -0,0 +1,130 @@
+<script lang="ts">
+    import { onMount, onDestroy } from 'svelte';
+
+    interface Props {
+        direction?: "horizontal" | "vertical";
+        width?: number;
+        bindingPanel?: HTMLElement;
+        reverse?: boolean;
+        onResizeEnd?: (size: number) => void;
+    }
+
+    let {
+        direction = "vertical",
+        width = 2,
+        bindingPanel,
+        reverse = false,
+        onResizeEnd
+    }: Props = $props();
+
+    let isDragging = $state(false);
+    let startPos = $state(0);
+    let startSize = $state(0);
+
+    const style = $derived(direction === "horizontal" ? `height: ${width}px` : `width: ${width}px`);
+    const fixed = $derived(!bindingPanel);
+
+    const calculateNewSize = (currentPos: number): number => {
+        if (!bindingPanel) return 0;
+
+        const delta = reverse ? startPos - currentPos : currentPos - startPos;
+        const minSize = 5;
+        return Math.max(minSize, startSize + delta);
+    };
+
+    const startDrag = (event: MouseEvent) => {
+        if (fixed || !bindingPanel) return;
+
+        isDragging = true;
+        startPos = direction === "horizontal" ? event.clientY : event.clientX;
+        startSize = direction === "horizontal"
+            ? bindingPanel.clientHeight
+            : bindingPanel.clientWidth;
+
+        document.addEventListener("mousemove", onDrag, { passive: false });
+        document.addEventListener("mouseup", stopDrag);
+        document.body.style.cursor = direction === "horizontal" ? "row-resize" : "col-resize";
+        event.preventDefault();
+    };
+
+    const onDrag = (event: MouseEvent) => {
+        if (!isDragging || !bindingPanel) return;
+
+        const currentPos = direction === "horizontal" ? event.clientY : event.clientX;
+        const newSize = calculateNewSize(currentPos);
+
+        if (direction === "horizontal") {
+            bindingPanel.style.height = `${newSize}px`;
+        } else {
+            bindingPanel.style.width = `${newSize}px`;
+        }
+    };
+
+    const stopDrag = () => {
+        if (!isDragging) return;
+
+        isDragging = false;
+        document.body.style.cursor = "";
+        document.removeEventListener("mousemove", onDrag);
+        document.removeEventListener("mouseup", stopDrag);
+
+        if (bindingPanel && onResizeEnd) {
+            const finalSize = direction === "horizontal"
+                ? bindingPanel.clientHeight
+                : bindingPanel.clientWidth;
+            onResizeEnd(finalSize);
+        }
+    };
+
+    // 组件销毁时清理
+    onDestroy(() => {
+        if (isDragging) {
+            stopDrag();
+        }
+    });
+
+</script>
+
+<div
+    class="uniface-divider {direction}"
+    class:fixed
+    {style}
+    role="separator"
+    aria-orientation={direction}
+    aria-label="Resize handle"
+    tabindex="0"
+    onmousedown={startDrag}
+/>
+
+<style>
+    .uniface-divider {
+        background-color: var(--uniface-dividing-line-color, #CBD5E1);
+        flex: 0 0 auto;
+        transition: background-color 0.2s ease;
+    }
+
+    .uniface-divider.horizontal {
+        width: 100%;
+        cursor: row-resize;
+    }
+
+    .uniface-divider.vertical {
+        height: 100%;
+        cursor: col-resize;
+    }
+
+    .uniface-divider.fixed {
+        cursor: default;
+        pointer-events: none;
+    }
+
+    /* 拖动时移除过渡效果，提高响应性 */
+    .uniface-divider:hover {
+        background-color: color-mix(in srgb, var(--uniface-dividing-line-color, #CBD5E1) 80%, #000);
+    }
+
+    /* 拖动时移除过渡效果，提高响应性 */
+    .uniface-divider:active {
+        transition: none;
+    }
+</style>

package/dist/general/split/Split.svelte.d.ts

@@ -0,0 +1,10 @@
+interface Props {
+    direction?: "horizontal" | "vertical";
+    width?: number;
+    bindingPanel?: HTMLElement;
+    reverse?: boolean;
+    onResizeEnd?: (size: number) => void;
+}
+declare const Split: import("svelte").Component<Props, {}, "">;
+type Split = ReturnType<typeof Split>;
+export default Split;