|
| 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 | + |
| 9 | +/** |
| 10 | + * `@object-ui/mobile`'s `SpecResponsiveConfig` IS the schema's type (objectui#4598). |
| 11 | + * |
| 12 | + * The card: `useResponsiveConfig.ts` hand-declared an interface over the four |
| 13 | + * responsive keys, renamed off the schema's own symbol (`ResponsiveConfig` → |
| 14 | + * `SpecResponsiveConfig`), under a comment saying it mirrored |
| 15 | + * `ResponsiveConfigSchema`. Nothing tied the two together — no import, no |
| 16 | + * `z.infer`, no compile-time reference of any kind. It AGREED key-for-key when |
| 17 | + * it was filed, which is the whole point: the agreement was maintained by |
| 18 | + * nobody and checked by nothing, and the comment already told the next session |
| 19 | + * the copy was canonical. `ViewNavigationConfig` (objectui#4588) read exactly |
| 20 | + * like that until it had drifted on `mode`. |
| 21 | + * |
| 22 | + * The fix re-exports the type from `@object-ui/types` — this package's only |
| 23 | + * runtime dependency, which publishes it imported straight from |
| 24 | + * `@objectstack/spec/ui` — so no new dependency edge was needed and the |
| 25 | + * published name did not move. |
| 26 | + * |
| 27 | + * ── Why this file exists, given the fix is a re-export ────────────────────── |
| 28 | + * |
| 29 | + * `scripts/check-spec-symbol-derivation.mjs` stops reporting the declaration |
| 30 | + * because after the fix there is no declaration: rule 2 collects type aliases, |
| 31 | + * interfaces, enums and variables, and a bare `export type { … }` is none of |
| 32 | + * those. That is the right outcome — the hand copy is gone — but the gate got |
| 33 | + * there by seeing nothing, not by following the chain. It cannot: the binding |
| 34 | + * now runs mobile → `@object-ui/types` → `@objectstack/spec/ui`, and the gate |
| 35 | + * reads one package at a time. |
| 36 | + * |
| 37 | + * So the middle link is the part no gate covers, and it is the only place this |
| 38 | + * fix can still rot: if `@object-ui/types` ever replaces its re-export with a |
| 39 | + * hand copy of its own, mobile inherits the copy silently and every check in |
| 40 | + * the repo stays green. The assertions below are written against |
| 41 | + * `@objectstack/spec/ui` DIRECTLY for that reason — pinning against |
| 42 | + * `@object-ui/types` would compare the import to itself and pass no matter what |
| 43 | + * either package did. |
| 44 | + * |
| 45 | + * The type-level half runs under `tsc -p tsconfig.test.json` (this package's |
| 46 | + * `type-check`), so a re-grown copy fails the build rather than waiting for a |
| 47 | + * reviewer. `@objectstack/spec` is a devDependency here — a test may import it; |
| 48 | + * the published `.d.ts` may not, which is why the source re-exports through |
| 49 | + * `@object-ui/types` instead of reaching for the spec directly. |
| 50 | + */ |
| 51 | + |
| 52 | +import { describe, it, expect } from 'vitest'; |
| 53 | +import { ResponsiveConfigSchema, type ResponsiveConfig } from '@objectstack/spec/ui'; |
| 54 | +import type { SpecResponsiveConfig } from '../index'; |
| 55 | + |
| 56 | +/* eslint-disable @typescript-eslint/no-unused-vars -- |
| 57 | + * The pins below are compile-time assertions: `tsc` is their only consumer and |
| 58 | + * they are erased before anything runs, so "unused" is what a passing one looks |
| 59 | + * like. The repo's `no-unused-vars` ignores `^_` for ARGUMENTS only, which is |
| 60 | + * why `packages/types`' equivalent file carries the same warnings; scoping the |
| 61 | + * exemption to this file keeps it from becoming a repo-wide hole. |
| 62 | + */ |
| 63 | + |
| 64 | +/* ── Type-level helpers ──────────────────────────────────────────────────── */ |
| 65 | + |
| 66 | +/** |
| 67 | + * Invariant equality. `extends` in one direction — or a `satisfies` check — |
| 68 | + * would accept a NARROWING, so a copy that quietly dropped `order` would still |
| 69 | + * pass. That is the exact drift this card is about, so the pin has to be |
| 70 | + * invariant to say anything at all. |
| 71 | + */ |
| 72 | +type Equal< A, B > = |
| 73 | + (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false; |
| 74 | +type Expect< T extends true > = T; |
| 75 | + |
| 76 | +/* ── The binding itself ──────────────────────────────────────────────────── */ |
| 77 | + |
| 78 | +/** |
| 79 | + * The whole card in one line: what `@object-ui/mobile` publishes under |
| 80 | + * `SpecResponsiveConfig` and what the schema declares are ONE type. Red on the |
| 81 | + * day any link in mobile → `@object-ui/types` → `@objectstack/spec/ui` is |
| 82 | + * replaced by a copy, however byte-identical it starts out. |
| 83 | + */ |
| 84 | +type _IsExactlyTheSchemaType = Expect< Equal< SpecResponsiveConfig, ResponsiveConfig > >; |
| 85 | + |
| 86 | +/** |
| 87 | + * The four keys `ResponsiveConfigSchema` declares. Adding one here to make a |
| 88 | + * local read compile is the defect rather than the fix: the key has to exist in |
| 89 | + * the schema first, or the platform refuses metadata that declares it. |
| 90 | + */ |
| 91 | +type SchemaDeclaredKeys = 'breakpoint' | 'hiddenOn' | 'columns' | 'order'; |
| 92 | + |
| 93 | +type _KeysAreExactlyTheSchemaFour = Expect< Equal< keyof SpecResponsiveConfig, SchemaDeclaredKeys > >; |
| 94 | + |
| 95 | +/** Every key is optional on the authoring side — none of the four is required. */ |
| 96 | +type _AllFourAreOptional = Expect< |
| 97 | + Equal< SpecResponsiveConfig, Partial< SpecResponsiveConfig > > |
| 98 | +>; |
| 99 | + |
| 100 | +/** |
| 101 | + * The breakpoint vocabulary is the schema's six, reached through the same |
| 102 | + * chain. `NonNullable` keeps this pointed at which names exist rather than at |
| 103 | + * the `| undefined` the optionality puts there on purpose. |
| 104 | + */ |
| 105 | +type _BreakpointVocabularyIsTheSchemaSix = Expect< |
| 106 | + Equal< |
| 107 | + NonNullable< SpecResponsiveConfig['breakpoint'] >, |
| 108 | + 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' |
| 109 | + > |
| 110 | +>; |
| 111 | + |
| 112 | +/* eslint-enable @typescript-eslint/no-unused-vars */ |
| 113 | + |
| 114 | +/* ── Runtime half ────────────────────────────────────────────────────────── */ |
| 115 | + |
| 116 | +// The type-level assertions above are erased before anything runs, so the |
| 117 | +// checks below re-ask the same questions of the schema VALUE. Without them this |
| 118 | +// file could keep compiling while the runtime contract moved underneath it. |
| 119 | +describe('SpecResponsiveConfig is the spec responsive config (objectui#4598)', () => { |
| 120 | + const schemaKeys = Object.keys(ResponsiveConfigSchema.shape).sort(); |
| 121 | + |
| 122 | + it('reads the four declared keys off the schema itself', () => { |
| 123 | + expect(schemaKeys, 'could not read ResponsiveConfigSchema.shape').toEqual( |
| 124 | + ['breakpoint', 'columns', 'hiddenOn', 'order'], |
| 125 | + ); |
| 126 | + }); |
| 127 | + |
| 128 | + it('accepts a fully-populated config, and the schema agrees', () => { |
| 129 | + const full: SpecResponsiveConfig = { |
| 130 | + breakpoint: 'md', |
| 131 | + hiddenOn: ['xs', 'sm'], |
| 132 | + columns: { xs: 12, sm: 6, lg: 4 }, |
| 133 | + order: { xs: 2, lg: 1 }, |
| 134 | + }; |
| 135 | + |
| 136 | + expect(Object.keys(full).sort()).toEqual(schemaKeys); |
| 137 | + expect(ResponsiveConfigSchema.parse(full)).toEqual(full); |
| 138 | + }); |
| 139 | + |
| 140 | + it('accepts the empty config — every key is optional', () => { |
| 141 | + const empty: SpecResponsiveConfig = {}; |
| 142 | + expect(ResponsiveConfigSchema.parse(empty)).toEqual({}); |
| 143 | + }); |
| 144 | + |
| 145 | + it('carries `2xl`, the breakpoint a five-name copy would be missing', () => { |
| 146 | + const widest: SpecResponsiveConfig = { breakpoint: '2xl', columns: { '2xl': 3 } }; |
| 147 | + expect(ResponsiveConfigSchema.parse(widest)).toEqual(widest); |
| 148 | + }); |
| 149 | + |
| 150 | + it('refuses a breakpoint outside the schema enum', () => { |
| 151 | + const bad: SpecResponsiveConfig = { |
| 152 | + // @ts-expect-error 'xxl' is not one of the six declared breakpoint names |
| 153 | + breakpoint: 'xxl', |
| 154 | + }; |
| 155 | + expect(() => ResponsiveConfigSchema.parse(bad)).toThrow(); |
| 156 | + }); |
| 157 | + |
| 158 | + it('refuses a key the schema does not declare', () => { |
| 159 | + const bad: SpecResponsiveConfig = { |
| 160 | + breakpoint: 'lg', |
| 161 | + // @ts-expect-error `visibleOn` is not a declared responsive key |
| 162 | + visibleOn: ['xs'], |
| 163 | + }; |
| 164 | + // The schema is strict, so the undeclared key is a runtime rejection too — |
| 165 | + // the type and the schema refuse the same authored metadata. |
| 166 | + expect(() => ResponsiveConfigSchema.parse(bad)).toThrow(); |
| 167 | + }); |
| 168 | +}); |
0 commit comments