@antelopejs/dms-frontend 0.8.0 → 0.9.0

package/templates/vue/sfc-global-types.mjs

@@ -0,0 +1,119 @@
+// Vue's SFC compiler turns `defineProps<Props>()` into runtime prop types, and
+// it reads a type from the component's own imports only. A type a module
+// auto-imports (its declared `app/types`, `app/composables`…, and Vue's own
+// `Ref`, `Component`…) is visible to TypeScript through auto-imports.d.ts but
+// not to the compiler, which drops it from the prop without a word:
+// `boolean | RowActionConfig` became `{ type: Boolean }` in a production build.
+//
+// The compiler does read ambient declarations from `script.globalTypeFiles`,
+// but not the `export type { … } from` re-exports auto-imports.d.ts is made
+// of. This writes those types as ambient aliases it can follow, from the same
+// directories and through the same scanner as the auto-imports, before Vite
+// compiles anything, and rewrites them when a dev server sees a module's
+// declared directories change.
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+// The very unimport the auto-import plugin scans with, so both read the
+// directories the same way. Imported by URL, not by path: on Windows,
+// `import()` reads `C:\...` as a URL whose scheme is `c:` and refuses it.
+const unimportUrl = pathToFileURL(
+  createRequire(
+    createRequire(import.meta.url).resolve("unplugin-auto-import/package.json"),
+  ).resolve("unimport"),
+);
+const { builtinPresets, resolvePreset, scanDirExports } = await import(
+  unimportUrl.href
+);
+
+const HEADER =
+  "// Generated by @antelopejs/dms-frontend from the auto-imported types, for\n" +
+  "// Vue's SFC compiler (script.globalTypeFiles). Not read by TypeScript.\n";
+
+const withoutExtension = (path) => path.replace(/\.[cm]?[jt]sx?$/, "");
+
+/**
+ * The ambient aliases of the auto-imported types: one per name, in the order
+ * the auto-import plugin reads them (Vue's preset, then the scanned
+ * directories), the last one winning, as unimport's own deduplication keeps
+ * the last of two imports of the same name. A module that exports its own
+ * `Component` thus shadows Vue's, for the compiler as for TypeScript.
+ *
+ * @param {(string | { glob: string, types?: boolean })[]} dirs the auto-import
+ *   directories, as handed to the auto-import plugin
+ * @param {string} cwd the workspace
+ */
+export async function sfcGlobalTypes(dirs, cwd) {
+  const vue = await resolvePreset(builtinPresets.vue);
+  const scanned = await scanDirExports(dirs, { cwd, types: true });
+  const aliases = new Map();
+  for (const entry of [...vue, ...scanned]) {
+    if (!entry.type) continue;
+    const name = entry.as ?? entry.name;
+    const source = JSON.stringify(withoutExtension(entry.from));
+    aliases.set(
+      name,
+      `declare type ${name} = import(${source}).${entry.name};`,
+    );
+  }
+  return `${HEADER}${[...aliases.values()].join("\n")}\n`;
+}
+
+function writeIfChanged(file, content) {
+  let current;
+  try {
+    current = readFileSync(file, "utf8");
+  } catch {
+    current = undefined;
+  }
+  if (current === content) return false;
+  // Through a temporary file: a build starting meanwhile reads the previous
+  // declarations or the new ones, never a half-written file the compiler
+  // would then keep in its cache.
+  const temporary = `${file}.${process.pid}.tmp`;
+  writeFileSync(temporary, content);
+  renameSync(temporary, file);
+  return true;
+}
+
+/** Writes the declarations once, before Vite's config is returned. */
+export async function writeSfcGlobalTypes(dirs, cwd, file) {
+  writeIfChanged(file, await sfcGlobalTypes(dirs, cwd));
+}
+
+/**
+ * Keeps the declarations in step on a dev server: a type file added, renamed
+ * or removed rewrites them, and the Vue plugin reloads the components whose
+ * props read the file.
+ */
+export function sfcGlobalTypesWatcher(dirs, cwd, file) {
+  return {
+    name: "dms-sfc-global-types",
+    apply: "serve",
+    configureServer(server) {
+      let pending;
+      const refresh = (path) => {
+        if (!/\.[cm]?[jt]sx?$/.test(path) || path === file) return;
+        clearTimeout(pending);
+        pending = setTimeout(() => {
+          // The file is under the workspace, which Vite watches: rewriting it
+          // is the change the Vue plugin reloads the dependent components on.
+          // A failed scan or write keeps the previous declarations: it must
+          // not end the dev server.
+          sfcGlobalTypes(dirs, cwd)
+            .then((content) => writeIfChanged(file, content))
+            .catch((error) =>
+              server.config.logger.warn(
+                `Could not update ${file}, the types Vue's SFC compiler ` +
+                  `reads: ${error instanceof Error ? error.message : error}`,
+              ),
+            );
+        }, 100);
+      };
+      for (const event of ["add", "change", "unlink"])
+        server.watcher.on(event, refresh);
+    },
+  };
+}

package/templates/vue/ssr-renderer.ts

@@ -63,6 +63,11 @@ export interface DmsSsrResult {
   modules: string[];
   error?: DmsErrorData;
   redirect?: string;
+  /**
+   * The locale of the catalog the page was rendered with: the server preloads
+   * that catalog's file, which the browser loads before it hydrates.
+   */
+  catalogLocale?: string;
 }
 
 export interface DmsSsrHead {
@@ -189,6 +194,7 @@ async function renderDmsPageWithRuntime(
     let icons = new Set<string>();
     let iconSymbols = new Map<string, string>();
     let payload: DmsPayload = { data: {}, errors: {}, state: {} };
+    let catalogLocale: (() => string | undefined) | undefined;
     const inertiaResult = await createInertiaApp({
       page,
       // Read as the HTML is complete: data a run settles afterwards was never
@@ -214,6 +220,7 @@ async function renderDmsPageWithRuntime(
           runtime,
           serverFetch,
         });
+        catalogLocale = configured.catalogLocale;
         return app;
       },
     });
@@ -256,6 +263,7 @@ async function renderDmsPageWithRuntime(
       },
       overlays: ssrContext.teleports?.["#dms-overlays"] ?? "",
       modules: [...(ssrContext.modules ?? [])],
+      catalogLocale: catalogLocale?.(),
     };
   } finally {
     // Only once the head and the async data are serialized: both still read

package/templates/vue/ui-kbd.mjs

@@ -0,0 +1,45 @@
+// Nuxt UI prints the `meta`, `ctrl` and `alt` of a key hint (`UKbd`, the
+// `kbds` of its menus) from a map every hint shares, blank until the first
+// hint mounts: a hint hydrating after that, in an async component, printed
+// "⌘" or "Ctrl" over the server's blank, a hydration mismatch on every
+// platform. Its `useKbd` is routed to the DMS runtime's `useDmsKbd`, which
+// keeps each hint on the server's value until it mounts and lets the
+// application give the platform to the server render
+// (`provideDmsKbdPlatform`). The build fails if Nuxt UI changes the form
+// rewritten here, rather than letting the mismatch come back unnoticed.
+
+/** Nuxt UI's key hint composable. */
+const USE_KBD = /\/@nuxt\/ui\/dist\/runtime\/composables\/useKbd\.js$/;
+/** Its export as Nuxt UI 4 writes it: one composable shared by every hint. */
+const SHARED_EXPORT =
+  /export const useKbd = \/\* @__PURE__ \*\/ createSharedComposable\(_useKbd\);/;
+const ROUTED_EXPORT =
+  'import { useDmsKbd } from "#dms/frontend-module";\n' +
+  "const useSharedKbd = /* @__PURE__ */ createSharedComposable(_useKbd);\n" +
+  "export const useKbd = () => useDmsKbd(useSharedKbd, kbdKeysMap);";
+
+/**
+ * The rewrite, as a Vite plugin.
+ *
+ * @param isNuxtUiFile `(id) => boolean`, whether a module is Nuxt UI's
+ */
+export function uiKbd(isNuxtUiFile) {
+  return {
+    name: "dms-ui-kbd",
+    enforce: "pre",
+    transform(code, id) {
+      const path = id.replaceAll("\\", "/").split("?")[0];
+      if (!isNuxtUiFile(id) || !USE_KBD.test(path)) return null;
+      if (
+        !SHARED_EXPORT.test(code) ||
+        !code.includes("export const kbdKeysMap")
+      )
+        this.error(
+          `${id} defines useKbd in a form the DMS does not rewrite: its key ` +
+            "hints would not hydrate cleanly. Update ui-kbd.mjs for this " +
+            "Nuxt UI release.",
+        );
+      return { code: code.replace(SHARED_EXPORT, ROUTED_EXPORT), map: null };
+    },
+  };
+}

package/templates/vue/vite.config.ts

@@ -10,16 +10,24 @@ import {
   type Plugin,
 } from "vite";
 import { clientCodeSplitting, onBuildLog } from "./client-chunking.mjs";
+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 { uiRequestState } from "./ui-request-state.mjs";
 import { autoImportDirectories } from "./frontend-build-loader.ts";
 import { frontendBuilds } from "./frontend-builds.generated.ts";
 import { orderHeadForFirstPaint } from "./head-order.mjs";
 import { iconScanGlobs } from "./icon-scan.mjs";
+import {
+  sfcGlobalTypesWatcher,
+  writeSfcGlobalTypes,
+} from "./sfc-global-types.mjs";
 
 interface FrontendModuleRegistryEntry {
   id: string;
+  name?: string;
+  packageName?: string;
   root: string;
   priority: number;
 }
@@ -69,6 +77,19 @@ const importDirectories = autoImportDirectories(
   frontendBuilds,
   (message) => logger.warn(message),
 );
+/**
+ * The auto-imported types, as declarations Vue's SFC compiler reads: without
+ * them a prop typed with one compiles to the wrong runtime type.
+ */
+const sfcGlobalTypesFile = resolve(
+  import.meta.dirname,
+  "sfc-global-types.generated.d.ts",
+);
+await writeSfcGlobalTypes(
+  importDirectories,
+  import.meta.dirname,
+  sfcGlobalTypesFile,
+);
 /**
  * Dependencies pre-bundled by name. A module's own dependencies need no entry:
  * the startup crawl below (`optimizerEntries`) finds them in its sources. A
@@ -153,6 +174,8 @@ export default defineConfig({
     // Fails a client build that imports a dms.server.ts or a file under a
     // module's server/ directory, however it is imported.
     rejectServerSourcesInClient(moduleRoots),
+    // What each module adds to the client entry, which `ajs dms build` reports.
+    recordEntryWeight(registry.modules),
     {
       name: "dms-ui-inertia-link",
       enforce: "pre",
@@ -160,9 +183,15 @@ export default defineConfig({
         return id === uiLinkImport ? uiInertiaLinkImport : null;
       },
     },
+    uiKbd(isNuxtUiFile),
     uiInertiaPage(isNuxtUiFile),
     uiRequestState(isNuxtUiFile),
-    vue(),
+    vue({ script: { globalTypeFiles: [sfcGlobalTypesFile] } }),
+    sfcGlobalTypesWatcher(
+      importDirectories,
+      import.meta.dirname,
+      sfcGlobalTypesFile,
+    ),
     ui({
       router: "inertia",
       icon: {
@@ -214,6 +243,7 @@ export default defineConfig({
                 "useDmsError",
                 "useDmsPagedData",
                 "useDmsPageLoading",
+                "isDmsHydrating",
                 "useDmsApp",
                 "useDmsRoute",
                 "useDmsRouter",
@@ -224,6 +254,7 @@ export default defineConfig({
                 "DmsClientOnly",
                 "DmsLink",
                 "useDmsUserSession",
+                "provideDmsKbdPlatform",
               ],
           },
         ],