@object-ui/i18n 17.6.0 → 18.0.0

package/dist/useObjectLabel.js

@@ -11,6 +11,7 @@
  * | What               | Auto-generated key                              | Fallback              |
  * |--------------------|-------------------------------------------------|-----------------------|
  * | Object label       | {ns}.objects.{objectName}.label                  | objectDef.label       |
+ * | Object plural      | {ns}.objects.{objectName}.pluralLabel            | objectDef.pluralLabel, then the object label |
  * | Object description | {ns}.objects.{objectName}.description             | objectDef.description |
  * | Field label        | {ns}.fields.{objectName}.{fieldName}              | field.label           |
  *
@@ -108,9 +109,10 @@ export function useObjectLabel() {
          * include crm.objects.* or crm.apps.*.
          *
          * `globalActions` is included so an app bundle whose only translated scope
-         * is global actions (no object/field entries) is still discovered — its
-         * `globalActions.<action>.*` overlays would otherwise be unreachable
-         * (objectui#3372).
+         * is global actions (no object/field entries) is still discovered — the
+         * `globalActions.<action>.*` copy of its object-less actions would otherwise
+         * be unreachable (objectui#3372; object-less only since objectui#11439, see
+         * `actionSuffixes`).
          */
         const getAppNamespaces = () => {
             if (!hasUsableI18nInstance(i18n))
@@ -168,28 +170,35 @@ export function useObjectLabel() {
         };
         /**
          * Build suffix candidates for an action-scoped key, mirroring the canonical
-         * `@objectstack/spec` resolver (`lookupActionField` in `system/i18n-resolver`).
+         * `@objectstack/spec` resolver (`actionTranslationNode` behind
+         * `lookupActionField`, in `system/i18n-resolver`): ONE node per action, chosen
+         * by its key object.
          *
-         * When the action is object-scoped, the object key
-         * (`objects.<obj>._actions.<action>.<tail>`) wins, but the global key
-         * (`globalActions.<action>.<tail>`) is appended as a fallback so a
-         * **globalAction surfaced on an object's action bar** still picks up its
-         * `globalActions.<action>.*` overlay when no object-scoped translation
-         * exists (objectui#3372). Without this fallback, a globalAction rendered on
-         * a record-detail action bar — where the caller passes `objectDef.name` for
-         * every action — misses `objects.<obj>._actions.<action>.label` and leaks the
-         * English metadata literal.
+         * `objectName` is the action's KEY object — the object the action belongs
+         * to: its declared `objectName`, else the host object that embeds it, which
+         * is what the spec's `translateObject` stamps on an embedded action. Callers
+         * pass that object (`useActionTextLocalizer` derives it from the action).
          *
-         * Object-less actions (`objectName` omitted) resolve straight to the global
-         * namespace, as before. Object precedence is preserved: the global key is
-         * only consulted after every object-scoped candidate misses.
+         * - A key object reads `objects.<obj>._actions.<action>.<tail>` and nothing
+         *   else.
+         * - No key object reads `globalActions.<action>.<tail>` and nothing else.
+         *
+         * There is deliberately NO object-then-global chain. objectui#3372 added one
+         * so `globalActions` copy reached actions drawn on an object's bar; the
+         * spec's `TranslationDataSchema.globalActions` is for actions "not bound to a
+         * specific object via `objectName`", `@objectstack/spec` 17.7.0 never reads it
+         * for a bound action, and objectui#11439 (triage's amended ruling) retired the
+         * chain so this client and the server resolve one bundle entry the same way.
+         * A bound action's copy filed under `globalActions` now misses on every
+         * surface alike and the authored text shows — the misfiling is what
+         * `os validate` already refuses, and it is fixed in the bundle, not here.
+         *
+         * The two object-name candidates (`objects.<ns__obj>` then `objects.<obj>`)
+         * are a separate axis and stay — see `stripNamespace`.
          */
-        const actionSuffixes = (objectName, actionName, tail) => {
-            const globalSuffix = `globalActions.${actionName}.${tail}`;
-            return objectName
-                ? [...objectSuffixes(objectName, `_actions.${actionName}.${tail}`), globalSuffix]
-                : [globalSuffix];
-        };
+        const actionSuffixes = (objectName, actionName, tail) => objectName
+            ? objectSuffixes(objectName, `_actions.${actionName}.${tail}`)
+            : [`globalActions.${actionName}.${tail}`];
         const fieldSuffixes = (objectName, fieldName) => {
             const base = stripNamespace(objectName);
             return base !== objectName
@@ -242,8 +251,8 @@ export function useObjectLabel() {
          * name under `_views` — the runtime view identity's own name, stripped of the
          * object prefix. That single spelling is canonical per the objectstack#5164
          * ruling A (2026-08-06): the i18n extractor asks the view composer for the key
-         * (objectstack#6124) and `packages/lint` enforces exactly that spelling
-         * (objectstack#6038), so this resolver accepts exactly what those produce.
+         * (objectstack `b3c1f3cd5`) and `packages/lint` enforces exactly that spelling
+         * (objectstack `7618ee814`), so this resolver accepts exactly what those produce.
          *
          * Deliberately NOT a second candidate: the prefixed full name
          * (`_views.<objectName>.<viewName>`). Accepting it made this client more
@@ -268,11 +277,37 @@ export function useObjectLabel() {
             const bareViewName = matchedPrefix ? viewName.slice(matchedPrefix.length) : viewName;
             return objectSuffixes(objectName, `_views.${bareViewName}.${tail}`);
         };
+        /** The singular object label; `objectPluralLabel` falls back to it. */
+        const objectLabel = (objectDef) => resolve(objectSuffixes(objectDef.name, 'label'), objectDef.label);
         return {
             /**
              * Resolve translated object label, falling back to objectDef.label.
              */
-            objectLabel: (objectDef) => resolve(objectSuffixes(objectDef.name, 'label'), objectDef.label),
+            objectLabel,
+            /**
+             * Resolve the object's PLURAL label — what a list of its records is called:
+             * an object list page's title and the breadcrumb segment that links to that
+             * list (objectui#11696). Record-scoped surfaces (the record page, a record
+             * drawer, "New …") keep {@link objectLabel}.
+             *
+             * Order: the translated plural (`{ns}.objects.{objectName}.pluralLabel`),
+             * else the declared `objectDef.pluralLabel`, else the singular as
+             * `objectLabel` resolves it — `pluralLabel` is optional in the spec, and an
+             * object that declares none is called by its label everywhere.
+             *
+             * The first two rungs are the client half of `translateObject` in
+             * `@objectstack/spec` (`system/i18n-resolver`), which serves `pluralLabel`
+             * as the catalog entry, else the authored value. There is deliberately NO
+             * rung that prefers a translated SINGULAR over a declared plural the bundle
+             * leaves untranslated: the server has none either, so every consumer of
+             * `/meta` shows the authored plural in that case, and this client showing
+             * something else would be a second dialect (see `viewSuffixes`). The gap is
+             * the bundle's — `os i18n extract` writes `pluralLabel` wherever the object
+             * declares one — and is fixed there.
+             */
+            objectPluralLabel: (objectDef) => resolve(objectSuffixes(objectDef.name, 'pluralLabel'), '')
+                || objectDef.pluralLabel
+                || objectLabel(objectDef),
             /**
              * Resolve translated object description, falling back to objectDef.description.
              */
@@ -328,15 +363,17 @@ export function useObjectLabel() {
              * reaches this client — so nav labels arrive already localized. One
              * owner, not two. To translate a sidebar group, translate it there.
              *
-             * History (objectui#5197): until then this docstring promised
+             * History (`9c60144b5`): until then this docstring promised
              * `"Sales" → "销售"` for sidebar groups, and `NavigationRenderer`
              * accepted `resolveGroupLabel`/`resolveItemLabel` to wire it up. Those
              * props could never fire — the renderer's `isCustomized` guard compared a
              * node's authored label against its own `id` (`Workspace` vs
              * `grp_workspace`), which never match, so the guard was true for every
-             * real entry. The props are gone; the promise was false, not merely
-             * unused. This helper is kept as a plain key reader for a consumer that
-             * renders navigation itself — it has no first-party caller.
+             * real entry. The props are gone, and so is the guard itself
+             * (objectui#11201: the renderer no longer matches a label's text against
+             * any name); the promise was false, not merely unused. This helper is kept
+             * as a plain key reader for a consumer that renders navigation itself — it
+             * has no first-party caller.
              */
             navGroupLabel: (appName, groupId, fallback) => resolve(`apps.${appName}.navigation.${groupId}.label`, fallback),
             /**
@@ -371,39 +408,17 @@ export function useObjectLabel() {
              * Resolve translated widget description within a dashboard.
              * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.description`.
              * Returns undefined when neither metadata nor translation provides one.
+             *
+             * This is a widget's ONE translated description. The sibling sub-caption
+             * key, `widgets.{widgetId}.subCaption`, is retired with its resolver
+             * (objectui#11389, ruling C): `@objectstack/spec` 17.7.0 refuses it by
+             * name in a translation bundle, and nothing here reads it.
              */
             widgetDescription: (dashboardName, widgetId, fallback) => {
                 const fb = fallback ?? '';
                 const resolved = resolve(dashboardSuffixes(dashboardName, `widgets.${widgetId}.description`), fb);
                 return resolved || undefined;
             },
-            /**
-             * Resolve a translated metric-widget SUB-CAPTION within a dashboard.
-             * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.subCaption`.
-             * Returns undefined when neither metadata nor translation provides one.
-             *
-             * Deliberately its OWN key, not a second reader of `widgets.{id}.description`.
-             * The KPI card renders two authored strings from two different fields — the
-             * shared card header's `widget.description`, and the sub-caption under the
-             * value, which is authored as `widget.options.description` — and the
-             * objectstack#5428 item-4 ruling (2026-08-06) settled that they get two
-             * keys, not one: 「两个作者字段两个 key」. Collapsing them would make one
-             * translation entry silently retarget the other field on any widget type
-             * that renders both at once (`kpi`, `gauge`, `bullet` — every metric-family
-             * type except the self-contained `metric`).
-             *
-             * `subCaption` is the member objectstack#8056 added to the widget
-             * translation node for exactly this, shipped in `@objectstack/spec@17.0.0`.
-             * The server-side resolver reads the SAME key and overlays it onto
-             * `options.description` (`translateDashboard`), so a document served
-             * through `/meta` and a document translated here land on the same string —
-             * this is the client half of one convention, not a second dialect.
-             */
-            widgetSubCaption: (dashboardName, widgetId, fallback) => {
-                const fb = fallback ?? '';
-                const resolved = resolve(dashboardSuffixes(dashboardName, `widgets.${widgetId}.subCaption`), fb);
-                return resolved || undefined;
-            },
             /**
              * Resolve translated page label, falling back to pageDef.label.
              * Convention: `{ns}.pages.{pageName}.label`.
@@ -422,15 +437,27 @@ export function useObjectLabel() {
              * that spells the prefix out does not resolve (see `viewSuffixes`).
              */
             viewLabel: (objectName, viewName, fallback) => resolve(viewSuffixes(objectName, viewName, 'label'), fallback),
-            /**
-             * Resolve translated list-view description.
-             * Convention: `{ns}.objects.{objectName}._views.{viewName}.description`.
+            /*
+             * There is deliberately NO `viewDescription` member here, and no
+             * `{ns}.objects.{objectName}._views.{viewName}.description` convention for
+             * it to resolve (objectui#7219, maintainer ruling 2026-09-02, option B).
+             *
+             * A list view's description has exactly ONE channel: the `I18nLabel` value
+             * authored on the view entry -- a string or an inline locale map -- which
+             * `ObjectView` relays and the render site resolves with `pickLocalized`
+             * (objectui#7199). The catalog key used to be declared and resolved right
+             * here, between its two wired-up siblings, but had zero callers and zero
+             * in-repo bundle usage: a bundle entry written under it reached no screen.
+             *
+             * Wiring it in instead was weighed and NOT taken -- two vocabularies for
+             * one concept plus a precedence rule is the ambiguity, not the fix. Leaving
+             * it declared and unfulfilled was not taken either; the standing rule is
+             * remove, not phase out, when a surface has measured zero use.
+             *
+             * `viewSuffixes` is NOT retired with it: `viewLabel` above and
+             * `viewEmptyState` below share that helper and keep resolving. Only the
+             * `'description'` tail passed to it is gone.
              */
-            viewDescription: (objectName, viewName, fallback) => {
-                const fb = fallback ?? '';
-                const resolved = resolve(viewSuffixes(objectName, viewName, 'description'), fb);
-                return resolved || undefined;
-            },
             /**
              * Resolve translated list-view emptyState. Returns a {title, message}
              * tuple with each field independently translated. Convention:
@@ -455,17 +482,18 @@ export function useObjectLabel() {
             sectionLabel: (objectName, sectionName, fallback) => resolve(objectSuffixes(objectName, `_sections.${sectionName}.label`), fallback),
             /**
              * Resolve translated action label.
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.label`,
-             * falling back to `{ns}.globalActions.{actionName}.label` — both when
-             * objectName is omitted AND when the object-scoped key misses (so a
-             * globalAction surfaced on a record-detail action bar still resolves;
-             * objectui#3372).
+             * `objectName` is the action's KEY object (its declared `objectName`, else
+             * the host that embeds it). Convention:
+             * `{ns}.objects.{objectName}._actions.{actionName}.label`; with no key
+             * object, `{ns}.globalActions.{actionName}.label`. Never both: a bound
+             * action does not read `globalActions` (objectui#11439, see
+             * `actionSuffixes`). Every action resolver below follows the same rule.
              */
             actionLabel: (objectName, actionName, fallback) => resolve(actionSuffixes(objectName, actionName, 'label'), fallback),
             /**
              * Resolve translated action confirmation prompt.
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.confirmText`,
-             * falling back to `{ns}.globalActions.{actionName}.confirmText`.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.confirmText`;
+             * with no key object, `{ns}.globalActions.{actionName}.confirmText`.
              * Returns undefined when no translation and no fallback exist.
              */
             actionConfirm: (objectName, actionName, fallback) => {
@@ -475,20 +503,38 @@ export function useObjectLabel() {
             },
             /**
              * Resolve translated action success message.
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.successMessage`,
-             * falling back to `{ns}.globalActions.{actionName}.successMessage`.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.successMessage`;
+             * with no key object, `{ns}.globalActions.{actionName}.successMessage`.
              */
             actionSuccess: (objectName, actionName, fallback) => {
                 const fb = fallback ?? '';
                 const resolved = resolve(actionSuffixes(objectName, actionName, 'successMessage'), fb);
                 return resolved || undefined;
             },
+            /**
+             * Resolve the translated success copy for ONE handler outcome — an entry of
+             * the action's `outcomeMessages` (`@objectstack/spec` 17.6.0, objectui#11344).
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.outcomeMessages.{outcome}`;
+             * with no key object, `{ns}.globalActions.{actionName}.outcomeMessages.{outcome}`
+             * — the addresses the spec's translation bundle declares for the key.
+             * Returns undefined when no translation and no fallback exist.
+             *
+             * Like `actionSuccess`, the answer is a TEMPLATE: a `${result.*}` token in a
+             * bundle entry passes through untouched (i18next interpolates its own
+             * `{{…}}` form, never `${…}`), and the action runner fills it in from the
+             * handler's answer once the action has run.
+             */
+            actionOutcome: (objectName, actionName, outcome, fallback) => {
+                const fb = fallback ?? '';
+                const resolved = resolve(actionSuffixes(objectName, actionName, `outcomeMessages.${outcome}`), fb);
+                return resolved || undefined;
+            },
             /**
              * Resolve translated action description (the explanatory line shown in the
              * action's param dialog / sheet / drawer header).
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.description`.
-             * Falls back to `{ns}.globalActions.{actionName}.description`, then the
-             * metadata's literal string; undefined when nothing resolves.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.description`;
+             * with no key object, `{ns}.globalActions.{actionName}.description`. Falls
+             * back to the metadata's literal string; undefined when nothing resolves.
              */
             actionDescription: (objectName, actionName, fallback) => {
                 const fb = fallback ?? '';
@@ -500,10 +546,9 @@ export function useObjectLabel() {
             /**
              * Resolve a translated copy of an action's post-success RESULT DIALOG
              * (`title` / `description` / `acknowledge` + per-field labels).
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.resultDialog.*`,
-             * falling back to `{ns}.globalActions.{actionName}.resultDialog.*` (when
-             * objectName is omitted OR the object-scoped key misses), then to the
-             * metadata's literal strings.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.resultDialog.*`;
+             * with no key object, `{ns}.globalActions.{actionName}.resultDialog.*`.
+             * Falls back to the metadata's literal strings.
              *
              * The `fields` translation node is keyed by the LITERAL result-field path
              * from the action metadata (may contain dots, e.g. `"user.email"`), so it
@@ -556,7 +601,8 @@ export function useObjectLabel() {
             },
             /**
              * Resolve translated action-PARAMETER text (label / placeholder / helpText).
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.{attr}`.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.{attr}`;
+             * with no key object, `{ns}.globalActions.{actionName}.params.{paramName}.{attr}`.
              * Falls back to the provided value (the metadata's literal string) when no
              * translation exists, so untranslated params keep rendering as authored.
              */
@@ -569,7 +615,8 @@ export function useObjectLabel() {
             },
             /**
              * Resolve a translated action-parameter SELECT OPTION label.
-             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.options.{optionValue}`.
+             * Convention: `{ns}.objects.{objectName}._actions.{actionName}.params.{paramName}.options.{optionValue}`;
+             * with no key object, the same path under `{ns}.globalActions.{actionName}`.
              * Falls back to the provided (English metadata) label when untranslated.
              */
             actionParamOptionLabel: (objectName, actionName, paramName, optionValue, fallback) => {

package/dist/useSafeTranslation.js

@@ -6,21 +6,38 @@
  * returning raw i18n keys — and, for a key the `defaults` map does not carry,
  * to the call site's own inline `t(key, { defaultValue })` (objectui#3865).
  * The lookup order is i18next's, so a provider-less host and a provider-mounted
- * one render the same string: `defaults[key]` (the pack value's stand-in here)
+ * one render the same string: `defaults[key_<category>]` for a numeric `count`
+ * (objectui#11445), then `defaults[key]` (the pack value's stand-in here)
  * -> `defaultValue` -> the key.
  *
  * @param defaults - Fallback English translations keyed by i18n key
  * @param testKey - A key to test if i18n is properly configured (must be in defaults)
  */
 import { useObjectTranslation } from './provider.js';
+import { DEFAULT_VALUE_OPTION, interpolateFallback } from './fallbackInterpolation.js';
 /**
- * The i18next option that names the string to use when the lookup misses.
+ * The plural rules the defaults tables are written in. Every table is English
+ * (the `en` pack's stand-in), so English selects the slot.
+ */
+const DEFAULTS_PLURAL_RULES = new Intl.PluralRules('en');
+/**
+ * The `defaults` row a count family answers from, the way i18next walks a pack
+ * (objectui#11445): `key_<category>` first, then the base `key`.
  *
- * It is a LOOKUP CONTROL, not interpolation data (objectui#3865): it chooses
- * which string is rendered, so it must never also be spliced into a
- * `{{defaultValue}}` hole in the string it chose — or in any other.
+ * i18next plural-selects only for a NUMERIC `count` (`needsPluralHandling` in
+ * i18next 26 is `count !== undefined && !isString(count)`), so a string count
+ * reads the base row on both paths. `_zero` is not looked up: no English row
+ * spells one, because `en` selects no `zero` category.
  */
-const DEFAULT_VALUE_OPTION = 'defaultValue';
+function defaultsRowFor(defaults, key, options) {
+    const count = options?.count;
+    if (typeof count === 'number' && Number.isFinite(count)) {
+        const slot = defaults[`${key}_${DEFAULTS_PLURAL_RULES.select(count)}`];
+        if (slot)
+            return slot;
+    }
+    return defaults[key];
+}
 export function createSafeTranslation(defaults, testKey) {
     // Factory-level fallback: one stable reference per defaults map, so
     // downstream useMemo/useCallback deps don't invalidate every render in
@@ -47,43 +64,24 @@ export function createSafeTranslation(defaults, testKey) {
         // `string`, and i18next itself declines a `null` default. `||` (not `??`)
         // keeps the whole chain consistent with the pre-existing `defaults[key] ||`
         // step: an empty string at any position falls through to the next.
+        //
+        // A count family's suffixed rows are reached here too (objectui#11445):
+        // `t('detail.replyCount', { count: 3 })` reads `detail.replyCount_other`
+        // before the base row, exactly as i18next reads the `en` pack. Before that
+        // card a family's `_one` / `_other` rows were unreachable on this path, so
+        // the code-selected `xxxCountOne` pairs were the only way a provider-less
+        // host rendered "1 reply" — the card retired those pairs.
         const inlineDefault = options?.[DEFAULT_VALUE_OPTION];
-        let value = defaults[key] || (typeof inlineDefault === 'string' ? inlineDefault : '') || key;
-        if (options) {
-            for (const [k, v] of Object.entries(options)) {
-                // Reserved: see DEFAULT_VALUE_OPTION. Skipped whatever its type, so an
-                // ignored non-string default cannot re-enter through this loop.
-                //
-                // This is the one deliberate divergence from i18next on this path, and
-                // it is unreachable with today's strings: i18next passes the whole
-                // options object to its interpolator, so it WOULD render
-                // `'Fallback: {{defaultValue}}'` as `'Fallback: INLINE'` (measured on
-                // 26.3.6) — but no value in this repo spells that hole (zero hits for
-                // `{{defaultValue` across packages/apps/examples), and splicing a
-                // fallback string into a hole named after itself has no sensible
-                // reading. The alternative — letting a call site's fallback text leak
-                // into an unrelated table value — is the worse of the two.
-                if (k === DEFAULT_VALUE_OPTION)
-                    continue;
-                // `split(needle).join(value)` — deliberately not `replace`, and not
-                // `replaceAll` either (objectui#3418). This path must agree with
-                // i18next, which serves the *provider* path; any divergence is a
-                // silent fork that only shows up on provider-less hosts, where we are
-                // least likely to see it:
-                //   1. `replace` with a string needle substitutes only the FIRST
-                //      occurrence. i18next substitutes every one, so a sentence that
-                //      repeats a placeholder ("Selected {{count}} of {{count}} items"
-                //      — natural in many locales, and often required by RTL /
-                //      agglutinative word order) leaked literal braces to users.
-                //   2. `replace` AND `replaceAll` both interpret `$&`, `` $` ``, `$'`
-                //      and `$$` in the *replacement* string. i18next does not. Values
-                //      here are runtime data — record labels, search terms — so this
-                //      one is reachable today, unlike (1).
-                // split/join is literal on both sides, which is exactly i18next's
-                // behaviour, and needs no regex escaping of the placeholder name.
-                value = value.split(`{{${k}}}`).join(String(v));
-            }
-        }
+        let value = defaultsRowFor(defaults, key, options) ||
+            (typeof inlineDefault === 'string' ? inlineDefault : '') ||
+            key;
+        // The interpolation itself lives in `fallbackInterpolation.ts` — ONE
+        // function, shared with `useObjectTranslation`'s not-ready path
+        // (objectui#6219). Both provider-less renderers therefore fill exactly
+        // the `{{name}}` spelling objectui#3512 holds the copy to, and the
+        // reserved-name rule for `defaultValue` (objectui#3865) is stated once.
+        // The behaviour pinned by `useSafeTranslation.test.tsx` is unchanged.
+        value = interpolateFallback(value, options);
         return value;
     };
     return function useSafeTranslation() {

package/dist/utils/first-day-of-week.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 first day of the week for a BCP-47 locale tag (objectui#11675).
+ *
+ * The first day of the week follows the user's locale, as dates, times and
+ * numbers do (ruling B on objectui#11675: there is no separate week-start
+ * setting). So a week grid, a weekday header row and a "this week" bound all
+ * read it from the tag they already format with, and never from a hard-coded
+ * Sunday or Monday: `en-US` starts on Sunday, `en-GB` and `zh-CN` on Monday.
+ *
+ * ## The engine's own week info comes first
+ *
+ * `Intl.Locale` carries CLDR's week data for the tag's region, including a
+ * `-u-fw-` keyword on the tag. It has two spellings: the `getWeekInfo()` method
+ * of the current Intl Locale Info proposal, and the `weekInfo` accessor engines
+ * shipped first. Both are read, the method first. Measured while writing this:
+ * Chromium 141 has both, Node 22 (the test and CI runtime) has the accessor
+ * only. Both count ISO weekdays, 1 (Monday) to 7 (Sunday).
+ *
+ * ## Where the engine has none, CLDR's table answers
+ *
+ * An engine with neither spelling gets {@link NON_MONDAY_REGIONS}: CLDR's
+ * `weekData` `firstDay` rows, read by region. The region is the tag's own, or
+ * the one CLDR's likely subtags give it (`Intl.Locale.prototype.maximize`), so
+ * `en` reads `US` and `zh` reads `CN`. A region the table does not list, and a
+ * tag with no region even after `maximize()`, reads Monday, CLDR's world
+ * default (`001`). This path reads the region only: a `-u-fw-` or `-u-rg-`
+ * keyword is the engine path's alone.
+ *
+ * The table transcribes ONE CLDR release, the one {@link WEEK_DATA_CLDR} names:
+ * the newest release the repository's CI runtime ships. Engines carry their own
+ * week data, and it differs: CLDR moves a region now and then, and a browser
+ * may carry data of its own. That is why the engine's answer wins wherever
+ * there is one. What re-derives the table against the running engine is
+ * `__tests__/firstDayOfWeek-11675.test.ts`, region by region. On a runtime
+ * whose CLDR release is not the table's, it reads that release's recorded
+ * differences from the table instead of reporting them as drift.
+ *
+ * ## A tag `Intl` refuses is refused here too
+ *
+ * A malformed tag throws `Intl.Locale`'s `RangeError`, as `Intl.DateTimeFormat`
+ * and `toLocaleDateString` do for the same tag. Every caller formats its dates
+ * with the tag it hands this function, so a tag that reached here and is
+ * malformed fails the caller's own formatting the same way. ⛔ No Sunday or
+ * Monday is guessed for it.
+ */
+/** A weekday as `Date.prototype.getDay` numbers it: 0 is Sunday, 6 is Saturday. */
+export type WeekdayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * The CLDR release {@link NON_MONDAY_REGIONS} transcribes, as the major part of
+ * `process.versions.cldr`. Change it only together with the table, from a
+ * runtime that ships that release.
+ */
+export declare const WEEK_DATA_CLDR = "48";
+/**
+ * The first day of the week in `locale`, numbered as `Date.prototype.getDay`
+ * numbers weekdays (0 is Sunday), which is also what react-day-picker's
+ * `weekStartsOn` takes. Read the module header for where the answer comes from.
+ *
+ * @example
+ * firstDayOfWeek('en-US'); // 0, Sunday
+ * firstDayOfWeek('en-GB'); // 1, Monday
+ * firstDayOfWeek('zh-CN'); // 1, Monday
+ */
+export declare function firstDayOfWeek(locale: string): WeekdayIndex;

package/dist/utils/first-day-of-week.js

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+/** ISO weekday 1 (Monday) to 7 (Sunday), as a {@link WeekdayIndex}. */
+const BY_ISO_WEEKDAY = [1, 2, 3, 4, 5, 6, 0];
+function fromIsoWeekday(day) {
+    return Number.isInteger(day) && day >= 1 && day <= 7 ? BY_ISO_WEEKDAY[day - 1] : undefined;
+}
+/**
+ * The CLDR release {@link NON_MONDAY_REGIONS} transcribes, as the major part of
+ * `process.versions.cldr`. Change it only together with the table, from a
+ * runtime that ships that release.
+ */
+export const WEEK_DATA_CLDR = '48';
+/**
+ * CLDR's `weekData` `firstDay` rows other than Monday, by region, as of the
+ * release {@link WEEK_DATA_CLDR} names. Regions are the canonical codes
+ * `Intl.Locale` reports (`BU` reads `MM`), so the deprecated aliases CLDR also
+ * lists are left out.
+ */
+const NON_MONDAY_REGIONS = [
+    [
+        0,
+        'AG AS BD BR BS BT BW BZ CA CO DM DO ET GT GU HK HN ID IL IN IS JM JP KE KH KR LA MH MM MO MT MX ' +
+            'MZ NI NP PA PE PH PK PR PT PY SA SG SV TH TT TW UM US VE VI WS YE ZA ZW',
+    ],
+    [5, 'MV'],
+    [6, 'AF BH DJ DZ EG IQ IR JO KW LY OM QA SD SY'],
+];
+/** CLDR's world default (`001`): the week starts on Monday. */
+const WORLD_FIRST_DAY = 1;
+const FIRST_DAY_BY_REGION = new Map(NON_MONDAY_REGIONS.flatMap(([day, regions]) => regions.split(' ').map((region) => [region, day])));
+function engineFirstDay(locale) {
+    const faces = locale;
+    if (typeof faces.getWeekInfo === 'function')
+        return fromIsoWeekday(faces.getWeekInfo().firstDay);
+    const info = faces.weekInfo;
+    return info ? fromIsoWeekday(info.firstDay) : undefined;
+}
+function tableFirstDay(locale) {
+    const region = locale.region ?? locale.maximize().region;
+    return (region !== undefined ? FIRST_DAY_BY_REGION.get(region) : undefined) ?? WORLD_FIRST_DAY;
+}
+/**
+ * The first day of the week in `locale`, numbered as `Date.prototype.getDay`
+ * numbers weekdays (0 is Sunday), which is also what react-day-picker's
+ * `weekStartsOn` takes. Read the module header for where the answer comes from.
+ *
+ * @example
+ * firstDayOfWeek('en-US'); // 0, Sunday
+ * firstDayOfWeek('en-GB'); // 1, Monday
+ * firstDayOfWeek('zh-CN'); // 1, Monday
+ */
+export function firstDayOfWeek(locale) {
+    const parsed = new Intl.Locale(locale);
+    return engineFirstDay(parsed) ?? tableFirstDay(parsed);
+}

package/dist/utils/formatting.d.ts

@@ -2,6 +2,17 @@
  * @object-ui/i18n - Date and currency formatting utilities
  *
  * Uses the native Intl API for locale-aware formatting.
+ *
+ * Every date helper below reads a string through `toDisplayDate`
+ * (`@object-ui/core`), the one parse step behind the date faces
+ * (objectui#10110, objectui#10183). The engine's own parse reads a date-only
+ * `2026-09-01` as UTC midnight, so each helper named August 31st for every
+ * viewer west of UTC (objectui#10866). The shared step tells the two shapes
+ * apart by the value: a date-only string is rebuilt at local midnight of the
+ * day it names, and a value with a time part keeps its instant. It also
+ * refuses a day its month does not have (`2026-02-30`, objectui#10026), which
+ * each helper then renders as the raw string, its face for any unparsable
+ * value.
  */
 export interface DateFormatOptions {
     locale?: string;
@@ -33,8 +44,19 @@ export declare function formatDate(date: Date | string | number, options?: DateF
 export declare function formatDateTime(date: Date | string | number, options?: DateFormatOptions): string;
 /**
  * Format a relative time (e.g., "2 days ago", "in 3 hours")
+ *
+ * A date-only value counts from now to the START of the day it names (local
+ * midnight), the same distance in every zone at the same wall-clock time.
+ * An unparsable value comes back as its string, as it does from
+ * {@link formatDate}; `Intl.RelativeTimeFormat` would throw on it.
+ *
+ * `options` are `Intl.RelativeTimeFormat`'s own `style` and `numeric`, passed
+ * through unchanged; omitted, the result is what it always was (`long`,
+ * `auto`: "yesterday", "2 days ago"). A surface with little room asks for a
+ * compact form, e.g. `{ style: 'short', numeric: 'always' }` ("1 day ago",
+ * "3 hr. ago").
  */
-export declare function formatRelativeTime(date: Date | string | number, locale?: string): string;
+export declare function formatRelativeTime(date: Date | string | number, locale?: string, options?: Pick<Intl.RelativeTimeFormatOptions, 'style' | 'numeric'>): string;
 /**
  * Format a currency value according to locale conventions. When `currency`
  * is omitted, falls back to a plain locale-formatted number (no symbol)