feat(aria/spinbutton): add aria spinbutton component

Introduces the aria spinbutton primitive with SpinButtonGroup for
automatic button connection using contentChildren, eliminating the
need for template reference variables.

Usage:
```html
<div ngSpinButtonGroup>
  <button ngSpinButtonDecrement>−</button>
  <input ngSpinButton [(value)]="value">
  <button ngSpinButtonIncrement>+</button>
</div>
```

- Add SpinButton directive with full ARIA spinbutton pattern
- Add SpinButtonGroup directive with contentChildren discovery
- Add SpinButtonIncrement and SpinButtonDecrement directives
- Add incrementDisabled/decrementDisabled computed signals to pattern
- Add public increment/decrement methods to pattern

Author: OmerGronich

.ng-dev/commit-message.mts

@@ -14,6 +14,7 @@ export const commitMessage: CommitMessageConfig = {
     'aria/grid',
     'aria/listbox',
     'aria/menu',
+    'aria/spinbutton',
     'aria/tabs',
     'aria/toolbar',
     'aria/tree',

src/aria/config.bzl

@@ -5,10 +5,11 @@ ARIA_ENTRYPOINTS = [
     "grid",
     "listbox",
     "menu",
+    "private",
+    "spinbutton",
     "tabs",
     "toolbar",
     "tree",
-    "private",
 ]
 
 # List of all entry-point targets of the Angular Aria package.

src/aria/private/BUILD.bazel

@@ -17,6 +17,7 @@ ts_project(
         "//src/aria/private/grid",
         "//src/aria/private/listbox",
         "//src/aria/private/menu",
+        "//src/aria/private/spinbutton",
         "//src/aria/private/tabs",
         "//src/aria/private/toolbar",
         "//src/aria/private/tree",

src/aria/private/public-api.ts

@@ -25,3 +25,4 @@ export * from './grid/row';
 export * from './grid/cell';
 export * from './grid/widget';
 export * from './deferred-content';
+export * from './spinbutton/spinbutton';

src/aria/private/spinbutton/BUILD.bazel

@@ -0,0 +1,16 @@
+load("//tools:defaults.bzl", "ts_project")
+
+package(default_visibility = ["//visibility:public"])
+
+ts_project(
+    name = "spinbutton",
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = ["**/*.spec.ts"],
+    ),
+    deps = [
+        "//:node_modules/@angular/core",
+        "//src/aria/private/behaviors/event-manager",
+        "//src/aria/private/behaviors/signal-like",
+    ],
+)

src/aria/private/spinbutton/spinbutton.ts

@@ -0,0 +1,251 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {KeyboardEventManager} from '../behaviors/event-manager';
+import {computed, SignalLike, WritableSignalLike} from '../behaviors/signal-like/signal-like';
+
+/** Represents the required inputs for a spinbutton. */
+export interface SpinButtonInputs {
+  /** A unique identifier for the spinbutton. */
+  id: SignalLike<string>;
+
+  /** The current value. Undefined represents an indeterminate state. */
+  value: WritableSignalLike<number | undefined>;
+
+  /** The minimum allowed value. */
+  min: SignalLike<number | undefined>;
+
+  /** The maximum allowed value. */
+  max: SignalLike<number | undefined>;
+
+  /** The step increment for arrow keys. */
+  step: SignalLike<number>;
+
+  /** The large step increment for Page Up/Down. Undefined means Page Up/Down are ignored. */
+  largeStep: SignalLike<number | undefined>;
+
+  /** Whether to wrap from max→min and min→max. */
+  wrap: SignalLike<boolean>;
+
+  /** Whether the spinbutton is disabled. */
+  disabled: SignalLike<boolean>;
+
+  /** Whether the spinbutton is readonly. */
+  readonly: SignalLike<boolean>;
+
+  /** Whether the spinbutton value is invalid. */
+  invalid: SignalLike<boolean>;
+
+  /** Whether the spinbutton is required. */
+  required: SignalLike<boolean>;
+
+  /**
+   * Human-readable text alternative to the value.
+   * When provided, this is used for aria-valuetext.
+   * When not provided, aria-valuetext uses the numeric value with proper formatting.
+   */
+  valueText: SignalLike<string | undefined>;
+
+  /** Reference to the host element. */
+  element: SignalLike<HTMLElement>;
+}
+
+/** Controls the state of a spinbutton. */
+export class SpinButtonPattern {
+  /** The tabindex of the spinbutton. */
+  tabIndex = computed(() => (this.inputs.disabled() ? -1 : 0));
+
+  /** Whether the spinbutton is disabled. */
+  disabled = computed(() => this.inputs.disabled() || null);
+
+  /** Whether the spinbutton is readonly. */
+  readonly = computed(() => this.inputs.readonly() || null);
+
+  /** Whether the spinbutton value is invalid. */
+  invalid = computed(() => this.inputs.invalid() || null);
+
+  /** Whether the spinbutton is required. */
+  required = computed(() => this.inputs.required() || null);
+
+  /** The current value for aria-valuenow. */
+  valueNow = computed(() => this.inputs.value() ?? null);
+
+  /** The minimum value for aria-valuemin. */
+  valueMin = computed(() => this.inputs.min() ?? null);
+
+  /** The maximum value for aria-valuemax. */
+  valueMax = computed(() => this.inputs.max() ?? null);
+
+  /** Whether increment is disabled (spinbutton disabled or at max without wrap). */
+  incrementDisabled = computed(() => {
+    if (this.inputs.disabled()) return true;
+    const value = this.inputs.value();
+    const max = this.inputs.max();
+    if (max === undefined || this.inputs.wrap()) return false;
+    return value !== undefined && value >= max;
+  });
+
+  /** Whether decrement is disabled (spinbutton disabled or at min without wrap). */
+  decrementDisabled = computed(() => {
+    if (this.inputs.disabled()) return true;
+    const value = this.inputs.value();
+    const min = this.inputs.min();
+    if (min === undefined || this.inputs.wrap()) return false;
+    return value !== undefined && value <= min;
+  });
+
+  /** The human-readable text for aria-valuetext. */
+  valueText = computed(() => {
+    const customText = this.inputs.valueText();
+    if (customText !== undefined) {
+      return customText;
+    }
+
+    const value = this.inputs.value();
+    if (value === undefined) {
+      return null;
+    }
+
+    // Replace hyphen-minus (U+002D) with Unicode minus sign (U+2212)
+    // for proper screen reader announcement on macOS VoiceOver
+    return String(value).replace('-', '\u2212');
+  });
+
+  /** The keydown event manager for the spinbutton. */
+  keydown = computed(() => {
+    const manager = new KeyboardEventManager();
+
+    if (this.inputs.disabled() || this.inputs.readonly()) {
+      return manager;
+    }
+
+    return manager
+      .on('ArrowUp', () => this._increment(this.inputs.step()))
+      .on('ArrowDown', () => this._decrement(this.inputs.step()))
+      .on('PageUp', () => {
+        const largeStep = this.inputs.largeStep();
+        if (largeStep !== undefined) {
+          this._increment(largeStep);
+        }
+      })
+      .on('PageDown', () => {
+        const largeStep = this.inputs.largeStep();
+        if (largeStep !== undefined) {
+          this._decrement(largeStep);
+        }
+      })
+      .on('Home', () => {
+        const min = this.inputs.min();
+        if (min !== undefined) {
+          this.inputs.value.set(min);
+        }
+      })
+      .on('End', () => {
+        const max = this.inputs.max();
+        if (max !== undefined) {
+          this.inputs.value.set(max);
+        }
+      });
+  });
+
+  constructor(readonly inputs: SpinButtonInputs) {}
+
+  /** Returns a set of violations. */
+  validate(): string[] {
+    const violations: string[] = [];
+    const min = this.inputs.min();
+    const max = this.inputs.max();
+    const value = this.inputs.value();
+    const wrap = this.inputs.wrap();
+
+    if (min !== undefined && max !== undefined && min > max) {
+      violations.push(`SpinButton: min (${min}) cannot be greater than max (${max}).`);
+    }
+
+    if (wrap && (min === undefined || max === undefined)) {
+      violations.push(`SpinButton: wrap requires both min and max to be defined.`);
+    }
+
+    if (value !== undefined) {
+      if (min !== undefined && value < min) {
+        violations.push(`SpinButton: value (${value}) is less than min (${min}).`);
+      }
+      if (max !== undefined && value > max) {
+        violations.push(`SpinButton: value (${value}) is greater than max (${max}).`);
+      }
+    }
+
+    return violations;
+  }
+
+  /** Handles keydown events for the spinbutton. */
+  onKeydown(event: KeyboardEvent): void {
+    this.keydown().handle(event);
+  }
+
+  /** Increments the value by the configured step. */
+  increment(): void {
+    this._increment(this.inputs.step());
+  }
+
+  /** Decrements the value by the configured step. */
+  decrement(): void {
+    this._decrement(this.inputs.step());
+  }
+
+  /** Increments the value by the given step amount. */
+  private _increment(step: number): void {
+    const currentValue = this._getInitializedValue();
+    const max = this.inputs.max();
+    const min = this.inputs.min();
+    const wrap = this.inputs.wrap();
+
+    let newValue = currentValue + step;
+
+    if (max !== undefined && newValue > max) {
+      if (wrap && min !== undefined) {
+        newValue = min;
+      } else {
+        newValue = max;
+      }
+    }
+
+    this.inputs.value.set(newValue);
+  }
+
+  /** Decrements the value by the given step amount. */
+  private _decrement(step: number): void {
+    const currentValue = this._getInitializedValue();
+    const min = this.inputs.min();
+    const max = this.inputs.max();
+    const wrap = this.inputs.wrap();
+
+    let newValue = currentValue - step;
+
+    if (min !== undefined && newValue < min) {
+      if (wrap && max !== undefined) {
+        newValue = max;
+      } else {
+        newValue = min;
+      }
+    }
+
+    this.inputs.value.set(newValue);
+  }
+
+  /** Gets the current value, initializing to min ?? 0 if undefined. */
+  private _getInitializedValue(): number {
+    const value = this.inputs.value();
+    if (value === undefined) {
+      const initialValue = this.inputs.min() ?? 0;
+      this.inputs.value.set(initialValue);
+      return initialValue;
+    }
+    return value;
+  }
+}

src/aria/spinbutton/BUILD.bazel

@@ -0,0 +1,57 @@
+load("//tools:defaults.bzl", "extract_api_to_json", "ng_project", "ng_web_test_suite")
+
+package(default_visibility = ["//visibility:public"])
+
+ng_project(
+    name = "spinbutton",
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = ["**/*.spec.ts"],
+    ),
+    deps = [
+        "//:node_modules/@angular/core",
+        "//src/aria/private",
+        "//src/cdk/a11y",
+    ],
+)
+
+ng_project(
+    name = "unit_test_sources",
+    testonly = True,
+    srcs = glob(
+        ["**/*.spec.ts"],
+        exclude = ["**/*.e2e.spec.ts"],
+    ),
+    deps = [
+        ":spinbutton",
+        "//:node_modules/@angular/core",
+        "//:node_modules/@angular/platform-browser",
+        "//:node_modules/axe-core",
+        "//src/cdk/testing/private",
+    ],
+)
+
+ng_web_test_suite(
+    name = "unit_tests",
+    deps = [":unit_test_sources"],
+)
+
+filegroup(
+    name = "source-files",
+    srcs = glob(
+        ["**/*.ts"],
+        exclude = ["**/*.spec.ts"],
+    ),
+)
+
+extract_api_to_json(
+    name = "json_api",
+    srcs = [
+        ":source-files",
+    ],
+    entry_point = ":index.ts",
+    module_name = "@angular/aria/spinbutton",
+    output_name = "aria-spinbutton.json",
+    private_modules = [""],
+    repo = "angular/components",
+)

src/aria/spinbutton/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+export * from './public-api';

src/aria/spinbutton/public-api.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+export {SpinButton} from './spinbutton';
+export {SpinButtonIncrement} from './spinbutton-increment';
+export {SpinButtonDecrement} from './spinbutton-decrement';
+export {SpinButtonGroup} from './spinbutton-group';