@object-ui/fields 16.0.0 → 16.1.0

package/src/widgets/ImageField.tsx

@@ -3,6 +3,7 @@ import { Button, EmptyValue } from '@object-ui/components';
 import { useUpload } from '@object-ui/providers';
 import { Upload, X, Image as ImageIcon, Crop as CropIcon, Loader2 } from 'lucide-react';
 import { FieldWidgetProps } from './types';
+import { useUploadingSignal } from './useUploadingSignal';
 
 // Lazy-load the cropper so the dialog (canvas + crop logic) is not in the initial
 // ImageField bundle. Consumers that never crop pay zero cost.
@@ -14,7 +15,7 @@ const ImageCropperDialog = lazy(() =>
  * ImageField - Image upload widget with preview thumbnails
  * Supports single and multiple image uploads with drag-and-drop and preview display
  */
-export function ImageField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
+export function ImageField({ value, onChange, field, readonly, onUploadingChange, ...props }: FieldWidgetProps<any>) {
   const inputRef = useRef<HTMLInputElement>(null);
   const imageField = (field || (props as any).schema) as any;
   const multiple = imageField?.multiple || false;
@@ -26,11 +27,52 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
   const [cropTarget, setCropTarget] = useState<{ index: number; src: string; name: string } | null>(null);
   const { upload } = useUpload();
   const [uploading, setUploading] = useState(false);
+  useUploadingSignal(uploading, onUploadingChange);
+
+  // Derived value + memoized handlers must run before the readonly early return
+  // so hook order stays stable across renders.
+  const images = value ? (Array.isArray(value) ? value : [value]) : [];
+
+  const handleCropConfirm = useCallback(
+    async (blob: Blob, name: string) => {
+      if (!cropTarget) return;
+      setUploading(true);
+      try {
+        const result = await upload(blob);
+        const next = {
+          name: result.name || name,
+          original_name: name,
+          size: result.size,
+          mime_type: result.mimeType,
+          url: result.url,
+        };
+        if (multiple) {
+          const updated = [...images];
+          updated[cropTarget.index] = next;
+          onChange(updated);
+        } else {
+          onChange(next);
+        }
+      } finally {
+        setUploading(false);
+        setCropTarget(null);
+      }
+    },
+    [cropTarget, images, multiple, onChange, upload],
+  );
+
+  const openCropper = useCallback(
+    (index: number) => {
+      const img = images[index];
+      if (!img?.url) return;
+      setCropTarget({ index, src: img.url, name: img.name || `image-${index}.png` });
+    },
+    [images],
+  );
 
   if (readonly) {
     if (!value) return <EmptyValue />;
-    
-    const images = Array.isArray(value) ? value : [value];
+
     return (
       <div className="flex flex-wrap gap-2">
         {images.map((img: any, idx: number) => (
@@ -45,8 +87,6 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
     );
   }
 
-  const images = value ? (Array.isArray(value) ? value : [value]) : [];
-
   const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
     const selectedFiles = Array.from(e.target.files || []);
     if (selectedFiles.length === 0) return;
@@ -87,43 +127,6 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
     }
   };
 
-  const handleCropConfirm = useCallback(
-    async (blob: Blob, name: string) => {
-      if (!cropTarget) return;
-      setUploading(true);
-      try {
-        const result = await upload(blob);
-        const next = {
-          name: result.name || name,
-          original_name: name,
-          size: result.size,
-          mime_type: result.mimeType,
-          url: result.url,
-        };
-        if (multiple) {
-          const updated = [...images];
-          updated[cropTarget.index] = next;
-          onChange(updated);
-        } else {
-          onChange(next);
-        }
-      } finally {
-        setUploading(false);
-        setCropTarget(null);
-      }
-    },
-    [cropTarget, images, multiple, onChange, upload],
-  );
-
-  const openCropper = useCallback(
-    (index: number) => {
-      const img = images[index];
-      if (!img?.url) return;
-      setCropTarget({ index, src: img.url, name: img.name || `image-${index}.png` });
-    },
-    [images],
-  );
-
   return (
     <div className={props.className}>
       <input

package/src/widgets/MultiSelectField.cascade.test.tsx

@@ -0,0 +1,143 @@
+/**
+ * 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.
+ */
+
+/**
+ * Cascading / role-gated `multiselect` options (#2715) — parity with the single
+ * `SelectField` (ADR-0058 / #2284).
+ *
+ * Exercises the observable widget behaviour: the dependency gate (a "select the
+ * parent first" empty-state), and the cascade clear — but here per-element: a
+ * selection dropped from the array when the offered set no longer includes it,
+ * while still-valid selections are kept. The per-option filtering itself is
+ * unit-tested in `@object-ui/core` (`optionRules.test.ts`); here we prove the
+ * chip picker wires `dependentValues` + predicate scope into that resolver via
+ * the shared `useCascadingOptions` hook.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { PredicateScopeProvider } from '@object-ui/react';
+import { MultiSelectField } from './MultiSelectField';
+
+const provinceField = {
+  name: 'province',
+  type: 'multiselect',
+  dependsOn: 'country',
+  options: [
+    { label: 'Zhejiang', value: 'zj', visibleWhen: "record.country == 'cn'" },
+    { label: 'California', value: 'ca', visibleWhen: "record.country == 'us'" },
+  ],
+} as any;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('MultiSelectField — dependency gating (#2715)', () => {
+  it('gates with a "select parent first" hint while the controlling field is empty', () => {
+    render(
+      <MultiSelectField
+        value={[]}
+        onChange={vi.fn()}
+        field={provinceField}
+        {...({ name: 'province', dependentValues: {} } as any)}
+      />,
+    );
+    const gate = screen.getByTestId('multiselect-empty-province');
+    expect(gate).toHaveTextContent(/select country first/i);
+    // Gated → no chips offered.
+    expect(screen.queryAllByRole('button')).toHaveLength(0);
+  });
+
+  it('unlocks the chips once the controlling field is set', () => {
+    render(
+      <MultiSelectField
+        value={[]}
+        onChange={vi.fn()}
+        field={provinceField}
+        {...({ name: 'province', dependentValues: { country: 'cn' } } as any)}
+      />,
+    );
+    expect(screen.queryByTestId('multiselect-empty-province')).not.toBeInTheDocument();
+    // Only the `cn` option is offered.
+    expect(screen.getByTestId('multiselect-option-zj')).toBeInTheDocument();
+    expect(screen.queryByTestId('multiselect-option-ca')).not.toBeInTheDocument();
+  });
+});
+
+describe('MultiSelectField — cascade clear (#2715)', () => {
+  it('drops only the selections the parent change no longer offers', () => {
+    const onChange = vi.fn();
+    render(
+      <MultiSelectField
+        value={['zj', 'ca']}
+        onChange={onChange}
+        field={provinceField}
+        {...({ name: 'province', dependentValues: { country: 'cn' } } as any)}
+      />,
+    );
+    // 'ca' is a US province — under country=cn it is not offered, so it is
+    // pruned; the still-valid 'zj' is kept.
+    expect(onChange).toHaveBeenCalledWith(['zj']);
+  });
+
+  it('keeps selections that are all still offered', () => {
+    const onChange = vi.fn();
+    render(
+      <MultiSelectField
+        value={['zj']}
+        onChange={onChange}
+        field={provinceField}
+        {...({ name: 'province', dependentValues: { country: 'cn' } } as any)}
+      />,
+    );
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+describe('MultiSelectField — role / context gating (#2715)', () => {
+  const tierField = {
+    name: 'tiers',
+    type: 'multiselect',
+    options: [
+      { label: 'Standard', value: 'standard' },
+      { label: 'Admin only', value: 'admin_only', visibleWhen: "'admin' in current_user.positions" },
+    ],
+  } as any;
+
+  it('prunes an admin-only value for a non-admin (offered set excludes it)', () => {
+    const onChange = vi.fn();
+    render(
+      <PredicateScopeProvider scope={{ current_user: { positions: ['sales'] } }}>
+        <MultiSelectField
+          value={['standard', 'admin_only']}
+          onChange={onChange}
+          field={tierField}
+          {...({ name: 'tiers', dependentValues: {} } as any)}
+        />
+      </PredicateScopeProvider>,
+    );
+    expect(onChange).toHaveBeenCalledWith(['standard']);
+  });
+
+  it('keeps an admin-only value for an admin', () => {
+    const onChange = vi.fn();
+    render(
+      <PredicateScopeProvider scope={{ current_user: { positions: ['admin'] } }}>
+        <MultiSelectField
+          value={['standard', 'admin_only']}
+          onChange={onChange}
+          field={tierField}
+          {...({ name: 'tiers', dependentValues: {} } as any)}
+        />
+      </PredicateScopeProvider>,
+    );
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

package/src/widgets/MultiSelectField.tsx

@@ -1,39 +1,102 @@
-import React from 'react';
+import React, { useEffect } from 'react';
 import { Badge, EmptyValue, cn } from '@object-ui/components';
+import type { OptionLike } from '@object-ui/core';
 import { FieldWidgetProps } from './types';
+import { useCascadingOptions } from './useCascadingOptions';
 
-interface Option { label: string; value: string; color?: string }
+interface Option extends OptionLike { color?: string }
 
 /**
  * MultiSelectField - select zero or more values from a fixed option set.
  *
  * Renders the configured options as toggleable chips. The stored value is a
- * string[] (the selected option values). Used for the `multiselect` field type.
+ * string[] (the selected option values). Used for the `multiselect` field type
+ * and for a `select` field declared `multiple: true`.
+ *
+ * Options support the same per-option `visibleWhen` cascading + `dependsOn`
+ * gating as the single `SelectField` (ADR-0058 / #2715), resolved through the
+ * shared {@link useCascadingOptions} hook: the offered chips 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 selections no longer
+ * offered (parent changed / predicate flipped) are dropped from the array.
  */
-export function MultiSelectField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string[]>) {
-  const config = (field || (props as any).schema) as any;
-  const options: Option[] = config?.options || [];
+export function MultiSelectField({
+  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 selected: string[] = Array.isArray(value) ? value : value == null ? [] : [value as unknown as string];
+  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: drop selected values the offered set no longer includes
+  // (parent changed / predicate flipped), keeping the ones still valid — unlike
+  // the scalar case we prune per-element rather than clearing the whole field.
+  useEffect(() => {
+    if (readonly) return;
+    if (selected.length === 0) return;
+    const stillOffered = selected.filter((v) => options.some((o) => o.value === v));
+    if (stillOffered.length !== selected.length) onChange(stillOffered);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [options, gated]);
 
   if (readonly) {
     if (selected.length === 0) return <EmptyValue />;
     return (
       <div className="flex flex-wrap gap-1">
         {selected.map((v) => {
-          const opt = options.find((o) => o.value === v);
+          // 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 === v);
           return <Badge key={v} variant="outline">{opt?.label || v}</Badge>;
         })}
       </div>
     );
   }
 
+  // No offered options is unfillable — surface a legible state instead of an
+  // empty chip row: a dependency-gated list prompts for its controlling field;
+  // an unconfigured / fully-filtered list says so. Mirrors the single select.
+  if (options.length === 0) {
+    const hint = gated
+      ? `Select ${dependsOnFields.join(' / ')} first`
+      : 'No options available';
+    return (
+      <div
+        data-testid={fieldName ? `multiselect-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>
+    );
+  }
+
   const toggle = (v: string) => {
     const next = selected.includes(v) ? selected.filter((x) => x !== v) : [...selected, v];
     onChange(next);
   };
 
   return (
-    <div className={cn('flex flex-wrap gap-1.5', className)}>
+    <div
+      className={cn('flex flex-wrap gap-1.5', className)}
+      data-testid={fieldName ? `multiselect-${fieldName}` : undefined}
+    >
       {options.map((opt) => {
         const active = selected.includes(opt.value);
         return (
@@ -43,6 +106,7 @@ export function MultiSelectField({ value, onChange, field, readonly, className,
             onClick={() => toggle(opt.value)}
             disabled={(props as any).disabled}
             aria-pressed={active}
+            data-testid={`multiselect-option-${opt.value}`}
             className={cn(
               'rounded-full border px-3 py-1 text-sm transition-colors',
               active

package/src/widgets/RadioField.cascade.test.tsx

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+
+/**
+ * Cascading / role-gated `radio` options (#2715) — parity with the single
+ * `SelectField` (ADR-0058 / #2284).
+ *
+ * Exercises the observable widget behaviour: the dependency gate (a "select the
+ * parent first" empty-state) and the scalar cascade clear (a value dropped when
+ * the offered set no longer includes it). The per-option filtering itself is
+ * unit-tested in `@object-ui/core` (`optionRules.test.ts`); here we prove the
+ * radio group wires `dependentValues` + predicate scope into that resolver via
+ * the shared `useCascadingOptions` hook.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { PredicateScopeProvider } from '@object-ui/react';
+import { RadioField } from './RadioField';
+
+const provinceField = {
+  name: 'province',
+  type: 'radio',
+  dependsOn: 'country',
+  options: [
+    { label: 'Zhejiang', value: 'zj', visibleWhen: "record.country == 'cn'" },
+    { label: 'California', value: 'ca', visibleWhen: "record.country == 'us'" },
+  ],
+} as any;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('RadioField — dependency gating (#2715)', () => {
+  it('gates with a "select parent first" hint while the controlling field is empty', () => {
+    render(
+      <RadioField
+        value={undefined}
+        onChange={vi.fn()}
+        field={provinceField}
+        {...({ name: 'province', dependentValues: {} } as any)}
+      />,
+    );
+    const gate = screen.getByTestId('radio-empty-province');
+    expect(gate).toHaveTextContent(/select country first/i);
+    // Gated → no radios offered.
+    expect(screen.queryAllByRole('radio')).toHaveLength(0);
+  });
+
+  it('unlocks the radios once the controlling field is set', () => {
+    render(
+      <RadioField
+        value={undefined}
+        onChange={vi.fn()}
+        field={provinceField}
+        {...({ name: 'province', dependentValues: { country: 'cn' } } as any)}
+      />,
+    );
+    expect(screen.queryByTestId('radio-empty-province')).not.toBeInTheDocument();
+    // Only the `cn` option is offered.
+    expect(screen.getByRole('radio', { name: 'Zhejiang' })).toBeInTheDocument();
+    expect(screen.queryByRole('radio', { name: 'California' })).not.toBeInTheDocument();
+  });
+});
+
+describe('RadioField — cascade clear (#2715)', () => {
+  it('clears a value the parent change no longer offers', () => {
+    const onChange = vi.fn();
+    render(
+      <RadioField
+        value={'ca'}
+        onChange={onChange}
+        field={provinceField}
+        {...({ name: 'province', dependentValues: { country: 'cn' } } as any)}
+      />,
+    );
+    // 'ca' is a US province — under country=cn it is not offered, so it is dropped.
+    expect(onChange).toHaveBeenCalledWith(undefined);
+  });
+
+  it('keeps a value that is still offered', () => {
+    const onChange = vi.fn();
+    render(
+      <RadioField
+        value={'zj'}
+        onChange={onChange}
+        field={provinceField}
+        {...({ name: 'province', dependentValues: { country: 'cn' } } as any)}
+      />,
+    );
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+describe('RadioField — role / context gating (#2715)', () => {
+  const tierField = {
+    name: 'tier',
+    type: 'radio',
+    options: [
+      { label: 'Standard', value: 'standard' },
+      { label: 'Admin only', value: 'admin_only', visibleWhen: "'admin' in current_user.positions" },
+    ],
+  } as any;
+
+  it('clears an admin-only value for a non-admin (offered set excludes it)', () => {
+    const onChange = vi.fn();
+    render(
+      <PredicateScopeProvider scope={{ current_user: { positions: ['sales'] } }}>
+        <RadioField
+          value={'admin_only'}
+          onChange={onChange}
+          field={tierField}
+          {...({ name: 'tier', dependentValues: {} } as any)}
+        />
+      </PredicateScopeProvider>,
+    );
+    expect(onChange).toHaveBeenCalledWith(undefined);
+  });
+
+  it('keeps an admin-only value for an admin', () => {
+    const onChange = vi.fn();
+    render(
+      <PredicateScopeProvider scope={{ current_user: { positions: ['admin'] } }}>
+        <RadioField
+          value={'admin_only'}
+          onChange={onChange}
+          field={tierField}
+          {...({ name: 'tier', dependentValues: {} } as any)}
+        />
+      </PredicateScopeProvider>,
+    );
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

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>
         );