launchpad-ux-custom-components

概要

このスキルでは、Constellation デザインシステムを基盤とする Pega Launchpad の カスタム UX について紹介します。以下について説明します。

• 標準搭載のビューやテンプレートだけを使うのではなく、カスタム Constellation コンポーネントの構築を検討すべきタイミング。
• カスタムコンポーネントを実装する前に必要となる情報とデザイン上の入力。
• カスタム UX が Launchpad の全体的なアーキテクチャと DX パターンにどのように適合するか。

カスタムコンポーネントは、Launchpad のデザイン言語とランタイムモデルを尊重しながら、特化したビジュアライゼーション、インタラクション、または統合を追加することで、標準の Constellation UX を拡張します。

コード生成前に必須となる会話の流れ

重要：ユーザーがカスタムコンポーネントをリクエストした場合、エージェントは references/conversation-flow.md で定義されたステップごとの会話の流れに必ず従ってください。

すべてのステップが完了し、ユーザーが確認するまで、コードを生成しないでください。

この流れでは、以下を確認します。

1. ステップ 1：OOTB Constellation コンポーネントでは要件を満たせないことを確認する
2. ステップ 2：UX Boosters カタログ（https://launchpad.io/ux-boosters）を確認する
3. ステップ 3：詳細な要件（機能、配置場所、データ、インタラクション）を収集する
4. ステップ 4：コンポーネントタイプ（Field／Widget／Template）の推奨を提示し、ユーザーの確認を得る
5. ステップ 5：その後に限り、コードを生成する

会話スクリプトと例の全体については、references/conversation-flow.md を参照してください。

---

前提条件

Launchpad 用のカスタム DX コンポーネントを構築する前に、以下を準備してください。

1. 開発環境

   • Node.js（LTS バージョン。例：18.x または 20.x）
   • npm（Node.js に付属）
   • コードエディター（VS Code を推奨）

2. Launchpad Provider へのアクセス

   • Launchpad Provider の管理者アクセス権
   • コンポーネントを使用するアプリケーション

3. DXCB 用の OAuth クライアント認証情報

   • Launchpad Studio で、9 ドットメニューをクリックし、Administration setup に移動します
   • 新しい OAuth 2.0 client registration を追加します
   • tasks.config.json 用の clientId と clientSecret を控えておきます

4. Provider の詳細

   • フロントエンド URL（例：https://your-provider.launchpad.io）
   • Isolation ID（Provider の設定で確認できます）

カスタム UX を構築するタイミング

ビジネス要件と UX 要件を満たす場合は、標準搭載の Constellation コンポーネントとテンプレートを優先してください。新しいカスタムコンポーネントの構築を決定する前に、Astro はユーザーに次のことを明示的に警告し、確認を促す必要があります。

1. まず UX Boosters カタログを確認する

   • Launchpad の事前構築済みカスタム UX コンポーネントの公開カタログ（**https://launchpad.io/ux-boosters**）を確認してください。
   • 要件を満たすコンポーネントがすでに存在し、ワンクリックで Provider にインストールできるかどうかを確認してください。

2. Constellation / Launchpad が標準でサポートしていないことを確認する

   • 要求されたパターンが、標準の Constellation ビュー、リージョンテンプレート、フィールド／ウィジェットの構成としてすでに利用できるかどうかを確認してください。
   • OOTB オプションがある場合は、新しいカスタムコンポーネントを作成するのではなく、そちらを使うよう Astro が推奨してください。

次の確認を行った後に限り、カスタム UX を検討してください。

• ビジネス上、標準では利用できない視覚化またはインタラクションパターン（たとえば、特殊なチャート、マップ、スケジューラー、複合レイアウト）が必要である。
• Launchpad のエクスペリエンス内に外部ウィジェットまたはライブラリを埋め込む必要がある（たとえば、サードパーティ製のマップ、チャート、ドキュメントビューアー）。
• 既存の Constellation の構成要素では適切にモデル化できない、複数のケースタイプやポータルで使用する再利用可能な UX パターンが必要である。
• 標準的なフォームやリストのパターンを超えた、特定のユーザーロールに合わせたビューで生産性や明瞭さを向上させたい。

カスタム UX を決定する前に、次の点を確認してください。

• 必要な動作を、標準の Constellation ビュー、リージョンテンプレート、OOTB コンポーネント（インストール可能な UX Boosters を含む）でモデル化できないこと。
• カスタムエクスペリエンスが、Launchpad のナビゲーション、アクセシビリティ、レスポンシブ対応のガイドラインに準拠できること。
• 長期的な保守コスト（更新、セキュリティ、ライブラリのアップグレード）が許容できること。

カスタム UX コンポーネントの構築前に必要な情報

カスタム UX コンポーネントを適切に設計、実装するには、まず次の情報を集めてください。

1. ユーザーとユースケースの定義

   • コンポーネントを使用するのは誰ですか（ペルソナ、ロール、チャネル）？
   • コンポーネントはどのポータルまたはページに表示されますか？
   • ユーザーがより迅速または正確に完了できるよう支援するのは、どのようなタスクまたは意思決定ですか？

2. データと API

   • コンポーネントに必要なLaunchpad のデータ（ケース、データオブジェクト、データページ）は何ですか？
   • どのDX API または Data View エンドポイントからデータを取得しますか？
   • コンポーネントから Launchpad に返す必要がある入力プロパティ（フィルター、選択項目、アクション）は何ですか？

3. インタラクションと動作

   • 主なユーザーアクションは何ですか（表示のみ、選択、ドラッグ＆ドロップ、インライン編集、詳細を開くなど）？
   • コンポーネントは状態の変化（読み込み中、エラー、空の状態、成功）にどのように対応すべきですか？
   • UX で適用する必要があるビジネスルール（選択数の上限、必須手順、検証メッセージ）はありますか？

4. ビジュアルデザインとレイアウト

   • レイアウト、階層、主要な状態を示すスケッチまたはワイヤーフレーム。
   • Constellation のデザイントークン（色、タイポグラフィ、間隔）およびレイアウトパターンとの整合性。
   • レスポンシブ動作（デスクトップ、タブレット、モバイルのブレークポイント）に関するガイドライン。

5. 技術的な制約とライブラリ

   • 必要な外部ライブラリまたは SDK（マップ、チャート、ドキュメントビューアー）、およびライセンスやセキュリティへの影響。
   • パフォーマンスまたはセキュリティに関する考慮事項（大規模なデータセット、PII、外部呼び出し）。

これらの情報を事前に文書化しておくと、カスタム UX コンポーネントが次の条件を満たすようにできます。

• 実際のユーザーニーズに基づいている。
• Launchpad と Constellation のデザインルールに準拠している。
• 実装と保守が実現可能である。

カスタム UX と Launchpad および DX の関係

カスタム UX コンポーネントは、Launchpad の DX アプローチに適切に統合してください。

• ブラウザーからバックエンドシステムを直接呼び出すのではなく、主要なデータアクセスレイヤーとして DX API と Data View を使用します。
• コンポーネントは UI ロジックのみを担うものとして扱います。複雑なビジネスルールや判断は、可能な限りサーバー側に維持してください。
• Launchpad の セキュリティおよびアクセス制御モデルに従い、認証や認可のチェックを回避しないでください。
• 一貫したエクスペリエンスを保つために、Constellation の ナビゲーションモデル（ケース、割り当て、ダイアログの開き方など）を尊重してください。

DXCB – カスタム UX コンポーネント向けフレームワーク

**DXCB（Digital Experience Component Builder）**は、Constellation 対応のカスタムコンポーネントを構築するためのフレームワークおよびツールセットです。次の標準的な方法を提供します。

• フロントエンドコード（通常は React ベース）を Constellation 拡張機能として構成します。
• DX API と Data View から取得する Launchpad のデータとコンテキストにコンポーネントをバインドします。
• コンポーネントをパッケージ化して登録し、Launchpad のポータルやビューで 再利用可能な構成要素として表示します。

DXCB を使用すると、カスタムコンポーネントは次のようになります。

• Constellation の デザインシステム（レイアウトグリッド、タイポグラフィ、間隔、色）を尊重します。
• Launchpad の ケースコンテキスト、ルーティング、更新モデルと適切に統合されます。
• 場当たり的なカスタムコードではなく、既知の拡張パターンに従うため、アップグレードに対応しやすくなります。

DXCB プロジェクトの開始

概要として、DXCB を使用して Launchpad のカスタムコンポーネントを構築する手順は次のとおりです。

1. DXCB プロジェクトを初期化する
   ターミナルで、DXCB プロジェクトを作成するフォルダーに移動します。

   npx @pega/custom-dx-components@~25.1 init
   

   重要：現在推奨されているバージョンについては、必ず Pega の公式ドキュメントを確認してください（このスキルの最後にある Pega の公式ドキュメントのセクションを参照）。

   • プロジェクト名、組織、バージョン、説明のプロンプトに回答します。
   • コンポーネント名を分かりやすく付けられるよう、組織名／ライブラリ名は適度に短くしてください。

2. tasks.config.json を構成する
   初期化後、DXCB によって tasks.config.json ファイルが作成されます。server-config セクションに Launchpad プロバイダーの詳細を設定します（前提条件を参照）。

   • server – プロバイダーのフロントエンド URL
   • clientId と clientSecret – OAuth 認証情報
   • isolationID – プロバイダーの分離 ID

   認証情報は 機密情報として扱い、社内のセキュリティ慣行に従ってください。

3. コンポーネントフォルダーを作成する
   コンポーネントディレクトリ（たとえば、src/components）内で次の作業を行います。

   • コンポーネントごとにフォルダーを作成します（たとえば、range-slider-template）。
   • 次のファイルを追加します。
     • コンポーネントの タイプ、サブタイプ、構成を定義する config.json。
     • getPConnect() と、必要に応じてグローバルな PCore を使用する React 実装ファイル（たとえば、index.tsx）。

適切なコンポーネントタイプの選択

DXCB は、Constellation コンポーネントを主に 3 種類サポートしています。

• レイアウトテンプレート：ビュー全体のレイアウトです（DETAILS、FORM、PAGE）。
• ウィジェット：ダッシュボードやユーティリティ向けの自己完結型パネル／カードです（PAGE、CASE、または PAGE と CASE）。
• フィールドコンポーネント：フィールドのサブタイプ（Integer、Text、Decimal など）を持つ単一フィールド用のコントロールです。

判断に迷った場合は、Constellation の UX パターンを基準に考えてください。

• ケース詳細のバンドとサマリーカード

  • パターン：ケースまたはデータビューの Details 領域にある KPI やサマリーパネルです。
  • DXCB：subtype: "DETAILS" を指定した Template です。
  • 例：examples/dxcb-examples/range-slider-template/ の Range Slider Template は、getPConnect().getActionsApi().updateFieldValue(...) を介して最小値／最大値をケースフィールドに書き戻します。

• ダッシュボードとランディングページのタイル

  • パターン：ポータルのランディングページにあるタイルやインサイトパネルです。
  • DXCB：subtype: "PAGE" を指定した Widget です（ユーティリティでも再利用する場合は ["PAGE", "CASE"]）。
  • 例：examples/dxcb-examples/calendar-widget/ の Calendar Widget は、Constellation データページから今後の作業項目を表示し、ナビゲーションやプレビューに PCore と getPConnect() を使用します。

• ケースビューのユーティリティペイン用ヘルパー

  • パターン：ケースの Utilities pane にあるコンテキストパネル（インサイト、タイムライン、関連する作業など）です。
  • DXCB：subtype: "CASE" を指定した Widget です。

• カスタムフィールドコントロール

  • パターン：専用の視覚表現を備えた単一入力コントロール（評価、ピル選択、カスタムスライダーなど）です。
  • DXCB：適切な field subtype（たとえば "Integer"、"Text"、"Decimal"）を指定した Field です。
  • 例：examples/dxcb-examples/star-rating-input/ の Star Rating Field は、整数のスコアを書き込み、Constellation のフィールド動作に準拠します。

正しいタイプとサブタイプを選択すると、次のことが実現します。

• Launchpad Studio の作成者が、適切なコンテキストでコンポーネントを 見つけられる ようになります。
• DXCB が適切な スターター実装 を生成します。
• コンポーネントが想定した場所（ウィジェットピッカー、レイアウトテンプレート、フィールドの「Display as」オプション）に表示されます。

DXCB プロジェクトから Launchpad Studio へ

DXCB プロジェクトでコンポーネントを実装したら、次の手順を実行します。

1. コンポーネントをビルドする DXCB プロジェクトのルートから DXCB のビルドスクリプトを実行します。例：

   npm run buildComponent
   

2. 対象の Provider に対して認証する DXCB の認証スクリプト（たとえば npm run Authenticate）を使用すると、tasks.config.json の server-config の値を使って、DXCB から Launchpad Provider に公開できます。

3. コンポーネントを公開する 公開スクリプト（たとえば npm run publish）を実行して、コンポーネントを Provider に登録します。

公開が成功すると、コンポーネントは Launchpad Studio に次のように表示されます。

• ウィジェットピッカーの Widget（type と subtype に応じて、Portal または Case／Utilities）。
• ビューのレイアウトピッカーの Template（Details、Form、Page）。
• 該当するタイプのフィールドの Display as オプションにある Field。

Astro が新しいコンポーネントの要件を収集する方法

開発者から新しいカスタムコンポーネントの作成を依頼された場合、エージェントは次の手順に従います。

1. 最も近い例を特定する

   • Launchpad のリファレンスリポジトリを参照します：https://github.com/pegasystems/constellation-ui-gallery/tree/next/src/components
   • config.json のタイプとサブタイプ（Field / Widget / Template）、および全体的な動作が依頼内容に最も合うコンポーネントを選びます。

2. config.json.properties を質問項目のチェックリストとして使用する

   • 選んだ例の config.json にある properties 配列を、入力が必要なビューのメタデータとして扱います。
   • 関連するプロパティごとに、開発者へ具体的な質問をします。たとえば、次のように尋ねます。
     • Field コンポーネントの場合：
       • PROPERTY フィールド（例：inputProperty、minValueProperty、maxValueProperty）：
         • 「このコンポーネントで読み取りと更新を行うケース／データプロパティはどれですか？」
       • LABEL / helper text フィールド（例：label、helperText）：
         • 「このコントロールに表示するラベルとヘルパーテキストを教えてください。」
       • SELECT オプション（例：format、maxRating）：
         • 「[property name] にはどのオプションを希望しますか？（source にある有効な値を列挙します。）」
     • Widget コンポーネントの場合：
       • データソースフィールド（例：dataPage）：
         • 「このウィジェットで使用するデータページはどれですか？」
       • コンテキスト／フィルターフィールド（例：contextProperty、setCaseID）：
         • 「現在のケースでフィルタリングしますか？する場合は、コンテキストを保持するプロパティを教えてください。」
       • レイアウト固有のフィールド（例：groups、groupProperty）：
         • 「列として表示するステータスまたはグループと、グループ化に使用するプロパティを教えてください。」
     • Template コンポーネントの場合：
       • リージョンの設定（例：A リージョン）：
         • 「リージョン A に配置するビューまたはフィールドを教えてください。」
       • 数値の境界値（例：min、max、step）：
         • 「このコントロールに設定する数値の範囲と増分を教えてください。」

3. コードを生成する前に確認して要約する

   • 回答内容を設定スナップショットとして要約します（使用するプロパティ、データソース、ラベル、範囲など）。
   • その後にのみ、次のものを生成します。
     • 回答内容を組み込んだ、用途に合わせた config.json と、
     • 次の要件を満たす index.tsx の実装：
       • getPConnect().getRawMetadata().config を使用して値を読み取ること。
       • references/PCore-PConnect-APIs.md の PConnect / PCore パターンに従うこと。

実装リファレンス – PConnect と PCore

DXCB コンポーネントの構築に関する、より詳しいコードレベルのガイダンスについては、このスキルフォルダーにある統合リファレンスを使用します。

• references/PCore-PConnect-APIs.md – Launchpad のカスタムコンポーネントで、コンポーネントごとの PConnect API（getPConnect()）とグローバルな PCore API（データページ、イベント、pub/sub、セマンティック URL）を使用する方法。

この SKILL.md では、カスタムコンポーネントをいつ、どのように設計するか、および DXCB が Launchpad にどう適合するかに焦点を当てています。references/ ドキュメントでは、詳細な実装パターンを説明しています。

Launchpad コンポーネントのリファレンスリポジトリ

重要：Launchpad では、コンポーネントのパターンや例を参照する際、Constellation UI Gallery リポジトリの next ブランチを使用してください。

https://github.com/pegasystems/constellation-ui-gallery/tree/next/src/components

master ブランチや Infinity 専用リポジトリは、Launchpad に適用できないパターンが含まれている場合があるため、使用しないでください。

新しいカスタムコンポーネントを生成する際、エージェントは次の手順に従う必要があります。

• まず、https://github.com/pegasystems/constellation-ui-gallery/tree/next/src/components のコンポーネントを参照し、類似したパターンを探します。
• 最初から作成するのではなく、要求されたパターン（テンプレート、ウィジェット、またはフィールド）に合った既存のコンポーネントを複製し、適応させます。
• このリポジトリのフォルダー構成、命名規則、実装パターンに従います。

リポジトリで利用できるコンポーネントパターンの例：

• Pega_Extensions_BarCode – バーコードの表示／入力コンポーネント。
• Pega_Extensions_Calendar – カレンダー／スケジュール管理ウィジェット。
• Pega_Extensions_IframeWrapper – iframe で外部コンテンツを埋め込むためのラッパー。
• Pega_Extensions_KanbanBoard – 作業項目用のカンバン形式のボード。
• Pega_Extensions_Meter – メーター／ゲージの視覚化コンポーネント。
• Pega_Extensions_QRCode – QR コードの表示／入力コンポーネント。
• Pega_Extensions_RangeSlider – 数値範囲用のレンジスライダーテンプレート。
• Pega_Extensions_RatingLayout – ケース概要用の評価レイアウトテンプレート。
• Pega_Extensions_SignatureCapture – 署名取得フィールドコンポーネント。
• Pega_Extensions_StarRatingInput – 星評価入力フィールド。
• Pega_Extensions_UtilityList – ケース／ポータルのコンテキスト用のユーティリティリストウィジェット。

Field コンポーネントのコーディングパターン（例：パスワード入力）

新しい Field コンポーネント（パスワード入力、テキスト入力など、単一の値を扱うコントロール）を生成する際、Astro は次の点に従ってください。

• 新しい構造を独自に考案するのではなく、参照リポジトリにある既存のフィールドコンポーネントのパターンを複製してください（例：Pega_Extensions_StarRatingInput）。
  • PegaExtensionsPasswordInput のような名前付きコンポーネントを定義してください。
  • @pega/cosmos-react-core の withConfiguration を使い、export default withConfiguration(PegaExtensionsPasswordInput); でデフォルトエクスポートしてください。
• 生の HTML 入力要素ではなく、Cosmos のフィールドコンポーネントを使用してください。
  • 編集可能なテキスト／パスワード形式の入力には、<input>／<label> の HTML 要素ではなく、@pega/cosmos-react-core の Input コンポーネントをレンダリングしてください。
  • 表示専用モードでは、編集可能なフィールドではなく、マスクされた値を持つ Text コンポーネントをレンダリングしてください（例：パスワードの場合は '***********'）。
• Constellation のランタイムおよび config.json に合わせて props を設定してください。
  • 次のような props を受け取ってください：getPConnect、label、value、helperText、validatemessage、hideLabel、displayMode、hasSuggestions、fieldMetadata、additionalProps、testId、disabled、readOnly、required。
  • 文字列として渡される場合があるブール値の props を正規化してください（例：true と 'true' の両方を true として扱う）。
  • fieldMetadata（例：fieldMetadata.maxLength）を使用して、Input の maxLength などの制約を設定してください。
• データバインディングには PConnect Actions API と状態マッピングを使用してください。
  • getPConnect() から PConnect インスタンスを取得し、次の値を導出してください。
    • const actions = pConn.getActionsApi();
    • const propName = pConn.getStateProps().value;（フィールドの基になるケースフィールド名）。
  • 値が実際に変わった場合にのみ、変更時に actions.updateFieldValue(propName, newValue) を使ってケースフィールドを更新してください。
  • フォーカスが外れたときに、actions.triggerFieldChange(propName, newValue) を使って検証と候補の処理を実行し、該当する場合は pConn.ignoreSuggestion() も実行してください。
• Constellation の表示モードとステータスを尊重してください。
  • displayMode === 'DISPLAY_ONLY' の場合は、編集可能な入力をレンダリングせず、編集不可の表示形式を返してください（パスワードの場合は、マスクされた Text の値を使用します）。
  • 既存の Pega_Extensions_* フィールドコンポーネントのパターンに従い、validatemessage、hasSuggestions などの props を使って、Cosmos の Input に設定するフィールドの status（'error'、'pending' など）を決定してください。

推奨フロントエンドパッケージ

Launchpad Custom UX 向けの React コンポーネントを生成または調整する際、エージェントは次の優先順位に従ってください。

1. まず、要件に合う既存のコンポーネントがないか @pega/cosmos-react-core（https://www.npmjs.com/package/@pega/cosmos-react-core）**を確認してください**。一般的なコンポーネントには、`Input`、`Button`、`Text`、`Flex`、`Grid`、`Card`、`Badge`、`Icon`、`FormField`、`Select`、`Checkbox`、`DatePicker`、`Modal`、`Table`、`Tabs` などがあります。カスタム実装を作成するのではなく、これらを直接使用してください。

2. 次に、単一のコンポーネントでは要件を満たせない場合、複数の Cosmos コンポーネントを組み合わせてください。@pega/cosmos-react-core のレイアウト、フォーム、表示用コンポーネントを組み合わせます。

3. 最後に、既存の Cosmos コンポーネントまたはその組み合わせでは要件を満たせない場合に限り、カスタムコンポーネントを作成してください。

• 参照リポジトリにある既存コンポーネントの import 文を確認し、新しいコードで同じパッケージとコンポーネントを再利用してください。
• インポートしたパッケージが、対象プロジェクトの package.json の依存関係に追加されていることを確認してください。

推奨パッケージの詳細な一覧と優先順位の全ガイドラインについては、references/frontend-packages.md を参照してください。

リポジトリの規約とファイル構成

DXCB コンポーネントを作成する際は、一貫性と見つけやすさを確保するため、次の命名規則と構成規則に従ってください。

フォルダーとファイルの命名

• コンポーネントフォルダー：Pega_Extensions_<Name> の形式を使用します（例：Pega_Extensions_StarRatingInput、Pega_Extensions_Calendar）。
• フォルダー名は、config.json の name および componentKey の値と一致させる必要があります。
• 各コンポーネントの標準ファイル：

ファイル	用途	必須
index.tsx	React コンポーネントの主な実装	✅ はい
config.json	DX コンポーネントのメタデータ（タイプ、サブタイプ、プロパティ）	✅ はい
Docs.mdx	Storybook／ギャラリー向けのドキュメント	✅ はい
demo.stories.tsx	コンポーネントをプレビューする Storybook ストーリー	✅ はい
demo.test.tsx	Jest ユニットテスト	✅ はい
styles.ts	Styled-components／CSS-in-JS	任意
localizations.json	i18n 文字列	任意

コンポーネント実装の規約

• React のインポート：ファイルの先頭に、必ず React のデフォルトインポートを含めてください。これにより、DXCB の TypeScript 設定で JSX が正しく動作します。

  import React, { useState, useEffect, useCallback } from 'react';
  

  重要：React のデフォルトインポートなしで import { useState } from 'react' を使用しないでください。DXCB プロジェクトの tsconfig では "jsx": "react" が使用されており、JSX 変換のために React がスコープ内に必要です。

• withConfiguration を使用したエクスポート：@pega/cosmos-react-core の withConfiguration でコンポーネントを必ずラップしてください。

  import React from 'react';
  import { withConfiguration } from '@pega/cosmos-react-core';
  
  const PegaExtensionsMyComponent = (props) => { /* ... */ };
  
  export default withConfiguration(PegaExtensionsMyComponent);
  

• TypeScript の React パターン：TypeScript を使用した関数コンポーネントを使用します。

• getPConnect の型指定：リポジトリに、より強い型の共通定義がすでに存在する場合を除き、コンポーネントの props には getPConnect?: any を使用してください。重複する単独の PegaConnect、PegaActionsApi、PegaStateProps インターフェイスは作成しないでください。

• フィールドスタイルのコンポーネント：

  • 公開 prop 名には hideLabel を使用します。
  • labelHidden={hideLabel} は Cosmos コントロールの内部でのみ渡します。
  • disabled、readOnly、required の型は boolean とし、共有パターンを使用して実行時の文字列 'true' を boolean に変換します。

    const [readOnlyBool, requiredBool, disabledBool] = [readOnly, required, disabled].map(
      (v) => v === true || v === 'true'
    );
    

config.json の構造

config.json が次の構造に従っていることを確認してください。

{
  "name": "Pega_Extensions_MyComponent",
  "componentKey": "Pega_Extensions_MyComponent",
  "label": "My Custom Component",
  "description": "A custom component for...",
  "type": "Field",
  "subtype": "Text",
  "properties": [
    {
      "name": "label",
      "label": "Label",
      "format": "TEXT"
    },
    {
      "name": "value",
      "label": "Value",
      "format": "PROPERTY"
    }
  ]
}

Storybook の規約

コンポーネントの demo.stories.tsx を作成する際は、次の点に従ってください。

• 値が制限されている props には、自由入力ではなく select コントロールを使用します。
• testId、hideLabel、disabled、readOnly、required など、一般的な props には適切なデフォルト値を設定します。
• 必要に応じて、追加のストーリーを Docs.mdx に記載します。
• ストーリーのレンダリングに必要な範囲でのみ PConnect／PCore をモックします。

検証とテスト

コンポーネントを完成と見なす前に、品質を確保するため、次の検証手順を実行してください。

リント

コードスタイルの問題や潜在的なエラーを検出するため、リンターを実行します。

npm run lint

問題を自動修正するには、次を実行します。

npm run fix

ビルドの検証

公開する前に、コンポーネントが正しくビルドされることを確認してください。

npm run buildComponent

コンポーネントの提供チェックリスト

コンポーネントの実装を完了する前に、次のチェックリストを使用してください。

• フォルダー名が Pega_Extensions_<Name> の規則に従っている
• config.json の name と componentKey がフォルダー名と一致している
• index.tsx が型付けされたコンポーネントを withConfiguration でラップしてエクスポートしている
• フィールドスタイルのコンポーネントでは、公開プロパティとして labelHidden ではなく hideLabel を使用している
• ブール型プロパティ（disabled、readOnly、required）が文字列 'true' の値を処理している
• getPConnect がリポジトリの規則（getPConnect?: any）に従っている
• PConnect／PCore の使用方法をリポジトリ内の例または公式ドキュメントで確認している
• Docs.mdx でコンポーネントを説明し、実際のプロパティと一致している
• demo.stories.tsx が適切なモックを使用してレンダリングされる
• Storybook のコントロールで、選択肢が限定されるプロパティに select を使用している
• 追加のストーリーを Docs.mdx の ## Examples に記載している
• demo.test.tsx で主要なレンダリング、動作、エッジケースをカバーしている
• styles.ts と localizations.json は必要な場合にのみ存在している
• コンポーネントをギャラリーに表示する必要がある場合、ソース登録ファイルを更新している
• npm run lint が成功する（または問題を明示的に報告している）
• npm run test で関連するテストが成功する
• スキップした検証手順があれば、明示的に記載している

ガードレール

カスタムコンポーネントを作成する際は、よくある問題を避けるため、次のルールに従ってください。

• DX コンポーネントのメタデータを独自に作成しないでください。 リポジトリ内の既存コンポーネントの構造と命名パターンを踏襲してください。
• 明示的に依頼されていない限り、生成済みのバンドルやリリース成果物を手動で編集しないでください。
• リポジトリに適切な選択肢がすでにある場合、利便性のためだけにパッケージ依存関係を追加しないでください。 まず既存の package.json を確認してください。
• コンポーネントを未完成のままにしないでください。 依頼で使用可能なコンポーネントが求められている場合は、必要なファイルをすべて含む完全な実装を提供してください。
• Constellation のパターンを回避しないでください。 生の HTML ではなく Cosmos コンポーネントを使用し、テーマ設定、アクセシビリティ、レスポンシブ動作を尊重してください。
• 検証を省略しないでください。 必ず npm run lint と関連するテストを実行するか、検証を省略した理由を明示的に報告してください。

Pega 公式ドキュメント

最新のガイダンスについては、次の Pega 公式リソースを参照してください。

トピック	ドキュメントリンク
DX コンポーネントで Launchpad を拡張する	https://docs.pega.com/bundle/launchpad/page/platform/launchpad/extend-applications-constellation-dx-components.html
Launchpad で DX コンポーネントを使用する	https://docs.pega.com/bundle/launchpad/page/platform/launchpad/working-constellation-dx-component-launchpad.html
DXCB プロジェクトを初期化する	https://docs.pega.com/bundle/constellation-dx-components/page/constellation-dx-components/custom-components/initialize-project.html
Constellation DX コンポーネントの概要	https://docs.pega.com/bundle/constellation-dx-components/page/constellation-dx-components/custom-components/custom-components.html
Launchpad と Infinity の違い	https://docs.pega.com/bundle/launchpad/page/platform/launchpad/differences-constellation-dx-components-launchpad-infinity.html