@antelopejs/dms-frontend 0.5.6 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",
@@ -85,6 +85,7 @@
     "@vitejs/plugin-vue": "^6.0.1",
     "@vue/server-renderer": "^3.5.25",
     "defu": "^6.1.4",
+    "devalue": "^5.9.4",
     "knip": "^6.34.0",
     "ofetch": "^1.5.1",
     "oxfmt": "^0.66.0",

package/templates/vue/app-runtime.ts

@@ -7,6 +7,7 @@ import ui from "@nuxt/ui/vue-plugin";
 import { useHead } from "@unhead/vue";
 import type { VueHeadClient } from "@unhead/vue/types";
 import type { IconifyIcon } from "@iconify/vue";
+import { parse } from "devalue";
 import type { FetchOptions } from "ofetch";
 import {
   type App,
@@ -22,8 +23,10 @@ import {
 import { createI18n, useI18n } from "vue-i18n";
 import DmsDynamicPage from "./DmsDynamicPage.vue";
 import {
+  type DmsLayerAppConfig,
   type DmsLocaleLoader,
   type DmsPageProps,
+  type DmsPayload,
   type DmsUser,
   createDmsFrontendRuntime,
   dmsPageSuspenseProps,
@@ -32,18 +35,22 @@ import {
   getDmsLayoutProps,
   getDmsPage,
   hydrateDmsPageProps,
+  hydrateDmsSharedProps,
   installDmsPlugins,
+  keepSharedOverHistory,
   preloadDmsPage,
+  preloadPrefetchedDmsPages,
   provideDmsFrontendRuntime,
   readDmsLocaleCookie,
   resolveDmsAsyncComponents,
   resolveDmsComponent,
-  serializeDmsAsyncData,
+  restoreDmsPayload,
   trackDmsAsyncComponents,
+  updateDmsAppConfig,
   useDmsAppConfig,
   useDmsState,
-  useError,
-  useUserSession,
+  useDmsError,
+  useDmsUserSession,
 } from "./frontend-module";
 import {
   SSR_ICONS_ID,
@@ -87,7 +94,7 @@ export type DmsServerFetch = (
   options?: FetchOptions,
 ) => Promise<unknown>;
 
-const SSR_ASYNC_DATA_ID = "dms-ssr-async-data";
+export const DMS_PAYLOAD_ID = "dms-payload";
 export const SSR_ASYNC_COMPONENTS_ID = "dms-ssr-async-components";
 const DEFAULT_LOCALE = "en";
 
@@ -112,17 +119,38 @@ function userLocale(user: DmsUser | null | undefined): string | undefined {
   return supportedLocales.includes(locale) ? locale : undefined;
 }
 
-function readServerRendered<T>(id: string, empty: T): T {
+function readServerRendered<T>(
+  id: string,
+  empty: T,
+  parseText: (text: string) => unknown = JSON.parse,
+): T {
   if (typeof document === "undefined") return empty;
   const element = document.getElementById(id);
   if (!element?.textContent) return empty;
-  const value = JSON.parse(element.textContent) as T;
+  const value = parseText(element.textContent) as T;
   element.remove();
   return value;
 }
 
 drawLoadedIconsAtOnce();
 
+/** A browser runtime, started from what the server rendered, if it did. */
+function createBrowserRuntime(
+  serverFetch?: DmsServerFetch,
+): DmsConfiguredApp["runtime"] {
+  const runtime = createDmsFrontendRuntime(
+    serverFetch as typeof import("ofetch").ofetch,
+  );
+  // Nothing when the server did not render the page: no hydration then.
+  const payload = readServerRendered<DmsPayload | undefined>(
+    DMS_PAYLOAD_ID,
+    undefined,
+    parse,
+  );
+  if (payload) restoreDmsPayload(runtime, payload);
+  return runtime;
+}
+
 const DmsInertiaPage = defineComponent({
   name: "DmsInertiaPage",
   inheritAttrs: false,
@@ -152,7 +180,7 @@ const DmsPersistentLayout = defineComponent({
   setup(_, { attrs, slots }) {
     const props = computed(() => attrs as unknown as DmsPageProps);
     const i18n = useI18n();
-    const { user } = useUserSession();
+    const { user } = useDmsUserSession();
     let localeVersion = 0;
     useHead({
       htmlAttrs: { lang: computed(() => i18n.locale.value) },
@@ -162,6 +190,13 @@ const DmsPersistentLayout = defineComponent({
       () => hydrateDmsPageProps(props.value),
       { immediate: true, flush: "sync" },
     );
+    // Apart from the page: a reload of the site layout alone (`router.reload({
+    // only: ["shared"] })`) is not a navigation.
+    watch(
+      () => attrs.shared,
+      () => hydrateDmsSharedProps(props.value.shared),
+      { flush: "sync" },
+    );
     // The session, not the page props: a page restored from history or from
     // the prefetch cache carries the user as it was when it was fetched, and
     // would switch the interface back to a language the user has left. A
@@ -178,7 +213,7 @@ const DmsPersistentLayout = defineComponent({
       },
       { immediate: true, flush: "sync" },
     );
-    const currentError = useError();
+    const currentError = useDmsError();
     const overlays = useDmsState<string[]>("dms-app-overlays", () => []);
     return () => {
       const error = currentError.value ?? props.value.error;
@@ -206,7 +241,7 @@ export function resolveDmsInertiaPage(): Component {
 
 function renderDmsPage(
   props: DmsPageProps,
-  capturedError: DmsPageProps["error"] = useError().value,
+  capturedError: DmsPageProps["error"] = useDmsError().value,
 ) {
   const error = capturedError ?? props.error;
   const page = error
@@ -251,16 +286,21 @@ function mergeDmsAppConfig(): void {
   mergeUiAppConfig(useAppConfig(), useDmsAppConfig());
 }
 
+/**
+ * Development only: applies the layers' app configs, edited while the page is
+ * open, to the DMS app config and to Nuxt UI's, both in place, so the
+ * components reading them and Nuxt UI's colors follow without a reload.
+ */
+export function applyLayerAppConfigs(appConfigs: DmsLayerAppConfig[]): void {
+  updateDmsAppConfig(appConfigs);
+  mergeUiAppConfig(useAppConfig(), useDmsAppConfig(), { isChanged: true });
+}
+
 export async function configureDmsApp(
   options: DmsAppOptions,
 ): Promise<DmsConfiguredApp> {
   mergeDmsAppConfig();
-  const runtime =
-    options.runtime ??
-    createDmsFrontendRuntime(
-      options.serverFetch as typeof import("ofetch").ofetch,
-      readServerRendered<Record<string, unknown>>(SSR_ASYNC_DATA_ID, {}),
-    );
+  const runtime = options.runtime ?? createBrowserRuntime(options.serverFetch);
   // The signed-in user's language, else the one this browser picked, which is
   // how a visitor's choice on a public page survives a reload.
   const locale =
@@ -289,6 +329,8 @@ export async function configureDmsApp(
   if (typeof window !== "undefined") {
     const toast = options.app.runWithContext(() => useToast());
     showNetworkErrors(toast.add, i18n.global);
+    preloadPrefetchedDmsPages();
+    options.app.runWithContext(keepSharedOverHistory);
   }
   // Resolve, before the app mounts, every async component the server
   // rendered: the page, its layout, and the components the render reached.
@@ -309,4 +351,4 @@ export async function configureDmsApp(
   return { mounted, runtime };
 }
 
-export { serializeDmsAsyncData, trackDmsAsyncComponents };
+export { trackDmsAsyncComponents };

package/templates/vue/client-server-guard.mjs

@@ -0,0 +1,73 @@
+// Keeping server code out of the browser.
+//
+// A module's `dms.server.ts` and the files under its `server/` directories run
+// in the generated server only: they read private options, sign tokens, talk
+// to the backend with its secrets. A client file that imports one of them,
+// even statically and through an alias, would ship that code in the client
+// bundle. Rollup's manifest only lists entries and dynamic imports, so a check
+// on the built output misses a static import; the guard sits in the module
+// graph instead, where every resolved file passes.
+//
+// Kept beside vite.config.ts rather than inside it so the plugin can be
+// exercised on its own, the way head-order.mjs is.
+
+import { relative, sep } from "node:path";
+
+const SERVER_ENTRY = /(?:^|[\\/])dms\.server\.[cm]?[jt]sx?$/;
+
+function stripQuery(id) {
+  const query = id.indexOf("?");
+  return query === -1 ? id : id.slice(0, query);
+}
+
+function insideModuleServerDirectory(file, moduleRoots) {
+  return moduleRoots.some((root) => {
+    const path = relative(root, file);
+    if (!path || path.startsWith("..") || path.startsWith(sep)) return false;
+    const segments = path.split(/[\\/]/);
+    return segments.slice(0, -1).includes("server");
+  });
+}
+
+/**
+ * Whether `id`, a resolved module id, is server code: a module's server entry
+ * (`dms.server.*`) or a file under a `server/` directory of a module. Installed
+ * packages never are: `node_modules` has its own `server` directories.
+ */
+export function isServerSource(id, moduleRoots) {
+  if (id.startsWith("\0")) return false;
+  const file = stripQuery(id);
+  if (/[\\/]node_modules[\\/]/.test(file)) return false;
+  return (
+    SERVER_ENTRY.test(file) || insideModuleServerDirectory(file, moduleRoots)
+  );
+}
+
+/**
+ * Fail a client build, and a client request in development, that loads server
+ * code. Server-side rendering and the server modules build load it through
+ * SSR, which the guard leaves alone.
+ */
+export function rejectServerSourcesInClient(moduleRoots) {
+  let ssrBuild = false;
+  return {
+    name: "dms-reject-server-sources-in-client",
+    enforce: "pre",
+    configResolved(config) {
+      ssrBuild = Boolean(config.build.ssr);
+    },
+    load(id, options) {
+      if (ssrBuild || options?.ssr) return null;
+      if (!isServerSource(id, moduleRoots)) return null;
+      const importers = this.getModuleInfo?.(id)?.importers ?? [];
+      const from = importers.length
+        ? ` (imported by ${importers.join(", ")})`
+        : "";
+      this.error(
+        `Server code in the client bundle: ${stripQuery(id)}${from}. ` +
+          "A dms.server.ts and the files under a module's server/ directory " +
+          "run in the server only; import them from a dms.server.ts, never from client code.",
+      );
+    },
+  };
+}

package/templates/vue/email-renderer.ts

@@ -2,6 +2,7 @@ import { renderToString } from "@vue/server-renderer";
 import { defu } from "defu";
 import { type Component, createSSRApp, h } from "vue";
 import { createI18n } from "vue-i18n";
+import { appConfigs } from "./app-configs.generated";
 import moduleRegistry from "./generated-frontend-modules.json";
 import { loadEmailLocaleMessages } from "./email-locales";
 import { stripSsrMarkers } from "./email-markup";
@@ -28,6 +29,21 @@ const orderedRegistries = moduleRegistry.modules
   .map((module) => registries[`/frontend-modules/${module.id}/dms.email.ts`])
   .filter((registry): registry is EmailRegistry => Boolean(registry));
 
+/**
+ * Every app config an email reads, highest precedence first: module by module,
+ * by descending priority, what its `dms.email.ts` declares for emails, then
+ * its layers' `app/app.config.ts`. A higher-priority module's layers still
+ * override a lower one's email config, and a module's own email config, the
+ * more specific of its two, keeps the values it gave emails before the layers'
+ * configs applied to them.
+ */
+const emailAppConfigs = moduleRegistry.modules.flatMap((module) => [
+  registries[`/frontend-modules/${module.id}/dms.email.ts`]?.appConfig ?? {},
+  ...appConfigs
+    .filter((layer) => layer.module === module.id)
+    .map((layer) => layer.config),
+]);
+
 function templateEntries(): Array<[string, () => Promise<EmailModule>]> {
   return orderedRegistries.flatMap((registry) =>
     Object.entries(registry.serverEmailTemplates),
@@ -138,10 +154,7 @@ export async function renderEmail(
     }),
   );
   app.provide("dmsEmailLocale", locale);
-  app.provide(
-    "dmsEmailAppConfig",
-    defu({}, ...orderedRegistries.map((registry) => registry.appConfig ?? {})),
-  );
+  app.provide("dmsEmailAppConfig", defu({}, ...emailAppConfigs));
   const publicConfig = defu(
     {},
     ...moduleRegistry.modules.map((module) => module.options),

package/templates/vue/email-runtime.ts

@@ -16,7 +16,7 @@ export function useDmsRuntimeConfig(): EmailRuntimeConfig {
   });
 }
 
-export function defineAppConfig<T extends Record<string, unknown>>(
+export function defineDmsAppConfig<T extends Record<string, unknown>>(
   config: T,
 ): T {
   return config;