@object-ui/fields 17.1.0 → 17.2.0

package/src/widgets/SliderField.tsx

@@ -1,12 +1,12 @@
 import React from 'react';
 import { Slider } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * Slider field widget - provides a range slider input
  * Supports numeric values with configurable min, max, and step
  */
-export function SliderField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<number>) {
+export function SliderField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<number>) {
   // Get slider-specific configuration from field metadata
   const sliderField = (field || (props as any).schema) as any;
   const min = sliderField?.min ?? 0;

package/src/widgets/SummaryField.tsx

@@ -1,12 +1,12 @@
 import React from 'react';
 import { EmptyValue } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * SummaryField - Read-only aggregation field
  * Values are aggregated from related records and cannot be edited
  */
-export function SummaryField({ value, field, ...props }: FieldWidgetProps<any>) {
+export function SummaryField({ value, field, ...props }: FieldWidgetComponentProps<any>) {
   const summaryField = (field || (props as any).schema) as any;
   const summaryType = summaryField?.summary_type || 'count';
 

package/src/widgets/TagsField.tsx

@@ -1,13 +1,13 @@
 import React from 'react';
 import { Badge, Input, EmptyValue, cn } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * TagsField - free-form list of string tags. Type a value and press Enter (or
  * comma) to add it; click a tag's × to remove it. The stored value is a
  * string[]. Used for the `tags` field type.
  */
-export function TagsField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string[]>) {
+export function TagsField({ value, onChange, field, readonly, className, ...props }: FieldWidgetComponentProps<string[]>) {
   const tags: string[] = Array.isArray(value) ? value : value == null ? [] : [value as unknown as string];
   const [draft, setDraft] = React.useState('');
 
@@ -58,7 +58,7 @@ export function TagsField({ value, onChange, field, readonly, className, ...prop
         onChange={(e) => setDraft(e.target.value)}
         onKeyDown={onKeyDown}
         onBlur={() => addTag(draft)}
-        disabled={(props as any).disabled}
+        disabled={props.disabled}
         placeholder={tags.length === 0 ? '输入后回车添加…' : ''}
         className="h-7 flex-1 border-0 bg-transparent p-0 px-1 shadow-none focus-visible:ring-0 min-w-[8ch]"
       />

package/src/widgets/TextAreaField.tsx

@@ -10,7 +10,7 @@ import {
   Button,
 } from '@object-ui/components';
 import { Maximize2, Check, X } from 'lucide-react';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * TextAreaField - Multi-line text input widget
@@ -21,7 +21,7 @@ import { FieldWidgetProps } from './types';
  * a fullscreen edit dialog — much easier on phones than tapping a 4-row
  * textarea trapped between other fields.
  */
-export function TextAreaField({ value, onChange, field, readonly, errorMessage, ...props }: FieldWidgetProps<string>) {
+export function TextAreaField({ value, onChange, field, readonly, errorMessage, ...props }: FieldWidgetComponentProps<string>) {
   // Hooks must run before any early return (readonly) to keep hook order stable.
   const [fullscreenOpen, setFullscreenOpen] = useState(false);
   const [draft, setDraft] = useState(value ?? '');

package/src/widgets/TextField.tsx

@@ -1,13 +1,13 @@
 import React from 'react';
 import { Input, Textarea, EmptyValue } from '@object-ui/components';
 import { TextareaFieldMetadata } from '@object-ui/types';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * TextField - Standard single-line or multi-line text input
  * Automatically renders as a textarea when rows are configured in field metadata
  */
-export function TextField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<string>) {
+export function TextField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>) {
   const fieldData = field || (props as any).schema;
 
   if (readonly) {

package/src/widgets/TimeField.tsx

@@ -1,13 +1,13 @@
 import React from 'react';
 import { Input, EmptyValue } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 import { openNativePicker } from './openNativePicker';
 
 /**
  * TimeField - Time picker input widget
  * Uses native time input for hour and minute selection
  */
-export function TimeField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<string>) {
+export function TimeField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>) {
   if (readonly) {
     return <span className="text-sm">{value || <EmptyValue />}</span>;
   }

package/src/widgets/UrlField.tsx

@@ -1,12 +1,12 @@
 import React from 'react';
 import { Input, EmptyValue } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * UrlField - URL input with clickable link in readonly mode
  * Validates URLs to only render http/https links for security
  */
-export function UrlField({ value, onChange, field, readonly, errorMessage, ...props }: FieldWidgetProps<string>) {
+export function UrlField({ value, onChange, field, readonly, errorMessage, ...props }: FieldWidgetComponentProps<string>) {
   const config = field || (props as any).schema;
   if (readonly) {
     if (!value) return <EmptyValue />;

package/src/widgets/UserField.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 import { LookupField } from './LookupField';
 
 /**
@@ -29,7 +29,7 @@ function withBannedFilter(filters?: any[]): any[] {
     : [...base, { field: 'banned', operator: 'ne', value: true }];
 }
 
-export function UserField(props: FieldWidgetProps<any>) {
+export function UserField(props: FieldWidgetComponentProps<any>) {
   const raw = (props.field || (props as any).schema) as any;
 
   // The objectSchema field metadata may live directly on `field`, or nested at

package/src/widgets/VectorField.tsx

@@ -1,12 +1,12 @@
 import React from 'react';
 import { EmptyValue } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * VectorField - Vector/embedding data display
  * Shows vector embeddings in a read-only format
  */
-export function VectorField({ value, field, ...props }: FieldWidgetProps<number[]>) {
+export function VectorField({ value, field, ...props }: FieldWidgetComponentProps<number[]>) {
   const vectorField = (field || (props as any).schema) as any;
   const dimensions = vectorField?.dimensions || (Array.isArray(value) ? value.length : 0);
 

package/src/widgets/file-value.ts

@@ -29,6 +29,8 @@
  * onto the same contract.
  */
 
+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. */
@@ -45,12 +47,26 @@ export interface FileValueView {
 
 /**
  * A minted file id: uuid/nanoid-shaped, and crucially not a URL — a URL always
- * carries `:`, `/` or `.`, so it can never match. Mirrors the platform's
- * `isFileIdToken`, which is the arbiter on the server side of the same question.
+ * 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 function isFileIdToken(value: unknown): value is string {
-  return typeof value === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(value);
-}
+export { isFileIdToken };
 
 /**
  * The `sys_file` id a value refers to, or `undefined`.

package/src/widgets/types.ts

@@ -1,10 +1,57 @@
-import { FieldMetadata } from '@object-ui/types';
+import type { AriaAttributes, FocusEventHandler, MouseEventHandler } from 'react';
+import type { 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> = {
+  /* ── The controlled-input contract every widget implements ─────────────── */
 
-export type FieldWidgetProps<T = any> = {
   value: T;
   onChange: (val: T) => void;
-  // Use a looser type for field to avoid complex circular dependencies for now
-  field: FieldMetadata; 
+  /**
+   * 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;
   className?: string;
@@ -15,5 +62,81 @@ export type FieldWidgetProps<T = any> = {
    * widgets ignore it.
    */
   onUploadingChange?: (uploading: boolean) => void;
-  [key: string]: any;
-}
+
+  /* ── Host plumbing: what a rendering host actually forwards ─────────────── */
+
+  /**
+   * 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;
+
+  /* ── DOM pass-through: what `...props` may legitimately reach an input ──── */
+
+  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;
+};