@object-ui/fields 17.6.0 → 17.7.0

package/dist/widgets/RecordPickerDialog.d.ts

@@ -41,7 +41,12 @@ export interface RecordPickerFilterBarProps {
  * Allows plugging in ObjectGrid or any compatible table component.
  */
 export interface RecordPickerGridSlotProps {
-    /** Resolved column definitions */
+    /**
+     * Resolved column definitions, less the ones field-level security denies
+     * once the permission policy has loaded, the display column included — the
+     * columns the built-in table draws (objectui#10373). When none survives,
+     * this is the id column alone.
+     */
     columns: LookupColumnDef[];
     /** Current page of records */
     records: any[];
@@ -93,16 +98,30 @@ export interface RecordPickerDialogProps {
     objectName: string;
     /** Columns to display. Defaults to [displayField, descriptionField]. */
     columns?: Array<string | LookupColumnDef>;
-    /** Primary display field (default: 'name') */
+    /**
+     * The display field as the lookup DECLARES it. The display column is keyed on
+     * it, or on `'name'` when it is omitted. With `objectSchema` given, a declared
+     * value is also the first rung of the column's title (the resolver's
+     * `titleField`); the `'name'` default never is, because it is a guess and a
+     * guess never outranks the referenced object's own declarations. So pass
+     * `undefined` when the field declares none, never a pre-filled `'name'`.
+     */
     displayField?: string;
     /**
-     * Optional `titleFormat` template (e.g. `"{full_name}"` or
-     * `"{case_number} - {subject}"`). When set and the displayField column is
-     * auto-inferred, the column renders via the template instead of reading
-     * a possibly-missing field. Mirrors how DetailView/ObjectCalendar resolve
-     * record titles.
+     * The referenced object's schema (objectui#10486). When given, the display
+     * column renders each record's title through `@object-ui/core`'s
+     * `getRecordDisplayName`, the call LookupField's dropdown option label and
+     * the read cell make: the declared `displayField`, then the object's
+     * `nameField`, then its deprecated `titleFormat` template, then type-aware
+     * derivation (ADR-0079). The title reads the row with its relations
+     * collapsed to ids and the fields the loaded policy denies removed, exactly
+     * as the dropdown's option label does.
+     *
+     * Replaces the retired `titleFormat` prop: a bare template cut out of the
+     * schema ranked above the `nameField` beside it, so the picker and the
+     * dropdown labelled one record two ways.
      */
-    titleFormat?: string | null;
+    objectSchema?: Record<string, unknown> | null;
     /** Record id field (default: 'id') */
     idField?: string;
     /** Page size (default: 10) */
@@ -119,7 +138,7 @@ export interface RecordPickerDialogProps {
     onSelectRecords?: (records: any[]) => void;
     /**
      * Base filters applied to every query.
-     * Converted from LookupFieldMetadata.lookup_filters.
+     * Converted from LookupFieldMetadata.lookupFilters.
      * Restricts which records are selectable (e.g. only active records).
      */
     lookupFilters?: LookupFilterDef[];
@@ -145,7 +164,7 @@ export interface RecordPickerDialogProps {
      *   (`before`, `after`, `is_empty`, `is_not_empty`) the record form has no
      *   `$op` for. No second operator vocabulary is introduced here: two already
      *   exist (the spec's `AST_OPERATOR_MAP`, data-objectstack's
-     *   `FILTER_OPERATOR_ALIASES`) and #3948 is what a third costs.
+     *   `FILTER_OPERATOR_ALIASES`) and objectstack-ai/objectstack#3948 is what a third costs.
      *
      * The discriminator is exact rather than heuristic — every AST node is an
      * ARRAY and a rule is a plain OBJECT, the same predicate `toFilterNode` uses.
@@ -168,7 +187,7 @@ export interface RecordPickerDialogProps {
      * The referenced object's schema `fields` map (field name → field
      * definition). When provided, cell renderers receive the FULL field
      * metadata — `options`, `currency`, `scale`, `precision`, `format`,
-     * `reference_to`, … — exactly like the list view enriches its columns from
+     * `reference`, … — exactly like the list view enriches its columns from
      * the object schema. Without it a `select` column falls back to
      * title-casing the raw stored value instead of resolving the option label
      * (#3333: `manufacturing` rendered as "Manufacturing" instead of the
@@ -225,4 +244,4 @@ export interface RecordPickerDialogProps {
  * states, and single/multi-select.  Responsive: mobile-friendly width
  * via Tailwind breakpoints.
  */
-export declare function RecordPickerDialog({ open, onOpenChange, title, multiple, dataSource, objectName, columns: columnsProp, displayField, titleFormat, idField, pageSize, value, onSelect, onSelectRecords, lookupFilters, baseFilter, cellRenderer, fieldsMeta, filterColumns, renderFilterBar, renderGrid, }: RecordPickerDialogProps): React.JSX.Element;
+export declare function RecordPickerDialog({ open, onOpenChange, title, multiple, dataSource, objectName, columns: columnsProp, displayField: declaredDisplayField, objectSchema, idField, pageSize, value, onSelect, onSelectRecords, lookupFilters, baseFilter, cellRenderer, fieldsMeta, filterColumns, renderFilterBar, renderGrid, }: RecordPickerDialogProps): React.JSX.Element;

package/dist/widgets/RichTextField.d.ts

@@ -23,7 +23,7 @@ import { FieldWidgetComponentProps } from './types.js';
  * from the shared `FullscreenFieldEditor`, so one form-level setting keeps
  * producing one behaviour across both widgets.
  *
- * ## Readonly display (objectui#5498)
+ * ## Readonly display (`4bb940b6e`)
  *
  * The readonly early return used to render `{value}` as a React TEXT CHILD,
  * so a readonly field of any of the three types showed the user the markup

package/dist/widgets/SelectionTray.d.ts

@@ -12,7 +12,18 @@ export interface SelectionTrayProps {
     /** Remove a selected record by its id. */
     onRemove: (id: any) => void;
     displayField?: string;
-    avatarField?: string;
+    /**
+     * The fields each chip's name is read from, in order; defaults to the ladder
+     * of `displayField` (`getPersonNameFields`). PeoplePicker passes the fields
+     * of that ladder the loaded policy lets the viewer read (objectui#10535).
+     */
+    nameFields?: string[];
+    /**
+     * Avatar image field (default `image`). `null` draws no image, only the
+     * initials: what PeoplePicker passes when field-level security withholds the
+     * field (objectui#10433).
+     */
+    avatarField?: string | null;
     idField?: string;
     /** Header label, e.g. "Selected (3)" — omit to hide the header. */
     label?: string;
@@ -24,4 +35,4 @@ export interface SelectionTrayProps {
     emptyText?: string;
     className?: string;
 }
-export declare function SelectionTray({ records, onRemove, displayField, avatarField, idField, label, onClear, clearLabel, emptyText, className, }: SelectionTrayProps): React.JSX.Element;
+export declare function SelectionTray({ records, onRemove, displayField, nameFields, avatarField, idField, label, onClear, clearLabel, emptyText, className, }: SelectionTrayProps): React.JSX.Element;

package/dist/widgets/TextField.d.ts

@@ -4,4 +4,4 @@ import { FieldWidgetComponentProps } from './types.js';
  * TextField - Standard single-line or multi-line text input
  * Automatically renders as a textarea when rows are configured in field metadata
  */
-export declare function TextField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;
+export declare function TextField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;

package/dist/widgets/TimeField.d.ts

@@ -4,4 +4,4 @@ import { FieldWidgetComponentProps } from './types.js';
  * TimeField - Time picker input widget
  * Uses native time input for hour and minute selection
  */
-export declare function TimeField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;
+export declare function TimeField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;

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

@@ -56,7 +56,7 @@ export declare function resolveSchemaOptions(meta: {
  * 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` / `reference_to` through to the lookup cell renderer so
+ * 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
@@ -68,9 +68,21 @@ export interface LookupColumnRenderContext {
     descriptors: Record<string, any>;
     /** Type-aware renderer resolver; when absent every cell degrades to text. */
     cellRenderer?: LookupCellRendererResolver;
-    /** The referenced object's `titleFormat`, applied to the display column. */
-    titleFormat?: string | null;
-    /** The lookup's display field — the column the title template stands in for. */
+    /**
+     * 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;
@@ -79,9 +91,14 @@ export interface LookupColumnRenderContext {
  * Render one column of one candidate record.
  *
  * Order:
- *   1. `titleFormat` template, for the display column only — so users see a
- *      human-readable name instead of a raw id when the display field
- *      (commonly defaulted to `name`) does not exist on the record.
+ *   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.
  *

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";