@rocket/js 0.1.1 → 0.2.0

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;
+}

package/src/layouts/atlas/atlasBlogLayout.js

@@ -0,0 +1,234 @@
+import { html } from 'lit';
+import { document } from '../layout-helper.js';
+import { resolve } from '../../resolve.js';
+import { webAwesomeComponents } from '@rocket/js/components/web-awesome.js';
+import { addBootstrapIconLibrary } from '../layout.js';
+import { rocketDemoComponents } from '../../components.js';
+import {
+  renderHeaderLogo,
+  renderHeaderNavLinks,
+  renderSocials,
+  renderStylesheets,
+} from './atlasDocLayout.js';
+
+/** @typedef {import('@rocket/js/types.js').BlogData} BlogData */
+/** @typedef {import('@rocket/js/types.js').PageCollectionEntry} PageCollectionEntry */
+
+/** @type {import('@rocket/js/types.js').Components} */
+export const atlasBlogComponents = {
+  'rocket-social-link': {
+    file: './components/RocketSocialLink.js',
+    className: 'RocketSocialLink',
+    loading: 'server',
+  },
+  ...rocketDemoComponents,
+  ...webAwesomeComponents,
+};
+
+/**
+ * @param {string} date date-only ISO string from Page Metadata
+ * @param {string | undefined} language
+ */
+export function formatBlogDate(date, language) {
+  const parsed = new Date(`${date}T00:00:00Z`);
+  if (Number.isNaN(parsed.getTime())) {
+    return date;
+  }
+  return new Intl.DateTimeFormat(language || 'en', {
+    dateStyle: 'long',
+    timeZone: 'UTC',
+  }).format(parsed);
+}
+
+/**
+ * @param {string[] | undefined} tags
+ * @param {BlogData} data
+ */
+export function renderBlogTags(tags, data) {
+  if (!tags || tags.length === 0) {
+    return '';
+  }
+  return html`
+    <ul class="atlas-blog-tags">
+      ${tags.map(
+        tag => html`
+          <li>
+            ${data.tagPathPrefix
+              ? html`<a href=${blogTagPath(data.tagPathPrefix, tag)} rel="tag">${tag}</a>`
+              : html`<span>${tag}</span>`}
+          </li>
+        `,
+      )}
+    </ul>
+  `;
+}
+
+/**
+ * @param {string} tagPathPrefix
+ * @param {string} tag
+ */
+export function blogTagPath(tagPathPrefix, tag) {
+  const prefix = tagPathPrefix.endsWith('/') ? tagPathPrefix : `${tagPathPrefix}/`;
+  return `${prefix}${tag}/`;
+}
+
+/**
+ * @param {import('@rocket/js/types.js').PageMetadata} metadata
+ * @param {BlogData} data
+ * @param {string | undefined} language
+ */
+export function renderBlogByline(metadata, data, language) {
+  const authors = metadata.authors || [];
+  if (!metadata.date && authors.length === 0 && !(metadata.tags || []).length) {
+    return '';
+  }
+  return html`
+    <div class="atlas-blog-byline">
+      ${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>
+  `;
+}
+
+/**
+ * @param {PageCollectionEntry[]} items
+ * @param {BlogData} data
+ * @param {string | undefined} language
+ */
+export function renderBlogPostList(items, data, language) {
+  if (items.length === 0) {
+    return html`<p class="atlas-blog-empty">No posts yet.</p>`;
+  }
+  return html`
+    <ol class="atlas-blog-post-list" reversed>
+      ${items.map(
+        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.description ? html`<p>${item.metadata.description}</p>` : ''}
+            ${renderBlogTags(item.metadata.tags, data)}
+          </li>
+        `,
+      )}
+    </ol>
+  `;
+}
+
+/**
+ * @param {import('@rocket/js/types.js').PagePagination | undefined} pagination
+ */
+export function renderBlogPagination(pagination) {
+  if (!pagination || pagination.totalPages <= 1) {
+    return '';
+  }
+  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>`}
+      <span>Page ${pagination.currentPage} of ${pagination.totalPages}</span>
+      ${pagination.nextPath
+        ? html`<a href=${pagination.nextPath} rel="next">Older posts</a>`
+        : html`<span></span>`}
+    </nav>
+  `;
+}
+
+/**
+ * Shared Atlas blog document chrome for post and index layouts.
+ *
+ * @param {import('../../PageData.js').PageData} pageData
+ * @param {BlogData} data
+ * @param {unknown} mainContent
+ */
+function atlasBlogDocument(pageData, data, mainContent) {
+  addBootstrapIconLibrary(pageData);
+  const cssPath = resolve('@rocket/js/docs/assets/prism-one-light.css', import.meta);
+  const siteName = pageData.siteHeadMetadata?.siteName ?? pageData.title;
+  const headContent = data.headContent?.({ pageData });
+
+  return document(
+    pageData,
+    html`
+      <div class="atlas-blog">
+        <header class="atlas-header atlas-blog-header">
+          <a href=${data.headerData.homeLink} class="logo-header">
+            ${renderHeaderLogo(data.headerData.logo, siteName)}
+          </a>
+          <nav class="atlas-header-links" aria-label="Primary navigation">
+            ${renderHeaderNavLinks(data.headerData.navLinks)}
+            ${renderSocials(data.headerData.socials, siteName)}
+          </nav>
+        </header>
+        <main id="content" class="atlas-blog-content">${mainContent}</main>
+      </div>
+    `,
+    {
+      menu: false,
+      headContent: html`
+        <link rel="stylesheet" href=${cssPath} />
+        <link
+          rel="stylesheet"
+          href="${resolve('@awesome.me/webawesome/dist/styles/webawesome.css', import.meta)}"
+        />
+        <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}
+            />`
+          : ''}
+        ${renderStylesheets(data.stylesheets)} ${headContent}
+      `,
+    },
+  );
+}
+
+/** @type {import('@rocket/js/types.js').Layout<BlogData>} */
+export const atlasPostLayout = (pageData, data) => {
+  const language = pageData.siteHeadMetadata?.language;
+  return atlasBlogDocument(
+    pageData,
+    data,
+    html`
+      <article class="atlas-blog-post">
+        ${renderBlogByline(pageData.metadata, data, language)} ${pageData.content}
+      </article>
+    `,
+  );
+};
+
+/** @type {import('@rocket/js/types.js').Layout<BlogData>} */
+export const atlasBlogIndexLayout = (pageData, data) => {
+  const language = pageData.siteHeadMetadata?.language;
+  const items = pageData.pagination?.items || [];
+  return atlasBlogDocument(
+    pageData,
+    data,
+    html`
+      <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>`
+            : ''}
+        </div>
+        ${renderBlogPostList(items, data, language)} ${renderBlogPagination(pageData.pagination)}
+      </section>
+    `,
+  );
+};

package/src/layouts/atlas/atlasDocLayout.js

@@ -119,6 +119,13 @@ export function renderHeaderNav(links = []) {
   `;
 }
 
+/**
+ * @param {string[] | undefined} stylesheets
+ */
+export function renderStylesheets(stylesheets = []) {
+  return stylesheets.map(href => html`<link rel="stylesheet" href=${href} />`);
+}
+
 /**
  * @param {import('@rocket/js/types.js').PageMetadataCustomValue | undefined} customValue
  * @returns {import('@rocket/js/types.js').AtlasDocAsideTip | false | undefined}
@@ -203,6 +210,7 @@ export const atlasDocLayout = (pageData, data) => {
   const serializedToc = serializeToc(pageData.toc);
   const navigationIconServerBudget =
     data.navigationIconServerBudget ?? DEFAULT_ATLAS_DOC_NAVIGATION_ICON_SERVER_BUDGET;
+  const headContent = data.headContent?.({ pageData });
 
   return document(
     pageData,
@@ -262,13 +270,14 @@ export const atlasDocLayout = (pageData, data) => {
     `,
     {
       menu: false,
-      headerContent: html`
+      headContent: html`
         <link rel="stylesheet" href=${cssPath} />
         <link
           rel="stylesheet"
           href="${resolve('@awesome.me/webawesome/dist/styles/webawesome.css', import.meta)}"
         />
         <link rel="stylesheet" href="${resolve('@rocket/js/layouts/atlasDoc.css', import.meta)}" />
+        ${renderStylesheets(data.stylesheets)} ${headContent}
       `,
     },
   );

package/src/layouts/atlas/atlasHeroLayout.js

@@ -3,7 +3,12 @@ import { document } from '../layout-helper.js';
 import { resolve } from '../../resolve.js';
 import { webAwesomeComponents } from '@rocket/js/components/web-awesome.js';
 import { addBootstrapIconLibrary } from '../layout.js';
-import { renderHeaderLogo, renderHeaderNav, renderSocials } from './atlasDocLayout.js';
+import {
+  renderHeaderLogo,
+  renderHeaderNav,
+  renderSocials,
+  renderStylesheets,
+} from './atlasDocLayout.js';
 import { rocketDemoComponents } from '../../components.js';
 
 /** @type {import('@rocket/js/types.js').Components} */
@@ -257,10 +262,8 @@ export const atlasHeroLayout = (pageData, data) => {
   const heroEyebrow = hero.eyebrow ?? hero.sloganTop;
   const heroTitle = hero.title ?? hero.sloganBottom ?? pageData.title;
   const siteName = pageData.siteHeadMetadata?.siteName ?? pageData.title;
-  const navLinks = data.headerData.navLinks ?? [
-    { text: 'Docs', href: hero.documentationLink },
-    { text: 'Examples', href: '/examples' },
-  ];
+  const navLinks = data.headerData.navLinks ?? [{ text: 'Docs', href: hero.documentationLink }];
+  const headContent = data.headContent?.({ pageData });
 
   return document(
     pageData,
@@ -324,13 +327,14 @@ export const atlasHeroLayout = (pageData, data) => {
     `,
     {
       menu: false,
-      headerContent: html`
+      headContent: html`
         <link rel="stylesheet" href=${cssPath} />
         <link
           rel="stylesheet"
           href="${resolve('@awesome.me/webawesome/dist/styles/webawesome.css', import.meta)}"
         />
         <link rel="stylesheet" href="${resolve('@rocket/js/layouts/atlasHero.css', import.meta)}" />
+        ${renderStylesheets(data.stylesheets)} ${headContent}
       `,
     },
   );

package/src/layouts/atlas/atlasNotFoundLayout.js

@@ -1,26 +1,11 @@
 import { html } from 'lit';
 import { document } from '../layout-helper.js';
 import { resolve } from '../../resolve.js';
+import { renderHeaderLogo, renderStylesheets } from './atlasDocLayout.js';
 
 /** @type {import('@rocket/js/types.js').Components} */
 export const atlasNotFoundComponents = {};
 
-/**
- * Renders the header logo.
- * @param {Array<string>} logo
- */
-function renderHeaderLogo(logo) {
-  if (logo.length === 1) {
-    return html`<img src=${logo[0]} alt="Logo" width="130" />`;
-  } else if (logo.length === 2) {
-    return html`
-      <img src=${logo[0]} alt="Logo" width="36" />
-      <img src=${logo[1]} alt="Logo Text" width="88" />
-    `;
-  }
-  return html`<b>Header logo should only contain one or two images.</b>`;
-}
-
 /**
  * @param {Array<{url: string, name: string, label?: string}>} socials
  */
@@ -32,6 +17,8 @@ function renderSocialLinks(socials) {
 export const atlasNotFoundLayout = (pageData, data) => {
   const homeLink = data.headerData.homeLink || '/';
   const rocketLogo = data.headerData.logo[0];
+  const siteName = pageData.siteHeadMetadata?.siteName ?? pageData.title;
+  const headContent = data.headContent?.({ pageData });
 
   return document(
     pageData,
@@ -39,7 +26,7 @@ export const atlasNotFoundLayout = (pageData, data) => {
       <div class="atlas-not-found">
         <header class="atlas-not-found-header">
           <a href=${homeLink} class="atlas-not-found-logo">
-            ${renderHeaderLogo(data.headerData.logo)}
+            ${renderHeaderLogo(data.headerData.logo, siteName)}
           </a>
           <nav class="atlas-not-found-links" aria-label="Project links">
             ${renderSocialLinks(data.headerData.socials)}
@@ -53,17 +40,20 @@ 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>
-            <img class="atlas-not-found-rocket" src=${rocketLogo} alt="" />
+            ${rocketLogo
+              ? html`<img class="atlas-not-found-rocket" src=${rocketLogo} alt="" />`
+              : html``}
           </div>
         </main>
       </div>
     `,
     {
       menu: false,
-      headerContent: html`<link
-        rel="stylesheet"
-        href="${resolve('@rocket/js/layouts/atlasNotFound.css', import.meta)}"
-      />`,
+      headContent: html`<link
+          rel="stylesheet"
+          href="${resolve('@rocket/js/layouts/atlasNotFound.css', import.meta)}"
+        />
+        ${renderStylesheets(data.stylesheets)} ${headContent}`,
     },
   );
 };

package/src/layouts/layout-helper.js

@@ -11,7 +11,7 @@ import { defaultHtmlMenu } from '../menu.js';
  * @param {Object} [options]
  * @param {LitHTML} [options.title]
  * @param {'html' | false} [options.menu] render a default menu. set to false if you want your own
- * @param {LitHTML} [options.headerContent]
+ * @param {LitHTML} [options.headContent]
  */
 export function document(
   data,
@@ -19,7 +19,7 @@ export function document(
   {
     title = data.siteHeadMetadata?.title ?? data.title,
     menu = 'html',
-    headerContent = undefined,
+    headContent = undefined,
   } = {},
 ) {
   const siteHeadMetadata = data.siteHeadMetadata;
@@ -40,12 +40,12 @@ export function document(
               }
             </style>`
           : ''}
-        ${data.clientCode} ${headerContent}
+        ${data.clientCode} ${headContent}
       </head>
       <body>
         ${menu
-          ? html`<div id="menu">${defaultHtmlMenu(data.pageTree)}</div>
-              <div id="content">${content}</div>`
+          ? html`<nav id="menu" aria-label="Site">${defaultHtmlMenu(data.pageTree)}</nav>
+              <main id="content">${content}</main>`
           : content}
       </body>
     </html>`;

package/src/layouts/layout.js

@@ -9,7 +9,7 @@ export const layout = data => {
   addBootstrapIconLibrary(data);
   return document(data, data.content, {
     menu: 'html',
-    headerContent: html`
+    headContent: html`
       <link
         rel="stylesheet"
         href="${resolve('@rocket/js/docs/assets/prism-one-light.css', import.meta)}"
@@ -27,7 +27,7 @@ export const singleDemoLayout = data => {
   addBootstrapIconLibrary(data);
   return document(data, data.content, {
     menu: false,
-    headerContent: html`
+    headContent: html`
       <link
         rel="stylesheet"
         href="${resolve('@awesome.me/webawesome/dist/styles/webawesome.css', import.meta)}"

package/src/loaded-page-module.js

@@ -92,6 +92,8 @@ function normalizeMarkdownPageContent(rawModule, { parseComponents }) {
  */
 function hasBrowserLoadedComponents(components) {
   return Object.values(components).some(
-    component => component.loading === 'client' || component.loading.startsWith('hydrate:'),
+    component =>
+      component.loading === 'client' ||
+      (typeof component.loading === 'string' && component.loading.startsWith('hydrate:')),
   );
 }

package/src/markdownCompiler.js

@@ -5,7 +5,7 @@ import rehypeRaw from 'rehype-raw';
 import { unified } from 'unified';
 import { visit } from 'unist-util-visit';
 import { extractMdCode } from './extractCode.js';
-import { mdToJs, mdToJsSingleDemo } from './transform.js';
+import { isDemoCodeNode, mdToJs, mdToJsSingleDemo } from './transform.js';
 import { init, parse as parseExports } from 'es-module-lexer';
 import ts from 'typescript';
 import { parseRequestDemoMetadata } from './requestDemoMetadata.js';
@@ -235,7 +235,7 @@ function extractDemoNames() {
   /** @type {import('unist-util-visit').Visitor} */
   const visitor = _node => {
     const node = /** @type {import('mdast').Code} */ (_node);
-    if (node.lang === 'js' && node.meta === 'demo' && typeof node.value === 'string') {
+    if (isDemoCodeNode(node) && typeof node.value === 'string') {
       for (const exported of parseExports(node.value)[1]) {
         demoNames.push(exported.ln || exported.n);
       }

package/src/markdownHook.js

@@ -102,7 +102,11 @@ export async function resolve(specifier, context, nextResolve) {
       },
     };
     if (match[0] === 'Setup' && isLocalFile(url)) {
-      await sendPort.sendAndWait({
+      // Fire-and-forget: awaiting a reply here can deadlock. The main thread
+      // blocks in Atomics.wait during e.g. a nested module.register() call, so
+      // it may be unable to answer until this resolve returns. postMessage
+      // delivery is ordered, which is all the dependency tracking needs.
+      sendPort.postMessage({
         parent: getPath(/** @type {string} */ (context.parentURL)),
         url: getPath(resolve.url),
       });
@@ -116,7 +120,8 @@ export async function resolve(specifier, context, nextResolve) {
         ...resolve.importAttributes,
         type: 'cache' + lastReload.toString(36),
       };
-      await sendPort.sendAndWait({
+      // Fire-and-forget, see above.
+      sendPort.postMessage({
         parent: getPath(/** @type {string} */ (context.parentURL)),
         url: getPath(resolve.url),
       });