# NumberEditor

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