@rocket/js 0.1.1 → 0.2.0

package/src/menu.js

@@ -34,13 +34,14 @@ export function treeFromPages(pages) {
       continue;
     }
     const parts = getMenuParts(url, module);
+    if (parts.some(part => part.startsWith(':'))) {
+      // Dynamic paths have no single public URL, so they get no menu entry.
+      continue;
+    }
     let obj = children;
     /** @type {any} */
     let last = {};
     for (const part of parts) {
-      if (part.startsWith(':')) {
-        break;
-      }
       const get = obj.find(leaf => leaf.name === part);
       if (!get) {
         /** @type {import('@rocket/js/types.js').PageTree[]} */
@@ -137,19 +138,25 @@ function sortRecursive(children) {
 }
 
 /**
+ * The itemFn receives the rendered child list (or lit `nothing`) and must place
+ * it inside the returned item so nested lists stay valid HTML.
+ *
  * @param {import("@rocket/js/types.js").PageTree} tree
  * @param {string} listTagName
- * @param {(name: string, url: string, module: import("@rocket/js/types.js").Module, linkText: string) => import("lit").TemplateResult} itemFn
+ * @param {(name: string, url: string, module: import("@rocket/js/types.js").Module, linkText: string, children: import("lit").TemplateResult | typeof nothing) => import("lit").TemplateResult} itemFn
+ * @returns {import("lit").TemplateResult}
  */
 export function treeToHtml(tree, listTagName, itemFn) {
   return html`${unsafeHTML(`<${listTagName}>`)}${join(
-    tree.children.map(page => {
-      let a = itemFn(page.name, page.url, page.module, page.linkText);
-      if (page.children.length) {
-        a = html`${a}${treeToHtml(page, listTagName, itemFn)}`;
-      }
-      return a;
-    }),
+    tree.children.map(page =>
+      itemFn(
+        page.name,
+        page.url,
+        page.module,
+        page.linkText,
+        page.children.length ? treeToHtml(page, listTagName, itemFn) : nothing,
+      ),
+    ),
     nothing,
   )}${unsafeHTML(`</${listTagName}>`)}`;
 }
@@ -158,14 +165,13 @@ export function treeToHtml(tree, listTagName, itemFn) {
  * @param {import('@rocket/js/types.js').PageTree} pageTree
  */
 export function defaultHtmlMenu(pageTree) {
-  return treeToHtml(
-    pageTree,
-    'ul',
-    (_name, url, _module, linkText) =>
-      html`<li>
-        <a href=${url}>${linkText}</a>
-      </li>`,
-  );
+  return treeToHtml(pageTree, 'ul', (_name, url, module, linkText, children) => {
+    const menu = module.config.menu;
+    const noLink = !url || menu === false || (typeof menu === 'object' && menu?.noLink);
+    return html`<li>
+      ${noLink ? html`<span>${linkText}</span>` : html`<a href=${url}>${linkText}</a>`}${children}
+    </li>`;
+  });
 }
 
 /** Runs on: import-hook */

package/src/menus/MainMenu.js

@@ -32,15 +32,21 @@ export class MainMenu extends LitElement {
    */
   list(page, depth = 0) {
     const title = page.linkText;
+    const isCurrent = page.url === this.currentPath;
     /** @type {any} */
-    const classes = { current: page.url === this.currentPath };
+    const classes = { current: isCurrent };
     const level = `lvl-${depth}`;
     classes[level] = true;
     return html`
       <li>
-        <a href=${ifDefined(page.menuNoLink ? undefined : page.url)} class=${classMap(classes)}
-          >${title}</a
-        >
+        ${page.menuNoLink
+          ? html`<span class=${classMap(classes)}>${title}</span>`
+          : html`<a
+              href=${ifDefined(page.url)}
+              class=${classMap(classes)}
+              aria-current=${ifDefined(isCurrent ? 'page' : undefined)}
+              >${title}</a
+            >`}
         ${page.children.length > 0
           ? html`<ul>
               ${page.children.map(child => this.list(child, depth + 1))}

package/src/{static-page-module-loader.js → page-module-loader.js}

@@ -3,7 +3,12 @@ import { parseComponents } from './components.js';
 
 /** @typedef {import('./page-runtime.js').PageModuleLoaderOptions} PageModuleLoaderOptions */
 
-export function createStaticPageModuleLoader() {
+/**
+ * The Page Module Loader used by both the development server and static builds.
+ * Loading goes through Rocket's import hooks, which behave the same in both
+ * runtime environments.
+ */
+export function createPageModuleLoader() {
   return {
     /**
      * @param {PageModuleLoaderOptions} options

package/src/page-pagination.js

@@ -1,4 +1,4 @@
-import { URLPattern } from 'urlpattern-polyfill';
+import { routePattern } from './route-pattern.js';
 import { PageData } from './PageData.js';
 import { normalizeDocumentPath } from './standalone-demo-url.js';
 
@@ -229,7 +229,7 @@ function parsePaginatedArchivePath(pathname) {
  * @param {string} routePath
  */
 function matchPagePath(pathname, origin, routePath) {
-  const pattern = new URLPattern({ pathname: routePath });
+  const pattern = routePattern(routePath);
   return pattern.exec(pathname, origin);
 }
 

package/src/page-runtime.js

@@ -1,9 +1,10 @@
 import { collectResult } from '@lit-labs/ssr/lib/render-result.js';
-import { URLPattern } from 'urlpattern-polyfill';
+import { routePattern } from './route-pattern.js';
 import { layout, singleDemoLayout } from './layouts/layout.js';
 import { PageData } from './PageData.js';
 import { finalizeRocketIcons } from './icons.js';
 import { matchPaginatedArchivePath, pageDataWithPagination } from './page-pagination.js';
+import { createPageFeed, matchPageFeedPath } from './feeds.js';
 import { matchStandaloneDemoUrl } from './standalone-demo-url.js';
 
 /** @typedef {import('@rocket/js/types.js').PageRegistry} PageRegistry */
@@ -86,6 +87,14 @@ export class PageRuntime {
       });
     }
 
+    // A configured Page at the exact request path always wins over a Page Feed.
+    const feedMatch = this.pages.has(url.pathname)
+      ? null
+      : matchPageFeedPath(url.pathname, this.pages);
+    if (feedMatch) {
+      return this.renderPageFeed(feedMatch, url.origin);
+    }
+
     const pageMatch = findPage(url.pathname, url.origin, this.pages);
     if (!pageMatch) {
       return new Response('Page not found', { status: 404 });
@@ -134,11 +143,47 @@ export class PageRuntime {
       });
     }
 
-    throw new Error('Unsupported Page module kind');
+    throw new PageRuntimeError(
+      'INVALID_PAGE_MODULE',
+      `Unsupported Page module kind for ${pageMatch.routePath}`,
+      { page: pageMatch.page, routePath: pageMatch.routePath },
+    );
+  }
+
+  /**
+   * Development falls back to the request origin so Page Feeds work before a
+   * Site Origin is configured; builds always pass the configured Site Origin.
+   *
+   * @param {{ page: Page; routePath: string }} feedMatch
+   * @param {string} requestOrigin
+   */
+  renderPageFeed(feedMatch, requestOrigin) {
+    /** @type {string} */
+    let feed;
+    try {
+      feed = createPageFeed({
+        pages: this.pages,
+        page: feedMatch.page,
+        pagePath: feedMatch.routePath,
+        siteOrigin: this.siteOrigin || requestOrigin,
+      });
+    } catch (error) {
+      throw new PageRuntimeError(
+        'PAGE_RENDER_FAILED',
+        `Failed to render Page Feed for ${feedMatch.page.file}`,
+        { cause: error, page: feedMatch.page, routePath: feedMatch.routePath },
+      );
+    }
+    return new Response(feed, {
+      headers: { 'content-type': 'application/atom+xml; charset=utf-8' },
+    });
   }
 }
 
 /**
+ * Redirect sources intentionally match the request path exactly (no
+ * trailing-slash normalization) so authors control both URL forms explicitly.
+ *
  * @param {string} pathname
  * @param {RedirectConfig[] | undefined} redirects
  */
@@ -466,7 +511,7 @@ function archivePageNumber(variant) {
  * @param {string} routePath
  */
 function matchPagePath(pathname, origin, routePath) {
-  const pattern = new URLPattern({ pathname: routePath });
+  const pattern = routePattern(routePath);
   return pattern.exec(pathname, origin);
 }
 

package/src/pages.js

@@ -21,56 +21,49 @@ export async function getPages(root, include, exclude) {
     cwd: root,
     exclude: ignoreFn(exclude),
   })) {
-    if (file.endsWith('.rocket.md')) {
-      const module = await tryImport(`./${p.relative(process.cwd(), file)}`);
-      const path = module.config?.path;
-      if (!path) {
-        throw new Error('No path found in file: ' + file);
-      }
-      if (pages.has(path)) {
-        throw new Error(
-          'Duplicate path found: ' + path + ', used in ' + file + ' and ' + pages.get(path)?.file,
-        );
-      }
-      const normalizedModule = normalizePageModule(file, module);
+    const kind = file.endsWith('.rocket.md')
+      ? 'md'
+      : file.endsWith('.rocket.js')
+        ? 'js'
+        : undefined;
+    if (!kind) {
+      continue;
+    }
+    const specifier = `./${p.relative(process.cwd(), p.resolve(root, file))}`;
+    /** @type {import('@rocket/js/types.js').Module} */
+    const module =
+      kind === 'md'
+        ? await tryImport(specifier)
+        : await import(specifier, { with: { type: 'rocketSetupJsInitial' } });
+    const path = module.config?.path;
+    if (!path) {
+      throw new Error('No path found in file: ' + file);
+    }
+    if (pages.has(path)) {
+      throw new Error(
+        'Duplicate path found: ' + path + ', used in ' + file + ' and ' + pages.get(path)?.file,
+      );
+    }
+    const normalizedModule = normalizePageModule(file, module);
+    if (kind === 'md') {
       validateMarkdownPageComponents(file, normalizedModule);
-      const linkText =
-        (normalizedModule.config.menu === false
-          ? undefined
-          : normalizedModule.config.menu?.linkText) || normalizedModule._$menuLinkText$;
-      const metadataConfig = normalizePageMetadataConfig(file, normalizedModule.config.metadata);
-      const title = metadataConfig.title || module._$title$ || linkText || titleFromPath(path);
-      pages.set(path, {
-        file,
-        module: normalizedModule,
-        metadata: pageMetadata(title, linkText, metadataConfig),
-        demoNames: normalizedModule._$demoNames$ || [],
-      });
-    } else if (file.endsWith('.rocket.js')) {
-      /** @type {import('@rocket/js/types.js').Module} */
-      const module = await import(`./${p.relative(process.cwd(), file)}`, {
-        with: { type: 'rocketSetupJsInitial' },
-      });
-      const path = module.config?.path;
-      if (!path) {
-        throw new Error('No path found in file: ' + file);
-      }
-      if (pages.has(path)) {
-        throw new Error(
-          'Duplicate path found: ' + path + ', used in ' + file + ' and ' + pages.get(path)?.file,
-        );
-      }
-      const normalizedModule = normalizePageModule(file, module);
-      const linkText =
-        normalizedModule.config.menu === false ? undefined : normalizedModule.config.menu?.linkText;
-      const metadataConfig = normalizePageMetadataConfig(file, normalizedModule.config.metadata);
-      const title = metadataConfig.title || linkText || titleFromPath(path);
-      pages.set(path, {
-        file,
-        module: normalizedModule,
-        metadata: pageMetadata(title, linkText, metadataConfig),
-      });
     }
+    const configLinkText =
+      normalizedModule.config.menu === false ? undefined : normalizedModule.config.menu?.linkText;
+    const linkText =
+      kind === 'md' ? configLinkText || normalizedModule._$menuLinkText$ : configLinkText;
+    const metadataConfig = normalizePageMetadataConfig(file, normalizedModule.config.metadata);
+    const title =
+      metadataConfig.title ||
+      (kind === 'md' ? module._$title$ : undefined) ||
+      linkText ||
+      titleFromPath(path);
+    pages.set(path, {
+      file,
+      module: normalizedModule,
+      metadata: pageMetadata(title, linkText, metadataConfig),
+      ...(kind === 'md' ? { demoNames: normalizedModule._$demoNames$ || [] } : {}),
+    });
   }
   return pages;
 }
@@ -448,10 +441,11 @@ function ignoreFn(exclude) {
    * @param {string} path
    */
   return function (path) {
+    if (path.includes('node_modules')) {
+      return true;
+    }
     for (const pattern of exclude) {
-      if (path.includes('node_modules')) {
-        return true;
-      } else if (typeof pattern === 'string') {
+      if (typeof pattern === 'string') {
         if (path.includes(pattern)) return true;
       } else {
         if (pattern.test(path)) return true;
@@ -466,12 +460,9 @@ function ignoreFn(exclude) {
  * @returns {string}
  */
 function titleFromPath(path) {
-  const parts = path.split('/');
+  const parts = path.split('/').filter(Boolean);
   const last = parts.findLast(part => !part.startsWith(':'));
-  if (!last) {
-    return parts[0] ? capitalize(parts[0].slice(1)) : 'Home';
-  }
-  return capitalize(last);
+  return last ? capitalize(last) : 'Home';
 }
 
 /**

package/src/publicAssets.js

@@ -1,6 +1,6 @@
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { URLPattern } from 'urlpattern-polyfill';
+import { routePattern } from './route-pattern.js';
 import { paginatedArchivePaths } from './page-pagination.js';
 import { normalizeDocumentPath, standaloneDemoPaths } from './standalone-demo-url.js';
 import { needsDefaultSocialPreviewImage, publicSocialPreviewPages } from './socialPreviewImages.js';
@@ -250,7 +250,7 @@ function generatedOutputClaims({ pages, generatedPages, config, emitRedirectFall
  */
 function matchingPage(requestPath, pages) {
   for (const [routePath, page] of pages) {
-    const pattern = new URLPattern({ pathname: routePath });
+    const pattern = routePattern(routePath);
     if (pattern.exec(requestPath, 'http://localhost')) {
       return { routePath, page };
     }

package/src/route-pattern.js

@@ -0,0 +1,21 @@
+/** Runs on: server */
+import { URLPattern } from 'urlpattern-polyfill';
+
+/** @type {Map<string, URLPattern>} */
+const patterns = new Map();
+
+/**
+ * Compiling a URLPattern is comparatively expensive and route paths repeat on
+ * every request, so compiled patterns are cached per route path.
+ *
+ * @param {string} routePath
+ * @returns {URLPattern}
+ */
+export function routePattern(routePath) {
+  let pattern = patterns.get(routePath);
+  if (!pattern) {
+    pattern = new URLPattern({ pathname: routePath });
+    patterns.set(routePath, pattern);
+  }
+  return pattern;
+}

package/src/siteDiscoverability.js

@@ -5,6 +5,7 @@ import {
   paginatedArchivePath,
   paginatedArchivePaths,
 } from './page-pagination.js';
+import { hasStaticParams, staticParamsPagePaths } from './static-params.js';
 
 /**
  * @param {{
@@ -55,6 +56,10 @@ export function createSitemap({ pages, siteOrigin }) {
 }
 
 /**
+ * The Robots File always references the canonical Sitemap URL, even when
+ * Rocket does not generate `sitemap.xml` itself — this is documented behavior
+ * so projects can supply a sitemap through other tooling.
+ *
  * @param {{
  *   pages?: import('@rocket/js/types.js').PageRegistry;
  *   siteOrigin: string;
@@ -82,7 +87,12 @@ export function createRobotsFile({ pages = new Map(), siteOrigin }) {
 function sitemapPageLocations({ pages, siteOrigin }) {
   return Array.from(pages.entries())
     .filter(([pagePath, page]) => {
-      return !hasPathParameter(pagePath) && page.module.config.discoverability?.sitemap !== false;
+      // Parameterized Pages join the Sitemap only when static params enumerate
+      // their public URLs.
+      return (
+        (!hasPathParameter(pagePath) || hasStaticParams(page)) &&
+        page.module.config.discoverability?.sitemap !== false
+      );
     })
     .flatMap(([pagePath, page]) => discoverabilityPagePaths({ pages, pagePath, page }))
     .map(pagePath => absolutePageUrl(siteOrigin, pagePath))
@@ -108,6 +118,9 @@ function robotsDisallowPaths({ pages }) {
  * }} options
  */
 function discoverabilityPagePaths({ pages, pagePath, page }) {
+  if (hasStaticParams(page)) {
+    return staticParamsPagePaths({ pages, page, pagePath });
+  }
   if (!hasPagePagination(page)) {
     return [pagePath];
   }

package/src/socialPreviewImages.js

@@ -57,7 +57,7 @@ export async function generateStaticDefaultSocialPreviewImages({
   siteHeadMetadata,
   siteOrigin,
   cacheDirectory,
-  captureSocialPreviewImage = captureSocialPreviewImageWithBrowser,
+  captureSocialPreviewImage,
 }) {
   /** @type {Map<string, DefaultSocialPreviewImageOutput>} */
   const outputs = new Map();
@@ -71,6 +71,43 @@ export async function generateStaticDefaultSocialPreviewImages({
     );
   }
 
+  // Launching Chromium costs seconds; share one browser across all uncached captures.
+  /** @type {import('puppeteer-core').Browser | undefined} */
+  let sharedBrowser;
+  /** @type {SocialPreviewCapture} */
+  const capture =
+    captureSocialPreviewImage ??
+    (async ({ html }) => {
+      sharedBrowser ??= await puppeteer.launch(await createSocialPreviewBrowserLaunchOptions());
+      return renderSocialPreviewImage(html, sharedBrowser);
+    });
+
+  try {
+    await generateInto({ outputs, pages, siteHeadMetadata, siteOrigin, cacheDirectory, capture });
+  } finally {
+    await sharedBrowser?.close();
+  }
+  return outputs;
+}
+
+/**
+ * @param {{
+ *   outputs: Map<string, DefaultSocialPreviewImageOutput>;
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   siteHeadMetadata: import('@rocket/js/types.js').SiteHeadMetadataConfig;
+ *   siteOrigin: string;
+ *   cacheDirectory?: string;
+ *   capture: SocialPreviewCapture;
+ * }} options
+ */
+async function generateInto({
+  outputs,
+  pages,
+  siteHeadMetadata,
+  siteOrigin,
+  cacheDirectory,
+  capture,
+}) {
   for (const [pagePath, page] of pages) {
     if (!needsDefaultSocialPreviewImage({ pagePath, page, siteHeadMetadata })) {
       continue;
@@ -101,7 +138,7 @@ export async function generateStaticDefaultSocialPreviewImages({
     }
 
     try {
-      const data = await captureSocialPreviewImage({
+      const data = await capture({
         html,
         width: DEFAULT_SOCIAL_PREVIEW_IMAGE_WIDTH,
         height: DEFAULT_SOCIAL_PREVIEW_IMAGE_HEIGHT,
@@ -121,7 +158,6 @@ export async function generateStaticDefaultSocialPreviewImages({
       );
     }
   }
-  return outputs;
 }
 
 /**
@@ -332,34 +368,39 @@ export async function captureSocialPreviewImageWithBrowser({ html }) {
 
 /**
  * @param {string} html
+ * @param {import('puppeteer-core').Browser} [existingBrowser] reused across captures; the caller owns closing it
  * @returns {Promise<Buffer>}
  */
-export async function renderSocialPreviewImage(html) {
-  /** @type {import('puppeteer-core').Browser | undefined} */
-  let browser;
+export async function renderSocialPreviewImage(html, existingBrowser) {
+  const browser =
+    existingBrowser ?? (await puppeteer.launch(await createSocialPreviewBrowserLaunchOptions()));
+  /** @type {import('puppeteer-core').Page | undefined} */
+  let page;
   try {
-    browser = await puppeteer.launch(await createSocialPreviewBrowserLaunchOptions());
-    const page = await browser.newPage();
-    await page.setViewport({
+    const capturePage = await browser.newPage();
+    page = capturePage;
+    await capturePage.setViewport({
       width: DEFAULT_SOCIAL_PREVIEW_IMAGE_WIDTH,
       height: DEFAULT_SOCIAL_PREVIEW_IMAGE_HEIGHT,
       deviceScaleFactor: 1,
     });
 
     await runSocialPreviewCaptureStep('set Social Preview HTML content', () =>
-      page.setContent(html, { waitUntil: 'load' }),
+      capturePage.setContent(html, { waitUntil: 'load' }),
     );
     await runSocialPreviewCaptureStep('wait for Social Preview fonts', () =>
-      page.evaluateHandle('document.fonts.ready'),
+      capturePage.evaluateHandle('document.fonts.ready'),
     );
     const screenshot = await runSocialPreviewCaptureStep('capture Social Preview screenshot', () =>
-      page.screenshot({
+      capturePage.screenshot({
         type: 'png',
       }),
     );
     return Buffer.from(screenshot);
   } finally {
-    if (browser) {
+    if (existingBrowser) {
+      await page?.close();
+    } else {
       await browser.close();
     }
   }
@@ -401,7 +442,21 @@ export async function resolveSocialPreviewBrowserExecutablePath({
     return explicitPath;
   }
   if (platform === 'linux') {
-    return chromiumExecutablePath();
+    // Prefer the bundled serverless Chromium (CI/deploy targets); fall back to
+    // a locally installed browser on regular Linux machines.
+    try {
+      return await chromiumExecutablePath();
+    } catch (error) {
+      const localBrowserPath = findLocalBrowserExecutable({ platform, env, fileExists });
+      if (localBrowserPath) {
+        return localBrowserPath;
+      }
+      throw new Error(
+        `Unable to resolve a browser for Social Preview Capture. ` +
+          `Install Google Chrome or set PUPPETEER_EXECUTABLE_PATH to a Chromium-compatible browser.`,
+        { cause: error },
+      );
+    }
   }
   const localBrowserPath = findLocalBrowserExecutable({ platform, env, fileExists });
   if (localBrowserPath) {
@@ -431,6 +486,17 @@ function findLocalBrowserExecutable({ platform, env, fileExists }) {
       '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
     );
   }
+  if (platform === 'linux') {
+    paths.push(
+      '/usr/bin/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/chromium',
+      '/usr/bin/chromium-browser',
+      '/snap/bin/chromium',
+      '/usr/bin/microsoft-edge',
+      '/usr/bin/brave-browser',
+    );
+  }
   if (platform === 'win32') {
     for (const root of [env.PROGRAMFILES, env['PROGRAMFILES(X86)'], env.LOCALAPPDATA]) {
       if (!root) {

package/src/standalone-demo-url.js

@@ -1,4 +1,4 @@
-import { URLPattern } from 'urlpattern-polyfill';
+import { routePattern } from './route-pattern.js';
 
 /** @typedef {import('@rocket/js/types.js').PageRegistry} PageRegistry */
 /** @typedef {import('@rocket/js/types.js').Page} Page */
@@ -124,7 +124,7 @@ export function normalizeDocumentPath(pagePath) {
  * @param {string} routePath
  */
 function matchPagePath(pathname, origin, routePath) {
-  const pattern = new URLPattern({ pathname: routePath });
+  const pattern = routePattern(routePath);
   return pattern.exec(pathname, origin);
 }