Checkbox Group コンポーネントの追加と周辺修正
新しい <wa-checkbox-group> が Web Awesome に導入され、チェックボックスやスイッチを共有ラベル・ヒントでまとめる機能が提供されました。合わせて、コード例表示のアクセシビリティ改善とダイアログボタンのスタイル統一が行われています。
背景
この PR は、以前のディスカッション #947 で合意された チェックボックスグループ 機能を実装するものです。実装にあたっては、関連 Issue #1076 で挙げられたコンポーネント追加の要望と合わせて、ドキュメントやテストの整備も同時に行われました。加えて、コピー用ボタンのフォーカス問題やダイアログのボタンスタイル不整合といった、既存コンポーネントの細部修正も本 PR に含まれています。
技術的な変更
コンポーネント本体の実装
wa-checkbox-group は WebAwesomeElement を継承し、@customElement('wa-checkbox-group') で登録されています。主要プロパティは label と hint で、スロットを通じて HTML ラベルやヒントを提供できます。また、orientation 属性でレイアウト方向を制御し、デフォルトは vertical です。
@customElement('wa-checkbox-group')
export default class WaCheckboxGroup extends WebAwesomeElement {
static css = [sizeStyles, formControlStyles, styles];
@property() label = '';
@property({ attribute: 'hint' }) hint = '';
@property({ reflect: true }) orientation: 'vertical' | 'horizontal' = 'vertical';
// ...省略...
}
スタイル定義
checkbox-group.styles.ts ではホスト要素のレイアウトと内部要素の間隔を CSS カスタムプロパティ --gap で管理しています。水平レイアウト時は --gap が 1 em に拡張され、フレックス方向が切り替わります。
:host {
--gap: 0.5em;
display: block;
}
:host([orientation='horizontal']) {
--gap: 1em;
}
[part~='form-control-input'] {
display: flex;
flex-direction: column;
align-items: start;
gap: var(--gap);
margin-block-start: 0.5em;
}
テストケース
checkbox-group.test.ts では、ラベルとヒントが正しく aria-labelledby / aria-describedby に反映されるか、role="group" が付与されているか、デフォルトの垂直レイアウトが適用されるかを検証しています。@open-wc/testing を利用したアクセシビリティテストも含まれています。
it('should expose a role="group" wrapper labeled by the label', async () => {
const el = await fixture<WaCheckboxGroup>(html`
<wa-checkbox-group label="Toppings">
<wa-checkbox value="cheese">Cheese</wa-checkbox>
</wa-checkbox-group>
`);
const group = el.shadowRoot!.querySelector('[role="group"]')!;
expect(group.getAttribute('aria-labelledby')).to.equal('label');
expect(group.getAttribute('aria-describedby')).to.equal('hint');
});
ドキュメントとナビゲーションの更新
新規マークダウン checkbox-group.md が追加され、基本使用例やラベル・ヒントの指定方法が記載されています。また、サイドバーテンプレート sidebar.njk にエントリが挿入され、コンポーネント一覧から直接参照できるようになりました。
@@ -230,6 +230,7 @@
</h2>
<ul>
<li><a href="/docs/components/checkbox/">Checkbox</a></li>
+ <li><a href="/docs/components/checkbox-group/">Checkbox Group</a></li>
<li><a href="/docs/components/color-picker/">Color Picker</a></li>
アクセシビリティ改善（コード例表示）
code-examples.js に source.inert の切り替えが追加され、折りたたまれたコード例がキーボードフォーカスから除外されます。これにより、コピー用ボタンが見えない領域でフォーカスされる問題が解消されました。
@@ -51,8 +51,10 @@
if (open) {
source.removeAttribute('aria-hidden');
+ source.inert = false;
} else {
source.setAttribute('aria-hidden', 'true');
+ source.inert = true;
}
}
ダイアログボタンのスタイル統一
dialog.md で <wa-button> の appearance="filled" が削除され、他の例と外観が統一されました。機能に影響はなく、見た目の一貫性のみが目的です。
@@ -19,7 +19,7 @@
<wa-dialog label="Dialog" id="dialog-overview">
This is a standard dialog. You can put any content you want in here!
- <wa-button appearance="filled" slot="footer" variant="brand" data-dialog="close">Close</wa-button>
+ <wa-button slot="footer" variant="brand" data-dialog="close">Close</wa-button>
</wa-dialog>
スペルチェック語彙の追加
cspell.json に "Groupable" が語彙として追加され、スペルチェックが補完されました。
@@ -95,6 +95,7 @@
"giga",
"globby",
"Grayscale",
+ "Groupable",
"groupby",
設計判断
HasSlotController が導入され、hint と label スロットの有無を監視し、スロットが未提供の場合は属性値にフォールバックしています。これにより、API の一貫性とアクセシビリティ要件が同時に満たされています。
レイアウト制御は CSS カスタムプロパティ --gap と orientation 属性の組み合わせで実装され、フレックス方向の切り替えはスタイルシートだけで完結します。追加ロジックが最小限に抑えられ、パフォーマンスへの影響が低減されています。
サイズ伝搬は sizeStyles と warnDeprecatedSize を継承し、子コンポーネントへ自動的に適用されます。将来的なサイズ API の統一に向けた段階的移行が可能な設計です。
アクセシビリティ改善として、code-examples.js の inert 制御と role="group" の提供が挙げられます。どちらもユーザーエクスペリエンスと WCAG への適合を意識した最小変更です。
まとめ
<wa-checkbox-group> の追加により、チェックボックスやスイッチのグルーピングが公式 API として提供され、ラベル・ヒント・方向性・サイズ設定が統一的に扱えるようになりました。併せて行われたドキュメント整備、ナビゲーション更新、アクセシビリティ微調整、ダイアログデザイン統一は、コンポーネント群全体の一貫性と開発者体験の向上に寄与します。