@antelopejs/dms-frontend 0.3.4 → 0.3.5

package/README.md

@@ -355,6 +355,25 @@ directory added to or removed from `layers/` is the exception: Vite reads the
 `#<layer>` aliases and the auto-imported directories at startup only, so the
 dev server says it needs a restart.
 
+### Icons
+
+The browser never asks a third party for an icon, so a Content-Security-Policy
+needs no exception for the Iconify API. Icons reach the page two ways:
+
+- **Bundled.** Nuxt UI's client bundle holds every icon its scanner finds in
+  the workspace's Vue, Markdown and YAML files, the TypeScript of each layer's
+  `app/` directory — `app.config.ts` and its `ui.icons` mappings included — and
+  Nuxt UI's own defaults.
+- **Served.** Any other icon, such as a page icon a backend module declares,
+  is fetched from the frontend server itself: `main.ts` points `@iconify/vue`
+  at `GET /api/_dms/icons/<prefix>.json?icons=<name>,…`, which answers in the
+  Iconify API format from the collections installed in the workspace
+  (`@iconify-json/<prefix>`, or `@iconify/json`). The workspace ships
+  `@iconify-json/lucide` and `@iconify-json/ph`; a module using another
+  collection depends on its `@iconify-json/*` package. An unknown collection
+  answers `404`, and a name outside Iconify's naming rule `400`. `ajs dms dev`
+  and `ajs dms start` run the same server, so both serve the route.
+
 ## Options
 
 | Option | Environment | Purpose |

package/dist/config.js

@@ -36,11 +36,14 @@ exports.TEMPLATE_FILES = [
     ["main.ts", "main.ts"],
     ["app-runtime.ts", "app-runtime.ts"],
     ["network-error.ts", "network-error.ts"],
+    ["ui-app-config.ts", "ui-app-config.ts"],
     ["ssr-renderer.ts", "ssr-renderer.ts"],
     ["frontend-module.ts", "frontend-module.ts"],
     ["globals.d.ts", "globals.d.ts"],
     ["compress-assets.mjs", "compress-assets.mjs"],
     ["head-order.mjs", "head-order.mjs"],
+    ["icon-api.mjs", "icon-api.mjs"],
+    ["icon-scan.mjs", "icon-scan.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.3.4",
+  "version": "0.3.5",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",
@@ -77,6 +77,8 @@
   },
   "devDependencies": {
     "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
+    "@iconify/utils": "^3.1.0",
+    "@iconify/vue": "^5.0.1",
     "@inertiajs/vue3": "^3.7.1",
     "@types/figlet": "^1.7.0",
     "@types/node": "^24.8.1",

package/templates/vue/app-runtime.ts

@@ -6,7 +6,6 @@ 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 { defu } from "defu";
 import type { FetchOptions } from "ofetch";
 import {
   type App,
@@ -48,6 +47,7 @@ import {
   syncLocaleMessages,
 } from "./locales.generated";
 import { showNetworkErrors } from "./network-error";
+import { createUiAppConfigMerger } from "./ui-app-config";
 
 export interface DmsInertiaSetupProps {
   initialPage: unknown;
@@ -233,20 +233,10 @@ function renderDmsPersistentLayout(
   );
 }
 
-/**
- * Nuxt UI keeps one app config for the whole process, and defu concatenates
- * arrays: merged into it on every server render, the compound variants the DMS
- * declares piled up, and every class list built from them grew with each
- * request. Each config is merged once; a new one, after a reload, is merged
- * again.
- */
-const mergedUiAppConfigs = new WeakSet<object>();
+const mergeUiAppConfig = createUiAppConfigMerger();
 
 function mergeDmsAppConfig(): void {
-  const uiAppConfig = useAppConfig();
-  if (mergedUiAppConfigs.has(uiAppConfig)) return;
-  Object.assign(uiAppConfig, defu(useDmsAppConfig(), uiAppConfig));
-  mergedUiAppConfigs.add(uiAppConfig);
+  mergeUiAppConfig(useAppConfig(), useDmsAppConfig());
 }
 
 export async function configureDmsApp(

package/templates/vue/icon-api.mjs

@@ -0,0 +1,15 @@
+/**
+ * Where the generated server answers the Iconify API, as
+ * `<ICON_API_PATH><prefix>.json?icons=a,b`. Under `/api/_dms/`, the prefix the
+ * server already answers itself, so it can never shadow a page or be proxied to
+ * the backend.
+ */
+export const ICON_API_PATH = "/api/_dms/icons/";
+
+/**
+ * The `@iconify/vue` API provider serving every icon the client bundle lacks
+ * from `origin`, instead of `api.iconify.design` and its fallbacks.
+ */
+export function sameOriginIconProvider(origin) {
+  return { resources: [origin], path: ICON_API_PATH };
+}

package/templates/vue/icon-scan.mjs

@@ -0,0 +1,31 @@
+import { relative, sep } from "node:path";
+
+/** What `@nuxt/icon`'s `IconUsageScanner` reads when given no `globInclude`. */
+const DEFAULT_SCAN_GLOBS = ["**/*.{vue,jsx,tsx,md,mdc,mdx,yml,yaml}"];
+
+/**
+ * The scripts of a frontend source root that may name an icon: its
+ * `app.config.ts` (the `ui.icons` mappings) and any icon a composable or a
+ * constant names in TypeScript. Limited to `app/`, so a module's tests,
+ * fixtures and tooling never reach the client bundle.
+ */
+const SOURCE_SCRIPT_GLOB = "app/**/*.ts";
+
+/**
+ * The `globInclude` of the Nuxt UI client-bundle icon scan.
+ *
+ * The scanner walks the Vite root, with globs relative to it, and by default
+ * skips `.ts` files: every icon a layer names only in TypeScript was then
+ * fetched from the Iconify API at run time. Every frontend source root lives
+ * under the workspace (`frontend-modules/`, enforced when the registry is
+ * written), so a relative glob reaches it. Globs are POSIX on every platform.
+ */
+export function iconScanGlobs(viteRoot, sourceRoots) {
+  const sourceGlobs = sourceRoots.map((root) =>
+    [
+      ...relative(viteRoot, root).split(sep).filter(Boolean),
+      SOURCE_SCRIPT_GLOB,
+    ].join("/"),
+  );
+  return [...DEFAULT_SCAN_GLOBS, ...sourceGlobs];
+}

package/templates/vue/main.ts

@@ -1,10 +1,12 @@
 import "./dms-main.css";
+import { addAPIProvider } from "@iconify/vue";
 import { createInertiaApp } from "@inertiajs/vue3";
 import { createHead } from "@unhead/vue/client";
 import { createApp, createSSRApp, h } from "vue";
 import { configureDmsApp, resolveDmsInertiaPage } from "./app-runtime";
 import { setupFrontendModules } from "./frontend-module";
 import { frontendModules } from "./frontend-modules.generated";
+import { sameOriginIconProvider } from "./icon-api.mjs";
 
 const DEV_STYLE_ATTRIBUTE = "data-dms-dev-style";
 
@@ -46,6 +48,9 @@ function markDmsReady(): void {
 }
 
 if (import.meta.env.DEV) adoptViteDevStyles();
+// Before any module or component can render an icon the client bundle lacks:
+// the generated server answers those queries from the installed collections.
+addAPIProvider("", sameOriginIconProvider(location.origin));
 
 await setupFrontendModules(frontendModules);
 

package/templates/vue/package.json

@@ -9,6 +9,10 @@
     "start": "node server.mjs"
   },
   "dependencies": {
+    "@iconify-json/lucide": "^1.2.64",
+    "@iconify-json/ph": "^1.2.2",
+    "@iconify/utils": "^3.1.0",
+    "@iconify/vue": "^5.0.1",
     "@inertiajs/vue3": "^3.7.0",
     "@nuxt/ui": "4.10.0",
     "@tailwindcss/typography": "^0.5.19",

package/templates/vue/server/content.mjs

@@ -0,0 +1,47 @@
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import {
+  createBrotliCompress,
+  createGzip,
+  constants as zlibConstants,
+} from "node:zlib";
+
+const MINIMUM_COMPRESSION_BYTES = 1_024;
+const DYNAMIC_BROTLI_QUALITY = 4;
+
+function responseEncoder(request, content) {
+  if (Buffer.byteLength(content) < MINIMUM_COMPRESSION_BYTES) return undefined;
+  const accepted = request.headers["accept-encoding"] ?? "";
+  if (accepted.includes("br"))
+    return {
+      encoding: "br",
+      stream: createBrotliCompress({
+        params: {
+          [zlibConstants.BROTLI_PARAM_QUALITY]: DYNAMIC_BROTLI_QUALITY,
+        },
+      }),
+    };
+  if (accepted.includes("gzip"))
+    return { encoding: "gzip", stream: createGzip() };
+}
+
+/** Send a generated body, compressed when the client accepts it. */
+export async function writeContent(
+  request,
+  response,
+  status,
+  headers,
+  content,
+) {
+  const encoder = responseEncoder(request, content);
+  const vary = [headers.vary, "Accept-Encoding"].filter(Boolean).join(", ");
+  const encodedHeaders = { ...headers, vary };
+  if (!encoder) {
+    response.writeHead(status, encodedHeaders);
+    response.end(content);
+    return;
+  }
+  encodedHeaders["content-encoding"] = encoder.encoding;
+  response.writeHead(status, encodedHeaders);
+  await pipeline(Readable.from([content]), encoder.stream, response);
+}

package/templates/vue/server/icons.mjs

@@ -0,0 +1,124 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getIcons } from "@iconify/utils";
+import { ICON_API_PATH } from "../icon-api.mjs";
+import { writeContent } from "./content.mjs";
+
+const WORKSPACE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+const JSON_TYPE = "application/json";
+const READ_METHODS = new Set(["GET", "HEAD"]);
+// Iconify's own naming rule, for prefixes and icon names alike. It is also
+// what keeps a request from naming anything but a collection file.
+const ICON_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const COLLECTION_FILE = /^([^/]+)\.json$/;
+const ICON_NAME_SEPARATOR = ",";
+// 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();
+
+function collectionSpecifiers(prefix) {
+  return [
+    `@iconify-json/${prefix}/icons.json`,
+    `@iconify/json/json/${prefix}.json`,
+  ];
+}
+
+function resolveCollectionFile(root, prefix) {
+  const require = createRequire(join(root, "package.json"));
+  for (const specifier of collectionSpecifiers(prefix)) {
+    try {
+      return require.resolve(specifier);
+    } catch {
+      // Not installed under this name: try the next source.
+    }
+  }
+  return undefined;
+}
+
+async function loadCollection(root, prefix) {
+  const file = resolveCollectionFile(root, prefix);
+  if (!file) return undefined;
+  return JSON.parse(await readFile(file, "utf8"));
+}
+
+/**
+ * Parsed once per collection: a collection file is several megabytes, and
+ * one page asks for icons of the same few collections many times.
+ */
+function collection(root, prefix) {
+  const key = join(root, prefix);
+  if (!collections.has(key)) {
+    const loading = loadCollection(root, prefix);
+    loading.catch(() => collections.delete(key));
+    collections.set(key, loading);
+  }
+  return collections.get(key);
+}
+
+function jsonResponse(status, cacheControl, payload) {
+  return {
+    status,
+    headers: { "content-type": JSON_TYPE, "cache-control": cacheControl },
+    body: JSON.stringify(payload),
+  };
+}
+
+function errorResponse(status, message) {
+  return jsonResponse(status, ERROR_CACHE_CONTROL, { message });
+}
+
+function requestedIcons(url) {
+  const names = (url.searchParams.get("icons") ?? "")
+    .split(ICON_NAME_SEPARATOR)
+    .filter(Boolean);
+  if (!names.length || !names.every((name) => ICON_NAME.test(name)))
+    return undefined;
+  return [...new Set(names)];
+}
+
+/** Whether the generated server answers `pathname` with `iconResponse`. */
+export function isIconRequest(pathname) {
+  return pathname.startsWith(ICON_API_PATH);
+}
+
+/**
+ * Answer an Iconify API icon query from the collections installed under
+ * `root`: the subset of `@iconify-json/<prefix>` (or `@iconify/json`) holding
+ * the requested icons, and a `not_found` list for the others, as
+ * `api.iconify.design` does. Returns the status, headers and body to send.
+ */
+export async function iconResponse(root, method, url) {
+  if (!READ_METHODS.has(method)) {
+    const response = errorResponse(405, "Method not allowed");
+    response.headers.allow = [...READ_METHODS].join(", ");
+    return response;
+  }
+  const prefix = url.pathname
+    .slice(ICON_API_PATH.length)
+    .match(COLLECTION_FILE)?.[1];
+  const names = requestedIcons(url);
+  if (!prefix || !ICON_NAME.test(prefix) || !names)
+    return errorResponse(400, "Invalid icon request");
+  const data = await collection(root, prefix);
+  if (!data) return errorResponse(404, "Unknown icon collection");
+  return jsonResponse(200, ICON_CACHE_CONTROL, getIcons(data, names, true));
+}
+
+/**
+ * Serve an Iconify API query from the collections installed in the workspace,
+ * the same way under `ajs dms dev` and `ajs dms start`: both run this server.
+ */
+export async function handleIcons(request, response) {
+  const url = new URL(request.url, "http://frontend.local");
+  const { status, headers, body } = await iconResponse(
+    WORKSPACE_ROOT,
+    request.method,
+    url,
+  );
+  return writeContent(request, response, status, headers, body);
+}

package/templates/vue/server.mjs

@@ -4,11 +4,6 @@ import { extname, join, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
-import {
-  createBrotliCompress,
-  createGzip,
-  constants as zlibConstants,
-} from "node:zlib";
 import { ofetch } from "ofetch";
 import { RequestBodyError, UpstreamError } from "./server/auth/backend.mjs";
 import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./server/auth/client-ip.mjs";
@@ -25,10 +20,12 @@ import {
   UNEXPECTED_ERROR_BODY,
 } from "./server/backend-response.mjs";
 import { productionHtmlTemplate } from "./server/client-manifest.mjs";
+import { writeContent } from "./server/content.mjs";
 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 requestFailure from "./server/request-failure.mjs";
 import { handleTester } from "./server/tester.mjs";
 import {
@@ -65,10 +62,12 @@ const AUTH_SERVER_ROUTES = [
 ];
 const HTML_RENDER_ROUTE = "/api/html/render";
 const TESTER_ROUTE = /^\/api\/_dms\/tester\/?$/;
+const LOCAL_ROUTES = [
+  [(pathname) => TESTER_ROUTE.test(pathname), handleTester],
+  [isIconRequest, handleIcons],
+];
 const AUTH_PAGE = "/auth";
 const ONBOARDING_PAGE = "/onboarding";
-const MINIMUM_COMPRESSION_BYTES = 1_024;
-const DYNAMIC_BROTLI_QUALITY = 4;
 const SOURCE_TEMPLATE_PATH = join(PROJECT_ROOT, "index.html");
 const BUILT_SSR_RENDERER_PATH = join(PROJECT_ROOT, "dist/ssr/ssr-renderer.js");
 // The SSR bundle keeps vue-i18n external, so Node loads its esm-bundler build,
@@ -282,36 +281,6 @@ function serveAsset(pathname, request, response) {
   return true;
 }
 
-function responseEncoder(request, content) {
-  if (Buffer.byteLength(content) < MINIMUM_COMPRESSION_BYTES) return undefined;
-  const accepted = request.headers["accept-encoding"] ?? "";
-  if (accepted.includes("br"))
-    return {
-      encoding: "br",
-      stream: createBrotliCompress({
-        params: {
-          [zlibConstants.BROTLI_PARAM_QUALITY]: DYNAMIC_BROTLI_QUALITY,
-        },
-      }),
-    };
-  if (accepted.includes("gzip"))
-    return { encoding: "gzip", stream: createGzip() };
-}
-
-async function writeContent(request, response, status, headers, content) {
-  const encoder = responseEncoder(request, content);
-  const vary = [headers.vary, "Accept-Encoding"].filter(Boolean).join(", ");
-  const encodedHeaders = { ...headers, vary };
-  if (!encoder) {
-    response.writeHead(status, encodedHeaders);
-    response.end(content);
-    return;
-  }
-  encodedHeaders["content-encoding"] = encoder.encoding;
-  response.writeHead(status, encodedHeaders);
-  await pipeline(Readable.from([content]), encoder.stream, response);
-}
-
 async function ssrRenderer(devServer) {
   if (devServer) return devServer.ssrLoadModule("/ssr-renderer.ts");
   productionSsrRenderer ??= import(BUILT_SSR_RENDERER_PATH);
@@ -419,7 +388,8 @@ async function writeBackendError(error, request, response) {
 export async function handleRequest(request, response) {
   const url = new URL(request.url, "http://frontend.local");
   const pathname = url.pathname;
-  if (TESTER_ROUTE.test(pathname)) return handleTester(request, response);
+  const localRoute = LOCAL_ROUTES.find(([matches]) => matches(pathname));
+  if (localRoute) return localRoute[1](request, response);
   if (pathname === "/api/_auth/session")
     return handleAuth(request, response, url);
   if (request.method === "POST" && pathname === HTML_RENDER_ROUTE)

package/templates/vue/ui-app-config.ts

@@ -0,0 +1,58 @@
+import { defu } from "defu";
+
+type PlainRecord = Record<string, unknown>;
+
+interface MergeState {
+  pristine: PlainRecord;
+  mergedFrom: object | null;
+}
+
+function isPlainRecord(value: unknown): value is PlainRecord {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+function clonePlain<T>(value: T): T {
+  if (Array.isArray(value)) return value.map(clonePlain) as T;
+  if (!isPlainRecord(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [key, clonePlain(entry)]),
+  ) as T;
+}
+
+function replaceInPlace(target: PlainRecord, source: PlainRecord): void {
+  for (const key of Object.keys(target)) {
+    if (!(key in source)) delete target[key];
+  }
+  Object.assign(target, source);
+}
+
+/**
+ * Merges the DMS app config into Nuxt UI's, which lives for the whole process.
+ * Each DMS config is merged once, so arrays that defu concatenates never pile
+ * up across renders. A new DMS config, after a development reload, replaces
+ * the previous merge: Nuxt UI's object is reset to its own values first, so
+ * changed and removed keys both reach the next server render.
+ */
+export function createUiAppConfigMerger(): (
+  uiAppConfig: PlainRecord,
+  dmsAppConfig: object,
+) => void {
+  const states = new WeakMap<object, MergeState>();
+  return (uiAppConfig, dmsAppConfig) => {
+    let state = states.get(uiAppConfig);
+    if (state === undefined) {
+      state = { pristine: clonePlain({ ...uiAppConfig }), mergedFrom: null };
+      states.set(uiAppConfig, state);
+    }
+    if (state.mergedFrom === dmsAppConfig) return;
+    replaceInPlace(
+      uiAppConfig,
+      defu(clonePlain(dmsAppConfig), clonePlain(state.pristine)),
+    );
+    state.mergedFrom = dmsAppConfig;
+  };
+}

package/templates/vue/vite.config.ts

@@ -4,6 +4,7 @@ import ui from "@nuxt/ui/vite";
 import vue from "@vitejs/plugin-vue";
 import { defineConfig, normalizePath, type Plugin } from "vite";
 import { orderHeadForFirstPaint } from "./head-order.mjs";
+import { iconScanGlobs } from "./icon-scan.mjs";
 
 interface FrontendModuleRegistryEntry {
   id: string;
@@ -128,7 +129,11 @@ export default defineConfig({
     vue(),
     ui({
       router: "inertia",
-      icon: { clientBundle: { scan: true } },
+      icon: {
+        clientBundle: {
+          scan: { globInclude: iconScanGlobs(__dirname, frontendSourceRoots) },
+        },
+      },
       components: { dirs: [] },
       autoImport: {
         dirs: importDirectories,
@@ -183,7 +188,9 @@ export default defineConfig({
     paintBeforeHydrate(),
   ],
   resolve: {
-    dedupe: ["vue", "reka-ui", "@nuxt/ui", "@vueuse/core"],
+    // `@iconify/vue` keeps its API providers in module state: `main.ts` and
+    // Nuxt UI's `Icon` must share one copy for the same-origin provider to apply.
+    dedupe: ["vue", "reka-ui", "@nuxt/ui", "@vueuse/core", "@iconify/vue"],
     alias: {
       "#dms/frontend-module": resolve(__dirname, "frontend-module.ts"),
       "#build/nuxt-icon-client-bundle": "virtual:nuxt-ui-icons",