make-app-sort

make-app-sort

ツールバーの並べ替え、CanvasTable のヘッダーの並べ替え、Entity Preset の永続化、Service レコードの sort リクエストを、統合された 1 つの機能として扱います。この Skill はコンシューマーとの契約と並べ替えのセマンティクスを担い、関連する Skill はそれぞれの実装領域を担います。

この機能のコントロールはデスクトップ／タブレットにのみ表示します。標準的なスマートフォン／phone カードリストには、並べ替えトリガーも CanvasTable のヘッダーアクションも表示しません。すでに適用された並べ替えは、画面幅の切り替えでデータの順序が予期せず変わらないよう、共有の通常レコードクエリに引き続き適用できます。ただし、ユーザーからモバイル向けのカスタム並べ替え機能を明示的に求められない限り、phone ユーザーは並べ替え状態を編集できません。

ワークフロー

1. ホストのパッケージマネージャー、正規化済みランタイムスキーマ、権限ゲート、Preset フック／ルート、レコードのリクエストライフサイクル、CanvasTable ヘッダー API、テストを確認します。
2. @qfei-design/make-app-sort@^0.1.0 をインストールします。その package.ai.json とすべての package.ai.json.readOrder エントリを読み、公開エクスポートと styles.css のみをインポートして、コピーされた UI モデル、パネル、スタイル、ドラッグ動作を削除します。
3. 候補は、キーが空でなく、capabilities.sortable === true の正規化済みランタイムフィールドのみから作成します。デスクトップ／タブレットのホストコンポーネントアダプターでは、各並べ替えフィールドのオプションの前に既定の Make フィールドタイプアイコン を表示します。並べ替え方向やその他のオプションにはアイコンを付けません。
4. 権限を考慮したオブジェクトコンテキストを確立します。スキーマと Entity Preset を読み込み、保存済みの並べ替えをサニタイズしてから、最初のレコードリクエストを許可します。
5. ホストが所有する外側の Popover を 1 つ使用し、パッケージの RecordSortPanel、useRecordSortController、ホストの公開コンポーネントアダプター、エンティティまたはアクセスコンテキストが変わるたびに変更される安定した resetKey トークンを組み合わせます。
6. CanvasTable の昇順／降順アクションを、openWithField(fieldKey, order?) を通じて同じコントローラーに接続します。ヘッダーアクションが編集するのは draft のみです。
7. onConfirm では { sort } のみを永続化し、同期的な onApplied では適用済み状態を置き換えます。オブジェクトコンテキストと適用済みフィルター／並べ替えに反応するレコードライフサイクルは、別に用意します。必ず onApplyError を指定します。
8. Service では、厳密なトランスポートパーサーで生の PATCH とレコード入力を解析し、現在のランタイムスキーマに対してフィールドを検証してから、順序を保った値を Make Data に転送します。寛容なサニタイズは、保存済み／上流からの読み取りにのみ使用します。
9. 書き込み可能なリストで make-app-actions を使用する場合は、正常に適用された並べ替えの世代を引き継ぎます。これにより、新しいクエリを操作可能にする前に、アクションが選択状態をクリアし、保留中の事前チェック／送信処理を無効化します。draft の編集、キャンセル、保存／適用の失敗では、現在のアクション選択を維持します。
10. テストリファレンスに記載されたモデル、UI、ヘッダー、Preset、権限、並行処理、Service、古いリクエスト、アクション選択条件のテストを追加します。

トピックのリファレンスマップ

タスク／トピック	参照先
並べ替え値、sortable 機能、検証、サニタイズ、5 階層の制限	references/sort-model.md
パネル UI、dnd-kit、draft ライフサイクル、openWithField、スタイル	references/ui-and-drag.md
Preset のハイドレーション、適用前の保存、レコードのタイミング、古いリクエスト	references/preset-and-data-flow.md
UI-Service ルート、Make Preset アダプター、レコードの検証とペイロード	references/service-contract.md
TDD、統合チェック、リグレッション、準備状況	references/testing-and-pitfalls.md
ツールバーの配置とオブジェクトリストのレイアウト	makeui を使用
CanvasTable ヘッダーメニューとサフィックスの仕組み	canvas-table-integration を使用
Service のルート／アダプターコードと境界ログ	make-app-service を使用
オブジェクト／リストのアクセス方針と権限ゲート	make-app-permission を使用
高度なフィルターの状態と Preset のフィルター永続化	make-app-filter を使用
グループ化の状態、Preset グループ、レコードグループ、groupFilter	make-app-group を使用
書き込み可能なリストの選択アクションと適用済みクエリの無効化	make-app-actions を使用

必須の不変条件

• 並べ替えは、要求された場合またはすでに存在する場合に限り必須です。デスクトップ／タブレットでは、対象になったら、ツールバーの並べ替え、CanvasTable のヘッダー連携、Preset への永続化、レコードの並べ替えをまとめて実装します。
• スマートフォン／phone の標準リストでは、並べ替えコントロールや CanvasTable のヘッダーアクションを非表示にし、描画しません。デスクトップ用の並べ替えボタンを phone のツールバーに追加しないでください。
• { fieldKey, order }[] のみを使用します。旧形式の { field, order }、不明なキー、無効な方向、重複、5 件を超えるエントリーは拒否します。
• 配列の順序を優先順位として扱います。インデックス 0 が最優先の並べ替えです。
• フィールドを並べ替え可能とするのは、正規化済みの実行時スキーマに空でないキーがあり、capabilities.sortable === true の場合のみです。フィールド型の許可リスト、表示中のテーブル列、サンプル行、ローカル DSL を正とする情報源として使用しないでください。
• 適用済みの並べ替えとパネルのドラフトは分離します。編集、ドラッグ、追加、削除、クリア、外側のクリック、エスケープでは、確定前にレコードを照会してはいけません。
• パッケージの useRecordSortController を使用し、resetKey、onConfirm、同期的な onApplied、必須の onApplyError を指定します。レコードのリクエストを onConfirm や onApplied に含めないでください。
• 適用前に保存します。Preset の書き込みはスパース形式とし、クリア時は sort: [] を使用します。フィルター、並べ替え、グループの各ディメンションが互いに上書きされないようにします。フィルターと並べ替えの保存が重なった場合も、共有の保存状態とエラー状態を正しく維持します。
• スキーマ／Preset のハイドレーションとアクセスチェックが、最初のレコードリクエストを制御します。オブジェクトまたは権限が変更された場合は、A -> B -> A を含め、古い世代、パネル、ヘッダーメニュー、適用済み状態、テーブルのクエリーコンテキストを無効化します。
• CanvasTable のヘッダーにある昇順／降順アクションは、openWithField を通じて共有パネルのドラフトを開くか更新するだけです。確定を迂回したり、レコードを直接呼び出したりしてはいけません。
• パッケージヘルパーは UI モデル／ドラフトの動作を担います。厳密な生入力の解析は Service が担います。無効な PATCH やレコードクエリーを受け入れるために、寛容なサニタイズを使用してはいけません。
• 検索は引き続きセッション内のみとします。Entity Preset にキーワード検索を永続化しないでください。
• make-app-actions が存在する場合、選択状態をクリアして保留中のアクション作業を無効化するのは、正常に適用された並べ替え世代のみです。ドラフトの編集、パネルのキャンセル、検証エラー、Preset の保存失敗、リストクエリーの失敗では、現在のアクション選択をクリアまたは変更してはいけません。
• UI-Service アダプターと Service のルート／アダプターで、開始、成功、失敗、古い結果の各分岐について、安全な境界ログを追加します。Cookie、トークン、シークレット、Authorization、機密性の高いレコードデータ全体は、絶対にログに記録しないでください。

グループ化の境界

グループ化は make-app-group と capabilities.groupable が担います。この Skill で、グループ化 UI、record-groups ペイロード、groupFilter 式の組み立て、Preset の group 書き込みを追加してはいけません。スパース形式の並べ替え更新では、既存のグループディメンションを維持します。

ハンドオフ

• makeuiとの連携：デスクトップ／タブレットでは、任意のソートトリガーをフィルターの後、更新の前に配置します。標準のスマートフォン用ビューでは非表示にします。このスキルがソートの動作と状態を管理します。
• canvas-table-integrationとの連携：ヘッダー／メニューの仕組みはそちらが管理します。このスキルは共通ソートパネルの呼び出しを管理します。
• make-app-serviceとの連携：このスキルが契約を定義し、Serviceが厳密な解析、ルート、Makeアダプター、スキーマ機能の検証、ログ、テストを管理します。
• make-app-permissionとの連携：アクセスポリシーはそちらが管理します。このスキルでは、権限の有効化／無効化をオブジェクトコンテキストの遷移として扱い、ソートリクエストを無効化します。
• make-app-filterとの連携：フィルターとソートは1つのEntity Presetライフサイクルを共有しますが、各次元を個別に更新し、並行して保存できます。
• make-app-groupとの連携：グループ化とソートは1つのEntity Presetライフサイクルを共有しますが、各次元を個別に更新します。ソートは通常のレコードとグループ化されたリーフレコードに適用されますが、グループ化モードのrecord-groupsリクエストでは通常のソートを無視します。
• make-app-actionsとの連携：アクションワークフローを使用する書き込み可能なリストに限り、正常に適用されたソートの世代を、新しいクエリがアクション可能になる前に引き渡します。これにより、アクションで選択状態がクリアされ、保留中の処理が無効化されます。下書きと失敗の経路では選択状態を保持します。このスキルはCanvasTableの選択APIを直接操作しません。