@ticatec/uniface-element 0.3.23 → 5.0.1

package/dist/form/number_editor/README.md

@@ -0,0 +1,356 @@
+# NumberEditor
+
+A robust numeric input component with precision control, range validation, thousand-separator formatting, and IME-safe input handling. Built on top of `CommonEditor`.
+
+## Features
+
+- **Precision Control**: Limit decimal places; `precision={0}` enforces integer-only input.
+- **Range Validation**: Configurable `min` / `max` with automatic clamping on blur.
+- **Negative Numbers**: Optional support for negative values via `allowNegative`.
+- **Thousand Separators**: Automatically groups digits (e.g. `1,234.56`) in display mode.
+- **Prefix / Suffix**: Display currency symbols or units (e.g. `$`, `%`, `kg`).
+- **Real-time Validation**: Keystroke-level filtering plus composition (IME) and paste protection.
+- **Variants & Compact Mode**: Supports `plain`, `outlined`, `filled` variants and a compact layout.
+- **Icon Slots**: `leadingIcon` / `trailingIcon` snippet props.
+- **Tooltip & Error**: Inline tip and error display via `tooltip` / `error`.
+- **Programmatic Focus**: Exposes a `focus()` method.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let price = 29.99;
+</script>
+
+<NumberEditor bind:value={price} precision={2} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number \| undefined` | `undefined` | Current numeric value (bindable). |
+| `precision` | `number \| undefined` | `undefined` | Decimal places. `undefined` = any precision; `0` = integer only; `n > 0` = up to `n` decimals. |
+| `allowNegative` | `boolean` | `false` | Whether negative numbers are allowed. |
+| `max` | `number \| undefined` | `undefined` | Maximum allowed value (clamped on blur). |
+| `min` | `number \| undefined` | `undefined` | Minimum allowed value (clamped on blur). |
+| `prefix` | `string` | `""` | Text rendered before the value (e.g. `$`). |
+| `suffix` | `string` | `""` | Text rendered after the value (e.g. `%`). |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Visual style variant. |
+| `compact` | `boolean` | `false` | Compact spacing layout. |
+| `readonly` | `boolean` | `false` | Read-only display (no editing). |
+| `disabled` | `boolean` | `false` | Disables the input entirely. |
+| `tooltip` | `string` | `undefined` | Inline tooltip text (hidden when `readonly`/`disabled`). |
+| `error` | `string` | `undefined` | Inline error text; takes priority over `tooltip`. |
+| `theme` | `string` | `undefined` | Theme style name for switching appearance. |
+| `leadingIcon` | `Snippet` | `undefined` | Snippet rendered before the value/prefix. |
+| `trailingIcon` | `Snippet` | `undefined` | Snippet rendered after the value/suffix. |
+| `onchange` | `(value: number \| undefined) => void` | `undefined` | Fired with the committed numeric value (on input commit and blur). |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | Focus lifecycle handlers. |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | Blur lifecycle handler. |
+| `onkeydown` | `(e: KeyboardEvent) => void` | `undefined` | Key down handler. |
+| `onkeyup` | `(e: KeyboardEvent) => void` | `undefined` | Key up handler. |
+| `onkeypress` | `(e: KeyboardEvent) => void` | `undefined` | Key press handler. |
+
+### Event passthrough
+
+Any additional props prefixed with `input$` are forwarded to the underlying `<input>` element. For example `input$aria-label` becomes `aria-label` on the native input.
+
+The following attributes are always excluded (stripped even if supplied via `input$`), because they are managed internally by the editor: `type`, `readonly`, `disabled`, `required`, `wrap`, `value`, `max`, `min`, `step`.
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `focus()` | Programmatically focuses the underlying input element. |
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let editor;
+</script>
+
+<NumberEditor bind:this={editor} bind:value />
+<button onclick={() => editor.focus()}>Focus</button>
+```
+
+## How precision works
+
+`precision` controls both input filtering and formatting:
+
+| `precision` | Allowed input | Display example |
+|-------------|---------------|-----------------|
+| `undefined` | Any number of decimals | `1234.5678` → `1,234.5678` |
+| `0` | Integers only (`.` key is blocked) | `1234` → `1,234` |
+| `2` | Up to 2 decimals | `1234.5` → `1,234.50` |
+
+When `precision={0}`, the decimal point key is blocked at the keyboard level, and any attempt to introduce a decimal (via paste or IME) is rejected and reverted to the last valid value.
+
+## Examples
+
+### Currency Input
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let amount = 100.0;
+</script>
+
+<NumberEditor
+  bind:value={amount}
+  variant="outlined"
+  precision={2}
+  prefix="$"
+  min={0}
+/>
+```
+
+### Percentage Input
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let percentage = 15.5;
+</script>
+
+<NumberEditor
+  bind:value={percentage}
+  variant="filled"
+  precision={1}
+  suffix="%"
+  min={0}
+  max={100}
+/>
+```
+
+### Integer Only (e.g. Age)
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let age = 25;
+</script>
+
+<NumberEditor
+  bind:value={age}
+  variant="outlined"
+  precision={0}
+  min={0}
+  max={120}
+  input$aria-label="Age"
+  input$placeholder="Enter age"
+/>
+```
+
+### Weight with Leading Icon
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+  import Icon from "@ticatec/uniface-element/Icon";
+
+  let weight = 75.2;
+</script>
+
+<NumberEditor
+  bind:value={weight}
+  variant="outlined"
+  precision={3}
+  suffix="kg"
+  min={1}
+  max={200}
+>
+  {#snippet leadingIcon()}
+    <Icon name="scale" />
+  {/snippet}
+</NumberEditor>
+```
+
+### Temperature with Negative Values
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let temperature = -5.5;
+</script>
+
+<NumberEditor
+  bind:value={temperature}
+  variant="filled"
+  precision={1}
+  suffix="°C"
+  allowNegative={true}
+  min={-50}
+  max={50}
+/>
+```
+
+### Financial Calculator
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let principal = 10000;
+  let rate = 5.5;
+  let years = 10;
+
+  let interest = $derived((principal * rate * years) / 100);
+
+  function handlePrincipalChange(value) {
+    console.log("Principal changed to:", value);
+  }
+</script>
+
+<NumberEditor
+  bind:value={principal}
+  variant="outlined"
+  precision={2}
+  prefix="$"
+  min={1}
+  onchange={handlePrincipalChange}
+  input$aria-label="Principal amount"
+/>
+
+<NumberEditor
+  bind:value={rate}
+  variant="outlined"
+  precision={2}
+  suffix="%"
+  min={0}
+  max={100}
+  input$aria-label="Interest rate"
+/>
+
+<NumberEditor
+  bind:value={years}
+  variant="outlined"
+  precision={0}
+  min={1}
+  max={50}
+  input$aria-label="Years"
+/>
+
+<NumberEditor value={interest} readonly variant="filled" precision={2} prefix="$" />
+```
+
+### Compact Dimensions Form
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let dimensions = { width: 100, height: 50, depth: 25 };
+</script>
+
+<div class="dimensions-form">
+  <NumberEditor
+    bind:value={dimensions.width}
+    compact
+    variant="outlined"
+    precision={2}
+    suffix="cm"
+    input$placeholder="W"
+  />
+  <span>×</span>
+  <NumberEditor
+    bind:value={dimensions.height}
+    compact
+    variant="outlined"
+    precision={2}
+    suffix="cm"
+    input$placeholder="H"
+  />
+  <span>×</span>
+  <NumberEditor
+    bind:value={dimensions.depth}
+    compact
+    variant="outlined"
+    precision={2}
+    suffix="cm"
+    input$placeholder="D"
+  />
+</div>
+
+<style>
+  .dimensions-form {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+</style>
+```
+
+### Error & Tooltip
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let discount = 0;
+  let errorMsg = "";
+  let touched = false;
+
+  function handleChange(value) {
+    touched = true;
+    errorMsg = value != null && value > 100 ? "Discount cannot exceed 100" : "";
+  }
+</script>
+
+<NumberEditor
+  bind:value={discount}
+  precision={2}
+  suffix="%"
+  min={0}
+  max={100}
+  error={errorMsg}
+  tooltip="Enter the discount percentage (0–100)"
+  onchange={handleChange}
+/>
+```
+
+## Validation Behavior
+
+NumberEditor validates input through multiple layers:
+
+- **Precision**: The `.` key is blocked when `precision={0}`; extra decimals are rejected during typing.
+- **Range**: On blur, the value is clamped to `[min, max]`.
+- **Negative**: The `-` key is blocked when `allowNegative={false}`.
+- **Characters**: Non-numeric and full-width (CJK) characters are blocked; IME composition that yields invalid input is reverted.
+- **Paste**: Pasted content is validated against the format and constraints before being accepted.
+- **Revert**: If an input does not pass validation, the editor reverts to the last valid value instead of accepting invalid text.
+
+## Best Practices
+
+1. **Pick the right `precision`**: Use `0` for IDs/counts, `2` for currency, and avoid leaving it unset (`undefined`) unless free-form decimals are truly needed.
+2. **Always set `min`/`max`** for bounded quantities to prevent invalid submissions.
+3. **Use `readonly` for computed fields** and `disabled` for inputs that are not currently applicable.
+4. **Provide `prefix`/`suffix`** for units and currency to improve readability.
+5. **Wire `onchange`** for cross-field calculations or server-side validation rather than relying solely on `bind:value`.
+6. **Prefer `error` over `tooltip`** when validation feedback is available, since `error` takes visual priority.
+7. **Add `input$aria-label`** when the editor is not paired with a visible label, for accessibility.
+
+## Related Components
+
+- [TextEditor](../text_editor/README.md) — General text input.
+- [UnitNumberEditor](../unit-number-editor/README.md) — Numeric input with a selectable unit.
+- [DateEditor](../date_picker/README.md) — Date input.

package/dist/form/number_editor/README_CN.md

@@ -0,0 +1,356 @@
+# NumberEditor
+
+功能完善的数字输入组件，支持精度控制、范围校验、千分位格式化以及对 IME/粘贴场景的安全处理。基于 `CommonEditor` 构建。
+
+## 特性
+
+- **精度控制**：限制小数位数，`precision={0}` 时仅允许输入整数。
+- **范围校验**：可配置 `min` / `max`，失焦时自动收敛到合法区间。
+- **负数支持**：通过 `allowNegative` 控制是否允许负值。
+- **千分位分隔**：自动按千位分组（如 `1,234.56`）。
+- **前缀 / 后缀**：显示货币符号或单位（如 `$`、`%`、`kg`）。
+- **实时校验**：按键级过滤，并在 IME 输入和粘贴时做兜底保护。
+- **变体与紧凑模式**：支持 `plain`、`outlined`、`filled` 变体以及紧凑布局。
+- **图标插槽**：通过 `leadingIcon` / `trailingIcon` 代码片段插入图标。
+- **提示与错误**：通过 `tooltip` / `error` 显示内联提示与错误信息。
+- **编程聚焦**：对外暴露 `focus()` 方法。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 引入
+
+```typescript
+import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+```
+
+## 基础用法
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let price = 29.99;
+</script>
+
+<NumberEditor bind:value={price} precision={2} />
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `number \| undefined` | `undefined` | 当前数值（可双向绑定）。 |
+| `precision` | `number \| undefined` | `undefined` | 小数位数。`undefined` = 任意精度；`0` = 仅整数；`n > 0` = 最多 n 位小数。 |
+| `allowNegative` | `boolean` | `false` | 是否允许输入负数。 |
+| `max` | `number \| undefined` | `undefined` | 允许的最大值（失焦时收敛）。 |
+| `min` | `number \| undefined` | `undefined` | 允许的最小值（失焦时收敛）。 |
+| `prefix` | `string` | `""` | 显示在数值前的文本（如 `$`）。 |
+| `suffix` | `string` | `""` | 显示在数值后的文本（如 `%`）。 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉风格变体。 |
+| `compact` | `boolean` | `false` | 是否使用紧凑布局。 |
+| `readonly` | `boolean` | `false` | 是否只读（不可编辑）。 |
+| `disabled` | `boolean` | `false` | 是否禁用。 |
+| `tooltip` | `string` | `undefined` | 内联提示文本（只读/禁用时隐藏）。 |
+| `error` | `string` | `undefined` | 内联错误文本；优先级高于 `tooltip`。 |
+| `theme` | `string` | `undefined` | 主题样式名称，用于切换组件外观。 |
+| `leadingIcon` | `Snippet` | `undefined` | 渲染在前缀之前的代码片段。 |
+| `trailingIcon` | `Snippet` | `undefined` | 渲染在后缀之后的代码片段。 |
+| `onchange` | `(value: number \| undefined) => void` | `undefined` | 提交新值时触发（输入提交与失焦时）。 |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | 获取焦点时触发。 |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | 失去焦点时触发。 |
+| `onkeydown` | `(e: KeyboardEvent) => void` | `undefined` | 按键按下时触发。 |
+| `onkeyup` | `(e: KeyboardEvent) => void` | `undefined` | 按键抬起时触发。 |
+| `onkeypress` | `(e: KeyboardEvent) => void` | `undefined` | 按键按下时触发。 |
+
+### 事件透传
+
+任何以 `input$` 为前缀的额外属性都会被透传给底层 `<input>` 元素。例如 `input$aria-label` 会被转换成原生 input 的 `aria-label`。
+
+以下属性由于由编辑器内部管理，即便通过 `input$` 前缀传入也会被剔除：`type`、`readonly`、`disabled`、`required`、`wrap`、`value`、`max`、`min`、`step`。
+
+## 方法（Methods）
+
+| 方法 | 说明 |
+|------|------|
+| `focus()` | 编程方式让底层 input 获取焦点。 |
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let editor;
+</script>
+
+<NumberEditor bind:this={editor} bind:value />
+<button onclick={() => editor.focus()}>聚焦</button>
+```
+
+## 精度（precision）的工作机制
+
+`precision` 同时控制输入过滤与格式化显示：
+
+| `precision` | 允许的输入 | 显示示例 |
+|-------------|-----------|----------|
+| `undefined` | 任意小数位 | `1234.5678` → `1,234.5678` |
+| `0` | 仅整数（`.` 键被屏蔽） | `1234` → `1,234` |
+| `2` | 最多 2 位小数 | `1234.5` → `1,234.50` |
+
+当 `precision={0}` 时，小数点按键在键盘事件层即被屏蔽；任何通过粘贴或 IME 引入小数点的尝试都会被拒绝，并回退到上一个有效值。
+
+## 示例
+
+### 货币输入
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let amount = 100.0;
+</script>
+
+<NumberEditor
+  bind:value={amount}
+  variant="outlined"
+  precision={2}
+  prefix="$"
+  min={0}
+/>
+```
+
+### 百分比输入
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let percentage = 15.5;
+</script>
+
+<NumberEditor
+  bind:value={percentage}
+  variant="filled"
+  precision={1}
+  suffix="%"
+  min={0}
+  max={100}
+/>
+```
+
+### 仅整数（如年龄）
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let age = 25;
+</script>
+
+<NumberEditor
+  bind:value={age}
+  variant="outlined"
+  precision={0}
+  min={0}
+  max={120}
+  input$aria-label="年龄"
+  input$placeholder="请输入年龄"
+/>
+```
+
+### 带前导图标的重量输入
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+  import Icon from "@ticatec/uniface-element/Icon";
+
+  let weight = 75.2;
+</script>
+
+<NumberEditor
+  bind:value={weight}
+  variant="outlined"
+  precision={3}
+  suffix="kg"
+  min={1}
+  max={200}
+>
+  {#snippet leadingIcon()}
+    <Icon name="scale" />
+  {/snippet}
+</NumberEditor>
+```
+
+### 允许负数的温度输入
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let temperature = -5.5;
+</script>
+
+<NumberEditor
+  bind:value={temperature}
+  variant="filled"
+  precision={1}
+  suffix="°C"
+  allowNegative={true}
+  min={-50}
+  max={50}
+/>
+```
+
+### 财务计算器
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let principal = 10000;
+  let rate = 5.5;
+  let years = 10;
+
+  let interest = $derived((principal * rate * years) / 100);
+
+  function handlePrincipalChange(value) {
+    console.log("本金变更为：", value);
+  }
+</script>
+
+<NumberEditor
+  bind:value={principal}
+  variant="outlined"
+  precision={2}
+  prefix="$"
+  min={1}
+  onchange={handlePrincipalChange}
+  input$aria-label="本金金额"
+/>
+
+<NumberEditor
+  bind:value={rate}
+  variant="outlined"
+  precision={2}
+  suffix="%"
+  min={0}
+  max={100}
+  input$aria-label="利率"
+/>
+
+<NumberEditor
+  bind:value={years}
+  variant="outlined"
+  precision={0}
+  min={1}
+  max={50}
+  input$aria-label="年限"
+/>
+
+<NumberEditor value={interest} readonly variant="filled" precision={2} prefix="$" />
+```
+
+### 紧凑尺寸表单
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let dimensions = { width: 100, height: 50, depth: 25 };
+</script>
+
+<div class="dimensions-form">
+  <NumberEditor
+    bind:value={dimensions.width}
+    compact
+    variant="outlined"
+    precision={2}
+    suffix="cm"
+    input$placeholder="宽"
+  />
+  <span>×</span>
+  <NumberEditor
+    bind:value={dimensions.height}
+    compact
+    variant="outlined"
+    precision={2}
+    suffix="cm"
+    input$placeholder="高"
+  />
+  <span>×</span>
+  <NumberEditor
+    bind:value={dimensions.depth}
+    compact
+    variant="outlined"
+    precision={2}
+    suffix="cm"
+    input$placeholder="深"
+  />
+</div>
+
+<style>
+  .dimensions-form {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+</style>
+```
+
+### 错误与提示
+
+```svelte
+<script>
+  import NumberEditor from "@ticatec/uniface-element/NumberEditor";
+
+  let discount = 0;
+  let errorMsg = "";
+  let touched = false;
+
+  function handleChange(value) {
+    touched = true;
+    errorMsg = value != null && value > 100 ? "折扣不能超过 100" : "";
+  }
+</script>
+
+<NumberEditor
+  bind:value={discount}
+  precision={2}
+  suffix="%"
+  min={0}
+  max={100}
+  error={errorMsg}
+  tooltip="请输入折扣百分比（0–100）"
+  onchange={handleChange}
+/>
+```
+
+## 校验行为
+
+NumberEditor 通过多层机制保证输入合法：
+
+- **精度**：`precision={0}` 时屏蔽 `.` 键；输入过程中拒绝多余的小数位。
+- **范围**：失焦时将数值收敛到 `[min, max]`。
+- **负数**：`allowNegative={false}` 时屏蔽 `-` 键。
+- **字符**：屏蔽非数字字符与全角（CJK）字符；若 IME 输入结果不合法，则回退。
+- **粘贴**：粘贴内容会先经过格式与约束校验，再决定是否接受。
+- **回退**：一旦输入未通过校验，编辑器会回退到上一个有效值，而非接受非法文本。
+
+## 最佳实践
+
+1. **选择合适的 `precision`**：ID/计数用 `0`，金额用 `2`，除非确实需要任意小数，否则避免使用 `undefined`（不设精度）。
+2. **为有界量值设置 `min`/`max`**，避免提交非法值。
+3. **计算字段用 `readonly`**，不适用的字段用 `disabled`。
+4. **善用 `prefix`/`suffix`** 标注单位与货币，提升可读性。
+5. **跨字段联动或服务端校验优先使用 `onchange`**，而不要只依赖 `bind:value`。
+6. **存在校验反馈时优先使用 `error`**，其视觉优先级高于 `tooltip`。
+7. **无可见 label 时添加 `input$aria-label`**，以保证可访问性。
+
+## 相关组件
+
+- [TextEditor](../text_editor/README_CN.md) — 通用文本输入。
+- [UnitNumberEditor](../unit-number-editor/README_CN.md) — 带可选单位的数字输入。
+- [DateEditor](../date_picker/README_CN.md) — 日期输入。