このライブラリについて

Plain Elements は、スタイルを持たないアクセシブルな UI primitive を提供する Web Components ライブラリです。Dialog、Popover、Tooltip、Tabs、Accordion、Collapsible の 6 つのコンポーネントがあり、それぞれ利用者が書いた HTML に対して操作性と ARIA 属性を追加します。

設計原則

• プラットフォーム API: Dialog はネイティブの <dialog> と showModal()、Accordion は <details> / <summary> を基本とし、Popover は Popover API を使います。ブラウザが既に持っているアクセシビリティや操作方法がある場合は再実装せず活かし、実装量を抑えます。
• Light DOM: Shadow DOM は使いません。すべての要素は、通常の CSS セレクターや Tailwind などのユーティリティクラスでそのままスタイリングできます。
• 利用者の HTML を変更しない: 要素の生成、ラップ、移動、並べ替え、削除は行いません。初期化時に変更するのは data-* 属性、aria-* 属性、仕様化された範囲での ID 補完、tabindex、位置計算に必要な最小限のインラインスタイルだけです。
• Progressive enhancement: JavaScript の読み込み前から、ネイティブ HTML として意味のある状態を保ちます。

提供するもの・しないもの

Plain Elements が提供するのは、アクセシビリティと操作性の実装です。具体的には、ARIA 属性の同期、キーボード操作、フォーカス管理、状態を表す data-* 属性、必要な場合のカスタムイベントです。

一方で、次のものは提供しません。

• 見た目のスタイル。CSS は同梱していないため、色、余白、アニメーションなどはすべて利用側で指定します。
• wrapper 要素や portal の生成。DOM 構造は利用者が書いた通りに保たれます。
• React、Vue、Svelte などの framework 向けの adapter。Web Components としてそのまま扱えるため、専用のラッパーは用意していません。

配布形態

ライブラリは ESM と IIFE の両方でビルドされ、npm package として配布します。ESM はバンドラーや type="module" に対応した環境向け、IIFE は script タグ 1 つ、または jsDelivr CDN から読み込める形式で、CMS やビルドツールを使わない環境に向いています。どちらの形式でも、読み込んだ時点でカスタム要素が登録されます。

想定用途

主な利用シーンは、CMS、LP、コーポレートサイト、静的サイトなど一般的な Web サイトです。加えて、Web アプリケーションでの利用も想定しており、安定した公開 API とテストを備えています。React や Vue などの framework を使っているプロジェクトでも、custom element としてそのまま組み込めます。まずはクイックスタートを参照してください。