@dr-ishaan/rehype-perfect-code-blocks 1.3.3 → 2.1.0

package/src/tokens.ts

@@ -0,0 +1,223 @@
+/**
+ * Design-token bridge — derives 20+ --pcb-* variables from 5 core values.
+ *
+ * v2.0.0 feature. Uses `color-mix(in oklch, ...)` for automatic color
+ * derivation, which is supported in all modern browsers (Chrome 111+,
+ * Safari 16.4+, Firefox 113+). For older browsers, the fallback values
+ * from the Shiki theme (Pattern 2, v1.3.0) still apply on the <pre> element.
+ */
+
+export interface DesignTokens {
+  bg?: string;
+  fg?: string;
+  border?: string;
+  radius?: string;
+  monoFont?: string;
+}
+
+/**
+ * Generate a CSS style string containing all derived --pcb-* variables
+ * from the 5 core token values. Returns an empty string if no tokens
+ * are provided.
+ *
+ * The generated CSS is applied to `:where(.pcb)` so it has zero
+ * specificity — user CSS always wins.
+ */
+export function generateTokenStyles(tokens: DesignTokens, scope?: string): string {
+  if (!tokens || Object.keys(tokens).length === 0) return '';
+
+  const { bg, fg, border, radius, monoFont } = tokens;
+  if (!bg && !fg && !border && !radius && !monoFont) return '';
+
+  const scopePrefix = scope ? `${scope} ` : '';
+  const lines: string[] = [];
+
+  // Direct mappings (1:1)
+  if (bg) lines.push(`  --pcb-bg: ${bg};`);
+  if (fg) lines.push(`  --pcb-fg: ${fg};`);
+  if (border) lines.push(`  --pcb-border: ${border};`);
+  if (radius) lines.push(`  --pcb-radius: ${radius};`);
+  if (monoFont) lines.push(`  --pcb-font-mono: ${monoFont};`);
+
+  // Derived mappings (auto-computed from core values via color-mix)
+  // Only derive if BOTH bg and fg are available (needed for color-mix)
+  if (bg && fg) {
+    // Line numbers: muted (50% mix of fg over bg)
+    lines.push(`  --pcb-text-muted: color-mix(in oklch, ${fg}, ${bg} 50%);`);
+    lines.push(`  --pcb-ln-fg: color-mix(in oklch, ${fg}, ${bg} 50%);`);
+
+    // Header bar background: slightly different from body (5% fg over bg)
+    lines.push(`  --pcb-bg-header: color-mix(in oklch, ${fg} 5%, ${bg});`);
+
+    // Header text: muted (30% fg mixed toward bg)
+    lines.push(`  --pcb-text-bar: color-mix(in oklch, ${fg}, ${bg} 30%);`);
+
+    // Line highlight: subtle tint (12% fg over bg)
+    lines.push(`  --pcb-line-highlight: color-mix(in oklch, ${fg} 12%, ${bg});`);
+
+    // Diff add: green tint (18% green over bg)
+    lines.push(`  --pcb-line-add: color-mix(in oklch, #2ea043 18%, ${bg});`);
+
+    // Diff del: red tint (18% red over bg)
+    lines.push(`  --pcb-line-del: color-mix(in oklch, #f85149 18%, ${bg});`);
+
+    // Focus: blue tint (18% blue over bg)
+    lines.push(`  --pcb-line-focus: color-mix(in oklch, #58a6ff 18%, ${bg});`);
+
+    // Copy button hover background: subtle (8% fg over bg)
+    lines.push(`  --pcb-copy-hover-bg: color-mix(in oklch, ${fg} 8%, ${bg});`);
+
+    // Gutter background: same as bg by default
+    lines.push(`  --pcb-bg-gutter: ${bg};`);
+
+    // Caption background: slightly different (like header)
+    lines.push(`  --pcb-caption-bg: color-mix(in oklch, ${fg} 5%, ${bg});`);
+
+    // Caption color: muted (like header text)
+    lines.push(`  --pcb-caption-color: color-mix(in oklch, ${fg}, ${bg} 30%);`);
+
+    // Word highlight: gold tint (30% gold over bg)
+    lines.push(`  --pcb-word-bg: color-mix(in oklch, #bb8009 30%, ${bg});`);
+
+    // Word highlight (id): blue tint (30% blue over bg)
+    lines.push(`  --pcb-word-bg-id: color-mix(in oklch, #58a6ff 30%, ${bg});`);
+  }
+
+  if (lines.length === 0) return '';
+
+  return `:where(${scopePrefix}.pcb) {\n${lines.join('\n')}\n}`;
+}
+
+/**
+ * Generate the dark-mode CSS selector based on the user's dark mode strategy.
+ *
+ * Returns the selector prefix that should be placed before `.pcb` in CSS rules.
+ * For 'media' strategy, returns empty string (the rules are wrapped in @media).
+ */
+export function generateDarkModeSelector(
+  darkMode?: {
+    strategy?: 'media' | 'attribute' | 'class' | 'custom';
+    attribute?: string;
+    attributeValue?: string;
+    class?: string;
+    customSelector?: string;
+  },
+  scope?: string
+): { selector: string; mediaQuery: string | null } {
+  const scopePrefix = scope ? `${scope} ` : '';
+
+  if (!darkMode || darkMode.strategy === 'media' || !darkMode.strategy) {
+    // Default: prefers-color-scheme media query
+    return { selector: '', mediaQuery: 'prefers-color-scheme: dark' };
+  }
+
+  if (darkMode.strategy === 'attribute') {
+    const attr = darkMode.attribute ?? 'data-theme';
+    const val = darkMode.attributeValue ?? 'dark';
+    return {
+      selector: `html[${attr}="${val}"] ${scopePrefix}`.trim(),
+      mediaQuery: null,
+    };
+  }
+
+  if (darkMode.strategy === 'class') {
+    const cls = darkMode.class ?? 'dark';
+    return {
+      selector: `html.${cls} ${scopePrefix}`.trim(),
+      mediaQuery: null,
+    };
+  }
+
+  if (darkMode.strategy === 'custom') {
+    const sel = darkMode.customSelector ?? ':root';
+    return {
+      selector: `${sel} ${scopePrefix}`.trim(),
+      mediaQuery: null,
+    };
+  }
+
+  return { selector: '', mediaQuery: 'prefers-color-scheme: dark' };
+}
+
+/**
+ * Generate the light-mode CSS selector (the inverse of dark mode).
+ * When dark mode is NOT active, light mode defaults apply.
+ */
+export function generateLightModeSelector(
+  darkMode?: {
+    strategy?: 'media' | 'attribute' | 'class' | 'custom';
+    attribute?: string;
+    attributeValue?: string;
+    class?: string;
+    customSelector?: string;
+  },
+  scope?: string
+): { selector: string; mediaQuery: string | null } {
+  const scopePrefix = scope ? `${scope} ` : '';
+
+  if (!darkMode || darkMode.strategy === 'media' || !darkMode.strategy) {
+    return { selector: '', mediaQuery: 'prefers-color-scheme: light' };
+  }
+
+  if (darkMode.strategy === 'attribute') {
+    const attr = darkMode.attribute ?? 'data-theme';
+    const val = darkMode.attributeValue ?? 'dark';
+    // Light = when the attribute is NOT the dark value
+    return {
+      selector: `html:not([${attr}="${val}"]) ${scopePrefix}`.trim(),
+      mediaQuery: null,
+    };
+  }
+
+  if (darkMode.strategy === 'class') {
+    const cls = darkMode.class ?? 'dark';
+    return {
+      selector: `html:not(.${cls}) ${scopePrefix}`.trim(),
+      mediaQuery: null,
+    };
+  }
+
+  if (darkMode.strategy === 'custom') {
+    // For custom, light = when the custom selector does NOT match
+    // This is tricky — we can't easily negate an arbitrary selector.
+    // Fall back to media query for the light case.
+    return { selector: '', mediaQuery: 'prefers-color-scheme: light' };
+  }
+
+  return { selector: '', mediaQuery: 'prefers-color-scheme: light' };
+}
+
+/**
+ * Apply a scope prefix to all CSS selectors in a stylesheet.
+ * This is a simple regex-based approach that handles the plugin's CSS
+ * structure. It prefixes every selector that starts with `.pcb` or
+ * `:where(.pcb` or `html` with the scope.
+ */
+export function applyScopeToCss(css: string, scope: string): string {
+  if (!scope) return css;
+
+  // Don't double-prefix if the scope is already present
+  if (css.includes(`${scope} .pcb`) || css.includes(`${scope}.pcb`)) return css;
+
+  // Prefix selectors that target .pcb or html.no-js
+  let result = css;
+
+  // :where(.pcb) → :where(scope .pcb)
+  result = result.replace(/:where\(\.pcb\)/g, `:where(${scope} .pcb)`);
+
+  // :where(html:not(...)) :where(.pcb:not(...)) → :where(scope html:not(...)) :where(scope .pcb:not(...))
+  // This is complex — for nested :where() with html, just prefix the whole compound
+  result = result.replace(/:where\(html/g, `:where(${scope} html`);
+
+  // .pcb pre → scope .pcb pre (the framework-reset overrides)
+  result = result.replace(/^(\.pcb\s)/gm, `${scope} $1`);
+
+  // .pcb__copy → scope .pcb__copy (note: .pcb__ starts with a dot, don't add another)
+  result = result.replace(/^(\.pcb__)/gm, `${scope} $1`);
+
+  // html.no-js .pcb__copy → scope html.no-js scope .pcb__copy
+  // (This is an edge case — the no-js rule needs both html and .pcb scoped)
+  result = result.replace(/html\.no-js\s+\.pcb/g, `${scope} html.no-js ${scope} .pcb`);
+
+  return result;
+}

package/src/transformer.ts

@@ -242,6 +242,13 @@ export function rehypePerfectCodeBlocks(userOptions: PerfectCodeOptions = {}) {
     preset: 'default',
     injectStyles: true,
     theme: 'auto',
+    cssInjection: 'inline' as const,
+    cssLayer: 'pcb',
+    tokens: undefined as unknown as NonNullable<PerfectCodeOptions['tokens']>,
+    darkMode: undefined as unknown as NonNullable<PerfectCodeOptions['darkMode']>,
+    scope: undefined as unknown as string,
+    math: undefined as unknown as NonNullable<PerfectCodeOptions['math']>,
+    devWarnings: process.env.NODE_ENV !== 'production',
     inline: false,
     ...rest,
   };

package/src/types.ts

@@ -122,6 +122,21 @@ export interface PerfectCodeOptions {
     transformerOrder?: 'before' | 'after';
     /** Override the highlighter factory (e.g. for custom TextMate grammars). */
     getHighlighter?: (opts: { themes: string[]; langs: string[] }) => Promise<unknown>;
+    /**
+     * v2.1.0: Lazy initialization — don't load Shiki until the first code block
+     * is encountered. On pages with no code blocks, Shiki (and its WASM engine)
+     * is never loaded, saving ~1MB of bundle.
+     *
+     * Default: false (Shiki initializes eagerly, same as v1.x/v2.0)
+     */
+    lazy?: boolean;
+    /**
+     * v2.1.0: Languages to preload when lazy is true. Only loaded if the
+     * document contains at least one code block.
+     *
+     * Default: ['typescript', 'bash', 'javascript', 'json', 'html', 'css']
+     */
+    preloadLangs?: string[];
     [key: string]: unknown;
   };
   /**
@@ -334,6 +349,207 @@ export interface PerfectCodeOptions {
   /** Manual theme override. Default: 'auto' (prefers-color-scheme) */
   theme?: 'auto' | 'dark' | 'light';
 
+  /* ---------- v2.0.0: CSS Architecture ---------- */
+
+  /**
+   * CSS injection strategy. Controls how the plugin's stylesheet is delivered.
+   *
+   * - `'inline'` (default) — injects the full CSS in a `<style>` tag on every page.
+   *   Simple, works everywhere, but the CSS is unlayered (can be overridden by
+   *   framework resets on cascade ties).
+   *
+   * - `'layer'` — injects the CSS wrapped in `@layer <cssLayer> { ... }`.
+   *   On sites using cascade layers (Tailwind v3+, daisyUI, etc.), this ensures
+   *   the plugin's CSS sits in the correct layer and framework resets don't
+   *   win on specificity ties. Requires `cssLayer` to be set.
+   *
+   * - `'import'` — does NOT inject CSS. The user imports it manually:
+   *   `import '@dr-ishaan/rehype-perfect-code-blocks/styles.css'`
+   *   Useful for sites that want full control over CSS loading (e.g., bundling
+   *   with PostCSS, or importing into a specific `@layer` in their own CSS).
+   *
+   * Default: `'inline'` (backward-compatible with v1.x).
+   */
+  cssInjection?: 'inline' | 'layer' | 'import';
+
+  /**
+   * The cascade layer name to use when `cssInjection: 'layer'`.
+   * The plugin's CSS will be wrapped in `@layer <cssLayer> { ... }`.
+   *
+   * Example: `cssLayer: 'components'` → all plugin CSS goes into
+   * `@layer components { ... }`, which the user can order above
+   * `@layer base` (framework resets) in their CSS:
+   *
+   * ```css
+   * @layer base, components, utilities;
+   * ```
+   *
+   * Default: `'pcb'`
+   */
+  cssLayer?: string;
+
+  /**
+   * Design-token bridge — provide 5 core values and the plugin auto-derives
+   * all 20+ `--pcb-*` variables. This is a shortcut for mapping the plugin
+   * to an external design system (Tailwind theme, daisyUI theme, CSS custom
+   * properties, etc.) without manually overriding every variable.
+   *
+   * Each value can be a CSS value string (e.g., `'#1a1b26'`) or a
+   * `var(--your-var)` reference.
+   *
+   * When set, the plugin generates a `<style>` block with the derived
+   * `--pcb-*` variables applied to `:where(.pcb)` (zero specificity, so
+   * user CSS still wins). If a specific `--pcb-*` variable is ALSO set
+   * in user CSS, the user's value wins (the token bridge is a default,
+   * not an override).
+   *
+   * Example:
+   * ```js
+   * perfectCode({
+   *   tokens: {
+   *     bg: 'var(--bg-subtle)',
+   *     fg: 'var(--ink)',
+   *     border: 'var(--rule)',
+   *     radius: 'var(--radius-card)',
+   *     monoFont: 'var(--font-mono)',
+   *   },
+   * })
+   * ```
+   *
+   * The plugin auto-derives:
+   * - `--pcb-bg` = `bg`
+   * - `--pcb-fg` = `fg`
+   * - `--pcb-border` = `border`
+   * - `--pcb-radius` = `radius`
+   * - `--pcb-font-mono` = `monoFont`
+   * - `--pcb-ln-fg` = `color-mix(in oklch, fg, bg 50%)` (muted line numbers)
+   * - `--pcb-bg-header` = `color-mix(in oklch, fg 5%, bg)` (header slightly different)
+   * - `--pcb-text-bar` = `color-mix(in oklch, fg, bg 30%)` (header text muted)
+   * - `--pcb-line-highlight` = `color-mix(in oklch, fg 12%, bg)` (subtle highlight)
+   * - `--pcb-line-add` = `color-mix(in oklch, #2ea043 18%, bg)` (diff add)
+   * - `--pcb-line-del` = `color-mix(in oklch, #f85149 18%, bg)` (diff del)
+   * - `--pcb-line-focus` = `color-mix(in oklch, #58a6ff 18%, bg)` (focus)
+   * - `--pcb-copy-bg` (hover) = `color-mix(in oklch, fg 8%, bg)`
+   *
+   * Uses `color-mix(in oklch, ...)` which is supported in all modern browsers
+   * (Chrome 111+, Safari 16.4+, Firefox 113+). For older browsers, the
+   * fallback values from the Shiki theme (Pattern 2, v1.3.0) still apply.
+   *
+   * Default: `undefined` (no token bridge; use the plugin's built-in defaults)
+   */
+  tokens?: {
+    /** Background color of the code block surface. */
+    bg?: string;
+    /** Foreground (text) color of the code. */
+    fg?: string;
+    /** Border color of the code block frame. */
+    border?: string;
+    /** Border radius of the code block. */
+    radius?: string;
+    /** Monospace font family for code text. */
+    monoFont?: string;
+  };
+
+  /**
+   * Dark mode strategy — controls how the plugin switches between light
+   * and dark themes.
+   *
+   * - `'media'` (default) — uses `@media (prefers-color-scheme: dark)`.
+   *   Automatic, no configuration needed. Same as v1.x behavior.
+   *
+   * - `'attribute'` — switches based on an attribute on `<html>`.
+   *   Requires `darkMode.attribute` and `darkMode.attributeValue`.
+   *   Example: `darkMode: { strategy: 'attribute', attribute: 'data-theme', attributeValue: 'dark' }`
+   *   → CSS: `html[data-theme="dark"] .pcb { ... }`
+   *
+   * - `'class'` — switches based on a class on `<html>`.
+   *   Requires `darkMode.class`.
+   *   Example: `darkMode: { strategy: 'class', class: 'dark' }`
+   *   → CSS: `html.dark .pcb { ... }`
+   *
+   * - `'custom'` — uses a custom CSS selector.
+   *   Requires `darkMode.customSelector`.
+   *   Example: `darkMode: { strategy: 'custom', customSelector: ':root[data-mode="night"]' }`
+   *   → CSS: `:root[data-mode="night"] .pcb { ... }`
+   *
+   * When using Shiki dual themes (`shiki.theme: { light, dark }`), the
+   * Shiki token CSS variables (`--shiki-light` / `--shiki-dark`) are also
+   * switched using the same strategy, not just `prefers-color-scheme`.
+   *
+   * Default: `'media'` (backward-compatible with v1.x)
+   */
+  darkMode?: {
+    strategy: 'media' | 'attribute' | 'class' | 'custom';
+    /** For `strategy: 'attribute'` — the attribute name on `<html>`. Default: `'data-theme'` */
+    attribute?: string;
+    /** For `strategy: 'attribute'` — the attribute value that triggers dark mode. Default: `'dark'` */
+    attributeValue?: string;
+    /** For `strategy: 'class'` — the class name on `<html>` that triggers dark mode. Default: `'dark'` */
+    class?: string;
+    /** For `strategy: 'custom'` — the full CSS selector that triggers dark mode. */
+    customSelector?: string;
+  };
+
+  /**
+   * CSS containment scope — prefix all generated CSS selectors with this
+   * string. Useful when code blocks appear in specific contexts (e.g., only
+   * inside `.prose` or `article`) and you don't want the plugin's CSS to
+   * affect code blocks elsewhere on the page.
+   *
+   * Example: `scope: '.prose'` → all selectors become `.prose .pcb { ... }`,
+   * `.prose .pcb__header { ... }`, etc.
+   *
+   * The scope is applied to ALL generated CSS, including the framework-reset
+   * overrides and the dark-mode selectors.
+   *
+   * Default: `undefined` (no scoping; CSS applies everywhere)
+   */
+  scope?: string;
+
+  /* ---------- v2.1.0: Math/LaTeX rendering ---------- */
+
+  /**
+   * Math/LaTeX rendering via KaTeX. When enabled, the plugin intercepts:
+   *   - Inline math: `$...$` in text (when `math.inline` is true)
+   *   - Block math: `$$...$$` blocks (when `math.block` is true)
+   *   - Fenced code blocks with language `math`, `latex`, or `tex`
+   *
+   * KaTeX renders at build time (server-side) — no client-side JS needed.
+   * The KaTeX CSS + fonts must be loaded on the client (the plugin injects
+   * a `<link>` to KaTeX CSS if `math.injectCss` is true).
+   *
+   * `katex` must be installed: `npm install katex`
+   *
+   * Default: `undefined` (no math rendering; `$...$` renders as literal text)
+   */
+  math?: {
+    /** Math engine. 'katex' renders via KaTeX (must be installed). Default: 'none' */
+    engine?: 'katex' | 'none';
+    /** Render inline `$...$` math. Default: true */
+    inline?: boolean;
+    /** Render block `$$...$$` and ```math blocks. Default: true */
+    block?: boolean;
+    /** Inject KaTeX CSS alongside plugin CSS. Default: true */
+    injectCss?: boolean;
+    /** Don't crash on invalid LaTeX — render the source as-is. Default: true */
+    throwOnError?: boolean;
+    /** Allow non-standard LaTeX commands. Default: false */
+    strict?: boolean | 'ignore' | 'error' | 'warn';
+  };
+
+  /* ---------- v2.1.0: Development warnings ---------- */
+
+  /**
+   * Emit warnings to the logger during build/dev for common misconfigurations:
+   *   - Unknown language not loaded in Shiki
+   *   - Invalid meta syntax (e.g., `{1,a-5}` instead of `{1,3-5}`)
+   *   - Conflicting options (e.g., `wrap` + `collapseAfter` both enabled)
+   *   - Code block inside raw HTML detected but rehype-raw not installed
+   *
+   * Default: true in development (when `NODE_ENV !== 'production'`), false in production.
+   */
+  devWarnings?: boolean;
+
   /* ---------- Inline code (legacy cosmetic option) ---------- */
   /** Also style inline `code` cosmetically (no tokenization). Default: false */
   inline?: boolean;