refactor(types): retire the hand-written @objectstack/spec/ui sub-schema mirrors (#2231 phase 2) (#2882)

The zod schemas headed "Mirrors @objectstack/spec/ui X" are now the spec's
schemas by reference, closing the double-maintenance / silent-divergence gap
the same way #2622 did for ListViewSchema:

- objectql.zod.ts: HttpMethodSchema, HttpRequestSchema, ViewDataSchema,
  SelectionConfigSchema, PaginationConfigSchema are direct re-exports;
  ListColumnSchema derives from the spec base + the two sanctioned local
  extensions (prefix, broadened summary incl. the { type, field } object
  form useColumnSummary supports).
- theme.zod.ts: ColorPalette/Typography/Spacing/BorderRadius/Shadow/
  Breakpoints/Animation/ZIndex/ThemeMode/ThemeLogo/ThemeDefinition all
  resolve to the spec's schemas.

Drift the mirrors had accumulated, now picked up from the spec:
ViewDataSchema gains the provider:'schema' variant; HttpRequest.method,
Selection.type and Pagination.pageSize apply spec defaults on parse;
ListColumn.summary accepts the full spec aggregation vocabulary but no
longer free strings; Animation.timing keys are the spec's snake_case
(what usePageTransition reads); ThemeDefinition gains the spec's
density/wcagContrast/rtl/touchTarget/keyboardNavigation and its mode
default follows the spec ('light').

A new drift-guard (spec-subschema-parity.test.ts) asserts reference
identity for every re-export — a faithful copy fails too: a copy is a fork.

Verified: types tsc 0 errors; types unit tests 14 files / 212 tests green;
consumer unit tests (app-shell view-schema, plugin-grid, plugin-list, core)
65 files / 1155 tests green; changed files lint-clean.

Closes nothing — #2231 stays open for the legacy-vocabulary migration and
the per-view-type config unification (kanban/calendar/gantt/gallery/
timeline), audited and documented in the PR.


Claude-Session: https://claude.ai/code/session_01V3EDGLKNvbcpDTLzyiAd3Q

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/unify-spec-subschemas.md

@@ -0,0 +1,32 @@
+---
+"@object-ui/types": patch
+---
+
+refactor(types): retire the hand-written @objectstack/spec/ui sub-schema mirrors (#2231 phase 2)
+
+The zod schemas that carried a "Mirrors @objectstack/spec/ui X" header are now the
+spec's schemas **by reference** instead of hand-maintained copies, closing the
+double-maintenance / silent-divergence gap the same way #2622 did for `ListViewSchema`:
+
+- `objectql.zod.ts` — `HttpMethodSchema`, `HttpRequestSchema`, `ViewDataSchema`,
+  `SelectionConfigSchema`, `PaginationConfigSchema` are direct re-exports.
+  `ListColumnSchema` derives from the spec base plus the two sanctioned
+  objectui-only extensions: `prefix` (ObjectGrid compound cells) and a broadened
+  `summary` (the spec `ColumnSummarySchema` enum ∪ the `{ type, field }` object
+  form `useColumnSummary` supports).
+- `theme.zod.ts` — `ColorPaletteSchema`, `TypographySchema`, `SpacingSchema`,
+  `BorderRadiusSchema`, `ShadowSchema`, `BreakpointsSchema`, `AnimationSchema`,
+  `ZIndexSchema`, `ThemeModeSchema`, `ThemeLogoSchema`, `ThemeDefinitionSchema`
+  all resolve to the spec's schemas.
+
+Validation deltas picked up from the spec (drift the mirrors had accumulated):
+`ViewDataSchema` gains the `provider: 'schema'` variant; `HttpRequestSchema.method`,
+`SelectionConfigSchema.type` and `PaginationConfigSchema.pageSize` now apply spec
+defaults on parse; `ListColumnSchema.summary` accepts the full spec aggregation
+vocabulary but no longer accepts arbitrary strings; `AnimationSchema.timing` keys are
+the spec's snake_case (`ease_in` — what the runtime reads) instead of the mirror's
+camelCase; `ThemeDefinitionSchema` gains `density`/`wcagContrast`/`rtl`/`touchTarget`/
+`keyboardNavigation` and its `mode` default follows the spec (`'light'`).
+
+A new drift-guard (`spec-subschema-parity.test.ts`) asserts reference identity for
+every re-export, so re-forking — including a faithful copy — fails CI.

packages/types/src/__tests__/spec-subschema-parity.test.ts

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+
+/**
+ * Sub-schema ↔ @objectstack/spec drift guard (issue #2231, phase 2).
+ *
+ * The former hand-written mirrors in `zod/objectql.zod.ts` and `zod/theme.zod.ts`
+ * are now the spec's schemas **by reference** — re-forking one (replacing the
+ * re-export with a local copy that can drift) is exactly the failure mode that
+ * produced the original ListViewSchema divergence. These tests pin:
+ *
+ *   1. Reference identity for every direct re-export. `toBe` — not structural
+ *      equality — so a "faithful copy" fails too: a copy is a fork.
+ *   2. The one *derived* schema (`ListColumnSchema`): every spec field flows in,
+ *      the local-extension set is exactly the sanctioned one, and the `summary`
+ *      broadening keeps the spec enum as its first (by-reference) union arm.
+ *
+ * When one of these fails, do NOT fork the schema back to make it green — the
+ * schema belongs upstream in `@objectstack/spec`. Extend locally via `.extend()`
+ * on the spec base (and sanction the field here) only for genuinely
+ * objectui-only renderer concerns. See #2231.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  HttpMethodSchema as SpecHttpMethodSchema,
+  HttpRequestSchema as SpecHttpRequestSchema,
+  ViewDataSchema as SpecViewDataSchema,
+  ListColumnSchema as SpecListColumnSchema,
+  ColumnSummarySchema as SpecColumnSummarySchema,
+  SelectionConfigSchema as SpecSelectionConfigSchema,
+  PaginationConfigSchema as SpecPaginationConfigSchema,
+  ColorPaletteSchema as SpecColorPaletteSchema,
+  TypographySchema as SpecTypographySchema,
+  SpacingSchema as SpecSpacingSchema,
+  BorderRadiusSchema as SpecBorderRadiusSchema,
+  ShadowSchema as SpecShadowSchema,
+  BreakpointsSchema as SpecBreakpointsSchema,
+  AnimationSchema as SpecAnimationSchema,
+  ZIndexSchema as SpecZIndexSchema,
+  ThemeModeSchema as SpecThemeModeSchema,
+  ThemeSchema as SpecThemeSchema,
+} from '@objectstack/spec/ui';
+import {
+  HttpMethodSchema,
+  HttpRequestSchema,
+  ViewDataSchema,
+  ListColumnSchema,
+  SelectionConfigSchema,
+  PaginationConfigSchema,
+} from '../zod/objectql.zod.js';
+import {
+  ColorPaletteSchema,
+  TypographySchema,
+  SpacingSchema,
+  BorderRadiusSchema,
+  ShadowSchema,
+  BreakpointsSchema,
+  AnimationSchema,
+  ZIndexSchema,
+  ThemeModeSchema,
+  ThemeLogoSchema,
+  ThemeDefinitionSchema,
+} from '../zod/theme.zod.js';
+
+describe('spec sub-schema re-exports are the spec objects (by reference)', () => {
+  const pairs: Array<[string, unknown, unknown]> = [
+    ['HttpMethodSchema', HttpMethodSchema, SpecHttpMethodSchema],
+    ['HttpRequestSchema', HttpRequestSchema, SpecHttpRequestSchema],
+    ['ViewDataSchema', ViewDataSchema, SpecViewDataSchema],
+    ['SelectionConfigSchema', SelectionConfigSchema, SpecSelectionConfigSchema],
+    ['PaginationConfigSchema', PaginationConfigSchema, SpecPaginationConfigSchema],
+    ['ColorPaletteSchema', ColorPaletteSchema, SpecColorPaletteSchema],
+    ['TypographySchema', TypographySchema, SpecTypographySchema],
+    ['SpacingSchema', SpacingSchema, SpecSpacingSchema],
+    ['BorderRadiusSchema', BorderRadiusSchema, SpecBorderRadiusSchema],
+    ['ShadowSchema', ShadowSchema, SpecShadowSchema],
+    ['BreakpointsSchema', BreakpointsSchema, SpecBreakpointsSchema],
+    ['AnimationSchema', AnimationSchema, SpecAnimationSchema],
+    ['ZIndexSchema', ZIndexSchema, SpecZIndexSchema],
+    ['ThemeModeSchema', ThemeModeSchema, SpecThemeModeSchema],
+    ['ThemeDefinitionSchema', ThemeDefinitionSchema, SpecThemeSchema],
+  ];
+
+  it.each(pairs.map(([name]) => [name] as const))('%s', (name) => {
+    const [, oui, spec] = pairs.find(([n]) => n === name)!;
+    expect(oui, `${name} must be the spec schema itself, not a copy`).toBe(spec);
+  });
+});
+
+describe('ThemeLogoSchema is the spec Theme logo shape (unwrapped by reference)', () => {
+  it('accepts and round-trips the spec logo keys', () => {
+    const logo = { light: '/l.svg', dark: '/d.svg', favicon: '/f.ico' };
+    expect(ThemeLogoSchema.parse(logo)).toEqual(logo);
+  });
+
+  it('has exactly the spec inline-logo key set', () => {
+    const specLogoShape = (SpecThemeSchema.shape.logo.unwrap() as { shape: Record<string, unknown> }).shape;
+    const ouiLogoShape = (ThemeLogoSchema as unknown as { shape: Record<string, unknown> }).shape;
+    expect(Object.keys(ouiLogoShape).sort()).toEqual(Object.keys(specLogoShape).sort());
+  });
+});
+
+describe('ListColumnSchema derives from the spec (extend, not fork)', () => {
+  const specShape = (SpecListColumnSchema as unknown as { shape: Record<string, unknown> }).shape;
+  const ouiShape = (ListColumnSchema as unknown as { shape: Record<string, unknown> }).shape;
+
+  /**
+   * objectui-only ListColumn fields — sanctioned local extensions. Each should be
+   * promoted into `@objectstack/spec` rather than grown here.
+   */
+  const SANCTIONED_LOCAL = new Set<string>([
+    // Airtable-style compound-cell prefix — read by ObjectGrid's cell renderer.
+    'prefix',
+  ]);
+  // `summary` is intentionally overridden (spec enum ∪ { type, field } object form
+  // supported by plugin-grid's useColumnSummary) — asserted separately below.
+  const OVERRIDDEN = new Set<string>(['summary']);
+
+  it('every spec field is present (spec fields flow in by reference)', () => {
+    const missing = Object.keys(specShape).filter((k) => !(k in ouiShape));
+    expect(missing, 'spec ListColumn fields missing from objectui — the derivation dropped them').toEqual([]);
+  });
+
+  it('spec fields are the spec schemas by reference (except sanctioned overrides)', () => {
+    for (const k of Object.keys(specShape)) {
+      if (OVERRIDDEN.has(k)) continue;
+      expect(ouiShape[k], `ListColumnSchema.${k} must flow in from the spec by reference`).toBe(specShape[k]);
+    }
+  });
+
+  it('objectui-only fields are exactly the sanctioned set', () => {
+    const localOnly = Object.keys(ouiShape).filter((k) => !(k in specShape));
+    expect(localOnly.sort()).toEqual([...SANCTIONED_LOCAL].sort());
+  });
+
+  it('summary keeps the spec enum as its by-reference base arm', () => {
+    // ZodOptional<ZodUnion<[SpecColumnSummarySchema, ZodObject]>>
+    const summary = ouiShape.summary as { unwrap(): { def: { options: unknown[] } } };
+    const arms = summary.unwrap().def.options;
+    expect(arms[0], 'summary union arm 0 must be the spec ColumnSummarySchema by reference').toBe(
+      SpecColumnSummarySchema,
+    );
+  });
+
+  it('summary accepts every spec aggregation and the renderer object form', () => {
+    for (const agg of ['none', 'count', 'count_unique', 'percent_filled', 'sum', 'avg', 'min', 'max']) {
+      expect(ListColumnSchema.shape.summary.safeParse(agg).success, `summary "${agg}"`).toBe(true);
+    }
+    expect(ListColumnSchema.shape.summary.safeParse({ type: 'sum', field: 'amount' }).success).toBe(true);
+    // The old mirror's free-string arm is gone — unknown aggregations fail loudly.
+    expect(ListColumnSchema.shape.summary.safeParse('median').success).toBe(false);
+  });
+});

packages/types/src/zod/README.md

@@ -25,6 +25,27 @@ is `z.infer<typeof ListViewSchema> & ListViewRuntimeProps`. A drift-guard test
 (`__tests__/list-view-spec-parity.test.ts`) fails if the spec grows a field objectui
 hasn't triaged. **Do not hand-add spec-owned fields here** — import them from the spec.
 
+### Spec sub-schemas are re-exported by reference (not mirrored) — #2231
+
+The schemas that used to be hand-written "mirrors" of `@objectstack/spec/ui` are now the
+spec's schemas **by reference**, so they cannot drift:
+
+- `objectql.zod.ts`: `HttpMethodSchema`, `HttpRequestSchema`, `ViewDataSchema`,
+  `SelectionConfigSchema`, `PaginationConfigSchema` are direct re-exports;
+  `ListColumnSchema` is the spec base plus two sanctioned objectui-only extensions
+  (`prefix`, and a broadened `summary` that also accepts the `{ type, field }` object
+  form the grid renderer supports).
+- `theme.zod.ts`: `ColorPaletteSchema`, `TypographySchema`, `SpacingSchema`,
+  `BorderRadiusSchema`, `ShadowSchema`, `BreakpointsSchema`, `AnimationSchema`,
+  `ZIndexSchema`, `ThemeModeSchema`, `ThemeLogoSchema`, `ThemeDefinitionSchema` all
+  resolve to the spec's schemas.
+
+A drift-guard test (`__tests__/spec-subschema-parity.test.ts`) asserts reference
+identity — a faithful copy fails it too, because a copy is a fork. **Do not re-fork
+these**: fix or extend the schema upstream in `@objectstack/spec`, or (for genuinely
+objectui-only renderer concerns) extend locally via `.extend()` on the spec base and
+sanction the field in the parity test.
+
 ## Installation
 
 The Zod schemas are included in the `@object-ui/types` package:

packages/types/src/zod/objectql.zod.ts

@@ -17,66 +17,54 @@
  */
 
 import { z } from 'zod';
-import { ListViewSchema as SpecListViewSchema } from '@objectstack/spec/ui';
+import {
+  ListViewSchema as SpecListViewSchema,
+  HttpMethodSchema as SpecHttpMethodSchema,
+  HttpRequestSchema as SpecHttpRequestSchema,
+  ViewDataSchema as SpecViewDataSchema,
+  ListColumnSchema as SpecListColumnSchema,
+  ColumnSummarySchema as SpecColumnSummarySchema,
+  SelectionConfigSchema as SpecSelectionConfigSchema,
+  PaginationConfigSchema as SpecPaginationConfigSchema,
+} from '@objectstack/spec/ui';
 import { BaseSchema } from './base.zod.js';
 
 /**
- * HTTP Method Schema
- * Mirrors @objectstack/spec/ui HttpMethodSchema.
+ * HTTP Method Schema — `@objectstack/spec/ui` schema re-exported by reference
+ * (issue #2231; formerly a hand-written mirror).
  */
-export const HttpMethodSchema = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+export const HttpMethodSchema = SpecHttpMethodSchema;
 
 /**
- * HTTP Request Schema
- * Mirrors @objectstack/spec/ui HttpRequestSchema.
+ * HTTP Request Schema — `@objectstack/spec/ui` schema re-exported by reference
+ * (issue #2231; formerly a hand-written mirror). Differences vs the old mirror:
+ * `body` is the spec's `z.unknown()` (a superset of the old record/string/FormData/
+ * Blob union) and `method` now defaults to `'GET'` on parse.
  */
-export const HttpRequestSchema = z.object({
-  url: z.string().describe('API endpoint URL'),
-  method: HttpMethodSchema.optional().describe('HTTP method'),
-  headers: z.record(z.string(), z.string()).optional().describe('Custom HTTP headers'),
-  params: z.record(z.string(), z.unknown()).optional().describe('Query parameters'),
-  body: z.union([z.record(z.string(), z.unknown()), z.string(), z.instanceof(FormData), z.instanceof(Blob)]).optional().describe('Request body'),
-});
+export const HttpRequestSchema = SpecHttpRequestSchema;
 
 /**
- * View Data Source Schema
- * Mirrors @objectstack/spec/ui ViewDataSchema.
+ * View Data Source Schema — `@objectstack/spec/ui` schema re-exported by reference
+ * (issue #2231; formerly a hand-written mirror that had drifted behind the spec's
+ * fourth `provider: 'schema'` variant for schema-bound forms).
  */
-export const ViewDataSchema = z.union([
-  z.object({
-    provider: z.literal('object'),
-    object: z.string().describe('Target object name'),
-  }),
-  z.object({
-    provider: z.literal('api'),
-    read: HttpRequestSchema.optional().describe('Read configuration'),
-    write: HttpRequestSchema.optional().describe('Write configuration'),
-  }),
-  z.object({
-    provider: z.literal('value'),
-    items: z.array(z.unknown()).describe('Static data array'),
-  }),
-]);
+export const ViewDataSchema = SpecViewDataSchema;
 
 /**
- * List Column Schema
- * Mirrors @objectstack/spec/ui ListColumnSchema.
+ * List Column Schema — derived from `@objectstack/spec/ui` `ListColumnSchema`
+ * (issue #2231): spec fields flow in by reference; objectui-only extensions are
+ * declared locally on top via `.extend()`.
+ *  - `summary` is broadened: the spec's `ColumnSummarySchema` enum plus the
+ *    `{ type, field }` object form the grid renderer supports (per-column field
+ *    override — see `useColumnSummary` in `@object-ui/plugin-grid`). The old
+ *    mirror's free-string arm is gone: unknown aggregation names now fail
+ *    validation instead of silently rendering nothing.
+ *  - `prefix` is objectui-only compound-cell rendering (read by `ObjectGrid`);
+ *    promote it into the spec rather than growing this extension.
  */
-export const ListColumnSchema = z.object({
-  field: z.string().describe('Field name'),
-  label: z.string().optional().describe('Display label'),
-  width: z.number().optional().describe('Column width'),
-  align: z.enum(['left', 'center', 'right']).optional().describe('Text alignment'),
-  hidden: z.boolean().optional().describe('Hide column by default'),
-  sortable: z.boolean().optional().describe('Allow sorting'),
-  resizable: z.boolean().optional().describe('Allow resizing'),
-  wrap: z.boolean().optional().describe('Allow text wrapping'),
-  type: z.string().optional().describe('Renderer type override'),
-  link: z.boolean().optional().describe('Functions as the primary navigation link (triggers View navigation)'),
-  action: z.string().optional().describe('Registered Action ID to execute when clicked'),
-  pinned: z.enum(['left', 'right']).optional().describe('Pin column to left or right edge'),
+export const ListColumnSchema = SpecListColumnSchema.extend({
   summary: z.union([
-    z.string(),
+    SpecColumnSummarySchema,
     z.object({
       type: z.enum(['count', 'sum', 'avg', 'min', 'max']).describe('Aggregation type'),
       field: z.string().optional().describe('Field to aggregate (defaults to column field)'),
@@ -89,21 +77,18 @@ export const ListColumnSchema = z.object({
 });
 
 /**
- * Selection Config Schema
- * Mirrors @objectstack/spec/ui SelectionConfigSchema.
+ * Selection Config Schema — `@objectstack/spec/ui` schema re-exported by reference
+ * (issue #2231; formerly a hand-written mirror). `type` now defaults to `'none'`
+ * on parse instead of staying undefined.
  */
-export const SelectionConfigSchema = z.object({
-  type: z.enum(['none', 'single', 'multiple']).optional().describe('Selection mode'),
-});
+export const SelectionConfigSchema = SpecSelectionConfigSchema;
 
 /**
- * Pagination Config Schema
- * Mirrors @objectstack/spec/ui PaginationConfigSchema.
+ * Pagination Config Schema — `@objectstack/spec/ui` schema re-exported by reference
+ * (issue #2231; formerly a hand-written mirror). `pageSize` is now the spec's
+ * positive-int with a default of 25 on parse.
  */
-export const PaginationConfigSchema = z.object({
-  pageSize: z.number().optional().describe('Page size'),
-  pageSizeOptions: z.array(z.number()).optional().describe('Page size options'),
-});
+export const PaginationConfigSchema = SpecPaginationConfigSchema;
 
 /**
  * Sort Config Schema