@ticatec/topside-elements 1.0.0

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

@@ -0,0 +1,262 @@
+# ImageEditor
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+图片上传字段：与 AttachmentEditor 同一套实现，瓦片显示缩略图、内置大图预览。
+
+## 适用场景
+
+- 头像、商品图和现场照片
+- 需要图片预览及多图上传管理
+
+## 导入
+
+```ts
+import ImageEditor from '@ticatec/topside-elements/ImageEditor';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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: ImageFile[]) => void` | 否 | `undefined` | 否 | files 变化后通知（上传完成或删除） |
+| `files` | 是 | `ImageFile[]` | 否 | `$bindable<ImageFile[]>([])` | 是 | 已上传的图片列表（可绑定） |
+| `layout` | 否 | `AttachmentLayout` | 否 | `'icon'` | 否 | 排列方式：icon（缩略图瓦片，自动换行，默认）/ list（每行一张） |
+| `height` | 否 | `number \| string` | 否 | `undefined` | 否 | 内容区高度；超出后内部滚动，不设则随内容自适应 |
+| `uploadFile` | 否 | `FileUpload` | 否 | `undefined` | 否 | 实际执行上传的函数；不传则只展示（不显示上传入口）。onUploaded 的第二个参数可传缩略图地址 |
+| `accept` | 否 | `string` | 否 | `"image/*"` | 否 | 允许的文件类型（同 input accept） |
+| `maxSize` | 否 | `number` | 否 | `1024 * 1024 * 10` | 否 | 单个文件大小上限（字节） |
+| `maxFiles` | 否 | `number` | 否 | `10` | 否 | 图片数量上限（含上传中的） |
+| `multiple` | 否 | `boolean` | 否 | `true` | 否 | 一次是否允许选择 / 拖入多张 |
+| `uploadText` | 否 | `string` | 否 | `undefined` | 否 | 上传入口的文字（空态时作为拖放区提示） |
+| `emptyText` | 否 | `string` | 否 | `undefined` | 否 | 没有图片且不能上传时显示的文字 |
+| `previewable` | 否 | `boolean` | 否 | `true` | 否 | 是否可预览：显示预览按钮，点击打开内置的大图预览 |
+| `onPreview` | 否 | `(file: ImageFile) => void` | 否 | `undefined` | 否 | 自定义预览；传了则不再打开内置预览 |
+| `beforeRemove` | 是 | `BeforeRemove<ImageFile>` | 否 | `undefined` | 否 | 删除图片前的否决钩子：返回 false 取消删除 |
+| `onremove` | 是 | `(file: ImageFile) => void` | 否 | `undefined` | 否 | 图片被删除后通知 |
+| `ondownload` | 否 | `(file: ImageFile) => void` | 否 | `undefined` | 否 | 自定义下载；不传则通过 `file.uri` 直接下载 |
+| `onFileUploaded` | 否 | `(file: ImageFile, 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: ImageFile[]) => void`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+### `files`
+
+已上传的图片列表（可绑定）
+
+- 类型：`ImageFile[]`
+- 默认值：`$bindable<ImageFile[]>([])`
+- 推荐写法：`bind:files`
+
+### `beforeRemove`
+
+删除图片前的否决钩子：返回 false 取消删除
+
+- 类型：`BeforeRemove<ImageFile>`
+- 默认值：`undefined`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+### `onremove`
+
+图片被删除后通知
+
+- 类型：`(file: ImageFile) => 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';
+```
+
+### `ImageFile`
+
+```ts
+export default interface ImageFile extends UploadedFile {
+
+    /**
+     * 缩略图地址，可选；缺省时直接用 uri 显示
+     */
+    thumbnail?: string | null;
+}
+```
+
+### `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';
+```
+
+### `UploadedFile`
+
+```ts
+export interface UploadedFile {
+
+    /**
+     * 文件名
+     */
+    name: string;
+
+    /**
+     * 存储地址（oss 路径 / URL）
+     */
+    uri: string;
+
+    /**
+     * 文件大小（字节），可选；上传完成后由组件写入
+     */
+    size?: number;
+
+    /**
+     * 缩略图地址，可选；有则在瓦片 / 列表里代替类型图标显示
+     */
+    thumbnail?: string | null;
+}
+```
+
+### `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 ImageEditor, {type FileUpload, type ImageFile} from '@ticatec/topside-elements/ImageEditor';
+
+  let files = $state<ImageFile[]>([]);
+  const uploadFile: FileUpload = (file, progress, uploaded) => {
+    progress(file.size);
+    uploaded(URL.createObjectURL(file));
+    return {cancel: async () => true};
+  };
+</script>
+
+<ImageEditor
+  bind:files
+  {uploadFile}
+  height={140}
+  maxFiles={5}
+  variant="outlined"
+  beforeRemove={async (file) => confirm(`确定删除 ${file.name}？`)}
+  onPreview={(file) => console.log('预览', file.uri)}
+/>
+<p>已上传 {files.length} 张图片</p>
+```
+
+## 源码
+
+- `src/lib/form/image_editor/ImageEditor.svelte`

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

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import ImageEditor, {type FileUpload, type ImageFile} from '@ticatec/topside-elements/ImageEditor';
+
+  let files = $state<ImageFile[]>([]);
+  const uploadFile: FileUpload = (file, progress, uploaded) => {
+    progress(file.size);
+    uploaded(URL.createObjectURL(file));
+    return {cancel: async () => true};
+  };
+</script>
+
+<ImageEditor
+  bind:files
+  {uploadFile}
+  height={140}
+  maxFiles={5}
+  variant="outlined"
+  beforeRemove={async (file) => confirm(`确定删除 ${file.name}？`)}
+  onPreview={(file) => console.log('预览', file.uri)}
+/>
+<p>已上传 {files.length} 张图片</p>

package/docs/components/indicator/README.md

@@ -0,0 +1,53 @@
+# Indicator
+
+命令式服务。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+通过命令式 API 显示全局处理中指示层。
+
+## 适用场景
+
+- 保存、导入和长任务执行期间
+- 需要阻止重复操作并提示正在处理
+
+## 导入
+
+```ts
+import Indicator from '@ticatec/topside-elements/Indicator';
+```
+
+## 公开成员与方法
+
+| 成员 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `message` | 是 | `string` | 否 | `$state('')` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:message`，仅供参考，不建议直接修改。 |
+| `visible` | 是 | `boolean` | 否 | `$state(false)` | 是 | 内部响应式状态：标记当前是否正在显示。由 `show()`/`hide()` 等方法统一管理；这是一个单例服务而非组件，不能使用 `bind:visible`，不建议直接修改。 |
+| `show()` | 否 | `(msg: string) => void` | 否 | `—` | 否 | 显示加载指示器 |
+| `hide()` | 否 | `() => void` | 否 | `—` | 否 | 隐藏加载指示器 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Indicator from '@ticatec/topside-elements/Indicator';
+
+  async function runTask() {
+    Indicator.show('处理中…');
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+    } finally {
+      Indicator.hide();
+    }
+  }
+</script>
+
+<button type="button" onclick={runTask}>开始任务（1.5 秒后自动隐藏）</button>
+```
+
+## 源码
+
+- `src/lib/overlay/indicator/Indicator.svelte.ts`

package/docs/components/indicator/example.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  import Indicator from '@ticatec/topside-elements/Indicator';
+
+  async function runTask() {
+    Indicator.show('处理中…');
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+    } finally {
+      Indicator.hide();
+    }
+  }
+</script>
+
+<button type="button" onclick={runTask}>开始任务（1.5 秒后自动隐藏）</button>

package/docs/components/input-options-select/README.md

@@ -0,0 +1,163 @@
+# InputOptionsSelect
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+允许输入文字并从候选项中选择的组合控件。
+
+## 适用场景
+
+- 客户、产品和地址快速检索
+- 用户既需要键入搜索又需要选择完整对象
+
+## 导入
+
+```ts
+import InputOptionsSelect from '@ticatec/topside-elements/InputOptionsSelect';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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` | 否 | 字段值发生变化时触发的回调 |
+| `clearable` | 否 | `boolean` | 否 | `undefined` | 否 | 是否允许清空（显示清空按钮），默认 true |
+| `text` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `value` | 是 | `any` | 否 | `$bindable()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+| `keyField` | 否 | `string` | 否 | `'code'` | 否 | 数据项中作为唯一值或选中值的字段名。 |
+| `textField` | 否 | `string` | 否 | `"text"` | 否 | 数据项中用于界面显示的文本字段名。 |
+| `retrieveText` | 否 | `RetrieveOptionText` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `showCode` | 否 | `boolean` | 否 | `false` | 否 | 是否显示选项 code |
+| `menu$height` | 否 | `number` | 否 | `0` | 否 | 高度配置，数值单位为像素。 |
+| `itemRender` | 否 | `any` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `lazyLoader` | 是 | `ListLazyLoader` | 否 | `undefined` | 否 | 异步分页加载器，签名为 `(filterText, pageNo) => Promise<{list, hasMore}>`。ListBox 当前从第 1 页开始请求，滚动到底部且 `hasMore=true` 时继续加载。 |
+| `oninput` | 否 | `(value: string) => 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`
+
+字段值发生变化时触发的回调
+
+- 类型：`(value?: any) => void`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+### `value`
+
+组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。
+
+- 类型：`any`
+- 默认值：`$bindable()`
+- 推荐写法：`bind:value`
+
+### `lazyLoader`
+
+异步分页加载器，签名为 `(filterText, pageNo) => Promise<{list, hasMore}>`。ListBox 当前从第 1 页开始请求，滚动到底部且 `hasMore=true` 时继续加载。
+
+- 类型：`ListLazyLoader`
+- 默认值：`undefined`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+### `RetrieveOptionText`
+
+```ts
+export type RetrieveOptionText = (item: any) => string;
+```
+
+### `ListLazyLoader`
+
+```ts
+export type ListLazyLoader = (text: string, pageNo: number) => Promise<LoadResult>;
+```
+
+### `LoadResult`
+
+```ts
+export interface LoadResult {
+    hasMore: boolean;
+    list: Array<any>;
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import InputOptionsSelect from '@ticatec/topside-elements/InputOptionsSelect';
+  let value = $state<any>('dev');
+</script>
+
+<InputOptionsSelect
+  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="请输入或选择"
+  keyField="code"
+  textField="text"
+  disabled={false}
+/>
+<p>当前状态：{JSON.stringify({value})}</p>
+```
+
+## 源码
+
+- `src/lib/form/input_options_select/InputOptionsSelect.svelte`

package/docs/components/input-options-select/example.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import InputOptionsSelect from '@ticatec/topside-elements/InputOptionsSelect';
+  let value = $state<any>('dev');
+</script>
+
+<InputOptionsSelect
+  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="请输入或选择"
+  keyField="code"
+  textField="text"
+  disabled={false}
+/>
+<p>当前状态：{JSON.stringify({value})}</p>

package/docs/components/list-box/ListItem.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  let {item, selected = false}: {item: {name: string; department: string}; selected?: boolean} = $props();
+</script>
+
+<div class:selected>
+  <strong>{item.name}</strong>
+  <small>{item.department}</small>
+</div>
+
+<style>
+  div {display: flex; justify-content: space-between; padding: 8px 12px;}
+  div.selected {background: #eef4ff; color: #174ea6;}
+  small {color: #64748b;}
+</style>