# Number input

## Overview

_[Design to fill]_

- **When to use**: _[Design to fill]_
- **When not to use**: _[Design to fill]_

## Anatomy

_[Design to fill]_

## Variants

| Prop         | Effect                                               |
| ------------ | ---------------------------------------------------- |
| `isSmall`    | Renders the smaller input with `text-200` sizing.    |
| `hasError`   | Applies the error style to signal invalid input.     |
| `hasWarning` | Applies the warning style to signal a caution state. |

## Props / API

### `NumberInput`

| Prop            | Type                       | Default | Description                                                 |
| --------------- | -------------------------- | ------- | ----------------------------------------------------------- |
| `value`         | `number`                   | -       | Controlled value.                                           |
| `defaultValue`  | `number`                   | -       | Uncontrolled initial value.                                 |
| `onValueChange` | `(value: number) => void`  | -       | Called with the parsed numeric value when it changes.       |
| `min`           | `number`                   | -       | Minimum allowed value.                                      |
| `max`           | `number`                   | -       | Maximum allowed value.                                      |
| `step`          | `number`                   | -       | Increment/decrement step size.                              |
| `format`        | `Intl.NumberFormatOptions` | -       | Number formatting options (currency, unit, decimals, etc.). |
| `hasError`      | `boolean`                  | -       | Applies the error style.                                    |
| `hasWarning`    | `boolean`                  | -       | Applies the warning style.                                  |
| `isSmall`       | `boolean`                  | -       | Renders the smaller size.                                   |
| `className`     | `string`                   | -       | Additional class names merged onto the input element.       |
| `name`          | `string`                   | -       | Form field name.                                            |
| `id`            | `string`                   | -       | Element id, for associating an external `<label>`.          |
| `placeholder`   | `string`                   | -       | Placeholder text shown when empty.                          |
| `required`      | `boolean`                  | -       | Marks the field as required.                                |
| `disabled`      | `boolean`                  | -       | Disables the input.                                         |
| `readOnly`      | `boolean`                  | -       | Renders the input as read-only.                             |

Built on Base UI's `NumberField` (`@base-ui/react/number-field`). Props are explicitly mapped to `NumberField.Root`/`NumberField.Input`; there is no `...rest` spreading of arbitrary HTML attributes.

## States

- Default (idle)
- Hover
- Focus-visible
- Error
- Warning
- Disabled
- Read-only

## Code examples

```tsx
import { useState } from "react";
import { NumberInput } from "@mylighthouse/prism-react";

export default function NumberInputExample(): React.JSX.Element {
  const [amount, setAmount] = useState<number | null>(0);

  return (
    <label>
      Quantity
      <NumberInput
        value={amount}
        onValueChange={setAmount}
        min={0}
        max={100}
        step={1}
      />
    </label>
  );
}
```

## A11y intent

_[Design to fill]_

- Always associate a visible label with the input so its purpose is announced.
- `hasError` / `hasWarning` are visual only, pair them with a programmatically associated message and don't rely on color alone to signal validity.
- The `disabled` input stays in the accessibility tree so its state is announced.