wa-zoomable-frame のアイコン描画不具合をインポートで解消

wa-zoomable-frame が内部で使用しているズームコントロール用アイコン（plus / minus）が、wa-icon が未登録の環境で表示されない問題を、明示的なインポート追加で根本的に解決しました。

背景

このセクションでは、アイコン未表示の根本原因とその影響を概観します。

問題の根本は wa-zoomable-frame が wa-icon コンポーネントを使用しながら、依存関係のインポートを忘れていたことにあります。zoomable-frame.ts の render メソッドでは <wa-icon name="minus"…> と <wa-icon name="plus"…> が記述されていますが、../icon/icon.js が読み込まれない場合、カスタム要素が未登録のままになるため、ブラウザは何も描画しません。Issue #2455 で報告された通り、アイコンは機能上は動作するものの視覚的に欠落し、ユーザー体験が損なわれました。

この不具合はモジュラー環境やツリーシェイキングが有効なビルドで顕在化します。全体に wa-icon が事前にロードされている場合は問題になりませんが、個別に wa-zoomable-frame をインポートしただけではアイコンが欠けたままです。

したがって、コンポーネント側で依存を明示的に宣言する必要があるという結論に至り、修正が検討されました。

技術的な変更

このセクションでは、実装に加えられた具体的なコード変更とその効果を解説します。

zoomable-frame.ts の冒頭に wa-icon モジュールの副作用インポートが追加されました。これにより、モジュールロード時にカスタム要素が自動的に登録されるようになります。

@@ -6,6 +6,7 @@ import { ColorSchemeController } from '../../internal/color-scheme-controller.js
 import { parseSpaceDelimitedTokens } from '../../internal/parse.js';
 import WebAwesomeElement from '../../internal/webawesome-element.js';
 import { LocalizeController } from '../../utilities/localize.js';
+import '../icon/icon.js';
 import styles from './zoomable-frame.styles.js';

インポートは副作用だけを期待した形式で、戻り値は利用しません。../icon/icon.js が実行されると customElements.define('wa-icon', …) が走り、wa-icon がグローバルレジストリに追加されます。その結果、render メソッド内の <wa-icon> タグは即座に有効となり、アイコンが正しく描画されます。

この変更は他のロジックに影響を与えず、ビルドサイズへの増加も最小限です。インポートは1行追加だけで、既存のAPIやスタイルに破壊的変更はありません。テストスイートに新たな失敗は報告されておらず、機能回帰も防止されています。

設計判断

このセクションでは、インポート追加という選択が示す設計上の意図とトレードオフを検討します。

明示的インポートはコンポーネントの依存関係をビルド時に確実に解決する方策として採用されました。@dependency wa-icon とコメントで明示されている通り、依存はコード上で表明すべきと判断され、実行時エラーを未然に防ぎます。

代替案としてはドキュメントで利用者に手動インポートを促す、あるいは動的インポートで遅延ロードする方法が考えられました。しかし前者は利用者負担が増大し、後者は実装の複雑化とロード順序の不確実性を招くため、信頼性が低下します。今回の修正は「最小限の変更で確実に動作させる」ことを優先し、ビルド時の副作用インポートを選択しました。

この判断はコンポーネントの再利用性とモジュール性を高める方向と一致します。依存がコードに埋め込まれることで、パッケージ単体でのテストやデモが容易になり、他パッケージへの影響を最小限に抑えられます。

まとめ

wa-zoomable-frame が wa-icon を利用する際の依存宣言漏れを修正し、アイコンが常に表示されるようになりました。1 行の副作用インポート追加というシンプルな変更で、モジュラー環境やツリーシェイキングが有効なビルドでも機能的・視覚的な一貫性が確保されます。これにより、コンポーネントの信頼性が向上し、利用者は追加の設定なしにズームコントロールを利用できるようになります。