intl-messageformat 7.8.4 → 8.2.1

package/CHANGELOG.md

@@ -3,6 +3,71 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [8.2.1](https://github.com/formatjs/formatjs/compare/intl-messageformat@8.2.0...intl-messageformat@8.2.1) (2020-03-05)
+
+
+### Bug Fixes
+
+* **intl-messageformat:** export Error obj ([614debb](https://github.com/formatjs/formatjs/commit/614debb80f654966bc3ba832d6e5603be88da3d9))
+
+
+
+
+
+# [8.2.0](https://github.com/formatjs/formatjs/compare/intl-messageformat@8.1.0...intl-messageformat@8.2.0) (2020-03-05)
+
+
+### Features
+
+* **intl-messageformat:** Add error type for better debugging ([6200573](https://github.com/formatjs/formatjs/commit/6200573c9f88b23f157bede7305fcc5da64b842b))
+
+
+
+
+
+# [8.1.0](https://github.com/formatjs/formatjs/compare/intl-messageformat@8.0.0...intl-messageformat@8.1.0) (2020-03-05)
+
+
+### Features
+
+* **intl-messageformat-parser:** Allow - in embedded HTML tag ([43aa6a7](https://github.com/formatjs/formatjs/commit/43aa6a727ab6fd5eb3fb4d8c4035039a2c27b6c5)), closes [#545](https://github.com/formatjs/formatjs/issues/545)
+
+
+
+
+
+# [8.0.0](https://github.com/formatjs/formatjs/compare/intl-messageformat@7.8.3...intl-messageformat@8.0.0) (2020-03-04)
+
+
+### Features
+
+* **intl-messageformat:** combine formatHTMLMessage into format ([d59fbf1](https://github.com/formatjs/formatjs/commit/d59fbf1a4a017a3a023254cb9947575eef9cf803))
+
+
+### BREAKING CHANGES
+
+* **intl-messageformat:** We've modified the way we parse and format embedded
+XML/HTML as follow:
+
+1. `formatHTMLMessage` has been combined with `format`
+2. All tags specified must have corresponding values and will throw
+error if it's missing, e.g: `new IntlMessageFormat("a
+<b>strong</b>").format({ b: (...chunks) => <strong>chunks</strong> })`
+3. Self-closing tags are treated as string literal by default. We don't
+allow formatting self-closing tags because we already use ICU
+`{placeholder}` syntax for that.
+4. XML/HTML tags are escaped using apostrophe just like other ICU
+constructs.
+5. Remove dependency on DOMParser and restrictions on void element like
+`<link>`. This effectively means you don't need to polyfill DOMParser in
+Node anymore
+
+fix(intl-messageformat-parser): fix escaping for XML tag
+
+
+
+
+
 ## [7.8.4](https://github.com/formatjs/formatjs/compare/intl-messageformat@7.8.3...intl-messageformat@7.8.4) (2020-01-27)
 
 **Note:** Version bump only for package intl-messageformat

package/README.md

@@ -164,32 +164,35 @@ console.log(output); // => "My name is Eric."
 
 _Note: A value **must** be supplied for every argument in the message pattern the instance was constructed with._
 
-### `getAst` Method
-
-Return the underlying AST for the compiled message
-
-### `formatHTMLMessage` method
-
-Formats message containing HTML tags & can be used to embed rich text formatters such as React. For example:
+#### Rich Text support
 
 ```tsx
 const mf = new IntlMessageFormat('hello <b>world</b>', 'en');
-mf.formatHTMLMessage({b: str => <span>{str}</span>});
+mf.format({b: str => <span>{str}</span>});
 // returns ['hello ', React element rendered as <span>world</span>]
 ```
 
-#### Caveats
-
-This is not meant to be a full-fledged method to embed HTML, but rather to tag specific text chunk so translation can be more contextual. Therefore, the following restrictions apply:
+We support embedded XML tag in the message, e.g `this is a <b>strong</b> tag`. This is not meant to be a full-fledged method to embed HTML, but rather to tag specific text chunk so translation can be more contextual. Therefore, the following restrictions apply:
 
 1. Any attributes on the HTML tag are also ignored.
-2. Self-closing tags are not supported, please use regular ICU placeholder like `{placeholder}`.
-3. HTML tags must be all lowercased since it's case-insensitive.
-4. Self-closing tags can not be used as HTML tag placeholder. For e.g. `"Please click this <link>link</link>"` will not work because `<link/>` is a self-closing tag, and it can not be parsed correctly by browser `DOMParser`.
+2. Self-closing tags are treated as string literal and not supported, please use regular ICU placeholder like `{placeholder}`.
+3. All tags specified must have corresponding values and will throw
+   error if it's missing, e.g: `new IntlMessageFormat("a<b>strong</b>").format({ b: (...chunks) => <strong>chunks</strong> })`.
+4. XML/HTML tags are escaped using apostrophe just like other ICU constructs. In order to escape you can do things like:
 
-- List of self-closing tags is defined [here](https://html.spec.whatwg.org/multipage/syntax.html#void-elements).
+```tsx
+new IntlMessageFormat("I '<'3 cats").format(); // "I <3 cats"
+new IntlMessageFormat("raw '<b>HTML</b>'").format(); // "raw <b>HTML</b>"
+new IntlMessageFormat(
+  "raw '<b>HTML</b>' with '<a>'{placeholder}'</a>'"
+).format({placeholder: 'some word'}); // "raw <b>HTML</b> with <a>some word</a>"
+```
+
+5. Embedded valid HTML tag is a bit of a grey area right now since we're not supporting the full HTML/XHTML/XML spec.
+
+### `getAst` Method
 
-If you don't have `DOMParser` available in your environment (e.g. Node.js), you need to add a polyfill. One of the packages that provides such a polyfill is [jsdom](https://www.npmjs.com/package/jsdom).
+Return the underlying AST for the compiled message.
 
 ### User Defined Formats
 

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 import { parse, MessageFormatElement } from 'intl-messageformat-parser';
-import { FormatterCache, Formatters, Formats, FormatXMLElementFn, PrimitiveType, MessageFormatPart } from './formatters';
+import { FormatterCache, Formatters, Formats, FormatXMLElementFn, MessageFormatPart } from './formatters';
 export interface Options {
     formatters?: Formatters;
 }
@@ -12,9 +12,8 @@ export declare class IntlMessageFormat {
     private readonly message;
     private readonly formatterCache;
     constructor(message: string | MessageFormatElement[], locales?: string | string[], overrideFormats?: Partial<Formats>, opts?: Options);
-    format: (values?: Record<string, PrimitiveType> | undefined) => string;
-    formatToParts: (values?: Record<string, any> | undefined) => MessageFormatPart[];
-    formatHTMLMessage: (values?: Record<string, string | number | boolean | object | Date | FormatXMLElementFn | null | undefined> | undefined) => (string | object)[];
+    format: <T = void>(values?: Record<string, string | number | boolean | Date | T | FormatXMLElementFn<T> | null | undefined> | undefined) => string | T | (string | T)[];
+    formatToParts: <T>(values?: Record<string, string | number | boolean | Date | T | FormatXMLElementFn<T> | null | undefined> | undefined) => MessageFormatPart<T>[];
     resolvedOptions: () => {
         locale: string;
     };

package/dist/core.js

@@ -61,14 +61,30 @@ var IntlMessageFormat = /** @class */ (function () {
             pluralRules: {},
         };
         this.format = function (values) {
-            return formatters_1.formatToString(_this.ast, _this.locales, _this.formatters, _this.formats, values, _this.message);
+            var parts = _this.formatToParts(values);
+            // Hot path for straight simple msg translations
+            if (parts.length === 1) {
+                return parts[0].value;
+            }
+            var result = parts.reduce(function (all, part) {
+                if (!all.length ||
+                    part.type !== 0 /* literal */ ||
+                    typeof all[all.length - 1] !== 'string') {
+                    all.push(part.value);
+                }
+                else {
+                    all[all.length - 1] += part.value;
+                }
+                return all;
+            }, []);
+            if (result.length <= 1) {
+                return result[0] || '';
+            }
+            return result;
         };
         this.formatToParts = function (values) {
             return formatters_1.formatToParts(_this.ast, _this.locales, _this.formatters, _this.formats, values, undefined, _this.message);
         };
-        this.formatHTMLMessage = function (values) {
-            return formatters_1.formatHTMLMessage(_this.ast, _this.locales, _this.formatters, _this.formats, values, _this.message);
-        };
         this.resolvedOptions = function () { return ({
             locale: Intl.NumberFormat.supportedLocalesOf(_this.locales)[0],
         }); };

package/dist/error.d.ts

@@ -0,0 +1,16 @@
+export declare const enum ErrorCode {
+    MISSING_VALUE = 0,
+    INVALID_VALUE = 1,
+    MISSING_INTL_API = 2
+}
+export declare class FormatError extends Error {
+    readonly code: ErrorCode;
+    constructor(msg: string, code: ErrorCode);
+    toString(): string;
+}
+export declare class InvalidValueError extends FormatError {
+    constructor(variableId: string, value: any, options: string[]);
+}
+export declare class MissingValueError extends FormatError {
+    constructor(variableId: string, originalMessage?: string);
+}

package/dist/error.js

@@ -0,0 +1,44 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+var FormatError = /** @class */ (function (_super) {
+    __extends(FormatError, _super);
+    function FormatError(msg, code) {
+        var _this = _super.call(this, msg) || this;
+        _this.code = code;
+        return _this;
+    }
+    FormatError.prototype.toString = function () {
+        return "[formatjs Error: " + this.code + "] " + this.message;
+    };
+    return FormatError;
+}(Error));
+exports.FormatError = FormatError;
+var InvalidValueError = /** @class */ (function (_super) {
+    __extends(InvalidValueError, _super);
+    function InvalidValueError(variableId, value, options) {
+        return _super.call(this, "Invalid values for \"" + variableId + "\": \"" + value + "\". Options are \"" + Object.keys(options).join('", "') + "\"", 1 /* INVALID_VALUE */) || this;
+    }
+    return InvalidValueError;
+}(FormatError));
+exports.InvalidValueError = InvalidValueError;
+var MissingValueError = /** @class */ (function (_super) {
+    __extends(MissingValueError, _super);
+    function MissingValueError(variableId, originalMessage) {
+        return _super.call(this, "The intl string context variable \"" + variableId + "\" was not provided to the string \"" + originalMessage + "\"", 0 /* MISSING_VALUE */) || this;
+    }
+    return MissingValueError;
+}(FormatError));
+exports.MissingValueError = MissingValueError;

package/dist/formatters.d.ts

@@ -16,19 +16,17 @@ export interface Formatters {
 }
 export declare const enum PART_TYPE {
     literal = 0,
-    argument = 1
+    object = 1
 }
 export interface LiteralPart {
     type: PART_TYPE.literal;
     value: string;
 }
-export interface ArgumentPart {
-    type: PART_TYPE.argument;
-    value: any;
+export interface ObjectPart<T = any> {
+    type: PART_TYPE.object;
+    value: T;
 }
-export declare type MessageFormatPart = LiteralPart | ArgumentPart;
+export declare type MessageFormatPart<T> = LiteralPart | ObjectPart<T>;
 export declare type PrimitiveType = string | number | boolean | null | undefined | Date;
-export declare function formatToParts(els: MessageFormatElement[], locales: string | string[], formatters: Formatters, formats: Formats, values?: Record<string, any>, currentPluralValue?: number, originalMessage?: string): MessageFormatPart[];
-export declare function formatToString(els: MessageFormatElement[], locales: string | string[], formatters: Formatters, formats: Formats, values?: Record<string, PrimitiveType>, originalMessage?: string): string;
-export declare type FormatXMLElementFn = (...args: any[]) => string | object;
-export declare function formatHTMLMessage(els: MessageFormatElement[], locales: string | string[], formatters: Formatters, formats: Formats, values?: Record<string, PrimitiveType | object | FormatXMLElementFn>, originalMessage?: string): Array<string | object>;
+export declare function formatToParts<T>(els: MessageFormatElement[], locales: string | string[], formatters: Formatters, formats: Formats, values?: Record<string, PrimitiveType | T | FormatXMLElementFn<T>>, currentPluralValue?: number, originalMessage?: string): MessageFormatPart<T>[];
+export declare type FormatXMLElementFn<T> = (...args: Array<string | T>) => string | Array<string | T>;

package/dist/formatters.js

@@ -1,35 +1,7 @@
 "use strict";
-var __extends = (this && this.__extends) || (function () {
-    var extendStatics = function (d, b) {
-        extendStatics = Object.setPrototypeOf ||
-            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
-            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
-        return extendStatics(d, b);
-    };
-    return function (d, b) {
-        extendStatics(d, b);
-        function __() { this.constructor = d; }
-        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
-    };
-})();
-var __spreadArrays = (this && this.__spreadArrays) || function () {
-    for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;
-    for (var r = Array(s), k = 0, i = 0; i < il; i++)
-        for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)
-            r[k] = a[j];
-    return r;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 var intl_messageformat_parser_1 = require("intl-messageformat-parser");
-var FormatError = /** @class */ (function (_super) {
-    __extends(FormatError, _super);
-    function FormatError(msg, variableId) {
-        var _this = _super.call(this, msg) || this;
-        _this.variableId = variableId;
-        return _this;
-    }
-    return FormatError;
-}(Error));
+var error_1 = require("./error");
 function mergeLiteral(parts) {
     if (parts.length < 2) {
         return parts;
@@ -47,6 +19,9 @@ function mergeLiteral(parts) {
         return all;
     }, []);
 }
+function isFormatXMLElementFn(el) {
+    return typeof el === 'function';
+}
 // TODO(skeleton): add skeleton support
 function formatToParts(els, locales, formatters, formats, values, currentPluralValue, 
 // For debugging
@@ -85,7 +60,7 @@ originalMessage) {
         var varName = el.value;
         // Enforce that all required values are provided by the caller.
         if (!(values && varName in values)) {
-            throw new FormatError("The intl string context variable \"" + varName + "\" was not provided to the string \"" + originalMessage + "\"");
+            throw new error_1.MissingValueError(varName, originalMessage);
         }
         var value = values[varName];
         if (intl_messageformat_parser_1.isArgumentElement(el)) {
@@ -96,7 +71,7 @@ originalMessage) {
                         : '';
             }
             result.push({
-                type: 1 /* argument */,
+                type: typeof value === 'string' ? 0 /* literal */ : 1 /* object */,
                 value: value,
             });
             continue;
@@ -142,10 +117,28 @@ originalMessage) {
             });
             continue;
         }
+        if (intl_messageformat_parser_1.isTagElement(el)) {
+            var children = el.children, value_1 = el.value;
+            var formatFn = values[value_1];
+            if (!isFormatXMLElementFn(formatFn)) {
+                throw new TypeError("Value for \"" + value_1 + "\" must be a function");
+            }
+            var parts = formatToParts(children, locales, formatters, formats, values);
+            var chunks = formatFn.apply(void 0, parts.map(function (p) { return p.value; }));
+            if (!Array.isArray(chunks)) {
+                chunks = [chunks];
+            }
+            result.push.apply(result, chunks.map(function (c) {
+                return {
+                    type: typeof c === 'string' ? 0 /* literal */ : 1 /* object */,
+                    value: c,
+                };
+            }));
+        }
         if (intl_messageformat_parser_1.isSelectElement(el)) {
             var opt = el.options[value] || el.options.other;
             if (!opt) {
-                throw new RangeError("Invalid values for \"" + el.value + "\": \"" + value + "\". Options are \"" + Object.keys(el.options).join('", "') + "\"");
+                throw new error_1.InvalidValueError(el.value, value, Object.keys(el.options));
             }
             result.push.apply(result, formatToParts(opt.value, locales, formatters, formats, values));
             continue;
@@ -154,7 +147,7 @@ originalMessage) {
             var opt = el.options["=" + value];
             if (!opt) {
                 if (!Intl.PluralRules) {
-                    throw new FormatError("Intl.PluralRules is not available in this environment.\nTry polyfilling it using \"@formatjs/intl-pluralrules\"\n");
+                    throw new error_1.FormatError("Intl.PluralRules is not available in this environment.\nTry polyfilling it using \"@formatjs/intl-pluralrules\"\n", 2 /* MISSING_INTL_API */);
                 }
                 var rule = formatters
                     .getPluralRules(locales, { type: el.pluralType })
@@ -162,7 +155,7 @@ originalMessage) {
                 opt = el.options[rule] || el.options.other;
             }
             if (!opt) {
-                throw new RangeError("Invalid values for \"" + el.value + "\": \"" + value + "\". Options are \"" + Object.keys(el.options).join('", "') + "\"");
+                throw new error_1.InvalidValueError(el.value, value, Object.keys(el.options));
             }
             result.push.apply(result, formatToParts(opt.value, locales, formatters, formats, values, value - (el.offset || 0)));
             continue;
@@ -171,138 +164,3 @@ originalMessage) {
     return mergeLiteral(result);
 }
 exports.formatToParts = formatToParts;
-function formatToString(els, locales, formatters, formats, values, 
-// For debugging
-originalMessage) {
-    var parts = formatToParts(els, locales, formatters, formats, values, undefined, originalMessage);
-    // Hot path for straight simple msg translations
-    if (parts.length === 1) {
-        return parts[0].value;
-    }
-    return parts.reduce(function (all, part) { return (all += part.value); }, '');
-}
-exports.formatToString = formatToString;
-// Singleton
-var domParser;
-var TOKEN_DELIMITER = '@@';
-var TOKEN_REGEX = /@@(\d+_\d+)@@/g;
-var counter = 0;
-function generateId() {
-    return Date.now() + "_" + ++counter;
-}
-function restoreRichPlaceholderMessage(text, objectParts) {
-    return text
-        .split(TOKEN_REGEX)
-        .filter(Boolean)
-        .map(function (c) { return (objectParts[c] != null ? objectParts[c] : c); })
-        .reduce(function (all, c) {
-        if (!all.length) {
-            all.push(c);
-        }
-        else if (typeof c === 'string' &&
-            typeof all[all.length - 1] === 'string') {
-            all[all.length - 1] += c;
-        }
-        else {
-            all.push(c);
-        }
-        return all;
-    }, []);
-}
-/**
- * Not exhaustive, just for sanity check
- */
-var SIMPLE_XML_REGEX = /(<([0-9a-zA-Z-_]*?)>(.*?)<\/([0-9a-zA-Z-_]*?)>)|(<[0-9a-zA-Z-_]*?\/>)/;
-var TEMPLATE_ID = Date.now() + '@@';
-var VOID_ELEMENTS = [
-    'area',
-    'base',
-    'br',
-    'col',
-    'embed',
-    'hr',
-    'img',
-    'input',
-    'link',
-    'meta',
-    'param',
-    'source',
-    'track',
-    'wbr',
-];
-function formatHTMLElement(el, objectParts, values) {
-    var tagName = el.tagName;
-    var outerHTML = el.outerHTML, textContent = el.textContent, childNodes = el.childNodes;
-    // Regular text
-    if (!tagName) {
-        return restoreRichPlaceholderMessage(textContent || '', objectParts);
-    }
-    tagName = tagName.toLowerCase();
-    var isVoidElement = ~VOID_ELEMENTS.indexOf(tagName);
-    var formatFnOrValue = values[tagName];
-    if (formatFnOrValue && isVoidElement) {
-        throw new FormatError(tagName + " is a self-closing tag and can not be used, please use another tag name.");
-    }
-    if (!childNodes.length) {
-        return [outerHTML];
-    }
-    var chunks = Array.prototype.slice.call(childNodes).reduce(function (all, child) {
-        return all.concat(formatHTMLElement(child, objectParts, values));
-    }, []);
-    // Legacy HTML
-    if (!formatFnOrValue) {
-        return __spreadArrays(["<" + tagName + ">"], chunks, ["</" + tagName + ">"]);
-    }
-    // HTML Tag replacement
-    if (typeof formatFnOrValue === 'function') {
-        return [formatFnOrValue.apply(void 0, chunks)];
-    }
-    return [formatFnOrValue];
-}
-function formatHTMLMessage(els, locales, formatters, formats, values, 
-// For debugging
-originalMessage) {
-    var parts = formatToParts(els, locales, formatters, formats, values, undefined, originalMessage);
-    var objectParts = {};
-    var formattedMessage = parts.reduce(function (all, part) {
-        if (part.type === 0 /* literal */) {
-            return (all += part.value);
-        }
-        var id = generateId();
-        objectParts[id] = part.value;
-        return (all += "" + TOKEN_DELIMITER + id + TOKEN_DELIMITER);
-    }, '');
-    // Not designed to filter out aggressively
-    if (!SIMPLE_XML_REGEX.test(formattedMessage)) {
-        return restoreRichPlaceholderMessage(formattedMessage, objectParts);
-    }
-    if (!values) {
-        throw new FormatError('Message has placeholders but no values was given');
-    }
-    if (typeof DOMParser === 'undefined') {
-        throw new FormatError('Cannot format XML message without DOMParser');
-    }
-    if (!domParser) {
-        domParser = new DOMParser();
-    }
-    var content = domParser
-        .parseFromString("<formatted-message id=\"" + TEMPLATE_ID + "\">" + formattedMessage + "</formatted-message>", 'text/html')
-        .getElementById(TEMPLATE_ID);
-    if (!content) {
-        throw new FormatError("Malformed HTML message " + formattedMessage);
-    }
-    var tagsToFormat = Object.keys(values).filter(function (varName) { return !!content.getElementsByTagName(varName).length; });
-    // No tags to format
-    if (!tagsToFormat.length) {
-        return restoreRichPlaceholderMessage(formattedMessage, objectParts);
-    }
-    var caseSensitiveTags = tagsToFormat.filter(function (tagName) { return tagName !== tagName.toLowerCase(); });
-    if (caseSensitiveTags.length) {
-        throw new FormatError("HTML tag must be lowercased but the following tags are not: " + caseSensitiveTags.join(', '));
-    }
-    // We're doing this since top node is `<formatted-message/>` which does not have a formatter
-    return Array.prototype.slice
-        .call(content.childNodes)
-        .reduce(function (all, child) { return all.concat(formatHTMLElement(child, objectParts, values)); }, []);
-}
-exports.formatHTMLMessage = formatHTMLMessage;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import IntlMessageFormat from './core';
 export * from './formatters';
 export * from './core';
+export * from './error';
 export default IntlMessageFormat;

package/dist/index.js

@@ -11,4 +11,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var core_1 = require("./core");
 __export(require("./formatters"));
 __export(require("./core"));
+__export(require("./error"));
 exports.default = core_1.default;