コード例における<wa-include>の展開による可読性向上
WebAwesomeのコード例表示機能が拡張され、<wa-include>タグが参照先のソースコードに再帰的に展開されるようになりました。これにより、コンポーネント化されたマルチページアプリケーションの実装をコード例から直接理解できるようになります。
背景
マルチページパターンのアプリケーションでは、<wa-include>を使ってインターフェース要素をコンポーネント化し、コードの重複を避けています。しかし、コード例に<wa-include>タグが表示されると、実際のソースコードを把握するのが困難になっていました。#1958でdata-select-src属性によるソース選択機能が追加されましたが、<wa-include>自体は展開されないままでした。
本PRは、この制約を解消するために<wa-include>を参照先コードに置き換える処理を実装しています。
技術的な変更
packages/webawesome/docs/_transformers/code-examples.jsにgetFrameSource関数が追加され、<wa-zoomable-frame>のソースコード取得処理が大幅に拡張されました。
変更前:
// getFrameSource関数は存在せず、
// srcdocまたはsrc属性の値をそのまま使用
変更後:
const getFrameSource = frame => {
const selectSrc = frame?.hasAttribute('data-select-src');
if (!selectSrc) return;
let src = frame.getAttribute('src');
let source = frame.getAttribute('srcdoc');
if (!source && src) {
// srcからファイルパスを正規化してソースを読み込み
src += src.match(/\.html/) ? '' : `${src.endsWith('/') ? '' : '/'}index.html`;
src = src.split('?')[0].split('#')[0];
source = readFileSync(path.join(baseDir, src), 'utf8');
}
const selectors = frame?.getAttribute('data-select-src');
if (selectors) {
const sourceNode = parse(source, { comment: true, voidTag: { closingSlash: true } });
sourceNode.querySelectorAll('wa-include').forEach(e => replaceIncludeWithSource(e));
// CSSセレクタに一致する要素を抽出し、フォーマットを正規化
// ...
}
return source.trim();
};
関数は以下の処理を順次実行します：
-
ソースの取得:
srcdoc属性が指定されている場合はその値を、src属性の場合はファイルシステムから読み込む -
wa-includeの展開:
sourceNode.querySelectorAll('wa-include').forEach(e => replaceIncludeWithSource(e))により、すべての<wa-include>を参照先のソースコードに再帰的に置き換える -
セレクタによる抽出:
data-select-src属性の値をCSSセレクタとして使用し、該当する要素のみを抽出 - フォーマットの正規化: インデントの調整、空行の整理、末尾空白の削除を実行
これにより、payment applicationのような複雑なマルチページアプリケーションのコード例でも、<wa-include>が実際のコードに展開されて表示されます。
設計判断
再帰的な展開処理が採用されました。querySelectorAll('wa-include')で抽出したすべての<wa-include>要素に対してreplaceIncludeWithSourceを適用することで、ネストされた<wa-include>も含めて完全に展開されます。
フォーマットの正規化では、parse()の出力における属性の不適切な改行を修正し、トップレベルまでインデントを削減し、複数の空行を単一の空行に折りたたむ処理が実装されています。これらの処理により、元のソースファイルとは異なるパース結果であっても、読みやすい形式で表示されます。
#1958で追加されたdata-select-src属性との統合により、展開後のコードから特定の要素のみを選択的に表示できる設計になっています。
まとめ
本PRは、コード例表示機能に再帰的な<wa-include>展開処理を追加した変更です。getFrameSource関数内で<wa-include>を参照先コードに置き換えることで、コンポーネント化されたアプリケーションの実装を、コード例から直接理解できるようになりました。既存のdata-select-src属性との組み合わせにより、展開後のコードから必要な部分のみを抽出して表示できます。