@rocket/js 0.1.2 → 0.2.1

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

@@ -210,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,
@@ -269,14 +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)}
+        ${renderStylesheets(data.stylesheets)} ${headContent}
       `,
     },
   );

package/src/layouts/atlas/atlasHeroLayout.js

@@ -262,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,
@@ -329,14 +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)}
+        ${renderStylesheets(data.stylesheets)} ${headContent}
       `,
     },
   );

package/src/layouts/atlas/atlasNotFoundLayout.js

@@ -1,27 +1,11 @@
 import { html } from 'lit';
 import { document } from '../layout-helper.js';
 import { resolve } from '../../resolve.js';
-import { renderStylesheets } from './atlasDocLayout.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
  */
@@ -33,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,
@@ -40,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)}
@@ -54,18 +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
+      headContent: html`<link
           rel="stylesheet"
           href="${resolve('@rocket/js/layouts/atlasNotFound.css', import.meta)}"
         />
-        ${renderStylesheets(data.stylesheets)}`,
+        ${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/main.js

@@ -5,6 +5,7 @@ import customRocketPlugin from './wds-plugin.js';
 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';
 
 const configFilePath = process.argv[2] || undefined;
 const startOptions = readStartOptions(process.argv[3]);
@@ -40,6 +41,7 @@ let devServerConfig = {
       defaultIconLibrary: config.defaultIconLibrary,
       watch: startOptions.watch,
     }),
+    preferProjectPackagesPlugin(),
   ],
   open: startOptions.open ?? true,
   nodeResolve: { exportConditions: ['browser'] },

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),
       });

package/src/menu.js

@@ -34,13 +34,14 @@ export function treeFromPages(pages) {
       continue;
     }
     const parts = getMenuParts(url, module);
+    if (parts.some(part => part.startsWith(':'))) {
+      // Dynamic paths have no single public URL, so they get no menu entry.
+      continue;
+    }
     let obj = children;
     /** @type {any} */
     let last = {};
     for (const part of parts) {
-      if (part.startsWith(':')) {
-        break;
-      }
       const get = obj.find(leaf => leaf.name === part);
       if (!get) {
         /** @type {import('@rocket/js/types.js').PageTree[]} */
@@ -137,19 +138,25 @@ function sortRecursive(children) {
 }
 
 /**
+ * The itemFn receives the rendered child list (or lit `nothing`) and must place
+ * it inside the returned item so nested lists stay valid HTML.
+ *
  * @param {import("@rocket/js/types.js").PageTree} tree
  * @param {string} listTagName
- * @param {(name: string, url: string, module: import("@rocket/js/types.js").Module, linkText: string) => import("lit").TemplateResult} itemFn
+ * @param {(name: string, url: string, module: import("@rocket/js/types.js").Module, linkText: string, children: import("lit").TemplateResult | typeof nothing) => import("lit").TemplateResult} itemFn
+ * @returns {import("lit").TemplateResult}
  */
 export function treeToHtml(tree, listTagName, itemFn) {
   return html`${unsafeHTML(`<${listTagName}>`)}${join(
-    tree.children.map(page => {
-      let a = itemFn(page.name, page.url, page.module, page.linkText);
-      if (page.children.length) {
-        a = html`${a}${treeToHtml(page, listTagName, itemFn)}`;
-      }
-      return a;
-    }),
+    tree.children.map(page =>
+      itemFn(
+        page.name,
+        page.url,
+        page.module,
+        page.linkText,
+        page.children.length ? treeToHtml(page, listTagName, itemFn) : nothing,
+      ),
+    ),
     nothing,
   )}${unsafeHTML(`</${listTagName}>`)}`;
 }
@@ -158,14 +165,13 @@ export function treeToHtml(tree, listTagName, itemFn) {
  * @param {import('@rocket/js/types.js').PageTree} pageTree
  */
 export function defaultHtmlMenu(pageTree) {
-  return treeToHtml(
-    pageTree,
-    'ul',
-    (_name, url, _module, linkText) =>
-      html`<li>
-        <a href=${url}>${linkText}</a>
-      </li>`,
-  );
+  return treeToHtml(pageTree, 'ul', (_name, url, module, linkText, children) => {
+    const menu = module.config.menu;
+    const noLink = !url || menu === false || (typeof menu === 'object' && menu?.noLink);
+    return html`<li>
+      ${noLink ? html`<span>${linkText}</span>` : html`<a href=${url}>${linkText}</a>`}${children}
+    </li>`;
+  });
 }
 
 /** Runs on: import-hook */

package/src/menus/MainMenu.js

@@ -32,15 +32,21 @@ export class MainMenu extends LitElement {
    */
   list(page, depth = 0) {
     const title = page.linkText;
+    const isCurrent = page.url === this.currentPath;
     /** @type {any} */
-    const classes = { current: page.url === this.currentPath };
+    const classes = { current: isCurrent };
     const level = `lvl-${depth}`;
     classes[level] = true;
     return html`
       <li>
-        <a href=${ifDefined(page.menuNoLink ? undefined : page.url)} class=${classMap(classes)}
-          >${title}</a
-        >
+        ${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))}

package/src/{static-page-module-loader.js → page-module-loader.js}

@@ -3,7 +3,12 @@ import { parseComponents } from './components.js';
 
 /** @typedef {import('./page-runtime.js').PageModuleLoaderOptions} PageModuleLoaderOptions */
 
-export function createStaticPageModuleLoader() {
+/**
+ * The Page Module Loader used by both the development server and static builds.
+ * Loading goes through Rocket's import hooks, which behave the same in both
+ * runtime environments.
+ */
+export function createPageModuleLoader() {
   return {
     /**
      * @param {PageModuleLoaderOptions} options

package/src/page-pagination.js

@@ -1,4 +1,4 @@
-import { URLPattern } from 'urlpattern-polyfill';
+import { routePattern } from './route-pattern.js';
 import { PageData } from './PageData.js';
 import { normalizeDocumentPath } from './standalone-demo-url.js';
 
@@ -229,7 +229,7 @@ function parsePaginatedArchivePath(pathname) {
  * @param {string} routePath
  */
 function matchPagePath(pathname, origin, routePath) {
-  const pattern = new URLPattern({ pathname: routePath });
+  const pattern = routePattern(routePath);
   return pattern.exec(pathname, origin);
 }