feat: Allow formatting embedded XML (#1379)

## Enhanced `FormattedMessage` & `formatMessage` rich text formatting

In v2, in order to do rich text formatting (embedding a `ReactElement`), you had to do this:

```tsx
<FormattedMessage
  defaultMessage="To buy a shoe, { link } and { cta }"
  values={{
    link: (
      <a class="external_link" target="_blank" href="https://www.shoe.com/">
        visit our website
      </a>
    ),
    cta: <strong class="important">eat a shoe</strong>,
  }}
/>
```

Now you can do:

```tsx
<FormattedMessage
  defaultMessage="To buy a shoe, <a>visit our website</a> and <cta>eat a shoe</cta>"
  values={{
    link: msg => (
      <a class="external_link" target="_blank" href="https://www.shoe.com/">
        {msg}
      </a>
    ),
    cta: msg => <strong class="important">{msg}</strong>,
  }}
/>
```

The change solves several issues:

1. Contextual information was lost when you need to style part of the string: In this example above, `link` effectively is a blackbox placeholder to a translator. It can be a person, an animal, or a timestamp. Conveying contextual information via `description` & `placeholder` variable is often not enough since the variable can get sufficiently complicated.
2. This brings feature-parity with other translation libs, such as [fluent](https://projectfluent.org/) by Mozilla (using Overlays).

However, in cases where we allow placeholders to be a ReactElement will have to be rewritten to 1 of the 2 syntax down below:

### Before

```tsx
<FormattedMessage
  defaultMessage="Hello, {name}"
  values={{
    name: <b>John</b>,
  }}
/>
```

### After

```tsx
<FormattedMessage
  defaultMessage="Hello, <b>John</b>"
  values={{
    b: name => <b>{name}</b>,
  }}
/>
```

OR (NOT RECOMMENDED)

```tsx
<FormattedMessage
  defaultMessage="Hello, <name/>"
  values={{
    name: () => <b>{John}</b>,
  }}
/>
```

Author: longlho

docs/Components.md

@@ -446,15 +446,16 @@ By default `<FormattedMessage>` will render the formatted string into a `<span>`
 
 #### Rich Text Formatting
 
-`<FormattedMessage>` also supports rich-text formatting by passing React elements to the `values` prop. In the message you need to use a simple argument (e.g., `{name}`); here's an example:
+`<FormattedMessage>` also supports rich-text formatting by specifying a XML tag in the message & resolving that tag in the `values` prop. Here's an example:
 
-```js
+```tsx
 <FormattedMessage
   id="app.greeting"
   description="Greeting to welcome the user to the app"
-  defaultMessage="Hello, {name}!"
+  defaultMessage="Hello, <b>Eric</b> <icon/>"
   values={{
-    name: <b>Eric</b>,
+    b: msg => <b>{msg}</b>,
+    icon: () => <svg />,
   }}
 />
 ```
@@ -463,7 +464,25 @@ By default `<FormattedMessage>` will render the formatted string into a `<span>`
 <span>Hello, <b>Eric</b>!</span>
 ```
 
-This allows messages to still be defined as a plain string _without_ HTML — making it easier for it to be translated. At runtime, React will also optimize this by only re-rendering the variable parts of the message when they change. In the above example, if the user changed their name, React would only need to update the contents of the `<b>` element.
+By allowing embedding XML tag we want to make sure contextual information is not lost when you need to style part of the string. In a more complicated example like:
+
+```tsx
+<FormattedMessage
+  defaultMessage="To buy a shoe, <a>visit our website</a> and <cta>buy a shoe</cta>"
+  values={{
+    link: msg => (
+      <a class="external_link" target="_blank" href="https://www.shoe.com/">
+        {msg}
+      </a>
+    ),
+    cta: msg => <strong class="important">{msg}</strong>,
+  }}
+/>
+```
+
+All the rich text gets translated together which yields higher quality output. This brings feature-parity with other translation libs as well, such as [fluent](https://projectfluent.org/) by Mozilla (using `overlays` concept).
+
+Extending this also allows users to potentially utilizing other rich text format, like [Markdown](https://daringfireball.net/projects/markdown/).
 
 ### `FormattedHTMLMessage`
 

docs/Getting-Started.md

@@ -8,10 +8,10 @@
   - [The `react-intl` Package](#the-react-intl-package)
     - [Module Bundlers](#module-bundlers)
   - [The React Intl Module](#the-react-intl-module)
-  - [`Intl` APIs requirements](#intl-apis-requirements)
-    - [Intl in browser](#intl-in-browser)
-    - [Intl in Node.js](#intl-in-nodejs)
-    - [Intl in React Native](#intl-in-react-native)
+  - [Runtime Requirements](#runtime-requirements)
+    - [Browser](#browser)
+    - [Node.js](#nodejs)
+    - [React Native](#react-native)
   - [Creating an I18n Context](#creating-an-i18n-context)
   - [Formatting Data](#formatting-data)
 - [Core Concepts](#core-concepts)
@@ -90,7 +90,7 @@ Whether you use the ES6, CommonJS, or UMD version of React Intl, they all provid
 
 **Note:** When using the UMD version of React Intl _without_ a module system, it will expect `react` to exist on the global variable: **`React`**, and put the above named exports on the global variable: **`ReactIntl`**.
 
-### `Intl` APIs requirements
+### Runtime Requirements
 
 React Intl relies on these `Intl` APIs:
 
@@ -109,11 +109,11 @@ import '@formatjs/intl-relativetimeformat/polyfill';
 import '@formatjs/intl-relativetimeformat/dist/locale-data/de'; // Add locale data for de
 ```
 
-#### Intl in browser
+#### Browser
 
 We officially support IE11 along with modern browsers (Chrome/FF/Edge/Safari).
 
-#### Intl in Node.js
+#### Node.js
 
 When using React Intl in Node.js, your `node` binary has to either:
 
@@ -125,13 +125,17 @@ When using React Intl in Node.js, your `node` binary has to either:
 
 If your `node` version is missing any of the `Intl` APIs above, you'd have to polyfill them accordingly.
 
-#### Intl in React Native
+We also rely on `DOMParser` to format rich text, thus for Node will need to polyfill using [xmldom](https://github.com/jindw/xmldom).
+
+#### React Native
 
 If you're using `react-intl` in React Native, make sure your runtime has built-in `Intl` support (similar to [JSC International variant](https://github.com/react-native-community/jsc-android-buildscripts#international-variant)). See these issues for more details:
 
 - https://github.com/formatjs/react-intl/issues/1356
 - https://github.com/formatjs/react-intl/issues/992
 
+We also rely on `DOMParser` to format rich text, thus for JSC will need to polyfill using [xmldom](https://github.com/jindw/xmldom).
+
 ### Creating an I18n Context
 
 Now with React Intl and its locale data loaded an i18n context can be created for your React app.

docs/Upgrade-Guide.md

@@ -9,7 +9,9 @@
 - [Migrate to using native Intl APIs](#migrate-to-using-native-intl-apis)
 - [TypeScript Support](#typescript-support)
 - [FormattedRelativeTime](#formattedrelativetime)
-- [`formatMessage` now supports `ReactElement`](#formatmessage-now-supports-reactelement)
+- [Enhanced `FormattedMessage` & `formatMessage` rich text formatting](#enhanced-formattedmessage--formatmessage-rich-text-formatting)
+  - [Before](#before)
+  - [After](#after)
 - [ESM Build](#esm-build)
   - [Jest](#jest)
   - [webpack babel-loader](#webpack-babel-loader)
@@ -29,6 +31,8 @@
 <IntlProvider textComponent="span" />
 ```
 
+- Rich text formatting enhancement in `FormattedMessage` & `formatMessage`
+
 ## Use React 16.3 and upwards
 
 React Intl v3 supports the new context API, fixing all kinds of tree update problems :tada:
@@ -237,32 +241,78 @@ const {value, unit} = selectUnit(Date.now() - 48 * 3600 * 1000);
 <FormattedRelativeTime value={value} unit={unit} />;
 ```
 
-## `formatMessage` now supports `ReactElement`
+## Enhanced `FormattedMessage` & `formatMessage` rich text formatting
 
-The imperative API `formatMessage` now supports `ReactElement` in values and will resolve type correctly. This change should be backwards-compatible since for regular non-`ReactElement` values it will still return a `string`, but for rich text like the example down below, it will return a `Array<string, React.ReactElement>`:
+In v2, in order to do rich text formatting (embedding a `ReactElement`), you had to do this:
 
-```ts
-const messages = defineMessages({
-  greeting: {
-    id: 'app.greeting',
-    defaultMessage: 'Hello, {name}!',
-    description: 'Greeting to welcome the user to the app',
-  },
-});
+```tsx
+<FormattedMessage
+  defaultMessage="To buy a shoe, { link } and { cta }"
+  values={{
+    link: (
+      <a class="external_link" target="_blank" href="https://www.shoe.com/">
+        visit our website
+      </a>
+    ),
+    cta: <strong class="important">eat a shoe</strong>,
+  }}
+/>
+```
+
+Now you can do:
+
+```tsx
+<FormattedMessage
+  defaultMessage="To buy a shoe, <a>visit our website</a> and <cta>eat a shoe</cta>"
+  values={{
+    link: msg => (
+      <a class="external_link" target="_blank" href="https://www.shoe.com/">
+        {msg}
+      </a>
+    ),
+    cta: msg => <strong class="important">{msg}</strong>,
+  }}
+/>
+```
+
+The change solves several issues:
 
-formatMessage(messages.greeting, {name: 'Eric'}); // "Hello, Eric!"
+1. Contextual information was lost when you need to style part of the string: In this example above, `link` effectively is a blackbox placeholder to a translator. It can be a person, an animal, or a timestamp. Conveying contextual information via `description` & `placeholder` variable is often not enough since the variable can get sufficiently complicated.
+2. This brings feature-parity with other translation libs, such as [fluent](https://projectfluent.org/) by Mozilla (using Overlays).
+
+However, in cases where we allow placeholders to be a ReactElement will have to be rewritten to 1 of the 2 syntax down below:
+
+### Before
+
+```tsx
+<FormattedMessage
+  defaultMessage="Hello, {name}"
+  values={{
+    name: <b>John</b>,
+  }}
+/>
 ```
 
+### After
+
 ```tsx
-const messages = defineMessages({
-  greeting: {
-    id: 'app.greeting',
-    defaultMessage: 'Hello, {name}!',
-    description: 'Greeting to welcome the user to the app',
-  },
-});
+<FormattedMessage
+  defaultMessage="Hello, <b>John</b>"
+  values={{
+    b: name => <b>{name}</b>,
+  }}
+/>
+```
 
-formatMessage(messages.greeting, {name: <b>Eric</b>}); // ['Hello, ', <b>Eric</b>, '!']
+OR (NOT RECOMMENDED)
+
+```tsx
+<FormattedMessage
+  defaultMessage="Hello, <name/>"
+  values={{
+    name: () => <b>{John}</b>,
+  }}
+/>
 ```
 
 ## ESM Build

package-lock.json

@@ -43,8 +43,8 @@
     "hoist-non-react-statics": "^3.3.0",
     "intl-format-cache": "^4.1.2",
     "intl-locales-supported": "^1.4.2",
-    "intl-messageformat": "^5.1.2",
-    "intl-messageformat-parser": "^2.1.2",
+    "intl-messageformat": "^5.2.0",
+    "intl-messageformat-parser": "^2.1.3",
     "invariant": "^2.1.1",
     "react": "^16.3.0",
     "shallow-equal": "^1.1.0"
@@ -63,11 +63,11 @@
     "@types/enzyme": "^3.10.3",
     "@types/jest": "^24.0.13",
     "@types/prop-types": "^15.7.1",
-    "@types/react-dom": "^16.8.4",
+    "@types/react-dom": "^16.8.5",
     "@typescript-eslint/eslint-plugin": "^1.13.0",
     "@typescript-eslint/parser": "^1.13.0",
     "babel-jest": "^24.8.0",
-    "babel-plugin-react-intl": "^4.1.2",
+    "babel-plugin-react-intl": "^4.1.3",
     "babel-plugin-transform-member-expression-literals": "^6.9.4",
     "babel-plugin-transform-property-literals": "^6.9.4",
     "babel-plugin-transform-react-remove-prop-types": "^0.4.18",

package.json

@@ -7,11 +7,9 @@
 import * as React from 'react';
 import withIntl from './injectIntl';
 import {BaseFormattedMessage} from './message';
-import {MessageFormatPrimitiveValue} from '../types';
+import {PrimitiveType} from 'intl-messageformat/core';
 
-class FormattedHTMLMessage extends BaseFormattedMessage<
-  MessageFormatPrimitiveValue
-> {
+class FormattedHTMLMessage extends BaseFormattedMessage<PrimitiveType> {
   static defaultProps = {
     ...BaseFormattedMessage.defaultProps,
     tagName: 'span' as 'span',

src/components/html-message.tsx

@@ -6,11 +6,7 @@
 
 import * as React from 'react';
 import withIntl from './injectIntl';
-import {
-  MessageDescriptor,
-  IntlShape,
-  MessageFormatPrimitiveValue,
-} from '../types';
+import {MessageDescriptor, IntlShape} from '../types';
 const shallowEquals = require('shallow-equal/objects');
 
 import {formatMessage as baseFormatMessage} from '../format';
@@ -19,10 +15,11 @@ import {
   DEFAULT_INTL_CONFIG,
   createDefaultFormatters,
 } from '../utils';
+import {PrimitiveType, FormatXMLElementFn} from 'intl-messageformat/core';
 
 const defaultFormatMessage = (
   descriptor: MessageDescriptor,
-  values?: Record<string, MessageFormatPrimitiveValue | React.ReactElement>
+  values?: Record<string, PrimitiveType | FormatXMLElementFn>
 ) => {
   if (process.env.NODE_ENV !== 'production') {
     console.error(
@@ -50,9 +47,9 @@ export interface Props<V extends React.ReactNode = React.ReactNode>
 }
 
 export class BaseFormattedMessage<
-  V extends MessageFormatPrimitiveValue | React.ReactElement =
-    | MessageFormatPrimitiveValue
-    | React.ReactElement
+  V extends PrimitiveType | FormatXMLElementFn =
+    | PrimitiveType
+    | FormatXMLElementFn
 > extends React.Component<Props<V>> {
   static defaultProps = {
     values: {},