@ticatec/topside-elements 1.0.0

package/dist/general/separator/README.md

@@ -0,0 +1,203 @@
+# Separator Component
+
+A **vertical** divider — a 1px-wide line whose height you control. Designed to sit between items in a flex row to visually separate them.
+
+> **Not for horizontal rules.** This component renders a 1px-wide, N-pixel-tall vertical bar. If you need a horizontal divider between stacked sections, use a plain `<div style="height: 1px; background: ..."></div>` or a `<hr>` instead.
+
+## Features
+
+- **Vertical divider**: fixed 1px width, configurable height
+- **Theme token**: color driven by the `--topside-separator-color` CSS variable
+- **Override-friendly**: `style` prop is appended after `height`, so any inline CSS wins
+- **Zero layout noise**: `position: relative` plays nicely inside flex/grid parents
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Separator from '@ticatec/topside-elements/Separator';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Separator from '@ticatec/topside-elements/Separator';
+</script>
+
+<div style="display: flex; align-items: center; gap: 16px;">
+  <span>Left</span>
+  <Separator />
+  <span>Right</span>
+</div>
+```
+
+The default height is `24px`, so the divider is 24px tall and 1px wide.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `height` | `string` | `'24px'` | CSS height value of the divider (e.g. `'24px'`, `'60px'`, `'100%'`) |
+| `style` | `string` | `undefined` | Extra inline CSS. Appended after `height`, so it can override height, color, etc. |
+
+## Events
+
+None.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="topside-separator" style="height: 24px; {your-style}"></div>
+```
+
+Built-in styles:
+
+```css
+.topside-separator {
+  position: relative;
+  width: 1px;
+  background-color: var(--topside-separator-color, #E2E8F0);
+}
+```
+
+### CSS Custom Properties
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--topside-separator-color` | `#E2E8F0` | Background color of the divider |
+
+Set it globally to theme every Separator, or scope it:
+
+```css
+:root {
+  --topside-separator-color: #d1d5db;
+}
+
+/* only inside dark toolbars */
+.dark-toolbar {
+  --topside-separator-color: #475569;
+}
+```
+
+## Basic Examples
+
+### Default Height (24px)
+
+```svelte
+<div style="display: flex; align-items: center; gap: 16px;">
+  <span>A</span>
+  <Separator />
+  <span>B</span>
+</div>
+```
+
+### Custom Height
+
+```svelte
+<div style="display: flex; align-items: center; gap: 16px; height: 80px;">
+  <span>Item</span>
+  <Separator height="60px" />   <!-- shorter than the row -->
+  <span>Item</span>
+  <Separator height="100%" />   <!-- full row height -->
+  <span>Item</span>
+</div>
+```
+
+### Custom Color
+
+```svelte
+<Separator style="background-color: #e53e3e;" />
+```
+
+Or via the theme token:
+
+```svelte
+<div style="--topside-separator-color: #e53e3e;">
+  <Separator />
+</div>
+```
+
+## Detailed Examples
+
+### Toolbar Dividers
+
+A common pattern: separate groups of action buttons in a toolbar.
+
+```svelte
+<script>
+  import Separator from '@ticatec/topside-elements/Separator';
+  import IconButton from '@ticatec/topside-elements/IconButton';
+</script>
+
+<div style="display: flex; align-items: center; gap: 8px; padding: 8px;">
+  <!-- File group -->
+  <IconButton icon="icon_google_create_new_folder" />
+  <IconButton icon="icon_google_save" />
+  <IconButton icon="icon_google_open_in_new" />
+
+  <Separator />
+
+  <!-- Edit group -->
+  <IconButton icon="icon_google_content_copy" />
+  <IconButton icon="icon_google_content_paste" />
+  <IconButton icon="icon_google_content_cut" />
+
+  <Separator />
+
+  <!-- Danger group -->
+  <IconButton icon="icon_google_delete" />
+</div>
+```
+
+### Header Layout
+
+Split a page header into left/right zones:
+
+```svelte
+<header style="display: flex; align-items: center; gap: 24px; height: 56px;">
+  <div class="brand">MyApp</div>
+  <Separator height="32px" />
+  <nav class="menu">...</nav>
+  <div style="flex: 1 1 auto;"></div>   <!-- spacer -->
+  <Separator height="32px" />
+  <div class="user">Hi, Henry</div>
+</header>
+```
+
+### Style Override via `style` Prop
+
+Because `style` is appended after `height`, later declarations win — you can override height, color, or even width:
+
+```svelte
+<!-- Taller, red -->
+<Separator style="height: 48px; background-color: #ef4444;" />
+
+<!-- Dashed vertical line -->
+<Separator style="height: 100%; width: 0; border-left: 1px dashed #94a3b8; background: transparent;" />
+```
+
+## Best Practices
+
+1. **Use between horizontal items** — that's what the 1px width is for.
+2. **For horizontal rules between stacked content**, don't use this component — use a `<hr>` or a 1px-tall `<div>`.
+3. **Keep height consistent** within a single toolbar/header (e.g. always `24px` or always `60%`).
+4. **Theme via the CSS variable** rather than per-instance `style`, so you can re-skin the whole app in one place.
+
+## Accessibility
+
+- Pure decoration; no interactive semantics.
+- The wrapper renders as a `<div>` with no ARIA attributes — screen readers ignore it.
+- Don't rely on a Separator alone to convey section boundaries; pair it with semantic headings or `<section>` elements.
+
+## Related Components
+
+- [Button](../button/README.md) — standard button (often used between Separators in toolbars)
+- [IconButton](../button/IconButton_README.md) — round icon button, common in toolbars next to Separators

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 宽，高度可配置
+- **主题令牌**：颜色由 `--topside-separator-color` CSS 变量驱动
+- **便于覆盖**：`style` 属性追加在 `height` 之后，任何内联 CSS 都能盖掉默认值
+- **不扰动布局**：`position: relative`，在 flex/grid 父容器里很老实
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import Separator from '@ticatec/topside-elements/Separator';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Separator from '@ticatec/topside-elements/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="topside-separator" style="height: 24px; {你的 style}"></div>
+```
+
+内置样式：
+
+```css
+.topside-separator {
+  position: relative;
+  width: 1px;
+  background-color: var(--topside-separator-color, #E2E8F0);
+}
+```
+
+### CSS 自定义属性
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `--topside-separator-color` | `#E2E8F0` | 分隔线的背景色 |
+
+全局设置即可主题化所有 Separator；也可以局部作用域：
+
+```css
+:root {
+  --topside-separator-color: #d1d5db;
+}
+
+/* 仅在深色工具栏内 */
+.dark-toolbar {
+  --topside-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="--topside-separator-color: #e53e3e;">
+  <Separator />
+</div>
+```
+
+## 详细示例
+
+### 工具栏分隔
+
+最经典的用法：在工具栏的按钮组之间画分隔线。
+
+```svelte
+<script>
+  import Separator from '@ticatec/topside-elements/Separator';
+  import IconButton from '@ticatec/topside-elements/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="topside-separator" style="height: {height}; {style};">
+
+</div>
+<style>
+    .topside-separator {
+        position: relative;
+        width: 1px;
+        background-color: var(--topside-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/separator/index.d.ts

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

package/dist/general/separator/index.js

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