Add Stepper component (quantity input with buttons)

- JS plugin with bounds, hold-to-repeat, keyboard and character filter
- demo page, docs page and screenshot page

.changeset/stepper.md

@@ -0,0 +1,7 @@
+---
+"@tabler/core": minor
+"@tabler/preview": minor
+"@tabler/docs": minor
+---
+
+Added the `Stepper` component, a `.stepper` quantity input with buttons, bounds, hold-to-repeat and keyboard support.

core/js/src/stepper.ts

@@ -0,0 +1,500 @@
+/**
+ * --------------------------------------------------------------------------
+ * Tabler stepper.ts
+ * Licensed under MIT (https://github.com/tabler/tabler/blob/dev/LICENSE)
+ * --------------------------------------------------------------------------
+ */
+
+import BaseComponent from './bootstrap/base-component'
+import EventHandler from './bootstrap/dom/event-handler'
+import SelectorEngine from './bootstrap/dom/selector-engine'
+import { initAll } from './bootstrap/util/component-functions'
+import { isDisabled } from './bootstrap/util/index'
+import type { ElementSelector } from './bootstrap/types'
+
+type StepperAction = 'increment' | 'decrement'
+
+type ComponentConfig = {
+  /** lower bound; `null` reads the input's `min` attribute, no bound when that is missing too */
+  min: number | null
+  /** upper bound; `null` reads the input's `max` attribute, no bound when that is missing too */
+  max: number | null
+  /** amount added or removed per step; `null` reads the input's `step` attribute, or 1 */
+  step: number | null
+  /** keep stepping while a button is held down */
+  repeat: boolean
+  /** milliseconds a button has to be held before it starts repeating */
+  repeatDelay: number
+  /** milliseconds between two repeated steps */
+  repeatInterval: number
+}
+
+type ComponentConfigInput = Partial<ComponentConfig> & Record<string, unknown>
+
+/**
+ * Constants
+ */
+
+const NAME = 'stepper'
+const DATA_KEY = `bs.${NAME}`
+const EVENT_KEY = `.${DATA_KEY}`
+
+const EVENT_CHANGE = `change${EVENT_KEY}`
+
+const SELECTOR_DATA_TOGGLE = `[data-bs-toggle="${NAME}"], [data-tblr-toggle="${NAME}"]`
+const SELECTOR_INPUT = 'input'
+const SELECTOR_ACTION = `[data-bs-${NAME}-action], [data-tblr-${NAME}-action]`
+
+const ATTRIBUTES_ACTION = [`data-bs-${NAME}-action`, `data-tblr-${NAME}-action`]
+
+const KEY_UP = 'ArrowUp'
+const KEY_DOWN = 'ArrowDown'
+const KEY_HOME = 'Home'
+const KEY_END = 'End'
+
+// A held button stops repeating on any of these, so a drag off the button or
+// a cancelled touch never leaves the timer running.
+const POINTER_END_EVENTS = ['pointerup', 'pointercancel', 'pointerleave']
+
+const Default: ComponentConfig = {
+  min: null,
+  max: null,
+  step: null,
+  repeat: true,
+  repeatDelay: 400,
+  repeatInterval: 80,
+}
+
+const DefaultType: Record<keyof ComponentConfig, string> = {
+  min: '(number|null)',
+  max: '(number|null)',
+  step: '(number|null)',
+  repeat: 'boolean',
+  repeatDelay: 'number',
+  repeatInterval: 'number',
+}
+
+/**
+ * Class definition
+ *
+ * A number field with a decrement and an increment button. The `<input>` stays
+ * the single source of truth: the buttons, the arrow keys and the public API
+ * all write to it, clamp to `min` / `max` and round to the precision of
+ * `step`, so a form sees nothing but an ordinary field.
+ */
+
+class Stepper extends BaseComponent {
+  declare _element: HTMLElement
+  declare _config: ComponentConfig
+  _input: HTMLInputElement | null = null
+  _buttons: HTMLElement[] = []
+  _min = Number.NEGATIVE_INFINITY
+  _max = Number.POSITIVE_INFINITY
+  _step = 1
+  _precision = 0
+  // Characters the field accepts: digits, plus a minus sign and a decimal
+  // separator only when the bounds and the step call for them.
+  _disallowed = /[^0-9]/g
+  _holdTimer: ReturnType<typeof setTimeout> | null = null
+  _repeatTimer: ReturnType<typeof setInterval> | null = null
+  // Set once a held button has stepped on its own, so the `click` that ends
+  // the hold does not add one more step.
+  _held = false
+  // The last value the field held, restored after an edit that is not a number
+  _lastValue = ''
+
+  _onClick = (event: Event): void => this._handleClick(event)
+  _onPointerDown = (event: Event): void => this._handlePointerDown(event)
+  _onPointerEnd = (): void => this._stopRepeat()
+  _onKeyDown = (event: Event): void => this._handleKeyDown(event as KeyboardEvent)
+  _onBeforeInput = (event: Event): void => this._handleBeforeInput(event as InputEvent)
+  _onInputChange = (): void => this._handleInputChange()
+
+  constructor(element: ElementSelector, config?: ComponentConfigInput) {
+    super(element, config)
+
+    if (!this._element) {
+      return
+    }
+
+    const input = SelectorEngine.findOne(SELECTOR_INPUT, this._element) as HTMLInputElement | null
+    if (!input) {
+      return
+    }
+
+    this._input = input
+    this._buttons = SelectorEngine.find(SELECTOR_ACTION, this._element)
+
+    this._resolveBounds()
+    this._setUpInput()
+    this._addEventListeners()
+    this._update()
+  }
+
+  // Getters
+  static get Default(): ComponentConfig {
+    return Default
+  }
+
+  static get DefaultType(): Record<keyof ComponentConfig, string> {
+    return DefaultType
+  }
+
+  static get NAME(): string {
+    return NAME
+  }
+
+  // Public
+  getValue(): number | null {
+    return this._parse(this._input?.value ?? '')
+  }
+
+  setValue(value: number | string): void {
+    const parsed = this._parse(String(value))
+    if (parsed === null) {
+      return
+    }
+
+    this._commit(parsed)
+  }
+
+  increment(): void {
+    this._stepBy(1)
+  }
+
+  decrement(): void {
+    this._stepBy(-1)
+  }
+
+  dispose(): void {
+    this._stopRepeat()
+
+    if (this._input) {
+      this._input.removeEventListener('keydown', this._onKeyDown)
+      this._input.removeEventListener('beforeinput', this._onBeforeInput)
+      this._input.removeEventListener('change', this._onInputChange)
+      this._input.removeEventListener('blur', this._onInputChange)
+    }
+
+    for (const button of this._buttons) {
+      button.removeEventListener('click', this._onClick)
+      button.removeEventListener('pointerdown', this._onPointerDown)
+      for (const type of POINTER_END_EVENTS) {
+        button.removeEventListener(type, this._onPointerEnd)
+      }
+    }
+
+    super.dispose()
+  }
+
+  // Private
+  // Config wins over the input's own attributes; both are optional.
+  _resolveBounds(): void {
+    const input = this._input!
+    const attribute = (name: string): number | null => {
+      const value = Number.parseFloat(input.getAttribute(name) ?? '')
+      return Number.isFinite(value) ? value : null
+    }
+
+    this._min = this._config.min ?? attribute('min') ?? Number.NEGATIVE_INFINITY
+    this._max = this._config.max ?? attribute('max') ?? Number.POSITIVE_INFINITY
+
+    const step = this._config.step ?? attribute('step')
+    this._step = step !== null && step > 0 ? step : 1
+
+    // `0.25` has two decimals: every result is rounded to the same precision,
+    // so repeated steps never drift into `0.30000000000000004`.
+    const decimals = String(this._step).split('.')[1]
+    this._precision = decimals ? decimals.length : 0
+
+    const allowed = `0-9${this._min < 0 ? '-' : ''}${this._precision > 0 ? '.,' : ''}`
+    this._disallowed = new RegExp(`[^${allowed}]`, 'g')
+  }
+
+  _setUpInput(): void {
+    const input = this._input!
+
+    // A text field keeps the native spin buttons away on every platform;
+    // the role tells assistive technology it still behaves like a number.
+    if (input.type !== 'number') {
+      input.setAttribute('role', 'spinbutton')
+      if (!input.hasAttribute('inputmode')) {
+        input.setAttribute('inputmode', this._precision > 0 ? 'decimal' : 'numeric')
+      }
+    }
+
+    const current = this._parse(input.value)
+    if (current !== null) {
+      input.value = this._format(this._clamp(current))
+    }
+
+    this._lastValue = input.value
+  }
+
+  _addEventListeners(): void {
+    const input = this._input!
+
+    input.addEventListener('keydown', this._onKeyDown)
+    input.addEventListener('beforeinput', this._onBeforeInput)
+    // `blur` as well as `change`: a value set by a script before the field is
+    // left fires no `change`, and the clamp must still happen.
+    input.addEventListener('change', this._onInputChange)
+    input.addEventListener('blur', this._onInputChange)
+
+    for (const button of this._buttons) {
+      button.addEventListener('click', this._onClick)
+      button.addEventListener('pointerdown', this._onPointerDown)
+      for (const type of POINTER_END_EVENTS) {
+        button.addEventListener(type, this._onPointerEnd)
+      }
+    }
+  }
+
+  _actionOf(button: HTMLElement): StepperAction | null {
+    for (const name of ATTRIBUTES_ACTION) {
+      const action = button.getAttribute(name)
+      if (action === 'increment' || action === 'decrement') {
+        return action
+      }
+    }
+
+    return null
+  }
+
+  _handleClick(event: Event): void {
+    const button = event.currentTarget as HTMLElement
+    event.preventDefault()
+
+    if (this._held) {
+      this._held = false
+      return
+    }
+
+    this._runAction(this._actionOf(button))
+  }
+
+  _handlePointerDown(event: Event): void {
+    const button = event.currentTarget as HTMLElement
+    const action = this._actionOf(button)
+
+    this._stopRepeat()
+
+    if (!this._config.repeat || !action || isDisabled(button) || this._isLocked()) {
+      return
+    }
+
+    // Keep the focus on the field being edited; the step itself happens on
+    // `click`, which also covers keyboard activation.
+    if ((event as PointerEvent).pointerType === 'mouse') {
+      event.preventDefault()
+    }
+
+    this._holdTimer = setTimeout(() => {
+      this._holdTimer = null
+      this._held = true
+      this._runAction(action)
+      this._repeatTimer = setInterval(() => this._runAction(action), this._config.repeatInterval)
+    }, this._config.repeatDelay)
+  }
+
+  _stopRepeat(): void {
+    if (this._holdTimer !== null) {
+      clearTimeout(this._holdTimer)
+      this._holdTimer = null
+    }
+
+    if (this._repeatTimer !== null) {
+      clearInterval(this._repeatTimer)
+      this._repeatTimer = null
+    }
+  }
+
+  _runAction(action: StepperAction | null): void {
+    if (action === 'increment') {
+      this.increment()
+    } else if (action === 'decrement') {
+      this.decrement()
+    }
+  }
+
+  _handleKeyDown(event: KeyboardEvent): void {
+    const steps: Record<string, () => void> = {
+      [KEY_UP]: () => this.increment(),
+      [KEY_DOWN]: () => this.decrement(),
+      [KEY_HOME]: () => this._commit(this._min),
+      [KEY_END]: () => this._commit(this._max),
+    }
+
+    const handler = steps[event.key]
+    if (!handler) {
+      return
+    }
+
+    if ((event.key === KEY_HOME && !Number.isFinite(this._min)) || (event.key === KEY_END && !Number.isFinite(this._max))) {
+      return
+    }
+
+    event.preventDefault()
+    handler()
+  }
+
+  // Letters never get into the field: a typed one is dropped, a pasted text
+  // keeps only its digits (and the sign or separator when those are allowed).
+  _handleBeforeInput(event: InputEvent): void {
+    const { data, inputType } = event
+    if (!data || !inputType.startsWith('insert')) {
+      return
+    }
+
+    const clean = data.replace(this._disallowed, '')
+    if (clean === data) {
+      return
+    }
+
+    event.preventDefault()
+
+    if (clean === '') {
+      return
+    }
+
+    const input = this._input!
+    const start = input.selectionStart ?? input.value.length
+    const end = input.selectionEnd ?? start
+    input.setRangeText(clean, start, end, 'end')
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+  }
+
+  // A typed value is clamped once the field is left; a value that is not a
+  // number goes back to the previous one. An untouched field is left alone,
+  // so leaving it fires no events.
+  _handleInputChange(): void {
+    const input = this._input!
+    if (input.value === this._lastValue) {
+      return
+    }
+
+    const parsed = this._parse(input.value)
+
+    if (parsed === null) {
+      input.value = this._lastValue
+      this._update()
+      return
+    }
+
+    this._commit(parsed)
+  }
+
+  _stepBy(direction: 1 | -1): void {
+    if (this._isLocked()) {
+      return
+    }
+
+    const current = this.getValue() ?? this._fallbackValue()
+    this._commit(current + direction * this._step)
+  }
+
+  // The value an empty field steps from: the nearest bound, or zero.
+  _fallbackValue(): number {
+    if (Number.isFinite(this._min) && this._min > 0) {
+      return this._min
+    }
+
+    if (Number.isFinite(this._max) && this._max < 0) {
+      return this._max
+    }
+
+    return 0
+  }
+
+  _commit(value: number): void {
+    const input = this._input!
+    const previousValue = this.getValue()
+    const next = this._clamp(value)
+    const formatted = this._format(next)
+
+    const changed = input.value !== formatted
+    input.value = formatted
+    this._lastValue = formatted
+    this._update()
+
+    if (!changed) {
+      return
+    }
+
+    // The field itself fires `input` and `change`, so a form, a framework
+    // binding or validation sees a stepped value like a typed one.
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+    input.dispatchEvent(new Event('change', { bubbles: true }))
+
+    EventHandler.trigger(this._element, EVENT_CHANGE, { value: next, previousValue })
+
+    if (next === this._min || next === this._max) {
+      this._stopRepeat()
+    }
+  }
+
+  _isLocked(): boolean {
+    const input = this._input!
+    return input.disabled || input.readOnly
+  }
+
+  _clamp(value: number): number {
+    return Math.min(this._max, Math.max(this._min, value))
+  }
+
+  _parse(value: string): number | null {
+    const trimmed = value.trim().replace(',', '.')
+    if (trimmed === '') {
+      return null
+    }
+
+    const parsed = Number(trimmed)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+
+  _format(value: number): string {
+    return value.toFixed(this._precision)
+  }
+
+  // Buttons go inert at a bound or while the field is locked, and the
+  // spinbutton role gets its `aria-value*` attributes refreshed.
+  _update(): void {
+    const input = this._input!
+    const value = this.getValue()
+    const locked = this._isLocked()
+
+    for (const button of this._buttons) {
+      const action = this._actionOf(button)
+      const atBound = value !== null && ((action === 'increment' && value >= this._max) || (action === 'decrement' && value <= this._min))
+      ;(button as HTMLButtonElement).disabled = locked || atBound
+    }
+
+    if (input.getAttribute('role') !== 'spinbutton') {
+      return
+    }
+
+    if (Number.isFinite(this._min)) {
+      input.setAttribute('aria-valuemin', this._format(this._min))
+    }
+
+    if (Number.isFinite(this._max)) {
+      input.setAttribute('aria-valuemax', this._format(this._max))
+    }
+
+    if (value === null) {
+      input.removeAttribute('aria-valuenow')
+    } else {
+      input.setAttribute('aria-valuenow', this._format(value))
+    }
+  }
+}
+
+/**
+ * Data API implementation
+ */
+
+// js-docs-start stepper-init
+initAll(SELECTOR_DATA_TOGGLE, Stepper)
+// js-docs-end stepper-init
+
+export default Stepper

core/js/tabler.ts

@@ -15,6 +15,7 @@ import './src/sortable'
 import './src/otp-input'
 import './src/sparkline'
 import './src/strength'
+import './src/stepper'
 
 // Re-export everything from bootstrap.ts (single source of truth)
 export * from './src/bootstrap'
@@ -29,6 +30,7 @@ export { default as InputMask } from './src/input-mask'
 export { default as OtpInput } from './src/otp-input'
 export { default as Sortable } from './src/sortable'
 export { default as Sparkline } from './src/sparkline'
+export { default as Stepper } from './src/stepper'
 export { default as Strength } from './src/strength'
 export { default as SwitchIcon } from './src/switch-icon'
 

core/js/tests/unit/stepper.spec.ts

@@ -0,0 +1,411 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest'
+import { clearFixture, getFixture } from '../helpers/fixture'
+import Stepper from '../../src/stepper'
+
+const markup = (inputAttributes = 'value="1" min="0" max="5"', wrapperAttributes = ''): string =>
+  [
+    `<div class="stepper" data-bs-toggle="stepper" ${wrapperAttributes}>`,
+    '  <button type="button" class="btn" data-bs-stepper-action="decrement">-</button>',
+    `  <input type="text" class="form-control" ${inputAttributes} />`,
+    '  <button type="button" class="btn" data-bs-stepper-action="increment">+</button>',
+    '</div>',
+  ].join('')
+
+describe('Stepper', () => {
+  let fixtureEl: HTMLElement
+
+  beforeAll(() => {
+    fixtureEl = getFixture()
+  })
+
+  beforeEach(() => {
+    fixtureEl.innerHTML = markup()
+  })
+
+  afterEach(() => {
+    clearFixture()
+    vi.useRealTimers()
+  })
+
+  const stepper = (): HTMLElement => fixtureEl.querySelector('.stepper')!
+  const input = (): HTMLInputElement => fixtureEl.querySelector('input')!
+  const decrementButton = (): HTMLButtonElement => fixtureEl.querySelector('[data-bs-stepper-action="decrement"]')!
+  const incrementButton = (): HTMLButtonElement => fixtureEl.querySelector('[data-bs-stepper-action="increment"]')!
+
+  const change = (value: string): void => {
+    input().value = value
+    input().dispatchEvent(new Event('change', { bubbles: true }))
+  }
+
+  const keydown = (key: string): KeyboardEvent => {
+    const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true })
+    input().dispatchEvent(event)
+    return event
+  }
+
+  describe('NAME', () => {
+    it('should return the plugin name', () => {
+      expect(Stepper.NAME).toBe('stepper')
+    })
+  })
+
+  describe('Default', () => {
+    it('should expose the default config', () => {
+      expect(Stepper.Default.min).toBeNull()
+      expect(Stepper.Default.repeat).toBe(true)
+      expect(typeof Stepper.DefaultType.step).toBe('string')
+    })
+  })
+
+  describe('constructor', () => {
+    it('should read the bounds from the input attributes', () => {
+      const instance = new Stepper(stepper())
+      expect(instance._min).toBe(0)
+      expect(instance._max).toBe(5)
+      expect(instance._step).toBe(1)
+    })
+
+    it('should let the config override the input attributes', () => {
+      const instance = new Stepper(stepper(), { min: 2, max: 10, step: 2 })
+      expect(instance._min).toBe(2)
+      expect(instance._max).toBe(10)
+      expect(instance._step).toBe(2)
+      expect(input().value).toBe('2')
+    })
+
+    it('should read the config from data attributes', () => {
+      fixtureEl.innerHTML = markup('value="1"', 'data-bs-min="1" data-bs-max="3" data-bs-step="0.5"')
+      const instance = new Stepper(stepper())
+      expect(instance._min).toBe(1)
+      expect(instance._max).toBe(3)
+      expect(instance._step).toBe(0.5)
+    })
+
+    it('should have no bounds when neither attributes nor config set them', () => {
+      fixtureEl.innerHTML = markup('value="1"')
+      const instance = new Stepper(stepper())
+      expect(instance._min).toBe(Number.NEGATIVE_INFINITY)
+      expect(instance._max).toBe(Number.POSITIVE_INFINITY)
+    })
+
+    it('should fall back to a step of 1 for a zero or negative step', () => {
+      fixtureEl.innerHTML = markup('value="1" step="0"')
+      expect(new Stepper(stepper())._step).toBe(1)
+    })
+
+    it('should clamp the initial value', () => {
+      fixtureEl.innerHTML = markup('value="9" min="0" max="5"')
+      new Stepper(stepper())
+      expect(input().value).toBe('5')
+    })
+
+    it('should give a text input the spinbutton role and a numeric inputmode', () => {
+      new Stepper(stepper())
+      expect(input().getAttribute('role')).toBe('spinbutton')
+      expect(input().getAttribute('inputmode')).toBe('numeric')
+      expect(input().getAttribute('aria-valuemin')).toBe('0')
+      expect(input().getAttribute('aria-valuemax')).toBe('5')
+      expect(input().getAttribute('aria-valuenow')).toBe('1')
+    })
+
+    it('should use the decimal inputmode for a fractional step', () => {
+      fixtureEl.innerHTML = markup('value="1" step="0.25"')
+      new Stepper(stepper())
+      expect(input().getAttribute('inputmode')).toBe('decimal')
+    })
+
+    it('should leave a number input alone', () => {
+      fixtureEl.innerHTML = markup('type="number" value="1" min="0" max="5"').replace('type="text"', '')
+      new Stepper(stepper())
+      expect(input().hasAttribute('role')).toBe(false)
+      expect(input().hasAttribute('aria-valuenow')).toBe(false)
+    })
+
+    it('should do nothing without an input', () => {
+      fixtureEl.innerHTML = '<div class="stepper"></div>'
+      const instance = new Stepper(stepper())
+      expect(instance._input).toBeNull()
+      expect(instance.getValue()).toBeNull()
+    })
+
+    it('should disable the buttons of a disabled input', () => {
+      fixtureEl.innerHTML = markup('value="1" disabled')
+      new Stepper(stepper())
+      expect(decrementButton().disabled).toBe(true)
+      expect(incrementButton().disabled).toBe(true)
+    })
+  })
+
+  describe('buttons', () => {
+    it('should step the value on click', () => {
+      new Stepper(stepper())
+      incrementButton().click()
+      expect(input().value).toBe('2')
+      decrementButton().click()
+      decrementButton().click()
+      expect(input().value).toBe('0')
+    })
+
+    it('should disable the button at a bound', () => {
+      fixtureEl.innerHTML = markup('value="4" min="0" max="5"')
+      new Stepper(stepper())
+      expect(incrementButton().disabled).toBe(false)
+      incrementButton().click()
+      expect(input().value).toBe('5')
+      expect(incrementButton().disabled).toBe(true)
+      expect(decrementButton().disabled).toBe(false)
+    })
+
+    it('should never leave the bounds', () => {
+      const instance = new Stepper(stepper(), { max: 2 })
+      instance.increment()
+      instance.increment()
+      instance.increment()
+      expect(input().value).toBe('2')
+    })
+
+    it('should keep stepping while a button is held', () => {
+      vi.useFakeTimers()
+      new Stepper(stepper(), { max: 100 })
+
+      incrementButton().dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, pointerType: 'mouse' }))
+      vi.advanceTimersByTime(400)
+      expect(input().value).toBe('2')
+      vi.advanceTimersByTime(80 * 3)
+      expect(input().value).toBe('5')
+
+      incrementButton().dispatchEvent(new PointerEvent('pointerup', { bubbles: true }))
+      vi.advanceTimersByTime(1000)
+      expect(input().value).toBe('5')
+
+      // The click that ends the hold is not one more step
+      incrementButton().click()
+      expect(input().value).toBe('5')
+    })
+
+    it('should stop a hold at a bound', () => {
+      vi.useFakeTimers()
+      const instance = new Stepper(stepper(), { max: 3 })
+
+      incrementButton().dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, pointerType: 'mouse' }))
+      vi.advanceTimersByTime(400 + 80 * 5)
+      expect(input().value).toBe('3')
+      expect(instance._repeatTimer).toBeNull()
+    })
+
+    it('should not repeat when the option is off', () => {
+      vi.useFakeTimers()
+      new Stepper(stepper(), { repeat: false, max: 100 })
+
+      incrementButton().dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, pointerType: 'mouse' }))
+      vi.advanceTimersByTime(2000)
+      expect(input().value).toBe('1')
+    })
+  })
+
+  describe('keyboard', () => {
+    it('should step with the arrow keys and jump with Home and End', () => {
+      new Stepper(stepper())
+      expect(keydown('ArrowUp').defaultPrevented).toBe(true)
+      expect(input().value).toBe('2')
+      keydown('ArrowDown')
+      expect(input().value).toBe('1')
+      keydown('End')
+      expect(input().value).toBe('5')
+      keydown('Home')
+      expect(input().value).toBe('0')
+    })
+
+    it('should ignore Home and End without a bound', () => {
+      fixtureEl.innerHTML = markup('value="1"')
+      new Stepper(stepper())
+      expect(keydown('End').defaultPrevented).toBe(false)
+      expect(input().value).toBe('1')
+    })
+
+    it('should leave other keys alone', () => {
+      new Stepper(stepper())
+      expect(keydown('a').defaultPrevented).toBe(false)
+    })
+  })
+
+  describe('typed value', () => {
+    it('should clamp a typed value on change', () => {
+      new Stepper(stepper())
+      change('42')
+      expect(input().value).toBe('5')
+      expect(incrementButton().disabled).toBe(true)
+    })
+
+    it('should clamp on blur as well', () => {
+      new Stepper(stepper())
+      input().value = '125'
+      input().dispatchEvent(new Event('blur'))
+      expect(input().value).toBe('5')
+    })
+
+    it('should fire nothing when an untouched field is left', () => {
+      new Stepper(stepper())
+      const spy = vi.fn()
+      input().addEventListener('change', spy)
+      input().dispatchEvent(new Event('blur'))
+      expect(spy).not.toHaveBeenCalled()
+    })
+
+    it('should restore the previous value after a non-numeric edit', () => {
+      new Stepper(stepper())
+      change('3')
+      change('abc')
+      expect(input().value).toBe('3')
+    })
+
+    it('should accept a decimal comma', () => {
+      fixtureEl.innerHTML = markup('value="1" step="0.5"')
+      new Stepper(stepper())
+      change('2,5')
+      expect(input().value).toBe('2.5')
+    })
+  })
+
+  describe('character filter', () => {
+    const beforeInput = (data: string, inputType = 'insertText'): InputEvent => {
+      const event = new InputEvent('beforeinput', { data, inputType, bubbles: true, cancelable: true })
+      input().dispatchEvent(event)
+      return event
+    }
+
+    it('should drop a typed letter and keep a digit', () => {
+      new Stepper(stepper())
+      expect(beforeInput('a').defaultPrevented).toBe(true)
+      expect(beforeInput('7').defaultPrevented).toBe(false)
+      expect(beforeInput('.').defaultPrevented).toBe(true)
+      expect(beforeInput('-').defaultPrevented).toBe(true)
+    })
+
+    it('should allow the sign and the separator when the bounds and step need them', () => {
+      fixtureEl.innerHTML = markup('value="0" min="-5" step="0.5"')
+      new Stepper(stepper())
+      expect(beforeInput('-').defaultPrevented).toBe(false)
+      expect(beforeInput('.').defaultPrevented).toBe(false)
+      expect(beforeInput(',').defaultPrevented).toBe(false)
+      expect(beforeInput('e').defaultPrevented).toBe(true)
+    })
+
+    it('should keep only the digits of a pasted text', () => {
+      new Stepper(stepper())
+      input().value = ''
+      input().setSelectionRange(0, 0)
+      expect(beforeInput('4 pcs', 'insertFromPaste').defaultPrevented).toBe(true)
+      expect(input().value).toBe('4')
+    })
+
+    it('should leave deletions alone', () => {
+      new Stepper(stepper())
+      expect(beforeInput('', 'deleteContentBackward').defaultPrevented).toBe(false)
+    })
+  })
+
+  describe('precision', () => {
+    it('should round to the precision of the step', () => {
+      fixtureEl.innerHTML = markup('value="0.1" step="0.1"')
+      const instance = new Stepper(stepper())
+      instance.increment()
+      instance.increment()
+      expect(input().value).toBe('0.3')
+      expect(instance.getValue()).toBe(0.3)
+    })
+
+    it('should step an empty field from the lower bound', () => {
+      fixtureEl.innerHTML = markup('value="" min="2" max="9"')
+      const instance = new Stepper(stepper())
+      expect(instance.getValue()).toBeNull()
+      expect(input().hasAttribute('aria-valuenow')).toBe(false)
+      instance.increment()
+      expect(input().value).toBe('3')
+    })
+  })
+
+  describe('events', () => {
+    it('should fire change.bs.stepper with the values', () => {
+      const instance = new Stepper(stepper())
+      const spy = vi.fn()
+      stepper().addEventListener('change.bs.stepper', spy)
+
+      instance.increment()
+      expect(spy).toHaveBeenCalledTimes(1)
+      const event = spy.mock.calls[0][0] as Event & { value: number; previousValue: number }
+      expect(event.value).toBe(2)
+      expect(event.previousValue).toBe(1)
+    })
+
+    it('should fire input and change on the field', () => {
+      const instance = new Stepper(stepper())
+      const onInput = vi.fn()
+      const onChange = vi.fn()
+      input().addEventListener('input', onInput)
+      input().addEventListener('change', onChange)
+
+      instance.increment()
+      expect(onInput).toHaveBeenCalledTimes(1)
+      expect(onChange).toHaveBeenCalledTimes(1)
+    })
+
+    it('should not fire when the value does not change', () => {
+      const instance = new Stepper(stepper())
+      const spy = vi.fn()
+      stepper().addEventListener('change.bs.stepper', spy)
+
+      instance.setValue(1)
+      instance.decrement()
+      instance.decrement()
+      expect(spy).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('setValue', () => {
+    it('should set and clamp the value', () => {
+      const instance = new Stepper(stepper())
+      instance.setValue(3)
+      expect(input().value).toBe('3')
+      instance.setValue('99')
+      expect(input().value).toBe('5')
+      instance.setValue('nope')
+      expect(input().value).toBe('5')
+    })
+  })
+
+  describe('disabled', () => {
+    it('should not step a disabled or readonly input', () => {
+      fixtureEl.innerHTML = markup('value="1" readonly')
+      const instance = new Stepper(stepper())
+      instance.increment()
+      expect(input().value).toBe('1')
+      expect(incrementButton().disabled).toBe(true)
+    })
+  })
+
+  describe('dispose', () => {
+    it('should remove the listeners and the instance', () => {
+      const instance = new Stepper(stepper())
+      instance.dispose()
+      incrementButton().click()
+      expect(input().value).toBe('1')
+      expect(Stepper.getInstance(stepper())).toBeNull()
+    })
+  })
+
+  describe('data-api', () => {
+    it('should initialise on getOrCreateInstance', () => {
+      const instance = Stepper.getOrCreateInstance(stepper())
+      expect(instance).toBeInstanceOf(Stepper)
+      expect(Stepper.getOrCreateInstance(stepper())).toBe(instance)
+    })
+
+    it('should accept the data-tblr-* action attributes', () => {
+      fixtureEl.innerHTML = markup().replaceAll('data-bs-stepper-action', 'data-tblr-stepper-action')
+      new Stepper(stepper())
+      fixtureEl.querySelector<HTMLButtonElement>('[data-tblr-stepper-action="increment"]')!.click()
+      expect(input().value).toBe('2')
+    })
+  })
+})

core/scss/_core.scss

@@ -69,6 +69,7 @@
 @forward 'ui/forms/form-custom';
 @forward 'ui/forms/form-check';
 @forward 'ui/forms/form-otp';
+@forward 'ui/forms/form-stepper';
 @forward 'ui/forms/validation';
 @forward 'ui/forms/strength';
 @forward 'ui/legend';

core/scss/_variables.scss

@@ -1207,6 +1207,14 @@ $otp-slot-box-shadow: var(--shadow-input) !default;
 $otp-separator-color: var(--secondary) !default;
 // scss-docs-end otp-variables
 
+// Stepper
+// scss-docs-start stepper-variables
+$stepper-input-width: 3.5rem !default;
+$stepper-bg: $input-bg !default;
+$stepper-border-color: var(--border-color) !default;
+$stepper-border-radius: $input-border-radius !default;
+// scss-docs-end stepper-variables
+
 // Cards
 // scss-docs-start card-variables
 $card-spacer-y: 1.25rem !default;

core/scss/ui/forms/_form-stepper.scss

@@ -0,0 +1,113 @@
+/*
+Stepper (number input with buttons)
+ */
+@use 'sass:map';
+@use '../../config' as *;
+
+// One bordered box, like a `.form-control`: the field in the middle and the
+// two buttons inside it have no border of their own.
+.stepper {
+  // scss-docs-start stepper-css-vars
+  --stepper-input-width: #{$stepper-input-width};
+  --stepper-bg: #{$stepper-bg};
+  --stepper-border-color: #{$stepper-border-color};
+  --stepper-border-radius: #{$stepper-border-radius};
+  // scss-docs-end stepper-css-vars
+  position: relative;
+  display: inline-flex;
+  align-items: stretch;
+  vertical-align: middle;
+  background-color: var(--stepper-bg);
+  border: $input-border-width solid var(--stepper-border-color);
+  box-shadow: $input-box-shadow;
+  @include border-radius(var(--stepper-border-radius));
+  @include focus-ring-transition(border-color);
+
+  // The box carries the focus ring for the field inside it.
+  &:focus-within {
+    --focus-ring-offset: -1px;
+    border-color: $input-focus-border-color;
+    @include focus-ring(true);
+  }
+
+  &:has(> .form-control:disabled) {
+    background-color: $input-disabled-bg;
+  }
+
+  > .form-control {
+    // stylelint-disable-next-line length-zero-no-unit
+    --control-border-width: 0px;
+    flex: 0 0 auto;
+    width: var(--stepper-input-width);
+    min-width: 0;
+    padding-inline: 0.25rem;
+    text-align: center;
+    appearance: textfield;
+    background-color: transparent;
+    border: 0;
+    border-radius: 0;
+    box-shadow: none;
+
+    // A `type="number"` field keeps its keyboard behaviour but loses the
+    // native spin buttons, which the stepper's own buttons replace.
+    &::-webkit-inner-spin-button,
+    &::-webkit-outer-spin-button {
+      margin: 0;
+      appearance: none;
+    }
+
+    &:focus {
+      background-color: transparent;
+      outline: 0;
+      box-shadow: none;
+    }
+
+    // The field is too narrow for the validation icon, which would sit on
+    // top of the number; the box border alone carries the state.
+    // `!important` because forms/_validation.scss forces the icon padding
+    // with one.
+    @each $state, $data in $form-validation-states {
+      &.is-#{$state},
+      .was-validated &:#{$state} {
+        padding-inline-end: 0.25rem !important;
+        background-image: none;
+      }
+    }
+  }
+
+  > .btn {
+    // With a unit, or `calc()` in the button's `min-width` has nothing to add
+    // stylelint-disable-next-line length-zero-no-unit
+    --btn-border-width: 0px;
+    --btn-bg: transparent;
+    --btn-border-color: transparent;
+    --btn-hover-border-color: transparent;
+    --btn-active-border-color: transparent;
+    --btn-hover-bg: var(--hover-bg);
+    --btn-box-shadow: none;
+    --focus-ring-offset: -2px;
+    // A held button must not select text or open the context menu on touch.
+    touch-action: manipulation;
+    user-select: none;
+    border-radius: 0;
+
+    &:first-child {
+      @include border-start-radius(calc(var(--stepper-border-radius) - #{$input-border-width}));
+    }
+
+    &:last-child {
+      @include border-end-radius(calc(var(--stepper-border-radius) - #{$input-border-width}));
+    }
+  }
+
+  @each $state, $data in $form-validation-states {
+    &:has(> .form-control.is-#{$state}),
+    .was-validated &:has(> .form-control:#{$state}) {
+      border-color: map.get($data, 'border-color');
+
+      &:focus-within {
+        outline-color: map.get($data, 'focus-ring-color');
+      }
+    }
+  }
+}

docs/content/ui/forms/stepper.mdx

@@ -0,0 +1,180 @@
+---
+title: Stepper
+seoTitle: Stepper (quantity input)
+order: 14
+summary: A number field with a decrease and an increase button, for a quantity in a cart, a number of seats or any value changed in fixed steps.
+description: Add a stepper input with min, max and step, hold-to-repeat buttons, arrow key support and change events.
+related: [/ui/forms/elements, /ui/forms/validation]
+source: core/scss/ui/forms/_form-stepper.scss
+css-vars: stepper
+classnames:
+  component:
+    - class: stepper
+      desc: Wrapper; holds the two buttons and the input
+---
+
+import Example from '@components/Example.astro'
+import CodeDocs from '@components/CodeDocs.astro'
+
+## Overview
+
+A stepper is an ordinary `<input>` between two buttons. The input stays the only field a form sees: the buttons, the arrow keys and the JavaScript API all write to it, keep the value between `min` and `max` and round it to the precision of `step`.
+
+Add `data-bs-toggle="stepper"` to a `.stepper` wrapper, mark the buttons with `data-bs-stepper-action="decrement"` and `"increment"`, and Tabler wires them up. The bounds come from the input's own `min`, `max` and `step` attributes.
+
+<Example column>
+  <div class="stepper" data-bs-toggle="stepper">
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="decrement" aria-label="Decrease">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+    <input type="text" class="form-control" value="1" min="1" max="99" aria-label="Quantity" />
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="increment" aria-label="Increase">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M12 5l0 14" />
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+  </div>
+</Example>
+
+## Usage
+
+### Bounds and step
+
+The button at a bound goes disabled, so the user sees when the value cannot go further. Letters never get into the field: a typed one is dropped and a pasted text keeps only its digits, with a minus sign allowed only when `min` is negative and a decimal separator only for a fractional `step`. A typed value is clamped once the field is left. A fractional `step` sets the precision: with `step="0.25"` the value is always shown with two decimals.
+
+<Example column>
+  <div class="stepper" data-bs-toggle="stepper">
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="decrement" aria-label="Decrease">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+    <input type="text" class="form-control" value="1.5" min="0" max="10" step="0.25" aria-label="Hours" />
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="increment" aria-label="Increase">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M12 5l0 14" />
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+  </div>
+</Example>
+
+Without `min` and `max` the value has no bounds. An empty field steps from `min` when that is positive, otherwise from zero.
+
+### Text or number input
+
+A `type="text"` input gets `role="spinbutton"`, the matching `aria-value*` attributes and a numeric `inputmode`, so a phone shows the number keyboard and the native spin buttons never appear. A `type="number"` input keeps the browser's own validation and keyboard behaviour; the stepper only hides its spin buttons.
+
+<Example column>
+  <div class="stepper" data-bs-toggle="stepper">
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="decrement" aria-label="Decrease">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+    <input type="number" class="form-control" value="5" min="0" max="10" aria-label="Seats" />
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="increment" aria-label="Increase">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M12 5l0 14" />
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+  </div>
+</Example>
+
+### Keyboard
+
+With the focus in the field, <kbd>↑</kbd> and <kbd>↓</kbd> step the value, <kbd>Home</kbd> and <kbd>End</kbd> jump to `min` and `max`. Holding a button down keeps stepping after a short delay; set `data-bs-repeat="false"` to turn that off.
+
+### Wider input
+
+The input is `3.5rem` wide by default, enough for a quantity. Set `--tblr-stepper-input-width` on the wrapper for longer values.
+
+<Example column>
+  <div class="stepper" data-bs-toggle="stepper" style="--tblr-stepper-input-width: 6rem">
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="decrement" aria-label="Decrease">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+    <input type="text" class="form-control" value="1000" min="0" step="100" aria-label="Amount" />
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="increment" aria-label="Increase">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M12 5l0 14" />
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+  </div>
+</Example>
+
+### Disabled
+
+Add `disabled` or `readonly` to the input; both buttons follow.
+
+<Example column>
+  <div class="stepper" data-bs-toggle="stepper">
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="decrement" aria-label="Decrease">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+    <input type="text" class="form-control" value="3" disabled aria-label="Quantity" />
+    <button type="button" class="btn btn-icon" data-bs-stepper-action="increment" aria-label="Increase">
+      <svg xmlns="http://www.w3.org/2000/svg" class="icon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M12 5l0 14" />
+        <path d="M5 12l14 0" />
+      </svg>
+    </button>
+  </div>
+</Example>
+
+### Validation
+
+Add `.is-valid` or `.is-invalid` to the input, the same way you would on any `.form-control`. The field is too narrow for the validation icon, so only the border changes colour.
+
+## Options
+
+Options are read from `data-bs-*` attributes on the `.stepper` element (the `data-tblr-*` alias also works), or passed to the constructor. An option set this way wins over the input's attribute.
+
+| Option           | Type           | Default | Description                                                                                          |
+| ---------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `min`            | number or null | `null`  | Lower bound. When `null`, the input's `min` attribute is used; without that there is no lower bound. |
+| `max`            | number or null | `null`  | Upper bound. When `null`, the input's `max` attribute is used; without that there is no upper bound. |
+| `step`           | number or null | `null`  | Amount per step. When `null`, the input's `step` attribute is used, or `1`.                          |
+| `repeat`         | boolean        | `true`  | Keeps stepping while a button is held down.                                                          |
+| `repeatDelay`    | number         | `400`   | Milliseconds a button has to be held before it starts repeating.                                     |
+| `repeatInterval` | number         | `80`    | Milliseconds between two repeated steps.                                                             |
+
+## JavaScript
+
+Tabler creates a `Stepper` for every element matching `[data-bs-toggle="stepper"]` (or `[data-tblr-toggle="stepper"]`):
+
+<CodeDocs name="stepper-init" file="core/js/src/stepper.ts" />
+
+Create one manually, or get an existing instance:
+
+```javascript
+const el = document.querySelector('.stepper')
+const stepper = tabler.Stepper.getOrCreateInstance(el, { min: 1, max: 10 })
+```
+
+The input itself fires the usual `input` and `change` events whenever a button or the API changes it, so a form, a framework binding or validation sees a stepped value like a typed one. On top of that, `change.bs.stepper` fires on the wrapper with both values:
+
+```javascript
+el.addEventListener('change.bs.stepper', (event) => {
+  console.log(event.value, event.previousValue)
+})
+```
+
+### Methods
+
+| Method            | Description                                                              |
+| ----------------- | ------------------------------------------------------------------------ |
+| `getValue()`      | Returns the current value as a number, or `null` for an empty field.     |
+| `setValue(value)` | Sets the value, clamped to the bounds and rounded to the step precision. |
+| `increment()`     | Adds one step.                                                           |
+| `decrement()`     | Removes one step.                                                        |
+| `dispose()`       | Removes the listeners and the instance.                                  |

preview/pages/form-elements.astro

@@ -11,6 +11,7 @@ import Layout from '@shared/components/cards/form/Layout.astro'
 import InputIcon from '@ui/form/InputIcon.astro'
 import InputMask from '@ui/form/InputMask.astro'
 import OtpInput from '@ui/OtpInput.astro'
+import Stepper from '@ui/Stepper.astro'
 import Button from '@ui/Button.astro'
 import Avatar from '@ui/Avatar.astro'
 import Card from '@ui/Card.astro'
@@ -158,6 +159,18 @@ const rows = [
             </CardBody>
           </Card>
         </div>
+        <div class="col-12 col-lg-6">
+          <Card>
+            <CardHeader title="Stepper" />
+            <CardBody>
+              <FormGroup label="Quantity" for="stepper-basic"><Stepper id="stepper-basic" value={1} min={1} max={99} /></FormGroup>
+              <FormGroup label="Step of 0.25" for="stepper-decimal"><Stepper id="stepper-decimal" value={1.5} min={0} max={10} step={0.25} /></FormGroup>
+              <FormGroup label="Without bounds" for="stepper-unbounded"><Stepper id="stepper-unbounded" value={0} /></FormGroup>
+              <FormGroup label="Native number input" for="stepper-number"><Stepper id="stepper-number" type="number" value={5} min={0} max={10} /></FormGroup>
+              <FormGroup label="Disabled" for="stepper-disabled"><Stepper id="stepper-disabled" value={3} disabled /></FormGroup>
+            </CardBody>
+          </Card>
+        </div>
         <div class="col-12 col-lg-6">
           <Card as="form" class="h-100">
             <CardHeader title="My Profile" />

preview/pages/stepper.astro

@@ -0,0 +1,175 @@
+---
+import DefaultLayout from '@shared/layouts/DefaultLayout.astro'
+import Card from '@ui/Card.astro'
+import CardBody from '@ui/CardBody.astro'
+import CardTitle from '@ui/CardTitle.astro'
+import CardSubtitle from '@ui/CardSubtitle.astro'
+import DocsLink from '@ui/DocsLink.astro'
+import FormGroup from '@ui/FormGroup.astro'
+import Stepper from '@ui/Stepper.astro'
+import Icon from '@ui/Icon.astro'
+
+const cart = [
+  { name: 'Hex nut M8 DIN 934, zinc plated', code: '8-934-8-ZN', price: '12.40', quantity: 2, max: 50 },
+  { name: 'Lock nut M8 DIN 985, stainless A2', code: '8-985-A2', price: '28.90', quantity: 1, max: 20 },
+  { name: 'Cap nut M8 DIN 1587, brass', code: '8-1587-MS', price: '41.00', quantity: 3, max: 3 },
+]
+---
+
+<DefaultLayout title="Stepper" pageMenu="base.stepper" description="A stepper is a number field with a decrease and an increase button, for a quantity or any value changed in fixed steps.">
+  <DocsLink slot="page-header-actions" path="/ui/forms/stepper" />
+
+  <div class="row row-cards">
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>Basic</CardTitle>
+          <CardSubtitle>Add <code>data-bs-toggle="stepper"</code> to a <code>.stepper</code> wrapper; the input's <code>min</code> and <code>max</code> set the bounds.</CardSubtitle>
+          <Stepper value={1} min={1} max={99} ariaLabel="Quantity" />
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>At a bound</CardTitle>
+          <CardSubtitle>The button at <code>min</code> or <code>max</code> goes disabled, so the user sees the value cannot go further.</CardSubtitle>
+          <div class="d-flex flex-wrap gap-3">
+            <Stepper value={0} min={0} max={10} ariaLabel="At the minimum" />
+            <Stepper value={10} min={0} max={10} ariaLabel="At the maximum" />
+          </div>
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>Step and precision</CardTitle>
+          <CardSubtitle>A fractional <code>step</code> sets how many decimals the value keeps.</CardSubtitle>
+          <div class="d-flex flex-wrap gap-3">
+            <Stepper value={1.5} min={0} max={10} step={0.25} ariaLabel="Hours" />
+            <Stepper value={500} min={0} step={100} ariaLabel="Amount" style="--tblr-stepper-input-width: 5rem" />
+          </div>
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>Without bounds</CardTitle>
+          <CardSubtitle>Without <code>min</code> and <code>max</code> the value goes both ways, so a minus sign can be typed too.</CardSubtitle>
+          <Stepper value={0} ariaLabel="Offset" />
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>Native number input</CardTitle>
+          <CardSubtitle>Use <code>type="number"</code> to keep the browser's own validation; the stepper only hides its spin buttons.</CardSubtitle>
+          <Stepper type="number" value={5} min={0} max={10} ariaLabel="Seats" />
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>No repeat</CardTitle>
+          <CardSubtitle>Add <code>data-bs-repeat="false"</code> to step once per click instead of repeating while the button is held.</CardSubtitle>
+          <Stepper value={1} min={1} max={99} repeat={false} ariaLabel="Quantity, one step per click" />
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>Wider input</CardTitle>
+          <CardSubtitle>Set <code>--tblr-stepper-input-width</code> on the wrapper for longer values.</CardSubtitle>
+          <Stepper value={125000} min={0} step={1000} ariaLabel="Budget" style="--tblr-stepper-input-width: 7rem" />
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>Disabled and readonly</CardTitle>
+          <CardSubtitle>Add <code>disabled</code> or <code>readonly</code> to the input; both buttons follow.</CardSubtitle>
+          <div class="d-flex flex-wrap gap-3">
+            <Stepper value={3} disabled ariaLabel="Disabled" />
+            <Stepper value={3} readonly ariaLabel="Readonly" />
+          </div>
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>Validation</CardTitle>
+          <CardSubtitle>Add <code>.is-valid</code> or <code>.is-invalid</code> to the input, like on any <code>.form-control</code>.</CardSubtitle>
+          <div class="d-flex flex-wrap gap-3">
+            <div class="stepper" data-bs-toggle="stepper">
+              <button type="button" class="btn btn-icon" data-bs-stepper-action="decrement" aria-label="Decrease"><Icon name="minus" /></button>
+              <input type="text" class="form-control is-valid" value="2" min="1" max="5" aria-label="Valid quantity" />
+              <button type="button" class="btn btn-icon" data-bs-stepper-action="increment" aria-label="Increase"><Icon name="plus" /></button>
+            </div>
+            <div class="stepper" data-bs-toggle="stepper">
+              <button type="button" class="btn btn-icon" data-bs-stepper-action="decrement" aria-label="Decrease"><Icon name="minus" /></button>
+              <input type="text" class="form-control is-invalid" value="5" min="1" max="5" aria-label="Invalid quantity" />
+              <button type="button" class="btn btn-icon" data-bs-stepper-action="increment" aria-label="Increase"><Icon name="plus" /></button>
+            </div>
+          </div>
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-6 col-lg-4">
+      <Card>
+        <CardBody>
+          <CardTitle>With a label and hint</CardTitle>
+          <CardSubtitle>A stepper sits in a <code>FormGroup</code> like any other control.</CardSubtitle>
+          <FormGroup label="Number of seats" for="stepper-seats" hint="Up to 8 seats per booking."><Stepper id="stepper-seats" name="seats" value={2} min={1} max={8} /></FormGroup>
+        </CardBody>
+      </Card>
+    </div>
+    <div class="col-md-12 col-lg-8">
+      <Card>
+        <CardBody>
+          <CardTitle>In a cart</CardTitle>
+          <CardSubtitle>The usual place for a stepper: a quantity per line, with <code>max</code> set to the stock.</CardSubtitle>
+          <div class="table-responsive">
+            <table class="table table-vcenter card-table">
+              <thead>
+                <tr>
+                  <th>Product</th>
+                  <th>Price</th>
+                  <th>Quantity</th>
+                  <th class="w-1"></th>
+                </tr>
+              </thead>
+              <tbody>
+                {
+                  cart.map((item) => (
+                    <tr>
+                      <td>
+                        <div>{item.name}</div>
+                        <div class="text-secondary">{item.code}</div>
+                      </td>
+                      <td class="text-nowrap">${item.price}</td>
+                      <td>
+                        <Stepper value={item.quantity} min={1} max={item.max} ariaLabel={`Quantity of ${item.name}`} />
+                      </td>
+                      <td>
+                        <button type="button" class="btn btn-icon btn-ghost-secondary" aria-label={`Remove ${item.name}`}>
+                          <Icon name="trash" />
+                        </button>
+                      </td>
+                    </tr>
+                  ))
+                }
+              </tbody>
+            </table>
+          </div>
+        </CardBody>
+      </Card>
+    </div>
+  </div>
+</DefaultLayout>

screenshots/pages/stepper.astro

@@ -0,0 +1,15 @@
+---
+// Stepper on its own: a quantity field between its two buttons, with the
+// cursor resting on the increase button. The value sits below the maximum, so
+// both buttons stay enabled and the picture shows the control in its normal
+// state rather than at a bound.
+import ScreenshotLayout from '../layouts/ScreenshotLayout.astro'
+import Stepper from '@ui/Stepper.astro'
+---
+
+<ScreenshotLayout title="Stepper" zoom={2} class="text-center">
+  <div class="d-inline-block position-relative">
+    <Stepper value={3} min={1} max={99} ariaLabel="Quantity" />
+    <span class="cursor" style="left: auto; right: 6px; top: 22px"></span>
+  </div>
+</ScreenshotLayout>

shared/data/docs.json

@@ -400,6 +400,10 @@
 							"title": "OTP input",
 							"url": "/ui/forms/otp-input"
 						},
+						{
+							"title": "Stepper",
+							"url": "/ui/forms/stepper"
+						},
 						{
 							"title": "CSS variables",
 							"url": "/ui/forms/css-variables"

shared/data/menu.json

@@ -256,6 +256,11 @@
         "url": "steps.html",
         "title": "Steps"
       },
+      "stepper": {
+        "url": "stepper.html",
+        "title": "Stepper",
+        "badge": "New"
+      },
       "tables": {
         "url": "tables.html",
         "title": "Tables"

shared/ui/Stepper.astro

@@ -0,0 +1,39 @@
+---
+// Stepper initializes from `data-bs-toggle="stepper"` and its `data-bs-*` options (tabler.js, core/js/src/stepper.ts).
+import Icon from '@ui/Icon.astro'
+
+interface Props {
+  /** data-bs-min: lower bound; defaults to the input's `min` attribute */
+  min?: number
+  /** data-bs-max: upper bound; defaults to the input's `max` attribute */
+  max?: number
+  /** data-bs-step: amount per step; defaults to the input's `step` attribute, or 1 */
+  step?: number
+  /** data-bs-repeat: keep stepping while a button is held (default: true) */
+  repeat?: boolean
+  value?: number | string
+  /** `text` keeps the native spin buttons away; `number` keeps the browser's own validation */
+  type?: 'text' | 'number'
+  ariaLabel?: string
+  id?: string
+  name?: string
+  disabled?: boolean
+  readonly?: boolean
+  /** labels of the two buttons, for screen readers */
+  decrementLabel?: string
+  incrementLabel?: string
+  class?: string
+  /** remaining attributes (data-*, …) are forwarded to the `.stepper` wrapper */
+  [key: string]: unknown
+}
+
+const { min, max, step, repeat, value, type = 'text', ariaLabel, id, name, disabled, readonly, decrementLabel = 'Decrease', incrementLabel = 'Increase', class: className, ...rest } = Astro.props
+
+const wrapperClass = ['stepper', className]
+---
+
+<div class:list={wrapperClass} data-bs-toggle="stepper" data-bs-repeat={repeat === false ? 'false' : undefined} {...rest}>
+  <button type="button" class="btn btn-icon" data-bs-stepper-action="decrement" aria-label={decrementLabel}><Icon name="minus" /></button>
+  <input type={type} class="form-control" id={id} name={name} value={value} min={min} max={max} step={step} disabled={disabled} readonly={readonly} aria-label={ariaLabel} />
+  <button type="button" class="btn btn-icon" data-bs-stepper-action="increment" aria-label={incrementLabel}><Icon name="plus" /></button>
+</div>