@rocket/js 0.1.2 → 0.2.0

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) {

package/src/icons.js

@@ -131,6 +131,7 @@ export async function resolveRocketIconAsset(requestPath, options = {}) {
   }
 
   const librarySegment = match[1];
+  const nameSegment = match[2];
   const resolver = createIconResolver({
     layoutIconLibraries: options.layoutIconLibraries,
     layoutDefaultIconLibrary: options.layoutDefaultIconLibrary,
@@ -144,6 +145,10 @@ export async function resolveRocketIconAsset(requestPath, options = {}) {
     }
     const icons = await indexIconLibrary(library, config);
     for (const [name, svg] of icons) {
+      // hashing every icon's SVG is expensive, so narrow by name first
+      if (sanitizePathSegment(name) !== nameSegment) {
+        continue;
+      }
       const url = iconAssetUrl({ library, name, svg });
       if (url === requestPath) {
         return { url, svg, library, name };

package/src/layouts/atlas/atlasBlog.css

@@ -0,0 +1,143 @@
+.atlas-blog {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  color: var(--docs-text-color);
+  background: var(--docs-surface-color);
+}
+
+.atlas-blog-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1.5rem;
+  flex-wrap: wrap;
+  padding: 0.75rem clamp(1rem, 4vw, 2.5rem);
+  border-bottom: 1px solid var(--docs-line-color);
+}
+
+.atlas-blog-content {
+  width: 100%;
+  max-width: 760px;
+  margin: 0 auto;
+  padding: clamp(1.5rem, 4vw, 3rem) 1rem 4rem;
+  box-sizing: border-box;
+}
+
+.atlas-blog-byline {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.5rem 1rem;
+  margin-block: 0.5rem 2rem;
+  color: var(--docs-muted-color);
+  font-size: 0.9rem;
+}
+
+.atlas-blog-authors::before {
+  content: '·';
+  margin-right: 1rem;
+}
+
+.atlas-blog-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.atlas-blog-tags a,
+.atlas-blog-tags span {
+  display: inline-block;
+  padding: 0.1rem 0.6rem;
+  border: 1px solid var(--docs-line-color);
+  border-radius: 999px;
+  background: var(--docs-surface-soft-color);
+  color: var(--docs-muted-color);
+  font-size: 0.8rem;
+  text-decoration: none;
+}
+
+.atlas-blog-tags a:hover {
+  border-color: var(--primary-color);
+  color: var(--primary-color);
+}
+
+.atlas-blog-intro {
+  margin-bottom: 2rem;
+}
+
+.atlas-blog-feed-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  color: var(--docs-muted-color);
+  text-decoration: none;
+}
+
+.atlas-blog-feed-link:hover {
+  color: var(--primary-color);
+}
+
+.atlas-blog-post-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+.atlas-blog-post-card {
+  padding: 1.25rem 1.5rem;
+  border: 1px solid var(--docs-line-color);
+  border-radius: 12px;
+  background: var(--docs-surface-soft-color);
+}
+
+.atlas-blog-post-card h2 {
+  margin: 0 0 0.25rem;
+  font-size: 1.25rem;
+}
+
+.atlas-blog-post-card h2 a {
+  color: var(--docs-text-dark-color);
+  text-decoration: none;
+}
+
+.atlas-blog-post-card h2 a:hover {
+  color: var(--primary-color);
+}
+
+.atlas-blog-post-card time {
+  color: var(--docs-muted-color);
+  font-size: 0.85rem;
+}
+
+.atlas-blog-post-card p {
+  margin: 0.5rem 0 0.75rem;
+}
+
+.atlas-blog-empty {
+  color: var(--docs-muted-color);
+}
+
+.atlas-blog-pagination {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-top: 2.5rem;
+  color: var(--docs-muted-color);
+}
+
+.atlas-blog-pagination a {
+  color: var(--link-color);
+  text-decoration: none;
+}
+
+.atlas-blog-pagination a:hover {
+  text-decoration: underline;
+}