@antelopejs/dms-frontend 0.3.11 → 0.4.0

package/dist/verify-source-sources.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSourceOptions = readSourceOptions;
+exports.readSources = readSources;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const common_1 = require("./common");
+const output_1 = require("./output");
+const verify_source_result_1 = require("./verify-source-result");
+const DMS_PACKAGE = "@antelopejs/dms";
+const DMS_CORE_LAYER_PACKAGE = "@antelopejs/dms-frontend-vue";
+const CORE_LAYER_DIRECTORY = "frontend-vue";
+const FRONTEND_ENTRY = "dms.frontend.ts";
+const ADD_DEV_DEPENDENCY = {
+    pnpm: "pnpm add -D",
+    npm: "npm install -D",
+    yarn: "yarn add -D",
+    bun: "bun add -d",
+};
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["package-lock.json", "npm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+];
+function readSourceOptions() {
+    return {
+        projectDir: process.cwd(),
+        layerSource: process.env.DMS_LAYER_SOURCE || undefined,
+        moduleSources: JSON.parse(process.env.DMS_MODULE_SOURCES ?? "[]"),
+        localPackages: JSON.parse(process.env.DMS_LOCAL_PACKAGES ?? "{}"),
+    };
+}
+function readManifest(packagePath) {
+    return JSON.parse((0, node_fs_1.readFileSync)(packagePath, "utf8"));
+}
+function readLayer(root) {
+    const packagePath = (0, node_path_1.join)(root, "package.json");
+    if (!(0, node_fs_1.existsSync)(packagePath))
+        throw new common_1.UsageError({
+            title: `No package.json in ${(0, output_1.showPath)(root)}`,
+            fixes: [verify_source_result_1.LAYER_PATH_FIX],
+        });
+    const { name } = readManifest(packagePath);
+    return { path: root, sourcePath: root, packageName: name };
+}
+function isCoreLayer(layer) {
+    return layer.packageName === DMS_CORE_LAYER_PACKAGE;
+}
+function shellArgument(path) {
+    return /^[\w@%+=:,./~-]+$/.test(path) ? path : JSON.stringify(path);
+}
+function defaultModuleRoot(projectDir) {
+    const root = [projectDir, (0, node_path_1.join)(projectDir, CORE_LAYER_DIRECTORY)].find((candidate) => (0, node_fs_1.existsSync)((0, node_path_1.join)(candidate, FRONTEND_ENTRY)));
+    if (root)
+        return root;
+    throw new common_1.UsageError({
+        title: "No frontend module to verify",
+        reason: `Neither ${(0, output_1.showPath)(projectDir)} nor its ${CORE_LAYER_DIRECTORY} directory contains ${FRONTEND_ENTRY}.`,
+        fixes: [
+            `Run the command from the frontend module, or pass its root with -m`,
+        ],
+    });
+}
+function packageManager(projectDir) {
+    for (let directory = projectDir;; directory = (0, node_path_1.dirname)(directory)) {
+        const packagePath = (0, node_path_1.join)(directory, "package.json");
+        if ((0, node_fs_1.existsSync)(packagePath)) {
+            const [name] = (readManifest(packagePath).packageManager ?? "").split("@");
+            if (name && ADD_DEV_DEPENDENCY[name])
+                return name;
+            const lockfile = LOCKFILES.find(([file]) => (0, node_fs_1.existsSync)((0, node_path_1.join)(directory, file)));
+            if (lockfile)
+                return lockfile[1];
+        }
+        if ((0, node_path_1.dirname)(directory) === directory)
+            return "pnpm";
+    }
+}
+function addDmsCommand(projectDir, version = "") {
+    return `${ADD_DEV_DEPENDENCY[packageManager(projectDir)]} ${DMS_PACKAGE}${version}`;
+}
+function describeDirectory(directory) {
+    return (0, node_path_1.resolve)(directory) === process.cwd()
+        ? "the current directory"
+        : (0, output_1.showPath)(directory);
+}
+function resolveDmsPackage(projectDir) {
+    try {
+        return require.resolve(`${DMS_PACKAGE}/package.json`, {
+            paths: [projectDir],
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function installedCoreLayer(projectDir) {
+    const packagePath = resolveDmsPackage(projectDir);
+    if (!packagePath)
+        throw new common_1.UsageError({
+            title: `${DMS_PACKAGE} is not installed in this project`,
+            reason: `Frontend modules are verified on top of the DMS core layer that ${DMS_PACKAGE} ships, and Node finds no ${DMS_PACKAGE} from ${describeDirectory(projectDir)}.`,
+            fixes: [
+                `Add it as a development dependency: ${addDmsCommand(projectDir)}`,
+            ],
+        });
+    const { version } = readManifest(packagePath);
+    const root = (0, node_path_1.join)((0, node_path_1.dirname)(packagePath), CORE_LAYER_DIRECTORY);
+    const layer = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "package.json"))
+        ? readLayer(root)
+        : undefined;
+    if (!layer || !isCoreLayer(layer))
+        throw new common_1.UsageError({
+            title: `${DMS_PACKAGE} ${version} ships no DMS core layer`,
+            reason: `${(0, output_1.showPath)((0, node_path_1.dirname)(packagePath))} has no ${CORE_LAYER_DIRECTORY} directory holding ${DMS_CORE_LAYER_PACKAGE}.`,
+            fixes: [`Update it: ${addDmsCommand(projectDir, "@latest")}`],
+        });
+    return {
+        layers: [layer],
+        coreLayer: `${DMS_PACKAGE} ${version} (installed in this project)`,
+    };
+}
+function notCoreLayer(sourceRoot, layers, modules, localPackages) {
+    const command = [
+        verify_source_result_1.VERIFY_SOURCE_COMMAND,
+        ...[...layers, ...modules].flatMap((layer) => [
+            "-m",
+            shellArgument((0, output_1.showPath)(layer.path)),
+        ]),
+        ...Object.entries(localPackages).flatMap(([name, path]) => [
+            "--local-package",
+            shellArgument(`${name}=${(0, output_1.showPath)(path)}`),
+        ]),
+    ].join(" ");
+    const names = layers
+        .map((layer) => layer.packageName ?? "a package without a name")
+        .join(", ");
+    const shown = (0, output_1.showPath)(sourceRoot);
+    return {
+        title: `${shown} is not the DMS core layer`,
+        reason: `--layer is for verifying an unpublished DMS core layer, ${DMS_CORE_LAYER_PACKAGE}, and ${shown} holds ${names}. ` +
+            `Without it, frontend modules are verified on the core layer of the ${DMS_PACKAGE} installed in the project.`,
+        fixes: [`Drop -l and pass the folder with -m: ${command}`],
+    };
+}
+function readLayerSource(layerSource) {
+    const sourceRoot = (0, node_path_1.resolve)(layerSource);
+    if (!(0, node_fs_1.statSync)(sourceRoot, { throwIfNoEntry: false })?.isDirectory())
+        throw new common_1.UsageError({
+            title: `Layer path not found: ${(0, output_1.showPath)(sourceRoot)}`,
+            fixes: [verify_source_result_1.LAYER_PATH_FIX],
+        });
+    const roots = (0, node_fs_1.existsSync)((0, node_path_1.join)(sourceRoot, FRONTEND_ENTRY))
+        ? [sourceRoot]
+        : (0, node_fs_1.readdirSync)(sourceRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => (0, node_path_1.join)(sourceRoot, entry.name));
+    if (roots.length === 0)
+        throw new common_1.UsageError({
+            title: `No frontend package in ${(0, output_1.showPath)(sourceRoot)}`,
+            fixes: [verify_source_result_1.LAYER_PATH_FIX],
+        });
+    return { sourceRoot, layers: roots.map(readLayer) };
+}
+function readSources(options) {
+    const { projectDir, layerSource, localPackages } = options;
+    const modules = (options.moduleSources.length > 0 || layerSource
+        ? options.moduleSources.map((root) => (0, node_path_1.resolve)(root))
+        : [defaultModuleRoot(projectDir)]).map(readLayer);
+    if (layerSource) {
+        const { sourceRoot, layers } = readLayerSource(layerSource);
+        if (!layers.some(isCoreLayer))
+            throw new common_1.UsageError(notCoreLayer(sourceRoot, layers, modules, localPackages));
+        return {
+            layers: [...layers, ...modules],
+            coreLayer: `the DMS core layer in ${(0, output_1.showPath)(sourceRoot)}`,
+        };
+    }
+    const passedCore = modules.find(isCoreLayer);
+    if (passedCore)
+        return {
+            layers: [passedCore, ...modules.filter((layer) => layer !== passedCore)],
+            coreLayer: `the DMS core layer in ${(0, output_1.showPath)(passedCore.path)}`,
+        };
+    const installed = installedCoreLayer(projectDir);
+    return { ...installed, layers: [...installed.layers, ...modules] };
+}

package/dist/workspace.d.ts

@@ -27,6 +27,7 @@ export interface FrontendManifest {
 }
 export interface ResolvedLayer {
     path: string;
+    name?: string;
     sourcePath?: string;
     packageName?: string;
     priority?: number;

package/package.json

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

package/templates/vue/DmsDynamicPage.vue

@@ -37,6 +37,7 @@ interface PageRoute {
 interface PagePayload {
   layout?: PageLayout;
   route?: PageRoute;
+  module?: string;
 }
 
 interface DynamicPageProps {
@@ -55,7 +56,8 @@ function resolveDefinition(
   return {
     id,
     component: definition.componentName
-      ? resolveDmsComponent(definition.componentName) || "div"
+      ? resolveDmsComponent(definition.componentName, props.page.module) ||
+        "div"
       : "div",
     componentName: definition.componentName,
     options: definition.options,

package/templates/vue/app-runtime.ts

@@ -6,6 +6,7 @@ import { en as uiEn, fr as uiFr } from "@nuxt/ui/locale";
 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 type { FetchOptions } from "ofetch";
 import {
   type App,
@@ -23,7 +24,9 @@ import DmsDynamicPage from "./DmsDynamicPage.vue";
 import {
   type DmsLocaleLoader,
   type DmsPageProps,
+  type DmsUser,
   createDmsFrontendRuntime,
+  dmsPageSuspenseProps,
   getDmsErrorPage,
   getDmsLayout,
   getDmsLayoutProps,
@@ -39,7 +42,13 @@ import {
   useDmsAppConfig,
   useDmsState,
   useError,
+  useUserSession,
 } from "./frontend-module";
+import {
+  SSR_ICONS_ID,
+  addDmsIcons,
+  drawLoadedIconsAtOnce,
+} from "./icon-hydration";
 import {
   loadLocaleMessages,
   localeMessages,
@@ -94,30 +103,24 @@ function uiLocale(locale: string): UiLocale {
   return UI_LOCALES[locale as keyof typeof UI_LOCALES] ?? UI_LOCALES.en;
 }
 
-function pageLocale(props: DmsPageProps): string {
-  const language = props.user?.language;
-  if (typeof language !== "string") return DEFAULT_LOCALE;
+/** The supported locale of a user's language, if it has one. */
+function userLocale(user: DmsUser | null | undefined): string | undefined {
+  const language = user?.language;
+  if (typeof language !== "string") return undefined;
   const locale = language.slice(0, 2);
-  return supportedLocales.includes(locale) ? locale : DEFAULT_LOCALE;
+  return supportedLocales.includes(locale) ? locale : undefined;
 }
 
-function readDmsAsyncData(): Record<string, unknown> {
-  if (typeof document === "undefined") return {};
-  const element = document.getElementById(SSR_ASYNC_DATA_ID);
-  if (!element?.textContent) return {};
-  const data = JSON.parse(element.textContent) as Record<string, unknown>;
+function readServerRendered<T>(id: string, empty: T): 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;
   element.remove();
-  return data;
+  return value;
 }
 
-function readDmsAsyncComponents(): string[] {
-  if (typeof document === "undefined") return [];
-  const element = document.getElementById(SSR_ASYNC_COMPONENTS_ID);
-  if (!element?.textContent) return [];
-  const names = JSON.parse(element.textContent) as string[];
-  element.remove();
-  return names;
-}
+drawLoadedIconsAtOnce();
 
 const DmsInertiaPage = defineComponent({
   name: "DmsInertiaPage",
@@ -148,17 +151,25 @@ const DmsPersistentLayout = defineComponent({
   setup(_, { attrs, slots }) {
     const props = computed(() => attrs as unknown as DmsPageProps);
     const i18n = useI18n();
+    const { user } = useUserSession();
     let localeVersion = 0;
     useHead({
       htmlAttrs: { lang: computed(() => i18n.locale.value) },
     });
     watch(
       () => [attrs.path, attrs.page, attrs.user, attrs.session, attrs.error],
-      async () => {
+      () => hydrateDmsPageProps(props.value),
+      { immediate: true, 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
+    // session without a language keeps the one on screen.
+    watch(
+      () => userLocale(user.value),
+      async (locale) => {
         const version = ++localeVersion;
-        hydrateDmsPageProps(props.value);
-        const locale = pageLocale(props.value);
-        if (i18n.locale.value === locale) return;
+        if (!locale || i18n.locale.value === locale) return;
         const messages = await loadLocaleMessages(locale);
         if (version !== localeVersion) return;
         i18n.setLocaleMessage(locale, messages);
@@ -205,7 +216,7 @@ function renderDmsPage(
     error,
     key: props.path,
   });
-  return h(Suspense, null, { default: () => pageContent });
+  return h(Suspense, dmsPageSuspenseProps(), { default: () => pageContent });
 }
 
 function renderDmsPersistentLayout(
@@ -247,9 +258,9 @@ export async function configureDmsApp(
     options.runtime ??
     createDmsFrontendRuntime(
       options.serverFetch as typeof import("ofetch").ofetch,
-      readDmsAsyncData(),
+      readServerRendered<Record<string, unknown>>(SSR_ASYNC_DATA_ID, {}),
     );
-  const locale = pageLocale(options.initialPageProps);
+  const locale = userLocale(options.initialPageProps.user) ?? DEFAULT_LOCALE;
   const messages = await loadLocaleMessages(locale);
   const i18n = createI18n({
     legacy: false,
@@ -266,6 +277,9 @@ export async function configureDmsApp(
   options.app.runWithContext(() =>
     hydrateDmsPageProps(options.initialPageProps, options.initialPageUrl),
   );
+  addDmsIcons(
+    readServerRendered<Record<string, IconifyIcon>>(SSR_ICONS_ID, {}),
+  );
   if (typeof window !== "undefined") {
     const toast = options.app.runWithContext(() => useToast());
     showNetworkErrors(toast.add, i18n.global);
@@ -275,7 +289,9 @@ export async function configureDmsApp(
   // Hydration then adopts the server-rendered markup instead of discarding it.
   await Promise.all([
     preloadDmsPage(options.initialPageProps),
-    resolveDmsAsyncComponents(readDmsAsyncComponents()),
+    resolveDmsAsyncComponents(
+      readServerRendered<string[]>(SSR_ASYNC_COMPONENTS_ID, []),
+    ),
   ]);
   const mounted = await installDmsPlugins(
     options.app,

package/templates/vue/frontend-build-loader.ts

@@ -0,0 +1,78 @@
+import { isAbsolute, posix, resolve } from "node:path";
+import { normalizePath } from "vite";
+import type { DmsFrontendBuildSetup } from "./frontend-build";
+
+/** A module's `dms.frontend.build.ts`, as the generated loader imports it. */
+export interface FrontendBuildDeclaration {
+  /** The module's id in the generated module registry. */
+  id: string;
+  setup: DmsFrontendBuildSetup;
+}
+
+interface FrontendModuleRoot {
+  id: string;
+  root: string;
+}
+
+export interface AutoImportDirectory {
+  glob: string;
+  types: boolean;
+}
+
+/** A module's private code: never auto-imported, whatever it declares. */
+const PRIVATE_DIRECTORY = /(?:^|\/)app\/build(?:\/|$)/;
+
+function declaredDirectories(setup: DmsFrontendBuildSetup): string[] {
+  const directories: string[] = [];
+  setup({
+    registerAutoImports: (entries) => directories.push(...entries),
+  });
+  return directories;
+}
+
+function rejection(directory: string): string | undefined {
+  const path = posix.normalize(normalizePath(directory));
+  if (isAbsolute(directory) || path === ".." || path.startsWith("../"))
+    return "it is not inside the module";
+  if (PRIVATE_DIRECTORY.test(path))
+    return "app/build/ holds the module's private code, which is never auto-imported";
+  return undefined;
+}
+
+/**
+ * The directories the modules declared in their `dms.frontend.build.ts`, as
+ * the auto-importer's scan globs. Each module's `app/build/` directories are
+ * excluded even from a broader declaration; a declaration naming one, or
+ * leaving the module, is ignored with a warning.
+ *
+ * Globs are POSIX on every platform: the scanner reads a backslash as an
+ * escape, not as a separator.
+ */
+export function autoImportDirectories(
+  modules: readonly FrontendModuleRoot[],
+  declarations: readonly FrontendBuildDeclaration[],
+  warn: (message: string) => void,
+): AutoImportDirectory[] {
+  const roots = new Map(modules.map((module) => [module.id, module.root]));
+  return declarations.flatMap(({ id, setup }) => {
+    const root = roots.get(id);
+    if (root === undefined) return [];
+    const scan = (pattern: string) => normalizePath(resolve(root, pattern));
+    const accepted = declaredDirectories(setup).filter((directory) => {
+      const reason = rejection(directory);
+      if (reason)
+        warn(
+          `Frontend module ${id} declares "${directory}" for auto-import, which is ignored: ${reason}.`,
+        );
+      return !reason;
+    });
+    if (accepted.length === 0) return [];
+    return [
+      ...accepted.map((directory) => ({
+        glob: scan(`${directory}/**/*`),
+        types: true,
+      })),
+      { glob: `!${scan("**/app/build/**")}`, types: true },
+    ];
+  });
+}

package/templates/vue/frontend-build.ts

@@ -0,0 +1,41 @@
+/**
+ * What a frontend module's `dms.frontend.build.ts` declares about how the
+ * application is built from it. Read when Vite starts, by `ajs dms dev` and
+ * `ajs dms build` alike.
+ */
+export interface DmsFrontendBuild {
+  /**
+   * Makes every export of the files under these directories available to
+   * the whole application without an import, in scripts and templates.
+   *
+   * Each entry is a directory relative to the module root, and may hold glob
+   * patterns: `layers/*\/app/composables` covers that directory of every
+   * layer. Nothing under an `app/build/` directory is ever auto-imported: it
+   * holds the module's private code, which its own files import by path.
+   */
+  registerAutoImports(directories: readonly string[]): void;
+}
+
+export type DmsFrontendBuildSetup = (build: DmsFrontendBuild) => void;
+
+/**
+ * Declares how the application is built from a frontend module, as the
+ * default export of its `dms.frontend.build.ts`:
+ *
+ * ```ts
+ * import { defineDmsFrontendBuild } from "#dms/frontend-build";
+ *
+ * export default defineDmsFrontendBuild((build) => {
+ *   build.registerAutoImports(["layers/*\/app/composables"]);
+ * });
+ * ```
+ *
+ * A module without this file has nothing auto-imported. The file runs in
+ * Node.js when Vite starts, not in the application: it may import Node.js
+ * built-ins, never the application's own code.
+ */
+export function defineDmsFrontendBuild(
+  setup: DmsFrontendBuildSetup,
+): DmsFrontendBuildSetup {
+  return setup;
+}