|
| 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#7313 — `ObjectCalendarSchema` declares the record-source ladder its |
| 9 | + * renderer already reads, on both faces, in the shape objectui#6939 landed on |
| 10 | + * `object-map` / `object-gantt` (PR #7471). |
| 11 | + * |
| 12 | + * ## The defect |
| 13 | + * |
| 14 | + * `ObjectCalendar` resolves its records through the shared ladder — |
| 15 | + * `resolveRecordSourceConfig(schema)` in `@object-ui/core` |
| 16 | + * (`packages/core/src/utils/record-source.ts`): `data`, then `staticData`, then |
| 17 | + * `objectName`, `null` when none is present. The published interface REQUIRED |
| 18 | + * `objectName` and declared neither `data` nor `staticData`; the mirror did the |
| 19 | + * same (no `requireRecordSource`). So the two static-data examples |
| 20 | + * `content/docs/plugins/plugin-calendar.mdx` teaches rendered correctly, were |
| 21 | + * refused by `safeValidateSchema`, and could not be annotated with their own |
| 22 | + * type (`TS2741: Property 'objectName' is missing`). |
| 23 | + * |
| 24 | + * Measured on `origin/main` at `91f92768` (identical to the dispatch base |
| 25 | + * `4dfdcc3c` on both faces), pristine dist, four documents through |
| 26 | + * `ObjectCalendarSchema.safeParse`: |
| 27 | + * |
| 28 | + * staticData only -> refused at `objectName` (invalid_type) |
| 29 | + * data only -> refused at `objectName` (invalid_type) |
| 30 | + * none of the three-> refused at `objectName` (invalid_type) |
| 31 | + * objectName only -> accepted |
| 32 | + * |
| 33 | + * `ObjectGanttSchema` on the same four: accepted / accepted / refused ON THE |
| 34 | + * REFINEMENT / accepted. This file pins that the calendar now agrees with the |
| 35 | + * gantt verdict-for-verdict, and WHY each verdict is what it is. |
| 36 | + * |
| 37 | + * ## What this file pins — the VALIDATOR and DECLARATION halves |
| 38 | + * |
| 39 | + * The render half needs no new pin: the renderer never changed. The read it |
| 40 | + * performs is pinned off disk below, so a later rewrite of the ladder cannot |
| 41 | + * leave this declaration describing a read that no longer exists. |
| 42 | + */ |
| 43 | +import { describe, it, expect } from 'vitest'; |
| 44 | +import { readFileSync } from 'node:fs'; |
| 45 | +import { fileURLToPath } from 'node:url'; |
| 46 | +import { dirname, join } from 'node:path'; |
| 47 | + |
| 48 | +import { ObjectCalendarSchema, ObjectGanttSchema, safeValidateSchema } from '../zod/index.zod'; |
| 49 | +import { BaseSchema } from '../zod/base.zod'; |
| 50 | +import type { |
| 51 | + ObjectCalendarSchema as TsObjectCalendarSchema, |
| 52 | + ObjectGanttSchema as TsObjectGanttSchema, |
| 53 | + ObjectKanbanSchema as TsObjectKanbanSchema, |
| 54 | + ViewData, |
| 55 | +} from '../objectql'; |
| 56 | + |
| 57 | +const HERE = dirname(fileURLToPath(import.meta.url)); |
| 58 | +const REPO_ROOT = join(HERE, '..', '..', '..', '..'); |
| 59 | +const RENDERER = 'packages/plugin-calendar/src/ObjectCalendar.tsx'; |
| 60 | +const LADDER = 'packages/core/src/utils/record-source.ts'; |
| 61 | +const DOC_PAGE = 'content/docs/plugins/plugin-calendar.mdx'; |
| 62 | + |
| 63 | +/* ── Type-level pins (invariant equality, house form) ─────────────────────── */ |
| 64 | + |
| 65 | +type Equal< A, B > = |
| 66 | + (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false; |
| 67 | +type Expect< T extends true > = T; |
| 68 | +/** `Partial< Pick< T, K > >` is assignable to `Pick< T, K >` exactly when `K` is optional on `T`. */ |
| 69 | +type IsOptionalKey< T, K extends keyof T > = Partial< Pick< T, K > > extends Pick< T, K > ? true : false; |
| 70 | + |
| 71 | +/** |
| 72 | + * `objectName` is OPTIONAL and still `string`. Both directions bite: required |
| 73 | + * again -> `string` is not `string | undefined` -> red; member DELETED -> the |
| 74 | + * key resolves through `BaseSchema`'s index signature to `any`, and |
| 75 | + * `Equal< any, … >` is false -> red. |
| 76 | + */ |
| 77 | +export type _CalendarObjectNameIsOptionalString = |
| 78 | + Expect< Equal< TsObjectCalendarSchema['objectName'], string | undefined > >; |
| 79 | +export type _CalendarObjectNameIsOptionalKey = |
| 80 | + Expect< IsOptionalKey< TsObjectCalendarSchema, 'objectName' > >; |
| 81 | + |
| 82 | +/** |
| 83 | + * `data` is DECLARED, optional, and `ViewData` — not `any`. Deleting the member |
| 84 | + * does NOT fall through to the index signature: it lands on the INHERITED |
| 85 | + * `BaseSchema.data?: any` (a declared member wins over an index signature), and |
| 86 | + * `Equal< any, ViewData | undefined >` is false -> red. That is the whole |
| 87 | + * reason the member is declared here rather than left to the base. |
| 88 | + */ |
| 89 | +export type _CalendarDataIsOptionalViewData = |
| 90 | + Expect< Equal< TsObjectCalendarSchema['data'], ViewData | undefined > >; |
| 91 | +export type _CalendarDataIsOptionalKey = |
| 92 | + Expect< IsOptionalKey< TsObjectCalendarSchema, 'data' > >; |
| 93 | + |
| 94 | +/** `staticData` is DECLARED and optional; deleted, it would resolve to `any`. */ |
| 95 | +export type _CalendarStaticDataIsOptionalAnyArray = |
| 96 | + Expect< Equal< TsObjectCalendarSchema['staticData'], any[] | undefined > >; |
| 97 | +export type _CalendarStaticDataIsOptionalKey = |
| 98 | + Expect< IsOptionalKey< TsObjectCalendarSchema, 'staticData' > >; |
| 99 | + |
| 100 | +/** One concept, one type: the calendar's three keys are the gantt's three keys. */ |
| 101 | +export type _CalendarDataMatchesGantt = |
| 102 | + Expect< Equal< TsObjectCalendarSchema['data'], TsObjectGanttSchema['data'] > >; |
| 103 | +export type _CalendarStaticDataMatchesGantt = |
| 104 | + Expect< Equal< TsObjectCalendarSchema['staticData'], TsObjectGanttSchema['staticData'] > >; |
| 105 | +export type _CalendarObjectNameMatchesGantt = |
| 106 | + Expect< Equal< TsObjectCalendarSchema['objectName'], TsObjectGanttSchema['objectName'] > >; |
| 107 | + |
| 108 | +/** |
| 109 | + * The document the plugin page teaches under "With Static Data". It did not |
| 110 | + * compile before this card — `objectName` was a required member, and an index |
| 111 | + * signature cannot rescue a MISSING required key — so this annotation is a real |
| 112 | + * compile-time pin. |
| 113 | + */ |
| 114 | +export const STATIC_DATA_DOCUMENT: TsObjectCalendarSchema = { |
| 115 | + type: 'object-calendar', |
| 116 | + staticData: [{ id: 1, title: 'Team Meeting', startDate: '2024-01-15T10:00:00' }], |
| 117 | +}; |
| 118 | + |
| 119 | +/** …and the `data`-authored one, typed against the declared `ViewData`. */ |
| 120 | +export const DATA_DOCUMENT: TsObjectCalendarSchema = { |
| 121 | + type: 'object-calendar', |
| 122 | + data: { provider: 'value', items: [{ id: 1, title: 'Team Meeting' }] }, |
| 123 | +}; |
| 124 | + |
| 125 | +/** |
| 126 | + * CLASS BOUNDARY, recorded without touching it (triage boundary 3 on |
| 127 | + * objectui#7313): `ObjectKanbanSchema` still REQUIRES `objectName`. Its |
| 128 | + * renderer reads `schema.data` ahead of the fetch and guards every |
| 129 | + * `objectName` read, so it carries the same defect class — but that block is |
| 130 | + * objectui#7322's, and this control only says where the class currently ends. |
| 131 | + * When a card moves the kanban's `objectName` to optional, this directive is |
| 132 | + * the line that card deletes. |
| 133 | + * |
| 134 | + * `groupBy` is supplied because objectui#7322 made it the required lane key |
| 135 | + * (and retired `groupField`), so `objectName` is the ONE member this literal |
| 136 | + * is missing — the directive would otherwise be satisfied by an unrelated |
| 137 | + * omission and stop saying anything about `objectName`. |
| 138 | + */ |
| 139 | +// @ts-expect-error — objectName is still required on ObjectKanbanSchema (the one deliberate error here) |
| 140 | +export const KANBAN_STILL_REQUIRES_OBJECT_NAME: TsObjectKanbanSchema = { |
| 141 | + type: 'object-kanban', |
| 142 | + groupBy: 'status', |
| 143 | +}; |
| 144 | + |
| 145 | +/* ── Runtime pins ─────────────────────────────────────────────────────────── */ |
| 146 | + |
| 147 | +/** |
| 148 | + * The four documents the card's verdict table is written over. `data` uses |
| 149 | + * the value provider — the config `staticData` is folded into, so the two |
| 150 | + * accepted-without-`objectName` rows exercise different keys but one route. |
| 151 | + */ |
| 152 | +const DOCUMENTS = { |
| 153 | + staticOnly: { staticData: [{ id: 1, title: 'Team Meeting', startDate: '2024-01-15T10:00:00' }] }, |
| 154 | + dataOnly: { data: { provider: 'value', items: [{ id: 1, title: 'Team Meeting' }] } }, |
| 155 | + none: {}, |
| 156 | + objectOnly: { objectName: 'events' }, |
| 157 | +} as const; |
| 158 | +type DocumentName = keyof typeof DOCUMENTS; |
| 159 | +const DOCUMENT_NAMES = Object.keys(DOCUMENTS) as DocumentName[]; |
| 160 | + |
| 161 | +/** The refinement's message, spelled exactly as the map/gantt members emit it. */ |
| 162 | +const REFUSAL_MESSAGE = '`object-calendar` has no record source: declare one of `data`, `staticData` or `objectName`'; |
| 163 | + |
| 164 | +function withType(type: string, name: DocumentName): Record<string, unknown> { |
| 165 | + return { type, ...DOCUMENTS[name] }; |
| 166 | +} |
| 167 | + |
| 168 | +/** Report the issues rather than `false`, so a red run says what broke. */ |
| 169 | +function reasons(schema: unknown): string[] { |
| 170 | + const r = safeValidateSchema(schema); |
| 171 | + return r.success ? [] : r.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`); |
| 172 | +} |
| 173 | + |
| 174 | +describe('objectui#7313 — the four documents, through the member and the published entry point', () => { |
| 175 | + it('`staticData` alone validates — the route the plugin page documents twice', () => { |
| 176 | + const doc = withType('object-calendar', 'staticOnly'); |
| 177 | + expect('objectName' in doc).toBe(false); |
| 178 | + expect(ObjectCalendarSchema.safeParse(doc).success).toBe(true); |
| 179 | + expect(reasons(doc)).toEqual([]); |
| 180 | + }); |
| 181 | + |
| 182 | + it('`data` alone validates', () => { |
| 183 | + const doc = withType('object-calendar', 'dataOnly'); |
| 184 | + expect(ObjectCalendarSchema.safeParse(doc).success).toBe(true); |
| 185 | + expect(reasons(doc)).toEqual([]); |
| 186 | + }); |
| 187 | + |
| 188 | + it('`objectName` alone still validates — the accept set only WIDENED, an empty name included', () => { |
| 189 | + expect(ObjectCalendarSchema.safeParse(withType('object-calendar', 'objectOnly')).success).toBe(true); |
| 190 | + expect(reasons(withType('object-calendar', 'objectOnly'))).toEqual([]); |
| 191 | + // Presence is `!== undefined`, not the renderer's truthiness: `objectName: |
| 192 | + // ''` validated before this card (a required `z.string()` accepts '') and |
| 193 | + // must still validate, or the change would narrow something. |
| 194 | + expect(ObjectCalendarSchema.safeParse({ type: 'object-calendar', objectName: '' }).success).toBe(true); |
| 195 | + }); |
| 196 | + |
| 197 | + it('NONE of the three is refused ON THE REFINEMENT — by name, not at `objectName`', () => { |
| 198 | + const result = ObjectCalendarSchema.safeParse(withType('object-calendar', 'none')); |
| 199 | + expect(result.success).toBe(false); |
| 200 | + if (result.success) return; |
| 201 | + // Exactly one issue, and it is the refinement's — not the `objectName` |
| 202 | + // key-level failure this document used to get, which would make this case |
| 203 | + // green for the wrong reason. |
| 204 | + expect(result.error.issues).toHaveLength(1); |
| 205 | + const issue = result.error.issues[0]; |
| 206 | + expect(issue.code).toBe('custom'); |
| 207 | + expect(issue.path).toEqual([]); |
| 208 | + expect((issue as { params?: { code?: string } }).params?.code).toBe('RECORD_SOURCE_REQUIRED'); |
| 209 | + expect(issue.message).toBe(REFUSAL_MESSAGE); |
| 210 | + }); |
| 211 | + |
| 212 | + it('…and the published entry point refuses it too, with the same message', () => { |
| 213 | + const r = safeValidateSchema({ type: 'object-calendar' }); |
| 214 | + expect(r.success).toBe(false); |
| 215 | + if (r.success) return; |
| 216 | + expect(r.error.issues.map((i) => i.message)).toContain(REFUSAL_MESSAGE); |
| 217 | + }); |
| 218 | +}); |
| 219 | + |
| 220 | +describe('objectui#7313 — parity with `ObjectGanttSchema`, verdict for verdict', () => { |
| 221 | + const verdicts = (member: { safeParse: (v: unknown) => { success: boolean } }, type: string) => |
| 222 | + DOCUMENT_NAMES.map((name) => member.safeParse(withType(type, name)).success); |
| 223 | + |
| 224 | + it('the two members agree on all four documents, and the vector is not vacuous', () => { |
| 225 | + const calendar = verdicts(ObjectCalendarSchema, 'object-calendar'); |
| 226 | + const gantt = verdicts(ObjectGanttSchema, 'object-gantt'); |
| 227 | + expect(calendar).toEqual(gantt); |
| 228 | + // Non-vacuity: a pair that accepted everything, or refused everything, |
| 229 | + // would "agree" too. The vector must carry BOTH verdicts, and in the |
| 230 | + // positions the card's table names. |
| 231 | + expect(new Set(calendar).size).toBe(2); |
| 232 | + expect(calendar).toEqual([true, true, false, true]); |
| 233 | + }); |
| 234 | + |
| 235 | + it('the refusal is the same issue on both members, differing only in the member name', () => { |
| 236 | + const c = ObjectCalendarSchema.safeParse({ type: 'object-calendar' }); |
| 237 | + const g = ObjectGanttSchema.safeParse({ type: 'object-gantt' }); |
| 238 | + expect(c.success).toBe(false); |
| 239 | + expect(g.success).toBe(false); |
| 240 | + if (c.success || g.success) return; |
| 241 | + const strip = (m: string) => m.replace(/`object-(calendar|gantt)`/, '`object-MEMBER`'); |
| 242 | + expect(strip(c.error.issues[0].message)).toBe(strip(g.error.issues[0].message)); |
| 243 | + expect((c.error.issues[0] as { params?: { code?: string } }).params?.code) |
| 244 | + .toBe((g.error.issues[0] as { params?: { code?: string } }).params?.code); |
| 245 | + }); |
| 246 | + |
| 247 | + it('control: `BaseSchema` accepts all four — the refusal above is the refinement\'s, not the base\'s', () => { |
| 248 | + // `BaseSchema` is `.passthrough()` with no record-source refinement, so it |
| 249 | + // takes every one of these documents. Only the member refuses `none`. |
| 250 | + for (const name of DOCUMENT_NAMES) { |
| 251 | + expect(BaseSchema.safeParse(withType('object-calendar', name)).success).toBe(true); |
| 252 | + } |
| 253 | + }); |
| 254 | +}); |
| 255 | + |
| 256 | +describe('objectui#7313 — `data` and `staticData` are DECLARED, not passthrough holes', () => { |
| 257 | + it('a wrong-typed `data` is refused AT the key; `objectName` is supplied so only `data` is under test', () => { |
| 258 | + const r = ObjectCalendarSchema.safeParse({ type: 'object-calendar', objectName: 'events', data: 'nope' }); |
| 259 | + expect(r.success).toBe(false); |
| 260 | + if (!r.success) expect(r.error.issues.map((i) => i.path[0])).toContain('data'); |
| 261 | + expect(ObjectCalendarSchema.safeParse({ type: 'object-calendar', objectName: 'events', data: { provider: 'object', object: 'events' } }).success).toBe(true); |
| 262 | + }); |
| 263 | + |
| 264 | + it('a wrong-typed `staticData` is refused AT the key', () => { |
| 265 | + const r = ObjectCalendarSchema.safeParse({ type: 'object-calendar', objectName: 'events', staticData: 'nope' }); |
| 266 | + expect(r.success).toBe(false); |
| 267 | + if (!r.success) expect(r.error.issues.map((i) => i.path[0])).toContain('staticData'); |
| 268 | + }); |
| 269 | + |
| 270 | + it('control: `BaseSchema` alone would have admitted both — delete either member and its refusal becomes this', () => { |
| 271 | + expect(BaseSchema.safeParse({ type: 'object-calendar', objectName: 'events', data: 'nope' }).success).toBe(true); |
| 272 | + expect(BaseSchema.safeParse({ type: 'object-calendar', objectName: 'events', staticData: 'nope' }).success).toBe(true); |
| 273 | + }); |
| 274 | + |
| 275 | + it('the object stayed an object: `.shape` is exposed, with the three keys in it and `objectName` optional', () => { |
| 276 | + // zod 4 attaches a refinement in place; had it wrapped the object, `.shape` |
| 277 | + // would be gone and the parity census in `zod-mirror-parity.test.ts` would |
| 278 | + // read the pair as vacuous. |
| 279 | + const shape = (ObjectCalendarSchema as unknown as { shape: Record<string, { safeParse: (v: unknown) => { success: boolean } }> }).shape; |
| 280 | + expect(Object.keys(shape)).toEqual(expect.arrayContaining(['objectName', 'data', 'staticData'])); |
| 281 | + expect(shape.objectName.safeParse(undefined).success).toBe(true); |
| 282 | + expect(shape.objectName.safeParse(5).success).toBe(false); |
| 283 | + }); |
| 284 | +}); |
| 285 | + |
| 286 | +describe('objectui#7313 — the declaration names a live read, in the declared order', () => { |
| 287 | + it('the renderer resolves its records through the shared ladder', () => { |
| 288 | + const src = readFileSync(join(REPO_ROOT, RENDERER), 'utf8'); |
| 289 | + expect(src, `${RENDERER} no longer calls resolveRecordSourceConfig(schema)`).toContain('resolveRecordSourceConfig(schema)'); |
| 290 | + }); |
| 291 | + |
| 292 | + it('the ladder reads `data`, then `staticData`, then `objectName` — the order the refinement rests on', () => { |
| 293 | + const src = readFileSync(join(REPO_ROOT, LADDER), 'utf8'); |
| 294 | + const body = src.slice(src.indexOf('export function resolveRecordSourceConfig')); |
| 295 | + const data = body.indexOf('if (schema.data)'); |
| 296 | + const staticData = body.indexOf('if (schema.staticData)'); |
| 297 | + const objectName = body.indexOf('if (schema.objectName)'); |
| 298 | + expect(data).toBeGreaterThan(-1); |
| 299 | + expect(staticData).toBeGreaterThan(data); |
| 300 | + expect(objectName).toBeGreaterThan(staticData); |
| 301 | + }); |
| 302 | + |
| 303 | + it('the two static-data examples on the plugin page carry the annotation (the card\'s completion signal)', () => { |
| 304 | + const page = readFileSync(join(REPO_ROOT, DOC_PAGE), 'utf8'); |
| 305 | + expect(page).toContain("const schema: ObjectCalendarSchema = {\n type: 'object-calendar',\n staticData: ["); |
| 306 | + expect(page).toContain("const valueProviderCalendar: ObjectCalendarSchema = {\n type: 'object-calendar',\n staticData: ["); |
| 307 | + // No bare `object-calendar` literal is left unannotated on the page. |
| 308 | + expect(page.match(/^const \w+ = \{\n\s+type: 'object-calendar'/gm)).toBeNull(); |
| 309 | + }); |
| 310 | +}); |
0 commit comments