ドキュメント例をComboboxに置き換え、多数のオプション表示を改善

2026年02月05日 02:18 JST shoelace-style/webawesome

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

WebAwesomeのドキュメントにおいて、選択肢が多い例では wa-combobox を使用するように変更されました。これにより、長いオプションリストでも検索・フィルタリングが可能になり、ユーザー体験が向上します。

背景

ドキュメントの対話的な例では、アニメーション名やイージング関数、配置オプションなどを選択するために wa-select コンポーネントが使用されていました。Animationドキュメントでは数十種類のアニメーション名とイージング関数から選択する必要があり、Popupドキュメントでは12種類の配置オプション（top、top-start、bottom-end など）を提供していました。

通常のセレクトボックスでは、選択肢が増えるとスクロールが必要になり、目的のオプションを見つけにくくなります。特にアニメーション名のように数が多く、名前で探したい場合には不便でした。#1977は、この問題に対処するためにコンポーネントを切り替えています。

技術的な変更

主な変更は2つの領域で行われました。Pro版コンポーネントの動的ロードと、ドキュメント例の書き換えです。

Pro版Comboboxコンポーネントの動的ロード

wa-combobox はPro版コンポーネントであるため、フリー版リポジトリで動作させるための仕組みが追加されました。

変更後:

const proComponents = [
  "combobox",
  "page"
]

const kitCode = "f4ea8aaaeb9d4f12"

proComponents.forEach((tagName) => {
  if (!customElements.get("wa-" + tagName)) {
    import(`https://ka-p.webawesome.com/kit/${kitCode}/webawesome@{{ package.version }}/components/${tagName}/${tagName}.js`)
      .catch((e) => {
        // known errors with dual registration. This is only a thing in the free repo.
      })
  }
})

Pro版コンポーネントのリストを定義し、各コンポーネントが未登録の場合のみ動的にインポートする仕組みです。コメントにあるように、これはフリー版リポジトリでローカル実行するための暫定的な実装で、シングルトンの動作やコンポーネントの二重読み込みに関する既知の問題があります。

Animationドキュメントの例の書き換え

アニメーション名とイージング関数の選択に wa-combobox が適用されました。

変更後:

<div class="animation-sandbox-combobox">
  <wa-animation name="bounce" easing="ease-in-out" duration="2000" play>
    <div class="box"></div>
  </wa-animation>

  <div class="controls">
    <wa-combobox label="Animation" placeholder="Select animation..."></wa-combobox>
    <wa-combobox label="Easing" placeholder="Select easing..."></wa-combobox>
    <wa-input label="Playback Rate" type="number" min="0" max="2" step=".25" value="1"></wa-input>
  </div>
</div>

スクリプト部分では、getAnimationNames() と getEasingNames() から取得したリストを使って wa-option 要素を動的に生成し、Comboboxに追加します。

await customElements.whenDefined('wa-combobox');
await customElements.whenDefined('wa-option');

const animations = getAnimationNames();
const easings = getEasingNames();

animations.forEach(name => {
  const option = document.createElement('wa-option');
  option.value = name;
  option.textContent = name;
  animationName.append(option);
});

カスタム要素の定義完了を待ってから要素を生成することで、確実に動作するようにしています。

Popupドキュメントの例の書き換え

配置オプションの選択にも同様の変更が適用されました。

変更前:

<wa-select label="Placement" name="placement" value="top" class="popup-overview-select">
  <wa-option value="top">top</wa-option>
  <wa-option value="top-start">top-start</wa-option>
  <wa-option value="top-end">top-end</wa-option>
  <!-- ... 12個のオプション -->
</wa-select>

変更後:

<wa-combobox label="Placement" name="placement" placeholder="Select placement..." class="popup-overview-select"></wa-combobox>

HTMLから冗長なオプション定義がなくなり、JavaScriptで動的に生成される形になりました。

const placements = ['top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end'];

placements.forEach(value => {
  const option = document.createElement('wa-option');
  option.value = value;
  option.textContent = value;
  placement.append(option);
});

配置オプションのリストを配列で定義し、ループ処理でオプションを追加することで、HTMLの記述量が大幅に削減されています。

設計判断

既存の wa-select を置き換える方式が採用されました。

ドキュメント内の例を更新する際、wa-select と wa-combobox を併用する選択肢もありましたが、すべての該当箇所で wa-combobox に統一されています。これにより、ユーザーは一貫したインターフェースで多数のオプションから選択できます。

また、オプションの定義を動的生成に変更することで、HTMLの可読性が向上し、メンテナンスも容易になりました。配置オプションやアニメーション名のような定型的なリストは、JavaScriptの配列やAPIから取得する方が変更に強い構造です。

本PRは、ドキュメントの対話的な例における選択UI を改善した変更です。多数のオプションを扱う場面で検索・フィルタリング可能な wa-combobox に切り替えることで、ユーザーが目的の値を素早く見つけられるようになりました。