|
| 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 | +}); |
0 commit comments