@docpensieve/components 0.1.0

package/src/site.js

@@ -0,0 +1,110 @@
+/**
+ * Page context handed to components.
+ *
+ * The compiler plugins rewrite the URLs of the tree built from the Markdown,
+ * but that work happens **before** React renders the components: a link
+ * produced by a component escapes them. This module gives it what it needs
+ * to resolve itself, following the same rules (ADR-006).
+ *
+ * It also carries what is needed to find a **file** of the version, which a
+ * component that includes a resource at build time requires.
+ *
+ * @module @docpensieve/components/site
+ */
+
+import path from 'node:path';
+
+/**
+ * Targets left as they are: external link, anchor, mailto, data:.
+ * Same rule as in the compiler.
+ */
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+
+/**
+ * @typedef {object} SiteContext
+ * @property {string} url URL of the page being rendered.
+ * @property {string} [dirUrl] Folder of the source file, mapped into URL
+ *   space. Base of relative targets: the page URL has one more level.
+ * @property {string} basePath Version root, deployment prefix included.
+ * @property {string} [filepath] Source file of the page, on disk.
+ * @property {string} [sourceDir] Source folder of the version.
+ */
+
+/** @type {SiteContext} */
+let context = { url: '/', basePath: '/' };
+
+/**
+ * Declares the page being rendered.
+ *
+ * Set by the generator before every page, like the class table.
+ *
+ * @param {Partial<SiteContext>} [page]
+ */
+export function setSiteContext(page = {}) {
+  context = {
+    url: page.url ?? '/',
+    dirUrl: page.dirUrl,
+    basePath: page.basePath ?? '/',
+    filepath: page.filepath,
+    sourceDir: page.sourceDir,
+  };
+}
+
+/** @returns {SiteContext} The current context. */
+export function getSiteContext() {
+  return context;
+}
+
+/**
+ * Resolves a target written by an author into a site URL.
+ *
+ * Same rules as for Markdown content: a relative target resolves against the
+ * page's folder, an absolute target starts from the version root.
+ *
+ * @param {string | undefined} target
+ * @returns {string | undefined} The resolved target, or as is when external.
+ */
+export function resolveUrl(target) {
+  if (typeof target !== 'string' || target === '' || EXTERNAL.test(target)) return target;
+
+  const { url, dirUrl, basePath } = context;
+
+  if (target.startsWith('/')) {
+    if (basePath === '/' || target.startsWith(basePath)) return target;
+    return `${basePath.replace(/\/$/, '')}${target}`;
+  }
+
+  // The origin is throwaway: only the resolved path matters. The base is the
+  // source file's folder, not the page URL — see `dirUrl`.
+  const resolved = new URL(target, `https://docpensieve.invalid${dirUrl ?? url}`);
+  return resolved.pathname + resolved.search + resolved.hash;
+}
+
+/**
+ * Resolves a target into a file path, for a resource read at build time.
+ *
+ * Same landmarks as for a URL, mapped to the disk: a relative target starts
+ * from the page's file, an absolute one from the version folder. Nothing can
+ * leave that folder — a page does not read the rest of the machine.
+ *
+ * @param {string} target
+ * @returns {string} Absolute path, inside the source folder.
+ * @throws {Error} When the context is missing or the target escapes it.
+ */
+export function resolveFile(target) {
+  const { filepath, sourceDir } = context;
+  if (!sourceDir) {
+    throw new Error('No source folder known: the page context was not set.');
+  }
+
+  const base = target.startsWith('/')
+    ? path.join(sourceDir, target.slice(1))
+    : path.resolve(path.dirname(filepath ?? sourceDir), target);
+
+  const resolved = path.resolve(base);
+  const root = path.resolve(sourceDir);
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+    throw new Error(`The target "${target}" leaves the version folder.`);
+  }
+  return resolved;
+}

package/src/skill.js

@@ -0,0 +1,200 @@
+/**
+ * Level gauge, as a bar or a circle.
+ *
+ * No JavaScript: the fill is done in CSS, and animates as it enters the
+ * viewport where `animation-timeline` exists. Elsewhere, the gauge is simply
+ * full — the value stays readable, which is what matters.
+ *
+ * @module @docpensieve/components/skill
+ */
+
+import { Fragment, createElement as h } from 'react';
+
+import { DocPensieveError } from '@docpensieve/shared';
+
+import { classNames, cls } from './classes.js';
+
+/** Shapes accepted by the gauge. */
+export const SKILL_SHAPES = Object.freeze(['bar', 'circle']);
+
+/**
+ * Radius giving the circle a circumference of a hundred units.
+ *
+ * Chosen for that reason: the level then goes as is into `stroke-dasharray`,
+ * with no multiplication or rounding. `100 / (2 * Math.PI)`.
+ */
+const RADIUS = 15.915_494;
+
+/**
+ * Bar gauge.
+ *
+ * @param {{ level: number, name: any, showValue: boolean, icon?: any, accessibleName: string }} props
+ * @returns {any}
+ */
+function Bar({ level, name, showValue, icon, accessibleName }) {
+  // Fragment rather than a div: one more wrapper would bring nothing and
+  // would stand between the gauge and its parts.
+  return h(
+    Fragment,
+    null,
+    h(
+      'div',
+      { className: cls('skillHead') },
+      h(
+        'span',
+        { className: cls('skillName') },
+        icon ? h('span', { className: cls('skillIcon') }, icon) : null,
+        name,
+      ),
+      showValue ? h('span', { className: cls('skillValue') }, `${level}%`) : null,
+    ),
+    h(
+      'div',
+      { className: cls('skillTrack'), ...measure(level, accessibleName) },
+      h('div', {
+        className: cls('skillFill'),
+        // The value goes through a variable: the entry animation uses it as
+        // its end point, and the base rule as the width.
+        style: { '--dp-skill-level': `${level}%` },
+      }),
+    ),
+  );
+}
+
+/**
+ * Circle gauge.
+ *
+ * The SVG is decorative: the wrapper carries the role and the value, so what
+ * is announced does not depend on what is drawn.
+ *
+ * @param {{ level: number, name: any, showValue: boolean, icon?: any, accessibleName: string }} props
+ * @returns {any}
+ */
+function Circle({ level, name, showValue, icon, accessibleName }) {
+  return h(
+    Fragment,
+    null,
+    h(
+      'div',
+      { className: cls('skillDial'), ...measure(level, accessibleName) },
+      h(
+        'svg',
+        { viewBox: '0 0 36 36', 'aria-hidden': 'true', focusable: 'false' },
+        h('circle', { className: cls('skillDialTrack'), cx: 18, cy: 18, r: RADIUS }),
+        h('circle', {
+          className: cls('skillDialFill'),
+          cx: 18,
+          cy: 18,
+          r: RADIUS,
+          // With a circumference of a hundred, the level is directly the
+          // drawn share. The entry animation starts from zero and ends here.
+          style: { '--dp-skill-level': String(level) },
+        }),
+      ),
+      showValue ? h('span', { className: cls('skillDialValue') }, `${level}%`) : null,
+    ),
+    h(
+      'div',
+      { className: cls('skillName') },
+      icon ? h('span', { className: cls('skillIcon') }, icon) : null,
+      name,
+    ),
+  );
+}
+
+/**
+ * Attributes describing the measure.
+ *
+ * `meter` describes exactly this: a value within a known range. The role
+ * carries it, so hiding it on screen does not remove it from what a screen
+ * reader announces.
+ *
+ * @param {number} level
+ * @param {string} name Name announced by a screen reader.
+ * @returns {Record<string, unknown>}
+ */
+function measure(level, name) {
+  return {
+    role: 'meter',
+    'aria-valuenow': level,
+    'aria-valuemin': 0,
+    'aria-valuemax': 100,
+    'aria-label': name,
+  };
+}
+
+/**
+ * Named gauge, from 0 to 100.
+ *
+ * @example
+ * <Skill name="Accessibility" level={80} />
+ * <Skill name="Accessibility" level={80} shape="circle" />
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any,
+ *   name?: any, level?: number, showValue?: boolean, shape?: string,
+ *   icon?: any, color?: string, label?: string,
+ * }} props `children` stands as a comment under the gauge. `showValue` hides
+ *   the numeric percentage without touching what the gauge announces.
+ *   `shape` picks between the bar and the circle. `icon` goes before the
+ *   name — a `LogoIcon` fits there. `color` tints the fill: any CSS colour,
+ *   the accent colour by default. `label` names the gauge for screen readers
+ *   when `name` is not text.
+ * @throws {DocPensieveError} Without a name, outside 0–100, or with an
+ *   unknown shape.
+ */
+export function Skill({
+  className,
+  style,
+  children,
+  name,
+  level,
+  showValue = true,
+  shape = 'bar',
+  icon,
+  color,
+  label,
+}) {
+  if (name === undefined || name === null || name === '') {
+    throw new DocPensieveError('A <Skill> without a name.', {
+      hint: 'Give it a name: <Skill name="CSS" level={80} />.',
+    });
+  }
+
+  if (typeof level !== 'number' || Number.isNaN(level) || level < 0 || level > 100) {
+    throw new DocPensieveError(`Invalid level for "${name}": "${level}".`, {
+      hint: 'level expects a number from 0 to 100.',
+    });
+  }
+
+  if (!SKILL_SHAPES.includes(shape)) {
+    throw new DocPensieveError(`Unknown gauge shape: "${shape}".`, {
+      hint: `Accepted values: ${SKILL_SHAPES.join(', ')}.`,
+    });
+  }
+
+  // The name a screen reader announces: `name` if it is text, otherwise
+  // `label`. With neither, the gauge announced itself as “45%” without saying
+  // of what — the only case where this component kept quiet instead of
+  // throwing.
+  const accessibleName = typeof name === 'string' ? name : label;
+  if (typeof accessibleName !== 'string' || accessibleName === '') {
+    throw new DocPensieveError('A <Skill> whose name is not text must carry label.', {
+      hint: 'Add label="…": it is the name a screen reader will read.',
+    });
+  }
+
+  const Shape = shape === 'circle' ? Circle : Bar;
+
+  return h(
+    'div',
+    {
+      className: classNames(cls('skill', shape === 'circle' && 'circle'), className),
+      // The tint goes through a variable: bar and circle read it in the same
+      // place, and a project can set it higher up for a whole group.
+      style: color ? { '--dp-skill-color': color, ...style } : style,
+    },
+    h(Shape, { level, name, showValue, icon, accessibleName }),
+    children ? h('div', { className: cls('skillNote') }, children) : null,
+  );
+}

package/src/styles.js

@@ -0,0 +1,35 @@
+/**
+ * Stylesheet of the shipped components.
+ *
+ * @module @docpensieve/components/styles
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { DocPensieveError } from '@docpensieve/shared';
+
+/** Stylesheet folder, resolved from this module rather than from the cwd. */
+const STYLES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'styles');
+
+/**
+ * Reads the default look of the components.
+ *
+ * It is concatenated with the theme's by the caller: a provider that
+ * redefines a slot replaces the `dp-*` class with its own, and these rules
+ * then stop applying by themselves.
+ *
+ * @returns {Promise<string>} CSS, trimmed.
+ * @throws {DocPensieveError} When the stylesheet is missing.
+ */
+export async function componentsCss() {
+  try {
+    return (await readFile(path.join(STYLES_DIR, 'components.css'), 'utf8')).trim();
+  } catch (cause) {
+    throw new DocPensieveError('Components stylesheet not found.', {
+      cause,
+      hint: 'The @docpensieve/components package looks incomplete: reinstall the dependencies.',
+    });
+  }
+}

package/src/time-timer.js

@@ -0,0 +1,251 @@
+/**
+ * Conditional display by date or duration.
+ *
+ * **Mind the meaning on a static site**: “right now” means the moment of the
+ * **build**, not of reading. A page built in November will still show “the
+ * offer starts soon” in January if the site has not been rebuilt in between.
+ *
+ * This is not a flaw: it is what a time-based component becomes without
+ * client-side JavaScript. A scheduled build — a cron job in CI — is enough to
+ * keep it right.
+ *
+ * @module @docpensieve/components/time-timer
+ */
+
+import { Children, Fragment, cloneElement, createElement as h, isValidElement } from 'react';
+
+import { DocPensieveError } from '@docpensieve/shared';
+
+/** Matches a duration: `30d`, `2h`, `45m`. */
+const DURATION = /^(\d+)([dhm])$/;
+
+/**
+ * Content shown before the period.
+ *
+ * No wrapper: a `span` around the author's content would become invalid
+ * markup as soon as they write a paragraph in it — which happens as soon as a
+ * blank line separates their text. The content therefore keeps its nature,
+ * inline or block.
+ *
+ * @param {{ children?: any, start?: string }} props
+ */
+export function FallbackBefore({ children }) {
+  return h(Fragment, null, children);
+}
+
+/**
+ * Content shown after the period.
+ *
+ * Without a wrapper, for the same reason as {@link FallbackBefore}.
+ *
+ * @param {{ children?: any, end?: string }} props
+ */
+export function FallbackAfter({ children }) {
+  return h(Fragment, null, children);
+}
+
+/**
+ * Parses a date in the `DD/MM[/YYYY] [HH:mm]` format.
+ *
+ * @param {string | undefined} text
+ * @param {boolean} strict Read in UTC rather than in local time.
+ * @param {Date} now Provides the default year when it is omitted.
+ * @returns {Date | null}
+ */
+function parseDate(text, strict, now) {
+  if (!text) return null;
+
+  const [datePart, timePart] = String(text).trim().split(/\s+/);
+  const [day, month, year] = datePart.split('/');
+  const [hours = '0', minutes = '0'] = timePart ? timePart.split(':') : [];
+
+  const targetYear = year ? Number(year) : strict ? now.getUTCFullYear() : now.getFullYear();
+
+  // Named fields rather than a spread array: `new Date(...array)` has no
+  // valid signature, the constructor expects distinct arguments.
+  const m = Number(month) - 1;
+  const d = Number(day);
+  const hh = Number(hours);
+  const mm = Number(minutes);
+
+  const date = strict
+    ? new Date(Date.UTC(targetYear, m, d, hh, mm))
+    : new Date(targetYear, m, d, hh, mm);
+
+  /*
+   * The constructor rolls over rather than failing: month 13 becomes January
+   * of the following year, 30 February becomes 1 March. A `NaN` therefore
+   * almost never happens, and a typo passed for a valid date — shifting the
+   * display without a word.
+   *
+   * So the resulting date is read back: if it does not say what was written,
+   * what was written does not exist.
+   */
+  const readBack = strict
+    ? [
+        date.getUTCFullYear(),
+        date.getUTCMonth(),
+        date.getUTCDate(),
+        date.getUTCHours(),
+        date.getUTCMinutes(),
+      ]
+    : [date.getFullYear(), date.getMonth(), date.getDate(), date.getHours(), date.getMinutes()];
+
+  const invalid =
+    Number.isNaN(date.getTime()) ||
+    [targetYear, m, d, hh, mm].some((value, index) => value !== readBack[index]);
+
+  if (invalid) {
+    throw new DocPensieveError(`Invalid date in TimeTimer: "${text}".`, {
+      hint: 'Expected format: DD/MM/YYYY, optionally followed by HH:mm.',
+    });
+  }
+  return date;
+}
+
+/**
+ * Shifts a date by a duration.
+ *
+ * @param {Date} from
+ * @param {string} duration
+ * @param {boolean} strict
+ * @returns {Date}
+ */
+function addDuration(from, duration, strict) {
+  const match = String(duration).trim().match(DURATION);
+  if (!match) {
+    // Showing nothing after a mere console warning would let a typo make a
+    // block vanish without a word — exactly what the project sets out to avoid.
+    throw new DocPensieveError(`Invalid duration in TimeTimer: "${duration}".`, {
+      hint: 'Accepted formats: 30d (days), 2h (hours), 45m (minutes).',
+    });
+  }
+
+  const [, amount, unit] = match;
+  const end = new Date(from);
+  const n = Number(amount);
+
+  if (unit === 'd') strict ? end.setUTCDate(end.getUTCDate() + n) : end.setDate(end.getDate() + n);
+  else if (unit === 'h')
+    strict ? end.setUTCHours(end.getUTCHours() + n) : end.setHours(end.getHours() + n);
+  else strict ? end.setUTCMinutes(end.getUTCMinutes() + n) : end.setMinutes(end.getMinutes() + n);
+
+  return end;
+}
+
+/**
+ * Places the current moment relative to the period.
+ *
+ * @param {Date} now
+ * @param {Date | null} start
+ * @param {Date | null} end
+ * @param {Date | null} beforeStart Lower bound of the “before” fallback.
+ * @param {Date | null} afterEnd    Upper bound of the “after” fallback.
+ * @returns {'during' | 'before' | 'after' | 'none'}
+ */
+function locate(now, start, end, beforeStart, afterEnd) {
+  if (!start || !end) return 'none';
+  if (now >= start && now <= end) return 'during';
+
+  if (now < start) {
+    if (beforeStart) return now >= beforeStart ? 'before' : 'none';
+    return 'before';
+  }
+  if (afterEnd) return now <= afterEnd ? 'after' : 'none';
+  return 'after';
+}
+
+/**
+ * Shows its content during a period, with fallbacks before and after.
+ *
+ * @example
+ * <TimeTimer date="25/12/2025">
+ *   Merry Christmas
+ *   <FallbackBefore>It is not Christmas yet</FallbackBefore>
+ *   <FallbackAfter>Christmas is over</FallbackAfter>
+ * </TimeTimer>
+ *
+ * @param {{
+ *   date?: string, start?: string, duration?: string,
+ *   strict?: boolean, children?: any, now?: Date,
+ * }} props `now` only exists for tests: without it, the build moment stands.
+ */
+export function TimeTimer({ date, start, duration, strict = false, children, now }) {
+  const current = now ?? new Date();
+
+  let startDate = null;
+  let endDate = null;
+
+  if (date && !start) {
+    startDate = parseDate(date, strict, current);
+    // A date alone covers the whole day.
+    if (startDate) endDate = addDuration(startDate, '1d', strict);
+  } else if (start && duration) {
+    startDate = parseDate(start, strict, current);
+    if (startDate) endDate = addDuration(startDate, duration, strict);
+  }
+
+  const { before, after, main } = extractFallbacks(children);
+
+  const state = locate(
+    current,
+    startDate,
+    endDate,
+    before?.props?.start ? parseDate(before.props.start, strict, current) : null,
+    after?.props?.end ? parseDate(after.props.end, strict, current) : null,
+  );
+
+  if (state === 'before') return before ?? null;
+  if (state === 'after') return after ?? null;
+  if (state === 'during') return h(Fragment, null, ...main);
+  return null;
+}
+
+/**
+ * Separates the fallbacks from the main content, at any depth.
+ *
+ * MDX wraps a component's children in a `<p>` when no blank line separates
+ * them — the most natural way to write, and the one of the usage examples. A
+ * search limited to the first level would then find nothing, and the
+ * component would show nothing at all, without saying so.
+ *
+ * @param {any} children
+ * @returns {{ before: any, after: any, main: any[] }}
+ */
+function extractFallbacks(children) {
+  let before = null;
+  let after = null;
+
+  /**
+   * @param {any} nodes
+   * @returns {any[]} The same nodes, fallbacks removed.
+   */
+  function walk(nodes) {
+    return Children.toArray(nodes)
+      .map((child) => {
+        if (!isValidElement(child)) return child;
+
+        if (child.type === FallbackBefore) {
+          before ??= child;
+          return null;
+        }
+        if (child.type === FallbackAfter) {
+          after ??= child;
+          return null;
+        }
+
+        // `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 {{ children?: any }} */ (child.props);
+        if (props?.children === undefined) return child;
+        const rest = walk(props.children);
+        return cloneElement(child, { key: child.key }, ...rest);
+      })
+      .filter((child) => child !== null);
+  }
+
+  // The walk must come before building the object: in a literal, `before` and
+  // `after` would be read before `walk` fills them, and would always be null.
+  const main = walk(children);
+  return { before, after, main };
+}

package/src/tooltip.js

@@ -0,0 +1,89 @@
+/**
+ * Tooltip on hover and from the keyboard.
+ *
+ * No JavaScript: the bubble is a real element that CSS reveals on hover and
+ * on focus. The trigger is therefore reachable from the keyboard, and the
+ * bubble announced through `aria-describedby` rather than guessed.
+ *
+ * @module @docpensieve/components/tooltip
+ */
+
+import { Children, createElement as h, isValidElement, useId } from 'react';
+
+import { DocPensieveError } from '@docpensieve/shared';
+
+import { classNames, cls } from './classes.js';
+
+/** Sides the bubble can sit on. */
+export const TOOLTIP_PLACEMENTS = Object.freeze(['top', 'bottom', 'left', 'right']);
+
+/**
+ * Removes the paragraph MDX sometimes wraps the term in.
+ *
+ * The content of a tag left alone on its line becomes a paragraph — and the
+ * formatter puts that content on its own line as soon as the tag is somewhat
+ * indented, inside a card or a column for instance. The trigger being an
+ * inline element, the result would be invalid markup that the browser would
+ * silently undo.
+ *
+ * A tooltip term is text by nature: unwrapping that paragraph gives back what
+ * the author meant to write.
+ *
+ * @param {any} children
+ * @returns {any}
+ */
+function withoutParagraph(children) {
+  const nodes = Children.toArray(children);
+  if (nodes.length !== 1) return children;
+
+  const only = nodes[0];
+  if (!isValidElement(only) || only.type !== 'p') return children;
+
+  return /** @type {{ children?: any }} */ (only.props).children;
+}
+
+/**
+ * Term with a tooltip.
+ *
+ * @example
+ * <Tooltip text="Generation of a complete site">build</Tooltip>
+ *
+ * @param {{
+ *   className?: string, style?: object, children?: any,
+ *   text?: string, placement?: string,
+ * }} props `text` is the content of the bubble; the children are the term it
+ *   explains.
+ * @throws {DocPensieveError} Without text, or with an unknown side.
+ */
+export function Tooltip({ className, style, children, text, placement = 'top' }) {
+  // An empty bubble would never appear: better to say so at build time than
+  // to leave a hover with no effect.
+  if (typeof text !== 'string' || text.trim() === '') {
+    throw new DocPensieveError('A <Tooltip> without text.', {
+      hint: 'Give the content of the bubble: <Tooltip text="…">term</Tooltip>.',
+    });
+  }
+
+  if (!TOOLTIP_PLACEMENTS.includes(placement)) {
+    throw new DocPensieveError(`Unknown tooltip placement: "${placement}".`, {
+      hint: `Accepted values: ${TOOLTIP_PLACEMENTS.join(', ')}.`,
+    });
+  }
+
+  // `useId` gives an identifier stable for the page; its colons are valid in
+  // HTML but get in the way everywhere else, so they are removed.
+  const id = `dp-tooltip-${useId().replace(/:/g, '')}`;
+
+  return h(
+    'span',
+    { className: classNames(cls('tooltip', placement), className), style },
+    // `tabIndex` makes the term reachable from the keyboard: without it, the
+    // bubble would only exist for mouse users.
+    h(
+      'span',
+      { className: cls('tooltipTrigger'), tabIndex: 0, 'aria-describedby': id },
+      withoutParagraph(children),
+    ),
+    h('span', { className: cls('tooltipBubble'), id, role: 'tooltip' }, text),
+  );
+}