@ticatec/topside-elements 1.0.0

package/docs/components/drawer/README.md

@@ -0,0 +1,70 @@
+# Drawer
+
+浮层与弹窗组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+从页面边缘滑出的抽屉式内容层。
+
+## 适用场景
+
+- 筛选面板、详情侧栏和移动端菜单
+- 希望保留当前页面上下文的辅助操作
+
+## 导入
+
+```ts
+import Drawer from '@ticatec/topside-elements/Drawer';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `visible` | 是 | `boolean` | 否 | `$bindable(false)` | 是 | 控制组件是否显示，通常使用 `bind:visible` 管理打开和关闭。 |
+| `width` | 否 | `number` | 否 | `300` | 否 | 宽度配置，数值单位为像素。 |
+| `position` | 否 | `'left' \| 'right'` | 否 | `'left'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `visible`
+
+控制组件是否显示，通常使用 `bind:visible` 管理打开和关闭。
+
+- 类型：`boolean`
+- 默认值：`$bindable(false)`
+- 推荐写法：`bind:visible`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Drawer from '@ticatec/topside-elements/Drawer';
+  let visible = $state<any>(false);
+</script>
+
+<Drawer
+  bind:visible
+  width={240}
+>
+  <div>在这里放置子内容</div>
+</Drawer>
+<p>当前状态：{JSON.stringify({visible})}</p>
+```
+
+## 源码
+
+- `src/lib/overlay/drawer/Drawer.svelte`

package/docs/components/drawer/example.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import Drawer from '@ticatec/topside-elements/Drawer';
+  let visible = $state<any>(false);
+</script>
+
+<Drawer
+  bind:visible
+  width={240}
+>
+  <div>在这里放置子内容</div>
+</Drawer>
+<p>当前状态：{JSON.stringify({visible})}</p>

package/docs/components/flex-form/README.md

@@ -0,0 +1,55 @@
+# FlexForm
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+使用 Flex 布局排列字段的表单容器。
+
+## 适用场景
+
+- 字段宽度灵活的响应式表单
+- 简单横向或自动换行的字段布局
+
+## 导入
+
+```ts
+import FlexForm from '@ticatec/topside-elements/FlexForm';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import FlexForm from '@ticatec/topside-elements/FlexForm';
+</script>
+
+<FlexForm>
+  <div>在这里放置子内容</div>
+</FlexForm>
+```
+
+## 源码
+
+- `src/lib/layouts/form_panel/flex_form/FlexForm.svelte`

package/docs/components/flex-form/example.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+  import FlexForm from '@ticatec/topside-elements/FlexForm';
+</script>
+
+<FlexForm>
+  <div>在这里放置子内容</div>
+</FlexForm>

package/docs/components/flex-row-form/README.md

@@ -0,0 +1,56 @@
+# FlexRowForm
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+按行组织字段并支持弹性宽度的表单布局。
+
+## 适用场景
+
+- 查询条件行和紧凑编辑行
+- 需要一行多个字段并自适应剩余空间
+
+## 导入
+
+```ts
+import FlexRowForm from '@ticatec/topside-elements/FlexRowForm';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `class` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的 CSS class。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import FlexRowForm from '@ticatec/topside-elements/FlexRowForm';
+</script>
+
+<FlexRowForm>
+  <div>在这里放置子内容</div>
+</FlexRowForm>
+```
+
+## 源码
+
+- `src/lib/layouts/form_panel/flex_row_form/FormContainer.svelte`

package/docs/components/flex-row-form/example.svelte

@@ -0,0 +1,7 @@
+<script lang="ts">
+  import FlexRowForm from '@ticatec/topside-elements/FlexRowForm';
+</script>
+
+<FlexRowForm>
+  <div>在这里放置子内容</div>
+</FlexRowForm>

package/docs/components/form-field/README.md

@@ -0,0 +1,84 @@
+# FormField
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+为输入控件提供标签、提示和错误区域的标准字段容器。
+
+## 适用场景
+
+- 编辑表单中的单个字段
+- 统一标签宽度、必填标记和校验信息
+
+## 导入
+
+```ts
+import FormField from '@ticatec/topside-elements/FormField';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `style` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的内联样式。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `label` | 是 | `string` | 是 | `—` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `label$style` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `labelSuffix` | 否 | `string` | 否 | `':'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `label$alignment` | 否 | `'center' \| 'top'` | 否 | `'center'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `autoHeight` | 否 | `boolean` | 否 | `undefined` | 否 | 高度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `required` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `direction` | 否 | `Direction` | 否 | `getLayoutMode()` | 否 | 标签与控件的排布方向 |
+| `class` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的 CSS class。 |
+| `children` | 是 | `Snippet` | 是 | `—` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `label`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`string`
+- 默认值：`—`
+- 示例写法：`label="示例标签"`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`—`
+- 示例写法：`children={children}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `Direction`
+
+```ts
+export type Direction = 'vertical' | 'horizontal';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import FormField from '@ticatec/topside-elements/FormField';
+</script>
+
+<FormField
+  label="示例标签"
+  autoHeight={true}
+>
+  <div>在这里放置子内容</div>
+</FormField>
+```
+
+## 源码
+
+- `src/lib/layouts/form_field/FormField.svelte`

package/docs/components/form-field/example.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import FormField from '@ticatec/topside-elements/FormField';
+</script>
+
+<FormField
+  label="示例标签"
+  autoHeight={true}
+>
+  <div>在这里放置子内容</div>
+</FormField>

package/docs/components/full-screen-overlay/README.md

@@ -0,0 +1,66 @@
+# FullScreenOverlay
+
+浮层与弹窗组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+覆盖整个视口的全屏浮层容器。
+
+## 适用场景
+
+- 全屏加载、预览和阻断式操作
+- 需要暂时隔离底层页面交互
+
+## 导入
+
+```ts
+import FullScreenOverlay from '@ticatec/topside-elements/FullScreenOverlay';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `visible` | 是 | `boolean` | 否 | `$bindable(false)` | 是 | 控制组件是否显示，通常使用 `bind:visible` 管理打开和关闭。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `visible`
+
+控制组件是否显示，通常使用 `bind:visible` 管理打开和关闭。
+
+- 类型：`boolean`
+- 默认值：`$bindable(false)`
+- 推荐写法：`bind:visible`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import FullScreenOverlay from '@ticatec/topside-elements/FullScreenOverlay';
+  let visible = $state<any>(false);
+</script>
+
+<FullScreenOverlay
+  bind:visible
+>
+  <div>在这里放置子内容</div>
+</FullScreenOverlay>
+<p>当前状态：{JSON.stringify({visible})}</p>
+```
+
+## 源码
+
+- `src/lib/overlay/common/FullscreenOverlay.svelte`

package/docs/components/full-screen-overlay/example.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import FullScreenOverlay from '@ticatec/topside-elements/FullScreenOverlay';
+  let visible = $state<any>(false);
+</script>
+
+<FullScreenOverlay
+  bind:visible
+>
+  <div>在这里放置子内容</div>
+</FullScreenOverlay>
+<p>当前状态：{JSON.stringify({visible})}</p>

package/docs/components/grid-form/README.md

@@ -0,0 +1,85 @@
+# GridForm
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+使用 CSS Grid 精确排列字段的表单容器。
+
+## 适用场景
+
+- 列数固定的复杂编辑表单
+- 需要字段跨列、对齐和稳定网格结构
+
+## 导入
+
+```ts
+import GridForm from '@ticatec/topside-elements/GridForm';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `columns` | 是 | `number` | 否 | `6` | 否 | 表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。 |
+| `variant` | 是 | `EditorVariant` | 否 | `undefined` | 否 | 传给内部编辑器的外观变体 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `children` | 是 | `Snippet<[string \| undefined, string \| undefined]>` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `columns`
+
+表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。
+
+- 类型：`number`
+- 默认值：`6`
+- 示例写法：`columns={1}`
+
+### `variant`
+
+传给内部编辑器的外观变体
+
+- 类型：`EditorVariant`
+- 默认值：`undefined`
+- 示例写法：`variant="plain"`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet<[string | undefined, string | undefined]>`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import GridForm from '@ticatec/topside-elements/GridForm';
+</script>
+
+<GridForm
+  variant="plain"
+>
+  <div>在这里放置子内容</div>
+</GridForm>
+```
+
+## 源码
+
+- `src/lib/layouts/form_panel/grid_form/GridForm.svelte`

package/docs/components/grid-form/example.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+  import GridForm from '@ticatec/topside-elements/GridForm';
+</script>
+
+<GridForm
+  variant="plain"
+>
+  <div>在这里放置子内容</div>
+</GridForm>

package/docs/components/group-check-box/README.md

@@ -0,0 +1,147 @@
+# GroupCheckBox
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+以成组方式展示多个可同时选择的复选项。
+
+## 适用场景
+
+- 权限、标签和兴趣多选
+- 选项较少且需要直接平铺展示
+
+## 导入
+
+```ts
+import GroupCheckBox from '@ticatec/topside-elements/GroupCheckBox';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `disabled` | 是 | `boolean` | 否 | `false` | 否 | 禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。 |
+| `readonly` | 是 | `boolean` | 否 | `false` | 否 | 只读状态。保留内容展示，但阻止用户修改。 |
+| `style` | 否 | `string` | 否 | `""` | 否 | 附加到组件根元素的内联样式。 |
+| `error` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `tooltip` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `value` | 是 | `string \| number` | 是 | `$bindable()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+| `bitBase` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `options` | 是 | `Array<OptionItem>` | 是 | `—` | 否 | 可选项数据源；通常配合 `keyField` 与 `textField` 指定值字段和显示字段。 |
+| `keyField` | 否 | `string` | 否 | `"code"` | 否 | 数据项中作为唯一值或选中值的字段名。 |
+| `textField` | 否 | `string` | 否 | `"text"` | 否 | 数据项中用于界面显示的文本字段名。 |
+| `delimiter` | 否 | `string` | 否 | `';'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `item$style` | 否 | `string` | 否 | `''` | 否 | 每个选项的内联样式 |
+| `disabledOptions` | 否 | `Array<string>` | 否 | `[]` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `hideOptions` | 否 | `Array<string>` | 否 | `[]` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `variant` | 是 | `EditorVariant` | 否 | `undefined` | 否 | 视觉样式变体，可选值：`""`(默认)、`plain`、`outlined`、`filled`；具体含义见组件说明。 |
+| `compact` | 否 | `boolean` | 否 | `false` | 否 | 启用紧凑尺寸，减少组件高度和内边距。 |
+| `class` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的 CSS class。 |
+| `onchange` | 是 | `(value: any) => void` | 否 | `undefined` | 否 | 用户完成值变更时调用；编程式赋值是否触发请以组件行为说明为准。 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件失去焦点时调用。 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件获得焦点时调用。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `disabled`
+
+禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`disabled={false}`
+
+### `readonly`
+
+只读状态。保留内容展示，但阻止用户修改。
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`readonly={false}`
+
+### `value`
+
+组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。
+
+- 类型：`string | number`
+- 默认值：`$bindable()`
+- 推荐写法：`bind:value`
+
+### `options`
+
+可选项数据源；通常配合 `keyField` 与 `textField` 指定值字段和显示字段。
+
+- 类型：`Array<OptionItem>`
+- 默认值：`—`
+- 示例写法：`options={[
+    {code: 'dev', text: '研发部'},
+    {code: 'product', text: '产品部'}
+  ]}`
+
+### `variant`
+
+视觉样式变体，可选值：`""`(默认)、`plain`、`outlined`、`filled`；具体含义见组件说明。
+
+- 类型：`EditorVariant`
+- 默认值：`undefined`
+- 示例写法：`variant="plain"`
+
+### `onchange`
+
+用户完成值变更时调用；编程式赋值是否触发请以组件行为说明为准。
+
+- 类型：`(value: any) => void`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `focus()` | `() => void` | 导出 focus 方法 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import GroupCheckBox from '@ticatec/topside-elements/GroupCheckBox';
+  let value = $state<any>("示例值");
+</script>
+
+<GroupCheckBox
+  bind:value
+  options={[
+    {code: 'dev', text: '研发部'},
+    {code: 'product', text: '产品部'}
+  ]}
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onblur={async (...args: any[]) => { console.log('onblur', ...args); return true; }}
+  keyField="code"
+  textField="text"
+  variant="plain"
+  disabled={false}
+  readonly={false}
+  compact={true}
+/>
+<p>当前状态：{JSON.stringify({value})}</p>
+```
+
+## 源码
+
+- `src/lib/form/group_box/group-check-box/GroupCheckBox.svelte`

package/docs/components/group-check-box/example.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import GroupCheckBox from '@ticatec/topside-elements/GroupCheckBox';
+  let value = $state<any>("示例值");
+</script>
+
+<GroupCheckBox
+  bind:value
+  options={[
+    {code: 'dev', text: '研发部'},
+    {code: 'product', text: '产品部'}
+  ]}
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onblur={async (...args: any[]) => { console.log('onblur', ...args); return true; }}
+  keyField="code"
+  textField="text"
+  variant="plain"
+  disabled={false}
+  readonly={false}
+  compact={true}
+/>
+<p>当前状态：{JSON.stringify({value})}</p>