@discord/intl 0.1.0-rc.1 → 0.1.1

package/dist/index.d.ts

@@ -1,3 +1,32 @@
+import { IntlManager } from './intl-manager';
+import { IntlManagerReact } from './react';
 export { IntlManager, createLoader, DEFAULT_LOCALE } from './intl-manager';
 export { IntlManagerReact } from './react';
 export type * from './types.d.ts';
+/**
+ * A type representing any message that has been formatted using one of the
+ * default formatting methods in the `@discord/intl` system. Use this type
+ * when you don't care about whether a message is static or contains rich text
+ * or has dynamically-formatted values, when you need to handle both in tandem,
+ * or when you need a generic return type for a function returning "any
+ * any-already formatted message".
+ *
+ * Generally, this is like `React.ReactNode`, accepting both strings and rich
+ * `ReactElement`s, but it is more specific to disallow nullish values and
+ * other special React elements like `ReactPortal`. Seeing this type, you can
+ * be confident that the value is intended to be the result of formatting an
+ * intl message, even if the actual value comes from elsewhere (like a
+ * user-generated string).
+ */
+export type ReactIntlMessage = string | ReturnType<IntlManagerReact<any>['format']>;
+/**
+ * The return value of `formatToParts` from `@discord/intl`, this type
+ * represents any AST structure for a message rendered using this system.
+ * The AST generally follows a Markdown-like structure, with text nodes
+ * interspersed within and around rich text formatting nodes.
+ *
+ * ASTs are created _after_ all placeholders have been filled by values
+ * 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']>;

package/dist/intl-manager.d.ts

@@ -1,12 +1,21 @@
 import { IntlShape } from '@formatjs/intl';
 import { LocaleId, LocaleImportMap, MessageLoader } from './message-loader';
-import type { FormatValuesFor, RichTextElementMap, TypedIntlMessageGetter } from './types';
+import type { FunctionTypeMap, IntlMessageGetter, RequiredFormatValues, RichTextElementMap, TypedIntlMessageGetter } from './types';
+/**
+ * Types for formatting functions when calling `formatToParts`, ensuring the
+ * functions yield value AST nodes.
+ */
+type AstFunctionTypes = {
+    link: undefined | object | ((children: object) => Array<string | any>);
+    hook: undefined | object | ((children: object) => Array<string | any>);
+    handler: undefined | object | ((children: object) => Array<string | any>);
+};
 /**
  * Fallback locale used for all internationalization when an operation in the
  * requested locale is not possible.
  */
 export declare const DEFAULT_LOCALE: string;
-export declare class IntlManager<DefaultElements extends RichTextElementMap, DefaultValues extends keyof DefaultElements> {
+export declare class IntlManager<DefaultElements extends RichTextElementMap, FunctionTypes extends FunctionTypeMap> {
     defaultLocale: string;
     currentLocale: string;
     intl: IntlShape;
@@ -42,8 +51,8 @@ export declare class IntlManager<DefaultElements extends RichTextElementMap, Def
      * use `format`, which will wrap the formatting in a React component that
      * subscribes to the current locale and state of loaded messages.
      */
-    formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(message: T): Array<string | any>;
-    formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(message: T, values: Omit<FormatValuesFor<T>, DefaultValues>): Array<string | any>;
+    formatToParts<T extends TypedIntlMessageGetter<undefined>>(message: T): Array<string | any>;
+    formatToParts<T extends IntlMessageGetter>(message: T, values: RequiredFormatValues<T, DefaultElements, AstFunctionTypes>): Array<string | any>;
     /**
      * For messages with no formatting values (i.e., plain strings, they can skip
      * a majority of the processing work and just resolve the message itself for
@@ -58,8 +67,8 @@ export declare class IntlManager<DefaultElements extends RichTextElementMap, Def
      * Format the given message with the provided values, removing any styling
      * and non-textual content from the message, returning a plain string.
      */
-    formatToPlainString<T extends TypedIntlMessageGetter<object | undefined>>(message: T): string;
-    formatToPlainString<T extends TypedIntlMessageGetter<object | undefined>>(message: T, values: Omit<FormatValuesFor<T>, DefaultValues>): string;
+    formatToPlainString<T extends TypedIntlMessageGetter<undefined>>(message: T): string;
+    formatToPlainString<T extends IntlMessageGetter>(message: T, values: RequiredFormatValues<T, DefaultElements, FunctionTypes>): string;
     /**
      * Similar to `formatToPlainString`, format the given message with the provided
      * values, but convert all rich text formatting back to Markdown syntax rather
@@ -67,8 +76,8 @@ export declare class IntlManager<DefaultElements extends RichTextElementMap, Def
      * can be sent through a separate Markdown renderer to get an equivalent
      * result to formatting this message directly.
      */
-    formatToMarkdownString<T extends TypedIntlMessageGetter<object | undefined>>(message: T): string;
-    formatToMarkdownString<T extends TypedIntlMessageGetter<object | undefined>>(message: T, values: Omit<FormatValuesFor<T>, DefaultValues>): string;
+    formatToMarkdownString<T extends TypedIntlMessageGetter<undefined>>(message: T): string;
+    formatToMarkdownString<T extends IntlMessageGetter>(message: T, values: RequiredFormatValues<T, DefaultElements, FunctionTypes>): string;
 }
 /**
  * Create a new MessageLoader, which handles lazily loading messages for
@@ -76,3 +85,4 @@ export declare class IntlManager<DefaultElements extends RichTextElementMap, Def
  * message defined in `messageKeys`.
  */
 export declare function createLoader(messageKeys: string[], localeImportMap: LocaleImportMap, defaultLocale: LocaleId): MessageLoader;
+export {};

package/dist/react.d.ts

@@ -1,15 +1,29 @@
 import * as React from 'react';
 import { IntlManager } from './intl-manager';
-import type { FormatValuesFor, RichTextElementMap, TypedIntlMessageGetter } from './types';
-export declare class IntlManagerReact<DefaultElements extends RichTextElementMap, DefaultValues extends keyof DefaultElements> extends IntlManager<DefaultElements, DefaultValues> {
+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 TypedIntlMessageGetter<object | undefined>>(props: {
+    IntlMessage: <T extends IntlMessageGetter>(props: {
         message: T;
-        values?: Omit<FormatValuesFor<T>, DefaultValues> | never;
+        values?: RequiredFormatValues<T, DefaultElements, ReactFunctionTypes> | never;
     }) => string | React.FunctionComponentElement<{
         children?: React.ReactNode | undefined;
     }>;
@@ -18,6 +32,7 @@ export declare class IntlManagerReact<DefaultElements extends RichTextElementMap
      * and respond to updates about the current locale and other relevant
      * information.
      */
-    format<T extends TypedIntlMessageGetter<object | undefined>>(message: T): React.ReactElement;
-    format<T extends TypedIntlMessageGetter<object | undefined>>(message: T, values: Omit<FormatValuesFor<T>, DefaultValues>): React.ReactElement;
+    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

@@ -57,7 +57,7 @@ var IntlManagerReact = /** @class */ (function (_super) {
             // 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 by a
+            // 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); });

package/dist/types.d.ts

@@ -19,6 +19,28 @@ export declare function defineMessages(messages: object): object;
  */
 export type RichTextElementMap = Record<string, (chunks: any[]) => any>;
 
+/**
+ * Placeholder type representing that this property is a Hook to be rendered
+ * while formatting.
+ */
+export type HookFunction = { __brand: 'hook-function' };
+/**
+ * Placeholder type representing that this property is a Link to be rendered
+ * while formatting.
+ */
+export type LinkFunction = { __brand: 'link-function' };
+/**
+ * Placeholder type representing that this property is a Handler function,
+ * which will be attached to some event when the message is formatted.
+ */
+export type HandlerFunction = { __brand: 'handler-function' };
+
+export type IntlNumber = string | number | null | undefined;
+export type IntlPlural = string | number | null | undefined;
+export type IntlAny = any;
+export type IntlDate = string | number | Date | null | undefined;
+export type IntlTime = string | number | Date | null | undefined;
+
 /**
  * Messages with no rich formatting and no value interpolations are just plain
  * strings, and are able to skip multiple formatting steps to work more
@@ -32,12 +54,16 @@ type PlainIntlMessage = string;
  * the message should be typed as a `PlainIntlMessage`.
  */
 type TypedIntlMessage<FormatValues extends object> = InternalIntlMessage & {
-  values: FormatValues;
+  __values: FormatValues;
 };
 
 type AnyIntlMessage<FormatValues extends object | undefined = undefined> =
   FormatValues extends undefined ? PlainIntlMessage : TypedIntlMessage<FormatValues>;
 
+export interface IntlMessageGetter extends IntlMessageGetterAdditions {
+  (locale: string): InternalIntlMessage | PlainIntlMessage;
+}
+
 /**
  * Getter function that retrieves a message that best matches the requested
  * locale. `FormatValues` represents either an object containing all of the
@@ -47,7 +73,50 @@ type AnyIntlMessage<FormatValues extends object | undefined = undefined> =
  */
 export interface TypedIntlMessageGetter<FormatValues extends object | undefined>
   extends IntlMessageGetterAdditions {
-  (locale: string): AnyIntlMessage<FormatValues>;
+  // TODO: This is lossy and unfortunate that typing can't be propagated
+  // to the returned message type, but doing so causes problems with
+  // contravariance of the type. When returning a message getter from a
+  // function with a generic message getter return type, TypeScript will
+  // try to assert that every returned type is strictly compatible with the
+  // declared return type. In that case, if a message is missing any of the
+  // properties declared in the type, it will error. But in the other direction
+  // when passing a message getter as a parameter _into_ a function, TypeScript
+  // will do the opposite and error if the getter has any _extra_ properties
+  // 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;
+
+  /**
+   * A phantom type (not part of the actual typing of the object) that ensures
+   * TypeScript won't use subtyping to widen the types of multiple messages
+   * unless they are _identical_. For an example of the problem:
+   * ```typescript
+   * declare const message1: {a: string};
+   * declare const message2: {a: string, b: boolean};
+   *
+   * const foo = condition ? message1 : message2;
+   * // ^ This becomes just `{a: string}`, because it's the common base type.
+   * ```
+   *
+   * This is fine for representing the object itself, but on messages those
+   * types represent required values at runtime, and so the greatest outer
+   * type is the only valid answer, rather than the greatest subtype.
+   *
+   * This phantom property ensures that TypeScript will never consider two
+   * messages subtypes of each other unless they contain identical properties,
+   * even the values of those properties, despite the fact that this only
+   * considers names being passed in (not sure how, but it does). The result
+   * is then always a union type of the possible types, which further
+   * downstream will ensure that all format values are always checked for all
+   * possible cases of the message.
+   */
+  __phantom: object extends FormatValues
+    ? any
+    : FormatValues extends undefined
+      ? any
+      : keyof FormatValues;
 }
 
 /**
@@ -122,16 +191,109 @@ type FormatValuesFor<T> =
   // be supplied, represented by the `never`. This prevents accidentally
   // passing an object, even an empty one, for those strings, and allows the
   // formatter to optimize a little more on each call.
-  [T] extends [TypedIntlMessageGetter<undefined>]
+  [T] extends [undefined]
     ? never
     : // The `never` condition needs to be repeated here, but this time _without_
       // the `[]` syntax, so that only the union elements with actual values are
       // included in the union. Without this, the `infer U` on the latter side
       // fails to resolve and the type just becomes `never`.
-      UnionToIntersection<
-        T extends TypedIntlMessageGetter<undefined>
-          ? never
-          : T extends TypedIntlMessageGetter<infer U>
-            ? U
-            : never
+      UnionToIntersection<T extends undefined ? never : T>;
+
+/**
+ * A template type for replaceable placeholder types to be defined by formatter
+ * implementations. Messages are typed using placeholder types like
+ * `HookFunction` and `HandlerFunction`, which are empty branded types
+ * indicating the _intent_ of a property, which the formatter is then able to
+ * replace with a more appropriate type. For example, a React formatter might
+ * replace a `HookFunction` with `(content: ReactNode) => ReactNode` to allow
+ * 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 {
+  link: any;
+  hook: any;
+  handler: any;
+}
+
+type ReplaceKeepingNullability<T, P> = P | Exclude<T, NonNullable<T>>;
+
+/**
+ * Type implementation for applying a `FunctionTypeMap` to a given argument
+ * type `T`. For each property of `T`, if its value is one of the placeholder
+ * types, like `HookFunction`, it will be replaced by the corresponding
+ * template value from `FunctionTypes`.
+ */
+type MapFunctionTypes<T, FunctionTypes extends FunctionTypeMap> = {
+  [K in keyof T]: ReplaceKeepingNullability<
+    T[K],
+    NonNullable<T[K]> extends LinkFunction
+      ? FunctionTypes['link']
+      : NonNullable<T[K]> extends HookFunction
+        ? FunctionTypes['hook']
+        : NonNullable<T[K]> extends HandlerFunction
+          ? FunctionTypes['handler']
+          : T[K]
+  >;
+};
+
+// Detect if T is explicitly `any`, in which case we don't want to do
+// any replacements, since each type should be `any`.
+// https://stackoverflow.com/a/61625831
+type CheckStrictAny<Check, Yes, No> = (Check extends never ? true : false) extends false ? No : Yes;
+
+/**
+ * Given a `TypedIntlMessageGetter` type, return the format values type
+ * argument from it. For example:
+ *
+ * ```typescript
+ * type SomeMessage = TypedIntlMessageGetter<{name: string}>
+ * type Result = IntlMessageGetterInnerType<SomeMessage>
+ * // Result is `{name: string}`
+ * ```
+ */
+type IntlMessageGetterInnerType<T extends IntlMessageGetter> =
+  T extends TypedIntlMessageGetter<infer U> ? U : never;
+
+/**
+ * Create the format values argument type for a format function using the
+ * configured `DefaultElements` for a formatter and injecting the placeholder
+ * 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<
+  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
+        // anything is allowed. This is only typical when consumers manually create a
+        // `TypedIntlMessageGetter` type as needed to pass values around, but loses
+        // any real type safety for the formatted values.
+        // Without this, though, `MapFunctionTypes` would always match the first
+        // 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
+        >
       >;
+
+export interface IntlOptionalRichTextKeys {
+  $_: any;
+  $b: any;
+  $i: any;
+  $p: any;
+  $link: any;
+  $code: any;
+}
+
+export type IntlFormatFunctionValuesArg<T extends IntlMessageGetter> = RequiredFormatValues<
+  T,
+  IntlOptionalRichTextKeys,
+  FunctionTypeMap
+>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discord/intl",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.1",
   "license": "MIT",
   "description": "Client runtime for managing messages and translations in a React project.",
   "main": "./dist/index.js",

package/src/index.ts

@@ -1,4 +1,36 @@
+import { IntlManager } from './intl-manager';
+import { IntlManagerReact } from './react';
+
 export { IntlManager, createLoader, DEFAULT_LOCALE } from './intl-manager';
 export { IntlManagerReact } from './react';
 
 export type * from './types.d.ts';
+
+/**
+ * A type representing any message that has been formatted using one of the
+ * default formatting methods in the `@discord/intl` system. Use this type
+ * when you don't care about whether a message is static or contains rich text
+ * or has dynamically-formatted values, when you need to handle both in tandem,
+ * or when you need a generic return type for a function returning "any
+ * any-already formatted message".
+ *
+ * Generally, this is like `React.ReactNode`, accepting both strings and rich
+ * `ReactElement`s, but it is more specific to disallow nullish values and
+ * other special React elements like `ReactPortal`. Seeing this type, you can
+ * be confident that the value is intended to be the result of formatting an
+ * intl message, even if the actual value comes from elsewhere (like a
+ * user-generated string).
+ */
+export type ReactIntlMessage = string | ReturnType<IntlManagerReact<any>['format']>;
+
+/**
+ * The return value of `formatToParts` from `@discord/intl`, this type
+ * represents any AST structure for a message rendered using this system.
+ * The AST generally follows a Markdown-like structure, with text nodes
+ * interspersed within and around rich text formatting nodes.
+ *
+ * ASTs are created _after_ all placeholders have been filled by values
+ * 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']>;

package/src/intl-manager.ts

@@ -8,7 +8,23 @@ import {
 
 import { LocaleId, LocaleImportMap, MessageLoader } from './message-loader';
 
-import type { FormatValuesFor, RichTextElementMap, TypedIntlMessageGetter } from './types';
+import type {
+  FunctionTypeMap,
+  IntlMessageGetter,
+  RequiredFormatValues,
+  RichTextElementMap,
+  TypedIntlMessageGetter,
+} from './types';
+
+/**
+ * Types for formatting functions when calling `formatToParts`, ensuring the
+ * functions yield value AST nodes.
+ */
+type AstFunctionTypes = {
+  link: undefined | object | ((children: object) => Array<string | any>);
+  hook: undefined | object | ((children: object) => Array<string | any>);
+  handler: undefined | object | ((children: object) => Array<string | any>);
+};
 
 /**
  * Fallback locale used for all internationalization when an operation in the
@@ -18,7 +34,7 @@ export const DEFAULT_LOCALE: string = 'en-US';
 
 export class IntlManager<
   DefaultElements extends RichTextElementMap,
-  DefaultValues extends keyof DefaultElements,
+  FunctionTypes extends FunctionTypeMap,
 > {
   defaultLocale: string;
   currentLocale: string;
@@ -84,16 +100,14 @@ export class IntlManager<
    * use `format`, which will wrap the formatting in a React component that
    * subscribes to the current locale and state of loaded messages.
    */
-  formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(
-    message: T,
-  ): Array<string | any>;
-  formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(
+  formatToParts<T extends TypedIntlMessageGetter<undefined>>(message: T): Array<string | any>;
+  formatToParts<T extends IntlMessageGetter>(
     message: T,
-    values: Omit<FormatValuesFor<T>, DefaultValues>,
+    values: RequiredFormatValues<T, DefaultElements, AstFunctionTypes>,
   ): Array<string | any>;
-  formatToParts<T extends TypedIntlMessageGetter<object | undefined>>(
+  formatToParts<T extends IntlMessageGetter>(
     message: T,
-    values?: Omit<FormatValuesFor<T>, DefaultValues>,
+    values?: RequiredFormatValues<T, DefaultElements, AstFunctionTypes>,
   ): Array<string | any> {
     if (typeof message === 'string') return [message];
     const resolvedMessage = typeof message === 'function' ? message(this.currentLocale) : message;
@@ -147,15 +161,15 @@ export class IntlManager<
    * Format the given message with the provided values, removing any styling
    * and non-textual content from the message, returning a plain string.
    */
-  formatToPlainString<T extends TypedIntlMessageGetter<object | undefined>>(message: T): string;
-  formatToPlainString<T extends TypedIntlMessageGetter<object | undefined>>(
+  formatToPlainString<T extends TypedIntlMessageGetter<undefined>>(message: T): string;
+  formatToPlainString<T extends IntlMessageGetter>(
     message: T,
-    values: Omit<FormatValuesFor<T>, DefaultValues>,
+    values: RequiredFormatValues<T, DefaultElements, FunctionTypes>,
   ): string;
-  formatToPlainString<T extends TypedIntlMessageGetter<object | undefined>>(
+  formatToPlainString<T extends IntlMessageGetter>(
     message: T,
-    values?: Omit<FormatValuesFor<T>, DefaultValues>,
-  ) {
+    values?: RequiredFormatValues<T, DefaultElements, FunctionTypes>,
+  ): string {
     if (typeof message === 'string') return message;
     const resolvedMessage = message(this.currentLocale);
     if (typeof resolvedMessage === 'string') return resolvedMessage;
@@ -176,15 +190,15 @@ export class IntlManager<
    * can be sent through a separate Markdown renderer to get an equivalent
    * result to formatting this message directly.
    */
-  formatToMarkdownString<T extends TypedIntlMessageGetter<object | undefined>>(message: T): string;
-  formatToMarkdownString<T extends TypedIntlMessageGetter<object | undefined>>(
+  formatToMarkdownString<T extends TypedIntlMessageGetter<undefined>>(message: T): string;
+  formatToMarkdownString<T extends IntlMessageGetter>(
     message: T,
-    values: Omit<FormatValuesFor<T>, DefaultValues>,
+    values: RequiredFormatValues<T, DefaultElements, FunctionTypes>,
   ): string;
-  formatToMarkdownString<T extends TypedIntlMessageGetter<object | undefined>>(
+  formatToMarkdownString<T extends IntlMessageGetter>(
     message: T,
-    values?: Omit<FormatValuesFor<T>, DefaultValues>,
-  ) {
+    values?: RequiredFormatValues<T, DefaultElements, FunctionTypes>,
+  ): string {
     // TODO(faulty): Implement the markdown syntax conversion here.
     if (typeof message === 'string') return message;
     const resolvedMessage = message(this.currentLocale);

package/src/react.ts

@@ -2,26 +2,53 @@ import * as React from 'react';
 
 import { IntlManager } from './intl-manager';
 
-import type { FormatValuesFor, RichTextElementMap, TypedIntlMessageGetter } from './types';
+import type {
+  IntlMessageGetter,
+  RequiredFormatValues,
+  RichTextElementMap,
+  TypedIntlMessageGetter,
+} from './types';
 
-export class IntlManagerReact<
-  DefaultElements extends RichTextElementMap,
-  DefaultValues extends keyof DefaultElements,
-> extends IntlManager<DefaultElements, DefaultValues> {
+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 TypedIntlMessageGetter<object | undefined>>(props: {
+  IntlMessage = <T extends IntlMessageGetter>(props: {
     message: T;
-    values?: Omit<FormatValuesFor<T>, DefaultValues> | never;
+    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 by a
+    // 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));
@@ -29,13 +56,9 @@ export class IntlManagerReact<
     // a plain string.
     if (typeof message === 'string') return message;
 
-    const parts = this.formatToParts(message, values as Omit<FormatValuesFor<T>, DefaultValues>);
+    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 as Omit<FormatValuesFor<T>, DefaultValues>),
-    );
+    return React.createElement(React.Fragment, undefined, this.formatToParts(message, values));
   };
 
   /**
@@ -43,14 +66,14 @@ export class IntlManagerReact<
    * and respond to updates about the current locale and other relevant
    * information.
    */
-  format<T extends TypedIntlMessageGetter<object | undefined>>(message: T): React.ReactElement;
-  format<T extends TypedIntlMessageGetter<object | undefined>>(
+  format<T extends TypedIntlMessageGetter<undefined>>(message: T): React.ReactElement;
+  format<T extends IntlMessageGetter>(
     message: T,
-    values: Omit<FormatValuesFor<T>, DefaultValues>,
+    values: RequiredFormatValues<T, DefaultElements, ReactFunctionTypes>,
   ): React.ReactElement;
-  format<T extends TypedIntlMessageGetter<object | undefined>>(
+  format<T extends IntlMessageGetter>(
     message: T,
-    values?: Omit<FormatValuesFor<T>, DefaultValues>,
+    values?: RequiredFormatValues<T, DefaultElements, ReactFunctionTypes>,
   ): React.ReactElement {
     return React.createElement(this.IntlMessage<T>, { message, values });
   }

package/src/types.d.ts

@@ -19,6 +19,28 @@ export declare function defineMessages(messages: object): object;
  */
 export type RichTextElementMap = Record<string, (chunks: any[]) => any>;
 
+/**
+ * Placeholder type representing that this property is a Hook to be rendered
+ * while formatting.
+ */
+export type HookFunction = { __brand: 'hook-function' };
+/**
+ * Placeholder type representing that this property is a Link to be rendered
+ * while formatting.
+ */
+export type LinkFunction = { __brand: 'link-function' };
+/**
+ * Placeholder type representing that this property is a Handler function,
+ * which will be attached to some event when the message is formatted.
+ */
+export type HandlerFunction = { __brand: 'handler-function' };
+
+export type IntlNumber = string | number | null | undefined;
+export type IntlPlural = string | number | null | undefined;
+export type IntlAny = any;
+export type IntlDate = string | number | Date | null | undefined;
+export type IntlTime = string | number | Date | null | undefined;
+
 /**
  * Messages with no rich formatting and no value interpolations are just plain
  * strings, and are able to skip multiple formatting steps to work more
@@ -32,12 +54,16 @@ type PlainIntlMessage = string;
  * the message should be typed as a `PlainIntlMessage`.
  */
 type TypedIntlMessage<FormatValues extends object> = InternalIntlMessage & {
-  values: FormatValues;
+  __values: FormatValues;
 };
 
 type AnyIntlMessage<FormatValues extends object | undefined = undefined> =
   FormatValues extends undefined ? PlainIntlMessage : TypedIntlMessage<FormatValues>;
 
+export interface IntlMessageGetter extends IntlMessageGetterAdditions {
+  (locale: string): InternalIntlMessage | PlainIntlMessage;
+}
+
 /**
  * Getter function that retrieves a message that best matches the requested
  * locale. `FormatValues` represents either an object containing all of the
@@ -47,7 +73,50 @@ type AnyIntlMessage<FormatValues extends object | undefined = undefined> =
  */
 export interface TypedIntlMessageGetter<FormatValues extends object | undefined>
   extends IntlMessageGetterAdditions {
-  (locale: string): AnyIntlMessage<FormatValues>;
+  // TODO: This is lossy and unfortunate that typing can't be propagated
+  // to the returned message type, but doing so causes problems with
+  // contravariance of the type. When returning a message getter from a
+  // function with a generic message getter return type, TypeScript will
+  // try to assert that every returned type is strictly compatible with the
+  // declared return type. In that case, if a message is missing any of the
+  // properties declared in the type, it will error. But in the other direction
+  // when passing a message getter as a parameter _into_ a function, TypeScript
+  // will do the opposite and error if the getter has any _extra_ properties
+  // 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;
+
+  /**
+   * A phantom type (not part of the actual typing of the object) that ensures
+   * TypeScript won't use subtyping to widen the types of multiple messages
+   * unless they are _identical_. For an example of the problem:
+   * ```typescript
+   * declare const message1: {a: string};
+   * declare const message2: {a: string, b: boolean};
+   *
+   * const foo = condition ? message1 : message2;
+   * // ^ This becomes just `{a: string}`, because it's the common base type.
+   * ```
+   *
+   * This is fine for representing the object itself, but on messages those
+   * types represent required values at runtime, and so the greatest outer
+   * type is the only valid answer, rather than the greatest subtype.
+   *
+   * This phantom property ensures that TypeScript will never consider two
+   * messages subtypes of each other unless they contain identical properties,
+   * even the values of those properties, despite the fact that this only
+   * considers names being passed in (not sure how, but it does). The result
+   * is then always a union type of the possible types, which further
+   * downstream will ensure that all format values are always checked for all
+   * possible cases of the message.
+   */
+  __phantom: object extends FormatValues
+    ? any
+    : FormatValues extends undefined
+      ? any
+      : keyof FormatValues;
 }
 
 /**
@@ -122,16 +191,109 @@ type FormatValuesFor<T> =
   // be supplied, represented by the `never`. This prevents accidentally
   // passing an object, even an empty one, for those strings, and allows the
   // formatter to optimize a little more on each call.
-  [T] extends [TypedIntlMessageGetter<undefined>]
+  [T] extends [undefined]
     ? never
     : // The `never` condition needs to be repeated here, but this time _without_
       // the `[]` syntax, so that only the union elements with actual values are
       // included in the union. Without this, the `infer U` on the latter side
       // fails to resolve and the type just becomes `never`.
-      UnionToIntersection<
-        T extends TypedIntlMessageGetter<undefined>
-          ? never
-          : T extends TypedIntlMessageGetter<infer U>
-            ? U
-            : never
+      UnionToIntersection<T extends undefined ? never : T>;
+
+/**
+ * A template type for replaceable placeholder types to be defined by formatter
+ * implementations. Messages are typed using placeholder types like
+ * `HookFunction` and `HandlerFunction`, which are empty branded types
+ * indicating the _intent_ of a property, which the formatter is then able to
+ * replace with a more appropriate type. For example, a React formatter might
+ * replace a `HookFunction` with `(content: ReactNode) => ReactNode` to allow
+ * 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 {
+  link: any;
+  hook: any;
+  handler: any;
+}
+
+type ReplaceKeepingNullability<T, P> = P | Exclude<T, NonNullable<T>>;
+
+/**
+ * Type implementation for applying a `FunctionTypeMap` to a given argument
+ * type `T`. For each property of `T`, if its value is one of the placeholder
+ * types, like `HookFunction`, it will be replaced by the corresponding
+ * template value from `FunctionTypes`.
+ */
+type MapFunctionTypes<T, FunctionTypes extends FunctionTypeMap> = {
+  [K in keyof T]: ReplaceKeepingNullability<
+    T[K],
+    NonNullable<T[K]> extends LinkFunction
+      ? FunctionTypes['link']
+      : NonNullable<T[K]> extends HookFunction
+        ? FunctionTypes['hook']
+        : NonNullable<T[K]> extends HandlerFunction
+          ? FunctionTypes['handler']
+          : T[K]
+  >;
+};
+
+// Detect if T is explicitly `any`, in which case we don't want to do
+// any replacements, since each type should be `any`.
+// https://stackoverflow.com/a/61625831
+type CheckStrictAny<Check, Yes, No> = (Check extends never ? true : false) extends false ? No : Yes;
+
+/**
+ * Given a `TypedIntlMessageGetter` type, return the format values type
+ * argument from it. For example:
+ *
+ * ```typescript
+ * type SomeMessage = TypedIntlMessageGetter<{name: string}>
+ * type Result = IntlMessageGetterInnerType<SomeMessage>
+ * // Result is `{name: string}`
+ * ```
+ */
+type IntlMessageGetterInnerType<T extends IntlMessageGetter> =
+  T extends TypedIntlMessageGetter<infer U> ? U : never;
+
+/**
+ * Create the format values argument type for a format function using the
+ * configured `DefaultElements` for a formatter and injecting the placeholder
+ * 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<
+  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
+        // anything is allowed. This is only typical when consumers manually create a
+        // `TypedIntlMessageGetter` type as needed to pass values around, but loses
+        // any real type safety for the formatted values.
+        // Without this, though, `MapFunctionTypes` would always match the first
+        // 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
+        >
       >;
+
+export interface IntlOptionalRichTextKeys {
+  $_: any;
+  $b: any;
+  $i: any;
+  $p: any;
+  $link: any;
+  $code: any;
+}
+
+export type IntlFormatFunctionValuesArg<T extends IntlMessageGetter> = RequiredFormatValues<
+  T,
+  IntlOptionalRichTextKeys,
+  FunctionTypeMap
+>;