@todoist/react-interpolate 0.0.0-stage → 2.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Doist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,222 @@
-# Temporary Holding Version
+# react-interpolate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![size](http://img.badgesize.io/https://cdn.jsdelivr.net/gh/todoist/react-interpolate/dist/react-interpolate.min.cjs?compression=gzip)](http://img.badgesize.io/https://cdn.jsdelivr.net/gh/todoist/react-interpolate/dist/react-interpolate.min.cjs?compression=gzip) [![Actions Status](https://github.com/todoist/react-interpolate/workflows/CI/badge.svg)](https://github.com/todoist/react-interpolate/actions)
+
+A string interpolation component that formats and interpolates a template string in a safe way.
+
+```jsx
+import Interpolate from '@todoist/react-interpolate'
+
+function Greeting() {
+    return (
+        <Interpolate
+            string="<h1>Hello {name}. Here is <a>your order info</a></h1>"
+            mapping={{
+                name: 'William',
+                a: <a href="https://orderinfo.com" />,
+            }}
+        />
+    )
+}
+```
+
+Would render the following HTML
+
+```html
+<h1>Hello William. Here is <a href="https://orderinfo.com">your order info</a></h1>
+```
+
+## Component API
+
+`<Interpolate>` component accepts the following props
+
+#### `string`
+
+The template string to be interpolated. Required.
+
+Please see the [Interpolation syntax](./#interpolation-syntax) section below for more detail.
+
+#### `mapping`
+
+An object that defines the values to be injected for placeholder and tags defined in the template string. Optional.
+
+-   For placeholder or self-closing tag, the mapping value could be any valid element value
+-   For open & close tag, the mapping value could be either renderer function or an element.
+
+```jsx
+<Interpolate
+    string="Hello {name}. Here is <orderLink>your order info</orderLink><hr/>.  \
+            Please contact <supportLink>support</supportLink> for help"
+    mapping={{
+        // you can map placholder and self-closing tag to any valid element value
+        name: 'William',
+        hr: <hr className="break" />,
+
+        // you can map open & close tag to a rendering function
+        orderLink: (text) => <a href="https://orderinfo.com">{text}</a>,
+
+        // or you can map open & close tag to an element
+        supportLink: <a href="https://orderinfo.com" />,
+    }}
+/>
+```
+
+#### `graceful`
+
+A boolean flag indicates how string syntax error or mapping error should be handled. When true, the raw string value from the prop `string` would be rendered as a fallback in the error scenario. When false, error would be thrown instead.
+
+Optional. `true` by default.
+
+```jsx
+// would render "an invalid string with unclose tag &lt;h1&gt;"
+<Interpolate graceful string="an invalid string with unclose tag <h1>" />
+```
+
+#### `syntax`
+
+Optional. `syntax` props allow use of react-Interpolate with different string formatting syntax. Please see the ["Custom syntax support"](#custom-syntax-support) section for more detail.
+
+## Interpolation syntax
+
+Here is interpolation syntax you can use in your `string`.
+
+#### Placeholder
+
+```jsx
+'hello {user_name}'
+```
+
+Placeholder name should be alphanumeric (`[A-Za-z0-9_]`). Placeholders could be mapped to any valid element value.
+
+#### Open & close tags
+
+```jsx
+'Here is <a>your order info</a>'
+
+// tag name could be any alphanumeric string
+'Here is <link>your order info</link>'
+
+// you can nest tag and placeholder
+'Here is <a><b>you order info {name}</b></a>'
+```
+
+Tag name should be alphanumeric (`[A-Za-z0-9_]`).
+
+Open & close tag could be mapped to an element value.
+
+```jsx
+<Interpolate
+    string="Here is <a>your order info</a>"
+    mapping={{
+        a: <a href="https://orderinfo.com" />
+    }}
+/>
+
+
+// Invalid; the mapping value element should not contain children
+<Interpolate
+    string="Here is <a>your order info</a>"
+    mapping={{
+        a: (
+            <a href="https://orderinfo.com">
+                <b />
+                <br />
+            </a>
+        )
+    }}
+/>
+```
+
+Open & close tag could be mapped to a rendering function, which would take a single argument that contains the enclosing text.
+
+```jsx
+<Interpolate
+    string="Here is <a>your order info</a>"
+    mapping={{
+        a: (text) => (
+            <a href="https://orderinfo.com">
+                <b>{text}</b>
+                <br />
+            </a>
+        ),
+    }}
+/>
+```
+
+Unclosed tag or incorrect nesting of tag would result in syntax error.
+
+```js
+// bad: no close tag
+'Here is <a>your order info'
+
+// bad: incorrect tag structure
+'Here is <a><b>your order info</a></b>'
+```
+
+#### Self closing tag
+
+```js
+'Hello.<br/>Here is your order'
+```
+
+Tag name should be alphanumeric (`[A-Za-z0-9_]`). Self closing tags could be mapped to any valid element value.
+
+## Auto tag element creation
+
+When tags are used the string but there are no correponding mapped value, it would by default create the corresponding HTML element by default.
+
+```jsx
+// would render: <h1>Hellow</h1><br/>World
+<Interpolate string="<h1>Hello</h1><br/>world" />
+```
+
+## Custom syntax support
+
+You may already be using a formatting syntax in your string that is different than the built-in syntax support from Interpolate. You can configure Interpolate so that it could recognize the formatting syntax that you use.
+
+For instance, you may be using [i18next](https://www.i18next.com/) which has a slightly different placeholder syntax.
+
+```
+hello {{name}}
+```
+
+You can define the formatting syntax of your string via `syntax` props.
+
+```jsx
+import Interpolate, { TOKEN_PLACEHOLDER } from "@todoist/react-interpolate"
+
+const i18nNextSyntax = [
+    {
+        type: TOKEN_PLACEHOLDER,
+        regex: /{{\s*(\w+)\s*}}/g
+    }
+]
+
+// will output "hi steven"
+<Interpolate
+    syntax={i18nNextSyntax}
+    string="hi {{name}}"
+    mapping={{
+        name: "steven"
+    }}
+/>
+```
+
+react-interpolate comes with i18next syntax support, and you can enable it via
+
+```jsx
+import { SYNTAX_I18NEXT } from "@todoist/react-interpolate"
+
+<Interpolate
+  syntax={SYNTAX_I18NEXT}
+  ...
+/>
+```
+
+# Releasing
+
+See [the release runbook](docs/releasing.md). Versions still follow semantic-release's Conventional Commits and the existing `v${version}` tag lineage: `fix:` selects a patch, `feat:` a minor and breaking changes a major. The first intended new-scope stable release is `@todoist/react-interpolate@2.2.5`, subject to actual history and collision checks.
+
+Pushes to `main` and `next` calculate the normal stable or `next.N` version and prepare a retained artifact without publishing. Authorized publication is an explicit protected operation: npm and GitHub Packages receive the same tarball, including bootstrap and missing-mirror retries. After both registry copies match, the release record commits the generated version/changelog back to `main`, creates the normal version tag and semantic-release channel note, and completes the GitHub release. `next` keeps its prerelease channel and skips source commitback; it never promotes `latest`.
+
+Keep the original successful run and artifact. Publication/record retries do not recalculate the version or rebuild the package, including after later workflow maintenance.

package/dist/react-interpolate.cjs

@@ -0,0 +1,444 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+var PropTypes = require('prop-types');
+var _classCallCheck = require('@babel/runtime/helpers/classCallCheck');
+var _createClass = require('@babel/runtime/helpers/createClass');
+var _objectWithoutProperties = require('@babel/runtime/helpers/objectWithoutProperties');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
+var PropTypes__default = /*#__PURE__*/_interopDefaultLegacy(PropTypes);
+var _classCallCheck__default = /*#__PURE__*/_interopDefaultLegacy(_classCallCheck);
+var _createClass__default = /*#__PURE__*/_interopDefaultLegacy(_createClass);
+var _objectWithoutProperties__default = /*#__PURE__*/_interopDefaultLegacy(_objectWithoutProperties);
+
+var TOKEN_PLACEHOLDER = 'TOKEN_PLACEHOLDER';
+var TOKEN_OPEN_TAG = 'TOKEN_OPEN_TAG';
+var TOKEN_CLOSE_TAG = 'TOKEN_CLOSE_TAG';
+var TOKEN_SELF_TAG = 'TOKEN_SELF_TAG';
+var TOKEN_TEXT = 'TOKEN_TEXT';
+var NODE_FRAGMENT = 'NODE_FRAGMENT';
+var NODE_TAG_ELEMENT = 'NODE_TAG_ELEMENT';
+var NODE_VOID_ELEMENT = 'NODE_VOID_ELEMENT';
+var NODE_PLACEHOLDER = 'NODE_PLACEHOLDER';
+var NODE_TEXT = 'NODE_TEXT';
+
+var _excluded = ["type", "children"];
+var Node = /*#__PURE__*/function () {
+  function Node(_ref) {
+    var type = _ref.type,
+      children = _ref.children,
+      fields = _objectWithoutProperties__default["default"](_ref, _excluded);
+    _classCallCheck__default["default"](this, Node);
+    this.type = type;
+    this.children = children || [];
+    for (var key in fields) {
+      this[key] = fields[key];
+    }
+    if (fields.token) {
+      this.string = fields.token.string;
+    }
+  }
+  _createClass__default["default"](Node, [{
+    key: "appendChild",
+    value: function appendChild(child) {
+      this.children.push(child);
+    }
+  }, {
+    key: "isLeaf",
+    get: function get() {
+      return this.children.length === 0;
+    }
+  }]);
+  return Node;
+}();
+Node.createTagNode = function (token, children) {
+  return new Node({
+    type: NODE_TAG_ELEMENT,
+    children: children,
+    name: token.name,
+    token: token
+  });
+};
+Node.createFragmentNode = function (children) {
+  return new Node({
+    type: NODE_FRAGMENT,
+    children: children
+  });
+};
+Node.createVoidNode = function (token) {
+  return new Node({
+    type: NODE_VOID_ELEMENT,
+    name: token.name,
+    token: token
+  });
+};
+Node.createTextNode = function (token) {
+  return new Node({
+    type: NODE_TEXT,
+    text: token.string,
+    token: token
+  });
+};
+Node.createPlaceholderNode = function (token) {
+  return new Node({
+    type: NODE_PLACEHOLDER,
+    name: token.name,
+    token: token
+  });
+};
+
+var SYNTAX_BUILT_IN = [{
+  type: TOKEN_PLACEHOLDER,
+  regex: /{\s*(\w+)\s*}/g
+}, {
+  type: TOKEN_OPEN_TAG,
+  regex: /<(\w+)>/g
+}, {
+  type: TOKEN_CLOSE_TAG,
+  regex: /<\/(\w+)>/g
+}, {
+  type: TOKEN_SELF_TAG,
+  regex: /<(\w+)\s*\/>/g
+}];
+var SYNTAX_I18NEXT = [{
+  type: TOKEN_PLACEHOLDER,
+  regex: /{{\s*(\w+)\s*}}/g
+}, {
+  type: TOKEN_OPEN_TAG,
+  regex: /<(\w+)>/g
+}, {
+  type: TOKEN_CLOSE_TAG,
+  regex: /<\/(\w+)>/g
+}, {
+  type: TOKEN_SELF_TAG,
+  regex: /<(\w+)\s*\/>/g
+}];
+
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) { n[e] = r[e]; } return n; }
+
+/*
+ * return a array of token object
+ */
+function lexer(string, syntax) {
+  var matches = [];
+  var _iterator = _createForOfIteratorHelper(syntax),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var rule = _step.value;
+      var type = rule.type,
+        regex = rule.regex;
+      var res;
+      while ((res = regex.exec(string)) !== null) {
+        matches.push({
+          type: type,
+          string: res[0],
+          name: res[1],
+          start: res.index,
+          end: res.index + res[0].length
+        });
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  matches.sort(function (a, b) {
+    return a.start - b.start;
+  });
+  var textTokens = [];
+  var start = 0;
+  matches.forEach(function (match) {
+    if (match.start === start) {
+      start = match.end;
+      return;
+    }
+    var end = match.start;
+    var text = string.substring(start, end);
+    textTokens.push({
+      type: TOKEN_TEXT,
+      string: text,
+      text: text,
+      start: start,
+      end: end
+    });
+    start = match.end;
+  });
+  var text = string.substring(start);
+  if (text !== '') {
+    textTokens.push({
+      type: TOKEN_TEXT,
+      string: text,
+      start: start,
+      end: string.length
+    });
+  }
+  var tokens = [].concat(textTokens, matches).sort(function (a, b) {
+    return a.start - b.start;
+  });
+  return tokens;
+}
+
+function parser(string, syntax) {
+  if (!syntax) {
+    syntax = SYNTAX_BUILT_IN;
+  }
+  var tokens = lexer(string, syntax);
+  var p = new Parser(tokens);
+  return p.parse();
+}
+var SYNTAX_ERROR = 'Syntax error. Please check if each open tag is closed correctly';
+
+// A special token representing end of the tream
+var EPSILON = {
+  type: 'EPSILON'
+};
+
+/*
+ * A recursive descent parser that construct a syntax tree represeting
+ * the DOM hierarchy structure.
+ *
+ * For instance, the following token
+ * <h1>hi <b>{name}</b></h1>
+ *
+ * Would result in the following tree
+ *
+ * <h1>
+ * ├─ "hi"
+ * └─ <b>
+ *    ├─ {name}
+ *
+ * The parser is based on the following grammar:
+ *
+ *   document ::= elementOrData
+ *   elementOrData ::= element elementOrData
+ *   elementOrData ::= data elementOrData
+ *   element ::= <open_tag> elementOrData <close_tag>
+ *   data ::= <selfTag>
+ *   data ::= <text>
+ *   data ::= <placeholder>
+ *
+ * ref: https://github.com/amghannam/Mini-XML-Recursive-Descent-Parser
+ */
+var Parser = /*#__PURE__*/function () {
+  function Parser(tokens) {
+    _classCallCheck__default["default"](this, Parser);
+    this.tokens = [].concat(tokens);
+    this.tags = [];
+  }
+  _createClass__default["default"](Parser, [{
+    key: "parse",
+    value: function parse() {
+      var tree = this.document();
+      if (!this.predict(EPSILON.type)) {
+        throw new Error(SYNTAX_ERROR);
+      }
+      return tree;
+    }
+
+    /*
+     * @return {Node}
+     */
+  }, {
+    key: "document",
+    value: function document() {
+      var children = this.elementOrData();
+      return Node.createFragmentNode(children);
+    }
+
+    /*
+     * @return {Node}
+     */
+  }, {
+    key: "element",
+    value: function element() {
+      var tagToken = this.openTag();
+      var children = this.elementOrData();
+      this.endTag();
+      return Node.createTagNode(tagToken, children);
+    }
+
+    /*
+     * @return {Token}
+     */
+  }, {
+    key: "openTag",
+    value: function openTag() {
+      if (!this.predict(TOKEN_OPEN_TAG)) {
+        throw new Error(SYNTAX_ERROR);
+      }
+      this.pushTag(this.lookahead);
+      return this.match(TOKEN_OPEN_TAG);
+    }
+
+    /*
+     * @return {[]Node}
+     */
+  }, {
+    key: "elementOrData",
+    value: function elementOrData() {
+      var children = [];
+      if (this.predict(TOKEN_OPEN_TAG)) {
+        children.push(this.element());
+        children = children.concat(this.elementOrData());
+      }
+      if (this.predict(TOKEN_SELF_TAG, TOKEN_TEXT, TOKEN_PLACEHOLDER)) {
+        var token = this.match(this.lookahead.type);
+        var node;
+        switch (token.type) {
+          case TOKEN_SELF_TAG:
+            node = Node.createVoidNode(token);
+            break;
+          case TOKEN_TEXT:
+            node = Node.createTextNode(token);
+            break;
+          case TOKEN_PLACEHOLDER:
+            node = Node.createPlaceholderNode(token);
+            break;
+        }
+        children.push(node);
+        children = children.concat(this.elementOrData());
+      }
+      return children;
+    }
+  }, {
+    key: "endTag",
+    value: function endTag() {
+      if (!this.predict(TOKEN_CLOSE_TAG)) {
+        throw new Error(SYNTAX_ERROR);
+      }
+      var openTag = this.tags.pop();
+      if (openTag.name !== this.lookahead.name) {
+        throw new Error(SYNTAX_ERROR);
+      }
+      this.match(TOKEN_CLOSE_TAG);
+    }
+  }, {
+    key: "lookahead",
+    get: function get() {
+      return this.tokens.length === 0 ? EPSILON : this.tokens[0];
+    }
+  }, {
+    key: "predict",
+    value: function predict() {
+      for (var _len = arguments.length, types = new Array(_len), _key = 0; _key < _len; _key++) {
+        types[_key] = arguments[_key];
+      }
+      return types.includes(this.lookahead.type);
+    }
+  }, {
+    key: "match",
+    value: function match(type) {
+      if (!this.predict(type)) {
+        throw new Error(SYNTAX_ERROR);
+      }
+      var token = this.tokens.shift();
+      return token;
+    }
+  }, {
+    key: "pushTag",
+    value: function pushTag(token) {
+      this.tags.push(token);
+    }
+  }]);
+  return Parser;
+}();
+
+var createElement = function createElement(node, mapping, keyPrefix) {
+  var children = node.children.map(function (c, i) {
+    return /*#__PURE__*/React__default["default"].createElement(React__default["default"].Fragment, {
+      key: keyPrefix + i
+    }, createElement(c, mapping, keyPrefix));
+  });
+  switch (node.type) {
+    case NODE_TEXT:
+      {
+        return node.text;
+      }
+    case NODE_FRAGMENT:
+      {
+        return /*#__PURE__*/React__default["default"].createElement(React__default["default"].Fragment, null, children);
+      }
+    case NODE_VOID_ELEMENT:
+      {
+        var val = mapping[node.name];
+        if (typeof val === 'function') {
+          return val();
+        }
+        return val || /*#__PURE__*/React__default["default"].createElement(node.name, null);
+      }
+    case NODE_TAG_ELEMENT:
+      {
+        var _val = mapping[node.name];
+        if (_val === undefined) {
+          return /*#__PURE__*/React__default["default"].createElement(node.name, null, children);
+        }
+        if (typeof _val === 'function') {
+          return _val(children);
+        }
+        if (/*#__PURE__*/React__default["default"].isValidElement(_val)) {
+          if (React__default["default"].Children.count(_val.props.children) !== 0) {
+            throw new Error('when passing an element as value, the element should not contains children');
+          }
+          return /*#__PURE__*/React__default["default"].cloneElement(_val, {
+            children: children
+          });
+        }
+        throw new Error("Invalid mapping value for \"".concat(node.name, "\". Only element or render function are accepted"));
+      }
+    case NODE_PLACEHOLDER:
+      {
+        var _val2 = mapping[node.name];
+        if (_val2 === undefined) {
+          console.warn("missing \"".concat(node.name, "\" in mapping"));
+          return node.string;
+        }
+        if (typeof _val2 === 'function') {
+          return _val2();
+        }
+        return _val2;
+      }
+    default:
+      return;
+  }
+};
+function Interpolate(_ref) {
+  var string = _ref.string,
+    syntax = _ref.syntax,
+    _ref$mapping = _ref.mapping,
+    mapping = _ref$mapping === void 0 ? {} : _ref$mapping,
+    _ref$graceful = _ref.graceful,
+    graceful = _ref$graceful === void 0 ? true : _ref$graceful;
+  try {
+    var tree = parser(string, syntax);
+    return createElement(tree, mapping, string);
+  } catch (e) {
+    if (graceful) {
+      console.error(e);
+      return string;
+    } else {
+      throw e;
+    }
+  }
+}
+Interpolate.propTypes = {
+  string: PropTypes__default["default"].string.isRequired,
+  mapping: PropTypes__default["default"].object,
+  graceful: PropTypes__default["default"].bool
+};
+
+exports.SYNTAX_BUILT_IN = SYNTAX_BUILT_IN;
+exports.SYNTAX_I18NEXT = SYNTAX_I18NEXT;
+exports.TOKEN_CLOSE_TAG = TOKEN_CLOSE_TAG;
+exports.TOKEN_OPEN_TAG = TOKEN_OPEN_TAG;
+exports.TOKEN_PLACEHOLDER = TOKEN_PLACEHOLDER;
+exports.TOKEN_SELF_TAG = TOKEN_SELF_TAG;
+exports["default"] = Interpolate;

package/dist/react-interpolate.d.ts

@@ -0,0 +1,18 @@
+export const TOKEN_PLACEHOLDER: 'TOKEN_PLACEHOLDER'
+
+type Syntax = {
+    type: typeof TOKEN_PLACEHOLDER
+    regex: RegExp
+}
+
+type InterpolateProps = {
+    string: string
+    mapping: {
+        [key: string]: ((children: React.ReactNode) => React.ReactNode) | React.ReactNode
+    }
+    syntax?: Syntax[]
+}
+
+declare function Interpolate(props: InterpolateProps): JSX.Element
+
+export = Interpolate