@ticatec/topside-elements 1.0.0

package/docs/components/action-bar/README.md

@@ -0,0 +1,114 @@
+# ActionBar
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+集中排列页面或区域操作按钮的工具栏。
+
+## 适用场景
+
+- 表单保存、取消和删除操作区
+- 列表页批量操作与页面级命令
+
+## 导入
+
+```ts
+import ActionBar from '@ticatec/topside-elements/ActionBar';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `actions` | 否 | `ButtonActions` | 否 | `[]` | 否 | 动作按钮列表，null 为分隔符 |
+| `style` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的内联样式。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `children`
+
+Svelte Snippet 子内容，用于自定义组件主体。
+
+- 类型：`Snippet`
+- 默认值：`undefined`
+- 示例写法：`children={children}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `ButtonActions`
+
+```ts
+export type ButtonActions = Array<ButtonAction | null>;
+```
+
+### `ButtonAction`
+
+```ts
+export interface ButtonAction {
+    /**
+     * 按钮的文字
+     */
+    label: string;
+
+    /**
+     * 是否禁用
+     */
+    disabled?: boolean;
+
+    /**
+     * 帮助信息
+     */
+    tooltip?: string;
+
+    /**
+     * 前缀图标
+     */
+    icon?: string;
+
+    /**
+     * 按钮的类型
+     */
+    type?: ButtonType;
+
+    /**
+     * click处理函数
+     */
+    handler?: OnClick;
+}
+```
+
+### `ButtonType`
+
+```ts
+export type ButtonType = 'default' | 'primary' | 'secondary' | 'third' | 'forth';
+```
+
+### `OnClick`
+
+```ts
+export type OnClick = (event: MouseEvent) => void;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import ActionBar from '@ticatec/topside-elements/ActionBar';
+</script>
+
+<ActionBar>
+  <div>在这里放置子内容</div>
+</ActionBar>
+```
+
+## 源码
+
+- `src/lib/layouts/action_bar/ActionBar.svelte`

package/docs/components/action-bar/example.svelte

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

package/docs/components/app-top-bar/README.md

@@ -0,0 +1,60 @@
+# AppTopBar
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+应用顶部导航和操作区域。
+
+## 适用场景
+
+- 后台系统顶栏、品牌区和用户菜单
+- 放置全局搜索、通知与快捷操作
+
+## 导入
+
+```ts
+import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `title` | 否 | `string` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `home` | 否 | `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 AppTopBar from '@ticatec/topside-elements/AppTopBar';
+</script>
+
+<AppTopBar
+  title="示例标题"
+>
+  <div>在这里放置子内容</div>
+</AppTopBar>
+```
+
+## 源码
+
+- `src/lib/layouts/app_top_bar/AppTopBar.svelte`

package/docs/components/app-top-bar/example.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+  import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+</script>
+
+<AppTopBar
+  title="示例标题"
+>
+  <div>在这里放置子内容</div>
+</AppTopBar>

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

@@ -0,0 +1,224 @@
+# AttachmentEditor
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+附件上传字段：整个内容区可拖入文件，list / icon 两种排列，内联显示上传进度并可取消、重试。
+
+## 适用场景
+
+- 合同、工单和审批附件
+- 需要限制文件数量、大小或类型的上传
+
+## 导入
+
+```ts
+import AttachmentEditor from '@ticatec/topside-elements/AttachmentEditor';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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` | 否 | `''` | 否 | 自定义内联样式，会应用到字段根容器上 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段获得焦点时触发的回调 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 字段失去焦点时触发的回调 |
+| `onchange` | 是 | `(files: T[]) => void` | 否 | `undefined` | 否 | files 变化后通知（上传完成或删除） |
+| `files` | 是 | `T[]` | 否 | `$bindable<T[]>([])` | 是 | 已上传的附件列表（可绑定） |
+| `layout` | 否 | `AttachmentLayout` | 否 | `'list'` | 否 | 排列方式：list（每行一个）/ icon（图标瓦片，自动换行） |
+| `height` | 否 | `number \| string` | 否 | `undefined` | 否 | 内容区高度；超出后内部滚动，不设则随内容自适应 |
+| `uploadFile` | 否 | `FileUpload` | 否 | `undefined` | 否 | 实际执行上传的函数；不传则组件只读展示（不显示上传入口） |
+| `accept` | 否 | `string` | 否 | `"*/*"` | 否 | 允许的文件类型（同 input accept） |
+| `maxSize` | 否 | `number` | 否 | `1024 * 1024 * 10` | 否 | 单个文件大小上限（字节） |
+| `maxFiles` | 否 | `number` | 否 | `10` | 否 | 文件数量上限（含上传中的） |
+| `multiple` | 否 | `boolean` | 否 | `true` | 否 | 一次是否允许选择 / 拖入多个文件 |
+| `uploadText` | 否 | `string` | 否 | `i18nRes.upload.dropHint()` | 否 | 上传入口的文字（空态时作为拖放区提示） |
+| `emptyText` | 否 | `string` | 否 | `i18nRes.upload.emptyText()` | 否 | 没有文件且不能上传时显示的文字 |
+| `showThumbnail` | 否 | `boolean` | 否 | `false` | 否 | 图片文件显示缩略图（已上传的用 thumbnail ?? uri，上传中的用本地预览）；ImageEditor 默认开启 |
+| `onPreview` | 否 | `(file: T) => void` | 否 | `undefined` | 否 | 预览：有则每个文件显示预览按钮 |
+| `beforeRemove` | 是 | `BeforeRemove<T>` | 否 | `undefined` | 否 | 删除附件前的否决钩子：返回 false 取消删除 |
+| `onremove` | 是 | `(file: T) => void` | 否 | `undefined` | 否 | 附件被删除后通知 |
+| `ondownload` | 否 | `(file: T) => void` | 否 | `undefined` | 否 | 自定义下载；不传则通过 `file.uri` 直接下载 |
+| `onFileUploaded` | 否 | `(file: T, source: File) => void` | 否 | `undefined` | 否 | 单个文件上传完成并加入 files 后通知 |
+| `onFileRejected` | 否 | `(file: File, reason: RejectReason) => void` | 否 | `undefined` | 否 | 文件因类型 / 大小 / 数量限制被拒绝时通知 |
+| `onUploadError` | 否 | `(file: File, error: Error) => void` | 否 | `undefined` | 否 | 上传失败时通知（任务保留在列表中，可重试或移除） |
+
+> 组件的“可绑定”表示源码使用了 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`
+
+files 变化后通知（上传完成或删除）
+
+- 类型：`(files: T[]) => void`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+### `files`
+
+已上传的附件列表（可绑定）
+
+- 类型：`T[]`
+- 默认值：`$bindable<T[]>([])`
+- 推荐写法：`bind:files`
+
+### `beforeRemove`
+
+删除附件前的否决钩子：返回 false 取消删除
+
+- 类型：`BeforeRemove<T>`
+- 默认值：`undefined`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+### `onremove`
+
+附件被删除后通知
+
+- 类型：`(file: T) => void`
+- 默认值：`undefined`
+- 示例写法：`onremove={async (...args: any[]) => { console.log('onremove', ...args); return true; }}`
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `openFileDialog()` | `() => void` | 打开系统文件选择框（等同于点击上传入口） |
+| `focus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+### `AttachmentLayout`
+
+```ts
+export type AttachmentLayout = 'list' | 'icon';
+```
+
+### `FileUpload`
+
+```ts
+export type FileUpload = (file: File, progressUpdate: ProgressUpdate, onUploaded: OnUploaded, errorHandler: OnError) => UploadProgress;
+```
+
+### `BeforeRemove`
+
+```ts
+export type BeforeRemove<T = any> = (file: T) => boolean | void | Promise<boolean | void>;
+```
+
+### `RejectReason`
+
+```ts
+export type RejectReason = 'accept' | 'size' | 'count';
+```
+
+### `ProgressUpdate`
+
+```ts
+export type ProgressUpdate = (uploadBytes: number) => void;
+```
+
+### `OnUploaded`
+
+```ts
+export type OnUploaded = (url: string, thumbnail?: string) => void;
+```
+
+### `OnError`
+
+```ts
+export type OnError = (e: Error) => void;
+```
+
+### `UploadProgress`
+
+```ts
+export interface UploadProgress {
+
+    cancel:()=>Promise<boolean>;
+
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import AttachmentEditor, {type AttachmentFile, type FileUpload} from '@ticatec/topside-elements/AttachmentEditor';
+
+  let files = $state<AttachmentFile[]>([]);
+  const uploadFile: FileUpload = (file, progress, uploaded) => {
+    progress(file.size);
+    uploaded(URL.createObjectURL(file));
+    return {cancel: async () => true};
+  };
+</script>
+
+<AttachmentEditor
+  bind:files
+  {uploadFile}
+  layout="icon"
+  height={160}
+  maxFiles={5}
+  variant="outlined"
+  beforeRemove={async (file) => confirm(`确定删除 ${file.name}？`)}
+  onFileRejected={(file, reason) => console.log('拒绝', file.name, reason)}
+/>
+<p>已上传 {files.length} 个附件</p>
+```
+
+## 源码
+
+- `src/lib/form/attachment_files/AttachmentEditor.svelte`

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

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import AttachmentEditor, {type AttachmentFile, type FileUpload} from '@ticatec/topside-elements/AttachmentEditor';
+
+  let files = $state<AttachmentFile[]>([]);
+  const uploadFile: FileUpload = (file, progress, uploaded) => {
+    progress(file.size);
+    uploaded(URL.createObjectURL(file));
+    return {cancel: async () => true};
+  };
+</script>
+
+<AttachmentEditor
+  bind:files
+  {uploadFile}
+  layout="icon"
+  height={160}
+  maxFiles={5}
+  variant="outlined"
+  beforeRemove={async (file) => confirm(`确定删除 ${file.name}？`)}
+  onFileRejected={(file, reason) => console.log('拒绝', file.name, reason)}
+/>
+<p>已上传 {files.length} 个附件</p>

package/docs/components/box/README.md

@@ -0,0 +1,63 @@
+# Box
+
+布局组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+提供边框、标题和内容区的通用容器。
+
+## 适用场景
+
+- 仪表盘模块和详情卡片区域
+- 需要统一间距与视觉分组的内容
+
+## 导入
+
+```ts
+import Box from '@ticatec/topside-elements/Box';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `title` | 否 | `string` | 否 | `''` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `round` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `content$style` | 否 | `string` | 否 | `''` | 否 | 内容区内联样式 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `children` | 是 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 子内容，用于自定义组件主体。 |
+| `header` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `footer` | 否 | `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 Box from '@ticatec/topside-elements/Box';
+</script>
+
+<Box
+  title="示例标题"
+  round={true}
+>
+  <div>在这里放置子内容</div>
+</Box>
+```
+
+## 源码
+
+- `src/lib/layouts/box/Box.svelte`

package/docs/components/box/example.svelte

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

package/docs/components/breadcrumbs/README.md

@@ -0,0 +1,86 @@
+# Breadcrumbs
+
+导航组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+展示当前位置层级并支持返回上级的面包屑导航。
+
+## 适用场景
+
+- 多层后台菜单和详情页路径
+- 文件目录、分类目录与层级页面导航
+
+## 导入
+
+```ts
+import Breadcrumbs from '@ticatec/topside-elements/Breadcrumbs';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `items` | 是 | `Array<Breadcrumb>` | 否 | `[]` | 否 | 组件的数据项集合。 |
+| `separator` | 否 | `string` | 否 | `"/"` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `onclick` | 是 | `(event: MouseEvent, item: any) => void` | 否 | `undefined` | 否 | 用户点击组件时调用，参数通常为 MouseEvent。 |
+| `style` | 否 | `string` | 否 | `""` | 否 | 附加到组件根元素的内联样式。 |
+| `leadingSeparator` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `items`
+
+组件的数据项集合。
+
+- 类型：`Array<Breadcrumb>`
+- 默认值：`[]`
+- 示例写法：`items={[
+    {label: '首页', data: {path: '/'}},
+    {label: '用户管理', data: {path: '/users'}}
+  ]}`
+
+### `onclick`
+
+用户点击组件时调用，参数通常为 MouseEvent。
+
+- 类型：`(event: MouseEvent, item: any) => void`
+- 默认值：`undefined`
+- 示例写法：`onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `Breadcrumb`
+
+```ts
+export default interface Breadcrumb {
+    label: string;
+    data: any;
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Breadcrumbs from '@ticatec/topside-elements/Breadcrumbs';
+</script>
+
+<Breadcrumbs
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  items={[
+    {label: '首页', data: {path: '/'}},
+    {label: '用户管理', data: {path: '/users'}}
+  ]}
+/>
+```
+
+## 源码
+
+- `src/lib/navigation/breadcrumbs/Breadcrumbs.svelte`

package/docs/components/breadcrumbs/example.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import Breadcrumbs from '@ticatec/topside-elements/Breadcrumbs';
+</script>
+
+<Breadcrumbs
+  onclick={async (...args: any[]) => { console.log('onclick', ...args); return true; }}
+  items={[
+    {label: '首页', data: {path: '/'}},
+    {label: '用户管理', data: {path: '/users'}}
+  ]}
+/>