@ticatec/topside-elements 1.0.0

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 `--topside-dividing-line-color`
+- **Cleanup on unmount**: in-flight drag is cancelled if the component is destroyed mid-drag
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Split from '@ticatec/topside-elements/Split';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Split from '@ticatec/topside-elements/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/topside-elements/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/topside-elements/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/topside-elements/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/topside-elements/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/topside-elements/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="topside-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
+.topside-divider {
+  background-color: var(--topside-dividing-line-color, #CBD5E1);
+  flex: 0 0 auto;          /* don't grow or shrink */
+  transition: background-color 0.2s ease;
+}
+
+.topside-divider.vertical {
+  height: 100%;
+  cursor: col-resize;
+}
+
+.topside-divider.horizontal {
+  width: 100%;
+  cursor: row-resize;
+}
+
+.topside-divider.fixed {
+  cursor: default;
+  pointer-events: none;
+}
+
+.topside-divider:hover {
+  /* darken 20% via color-mix */
+  background-color: color-mix(in srgb, var(--topside-dividing-line-color, #CBD5E1) 80%, #000);
+}
+
+.topside-divider:active {
+  transition: none;        /* no animation lag during drag */
+}
+```
+
+### CSS Custom Properties
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--topside-dividing-line-color` | `#CBD5E1` | Background color of the bar (hover state darkens it 20%) |
+
+```css
+:root {
+  --topside-dividing-line-color: #d4d4d8;
+}
+.dark-theme {
+  --topside-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)

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 以下
+- **主题令牌**：颜色由 `--topside-dividing-line-color` 驱动
+- **销毁时清理**：组件在拖动过程中被销毁会自动取消拖动
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import Split from '@ticatec/topside-elements/Split';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Split from '@ticatec/topside-elements/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/topside-elements/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/topside-elements/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/topside-elements/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/topside-elements/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/topside-elements/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="topside-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
+.topside-divider {
+  background-color: var(--topside-dividing-line-color, #CBD5E1);
+  flex: 0 0 auto;          /* 不膨胀不收缩 */
+  transition: background-color 0.2s ease;
+}
+
+.topside-divider.vertical {
+  height: 100%;
+  cursor: col-resize;
+}
+
+.topside-divider.horizontal {
+  width: 100%;
+  cursor: row-resize;
+}
+
+.topside-divider.fixed {
+  cursor: default;
+  pointer-events: none;
+}
+
+.topside-divider:hover {
+  /* color-mix 加深 20% */
+  background-color: color-mix(in srgb, var(--topside-dividing-line-color, #CBD5E1) 80%, #000);
+}
+
+.topside-divider:active {
+  transition: none;        /* 拖动时无动画延迟 */
+}
+```
+
+### CSS 自定义属性
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `--topside-dividing-line-color` | `#CBD5E1` | 分隔条背景色（hover 时自动加深 20%） |
+
+```css
+:root {
+  --topside-dividing-line-color: #d4d4d8;
+}
+.dark-theme {
+  --topside-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 竖线（无交互）