feat: Add new intl-based formatter builder

README.md

@@ -15,17 +15,46 @@ A simple time-ago component for [React].
 React.createElement(TimeAgo, {date: 'Aug 29, 2014'})
 ```
 
+## Intl Formatter
+
+Since v8.2.0 `react-timeago` comes with a formatter that uses the `Intl` that is built-in to Javascript
+to create relative time format in any locale you want with little configuration.
+
+However, this option is not the default. (The default is a custom formatter for English). You can use it
+by manually importing the `makeIntlFormatter` function.
+
+```tsx
+import TimeAgo from 'react-timeago'
+import {makeIntlFormatter} from 'react-timeago/defaultFormatter';
+
+const intlFormatter = makeIntlFormatter({
+  locale: undefined, // string
+  localeMatcher?: 'best fit', // 'lookup' | 'best fit',
+  numberingSystem?: 'latn' // Intl$NumberingSystem such as 'arab', 'deva', 'hebr' etc.
+  style?: 'long', // 'long' | 'short' | 'narrow',
+  numeric?: 'auto', //  'always' | 'auto', Using 'auto` will convert "1 day ago" to "yesterday" etc.
+});
+
+<TimeAgo date='Feb 1, 1966' formatter={intlFormatter} />
+```
+
+`makeIntlFormatter` can be called without any arguments at all and you'll get good defaults.
+
+This new formatter should be your first choice when using `react-timeago` going forward as long as it
+has the [browser support](https://caniuse.com/mdn-javascript_builtins_intl_relativetimeformat_format) you need.
+
 ## Language support
 
-Since v3.1.0 `react-timeago` now comes with support for a large number of languages out of the box.
+Since v3.1.0 `react-timeago` comes with support for a large number of languages out of the box.
 This support is based on the string objects taken from `jquery-timeago` and then updated with the help of the
 community. Many thanks to all those who contribute language support.
 
 ### Usage
+
 To use any of the languages provided, other than the default english, you will have to
 import the language strings and build a custom formatter.
 
-```jsx
+```tsx
 import TimeAgo from 'react-timeago'
 import frenchStrings from 'react-timeago/lib/language-strings/fr'
 import buildFormatter from 'react-timeago/lib/formatters/buildFormatter'

examples/simple/index.js

@@ -1,13 +1,79 @@
 /* @flow strict */
 import * as React from 'react'
+import { useMemo } from 'react'
 import ReactDom from 'react-dom/client'
 import TimeAgo from '../../src/index'
+import { makeIntlFormatter } from '../../src/defaultFormatter'
 
 const appElement = document.getElementById('app')
 
-appElement &&
-  ReactDom.createRoot(appElement).render(
+function Bare({ date }: { date: number }) {
+  return (
+    <>
+      You opened this page <TimeAgo date={date} />
+    </>
+  )
+}
+
+const intlFormatter = makeIntlFormatter({
+  locale: 'en',
+  style: 'long',
+  numeric: 'auto',
+})
+
+function Intl({ date }: { date: number }) {
+  const [locale, setLocale] = React.useState('en')
+  const [style, setStyle] = React.useState('long')
+  const [numeric, setNumeric] = React.useState('auto')
+
+  const intlFormatter = useMemo(
+    () =>
+      makeIntlFormatter({
+        locale,
+        style,
+        numeric,
+      }),
+    [locale, style, numeric],
+  )
+  return (
     <div>
-      You opened this page <TimeAgo date={Date.now()} />
-    </div>,
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        <option value="en">en</option>
+        <option value="fr">fr</option>
+        <option value="es">es</option>
+        <option value="de">de</option>
+        <option value="it">it</option>
+        <option value="ja">ja</option>
+        <option value="ko">ko</option>
+        <option value="zh">zh</option>
+      </select>
+      <select value={style} onChange={(e) => setStyle(e.target.value)}>
+        <option value="long">long</option>
+        <option value="short">short</option>
+        <option value="narrow">narrow</option>
+      </select>
+      <select value={numeric} onChange={(e) => setNumeric(e.target.value)}>
+        <option value="auto">auto</option>
+        <option value="always">always</option>
+      </select>
+      <TimeAgo date={date} formatter={intlFormatter} />
+    </div>
   )
+}
+
+function App() {
+  const [date, setDate] = React.useState(Date.now())
+
+  return (
+    <>
+      <h1>Bare</h1>
+      <Bare date={date} />
+      <h1>Intl</h1>
+      You opened this page <Intl date={date} />
+      <hr />
+      <button onClick={() => setDate(Date.now())}>Reset Time</button>
+    </>
+  )
+}
+
+appElement && ReactDom.createRoot(appElement).render(<App />)