canvas-table-integration

canvas-table-integration

このスキルは、@qfei-design/canvas-table のコンシューマー側の統合にのみ使用してください。Ant Design Table、Arco Table、TDesign Table、ネイティブ HTML テーブル、その他のテーブル実装は、プロダクトのテーブルとしてサポートしていません。

このスキルには、2 つの基本トラックと 1 つの任意の拡張機能があります。

• トラック A（基本）：Make を使用しないローカル／仮想テーブル、公開 API、行ヘッドのアクション、任意の選択／ドラッグ／サマリー、軽量なキャンバス操作。
• トラック C（基本）：Make のスキーマ駆動カラム、apps/ui/src/lib/make-field-types.ts またはホスト側の同等の場所にある共有ホストフィールド表示レジストリ、純粋な値の正規化、フィールドレンダラー、オーバーフロー時のみのツールチップ。
• トラック B（拡張）：customEdit、制御されたコミット、ポップアップの所有権、ホスト側のフィールドエディター、ロールバックによって、選択した基本トラックに重ねて適用するセル編集。

すべての Make スキーマテーブルにはトラック C を基本として選択してください。カラムが Make スキーマ駆動ではない場合に限り、トラック A を選択してください。編集が明示的に求められている場合、またはすでに確立されている場合にのみ、トラック B を追加してください。トラック B が選択した表示ベースに取って代わることはありません。

トラック B の重要なルール：CanvasTable のすべてのセル編集の実装は、references/make-cell-edit-defaults.md に従ってトラック B を適用する必要があります。ポップアップを使用しないエディターでは、CanvasTable のアクティブな編集枠線のみを残してください。内部コントロールはセル全体に広げ、枠線なしにする必要があります。ポップアップの即時表示、スクロール後の位置調整、正規化された値、変更のない値の保存スキップのいずれかが欠けている場合、準備完了とは見なせません。

クイックスタート

1. これはテーブルライブラリの保守ではなく、コンシューマー側のテーブル連携であることを確認します。
2. パッケージのインストールを確認し、以下の必須順序でパッケージの AI ドキュメントを読みます。ビジネス行の色を選択状態やホバー状態と組み合わせる連携では、公開されている @qfei-design/canvas-table@^1.3.1 の仕様が必要です。
3. ベースとして Track A または Track C を選びます。必要に応じて編集機能を強化するために Track B を追加します。編集可能な Make スキーマテーブルには、Track C と Track B を使用します。
4. Make スキーマテーブルでは、テーブルを初期化する前にスキーマフィールドを読み込み、正規化します。正規化したフィールドタイプ、スキーマの field.properties、共有フィールドタイプレジストリから IColumn[] とレンダラーを作成します。デスクトップ／タブレットのフィールドヘッダーには、公開 prefixRender API を使用してデフォルトの Lucide タイプアイコンも表示します。正確なマッピングについては、makeui のフィールドタイプアイコン仕様を参照してください。
5. トピックマップから、ベーストラックのリファレンスのみを読みます。編集が対象範囲に含まれる場合は、Track B のリファレンスも読みます。
6. 利用可能な場合は、パッケージのレシピ／サンプルを出発点にし、プロジェクト固有の変更を最小限に抑えて適用します。
7. ユーザーが明示的に無効化しない限り、テーブル行のデフォルト機能を有効にします。showSN の連番と、bodyRowHeadSuffixOptions によるホバー時に表示される詳細を開くアクションを設定します。
8. 書き込み可能な Make レコードリストでは、複数選択を有効にし、デフォルトの編集／削除／一括編集アクションのワークフローを make-app-actions に接続します。明示的に読み取り専用とされたリストのみ、これを無効にします。
9. CanvasTable 1.3.1 では、ビジネス行色の仕様が公開されています。明示的に指定した setRowColors／rowStyleOptions の色は選択状態やホバー状態よりも優先して表示され、clearRowColors は元の行スタイルまたは組み込みの背景色に戻します。この機能を使用する前に ^1.3.1 を解決してください。古いパッケージの描画順序を、ホスト側の CSS やプライベートインポートで修正してはいけません。
10. Make スキーマテーブルでは、プラットフォームのフィールドレンダラーのデフォルトを適用します。テキストを含むオーバーフローには省略記号を表示します。ツールチップは、省略記号付きのオーバーフローまたは非表示の +N コンテンツに対してのみデフォルトで有効にします。ユーザーから要求されるのを待たずに設定してください。
11. オブジェクト／エンティティ／スキーマのキーが変わったら、テーブルの操作状態とスクロール位置をリセットします。前のオブジェクトの水平または垂直スクロール位置を、次のオブジェクトに引き継いではいけません。
12. テーブルの初期化を行数から独立させます。コンテナーのサイズとスキーマ／列の準備ができたらテーブルを作成し、ローカルモードでは最新の行を setData(latestRows) で適用します。仮想モードでは、インストール済みの公開ドキュメントに基づいてページ専用または ID 対応のコールバックを選び、そのページ／リクエストの仕様を維持します。行が空でも有効な状態として、ヘッダーと空状態を引き続きレンダリングする必要があります。
13. 大量データ、高速スクロール、またはスクロールバーのドラッグを伴う仮想読み込みでは、references/virtual-table-patterns.md に従います。インストール済み仕様の選択、リクエスト ID 管理、上限付きスケジューリング、古いリクエストのキャンセル、保留中ページの解放、合計件数／ページのアトミックな書き込み、キャッシュ上限は、この方式で必須となる要件です。
14. Track B が対象範囲に含まれる場合は、完了前に必須のセル編集標準を確認します。標準に準拠しないセルエディターは、部分的な成果としてもリリースできません。
15. ユーザーが現時点で明示的に必要としている機能のみを追加します。ページネーション、ソート、グループ化、セル編集は引き続きオプトインです。Make レコードリストの選択アクションは、make-app-actions によるものがデフォルトです。
16. テーブルヘッダーのソートが要求された場合、この Skill は、ドキュメント化されたヘッダーメニュー／サフィックスの仕組みにのみ使用します。ソート動作、openWithField、Preset、レコードのタイミングについては make-app-sort に接続します。
17. Make レコードリストのグループ化が要求された場合、この Skill は、GroupTableComponent の公開 API の仕組みにのみ使用します。グループ化動作、Preset、record-groups、groupFilter、リーフページのタイミングについては make-app-group に接続します。
18. 完了前に、関連する落とし穴のリファレンスを読み、具体的なテーブルの処理経路を 1 つ検証します。

このスキルを使用しない場合

• @qfei-design/canvas-table の公開
• テーブルライブラリ自体の編集
• @qfei-design/canvas-table の代わりに、別の製品テーブル実装を生成または維持すること
• テーブルライブラリのリポジトリ内にある package.ai.json、recipes.json、サンプル、ドキュメントの保守
• プライベート npm レジストリの設定
• グループ化テーブルのアーキテクチャをデフォルトの回答として扱うこと
• すでにエディター／コンポーネントシステムがあるプロジェクトに、新しい UI コンポーネントライブラリを無理に導入すること
• Make DSL YAML の設計または生成。スキーマモデリングには makedsl を使用してください
• Service ルート、サーバー切断処理、下流のキャンセルアダプターの設計。make-app-service を使用してください

事前確認

コードを編集する前に、次のことを行います。

1. 現在のプロジェクトに @qfei-design/canvas-table がインストールされていることを確認します。
2. package.json がない場合は、処理を中止し、現在のディレクトリが npm パッケージではないことをユーザーに伝えます。
3. パッケージがない場合は、ロックファイルからパッケージマネージャーを特定し、続行する前にインストールします。
   • pnpm-lock.yaml：
     • Make App：新しい App または明示的なランタイム移行の場合は、まず make-app-runtime のベースライン "packageManager": "[email protected]"、Node.js 22.20.0、Corepack 0.34.0 を確認してから、corepack pnpm add @qfei-design/canvas-table を実行します。既存の Make App では、宣言済みのランタイムを維持し、Corepack を使って宣言済みの pnpm バージョンを解決します。CanvasTable を追加するだけのためにランタイムを移行しないでください。
     • Make App 以外の pnpm プロジェクト：pnpm add @qfei-design/canvas-table を実行し、プロジェクト既存のパッケージマネージャーのワークフローを維持します。この連携だけを目的に Corepack を導入しないでください。
   • yarn.lock → yarn add @qfei-design/canvas-table
   • package-lock.json → npm install @qfei-design/canvas-table
4. ロックファイルがない場合：
   • Make App：新しい App または明示的なランタイム移行では、まず make-app-runtime のベースラインを確立してから、corepack pnpm add @qfei-design/canvas-table を実行します。ロックファイルがない既存の Make App では処理を中止し、パッケージマネージャー、ワークスペース、CI／インストールのワークフローの調整を make-app-runtime に引き継ぎます。pnpm を前提としたり、ロックファイルを生成したり、CanvasTable を追加するだけのためにランタイムを移行したりしないでください。
   • Make App 以外のプロジェクト：デフォルトで npm install @qfei-design/canvas-table を実行します。
5. インストールに失敗した場合は、処理を中止し、コマンドとエラーを報告します。

一貫して @qfei-design/canvas-table を使用してください。既存のコードベースで別のパッケージ名が使われている場合は、処理を中止し、コンシューマーアプリの依存関係を変更する前に確認を求めてください。

既存の Make のレコード一覧で別のテーブルコンポーネントが使われていても、想定される連携先は引き続き @qfei-design/canvas-table です。ユーザーがこのページを canvas-table の対象外だと明示した場合を除き、UI ライブラリのテーブルをメインのレコードテーブルとして維持しないでください。

必須の読み込み手順

1. インストール済みパッケージのルート、または package.json の名前が @qfei-design/canvas-table であるソースパッケージのルートを特定します。
2. まず <package-root>/package.ai.json を読み込みます。
3. package.ai.json.readOrder を解析し、各エントリーをパッケージルートを基準に解決して、宣言されたファイルがすべて存在することを確認します。
4. すでに読み込んだ package.ai.json のエントリーを除き、宣言された順序で残りのエントリーを読み込みます。

package.ai.json.readOrder を信頼できる唯一の情報源とします。docs/、examples/、モノレポのフォルダー名、その他のパッケージ内部のドキュメントパスをハードコードしないでください。宣言されたファイルが見つからない場合は、内部ソースから推測せず、正確なパスとパッケージのバージョンを報告してください。

トピック参照マップ

タスク／トピック	参照先
公開プロパティ、メソッド、イベント、セットアップ、クリーンアップ	references/core-props-methods-events.md
行ヘッダーの連番または詳細を開くアクション	references/row-head-action-patterns.md
レコード一覧のデフォルト選択、編集／削除／一括編集アクションの作成	make-app-actions を使用
仮想読み込み、ページネーション対応のバックエンド連携、大量データの高速スクロール、またはスクロールバーのドラッグ	references/virtual-table-patterns.md
スキーマ／メタから IColumn[] への変換	references/column-patterns.md
通常のテーブルヘッダーとグループ化されたテーブルヘッダーの前に表示するデフォルトの Make フィールド型アイコン	makeui のフィールド型アイコンの仕様とreferences/column-patterns.md
クリック可能なセルのカスタムシェイプ	references/shape-render-patterns.md
トラック A の注意点	references/common-pitfalls.md
セル編集の仕様	references/edit-contract.md
ホスト側の編集アーキテクチャ	references/edit-host-architecture.md
編集のライフサイクル、位置指定、閉じる／確定／ロールバック	references/edit-interaction-lifecycle.md
プラットフォーム Make の編集可能セルのデフォルト	references/make-cell-edit-defaults.md
フィールドエディターのマッピング	references/field-editor-patterns.md
ホストコンポーネントの選択	references/editor-component-selection.md
添付ファイルエディターの連携	references/attachment-editor-patterns.md
トラック B の注意点	references/edit-common-pitfalls.md
Make フィールドの表示	references/make-field-display-patterns.md
下流で実証済みの使用方法と未検証の領域	references/validated-usage-notes.md
トラックのワークフロー、機能チェックリスト、出力テンプレート	references/track-workflows.md
テーブルヘッダーの昇順／降順動作、共有ソートパネル、Preset とレコードのソート	make-app-sort を使用
Make のレコードグループ化、Preset グループ、record-groups、groupFilter、グループ化されたリーフのページネーション	make-app-group を使用
サービスルートのキャンセル、サーバー切断の処理、下流への AbortSignal の伝播	make-app-service を使用

ベースのトラック A の場合

必要に応じて参照してください。

• references/core-props-methods-events.md
• ボディ行ヘッダー／連番領域にアイコンまたはアクションを追加する場合は、references/row-head-action-patterns.md
• ページネーション対応の仮想読み込みを使用する場合、特に大量データ、高速スクロール、またはスクロールバーのドラッグに対応する場合は、references/virtual-table-patterns.md
• 列を構成する場合は、references/column-patterns.md
• クリック可能なセルのカスタムコンテンツを追加する場合は、references/shape-render-patterns.md
• 変更を確定する前に、references/common-pitfalls.md

ベースのトラック C の場合

以下を参照してください。

• references/make-field-display-patterns.md
• キャンバスシェイプを追加する場合は、references/shape-render-patterns.md
• フィールドスキーマから IColumn[] を導出する場合は、references/column-patterns.md
• 変更を確定する前に、references/common-pitfalls.md

セル編集にトラック B を追加する場合

以下の順に参照してください。

1. 選択したベーストラックの参照資料。Make スキーマの編集可能テーブルでは、トラック C の表示ベースラインを維持する必要があります
2. package.ai.json.readOrder で宣言されたパッケージレベルのセル編集ドキュメント
3. references/edit-contract.md
4. references/edit-host-architecture.md
5. references/edit-interaction-lifecycle.md
6. references/make-cell-edit-defaults.md
7. references/field-editor-patterns.md
8. references/editor-component-selection.md
9. 添付ファイルフィールドが対象範囲に含まれる場合は、references/attachment-editor-patterns.md
10. 変更を確定する前に、references/edit-common-pitfalls.md

必須のパッケージファイルが見つからない場合は、作業を中止し、見つからないファイルを正確にユーザーに伝えてください。

トラックの構成

• トラック A とトラック C は、相互に排他的な表示ベースです。
• トラック B は拡張レイヤーであり、置き換え用のベースではありません。
• Make 以外の編集可能なテーブルには、トラック A とトラック B を使用します。
• Make スキーマの編集可能なテーブルには、トラック C とトラック B を使用します。これにより、編集機能を追加しながら、表示の正規化とレンダラーの動作を維持できます。
• 詳細なワークフロー、機能チェックリスト、フィールドのグループ分けは、references/track-workflows.md と references/make-field-display-patterns.md に記載されています。

安全ルールとデフォルト

以下を安全ルールとして扱います。

• ブラウザー／クライアント専用です。SSR 中にインスタンスを作成しないでください
• 幅と高さを明示した、実際の DOM コンテナーを使用してください
• ドキュメントに記載された公開 API のみを使用してください
• src または dist からインポートしないでください
• 製品テーブルには @qfei-design/canvas-table を使用してください。UI ライブラリのテーブルで代用しないでください
• globalEventBus.onWithNamespace(...) の名前空間キーには table.tableId を使用してください
• アンマウント時／クリーンアップ時にテーブルインスタンスを破棄してください
• オブジェクト／エンティティ／スキーマのルートを切り替えるときは、スクロール位置と一時的なテーブル状態をリセットしてください。/objects/:objectKey で同じ React コンポーネントを再利用できるのは、テーブルにその識別子をキーとして設定する場合、または識別子の変更時に canvas-table インスタンス／状態を明示的にリセットする場合に限ります
• 生の meta をテーブルランタイムに直接渡さないでください
• テーブルを作成する前に、meta を IColumn[] に変換してください
• Make のスキーマテーブルでは、スキーマの読み込みを待つ間に、汎用のプレースホルダー列や行キーから推定した列でテーブルを作成しないでください
• テーブル作成の条件に records.length、rows.length、または業務上の合計値を使用しないでください。行が空でも有効なテーブル状態です。ヘッダーを表示したままにし、setData([]) の後に組み込みの空状態を表示してください
• CanvasTable インスタンスの準備より先に行が届く可能性がある場合は、最新の行を保存し、インスタンス作成直後に setData(latestRows) を呼び出してください。tableRef.current が null であるために、早期のデータ更新が失われないようにしてください
• 数値の解析失敗を NaN、Infinity、または例外テキストとして表示しないでください。キャンバスに描画する前に、空の表示値に正規化してください
• 書式設定済みの通貨値やパーセント値を、通常のバックエンド契約として受け入れないでください。¥、￥、%、または桁区切りを含む文字列は依存関係の不備です。API で使用可能な値として黙って扱うのではなく、- を表示するか、データ契約の問題を明示してください
• Make のスキーマテーブルでは、生成した列／編集設定に正規化済みの field.properties を保持し、レンダラーとエディターから Number.precision、Date.format、DateRange.begin/end、Currency.symbol/decimalPlaces/useGrouping、Percent.decimalPlaces、File.maxCount、および複数識別子の maxCount を利用できるようにしてください
• 数値、通貨、パーセントのセルエディターでは、生の小数入力テキストを保持し、解析と確定の前に Number.precision、Currency.decimalPlaces、または Percent.decimalPlaces を適用してください。小数桁数の超過時はエディターをアクティブなままにし、ツールチップまたは外部の検証領域に 最多保留 N 位小数 を表示し、保存 API を呼び出さないでください。ホストプロジェクトに明記されている場合を除き、黙って丸めることは禁止です
• 数値セルエディターでは、無効な IME 変換中も最後に確定した数字を保持し、未確定の IME 候補を選択するために Enter を押したときにセルを確定しないでください。references/field-editor-patterns.md に記載された数値エディターの動作と検証ガイダンスに従ってください
• ビジュアルな canvas-table ホスト、またはパッケージが作成するフォーカス可能なキャンバスを含む可能性のある祖先に、aria-hidden や inert を設定しないでください
• スクリーンリーダー用の代替テーブルが必要な場合は、視覚的に隠した別の構造として配置し、ビジュアルホストにはそれ自体の非隠しアクセシブルラベルを付けてください
• ページネーションはオプトインです。ユーザーからページネーション、仮想読み込み、またはページネーション対応バックエンドとの統合を明示的に求められない限り、表示されるページネーションコントロール、ページサイズセレクター、ページ状態、ページクエリパラメーター、合計件数の処理、ページネーション付きフェッチロジック、virtualOptions、または data:load の配線を追加しないでください
• インストール済みドキュメントで仮想ページのリクエストコンテキストが公開されている場合は、それを同期的に確保し、同じリクエストをネットワークシグナルと setData／setVirtualPageData または markPageLoadFailed に渡してください。旧式のページのみの方法を使用できるのは、それがインストール済みの公開契約である場合に限ります
• 仮想読み込みの失敗やキャンセル時には、インストール済みパッケージのドキュメントに記載された公開 API を使用して、パッケージの保留中ページマーカーを解除してください。大量データや高速スクロールの経路では、一時的に表示されたすべてのビューポートページを即時に要求するのではなく、上限のあるホストスケジューラーも使用してください
• ソートはオプトインです。要求された場合は、ホストがドキュメントに従って実装した CanvasTable ヘッダーメニュー／サフィックス API を通じてのみヘッダーの昇順／降順を表示し、その後、共有の make-app-sort コントローラーを呼び出してください。レコードをローカルでソートしたり、独自のヘッダーソート状態を保持したり、ヘッダー操作からレコードを直接呼び出したりしないでください
• グループ化はオプトインです。Make のレコード一覧では、パッケージパネル、Preset、Service、groupFilter、およびレコードのタイミングに make-app-group を使用してください。この Skill では GroupTableComponent のインスタンスを作成し、group:load／group:data:load を配線できますが、グループ化の意味を独自に定義してはなりません
• Make のレコード操作はデフォルトです。この Skill では、公開されている選択状態のスナップショット、clearSelection、サポートされている Shift／全選択の動作、および行の色を配線します。操作状態、権限、事前チェック、一括操作モーダル、変更のタイミングは make-app-actions が管理します。CanvasTable 1.3.1 の契約では、GroupTableComponent は Shift による範囲選択をサポートしません。ホスト側でこれを模倣しないでください
• CanvasTable 1.3.1 における行色の意味上の優先順位とクリーンアップを、レコード操作に関する最低限の契約として扱ってください。業務上の行色は選択状態やホバーよりも優先して表示され、コマンドの色はドキュメントに記載された clearRowColors(rowKeys) で削除する必要があります。setRowColors(rowKeys, undefined) をクリーンアップの代替手段として使用しないでください。ホスト側でキャンバスの内部をオーバーライドするのではなく、@qfei-design/canvas-table@^1.3.1 を必須としてください
• 通常の Make CanvasTableComponent レコード一覧では、1 回の Shift による範囲選択操作で選択できるレコードは最大 200 件です。上限の適用には、インストール済みの公開選択契約のみを使用してください。その機能がない場合は、ホスト側でキーボードアンカー、範囲の展開、または非公開の選択状態を実装せず、ブロッカーとして報告してください

詳細なワークフローとメンテナンスの参考資料

• トラックのワークフロー、機能チェックリスト、回避項目、延期されたトピック、最終回答のテンプレートについては、references/track-workflows.md をお読みください。
• 現在のプロジェクトやパッケージのドキュメントで明確に扱われていない機能を使用する前に、references/validated-usage-notes.md をお読みください。検証済みの下流パターンと、十分に実証されていないパッケージ機能を区別できます。