@object-ui/fields 17.2.0 → 17.5.0

package/src/index.tsx

@@ -9,11 +9,16 @@
 import React from 'react';
 import type { FieldMetadata, SelectOptionMetadata } from '@object-ui/types';
 import { ComponentRegistry, percentDisplayValue, getRecordDisplayName } from '@object-ui/core';
-import { useLocalization } from '@object-ui/i18n';
+import { useLocalization, useDisplayLocale, formatDisplayNumber } from '@object-ui/i18n';
 import { Badge, Avatar, AvatarImage, AvatarFallback, Button, Checkbox, EmptyValue, cn } from '@object-ui/components';
 import { Check, X, Copy, Phone as PhoneIcon, MapPin } from 'lucide-react';
 import { useObjectTranslation } from '@object-ui/react';
 import { SchemaRendererContext as _SchemaRendererContext } from '@object-ui/react';
+import { useRelatedRecordActions } from '@object-ui/react';
+import { withFieldCarrier } from './withFieldCarrier';
+// Pure formatting rule shared with `AddressField`'s readonly branch — no React,
+// so this does not pull the widget out of its lazy chunk (objectui#4037).
+import { formatAddress, type AddressValue } from './widgets/address-format';
 
 // Module-level cache so multiple renderers fetching the same lookup ID
 // only trigger one network call. Keyed by `${objectName}:${id}`.
@@ -284,46 +289,15 @@ function useFieldTranslate(): ((key: string, params?: Record<string, unknown>) =
   return t as (key: string, params?: Record<string, unknown>) => string;
 }
 
-import { TextField } from './widgets/TextField';
-import { NumberField } from './widgets/NumberField';
-import { BooleanField } from './widgets/BooleanField';
-import { SelectField } from './widgets/SelectField';
-import { DateField } from './widgets/DateField';
-import { EmailField } from './widgets/EmailField';
-import { PhoneField } from './widgets/PhoneField';
-import { UrlField } from './widgets/UrlField';
-import { CurrencyField } from './widgets/CurrencyField';
-import { TextAreaField } from './widgets/TextAreaField';
-import { RichTextField } from './widgets/RichTextField';
-import { LookupField } from './widgets/LookupField';
-import { CapabilityMultiSelectField } from './widgets/CapabilityMultiSelectField';
-import { DateTimeField } from './widgets/DateTimeField';
-import { TimeField } from './widgets/TimeField';
-import { PercentField } from './widgets/PercentField';
-import { PasswordField } from './widgets/PasswordField';
-import { FileField } from './widgets/FileField';
-import { ImageField } from './widgets/ImageField';
+// Only the two symbols this module actually CALLS are imported eagerly. Every
+// field widget used to be imported here as well, statically, purely to hand a
+// component reference to the docs-demo `createFieldRenderer()` wrapper —
+// removed with it (objectui#3910). The live registration path resolves widgets
+// through the lazy loaders in `fieldWidgetMap` below, so nothing here needs a
+// static reference; the widgets stay publicly available via the `export * from
+// './widgets/…'` block at the end of this file.
 import { ImageLightbox } from './widgets/ImageLightbox';
 import { readFileValues } from './widgets/file-value';
-import { LocationField } from './widgets/LocationField';
-import { FormulaField } from './widgets/FormulaField';
-import { SummaryField } from './widgets/SummaryField';
-import { AutoNumberField } from './widgets/AutoNumberField';
-import { UserField } from './widgets/UserField';
-import { ObjectField } from './widgets/ObjectField';
-import { VectorField } from './widgets/VectorField';
-import { GridField } from './widgets/GridField';
-// New widgets according to @objectstack/spec
-import { ColorField } from './widgets/ColorField';
-import { SliderField } from './widgets/SliderField';
-import { RatingField } from './widgets/RatingField';
-import { CodeField } from './widgets/CodeField';
-import { AvatarField } from './widgets/AvatarField';
-import { AddressField } from './widgets/AddressField';
-import { GeolocationField } from './widgets/GeolocationField';
-import { SignatureField } from './widgets/SignatureField';
-import { QRCodeField } from './widgets/QRCodeField';
-import { MasterDetailField } from './widgets/MasterDetailField';
 
 /**
  * Cell renderer props
@@ -384,27 +358,56 @@ export function coerceToSafeValue(value: unknown): string | number | boolean | n
  * USD for unconfigured currency fields was the #1 source of "why is my
  * RMB amount showing as dollars?" bug reports.
  *
- * Trailing `.00` is dropped when the value is a whole number — Salesforce
- * convention: `$1,234.50` keeps cents; `$1,234` does not.
+ * Trailing minor units are dropped when the value is a whole number —
+ * Salesforce convention: `$1,234.50` keeps cents; `$1,234` does not. Wholeness
+ * picks ONE fraction-digit width, never a range: a whole amount shows 0 digits,
+ * and a fractional amount shows the width the CURRENCY has — so a real cents
+ * value of `.50` renders `.50`, not `.5`, and a yen amount renders `¥1,235`
+ * rather than cents the yen does not have.
  */
-import { resolveFieldCurrency } from './currency';
+import { resolveFieldCurrency, currencyFractionDigits } from './currency';
 export { resolveFieldCurrency };
 
-export function formatCurrency(value: number, currency?: string): string {
+export function formatCurrency(value: number, currency?: string, locale?: string): string {
   const isWhole = Number.isFinite(value) && value === Math.trunc(value);
-  const maxFrac = isWhole ? 0 : 2;
+  // ONE width for both bounds, not a range (objectui#4332). The symbol branch
+  // used to pass `minimumFractionDigits: 0` against a wholeness-switched
+  // maximum, which handed Intl the range [0, 2] — and Intl then emits the
+  // SHORTEST representation in range, so a genuine cents value of `.50` was
+  // printed as `.5`: `$1,234.5` instead of the `$1,234.50` promised above.
+  // It was the only branch that did: the no-currency branch reaches
+  // `formatNumber`, which sets both bounds to the width it is given, and the
+  // bad-currency fallback below has always used `toFixed`. Both already
+  // rendered `1,234.50` for the same amount.
+  //
+  // The non-whole width is the CURRENCY's own ISO 4217 minor-unit count, not a
+  // literal 2 (objectui#4361). Passing 2 for every currency on earth OVERRODE
+  // what `Intl` already knows: JPY has no minor unit and KWD has three, so a
+  // yen amount was printed with cents it does not have (`¥1,234.50`) and a
+  // dinar amount one digit short (`KWD 1.50`).
+  //
+  // The wholeness switch itself is NOT retired — dropping both bounds and
+  // letting `Intl` decide would fix the digit count by turning `$1,234` back
+  // into `$1,234.00`, which is exactly the convention this function documents
+  // and objectui#4033 pinned. It is extended instead: whole amounts drop the
+  // fraction for EVERY currency (`KWD 1`, not `KWD 1.000`), fractional amounts
+  // take that currency's own count.
+  //
+  // With no currency in hand there is nothing to derive from, so that branch
+  // keeps the historical 2.
+  const fracDigits = isWhole ? 0 : currency ? currencyFractionDigits(currency) : 2;
   if (!currency) {
-    return formatNumber(value, maxFrac);
+    return formatNumber(value, fracDigits, locale);
   }
   try {
-    return new Intl.NumberFormat('en-US', {
-      style: 'currency',
+    return formatDisplayNumber(value, {
+      locale,
       currency,
-      minimumFractionDigits: 0,
-      maximumFractionDigits: maxFrac,
-    }).format(value);
+      minimumFractionDigits: fracDigits,
+      maximumFractionDigits: fracDigits,
+    });
   } catch {
-    return `${currency} ${value.toFixed(maxFrac)}`;
+    return `${currency} ${value.toFixed(fracDigits)}`;
   }
 }
 
@@ -413,25 +416,26 @@ export function formatCurrency(value: number, currency?: string): string {
  * E.g., $150,000 → $150K, $1,200,000 → $1.2M
  * When `currency` is undefined, returns a compact number without symbol.
  */
-export function formatCompactCurrency(value: number, currency?: string): string {
+export function formatCompactCurrency(value: number, currency?: string, locale?: string): string {
   if (!currency) {
     try {
-      const formatted = new Intl.NumberFormat('en-US', {
+      const formatted = formatDisplayNumber(value, {
+        locale,
         notation: 'compact',
         maximumFractionDigits: 1,
-      }).format(value);
+      });
       return formatted.replace(/\.0(?=[KMBT])/, '');
     } catch {
       return String(value);
     }
   }
   try {
-    const formatted = new Intl.NumberFormat('en-US', {
-      style: 'currency',
+    const formatted = formatDisplayNumber(value, {
+      locale,
       currency,
       notation: 'compact',
       maximumFractionDigits: 1,
-    }).format(value);
+    });
     // Strip trailing ".0" before compact suffix for consistent cross-environment output
     // e.g. "$150.0K" → "$150K" while keeping "$1.5M" intact
     return formatted.replace(/\.0(?=[KMBT])/, '');
@@ -445,26 +449,95 @@ export function formatCompactCurrency(value: number, currency?: string): string
  * Used as a safe fallback when a currency-typed field has no `currency`
  * configured — we'd rather render `1,234.50` than silently assume USD.
  */
-export function formatNumber(value: number, decimals: number = 2): string {
+export function formatNumber(value: number, decimals: number = 2, locale?: string): string {
   try {
-    return new Intl.NumberFormat('en-US', {
+    // Deliberately passes NO `scale`: `decimals` here is a display width the
+    // caller chose, not a field's declared scale, so the ordinal no-grouping
+    // policy must not fire. `formatCurrency`'s no-currency fallback lands here
+    // with `decimals: 0` for a whole amount — that is still money and must keep
+    // its separators.
+    return formatDisplayNumber(value, {
+      locale,
       minimumFractionDigits: decimals,
       maximumFractionDigits: decimals,
-    }).format(value);
+    });
   } catch {
     return value.toFixed(decimals);
   }
 }
 
 /**
- * Format percent value
+ * The percent rendering itself, on a value ALREADY in display magnitude (`80`
+ * means 80%).
+ *
+ * Split out from {@link formatPercent} because `PercentCellRenderer`'s
+ * whole-percent branch needs this exact rendering under a DIFFERENT scaling
+ * policy (see there). Two copies of the expression is precisely the drift
+ * `percentDisplayValue`'s doc comment exists to prevent, so there is one copy
+ * and the scaling decision is made by the caller.
+ */
+function formatPercentBody(displayValue: number, precision: number, locale?: string): string {
+  try {
+    // `style: 'percentPoints'` renders a value that is ALREADY in percentage
+    // points, so there is no `/ 100` here. Going through `Intl` rather than
+    // appending a literal '%' is what buys the locale's percent CONVENTION and
+    // not merely its separators: German writes `1.235 %` with a no-break space
+    // before the sign, English `1,235%` with none, Turkish puts the sign in
+    // FRONT. Both bounds are set to `precision` so the width is exactly the one
+    // the caller asked for — the same contract `toFixed` gave.
+    //
+    // ⚠️ NOT `style: 'percent'` (objectui#4590). That style wants a FRACTION, so
+    // this used to divide by 100 for `Intl` to multiply straight back — and the
+    // round trip is not value-preserving. `Intl` formats from the SHORTEST
+    // decimal representation of the double it is handed, and the quotient's is
+    // not the authored one: `1.005` is `1.005`, but `1.005 / 100` is
+    // `0.010049999999999999`, which percent-scales to `1.0049999999999999` and
+    // rounds DOWN — so a stored 1.005 rendered `1.00%` where half-up is `1.01%`.
+    // The DIVISION lost the digit, not the rounding, which is why it reproduced
+    // in every locale and why 27,577 of 1,200,003 ordinary en-US forms moved
+    // (0.005-step grid to 2,000, precisions 0/1/2), every one a last-digit
+    // off-by-one. The same artefact reached the top of the double range:
+    // `MAX_SAFE_INTEGER` points rendered `…740,990%` for `…740,991%`.
+    //
+    // The affix is unchanged by the switch: `'percentPoints'` is `Intl`'s
+    // `style: 'unit'` / `unit: 'percent'` / `unitDisplay: 'narrow'`, measured
+    // byte-identical to `style: 'percent'` across all 171 locale tags in #4576
+    // and re-measured on THIS call shape in #4590 — 720 combinations (10 locales
+    // x 18 values x 4 precisions), 0 convention diffs, 130 numeral diffs.
+    // `formatMeasure` renders through the same option, so a percentage point
+    // reads identically in a list cell and in a dashboard measure.
+    return formatDisplayNumber(displayValue, {
+      locale,
+      style: 'percentPoints',
+      minimumFractionDigits: precision,
+      maximumFractionDigits: precision,
+    });
+  } catch {
+    return `${displayValue.toFixed(precision)}%`;
+  }
+}
+
+/**
+ * Format percent value.
  * Handles both decimal (0.8 = 80%) and whole number (80 = 80%) inputs.
+ *
+ * `locale` is the third positional parameter, matching {@link formatNumber} and
+ * {@link formatCurrency} — the shape the sibling formatters already use.
+ * Callers should pass the tag from `useDisplayLocale()`.
+ *
+ * Before objectui#4553 this function took no locale and never touched `Intl`:
+ * its whole body was `${percentDisplayValue(value).toFixed(precision)}%`, so it
+ * rendered in NO locale rather than the machine's — an ASCII decimal mark and
+ * never a grouping separator, byte-identical on every machine. That made
+ * `1235%` the output everywhere, which is wrong in en-US as well as in German,
+ * so the grouping and the locale are fixed together: en output MOVES from
+ * `1235%` to `1,235%` at four digits and up, and that move is the fix.
  */
-export function formatPercent(value: number, precision: number = 0): string {
+export function formatPercent(value: number, precision: number = 0, locale?: string): string {
   // Scale a fraction-stored percent (0.8 → 80%) via the shared core helper, so
   // the list cell and the dashboard measure formatter (`formatMeasure`) agree.
   const displayValue = percentDisplayValue(value);
-  return `${displayValue.toFixed(precision)}%`;
+  return formatPercentBody(displayValue, precision, locale);
 }
 
 /**
@@ -548,8 +621,13 @@ export function formatDate(value: string | Date | number, style?: string, option
   if (!(date instanceof Date) || isNaN(date.getTime())) return '—';
 
   if (style === 'short') {
-    // Compact format for mobile: "Jan 15, '24"
-    const month = date.toLocaleDateString('en-US', { month: 'short' });
+    // Compact format for mobile: "Jan 15, '24" / "1月 15, '24".
+    // Only the MONTH token is localized: the surrounding compact shape (day,
+    // apostrophe + 2-digit year) is a deliberate fixed layout for narrow
+    // cards, not a locale-derived one. The tag comes from `options.locale`
+    // like the default branch below — hardcoding `'en-US'` here made this the
+    // one branch that ignored a locale its caller had threaded (objectui#4272).
+    const month = date.toLocaleDateString(options?.locale, { month: 'short' });
     const day = date.getDate();
     const year = String(date.getFullYear()).slice(-2);
     return `${month} ${day}, '${year}`;
@@ -573,14 +651,22 @@ export function formatDate(value: string | Date | number, style?: string, option
 }
 
 /**
- * Format datetime value
+ * Format datetime value.
+ *
+ * `options` mirrors {@link formatDate}'s and is optional, so an existing
+ * caller that passes nothing keeps the exact runtime-default behavior it had.
+ * Before objectui#4272 the parameter did not exist at all, which meant no
+ * caller could localize this function however hard it tried — it always handed
+ * `Intl` an `undefined` tag, i.e. the MACHINE's locale, which is neither of
+ * the repo's two locale channels. Callers should pass the tag from
+ * `useDisplayLocale()`.
  */
-export function formatDateTime(value: string | Date | number): string {
+export function formatDateTime(value: string | Date | number, options?: DateDisplayOptions): string {
   if (value === null || value === undefined || value === '') return '—';
   const date = value instanceof Date ? value : new Date(value as any);
   if (!(date instanceof Date) || isNaN(date.getTime())) return '—';
-  
-  return date.toLocaleDateString(undefined, {
+
+  return date.toLocaleDateString(options?.locale, {
     year: 'numeric',
     month: 'short',
     day: 'numeric',
@@ -589,21 +675,54 @@ export function formatDateTime(value: string | Date | number): string {
   });
 }
 
+/**
+ * Single-line cell value with a working ellipsis and a full-text fallback.
+ *
+ * `truncate` on a bare inline `<span>` never clips — an inline box has no
+ * width box for `overflow:hidden` / `text-overflow:ellipsis` to act on, so
+ * the value renders at full content width and the tail is silently cut by
+ * whatever ancestor happens to clip (the detail card edge), with no ellipsis
+ * (objectui#3466; same mechanism as the JSON cell in objectui#2578).
+ * Block-level + `max-w-full` gives the span its parent's width to truncate
+ * against, and as a flex item its `overflow:hidden` zeroes the automatic
+ * min-size so it can shrink below the text width. The `title` keeps the full
+ * text reachable on hover — host rows (detail sections) put their inline-edit
+ * hint in *their* `title`, so the value's full text must live on the value
+ * element itself, where it takes precedence under the cursor.
+ */
+function TruncatedText({
+  text,
+  className,
+}: {
+  text: string;
+  className?: string;
+}): React.ReactElement {
+  return (
+    <span className={cn('block max-w-full truncate', className)} title={text}>
+      {text}
+    </span>
+  );
+}
+
 /**
  * Text field cell renderer
  */
 export function TextCellRenderer({ value }: CellRendererProps): React.ReactElement {
   const safe = coerceToSafeValue(value);
   if (safe == null || safe === '') return <EmptyValue />;
-  return <span className="truncate">{String(safe)}</span>;
+  return <TruncatedText text={String(safe)} />;
 }
 
 /**
  * Number field cell renderer
  */
 export function NumberCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
+  // Hook before the empty-value early return — a value flipping between null
+  // and set must not change the hook count between renders (same rule as
+  // CurrencyCellRenderer below).
+  const locale = useDisplayLocale();
   if (value == null) return <EmptyValue />;
-  
+
   const safe = coerceToSafeValue(value);
   const numField = field as any;
   // Decimal places come from `scale` (the `s` in a `decimal(p, s)` column),
@@ -614,13 +733,22 @@ export function NumberCellRenderer({ value, field }: CellRendererProps): React.R
   // scale 2 → "16.00", a field with scale 3 → "3.140"); when it is absent we
   // keep the minimum at 0 so trailing zeros are trimmed and only cap the
   // maximum (20 = Intl max) to preserve the value's natural precision.
+  //
+  // `scale` is also the grouping POLICY input (objectui#4033): a declared
+  // `scale: 0` with no currency is a discrete integer — a year, a fiscal
+  // period, an ordinal — and those are rendered ungrouped, so a `Field.number`
+  // year finally shows `2026` instead of `2,026`. An ABSENT scale keeps
+  // grouping: absent means "decimals unknown", not "integer". The policy and
+  // its interim status live in `formatDisplayNumber`, not here.
   const scale = typeof numField.scale === 'number' ? numField.scale : undefined;
   const num = Number(safe);
   const formatted = !isNaN(num)
-    ? new Intl.NumberFormat('en-US', {
+    ? formatDisplayNumber(num, {
+        locale,
+        scale,
         minimumFractionDigits: scale ?? 0,
         maximumFractionDigits: scale ?? 20,
-      }).format(num)
+      })
     : String(safe);
   
   return <span className="tabular-nums">{formatted}</span>;
@@ -633,6 +761,7 @@ export function CurrencyCellRenderer({ value, field }: CellRendererProps): React
   // Hooks before the empty-value early return — a value flipping between
   // null and set must not change the hook count between renders.
   const { currency: tenantCurrency } = useLocalization();
+  const locale = useDisplayLocale();
   if (value == null) return <EmptyValue />;
 
   const safe = coerceToSafeValue(value);
@@ -643,7 +772,7 @@ export function CurrencyCellRenderer({ value, field }: CellRendererProps): React
   const currency = resolveFieldCurrency(field as any, tenantCurrency);
   const num = Number(safe);
   const formatted = !isNaN(num)
-    ? formatCurrency(num, currency)
+    ? formatCurrency(num, currency, locale)
     : String(safe);
 
   return <span className="tabular-nums font-medium whitespace-nowrap">{formatted}</span>;
@@ -656,8 +785,12 @@ const WHOLE_PERCENT_FIELD_PATTERN = /progress|completion/;
  * Percent field cell renderer with mini progress bar
  */
 export function PercentCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
+  // Hook before the empty-value early return — a value flipping between null
+  // and set must not change the hook count between renders (same rule as
+  // NumberCellRenderer / CurrencyCellRenderer above).
+  const locale = useDisplayLocale();
   if (value == null) return <EmptyValue />;
-  
+
   const safe = coerceToSafeValue(value);
   const percentField = field as any;
   const precision = percentField.precision ?? 0;
@@ -671,13 +804,35 @@ export function PercentCellRenderer({ value, field }: CellRendererProps): React.
   const barValue = isWholePercentField
     ? numValue
     : (numValue > -1 && numValue < 1) ? numValue * 100 : numValue;
-  const formatted = isWholePercentField ? `${numValue.toFixed(precision)}%` : formatPercent(numValue, precision);
+  // Both branches render through the same locale-aware body (objectui#4553);
+  // they differ ONLY in the scaling policy, which is the whole point of the
+  // branch. The whole-percent branch used to be a second bare `toFixed` path,
+  // so before this card a `progress` field was ungrouped and unlocalized even
+  // where an ordinary percent column would not have been — leaving it behind
+  // would have made ONE grid internally inconsistent, which is worse than the
+  // uniform defect it had.
+  const formatted = isWholePercentField
+    ? formatPercentBody(numValue, precision, locale)
+    : formatPercent(numValue, precision, locale);
   const clampedBar = Math.max(0, Math.min(100, barValue));
   
+  // Layout contract (objectstack#5066): THE NUMBER IS THE CONTENT, THE BAR IS
+  // DECORATION. The bar used to be `w-16 shrink-0` while the value span was
+  // shrinkable, so in a narrow clipping container — a `record:highlights` chip
+  // is `basis-[9rem]`/`min-w-[7rem]` and clips with `truncate` — the 64px bar
+  // took the space and the value was silently cut mid-digit: a stored `33.33`
+  // rendered `33%` in the DOM but read as `3` on screen, with no ellipsis and
+  // nothing in the accessible name to signal the loss.
+  //
+  // So the priority is inverted: the value span is `shrink-0` (never sacrificed)
+  // and the bar keeps `w-16` only as its PREFERRED width, free to shrink away
+  // under pressure. It is deliberately NOT `flex-1` — growing is not wanted, or
+  // every wide grid cell would stretch its bar; `w-16` stays the upper bound and
+  // wide containers look exactly as before.
   return (
-    <div className="flex items-center gap-2">
+    <div className="flex min-w-0 items-center gap-2">
       <div
-        className="h-1.5 w-16 rounded-full bg-muted ring-1 ring-inset ring-border/60 overflow-hidden shrink-0"
+        className="h-1.5 w-16 min-w-0 shrink rounded-full bg-muted ring-1 ring-inset ring-border/60 overflow-hidden"
         role="progressbar"
         aria-valuenow={clampedBar}
         aria-valuemin={0}
@@ -688,7 +843,7 @@ export function PercentCellRenderer({ value, field }: CellRendererProps): React.
           style={{ width: `${clampedBar}%` }}
         />
       </div>
-      <span className="tabular-nums whitespace-nowrap">{formatted}</span>
+      <span className="shrink-0 tabular-nums whitespace-nowrap">{formatted}</span>
     </div>
   );
 }
@@ -748,7 +903,14 @@ export function BooleanCellRenderer({ value, field }: CellRendererProps): React.
  * Date field cell renderer
  */
 export function DateCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
-  const { locale } = useLocalization();
+  // `useDisplayLocale()`, NOT `useLocalization().locale` (objectui#4468). The
+  // raw tenant locale is `undefined` on any workspace that never configured
+  // one, and `Intl` reads the MACHINE's locale from `undefined` — so a `zh`
+  // console rendered `逾期 6 天` (which resolves through `t`, the ACTIVE UI
+  // language) beside `In 3 days` and `6 days ago` (which resolve through
+  // `Intl`) on the SAME row. One channel for both halves, or the row
+  // disagrees with itself.
+  const locale = useDisplayLocale();
   const t = useFieldTranslate();
   if (!value) return <EmptyValue />;
   const safe = coerceToSafeValue(value);
@@ -785,17 +947,26 @@ export function DateCellRenderer({ value, field }: CellRendererProps): React.Rea
  * DateTime field cell renderer (Airtable-style with date and time visually separated)
  */
 export function DateTimeCellRenderer({ value }: CellRendererProps): React.ReactElement {
+  // Hook before every early return — a value flipping between null and set
+  // must not change the hook count between renders (same rule as the number /
+  // currency renderers above). This is the site objectui#4468 caught rendering
+  // `8/11/2026 12:00 am` inside an otherwise Chinese grid: both calls passed
+  // `undefined`, i.e. the machine's locale, on every session.
+  const locale = useDisplayLocale();
   if (!value) return <EmptyValue />;
   const safe = coerceToSafeValue(value);
   const date = safe != null ? new Date(safe as string | number) : null;
   if (date === null || isNaN(date.getTime())) return <EmptyValue />;
 
-  const datePart = date.toLocaleDateString(undefined, {
+  const datePart = date.toLocaleDateString(locale, {
     month: 'numeric',
     day: 'numeric',
     year: 'numeric',
   });
-  const timePart = date.toLocaleTimeString(undefined, {
+  // `hour12` stays declared: this is the compact Airtable-style cell, and the
+  // 12-hour face is its design, not a locale artefact. Locales that write no
+  // am/pm marker simply ignore it.
+  const timePart = date.toLocaleTimeString(locale, {
     hour: 'numeric',
     minute: '2-digit',
     hour12: true,
@@ -1089,10 +1260,13 @@ export function SelectCellRenderer({ value, field }: CellRendererProps): React.R
         || SEMANTIC_COLOR_MAP[String(val).toLowerCase().replace(/[\s-]/g, '_')]
         || hashToColor(String(val).toLowerCase().replace(/[\s-]/g, '_'));
       const dotClass = DOT_COLOR_MAP[colorName] || DOT_COLOR_MAP.gray;
+      // max-w-full bounds the (otherwise content-sized) inline-flex box so the
+      // inner truncate can engage; title keeps the full label on hover
+      // (objectui#3466, same class of bug as the badge branch below).
       return (
-        <span key={key} className="inline-flex items-center gap-1.5 text-sm">
+        <span key={key} className="inline-flex max-w-full items-center gap-1.5 text-sm" title={label}>
           <span className={cn('h-1.5 w-1.5 rounded-full shrink-0', dotClass)} aria-hidden="true" />
-          <span className="truncate">{label}</span>
+          <span className="min-w-0 truncate">{label}</span>
         </span>
       );
     }
@@ -1266,7 +1440,7 @@ export function FileCellRenderer({ value, field }: CellRendererProps): React.Rea
   }
   
   const fileName = value.name || value.original_name || 'File';
-  return <span className="text-sm truncate">{fileName}</span>;
+  return <TruncatedText text={String(fileName)} className="text-sm" />;
 }
 
 /**
@@ -1355,6 +1529,89 @@ export function ImageCellRenderer({ value }: CellRendererProps): React.ReactElem
   );
 }
 
+/**
+ * The referenced record's id inside one lookup value — an `$expand`-ed record
+ * object (`{ id, name, … }`) or the raw foreign key itself. `undefined` when
+ * the value carries no id we could address (e.g. an unresolved external-id
+ * reference), which the link below reads as "not navigable".
+ */
+function referencedRecordId(item: unknown): string | number | undefined {
+  if (item == null || item === '') return undefined;
+  if (typeof item === 'object') {
+    const id = (item as Record<string, unknown>).id ?? (item as Record<string, unknown>)._id;
+    if (typeof id === 'number') return id;
+    return typeof id === 'string' && id !== '' ? id : undefined;
+  }
+  if (typeof item === 'string' || typeof item === 'number') return item;
+  return undefined;
+}
+
+/**
+ * Wrap a lookup's display value in a link to the record it references
+ * (objectui#4336).
+ *
+ * On the record detail page a valued lookup used to render as plain text plus
+ * a copy button — the referenced document's name was right there and there was
+ * no way to reach it, so users copied the number and searched for it from the
+ * list. Related-list cells pointing at a third object were dead in the same
+ * way. Both surfaces resolve through `LookupCellRenderer`, so the affordance
+ * belongs here, once.
+ *
+ * **The URL is not built here.** This package has no router and no business
+ * knowing what a record route looks like; the host publishes its own builder
+ * through `RelatedRecordActionsContext` (`recordHref` / `openRecord`) — the
+ * same one the related list's row navigation uses. No host, or a host that
+ * cannot route to that object, renders the value EXACTLY as before: no anchor,
+ * no styling change, nothing to un-learn (Studio designer, embedded renderers,
+ * standalone grids).
+ *
+ * A real `href` rather than a click handler, so middle-click / ⌘-click / "copy
+ * link address" behave the way a link is supposed to; a plain left click is
+ * handed to the host so navigation stays in-app.
+ */
+function ReferencedRecordLink({
+  objectName,
+  recordId,
+  className,
+  children,
+}: {
+  objectName?: string;
+  recordId?: string | number;
+  className?: string;
+  children: React.ReactNode;
+}): React.ReactElement {
+  const host = useRelatedRecordActions();
+  const navigable = !!objectName && recordId != null && recordId !== '';
+  const href =
+    navigable && host?.recordHref
+      ? host.recordHref(objectName as string, recordId as string | number)
+      : null;
+
+  if (!href) return <>{children}</>;
+
+  return (
+    <a
+      href={href}
+      className={cn('text-primary underline-offset-4 hover:underline', className)}
+      onClick={(e) => {
+        // The rows this cell sits in carry their own click handlers — the
+        // detail row copies the field value, a related-list row opens ITS own
+        // record. Following the reference must not also fire those.
+        e.stopPropagation();
+        // Modifier and non-primary clicks belong to the browser (new tab, new
+        // window) — that is the point of rendering a real href.
+        if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+        // No SPA handler: let the anchor navigate on its own.
+        if (!host?.openRecord) return;
+        e.preventDefault();
+        host.openRecord(objectName as string, recordId as string | number);
+      }}
+    >
+      {children}
+    </a>
+  );
+}
+
 /**
  * Lookup/Master-Detail field cell renderer.
  *
@@ -1427,15 +1684,24 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
       // Compute inside try, render outside — constructing JSX in a try/catch
       // doesn't catch its render errors anyway (react-hooks/error-boundaries).
       let parsedDisplay = '';
+      let parsedId: string | number | undefined;
       try {
         const parsed = JSON.parse(s) as Record<string, unknown>;
         if (parsed && typeof parsed === 'object') {
           parsedDisplay =
             resolveLookupRecordName(parsed, refSchema, displayField) ||
             String(parsed.externalId ?? parsed.id ?? parsed._id ?? '');
+          // An external-id reference has no record id yet — stays unlinked.
+          parsedId = referencedRecordId(parsed);
         }
       } catch { /* not JSON — fall through to normal resolution */ }
-      if (parsedDisplay) return <span className="truncate">{parsedDisplay}</span>;
+      if (parsedDisplay) {
+        return (
+          <ReferencedRecordLink objectName={referenceTo} recordId={parsedId}>
+            <TruncatedText text={parsedDisplay} />
+          </ReferencedRecordLink>
+        );
+      }
     }
   }
 
@@ -1446,7 +1712,11 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
     const display =
       resolveLookupRecordName(obj, refSchema, displayField) || String(obj.id || obj._id || '');
     if (display) {
-      return <span className="truncate">{display}</span>;
+      return (
+        <ReferencedRecordLink objectName={referenceTo} recordId={referencedRecordId(obj)}>
+          <TruncatedText text={display} />
+        </ReferencedRecordLink>
+      );
     }
   }
 
@@ -1484,18 +1754,26 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
             label = r.text;
             muted = r.muted;
           }
+          // Each chip is one referenced record, so each links on its own —
+          // there is no single destination a multi-value cell could point at.
           return (
-            <span
+            <ReferencedRecordLink
               key={idx}
-              className={cn(
-                'inline-flex items-center px-2 py-0.5 rounded text-xs font-medium',
-                muted
-                  ? 'bg-muted/40 text-muted-foreground'
-                  : 'bg-gray-50 text-gray-700 dark:bg-gray-800/50 dark:text-gray-200',
-              )}
+              objectName={referenceTo}
+              recordId={referencedRecordId(item)}
+              className="text-inherit"
             >
-              {label}
-            </span>
+              <span
+                className={cn(
+                  'inline-flex items-center px-2 py-0.5 rounded text-xs font-medium',
+                  muted
+                    ? 'bg-muted/40 text-muted-foreground'
+                    : 'bg-gray-50 text-gray-700 dark:bg-gray-800/50 dark:text-gray-200',
+                )}
+              >
+                {label}
+              </span>
+            </ReferencedRecordLink>
           );
         })}
       </div>
@@ -1506,12 +1784,23 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
     const label =
       resolveLookupRecordName(value as Record<string, unknown>, refSchema, displayField) ||
       String((value as any).id || (value as any)._id || '[Object]');
-    return <span className="truncate">{label}</span>;
+    return (
+      <ReferencedRecordLink objectName={referenceTo} recordId={referencedRecordId(value)}>
+        <TruncatedText text={label} />
+      </ReferencedRecordLink>
+    );
   }
 
   // Primitive value (e.g. raw ID): try options → resolver → opaque-ID placeholder → raw
+  // The value IS the foreign key, so it addresses the record even when the
+  // display name could not be resolved (the muted placeholder) — a reference
+  // that is present but unnamed is still worth being able to open.
   const { text, muted } = resolveLabel(value);
-  return <span className={cn('truncate', muted && 'text-muted-foreground')}>{text}</span>;
+  return (
+    <ReferencedRecordLink objectName={referenceTo} recordId={referencedRecordId(value)}>
+      <TruncatedText text={text} className={muted ? 'text-muted-foreground' : undefined} />
+    </ReferencedRecordLink>
+  );
 }
 
 /**
@@ -1535,7 +1824,7 @@ export function UserCellRenderer({ value }: CellRendererProps): React.ReactEleme
 
   // Primitive value: just display the ID/username as text
   if (typeof value !== 'object') {
-    return <span className="truncate">{String(value)}</span>;
+    return <TruncatedText text={String(value)} />;
   }
   
   if (Array.isArray(value)) {
@@ -1544,11 +1833,7 @@ export function UserCellRenderer({ value }: CellRendererProps): React.ReactEleme
         {value.slice(0, 3).map((user, idx) => {
           // Primitive user in array
           if (typeof user !== 'object' || user === null) {
-            return (
-              <span key={idx} className="truncate text-sm">
-                {String(user)}
-              </span>
-            );
+            return <TruncatedText key={idx} text={String(user)} className="text-sm" />;
           }
           const name = user.name || user.username || 'User';
           const initials = name.split(' ').map((n: string) => n[0]).join('').toUpperCase().slice(0, 2);
@@ -1588,7 +1873,7 @@ export function UserCellRenderer({ value }: CellRendererProps): React.ReactEleme
           {initials}
         </AvatarFallback>
       </Avatar>
-      <span className="truncate">{name}</span>
+      <TruncatedText text={String(name)} />
     </div>
   );
 }
@@ -1670,13 +1955,10 @@ export function JsonCellRenderer({ value }: CellRendererProps): React.ReactEleme
   } else {
     text = String(value);
   }
-  // inline-block + max-w-full so `truncate` (overflow-hidden/ellipsis/nowrap)
-  // actually clamps to the cell width. On a bare inline <span> truncate never
-  // clips — there is no width box — and its `white-space:nowrap` also defeats
-  // the parent cell's `break-words`, so a long name-keyed map / address JSON
-  // spills into the neighbouring column (objectui#2578). The title keeps the
-  // full value on hover.
-  return <span className="block max-w-full font-mono text-xs text-gray-600 truncate" title={text}>{text}</span>;
+  // The original site of the block-level+max-w-full+title pattern
+  // (objectui#2578) — now shared with every single-line value renderer via
+  // TruncatedText (objectui#3466).
+  return <TruncatedText text={text} className="font-mono text-xs text-gray-600" />;
 }
 
 /**
@@ -1770,6 +2052,39 @@ export function LocationCellRenderer({ value }: CellRendererProps): React.ReactE
   return <JsonCellRenderer value={value} field={{} as any} />;
 }
 
+/**
+ * Renders an `address` value as a formatted single-line postal address instead
+ * of stringified JSON (objectui#4037).
+ *
+ * The detail page's display registry mapped `address` to {@link JsonCellRenderer},
+ * so a populated address read as `{"street":"中策路 1 号","city":"杭州",…}` on the
+ * detail page and in its inline-edit read state — while the very same value
+ * rendered correctly in the create/edit dialog, whose input registry has always
+ * carried `address`. Read side only: nothing about the input widget changes.
+ *
+ * Layout is not invented here. It is {@link formatAddress} — the rule
+ * `AddressField`'s own readonly branch already applied, over the sub-field set
+ * its inputs expose — so a readonly form and a detail page cannot spell one
+ * stored address two ways.
+ *
+ * Anything `formatAddress` cannot recognize falls back to compact JSON rather
+ * than rendering blank: an unknown shape stays visible (today's behaviour) and
+ * is never silently swallowed by the fix.
+ */
+export function AddressCellRenderer({ value }: CellRendererProps): React.ReactElement {
+  if (value == null || value === '') return <EmptyValue />;
+  // A plain string address (some apps store one) is already display-ready.
+  if (typeof value === 'string') return <TruncatedText text={value} className="text-sm" />;
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    const formatted = formatAddress(value as AddressValue);
+    if (formatted) return <TruncatedText text={formatted} className="text-sm" />;
+    // An object carrying no recognized part: `{}` reads as empty, while
+    // `{ foo: 1 }` keeps its JSON so real data is never hidden.
+    if (Object.keys(value as Record<string, unknown>).length === 0) return <EmptyValue />;
+  }
+  return <JsonCellRenderer value={value} field={{} as any} />;
+}
+
 /**
  * Get the appropriate cell renderer for a field type
  */
@@ -1826,7 +2141,7 @@ export function getCellRenderer(fieldType: string): React.FC<CellRendererProps>
     secret: () => <span>••••••</span>,
     location: LocationCellRenderer,
     geolocation: LocationCellRenderer,
-    address: JsonCellRenderer,
+    address: AddressCellRenderer,
     color: ColorSwatchCellRenderer,
     json: JsonCellRenderer,
     object: JsonCellRenderer,
@@ -2034,64 +2349,16 @@ export function evaluateCondition(condition: any, formData: any): boolean {
   return true;
 }
 
-// Create wrapper renderers for field widgets to work with ComponentDemo
-function createFieldRenderer(FieldWidget: React.ComponentType<any>) {
-  const FieldRenderer: React.FC<any> = ({ schema, className, value: initialValue, ...props }) => {
-    const [value, setValue] = React.useState(initialValue ?? schema?.value ?? '');
-    
-    const field = {
-      name: schema?.name || 'field',
-      label: schema?.label,
-      type: schema?.type,
-      placeholder: schema?.placeholder,
-      required: schema?.required,
-      readonly: schema?.readonly || schema?.readOnly,
-      help: schema?.help,
-      description: schema?.description,
-      // `??`, not `||` — an authored default of `false` / `0` / `''` is a value,
-      // and `||` silently threw it away (same falsy-as-empty class as cloud#972).
-      defaultValue: schema?.defaultValue ?? schema?.value,
-      ...schema,
-    };
-
-    const handleChange = React.useCallback((newValue: any) => {
-      setValue(newValue);
-      if (props.onChange) {
-        props.onChange(newValue);
-      }
-    }, [props]);
-
-    const readonly = schema?.readonly || schema?.readOnly || false;
-
-    return (
-      <div 
-        className="grid w-full items-center gap-1.5"
-        data-obj-id={schema?.id}
-        data-obj-type={schema?.type}
-      >
-        {schema?.label && (
-          <label htmlFor={schema.id} className={schema.required ? "after:content-['*'] after:ml-0.5 after:text-red-500" : ""}>
-            {schema.label}
-          </label>
-        )}
-        <FieldWidget
-          value={value}
-          onChange={handleChange}
-          field={field}
-          readonly={readonly}
-          className={className}
-        />
-        {schema?.description && (
-          <p className="text-sm text-gray-500">{schema.description}</p>
-        )}
-      </div>
-    );
-  };
-  
-  FieldRenderer.displayName = `FieldRenderer(${FieldWidget.displayName || FieldWidget.name || 'Component'})`;
-  
-  return FieldRenderer;
-}
+// TOMBSTONE (objectui#3910, ruling B of objectui#3798) — `createFieldRenderer()`
+// lived here. It wrapped a field widget in synthesized label/description chrome
+// plus a local `useState` + `onChange`, which let a BARE field node render
+// standalone under `SchemaRenderer`. Only `registerFields()` (below, also
+// removed) ever called it, and only the docs site called that — so the chrome
+// existed nowhere a real application could reach, and the docs demos showed a
+// rendering no app produces. The catalog's field examples are form-hosted now
+// (`{ type: 'form', fields: [...] }`), where the real form renderer owns label
+// and value state. Do not re-add a second, demo-only registration path: one
+// registration seam is the whole point (objectui#3308).
 
 /**
  * Field widget map for lazy loading
@@ -2268,6 +2535,50 @@ const FIELD_TYPES_SKIP_FALLBACK = new Set([
   'recipient-picker',
 ]);
 
+/**
+ * Widgets whose labelled surface is NOT a labelable HTML element, so a host's
+ * `<label for>` cannot reach it and the association has to go by IDREF instead
+ * (`ComponentMeta.labelling`, objectui#3961). Two shapes, one declaration:
+ *
+ *  - real composites — `address` / `geolocation` render several inputs under one
+ *    container, and `checkboxes` / `radio` / `rating` / `multiselect` a set of
+ *    choice controls; the host's label names the GROUP, each sub-control keeps
+ *    its own name (a sub-label, or the chip's own text content).
+ *  - `file` is not composite at all: it has exactly ONE control, the dropzone,
+ *    which is a `div[role="button"]` (it is the keyboard path to the hidden file
+ *    input). It is here because a `div` cannot be `for`-labelled, not because it
+ *    is a group, and it renders NO `role="group"` — the dropzone itself takes the
+ *    `aria-labelledby`.
+ *
+ * Measured, not assumed: every entry was verified in a real form to be a widget
+ * whose host label either resolved to nothing (`address` / `geolocation`, whose
+ * sub-input ids overwrote the host id — objectui#3343) or resolved to an element
+ * that cannot carry it (`checkboxes` / `radio` / `rating` / `file` /
+ * `multiselect`). In both shapes the visible group label was, before this
+ * declaration, the accessible name of NOTHING.
+ *
+ * `multiselect` arrived one issue later (objectui#3975) for a coverage reason,
+ * not a mechanism one: #3961's probe covered the six above, and re-running it
+ * over the full widget map afterwards found `multiselect` on the byte-identical
+ * failure shape as `checkboxes` — the host id kept, on the chip row's wrapper
+ * `div`, where a `for` is inert. Same declaration, same container answer.
+ *
+ * A widget NOT listed here takes the single-control path unchanged. That is the
+ * safe default: the host keeps emitting `for`, and a composite that forgot to
+ * declare itself is caught by the label-association tests (objectui#3952) rather
+ * than silently emitting an `aria-labelledby` onto a container with no role.
+ */
+const FIELD_TYPES_GROUP_LABELLED = new Set([
+  'address',
+  'geolocation',
+  'checkboxes',
+  'radio',
+  'rating',
+  'file',
+  // objectui#3975 — the residual after #3961's six, same shape as `checkboxes`.
+  'multiselect',
+]);
+
 export function registerField(fieldType: string): void {
   const loader = fieldWidgetMap[fieldType];
   if (!loader) {
@@ -2277,11 +2588,18 @@ export function registerField(fieldType: string): void {
   
   // Create lazy component
   const LazyFieldWidget = React.lazy(loader);
-  
-  // Register with field namespace - NO WRAPPER to allow form renderer to control label/layout
-  ComponentRegistry.register(fieldType, LazyFieldWidget, {
+
+  // Register with field namespace. No LAYOUT wrapper — the form renderer owns
+  // label/description/spacing. The only thing wrapped is the metadata carrier:
+  // `withFieldCarrier` maps `SchemaRenderer`'s `schema` node onto `field`
+  // (objectui#3233) and renders nothing of its own.
+  ComponentRegistry.register(fieldType, withFieldCarrier(LazyFieldWidget), {
     namespace: 'field',
     skipFallback: FIELD_TYPES_SKIP_FALLBACK.has(fieldType),
+    // Only the group-labelled widgets carry the key; everything else leaves it
+    // absent, which the form renderer reads as `'control'` (objectui#3961). One
+    // spelling of the default, in one place.
+    ...(FIELD_TYPES_GROUP_LABELLED.has(fieldType) ? { labelling: 'group' as const } : null),
   });
 }
 
@@ -2301,100 +2619,37 @@ export function registerAllFields(): void {
   });
 }
 
-/**
- * Legacy function - kept for backward compatibility
- * @deprecated Use registerAllFields() instead
- */
-export function registerFields() {
-  // Basic fields - wrapped for documentation compatibility
-  // `text` collides with the display text widget in @object-ui/components.
-  // Display semantics ({ type: 'text', content: '...' }) are the dominant
-  // usage across the docs/blocks catalog, so we keep this renderer accessible
-  // only via the namespaced `field:text` key and let the display widget win
-  // the bare `text` lookup.
-  ComponentRegistry.register('text', createFieldRenderer(TextField), { namespace: 'field', skipFallback: true });
-  // `textarea`/`select` collide with the `ui:*` form-input primitives that own
-  // the bare keys; namespaced-only (forms use `field:<type>`). See the shared
-  // FIELD_TYPES_SKIP_FALLBACK note above registerField().
-  ComponentRegistry.register('textarea', createFieldRenderer(TextAreaField), { namespace: 'field', skipFallback: true });
-  ComponentRegistry.register('number', createFieldRenderer(NumberField), { namespace: 'field' });
-  ComponentRegistry.register('boolean', createFieldRenderer(BooleanField), { namespace: 'field' });
-  ComponentRegistry.register('select', createFieldRenderer(SelectField), { namespace: 'field', skipFallback: true });
-  ComponentRegistry.register('date', createFieldRenderer(DateField), { namespace: 'field' });
-  ComponentRegistry.register('datetime', createFieldRenderer(DateTimeField), { namespace: 'field' });
-  // Namespaced-only: no other renderer legitimately owns the bare 'time' key,
-  // but the fallback still triggered noisy "bare-name overwritten" warnings on
-  // every re-registration (e.g. hot reload / re-init in a shared registry).
-  ComponentRegistry.register('time', createFieldRenderer(TimeField), { namespace: 'field', skipFallback: true });
-  
-  // Contact fields - wrapped for documentation compatibility
-  // `email` collides with the `ui:email` input variant; namespaced-only so the
-  // display/input primitive keeps the bare key (forms use `field:email`).
-  ComponentRegistry.register('email', createFieldRenderer(EmailField), { namespace: 'field', skipFallback: true });
-  ComponentRegistry.register('phone', createFieldRenderer(PhoneField), { namespace: 'field' });
-  ComponentRegistry.register('url', createFieldRenderer(UrlField), { namespace: 'field' });
-  
-  // Specialized fields - wrapped for documentation compatibility
-  ComponentRegistry.register('currency', createFieldRenderer(CurrencyField), { namespace: 'field' });
-  ComponentRegistry.register('percent', createFieldRenderer(PercentField), { namespace: 'field' });
-  // `password` collides with the `ui:password` input variant; namespaced-only.
-  ComponentRegistry.register('password', createFieldRenderer(PasswordField), { namespace: 'field', skipFallback: true });
-  // `markdown` collides with the markdown DISPLAY renderer (plugin-markdown:markdown),
-  // which owns bare `{ type: 'markdown', content }`; the field renderer here is the
-  // RichText editor, reached by forms via `field:markdown`. Namespaced-only.
-  ComponentRegistry.register('markdown', createFieldRenderer(RichTextField), { namespace: 'field', skipFallback: true });
-  // `html` collides with the HTML-rendering display widget. Keep the
-  // markdown field, but expose the HTML field only via `field:html` so the
-  // display widget remains the default for { type: 'html', content }.
-  ComponentRegistry.register('html', createFieldRenderer(RichTextField), { namespace: 'field', skipFallback: true });
-  ComponentRegistry.register('lookup', createFieldRenderer(LookupField), { namespace: 'field' });
-  // Capability multi-select (ADR-0056 P2) — reached only via the field
-  // `widget: 'capability-multiselect'` hint (see MetadataProvider), never a bare
-  // field type. Registered WITHOUT createFieldRenderer: it is a fully-controlled
-  // widget (value/onChange from RHF), so the wrapper's extra label + local value
-  // buffer would only duplicate the form's FormLabel and desync the value.
-  ComponentRegistry.register('capability-multiselect', CapabilityMultiSelectField, { namespace: 'field', skipFallback: true });
-  // master_detail = child-side FK lookup (single value, typically required). See
-  // fieldWidgetMap above for rationale.
-  ComponentRegistry.register('master_detail', createFieldRenderer(LookupField), { namespace: 'field' });
-  
-  // File fields
-  ComponentRegistry.register('file', createFieldRenderer(FileField), { namespace: 'field' });
-  // `image` collides with the display image widget; namespaced-only.
-  ComponentRegistry.register('image', createFieldRenderer(ImageField), { namespace: 'field', skipFallback: true });
-  
-  // Location field
-  ComponentRegistry.register('location', createFieldRenderer(LocationField), { namespace: 'field' });
-  
-  // Computed/Read-only fields
-  ComponentRegistry.register('formula', createFieldRenderer(FormulaField), { namespace: 'field' });
-  ComponentRegistry.register('summary', createFieldRenderer(SummaryField), { namespace: 'field' });
-  ComponentRegistry.register('auto_number', createFieldRenderer(AutoNumberField), { namespace: 'field' });
-  
-  // User fields
-  ComponentRegistry.register('user', createFieldRenderer(UserField), { namespace: 'field' });
-  ComponentRegistry.register('owner', createFieldRenderer(UserField), { namespace: 'field' });
-  
-  // Complex data types
-  ComponentRegistry.register('object', createFieldRenderer(ObjectField), { namespace: 'field' });
-  ComponentRegistry.register('vector', createFieldRenderer(VectorField), { namespace: 'field' });
-  // `grid` collides with the layout grid component; namespaced-only.
-  ComponentRegistry.register('grid', createFieldRenderer(GridField), { namespace: 'field', skipFallback: true });
-  
-  // NEW: Additional field types from @objectstack/spec
-  ComponentRegistry.register('color', createFieldRenderer(ColorField), { namespace: 'field' });
-  // `slider` collides with the `ui:slider` display control; namespaced-only.
-  ComponentRegistry.register('slider', createFieldRenderer(SliderField), { namespace: 'field', skipFallback: true });
-  ComponentRegistry.register('rating', createFieldRenderer(RatingField), { namespace: 'field' });
-  ComponentRegistry.register('code', createFieldRenderer(CodeField), { namespace: 'field' });
-  // `avatar` collides with the display avatar widget; namespaced-only.
-  ComponentRegistry.register('avatar', createFieldRenderer(AvatarField), { namespace: 'field', skipFallback: true });
-  // Namespaced-only — see the 'time' registration above for rationale.
-  ComponentRegistry.register('address', createFieldRenderer(AddressField), { namespace: 'field', skipFallback: true });
-  ComponentRegistry.register('geolocation', createFieldRenderer(GeolocationField), { namespace: 'field' });
-  ComponentRegistry.register('signature', createFieldRenderer(SignatureField), { namespace: 'field' });
-  ComponentRegistry.register('qrcode', createFieldRenderer(QRCodeField), { namespace: 'field' });
-}
+// TOMBSTONE (objectui#3910, ruling B of objectui#3798) — `registerFields()` lived
+// here. It registered every widget wrapped in `createFieldRenderer` (above) under
+// the same `field:<type>` keys `registerAllFields()` owns, so whoever called it
+// LAST won the registry. Its only caller was the docs site, which needed the
+// synthesized label + `onChange` to render a bare field node standalone.
+//
+// objectui#3308 ruled "registration gets exactly one path"; the implementation
+// (PR #3793) then disproved the assumption that this was a redundant duplicate —
+// it was a demo host adapter, and switching the docs site to `registerAllFields()`
+// alone would have left the demo inputs inert. Ruling B of objectui#3798 resolved
+// that by moving the docs catalog's field examples to form hosting
+// (`{ type: 'form', fields: [...] }`), which deletes the need for the adapter
+// instead of relocating it: the form renderer already owns label and value state,
+// so the docs now show what a real application actually renders.
+//
+// Do not re-add this or any second registration path. `registerAllFields()` (and
+// `registerField()` for one type) is the seam; a docs- or test-only wrapper that
+// re-registers `field:<type>` silently shadows the live entry for every consumer
+// sharing the registry.
+//
+// TOMBSTONE (objectui#3308, ADR-0049 enforce-or-remove) — `field:capability-multiselect`
+// was registered inside `registerFields()`, and ONLY there. Because the docs site
+// was that function's sole caller, the key never existed on the live path, so a
+// field authored with `widget: 'capability-multiselect'` resolved to nothing in
+// every real app while a comment here advertised it as usable from a record form.
+// Nothing stamped the hint either: ADR-0056 P1 stamps `permission-facet-link` on
+// all six `sys_permission_set` facets (`data-objectstack/src/index.ts`
+// applyFieldWidgetOverrides) and P2 put the capability editor in Studio. The
+// widget NAME stays retired — do not add it to `fieldWidgetMap`.
+// `CapabilityMultiSelectField` itself lives on as a plain component, imported and
+// rendered directly by Studio's `PermissionMatrixEditor` (ADR-0056 P2's design).
 
 export * from './widgets/types';
 // File field value shapes (ObjectStack ADR-0104 D3 wave 2) — the single
@@ -2423,6 +2678,11 @@ export * from './widgets/ObjectRefField';
 export * from './widgets/FilterConditionField';
 export * from './widgets/RecipientPickerField';
 export * from './widgets/RecordPickerDialog';
+// Shared picker-column derivation (ADR-0085 highlightFields → displayFields →
+// schema walk) — consumed by LookupField AND by RelatedList's Add-picker so a
+// lookup picker and a related-list Add dialog of the same object agree on
+// columns (#3365).
+export * from './widgets/deriveLookupColumns';
 export * from './widgets/FileField';
 export * from './widgets/ImageField';
 export { ImageCropperDialog } from './widgets/ImageCropperDialog';
@@ -2451,5 +2711,35 @@ export * from './widgets/RadioField';
 export * from './widgets/CheckboxesField';
 export * from './widgets/TagsField';
 
+// The SDUI-node → `field` adapter every registration here goes through
+// (objectui#3233). Exported so a widget registered OUTSIDE this repo can reach
+// the same single-carrier guarantee instead of re-growing a `field || schema`
+// read of its own.
+export { withFieldCarrier } from './withFieldCarrier';
+
+// The whitelist that decides what a widget's `...props` spread may put on a
+// DOM element (objectui#3291) — the runtime executor of the "DOM pass-through"
+// block of `FieldWidgetComponentProps`. Exported for the same reason as
+// `withFieldCarrier` above: a widget authored outside this repo needs to reach
+// it, or it re-grows the bare spread this closed.
+export { toDomProps } from './widgets/toDomProps';
+export type { DomProps } from './widgets/toDomProps';
+
+// The native date/time control value adapters (objectui#3127). `DateTimeField`
+// is ISO-canonical on BOTH sides — it takes the record's ISO instant and hands
+// an ISO instant back, which is also the wire form the platform's `datetime`
+// value contract requires (`InstantValueSchema`: an ISO-8601 instant with an
+// explicit zone), so no consumer has to convert at its own serialization
+// boundary. `ActionParamDialog` used to (objectstack#5061 removed it — the
+// zone-less wall clock it produced was the one shape the validator rejects).
+// Exported for the same reason as `toDomProps` above: a widget authored outside
+// this repo needs the same pair, and a second copy of "what the local wall clock
+// of an instant is" would drift from this one.
+export {
+  toDateInputValue,
+  toDateTimeInputValue,
+  fromDateTimeInputValue,
+} from './widgets/nativeDateValue';
+
 // Initialize registry
 registerAllFields();