@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/number-editor/README.md

@@ -1,26 +1,357 @@
 # NumberEditor
 
-## 使用方法
-
-```sveltehtml
-<NumberEditor filled max={500} suffix="KG" compact/>
-```
-
-## 属性
-| 属性            | 描述               | 类型              |
-|---|------------------|-----------------|
-| disabled      | 当前的数字输入框是否可用     | true / false    |
-| readonly      | 当前的数字输入框为只读或者可编辑 | true / false    |
-| outlined      | 当前的是否带边框         | true / false    |
-| filled        | 当前输入框是否填充        | true / false    |
-| compact       | 按照紧凑格式显示         | true / false    |
-| style         | 自定义style         | 字符串             |
-| value         | 值                | true / false    |
-| precision     | 精度               | 整数              |
-| suffix        | 后缀               | 字符              |
-| prefix        | 前缀               | 字符              |
-| allowNegative | 是否可以是负数          | true / false    |
-| displayMode   | 最小值              | 0(格式显示) / 1（正常） |
-| max           | 最大值              | 数字              |
+A robust number input component that provides precision control, validation, and formatting for numeric data entry.
 
+## Features
 
+- **Precision Control**: Configure decimal places for accurate number formatting
+- **Range Validation**: Set min/max values with automatic boundary enforcement
+- **Negative Numbers**: Optional support for negative values
+- **Custom Formatting**: Add prefix/suffix text for currency, units, etc.
+- **Input Validation**: Real-time validation with proper error handling
+- **Multiple Variants**: Support for outlined, filled, plain, and default styles
+- **Display Mode**: Switch between edit and view modes
+- **Action Icons**: Built-in clear functionality with customizable icons
+- **Focus Management**: Programmatic focus control with setFocus method
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
+  
+  let price = 29.99;
+</script>
+
+<NumberEditor bind:value={price} />
+```
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number \| null` | `undefined` | The current numeric value |
+| `disabled` | `boolean` | `false` | Disables the input |
+| `readonly` | `boolean` | `false` | Makes the input read-only |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Visual style variant |
+| `compact` | `boolean` | `false` | Enables compact display mode |
+| `style` | `string` | `''` | Custom CSS styles |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `precision` | `number \| null` | `null` | Number of decimal places |
+| `suffix` | `string` | `''` | Text to display after the value |
+| `prefix` | `string` | `''` | Text to display before the value |
+| `allowNegative` | `boolean` | `false` | Allow negative numbers |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Edit or view mode |
+| `max` | `number \| null` | `null` | Maximum allowed value |
+| `min` | `number \| null` | `null` | Minimum allowed value |
+| `removable` | `boolean` | `true` | Show clear button when value exists |
+| `onchange` | `OnChangeHandler<number \| null>` | `null` | Change event handler |
+| `class` | `string` | `''` | CSS class name |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `setFocus()` | Programmatically focus the input field |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| `leading-icon` | Icon to display before the input |
+| `trailing-icon` | Icon to display after the input |
+
+## Examples
+
+### Currency Input
+
+```svelte
+<script>
+  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
+  import FormField from '@ticatec/uniface-element/FormField';
+  
+  let amount = 100.00;
+</script>
+
+<FormField label="Amount">
+  <NumberEditor 
+    bind:value={amount}
+    variant="outlined"
+    precision={2}
+    prefix="$"
+    allowNegative={false}
+    min={0}
+  />
+</FormField>
+```
+
+### 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}
+/>
+```
+
+### Weight/Measurement Input
+
+```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}
+>
+  <svelte:fragment slot="leading-icon">
+    <Icon name="scale" />
+  </svelte:fragment>
+</NumberEditor>
+```
+
+### Integer Only Input
+
+```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}
+  placeholder="Enter age"
+/>
+```
+
+### Temperature Input (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';
+  import FormField from '@ticatec/uniface-element/FormField';
+  
+  let principal = 10000;
+  let rate = 5.5;
+  let years = 10;
+  
+  $: interest = (principal * rate * years) / 100;
+  
+  function handlePrincipalChange(value) {
+    console.log('Principal changed to:', value);
+  }
+</script>
+
+<div class="calculator">
+  <FormField label="Principal Amount">
+    <NumberEditor 
+      bind:value={principal}
+      variant="outlined"
+      precision={2}
+      prefix="$"
+      min={1}
+      onchange={handlePrincipalChange}
+    />
+  </FormField>
+  
+  <FormField label="Interest Rate">
+    <NumberEditor 
+      bind:value={rate}
+      variant="outlined"
+      precision={2}
+      suffix="%"
+      min={0}
+      max={100}
+    />
+  </FormField>
+  
+  <FormField label="Years">
+    <NumberEditor 
+      bind:value={years}
+      variant="outlined"
+      precision={0}
+      min={1}
+      max={50}
+    />
+  </FormField>
+  
+  <FormField label="Total Interest">
+    <NumberEditor 
+      value={interest}
+      readonly
+      variant="filled"
+      precision={2}
+      prefix="$"
+    />
+  </FormField>
+</div>
+```
+
+### View Mode Display
+
+```svelte
+<script>
+  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
+  import { DisplayMode } from '@ticatec/uniface-element';
+  
+  let value = 1234.56;
+  let isEditing = false;
+</script>
+
+<NumberEditor 
+  bind:value
+  displayMode={isEditing ? DisplayMode.Edit : DisplayMode.View}
+  precision={2}
+  prefix="$"
+  variant="outlined"
+/>
+
+<button on:click={() => isEditing = !isEditing}>
+  {isEditing ? 'View' : 'Edit'}
+</button>
+```
+
+### Compact Form Layout
+
+```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"
+    placeholder="W"
+  />
+  <span>�</span>
+  <NumberEditor 
+    bind:value={dimensions.height}
+    compact
+    variant="outlined"
+    precision={2}
+    suffix="cm"
+    placeholder="H"
+  />
+  <span>�</span>
+  <NumberEditor 
+    bind:value={dimensions.depth}
+    compact
+    variant="outlined"
+    precision={2}
+    suffix="cm"
+    placeholder="D"
+  />
+</div>
+
+<style>
+  .dimensions-form {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+</style>
+```
+
+## Validation
+
+The NumberEditor automatically validates input based on the configured constraints:
+
+- **Precision**: Limits decimal places to the specified precision
+- **Range**: Enforces min/max boundaries on blur
+- **Negative**: Prevents negative input when `allowNegative` is false
+- **Non-numeric**: Blocks non-numeric characters and full-width characters
+- **Real-time**: Validates during typing and provides immediate feedback
+
+## Best Practices
+
+1. **Use appropriate precision**: Set precision based on your data requirements
+2. **Set meaningful ranges**: Use min/max to prevent invalid values
+3. **Provide clear labels**: Use FormField to wrap NumberEditor with descriptive labels
+4. **Handle change events**: Implement onchange for validation or calculations
+5. **Consider user experience**: Use placeholder text and proper variant styling
+6. **Use prefix/suffix wisely**: Add units or currency symbols for clarity
+7. **Disable when needed**: Use readonly for calculated fields or disabled for unavailable inputs
+
+## Styling
+
+The NumberEditor supports CSS custom properties for styling:
+
+```css
+.number-editor {
+  --number-editor-font-size: 14px;
+  --number-editor-padding: 8px 12px;
+  --number-editor-border-color: #e0e0e0;
+  --number-editor-focus-color: #1976d2;
+}
+```
+
+## Accessibility
+
+- Proper ARIA labels and roles
+- Keyboard navigation support
+- Screen reader compatibility
+- Focus management
+- High contrast mode support
+
+## Related Components
+
+- [TextEditor](../text-editor/README.md) - For text input
+- [FormField](../form-field/README.md) - For form layout and labels
+- [UnitNumberEditor](../unit-number-editor/README.md) - For numbers with unit selection