# NumberField

A form control for numeric input with validation and optional spin buttons.

## Usage

Use standalone, or wrap `NumberInput` to share state.

```svelte
<NumberField {...props} />

<NumberField {...props}>
  <NumberInput {...props} />
</NumberField>
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<div class="whole">
  <div class="top" conditional: label or aux>
    <label class="label" conditional>
      {label}
      <span class="extra" conditional>{extra}</span>
    </label>
    <span class="aux" conditional>{aux}</span>
  </div>
  <div class="middle">
    <span class="left" conditional>{left}</span>
    {#if children}{@render children()}{:else}<NumberInput />{/if}
    <span class="right" conditional>{right}</span>
  </div>
  <div class="bottom" conditional: has text, or always when reserve; role="alert only on error">{bottom}</div>
</div>
```

## Props

| Name          | Type                    | Default   | Description                                                                                       |
| ------------- | ----------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `label`       | `string`                | -         | Field label                                                                                       |
| `extra`       | `string`                | -         | Extra text shown with the label                                                                   |
| `aux`         | `Snippet`               | -         | Auxiliary content; receives value, variant, and input element                                     |
| `left`        | `Snippet`               | -         | Content before the control; receives value, variant, and input element                            |
| `right`       | `Snippet`               | -         | Content after the control; receives value, variant, and input element                             |
| `bottom`      | `string`                | -         | Bottom message                                                                                    |
| `reserve`     | `boolean`               | `false`   | Renders the bottom element even without a message to prevent layout shift                         |
| `value`       | `number`                | -         | Bindable field value; undefined means empty                                                       |
| `validations` | `NumberFieldValidation` | -         | Validation functions for input values                                                             |
| `name`        | `string`                | -         | Form submission name                                                                              |
| `element`     | `HTMLInputElement`      | -         | Bindable input element                                                                            |
| `styling`     | `SVSClass`              | -         | Styling override                                                                                  |
| `variant`     | `SVSVariant`            | `NEUTRAL` | Bindable variant                                                                                  |
| `numberInput` | `Omit`                  | -         | Flat props for the default inner `NumberInput`; ignored when `children` provides a custom control |
| `children`    | `Snippet`               | -         | Compound form child control that owns its own props                                               |
## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

In the initial state or when there is no input value, `neutral` is applied. After a value is entered, the variant switches to `active` if validation succeeds, or to `inactive` if validation fails. When validating the form, `inactive` is applied when validation fails. If the `variant` prop is specified, the specified value is applied instead of `neutral`.

### Default Class Name

`svs-number-field`

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Field (`whole` `<div>`): `role="group"` and `aria-labelledby` pointing to the label part when label text is present.
- Message (`bottom`): `role="alert"` when the field is inactive and showing an error message.

Provide `label` text for the field's accessible name; the component wires that label to the group instead of requiring an author-passed `aria-label`. Spinbutton ARIA and keyboard behavior for the default control are documented on [NumberInput](/docs/number-input).

## Exports

### Types

```ts
type NumberFieldValidation = SVSFieldValidation<number | undefined>;
interface NumberFieldProps {
  label?: string;
  extra?: string;
  aux?: Snippet<[number | undefined, string, HTMLInputElement | undefined]>; // Snippet<[value,variant,element]>
  left?: Snippet<[number | undefined, string, HTMLInputElement | undefined]>; // Snippet<[value,variant,element]>
  right?: Snippet<[number | undefined, string, HTMLInputElement | undefined]>; // Snippet<[value,variant,element]>
  bottom?: string;
  reserve?: boolean; // (false)
  value?: number; // bindable; undefined = empty
  validations?: NumberFieldValidation[];
  name?: string;
  element?: HTMLInputElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  numberInput?: Omit<NumberInputProps, NumberInputReqdProps | NumberInputBindProps | "name" | "variant">; // default <NumberInput/> props
  children?: Snippet;
}
type NumberFieldReqdProps = never;
type NumberFieldBindProps = "value" | "variant" | "element";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=NumberFieldBasic.svelte
<script lang="ts">
  import { NumberField } from "svseeds";

  const styling = {
    label: "font-bold",
    middle: "mt-1 w-fit",
    bottom: "mt-1 text-xs",
  };
  const childStyle = {
    whole: "inline-flex items-stretch rounded-sm border",
    main: "w-32 px-2 text-center outline-hidden",
    left: "p-2 size-8 cursor-pointer",
    right: "p-2 size-8 cursor-pointer",
  };

  const myProps = {
    label: "Number Field",
    bottom: "Choose a value from 0 to 100",
    styling,
    numberInput: {
      min: 0,
      max: 100,
      step: 5,
      spin: "split" as const,
      placeholder: "0",
      styling: childStyle,
    },
  };
</script>

<NumberField {...myProps} />
```
### With Interactive Variant

**Code**

```svelte src=NumberFieldPract.svelte
<script lang="ts">
  import { NumberField, NumberInput } from "svseeds";
  import type { NumberFieldValidation } from "svseeds";

  let { variant = $bindable() } = $props();
  const validations: NumberFieldValidation[] = [({ value }) => (value !== undefined && value % 2 !== 0 ? "Must be even" : "")];
  const variantStyle = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const styling = {
    label: {
      base: "flex items-center font-bold",
      inactive: "text-red-500",
    },
    extra: "ps-1 text-sm text-gray-400",
    middle: {
      base: "mt-1 flex w-48 items-center rounded-sm border",
      ...variantStyle,
    },
    right: "flex size-8 items-center justify-center text-sm",
    bottom: {
      base: "mt-1 text-xs",
      inactive: "text-red-500",
    },
  };
  const myProps = {
    label: "Even Score",
    extra: "(0-100)",
    bottom: "Use the spin buttons or type a number",
    validations,
    styling,
  };
  const childStyle = {
    whole: "inline-flex items-stretch",
    main: "w-32 px-2 text-center outline-hidden order-2",
    left: "p-1 w-8 h-4 cursor-pointer",
    right: "p-1 w-8 h-4 cursor-pointer",
    aux: "flex flex-col order-1",
  };
  const childProps = {
    min: 0,
    max: 100,
    step: 2,
    spin: "stack" as const,
    placeholder: "0",
    styling: childStyle,
  };
</script>

<NumberField bind:variant {...myProps}>
  {#snippet right()}
    <span>pts</span>
  {/snippet}
  <NumberInput {...childProps} />
</NumberField>
```