@object-ui/fields 16.0.0 → 17.1.0

package/src/widgets/LookupField.tsx

@@ -205,6 +205,12 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   // even when the record wasn't part of the Level 1 popover fetch.
   const [pickerResolvedRecords, setPickerResolvedRecords] = useState<LookupOption[]>([]);
 
+  // Ids whose hydration attempt has FINISHED — found or not — keyed by
+  // String(id). Distinguishes "still loading" from "unresolvable" (deleted
+  // record, fetch failure) so the trigger's hydrating state can't stick
+  // forever on an id that will never resolve (#3108).
+  const [hydrationSettled, setHydrationSettled] = useState<Set<string>>(() => new Set());
+
   // Arrow-key active index (-1 = none)
   const [activeIndex, setActiveIndex] = useState(-1);
   const listRef = useRef<HTMLDivElement>(null);
@@ -476,8 +482,13 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
     (async () => {
       try {
         const fetched: LookupOption[] = [];
-        for (const id of unresolved) {
-          if (typeof (dataSource as any).findOne === 'function') {
+        // Single id: the pre-existing cheap paths — a primary-id `findOne`
+        // GET, or an equality filter when the field commits a different
+        // column (`id_field: 'name'` — e.g. position machine names,
+        // objectstack #3508).
+        if (unresolved.length === 1) {
+          const id = unresolved[0];
+          if (typeof (dataSource as any).findOne === 'function' && idField === 'id') {
             const rec = await (dataSource as any).findOne(referenceTo, id);
             if (rec) fetched.push(recordToOption(rec, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema));
           } else {
@@ -485,9 +496,35 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
               $filter: { [idField]: id },
               $top: 1,
             } as QueryParams);
-            const rows = res?.data ?? res ?? [];
+            const rows = (res as any)?.data ?? res ?? [];
             if (rows[0]) fetched.push(recordToOption(rows[0], displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema));
           }
+        } else {
+          // SEVERAL unresolved ids: one `$in` query per chunk. A multi-value
+          // field can hold dozens of ids, and the old serial findOne-per-id
+          // took seconds while the trigger sat on the empty "Select…"
+          // placeholder (#3108).
+          // Chunked to LOOKUP_PAGE_SIZE so no request exceeds the page size
+          // a server may cap `$top` at; chunks run in parallel.
+          const chunks: any[][] = [];
+          for (let i = 0; i < unresolved.length; i += LOOKUP_PAGE_SIZE) {
+            chunks.push(unresolved.slice(i, i + LOOKUP_PAGE_SIZE));
+          }
+          const results = await Promise.all(
+            chunks.map((chunk) =>
+              dataSource.find(referenceTo, {
+                $filter: { [idField]: { $in: chunk } },
+                $top: chunk.length,
+              } as QueryParams),
+            ),
+          );
+          for (const res of results) {
+            const rows = (res as any)?.data ?? res ?? [];
+            if (!Array.isArray(rows)) continue;
+            for (const row of rows) {
+              fetched.push(recordToOption(row, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema));
+            }
+          }
         }
         if (!cancelled && fetched.length) {
           setPickerResolvedRecords((prev) => {
@@ -498,6 +535,17 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
         }
       } catch {
         // Ignore — chip will fall back to showing the raw id.
+      } finally {
+        // Mark the attempt settled — found or not — so `hydrating` below
+        // clears even for ids that no longer resolve (deleted records,
+        // fetch failures) instead of spinning forever.
+        if (!cancelled) {
+          setHydrationSettled((prev) => {
+            const next = new Set(prev);
+            for (const id of unresolved) next.add(String(id));
+            return next;
+          });
+        }
       }
     })();
     return () => {
@@ -576,6 +624,31 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
     [findOption, findOptionLoose, displayField, idField, effectiveDescriptionField, refTitleFormat, refObjectSchema],
   );
 
+  // A value can hold bare ids that no option list resolves YET — the batch
+  // hydration above is still in flight. While any such id is pending, the
+  // trigger must not present the field as empty: a 41-value lookup rendered
+  // the bare "Select…" placeholder for seconds, indistinguishable from
+  // having no value at all (#3108).
+  const hydrating = useMemo(() => {
+    if (!hasDataSource) return false;
+    const raw: any[] = multiple
+      ? Array.isArray(value) ? value : []
+      : value != null && value !== '' ? [value] : [];
+    return raw.some(
+      (v) =>
+        v != null && v !== '' && typeof v !== 'object' && !parseReferenceObjectString(v) &&
+        !findOption(v) && !findOptionLoose(v) &&
+        !hydrationSettled.has(String(v)),
+    );
+  }, [hasDataSource, multiple, value, findOption, findOptionLoose, hydrationSettled]);
+
+  // Committed-value count. During hydration the resolved-option count
+  // undercounts (unresolved ids are filtered out below), so the trigger
+  // shows this raw count instead.
+  const rawSelectedCount = multiple
+    ? (Array.isArray(value) ? value : []).filter((v) => v != null && v !== '').length
+    : value != null && value !== '' ? 1 : 0;
+
   const selectedOptions = multiple
     ? (Array.isArray(value) ? value : []).map(resolveSelectedOption).filter(Boolean)
     : value ? [resolveSelectedOption(value)].filter(Boolean) : [];
@@ -797,6 +870,17 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
 
   if (readonly) {
     if (!selectedOptions.length) {
+      if (hydrating) {
+        return (
+          <span
+            className="inline-flex items-center gap-1.5 text-sm text-muted-foreground"
+            data-testid="lookup-hydrating"
+          >
+            <Loader2 className="size-3.5 animate-spin" />
+            {multiple ? t('table.selected', { count: rawSelectedCount }) : t('lookup.loading')}
+          </span>
+        );
+      }
       return <EmptyValue />;
     }
 
@@ -842,15 +926,28 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
         ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
         : undefined}
     >
-      <Search className={cn('size-4 shrink-0 text-muted-foreground', compact ? 'mr-1.5' : 'mr-2')} />
+      {hydrating ? (
+        <Loader2
+          className={cn('size-4 shrink-0 animate-spin text-muted-foreground', compact ? 'mr-1.5' : 'mr-2')}
+          data-testid="lookup-hydrating"
+        />
+      ) : (
+        <Search className={cn('size-4 shrink-0 text-muted-foreground', compact ? 'mr-1.5' : 'mr-2')} />
+      )}
       <span className={cn('truncate', compact && selectedOptions.length === 0 && 'text-muted-foreground')}>
         {dependenciesMissing
           ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
-          : compact && !multiple && selectedOptions.length > 0
-            ? singleSelectedLabel
-            : selectedOptions.length === 0
-              ? lookupField?.placeholder || t('common.select')
-              : multiple ? t('table.selected', { count: selectedOptions.length }) : t('common.select')}
+          : hydrating
+            // The value EXISTS but its labels are still loading — say so
+            // instead of the empty placeholder (#3108).
+            ? multiple
+              ? t('table.selected', { count: rawSelectedCount })
+              : t('lookup.loading')
+            : compact && !multiple && selectedOptions.length > 0
+              ? singleSelectedLabel
+              : selectedOptions.length === 0
+                ? lookupField?.placeholder || t('common.select')
+                : multiple ? t('table.selected', { count: selectedOptions.length }) : t('common.select')}
       </span>
     </Button>
   );

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,48 +1,115 @@
-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);
+        // Multi-value fields store string arrays — stringify the (possibly
+        // numeric, #3090-widened) authored value at this boundary.
+        const value = String(opt.value);
+        const active = selected.includes(value);
         return (
           <button
             type="button"
-            key={opt.value}
-            onClick={() => toggle(opt.value)}
+            key={value}
+            onClick={() => toggle(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/ObjectRefField.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { Combobox, EmptyValue, cn } from '@object-ui/components';
 import { SchemaRendererContext } from '@object-ui/react';
 import type { FieldWidgetProps } from './types';
+import { useFieldTranslation } from './useFieldTranslation';
 
 /**
  * ObjectRefField — object-name picker for form fields that store the machine
@@ -33,6 +34,7 @@ export function ObjectRefField({
   ...props
 }: FieldWidgetProps<string>) {
   const ctx = React.useContext(SchemaRendererContext);
+  const { t } = useFieldTranslation();
   const dataSource: any = (props as any).dataSource ?? (ctx as any)?.dataSource ?? null;
   const disabled = (props as any).disabled as boolean | undefined;
 
@@ -94,11 +96,14 @@ export function ObjectRefField({
       options={options}
       value={value ?? ''}
       onValueChange={(v) => onChange(v as any)}
-      placeholder={objects === null ? 'Loading objects…' : 'Select an object'}
-      searchPlaceholder="Search objects…"
-      emptyText={objects === null ? 'Loading…' : 'No objects found'}
+      placeholder={objects === null ? t('fields.objectRef.loading') : t('fields.objectRef.placeholder')}
+      searchPlaceholder={t('fields.objectRef.search')}
+      emptyText={objects === null ? t('common.loading') : t('fields.objectRef.empty')}
       disabled={disabled}
-      className={cn(className)}
+      // Fill the form column like every other input. Combobox's own
+      // `w-[200px]` is a component default that left this control stranded at
+      // a third of the row while `名称` beside it ran full width.
+      className={cn('w-full', className)}
     />
   );
 }

package/src/widgets/PeoplePicker.test.tsx

@@ -189,6 +189,26 @@ describe('PeoplePicker', () => {
     expect(onSelect).toHaveBeenCalledWith('u1');
   });
 
+  it('keyboard: cursor resets when the results are replaced by a search', async () => {
+    // Pins the semantics the render-phase reset must preserve: a NEW result
+    // set does not inherit the previous set's cursor. (The reset moved out of
+    // an effect into the render phase so it can never land AFTER a subsequent
+    // ArrowDown — the CI flake on the test above.)
+    const ds = makeDataSource();
+    render(
+      <PeoplePicker {...baseProps} dataSource={ds} onSelect={vi.fn()} onSelectRecords={vi.fn()} onOpenChange={vi.fn()} />,
+    );
+    await waitFor(() => expect(screen.getByText('Amy Lin')).toBeTruthy());
+    const search = screen.getByTestId('people-picker-search');
+    fireEvent.keyDown(search, { key: 'ArrowDown' });
+    await waitFor(() =>
+      expect(screen.getAllByTestId('person-row')[0].getAttribute('data-active')).toBe('true'),
+    );
+    fireEvent.change(search, { target: { value: 'bob' } });
+    await waitFor(() => expect(screen.getAllByTestId('person-row')).toHaveLength(1));
+    expect(screen.getAllByTestId('person-row')[0].getAttribute('data-active')).not.toBe('true');
+  });
+
   it('keyboard: Backspace on empty search removes the last chip (multi)', async () => {
     const ds = makeDataSource();
     render(

package/src/widgets/PeoplePicker.tsx

@@ -320,10 +320,22 @@ export function PeoplePicker({
     () => query.records.map(r => String(getPersonId(r, idField))).join(''),
     [query.records, idField],
   );
-  useEffect(() => {
+  // The reset runs in the RENDER PHASE (the "adjusting state during render"
+  // pattern), NOT in an effect. An effect flushes asynchronously after the
+  // render that delivered the records — so a reset queued by their arrival
+  // could land AFTER a subsequent ArrowDown and eat the just-set cursor.
+  // That is the residual ArrowDown→Enter flake the signature key above did
+  // not close (CI reproduced it under load), and a real fast-fingers UX bug:
+  // rows appear, the user presses ArrowDown, the highlight vanishes.
+  // Resetting during the same render that shows the new rows makes the
+  // ordering deterministic — by the time the rows are visible, the reset
+  // has already happened.
+  const cursorEpoch = `${query.search}\u0000${recordsSignature}`;
+  const [seenCursorEpoch, setSeenCursorEpoch] = useState(cursorEpoch);
+  if (seenCursorEpoch !== cursorEpoch) {
+    setSeenCursorEpoch(cursorEpoch);
     setActiveIndex(-1);
-    // 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/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();
+  });
+});