@object-ui/fields 17.2.0 → 17.3.0

package/src/widgets/FullscreenFieldEditor.tsx

@@ -0,0 +1,271 @@
+/**
+ * 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.
+ */
+
+import React, { useState } from 'react';
+import {
+  cn,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogFooter,
+  Button,
+} from '@object-ui/components';
+import { Maximize2, Check, X } from 'lucide-react';
+import { useFieldTranslation } from './useFieldTranslation';
+
+/**
+ * The fullscreen-edit affordance shared by every long-text widget: the "expand"
+ * button plus the full-height dialog it opens.
+ *
+ * ## Why this is shared rather than copied
+ *
+ * `ObjectFormSchema.mobile.fullscreenLongText` is ONE form-level promise, and
+ * `ObjectForm` projects it onto EVERY long-text field as `mobile_fullscreen`
+ * (`field:textarea` → `TextAreaField`, `field:markdown` / `field:html` →
+ * `RichTextField`). A user who turns the setting on gets one behaviour, so the
+ * behaviour has one implementation. objectui#3301 is what the other
+ * arrangement costs: the flag reached `RichTextField` for as long as the
+ * feature has existed and that widget simply never read it, so half the
+ * documented promise ("textarea/rich-text get an expand button") silently did
+ * nothing. A second hand-written copy of the state machine is the same failure
+ * with an extra step — it drifts, and nothing reports the drift.
+ *
+ * What is genuinely per-widget is the EDITOR, so that is the only thing
+ * injected: `children` renders it against the draft. Everything a user can
+ * observe about the *interaction* — when the affordance appears, that the
+ * dialog seeds from the committed value, that typing stays local until "Done",
+ * that "Cancel" discards — lives here, once.
+ *
+ * ## Draft semantics (unchanged from the original `TextAreaField` behaviour)
+ *
+ * The dialog edits a LOCAL draft seeded from `value` at open time and commits
+ * once, on "Done". It deliberately does not stream every keystroke to the host:
+ * these widgets sit in a react-hook-form field, and per-keystroke `onChange`
+ * during a modal edit would mark the form dirty (and fire validation) for an
+ * edit the user may still cancel. "Cancel" therefore needs no undo — nothing
+ * was written.
+ *
+ * ## `disabled` (objectui#3402)
+ *
+ * The dialog is a SECOND editing surface for the same value, so a field that is
+ * not interactive has to be not interactive here too. It was not: hosts landed
+ * `disabled` on their inline control only, this component never declared the
+ * prop at all, and a disabled long-text field therefore sat correctly greyed out
+ * next to a live expand button — click it, type anything, press "Done", and the
+ * edit went into form state through `onCommit`. Measured on `origin/main`
+ * before the fix: inline `disabled=true`, toggle `disabled=false`, dialog input
+ * `disabled=false`, `onChange` called with "EDITED WHILE DISABLED".
+ *
+ * The gate is shaped like the built-in path's (`FullscreenTextarea` in
+ * `components/src/renderers/form/form.tsx`, objectui#3400/PR #3401), because
+ * one form-level setting must keep producing one behaviour on both paths:
+ *
+ *  - the toggle STAYS but is `disabled` — `disabled` means "not interactive,
+ *    muted", not "shown plainly", which is `readonly`'s job (and `readonly`
+ *    never reaches this component at all — see below);
+ *  - `openFullscreen` refuses independently of the attribute, since a
+ *    programmatic dispatch and a lost `pointer-events` rule both get past it;
+ *  - the dialog locks on its OWN — `disabled` is not merely a static flag, it is
+ *    also the form's `isSubmitting`, which flips to true while the dialog may
+ *    already be open. At that moment the toggle is no longer the gate. So the
+ *    editor is told (third `children` argument) and "Done" is disabled;
+ *  - and `onCommit` is gated, because that is the single point where a value can
+ *    leave this component for host state. Nothing native guards it: it is a
+ *    click handler on a different control reading React state.
+ *
+ * "Cancel" and `Esc` stay live in every state — a dialog that goes disabled
+ * mid-edit must still be closable, or a submit in flight traps the user in it.
+ *
+ * ## Why there is no `readonly` prop
+ *
+ * Both hosts early-return a read-only DISPLAY before they compute the affordance
+ * (`TextAreaField.tsx`, `RichTextField.tsx`), so this component is never
+ * rendered for a read-only field and a `readonly` prop here would be declared
+ * with no producer — the shape this package keeps deleting (objectui#3232/#3233).
+ * A future host that renders an editor for read-only fields must add the prop
+ * AND the producer together; do not add it "for symmetry" beforehand.
+ *
+ * ## `testIdPrefix`
+ *
+ * Each host passes its own (`textarea`, `richtext`), yielding the same
+ * convention with a per-widget namespace: `<prefix>-fullscreen-toggle` /
+ * `-dialog` / `-save`. One form can contain both a textarea and a markdown
+ * field, so a single shared id would make a test unable to say which widget it
+ * had found. The editor's own test id belongs to `children` for the same
+ * reason.
+ *
+ * ## Copy (objectui#3404)
+ *
+ * Every string here goes through `useFieldTranslation()` and consumes the
+ * EXISTING `form.fullscreen.*` / `common.cancel` keys — the same ones the
+ * built-in branch consumes since objectui#3272. Nothing was missing from the
+ * ten locale packs; this path simply never read them, so a zh session opened a
+ * dialog reading `Cancel` / `Done` while a long-text field rendered by the
+ * built-in branch **in the same form** read 「取消 / 完成」.
+ *
+ * Sharing the keys rather than minting `fields.fullscreen.*` twins is the
+ * point: one form-level setting (`mobile.fullscreenLongText`) projects onto
+ * both render paths, so two copies of this copy could only drift.
+ *
+ * `useFieldTranslation` (not bare `useObjectTranslation`) because this widget
+ * is rendered without an `I18nProvider` by standalone/embedded hosts and by
+ * every bare-render test in this package. Measured before the change: with no
+ * provider mounted `useObjectTranslation().t('common.cancel')` returns
+ * `"common.cancel"` — the raw key — and the `{{label}}` interpolation collapses
+ * entirely. The safe hook's English defaults are byte-identical to the literals
+ * they replaced, so the provider-less rendering is unchanged.
+ *
+ * Focus management, `Esc`, the overlay and the close button are Radix's, via
+ * the repo's `Dialog` (`@object-ui/components`) — deliberately not re-answered
+ * here.
+ */
+export interface FullscreenFieldEditorProps {
+  /**
+   * The committed value. Seeds the draft each time the dialog opens — read at
+   * open time, not held, so a value that changes underneath while the dialog is
+   * closed is picked up on the next open.
+   */
+  value: string;
+  /** Called once with the draft when the user confirms. */
+  onCommit: (next: string) => void;
+  /** Field label — the dialog title and part of the toggle's accessible name. */
+  label?: string;
+  /** Namespace for this widget's fullscreen test ids. See above. */
+  testIdPrefix: string;
+  /**
+   * The host field is not interactive (objectui#3402). Disables the toggle, the
+   * "Done" button and the write-back, and is handed to `children` so the host's
+   * own editor renders disabled too. See the `disabled` section above for why
+   * each of those is a separate line rather than belt-and-braces.
+   *
+   * **Producer**: the widget's `disabled` prop, which the form renderer computes
+   * as `disabled || fieldDisabled || isSubmitting || optionGroupGated` and
+   * forwards to registered widgets (`stripRegisteredFieldProps` does not strip
+   * it).
+   */
+  disabled?: boolean;
+  /**
+   * The editor itself, rendered inside the dialog body against the draft. The
+   * host passes the SAME editor it renders inline, so "fullscreen" is a size
+   * change rather than a second, poorer editing surface.
+   *
+   * The third argument is this component's `disabled`, and the host is expected
+   * to put it on the control it renders: only the host knows which element its
+   * editor's disabled state belongs on. Ignoring it is not a write-back hole —
+   * `onCommit` is gated here regardless — but it does leave a control that looks
+   * editable while the field is not, so both in-repo hosts apply it and their
+   * tests pin it.
+   */
+  children: (
+    draft: string,
+    setDraft: (next: string) => void,
+    disabled: boolean,
+  ) => React.ReactNode;
+  /** Optional footer status for the draft (e.g. a character counter). */
+  footer?: (draft: string) => React.ReactNode;
+  /**
+   * Extra classes for the toggle button. It is absolutely positioned by
+   * default and expects a `relative` ancestor; a host whose layout has a
+   * better home for it can re-place it here.
+   */
+  toggleClassName?: string;
+}
+
+export function FullscreenFieldEditor({
+  value,
+  onCommit,
+  label,
+  testIdPrefix,
+  disabled = false,
+  children,
+  footer,
+  toggleClassName,
+}: FullscreenFieldEditorProps) {
+  const { t } = useFieldTranslation();
+  const [open, setOpen] = useState(false);
+  const [draft, setDraft] = useState(value ?? '');
+
+  const openFullscreen = () => {
+    if (disabled) return;
+    setDraft(value ?? '');
+    setOpen(true);
+  };
+  const cancelFullscreen = () => setOpen(false);
+  const commitFullscreen = () => {
+    // THE gate: the one point where a value leaves this component for host
+    // state. `disabled` can flip to true while this dialog is open (it carries
+    // the form's `isSubmitting`), so this is checked here and not only on the
+    // way in. Closing is unconditional — see "Cancel and Esc stay live" above.
+    if (!disabled) onCommit(draft);
+    setOpen(false);
+  };
+
+  return (
+    <>
+      <button
+        type="button"
+        onClick={openFullscreen}
+        disabled={disabled}
+        className={cn(
+          'absolute top-1.5 right-1.5 inline-flex items-center justify-center size-7 rounded-md bg-background/80 text-muted-foreground hover:text-foreground hover:bg-background border shadow-sm transition-colors',
+          'disabled:opacity-50 disabled:pointer-events-none',
+          toggleClassName,
+        )}
+        aria-label={t('form.fullscreen.toggle', {
+          label: label ?? t('form.fullscreen.textFallback'),
+        })}
+        data-testid={`${testIdPrefix}-fullscreen-toggle`}
+      >
+        <Maximize2 className="size-3.5" />
+      </button>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent
+          className="sm:max-w-3xl h-[100dvh] sm:h-[80vh] max-h-[100dvh] sm:max-h-[80vh] flex flex-col p-0 gap-0"
+          data-testid={`${testIdPrefix}-fullscreen-dialog`}
+        >
+          <DialogHeader className="p-4 border-b">
+            <DialogTitle className="text-base">{label ?? t('form.fullscreen.title')}</DialogTitle>
+            {/*
+              Parity with the built-in branch (`form.tsx`), which has carried
+              this sr-only line since #3272. Without it Radix reports no
+              `descriptionPresent` and omits `aria-describedby` altogether, so
+              the registered path's dialog had no accessible description while
+              the identical built-in one did — and `form.fullscreen.description`
+              was a key with no consumer here. (The missing-Description console
+              warning older Radix versions emitted is NOT why: @radix-ui/react-dialog
+              1.1.23 contains no `console.*` call at all, verified before adding this.)
+            */}
+            <DialogDescription className="sr-only">
+              {t('form.fullscreen.description')}
+            </DialogDescription>
+          </DialogHeader>
+          <div className="flex-1 min-h-0 p-4">{children(draft, setDraft, disabled)}</div>
+          <DialogFooter className="p-3 border-t flex-row justify-between sm:justify-end gap-2">
+            {footer?.(draft)}
+            <div className="flex gap-2 ml-auto">
+              <Button type="button" variant="ghost" onClick={cancelFullscreen}>
+                <X className="size-4 mr-1" /> {t('common.cancel')}
+              </Button>
+              <Button
+                type="button"
+                onClick={commitFullscreen}
+                disabled={disabled}
+                data-testid={`${testIdPrefix}-fullscreen-save`}
+              >
+                <Check className="size-4 mr-1" /> {t('form.fullscreen.done')}
+              </Button>
+            </div>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

package/src/widgets/GeolocationField.tsx

@@ -1,7 +1,8 @@
-import React from 'react';
+import React, { useId } from 'react';
 import { Input, Button, Label, EmptyValue } from '@object-ui/components';
 import { MapPin, Crosshair } from 'lucide-react';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 
 /**
  * Geolocation data structure
@@ -16,9 +17,20 @@ export interface GeolocationValue {
  * Geolocation field widget - provides a location picker with coordinates
  * Supports manual entry and browser geolocation API
  */
-export function GeolocationField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<GeolocationValue>) {
+export function GeolocationField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<GeolocationValue>) {
   const [isLoading, setIsLoading] = React.useState(false);
   const location = value || {};
+  // DOM pass-through (objectui#3318): the whitelist spread goes onto the FIRST
+  // sub-input (latitude); the composite's validation state goes onto BOTH
+  // focusable sub-inputs via `aria-invalid={!!error}`.
+  const domProps = toDomProps(props);
+  // Sub-input ids (objectui#3343): `useId()` prefix + sub-field name — the
+  // `groupId` paradigm of RadioField / CheckboxesField. Hardcoded literals
+  // ("latitude" / "longitude") collide as soon as a form renders two
+  // geolocation fields, and every label's htmlFor then resolves to the
+  // FIRST match.
+  const groupId = useId();
+  const subId = (name: keyof GeolocationValue) => `${groupId}-${name}`;
 
   const handleFieldChange = (fieldName: keyof GeolocationValue, fieldValue: string) => {
     onChange({
@@ -115,9 +127,10 @@ export function GeolocationField({ value, onChange, field, readonly, ...props }:
 
       <div className="grid grid-cols-2 gap-3">
         <div>
-          <Label htmlFor="latitude" className="text-xs">Latitude</Label>
+          <Label htmlFor={subId('latitude')} className="text-xs">Latitude</Label>
           <Input
-            id="latitude"
+            {...domProps}
+            id={subId('latitude')}
             type="number"
             value={location.latitude ?? ''}
             onChange={(e) => handleFieldChange('latitude', e.target.value)}
@@ -125,19 +138,21 @@ export function GeolocationField({ value, onChange, field, readonly, ...props }:
             disabled={readonly || props.disabled}
             step="any"
             className={props.className}
+            aria-invalid={!!error}
           />
         </div>
         
         <div>
-          <Label htmlFor="longitude" className="text-xs">Longitude</Label>
+          <Label htmlFor={subId('longitude')} className="text-xs">Longitude</Label>
           <Input
-            id="longitude"
+            id={subId('longitude')}
             type="number"
             value={location.longitude ?? ''}
             onChange={(e) => handleFieldChange('longitude', e.target.value)}
             placeholder="-122.4194"
             disabled={readonly || props.disabled}
             step="any"
+            aria-invalid={!!error}
           />
         </div>
       </div>

package/src/widgets/GeolocationField.uniqueIds.test.tsx

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ */
+
+/**
+ * Unique sub-input ids for the composite `geolocation` widget
+ * (objectui#3343).
+ *
+ * The widget used to hardcode literal ids ("latitude" / "longitude") on its
+ * sub-inputs. Two geolocation fields in one form — e.g. origin + destination
+ * — then produced duplicate DOM ids, and every `Label htmlFor` resolved to
+ * the FIRST match in the document: each sub-label of the second field
+ * clicked/announced the first field's input.
+ *
+ * The fix follows the `groupId` paradigm of RadioField / CheckboxesField:
+ * a `useId()` prefix + the sub-field name. These tests pin it by rendering
+ * TWO instances in one form:
+ *
+ * 1. every `[id]` in the document is globally unique (red again if anyone
+ *    reverts to hardcoded literals — both instances would emit
+ *    id="latitude");
+ * 2. each sub-label of the SECOND instance resolves — via the exact
+ *    mechanism browsers use for label activation, `for` → getElementById —
+ *    to an input inside its OWN instance, and focusing it lands there.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, within } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { GeolocationField } from './GeolocationField';
+
+const field = { name: 'location', type: 'geolocation' } as any;
+
+const SUB_LABELS = ['Latitude', 'Longitude'];
+
+function renderTwoInOneForm() {
+  return render(
+    <form>
+      <div data-testid="geo-a">
+        <GeolocationField value={{}} onChange={vi.fn()} field={field} />
+      </div>
+      <div data-testid="geo-b">
+        <GeolocationField value={{}} onChange={vi.fn()} field={field} />
+      </div>
+    </form>,
+  );
+}
+
+describe('GeolocationField — unique sub-input ids (objectui#3343)', () => {
+  it('two geolocation fields in one form produce globally unique DOM ids', () => {
+    const { baseElement } = renderTwoInOneForm();
+    const ids = Array.from(baseElement.querySelectorAll('[id]')).map((el) => el.id);
+    // 2 sub-inputs per instance — both instances must actually render ids.
+    expect(ids.length).toBeGreaterThanOrEqual(4);
+    const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
+    expect(duplicates).toEqual([]);
+  });
+
+  it("each sub-label of the SECOND field focuses that field's own input", () => {
+    const { getByTestId } = renderTwoInOneForm();
+    const first = getByTestId('geo-a');
+    const second = getByTestId('geo-b');
+
+    for (const text of SUB_LABELS) {
+      const label = within(second).getByText(text);
+      const forId = label.getAttribute('for');
+      expect(forId, `label "${text}" must carry htmlFor`).toBeTruthy();
+
+      // Exactly what the browser does on label click / SR announcement:
+      // resolve `for` against the document.
+      const control = document.getElementById(forId!);
+      expect(control, `htmlFor of "${text}" must resolve`).not.toBeNull();
+      expect(control!.tagName).toBe('INPUT');
+      expect(
+        second.contains(control),
+        `"${text}" must resolve into its OWN field, not the first one`,
+      ).toBe(true);
+      expect(first.contains(control)).toBe(false);
+
+      (control as HTMLInputElement).focus();
+      expect(control).toHaveFocus();
+    }
+  });
+});

package/src/widgets/GridField.tsx

@@ -324,7 +324,7 @@ export function GridField({
    *  the header (`parent.status == 'paid'`). Supplied by MasterDetailForm. */
   contextRecord?: Record<string, unknown>;
 }) {
-  const cfg = (field || (props as any).schema || {}) as any;
+  const cfg = (field || {}) as any;
   const allColumns: GridColumn[] = cfg.columns || [];
   const rows: Row[] = Array.isArray(value) ? value : [];
   const contextRecord = props.contextRecord;

package/src/widgets/ImageField.tsx

@@ -4,6 +4,7 @@ import { useUpload } from '@object-ui/providers';
 import { useObjectTranslation } from '@object-ui/i18n';
 import { X, Image as ImageIcon, Crop as CropIcon, Loader2 } from 'lucide-react';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 import { ImageLightbox } from './ImageLightbox';
 import { useUploadingSignal } from './useUploadingSignal';
 import {
@@ -24,9 +25,9 @@ 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, onUploadingChange, ...props }: FieldWidgetComponentProps<any>) {
+export function ImageField({ value, onChange, field, readonly, onUploadingChange, error, ...props }: FieldWidgetComponentProps<any>) {
   const inputRef = useRef<HTMLInputElement>(null);
-  const imageField = (field || (props as any).schema) as any;
+  const imageField = field as any;
   const multiple = imageField?.multiple || false;
   const accept = imageField?.accept ? imageField.accept.join(',') : 'image/*';
   /**
@@ -212,12 +213,18 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
         )}
         
         <Button
+          // DOM pass-through onto the widget's real focusable control — the
+          // upload button is the keyboard path to the hidden file input
+          // (objectui#3318).
+          {...toDomProps(props)}
           type="button"
           variant="outline"
           onClick={() => inputRef.current?.click()}
           className="w-full"
           disabled={uploading}
           data-testid="image-field-upload-button"
+          // AFTER the spread so this widget's own computation wins (#3222).
+          aria-invalid={!!error}
         >
           {uploading ? (
             <Loader2 className="size-4 mr-2 animate-spin" />

package/src/widgets/LocationField.tsx

@@ -1,13 +1,14 @@
 import React from 'react';
 import { Input, EmptyValue } from '@object-ui/components';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 
 /**
  * LocationField - Geographic coordinate input for latitude and longitude
  * Stores location as { latitude, longitude } object and displays as comma-separated pair
  */
-export function LocationField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<any>) {
-  const config = field || (props as any).schema;
+export function LocationField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<any>) {
+  const config = field;
   // Location is stored as { latitude, longitude } object
   // For display, convert to "latitude, longitude" string format
   const displayValue = value && typeof value === 'object' 
@@ -39,12 +40,18 @@ export function LocationField({ value, onChange, field, readonly, ...props }: Fi
 
   return (
     <Input
+      // DOM pass-through onto the real focusable control (objectui#3318).
+      {...toDomProps(props)}
       type="text"
       value={displayValue}
       onChange={handleChange}
       placeholder={config?.placeholder || 'latitude, longitude'}
       disabled={readonly || props.disabled}
       className={props.className}
+      // AFTER the spread so this widget's own computation wins: `error` is
+      // the published validation slot (#3222), `!!undefined` → explicit
+      // "false".
+      aria-invalid={!!error}
     />
   );
 }

package/src/widgets/LookupField.gateHintLabel.test.tsx

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+
+/**
+ * A gated lookup names its controlling field by LABEL — objectstack#5407.
+ *
+ * The gate sentence (`lookup.selectFirst`) is translated in all ten packs, but
+ * its `{{fields}}` interpolation came straight off `depends_on`, which holds
+ * API names. So the rendered hint was localized around a raw identifier in
+ * every locale, English included:
+ *
+ *     en    Select crm_account first
+ *     zh-CN 请先选择crm_account
+ *
+ * The `en` row is why this is not merely an i18n bug: an English user was shown
+ * an internal identifier. The form renderer knows the label (it already
+ * resolves the same map for the fixed-option widgets' `emptyHint`) and now
+ * hands it over as `dependsOnLabels`.
+ *
+ * All three gated surfaces are asserted — the trigger's visible text, the
+ * trigger's `title`, and the "browse all" button's `title` — because they were
+ * three independent copies of the same expression and a fix applied to one of
+ * them looks identical from the outside.
+ */
+
+import { render, screen, cleanup } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { LookupField } from './LookupField';
+
+/** Mirrors the reported metadata: the parent field's API name IS an object-ish
+ *  name (`crm_account`), which is exactly what made the leak so legible. */
+const gatedField = {
+  name: 'contact',
+  label: 'Contact',
+  reference_to: 'crm_contact',
+  reference_field: 'name',
+  depends_on: ['crm_account'],
+} as any;
+
+const dataSource = { find: vi.fn(async () => ({ data: [], total: 0 })) } as any;
+
+function renderGated(extra: Record<string, unknown>) {
+  return render(
+    <LookupField
+      field={gatedField}
+      value={undefined}
+      onChange={vi.fn()}
+      readonly={false}
+      dataSource={dataSource}
+      {...({ dependentValues: { crm_account: null }, ...extra } as any)}
+    />,
+  );
+}
+
+beforeEach(() => {
+  Object.defineProperty(window, 'innerWidth', { writable: true, configurable: true, value: 1280 });
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    addListener: () => {},
+    removeListener: () => {},
+    dispatchEvent: () => false,
+  })) as any;
+});
+
+afterEach(() => cleanup());
+
+describe('LookupField gate hint names the controlling field (objectstack#5407)', () => {
+  it('interpolates the label the host supplied, not the API name', () => {
+    renderGated({ dependsOnLabels: { crm_account: 'Account' } });
+
+    const trigger = screen.getByTestId('lookup-trigger-gated');
+    expect(trigger).toHaveTextContent('Select Account first');
+    // The identifier must be gone from the copy entirely, not merely
+    // accompanied by the label.
+    expect(trigger).not.toHaveTextContent('crm_account');
+    expect(trigger).toHaveAttribute('title', 'Select Account first');
+  });
+
+  it('labels the gated "browse all" button the same way', () => {
+    renderGated({ dependsOnLabels: { crm_account: 'Account' } });
+
+    const browse = screen.getByTestId('browse-all-records');
+    expect(browse).toBeDisabled();
+    expect(browse).toHaveAttribute('title', 'Select Account first');
+  });
+
+  it('joins several controlling fields by their labels', () => {
+    render(
+      <LookupField
+        field={{ ...gatedField, depends_on: ['crm_account', 'lead_source'] }}
+        value={undefined}
+        onChange={vi.fn()}
+        readonly={false}
+        dataSource={dataSource}
+        {...({
+          dependentValues: { crm_account: null, lead_source: null },
+          dependsOnLabels: { crm_account: 'Account', lead_source: 'Lead Source' },
+        } as any)}
+      />,
+    );
+
+    expect(screen.getByTestId('lookup-trigger-gated')).toHaveTextContent(
+      'Select Account, Lead Source first',
+    );
+  });
+
+  it('falls back to the API name for a field the host did not map', () => {
+    // Standalone use (no host form) has to keep rendering what it rendered
+    // before — the map is an enrichment, not a new requirement. This is also
+    // the assertion that would go red if `dependsOnLabels` were consulted for
+    // its VALUES rather than keyed by field name.
+    renderGated({ dependsOnLabels: { some_other_field: 'Irrelevant' } });
+
+    expect(screen.getByTestId('lookup-trigger-gated')).toHaveTextContent(
+      'Select crm_account first',
+    );
+  });
+
+  it('falls back to the API name when the host passes no map at all', () => {
+    renderGated({});
+
+    expect(screen.getByTestId('lookup-trigger-gated')).toHaveTextContent(
+      'Select crm_account first',
+    );
+  });
+});