@object-ui/fields 17.3.0 → 17.5.0

package/src/widgets/GeolocationField.tsx

@@ -3,6 +3,7 @@ import { Input, Button, Label, EmptyValue } from '@object-ui/components';
 import { MapPin, Crosshair } from 'lucide-react';
 import { FieldWidgetComponentProps } from './types';
 import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
 
 /**
  * Geolocation data structure
@@ -23,7 +24,24 @@ export function GeolocationField({ value, onChange, field, readonly, error, ...p
   // 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);
+  //
+  // `id` and `aria-labelledby` are held back and land on the group CONTAINER
+  // instead (objectui#3961) — they address the whole field, not the latitude box.
+  // The host `id` never reached the DOM before: it was overwritten one line later
+  // by `id={subId('latitude')}` (objectui#3343), leaving the form's group label
+  // pointing at nothing. And `aria-labelledby` on the latitude input would
+  // OVERRIDE its own "Latitude" label with the field name. `aria-describedby` and
+  // the rest stay on the first sub-input, where focus can reach them.
+  const {
+    id: _hostId,
+    'aria-labelledby': _hostLabelledBy,
+    ...domProps
+  } = toDomProps(props);
+  // The pair held back above, in the one spelling every group-labelled widget
+  // uses for it — and computed HERE, before the readonly early return below,
+  // because that return used to drop both keys on the floor: a published label
+  // id with no consumer in the document (objectui#3990). See `toHostGroupProps`.
+  const hostGroupProps = toHostGroupProps(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
@@ -79,9 +97,13 @@ export function GeolocationField({ value, onChange, field, readonly, error, ...p
   };
 
   if (readonly) {
+    // Readonly the composite collapses to the formatted coordinates (plus the
+    // "View on map" link), so THAT row is the surface the host label names
+    // (objectui#3990). The `EmptyValue` placeholder sits inside it, so it needs
+    // nothing of its own.
     const formatted = formatLocation(location);
     return (
-      <div className="flex items-center gap-2">
+      <div {...hostGroupProps} className="flex items-center gap-2">
         <MapPin className="w-4 h-4 text-muted-foreground" />
         {formatted ? <span className="text-sm">{formatted}</span> : <EmptyValue />}
         {location.latitude && location.longitude && (
@@ -100,7 +122,11 @@ export function GeolocationField({ value, onChange, field, readonly, error, ...p
   }
 
   return (
-    <div className="space-y-3">
+    // `role="group"` only when a host actually named this container
+    // (objectui#3961); standalone rendering stays exactly as it was. That
+    // condition now lives in `toHostGroupProps` so this container and the
+    // readonly row above cannot answer differently (objectui#3990).
+    <div className="space-y-3" {...hostGroupProps}>
       <div className="flex items-center gap-2">
         <Button
           type="button"

package/src/widgets/GridField.test.tsx

@@ -113,6 +113,232 @@ describe('GridField / LineItemsField — editable line items', () => {
     expect(onChange).toHaveBeenCalledWith([{ description: 'Taxi', amount: 42.5 }]);
   });
 
+  /**
+   * objectui#3566 — the sub-grid face of #3127. `<input type="date">` accepts
+   * exactly `YYYY-MM-DD` and rejects every other shape SILENTLY: the attribute
+   * still lands in the DOM, so the value looks present in the markup, while
+   * `.value` reads back `''` and the cell paints its empty placeholder. Since
+   * the API hands back `2026-06-17T00:00:00.000Z` for a `date` field, every
+   * date cell in an inline child grid rendered blank on a row that has a value.
+   * Asserting `.value` (never `getAttribute('value')`) is the only way to see
+   * this bug at all.
+   */
+  describe('date columns echo the stored value (#3566)', () => {
+    const dateField = {
+      columns: [
+        { field: 'description', label: 'Description', type: 'text' as const },
+        { field: 'incurred_on', label: 'Incurred On', type: 'date' as const },
+      ],
+    } as any;
+
+    // Both spellings the API may hand back for a `date` field. The bare form
+    // must survive VERBATIM — re-parsing it as UTC midnight and reading local
+    // calendar components back out would move it to the 16th anywhere west of
+    // Greenwich, which is the off-by-one this fix must not introduce.
+    it.each(['2026-06-17', '2026-06-17T00:00:00.000Z'])(
+      'shows the stored calendar day for %s instead of an empty cell',
+      (stored) => {
+        render(
+          <GridField value={[{ description: 'Taxi', incurred_on: stored }]} onChange={() => {}} field={dateField} />,
+        );
+        const cell = screen.getAllByLabelText('Incurred On')[0] as HTMLInputElement;
+        expect(cell.type).toBe('date');
+        expect(cell.value).toBe('2026-06-17');
+      },
+    );
+
+    it('leaves an empty date cell empty', () => {
+      render(<GridField value={[{ description: 'Taxi', incurred_on: null }]} onChange={() => {}} field={dateField} />);
+      expect((screen.getAllByLabelText('Incurred On')[0] as HTMLInputElement).value).toBe('');
+    });
+
+    it('writes back the control\'s own YYYY-MM-DD, unchanged by the read fix', () => {
+      // No paired conversion on the write side: `onChange` hands over exactly
+      // what `<input type="date">` produces, matching DateField's contract. A
+      // conversion here would put read and write on different bases.
+      const onChange = vi.fn();
+      render(
+        <GridField
+          value={[{ description: 'Taxi', incurred_on: '2026-06-17T00:00:00.000Z' }]}
+          onChange={onChange}
+          field={dateField}
+        />,
+      );
+      fireEvent.change(screen.getAllByLabelText('Incurred On')[0], { target: { value: '2026-06-18' } });
+      expect(onChange).toHaveBeenCalledWith([{ description: 'Taxi', incurred_on: '2026-06-18' }]);
+    });
+  });
+
+  /**
+   * objectui#3569 — the type collapse behind #3566's symptom. `datetime` and
+   * `time` used to be mapped onto the ONE `date` column type, so a datetime
+   * cell rendered `<input type="date">`. That is not merely an under-render:
+   * the control emits a bare `YYYY-MM-DD`, so a user who only re-picked the
+   * DAY silently wrote the record's time component out of existence. The
+   * falsifiable claim of these tests is therefore the TIME COMPONENT, not the
+   * control's markup.
+   *
+   * Local-wall-clock expectations are computed here from `Date` rather than
+   * hard-coded, so the suite asserts the same thing in every timezone (and the
+   * day-shift arithmetic is done in LOCAL parts, so it is DST-safe too).
+   */
+  describe('datetime / time columns get their own control (#3569)', () => {
+    const pad2 = (n: number) => String(n).padStart(2, '0');
+    /** The local wall clock an `<input type="datetime-local">` must show for `iso`. */
+    const localInputValue = (iso: string | Date) => {
+      const d = iso instanceof Date ? iso : new Date(iso);
+      return (
+        `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}` +
+        `T${pad2(d.getHours())}:${pad2(d.getMinutes())}`
+      );
+    };
+
+    const temporalField = {
+      columns: [
+        { field: 'merchant', label: 'Merchant', type: 'text' as const },
+        { field: 'incurred_on', label: 'Incurred On', type: 'date' as const },
+        { field: 'incurred_at', label: 'Incurred At', type: 'datetime' as const },
+        { field: 'started_at', label: 'Started At', type: 'time' as const },
+      ],
+    } as any;
+
+    const STORED_ISO = '2026-06-17T14:30:00.000Z';
+
+    it('renders a datetime column as datetime-local, echoing the stored instant', () => {
+      render(
+        <GridField
+          value={[{ merchant: 'Chipotle', incurred_at: STORED_ISO }]}
+          onChange={() => {}}
+          field={temporalField}
+        />,
+      );
+      const cell = screen.getAllByLabelText('Incurred At')[0] as HTMLInputElement;
+      expect(cell.type).toBe('datetime-local');
+      expect(cell.value).toBe(localInputValue(STORED_ISO));
+    });
+
+    it('does NOT collapse the datetime column onto the date control', () => {
+      render(
+        <GridField
+          value={[{ merchant: 'Chipotle', incurred_on: '2026-06-17', incurred_at: STORED_ISO }]}
+          onChange={() => {}}
+          field={temporalField}
+        />,
+      );
+      // The sibling `date` column keeps its own control — the two are distinct
+      // now, which is exactly what was lost before.
+      expect((screen.getAllByLabelText('Incurred On')[0] as HTMLInputElement).type).toBe('date');
+      expect((screen.getAllByLabelText('Incurred At')[0] as HTMLInputElement).type).toBe('datetime-local');
+    });
+
+    /** THE regression: editing only the day must not destroy the time. */
+    it('keeps the time component when only the day is edited', () => {
+      const onChange = vi.fn();
+      render(
+        <GridField
+          value={[{ merchant: 'Chipotle', incurred_at: STORED_ISO }]}
+          onChange={onChange}
+          field={temporalField}
+        />,
+      );
+      const cell = screen.getAllByLabelText('Incurred At')[0] as HTMLInputElement;
+
+      // What a user does to correct a date: move the day forward one, leave
+      // the wall clock alone.
+      const before = new Date(STORED_ISO);
+      const nextDay = new Date(before);
+      nextDay.setDate(nextDay.getDate() + 1);
+      fireEvent.change(cell, { target: { value: localInputValue(nextDay) } });
+
+      const emitted = onChange.mock.calls[0][0][0].incurred_at;
+      const after = new Date(emitted);
+      expect(after.getHours()).toBe(before.getHours());
+      expect(after.getMinutes()).toBe(before.getMinutes());
+      // Round-tripped as ISO-8601 (`fromDateTimeInputValue`), NOT the control's
+      // naive zone-less string — read and write share one basis.
+      expect(emitted).toBe(nextDay.toISOString());
+    });
+
+    it('leaves an empty datetime cell empty', () => {
+      render(
+        <GridField value={[{ merchant: 'Chipotle', incurred_at: null }]} onChange={() => {}} field={temporalField} />,
+      );
+      expect((screen.getAllByLabelText('Incurred At')[0] as HTMLInputElement).value).toBe('');
+    });
+
+    it('renders a time column as a time control and round-trips HH:mm verbatim', () => {
+      const onChange = vi.fn();
+      render(
+        <GridField
+          value={[{ merchant: 'Chipotle', started_at: '14:30' }]}
+          onChange={onChange}
+          field={temporalField}
+        />,
+      );
+      const cell = screen.getAllByLabelText('Started At')[0] as HTMLInputElement;
+      expect(cell.type).toBe('time');
+      expect(cell.value).toBe('14:30');
+      // A `time` value is a zone-less wall clock — stored exactly as typed, the
+      // same contract `TimeField` follows. No conversion in either direction.
+      fireEvent.change(cell, { target: { value: '09:15' } });
+      expect(onChange).toHaveBeenCalledWith([{ merchant: 'Chipotle', started_at: '09:15' }]);
+    });
+
+    /**
+     * The read-only faces the issue calls out: `displayText()` and the
+     * read-only table both fell through to `String(value)`, printing the raw
+     * `2026-06-17T00:00:00.000Z` on screen. Neither could be fixed before the
+     * collapse was undone — with one column type the renderer had no way to
+     * know whether to show a day or a day plus a time.
+     */
+    describe('read-only display formats each temporal type as itself', () => {
+      const row = { merchant: 'Chipotle', incurred_on: '2026-06-17T00:00:00.000Z', incurred_at: STORED_ISO, started_at: '14:30' };
+      // Spelled `'en'` rather than bare `toLocaleDateString()` (objectui#4468):
+      // the bare call reads the MACHINE's locale, so these pins agreed with the
+      // widget only by the accident of a CI runner set to en-US — and they
+      // would have kept agreeing with it after the widget started following the
+      // session locale, which is the bug this suite has to be able to see.
+      // `'en'` is what `useDisplayLocale()` resolves to with no provider.
+      const expectedDay = new Date(2026, 5, 17).toLocaleDateString('en');
+      const dt = new Date(STORED_ISO);
+      const expectedInstant = `${dt.toLocaleDateString('en')} ${dt.toLocaleTimeString('en')}`;
+
+      it('formats date / datetime / time in the read-only table', () => {
+        render(<GridField value={[row]} onChange={() => {}} field={temporalField} readonly />);
+        const table = screen.getByTestId('line-items-readonly');
+        expect(table.textContent).toContain(expectedDay);
+        expect(table.textContent).toContain(expectedInstant);
+        expect(table.textContent).toContain('14:30');
+        // The raw stored ISO must never reach the screen.
+        expect(table.textContent).not.toContain('2026-06-17T00:00:00.000Z');
+        expect(table.textContent).not.toContain(STORED_ISO);
+      });
+
+      it('formats them the same way in list display mode', () => {
+        const { container } = render(
+          <GridField value={[row]} onChange={() => {}} field={temporalField} displayMode="list" onRowExpand={() => {}} />,
+        );
+        expect(container.textContent).toContain(expectedDay);
+        expect(container.textContent).toContain(expectedInstant);
+        expect(container.textContent).not.toContain(STORED_ISO);
+      });
+
+      it('shows a value it cannot parse rather than "Invalid Date"', () => {
+        render(
+          <GridField value={[{ merchant: 'X', incurred_at: 'not-a-date' }]} onChange={() => {}} field={temporalField} readonly />,
+        );
+        expect(screen.getByTestId('line-items-readonly').textContent).toContain('not-a-date');
+      });
+
+      // The `zh` half of this — the sub-grid following the SESSION locale
+      // (objectui#4468) — lives in `__tests__/date-locale-channel.test.tsx`,
+      // not here. Mounting an `I18nProvider` anywhere in THIS file changes what
+      // the provider-less renders further down resolve, and the file-columns
+      // chip test reads a translated `aria-label`; keeping the provider in its
+      // own file keeps that coupling out of the way.
+    });
+  });
+
   describe('trailing ghost row (start-with-one + auto-append)', () => {
     it('renders a trailing empty row so an empty grid still has one input line', () => {
       render(<GridField value={[]} onChange={() => {}} field={field} />);

package/src/widgets/GridField.tsx

@@ -17,8 +17,10 @@ import {
 } from '@object-ui/components';
 import { Plus, Trash2, SlidersHorizontal, Maximize2, Copy, GripVertical } from 'lucide-react';
 import { resolveFieldRuleState } from '@object-ui/core';
+import { useDisplayLocale } from '@object-ui/i18n';
 import { LookupField } from './LookupField';
 import { FileCell } from './FileField';
+import { toDateInputValue, toDateTimeInputValue, fromDateTimeInputValue } from './nativeDateValue';
 
 /**
  * GridField / LineItemsField — editable child-grid ("line items") widget.
@@ -31,7 +33,8 @@ import { FileCell } from './FileField';
  *
  * Column config (a subset of `GridColumnDefinition`):
  *   { field, label?, type?, options?, width?, required?, prefix?, step? }
- *   type ∈ 'text' | 'number' | 'currency' | 'date' | 'select' | 'lookup' | 'file'
+ *   type ∈ 'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time'
+ *        | 'select' | 'lookup' | 'file'
  *
  * Field-level config (from `GridFieldMetadata`):
  *   columns, min_rows, max_rows, allow_add, allow_delete, total_field
@@ -40,7 +43,16 @@ import { FileCell } from './FileField';
 export interface GridColumn {
   field: string;
   label?: string;
-  type?: 'text' | 'number' | 'currency' | 'date' | 'select' | 'lookup' | 'file';
+  /**
+   * Cell control + read/write adapter for the column.
+   *
+   * `date` / `datetime` / `time` are three DISTINCT controls, not one
+   * (objectui#3569). Collapsing `datetime` onto the `date` control did not
+   * merely under-render it — `<input type="date">` hands back a bare
+   * `YYYY-MM-DD` on change, so touching the day of a `datetime` cell silently
+   * DELETED its time component from the record.
+   */
+  type?: 'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file';
   options?: Array<{ label: string; value: string }>;
   width?: number;
   required?: boolean;
@@ -110,6 +122,10 @@ const MIN_WIDTH_BY_TYPE: Record<string, number> = {
   number: 104,
   currency: 116,
   date: 150,
+  // `<input type="datetime-local">` renders a day AND a wall clock, so it needs
+  // materially more room than a date cell before the browser starts eliding.
+  datetime: 200,
+  time: 116,
   file: 168,
 };
 const minWidthFor = (c: GridColumn): number => c.width ?? MIN_WIDTH_BY_TYPE[c.type ?? 'text'] ?? 132;
@@ -254,10 +270,52 @@ export function computeRow(columns: GridColumn[], row: Row): Row {
   return next;
 }
 
+/** True for the three temporal column types, which all need a formatter on the
+ *  read-only surfaces rather than the raw stored string (objectui#3569). */
+const isTemporal = (t?: string) => t === 'date' || t === 'datetime' || t === 'time';
+
+/**
+ * Read-only display text for a temporal cell (objectui#3569).
+ *
+ * The stored shapes differ per type and so must the rendering — which is only
+ * decidable now that `datetime`/`time` are no longer collapsed onto `date`:
+ *
+ * - `date` — a calendar day. Formatted from its VERBATIM `YYYY-MM-DD` parts via
+ *   a local `Date`, never by parsing the stored string: `new Date('2026-06-17')`
+ *   is UTC midnight, so reading local calendar components back out of it moves
+ *   the day to the 16th everywhere west of Greenwich.
+ * - `datetime` — an instant. Rendered as local day + local time, the same basis
+ *   `toDateTimeInputValue` uses for the editor, so the two never disagree (and
+ *   matching `DateTimeField`'s own read-only rendering).
+ * - `time` — a zone-less wall clock (`HH:mm[:ss]`); it is already display-ready.
+ *
+ * An unparseable value falls through to its raw string rather than rendering
+ * "Invalid Date" — showing the user what is actually stored beats hiding it.
+ *
+ * `locale` is threaded rather than left to `Intl`'s default (objectui#4468):
+ * the default is the MACHINE's locale, which has nothing to do with the
+ * session, so a Chinese form rendered `6/17/2026` in its line items.
+ */
+function temporalText(type: string | undefined, value: any, locale: string): string {
+  const raw = String(value);
+  if (type === 'time') return raw;
+  if (type === 'date') {
+    const ymd = toDateInputValue(value);
+    if (!ymd) return raw;
+    const [y, m, d] = ymd.split('-').map(Number);
+    return new Date(y, m - 1, d).toLocaleDateString(locale);
+  }
+  const dt = value instanceof Date ? value : new Date(raw);
+  if (Number.isNaN(dt.getTime())) return raw;
+  return `${dt.toLocaleDateString(locale)} ${dt.toLocaleTimeString(locale)}`;
+}
+
 /** Read-only display text for a cell in list mode (select → option label,
- *  currency/number → formatted, empty → em dash). Lookups render separately. */
-function displayText(c: GridColumn, value: any): string {
+ *  currency/number → formatted, date/datetime/time → localized, empty → em
+ *  dash). Lookups render separately. */
+function displayText(c: GridColumn, value: any, locale: string): string {
   if (value === null || value === undefined || value === '') return '—';
+  if (isTemporal(c.type)) return temporalText(c.type, value, locale);
   if (c.type === 'file') {
     const files = Array.isArray(value) ? value : [value];
     if (files.length === 0) return '—';
@@ -283,6 +341,14 @@ function coerce(type: string | undefined, raw: string): any {
     const n = Number(raw);
     return Number.isNaN(n) ? raw : n;
   }
+  // `<input type="datetime-local">` hands back a ZONE-LESS local wall clock;
+  // storing that verbatim would put the write on a different basis from the
+  // read (`toDateTimeInputValue`), so a user in UTC+8 who picked 08:33 would
+  // store 08:33Z and see 16:33 back. The pair must be used as a pair — this is
+  // the same contract `DateTimeField` follows (objectui#3127 / #3569).
+  // `date` and `time` need no conversion: their controls already emit exactly
+  // the stored shape (`YYYY-MM-DD`, `HH:mm`).
+  if (type === 'datetime') return fromDateTimeInputValue(raw);
   return raw;
 }
 
@@ -328,6 +394,10 @@ export function GridField({
   const allColumns: GridColumn[] = cfg.columns || [];
   const rows: Row[] = Array.isArray(value) ? value : [];
   const contextRecord = props.contextRecord;
+  // The one locale channel every field renderer resolves through: tenant
+  // regional default → active UI language → 'en' (objectui#4468). Read here
+  // and passed down, since `displayText` is a pure helper.
+  const displayLocale = useDisplayLocale();
 
   // Per-cell CEL rule state (B2 in grids). A column with no readonlyWhen/
   // requiredWhen resolves to its static flags (cheap fast-path — no engine
@@ -626,8 +696,13 @@ 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])
+                      ) : c.type === 'file' || isTemporal(c.type) ? (
+                        // A temporal column printed with `String(value)` puts
+                        // the raw stored ISO on screen — `2026-06-17T00:00:00.000Z`
+                        // for a date, and for a datetime it would ALSO have been
+                        // wrong to render as a bare day (objectui#3569). Now that
+                        // the three types are distinct, each formats as itself.
+                        displayText(c, row[c.field], displayLocale)
                       ) : row[c.field] != null && row[c.field] !== '' ? (
                         String(row[c.field])
                       ) : (
@@ -687,7 +762,7 @@ export function GridField({
       }
       return (
         <span className={cn('px-2 text-sm text-foreground', isNumeric(c.type) && 'tabular-nums', (val == null || val === '') && 'text-muted-foreground')}>
-          {displayText(c, val)}
+          {displayText(c, val, displayLocale)}
         </span>
       );
     }
@@ -699,7 +774,7 @@ export function GridField({
           title="Computed"
           data-computed={c.field}
         >
-          {displayText(c, val)}
+          {displayText(c, val, displayLocale)}
         </span>
       );
     }
@@ -757,10 +832,39 @@ export function GridField({
             c.type === 'currency' && 'pl-6',
             isNumeric(c.type) && 'text-right tabular-nums',
           )}
-          type={c.type === 'date' ? 'date' : isNumeric(c.type) ? 'number' : 'text'}
+          type={
+            c.type === 'date'
+              ? 'date'
+              : c.type === 'datetime'
+                ? 'datetime-local'
+                : c.type === 'time'
+                  ? 'time'
+                  : isNumeric(c.type)
+                    ? 'number'
+                    : 'text'
+          }
           step={isNumeric(c.type) ? c.step ?? 'any' : undefined}
           aria-label={c.label || c.field}
-          value={val != null ? String(val) : ''}
+          // A temporal cell holding the API's ISO shape (`2026-06-17T14:30:00.000Z`)
+          // is SILENTLY rejected by the native control — the attribute lands in
+          // the DOM but `input.value` reads back `''` and the cell paints empty
+          // (objectui#3566, the sub-grid face of #3127). So each type reads
+          // through its own adapter:
+          //   date     → `YYYY-MM-DD`; the control writes that shape back
+          //              verbatim, so no paired conversion on `onChange`.
+          //   datetime → `YYYY-MM-DDTHH:mm` local; PAIRED with
+          //              `fromDateTimeInputValue` in `coerce` so read and write
+          //              share one basis (objectui#3569).
+          //   time     → `HH:mm[:ss]` is already the stored shape, both ways.
+          value={
+            c.type === 'date'
+              ? toDateInputValue(val)
+              : c.type === 'datetime'
+                ? toDateTimeInputValue(val)
+                : val != null
+                  ? String(val)
+                  : ''
+          }
           onChange={(e) => setCell(rowIdx, c, e.target.value)}
           disabled={locked}
         />

package/src/widgets/ImageField.maxSize.test.tsx

@@ -0,0 +1,154 @@
+/**
+ * ImageField — a declared `maxSize` is enforced BEFORE any upload starts
+ * (objectui#4141).
+ *
+ * The defect this pins: `paramToField` copies `maxSize` onto the field config
+ * for every param type, so the image widget RECEIVES the constraint — it just
+ * never read it. An oversized pick therefore fired the whole
+ * `presigned → PUT → complete` chain and rendered a preview, while the sibling
+ * file param rejected the same pick with zero uploads.
+ *
+ * So the assertion that matters is **zero upload attempts**, not "no preview":
+ * a widget that uploads the bytes and then hides the thumbnail has still
+ * stored an over-limit file. The spy sits on the `UploadProvider` adapter —
+ * the layer that performs the presigned request — so a call there IS the
+ * network attempt.
+ *
+ * Two upload entry points exist on this widget and both are covered here:
+ *   1. the native picker (`handleFileChange`, single and `multiple`);
+ *   2. the crop dialog's confirm (`handleCropConfirm`), which uploads a
+ *      freshly re-encoded PNG blob — canvas re-encoding can push a crop of an
+ *      in-limit JPEG *over* the limit, so it is a real second door.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { UploadProvider, type UploadAdapter } from '@object-ui/providers';
+import { ImageField } from './ImageField';
+// Imported at module scope (not awaited in a hook) so the widget's
+// `React.lazy(() => import('./ImageCropperDialog'))` resolves from the ESM
+// cache instead of racing RTL's 1000ms `findBy` budget — AGENTS.md §测试纪律.
+import './ImageCropperDialog';
+
+const MB = 1024 * 1024;
+
+/** A File whose reported `size` is the declared one (constructor bytes are not). */
+function imageOfSize(name: string, bytes: number): File {
+  const file = new File(['x'], name, { type: 'image/png' });
+  Object.defineProperty(file, 'size', { value: bytes });
+  return file;
+}
+
+function blobOfSize(bytes: number): Blob {
+  const blob = new Blob(['x'], { type: 'image/png' });
+  Object.defineProperty(blob, 'size', { value: bytes });
+  return blob;
+}
+
+function renderField(field: Record<string, unknown>, value: unknown = undefined) {
+  const upload = vi.fn(async (f: File | Blob) => ({
+    url: 'https://cdn.example/uploaded.png',
+    name: (f as File).name ?? 'cropped.png',
+    size: f.size,
+    mimeType: f.type || 'image/png',
+  }));
+  const adapter: UploadAdapter = { name: 'spy', upload };
+  const onChange = vi.fn();
+  render(
+    <UploadProvider adapter={adapter}>
+      <ImageField field={field as any} value={value} onChange={onChange} />
+    </UploadProvider>,
+  );
+  return { upload, onChange, input: document.querySelector('input[type="file"]') as HTMLInputElement };
+}
+
+describe('ImageField — client-side maxSize guard (#4141)', () => {
+  it('never reaches the upload layer for a pick over the declared maxSize', async () => {
+    const { upload, onChange, input } = renderField({ name: 'p_cover', maxSize: 5 * MB });
+
+    fireEvent.change(input, { target: { files: [imageOfSize('huge.png', 6.3 * MB)] } });
+
+    // The message is the proof the guard ran; the spy is the proof nothing was sent.
+    await screen.findByText(/"huge\.png" exceeds max size \(5\.0 MB\)/);
+    expect(upload).not.toHaveBeenCalled();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('still uploads a pick inside the declared maxSize', async () => {
+    const { upload, onChange, input } = renderField({ name: 'p_cover', maxSize: 5 * MB });
+
+    fireEvent.change(input, { target: { files: [imageOfSize('ok.png', 1 * MB)] } });
+
+    await waitFor(() => expect(onChange).toHaveBeenCalled());
+    expect(upload).toHaveBeenCalledTimes(1);
+    expect(screen.queryByText(/exceeds max size/)).toBeNull();
+  });
+
+  it('uploads unrestricted when the param declares no maxSize', async () => {
+    const { upload, onChange, input } = renderField({ name: 'p_cover' });
+
+    fireEvent.change(input, { target: { files: [imageOfSize('enormous.png', 500 * MB)] } });
+
+    await waitFor(() => expect(onChange).toHaveBeenCalled());
+    expect(upload).toHaveBeenCalledTimes(1);
+    expect(screen.queryByText(/exceeds max size/)).toBeNull();
+  });
+
+  it('rejects only the oversized picks of a multi-select and uploads the rest', async () => {
+    const { upload, onChange, input } = renderField({ name: 'p_gallery', multiple: true, maxSize: 5 * MB });
+
+    fireEvent.change(input, {
+      target: { files: [imageOfSize('small.png', 1 * MB), imageOfSize('huge.png', 6.3 * MB)] },
+    });
+
+    await waitFor(() => expect(onChange).toHaveBeenCalled());
+    expect(upload).toHaveBeenCalledTimes(1);
+    expect((upload.mock.calls[0][0] as File).name).toBe('small.png');
+    expect(screen.getByText(/"huge\.png" exceeds max size \(5\.0 MB\)/)).toBeTruthy();
+  });
+
+  it('guards the crop dialog too — an oversized re-encode is never uploaded', async () => {
+    const existing = { name: 'cover.png', url: 'https://cdn.example/cover.png', mime_type: 'image/png' };
+    const { upload, onChange } = renderField({ name: 'p_cover', maxSize: 5 * MB, crop: true }, existing);
+
+    fireEvent.click(screen.getByTestId('image-field-crop-0'));
+    const confirm = await screen.findByTestId('fake-crop-confirm');
+    fireEvent.click(confirm);
+
+    await screen.findByText(/exceeds max size \(5\.0 MB\)/);
+    expect(upload).not.toHaveBeenCalled();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('still uploads a crop that fits inside the declared maxSize', async () => {
+    const existing = { name: 'cover.png', url: 'https://cdn.example/cover.png', mime_type: 'image/png' };
+    const { upload, onChange } = renderField({ name: 'p_cover', maxSize: 5 * MB, crop: true }, existing);
+
+    fireEvent.click(screen.getByTestId('image-field-crop-0'));
+    fireEvent.click(await screen.findByTestId('fake-crop-confirm-small'));
+
+    await waitFor(() => expect(onChange).toHaveBeenCalled());
+    expect(upload).toHaveBeenCalledTimes(1);
+  });
+});
+
+/**
+ * The real cropper is a canvas + `toBlob` pipeline that happy-dom cannot run;
+ * this stand-in drives the ONE contract ImageField has with it — `onConfirm`
+ * hands back a blob and a name — with a blob size on either side of the limit.
+ */
+vi.mock('./ImageCropperDialog', () => ({
+  ImageCropperDialog: ({ onConfirm }: { onConfirm: (blob: Blob, name: string) => void }) => (
+    <div>
+      <button type="button" data-testid="fake-crop-confirm" onClick={() => onConfirm(blobOfSize(6.3 * MB), 'cover.png')}>
+        confirm big
+      </button>
+      <button
+        type="button"
+        data-testid="fake-crop-confirm-small"
+        onClick={() => onConfirm(blobOfSize(0.5 * MB), 'cover.png')}
+      >
+        confirm small
+      </button>
+    </div>
+  ),
+}));