feat(spec): export the object-level refinement checks the mirrored UI schemas run (#16489) (#16697)

* feat(spec): export the object-level refinement checks the mirrored UI schemas run

Every spec object that carries an object-level refinement and is mirrored
downstream by a .shape derivation now exports its check as a named, typed
function from the same module, one per refinement: checkListViewPageMount and
checkListViewCalendarVisualization (ListViewSchema), checkPageSourceCompleteness
(PageSchema, extracted from the inline superRefine), and
checkGlobalFilterDateDefaultValue (GlobalFilterSchema, extracted likewise).
Every schema attaches the export by identifier, so no accept set moves.

object-refinement-check-exports.test.ts pins, per export: parity over every
failure path between the direct call, the schema's own check object and the
schema's parse; check count + bijection; attachment by identifier; barrel
identity.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F8SRGcf2eKTK7RRpWCGxwf

* test(spec): count refinement attachments in code only; regenerate api-surface + export-origins for the four exports

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F8SRGcf2eKTK7RRpWCGxwf

* test(spec): count refinement attachments by code line, no private comment stripper

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F8SRGcf2eKTK7RRpWCGxwf

---------

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

Author: os-trump

.changeset/spec-export-object-refinement-checks.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): export the object-level refinement checks the mirrored UI schemas run — `checkListViewPageMount`, `checkListViewCalendarVisualization`, `checkPageSourceCompleteness`, `checkGlobalFilterDateDefaultValue` (#16489, the spec half of objectui#7715)
+
+objectui derives its zod schemas from the spec's `.shape` (`specFieldsExcept(SpecListViewSchema.shape, …)`, six sites at the pinned build). That carries the spec's FIELDS by reference and drops every check attached to the spec OBJECT (`superRefine` / `refine`), so at 17.3.0 objectui's authoring door accepted `appearance.allowedVisualizations: ['calendar']` with no `calendar:` block while the spec's publish door refused it. Contract-first: the rule is written once, in the spec, and a mirror attaches that same rule instead of re-implementing it.
+
+Every spec object that carries an object-level refinement and is mirrored downstream now exports its check as a named, typed function (`(value, ctx: z.RefinementCtx) => void`) from `@objectstack/spec/ui`, alongside the schema — one function per refinement, no bundled "all checks" blob, so a mirror attaches exactly the ones whose fields it carries:
+
+| Schema | Export | Refuses |
+|:--|:--|:--|
+| `ListViewSchema` | `checkListViewPageMount` | `type: 'page'` with no `pageName`; `pageName` on a view that is not `type: 'page'`; a page mount declaring `columns` |
+| `ListViewSchema` | `checkListViewCalendarVisualization` | `'calendar'` in `appearance.allowedVisualizations` with no `calendar:` block |
+| `PageSchema` | `checkPageSourceCompleteness` | an `html` / `react` / `jsx` page with no non-empty `source` |
+| `GlobalFilterSchema` | `checkGlobalFilterDateDefaultValue` | a `type: 'date'` filter whose `defaultValue` is neither a preset name, an ISO date, nor a date-macro token |
+
+The population is measured from the schemas themselves (`_zod.def.checks`) against the six objectui derivation sites: `ListViewSchema` (2 checks), `PageSchema` (1) and `GlobalFilterSchema` (1 — mirrored by a `.shape` spread rather than `specFieldsExcept`) carry object-level refinements; `NavigationAreaSchema`, `AppSchema`, `DashboardWidgetSchema` and `DashboardSchema` carry none, so nothing is exported for them. The two `ListViewSchema` checks were already named module-private functions and are now exported; the `PageSchema` and `GlobalFilterSchema` checks were inline `superRefine` bodies, extracted verbatim into named functions the schema now attaches by identifier.
+
+Additive, and the schemas are unchanged: every schema attaches the very function it exports, so no accept set moves — every ListView, Page and GlobalFilter document that parsed before parses identically, with identical issues. `minor` because four new symbols land in the published `dist/*.d.ts`. Each export is pinned to be the check its schema runs (`object-refinement-check-exports.test.ts`: parity over every failure path between the direct call, the schema's own check object and the schema's parse; the schema carries exactly as many checks as are exported for it; the module attaches each by identifier). Attaching them at the derivation sites is the objectui half, objectui#7715.

packages/spec/api-surface/ui.json

@@ -429,6 +429,10 @@
     "chartAggregateCategoryKey (function)",
     "chartAggregateResultKeys (function)",
     "chartAggregateValueKey (function)",
+    "checkGlobalFilterDateDefaultValue (function)",
+    "checkListViewCalendarVisualization (function)",
+    "checkListViewPageMount (function)",
+    "checkPageSourceCompleteness (function)",
     "columnSummaryAlias (function)",
     "compileListViewGroupQuery (function)",
     "compileListViewGroupRowsQuery (function)",

packages/spec/export-origins/ui.json

@@ -415,6 +415,10 @@
     "chartAggregateCategoryKey": "src/ui/chart-aggregate.ts#chartAggregateCategoryKey (function)",
     "chartAggregateResultKeys": "src/ui/chart-aggregate.ts#chartAggregateResultKeys (function)",
     "chartAggregateValueKey": "src/ui/chart-aggregate.ts#chartAggregateValueKey (function)",
+    "checkGlobalFilterDateDefaultValue": "src/ui/dashboard.zod.ts#checkGlobalFilterDateDefaultValue (function)",
+    "checkListViewCalendarVisualization": "src/ui/view.zod.ts#checkListViewCalendarVisualization (function)",
+    "checkListViewPageMount": "src/ui/view.zod.ts#checkListViewPageMount (function)",
+    "checkPageSourceCompleteness": "src/ui/page.zod.ts#checkPageSourceCompleteness (function)",
     "columnSummaryAlias": "src/ui/view-grouping-query.ts#columnSummaryAlias (function)",
     "compileListViewGroupQuery": "src/ui/view-grouping-query.ts#compileListViewGroupQuery (function)",
     "compileListViewGroupRowsQuery": "src/ui/view-grouping-query.ts#compileListViewGroupRowsQuery (function)",

packages/spec/src/ui/dashboard.zod.ts

@@ -698,6 +698,63 @@ function isDateMacroPlaceholder(value: string): boolean {
   return !!m && isDateMacroToken(m[1]);
 }
 
+/**
+ * [#4614] The `type: 'date'` ⇄ `defaultValue` vocabulary check attached to
+ * {@link GlobalFilterSchema} — a date filter's default is checked against the
+ * vocabulary that can actually resolve it.
+ *
+ * Why this filter type and not the built-in `dateRange`: `dateRange`'s
+ * `defaultRange` has always been an enum, so a typo there was already an
+ * author-time error. A `globalFilters` entry of `type: 'date'` was the
+ * asymmetric half — `defaultValue` is `string | number | boolean`, so a bare
+ * preset name is the ONLY spelling available, and nothing checked it. An
+ * unknown name then failed SILENTLY and late: the renderer cannot lift it to a
+ * range, falls through to "a bare string date means equality on that day", and
+ * emits `created_at = 'last_7_dayz'` — a condition no row matches, which the
+ * backend answers `200 OK` with a zero. Every tile reads 0 and the filter bar
+ * shows "All time", so the dashboard looks deliberately empty rather than
+ * misconfigured. That is the failure this moves to parse time.
+ *
+ * Exported (#16489, the spec half of objectui#7715) so a downstream mirror
+ * that spreads `GlobalFilterSchema.shape` — which carries the FIELDS by
+ * reference and drops every object-level check — can re-attach exactly this
+ * rule with `.superRefine(checkGlobalFilterDateDefaultValue)` instead of
+ * re-parsing through the spec schema or re-implementing it. One function per
+ * refinement, no bundle. `GlobalFilterSchema` attaches this same binding, so
+ * the export IS the check the schema runs — pinned in
+ * `object-refinement-check-exports.test.ts`.
+ */
+export function checkGlobalFilterDateDefaultValue(
+  filter: { type?: string; defaultValue?: unknown },
+  ctx: z.RefinementCtx,
+): void {
+  if (filter.type !== 'date' || filter.defaultValue === undefined) return;
+
+  const value = filter.defaultValue;
+  if (
+    typeof value === 'string' &&
+    ((DATE_RANGE_PRESETS as readonly string[]).includes(value) ||
+      isDateMacroPlaceholder(value) ||
+      ISO_DATE_RE.test(value))
+  ) {
+    return;
+  }
+
+  ctx.addIssue({
+    code: 'custom',
+    path: ['defaultValue'],
+    message:
+      `${JSON.stringify(value)} is not a value a \`type: 'date'\` filter can resolve. ` +
+      'Use one of three spellings: a preset name (' +
+      DATE_RANGE_PRESETS.join(', ') +
+      '); an ISO date such as `2026-01-15` or `2026-01-15T08:30:00Z`, meaning that ' +
+      'day exactly; or a date-macro token such as `{today}` or `{30_days_ago}` ' +
+      '(the full vocabulary is `DATE_MACRO_TOKENS` in `@objectstack/spec/data`). ' +
+      "`custom` is not among them — it is a `dateRange.defaultRange` sentinel that " +
+      'carries no bounds of its own.',
+  });
+}
+
 /**
  * Dynamic options binding for global filters.
  * Allows dropdown options to be fetched from an object at runtime.
@@ -791,47 +848,11 @@ export const GlobalFilterSchema = lazySchema(() => strictObject({
 
   /** Widget IDs to apply this filter to (when scope is widget) */
   targetWidgets: z.array(z.string()).optional().describe('Widget IDs to apply this filter to'),
-}).superRefine((filter, ctx) => {
-  // #4614 — a date filter's `defaultValue` is checked against the vocabulary
-  // that can actually resolve it.
-  //
-  // Why this filter type and not the built-in `dateRange`: `dateRange`'s
-  // `defaultRange` has always been an enum, so a typo there was already an
-  // author-time error. A `globalFilters` entry of `type: 'date'` was the
-  // asymmetric half — `defaultValue` is `string | number | boolean`, so a bare
-  // preset name is the ONLY spelling available, and nothing checked it. An
-  // unknown name then failed SILENTLY and late: the renderer cannot lift it to a
-  // range, falls through to "a bare string date means equality on that day", and
-  // emits `created_at = 'last_7_dayz'` — a condition no row matches, which the
-  // backend answers `200 OK` with a zero. Every tile reads 0 and the filter bar
-  // shows "All time", so the dashboard looks deliberately empty rather than
-  // misconfigured. That is the failure this moves to parse time.
-  if (filter.type !== 'date' || filter.defaultValue === undefined) return;
-
-  const value = filter.defaultValue;
-  if (
-    typeof value === 'string' &&
-    ((DATE_RANGE_PRESETS as readonly string[]).includes(value) ||
-      isDateMacroPlaceholder(value) ||
-      ISO_DATE_RE.test(value))
-  ) {
-    return;
-  }
-
-  ctx.addIssue({
-    code: 'custom',
-    path: ['defaultValue'],
-    message:
-      `${JSON.stringify(value)} is not a value a \`type: 'date'\` filter can resolve. ` +
-      'Use one of three spellings: a preset name (' +
-      DATE_RANGE_PRESETS.join(', ') +
-      '); an ISO date such as `2026-01-15` or `2026-01-15T08:30:00Z`, meaning that ' +
-      'day exactly; or a date-macro token such as `{today}` or `{30_days_ago}` ' +
-      '(the full vocabulary is `DATE_MACRO_TOKENS` in `@objectstack/spec/data`). ' +
-      "`custom` is not among them — it is a `dateRange.defaultRange` sentinel that " +
-      'carries no bounds of its own.',
-  });
-}));
+})
+  // #4614 — the date `defaultValue` vocabulary check. Attached by identifier,
+  // not inlined: the export is the rule a `.shape` mirror re-attaches (#16489),
+  // and it must be this binding, not a copy.
+  .superRefine(checkGlobalFilterDateDefaultValue));
 
 /**
  * Dashboard Schema