@rocket/js 0.1.2 → 0.2.0

package/src/cli/RocketBuild.js

@@ -6,8 +6,10 @@ import { build } from 'vite';
 import path from 'node:path';
 import { PageRuntime } from '../page-runtime.js';
 import { createIconAssetStore, rocketIconRuntimeOutputs } from '../icons.js';
-import { paginatedArchivePaths } from '../page-pagination.js';
-import { createStaticPageModuleLoader } from '../static-page-module-loader.js';
+import { hasPagePagination, paginatedArchivePaths } from '../page-pagination.js';
+import { hasPageFeed, pageFeedPath } from '../feeds.js';
+import { hasStaticParams, staticParamsPagePaths } from '../static-params.js';
+import { createPageModuleLoader } from '../page-module-loader.js';
 import { writeSiteDiscoverabilityOutputs } from '../siteDiscoverability.js';
 import { normalizeDocumentPath, standaloneDemoPaths } from '../standalone-demo-url.js';
 import {
@@ -46,6 +48,7 @@ export class RocketBuild {
 
     program
       .command('build')
+      .description('build the static site into the output directory')
       .option('-o, --output-dir <path>', 'Path where to output built files')
       .action(async ({ outputDir }) => {
         if (outputDir) {
@@ -96,6 +99,8 @@ export class RocketBuild {
       emitRedirectFallbacks: !this.cli.config.adapter,
     });
     const outDir = this.outputDir ? path.resolve(this.outputDir) : path.resolve('dist');
+    // Vite's emptyOutDir force-clears any outDir, so containment must hold on every path.
+    assertOutputDirInsideProject(outDir);
     assertPublicAssetsOutputDir({ projectRoot: process.cwd(), outDir });
 
     try {
@@ -217,7 +222,7 @@ export function splitPages(pages) {
 export async function renderStaticPages({
   pages,
   staticPages,
-  pageModuleLoader = createStaticPageModuleLoader(),
+  pageModuleLoader = createPageModuleLoader(),
   origin = 'http://localhost',
   urlLifecycle,
   siteHeadMetadata,
@@ -232,6 +237,8 @@ export async function renderStaticPages({
   assertStaticJavaScriptPagesHaveConcretePaths(staticPages);
   assertNoStandaloneDemoPathCollisions(pages, staticPages);
   assertNoPaginatedArchivePathCollisions(pages, staticPages);
+  assertPageFeedsAreBuildable({ pages, staticPages, siteOrigin });
+  assertNoStaticParamsPathCollisions(pages, staticPages);
   validateUrlLifecycleGeneratedOutputCollisions({
     redirects: urlLifecycle?.redirects,
     pages,
@@ -265,6 +272,13 @@ export async function renderStaticPages({
   });
   for (const [pagePath, page] of staticPages) {
     try {
+      if (hasStaticParams(page)) {
+        for (const paramPath of staticParamsPagePaths({ pages, page, pagePath })) {
+          const paramResponse = await pageRuntime.render(new Request(new URL(paramPath, origin)));
+          await writeStaticResponse(paramPath, paramResponse);
+        }
+        continue;
+      }
       const response = await pageRuntime.render(new Request(new URL(pagePath, origin)));
       await writeStaticResponse(pagePath, response);
       for (const archivePath of paginatedArchivePaths({ pages, page, pagePath })) {
@@ -275,6 +289,11 @@ export async function renderStaticPages({
         const demoResponse = await pageRuntime.render(new Request(new URL(demoPath, origin)));
         await writeStandaloneDemoResponse(demoPath, page, demoResponse);
       }
+      if (hasPageFeed(page)) {
+        const feedPath = pageFeedPath(pagePath);
+        const feedResponse = await pageRuntime.render(new Request(new URL(feedPath, origin)));
+        await writeStaticResponse(feedPath, feedResponse);
+      }
     } catch (error) {
       throw new Error(`Failed to render page: ${pagePath}. ${errorMessage(error)}`, {
         cause: error,
@@ -293,18 +312,55 @@ export async function renderStaticPages({
  */
 function assertStaticJavaScriptPagesHaveConcretePaths(staticPages) {
   for (const [pagePath, page] of staticPages) {
-    if (!page.file.endsWith('.js') || !hasPathParameter(pagePath)) {
+    if (!page.file.endsWith('.js') || !hasPathParameter(pagePath) || hasStaticParams(page)) {
       continue;
     }
     throw new Error(
       `Static JavaScript Page ${pagePath} (${page.file}) cannot be rendered as one static ` +
-        `output document because its path is parameterized. Parameterized JavaScript Pages need ` +
-        `request-time rendering until Rocket has an API for enumerating static params. Use ` +
-        `render: 'server' for this Page today.`,
+        `output document because its path is parameterized. Export static params to enumerate ` +
+        `its output documents, or use render: 'server' for request-time rendering.`,
     );
   }
 }
 
+/**
+ * @param {import('@rocket/js/types.js').PageRegistry} pages
+ * @param {import('@rocket/js/types.js').PageRegistry} staticPages
+ */
+function assertNoStaticParamsPathCollisions(pages, staticPages) {
+  const configuredPages = configuredPageOutputPaths(pages);
+  const staticParamsPages = new Map();
+  for (const [pagePath, page] of staticPages) {
+    if (!hasStaticParams(page)) {
+      continue;
+    }
+    if (hasPagePagination(page)) {
+      throw new Error(
+        `Static JavaScript Page ${pagePath} (${page.file}) cannot combine static params with ` +
+          `pagination. Paginate a concrete archive Page instead.`,
+      );
+    }
+    for (const paramPath of staticParamsPagePaths({ pages, page, pagePath })) {
+      const outputPath = normalizeDocumentPath(paramPath);
+      const collision = configuredPages.get(outputPath);
+      if (collision) {
+        throw new Error(
+          `Static params output path ${paramPath} for page ${page.file} collides with ` +
+            `configured Page ${collision.page.file} at ${collision.path}`,
+        );
+      }
+      const paramCollision = staticParamsPages.get(outputPath);
+      if (paramCollision) {
+        throw new Error(
+          `Static params output path ${paramPath} for page ${page.file} collides with ` +
+            `static params output path ${paramCollision.path} for page ${paramCollision.page.file}`,
+        );
+      }
+      staticParamsPages.set(outputPath, { path: paramPath, page });
+    }
+  }
+}
+
 /**
  * @param {string} pagePath
  */
@@ -312,6 +368,40 @@ function hasPathParameter(pagePath) {
   return /(^|\/):[^/]+/.test(pagePath);
 }
 
+/**
+ * @param {{
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   staticPages: import('@rocket/js/types.js').PageRegistry;
+ *   siteOrigin?: string;
+ * }} options
+ */
+function assertPageFeedsAreBuildable({ pages, staticPages, siteOrigin }) {
+  for (const [pagePath, page] of staticPages) {
+    if (!hasPageFeed(page)) {
+      continue;
+    }
+    if (hasPathParameter(pagePath)) {
+      throw new Error(
+        `Page Feed for ${page.file} cannot use the parameterized path ${pagePath}. ` +
+          `Page Feeds need a concrete owning Page path.`,
+      );
+    }
+    if (typeof siteOrigin !== 'string' || siteOrigin.trim() === '') {
+      throw new Error(
+        `Page Feed ${pageFeedPath(pagePath)} for ${page.file} requires a Site Origin for ` +
+          `absolute feed URLs. Add siteOrigin: 'https://example.com' to rocket-config.js.`,
+      );
+    }
+    const collision = pages.get(pageFeedPath(pagePath));
+    if (collision) {
+      throw new Error(
+        `Page Feed ${pageFeedPath(pagePath)} for ${page.file} collides with configured ` +
+          `Page ${collision.file}`,
+      );
+    }
+  }
+}
+
 /**
  * @param {import('@rocket/js/types.js').PageRegistry} pages
  * @param {import('@rocket/js/types.js').PageRegistry} staticPages
@@ -429,23 +519,30 @@ function writeIconAssetOutputs(iconAssetStore) {
 /**
  * @param {string} outDir
  */
-function clearExistingOutputDir(outDir) {
-  if (!existsSync(outDir)) {
-    return;
-  }
+function assertOutputDirInsideProject(outDir) {
   const projectRoot = path.resolve(process.cwd());
   const relativeOutDir = path.relative(projectRoot, outDir);
   if (
     relativeOutDir === '' ||
-    relativeOutDir.startsWith(`..${path.sep}`) ||
     relativeOutDir === '..' ||
+    relativeOutDir.startsWith(`..${path.sep}`) ||
     path.isAbsolute(relativeOutDir)
   ) {
     throw new Error(
       `Invalid build output directory ${outDir}. ` +
-        `Rocket can only clear an existing output directory inside the project root.`,
+        `Rocket only writes build output inside the project root.`,
     );
   }
+}
+
+/**
+ * @param {string} outDir
+ */
+function clearExistingOutputDir(outDir) {
+  if (!existsSync(outDir)) {
+    return;
+  }
+  assertOutputDirInsideProject(outDir);
   rmSync(outDir, { recursive: true });
 }
 

package/src/cli/RocketCli.js

@@ -1,9 +1,14 @@
+import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
 import { readConfig } from '../config.js';
 import { RocketBuild } from './RocketBuild.js';
 import { RocketInit } from './RocketInit.js';
 import { RocketStart } from './RocketStart.js';
 
+const packageJson = JSON.parse(
+  readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+);
+
 export class RocketCli {
   /** @type {string[]} */
   argv;
@@ -21,7 +26,12 @@ export class RocketCli {
     this.argv = argv;
 
     this.program = new Command();
-    this.program.allowUnknownOption(true).option('-c, --config-file <path>', 'path to config file');
+    this.program
+      .name('rocket')
+      .description('HTML-first static-site metaframework for content sites and Web Component docs')
+      .version(packageJson.version)
+      .allowUnknownOption(true)
+      .option('-c, --config-file <path>', 'path to config file');
     this.program.parseOptions(this.argv);
 
     this.program.allowUnknownOption(false);

package/src/cli/RocketStart.js

@@ -8,6 +8,9 @@ export class RocketStart {
   /** @type {RocketStartOptions} */
   startOptions = {};
 
+  /** @type {import('child_process').ChildProcess | undefined} */
+  server = undefined;
+
   /**
    * @param {import('commander').Command} program
    * @param {import('./RocketCli.js').RocketCli} cli
@@ -17,6 +20,7 @@ export class RocketStart {
 
     program
       .command('start')
+      .description('start the development server')
       .option('-p, --port <port>', 'port for the development server')
       .option('--no-open', 'do not open the browser')
       .option('--no-watch', 'disable automatic file watching and reloads')
@@ -32,7 +36,7 @@ export class RocketStart {
    */
   spawnServer(options = {}) {
     process.stdin.setRawMode?.(true);
-    return spawn(
+    const server = spawn(
       'node',
       startServerArgs({
         configFilePath: this.cli?.configFilePath,
@@ -43,13 +47,47 @@ export class RocketStart {
         cwd: process.cwd(),
       },
     );
+    server.on('exit', (code, signal) => {
+      // ignore exits of already-replaced servers during a restart
+      if (this.server !== server) {
+        return;
+      }
+      this.server = undefined;
+      if (this.startOptions.watch !== false) {
+        console.log(
+          `Rocket dev server stopped (${signal ?? `code ${code}`}). ` +
+            'Waiting for changes - press Ctrl+R to restart or Ctrl+C to quit.',
+        );
+      } else {
+        this.shutdown(typeof code === 'number' ? code : 1);
+      }
+    });
+    return server;
   }
 
   restartServer() {
-    this.server?.kill();
-    this.server = this.spawnServer(this.startOptions);
+    const oldServer = this.server;
+    this.server = undefined;
     console.clear();
     console.log('Restarting rocket server...');
+    if (oldServer && oldServer.exitCode === null && oldServer.signalCode === null) {
+      // wait for the old process to release its port before respawning
+      oldServer.once('exit', () => {
+        this.server = this.spawnServer(this.startOptions);
+      });
+      oldServer.kill();
+    } else {
+      this.server = this.spawnServer(this.startOptions);
+    }
+  }
+
+  /**
+   * @param {number} code
+   */
+  shutdown(code) {
+    process.stdin.setRawMode?.(false);
+    this.server?.kill();
+    process.exit(code);
   }
 
   /**
@@ -71,25 +109,31 @@ export class RocketStart {
         }, 100),
       );
 
-      // watch src
-      watch(
-        import.meta.dirname,
-        { recursive: true },
-        debounce(async (_, filename) => {
-          if (!filename) {
-            return;
-          }
-          this.restartServer();
-        }, 100),
-      );
+      // watch the framework source when running from a Rocket checkout
+      const frameworkSrcDir = path.join(import.meta.dirname, '..');
+      if (!frameworkSrcDir.includes('node_modules') && frameworkSrcDir.startsWith(process.cwd())) {
+        watch(
+          frameworkSrcDir,
+          { recursive: true },
+          debounce(async (_, filename) => {
+            if (!filename) {
+              return;
+            }
+            this.restartServer();
+          }, 100),
+        );
+      }
+    }
+
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      process.on(signal, () => this.shutdown(0));
     }
 
     process.stdin.on('data', data => {
       const char = data.toString();
       if (char === '\u0003' || char === '\u0004') {
         // Ctrl+C or Ctrl+D
-        this.server?.kill();
-        process.exit(0);
+        this.shutdown(0);
       } else if (char === '\u0012') {
         // Ctrl+R
         this.restartServer();

package/src/cli/cli.js

@@ -1,7 +1,16 @@
 #!/usr/bin/env node
+/* eslint-disable no-console */
 
 import { RocketCli } from './RocketCli.js';
 
 const cli = new RocketCli();
 
-await cli.start();
+try {
+  await cli.start();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  if (process.env.ROCKET_DEBUG) {
+    console.error(error);
+  }
+  process.exit(1);
+}

package/src/component-hydration.js

@@ -30,7 +30,7 @@ export function createComponentHydration({
         serverOnlyComponents.push({ name, file, className, module });
       } else if (loading === 'client') {
         clientComponents.push({ name, file, className });
-      } else if (loading.startsWith('hydrate:')) {
+      } else if (isHydrateLoading(loading)) {
         const module = await loadComponentModule(file);
         hydratedComponents.push({
           name,
@@ -39,13 +39,21 @@ export function createComponentHydration({
           module,
           strategy: loading.slice('hydrate:'.length),
         });
+      } else {
+        throw new Error(
+          `Registered Component "${name}" has an invalid loading value ${JSON.stringify(
+            loading,
+          )}. Use 'server', 'client', or 'hydrate:<strategy>'.`,
+        );
       }
     }
 
     const registry = customElementsRegistry || customElements;
-    registry.__definitions.clear();
+    // The @lit-labs/ssr-dom-shim registry keeps definitions between renders;
+    // spec-compliant registries have no such internals to reset.
+    registry.__definitions?.clear();
     // @ts-ignore
-    registry.__reverseDefinitions.clear();
+    registry.__reverseDefinitions?.clear();
     for (const component of serverOnlyComponents.concat(hydratedComponents)) {
       if (!component.module[component.className]) {
         throw new Error(
@@ -84,3 +92,15 @@ export function createComponentHydration({
     return clientCode;
   };
 }
+
+/**
+ * @param {unknown} loading
+ * @returns {loading is string}
+ */
+function isHydrateLoading(loading) {
+  return (
+    typeof loading === 'string' &&
+    loading.startsWith('hydrate:') &&
+    loading.length > 'hydrate:'.length
+  );
+}

package/src/components/RocketDrawer.js

@@ -13,13 +13,47 @@ export class RocketDrawer extends LitElement {
   connectedCallback() {
     super.connectedCallback();
     this._onDocClick = this._onDocClick.bind(this);
+    this._onKeyDown = this._onKeyDown.bind(this);
     document.addEventListener('click', this._onDocClick, { capture: true });
+    document.addEventListener('keydown', this._onKeyDown);
   }
   disconnectedCallback() {
     document.removeEventListener('click', this._onDocClick, { capture: true });
+    document.removeEventListener('keydown', this._onKeyDown);
     super.disconnectedCallback();
   }
 
+  /**
+   * @param {KeyboardEvent} ev
+   */
+  _onKeyDown(ev) {
+    if (ev.key === 'Escape' && this.open) {
+      this.close();
+    }
+  }
+
+  /**
+   * @param {Map<string, unknown>} changedProperties
+   */
+  updated(changedProperties) {
+    // skip the initial render so the drawer never steals focus on page load
+    if (!changedProperties.has('open') || changedProperties.get('open') === undefined) {
+      return;
+    }
+    if (this.open) {
+      this.shadowRoot?.getElementById('content')?.focus();
+    } else {
+      const invokerSlot = /** @type {HTMLSlotElement | null} */ (
+        this.shadowRoot?.querySelector('slot[name="invoker"]') ?? null
+      );
+      const assigned = /** @type {HTMLElement | undefined} */ (invokerSlot?.assignedElements()[0]);
+      const fallback = /** @type {HTMLElement | null} */ (
+        this.shadowRoot?.querySelector('.burger-menu') ?? null
+      );
+      (assigned ?? fallback)?.focus();
+    }
+  }
+
   render() {
     return html`
       <slot name="invoker">
@@ -36,7 +70,7 @@ export class RocketDrawer extends LitElement {
       </slot>
 
       <dialog ?open=${this.open} id="rd-dialog">
-        <div id="content">
+        <div id="content" tabindex="-1">
           <slot></slot>
         </div>
       </dialog>
@@ -149,23 +183,23 @@ export class RocketDrawer extends LitElement {
       overflow: hidden;
       opacity: 0;
       pointer-events: none;
+      /* visibility keeps the closed drawer out of tab order and the a11y tree */
+      visibility: hidden;
       transition:
         width 0.35s var(--rd-ease-3),
-        opacity 0.35s var(--rd-ease-3);
+        opacity 0.35s var(--rd-ease-3),
+        visibility 0s var(--rd-ease-3) 0.35s;
       will-change: width;
     }
     dialog[open] {
       width: var(--rd-target-width);
       opacity: 1;
       pointer-events: auto;
-    }
-    dialog::backdrop {
-      background: rgba(0, 0, 0, 0.4);
-      transition: opacity 0.35s var(--rd-ease-3);
-      opacity: 0;
-    }
-    dialog[open]::backdrop {
-      opacity: 1;
+      visibility: visible;
+      transition:
+        width 0.35s var(--rd-ease-3),
+        opacity 0.35s var(--rd-ease-3),
+        visibility 0s;
     }
 
     #content {

package/src/components/RocketSocialLink.js

@@ -2,14 +2,38 @@ import { readFileSync } from 'fs';
 import { LitElement, html, css } from 'lit';
 import { unsafeHTML } from 'lit/directives/unsafe-html.js';
 
+const SUPPORTED_BRANDS = new Set([
+  'discord',
+  'github',
+  'gitlab',
+  'license',
+  'npm',
+  'slack',
+  'telegram',
+  'twitter',
+]);
+
+/** @type {Map<string, string>} */
+const iconCache = new Map();
+
 /**
  * @param {string} brandName
  * @returns {import('lit/directive.js').DirectiveResult}
  */
 function getIcon(brandName) {
   const brand = brandName.toLowerCase();
-  const fileContent = readFileSync(new URL(`./assets/${brand}.svg`, import.meta.url), 'utf8');
-  return unsafeHTML(fileContent.toString());
+  if (!SUPPORTED_BRANDS.has(brand)) {
+    throw new Error(
+      `rocket-social-link does not support name="${brandName}". ` +
+        `Supported names: ${[...SUPPORTED_BRANDS].join(', ')}.`,
+    );
+  }
+  let fileContent = iconCache.get(brand);
+  if (fileContent === undefined) {
+    fileContent = readFileSync(new URL(`./assets/${brand}.svg`, import.meta.url), 'utf8');
+    iconCache.set(brand, fileContent);
+  }
+  return unsafeHTML(fileContent);
 }
 
 export class RocketSocialLink extends LitElement {

package/src/config.js

@@ -1,5 +1,7 @@
 /** Runs on: server */
+import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { validateIconLibrariesConfig } from './icons.js';
 
 const REDIRECT_STATUSES = new Set([301, 302, 307, 308]);
@@ -9,14 +11,25 @@ const REDIRECT_STATUSES = new Set([301, 302, 307, 308]);
  * @returns {Promise<import("@rocket/js/types.js").ResolvedRocketConfig>}
  */
 export async function readConfig(filePath) {
-  const configFile = await import(
-    filePath ? path.join(process.cwd(), filePath) : path.join(process.cwd(), 'rocket-config.js')
-  );
+  const configPath = path.join(process.cwd(), filePath || 'rocket-config.js');
+  if (!existsSync(configPath)) {
+    throw new Error(
+      `No Rocket config found at ${configPath}. ` +
+        `Run "npx rocket init" to create one, or pass --config-file <path>.`,
+    );
+  }
+  const configFile = await import(pathToFileURL(configPath).href);
   if (configFile.default === undefined) {
     throw new Error('rocket-config.js must have a default export');
   }
   /** @type {import("@rocket/js/types.js").RocketConfig} */
   const config = configFile.default;
+  if (!Array.isArray(config.includeGlobs)) {
+    throw new Error(
+      `Invalid Rocket config in ${configPath}: includeGlobs must be an array of glob strings, ` +
+        `e.g. includeGlobs: ['docs/pages/**/*.rocket.{md,js}'].`,
+    );
+  }
   validateRedirectConfig(config.urlLifecycle?.redirects);
   const siteHeadMetadata = normalizeSiteHeadMetadataConfig(config.siteHeadMetadata);
   validateIconLibrariesConfig(config.iconLibraries);
@@ -24,7 +37,7 @@ export async function readConfig(filePath) {
   const siteOrigin = siteHeadMetadata
     ? requireSiteHeadMetadataSiteOrigin(config.siteOrigin)
     : config.siteOrigin;
-  config.includeGlobs = config.includeGlobs.map(glob => {
+  const includeGlobs = config.includeGlobs.map(glob => {
     if (!glob.includes('*') && !glob.includes('.')) {
       // If the glob is a directory, include all files in the directory
       return `${glob}${glob.endsWith('/') ? '' : '/'}**`;
@@ -36,6 +49,7 @@ export async function readConfig(filePath) {
     excludeRegex: [],
     adjustDevServerConfig: _ => _,
     ...config,
+    includeGlobs,
     ...(siteOrigin ? { siteOrigin } : {}),
     ...(siteHeadMetadata ? { siteHeadMetadata } : {}),
   };
@@ -248,6 +262,14 @@ function invalidSiteOriginError(siteOrigin) {
 function validateRedirectConfig(redirects = []) {
   const sources = new Set();
   for (const redirect of redirects) {
+    // whitespace would corrupt whitespace-delimited outputs like Netlify _redirects
+    if (containsWhitespace(redirect.source) || containsWhitespace(redirect.target)) {
+      throw new Error(
+        `Invalid Redirect from ${JSON.stringify(redirect.source)} to ${JSON.stringify(
+          redirect.target,
+        )}. Redirect paths must not contain whitespace; percent-encode it instead (%20).`,
+      );
+    }
     if (!isInternalAbsolutePath(redirect.source)) {
       throw new Error(
         `Invalid Redirect source ${JSON.stringify(
@@ -283,6 +305,13 @@ function isInternalAbsolutePath(value) {
   return typeof value === 'string' && value.startsWith('/') && !value.startsWith('//');
 }
 
+/**
+ * @param {unknown} value
+ */
+function containsWhitespace(value) {
+  return typeof value === 'string' && /\s/.test(value);
+}
+
 /**
  * @param {unknown} value
  */