@ticatec/uniface-element 5.0.5 → 5.1.0

package/dist/form/switch/Switch.svelte

@@ -1,15 +1,17 @@
 <script lang="ts">
     interface Props {
-        checkLabel?: string;
-        uncheckLabel?: string;
+        /** 开启状态显示的文字 */
+        checkedText?: string;
+        /** 关闭状态显示的文字 */
+        uncheckedText?: string;
         readonly?: boolean;
         disabled?: boolean;
         value?: boolean;
     }
 
     let {
-        checkLabel = "On",
-        uncheckLabel = "Off",
+        checkedText = "On",
+        uncheckedText = "Off",
         readonly = false,
         disabled = false,
         value = $bindable(false)
@@ -27,7 +29,7 @@
     <label class="switch" class:readonly class:disabled>
         <input type="checkbox" bind:checked={value} disabled={disabled} aria-readonly={readonly} onclick={toggleSwitch}>
         <span class="slider" aria-hidden="true"></span>
-        <span class="text" aria-hidden="true">{value ? uncheckLabel : checkLabel}</span>
+        <span class="text" aria-hidden="true">{value ? uncheckedText : checkedText}</span>
     </label>
 </div>
 

package/dist/form/switch/Switch.svelte.d.ts

@@ -1,6 +1,8 @@
 interface Props {
-    checkLabel?: string;
-    uncheckLabel?: string;
+    /** 开启状态显示的文字 */
+    checkedText?: string;
+    /** 关闭状态显示的文字 */
+    uncheckedText?: string;
     readonly?: boolean;
     disabled?: boolean;
     value?: boolean;

package/dist/form/text_editor/PasswordEditor.svelte

@@ -4,7 +4,7 @@
     import Icon from "../../general/icon";
     import CommonEditor from "../common_editor/CommonEditor.svelte";
     import type CommonFieldProps from "../common_editor/CommonFieldProps";
-    import type {KeyboardEvents} from "../common_editor/EditorEvents";
+    import type {KeyboardEvents} from "../events";
 
     const excludeAttrs = ['type', 'readonly', 'disabled', 'required', 'wrap', 'value', 'placeholder'];
 
@@ -61,7 +61,7 @@
     <input bind:this={editor} bind:value type={showPassword ? 'text' : 'password'} {...input$} onchange={handleChangeEvent} {...eventHandlers()} />
     {#snippet trailingIcon()}
         <div class="password-icon">
-            <Icon name={iconName()} onclick={togglePassword} />
+            <Icon name={iconName()} tabindex={-1} onclick={togglePassword} />
         </div>
     {/snippet}
 </CommonEditor>

package/dist/form/text_editor/PasswordEditor.svelte.d.ts

@@ -1,5 +1,5 @@
 import type CommonFieldProps from "../common_editor/CommonFieldProps";
-import type { KeyboardEvents } from "../common_editor/EditorEvents";
+import type { KeyboardEvents } from "../events";
 interface Props extends CommonFieldProps, KeyboardEvents {
     value?: string;
     [key: `input\$${string}`]: any;

package/dist/form/text_editor/TextEditor.svelte

@@ -1,10 +1,10 @@
 <script lang="ts">
 
     import type {CaseMode} from "../types";
-    import prefixFilter, {filterProps} from "../../utils/prefixFilter";
+    import prefixFilter, {eventFilter} from "../../utils/prefixFilter";
     import CommonEditor from "../common_editor/CommonEditor.svelte";
     import type CommonEditorProps from "../common_editor/CommonEditorProps";
-    import {keyboardAttrs, type KeyboardEvents} from "../common_editor/EditorEvents";
+    import type {KeyboardEvents} from "../events";
     import type {Snippet} from "svelte";
 
     const excludeAttrs = ['type', 'readonly', 'disabled', 'required', 'wrap', 'value'];
@@ -70,7 +70,9 @@
     }
 
     let input$ = $derived(prefixFilter(restProps, 'input$', excludeAttrs));
-    let eventHandlers = $derived(filterProps(restProps, keyboardAttrs));
+    // Forward every on* handler a consumer passes (onfocus/onblur/onkeydown/…) to the native input.
+    // Kept reactive on purpose (see SearchBox). Internal oninput/onchange are spread AFTER this so they win.
+    let eventHandlers = $derived(eventFilter(restProps));
 
     const clear = () => {
         value = undefined;
@@ -80,7 +82,7 @@
 </script>
 
 
-<CommonEditor textValue={value} {clear} {suffix} {prefix} {readonly} {disabled} {variant} {theme} {compact} {leadingIcon} {trailingIcon} {tooltip}
+<CommonEditor textValue={value} {clear} {style} {suffix} {prefix} {readonly} {disabled} {variant} {theme} {compact} {leadingIcon} {trailingIcon} {tooltip}
               {error}>
     <input bind:this={editor} {...input$} {placeholder} {...eventHandlers}
            oninput={handleInput} onchange={handleChange} bind:value/>

package/dist/form/text_editor/TextEditor.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { CaseMode } from "../types";
 import type CommonEditorProps from "../common_editor/CommonEditorProps";
-import { type KeyboardEvents } from "../common_editor/EditorEvents";
+import type { KeyboardEvents } from "../events";
 interface Props extends CommonEditorProps, KeyboardEvents {
     caseMode?: CaseMode;
     /**

package/dist/form/time_editor/README.md

@@ -1,5 +1,7 @@
 # TimeEditor
 
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `mandatory` were removed in 5.1.0 (no compatibility aliases are kept).
+
 A specialized time input component with interactive time selection functionality. Features keyboard navigation, automatic validation, and support for both minute and second precision. The component stores time as a numeric value representing total minutes (with fractional seconds).
 
 ## Features
@@ -41,7 +43,7 @@ import TimeEditor from "@ticatec/uniface-element/TimeEditor";
 |------|------|---------|-------------|
 | `value` | `number \| undefined` | `undefined` | Time value in minutes (e.g. `90.5` = 1:30:30). Bindable. |
 | `precision` | `"M" \| "S"` | `"M"` | Time precision: `"M"` for minutes (HH:MM), `"S"` for seconds (HH:MM:SS). |
-| `mandatory` | `boolean` | `false` | When true, show `00:00` instead of `__:__` for empty fields. |
+| `clearable` | `boolean` | `true` | Whether the value can be cleared (shows the clear button). The old `mandatory` prop meant the opposite (`mandatory={true}` = `clearable={false}`) and was removed in 5.1.0. |
 | `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Visual style variant. |
 | `compact` | `boolean` | `false` | Compact spacing layout. |
 | `disabled` | `boolean` | `false` | Disables the editor. |
@@ -173,7 +175,7 @@ Range: `0` to `1439` minutes (23:59).
 <!-- Mandatory mode (shows zeros) -->
 <div class="form-group">
   <label>Required Time:</label>
-  <TimeEditor bind:value={requiredTime} mandatory />
+  <TimeEditor bind:value={requiredTime} clearable={false} />
 </div>
 ```
 

package/dist/form/time_editor/README_CN.md

@@ -1,5 +1,7 @@
 # TimeEditor 时间输入组件
 
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `mandatory` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
 专业的时间输入组件，支持交互式的时分/时分秒选择功能。具有键盘导航、自动校验，支持分钟（HH:MM）和秒（HH:MM:SS）两种精度。组件内部以分钟数（含小数秒）存储时间值。
 
 ## 功能特性
@@ -41,7 +43,7 @@ import TimeEditor from "@ticatec/uniface-element/TimeEditor";
 |------|------|--------|------|
 | `value` | `number \| undefined` | `undefined` | 时间值（分钟数），如 `90.5` = 1:30:30。可双向绑定。 |
 | `precision` | `"M" \| "S"` | `"M"` | 时间精度：`"M"` 为分钟（HH:MM），`"S"` 为秒（HH:MM:SS）。 |
-| `mandatory` | `boolean` | `false` | 为 true 时，空值显示 `00:00` 而非 `__:__`。 |
+| `clearable` | `boolean` | `true` | 是否允许清空（显示清空按钮）。旧名 `mandatory` 语义相反（`mandatory={true}` = `clearable={false}`），5.1.0 已移除。 |
 | `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉样式变体。 |
 | `compact` | `boolean` | `false` | 紧凑间距布局。 |
 | `disabled` | `boolean` | `false` | 禁用编辑器。 |
@@ -173,7 +175,7 @@ TimeEditor 以分钟数存储时间：
 <!-- 必填模式（显示零） -->
 <div class="form-group">
   <label>必填时间：</label>
-  <TimeEditor bind:value={requiredTime} mandatory />
+  <TimeEditor bind:value={requiredTime} clearable={false} />
 </div>
 ```
 

package/dist/form/time_editor/TimeEditor.svelte

@@ -8,7 +8,8 @@
 
     interface Props extends CommonFieldProps {
         precision?: TimePrecision;
-        mandatory?: boolean;
+        /** 是否允许清空（显示清空按钮），默认 true */
+        clearable?: boolean;
         suffix?: string;
         prefix?: string;
         value?: number | undefined;
@@ -19,7 +20,7 @@
     let {
         disabled = false,
         readonly = false,
-        mandatory = false,
+        clearable = true,
         precision = 'M',
         variant,
         theme,
@@ -35,6 +36,7 @@
         trailingIcon,
     }: Props = $props();
 
+
     let editor: HTMLInputElement;
     let hasFocus = $state(false);
     let cursorIndex = 0;
@@ -60,7 +62,7 @@
 
     function toTimeText(v: number | undefined): string {
         if (v == null) {
-            return mandatory ? getEmptyStr().replaceAll('_', '0') : getEmptyStr();
+            return clearable ? getEmptyStr() : getEmptyStr().replaceAll('_', '0');
         }
         const totalMinutes = Math.floor(v);
         const hh = Math.min(23, Math.floor(totalMinutes / 60));
@@ -151,10 +153,10 @@
                 moveCursor(1);
                 break;
             case 'Delete':
-                textValue = replaceChar(cursorIndex, mandatory ? '0' : '_');
+                textValue = replaceChar(cursorIndex, clearable ? '_' : '0');
                 break;
             case 'Backspace':
-                textValue = replaceChar(cursorIndex, mandatory ? '0' : '_');
+                textValue = replaceChar(cursorIndex, clearable ? '_' : '0');
                 await tick();
                 moveCursor(cursorIndex > 0 ? -1 : 0);
                 break;
@@ -192,7 +194,8 @@
         editor.focus();
     }
 
-    let canClean = $derived(textValue !== getEmptyStr());
+    // 只有允许清空且当前有内容时才显示清空按钮
+    const showClear = $derived(clearable && textValue !== getEmptyStr());
 </script>
 
 <CommonEditor
@@ -207,7 +210,7 @@
     {compact}
     {leadingIcon}
     {trailingIcon}
-    {canClean}
+    clearable={showClear}
     {clear}>
     <input
         bind:this={editor}

package/dist/form/time_editor/TimeEditor.svelte.d.ts

@@ -3,7 +3,8 @@ import type CommonFieldProps from "../common_editor/CommonFieldProps";
 type TimePrecision = 'M' | 'S';
 interface Props extends CommonFieldProps {
     precision?: TimePrecision;
-    mandatory?: boolean;
+    /** 是否允许清空（显示清空按钮），默认 true */
+    clearable?: boolean;
     suffix?: string;
     prefix?: string;
     value?: number | undefined;

package/dist/form/types.d.ts

@@ -1,45 +1,8 @@
 export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
 export type InputType = 'text' | 'search' | 'email' | 'tel' | 'url' | 'password' | 'number';
 export type CaseMode = 'upper' | 'lower';
-export interface EditorEvents {
-    onblur?: (e: FocusEvent) => void;
-    onfocus?: (e: FocusEvent) => void;
-    onfocusin?: (e: FocusEvent) => void;
-    onfocusout?: (e: FocusEvent) => void;
-    oninput?: (e: InputEvent) => void;
-    onchange?: (value: any) => void;
-    onbeforeinput?: (e: InputEvent) => void;
-    onkeydown?: (e: KeyboardEvent) => void;
-    onkeyup?: (e: KeyboardEvent) => void;
-    onkeypress?: (e: KeyboardEvent) => void;
-    oncompositionstart?: (e: CompositionEvent) => void;
-    oncompositionend?: (e: CompositionEvent) => void;
-    oncompositionupdate?: (e: CompositionEvent) => void;
-    oncopy?: (e: ClipboardEvent) => void;
-    oncut?: (e: ClipboardEvent) => void;
-    onpaste?: (e: ClipboardEvent) => void;
-    onselect?: (e: Event) => void;
-    oninvalid?: (e: Event) => void;
-    onreset?: (e: Event) => void;
-    onclick?: (e: MouseEvent) => void;
-    ondblclick?: (e: MouseEvent) => void;
-    onmousedown?: (e: MouseEvent) => void;
-    onmouseup?: (e: MouseEvent) => void;
-    onmouseover?: (e: MouseEvent) => void;
-    onmousemove?: (e: MouseEvent) => void;
-    onmouseout?: (e: MouseEvent) => void;
-    onmouseenter?: (e: MouseEvent) => void;
-    onmouseleave?: (e: MouseEvent) => void;
-    onwheel?: (e: WheelEvent) => void;
-    ontouchstart?: (e: TouchEvent) => void;
-    ontouchend?: (e: TouchEvent) => void;
-    ontouchmove?: (e: TouchEvent) => void;
-    ontouchcancel?: (e: TouchEvent) => void;
-    ondrag?: (e: DragEvent) => void;
-    ondragstart?: (e: DragEvent) => void;
-    ondragend?: (e: DragEvent) => void;
-    ondragover?: (e: DragEvent) => void;
-    ondragenter?: (e: DragEvent) => void;
-    ondragleave?: (e: DragEvent) => void;
-    ondrop?: (e: DragEvent) => void;
-}
+/**
+ * 删除文件前的否决钩子（NAMING R2）：返回 false 取消删除。
+ * @template T 文件对象类型（AttachmentFile / ImageFile）
+ */
+export type BeforeRemove<T = any> = (file: T) => boolean | void | Promise<boolean | void>;

package/dist/form/unit-number-editor/README.md

@@ -1,5 +1,7 @@
 # UnitNumberEditor
 
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `units` were removed in 5.1.0 (no compatibility aliases are kept).
+
 A numeric input with built-in unit conversion. Users type a value in any unit (kg, lb, m, ft, …) and the component converts it to a standard unit via a configurable `ratio`. A dropdown on the trailing side switches units; the displayed value updates accordingly.
 
 The `value` prop is always in the **standard unit** (the one whose `ratio === 1`). The displayed value is `value × unit.ratio`.
@@ -45,7 +47,7 @@ import UnitNumberEditor, { type UnitOption } from "@ticatec/uniface-element/Unit
 <UnitNumberEditor
   bind:value={weightValue}
   bind:unitCode={weightUnit}
-  units={weightUnits}
+  options={weightUnits}
   placeholder="Enter weight"
 />
 ```
@@ -55,8 +57,8 @@ import UnitNumberEditor, { type UnitOption } from "@ticatec/uniface-element/Unit
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `value` | `number \| undefined` | `undefined` | Value in the **standard unit** (the unit with `ratio === 1`). Supports `bind:value`. |
-| `unitCode` | `string \| undefined` | first unit's code | Currently selected unit code. Supports `bind:unitCode`. Falls back to standard unit, then `units[0]`. |
-| `units` | `Array<UnitOption>` | — (required) | Available units. One should have `ratio: 1`. |
+| `unitCode` | `string \| undefined` | first unit's code | Currently selected unit code. Supports `bind:unitCode`. Falls back to standard unit, then `options[0]`. |
+| `options` | `Array<UnitOption>` | — (required) | Available options. One should have `ratio: 1`. |
 | `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Visual variant. |
 | `compact` | `boolean` | `false` | Use compact spacing. |
 | `disabled` | `boolean` | `false` | Disable editing (renders a read-only display). |
@@ -133,7 +135,7 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
 <UnitNumberEditor
   bind:value={weight}
   bind:unitCode={weightUnit}
-  units={weightUnits}
+  options={weightUnits}
   onchange={handleChange}
   placeholder="Enter weight"
 />
@@ -158,7 +160,7 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
 <UnitNumberEditor
   bind:value={distance}
   bind:unitCode={distanceUnit}
-  units={distanceUnits}
+  options={distanceUnits}
   placeholder="Enter distance"
 />
 ```
@@ -173,7 +175,7 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
   let unit = "kg";
   let isFocused = false;
 
-  const units: UnitOption[] = [
+  const options: UnitOption[] = [
     { code: "kg", text: "Kilograms", ratio: 1, precision: 2 },
     { code: "lb", text: "Pounds", ratio: 2.20462, precision: 2 }
   ];
@@ -185,7 +187,7 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
 <UnitNumberEditor
   bind:value={value}
   bind:unitCode={unit}
-  units={units}
+  options={options}
   onfocus={handleFocus}
   onblur={handleBlur}
   placeholder="Enter value"
@@ -205,15 +207,15 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
   let v3: number | undefined = 300;
   let u1 = "m", u2 = "m", u3 = "m";
 
-  const units: UnitOption[] = [
+  const options: UnitOption[] = [
     { code: "m", text: "Meters", ratio: 1, precision: 2 },
     { code: "ft", text: "Feet", ratio: 3.28084, precision: 2 }
   ];
 </script>
 
-<UnitNumberEditor bind:value={v1} bind:unitCode={u1} units={units} placeholder="Default" />
-<UnitNumberEditor bind:value={v2} bind:unitCode={u2} units={units} variant="outlined" placeholder="Outlined" />
-<UnitNumberEditor bind:value={v3} bind:unitCode={u3} units={units} variant="filled" placeholder="Filled" />
+<UnitNumberEditor bind:value={v1} bind:unitCode={u1} options={options} placeholder="Default" />
+<UnitNumberEditor bind:value={v2} bind:unitCode={u2} options={options} variant="outlined" placeholder="Outlined" />
+<UnitNumberEditor bind:value={v3} bind:unitCode={u3} options={options} variant="filled" placeholder="Filled" />
 ```
 
 ### Custom Leading Icon
@@ -235,7 +237,7 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
 <UnitNumberEditor
   bind:value={price}
   bind:unitCode={currency}
-  units={currencies}
+  options={currencies}
   prefix="$"
 >
   {#snippet leadingIcon()}
@@ -254,7 +256,7 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
   let value: number | undefined;
   let unit = "kg";
 
-  const units: UnitOption[] = [
+  const options: UnitOption[] = [
     { code: "kg", text: "Kilograms", ratio: 1, precision: 2 },
     { code: "lb", text: "Pounds", ratio: 2.20462, precision: 2 }
   ];
@@ -268,7 +270,7 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
   bind:this={editor}
   bind:value={value}
   bind:unitCode={unit}
-  units={units}
+  options={options}
   placeholder="Click the button to focus me"
 />
 ```
@@ -283,15 +285,15 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
   let readonlyValue: number | undefined = 75;
   let unit = "kg";
 
-  const units: UnitOption[] = [
+  const options: UnitOption[] = [
     { code: "kg", text: "Kilograms", ratio: 1, precision: 2 },
     { code: "lb", text: "Pounds", ratio: 2.20462, precision: 2 }
   ];
 </script>
 
-<UnitNumberEditor bind:value={normalValue} bind:unitCode={unit} units={units} placeholder="Normal" />
-<UnitNumberEditor bind:value={readonlyValue} bind:unitCode={unit} units={units} readonly />
-<UnitNumberEditor bind:value={normalValue} bind:unitCode={unit} units={units} disabled />
+<UnitNumberEditor bind:value={normalValue} bind:unitCode={unit} options={options} placeholder="Normal" />
+<UnitNumberEditor bind:value={readonlyValue} bind:unitCode={unit} options={options} readonly />
+<UnitNumberEditor bind:value={normalValue} bind:unitCode={unit} options={options} disabled />
 ```
 
 ### Cooking Converter
@@ -316,7 +318,7 @@ Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
   <UnitNumberEditor
     bind:value={amount}
     bind:unitCode={unit}
-    units={volumeUnits}
+    options={volumeUnits}
     placeholder="Enter amount"
   />
   <p>Standard unit value: {amount ?? "—"} ml</p>

package/dist/form/unit-number-editor/README_CN.md

@@ -1,5 +1,7 @@
 # UnitNumberEditor 带单位的数字输入
 
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `units` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
 内置单位转换的数字输入组件。用户可以在任意单位（kg、lb、m、ft 等）中输入数值，组件会通过可配置的 `ratio` 自动转换为标准单位。右侧下拉菜单可切换单位，显示值会相应更新。
 
 `value` 属性始终表示**标准单位**（`ratio === 1` 的单位）中的值。显示值为 `value × unit.ratio`。
@@ -45,7 +47,7 @@ import UnitNumberEditor, { type UnitOption } from "@ticatec/uniface-element/Unit
 <UnitNumberEditor
   bind:value={weightValue}
   bind:unitCode={weightUnit}
-  units={weightUnits}
+  options={weightUnits}
   placeholder="输入重量"
 />
 ```
@@ -55,8 +57,8 @@ import UnitNumberEditor, { type UnitOption } from "@ticatec/uniface-element/Unit
 | 属性 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `value` | `number \| undefined` | `undefined` | **标准单位**中的值（`ratio === 1` 的单位）。支持 `bind:value`。 |
-| `unitCode` | `string \| undefined` | 第一个单位的 code | 当前选中的单位代码。支持 `bind:unitCode`。不匹配时回退到标准单位，再回退到 `units[0]`。 |
-| `units` | `Array<UnitOption>` | —（必填） | 可用单位列表。其中应有一个 `ratio: 1`。 |
+| `unitCode` | `string \| undefined` | 第一个单位的 code | 当前选中的单位代码。支持 `bind:unitCode`。不匹配时回退到标准单位，再回退到 `options[0]`。 |
+| `options` | `Array<UnitOption>` | —（必填） | 可用单位列表。其中应有一个 `ratio: 1`。 |
 | `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉变体。 |
 | `compact` | `boolean` | `false` | 使用紧凑间距。 |
 | `disabled` | `boolean` | `false` | 禁用编辑（显示为只读）。 |
@@ -133,7 +135,7 @@ interface UnitOption {
 <UnitNumberEditor
   bind:value={weight}
   bind:unitCode={weightUnit}
-  units={weightUnits}
+  options={weightUnits}
   onchange={handleChange}
   placeholder="输入重量"
 />
@@ -158,7 +160,7 @@ interface UnitOption {
 <UnitNumberEditor
   bind:value={distance}
   bind:unitCode={distanceUnit}
-  units={distanceUnits}
+  options={distanceUnits}
   placeholder="输入距离"
 />
 ```
@@ -173,7 +175,7 @@ interface UnitOption {
   let unit = "kg";
   let isFocused = false;
 
-  const units: UnitOption[] = [
+  const options: UnitOption[] = [
     { code: "kg", text: "千克", ratio: 1, precision: 2 },
     { code: "lb", text: "磅", ratio: 2.20462, precision: 2 }
   ];
@@ -185,7 +187,7 @@ interface UnitOption {
 <UnitNumberEditor
   bind:value={value}
   bind:unitCode={unit}
-  units={units}
+  options={options}
   onfocus={handleFocus}
   onblur={handleBlur}
   placeholder="输入值"
@@ -205,15 +207,15 @@ interface UnitOption {
   let v3: number | undefined = 300;
   let u1 = "m", u2 = "m", u3 = "m";
 
-  const units: UnitOption[] = [
+  const options: UnitOption[] = [
     { code: "m", text: "米", ratio: 1, precision: 2 },
     { code: "ft", text: "英尺", ratio: 3.28084, precision: 2 }
   ];
 </script>
 
-<UnitNumberEditor bind:value={v1} bind:unitCode={u1} units={units} placeholder="默认" />
-<UnitNumberEditor bind:value={v2} bind:unitCode={u2} units={units} variant="outlined" placeholder="描边" />
-<UnitNumberEditor bind:value={v3} bind:unitCode={u3} units={units} variant="filled" placeholder="填充" />
+<UnitNumberEditor bind:value={v1} bind:unitCode={u1} options={options} placeholder="默认" />
+<UnitNumberEditor bind:value={v2} bind:unitCode={u2} options={options} variant="outlined" placeholder="描边" />
+<UnitNumberEditor bind:value={v3} bind:unitCode={u3} options={options} variant="filled" placeholder="填充" />
 ```
 
 ### 自定义前导图标
@@ -235,7 +237,7 @@ interface UnitOption {
 <UnitNumberEditor
   bind:value={price}
   bind:unitCode={currency}
-  units={currencies}
+  options={currencies}
   prefix="$"
 >
   {#snippet leadingIcon()}
@@ -254,7 +256,7 @@ interface UnitOption {
   let value: number | undefined;
   let unit = "kg";
 
-  const units: UnitOption[] = [
+  const options: UnitOption[] = [
     { code: "kg", text: "千克", ratio: 1, precision: 2 },
     { code: "lb", text: "磅", ratio: 2.20462, precision: 2 }
   ];
@@ -268,7 +270,7 @@ interface UnitOption {
   bind:this={editor}
   bind:value={value}
   bind:unitCode={unit}
-  units={units}
+  options={options}
   placeholder="点击按钮聚焦我"
 />
 ```
@@ -283,15 +285,15 @@ interface UnitOption {
   let readonlyValue: number | undefined = 75;
   let unit = "kg";
 
-  const units: UnitOption[] = [
+  const options: UnitOption[] = [
     { code: "kg", text: "千克", ratio: 1, precision: 2 },
     { code: "lb", text: "磅", ratio: 2.20462, precision: 2 }
   ];
 </script>
 
-<UnitNumberEditor bind:value={normalValue} bind:unitCode={unit} units={units} placeholder="正常" />
-<UnitNumberEditor bind:value={readonlyValue} bind:unitCode={unit} units={units} readonly />
-<UnitNumberEditor bind:value={normalValue} bind:unitCode={unit} units={units} disabled />
+<UnitNumberEditor bind:value={normalValue} bind:unitCode={unit} options={options} placeholder="正常" />
+<UnitNumberEditor bind:value={readonlyValue} bind:unitCode={unit} options={options} readonly />
+<UnitNumberEditor bind:value={normalValue} bind:unitCode={unit} options={options} disabled />
 ```
 
 ### 烹饪单位转换器
@@ -316,7 +318,7 @@ interface UnitOption {
   <UnitNumberEditor
     bind:value={amount}
     bind:unitCode={unit}
-    units={volumeUnits}
+    options={volumeUnits}
     placeholder="输入数量"
   />
   <p>标准单位值：{amount ?? "—"} ml</p>

package/dist/form/unit-number-editor/UnitNumberEditor.svelte

@@ -16,7 +16,8 @@
         error?: string;
         value?: number;
         unitCode?: string;
-        units: Array<UnitOption>;
+        /** 可选单位列表 */
+        options?: Array<UnitOption>;
         disabled?: boolean;
         readonly?: boolean;
         prefix?: string;
@@ -24,8 +25,8 @@
         menu$height?: number;
         placeholder?: string;
         onchange?: (value: number | undefined) => void;
-        onfocus?: (e: FocusEvent) => void;
-        onblur?: (e: FocusEvent) => void;
+        onfocus?: (event: FocusEvent) => void;
+        onblur?: (event: FocusEvent) => void;
         leadingIcon?: Snippet;
     }
 
@@ -38,7 +39,7 @@
         error,
         value = $bindable<number | undefined>(),
         unitCode = $bindable<string | undefined>(),
-        units,
+        options = [],
         disabled = false,
         readonly = false,
         prefix,
@@ -55,8 +56,8 @@
     let unitValue = $state<number | undefined>(value);
     let oldValue = value;
     let isUserChange = false;
-    const standardUnit = $derived(units.find(item => item.ratio === 1));
-    const unit = $derived(units.find(item => item.code === unitCode) ?? standardUnit ?? units[0]);
+    const standardUnit = $derived(options.find(item => item.ratio === 1));
+    const unit = $derived(options.find(item => item.code === unitCode) ?? standardUnit ?? options[0]);
     const mh = $derived(`height: ${menu$height > 0 ? menu$height + 'px' : 'auto'}`);
 
     export function focus() {
@@ -96,7 +97,7 @@
     const handleUnitClick = (item: UnitOption) => (e: MouseEvent) => {
         unitCode = item.code;
         calculateUnitValue(item);
-        editorRef?.closePopup();
+        editorRef?.close();
         setTimeout(() => editor?.focus(), 50);
         e.stopPropagation();
         e.preventDefault();
@@ -129,8 +130,8 @@
 
     // Initialize / sync unitCode only if user hasn't explicitly cleared it
     $effect(() => {
-        if (units.length > 0 && unitCode != null) {
-            const resolved = units.find(item => item.code === unitCode) ?? standardUnit ?? units[0];
+        if (options.length > 0 && unitCode != null) {
+            const resolved = options.find(item => item.code === unitCode) ?? standardUnit ?? options[0];
             if (unitCode !== resolved?.code) {
                 unitCode = resolved?.code;
             }
@@ -189,9 +190,9 @@
             onchange={handleValueChange}
     />
 
-    {#snippet popupLayer()}
+    {#snippet popup()}
         <div class="options-popover" style={mh} role="listbox">
-            {#each units as op}
+            {#each options as op}
                 <div class="option-item"
                      onclick={handleUnitClick(op)} onkeydown={handleUnitKeyDown(op)}
                      role="option" tabindex="0" aria-selected={op.code === unitCode}>