`<wa-number-input>`の追加による数値入力の標準化

2026年02月03日 00:33 JST shoelace-style/webawesome

https://github.com/shoelace-style/webawesome/pull/1990

Web Awesome 3.2では、ステッパーボタンを備えた数値入力コンポーネント <wa-number-input> が実験的機能として追加されました。これにより、Kickstarterストレッチゴールの5番目のコンポーネントとして、フォーム制御要素の充実が図られます。

背景

Web Awesomeは、Kickstarterプロジェクトにおいて14個の新規コンポーネント追加をストレッチゴールとして掲げており、#1076でその進捗が管理されています。今回の<wa-number-input>が5番目のコンポーネントとして実装され、#1688でトラッキングされていた作業が完了しました。

数値入力は多くのWebアプリケーションで必要とされる基本的なUI要素ですが、ブラウザネイティブの<input type="number">には、スタイリングの制約やクロスブラウザでの一貫性の問題がありました。専用コンポーネントの追加により、Web Awesomeの設計思想に沿った統一的なUIを提供できます。

技術的な変更

コンポーネントの実装

packages/webawesome/src/components/number-input/number-input.tsに新規ファイルが追加され、381行のコンポーネント実装が含まれています。コンポーネントは WebAwesomeFormAssociatedElement を継承しており、標準的なフォーム制御要素として機能します。

主要なプロパティ:

@property({ type: Number }) min?: number;
@property({ type: Number }) max?: number;
@property({ type: Number }) step = 1;
@property({ type: Boolean, attribute: 'without-steppers' }) withoutSteppers = false;
@property() inputmode: 'numeric' | 'decimal' = 'numeric';

これらのプロパティにより、最小値・最大値の制約、ステップ幅の指定、ステッパーボタンの表示/非表示、キーボードタイプの制御が可能です。

スタイリングシステム

packages/webawesome/src/components/number-input/number-input.styles.tsには246行のスタイル定義があり、Web Awesomeの既存のデザイントークンを活用しています。

.number-field {
  display: flex;
  align-items: stretch;
  justify-content: start;
  height: var(--wa-form-control-height);
  border-color: var(--wa-form-control-border-color);
  border-radius: var(--wa-form-control-border-radius);
}

appearance 属性（outlined/filled）に応じた外観の切り替えや、pill 属性による角丸表示、size 属性（small/medium/large）によるサイズバリエーションをサポートしています。

ステッパーボタンのアイコン

packages/webawesome/src/components/icon/library.system.tsに、ステッパーボタン用の plus アイコンが追加されました。既存の minus アイコンと組み合わせて、増減ボタンに使用されます。

plus: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 640"><!--!Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2026 Fonticons, Inc.--><path fill="currentColor" d="M352 128C352 110.3 337.7 96 320 96C302.3 96 288 110.3 288 128L288 288L128 288C110.3 288 96 302.3 96 320C96 337.7 110.3 352 128 352L288 352L288 512C288 529.7 302.3 544 320 544C337.7 544 352 529.7 352 512L352 352L512 352C529.7 352 544 337.7 544 320C544 302.3 529.7 288 512 288L352 288L352 128z"/></svg>`

国際化対応

多くの言語ファイルに、ステッパーボタンのアクセシビリティラベル用の翻訳が追加されています。

increment: 'Increment',
decrement: 'Decrement'

これにより、スクリーンリーダーユーザーが各ボタンの機能を理解できるようになります。Diffからは、アラビア語、チェコ語、デンマーク語、ドイツ語、英語、スペイン語、ペルシア語、フィンランド語、フランス語、ヘブライ語、ヒンディー語、クロアチア語、ハンガリー語、インドネシア語、イタリア語、日本語、カザフ語、ノルウェー語（ブークモール）、オランダ語、ノルウェー語（ニーノシュク）、ポーランド語、ポルトガル語の翻訳ファイルが更新されたことが確認できます。

テストカバレッジ

packages/webawesome/src/components/number-input/number-input.test.tsには598行のテストコードが含まれており、以下の観点がカバーされています:

アクセシビリティ検証
デフォルトプロパティの確認
フォーム送信時の値のシリアライゼーション
min/max/step制約の動作
ステッパーボタンのクリック操作
キーボード操作（上下矢印キー）
無効化・読み取り専用状態
カスタム状態（blank、invalid）

ドキュメントとナビゲーション

packages/webawesome/docs/docs/components/number-input.mdに226行のドキュメントページが追加され、使用例やAPIリファレンスが提供されています。サイドバーナビゲーション（docs/_includes/sidebar.njk）では、計画中を示す plannedBadge が削除され、通常のリンクに変更されました。

-<li><span class="is-planned wa-split">Number Input <a href="https://github.com/shoelace-style/webawesome/issues/1688" target="_blank">{{ plannedBadge("A Web Awesome Kickstarter stretch goal!") }}</a></span></li>
+<li><a href="/docs/components/number-input">Number Input</a></li>

設計判断

フォーム統合の優先

コンポーネントは WebAwesomeFormAssociatedElement を基底クラスとして採用しており、標準的なHTML5フォーム検証やフォーム送信との統合が最初から考慮されています。MirrorValidatorによる制約検証により、min/maxなどの属性が自動的にバリデーションロジックに反映されます。

ステッパーボタンのオプション化

without-steppers 属性の提供により、ステッパーボタンの表示を制御できます。これは、画面スペースが限られたモバイル環境や、キーボード入力を主とするデスクトップ環境での柔軟な使い分けを可能にする判断です。

実験的ステータスの付与

@status experimentalのタグが付与されており、APIの安定性が保証されていないことが明示されています。コンポーネント定義の冒頭にこのアノテーションを配置することで、ドキュメント生成時に自動的に警告が表示される仕組みです。

`inputmode`属性のデフォルト値

inputmodeのデフォルト値として numeric が選択されました。これにより、モバイルデバイスで数値専用キーボードが表示されます。小数点入力が必要な場合はdecimalに変更できる設計となっています。

まとめ

本PRは、Web AwesomeのKickstarterストレッチゴール達成に向けた重要なマイルストーンです。フォーム統合、国際化、アクセシビリティ、テストカバレッジのすべてにおいて、既存コンポーネントと同等の品質基準を満たす実装となっています。実験的ステータスでのリリースにより、ユーザーフィードバックを収集しながらAPIの成熟度を高めていく段階的なアプローチが採られています。

背景