@docpensieve/theme 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,56 @@
+# @docpensieve/theme
+
+> Composable themes
+
+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/theme
+```
+
+## Usage
+
+Two themes ship — Tailwind and a dependency-free custom theme — behind the
+same contract. Templates ask the theme for their classes rather than
+hard-coding them, which gives two renderings for a single set of templates.
+
+```js
+import { ThemeEngine, CustomProvider } from '@docpensieve/theme';
+
+const engine = new ThemeEngine().register(
+  'custom',
+  new CustomProvider({ tokens: { '--dp-accent': '#008060' } }),
+);
+```
+
+Writing your own takes two members:
+
+```ts
+import { BaseThemeProvider } from '@docpensieve/theme';
+import type { ThemeOutput, CompileContext } from '@docpensieve/theme';
+
+class MyProvider extends BaseThemeProvider {
+  get classes() {
+    return { nav: 'my-nav' };
+  }
+  async compile(context?: CompileContext): Promise<ThemeOutput> {
+    return { css: '.my-nav{}', variables: {} };
+  }
+}
+```
+
+`tailwindcss` is installed with the package: the default theme needs it, and
+starting a project should not ask for anything more. The custom theme does not
+use it.
+
+## Documentation
+
+See the [repository](https://github.com/Juniors017/docpensieve#readme).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@docpensieve/theme",
+  "version": "0.1.0",
+  "description": "DocPensieve theme system: composable providers (Tailwind, custom)",
+  "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",
+    "tailwindcss": "^4.3.3"
+  },
+  "keywords": [
+    "docpensieve",
+    "theme",
+    "css",
+    "tailwindcss",
+    "design-system"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Juniors017/docpensieve.git",
+    "directory": "packages/theme"
+  },
+  "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/base-provider.js

@@ -0,0 +1,62 @@
+/**
+ * Contract shared by every theme provider.
+ * @module @docpensieve/theme/base-provider
+ */
+
+/**
+ * @typedef {object} ThemeOutput
+ * @property {string} css CSS to concatenate into the final stylesheet.
+ * @property {Record<string, string>} variables Exposed CSS variables (`--dp-*`).
+ */
+
+/**
+ * @typedef {object} CompileContext
+ * @property {string[]} [candidates] Class names collected from the rendered
+ *   pages. A utility provider, Tailwind first and foremost, only emits the
+ *   matching rules; the others ignore them.
+ */
+
+/**
+ * Base class to extend in order to plug in a CSS framework.
+ *
+ * A provider generates no HTML: it supplies CSS, variables and a table of
+ * class aliases. That is what lets a single template render correctly under
+ * Tailwind as well as under the custom theme.
+ */
+export class BaseThemeProvider {
+  /** Short provider identifier, unique within the engine. */
+  static id = 'base';
+
+  /** @param {Record<string, any>} [options] Options taken from `config.theme`. */
+  constructor(options = {}) {
+    if (new.target === BaseThemeProvider) {
+      throw new TypeError('BaseThemeProvider is abstract: extend it instead of instantiating it.');
+    }
+    this.options = options;
+  }
+
+  /**
+   * Class aliases this provider imposes on the shell slots.
+   *
+   * Deliberately synchronous and outside `compile()`: templates need these
+   * classes to be rendered, and a utility provider needs the rendered pages to
+   * compile its CSS. Keeping them apart breaks that circular dependency.
+   *
+   * @returns {Record<string, string>} Redefined slots, the others falling back
+   *   to `DEFAULT_THEME_CLASSES`.
+   */
+  get classes() {
+    return {};
+  }
+
+  /**
+   * Produces the provider's CSS contribution.
+   *
+   * @param {CompileContext} [_context]
+   * @returns {Promise<ThemeOutput>}
+   * @abstract
+   */
+  async compile(_context) {
+    throw new Error(`${this.constructor.name} must implement compile().`);
+  }
+}

package/src/custom-provider.js

@@ -0,0 +1,69 @@
+/**
+ * DocPensieve's custom theme, with no external dependency.
+ *
+ * @module @docpensieve/theme/custom-provider
+ */
+
+import { BaseThemeProvider } from './base-provider.js';
+import { joinCss, readStyle } from './styles.js';
+
+/**
+ * Palette and measures of the light theme.
+ *
+ * Dark mode does not live here: it fits in two blocks of `custom.css`, since
+ * a flat table of variables cannot express a media query.
+ */
+export const DEFAULT_TOKENS = Object.freeze({
+  '--dp-bg': '#ffffff',
+  '--dp-bg-soft': '#f7f8fa',
+  '--dp-text': '#1c1e21',
+  '--dp-text-soft': '#5f6773',
+  '--dp-border': '#e3e6ea',
+  '--dp-rule': '#e8ebef',
+  '--dp-accent': '#5b57d1',
+  '--dp-accent-soft': '#f0effc',
+  '--dp-shadow': 'rgba(20, 24, 34, 0.12)',
+  '--dp-radius': '6px',
+  '--dp-font': 'system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+  '--dp-font-mono':
+    'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+  '--dp-content-width': 'none',
+  '--dp-sidebar-width': '15.5rem',
+  '--dp-toc-width': '13rem',
+});
+
+/** Custom theme: hand-written CSS, no dependency. */
+export class CustomProvider extends BaseThemeProvider {
+  static id = 'custom';
+
+  /**
+   * @param {{ tokens?: Record<string, string>, css?: string }} [options]
+   *   `tokens` overrides the palette and the measures — keys without a
+   *   leading `--` are prefixed by the engine. `css` is appended after the
+   *   default stylesheet, so it wins at equal specificity.
+   */
+  constructor(options = {}) {
+    super(options);
+    this.tokens = { ...DEFAULT_TOKENS, ...(options.tokens ?? {}) };
+    this.extraCss = options.css ?? '';
+  }
+
+  /**
+   * @returns {Promise<import('./base-provider.js').ThemeOutput>}
+   * @throws {ThemeError} When a stylesheet of the package is missing.
+   */
+  async compile() {
+    // Skeleton first, skin second: the grid and the sticky columns are shared
+    // with the other providers, only the visual decisions belong to this theme.
+    const [structure, prose, skin] = await Promise.all([
+      readStyle('structure.css'),
+      readStyle('prose.css'),
+      readStyle('custom.css'),
+    ]);
+
+    return {
+      css: joinCss(structure, prose, skin, this.extraCss),
+      variables: this.tokens,
+    };
+  }
+}

package/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * @docpensieve/theme — composable theme providers.
+ * @module @docpensieve/theme
+ */
+
+/**
+ * Types of the provider contract, re-exported for consumers of the published
+ * package: without this they would only be reachable through an internal path.
+ *
+ * @typedef {import('./base-provider.js').ThemeOutput} ThemeOutput
+ * @typedef {import('./base-provider.js').CompileContext} CompileContext
+ */
+
+export { BaseThemeProvider } from './base-provider.js';
+export { CustomProvider, DEFAULT_TOKENS } from './custom-provider.js';
+export { TailwindProvider } from './tailwind-provider.js';
+export { ThemeEngine } from './theme-engine.js';

package/src/styles.js

@@ -0,0 +1,45 @@
+/**
+ * Reads the stylesheets shipped with the package.
+ *
+ * @module @docpensieve/theme/styles
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ThemeError } 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 a stylesheet of the package.
+ *
+ * @param {string} name File name, `'structure.css'` for instance.
+ * @returns {Promise<string>} Contents, trimmed.
+ * @throws {ThemeError} When the stylesheet is missing.
+ */
+export async function readStyle(name) {
+  try {
+    return (await readFile(path.join(STYLES_DIR, name), 'utf8')).trim();
+  } catch (cause) {
+    throw new ThemeError(`Theme stylesheet not found: ${name}.`, {
+      cause,
+      hint: 'The @docpensieve/theme package looks incomplete: reinstall the dependencies.',
+    });
+  }
+}
+
+/**
+ * Joins several CSS fragments into one stylesheet.
+ *
+ * @param {...(string | undefined | null)} parts
+ * @returns {string}
+ */
+export function joinCss(...parts) {
+  return parts
+    .map((part) => (part ?? '').trim())
+    .filter(Boolean)
+    .join('\n\n');
+}

package/src/tailwind-provider.js

@@ -0,0 +1,167 @@
+/**
+ * Theme built on Tailwind CSS.
+ *
+ * @module @docpensieve/theme/tailwind-provider
+ */
+
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { ThemeError } from '@docpensieve/shared';
+
+import { BaseThemeProvider } from './base-provider.js';
+import { joinCss, readStyle } from './styles.js';
+
+/**
+ * DocPensieve tokens, as literal values of the Tailwind palette.
+ *
+ * Tailwind only emits a theme variable when a class uses it:
+ * `var(--color-slate-700)` would stay empty as long as nobody writes
+ * `text-slate-700`. The values are therefore copied, at the cost of a possible
+ * drift if Tailwind retouches its palette.
+ */
+const TAILWIND_TOKENS = Object.freeze({
+  '--dp-bg': '#ffffff',
+  '--dp-bg-soft': 'oklch(96.8% 0.007 247.896)',
+  '--dp-text': 'oklch(20.8% 0.042 265.755)',
+  '--dp-text-soft': 'oklch(55.4% 0.046 257.417)',
+  '--dp-border': 'oklch(92.9% 0.013 255.508)',
+  '--dp-rule': 'oklch(92.9% 0.013 255.508)',
+  '--dp-accent': 'oklch(51.1% 0.262 276.966)',
+  '--dp-accent-soft': 'oklch(96.2% 0.018 272.314)',
+  '--dp-shadow': 'rgba(15, 23, 42, 0.12)',
+  '--dp-radius': '0.375rem',
+  '--dp-font': 'var(--font-sans, ui-sans-serif, system-ui, sans-serif)',
+  '--dp-font-mono': 'var(--font-mono, ui-monospace, monospace)',
+  '--dp-content-width': 'none',
+  '--dp-sidebar-width': '15.5rem',
+  '--dp-toc-width': '13rem',
+});
+
+/**
+ * Slots dressed in Tailwind utilities.
+ *
+ * The `dp-*` classes stay first: they are what the shared skeleton and the
+ * bridge target. Everything else is utilities, including the current-page
+ * state, expressed through the `aria-[current=page]` variant.
+ */
+const TAILWIND_CLASSES = Object.freeze({
+  header:
+    'dp-header border-b border-slate-200 bg-white/90 backdrop-blur dark:border-slate-800 dark:bg-slate-950/90',
+  brand: 'dp-brand font-semibold tracking-tight text-slate-900 no-underline dark:text-slate-100',
+  versionsList:
+    'dp-versions-list rounded-md border border-slate-200 bg-white p-1 shadow-lg dark:border-slate-800 dark:bg-slate-900',
+  sidebar: 'dp-sidebar text-sm',
+  navLink:
+    'dp-nav-link block rounded px-2 py-1 no-underline text-slate-600 hover:bg-slate-100 hover:text-slate-900 aria-[current=page]:bg-indigo-50 aria-[current=page]:font-medium aria-[current=page]:text-indigo-700 dark:text-slate-400 dark:hover:bg-slate-800 dark:hover:text-slate-100 dark:aria-[current=page]:bg-slate-800 dark:aria-[current=page]:text-indigo-300',
+  navLabel:
+    'dp-nav-label block px-2 pt-3 pb-1 text-xs font-semibold uppercase tracking-wide text-slate-500',
+  toc: 'dp-toc text-sm',
+  tocTitle: 'dp-toc-title mb-2 text-xs font-semibold uppercase tracking-wide text-slate-500',
+  tocList: 'dp-toc-list border-l border-slate-200 dark:border-slate-800',
+  footer:
+    'dp-footer border-t border-slate-200 p-6 text-center text-sm text-slate-500 dark:border-slate-800',
+});
+
+/** Minimal stylesheet handed to Tailwind, unless the project says otherwise. */
+const DEFAULT_SOURCE = '@import "tailwindcss";';
+
+/** Tailwind theme: on-demand compilation of the classes actually used. */
+export class TailwindProvider extends BaseThemeProvider {
+  static id = 'tailwind';
+
+  /**
+   * @param {{ tokens?: Record<string, string>, css?: string, source?: string }} [options]
+   *   `source` replaces the entry stylesheet handed to Tailwind, to put a
+   *   `@theme` block or additional directives in it.
+   */
+  constructor(options = {}) {
+    super(options);
+    this.tokens = { ...TAILWIND_TOKENS, ...(options.tokens ?? {}) };
+    this.extraCss = options.css ?? '';
+    this.source = options.source ?? DEFAULT_SOURCE;
+  }
+
+  /** @returns {Record<string, string>} Slots dressed in utilities. */
+  get classes() {
+    return { ...TAILWIND_CLASSES };
+  }
+
+  /**
+   * Loads Tailwind.
+   *
+   * It ships as a dependency of this package, but is only loaded when this
+   * provider compiles: a project on the custom theme never pays for it. A
+   * failure here means a broken installation.
+   *
+   * @returns {Promise<{ compile: Function, dir: string }>}
+   * @throws {ThemeError} When the `tailwindcss` package cannot be found.
+   */
+  async #loadTailwind() {
+    try {
+      const require = createRequire(import.meta.url);
+      const dir = path.dirname(require.resolve('tailwindcss/package.json'));
+      const { compile } = await import('tailwindcss');
+      return { compile, dir };
+    } catch (cause) {
+      throw new ThemeError('The "tailwindcss" package cannot be found.', {
+        cause,
+        hint: 'Reinstall the dependencies with "npm install", or choose the custom theme in docpensieve.config.js.',
+      });
+    }
+  }
+
+  /**
+   * @param {import('./base-provider.js').CompileContext} [context]
+   * @returns {Promise<import('./base-provider.js').ThemeOutput>}
+   * @throws {ThemeError} When Tailwind is missing or its compilation fails.
+   */
+  async compile(context = {}) {
+    const { compile, dir } = await this.#loadTailwind();
+
+    // The classes collected from the rendered pages, plus ours in case the
+    // provider is compiled outside the generator. The union avoids emitting
+    // rules for utilities nobody writes.
+    const candidates = new Set(context.candidates ?? []);
+    for (const value of Object.values(TAILWIND_CLASSES)) {
+      for (const token of value.split(/\s+/)) if (token) candidates.add(token);
+    }
+
+    let utilities;
+    try {
+      const compiler = await compile(this.source, {
+        base: dir,
+        /** @param {string} id */
+        async loadStylesheet(id) {
+          const relative =
+            id === 'tailwindcss' ? 'index.css' : `${id.replace(/^tailwindcss\//, '')}.css`;
+          const file = path.join(dir, relative);
+          return { path: file, base: path.dirname(file), content: await readFile(file, 'utf8') };
+        },
+        async loadModule() {
+          throw new ThemeError('Tailwind plugins are not supported yet.', {
+            hint: 'Remove the @plugin directives from theme.source.',
+          });
+        },
+      });
+      utilities = compiler.build([...candidates]);
+    } catch (cause) {
+      if (cause instanceof ThemeError) throw cause;
+      throw new ThemeError('Tailwind compilation failed.', { cause });
+    }
+
+    const [structure, prose, bridge] = await Promise.all([
+      readStyle('structure.css'),
+      readStyle('prose.css'),
+      readStyle('tailwind-bridge.css'),
+    ]);
+
+    // Tailwind first — Preflight included: the skeleton, the prose and the
+    // bridge must be able to correct it.
+    return {
+      css: joinCss(utilities, structure, prose, bridge, this.extraCss),
+      variables: this.tokens,
+    };
+  }
+}

package/src/theme-engine.js

@@ -0,0 +1,116 @@
+/**
+ * Registration and merging of theme providers.
+ *
+ * @module @docpensieve/theme/theme-engine
+ */
+
+import { DEFAULT_THEME_CLASSES, ThemeError } from '@docpensieve/shared';
+
+import { BaseThemeProvider } from './base-provider.js';
+
+/**
+ * Serialises a table of variables into a `:root` block.
+ *
+ * @param {Record<string, string>} variables
+ * @returns {string} CSS block, or an empty string when there is nothing to write.
+ */
+function toRootBlock(variables) {
+  const entries = Object.entries(variables);
+  if (entries.length === 0) return '';
+
+  const declarations = entries
+    .map(([name, value]) => `  ${name.startsWith('--') ? name : `--${name}`}: ${value};`)
+    .join('\n');
+
+  return `:root {\n${declarations}\n}\n`;
+}
+
+/** Combines several providers into a single CSS output. */
+export class ThemeEngine {
+  constructor() {
+    /** @type {Map<string, BaseThemeProvider>} */
+    this.providers = new Map();
+  }
+
+  /**
+   * @param {string} id Provider identifier.
+   * @param {BaseThemeProvider} provider
+   * @returns {this} To chain registrations.
+   */
+  register(id, provider) {
+    if (!(provider instanceof BaseThemeProvider)) {
+      throw new TypeError(`The provider "${id}" must extend BaseThemeProvider.`);
+    }
+    this.providers.set(id, provider);
+    return this;
+  }
+
+  /**
+   * @param {string} id
+   * @returns {BaseThemeProvider | undefined}
+   */
+  get(id) {
+    return this.providers.get(id);
+  }
+
+  /**
+   * Shell class aliases, all providers combined.
+   *
+   * Synchronous and independent of `compile()`: templates need these classes
+   * to be rendered, whereas a utility provider needs the rendered pages to
+   * compile its CSS.
+   *
+   * @returns {Record<string, string>} Shared slots, overridden by each
+   *   provider in registration order.
+   */
+  get classes() {
+    const merged = { ...DEFAULT_THEME_CLASSES };
+    for (const provider of this.providers.values()) Object.assign(merged, provider.classes ?? {});
+    return merged;
+  }
+
+  /**
+   * Merges the outputs of every registered provider.
+   *
+   * Registration order sets precedence: the last one registered wins on
+   * variables and class aliases, and its CSS is concatenated last, so it wins
+   * at equal specificity.
+   *
+   * The merged variables are emitted in a single `:root` block placed
+   * **before** the providers' CSS. That is what lets a provider override
+   * another's palette without duplicating its rules.
+   *
+   * @param {import('./base-provider.js').CompileContext} [context] Passed as
+   *   is to every provider.
+   * @returns {Promise<import('./base-provider.js').ThemeOutput>}
+   * @throws {ThemeError} When no provider is registered.
+   */
+  async compile(context) {
+    if (this.providers.size === 0) {
+      throw new ThemeError('No theme provider registered.', {
+        hint: 'Register at least one provider, for example new CustomProvider(), before calling compile().',
+      });
+    }
+
+    /** @type {Record<string, string>} */
+    const variables = {};
+    /** @type {string[]} */
+    const sheets = [];
+
+    for (const [id, provider] of this.providers) {
+      let output;
+      try {
+        output = await provider.compile(context);
+      } catch (cause) {
+        if (cause instanceof ThemeError) throw cause;
+        throw new ThemeError(`The provider "${id}" failed.`, { cause });
+      }
+
+      Object.assign(variables, output?.variables ?? {});
+      if (output?.css) sheets.push(output.css.trim());
+    }
+
+    const css = [toRootBlock(variables), ...sheets].filter(Boolean).join('\n\n');
+    return { css: `${css}\n`, variables };
+  }
+}