JSX型定義の強化とSolidJS対応

2026年02月03日 02:56 JST shoelace-style/webawesome

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

Web AwesomeのJSX型生成パッケージがアップグレードされ、SolidJS向けのTypeScript型定義とイベントターゲットの型安全性が向上しました。これにより、React・SolidJSなどのJSX利用環境でのWeb Awesomeコンポーネントの開発体験が改善されます。

背景

Web Awesomeは @wc-toolkit/jsx-types を使用してJSX向けの型定義を生成していましたが、従来のバージョン（1.3.0）ではReactのみをサポートし、イベントハンドラの型定義が不完全でした。#1925 はパッケージを1.5.2にアップグレードし、新機能を活用する形で型定義の生成設定を拡張しています。

この変更により、SolidJSユーザーがWeb Awesomeコンポーネントを使用する際の型サポートが提供され、JSXでのイベントハンドリング時に正確な型情報が得られるようになります。

技術的な変更

型生成の設定ファイル custom-elements-manifest.js に stronglyTypedEvents オプションが追加されました。

変更前:

jsxTypesPlugin({
  fileName: 'custom-elements-jsx.d.ts',
  outdir,
  defaultExport: true,
  componentTypePath: (_name, _tag, modulePath) => {
    return `./${modulePath}`;
  },
}),

変更後:

jsxTypesPlugin({
  fileName: 'custom-elements-jsx.d.ts',
  outdir,
  defaultExport: true,
  stronglyTypedEvents: true,
  componentTypePath: (_name, _tag, modulePath) => {
    return `./${modulePath}`;
  },
}),

stronglyTypedEvents: true により、イベントハンドラの型定義が CustomEvent<{ ... }> ではなく、コンポーネント固有のイベント型（WaSlideChangeEvent、WaHideEvent など）を使用するようになります。各コンポーネントファイルでは、これらのイベント型が export type ステートメントで公開されています。

export type { WaSlideChangeEvent };

@customElement('wa-carousel')
export default class WaCarousel extends WebAwesomeElement {
  // ...
}

イベントのJSDocコメントも、@event {{ index: number, slide: WaCarouselItem }} から @event {WaSlideChangeEvent} のように型名を直接参照する形式に統一されました。

SolidJSサポートの追加

SolidJSユーザー向けのドキュメント docs/frameworks/solidjs.md が新規追加されました。このドキュメントでは、TypeScript設定の2つのアプローチが示されています。

TSConfig設定方式:

{
  "compilerOptions": {
    "types": [
      "@awesome.me/webawesome/dist/custom-elements-jsx.d.ts"
    ]
  }
}

トリプルスラッシュディレクティブ方式:

/// <reference types="@awesome.me/webawesome/dist/custom-elements-jsx.d.ts" />

これらの設定により、SolidJSの .tsx ファイル内で <wa-button> のような Web Awesome コンポーネントを使用する際に、プロパティとイベントの型補完が有効になります。

Drawer コンポーネントの不要なプロパティ削除

wa-drawer コンポーネントの JSDoc から modal プロパティの説明が削除されました。このプロパティは内部実装の詳細であり、公開 API として文書化する必要がなかったためです。

- * @property modal - Exposes the internal modal utility that controls focus trapping. To temporarily disable focus
- *   trapping and allow third-party modals spawned from an active Shoelace modal, call `modal.activateExternal()` when
- *   the third-party modal opens. Upon closing, call `modal.deactivateExternal()` to restore Shoelace's focus trapping.

設計判断

イベント型の外部公開 という設計判断が採用されました。

PR内では、イベント型を各コンポーネントファイルから export type する方式が選択されています。これにより、JSX型生成ツールがこれらの型定義を参照でき、生成される型定義ファイル内でイベントハンドラに適切な型を適用できます。

代替案として、イベント型を内部型として保持し、JSDoc内で匿名型として定義する方法も考えられましたが、型の再利用性と型定義ファイルの生成の観点から、明示的な型エクスポートが選ばれています。この判断により、ユーザーコード内でもイベント型を直接参照できる副次的な利点が生まれました。

import type { WaSlideChangeEvent } from '@awesome.me/webawesome';

function handleSlideChange(event: WaSlideChangeEvent) {
  console.log('Slide changed to:', event.detail.index);
}

SolidJSサポートに関しては、Reactと同じ型定義ファイルを共有する設計が採用されました。JSX型生成ツールの新バージョンが両フレームワークの型定義を単一ファイルで生成できるため、フレームワークごとに別々の型定義を管理する必要がなくなっています。

まとめ

本PRは、型生成パッケージのアップグレードと設定オプションの追加により、Web AwesomeコンポーネントのJSX利用時の型安全性を向上させました。stronglyTypedEvents オプションの有効化とイベント型の明示的なエクスポートにより、イベントハンドラが正確な型情報を持つようになり、SolidJSユーザーにも同等の型サポートが提供されるようになっています。