@ticatec/topside-elements 1.0.0

package/dist/layouts/form_panel/flex_row_form/README.md

@@ -0,0 +1,224 @@
+# FlexRowForm
+
+A row-based form layout: an outer column-flex container holds `Row`s, each `Row` holds `Cell`s with 12-column spans. Unlike [FlexForm](../flex_form/README.md) (which auto-wraps), FlexRowForm enforces explicit row boundaries — content does not flow between rows. The outer container scrolls vertically when content overflows.
+
+## Components
+
+| Export | Purpose |
+|--------|---------|
+| `FormContainer` (default) | Outer wrapper — vertical scroll, column flex |
+| `Row` | A horizontal flex row |
+| `Cell` | A 12-column-span cell (raw; doesn't wrap FormField) |
+| `CellField` | Re-exported from `flex_form` — Cell + FormField combined |
+| `EmptyCell` | Re-exported from `flex_form` — empty spacer cell |
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import FlexRowForm, { Row, Cell, CellField, EmptyCell } from '@ticatec/topside-elements/FlexRowForm';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import FlexRowForm, { Row, CellField } from '@ticatec/topside-elements/FlexRowForm';
+  import TextEditor from '@ticatec/topside-elements/TextEditor';
+</script>
+
+<FlexRowForm>
+  <Row>
+    <CellField label="First name" span={3}>
+      <TextEditor bind:value={firstName} />
+    </CellField>
+    <CellField label="Last name" span={3}>
+      <TextEditor bind:value={lastName} />
+    </CellField>
+    <CellField label="Email" span={6}>
+      <TextEditor type="email" bind:value={email} />
+    </CellField>
+  </Row>
+
+  <Row>
+    <CellField label="Address" span={12}>
+      <TextEditor bind:value={address} />
+    </CellField>
+  </Row>
+</FlexRowForm>
+```
+
+## Components Reference
+
+### `FormContainer` (default export)
+
+Outer wrapper. Children render inside an `overflow: auto` column-flex container.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `class` | `string \| undefined` | `undefined` | Extra CSS class on the outer wrapper |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper |
+| `children` | `Snippet \| undefined` | `undefined` | Form content (typically `Row`s) |
+
+Outer wrapper CSS:
+
+```css
+.flex-row-form {
+  width: 100%;
+  overflow: hidden;
+  padding: var(--topside-form-container-padding);
+}
+
+.flex-row-form > div {
+  display: flex;
+  flex-direction: column;
+  overflow: auto;             /* ← vertical scroll when content overflows */
+}
+```
+
+### `Row`
+
+A horizontal flex row. Children render side-by-side.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `style` | `string` | `''` | Inline CSS on the row |
+| `theme` | `string \| undefined` | `undefined` | CSS class on the row (not `data-theme`!) |
+| `variant` | `string \| undefined` | `undefined` | **Snippet parameter only** — passed to children snippet, not rendered as a class |
+| `children` | `Snippet<[string \| undefined, string \| undefined]> \| undefined` | `undefined` | Row content. The snippet receives `(theme, variant)` as arguments. |
+
+> **`theme` quirk on Row.** Unlike most components in this library, Row applies `theme` as a CSS **class** (`<div class="form-row {theme}">`), not as `data-theme`. If you're using `[data-theme="..."]` selectors, they won't match.
+
+Built-in CSS:
+
+```css
+.form-row {
+  display: flex;
+  flex-direction: row;
+  padding: var(--topside-form-row-padding);
+}
+
+.form-row:last-child {
+  padding-bottom: 0;        /* no trailing gap */
+}
+```
+
+### `Cell`
+
+A raw 12-column-span cell. Does **not** wrap FormField — use this when you need full control over content (custom layout, multiple controls, etc.). For label+control use `CellField`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `span` | `number` | `1` | Column span (1–12, clamped). Each unit ≈ 8.33% of row width. |
+| `style` | `string` | `''` | Inline CSS appended after the computed `width: N%` |
+| `variant` | `string \| undefined` | `undefined` | CSS class on the cell + snippet arg |
+| `theme` | `string \| undefined` | `undefined` | CSS class on the cell + snippet arg |
+| `children` | `Snippet<[string \| undefined, string \| undefined]> \| undefined` | `undefined` | Cell content. Receives `(theme, variant)` as snippet args. |
+
+Width computation:
+
+```js
+const ONE_CELL = 100 / 12;
+const width = `${ONE_CELL * cs}%`;   // 1 → 8.33%, 6 → 50%, 12 → 100%
+```
+
+> **Snippet args order is consistent across Row and Cell**: both pass `(theme, variant)`. The same order is used by GridForm and GridField.
+
+### `CellField` (re-exported)
+
+Convenience: a `Cell`-sized wrapper around [FormField](../../form_field/README.md). Same props as in [FlexForm's CellField](../flex_form/README.md#cellfield) — `span`, `label`, `required`, `label$style`, `style`, `theme`, `children`.
+
+### `EmptyCell` (re-exported)
+
+Empty 12-column-span spacer. Same as [FlexForm's EmptyCell](../flex_form/README.md#emptycell).
+
+## Examples
+
+### Multiple Rows
+
+```svelte
+<FlexRowForm>
+  <Row>
+    <CellField label="Username" span={6} required />
+    <CellField label="Status"   span={6} />
+  </Row>
+  <Row>
+    <CellField label="Bio"      span={12} />
+  </Row>
+</FlexRowForm>
+```
+
+### Raw Cell with Custom Content
+
+```svelte
+<Row>
+  <Cell span={6}>
+    <div style="display: flex; gap: 8px;">
+      <TextEditor bind:value={phone} placeholder="Phone" />
+      <Button label="Verify" onclick={verify} />
+    </div>
+  </Cell>
+  <CellField label="Email" span={6}>
+    <TextEditor bind:value={email} />
+  </CellField>
+</Row>
+```
+
+### Snippet Args (theme, variant)
+
+```svelte
+<Row variant="compact">
+  {#snippet children(theme, variant)}
+    <Cell span={6} theme={theme} variant={variant}>
+      {#snippet cellChildren(theme, variant)}
+        <TextEditor variant={variant} />
+      {/snippet}
+    </Cell>
+  {/snippet}
+</Row>
+```
+
+In practice, snippet args are rarely needed unless you're propagating form-wide theme/variant to deeply nested controls.
+
+### Mixed Cell + EmptyCell + CellField
+
+```svelte
+<Row>
+  <CellField label="A" span={4} />
+  <EmptyCell span={4} />
+  <CellField label="B" span={4} />
+</Row>
+```
+
+## CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--topside-form-container-padding` | (theme) | Padding on `FormContainer` |
+| `--topside-form-row-padding` | (theme) | Padding on each `Row` |
+| `--topside-form-cell-padding` | (theme) | Padding on each `Cell` |
+
+## Behavior Notes
+
+- **Outer container scrolls vertically**, not horizontally. `overflow: auto` on the inner wrapper.
+- **Rows are explicit.** Content doesn't flow between rows (unlike FlexForm's auto-wrap).
+- **`Row:last-child` drops its bottom padding** so the form ends flush.
+- **`theme` on Row and Cell is a CSS class**, not a `data-theme` attribute. Inconsistent with the rest of the library — be aware when writing theme selectors.
+- **Snippet arg order:** Row, Cell, GridForm, and GridField all pass `(theme, variant)` consistently.
+- **`Cell` is raw** — it doesn't render FormField. Use `CellField` for label+control.
+
+## Accessibility
+
+Inherits FormField a11y behavior (when using `CellField`). Raw `Cell` content is your responsibility — add your own `<label for>` association if you put form controls inside.
+
+## Related Components
+
+- [FlexForm](../flex_form/README.md) — auto-wrapping sibling, no explicit Row boundaries
+- [GridForm](../grid_form/README.md) — CSS Grid sibling with rowSpan / colSpan
+- [FormField](../../form_field/README.md) — what CellField renders internally

package/dist/layouts/form_panel/flex_row_form/README_CN.md

@@ -0,0 +1,224 @@
+# FlexRowForm
+
+基于行的表单布局：外层 column-flex 容器装 `Row`，每个 `Row` 里放 12 列跨度的 `Cell`。跟 [FlexForm](../flex_form/README_CN.md)（自动换行）不同，FlexRowForm 强制显式行边界 —— 内容不会跨行流动。内容溢出时外层容器纵向滚动。
+
+## 组件
+
+| 导出 | 用途 |
+|------|------|
+| `FormContainer`（默认） | 外层 wrapper —— 纵向滚动，column flex |
+| `Row` | 横向 flex 行 |
+| `Cell` | 12 列跨度的 cell（原始；不包 FormField） |
+| `CellField` | 从 `flex_form` 复用 —— Cell + FormField 合体 |
+| `EmptyCell` | 从 `flex_form` 复用 —— 空占位 cell |
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import FlexRowForm, { Row, Cell, CellField, EmptyCell } from '@ticatec/topside-elements/FlexRowForm';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import FlexRowForm, { Row, CellField } from '@ticatec/topside-elements/FlexRowForm';
+  import TextEditor from '@ticatec/topside-elements/TextEditor';
+</script>
+
+<FlexRowForm>
+  <Row>
+    <CellField label="姓" span={3}>
+      <TextEditor bind:value={firstName} />
+    </CellField>
+    <CellField label="名" span={3}>
+      <TextEditor bind:value={lastName} />
+    </CellField>
+    <CellField label="邮箱" span={6}>
+      <TextEditor type="email" bind:value={email} />
+    </CellField>
+  </Row>
+
+  <Row>
+    <CellField label="地址" span={12}>
+      <TextEditor bind:value={address} />
+    </CellField>
+  </Row>
+</FlexRowForm>
+```
+
+## 组件参考
+
+### `FormContainer`（默认导出）
+
+外层 wrapper。children 渲染在 `overflow: auto` 的 column-flex 容器里。
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `class` | `string \| undefined` | `undefined` | 外层 wrapper 的额外 CSS 类 |
+| `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme` |
+| `children` | `Snippet \| undefined` | `undefined` | 表单内容（通常是 `Row`） |
+
+外层 CSS：
+
+```css
+.flex-row-form {
+  width: 100%;
+  overflow: hidden;
+  padding: var(--topside-form-container-padding);
+}
+
+.flex-row-form > div {
+  display: flex;
+  flex-direction: column;
+  overflow: auto;             /* ← 内容溢出时纵向滚动 */
+}
+```
+
+### `Row`
+
+横向 flex 行。children 并排渲染。
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `style` | `string` | `''` | 行的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 行的 CSS 类（**不是** `data-theme`！） |
+| `variant` | `string \| undefined` | `undefined` | **仅 snippet 参数** —— 传给 children snippet，不渲染成类 |
+| `children` | `Snippet<[string \| undefined, string \| undefined]> \| undefined` | `undefined` | 行内容。snippet 接收 `(theme, variant)` 作为参数 |
+
+> **Row 上 `theme` 的怪行为。** 跟库里大多数组件不同，Row 把 `theme` 应用为 CSS **类**（`<div class="form-row {theme}">`），不是 `data-theme`。如果你用 `[data-theme="..."]` 选择器，匹配不上。
+
+内置 CSS：
+
+```css
+.form-row {
+  display: flex;
+  flex-direction: row;
+  padding: var(--topside-form-row-padding);
+}
+
+.form-row:last-child {
+  padding-bottom: 0;        /* 最后行不留尾部间距 */
+}
+```
+
+### `Cell`
+
+原始的 12 列跨度 cell。**不**包 FormField —— 需要完全控制内容（自定义布局、多个控件等）时用。标签+控件场景用 `CellField`。
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `span` | `number` | `1` | 列跨度（1–12，夹到范围内）。每单位 ≈ 行宽的 8.33% |
+| `style` | `string` | `''` | 内联 CSS，追加在计算出的 `width: N%` 之后 |
+| `variant` | `string \| undefined` | `undefined` | cell 的 CSS 类 + snippet 参数 |
+| `theme` | `string \| undefined` | `undefined` | cell 的 CSS 类 + snippet 参数 |
+| `children` | `Snippet<[string \| undefined, string \| undefined]> \| undefined` | `undefined` | cell 内容。snippet 接收 `(theme, variant)` 作为参数 |
+
+宽度计算：
+
+```js
+const ONE_CELL = 100 / 12;
+const width = `${ONE_CELL * cs}%`;   // 1 → 8.33%, 6 → 50%, 12 → 100%
+```
+
+> **Snippet 参数顺序在 Row / Cell / GridForm / GridField 间一致**：都传 `(theme, variant)`。
+
+### `CellField`（复用导出）
+
+便利写法：`Cell` 尺寸的 wrapper，内部包 [FormField](../../form_field/README_CN.md)。Props 同 [FlexForm 的 CellField](../flex_form/README_CN.md#cellfield) —— `span`、`label`、`required`、`label$style`、`style`、`theme`、`children`。
+
+### `EmptyCell`（复用导出）
+
+空的 12 列跨度占位。同 [FlexForm 的 EmptyCell](../flex_form/README_CN.md#emptycell)。
+
+## 示例
+
+### 多行
+
+```svelte
+<FlexRowForm>
+  <Row>
+    <CellField label="用户名" span={6} required />
+    <CellField label="状态"   span={6} />
+  </Row>
+  <Row>
+    <CellField label="简介"   span={12} />
+  </Row>
+</FlexRowForm>
+```
+
+### 用原始 Cell 放自定义内容
+
+```svelte
+<Row>
+  <Cell span={6}>
+    <div style="display: flex; gap: 8px;">
+      <TextEditor bind:value={phone} placeholder="电话" />
+      <Button label="验证" onclick={verify} />
+    </div>
+  </Cell>
+  <CellField label="邮箱" span={6}>
+    <TextEditor bind:value={email} />
+  </CellField>
+</Row>
+```
+
+### Snippet 参数（theme、variant）
+
+```svelte
+<Row variant="compact">
+  {#snippet children(theme, variant)}
+    <Cell span={6} theme={theme} variant={variant}>
+      {#snippet cellChildren(theme, variant)}
+        <TextEditor variant={variant} />
+      {/snippet}
+    </Cell>
+  {/snippet}
+</Row>
+```
+
+实际开发中 snippet 参数很少用到，除非你要把表单级的 theme/variant 传到深层嵌套控件。
+
+### 混合 Cell + EmptyCell + CellField
+
+```svelte
+<Row>
+  <CellField label="A" span={4} />
+  <EmptyCell span={4} />
+  <CellField label="B" span={4} />
+</Row>
+```
+
+## CSS 变量
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `--topside-form-container-padding` | （主题） | `FormContainer` 的 padding |
+| `--topside-form-row-padding` | （主题） | 每个 `Row` 的 padding |
+| `--topside-form-cell-padding` | （主题） | 每个 `Cell` 的 padding |
+
+## 行为说明
+
+- **外层容器纵向滚动**，不横向。内层 wrapper 是 `overflow: auto`
+- **行是显式的。** 内容不跨行流动（与 FlexForm 的自动换行不同）
+- **`Row:last-child` 去掉底部 padding**，让表单结尾紧贴
+- **Row 和 Cell 的 `theme` 是 CSS 类**，不是 `data-theme` 属性。跟库其他地方不一致 —— 写主题选择器时注意
+- **Snippet 参数顺序：** Row / Cell / GridForm / GridField 都一致传 `(theme, variant)`
+- **`Cell` 是原始的** —— 不渲染 FormField。标签+控件场景用 `CellField`
+
+## 无障碍访问
+
+继承 FormField 的 a11y 行为（用 `CellField` 时）。原始 `Cell` 内容自负 —— 放表单控件时自己加 `<label for>` 关联。
+
+## 相关组件
+
+- [FlexForm](../flex_form/README_CN.md) —— 自动换行的同胞，无显式 Row 边界
+- [GridForm](../grid_form/README_CN.md) —— CSS Grid 同胞，有 rowSpan / colSpan
+- [FormField](../../form_field/README_CN.md) —— CellField 内部渲染的东西

package/dist/layouts/form_panel/flex_row_form/Row.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+    import type {EditorVariant} from "../../../form/types";
+    import type {Snippet} from 'svelte';
+
+    interface Props {
+        theme?: string;
+        /** 传给内部编辑器的外观变体 */
+        variant?: EditorVariant;
+        style?: string;
+        children?: Snippet<[string | undefined, string | undefined]>;
+    }
+
+    let {
+        style = '',
+        theme,
+        variant,
+        children
+    }: Props = $props();
+</script>
+
+<div class="form-row {theme}" {style}>
+    {#if children}
+        {@render children(theme, variant)}
+    {/if}
+</div>
+
+<style>
+    .form-row {
+        display: flex;
+        flex-direction: row;
+        padding: var(--topside-form-row-padding);
+    }
+
+    .form-row:last-child {
+        padding-bottom: 0;
+    }
+</style>

package/dist/layouts/form_panel/flex_row_form/Row.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { EditorVariant } from "../../../form/types";
+import type { Snippet } from 'svelte';
+interface Props {
+    theme?: string;
+    /** 传给内部编辑器的外观变体 */
+    variant?: EditorVariant;
+    style?: string;
+    children?: Snippet<[string | undefined, string | undefined]>;
+}
+declare const Row: import("svelte").Component<Props, {}, "">;
+type Row = ReturnType<typeof Row>;
+export default Row;

package/dist/layouts/form_panel/flex_row_form/index.d.ts

@@ -0,0 +1,7 @@
+import FormContainer from "./FormContainer.svelte";
+import Row from "./Row.svelte";
+import Cell from "./Cell.svelte";
+import CellField from "../flex_form/CellField.svelte";
+import EmptyCell from "../flex_form/EmptyCell.svelte";
+export default FormContainer;
+export { Row, Cell, CellField, EmptyCell };

package/dist/layouts/form_panel/flex_row_form/index.js

@@ -0,0 +1,7 @@
+import FormContainer from "./FormContainer.svelte";
+import Row from "./Row.svelte";
+import Cell from "./Cell.svelte";
+import CellField from "../flex_form/CellField.svelte";
+import EmptyCell from "../flex_form/EmptyCell.svelte";
+export default FormContainer;
+export { Row, Cell, CellField, EmptyCell };

package/dist/layouts/form_panel/grid_form/EmptyCell.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+    interface Props {
+        rowSpan?: number;
+        colSpan?: number;
+        row?: number;
+        col?: number;
+    }
+
+    let {
+        rowSpan = 1,
+        colSpan = 1,
+        row,
+        col
+    }: Props = $props();
+
+    const style = $derived(() => {
+        let s = '';
+        if (row != null) s += `grid-row-start: ${row};`;
+        if (col != null) s += `grid-column-start: ${col};`;
+        if (rowSpan > 1) s += `grid-row-end: span ${rowSpan};`;
+        if (colSpan > 1) s += `grid-column-end: span ${colSpan};`;
+        return s;
+    });
+</script>
+
+<div class="cell-field" style={style()}></div>
+
+<style>
+    .cell-field {
+        box-sizing: border-box;
+    }
+</style>

package/dist/layouts/form_panel/grid_form/EmptyCell.svelte.d.ts

@@ -0,0 +1,9 @@
+interface Props {
+    rowSpan?: number;
+    colSpan?: number;
+    row?: number;
+    col?: number;
+}
+declare const EmptyCell: import("svelte").Component<Props, {}, "">;
+type EmptyCell = ReturnType<typeof EmptyCell>;
+export default EmptyCell;

package/dist/layouts/form_panel/grid_form/GridField.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+    import type {EditorVariant} from "../../../form/types";
+    import type {Direction} from "../../../types";
+    import type {Snippet} from 'svelte';
+    import FormField from "../../form_field";
+
+    interface Props {
+        label?: string;
+        label$style?: string;
+        required?: boolean;
+        /** 标签与控件的排布方向 */
+        direction?: Direction;
+        rowSpan?: number;
+        colSpan?: number;
+        row?: number | null;
+        col?: number | null;
+        labelSuffix?: string;
+        /** 传给内部编辑器的外观变体 */
+        variant?: EditorVariant;
+        theme?: string;
+        children?: Snippet<[string | undefined, string | undefined]>;
+    }
+
+    let {
+        label = "Label:",
+        label$style = '',
+        required = false,
+        direction = 'vertical',
+        rowSpan = 1,
+        colSpan = 1,
+        row = null,
+        col = null,
+        labelSuffix = ':',
+        variant,
+        theme,
+        children
+    }: Props = $props();
+
+    const style = $derived(
+        `${rowSpan > 1 ? `grid-row-end: span ${rowSpan};` : ''}${colSpan > 1 ? `grid-column-end: span ${colSpan};` : ''}${row != null ? `grid-row-start: ${row};` : ''}${col != null ? `grid-column-start: ${col};` : ''}`
+    );
+</script>
+
+<FormField class="form-cell {direction} {theme}" {label$style} {labelSuffix} {style} {label} {required}>
+    {#if children}
+        {@render children(theme, variant)}
+    {/if}
+</FormField>

package/dist/layouts/form_panel/grid_form/GridField.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { EditorVariant } from "../../../form/types";
+import type { Direction } from "../../../types";
+import type { Snippet } from 'svelte';
+interface Props {
+    label?: string;
+    label$style?: string;
+    required?: boolean;
+    /** 标签与控件的排布方向 */
+    direction?: Direction;
+    rowSpan?: number;
+    colSpan?: number;
+    row?: number | null;
+    col?: number | null;
+    labelSuffix?: string;
+    /** 传给内部编辑器的外观变体 */
+    variant?: EditorVariant;
+    theme?: string;
+    children?: Snippet<[string | undefined, string | undefined]>;
+}
+declare const GridField: import("svelte").Component<Props, {}, "">;
+type GridField = ReturnType<typeof GridField>;
+export default GridField;

package/dist/layouts/form_panel/grid_form/GridForm.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+    import type {EditorVariant} from "../../../form/types";
+    import type {Snippet} from 'svelte';
+
+    interface Props {
+        style?: string;
+        columns?: number;
+        /** 传给内部编辑器的外观变体 */
+        variant?: EditorVariant;
+        theme?: string;
+        children?: Snippet<[string | undefined, string | undefined]>;
+    }
+
+    let {
+        style = '',
+        columns = 6,
+        variant,
+        theme,
+        children
+    }: Props = $props();
+
+    const gridStyle = $derived(`grid-template-columns: repeat(${columns}, 1fr)`);
+</script>
+
+<div class="grid-form {theme}" {style}>
+    <div style={gridStyle}>
+        {#if children}
+            {@render children(theme, variant)}
+        {/if}
+    </div>
+</div>
+
+<style>
+    .grid-form {
+        position: relative;
+        width: 100%;
+        display: block;
+        padding: var(--topside-form-container-padding);
+    }
+
+    .grid-form > div {
+        width: 100%;
+        height: 100%;
+        position: relative;
+        display: grid;
+        justify-items: start;
+        box-sizing: border-box;
+    }
+</style>