@rocket/js 0.2.1 → 0.3.0

package/src/icons.js

@@ -5,6 +5,7 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import * as parse5 from 'parse5';
+import { resolve } from './resolve.js';
 
 const require = createRequire(import.meta.url);
 
@@ -13,6 +14,8 @@ const ICON_REFERENCE_CONFIG_FIELDS = new Set(['library', 'name']);
 const ROCKET_ICON_ASSET_PREFIX = '/_rocket/icons/';
 const ROCKET_ICON_DEFINE_MODULE_PATH = '/_rocket/rocket-icon.js';
 const ROCKET_ICON_CLASS_MODULE_PATH = '/_rocket/RocketIcon.js';
+const WEB_AWESOME_ICON_ASSET_PREFIX = '/_rocket/wa-icons/';
+const WEB_AWESOME_ICON_LIBRARY_MODULE = '@awesome.me/webawesome/dist/components/icon/library.js';
 const SHADOW_ICON_STYLE =
   ':host{display:inline-block;width:1em;height:1em;vertical-align:-0.125em;line-height:1}' +
   ':host([hidden]){display:none}' +
@@ -66,6 +69,52 @@ export class IconAssetStore {
     /** @type {Map<string, { url: string; svg: string; library: string; name: string }>} */
     this.assets = new Map();
     this.needsRuntime = false;
+    /** @type {Map<string, { library: string; config: import('@rocket/js/types.js').NormalizedIconLibraryConfig }>} */
+    this.webAwesomeIconLibraries = new Map();
+  }
+
+  /**
+   * Publishes every icon of an Icon Library at `/_rocket/wa-icons/{library}/{name}.svg`, because
+   * browser code may ask `wa-icon` for any name.
+   *
+   * @param {string} library
+   * @param {import('@rocket/js/types.js').NormalizedIconLibraryConfig} config
+   */
+  addWebAwesomeIconLibrary(library, config) {
+    this.webAwesomeIconLibraries.set(sanitizePathSegment(library), { library, config });
+  }
+
+  /**
+   * @param {string} url
+   * @returns {Promise<{ url: string; svg: string } | undefined>}
+   */
+  async getWebAwesomeIcon(url) {
+    const match = /^\/_rocket\/wa-icons\/([^/]+)\/([^/]+)\.svg$/.exec(url);
+    const entry = match && this.webAwesomeIconLibraries.get(match[1]);
+    if (!match || !entry) {
+      return undefined;
+    }
+    let name;
+    try {
+      name = decodeURIComponent(match[2]);
+    } catch {
+      return undefined;
+    }
+    const svg = (await indexIconLibrary(entry.library, entry.config)).get(name);
+    return svg === undefined ? undefined : { url, svg };
+  }
+
+  async webAwesomeIconOutputs() {
+    const outputs = [];
+    for (const [segment, { library, config }] of this.webAwesomeIconLibraries) {
+      for (const [name, svg] of await indexIconLibrary(library, config)) {
+        outputs.push({
+          url: `${WEB_AWESOME_ICON_ASSET_PREFIX}${segment}/${name}.svg`,
+          svg,
+        });
+      }
+    }
+    return outputs;
   }
 
   /**
@@ -177,6 +226,7 @@ export function validateIconLibrariesConfig(iconLibraries) {
  *     _iconLibraries?: Map<string, import('@rocket/js/types.js').NormalizedIconLibraryConfig>;
  *     _defaultIconLibrary?: string;
  *     _iconReferences?: import('@rocket/js/types.js').IconReferenceConfig[];
+ *     _webAwesomeIconLibrary?: string;
  *     _hydrationScript?: string;
  *     _hasBrowserLoadedComponents?: boolean;
  *   };
@@ -185,6 +235,15 @@ export function validateIconLibrariesConfig(iconLibraries) {
  * @returns {Promise<string>}
  */
 export async function finalizeRocketIcons(html, options = {}) {
+  const output = await finalizeRocketIconHostsAndManifest(html, options);
+  return finalizeWebAwesomeIcons(output, options);
+}
+
+/**
+ * @param {string} html
+ * @param {Parameters<typeof finalizeRocketIcons>[1] & {}} options
+ */
+async function finalizeRocketIconHostsAndManifest(html, options) {
   const lowerHtml = html.toLowerCase();
   const hasIconHosts = lowerHtml.includes('<rocket-icon');
   const hasIconLoadingPolicy =
@@ -261,6 +320,85 @@ export async function finalizeRocketIcons(html, options = {}) {
   });
 }
 
+/**
+ * Points Web Awesome's `default` icon library at the Page's Web Awesome Icon Library, so
+ * `wa-icon` elements created by browser code load self-hosted SVGs instead of a CDN.
+ *
+ * @param {string} html
+ * @param {Parameters<typeof finalizeRocketIcons>[1] & {}} options
+ */
+async function finalizeWebAwesomeIcons(html, options) {
+  const library = options.pageData?._webAwesomeIconLibrary;
+  if (!library) {
+    return html;
+  }
+  const resolver = createIconResolver({
+    layoutIconLibraries: options.layoutIconLibraries || options.pageData?._iconLibraries,
+    layoutDefaultIconLibrary:
+      options.layoutDefaultIconLibrary || options.pageData?._defaultIconLibrary,
+    projectIconLibraries: options.iconLibraries,
+    projectDefaultIconLibrary: options.defaultIconLibrary,
+  });
+  const config = resolver.libraries.get(library);
+  if (!config) {
+    throw new Error(`Web Awesome Icon Library "${library}" is not configured.`);
+  }
+  options.iconAssetStore?.addWebAwesomeIconLibrary(library, config);
+
+  const iconBaseUrl = `${WEB_AWESOME_ICON_ASSET_PREFIX}${sanitizePathSegment(library)}/`;
+  const registrationHtml =
+    '<script type="module" data-rocket-wa-icon-library>' +
+    `import { registerIconLibrary } from '${resolve(WEB_AWESOME_ICON_LIBRARY_MODULE, import.meta)}';` +
+    `registerIconLibrary('default', { resolver: name => '${iconBaseUrl}' + encodeURIComponent(name) + '.svg' });` +
+    '</script>';
+  return insertWebAwesomeIconRegistration(html, registrationHtml);
+}
+
+/**
+ * Places the registration after every import map, because browsers ignore or restrict an import
+ * map that follows a module script. Otherwise it goes before the Page's first head script: module
+ * scripts run in document order, so it runs before component code. Scripts inside HTML comments
+ * are ignored.
+ *
+ * @param {string} html
+ * @param {string} insertion
+ */
+function insertWebAwesomeIconRegistration(html, insertion) {
+  const scanHtml = html
+    .replace(/<!--[\s\S]*?(?:-->|$)/g, comment => ' '.repeat(comment.length))
+    .toLowerCase();
+  const headClose = scanHtml.indexOf('</head>');
+  /** @type {number[]} */
+  const scriptStarts = [];
+  let afterImportMaps = 0;
+  const scriptOpen = /<script(?=[\s>/])[^>]*>/g;
+  let match;
+  while ((match = scriptOpen.exec(scanHtml))) {
+    const close = scanHtml.indexOf('</script', scriptOpen.lastIndex);
+    const closeEnd = close === -1 ? -1 : scanHtml.indexOf('>', close);
+    const end = closeEnd === -1 ? scanHtml.length : closeEnd + 1;
+    if (/\btype\s*=\s*["']?importmap["'\s/>]/.test(match[0])) {
+      afterImportMaps = end;
+    } else {
+      scriptStarts.push(match.index);
+    }
+    scriptOpen.lastIndex = end;
+  }
+
+  const firstHeadScript = scriptStarts.find(
+    start => start >= afterImportMaps && (headClose === -1 || start < headClose),
+  );
+  let index;
+  if (firstHeadScript !== undefined) {
+    index = firstHeadScript;
+  } else if (headClose !== -1 && headClose >= afterImportMaps) {
+    index = headClose;
+  } else {
+    index = afterImportMaps;
+  }
+  return html.slice(0, index) + insertion + html.slice(index);
+}
+
 /**
  * @param {unknown} iconLibraries
  * @param {string} owner

package/src/layouts/atlas/atlasBlogLayout.js

@@ -53,9 +53,11 @@ export function renderBlogTags(tags, data) {
       ${tags.map(
         tag => html`
           <li>
-            ${data.tagPathPrefix
-              ? html`<a href=${blogTagPath(data.tagPathPrefix, tag)} rel="tag">${tag}</a>`
-              : html`<span>${tag}</span>`}
+            ${
+              data.tagPathPrefix
+                ? html`<a href=${blogTagPath(data.tagPathPrefix, tag)} rel="tag">${tag}</a>`
+                : html`<span>${tag}</span>`
+            }
           </li>
         `,
       )}
@@ -84,9 +86,11 @@ export function renderBlogByline(metadata, data, language) {
   }
   return html`
     <div class="atlas-blog-byline">
-      ${metadata.date
-        ? html`<time datetime=${metadata.date}>${formatBlogDate(metadata.date, language)}</time>`
-        : ''}
+      ${
+        metadata.date
+          ? html`<time datetime=${metadata.date}>${formatBlogDate(metadata.date, language)}</time>`
+          : ''
+      }
       ${authors.length ? html`<span class="atlas-blog-authors">${authors.join(', ')}</span>` : ''}
       ${renderBlogTags(metadata.tags, data)}
     </div>
@@ -108,11 +112,13 @@ export function renderBlogPostList(items, data, language) {
         item => html`
           <li class="atlas-blog-post-card">
             <h2><a href=${item.url}>${item.metadata.title}</a></h2>
-            ${item.metadata.date
-              ? html`<time datetime=${item.metadata.date}
-                  >${formatBlogDate(item.metadata.date, language)}</time
-                >`
-              : ''}
+            ${
+              item.metadata.date
+                ? html`<time datetime=${item.metadata.date}
+                    >${formatBlogDate(item.metadata.date, language)}</time
+                  >`
+                : ''
+            }
             ${item.metadata.description ? html`<p>${item.metadata.description}</p>` : ''}
             ${renderBlogTags(item.metadata.tags, data)}
           </li>
@@ -131,13 +137,17 @@ export function renderBlogPagination(pagination) {
   }
   return html`
     <nav class="atlas-blog-pagination" aria-label="Blog pages">
-      ${pagination.previousPath
-        ? html`<a href=${pagination.previousPath} rel="prev">Newer posts</a>`
-        : html`<span></span>`}
+      ${
+        pagination.previousPath
+          ? html`<a href=${pagination.previousPath} rel="prev">Newer posts</a>`
+          : html`<span></span>`
+      }
       <span>Page ${pagination.currentPage} of ${pagination.totalPages}</span>
-      ${pagination.nextPath
-        ? html`<a href=${pagination.nextPath} rel="next">Older posts</a>`
-        : html`<span></span>`}
+      ${
+        pagination.nextPath
+          ? html`<a href=${pagination.nextPath} rel="next">Older posts</a>`
+          : html`<span></span>`
+      }
     </nav>
   `;
 }
@@ -181,14 +191,16 @@ function atlasBlogDocument(pageData, data, mainContent) {
         />
         <link rel="stylesheet" href="${resolve('@rocket/js/layouts/atlasDoc.css', import.meta)}" />
         <link rel="stylesheet" href="${resolve('@rocket/js/layouts/atlasBlog.css', import.meta)}" />
-        ${data.feedPath
-          ? html`<link
-              rel="alternate"
-              type="application/atom+xml"
-              href=${data.feedPath}
-              title=${siteName}
-            />`
-          : ''}
+        ${
+          data.feedPath
+            ? html`<link
+                rel="alternate"
+                type="application/atom+xml"
+                href=${data.feedPath}
+                title=${siteName}
+              />`
+            : ''
+        }
         ${renderStylesheets(data.stylesheets)} ${headContent}
       `,
     },
@@ -220,12 +232,14 @@ export const atlasBlogIndexLayout = (pageData, data) => {
       <section class="atlas-blog-index">
         <div class="atlas-blog-intro">
           ${pageData.content}
-          ${data.feedPath
-            ? html`<a class="atlas-blog-feed-link" href=${data.feedPath}>
-                <rocket-icon library="bootstrap" name="rss" aria-hidden="true"></rocket-icon>
-                Feed
-              </a>`
-            : ''}
+          ${
+            data.feedPath
+              ? html`<a class="atlas-blog-feed-link" href=${data.feedPath}>
+                  <rocket-icon library="bootstrap" name="rss" aria-hidden="true"></rocket-icon>
+                  Feed
+                </a>`
+              : ''
+          }
         </div>
         ${renderBlogPostList(items, data, language)} ${renderBlogPagination(pageData.pagination)}
       </section>

package/src/layouts/atlas/atlasDocLayout.js

@@ -245,22 +245,28 @@ export const atlasDocLayout = (pageData, data) => {
 
         <main id="content" class="atlas-content">${pageData.content}</main>
 
-        ${pageNavigation.previous || pageNavigation.next
-          ? html`<nav id="prev-next" slot="main-footer" class="atlas-prev-next" aria-label="Page">
-              ${pageNavigation.previous
-                ? html`<rocket-previous-page
-                    .pageTree=${pageData.pageTree}
-                    .currentPath=${pageData.url}
-                  ></rocket-previous-page>`
-                : ''}
-              ${pageNavigation.next
-                ? html`<rocket-next-page
-                    .pageTree=${pageData.pageTree}
-                    .currentPath=${pageData.url}
-                  ></rocket-next-page>`
-                : ''}
-            </nav>`
-          : ''}
+        ${
+          pageNavigation.previous || pageNavigation.next
+            ? html`<nav id="prev-next" slot="main-footer" class="atlas-prev-next" aria-label="Page">
+                ${
+                  pageNavigation.previous
+                    ? html`<rocket-previous-page
+                        .pageTree=${pageData.pageTree}
+                        .currentPath=${pageData.url}
+                      ></rocket-previous-page>`
+                    : ''
+                }
+                ${
+                  pageNavigation.next
+                    ? html`<rocket-next-page
+                        .pageTree=${pageData.pageTree}
+                        .currentPath=${pageData.url}
+                      ></rocket-next-page>`
+                    : ''
+                }
+              </nav>`
+            : ''
+        }
 
         <aside slot="aside" class="atlas-toc">
           <rocket-toc toc=${serializedToc}></rocket-toc>

package/src/layouts/atlas/atlasHeroLayout.js

@@ -69,16 +69,18 @@ function renderTrustBadges(badges) {
 
         return html`
           <li>
-            ${href && icon
-              ? html`
-                  <rocket-social-link
-                    url=${href}
-                    name=${icon}
-                    label=${text}
-                    aria-label=${text}
-                  ></rocket-social-link>
-                `
-              : html`<span class="trust-badge-text">${text}</span>`}
+            ${
+              href && icon
+                ? html`
+                    <rocket-social-link
+                      url=${href}
+                      name=${icon}
+                      label=${text}
+                      aria-label=${text}
+                    ></rocket-social-link>
+                  `
+                : html`<span class="trust-badge-text">${text}</span>`
+            }
           </li>
         `;
       })}
@@ -142,13 +144,15 @@ function renderWhyCard(card) {
         <h3>${card.title}</h3>
         <p>${card.description}</p>
       </div>
-      ${card.tags?.length
-        ? html`
-            <ul class="tag-list" aria-label="${card.title} tags">
-              ${card.tags.map(tag => html`<li>${tag}</li>`)}
-            </ul>
-          `
-        : html``}
+      ${
+        card.tags?.length
+          ? html`
+              <ul class="tag-list" aria-label="${card.title} tags">
+                ${card.tags.map(tag => html`<li>${tag}</li>`)}
+              </ul>
+            `
+          : html``
+      }
     </article>
   `;
 }
@@ -303,25 +307,29 @@ export const atlasHeroLayout = (pageData, data) => {
             ${renderInstallPill(hero)} ${renderTrustBadges(hero.badges ?? [])}
           </div>
 
-          ${hero.logoNoText
-            ? html`
-                <div class="hero-art" aria-hidden="true">
-                  <div class="rocket-visual">
-                    <span class="spark spark-one"></span>
-                    <span class="spark spark-two"></span>
-                    <span class="spark spark-three"></span>
-                    <img src=${hero.logoNoText} alt="" width="370" />
+          ${
+            hero.logoNoText
+              ? html`
+                  <div class="hero-art" aria-hidden="true">
+                    <div class="rocket-visual">
+                      <span class="spark spark-one"></span>
+                      <span class="spark spark-two"></span>
+                      <span class="spark spark-three"></span>
+                      <img src=${hero.logoNoText} alt="" width="370" />
+                    </div>
                   </div>
-                </div>
-              `
-            : html``}
+                `
+              : html``
+          }
         </section>
         <div class="home-content">${pageData.content}</div>
         ${renderWhyRocket(data.whyRocketData)}
         ${renderHomeColumns(data.quickStartData, data.workflowData)}
-        ${data.featuresData?.length
-          ? html`<rocket-feature-list .features=${data.featuresData}></rocket-feature-list>`
-          : html``}
+        ${
+          data.featuresData?.length
+            ? html`<rocket-feature-list .features=${data.featuresData}></rocket-feature-list>`
+            : html``
+        }
       </main>
       <rocket-footer .data=${data.footerData}></rocket-footer>
     `,

package/src/layouts/atlas/atlasNotFoundLayout.js

@@ -40,9 +40,11 @@ export const atlasNotFoundLayout = (pageData, data) => {
             <div class="atlas-not-found-stars"></div>
             <div class="atlas-not-found-orbit"></div>
             <p class="atlas-not-found-code">404</p>
-            ${rocketLogo
-              ? html`<img class="atlas-not-found-rocket" src=${rocketLogo} alt="" />`
-              : html``}
+            ${
+              rocketLogo
+                ? html`<img class="atlas-not-found-rocket" src=${rocketLogo} alt="" />`
+                : html``
+            }
           </div>
         </main>
       </div>

package/src/layouts/layout-helper.js

@@ -30,23 +30,27 @@ export function document(
         <meta name="viewport" content="width=device-width, initial-scale=1" />
         <title>${title}</title>
         ${siteHeadMetadataTemplate(siteHeadMetadata)}
-        ${menu
-          ? html`<style>
-              body {
-                display: flex;
-              }
-              #menu {
-                margin-right: 1em;
-              }
-            </style>`
-          : ''}
+        ${
+          menu
+            ? html`<style>
+                body {
+                  display: flex;
+                }
+                #menu {
+                  margin-right: 1em;
+                }
+              </style>`
+            : ''
+        }
         ${data.clientCode} ${headContent}
       </head>
       <body>
-        ${menu
-          ? html`<nav id="menu" aria-label="Site">${defaultHtmlMenu(data.pageTree)}</nav>
-              <main id="content">${content}</main>`
-          : content}
+        ${
+          menu
+            ? html`<nav id="menu" aria-label="Site">${defaultHtmlMenu(data.pageTree)}</nav>
+                <main id="content">${content}</main>`
+            : content
+        }
       </body>
     </html>`;
 }
@@ -63,21 +67,27 @@ function siteHeadMetadataTemplate(metadata) {
     ${metadata.indexing === 'noindex' ? html`<meta name="robots" content="noindex" />` : ''}
     <link rel="canonical" href=${metadata.canonicalUrl} />
     ${metadata.icons?.ico ? html`<link rel="icon" href=${metadata.icons.ico} sizes="any" />` : ''}
-    ${metadata.icons?.svg
-      ? html`<link rel="icon" href=${metadata.icons.svg} type="image/svg+xml" />`
-      : ''}
-    ${metadata.icons?.appleTouchIcon
-      ? html`<link rel="apple-touch-icon" href=${metadata.icons.appleTouchIcon} />`
-      : ''}
+    ${
+      metadata.icons?.svg
+        ? html`<link rel="icon" href=${metadata.icons.svg} type="image/svg+xml" />`
+        : ''
+    }
+    ${
+      metadata.icons?.appleTouchIcon
+        ? html`<link rel="apple-touch-icon" href=${metadata.icons.appleTouchIcon} />`
+        : ''
+    }
     ${metadata.themeColor ? html`<meta name="theme-color" content=${metadata.themeColor} />` : ''}
     <meta property="og:site_name" content=${metadata.siteName} />
     <meta property="og:title" content=${metadata.title} />
     <meta property="og:description" content=${metadata.description} />
     <meta property="og:url" content=${metadata.canonicalUrl} />
     <meta property="og:type" content="website" />
-    ${metadata.socialPreview?.image
-      ? html`<meta property="og:image" content=${metadata.socialPreview.image} />`
-      : ''}
+    ${
+      metadata.socialPreview?.image
+        ? html`<meta property="og:image" content=${metadata.socialPreview.image} />`
+        : ''
+    }
     <meta
       name="twitter:card"
       content=${metadata.socialPreview?.image ? 'summary_large_image' : 'summary'}
@@ -85,8 +95,10 @@ function siteHeadMetadataTemplate(metadata) {
     <meta name="twitter:title" content=${metadata.title} />
     <meta name="twitter:description" content=${metadata.description} />
     <meta name="twitter:url" content=${metadata.canonicalUrl} />
-    ${metadata.socialPreview?.image
-      ? html`<meta name="twitter:image" content=${metadata.socialPreview.image} />`
-      : ''}
+    ${
+      metadata.socialPreview?.image
+        ? html`<meta name="twitter:image" content=${metadata.socialPreview.image} />`
+        : ''
+    }
   `;
 }

package/src/main.js

@@ -6,6 +6,7 @@ import { MessageChannel } from 'node:worker_threads';
 import { customElements } from '@lit-labs/ssr-dom-shim';
 import { readConfig } from './config.js';
 import { preferProjectPackagesPlugin } from './prefer-project-packages-plugin.js';
+import { getPages } from './pages.js';
 
 const configFilePath = process.argv[2] || undefined;
 const startOptions = readStartOptions(process.argv[3]);
@@ -49,6 +50,20 @@ let devServerConfig = {
   port: startOptions.port ?? 8888,
 };
 
+if (config.adapter?.adjustDevServerConfig) {
+  try {
+    devServerConfig = await config.adapter.adjustDevServerConfig(devServerConfig, {
+      pages: await getPages(process.cwd(), config.includeGlobs, config.excludeRegex),
+      projectRoot: process.cwd(),
+      config,
+    });
+  } catch (error) {
+    // Adapter startup checks are author-facing, so show the message like the CLI does.
+    // eslint-disable-next-line no-console
+    console.error(error instanceof Error && !process.env.ROCKET_DEBUG ? error.message : error);
+    process.exit(1);
+  }
+}
 devServerConfig = config.adjustDevServerConfig(devServerConfig);
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars

package/src/markdownCompiler.js

@@ -237,7 +237,11 @@ function extractDemoNames() {
     const node = /** @type {import('mdast').Code} */ (_node);
     if (isDemoCodeNode(node) && typeof node.value === 'string') {
       for (const exported of parseExports(node.value)[1]) {
-        demoNames.push(exported.ln || exported.n);
+        if (exported.type === 'direct') {
+          demoNames.push(exported.localName || exported.name);
+        } else if (exported.type === 'reexport') {
+          demoNames.push(exported.name);
+        }
       }
     }
   };

package/src/menus/MainMenu.js

@@ -39,19 +39,23 @@ export class MainMenu extends LitElement {
     classes[level] = true;
     return html`
       <li>
-        ${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))}
-            </ul>`
-          : ''}
+        ${
+          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))}
+              </ul>`
+            : ''
+        }
       </li>
     `;
   }