Accordion と Accordion Item コンポーネントの追加

Web Awesome へ <wa-accordion> と <wa-accordion-item> の 2 つの実験的コンポーネントが追加され、キーボード対応の縦型可展開セクションが利用可能になりました。

背景

なぜ新しいコンポーネントが必要だったのか は、従来の UI パターンで頻出する「FAQ」や「設定パネル」等の情報整理が、アクセシビリティとデザインの両立で実装コストが高くなる点です。既存コンポーネント群は単体要素の組み合わせで実装されており、展開・折りたたみロジックやイベントハンドリングを各プロジェクトで重複実装していました。この PR は、共通化とアクセシビリティの標準化を目的に、Accordion 系の基盤コンポーネントを公式に提供します。

技術的な変更

コンポーネント実装 は packages/webawesome/src/components/accordion/ と accordion-item/ に新規ファイルを追加し、Lit を用いた Web Components として定義されています。主な変更点は以下の通りです。

accordion.ts に WaAccordion クラスを追加。mode（multiple/single/single-collapsible）や icon-placement、heading-level、appearance といった属性を反映し、expandAll() / collapseAll() メソッドと 4 種類のカスタムイベント（wa-expand など）を提供します。
accordion-item.ts に WaAccordionItem クラスを追加。label、expanded、disabled 属性をホストに反映し、expand() / collapse() / toggle() が Promise を返してアニメーション完了を通知します。animationGeneration カウンタで競合アニメーションを防止しています。
スタイルは accordion.styles.ts と accordion-item.styles.ts に分割し、--spacing、--show-duration、--hide-duration、--easing 等の CSS カスタムプロパティで外部調整が可能です。アイコン位置は flex-direction: row-reverse により start 配置を実現しています。
カスタムイベントは src/events/ に新規追加し、events.ts でエクスポートしています。WaAccordionExpandEvent などはキャンセル可能で、親コンポーネント側で展開ロジックをフックできます。
テストは accordion.test.ts と accordion-item.test.ts に総合的なアクセシビリティテスト、属性デフォルト検証、キーボード操作シナリオを追加し、@open-wc/testing と @web/test-runner-commands を利用しています。
ドキュメントは docs/components/accordion.md と accordion-item.md を新規作成し、使用例、属性一覧、イベント一覧を掲載。サイドバーのナビゲーションは docs/_includes/sidebar.njk にリスト項目を挿入して自動反映させました。

代表的なコード例

@customElement('wa-accordion')
export default class WaAccordion extends WebAwesomeElement {
  @property({ reflect: true }) mode: 'single' | 'single-collapsible' | 'multiple' = 'multiple';
  @property({ attribute: 'icon-placement', reflect: true }) iconPlacement: 'start' | 'end' = 'end';
  // …省略
}

@customElement('wa-accordion-item')
export default class WaAccordionItem extends WebAwesomeElement {
  @property({ type: Boolean, reflect: true }) expanded = false;
  @property({ type: Boolean, reflect: true }) disabled = false;
  // expand(), collapse(), toggle() が Promise を返す実装
}

設計判断

属性拡張と後方互換性の選択 が本 PR の中心的な設計判断です。WaAccordion と WaAccordionItem は両方とも WebAwesomeElement を継承し、CSS カスタムプロパティで外観を外部から制御できるようにしました。属性はすべて reflect: true とし、DOM から直接閲覧・変更できる点でコンポーネントの宣言的使用を促進しています。イベントは キャンセル可能 に設計し、アプリ側で展開前にロジックを差し込める柔軟性を持たせました。さらに、mode のデフォルトを multiple とし、既存 UI パターンへの影響を最小化しています。これらは「拡張は最小限に、既存 API との互換性は保持する」という設計方針に沿った選択です。

まとめ

本 PR により、Web Awesome にアクセシブルでカスタマイズ可能な Accordion 系コンポーネント が標準装備され、共通実装の重複を排除しつつ、属性・イベント・CSS カスタムプロパティによる柔軟な制御が可能になりました。ドキュメントとテストの整備により、導入障壁も低く設定されています。