make-app-group

make-app-group

ツールバーのグループ化、オプションの CanvasTable ヘッダーにあるグループ化項目、Entity Preset の永続化、Service の record-groups リクエスト、レコードの groupFilter、CanvasTable のグループ化表示を、ひとつの統合された機能として扱います。

この Skill は、利用側の契約とグループ化のセマンティクスを担います。関連する Skill は、それぞれの実装領域を担います。

この機能は、デスクトップ／タブレット向けの表示です。標準のスマートフォン／phone カード一覧には、分组トリガー、GroupTableComponent、グループ化された CanvasTable、グループ化されたリーフナビゲーションは表示しません。デスクトップの Preset に適用済みのグループがある場合は、phone View が通常のグループ化されていないレコードをリクエストする間も、その保存済み／ドラフト状態を維持します。幅が変わったことだけを理由に Preset をクリアしないでください。

ワークフロー

1. ホストのパッケージマネージャー、正規化されたランタイムスキーマ、権限ゲート、Preset のフック／ルート、レコードのライフサイクル、既存の CanvasTable 統合、およびテストを調査します。
2. @qfei-design/make-app-group@^0.1.0 をインストールします。最初に package.ai.json を読み、package.ai.json.readOrder を解析して、宣言されたすべてのファイルを順番に読み込みます。公開エクスポートと styles.css のみをインポートし、コピーされた UI モデル、パネル、スタイル、またはドラッグ動作は削除します。
3. @qfei-design/canvas-table がインストールされていることを確認します。canvas-table-integration を使用してインストール済みパッケージのドキュメントを読み、GroupTableComponent、group:load、group:data:load、setGroup、setData、および markGroupPageLoadFailed が公開されていることを確認します。
4. キーが空でなく、capabilities.groupable === true の正規化されたランタイムフィールドからグループ化候補を作成します。表示列、サンプル行、ローカル DSL、フィールド型の許可リストを正とする情報源にしてはいけません。デスクトップ／タブレットのホストコンポーネントアダプターでは、各グループ化フィールドの選択肢の前にデフォルトの Make フィールド型アイコン を表示します。並べ替え方向やその他の選択肢には装飾を付けません。
5. 順序付きの { fieldKey, order }[] のみをグループ化リストの値として使用します。これを Entity Preset の group に保存し、一意なフィールドは最大3つまでにします。
6. 権限を考慮したオブジェクトコンテキストを確立します。スキーマと Entity Preset を読み込み、保存済みのグループをサニタイズしてから、通常レコードまたはグループ化レコードの読み込みを選択します。
7. パッケージの RecordGroupPanel、useRecordGroupController、ホストコンポーネントアダプター、および安定した resetKey を使い、クリック／押下で開く、制御されたホストの Popover／Drawer／Modal を1つ使用します。ポータル化／テレポートされたすべての子ポップアップを外側のインタラクション境界の一部として扱います。ホバー、ポインターの離脱、ブラー、子の値選択、または子オーバーレイのクローズによって閉じてはいけません。
8. onConfirm では { group } のみを保存し、同期的な onApplied で適用済みグループ状態を置き換えます。別のデータライフサイクルを設け、オブジェクトコンテキストと適用済みのフィルター／並べ替え／グループに反応させます。必ず onApplyError を指定します。
9. 書き込み可能なリストが make-app-actions を使用する場合、正常に適用されたグループの世代を引き渡し、アクションによる選択のクリアと、保留中の事前チェック／送信処理の無効化を行います。ドラフトの編集、キャンセル、保存／適用の失敗時には、現在のアクション選択を維持します。
10. Service では、厳格なトランスポートパーサーで未加工の Preset とクエリ入力を解析し、現在のランタイムスキーマに照らしてグループフィールドを検証してから、順序付きのグループ値を Make Data に転送します。寛容なサニタイズは、保存済み／上流からの読み取りに限って使用します。
11. 適用済みグループが空の場合は通常のレコードモードを使用し、Data API の group は省略します。適用済みグループが空でない場合は、まずルートグループページをリクエストしてから、GroupTableComponent を初期化または更新します。
12. 初期グループフィルターと選択されたグループパスの条件から groupFilter を組み立てます。バックエンドの DNF 式ルールを使用します。複雑な式を手作業で連結してはいけません。
13. CanvasTable の group:load を残りのグループレベルに接続し、group:data:load を完全なグループパスの groupFilter を用いた通常レコードの読み込みに接続します。
14. テスト用リファレンスに記載されたモデル、UI、Preset、Service、groupFilter、CanvasTable、権限、並行処理、古いリクエスト、および失敗ページのテストを追加します。

トピックの参照先一覧

タスク／トピック	参照先
グループ値、機能の提供元、Lookup のサポート、group: [] のセマンティクス	references/group-model.md
パッケージ UI、dnd-kit、ドラフトのライフサイクル、openWithField、スタイル	references/ui-and-drag.md
プリセットのハイドレーション、適用前の保存、グループデータのタイミング、古いリクエスト	references/preset-and-data-flow.md
CEL リテラルの処理、DNF への追加、null と Lookup のパス条件	references/group-filter-expression.md
UI-Service のルート、Make Data のグループ化モード、検証とペイロード	references/service-contract.md
CanvasTable のグループイベント、ルート／子／リーフの読み込み、レンダリングのリセット	references/canvas-table-flow.md
TDD、統合チェック、リグレッション、準備状況	references/testing-and-pitfalls.md
ツールバーの配置とオブジェクトリストのレイアウト	makeui を使用してください
CanvasTable の構築とヘッダーメニューの仕組み	canvas-table-integration を使用してください
サービスのルート／アダプターコードと境界ログ	make-app-service を使用してください
オブジェクト／リストのアクセス制御と権限ゲート	make-app-permission を使用してください
グループ化されたレコードの選択アクションと一括編集	make-app-actions を使用してください
高度なフィルターの式のセマンティクス	make-app-filter を使用してください。CEL を生成する場合は makedsl のフィルターリファレンスを参照してください
レコードの並べ替えとテーブルヘッダーの昇順／降順の動作	make-app-sort を使用してください

必須の不変条件

• グループ化は、要求されるか、すでに存在するまでは任意です。デスクトップ／タブレットでは、対象に含めた後、ツールバーでのグループ化、Preset の永続化、Service のコントラクト、グループ化された CanvasTable の描画、グループ化されたリーフのページネーションをまとめて実装してください。
• 携帯電話／phone の標準リストでは、グループ化コントロールとグループ化された CanvasTable／GroupTableComponent を非表示にし、描画もしません。phone のレコードクエリでは通常の records モードを使用し、保存済みのデスクトップ／タブレットのグループ Preset を変更せずに、group／groupFilter を省略してください。
• 順序付きの { fieldKey, order }[] のみを使用してください。旧形式の groupFieldKey、field、sort、方向の別名、マップオブジェクト、重複、未知のプロパティ、3 件を超えるエントリは拒否してください。
• Data API のグループ項目に指定できるのは fieldKey と order のみです。グループ化では、空文字列を含め、properties は常に無効です。
• 配列の順序が階層の契約です。インデックス 0 はルートグループ、インデックス 1 は第 2 階層、インデックス 2 は第 3 階層です。
• 正規化されたランタイムスキーマに空でないキーがあり、capabilities.groupable === true の場合に限り、フィールドをグループ化できます。UI または Preset に古い値が含まれていても、Service が最終的な判断を行います。
• プラットフォームのガイダンスで Make.Field.Lookup を一律に無効化しないでください。Lookup のグループ化サポートは、ランタイムスキーマの capability とバックエンドのリレーションルールによって決まります。プロジェクトで一時的な V1 ポリシーを追加してもかまいませんが、この Skill ではプラットフォームルールとして定めないでください。
• 適用済みのグループとパネルの下書きは分けてください。編集、ドラッグ、追加、削除、クリア、実際の外側クリック、子オーバーレイとの操作、ヘッダーの openWithField では、確定前にグループやレコードをリクエストしてはなりません。
• 外側のグループ化オーバーレイは制御対象とし、明示的なクリック／押下でのみ開きます。ホバーやフォーカスでは開かないでください。確定が成功した後、または実際の外側ポインター操作が確認された後に閉じてください。ポータル／テレポート経由で描画される Select、ピッカー、メニュー、ツールチップ、ポップオーバー、ドラッグオーバーレイは、引き続き管理対象の操作境界内にあるものとし、グループ化パネルを閉じてはなりません。
• パッケージの useRecordGroupController を、resetKey、onConfirm、同期的な onApplied、必須の onApplyError とともに使用してください。グループデータのリクエストを onConfirm や onApplied に置かないでください。
• 適用前に保存してください。Preset の書き込みは疎にし、クリア時は Preset に { group: [] } を設定してください。filter、sort、group が互いを上書きしてはなりません。
• Data API の records モードでは、group を省略するか null にします。Data API の group: [] は無効であり、グループ化されたリーフレコードのリクエストに使用してはなりません。
• グループ化モードのリクエストでは fields と通常の sort を省略してください。Make Data はグループ化モードではこれらを無視します。リーフレコードのリクエストは通常の records モードに戻し、fields、filter、groupFilter、sort、pagination を含めることができます。
• スキーマ／Preset の読み込みとアクセスチェックが、最初のレコードまたはグループのリクエストを制御します。エンティティまたは権限が変更された場合、以前の世代、パネル、ヘッダーメニュー、適用済み状態、グループキャッシュ、リーフキャッシュ、テーブルクエリコンテキストを無効化してください。
• groupFilter は filter から独立しています。1 つの式にまとめないでください。バックエンドは両者を AND 関係として適用します。
• 既存の OR 式にグループパス条件を追加する場合は、DNF を維持してください。バックエンドが解析できないネスト式を生成するのではなく、トップレベルの OR 分岐それぞれに新しい条件を追加してください。
• グループ化されたリーフページの読み込みが失敗またはキャンセルされた場合は、markGroupPageLoadFailed(groupValue, page) を呼び出し、CanvasTable がそのページを再試行できるようにしてください。
• 製品でグループ化された編集のライフサイクルを明示的に定義し、テストしない限り、Grouped V1 ではセル編集を無効として扱ってください。
• 書き込み可能なグループ化レコードリストでは、デフォルトの make-app-actions 選択ワークフローを使用できます。CanvasTable 1.3.1 では、GroupTableComponent は Shift キーによる範囲選択をサポートしません。ホスト側で模倣しないでください。
• このアクションワークフローを使用する場合、適用に成功したグループ世代のみが選択をクリアし、保留中のアクション処理を無効化します。グループの下書き、キャンセル、検証／Preset の失敗、グループクエリの失敗では、選択状態を維持してください。
• UI-Service アダプターと Service のルート／アダプターに、開始、成功、失敗、古い結果の各分岐について、安全な境界ログを追加してください。Cookie、トークン、シークレット、Authorization、完全な式、レコードのペイロードは決してログに記録しないでください。

ハンドオフ

• makeuiとの連携：デスクトップ／タブレットでは、フィルターの後、ソートの前にオプションのグループトリガーを配置します。標準のスマートフォン用ビューではこれを非表示にし、通常のレコードカードを使用します。このスキルはグループ動作と状態を担当します。
• canvas-table-integrationとの連携：GroupTableComponentの構築とCanvasTableの公開APIの仕組みは同スキルが担当します。このスキルは、何をいつリクエストするか、およびグループ化の結果をテーブルに反映する方法を担当します。
• make-app-serviceとの連携：このスキルはグループクエリとPresetのセマンティクスを定義します。Serviceは厳密な解析、ルート、Makeアダプター、スキーマ機能の検証、ログ、テストを担当します。
• make-app-permissionとの連携：アクセス・ポリシーは同スキルが担当します。このスキルでは、権限の有効化／無効化を、グループリクエストを無効にするオブジェクトコンテキストの遷移として扱います。
• make-app-filterとの連携：フィルターとグループは式のセマンティクスを共有しますが、別々のリクエストフィールドを使用します。フィルターパネルの状態はfilterとして永続化され、グループ化パスの状態は一時的なもので、groupFilterとして送信されます。
• make-app-sortとの連携：ソートとグループは同じEntity Presetライフサイクルを共有しますが、各ディメンションは独立して更新されます。ソートが適用されるのは通常のレコードとグループ化されたリーフレコードのみで、グループ化モードのリクエストには適用されません。
• make-app-actionsとの連携：書き込み可能なグループ化リストでアクションワークフローを使用する場合に限り、正常に適用されたグループ生成を引き渡します。これにより、アクション側で選択をクリアし、保留中の処理を無効化できます。ドラフトと失敗の経路では現在の選択が維持されます。このスキルはCanvasTableの選択イベントを発行しません。