@ticatec/topside-elements 1.0.0

package/docs/components/tabs/example.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import Tabs from '@ticatec/topside-elements/Tabs';
+  let tabs = $state<any>([
+    {id: 'overview', text: '概览'},
+    {id: 'settings', text: '设置'}
+  ]);
+  let activeTab = $state<any>();
+</script>
+
+<Tabs
+  bind:tabs
+  bind:activeTab
+  onrefresh={async (...args: any[]) => { console.log('onrefresh', ...args); return true; }}
+  onremove={async (...args: any[]) => { console.log('onremove', ...args); return true; }}
+  textField="text"
+  keyField="id"
+  closable={true}
+  maxTabWidth={240}
+>
+  <div>在这里放置子内容</div>
+</Tabs>
+<p>当前状态：{JSON.stringify({tabs, activeTab})}</p>

package/docs/components/tag/README.md

@@ -0,0 +1,74 @@
+# Tag
+
+通用组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+以紧凑标签展示分类、状态或可删除项。
+
+## 适用场景
+
+- 状态徽标、筛选条件和已选项
+- 需要颜色区分或点击删除的小块信息
+
+## 导入
+
+```ts
+import Tag from '@ticatec/topside-elements/Tag';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `size` | 否 | `Size` | 否 | `'medium'` | 否 | 尺寸档位 |
+| `variant` | 是 | `'borderless' \| 'border' \| 'round'` | 否 | `'border'` | 否 | 视觉样式变体，可选值：`borderless`、`border`、`round`；具体含义见组件说明。 |
+| `removable` | 否 | `boolean` | 否 | `true` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `data` | 否 | `any` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `text` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `style` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的内联样式。 |
+| `class` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的 CSS class。 |
+| `ondelete` | 否 | `(data?: any)=>void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `color` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `variant`
+
+视觉样式变体，可选值：`borderless`、`border`、`round`；具体含义见组件说明。
+
+- 类型：`'borderless' | 'border' | 'round'`
+- 默认值：`'border'`
+- 示例写法：`variant="borderless"`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `Size`
+
+```ts
+export type Size = 'small' | 'medium' | 'large';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Tag from '@ticatec/topside-elements/Tag';
+</script>
+
+<Tag
+  ondelete={async (...args: any[]) => { console.log('ondelete', ...args); return true; }}
+  variant="borderless"
+  size="small"
+/>
+```
+
+## 源码
+
+- `src/lib/general/tag/Tag.svelte`

package/docs/components/tag/example.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+  import Tag from '@ticatec/topside-elements/Tag';
+</script>
+
+<Tag
+  ondelete={async (...args: any[]) => { console.log('ondelete', ...args); return true; }}
+  variant="borderless"
+  size="small"
+/>

package/docs/components/text-button/README.md

@@ -0,0 +1,109 @@
+# TextButton
+
+通用组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+弱化边框和背景的文字操作按钮。
+
+## 适用场景
+
+- 表格行操作、链接式命令和次要操作
+- 不希望抢占主要按钮视觉层级
+
+## 导入
+
+```ts
+import TextButton from '@ticatec/topside-elements/TextButton';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `disabled` | 是 | `boolean` | 否 | `false` | 否 | 禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。 |
+| `size` | 否 | `Size` | 否 | `'medium'` | 否 | 尺寸档位 |
+| `label` | 否 | `string` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `type` | 否 | `ButtonType` | 否 | `'default'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `htmlType` | 否 | `'button' \| 'submit' \| 'reset'` | 否 | `'button'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `onclick` | 是 | `(event: MouseEvent) => void` | 否 | `undefined` | 否 | 用户点击组件时调用，参数通常为 MouseEvent。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `tooltip` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+| `tabindex` | 否 | `number` | 否 | `-1` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `outer` | 否 | `boolean` | 否 | `true` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `variant` | 是 | `'plain' \| 'round' \| ''` | 否 | `'round'` | 否 | 视觉样式变体，可选值：`plain`、`round`、`""`(默认)；具体含义见组件说明。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `disabled`
+
+禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`disabled={false}`
+
+### `onclick`
+
+用户点击组件时调用，参数通常为 MouseEvent。
+
+- 类型：`(event: MouseEvent) => void`
+- 默认值：`undefined`
+- 示例写法：`onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}`
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+### `variant`
+
+视觉样式变体，可选值：`plain`、`round`、`""`(默认)；具体含义见组件说明。
+
+- 类型：`'plain' | 'round' | ''`
+- 默认值：`'round'`
+- 示例写法：`variant="plain"`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `Size`
+
+```ts
+export type Size = 'small' | 'medium' | 'large';
+```
+
+### `ButtonType`
+
+```ts
+export type ButtonType = 'default' | 'primary' | 'secondary' | 'third' | 'forth';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import TextButton from '@ticatec/topside-elements/TextButton';
+</script>
+
+<TextButton
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  label="示例标签"
+  variant="plain"
+  disabled={false}
+  size="small"
+/>
+```
+
+## 源码
+
+- `src/lib/general/button/TextButton.svelte`

package/docs/components/text-button/example.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import TextButton from '@ticatec/topside-elements/TextButton';
+</script>
+
+<TextButton
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  label="示例标签"
+  variant="plain"
+  disabled={false}
+  size="small"
+/>

package/docs/components/text-editor/README.md

@@ -0,0 +1,147 @@
+# TextEditor
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+标准单行文本输入编辑器。
+
+## 适用场景
+
+- 姓名、编码、标题和普通文本字段
+- 需要前后缀、图标、大小写或校验状态
+
+## 导入
+
+```ts
+import TextEditor from '@ticatec/topside-elements/TextEditor';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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` | 否 | 字段值发生变化时触发的回调 |
+| `prefix` | 否 | `string` | 否 | `undefined` | 否 | 字段前缀文本，展示在输入区域前方 |
+| `suffix` | 否 | `string` | 否 | `undefined` | 否 | 字段后缀文本，展示在输入区域后方 |
+| `leadingIcon` | 否 | `Snippet` | 否 | `undefined` | 否 | 前置图标片段，渲染在输入区域前方，优先级高于 prefix |
+| `trailingIcon` | 否 | `Snippet` | 否 | `undefined` | 否 | 后置图标片段，渲染在输入区域后方，优先级高于 suffix |
+| `onkeydown` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `onkeyup` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `onkeypress` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `caseMode` | 否 | `CaseMode` | 否 | `undefined` | 否 | 大小写模式 |
+| `value` | 是 | `string` | 否 | `$bindable()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+| `input\$*` | 否 | `any` | 否 | `透传` | 否 | 匹配此前缀的属性会透传给内部元素。 |
+
+> 组件的“可绑定”表示源码使用了 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()`
+- 推荐写法：`bind:value`
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `focus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+### `CaseMode`
+
+```ts
+export type CaseMode = 'upper' | 'lower';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import TextEditor from '@ticatec/topside-elements/TextEditor';
+  let value = $state<any>("示例值");
+</script>
+
+<TextEditor
+  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/text_editor/TextEditor.svelte`

package/docs/components/text-editor/example.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import TextEditor from '@ticatec/topside-elements/TextEditor';
+  let value = $state<any>("示例值");
+</script>
+
+<TextEditor
+  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/time-editor/README.md

@@ -0,0 +1,130 @@
+# TimeEditor
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+输入和选择一天内时间的编辑器。
+
+## 适用场景
+
+- 营业时间、提醒时间和排班时间
+- 只需要时分秒而不需要日期
+
+## 导入
+
+```ts
+import TimeEditor from '@ticatec/topside-elements/TimeEditor';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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` | 否 | 字段值发生变化时触发的回调 |
+| `precision` | 否 | `TimePrecision` | 否 | `'M'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `clearable` | 否 | `boolean` | 否 | `true` | 否 | 是否允许清空（显示清空按钮），默认 true |
+| `suffix` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `prefix` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `value` | 是 | `number \| undefined` | 否 | `$bindable<number \| undefined>()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+| `leadingIcon` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `trailingIcon` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+
+> 组件的“可绑定”表示源码使用了 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`，外部修改会同步到组件。
+
+- 类型：`number | undefined`
+- 默认值：`$bindable<number | undefined>()`
+- 推荐写法：`bind:value`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import TimeEditor from '@ticatec/topside-elements/TimeEditor';
+  let value = $state<any>('09:30:00');
+</script>
+
+<TimeEditor
+  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/time_editor/TimeEditor.svelte`

package/docs/components/time-editor/example.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import TimeEditor from '@ticatec/topside-elements/TimeEditor';
+  let value = $state<any>('09:30:00');
+</script>
+
+<TimeEditor
+  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/toast/README.md

@@ -0,0 +1,52 @@
+# Toast
+
+命令式服务。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+通过命令式 API 显示自动消失的轻量通知。
+
+## 适用场景
+
+- 保存成功、网络失败和操作反馈
+- 无需打断用户当前操作的短消息
+
+## 导入
+
+```ts
+import Toast from '@ticatec/topside-elements/Toast';
+```
+
+## 公开成员与方法
+
+| 成员 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `message` | 是 | `string` | 否 | `$state('')` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:message`，仅供参考，不建议直接修改。 |
+| `type` | 是 | `ToastType` | 否 | `$state<ToastType>('info')` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:type`，仅供参考，不建议直接修改。 |
+| `visible` | 是 | `boolean` | 否 | `$state(false)` | 是 | 内部响应式状态：标记当前是否正在显示。由 `show()`/`hide()` 等方法统一管理；这是一个单例服务而非组件，不能使用 `bind:visible`，不建议直接修改。 |
+| `contentHeight` | 是 | `number` | 否 | `$state(0)` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:contentHeight`，仅供参考，不建议直接修改。 |
+| `show()` | 否 | `(msg: string, type: ToastType = 'info', duration: number = 3) => void` | 否 | `—` | 否 | 显示 toast 通知 |
+| `info()` | 否 | `(msg: string, duration: number = 3) => void` | 否 | `—` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `success()` | 否 | `(msg: string, duration: number = 3) => void` | 否 | `—` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `error()` | 否 | `(msg: string, duration: number = 3) => void` | 否 | `—` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Toast from '@ticatec/topside-elements/Toast';
+
+  function notify() {
+    Toast.show('操作成功');
+  }
+</script>
+
+<button type="button" onclick={notify}>显示提示</button>
+```
+
+## 源码
+
+- `src/lib/overlay/toast/Toast.svelte.ts`

package/docs/components/toast/example.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+  import Toast from '@ticatec/topside-elements/Toast';
+
+  function notify() {
+    Toast.show('操作成功');
+  }
+</script>
+
+<button type="button" onclick={notify}>显示提示</button>

package/docs/components/tooltip/README.md

@@ -0,0 +1,44 @@
+# Tooltip
+
+浮层与弹窗组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+自动读取 data-tip/data-tooltip 并显示悬停提示。
+
+## 适用场景
+
+- 解释图标、缩写和不可用操作
+- 需要全局统一、支持 Markdown 的提示层
+
+## 导入
+
+```ts
+import Tooltip from '@ticatec/topside-elements/Tooltip';
+```
+
+别名入口：`@ticatec/topside-elements/PopupHint`
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `delay` | 否 | `number` | 否 | `200` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `offset` | 否 | `number` | 否 | `6` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Tooltip from '@ticatec/topside-elements/Tooltip';
+</script>
+
+<Tooltip/>
+```
+
+## 源码
+
+- `src/lib/overlay/tooltip/Tooltip.svelte`

package/docs/components/tooltip/example.svelte

@@ -0,0 +1,5 @@
+<script lang="ts">
+  import Tooltip from '@ticatec/topside-elements/Tooltip';
+</script>
+
+<Tooltip/>