refactor(fields,layout,plugin-detail,plugin-grid,collaboration,plugin-charts,plugin-form,providers,runner,sdui-parser)!: burn ledger batch 7 — 14 symbols stop wearing spec names (#3224)

objectui#3161, objectstack#4115 ledger batch 7 — the long tail, one or two
entries per package. All ten packages leave the ledger (17 -> 3 collisions,
11 -> 1 packages; what remains is batch 8's @object-ui/types trio, untouched).

Verdicts, per SYMBOL rather than per cluster:

@object-ui/fields
  - isFileIdToken       -> re-export. The local copy was character-for-character
    identical to the spec's function while its comment claimed to "mirror" it,
    so every behaviour test passed against it and only reference identity could
    tell the two apart (objectui#3003, re-proved on isAggregatedViewContainer in
    objectui#3169). The regex is a wire decision: widen it server-side while a
    copy here keeps the old bound and every new id reads as "not a reference".
  - FieldWidgetProps    -> FieldWidgetComponentProps (spec's is the DECLARED
    widget-plugin props contract). The two disagree on the validation-message
    key — spec `error`, objectui `errorMessage` — filed as objectui#3222; the
    `[key: string]: any` that hid it is objectui#3221.

@object-ui/layout
  - PageHeaderProps -> PageHeaderComponentProps, the name app-shell already
    chose for the same split in objectui#3169, reused rather than re-invented.
  - Page            -> PageNodeRenderer. The spec's Page is the authored page
    DOCUMENT; this renders types' PageNodeSchema, the SDUI NODE that
    objectui#3074 had already renamed off PageSchema. Unregistered and `& any`:
    objectui#3223.

@object-ui/plugin-detail
  - FeedFilterMode  -> re-export (a hand copy of the spec enum, in a file that
    already imported FeedItemType from the same spec subpath).
  - ObjectFieldLike -> ObjectDefFieldLike. The spec's is the i18n duck type
    translateObject walks, and it ends in `[key: string]: any` — deriving would
    trade a precise three-key layout contract for a bag (objectstack#4075 from
    the spec's side).

@object-ui/plugin-grid
  - ColumnSummaryConfig -> ColumnSummarySetting, derived as
    NonNullable<ListColumn['summary']>. The spec owns that name for the OBJECT
    form ALONE, so the local declaration wore it for a strictly WIDER type: code
    written here accepted 'sum', the same name imported from the spec rejects
    it. The eleven-member union beside it is the spec's ColumnSummary enum now
    instead of a hand copy under a comment promising lockstep, which turns the
    total Record<ColumnSummaryType, string> label map into the thing that
    reports a divergence.
  - isMultiValueField -> hasMultiValueShape, delegating to the spec function it
    used to shadow. The two had different PRECONDITIONS (the spec's requires a
    def with a `type`; this one is called with `objectFields?.[name]`), which is
    worse than a plain fork: an import swapped between the modules keeps
    compiling and changes behaviour only on the missing-field path.

@object-ui/collaboration
  - RealtimeConfig -> RealtimeSubscriptionConfig (spec's is the app-level
    realtime declaration; this is one browser socket's dial settings). Zero
    shared declared keys — measured against the spec's own schema shape at
    runtime, because the spec declares that schema as a PASSTHROUGH object and a
    type-level key comparison against a bag answers nothing.

@object-ui/plugin-charts
  - ChartConfig -> ChartContainerConfig. The one collision in this batch that
    had already produced ambiguity in read code: AdvancedChartImpl declared
    `config?: ChartConfig` meaning the shadcn per-series style map, lines from
    comments reading "Spec `ChartConfig.yAxis`" meaning the authored document.

@object-ui/plugin-form
  - FormSection -> FormSectionContainer. Deliberately NOT batch 6's ListView
    exemption: ListViewProps.schema takes the spec-derived metadata as one prop,
    so that renderer restates nothing, while FormSectionContainerProps takes the
    same metadata FLATTENED into individual props — a rival vocabulary. `columns`
    stays `1|2|3|4` rather than binding the spec key, which accepts the string
    forms and normalises them in its own pipe; the pin fails if that changes.

@object-ui/providers
  - Theme -> ThemePreference, derived from the spec's ThemeMode input plus the
    legacy 'system' spelling. Neither of the two shapes the triage note
    predicted: it was Theme['mode'] wearing Theme's name, i.e. a string union
    standing where the spec has a whole document. ThemeMode, the spec's own name
    for it, is a spec export too — the objectui#3169 rule again.

@object-ui/runner
  - App -> RunnerApp (spec owns App for the authored application metadata AND
    the App.create() builder). A default export, so no consumer churn.

@object-ui/sdui-parser
  - ValidationResult -> ManifestValidationResult, per the
    <what was validated>Validation<Error|Result> convention registered on
    objectstack#4115; core took SchemaNodeValidationResult in batch 4.

Renames are by identifier boundary, per package, no global replace; not one
string literal changed (the `form-section` CSS class, component keys, error
names). Docs that named the renamed public types are updated with them
(content/docs, skills/objectui).

Verification: `--ledger` regenerated and set-diffed — removed is exactly these
14, added empty, @object-ui/types byte-identical. Guard green; turbo type-check
78/78 (full repo); full suite 834 files / 9746 tests passed, 0 failed; ESLint on
changed files 0 errors. plugin-detail/plugin-grid/plugin-form gained a
tsconfig.typetests.json chained off type-check (their test trees are still in
TEST_DEBT, so nothing would have compiled the new pins — objectui#3181);
collaboration gained a tsconfig.test.json with its first test file.

Five mutation directions, all red: re-forking isFileIdToken byte-for-byte
(guard by name+file, and the reference-identity assertion — while all 20+
behaviour assertions in file-value.test.ts stayed green); restoring the original
hand-written Theme (guard); re-forking the derived ColumnSummaryType with one
member dropped (the runtime spec-vocabulary test names the missing member, and
the typetests pin fails); leaving a burned name in DEBT (rotting ratchet);
unchaining a tsconfig.typetests.json (type-check coverage ratchet). A sixth
records a known hole: renaming ThemePreference back to `Theme` while KEEPING the
derivation passes the guard — derivation is derivation, batch 5's
ConflictResolutionStrategy trap — and is caught only by the tripwire test, which
is why every rename here has one.


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

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

Author: os-zhuang

.changeset/long-tail-spec-symbol-burn-down.md

@@ -0,0 +1,69 @@
+---
+"@object-ui/collaboration": major
+"@object-ui/fields": major
+"@object-ui/layout": major
+"@object-ui/plugin-charts": major
+"@object-ui/plugin-detail": major
+"@object-ui/plugin-form": major
+"@object-ui/plugin-grid": major
+"@object-ui/providers": major
+"@object-ui/runner": major
+"@object-ui/sdui-parser": major
+---
+
+Stop declaring 14 symbols across ten packages under names `@objectstack/spec`
+owns (objectui#3161, objectstack#4115 batch 7 — the long tail, one or two
+entries per package). All ten packages leave the ledger, which drops from 17
+collisions across 11 packages to 3 across 1.
+
+**Renamed exports** — in every case the spec exports the same name for a
+*different* thing, so the old name was a mis-description rather than a dialect:
+
+| package | was | now | what the spec's same-named export is |
+|:--|:--|:--|:--|
+| `@object-ui/fields` | `FieldWidgetProps` | `FieldWidgetComponentProps` | the DECLARED field-widget plugin props contract (a zod object; `field.type` is the `FieldType` enum, `readonly`/`required` carry defaults) |
+| `@object-ui/layout` | `PageHeaderProps` | `PageHeaderComponentProps` | the authored `page:header` node — a zod schema of `title`, `subtitle`, an icon NAME, `breadcrumb`, `actions: string[]` |
+| `@object-ui/layout` | `Page` | `PageNodeRenderer` | the authored page metadata DOCUMENT (`name`, `label`, `type`, `regions`) |
+| `@object-ui/plugin-detail` | `ObjectFieldLike` | `ObjectDefFieldLike` | the i18n duck type `translateObject` walks (`help`/`description`, plus `[key: string]: any`) |
+| `@object-ui/plugin-grid` | `ColumnSummaryConfig` | `ColumnSummarySetting` | the OBJECT form of `ListColumn.summary` **only** — the local one was the whole union, shorthand included |
+| `@object-ui/plugin-grid` | `isMultiValueField` | `hasMultiValueShape` | the spec's classifier, which requires a def with a `type`; the local one is called with `undefined` |
+| `@object-ui/collaboration` | `RealtimeConfig` | `RealtimeSubscriptionConfig` | the app's realtime DECLARATION (`enabled`, `transport`, `subscriptions[]`) |
+| `@object-ui/plugin-charts` | `ChartConfig` | `ChartContainerConfig` | the authored chart document (`type`, `xAxis`, `series`, `showLegend`, …) |
+| `@object-ui/plugin-form` | `FormSection` / `FormSectionProps` | `FormSectionContainer` / `FormSectionContainerProps` | the authored form-section metadata (`name`, `pane`, `visibleWhen`, `fields`) |
+| `@object-ui/providers` | `Theme` | `ThemePreference` | a whole theme DOCUMENT (`name`, `label`, `colors`, `typography`) |
+| `@object-ui/runner` | `App` (default export) | `RunnerApp` | the authored application metadata type **and** the `App.create()` builder |
+| `@object-ui/sdui-parser` | `ValidationResult` | `ManifestValidationResult` | plugin-manifest validation (`{ valid, errors?, warnings? }`), exported from both `kernel` and `contracts` |
+
+`ManifestValidationResult` follows the `<what was validated>Validation<Error|Result>`
+convention registered on objectstack#4115 (`@object-ui/core` took
+`SchemaNodeValidationResult` in batch 4). `PageHeaderComponentProps` deliberately
+reuses the name `@object-ui/app-shell` already chose for its own header props in
+batch 3, so one concept does not acquire two dialect names one package apart.
+
+**Now derived from the spec instead of hand-written:**
+
+- `@object-ui/fields` — `isFileIdToken` is re-exported from
+  `@objectstack/spec/data`. The local copy was character-for-character identical
+  to the spec's function while its comment said it "mirrors" it, so every
+  behaviour test passed and only reference identity could tell the two apart.
+  The regex is a wire decision: widening it server-side while a copy here kept
+  the old bound would make every new id read as "not a reference", and the
+  widget would submit the legacy inline blob to a backend expecting a reference.
+- `@object-ui/plugin-detail` — `FeedFilterMode` is re-exported from
+  `@objectstack/spec/data`, in a file that already imported the sibling
+  `FeedItemType` from the spec.
+- `@object-ui/plugin-grid` — the eleven-member aggregation union is now the
+  spec's `ColumnSummary` enum, so the total `Record<ColumnSummaryType, string>`
+  label map turns a member the spec adds into a compile error instead of a
+  blank footer cell. `ColumnSummarySetting` is `NonNullable<ListColumn['summary']>`,
+  i.e. whatever forms the spec itself accepts. `hasMultiValueShape` delegates to
+  the spec's `isMultiValueField` rather than re-deriving it from
+  `MULTI_OPTION_TYPES` / `MULTI_CAPABLE_TYPES`.
+- `@object-ui/providers` — `ThemePreference` is the spec's `ThemeMode` union
+  plus the one legacy `'system'` spelling this provider still honours for stored
+  preferences, read off the schema's own `_zod` carrier so the package takes no
+  zod dependency.
+
+`@objectstack/spec` moves from `devDependencies` to `dependencies` in
+`@object-ui/fields` (it re-exports a runtime function) and `@object-ui/providers`
+(its public `.d.ts` now references the spec).

content/docs/guide/plugin-development.md

@@ -176,11 +176,11 @@ Now any schema with `"type": "board"` will resolve to your component.
 
 ## Implementing a Custom Field Widget
 
-Field widgets follow the `FieldWidgetProps` interface from `@object-ui/fields`.
+Field widgets follow the `FieldWidgetComponentProps` interface from `@object-ui/fields`.
 
 ```typescript
-// FieldWidgetProps<T> shape (from packages/fields/src/widgets/types.ts)
-type FieldWidgetProps<T = any> = {
+// FieldWidgetComponentProps<T> shape (from packages/fields/src/widgets/types.ts)
+type FieldWidgetComponentProps<T = any> = {
   value: T;
   onChange: (val: T) => void;
   field: FieldMetadata;
@@ -197,7 +197,7 @@ type FieldWidgetProps<T = any> = {
 // src/ColorPickerField.tsx
 import React from 'react';
 import { Input } from '@object-ui/components';
-import type { FieldWidgetProps } from '@object-ui/fields';
+import type { FieldWidgetComponentProps } from '@object-ui/fields';
 
 export function ColorPickerField({
   value,
@@ -206,7 +206,7 @@ export function ColorPickerField({
   readonly,
   disabled,
   errorMessage,
-}: FieldWidgetProps<string>) {
+}: FieldWidgetComponentProps<string>) {
   if (readonly) {
     return (
       <div className="flex items-center gap-2">
@@ -435,4 +435,4 @@ import '@object-ui/plugin-board';
 - [Component Registry](./component-registry.md) — registry internals and advanced usage
 - [Plugins Overview](./plugins.md) — official plugin catalog
 - [Schema Rendering](./schema-rendering.md) — how schemas become UI
-- [Fields Guide](./fields.md) — built-in field widgets and `FieldWidgetProps`
+- [Fields Guide](./fields.md) — built-in field widgets and `FieldWidgetComponentProps`

content/docs/layout/page-header.mdx

@@ -25,7 +25,7 @@ import { PageHeader } from '@object-ui/layout';
 ## Component Props
 
 ```plaintext
-interface PageHeaderProps {
+interface PageHeaderComponentProps {
   title: string;                 // Page title (required)
   description?: string;          // Page description
   action?: React.ReactNode;      // Action buttons or elements

examples/byo-backend-console/src/App.tsx

@@ -179,7 +179,7 @@ function ObjectFormPage() {
 
 /**
  * Modal ObjectForm with explicit `sections` — exercises the Card-wrapped
- * `FormSection` path (formType: 'modal'/'split'/'tabbed'/'wizard' all share
+ * `FormSectionContainer` path (formType: 'modal'/'split'/'tabbed'/'wizard' all share
  * it), as opposed to `ObjectFormPage` above which renders the flat
  * divider-only path used by the default `formType: 'simple'` + `fieldGroups`.
  */

packages/app-shell/src/utils/paramToField.ts

@@ -44,7 +44,7 @@ export function resolveParamWidgetType(paramType: string): string {
 const LOOKUP_WIDGET_TYPES = new Set(['lookup', 'master_detail']);
 
 /**
- * Map an `ActionParamDef` to the field-metadata shape `FieldWidgetProps.field`
+ * Map an `ActionParamDef` to the field-metadata shape `FieldWidgetComponentProps.field`
  * expects. Lossless for the widget-relevant config: options, `multiple`,
  * upload `accept`/`maxSize`, and the full lookup picker config that
  * `resolveActionParams()` copies from the underlying object field.

packages/collaboration/package.json

@@ -30,7 +30,7 @@
     "build": "tsc",
     "clean": "rm -rf dist",
     "test": "vitest run",
-    "type-check": "tsc --noEmit",
+    "type-check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "lint": "eslint ."
   },
   "peerDependencies": {
@@ -40,6 +40,7 @@
     "@object-ui/types": "workspace:*"
   },
   "devDependencies": {
+    "@objectstack/spec": "^17.0.0-rc.1",
     "@types/react": "19.2.17",
     "react": "19.2.8",
     "typescript": "^6.0.3",

packages/collaboration/src/__tests__/spec-symbol-batch7.test.ts

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+
+/**
+ * `@object-ui/collaboration` ↔ `@objectstack/spec` symbol-collision guard
+ * (objectui#3161, objectstack#4115 ledger batch 7).
+ *
+ * `RealtimeConfig` → `RealtimeSubscriptionConfig`. Batch 6's first method rule
+ * — read the collision per SYMBOL, never per cluster — applies here in its
+ * "looks like a dialect, is actually a different concept" direction, the same
+ * verdict `SecurityPolicy` got: the spec's `RealtimeConfig` is the app's
+ * realtime DECLARATION (`enabled`, one `transport`, a list of `subscriptions`
+ * naming record events), and this is one browser socket's dial settings. The
+ * `Extract<…> = never` pin below is what makes "they share nothing" a checked
+ * fact rather than a claim in a comment — and it is also the tripwire: if the
+ * spec grows a `url` or a `channel` at top level, the two concepts have started
+ * to converge and this symbol needs re-triage.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { RealtimeConfigSchema } from '@objectstack/spec/api';
+import type { RealtimeConfig as SpecRealtimeConfig } from '@objectstack/spec/api';
+
+import type { RealtimeSubscriptionConfig } from '../useRealtimeSubscription';
+
+type Assert<T extends true> = T;
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type Extends<A, B> = [A] extends [B] ? true : false;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type HasKey<T, K extends string> = K extends keyof T ? true : false;
+
+/**
+ * Every key of the local config, exhaustively — `Record<keyof …, true>` makes
+ * tsc reject both a missing key and an invented one, so this list cannot drift
+ * out of step with the interface the way a hand-written array would.
+ */
+const LOCAL_KEYS: Record<keyof RealtimeSubscriptionConfig, true> = {
+  url: true,
+  channel: true,
+  autoReconnect: true,
+  reconnectInterval: true,
+  maxReconnectAttempts: true,
+  authToken: true,
+};
+
+const specDeclaredKeys = Object.keys(
+  (RealtimeConfigSchema as unknown as { shape?: Record<string, unknown> }).shape ?? {},
+);
+
+describe('the two configs describe different things', () => {
+  it('reads the spec schema shape (the probe itself is not vacuous)', () => {
+    expect(specDeclaredKeys.length).toBeGreaterThan(0);
+  });
+
+  it('shares not one declared key with the spec declaration', () => {
+    // Read off the spec's own schema rather than restated here — the disjoint
+    // key sets ARE the argument for the rename, so they have to be measured.
+    for (const key of Object.keys(LOCAL_KEYS)) {
+      expect(
+        specDeclaredKeys,
+        `the spec's RealtimeConfig now declares '${key}' too — the two concepts are converging, ` +
+          `re-triage this symbol instead of leaving the rename standing on a stale reason`,
+      ).not.toContain(key);
+    }
+  });
+});
+
+describe('RealtimeSubscriptionConfig is not a dialect of the spec RealtimeConfig', () => {
+  it('is pinned at compile time', () => {
+    // Load-bearing import: if the spec retires `RealtimeConfig`, this file
+    // stops compiling and the local name is free to come back.
+    type _SpecIsReal = Assert<Equal<IsAny<SpecRealtimeConfig>, false>>;
+
+    // NOTE — why the key comparison above is a runtime one. The spec declares
+    // `RealtimeConfigSchema` as a PASSTHROUGH object (`z.core.$loose`), so the
+    // inferred type carries an index signature: `keyof SpecRealtimeConfig`
+    // includes `string`, every `K extends keyof Spec` probe answers `true`, and
+    // `Extract<keyof Local, keyof Spec>` collapses to all of `keyof Local`.
+    // That is the objectstack#4075 mechanism on the SPEC's side — the same
+    // reason `ObjectFieldLike` (plugin-detail, this batch) could not be derived
+    // either. Deriving from a bag is not deriving.
+    type _SpecIsALooseBag = Assert<Extends<string, keyof SpecRealtimeConfig>>;
+
+    // What survives that: assignability, which still honours the REQUIRED keys.
+    type _NotAssignableEitherWay = Assert<Equal<Extends<RealtimeSubscriptionConfig, SpecRealtimeConfig>, false>>;
+    type _NorTheOtherWay = Assert<Equal<Extends<SpecRealtimeConfig, RealtimeSubscriptionConfig>, false>>;
+
+    // And what the local one models, so the reason survives with the pin.
+    type _LocalDialsASocket = Assert<HasKey<RealtimeSubscriptionConfig, 'reconnectInterval'>>;
+
+    expect(true).toBe(true);
+  });
+});

packages/collaboration/src/index.ts

@@ -22,7 +22,7 @@
 
 export {
   useRealtimeSubscription,
-  type RealtimeConfig,
+  type RealtimeSubscriptionConfig,
   type ConnectionState,
   type RealtimeMessage,
   type RealtimeResult,

packages/collaboration/src/useRealtimeSubscription.ts

@@ -8,8 +8,22 @@
 
 import { useState, useEffect, useCallback, useRef } from 'react';
 
-/** WebSocket connection configuration */
-export interface RealtimeConfig {
+/**
+ * WebSocket connection configuration for {@link useRealtimeSubscription}.
+ *
+ * Named `RealtimeSubscriptionConfig`, not `RealtimeConfig` (objectui#3161,
+ * objectstack#4115 ledger batch 7). The spec's `RealtimeConfig`
+ * (`@objectstack/spec/api`) is the app-level realtime DECLARATION — `enabled`,
+ * a `transport` of `websocket | sse | polling`, and a `subscriptions[]` array
+ * whose entries name the record events to deliver. This is one browser socket's
+ * dial settings: which URL, which channel, how to back off when it drops. The
+ * two share no declared key at all — measured against the spec's own schema
+ * shape in `__tests__/spec-symbol-batch7.test.ts` rather than assumed, because
+ * the spec declares that schema as a PASSTHROUGH object and a type-level key
+ * comparison against a bag answers nothing. So there was no dialect to
+ * reconcile here, only a name to hand back.
+ */
+export interface RealtimeSubscriptionConfig {
   /** WebSocket URL */
   url?: string;
   /** Room/channel to subscribe to */
@@ -62,7 +76,7 @@ export interface RealtimeResult<T = unknown> {
  * Provides automatic reconnection with exponential backoff,
  * message buffering, and typed message subscriptions.
  */
-export function useRealtimeSubscription<T = unknown>(config: RealtimeConfig): RealtimeResult<T> {
+export function useRealtimeSubscription<T = unknown>(config: RealtimeSubscriptionConfig): RealtimeResult<T> {
   const {
     url,
     channel,

packages/collaboration/tsconfig.test.json

@@ -0,0 +1,24 @@
+{
+  // Type-checks this package's TESTS, which `tsconfig.json` excludes.
+  // See `packages/types/tsconfig.test.json` for why that exclusion was a hole:
+  // the build correctly keeps tests out of `dist`, but nothing else compiled
+  // them, so a test could assert a contract the compiler never checked.
+  //
+  // Added with the package's first test file (objectui#3161): its load-bearing
+  // content is compile-time `Assert< Equal< …, … > >` pins, which vitest erases
+  // and only `tsc` can check.
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    // The package build emits `dist`; this project emits nothing, so it must
+    // not inherit `composite` / `declaration` from the build config.
+    "composite": false,
+    "declaration": false,
+    "jsx": "react-jsx",
+    // Drop the root tsconfig's source-tree `paths` so `@object-ui/*` and
+    // `@objectstack/spec` resolve through the workspace dependency's built
+    // `.d.ts` instead of pulling sibling sources in as program inputs (TS6059).
+    "paths": {}
+  },
+  "include": ["src/**/*.test.ts", "src/**/*.test.tsx"]
+}