@ticatec/uniface-element 5.0.0 → 5.0.2

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

@@ -0,0 +1,143 @@
+# MemoEditor
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+用于输入多行文本的编辑器。
+
+## 适用场景
+
+- 备注、描述、意见和长文本内容
+- 需要换行、字符限制或多行显示
+
+## 导入
+
+```ts
+import MemoEditor from '@ticatec/uniface-element/MemoEditor';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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` | 是 | `(value?: any) => void` | 否 | `undefined` | 否 | 字段值发生变化时触发的回调 |
+| `onkeydown` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `onkeyup` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `onkeypress` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `class` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的 CSS class。 |
+| `value` | 是 | `any` | 否 | `$bindable()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+| `wrap` | 否 | `"hard" \| "soft"` | 否 | `'hard'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `resize` | 否 | `'none' \| 'horizontal' \| 'vertical' \| 'both'` | 否 | `'none'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `showIndicator` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `maxLength` | 否 | `number` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `rows` | 否 | `number` | 否 | `3` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `autoHeight` | 否 | `boolean` | 否 | `false` | 否 | 高度配置；字符串可以使用 px、rem、% 等 CSS 单位。 |
+| `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`，外部修改会同步到组件。
+
+- 类型：`any`
+- 默认值：`$bindable()`
+- 推荐写法：`bind:value`
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `focus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import MemoEditor from '@ticatec/uniface-element/MemoEditor';
+  let value = $state<any>();
+</script>
+
+<MemoEditor
+  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/memo_editor/MemoEditor.svelte`

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

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import MemoEditor from '@ticatec/uniface-element/MemoEditor';
+  let value = $state<any>();
+</script>
+
+<MemoEditor
+  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/message-box/README.md

@@ -0,0 +1,68 @@
+# MessageBox
+
+命令式服务。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+通过命令式 API 显示信息或确认消息。
+
+## 适用场景
+
+- 删除确认、操作结果和警告提示
+- 需要等待用户确认结果后继续执行
+
+## 导入
+
+```ts
+import MessageBox from '@ticatec/uniface-element/MessageBox';
+```
+
+## 公开成员与方法
+
+| 成员 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `visible` | 是 | `boolean` | 否 | `$state(false)` | 是 | 内部响应式状态：标记当前是否正在显示。由 `show()`/`hide()` 等方法统一管理；这是一个单例服务而非组件，不能使用 `bind:visible`，不建议直接修改。 |
+| `title` | 是 | `string` | 否 | `$state('')` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:title`，仅供参考，不建议直接修改。 |
+| `message` | 是 | `string` | 否 | `$state('')` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:message`，仅供参考，不建议直接修改。 |
+| `type` | 是 | `MessageType` | 否 | `$state<MessageType>('info')` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:type`，仅供参考，不建议直接修改。 |
+| `iconType` | 是 | `string` | 否 | `$state('')` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:iconType`，仅供参考，不建议直接修改。 |
+| `buttons` | 是 | `MessageButton[]` | 否 | `$state<MessageButton[]>([])` | 是 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:buttons`，仅供参考，不建议直接修改。 |
+| `showInfo` | 否 | `(message: string, options?: { title?: string, type?: InfoType }) => Promise<void>` | 否 | `函数实现` | 否 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:showInfo`，仅供参考，不建议直接修改。 |
+| `showConfirm` | 否 | `(message: string, options?: { title?: string, type?: ConfirmType }) => Promise<any>` | 否 | `函数实现` | 否 | 内部响应式状态；由上方方法统一管理。这是一个单例服务而非组件，不能使用 `bind:showConfirm`，仅供参考，不建议直接修改。 |
+| `resolveWith()` | 否 | `(result: ModalResult) => void` | 否 | `—` | 否 | 用户点了某个按钮（或关闭图标 / ESC）。 内部使用：由面板调用，触发外层的 Promise resolve。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `ModalResult`
+
+```ts
+export enum ModalResult {
+    MR_OK = 1,
+    MR_CANCEL = 2,
+    MR_CLOSE = 3
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import MessageBox from '@ticatec/uniface-element/MessageBox';
+
+  async function confirmAction() {
+    const result = await MessageBox.showConfirm('确定继续吗？');
+    console.log(result);
+  }
+</script>
+
+<button type="button" onclick={confirmAction}>确认操作</button>
+```
+
+## 源码
+
+- `src/lib/overlay/message-box/MessageBox.svelte.ts`

package/docs/components/message-box/example.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import MessageBox from '@ticatec/uniface-element/MessageBox';
+
+  async function confirmAction() {
+    const result = await MessageBox.showConfirm('确定继续吗？');
+    console.log(result);
+  }
+</script>
+
+<button type="button" onclick={confirmAction}>确认操作</button>

package/docs/components/navigator/README.md

@@ -0,0 +1,75 @@
+# Navigator
+
+导航组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+展示步骤或项目状态的纵向/横向导航器。
+
+## 适用场景
+
+- 流程向导、任务阶段和模块切换
+- 需要表达已完成、当前和后续状态
+
+## 导入
+
+```ts
+import Navigator from '@ticatec/uniface-element/Navigator';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `items` | 是 | `Array<any>` | 是 | `—` | 否 | 组件的数据项集合。 |
+| `activeItem` | 是 | `any` | 否 | `$bindable()` | 是 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `style` | 否 | `string` | 否 | `""` | 否 | 附加到组件根元素的内联样式。 |
+| `highlights` | 否 | `Array<any>` | 否 | `[]` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `itemClickHandler` | 否 | `ItemClickHandler` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `retrieveStatus` | 否 | `RetrieveItemStatus` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `items`
+
+组件的数据项集合。
+
+- 类型：`Array<any>`
+- 默认值：`—`
+- 示例写法：`items={[
+    {label: '首页', data: {path: '/'}},
+    {label: '用户管理', data: {path: '/users'}}
+  ]}`
+
+### `activeItem`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`any`
+- 默认值：`$bindable()`
+- 推荐写法：`bind:activeItem`
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Navigator from '@ticatec/uniface-element/Navigator';
+  let activeItem = $state<any>();
+</script>
+
+<Navigator
+  items={[
+    {label: '首页', data: {path: '/'}},
+    {label: '用户管理', data: {path: '/users'}}
+  ]}
+  bind:activeItem
+/>
+<p>当前状态：{JSON.stringify({activeItem})}</p>
+```
+
+## 源码
+
+- `src/lib/navigation/navigator/Navigator.svelte`

package/docs/components/navigator/example.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+  import Navigator from '@ticatec/uniface-element/Navigator';
+  let activeItem = $state<any>();
+</script>
+
+<Navigator
+  items={[
+    {label: '首页', data: {path: '/'}},
+    {label: '用户管理', data: {path: '/users'}}
+  ]}
+  bind:activeItem
+/>
+<p>当前状态：{JSON.stringify({activeItem})}</p>

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

@@ -0,0 +1,113 @@
+# NavigatorMenu
+
+导航组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+支持层级菜单、滚动与激活状态的应用导航菜单。
+
+## 适用场景
+
+- 后台主导航和模块菜单
+- 菜单项较多或包含子菜单的应用
+
+## 导入
+
+```ts
+import NavigatorMenu from '@ticatec/uniface-element/NavigatorMenu';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `menuItems` | 是 | `Array<MenuNode>` | 是 | `—` | 否 | 菜单层级数据集合；每一项可包含子菜单，结构由 `textField` 与子项字段共同决定。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `textField` | 是 | `string \| GetText<MenuItem>` | 是 | `—` | 否 | 数据项中用于界面显示的文本字段名。 |
+| `onItemClick` | 是 | `OnMenuClick` | 是 | `—` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `variant` | 是 | `Variant` | 否 | `'vertical'` | 否 | 视觉样式变体，可选值：`vertical`、`horizontal`；具体含义见组件说明。 |
+| `theme` | 否 | `string` | 否 | `''` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `menuItems`
+
+菜单层级数据集合；每一项可包含子菜单，结构由 `textField` 与子项字段共同决定。
+
+- 类型：`Array<MenuNode>`
+- 默认值：`—`
+- 示例写法：`menuItems={[]}`
+
+### `textField`
+
+数据项中用于界面显示的文本字段名。
+
+- 类型：`string | GetText<MenuItem>`
+- 默认值：`—`
+- 示例写法：`textField="text"`
+
+### `onItemClick`
+
+事件或行为回调；参数与返回值以类型签名为准。
+
+- 类型：`OnMenuClick`
+- 默认值：`—`
+- 示例写法：`onItemClick={async (...args: any[]) => { console.log('onItemClick', ...args); return true; }}`
+
+### `variant`
+
+视觉样式变体，可选值：`vertical`、`horizontal`；具体含义见组件说明。
+
+- 类型：`Variant`
+- 默认值：`'vertical'`
+- 示例写法：`variant="vertical"`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `MenuNode`
+
+```ts
+export interface MenuNode {
+    item: MenuItem;
+    children?: MenuNode[];
+    expand?: boolean;
+}
+```
+
+### `MenuItem`
+
+```ts
+export default interface MenuItem {
+    [key: string]: any
+}
+```
+
+### `OnMenuClick`
+
+```ts
+export type OnMenuClick = (item: MenuItem) => void;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import NavigatorMenu from '@ticatec/uniface-element/NavigatorMenu';
+</script>
+
+<NavigatorMenu
+  menuItems={[]}
+  textField="text"
+  onItemClick={async (...args: any[]) => { console.log('onItemClick', ...args); return true; }}
+  variant="vertical"
+/>
+```
+
+## 源码
+
+- `src/lib/navigation/nav_menu/NavigatorMenu.svelte`

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

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import NavigatorMenu from '@ticatec/uniface-element/NavigatorMenu';
+</script>
+
+<NavigatorMenu
+  menuItems={[]}
+  textField="text"
+  onItemClick={async (...args: any[]) => { console.log('onItemClick', ...args); return true; }}
+  variant="vertical"
+/>

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

@@ -0,0 +1,144 @@
+# NumberEditor
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+输入并校验数值的编辑器。
+
+## 适用场景
+
+- 数量、金额、比例和排序值
+- 需要最小值、最大值或精度控制
+
+## 导入
+
+```ts
+import NumberEditor from '@ticatec/uniface-element/NumberEditor';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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` | 否 | 字段值发生变化时触发的回调 |
+| `onkeydown` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `onkeyup` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `onkeypress` | 否 | `(event: KeyboardEvent) => void` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `value` | 是 | `any` | 否 | `$bindable()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+| `precision` | 否 | `number` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `suffix` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `prefix` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `allowNegative` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `max` | 否 | `number` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `min` | 否 | `number` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `leadingIcon` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `trailingIcon` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `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`，外部修改会同步到组件。
+
+- 类型：`any`
+- 默认值：`$bindable()`
+- 推荐写法：`bind:value`
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `focus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
+  let value = $state<any>(42);
+</script>
+
+<NumberEditor
+  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/number_editor/NumberEditor.svelte`

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

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
+  let value = $state<any>(42);
+</script>
+
+<NumberEditor
+  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>