@keenaioc/data-view 0.0.0-poc.1 → 0.2.0-alpha.8

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+歷史紀錄保留當時版本資訊；部分舊版已下架，歷史安裝／回退指令不代表仍可下載。alpha.8 的回退基準為 alpha.7。
+
+## 0.2.0-alpha.8 — 2026-09-06（公開 Alpha 測試版）
+
+- 新增：CORE-01 `presentation` 自動／表格／卡片及選擇回呼；CORE-02 `chrome: "compact"` 精簡工具列、窄版圖示與更多操作；CORE-03 精簡表頭及 `headerStart`／`headerEnd` 插槽。
+- 新增：CORE-05 `height` 控制整個 DataView 或 DataViewWorkspace；資料區扣除工具列與狀態列後使用剩餘高度，桌面、甘特、行事曆及卡片共用。既有 `viewportHeight` 保留資料区語意。
+- 修正：CORE-04／T15 虛擬分組按鈕 31px → 正式 metrics 的 28px；保留外層 8px／內層 4px。精簡介面的工具列、視圖及排程導覽採用控制項尺寸；多選與複雜輸入維持詳情編輯。
+- 修正：CORE-06 甘特桌面與手機議程同時顯示；寬窄切換優先於版面 display，日曆亦共用切換規則。
+- 不相容變更：無必要 API 或資料遷移；未傳新 props 時保留標準表頭與資料區高度模式。自動呈現依元件寬度（767px）切換；窄桌面要維持表格可明確選擇 table。
+- 需要調整：使用精簡版面的接入專案更新精確 dependency 與 CSS；不需要專案 CSS 覆蓋。不啟用依賴連動、資源負荷或自動改期。
+- 升級：`npm install --save-exact @keenaioc/data-view@0.2.0-alpha.8`，同步更新套件 CSS 與 lockfile，先驗收一個試點。
+- 設定／資料遷移：schemaVersion 維持 1，不修改資料。呈現偏好由 host 保存；既有受控 view 需自行選擇 workbench 密度。回退：還原 alpha.7 dependency／lockfile，移除新 props 後重建；保留 host 偏好備份。
+- 限制：實際瀏覽器驗收受平台網址政策阻擋，尚未完成全寬／720px／手機與甘特切回表格的操作驗收；建置及程式測試不取代此驗收。
+
+## 0.2.0-alpha.7 — 2026-09-06（Alpha）
+
+- 資料保護：加入公開資料隔離說明與打包前檢查；公開文件移除內部來源識別資訊。共用 API 不變；舊版公開內容不會因本次更新而自動消除。
+
+- 新增：T01～T19接入介面、角色與個人狀態分離、正式欄位Editor/action/quick view、穩定ID分組、手機獨立設定、同列佇列與不同列並行、workbench精確尺寸、遠端query/source/cursor/snapshot契約。
+- 修正：普通唯讀不能開卡、內部分組欄可被重新顯示、同名人員分組合併、560px寫死位移、系統值／膠囊／空白與箭頭、搜尋和收合被版面權限阻擋。
+- 移除：可見分頁與pageSize切片；表格、甘特與行事曆改連續結果。空日期與無效日期分開，排程診斷入口預設關閉。
+- 不相容變更：人員／關聯篩選與分組改永久ID；舊名称條件與收合鍵須檢查。pageSize不再作用，scheduleRows另回invalid，預設虛擬化；不自動強制切換既有密度。schemaVersion維持1。
+- 調整專案：本次共用權威來源與Lab。接入專案沒有自動升級；後續各自處理後端查詢、設定遷移與交易。
+- 升級：先 inspectViewMigration、備份 dependency/lockfile/ViewConfig/schema，以精確 alpha.7 接入測試專案；完成操作驗收才升級正式系統。原 alpha.6／alpha.7 工作合併為本版，alpha.6 未另發布。
+- 回退：還原精確alpha.5及舊lockfile／設定快照，重建發布；不撤銷業務資料。
+- 限制：完整操作驗收因瀏覽器環境政策限制而未完成；Alpha 發布與安裝驗證不取代正式業務驗收。見 KNOWN-LIMITATIONS.md。
+
+## 0.2.0-alpha.5 — 2026-09-05（公開 alpha，next）
+
+- 新增：命名視圖新增／命名／複製／刪除，同一資料來源，最多 50 個視圖；最後一個視圖不可刪。
+- 新增：每視圖儲存欄位／寬度／排序／篩選／分組收合、搜尋／分頁、桌機與手機內部捲動位置、甘特尺度／定位日期／左右捲動／分割寬度。
+- 新增：甘特左側沿用欄位 renderer、直接打勾、輸入器、權限、欄寬與固定規則；複雜輸入開啟共用詳情。
+- 新增：週／月／季／年有界連續時間窗、今天線、週末底色、完整最多三層分組收合；未排程資料留在左側。
+- 修正：移除離開元件便丟棄設定的防抖計時器；完整快照序列化、錯誤保留與重試、寫入中阻擋切換視圖。附件連結與上傳按鈕分離，避免巢狀互動元素。
+- 不相容變更：沒有必要 API／資料遷移；`DataViewConfig.location` 為選填。新增 `DataViewWorkspace`／`DataViewCollection`。命名視圖切換會結束該視圖的本次復原歷史，業務資料不變。
+- 需要調整：共用來源及 HY Data View Lab；其他 Sites 自行選擇接入，沒有自動升級。
+- 設定遷移：Lab `views:v3` 匯入 `view:v2` 或 `view:v1` 為「預設視圖」，保留舊鍵。正式接入以使用者＋資料集保存 JSON 集合；跨裝置由 host 儲存服務處理。
+- 升級：`npm install --save-exact @keenaioc/data-view@0.2.0-alpha.5`。更新 CSS、dependency 與 lockfile，先於 Lab／單一試點驗收。
+- 回退：保存集合原始快照，選出 `views.find(v => v.id === activeViewId).config` 交給舊 `DataView`；還原 alpha.2 dependency／lockfile。舊版不支援命名視圖與 location，勿讓舊版覆寫 v3 快照。回退程式不回退資料或 schema。
+- 驗收：程式測試、型別及建置另見來源驗收紀錄；實際驗證了新增視圖、直接連續打勾、跨視圖隔離、重載保留尺度／分割寬度、收合對齊、手機卡片與失敗提示。瀏覽器中途遭平台 URL 政策阻擋，後續全流程仍待驗收。本次公開 alpha 保留未驗收限制；不標記為穩定版或升級正式業務專案。
+
+
+## 0.2.0-alpha.4 — 2026-09-05（候選版，尚未發布）
+
+- 新增 Finish-to-start 依賴線與管理入口、0–365 等待天數、重複／自連／循環阻擋；關係由 host 保存。
+- 新增改期預覽與確認套用；保留後續工期／緩衝、鎖定保護、原子提交及整批復原；依賴版本與相關舊日期會再次檢查。
+- 未排程／月份外資料保留左側，月份外可定位；無日期不自動建立排程。
+- Lab 加入三筆合成依賴鏈、後續日期鎖定與版本／權限／儲存失敗情境。
+- 選填 API 增加 `ganttDependencies`、`onGanttDependencyChange`、`canManageDependencies` 與 `BatchCommit.scheduleGuard`。未啟用者不需調整；啟用前 adapter 必須完成 guard 交易驗證。schemaVersion 保持 1。
+- 進度範本、容量預測與業務工序由接入專案管理，不包含在共用引擎。
+- 升級：候選完成 Lab 驗收、正式發布後，試點專案精確固定版本並接入 guard。回退套件不撤銷已套用的日期，依賴資料由 host 保留；如要撤銷日期，需以有效的整批復原或業務稽核處理。
+
+## 0.2.0-alpha.3 — 2026-09-05（候選版，尚未發布）
+
+- 新增內容：甘特膠囊條整體拖移、開始／結束端點縮放、拖曳預覽及 Esc 取消；整條游標為移動，端點為左右調整。支援左右鍵移動目前聚焦的整條或端點。可設定標題／日期來源、自訂色或單選欄位選項色、標題與天數顯示、僅計算工作天。
+- 日期規則：日曆天含首尾；整條拖移保留日曆天數。工作天模式只計週一至週五，移動時保留工作天天數並調整週末，日曆跨度可能改變；不包含國定假日。端點至少保留一天，日期時間欄位保留原本時間與時區文字。
+- 寫入規則：沿用 onBatchCommit，reason 為 edit，每次提供兩個日期格以同時核對兩端前值；不另建排程資料。需要兩個不同且可修改的 date/dateTime 欄位；任一無權限、唯讀、系統欄位或未接原子回呼時不開放拖曳。儲存失敗／衝突保留原值，成功納入既有復原／重做。
+- 修正內容：短條標題在條外顯示；進度作底色覆蓋；依自訂底色選擇深／淺文字，避免不可讀。分開移動與端點按鈕，無巢狀互動元素。
+- 不相容變更：無必要 API 或 schema 遷移；GanttMapping 新增選填設定，schemaVersion 仍為 1，舊 host 原子回呼可沿用。舊版本不會保留新增甘特設定，回退前請保存原始 ViewConfig。
+- 需要調整的專案：共用核心與 Lab 候選；其他 Sites 維持原版本。
+- 升級方式：本版尚未發布 npm；先完成 Lab 滑鼠、鍵盤與權限／失敗實際驗收，取得發布授權後才安裝精確版本。可安裝的前一版是 0.2.0-alpha.2，不含本次拖曳。
+- 回退方式：回到 data-view-v0.2.0-alpha.2 標籤或精確 npm 0.2.0-alpha.2，還原 dependency／lockfile／檢視快照並重建；不撤銷資料修改。
+- 已知限制：尚未做本次瀏覽器互動驗收；月份邊界可調整日期但不會拖曳自動換月；不含依賴線及假日曆。手機仍用清單與共用詳情編輯，沒有硬縮桌機拖曳介面。
+
+## 0.2.0-alpha.2 — 2026-09-05（公開 alpha，next）
+
+- 新增內容：表格欄尾固定「＋」及桌機／手機工具列的「新增欄位」入口；共用新增表單直接選擇 13 種可編輯欄位類型，再填名稱與選項。系統欄位由接入專案維護。
+- 修正內容：核取方塊在桌機、手機、詳情與虛擬表格可直接點擊勾選／取消，游標顯示手指，不再反覆進入編輯器；Enter／空白鍵可直接切換。沿用原寫入、權限、失敗、衝突與復原流程；舊單格回呼在儲存中阻擋同格重複提交。刪除欄位後管理面板自動選擇另一現有欄位。
+- 不相容變更：無。欄位註冊中心增加選填 toggleValue；既有資料介面與 schemaVersion 1 不變。
+- 需要調整的專案：僅共用核心與 Lab；其他正式 Sites 未升級。
+- 升級方式：`npm install --save-exact @keenaioc/data-view@0.2.0-alpha.2`；提交 dependency 與 lockfile，按 INTEGRATION.md 接入 host adapter，先驗收指定試點再重新發布該 Sites。無即時強制更新。
+- 回退方式：Lab 回到先前 alpha.1 的 Git／Sites 版本；正式專案保留原精確套件版本。無資料或設定遷移，回退不會撤銷業務資料操作。
+- 驗收與發布範圍：27 項程式端測試、型別、Lint 與建置通過；以公開 alpha 提供精確安裝版本並列出限制。完整滑鼠、鍵盤及手機觸控驗收尚未完成，不標為穩定版，也不宣稱已接上其他正式專案。已知限制見 KNOWN-LIMITATIONS.md。
+- 文件：套件內附 INTEGRATION.md、KNOWN-LIMITATIONS.md、更新／升降級說明與共用修改規則。
+
+## 0.2.0-alpha.1 — 2026-09-04（候選版，尚未發布）
+
+- 新增內容：甘特圖與行事曆的欄位映射、月份切換、跨日／跨月、進度及選項色、共用詳細資料編輯；新增／重新命名／複製／刪除欄位回呼與保護規則；原子批次修改、貼上預覽、最近 20 次成功資料操作的復原／重做；條件式整列／儲存格填色；固定右欄；三種列高；桌機固定列高虛擬捲動；方向鍵、Shift 範圍選取、Home／End、PageUp／PageDown、Tab、Enter／F2、Escape、複製／TSV 貼上及清空預覽。手機使用精簡卡片及排程清單，詳情共用欄位輸入器。
+- 修正內容：中文選項分組順序、預設固定欄保留、個人檢視寫入序列化、失效欄位引用清理、數字空值不等於零、非法日期不再使畫面崩潰；寫入入口重新檢查權限及前值。Lab 補齊獨立 TypeScript 檢查所需的 Worker 資產型別，移除未使用的型別宣告，不改儲存綁定。
+- 不相容變更：無必要 API 或 schema 遷移；`schemaVersion: 1` 新增選填欄位，舊 `onCellCommit` 仍可用。驗證修正會拒絕原先誤收的字串型數字、非法日期及無效參照 ID；adapter 必須提供符合型別的值。功能階段 V2 不代表 SemVer `2.0.0`。
+- 需要調整的專案：僅共用核心與 HY Data View Lab；其他 Sites 未升級。
+- 設定／資料遷移：無自動資料搬移。新增、複製與軟刪欄位需接入專案自行保存 schema／值；系統欄位與稽核仍由專案維護。Lab 只持久化個人檢視，新鍵 `hy-data-view-lab:view:v2`，保留舊 v1 鍵。Lab 資料與新增欄位在重載後重建。
+- 升級方式：先完成 `docs/V2-ACCEPTANCE.md` 尚未完成項目並取得發布授權。發布後才以 `npm install --save-exact @keenaioc/data-view@0.2.0-alpha.1` 更新單一測試專案及 lockfile；引用新功能前實作 `onBatchCommit`／`onFieldChange`。目前不可把這個指令當成已可下載版本。
+- 回退方式：保留 V1 的套件與檢視快照，回復 `0.1.0-alpha.1` 的 dependency／lockfile 並重建。V1 忽略 V2 的視圖、填色等新增設定；右側固定在 V1 取消固定。若需保留 V2 設定供再次升級，另存原始快照，勿讓 V1 覆寫。資料修改與 schema 修改不會因套件回退而自動撤銷，由專案自己的可逆遷移／備份處理。
+- 驗收狀態：建置、型別及程式端測試完成；瀏覽器僅完成初步桌機操作，後續因環境網址安全政策中止。未完成桌機／手機全流程驗收前不得發布。
+
+## 0.1.0-alpha.1 — 2026-09-04
+
+- 新增內容：19 種候選欄位型別的集中註冊中心；桌機表格與手機卡片；單欄／多欄排序；AND／OR 多條件篩選；最多三層分組與展開收合；欄寬調整；欄位拖曳；顯示／隱藏；固定左欄；單列／多列選取；儲存格編輯；附件回呼；分頁；搜尋；個人檢視設定；載入、空白、錯誤、無權限、唯讀、儲存失敗與衝突狀態。
+- 修正內容：多選與人員欄位在完成選取後才提交；固定左欄自動排列至左側；選項分組沿用欄位選項順序；無讀取權限的值不會透過篩選結果洩漏；桌機與手機編輯器不再同時掛載；必填驗證錯誤可直接顯示。
+- 不相容變更：無。這是第一個可驗收的 alpha 版本，尚未承諾穩定 API。
+- 需要調整的專案：只有 HY Data View Lab。其他接入專案均未修改。
+- 升級方式：`npm install --save-exact @keenaioc/data-view@0.1.0-alpha.1`，並引用 `@keenaioc/data-view/style.css`。
+- 回退方式：還原專案的 `package.json` 與 lockfile 至升級前 commit，再重新建置及發布該 Sites 專案。正式專案在 alpha 階段不得以 `latest` 或範圍版本自動升級。
+
+## 0.0.0-poc.1 — 2026-09-04
+
+- 新增內容：驗證公開 npm 套件可由另一個 Sites starter 在無 npm 登入狀態下，以精確版本安裝並完成 SSR、單一 React 與正式建置。
+- 修正內容：無。
+- 不相容變更：不適用；此版本只有跨專案引用驗證用途。
+- 需要調整的專案：無。
+- 升級方式：不要用於正式專案。
+- 回退方式：移除 POC 套件並還原 lockfile。

package/DATA-PRIVACY.md

@@ -0,0 +1,20 @@
+# 公開套件與資料隔離
+
+`@keenaioc/data-view` 是公開 npm 套件；公開的是通用程式與介面，不是接入專案的資料或內部工作內容。
+
+## 所有接入 WORK 的規則
+
+- 真實客戶、員工、案件、聯絡方式、地址、金額、排程、附件、畫面截圖、記錄、權限配置、商業公式及憑證留在原專案，不提交至共用套件、公開文件或測試場。
+- 回報共用問題時，提供通用需求與最小重現。從空白建立虛構資料，使用 `DEMO-001`、`測試人員甲` 等標示；不可只替換名字，卻保留可辨識的案號、地址、日期組合或附件網址。
+- 真實資料經各專案自己的 adapter 和後端授權取得。不得為了方便範例而寫進前端程式、預設值、測試檔、source map、錯誤文字或公開變更紀錄。
+- 欄位隱藏、分組收合、internal 與前端權限只是顯示規則。傳到瀏覽器的資料仍可能被讀取；無權限的資料應由後端排除，伺服器秘密不可送入瀏覽器。
+- 套件共用不需要集中保存各專案資料。不新增將資料、遙測或錯誤 payload 自動回傳共用維護端的機制。
+- 發布、教學或回報錯誤前，連同截圖、附件、複製文字、檢視設定中的搜尋條件及連結一起去識別化。不要把原始資料送到外部掃描服務。
+
+## 維護與發布
+
+每次整合與發布都須重新檢查實際打包內容、編譯產物、README、更新紀錄、範例及測試場。只允許共用編譯程式、型別、樣式與公開文件進入 npm；每次都要確認打包範圍，不能依賴上次的結果。
+
+來源專案提供 `check:privacy` 與發布前檢查，核對檔案清單及常見敏感字樣。自動檢查不能辨認所有私人資訊、影像或商業規則，仍須人工審閱並記錄精確發布檔案的雜湊。未確認的內容不公開。
+
+若舊版本曾含私人資訊，應先確認曝光範圍並通知擁有者。發布修正版不會消除舊套件、歷史版本、快取或已下載副本；憑證外洩須由擁有者處理撤銷或輪替，不應在問題報告再次貼出原值。

package/INTEGRATION.md

@@ -0,0 +1,178 @@
+# HomeYa 共用資料視圖接入說明
+
+適用版本 `0.2.0-alpha.7`（Alpha）；2026-09-06。alpha.5 不包含本文件的新介面；原規劃的 alpha.6／alpha.7 整合為本版，未另行發布 alpha.6。完整操作驗收仍未完成，正式專案採用前須先試點驗證。
+
+## 所有 WORK 的共同規則
+
+共用套件是公開的。其他 WORK 的資料、截圖、附件、私人連結及商業內容不得隨整合帶入；問題回報與範例使用完全虛構資料。完整規則見 [公開套件與資料隔離](./DATA-PRIVACY.md)。
+
+本專案使用 HomeYa 共用資料視圖。遇到表格修改需求時，先判斷是「專案設定」或「共用能力」。專案設定可在本專案修改；共用能力與共用錯誤不得在本專案另行實作，必須整理成共用表格修改單，交由 HomeYa 共用資料視圖專案修改及發布新版本。本專案只在確認相容後升級版本。
+
+共用端負責欄位、互動、顯示、查詢契約及通用權限介面。專案負責帳號、資料庫、權限決策、資料取得／寫入、交易、流程、公式、上傳、稽核與設定保存。前端隱藏與 canRead/canEdit 不能代替後端授權。
+
+發布後使用精確 dependency 與 lockfile，驗收後各自重新發布。React >=18.2 <20、ESM、TypeScript；引入 `@keenaioc/data-view/style.css`，在 client component 使用。不會即時強制更新其他 Sites。
+
+## T19：先查詢，再載入；不顯示分頁
+
+1. 先取得使用者、角色與視圖設定，再依權限、filters、search、sorts、groups 查詢。
+2. 不要把整張表抓完才交給瀏覽器篩選。大量資料採遠端模式；少量已完整取得的資料可用本地 rows 模式。
+3. 原 WORK 將標準條件轉成參數化查詢，驗證欄位 ID、operator、值與權限。不接受任意 SQL，也不能下載第一批後才於前端篩選。
+4. 移除每頁筆數與翻頁，符合條件的資料連續捲動。pageSize、location.page、schedulePage 僅接受舊設定，不再截斷結果。
+5. 網路可內部分批，但總數／排序／分組語意涵蓋完整結果。未載完明確顯示尚未完整，失敗不能當成零筆或全部。
+6. 隱藏欄位、收合分組、虛擬化只減少畫面負擔。要排除已完成，將「完成隱藏 isFalse」送到後端。
+7. 時間軸捲動不等於日期篩選；未填日期的工程資料仍須留在甘特左側。
+
+DataViewQuery：`{version:1,search,filters:{conjunction,rules},sorts,groups}`。filter 含 id/fieldId/operator/value。人員與關聯使用永久 ID；containsAny 比對 ID 集合，equals 比較完整 ID 集合。空值依欄位 registry；日期按 ISO 日期解讀，時區由 host 統一。
+
+`DataSource<Row>.query({query,cursor?,snapshot?,signal})` 回傳：
+
+```ts
+{ rows: Row[]; total: number; nextCursor: string | null;
+  snapshot: string; groupCounts?: Record<string, number> }
+```
+
+- total 是授權及篩選後的精確總數。groupCounts 用完整穩定分組 key；未提供且結果未完整時，分組數量標為「已載入」。
+- 同一查詢各批 snapshot 不變；後端提供一致快照，或用資料集 revision 拒絕載入期間已變更的查詢，要求重新查詢。不能永遠回傳固定假 snapshot。
+- 排序加永久 ID 作穩定同值次序。後端分組查詢需使完整分組順序與各組內排序一致；核心不對遠端片段重新篩選或排序。
+- cursor 綁查詢、授權身分與 snapshot。核心檢查重複 ID、循環 cursor、總數及版本；後端也要驗證。
+- 可只取必要欄位並延後詳情／附件內容，但不能漏掉篩選、排序、分組、顯示與排程需要的欄位。
+
+```tsx
+// source.query 是專案的真實 API adapter；source/getRowId 必須 memoize。
+const remote = useRemoteDataView(source, getRowId);
+return <DataView identityKey={`${projectId}:${dataset}:${userId}:${role}`}
+  fields={fields} {...remote} getRowId={getRowId}
+  initialView={savedView} onViewChange={saveView}
+  onBatchCommit={commitAtomically} />;
+```
+
+hook 的擁有元件也須依相同 identity key 重新掛載，避免帳號／資料集切換殘留資料。hook 取消舊請求、忽略遲到結果；onLoadMore 載下一批，onRetry 清空並重新查詢。自行管理請求可傳 remote:{queryKey,total,complete,loading,error,onLoadMore,onRetry,groupCounts} 與 onQueryChange，queryKey 使用 dataViewQueryKey。key 不符時隱藏舊結果。
+
+未完整載入時全選只選目前已載入 ID，完整後才是全部符合條件資料。沒有隱含的後端全結果批次。寫入影響篩選、排序或分組時，host 應重新查詢並處理選取、總數與位置；不能保留錯誤分組。
+
+## T01／T02：版面與個人狀態
+
+canConfigureView 控制欄位、分組設定、顏色及版面。搜尋、收合、視圖導航獨立；canSearch/canCollapseGroups/canSwitchView 預設允許。canFilter/canSort 可明確允許成員，未指定時沿用 canConfigureView。
+
+features 的 search/filter/sort/group/columns/colors/viewTabs/viewSettings/viewManagement 可分別設 false 隱藏入口；rowOpen:true 增加桌面開卡按鈕。toolbarStart/toolbarEnd 插入專案自己的案件篩選等控制項，仍由專案更新查詢條件，不複製共用工具列。
+
+- view 是受控版面；initialView 僅提供初始值。
+- runtimeState/onRuntimeChange 保存個人 location、collapsedGroups、filters/sorts 覆蓋與 viewType。
+- onViewChange：沒有 onRuntimeChange 時沿用完整快照；提供後，版面保存排除個人導航與查詢覆蓋。
+- onViewChangeDetail 接收 {scope:'layout'|'query'|'navigation',view,runtime}，可記錄變更；不要再重複寫入同一保存位置。
+- splitViewState/mergeViewState 拆合版面及導航；角色模板的 filters/sorts 與個人覆蓋由 host 分別保存。
+- 角色模板鍵包含 project/dataset/role/device；個人狀態再加真實 user/view ID。模擬身分與真實管理員資格須分開驗證。
+- identityKey 切換使用者／資料集／角色時清除編輯、選取、歷史及尚未送出的舊佇列。已送後端的請求仍由 host 核對結果。
+
+DataViewWorkspace 支援受控 views、runtimeStates/onViewRuntimeChange(viewId,state)、onActiveViewChange(viewId)。不要每次捲動都回寫角色模板。舊用法仍保存完整集合。保存中或失敗的快照不接受外部模板覆蓋；衝突時由 host 提供重載／重新掛載。
+
+## T04～T08／T14／T16／T17：欄位介面
+
+|定義|用途|
+|---|---|
+|internal:true|授權提供的內部分組 metadata；不能出現在欄位管理、儲存格、詳情、剪貼簿或標題映射。canRead=false 仍禁止分組讀值|
+|render(value,row)|純顯示，不能內嵌操作按鈕|
+|Editor(props)|欄位級編輯器：value/row/field/onCommit/onCancel；沿用 registry 驗證與系統唯讀，不複製 registry|
+|renderQuickView(context)|快速檢視，提供 row/field/value/close/openRow，可進共用編輯|
+|renderAction(context)|獨立操作 shell；disabled/pending/run(action)。使用 run 取得同列佇列與錯誤提示；canAct(row) 決定流程資格，API由host提供|
+|groupValue(value)|穩定 key 與 label 分開|
+|groupOrder|value key順序：單值encodeURIComponent(ID)，多值為排序去重ID陣列JSON再編碼|
+|renderGroup(node)|共用分組外觀擴充，不額外讀取未授權值|
+|options color/textColor/groupColor/groupTextColor|格內與分組前景／背景色分開，人員按ID對應|
+|appearance|avatar、people:'combined'/'separate'、relation:'text'/'pill'、arrow、empty:'blank'/'dash'、systemValue|
+|multiple:false|人員單選，資料形狀仍為PersonValue[]|
+|formatText(value,row)|可讀複製與標題格式，呼叫前檢查讀取權限|
+
+人員／關聯有搜尋、空白、取消與確認；多人可合併一顆「甲、乙」，不改底層ID。title保留完整姓名，可開詳情。預設不顯示頭像，需顯示用avatar:true。
+
+onRowOpen(row)供一般唯讀格或開卡按鈕觸發；未提供用內建詳情。renderDetail/renderDetailFooter/renderMobileRow收到{row,fields,close,renderCell}；fields已排除內部及不可讀欄，但row是host原物件，自訂renderer仍須遵守權限。formatReadableRow輸出「欄位：值」，供LINE手動複製，不發送訊息。
+
+createdBy/updatedBy/systemReadOnly使用灰底小圓角；其他來源如轉交人用appearance.systemValue。普通唯讀仍可開卡／複製，不一律置灰。空白格不輸出破折號或字面跳脫空白；整格仍可點。arrow:false不保留箭頭寬度。
+
+## T15／T09／T10：尺寸、捲動與手機
+
+density:'workbench'：資料列32px、表頭32px、儲存格13px/16px、表頭12px；膠囊20px高/11px字/左右8px；控制項28px、操作按鈕24px。表頭左6右12、資料格左右6上下0；分組28px，外層間距8px、內層4px。
+
+metrics?:Partial<DataViewMetrics>正式調整以上數值；resolveMetrics/WORKBENCH_METRICS公開。CSS、表格虛擬化、甘特左右與連線使用同一組數值。36/52/72旧密度保留，不強改個人選擇。實際DOM高度仍須操作驗收。
+
+viewportHeight可為px數值或CSS高度；ResizeObserver量測可見高度。bottomScrollbar預設開啟桌面同步底部捲軸，容器16px/捲軸12px可調；作業系統覆蓋式捲軸影響外觀。
+
+超過200筆表格自動虛擬化；少量可用virtualize:false。手機表格用量測高度的卡片視窗；甘特桌面左右共享虛擬列。mobile:{fieldIds,summaryFieldId,presentation:'cards'|'compact'}決定獨立手機版面，可在視圖設定調整。行事曆「另N筆」開啟完整當日結果，不是資料分頁。
+
+## T03／T11／T13：移動與寫入
+
+rowMove:{canMove,canDrop,onMove}啟用六點把手。request含row、永久rowId、targetRowId、position:'before'/'after'/'groupEnd'、完整sourceGroupPath/targetGroupPath；每層有fieldId/key/valueKey。
+
+支援指標／觸控把手、Escape/pointercancel、上下鍵選已呈現落點與Enter確認、邊緣垂直捲動。僅顯示一個合法落點；不完整或無讀取權限的分組拒絕。虛擬視窗外的鍵盤落點需先捲入。host負責分組值、手動順序、權限及交易；篩選下使用永久targetRowId作錨點。排序與手動順序衝突時host須訂規則。核心無樂觀搬移，成功更新rows後才移動；失敗保留原順序。
+
+- onCellCommit完成真正儲存才resolve，失敗reject；與onBatchCommit同時提供時單格優先走它，不納入批次歷史。
+- onBatchCommit含id/reason/changes，最多1000格；host原子驗證所有權限、previousValue/revision並一次寫入，不能用多次單格API假裝原子批次。
+- 核心同列序列化，不同列並行；批次鎖相關列，schema/依賴修改等待既有寫入。host仍須revision、冪等與交易保證。
+- queued row是讀取快照，host應从自己的資料模型取得最新revision；在Promise完成前更新rows，必要時host同列佇列接續revision。
+- 成功但回應丟失先查operation ID或重載，不盲目重送；不得吞錯讓UI誤判成功。
+- features.batch/copy/paste/clear/undo/redo各自控制；批次型寫入需要onBatchCommit。初期只提供onCellCommit即可。流程action/system/internal欄位禁止通用批次改寫。
+- 復原／重做保留掛載內最近20次成功批次；切視圖／查詢／身分／schema清除。流程、附件與外部副作用不在歷史內。
+
+欄位管理沿用onFieldChange + canManageFields；結構與值由host保存，系統／內部／流程欄位禁止使用者刪改。附件走onRequestAttachment。
+
+## T18：排程與名稱
+
+空起訖、只有開始、只有結束皆保留原資料，甘特左側依共同條件呈現；右側不畫膠囊，不補今天或改狀態。已填無效日期或結束早於開始才屬invalid。scheduleRows回傳{items,unscheduled,invalid}。
+
+schedulePolicy:{showUnscheduled,showInvalidDates}預設false，不顯示入口或數量警示，可按視圖保存。可依專案需求設false；輸入驗證保留。
+
+gantt/calendar.titleFieldId使用getValue与formatText/可讀文字；空值用友善名稱。getRowLabel可覆寫開卡／清單名稱，host必須遵守讀取權限。getRowId永遠是永久ID。專案自行衍生的顯示標題欄位是隱藏的普通衍生欄，非internal分組欄。
+
+## 甘特依賴既有邊界
+
+起訖映射需指定兩個欄位，但每筆日期可空白。整條移動保留工期、左右端改天數；dateTime保留原時間及時區字串。工作天只排除六日，不含假日。手機用卡片與詳情改期。
+
+依賴僅Finish-to-start，需完整授權關係及相關rows；最多2000條連線、500筆相關列/1000格。拖曳先預覽再原子套用，必要時才推遲後續，鎖定或無權限則整份拒絕。host在同一交易驗證scheduleGuard。遠端片段不能宣稱完整依賴資料；未具備完整後端保證請勿啟用。沒有關鍵路徑、資源負荷、公式或自動承諾日期。
+
+## T12：升級與回退
+
+先備份alpha.5的dependency、lockfile、ViewConfig、schema及角色／個人設定。inspectViewMigration(fields,oldView)列出未知欄位、分頁移除及分組鍵變更。host先處理舊ID映射再normalize，不能忽略診斷直接覆蓋原設定。
+
+schemaVersion仍1，但分頁移除、人員／關聯條件與分組使用ID、日期異常分開、預設無診斷入口、虛擬化預設是行為變更。extensions保留JSON；其他頂層業務設定需移入extensions或專案設定表。
+
+舊人員分組收合鍵與名稱篩選需用旧資料及ID對照轉換；同名不明不可猜測。無法轉換的收合鍵首次展開，保留原備份以回退。
+
+以 `npm install --save-exact @keenaioc/data-view@0.2.0-alpha.7` 接入單一測試專案，驗證 lockfile、型別、CSS 與實際操作，再决定正式 Site 的升級。較舊版本已進入下架處理，不作為新接入的回退來源；alpha.8 的回退基準為 alpha.7，詳見下節。發布套件不代表任何接入專案已完成操作驗收。
+
+
+## alpha.8：CORE-01～06（Alpha）
+
+以下 API 自 alpha.8 提供。使用 `npm install --save-exact @keenaioc/data-view@0.2.0-alpha.8` 更新精確 dependency、lockfile 與套件 CSS；不要從其他專案複製內部 CSS。修正後瀏覽器驗收尚未完成，需先於測試專案核對下列行為。
+
+```tsx
+import { DataView, type DataViewConfig } from "@keenaioc/data-view";
+import "@keenaioc/data-view/style.css";
+
+// host 提供資料、view、回呼，以及使用者＋資料集／視圖範圍內的呈現偏好。
+<DataView
+  fields={fields}
+  rows={rows}
+  getRowId={(row) => row.id}
+  view={view}
+  onViewChange={saveView}
+  presentation={presentation} // "auto" | "table" | "cards"
+  onPresentationChange={savePresentation}
+  chrome="compact"
+  height={availableHeight}
+  headerStart={<ScopeSelector />}
+  headerEnd={<ProjectSaveStatus />}
+  onCellCommit={saveCell}
+/>
+```
+
+- `presentation` 是受控 prop，不會改資料或 viewType。auto 依元件寬度切換（767px 以下窄版）；table 強制桌面表格／甘特／月曆，cards 強制卡片／議程。省略回呼便不顯示選擇器；host 必須保存及回傳選擇。它與 `view.mobile.presentation` 的 cards／compact 卡片密度是不同設定。
+- `chrome="compact"` 精簡標題、視圖與工具列。搜尋／篩選／排序／分組保留；窄空間轉圖示，title 與 accessible name 保留完整文字與條件數。次要操作進「更多」，Tab 操作、Escape 關閉返回觸發鈕。標準模式仍是原工具列。
+- `toolbarStart` 放常用業務範圍控制；`toolbarEnd` 在精簡模式收進更多，不能放必須持續可見的警告。持續狀態使用 `headerEnd`。內建載入完整性／查詢錯誤／寫入失敗／衝突提示不會收進更多。
+- `headerStart`／`headerEnd` 是新增插槽，不取代必要筆數與儲存提示。可用 `features.viewTabs=false` 關掉內建種類切換、由 host 控制 viewType；DataViewWorkspace 的命名視圖仍維持同一份資料，精簡模式縮減其間距。
+- `height` 是**整個元件**高度。DataViewWorkspace 還包含命名視圖與集合儲存狀態。可傳 px 數值或 CSS 長度；100% 必須有明確高度的父層，flex 父層需 `min-height:0`。推薦 host 量測網站剩餘空間後傳數值。極低高度若連工具列與警告也放不下，需由 host 提供更多空間。
+- `viewportHeight` 仍是**資料區**高度，不含標題／工具列；未提供 height 時生效。新增 height 優先；避免將兩種數值誤當相同意義。手機卡片也遵守資料區限制。固定整體高度時由各視圖資料區負責垂直捲動；甘特左右捲動保持同步。
+- 工作台密度須在受控 `view.density` 或新視圖 `initialView.density` 設為 workbench；既有設定不會被初始值覆蓋。表格資料列／表頭 32px、字 13px、膠囊 20px／11px；分組按鈕 28px、外層間距 8px／內層 4px。
+- 複雜編輯器／多選／人員／關聯在詳情開啟，避免撐高或裁切行內操作。自訂 renderer／action 必須遵守格子空間，完整內容使用 quick view／detail。
+- 舊設定無強制遷移；新偏好由 host 自己的設定服務保存，建議區分使用者＋資料集＋視圖。不要修改 backend query 或資料為了切换顯示模式。
+- 回退：還原 alpha.7 的 dependency／lockfile，移除新 props（presentation/onPresentationChange/chrome/headerStart/headerEnd/height），保留偏好與 view 備份。無資料搬移。更舊版已涉及下架處理，不作為本版回退來源。
+- 驗收必須涵蓋全寬、720px 分割窗、手機、表格→甘特→表格、分組、編輯、水平及連續捲動、儲存失敗／衝突、遠端尚未完整／完整／查詢失敗；只用合成資料。

package/KNOWN-LIMITATIONS.md

@@ -0,0 +1,34 @@
+# 已知限制：0.2.0-alpha.7（Alpha）
+
+2026-09-06。本版整合 T01～T19 與資料保護修正。程式、測試場與文件已修改，自動測試及建置通過；實際操作驗收未完成，不能宣稱正式替換工作台已準備完成。
+
+## 驗收與接入限制
+
+- 程式測試涵蓋欄位／權限、穩定分組、設定契約、無分頁、遠端分批完整性與取消、並行佇列、虛擬位移及SSR，不證明實際DOM高度、滑鼠落點、觸控、焦點或捲動手感。
+- 先前Cloud Browser明確以網址政策拒絕操作；本輪未用其他網址、瀏覽器或替代路徑繞過。32px/13px/20px/11px是程式契約，仍需實際量測。
+- Lab全部使用合成資料。相容區遠端模式是API契約模擬，沒有真實網路或資料庫效能證據；不得宣稱接入專案已減少下載量。
+- 接入專案尚未升級或改後端。真實權限、同步、交易、稽核與上傳須由接入專案驗收。
+- 遠端模式需要host實作query/cursor/snapshot/total、權限與索引；只傳rows仍是本地篩選。沒有自動將前端條件轉成資料庫查詢。
+- 完整性依賴真實總數及一致快照；固定假snapshot無法保證正確。資料變動可拒絕舊批次並重查。
+- 未完整載入時批次只涉及明確已載入ID；沒有groupCounts時群組顯示「已載入」。沒有隱含的全結果批次。
+- 所有視圖移除資料分頁。桌面表格與甘特、手機表格有虛擬化；行事曆及甘特手機清單仍使用連續卡片，範圍應由篩選控制。
+- 資料列拖曳键盤落點限已呈現視窗，需先捲到目標；指標把手支援邊緣捲動及取消。host更新rows才改順序，需自行定義排序與手動搬移的關係。
+- 分層角色／個人狀態是介面，無內建角色資料庫或跨裝置服務；未接onRuntimeChange仍保存完整快照。
+- 同時提供onCellCommit/onBatchCommit時單格優先前者，不納入批次復原；需統一歷史可只提供onBatchCommit。流程、附件與欄位結構不支援資料格復原。
+- 已送出的舊身分請求不會因切畫面撤銷；後端仍須授權、冪等、結果核對。尚未開始的佇列會取消。
+- 自訂renderer/Editor/action與host同程式執行，須遵守權限。internal是可分組但不暴露的授權metadata，不是秘密儲存區。
+- 工作台density與色票需host套用；保留36/52/72選擇，不強制切所有使用者密度。底部捲軸外觀受作業系統影響。
+- 人員／關聯篩選及分組從名稱改ID，需檢查舊設定；同名不可猜測。pageSize不再作用。
+- 甘特僅整日FS依賴，工作天只扣六日；需完整相關資料及原子scheduleGuard，遠端片段不能宣稱完整。沒有關鍵路徑、資源負荷、假日、公式或自動承諾排程。
+
+套件發布與安裝成功不代表業務接入或操作驗收完成。接入專案各自處理後端查詢、設定遷移、權限及保存；既有 alpha.5 試點不代表本版已驗收。
+
+
+## alpha.8 Alpha 限制
+
+- CORE-01～06 與 T15 修正自 alpha.8 提供；alpha.7 不具備這些修正。本版為公開 Alpha，並非完成操作驗收的穩定版。
+- 瀏覽器預覽曾成功顯示基底；本次修正後重載遭平台 URL 政策阻擋，桌機／720px／手機、更多選單鍵盤、實際高度與捲動仍待操作驗收。
+- 精簡表頭在空間不足時允許標題／視圖區換行，工具列保持單行。任意 host 插槽內容需自行保持精簡；長警告不裁掉。
+- 卡片／議程的觸控目標不強制等同桌機 28px 控制項。自訂欄位元件仍需依接入說明選擇詳情／快速檢視。
+- height 百分比需要有高度的父層；此 API 不能修正 host 自己造成的雙重頁面捲動。DataViewWorkspace 的命名視圖列仍存在，需與單一 viewType 切換分別設定。
+- 呈現偏好由 host 保存，不自動跨使用者／裝置同步；不啟用進度排程相關進階能力。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HomeYa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,73 @@
 # @keenaioc/data-view
 
-HomeYa 共用資料視圖的跨 Sites 引用驗證套件。
+HomeYa 共用資料視圖引擎。以 既有工作台的既有表格成果為主要來源，集中管理欄位型別、表格操作、個人檢視與通用資料／權限介面。
 
-目前的 `0.0.0-poc.*` 版本只驗證公開 npm 安裝、React/CSS 入口、固定版本升級與回退。它不是正式 V1，也不包含業務資料、資料庫連線或 HomeYa 專案設定。
+套件不包含資料庫、業務流程、報價公式、使用者帳號或專案資料。接入專案透過 `DataView` 的 callbacks 處理讀取、寫入、附件、權限與稽核。
 
-正式版本將以 HomeYa 設計待辦工作台的既有表格成果為主要來源，抽出欄位註冊、表格操作、檢視設定與通用資料／權限介面。
+本文件版本：**`0.2.0-alpha.8`（公開 Alpha 測試版）**。新增精簡表頭／工具列、呈現選擇、整體高度與甘特響應修正。程式、型別、建置及打包檢查已通過；修正後瀏覽器操作驗收尚未完成，接入時須重測。
 
-```bash
-npm install --save-exact @keenaioc/data-view@0.0.0-poc.1
+既有基底：整合 T01～T19：工作台密度與 renderer、權限及狀態分離、資料列拖曳、並行寫入、手機獨立版面、排程空值、無分頁與遠端查詢契約。原先規劃的 alpha.6／alpha.7 合併為本版；alpha.6 未另行發布。
+
+本版保留 Alpha 限制：自動測試與建置通過，完整桌機／手機操作驗收尚未完成。先在測試專案接入，再決定是否升級正式系統。
+
+```sh
+npm install --save-exact @keenaioc/data-view@0.2.0-alpha.8
+```
+
+必須固定精確版本；不要使用無版本安裝、`latest`、`next` 或範圍版本。
+
+公開範圍及所有接入專案的資料隔離規則見 [資料保護說明](./DATA-PRIVACY.md)。
+
+詳見 [接入說明](./INTEGRATION.md)、[已知限制](./KNOWN-LIMITATIONS.md) 與 [更新紀錄](./CHANGELOG.md)。
+
+需要 React >=18.2 且 <20；已實測 React 19.2.6。套件是 ESM，並包含 TypeScript 定義；必須引用 CSS。Next.js／Sites 請在 client component 使用 DataView。
+
+以下是可直接使用的唯讀接入；加入寫入 callback 後才開放編輯。
+
+```tsx
+"use client";
+import { DataView, DATA_VIEW_VERSION, type FieldDefinition } from "@keenaioc/data-view";
+import "@keenaioc/data-view/style.css";
+
+type Project = { id: string; name: string; hidden: boolean };
+const fields: FieldDefinition<Project>[] = [
+  { id: "name", label: "案件", type: "singleLineText", pinned: "left" },
+  { id: "hidden", label: "完成隱藏", type: "checkbox" },
+];
+
+export function ProjectView({ rows }: { rows: Project[] }) {
+  return <>
+    <small>HomeYa 共用資料視圖 {DATA_VIEW_VERSION}</small>
+    <DataView fields={fields} rows={rows} getRowId={(row) => row.id}
+      initialView={{ filters: { conjunction: "and", rules: [
+        { id: "open-only", fieldId: "hidden", operator: "isFalse" },
+      ] } }} />
+  </>;
+}
 ```
+
+完成隱藏只是一般 checkbox 欄位；是否隱藏由檢視篩選決定，不刪除資料。新增欄位需要同時提供 `onFieldChange` 與 `permissions.canManageFields: true`。寫入後由 host 更新 `rows`／`fields`，否則畫面不會保存新值。
+
+## V2 相容擴充
+
+`DataViewConfig.schemaVersion` 維持 `1`。`viewType` 可選 `table`／`gantt`／`calendar`；三者共用同一份 `rows`、`fields`、篩選、排序、分組、收合與權限。多數新介面為選填；分頁移除、人員／關聯篩選與分組改用 ID、排程日期分類為行為變更，必須先依接入說明檢查相容性。
+
+- `gantt`：指定 `titleFieldId`、`startFieldId`、`endFieldId`，選填 `groupFieldId`、`progressFieldId`。分組同步共用第一層，進度為 0–1。
+- `calendar`：指定 `titleFieldId`、`dateFieldId`；選填 `startTimeFieldId`、`endTimeFieldId`（完整日期時間）、`colorFieldId`（選項顏色）。排程以傳入 ISO 日期呈現，adapter 統一時區。
+- `onBatchCommit`：整批 `CellCommit[]`，用於編輯、批次、貼上、清空、復原與重做。專案必須重新驗證身分、schema、權限、前值／revision，以 transaction 保證全成功或全失敗，並用 request id 防止重複寫入。不能逐格寫入後假裝整批成功。
+- `onFieldChange`：新增、複製、重新命名、刪除欄位的意圖。需 `canManageFields: true`；專案自行管理持久化／軟刪／稽核，再更新 `fields`。系統欄位不能由使用者建立或變更。
+- `density`：workbench／compact／standard／comfortable；`virtualize`：桌機資料列與手機表格卡片虛擬化；`colorRules`：個人條件式整列／儲存格填色，不寫入資料。
+
+沒有 `onBatchCommit` 的接入專案保留 V1 單格回呼，不啟用批次或歷史。復原／重做只限目前掛載最近 20 次成功資料操作，最多 1,000 格／次，遇衝突拒絕覆寫；不包含附件、欄位結構或外部副作用。
+
+每個 Sites 固定精確版本及 lockfile，按 Lab → 一個試點 → 其他專案逐一升級。保留 dependency、ViewConfig 與 schema 快照供回退；回退套件不會自動回復資料修改。不要引用 `latest`、`next` 或範圍版本作自動更新。
+
+## 共用修改規則
+
+本專案使用 HomeYa 共用資料視圖。遇到表格修改需求時，先判斷是「專案設定」或「共用能力」。專案設定可在本專案修改；共用能力與共用錯誤不得在本專案另行實作，必須整理成共用表格修改單，交由 HomeYa 共用資料視圖專案修改及發布新版本。本專案只在確認相容後升級版本。
+
+## 命名視圖（alpha.5）
+
+需要多個命名視圖時用 `DataViewWorkspace`，單一視圖原有 `DataView` API 保留。`initialViews` 只在掛載時讀取，必須先載入個人設定再掛載；切換使用者或資料集時由 host 改 `key`。所有視圖共用同一組 `rows`、`fields` 與資料寫入 callbacks。完整範例及回退方法見 [接入說明](./INTEGRATION.md)。
+
+不要求第一欄為特殊主欄位，不新增公式引擎。一般欄位仍可依既有規則固定、拖曳或隱藏。

package/dist/contracts.d.ts

@@ -0,0 +1,33 @@
+import type { DataViewConfig, DataViewMetrics, DataViewQuery, FieldDefinition, ViewRuntimeState } from "./types.js";
+export declare const WORKBENCH_METRICS: DataViewMetrics;
+export declare function resolveMetrics(density: DataViewConfig["density"], input?: Partial<DataViewMetrics>): DataViewMetrics;
+export declare function splitViewState(view: DataViewConfig): {
+    layout: DataViewConfig;
+    runtime: ViewRuntimeState;
+};
+export declare function mergeViewState(layout: DataViewConfig, runtime?: ViewRuntimeState): DataViewConfig;
+export declare function createDataViewQuery(view: DataViewConfig): DataViewQuery;
+/** JSON-safe canonical key: callers must reset remote rows whenever this changes. */
+export declare function dataViewQueryKey(query: DataViewQuery): string;
+/** Diagnostics do not silently rewrite or infer business field mappings. */
+export declare function inspectViewMigration<Row>(fields: FieldDefinition<Row>[], view: Partial<DataViewConfig>): {
+    code: string;
+    fieldId?: string;
+    message: string;
+}[];
+/** Locks intersecting rows; independent rows run concurrently. '*' is a schema barrier. */
+export declare function createWriteQueue(): {
+    readonly pending: number;
+    dispose(): void;
+    run<T>(resources: string[], action: () => Promise<T> | T): Promise<T>;
+};
+/** Prefix offsets support independently sized group rows without virtual scroll drift. */
+export declare function virtualWindow(heights: number[], top: number, viewport: number, overscan?: number): {
+    offsets: number[];
+    start: number;
+    end: number;
+    before: number;
+    after: number;
+    total: number;
+};
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpH,eAAO,MAAM,iBAAiB,EAAE,eAK/B,CAAC;AACF,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAQpH;AACD,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAG1G;AACD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAEjG;AACD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAEvE;AACD,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,UAAmC;AAExF,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,cAAc,CAAC;UAEpE,MAAM;cAAY,MAAM;aAAW,MAAM;IAO3E;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB;;;QAOxB,CAAC,aAAa,MAAM,EAAE,UAAU,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;EAUxE;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAI;;;;;;;EAM3F"}

package/dist/contracts.js

@@ -0,0 +1,83 @@
+export const WORKBENCH_METRICS = {
+    rowHeight: 32, headerHeight: 32, groupHeight: 28, groupGap: 8, nestedGroupGap: 4,
+    cellFontSize: 13, cellLineHeight: 16, headerFontSize: 12, cellPadding: 6,
+    headerPaddingLeft: 6, headerPaddingRight: 12, controlHeight: 28, actionHeight: 24,
+    badgeHeight: 20, badgeFontSize: 11, badgePadding: 8, scrollbarHeight: 16, scrollbarThumb: 12,
+};
+export function resolveMetrics(density, input) {
+    const base = density === "workbench" ? WORKBENCH_METRICS : { ...WORKBENCH_METRICS, rowHeight: density === "compact" ? 36 : density === "comfortable" ? 72 : 52, headerHeight: 36, cellFontSize: 14, headerFontSize: 13, badgeFontSize: 12 };
+    const out = { ...base };
+    for (const key of Object.keys(base)) {
+        const value = input?.[key];
+        if (typeof value === "number" && Number.isFinite(value) && value >= (key.endsWith("Gap") ? 0 : 1) && value <= 500)
+            out[key] = value;
+    }
+    return out;
+}
+export function splitViewState(view) {
+    const { location, collapsedGroups, ...layout } = view;
+    return { layout: { ...layout, collapsedGroups: [] }, runtime: { location, collapsedGroups } };
+}
+export function mergeViewState(layout, runtime) {
+    return { ...layout, ...runtime, location: { ...layout.location, ...runtime?.location } };
+}
+export function createDataViewQuery(view) {
+    return { version: 1, search: view.location?.search ?? "", filters: view.filters, sorts: view.sorts, groups: view.groups };
+}
+/** JSON-safe canonical key: callers must reset remote rows whenever this changes. */
+export function dataViewQueryKey(query) { return JSON.stringify(query); }
+/** Diagnostics do not silently rewrite or infer business field mappings. */
+export function inspectViewMigration(fields, view) {
+    const ids = new Set(fields.map((f) => f.id));
+    const diagnostics = [];
+    for (const id of new Set([...(view.columns ?? []).map((c) => c.fieldId), ...(view.sorts ?? []).map((s) => s.fieldId), ...(view.groups ?? []).map((g) => g.fieldId), ...(view.filters?.rules ?? []).map((r) => r.fieldId)])) {
+        if (!ids.has(id))
+            diagnostics.push({ code: "unknown-field", fieldId: id, message: "欄位不存在，請由專案提供舊 ID 映射後再正規化" });
+    }
+    if (view.pageSize !== undefined || (view.location?.page ?? 1) > 1)
+        diagnostics.push({ code: "pagination-removed", message: "分頁已移除；保留原始設定備份，使用連續捲動" });
+    if (view.collapsedGroups?.length && view.groups?.some((g) => fields.some((f) => f.id === g.fieldId && ["person", "relation", "multiSelect", "createdBy", "updatedBy"].includes(f.type))))
+        diagnostics.push({ code: "stable-group-keys", message: "人員／關聯／多選改用穩定 ID；舊收合鍵須由舊資料對照轉換，否則這些分組首次展開" });
+    return diagnostics;
+}
+/** Locks intersecting rows; independent rows run concurrently. '*' is a schema barrier. */
+export function createWriteQueue() {
+    const tails = new Map();
+    const all = new Set();
+    let disposed = false;
+    return {
+        get pending() { return all.size; },
+        dispose() { disposed = true; },
+        run(resources, action) {
+            const keys = [...new Set(resources)];
+            const waiting = keys.includes("*") ? [...all] : [tails.get("*"), ...keys.map((key) => tails.get(key))].filter(Boolean);
+            const result = Promise.all(waiting.map((p) => p.catch(() => { }))).then(() => { if (disposed)
+                throw new Error("檢視身分已切換，尚未送出的操作已取消"); return action(); });
+            all.add(result);
+            for (const key of keys)
+                tails.set(key, result);
+            const clear = () => { all.delete(result); for (const key of keys)
+                if (tails.get(key) === result)
+                    tails.delete(key); };
+            void result.then(clear, clear);
+            return result;
+        },
+    };
+}
+/** Prefix offsets support independently sized group rows without virtual scroll drift. */
+export function virtualWindow(heights, top, viewport, overscan = 5) {
+    const offsets = [0];
+    for (const height of heights)
+        offsets.push(offsets.at(-1) + height);
+    const lower = (value) => { let lo = 0, hi = heights.length; while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (offsets[mid + 1] <= value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    } return lo; };
+    const start = Math.max(0, lower(Math.max(0, top)) - overscan);
+    const end = Math.min(heights.length, lower(Math.max(0, top) + Math.max(1, viewport)) + overscan + 1);
+    return { offsets, start, end, before: offsets[start], after: offsets.at(-1) - offsets[end], total: offsets.at(-1) };
+}
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"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"}

package/dist/data-view.d.ts

@@ -0,0 +1,3 @@
+import type { DataViewProps } from "./types.js";
+export declare function DataView<Row>(props: DataViewProps<Row>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=data-view.d.ts.map

package/dist/data-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-view.d.ts","sourceRoot":"","sources":["../src/data-view.tsx"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAIV,aAAa,EAWd,MAAM,YAAY,CAAC;AAQpB,wBAAgB,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,2CAEtD"}