@object-ui/i18n 17.7.0 → 18.0.0

package/README.md

@@ -196,7 +196,70 @@ A date-only string such as `'2026-09-01'` names a calendar day: every date
 helper reads it as that day in every viewer's time zone (`formatDateTime` shows
 its midnight, and `formatRelativeTime` counts to the start of it). A string
 with a time part is an instant, read in the viewer's zone. `formatDateSpec`
-applies its `timeZone` to an instant only.
+applies its `timeZone` to an instant only. These helpers do not read the
+display zone below; the field cells and measures format through
+`@object-ui/core`'s date faces, which do.
+
+### Regional defaults (`LocalizationProvider`)
+
+`LocalizationProvider` carries the workspace's resolved regional defaults to
+every renderer below it, and `useLocalization()` reads them (`{}` outside a
+provider). The console fills it from `GET /api/v1/auth/me/localization`.
+
+```tsx
+import type { ReactNode } from 'react';
+import { LocalizationProvider, useLocalization } from '@object-ui/i18n';
+
+export function Regional({ children }: { children: ReactNode }) {
+  return (
+    <LocalizationProvider value={{ currency: 'EUR', locale: 'de-DE', timezone: 'Europe/Berlin' }}>
+      {children}
+    </LocalizationProvider>
+  );
+}
+
+export function ZoneLabel() {
+  const { timezone } = useLocalization();
+  return <span>{timezone ?? 'viewer zone'}</span>;
+}
+```
+
+- `currency` (ISO 4217) is the default a currency field without its own code
+  renders in.
+- `locale` (BCP-47) outranks the UI language for number and date formatting;
+  read the effective tag with `useDisplayLocale()`.
+- `timezone` (IANA) is the zone instants render in. The provider hands it to
+  `setDisplayTimeZone` in `@object-ui/core`, so every date and datetime face
+  takes it without any renderer passing a zone, and `useLocalization().timezone`
+  reads back the zone those faces use (`undefined` for a name the runtime does
+  not know). Without one, instants render in the viewer's zone. There is one
+  display zone per page, and unmounting the provider clears it.
+
+#### The first day of the week
+
+`firstDayOfWeek(locale)` answers the first day of the week for a BCP-47 tag,
+numbered as `Date.prototype.getDay` numbers weekdays (0 is Sunday), which is
+also what react-day-picker's `weekStartsOn` takes. It reads the engine's
+`Intl.Locale` week info, and CLDR's region table where the engine has none, so
+a week grid or a "this week" bound starts where the user's locale says rather
+than on a fixed day. There is no separate week-start setting: the tag is the
+one the caller already formats its dates with, such as `useDisplayLocale()`.
+
+```tsx
+import { firstDayOfWeek, useDisplayLocale } from '@object-ui/i18n';
+
+firstDayOfWeek('en-US'); // 0, Sunday
+firstDayOfWeek('en-GB'); // 1, Monday
+firstDayOfWeek('zh-CN'); // 1, Monday
+
+function WeekHeader() {
+  const weekStart = firstDayOfWeek(useDisplayLocale());
+  // ...lay the week out from `weekStart`
+}
+```
+
+A tag `Intl` refuses (`en_US`) throws the same `RangeError` that formatting a
+date with it would.
 
 ### Built-in locales — one is resident, nine are fetched on demand
 

package/dist/LocalizationContext.d.ts

@@ -7,18 +7,20 @@
  */
 /**
  * LocalizationContext — the tenant's resolved REGIONAL defaults (currency,
- * locale) for the current request, surfaced to every renderer.
+ * locale, time zone) for the current request, surfaced to every renderer.
  *
  * This is the client half of ADR-0053: the framework resolves a workspace
- * `localization.currency` / `locale` onto each request's ExecutionContext and
- * exposes them at `GET /api/v1/auth/me/localization`. A fetching wrapper (in
- * app-shell) loads them once and feeds this PURE context, so low-level field /
- * measure renderers can resolve a currency code down to the org default —
- * instead of hard-coding `$`/`¥`/`USD` or degrading to a bare number — without
- * any of them depending on app-shell or making their own fetch.
+ * `localization.currency` / `locale` / `timezone` onto each request's
+ * ExecutionContext and exposes them at `GET /api/v1/auth/me/localization`. A
+ * fetching wrapper (in app-shell) loads them once and feeds this PURE context,
+ * so low-level field / measure renderers can resolve a currency code down to
+ * the org default — instead of hard-coding `$`/`¥`/`USD` or degrading to a
+ * bare number — without any of them depending on app-shell or making their own
+ * fetch.
  *
  * Undefined values mean "no tenant default known" → consumers render a plain
- * number (the existing safe behavior).
+ * number (the existing safe behavior), and instants render in the viewer's
+ * own zone.
  */
 import * as React from 'react';
 export interface LocalizationValue {
@@ -26,8 +28,29 @@ export interface LocalizationValue {
     currency?: string;
     /** Tenant/display locale (BCP-47) for Intl formatting, or undefined. */
     locale?: string;
+    /**
+     * The zone instants render in (an IANA name), or undefined for the viewer's
+     * own (objectui#11693). The provider hands it to the central date faces in
+     * `@object-ui/core`; read back from {@link useLocalization}, it is the zone
+     * those faces render in, so a name the runtime does not know reads back
+     * `undefined`.
+     */
+    timezone?: string;
 }
-/** Pure provider — the fetching/loading concern lives in the app shell. */
+/**
+ * Pure provider — the fetching/loading concern lives in the app shell.
+ *
+ * It is also the ONE place the display zone enters the date faces
+ * (objectui#11693): `value.timezone` is handed to `setDisplayTimeZone` in
+ * `@object-ui/core`, which every date and datetime face reads, so no renderer
+ * threads a zone of its own. The hand-off runs in a layout effect, and the
+ * zone the context carries is read back from core through
+ * `useSyncExternalStore`, so the context changes only AFTER the faces have the
+ * new zone: every consumer then re-renders in it, before the browser paints.
+ *
+ * The display zone is one per page, as the date faces are: a second provider
+ * with a different zone would race this one for it, and unmounting clears it.
+ */
 export declare function LocalizationProvider({ value, children, }: {
     value: LocalizationValue;
     children: React.ReactNode;

package/dist/LocalizationContext.js

@@ -8,25 +8,47 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 /**
  * LocalizationContext — the tenant's resolved REGIONAL defaults (currency,
- * locale) for the current request, surfaced to every renderer.
+ * locale, time zone) for the current request, surfaced to every renderer.
  *
  * This is the client half of ADR-0053: the framework resolves a workspace
- * `localization.currency` / `locale` onto each request's ExecutionContext and
- * exposes them at `GET /api/v1/auth/me/localization`. A fetching wrapper (in
- * app-shell) loads them once and feeds this PURE context, so low-level field /
- * measure renderers can resolve a currency code down to the org default —
- * instead of hard-coding `$`/`¥`/`USD` or degrading to a bare number — without
- * any of them depending on app-shell or making their own fetch.
+ * `localization.currency` / `locale` / `timezone` onto each request's
+ * ExecutionContext and exposes them at `GET /api/v1/auth/me/localization`. A
+ * fetching wrapper (in app-shell) loads them once and feeds this PURE context,
+ * so low-level field / measure renderers can resolve a currency code down to
+ * the org default — instead of hard-coding `$`/`¥`/`USD` or degrading to a
+ * bare number — without any of them depending on app-shell or making their own
+ * fetch.
  *
  * Undefined values mean "no tenant default known" → consumers render a plain
- * number (the existing safe behavior).
+ * number (the existing safe behavior), and instants render in the viewer's
+ * own zone.
  */
 import * as React from 'react';
+import { getDisplayTimeZone, setDisplayTimeZone, subscribeDisplayTimeZone } from '@object-ui/core';
 const LocalizationCtx = React.createContext({});
-/** Pure provider — the fetching/loading concern lives in the app shell. */
+/**
+ * Pure provider — the fetching/loading concern lives in the app shell.
+ *
+ * It is also the ONE place the display zone enters the date faces
+ * (objectui#11693): `value.timezone` is handed to `setDisplayTimeZone` in
+ * `@object-ui/core`, which every date and datetime face reads, so no renderer
+ * threads a zone of its own. The hand-off runs in a layout effect, and the
+ * zone the context carries is read back from core through
+ * `useSyncExternalStore`, so the context changes only AFTER the faces have the
+ * new zone: every consumer then re-renders in it, before the browser paints.
+ *
+ * The display zone is one per page, as the date faces are: a second provider
+ * with a different zone would race this one for it, and unmounting clears it.
+ */
 export function LocalizationProvider({ value, children, }) {
+    const { timezone } = value;
+    React.useLayoutEffect(() => {
+        setDisplayTimeZone(timezone);
+        return () => setDisplayTimeZone(undefined);
+    }, [timezone]);
+    const appliedZone = React.useSyncExternalStore(subscribeDisplayTimeZone, getDisplayTimeZone, getDisplayTimeZone);
     // Stable identity unless the resolved values actually change.
-    const memo = React.useMemo(() => ({ currency: value.currency, locale: value.locale }), [value.currency, value.locale]);
+    const memo = React.useMemo(() => ({ currency: value.currency, locale: value.locale, timezone: appliedZone }), [value.currency, value.locale, appliedZone]);
     return _jsx(LocalizationCtx.Provider, { value: memo, children: children });
 }
 /**

package/dist/index.d.ts

@@ -47,3 +47,4 @@ export { LocalizationProvider, useLocalization, type LocalizationValue } from '.
 export { resolveFieldCurrency } from './currency.js';
 export { useDisplayLocale } from './useDisplayLocale.js';
 export { formatDisplayNumber, shouldGroupDisplayNumber, type DisplayNumberFormatOptions, } from './utils/index.js';
+export { firstDayOfWeek, type WeekdayIndex } from './utils/index.js';

package/dist/index.js

@@ -98,3 +98,7 @@ export { resolveFieldCurrency } from './currency.js';
 // see `utils/number-display.ts` for the grouping policy and its interim status.
 export { useDisplayLocale } from './useDisplayLocale.js';
 export { formatDisplayNumber, shouldGroupDisplayNumber, } from './utils/index.js';
+// objectui#11675 — the first day of the week for a locale tag. The calendar's
+// grids and the timeline's week buckets read it from the tag they format with,
+// so the week starts where the locale says and never on a hard-coded day.
+export { firstDayOfWeek } from './utils/index.js';