feat: add formatDisplayName and FormattedDisplayName (#1567)

* feat: add formatDisplayName and FormattedDisplayName

Fixes #1547

* add docs

Author: pyrocat101

docs/API.md

@@ -28,6 +28,8 @@ There are a few API layers that React Intl provides and is built on. When using
     - [Message Formatting Fallbacks](#message-formatting-fallbacks)
     - [`formatMessage`](#formatmessage)
     - [`formatHTMLMessage`](#formathtmlmessage)
+  - [Localized Display Name APIs](#localized-display-name-apis)
+    - [`formatDisplayName`](#formatdisplayname)
 - [React Intl Components](#react-intl-components)
 
 <!-- tocstop -->
@@ -560,6 +562,47 @@ function formatHTMLMessage(
 
 **Note:** This API is provided to format legacy string message that contain HTML, but is not recommended, use [`<FormattedMessage>`](./Components.md#formattedmessage) instead.
 
+### Localized Display Name APIs
+
+**This uses stage 3 [`Intl.DisplayNames`][displaynames-repo] API so [polyfill][displaynames-polyfill] is required.**
+
+[displaynames-repo]: https://github.com/tc39/proposal-intl-displaynames
+[displaynames-polyfill]: https://www.npmjs.com/package/@formatjs/intl-displaynames
+
+This API provides _localized_ display names for languages, scripts, regions, and currencies.
+
+#### `formatDisplayName`
+
+```ts
+type FormatDisplayNameOptions = {
+  style?: 'narrow' | 'short' | 'long';
+  type?: 'language' | 'region' | 'script' | 'currency';
+  fallback?: 'code' | 'none';
+};
+
+function formatDisplayName(
+  value: string | number | object,
+  options?: FormatDisplayNameOptions
+): string | undefined;
+```
+
+Usage examples:
+
+```ts
+// When locale is `en`
+formatDisplayName('zh-Hans-SG'); //=> Simplified Chinese (Singapore)
+// When locale is `zh`
+formatDisplayName('zh-Hans-SG'); //=> 简体中文（新加坡）
+
+// When locale is `en`...
+// ISO-15924 four letters script code to localized display name
+formatDisplayName('Deva', {type: 'script'}); //=> Devanagari
+// ISO-4217 currency code to localized display name
+formatDisplayName('CNY', {type: 'currency'}); //=> Chinese Yuan
+// ISO-3166 two letters region code to localized display name
+formatDisplayName('UN', {type: 'region'}); //=> United Nations
+```
+
 ## React Intl Components
 
 The React components provided by React Intl allow for a declarative, idiomatic-React way of providing internationalization configuration and format dates, numbers, and strings/messages in your app.

docs/Components.md

@@ -30,6 +30,8 @@ React Intl has a set of React components that provide a declarative way to setup
     - [Caveats](#caveats)
   - [`FormattedHTMLMessage`](#formattedhtmlmessage)
   - [Using React-Intl with React Native](#using-react-intl-with-react-native)
+- [Localized Display Name Components](#localized-display-name-components)
+  - [`FormattedDisplayName`](#formatteddisplayname)
 
 <!-- tocstop -->
 
@@ -710,3 +712,43 @@ This component uses the [`formatHTMLMessage`](API.md#formathtmlmessage) API and
 Historically, it was required to provide a `textComponent` for React-Intl to work on React Native, because Fragments didn't exist at the time and React Native would break trying to render a `span` (the default `textComponent` in React-Intl V2).
 
 Starting with [React Native v0.52](https://github.com/react-native-community/releases/blob/master/CHANGELOG.md#0520---2018-01-07), which uses [React v16.2+](https://reactjs.org/blog/2017/11/28/react-v16.2.0-fragment-support.html), Fragments are supported. And since React-Intl V3's default `textComponent` is `<React.Fragment>`, such requirement no longer exists.
+
+## Localized Display Name Components
+
+### `FormattedDisplayName`
+
+This component uses [`formatDisplayName`][formatdisplayname] and [`Intl.DisplayName`][intl-displayname]
+has `props` that correspond to `DisplayNameOptions`. You might need a [polyfill][displaynames-polyfill].
+
+[formatdisplayname]: API.md#formatdisplayname
+[intl-displayname]: https://github.com/tc39/proposal-intl-displaynames
+[displaynames-polyfill]: https://www.npmjs.com/package/@formatjs/intl-displaynames
+
+**Props:**
+
+```ts
+props: FormatDisplayNameOptions &
+  {
+    value: string | number | object,
+  };
+```
+
+**Example:**
+
+When the locale is `en`:
+
+```tsx
+<FormattedDisplayName type="language" value="zh-Hans-SG" />
+```
+
+```html
+Simplified Chinese (Singapore)
+```
+
+```tsx
+<FormattedDisplayName type="currency" value="JPY" />
+```
+
+```html
+Japanese Yen
+```

docs/Getting-Started.md

@@ -51,6 +51,11 @@ React Intl relies on these `Intl` APIs:
 - [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat): Available on IE11+
 - [Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/PluralRules): This can be polyfilled using [this package](https://www.npmjs.com/package/@formatjs/intl-pluralrules).
 - [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat): This can be polyfilled using [this package](https://www.npmjs.com/package/@formatjs/intl-relativetimeformat).
+- (Optional) [Intl.DisplayNames][displaynames-spec]: Required if you use [`formatDisplayName`](API.md#formatdisplayname)
+  or [`FormattedDisplayName`](Components.md#formatteddisplayname). This can be polyfilled using [this package][displaynames-polyfill].
+
+  [displaynames-spec]: https://tc39.es/proposal-intl-displaynames/
+  [displaynames-polyfill]: https://www.npmjs.com/package/@formatjs/intl-displaynames
 
 If you need to support older browsers, we recommend you do the following:
 
@@ -74,6 +79,16 @@ if (!Intl.RelativeTimeFormat) {
 }
 ```
 
+5. If you need `Intl.DisplayNames`, include this [polyfill][displaynames-polyfill] in your build along
+   with individual CLDR data for each locale you support.
+
+```js
+if (!Intl.DisplayNames) {
+  require('@formatjs/intl-displaynames/polyfill');
+  require('@formatjs/intl-displaynames/dist/locale-data/de'); // Add locale data for de
+}
+```
+
 ### Browser
 
 We officially support IE11 along with 2 most recent versions of Edge, Chrome & Firefox.
@@ -118,6 +133,7 @@ If you cannot use the Intl variant of JSC (e.g on iOS), follow the instructions
 FormatJS also provides types & polyfill for the following Stage 3 Intl APIs:
 
 - Unified NumberFormat: [polyfill](https://www.npmjs.com/package/@formatjs/intl-unified-numberformat) & [spec](https://github.com/tc39/proposal-unified-intl-numberformat)
+- DisplayNames: [polyfill][displaynames-polyfill] & [spec][displaynames-spec]
 
 ## The `react-intl` Package
 

package-lock.json

@@ -131,6 +131,7 @@
   "types": "./lib/react-intl.d.ts",
   "sideEffects": false,
   "dependencies": {
+    "@formatjs/intl-displaynames": "^1.2.0",
     "@formatjs/intl-listformat": "^1.3.7",
     "@formatjs/intl-relativetimeformat": "^4.5.7",
     "@formatjs/intl-unified-numberformat": "^3.0.4",

package.json

@@ -5,6 +5,7 @@ import {
   FormatDateOptions,
   FormatNumberOptions,
   FormatListOptions,
+  FormatDisplayNameOptions,
 } from '../types';
 import {Context} from './injectIntl';
 
@@ -13,6 +14,9 @@ enum DisplayName {
   formatTime = 'FormattedTime',
   formatNumber = 'FormattedNumber',
   formatList = 'FormattedList',
+  // Note that this DisplayName is the locale display name, not to be confused with
+  // the name of the enum, which is for React component display name in dev tools.
+  formatDisplayName = 'FormattedDisplayName',
 }
 
 enum DisplayNameParts {
@@ -27,6 +31,7 @@ type Formatter = {
   formatTime: FormatDateOptions;
   formatNumber: FormatNumberOptions;
   formatList: FormatListOptions;
+  formatDisplayName: FormatDisplayNameOptions;
 };
 
 export const FormattedNumberParts: React.FC<Formatter['formatNumber'] & {

src/components/createFormattedComponent.tsx

@@ -27,6 +27,7 @@ import {formatPlural} from '../formatters/plural';
 import {formatMessage, formatHTMLMessage} from '../formatters/message';
 import * as shallowEquals_ from 'shallow-equal/objects';
 import {formatList} from '../formatters/list';
+import {formatDisplayName} from '../formatters/displayName';
 const shallowEquals: typeof shallowEquals_ =
   (shallowEquals_ as any).default || shallowEquals_;
 
@@ -146,6 +147,11 @@ export function createIntl(
     formatMessage: formatMessage.bind(null, resolvedConfig, formatters),
     formatHTMLMessage: formatHTMLMessage.bind(null, resolvedConfig, formatters),
     formatList: formatList.bind(null, resolvedConfig, formatters.getListFormat),
+    formatDisplayName: formatDisplayName.bind(
+      null,
+      resolvedConfig,
+      formatters.getDisplayNames
+    ),
   };
 }
 

src/components/provider.tsx

@@ -0,0 +1,35 @@
+import {IntlConfig, Formatters, IntlFormatters} from '../types';
+import {filterProps, createError} from '../utils';
+import {
+  DisplayNamesOptions,
+  DisplayNames as IntlDisplayNames,
+} from '@formatjs/intl-displaynames';
+
+const DISPLAY_NAMES_OPTONS: Array<keyof DisplayNamesOptions> = [
+  'localeMatcher',
+  'style',
+  'type',
+  'fallback',
+];
+
+export function formatDisplayName(
+  {locale, onError}: Pick<IntlConfig, 'locale' | 'onError'>,
+  getDisplayNames: Formatters['getDisplayNames'],
+  value: Parameters<IntlFormatters['formatDisplayName']>[0],
+  options: Parameters<IntlFormatters['formatDisplayName']>[1] = {}
+): string | undefined {
+  const DisplayNames: typeof IntlDisplayNames = (Intl as any).DisplayNames;
+  if (!DisplayNames) {
+    onError(
+      createError(`Intl.DisplayNames is not available in this environment.
+Try polyfilling it using "@formatjs/intl-displaynames"
+`)
+    );
+  }
+  const filteredOptions = filterProps(options, DISPLAY_NAMES_OPTONS);
+  try {
+    return getDisplayNames(locale, filteredOptions).of(value);
+  } catch (e) {
+    onError(createError('Error formatting display name.', e));
+  }
+}

src/formatters/displayName.ts

@@ -127,7 +127,7 @@ export function formatMessage(
 
   // `id` is a required field of a Message Descriptor.
   invariant(!!id, '[React Intl] An `id` must be provided to format a message.');
-  const message = messages && messages[String(id)]
+  const message = messages && messages[String(id)];
   formats = deepMergeFormatsAndSetTimeZone(formats, timeZone);
   defaultFormats = deepMergeFormatsAndSetTimeZone(defaultFormats, timeZone);
 

src/formatters/message.ts

@@ -13,6 +13,7 @@ import {
 import {CustomFormatConfig} from './types';
 import {UnifiedNumberFormatOptions} from '@formatjs/intl-unified-numberformat';
 import {IntlListFormatOptions} from '@formatjs/intl-listformat';
+import {DisplayNamesOptions} from '@formatjs/intl-displaynames/lib';
 export {
   default as injectIntl,
   Provider as RawIntlProvider,
@@ -38,6 +39,9 @@ export const FormattedNumber: React.FC<UnifiedNumberFormatOptions &
 export const FormattedList: React.FC<IntlListFormatOptions & {
   value: React.ReactNode[];
 }> = createFormattedComponent('formatList');
+export const FormattedDisplayName: React.FC<DisplayNamesOptions & {
+  value: string | number | object;
+}> = createFormattedComponent('formatDisplayName');
 export const FormattedDateParts = createFormattedDateTimePartsComponent(
   'formatDate'
 );

src/index.ts

@@ -15,6 +15,7 @@ import IntlRelativeTimeFormat, {
 import {MessageFormatElement} from 'intl-messageformat-parser';
 import {UnifiedNumberFormatOptions} from '@formatjs/intl-unified-numberformat';
 import IntlListFormat, {IntlListFormatOptions} from '@formatjs/intl-listformat';
+import {DisplayNames, DisplayNamesOptions} from '@formatjs/intl-displaynames';
 
 export interface IntlConfig {
   locale: string;
@@ -58,6 +59,11 @@ export type FormatPluralOptions = Exclude<
 
 export type FormatListOptions = Exclude<IntlListFormatOptions, 'localeMatcher'>;
 
+export type FormatDisplayNameOptions = Exclude<
+  DisplayNamesOptions,
+  'localeMatcher'
+>;
+
 export interface IntlFormatters {
   formatDate(
     value: Parameters<Intl.DateTimeFormat['format']>[0] | string,
@@ -107,14 +113,15 @@ export interface IntlFormatters {
     descriptor: MessageDescriptor,
     values?: Record<string, PrimitiveType>
   ): React.ReactNode;
-  formatList(
-    values: Array<string>,
-    opts?: FormatListOptions
-  ): string;
+  formatList(values: Array<string>, opts?: FormatListOptions): string;
   formatList(
     values: Array<string | React.ReactNode>,
     opts?: FormatListOptions
   ): React.ReactNode;
+  formatDisplayName(
+    value: Parameters<DisplayNames['of']>[0],
+    opts?: FormatDisplayNameOptions
+  ): string | undefined;
 }
 
 export interface Formatters {
@@ -136,6 +143,9 @@ export interface Formatters {
   getListFormat(
     ...args: ConstructorParameters<typeof IntlListFormat>
   ): IntlListFormat;
+  getDisplayNames(
+    ...args: ConstructorParameters<typeof DisplayNames>
+  ): DisplayNames;
 }
 
 export interface IntlShape extends IntlConfig, IntlFormatters {
@@ -149,6 +159,7 @@ export interface IntlCache {
   relativeTime: Record<string, IntlRelativeTimeFormat>;
   pluralRules: Record<string, Intl.PluralRules>;
   list: Record<string, IntlListFormat>;
+  displayNames: Record<string, DisplayNames>;
 }
 
 export interface MessageDescriptor {

src/types.ts

@@ -13,7 +13,7 @@ import {IntlConfig, IntlCache, CustomFormats, Formatters} from './types';
 import * as React from 'react';
 import IntlMessageFormat from 'intl-messageformat';
 import memoizeIntlConstructor from 'intl-format-cache';
-import {invariant} from '@formatjs/intl-utils'
+import {invariant} from '@formatjs/intl-utils';
 import {IntlRelativeTimeFormatOptions} from '@formatjs/intl-relativetimeformat';
 
 const ESCAPED_CHARS: Record<number, string> = {
@@ -97,6 +97,7 @@ export function createIntlCache(): IntlCache {
     relativeTime: {},
     pluralRules: {},
     list: {},
+    displayNames: {},
   };
 }
 
@@ -109,6 +110,7 @@ export function createFormatters(
 ): Formatters {
   const RelativeTimeFormat = (Intl as any).RelativeTimeFormat;
   const ListFormat = (Intl as any).ListFormat;
+  const DisplayNames = (Intl as any).DisplayNames;
   return {
     getDateTimeFormat: memoizeIntlConstructor(
       Intl.DateTimeFormat,
@@ -122,6 +124,7 @@ export function createFormatters(
     ),
     getPluralRules: memoizeIntlConstructor(Intl.PluralRules, cache.pluralRules),
     getListFormat: memoizeIntlConstructor(ListFormat, cache.list),
+    getDisplayNames: memoizeIntlConstructor(DisplayNames, cache.displayNames),
   };
 }
 

src/utils.ts

@@ -2,6 +2,7 @@ import {configure} from 'enzyme';
 import '@formatjs/intl-pluralrules/polyfill-locales';
 import '@formatjs/intl-relativetimeformat/polyfill-locales';
 import '@formatjs/intl-listformat/polyfill-locales';
+import '@formatjs/intl-displaynames/polyfill-locales';
 import * as Adapter from 'enzyme-adapter-react-16';
 
 configure({adapter: new Adapter()});