# stepper

> Press-and-hold repeat for a NumberField group's increment/decrement buttons, calling the field's native `stepUp()`/`stepDown()` on an interval for as long as a button stays pressed.

```ts
import { stepper } from "@sdxc/ui/mixins";
```

Adds press-and-hold repeat to a NumberField group's Invoker-Command
increment/decrement buttons. The trailing click after a hold-repeat
gesture is absorbed so it doesn't add one extra step atop the repeat.

## Signature

```ts
stepper(options?: StepperOptions): MixinDescriptor<HTMLElement>
```

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `options?` | `StepperOptions` | Hold-to-repeat timing overrides. |

## Examples

```tsx
<div role="group" mix={[stepper()]}>
	<button type="button" command={NUMBER_FIELD_STEP_DOWN_COMMAND} commandfor="quantity" aria-label={decrementLabel}>
		<MinusIcon />
	</button>
	<input id="quantity" type="number" min={0} max={99} defaultValue={1} />
	<button type="button" command={NUMBER_FIELD_STEP_UP_COMMAND} commandfor="quantity" aria-label={incrementLabel}>
		<PlusIcon />
	</button>
</div>
```

## Used with it

The events, constants and types its module publishes, each imported from `@sdxc/ui/mixins` too.

### NumberFieldStepEvent

Dispatched on the number input immediately after `stepper()` applies a
step, carrying the direction and freshly stepped value so a consumer can
react without diffing `input`/`change` events against the prior value.

#### Signature

```ts
new NumberFieldStepEvent(direction: NumberFieldStepDirection, value: number)
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `direction` | `"increment" \| "decrement"` | Which direction the value just moved. |
| `value` | `readonly number` | The input's `valueAsNumber` immediately after the step. |

### NUMBER_FIELD_STEP_UP_COMMAND

Custom Invoker Command an increment button declares (`command="--step-up"`
`commandfor` pointing at the group's number input), read back by
`stepper()` to call `stepUp()` on the matching input.

#### Signature

```ts
const NUMBER_FIELD_STEP_UP_COMMAND = "--step-up"
```

### NUMBER_FIELD_STEP_DOWN_COMMAND

Custom Invoker Command a decrement button declares (`command="--step-down"`
`commandfor` pointing at the group's number input), read back by
`stepper()` to call `stepDown()` on the matching input.

#### Signature

```ts
const NUMBER_FIELD_STEP_DOWN_COMMAND = "--step-down"
```

### NUMBER_FIELD_STEP_EVENT

Event type `stepper()` dispatches on the number input after every
completed step, whether triggered by a single activation or by one tick of
hold-to-repeat.

#### Signature

```ts
const NUMBER_FIELD_STEP_EVENT = "ui:number-field-step" as const
```

### StepperOptions

Options accepted by stepper to tune its hold-to-repeat timing.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `holdDelayMs?` | `number` | Milliseconds a step button must stay pressed before hold-repeat begins. Defaults to DEFAULT_HOLD_DELAY_MS. |
| `holdIntervalMs?` | `number` | Milliseconds between repeated steps once hold-repeat has begun. Defaults to DEFAULT_HOLD_INTERVAL_MS. |

### NumberFieldStepDirection

Direction a single step moves a NumberField's value: `"increment"` raises
it, `"decrement"` lowers it.

#### Signature

```ts
type NumberFieldStepDirection = "increment" | "decrement"
```

One of `"increment"`, `"decrement"`.