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

package/src/types.d.ts

@@ -1,5 +1,6 @@
 import type { InternalIntlMessage } from './message';
 import type { IntlMessageGetterAdditions } from './message-loader';
+import { FormatBuilderConstructor } from './format';
 
 /**
  * Use this function to define messages as part of the `@discord/intl`
@@ -11,14 +12,6 @@ import type { IntlMessageGetterAdditions } from './message-loader';
  */
 export declare function defineMessages(messages: object): object;
 
-/**
- * A map of tag names to render functions to apply when the tags are
- * encountered while formatting a message. Each `IntlManager` can be
- * constructed with a different map of these elements, for example to allow
- * one manager to render React output while another renders accessibility text.
- */
-export type RichTextElementMap = Record<string, (chunks: any[]) => any>;
-
 /**
  * Placeholder type representing that this property is a Hook to be rendered
  * while formatting.
@@ -46,19 +39,8 @@ export type IntlTime = string | number | Date | null | undefined;
  * strings, and are able to skip multiple formatting steps to work more
  * efficiently. This type represents those messages distinctly.
  */
-type PlainIntlMessage = string;
-/**
- * A richly-formatted message that injects dynamic values while formatting,
- * with the types of those values defined by the `FormatValues` object. All
- * messages of this type must have at least one value in the object, otherwise
- * the message should be typed as a `PlainIntlMessage`.
- */
-type TypedIntlMessage<FormatValues extends object> = InternalIntlMessage & {
-  __values: FormatValues;
-};
-
-type AnyIntlMessage<FormatValues extends object | undefined = undefined> =
-  FormatValues extends undefined ? PlainIntlMessage : TypedIntlMessage<FormatValues>;
+export type PlainIntlMessage = string;
+export type AnyIntlMessage = PlainIntlMessage | InternalIntlMessage;
 
 export interface IntlMessageGetter extends IntlMessageGetterAdditions {
   (locale: string): InternalIntlMessage | PlainIntlMessage;
@@ -85,8 +67,8 @@ export interface TypedIntlMessageGetter<FormatValues extends object | undefined>
   // from the declared type. The latter of these is definitely semantically
   // correct, but the former is more just an annoying part of the type system
   // because of this returned type being nested within this interface and the
-  // strict subtying that TypeScript uses.
-  (locale: string): InternalIntlMessage | PlainIntlMessage;
+  // strict subtyping that TypeScript uses.
+  (locale: string): InternalIntlMessage;
 
   /**
    * A phantom type (not part of the actual typing of the object) that ensures
@@ -183,7 +165,7 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
  * checked against the provided message types, and error messages will be
  * accurate as a result.
  */
-type FormatValuesFor<T> =
+export type FormatValuesFor<T> =
   // `[]` syntax forces TypeScript to not distribute the possible union of
   // types, meaning this represents "_all_ values of T are an extension of
   // the parent type", which in this case represents messages with no
@@ -209,12 +191,18 @@ type FormatValuesFor<T> =
  * the caller to inject React elements within a string, while an AST formatter
  * might require a specific object shape, or allow any plain object.
  */
-interface FunctionTypeMap {
+export interface FunctionTypeMap {
   link: any;
   hook: any;
   handler: any;
 }
 
+export interface FunctionTypes<Result, HandlerType = (content: Result[]) => Result | Result[]> {
+  link: undefined | ((content: Result[]) => Result | Result[]);
+  hook: undefined | ((content: Result[]) => Result | Result[]);
+  handler: undefined | HandlerType;
+}
+
 type ReplaceKeepingNullability<T, P> = P | Exclude<T, NonNullable<T>>;
 
 /**
@@ -226,6 +214,8 @@ type ReplaceKeepingNullability<T, P> = P | Exclude<T, NonNullable<T>>;
 type MapFunctionTypes<T, FunctionTypes extends FunctionTypeMap> = {
   [K in keyof T]: ReplaceKeepingNullability<
     T[K],
+    // TODO: replace these types with string literal types in the generated
+    // file, turning this whole chain into `FunctionTypes[T[K]] ?? T[K]`.
     NonNullable<T[K]> extends LinkFunction
       ? FunctionTypes['link']
       : NonNullable<T[K]> extends HookFunction
@@ -251,7 +241,7 @@ type CheckStrictAny<Check, Yes, No> = (Check extends never ? true : false) exten
  * // Result is `{name: string}`
  * ```
  */
-type IntlMessageGetterInnerType<T extends IntlMessageGetter> =
+export type IntlMessageGetterInnerType<T extends IntlMessageGetter> =
   T extends TypedIntlMessageGetter<infer U> ? U : never;
 
 /**
@@ -260,13 +250,12 @@ type IntlMessageGetterInnerType<T extends IntlMessageGetter> =
  * types from `FunctionTypes`. The result is the set of required values
  * necessary to format the message of type `T` with the calling formatter.
  */
-type RequiredFormatValues<
+export type RequiredFormatValues<
   Values extends IntlMessageGetter,
-  DefaultElements,
   FunctionTypes extends FunctionTypeMap,
 > =
   IntlMessageGetterInnerType<Values> extends undefined
-    ? never
+    ? {}
     : CheckStrictAny<
         IntlMessageGetterInnerType<Values>,
         // If `T` is explicitly `any`, then individual properties can't be typed and
@@ -277,23 +266,30 @@ type RequiredFormatValues<
         // value and turn every property into the mapped `LinkFunction` type, which
         // is almost always going to be wrong.
         any,
-        MapFunctionTypes<
-          Omit<FormatValuesFor<IntlMessageGetterInnerType<Values>>, keyof DefaultElements>,
-          FunctionTypes
-        >
+        MapFunctionTypes<FormatValuesFor<IntlMessageGetterInnerType<Values>>, FunctionTypes>
       >;
 
-export interface IntlOptionalRichTextKeys {
-  $_: any;
-  $b: any;
-  $i: any;
-  $p: any;
-  $link: any;
-  $code: any;
+export interface RichTextFormattingMap<T = any> {
+  $_: T;
+  $b: T;
+  $i: T;
+  $p: T;
+  $link: T;
+  $code: T;
 }
 
-export type IntlFormatFunctionValuesArg<T extends IntlMessageGetter> = RequiredFormatValues<
-  T,
-  IntlOptionalRichTextKeys,
-  FunctionTypeMap
->;
+export type RichTextTagNames = keyof RichTextFormattingMap;
+
+export interface FormatterImplementation<
+  FunctionTypes extends FunctionTypeMap,
+  Result,
+  BuilderResult = Result,
+> {
+  format: (
+    message: AnyIntlMessage,
+    values: object,
+    builder?: FormatBuilderConstructor<BuilderResult>,
+  ) => Result;
+  builder: FormatBuilderConstructor<BuilderResult extends (infer T)[] ? T : BuilderResult>;
+  __$functionTypes?: FunctionTypes;
+}

package/dist/react.d.ts

@@ -1,38 +0,0 @@
-import * as React from 'react';
-import { IntlManager } from './intl-manager';
-import type { IntlMessageGetter, RequiredFormatValues, RichTextElementMap, TypedIntlMessageGetter } from './types';
-type ReactHandlerEvent = React.MouseEvent | React.KeyboardEvent;
-type ReactClickHandler = (e: ReactHandlerEvent) => void;
-type ReactFunctionTypes = {
-    link: undefined | ((content: React.ReactNode | React.ReactNode[], key: string) => React.ReactNode);
-    hook: undefined | ((content: React.ReactNode | React.ReactNode[], key: string) => React.ReactNode);
-    handler: undefined | ReactClickHandler | {
-        onClick: ReactClickHandler;
-    } | {
-        onContextMenu: ReactClickHandler;
-    } | {
-        onClick: ReactClickHandler;
-        onContextMenu: ReactClickHandler;
-    };
-};
-export declare class IntlManagerReact<DefaultElements extends RichTextElementMap> extends IntlManager<DefaultElements, ReactFunctionTypes> {
-    /**
-     * A reactive component form of `intl.format` that automatically updates when
-     * the application's locale changes and when new data is loaded for the
-     * subject message.
-     */
-    IntlMessage: <T extends IntlMessageGetter>(props: {
-        message: T;
-        values?: RequiredFormatValues<T, DefaultElements, ReactFunctionTypes> | never;
-    }) => string | React.FunctionComponentElement<{
-        children?: React.ReactNode | undefined;
-    }>;
-    /**
-     * 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.
-     */
-    format<T extends TypedIntlMessageGetter<undefined>>(message: T): React.ReactElement;
-    format<T extends IntlMessageGetter>(message: T, values: RequiredFormatValues<T, DefaultElements, ReactFunctionTypes>): React.ReactElement;
-}
-export {};

package/dist/react.js

@@ -1,80 +0,0 @@
-"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 (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
-        return extendStatics(d, b);
-    };
-    return function (d, b) {
-        if (typeof b !== "function" && b !== null)
-            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
-        extendStatics(d, b);
-        function __() { this.constructor = d; }
-        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
-    };
-})();
-var __read = (this && this.__read) || function (o, n) {
-    var m = typeof Symbol === "function" && o[Symbol.iterator];
-    if (!m) return o;
-    var i = m.call(o), r, ar = [], e;
-    try {
-        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
-    }
-    catch (error) { e = { error: error }; }
-    finally {
-        try {
-            if (r && !r.done && (m = i["return"])) m.call(i);
-        }
-        finally { if (e) throw e.error; }
-    }
-    return ar;
-};
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.IntlManagerReact = void 0;
-var React = require("react");
-var intl_manager_1 = require("./intl-manager");
-var IntlManagerReact = /** @class */ (function (_super) {
-    __extends(IntlManagerReact, _super);
-    function IntlManagerReact() {
-        var _this = _super.apply(this, __spreadArray([], __read(arguments), false)) || this;
-        /**
-         * A reactive component form of `intl.format` that automatically updates when
-         * the application's locale changes and when new data is loaded for the
-         * subject message.
-         */
-        _this.IntlMessage = function (props) {
-            var message = props.message, values = props.values;
-            // Use the locale from this point in the application, which may be
-            // different from the global locale.
-            var locale = React.useSyncExternalStore(_this.onLocaleChange, function () { return _this.currentLocale; });
-            // TODO(faulty): This can and should be replaced with
-            // `use(messagesLoadedPromise)` once `use` is shipped to stable.
-            // Source the actual message to render for that locale from its loader.
-            React.useSyncExternalStore(message.onChange, function () { return message(locale); });
-            // If there are no object parts in the message, it has no formatting and can just be returned as
-            // a plain string.
-            if (typeof message === 'string')
-                return message;
-            var parts = _this.formatToParts(message, values);
-            if (parts.length === 1 && typeof parts[0] === 'string')
-                return parts[0];
-            return React.createElement(React.Fragment, undefined, _this.formatToParts(message, values));
-        };
-        return _this;
-    }
-    IntlManagerReact.prototype.format = function (message, values) {
-        return React.createElement((this.IntlMessage), { message: message, values: values });
-    };
-    return IntlManagerReact;
-}(intl_manager_1.IntlManager));
-exports.IntlManagerReact = IntlManagerReact;

package/src/react.ts

@@ -1,80 +0,0 @@
-import * as React from 'react';
-
-import { IntlManager } from './intl-manager';
-
-import type {
-  IntlMessageGetter,
-  RequiredFormatValues,
-  RichTextElementMap,
-  TypedIntlMessageGetter,
-} from './types';
-
-type ReactHandlerEvent = React.MouseEvent | React.KeyboardEvent;
-type ReactClickHandler = (e: ReactHandlerEvent) => void;
-
-type ReactFunctionTypes = {
-  // TODO: Allowing `undefined` on these is a migration artifact that should be
-  // removed. Functions, like all other values, should be required when
-  // formatting to avoid unexpected missing behavior.
-  link:
-    | undefined
-    | ((content: React.ReactNode | React.ReactNode[], key: string) => React.ReactNode);
-
-  hook:
-    | undefined
-    | ((content: React.ReactNode | React.ReactNode[], key: string) => React.ReactNode);
-  handler:
-    | undefined
-    | ReactClickHandler
-    | { onClick: ReactClickHandler }
-    | { onContextMenu: ReactClickHandler }
-    | { onClick: ReactClickHandler; onContextMenu: ReactClickHandler };
-};
-
-export class IntlManagerReact<DefaultElements extends RichTextElementMap> extends IntlManager<
-  DefaultElements,
-  ReactFunctionTypes
-> {
-  /**
-   * A reactive component form of `intl.format` that automatically updates when
-   * the application's locale changes and when new data is loaded for the
-   * subject message.
-   */
-  IntlMessage = <T extends IntlMessageGetter>(props: {
-    message: T;
-    values?: RequiredFormatValues<T, DefaultElements, ReactFunctionTypes> | never;
-  }) => {
-    const { message, values } = props;
-    // Use the locale from this point in the application, which may be
-    // different from the global locale.
-    const locale = React.useSyncExternalStore(this.onLocaleChange, () => this.currentLocale);
-    // TODO(faulty): This can and should be replaced with
-    // `use(messagesLoadedPromise)` once `use` is shipped to stable.
-    // Source the actual message to render for that locale from its loader.
-    React.useSyncExternalStore(message.onChange, () => message(locale));
-    // If there are no object parts in the message, it has no formatting and can just be returned as
-    // a plain string.
-    if (typeof message === 'string') return message;
-
-    const parts = this.formatToParts(message, values);
-    if (parts.length === 1 && typeof parts[0] === 'string') return parts[0];
-    return React.createElement(React.Fragment, undefined, this.formatToParts(message, values));
-  };
-
-  /**
-   * 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.
-   */
-  format<T extends TypedIntlMessageGetter<undefined>>(message: T): React.ReactElement;
-  format<T extends IntlMessageGetter>(
-    message: T,
-    values: RequiredFormatValues<T, DefaultElements, ReactFunctionTypes>,
-  ): React.ReactElement;
-  format<T extends IntlMessageGetter>(
-    message: T,
-    values?: RequiredFormatValues<T, DefaultElements, ReactFunctionTypes>,
-  ): React.ReactElement {
-    return React.createElement(this.IntlMessage<T>, { message, values });
-  }
-}