@object-ui/fields 17.6.0 → 18.0.0

package/dist/widgets/date-picker/localeDateText.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The display text for a native-shaped value (`YYYY-MM-DD`, or
+ * `YYYY-MM-DDTHH:mm` when `withTime`). `''` for an empty or unreadable value.
+ */
+export declare function formatLocaleDateText(value: string, locale: string, withTime: boolean): string;
+/**
+ * The pattern the text box expects, for its placeholder: the locale's own
+ * order and separators with `YYYY` / `MM` / `DD` (and `HH` / `mm`) in place of
+ * the digits.
+ */
+export declare function localeDatePattern(locale: string, withTime: boolean): string;
+/**
+ * Reads what was typed into the text box.
+ *
+ * Returns `''` for blank text, the native-shaped value for a real day (and a
+ * real clock time when `withTime`), and `null` for text that names no real
+ * date. Accepted:
+ *
+ *   - the locale's own digit order, with any separators (`10/16/2026` in `en`,
+ *     `2026/10/16` in `zh`, `16.10.2026` in `de`);
+ *   - an ISO date `2026-10-16`, in every locale (a four-digit first group is
+ *     read as the year);
+ *   - a two-digit year, read in this century;
+ *   - with `withTime`: an hour and minute after the date, 24-hour, or 12-hour
+ *     with `AM` / `PM` or the locale's own afternoon marker. With no time, the
+ *     time is midnight.
+ */
+export declare function parseLocaleDateText(text: string, locale: string, withTime: boolean): string | null;
+/** The local calendar day of `d` as `YYYY-MM-DD`. */
+export declare function toLocalDay(d: Date): string;
+/** Local midnight of a `YYYY-MM-DD` day, for the calendar to select. */
+export declare function fromLocalDay(day: string): Date | undefined;

package/dist/widgets/deriveLookupColumns.d.ts

@@ -24,7 +24,7 @@ interface ObjectSchemaLike {
 }
 /**
  * Derive sensible Record Picker columns from a referenced object's schema when
- * a lookup field declares no explicit `lookup_columns`.
+ * a lookup field declares no explicit `lookupColumns`.
  *
  * Priority:
  *   1. The referenced object's ADR-0085 `highlightFields` — the canonical

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

@@ -0,0 +1,63 @@
+import { default as React } from 'react';
+import { FileValueView } from './file-value.js';
+/**
+ * The translated label and hint for a file the reader may not open
+ * (objectui#12339): a value that arrived as the refused marker
+ * `{ id, metadataRefused: true }` carries no name of its own, and drawing the
+ * generic `fields.file.fileFallback` for it would read as an ordinary file.
+ */
+export declare function useRestrictedFileText(): {
+    label: string;
+    hint: string;
+};
+/**
+ * The restricted state of one file value (`view.metadataRefused`): a lock
+ * and the translated "Restricted file" label instead of a name, and ⛔ no
+ * thumbnail — no MIME type was served, so there is nothing to decide one on.
+ *
+ * It stays an anchor to the view's id-derived URL: whether this reader may
+ * download the file is the download endpoint's own decision, and it may
+ * answer `403 FILE_DOWNLOAD_DENIED`. The accessible name is the visible
+ * label; the hint rides on `title`.
+ *
+ * `compact` draws the lock alone, for a cell or tile that has no room for
+ * the label — the label then becomes the anchor's `aria-label`.
+ */
+export declare function RestrictedFileAffordance({ view, className, compact, icon, }: {
+    view: FileValueView;
+    className?: string;
+    compact?: boolean;
+    /** Suppressed where the row already draws its own icon to the left. */
+    icon?: boolean;
+}): React.ReactElement;
+/**
+ * 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-refused.d.ts

@@ -0,0 +1,17 @@
+import { FileRefusedValue } from '@objectstack/spec/data';
+/**
+ * Is this value the platform's refused marker `{ id, metadataRefused: true }`?
+ *
+ * Judged by the spec's own closed `FileRefusedValueSchema`, not by a second
+ * hand-written shape here: an object with any other key is not the marker,
+ * and reads through `readFileValue`'s ordinary object arm.
+ */
+export declare function isFileRefusedValue(value: unknown): value is FileRefusedValue;
+/**
+ * One element of a field value as an editable widget re-submits it beside or
+ * after an edit (append, remove, crop): the refused marker is reduced to its
+ * bare `sys_file` id — the stored form — and ⛔ never sent back as the marker
+ * object, which is a read form no record write accepts. Every other element
+ * passes through untouched, as before.
+ */
+export declare function fileValueForResubmit(value: unknown): unknown;

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,12 +3,28 @@ 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;
     size?: number;
     mimeType?: string;
+    /**
+     * `true` when the value is the platform's refused marker
+     * `{ id, metadataRefused: true }` (`FileRefusedValueSchema`): the reader may
+     * read the record but not this file's `sys_file` metadata, so no name, size,
+     * MIME type or URL was served. The view still carries `id` and the
+     * id-derived `url` — the download endpoint judges its own access and may
+     * answer `403 FILE_DOWNLOAD_DENIED` — but a renderer draws a restricted
+     * state rather than a generic file chip, and never attempts a thumbnail
+     * (objectui#12339). Absent on every other form.
+     */
+    metadataRefused?: true;
     /** The value as it arrived, so callers can pass it through untouched. */
     raw: unknown;
 }
@@ -29,9 +45,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 +90,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/longTextCarrierHandoff.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The key a HOST writes onto a long-text widget's `field` carrier at runtime —
+ * wider than the shape an author may WRITE, on purpose (objectui#12242,
+ * maintainer ruling A, under AGENTS.md #0.1 and the objectui#6356 pattern).
+ *
+ * `mobile_fullscreen` is a projection of the FORM-level setting
+ * `ObjectFormSchema.mobile.fullscreenLongText`. Its one producer is
+ * `ObjectForm` (`@object-ui/plugin-form`), which stamps it onto the carrier
+ * the form renderer hands each long-text widget (`f.field || f`) while it
+ * builds the form. Its consumers are `TextAreaField` and `RichTextField` here,
+ * which read it off `field` and nowhere else (objectui#3245), and the form
+ * renderer's built-in `textarea` branch in `@object-ui/components`, which
+ * reads it off its own props. Nobody authors it: `@objectstack/spec`'s
+ * `FieldSchema` refuses the key by name, so no published object can carry it,
+ * and `@object-ui/types`' field metadata types no longer declare it.
+ *
+ * ⛔ Deliberately NOT exported from this package's index, and ⛔ never to be
+ * added back to `@object-ui/types`: the authoring face refuses the key, and a
+ * public type naming it would invite the spelling that face refuses.
+ */
+export interface LongTextCarrierHandoff {
+    /**
+     * Draw the fullscreen-edit affordance (an "expand" button opening a
+     * full-height dialog) beside the inline editor. Absent when the form did
+     * not opt in.
+     */
+    mobile_fullscreen?: boolean;
+}

package/dist/widgets/lookupColumnDisplay.d.ts

@@ -23,7 +23,7 @@ export type SchemaOption = {
 /** 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
+ * Normalise a lookupColumns entry (string | LookupColumnDef) into a
  * concrete LookupColumnDef object.
  */
 export declare function normalizeColumn(col: string | LookupColumnDef): LookupColumnDef;
@@ -56,11 +56,11 @@ 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
- * string-authored `lookup_columns` format identically to object-authored ones.
+ * string-authored `lookupColumns` 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 {
@@ -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;