@object-ui/fields 17.3.0 → 17.5.0

package/src/widgets/RecordPickerDialog.dateLocale.test.tsx

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4272 — the lookup picker's MongoDB `$date` fallback rendered in the
+ * MACHINE's locale.
+ *
+ * `renderCellContent`'s plain-text fallback runs whenever a column has no
+ * usable field descriptor / cell renderer — the shape a string-authored
+ * `lookup_columns` entry against an object with no `fieldsMeta` produces. For
+ * an expanded Mongo value it did:
+ *
+ *     if (val.$date) return new Date(val.$date).toLocaleDateString();
+ *
+ * with no tag at all. `undefined` is not "the user's locale", it is the
+ * machine's — so this cell rendered `8/11/2026` on a `zh` console while every
+ * neighbouring date cell (fixed in PR #4512) rendered `2026/8/11`.
+ *
+ * ── Directions ───────────────────────────────────────────────────────────
+ * Runner machine locale is `en-US`, so the `en` case is GREEN ON BOTH SIDES —
+ * the byte-identical pin, not evidence. The `zh` case goes red against
+ * unfixed code, and so does the precedence case: `de` (`11.8.2026`) differs
+ * from BOTH the machine form and the `zh` form, so it cannot pass by
+ * coincidence.
+ *
+ * This file mounts providers; the pure-function cases for the same card are
+ * kept in `__tests__/date-formatter-residue-4272.test.ts` (objectui#4514).
+ */
+
+import React from 'react';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, waitFor, cleanup } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { I18nProvider, LocalizationProvider } from '@object-ui/i18n';
+import { RecordPickerDialog } from './RecordPickerDialog';
+
+/** The exact expanded-Mongo shape the picker receives from the server. */
+const records = [
+  { id: 'r1', name: 'Northwind', signed_on: { $date: new Date(2026, 7, 11, 0, 0, 0).toISOString() } },
+];
+
+function makeDataSource() {
+  return { find: vi.fn(async () => ({ data: records, total: records.length })) } as any;
+}
+
+/**
+ * A session: the UI language the user picked plus the tenant's regional
+ * default (usually absent). Mirrors `date-locale-channel.test.tsx`'s harness
+ * so both halves of this card describe a session the same way.
+ */
+function renderSession(language: string, tenantLocale?: string) {
+  return render(
+    <I18nProvider
+      config={{ defaultLanguage: language, detectBrowserLanguage: false }}
+      persistLanguage={false}
+    >
+      <LocalizationProvider value={{ locale: tenantLocale }}>
+        <RecordPickerDialog
+          open
+          onOpenChange={() => {}}
+          onSelect={() => {}}
+          dataSource={makeDataSource()}
+          objectName="accounts"
+          // Deliberately no `type` and no `fieldsMeta`/`cellRenderer`: this is
+          // what drives BOTH columns through the plain-text fallback where the
+          // `$date` branch lives. `name` is carried purely as a render anchor —
+          // the picker table shows only the columns it is given, so waiting on
+          // a field that is not a column would wait forever.
+          columns={[
+            { field: 'name', label: 'Name' },
+            { field: 'signed_on', label: 'Signed On' },
+          ]}
+        />
+      </LocalizationProvider>
+    </I18nProvider>,
+  );
+}
+
+/**
+ * The dialog renders through a Radix portal, so its table is NOT inside the
+ * `container` `render()` returns — it is mounted at the document body. Reading
+ * `container.textContent` here would assert against an empty string, which
+ * passes every `not.toContain` for the wrong reason.
+ */
+function bodyText(): string {
+  return document.body.textContent ?? '';
+}
+
+afterEach(() => cleanup());
+
+describe('RecordPickerDialog — the $date fallback follows the display locale (objectui#4272)', () => {
+  it('zh session renders the Chinese date form', async () => {
+    renderSession('zh');
+    await waitFor(() => expect(screen.getByText('Northwind')).toBeInTheDocument());
+    expect(bodyText()).toContain('2026/8/11');
+    expect(bodyText()).not.toContain('8/11/2026');
+  });
+
+  /** PIN — the runner's machine locale is `en-US`, so this is green both sides. */
+  it('en session output is byte-identical (must-not-change)', async () => {
+    renderSession('en');
+    await waitFor(() => expect(screen.getByText('Northwind')).toBeInTheDocument());
+    expect(bodyText()).toContain('8/11/2026');
+  });
+
+  /**
+   * `useDisplayLocale()` puts the TENANT's configured regional default above
+   * the active UI language. `de` is chosen because its form (`11.8.2026`)
+   * matches neither the machine's (`8/11/2026`) nor `zh`'s (`2026/8/11`), so
+   * this case is genuinely red before the fix instead of passing by accident.
+   */
+  it('an explicit tenant locale outranks the active UI language', async () => {
+    renderSession('zh', 'de');
+    await waitFor(() => expect(screen.getByText('Northwind')).toBeInTheDocument());
+    expect(bodyText()).toContain('11.8.2026');
+    expect(bodyText()).not.toContain('2026/8/11');
+    expect(bodyText()).not.toContain('8/11/2026');
+  });
+});

package/src/widgets/RecordPickerDialog.tsx

@@ -38,7 +38,11 @@ import {
   X,
 } from 'lucide-react';
 import type { DataSource, LookupColumnDef, LookupFilterDef } from '@object-ui/types';
-import { useSafeFieldLabel } from '@object-ui/i18n';
+// The repo's single filter sink (`packages/core/src/utils/filter-converter.ts`)
+// — shared with plugin-list's `buildEffectiveFilter` and plugin-view's
+// ObjectView, so a spec `ViewFilterRule[]` lowers in exactly one place.
+import { mergeFilterNodes } from '@object-ui/core';
+import { useSafeFieldLabel, useDisplayLocale } from '@object-ui/i18n';
 import { useFieldTranslation } from './useFieldTranslation';
 import { useRecordQuery } from './useRecordQuery';
 
@@ -360,13 +364,39 @@ export interface RecordPickerDialogProps {
   lookupFilters?: LookupFilterDef[];
 
   /**
-   * Hard filter constraints applied to every query, in QueryParams.$filter
-   * record form. Unlike `lookupFilters`, entries here never surface in the
-   * filter bar and cannot be overridden by user filter input — used for the
-   * dependent (cascading) lookup chain, where the parent field's value MUST
-   * scope the candidate set (#2215).
+   * Hard filter constraint applied to every query. Unlike `lookupFilters`,
+   * entries here never surface in the filter bar and cannot be overridden by
+   * user filter input.
+   *
+   * Two shapes, discriminated STRUCTURALLY (`Array.isArray`), because the two
+   * callers speak two legitimate vocabularies and neither should be bent into
+   * the other:
+   *
+   * - **`QueryParams.$filter` record form** (`{ account: 'a1' }`) — the
+   *   dependent (cascading) lookup chain, where the parent field's value MUST
+   *   scope the candidate set (#2215). Merged by KEY OVERWRITE, so a cascaded
+   *   value REPLACES a stale `lookupFilters` entry on the same field instead of
+   *   intersecting with it. That precedence is load-bearing: an `and` of both
+   *   would ask for `account = 'stale' AND account = 'a1'` and return nothing.
+   * - **A spec `ViewFilterRule[]`** (`[{ field, operator, value? }]`) — an
+   *   author's `record:related_list.add.picker.filter`, handed over VERBATIM
+   *   (#3831). Lowered by `mergeFilterNodes`, the repo's single filter sink, so
+   *   all 19 `VIEW_FILTER_OPERATORS` reach the wire — including the four
+   *   (`before`, `after`, `is_empty`, `is_not_empty`) the record form has no
+   *   `$op` for. No second operator vocabulary is introduced here: two already
+   *   exist (the spec's `AST_OPERATOR_MAP`, data-objectstack's
+   *   `FILTER_OPERATOR_ALIASES`) and #3948 is what a third costs.
+   *
+   * The discriminator is exact rather than heuristic — every AST node is an
+   * ARRAY and a rule is a plain OBJECT, the same predicate `toFilterNode` uses.
+   *
+   * Typed `unknown` rather than `Record< string, any >` on purpose: that type
+   * ACCEPTED a rule array (TypeScript lets an array satisfy a string index of
+   * `any`), the old object-spread merge then flattened it to
+   * `{"0": {...}, "1": {...}}`, and the query filtered on columns literally
+   * named `0`/`1` — type-check green, wrong query, no diagnostic anywhere.
    */
-  baseFilter?: Record<string, any>;
+  baseFilter?: unknown;
 
   /**
    * Cell renderer resolver function.
@@ -466,6 +496,9 @@ export function RecordPickerDialog({
 }: RecordPickerDialogProps) {
   const { t } = useFieldTranslation();
   const { translateOptions } = useSafeFieldLabel();
+  // The one date/number locale resolver: tenant regional default → active UI
+  // language → 'en' (objectui#4272). Read unconditionally at component level.
+  const displayLocale = useDisplayLocale();
 
   // Query state (records/loading/error/total + page/search/sort) lives in the
   // shared useRecordQuery kernel — instantiated after mergedFilter below.
@@ -586,18 +619,34 @@ export function RecordPickerDialog({
     });
   }, [baseFilterColumns, fieldsMeta, objectName, translateOptions]);
 
-  // Merge base lookup_filters with user filter bar values. The hard
-  // `baseFilter` constraint (dependent-lookup chain, #2215) is spread LAST so
-  // user filter-bar input can never widen it back out.
-  const mergedFilter = useMemo<Record<string, any> | undefined>(() => {
+  // Merge base lookup_filters with user filter bar values, then apply the hard
+  // `baseFilter` constraint BY SHAPE (see the prop's own doc for why the two
+  // shapes exist):
+  //
+  //   record form → spread LAST, exactly as this merge has always done, so
+  //                 user filter-bar input can never widen it back out and a
+  //                 cascaded parent value replaces a stale same-field
+  //                 `lookupFilters` entry (#2215).
+  //   rule array  → its OWN `and` child via `mergeFilterNodes`, the shared
+  //                 sink, so a spec `ViewFilterRule[]` lowers losslessly
+  //                 (#3831) instead of being spread into `{0: rule}`.
+  //
+  // When BOTH are in play the record side is still built first and lowered as
+  // one node, so its key-overwrite precedence survives the conjunction.
+  const mergedFilter = useMemo<unknown>(() => {
     const lookupBase = lookupFilters?.length
       ? lookupFiltersToRecord(lookupFilters)
       : {};
     const userFilter = effectiveFilterColumns?.length
       ? filterValuesToRecord(filterValues, effectiveFilterColumns)
       : {};
-    const combined = { ...lookupBase, ...userFilter, ...(baseFilter ?? {}) };
-    return Object.keys(combined).length > 0 ? combined : undefined;
+    const rules = Array.isArray(baseFilter) ? baseFilter : undefined;
+    const recordBase = rules
+      ? undefined
+      : (baseFilter as Record<string, any> | undefined);
+    const combined = { ...lookupBase, ...userFilter, ...(recordBase ?? {}) };
+    const record = Object.keys(combined).length > 0 ? combined : undefined;
+    return rules ? mergeFilterNodes(record, rules) : record;
   }, [lookupFilters, effectiveFilterColumns, filterValues, baseFilter]);
 
   // Shared query kernel: builds params, fetches, and owns records/loading/error/
@@ -814,13 +863,13 @@ export function RecordPickerDialog({
       // Handle MongoDB types / expanded references
       if (val.$numberDecimal) return String(Number(val.$numberDecimal));
       if (val.$oid) return String(val.$oid);
-      if (val.$date) return new Date(val.$date).toLocaleDateString();
+      if (val.$date) return new Date(val.$date).toLocaleDateString(displayLocale);
       if (val.name || val.label) return String(val.name || val.label);
       return JSON.stringify(val);
     }
     if (typeof val === 'boolean') return val ? 'Yes' : 'No';
     return String(val);
-  }, [cellRenderer, titleFormat, displayField, columnFieldDescriptors]);
+  }, [cellRenderer, titleFormat, displayField, columnFieldDescriptors, displayLocale]);
 
   // Render sort indicator for a column
   const renderSortIcon = useCallback((field: string) => {

package/src/widgets/RichTextField.tsx

@@ -133,7 +133,7 @@ export function RichTextField({ value, onChange, field, readonly, error, ...prop
   const hint = t('fields.richText.basicEditorHint', { defaultValue: 'Rich text editor (basic)' });
   const placeholder =
     richField?.placeholder ||
-    t('fields.richText.placeholder', { defaultValue: 'Enter text...' });
+    t('fields.richText.placeholder', { defaultValue: 'Enter text…' });
 
   return (
     <RichTextEditorSurface

package/src/widgets/SelectField.tsx

@@ -21,11 +21,31 @@ import { useCascadingOptions } from './useCascadingOptions';
  *
  * 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.
+ * — the same widget the `multiselect` type uses. Single-value selects keep the
+ * cascading dropdown below.
+ *
+ * The FORM no longer arrives here with `multiple` (objectui#3986):
+ * `mapFieldTypeToFormType` now resolves a `select` + `multiple: true` field to
+ * `field:multiselect`, so the object-form path renders `MultiSelectField`
+ * directly under its own registry id — which is what carries the
+ * `labelling: 'group'` declaration the host label needs. Deciding the widget at
+ * the type-resolution layer is what keeps the declaration and the render from
+ * disagreeing; a delegation invisible to the resolver could not.
+ *
+ * The branch below stays because it is NOT dead — measured entrances that reach
+ * it with `multiple` set, none of which consult that resolver:
+ *
+ *  - **the inline grid editor** — `FieldEditWidget` looks `select` up in its own
+ *    `EDIT_WIDGETS` table, which SHORT-CIRCUITS before the alias map is
+ *    consulted, and forwards the whole metadata object as `field`;
+ *  - **`ActionParamDialog`** — `paramToField` resolves through
+ *    `resolveFormWidgetType`, which likewise returns `select` from
+ *    `fieldWidgetMap` before reaching the alias map, and carries
+ *    `multiple: param.multiple` on the field it builds;
+ *  - **hand-written SDUI** — a `{ type: 'field:select' }` node whose metadata
+ *    declares `multiple`, which addresses this widget by name.
+ *
+ * All three then inherit multi-select from here identically, with no drift.
  *
  * Both branches resolve per-option `visibleWhen` cascading / role-gating through
  * the shared {@link useCascadingOptions} hook (#2715), so single and multi stay
@@ -86,6 +106,17 @@ function SingleSelectField({
   // (parent changed / predicate flipped), drop it so no stale pair persists.
   useEffect(() => {
     if (readonly) return;
+    // Never configured → nothing to prune against; see `MultiSelectField`'s
+    // copy of this guard for the measured failure (objectui#4220). Kept
+    // identical across the four option widgets: an authored list is what the
+    // cascade prunes, and all four render the same `OptionsEmptyState` when
+    // there is none.
+    if (rawOptions.length === 0) return;
+    // Gated → the authored list is withheld until the `dependsOn` parent is
+    // chosen, so the empty offered set is missing information, not a verdict on
+    // the stored value; clearing here fired on mount (objectui#4247). Same
+    // reasoning, at length, in `MultiSelectField`.
+    if (gated) return;
     if (value === undefined || value === null || (value as unknown) === '') return;
     if (!isValueStillOffered(value, options)) onChange?.(undefined as unknown as string);
     // eslint-disable-next-line react-hooks/exhaustive-deps

package/src/widgets/UserField.tsx

@@ -33,8 +33,9 @@ export function UserField(props: FieldWidgetComponentProps<any>) {
   const raw = props.field as any;
 
   // The objectSchema field metadata may live directly on `field`, or nested at
-  // `field.field` when rendered via the createFieldRenderer wrapper — mirror the
-  // unwrap LookupField itself performs.
+  // `field.field` — the form renderer's declared metadata slot (objectui#3090).
+  // Mirror the unwrap LookupField itself performs. (Formerly attributed to the
+  // docs-demo `createFieldRenderer` wrapper, removed in objectui#3910.)
   const metaIsNested = raw?.field && typeof raw.field === 'object'
     && ('reference' in raw.field || 'reference_to' in raw.field || 'type' in raw.field);
   const meta = metaIsNested ? raw.field : raw;

package/src/widgets/__tests__/FilterConditionField.operators.test.ts

@@ -93,14 +93,38 @@ describe('every spec field operator is reachable from the builder (#2942)', () =
     // emits the bare `{ field: value }` shape, never an explicit `$eq`.
     // `$between` stays covered by the `$gte`+`$lte` pair `between` emits
     // (kvToCondition reads that pair back as `between`).
+    //
+    // `$icontains` is a GENUINE GAP, not a modelling nuance, and is excluded
+    // here rather than silently dropped from the vocabulary. `FieldOperatorsSchema`
+    // gained it between @objectstack/spec 17.0.0-rc.2 and rc.5 (it folds ASCII
+    // case, i.e. case-insensitive contains): the server accepts the token, and no
+    // builder operator can author it, so the capability is unreachable from the
+    // filter UI. Closing it needs a new builder operator with a user-visible
+    // label — a new key in all ten locale packs — which is feature work and
+    // deliberately NOT carried by the dependency bump that surfaced it
+    // (objectui#3560). Tracked as objectui#3567; delete this exclusion when it
+    // lands, and the assertion below will hold it honest.
+    const KNOWN_UNREACHABLE = new Set(['$eq', '$between', '$icontains']);
     const unreachable = [...SPEC_OPERATORS].filter(
-      (op) => op !== '$eq' && op !== '$between' && !emitted.has(op),
+      (op) => !KNOWN_UNREACHABLE.has(op) && !emitted.has(op),
     );
     expect(
       unreachable,
       'FieldOperatorsSchema accepts these but no builder operator can author them',
     ).toEqual([]);
   });
+
+  it('every KNOWN_UNREACHABLE token is still a spec operator (the exclusion ratchet)', () => {
+    // A stale exclusion is how a parity test rots into a tautology: if the spec
+    // ever drops one of these, the entry must go too rather than sit there
+    // excusing a token nobody ships. `$eq` / `$between` / `$icontains` are all
+    // real `FieldOperatorsSchema` keys today.
+    for (const op of ['$eq', '$between', '$icontains']) {
+      expect(SPEC_OPERATORS.has(op), `'${op}' is excluded but no longer a spec operator`).toBe(
+        true,
+      );
+    }
+  });
 });
 
 describe('kvToCondition round-trips what condToMongo writes', () => {

package/src/widgets/address-format.ts

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ */
+
+/**
+ * The address value shape, and the ONE formatting rule every address surface
+ * renders it with.
+ *
+ * This module exists because the rule had exactly one implementation and only
+ * one consumer could reach it (objectui#4037). `AddressField`'s readonly branch
+ * collapsed a stored address to a formatted line, while the display (read)
+ * registry the detail page uses mapped `address` straight to `JsonCellRenderer`
+ * — so the same stored value rendered as `Street, City, State ZIP, Country` in
+ * a readonly form and as `{"street":"…","city":"…"}` on the detail page.
+ *
+ * The fix keeps ONE definition rather than a second copy next to the renderer:
+ * a duplicated rule is a rule that drifts, and two spellings of the same
+ * address on two surfaces of one app is the very failure the issue reports.
+ *
+ * Deliberately pure — no React, no component imports — so the eager
+ * `@object-ui/fields` barrel can use it for cell rendering without pulling
+ * `AddressField` (and its inputs) out of the lazily-loaded widget chunk.
+ */
+
+import type { AddressValue } from '@objectstack/spec/data';
+
+/**
+ * Address data structure — `z.input` of `@objectstack/spec`'s
+ * `AddressValueSchema`, which is what the platform stores and what
+ * `/api/v1/data/**` serves back.
+ *
+ * The postal code is spelled `postalCode` (objectstack#5143). `AddressField`
+ * used to read and write `zipCode`, a key that appears nowhere in the spec, so
+ * the stored postal code never reached the input — and whatever the user then
+ * typed into that apparently-empty box was written under a key
+ * `AddressValueSchema` strips: lost outright on a new record, and on an
+ * existing one silently discarded while the stale stored value survived. (A
+ * postal code nobody touched did survive an unrelated edit, because the write
+ * spread the whole stored object through; the issue's account of that half is
+ * corrected in `AddressField.postalCode.test.tsx`.) One name, on both sides:
+ * the contract's.
+ *
+ * IMPORTED rather than declared since objectui#4167. rc.6 publishes
+ * `AddressValue` under this exact name, and the local copy — whose own comment
+ * already claimed to be "the part names of `AddressSchema`" — declared five of
+ * the seven parts. `countryCode` and `formatted` were missing, which is
+ * objectstack#4115's failure class precisely: a canonical CLAIM over a narrower
+ * shape, believed by the next reader. The claim is now the code.
+ *
+ * `AddressField` still renders five inputs and {@link formatAddress} still
+ * composes five parts, and that is a deliberate split rather than an omission:
+ * `formatted` is a derived one-line rendering of the parts (what this module
+ * computes) and `countryCode` is the ISO pair for `country`, neither of which a
+ * human types into a part box. Binding the type does not publish them as
+ * inputs — it stops the type from asserting the platform cannot store them, and
+ * it means a write from the widget no longer looks type-clean while dropping a
+ * key the contract carries: the `{ ...address }` spread in `handleFieldChange`
+ * preserves both, and now says so.
+ *
+ * The declaration moved here (objectui#4037) so the display cell renderer and
+ * the widget share one definition; the SOURCE of that definition is the spec.
+ */
+export type { AddressValue };
+
+/**
+ * The shape written by builds up to and including 17.0.0-rc.1, whose postal
+ * code landed under `zipCode` (objectstack#5143). Read-time compatibility ONLY,
+ * and deliberately not part of {@link AddressValue}: authoring code must not be
+ * able to spell `zipCode`, and nothing here ever writes it back — the first
+ * edit of any part normalizes the record onto `postalCode` (see
+ * `AddressField`'s `handleFieldChange`). This is not a producer alias to be
+ * honoured forever; it exists to carry data THIS widget mis-wrote, and can go
+ * once no such data remains.
+ */
+export type LegacyAddressValue = AddressValue & { zipCode?: string };
+
+/** Postal code of a stored address, preferring the canonical key. */
+export function readPostalCode(addr: AddressValue): string | undefined {
+  return addr.postalCode ?? (addr as LegacyAddressValue).zipCode;
+}
+
+/**
+ * One address part, normalized for joining: absent, non-string and
+ * whitespace-only parts all collapse to `''` so the caller's `filter(Boolean)`
+ * drops them. This is what keeps a partial address free of dangling separators
+ * and of the string `undefined`.
+ */
+function part(value: unknown): string {
+  if (value == null) return '';
+  return String(value).trim();
+}
+
+/**
+ * Formats a stored address as a single line: `Street, City, State ZIP, Country`.
+ *
+ * Ordering and separators are NOT invented here — they are the rule
+ * `AddressField` already applied in its readonly branch, and the sub-field set
+ * its inputs expose (street / city / state / postalCode / country). Missing
+ * parts are dropped rather than spaced over, so a street-only address is
+ * `"中策路 1 号"` and never `", , ,"`.
+ *
+ * Returns `''` when no part is usable — callers decide what an empty address
+ * looks like (an `EmptyValue` placeholder for the cell renderer), and a value
+ * carrying no recognized part at all is NOT silently blanked: see
+ * `AddressCellRenderer`, which falls back to JSON so unknown data stays visible.
+ */
+export function formatAddress(addr: AddressValue): string {
+  // State and postal code share one comma-delimited group, space-separated
+  // inside it ("CA 94102"); either one alone occupies the group by itself.
+  const stateAndPostal = [part(addr.state), part(readPostalCode(addr))]
+    .filter(Boolean)
+    .join(' ');
+  return [part(addr.street), part(addr.city), stateAndPostal, part(addr.country)]
+    .filter(Boolean)
+    .join(', ');
+}

package/src/widgets/file-size-guard.ts

@@ -0,0 +1,55 @@
+/**
+ * The client-side `maxSize` guard shared by the file and image widgets
+ * (objectui#4141).
+ *
+ * Why this is shared rather than mirrored per widget: the guard is the only
+ * thing standing between a declared `maxSize` and a real `presigned → PUT →
+ * complete` round trip, and `paramToField` copies `maxSize` onto the field
+ * config for **every** param type regardless of which widget ends up rendering
+ * it. So a widget that re-derives the check drifts silently — the image param
+ * shipped receiving the constraint and never reading it, while the file param
+ * rejected the identical pick, and nothing failed until QA drove the two side by
+ * side. One exported function makes the difference visible: a widget either
+ * calls it or conspicuously does not.
+ *
+ * Both widgets deliberately share the `fields.file.exceedsMaxSize` key too. The
+ * sentence names a file and a limit and says nothing file-widget-specific, it is
+ * already translated in all 11 built-in locales, and a parallel `fields.image.*`
+ * twin would be the same sentence maintained twice — drifting the moment one
+ * translator rewords one of them.
+ */
+
+/**
+ * Minimal shape of the i18next `t` this module needs, matching the established
+ * `TranslateFn` pattern in `app-shell/src/providers/writeWarningToast`.
+ */
+export type TranslateFn = (key: string, options?: Record<string, unknown>) => string;
+
+/** Divisor for rendering a byte limit as MB, matching the widgets' size display. */
+const BYTES_PER_MB = 1024 * 1024;
+
+/**
+ * The rejection message for a pick that exceeds `maxSize`, or `null` when the
+ * pick is within the limit — so a caller reads it as `if (err) reject`.
+ *
+ * A falsy `maxSize` (undeclared, or an explicit `0`) means **unrestricted**,
+ * preserving the `if (maxSize && …)` semantics the file widget has always
+ * applied: an undeclared limit must never turn into a 0-byte one.
+ *
+ * Takes `name` and `size` separately instead of a `File` because the image
+ * widget's crop path validates a re-encoded `Blob`, which carries no name of its
+ * own — that name comes from the cropper's output.
+ */
+export function maxSizeError(
+  t: TranslateFn,
+  pick: { name: string; size: number },
+  maxSize: number | undefined,
+): string | null {
+  if (!maxSize || pick.size <= maxSize) return null;
+  const maxMB = (maxSize / BYTES_PER_MB).toFixed(1);
+  return t('fields.file.exceedsMaxSize', {
+    defaultValue: `"${pick.name}" exceeds max size (${maxMB} MB)`,
+    name: pick.name,
+    max: maxMB,
+  });
+}

package/src/widgets/nativeDateValue.test.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 { describe, it, expect } from 'vitest';
+import { InstantValueSchema } from '@objectstack/spec/data';
+import {
+  toDateInputValue,
+  toDateTimeInputValue,
+  fromDateTimeInputValue,
+} from './nativeDateValue';
+
+/**
+ * These assertions are deliberately written to hold in EVERY timezone, because
+ * the bug they pin (objectui#3127) is a timezone-shaped one and a test that
+ * only passes in UTC would go green on CI while the defect it guards is live
+ * for every user east or west of it.
+ *
+ * The trick: never hardcode the expected wall clock. Assert the SHAPE the
+ * native control demands, and assert that reading that shape back (as local
+ * time, which is how both the browser and `new Date` read a zone-less
+ * datetime) lands on the same INSTANT we started from.
+ */
+
+const localInstantOf = (bare: string) => new Date(bare).getTime();
+
+describe('toDateInputValue', () => {
+  it('keeps a leading YYYY-MM-DD verbatim, in any timezone', () => {
+    // Re-parsing would read this as UTC midnight and hand back the 16th
+    // anywhere west of Greenwich. The calendar day is the value here.
+    expect(toDateInputValue('2026-06-17')).toBe('2026-06-17');
+    expect(toDateInputValue('2026-06-17T14:30:00.000Z')).toBe('2026-06-17');
+  });
+
+  it('formats a Date to the local calendar day', () => {
+    const d = new Date(2026, 5, 17, 23, 59);
+    expect(toDateInputValue(d)).toBe('2026-06-17');
+  });
+
+  it('maps empty and unparseable input to an empty control', () => {
+    expect(toDateInputValue(null)).toBe('');
+    expect(toDateInputValue(undefined)).toBe('');
+    expect(toDateInputValue('')).toBe('');
+    expect(toDateInputValue('not a date')).toBe('');
+  });
+});
+
+describe('toDateTimeInputValue', () => {
+  it('renders a UTC ISO instant as a local wall clock the control accepts', () => {
+    const iso = '2026-06-17T14:30:00.000Z';
+    const shown = toDateTimeInputValue(iso);
+
+    // 1. The shape `datetime-local` demands — the whole point of #3127.
+    expect(shown).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/);
+    // 2. …denoting the SAME instant the record holds.
+    expect(localInstantOf(shown)).toBe(new Date(iso).getTime());
+  });
+
+  it('truncates an already-local datetime to minutes without re-parsing it', () => {
+    expect(toDateTimeInputValue('2026-06-17T14:30')).toBe('2026-06-17T14:30');
+    expect(toDateTimeInputValue('2026-06-17T14:30:59')).toBe('2026-06-17T14:30');
+    expect(toDateTimeInputValue('2026-06-17T14:30:59.123')).toBe('2026-06-17T14:30');
+  });
+
+  it('maps empty and unparseable input to an empty control', () => {
+    expect(toDateTimeInputValue(null)).toBe('');
+    expect(toDateTimeInputValue(undefined)).toBe('');
+    expect(toDateTimeInputValue('')).toBe('');
+    expect(toDateTimeInputValue('not a date')).toBe('');
+  });
+});
+
+describe('fromDateTimeInputValue', () => {
+  it('reads the control back on the same basis it was written', () => {
+    const local = '2026-06-17T14:30';
+    const stored = fromDateTimeInputValue(local);
+
+    expect(stored).toMatch(/Z$/);
+    expect(new Date(stored).getTime()).toBe(localInstantOf(local));
+  });
+
+  it('round-trips an ISO instant through the control unchanged', () => {
+    // The invariant that makes the read/write pair safe: opening an editor and
+    // re-picking the same minute must not move the record.
+    const iso = '2026-06-17T14:30:00.000Z';
+    expect(fromDateTimeInputValue(toDateTimeInputValue(iso))).toBe(iso);
+  });
+
+  it('returns an unparseable value untouched rather than blanking it', () => {
+    expect(fromDateTimeInputValue('garbage')).toBe('garbage');
+    expect(fromDateTimeInputValue('')).toBe('');
+  });
+
+  /**
+   * The producer side of objectstack#5061. This function's output is not just
+   * "an ISO string" by convention — it IS the platform's `datetime` value
+   * contract, and `ActionParamDialog` now relies on that: it POSTs the widget's
+   * value with no conversion of its own, so a change here that dropped the zone
+   * (or emitted the control's naive wall clock) would make every datetime action
+   * param 400 again. Pinned against the real schema rather than a regex so the
+   * two cannot drift.
+   */
+  it('emits a value the platform datetime contract accepts (InstantValueSchema)', () => {
+    expect(InstantValueSchema.safeParse(fromDateTimeInputValue('2026-06-17T14:30')).success).toBe(true);
+    // The control may include seconds; those must survive into the instant.
+    expect(InstantValueSchema.safeParse(fromDateTimeInputValue('2026-06-17T14:30:45')).success).toBe(true);
+    // The shape the contract rejects — what the control itself hands us, and so
+    // exactly what must NOT come back out of this function.
+    expect(InstantValueSchema.safeParse('2026-06-17T14:30').success).toBe(false);
+  });
+});