@docpensieve/components 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valentin Chevoleau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @docpensieve/components
+
+> Global MDX components
+
+Part of [DocPensieve](https://github.com/Juniors017/docpensieve), a static documentation site generator:
+Markdown and MDX in, static HTML out, one version per orphan branch, JSON-LD
+structured data from the frontmatter.
+
+## Installation
+
+```bash
+npm install @docpensieve/components
+```
+
+## Usage
+
+The components registered here are injected into the MDX compilation: they
+can be used in any page **without an import**.
+
+```js
+import { createRegistry } from '@docpensieve/components';
+
+const components = createRegistry({ MyBlock });
+```
+
+React is a build-only dependency.
+
+## Documentation
+
+See the [repository](https://github.com/Juniors017/docpensieve#readme).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@docpensieve/components",
+  "version": "0.1.0",
+  "description": "DocPensieve global MDX components, usable without import: Card, Columns, Tooltip, Tree, Skill, TimeTimer, LogoIcon, ScrollToTop",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "styles",
+    "types"
+  ],
+  "dependencies": {
+    "@docpensieve/shared": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19"
+  },
+  "keywords": [
+    "docpensieve",
+    "mdx",
+    "components",
+    "react",
+    "documentation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Juniors017/docpensieve.git",
+    "directory": "packages/components"
+  },
+  "homepage": "https://github.com/Juniors017/docpensieve#readme",
+  "bugs": {
+    "url": "https://github.com/Juniors017/docpensieve/issues"
+  },
+  "author": "Valentin Chevoleau (Juniors017)",
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./types/index.d.ts",
+  "scripts": {
+    "prepack": "tsc -b tsconfig.build.json"
+  }
+}

package/src/card.js

@@ -0,0 +1,94 @@
+/**
+ * Card and its parts.
+ *
+ * The component provides the **structure** — the wrapper, the separators, the
+ * spacing. The look is set through `className`, with the utilities of the
+ * active theme. One prop per typographic setting would mean reimplementing,
+ * less well, what CSS already does.
+ *
+ * Classes come from the theme (ADR-007), never from a hard-coded framework.
+ *
+ * The files of this package are plain JavaScript, with no build step: no JSX,
+ * hence `createElement` — shortened to `h` for readability.
+ *
+ * @module @docpensieve/components/card
+ */
+
+import { createElement as h } from 'react';
+
+import { classNames, cls } from './classes.js';
+import { resolveUrl } from './site.js';
+
+/**
+ * @typedef {object} PartProps
+ * @property {string} [className] Classes added to the component's own.
+ * @property {object} [style]
+ * @property {any} [children]
+ */
+
+/**
+ * Makes a card part: header, body or footer.
+ *
+ * The three only differ by their theme slot.
+ *
+ * @param {string} slot Theme slot, `'cardHeader'` for instance.
+ * @param {string} name Name shown in errors and rendering tools.
+ * @returns {(props: PartProps) => any}
+ */
+function cardPart(slot, name) {
+  /** @param {PartProps} props */
+  function Part({ className, style, children }) {
+    return h('div', { className: classNames(cls(slot), className), style }, children);
+  }
+  Object.defineProperty(Part, 'name', { value: name });
+  return Part;
+}
+
+/**
+ * Card container.
+ *
+ * @param {PartProps & { elevated?: boolean, href?: string }} props
+ *   `elevated` adds a shadow. `href` makes the whole card clickable, rather
+ *   than a link on the title alone that would leave the rest inert.
+ */
+export function Card({ className, style, children, elevated = false, href }) {
+  return h(
+    href ? 'a' : 'div',
+    {
+      className: classNames(cls('card', elevated && 'elevated'), className),
+      style,
+      // A link produced by a component escapes the compiler plugins: it
+      // resolves itself, following the same rules (ADR-006).
+      ...(href ? { href: resolveUrl(href) } : {}),
+    },
+    children,
+  );
+}
+
+export const CardHeader = cardPart('cardHeader', 'CardHeader');
+export const CardBody = cardPart('cardBody', 'CardBody');
+export const CardFooter = cardPart('cardFooter', 'CardFooter');
+
+/**
+ * Image at the top of a card.
+ *
+ * `src` resolves as in Markdown — relative to the page, absolute from the
+ * version root. The compiler plugins cannot handle it: they work on the
+ * Markdown tree, before React renders anything. So the component does it
+ * itself (ADR-006).
+ *
+ * @param {{
+ *   className?: string, style?: object, src?: string,
+ *   alt?: string, title?: string, srcSet?: string, sizes?: string,
+ * }} props `alt` defaults to the empty string: without that attribute, a
+ *   screen reader would announce the file URL.
+ */
+export function CardImage({ className, style, src, alt = '', ...rest }) {
+  return h('img', {
+    className: classNames(cls('cardImage'), className),
+    style,
+    src: resolveUrl(src),
+    alt,
+    ...rest,
+  });
+}

package/src/classes.js

@@ -0,0 +1,90 @@
+/**
+ * Resolution of component classes.
+ *
+ * A component never writes a framework class. It asks for the class of its
+ * slot, and the theme answers — or not. Without an answer, the fallback is a
+ * `dp-*` class that the package stylesheet styles on the `--dp-*` tokens: the
+ * component therefore follows the active palette without knowing anything
+ * about it (ADR-007).
+ *
+ * @module @docpensieve/components/classes
+ */
+
+/**
+ * Table supplied by the theme, set once by the generator.
+ *
+ * Module state rather than a React context: MDX compilation happens in a
+ * single process, with a single configuration, and a context would force
+ * `core` to know this package — which ADR-002 forbids.
+ *
+ * @type {Record<string, string>}
+ */
+let themeClasses = {};
+
+/**
+ * Declares the theme table for the whole compilation.
+ *
+ * @param {Record<string, string>} [classes]
+ */
+export function setThemeClasses(classes = {}) {
+  themeClasses = classes;
+}
+
+/** @returns {Record<string, string>} The current table, for inspection. */
+export function getThemeClasses() {
+  return themeClasses;
+}
+
+/**
+ * Converts a slot name into a fallback class.
+ *
+ * @example
+ * fallbackClass('cardHeader')  // 'dp-card-header'
+ *
+ * @param {string} slot
+ * @returns {string}
+ */
+export function fallbackClass(slot) {
+  return `dp-${slot.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}`;
+}
+
+/**
+ * Class of a slot, variants included.
+ *
+ * @example
+ * cls('card')                  // 'dp-card'
+ * cls('card', 'shadow')        // 'dp-card dp-card--shadow'
+ * cls('alert', false && 'x')   // 'dp-alert' — falsy values are ignored
+ *
+ * @param {string} slot Slot name.
+ * @param {...unknown} modifiers Variants, each one suffixed as `--variant`.
+ *   Falsy values are ignored, which allows writing `cls('card', shadow && shadow)`.
+ * @returns {string}
+ */
+export function cls(slot, ...modifiers) {
+  const base = themeClasses[slot] ?? fallbackClass(slot);
+  const root = fallbackClass(slot);
+
+  // `filter(Boolean)` lets 0 through: a `span && ...` on a zero number would
+  // produce “--0”. Only non-empty strings are kept.
+  const variants = modifiers
+    .filter((modifier) => typeof modifier === 'string' && modifier !== '')
+    .map((modifier) => themeClasses[`${slot}.${modifier}`] ?? `${root}--${modifier}`);
+
+  return [base, ...variants].join(' ');
+}
+
+/**
+ * Joins classes while ignoring falsy values.
+ *
+ * A minimal equivalent of `clsx`: one more dependency is not worth it for six
+ * lines.
+ *
+ * @param {...unknown} parts
+ * @returns {string | undefined} `undefined` when nothing is left, to avoid a
+ *   `class=""` in the produced HTML.
+ */
+export function classNames(...parts) {
+  const kept = parts.filter(Boolean).join(' ').trim();
+  return kept === '' ? undefined : kept;
+}

package/src/columns.js

@@ -0,0 +1,124 @@
+/**
+ * Column grid.
+ *
+ * Not to be confused with CSS multi-column (`column-count`), where content
+ * *flows* from one column to the next as in a newspaper. Here every block is
+ * placed explicitly: it is a grid, not a flow. For a flow, the theme's
+ * utilities are enough, without a component.
+ *
+ * Two layouts, depending on what the row holds:
+ *
+ * - **no declared width** — the columns share the space equally, whatever
+ *   their number;
+ * - **declared widths** — twelve tracks, and each column takes the number it
+ *   asks for.
+ *
+ * The grid works out the gap between columns by itself: a width therefore has
+ * no calculation to make, and changing the gap breaks nothing.
+ *
+ * Classes come from the theme (ADR-007), never from a hard-coded framework.
+ *
+ * @module @docpensieve/components/columns
+ */
+
+import { Children, createContext, createElement as h, isValidElement, useContext } from 'react';
+
+import { DocPensieveError } from '@docpensieve/shared';
+
+import { classNames, cls } from './classes.js';
+
+/** Number of tracks when widths are declared. */
+const TRACKS = 12;
+
+/**
+ * What a column learns from its row.
+ *
+ * `null` outside a row: without this landmark, a lone `Column` rendered a
+ * grid cell without a grid — full width, with no error or warning. A tag that
+ * silently does nothing is what this project sets out to avoid.
+ *
+ * @type {import('react').Context<{ sized: boolean } | null>}
+ */
+const Row = createContext(/** @type {{ sized: boolean } | null} */ (null));
+
+/**
+ * Tells whether at least one column of the row declares a width.
+ *
+ * The walk goes down into the children: depending on how the author spaces
+ * out their MDX, the columns are not always direct children of the row.
+ *
+ * @param {any} children
+ * @returns {boolean}
+ */
+function hasSizedColumn(children) {
+  return Children.toArray(children).some((child) => {
+    if (!isValidElement(child)) return false;
+    // `props` is not typed on an arbitrary element: open it here rather than
+    // impose a shape on everything an author can write.
+    const props = /** @type {{ span?: number, children?: any }} */ (child.props);
+    if (child.type === Column) return props.span !== undefined;
+    return props?.children !== undefined && hasSizedColumn(props.children);
+  });
+}
+
+/**
+ * Row of columns.
+ *
+ * The gap is set through `className` or `style`, with the theme's utilities:
+ * the grid recomputes the widths by itself.
+ *
+ * @param {{ className?: string, style?: object, children?: any }} props
+ */
+export function Columns({ className, style, children }) {
+  const sized = hasSizedColumn(children);
+
+  return h(
+    Row.Provider,
+    { value: { sized } },
+    h(
+      'div',
+      { className: classNames(cls('columns', sized && 'twelfths'), className), style },
+      children,
+    ),
+  );
+}
+
+/**
+ * Column of a row.
+ *
+ * @param {{ className?: string, style?: object, children?: any, span?: number }} props
+ *   `span` is the number of tracks taken out of twelve — `span={6}` for a
+ *   half, `span={8}` for two thirds. Twelve because twelve divides by two,
+ *   three, four and six. Without `span`, the columns share the space equally.
+ * @throws {DocPensieveError} Outside a `Columns`, or when the row mixes
+ *   columns with and without a width.
+ */
+export function Column({ className, style, children, span }) {
+  const row = useContext(Row);
+
+  if (row === null) {
+    throw new DocPensieveError('A <Column> was written outside a <Columns>.', {
+      hint: 'Wrap the columns: <Columns><Column>…</Column></Columns>.',
+    });
+  }
+
+  if (span !== undefined && (!Number.isInteger(span) || span < 1 || span > TRACKS)) {
+    throw new DocPensieveError(`Invalid column width: "${span}".`, {
+      hint: `span expects an integer from 1 to ${TRACKS}, the number of tracks taken out of ${TRACKS}.`,
+    });
+  }
+
+  // A column without a width in a row that declares some would take a single
+  // track out of twelve: a sliver, where the author expected a column.
+  if (row.sized && span === undefined) {
+    throw new DocPensieveError('A <Column> without a width in a row that declares some.', {
+      hint: `Give a span to every column of the row, or to none. The total is ${TRACKS}.`,
+    });
+  }
+
+  return h(
+    'div',
+    { className: classNames(cls('column', span && `span-${span}`), className), style },
+    children,
+  );
+}

package/src/index.js

@@ -0,0 +1,23 @@
+/**
+ * @docpensieve/components — global components available in MDX.
+ *
+ * React is a build-only dependency: the generated HTML loads no React
+ * runtime. The components are therefore **static** — no state, no event
+ * listener. Whatever needs interaction goes through CSS or through native
+ * HTML elements such as `<details>`.
+ *
+ * @module @docpensieve/components
+ */
+
+export { classNames, cls, fallbackClass, getThemeClasses, setThemeClasses } from './classes.js';
+export { Card, CardBody, CardFooter, CardHeader, CardImage } from './card.js';
+export { Column, Columns } from './columns.js';
+export { FallbackAfter, FallbackBefore, TimeTimer } from './time-timer.js';
+export { TOOLTIP_PLACEMENTS, Tooltip } from './tooltip.js';
+export { Tree, TreeItem } from './tree.js';
+export { ScrollToTop } from './scroll-to-top.js';
+export { SKILL_SHAPES, Skill } from './skill.js';
+export { LogoIcon } from './logo-icon.js';
+export { componentsCss } from './styles.js';
+export { getSiteContext, resolveFile, resolveUrl, setSiteContext } from './site.js';
+export { builtinComponents, createRegistry, listComponentNames } from './registry.js';

package/src/logo-icon.js

@@ -0,0 +1,125 @@
+/**
+ * SVG icon inlined at build time.
+ *
+ * The file is read once and its content placed in the page. That is what
+ * lets it take its colour from `currentColor` and be styled like everything
+ * else — impossible through an `img` tag, which isolates the document.
+ *
+ * @module @docpensieve/components/logo-icon
+ */
+
+import { readFileSync } from 'node:fs';
+import { createElement as h } from 'react';
+
+import { DocPensieveError } from '@docpensieve/shared';
+
+import { classNames, cls } from './classes.js';
+import { resolveFile } from './site.js';
+
+/** Isolates the `svg` root: XML header, doctype and comments stay out. */
+const SVG_ROOT = /<svg\b[\s\S]*<\/svg>/i;
+
+/** A script embedded in an SVG would run in the page. */
+const SCRIPT = /<script\b[\s\S]*?<\/script\s*>/gi;
+
+/** Event handlers written as attributes, for the same reason. */
+const HANDLER = /\son[a-z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi;
+
+/**
+ * Files already read, by absolute path.
+ *
+ * The same icon often comes back within a page and from one page to the
+ * next: without this cache, every occurrence would read the disk again.
+ *
+ * @type {Map<string, string>}
+ */
+const cache = new Map();
+
+/**
+ * Reads an SVG and strips what would run.
+ *
+ * The file comes from the project, so from a trusted source; the stripping
+ * mostly matters for an icon fetched elsewhere and dropped in without review.
+ * The produced site loads no JavaScript, and a component is not going to
+ * introduce any.
+ *
+ * @param {string} src Path written by the author.
+ * @returns {string} The content of the `svg` tag.
+ * @throws {DocPensieveError} File not found, or without an `svg` tag.
+ */
+function readSvg(src) {
+  /** @type {string} */
+  let file;
+  try {
+    file = resolveFile(src);
+  } catch (cause) {
+    throw new DocPensieveError(
+      `Icon "${src}": ${(cause instanceof Error && cause.message) || cause}`,
+      {
+        cause,
+        hint: 'A relative path starts from the page, an absolute path from the version folder.',
+      },
+    );
+  }
+
+  const cached = cache.get(file);
+  if (cached !== undefined) return cached;
+
+  /** @type {string} */
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (cause) {
+    throw new DocPensieveError(`Icon not found: "${src}".`, {
+      cause,
+      hint: `Expected file here: ${file}`,
+    });
+  }
+
+  const match = raw.match(SVG_ROOT);
+  if (!match) {
+    throw new DocPensieveError(`The file "${src}" contains no <svg> tag.`, {
+      hint: 'LogoIcon expects an SVG file.',
+    });
+  }
+
+  const clean = match[0].replace(SCRIPT, '').replace(HANDLER, '');
+  cache.set(file, clean);
+  return clean;
+}
+
+/**
+ * Project SVG icon, inlined in the page.
+ *
+ * @example
+ * <LogoIcon src="./icons/book.svg" label="Documentation" />
+ *
+ * @param {{
+ *   className?: string, style?: object,
+ *   src?: string, label?: string, size?: string,
+ * }} props `label` describes the icon; without it the icon is treated as
+ *   decorative and hidden from screen readers — which is right when nearby
+ *   text already says the same thing. `size` accepts any CSS length.
+ * @throws {DocPensieveError} Without `src`, or when the file cannot be read.
+ */
+export function LogoIcon({ className, style, src, label, size }) {
+  if (typeof src !== 'string' || src === '') {
+    throw new DocPensieveError('A <LogoIcon> without src.', {
+      hint: 'Give the path of the file: <LogoIcon src="./logo.svg" />.',
+    });
+  }
+
+  const decorative = label === undefined || label === null || label === '';
+
+  return h('span', {
+    className: classNames(cls('logoIcon'), className),
+    style: size ? { '--dp-logo-icon-size': size, ...style } : style,
+    role: decorative ? undefined : 'img',
+    'aria-label': decorative ? undefined : label,
+    'aria-hidden': decorative ? 'true' : undefined,
+    // The only way to put an SVG read from disk into the rendered tree. Its
+    // content comes from the project sources and has been stripped of any
+    // script.
+    dangerouslySetInnerHTML: { __html: readSvg(src) },
+  });
+}

package/src/registry.js

@@ -0,0 +1,62 @@
+/**
+ * Registry of global components.
+ *
+ * The components registered here are passed to @mdx-js/mdx as the
+ * `components` table: they become usable in any `.mdx` without an import.
+ *
+ * @module @docpensieve/components/registry
+ */
+
+import { Card, CardBody, CardFooter, CardHeader, CardImage } from './card.js';
+import { Column, Columns } from './columns.js';
+import { LogoIcon } from './logo-icon.js';
+import { ScrollToTop } from './scroll-to-top.js';
+import { Skill } from './skill.js';
+import { FallbackAfter, FallbackBefore, TimeTimer } from './time-timer.js';
+import { Tooltip } from './tooltip.js';
+import { Tree, TreeItem } from './tree.js';
+
+/**
+ * Components shipped with DocPensieve.
+ * @type {Record<string, Function>}
+ */
+export const builtinComponents = {
+  Card,
+  CardHeader,
+  CardBody,
+  CardFooter,
+  CardImage,
+  Columns,
+  Column,
+  TimeTimer,
+  FallbackBefore,
+  FallbackAfter,
+  Tooltip,
+  Tree,
+  TreeItem,
+  ScrollToTop,
+  Skill,
+  LogoIcon,
+};
+
+/**
+ * Builds the component table passed to the MDX compiler.
+ *
+ * @param {Record<string, Function>} [userComponents] Project components, which
+ *   override the built-in components of the same name.
+ * @returns {Record<string, Function>} Table ready for @mdx-js/mdx.
+ */
+export function createRegistry(userComponents = {}) {
+  return { ...builtinComponents, ...userComponents };
+}
+
+/**
+ * Lists the available component names — useful for a readable error message
+ * when an `.mdx` references an unknown component.
+ *
+ * @param {Record<string, Function>} registry
+ * @returns {string[]} Names sorted alphabetically.
+ */
+export function listComponentNames(registry) {
+  return Object.keys(registry).sort();
+}

package/src/scroll-to-top.js

@@ -0,0 +1,65 @@
+/**
+ * Back to the top of the page.
+ *
+ * No JavaScript: a link to the `top` fragment, which the HTML specification
+ * reserves for the top of the document when no element carries that
+ * identifier. The button therefore works without adding anything to the page.
+ *
+ * It only shows once the page has scrolled, through `animation-timeline`.
+ * Where the browser ignores it, it simply stays visible: a button always there
+ * is better than a button never there.
+ *
+ * @module @docpensieve/components/scroll-to-top
+ */
+
+import { createElement as h } from 'react';
+
+import { classNames, cls } from './classes.js';
+
+/**
+ * Arrow of the button.
+ *
+ * Drawn here rather than written as a character: a typographic chevron
+ * changes shape and alignment from one font to another.
+ */
+function Chevron() {
+  return h(
+    'svg',
+    {
+      className: cls('scrollTopIcon'),
+      viewBox: '0 0 24 24',
+      fill: 'none',
+      stroke: 'currentColor',
+      strokeWidth: 2,
+      strokeLinecap: 'round',
+      strokeLinejoin: 'round',
+      // The arrow duplicates the accessible name of the link: announcing it a
+      // second time would tell nothing.
+      'aria-hidden': 'true',
+      focusable: 'false',
+    },
+    h('path', { d: 'M12 19V5' }),
+    h('path', { d: 'm5 12 7-7 7 7' }),
+  );
+}
+
+/**
+ * Back-to-top button.
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any, label?: string,
+ * }} props `label` is read by screen readers. The children replace the arrow
+ *   with whatever you want.
+ */
+export function ScrollToTop({ className, style, children, label = 'Back to top' }) {
+  return h(
+    'a',
+    {
+      className: classNames(cls('scrollTop'), className),
+      style,
+      href: '#top',
+      'aria-label': label,
+    },
+    children ?? h(Chevron),
+  );
+}