@object-ui/fields 14.0.0 → 14.1.0

package/src/widgets/FileField.tsx

@@ -5,39 +5,24 @@ import { Upload, X, File as FileIcon, ImageIcon, Camera, Loader2 } from 'lucide-
 import { FieldWidgetProps } from './types';
 
 /**
- * FileField - File upload widget with drag-and-drop support
- * Supports single and multiple file uploads with configurable accepted file types.
- * L2: File size validation, per-file progress indicators, error messages.
+ * Shared upload pipeline for the file widgets: validates size, uploads through
+ * the configured UploadProvider adapter (with progress), and merges results
+ * into the field value — append for `multiple`, replace otherwise. Extracted so
+ * the full-size FileField and the compact grid-cell {@link FileCell} stay
+ * behaviourally identical (same value shape, same error handling).
  */
-export function FileField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
-  const inputRef = useRef<HTMLInputElement>(null);
-  const cameraRef = useRef<HTMLInputElement>(null);
-  const fileField = (field || (props as any).schema) as any;
-  const multiple = fileField?.multiple || false;
-  const accept = fileField?.accept ? fileField.accept.join(',') : undefined;
-  const maxSize = fileField?.maxSize as number | undefined; // bytes
-  /**
-   * Camera capture mode for mobile devices.
-   * - `'environment'` (back camera): photos of receipts, documents, products
-   * - `'user'` (front camera): selfies, profile pictures
-   * - `false`: disable the camera button entirely
-   * @default 'environment' when accept includes image/* on a touch device
-   */
-  const captureMode = (fileField?.capture ?? null) as 'environment' | 'user' | false | null;
-  const acceptsImages = !accept || accept.split(',').some((t: string) =>
-    t.trim().startsWith('image/') || t.trim() === 'image/*' || t.trim().startsWith('.jp') || t.trim().startsWith('.png') || t.trim().startsWith('.gif') || t.trim().startsWith('.webp'),
-  );
-  // Auto-enable camera button on touch devices when image upload is permitted, unless explicitly disabled.
-  const isTouchDevice = typeof navigator !== 'undefined' && (navigator.maxTouchPoints > 0 || /Mobi|Android/i.test(navigator.userAgent));
-  const cameraEnabled = captureMode === false ? false : (captureMode ?? (acceptsImages && isTouchDevice ? 'environment' : null));
-  const [isDragOver, setIsDragOver] = useState(false);
-  const [errors, setErrors] = useState<string[]>([]);
+function useFileUploads(opts: {
+  files: any[];
+  multiple: boolean;
+  maxSize?: number;
+  onChange: (value: any) => void;
+}) {
+  const { files, multiple, maxSize, onChange } = opts;
   const { upload } = useUpload();
+  const [errors, setErrors] = useState<string[]>([]);
   const [uploadProgress, setUploadProgress] = useState<Record<string, number>>({});
   const [uploading, setUploading] = useState(false);
 
-  const files = value ? (Array.isArray(value) ? value : [value]) : [];
-
   const processFiles = useCallback(async (selectedFiles: File[]) => {
     if (selectedFiles.length === 0) return;
     const newErrors: string[] = [];
@@ -91,6 +76,42 @@ export function FileField({ value, onChange, field, readonly, ...props }: FieldW
     }
   }, [files, multiple, onChange, maxSize, upload]);
 
+  return { processFiles, errors, uploading, uploadProgress };
+}
+
+/**
+ * FileField - File upload widget with drag-and-drop support
+ * Supports single and multiple file uploads with configurable accepted file types.
+ * L2: File size validation, per-file progress indicators, error messages.
+ */
+export function FileField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const cameraRef = useRef<HTMLInputElement>(null);
+  const fileField = (field || (props as any).schema) as any;
+  const multiple = fileField?.multiple || false;
+  const accept = fileField?.accept ? fileField.accept.join(',') : undefined;
+  const maxSize = fileField?.maxSize as number | undefined; // bytes
+  /**
+   * Camera capture mode for mobile devices.
+   * - `'environment'` (back camera): photos of receipts, documents, products
+   * - `'user'` (front camera): selfies, profile pictures
+   * - `false`: disable the camera button entirely
+   * @default 'environment' when accept includes image/* on a touch device
+   */
+  const captureMode = (fileField?.capture ?? null) as 'environment' | 'user' | false | null;
+  const acceptsImages = !accept || accept.split(',').some((t: string) =>
+    t.trim().startsWith('image/') || t.trim() === 'image/*' || t.trim().startsWith('.jp') || t.trim().startsWith('.png') || t.trim().startsWith('.gif') || t.trim().startsWith('.webp'),
+  );
+  // Auto-enable camera button on touch devices when image upload is permitted, unless explicitly disabled.
+  const isTouchDevice = typeof navigator !== 'undefined' && (navigator.maxTouchPoints > 0 || /Mobi|Android/i.test(navigator.userAgent));
+  const cameraEnabled = captureMode === false ? false : (captureMode ?? (acceptsImages && isTouchDevice ? 'environment' : null));
+  const [isDragOver, setIsDragOver] = useState(false);
+
+  const files = value ? (Array.isArray(value) ? value : [value]) : [];
+  const { processFiles, errors, uploading, uploadProgress } = useFileUploads({
+    files, multiple, maxSize, onChange,
+  });
+
   const handleDragOver = useCallback((e: React.DragEvent) => {
     e.preventDefault();
     e.stopPropagation();
@@ -301,3 +322,124 @@ export function FileField({ value, onChange, field, readonly, ...props }: FieldW
     </div>
   );
 }
+
+/**
+ * FileCell — compact upload control for a line-item grid cell (objectui#2360).
+ *
+ * Same value shape and upload pipeline as {@link FileField}, sized for a 32px
+ * grid row: existing files render as removable chips (image thumbnail / file
+ * icon + name) and a small button opens the native file picker. No
+ * drag-and-drop zone — a grid cell has no room for one; the per-row expand
+ * form still offers the full-size FileField.
+ */
+export function FileCell({
+  value,
+  onChange,
+  disabled,
+  multiple,
+  accept,
+  maxSize,
+  'aria-label': ariaLabel,
+  'data-cell': dataCell,
+}: {
+  value: any;
+  onChange: (value: any) => void;
+  disabled?: boolean;
+  multiple?: boolean;
+  /** Comma-joined accept list for the native picker (e.g. `"image/*,.pdf"`). */
+  accept?: string;
+  /** Max file size in bytes (oversize picks are rejected with an inline error). */
+  maxSize?: number;
+  'aria-label'?: string;
+  /** Focus-grid coordinate (see GridField keyboard navigation). */
+  'data-cell'?: string;
+}) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const files = value ? (Array.isArray(value) ? value : [value]) : [];
+  const { processFiles, errors, uploading } = useFileUploads({
+    files, multiple: !!multiple, maxSize, onChange,
+  });
+
+  const removeAt = (index: number) => {
+    if (multiple) {
+      const next = files.filter((_: any, i: number) => i !== index);
+      onChange(next.length > 0 ? next : null);
+    } else {
+      onChange(null);
+    }
+  };
+
+  const isImage = (file: any) => String(file?.mime_type || '').startsWith('image/');
+  const nameOf = (file: any) =>
+    typeof file === 'string' ? file : file?.name || file?.original_name || 'File';
+  const showUpload = !disabled && !uploading && (multiple || files.length === 0);
+
+  return (
+    <div className="flex min-h-8 flex-wrap items-center gap-1 px-1 py-0.5">
+      <input
+        ref={inputRef}
+        type="file"
+        multiple={multiple}
+        accept={accept}
+        onChange={(e) => {
+          processFiles(Array.from(e.target.files || []));
+          e.target.value = ''; // allow re-picking the same file
+        }}
+        className="hidden"
+      />
+      {files.map((file: any, idx: number) => (
+        <span
+          key={idx}
+          className="inline-flex max-w-40 items-center gap-1 rounded border bg-muted/50 px-1 py-0.5 text-xs"
+          title={nameOf(file)}
+          data-testid="file-cell-chip"
+        >
+          {isImage(file) && file.url ? (
+            <img src={file.url} alt={nameOf(file)} className="size-5 shrink-0 rounded object-cover" />
+          ) : (
+            <FileIcon className="size-3 shrink-0 text-muted-foreground" />
+          )}
+          <span className="truncate">{nameOf(file)}</span>
+          {!disabled && (
+            <button
+              type="button"
+              className="shrink-0 rounded p-0.5 text-muted-foreground hover:text-foreground"
+              aria-label={`Remove ${nameOf(file)}`}
+              onClick={() => removeAt(idx)}
+            >
+              <X className="size-3" />
+            </button>
+          )}
+        </span>
+      ))}
+      {uploading && (
+        <span
+          className="inline-flex items-center gap-1 text-xs text-muted-foreground"
+          data-testid="file-cell-uploading"
+        >
+          <Loader2 className="size-3.5 animate-spin" />
+        </span>
+      )}
+      {showUpload && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          className="h-7 gap-1 px-2 text-xs text-muted-foreground hover:text-foreground"
+          onClick={() => inputRef.current?.click()}
+          aria-label={ariaLabel}
+          data-cell={dataCell}
+          disabled={disabled}
+        >
+          <Upload className="size-3.5" />
+          {files.length === 0 && 'Upload'}
+        </Button>
+      )}
+      {errors.length > 0 && (
+        <span className="w-full truncate text-[11px] text-destructive" title={errors.join('; ')}>
+          {errors[0]}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/widgets/GridField.test.tsx

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
 import React from 'react';
+import { UploadProvider } from '@object-ui/providers';
 import { GridField, LineItemsField, sumColumn, lookupAutofillPatch } from './GridField';
 
 const columns = [
@@ -258,6 +259,88 @@ describe('GridField / LineItemsField — editable line items', () => {
     });
   });
 
+  describe('file columns (upload in a grid cell — #2360)', () => {
+    const fileField = {
+      columns: [
+        { field: 'description', label: 'Description', type: 'text' as const },
+        { field: 'receipt', label: 'Receipt', type: 'file' as const },
+      ],
+    } as any;
+
+    it('renders a real upload control in the cell, not a text input', () => {
+      render(<GridField value={[{ description: 'Taxi', receipt: null }]} onChange={() => {}} field={fileField} />);
+      // One upload button per row (data row + ghost), backed by a native file input.
+      expect(screen.getAllByRole('button', { name: 'Receipt' }).length).toBeGreaterThan(0);
+      expect(document.querySelector('input[type="file"]')).toBeTruthy();
+      expect(screen.queryByRole('textbox', { name: 'Receipt' })).toBeNull();
+    });
+
+    it('uploads a picked file and writes the file object into the row', async () => {
+      const onChange = vi.fn();
+      const adapter = {
+        name: 'test',
+        upload: async (f: File) => ({ url: 'https://cdn/receipt.png', name: f.name, size: f.size, mimeType: f.type }),
+      };
+      render(
+        <UploadProvider adapter={adapter as any}>
+          <GridField value={[{ description: 'Taxi', receipt: null }]} onChange={onChange} field={fileField} />
+        </UploadProvider>,
+      );
+      const file = new File(['x'], 'receipt.png', { type: 'image/png' });
+      const input = document.querySelectorAll('input[type="file"]')[0] as HTMLInputElement;
+      fireEvent.change(input, { target: { files: [file] } });
+      await waitFor(() => expect(onChange).toHaveBeenCalled());
+      expect(onChange).toHaveBeenCalledWith([
+        {
+          description: 'Taxi',
+          receipt: {
+            name: 'receipt.png',
+            original_name: 'receipt.png',
+            size: file.size,
+            mime_type: 'image/png',
+            url: 'https://cdn/receipt.png',
+          },
+        },
+      ]);
+    });
+
+    it('shows an uploaded file as a removable chip', () => {
+      const onChange = vi.fn();
+      render(
+        <GridField
+          value={[{ description: 'Taxi', receipt: { name: 'receipt.png', mime_type: 'image/png' } }]}
+          onChange={onChange}
+          field={fileField}
+        />,
+      );
+      expect(screen.getByText('receipt.png')).toBeTruthy();
+      fireEvent.click(screen.getByLabelText('Remove receipt.png'));
+      expect(onChange).toHaveBeenCalledWith([{ description: 'Taxi', receipt: null }]);
+    });
+
+    it('passes the column accept list to the native picker', () => {
+      const withAccept = {
+        columns: [{ field: 'receipt', label: 'Receipt', type: 'file' as const, accept: ['image/*', '.pdf'] }],
+      } as any;
+      render(<GridField value={[]} onChange={() => {}} field={withAccept} />);
+      const input = document.querySelector('input[type="file"]') as HTMLInputElement;
+      expect(input.getAttribute('accept')).toBe('image/*,.pdf');
+    });
+
+    it('renders the file name read-only in readonly mode', () => {
+      render(
+        <GridField
+          value={[{ description: 'Taxi', receipt: { name: 'receipt.png' } }]}
+          onChange={() => {}}
+          field={fileField}
+          readonly
+        />,
+      );
+      expect(screen.getByText('receipt.png')).toBeTruthy();
+      expect(document.querySelector('input[type="file"]')).toBeNull();
+    });
+  });
+
   it('sumColumn ignores blanks and NaN', () => {
     expect(sumColumn([{ amount: 1 }, { amount: 2 }, { amount: null }], 'amount')).toBe(3);
   });

package/src/widgets/GridField.tsx

@@ -18,6 +18,7 @@ import {
 import { Plus, Trash2, SlidersHorizontal, Maximize2, Copy, GripVertical } from 'lucide-react';
 import { resolveFieldRuleState } from '@object-ui/core';
 import { LookupField } from './LookupField';
+import { FileCell } from './FileField';
 
 /**
  * GridField / LineItemsField — editable child-grid ("line items") widget.
@@ -30,7 +31,7 @@ import { LookupField } from './LookupField';
  *
  * Column config (a subset of `GridColumnDefinition`):
  *   { field, label?, type?, options?, width?, required?, prefix?, step? }
- *   type ∈ 'text' | 'number' | 'currency' | 'date' | 'select'
+ *   type ∈ 'text' | 'number' | 'currency' | 'date' | 'select' | 'lookup' | 'file'
  *
  * Field-level config (from `GridFieldMetadata`):
  *   columns, min_rows, max_rows, allow_add, allow_delete, total_field
@@ -39,7 +40,7 @@ import { LookupField } from './LookupField';
 export interface GridColumn {
   field: string;
   label?: string;
-  type?: 'text' | 'number' | 'currency' | 'date' | 'select' | 'lookup';
+  type?: 'text' | 'number' | 'currency' | 'date' | 'select' | 'lookup' | 'file';
   options?: Array<{ label: string; value: string }>;
   width?: number;
   required?: boolean;
@@ -49,7 +50,11 @@ export interface GridColumn {
   reference?: string;
   displayField?: string;
   idField?: string;
+  /** Multi-value column: multi-record lookup, or multi-file upload cell. */
   multiple?: boolean;
+  /** For `type: 'file'` — accepted MIME types / extensions for the picker
+   *  (e.g. `['image/*', '.pdf']`). Omit to accept anything. */
+  accept?: string[];
   /**
    * Hidden from the grid by default but revealable via the column chooser.
    * Set by `deriveColumns` for fields beyond the default-visible budget — the
@@ -105,6 +110,7 @@ const MIN_WIDTH_BY_TYPE: Record<string, number> = {
   number: 104,
   currency: 116,
   date: 150,
+  file: 168,
 };
 const minWidthFor = (c: GridColumn): number => c.width ?? MIN_WIDTH_BY_TYPE[c.type ?? 'text'] ?? 132;
 
@@ -252,6 +258,13 @@ export function computeRow(columns: GridColumn[], row: Row): Row {
  *  currency/number → formatted, empty → em dash). Lookups render separately. */
 function displayText(c: GridColumn, value: any): string {
   if (value === null || value === undefined || value === '') return '—';
+  if (c.type === 'file') {
+    const files = Array.isArray(value) ? value : [value];
+    if (files.length === 0) return '—';
+    if (files.length > 1) return `${files.length} files`;
+    const f = files[0];
+    return typeof f === 'string' ? f : f?.name || f?.original_name || 'File';
+  }
   if (c.type === 'select' && Array.isArray(c.options)) {
     const opt = c.options.find((o) => String(o.value) === String(value));
     return opt ? opt.label : String(value);
@@ -613,6 +626,8 @@ export function GridField({
                           readonly
                           field={{ reference: c.reference, display_field: c.displayField, id_field: c.idField } as any}
                         />
+                      ) : c.type === 'file' ? (
+                        displayText(c, row[c.field])
                       ) : row[c.field] != null && row[c.field] !== '' ? (
                         String(row[c.field])
                       ) : (
@@ -700,6 +715,21 @@ export function GridField({
         />
       );
     }
+    // File / image column → a real upload control in the cell (objectui#2360),
+    // not a text input: chips for uploaded files + a compact picker button.
+    if (c.type === 'file') {
+      return (
+        <FileCell
+          value={val}
+          onChange={(v: any) => setCellValue(rowIdx, c.field, v)}
+          multiple={c.multiple}
+          accept={Array.isArray(c.accept) && c.accept.length > 0 ? c.accept.join(',') : undefined}
+          disabled={locked}
+          aria-label={c.label || c.field}
+          data-cell={`${rowIdx}-${colIdx}`}
+        />
+      );
+    }
     if (c.type === 'select') {
       return (
         <Select value={val != null ? String(val) : ''} onValueChange={(v) => setCell(rowIdx, c, v)} disabled={locked}>

package/src/widgets/LookupField.tsx

@@ -544,6 +544,16 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
     [idField],
   );
 
+  // Level-2 pickers (PeoplePicker / RecordPickerDialog) operate on bare ids —
+  // their seed queries and selected-row matching compare against `idField`
+  // values. Collapse any `$expand`-ed record objects (passed through
+  // uncollapsed by the inline editor, objectui#2572) before handing the value
+  // down, or the seed fetch would query for a bogus object-shaped id.
+  const pickerValue = useMemo(
+    () => (multiple ? (Array.isArray(value) ? value.map(normalizeId) : []) : normalizeId(value)),
+    [multiple, value, normalizeId],
+  );
+
   // Resolve a raw field value into its display option. An expanded-reference
   // object is mapped directly (mirroring the read cell's display-name path) so
   // the inline editor shows the record's name instead of the placeholder; a bare
@@ -914,7 +924,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
           subtitleFields={subtitleFields}
           avatarField={avatarField}
           pageSize={lookupPageSize}
-          value={value}
+          value={pickerValue}
           onSelect={onChange}
           onSelectRecords={handlePickerSelectRecords}
           lookupFilters={lookupFilters}
@@ -1135,7 +1145,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
           titleFormat={refTitleFormat}
           idField={idField}
           pageSize={lookupPageSize}
-          value={value}
+          value={pickerValue}
           onSelect={onChange}
           onSelectRecords={handlePickerSelectRecords}
           lookupFilters={lookupFilters}

package/src/widgets/NumberField.tsx

@@ -14,8 +14,16 @@ export function NumberField({ value, onChange, field, readonly, ...props }: Fiel
 
   const numberField = (field || (props as any).schema) as NumberFieldMetadata;
   // Step follows `scale` (decimal places), not `precision` (total digit count):
-  // a decimal(10, 0) column has 0 decimal places, so the input should step by 1.
+  // a decimal(10, 0) column has 0 decimal places, so the input should step by 1
+  // (`scale: 0` is a valid declaration — hence the typeof check, not truthiness).
+  // An explicit `step` in the metadata wins over the derived one.
   const scale = numberField?.scale;
+  const step =
+    typeof numberField?.step === 'number'
+      ? numberField.step
+      : typeof scale === 'number'
+        ? Math.pow(10, -scale)
+        : 'any';
 
   // Filter out non-DOM props
   const { inputType, ...domProps } = props as any;
@@ -31,7 +39,11 @@ export function NumberField({ value, onChange, field, readonly, ...props }: Fiel
       }}
       placeholder={numberField?.placeholder}
       disabled={readonly || domProps.disabled}
-      step={scale ? Math.pow(10, -scale) : 'any'}
+      // Surface the field's declared range so the browser's spinner/keyboard
+      // affordances respect it (server-side validation still owns enforcement).
+      min={typeof numberField?.min === 'number' ? numberField.min : undefined}
+      max={typeof numberField?.max === 'number' ? numberField.max : undefined}
+      step={step}
     />
   );
 }

package/src/widgets/PeoplePicker.test.tsx

@@ -179,6 +179,12 @@ describe('PeoplePicker', () => {
     await waitFor(() => expect(screen.getByText('Amy Lin')).toBeTruthy());
     const search = screen.getByTestId('people-picker-search');
     fireEvent.keyDown(search, { key: 'ArrowDown' });
+    // Wait for the cursor to actually land on the first row before committing —
+    // guards against a late background re-render swallowing the keypress (the
+    // old identity-keyed cursor reset made this flaky on slow CI).
+    await waitFor(() =>
+      expect(screen.getAllByTestId('person-row')[0].getAttribute('data-active')).toBe('true'),
+    );
     fireEvent.keyDown(search, { key: 'Enter' });
     expect(onSelect).toHaveBeenCalledWith('u1');
   });

package/src/widgets/PeoplePicker.tsx

@@ -311,10 +311,19 @@ export function PeoplePicker({
 
   // --- keyboard cursor ---
   const [activeIndex, setActiveIndex] = useState(-1);
-  // Reset the cursor when the query changes (results replaced).
+  // Reset the cursor when the query results are actually *replaced* — keyed on
+  // the record-id signature, not the array identity. A background refetch that
+  // returns the same records (StrictMode double-effect, refetch-on-focus)
+  // re-emits a new array; resetting on identity alone yanked the cursor to -1
+  // mid-navigation (flaky ArrowDown→Enter, and a real UX nit).
+  const recordsSignature = useMemo(
+    () => query.records.map(r => String(getPersonId(r, idField))).join(''),
+    [query.records, idField],
+  );
   useEffect(() => {
     setActiveIndex(-1);
-  }, [query.search, query.records]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [query.search, recordsSignature]);
   // Keep it in range if the list shrinks.
   useEffect(() => {
     setActiveIndex(i => (i >= navList.length ? navList.length - 1 : i));

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

@@ -102,14 +102,14 @@ describe('SelectField — role / context gating (#2284)', () => {
     type: 'select',
     options: [
       { label: 'Standard', value: 'standard' },
-      { label: 'Admin only', value: 'admin_only', visibleWhen: "'admin' in current_user.roles" },
+      { 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: { roles: ['sales'] } }}>
+      <PredicateScopeProvider scope={{ current_user: { positions: ['sales'] } }}>
         <SelectField
           value={'admin_only'}
           onChange={onChange}
@@ -124,7 +124,7 @@ describe('SelectField — role / context gating (#2284)', () => {
   it('keeps an admin-only value for an admin', () => {
     const onChange = vi.fn();
     render(
-      <PredicateScopeProvider scope={{ current_user: { roles: ['admin'] } }}>
+      <PredicateScopeProvider scope={{ current_user: { positions: ['admin'] } }}>
         <SelectField
           value={'admin_only'}
           onChange={onChange}

package/src/widgets/SelectField.tsx

@@ -24,7 +24,7 @@ import { FieldWidgetProps } from './types';
  * Supports cascading / role-gated options (#2284): each option may carry a
  * `visibleWhen` CEL predicate, evaluated against the live form record +
  * `current_user`, so the offered set narrows as a controlling field changes
- * (`record.country == 'cn'`) or by role (`'admin' in current_user.roles`). A
+ * (`record.country == 'cn'`) or by role (`'admin' in current_user.positions`). A
  * field declares which sibling fields drive its list via `dependsOn`; while any
  * of those is empty the control is gated with a "select the parent first" hint,
  * mirroring the dependent-lookup UX.