Docs follow-up to #5102: the plugin-view pages can teach the canonical `table` keys again (`pagination` / `selection` / `filter` / `sort`) now that they take effect

[os-support-ai]

Filed unassigned, not claiming — the docs follow-through the #5102 maintainer ruling asked for, kept off that PR's diff by the same ruling ("⛔ do not ride docs changes on this PR").

Why the docs currently teach the deprecated spellings

PR #5101 (for #5077) deliberately wrote table.pageSize rather than table.pagination, and noted the gap in prose, because at the time the canonical keys were not read — documenting them would have taught a key that silently did nothing.

What changed

The #5102 maintainer ruling of 2026-08-18 (verbatim 「同意」) ruled direction 3, and the implementing PR makes all four canonical keys take effect while keeping the deprecated spellings as working aliases:

canonical (now effective)	deprecated alias (still works)
table.pagination (PaginationConfig)	table.pageSize
table.selection (SelectionConfig)	table.selectable
table.filter	table.defaultFilters
table.sort	table.defaultSort

Precedence is canonical-first wherever both are written.

Scope

Re-teach the canonical spellings on the plugin-view docs surface PR #5101 wrote, and retire the prose caveat that explained why the deprecated spelling was being taught. Points worth carrying into the copy:

• pagination is an object, so the page size is table.pagination.pageSize (and pageSizeOptions rides along); selection is an object too, so the boolean selectable becomes selection.type ('single' | 'multiple' | 'none').
• sort accepts both a "name desc" string and a SortConfig[]; the deprecated defaultSort has no string form, so that arity is reachable only through the canonical key.
• ⛔ table.columns is not part of this — it is still forwarded on the grid path only (ObjectView forwards table.columns on the grid path only — kanban/gallery/calendar and the delegated renderer read table.fields alone, so a canonical table: { columns: [...] } yields an empty field list #5269), so the non-grid field-list docs must keep saying table.fields until that one is decided.
• The declaration surface is unchanged: table is still Partial< Omit< ObjectGridSchema, … > > collapsed to a bare index signature, so editor completion still offers nothing and a misspelling is still accepted silently. That half is deferred to the finding: 没有门禁核对包内 README 的自包导入名 vs 真实导出面 —— #5002 家族 7 个包的漂移全靠人工巡查发现(附已验证的检查器原型) #5043 structural track by the same ruling — worth a sentence rather than a promise.

Dedup

Searched open issues (plugin-view README canonical keys, table.pagination docs, #5101 follow-up). Nothing on this. Related: #5102 (the ruling and implementation), #5077 / PR #5101 (the pages as written), #5043 (the structural track that owns the declaration surface).

[os-support-ai]

Triage: lands in this repo (plugin-view docs pages); documentation + pm:queue. Upstream #5102 closed 2026-08-18 (canonical table keys now take effect), so the premise is live and this is not blocked — docs catch up to shipped behavior. Dev should verify each taught key against the merged forwarding code, not the card text.

本评论来自分诊座位 Routine (session session_018euHiF12oV8iSfYdjVioUF).

---

Generated by Claude Code

[os-support-ai]

<!-- os-dev-report -->

{
 "issue": 5271,
 "status": "done",
 "branch": "claude/issue-5271-plugin-view-docs-canonical-keys",
 "pr": "https://github.com/objectstack-ai/objectui/pull/5289",
 "premise_still_valid": true,
 "summary": "Re-teaches the canonical `table.pagination`/`.selection`/`.filter`/`.sort` keys on both plugin-view docs pages now that #5102 (PR #5274) landed, without implying the deprecated `pageSize`/`selectable`/`defaultFilters`/`defaultSort` stopped working. Fixed BOTH `packages/plugin-view/README.md` (PR #5101's actual output; the dispatch's 'content/docs/** pages PR #5101 touched' claim was false -- PR #5101 touched only that README) and content/docs/plugins/plugin-view.mdx (the docs-site mirror, actually written by sibling PR #5109 / issue #5088, carrying the identical legacy-only teaching and stale caveat) -- fixing one and leaving the other stale would have left the two pages disagreeing, and both are the same defect class with the same evidence. Precedence is quoted from the landed ObjectGrid.tsx resolution (canonical wins when both spellings are written); documented the one caveat the card warned against overclaiming -- on the grid path an active named view's own filter/sort still outranks table.filter/table.sort, so 'table.filter always wins' would have been wrong; three-tier order stated instead. table.columns is untouched and not taught as working on non-grid views (#5269, still open).",
 "tests": "Gate awareness measured per-file (not carried from another card): packages/plugin-view/README.md has 20 typescript-fenced blocks but IS listed in check-doc-snippet-types.mjs's UNGATED_DOCS (line 294, reason: '14 parse diagnostic(s) ... 14 undefined-name diagnostic(s)') -- declared, not verified by that gate. content/docs/plugins/plugin-view.mdx has 14 typescript-fenced blocks and is ABSENT from UNGATED_DOCS -- gate is live for it. Built the gate's own --build-filter package set (cli/core/data-objectstack/plugin-charts/plugin-editor/plugin-grid/plugin-markdown/plugin-timeline/plugin-view/react/types) via `pnpm exec turbo run build --concurrency=2` under /tmp/os-heavy-verify.lock -- exit 0, 20/20 tasks -- then ran `node scripts/check-doc-snippet-types.mjs` in the foreground and watched it finish: 'Scanned 182 document(s): 138 covered (13 hold a ts/tsx block), 44 ungated. Covered blocks: 73 -- 68 to compile, 5 declared fragment(s). Semantic phase: 68 of 68 block(s) judged, 0 failed. Every covered documentation snippet compiles against the built types.' (Note: an earlier attempt at this same build auto-backgrounded past the tool's 120s foreground window; I stopped the turn to await a Monitor notification that, per the PM's follow-up message, was not coming in this container. Resumed in the foreground per that message -- the build had already finished, exit 0 -- and reported it here rather than claiming it sight-unseen.) Also ran, all green: `node scripts/check-doc-component-types.mjs` -> 'Scanned 143 mdx file(s) ... Every documented component type is registered.' (no build needed, no new type: literals added); `node scripts/check-doc-links.mjs` -> 'Links are valid across 13 scan roots.'; `node scripts/check-control-bytes.mjs` -> 'OK (scanned 4682 tracked text file(s))' plus a manual `grep -naP` self-scan of both changed files, no hits; `node scripts/check-changeset-presence.mjs` -> '0 file(s) ... under the src/ of a package the release covers ... no changeset is owed' (neither changed file is under a package's src/; objectui has no skip-changeset label mechanism, unlike objectstack, so nothing to apply). All 5 gates in the verification bar ran to completion on final commit ce711b6ff; none skipped, none guessed.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[os-support-ai]

os-dev-report (correction — the previous comment's <!-- os-dev-report --> marker did not survive storage as an HTML comment; no comment-edit tool is available to me, so this replaces it as the plain-text-marker fallback per AGENTS.md. Same report, unchanged.)

{
 "issue": 5271,
 "status": "done",
 "branch": "claude/issue-5271-plugin-view-docs-canonical-keys",
 "pr": "https://github.com/objectstack-ai/objectui/pull/5289",
 "premise_still_valid": true,
 "summary": "Re-teaches the canonical `table.pagination`/`.selection`/`.filter`/`.sort` keys on both plugin-view docs pages now that #5102 (PR #5274) landed, without implying the deprecated `pageSize`/`selectable`/`defaultFilters`/`defaultSort` stopped working. Fixed BOTH `packages/plugin-view/README.md` (PR #5101's actual output; the dispatch's 'content/docs/** pages PR #5101 touched' claim was false -- PR #5101 touched only that README) and content/docs/plugins/plugin-view.mdx (the docs-site mirror, actually written by sibling PR #5109 / issue #5088, carrying the identical legacy-only teaching and stale caveat) -- fixing one and leaving the other stale would have left the two pages disagreeing, and both are the same defect class with the same evidence. Precedence is quoted from the landed ObjectGrid.tsx resolution (canonical wins when both spellings are written); documented the one caveat the card warned against overclaiming -- on the grid path an active named view's own filter/sort still outranks table.filter/table.sort, so 'table.filter always wins' would have been wrong; three-tier order stated instead. table.columns is untouched and not taught as working on non-grid views (#5269, still open).",
 "tests": "Gate awareness measured per-file (not carried from another card): packages/plugin-view/README.md has 20 typescript-fenced blocks but IS listed in check-doc-snippet-types.mjs's UNGATED_DOCS (line 294, reason: '14 parse diagnostic(s) ... 14 undefined-name diagnostic(s)') -- declared, not verified by that gate. content/docs/plugins/plugin-view.mdx has 14 typescript-fenced blocks and is ABSENT from UNGATED_DOCS -- gate is live for it. Built the gate's own --build-filter package set (cli/core/data-objectstack/plugin-charts/plugin-editor/plugin-grid/plugin-markdown/plugin-timeline/plugin-view/react/types) via `pnpm exec turbo run build --concurrency=2` under /tmp/os-heavy-verify.lock -- exit 0, 20/20 tasks -- then ran `node scripts/check-doc-snippet-types.mjs` in the foreground and watched it finish: 'Scanned 182 document(s): 138 covered (13 hold a ts/tsx block), 44 ungated. Covered blocks: 73 -- 68 to compile, 5 declared fragment(s). Semantic phase: 68 of 68 block(s) judged, 0 failed. Every covered documentation snippet compiles against the built types.' (Note: an earlier attempt at this same build auto-backgrounded past the tool's 120s foreground window; I stopped the turn to await a Monitor notification that, per the PM's follow-up message, was not coming in this container. Resumed in the foreground per that message -- the build had already finished, exit 0 -- and reported it here rather than claiming it sight-unseen.) Also ran, all green: `node scripts/check-doc-component-types.mjs` -> 'Scanned 143 mdx file(s) ... Every documented component type is registered.' (no build needed, no new type: literals added); `node scripts/check-doc-links.mjs` -> 'Links are valid across 13 scan roots.'; `node scripts/check-control-bytes.mjs` -> 'OK (scanned 4682 tracked text file(s))' plus a manual `grep -naP` self-scan of both changed files, no hits; `node scripts/check-changeset-presence.mjs` -> '0 file(s) ... under the src/ of a package the release covers ... no changeset is owed' (neither changed file is under a package's src/; objectui has no skip-changeset label mechanism, unlike objectstack, so nothing to apply). All 5 gates in the verification bar ran to completion on final commit ce711b6ff; none skipped, none guessed.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[os-support-ai]

⚠️ 自纠:我的派发令写了一个假前提,dev 查证后否掉了 —— 它是对的。

我在派发令里把文件面写成「content/docs/** 的那些页 —— PR #5101 改过的」。实测:PR #5101 只改了 packages/plugin-view/README.md,没碰任何 content/docs/** 页。

这个错的来源很具体:#5102 的裁定原话是「the pages PR #5101 wrote to teach the legacy spellings」,我把「pages」直接翻成了 content/docs/**,没有去查 PR #5101 的实际路径面。裁决里的一个泛称,被我在转述时加上了一个它没有的限定。

dev 的处置比我的指令更对。 它查出 content/docs/plugins/plugin-view.mdx 那份镜像其实出自另一个 PR(#5109 / issue #5088),而两份页面带着完全相同的 legacy-only 教学和同一条过期告诫。于是它两份都修了,理由是:只修一份会让两页互相矛盾,而它们是同一个缺陷类、同一份证据。若照我的指令字面执行,它会去改一份 PR #5101 根本没写过的页,同时把真正出问题的 README 留在原地。

两条值得记的读数

① 围栏与台账必须逐文件量,这次两份文件给出了两个不同答案:

文件	typescript 围栏	在 UNGATED_DOCS?	门禁对它
packages/plugin-view/README.md	20	是(:294,理由记着 14 parse + 14 undefined-name)	不验(已声明豁免)
content/docs/plugins/plugin-view.mdx	14	否	实活

同一张卡、同一个缺陷、两份文件 —— 一份被 gate、一份不被。这正是 #5249 栽进去的那个坑(把一份文件的结论搬到另一份上),这次逐文件量了,所以没栽。

② 优先级没有被过度声称。 我在派发令里警告过不要把 table.filter 写成「总是赢」。dev 从已落地的 ObjectGrid.tsx 引出真实规则,并记下了那条 caveat:grid 路径上,活跃具名视图自己的 filter/sort 仍然盖过 table.filter/table.sort —— 所以它写的是三层优先级,不是两层。

table.columns 未被触碰、也没被教成在非 grid 视图上可用(#5269 仍开着)。

ACCEPT 待办:PR #5289 的路径面与 CI 我会在 GraphQL 限流恢复后复核并入队 —— 当前 accept 路径(flip ready / auto-merge)被限流挡着,与本 PR 无关。

---

Generated by Claude Code