@object-ui/fields 17.2.0 → 17.5.0

package/src/widgets/__tests__/TextAreaField.mobileFullscreen.test.tsx

@@ -0,0 +1,175 @@
+/**
+ * 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.
+ */
+
+/**
+ * `TextAreaField`'s fullscreen affordance has ONE source (objectui#3232).
+ *
+ * It used to be read from four places with a `??` chain — a `mobileFullscreen`
+ * (camelCase) prop, `field.mobile_fullscreen`, a `mobile_fullscreen` prop, and
+ * `schema.mobile_fullscreen`. Only the field-metadata flag was ever produced:
+ * `ObjectForm` stamps it on long-text fields from
+ * `ObjectFormSchema.mobile.fullscreenLongText`. The camelCase prop had no
+ * producer anywhere in the repo, and the snake_case prop could not arrive
+ * because `stripRegisteredFieldProps` (components/src/renderers/form/form.tsx)
+ * removes it from what registered widgets are forwarded.
+ *
+ * So this file pins both halves of that convergence:
+ *
+ *  1. **The live path still works.** The metadata flag drives the affordance
+ *     end to end — button, dialog, and the committed edit. Deleting the dead
+ *     reads must not have cost the working behaviour, and this is the test
+ *     that fails if a future refactor drops the real read too.
+ *  2. **The retired prop spellings are gone**, at compile time (they are not
+ *     on the closed `FieldWidgetComponentProps`, objectui#3221) and at runtime
+ *     (a host that passes one anyway gets no affordance). Convergence means a
+ *     misspelled flag is now inert and loud, not silently absorbed.
+ *
+ * Note the built-in (unregistered) `textarea` branch in `form.tsx` reads
+ * `mobile_fullscreen || fullscreen` off the form-field props and renders its
+ * own `FullscreenTextarea`. That is a separate, live path and is untouched
+ * here — this file is about the registered `field:textarea` widget only.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import { TextAreaField } from '../TextAreaField';
+import type { FieldWidgetComponentProps } from '../types';
+import type { FieldMetadata } from '@object-ui/types';
+
+const fieldMeta = (extra: Record<string, unknown> = {}) =>
+  ({
+    name: 'description',
+    label: 'Description',
+    type: 'textarea',
+    ...extra,
+  }) as unknown as FieldMetadata;
+
+describe('TextAreaField mobile fullscreen — the metadata flag is the only source', () => {
+  it('renders the expand affordance when the field metadata sets mobile_fullscreen', () => {
+    render(
+      <TextAreaField
+        value="hello"
+        onChange={() => {}}
+        field={fieldMeta({ mobile_fullscreen: true })}
+      />,
+    );
+
+    expect(screen.getByTestId('textarea-fullscreen-toggle')).toBeInTheDocument();
+  });
+
+  it('opens the fullscreen dialog and commits the edited draft', () => {
+    const onChange = vi.fn();
+    render(
+      <TextAreaField
+        value="hello"
+        onChange={onChange}
+        field={fieldMeta({ mobile_fullscreen: true })}
+      />,
+    );
+
+    // Closed until the affordance is used — the dialog is not just mounted.
+    expect(screen.queryByTestId('textarea-fullscreen-dialog')).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByTestId('textarea-fullscreen-toggle'));
+    expect(screen.getByTestId('textarea-fullscreen-dialog')).toBeInTheDocument();
+
+    const dialogInput = screen.getByTestId('textarea-fullscreen-input');
+    expect(dialogInput).toHaveValue('hello');
+
+    fireEvent.change(dialogInput, { target: { value: 'hello from fullscreen' } });
+    // The draft is local until "Done" — the host is not notified per keystroke.
+    expect(onChange).not.toHaveBeenCalled();
+
+    fireEvent.click(screen.getByTestId('textarea-fullscreen-save'));
+    expect(onChange).toHaveBeenCalledWith('hello from fullscreen');
+  });
+
+  it('no longer reads the flag off a `schema` prop (objectui#3233)', () => {
+    // This used to be the second carrier: `SchemaRenderer` passed the authored
+    // node as `schema` and the widget resolved `field || schema`. v17 converged
+    // that at the producer — the registry adapter (`withFieldCarrier`) maps the
+    // SDUI node onto `field` before any widget sees it, so the widget has one
+    // read. A host that still passes `schema` is now inert AND loud: a compile
+    // error on the closed props type, and no affordance at runtime.
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      const legacyHostProps = {
+        schema: fieldMeta({ mobile_fullscreen: true }),
+      } as unknown as Partial<FieldWidgetComponentProps<string>>;
+
+      render(
+        <TextAreaField
+          value=""
+          onChange={() => {}}
+          field={fieldMeta()}
+          {...legacyHostProps}
+        />,
+      );
+
+      expect(screen.queryByTestId('textarea-fullscreen-toggle')).not.toBeInTheDocument();
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+
+  it('renders no affordance when the metadata does not opt in', () => {
+    render(<TextAreaField value="hello" onChange={() => {}} field={fieldMeta()} />);
+
+    expect(screen.queryByTestId('textarea-fullscreen-toggle')).not.toBeInTheDocument();
+    expect(screen.queryByTestId('textarea-fullscreen-dialog')).not.toBeInTheDocument();
+  });
+});
+
+describe('TextAreaField mobile fullscreen — the retired prop spellings', () => {
+  it('does not declare them on the widget contract', () => {
+    const props = {} as FieldWidgetComponentProps<string>;
+
+    // Both were read by the widget and written by no host. With the closed
+    // props type (objectui#3221) they are now compile errors, so a future
+    // author reaches for the metadata flag instead of a silently ignored prop.
+    // @ts-expect-error `mobileFullscreen` is not part of this contract
+    void props.mobileFullscreen;
+    // @ts-expect-error `mobile_fullscreen` is a metadata key, not a widget prop
+    void props.mobile_fullscreen;
+    // …and the retired second METADATA carrier (objectui#3233). The flag has
+    // one source and that source now has one carrier.
+    // @ts-expect-error `schema` was retired from the widget contract in v17
+    void props.schema;
+
+    expect(true).toBe(true);
+  });
+
+  it('ignores them at runtime when a host passes them anyway', () => {
+    // Untyped hosts (plain JS, `as any` spreads) can still get these onto the
+    // element. They must not resurrect the affordance: the metadata flag is
+    // the contract. Unknown props land on the DOM spread, so React's unknown
+    // -attribute warnings are expected noise here and are suppressed.
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      const hostProps = {
+        mobileFullscreen: true,
+        mobile_fullscreen: true,
+      } as unknown as Partial<FieldWidgetComponentProps<string>>;
+
+      render(
+        <TextAreaField
+          value="hello"
+          onChange={() => {}}
+          field={fieldMeta()}
+          {...hostProps}
+        />,
+      );
+
+      expect(screen.queryByTestId('textarea-fullscreen-toggle')).not.toBeInTheDocument();
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+});

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);
+  });
+});

package/src/widgets/nativeDateValue.ts

@@ -0,0 +1,112 @@
+/**
+ * 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.
+ */
+
+/**
+ * Value adapters for the native date/time controls (objectui#3127).
+ *
+ * ## The defect these close
+ *
+ * `<input type="date">` accepts exactly `YYYY-MM-DD` and
+ * `<input type="datetime-local">` exactly `YYYY-MM-DDTHH:mm[:ss]` — a **local
+ * wall clock with no zone suffix**. Anything else is not "coerced" or
+ * "warned about": the browser SILENTLY rejects it. The attribute still lands
+ * in the DOM, so the value looks present to anyone inspecting markup, while
+ * `input.value` reads back `""` and the control paints its empty placeholder:
+ *
+ * ```js
+ * el.getAttribute('value')  // "2026-08-16T00:33:00.000Z"  ← the record's value
+ * el.value                  // ""                          ← what the user sees
+ * ```
+ *
+ * Records come back from the API as full ISO-8601 (`…T00:33:00.000Z`) — which
+ * is precisely one of those rejected shapes. So EVERY datetime field in an
+ * edit dialog rendered blank while holding a real value, and users read that
+ * as "the date was lost" and retyped it (which is the only way the display bug
+ * could turn into a data change).
+ *
+ * ## Why a round trip, and not just a formatter
+ *
+ * Formatting on the way IN without converting on the way OUT would be the
+ * worse bug: the control would then be read as UTC but written back as a naive
+ * local string, so a user in UTC+8 who picked "08:33" would store 08:33Z and
+ * see 16:33 on the detail page. Read basis and write basis must be the same
+ * one, so `toDateTimeInputValue` / `fromDateTimeInputValue` are a pair and are
+ * used as a pair.
+ *
+ * ## Shape kept in form state
+ *
+ * `datetime` round-trips through ISO — the shape the API hands us and the one
+ * display/format code already assumes. `date` stays a plain `YYYY-MM-DD`
+ * string, matching what the inline cell editor in `@object-ui/components`
+ * (`data-table.tsx`) and `@object-ui/plugin-detail`'s `InlineFieldInput`
+ * already do. Untouched fields are never re-emitted, so a form that opens and
+ * closes without an edit still submits nothing for them.
+ */
+
+function pad2(n: number): string {
+  return String(n).padStart(2, '0');
+}
+
+/**
+ * Stored value → `<input type="date">` value (`YYYY-MM-DD`).
+ *
+ * A leading `YYYY-MM-DD` is passed through VERBATIM rather than re-parsed: a
+ * date-only string is parsed as UTC midnight by `new Date()`, so reading local
+ * calendar components back out of it shifts the day by one everywhere west of
+ * Greenwich. `2026-06-17` must stay June 17th in every zone.
+ */
+export function toDateInputValue(value: unknown): string {
+  if (value == null || value === '') return '';
+  if (typeof value === 'string') {
+    const m = value.match(/^(\d{4}-\d{2}-\d{2})/);
+    if (m) return m[1];
+  }
+  const d = value instanceof Date ? value : new Date(String(value));
+  if (Number.isNaN(d.getTime())) return '';
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+/**
+ * Stored value → `<input type="datetime-local">` value (`YYYY-MM-DDTHH:mm`),
+ * expressed in the viewer's local wall clock — the same instant the detail
+ * page shows, so opening the editor never appears to move the time.
+ *
+ * A value that is ALREADY a zone-less local datetime is truncated to minutes
+ * in place instead of being round-tripped through `Date`, which would
+ * reinterpret it and then re-render it, twice risking an off-by-a-zone shift.
+ */
+export function toDateTimeInputValue(value: unknown): string {
+  if (value == null || value === '') return '';
+  if (typeof value === 'string') {
+    const local = value.match(/^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})(?::\d{2}(?:\.\d+)?)?$/);
+    if (local) return `${local[1]}T${local[2]}`;
+  }
+  const d = value instanceof Date ? value : new Date(String(value));
+  if (Number.isNaN(d.getTime())) return '';
+  return (
+    `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}` +
+    `T${pad2(d.getHours())}:${pad2(d.getMinutes())}`
+  );
+}
+
+/**
+ * `<input type="datetime-local">` value → stored value (ISO-8601, UTC).
+ *
+ * The control hands us a zone-less local wall clock; `new Date()` reads that
+ * form as local time, which is the inverse of what `toDateTimeInputValue`
+ * wrote — the pair is what keeps read and write on one basis.
+ *
+ * An unparseable string is returned untouched rather than blanked: dropping a
+ * value the user can see in the box would be a data loss dressed up as a fix.
+ */
+export function fromDateTimeInputValue(value: string): string {
+  if (!value) return '';
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return value;
+  return d.toISOString();
+}