@messagevisor/vue 0.0.1 → 0.1.0

package/src/api.ts

@@ -0,0 +1,119 @@
+import type {
+  EvaluationOptions,
+  MessageFormatResult,
+  MessagePrimitiveValue,
+  MessageValues,
+  Messagevisor,
+  TranslateOptions,
+} from "@messagevisor/sdk";
+import type { MessageKey } from "@messagevisor/types";
+
+import type { MessagevisorVueContextValue, VueMessageChunk } from "./MessagevisorContext";
+import { createRichTextTools, type VueMessageValues, type VueRichMessageValues } from "./richText";
+
+const BOUND_METHODS = [
+  "formatNumber",
+  "formatNumberToParts",
+  "formatDate",
+  "formatDateToParts",
+  "formatTime",
+  "formatTimeToParts",
+  "formatDateTimeRange",
+  "formatRelativeTime",
+  "formatPlural",
+  "formatList",
+  "formatListToParts",
+  "formatDisplayName",
+  "setLocale",
+  "getLocale",
+  "getDirection",
+  "setContext",
+  "getContext",
+  "setCurrency",
+  "getCurrency",
+  "setTimeZone",
+  "getTimeZone",
+  "setDatafile",
+  "getRevision",
+] as const satisfies readonly (keyof Messagevisor)[];
+
+type VueTranslationMethod = {
+  (
+    messageKey: MessageKey,
+    values?: Record<string, MessagePrimitiveValue>,
+    options?: TranslateOptions,
+  ): string;
+  (
+    messageKey: MessageKey,
+    values: VueRichMessageValues,
+    options?: TranslateOptions,
+  ): MessageFormatResult<VueMessageChunk>;
+};
+
+type VueFormatMessageMethod = {
+  (
+    message: string,
+    values?: Record<string, MessagePrimitiveValue>,
+    options?: EvaluationOptions,
+  ): string;
+  (
+    message: string,
+    values: VueRichMessageValues,
+    options?: EvaluationOptions,
+  ): MessageFormatResult<VueMessageChunk>;
+};
+
+export type MessagevisorApi = {
+  t: VueTranslationMethod;
+  translate: VueTranslationMethod;
+  formatMessage: VueFormatMessageMethod;
+} & Pick<Messagevisor, (typeof BOUND_METHODS)[number]>;
+
+function bindMethod<K extends keyof Messagevisor>(instance: Messagevisor, key: K): Messagevisor[K] {
+  return (instance[key] as (...args: never[]) => unknown).bind(instance) as Messagevisor[K];
+}
+
+export function createMessagevisorApi(context: MessagevisorVueContextValue): MessagevisorApi {
+  const sdk = context.instance;
+  const richText = createRichTextTools(context);
+
+  const translate = ((messageKey, values, options) => {
+    const message = sdk.getRawTranslation(messageKey, options);
+    const translation = sdk.translate<VueMessageChunk>(
+      messageKey,
+      richText.mergeValues(values as VueMessageValues, message) as MessageValues<VueMessageChunk>,
+      options,
+    );
+
+    return richText.wrapResult(
+      richText.runModules(translation, {
+        source: "translation",
+        messageKey,
+      }),
+    );
+  }) as VueTranslationMethod;
+
+  const result = {
+    t: translate,
+    translate,
+    formatMessage: ((message, values, options) => {
+      const translation = sdk.formatMessage<VueMessageChunk>(
+        message,
+        richText.mergeValues(values as VueMessageValues, message) as MessageValues<VueMessageChunk>,
+        options,
+      );
+
+      return richText.wrapResult(
+        richText.runModules(translation, {
+          source: "formatMessage",
+        }),
+      );
+    }) as VueFormatMessageMethod,
+  } as MessagevisorApi;
+
+  for (const key of BOUND_METHODS) {
+    result[key] = bindMethod(sdk, key) as never;
+  }
+
+  return result;
+}

package/src/components.spec.ts

@@ -0,0 +1,134 @@
+import { mount } from "@vue/test-utils";
+import { defineComponent, h } from "vue";
+
+import { MessagevisorProvider } from "./MessagevisorProvider";
+import { FormatMessage, MessageTranslation } from "./components";
+import { createRichTestInstance } from "./testUtils";
+
+describe("Vue components", function () {
+  it("renders translations and raw formatted messages", function () {
+    const m = createRichTestInstance();
+    const wrapper = mount(MessagevisorProvider, {
+      props: { instance: m },
+      slots: {
+        default: () =>
+          h("div", [
+            h(MessageTranslation, {
+              class: "translation",
+              messageKey: "greeting",
+              tag: "span",
+              values: { name: "Ada" },
+            }),
+            h(FormatMessage, {
+              class: "format",
+              message: "Hi {name}",
+              tag: "span",
+              values: { name: "Grace" },
+            }),
+          ]),
+      },
+    });
+
+    expect(wrapper.find(".translation").text()).toEqual("Hello Ada");
+    expect(wrapper.find(".format").text()).toEqual("Hi Grace");
+  });
+
+  it("renders rich text with provider defaults", function () {
+    const m = createRichTestInstance();
+    const wrapper = mount(MessagevisorProvider, {
+      props: {
+        instance: m,
+        defaultRichTextElements: {
+          strong: (chunks) => h("strong", chunks),
+          link: (chunks) => h("a", { href: "/terms" }, chunks),
+        },
+      },
+      slots: {
+        default: () =>
+          h(MessageTranslation, {
+            messageKey: "richTerms",
+            values: { product: "Messagevisor" },
+          }),
+      },
+    });
+
+    expect(wrapper.find("a").attributes("href")).toEqual("/terms");
+    expect(wrapper.find("a").text()).toEqual("terms");
+    expect(wrapper.find("strong").text()).toEqual("Messagevisor");
+    expect(wrapper.text()).toContain("Read our");
+  });
+
+  it("lets local rich text slots override provider defaults", function () {
+    const m = createRichTestInstance();
+    const Host = defineComponent({
+      render() {
+        return h(
+          MessageTranslation,
+          {
+            messageKey: "richTerms",
+            values: { product: "Messagevisor" },
+          },
+          {
+            link: ({ chunks }: { chunks: any[] }) => h("button", { type: "button" }, chunks),
+          },
+        );
+      },
+    });
+
+    const wrapper = mount(MessagevisorProvider, {
+      props: {
+        instance: m,
+        defaultRichTextElements: {
+          strong: (chunks) => h("strong", chunks),
+          link: (chunks) => h("a", { href: "/terms" }, chunks),
+        },
+      },
+      slots: { default: () => h(Host) },
+    });
+
+    expect(wrapper.find("button").text()).toEqual("terms");
+    expect(wrapper.find("a").exists()).toEqual(false);
+    expect(wrapper.find("strong").text()).toEqual("Messagevisor");
+  });
+
+  it("runs provider modules for component output", function () {
+    const m = createRichTestInstance();
+    const wrapper = mount(MessagevisorProvider, {
+      props: {
+        instance: m,
+        modules: [
+          {
+            transform({ translation }) {
+              return typeof translation === "string" ? h("mark", translation) : undefined;
+            },
+          },
+        ],
+      },
+      slots: {
+        default: () =>
+          h(FormatMessage, {
+            message: "Hello {name}",
+            values: { name: "Ada" },
+          }),
+      },
+    });
+
+    expect(wrapper.find("mark").text()).toEqual("Hello Ada");
+  });
+
+  it("can render without a wrapper when no tag is provided", function () {
+    const m = createRichTestInstance();
+    const wrapper = mount(MessagevisorProvider, {
+      props: { instance: m },
+      slots: {
+        default: () =>
+          h(MessageTranslation, {
+            messageKey: "greeting",
+            values: { name: "Ada" },
+          }),
+      },
+    });
+
+    expect(wrapper.text()).toEqual("Hello Ada");
+  });
+});

package/src/components.ts

@@ -0,0 +1,111 @@
+import type { EvaluationOptions, MessageValues, TranslateOptions } from "@messagevisor/sdk";
+import type { MessageKey } from "@messagevisor/types";
+import { defineComponent, h, type PropType } from "vue";
+
+import type { VueMessageChunk } from "./MessagevisorContext";
+import { createRichTextTools, resolveRecord, type VueMessageValues } from "./richText";
+import { useMessagevisorContextValue } from "./useSdk";
+
+function getSlotValues(slots: Record<string, any>) {
+  return Object.fromEntries(
+    Object.keys(slots)
+      .filter((key) => key !== "default")
+      .map((key) => [key, (chunks: Array<string | VueMessageChunk>) => slots[key]?.({ chunks })]),
+  ) as VueMessageValues;
+}
+
+export const MessageTranslation = defineComponent({
+  name: "MessageTranslation",
+  inheritAttrs: false,
+  props: {
+    messageKey: {
+      type: String as PropType<MessageKey>,
+      required: true,
+    },
+    values: {
+      type: Object as PropType<VueMessageValues>,
+      default: undefined,
+    },
+    options: {
+      type: Object as PropType<TranslateOptions>,
+      default: undefined,
+    },
+    tag: {
+      type: [String, Object] as PropType<string | object | false>,
+      default: undefined,
+    },
+  },
+  setup(props, { attrs, slots }) {
+    const context = useMessagevisorContextValue();
+    const richText = createRichTextTools(context);
+
+    return () => {
+      const message = context.instance.getRawTranslation(props.messageKey, props.options);
+      const values = {
+        ...(resolveRecord(props.values) || {}),
+        ...getSlotValues(slots),
+      };
+      const translation = context.instance.translate<VueMessageChunk>(
+        props.messageKey,
+        richText.mergeValues(values, message) as MessageValues<VueMessageChunk>,
+        props.options,
+      );
+
+      const result = richText.wrapResult(
+        richText.runModules(translation, {
+          source: "translation",
+          messageKey: props.messageKey,
+        }),
+      );
+
+      return props.tag ? h(props.tag as string, attrs, result as any) : result;
+    };
+  },
+});
+
+export const FormatMessage = defineComponent({
+  name: "FormatMessage",
+  inheritAttrs: false,
+  props: {
+    message: {
+      type: String,
+      required: true,
+    },
+    values: {
+      type: Object as PropType<VueMessageValues>,
+      default: undefined,
+    },
+    options: {
+      type: Object as PropType<EvaluationOptions>,
+      default: undefined,
+    },
+    tag: {
+      type: [String, Object] as PropType<string | object | false>,
+      default: undefined,
+    },
+  },
+  setup(props, { attrs, slots }) {
+    const context = useMessagevisorContextValue();
+    const richText = createRichTextTools(context);
+
+    return () => {
+      const values = {
+        ...(resolveRecord(props.values) || {}),
+        ...getSlotValues(slots),
+      };
+      const translation = context.instance.formatMessage<VueMessageChunk>(
+        props.message,
+        richText.mergeValues(values, props.message) as MessageValues<VueMessageChunk>,
+        props.options,
+      );
+
+      const result = richText.wrapResult(
+        richText.runModules(translation, {
+          source: "formatMessage",
+        }),
+      );
+
+      return props.tag ? h(props.tag as string, attrs, result as any) : result;
+    };
+  },
+});

package/src/createMessagevisorProvider.ts

@@ -0,0 +1,43 @@
+import type { Messagevisor } from "@messagevisor/sdk";
+import type { App, Plugin } from "vue";
+
+import {
+  MessagevisorInjectionKey,
+  type MessagevisorProviderModule,
+  type VueRichTextElementHandler,
+} from "./MessagevisorContext";
+import { createMessagevisorApi, type MessagevisorApi } from "./api";
+
+export interface MessagevisorProviderOptions {
+  instance: Messagevisor;
+  defaultRichTextElements?: Record<string, VueRichTextElementHandler>;
+  wrapRichTextChunksInFragment?: boolean;
+  modules?: MessagevisorProviderModule[];
+}
+
+export function createMessagevisorProvider(options: MessagevisorProviderOptions): Plugin {
+  return {
+    install(app: App) {
+      const context = {
+        instance: options.instance,
+        defaultRichTextElements: options.defaultRichTextElements || {},
+        wrapRichTextChunksInFragment: options.wrapRichTextChunksInFragment ?? true,
+        modules: options.modules || [],
+      };
+      const api = createMessagevisorApi(context);
+
+      app.provide(MessagevisorInjectionKey, context);
+      app.config.globalProperties.$messagevisor = api;
+      app.config.globalProperties.$m = api;
+      app.config.globalProperties.$t = api.t;
+    },
+  };
+}
+
+declare module "vue" {
+  interface ComponentCustomProperties {
+    $messagevisor: MessagevisorApi;
+    $m: MessagevisorApi;
+    $t: MessagevisorApi["t"];
+  }
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+export {
+  MessagevisorInjectionKey,
+  type MessagevisorProviderModule,
+  type MessagevisorVueContextValue,
+  type VueMessageChunk,
+  type VueRichTextElementHandler,
+} from "./MessagevisorContext";
+export { MessagevisorProvider } from "./MessagevisorProvider";
+export { MessageTranslation, FormatMessage } from "./components";
+export {
+  createMessagevisorProvider,
+  type MessagevisorProviderOptions,
+} from "./createMessagevisorProvider";
+export { useMessagevisor } from "./useMessagevisor";
+export { useMessagevisorSnapshot } from "./useMessagevisorSnapshot";
+export { useSdk, useMessagevisorContextValue } from "./useSdk";
+export {
+  useCurrency,
+  useDirection,
+  useFormatDate,
+  useFormatDateTimeRange,
+  useFormatDateToParts,
+  useFormatDisplayName,
+  useFormatList,
+  useFormatListToParts,
+  useFormatMessage,
+  useFormatNumber,
+  useFormatNumberToParts,
+  useFormatPlural,
+  useFormatRelativeTime,
+  useFormatTime,
+  useFormatTimeToParts,
+  useLocale,
+  useLocaleInfo,
+  useMessagevisorContext,
+  useTimeZone,
+  useTranslation,
+  type LocaleInfo,
+} from "./useReactiveMessagevisor";
+export { type MessagevisorApi } from "./api";
+export { type VueMessageValues, type VueRichMessageValues } from "./richText";

package/src/richText.ts

@@ -0,0 +1,130 @@
+import type {
+  MessagePrimitiveValue,
+  MessageValue,
+  MessagevisorTranslationSource,
+} from "@messagevisor/sdk";
+import type { MessageKey } from "@messagevisor/types";
+import { Fragment, h, isRef } from "vue";
+
+import type {
+  MessagevisorVueContextValue,
+  VueMessageChunk,
+  VueRichTextElementHandler,
+} from "./MessagevisorContext";
+
+export type VueMessageValues = Record<string, MessageValue<VueMessageChunk>>;
+export type VueRichMessageValues = Record<
+  string,
+  MessagePrimitiveValue | VueRichTextElementHandler
+>;
+
+const RICH_TAG_NAME_PATTERN = /<([A-Za-z][A-Za-z0-9_-]*)\b[^>]*>/g;
+
+function getRichTagNames(message: string) {
+  const tags = new Set<string>();
+  let match: RegExpExecArray | null;
+
+  while ((match = RICH_TAG_NAME_PATTERN.exec(message))) {
+    tags.add(match[1]);
+  }
+
+  return tags;
+}
+
+function maybeResolveRecordEntry(value: unknown) {
+  if (isRef(value)) {
+    return value.value;
+  }
+
+  if (typeof value === "function" && value.length === 0) {
+    return (value as () => unknown)();
+  }
+
+  return value;
+}
+
+export function resolveRecord<TRecord extends Record<string, unknown>>(
+  value?: TRecord | (() => TRecord),
+) {
+  const record = typeof value === "function" ? value() : value;
+
+  if (!record) {
+    return record;
+  }
+
+  return Object.fromEntries(
+    Object.entries(record).map(([key, entry]) => [key, maybeResolveRecordEntry(entry)]),
+  ) as TRecord;
+}
+
+export function createRichTextTools(context: MessagevisorVueContextValue) {
+  function mergeValues(values?: VueMessageValues, message?: string) {
+    const defaults = context.defaultRichTextElements;
+    const defaultKeys = Object.keys(defaults);
+
+    if (!message || defaultKeys.length === 0) {
+      return values;
+    }
+
+    const tagNames = getRichTagNames(message);
+    const matchingDefaults = Object.fromEntries(
+      defaultKeys.filter((key) => tagNames.has(key)).map((key) => [key, defaults[key]]),
+    ) as VueMessageValues;
+
+    if (Object.keys(matchingDefaults).length === 0) {
+      return values;
+    }
+
+    return {
+      ...matchingDefaults,
+      ...(values || {}),
+    };
+  }
+
+  function wrapResult<T>(result: T) {
+    if (!context.wrapRichTextChunksInFragment || !Array.isArray(result)) {
+      return result;
+    }
+
+    return h(
+      Fragment,
+      null,
+      result.map((chunk, index) => h(Fragment, { key: index }, [chunk])),
+    );
+  }
+
+  function runModules<TTranslation>(
+    translation: TTranslation,
+    payload: {
+      source: MessagevisorTranslationSource;
+      messageKey?: MessageKey;
+    },
+  ) {
+    let currentTranslation = translation as VueMessageChunk;
+    const locale = context.instance.getLocale();
+
+    if (!locale) {
+      return translation;
+    }
+
+    for (const module of context.modules) {
+      const nextTranslation = module.transform?.({
+        translation: currentTranslation,
+        locale,
+        ...payload,
+      });
+
+      if (typeof nextTranslation !== "undefined") {
+        currentTranslation = nextTranslation;
+      }
+    }
+
+    return currentTranslation;
+  }
+
+  return {
+    mergeValues,
+    runModules,
+    wrapResult,
+  };
+}

package/src/testUtils.ts

@@ -0,0 +1,82 @@
+import { createMessagevisor } from "@messagevisor/sdk";
+import { createICUModule } from "@messagevisor/module-icu";
+import type { DatafileContent } from "@messagevisor/types";
+
+export const enDatafile: DatafileContent = {
+  schemaVersion: "1",
+  messagevisorVersion: "0.0.1",
+  revision: "1-en",
+  target: "web",
+  locale: "en-US",
+  direction: "ltr",
+  formats: {
+    number: {
+      money: { style: "currency", currency: "USD", currencyDisplay: "symbol" },
+    },
+    date: {
+      short: { year: "2-digit", month: "numeric", day: "numeric", timeZone: "UTC" },
+    },
+    time: {
+      short: { hour: "numeric", minute: "2-digit", timeZone: "UTC" },
+    },
+    dateTimeRange: {
+      short: { month: "short", day: "numeric", timeZone: "UTC" },
+    },
+    relative: {
+      short: { numeric: "auto", style: "short" },
+    },
+  },
+  segments: {
+    pro: {
+      conditions: [{ attribute: "plan", operator: "equals", value: "pro" }],
+    },
+  },
+  messages: {
+    greeting: {
+      overrides: [
+        {
+          key: "pro",
+          segments: "pro",
+          translation: "Welcome back, pro {name}",
+        },
+      ],
+    },
+    total: {},
+    richTerms: {},
+    raw: {},
+  },
+  translations: {
+    greeting: "Hello {name}",
+    total: "Total: {amount, number, money}",
+    richTerms: "Read our <link>terms</link> for <strong>{product}</strong>.",
+    raw: "Raw {name}",
+  },
+};
+
+export const nlDatafile: DatafileContent = {
+  ...enDatafile,
+  revision: "1-nl",
+  locale: "nl-NL",
+  translations: {
+    ...enDatafile.translations,
+    greeting: "Hallo {name}",
+  },
+};
+
+export function createTestInstance() {
+  return createMessagevisor({
+    datafile: enDatafile,
+    timeZone: "UTC",
+    logLevel: "fatal",
+    modules: [createICUModule()],
+  });
+}
+
+export function createRichTestInstance() {
+  return createMessagevisor({
+    datafile: enDatafile,
+    timeZone: "UTC",
+    logLevel: "fatal",
+    modules: [createICUModule({ ignoreTags: false })],
+  });
+}