0.3から1.0への移行

このガイドでは公開パッケージの契約を対応づけます。アプリケーション固有のimport、ルート、データモデル、依存関係のリビジョン、ギャップ分析、移行状況は含みません。

変更点

1.0.0は追加リリースではなく、全面的な置き換えです。0.3の実装、Tailwindプリセット、スタイルシート、およびすべてのサブパスエクスポートはパッケージから削除されました。1.0.0内に互換性のための経路はありません。アプリケーションは意図的にアップグレードするか、引き続き公開・インストール可能な0.3.xを使います。

両リリースが同じimportパスを使うため、1つのインストール済みバージョンから0.3と1.0を同時にレンダリングすることはできません。本番コードを段階的に変更するのではなく、ブランチを作ってアップグレードしてください。

セットアップの変更

1. 独立した移行ブランチに1.0.0をインストールします。
2. Tailwindプリセットのimport、パッケージのcontent glob、./stylesのimportを削除します。
3. アプリケーションレベルのエントリで@language-lit/material3-expressive/styles.cssを一度だけ読み込みます。
4. Material3Providerをレンダリングし、light、dark、systemからモードを選びます。
5. カスタムデザイン値をCSSやTailwind設定ではなく、createTheme／extendThemeのデータに移します。
6. コンポーネントをセマンティックな領域ごとに置き換え、フォーム、キーボード操作、フォーカス、RTL、強制カラー、モーションの軽減、SSR、本番CSSを確認します。

よくある公開概念の対応

正確なpropsについてはサポート対象コンポーネントの一覧と各リンク先をご覧ください。名前が似ていても、propsレベルの互換性は保証されません。

1.0に対応するプリミティブがない0.3 API

0.3パッケージには、1.0の一覧にあるMaterialプリミティブではないユーティリティや、アプリケーションレベルの表示パターンが含まれていました。データ表示レシピ、フレームワークアダプターのコンテキスト、アプリケーションのフォントやテーマを読み込むフックなどです。これらはアプリケーション側の組み立てで置き換えるか、公開タスクの手順に従って将来の汎用コンポーネントを提案してください。以前存在したことを理由に、提供範囲が広がることはありません。

破壊的変更

• /theme、/tokens、/styles.css以外のすべてのサブパスが削除されました。
• Tailwindプリセット、パッケージのcontent glob、./stylesエントリはなくなりました。
• CSSはm3e名前空間を使い、Tailwindトークンを消費しません。0.3の--md-*カスタムプロパティは削除されました。
• Material3Providerは実際のdivでテーマをスコープ化します。フレームワークのリンク／画像アダプターは管理しません。
• コンポーネントでは、移植したアプリケーションやComposeのロールより、ネイティブ要素とAPGのセマンティクスを優先します。
• 状態を持つ複合コンポーネントでは、子要素やルーターに結びつけず、明示的な制御／非制御の値コールバックとデータ配列を使います。
• アイコン用のレジストリやフォントローダーは同梱されません。
• パッケージにランタイム依存関係はありません。peer依存関係はReactとReact DOMのみです。
• サポートの保証対象は生成された準拠コンポーネント一覧のみです。

検証とロールバック

移行した領域ごとに、アプリケーションの型チェック、テスト、アクセシビリティチェック、SSRビルド、本番バンドルを実行します。公開パッケージの検証には、このリポジトリのnpm run verifyを使います。

ロールバックでは、利用側の変更で0.3.x依存関係、import、スタイルを復元します。利用側固有の展開／ロールバック手順は、この公開リポジトリの対象外です。