Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit c3df43a

Browse files
feat(plugin-grid,types,react): ObjectGrid takes onNavigate as a prop that wins over schema.onNavigate, and the four onNavigate faces take one closed token, RecordNavigateAction (objectui#9547) (#11218)
Fixes #9547 Clause-②: yes ## What this does Ruling C on this card (decision batch 166, item 1, comment `5731678470`, maintainer 「同意」), step 3, in one pass now that objectui resolves `@objectstack/spec` 17.5.0 (triage probe `5904192911`): - `ObjectGridComponentProps` declares `onNavigate?: (recordId: string | number, action: RecordNavigateAction) => void`, and `ObjectGrid` reads `onNavigate: onNavigate ?? schema.onNavigate` — the ruling's `props.onNavigate ?? schema.onNavigate`, spelled with the destructured prop the way its nine siblings are. When both are supplied, the prop wins. - `RecordNavigateAction = 'view' | 'new_window'` is a new type export of `@object-ui/types`, and all four faces take it: the new prop, `ObjectGridSchema.onNavigate`, `ListViewRuntimeProps.onNavigate` (so `ListViewSchema['onNavigate']`), and `UseNavigationOverlayOptions.onNavigate` in `@object-ui/react`. Each face opens with the same sentence. ⛔ No interim `string`, ⛔ no `'edit'`. - The two docblocks that counted "nine siblings" now count ten: the programmatic-only note on `ObjectGridSchema.onNavigate`, and the read-site exemption comment in `ObjectGrid.tsx`. Every pinned phrase of both is unchanged. - `gridNonAuthorKeys.test.tsx`: the read-line anchor is re-aimed at `onNavigate: onNavigate ?? schema.onNavigate,`, by content. - New `onNavigateProp-9547.test.tsx`: the ruling's two pins (the prop is wired in `page` mode; the prop beats the schema key), plus a modifier click handing the prop `'new_window'`, type-level pins that each face's second parameter IS `RecordNavigateAction` and is required, and a read of the spec catalogue row against the union. - `.changeset/9547-ongrid-onnavigate-prop.md`: `minor` for `@object-ui/plugin-grid`, `@object-ui/types`, `@object-ui/react`, with the Clause-② paragraph and what a host has to change. Two commits: `1432197b88` (the type and the three sibling faces), `0c73dfb843` (the prop, the read, the pins, the changeset), then `fc90ce532d` merges `main` at `0389650f3c` (it brought PR #10278, objectui#9853, into `ObjectGrid.tsx` / `objectql.ts` / `objectql.zod.ts`; no conflict and no hunk near `onNavigate`). ## The PM's mechanism assumptions, measured 1. **Held, with one correction.** On `846cec0efe`: `ObjectGridComponentProps` declared no `onNavigate`; the grid read `onNavigate: schema.onNavigate`. In `objectql.ts`, `ObjectGridSchema.onNavigate` and `ListViewRuntimeProps.onNavigate` were `(recordId, action?: string)`; the `'view' | 'edit'` declaration is `ObjectViewSchema.onNavigate` — a different channel (`plugin-view`'s `ObjectView` invokes it with `'new'` / `'edit'` / `'view'` itself), not one of the ruling's three sibling faces, and it is untouched. `UseNavigationOverlayOptions` lives in `packages/react/src/hooks/useNavigationOverlay.ts`, typed `(recordId, action?: string)`. 2. **Falsified.** The installed `@objectstack/spec` 17.5.0 exports no TypeScript type for the union: `onNavigate` occurs in none of its `.d.ts` files, and `'view' | 'new_window'` occurs only as the `type` STRING of the `onNavigate` row in the `ListView` entry of `REACT_BLOCKS` (`dist/ui/index.mjs`). objectstack `main` (`05a7547c9f`) is the same. ⇒ the literal is spelled once, as `RecordNavigateAction`, and the spec-row case in the new test fails if the two vocabularies part. 3. **Held.** `handleClick` in `useNavigationOverlay` calls `onNavigate` at four sites: two pass `'new_window'`, two pass `'view'`, none passes `'edit'` (the retired `navigation.view` read is already gone). The option is now typed against the union, so a third token there is a compile error. The pins assert that `('1', 'view')` in `page` mode and `('1', 'new_window')` on a meta-click reach the prop. 4. **Held.** No test counts `ObjectGridComponentProps` members; the "nine" census is the two docblocks' prose. `NINE_SIBLINGS` in `gridNonAuthorKeys.test.tsx` asserts the nine are NOT declared on `ObjectGridSchema`, which stays true, so it is unchanged. ## Files outside the claim's list, and why - `packages/types/src/index.ts` — one barrel line exporting `RecordNavigateAction`; "one place, reused" across three packages needs the export. - `packages/types/src/zod/objectql.zod.ts`, `packages/types/src/__tests__/zod-mirror-parity.test.ts` — comments only. Two contrasted `ObjectViewSchema.onNavigate` with "the grid's `action?: string`" and two quoted the grid's read as `onNavigate: schema.onNavigate`. This change made all four false, so they now name the new type and quote the new read. ## What a host sees - A handler written `(id, action?: string) => …`, or with one parameter, still compiles and receives what it received before. - A handler annotated with a union that leaves out `'new_window'` (the old docblock's `'view' | 'edit'`) is refused with TS2322. Measured with a throwaway probe compiled by `plugin-grid`'s `tsconfig.test.json` and deleted afterwards: TS2322 on a `'view' | 'edit'` handler, TS2345 on a call passing `'edit'`, TS2554 on a call omitting the token, no error on the two accepted shapes. - In-repo consumers that pass a handler (`app-shell`'s `ObjectView`, `InterfaceListPage`, `ObjectDataPage`; `plugin-gantt`'s `ObjectGantt`; `plugin-list`'s `ListView`) all type-check unchanged. ## Tests — all on `fc90ce532d` (the head this PR opens at) unless marked Every heavy run went through the shared lock; the verdict lines quoted are the lock's own. - Build: `pnpm --workspace-concurrency=2 --filter '@object-ui/app-shell^...' --filter '@object-ui/plugin-gantt^...' build` → `VERDICT command-exit 0` (covers the `plugin-grid` closure). - Type-check, touched packages and the downstream consumers of the narrowed faces: `pnpm --workspace-concurrency=2 --filter @object-ui/types --filter @object-ui/react --filter @object-ui/plugin-grid --filter @object-ui/plugin-list --filter @object-ui/plugin-gantt --filter @object-ui/plugin-view --filter @object-ui/app-shell run type-check` → all seven `type-check: Done`, `VERDICT command-exit 0`. `tsc -p tsconfig.test.json --listFiles` in `plugin-grid` lists `onNavigateProp-9547.test.tsx`, so the type-level pins are compiled. - `pnpm exec vitest run --maxWorkers=2 --shard=1/2 packages/plugin-grid/` → `Test Files 87 passed (87)`, `Tests 769 passed (769)`; `--shard=2/2` → `Test Files 86 passed (86)`, `Tests 824 passed (824)`. - `pnpm exec vitest run --maxWorkers=2 packages/types/ packages/react/` → `Test Files 393 passed (393)`, `Tests 8257 passed (8257)`. - `node scripts/check-changeset-presence.mjs` → exit 0, "8 source file(s) of 3 released package(s) changed, and this change declares 1 changeset(s)". - `pnpm check:control-bytes` → exit 0 · `check:spec-symbols` → exit 0 · `check:new-line-citations` → `VERDICT new-cross-file-line-citations: 0 new citation(s)` · `check:handler-key-reads` → exit 0, "every judged read is a declared member of its arm" · `check:doc-example-readers` → exit 0 · `check:changeset-claims` → exit 0 (report-only) · `check:pending-changeset-literals` → exit 0. - ESLint on the 8 changed TS/TSX files, the packages' own `eslint .` form: 8 file results in `--format json`, 0 errors, 252 warnings (1 of them in the new test: `no-explicit-any` on the fake adapter cast, the same idiom `gridNonAuthorKeys.test.tsx` uses). `eslint.config.js` sets no `parserOptions` / `projectService`, so linting is not type-aware and this diff cannot move a verdict on an untouched file. The repo-wide lint is CI's. ## Reverse verification (committed first, restored by blob hash) - **Behaviour**, on `0c73dfb843`, through `ablation-replace.mjs` with the read reverted to `onNavigate: schema.onNavigate,` (on-disk counts during the run: mutated line 1, real line 0): `Tests 4 failed | 41 passed (45)` — the three new prop cases and the re-aimed anchor went red; the schema-only control ("the renderer still reads it") stayed green. Restored: blob equals HEAD, `git diff HEAD` empty. - **Types**, on `0c73dfb843`, through the rebuilt `dist/` (plugin-grid resolves `@object-ui/types` through its exports): `ListViewRuntimeProps.onNavigate` widened back to `action?: string`, types rebuilt, the mutated declaration counted 1 in `dist/objectql.d.ts`, then `tsc -p tsconfig.test.json` in plugin-grid → exit 2 with exactly two TS2344 errors, on the `ListViewFace` and `ListViewArity` pins. Restore leg: source restored by blob hash, types rebuilt, mutated declaration 0 in `dist`, real declaration 2, the same `tsc` exit 0. ## Acceptance notes - `packages/plugin-grid/README.md` and `content/docs/plugins/plugin-grid.mdx` ("Row callbacks are component props") stay true — they already tell callers to prefer passing `onNavigate` as a prop — but neither lists it with the nine or names `RecordNavigateAction`. Not edited: outside the claimed file surface. Carrier: the dispatching seat. - `check:readme-exports` → exit 1 because 8 packages outside this change were unbuilt here ("could not be judged", 0 fabricated). NOT MEASURED; this diff edits no README. - The spec-row case was not ablated: it reads the installed catalogue, which this PR does not change. --- _Generated by [Claude Code](https://claude.ai/code/session_0122Knsowci76D2rBWReCzzZ)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent e6bc087 commit c3df43a

9 files changed

Lines changed: 327 additions & 27 deletions

File tree

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
'@object-ui/plugin-grid': minor
3+
'@object-ui/types': minor
4+
'@object-ui/react': minor
5+
---
6+
7+
`ObjectGrid` takes `onNavigate` as a component prop, and the list channel's navigation callback takes one closed mode token, `'view' | 'new_window'`.
8+
9+
`ObjectGridSchema.onNavigate`'s documentation told programmatic callers to pass it on `ObjectGridComponentProps`, where the grid's nine other callbacks live — but that interface did not declare it, so a host that followed the advice passed a function the grid never called, with no diagnostic. `ObjectGridComponentProps` now declares `onNavigate`, and the grid reads the prop first and `schema.onNavigate` only when no prop is supplied: when both are given, the prop wins. `onRowClick`, when supplied, still takes the row click before either.
10+
11+
The callback's second argument is now `RecordNavigateAction`, a new type exported by `@object-ui/types`: the closed union `'view' | 'new_window'`, where `'view'` opens the record page and `'new_window'` opens it in a new browser tab. It is exactly what `useNavigationOverlay` emits, and the vocabulary `@objectstack/spec` 17.5.0 gives the react-tier `ListView` `onNavigate` callback. The same type now sits on all four faces of the channel — `ObjectGridComponentProps.onNavigate`, `ObjectGridSchema.onNavigate`, `ListViewSchema.onNavigate`, and `UseNavigationOverlayOptions.onNavigate` in `@object-ui/react` — where the three existing faces declared `action?: string` and two of them described it as `'view' | 'edit'`. No branch of the hook passes `'edit'`.
12+
13+
**Clause-②: yes** — one prop added (`ObjectGridComponentProps.onNavigate`), one type exported (`RecordNavigateAction`), and three published callback types narrowed from `(recordId, action?: string) => void` to `(recordId, action: RecordNavigateAction) => void`. What a host has to change:
14+
15+
- A handler you supply that is written `(id, action?: string) => …`, or with no second parameter at all, still compiles unchanged and receives exactly what it received before.
16+
- A handler whose second parameter is annotated with a union that leaves out `'new_window'` — the old documentation's `'view' | 'edit'` is the likely one — is now refused with TS2322. Annotate it `RecordNavigateAction` (or drop the annotation) and handle `'new_window'`, which a Cmd/Ctrl/middle-click and `navigation.mode: 'new_window'` already deliver.
17+
- Code that CALLS one of these callbacks itself must now pass the second argument, and it must be one of the two members.

‎packages/plugin-grid/src/ObjectGrid.tsx‎

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
*/
2323

2424
import React, { useEffect, useState, useCallback, useMemo } from 'react';
25-
import type { ObjectGridSchema, DataSource, ListColumn, TableColumn, ViewData, TableSortItem, DataTableSchema, ListViewExportFormat } from '@object-ui/types';
25+
import type { ObjectGridSchema, DataSource, ListColumn, TableColumn, ViewData, TableSortItem, DataTableSchema, ListViewExportFormat, RecordNavigateAction } from '@object-ui/types';
2626
import { isSystemManagedField, normalizeTableColumnType } from '@object-ui/types';
2727
import type { I18nLabel } from '@objectstack/spec/ui';
2828
import { parseFilterAST, type FilterCondition } from '@objectstack/spec/data';
@@ -698,6 +698,22 @@ export interface ObjectGridComponentProps extends ObjectGridExternalPaginationPr
698698
* already use this spelling for exactly this situation.
699699
*/
700700
onRowClick?: (record: any, event?: any) => void;
701+
/**
702+
* Called for page-level navigation with the record id and a
703+
* {@link RecordNavigateAction} — a navigation-MODE token from a closed
704+
* vocabulary: `'view'` opens the record page, `'new_window'` opens it in a
705+
* new browser tab.
706+
*
707+
* [objectui#9547] The tenth callback on this interface, and the channel a
708+
* programmatic caller should use: its nine siblings below are props here
709+
* too, and `ObjectGridSchema.onNavigate`'s own docblock sends callers to
710+
* this interface for it. That schema key still works — it is the
711+
* same slot reached off the node — and when BOTH are supplied, THIS PROP
712+
* WINS (maintainer ruling C on objectui#9547: the programmatic caller is the
713+
* nearer party). `onRowClick` above still takes full priority over either:
714+
* a host that owns the row click owns navigation too.
715+
*/
716+
onNavigate?: (recordId: string | number, action: RecordNavigateAction) => void;
701717
onEdit?: (record: any) => void;
702718
onDelete?: (record: any) => void;
703719
onBulkDelete?: (records: any[]) => void;
@@ -1463,6 +1479,7 @@ export const ObjectGrid: React.FC<ObjectGridComponentProps> = ({
14631479
onBulkDelete,
14641480
onRowSelect,
14651481
onRowClick,
1482+
onNavigate,
14661483
onCellChange,
14671484
onRowSave,
14681485
onBatchSave,
@@ -2834,8 +2851,12 @@ export const ObjectGrid: React.FC<ObjectGridComponentProps> = ({
28342851
// three. Programmatic callers already have the channel its nine siblings
28352852
// use: `onRowClick`, `onRowSelect`, `onCellChange`, `onRowSave`,
28362853
// `onBatchSave`, `onEdit`, `onDelete`, `onBulkDelete` and `onAddRecord`
2837-
// are props on `ObjectGridComponentProps`, and that is where a caller
2838-
// should prefer to pass this one too.
2854+
// are props on `ObjectGridComponentProps`, and since objectui#9547 this one
2855+
// is the tenth prop there, which is where a caller should prefer to pass
2856+
// it. When both are supplied the PROP WINS (maintainer ruling C on
2857+
// objectui#9547), so `schema.onNavigate` below is the fallback read — kept,
2858+
// because a host that builds the node in TypeScript still reaches the slot
2859+
// that way. `__tests__/onNavigateProp-9547.test.tsx` pins both halves.
28392860
//
28402861
// The contract says the same thing independently: `ComponentPropsMap
28412862
// ['object-grid']` (`@objectstack/spec@17`) is a `strictObject` and
@@ -2844,7 +2865,7 @@ export const ObjectGrid: React.FC<ObjectGridComponentProps> = ({
28442865
// rejected there — are pinned by `__tests__/gridNonAuthorKeys.test.tsx`,
28452866
// together with the read itself, so this exemption cannot decay into a
28462867
// silent drop.
2847-
onNavigate: schema.onNavigate,
2868+
onNavigate: onNavigate ?? schema.onNavigate,
28482869
onRowClick,
28492870
});
28502871

‎packages/plugin-grid/src/__tests__/gridNonAuthorKeys.test.tsx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -784,11 +784,14 @@ describe('`onNavigate` — the exemption is DOCUMENTED, which is what this card
784784
it('the read site in ObjectGrid.tsx carries the exemption comment', () => {
785785
// Anchored on the read line, which exists in both states of the world, so a
786786
// red here means the COMMENT went missing — never that the anchor moved.
787-
const reads = indicesWhere(gridLines, (t) => t === 'onNavigate: schema.onNavigate,');
787+
// Re-aimed by objectui#9547: the read became `onNavigate ?? schema.onNavigate`
788+
// (the component prop first, the schema key as its fallback — ruling C on
789+
// that card), and `onNavigateProp-9547.test.tsx` pins that precedence.
790+
const reads = indicesWhere(gridLines, (t) => t === 'onNavigate: onNavigate ?? schema.onNavigate,');
788791
expect(
789792
reads.length,
790-
'the `onNavigate: schema.onNavigate` read is gone or duplicated; re-aim this pin before'
791-
+ ' trusting anything else in this describe.',
793+
'the `onNavigate: onNavigate ?? schema.onNavigate` read is gone or duplicated; re-aim this'
794+
+ ' pin before trusting anything else in this describe.',
792795
).toBe(1);
793796

794797
const block = commentBlockAbove(gridLines, reads[0]);
Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
/**
2+
* ObjectUI
3+
* Copyright (c) 2024-present ObjectStack Inc.
4+
*
5+
* This source code is licensed under the MIT license found in the
6+
* LICENSE file in the root directory of this source tree.
7+
*
8+
* objectui#9547 — `onNavigate` is a prop on `ObjectGridComponentProps`, the
9+
* prop wins over `schema.onNavigate`, and the four faces of the list channel
10+
* take one closed mode token.
11+
*
12+
* ## What was wrong
13+
*
14+
* `ObjectGridSchema.onNavigate`'s docblock sent programmatic callers to
15+
* `ObjectGridComponentProps` — "that is where a caller should prefer to pass
16+
* this one too" — and the interface did not declare it. A host that followed
17+
* the advice passed a function the grid never called, with no diagnostic.
18+
*
19+
* ## What the maintainer ruled (ruling C on objectui#9547)
20+
*
21+
* The prop exists and is read as `props.onNavigate ?? schema.onNavigate`: the
22+
* programmatic caller is the nearer party, so the prop wins. Its second
23+
* argument is the closed union `'view' | 'new_window'` — the vocabulary
24+
* `useNavigationOverlay` emits and the `@objectstack/spec` react-tier
25+
* `ListView` catalogue publishes — and the three sibling faces
26+
* (`ObjectGridSchema.onNavigate`, `ListViewRuntimeProps.onNavigate`,
27+
* `UseNavigationOverlayOptions.onNavigate`) take the same type. ⛔ No `string`,
28+
* ⛔ no `'edit'`: no branch of the hook emits it.
29+
*
30+
* ## The pins
31+
*
32+
* - behavioural: the prop fires in `page` mode with `'view'`; a modifier click
33+
* delivers `'new_window'` to it; with BOTH supplied only the prop fires. The
34+
* schema-only case is the control and already lives in
35+
* `gridNonAuthorKeys.test.tsx` ("the renderer still reads it").
36+
* - type-level: the four faces' second parameter IS `RecordNavigateAction`,
37+
* required, and that type is exactly the two members. Compiled by this
38+
* package's `tsconfig.test.json`; vitest erases them.
39+
* - spec: the catalogue row's `type` STRING names the same members, so the
40+
* one hand-spelled union in `@object-ui/types` cannot drift from it quietly.
41+
*/
42+
43+
import { describe, it, expect, vi } from 'vitest';
44+
import { render, screen, waitFor, fireEvent } from '@testing-library/react';
45+
import '@testing-library/jest-dom';
46+
import React from 'react';
47+
import { REACT_BLOCKS } from '@objectstack/spec/ui';
48+
import { ActionProvider, type UseNavigationOverlayOptions } from '@object-ui/react';
49+
import type { ListViewSchema, ObjectGridSchema, RecordNavigateAction } from '@object-ui/types';
50+
import { ObjectGrid } from '../ObjectGrid';
51+
import type { ObjectGridComponentProps } from '../ObjectGrid';
52+
53+
const rows = [
54+
{ id: '1', name: 'Alice', email: 'alice@example.com' },
55+
{ id: '2', name: 'Bob', email: 'bob@example.com' },
56+
];
57+
58+
function makeAdapter() {
59+
return {
60+
find: vi.fn().mockResolvedValue({ data: rows, total: rows.length }),
61+
findOne: vi.fn(),
62+
create: vi.fn(),
63+
update: vi.fn(),
64+
delete: vi.fn(),
65+
getObjectSchema: vi.fn().mockResolvedValue({
66+
name: 'test_object',
67+
fields: { id: { type: 'text' }, name: { type: 'text' }, email: { type: 'text' } },
68+
}),
69+
};
70+
}
71+
72+
function renderGrid(
73+
schemaExtra: Record<string, unknown>,
74+
props: Partial<ObjectGridComponentProps> = {},
75+
) {
76+
const schema = {
77+
type: 'object-grid',
78+
objectName: 'test_object',
79+
columns: [{ field: 'name', label: 'Name' }, { field: 'email', label: 'Email' }],
80+
data: { provider: 'value', items: rows },
81+
navigation: { mode: 'page' },
82+
...schemaExtra,
83+
} as ObjectGridSchema;
84+
return render(
85+
<ActionProvider>
86+
<ObjectGrid schema={schema} dataSource={makeAdapter() as any} {...props} />
87+
</ActionProvider>,
88+
);
89+
}
90+
91+
/** Alice's email cell — a plain cell, so the click reaches the row handler. */
92+
async function aliceCell(container: HTMLElement): Promise<HTMLElement> {
93+
await waitFor(() => expect(screen.getByText('alice@example.com')).toBeInTheDocument());
94+
const cell = Array.from(container.querySelectorAll('tbody td')).find(
95+
(td) => td.textContent?.trim() === 'alice@example.com',
96+
);
97+
expect(cell, 'the fixture row never rendered, so a silent no-call would look like a pass').toBeTruthy();
98+
return cell as HTMLElement;
99+
}
100+
101+
describe('objectui#9547 — the `onNavigate` PROP reaches the row click', () => {
102+
it('fires in `page` mode with the record id and `view`', async () => {
103+
const onNavigate = vi.fn();
104+
const { container } = renderGrid({ id: 'prop-page' }, { onNavigate });
105+
106+
fireEvent.click(await aliceCell(container));
107+
108+
await waitFor(() =>
109+
expect(
110+
onNavigate,
111+
'the `onNavigate` PROP no longer fires on a row click — the read at the'
112+
+ ' `useNavigationOverlay` call stopped consulting the prop.',
113+
).toHaveBeenCalledTimes(1),
114+
);
115+
expect(onNavigate).toHaveBeenCalledWith('1', 'view');
116+
});
117+
118+
it('a modifier click delivers the other member, `new_window`, to the same prop', async () => {
119+
const onNavigate = vi.fn();
120+
const { container } = renderGrid({ id: 'prop-meta' }, { onNavigate });
121+
122+
fireEvent.click(await aliceCell(container), { metaKey: true });
123+
124+
await waitFor(() => expect(onNavigate).toHaveBeenCalledTimes(1));
125+
expect(onNavigate).toHaveBeenCalledWith('1', 'new_window');
126+
});
127+
128+
it('with BOTH supplied, the prop wins and the schema key is not called', async () => {
129+
const fromProp = vi.fn();
130+
const fromSchema = vi.fn();
131+
const { container } = renderGrid({ id: 'prop-wins', onNavigate: fromSchema }, { onNavigate: fromProp });
132+
133+
fireEvent.click(await aliceCell(container));
134+
135+
await waitFor(() => expect(fromProp).toHaveBeenCalledTimes(1));
136+
expect(fromProp).toHaveBeenCalledWith('1', 'view');
137+
expect(
138+
fromSchema,
139+
'`schema.onNavigate` fired although the prop was supplied — ruling C on objectui#9547'
140+
+ ' made the prop win (`props.onNavigate ?? schema.onNavigate`).',
141+
).not.toHaveBeenCalled();
142+
});
143+
});
144+
145+
// ---------------------------------------------------------------------------
146+
// One type, four faces — compile-time. The `it` below only keeps the suite
147+
// honest about there being nothing to run; `tsc -p tsconfig.test.json` is what
148+
// checks these.
149+
// ---------------------------------------------------------------------------
150+
151+
type Assert<T extends true> = T;
152+
type IsAny<T> = 0 extends 1 & T ? true : false;
153+
type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
154+
? true
155+
: false;
156+
type ActionOf<F> = F extends (recordId: string | number, action: infer A) => void ? A : never;
157+
type ArityOf<F> = F extends (...args: infer P) => void ? P['length'] : never;
158+
159+
type PropFace = NonNullable<ObjectGridComponentProps['onNavigate']>;
160+
type SchemaFace = NonNullable<ObjectGridSchema['onNavigate']>;
161+
type ListViewFace = NonNullable<ListViewSchema['onNavigate']>;
162+
type HookFace = NonNullable<UseNavigationOverlayOptions['onNavigate']>;
163+
164+
/** The two members, spelled once more so the spec comparison has a runtime value. */
165+
const MEMBERS = ['new_window', 'view'] as const satisfies readonly RecordNavigateAction[];
166+
167+
type _TypeIsTheTwoMembers = Assert<Equal<RecordNavigateAction, 'view' | 'new_window'>>;
168+
type _MembersAreExhaustive = Assert<Equal<(typeof MEMBERS)[number], RecordNavigateAction>>;
169+
type _NotAny = Assert<Equal<IsAny<RecordNavigateAction>, false>>;
170+
type _PropFace = Assert<Equal<ActionOf<PropFace>, RecordNavigateAction>>;
171+
type _SchemaFace = Assert<Equal<ActionOf<SchemaFace>, RecordNavigateAction>>;
172+
type _ListViewFace = Assert<Equal<ActionOf<ListViewFace>, RecordNavigateAction>>;
173+
type _HookFace = Assert<Equal<ActionOf<HookFace>, RecordNavigateAction>>;
174+
// Required on every face, as the catalogue types it: an optional `action?`
175+
// would read `1 | 2` here and hand a host `undefined` to branch on.
176+
type _PropArity = Assert<Equal<ArityOf<PropFace>, 2>>;
177+
type _SchemaArity = Assert<Equal<ArityOf<SchemaFace>, 2>>;
178+
type _ListViewArity = Assert<Equal<ArityOf<ListViewFace>, 2>>;
179+
type _HookArity = Assert<Equal<ArityOf<HookFace>, 2>>;
180+
181+
describe('objectui#9547 — the four faces take one closed mode token', () => {
182+
it('is pinned at compile time', () => {
183+
expect(MEMBERS).toHaveLength(2);
184+
});
185+
186+
it('the `@objectstack/spec` react-tier `ListView` catalogue row names exactly these members', () => {
187+
const listView = REACT_BLOCKS.find((block) => block.tag === 'ListView');
188+
expect(listView, 'the spec catalogue no longer carries a `ListView` block').toBeTruthy();
189+
const row = listView!.interactions.find((prop) => prop.name === 'onNavigate');
190+
expect(row, 'the spec `ListView` block no longer carries an `onNavigate` row').toBeTruthy();
191+
192+
// The catalogue types the callback as TEXT, e.g.
193+
// "(recordId, action: 'view' | 'new_window') => void" — read the union out.
194+
const union = /action\??:\s*([^)]*)\)/.exec(row!.type)?.[1];
195+
expect(union, `the catalogue row's type no longer names an \`action\` parameter: ${row!.type}`).toBeTruthy();
196+
const specMembers = union!
197+
.split('|')
198+
.map((member) => member.trim().replace(/^'|'$/g, ''))
199+
.sort();
200+
201+
expect(
202+
specMembers,
203+
'`@objectstack/spec` now publishes a different navigation-mode vocabulary for'
204+
+ ' `ListView.onNavigate` than `RecordNavigateAction` in `@object-ui/types`. Move the'
205+
+ ' union there (and the four faces with it), or raise it upstream — never widen one side alone.',
206+
).toEqual([...MEMBERS].sort());
207+
});
208+
});

‎packages/react/src/hooks/useNavigationOverlay.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
import { useState, useCallback, useMemo } from 'react';
5353

5454
import type { NavigationConfigSchema, NavigationMode as SpecNavigationMode } from '@objectstack/spec/ui';
55+
import type { RecordNavigateAction } from '@object-ui/types';
5556
import type { SpecAuthoredInput } from '../spec-input.js';
5657

5758
/**
@@ -171,8 +172,19 @@ export interface UseNavigationOverlayOptions {
171172
navigation?: NavigationConfig;
172173
/** Object name — used to build default URLs for page/new_window modes */
173174
objectName?: string;
174-
/** External onNavigate callback (e.g., from ActionProvider or parent) */
175-
onNavigate?: (recordId: string | number, action?: string) => void;
175+
/**
176+
* Called for page-level navigation with the record id and a
177+
* {@link RecordNavigateAction} — a navigation-MODE token from a closed
178+
* vocabulary: `'view'` opens the record page, `'new_window'` opens it in a
179+
* new browser tab.
180+
*
181+
* `handleClick` below is the one producer of that token, and every call it
182+
* makes is typed against this declaration — so a third token is a compile
183+
* error here, not a branch a host's handler silently never matches
184+
* (objectui#9547). Supplied by the host that renders the list (a
185+
* `schema.onNavigate`, a component prop, or the host's own router closure).
186+
*/
187+
onNavigate?: (recordId: string | number, action: RecordNavigateAction) => void;
176188
/**
177189
* External onRowClick callback — if set, takes full priority.
178190
*

‎packages/types/src/__tests__/zod-mirror-parity.test.ts‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2334,17 +2334,18 @@ interface KnownDrift {
23342334
* `ComponentPropsMap['object-grid']` `strictObject` already refused the key.
23352335
*
23362336
* ⚠️ No in-repo host builds an `object-grid` node carrying it — measured. The
2337-
* read is live and deliberate (`onNavigate: schema.onNavigate` into
2338-
* `useNavigationOverlay`), and `plugin-grid`'s `gridNonAuthorKeys.test.tsx`
2337+
* read is live and deliberate (`onNavigate: onNavigate ?? schema.onNavigate`
2338+
* into `useNavigationOverlay` — the fallback behind the component prop since
2339+
* objectui#9547), and `plugin-grid`'s `gridNonAuthorKeys.test.tsx`
23392340
* supplies it from a schema and asserts the call fires.
23402341
*/
23412342
'objectql.zod.ts#ObjectGridSchema': 'onNavigate';
23422343
/**
23432344
* RUNTIME SLOT (objectui#6124 shape, declared by objectui#7804) — the same
23442345
* key NAME as the entry above and nothing else in common: a different second
2345-
* parameter (`mode: 'view' | 'edit'` rather than `action?: string`), a
2346-
* different renderer, a different supplier. Judged separately for exactly
2347-
* that reason.
2346+
* parameter (`mode: 'view' | 'edit'` rather than
2347+
* `action: RecordNavigateAction`, objectui#9547), a different renderer, a
2348+
* different supplier. Judged separately for exactly that reason.
23482349
*
23492350
* `plugin-view`'s `ObjectView` invokes it at four sites —
23502351
* `schema.onNavigate('new', 'edit')` on create, and the record id with

‎packages/types/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -473,6 +473,7 @@ export type {
473473
ObjectViewSchema,
474474
NamedListView,
475475
ViewNavigationConfig,
476+
RecordNavigateAction,
476477
ViewTabBarConfig,
477478
ObjectQLComponentSchema,
478479
ObjectCalendarBlockConfig,

0 commit comments

Comments
 (0)