@ticatec/topside-elements 1.0.0

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

@@ -0,0 +1,352 @@
+# 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`.
+
+## Features
+
+- **Unit Conversion**: Automatic conversion between units via configurable ratios.
+- **Unit Dropdown**: Trailing-side dropdown for switching units.
+- **Standard Unit Storage**: `value` is always stored in the standard unit (ratio = 1).
+- **Per-Unit Precision**: Each unit can declare its own `precision`, `min`, `max`.
+- **Clear Functionality**: Built-in clear button.
+- **Variants**: Support for `plain`, `outlined`, `filled` styles.
+- **Leading Icon**: Custom snippet slot for icons.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let weightValue: number | undefined = 75; // standard unit (kg)
+  let weightUnit = "kg";
+
+  const weightUnits: UnitOption[] = [
+    { code: "kg", text: "Kilograms", ratio: 1, precision: 2 },
+    { code: "lb", text: "Pounds", ratio: 2.20462, precision: 2 },
+    { code: "g", text: "Grams", ratio: 1000, precision: 0 }
+  ];
+</script>
+
+<UnitNumberEditor
+  bind:value={weightValue}
+  bind:unitCode={weightUnit}
+  options={weightUnits}
+  placeholder="Enter weight"
+/>
+```
+
+## Props
+
+| 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 `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). |
+| `readonly` | `boolean` | `false` | Read-only mode (renders a read-only display). |
+| `prefix` | `string` | `""` | Text prefix shown before the input. |
+| `placeholder` | `string` | `""` | Placeholder for the underlying `<input>`. |
+| `allowNegative` | `boolean` | `false` | Allow negative numbers. |
+| `tooltip` | `string` | `undefined` | Hover tooltip text. |
+| `error` | `string` | `undefined` | Error message text. |
+| `theme` | `string` | `undefined` | Theme name for appearance switching. |
+| `style` | `string` | `""` | Inline CSS styles. |
+| `menu$height` | `number` | `0` | Fixed height (px) for the unit dropdown. `0` means auto. |
+| `leadingIcon` | `Snippet` | `undefined` | Custom snippet rendered before the input. |
+| `onchange` | `(value: number \| undefined) => void` | `undefined` | Fires on user-initiated value changes. Receives the new standard-unit value. |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | Input gains focus. Suppressed while the unit dropdown is open. |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | Input loses focus. Suppressed while the unit dropdown is open. |
+
+## UnitOption
+
+```typescript
+interface UnitOption {
+  code: string;            // unit identifier, e.g. "kg"
+  text?: string;           // display label, e.g. "Kilograms" (falls back to code)
+  ratio?: number;          // multiply standard value by ratio to get display value
+  precision?: number;      // decimal places for this unit
+  max?: number;            // max value in this unit
+  min?: number;            // min value in this unit
+}
+```
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `focus()` | Programmatically focus the underlying input. |
+
+## Conversion Logic
+
+1. **Standard unit** — exactly one unit should have `ratio: 1`. Its `code` is the canonical unit.
+2. **User types** in the current unit → the entered value is divided by `unit.ratio` and stored in `value`.
+3. **Display** — when `value` or the selected unit changes (and the input is not focused), the display is recomputed as `value × unit.ratio`.
+4. **External `value` changes** propagate to the display the same way, as long as the input is not focused.
+
+Example: with `kg` as standard (`ratio: 1`) and `lb` (`ratio: 2.20462`):
+
+```text
+User types 100 in lb → value = 100 / 2.20462 ≈ 45.36 (kg)
+Switch to kg        → display = 45.36 × 1       = 45.36
+Switch back to lb   → display = 45.36 × 2.20462 ≈ 100
+```
+
+## Examples
+
+### Weight Converter with Change Callback
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let weight: number | undefined = 70;
+  let weightUnit = "kg";
+
+  const weightUnits: UnitOption[] = [
+    { code: "kg", text: "Kilograms", ratio: 1, precision: 2 },
+    { code: "lb", text: "Pounds", ratio: 2.20462, precision: 2 },
+    { code: "g", text: "Grams", ratio: 1000, precision: 0 }
+  ];
+
+  const handleChange = (v: number | undefined) => {
+    console.log(`Standard-unit value: ${v} kg`);
+  };
+</script>
+
+<UnitNumberEditor
+  bind:value={weight}
+  bind:unitCode={weightUnit}
+  options={weightUnits}
+  onchange={handleChange}
+  placeholder="Enter weight"
+/>
+```
+
+### Distance with Min/Max per Unit
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let distance: number | undefined;
+  let distanceUnit = "m";
+
+  const distanceUnits: UnitOption[] = [
+    { code: "m", text: "Meters", ratio: 1, precision: 2, min: 0 },
+    { code: "cm", text: "Centimeters", ratio: 100, precision: 0, min: 0 },
+    { code: "mm", text: "Millimeters", ratio: 1000, precision: 0, min: 0 }
+  ];
+</script>
+
+<UnitNumberEditor
+  bind:value={distance}
+  bind:unitCode={distanceUnit}
+  options={distanceUnits}
+  placeholder="Enter distance"
+/>
+```
+
+### Focus and Blur Tracking
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let value: number | undefined;
+  let unit = "kg";
+  let isFocused = false;
+
+  const options: UnitOption[] = [
+    { code: "kg", text: "Kilograms", ratio: 1, precision: 2 },
+    { code: "lb", text: "Pounds", ratio: 2.20462, precision: 2 }
+  ];
+
+  const handleFocus = () => { isFocused = true; console.log("focused"); };
+  const handleBlur = () => { isFocused = false; console.log("blurred"); };
+</script>
+
+<UnitNumberEditor
+  bind:value={value}
+  bind:unitCode={unit}
+  options={options}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+  placeholder="Enter value"
+/>
+
+<p>{isFocused ? "Input is focused" : "Input is not focused"}</p>
+```
+
+### Variants
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let v1: number | undefined = 100;
+  let v2: number | undefined = 200;
+  let v3: number | undefined = 300;
+  let u1 = "m", u2 = "m", u3 = "m";
+
+  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} 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
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let price: number | undefined = 19.99;
+  let currency = "USD";
+
+  const currencies: UnitOption[] = [
+    { code: "USD", text: "USD" },
+    { code: "CNY", text: "CNY" },
+    { code: "EUR", text: "EUR" }
+  ];
+</script>
+
+<UnitNumberEditor
+  bind:value={price}
+  bind:unitCode={currency}
+  options={currencies}
+  prefix="$"
+>
+  {#snippet leadingIcon()}
+    <i class="icon_google_attach_money" aria-hidden="true"></i>
+  {/snippet}
+</UnitNumberEditor>
+```
+
+### Programmatic Focus
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let editor: UnitNumberEditor;
+  let value: number | undefined;
+  let unit = "kg";
+
+  const options: UnitOption[] = [
+    { code: "kg", text: "Kilograms", ratio: 1, precision: 2 },
+    { code: "lb", text: "Pounds", ratio: 2.20462, precision: 2 }
+  ];
+
+  const focusEditor = () => editor?.focus();
+</script>
+
+<button onclick={focusEditor}>Focus editor</button>
+
+<UnitNumberEditor
+  bind:this={editor}
+  bind:value={value}
+  bind:unitCode={unit}
+  options={options}
+  placeholder="Click the button to focus me"
+/>
+```
+
+### Disabled and Readonly
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let normalValue: number | undefined = 50;
+  let readonlyValue: number | undefined = 75;
+  let unit = "kg";
+
+  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} 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
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let amount: number | undefined = 250;
+  let unit = "ml";
+
+  const volumeUnits: UnitOption[] = [
+    { code: "ml", text: "Milliliters", ratio: 1, precision: 0 },
+    { code: "l", text: "Liters", ratio: 0.001, precision: 3 },
+    { code: "cup", text: "Cups", ratio: 0.00236588, precision: 3 },
+    { code: "tbsp", text: "Tablespoons", ratio: 0.0000147868, precision: 6 }
+  ];
+</script>
+
+<div class="cooking-converter">
+  <h3>Cooking Converter</h3>
+  <UnitNumberEditor
+    bind:value={amount}
+    bind:unitCode={unit}
+    options={volumeUnits}
+    placeholder="Enter amount"
+  />
+  <p>Standard unit value: {amount ?? "—"} ml</p>
+</div>
+
+<style>
+  .cooking-converter {
+    max-width: 400px;
+  }
+  h3 {
+    margin-bottom: 16px;
+  }
+  p {
+    color: #6b7280;
+    margin-top: 12px;
+  }
+</style>
+```
+
+## Notes
+
+- **Focus & dropdown interaction**: Opening the unit dropdown does not fire `onblur`; closing it via outside-click fires it only if focus does not return to the input.
+- **Negative numbers**: Pass `allowNegative` to allow `-` in the input.
+- **No standard unit**: If no `UnitOption` has `ratio: 1`, the component treats the first unit as the base and skips ratio conversion.
+- **Precision**: Each unit can declare its own `precision`, `min`, `max`. Validation is delegated to the underlying `NumberInput`.
+
+## Related Components
+
+- [NumberEditor](../number_editor/README.md) — Numeric input without units.
+- [TextEditor](../text_editor/README.md) — Plain text input.
+- [PromptsTextEditor](../prompts_text_editor/README.md) — Text input with suggestion dropdown.

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

@@ -0,0 +1,352 @@
+# 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`。
+
+## 功能特性
+
+- **单位转换**: 通过可配置的比率在不同单位之间自动转换。
+- **单位下拉**: 右侧下拉菜单切换单位。
+- **标准单位存储**: `value` 始终存储在标准单位（ratio = 1）中。
+- **单位专属精度**: 每个单位可声明各自的 `precision`、`min`、`max`。
+- **清除功能**: 内置清除按钮。
+- **多种变体**: 支持 `plain`、`outlined`、`filled` 样式。
+- **前导图标**: 支持自定义代码片段插槽。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+```
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let weightValue: number | undefined = 75; // 标准单位（kg）
+  let weightUnit = "kg";
+
+  const weightUnits: UnitOption[] = [
+    { code: "kg", text: "千克", ratio: 1, precision: 2 },
+    { code: "lb", text: "磅", ratio: 2.20462, precision: 2 },
+    { code: "g", text: "克", ratio: 1000, precision: 0 }
+  ];
+</script>
+
+<UnitNumberEditor
+  bind:value={weightValue}
+  bind:unitCode={weightUnit}
+  options={weightUnits}
+  placeholder="输入重量"
+/>
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `number \| undefined` | `undefined` | **标准单位**中的值（`ratio === 1` 的单位）。支持 `bind:value`。 |
+| `unitCode` | `string \| undefined` | 第一个单位的 code | 当前选中的单位代码。支持 `bind:unitCode`。不匹配时回退到标准单位，再回退到 `options[0]`。 |
+| `options` | `Array<UnitOption>` | —（必填） | 可用单位列表。其中应有一个 `ratio: 1`。 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉变体。 |
+| `compact` | `boolean` | `false` | 使用紧凑间距。 |
+| `disabled` | `boolean` | `false` | 禁用编辑（显示为只读）。 |
+| `readonly` | `boolean` | `false` | 只读模式（显示为只读）。 |
+| `prefix` | `string` | `""` | 输入框前面的文本。 |
+| `placeholder` | `string` | `""` | 底层 `<input>` 的占位符。 |
+| `allowNegative` | `boolean` | `false` | 允许负数。 |
+| `tooltip` | `string` | `undefined` | 悬停提示文本。 |
+| `error` | `string` | `undefined` | 错误信息文本。 |
+| `theme` | `string` | `undefined` | 主题名称，用于切换外观。 |
+| `style` | `string` | `""` | 内联 CSS 样式。 |
+| `menu$height` | `number` | `0` | 单位下拉菜单的固定高度（像素）。`0` 表示自动。 |
+| `leadingIcon` | `Snippet` | `undefined` | 渲染在输入框前面的自定义代码片段。 |
+| `onchange` | `(value: number \| undefined) => void` | `undefined` | 用户操作导致值变化时触发，返回新的标准单位值。 |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | 输入框获得焦点时触发。打开单位下拉时抑制。 |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | 输入框失去焦点时触发。打开单位下拉时抑制。 |
+
+## UnitOption
+
+```typescript
+interface UnitOption {
+  code: string;            // 单位标识符，如 "kg"
+  text?: string;           // 显示标签，如 "千克"（回退到 code）
+  ratio?: number;          // 标准值乘以该比率得到显示值
+  precision?: number;      // 该单位的小数位数
+  max?: number;            // 该单位的最大值
+  min?: number;            // 该单位的最小值
+}
+```
+
+## 方法
+
+| 方法 | 说明 |
+|------|------|
+| `focus()` | 编程方式让底层 input 获取焦点。 |
+
+## 转换逻辑
+
+1. **标准单位** — 应恰好有一个 `ratio: 1` 的单位，其 `code` 即为标准单位。
+2. **用户输入** — 在当前单位中输入的值除以 `unit.ratio` 后存入 `value`。
+3. **显示** — 当 `value` 或选中单位变化时（且输入框未聚焦），显示值按 `value × unit.ratio` 重新计算。
+4. **外部 `value` 变化** — 只要输入框未聚焦，同样传播到显示值。
+
+示例：以 `kg` 为标准（`ratio: 1`），`lb` 的 `ratio: 2.20462`：
+
+```text
+用户在 lb 中输入 100 → value = 100 / 2.20462 ≈ 45.36（kg）
+切换到 kg            → 显示 = 45.36 × 1       = 45.36
+切换回 lb            → 显示 = 45.36 × 2.20462 ≈ 100
+```
+
+## 示例
+
+### 重量转换器（带变更回调）
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let weight: number | undefined = 70;
+  let weightUnit = "kg";
+
+  const weightUnits: UnitOption[] = [
+    { code: "kg", text: "千克", ratio: 1, precision: 2 },
+    { code: "lb", text: "磅", ratio: 2.20462, precision: 2 },
+    { code: "g", text: "克", ratio: 1000, precision: 0 }
+  ];
+
+  const handleChange = (v: number | undefined) => {
+    console.log(`标准单位值: ${v} kg`);
+  };
+</script>
+
+<UnitNumberEditor
+  bind:value={weight}
+  bind:unitCode={weightUnit}
+  options={weightUnits}
+  onchange={handleChange}
+  placeholder="输入重量"
+/>
+```
+
+### 带单位专属最小/最大值的距离输入
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let distance: number | undefined;
+  let distanceUnit = "m";
+
+  const distanceUnits: UnitOption[] = [
+    { code: "m", text: "米", ratio: 1, precision: 2, min: 0 },
+    { code: "cm", text: "厘米", ratio: 100, precision: 0, min: 0 },
+    { code: "mm", text: "毫米", ratio: 1000, precision: 0, min: 0 }
+  ];
+</script>
+
+<UnitNumberEditor
+  bind:value={distance}
+  bind:unitCode={distanceUnit}
+  options={distanceUnits}
+  placeholder="输入距离"
+/>
+```
+
+### 焦点跟踪
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let value: number | undefined;
+  let unit = "kg";
+  let isFocused = false;
+
+  const options: UnitOption[] = [
+    { code: "kg", text: "千克", ratio: 1, precision: 2 },
+    { code: "lb", text: "磅", ratio: 2.20462, precision: 2 }
+  ];
+
+  const handleFocus = () => { isFocused = true; console.log("获得焦点"); };
+  const handleBlur = () => { isFocused = false; console.log("失去焦点"); };
+</script>
+
+<UnitNumberEditor
+  bind:value={value}
+  bind:unitCode={unit}
+  options={options}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+  placeholder="输入值"
+/>
+
+<p>{isFocused ? "输入框已聚焦" : "输入框未聚焦"}</p>
+```
+
+### 不同变体
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let v1: number | undefined = 100;
+  let v2: number | undefined = 200;
+  let v3: number | undefined = 300;
+  let u1 = "m", u2 = "m", u3 = "m";
+
+  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} 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="填充" />
+```
+
+### 自定义前导图标
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let price: number | undefined = 19.99;
+  let currency = "USD";
+
+  const currencies: UnitOption[] = [
+    { code: "USD", text: "美元" },
+    { code: "CNY", text: "人民币" },
+    { code: "EUR", text: "欧元" }
+  ];
+</script>
+
+<UnitNumberEditor
+  bind:value={price}
+  bind:unitCode={currency}
+  options={currencies}
+  prefix="$"
+>
+  {#snippet leadingIcon()}
+    <i class="icon_google_attach_money" aria-hidden="true"></i>
+  {/snippet}
+</UnitNumberEditor>
+```
+
+### 编程聚焦
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let editor: UnitNumberEditor;
+  let value: number | undefined;
+  let unit = "kg";
+
+  const options: UnitOption[] = [
+    { code: "kg", text: "千克", ratio: 1, precision: 2 },
+    { code: "lb", text: "磅", ratio: 2.20462, precision: 2 }
+  ];
+
+  const focusEditor = () => editor?.focus();
+</script>
+
+<button onclick={focusEditor}>聚焦编辑器</button>
+
+<UnitNumberEditor
+  bind:this={editor}
+  bind:value={value}
+  bind:unitCode={unit}
+  options={options}
+  placeholder="点击按钮聚焦我"
+/>
+```
+
+### 禁用与只读
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let normalValue: number | undefined = 50;
+  let readonlyValue: number | undefined = 75;
+  let unit = "kg";
+
+  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} options={options} placeholder="正常" />
+<UnitNumberEditor bind:value={readonlyValue} bind:unitCode={unit} options={options} readonly />
+<UnitNumberEditor bind:value={normalValue} bind:unitCode={unit} options={options} disabled />
+```
+
+### 烹饪单位转换器
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from "@ticatec/topside-elements/UnitNumberEditor";
+
+  let amount: number | undefined = 250;
+  let unit = "ml";
+
+  const volumeUnits: UnitOption[] = [
+    { code: "ml", text: "毫升", ratio: 1, precision: 0 },
+    { code: "l", text: "升", ratio: 0.001, precision: 3 },
+    { code: "cup", text: "杯", ratio: 0.00236588, precision: 3 },
+    { code: "tbsp", text: "大汤匙", ratio: 0.0000147868, precision: 6 }
+  ];
+</script>
+
+<div class="cooking-converter">
+  <h3>烹饪单位转换</h3>
+  <UnitNumberEditor
+    bind:value={amount}
+    bind:unitCode={unit}
+    options={volumeUnits}
+    placeholder="输入数量"
+  />
+  <p>标准单位值：{amount ?? "—"} ml</p>
+</div>
+
+<style>
+  .cooking-converter {
+    max-width: 400px;
+  }
+  h3 {
+    margin-bottom: 16px;
+  }
+  p {
+    color: #6b7280;
+    margin-top: 12px;
+  }
+</style>
+```
+
+## 注意事项
+
+- **焦点与下拉交互**: 打开单位下拉菜单不会触发 `onblur`；通过点击外部关闭时，若焦点未回到输入框则触发 `onblur`。
+- **负数**: 传入 `allowNegative` 以允许输入负数。
+- **无标准单位**: 如果没有 `UnitOption` 的 `ratio: 1`，组件将第一个单位视为基准，跳过比率转换。
+- **精度**: 每个单位可声明各自的 `precision`、`min`、`max`。校验委托给底层的 `NumberInput`。
+
+## 相关组件
+
+- [NumberEditor](../number_editor/README_CN.md) — 不带单位的数字输入。
+- [TextEditor](../text_editor/README_CN.md) — 普通文本输入。
+- [PromptsTextEditor](../prompts_text_editor/README_CN.md) — 带建议下拉的文本输入。