netjes 0.0.3 → 0.0.4

package/src/payload.ts

@@ -121,6 +121,12 @@ export type PagePayload = {
   basePath?: string;
   /** The request culture, with `AddNetjesLocalization`. */
   locale?: string;
+  /**
+   * Each mounted page package's URL for this request, by npm name, without the base path: `/help`, `/acme/help`, or `/`
+   * for a package mounted at the root. Null when the request has no value for one of the prefix's parameters. Left out
+   * when the app mounts no package.
+   */
+  mounts?: Record<string, string | null>;
   /**
    * Client only, never sent: how far the browser clock is ahead of the server's, measured when the payload arrived.
    * Server timestamps plus this offset are browser timestamps.
@@ -333,6 +339,7 @@ function pagePayload(json: Json): PagePayload {
   if (json.renderedAt !== undefined && json.renderedAt !== null) payload.renderedAt = number(json.renderedAt, 'renderedAt');
   if (json.basePath !== undefined && json.basePath !== null) payload.basePath = string(json.basePath, 'basePath');
   if (json.locale !== undefined && json.locale !== null) payload.locale = string(json.locale, 'locale');
+  if (json.mounts !== undefined && json.mounts !== null) payload.mounts = mounts(json.mounts);
   if (json.draftMode !== undefined && json.draftMode !== null) {
     if (typeof json.draftMode !== 'boolean') fail('draftMode must be a boolean');
     payload.draftMode = json.draftMode;
@@ -340,6 +347,31 @@ function pagePayload(json: Json): PagePayload {
   return payload;
 }
 
+/** A segment a browser resolves away, also when encoded: `.`, `..`, `%2e`, `.%2E` and the like. */
+export function isDotSegment(segment: string): boolean {
+  return /^(?:\.|%2e){1,2}$/i.test(segment);
+}
+
+/**
+ * A mount's URL as the server writes it: `/`, or `/` and segments, none empty or a dot segment, with no query, fragment,
+ * backslash, whitespace or control character. The mounted components put it in front of their hrefs.
+ */
+function mountUrl(value: unknown, what: string): string | null {
+  if (value === null) return null;
+  const url = string(value, what);
+  if (url === '/') return url;
+  const [first, ...segments] = url.split('/');
+  const unsafe = (segment: string) => segment === '' || isDotSegment(segment) || /[?#\\\s\u0000-\u001F\u007F]/.test(segment);
+  if (first !== '' || segments.length === 0 || segments.some(unsafe)) fail(`${what} must be a path of the app, such as /help`);
+  return url;
+}
+
+function mounts(value: unknown): Record<string, string | null> {
+  const result: Record<string, string | null> = {};
+  for (const [name, url] of Object.entries(object(value, 'mounts'))) result[name] = mountUrl(url, `mounts.${name}`);
+  return result;
+}
+
 export function parseNavigationPayload(value: unknown): NavigationPayload {
   const json = object(value, 'payload');
   switch (json.kind) {

package/src/render-document.tsx

@@ -32,7 +32,17 @@ export type RenderDocumentOptions = {
   lang?: string;
   /** What `usePublicConfig()` reads, as the `Netjes:PublicConfig` section. */
   publicConfig?: Record<string, unknown>;
-  /** The page files, keyed `/app/...` as `import.meta.glob` keys them. Default: the app's, from the `netjes()` plugin. */
+  /**
+   * The page packages the app mounts, by npm name, each at its prefix as `MapPagePackage` takes it:
+   * `{ '@acme/help-center': '/(marketing)/help' }`. Their files in the pages map go into the app's folders under the
+   * prefix, so an app page in a package's folder renders inside the package's layouts, and the payload's `mounts` gives
+   * each one's URL for the page's `params`. A package that `netjes({ packages })` does not list has its pages in `app`.
+   */
+  mounts?: Record<string, string>;
+  /**
+   * The page files, keyed `/app/...` as `import.meta.glob` keys them, and a page package's `/<npm name>/<its pages
+   * folder>/...`. Default: the app's and the listed packages', from the `netjes()` plugin.
+   */
   modules?: Record<string, () => Promise<unknown>>;
   /** Stops the render, which then rejects with the signal's reason: for a page that waits on a Promise that never settles. */
   signal?: AbortSignal;
@@ -65,6 +75,65 @@ function list(items: readonly string[]): string {
   return items.length < 2 ? (items[0] ?? '') : `${items.slice(0, -1).join(', ')} and ${items.at(-1) ?? ''}`;
 }
 
+/** A page package mounted at a prefix: the prefix's folders below the app directory (`''` for `/`), and its pages folder. */
+type Mount = { name: string; folder: string; pages: string };
+
+/**
+ * A file of the pages map the server routes: its id, its path in the app directory (a package's under its mount), and
+ * its source, `app` or the package's name.
+ */
+type RoutedFile = { id: string; path: string; source: string };
+
+const PREFIX_SEGMENT = /^(?:[\p{L}\p{N}._~-]+|\[[A-Za-z_][A-Za-z0-9_]*\]|\([\p{L}\p{N}_-]+\))$/u;
+
+/** The mounts of `options.mounts`, with their pages folders from the plugin's list; throws for a prefix MapPagePackage refuses. */
+function mountsOf(mounts: Readonly<Record<string, string>> | undefined, packages: readonly { name: string; pages: string }[]): Mount[] {
+  return Object.entries(mounts ?? {}).map(([name, prefix]) => {
+    const folders = prefix === '/' ? [] : prefix.split('/').slice(1);
+    const refused = (folder: string) => folder === '.' || folder === '..' || isPrivate(folder) || !PREFIX_SEGMENT.test(folder);
+    // A parameter used twice, in any case, as MapPagePackage refuses it.
+    const parameters = folders.filter((folder) => folder.startsWith('[')).map((folder) => folder.toLowerCase());
+    if (!prefix.startsWith('/') || folders.some(refused) || new Set(parameters).size < parameters.length) {
+      throw new Error(
+        `netjes: renderDocument cannot mount '${name}' at '${prefix}': write the prefix as MapPagePackage takes it, ` +
+          "such as '/help', '/(marketing)/help' or '/[tenant]/help'.",
+      );
+    }
+    return { name, folder: folders.join('/'), pages: packages.find((p) => p.name === name)?.pages ?? 'app' };
+  });
+}
+
+/** The files the server routes: the app's where they are, and a mounted package's under its prefix's folders. */
+function routedFiles(files: readonly string[], appDir: string, mounts: readonly Mount[]): RoutedFile[] {
+  return files.flatMap((id): RoutedFile[] => {
+    if (id.startsWith(`${appDir}/`)) return [{ id, path: id, source: 'app' }];
+    const mount = mounts.find((m) => id.startsWith(`${m.name}/${m.pages}/`));
+    if (!mount) return [];
+    const below = id.slice(mount.name.length + mount.pages.length + 2);
+    return [{ id, path: [appDir, mount.folder, below].filter(Boolean).join('/'), source: mount.name }];
+  });
+}
+
+/**
+ * Each mount's URL for these route values, as the server sends it: the literal segments as written and each value
+ * encoded as one segment, or null when a value is missing, a list, empty, `.` or `..`.
+ */
+function mountUrls(mounts: readonly Mount[], params: Params): Record<string, string | null> {
+  // As the server encodes a value (Uri.EscapeDataString), which encodeURIComponent leaves these five unencoded.
+  const encode = (value: string) => encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+  return Object.fromEntries(
+    mounts.map((mount) => {
+      const segments: string[] = [];
+      for (const folder of mount.folder.split('/').filter((f) => f && !isGroup(f))) {
+        const value = folder.startsWith('[') ? params[folder.slice(1, -1)] : folder;
+        if (typeof value !== 'string' || value === '' || value === '.' || value === '..') return [mount.name, null];
+        segments.push(folder.startsWith('[') ? encode(value) : value);
+      }
+      return [mount.name, `/${segments.join('/')}`];
+    }),
+  );
+}
+
 /** A file in the app directory: the folders below the directory and the file's name without its extension; null for any other file. */
 function parse(file: string, appDir: string): { folders: string[]; name: string } | null {
   if (!file.startsWith(`${appDir}/`) || !PAGE_EXTENSION.test(file)) return null;
@@ -75,17 +144,17 @@ function parse(file: string, appDir: string): { folders: string[]; name: string
 
 type AppFiles = {
   /** Each folder's convention files by name, by its path below the app directory (`''` for the directory itself). */
-  folders: Map<string, Map<string, string>>;
+  folders: Map<string, Map<string, RoutedFile>>;
   /** The folders with parallel route slots, each with the first of its slots. */
   slots: Map<string, string>;
 };
 
 /** The convention files the server routes: none in private folders, and the slots that pages and defaults make. */
-function appFiles(files: readonly string[], appDir: string): AppFiles {
-  const folders = new Map<string, Map<string, string>>();
+function appFiles(files: readonly RoutedFile[], appDir: string): AppFiles {
+  const folders = new Map<string, Map<string, RoutedFile>>();
   const slots = new Map<string, string>();
-  for (const file of [...files].sort(ordinal)) {
-    const parsed = parse(file, appDir);
+  for (const file of [...files].sort((a, b) => ordinal(a.id, b.id))) {
+    const parsed = parse(file.path, appDir);
     if (!parsed || parsed.folders.some(isPrivate)) continue;
     const slot = parsed.folders.findIndex(isSlot);
     if (slot >= 0) {
@@ -98,7 +167,12 @@ function appFiles(files: readonly string[], appDir: string): AppFiles {
     const folder = parsed.folders.join('/');
     let conventions = folders.get(folder);
     if (!conventions) folders.set(folder, (conventions = new Map()));
-    if (!conventions.has(parsed.name)) conventions.set(parsed.name, file);
+    const other = conventions.get(parsed.name);
+    // As the server, which refuses two sources' segment files in one folder.
+    if (other && other.source !== file.source && parsed.name !== 'page') {
+      throw new Error(`netjes: renderDocument has two ${parsed.name} files for ${[appDir, folder].filter(Boolean).join('/')}: ${other.id} and ${file.id}.`);
+    }
+    if (!other) conventions.set(parsed.name, file);
   }
   return { folders, slots };
 }
@@ -141,7 +215,7 @@ function segmentsFor(page: string, app: AppFiles, folders: readonly string[], ap
     if (!conventions || !SEGMENT_FILES.some((name) => conventions.has(name))) continue;
     const segment: SegmentRef = { id: folder ? `${appDir}/${folder}` : appDir };
     for (const name of ['layout', 'template', 'loading', 'error'] as const) {
-      const file = conventions.get(name);
+      const file = conventions.get(name)?.id;
       if (file) segment[name] = file;
     }
     if (segment.layout) {
@@ -154,44 +228,66 @@ function segmentsFor(page: string, app: AppFiles, folders: readonly string[], ap
 }
 
 /** Every file renderDocument could render from these: the pages and the boundary files, in ordinal order. */
-function renderable(files: readonly string[], appDir: string): string[] {
+function renderable(files: readonly RoutedFile[], appDir: string): string[] {
   return files
     .filter((file) => {
-      const parsed = parse(file, appDir);
+      const parsed = parse(file.path, appDir);
       if (!parsed || parsed.folders.some((folder) => isPrivate(folder) || isSlot(folder))) return false;
-      return parsed.name === 'page' || (BOUNDARIES.has(parsed.name) && (parsed.name !== 'global-error' || parsed.folders.length === 0));
+      return parsed.name === 'page' || (BOUNDARIES.has(parsed.name) && (parsed.name !== 'global-error' || isRootGlobalError(file, parsed)));
     })
+    .map(({ id }) => id)
     .sort(ordinal);
 }
 
+/** The global error page is the app's own, in the app directory itself; the server refuses one in a package. */
+const isRootGlobalError = (file: RoutedFile, parsed: { folders: string[] }) => file.source === 'app' && parsed.folders.length === 0;
+
 /**
  * The payload the server sends with the document of `page`, a file of the pages map named without its leading slash,
  * for the values in `options`: the route, kind, status and segments by the server's rules, and a build with no
- * stylesheets or scripts. Throws for a file it cannot render: one not in `files`, a layout, or a page in a private
- * folder or under a parallel route slot.
+ * stylesheets or scripts. The files of the page packages `options.mounts` names go under their prefixes, with their
+ * pages folders from `packages`. Throws for a file it cannot render: one not in `files`, a layout, a page in a private
+ * folder or under a parallel route slot, or a file of a package it does not mount.
  */
-export function documentPayload(page: string, options: DocumentOptions, files: readonly string[], appDir: string): InitialPayload {
+export function documentPayload(
+  page: string,
+  options: DocumentOptions,
+  files: readonly string[],
+  appDir: string,
+  packages: readonly { name: string; pages: string }[] = [],
+): InitialPayload {
   const paths = files.map((file) => file.replace(/^\//, ''));
+  const mounts = mountsOf(options.mounts, packages);
+  const routed = routedFiles(paths, appDir, mounts);
   if (!paths.includes(page)) {
     const hint = page.startsWith('/') && paths.includes(page.slice(1))
       ? `; name the file without the leading slash: ${page.slice(1)}.`
-      : `. The files it can render are ${list(renderable(paths, appDir))}.`;
+      : `. The files it can render are ${list(renderable(routed, appDir))}.`;
     throw new Error(`netjes: renderDocument has no ${page} in the pages map${hint}`);
   }
-  const parsed = parse(page, appDir);
-  if (!parsed) throw new Error(`netjes: renderDocument cannot render ${page}, which is not in the app's directory, ${appDir}.`);
+  const file = routed.find((routedFile) => routedFile.id === page);
+  const parsed = file && parse(file.path, appDir);
+  if (!parsed) {
+    const unmounted = packages.find((p) => page.startsWith(`${p.name}/`))?.name;
+    throw new Error(
+      unmounted
+        ? `netjes: renderDocument cannot render ${page}, a file of the page package '${unmounted}', which it does not mount: ` +
+            `pass its prefix as MapPagePackage takes it, as in mounts: { '${unmounted}': '/help' }.`
+        : `netjes: renderDocument cannot render ${page}, which is not in the app's directory, ${appDir}, or in a mounted page package's pages.`,
+    );
+  }
   if (parsed.folders.some(isPrivate)) throw new Error(`netjes: renderDocument cannot render ${page}: a private folder is not routed.`);
   const slot = parsed.folders.findIndex(isSlot);
   if (slot >= 0) throw slotError(page, 'is in', [appDir, ...parsed.folders.slice(0, slot + 1)].join('/'));
   const boundary = BOUNDARIES.get(parsed.name);
-  if ((parsed.name !== 'page' && !boundary) || (parsed.name === 'global-error' && parsed.folders.length > 0)) {
+  if ((parsed.name !== 'page' && !boundary) || (parsed.name === 'global-error' && !isRootGlobalError(file, parsed))) {
     throw new Error(
       `netjes: renderDocument renders a page or a not-found, error, forbidden, unauthorized or global-error file, not ${page}.`,
     );
   }
 
   // The global error page renders without any layout, the others inside the segments down to their own folder.
-  const segments = parsed.name === 'global-error' ? [] : segmentsFor(page, appFiles(paths, appDir), parsed.folders, appDir, options);
+  const segments = parsed.name === 'global-error' ? [] : segmentsFor(page, appFiles(routed, appDir), parsed.folders, appDir, options);
   for (const file of Object.keys(options.layouts ?? {})) {
     if (!segments.some((segment) => segment.layout === file)) {
       const layouts = segments.flatMap((segment) => (segment.layout ? [segment.layout] : []));
@@ -216,6 +312,7 @@ export function documentPayload(page: string, options: DocumentOptions, files: r
     status: options.status ?? boundary?.status ?? 200,
     url: options.url ?? '/',
     version: 'test',
+    ...(mounts.length > 0 ? { mounts: mountUrls(mounts, options.params ?? {}) } : {}),
     document: {
       lang: options.lang ?? 'en',
       assets: { stylesheets: [], modulePreloads: [], scripts: [] },
@@ -294,7 +391,7 @@ export async function renderDocument(page: string, options: RenderDocumentOption
   signal?.throwIfAborted();
   const app = await import('virtual:netjes/pages');
   const pages = modules ?? app.pages;
-  const payload = documentPayload(page, sent, Object.keys(pages), app.appDir);
+  const payload = documentPayload(page, sent, Object.keys(pages), app.appDir, app.packages);
   // Loaded here, so that component tests, which import netjes/testing too, never load react-dom/server.
   const { createServerRenderer } = await import('./server-render.tsx');
   const stream = await createServerRenderer(pages).renderToStream(htmlSafeJson(payload), {

package/src/testing.tsx

@@ -26,6 +26,12 @@ export type TestAppOptions = {
   params?: Params;
   /** What the server would send as `SharedProps`. */
   shared?: unknown;
+  /**
+   * Each mounted page package's URL for the page, by npm name, as the server sends it: `{ '@acme/help-center': '/help' }`,
+   * without the base path, or `null` for a prefix whose value the page has none for. The links, forms and router hooks
+   * of the package's generated file go below it.
+   */
+  mounts?: Record<string, string | null>;
   /** Seeded into the QueryClient the way `PageResult.WithQuery` seeds it, as of now. */
   queries?: ReadonlyArray<{ key: readonly unknown[]; data: unknown }>;
   /**
@@ -183,6 +189,7 @@ export function createTestApp(options: TestAppOptions = {}): TestApp {
         ...(antiforgery ? { antiforgery } : {}),
         ...(options.draftMode ? { draftMode: true } : {}),
         ...(options.locale ? { locale: options.locale } : {}),
+        ...(options.mounts ? { mounts: options.mounts } : {}),
       }),
       [url],
     );

package/src/virtual.d.ts

@@ -1,8 +1,13 @@
 declare module 'virtual:netjes/pages' {
-  /** Every page, layout and other convention file, keyed `/app/...`, as lazy imports. Generated by the netjes Vite plugin. */
+  /**
+   * Every page, layout and other convention file, as lazy imports, keyed by `/` and the file's id: `/app/...` for the
+   * app's, `/<npm name>/<its pages folder>/...` for a page package's. Generated by the netjes Vite plugin.
+   */
   export const pages: Record<string, () => Promise<unknown>>;
   /** The folder of the page files, as the plugin's `appDir` names it: `app`, or e.g. `src/app`. */
   export const appDir: string;
+  /** The page packages `netjes({ packages })` lists, each with the folder of its pages; `[]` when it lists none. */
+  export const packages: ReadonlyArray<{ readonly name: string; readonly pages: string }>;
 }
 
 declare module 'virtual:netjes/query' {

package/template/_AGENTS.md

@@ -12,9 +12,9 @@ How this app is built, for coding agents and the people working with them. It is
 
 | Path | What |
 |---|---|
-| `app/` | Pages, as in the Next.js App Router: `page.tsx` is `/`, `about/page.tsx` is `/about`, `blog/[slug]/page.tsx` is `/blog/{slug}`. `layout.tsx` wraps the pages below it and stays mounted. Netjes renders `<html>`, `<head>` and `<body>` around the root layout, so no layout renders them: the root one returns what goes inside `<body>`. `loading.tsx`, `error.tsx`, `not-found.tsx`, `forbidden.tsx` and `unauthorized.tsx` are boundaries. `(group)` folders add no URL segment, `_private` folders are not routed. `document.test.ts` renders the home page's whole document, as the server sends it, with `renderDocument` from `netjes/testing`. |
+| `app/` | Pages, as in the Next.js App Router: `page.tsx` is `/`, `about/page.tsx` is `/about`, `blog/[slug]/page.tsx` is `/blog/{slug}`. `layout.tsx` wraps the pages below it and stays mounted. Netjes renders `<html>`, `<head>` and `<body>` around the root layout, so no layout renders them: the root one returns what goes inside `<body>`. `loading.tsx`, `error.tsx`, `not-found.tsx`, `forbidden.tsx` and `unauthorized.tsx` are boundaries. `(group)` folders add no URL segment, `_private` folders are not routed. A mounted page package's pages, layouts and boundaries merge into these folders under its prefix, from `node_modules`. `document.test.ts` renders the home page's whole document, as the server sends it, with `renderDocument` from `netjes/testing`. |
 | `Features/` | The C# side, one folder per feature (`namespace __NAME__.Features.Home`): page loaders (`MapPageLoader`), layout loaders (`MapLayoutLoader`), server actions (`MapAction`) and JSON endpoints, with records for what they take and return. Each feature has a `Map...` extension method that `Program.cs` calls. |
-| `Program.cs` | Services and the pipeline: `AddNetjes`, `UseNetjes`, authentication (when you add it), `UseAntiforgery`, each feature's `Map...`, and `app.MapPages()` last. |
+| `Program.cs` | Services and the pipeline: `AddNetjes`, `UseNetjes`, authentication (when you add it), `UseAntiforgery`, each page package's mount and each feature's `Map...`, and `app.MapPages()` last. |
 | `components/` | React components, with their Vitest tests next to them (`*.test.tsx`). |
 <!--netjes:if tests-->
 | `tests/__NAME__.Tests/` | The C# tests: a new test of a loader or an action goes here. In the project `netjes new` writes, on xUnit v3, `AppFactory.cs` runs the real app in memory with `WebApplicationFactory`, with no Node and no client build, and `HomePageTests.cs` requests the home page and posts its form as the client router does. C# for the app does not go in the root folders `tests/` and `e2e/`, which `netjes new` leaves out of the app's build (`DefaultItemExcludes` in `__NAME__.csproj`). |
@@ -22,7 +22,7 @@ How this app is built, for coding agents and the people working with them. It is
 <!--netjes:if e2e-->
 | `e2e/` | Playwright tests, which `npm run test:e2e` runs. The `playwright.config.ts` that `netjes new` writes runs them against the app twice: in Development (the Vite dev server) and in Production (the build). |
 <!--netjes:end-->
-| `generated/netjes.ts` | Generated from the C# types and the page files: zod schemas for page and layout props (`pages`, `layouts`), `sharedProps`, typed `serverActions`, `api` schemas for JSON endpoints, `endpointUrl()` for the URLs of the app's endpoints, `route()` and the `Href` type. Never edit it. |
+| `generated/netjes.ts` | Generated from the C# types and the page files: zod schemas for page and layout props (`pages`, `layouts`), `sharedProps`, typed `serverActions`, `api` schemas for JSON endpoints, `endpointUrl()` for the URLs of the app's endpoints, `route()` and the `Href` type, the pages of mounted page packages included. Never edit it. |
 | `styles/global.css` | Tailwind CSS (`@import 'tailwindcss'`), imported by `app/layout.tsx`. |
 | `public/` | Static files, served at the site root. `favicon.svg` is the Netjes mark, linked by `icons` in the root layout's `metadata`; replace it with the app's own. |
 
@@ -69,6 +69,7 @@ A page without a loader is a plain default export and gets empty props. Forms ca
 - In the TypeScript configs `netjes new` writes, `tsconfig.app.json` checks the app's code without Node's types, so a component or page that reads `process` or imports `node:*` fails `npm run typecheck`. Code that runs only in Node goes in `scripts/`, which `tsconfig.node.json` checks with them; do not add `node` to the `types` of `tsconfig.app.json`.
 - An `error.tsx` renders `error.message` only when `!error.withheld`, and shows `error.status ?? 500` if it shows a status.
 - `Netjes:PublicConfig` is sent to the browser: never put secrets there. So is the route of each endpoint with an `endpointUrl` key, one mapped only in Development included, once any component calls `endpointUrl`: keep secrets out of routes, and authorize on the endpoint ([security](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/security.md#errors-and-configuration)).
+- Page packages (pages, layouts, loaders and actions from an npm and NuGet package pair) are mounted, never copied into `app/`: the package's extension in `Program.cs` before `app.MapPages()`, at a prefix in folder syntax (`app.MapHelpCenter("/help")`, `"/(marketing)/help"`), and the npm name in `netjes({ packages })` in `vite.config.ts`. Install both halves at one version. Its files merge into `app/` folder by folder, so an app page in its folder renders inside its layouts. An app page of the same shape as one of its pages stops the app: replace the package's page with `.Override("/help/contact")` on the mount, reading the props from the package's generated file. Conventions on the mount cover only the package's pages; protect the app's own pages under the prefix as usual. For a package that draws its own shell, keep `app/layout.tsx` to providers and the skip link, and put the site's chrome in `app/(site)/layout.tsx`. Run `npx netjes generate` after updating a package ([page packages](https://github.com/DennisVerhoeven/netjes/blob/main/docs/guides/page-packages.md)).
 - Write the failing test first, then the change.
 
 ## Before you finish