@docpensieve/theme 0.1.0

package/styles/tailwind-bridge.css

@@ -0,0 +1,131 @@
+/*
+ * Bridge between the DocPensieve shell and Tailwind.
+ *
+ * Tailwind dresses the shell through utilities set on the slots: this file
+ * only holds what a utility cannot express — the descendant selectors of the
+ * menu — and the dark-mode palette of the --dp-* tokens, which Tailwind does
+ * not emit on its own.
+ *
+ * The article typography comes from prose.css: Tailwind's Preflight resets
+ * headings, lists and quotes.
+ */
+
+/* --- Dark mode ----------------------------------------------------------- */
+
+/*
+ * Tailwind v4 varies `dark:` on the system preference. These blocks follow
+ * the same rule for the shared tokens, with the `.light` / `.dark` escape
+ * hatch that theme.darkMode allows.
+ */
+@media (prefers-color-scheme: dark) {
+  :root:not(.light) {
+    --dp-bg: oklch(12.9% 0.042 264.695);
+    --dp-bg-soft: oklch(20.8% 0.042 265.755);
+    --dp-text: oklch(96.8% 0.007 247.896);
+    --dp-text-soft: oklch(70.4% 0.04 256.788);
+    --dp-border: oklch(27.9% 0.041 260.031);
+    --dp-rule: oklch(27.9% 0.041 260.031);
+    --dp-accent: oklch(78.5% 0.115 274.713);
+    --dp-accent-soft: oklch(20.8% 0.042 265.755);
+    --dp-shadow: rgba(0, 0, 0, 0.45);
+  }
+}
+
+:root.dark {
+  --dp-bg: oklch(12.9% 0.042 264.695);
+  --dp-bg-soft: oklch(20.8% 0.042 265.755);
+  --dp-text: oklch(96.8% 0.007 247.896);
+  --dp-text-soft: oklch(70.4% 0.04 256.788);
+  --dp-border: oklch(27.9% 0.041 260.031);
+  --dp-rule: oklch(27.9% 0.041 260.031);
+  --dp-accent: oklch(78.5% 0.115 274.713);
+  --dp-accent-soft: oklch(20.8% 0.042 265.755);
+  --dp-shadow: rgba(0, 0, 0, 0.45);
+}
+
+body {
+  background-color: var(--dp-bg);
+  color: var(--dp-text);
+  font-family: var(--dp-font);
+  line-height: 1.7;
+}
+
+a {
+  color: var(--dp-accent);
+}
+
+/* --- Side menu ----------------------------------------------------------- */
+
+/*
+ * A utility applies to one element, not to a relation between elements: the
+ * rule linking a child to its parent can only come from here.
+ */
+.dp-nav .dp-nav {
+  margin: 0.1rem 0 0.35rem 0.35rem;
+  padding-left: 0.85rem;
+  border-left: 1px solid var(--dp-rule);
+}
+
+.dp-nav,
+.dp-toc-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* The bar of the current page sits on the parent's rule, in its place. */
+.dp-nav .dp-nav .dp-nav-link[aria-current='page'] {
+  position: relative;
+}
+.dp-nav .dp-nav .dp-nav-link[aria-current='page']::before {
+  content: '';
+  position: absolute;
+  left: calc(-0.85rem - 1px);
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background: var(--dp-accent);
+  border-radius: 2px;
+}
+
+/* --- Version switcher ---------------------------------------------------- */
+
+.dp-versions > summary::after {
+  content: '';
+  width: 0.4rem;
+  height: 0.4rem;
+  margin-top: -0.2rem;
+  border-right: 1.5px solid currentColor;
+  border-bottom: 1.5px solid currentColor;
+  transform: rotate(45deg);
+}
+.dp-versions[open] > summary::after {
+  transform: rotate(-135deg);
+  margin-top: 0.15rem;
+}
+
+/* --- Table of contents --------------------------------------------------- */
+
+.dp-toc-list .dp-toc-list {
+  border-left: 0;
+  padding-left: 0.8rem;
+}
+.dp-toc-item a {
+  display: block;
+  padding: 0.18rem 0 0.18rem 0.8rem;
+  margin-left: -1px;
+  border-left: 1px solid transparent;
+  color: var(--dp-text-soft);
+  text-decoration: none;
+  line-height: 1.45;
+}
+.dp-toc-item a:hover {
+  color: var(--dp-accent);
+  border-left-color: var(--dp-accent);
+}
+
+@media (max-width: 56rem) {
+  .dp-sidebar {
+    border-bottom: 1px solid var(--dp-border);
+  }
+}

package/types/base-provider.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Contract shared by every theme provider.
+ * @module @docpensieve/theme/base-provider
+ */
+export type ThemeOutput = {
+    /**
+     * CSS to concatenate into the final stylesheet.
+     */
+    css: string;
+    /**
+     * Exposed CSS variables (`--dp-*`).
+     */
+    variables: Record<string, string>;
+};
+export type CompileContext = {
+    /**
+     * Class names collected from the rendered
+     * pages. A utility provider, Tailwind first and foremost, only emits the
+     * matching rules; the others ignore them.
+     */
+    candidates?: string[];
+};
+/**
+ * @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 declare class BaseThemeProvider {
+    options: Record<string, any>;
+    /** Short provider identifier, unique within the engine. */
+    static id: string;
+    /** @param {Record<string, any>} [options] Options taken from `config.theme`. */
+    constructor(options?: Record<string, any>);
+    /**
+     * 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(): Record<string, string>;
+    /**
+     * Produces the provider's CSS contribution.
+     *
+     * @param {CompileContext} [_context]
+     * @returns {Promise<ThemeOutput>}
+     * @abstract
+     */
+    compile(_context?: CompileContext): Promise<ThemeOutput>;
+}

package/types/custom-provider.d.ts

@@ -0,0 +1,66 @@
+/**
+ * DocPensieve's custom theme, with no external dependency.
+ *
+ * @module @docpensieve/theme/custom-provider
+ */
+import { BaseThemeProvider } from './base-provider.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 declare const DEFAULT_TOKENS: Readonly<{
+    '--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 declare class CustomProvider extends BaseThemeProvider {
+    tokens: {
+        '--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";
+    };
+    extraCss: string;
+    static id: string;
+    /**
+     * @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?: {
+        tokens?: Record<string, string>;
+        css?: string;
+    });
+    /**
+     * @returns {Promise<import('./base-provider.js').ThemeOutput>}
+     * @throws {ThemeError} When a stylesheet of the package is missing.
+     */
+    compile(): Promise<import('./base-provider.js').ThemeOutput>;
+}

package/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @docpensieve/theme — composable theme providers.
+ * @module @docpensieve/theme
+ */
+export type ThemeOutput = import('./base-provider.js').ThemeOutput;
+export type CompileContext = import('./base-provider.js').CompileContext;
+/**
+ * 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/types/styles.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Reads the stylesheets shipped with the package.
+ *
+ * @module @docpensieve/theme/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 declare function readStyle(name: string): Promise<string>;
+/**
+ * Joins several CSS fragments into one stylesheet.
+ *
+ * @param {...(string | undefined | null)} parts
+ * @returns {string}
+ */
+export declare function joinCss(...parts: (string | undefined | null)[]): string;

package/types/tailwind-provider.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Theme built on Tailwind CSS.
+ *
+ * @module @docpensieve/theme/tailwind-provider
+ */
+import { BaseThemeProvider } from './base-provider.js';
+/** Tailwind theme: on-demand compilation of the classes actually used. */
+export declare class TailwindProvider extends BaseThemeProvider {
+    #private;
+    tokens: {
+        '--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";
+    };
+    extraCss: string;
+    source: string;
+    static id: string;
+    /**
+     * @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?: {
+        tokens?: Record<string, string>;
+        css?: string;
+        source?: string;
+    });
+    /** @returns {Record<string, string>} Slots dressed in utilities. */
+    get classes(): Record<string, string>;
+    /**
+     * @param {import('./base-provider.js').CompileContext} [context]
+     * @returns {Promise<import('./base-provider.js').ThemeOutput>}
+     * @throws {ThemeError} When Tailwind is missing or its compilation fails.
+     */
+    compile(context?: import('./base-provider.js').CompileContext): Promise<import('./base-provider.js').ThemeOutput>;
+}

package/types/theme-engine.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Registration and merging of theme providers.
+ *
+ * @module @docpensieve/theme/theme-engine
+ */
+import { BaseThemeProvider } from './base-provider.js';
+/** Combines several providers into a single CSS output. */
+export declare class ThemeEngine {
+    /** @type {Map<string, BaseThemeProvider>} */
+    providers: Map<string, BaseThemeProvider>;
+    constructor();
+    /**
+     * @param {string} id Provider identifier.
+     * @param {BaseThemeProvider} provider
+     * @returns {this} To chain registrations.
+     */
+    register(id: string, provider: BaseThemeProvider): this;
+    /**
+     * @param {string} id
+     * @returns {BaseThemeProvider | undefined}
+     */
+    get(id: string): BaseThemeProvider | undefined;
+    /**
+     * 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(): Record<string, string>;
+    /**
+     * 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.
+     */
+    compile(context?: import('./base-provider.js').CompileContext): Promise<import('./base-provider.js').ThemeOutput>;
+}