@object-ui/fields 17.5.0 → 17.7.0

package/dist/widgets/address-format.d.ts

@@ -52,17 +52,37 @@ export type LegacyAddressValue = AddressValue & {
 /** Postal code of a stored address, preferring the canonical key. */
 export declare function readPostalCode(addr: AddressValue): string | undefined;
 /**
- * Formats a stored address as a single line: `Street, City, State ZIP, Country`.
+ * Formats a stored address as a single line, in the part order the reader's
+ * locale writes addresses in.
  *
- * 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 `", , ,"`.
+ * Two orders, and the second is exactly the first reversed:
+ *
+ *   - **small-to-large** (default; `en` and every Latin/Cyrillic/Arabic locale
+ *     this repo ships) — `Street, City, State ZIP, Country`. Unchanged from
+ *     what `AddressField`'s readonly branch has always produced, so English and
+ *     provider-less rendering are byte-identical to before.
+ *   - **large-to-small** ({@link LARGE_TO_SMALL_LANGUAGES}) — `Country, ZIP
+ *     State, City, Street`. A `zh` console rendering a Chinese address
+ *     largest-first is the whole point of objectui#4028: `中国, 310000 浙江,
+ *     杭州, 中策路 1 号` rather than the US-ordered line it produced before.
+ *
+ * Only the ORDER varies. The separator stays `', '` in both, because that is
+ * not what the issue reports and because these lines carry mixed-script data —
+ * a US address read on a `zh` console would look stranger under fullwidth
+ * punctuation than under the comma it already has.
+ *
+ * The state/postal-code pair keeps its one comma-delimited group in both
+ * orders, space-separated inside it ("CA 94102" / "310000 浙江"); either part
+ * alone occupies the group by itself. 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.
+ *
+ * @param locale - BCP-47 tag from `useDisplayLocale()`. Omitted (tests, and any
+ *   caller with no React context) means the small-to-large default, which is
+ *   what this function did unconditionally before objectui#4028.
  */
-export declare function formatAddress(addr: AddressValue): string;
+export declare function formatAddress(addr: AddressValue, locale?: string): string;

package/dist/widgets/file-affordance.d.ts

@@ -0,0 +1,33 @@
+import { default as React } from 'react';
+import { FileValueView } from './file-value.js';
+/**
+ * One file: a keyboard-reachable view/download link when it resolves, and the
+ * caller's own `fallback` text when it does not.
+ *
+ * The anchor's accessible name is the file NAME, carried as its link text, so
+ * this needs no `aria-label` and therefore no new translation key — the name
+ * itself already comes off the i18n channel at every call site (a value that
+ * carries no name of its own falls back to `fields.file.fileFallback`).
+ *
+ * `target="_blank"` + `rel="noopener noreferrer"` mirrors `UrlCellRenderer`,
+ * and the click is `stopPropagation`-guarded so opening a file from inside a
+ * grid row does not also trigger row navigation — the same guard
+ * `ImageCellRenderer` puts on its thumbnail.
+ *
+ * ⛔ No `download` attribute: whether the browser views the file inline or
+ * saves it is the storage endpoint's decision, signed into the
+ * `content-disposition` it returns. Forcing one of the two here would override
+ * a choice the platform already makes per file.
+ */
+export declare function FileValueAffordance({ view, fallback, className, icon, }: {
+    view: FileValueView;
+    /**
+     * What to draw when the value resolves to no URL. Required rather than
+     * defaulted: every call site already had a text rendering of its own, and a
+     * default here would quietly replace one of them.
+     */
+    fallback: React.ReactNode;
+    className?: string;
+    /** Suppressed where the row already draws its own icon or thumbnail. */
+    icon?: boolean;
+}): React.ReactElement;

package/dist/widgets/file-size-guard.d.ts

@@ -1,28 +1,10 @@
+import { TranslateFn } from '@object-ui/i18n';
 /**
- * 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`.
+ * Minimal shape of the i18next `t` this module needs — RE-EXPORTED from its one
+ * authority in `@object-ui/i18n`, never re-declared (objectui#8261). The
+ * sibling widgets that import it from here keep doing so; no import path moves.
  */
-export type TranslateFn = (key: string, options?: Record<string, unknown>) => string;
+export type { TranslateFn } from '@object-ui/i18n';
 /**
  * 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`.

package/dist/widgets/file-value.d.ts

@@ -3,7 +3,12 @@ import { isFileIdToken } from '@objectstack/spec/data';
 export interface FileValueView {
     /** `sys_file` id, when the value carries one. */
     id?: string;
-    /** Best available display name. Never empty. */
+    /**
+     * Best available display name: the value's own, else the caller's
+     * `fallbackName`. Empty only when the caller passed an empty fallback to ask
+     * for "no name" (the image cell does, so a nameless image reaches its
+     * translated alt — objectui#10493).
+     */
     name: string;
     /** Resolvable URL, when the value carries one. A bare reference does not. */
     url?: string;
@@ -29,9 +34,8 @@ export interface FileValueView {
  * Why it matters that this one is shared rather than duplicated: the regex is a
  * WIRE decision. Widening it server-side (say, ids grow past 64 chars) while a
  * copy here keeps the old bound turns every new id into "not a reference", and
- * the widget then submits the legacy inline blob against a backend that expects
- * a reference. That failure surfaces as a broken thumbnail, nowhere near a
- * regex.
+ * `fileValueForSubmit` then refuses every upload as incomplete — loud, but
+ * pointing at the adapter while the cause is a regex two packages away.
  */
 export { isFileIdToken };
 /**
@@ -75,13 +79,38 @@ export interface UploadResultLike {
     meta?: Record<string, unknown>;
 }
 /**
- * What to store in the field for a completed upload.
+ * A completed upload that surfaced no `sys_file` id, refused at the point of
+ * submit (objectui#7699).
  *
- * Returns the bare `sys_file` id when the adapter surfaced one — the reference
- * form — and the legacy inline blob when it did not, so a deployment whose
- * upload adapter or backend predates file-as-reference keeps working unchanged.
+ * The adapter reported success, so this is not a transport failure and the
+ * widgets do not quote an adapter message for it: what the user needs to know
+ * is that the field was NOT changed. Named — `name` and `code` — so a caller
+ * can tell it from a thrown network error without reading the message, and
+ * carrying the file's name so a host that reports it can say which pick.
  */
-export declare function fileValueForSubmit(result: UploadResultLike, originalName?: string): string | Record<string, unknown>;
+export declare class UploadIncompleteError extends Error {
+    readonly code: "UPLOAD_INCOMPLETE";
+    /** The pick's own name when the caller knew it, else the adapter's stored object name. */
+    readonly fileName: string;
+    constructor(fileName: string);
+}
+/**
+ * What to store in the field for a completed upload: the bare `sys_file` id
+ * the adapter surfaced in `meta.fileId` — the reference form, the only form
+ * the stored contract admits.
+ *
+ * Throws {@link UploadIncompleteError} when the adapter surfaced no id-shaped
+ * `fileId`. ⛔ There is no fallback: the inline blob this function used to
+ * build in that case (`{ name, original_name, size, mime_type, url }`) is a
+ * shape no deployment's stored contract accepts, and a client that sent it
+ * turned a successful-looking upload into a save the backend refused (see the
+ * module header's "Submitting"). The callers catch the refusal per pick and
+ * render it in the same error row a transport failure lands in.
+ *
+ * @param originalName the pick's own file name, used to name the refusal;
+ *   the adapter's stored object name stands in when the caller has none.
+ */
+export declare function fileValueForSubmit(result: UploadResultLike, originalName?: string): string;
 /**
  * The display view of a just-completed upload.
  *

package/dist/widgets/lookupColumnDisplay.d.ts

@@ -0,0 +1,110 @@
+import { default as React } from 'react';
+import { LookupColumnDef } from '@object-ui/types';
+/**
+ * Cell renderer function signature — matches `getCellRenderer` from
+ * `@object-ui/fields`. Re-declared here (rather than imported from
+ * RecordPickerDialog) so this module sits BELOW both consumers in the import
+ * graph and neither surface can pull the other in.
+ */
+export type LookupCellRendererResolver = (fieldType: string) => React.FC<{
+    value: any;
+    field: any;
+}>;
+/**
+ * A select option as the object schema declares it — `{ value, label }` plus
+ * whatever the renderer also reads (`color`, …), which the i18n translation
+ * carries through untouched.
+ */
+export type SchemaOption = {
+    value: any;
+    label: string;
+    [key: string]: any;
+};
+/** Translate a schema field's options through the shared i18n option path. */
+export type OptionTranslator = (objectName: string, fieldName: string, options: SchemaOption[]) => SchemaOption[];
+/**
+ * Normalise a lookup_columns entry (string | LookupColumnDef) into a
+ * concrete LookupColumnDef object.
+ */
+export declare function normalizeColumn(col: string | LookupColumnDef): LookupColumnDef;
+/**
+ * Pretty-print a field name as a column header label.
+ * Converts snake_case / camelCase to Title Case.
+ */
+export declare function fieldToLabel(field: string): string;
+/**
+ * Resolve a field's select options from the referenced object's schema field
+ * definition (`fieldsMeta[field]`), translated through the shared i18n option
+ * path.
+ *
+ * This is the SINGLE source for every surface that needs option labels: the
+ * picker table cells (#3333), the picker's filter panel select inputs (#3336)
+ * and the inline dropdown's option preview (#5492) — so a picker column, the
+ * filter input for that same column and the dropdown row can never disagree
+ * about what an option is called.
+ *
+ * Returns `undefined` when the schema field declares no options: a select
+ * field with no authored options genuinely has nothing to offer, and
+ * synthesising entries from the loaded page's raw stored values would paper
+ * over the metadata gap with a list that changes per page.
+ */
+export declare function resolveSchemaOptions(meta: {
+    options?: unknown;
+} | undefined, objectName: string, fieldName: string, translateOptions: OptionTranslator): SchemaOption[] | undefined;
+/**
+ * Field descriptors handed to the type-aware cell renderers, enriched from the
+ * referenced object's schema (`fieldsMeta`) the same way the list view enriches
+ * its columns. This is what lets a `select` column resolve its option label
+ * (options + i18n) instead of title-casing the raw value (#3333), and what
+ * carries `reference` through to the lookup cell renderer so
+ * an unresolved foreign-key id resolves to a name (#5492).
+ *
+ * Columns whose def carries no `type` inherit the schema field's type, so
+ * string-authored `lookup_columns` format identically to object-authored ones.
+ */
+export declare function buildLookupColumnDescriptors(columns: LookupColumnDef[], fieldsMeta: Record<string, any> | undefined, objectName: string, translateOptions: OptionTranslator): Record<string, any>;
+export interface LookupColumnRenderContext {
+    /** Field descriptors from {@link buildLookupColumnDescriptors}. */
+    descriptors: Record<string, any>;
+    /** Type-aware renderer resolver; when absent every cell degrades to text. */
+    cellRenderer?: LookupCellRendererResolver;
+    /**
+     * The referenced object's schema. When given, the display column renders the
+     * record's title through `@object-ui/core`'s `getRecordDisplayName`, the same
+     * call the lookup dropdown's option label and the read cell make
+     * (objectui#10486).
+     */
+    objectSchema?: Record<string, unknown> | null;
+    /**
+     * The lookup field's DECLARED display field, handed to the resolver as its
+     * `titleField`. `undefined` when the field declares none: the `name` default
+     * the display column is keyed on is a guess, and a guess never outranks the
+     * referenced object's own declarations.
+     */
+    titleField?: string;
+    /** The column the record title stands in for (the display column's key). */
+    displayField?: string;
+    /** Locale for the plain-text `$date` fallback. */
+    displayLocale?: string;
+}
+/**
+ * Render one column of one candidate record.
+ *
+ * Order:
+ *   1. the record title, for the display column only and only when the
+ *      referenced object's schema is given: `getRecordDisplayName` with the
+ *      lookup's declared display field as its `titleField`, i.e. the field's
+ *      own `displayField`, then the object's `nameField`, then its deprecated
+ *      `titleFormat` template, then type-aware derivation (ADR-0079; the lookup
+ *      branch of objectui#9436's ruling C1). The resolver's own floor
+ *      (`Untitled` / `Record #<id>`) is not a title here, so a record with
+ *      nothing nameable falls through to step 2 and keeps its column's value.
+ *   2. the type-aware cell renderer for the column's field descriptor.
+ *   3. a plain-text fallback for columns with no descriptor / no resolver.
+ *
+ * Step 3 never blanks a populated value: an object with no recognised shape
+ * keeps its JSON and a primitive keeps its `String()` form. That floor is
+ * deliberate — an unresolved reference showing its bare id is strictly better
+ * than a silently empty column (objectui#5492).
+ */
+export declare function renderLookupColumnValue(record: any, col: LookupColumnDef, ctx: LookupColumnRenderContext): React.ReactNode;

package/dist/widgets/nativeDateValue.d.ts

@@ -6,32 +6,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Stored value → `<input type="date">` value (`YYYY-MM-DD`).
+ * Value adapters for the native date/time controls (objectui#3127).
  *
- * 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.
+ * They live in `@object-ui/core` (`utils/native-date-value.ts`), next to the
+ * `isRealCalendarDate` judgement they share, so `@object-ui/components`' data
+ * table can use the same set without a package cycle (objectui#10625). This
+ * module re-exports them unchanged, so every importer here, and the public
+ * `@object-ui/fields` barrel, names the same symbols as before. The design
+ * notes (the round trip, the shape kept in form state, the impossible stored
+ * day) are in the `core` module's header.
  */
-export declare function toDateInputValue(value: unknown): string;
-/**
- * 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 declare function toDateTimeInputValue(value: unknown): string;
-/**
- * `<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 declare function fromDateTimeInputValue(value: string): string;
+export { toDateInputValue, toDateTimeInputValue, fromDateTimeInputValue, isImpossibleStoredDay, } from '@object-ui/core';

package/dist/widgets/number-format.d.ts

@@ -0,0 +1,137 @@
+import { FieldMetadata } from '@object-ui/types';
+import { PercentScale } from '@objectstack/spec/data';
+/**
+ * Format a numeric value the way the `number` field declaring it says to
+ * display it.
+ *
+ * @param value  the numeric value. Callers decide what counts as empty or as
+ *               not a number before calling: this formats a number, it does
+ *               not judge one.
+ * @param field  the field metadata; its `type`, `scale` and `useGrouping` are
+ *               the inputs read.
+ * @param locale the display locale tag, from `useDisplayLocale()`.
+ */
+export declare function formatNumberFieldValue(value: number, field: FieldMetadata, locale: string): string;
+/**
+ * The display width of a currency amount: the resolved currency's own ISO 4217
+ * minor-unit count (2 for USD / CNY, 0 for JPY, 3 for KWD), or the historical 2
+ * when no currency is resolved, since there is then no minor unit to ask about.
+ *
+ * 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 by objectui#10276. ⛔ Not the field-level `precision` (the
+ * TOTAL digit count of a decimal(p, s) column), ⛔ not `scale` (taken off the
+ * `currency` type by ruling B on objectstack-ai/objectstack#19629) and ⛔ not
+ * `currencyConfig.precision`. `CurrencyField`'s comment beside its call carries
+ * the full reasoning.
+ *
+ * One function, so the width a currency amount is DISPLAYED at
+ * ({@link formatCurrency}) and the width `CurrencyField` EDITS it at (its
+ * `step` and its blur rounding) cannot part.
+ */
+export declare function currencyDisplayWidth(currency: string | undefined): number;
+/**
+ * Format a currency amount: the ONE call every display face of a `currency`
+ * field makes. `CurrencyCellRenderer` in a table, `CurrencyField`'s read-only
+ * branch in a form, and every face that takes the cell's formatter by
+ * reference all reach it, so they agree by construction (objectui#11444).
+ *
+ * When `currency` is undefined the amount is a plain number with thousands
+ * separators and no symbol. Silently assuming USD for unconfigured currency
+ * fields was the #1 source of "why is my RMB amount showing as dollars?" bug
+ * reports.
+ *
+ * The width is the DECLARED one, {@link currencyDisplayWidth}, for every
+ * amount: `$3,456.00`, `$3,456.50`, `¥3,456`, `KWD 3,456.000`. Triage ruled
+ * that the protocol's convention is the declared width (objectui#11444, comment
+ * 5946462862), the family's one width source (ruling A′, `resolveFieldScale`),
+ * and retired the objectui#4033 whole-amount trimming this function used to
+ * apply: a whole amount dropped its fraction (`$3,456`, `KWD 3,456`) while the
+ * read-only form showed the same amount at the currency's width (`$3,456.00`),
+ * so one stored value read two ways.
+ *
+ * ONE width for both `Intl` bounds, never a range (objectui#4332). The symbol
+ * branch once passed `minimumFractionDigits: 0` against a larger maximum, and
+ * `Intl` then emits the SHORTEST representation in range, so a genuine cents
+ * value of `.50` printed as `.5` (`$1,234.5`).
+ *
+ * The width is the CURRENCY's own minor-unit count, not a literal 2
+ * (objectui#4361). Passing 2 for every currency on earth overrode what `Intl`
+ * already knows: a yen amount was printed with cents it does not have
+ * (`¥1,234.50`) and a dinar amount one digit short (`KWD 1.50`).
+ *
+ * Deliberately passes NO `scale` to `formatDisplayNumber`: `scale: 0` without a
+ * currency reads as an ordinal there and drops the grouping separators
+ * (objectui#4033), and an amount is never an ordinal.
+ */
+export declare function formatCurrency(value: number, currency?: string, locale?: string): string;
+/**
+ * The storage scale a percent FACE reads a field's stored number at: the
+ * spec's `percentScaleOf` (`@objectstack/spec/data`) by reference, plus the
+ * one type the percent cell draws that the spec does not answer for
+ * (objectui#11475).
+ *
+ * `PercentCellRenderer` reads it, and so does every face that renders the
+ * cell's number for the same field (the grid footer, the record detail chip,
+ * the gantt tooltip, the mobile card, the object metric tile), so one stored
+ * value reads one magnitude on all of them. ⛔ None of them reads the storage
+ * off the VALUE: a magnitude guess cannot tell a fraction-stored `1` (100%)
+ * from one percentage point.
+ *
+ * - **`percent`, and a textual field the `format: 'percent'` hint promotes to
+ *   the percent cell:** `percentScaleOf` asked about `percent`, the face's own
+ *   type, with the field's declared `max`. A percent field stores a fraction
+ *   unless it declares a `max` above 1. Asking about `percent` rather than the
+ *   bag's own `type` is what lets a promoted textual field, or a bag whose
+ *   `type` was rewritten to the renderer key, read by the percent convention
+ *   too; it is the same reason `PercentField` asks `resolveFieldScale` about
+ *   `percent`. `percentScaleOf` answers every percent field, so the result is
+ *   never `undefined`.
+ * - **`progress`: `whole`, stated here.** The spec's `percentScaleOf` answers
+ *   `undefined` for it (it keys on `percent` alone), so the spec states no
+ *   percent storage for a `progress` field, and an undeclared key follows the
+ *   implementation: the one editor a `progress` field has, `SliderField`,
+ *   stores the slider's position on a `0`–`100` range unless the field
+ *   declares other bounds, and every first-party `progress` field declares
+ *   `min: 0, max: 100`. So its number IS percentage points.
+ *
+ * @param field the field definition the face holds. Only `type` and `max`
+ *              are read, and a `max` that is not a number is not a
+ *              declaration.
+ */
+export declare function percentCellScale(field: {
+    type?: string;
+    max?: unknown;
+} | null | undefined): PercentScale;
+/**
+ * Render a percent on a value ALREADY in display magnitude (`80` means 80%):
+ * the ONE rendering call every display face of a `percent` field makes.
+ * `formatPercent` (the table cell, and every face that takes the cell's
+ * formatter by reference) and `PercentField`'s read-only branch in a form both
+ * end here, so
+ * the locale's percent convention, the grouping and the width cannot part
+ * between them (objectui#11444). The read-only face printed
+ * `toDisplay(value).toFixed(scale)` plus a literal `%`: a `scale: 2` field
+ * holding `0.25` read `25.00%` in a `de` form while its cell read `25,00 %`.
+ *
+ * The SCALING is the caller's, and it is a separate statement on purpose:
+ * both callers scale at the storage the field DECLARES, read through the
+ * spec's `percentScaleOf` (a fraction unless the field declares a `max` above
+ * 1, the rule the edit input writes by). `formatPercent` takes it as its
+ * `percentScale` argument, which the cell answers with
+ * {@link percentCellScale}; `PercentField` asks `percentScaleOf` itself, so
+ * its read-only text and its input never show one stored value at two
+ * magnitudes. Until objectui#11475 the cell guessed the storage from the
+ * value's magnitude instead, so a fraction-stored `1` (100%) read `100%` in a
+ * read-only form and `1%` in its cell, and a whole-stored `0.5` read `0.5%`
+ * and `50%`.
+ * ⛔ Do not add a caller with a scaling rule of its own, and ⛔ never one keyed
+ * on the column's NAME: objectui#9452 removed exactly that from
+ * `PercentCellRenderer`.
+ *
+ * @param displayValue the percentage points to render.
+ * @param precision    the decimal places, fixed at both bounds: the width the
+ *                     caller resolved (`resolveFieldScale`, ruling A′).
+ * @param locale       the display locale tag, from `useDisplayLocale()`.
+ */
+export declare function formatPercentPoints(displayValue: number, precision: number, locale?: string): string;

package/dist/widgets/numberBadInput.d.ts

@@ -0,0 +1,135 @@
+import { default as React } from 'react';
+import { TranslateFn } from './file-size-guard.js';
+/**
+ * ONE reading of "this box is showing text the browser cannot read", shared by
+ * every `type="number"` widget in this package (objectui#6780).
+ *
+ * ## The defect this closes
+ *
+ * A `type="number"` box can DISPLAY one thing and hold another, with nothing
+ * said. Measured on Chromium 141.0.7390.37 (Playwright 1.62.1), typing `1e`
+ * into an empty number input:
+ *
+ * ```
+ * .value            = ""            <- what every widget here reads
+ * validity.badInput = true          <- what the browser actually thinks
+ * pixels vs an untouched box: DIFFERENT   <- the box IS still showing `1e`
+ * ```
+ *
+ * So the widget emitted `null`, `aria-invalid` stayed `"false"`, and no
+ * diagnostic was drawn: objectui#6716's silent-refusal class, on a money field.
+ *
+ * ## Why `validity.badInput` and not a regex of our own
+ *
+ * It is the PLATFORM's own predicate — the browser stating, in its own words,
+ * whether it can read the text — rather than a second renderer-side dialect of
+ * "what a number is" (AGENTS.md #0.1).
+ *
+ * ⚠️ objectui#6765 recorded `badInput` as "the ONE signal happy-dom and Chromium
+ * agree on". objectui#6780 measured that and NARROWED it, because the
+ * difference decides which strings a unit test may drive: in Chromium
+ * `badInput` is never true for a programmatic `.value` write (it reports that
+ * the UA cannot read the USER's input), so on the only route a happy-dom test
+ * has, the two engines agree on nothing. The agreement this guard rests on is
+ * between happy-dom's programmatic verdict and Chromium's TYPED verdict, and it
+ * holds for a measured subset — four strings agree on "bad", seven agree on
+ * "fine", and eight disagree. The full matrix, and the lists the tests are
+ * allowed to use, are in `__tests__/numberInputBrowserReadings.ts`.
+ *
+ * ⭐ And it is NOT objectui#6715's anchored guard wearing a different hat.
+ * That one was measured to be a provable no-op here — it rejects only strings
+ * this test environment fabricates. This one fires on keyboard-reachable
+ * states, MEASURED in Chromium by typing each key by key into an empty box:
+ *
+ * ```
+ * typed "1e"  "1e-"  "1e+"  "-"  "."  "+"  "-."  "e"  "5e"   -> badInput TRUE
+ * typed "1."  "1e5"  "1.2.3"  "0x10"  "12abc"                -> badInput false
+ * ```
+ *
+ * and never on anything the browser can actually emit: `12`, `1.23`, `010`,
+ * `15`, `1`, `12.345` all read `badInput === false`.
+ *
+ * ## ⛔ What this deliberately does NOT do: change what is emitted
+ *
+ * objectui#6716's shape REFUSES (its `onChange` never fires and the prior value
+ * stands). Here that would destroy the very text the diagnostic points at, so
+ * these widgets keep emitting exactly what they emitted before and only stop
+ * being silent about it. MEASURED, in both halves:
+ *
+ *  - Chromium: after typing `1e`, a script write of `.value` clears the raw
+ *    display and flips `badInput` back to `false` — even writing `""`.
+ *  - React 19.2.8's own `updateInput` (`react-dom/cjs/react-dom-client.
+ *    development.js`) restores a number input with
+ *    `if ((0 === value && "" === element.value) || element.value != value)
+ *    element.value = "" + getToStringValue(value);`
+ *
+ * So for a box that already held `5`, refusing leaves `props.value` at `5`,
+ * `element.value` at `""`, and React writes `"5"` back — wiping the `5e` the
+ * user is looking at and the message is about. Emitting keeps `props.value` at
+ * `""`, the write is skipped, and the raw text survives, which is what
+ * objectui#6716 requires of a refusal ("keeps the refused text in the box, so
+ * the message has something to point at").
+ *
+ * ⚠️ The text itself is NOT quotable. The browser displays it but never exposes
+ * it — `.value` is `""` and there is no other channel — so unlike
+ * objectui#6715's residue message this one cannot name what was typed. It
+ * points at the box instead.
+ */
+/**
+ * The one sentence, in objectui#6716's `Not saved: …` shape, read from the
+ * package's locale channel (objectui#8148).
+ *
+ * objectui#6755 ruled that a widget's OWN refusal sentence goes through
+ * `useFieldTranslation` + `FIELD_DEFAULTS`; `320374d2a` applied it to
+ * `LocationField`'s residue arm. This was the FIFTH such sentence and the only
+ * SHARED one — the four already keyed are each one widget's, while this literal
+ * served `NumberField`, `CurrencyField`, `PercentField` and both of
+ * `GeolocationField`'s boxes through {@link useBadInputRefusal}. Its sharpest
+ * consequence: `GeolocationField` sits beside `LocationField`, whose refusals
+ * are all keyed, so two adjacent coordinate widgets refused bad input in two
+ * different languages on one form.
+ *
+ * ⭐ `example` stays a HOLE rather than being keyed per widget, and that is
+ * what keeps the decimal numerals out of every pack. Five different values
+ * reach this one sentence — `1234`, `1234.56`, `12.5`, `30.2741`, `120.1551` —
+ * so a per-widget key would need five keys times ten packs, and each pack would
+ * then hold a decimal numeral it could legitimately re-punctuate. A pack that
+ * wrote `1234,56` would read as the `latitude, longitude` PAIR the adjacent
+ * widget asks for; the hole is filled by the widget in ASCII and no pack ever
+ * spells a digit.
+ *
+ * The English value is byte-identical to the literal it replaces, so English
+ * and provider-less rendering are unchanged.
+ */
+export declare function badInputMessage(t: TranslateFn, example: string): string;
+/**
+ * The widget's OWN refusal state, and the reader that fills it.
+ *
+ * Named `refusal`, never `error`: `error` is the published validation slot on
+ * the widget contract (objectui#3222) with exactly one author, the form
+ * renderer. This is the widget's own reading, which no host can produce — the
+ * same two-name split `LocationField` uses (objectui#6716).
+ *
+ * `readBadInput` is called from BOTH arms, because neither alone sees every
+ * route (MEASURED in Chromium):
+ *
+ *  - TYPED `1e` into an empty box fires 2 `input` events — the `e` keystroke
+ *    moves `.value` from `"1"` to `""`, so React does deliver an `onChange`.
+ *  - PASTED `1e` into an empty box fires 1 `input` event, but `.value` never
+ *    leaves `""`; React's own input-value tracking suppresses the synthetic
+ *    `onChange`, so the CHANGE arm never runs. Blur fires, and `badInput` is
+ *    still `true` at blur time — which is the whole reason for the blur arm.
+ */
+export declare function useBadInputRefusal(example: string): {
+    refusal: string | null;
+    readBadInput: (target: HTMLInputElement | null | undefined) => boolean;
+};
+/**
+ * The drawn diagnostic — objectui#6716's exact markup, in one spelling so the
+ * four widgets of this class cannot drift apart.
+ */
+export declare function BadInputMessage({ refusal }: {
+    refusal: string | null;
+}): React.JSX.Element | null;
+/** The class that marks the refused control, in one spelling. */
+export declare const BAD_INPUT_BORDER = "border-red-500 focus-visible:ring-red-500";

package/dist/widgets/personDisplay.d.ts

@@ -13,8 +13,22 @@
  */
 /** Resolve a possibly-dotted path (e.g. `primary_business_unit_id.name`) against a record. */
 export declare function resolvePath(record: any, path: string): any;
-/** Best display name for a person record, tolerating expanded / raw shapes. */
-export declare function getPersonName(record: any, nameField?: string): string;
+/**
+ * The fields a person's display name is read from, in order: the configured
+ * display field, then `name`, `username`, `label`. A caller that gates the name
+ * by field-level security filters THIS list and hands the rest to
+ * {@link getPersonName} (objectui#10535): a denied rung is skipped, so the name
+ * falls through to the next readable one — the row a stripping backend serves
+ * reads the same.
+ */
+export declare function getPersonNameFields(nameField?: string): string[];
+/**
+ * Best display name for a person record, tolerating expanded / raw shapes: the
+ * first field of the name ladder the record holds a value for. `nameField` is
+ * the configured display field, whose ladder is {@link getPersonNameFields}, or
+ * the ladder itself, already filtered to the fields the viewer may read.
+ */
+export declare function getPersonName(record: any, nameField?: string | readonly string[]): string;
 /**
  * Up-to-2-char initials for the avatar fallback.
  * - "John Doe" → "JD"; "John" → "JO"
@@ -23,8 +37,12 @@ export declare function getPersonName(record: any, nameField?: string): string;
 export declare function getPersonInitials(name: string): string;
 /** Secondary line: resolve each field path, drop empties, join with " · ". */
 export declare function getPersonSubtitle(record: any, fields?: string[]): string;
-/** Avatar image URL (defaults to `sys_user.image`); undefined when absent. */
-export declare function getPersonAvatarUrl(record: any, avatarField?: string): string | undefined;
+/**
+ * Avatar image URL (defaults to `sys_user.image`); undefined when absent, and
+ * when `avatarField` is `null` — no avatar field to read, e.g. one field-level
+ * security withholds (objectui#10433).
+ */
+export declare function getPersonAvatarUrl(record: any, avatarField?: string | null): string | undefined;
 /** Record id, tolerating `id` / `_id` / a custom id field. */
 export declare function getPersonId(record: any, idField?: string): any;
 /**