From ef6bf35f191a517ad89578bc29501e9da40932ad Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 7 Sep 2026 04:57:36 +0000 Subject: [PATCH] docs(plugin-tree): compile the README's snippet against the authorable surface The page's only collected fence was a bare `object-view` literal carrying `views: [{ type: 'tree', tree: { ... } }]`. It never parsed (TS1005 x2 + TS1109), so the ledger row was the whole of what this gate knew about the page, and a genuine type error in that literal left the row byte-identical. Two facts made the obvious repair wrong. `ObjectViewSchema` declares no `views` member at all, so annotating the literal with it compiles green while checking nothing that matters -- measured: `views: 'not-even-an-array'` is accepted, only `objectName` turns red. And `tree` is a host-composition view type, not an authorable one: objectui#5321 ruled it recorded rather than declared, and ObjectView.tsx states verbatim that its config surface is "not authoring surface to teach in the docs". The example taught, as authored metadata, the one shape that ruling forbids teaching. So the example now writes the `object-tree` node an author can actually select, bound through the exported `ObjectQLComponentSchema` union, which narrows on `type` and checks all five declared members. The host-only `tree` alias keeps its paragraph, as prose rather than as a copyable example. The four documented defaults were each checked against ObjectTree.tsx and were already correct; they are unchanged. Part of #5174 (batch 33) Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr --- packages/plugin-tree/README.md | 49 +++++++++++++++++++---------- scripts/check-doc-snippet-types.mjs | 2 -- 2 files changed, 32 insertions(+), 19 deletions(-) diff --git a/packages/plugin-tree/README.md b/packages/plugin-tree/README.md index f734448874..d71be52b38 100644 --- a/packages/plugin-tree/README.md +++ b/packages/plugin-tree/README.md @@ -9,28 +9,26 @@ handles *fixed-depth* hierarchies; a tree handles arbitrary depth.) It registers two component types via the `ComponentRegistry`: -- `object-tree` — the object-bound renderer -- `tree` — the view-type alias used by `ObjectView` / `ViewSwitcher` +- `object-tree` — the object-bound renderer, and the one an author selects +- `tree` — a view-type alias reached only by host composition (see below) ## Usage +Author an `object-tree` node. Its config keys sit **flat on the node**, and +`ObjectQLComponentSchema` narrows on `type`, so each one is checked against +`ObjectTreeSchema`: + ```ts -// As a view inside an ObjectView -{ - type: 'object-view', +import type { ObjectQLComponentSchema } from '@object-ui/types'; + +const schema: ObjectQLComponentSchema = { + type: 'object-tree', objectName: 'business_unit', - views: [ - { - type: 'tree', - tree: { - parentField: 'parent', // single-parent pointer (auto-detected if omitted) - labelField: 'name', // indented first column - fields: ['name', 'manager'], // additional flat columns - defaultExpandedDepth: 1, // 0 = roots only; omit = expand all - }, - }, - ], -} + parentField: 'parent', // single-parent pointer (auto-detected if omitted) + labelField: 'name', // indented first column + fields: ['name', 'manager'], // additional flat columns + defaultExpandedDepth: 1, // 0 = roots only; omit = expand all +}; ``` ### Config @@ -45,6 +43,23 @@ It registers two component types via the `ComponentRegistry`: Records whose parent is missing (or points outside the result set) are kept as roots, so nothing is silently dropped. +### The `tree` view type is host composition, not authoring + +`tree` is **not** an authorable view type. Neither `ObjectViewSchema.defaultViewType` +nor `NamedListView.type` admits it — both are the same seven-value union that stops +at `map` — so no authored document selects a tree view, and `ObjectViewSchema` +declares no `views` member at all. The `tree` branch runs only when a **host** +composes `ObjectView` with a `views` prop, whose entries carry `id` and `label` +and are typed `ViewType`. That was ruled deliberate on objectui#5321 +(2026-08-20): `tree` and `chart` are recorded as host-composition-only surfaces +rather than added to the authored unions. The per-view `tree` config block that +path reads is host config, so it is not documented here as authoring surface. + +The live consumer is the console: it passes stored view records to `ObjectView` +as `views`, and its create-view dialog offers `tree` among the types a console +user can create. To render a tree from authored metadata, write the +`object-tree` node above. + ## License MIT — see [LICENSE](./LICENSE). diff --git a/scripts/check-doc-snippet-types.mjs b/scripts/check-doc-snippet-types.mjs index 4493205203..8d41e80e81 100644 --- a/scripts/check-doc-snippet-types.mjs +++ b/scripts/check-doc-snippet-types.mjs @@ -781,8 +781,6 @@ const UNGATED_DOCS = { '1 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies; 1 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2322x1 — candidate real defects, un-triaged', 'packages/plugin-markdown/README.md': '2 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies', - 'packages/plugin-tree/README.md': - '3 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies', }; // ── Fence scanning ───────────────────────────────────────────────────────────