@ticatec/topside-elements 1.0.0

package/docs/components/color-picker/README.md

@@ -0,0 +1,132 @@
+# ColorPicker
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+选择并编辑十六进制颜色值的表单控件。
+
+## 适用场景
+
+- 主题、标签和图表颜色配置
+- 需要原生色板与手工输入颜色值
+
+## 导入
+
+```ts
+import ColorPicker from '@ticatec/topside-elements/ColorPicker';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 主题样式名称，用于切换组件外观主题 |
+| `tooltip` | 否 | `string` | 否 | `undefined` | 否 | 悬停提示信息，鼠标悬浮在字段上时显示 |
+| `error` | 否 | `string` | 否 | `undefined` | 否 | 错误信息，用于在字段下方展示校验错误提示 |
+| `disabled` | 是 | `boolean` | 否 | `false` | 否 | 是否禁用该字段，禁用后字段不可编辑且不响应交互 |
+| `readonly` | 是 | `boolean` | 否 | `false` | 否 | 是否只读，只读状态下字段不可编辑但可聚焦和复制 |
+| `compact` | 否 | `boolean` | 否 | `false` | 否 | 是否启用紧凑模式，紧凑模式下字段内部间距更小 |
+| `variant` | 是 | `EditorVariant` | 否 | `undefined` | 否 | 编辑器外观样式变体 |
+| `placeholder` | 是 | `string` | 否 | `undefined` | 否 | 占位提示文本，字段值为空时在输入区域内展示 |
+| `style` | 否 | `string` | 否 | `undefined` | 否 | 自定义内联样式，会应用到字段根容器上 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段获得焦点时触发的回调 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段失去焦点时触发的回调 |
+| `onchange` | 是 | `(value?: any) => void` | 否 | `undefined` | 否 | 字段值发生变化时触发的回调 |
+| `value` | 是 | `string` | 否 | `$bindable<string \| undefined>("#000000")` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `disabled`
+
+是否禁用该字段，禁用后字段不可编辑且不响应交互
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`disabled={false}`
+
+### `readonly`
+
+是否只读，只读状态下字段不可编辑但可聚焦和复制
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`readonly={false}`
+
+### `variant`
+
+编辑器外观样式变体
+
+- 类型：`EditorVariant`
+- 默认值：`undefined`
+- 示例写法：`variant="plain"`
+
+### `placeholder`
+
+占位提示文本，字段值为空时在输入区域内展示
+
+- 类型：`string`
+- 默认值：`undefined`
+- 示例写法：`placeholder="请输入或选择"`
+
+### `onchange`
+
+字段值发生变化时触发的回调
+
+- 类型：`(value?: any) => void`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+### `value`
+
+组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。
+
+- 类型：`string`
+- 默认值：`$bindable<string | undefined>("#000000")`
+- 推荐写法：`bind:value`
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `focus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import ColorPicker from '@ticatec/topside-elements/ColorPicker';
+  let value = $state<any>('#2563eb');
+</script>
+
+<ColorPicker
+  bind:value
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+  variant="plain"
+  placeholder="请输入或选择"
+  disabled={false}
+  readonly={false}
+  compact={true}
+/>
+<p>当前状态：{JSON.stringify({value})}</p>
+```
+
+## 源码
+
+- `src/lib/form/color_picker/ColorPicker.svelte`

package/docs/components/color-picker/example.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import ColorPicker from '@ticatec/topside-elements/ColorPicker';
+  let value = $state<any>('#2563eb');
+</script>
+
+<ColorPicker
+  bind:value
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+  variant="plain"
+  placeholder="请输入或选择"
+  disabled={false}
+  readonly={false}
+  compact={true}
+/>
+<p>当前状态：{JSON.stringify({value})}</p>

package/docs/components/columns-layout/README.md

@@ -0,0 +1,74 @@
+# ColumnsLayout
+
+应用布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+以多列方式组织可调整区域的应用布局。
+
+## 适用场景
+
+- 主从视图和多面板工作台
+- 左右或多列区域需要独立宽度配置
+
+## 导入
+
+```ts
+import ColumnsLayout from '@ticatec/topside-elements/app-layout/ColumnsLayout';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `width` | 否 | `string` | 否 | `'100%'` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `height` | 否 | `string` | 否 | `'100%'` | 否 | 高度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `leftWidth` | 否 | `string \| null` | 否 | `null` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `rightWidth` | 否 | `string \| null` | 否 | `null` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `leftMinWidth` | 否 | `string \| null` | 否 | `null` | 否 | 左栏最小宽度（CSS 长度） |
+| `leftMaxWidth` | 否 | `string \| null` | 否 | `null` | 否 | 左栏最大宽度（CSS 长度） |
+| `rightMinWidth` | 否 | `string \| null` | 否 | `null` | 否 | 右栏最小宽度（CSS 长度） |
+| `rightMaxWidth` | 否 | `string \| null` | 否 | `null` | 否 | 右栏最大宽度（CSS 长度） |
+| `leftResize` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `rightResize` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `left` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+| `right` | 否 | `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 ColumnsLayout from '@ticatec/topside-elements/app-layout/ColumnsLayout';
+</script>
+
+<ColumnsLayout
+  width="240px"
+  height="48px"
+  leftWidth="240px"
+  rightWidth="240px"
+  leftMinWidth="240px"
+  leftMaxWidth="240px"
+  rightMinWidth="240px"
+  rightMaxWidth="240px"
+>
+  <div>在这里放置子内容</div>
+</ColumnsLayout>
+```
+
+## 源码
+
+- `src/lib/app_layout/ColumnsLayout.svelte`

package/docs/components/columns-layout/example.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import ColumnsLayout from '@ticatec/topside-elements/app-layout/ColumnsLayout';
+</script>
+
+<ColumnsLayout
+  width="240px"
+  height="48px"
+  leftWidth="240px"
+  rightWidth="240px"
+  leftMinWidth="240px"
+  leftMaxWidth="240px"
+  rightMinWidth="240px"
+  rightMaxWidth="240px"
+>
+  <div>在这里放置子内容</div>
+</ColumnsLayout>

package/docs/components/common-dialog/README.md

@@ -0,0 +1,118 @@
+# CommonDialog
+
+浮层与弹窗组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+带标准标题、内容和操作区的通用对话框壳。
+
+## 适用场景
+
+- 编辑表单和详情确认弹窗
+- 需要统一对话框结构的业务组件
+
+## 导入
+
+```ts
+import CommonDialog from '@ticatec/topside-elements/CommonDialog';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `title` | 是 | `string` | 是 | `—` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `width` | 否 | `string` | 否 | `'unset'` | 否 | 宽度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `height` | 否 | `string` | 否 | `'unset'` | 否 | 高度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `beforeClose` | 是 | `BeforeClose \| null` | 否 | `null` | 否 | 关闭前的否决钩子：结果为 MR_CANCEL / MR_CLOSE 时调用，返回 false 阻止关闭 |
+| `content$style` | 否 | `string` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `confirmable` | 否 | `boolean` | 否 | `true` | 否 | 确认按钮是否可用 |
+| `onconfirm` | 否 | `(() => Promise<any>) \| null` | 否 | `null` | 否 | 点击确认时调用；返回 truthy 值则以 MR_OK 关闭 |
+| `confirmText` | 否 | `string \| null` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `onclose` | 是 | `OnClose \| null` | 否 | `null` | 否 | 关闭后的通知回调，参数为 ModalResult |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `title`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`string`
+- 默认值：`—`
+- 示例写法：`title="示例标题"`
+
+### `beforeClose`
+
+关闭前的否决钩子：结果为 MR_CANCEL / MR_CLOSE 时调用，返回 false 阻止关闭
+
+- 类型：`BeforeClose | null`
+- 默认值：`null`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+### `onclose`
+
+关闭后的通知回调，参数为 ModalResult
+
+- 类型：`OnClose | null`
+- 默认值：`null`
+- 示例写法：`onclose={async (...args: any[]) => { console.log('onclose', ...args); return true; }}`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `BeforeClose`
+
+```ts
+export type BeforeClose = () => boolean | void | Promise<boolean | void>;
+```
+
+### `OnClose`
+
+```ts
+export type OnClose = (result: ModalResult) => void;
+```
+
+### `ModalResult`
+
+```ts
+export enum ModalResult {
+    MR_OK = 1,
+    MR_CANCEL = 2,
+    MR_CLOSE = 3
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import CommonDialog from '@ticatec/topside-elements/CommonDialog';
+</script>
+
+<CommonDialog
+  title="示例标题"
+  onconfirm={async (...args: any[]) => { console.log('onconfirm', ...args); return true; }}
+  onclose={async (...args: any[]) => { console.log('onclose', ...args); return true; }}
+  width="240px"
+  height="48px"
+>
+  <div>在这里放置子内容</div>
+</CommonDialog>
+```
+
+## 源码
+
+- `src/lib/overlay/dialog/CommonDialog.svelte`

package/docs/components/common-dialog/example.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+  import CommonDialog from '@ticatec/topside-elements/CommonDialog';
+</script>
+
+<CommonDialog
+  title="示例标题"
+  onconfirm={async (...args: any[]) => { console.log('onconfirm', ...args); return true; }}
+  onclose={async (...args: any[]) => { console.log('onclose', ...args); return true; }}
+  width="240px"
+  height="48px"
+>
+  <div>在这里放置子内容</div>
+</CommonDialog>

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

@@ -0,0 +1,296 @@
+# ConciseDataTable
+
+数据展示组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+轻量紧凑的数据表格，适合快速展示较少列。
+
+## 适用场景
+
+- 弹窗内列表和摘要数据
+- 不需要复杂冻结列与行操作的表格
+
+## 导入
+
+```ts
+import ConciseDataTable from '@ticatec/topside-elements/ConciseDataTable';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `list` | 是 | `Array<any>` | 是 | `—` | 否 | 组件展示的数据集合。数据项结构由相关列、字段映射或渲染器决定。 |
+| `columns` | 是 | `Array<Column>` | 是 | `—` | 否 | 表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。 |
+| `autoScroll` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `scrollInterval` | 否 | `number` | 否 | `2000` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `onRowClick` | 否 | `OnRowClick \| null` | 否 | `null` | 否 | 行点击回调 |
+| `options` | 是 | `TableOptions` | 否 | `{}` | 否 | 可选项数据源；通常配合 `keyField` 与 `textField` 指定值字段和显示字段。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `class` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的 CSS class。 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件获得焦点时调用。 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件失去焦点时调用。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `list`
+
+组件展示的数据集合。数据项结构由相关列、字段映射或渲染器决定。
+
+- 类型：`Array<any>`
+- 默认值：`—`
+- 示例写法：`list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}`
+
+### `columns`
+
+表格列定义，控制字段、标题、宽度、格式化、链接和自定义渲染。
+
+- 类型：`Array<Column>`
+- 默认值：`—`
+- 示例写法：`columns={[
+    {field: 'name', title: '姓名', width: 160},
+    {field: 'department', title: '部门', width: 180}
+  ]}`
+
+### `options`
+
+可选项数据源；通常配合 `keyField` 与 `textField` 指定值字段和显示字段。
+
+- 类型：`TableOptions`
+- 默认值：`{}`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `focus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `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;
+
+}
+```
+
+### `OnRowClick`
+
+```ts
+export type OnRowClick = (row:any) => void;
+```
+
+### `TableOptions`
+
+```ts
+export interface TableOptions {
+    //表格的背景色
+    backgroundColor?: string;
+    //表格的文字颜色
+    color?: string;
+    //标题行高
+    headerHeight?: number;
+    //标题行的背景色
+    headerBackgroundColor?: string;
+    //标题行文字颜色
+    headerColor?: string;
+    //间隔行背景色
+    alternativeBackgroundColor?: string;
+    //间隔行颜色
+    alternativeColor?: string;
+    //数据行高度
+    rowHeight?: number;
+}
+```
+
+### `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;
+}
+```
+
+### `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;
+```
+
+### `HrefLink`
+
+```ts
+export default interface HrefLink {
+    /**
+     * 显示超链接的文字
+     */
+    label: string;
+    /**
+     * 点击的处理函数
+     */
+    handler: OnHrefClick;
+}
+```
+
+### `OnHrefClick`
+
+```ts
+export type OnHrefClick = () => void;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import ConciseDataTable from '@ticatec/topside-elements/ConciseDataTable';
+</script>
+
+<ConciseDataTable
+  list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}
+  columns={[
+    {field: 'name', title: '姓名', width: 160},
+    {field: 'department', title: '部门', width: 180}
+  ]}
+  onRowClick={async (...args: any[]) => { console.log('onRowClick', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+/>
+```
+
+## 源码
+
+- `src/lib/data_display/concise_data_table/ConciseListTable.svelte`

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

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import ConciseDataTable from '@ticatec/topside-elements/ConciseDataTable';
+</script>
+
+<ConciseDataTable
+  list={[
+    {id: 1, name: '张三', department: '研发部'},
+    {id: 2, name: '李四', department: '产品部'}
+  ]}
+  columns={[
+    {field: 'name', title: '姓名', width: 160},
+    {field: 'department', title: '部门', width: 180}
+  ]}
+  onRowClick={async (...args: any[]) => { console.log('onRowClick', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+/>