@antelopejs/dms-frontend 0.9.2 → 0.9.3

package/README.md

@@ -9,7 +9,7 @@
 
 <a href="https://www.npmjs.com/package/@antelopejs/dms-frontend"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/dms-frontend?style=for-the-badge&labelColor=000000&color=000000"></a>
 <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/dms-frontend?style=for-the-badge&labelColor=000000&color=000000"></a>
-<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
+<a href="https://discord.gg/g4pFt6eXqu"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
 <a href="https://dms.antelopejs.com/docs/frontend"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
 
 **The frontend of the AntelopeJS DMS: the `ajs dms` CLI, the Vue renderer and the frontend-module SDK.**

package/dist/config.js

@@ -50,6 +50,7 @@ exports.TEMPLATE_FILES = [
     ["index.html", "index.html"],
     ["main.ts", "main.ts"],
     ["app-runtime.ts", "app-runtime.ts"],
+    ["message-subset.ts", "message-subset.ts"],
     ["network-error.ts", "network-error.ts"],
     ["ui-app-config.ts", "ui-app-config.ts"],
     ["layer-app-config.ts", "layer-app-config.ts"],
@@ -60,6 +61,7 @@ exports.TEMPLATE_FILES = [
     ["frontend-build-loader.ts", "frontend-build-loader.ts"],
     ["server-module.ts", "server-module.ts"],
     ["icon-hydration.ts", "icon-hydration.ts"],
+    ["icon-bundle.ts", "icon-bundle.ts"],
     ["globals.d.ts", "globals.d.ts"],
     ["compress-assets.mjs", "compress-assets.mjs"],
     ["head-order.mjs", "head-order.mjs"],
@@ -72,6 +74,7 @@ exports.TEMPLATE_FILES = [
     ["icon-api.mjs", "icon-api.mjs"],
     ["icon-scan.mjs", "icon-scan.mjs"],
     ["ui-kbd.mjs", "ui-kbd.mjs"],
+    ["ui-lazy-icons.mjs", "ui-lazy-icons.mjs"],
     ["email-renderer.ts", "email-renderer.ts"],
     ["email-runtime.ts", "email-runtime.ts"],
     ["email-locales.ts", "email-locales.ts"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",

package/templates/vue/app-runtime.ts

@@ -4,6 +4,7 @@ import { useToast } from "@nuxt/ui/composables/useToast";
 import { useAppConfig } from "@nuxt/ui/runtime/vue/composables/useAppConfig";
 import { en as uiEn, fr as uiFr } from "@nuxt/ui/locale";
 import ui from "@nuxt/ui/vue-plugin";
+import { router } from "@inertiajs/vue3";
 import { useHead } from "@unhead/vue";
 import type { VueHeadClient } from "@unhead/vue/types";
 import type { IconifyIcon } from "@iconify/vue";
@@ -64,7 +65,13 @@ import {
   supportedLocales,
   syncLocaleMessages,
 } from "./locales.generated";
-import { showNetworkErrors } from "./network-error";
+import {
+  type DmsMessageSubset,
+  SSR_MESSAGES_ID,
+  recordMessageReads,
+} from "./message-subset";
+import { NETWORK_ERROR_KEYS, showNetworkErrors } from "./network-error";
+import { loadIconBundle } from "./icon-bundle";
 import { createUiAppConfigMerger } from "./ui-app-config";
 
 export interface DmsInertiaSetupProps {
@@ -86,8 +93,16 @@ export interface DmsAppOptions {
 }
 
 export interface DmsConfiguredApp {
-  /** The locale of the catalog the app shows its messages from now. */
+  /**
+   * The locale of the catalog the app shows its messages from now, none when
+   * the page is served the messages it read alone.
+   */
   catalogLocale: () => string | undefined;
+  /**
+   * On the server, for a page of a visitor who is not signed in: the messages
+   * the render read, which the page carries instead of the whole catalog.
+   */
+  messageSubset: () => DmsMessageSubset | undefined;
   mounted: () => Promise<void>;
   runtime: ReturnType<typeof createDmsFrontendRuntime>;
 }
@@ -238,8 +253,18 @@ const DmsPersistentInertiaPage = Object.assign(DmsInertiaPage, {
   layout: DmsPersistentLayout,
 });
 
-export function resolveDmsInertiaPage(): Component {
-  return DmsPersistentInertiaPage;
+/**
+ * What a visit waits for before it shows its page, set when the first one
+ * starts from a page that began without what the pages after it read: a
+ * subset of the catalog, the icon bundle. Inertia also resolves the first page
+ * once the app is set up, which must not wait for it.
+ */
+let completeInitialAssets: (() => Promise<void>) | undefined;
+
+export function resolveDmsInertiaPage(): Component | Promise<Component> {
+  return completeInitialAssets
+    ? completeInitialAssets().then(() => DmsPersistentInertiaPage)
+    : DmsPersistentInertiaPage;
 }
 
 function renderDmsPage(
@@ -310,13 +335,66 @@ export async function configureDmsApp(
     userLocale(options.initialPageProps.user) ??
     readDmsLocaleCookie(runtime, supportedLocales) ??
     DEFAULT_LOCALE;
-  const messages = await loadLocaleMessages(locale);
+  const anonymous = !options.initialPageProps.user;
+  const subset = anonymous
+    ? readServerRendered<DmsMessageSubset | undefined>(
+        SSR_MESSAGES_ID,
+        undefined,
+      )
+    : undefined;
+  const started = subset?.locale === locale ? subset : undefined;
+  const messages = started?.messages ?? (await loadLocaleMessages(locale));
+  const recorder =
+    anonymous && typeof window === "undefined"
+      ? recordMessageReads(messages)
+      : undefined;
+  let loading: Promise<void> | undefined;
   const i18n = createI18n({
     legacy: false,
     locale,
     fallbackLocale: DEFAULT_LOCALE,
-    messages: { ...localeMessages, [locale]: messages },
+    messages: started
+      ? { [locale]: messages }
+      : { ...localeMessages, [locale]: recorder?.messages ?? messages },
+    ...(started && {
+      missing: (_locale: string, key: string) => {
+        if (i18n.global.locale.value !== locale) return key;
+        void loadCompleteCatalog();
+        return "";
+      },
+    }),
   });
+  function loadCompleteCatalog(): Promise<void> {
+    if (i18n.global.locale.value !== locale) return Promise.resolve();
+    loading ??= loadLocaleMessages(locale).then(
+      (complete) => {
+        i18n.global.setLocaleMessage(locale, complete);
+        i18n.global.setMissingHandler(null);
+      },
+      () => {
+        loading = undefined;
+      },
+    );
+    return loading;
+  }
+  if (anonymous && typeof window !== "undefined") {
+    const complete = async (): Promise<void> => {
+      await Promise.all([
+        started ? loadCompleteCatalog() : undefined,
+        loadIconBundle(),
+      ]);
+    };
+    router.on("before", () => {
+      completeInitialAssets = complete;
+      void complete();
+    });
+    for (const type of ["pointerdown", "keydown", "focusin", "touchstart"])
+      addEventListener(type, () => void loadIconBundle(), {
+        once: true,
+        capture: true,
+      });
+  }
+  if (recorder) for (const key of NETWORK_ERROR_KEYS) i18n.global.te(key);
   // A translation changed in a layer during development reaches the page
   // without a reload. A server render imports the new catalogs instead.
   if (typeof window !== "undefined") syncLocaleMessages(i18n.global);
@@ -339,6 +417,7 @@ export async function configureDmsApp(
   // rendered: the page, its layout, and the components the render reached.
   // Hydration then adopts the server-rendered markup instead of discarding it.
   await Promise.all([
+    anonymous ? undefined : loadIconBundle(),
     preloadDmsPage(options.initialPageProps),
     resolveDmsAsyncComponents(
       readServerRendered<string[]>(SSR_ASYNC_COMPONENTS_ID, []),
@@ -352,7 +431,9 @@ export async function configureDmsApp(
     supportedLocales,
   );
   return {
-    catalogLocale: () => catalogLocale(i18n.global.locale.value),
+    catalogLocale: () =>
+      recorder ? undefined : catalogLocale(i18n.global.locale.value),
+    messageSubset: () => recorder && { locale, messages: recorder.subset() },
     mounted,
     runtime,
   };

package/templates/vue/globals.d.ts

@@ -1 +1,6 @@
 declare const defineDmsAppConfig: typeof import("./frontend-module").defineDmsAppConfig;
+declare module "virtual:nuxt-ui-icons" {
+  export function init(
+    add: (name: string, data: import("@iconify/vue").IconifyIcon) => boolean,
+  ): void;
+}

package/templates/vue/icon-bundle.ts

@@ -0,0 +1,31 @@
+import { addIcon, type IconifyIcon } from "@iconify/vue";
+
+function register(name: string, data: IconifyIcon): boolean {
+  const colon = name.indexOf(":");
+  if (colon !== -1 && name.slice(0, colon).includes("-")) {
+    addIcon(name.replace(":", "-"), data);
+  }
+  return addIcon(name, data);
+}
+
+let loading: Promise<void> | undefined;
+
+/**
+ * Loads the icons Nuxt UI bundles for the client, once: every icon the
+ * application's sources name. A server render has them from the start (Nuxt
+ * UI's own plugin, left in place by `ui-lazy-icons.mjs`), so there is nothing
+ * to load.
+ *
+ * A failed load is forgotten and resolves: an icon the bundle would have
+ * held is then fetched from the icon API, as one outside the bundle always is.
+ */
+export function loadIconBundle(): Promise<void> {
+  if (import.meta.env.SSR) return Promise.resolve();
+  loading ??= import("virtual:nuxt-ui-icons").then(
+    ({ init }) => init(register),
+    () => {
+      loading = undefined;
+    },
+  );
+  return loading;
+}

package/templates/vue/message-subset.ts

@@ -0,0 +1,65 @@
+/** The `<script>` the server render leaves in the document for {@link DmsMessageSubset}. */
+export const SSR_MESSAGES_ID = "dms-ssr-messages";
+
+type Messages = Record<string, unknown>;
+
+/**
+ * The messages a server render read from a locale's catalog, as a catalog of
+ * their own, with the locale they belong to.
+ */
+export interface DmsMessageSubset {
+  locale: string;
+  messages: Messages;
+}
+
+export interface MessageReadRecorder {
+  /** The catalog to give the render: every read through it is recorded. */
+  messages: Messages;
+  /** What the render read so far. */
+  subset: () => Messages;
+}
+
+function isTraversable(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+function isMessages(value: unknown): value is Messages {
+  return isTraversable(value);
+}
+
+type Slot = () => Messages;
+
+/**
+ * Wraps a catalog so that the messages read through it are collected, with
+ * the path they sit at, into a catalog of their own.
+ *
+ * A message is recorded when a string is read from the catalog, whether by a
+ * lookup (`t`), an existence check (`te`) or a walk over a subtree (`tm`).
+ */
+export function recordMessageReads(messages: Messages): MessageReadRecorder {
+  const used: Messages = {};
+  const place = (source: object, parent: Slot, key: string): Slot => {
+    return () => {
+      const holder = parent();
+      const existing = holder[key];
+      if (isMessages(existing)) return existing;
+      const container: Messages = Array.isArray(source) ? [] : {};
+      holder[key] = container;
+      return container;
+    };
+  };
+  const wrap = <T extends object>(source: T, slot: Slot): T =>
+    new Proxy(source, {
+      get(target, key, receiver) {
+        const value: unknown = Reflect.get(target, key, receiver);
+        if (typeof key !== "string" || key === "__proto__") return value;
+        if (typeof value === "string") {
+          slot()[key] = value;
+          return value;
+        }
+        if (isTraversable(value)) return wrap(value, place(value, slot, key));
+        return value;
+      },
+    });
+  return { messages: wrap(messages, () => used), subset: () => used };
+}

package/templates/vue/network-error.ts

@@ -15,6 +15,10 @@ export interface DmsNetworkErrorTranslator {
 
 const NETWORK_ERROR_TOAST_ID = "dms-network-error";
 const NETWORK_ERROR_KEY = "error.network";
+/** The messages a module overrides the built-in texts with. */
+export const NETWORK_ERROR_KEYS = ["title", "description"].map(
+  (name) => `${NETWORK_ERROR_KEY}.${name}`,
+);
 const DEFAULT_LOCALE = "en";
 // Shipped with the renderer, since no module is guaranteed to translate the
 // case; a module overrides them with `error.network.title` and

package/templates/vue/ssr-renderer.ts

@@ -30,6 +30,7 @@ import {
   trackDmsServerScopes,
   withPublicOptions,
 } from "./frontend-module";
+import { type DmsMessageSubset, SSR_MESSAGES_ID } from "./message-subset";
 import { parsePublicOptions } from "./public-options";
 import { frontendModules } from "./frontend-modules.generated";
 import {
@@ -129,6 +130,12 @@ function asyncComponentsScript(names: Set<string>): string {
   return `<script id="${SSR_ASYNC_COMPONENTS_ID}" type="application/json">${value}</script>`;
 }
 
+function messagesScript(subset: DmsMessageSubset | undefined): string {
+  if (!subset) return "";
+  const value = JSON.stringify(subset).replaceAll("<", "\\u003c");
+  return `<script id="${SSR_MESSAGES_ID}" type="application/json">${value}</script>`;
+}
+
 function iconsScript(names: Set<string>): string {
   const value = JSON.stringify(serializeDmsIcons(names)).replaceAll(
     "<",
@@ -195,6 +202,7 @@ async function renderDmsPageWithRuntime(
     let iconSymbols = new Map<string, string>();
     let payload: DmsPayload = { data: {}, errors: {}, state: {} };
     let catalogLocale: (() => string | undefined) | undefined;
+    let messageSubset: (() => DmsMessageSubset | undefined) | undefined;
     const inertiaResult = await createInertiaApp({
       page,
       // Read as the HTML is complete: data a run settles afterwards was never
@@ -221,6 +229,7 @@ async function renderDmsPageWithRuntime(
           serverFetch,
         });
         catalogLocale = configured.catalogLocale;
+        messageSubset = configured.messageSubset;
         return app;
       },
     });
@@ -255,7 +264,7 @@ async function renderDmsPageWithRuntime(
     const renderedHead = await renderSSRHead(head);
     return {
       error: page.props.error,
-      body: `${inertiaResult.body}${dmsIconSprite(iconSymbols)}${payloadScript(payload)}${asyncComponentsScript(asyncComponents)}${iconsScript(icons)}`,
+      body: `${inertiaResult.body}${dmsIconSprite(iconSymbols)}${payloadScript(payload)}${asyncComponentsScript(asyncComponents)}${iconsScript(icons)}${messagesScript(messageSubset?.())}`,
       head: {
         bodyAttrs: renderedHead.bodyAttrs,
         headTags: `${inertiaResult.head.join("")}${renderedHead.headTags}`,

package/templates/vue/ui-lazy-icons.mjs

@@ -0,0 +1,44 @@
+/**
+ * @typedef {object} IconsPluginContext
+ * @property {{ config: { consumer: string } }} environment
+ * @property {(message: string) => never} error
+ */
+
+/** Nuxt UI's plugin that installs the client icon bundle. */
+const ICONS_PLUGIN = /\/@nuxt\/ui\/dist\/runtime\/vue\/plugins\/icons\.js$/;
+
+/**
+ * The client build of Nuxt UI's icons plugin, as a Vite plugin.
+ *
+ * The plugin imports the bundle of every icon the sources name, which put it
+ * in the entry of every page, the sign-in page's included, for icons it draws
+ * from the server render's own copy. The client gets an empty plugin, and
+ * `loadIconBundle` (`icon-bundle.ts`) loads the bundle when the page needs it. The server render keeps the plugin as it is. The
+ * build fails if Nuxt UI changes the form rewritten here, rather than
+ * letting the bundle return to the entry unnoticed.
+ *
+ * @param {(id: string) => boolean} isNuxtUiFile whether a module is Nuxt UI's
+ * @returns {{ name: string, enforce: "pre", transform: (this: IconsPluginContext, code: string, id: string) => { code: string, map: null } | null }}
+ */
+export function uiLazyIcons(isNuxtUiFile) {
+  return {
+    name: "dms-ui-lazy-icons",
+    enforce: "pre",
+    transform(code, id) {
+      const path = id.replaceAll("\\", "/").split("?")[0];
+      if (
+        this.environment.config.consumer !== "client" ||
+        !isNuxtUiFile(id) ||
+        !ICONS_PLUGIN.test(path)
+      )
+        return null;
+      if (!code.includes("virtual:nuxt-ui-icons"))
+        this.error(
+          `${id} no longer installs the client icon bundle the way the DMS ` +
+            "defers it: the bundle would return to the entry. Update " +
+            "ui-lazy-icons.mjs for this Nuxt UI release.",
+        );
+      return { code: "export default { install() {} };", map: null };
+    },
+  };
+}

package/templates/vue/vite.config.ts

@@ -14,6 +14,7 @@ import { recordEntryWeight } from "./entry-weight.mjs";
 import { rejectServerSourcesInClient } from "./client-server-guard.mjs";
 import { uiInertiaPage } from "./ui-inertia-page.mjs";
 import { uiKbd } from "./ui-kbd.mjs";
+import { uiLazyIcons } from "./ui-lazy-icons.mjs";
 import { uiRequestState } from "./ui-request-state.mjs";
 import { autoImportDirectories, vitePlugins } from "./frontend-build-loader.ts";
 import { frontendBuilds } from "./frontend-builds.generated.ts";
@@ -184,6 +185,7 @@ export default defineConfig({
       },
     },
     uiKbd(isNuxtUiFile),
+    uiLazyIcons(isNuxtUiFile),
     uiInertiaPage(isNuxtUiFile),
     uiRequestState(isNuxtUiFile),
     vue({ script: { globalTypeFiles: [sfcGlobalTypesFile] } }),