@ticatec/topside-elements 1.0.0

package/docs/components/context-menu/README.md

@@ -0,0 +1,99 @@
+# ContextMenu
+
+命令式服务。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+通过命令式 API 在鼠标位置显示上下文菜单。
+
+## 适用场景
+
+- 表格行、树节点和画布右键操作
+- 需要根据当前对象动态构建菜单项
+
+## 导入
+
+```ts
+import ContextMenu from '@ticatec/topside-elements/ContextMenu';
+```
+
+## 公开成员与方法
+
+| 成员 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `visible` | 是 | `boolean` | 否 | `$state(false)` | 是 | 内部响应式状态：标记当前是否正在显示。由 `show()`/`hide()` 等方法统一管理；这是一个单例服务而非组件，不能使用 `bind:visible`，不建议直接修改。 |
+| `position` | 是 | `{ x: number; y: number }` | 否 | `$state({ x: 0, y: 0 })` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:position`，仅供参考，不建议直接修改。 |
+| `items` | 是 | `ContextMenuItem[]` | 否 | `$state<ContextMenuItem[]>([])` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:items`，仅供参考，不建议直接修改。 |
+| `width` | 是 | `number` | 否 | `$state(150)` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:width`，仅供参考，不建议直接修改。 |
+| `height` | 是 | `number` | 否 | `$state(150)` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:height`，仅供参考，不建议直接修改。 |
+| `theme` | 是 | `unknown` | 否 | `$state()` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:theme`，仅供参考，不建议直接修改。 |
+| `show()` | 否 | `(event: MouseEvent, list: ContextMenuItem[], width = 150, height = 150, currentTheme?: string) => void` | 否 | `—` | 否 | 唤起右键菜单 |
+| `hide()` | 否 | `() => void` | 否 | `—` | 否 | 关闭右键菜单 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `ContextMenuItem`
+
+```ts
+export interface ContextMenuItem {
+    /**
+     * Display text for the menu item
+     */
+    label?: string;
+
+    /**
+     * Action to execute when item is clicked
+     */
+    handler?: ContextMenuAction;
+
+    /**
+     * Whether the item is disabled
+     */
+    disabled?: boolean;
+
+    /**
+     * Whether this is a separator item
+     */
+    separator?: boolean;
+
+    /**
+     * Icon class or name for the menu item
+     */
+    icon?: string;
+
+    /**
+     * Custom CSS styles for the item
+     */
+    style?: string;
+}
+```
+
+### `ContextMenuAction`
+
+```ts
+export type ContextMenuAction = () => void;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import ContextMenu from '@ticatec/topside-elements/ContextMenu';
+
+  function openMenu(event: MouseEvent) {
+    event.preventDefault();
+    ContextMenu.show(event, [{label: '查看', handler: () => console.log('查看')}]);
+  }
+</script>
+
+<button type="button" oncontextmenu={openMenu}>在此区域右键点击</button>
+```
+
+## 源码
+
+- `src/lib/overlay/context-menu/ContextMenu.svelte.ts`

package/docs/components/context-menu/example.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import ContextMenu from '@ticatec/topside-elements/ContextMenu';
+
+  function openMenu(event: MouseEvent) {
+    event.preventDefault();
+    ContextMenu.show(event, [{label: '查看', handler: () => console.log('查看')}]);
+  }
+</script>
+
+<button type="button" oncontextmenu={openMenu}>在此区域右键点击</button>

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

@@ -0,0 +1,70 @@
+# CriteriaField
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+用于搜索条件区域的带标签字段容器。
+
+## 适用场景
+
+- 高级查询和筛选面板
+- 需要统一排列查询控件与字段标签
+
+## 导入
+
+```ts
+import CriteriaField from '@ticatec/topside-elements/CriteriaField';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `label` | 是 | `string` | 是 | `—` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `label$style` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `labelSuffix` | 否 | `string` | 否 | `':'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `children` | 是 | `Snippet` | 是 | `—` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+| `size` | 否 | `'' \| 'x15' \| 'x20' \| 'x25' \| 'x30' \| 'x35' \| 'x40'` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `label`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`string`
+- 默认值：`—`
+- 示例写法：`label="示例标签"`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`—`
+- 示例写法：`children={children}`
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import CriteriaField from '@ticatec/topside-elements/CriteriaField';
+</script>
+
+<CriteriaField
+  label="示例标签"
+  size="x15"
+>
+  <div>在这里放置子内容</div>
+</CriteriaField>
+```
+
+## 源码
+
+- `src/lib/layouts/criteria_field/CriteriaField.svelte`

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

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

package/docs/components/data-table/README.md

@@ -0,0 +1,388 @@
+# DataTable
+
+数据表格组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+支持列配置、选择、操作、冻结和扩展行的数据表格。
+
+## 适用场景
+
+- 企业列表页和大数据管理界面
+- 需要排序、选择、自定义单元格或行操作
+
+## 导入
+
+```ts
+import DataTable from '@ticatec/topside-elements/DataTable';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `columns` | 是 | `Array<DataColumn>` | 是 | `—` | 否 | 表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。 |
+| `actionsColumn` | 否 | `ActionsColumn<T> \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `indicatorColumn` | 否 | `IndicatorColumn \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `rowHeight` | 否 | `number` | 否 | `42` | 否 | 高度配置，数值单位为像素。 |
+| `headerHeight` | 否 | `number` | 否 | `48` | 否 | 高度配置，数值单位为像素。 |
+| `list` | 是 | `Array<T>` | 是 | `—` | 否 | 组件展示的数据集合。数据项结构由相关列、字段映射或渲染器决定。 |
+| `selectedRows` | 是 | `Array<T>` | 否 | `$bindable([])` | 是 | 当前选中的行数据数组，推荐使用 `bind:selectedRows`；数组项与 `list` 中的数据引用一致。 |
+| `inlineRowHeight` | 是 | `number` | 否 | `$bindable(80)` | 是 | 高度配置，数值单位为像素。 |
+| `rowBorder` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `colBorder` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `emptyText` | 否 | `string` | 否 | `undefined` | 否 | 无数据时显示的文案 |
+| `getRowFontStyle` | 否 | `GetRowFontStyle<T>` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `virtual` | 否 | `boolean` | 否 | `false` | 否 | 行虚拟化(窗口化渲染):仅渲染可视区域附近的行,大数据集(数千行以上) 建议开启。要求所有行高度一致(即统一的 rowHeight),因此默认关闭。 |
+| `overscan` | 否 | `number` | 否 | `8` | 否 | 虚拟化时可视区上下额外渲染的行数。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `columns`
+
+表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。
+
+- 类型：`Array<DataColumn>`
+- 默认值：`—`
+- 示例写法：`columns={[
+    {field: 'name', title: '姓名', width: 160},
+    {field: 'department', title: '部门', width: 180}
+  ]}`
+
+### `list`
+
+组件展示的数据集合。数据项结构由相关列、字段映射或渲染器决定。
+
+- 类型：`Array<T>`
+- 默认值：`—`
+- 示例写法：`list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}`
+
+### `selectedRows`
+
+当前选中的行数据数组，推荐使用 `bind:selectedRows`；数组项与 `list` 中的数据引用一致。
+
+- 类型：`Array<T>`
+- 默认值：`$bindable([])`
+- 推荐写法：`bind:selectedRows`
+
+### `inlineRowHeight`
+
+高度配置，数值单位为像素。
+
+- 类型：`number`
+- 默认值：`$bindable(80)`
+- 推荐写法：`bind:inlineRowHeight`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `DataColumn`
+
+```ts
+export default interface DataColumn {
+
+    /**
+     * 列头文字（与 ConciseListTable 的 Column.title 统一）
+     */
+    title: string;
+
+    /**
+     * 对应的字段/属性名
+     */
+    field?: string;
+
+    /**
+     * 是否冻结在数据表中，如果前面的frozen是false，那么就无效
+     */
+    frozen?: boolean;
+
+    /**
+     * 对齐方式
+     */
+    align?: 'left' | 'center' | 'right';
+
+    /**
+     *
+     */
+    width: number;
+
+    minWidth?: number;
+
+    /**
+     * 是否可以换行，默认为false
+     */
+    wrap?: boolean;
+
+    /**
+     * 单元格转换函数
+     */
+    formatter?: FormatCellFn;
+
+    /**
+     * 是否将单元格内容作为可信 HTML 渲染（{@html}），而非纯文本转义。
+     * 仅当 field/formatter 输出为可信标记时才应设为 true。
+     */
+    renderHTML?: boolean;
+
+
+    /**
+     * 超链接设置
+     */
+    href?: HrefBuilder;
+
+    /**
+     * 是否生产hint
+     */
+    hint?: CellHint;
+
+    /**
+     * 渲染器
+     */
+    render?: any;
+
+    /**
+     *
+     */
+    visible?: boolean;
+
+    /**
+     *
+     */
+    resizable?: boolean;
+
+    /**
+     *
+     */
+    compareFunction?: CompareFn;
+
+    /**
+     * 获取表格的样式
+     */
+    cellStyle?: GetCellStyle;
+}
+```
+
+### `ActionsColumn`
+
+```ts
+export default interface ActionsColumn<T = any> {
+    /**
+     * 宽度
+     */
+    width: number;
+    /**
+     *
+     */
+    getActions: GetRowActions<T>;
+
+    /**
+     * 对齐方式，默认靠左对齐
+     */
+    align?: 'left' | 'center';
+}
+```
+
+### `IndicatorColumn`
+
+```ts
+export default interface IndicatorColumn {
+    /**
+     *
+     */
+    width: number;
+    /**
+     *
+     */
+    selectable?: boolean;
+
+    /**
+     *
+     */
+    buildInlineComponent?: (data:any) => Promise<any>;
+
+
+    /**
+     * 是否显示行号
+     */
+    /** 是否显示行号 */
+    showRowNo?: boolean
+}
+```
+
+### `GetRowFontStyle`
+
+```ts
+export type GetRowFontStyle<T = any> = (data: T) => RowFontStyle;
+```
+
+### `Column`
+
+```ts
+export default interface Column {
+    // Display title for column header
+    title: string;
+    // Field name in data object
+    field: string;
+    // Width in pixels
+    width: number;
+    // Alignment: "left", "center", "right"
+    align?: "left" | "center" | "right",
+    // Flex weight: 0 = fixed width, >0 = proportional scaling
+    weight?: number;
+    // Optional formatter function
+    formatter?: (value: any) => string
+    // When true, the cell's (formatted) value is rendered as raw HTML ({@html}).
+    // Defaults to false/unset (safe, escaped plain text). Only set true when the
+    // field/formatter output is trusted markup — this is the same opt-in semantic as
+    // DataColumn#renderHTML in the data_table component.
+    renderHTML?: boolean;
+
+}
+```
+
+### `FormatCellFn`
+
+```ts
+export type FormatCellFn = (value: any) => string;
+```
+
+### `HrefBuilder`
+
+```ts
+export type HrefBuilder = (item: any) => Array<HrefLink> | HrefLink | string;
+```
+
+### `CellHint`
+
+```ts
+export type CellHint = (value: any) => string;
+```
+
+### `CompareFn`
+
+```ts
+export type CompareFn = (o1: any, o2: any) => number;
+```
+
+### `GetCellStyle`
+
+```ts
+export type GetCellStyle = (data: any) => string;
+```
+
+### `GetRowActions`
+
+```ts
+export type GetRowActions<T = any> = (item: T) => Array<RowAction<T>>;
+```
+
+### `RowFontStyle`
+
+```ts
+export interface RowFontStyle {
+    /**
+     * 字体大小
+     */
+    size?: string;
+    /**
+     * 字体颜色
+     */
+    color?: string;
+    /**
+     * 字重
+     */
+    weight?: number | string;
+}
+```
+
+### `HrefLink`
+
+```ts
+export default interface HrefLink {
+    /**
+     * 显示超链接的文字
+     */
+    label: string;
+    /**
+     * 点击的处理函数
+     */
+    handler: OnHrefClick;
+}
+```
+
+### `RowAction`
+
+```ts
+export default interface RowAction<T = any> {
+    /** 显示文字 */
+    label: string;
+    /** 语义类型 */
+    type?: ButtonType;
+    /** 前缀图标 */
+    icon?: string;
+    /** 提示 */
+    tooltip?: string;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 点击处理 */
+    handler: ActionHandler<T>;
+}
+```
+
+### `OnHrefClick`
+
+```ts
+export type OnHrefClick = () => void;
+```
+
+### `ButtonType`
+
+```ts
+export type ButtonType = 'default' | 'primary' | 'secondary' | 'third' | 'forth';
+```
+
+### `ActionHandler`
+
+```ts
+export type ActionHandler<T = any> = (data: T) => void | Promise<void>;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import DataTable from '@ticatec/topside-elements/DataTable';
+  let selectedRows = $state<any>([]);
+  let inlineRowHeight = $state<any>(80);
+</script>
+
+<DataTable
+  columns={[
+    {field: 'name', title: '姓名', width: 160},
+    {field: 'department', title: '部门', width: 180}
+  ]}
+  list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}
+  bind:selectedRows
+  bind:inlineRowHeight
+  rowBorder={true}
+  colBorder={true}
+  rowHeight={48}
+  headerHeight={48}
+/>
+<p>当前状态：{JSON.stringify({selectedRows, inlineRowHeight})}</p>
+```
+
+## 源码
+
+- `src/lib/data_table/DataTable.svelte`

package/docs/components/data-table/example.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+  import DataTable from '@ticatec/topside-elements/DataTable';
+  let selectedRows = $state<any>([]);
+  let inlineRowHeight = $state<any>(80);
+</script>
+
+<DataTable
+  columns={[
+    {field: 'name', title: '姓名', width: 160},
+    {field: 'department', title: '部门', width: 180}
+  ]}
+  list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}
+  bind:selectedRows
+  bind:inlineRowHeight
+  rowBorder={true}
+  colBorder={true}
+  rowHeight={48}
+  headerHeight={48}
+/>
+<p>当前状态：{JSON.stringify({selectedRows, inlineRowHeight})}</p>