Spinbutton

---
/**
 * APG Spinbutton Pattern - Astro Implementation
 *
 * A control that allows users to select a value from a discrete set or range.
 * Uses Web Components for interactive behavior.
 *
 * @see https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/
 */

export interface Props {
  /** Default value */
  defaultValue?: number;
  /** Minimum value (undefined = no limit) */
  min?: number;
  /** Maximum value (undefined = no limit) */
  max?: number;
  /** Step increment (default: 1) */
  step?: number;
  /** Large step for PageUp/PageDown */
  largeStep?: number;
  /** Whether spinbutton is disabled */
  disabled?: boolean;
  /** Whether spinbutton is read-only */
  readOnly?: boolean;
  /** Show increment/decrement buttons (default: true) */
  showButtons?: boolean;
  /** Visible label text */
  label?: string;
  /** Human-readable value text for aria-valuetext */
  valueText?: string;
  /** Format pattern for dynamic value display (e.g., "{value} items") */
  format?: string;
  /** Spinbutton id */
  id?: string;
  /** Additional CSS class */
  class?: string;
  /** Accessible label when no visible label */
  'aria-label'?: string;
  /** Reference to external label element */
  'aria-labelledby'?: string;
  /** Reference to description element */
  'aria-describedby'?: string;
  /** Whether the input value is invalid */
  'aria-invalid'?: boolean;
  /** Test ID */
  'data-testid'?: string;
}

const {
  defaultValue = 0,
  min,
  max,
  step = 1,
  largeStep,
  disabled = false,
  readOnly = false,
  showButtons = true,
  label,
  valueText,
  format,
  id,
  class: className = '',
  'aria-label': ariaLabel,
  'aria-labelledby': ariaLabelledby,
  'aria-describedby': ariaDescribedby,
  'aria-invalid': ariaInvalid,
  'data-testid': dataTestid,
} = Astro.props;

// Utility functions
const clamp = (val: number, minVal?: number, maxVal?: number): number => {
  let result = val;
  if (minVal !== undefined) result = Math.max(minVal, result);
  if (maxVal !== undefined) result = Math.min(maxVal, result);
  return result;
};

const roundToStep = (val: number, stepVal: number, minVal?: number): number => {
  const base = minVal ?? 0;
  const steps = Math.round((val - base) / stepVal);
  const result = base + steps * stepVal;
  const decimalPlaces = (stepVal.toString().split('.')[1] || '').length;
  return Number(result.toFixed(decimalPlaces));
};

// Calculate initial value
const initialValue = clamp(roundToStep(defaultValue, step, min), min, max);

// Format value helper
const formatValueText = (value: number, formatStr?: string): string => {
  if (!formatStr) return String(value);
  return formatStr
    .replace('{value}', String(value))
    .replace('{min}', min !== undefined ? String(min) : '')
    .replace('{max}', max !== undefined ? String(max) : '');
};

// Initial aria-valuetext
const getInitialAriaValueText = (): string | undefined => {
  if (valueText) return valueText;
  if (format) return formatValueText(initialValue, format);
  return undefined;
};
const initialAriaValueText = getInitialAriaValueText();

// Generate unique label ID
const labelId = label ? `spinbutton-label-${Math.random().toString(36).slice(2, 9)}` : undefined;

const effectiveLargeStep = largeStep ?? step * 10;
---

<apg-spinbutton
  data-min={min}
  data-max={max}
  data-step={step}
  data-large-step={effectiveLargeStep}
  data-disabled={disabled}
  data-readonly={readOnly}
  data-format={format}
>
  <div class={`apg-spinbutton ${disabled ? 'apg-spinbutton--disabled' : ''} ${className}`.trim()}>
    {
      label && (
        <span id={labelId} class="apg-spinbutton-label">
          {label}
        </span>
      )
    }
    <div class="apg-spinbutton-controls">
      {
        showButtons && (
          <button
            type="button"
            tabindex={-1}
            aria-label="Decrement"
            disabled={disabled}
            class="apg-spinbutton-button apg-spinbutton-decrement"
          >
            −
          </button>
        )
      }
      <input
        type="text"
        role="spinbutton"
        id={id}
        tabindex={disabled ? -1 : 0}
        inputmode="numeric"
        value={String(initialValue)}
        readonly={readOnly}
        aria-valuenow={initialValue}
        aria-valuemin={min}
        aria-valuemax={max}
        aria-valuetext={initialAriaValueText}
        aria-label={label ? undefined : ariaLabel}
        aria-labelledby={ariaLabelledby ?? labelId}
        aria-describedby={ariaDescribedby}
        aria-disabled={disabled || undefined}
        aria-readonly={readOnly || undefined}
        aria-invalid={ariaInvalid || undefined}
        data-testid={dataTestid}
        class="apg-spinbutton-input"
      />
      {
        showButtons && (
          <button
            type="button"
            tabindex={-1}
            aria-label="Increment"
            disabled={disabled}
            class="apg-spinbutton-button apg-spinbutton-increment"
          >
            +
          </button>
        )
      }
    </div>
    {showButtons && <span role="status" class="apg-spinbutton-live" />}
  </div>
</apg-spinbutton>

<script>
  class ApgSpinbutton extends HTMLElement {
    private input: HTMLInputElement | null = null;
    private incrementBtn: HTMLButtonElement | null = null;
    private decrementBtn: HTMLButtonElement | null = null;
    private liveRegion: HTMLElement | null = null;
    private announceTimer: ReturnType<typeof setTimeout> | undefined;
    private isComposing = false;
    private previousValidValue = 0;

    // Bound handler references (to properly remove listeners)
    private boundHandleKeyDown = this.handleKeyDown.bind(this);
    private boundHandleInput = this.handleInput.bind(this);
    private boundHandleBlur = this.handleBlur.bind(this);
    private boundHandleCompositionStart = this.handleCompositionStart.bind(this);
    private boundHandleCompositionEnd = this.handleCompositionEnd.bind(this);
    private boundHandleIncrement = this.handleIncrement.bind(this);
    private boundHandleDecrement = this.handleDecrement.bind(this);
    private boundPreventMouseDown = this.preventMouseDown.bind(this);

    connectedCallback() {
      this.input = this.querySelector('[role="spinbutton"]');
      this.incrementBtn = this.querySelector('.apg-spinbutton-increment');
      this.decrementBtn = this.querySelector('.apg-spinbutton-decrement');
      this.liveRegion = this.querySelector('.apg-spinbutton-live');

      if (this.input) {
        this.previousValidValue = this.currentValue;
        this.input.addEventListener('keydown', this.boundHandleKeyDown);
        this.input.addEventListener('input', this.boundHandleInput);
        this.input.addEventListener('blur', this.boundHandleBlur);
        this.input.addEventListener('compositionstart', this.boundHandleCompositionStart);
        this.input.addEventListener('compositionend', this.boundHandleCompositionEnd);
      }

      if (this.incrementBtn) {
        this.incrementBtn.addEventListener('mousedown', this.boundPreventMouseDown);
        this.incrementBtn.addEventListener('click', this.boundHandleIncrement);
      }

      if (this.decrementBtn) {
        this.decrementBtn.addEventListener('mousedown', this.boundPreventMouseDown);
        this.decrementBtn.addEventListener('click', this.boundHandleDecrement);
      }
    }

    disconnectedCallback() {
      clearTimeout(this.announceTimer);

      if (this.input) {
        this.input.removeEventListener('keydown', this.boundHandleKeyDown);
        this.input.removeEventListener('input', this.boundHandleInput);
        this.input.removeEventListener('blur', this.boundHandleBlur);
        this.input.removeEventListener('compositionstart', this.boundHandleCompositionStart);
        this.input.removeEventListener('compositionend', this.boundHandleCompositionEnd);
      }

      if (this.incrementBtn) {
        this.incrementBtn.removeEventListener('mousedown', this.boundPreventMouseDown);
        this.incrementBtn.removeEventListener('click', this.boundHandleIncrement);
      }

      if (this.decrementBtn) {
        this.decrementBtn.removeEventListener('mousedown', this.boundPreventMouseDown);
        this.decrementBtn.removeEventListener('click', this.boundHandleDecrement);
      }
    }

    private preventMouseDown(event: MouseEvent) {
      event.preventDefault();
    }

    private get min(): number | undefined {
      const val = this.dataset.min;
      return val !== undefined && val !== '' ? Number(val) : undefined;
    }

    private get max(): number | undefined {
      const val = this.dataset.max;
      return val !== undefined && val !== '' ? Number(val) : undefined;
    }

    private get step(): number {
      return Number(this.dataset.step) || 1;
    }

    private get largeStep(): number {
      return Number(this.dataset.largeStep) || this.step * 10;
    }

    private get isDisabled(): boolean {
      return this.dataset.disabled === 'true';
    }

    private get isReadOnly(): boolean {
      return this.dataset.readonly === 'true';
    }

    private get format(): string | undefined {
      return this.dataset.format;
    }

    private formatValue(value: number): string {
      const fmt = this.format;
      if (!fmt) return String(value);
      return fmt
        .replace('{value}', String(value))
        .replace('{min}', this.min !== undefined ? String(this.min) : '')
        .replace('{max}', this.max !== undefined ? String(this.max) : '');
    }

    private get currentValue(): number {
      return Number(this.input?.getAttribute('aria-valuenow')) || 0;
    }

    private clamp(val: number): number {
      let result = val;
      if (this.min !== undefined) result = Math.max(this.min, result);
      if (this.max !== undefined) result = Math.min(this.max, result);
      return result;
    }

    private roundToStep(val: number): number {
      const base = this.min ?? 0;
      const steps = Math.round((val - base) / this.step);
      const result = base + steps * this.step;
      const decimalPlaces = (this.step.toString().split('.')[1] || '').length;
      return Number(result.toFixed(decimalPlaces));
    }

    private updateValue(newValue: number, updateInput = true) {
      if (!this.input || this.isDisabled) return;

      const clampedValue = this.clamp(this.roundToStep(newValue));
      const currentValue = this.currentValue;

      if (clampedValue === currentValue) return;

      // Update ARIA
      this.input.setAttribute('aria-valuenow', String(clampedValue));

      // Update aria-valuetext if format is provided
      if (this.format) {
        this.input.setAttribute('aria-valuetext', this.formatValue(clampedValue));
      }

      // Update input value
      if (updateInput) {
        this.input.value = String(clampedValue);
      }

      this.previousValidValue = clampedValue;

      // Dispatch event
      this.dispatchEvent(
        new CustomEvent('valuechange', {
          detail: { value: clampedValue },
          bubbles: true,
        })
      );
    }

    private handleKeyDown(event: KeyboardEvent) {
      if (this.isDisabled) return;

      let newValue = this.currentValue;
      let handled = false;

      switch (event.key) {
        case 'ArrowUp':
          if (!this.isReadOnly) {
            newValue = this.currentValue + this.step;
            handled = true;
          }
          break;
        case 'ArrowDown':
          if (!this.isReadOnly) {
            newValue = this.currentValue - this.step;
            handled = true;
          }
          break;
        case 'Home':
          if (this.min !== undefined) {
            newValue = this.min;
            handled = true;
          }
          break;
        case 'End':
          if (this.max !== undefined) {
            newValue = this.max;
            handled = true;
          }
          break;
        case 'PageUp':
          if (!this.isReadOnly) {
            newValue = this.currentValue + this.largeStep;
            handled = true;
          }
          break;
        case 'PageDown':
          if (!this.isReadOnly) {
            newValue = this.currentValue - this.largeStep;
            handled = true;
          }
          break;
        default:
          return;
      }

      if (handled) {
        event.preventDefault();
        this.updateValue(newValue);
      }
    }

    private handleInput() {
      if (this.isComposing || !this.input) return;

      const parsed = parseFloat(this.input.value);
      if (!isNaN(parsed)) {
        const clampedValue = this.clamp(this.roundToStep(parsed));
        if (clampedValue !== this.previousValidValue) {
          this.input.setAttribute('aria-valuenow', String(clampedValue));
          if (this.format) {
            this.input.setAttribute('aria-valuetext', this.formatValue(clampedValue));
          }
          this.previousValidValue = clampedValue;
          this.dispatchEvent(
            new CustomEvent('valuechange', {
              detail: { value: clampedValue },
              bubbles: true,
            })
          );
        }
      }
    }

    private handleBlur() {
      if (!this.input) return;

      const parsed = parseFloat(this.input.value);

      if (isNaN(parsed)) {
        // Revert to previous valid value
        this.input.value = String(this.previousValidValue);
        this.input.setAttribute('aria-valuenow', String(this.previousValidValue));
      } else {
        const newValue = this.clamp(this.roundToStep(parsed));
        this.input.value = String(newValue);
        this.input.setAttribute('aria-valuenow', String(newValue));
        if (this.format) {
          this.input.setAttribute('aria-valuetext', this.formatValue(newValue));
        }
        if (newValue !== this.previousValidValue) {
          this.previousValidValue = newValue;
          this.dispatchEvent(
            new CustomEvent('valuechange', {
              detail: { value: newValue },
              bubbles: true,
            })
          );
        }
      }
    }

    private handleCompositionStart() {
      this.isComposing = true;
    }

    private handleCompositionEnd() {
      this.isComposing = false;
      this.handleInput();
    }

    // Announce the value after a button click, since the value change itself
    // may not be reported. Uses ariaNotify when available, otherwise a live region.
    private announce() {
      const input: (HTMLElement & { ariaNotify?: (m: string) => void }) | null = this.input;
      if (!input) return;
      const message = input.getAttribute('aria-valuetext') ?? String(this.currentValue);
      if (typeof input.ariaNotify === 'function') {
        input.ariaNotify(message);
        return;
      }
      if (!this.liveRegion) return;
      this.liveRegion.textContent = message;
      clearTimeout(this.announceTimer);
      this.announceTimer = setTimeout(() => {
        if (this.liveRegion) this.liveRegion.textContent = '';
      }, 1000);
    }

    private handleIncrement(event: MouseEvent) {
      event.preventDefault();
      if (this.isDisabled || this.isReadOnly) return;
      this.updateValue(this.currentValue + this.step);
      this.announce();
      this.input?.focus();
    }

    private handleDecrement(event: MouseEvent) {
      event.preventDefault();
      if (this.isDisabled || this.isReadOnly) return;
      this.updateValue(this.currentValue - this.step);
      this.announce();
      this.input?.focus();
    }

    // Public method to update value programmatically
    setValue(newValue: number) {
      this.updateValue(newValue);
    }
  }

  if (!customElements.get('apg-spinbutton')) {
    customElements.define('apg-spinbutton', ApgSpinbutton);
  }
</script>

---
import Spinbutton from './Spinbutton.astro';
---

<!-- Basic usage with aria-label -->
<Spinbutton aria-label="Quantity" />

<!-- With visible label and min/max -->
<Spinbutton
  defaultValue={5}
  min={0}
  max={100}
  label="Quantity"
/>

<!-- With format for display and aria-valuetext -->
<Spinbutton
  defaultValue={3}
  min={1}
  max={10}
  label="Rating"
  format="{value} of {max}"
/>

<!-- Decimal step values -->
<Spinbutton
  defaultValue={0.5}
  min={0}
  max={1}
  step={0.1}
  label="Opacity"
/>

<!-- Unbounded (no min/max limits) -->
<Spinbutton
  defaultValue={0}
  label="Counter"
/>

<!-- Listen to value changes (Web Component event) -->
<Spinbutton id="my-spinbutton" defaultValue={5} label="Value" />

<script>
  const spinbutton = document.querySelector('#my-spinbutton');
  spinbutton?.addEventListener('valuechange', (e) => {
    console.log('Value:', e.detail.value);
  });
</script>