fix(spec-parity): the fifteen Tier-2 spec values render instead of validating into nothing (#2942)

Every row below is the #2897 shape — validates at authoring time, renders
nothing (or a dead control), no test fails and no warning fires:

- UserFilters `element: 'toggle'`: `default: return null` deleted the ENTIRE
  filter bar for stored toggle configs. The existing-but-unreachable
  ToggleFilters branch is wired; authoring stays untypeable (ADR-0053) while
  stored metadata keeps rendering (spec ADR-0047 §3.4a).
- UserFilters `date-range` / `text`: dead "No options" popovers become a
  from/to date pair (emits >=/<= bounds) and a contains search input.
- useAnimation: preset/easing maps re-keyed to the spec's underscore
  vocabulary (+ rotate/flip via usePageTransition's classes); hyphen dialect
  and `scale-fade` stay accepted for stored configs. The
  `EASING_MAP[easing] || easing` fallthrough no longer emits invalid CSS.
- NotificationContext: displayType materialized (spec default toast, legacy
  `modal` presents as alert) and the unions now match NotificationTypeSchema
  / NotificationPositionSchema instead of claiming to.
- useNavigationOverlay: the spec `size` buckets resolve to viewport-clamped
  widths off app-shell too (explicit `width` still wins; `auto` stays
  host-derived).
- Both ThemeProviders: `mode: 'auto'` follows the OS instead of adding a
  dead `auto` class that locked the light theme; `system` kept as the
  pre-spec spelling.
- AdvancedChart: the single-value families (gauge/solid-gauge/metric/kpi/
  bullet) render the measure as a number, table/pivot name their owning
  component, unknown types are named — never the bar SHELL with null series
  marks that was indistinguishable from an empty dataset (reachable via
  ChartRenderer's `schema.chartType ?? spec.chartType` bypass).
- Export menus (ObjectGrid + ListView): undeliverable formats render
  disabled with a reason — picking PDF used to close the popover and
  download nothing; xlsx did the same without the server path.
- Timeline: the spec `scale` key is read at last (legacy `timeScale` kept);
  hour/quarter/year generate real gantt header buckets instead of a blank
  axis.
- Toaster: position (all six spec values) and `limit` reach sonner instead
  of being discarded by a bare `<SonnerToaster />`.
- useSpecGesture: the DECLARED `config.type` drives recognition —
  pan/drag/rotate/double_tap no longer collapse to tap; useGesture gains
  real double-tap (two taps, not one) and two-touch pinch/rotate deltas.
- ReportViewer: `aggregation: 'distinct'` computes a distinct count instead
  of a blank summary cell.
- FieldEditWidget: inline resolution goes through the form's alias table, so
  `json` gets the code editor, `tree` the lookup picker, and composite/
  record/repeater/video/audio/autonumber resolve to their documented
  exclusions; ObjectGrid's editability gate consults the same contract, so
  a `composite` cell is read-only instead of a value-corrupting text box.
- FilterBuilder: $startsWith/$endsWith/$null/$exists become authorable
  (startsWith/endsWith/isNull/isNotNull/exists/notExists) and round-trip
  through condToMongo/kvToCondition — every FieldOperatorsSchema token is
  now reachable from the UI.

Each fix lands with a spec-parity guard per the #2897 template; `fields`,
`mobile`, `plugin-charts` and `providers` gain the `@objectstack/spec`
devDependency that makes those guards possible (no second zod peer variant
materialized — verified in the lockfile).

Refs #2942, #2901

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

packages/app-shell/src/chrome/ThemeProvider.tsx

@@ -1,6 +1,8 @@
 import { createContext, useContext, useEffect, useState } from "react"
 
-type Theme = "dark" | "light" | "system"
+// `auto` is the spec's OS-following mode (ThemeModeSchema, ui/theme.zod.ts);
+// `system` is this provider's pre-spec spelling, kept for stored values.
+type Theme = "dark" | "light" | "auto" | "system"
 
 type ThemeProviderProps = {
   children: React.ReactNode
@@ -35,7 +37,10 @@ export function ThemeProvider({
 
     root.classList.remove("light", "dark")
 
-    if (theme === "system") {
+    // Branching on `system` alone sent the spec's `auto` into
+    // `classList.add('auto')` — a class no Tailwind variant matches, locking
+    // the light theme with the OS preference ignored (#2942).
+    if (theme === "auto" || theme === "system") {
       const systemTheme = window.matchMedia("(prefers-color-scheme: dark)")
         .matches
         ? "dark"

packages/components/src/__tests__/toaster-position-spec-parity.test.tsx

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+
+/**
+ * Toaster position ↔ spec vocabulary parity + behavior (#2942).
+ *
+ * The `toaster` block used to mount `<SonnerToaster />` bare with
+ * `inputs: []` — all six `NotificationPositionSchema` values (and `limit`)
+ * validated and were discarded.
+ */
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import React from 'react';
+import '@testing-library/jest-dom';
+import { NotificationPositionSchema } from '@objectstack/spec/ui';
+import { renderComponent } from './test-utils';
+import { TOASTER_POSITIONS } from '../renderers/feedback/toaster';
+
+// Sonner defers mounting its DOM container, so the behavior tests assert on
+// the props our registration hands it rather than sonner internals.
+vi.mock('../ui/sonner', () => ({
+  Toaster: (props: { position?: string; visibleToasts?: number }) => (
+    <div data-testid="sonner-mock" data-position={props.position} data-limit={props.visibleToasts} />
+  ),
+  toast: Object.assign(() => undefined, {
+    success: () => undefined,
+    error: () => undefined,
+    info: () => undefined,
+    warning: () => undefined,
+  }),
+}));
+
+beforeAll(async () => {
+  await import('../renderers');
+}, 30000);
+
+describe('toaster covers the spec notification-position vocabulary', () => {
+  const rawOptions = (NotificationPositionSchema as unknown as { options?: readonly string[] }).options;
+  const specNames: string[] = Array.isArray(rawOptions) ? [...rawOptions] : [];
+
+  it('reads a non-empty enum from the spec', () => {
+    expect(specNames, 'could not read NotificationPositionSchema.options from the spec').not.toEqual([]);
+  });
+
+  it('maps every spec position onto a sonner position', () => {
+    const unmapped = specNames.filter((name) => !(name in TOASTER_POSITIONS));
+    expect(unmapped, 'these validate and then the toaster discards them').toEqual([]);
+  });
+
+  it('maps only spec positions and the ToasterSchema hyphen dialect', () => {
+    const sonnerIds = new Set(Object.values(TOASTER_POSITIONS));
+    const extra = Object.keys(TOASTER_POSITIONS).filter(
+      (name) => !specNames.includes(name) && !sonnerIds.has(name as never),
+    );
+    expect(extra, 'unexpected renderer-local position dialect').toEqual([]);
+  });
+});
+
+describe('toaster behavior', () => {
+  it('a spec underscore position (and limit) reaches sonner translated', () => {
+    const { getByTestId } = renderComponent({ type: 'toaster', position: 'top_center', limit: 3 } as any);
+    const toaster = getByTestId('sonner-mock');
+    expect(toaster).toHaveAttribute('data-position', 'top-center');
+    expect(toaster).toHaveAttribute('data-limit', '3');
+  });
+
+  it('the hyphen dialect keeps working', () => {
+    const { getByTestId } = renderComponent({ type: 'toaster', position: 'bottom-left' } as any);
+    expect(getByTestId('sonner-mock')).toHaveAttribute('data-position', 'bottom-left');
+  });
+});

packages/components/src/custom/filter-builder.tsx

@@ -71,6 +71,16 @@ const defaultOperators = [
   { value: "between", label: "Between" },
   { value: "in", label: "In" },
   { value: "notIn", label: "Not in" },
+  // String-specific spec operators ($startsWith / $endsWith) — they validated
+  // at the data layer but were unreachable from this dropdown (#2942).
+  { value: "startsWith", label: "Starts with" },
+  { value: "endsWith", label: "Ends with" },
+  // Null / existence spec operators ($null / $exists). Distinct from
+  // isEmpty/isNotEmpty, which also treat '' as empty.
+  { value: "isNull", label: "Is null" },
+  { value: "isNotNull", label: "Is not null" },
+  { value: "exists", label: "Is set" },
+  { value: "notExists", label: "Is not set" },
 ] as const
 
 /**
@@ -121,16 +131,23 @@ const useSafeFilterTranslation = createSafeTranslation(
     'filterBuilder.operators.between': 'Between',
     'filterBuilder.operators.in': 'In',
     'filterBuilder.operators.notIn': 'Not in',
+    'filterBuilder.operators.startsWith': 'Starts with',
+    'filterBuilder.operators.endsWith': 'Ends with',
+    'filterBuilder.operators.isNull': 'Is null',
+    'filterBuilder.operators.isNotNull': 'Is not null',
+    'filterBuilder.operators.exists': 'Is set',
+    'filterBuilder.operators.notExists': 'Is not set',
   },
   'filterBuilder.where',
 )
 
-const textOperators = ["equals", "notEquals", "contains", "notContains", "isEmpty", "isNotEmpty"]
-const numberOperators = ["equals", "notEquals", "greaterThan", "lessThan", "greaterOrEqual", "lessOrEqual", "isEmpty", "isNotEmpty"]
+const NULLNESS_OPERATORS = ["isNull", "isNotNull", "exists", "notExists"]
+const textOperators = ["equals", "notEquals", "contains", "notContains", "startsWith", "endsWith", "isEmpty", "isNotEmpty", ...NULLNESS_OPERATORS]
+const numberOperators = ["equals", "notEquals", "greaterThan", "lessThan", "greaterOrEqual", "lessOrEqual", "isEmpty", "isNotEmpty", ...NULLNESS_OPERATORS]
 const booleanOperators = ["equals", "notEquals"]
-const dateOperators = ["equals", "notEquals", "before", "after", "between", "isEmpty", "isNotEmpty"]
-const selectOperators = ["equals", "notEquals", "in", "notIn", "isEmpty", "isNotEmpty"]
-const lookupOperators = ["equals", "notEquals", "in", "notIn", "isEmpty", "isNotEmpty"]
+const dateOperators = ["equals", "notEquals", "before", "after", "between", "isEmpty", "isNotEmpty", ...NULLNESS_OPERATORS]
+const selectOperators = ["equals", "notEquals", "in", "notIn", "isEmpty", "isNotEmpty", ...NULLNESS_OPERATORS]
+const lookupOperators = ["equals", "notEquals", "in", "notIn", "isEmpty", "isNotEmpty", ...NULLNESS_OPERATORS]
 
 /** Field types that share the same operator/input behavior as number (numeric comparison operators, number input) */
 const numberLikeTypes = ["number", "currency", "percent", "rating"]
@@ -256,7 +273,7 @@ function FilterBuilder({
   }
 
   const needsValueInput = (operator: string) => {
-    return !["isEmpty", "isNotEmpty"].includes(operator)
+    return !["isEmpty", "isNotEmpty", "isNull", "isNotNull", "exists", "notExists"].includes(operator)
   }
 
   const getInputType = (fieldValue: string) => {

packages/components/src/renderers/feedback/toaster.tsx

@@ -10,14 +10,58 @@ import { ComponentRegistry } from '@object-ui/core';
 import type { ToasterSchema } from '@object-ui/types';
 import { Toaster as SonnerToaster } from '../../ui/sonner';
 
-ComponentRegistry.register('toaster', 
-  () => {
-    return <SonnerToaster />;
+/**
+ * Spec `NotificationPositionSchema` (`ui/notification.zod.ts`, underscore
+ * spellings) → sonner's hyphenated position ids. The hyphen spellings are
+ * `ToasterSchema`'s own dialect and map through as identities, so both
+ * registers work. Before #2942 the renderer mounted `<SonnerToaster />` bare
+ * (`inputs: []`) and every authored position — all six spec values — plus
+ * `limit` validated and changed nothing. Exported for the spec-parity test.
+ */
+export const TOASTER_POSITIONS: Record<
+  string,
+  'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
+> = {
+  top_left: 'top-left',
+  top_center: 'top-center',
+  top_right: 'top-right',
+  bottom_left: 'bottom-left',
+  bottom_center: 'bottom-center',
+  bottom_right: 'bottom-right',
+  // ToasterSchema's hyphen dialect — identity entries.
+  'top-left': 'top-left',
+  'top-center': 'top-center',
+  'top-right': 'top-right',
+  'bottom-left': 'bottom-left',
+  'bottom-center': 'bottom-center',
+  'bottom-right': 'bottom-right',
+};
+
+ComponentRegistry.register(
+  'toaster',
+  ({ schema }: { schema: ToasterSchema }) => {
+    const position = schema?.position ? TOASTER_POSITIONS[schema.position] : undefined;
+    const limit = typeof schema?.limit === 'number' && schema.limit > 0 ? schema.limit : undefined;
+    return (
+      <SonnerToaster
+        {...(position ? { position } : {})}
+        {...(limit ? { visibleToasts: limit } : {})}
+      />
+    );
   },
   {
     namespace: 'ui',
     label: 'Toaster',
-    inputs: [],
-    defaultProps: {}
-  }
+    inputs: [
+      {
+        name: 'position',
+        type: 'enum',
+        enum: ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'],
+        defaultValue: 'bottom-right',
+        label: 'Position',
+      },
+      { name: 'limit', type: 'number', label: 'Max visible toasts' },
+    ],
+    defaultProps: {},
+  },
 );

packages/core/src/index.ts

@@ -53,5 +53,6 @@ export * from './utils/chart-series.js';
 export * from './utils/dataset-format.js';
 export * from './utils/record-title.js';
 export * from './utils/export-filename.js';
+export * from './utils/export-formats.js';
 export * from './utils/reference-keys.js';
 export * from './utils/normalize-list-view.js';

packages/core/src/utils/__tests__/export-formats.test.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+
+/**
+ * Export format ↔ spec vocabulary parity + deliverability (#2942).
+ *
+ * `ListViewSchema.exportOptions` accepts csv/xlsx/pdf/json; the export menus
+ * offered every authored format and then silently no-opped on the ones no
+ * path can produce — picking PDF closed the popover and downloaded nothing,
+ * and XLSX did the same whenever the server path was unavailable. The menus
+ * now consult `isExportFormatDeliverable` and render dead formats disabled.
+ */
+import { describe, it, expect } from 'vitest';
+import { ListViewSchema } from '@objectstack/spec/ui';
+import { EXPORT_FORMATS, isExportFormatDeliverable } from '../export-formats';
+
+function specFormats(): string[] {
+  const field = (ListViewSchema as unknown as { shape?: Record<string, unknown> }).shape
+    ?.exportOptions as { def?: { innerType?: { element?: { options?: readonly string[] } } } } | undefined;
+  const options = field?.def?.innerType?.element?.options;
+  return Array.isArray(options) ? [...options] : [];
+}
+
+describe('export formats cover the spec vocabulary', () => {
+  const specNames = specFormats();
+
+  it('reads a non-empty enum from the spec', () => {
+    expect(specNames, 'could not read ListViewSchema.shape.exportOptions element options').not.toEqual([]);
+  });
+
+  it('declares exactly the spec formats', () => {
+    expect([...EXPORT_FORMATS].sort()).toEqual([...specNames].sort());
+  });
+
+  it('every spec format has an explicit deliverability decision', () => {
+    for (const format of specNames) {
+      // Both wiring states must produce a boolean — never an accidental
+      // fall-through that lets a dead option through to a silent no-op.
+      expect(typeof isExportFormatDeliverable(format, true)).toBe('boolean');
+      expect(typeof isExportFormatDeliverable(format, false)).toBe('boolean');
+    }
+  });
+});
+
+describe('deliverability per wiring', () => {
+  it('csv/json always deliver (client fallback)', () => {
+    expect(isExportFormatDeliverable('csv', false)).toBe(true);
+    expect(isExportFormatDeliverable('json', false)).toBe(true);
+  });
+
+  it('xlsx delivers only over the server path', () => {
+    expect(isExportFormatDeliverable('xlsx', true)).toBe(true);
+    expect(isExportFormatDeliverable('xlsx', false)).toBe(false);
+  });
+
+  it('pdf has no producer yet — never deliverable, never a silent no-op', () => {
+    expect(isExportFormatDeliverable('pdf', true)).toBe(false);
+    expect(isExportFormatDeliverable('pdf', false)).toBe(false);
+  });
+});

packages/core/src/utils/export-formats.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+
+/**
+ * The spec's export-format vocabulary (`ui/view.zod.ts` `exportOptions`).
+ * Exported for the spec-parity test.
+ */
+export const EXPORT_FORMATS: ReadonlySet<string> = new Set(['csv', 'xlsx', 'pdf', 'json']);
+
+/**
+ * Whether the current wiring can actually PRODUCE a file for one export
+ * format (#2942):
+ *
+ * - `csv` / `json` — always: the client fallback serializes them locally;
+ * - `xlsx` — only over the server streaming path (`dataSource.exportDownload`
+ *   with a real object binding): type-aware value formatting and permission
+ *   enforcement are server-side, and there is no client XLSX writer;
+ * - `pdf` — no producer exists on either path yet.
+ *
+ * The export menus used to offer every authored format unconditionally and
+ * then silently no-op: picking PDF closed the popover and downloaded
+ * nothing. The menus now render undeliverable formats disabled, so the
+ * authored option is visible but cannot dead-click.
+ */
+export function isExportFormatDeliverable(format: string, serverExportAvailable: boolean): boolean {
+  switch (format) {
+    case 'csv':
+    case 'json':
+      return true;
+    case 'xlsx':
+      return serverExportAvailable;
+    case 'pdf':
+    default:
+      return false;
+  }
+}

packages/fields/package.json

@@ -49,6 +49,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
+    "@objectstack/spec": "^17.0.0-rc.0",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "^6.0.4",

packages/fields/src/FieldEditWidget.test.ts

@@ -7,10 +7,12 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { FieldType } from '@objectstack/spec/data';
 import {
   FORM_FIELD_TYPES,
   INLINE_EXCLUDED_FIELD_TYPES,
   hasFieldEditWidget,
+  isInlineExcludedFieldType,
   mapFieldTypeToFormType,
 } from './index';
 
@@ -88,3 +90,44 @@ describe('inline editor ↔ form widget parity', () => {
     }
   });
 });
+
+/**
+ * #2942 — the guard above iterates FORM_FIELD_TYPES (the form widget-map
+ * keys), so a SPEC field type that reaches the form only through the alias
+ * table could sit in neither set and silently fall back to the grid's plain
+ * text input: `json`, `composite`, `record`, `repeater`, `tree`, `video`,
+ * `audio`, `autonumber` all did. This pins the contract at the spec boundary:
+ * every `FieldType` member must resolve (alias-aware) to an inline editor or
+ * a documented exclusion.
+ */
+describe('inline editor ↔ SPEC FieldType parity (#2942)', () => {
+  const specTypes: string[] = Array.isArray((FieldType as { options?: readonly string[] }).options)
+    ? [...(FieldType as { options: readonly string[] }).options]
+    : [];
+
+  it('reads a non-empty enum from the spec', () => {
+    expect(specTypes, 'could not read FieldType.options from the spec').not.toEqual([]);
+  });
+
+  it('every spec field type resolves to an inline decision (editor or exclusion)', () => {
+    const undecided = specTypes.filter(
+      (t) => !hasFieldEditWidget(t) && !isInlineExcludedFieldType(t),
+    );
+    // If this fails: a spec field type would fall back to a plain text input
+    // inline. Give it a widget (EDIT_WIDGETS / the alias table) or a
+    // documented exclusion (INLINE_EXCLUDED_FIELD_TYPES).
+    expect(undecided).toEqual([]);
+  });
+
+  it('the structured/computed spec spellings are closed corruption paths', () => {
+    // Excluded (alias-aware): editing these through a text box corrupts the value.
+    for (const t of ['composite', 'record', 'repeater', 'video', 'audio', 'autonumber']) {
+      expect(isInlineExcludedFieldType(t), `${t} must be excluded from inline editing`).toBe(true);
+      expect(hasFieldEditWidget(t), `${t} must not resolve to an editor`).toBe(false);
+    }
+    // Editable through their form widgets: json → code editor, tree → lookup picker.
+    for (const t of ['json', 'tree']) {
+      expect(hasFieldEditWidget(t), `${t} must resolve to its form widget`).toBe(true);
+    }
+  });
+});