@object-ui/fields 15.0.0 → 16.1.0

package/src/widgets/RadioField.tsx

@@ -1,25 +1,82 @@
-import React, { useId } from 'react';
+import React, { useId, useEffect } from 'react';
 import { RadioGroup, RadioGroupItem, Label, EmptyValue } from '@object-ui/components';
+import { isValueStillOffered, type OptionLike } from '@object-ui/core';
 import { FieldWidgetProps } from './types';
+import { useCascadingOptions } from './useCascadingOptions';
 
-interface Option { label: string; value: string }
+type Option = OptionLike;
 
 /**
  * RadioField - choose exactly one value from a fixed option set, rendered as a
  * radio group. The stored value is the selected option value (string). Used for
  * the `radio` field type.
+ *
+ * Like the single `SelectField`, options support per-option `visibleWhen`
+ * cascading + `dependsOn` gating (ADR-0058 / #2715), resolved through the shared
+ * {@link useCascadingOptions} hook: the offered radios narrow against the live
+ * form record + `current_user`, the control is gated behind a "select the parent
+ * first" hint while a dependency is empty, and a value no longer offered (parent
+ * changed / predicate flipped) is cleared.
  */
-export function RadioField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string>) {
-  const config = (field || (props as any).schema) as any;
-  const options: Option[] = config?.options || [];
+export function RadioField({
+  value,
+  onChange,
+  field,
+  readonly,
+  className,
+  schema,
+  dependentValues,
+  dependsOn: dependsOnProp,
+  emptyHint: _emptyHint,
+  dataSource: _dataSource,
+  ...props
+}: FieldWidgetProps<string>) {
+  const config = (field || schema) as any;
+  const rawOptions: Option[] = config?.options || [];
   const groupId = useId();
+  const fieldName = (props as any).name || config?.name || (props as any).id || '';
+
+  const dependsOn = config?.dependsOn ?? dependsOnProp;
+  const { options, gated, dependsOnFields } = useCascadingOptions<Option>(
+    rawOptions,
+    dependsOn,
+    dependentValues,
+  );
+
+  // Cascade clear: once the offered set no longer includes the current value
+  // (parent changed / predicate flipped), drop it so no stale pair persists.
+  useEffect(() => {
+    if (readonly) return;
+    if (value === undefined || value === null || (value as unknown) === '') return;
+    if (!isValueStillOffered(value, options)) onChange?.(undefined as unknown as string);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [options, gated]);
 
   if (readonly) {
     if (value == null || value === '') return <EmptyValue />;
-    const opt = options.find((o) => o.value === value);
+    // Label from the raw set so a stored value hidden by `visibleWhen` still
+    // renders its label rather than a bare id.
+    const opt = rawOptions.find((o) => o.value === value);
     return <span className="text-sm">{opt?.label || String(value)}</span>;
   }
 
+  // No offered options is unfillable — surface a legible state instead of an
+  // empty radio group: a dependency-gated list prompts for its controlling
+  // field; an unconfigured / fully-filtered list says so. Mirrors the select.
+  if (options.length === 0) {
+    const hint = gated
+      ? `Select ${dependsOnFields.join(' / ')} first`
+      : 'No options available';
+    return (
+      <div
+        data-testid={fieldName ? `radio-empty-${fieldName}` : undefined}
+        className="flex min-h-9 w-full items-center rounded-md border border-input bg-muted/30 px-3 py-2 text-sm text-muted-foreground"
+      >
+        {hint}
+      </div>
+    );
+  }
+
   return (
     <RadioGroup
       value={value ?? ''}
@@ -31,7 +88,7 @@ export function RadioField({ value, onChange, field, readonly, className, ...pro
         const id = `${groupId}-${opt.value}`;
         return (
           <div key={opt.value} className="flex items-center space-x-2">
-            <RadioGroupItem value={opt.value} id={id} />
+            <RadioGroupItem value={opt.value} id={id} data-testid={`radio-option-${opt.value}`} />
             <Label htmlFor={id} className="font-normal">{opt.label}</Label>
           </div>
         );

package/src/widgets/SelectField.tsx

@@ -1,4 +1,4 @@
-import React, { useContext, useEffect, useMemo } from 'react';
+import React, { useEffect } from 'react';
 import {
   Select,
   SelectContent,
@@ -7,19 +7,38 @@ import {
   SelectValue,
   EmptyValue,
 } from '@object-ui/components';
-import {
-  resolveVisibleOptions,
-  isOptionGroupGated,
-  resolveDependsOnFields,
-  isValueStillOffered,
-} from '@object-ui/core';
-import { SchemaRendererContext, usePredicateScope } from '@object-ui/react';
+import { isValueStillOffered } from '@object-ui/core';
 import { SelectFieldMetadata } from '@object-ui/types';
 import { useFieldTranslation } from './useFieldTranslation';
 import { FieldWidgetProps } from './types';
+import { MultiSelectField } from './MultiSelectField';
+import { useCascadingOptions } from './useCascadingOptions';
 
 /**
- * SelectField - Dropdown selection widget with configurable options.
+ * SelectField - dropdown selection widget.
+ *
+ * A field declared `multiple: true` selects zero-or-more values (spec:
+ * `multiple` is valid on `select`), so it renders the multi-value chip picker
+ * — the same widget the `multiselect` type uses. Delegating here (rather than
+ * only at a type-resolution layer) means every surface that renders the
+ * `select` widget — the object form, the inline grid editor, and
+ * `ActionParamDialog` — inherits multi-select identically, with no drift
+ * between them. Single-value selects keep the cascading dropdown below.
+ *
+ * Both branches resolve per-option `visibleWhen` cascading / role-gating through
+ * the shared {@link useCascadingOptions} hook (#2715), so single and multi stay
+ * in lockstep.
+ */
+export function SelectField(props: FieldWidgetProps<any>) {
+  const config = (props.field || (props as any).schema) as SelectFieldMetadata | undefined;
+  if ((config as any)?.multiple) {
+    return <MultiSelectField {...props} />;
+  }
+  return <SingleSelectField {...(props as FieldWidgetProps<string>)} />;
+}
+
+/**
+ * SingleSelectField - single-value dropdown with configurable options.
  *
  * Supports cascading / role-gated options (#2284): each option may carry a
  * `visibleWhen` CEL predicate, evaluated against the live form record +
@@ -29,7 +48,7 @@ import { FieldWidgetProps } from './types';
  * of those is empty the control is gated with a "select the parent first" hint,
  * mirroring the dependent-lookup UX.
  */
-export function SelectField({
+function SingleSelectField({
   value,
   onChange,
   field,
@@ -50,28 +69,11 @@ export function SelectField({
   // react-hook-form field name spread in by the form renderer (FormField).
   const fieldName = (props as any).name || (config as any)?.name || props.id || '';
 
-  // Live form values for cascading options — injected by the form renderer as
-  // `dependentValues` (same channel dependent lookups use), falling back to the
-  // record on SchemaRendererContext. `current_user` etc. come from the global
-  // predicate scope so role/context predicates resolve too.
-  const ctx = useContext(SchemaRendererContext) as any;
-  const record = useMemo<Record<string, unknown>>(() => {
-    return (dependentValues ?? ctx?.formValues ?? ctx?.data ?? {}) as Record<string, unknown>;
-  }, [dependentValues, ctx?.formValues, ctx?.data]);
-  const predicateScope = usePredicateScope();
-
   const dependsOn = (config as any)?.dependsOn ?? dependsOnProp;
-  const dependsOnFields = useMemo(() => resolveDependsOnFields(dependsOn), [dependsOn]);
-  const gated = useMemo(
-    () => dependsOnFields.length > 0 && isOptionGroupGated(dependsOn, record),
-    [dependsOnFields, dependsOn, record],
-  );
-
-  // Effective (offered) options after per-option `visibleWhen` filtering. Empty
-  // while gated so we never present an unfiltered set before the parent is set.
-  const options = useMemo(
-    () => (gated ? [] : resolveVisibleOptions(rawOptions, record, predicateScope)),
-    [gated, rawOptions, record, predicateScope],
+  const { options, gated, dependsOnFields } = useCascadingOptions(
+    rawOptions,
+    dependsOn,
+    dependentValues,
   );
 
   // Cascade clear: once the offered set no longer includes the current value

package/src/widgets/TextAreaField.tsx

@@ -22,6 +22,10 @@ import { FieldWidgetProps } from './types';
  * textarea trapped between other fields.
  */
 export function TextAreaField({ value, onChange, field, readonly, errorMessage, ...props }: FieldWidgetProps<string>) {
+  // Hooks must run before any early return (readonly) to keep hook order stable.
+  const [fullscreenOpen, setFullscreenOpen] = useState(false);
+  const [draft, setDraft] = useState(value ?? '');
+
   if (readonly) {
     return (
       <div className="text-sm whitespace-pre-wrap">
@@ -42,8 +46,6 @@ export function TextAreaField({ value, onChange, field, readonly, errorMessage,
     (props as any).mobile_fullscreen ??
     (props as any).schema?.mobile_fullscreen,
   );
-  const [fullscreenOpen, setFullscreenOpen] = useState(false);
-  const [draft, setDraft] = useState(value ?? '');
 
   const openFullscreen = () => { setDraft(value ?? ''); setFullscreenOpen(true); };
   const cancelFullscreen = () => setFullscreenOpen(false);

package/src/widgets/deriveLookupColumns.test.ts

@@ -50,6 +50,19 @@ describe('deriveLookupColumns', () => {
     expect(deriveLookupColumns(accountSchema, { displayField: 'name', max: 2 })).toHaveLength(2);
   });
 
+  it('skips fields flagged `system: true` even when the name is not a known audit column', () => {
+    const schema = {
+      fields: {
+        name: { type: 'text', label: 'Name' },
+        // Non-canonical name, but stamped system by the framework — must be skipped.
+        custom_ref: { type: 'lookup', label: 'Custom Ref', system: true } as any,
+        code: { type: 'text', label: 'Code' },
+      },
+    };
+    const cols = deriveLookupColumns(schema, { displayField: 'name', max: 10 });
+    expect(cols.map((c) => c.field)).toEqual(['name', 'code']);
+  });
+
   it('honours an object-level displayFields list, with the display field first', () => {
     const schema = {
       fields: {

package/src/widgets/deriveLookupColumns.ts

@@ -1,17 +1,5 @@
 import type { LookupColumnDef } from '@object-ui/types';
-
-/**
- * System / audit fields that carry no disambiguating value in a record picker.
- * Excluded from auto-derived columns so the picker shows business data, not
- * bookkeeping.
- */
-const SYSTEM_FIELDS = new Set<string>([
-  'id', '_id',
-  'created', 'modified', 'created_at', 'updated_at',
-  'created_by', 'updated_by', 'modified_by',
-  'owner_id', 'organization_id', 'space', 'company_id',
-  'instance_state', 'locked', 'is_deleted', 'deleted',
-]);
+import { isSystemManagedField } from '@object-ui/types';
 
 /**
  * Field types that don't render usefully as a compact picker column (large
@@ -31,7 +19,7 @@ export interface DeriveColumnsOptions {
 }
 
 interface ObjectSchemaLike {
-  fields?: Record<string, { type?: string; label?: string; hidden?: boolean }>;
+  fields?: Record<string, { type?: string; label?: string; hidden?: boolean; system?: boolean }>;
   /**
    * ADR-0085 semantic role: the object's most important fields. The single
    * source for "how to list this object" — shared with the detail-page related
@@ -106,8 +94,10 @@ export function deriveLookupColumns(
   // 3. Derive from the field set in declaration order.
   const candidates = Object.keys(fields).filter((name) => {
     if (name === displayField) return false;
-    if (SYSTEM_FIELDS.has(name)) return false;
     const f = fieldDef(name);
+    // Skip framework-managed system/audit/ownership columns (incl. owner_id) —
+    // they carry no disambiguating value in a record picker.
+    if (isSystemManagedField(name, f)) return false;
     if (f.hidden) return false;
     if (f.type && NON_TABULAR_TYPES.has(f.type)) return false;
     return true;

package/src/widgets/types.ts

@@ -9,5 +9,11 @@ export type FieldWidgetProps<T = any> = {
   disabled?: boolean;
   className?: string;
   errorMessage?: string;
+  /**
+   * Upload widgets (`file`/`image`) fire this when their in-progress state
+   * flips, so a host can block submit until a presigned upload settles. Other
+   * widgets ignore it.
+   */
+  onUploadingChange?: (uploading: boolean) => void;
   [key: string]: any;
 }

package/src/widgets/useCascadingOptions.ts

@@ -0,0 +1,46 @@
+import { useContext, useMemo } from 'react';
+import {
+  resolveCascadingOptions,
+  type CascadingOptions,
+  type OptionLike,
+  type DependsOnInput,
+} from '@object-ui/core';
+import { SchemaRendererContext, usePredicateScope } from '@object-ui/react';
+
+/**
+ * Shared per-option cascading / role-gating resolution for the option widgets
+ * (`SelectField` single, `MultiSelectField`, `RadioField`) — the client half of
+ * ADR-0058 (#2284). Each option may carry a `visibleWhen` CEL predicate; the
+ * offered set narrows against the live form record (`record.country == 'cn'`) +
+ * the global predicate scope (`'admin' in current_user.positions`). A field
+ * declares which sibling fields drive its list via `dependsOn`; while any is
+ * empty the list is *gated* — callers surface a "select the parent first" hint
+ * rather than an unfiltered set, mirroring the dependent-lookup UX.
+ *
+ * This is the React wrapper that sources `record` (the live form values) and the
+ * predicate scope from context; the actual resolution is the pure
+ * {@link resolveCascadingOptions} in `@object-ui/core`, shared with the form
+ * renderer so gating/filtering can never drift between them (#2715).
+ */
+export type CascadingOptionsResult<T extends OptionLike> = CascadingOptions<T>;
+
+export function useCascadingOptions<T extends OptionLike>(
+  rawOptions: readonly T[],
+  dependsOn: DependsOnInput,
+  dependentValues: Record<string, unknown> | undefined,
+): CascadingOptionsResult<T> {
+  // Live form values for cascading options — injected by the form renderer as
+  // `dependentValues` (same channel dependent lookups use), falling back to the
+  // record on SchemaRendererContext. `current_user` etc. come from the global
+  // predicate scope so role/context predicates resolve too.
+  const ctx = useContext(SchemaRendererContext) as any;
+  const record = useMemo<Record<string, unknown>>(() => {
+    return (dependentValues ?? ctx?.formValues ?? ctx?.data ?? {}) as Record<string, unknown>;
+  }, [dependentValues, ctx?.formValues, ctx?.data]);
+  const predicateScope = usePredicateScope();
+
+  return useMemo(
+    () => resolveCascadingOptions(rawOptions, record, dependsOn, predicateScope),
+    [rawOptions, record, dependsOn, predicateScope],
+  );
+}

package/src/widgets/useFieldTranslation.ts

@@ -39,6 +39,19 @@ const FIELD_DEFAULTS: Record<string, string> = {
   'lookup.nextPage': 'Next page',
   'lookup.jumpToPage': 'Jump to page',
   'lookup.retry': 'Retry',
+  // objectui#2600 B5 — capability picker scope group headers.
+  'capability.group.platform': 'Platform',
+  'capability.group.org': 'Organization',
+  'capability.group.other': 'Other',
+  // objectui#2600 B5 — curated platform capability labels (registry serves
+  // English; dots in the api-name become underscores in the key).
+  'capability.label.manage_users': 'Manage Users',
+  'capability.label.manage_org_users': 'Manage Organization Users',
+  'capability.label.manage_metadata': 'Manage Metadata',
+  'capability.label.manage_platform_settings': 'Manage Platform Settings',
+  'capability.label.setup_access': 'Setup Access',
+  'capability.label.setup_write': 'Write Settings',
+  'capability.label.studio_access': 'Studio Access',
 };
 
 export const useFieldTranslation = createSafeTranslation(

package/src/widgets/useUploadingSignal.test.tsx

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useUploadingSignal } from './useUploadingSignal';
+
+/**
+ * useUploadingSignal — surfaces an upload widget's in-progress flips to a host
+ * (ActionParamDialog blocks Confirm while a file/image param uploads). It must
+ * fire only when `uploading` changes and always call the latest callback.
+ */
+describe('useUploadingSignal', () => {
+  it('fires with the initial value on mount', () => {
+    const cb = vi.fn();
+    renderHook(() => useUploadingSignal(false, cb));
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenLastCalledWith(false);
+  });
+
+  it('fires again only when `uploading` changes', () => {
+    const cb = vi.fn();
+    const { rerender } = renderHook(({ u }) => useUploadingSignal(u, cb), {
+      initialProps: { u: false },
+    });
+    cb.mockClear();
+
+    rerender({ u: true });
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenLastCalledWith(true);
+
+    // Same value → no extra fire.
+    rerender({ u: true });
+    expect(cb).toHaveBeenCalledTimes(1);
+
+    rerender({ u: false });
+    expect(cb).toHaveBeenCalledTimes(2);
+    expect(cb).toHaveBeenLastCalledWith(false);
+  });
+
+  it('always invokes the latest callback (no stale closure)', () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = renderHook(
+      ({ cb, u }) => useUploadingSignal(u, cb),
+      { initialProps: { cb: first, u: false } },
+    );
+    // Swap the callback without changing `uploading` → no fire yet.
+    rerender({ cb: second, u: false });
+    expect(second).not.toHaveBeenCalled();
+    // Now flip `uploading` → the NEW callback fires, not the old one.
+    rerender({ cb: second, u: true });
+    expect(second).toHaveBeenCalledWith(true);
+    expect(first).not.toHaveBeenCalledWith(true);
+  });
+
+  it('is a no-op when no callback is provided', () => {
+    expect(() => {
+      const { rerender } = renderHook(({ u }) => useUploadingSignal(u), {
+        initialProps: { u: false },
+      });
+      rerender({ u: true });
+    }).not.toThrow();
+  });
+});

package/src/widgets/useUploadingSignal.ts

@@ -0,0 +1,20 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Notify a parent whenever an upload widget's in-progress state flips. Used by
+ * hosts that must block a submit until the presigned upload resolves — e.g.
+ * `ActionParamDialog` disables Confirm so a `file`/`image` param can't be
+ * submitted mid-upload (the value only becomes the fileId once the upload
+ * settles). Fires with the latest callback and only when `uploading` actually
+ * changes, so an inline arrow prop doesn't thrash the parent every render.
+ */
+export function useUploadingSignal(
+  uploading: boolean,
+  onUploadingChange?: (uploading: boolean) => void,
+): void {
+  const ref = useRef(onUploadingChange);
+  ref.current = onUploadingChange;
+  useEffect(() => {
+    ref.current?.(uploading);
+  }, [uploading]);
+}