@docpensieve/components 0.4.0-beta.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docpensieve/components",
-  "version": "0.4.0-beta.1",
+  "version": "0.4.0",
   "description": "DocPensieve global MDX components, usable without import: Card, Columns, Tooltip, Tree, Skill, TimeTimer, LogoIcon, ScrollToTop",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,7 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/shared": "0.4.0-beta.1"
+    "@docpensieve/shared": "0.4.0"
   },
   "peerDependencies": {
     "react": "^19"

package/src/admonition.js

@@ -0,0 +1,141 @@
+/**
+ * Admonition: a block set apart from the text, which says how to read it — a
+ * tip, a caution, a danger.
+ *
+ * Six kinds ship with the tool, and a project declares its own in its
+ * configuration rather than waiting for the list to grow. A kind is a label
+ * and a **tone**: the tone carries the colour, taken from the theme's tokens,
+ * so a project adds a kind without touching a stylesheet, and the block
+ * follows the palette of whichever theme is active (ADR-007).
+ *
+ * @module @docpensieve/components/admonition
+ */
+
+import { createElement as h } from 'react';
+
+import { ADMONITION_TONES, DocPensieveError } from '@docpensieve/shared';
+
+import { classNames, cls } from './classes.js';
+import { LogoIcon } from './logo-icon.js';
+
+/**
+ * The kinds the tool ships with, each a label and a tone.
+ *
+ * `alert` and `danger` share a tone and differ in their label and their icon:
+ * one calls for attention now, the other warns of what a wrong move costs.
+ */
+export const ADMONITION_KINDS = Object.freeze({
+  note: { label: 'Note', tone: 'note' },
+  info: { label: 'Info', tone: 'info' },
+  tip: { label: 'Tip', tone: 'tip' },
+  attention: { label: 'Attention', tone: 'attention' },
+  alert: { label: 'Alert', tone: 'danger' },
+  danger: { label: 'Danger', tone: 'danger' },
+});
+
+/**
+ * Icons, drawn rather than written as characters: an emoji changes shape from
+ * one system to the next, and carries a meaning screen readers announce.
+ *
+ * Each is a path on a 24 × 24 grid, stroked in the current colour — never
+ * filled from CSS, which would turn an outline into a solid shape.
+ *
+ * @type {Record<string, string>}
+ */
+const PATHS = Object.freeze({
+  note: 'M4 5h16M4 12h16M4 19h10',
+  info: 'M12 16v-5M12 8h.01M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0z',
+  tip: 'M9 18h6M10 21h4M12 3a6 6 0 0 0-3.5 10.9c.5.4.8 1 .9 1.6h5.2c.1-.6.4-1.2.9-1.6A6 6 0 0 0 12 3z',
+  attention:
+    'M12 9v4M12 17h.01M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0z',
+  alert: 'M18 8a6 6 0 0 0-12 0c0 7-3 9-3 9h18s-3-2-3-9M13.7 21a2 2 0 0 1-3.4 0',
+  danger: 'M12 8v5M12 16h.01M8.6 2.6h6.8L21.4 8.6v6.8L15.4 21.4H8.6L2.6 15.4V8.6z',
+});
+
+/**
+ * Kinds the project declares, set once for the whole compilation.
+ *
+ * Module state rather than a prop: an author writes `type="…"` and nothing
+ * else, and `core` cannot hand this down without knowing this package
+ * (ADR-002). The same reasoning as the theme's class table.
+ *
+ * @type {Record<string, { label: string, tone: string, icon?: string }>}
+ */
+let projectKinds = {};
+
+/**
+ * Declares the kinds of the project, beside the ones shipped.
+ *
+ * @param {Record<string, { label: string, tone: string, icon?: string }>} [kinds]
+ */
+export function setAdmonitionKinds(kinds = {}) {
+  projectKinds = kinds;
+}
+
+/** @returns {Record<string, { label: string, tone: string, icon?: string }>} Every kind available. */
+export function getAdmonitionKinds() {
+  return { ...ADMONITION_KINDS, ...projectKinds };
+}
+
+/**
+ * Block set apart from the text.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any,
+ *   type?: string, title?: string,
+ * }} props `type` names the kind; `title` replaces its label for this block
+ *   alone.
+ * @throws {DocPensieveError} When the kind is unknown.
+ */
+export function Admonition({ className, style, children, type = 'note', title, ...rest }) {
+  const table = getAdmonitionKinds();
+  const kind = table[type];
+
+  // A kind nobody declared would render a block with no colour and no label —
+  // exactly the silent nothing this project refuses.
+  if (!kind) {
+    throw new DocPensieveError(`Unknown admonition type: "${type}".`, {
+      hint: `Known types: ${Object.keys(table).sort().join(', ')}. Declare your own in the admonitions field of the configuration.`,
+    });
+  }
+
+  const tone = ADMONITION_TONES.includes(kind.tone) ? kind.tone : 'note';
+
+  return h(
+    'aside',
+    {
+      className: classNames(cls('admonition', tone), className),
+      style,
+      // Set apart from the flow of the text, and announced as such.
+      role: 'note',
+      ...rest,
+    },
+    h(
+      'p',
+      { className: cls('admonitionTitle') },
+      // A kind may bring a mark of its own — a logo, inlined from the version
+      // folder. Without one, the drawing of its tone stands.
+      kind.icon
+        ? h(LogoIcon, { className: cls('admonitionIcon'), src: kind.icon })
+        : h(
+            'svg',
+            {
+              className: cls('admonitionIcon'),
+              viewBox: '0 0 24 24',
+              fill: 'none',
+              stroke: 'currentColor',
+              strokeWidth: 2,
+              strokeLinecap: 'round',
+              strokeLinejoin: 'round',
+              // The title beside it already names the kind: announcing the
+              // icon too would say it twice.
+              'aria-hidden': 'true',
+              focusable: 'false',
+            },
+            h('path', { d: PATHS[type] ?? PATHS[tone] ?? PATHS.note }),
+          ),
+      title ?? kind.label,
+    ),
+    h('div', { className: cls('admonitionBody') }, children),
+  );
+}

package/src/iconify.js

@@ -0,0 +1,107 @@
+/**
+ * Icons taken from an icon set, at build time.
+ *
+ * An icon is named `prefix:name` — the way those collections name them. The
+ * set is read from the package the project installed, and the drawing is
+ * placed in the page like any other icon: the reader downloads nothing, and no
+ * request leaves their browser. The online service those collections offer
+ * would mean both.
+ *
+ * The sets are **optional dependencies of the project**: a site installs the
+ * ones it uses, and this package keeps depending on nothing but `shared`. A
+ * set that is not installed stops the build, naming what to install.
+ *
+ * @module @docpensieve/components/iconify
+ */
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { DocPensieveError } from '@docpensieve/shared';
+
+/** `prefix:name` — never a path, which always holds a dot or a slash. */
+const ICON_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
+
+/**
+ * Whether a target names an icon of a set rather than a file.
+ *
+ * @param {string} src
+ * @returns {boolean}
+ */
+export function isIconName(src) {
+  return ICON_NAME.test(src) && !src.includes('/');
+}
+
+/**
+ * Sets already read, by prefix. A page uses the same set many times over.
+ *
+ * @type {Map<string, any>}
+ */
+const sets = new Map();
+
+/** Drawings already assembled, by full name. @type {Map<string, string>} */
+const drawings = new Map();
+
+/**
+ * Loads an icon set from the project.
+ *
+ * Two resolutions are tried: from this package — where a hoisted install puts
+ * the set within reach — and from the project folder, which covers the rest.
+ *
+ * @param {string} prefix
+ * @returns {any} The set, as the collection ships it.
+ * @throws {DocPensieveError} When the set is not installed.
+ */
+function loadSet(prefix) {
+  const known = sets.get(prefix);
+  if (known) return known;
+
+  const specifier = `@iconify-json/${prefix}/icons.json`;
+  const froms = [import.meta.url, path.join(process.cwd(), 'noop.js')];
+
+  for (const from of froms) {
+    try {
+      const set = createRequire(from)(specifier);
+      sets.set(prefix, set);
+      return set;
+    } catch {
+      // Tried elsewhere before giving up.
+    }
+  }
+
+  throw new DocPensieveError(`No icon set installed for "${prefix}".`, {
+    hint: `Install the set beside your project: npm install --save-dev @iconify-json/${prefix}`,
+  });
+}
+
+/**
+ * The drawing of an icon, as a complete `svg` tag.
+ *
+ * @param {string} name Full name, `prefix:icon`.
+ * @returns {string}
+ * @throws {DocPensieveError} Set not installed, or icon absent from it.
+ */
+export function iconSvg(name) {
+  const known = drawings.get(name);
+  if (known !== undefined) return known;
+
+  const [prefix, icon] = name.split(':');
+  const set = loadSet(prefix);
+
+  // A set names some icons twice: the second name is an alias of the first.
+  const alias = set.aliases?.[icon];
+  const entry = set.icons?.[icon] ?? (alias ? set.icons?.[alias.parent] : undefined);
+
+  if (!entry) {
+    throw new DocPensieveError(`The icon set "${prefix}" holds no icon named "${icon}".`, {
+      hint: `Check the name in that collection: it is written ${prefix}:some-icon.`,
+    });
+  }
+
+  const width = entry.width ?? set.width ?? 16;
+  const height = entry.height ?? set.height ?? 16;
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}">${entry.body}</svg>`;
+
+  drawings.set(name, svg);
+  return svg;
+}

package/src/index.js

@@ -18,9 +18,16 @@ export {
   setThemeClasses,
   setThemeFramework,
 } from './classes.js';
+export {
+  ADMONITION_KINDS,
+  Admonition,
+  getAdmonitionKinds,
+  setAdmonitionKinds,
+} from './admonition.js';
 export { Card, CardBody, CardFooter, CardHeader, CardImage } from './card.js';
 export { Cards } from './cards.js';
 export { Column, Columns } from './columns.js';
+export { Menu, MenuGroup, MenuLink } from './menu.js';
 export { FallbackAfter, FallbackBefore, TimeTimer } from './time-timer.js';
 export { TOOLTIP_PLACEMENTS, Tooltip } from './tooltip.js';
 export { Tree, TreeItem } from './tree.js';

package/src/logo-icon.js

@@ -14,6 +14,7 @@ import { createElement as h } from 'react';
 import { DocPensieveError } from '@docpensieve/shared';
 
 import { classNames, cls } from './classes.js';
+import { iconSvg, isIconName } from './iconify.js';
 import { resolveFile } from './site.js';
 
 /** Isolates the `svg` root: XML header, doctype and comments stay out. */
@@ -48,6 +49,11 @@ const cache = new Map();
  * @throws {DocPensieveError} File not found, or without an `svg` tag.
  */
 function readSvg(src) {
+  // `prefix:name` names an icon of a set rather than a file of the project:
+  // the drawing then comes from the set the project installed, and is placed
+  // in the page all the same.
+  if (isIconName(src)) return iconSvg(src).replace(SCRIPT, '').replace(HANDLER, '');
+
   /** @type {string} */
   let file;
   try {

package/src/menu.js

@@ -0,0 +1,131 @@
+/**
+ * A menu of links, placed anywhere in a page.
+ *
+ * The header already carries the navigation of the site, and the sidebar that
+ * of the documentation. This one belongs to a page: the links a section wants
+ * to offer where it stands — a summary at the top of a landing page, the
+ * chapters of a guide, the entries of a portal.
+ *
+ * It holds no state and loads no script. On a narrow screen it folds behind a
+ * button, a native `details` element: the menu is therefore written once and
+ * rendered twice, a row and a fold, of which the stylesheet shows one. The
+ * alternative, a single rendering revealed by a recent CSS pseudo-element,
+ * hides the links outright on a browser that does not know it.
+ *
+ * Classes come from the theme (ADR-007), never from a hard-coded framework.
+ *
+ * @module @docpensieve/components/menu
+ */
+
+import { createContext, createElement as h, useContext } from 'react';
+
+import { DocPensieveError } from '@docpensieve/shared';
+
+import { classNames, cls } from './classes.js';
+import { resolveUrl } from './site.js';
+
+/**
+ * What an entry learns from the menu holding it.
+ *
+ * `false` outside a menu: without this landmark, a lone `MenuLink` rendered a
+ * link with no menu around it — styled as an entry, standing nowhere, and
+ * without a word to say so.
+ *
+ * @type {import('react').Context<boolean>}
+ */
+const InMenu = createContext(false);
+
+/**
+ * Menu of links.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any, label?: string,
+ * }} props `label` names the menu for screen readers, and labels the button it
+ *   folds into on a narrow screen.
+ */
+export function Menu({ className, style, children, label = 'Menu' }) {
+  const entries = h(InMenu.Provider, { value: true }, children);
+
+  return h(
+    'div',
+    { className: classNames(cls('pageMenu'), className), style },
+    // The row and the fold hold the same entries; the stylesheet shows one or
+    // the other, so a screen reader never meets the menu twice.
+    h('nav', { className: cls('pageMenuRow'), 'aria-label': label }, entries),
+    h(
+      'details',
+      { className: cls('pageMenuFold') },
+      h('summary', null, label),
+      h('nav', { className: cls('pageMenuFoldList'), 'aria-label': label }, entries),
+    ),
+  );
+}
+
+/**
+ * Entry of a menu.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any, href?: string,
+ * }} props
+ * @throws {DocPensieveError} Outside a `Menu`, or without a target.
+ */
+export function MenuLink({ className, style, children, href }) {
+  if (!useContext(InMenu)) {
+    throw new DocPensieveError('A <MenuLink> was written outside a <Menu>.', {
+      hint: 'Wrap the entries in <Menu>…</Menu>.',
+    });
+  }
+
+  // A menu entry that leads nowhere is furniture: better said at build time
+  // than left for a reader to click.
+  if (typeof href !== 'string' || href.trim() === '') {
+    throw new DocPensieveError('A <MenuLink> without href.', {
+      hint: 'Give the target: <MenuLink href="/guide/">Guide</MenuLink>.',
+    });
+  }
+
+  return h(
+    'a',
+    {
+      className: classNames(cls('pageMenuLink'), className),
+      style,
+      // A link produced by a component escapes the compiler plugins: it
+      // resolves itself, following the same rules (ADR-006).
+      href: resolveUrl(href),
+    },
+    children,
+  );
+}
+
+/**
+ * Group of entries, folded under a title.
+ *
+ * In the row it opens as a panel below its title; folded, it unfolds in place
+ * rather than over the rest — on a narrow screen a panel would open off
+ * screen.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any, title?: string,
+ * }} props
+ * @throws {DocPensieveError} Outside a `Menu`, or without a title.
+ */
+export function MenuGroup({ className, style, children, title }) {
+  if (!useContext(InMenu)) {
+    throw new DocPensieveError('A <MenuGroup> was written outside a <Menu>.', {
+      hint: 'Wrap the groups in <Menu>…</Menu>.',
+    });
+  }
+
+  if (typeof title !== 'string' || title.trim() === '') {
+    throw new DocPensieveError('A <MenuGroup> without title.', {
+      hint: 'The title is what opens the group: <MenuGroup title="Reference">…</MenuGroup>.',
+    });
+  }
+
+  return h(
+    'details',
+    { className: classNames(cls('pageMenuGroup'), className), style },
+    h('summary', { className: cls('pageMenuTitle') }, title),
+    h('div', { className: cls('pageMenuPanel') }, children),
+  );
+}

package/src/registry.js

@@ -7,11 +7,13 @@
  * @module @docpensieve/components/registry
  */
 
+import { Admonition } from './admonition.js';
 import { Card, CardBody, CardFooter, CardHeader, CardImage } from './card.js';
 import { Cards } from './cards.js';
 import { Column, Columns } from './columns.js';
 import { ForTheme } from './for-theme.js';
 import { LogoIcon } from './logo-icon.js';
+import { Menu, MenuGroup, MenuLink } from './menu.js';
 import { ScrollToTop } from './scroll-to-top.js';
 import { Skill } from './skill.js';
 import { FallbackAfter, FallbackBefore, TimeTimer } from './time-timer.js';
@@ -23,6 +25,7 @@ import { Tree, TreeItem } from './tree.js';
  * @type {Record<string, Function>}
  */
 export const builtinComponents = {
+  Admonition,
   Card,
   CardHeader,
   CardBody,
@@ -31,6 +34,9 @@ export const builtinComponents = {
   Cards,
   Columns,
   Column,
+  Menu,
+  MenuLink,
+  MenuGroup,
   TimeTimer,
   FallbackBefore,
   FallbackAfter,

package/styles/components.css

@@ -14,6 +14,200 @@
  */
 
 @layer components {
+  /* --- Admonition -------------------------------------------------------- */
+
+  /*
+   * A block set apart from the text. Its colour comes from its tone, through
+   * two variables the modifier sets: the component therefore knows no colour,
+   * and a kind declared by a project needs no rule of its own.
+   */
+  .dp-admonition {
+    --dp-admonition-colour: var(--dp-text-soft);
+    --dp-admonition-ground: var(--dp-bg-soft);
+    margin: 1.5rem 0;
+    padding: 0.9rem 1.1rem;
+    border: 1px solid var(--dp-border);
+    border-inline-start: 3px solid var(--dp-admonition-colour);
+    border-radius: var(--dp-radius);
+    background: var(--dp-admonition-ground);
+  }
+
+  .dp-admonition--info {
+    --dp-admonition-colour: var(--dp-accent);
+    --dp-admonition-ground: var(--dp-accent-soft);
+  }
+
+  .dp-admonition--tip {
+    --dp-admonition-colour: var(--dp-tip);
+    --dp-admonition-ground: var(--dp-tip-soft);
+  }
+
+  .dp-admonition--attention {
+    --dp-admonition-colour: var(--dp-attention);
+    --dp-admonition-ground: var(--dp-attention-soft);
+  }
+
+  .dp-admonition--danger {
+    --dp-admonition-colour: var(--dp-danger);
+    --dp-admonition-ground: var(--dp-danger-soft);
+  }
+
+  .dp-admonition-title {
+    display: flex;
+    align-items: center;
+    gap: 0.45rem;
+    margin: 0 0 0.4rem;
+    color: var(--dp-admonition-colour);
+    font-weight: 600;
+  }
+
+  /* Size only: the icon inherits the colour of the title it stands beside. */
+  .dp-admonition-icon {
+    flex: none;
+    inline-size: 1.05rem;
+    block-size: 1.05rem;
+  }
+
+  .dp-admonition-body > :first-child {
+    margin-block-start: 0;
+  }
+
+  .dp-admonition-body > :last-child {
+    margin-block-end: 0;
+  }
+
+  /* --- Menu -------------------------------------------------------------- */
+
+  /*
+   * A menu of links inside a page. Written once and rendered twice — a row and
+   * a fold — of which one shows: a single rendering revealed by CSS alone
+   * hides the links outright where that CSS is unknown.
+   */
+  .dp-page-menu {
+    margin: 1.5rem 0;
+  }
+
+  .dp-page-menu-row {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.35rem 1.25rem;
+  }
+
+  .dp-page-menu-fold {
+    display: none;
+  }
+
+  .dp-page-menu-fold > summary {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.45rem 0.9rem;
+    border: 1px solid var(--dp-border);
+    border-radius: var(--dp-radius);
+    color: var(--dp-text-soft);
+    cursor: pointer;
+    list-style: none;
+  }
+
+  .dp-page-menu-fold > summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .dp-page-menu-fold[open] > summary,
+  .dp-page-menu-fold > summary:hover {
+    border-color: var(--dp-text-soft);
+    color: var(--dp-text);
+  }
+
+  .dp-page-menu-fold-list {
+    display: flex;
+    flex-direction: column;
+    gap: 0.6rem;
+    margin-block-start: 0.75rem;
+    padding-inline-start: 0.75rem;
+    border-inline-start: 1px solid var(--dp-border);
+  }
+
+  .dp-page-menu-link {
+    color: var(--dp-text);
+    font-weight: 500;
+    text-decoration: none;
+  }
+
+  .dp-page-menu-link:hover {
+    color: var(--dp-accent);
+  }
+
+  /* A group: a panel in the row, unfolded in place once the menu is folded. */
+  .dp-page-menu-group {
+    position: relative;
+  }
+
+  .dp-page-menu-title {
+    color: var(--dp-text-soft);
+    font-weight: 500;
+    cursor: pointer;
+    list-style: none;
+  }
+
+  .dp-page-menu-title::-webkit-details-marker {
+    display: none;
+  }
+
+  .dp-page-menu-title::after {
+    content: '';
+    display: inline-block;
+    inline-size: 0.35rem;
+    block-size: 0.35rem;
+    margin-inline-start: 0.4rem;
+    border-inline-end: 1px solid currentColor;
+    border-block-end: 1px solid currentColor;
+    rotate: 45deg;
+    translate: 0 -0.15rem;
+  }
+
+  .dp-page-menu-group[open] > .dp-page-menu-title {
+    color: var(--dp-text);
+  }
+
+  .dp-page-menu-panel {
+    position: absolute;
+    top: calc(100% + 0.4rem);
+    left: 0;
+    z-index: 10;
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    min-inline-size: 10rem;
+    padding: 0.8rem 1rem;
+    border: 1px solid var(--dp-border);
+    border-radius: var(--dp-radius);
+    background: var(--dp-bg);
+    box-shadow: 0 8px 24px var(--dp-shadow);
+  }
+
+  .dp-page-menu-fold-list .dp-page-menu-panel {
+    position: static;
+    min-inline-size: 0;
+    padding: 0.5rem 0 0 0.75rem;
+    border: 0;
+    border-inline-start: 1px solid var(--dp-border);
+    border-radius: 0;
+    background: transparent;
+    box-shadow: none;
+  }
+
+  @media (max-width: 40rem) {
+    .dp-page-menu-row {
+      display: none;
+    }
+
+    .dp-page-menu-fold {
+      display: block;
+    }
+  }
+
   /* --- Cards ------------------------------------------------------------- */
 
   /*

package/types/admonition.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Admonition: a block set apart from the text, which says how to read it — a
+ * tip, a caution, a danger.
+ *
+ * Six kinds ship with the tool, and a project declares its own in its
+ * configuration rather than waiting for the list to grow. A kind is a label
+ * and a **tone**: the tone carries the colour, taken from the theme's tokens,
+ * so a project adds a kind without touching a stylesheet, and the block
+ * follows the palette of whichever theme is active (ADR-007).
+ *
+ * @module @docpensieve/components/admonition
+ */
+/**
+ * The kinds the tool ships with, each a label and a tone.
+ *
+ * `alert` and `danger` share a tone and differ in their label and their icon:
+ * one calls for attention now, the other warns of what a wrong move costs.
+ */
+export declare const ADMONITION_KINDS: Readonly<{
+    note: {
+        label: string;
+        tone: string;
+    };
+    info: {
+        label: string;
+        tone: string;
+    };
+    tip: {
+        label: string;
+        tone: string;
+    };
+    attention: {
+        label: string;
+        tone: string;
+    };
+    alert: {
+        label: string;
+        tone: string;
+    };
+    danger: {
+        label: string;
+        tone: string;
+    };
+}>;
+/**
+ * Declares the kinds of the project, beside the ones shipped.
+ *
+ * @param {Record<string, { label: string, tone: string, icon?: string }>} [kinds]
+ */
+export declare function setAdmonitionKinds(kinds?: Record<string, {
+    label: string;
+    tone: string;
+    icon?: string;
+}>): void;
+/** @returns {Record<string, { label: string, tone: string, icon?: string }>} Every kind available. */
+export declare function getAdmonitionKinds(): Record<string, {
+    label: string;
+    tone: string;
+    icon?: string;
+}>;
+/**
+ * Block set apart from the text.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any,
+ *   type?: string, title?: string,
+ * }} props `type` names the kind; `title` replaces its label for this block
+ *   alone.
+ * @throws {DocPensieveError} When the kind is unknown.
+ */
+export declare function Admonition({ className, style, children, type, title, ...rest }: {
+    className?: string;
+    style?: object;
+    children?: any;
+    type?: string;
+    title?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+    role: "note";
+}, HTMLElement>;

package/types/iconify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Icons taken from an icon set, at build time.
+ *
+ * An icon is named `prefix:name` — the way those collections name them. The
+ * set is read from the package the project installed, and the drawing is
+ * placed in the page like any other icon: the reader downloads nothing, and no
+ * request leaves their browser. The online service those collections offer
+ * would mean both.
+ *
+ * The sets are **optional dependencies of the project**: a site installs the
+ * ones it uses, and this package keeps depending on nothing but `shared`. A
+ * set that is not installed stops the build, naming what to install.
+ *
+ * @module @docpensieve/components/iconify
+ */
+/**
+ * Whether a target names an icon of a set rather than a file.
+ *
+ * @param {string} src
+ * @returns {boolean}
+ */
+export declare function isIconName(src: string): boolean;
+/**
+ * The drawing of an icon, as a complete `svg` tag.
+ *
+ * @param {string} name Full name, `prefix:icon`.
+ * @returns {string}
+ * @throws {DocPensieveError} Set not installed, or icon absent from it.
+ */
+export declare function iconSvg(name: string): string;

package/types/index.d.ts

@@ -9,9 +9,11 @@
  * @module @docpensieve/components
  */
 export { classNames, cls, fallbackClass, getThemeClasses, getThemeFramework, setThemeClasses, setThemeFramework, } from './classes.js';
+export { ADMONITION_KINDS, Admonition, getAdmonitionKinds, setAdmonitionKinds, } from './admonition.js';
 export { Card, CardBody, CardFooter, CardHeader, CardImage } from './card.js';
 export { Cards } from './cards.js';
 export { Column, Columns } from './columns.js';
+export { Menu, MenuGroup, MenuLink } from './menu.js';
 export { FallbackAfter, FallbackBefore, TimeTimer } from './time-timer.js';
 export { TOOLTIP_PLACEMENTS, Tooltip } from './tooltip.js';
 export { Tree, TreeItem } from './tree.js';

package/types/menu.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A menu of links, placed anywhere in a page.
+ *
+ * The header already carries the navigation of the site, and the sidebar that
+ * of the documentation. This one belongs to a page: the links a section wants
+ * to offer where it stands — a summary at the top of a landing page, the
+ * chapters of a guide, the entries of a portal.
+ *
+ * It holds no state and loads no script. On a narrow screen it folds behind a
+ * button, a native `details` element: the menu is therefore written once and
+ * rendered twice, a row and a fold, of which the stylesheet shows one. The
+ * alternative, a single rendering revealed by a recent CSS pseudo-element,
+ * hides the links outright on a browser that does not know it.
+ *
+ * Classes come from the theme (ADR-007), never from a hard-coded framework.
+ *
+ * @module @docpensieve/components/menu
+ */
+/**
+ * Menu of links.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any, label?: string,
+ * }} props `label` names the menu for screen readers, and labels the button it
+ *   folds into on a narrow screen.
+ */
+export declare function Menu({ className, style, children, label }: {
+    className?: string;
+    style?: object;
+    children?: any;
+    label?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+}, HTMLElement>;
+/**
+ * Entry of a menu.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any, href?: string,
+ * }} props
+ * @throws {DocPensieveError} Outside a `Menu`, or without a target.
+ */
+export declare function MenuLink({ className, style, children, href }: {
+    className?: string;
+    style?: object;
+    children?: any;
+    href?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+    href: string | undefined;
+}, HTMLElement>;
+/**
+ * Group of entries, folded under a title.
+ *
+ * In the row it opens as a panel below its title; folded, it unfolds in place
+ * rather than over the rest — on a narrow screen a panel would open off
+ * screen.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any, title?: string,
+ * }} props
+ * @throws {DocPensieveError} Outside a `Menu`, or without a title.
+ */
+export declare function MenuGroup({ className, style, children, title }: {
+    className?: string;
+    style?: object;
+    children?: any;
+    title?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: object | undefined;
+}, HTMLElement>;