@antelopejs/dms-frontend 0.3.11 → 0.4.0

package/templates/vue/frontend-module.ts

@@ -31,6 +31,7 @@ import {
   type PropType,
   type Ref,
   reactive,
+  readonly,
   ref,
   watch,
 } from "vue";
@@ -50,6 +51,12 @@ export interface DmsPagePayload {
   layoutUrl?: string;
   layout?: DmsPageLayout;
   shared?: DmsSharedPagePayload;
+  /**
+   * The frontend module that owns the page's component tree, by the name the
+   * backend added it under (its manifest name). Components that module
+   * registered with `{ private: true }` resolve in this page's tree only.
+   */
+  module?: string;
   [key: string]: unknown;
 }
 export interface DmsSharedPagePayload {
@@ -82,6 +89,13 @@ export interface DmsUser extends Record<string, unknown> {}
 export interface DmsSession {
   accountId: string;
   activeTenantId?: string;
+  /**
+   * When the frontend server last wrote this session, in milliseconds since
+   * the epoch. A page restored from history or from the prefetch cache
+   * carries an older session than the one the app already holds, and does not
+   * replace it.
+   */
+  updatedAt?: number;
 }
 export interface DmsRuntimeConfig extends RuntimeConfig {
   public: PublicRuntimeConfig;
@@ -220,9 +234,22 @@ export interface DmsPluginRegistrationOptions {
   clientOnly?: boolean;
 }
 export type DmsComponentPreloader = () => Promise<unknown>;
+export interface DmsComponentRegistrationOptions {
+  /**
+   * Keeps the component out of the application's global components: it
+   * resolves by name only in the component trees of the backend pages the
+   * registering module owns (see `DmsPagePayload.module`), where it takes
+   * precedence over a public component of the same name. Defaults to `false`.
+   */
+  private?: boolean;
+}
 export interface DmsFrontendSdk {
   options: DmsModuleOptions;
-  registerComponent(name: string, component: Component): void;
+  registerComponent(
+    name: string,
+    component: Component,
+    options?: DmsComponentRegistrationOptions,
+  ): void;
   registerPage(
     name: string,
     component: Component,
@@ -264,6 +291,11 @@ export interface DmsFrontendModule {
   setup(sdk: DmsFrontendSdk): void | Promise<void>;
 }
 export interface DmsFrontendModuleRegistration {
+  /**
+   * The module's manifest name, which its backend pages carry as their
+   * `module`. Without it, the module's private components never resolve.
+   */
+  name?: string;
   module: DmsFrontendModule;
   options: DmsModuleOptions;
 }
@@ -283,6 +315,8 @@ export interface DmsRuntimeHooks {
 interface DmsComponentRegistration {
   name: string;
   component: Component;
+  /** The registering module, for a private component. */
+  module?: string;
 }
 
 interface DmsFrontendEntry {
@@ -305,6 +339,8 @@ interface DmsPluginRegistration {
  */
 interface DmsFrontendRegistry {
   components: Map<string, DmsComponentRegistration>;
+  /** Private components, by registering module, then by normalized name. */
+  privateComponents: Map<string, Map<string, DmsComponentRegistration>>;
   pages: Map<string, DmsFrontendEntry>;
   dynamicPages: Map<string, DmsFrontendEntry>;
   layouts: Map<string, DmsFrontendEntry>;
@@ -333,6 +369,8 @@ export interface DmsFrontendRuntime {
   pendingNavigation?: Promise<void>;
   hasNavigationListener: boolean;
   pageVersion: number;
+  /** Whether the page `<Suspense>` waits on the page being navigated to. */
+  pageLoading: Ref<boolean>;
   /**
    * Identifies the page on screen (its path, or the error page shown at that
    * path), whose meta `route.meta` holds.
@@ -351,6 +389,7 @@ export interface DmsFrontendRuntime {
 function createDmsFrontendRegistry(): DmsFrontendRegistry {
   return {
     components: new Map(),
+    privateComponents: new Map(),
     pages: new Map(),
     dynamicPages: new Map(),
     layouts: new Map(),
@@ -403,6 +442,7 @@ export function createDmsFrontendRuntime(
     }),
     hasNavigationListener: false,
     pageVersion: 0,
+    pageLoading: ref(false),
     scope: effectScope(true),
   };
 }
@@ -1187,23 +1227,82 @@ export function useUserSession<
   };
 }
 
+/**
+ * Whether the page loaded by the current navigation is still pending: its
+ * chunk, or an async `setup` it awaits, has not resolved yet. A layout reads
+ * it to show its own placeholder in place of the page. Always `false` on the
+ * server and during hydration, which render the page resolved.
+ */
+export function useDmsPageLoading(): Readonly<Ref<boolean>> {
+  return readonly(useDmsRuntime().pageLoading);
+}
+
+/**
+ * The props of the `<Suspense>` around the page that keep `useDmsPageLoading`
+ * in step with it. Cleared before the boundary unmounts, so a page left while
+ * pending never leaves the state set.
+ */
+export function dmsPageSuspenseProps(): Record<string, () => void> {
+  const loading = useDmsRuntime().pageLoading;
+  const settle = () => {
+    loading.value = false;
+  };
+  return {
+    onPending: () => {
+      loading.value = true;
+    },
+    onResolve: settle,
+    onVnodeBeforeUnmount: settle,
+  };
+}
+
 function registerDmsComponentEntry(
   entries: Map<string, DmsComponentRegistration>,
-  name: string,
-  component: Component,
+  registration: DmsComponentRegistration,
 ): void {
-  const key = normalizeDmsName(name);
-  if (!entries.has(key)) entries.set(key, { name, component });
+  const key = normalizeDmsName(registration.name);
+  if (!entries.has(key)) entries.set(key, registration);
 }
 /** Registers a component unless a higher-priority module already owns its name. */
 export function registerDmsComponent(name: string, component: Component): void {
-  registerDmsComponentEntry(registry.components, name, component);
+  registerDmsComponentEntry(registry.components, { name, component });
 }
-export function resolveDmsComponent(name: string): Component | undefined {
-  return registry.components.get(normalizeDmsName(name))?.component;
+/**
+ * Resolves a registered component by name. `owner` is the `module` of the
+ * backend page whose component tree is rendered: the private components that
+ * module registered resolve there, ahead of a public one of the same name.
+ * Without it, only public components resolve.
+ */
+export function resolveDmsComponent(
+  name: string,
+  owner?: string,
+): Component | undefined {
+  const key = normalizeDmsName(name);
+  const own = owner
+    ? registry.privateComponents.get(owner)?.get(key)
+    : undefined;
+  return (own ?? registry.components.get(key))?.component;
 }
 export const getDmsComponent = resolveDmsComponent;
 
+const PRIVATE_COMPONENT_SEPARATOR = "::";
+
+function registeredComponents(): DmsComponentRegistration[] {
+  return [
+    ...registry.components.values(),
+    ...[...registry.privateComponents.values()].flatMap((entries) => [
+      ...entries.values(),
+    ]),
+  ];
+}
+
+/** Names a registered component across the server render and hydration. */
+function componentReference({ name, module }: DmsComponentRegistration) {
+  return module === undefined
+    ? name
+    : `${module}${PRIVATE_COMPONENT_SEPARATOR}${name}`;
+}
+
 /**
  * Records, by registered name, every registered async component a server
  * render reaches, so the client can resolve the same ones before hydrating.
@@ -1213,9 +1312,9 @@ export const getDmsComponent = resolveDmsComponent;
  */
 export function trackDmsAsyncComponents(app: App): Set<string> {
   const names = new Map<Component, string>();
-  registry.components.forEach(({ component, name }) => {
-    if ((component as DmsAsyncComponent).__asyncLoader)
-      names.set(component, name);
+  registeredComponents().forEach((registration) => {
+    if ((registration.component as DmsAsyncComponent).__asyncLoader)
+      names.set(registration.component, componentReference(registration));
   });
   const rendered = new Set<string>();
   app.mixin({
@@ -1258,10 +1357,18 @@ export function trackDmsServerScopes(app: App): () => void {
 export async function resolveDmsAsyncComponents(
   names: readonly string[],
 ): Promise<void> {
+  const components = new Map(
+    registeredComponents().map((registration) => [
+      componentReference(registration),
+      registration.component,
+    ]),
+  );
   await Promise.all(
     names.map((name) =>
       (
-        resolveDmsComponent(name) as DmsAsyncComponent | undefined
+        (components.get(name) ?? resolveDmsComponent(name)) as
+          | DmsAsyncComponent
+          | undefined
       )?.__asyncLoader?.(),
     ),
   );
@@ -1303,6 +1410,7 @@ function collectRenderedComponentNames(
 
 async function preloadDmsLayoutComponents(
   layout: DmsPageLayout | undefined,
+  owner: string | undefined,
 ): Promise<void> {
   const names = new Set<string>();
   collectRenderedComponentNames(layout?.layout, names);
@@ -1311,7 +1419,7 @@ async function preloadDmsLayoutComponents(
   });
   await Promise.all(
     [...names].map((name) => {
-      const component = resolveDmsComponent(name) as
+      const component = resolveDmsComponent(name, owner) as
         | DmsAsyncComponent
         | undefined;
       return component?.__asyncLoader?.();
@@ -1371,6 +1479,24 @@ export function getDmsLayoutProps(
   };
 }
 
+/**
+ * Whether a page carries an older session of the same account than the one
+ * the app holds: Inertia restores a page from history, or serves it from the
+ * prefetch cache, with the props it was fetched with, and those must not undo
+ * a later `useUserSession().fetch()`.
+ */
+function isStaleSession(
+  incoming: DmsSession | undefined,
+  current: DmsSession | null,
+): boolean {
+  return (
+    !!incoming &&
+    !!current &&
+    incoming.accountId === current.accountId &&
+    (incoming.updatedAt ?? 0) < (current.updatedAt ?? 0)
+  );
+}
+
 export function hydrateDmsPageProps(props: DmsPageProps, url?: string): void {
   const runtime = useDmsRuntime();
   if (url) updateRoute(runtime, url);
@@ -1384,10 +1510,12 @@ export function hydrateDmsPageProps(props: DmsPageProps, url?: string): void {
   }
   runtime.pageVersion++;
   runtime.currentError.value = null;
-  useDmsState<DmsUser | null>("dms-user", () => null).value =
-    props.user ?? null;
-  useDmsState<DmsSession | null>("dms-session", () => null).value =
-    props.session ?? null;
+  const session = useDmsState<DmsSession | null>("dms-session", () => null);
+  if (!isStaleSession(props.session, session.value)) {
+    useDmsState<DmsUser | null>("dms-user", () => null).value =
+      props.user ?? null;
+    session.value = props.session ?? null;
+  }
   const shared = props.page.shared;
   if (shared) {
     useDmsState<unknown>("dms-siteLayout", () => undefined).value =
@@ -1433,7 +1561,8 @@ export async function preloadDmsPage(props: DmsPageProps): Promise<void> {
       (entry?.component as DmsAsyncComponent | undefined)?.__asyncLoader?.(),
     ]),
   );
-  if (!props.error) await preloadDmsLayoutComponents(props.page.layout);
+  if (!props.error)
+    await preloadDmsLayoutComponents(props.page.layout, props.page.module);
 }
 
 export function useDmsInjection<T>(
@@ -1451,14 +1580,29 @@ function registerDmsFrontendEntry(
   if (!entries.has(name)) entries.set(name, { component, preload });
 }
 
+function privateComponentsOf(
+  target: DmsFrontendRegistry,
+  owner: string,
+): Map<string, DmsComponentRegistration> {
+  const entries = target.privateComponents.get(owner) ?? new Map();
+  target.privateComponents.set(owner, entries);
+  return entries;
+}
+
 function createSdk(
   target: DmsFrontendRegistry,
-  options: DmsModuleOptions,
+  { name: owner = "", options }: DmsFrontendModuleRegistration,
 ): DmsFrontendSdk {
   return {
     options,
-    registerComponent: (name, component) =>
-      registerDmsComponentEntry(target.components, name, component),
+    registerComponent: (name, component, registration = {}) =>
+      registration.private
+        ? registerDmsComponentEntry(privateComponentsOf(target, owner), {
+            name,
+            component,
+            module: owner,
+          })
+        : registerDmsComponentEntry(target.components, { name, component }),
     registerPage: (name, component, preload) => {
       const key = normalizeDmsPageKey(name);
       registerDmsFrontendEntry(target.pages, key, component, preload);
@@ -1519,7 +1663,7 @@ export async function setupFrontendModules(
       runtimeConfig.value.public,
       registration.options.public,
     );
-    await registration.module.setup(createSdk(next, registration.options));
+    await registration.module.setup(createSdk(next, registration));
   }
   registry = next;
 }

package/templates/vue/icon-hydration.ts

@@ -0,0 +1,78 @@
+import {
+  addCollection,
+  addIcon,
+  getIcon,
+  Icon,
+  type IconifyIcon,
+  type IconifyJSON,
+  iconLoaded,
+} from "@iconify/vue";
+import type { App, Component, ComponentPublicInstance } from "vue";
+
+/** The element a server render writes the data of the icons it drew to. */
+export const SSR_ICONS_ID = "dms-ssr-icons";
+
+interface IconProps {
+  icon?: unknown;
+}
+
+/**
+ * Draws an Iconify icon in its first render whenever its data is loaded, on
+ * the server as in the browser.
+ *
+ * `@iconify/vue` otherwise renders every icon empty until it mounts, which a
+ * server render never does: pages arrived without their icons, which popped in
+ * once hydrated. Its `ssr` prop opts out of the wait, but Nuxt UI's `UIcon`
+ * does not pass it, so its default is set here, and only for an icon whose
+ * data is loaded: an icon still to be fetched waits for the mount as before,
+ * so a server render never queries an Iconify API.
+ */
+export function drawLoadedIconsAtOnce(): void {
+  (Icon as unknown as { props: Record<string, unknown> }).props.ssr = {
+    type: Boolean,
+    default: ({ icon }: IconProps) =>
+      typeof icon !== "string" || iconLoaded(icon),
+  };
+}
+
+/**
+ * Loads whole icon collections, so a server render draws any icon of them,
+ * including those only named by backend data, which the client bundle's scan
+ * cannot see.
+ */
+export function registerDmsIconCollections(collections: IconifyJSON[]): void {
+  for (const collection of collections) addCollection(collection);
+}
+
+/** Records the name of every Iconify icon a server render reaches. */
+export function trackDmsIcons(app: App): Set<string> {
+  const names = new Set<string>();
+  app.mixin({
+    beforeCreate(this: ComponentPublicInstance) {
+      if (this.$.type !== (Icon as Component)) return;
+      const { icon } = this.$props as IconProps;
+      if (typeof icon === "string") names.add(icon);
+    },
+  });
+  return names;
+}
+
+/**
+ * The data of the icons a server render drew, which the browser loads before
+ * it hydrates: an icon outside the client bundle would otherwise hydrate
+ * empty over the server's markup.
+ */
+export function serializeDmsIcons(
+  names: Iterable<string>,
+): Record<string, IconifyIcon> {
+  return Object.fromEntries(
+    [...names].flatMap((name) => {
+      const data = getIcon(name);
+      return data ? [[name, data]] : [];
+    }),
+  );
+}
+
+export function addDmsIcons(icons: Record<string, IconifyIcon>): void {
+  for (const [name, data] of Object.entries(icons)) addIcon(name, data);
+}

package/templates/vue/server/auth/backend.mjs

@@ -1,4 +1,4 @@
-import { clientIp } from "./client-ip.mjs";
+import { clientCountryHeader, clientIp } from "./client-ip.mjs";
 
 const FORWARDED_HEADERS = [
   "user-agent",
@@ -26,12 +26,26 @@ export function publicBackendMessage(data) {
     : undefined;
 }
 
-export async function backend(path, request, options = {}) {
-  const headers = Object.fromEntries(
-    FORWARDED_HEADERS.flatMap((name) =>
-      request.headers[name] ? [[name, request.headers[name]]] : [],
+/**
+ * The headers of a client request the server relays to the backend.
+ *
+ * @param request The client request
+ * @param names Lowercase names of the request headers to copy when present
+ * @returns The client country header, then the copied headers
+ */
+export function relayedHeaders(request, names) {
+  return {
+    ...clientCountryHeader(request),
+    ...Object.fromEntries(
+      names.flatMap((name) =>
+        request.headers[name] ? [[name, request.headers[name]]] : [],
+      ),
     ),
-  );
+  };
+}
+
+export async function backend(path, request, options = {}) {
+  const headers = relayedHeaders(request, FORWARDED_HEADERS);
   headers["x-forwarded-for"] = clientIp(request);
   if (options.token) headers.authorization = `Bearer ${options.token}`;
   if (options.relay)

package/templates/vue/server/auth/client-ip.mjs

@@ -51,6 +51,34 @@ export function clientIp(request) {
   return chain[Math.max(0, chain.length - hops - 1)] ?? socketIp;
 }
 
+const DEFAULT_COUNTRY_HEADER = "CF-IPCountry";
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
+
+function countryHeader() {
+  const name = (process.env.DMS_COUNTRY_HEADER ?? DEFAULT_COUNTRY_HEADER)
+    .trim()
+    .toLowerCase();
+  return HEADER_NAME.test(name) ? name : undefined;
+}
+
+/**
+ * The client's country header, as the backend request headers to add.
+ *
+ * The header is the one `DMS_COUNTRY_HEADER` names (`CF-IPCountry` by
+ * default, empty to relay none), the name the DMS reads from
+ * `auth.signInCountry.header`. Like `X-Forwarded-For`, it is only believed
+ * from a trusted reverse proxy: with `DMS_TRUSTED_PROXY_HOPS` at `0`, any
+ * caller could have set it, so nothing is relayed.
+ */
+export function clientCountryHeader(request) {
+  const name = countryHeader();
+  if (!name || !trustedHops()) return {};
+  const value = request.headers?.[name];
+  return typeof value === "string" && value.trim()
+    ? { [name]: value.trim() }
+    : {};
+}
+
 /**
  * Body answered with the 403 of the CSRF origin check.
  *

package/templates/vue/server/auth/routes.mjs

@@ -66,6 +66,7 @@ export function publicSession(session) {
     session: {
       accountId: session.accountId,
       activeTenantId: session.activeTenantId,
+      updatedAt: session.updatedAt,
     },
   };
 }

package/templates/vue/server/auth/session.mjs

@@ -146,9 +146,15 @@ export function assertAccountInvariant(session, accountId) {
     throw new Error("Account session invariant violated");
 }
 
+/**
+ * Write `session` as the current one, and as one of the stored accounts.
+ * Stamps it with `updatedAt`, which lets the browser tell a page fetched
+ * before this write, and restored from its cache, from a current one.
+ */
 export function persistAccountSession(request, response, session, accountId) {
   const id = accountId ?? session.accountId ?? randomUUID();
   session.accountId = id;
+  session.updatedAt = Date.now();
   const account = storeAccount(request, response, session, id);
   assertAccountInvariant(session, account.accountId);
   writeSession(response, session);

package/templates/vue/server/icons.mjs

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,12 +14,16 @@ const READ_METHODS = new Set(["GET", "HEAD"]);
 const ICON_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const COLLECTION_FILE = /^([^/]+)\.json$/;
 const ICON_NAME_SEPARATOR = ",";
+const COLLECTION_PACKAGES = join("node_modules", "@iconify-json");
 // An icon's data only changes with the installed collection, which a
 // deployment replaces; a week bounds how long an upgraded icon can lag.
 const ICON_CACHE_CONTROL =
   "public, max-age=604800, stale-while-revalidate=86400";
 const ERROR_CACHE_CONTROL = "no-store";
 const collections = new Map();
+// By renderer module: a development server evaluates a new one after a layer
+// changes, and each must find the collections loaded before it renders.
+const rendererCollections = new WeakMap();
 
 function collectionSpecifiers(prefix) {
   return [
@@ -60,6 +64,44 @@ function collection(root, prefix) {
   return collections.get(key);
 }
 
+/**
+ * Every `@iconify-json/<prefix>` collection installed in the workspace under
+ * `root`, the ones the server render draws from. The workspace hoists every
+ * dependency, a module's collections included.
+ */
+export async function installedCollections(root) {
+  const prefixes = await readdir(join(root, COLLECTION_PACKAGES)).catch(
+    () => [],
+  );
+  const loaded = await Promise.all(
+    prefixes
+      .filter((prefix) => ICON_NAME.test(prefix))
+      .map((prefix) => collection(root, prefix)),
+  );
+  return loaded.filter(Boolean);
+}
+
+/**
+ * Hand a server renderer the installed collections, once per renderer module,
+ * before its first render. A collection that fails to load leaves the render
+ * with the bundled icons only.
+ */
+export function provideIconCollections(renderer, root = WORKSPACE_ROOT) {
+  if (!rendererCollections.has(renderer))
+    rendererCollections.set(
+      renderer,
+      installedCollections(root)
+        .then((loaded) => renderer.registerDmsIconCollections(loaded))
+        .catch((error) =>
+          console.error(
+            "DMS icon collections not loaded; server renders draw bundled icons only",
+            error,
+          ),
+        ),
+    );
+  return rendererCollections.get(renderer);
+}
+
 function jsonResponse(status, cacheControl, payload) {
   return {
     status,

package/templates/vue/server.mjs

@@ -5,7 +5,11 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
 import { ofetch } from "ofetch";
-import { RequestBodyError, UpstreamError } from "./server/auth/backend.mjs";
+import {
+  relayedHeaders,
+  RequestBodyError,
+  UpstreamError,
+} from "./server/auth/backend.mjs";
 import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./server/auth/client-ip.mjs";
 import {
   handleAuth,
@@ -36,7 +40,7 @@ import { documentStyleTags } from "./server/dev-styles.mjs";
 import { handleEmailRender, watchEmailBundle } from "./server/email.mjs";
 import { HOMEPAGE } from "./server/homepage.mjs";
 import { htmlTag } from "./server/html-tag.mjs";
-import { handleIcons, isIconRequest } from "./server/icons.mjs";
+import * as icons from "./server/icons.mjs";
 import * as requestFailure from "./server/request-failure.mjs";
 import { handleTester } from "./server/tester.mjs";
 import {
@@ -75,7 +79,7 @@ const HTML_RENDER_ROUTE = "/api/html/render";
 const TESTER_ROUTE = /^\/api\/_dms\/tester\/?$/;
 const LOCAL_ROUTES = [
   [(pathname) => TESTER_ROUTE.test(pathname), handleTester],
-  [isIconRequest, handleIcons],
+  [icons.isIconRequest, icons.handleIcons],
 ];
 const AUTH_PAGE = "/auth";
 const ONBOARDING_PAGE = "/onboarding";
@@ -117,18 +121,13 @@ async function developmentServer() {
 }
 
 function backendHeaders(request) {
-  const names = [
+  const headers = relayedHeaders(request, [
     "accept",
     "content-type",
     "user-agent",
     "x-content-language",
     "x-realtime-session",
-  ];
-  const headers = Object.fromEntries(
-    names.flatMap((name) =>
-      request.headers[name] ? [[name, request.headers[name]]] : [],
-    ),
-  );
+  ]);
   const session = readSession(request);
   if (session?.accessToken)
     headers.authorization = `Bearer ${session.accessToken}`;
@@ -297,9 +296,11 @@ function serveAsset(pathname, request, response) {
 }
 
 async function ssrRenderer(devServer) {
-  if (devServer) return devServer.ssrLoadModule("/ssr-renderer.ts");
-  productionSsrRenderer ??= import(BUILT_SSR_RENDERER_PATH);
-  return productionSsrRenderer;
+  const renderer = devServer
+    ? await devServer.ssrLoadModule("/ssr-renderer.ts")
+    : await (productionSsrRenderer ??= import(BUILT_SSR_RENDERER_PATH));
+  await icons.provideIconCollections(renderer);
+  return renderer;
 }
 
 export async function renderHtml(