@ticatec/topside-elements 1.0.0

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

@@ -0,0 +1,202 @@
+# FlexForm
+
+A wrapping 12-column flex-row form layout. Drop `CellField` children inside; each takes a `span` (1–12) of the row. Items wrap to the next line automatically when the row fills up — use `RowBreak` to force a break, `EmptyCell` to skip columns.
+
+This is the loosest of the three form layouts in this library: no rows required, content reflows with the viewport.
+
+## Components
+
+| Export | Purpose |
+|--------|---------|
+| `FlexForm` (default) | Outer wrapper — flex-row, wraps |
+| `CellField` | A 12-column-span cell wrapping [FormField](../../form_field/README.md) |
+| `EmptyCell` | An empty 12-column-span spacer |
+| `RowBreak` | Forces subsequent content onto a new row |
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import FlexForm, { CellField, EmptyCell, RowBreak } from '@ticatec/topside-elements/FlexForm';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import FlexForm, { CellField } from '@ticatec/topside-elements/FlexForm';
+  import TextEditor from '@ticatec/topside-elements/TextEditor';
+</script>
+
+<FlexForm>
+  <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>
+</FlexForm>
+```
+
+The three cells above occupy 3 + 3 + 6 = 12 columns → exactly one row.
+
+## Components Reference
+
+### `FlexForm`
+
+The outer wrapper. Children go inside as a flex-row that wraps.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `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 `CellField` / `EmptyCell` / `RowBreak`) |
+
+Outer wrapper CSS:
+
+```css
+.flex-form {
+  width: 100%;
+  padding: var(--topside-form-container-padding);
+}
+
+.flex-form > div {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;                /* ← items wrap to next line */
+  row-gap: var(--topside-form-row-gap);
+}
+```
+
+### `CellField`
+
+A 12-column-span cell that wraps [FormField](../../form_field/README.md). Renders the label + children.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `span` | `number` | `1` | Column span. Clamped to 1–12. Each unit = `100% / 12 ≈ 8.33%` of row width. |
+| `label` | `string` | `'Label'` | Label text forwarded to FormField |
+| `required` | `boolean` | `false` | Show red `*` before the label (FormField feature) |
+| `label$style` | `string` | `''` | Inline CSS on the label |
+| `style` | `string` | `''` | Extra inline CSS appended **after** the computed `width: N%`. Use for padding/margin overrides. |
+| `theme` | `string \| undefined` | `undefined` | Forwarded to FormField |
+| `children` | `Snippet \| undefined` | `undefined` | The actual form control |
+
+Computed width:
+
+```js
+const generateCss = (sp) => `width: ${sp * 100 / 12}%`;   // 1 → 8.33%, 6 → 50%, 12 → 100%
+```
+
+The `style` prop is appended after this width — `${style}; width: N%`. If you set `width` in your `style`, **the prop wins** (last declaration wins in CSS) — be careful.
+
+### `EmptyCell`
+
+A spacer cell with no content. Same `span` semantics as `CellField`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `span` | `number` | `1` | Column span (1–12, clamped) |
+
+Useful for right-aligning a single field on a row: put an `EmptyCell` with the matching span before it.
+
+### `RowBreak`
+
+Forces subsequent cells onto a new row. Renders `<div style="width: 100%; height: 0;">`, which exploits the flex-wrap behavior to break the row.
+
+```svelte
+<FlexForm>
+  <CellField label="A" span={6} />
+  <RowBreak />
+  <CellField label="B" span={6} />   <!-- starts a new row even though A+B = 12 -->
+</FlexForm>
+```
+
+No props.
+
+## Examples
+
+### Responsive Auto-Wrap
+
+Cells wrap when their combined span exceeds 12:
+
+```svelte
+<FlexForm>
+  <CellField label="A" span={4} />   <!-- 4 -->
+  <CellField label="B" span={4} />   <!-- 4 → row total 8 -->
+  <CellField label="C" span={4} />   <!-- 4 → row total 12, full -->
+  <CellField label="D" span={4} />   <!-- wraps to next row -->
+  <CellField label="E" span={4} />
+</FlexForm>
+```
+
+Row 1: A, B, C. Row 2: D, E.
+
+### Forced Row Break
+
+```svelte
+<FlexForm>
+  <CellField label="Username" span={6} />
+  <CellField label="Password" span={6} />
+  <RowBreak />
+  <CellField label="Remember me" span={12} />
+</FlexForm>
+```
+
+### Right-Aligned Field with EmptyCell
+
+```svelte
+<FlexForm>
+  <CellField label="Left" span={4} />
+  <EmptyCell span={4} />
+  <CellField label="Right" span={4} />
+</FlexForm>
+```
+
+### Mixed: CellField + EmptyCell + RowBreak
+
+```svelte
+<FlexForm>
+  <CellField label="Title"   span={8} required />
+  <CellField label="Status"  span={4} />
+  <RowBreak />
+  <CellField label="Summary" span={12} />
+  <EmptyCell span={6} />
+  <CellField label="Owner"   span={6} />
+</FlexForm>
+```
+
+## CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--topside-form-container-padding` | (theme) | Padding on the outer `FlexForm` wrapper |
+| `--topside-form-row-gap` | (theme) | Vertical gap between wrapped rows |
+| `--topside-form-field-padding` | (theme) | Padding on each cell — actually consumed by the inner FormField |
+
+> Cell-level padding is controlled by FormField's `--topside-form-field-padding` token (CellField renders FormField, which applies the padding to its own wrapper). Set this token globally or per-scope to adjust cell spacing.
+
+## Behavior Notes
+
+- **No scrolling.** `FlexForm` doesn't constrain height or scroll. Use an outer container if you need that.
+- **Children wrap, not crop.** When total span > 12, the excess wraps to a new row.
+- **`RowBreak` is just a 100%-width zero-height div** — it works because flex-wrap treats 100%-width items as row-fillers.
+- **CellField always renders FormField**, which means it inherits `getLayoutMode()` from context. Pair with `setLayoutMode('horizontal' | 'vertical')` in an ancestor.
+
+## Accessibility
+
+Inherits whatever FormField does — which means **labels are not associated with the wrapped control via `<label for>`**. See [FormField's a11y notes](../../form_field/README.md#accessibility).
+
+## Related Components
+
+- [FormField](../../form_field/README.md) — what CellField renders internally
+- [FlexRowForm](../flex_row_form/README.md) — sibling with explicit `Row` boundaries, vertical scrolling
+- [GridForm](../grid_form/README.md) — sibling using CSS Grid (rowSpan / colSpan)

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

@@ -0,0 +1,202 @@
+# FlexForm
+
+12 列的 wrapping flex-row 表单布局。把 `CellField` 子组件丢进去，每个按 `span`（1–12）占列宽。一行排满后自动换行 —— 用 `RowBreak` 强制换行，`EmptyCell` 占位跳过列。
+
+库内三个表单布局里最松散的一个：不需要 Row 边界，内容会随视口自适应回流。
+
+## 组件
+
+| 导出 | 用途 |
+|------|------|
+| `FlexForm`（默认） | 外层 wrapper —— flex-row，自动换行 |
+| `CellField` | 12 列跨度的 cell，内部包 [FormField](../../form_field/README_CN.md) |
+| `EmptyCell` | 空 cell 占位（同样 12 列跨度） |
+| `RowBreak` | 强制后续内容换到新行 |
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import FlexForm, { CellField, EmptyCell, RowBreak } from '@ticatec/topside-elements/FlexForm';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import FlexForm, { CellField } from '@ticatec/topside-elements/FlexForm';
+  import TextEditor from '@ticatec/topside-elements/TextEditor';
+</script>
+
+<FlexForm>
+  <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>
+</FlexForm>
+```
+
+三个 cell 占 3 + 3 + 6 = 12 列 → 正好一行。
+
+## 组件参考
+
+### `FlexForm`
+
+外层 wrapper。children 放在 flex-row 里自动换行。
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme` |
+| `children` | `Snippet \| undefined` | `undefined` | 表单内容（通常是 `CellField` / `EmptyCell` / `RowBreak`） |
+
+外层 CSS：
+
+```css
+.flex-form {
+  width: 100%;
+  padding: var(--topside-form-container-padding);
+}
+
+.flex-form > div {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;                /* ← 内容排满换行 */
+  row-gap: var(--topside-form-row-gap);
+}
+```
+
+### `CellField`
+
+12 列跨度的 cell，内部包 [FormField](../../form_field/README_CN.md)。渲染 label + children。
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `span` | `number` | `1` | 列跨度。夹到 1–12。每单位 = 行宽的 `100% / 12 ≈ 8.33%` |
+| `label` | `string` | `'Label'` | 标签文字，透传给 FormField |
+| `required` | `boolean` | `false` | 标签前显示红色 `*`（FormField 功能） |
+| `label$style` | `string` | `''` | 标签的内联 CSS |
+| `style` | `string` | `''` | 额外内联 CSS，**追加在**计算出的 `width: N%` 之后。用于 padding/margin 覆盖 |
+| `theme` | `string \| undefined` | `undefined` | 透传给 FormField |
+| `children` | `Snippet \| undefined` | `undefined` | 实际表单控件 |
+
+计算宽度：
+
+```js
+const generateCss = (sp) => `width: ${sp * 100 / 12}%`;   // 1 → 8.33%, 6 → 50%, 12 → 100%
+```
+
+`style` prop 追加在这个 width 之后 —— `${style}; width: N%`。如果你在 `style` 里写了 `width`，**你的会赢**（CSS 后写覆盖）—— 小心。
+
+### `EmptyCell`
+
+无内容的占位 cell。`span` 语义同 `CellField`。
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `span` | `number` | `1` | 列跨度（1–12，夹到范围内） |
+
+用于行内右对齐某个字段：前面放一个匹配 span 的 `EmptyCell`。
+
+### `RowBreak`
+
+强制后续 cell 换到新行。渲染 `<div style="width: 100%; height: 0;">`，利用 flex-wrap 行为断行。
+
+```svelte
+<FlexForm>
+  <CellField label="A" span={6} />
+  <RowBreak />
+  <CellField label="B" span={6} />   <!-- 虽然 A+B = 12，依然从新行开始 -->
+</FlexForm>
+```
+
+无 props。
+
+## 示例
+
+### 自适应换行
+
+cell 总 span 超过 12 时自动换行：
+
+```svelte
+<FlexForm>
+  <CellField label="A" span={4} />   <!-- 4 -->
+  <CellField label="B" span={4} />   <!-- 4 → 行总 8 -->
+  <CellField label="C" span={4} />   <!-- 4 → 行总 12，满 -->
+  <CellField label="D" span={4} />   <!-- 换到下一行 -->
+  <CellField label="E" span={4} />
+</FlexForm>
+```
+
+第 1 行：A、B、C。第 2 行：D、E。
+
+### 强制换行
+
+```svelte
+<FlexForm>
+  <CellField label="用户名" span={6} />
+  <CellField label="密码"   span={6} />
+  <RowBreak />
+  <CellField label="记住我" span={12} />
+</FlexForm>
+```
+
+### 用 EmptyCell 右对齐
+
+```svelte
+<FlexForm>
+  <CellField label="左" span={4} />
+  <EmptyCell span={4} />
+  <CellField label="右" span={4} />
+</FlexForm>
+```
+
+### 混合：CellField + EmptyCell + RowBreak
+
+```svelte
+<FlexForm>
+  <CellField label="标题"   span={8} required />
+  <CellField label="状态"   span={4} />
+  <RowBreak />
+  <CellField label="摘要"   span={12} />
+  <EmptyCell span={6} />
+  <CellField label="所有者" span={6} />
+</FlexForm>
+```
+
+## CSS 变量
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `--topside-form-container-padding` | （主题） | 外层 `FlexForm` wrapper 的 padding |
+| `--topside-form-row-gap` | （主题） | 换行后的行间距 |
+| `--topside-form-field-padding` | （主题） | 每个 cell 的 padding —— 实际由内部 FormField 消费 |
+
+> cell 级 padding 由 FormField 的 `--topside-form-field-padding` 令牌控制（CellField 渲染 FormField，后者把 padding 应用到自己的 wrapper 上）。全局或局部设这个令牌来调整 cell 间距。
+
+## 行为说明
+
+- **不滚动。** `FlexForm` 不限制高度、不滚动。需要的话外面套个容器
+- **children 是换行不是裁剪。** 总 span > 12 时，超出部分换到新行
+- **`RowBreak` 就是个 100% 宽 0 高的 div** —— 起作用是因为 flex-wrap 把 100% 宽的元素当成行填充物
+- **CellField 始终渲染 FormField**，意味着它从 context 继承 `getLayoutMode()`。在祖先里配 `setLayoutMode('horizontal' | 'vertical')`
+
+## 无障碍访问
+
+继承 FormField 的所有限制 —— **标签不会通过 `<label for>` 与内部控件关联**。详见 [FormField 的 a11y 说明](../../form_field/README_CN.md#无障碍访问)。
+
+## 相关组件
+
+- [FormField](../../form_field/README_CN.md) —— CellField 内部渲染的东西
+- [FlexRowForm](../flex_row_form/README_CN.md) —— 显式 `Row` 边界、纵向滚动的同胞
+- [GridForm](../grid_form/README_CN.md) —— 基于 CSS Grid（rowSpan / colSpan）的同胞

package/dist/layouts/form_panel/flex_form/RowBreak.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+</script>
+
+<div class="row-break"></div>
+
+<style>
+    .row-break {
+        width: 100%;
+        height: 0;
+    }
+</style>

package/dist/layouts/form_panel/flex_form/RowBreak.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const RowBreak: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type RowBreak = InstanceType<typeof RowBreak>;
+export default RowBreak;

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

@@ -0,0 +1,6 @@
+import FlexForm from "./FlexForm.svelte";
+import CellField from "./CellField.svelte";
+import EmptyCell from "./EmptyCell.svelte";
+import RowBreak from "./RowBreak.svelte";
+export default FlexForm;
+export { CellField, EmptyCell, RowBreak };

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

@@ -0,0 +1,6 @@
+import FlexForm from "./FlexForm.svelte";
+import CellField from "./CellField.svelte";
+import EmptyCell from "./EmptyCell.svelte";
+import RowBreak from "./RowBreak.svelte";
+export default FlexForm;
+export { CellField, EmptyCell, RowBreak };

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

@@ -0,0 +1,42 @@
+<script lang="ts">
+    import type {EditorVariant} from "../../../form/types";
+    import type {Snippet} from 'svelte';
+
+    interface Props {
+        style?: string;
+        span?: number;
+        /** 传给内部编辑器的外观变体 */
+        variant?: EditorVariant;
+        theme?: string;
+        children?: Snippet<[string | undefined, string | undefined]>;
+    }
+
+    let {
+        style = '',
+        span = 1,
+        variant,
+        theme,
+        children
+    }: Props = $props();
+
+    const ONE_CELL = 100 / 12;
+
+    const cs = $derived(Math.min(12, Math.max(1, Math.round(span || 1))));
+    const width = $derived(`${ONE_CELL * cs}%`);
+    const combinedStyle = $derived(`${style}; width: ${width}`);
+</script>
+
+<div class="form-cell {theme} {variant}" style={combinedStyle}>
+    {#if children}
+        {@render children(theme, variant)}
+    {/if}
+</div>
+
+<style>
+    .form-cell {
+        position: relative;
+        box-sizing: border-box;
+        flex: 0 0 auto;
+        padding: var(--topside-form-cell-padding);
+    }
+</style>

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

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

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

@@ -0,0 +1,45 @@
+<script lang="ts">
+    import type {Snippet} from 'svelte';
+
+    interface Props {
+        class?: string;
+        style?: string;
+        theme?: string;
+        children?: Snippet;
+    }
+
+    let {
+        class: className,
+        style = '',
+        theme,
+        children
+    }: Props = $props();
+</script>
+
+<div class="flex-row-form {className}" data-theme={theme} {style}>
+    <div>
+        {#if children}
+            {@render children()}
+        {/if}
+    </div>
+</div>
+
+<style>
+    .flex-row-form {
+        width: 100%;
+        position: relative;
+        overflow: hidden;
+        padding: var(--topside-form-container-padding);
+    }
+
+    .flex-row-form > div {
+        width: 100%;
+        height: 100%;
+        display: flex;
+        overflow: auto;
+        position: relative;
+        justify-items: start;
+        box-sizing: border-box;
+        flex-direction: column;
+    }
+</style>

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

@@ -0,0 +1,10 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    class?: string;
+    style?: string;
+    theme?: string;
+    children?: Snippet;
+}
+declare const FormContainer: import("svelte").Component<Props, {}, "">;
+type FormContainer = ReturnType<typeof FormContainer>;
+export default FormContainer;