@docpensieve/core 0.4.0-beta.1 → 0.4.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docpensieve/core",
-  "version": "0.4.0-beta.1",
+  "version": "0.4.0-beta.2",
   "description": "DocPensieve engine: loading, MDX compilation, structured data, site generation",
   "type": "module",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/shared": "0.4.0-beta.1",
+    "@docpensieve/shared": "0.4.0-beta.2",
     "@mdx-js/mdx": "^3.1.1",
     "@shikijs/rehype": "^4.4.3",
     "gray-matter": "^4.0.3",

package/src/config.js

@@ -39,8 +39,11 @@ import {
  * @property {{ framework: string, darkMode?: string, toggle?: boolean, tokens?: Record<string, string>, css?: string, source?: string }} theme
  * @property {string} sidebar     `'auto'`, or the path of a description.
  * @property {string} [authors]   Path of a JSON describing the authors, read in each version folder.
- * @property {{ label: string, href: string, version?: string }[]} [headerLinks]
- *   Links of the header, beside the version switcher.
+ * @property {{ label: string, href?: string, version?: string, columns?: { title?: string, items: { label: string, href: string, version?: string }[] }[] }[]} [headerLinks]
+ *   Links of the header, beside the version switcher. An entry carrying
+ *   `columns` opens a panel of links instead of leading anywhere itself.
+ * @property {boolean} [foldedSidebar] Categories of the menu fold, opened on
+ *   the branch of the page being read.
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.
  * @property {{ enabled: boolean }} jsonld
@@ -80,6 +83,9 @@ export const DEFAULT_CONFIG = Object.freeze({
   // No link in the header by default: the version switcher and the search
   // field are there already.
   headerLinks: [],
+  // The menu shows whole by default: a documentation of a few dozen pages
+  // reads better open than behind folds. Long ones turn this on.
+  foldedSidebar: false,
   globalComponents: true,
   scrollToTop: true,
   jsonld: { enabled: true },
@@ -279,29 +285,69 @@ export function normalizeConfig(userConfig) {
       });
     }
     const slugs = new Set(config.versions.map((version) => version.slug));
-    for (const link of config.headerLinks) {
-      if (!link || typeof link.label !== 'string' || link.label.trim() === '') {
-        throw new ConfigError(`A header link has no label: ${JSON.stringify(link)}.`, {
-          hint: "Write { label: 'Examples', href: '/examples/' }.",
-        });
-      }
+
+    /** @param {any} link @param {string} where */
+    const checkTarget = (link, where) => {
       if (
         typeof link.href !== 'string' ||
         !(link.href.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(link.href))
       ) {
-        throw new ConfigError(
-          `The header link "${link.label}" needs an absolute target: "${String(link.href)}".`,
-          {
-            hint: "Start from the root of the version — '/examples/' — or give a full address.",
-          },
-        );
+        throw new ConfigError(`${where} needs an absolute target: "${String(link.href)}".`, {
+          hint: "Start from the root of the version — '/examples/' — or give a full address.",
+        });
       }
       if (link.version !== undefined && !slugs.has(link.version)) {
-        throw new ConfigError(
-          `The header link "${link.label}" names an unknown version: "${String(link.version)}".`,
-          { hint: `Declared versions: ${[...slugs].join(', ')}.` },
-        );
+        throw new ConfigError(`${where} names an unknown version: "${String(link.version)}".`, {
+          hint: `Declared versions: ${[...slugs].join(', ')}.`,
+        });
       }
+    };
+
+    for (const link of config.headerLinks) {
+      if (!link || typeof link.label !== 'string' || link.label.trim() === '') {
+        throw new ConfigError(`A header link has no label: ${JSON.stringify(link)}.`, {
+          hint: "Write { label: 'Examples', href: '/examples/' }.",
+        });
+      }
+
+      // An entry either leads somewhere, or opens a panel of links: both at
+      // once would leave a click meaning two things.
+      if (link.columns !== undefined) {
+        if (!Array.isArray(link.columns) || link.columns.length === 0) {
+          throw new ConfigError(`The columns of "${link.label}" must be a list of columns.`, {
+            hint: "Write columns: [{ title: 'Guide', items: [{ label: 'Install', href: '/guide/install/' }] }].",
+          });
+        }
+        if (link.href !== undefined) {
+          throw new ConfigError(`The header entry "${link.label}" has both href and columns.`, {
+            hint: 'An entry either leads somewhere, or opens a panel: drop one of the two.',
+          });
+        }
+        for (const column of link.columns) {
+          if (!column || !Array.isArray(column.items) || column.items.length === 0) {
+            throw new ConfigError(`A column of "${link.label}" holds no link.`, {
+              hint: "Every column needs items: [{ label: 'Install', href: '/guide/install/' }].",
+            });
+          }
+          if (column.title !== undefined && typeof column.title !== 'string') {
+            throw new ConfigError(`A column title of "${link.label}" must be text.`, {
+              hint: 'Either write a title, or leave the field out.',
+            });
+          }
+          for (const item of column.items) {
+            if (!item || typeof item.label !== 'string' || item.label.trim() === '') {
+              throw new ConfigError(
+                `A link of "${link.label}" has no label: ${JSON.stringify(item)}.`,
+                { hint: "Write { label: 'Install', href: '/guide/install/' }." },
+              );
+            }
+            checkTarget(item, `The link "${item.label}" of "${link.label}"`);
+          }
+        }
+        continue;
+      }
+
+      checkTarget(link, `The header link "${link.label}"`);
     }
   }
 

package/src/generator.js

@@ -28,7 +28,12 @@ import { buildFeed, buildRobots, buildSitemap } from './discovery.js';
 import { imageSize } from './image-size.js';
 import { minifyCss } from './minify-css.js';
 import { SEARCH_SLUG, htmlToText, searchPageContent } from './search-index.js';
-import { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
+import {
+  buildSidebar,
+  buildSidebarFromDescription,
+  collectSectionTitles,
+  foldSidebar,
+} from './sidebar.js';
 import { StructuredDataBuilder } from './structured-data.js';
 
 /** Template folder, resolved from this module rather than from the cwd. */
@@ -245,6 +250,7 @@ export class SiteGenerator {
         ? await this.#describedSidebar(sourceDir, docs, pageUrl, version.folder)
         : null;
     const sidebar = described ?? buildSidebar(docs, pageUrl, { brand: this.config.projectName });
+    const folded = this.config.foldedSidebar === true;
     const breadcrumbTitles = collectSectionTitles(docs);
     const layout = await this.#loadLayout();
     const classes = this.#classes();
@@ -276,13 +282,29 @@ export class SiteGenerator {
     // Links of the header, resolved once per version. A link naming a version
     // leads there from every version: a section written in one version only
     // stays reachable from the others.
-    const headerLinks = (this.config.headerLinks ?? []).map((link) => ({
-      label: link.label,
-      href: EXTERNAL_PREVIEW.test(link.href)
+    /** @param {{ href: string, version?: string }} link */
+    const headerTarget = (link) =>
+      EXTERNAL_PREVIEW.test(link.href)
         ? link.href
         : joinUrl(this.config.baseUrl, 'versions', link.version ?? version.slug) +
-          link.href.replace(/^\/+/, ''),
-    }));
+          link.href.replace(/^\/+/, '');
+
+    const headerLinks = (this.config.headerLinks ?? []).map((link) =>
+      link.columns
+        ? {
+            label: link.label,
+            columns: link.columns.map((column) => ({
+              title: column.title,
+              items: column.items.map((item) => ({ label: item.label, href: headerTarget(item) })),
+            })),
+          }
+        : // Without columns the configuration has checked the target: an entry
+          // that leads nowhere and opens nothing never gets here.
+          {
+            label: link.label,
+            href: headerTarget({ href: String(link.href), version: link.version }),
+          },
+    );
 
     const shell = {
       lang: this.config.lang ?? 'en',
@@ -436,7 +458,10 @@ export class SiteGenerator {
         noindex: version.prerelease === true,
         byline,
         tags: wide ? [] : pageTags(doc.frontmatter.tags),
-        sidebar: wide ? [] : sidebar,
+        // Folded, the menu opens on the branch of the page being rendered, so
+        // it is prepared per page rather than once per version.
+        sidebar: wide ? [] : folded ? foldSidebar(sidebar, url) : sidebar,
+        foldedSidebar: folded,
         toc: wide ? [] : toc,
         preloads,
         content: html,

package/src/index.js

@@ -19,6 +19,7 @@
  * @typedef {import('./compiler.js').TocEntry} TocEntry
  * @typedef {import('./compiler.js').Preload} Preload
  * @typedef {import('./sidebar.js').SidebarNode} SidebarNode
+ * @typedef {import('./sidebar.js').FoldedNode} FoldedNode
  * @typedef {import('./authors.js').Author} Author
  * @typedef {import('./authors.js').Byline} Byline
  */
@@ -34,6 +35,11 @@ export { DocLoader } from './loader.js';
 export { Compiler } from './compiler.js';
 export { StructuredDataBuilder } from './structured-data.js';
 export { SiteGenerator } from './generator.js';
-export { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
+export {
+  buildSidebar,
+  buildSidebarFromDescription,
+  collectSectionTitles,
+  foldSidebar,
+} from './sidebar.js';
 export { buildFeed, buildRobots, buildSitemap } from './discovery.js';
 export { buildAuthorTable, buildByline, readDate, resolvePageAuthors } from './authors.js';

package/src/sidebar.js

@@ -104,6 +104,58 @@ export function collectSectionTitles(docs) {
   return titles;
 }
 
+/**
+ * Prepares a menu whose categories fold, for the page being rendered.
+ *
+ * Two things change. Every category carries `open`, true along the branch
+ * holding the current page: a long menu opens where the reader stands, and
+ * stays closed everywhere else. And a category that is itself a page gains
+ * that page as its first entry — folded, its title becomes the handle of the
+ * fold, which cannot be a link as well without a click meaning two things.
+ *
+ * The tree is rebuilt rather than marked in place: it is shared by every page
+ * of the version, and marking it would leave one page's branch open on all the
+ * others.
+ *
+ * @typedef {object} FoldedNode
+ * @property {string} label
+ * @property {string | null} url
+ * @property {FoldedNode[]} items
+ * @property {boolean} [open] Whether the category starts open. Absent on a
+ *   plain entry, which has nothing to fold.
+ */
+
+/**
+ * @param {SidebarNode[]} nodes
+ * @param {string} [currentUrl] URL of the page being rendered.
+ * @returns {FoldedNode[]}
+ */
+export function foldSidebar(nodes, currentUrl = '') {
+  return nodes.map((node) => {
+    if (node.items.length === 0) return { ...node };
+
+    const items = foldSidebar(
+      node.url ? [{ label: node.label, url: node.url, items: [] }, ...node.items] : node.items,
+      currentUrl,
+    );
+
+    // Open when the reader is inside: on the category's own page, or on any
+    // page it holds, however deep.
+    return { ...node, items, open: node.url === currentUrl || holds(items, currentUrl) };
+  });
+}
+
+/**
+ * Whether a branch holds the current page.
+ *
+ * @param {FoldedNode[]} nodes
+ * @param {string} currentUrl
+ * @returns {boolean}
+ */
+function holds(nodes, currentUrl) {
+  return nodes.some((node) => node.url === currentUrl || holds(node.items, currentUrl));
+}
+
 /**
  * An entry of a sidebar description: a page path, or an object — see
  * `buildSidebarFromDescription`.

package/templates/header-menu.hbs

@@ -15,7 +15,29 @@ a row on a wide screen, behind a menu button on a narrow one. --}}
 {{/if}}
 {{#if headerLinks.length}}
 <ul class="{{{cls.headerLinks}}}">
-  {{#each headerLinks}}<li><a href="{{href}}">{{label}}</a></li>{{/each}}
+  {{#each headerLinks}}
+  <li>
+    {{#if columns.length}}
+    {{!-- A panel of links rather than a link: a details again, so that it
+    opens without a script, and folds into the menu of a narrow screen. --}}
+    <details class="{{{@root.cls.mega}}}">
+      <summary>{{label}}</summary>
+      <div class="{{{@root.cls.megaPanel}}}">
+        {{#each columns}}
+        <div class="{{{@root.cls.megaColumn}}}">
+          {{#if title}}<p class="{{{@root.cls.megaTitle}}}">{{title}}</p>{{/if}}
+          <ul>
+            {{#each items}}<li><a href="{{href}}">{{label}}</a></li>{{/each}}
+          </ul>
+        </div>
+        {{/each}}
+      </div>
+    </details>
+    {{else}}
+    <a href="{{href}}">{{label}}</a>
+    {{/if}}
+  </li>
+  {{/each}}
 </ul>
 {{/if}}
 {{!-- A plain form: it leads to the search page, and needs no script. --}}

package/templates/layout.hbs

@@ -85,10 +85,19 @@
     </header>
 
     <div class="{{#if wide}}{{{cls.shellWide}}}{{else}}{{{cls.shell}}}{{/if}}">
+      {{!-- Written once, shown twice: the column on a wide screen, and a folded
+      menu above the content on a narrow one, where a full menu would eat the
+      first screen. Only one of the two is displayed at a time. --}}
       {{#if sidebar.length}}
       <nav class="{{{cls.sidebar}}}" aria-label="Documentation navigation">
         {{> navItems sidebar}}
       </nav>
+      <details class="{{{cls.sidebarMenu}}}">
+        <summary>Documentation menu</summary>
+        <nav aria-label="Documentation navigation">
+          {{> navItems sidebar}}
+        </nav>
+      </details>
       {{/if}}
 
       <main class="{{{cls.main}}}" id="content" tabindex="-1">

package/templates/nav-items.hbs

@@ -1,14 +1,30 @@
 <ul class="{{{@root.cls.nav}}}">
   {{#each this}}
   <li class="{{{@root.cls.navItem}}}{{#if items.length}} {{{@root.cls.navItemParent}}}{{/if}}">
+    {{#if items.length}}
+    {{#if @root.foldedSidebar}}
+    {{!-- Folded, a category is a native details: it opens without a script,
+    and starts open on the branch the reader is in. Its own page sits as the
+    first entry, since the handle of the fold cannot be a link as well. --}}
+    <details class="{{{@root.cls.navGroup}}}"{{#if open}} open{{/if}}>
+      <summary class="{{{@root.cls.navSummary}}}">{{label}}</summary>
+      {{> navItems items}}
+    </details>
+    {{else}}
     {{#if url}}
     <a class="{{{@root.cls.navLink}}}" href="{{url}}"{{#if (eq url @root.currentUrl)}} aria-current="page"{{/if}}>{{label}}</a>
     {{else}}
     <span class="{{{@root.cls.navLabel}}}">{{label}}</span>
     {{/if}}
-    {{#if items.length}}
     {{> navItems items}}
     {{/if}}
+    {{else}}
+    {{#if url}}
+    <a class="{{{@root.cls.navLink}}}" href="{{url}}"{{#if (eq url @root.currentUrl)}} aria-current="page"{{/if}}>{{label}}</a>
+    {{else}}
+    <span class="{{{@root.cls.navLabel}}}">{{label}}</span>
+    {{/if}}
+    {{/if}}
   </li>
   {{/each}}
 </ul>

package/types/config.d.ts

@@ -76,13 +76,27 @@ export type DocPensieveConfig = {
      */
     authors?: string;
     /**
-     * Links of the header, beside the version switcher.
+     * Links of the header, beside the version switcher. An entry carrying
+     * `columns` opens a panel of links instead of leading anywhere itself.
      */
     headerLinks?: {
         label: string;
-        href: string;
+        href?: string;
         version?: string;
+        columns?: {
+            title?: string;
+            items: {
+                label: string;
+                href: string;
+                version?: string;
+            }[];
+        }[];
     }[];
+    /**
+     * Categories of the menu fold, opened on
+     * the branch of the page being read.
+     */
+    foldedSidebar?: boolean;
     globalComponents: boolean;
     /**
      * Back-to-top button on every page.
@@ -150,8 +164,11 @@ export type DocPensieveConfig = {
  * @property {{ framework: string, darkMode?: string, toggle?: boolean, tokens?: Record<string, string>, css?: string, source?: string }} theme
  * @property {string} sidebar     `'auto'`, or the path of a description.
  * @property {string} [authors]   Path of a JSON describing the authors, read in each version folder.
- * @property {{ label: string, href: string, version?: string }[]} [headerLinks]
- *   Links of the header, beside the version switcher.
+ * @property {{ label: string, href?: string, version?: string, columns?: { title?: string, items: { label: string, href: string, version?: string }[] }[] }[]} [headerLinks]
+ *   Links of the header, beside the version switcher. An entry carrying
+ *   `columns` opens a panel of links instead of leading anywhere itself.
+ * @property {boolean} [foldedSidebar] Categories of the menu fold, opened on
+ *   the branch of the page being read.
  * @property {boolean} globalComponents
  * @property {boolean} scrollToTop Back-to-top button on every page.
  * @property {{ enabled: boolean }} jsonld

package/types/index.d.ts

@@ -14,6 +14,7 @@ export type CompileResult = import('./compiler.js').CompileResult;
 export type TocEntry = import('./compiler.js').TocEntry;
 export type Preload = import('./compiler.js').Preload;
 export type SidebarNode = import('./sidebar.js').SidebarNode;
+export type FoldedNode = import('./sidebar.js').FoldedNode;
 export type Author = import('./authors.js').Author;
 export type Byline = import('./authors.js').Byline;
 /**
@@ -27,6 +28,7 @@ export type Byline = import('./authors.js').Byline;
  * @typedef {import('./compiler.js').TocEntry} TocEntry
  * @typedef {import('./compiler.js').Preload} Preload
  * @typedef {import('./sidebar.js').SidebarNode} SidebarNode
+ * @typedef {import('./sidebar.js').FoldedNode} FoldedNode
  * @typedef {import('./authors.js').Author} Author
  * @typedef {import('./authors.js').Byline} Byline
  */
@@ -35,6 +37,6 @@ export { DocLoader } from './loader.js';
 export { Compiler } from './compiler.js';
 export { StructuredDataBuilder } from './structured-data.js';
 export { SiteGenerator } from './generator.js';
-export { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
+export { buildSidebar, buildSidebarFromDescription, collectSectionTitles, foldSidebar, } from './sidebar.js';
 export { buildFeed, buildRobots, buildSitemap } from './discovery.js';
 export { buildAuthorTable, buildByline, readDate, resolvePageAuthors } from './authors.js';

package/types/sidebar.d.ts

@@ -58,6 +58,42 @@ export declare function buildSidebar(docs: import('./loader.js').Doc[], toUrl?:
  * @returns {Record<string, string>} Full folder slug to title.
  */
 export declare function collectSectionTitles(docs: import('./loader.js').Doc[]): Record<string, string>;
+export type FoldedNode = {
+    label: string;
+    url: string | null;
+    items: FoldedNode[];
+    /**
+     * Whether the category starts open. Absent on a
+     * plain entry, which has nothing to fold.
+     */
+    open?: boolean;
+};
+/**
+ * Prepares a menu whose categories fold, for the page being rendered.
+ *
+ * Two things change. Every category carries `open`, true along the branch
+ * holding the current page: a long menu opens where the reader stands, and
+ * stays closed everywhere else. And a category that is itself a page gains
+ * that page as its first entry — folded, its title becomes the handle of the
+ * fold, which cannot be a link as well without a click meaning two things.
+ *
+ * The tree is rebuilt rather than marked in place: it is shared by every page
+ * of the version, and marking it would leave one page's branch open on all the
+ * others.
+ *
+ * @typedef {object} FoldedNode
+ * @property {string} label
+ * @property {string | null} url
+ * @property {FoldedNode[]} items
+ * @property {boolean} [open] Whether the category starts open. Absent on a
+ *   plain entry, which has nothing to fold.
+ */
+/**
+ * @param {SidebarNode[]} nodes
+ * @param {string} [currentUrl] URL of the page being rendered.
+ * @returns {FoldedNode[]}
+ */
+export declare function foldSidebar(nodes: SidebarNode[], currentUrl?: string): FoldedNode[];
 export type SidebarEntry = string | {
     page?: string;
     label?: string;