@discord/intl 0.1.2 → 0.2.0-canary.641ab2f

package/src/format.ts

@@ -0,0 +1,224 @@
+/**
+ * The core formatter, responsible for applying values to placeholders in
+ * messages and creating a static CST from the result. This method does _not_
+ * replace any of the rich-text formatting values (e.g., `$b` or `$link`) and
+ * leaves those to final formatters to apply as appropriate for the context
+ * of where the message is being rendered (e.g., React versus a plain string).
+ *
+ * The majority of this method is lifted from FormatJS' own `formatToParts`
+ * implementation, but is abstracted here to provide a few benefits:
+ * - working with the keyless AST format rather than having to transpose to the
+ *   exact object format that FormatJS expects.
+ * - understanding the difference between rich text formatting values and
+ *   user-provided values.
+ * - provide extra options related to the above for more control over how
+ *   formatting operates, while abstracting out some of the common values.
+ * - adding extra context for hook and link functions to provide a `key`
+ *   parameter, important to have React treat the resulting elements nicely.
+ */
+
+import { FormatJsNode, FormatJsNodeType } from './keyless-json';
+import { Formats, Formatters, MissingValueError } from 'intl-messageformat';
+import { RichTextTagNames } from './types';
+
+/**
+ * Returns true if the tag name should be considered a rich text tag that
+ * applies formatting to a message, rather than being a user-supplied value.
+ */
+function isRichTextTag(name: string) {
+  return name[0] === '$';
+}
+
+export abstract class FormatBuilder<Result> {
+  abstract pushRichTextTag(tag: RichTextTagNames, children: Result[]): void;
+  abstract pushLiteralText(text: string): void;
+  abstract pushObject(value: object): void;
+  abstract finish(): Result[];
+}
+
+export type FormatBuilderConstructor<Result> = new () => FormatBuilder<Result>;
+
+export function bindFormatValuesWithBuilder<T, Builder extends FormatBuilder<T>>(
+  builder: Builder,
+  nodes: FormatJsNode[],
+  locales: string | string[],
+  formatters: Formatters,
+  formats: Formats,
+  values: Record<string, string | object> = {},
+  currentPluralValue?: number,
+  originalMessage?: string,
+) {
+  // Hot path for static messages that are just parsed as a single string element.
+  if (nodes.length === 1 && nodes[0].type === FormatJsNodeType.Literal) {
+    builder.pushLiteralText(nodes[0].value);
+    return;
+  }
+
+  for (const node of nodes) {
+    switch (node.type) {
+      case FormatJsNodeType.Literal:
+        builder.pushLiteralText(node.value);
+        continue;
+
+      case FormatJsNodeType.Pound:
+        // Replace `#` in plural rules with the actual numeric value. Only
+        // numeric values are replaced, otherwise the value is completed ignored?
+        // Behavior copied from FormatJS directly.
+        if (typeof currentPluralValue === 'number') {
+          const value = formatters.getNumberFormat(locales).format(currentPluralValue);
+          builder.pushLiteralText(value);
+        }
+        continue;
+    }
+
+    const { value: variableName } = node;
+    // Enforce that all required values are provided by the caller, even if the
+    // actual value is falsy/undefined.
+    if (!(variableName in values) && !isRichTextTag(variableName)) {
+      throw new MissingValueError(variableName, originalMessage);
+    }
+
+    const value = values[variableName];
+
+    switch (node.type) {
+      case FormatJsNodeType.Argument:
+        // Empty values don't need to be added at all, they are purely for AST representation.
+        if (variableName == '$_') break;
+
+        if (typeof value === 'object') {
+          builder.pushObject(value);
+        } else {
+          // Taken from FormatJS: non-objects (strings, numbers, and falsy
+          // values) all get cast to strings immediately as literal nodes.
+          builder.pushLiteralText(String(value));
+        }
+        break;
+      case FormatJsNodeType.Date: {
+        // Distinct from FormatJS: We don't currently parse the skeleton ahead of time in the AST,
+        // so this manages parsing the skeleton as well before passing it onto the date formatter.
+        if (typeof node.style !== 'string') {
+          throw '@discord/intl does not currently support non-string format skeletons';
+        }
+        const style = node.style in formats.date ? formats.date[node.style] : undefined; // TODO: parseSkeleton();
+        // @ts-expect-error Cast string values to dates properly.
+        builder.pushLiteralText(formatters.getDateTimeFormat(locales, style).format(value));
+        break;
+      }
+      case FormatJsNodeType.Time: {
+        // Distinct from FormatJS: We don't currently parse the skeleton ahead of time in the AST,
+        // so this manages parsing the skeleton as well before passing it onto the date formatter.
+        if (typeof node.style !== 'string') {
+          throw '@discord/intl does not currently support non-string format skeletons';
+        }
+        const style = node.style in formats.time ? formats.time[node.style] : undefined; // TODO: parseSkeleton();
+        builder.pushLiteralText(
+          // @ts-expect-error Cast string values to dates properly.
+          formatters.getDateTimeFormat(locales, style).format(value),
+        );
+        break;
+      }
+      case FormatJsNodeType.Number: {
+        // Distinct from FormatJS: We don't currently parse the skeleton ahead of time in the AST,
+        // so this manages parsing the skeleton as well before passing it onto the date formatter.
+        if (typeof node.style !== 'string') {
+          throw '@discord/intl does not currently support non-string format skeletons';
+        }
+        const style = node.style in formats.number ? formats.number[node.style] : undefined; // TODO: parseSkeleton();
+
+        // @ts-expect-error Support `scale` style property.
+        const scaledValue = value as number;
+        // const scaledValue = (value as number) * (style?.scale ?? 1);
+        builder.pushLiteralText(formatters.getNumberFormat(locales, style).format(scaledValue));
+        break;
+      }
+
+      case FormatJsNodeType.Tag: {
+        const { children } = node;
+        const appliedChildren = bindFormatValues(
+          builder.constructor as FormatBuilderConstructor<T>,
+          children,
+          locales,
+          formatters,
+          formats,
+          values,
+          currentPluralValue,
+        );
+        if (isRichTextTag(variableName)) {
+          builder.pushRichTextTag(variableName as RichTextTagNames, appliedChildren);
+        } else {
+          if (typeof value !== 'function') {
+            throw `expected a function type for a Tag formatting value, ${variableName}. got ${typeof value}: ${value}`;
+          }
+          let chunks = value(appliedChildren);
+          chunks = Array.isArray(chunks) ? chunks : [chunks];
+          for (const chunk of chunks) {
+            if (typeof chunk === 'string') {
+              builder.pushLiteralText(chunk);
+            } else {
+              builder.pushObject(chunk);
+            }
+          }
+        }
+        break;
+      }
+
+      case FormatJsNodeType.Select: {
+        const option = node.value in node.options ? node.options[node.value] : node.options.other;
+        if (option == null) {
+          throw `${node.value} is not a known option for select value ${variableName}. Valid options are ${Object.keys(node.options).join(', ')}`;
+        }
+        bindFormatValuesWithBuilder(builder, option.value, locales, formatters, formats, values);
+        break;
+      }
+
+      case FormatJsNodeType.Plural: {
+        const option = (() => {
+          const exactSelector = `=${value}`;
+          if (exactSelector in node.options) return node.options[exactSelector];
+          const rule = formatters
+            .getPluralRules(locales, { type: node.pluralType })
+            // @ts-expect-error Assert this `as number` properly.
+            .select((value as number) - (node.offset ?? 0));
+          return node.options[rule] ?? node.options.other;
+        })();
+
+        if (option == null) {
+          throw `${node.value} is not a known option for plural value ${variableName}. Valid options are ${Object.keys(node.options).join(', ')}`;
+        }
+        bindFormatValuesWithBuilder(
+          builder,
+          option.value,
+          locales,
+          formatters,
+          formats,
+          values,
+          // @ts-expect-error assert this `as number` properly.
+          (value as number) - (node.offset ?? 0),
+        );
+        break;
+      }
+    }
+  }
+}
+
+export function bindFormatValues<Result>(
+  Builder: FormatBuilderConstructor<Result>,
+  nodes: FormatJsNode[],
+  locales: string | string[],
+  formatters: Formatters,
+  formats: Formats,
+  values: Record<string, string | object> = {},
+  currentPluralValue?: number,
+): Result[] {
+  const builder = new Builder();
+  bindFormatValuesWithBuilder(
+    builder,
+    nodes,
+    locales,
+    formatters,
+    formats,
+    values,
+    currentPluralValue,
+  );
+  return builder.finish();
+}

package/src/formatters/ast.ts

@@ -0,0 +1,155 @@
+import {
+  AnyIntlMessage,
+  FormatterImplementation,
+  FunctionTypes,
+  type RichTextFormattingMap,
+  RichTextTagNames,
+} from '../types';
+import { IntlManager } from '../intl-manager';
+import { FormatBuilder } from '../format';
+
+/**
+ * Types for formatting functions when calling `formatToParts`, ensuring the
+ * functions yield value AST nodes.
+ */
+export type AstFunctionTypes = FunctionTypes<RichTextNode>;
+
+// This structure aims to match `simple-markdown`'s AST, but that type is very
+// loosely defined as just "type" and "arbitrary map of content". This is more
+// explicit and type-safe.
+export enum RichTextNodeType {
+  Text = 'text',
+  Strong = 'strong',
+  Emphasis = 'emphasis',
+  Code = 'code',
+  Link = 'link',
+  Paragraph = 'paragraph',
+  /**
+   * A special extension for when the value of a placeholder is an object.
+   * Rather than casting to a string here, the object is preserved as-is for a
+   * future formatter to render as appropriate (i.e., using an object as a
+   * value when formatting to an AST should keep that object structure so that
+   * the final AST is accurate for what the user expects, but when rendering to
+   * a plain string, the final formatter can just cast that object to a string
+   * using its `toString` method or some other mechanism).
+   */
+  Object = 'object',
+}
+
+const RICH_TEXT_TAG_TYPES: Record<RichTextTagNames, RichTextNodeType> = {
+  $_: RichTextNodeType.Text,
+  $b: RichTextNodeType.Strong,
+  $i: RichTextNodeType.Emphasis,
+  $code: RichTextNodeType.Code,
+  $link: RichTextNodeType.Link,
+  $p: RichTextNodeType.Paragraph,
+};
+
+interface RichTextNodeBase<ContentType> {
+  type: RichTextNodeType;
+  content: ContentType;
+}
+interface RichTextTextNode extends RichTextNodeBase<string> {
+  type: RichTextNodeType.Text;
+}
+interface RichTextStrongNode extends RichTextNodeBase<RichTextNode[]> {
+  type: RichTextNodeType.Strong;
+}
+interface RichTextEmphasisNode extends RichTextNodeBase<RichTextNode[]> {
+  type: RichTextNodeType.Emphasis;
+}
+interface RichTextCodeNode extends RichTextNodeBase<RichTextNode[]> {
+  type: RichTextNodeType.Code;
+}
+interface RichTextParagraphNode extends RichTextNodeBase<RichTextNode[]> {
+  type: RichTextNodeType.Paragraph;
+}
+interface RichTextLinkNode extends RichTextNodeBase<RichTextNode[]> {
+  type: RichTextNodeType.Link;
+  target: string;
+}
+interface RichTextObjectNode extends RichTextNodeBase<object> {
+  type: RichTextNodeType.Object;
+}
+
+export type RichTextNode =
+  | RichTextTextNode
+  | RichTextStrongNode
+  | RichTextEmphasisNode
+  | RichTextCodeNode
+  | RichTextParagraphNode
+  | RichTextLinkNode
+  | RichTextObjectNode;
+
+const AST_RICH_TEXT_ELEMENTS: RichTextFormattingMap<AstFunctionTypes['hook']> = {
+  $_: () => ({ type: RichTextNodeType.Text, content: '' }),
+  $b: (content) => ({ type: RichTextNodeType.Strong, content }),
+  $code: (content) => ({ type: RichTextNodeType.Code, content }),
+  $i: (content) => ({ type: RichTextNodeType.Emphasis, content }),
+  $link: ([target, ...content]) => ({
+    type: RichTextNodeType.Link,
+    target: target.content as string,
+    content,
+  }),
+  $p: (content) => ({ type: RichTextNodeType.Paragraph, content }),
+};
+
+class AstBuilder extends FormatBuilder<RichTextNode> {
+  result: RichTextNode[] = [];
+
+  pushRichTextTag(tag: RichTextTagNames, children: RichTextNode[]) {
+    if (!(tag in AST_RICH_TEXT_ELEMENTS)) {
+      throw `${tag} is not a known rich text formatting tag`;
+    }
+    const result = AST_RICH_TEXT_ELEMENTS[tag](children);
+    if (Array.isArray(result)) {
+      this.result.push(...result);
+    } else {
+      this.result.push(result);
+    }
+  }
+
+  pushLiteralText(text: string) {
+    const last = this.result[this.result.length - 1];
+    if (last.type === RichTextNodeType.Text) {
+      last.content += text;
+    } else {
+      this.result.push({ type: RichTextNodeType.Text, content: text });
+    }
+  }
+
+  pushObject(value: object) {
+    this.result.push({ type: RichTextNodeType.Object, content: value });
+  }
+
+  finish(): RichTextNode[] {
+    return this.result;
+  }
+}
+
+/**
+ * Format the given message in the current locale with the provided values.
+ * The returned values is _always_ an Array of parts, even if the message is
+ * a simple string value.
+ *
+ * This function is the basis of how messages are normally formatted, and can
+ * be used anywhere. However, it is not reactive and only functions on the
+ * data that is currently loaded and known. For a reactive function that
+ * automatically updates when the locale changes or when new data is loaded,
+ * use `format`, which will wrap the formatting in a React component that
+ * subscribes to the current locale and state of loaded messages.
+ */
+export function formatToAst(
+  this: IntlManager,
+  message: AnyIntlMessage,
+  values: object,
+): RichTextNode[] {
+  if (typeof message === 'string') return [{ type: RichTextNodeType.Text, content: message }];
+
+  return this.bindFormatValues(AstBuilder, message, values);
+}
+
+export const astFormatter: FormatterImplementation<AstFunctionTypes, RichTextNode[]> = {
+  format: formatToAst,
+  builder: AstBuilder,
+};

package/src/formatters/index.ts

@@ -0,0 +1,9 @@
+export { astFormatter, type AstFunctionTypes, type RichTextNode, RichTextNodeType } from './ast';
+export { markdownFormatter, type MarkdownFunctionTypes } from './markdown';
+export {
+  reactFormatter,
+  makeReactFormatter,
+  DEFAULT_REACT_RICH_TEXT_ELEMENTS,
+  type ReactFunctionTypes,
+} from './react';
+export { stringFormatter, type StringFunctionTypes } from './string';

package/src/formatters/markdown.ts

@@ -0,0 +1,54 @@
+/**
+ * Similar to `formatToPlainString`, format the given message with the provided
+ * values, but convert all rich text formatting back to Markdown syntax rather
+ * than rendering the actual rich content. The result is a plain string that
+ * can be sent through a separate Markdown renderer to get an equivalent
+ * result to formatting this message directly.
+ */
+import {
+  AnyIntlMessage,
+  FormatterImplementation,
+  FunctionTypes,
+  RichTextFormattingMap,
+  RichTextTagNames,
+} from '../types';
+import { IntlManager } from '../intl-manager';
+import { FormatBuilderConstructor } from '../format';
+import { StringBuilder } from './string';
+
+export type MarkdownFunctionTypes = FunctionTypes<string>;
+
+const MARKDOWN_RICH_TEXT_ELEMENTS: RichTextFormattingMap<MarkdownFunctionTypes['hook']> = {
+  $_: () => '',
+  $b: (content) => '**' + content.join('') + '**',
+  $code: (content) => '`' + content.join('') + '`',
+  $i: (content) => '*' + content.join('') + '*',
+  $link: ([target, ...content]) => '[' + content.join('') + '](' + target + ')',
+  $p: (content) => content.join('') + '\n\n',
+};
+
+class MarkdownBuilder extends StringBuilder {
+  result: string = '';
+
+  pushRichTextTag(tag: RichTextTagNames, children: string[]) {
+    this.result += MARKDOWN_RICH_TEXT_ELEMENTS[tag](children);
+  }
+}
+
+export function formatToMarkdownString(
+  this: IntlManager,
+  message: AnyIntlMessage,
+  values: object,
+  Builder: FormatBuilderConstructor<string> = MarkdownBuilder,
+): string {
+  if (typeof message === 'string') return message;
+
+  const result = this.bindFormatValues(Builder, message, values);
+  // MarkdownBuilder always creates a single-element array with the string value.
+  return result[0];
+}
+
+export const markdownFormatter: FormatterImplementation<MarkdownFunctionTypes, string> = {
+  format: formatToMarkdownString,
+  builder: MarkdownBuilder,
+};

package/src/formatters/react.ts

@@ -0,0 +1,100 @@
+/**
+ * Format the given message as a React component, allowing it to listen for
+ * and respond to updates about the current locale and other relevant
+ * information.
+ */
+import type {
+  AnyIntlMessage,
+  FormatterImplementation,
+  FunctionTypes,
+  RichTextFormattingMap,
+  RichTextTagNames,
+} from '../types';
+import * as React from 'react';
+import { IntlManager } from '../intl-manager';
+import { FormatBuilder, FormatBuilderConstructor } from '../format';
+
+export type ReactHandlerEvent = React.MouseEvent | React.KeyboardEvent;
+export type ReactClickHandler = (e: ReactHandlerEvent) => void;
+
+export type ReactFunctionTypes = FunctionTypes<
+  React.ReactNode,
+  | ReactClickHandler
+  | { onClick: ReactClickHandler }
+  | { onContextMenu: ReactClickHandler }
+  | { onClick: ReactClickHandler; onContextMenu: ReactClickHandler }
+>;
+
+const h = React.createElement;
+export const DEFAULT_REACT_RICH_TEXT_ELEMENTS: RichTextFormattingMap<ReactFunctionTypes['hook']> = {
+  $_: () => '',
+  $b: (content) => h('strong', undefined, content),
+  $code: (content) => h('code', undefined, content),
+  $i: (content) => h('em', undefined, content),
+  // $link will always be [href, <empty>, ...content]
+  $link: ([href, ...content]) => h('a', { href }, content),
+  $p: (content) => h('p', undefined, content),
+};
+
+/**
+ * Creates a new `FormatBuilder` class that constructs a React element tree
+ * from the message using the given `richTextElements` to apply formatting.
+ * This allows consumers to inject their own design system components and
+ * overrides for rendering elements like links, paragraphs, and code blocks.
+ * @param richTextElements
+ */
+function createReactBuilder(richTextElements: RichTextFormattingMap<ReactFunctionTypes['hook']>): {
+  new (): FormatBuilder<React.ReactNode>;
+} {
+  return class extends FormatBuilder<React.ReactNode> {
+    result: React.ReactNode[] = [];
+
+    pushRichTextTag(tag: RichTextTagNames, children: React.ReactNode[]) {
+      this.result.push(richTextElements[tag](children));
+    }
+
+    pushLiteralText(text: string) {
+      this.result.push(text);
+    }
+
+    pushObject(value: object) {
+      // @ts-expect-error this is technically invalid, but we'll just assume that if a format returns
+      // an object, it'll be acting as some form of ReactNode.
+      this.result.push(value);
+    }
+
+    finish(): React.ReactNode[] {
+      return this.result;
+    }
+  };
+}
+
+export function formatReact(
+  this: IntlManager,
+  message: AnyIntlMessage,
+  values: object,
+  Builder: FormatBuilderConstructor<React.ReactElement>,
+): React.ReactElement {
+  if (typeof message === 'string') {
+    return React.createElement(React.Fragment, undefined, message);
+  }
+
+  const parts = this.bindFormatValues(Builder, message, values);
+  return React.createElement(React.Fragment, undefined, parts);
+}
+
+/**
+ * Create a new React formatter with the given rich text elements replacing the defaults. Use this
+ * function to inject custom components for things like links and paragraphs, which may be best
+ * suited to use components from a Design System or other library rather than native DOM elements.
+ */
+export function makeReactFormatter(
+  richTextElements: RichTextFormattingMap<ReactFunctionTypes['hook']>,
+): FormatterImplementation<ReactFunctionTypes, React.ReactElement, React.ReactNode> {
+  return {
+    format: formatReact,
+    builder: createReactBuilder(richTextElements),
+  };
+}
+
+export const reactFormatter = makeReactFormatter(DEFAULT_REACT_RICH_TEXT_ELEMENTS);

package/src/formatters/string.ts

@@ -0,0 +1,62 @@
+/**
+ * Format the given message with the provided values, removing any styling
+ * and non-textual content from the message, returning a plain string.
+ */
+import { AnyIntlMessage, FormatterImplementation, FunctionTypes, RichTextTagNames } from '../types';
+import { FormatBuilder } from '../format';
+import { IntlManager } from '../intl-manager';
+
+/**
+ * Types for formatting functions when calling `bindFormatValues`, ensuring the
+ * functions always yield plain strings.
+ */
+export type StringFunctionTypes = FunctionTypes<string>;
+
+export class StringBuilder extends FormatBuilder<string> {
+  result: string = '';
+
+  pushRichTextTag(tag: RichTextTagNames, children: string[]) {
+    // Plain string formatting ignores rich text tags and just takes the
+    // visible content from the children. This means the `target` element
+    // of a link is ignored, otherwise all the children are just joined
+    // together directly.
+    if (tag === '$link') {
+      this.result += children.slice(1).join('');
+      return;
+    }
+    this.result += children.join('');
+  }
+
+  pushLiteralText(text: string) {
+    this.result += text;
+  }
+
+  pushObject(value: object) {
+    // Objects are only included in the result if they specify a toString value directly.
+    // Otherwise, they would be rendered as `[object Object]`, which is never helpful.
+    if ('toString' in value) {
+      this.result += value.toString();
+    }
+  }
+
+  finish(): string[] {
+    return [this.result];
+  }
+}
+
+export function formatToPlainString(
+  this: IntlManager,
+  message: AnyIntlMessage,
+  values: object,
+): string {
+  if (typeof message === 'string') return message;
+
+  const result = this.bindFormatValues(StringBuilder, message, values);
+  // StringBuilder always creates a single element array with the string value.
+  return result[0];
+}
+
+export const stringFormatter: FormatterImplementation<StringFunctionTypes, string> = {
+  format: formatToPlainString,
+  builder: StringBuilder,
+};

package/src/index.ts

@@ -1,9 +1,9 @@
-import { IntlManager } from './intl-manager';
-import { IntlManagerReact } from './react';
-
-export { IntlManager, createLoader, DEFAULT_LOCALE } from './intl-manager';
-export { IntlManagerReact } from './react';
+import * as React from 'react';
+import { RichTextNode } from './formatters';
 
+export * from './formatters';
+export { IntlManager, DEFAULT_LOCALE, type FormatFunction } from './intl-manager';
+export { createLoader, waitForAllDefaultIntlMessagesLoaded } from './message-loader';
 export type * from './types.d.ts';
 
 /**
@@ -21,7 +21,7 @@ export type * from './types.d.ts';
  * intl message, even if the actual value comes from elsewhere (like a
  * user-generated string).
  */
-export type ReactIntlMessage = string | ReturnType<IntlManagerReact<any>['format']>;
+export type ReactIntlMessage = string | React.ReactElement;
 
 /**
  * The return value of `formatToParts` from `@discord/intl`, this type
@@ -33,4 +33,4 @@ export type ReactIntlMessage = string | ReturnType<IntlManagerReact<any>['format
  * from a call to `formatToParts`, meaning they are intended to be fully static
  * structures passed around for custom rendering functions to use.
  */
-export type IntlMessageAst = ReturnType<IntlManager<any, any>['formatToParts']>;
+export type IntlMessageAst = RichTextNode;