@object-ui/fields 16.0.0 → 16.1.0

package/dist/widgets/CheckboxesField.d.ts

@@ -4,5 +4,12 @@ import { FieldWidgetProps } from './types';
  * CheckboxesField - select zero or more values from a fixed option set, rendered
  * as a list of checkboxes. The stored value is a string[]. Used for the
  * `checkboxes` field type.
+ *
+ * Options support the same per-option `visibleWhen` cascading + `dependsOn`
+ * gating as `MultiSelectField` (ADR-0058 / #2715), resolved through the shared
+ * {@link useCascadingOptions} hook: the offered boxes 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 pruned from the array.
  */
-export declare function CheckboxesField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string[]>): React.JSX.Element;
+export declare function CheckboxesField({ value, onChange, field, readonly, className, schema, dependentValues, dependsOn: dependsOnProp, emptyHint: _emptyHint, dataSource: _dataSource, ...props }: FieldWidgetProps<string[]>): React.JSX.Element;

package/dist/widgets/FileField.d.ts

@@ -5,7 +5,7 @@ import { FieldWidgetProps } from './types';
  * Supports single and multiple file uploads with configurable accepted file types.
  * L2: File size validation, per-file progress indicators, error messages.
  */
-export declare function FileField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>): React.JSX.Element;
+export declare function FileField({ value, onChange, field, readonly, onUploadingChange, ...props }: FieldWidgetProps<any>): React.JSX.Element;
 /**
  * FileCell — compact upload control for a line-item grid cell (objectui#2360).
  *

package/dist/widgets/ImageField.d.ts

@@ -4,4 +4,4 @@ import { FieldWidgetProps } from './types';
  * ImageField - Image upload widget with preview thumbnails
  * Supports single and multiple image uploads with drag-and-drop and preview display
  */
-export declare function ImageField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>): React.JSX.Element;
+export declare function ImageField({ value, onChange, field, readonly, onUploadingChange, ...props }: FieldWidgetProps<any>): React.JSX.Element;

package/dist/widgets/MultiSelectField.d.ts

@@ -4,6 +4,14 @@ import { FieldWidgetProps } from './types';
  * 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 declare function MultiSelectField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string[]>): React.JSX.Element;
+export declare function MultiSelectField({ value, onChange, field, readonly, className, schema, dependentValues, dependsOn: dependsOnProp, emptyHint: _emptyHint, dataSource: _dataSource, ...props }: FieldWidgetProps<string[]>): React.JSX.Element;

package/dist/widgets/RadioField.d.ts

@@ -4,5 +4,12 @@ import { FieldWidgetProps } from './types';
  * 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 declare function RadioField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string>): React.JSX.Element;
+export declare function RadioField({ value, onChange, field, readonly, className, schema, dependentValues, dependsOn: dependsOnProp, emptyHint: _emptyHint, dataSource: _dataSource, ...props }: FieldWidgetProps<string>): React.JSX.Element;

package/dist/widgets/SelectField.d.ts

@@ -1,14 +1,18 @@
 import { default as React } from 'react';
 import { FieldWidgetProps } from './types';
 /**
- * SelectField - Dropdown selection widget with configurable options.
+ * SelectField - dropdown selection widget.
  *
- * 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.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.
+ * 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 declare function SelectField({ value, onChange, field, readonly, schema, dependentValues, dependsOn: dependsOnProp, emptyHint: _emptyHint, dataSource: _dataSource, ...props }: FieldWidgetProps<string>): React.JSX.Element;
+export declare function SelectField(props: FieldWidgetProps<any>): React.JSX.Element;

package/dist/widgets/deriveLookupColumns.d.ts

@@ -10,6 +10,7 @@ interface ObjectSchemaLike {
         type?: string;
         label?: string;
         hidden?: boolean;
+        system?: boolean;
     }>;
     /**
      * ADR-0085 semantic role: the object's most important fields. The single

package/dist/widgets/types.d.ts

@@ -7,5 +7,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/dist/widgets/useCascadingOptions.d.ts

@@ -0,0 +1,18 @@
+import { CascadingOptions, OptionLike, DependsOnInput } from '@object-ui/core';
+/**
+ * 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 declare function useCascadingOptions<T extends OptionLike>(rawOptions: readonly T[], dependsOn: DependsOnInput, dependentValues: Record<string, unknown> | undefined): CascadingOptionsResult<T>;

package/dist/widgets/useUploadingSignal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function useUploadingSignal(uploading: boolean, onUploadingChange?: (uploading: boolean) => void): void;

package/dist/widgets/useUploadingSignal.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/fields",
-  "version": "16.0.0",
+  "version": "16.1.0",
   "description": "Field renderers and registry for Object UI",
   "license": "MIT",
   "type": "module",
@@ -25,17 +25,17 @@
   ],
   "dependencies": {
     "clsx": "^2.1.1",
-    "lucide-react": "^1.24.0",
+    "lucide-react": "^1.25.0",
     "react-markdown": "^10.1.0",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.6.0",
-    "@object-ui/components": "16.0.0",
-    "@object-ui/core": "16.0.0",
-    "@object-ui/i18n": "16.0.0",
-    "@object-ui/providers": "16.0.0",
-    "@object-ui/react": "16.0.0",
-    "@object-ui/types": "16.0.0"
+    "@object-ui/components": "16.1.0",
+    "@object-ui/core": "16.1.0",
+    "@object-ui/i18n": "16.1.0",
+    "@object-ui/providers": "16.1.0",
+    "@object-ui/react": "16.1.0",
+    "@object-ui/types": "16.1.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -46,7 +46,7 @@
     "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
     "typescript": "^6.0.3",
-    "vite": "^8.1.4",
+    "vite": "^8.1.5",
     "vite-plugin-dts": "^5.0.3"
   },
   "publishConfig": {

package/src/field-type-coverage.test.ts

@@ -27,7 +27,9 @@ const FORM_WIDGET_TYPES = [
   'file', 'image', 'avatar', 'video', 'audio', 'signature',
   'location', 'geolocation', 'address', 'color', 'code', 'json', 'qrcode', 'vector',
   'object', 'composite', 'record', 'repeater',
-  'formula', 'summary', 'auto_number',
+  // `autonumber` is the spec `FieldType` spelling; `auto_number` is the widget
+  // map key. Both must resolve to the AutoNumber widget, not text.
+  'formula', 'summary', 'auto_number', 'autonumber',
 ];
 
 /**

package/src/index.tsx

@@ -277,12 +277,11 @@ function useFieldLabel() {
  * fallback in that case.
  */
 function useFieldTranslate(): ((key: string, params?: Record<string, unknown>) => string) | undefined {
-  try {
-    const { t } = useObjectTranslation();
-    return t as (key: string, params?: Record<string, unknown>) => string;
-  } catch {
-    return undefined;
-  }
+  // useObjectTranslation is provider-safe (optional context read; react-i18next
+  // falls back to the global instance), so it never throws — no try/catch, which
+  // would wrap a hook call and violate rules-of-hooks. Mirrors useFieldLabel.
+  const { t } = useObjectTranslation();
+  return t as (key: string, params?: Record<string, unknown>) => string;
 }
 
 import { TextField } from './widgets/TextField';
@@ -1907,6 +1906,10 @@ export function mapFieldTypeToFormType(fieldType: string): string {
     // Auto-generated/computed fields (typically read-only)
     formula: 'field:formula',
     summary: 'field:summary',
+    // `@objectstack/spec` spells this `autonumber`; the widget map key is
+    // `auto_number`. Map both spellings so a spec-typed field/param doesn't
+    // fall through to the plain text input.
+    autonumber: 'field:auto_number',
     auto_number: 'field:auto_number',
   };
 
@@ -2222,6 +2225,44 @@ const fieldWidgetMap: Record<string, () => Promise<{ default: React.ComponentTyp
  */
 export const FORM_FIELD_TYPES: readonly string[] = Object.freeze(Object.keys(fieldWidgetMap));
 
+/**
+ * Resolve an arbitrary field-type spelling to the widget key the form uses.
+ * A key already present in the widget map resolves to itself; spec aliases
+ * (`toggle`, `json`, `repeater`, `secret`, …) resolve through
+ * {@link mapFieldTypeToFormType}; anything unknown falls back to `text` —
+ * the same fallback the form renderer applies.
+ *
+ * Consumers that render field widgets outside the form (e.g. the app-shell
+ * `ActionParamDialog`) use this + {@link getLazyFieldWidget} so their type
+ * support can never drift behind the form surface (ADR-0059).
+ */
+export function resolveFormWidgetType(fieldType: string): string {
+  if (fieldWidgetMap[fieldType]) return fieldType;
+  const mapped = mapFieldTypeToFormType(fieldType).replace(/^field:/, '');
+  return fieldWidgetMap[mapped] ? mapped : 'text';
+}
+
+/** Cache so each widget type creates one lazy component (and one chunk request). */
+const lazyFieldWidgets = new Map<string, React.ComponentType<any>>();
+
+/**
+ * Lazily-loaded form field widget for a field type. Shares the exact loaders
+ * of {@link fieldWidgetMap} (the same components `registerField` registers for
+ * forms), wrapped in `React.lazy` and cached per type — so a consumer can
+ * render any form-supported field type without eagerly bundling every widget.
+ * Render inside a `<Suspense>` boundary. Unknown types resolve to the `text`
+ * widget via {@link resolveFormWidgetType}.
+ */
+export function getLazyFieldWidget(fieldType: string): React.ComponentType<any> {
+  const key = resolveFormWidgetType(fieldType);
+  let Widget = lazyFieldWidgets.get(key);
+  if (!Widget) {
+    Widget = React.lazy(fieldWidgetMap[key]);
+    lazyFieldWidgets.set(key, Widget);
+  }
+  return Widget;
+}
+
 /**
  * Register a specific field type lazily
  * @param fieldType - The field type to register (e.g., 'text', 'number')

package/src/standard-widgets.test.tsx

@@ -213,6 +213,50 @@ describe('Standard Field Widgets', () => {
       );
       expect(container.textContent).toBe('Option A');
     });
+
+    // A `select` declared `multiple` is a multi-value picker (spec allows
+    // `multiple` on select). SelectField delegates to the chip picker so the
+    // form, inline editor, and ActionParamDialog all get multi-select from the
+    // one `select` widget — no single-select fallback, no per-surface drift.
+    it('renders the multi-value chip picker when field.multiple is set', () => {
+      render(
+        <SelectField
+          value={['a']}
+          onChange={mockOnChange}
+          field={{ ...fieldMock, multiple: true } as any}
+        />
+      );
+      // Chip picker uses toggle buttons (aria-pressed), not a Radix combobox.
+      expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
+      const optionA = screen.getByRole('button', { name: 'Option A' });
+      expect(optionA).toHaveAttribute('aria-pressed', 'true');
+      expect(screen.getByRole('button', { name: 'Option B' })).toHaveAttribute('aria-pressed', 'false');
+    });
+
+    it('multi-select toggles values as an array', () => {
+      render(
+        <SelectField
+          value={['a']}
+          onChange={mockOnChange}
+          field={{ ...fieldMock, multiple: true } as any}
+        />
+      );
+      fireEvent.click(screen.getByRole('button', { name: 'Option B' }));
+      expect(mockOnChange).toHaveBeenCalledWith(['a', 'b']);
+    });
+
+    it('multi-select renders selected values as badges in readonly mode', () => {
+      const { container } = render(
+        <SelectField
+          value={['a', 'b']}
+          onChange={mockOnChange}
+          field={{ ...fieldMock, multiple: true } as any}
+          readonly={true}
+        />
+      );
+      expect(container.textContent).toContain('Option A');
+      expect(container.textContent).toContain('Option B');
+    });
   });
 
   describe('BooleanField', () => {

package/src/widgets/CheckboxesField.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 `checkboxes` options (#2715 follow-up) — parity with
+ * `MultiSelectField` (ADR-0058 / #2284).
+ *
+ * Exercises the observable widget behaviour: the dependency gate (a "select the
+ * parent first" empty-state) and the per-element cascade clear — 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 checkbox list
+ * 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 { CheckboxesField } from './CheckboxesField';
+
+const provinceField = {
+  name: 'provinces',
+  type: 'checkboxes',
+  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('CheckboxesField — dependency gating (#2715)', () => {
+  it('gates with a "select parent first" hint while the controlling field is empty', () => {
+    render(
+      <CheckboxesField
+        value={[]}
+        onChange={vi.fn()}
+        field={provinceField}
+        {...({ name: 'provinces', dependentValues: {} } as any)}
+      />,
+    );
+    const gate = screen.getByTestId('checkboxes-empty-provinces');
+    expect(gate).toHaveTextContent(/select country first/i);
+    // Gated → no checkboxes offered.
+    expect(screen.queryAllByRole('checkbox')).toHaveLength(0);
+  });
+
+  it('unlocks the checkboxes once the controlling field is set', () => {
+    render(
+      <CheckboxesField
+        value={[]}
+        onChange={vi.fn()}
+        field={provinceField}
+        {...({ name: 'provinces', dependentValues: { country: 'cn' } } as any)}
+      />,
+    );
+    expect(screen.queryByTestId('checkboxes-empty-provinces')).not.toBeInTheDocument();
+    // Only the `cn` option is offered.
+    expect(screen.getByRole('checkbox', { name: 'Zhejiang' })).toBeInTheDocument();
+    expect(screen.queryByRole('checkbox', { name: 'California' })).not.toBeInTheDocument();
+  });
+});
+
+describe('CheckboxesField — cascade clear (#2715)', () => {
+  it('drops only the selections the parent change no longer offers', () => {
+    const onChange = vi.fn();
+    render(
+      <CheckboxesField
+        value={['zj', 'ca']}
+        onChange={onChange}
+        field={provinceField}
+        {...({ name: 'provinces', 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(
+      <CheckboxesField
+        value={['zj']}
+        onChange={onChange}
+        field={provinceField}
+        {...({ name: 'provinces', dependentValues: { country: 'cn' } } as any)}
+      />,
+    );
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+describe('CheckboxesField — role / context gating (#2715)', () => {
+  const tierField = {
+    name: 'tiers',
+    type: 'checkboxes',
+    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'] } }}>
+        <CheckboxesField
+          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'] } }}>
+        <CheckboxesField
+          value={['standard', 'admin_only']}
+          onChange={onChange}
+          field={tierField}
+          {...({ name: 'tiers', dependentValues: {} } as any)}
+        />
+      </PredicateScopeProvider>,
+    );
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

package/src/widgets/CheckboxesField.tsx

@@ -1,39 +1,101 @@
-import React, { useId } from 'react';
+import React, { useId, useEffect } from 'react';
 import { Checkbox, Label, EmptyValue, Badge } 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 }
+type Option = OptionLike;
 
 /**
  * CheckboxesField - select zero or more values from a fixed option set, rendered
  * as a list of checkboxes. The stored value is a string[]. Used for the
  * `checkboxes` field type.
+ *
+ * Options support the same per-option `visibleWhen` cascading + `dependsOn`
+ * gating as `MultiSelectField` (ADR-0058 / #2715), resolved through the shared
+ * {@link useCascadingOptions} hook: the offered boxes 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 pruned from the array.
  */
-export function CheckboxesField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string[]>) {
-  const config = (field || (props as any).schema) as any;
-  const options: Option[] = config?.options || [];
+export function CheckboxesField({
+  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 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: prune selected values the offered set no longer includes
+  // (parent changed / predicate flipped), keeping the ones still valid — the
+  // per-element clear the multi-value case needs (cf. the scalar select/radio).
+  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 checkbox list: 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 ? `checkboxes-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, checked: boolean) => {
     const next = checked ? [...selected.filter((x) => x !== v), v] : selected.filter((x) => x !== v);
     onChange(next);
   };
 
   return (
-    <div className={className}>
+    <div
+      className={className}
+      data-testid={fieldName ? `checkboxes-${fieldName}` : undefined}
+    >
       {options.map((opt) => {
         const id = `${groupId}-${opt.value}`;
         return (
@@ -43,6 +105,7 @@ export function CheckboxesField({ value, onChange, field, readonly, className, .
               checked={selected.includes(opt.value)}
               onCheckedChange={(checked) => toggle(opt.value, !!checked)}
               disabled={(props as any).disabled}
+              data-testid={`checkboxes-option-${opt.value}`}
             />
             <Label htmlFor={id} className="font-normal">{opt.label}</Label>
           </div>

package/src/widgets/FileField.tsx

@@ -3,6 +3,7 @@ import { Button, EmptyValue } from '@object-ui/components';
 import { useUpload } from '@object-ui/providers';
 import { Upload, X, File as FileIcon, ImageIcon, Camera, Loader2 } from 'lucide-react';
 import { FieldWidgetProps } from './types';
+import { useUploadingSignal } from './useUploadingSignal';
 
 /**
  * Shared upload pipeline for the file widgets: validates size, uploads through
@@ -49,6 +50,12 @@ function useFileUploads(opts: {
                 setUploadProgress((prev) => ({ ...prev, [file.name]: ratio })),
             });
             return {
+              // `file_id` is the storage id the backend keys attachments by
+              // (the adapter returns it as `meta.fileId`); surfacing it here
+              // lets callers that need the id — e.g. an action param POSTing
+              // `attachments: string[]` — recover it without a second lookup.
+              // Extra key; the record file-field value shape is unchanged.
+              file_id: (result.meta as { fileId?: string } | undefined)?.fileId,
               name: result.name,
               original_name: file.name,
               size: result.size,
@@ -84,7 +91,7 @@ function useFileUploads(opts: {
  * 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>) {
+export function FileField({ value, onChange, field, readonly, onUploadingChange, ...props }: FieldWidgetProps<any>) {
   const inputRef = useRef<HTMLInputElement>(null);
   const cameraRef = useRef<HTMLInputElement>(null);
   const fileField = (field || (props as any).schema) as any;
@@ -111,6 +118,7 @@ export function FileField({ value, onChange, field, readonly, ...props }: FieldW
   const { processFiles, errors, uploading, uploadProgress } = useFileUploads({
     files, multiple, maxSize, onChange,
   });
+  useUploadingSignal(uploading, onUploadingChange);
 
   const handleDragOver = useCallback((e: React.DragEvent) => {
     e.preventDefault();