fix: Change numeric option from auto to always for format.relativeTime

docs/pages/docs/usage/configuration.mdx

@@ -15,7 +15,7 @@ Depending on if you handle [internationalization in Client- or Server Components
 `i18n.ts` can be used to provide configuration for **Server Components**.
 
 ```tsx filename="i18n.ts"
-import {notFound} from "next/navigation";
+import {notFound} from 'next/navigation';
 import {getRequestConfig} from 'next-intl/server';
 
 // Can be imported from a shared config
@@ -462,9 +462,12 @@ function getMessageFallback({namespace, key, error}) {
   }
 }
 
-<NextIntlClientProvider onError={onError} getMessageFallback={getMessageFallback}>
+<NextIntlClientProvider
+  onError={onError}
+  getMessageFallback={getMessageFallback}
+>
   ...
-</NextIntlClientProvider>
+</NextIntlClientProvider>;
 ```
 
 </Tab>
@@ -504,11 +507,12 @@ return (
 As a convenience, there are a couple of hooks that allow you to read global configuration.
 
 ```tsx
-import {useLocale, useTimeZone, useMessages} from 'next-intl';
+import {useLocale, useTimeZone, useMessages, useNow} from 'next-intl';
 
 function Component() {
   const locale = useLocale();
   const timeZone = useTimeZone();
   const messages = useMessages();
+  const now = useNow();
 }
 ```

docs/pages/docs/usage/dates-times.mdx

@@ -3,11 +3,11 @@ import PartnerContentLink from 'components/PartnerContentLink';
 
 # Date and time formatting
 
-The formatting of dates and times varies greatly between locales (e.g. "Apr 24, 2023" in `en-US` vs. "24 квіт. 2023 р." in `uk-UA`). By using the formatting capabilities of `next-intl`, you can handle all i18n differences in your Next.js app automatically.
+The formatting of dates and times varies greatly between locales (e.g. "Apr 24, 2023" in `en-US` vs. "24 квіт. 2023 р." in `uk-UA`). By using the formatting capabilities of `next-intl`, you can handle i18n differences in your Next.js app automatically.
 
 ## Formatting dates and times
 
-You can format plain dates that are not part of a message with the `useFormatter` hook:
+You can format plain dates that are not part of a message with the `dateTime` function that is returned from the `useFormatter` hook:
 
 ```js
 import {useFormatter} from 'next-intl';
@@ -51,24 +51,26 @@ const twoDaysAgo = subDays(date, 2);
 
 ## Formatting relative time
 
-Relative time durations can be formatted with a separate function:
+You can format plain dates that are not part of a message with the `relativeTime` function:
 
 ```js
 import {useFormatter} from 'next-intl';
 
 function Component() {
   const format = useFormatter();
   const dateTime = new Date('2020-11-20T08:30:00.000Z');
-  const now = new Date('2020-11-20T10:36:00.000Z');
 
-  // Renders "2 hours ago"
-  format.relativeTime(dateTime, now);
+  // At 2020-11-20T10:36:00.000Z,
+  // this will render "2 hours ago"
+  format.relativeTime(dateTime);
 }
 ```
 
-Note that values are rounded, so e.g. if 100 seconds have passed, "2 minutes ago" will be returned.
+Note that values are rounded, so e.g. if 126 minutes have passed, "2 hours ago" will be returned.
 
-If you want to use a specific unit, you can pass options with the second argument:
+### Supplying `now`
+
+By default, `relativeTime` will use [the global value for `now`](/docs/usage/configuration#now). If you want to use a different value, you can explicitly pass this as the second parameter.
 
 ```js
 import {useFormatter} from 'next-intl';
@@ -78,29 +80,23 @@ function Component() {
   const dateTime = new Date('2020-11-20T08:30:00.000Z');
   const now = new Date('2020-11-20T10:36:00.000Z');
 
-  // Renders "today"
-  format.relativeTime(dateTime, { now, unit: 'day' });
+  // Renders "2 hours ago"
+  format.relativeTime(dateTime, now);
 }
 ```
 
-Supplying `now` is necessary for the function to return consistent results. If you have [configured a global value for `now`](/docs/usage/configuration#now), you can omit the second argument:
-
-```js
-format.relativeTime(dateTime);
-```
-
-### `useNow`
-
-If you want the relative time value to update over time, you can do so with the `useNow` hook:
+If you want the relative time value to update over time, you can do so with [the `useNow` hook](/docs/usage/configuration#retrieve-global-configuration):
 
 ```js
 import {useNow, useFormatter} from 'next-intl';
 
 function Component() {
+  // Use the global now value initially …
   const now = useNow({
-    // Update every 10 seconds
+    // … and update it every 10 seconds
     updateInterval: 1000 * 10
   });
+
   const format = useFormatter();
   const dateTime = new Date('2020-11-20T10:36:01.516Z');
 
@@ -109,6 +105,25 @@ function Component() {
 }
 ```
 
+### Customizing the unit
+
+By default, `relativeTime` will pick a unit based on the difference between the passed date and `now` (e.g. 3 seconds, 40 minutes, 4 days, etc.).
+
+If you want to use a specific unit, you can provide options via the second argument:
+
+```js
+import {useFormatter} from 'next-intl';
+
+function Component() {
+  const format = useFormatter();
+  const dateTime = new Date('2020-03-20T08:30:00.000Z');
+  const now = new Date('2020-11-22T10:36:00.000Z');
+
+  // Renders "247 days ago"
+  format.relativeTime(dateTime, {now, unit: 'day'});
+}
+```
+
 ## Dates and times within messages
 
 Dates and times can be embedded within messages by using the ICU syntax.

examples/example-app-router-playground/tests/main.spec.ts

@@ -195,7 +195,7 @@ it('can use `getMessageFallback`', async ({page}) => {
 it('can use the core library', async ({page}) => {
   await page.goto('/en');
   const element = page.getByTestId('CoreLibrary');
-  await expect(element).toHaveText('Relative time: tomorrow');
+  await expect(element).toHaveText('Relative time: in 1 day');
 });
 
 it('can use `Link` on the server', async ({page}) => {

packages/next-intl/package.json

@@ -114,7 +114,7 @@
   "size-limit": [
     {
       "path": "dist/production/index.react-client.js",
-      "limit": "12.841 KB"
+      "limit": "12.855 KB"
     },
     {
       "path": "dist/production/index.react-server.js",

packages/use-intl/package.json

@@ -90,7 +90,7 @@
   "size-limit": [
     {
       "path": "dist/production/index.js",
-      "limit": "12.385 kB"
+      "limit": "12.4 kB"
     }
   ]
 }

packages/use-intl/src/core/createFormatter.tsx

@@ -219,7 +219,15 @@ export default function createFormatter({
       const value = calculateRelativeTimeValue(seconds, unit);
 
       return new Intl.RelativeTimeFormat(locale, {
-        numeric: 'auto'
+        // `numeric: 'auto'` can theoretically produce output like "yesterday",
+        // but it only works with integers. E.g. -1 day will produce "yesterday",
+        // but -1.1 days will produce "-1.1 days". Rounding before formatting is
+        // not desired, as the given dates might cross a threshold were the
+        // output isn't correct anymore. Example: 2024-01-08T23:00:00.000Z and
+        // 2024-01-08T01:00:00.000Z would produce "yesterday", which is not the
+        // case. By using `always` we can ensure correct output. The only exception
+        // is the formatting of times <1 second as "now".
+        numeric: unit === 'second' ? 'auto' : 'always'
       }).format(value, unit);
     } catch (error) {
       onError(