@rocket/js 0.1.1 → 0.2.0

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
  */

package/src/feeds.js

@@ -0,0 +1,212 @@
+import { PageData } from './PageData.js';
+import { normalizeDocumentPath } from './standalone-demo-url.js';
+
+/** @typedef {import('@rocket/js/types.js').Page} Page */
+/** @typedef {import('@rocket/js/types.js').PageCollectionEntry} PageCollectionEntry */
+/** @typedef {import('@rocket/js/types.js').PageFeedConfig} PageFeedConfig */
+/** @typedef {import('@rocket/js/types.js').PageFeedDeclaration} PageFeedDeclaration */
+/** @typedef {import('@rocket/js/types.js').PageRegistry} PageRegistry */
+
+// Atom requires a feed-level <updated> value even when no entry has dates yet.
+const FALLBACK_UPDATED = '1970-01-01';
+
+/**
+ * @param {Page} page
+ */
+export function hasPageFeed(page) {
+  return page.file.endsWith('.js') && page.module.feed !== undefined;
+}
+
+/**
+ * @param {string} pagePath
+ */
+export function pageFeedPath(pagePath) {
+  return `${normalizeDocumentPath(pagePath)}feed.xml`;
+}
+
+/**
+ * @param {string} pathname
+ * @param {PageRegistry} pages
+ * @returns {{ page: Page; routePath: string } | null}
+ */
+export function matchPageFeedPath(pathname, pages) {
+  for (const [routePath, page] of pages) {
+    if (!hasPageFeed(page) || hasPathParameter(routePath)) {
+      continue;
+    }
+    if (pageFeedPath(routePath) === pathname) {
+      return { page, routePath };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {{
+ *   pages: PageRegistry;
+ *   page: Page;
+ *   pagePath: string;
+ *   siteOrigin: string;
+ * }} options
+ * @returns {string}
+ */
+export function createPageFeed({ pages, page, pagePath, siteOrigin }) {
+  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.`,
+    );
+  }
+  const config = resolvePageFeedConfig({ pages, page, pagePath });
+  const feedUrl = absoluteUrl(siteOrigin, pageFeedPath(pagePath));
+  const pageUrl = absoluteUrl(siteOrigin, normalizeDocumentPath(pagePath));
+  const entries =
+    config.limit === undefined ? config.collection : config.collection.slice(0, config.limit);
+
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<feed xmlns="http://www.w3.org/2005/Atom">',
+    `  <title>${escapeXml(config.title)}</title>`,
+  ];
+  if (config.description) {
+    lines.push(`  <subtitle>${escapeXml(config.description)}</subtitle>`);
+  }
+  lines.push(
+    `  <id>${escapeXml(pageUrl)}</id>`,
+    `  <link rel="self" type="application/atom+xml" href="${escapeXml(feedUrl)}"/>`,
+    `  <link rel="alternate" type="text/html" href="${escapeXml(pageUrl)}"/>`,
+    `  <updated>${atomDate(newestEntryDate(entries))}</updated>`,
+  );
+  for (const entry of entries) {
+    lines.push(...feedEntryLines(entry, siteOrigin));
+  }
+  lines.push('</feed>', '');
+  return lines.join('\n');
+}
+
+/**
+ * @param {PageCollectionEntry} entry
+ * @param {string} siteOrigin
+ */
+function feedEntryLines(entry, siteOrigin) {
+  const entryUrl = absoluteUrl(siteOrigin, normalizeDocumentPath(entry.path));
+  const lines = [
+    '  <entry>',
+    `    <title>${escapeXml(entry.metadata.title)}</title>`,
+    `    <id>${escapeXml(entryUrl)}</id>`,
+    `    <link rel="alternate" type="text/html" href="${escapeXml(entryUrl)}"/>`,
+    `    <updated>${atomDate(entry.metadata.updated || entry.metadata.date || FALLBACK_UPDATED)}</updated>`,
+  ];
+  if (entry.metadata.date) {
+    lines.push(`    <published>${atomDate(entry.metadata.date)}</published>`);
+  }
+  if (entry.metadata.description) {
+    lines.push(`    <summary>${escapeXml(entry.metadata.description)}</summary>`);
+  }
+  for (const author of entry.metadata.authors || []) {
+    lines.push('    <author>', `      <name>${escapeXml(author)}</name>`, '    </author>');
+  }
+  lines.push('  </entry>');
+  return lines;
+}
+
+/**
+ * @param {{
+ *   pages: PageRegistry;
+ *   page: Page;
+ *   pagePath: string;
+ * }} options
+ * @returns {PageFeedConfig}
+ */
+function resolvePageFeedConfig({ pages, page, pagePath }) {
+  const declaration = /** @type {PageFeedDeclaration} */ (page.module.feed);
+  const config =
+    typeof declaration === 'function'
+      ? declaration(new PageData(pages, page.metadata, pagePath))
+      : declaration;
+  return normalizePageFeedConfig(config, page);
+}
+
+/**
+ * @param {unknown} config
+ * @param {Page} page
+ * @returns {PageFeedConfig}
+ */
+function normalizePageFeedConfig(config, page) {
+  if (typeof config !== 'object' || config === null) {
+    throw new Error(pageFeedConfigError(page));
+  }
+  const feedConfig = /** @type {Record<string, unknown>} */ (config);
+  if (
+    typeof feedConfig.title !== 'string' ||
+    feedConfig.title.trim() === '' ||
+    !Array.isArray(feedConfig.collection) ||
+    (feedConfig.description !== undefined && typeof feedConfig.description !== 'string') ||
+    (feedConfig.limit !== undefined &&
+      (typeof feedConfig.limit !== 'number' ||
+        !Number.isInteger(feedConfig.limit) ||
+        feedConfig.limit <= 0))
+  ) {
+    throw new Error(pageFeedConfigError(page));
+  }
+  return /** @type {PageFeedConfig} */ (config);
+}
+
+/**
+ * @param {Page} page
+ */
+function pageFeedConfigError(page) {
+  return (
+    `Page Feed for ${page.file} must provide a non-empty title, a collection array, ` +
+    `an optional string description, and an optional positive integer limit.`
+  );
+}
+
+/**
+ * @param {PageCollectionEntry[]} entries
+ */
+function newestEntryDate(entries) {
+  let newest = '';
+  for (const entry of entries) {
+    const date = entry.metadata.updated || entry.metadata.date || '';
+    if (date > newest) {
+      newest = date;
+    }
+  }
+  return newest || FALLBACK_UPDATED;
+}
+
+/**
+ * Page Metadata dates are date-only ISO strings; Atom requires full timestamps.
+ * @param {string} date
+ */
+function atomDate(date) {
+  return `${date}T00:00:00Z`;
+}
+
+/**
+ * @param {string} siteOrigin
+ * @param {string} pagePath
+ */
+function absoluteUrl(siteOrigin, pagePath) {
+  return new URL(pagePath, `${siteOrigin}/`).href;
+}
+
+/**
+ * @param {string} pagePath
+ */
+function hasPathParameter(pagePath) {
+  return /(^|\/):[^/]+/.test(pagePath);
+}
+
+/**
+ * @param {string} value
+ */
+function escapeXml(value) {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}

package/src/hydration/hydrationLoader.js

@@ -30,7 +30,7 @@ export class HydrationLoader {
   /**
    * @param {number} index
    * @param {object} options
-   * @param {HTMLElement[]} [options.composedPath]
+   * @param {EventTarget[]} [options.composedPath]
    * @param {Event} [options.event]
    * @returns {Promise<{ needsCleanup: boolean }>}
    */
@@ -124,11 +124,14 @@ export class HydrationLoader {
    * @param {String} param1.strategyType
    * @param {String} [param1.strategyOptions]
    * @param {Boolean} param1.resolveAble
-   * @param {Object} [options]
+   * @param {{ composedPath?: EventTarget[]; event?: Event }} [options]
    */
   async setResolveAbleOn({ target, strategyType, strategyOptions, resolveAble }, options = {}) {
     let needsCleanup = false;
-    const foundIndex = this.elements.findIndex(el => el.node === target && !el.deleteMe);
+    // Events fired on light-DOM descendants should still hydrate the host.
+    const foundIndex = this.elements.findIndex(
+      el => !el.deleteMe && (el.node === target || options.composedPath?.includes(el.node)),
+    );
     if (foundIndex !== -1) {
       const element = this.elements[foundIndex];
 
@@ -162,55 +165,61 @@ export class HydrationLoader {
 
     let needsCleanup = false;
     for (let i = 0; i < this.elements.length; i += 1) {
-      ({ needsCleanup } = await this.checkElement(i));
+      const result = await this.checkElement(i);
+      needsCleanup = needsCleanup || result.needsCleanup;
     }
     if (needsCleanup) {
-      await this.cleanup();
+      this.cleanup();
     }
 
     await this.handleOnVisible();
     await this.handleOnClick();
     await this.handleOnFocus();
+    await this.handleOnHover();
     await this.handleOnMedia();
   }
 
   async handleOnMedia() {
+    // One listener per media query; it looks up the current elements when it
+    // fires, so hydrated elements never keep stale per-element listeners alive.
+    /** @type {Set<string>} */
+    const queries = new Set();
     for (const el of this.elements) {
       for (const strategy of el.strategies) {
         if (strategy.type === 'onMedia' && strategy.options) {
-          if (!this.mediaQueries[strategy.options]) {
-            this.mediaQueries[strategy.options] = window.matchMedia(strategy.options);
-          }
+          queries.add(strategy.options);
+        }
+      }
+    }
 
-          // TODO: remove event listener on cleanup if element gets removed
-          this.mediaQueries[strategy.options].addEventListener('change', ev => {
-            if (ev.matches) {
-              this.setResolveAbleOn({
-                target: el.node,
-                strategyType: strategy.type,
-                strategyOptions: strategy.options,
-                resolveAble: true,
-              });
-            } else {
-              this.setResolveAbleOn({
-                target: el.node,
-                strategyType: strategy.type,
-                strategyOptions: strategy.options,
-                resolveAble: false,
-              });
-            }
-          });
+    for (const query of queries) {
+      if (!this.mediaQueries[query]) {
+        const mediaQuery = window.matchMedia(query);
+        this.mediaQueries[query] = mediaQuery;
+        mediaQuery.addEventListener('change', ev => {
+          this.updateOnMediaElements(query, ev.matches);
+        });
+      }
+      if (this.mediaQueries[query].matches) {
+        await this.updateOnMediaElements(query, true);
+      }
+    }
+  }
 
-          // Initial check
-          if (this.mediaQueries[strategy.options].matches) {
-            this.setResolveAbleOn({
-              target: el.node,
-              strategyType: strategy.type,
-              strategyOptions: strategy.options,
-              resolveAble: true,
-            });
-          }
-        }
+  /**
+   * @param {string} query
+   * @param {boolean} matches
+   */
+  async updateOnMediaElements(query, matches) {
+    // iterate over a copy — hydration mutates this.elements
+    for (const el of [...this.elements]) {
+      if (el.strategies.some(s => s.type === 'onMedia' && s.options === query)) {
+        await this.setResolveAbleOn({
+          target: el.node,
+          strategyType: 'onMedia',
+          strategyOptions: query,
+          resolveAble: matches,
+        });
       }
     }
   }
@@ -220,9 +229,11 @@ export class HydrationLoader {
       if (!ev.target) {
         return;
       }
+      // composedPath() only returns the full path during dispatch, so capture it now
+      const composedPath = ev.composedPath();
       this.setResolveAbleOn(
         { target: ev.target, strategyType: 'onClick', resolveAble: true },
-        { composedPath: ev.composedPath(), event: ev },
+        { composedPath, event: ev },
       );
 
       // reset the onClick resolveAble if the click did not result in the hydration of the element
@@ -230,11 +241,10 @@ export class HydrationLoader {
         if (!ev.target) {
           return;
         }
-        this.setResolveAbleOn({
-          target: ev.target,
-          strategyType: 'onClick',
-          resolveAble: false,
-        });
+        this.setResolveAbleOn(
+          { target: ev.target, strategyType: 'onClick', resolveAble: false },
+          { composedPath },
+        );
       }, 50);
     });
   }
@@ -244,9 +254,11 @@ export class HydrationLoader {
       if (!ev.target) {
         return;
       }
+      // composedPath() only returns the full path during dispatch, so capture it now
+      const composedPath = ev.composedPath();
       this.setResolveAbleOn(
         { target: ev.target, strategyType: 'onFocus', resolveAble: true },
-        { composedPath: ev.composedPath(), event: ev },
+        { composedPath, event: ev },
       );
 
       // reset the onFocus resolveAble if the focus did not resulted in the hydration of the element
@@ -254,15 +266,35 @@ export class HydrationLoader {
         if (!ev.target) {
           return;
         }
-        this.setResolveAbleOn({
-          target: ev.target,
-          strategyType: 'onFocus',
-          resolveAble: false,
-        });
+        this.setResolveAbleOn(
+          { target: ev.target, strategyType: 'onFocus', resolveAble: false },
+          { composedPath },
+        );
       }, 50);
     });
   }
 
+  async handleOnHover() {
+    document.body.addEventListener('pointerover', ev => {
+      if (!ev.target) {
+        return;
+      }
+      this.setResolveAbleOn(
+        { target: ev.target, strategyType: 'onHover', resolveAble: true },
+        { composedPath: ev.composedPath() },
+      );
+    });
+    document.body.addEventListener('pointerout', ev => {
+      if (!ev.target) {
+        return;
+      }
+      this.setResolveAbleOn(
+        { target: ev.target, strategyType: 'onHover', resolveAble: false },
+        { composedPath: ev.composedPath() },
+      );
+    });
+  }
+
   async handleOnVisible() {
     this.intersectionObserver = new IntersectionObserver(entries => {
       for (const entry of entries) {