fix(types): tree-view mirror stops requiring the limb it reads third (group 2 of objectui#6939)

.changeset/6939-tree-view-nodes-mirror.md

@@ -0,0 +1,61 @@
+---
+'@object-ui/types': patch
+---
+
+Repair the `tree-view` mirror: `data` is optional, so the `nodes` spelling the
+renderer reads FIRST is a legal document on its own (objectui#6939, maintainer
+ruling recorded 2026-09-02 — this is one of the eight groups on that card,
+dispatched as its own PR per the ruling).
+
+`TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD:
+
+ const rawNodes = boundData || schema.nodes || schema.data || [];
+ // packages/components/src/renderers/data-display/tree-view.tsx:105
+
+The registration's own `inputs` and `defaultProps` spell it `nodes`, and the
+four `components-data-display-tree-view/*` catalog entries ARE those
+`defaultProps` — so `safeValidateSchema` refused every one of them
+(`: Invalid input`) while the renderer drew them correctly. Re-measured on
+`origin/main` at `fe4e7a9e8`: four refusals, and four renders that are
+byte-identical under either spelling (28 / 28 / 12 / 34 elements, same tag
+census, same `textContent` SHA-256). Identical output under the "correction" is
+objectui#6318's own triage test for *the schema was the wrong side*.
+
+**For AUTHORS this widens on both faces.** `data` goes from required to optional
+on the mirror and on the TypeScript twin in the same stroke; nothing that
+validated before validates less, and no document that type-checked as a literal
+stops doing so. A document authored on `data` — such as the tree-view entry in
+`packages/types/examples/data-display-examples.json` — is untouched, and both
+spellings together stay legal.
+
+**For a READER of the TypeScript twin this is a narrowing, and that is the half
+worth stating.** `TreeViewSchema['data']` is now `TreeNode[] | undefined`, so
+code that read `schema.data` and relied on its presence needs a guard and will
+otherwise stop compiling (measured on a consumer probe: exit 0 before, `TS2322`
+plus `TS18048` after). The only in-repo reader already has that guard —
+`renderers/data-display/tree-view.tsx:105` reads
+`boundData || schema.nodes || schema.data || []` — and it type-checks clean, so
+nothing in this repository changes. An out-of-repo consumer that reads the key
+unguarded is the population this paragraph exists for.
+
+Still `patch`: the required-ness was never a guarantee the renderer honoured (it
+reads the key third, behind a default), the accept set only grows, and this is
+the same shape as the two sibling groups of this card that have already landed.
+
+**`data` stays DECLARED rather than being deleted**, and the difference is
+measured rather than assumed: `BaseSchema` already declares `data`
+(`z.any().optional()`; `data?: any` on the TS face), so removing the member
+would not reject the key — it would admit it *unvalidated* while the renderer
+went on reading it. Optional-and-typed is the only shape in which `declared` and
+`enforced` agree for a key that is still read.
+
+**No refinement was added**, deliberately, unlike this card's
+`object-map` / `object-gantt` group. A tree-view carrying no data source at all
+becomes legal here, and that admits no new rendering outcome: `{ data: [] }` was
+already legal and already drew the same empty tree, so an "at least one of
+`nodes` / `data` / `bind`" rule would forbid a spelling of an empty state the
+contract already permits rather than buy a guarantee.
+
+`nodes` and `title` are objectui#6150's declarations and are unchanged; that
+card declared the reads and said in as many words that relaxing `data` was a
+separate accept-set change. This is that change.

content/docs/api/schema-reference.md

@@ -524,7 +524,8 @@ A hierarchical tree component for nested data with expand/collapse and selection
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | `TreeNode[]` | **Required.** Nested tree data. Each node has `id`, `label`, optional `icon` and `children`. |
+| `nodes` | `TreeNode[]` | Optional. Nested tree data — the spelling the renderer reads FIRST, and the one the component's own `inputs` and `defaultProps` use. Each node has `id`, `label`, optional `icon` and `children`. |
+| `data` | `TreeNode[]` | Optional. Nested tree data, read only when `nodes` is absent (the renderer reads `nodes` first — objectui#6939). |
 | `defaultExpandedIds` | `string[]` | Node IDs expanded on initial render. |
 | `defaultSelectedIds` | `string[]` | Node IDs selected on initial render. |
 | `expandedIds` | `string[]` | Controlled expanded state. |

examples/schema-catalog/test/tree-view-nodes-mirror-6939.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * objectui#6939, the `tree-view` group — the RENDER half. The validator-side
+ * contract is pinned in
+ * `packages/types/src/__tests__/tree-view-data-optional-6939.test.ts`.
+ *
+ * `TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD
+ * (`boundData || schema.nodes || schema.data || []`,
+ * `renderers/data-display/tree-view.tsx:105`), so all four catalog entries —
+ * which author `nodes`, the spelling the registration's own `inputs` and
+ * `defaultProps` use, and which ARE those `defaultProps` — were refused by
+ * `safeValidateSchema` while drawing correctly.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So a repair on the schema side has to
+ * clear the mirror image of that bar — the validator's verdict must change and
+ * the renderer's output must NOT. `PRE_REPAIR` was measured on `origin/main` at
+ * `fe4e7a9e8`, BEFORE either face was touched, through THIS file's harness.
+ *
+ * ⚠️ The card's table reports "identical — 14 elements" for this row. The
+ * identity reproduces exactly (all four tiles, element count, tag census and a
+ * SHA-256 of `textContent`); the absolute 14 does NOT reproduce in this
+ * harness, which measures 28 / 28 / 12 / 34. Element counts are harness-bound —
+ * the docs-gallery harness (`catalog-gallery-render.test.tsx`, provider plus
+ * `SidebarProvider` plus a padded wrapper) gives different absolutes for the
+ * same tile — so identity WITHIN one harness is the claim that discriminates,
+ * and the number is recorded here rather than carried over from the card.
+ *
+ * Three readings per tile, because a count alone cannot tell a swapped element
+ * from an equal one: element count, a tag census, and the text (literally, plus
+ * a SHA-256 of it).
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { createHash } from 'node:crypto';
+import '@object-ui/components';
+import { SchemaRenderer, toRenderableSchema } from '@object-ui/react';
+import { TreeViewSchema, safeValidateSchema } from '@object-ui/types/zod';
+import { getExample } from '../src/index.js';
+
+const IDS = [
+ 'components-data-display-tree-view/deep-nesting',
+ 'components-data-display-tree-view/file-tree',
+ 'components-data-display-tree-view/org-chart',
+ 'components-data-display-tree-view/sidebar-navigation',
+] as const;
+
+/**
+ * Measured on `origin/main` @ `fe4e7a9e8` through `measure()` below, both faces
+ * untouched. Every one of the four reported `: Invalid input` from
+ * `safeValidateSchema` at that commit, and every one drew exactly this.
+ */
+const PRE_REPAIR: Record<(typeof IDS)[number], {
+ elements: number;
+ tags: Record<string, number>;
+ text: string;
+ sha256: string;
+}> = {
+ 'components-data-display-tree-view/deep-nesting': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'Project Structuresrcpublicpackage.json',
+ sha256: 'e55f4d288401013fd1d6d5f1045e77eba31b07c9a62656efdcc94945e7503167',
+ },
+ 'components-data-display-tree-view/file-tree': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'File ExplorerDocumentsPhotosREADME.md',
+ sha256: '3f2f5a7468194a1af717c2c798a3dd4f9421df445b6c36dae9748eb83639d84a',
+ },
+ 'components-data-display-tree-view/org-chart': {
+ elements: 12,
+ tags: { DIV: 5, H3: 1, BUTTON: 1, svg: 2, path: 2, SPAN: 1 },
+ text: 'OrganizationCEO',
+ sha256: '45f07e1527f23fbd805de7c378192a8fc79d82641d0e98fc35e745d721a17985',
+ },
+ 'components-data-display-tree-view/sidebar-navigation': {
+ elements: 34,
+ tags: { DIV: 13, H3: 1, SPAN: 6, svg: 6, path: 6, BUTTON: 2 },
+ text: 'NavigationDashboardProductsOrdersSettings',
+ sha256: '6126579fe6fca4c4d9c5e25d1ca32f8d3967f2ec1fd1f88bcafa2d8c3f399d01',
+ },
+};
+
+/** Render one entry the way the docs gallery does and measure what it drew. */
+function measure(schema: unknown) {
+ const { container, unmount } = render(
+ <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />,
+ );
+ const nodes = Array.from(container.querySelectorAll('*'));
+ const text = container.textContent ?? '';
+ const out = {
+ elements: nodes.length,
+ tags: nodes.reduce<Record<string, number>>((h, el) => ((h[el.tagName] = (h[el.tagName] ?? 0) + 1), h), {}),
+ text,
+ sha256: createHash('sha256').update(text).digest('hex'),
+ };
+ unmount();
+ return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+ const r = safeValidateSchema(schema);
+ return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+/** The fixture as authored, and the "correction" objectui#6318's triage asks about. */
+function asAuthored(id: (typeof IDS)[number]) {
+ return getExample(id).schema as Record<string, unknown>;
+}
+function asDataSpelling(id: (typeof IDS)[number]) {
+ const { nodes, ...rest } = asAuthored(id);
+ return { ...rest, data: nodes };
+}
+
+describe('objectui#6939 — the four tree-view entries the mirror refused now validate', () => {
+ it.each(IDS)('%s validates under safeValidateSchema', (id) => {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+ it.each(IDS)('%s renders exactly what it rendered before', (id) => {
+ const after = measure(asAuthored(id));
+ const before = PRE_REPAIR[id];
+ expect(after.elements).toBe(before.elements);
+ expect(after.tags).toEqual(before.tags);
+ expect(after.text).toBe(before.text);
+ expect(after.sha256).toBe(before.sha256);
+ });
+
+ it.each(IDS)('%s anti-vacuity: the tile drew its AUTHORED tree, not an empty box', (id) => {
+ // A tile that renders nothing — or the error boundary — satisfies
+ // "identical" trivially. The authored title and every root label on screen
+ // prove the nodes reached the renderer through `nodes`, the spelling the
+ // mirror refused.
+ const schema = asAuthored(id) as { title: string; nodes: { label: string }[] };
+ const m = measure(schema);
+ expect(m.elements).toBeGreaterThan(10);
+ expect(m.text.trim().length).toBeGreaterThan(0);
+ expect(m.text).not.toContain('failed to render');
+ expect(m.text).toContain(schema.title);
+ for (const node of schema.nodes) expect(m.text).toContain(node.label);
+ });
+});
+
+describe('objectui#6939 — the fixtures were the side that was right', () => {
+ it.each(IDS)('%s: "correcting" it to `data` changes no pixel', (id) => {
+ // The card's own discriminator, re-measured here rather than quoted: the
+ // spelling swap moves nothing, so the schema was the wrong side. Contrast
+ // the same probe on the sibling groups, where the "correction" emptied the
+ // board or blanked the tile.
+ const authored = measure(asAuthored(id));
+ const corrected = measure(asDataSpelling(id));
+ expect(corrected.elements).toBe(authored.elements);
+ expect(corrected.text).toBe(authored.text);
+ expect(corrected.sha256).toBe(authored.sha256);
+ });
+
+ it.each(IDS)('%s stays on the spelling its renderer reads FIRST', (id) => {
+ const schema = asAuthored(id);
+ expect(schema.nodes).toBeDefined();
+ expect('data' in schema).toBe(false);
+ });
+
+ it('both spellings validate — the accept set widened, it did not move', () => {
+ // ⛔ Do NOT "repair" a future red here by migrating the fixtures to `data`.
+ // The renderer reads `nodes` first and the registration's `defaultProps`
+ // spell it `nodes`; the fixtures ARE those defaults.
+ for (const id of IDS) {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ expect(reasons(asDataSpelling(id))).toEqual([]);
+ }
+ });
+
+ it('the keys are DECLARED, not passthrough holes', () => {
+ // Counter-probes on keys the mirror declares; an unknown key proves nothing
+ // here, because `BaseSchema` is `.passthrough()`.
+ const shape = (TreeViewSchema as unknown as { shape: Record<string, unknown> }).shape;
+ expect(Object.keys(shape)).toEqual(expect.arrayContaining(['nodes', 'title', 'data']));
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', nodes: 'not-an-array' }).success).toBe(false);
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', data: 'not-an-array' }).success).toBe(false);
+ // …and a good shape still passes, so the two above are not failing for some
+ // unrelated reason. ⚠️ The carrier carries BOTH spellings on purpose: it is
+ // legal with or without this card, so this control cannot redden for the
+ // relaxation it is controlling for. (That the authored, `nodes`-only
+ // fixtures parse is the first describe block's claim, not this one's.)
+ expect(TreeViewSchema.safeParse({
+ type: 'tree-view', title: 'File Explorer', data: [], nodes: [{ id: '1', label: 'Documents' }],
+ }).success).toBe(true);
+ });
+});

.changeset/6939-tree-view-nodes-mirror.md

@@ -0,0 +1,61 @@
+---
+'@object-ui/types': patch
+---
+
+Repair the `tree-view` mirror: `data` is optional, so the `nodes` spelling the
+renderer reads FIRST is a legal document on its own (objectui#6939, maintainer
+ruling recorded 2026-09-02 — this is one of the eight groups on that card,
+dispatched as its own PR per the ruling).
+
+`TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD:
+
+ const rawNodes = boundData || schema.nodes || schema.data || [];
+ // packages/components/src/renderers/data-display/tree-view.tsx:105
+
+The registration's own `inputs` and `defaultProps` spell it `nodes`, and the
+four `components-data-display-tree-view/*` catalog entries ARE those
+`defaultProps` — so `safeValidateSchema` refused every one of them
+(`: Invalid input`) while the renderer drew them correctly. Re-measured on
+`origin/main` at `fe4e7a9e8`: four refusals, and four renders that are
+byte-identical under either spelling (28 / 28 / 12 / 34 elements, same tag
+census, same `textContent` SHA-256). Identical output under the "correction" is
+objectui#6318's own triage test for *the schema was the wrong side*.
+
+**For AUTHORS this widens on both faces.** `data` goes from required to optional
+on the mirror and on the TypeScript twin in the same stroke; nothing that
+validated before validates less, and no document that type-checked as a literal
+stops doing so. A document authored on `data` — such as the tree-view entry in
+`packages/types/examples/data-display-examples.json` — is untouched, and both
+spellings together stay legal.
+
+**For a READER of the TypeScript twin this is a narrowing, and that is the half
+worth stating.** `TreeViewSchema['data']` is now `TreeNode[] | undefined`, so
+code that read `schema.data` and relied on its presence needs a guard and will
+otherwise stop compiling (measured on a consumer probe: exit 0 before, `TS2322`
+plus `TS18048` after). The only in-repo reader already has that guard —
+`renderers/data-display/tree-view.tsx:105` reads
+`boundData || schema.nodes || schema.data || []` — and it type-checks clean, so
+nothing in this repository changes. An out-of-repo consumer that reads the key
+unguarded is the population this paragraph exists for.
+
+Still `patch`: the required-ness was never a guarantee the renderer honoured (it
+reads the key third, behind a default), the accept set only grows, and this is
+the same shape as the two sibling groups of this card that have already landed.
+
+**`data` stays DECLARED rather than being deleted**, and the difference is
+measured rather than assumed: `BaseSchema` already declares `data`
+(`z.any().optional()`; `data?: any` on the TS face), so removing the member
+would not reject the key — it would admit it *unvalidated* while the renderer
+went on reading it. Optional-and-typed is the only shape in which `declared` and
+`enforced` agree for a key that is still read.
+
+**No refinement was added**, deliberately, unlike this card's
+`object-map` / `object-gantt` group. A tree-view carrying no data source at all
+becomes legal here, and that admits no new rendering outcome: `{ data: [] }` was
+already legal and already drew the same empty tree, so an "at least one of
+`nodes` / `data` / `bind`" rule would forbid a spelling of an empty state the
+contract already permits rather than buy a guarantee.
+
+`nodes` and `title` are objectui#6150's declarations and are unchanged; that
+card declared the reads and said in as many words that relaxing `data` was a
+separate accept-set change. This is that change.

content/docs/api/schema-reference.md

@@ -524,7 +524,8 @@ A hierarchical tree component for nested data with expand/collapse and selection
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | `TreeNode[]` | **Required.** Nested tree data. Each node has `id`, `label`, optional `icon` and `children`. |
+| `nodes` | `TreeNode[]` | Optional. Nested tree data — the spelling the renderer reads FIRST, and the one the component's own `inputs` and `defaultProps` use. Each node has `id`, `label`, optional `icon` and `children`. |
+| `data` | `TreeNode[]` | Optional. Nested tree data, read only when `nodes` is absent (the renderer reads `nodes` first — objectui#6939). |
 | `defaultExpandedIds` | `string[]` | Node IDs expanded on initial render. |
 | `defaultSelectedIds` | `string[]` | Node IDs selected on initial render. |
 | `expandedIds` | `string[]` | Controlled expanded state. |

examples/schema-catalog/test/tree-view-nodes-mirror-6939.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * objectui#6939, the `tree-view` group — the RENDER half. The validator-side
+ * contract is pinned in
+ * `packages/types/src/__tests__/tree-view-data-optional-6939.test.ts`.
+ *
+ * `TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD
+ * (`boundData || schema.nodes || schema.data || []`,
+ * `renderers/data-display/tree-view.tsx:105`), so all four catalog entries —
+ * which author `nodes`, the spelling the registration's own `inputs` and
+ * `defaultProps` use, and which ARE those `defaultProps` — were refused by
+ * `safeValidateSchema` while drawing correctly.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So a repair on the schema side has to
+ * clear the mirror image of that bar — the validator's verdict must change and
+ * the renderer's output must NOT. `PRE_REPAIR` was measured on `origin/main` at
+ * `fe4e7a9e8`, BEFORE either face was touched, through THIS file's harness.
+ *
+ * ⚠️ The card's table reports "identical — 14 elements" for this row. The
+ * identity reproduces exactly (all four tiles, element count, tag census and a
+ * SHA-256 of `textContent`); the absolute 14 does NOT reproduce in this
+ * harness, which measures 28 / 28 / 12 / 34. Element counts are harness-bound —
+ * the docs-gallery harness (`catalog-gallery-render.test.tsx`, provider plus
+ * `SidebarProvider` plus a padded wrapper) gives different absolutes for the
+ * same tile — so identity WITHIN one harness is the claim that discriminates,
+ * and the number is recorded here rather than carried over from the card.
+ *
+ * Three readings per tile, because a count alone cannot tell a swapped element
+ * from an equal one: element count, a tag census, and the text (literally, plus
+ * a SHA-256 of it).
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { createHash } from 'node:crypto';
+import '@object-ui/components';
+import { SchemaRenderer, toRenderableSchema } from '@object-ui/react';
+import { TreeViewSchema, safeValidateSchema } from '@object-ui/types/zod';
+import { getExample } from '../src/index.js';
+
+const IDS = [
+ 'components-data-display-tree-view/deep-nesting',
+ 'components-data-display-tree-view/file-tree',
+ 'components-data-display-tree-view/org-chart',
+ 'components-data-display-tree-view/sidebar-navigation',
+] as const;
+
+/**
+ * Measured on `origin/main` @ `fe4e7a9e8` through `measure()` below, both faces
+ * untouched. Every one of the four reported `: Invalid input` from
+ * `safeValidateSchema` at that commit, and every one drew exactly this.
+ */
+const PRE_REPAIR: Record<(typeof IDS)[number], {
+ elements: number;
+ tags: Record<string, number>;
+ text: string;
+ sha256: string;
+}> = {
+ 'components-data-display-tree-view/deep-nesting': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'Project Structuresrcpublicpackage.json',
+ sha256: 'e55f4d288401013fd1d6d5f1045e77eba31b07c9a62656efdcc94945e7503167',
+ },
+ 'components-data-display-tree-view/file-tree': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'File ExplorerDocumentsPhotosREADME.md',
+ sha256: '3f2f5a7468194a1af717c2c798a3dd4f9421df445b6c36dae9748eb83639d84a',
+ },
+ 'components-data-display-tree-view/org-chart': {
+ elements: 12,
+ tags: { DIV: 5, H3: 1, BUTTON: 1, svg: 2, path: 2, SPAN: 1 },
+ text: 'OrganizationCEO',
+ sha256: '45f07e1527f23fbd805de7c378192a8fc79d82641d0e98fc35e745d721a17985',
+ },
+ 'components-data-display-tree-view/sidebar-navigation': {
+ elements: 34,
+ tags: { DIV: 13, H3: 1, SPAN: 6, svg: 6, path: 6, BUTTON: 2 },
+ text: 'NavigationDashboardProductsOrdersSettings',
+ sha256: '6126579fe6fca4c4d9c5e25d1ca32f8d3967f2ec1fd1f88bcafa2d8c3f399d01',
+ },
+};
+
+/** Render one entry the way the docs gallery does and measure what it drew. */
+function measure(schema: unknown) {
+ const { container, unmount } = render(
+ <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />,
+ );
+ const nodes = Array.from(container.querySelectorAll('*'));
+ const text = container.textContent ?? '';
+ const out = {
+ elements: nodes.length,
+ tags: nodes.reduce<Record<string, number>>((h, el) => ((h[el.tagName] = (h[el.tagName] ?? 0) + 1), h), {}),
+ text,
+ sha256: createHash('sha256').update(text).digest('hex'),
+ };
+ unmount();
+ return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+ const r = safeValidateSchema(schema);
+ return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+/** The fixture as authored, and the "correction" objectui#6318's triage asks about. */
+function asAuthored(id: (typeof IDS)[number]) {
+ return getExample(id).schema as Record<string, unknown>;
+}
+function asDataSpelling(id: (typeof IDS)[number]) {
+ const { nodes, ...rest } = asAuthored(id);
+ return { ...rest, data: nodes };
+}
+
+describe('objectui#6939 — the four tree-view entries the mirror refused now validate', () => {
+ it.each(IDS)('%s validates under safeValidateSchema', (id) => {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+ it.each(IDS)('%s renders exactly what it rendered before', (id) => {
+ const after = measure(asAuthored(id));
+ const before = PRE_REPAIR[id];
+ expect(after.elements).toBe(before.elements);
+ expect(after.tags).toEqual(before.tags);
+ expect(after.text).toBe(before.text);
+ expect(after.sha256).toBe(before.sha256);
+ });
+
+ it.each(IDS)('%s anti-vacuity: the tile drew its AUTHORED tree, not an empty box', (id) => {
+ // A tile that renders nothing — or the error boundary — satisfies
+ // "identical" trivially. The authored title and every root label on screen
+ // prove the nodes reached the renderer through `nodes`, the spelling the
+ // mirror refused.
+ const schema = asAuthored(id) as { title: string; nodes: { label: string }[] };
+ const m = measure(schema);
+ expect(m.elements).toBeGreaterThan(10);
+ expect(m.text.trim().length).toBeGreaterThan(0);
+ expect(m.text).not.toContain('failed to render');
+ expect(m.text).toContain(schema.title);
+ for (const node of schema.nodes) expect(m.text).toContain(node.label);
+ });
+});
+
+describe('objectui#6939 — the fixtures were the side that was right', () => {
+ it.each(IDS)('%s: "correcting" it to `data` changes no pixel', (id) => {
+ // The card's own discriminator, re-measured here rather than quoted: the
+ // spelling swap moves nothing, so the schema was the wrong side. Contrast
+ // the same probe on the sibling groups, where the "correction" emptied the
+ // board or blanked the tile.
+ const authored = measure(asAuthored(id));
+ const corrected = measure(asDataSpelling(id));
+ expect(corrected.elements).toBe(authored.elements);
+ expect(corrected.text).toBe(authored.text);
+ expect(corrected.sha256).toBe(authored.sha256);
+ });
+
+ it.each(IDS)('%s stays on the spelling its renderer reads FIRST', (id) => {
+ const schema = asAuthored(id);
+ expect(schema.nodes).toBeDefined();
+ expect('data' in schema).toBe(false);
+ });
+
+ it('both spellings validate — the accept set widened, it did not move', () => {
+ // ⛔ Do NOT "repair" a future red here by migrating the fixtures to `data`.
+ // The renderer reads `nodes` first and the registration's `defaultProps`
+ // spell it `nodes`; the fixtures ARE those defaults.
+ for (const id of IDS) {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ expect(reasons(asDataSpelling(id))).toEqual([]);
+ }
+ });
+
+ it('the keys are DECLARED, not passthrough holes', () => {
+ // Counter-probes on keys the mirror declares; an unknown key proves nothing
+ // here, because `BaseSchema` is `.passthrough()`.
+ const shape = (TreeViewSchema as unknown as { shape: Record<string, unknown> }).shape;
+ expect(Object.keys(shape)).toEqual(expect.arrayContaining(['nodes', 'title', 'data']));
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', nodes: 'not-an-array' }).success).toBe(false);
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', data: 'not-an-array' }).success).toBe(false);
+ // …and a good shape still passes, so the two above are not failing for some
+ // unrelated reason. ⚠️ The carrier carries BOTH spellings on purpose: it is
+ // legal with or without this card, so this control cannot redden for the
+ // relaxation it is controlling for. (That the authored, `nodes`-only
+ // fixtures parse is the first describe block's claim, not this one's.)
+ expect(TreeViewSchema.safeParse({
+ type: 'tree-view', title: 'File Explorer', data: [], nodes: [{ id: '1', label: 'Documents' }],
+ }).success).toBe(true);
+ });
+});

.changeset/6939-tree-view-nodes-mirror.md

@@ -0,0 +1,61 @@
+---
+'@object-ui/types': patch
+---
+
+Repair the `tree-view` mirror: `data` is optional, so the `nodes` spelling the
+renderer reads FIRST is a legal document on its own (objectui#6939, maintainer
+ruling recorded 2026-09-02 — this is one of the eight groups on that card,
+dispatched as its own PR per the ruling).
+
+`TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD:
+
+ const rawNodes = boundData || schema.nodes || schema.data || [];
+ // packages/components/src/renderers/data-display/tree-view.tsx:105
+
+The registration's own `inputs` and `defaultProps` spell it `nodes`, and the
+four `components-data-display-tree-view/*` catalog entries ARE those
+`defaultProps` — so `safeValidateSchema` refused every one of them
+(`: Invalid input`) while the renderer drew them correctly. Re-measured on
+`origin/main` at `fe4e7a9e8`: four refusals, and four renders that are
+byte-identical under either spelling (28 / 28 / 12 / 34 elements, same tag
+census, same `textContent` SHA-256). Identical output under the "correction" is
+objectui#6318's own triage test for *the schema was the wrong side*.
+
+**For AUTHORS this widens on both faces.** `data` goes from required to optional
+on the mirror and on the TypeScript twin in the same stroke; nothing that
+validated before validates less, and no document that type-checked as a literal
+stops doing so. A document authored on `data` — such as the tree-view entry in
+`packages/types/examples/data-display-examples.json` — is untouched, and both
+spellings together stay legal.
+
+**For a READER of the TypeScript twin this is a narrowing, and that is the half
+worth stating.** `TreeViewSchema['data']` is now `TreeNode[] | undefined`, so
+code that read `schema.data` and relied on its presence needs a guard and will
+otherwise stop compiling (measured on a consumer probe: exit 0 before, `TS2322`
+plus `TS18048` after). The only in-repo reader already has that guard —
+`renderers/data-display/tree-view.tsx:105` reads
+`boundData || schema.nodes || schema.data || []` — and it type-checks clean, so
+nothing in this repository changes. An out-of-repo consumer that reads the key
+unguarded is the population this paragraph exists for.
+
+Still `patch`: the required-ness was never a guarantee the renderer honoured (it
+reads the key third, behind a default), the accept set only grows, and this is
+the same shape as the two sibling groups of this card that have already landed.
+
+**`data` stays DECLARED rather than being deleted**, and the difference is
+measured rather than assumed: `BaseSchema` already declares `data`
+(`z.any().optional()`; `data?: any` on the TS face), so removing the member
+would not reject the key — it would admit it *unvalidated* while the renderer
+went on reading it. Optional-and-typed is the only shape in which `declared` and
+`enforced` agree for a key that is still read.
+
+**No refinement was added**, deliberately, unlike this card's
+`object-map` / `object-gantt` group. A tree-view carrying no data source at all
+becomes legal here, and that admits no new rendering outcome: `{ data: [] }` was
+already legal and already drew the same empty tree, so an "at least one of
+`nodes` / `data` / `bind`" rule would forbid a spelling of an empty state the
+contract already permits rather than buy a guarantee.
+
+`nodes` and `title` are objectui#6150's declarations and are unchanged; that
+card declared the reads and said in as many words that relaxing `data` was a
+separate accept-set change. This is that change.

content/docs/api/schema-reference.md

@@ -524,7 +524,8 @@ A hierarchical tree component for nested data with expand/collapse and selection
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | `TreeNode[]` | **Required.** Nested tree data. Each node has `id`, `label`, optional `icon` and `children`. |
+| `nodes` | `TreeNode[]` | Optional. Nested tree data — the spelling the renderer reads FIRST, and the one the component's own `inputs` and `defaultProps` use. Each node has `id`, `label`, optional `icon` and `children`. |
+| `data` | `TreeNode[]` | Optional. Nested tree data, read only when `nodes` is absent (the renderer reads `nodes` first — objectui#6939). |
 | `defaultExpandedIds` | `string[]` | Node IDs expanded on initial render. |
 | `defaultSelectedIds` | `string[]` | Node IDs selected on initial render. |
 | `expandedIds` | `string[]` | Controlled expanded state. |

examples/schema-catalog/test/tree-view-nodes-mirror-6939.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * objectui#6939, the `tree-view` group — the RENDER half. The validator-side
+ * contract is pinned in
+ * `packages/types/src/__tests__/tree-view-data-optional-6939.test.ts`.
+ *
+ * `TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD
+ * (`boundData || schema.nodes || schema.data || []`,
+ * `renderers/data-display/tree-view.tsx:105`), so all four catalog entries —
+ * which author `nodes`, the spelling the registration's own `inputs` and
+ * `defaultProps` use, and which ARE those `defaultProps` — were refused by
+ * `safeValidateSchema` while drawing correctly.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So a repair on the schema side has to
+ * clear the mirror image of that bar — the validator's verdict must change and
+ * the renderer's output must NOT. `PRE_REPAIR` was measured on `origin/main` at
+ * `fe4e7a9e8`, BEFORE either face was touched, through THIS file's harness.
+ *
+ * ⚠️ The card's table reports "identical — 14 elements" for this row. The
+ * identity reproduces exactly (all four tiles, element count, tag census and a
+ * SHA-256 of `textContent`); the absolute 14 does NOT reproduce in this
+ * harness, which measures 28 / 28 / 12 / 34. Element counts are harness-bound —
+ * the docs-gallery harness (`catalog-gallery-render.test.tsx`, provider plus
+ * `SidebarProvider` plus a padded wrapper) gives different absolutes for the
+ * same tile — so identity WITHIN one harness is the claim that discriminates,
+ * and the number is recorded here rather than carried over from the card.
+ *
+ * Three readings per tile, because a count alone cannot tell a swapped element
+ * from an equal one: element count, a tag census, and the text (literally, plus
+ * a SHA-256 of it).
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { createHash } from 'node:crypto';
+import '@object-ui/components';
+import { SchemaRenderer, toRenderableSchema } from '@object-ui/react';
+import { TreeViewSchema, safeValidateSchema } from '@object-ui/types/zod';
+import { getExample } from '../src/index.js';
+
+const IDS = [
+ 'components-data-display-tree-view/deep-nesting',
+ 'components-data-display-tree-view/file-tree',
+ 'components-data-display-tree-view/org-chart',
+ 'components-data-display-tree-view/sidebar-navigation',
+] as const;
+
+/**
+ * Measured on `origin/main` @ `fe4e7a9e8` through `measure()` below, both faces
+ * untouched. Every one of the four reported `: Invalid input` from
+ * `safeValidateSchema` at that commit, and every one drew exactly this.
+ */
+const PRE_REPAIR: Record<(typeof IDS)[number], {
+ elements: number;
+ tags: Record<string, number>;
+ text: string;
+ sha256: string;
+}> = {
+ 'components-data-display-tree-view/deep-nesting': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'Project Structuresrcpublicpackage.json',
+ sha256: 'e55f4d288401013fd1d6d5f1045e77eba31b07c9a62656efdcc94945e7503167',
+ },
+ 'components-data-display-tree-view/file-tree': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'File ExplorerDocumentsPhotosREADME.md',
+ sha256: '3f2f5a7468194a1af717c2c798a3dd4f9421df445b6c36dae9748eb83639d84a',
+ },
+ 'components-data-display-tree-view/org-chart': {
+ elements: 12,
+ tags: { DIV: 5, H3: 1, BUTTON: 1, svg: 2, path: 2, SPAN: 1 },
+ text: 'OrganizationCEO',
+ sha256: '45f07e1527f23fbd805de7c378192a8fc79d82641d0e98fc35e745d721a17985',
+ },
+ 'components-data-display-tree-view/sidebar-navigation': {
+ elements: 34,
+ tags: { DIV: 13, H3: 1, SPAN: 6, svg: 6, path: 6, BUTTON: 2 },
+ text: 'NavigationDashboardProductsOrdersSettings',
+ sha256: '6126579fe6fca4c4d9c5e25d1ca32f8d3967f2ec1fd1f88bcafa2d8c3f399d01',
+ },
+};
+
+/** Render one entry the way the docs gallery does and measure what it drew. */
+function measure(schema: unknown) {
+ const { container, unmount } = render(
+ <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />,
+ );
+ const nodes = Array.from(container.querySelectorAll('*'));
+ const text = container.textContent ?? '';
+ const out = {
+ elements: nodes.length,
+ tags: nodes.reduce<Record<string, number>>((h, el) => ((h[el.tagName] = (h[el.tagName] ?? 0) + 1), h), {}),
+ text,
+ sha256: createHash('sha256').update(text).digest('hex'),
+ };
+ unmount();
+ return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+ const r = safeValidateSchema(schema);
+ return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+/** The fixture as authored, and the "correction" objectui#6318's triage asks about. */
+function asAuthored(id: (typeof IDS)[number]) {
+ return getExample(id).schema as Record<string, unknown>;
+}
+function asDataSpelling(id: (typeof IDS)[number]) {
+ const { nodes, ...rest } = asAuthored(id);
+ return { ...rest, data: nodes };
+}
+
+describe('objectui#6939 — the four tree-view entries the mirror refused now validate', () => {
+ it.each(IDS)('%s validates under safeValidateSchema', (id) => {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+ it.each(IDS)('%s renders exactly what it rendered before', (id) => {
+ const after = measure(asAuthored(id));
+ const before = PRE_REPAIR[id];
+ expect(after.elements).toBe(before.elements);
+ expect(after.tags).toEqual(before.tags);
+ expect(after.text).toBe(before.text);
+ expect(after.sha256).toBe(before.sha256);
+ });
+
+ it.each(IDS)('%s anti-vacuity: the tile drew its AUTHORED tree, not an empty box', (id) => {
+ // A tile that renders nothing — or the error boundary — satisfies
+ // "identical" trivially. The authored title and every root label on screen
+ // prove the nodes reached the renderer through `nodes`, the spelling the
+ // mirror refused.
+ const schema = asAuthored(id) as { title: string; nodes: { label: string }[] };
+ const m = measure(schema);
+ expect(m.elements).toBeGreaterThan(10);
+ expect(m.text.trim().length).toBeGreaterThan(0);
+ expect(m.text).not.toContain('failed to render');
+ expect(m.text).toContain(schema.title);
+ for (const node of schema.nodes) expect(m.text).toContain(node.label);
+ });
+});
+
+describe('objectui#6939 — the fixtures were the side that was right', () => {
+ it.each(IDS)('%s: "correcting" it to `data` changes no pixel', (id) => {
+ // The card's own discriminator, re-measured here rather than quoted: the
+ // spelling swap moves nothing, so the schema was the wrong side. Contrast
+ // the same probe on the sibling groups, where the "correction" emptied the
+ // board or blanked the tile.
+ const authored = measure(asAuthored(id));
+ const corrected = measure(asDataSpelling(id));
+ expect(corrected.elements).toBe(authored.elements);
+ expect(corrected.text).toBe(authored.text);
+ expect(corrected.sha256).toBe(authored.sha256);
+ });
+
+ it.each(IDS)('%s stays on the spelling its renderer reads FIRST', (id) => {
+ const schema = asAuthored(id);
+ expect(schema.nodes).toBeDefined();
+ expect('data' in schema).toBe(false);
+ });
+
+ it('both spellings validate — the accept set widened, it did not move', () => {
+ // ⛔ Do NOT "repair" a future red here by migrating the fixtures to `data`.
+ // The renderer reads `nodes` first and the registration's `defaultProps`
+ // spell it `nodes`; the fixtures ARE those defaults.
+ for (const id of IDS) {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ expect(reasons(asDataSpelling(id))).toEqual([]);
+ }
+ });
+
+ it('the keys are DECLARED, not passthrough holes', () => {
+ // Counter-probes on keys the mirror declares; an unknown key proves nothing
+ // here, because `BaseSchema` is `.passthrough()`.
+ const shape = (TreeViewSchema as unknown as { shape: Record<string, unknown> }).shape;
+ expect(Object.keys(shape)).toEqual(expect.arrayContaining(['nodes', 'title', 'data']));
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', nodes: 'not-an-array' }).success).toBe(false);
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', data: 'not-an-array' }).success).toBe(false);
+ // …and a good shape still passes, so the two above are not failing for some
+ // unrelated reason. ⚠️ The carrier carries BOTH spellings on purpose: it is
+ // legal with or without this card, so this control cannot redden for the
+ // relaxation it is controlling for. (That the authored, `nodes`-only
+ // fixtures parse is the first describe block's claim, not this one's.)
+ expect(TreeViewSchema.safeParse({
+ type: 'tree-view', title: 'File Explorer', data: [], nodes: [{ id: '1', label: 'Documents' }],
+ }).success).toBe(true);
+ });
+});

.changeset/6939-tree-view-nodes-mirror.md

@@ -0,0 +1,61 @@
+---
+'@object-ui/types': patch
+---
+
+Repair the `tree-view` mirror: `data` is optional, so the `nodes` spelling the
+renderer reads FIRST is a legal document on its own (objectui#6939, maintainer
+ruling recorded 2026-09-02 — this is one of the eight groups on that card,
+dispatched as its own PR per the ruling).
+
+`TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD:
+
+ const rawNodes = boundData || schema.nodes || schema.data || [];
+ // packages/components/src/renderers/data-display/tree-view.tsx:105
+
+The registration's own `inputs` and `defaultProps` spell it `nodes`, and the
+four `components-data-display-tree-view/*` catalog entries ARE those
+`defaultProps` — so `safeValidateSchema` refused every one of them
+(`: Invalid input`) while the renderer drew them correctly. Re-measured on
+`origin/main` at `fe4e7a9e8`: four refusals, and four renders that are
+byte-identical under either spelling (28 / 28 / 12 / 34 elements, same tag
+census, same `textContent` SHA-256). Identical output under the "correction" is
+objectui#6318's own triage test for *the schema was the wrong side*.
+
+**For AUTHORS this widens on both faces.** `data` goes from required to optional
+on the mirror and on the TypeScript twin in the same stroke; nothing that
+validated before validates less, and no document that type-checked as a literal
+stops doing so. A document authored on `data` — such as the tree-view entry in
+`packages/types/examples/data-display-examples.json` — is untouched, and both
+spellings together stay legal.
+
+**For a READER of the TypeScript twin this is a narrowing, and that is the half
+worth stating.** `TreeViewSchema['data']` is now `TreeNode[] | undefined`, so
+code that read `schema.data` and relied on its presence needs a guard and will
+otherwise stop compiling (measured on a consumer probe: exit 0 before, `TS2322`
+plus `TS18048` after). The only in-repo reader already has that guard —
+`renderers/data-display/tree-view.tsx:105` reads
+`boundData || schema.nodes || schema.data || []` — and it type-checks clean, so
+nothing in this repository changes. An out-of-repo consumer that reads the key
+unguarded is the population this paragraph exists for.
+
+Still `patch`: the required-ness was never a guarantee the renderer honoured (it
+reads the key third, behind a default), the accept set only grows, and this is
+the same shape as the two sibling groups of this card that have already landed.
+
+**`data` stays DECLARED rather than being deleted**, and the difference is
+measured rather than assumed: `BaseSchema` already declares `data`
+(`z.any().optional()`; `data?: any` on the TS face), so removing the member
+would not reject the key — it would admit it *unvalidated* while the renderer
+went on reading it. Optional-and-typed is the only shape in which `declared` and
+`enforced` agree for a key that is still read.
+
+**No refinement was added**, deliberately, unlike this card's
+`object-map` / `object-gantt` group. A tree-view carrying no data source at all
+becomes legal here, and that admits no new rendering outcome: `{ data: [] }` was
+already legal and already drew the same empty tree, so an "at least one of
+`nodes` / `data` / `bind`" rule would forbid a spelling of an empty state the
+contract already permits rather than buy a guarantee.
+
+`nodes` and `title` are objectui#6150's declarations and are unchanged; that
+card declared the reads and said in as many words that relaxing `data` was a
+separate accept-set change. This is that change.

content/docs/api/schema-reference.md

@@ -524,7 +524,8 @@ A hierarchical tree component for nested data with expand/collapse and selection
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | `TreeNode[]` | **Required.** Nested tree data. Each node has `id`, `label`, optional `icon` and `children`. |
+| `nodes` | `TreeNode[]` | Optional. Nested tree data — the spelling the renderer reads FIRST, and the one the component's own `inputs` and `defaultProps` use. Each node has `id`, `label`, optional `icon` and `children`. |
+| `data` | `TreeNode[]` | Optional. Nested tree data, read only when `nodes` is absent (the renderer reads `nodes` first — objectui#6939). |
 | `defaultExpandedIds` | `string[]` | Node IDs expanded on initial render. |
 | `defaultSelectedIds` | `string[]` | Node IDs selected on initial render. |
 | `expandedIds` | `string[]` | Controlled expanded state. |

examples/schema-catalog/test/tree-view-nodes-mirror-6939.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * objectui#6939, the `tree-view` group — the RENDER half. The validator-side
+ * contract is pinned in
+ * `packages/types/src/__tests__/tree-view-data-optional-6939.test.ts`.
+ *
+ * `TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD
+ * (`boundData || schema.nodes || schema.data || []`,
+ * `renderers/data-display/tree-view.tsx:105`), so all four catalog entries —
+ * which author `nodes`, the spelling the registration's own `inputs` and
+ * `defaultProps` use, and which ARE those `defaultProps` — were refused by
+ * `safeValidateSchema` while drawing correctly.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So a repair on the schema side has to
+ * clear the mirror image of that bar — the validator's verdict must change and
+ * the renderer's output must NOT. `PRE_REPAIR` was measured on `origin/main` at
+ * `fe4e7a9e8`, BEFORE either face was touched, through THIS file's harness.
+ *
+ * ⚠️ The card's table reports "identical — 14 elements" for this row. The
+ * identity reproduces exactly (all four tiles, element count, tag census and a
+ * SHA-256 of `textContent`); the absolute 14 does NOT reproduce in this
+ * harness, which measures 28 / 28 / 12 / 34. Element counts are harness-bound —
+ * the docs-gallery harness (`catalog-gallery-render.test.tsx`, provider plus
+ * `SidebarProvider` plus a padded wrapper) gives different absolutes for the
+ * same tile — so identity WITHIN one harness is the claim that discriminates,
+ * and the number is recorded here rather than carried over from the card.
+ *
+ * Three readings per tile, because a count alone cannot tell a swapped element
+ * from an equal one: element count, a tag census, and the text (literally, plus
+ * a SHA-256 of it).
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { createHash } from 'node:crypto';
+import '@object-ui/components';
+import { SchemaRenderer, toRenderableSchema } from '@object-ui/react';
+import { TreeViewSchema, safeValidateSchema } from '@object-ui/types/zod';
+import { getExample } from '../src/index.js';
+
+const IDS = [
+ 'components-data-display-tree-view/deep-nesting',
+ 'components-data-display-tree-view/file-tree',
+ 'components-data-display-tree-view/org-chart',
+ 'components-data-display-tree-view/sidebar-navigation',
+] as const;
+
+/**
+ * Measured on `origin/main` @ `fe4e7a9e8` through `measure()` below, both faces
+ * untouched. Every one of the four reported `: Invalid input` from
+ * `safeValidateSchema` at that commit, and every one drew exactly this.
+ */
+const PRE_REPAIR: Record<(typeof IDS)[number], {
+ elements: number;
+ tags: Record<string, number>;
+ text: string;
+ sha256: string;
+}> = {
+ 'components-data-display-tree-view/deep-nesting': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'Project Structuresrcpublicpackage.json',
+ sha256: 'e55f4d288401013fd1d6d5f1045e77eba31b07c9a62656efdcc94945e7503167',
+ },
+ 'components-data-display-tree-view/file-tree': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'File ExplorerDocumentsPhotosREADME.md',
+ sha256: '3f2f5a7468194a1af717c2c798a3dd4f9421df445b6c36dae9748eb83639d84a',
+ },
+ 'components-data-display-tree-view/org-chart': {
+ elements: 12,
+ tags: { DIV: 5, H3: 1, BUTTON: 1, svg: 2, path: 2, SPAN: 1 },
+ text: 'OrganizationCEO',
+ sha256: '45f07e1527f23fbd805de7c378192a8fc79d82641d0e98fc35e745d721a17985',
+ },
+ 'components-data-display-tree-view/sidebar-navigation': {
+ elements: 34,
+ tags: { DIV: 13, H3: 1, SPAN: 6, svg: 6, path: 6, BUTTON: 2 },
+ text: 'NavigationDashboardProductsOrdersSettings',
+ sha256: '6126579fe6fca4c4d9c5e25d1ca32f8d3967f2ec1fd1f88bcafa2d8c3f399d01',
+ },
+};
+
+/** Render one entry the way the docs gallery does and measure what it drew. */
+function measure(schema: unknown) {
+ const { container, unmount } = render(
+ <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />,
+ );
+ const nodes = Array.from(container.querySelectorAll('*'));
+ const text = container.textContent ?? '';
+ const out = {
+ elements: nodes.length,
+ tags: nodes.reduce<Record<string, number>>((h, el) => ((h[el.tagName] = (h[el.tagName] ?? 0) + 1), h), {}),
+ text,
+ sha256: createHash('sha256').update(text).digest('hex'),
+ };
+ unmount();
+ return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+ const r = safeValidateSchema(schema);
+ return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+/** The fixture as authored, and the "correction" objectui#6318's triage asks about. */
+function asAuthored(id: (typeof IDS)[number]) {
+ return getExample(id).schema as Record<string, unknown>;
+}
+function asDataSpelling(id: (typeof IDS)[number]) {
+ const { nodes, ...rest } = asAuthored(id);
+ return { ...rest, data: nodes };
+}
+
+describe('objectui#6939 — the four tree-view entries the mirror refused now validate', () => {
+ it.each(IDS)('%s validates under safeValidateSchema', (id) => {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+ it.each(IDS)('%s renders exactly what it rendered before', (id) => {
+ const after = measure(asAuthored(id));
+ const before = PRE_REPAIR[id];
+ expect(after.elements).toBe(before.elements);
+ expect(after.tags).toEqual(before.tags);
+ expect(after.text).toBe(before.text);
+ expect(after.sha256).toBe(before.sha256);
+ });
+
+ it.each(IDS)('%s anti-vacuity: the tile drew its AUTHORED tree, not an empty box', (id) => {
+ // A tile that renders nothing — or the error boundary — satisfies
+ // "identical" trivially. The authored title and every root label on screen
+ // prove the nodes reached the renderer through `nodes`, the spelling the
+ // mirror refused.
+ const schema = asAuthored(id) as { title: string; nodes: { label: string }[] };
+ const m = measure(schema);
+ expect(m.elements).toBeGreaterThan(10);
+ expect(m.text.trim().length).toBeGreaterThan(0);
+ expect(m.text).not.toContain('failed to render');
+ expect(m.text).toContain(schema.title);
+ for (const node of schema.nodes) expect(m.text).toContain(node.label);
+ });
+});
+
+describe('objectui#6939 — the fixtures were the side that was right', () => {
+ it.each(IDS)('%s: "correcting" it to `data` changes no pixel', (id) => {
+ // The card's own discriminator, re-measured here rather than quoted: the
+ // spelling swap moves nothing, so the schema was the wrong side. Contrast
+ // the same probe on the sibling groups, where the "correction" emptied the
+ // board or blanked the tile.
+ const authored = measure(asAuthored(id));
+ const corrected = measure(asDataSpelling(id));
+ expect(corrected.elements).toBe(authored.elements);
+ expect(corrected.text).toBe(authored.text);
+ expect(corrected.sha256).toBe(authored.sha256);
+ });
+
+ it.each(IDS)('%s stays on the spelling its renderer reads FIRST', (id) => {
+ const schema = asAuthored(id);
+ expect(schema.nodes).toBeDefined();
+ expect('data' in schema).toBe(false);
+ });
+
+ it('both spellings validate — the accept set widened, it did not move', () => {
+ // ⛔ Do NOT "repair" a future red here by migrating the fixtures to `data`.
+ // The renderer reads `nodes` first and the registration's `defaultProps`
+ // spell it `nodes`; the fixtures ARE those defaults.
+ for (const id of IDS) {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ expect(reasons(asDataSpelling(id))).toEqual([]);
+ }
+ });
+
+ it('the keys are DECLARED, not passthrough holes', () => {
+ // Counter-probes on keys the mirror declares; an unknown key proves nothing
+ // here, because `BaseSchema` is `.passthrough()`.
+ const shape = (TreeViewSchema as unknown as { shape: Record<string, unknown> }).shape;
+ expect(Object.keys(shape)).toEqual(expect.arrayContaining(['nodes', 'title', 'data']));
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', nodes: 'not-an-array' }).success).toBe(false);
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', data: 'not-an-array' }).success).toBe(false);
+ // …and a good shape still passes, so the two above are not failing for some
+ // unrelated reason. ⚠️ The carrier carries BOTH spellings on purpose: it is
+ // legal with or without this card, so this control cannot redden for the
+ // relaxation it is controlling for. (That the authored, `nodes`-only
+ // fixtures parse is the first describe block's claim, not this one's.)
+ expect(TreeViewSchema.safeParse({
+ type: 'tree-view', title: 'File Explorer', data: [], nodes: [{ id: '1', label: 'Documents' }],
+ }).success).toBe(true);
+ });
+});

.changeset/6939-tree-view-nodes-mirror.md

@@ -0,0 +1,61 @@
+---
+'@object-ui/types': patch
+---
+
+Repair the `tree-view` mirror: `data` is optional, so the `nodes` spelling the
+renderer reads FIRST is a legal document on its own (objectui#6939, maintainer
+ruling recorded 2026-09-02 — this is one of the eight groups on that card,
+dispatched as its own PR per the ruling).
+
+`TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD:
+
+ const rawNodes = boundData || schema.nodes || schema.data || [];
+ // packages/components/src/renderers/data-display/tree-view.tsx:105
+
+The registration's own `inputs` and `defaultProps` spell it `nodes`, and the
+four `components-data-display-tree-view/*` catalog entries ARE those
+`defaultProps` — so `safeValidateSchema` refused every one of them
+(`: Invalid input`) while the renderer drew them correctly. Re-measured on
+`origin/main` at `fe4e7a9e8`: four refusals, and four renders that are
+byte-identical under either spelling (28 / 28 / 12 / 34 elements, same tag
+census, same `textContent` SHA-256). Identical output under the "correction" is
+objectui#6318's own triage test for *the schema was the wrong side*.
+
+**For AUTHORS this widens on both faces.** `data` goes from required to optional
+on the mirror and on the TypeScript twin in the same stroke; nothing that
+validated before validates less, and no document that type-checked as a literal
+stops doing so. A document authored on `data` — such as the tree-view entry in
+`packages/types/examples/data-display-examples.json` — is untouched, and both
+spellings together stay legal.
+
+**For a READER of the TypeScript twin this is a narrowing, and that is the half
+worth stating.** `TreeViewSchema['data']` is now `TreeNode[] | undefined`, so
+code that read `schema.data` and relied on its presence needs a guard and will
+otherwise stop compiling (measured on a consumer probe: exit 0 before, `TS2322`
+plus `TS18048` after). The only in-repo reader already has that guard —
+`renderers/data-display/tree-view.tsx:105` reads
+`boundData || schema.nodes || schema.data || []` — and it type-checks clean, so
+nothing in this repository changes. An out-of-repo consumer that reads the key
+unguarded is the population this paragraph exists for.
+
+Still `patch`: the required-ness was never a guarantee the renderer honoured (it
+reads the key third, behind a default), the accept set only grows, and this is
+the same shape as the two sibling groups of this card that have already landed.
+
+**`data` stays DECLARED rather than being deleted**, and the difference is
+measured rather than assumed: `BaseSchema` already declares `data`
+(`z.any().optional()`; `data?: any` on the TS face), so removing the member
+would not reject the key — it would admit it *unvalidated* while the renderer
+went on reading it. Optional-and-typed is the only shape in which `declared` and
+`enforced` agree for a key that is still read.
+
+**No refinement was added**, deliberately, unlike this card's
+`object-map` / `object-gantt` group. A tree-view carrying no data source at all
+becomes legal here, and that admits no new rendering outcome: `{ data: [] }` was
+already legal and already drew the same empty tree, so an "at least one of
+`nodes` / `data` / `bind`" rule would forbid a spelling of an empty state the
+contract already permits rather than buy a guarantee.
+
+`nodes` and `title` are objectui#6150's declarations and are unchanged; that
+card declared the reads and said in as many words that relaxing `data` was a
+separate accept-set change. This is that change.

content/docs/api/schema-reference.md

@@ -524,7 +524,8 @@ A hierarchical tree component for nested data with expand/collapse and selection
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | `TreeNode[]` | **Required.** Nested tree data. Each node has `id`, `label`, optional `icon` and `children`. |
+| `nodes` | `TreeNode[]` | Optional. Nested tree data — the spelling the renderer reads FIRST, and the one the component's own `inputs` and `defaultProps` use. Each node has `id`, `label`, optional `icon` and `children`. |
+| `data` | `TreeNode[]` | Optional. Nested tree data, read only when `nodes` is absent (the renderer reads `nodes` first — objectui#6939). |
 | `defaultExpandedIds` | `string[]` | Node IDs expanded on initial render. |
 | `defaultSelectedIds` | `string[]` | Node IDs selected on initial render. |
 | `expandedIds` | `string[]` | Controlled expanded state. |

examples/schema-catalog/test/tree-view-nodes-mirror-6939.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * objectui#6939, the `tree-view` group — the RENDER half. The validator-side
+ * contract is pinned in
+ * `packages/types/src/__tests__/tree-view-data-optional-6939.test.ts`.
+ *
+ * `TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD
+ * (`boundData || schema.nodes || schema.data || []`,
+ * `renderers/data-display/tree-view.tsx:105`), so all four catalog entries —
+ * which author `nodes`, the spelling the registration's own `inputs` and
+ * `defaultProps` use, and which ARE those `defaultProps` — were refused by
+ * `safeValidateSchema` while drawing correctly.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So a repair on the schema side has to
+ * clear the mirror image of that bar — the validator's verdict must change and
+ * the renderer's output must NOT. `PRE_REPAIR` was measured on `origin/main` at
+ * `fe4e7a9e8`, BEFORE either face was touched, through THIS file's harness.
+ *
+ * ⚠️ The card's table reports "identical — 14 elements" for this row. The
+ * identity reproduces exactly (all four tiles, element count, tag census and a
+ * SHA-256 of `textContent`); the absolute 14 does NOT reproduce in this
+ * harness, which measures 28 / 28 / 12 / 34. Element counts are harness-bound —
+ * the docs-gallery harness (`catalog-gallery-render.test.tsx`, provider plus
+ * `SidebarProvider` plus a padded wrapper) gives different absolutes for the
+ * same tile — so identity WITHIN one harness is the claim that discriminates,
+ * and the number is recorded here rather than carried over from the card.
+ *
+ * Three readings per tile, because a count alone cannot tell a swapped element
+ * from an equal one: element count, a tag census, and the text (literally, plus
+ * a SHA-256 of it).
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { createHash } from 'node:crypto';
+import '@object-ui/components';
+import { SchemaRenderer, toRenderableSchema } from '@object-ui/react';
+import { TreeViewSchema, safeValidateSchema } from '@object-ui/types/zod';
+import { getExample } from '../src/index.js';
+
+const IDS = [
+ 'components-data-display-tree-view/deep-nesting',
+ 'components-data-display-tree-view/file-tree',
+ 'components-data-display-tree-view/org-chart',
+ 'components-data-display-tree-view/sidebar-navigation',
+] as const;
+
+/**
+ * Measured on `origin/main` @ `fe4e7a9e8` through `measure()` below, both faces
+ * untouched. Every one of the four reported `: Invalid input` from
+ * `safeValidateSchema` at that commit, and every one drew exactly this.
+ */
+const PRE_REPAIR: Record<(typeof IDS)[number], {
+ elements: number;
+ tags: Record<string, number>;
+ text: string;
+ sha256: string;
+}> = {
+ 'components-data-display-tree-view/deep-nesting': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'Project Structuresrcpublicpackage.json',
+ sha256: 'e55f4d288401013fd1d6d5f1045e77eba31b07c9a62656efdcc94945e7503167',
+ },
+ 'components-data-display-tree-view/file-tree': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'File ExplorerDocumentsPhotosREADME.md',
+ sha256: '3f2f5a7468194a1af717c2c798a3dd4f9421df445b6c36dae9748eb83639d84a',
+ },
+ 'components-data-display-tree-view/org-chart': {
+ elements: 12,
+ tags: { DIV: 5, H3: 1, BUTTON: 1, svg: 2, path: 2, SPAN: 1 },
+ text: 'OrganizationCEO',
+ sha256: '45f07e1527f23fbd805de7c378192a8fc79d82641d0e98fc35e745d721a17985',
+ },
+ 'components-data-display-tree-view/sidebar-navigation': {
+ elements: 34,
+ tags: { DIV: 13, H3: 1, SPAN: 6, svg: 6, path: 6, BUTTON: 2 },
+ text: 'NavigationDashboardProductsOrdersSettings',
+ sha256: '6126579fe6fca4c4d9c5e25d1ca32f8d3967f2ec1fd1f88bcafa2d8c3f399d01',
+ },
+};
+
+/** Render one entry the way the docs gallery does and measure what it drew. */
+function measure(schema: unknown) {
+ const { container, unmount } = render(
+ <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />,
+ );
+ const nodes = Array.from(container.querySelectorAll('*'));
+ const text = container.textContent ?? '';
+ const out = {
+ elements: nodes.length,
+ tags: nodes.reduce<Record<string, number>>((h, el) => ((h[el.tagName] = (h[el.tagName] ?? 0) + 1), h), {}),
+ text,
+ sha256: createHash('sha256').update(text).digest('hex'),
+ };
+ unmount();
+ return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+ const r = safeValidateSchema(schema);
+ return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+/** The fixture as authored, and the "correction" objectui#6318's triage asks about. */
+function asAuthored(id: (typeof IDS)[number]) {
+ return getExample(id).schema as Record<string, unknown>;
+}
+function asDataSpelling(id: (typeof IDS)[number]) {
+ const { nodes, ...rest } = asAuthored(id);
+ return { ...rest, data: nodes };
+}
+
+describe('objectui#6939 — the four tree-view entries the mirror refused now validate', () => {
+ it.each(IDS)('%s validates under safeValidateSchema', (id) => {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+ it.each(IDS)('%s renders exactly what it rendered before', (id) => {
+ const after = measure(asAuthored(id));
+ const before = PRE_REPAIR[id];
+ expect(after.elements).toBe(before.elements);
+ expect(after.tags).toEqual(before.tags);
+ expect(after.text).toBe(before.text);
+ expect(after.sha256).toBe(before.sha256);
+ });
+
+ it.each(IDS)('%s anti-vacuity: the tile drew its AUTHORED tree, not an empty box', (id) => {
+ // A tile that renders nothing — or the error boundary — satisfies
+ // "identical" trivially. The authored title and every root label on screen
+ // prove the nodes reached the renderer through `nodes`, the spelling the
+ // mirror refused.
+ const schema = asAuthored(id) as { title: string; nodes: { label: string }[] };
+ const m = measure(schema);
+ expect(m.elements).toBeGreaterThan(10);
+ expect(m.text.trim().length).toBeGreaterThan(0);
+ expect(m.text).not.toContain('failed to render');
+ expect(m.text).toContain(schema.title);
+ for (const node of schema.nodes) expect(m.text).toContain(node.label);
+ });
+});
+
+describe('objectui#6939 — the fixtures were the side that was right', () => {
+ it.each(IDS)('%s: "correcting" it to `data` changes no pixel', (id) => {
+ // The card's own discriminator, re-measured here rather than quoted: the
+ // spelling swap moves nothing, so the schema was the wrong side. Contrast
+ // the same probe on the sibling groups, where the "correction" emptied the
+ // board or blanked the tile.
+ const authored = measure(asAuthored(id));
+ const corrected = measure(asDataSpelling(id));
+ expect(corrected.elements).toBe(authored.elements);
+ expect(corrected.text).toBe(authored.text);
+ expect(corrected.sha256).toBe(authored.sha256);
+ });
+
+ it.each(IDS)('%s stays on the spelling its renderer reads FIRST', (id) => {
+ const schema = asAuthored(id);
+ expect(schema.nodes).toBeDefined();
+ expect('data' in schema).toBe(false);
+ });
+
+ it('both spellings validate — the accept set widened, it did not move', () => {
+ // ⛔ Do NOT "repair" a future red here by migrating the fixtures to `data`.
+ // The renderer reads `nodes` first and the registration's `defaultProps`
+ // spell it `nodes`; the fixtures ARE those defaults.
+ for (const id of IDS) {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ expect(reasons(asDataSpelling(id))).toEqual([]);
+ }
+ });
+
+ it('the keys are DECLARED, not passthrough holes', () => {
+ // Counter-probes on keys the mirror declares; an unknown key proves nothing
+ // here, because `BaseSchema` is `.passthrough()`.
+ const shape = (TreeViewSchema as unknown as { shape: Record<string, unknown> }).shape;
+ expect(Object.keys(shape)).toEqual(expect.arrayContaining(['nodes', 'title', 'data']));
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', nodes: 'not-an-array' }).success).toBe(false);
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', data: 'not-an-array' }).success).toBe(false);
+ // …and a good shape still passes, so the two above are not failing for some
+ // unrelated reason. ⚠️ The carrier carries BOTH spellings on purpose: it is
+ // legal with or without this card, so this control cannot redden for the
+ // relaxation it is controlling for. (That the authored, `nodes`-only
+ // fixtures parse is the first describe block's claim, not this one's.)
+ expect(TreeViewSchema.safeParse({
+ type: 'tree-view', title: 'File Explorer', data: [], nodes: [{ id: '1', label: 'Documents' }],
+ }).success).toBe(true);
+ });
+});

.changeset/6939-tree-view-nodes-mirror.md

@@ -0,0 +1,61 @@
+---
+'@object-ui/types': patch
+---
+
+Repair the `tree-view` mirror: `data` is optional, so the `nodes` spelling the
+renderer reads FIRST is a legal document on its own (objectui#6939, maintainer
+ruling recorded 2026-09-02 — this is one of the eight groups on that card,
+dispatched as its own PR per the ruling).
+
+`TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD:
+
+ const rawNodes = boundData || schema.nodes || schema.data || [];
+ // packages/components/src/renderers/data-display/tree-view.tsx:105
+
+The registration's own `inputs` and `defaultProps` spell it `nodes`, and the
+four `components-data-display-tree-view/*` catalog entries ARE those
+`defaultProps` — so `safeValidateSchema` refused every one of them
+(`: Invalid input`) while the renderer drew them correctly. Re-measured on
+`origin/main` at `fe4e7a9e8`: four refusals, and four renders that are
+byte-identical under either spelling (28 / 28 / 12 / 34 elements, same tag
+census, same `textContent` SHA-256). Identical output under the "correction" is
+objectui#6318's own triage test for *the schema was the wrong side*.
+
+**For AUTHORS this widens on both faces.** `data` goes from required to optional
+on the mirror and on the TypeScript twin in the same stroke; nothing that
+validated before validates less, and no document that type-checked as a literal
+stops doing so. A document authored on `data` — such as the tree-view entry in
+`packages/types/examples/data-display-examples.json` — is untouched, and both
+spellings together stay legal.
+
+**For a READER of the TypeScript twin this is a narrowing, and that is the half
+worth stating.** `TreeViewSchema['data']` is now `TreeNode[] | undefined`, so
+code that read `schema.data` and relied on its presence needs a guard and will
+otherwise stop compiling (measured on a consumer probe: exit 0 before, `TS2322`
+plus `TS18048` after). The only in-repo reader already has that guard —
+`renderers/data-display/tree-view.tsx:105` reads
+`boundData || schema.nodes || schema.data || []` — and it type-checks clean, so
+nothing in this repository changes. An out-of-repo consumer that reads the key
+unguarded is the population this paragraph exists for.
+
+Still `patch`: the required-ness was never a guarantee the renderer honoured (it
+reads the key third, behind a default), the accept set only grows, and this is
+the same shape as the two sibling groups of this card that have already landed.
+
+**`data` stays DECLARED rather than being deleted**, and the difference is
+measured rather than assumed: `BaseSchema` already declares `data`
+(`z.any().optional()`; `data?: any` on the TS face), so removing the member
+would not reject the key — it would admit it *unvalidated* while the renderer
+went on reading it. Optional-and-typed is the only shape in which `declared` and
+`enforced` agree for a key that is still read.
+
+**No refinement was added**, deliberately, unlike this card's
+`object-map` / `object-gantt` group. A tree-view carrying no data source at all
+becomes legal here, and that admits no new rendering outcome: `{ data: [] }` was
+already legal and already drew the same empty tree, so an "at least one of
+`nodes` / `data` / `bind`" rule would forbid a spelling of an empty state the
+contract already permits rather than buy a guarantee.
+
+`nodes` and `title` are objectui#6150's declarations and are unchanged; that
+card declared the reads and said in as many words that relaxing `data` was a
+separate accept-set change. This is that change.

content/docs/api/schema-reference.md

@@ -524,7 +524,8 @@ A hierarchical tree component for nested data with expand/collapse and selection
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | `TreeNode[]` | **Required.** Nested tree data. Each node has `id`, `label`, optional `icon` and `children`. |
+| `nodes` | `TreeNode[]` | Optional. Nested tree data — the spelling the renderer reads FIRST, and the one the component's own `inputs` and `defaultProps` use. Each node has `id`, `label`, optional `icon` and `children`. |
+| `data` | `TreeNode[]` | Optional. Nested tree data, read only when `nodes` is absent (the renderer reads `nodes` first — objectui#6939). |
 | `defaultExpandedIds` | `string[]` | Node IDs expanded on initial render. |
 | `defaultSelectedIds` | `string[]` | Node IDs selected on initial render. |
 | `expandedIds` | `string[]` | Controlled expanded state. |

examples/schema-catalog/test/tree-view-nodes-mirror-6939.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * objectui#6939, the `tree-view` group — the RENDER half. The validator-side
+ * contract is pinned in
+ * `packages/types/src/__tests__/tree-view-data-optional-6939.test.ts`.
+ *
+ * `TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD
+ * (`boundData || schema.nodes || schema.data || []`,
+ * `renderers/data-display/tree-view.tsx:105`), so all four catalog entries —
+ * which author `nodes`, the spelling the registration's own `inputs` and
+ * `defaultProps` use, and which ARE those `defaultProps` — were refused by
+ * `safeValidateSchema` while drawing correctly.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So a repair on the schema side has to
+ * clear the mirror image of that bar — the validator's verdict must change and
+ * the renderer's output must NOT. `PRE_REPAIR` was measured on `origin/main` at
+ * `fe4e7a9e8`, BEFORE either face was touched, through THIS file's harness.
+ *
+ * ⚠️ The card's table reports "identical — 14 elements" for this row. The
+ * identity reproduces exactly (all four tiles, element count, tag census and a
+ * SHA-256 of `textContent`); the absolute 14 does NOT reproduce in this
+ * harness, which measures 28 / 28 / 12 / 34. Element counts are harness-bound —
+ * the docs-gallery harness (`catalog-gallery-render.test.tsx`, provider plus
+ * `SidebarProvider` plus a padded wrapper) gives different absolutes for the
+ * same tile — so identity WITHIN one harness is the claim that discriminates,
+ * and the number is recorded here rather than carried over from the card.
+ *
+ * Three readings per tile, because a count alone cannot tell a swapped element
+ * from an equal one: element count, a tag census, and the text (literally, plus
+ * a SHA-256 of it).
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { createHash } from 'node:crypto';
+import '@object-ui/components';
+import { SchemaRenderer, toRenderableSchema } from '@object-ui/react';
+import { TreeViewSchema, safeValidateSchema } from '@object-ui/types/zod';
+import { getExample } from '../src/index.js';
+
+const IDS = [
+ 'components-data-display-tree-view/deep-nesting',
+ 'components-data-display-tree-view/file-tree',
+ 'components-data-display-tree-view/org-chart',
+ 'components-data-display-tree-view/sidebar-navigation',
+] as const;
+
+/**
+ * Measured on `origin/main` @ `fe4e7a9e8` through `measure()` below, both faces
+ * untouched. Every one of the four reported `: Invalid input` from
+ * `safeValidateSchema` at that commit, and every one drew exactly this.
+ */
+const PRE_REPAIR: Record<(typeof IDS)[number], {
+ elements: number;
+ tags: Record<string, number>;
+ text: string;
+ sha256: string;
+}> = {
+ 'components-data-display-tree-view/deep-nesting': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'Project Structuresrcpublicpackage.json',
+ sha256: 'e55f4d288401013fd1d6d5f1045e77eba31b07c9a62656efdcc94945e7503167',
+ },
+ 'components-data-display-tree-view/file-tree': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'File ExplorerDocumentsPhotosREADME.md',
+ sha256: '3f2f5a7468194a1af717c2c798a3dd4f9421df445b6c36dae9748eb83639d84a',
+ },
+ 'components-data-display-tree-view/org-chart': {
+ elements: 12,
+ tags: { DIV: 5, H3: 1, BUTTON: 1, svg: 2, path: 2, SPAN: 1 },
+ text: 'OrganizationCEO',
+ sha256: '45f07e1527f23fbd805de7c378192a8fc79d82641d0e98fc35e745d721a17985',
+ },
+ 'components-data-display-tree-view/sidebar-navigation': {
+ elements: 34,
+ tags: { DIV: 13, H3: 1, SPAN: 6, svg: 6, path: 6, BUTTON: 2 },
+ text: 'NavigationDashboardProductsOrdersSettings',
+ sha256: '6126579fe6fca4c4d9c5e25d1ca32f8d3967f2ec1fd1f88bcafa2d8c3f399d01',
+ },
+};
+
+/** Render one entry the way the docs gallery does and measure what it drew. */
+function measure(schema: unknown) {
+ const { container, unmount } = render(
+ <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />,
+ );
+ const nodes = Array.from(container.querySelectorAll('*'));
+ const text = container.textContent ?? '';
+ const out = {
+ elements: nodes.length,
+ tags: nodes.reduce<Record<string, number>>((h, el) => ((h[el.tagName] = (h[el.tagName] ?? 0) + 1), h), {}),
+ text,
+ sha256: createHash('sha256').update(text).digest('hex'),
+ };
+ unmount();
+ return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+ const r = safeValidateSchema(schema);
+ return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+/** The fixture as authored, and the "correction" objectui#6318's triage asks about. */
+function asAuthored(id: (typeof IDS)[number]) {
+ return getExample(id).schema as Record<string, unknown>;
+}
+function asDataSpelling(id: (typeof IDS)[number]) {
+ const { nodes, ...rest } = asAuthored(id);
+ return { ...rest, data: nodes };
+}
+
+describe('objectui#6939 — the four tree-view entries the mirror refused now validate', () => {
+ it.each(IDS)('%s validates under safeValidateSchema', (id) => {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+ it.each(IDS)('%s renders exactly what it rendered before', (id) => {
+ const after = measure(asAuthored(id));
+ const before = PRE_REPAIR[id];
+ expect(after.elements).toBe(before.elements);
+ expect(after.tags).toEqual(before.tags);
+ expect(after.text).toBe(before.text);
+ expect(after.sha256).toBe(before.sha256);
+ });
+
+ it.each(IDS)('%s anti-vacuity: the tile drew its AUTHORED tree, not an empty box', (id) => {
+ // A tile that renders nothing — or the error boundary — satisfies
+ // "identical" trivially. The authored title and every root label on screen
+ // prove the nodes reached the renderer through `nodes`, the spelling the
+ // mirror refused.
+ const schema = asAuthored(id) as { title: string; nodes: { label: string }[] };
+ const m = measure(schema);
+ expect(m.elements).toBeGreaterThan(10);
+ expect(m.text.trim().length).toBeGreaterThan(0);
+ expect(m.text).not.toContain('failed to render');
+ expect(m.text).toContain(schema.title);
+ for (const node of schema.nodes) expect(m.text).toContain(node.label);
+ });
+});
+
+describe('objectui#6939 — the fixtures were the side that was right', () => {
+ it.each(IDS)('%s: "correcting" it to `data` changes no pixel', (id) => {
+ // The card's own discriminator, re-measured here rather than quoted: the
+ // spelling swap moves nothing, so the schema was the wrong side. Contrast
+ // the same probe on the sibling groups, where the "correction" emptied the
+ // board or blanked the tile.
+ const authored = measure(asAuthored(id));
+ const corrected = measure(asDataSpelling(id));
+ expect(corrected.elements).toBe(authored.elements);
+ expect(corrected.text).toBe(authored.text);
+ expect(corrected.sha256).toBe(authored.sha256);
+ });
+
+ it.each(IDS)('%s stays on the spelling its renderer reads FIRST', (id) => {
+ const schema = asAuthored(id);
+ expect(schema.nodes).toBeDefined();
+ expect('data' in schema).toBe(false);
+ });
+
+ it('both spellings validate — the accept set widened, it did not move', () => {
+ // ⛔ Do NOT "repair" a future red here by migrating the fixtures to `data`.
+ // The renderer reads `nodes` first and the registration's `defaultProps`
+ // spell it `nodes`; the fixtures ARE those defaults.
+ for (const id of IDS) {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ expect(reasons(asDataSpelling(id))).toEqual([]);
+ }
+ });
+
+ it('the keys are DECLARED, not passthrough holes', () => {
+ // Counter-probes on keys the mirror declares; an unknown key proves nothing
+ // here, because `BaseSchema` is `.passthrough()`.
+ const shape = (TreeViewSchema as unknown as { shape: Record<string, unknown> }).shape;
+ expect(Object.keys(shape)).toEqual(expect.arrayContaining(['nodes', 'title', 'data']));
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', nodes: 'not-an-array' }).success).toBe(false);
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', data: 'not-an-array' }).success).toBe(false);
+ // …and a good shape still passes, so the two above are not failing for some
+ // unrelated reason. ⚠️ The carrier carries BOTH spellings on purpose: it is
+ // legal with or without this card, so this control cannot redden for the
+ // relaxation it is controlling for. (That the authored, `nodes`-only
+ // fixtures parse is the first describe block's claim, not this one's.)
+ expect(TreeViewSchema.safeParse({
+ type: 'tree-view', title: 'File Explorer', data: [], nodes: [{ id: '1', label: 'Documents' }],
+ }).success).toBe(true);
+ });
+});

.changeset/6939-tree-view-nodes-mirror.md

@@ -0,0 +1,61 @@
+---
+'@object-ui/types': patch
+---
+
+Repair the `tree-view` mirror: `data` is optional, so the `nodes` spelling the
+renderer reads FIRST is a legal document on its own (objectui#6939, maintainer
+ruling recorded 2026-09-02 — this is one of the eight groups on that card,
+dispatched as its own PR per the ruling).
+
+`TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD:
+
+ const rawNodes = boundData || schema.nodes || schema.data || [];
+ // packages/components/src/renderers/data-display/tree-view.tsx:105
+
+The registration's own `inputs` and `defaultProps` spell it `nodes`, and the
+four `components-data-display-tree-view/*` catalog entries ARE those
+`defaultProps` — so `safeValidateSchema` refused every one of them
+(`: Invalid input`) while the renderer drew them correctly. Re-measured on
+`origin/main` at `fe4e7a9e8`: four refusals, and four renders that are
+byte-identical under either spelling (28 / 28 / 12 / 34 elements, same tag
+census, same `textContent` SHA-256). Identical output under the "correction" is
+objectui#6318's own triage test for *the schema was the wrong side*.
+
+**For AUTHORS this widens on both faces.** `data` goes from required to optional
+on the mirror and on the TypeScript twin in the same stroke; nothing that
+validated before validates less, and no document that type-checked as a literal
+stops doing so. A document authored on `data` — such as the tree-view entry in
+`packages/types/examples/data-display-examples.json` — is untouched, and both
+spellings together stay legal.
+
+**For a READER of the TypeScript twin this is a narrowing, and that is the half
+worth stating.** `TreeViewSchema['data']` is now `TreeNode[] | undefined`, so
+code that read `schema.data` and relied on its presence needs a guard and will
+otherwise stop compiling (measured on a consumer probe: exit 0 before, `TS2322`
+plus `TS18048` after). The only in-repo reader already has that guard —
+`renderers/data-display/tree-view.tsx:105` reads
+`boundData || schema.nodes || schema.data || []` — and it type-checks clean, so
+nothing in this repository changes. An out-of-repo consumer that reads the key
+unguarded is the population this paragraph exists for.
+
+Still `patch`: the required-ness was never a guarantee the renderer honoured (it
+reads the key third, behind a default), the accept set only grows, and this is
+the same shape as the two sibling groups of this card that have already landed.
+
+**`data` stays DECLARED rather than being deleted**, and the difference is
+measured rather than assumed: `BaseSchema` already declares `data`
+(`z.any().optional()`; `data?: any` on the TS face), so removing the member
+would not reject the key — it would admit it *unvalidated* while the renderer
+went on reading it. Optional-and-typed is the only shape in which `declared` and
+`enforced` agree for a key that is still read.
+
+**No refinement was added**, deliberately, unlike this card's
+`object-map` / `object-gantt` group. A tree-view carrying no data source at all
+becomes legal here, and that admits no new rendering outcome: `{ data: [] }` was
+already legal and already drew the same empty tree, so an "at least one of
+`nodes` / `data` / `bind`" rule would forbid a spelling of an empty state the
+contract already permits rather than buy a guarantee.
+
+`nodes` and `title` are objectui#6150's declarations and are unchanged; that
+card declared the reads and said in as many words that relaxing `data` was a
+separate accept-set change. This is that change.

content/docs/api/schema-reference.md

@@ -524,7 +524,8 @@ A hierarchical tree component for nested data with expand/collapse and selection
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | `TreeNode[]` | **Required.** Nested tree data. Each node has `id`, `label`, optional `icon` and `children`. |
+| `nodes` | `TreeNode[]` | Optional. Nested tree data — the spelling the renderer reads FIRST, and the one the component's own `inputs` and `defaultProps` use. Each node has `id`, `label`, optional `icon` and `children`. |
+| `data` | `TreeNode[]` | Optional. Nested tree data, read only when `nodes` is absent (the renderer reads `nodes` first — objectui#6939). |
 | `defaultExpandedIds` | `string[]` | Node IDs expanded on initial render. |
 | `defaultSelectedIds` | `string[]` | Node IDs selected on initial render. |
 | `expandedIds` | `string[]` | Controlled expanded state. |

examples/schema-catalog/test/tree-view-nodes-mirror-6939.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * objectui#6939, the `tree-view` group — the RENDER half. The validator-side
+ * contract is pinned in
+ * `packages/types/src/__tests__/tree-view-data-optional-6939.test.ts`.
+ *
+ * `TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD
+ * (`boundData || schema.nodes || schema.data || []`,
+ * `renderers/data-display/tree-view.tsx:105`), so all four catalog entries —
+ * which author `nodes`, the spelling the registration's own `inputs` and
+ * `defaultProps` use, and which ARE those `defaultProps` — were refused by
+ * `safeValidateSchema` while drawing correctly.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So a repair on the schema side has to
+ * clear the mirror image of that bar — the validator's verdict must change and
+ * the renderer's output must NOT. `PRE_REPAIR` was measured on `origin/main` at
+ * `fe4e7a9e8`, BEFORE either face was touched, through THIS file's harness.
+ *
+ * ⚠️ The card's table reports "identical — 14 elements" for this row. The
+ * identity reproduces exactly (all four tiles, element count, tag census and a
+ * SHA-256 of `textContent`); the absolute 14 does NOT reproduce in this
+ * harness, which measures 28 / 28 / 12 / 34. Element counts are harness-bound —
+ * the docs-gallery harness (`catalog-gallery-render.test.tsx`, provider plus
+ * `SidebarProvider` plus a padded wrapper) gives different absolutes for the
+ * same tile — so identity WITHIN one harness is the claim that discriminates,
+ * and the number is recorded here rather than carried over from the card.
+ *
+ * Three readings per tile, because a count alone cannot tell a swapped element
+ * from an equal one: element count, a tag census, and the text (literally, plus
+ * a SHA-256 of it).
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { createHash } from 'node:crypto';
+import '@object-ui/components';
+import { SchemaRenderer, toRenderableSchema } from '@object-ui/react';
+import { TreeViewSchema, safeValidateSchema } from '@object-ui/types/zod';
+import { getExample } from '../src/index.js';
+
+const IDS = [
+ 'components-data-display-tree-view/deep-nesting',
+ 'components-data-display-tree-view/file-tree',
+ 'components-data-display-tree-view/org-chart',
+ 'components-data-display-tree-view/sidebar-navigation',
+] as const;
+
+/**
+ * Measured on `origin/main` @ `fe4e7a9e8` through `measure()` below, both faces
+ * untouched. Every one of the four reported `: Invalid input` from
+ * `safeValidateSchema` at that commit, and every one drew exactly this.
+ */
+const PRE_REPAIR: Record<(typeof IDS)[number], {
+ elements: number;
+ tags: Record<string, number>;
+ text: string;
+ sha256: string;
+}> = {
+ 'components-data-display-tree-view/deep-nesting': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'Project Structuresrcpublicpackage.json',
+ sha256: 'e55f4d288401013fd1d6d5f1045e77eba31b07c9a62656efdcc94945e7503167',
+ },
+ 'components-data-display-tree-view/file-tree': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'File ExplorerDocumentsPhotosREADME.md',
+ sha256: '3f2f5a7468194a1af717c2c798a3dd4f9421df445b6c36dae9748eb83639d84a',
+ },
+ 'components-data-display-tree-view/org-chart': {
+ elements: 12,
+ tags: { DIV: 5, H3: 1, BUTTON: 1, svg: 2, path: 2, SPAN: 1 },
+ text: 'OrganizationCEO',
+ sha256: '45f07e1527f23fbd805de7c378192a8fc79d82641d0e98fc35e745d721a17985',
+ },
+ 'components-data-display-tree-view/sidebar-navigation': {
+ elements: 34,
+ tags: { DIV: 13, H3: 1, SPAN: 6, svg: 6, path: 6, BUTTON: 2 },
+ text: 'NavigationDashboardProductsOrdersSettings',
+ sha256: '6126579fe6fca4c4d9c5e25d1ca32f8d3967f2ec1fd1f88bcafa2d8c3f399d01',
+ },
+};
+
+/** Render one entry the way the docs gallery does and measure what it drew. */
+function measure(schema: unknown) {
+ const { container, unmount } = render(
+ <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />,
+ );
+ const nodes = Array.from(container.querySelectorAll('*'));
+ const text = container.textContent ?? '';
+ const out = {
+ elements: nodes.length,
+ tags: nodes.reduce<Record<string, number>>((h, el) => ((h[el.tagName] = (h[el.tagName] ?? 0) + 1), h), {}),
+ text,
+ sha256: createHash('sha256').update(text).digest('hex'),
+ };
+ unmount();
+ return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+ const r = safeValidateSchema(schema);
+ return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+/** The fixture as authored, and the "correction" objectui#6318's triage asks about. */
+function asAuthored(id: (typeof IDS)[number]) {
+ return getExample(id).schema as Record<string, unknown>;
+}
+function asDataSpelling(id: (typeof IDS)[number]) {
+ const { nodes, ...rest } = asAuthored(id);
+ return { ...rest, data: nodes };
+}
+
+describe('objectui#6939 — the four tree-view entries the mirror refused now validate', () => {
+ it.each(IDS)('%s validates under safeValidateSchema', (id) => {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+ it.each(IDS)('%s renders exactly what it rendered before', (id) => {
+ const after = measure(asAuthored(id));
+ const before = PRE_REPAIR[id];
+ expect(after.elements).toBe(before.elements);
+ expect(after.tags).toEqual(before.tags);
+ expect(after.text).toBe(before.text);
+ expect(after.sha256).toBe(before.sha256);
+ });
+
+ it.each(IDS)('%s anti-vacuity: the tile drew its AUTHORED tree, not an empty box', (id) => {
+ // A tile that renders nothing — or the error boundary — satisfies
+ // "identical" trivially. The authored title and every root label on screen
+ // prove the nodes reached the renderer through `nodes`, the spelling the
+ // mirror refused.
+ const schema = asAuthored(id) as { title: string; nodes: { label: string }[] };
+ const m = measure(schema);
+ expect(m.elements).toBeGreaterThan(10);
+ expect(m.text.trim().length).toBeGreaterThan(0);
+ expect(m.text).not.toContain('failed to render');
+ expect(m.text).toContain(schema.title);
+ for (const node of schema.nodes) expect(m.text).toContain(node.label);
+ });
+});
+
+describe('objectui#6939 — the fixtures were the side that was right', () => {
+ it.each(IDS)('%s: "correcting" it to `data` changes no pixel', (id) => {
+ // The card's own discriminator, re-measured here rather than quoted: the
+ // spelling swap moves nothing, so the schema was the wrong side. Contrast
+ // the same probe on the sibling groups, where the "correction" emptied the
+ // board or blanked the tile.
+ const authored = measure(asAuthored(id));
+ const corrected = measure(asDataSpelling(id));
+ expect(corrected.elements).toBe(authored.elements);
+ expect(corrected.text).toBe(authored.text);
+ expect(corrected.sha256).toBe(authored.sha256);
+ });
+
+ it.each(IDS)('%s stays on the spelling its renderer reads FIRST', (id) => {
+ const schema = asAuthored(id);
+ expect(schema.nodes).toBeDefined();
+ expect('data' in schema).toBe(false);
+ });
+
+ it('both spellings validate — the accept set widened, it did not move', () => {
+ // ⛔ Do NOT "repair" a future red here by migrating the fixtures to `data`.
+ // The renderer reads `nodes` first and the registration's `defaultProps`
+ // spell it `nodes`; the fixtures ARE those defaults.
+ for (const id of IDS) {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ expect(reasons(asDataSpelling(id))).toEqual([]);
+ }
+ });
+
+ it('the keys are DECLARED, not passthrough holes', () => {
+ // Counter-probes on keys the mirror declares; an unknown key proves nothing
+ // here, because `BaseSchema` is `.passthrough()`.
+ const shape = (TreeViewSchema as unknown as { shape: Record<string, unknown> }).shape;
+ expect(Object.keys(shape)).toEqual(expect.arrayContaining(['nodes', 'title', 'data']));
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', nodes: 'not-an-array' }).success).toBe(false);
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', data: 'not-an-array' }).success).toBe(false);
+ // …and a good shape still passes, so the two above are not failing for some
+ // unrelated reason. ⚠️ The carrier carries BOTH spellings on purpose: it is
+ // legal with or without this card, so this control cannot redden for the
+ // relaxation it is controlling for. (That the authored, `nodes`-only
+ // fixtures parse is the first describe block's claim, not this one's.)
+ expect(TreeViewSchema.safeParse({
+ type: 'tree-view', title: 'File Explorer', data: [], nodes: [{ id: '1', label: 'Documents' }],
+ }).success).toBe(true);
+ });
+});

.changeset/6939-tree-view-nodes-mirror.md

@@ -0,0 +1,61 @@
+---
+'@object-ui/types': patch
+---
+
+Repair the `tree-view` mirror: `data` is optional, so the `nodes` spelling the
+renderer reads FIRST is a legal document on its own (objectui#6939, maintainer
+ruling recorded 2026-09-02 — this is one of the eight groups on that card,
+dispatched as its own PR per the ruling).
+
+`TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD:
+
+ const rawNodes = boundData || schema.nodes || schema.data || [];
+ // packages/components/src/renderers/data-display/tree-view.tsx:105
+
+The registration's own `inputs` and `defaultProps` spell it `nodes`, and the
+four `components-data-display-tree-view/*` catalog entries ARE those
+`defaultProps` — so `safeValidateSchema` refused every one of them
+(`: Invalid input`) while the renderer drew them correctly. Re-measured on
+`origin/main` at `fe4e7a9e8`: four refusals, and four renders that are
+byte-identical under either spelling (28 / 28 / 12 / 34 elements, same tag
+census, same `textContent` SHA-256). Identical output under the "correction" is
+objectui#6318's own triage test for *the schema was the wrong side*.
+
+**For AUTHORS this widens on both faces.** `data` goes from required to optional
+on the mirror and on the TypeScript twin in the same stroke; nothing that
+validated before validates less, and no document that type-checked as a literal
+stops doing so. A document authored on `data` — such as the tree-view entry in
+`packages/types/examples/data-display-examples.json` — is untouched, and both
+spellings together stay legal.
+
+**For a READER of the TypeScript twin this is a narrowing, and that is the half
+worth stating.** `TreeViewSchema['data']` is now `TreeNode[] | undefined`, so
+code that read `schema.data` and relied on its presence needs a guard and will
+otherwise stop compiling (measured on a consumer probe: exit 0 before, `TS2322`
+plus `TS18048` after). The only in-repo reader already has that guard —
+`renderers/data-display/tree-view.tsx:105` reads
+`boundData || schema.nodes || schema.data || []` — and it type-checks clean, so
+nothing in this repository changes. An out-of-repo consumer that reads the key
+unguarded is the population this paragraph exists for.
+
+Still `patch`: the required-ness was never a guarantee the renderer honoured (it
+reads the key third, behind a default), the accept set only grows, and this is
+the same shape as the two sibling groups of this card that have already landed.
+
+**`data` stays DECLARED rather than being deleted**, and the difference is
+measured rather than assumed: `BaseSchema` already declares `data`
+(`z.any().optional()`; `data?: any` on the TS face), so removing the member
+would not reject the key — it would admit it *unvalidated* while the renderer
+went on reading it. Optional-and-typed is the only shape in which `declared` and
+`enforced` agree for a key that is still read.
+
+**No refinement was added**, deliberately, unlike this card's
+`object-map` / `object-gantt` group. A tree-view carrying no data source at all
+becomes legal here, and that admits no new rendering outcome: `{ data: [] }` was
+already legal and already drew the same empty tree, so an "at least one of
+`nodes` / `data` / `bind`" rule would forbid a spelling of an empty state the
+contract already permits rather than buy a guarantee.
+
+`nodes` and `title` are objectui#6150's declarations and are unchanged; that
+card declared the reads and said in as many words that relaxing `data` was a
+separate accept-set change. This is that change.

content/docs/api/schema-reference.md

@@ -524,7 +524,8 @@ A hierarchical tree component for nested data with expand/collapse and selection
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `data` | `TreeNode[]` | **Required.** Nested tree data. Each node has `id`, `label`, optional `icon` and `children`. |
+| `nodes` | `TreeNode[]` | Optional. Nested tree data — the spelling the renderer reads FIRST, and the one the component's own `inputs` and `defaultProps` use. Each node has `id`, `label`, optional `icon` and `children`. |
+| `data` | `TreeNode[]` | Optional. Nested tree data, read only when `nodes` is absent (the renderer reads `nodes` first — objectui#6939). |
 | `defaultExpandedIds` | `string[]` | Node IDs expanded on initial render. |
 | `defaultSelectedIds` | `string[]` | Node IDs selected on initial render. |
 | `expandedIds` | `string[]` | Controlled expanded state. |

examples/schema-catalog/test/tree-view-nodes-mirror-6939.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * objectui#6939, the `tree-view` group — the RENDER half. The validator-side
+ * contract is pinned in
+ * `packages/types/src/__tests__/tree-view-data-optional-6939.test.ts`.
+ *
+ * `TreeViewSchema` REQUIRED `data`, the limb the renderer reads THIRD
+ * (`boundData || schema.nodes || schema.data || []`,
+ * `renderers/data-display/tree-view.tsx:105`), so all four catalog entries —
+ * which author `nodes`, the spelling the registration's own `inputs` and
+ * `defaultProps` use, and which ARE those `defaultProps` — were refused by
+ * `safeValidateSchema` while drawing correctly.
+ *
+ * ## Why the render half is the discriminating half
+ *
+ * From objectui#6318's triage: a "correction" that renders identically proves
+ * the SCHEMA was wrong, not the fixture. So a repair on the schema side has to
+ * clear the mirror image of that bar — the validator's verdict must change and
+ * the renderer's output must NOT. `PRE_REPAIR` was measured on `origin/main` at
+ * `fe4e7a9e8`, BEFORE either face was touched, through THIS file's harness.
+ *
+ * ⚠️ The card's table reports "identical — 14 elements" for this row. The
+ * identity reproduces exactly (all four tiles, element count, tag census and a
+ * SHA-256 of `textContent`); the absolute 14 does NOT reproduce in this
+ * harness, which measures 28 / 28 / 12 / 34. Element counts are harness-bound —
+ * the docs-gallery harness (`catalog-gallery-render.test.tsx`, provider plus
+ * `SidebarProvider` plus a padded wrapper) gives different absolutes for the
+ * same tile — so identity WITHIN one harness is the claim that discriminates,
+ * and the number is recorded here rather than carried over from the card.
+ *
+ * Three readings per tile, because a count alone cannot tell a swapped element
+ * from an equal one: element count, a tag census, and the text (literally, plus
+ * a SHA-256 of it).
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { createHash } from 'node:crypto';
+import '@object-ui/components';
+import { SchemaRenderer, toRenderableSchema } from '@object-ui/react';
+import { TreeViewSchema, safeValidateSchema } from '@object-ui/types/zod';
+import { getExample } from '../src/index.js';
+
+const IDS = [
+ 'components-data-display-tree-view/deep-nesting',
+ 'components-data-display-tree-view/file-tree',
+ 'components-data-display-tree-view/org-chart',
+ 'components-data-display-tree-view/sidebar-navigation',
+] as const;
+
+/**
+ * Measured on `origin/main` @ `fe4e7a9e8` through `measure()` below, both faces
+ * untouched. Every one of the four reported `: Invalid input` from
+ * `safeValidateSchema` at that commit, and every one drew exactly this.
+ */
+const PRE_REPAIR: Record<(typeof IDS)[number], {
+ elements: number;
+ tags: Record<string, number>;
+ text: string;
+ sha256: string;
+}> = {
+ 'components-data-display-tree-view/deep-nesting': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'Project Structuresrcpublicpackage.json',
+ sha256: 'e55f4d288401013fd1d6d5f1045e77eba31b07c9a62656efdcc94945e7503167',
+ },
+ 'components-data-display-tree-view/file-tree': {
+ elements: 28,
+ tags: { DIV: 10, H3: 1, BUTTON: 2, svg: 5, path: 6, SPAN: 4 },
+ text: 'File ExplorerDocumentsPhotosREADME.md',
+ sha256: '3f2f5a7468194a1af717c2c798a3dd4f9421df445b6c36dae9748eb83639d84a',
+ },
+ 'components-data-display-tree-view/org-chart': {
+ elements: 12,
+ tags: { DIV: 5, H3: 1, BUTTON: 1, svg: 2, path: 2, SPAN: 1 },
+ text: 'OrganizationCEO',
+ sha256: '45f07e1527f23fbd805de7c378192a8fc79d82641d0e98fc35e745d721a17985',
+ },
+ 'components-data-display-tree-view/sidebar-navigation': {
+ elements: 34,
+ tags: { DIV: 13, H3: 1, SPAN: 6, svg: 6, path: 6, BUTTON: 2 },
+ text: 'NavigationDashboardProductsOrdersSettings',
+ sha256: '6126579fe6fca4c4d9c5e25d1ca32f8d3967f2ec1fd1f88bcafa2d8c3f399d01',
+ },
+};
+
+/** Render one entry the way the docs gallery does and measure what it drew. */
+function measure(schema: unknown) {
+ const { container, unmount } = render(
+ <SchemaRenderer schema={toRenderableSchema(schema as never) as never} />,
+ );
+ const nodes = Array.from(container.querySelectorAll('*'));
+ const text = container.textContent ?? '';
+ const out = {
+ elements: nodes.length,
+ tags: nodes.reduce<Record<string, number>>((h, el) => ((h[el.tagName] = (h[el.tagName] ?? 0) + 1), h), {}),
+ text,
+ sha256: createHash('sha256').update(text).digest('hex'),
+ };
+ unmount();
+ return out;
+}
+
+/** Report the issues rather than `false`, so a red run says what broke. */
+function reasons(schema: unknown): string[] {
+ const r = safeValidateSchema(schema);
+ return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+/** The fixture as authored, and the "correction" objectui#6318's triage asks about. */
+function asAuthored(id: (typeof IDS)[number]) {
+ return getExample(id).schema as Record<string, unknown>;
+}
+function asDataSpelling(id: (typeof IDS)[number]) {
+ const { nodes, ...rest } = asAuthored(id);
+ return { ...rest, data: nodes };
+}
+
+describe('objectui#6939 — the four tree-view entries the mirror refused now validate', () => {
+ it.each(IDS)('%s validates under safeValidateSchema', (id) => {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ });
+});
+
+describe('objectui#6939 — and the repair moved the validator, not the renderer', () => {
+ it.each(IDS)('%s renders exactly what it rendered before', (id) => {
+ const after = measure(asAuthored(id));
+ const before = PRE_REPAIR[id];
+ expect(after.elements).toBe(before.elements);
+ expect(after.tags).toEqual(before.tags);
+ expect(after.text).toBe(before.text);
+ expect(after.sha256).toBe(before.sha256);
+ });
+
+ it.each(IDS)('%s anti-vacuity: the tile drew its AUTHORED tree, not an empty box', (id) => {
+ // A tile that renders nothing — or the error boundary — satisfies
+ // "identical" trivially. The authored title and every root label on screen
+ // prove the nodes reached the renderer through `nodes`, the spelling the
+ // mirror refused.
+ const schema = asAuthored(id) as { title: string; nodes: { label: string }[] };
+ const m = measure(schema);
+ expect(m.elements).toBeGreaterThan(10);
+ expect(m.text.trim().length).toBeGreaterThan(0);
+ expect(m.text).not.toContain('failed to render');
+ expect(m.text).toContain(schema.title);
+ for (const node of schema.nodes) expect(m.text).toContain(node.label);
+ });
+});
+
+describe('objectui#6939 — the fixtures were the side that was right', () => {
+ it.each(IDS)('%s: "correcting" it to `data` changes no pixel', (id) => {
+ // The card's own discriminator, re-measured here rather than quoted: the
+ // spelling swap moves nothing, so the schema was the wrong side. Contrast
+ // the same probe on the sibling groups, where the "correction" emptied the
+ // board or blanked the tile.
+ const authored = measure(asAuthored(id));
+ const corrected = measure(asDataSpelling(id));
+ expect(corrected.elements).toBe(authored.elements);
+ expect(corrected.text).toBe(authored.text);
+ expect(corrected.sha256).toBe(authored.sha256);
+ });
+
+ it.each(IDS)('%s stays on the spelling its renderer reads FIRST', (id) => {
+ const schema = asAuthored(id);
+ expect(schema.nodes).toBeDefined();
+ expect('data' in schema).toBe(false);
+ });
+
+ it('both spellings validate — the accept set widened, it did not move', () => {
+ // ⛔ Do NOT "repair" a future red here by migrating the fixtures to `data`.
+ // The renderer reads `nodes` first and the registration's `defaultProps`
+ // spell it `nodes`; the fixtures ARE those defaults.
+ for (const id of IDS) {
+ expect(reasons(asAuthored(id))).toEqual([]);
+ expect(reasons(asDataSpelling(id))).toEqual([]);
+ }
+ });
+
+ it('the keys are DECLARED, not passthrough holes', () => {
+ // Counter-probes on keys the mirror declares; an unknown key proves nothing
+ // here, because `BaseSchema` is `.passthrough()`.
+ const shape = (TreeViewSchema as unknown as { shape: Record<string, unknown> }).shape;
+ expect(Object.keys(shape)).toEqual(expect.arrayContaining(['nodes', 'title', 'data']));
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', nodes: 'not-an-array' }).success).toBe(false);
+ expect(TreeViewSchema.safeParse({ type: 'tree-view', data: 'not-an-array' }).success).toBe(false);
+ // …and a good shape still passes, so the two above are not failing for some
+ // unrelated reason. ⚠️ The carrier carries BOTH spellings on purpose: it is
+ // legal with or without this card, so this control cannot redden for the
+ // relaxation it is controlling for. (That the authored, `nodes`-only
+ // fixtures parse is the first describe block's claim, not this one's.)
+ expect(TreeViewSchema.safeParse({
+ type: 'tree-view', title: 'File Explorer', data: [], nodes: [{ id: '1', label: 'Documents' }],
+ }).success).toBe(true);
+ });
+});