@object-ui/fields 16.1.0 → 17.2.0

package/dist/widgets/file-value.d.ts

@@ -0,0 +1,99 @@
+import { isFileIdToken } from '@objectstack/spec/data';
+/** A file value normalised for rendering, whatever form it arrived in. */
+export interface FileValueView {
+    /** `sys_file` id, when the value carries one. */
+    id?: string;
+    /** Best available display name. Never empty. */
+    name: string;
+    /** Resolvable URL, when the value carries one. A bare reference does not. */
+    url?: string;
+    size?: number;
+    mimeType?: string;
+    /** The value as it arrived, so callers can pass it through untouched. */
+    raw: unknown;
+}
+/**
+ * A minted file id: uuid/nanoid-shaped, and crucially not a URL — a URL always
+ * carries `:`, `/` or `.`, so it can never match.
+ *
+ * This IS the platform's arbiter now, not a mirror of it (objectui#3161,
+ * objectstack#4115 ledger batch 7). The declaration that stood here said it
+ * "mirrors the platform's `isFileIdToken`" while being a character-for-character
+ * copy of that function's body under that function's own name — the shape
+ * objectui#3003 argued about and objectui#3169 caught again in
+ * `isAggregatedViewContainer`: every value test and every behaviour test passes
+ * against a faithful copy, so reference identity is the only check that can tell
+ * a re-export from a fork. It is asserted in
+ * `__tests__/spec-symbol-batch7.test.ts`.
+ *
+ * Why it matters that this one is shared rather than duplicated: the regex is a
+ * WIRE decision. Widening it server-side (say, ids grow past 64 chars) while a
+ * copy here keeps the old bound turns every new id into "not a reference", and
+ * the widget then submits the legacy inline blob against a backend that expects
+ * a reference. That failure surfaces as a broken thumbnail, nowhere near a
+ * regex.
+ */
+export { isFileIdToken };
+/**
+ * The `sys_file` id a value refers to, or `undefined`.
+ *
+ * `file_id ?? id` matches the rule `serializeParamValues` already applies to
+ * action params — one extraction rule for both surfaces.
+ */
+export declare function fileIdOf(value: unknown): string | undefined;
+/**
+ * The stable download endpoint a bare `sys_file` id resolves to.
+ *
+ * `createObjectStackUploadAdapter` stores exactly this URL (`${basePath}/files/
+ * :id`, default base `/api/v1/storage`) as a completed upload's value, and the
+ * endpoint 302-redirects to a freshly-signed short-lived URL on every request —
+ * so it can be used directly as an `<img src>`. Building it here means a value
+ * still in its bare-reference form (the backend read path didn't expand it —
+ * seen on the edit-form data path, objectui image thumbnails rendering broken)
+ * resolves to a real URL instead of an empty `src`.
+ */
+export declare const FILE_STORAGE_BASE_PATH = "/api/v1/storage";
+/** The stable download URL for a `sys_file` id. */
+export declare function fileUrlFromId(id: string): string;
+/**
+ * Normalise one file value for display.
+ *
+ * @param fallbackName shown when the value carries no usable name — pass a
+ *   translated string so the widget stays localised.
+ */
+export declare function readFileValue(value: unknown, fallbackName?: string): FileValueView;
+/** Normalise a field value (single or `multiple`) to an array of views. */
+export declare function readFileValues(value: unknown, fallbackName?: string): FileValueView[];
+/** Does this value look like an image, by MIME type? */
+export declare function isImageValue(view: FileValueView): boolean;
+/** The subset of an upload result these helpers read. */
+export interface UploadResultLike {
+    url: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * What to store in the field for a completed upload.
+ *
+ * Returns the bare `sys_file` id when the adapter surfaced one — the reference
+ * form — and the legacy inline blob when it did not, so a deployment whose
+ * upload adapter or backend predates file-as-reference keeps working unchanged.
+ */
+export declare function fileValueForSubmit(result: UploadResultLike, originalName?: string): string | Record<string, unknown>;
+/**
+ * The display view of a just-completed upload.
+ *
+ * Submitting a bare id means the field value no longer carries the name, size
+ * or URL needed to render it, and the enriched form only comes back on the next
+ * read. Widgets keep these views keyed by id so an upload appears immediately
+ * instead of showing a bare token until a refetch.
+ */
+export declare function uploadResultView(result: UploadResultLike, originalName?: string): FileValueView;
+/**
+ * Merge locally-known upload views over a field value's own views, matched by
+ * id. A value that is still a bare reference picks up the name/URL captured at
+ * upload time; anything already enriched by the backend is left alone.
+ */
+export declare function withRecentUploads(views: FileValueView[], recent: Record<string, FileValueView>): FileValueView[];

package/dist/widgets/file-value.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/widgets/types.d.ts

@@ -1,7 +1,53 @@
-import { FieldMetadata } from '@object-ui/types';
-export type FieldWidgetProps<T = any> = {
+import { AriaAttributes, FocusEventHandler, MouseEventHandler } from 'react';
+import { DependsOnInput, FieldMetadata } from '@object-ui/types';
+/**
+ * Props every field widget in this package receives at RUNTIME.
+ *
+ * Named `FieldWidgetComponentProps`, not `FieldWidgetProps` (objectui#3161,
+ * objectstack#4115 ledger batch 7), adopting the name `@object-ui/app-shell`
+ * settled on for the same split in objectui#3169: `@objectstack/spec/ui` owns
+ * `FieldWidgetProps` for the DECLARED widget-plugin contract — a zod object
+ * (`FieldWidgetPropsSchema`) a plugin manifest is validated against, with
+ * `field` narrowed to `{ name?, label?, type: <the FieldType enum> }` and
+ * `readonly` / `required` carrying `.default()`s. This is the React interface
+ * the widgets in this directory actually implement, against
+ * `@object-ui/types`'s much richer `FieldMetadata`.
+ *
+ * The two are NOT interchangeable, and the divergence is not cosmetic: the
+ * spec's contract names the error slot `error`, this one names it
+ * `errorMessage`, so a widget written to the spec's declared props renders no
+ * validation message here. That divergence is tracked in objectui#3222 and is
+ * deliberately NOT resolved here — but it is now *visible*: reading
+ * `props.error` or `props.required` off this type is a compile error rather
+ * than a silent `any`.
+ *
+ * ## Why there is no `[key: string]: any` (objectui#3221)
+ *
+ * This type used to end in an index signature, "load-bearing" for the widgets'
+ * `...props` spreads. It was also why every drift above was invisible: **a type
+ * that claims to have every key can never be reported as missing one** (the
+ * objectstack#4075 mechanism). `props.required` and `props.error` were legal
+ * reads typed `any` and always `undefined` at runtime; a misspelled prop
+ * (`readOnly` for `readonly`, `onchange` for `onChange`) compiled; and any
+ * structural/parity comparison against the type was useless *in principle*,
+ * which is why the batch-7 symbol guard was the only detector that could see
+ * the collision at all.
+ *
+ * It is replaced by the CLOSED set below: the controlled-input contract, the
+ * host plumbing the form renderer genuinely forwards, and a DOM pass-through
+ * allowance. `data-*` is an open family by design (it is open in HTML too) and
+ * is expressed as a template-literal index signature, which — unlike
+ * `[key: string]` — leaves `keyof` finite, so an undeclared prop still fails.
+ *
+ * Adding a key here is a contract change: say who produces it and who reads it.
+ */
+export type FieldWidgetComponentProps<T = any> = {
     value: T;
     onChange: (val: T) => void;
+    /**
+     * The field's metadata. Deliberately the looser `@object-ui/types` shape
+     * rather than the spec's, to avoid a circular dependency for now.
+     */
     field: FieldMetadata;
     readonly?: boolean;
     disabled?: boolean;
@@ -13,5 +59,75 @@ export type FieldWidgetProps<T = any> = {
      * widgets ignore it.
      */
     onUploadingChange?: (uploading: boolean) => void;
-    [key: string]: any;
+    /**
+     * The raw authored node the widget was rendered from. Two hosts supply it:
+     * `SchemaRenderer` (`<Component schema={schema} {...schema} />`) and the
+     * form renderer's `renderFieldComponent` (`schema={props.field || ...}`),
+     * which is why ~25 widgets read `field || schema` for their config.
+     *
+     * This is a second carrier for what `field` already means, i.e. a de-facto
+     * second contract (AGENTS.md #0.1) — declared here so it is at least
+     * visible; converging the two is tracked separately.
+     */
+    schema?: FieldMetadata | Record<string, unknown>;
+    /**
+     * DataSource for widgets that query records (lookup / user / object-ref /
+     * recipient-picker / grid). Injected by the form renderer for the field
+     * types that need it, and passed directly by inline-edit hosts. Option
+     * widgets destructure it purely to keep it off their DOM spread.
+     *
+     * Left structural (`unknown`): `@object-ui/fields` must not depend on a
+     * concrete adapter — every consumer narrows it itself.
+     */
+    dataSource?: unknown;
+    /**
+     * Live sibling-field values driving cascading / role-gated options and
+     * dependent lookups (ADR-0058, #2215/#2284). The form renderer passes the
+     * in-progress record; widgets fall back to `SchemaRendererContext`.
+     */
+    dependentValues?: Record<string, unknown>;
+    /**
+     * Controlling field(s) that gate this field's option list. Normally declared
+     * on the field metadata; accepted as a prop so a host can drive the gate for
+     * a field it synthesised. Field metadata wins when both are present.
+     */
+    dependsOn?: DependsOnInput;
+    /**
+     * Hint shown when a dependency-gated option list is still waiting on its
+     * controlling field. Forwarded by the form renderer; the option widgets in
+     * this package currently discard it and render their own message instead.
+     */
+    emptyHint?: string;
+    /**
+     * Render as a single-line, borderless control for a grid cell (the inline
+     * editor and the line-item grid set it) instead of the full form layout.
+     */
+    compact?: boolean;
+    /**
+     * Receive the FULL selected record rather than just its id, so a host can
+     * auto-fill sibling fields from it (a line-item grid copying a product's
+     * price). When provided, the host owns the resulting value change.
+     */
+    onSelectRecord?: (record: Record<string, any>) => void;
+    /**
+     * Offer a "create new" affordance in a record picker, carrying whatever the
+     * user had typed. Also declarable on the field metadata.
+     */
+    onCreateNew?: (searchQuery: string) => void;
+    id?: string;
+    /** react-hook-form's field name, spread in by the form renderer. */
+    name?: string;
+    autoFocus?: boolean;
+    tabIndex?: number;
+    onBlur?: FocusEventHandler<HTMLElement>;
+    onFocus?: FocusEventHandler<HTMLElement>;
+    onClick?: MouseEventHandler<HTMLElement>;
+} & AriaAttributes & {
+    /**
+     * Arbitrary `data-*` attributes (test ids, analytics hooks). Open by design,
+     * but a template-literal key — `keyof` stays finite, so this does NOT
+     * reintroduce the index signature objectui#3221 removed: `props.required`
+     * is still an error, `props['data-testid']` is still fine.
+     */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
 };

package/dist/widgets/useFieldTranslation.d.ts

@@ -1,5 +1,7 @@
 export declare const useFieldTranslation: () => {
     t: (key: string, options?: Record<string, unknown>) => string;
+    language: string;
 } | {
     t: import('i18next').TFunction<string, undefined>;
+    language: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/fields",
-  "version": "16.1.0",
+  "version": "17.2.0",
   "description": "Field renderers and registry for Object UI",
   "license": "MIT",
   "type": "module",
@@ -24,18 +24,19 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@objectstack/spec": "^17.0.0-rc.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.25.0",
     "react-markdown": "^10.1.0",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.6.0",
-    "@object-ui/components": "16.1.0",
-    "@object-ui/core": "16.1.0",
-    "@object-ui/i18n": "16.1.0",
-    "@object-ui/providers": "16.1.0",
-    "@object-ui/react": "16.1.0",
-    "@object-ui/types": "16.1.0"
+    "@object-ui/components": "17.2.0",
+    "@object-ui/core": "17.2.0",
+    "@object-ui/i18n": "17.2.0",
+    "@object-ui/providers": "17.2.0",
+    "@object-ui/react": "17.2.0",
+    "@object-ui/types": "17.2.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -44,7 +45,7 @@
   "devDependencies": {
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
-    "@vitejs/plugin-react": "^6.0.3",
+    "@vitejs/plugin-react": "^6.0.4",
     "typescript": "^6.0.3",
     "vite": "^8.1.5",
     "vite-plugin-dts": "^5.0.3"

package/src/FieldEditWidget.test.ts

@@ -7,12 +7,33 @@
  */
 
 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';
 
+/**
+ * A field type the form can render — either a direct widget-map key, or a spec
+ * spelling that resolves onto one through the alias table (`secret` →
+ * `field:password`, `autonumber` → `field:auto_number`, …).
+ *
+ * `FORM_FIELD_TYPES` alone is `Object.keys(fieldWidgetMap)`, which does NOT
+ * include the alias-only spellings — see the note at index.tsx's
+ * `resolveFormWidgetType`. Using it as the definition of "a real type" made the
+ * staleness check below reject `secret`, a genuine spec field type the form
+ * renders, purely because it arrives via an alias.
+ */
+function isRenderableFormType(t: string): boolean {
+  // `text` is the alias table's fallback, so a non-`field:text` result means an
+  // explicit entry exists. `text` itself is a direct widget key, so it is
+  // already covered by the first clause and no real type is missed here.
+  return FORM_FIELD_TYPES.includes(t) || mapFieldTypeToFormType(t) !== 'field:text';
+}
+
 /**
  * Drift-guard: the inline cell editor reuses the form's field widgets, but the
  * two lists were hand-maintained separately and drifted — `lookup` (and other
@@ -34,11 +55,21 @@ describe('inline editor ↔ form widget parity', () => {
   });
 
   it('the exclusion set lists only real form types (no stale entries)', () => {
-    const known = new Set(FORM_FIELD_TYPES);
-    const stale = [...INLINE_EXCLUDED_FIELD_TYPES].filter((t) => !known.has(t));
+    const stale = [...INLINE_EXCLUDED_FIELD_TYPES].filter((t) => !isRenderableFormType(t));
     expect(stale).toEqual([]);
   });
 
+  it('credential types are never inline-editable', () => {
+    // The grid's fallback for a type with no inline editor is a PLAIN TEXT input.
+    // Both of these are masked on read, so that input would show the mask as the
+    // value and write it straight back; `secret` also round-trips through an
+    // encrypted store (ADR-0100), so the cell holds an opaque ref, not the value.
+    for (const t of ['password', 'secret']) {
+      expect(hasFieldEditWidget(t), `${t} must not have an inline editor`).toBe(false);
+      expect(INLINE_EXCLUDED_FIELD_TYPES.has(t), `${t} must be explicitly excluded`).toBe(true);
+    }
+  });
+
   it('relational fields use the standard picker inline (regression: lookup was a text box)', () => {
     for (const t of ['lookup', 'master_detail', 'user', 'owner']) {
       expect(hasFieldEditWidget(t)).toBe(true);
@@ -59,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);
+    }
+  });
+});

package/src/FieldEditWidget.tsx

@@ -7,7 +7,7 @@
  */
 
 import React from 'react';
-import type { FieldWidgetProps } from './widgets/types';
+import type { FieldWidgetComponentProps } from './widgets/types';
 
 // The SAME dedicated widgets the form renders — reused for in-place editing
 // (e.g. the data grid's inline cell editor) so a select edits as a dropdown, a
@@ -44,6 +44,9 @@ import { LocationField } from './widgets/LocationField';
 import { GeolocationField } from './widgets/GeolocationField';
 import { CodeField } from './widgets/CodeField';
 import { QRCodeField } from './widgets/QRCodeField';
+// The FORM's spec-alias table (`json` → `field:code`, `tree` → `field:lookup`,
+// …) — inline resolution reuses it so spec spellings get the form's decision.
+import { mapFieldTypeToFormType } from './field-type-alias';
 
 /**
  * Field types that edit in place with a dedicated widget. Keyed by the raw
@@ -51,7 +54,7 @@ import { QRCodeField } from './widgets/QRCodeField';
  * Rich/heavy types (file, image, lookup, richtext, …) are intentionally absent
  * so callers fall back to their own simpler editor.
  */
-const EDIT_WIDGETS: Record<string, React.ComponentType<FieldWidgetProps<any>>> = {
+const EDIT_WIDGETS: Record<string, React.ComponentType<FieldWidgetComponentProps<any>>> = {
   text: TextField,
   textarea: TextAreaField,
   number: NumberField,
@@ -102,7 +105,13 @@ export const INLINE_EXCLUDED_FIELD_TYPES = new Set<string>([
   // Binary / attachment — edited from the record form, shown read-only in the grid.
   'file', 'image', 'avatar', 'signature',
   // Heavy / full editors — better in the record form than a cell.
-  'markdown', 'html', 'richtext', 'password',
+  'markdown', 'html', 'richtext',
+  // Credentials — never inline-editable. Both are masked on read, so the cell has
+  // no real value to seed an editor with, and the grid's fallback is a PLAIN TEXT
+  // input: it would render the mask as if it were the value and write it straight
+  // back. `secret` additionally round-trips through an encrypted store (ADR-0100,
+  // data/field.zod.ts) — the cell holds an opaque ref, not the secret.
+  'password', 'secret',
   // Containers / non-authorable — a sub-form / sub-grid / embedding vector
   // doesn't belong in a single cell.
   'object', 'grid', 'vector',
@@ -116,9 +125,39 @@ export const DISCRETE_EDIT_TYPES = new Set<string>([
   'boolean', 'toggle', 'select', 'status', 'radio', 'rating',
 ]);
 
+/**
+ * Resolve a field type to its inline-editing key: the raw type when the
+ * widget/exclusion tables name it directly, otherwise its form-alias target
+ * (`mapFieldTypeToFormType`, `field:` prefix stripped).
+ *
+ * The tables are keyed by the FORM's spellings, but spec field types reach
+ * this layer in the SPEC's spellings — `json`, `tree`, `composite`, `record`,
+ * `repeater`, `video`, `audio`, `autonumber` are aliases in the form map and
+ * were keys in NEITHER table here, so the grid silently fell back to a plain
+ * text input for all of them: typing over structured JSON or a hierarchy ref
+ * is a value-corruption path (#2942). Resolving through the same alias table
+ * the form uses gives each spec type the form's own decision: `json` → the
+ * code editor, `tree` → the lookup picker, and the container/computed/binary
+ * families → their documented exclusions.
+ */
+function resolveInlineEditType(type: string): string {
+  if (type in EDIT_WIDGETS || INLINE_EXCLUDED_FIELD_TYPES.has(type)) return type;
+  return mapFieldTypeToFormType(type).replace(/^field:/, '');
+}
+
 /** True when a field type has a dedicated in-place edit widget. */
 export function hasFieldEditWidget(type: string | undefined): boolean {
-  return !!type && type in EDIT_WIDGETS;
+  return !!type && resolveInlineEditType(type) in EDIT_WIDGETS;
+}
+
+/**
+ * True when a field type is deliberately NOT inline-editable (alias-aware:
+ * `composite` resolves to the excluded `object`, `video` to `file`, …).
+ * Grid hosts must treat these as read-only cells — falling back to a plain
+ * text editor is exactly the corruption path the exclusion exists to close.
+ */
+export function isInlineExcludedFieldType(type: string | undefined): boolean {
+  return !!type && INLINE_EXCLUDED_FIELD_TYPES.has(resolveInlineEditType(type));
 }
 
 /**
@@ -141,9 +180,12 @@ export function FieldEditWidget({
   value,
   onChange,
   readonly,
-}: FieldWidgetProps<any>): React.ReactElement | null {
-  const Widget = field?.type ? EDIT_WIDGETS[field.type] : undefined;
+}: FieldWidgetComponentProps<any>): React.ReactElement | null {
+  const resolved = field?.type ? resolveInlineEditType(field.type) : undefined;
+  const Widget = resolved ? EDIT_WIDGETS[resolved] : undefined;
   if (!Widget) return null;
-  const compactProps = field?.type && COMPACT_EDIT_TYPES.has(field.type) ? { compact: true } : {};
-  return <Widget field={field} value={value} onChange={onChange} readonly={readonly} {...(compactProps as any)} />;
+  // `compact` is a declared widget prop (objectui#3221 closed this type), so
+  // the spread no longer needs an `any` escape hatch to get past it.
+  const compactProps = resolved && COMPACT_EDIT_TYPES.has(resolved) ? { compact: true } : {};
+  return <Widget field={field} value={value} onChange={onChange} readonly={readonly} {...compactProps} />;
 }

package/src/__tests__/spec-symbol-batch7.test.ts

@@ -0,0 +1,112 @@
+/**
+ * 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/fields` ↔ `@objectstack/spec` symbol-collision guards
+ * (objectui#3161, objectstack#4115 ledger batch 7).
+ *
+ * Two symbols, two different verdicts:
+ *
+ *  - `isFileIdToken` was a character-for-character copy of the spec's function
+ *    under the spec's own name. It is a re-export now, and the gate below is
+ *    REFERENCE IDENTITY — not behaviour. A faithful copy passes every behaviour
+ *    test ever written for it (objectui#3003, re-proved on
+ *    `isAggregatedViewContainer` in objectui#3169), so `toBe` is the only
+ *    assertion that can tell a re-export from a fork.
+ *
+ *  - `FieldWidgetProps` is now `FieldWidgetComponentProps`. The spec owns that
+ *    name for the DECLARED widget-plugin props contract; this package's is the
+ *    React interface its widgets implement. The pins record the divergence that
+ *    made re-exporting impossible — and, since objectui#3221 closed the type,
+ *    that the divergence is now *visible* rather than swallowed by a
+ *    `[key: string]: any` index signature.
+ *
+ * The other direction — "the spec must not start owning the NEW names" — is not
+ * asserted here because `scripts/check-spec-symbol-derivation.mjs` already
+ * answers it on every CI run, for every name in the package rather than the
+ * handful a test would remember to list.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { isFileIdToken as specIsFileIdToken } from '@objectstack/spec/data';
+import type { FieldWidgetProps as SpecFieldWidgetProps } from '@objectstack/spec/ui';
+
+import { isFileIdToken, fileIdOf } from '../widgets/file-value';
+import type { FieldWidgetComponentProps } from '../widgets/types';
+
+describe('isFileIdToken IS the spec function', () => {
+  it('is the same function object, not an equivalent one', () => {
+    // The whole point. Every value/behaviour assertion below this line would
+    // also pass against a re-forked copy; this one would not.
+    expect(isFileIdToken).toBe(specIsFileIdToken);
+  });
+
+  it('is the arbiter the rest of the module routes through', () => {
+    // `fileIdOf` must keep agreeing with the shared predicate, so a future
+    // "small local tweak" to the id shape cannot be reintroduced one caller at
+    // a time.
+    for (const value of ['abc123', 'AbC-_9', 'x'.repeat(64)]) {
+      expect(specIsFileIdToken(value)).toBe(true);
+      expect(fileIdOf(value)).toBe(value);
+    }
+    for (const value of ['https://example.com/f.png', '/api/v1/storage/files/1', 'a.b', 'x'.repeat(65)]) {
+      expect(specIsFileIdToken(value)).toBe(false);
+      expect(fileIdOf(value)).toBeUndefined();
+    }
+  });
+});
+
+/* -------------------------------------------------------------------------- */
+/* Compile-time pins. A violation is a `tsc` error, not a runtime failure.     */
+/* This package's tsconfig.json includes its tests, so `type-check` compiles   */
+/* them (scripts/check-type-check-coverage.mjs keeps that true).              */
+/* -------------------------------------------------------------------------- */
+
+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;
+
+describe('FieldWidgetComponentProps is the RENDERED layer of the spec contract', () => {
+  it('is pinned at compile time', () => {
+    // The import above is itself half the tripwire: the day the spec stops
+    // exporting `FieldWidgetProps`, this file stops compiling and the rename's
+    // reason is up for re-triage (the plain name could come back).
+    type _SpecIsReal = Assert<Equal<IsAny<SpecFieldWidgetProps>, false>>;
+
+    // The divergence that makes a re-export impossible AND is a live defect
+    // worth naming: the declared contract calls the validation-message slot
+    // `error`; every widget in this package reads `errorMessage`. A widget
+    // written against the spec's declared props renders no message here, and
+    // nothing reports it. Recorded, not fixed, by the rename — objectui#3222.
+    type _SpecNamesItError = Assert<HasKey<SpecFieldWidgetProps, 'error'>>;
+    type _LocalNamesItErrorMessage = Assert<HasKey<FieldWidgetComponentProps, 'errorMessage'>>;
+
+    // …and the reason nobody noticed used to sit right here: three pins
+    // asserting that `[key: string]: any` was still present, and that
+    // `props.required` / `props.error` therefore read as `any`. objectui#3221
+    // removed that index signature, so those pins have gone red on purpose and
+    // are gone with it. What replaces them is the inverse claim — the type is
+    // now CLOSED, so the two keys the spec declares and this one does not can
+    // finally be reported as missing. That is what makes objectui#3222 (the
+    // `error` / `errorMessage` divergence) decidable by the compiler instead of
+    // by a symbol guard.
+    type _NoStringIndexSignature = Assert<Equal<Extends<string, keyof FieldWidgetComponentProps>, false>>;
+    type _RequiredIsAbsent = Assert<Equal<HasKey<FieldWidgetComponentProps, 'required'>, false>>;
+    type _ErrorIsAbsent = Assert<Equal<HasKey<FieldWidgetComponentProps, 'error'>, false>>;
+
+    // `data-*` stays open (it is open in HTML too), but as a template-literal
+    // key — the distinction that keeps `keyof` finite above. A pin, because
+    // widening it back to `[key: string]` would silently restore the defect
+    // while every assertion here still read as "closed".
+    type _DataAttributesStayOpen = Assert<Extends<'data-testid', keyof FieldWidgetComponentProps>>;
+
+    expect(true).toBe(true);
+  });
+});