wip(ui): record-mode currency — resolver reads the record's code field; cells, currency widget and create-form seeding follow it

Work in progress for the record currency display (ADR-0144 D2, D8 rule 4).

Claude-Session: https://claude.ai/code/session_01Utp6CXtadYa5QXb2PbXPev
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

ui/packages/fields/src/currency.ts

@@ -11,7 +11,7 @@
  * it so the long-standing `@object-ui/fields` import path keeps working for
  * every field/cell renderer that already depends on it.
  */
-export { resolveFieldCurrency } from '@object-ui/i18n';
+export { resolveFieldCurrency, recordCurrencyField } from '@object-ui/i18n';
 
 /**
  * Fallback width for a currency whose digit count cannot be resolved: the

ui/packages/fields/src/index.tsx

@@ -821,7 +821,7 @@ function RatingCellRenderer({ value, field }: CellRendererProps): React.ReactEle
 /**
  * Currency field cell renderer
  */
-export function CurrencyCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
+export function CurrencyCellRenderer({ value, field, dependentValues }: CellRendererProps): React.ReactElement {
   // 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();
@@ -834,8 +834,11 @@ export function CurrencyCellRenderer({ value, field }: CellRendererProps): React
   // Resolve the display currency via the shared precedence: field `currency` →
   // `currencyConfig.defaultCurrency` → the tenant default (ADR-0053). When none
   // is known, render a plain number — never a guessed symbol (silently assuming
-  // USD mis-displays non-USD orgs, e.g. RMB amounts shown as $).
-  const currency = resolveFieldCurrency(field as any, tenantCurrency);
+  // USD mis-displays non-USD orgs, e.g. RMB amounts shown as $). A
+  // `record`-mode amount (ADR-0144 D2) reads its row's code field instead, so
+  // three invoices in USD / EUR / JPY show three symbols; a row with no code
+  // shows a plain number.
+  const currency = resolveFieldCurrency(field as any, tenantCurrency, dependentValues);
   const num = Number(safe);
   // `CurrencyField`'s read-only branch makes this same call, so a table cell
   // and a read-only form show one amount identically: the currency's ISO 4217
@@ -2867,7 +2870,7 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
  * not import each other; `__tests__/formulaFaces.returnType-11748.test.tsx`
  * compares the two faces' text for every declared type.
  */
-export function FormulaCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
+export function FormulaCellRenderer({ value, field, dependentValues }: CellRendererProps): React.ReactElement {
   // Hooks before the empty-value early return: the hook count must not change
   // when a value flips between null and set. The date face reads the display
   // locale; the boolean face reads the locale's word.
@@ -2910,9 +2913,10 @@ export function FormulaCellRenderer({ value, field }: CellRendererProps): React.
   // renderer reads `currencyConfig` through `resolveFieldCurrency` exactly as
   // it reads a currency field's, so a `fixed` config keeps its own code and an
   // absent one is `dynamic`, the tenant default currency. ⛔ No second money
-  // formatter here.
+  // formatter here. The row rides along for a `record`-mode formula, whose
+  // currency is its row's code field (ADR-0144 D2).
   if (valueType === 'currency') {
-    return <CurrencyCellRenderer value={value} field={field} />;
+    return <CurrencyCellRenderer value={value} field={field} dependentValues={dependentValues} />;
   }
 
   // A declared BOOLEAN reads the locale's Yes / No word (objectui#11748), the

ui/packages/fields/src/widgets/CurrencyField.tsx

@@ -7,12 +7,15 @@ import { resolveFieldCurrency, currencySymbol } from '../currency.js';
 import { useBadInputRefusal, BadInputMessage, BAD_INPUT_BORDER } from './numberBadInput.js';
 import { formatCurrency, currencyDisplayWidth } from './number-format.js';
 
-export function CurrencyField({ value, onChange, field, readonly, error, className, ...props }: FieldWidgetComponentProps<number>) {
+export function CurrencyField({ value, onChange, field, readonly, error, className, dependentValues, ...props }: FieldWidgetComponentProps<number>) {
   const currencyField = field as any;
   // Shared precedence: field currency → currencyConfig → tenant default (ADR-0053).
+  // A `record`-mode amount (ADR-0144 D2) reads the code its record holds —
+  // `dependentValues` is the live form record, so picking a code in the
+  // sibling select moves this box's symbol and decimals with it.
   const { currency: tenantCurrency } = useLocalization();
   const locale = useDisplayLocale();
-  const currency: string | undefined = resolveFieldCurrency(currencyField, tenantCurrency);
+  const currency: string | undefined = resolveFieldCurrency(currencyField, tenantCurrency, dependentValues);
   // A currency's decimal places are the CURRENCY's, not a field setting — the
   // maintainer ruling recorded on objectstack-ai/objectstack#19910 (batch #218
   // item 2), executed here by objectui#10276. The width is the ISO 4217

ui/packages/fields/src/widgets/FormulaField.tsx

@@ -116,7 +116,7 @@ export function FormulaField({ value, field, ...props }: FieldWidgetComponentPro
     }
     const amount = Number(safe);
     if (isNaN(amount)) return <span className={typedClassName}>{String(safe)}</span>;
-    return <CurrencyField value={amount} onChange={props.onChange} field={field} readonly />;
+    return <CurrencyField value={amount} onChange={props.onChange} field={field} dependentValues={props.dependentValues} readonly />;
   }
 
   if (valueType === 'boolean') {

ui/packages/i18n/src/currency.ts

@@ -6,10 +6,44 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/**
+ * The currency config a field declares, in the three modes of
+ * `@objectstack/spec`'s `CurrencyConfigSchema` (ADR-0144 D2 adds `record`).
+ */
+export interface FieldCurrencyConfig {
+  currencyMode?: 'dynamic' | 'fixed' | 'record';
+  defaultCurrency?: string;
+  /** `record` mode only: the sibling field holding each record's ISO 4217 code. */
+  currencyField?: string;
+}
+
+/**
+ * The sibling code field a `record`-mode amount points at (ADR-0144 D2), or
+ * `undefined` for a `dynamic` / `fixed` field and for anything that is not a
+ * currency config at all. The one reading every surface that needs the
+ * pointer itself — the form's code select, the grid footer's grouping test,
+ * the filter builder — shares, so none of them re-derives the mode test.
+ */
+export function recordCurrencyField(
+  field: { currencyConfig?: FieldCurrencyConfig } | null | undefined,
+): string | undefined {
+  const config = field?.currencyConfig;
+  if (config?.currencyMode !== 'record') return undefined;
+  return typeof config.currencyField === 'string' && config.currencyField !== ''
+    ? config.currencyField
+    : undefined;
+}
+
 /**
  * Resolve the display currency code for a currency-typed field, in precedence
  * order:
  *
+ *  0. a `record`-mode field (ADR-0144 D2) reads ONLY the record in scope: the
+ *     value of the sibling field `currencyConfig.currencyField` names. No
+ *     record, or a record whose code is blank, resolves to `undefined` — never
+ *     to steps 1–4. The record's code field is the only place that amount's
+ *     currency lives, so the tenant default would name a currency the amount
+ *     is not in: an amount of 100 EUR shown as `¥100` is worse than `100`;
  *  1. the field's explicit `currency` — a per-node display code. The spec
  *     declares it on presentation surfaces (the metric widget's `currency`, a
  *     dataset measure's `currency`) and looser grid/column configs carry it;
@@ -27,34 +61,46 @@
  *
  * `currencyMode: 'dynamic'` — and a `currencyConfig` with no `currencyMode` at
  * all, which `@objectstack/spec` defaults to `'dynamic'` — skips step 2
- * (objectui#10422). The spec describes that mode as "user selectable", and its
- * `FieldSchema` guidance says a field without a fixed currency "uses the tenant
- * default at runtime". No value carries a user-selected code today (a currency
- * value is a bare number), so a dynamic field reads the tenant default, never
- * its `defaultCurrency`. That matters beyond authored dynamic configs: the
- * spec parses an EMPTY `currencyConfig` to
- * `{ currencyMode: 'dynamic', defaultCurrency: 'CNY' }`, which must not render
- * as yuan. If a value ever carries its own selected code, that code is the one
- * to win, ahead of the tenant default.
+ * (objectui#10422): a dynamic field reads the tenant default, never its
+ * `defaultCurrency`. That matters beyond authored dynamic configs: until
+ * @objectstack/spec dropped the `'CNY'` default (#27157), the spec parsed an
+ * EMPTY `currencyConfig` to `{ currencyMode: 'dynamic', defaultCurrency: 'CNY' }`,
+ * and rows stored or built by that parse still carry it until a rehydration
+ * strips it; it must not render as yuan. The spec now refuses a `fixed`
+ * config without a code at authoring and save, but a stored row saved that
+ * way before is kept as authored and still loads with no code; step 2 skips
+ * it and the tenant default shows, as it always did. A per-record currency is
+ * step 0's, and only a `record`-mode field has one.
  *
  * This is the single resolution every field / measure / cell renderer shares -
  * ending the per-renderer drift where some read only `currency`, others only
  * `defaultCurrency`, and others `currencyConfig`. It lives in `@object-ui/i18n`
  * (alongside `useLocalization`) because the tenant default is a localization
  * concern; `@object-ui/fields` re-exports it for backward compatibility.
+ *
+ * `record` is the row / form values the amount sits in. A caller that holds no
+ * record (a column-level header, a footer over many rows) passes none, and a
+ * `record`-mode field then resolves to no currency, which is the honest answer
+ * for a set of amounts in different currencies.
  */
 export function resolveFieldCurrency(
   field:
     | {
         currency?: string;
         defaultCurrency?: string;
-        currencyConfig?: { currencyMode?: 'dynamic' | 'fixed'; defaultCurrency?: string };
+        currencyConfig?: FieldCurrencyConfig;
       }
     | null
     | undefined,
   tenantDefault?: string,
+  record?: Readonly<Record<string, unknown>> | null,
 ): string | undefined {
   const config = field?.currencyConfig;
+  if (config?.currencyMode === 'record') {
+    const codeField = recordCurrencyField(field);
+    const code = codeField !== undefined ? record?.[codeField] : undefined;
+    return typeof code === 'string' && code !== '' ? code : undefined;
+  }
   return (
     field?.currency ||
     (config?.currencyMode === 'fixed' ? config.defaultCurrency : undefined) ||

ui/packages/i18n/src/index.ts

@@ -154,7 +154,7 @@ export {
 
 export { pickLocalized, setLocalized, clearLocalized } from './pickLocalized.js';
 export { LocalizationProvider, useLocalization, type LocalizationValue } from './LocalizationContext.js';
-export { resolveFieldCurrency } from './currency.js';
+export { resolveFieldCurrency, recordCurrencyField, type FieldCurrencyConfig } from './currency.js';
 
 // The one number-display formatter (objectui#4033) and the locale it formats
 // in. Every field cell / widget / metric renderer goes through this pair —

ui/packages/plugin-form/src/DrawerForm.tsx

@@ -37,7 +37,7 @@ import {
 import { Loader2 } from 'lucide-react';
 
 import { SchemaRenderer, useSafeFieldLabel, usePreviewMode } from '@object-ui/react';
-import { createSafeTranslation } from '@object-ui/i18n';
+import { createSafeTranslation, useLocalization } from '@object-ui/i18n';
 import { MasterDetailForm } from './MasterDetailForm';
 import { buildSectionFields as buildSectionFieldsShared } from './sectionFields';
 import { buildFlatFields } from './flatFields';
@@ -253,6 +253,9 @@ const DrawerFormBody: React.FC<DrawerFormProps> = ({
   const { fieldLabel, sectionLabel } = useSafeFieldLabel();
   const perms = usePermissions();
   const { userId: currentUserId } = perms;
+  // ADR-0144 D8 rule 4 — the organization currency a record-currency code
+  // field opens on in create mode.
+  const { currency: homeCurrency } = useLocalization();
   const { t } = useDiscardTranslation();
   // Upload-in-flight gate (objectui#10166): Save is refused, disabled and
   // EXPLAINED while a file/image widget below is still uploading.
@@ -405,7 +408,7 @@ const DrawerFormBody: React.FC<DrawerFormProps> = ({
         // Declared static defaults are this form's opening values (#4047) —
         // see `schemaDefaults` for the create-only boundary and for why
         // runtime defaults are left to the server.
-        setFormData(seedCreateValues(objectSchema, resolveInitialRecord(schema), { currentUserId }));
+        setFormData(seedCreateValues(objectSchema, resolveInitialRecord(schema), { currentUserId, homeCurrency }));
         // Not a read, so no earlier record read's failure describes the form.
         run.commit();
         setLoading(false);

ui/packages/plugin-form/src/ModalForm.tsx

@@ -38,7 +38,7 @@ import {
 import { Loader2 } from 'lucide-react';
 import { MasterDetailForm } from './MasterDetailForm';
 import { SchemaRenderer, useSafeFieldLabel, usePreviewMode } from '@object-ui/react';
-import { createSafeTranslation } from '@object-ui/i18n';
+import { createSafeTranslation, useLocalization } from '@object-ui/i18n';
 import { buildSectionFields as buildSectionFieldsShared } from './sectionFields';
 import { buildFlatFields } from './flatFields';
 import { isRecordReadOutstanding } from './recordReadGate';
@@ -342,6 +342,9 @@ const ModalFormBody: React.FC<ModalFormProps> = ({
   const uploadGate = useUploadGate();
   const previewMode = usePreviewMode();
   const perms = usePermissions();
+  // ADR-0144 D8 rule 4 — the organization currency a record-currency code
+  // field opens on in create mode.
+  const { currency: homeCurrency } = useLocalization();
   const [objectSchema, setObjectSchema] = useState<any>(null);
   const [formData, setFormData] = useState<Record<string, any>>({});
   // The ONE field-gate step every layout draws through (`gateFormFields`,
@@ -565,7 +568,7 @@ const ModalFormBody: React.FC<ModalFormProps> = ({
         // supplied initial values still win. See `schemaDefaults` for why
         // runtime defaults (`NOW()`, `current_user`, CEL envelopes) are left
         // to the server and why option-level `default` is not read here.
-        setFormData(seedCreateValues(objectSchema, resolveInitialRecord(schema), { currentUserId: perms.userId }));
+        setFormData(seedCreateValues(objectSchema, resolveInitialRecord(schema), { currentUserId: perms.userId, homeCurrency }));
         // Not a read, so no earlier record read's failure describes the form.
         run.commit();
         setLoading(false);

ui/packages/plugin-form/src/ObjectForm.tsx

@@ -16,7 +16,7 @@
 import React, { useEffect, useState, useCallback, useMemo } from 'react';
 import type { ObjectFormSchema, FormField, FormSchema, DataSource } from '@object-ui/types';
 import { SchemaRenderer, useSafeFieldLabel } from '@object-ui/react';
-import { pickLocalized, useObjectTranslation } from '@object-ui/i18n';
+import { pickLocalized, useObjectTranslation, useLocalization } from '@object-ui/i18n';
 import { useRecordInvalidation } from './recordInvalidation';
 import { mapFieldTypeToFormType, buildValidationRules, formatFileSize, fieldHelpText } from '@object-ui/fields';
 import { useIsMobile, toast } from '@object-ui/components';
@@ -1270,13 +1270,16 @@ const SimpleObjectForm: React.FC<{ schema: LocalizedObjectFormSchema; dataSource
   // the create-mode `required` suppression (#4069), so seeding and validation
   // cannot disagree about which mode this form is in.
   const isCreateForm = isCreateFormMode(schema);
+  // ADR-0144 D8 rule 4 — the organization currency a record-currency code
+  // field opens on in create mode.
+  const { currency: homeCurrency } = useLocalization();
   // [#5683] `currentUserId` lets the one client-resolvable token
   // (`current_user`) pre-fill with the id the server would stamp anyway;
   // null/unloaded seeds nothing and keeps the omit-and-let-the-engine-resolve
   // contract above.
   const schemaDefaults = React.useMemo(
-    () => (isCreateForm ? schemaDefaultValues(objectSchema, { currentUserId: perms.userId }) : {}),
-    [objectSchema, isCreateForm, perms.userId],
+    () => (isCreateForm ? schemaDefaultValues(objectSchema, { currentUserId: perms.userId, homeCurrency }) : {}),
+    [objectSchema, isCreateForm, perms.userId, homeCurrency],
   );
 
   // What the form OPENS with: the seeded defaults, overlaid with the caller's

ui/packages/plugin-form/src/SplitForm.tsx

@@ -26,6 +26,7 @@
 import React, { useState, useCallback, useEffect, useMemo, useRef } from 'react';
 import type { FormField, FormSchema, DataSource, ObjectFormSchema, ObjectFormSection } from '@object-ui/types';
 import { cn, toast } from '@object-ui/components';
+import { useLocalization } from '@object-ui/i18n';
 import { SchemaRenderer, useSafeFieldLabel } from '@object-ui/react';
 import { buildSectionFields as buildSectionFieldsShared } from './sectionFields';
 import { seedCreateValues } from './schemaDefaults';
@@ -182,6 +183,9 @@ export const SplitForm: React.FC<SplitFormProps> = ({
   const { t } = useFormChromeTranslation();
   const perms = usePermissions();
   const { userId: currentUserId } = perms;
+  // ADR-0144 D8 rule 4 — the organization currency a record-currency code
+  // field opens on in create mode.
+  const { currency: homeCurrency } = useLocalization();
   // Upload-in-flight gate (objectui#10166): a `file`/`image` value is only its
   // fileId once the presigned upload settles, so a save during that window
   // stored the record WITHOUT the attachment and reported success.
@@ -270,7 +274,7 @@ export const SplitForm: React.FC<SplitFormProps> = ({
         // Declared static defaults are this form's opening values (#4047) —
         // see `schemaDefaults` for the create-only boundary and for why
         // runtime defaults are left to the server.
-        setFormData(seedCreateValues(objectSchema, resolveInitialRecord(schema), { currentUserId }));
+        setFormData(seedCreateValues(objectSchema, resolveInitialRecord(schema), { currentUserId, homeCurrency }));
         // Not a read, so no earlier record read's failure describes the form.
         run.commit();
         setLoading(false);