@object-ui/i18n 17.7.0 → 18.0.0

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

@@ -49,8 +49,14 @@ export declare function formatDateTime(date: Date | string | number, options?: D
  * 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)

package/dist/utils/formatting.js

@@ -59,8 +59,14 @@ export function formatDateTime(date, options = {}) {
  * 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 function formatRelativeTime(date, locale = 'en') {
+export function formatRelativeTime(date, locale = 'en', options = {}) {
     const d = toDisplayDate(date);
     if (isNaN(d.getTime())) {
         return String(date);
@@ -71,7 +77,10 @@ export function formatRelativeTime(date, locale = 'en') {
     const diffMin = Math.round(diffSec / 60);
     const diffHour = Math.round(diffMin / 60);
     const diffDay = Math.round(diffHour / 24);
-    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+    const rtf = new Intl.RelativeTimeFormat(locale, {
+        numeric: options.numeric ?? 'auto',
+        style: options.style ?? 'long',
+    });
     if (Math.abs(diffSec) < 60)
         return rtf.format(diffSec, 'second');
     if (Math.abs(diffMin) < 60)

package/dist/utils/index.d.ts

@@ -2,3 +2,4 @@ export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatN
 export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, type SpecPluralRule, type SpecDateFormat, type SpecNumberFormat, type SpecLocaleConfig, } from './spec-formatters.js';
 export { isSpecTranslationData, transformSpecTranslations, type SpecTranslationData, } from './spec-translations.js';
 export { formatDisplayNumber, shouldGroupDisplayNumber, type DisplayNumberFormatOptions, } from './number-display.js';
+export { firstDayOfWeek, type WeekdayIndex } from './first-day-of-week.js';

package/dist/utils/index.js

@@ -2,3 +2,4 @@ export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatN
 export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, } from './spec-formatters.js';
 export { isSpecTranslationData, transformSpecTranslations, } from './spec-translations.js';
 export { formatDisplayNumber, shouldGroupDisplayNumber, } from './number-display.js';
+export { firstDayOfWeek } from './first-day-of-week.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/i18n",
-  "version": "17.7.0",
+  "version": "18.0.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -37,7 +37,7 @@
   "dependencies": {
     "i18next": "^26.4.0",
     "react-i18next": "^17.0.11",
-    "@object-ui/core": "17.7.0"
+    "@object-ui/core": "18.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"