@rocket/js 0.1.1 → 0.2.0

package/src/static-params.js

@@ -0,0 +1,114 @@
+import { PageData } from './PageData.js';
+
+/** @typedef {import('@rocket/js/types.js').Page} Page */
+/** @typedef {import('@rocket/js/types.js').PageRegistry} PageRegistry */
+/** @typedef {import('@rocket/js/types.js').PageStaticParams} PageStaticParams */
+/** @typedef {import('@rocket/js/types.js').PageStaticParamsDeclaration} PageStaticParamsDeclaration */
+
+/**
+ * @param {Page} page
+ */
+export function hasStaticParams(page) {
+  return page.file.endsWith('.js') && page.module.staticParams !== undefined;
+}
+
+/**
+ * @param {string} pagePath
+ */
+export function hasPathParameter(pagePath) {
+  return /(^|\/):[^/]+/.test(pagePath);
+}
+
+/**
+ * Enumerates the concrete output paths of a parameterized static JavaScript
+ * Page from its `staticParams` export.
+ *
+ * @param {{
+ *   pages: PageRegistry;
+ *   page: Page;
+ *   pagePath: string;
+ * }} options
+ * @returns {string[]}
+ */
+export function staticParamsPagePaths({ pages, page, pagePath }) {
+  if (!hasPathParameter(pagePath)) {
+    throw new Error(
+      `Static params for ${page.file} require a parameterized Page path, ` +
+        `but its path ${pagePath} has no route params.`,
+    );
+  }
+  const declaration = /** @type {PageStaticParamsDeclaration} */ (page.module.staticParams);
+  const paramsList =
+    typeof declaration === 'function'
+      ? declaration(new PageData(pages, page.metadata, pagePath))
+      : declaration;
+  if (!Array.isArray(paramsList)) {
+    throw new Error(`Static params for ${page.file} must be an array of route param objects.`);
+  }
+  const paths = [];
+  const seen = new Set();
+  for (const params of paramsList) {
+    const concretePath = substituteRouteParams(pagePath, params, page);
+    if (seen.has(concretePath)) {
+      throw new Error(
+        `Static params for ${page.file} produce the duplicate output path ${concretePath}.`,
+      );
+    }
+    seen.add(concretePath);
+    paths.push(concretePath);
+  }
+  return paths;
+}
+
+/**
+ * @param {string} pagePath
+ * @param {unknown} params
+ * @param {Page} page
+ * @returns {string}
+ */
+function substituteRouteParams(pagePath, params, page) {
+  if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+    throw new Error(`Static params for ${page.file} must be objects with string values.`);
+  }
+  const paramValues = /** @type {Record<string, unknown>} */ (params);
+  const usedNames = new Set();
+  const segments = pagePath.split('/').map(segment => {
+    if (!segment.startsWith(':')) {
+      return segment;
+    }
+    const name = segment.slice(1);
+    usedNames.add(name);
+    return routeParamValue(name, paramValues[name], page);
+  });
+  for (const name of Object.keys(paramValues)) {
+    if (!usedNames.has(name)) {
+      throw new Error(
+        `Static params for ${page.file} set unknown route param "${name}" ` +
+          `for the Page path ${pagePath}.`,
+      );
+    }
+  }
+  return segments.join('/');
+}
+
+/**
+ * @param {string} name
+ * @param {unknown} value
+ * @param {Page} page
+ * @returns {string}
+ */
+function routeParamValue(name, value, page) {
+  if (typeof value !== 'string' || value === '') {
+    throw new Error(
+      `Static params for ${page.file} must provide a non-empty string ` +
+        `for route param "${name}".`,
+    );
+  }
+  if (encodeURIComponent(value) !== value) {
+    throw new Error(
+      `Static params for ${page.file} route param "${name}" value ${JSON.stringify(value)} ` +
+        `is not a URL-safe path segment. Slugify param values before returning them.`,
+    );
+  }
+  return value;
+}

package/src/transform.js

@@ -90,10 +90,7 @@ export async function mdToJsSingleDemo(md, demo) {
 
   const code = /** @type {{client: string; server: string}} */ (result.data.code);
 
-  let litImport = "import { html } from 'lit'";
-  if (/import\s*?{(?:\n|.)*?html(\n|.)*}.*/m.test(code.server)) {
-    litImport = '';
-  }
+  const litImport = hasTopLevelHtmlBinding(code.server) ? '' : "import { html } from 'lit'";
   const moduleCode = `
 import {render} from '@lit-labs/ssr';
 ${litImport}
@@ -119,11 +116,10 @@ export function contentFn(data, layout) {
  * @returns {Promise<string>}
  */
 async function makeJsFile(serverCode, clientCode, markdown, headlines) {
-  let litImport = "import { html } from 'lit'";
   const normalizedServerCode = normalizeLayoutExportBindings(serverCode);
-  if (/import\s*?{(?:\n|.)*?html(\n|.)*}.*/m.test(normalizedServerCode)) {
-    litImport = '';
-  }
+  const litImport = hasTopLevelHtmlBinding(normalizedServerCode)
+    ? ''
+    : "import { html } from 'lit'";
   return `
 import {render} from '@lit-labs/ssr';
 ${litImport}
@@ -145,6 +141,56 @@ export function contentFn(data, defaultLayout) {
 }`;
 }
 
+/**
+ * The generated Markdown module wraps the page content in a lit `html` template, so it must inject
+ * `import { html } from 'lit'` unless the Page's server code already provides a top-level `html`
+ * binding (an import binding or a top-level declaration).
+ *
+ * @param {string} code
+ * @returns {boolean}
+ */
+function hasTopLevelHtmlBinding(code) {
+  if (typeof code !== 'string' || code === '') {
+    return false;
+  }
+  const sourceFile = ts.createSourceFile(
+    'page-server.js',
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.JS,
+  );
+  for (const statement of sourceFile.statements) {
+    if (ts.isImportDeclaration(statement) && statement.importClause) {
+      const { name, namedBindings } = statement.importClause;
+      if (name?.text === 'html') {
+        return true;
+      }
+      if (namedBindings) {
+        if (ts.isNamespaceImport(namedBindings)) {
+          if (namedBindings.name.text === 'html') {
+            return true;
+          }
+        } else if (namedBindings.elements.some(element => element.name.text === 'html')) {
+          return true;
+        }
+      }
+    } else if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name) && declaration.name.text === 'html') {
+          return true;
+        }
+      }
+    } else if (
+      (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) &&
+      statement.name?.text === 'html'
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Direct ESM re-exports do not create local bindings, but the generated Markdown module calls the
  * selected layout from inside contentFn. Rewriting only direct `layout` re-exports keeps the public
@@ -242,8 +288,7 @@ function parseDemos() {
       codePreview.visited = true;
       codePreview.meta = demoCodeBlockMeta(node.meta);
       const code = node.value;
-      const parsed = parseExports(code);
-      const name = parsed[1][0].ln || parsed[1][0].n;
+      const name = demoExportName(code);
       // we transform a code node into a root node, so cast
       const rootNode = /** @type {import('mdast').Root} */ (/** @type {unknown} */ (node));
       rootNode.type = 'root';
@@ -357,10 +402,26 @@ function isRequestDemoCodeNode(node) {
 /**
  * @param {import('mdast').Code} node
  */
-function isDemoCodeNode(node) {
+export function isDemoCodeNode(node) {
   return node.lang === 'js' && /(?:^|\s)demo(?:\s|$)/.test(node.meta || '');
 }
 
+/**
+ * @param {string} code
+ * @returns {string}
+ */
+function demoExportName(code) {
+  const [, moduleExports] = parseExports(code);
+  const name = moduleExports[0] && (moduleExports[0].ln || moduleExports[0].n);
+  if (!name) {
+    throw new Error(
+      'A ```js demo code block must export the demo function, ' +
+        'e.g. "export const myDemo = () => html`...`".',
+    );
+  }
+  return name;
+}
+
 /**
  * @param {string | null | undefined} meta
  */
@@ -400,8 +461,7 @@ function extractSingleDemo(demoName) {
       codePreview.visited = true;
       codePreview.meta = demoCodeBlockMeta(node.meta);
       const code = node.value;
-      const parsed = parseExports(code);
-      const name = parsed[1][0].ln || parsed[1][0].n;
+      const name = demoExportName(code);
       if (name !== demoName) {
         return;
       }
@@ -596,17 +656,24 @@ function readStringProperty(value) {
  */
 function escapeOutsideTemplates(string) {
   let result = '';
-  let templateLevels = 0;
+  let braceDepth = 0;
   for (let i = 0; i < string.length; i++) {
-    if (string[i] === '$' && string[i + 1] === '{' && string[i - 1] !== '\\') {
-      templateLevels++;
-    } else if (templateLevels && string[i] === '}') {
-      templateLevels--;
-    }
-    if (templateLevels) {
-      result += string[i];
-    } else {
+    if (braceDepth === 0) {
+      if (string[i] === '$' && string[i + 1] === '{' && string[i - 1] !== '\\') {
+        braceDepth = 1;
+        result += '${';
+        i++;
+        continue;
+      }
       result += string[i].replace('\\', '\\\\').replace('`', '\\`');
+    } else {
+      // Track nested braces so expressions like `${ fn({ a: 1 }) }` stay intact.
+      if (string[i] === '{') {
+        braceDepth++;
+      } else if (string[i] === '}') {
+        braceDepth--;
+      }
+      result += string[i];
     }
   }
 

package/src/wds-plugin.js

@@ -6,7 +6,8 @@ import fs from 'node:fs';
 import { debounce } from './debounce.js';
 import path from 'node:path';
 import { createIconAssetStore, rocketIconRuntimeOutputs } from './icons.js';
-import { createDevelopmentPageModuleLoader } from './development-page-module-loader.js';
+import { createPageModuleLoader } from './page-module-loader.js';
+import { matchPageFeedPath } from './feeds.js';
 import { PageRuntime, PageRuntimeError } from './page-runtime.js';
 import {
   PUBLIC_ASSETS_DIR,
@@ -23,6 +24,9 @@ let pageRegistry = new Map();
 /** @type {Map<string, Set<string>>} */
 let modules = new Map();
 
+/** @type {import('./publicAssets.js').PublicAsset[] | null} */
+let cachedPublicAssets = null;
+
 /** @typedef {import('@rocket/js/types.js').UrlLifecycleConfig} UrlLifecycleConfig */
 /** @typedef {{ urlLifecycle?: UrlLifecycleConfig; siteHeadMetadata?: import('@rocket/js/types.js').SiteHeadMetadataConfig; siteOrigin?: string; siteDiscoverability?: import('@rocket/js/types.js').SiteDiscoverabilityConfig; iconLibraries?: import('@rocket/js/types.js').IconLibrariesConfig; defaultIconLibrary?: string; captureSocialPreviewImage?: import('./socialPreviewImages.js').SocialPreviewCapture; watch?: boolean }} RocketDevServerPluginOptions */
 /** @typedef {RocketDevServerPluginOptions | UrlLifecycleConfig} RocketDevServerPluginInput */
@@ -84,6 +88,10 @@ export default (include, exclude, resolverPort, options = {}) => {
       const publicDir = path.join(process.cwd(), PUBLIC_ASSETS_DIR);
       if (watchEnabled && fs.existsSync(publicDir)) {
         fileWatcher?.add(publicDir);
+        // re-discover and re-validate Public Assets on the next request
+        fileWatcher?.on?.('all', () => {
+          cachedPublicAssets = null;
+        });
       }
     },
     serverStop() {
@@ -128,7 +136,7 @@ export default (include, exclude, resolverPort, options = {}) => {
           type: 'image/svg+xml',
         };
       }
-      const publicAssets = validateDevelopmentPublicAssets(pluginOptions);
+      const publicAssets = cachedPublicAssets ?? validateDevelopmentPublicAssets(pluginOptions);
       const publicAsset = findPublicAsset(publicAssets, context.path);
       if (publicAsset) {
         return /** @type {any} */ ({
@@ -151,6 +159,10 @@ export default (include, exclude, resolverPort, options = {}) => {
       } else if (context.header.accept === '*/*') {
         isPage = false;
       }
+      // Feed readers fetch Page Feeds without document Accept headers.
+      if (!isPage && matchPageFeedPath(context.path, pageRegistry)) {
+        isPage = true;
+      }
       if (!isPage) {
         const pathname = new URLPattern().exec(context.header.referer)?.pathname.input;
         if (!pathname) {
@@ -196,6 +208,7 @@ function validateDevelopmentPublicAssets(pluginOptions) {
     }),
     emitRedirectFallbacks: false,
   });
+  cachedPublicAssets = publicAssets;
   return publicAssets;
 }
 
@@ -222,7 +235,7 @@ async function renderPageRuntime(
 ) {
   const pageRuntime = new PageRuntime({
     pages: pageRegistry,
-    pageModuleLoader: createDevelopmentPageModuleLoader(),
+    pageModuleLoader: createPageModuleLoader(),
     urlLifecycle,
     siteHeadMetadata,
     siteOrigin,

package/dist-types/src/development-page-module-loader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"development-page-module-loader.d.ts","sourceRoot":"","sources":["../../src/development-page-module-loader.js"],"names":[],"mappings":"AAGA,6FAA6F;AAE7F;IAEI;;OAEG;4BADQ,uBAAuB;;;;;;;EAoBrC;sCAzBa,OAAO,mBAAmB,EAAE,uBAAuB"}

package/dist-types/src/static-page-module-loader.d.ts

@@ -1,15 +0,0 @@
-/** @typedef {import('./page-runtime.js').PageModuleLoaderOptions} PageModuleLoaderOptions */
-export function createStaticPageModuleLoader(): {
-    /**
-     * @param {PageModuleLoaderOptions} options
-     */
-    load({ page, variant }: PageModuleLoaderOptions): Promise<{
-        kind: "markdown";
-        contentFn: unknown;
-    } | {
-        kind: "javascript";
-        body: unknown;
-    }>;
-};
-export type PageModuleLoaderOptions = import("./page-runtime.js").PageModuleLoaderOptions;
-//# sourceMappingURL=static-page-module-loader.d.ts.map

package/dist-types/src/static-page-module-loader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"static-page-module-loader.d.ts","sourceRoot":"","sources":["../../src/static-page-module-loader.js"],"names":[],"mappings":"AAGA,6FAA6F;AAE7F;IAEI;;OAEG;4BADQ,uBAAuB;;;;;;;EAoBrC;sCAzBa,OAAO,mBAAmB,EAAE,uBAAuB"}

package/src/development-page-module-loader.js

@@ -1,29 +0,0 @@
-import { normalizeLoadedPageModule } from './loaded-page-module.js';
-import { parseComponents } from './components.js';
-
-/** @typedef {import('./page-runtime.js').PageModuleLoaderOptions} PageModuleLoaderOptions */
-
-export function createDevelopmentPageModuleLoader() {
-  return {
-    /**
-     * @param {PageModuleLoaderOptions} options
-     */
-    async load({ page, variant }) {
-      if (!page.file.endsWith('.js')) {
-        const importAttributes = { type: 'rocketLoadMdInitial' };
-        if (typeof variant === 'object' && variant.kind === 'standalone-demo') {
-          Object.assign(importAttributes, { singleDemo: variant.demoName });
-        }
-        const module = await import(`./${page.file}`, {
-          with: importAttributes,
-        });
-        return normalizeLoadedPageModule({ kind: 'markdown', module, parseComponents });
-      }
-
-      const module = await import(`./${page.file}`, {
-        with: { type: 'rocketLoadJsInitial' },
-      });
-      return normalizeLoadedPageModule({ kind: 'javascript', module });
-    },
-  };
-}