@chromamark/renderer 0.1.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@chromamark/renderer",
+  "version": "0.1.0",
+  "description": "ChromaMark renderer — a markdown-it plugin adding colored blocks, colored pills, collapsible sections, fields, meters and inline diff on top of CommonMark + GFM.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "cjfravel-dev",
+  "homepage": "https://github.com/cjfravel-dev/ChromaMark#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cjfravel-dev/ChromaMark.git",
+    "directory": "packages/renderer"
+  },
+  "bugs": {
+    "url": "https://github.com/cjfravel-dev/ChromaMark/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "browser": "./dist/chromamark.esm.js",
+  "unpkg": "./dist/chromamark.min.js",
+  "jsdelivr": "./dist/chromamark.min.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./browser": "./dist/chromamark.esm.js",
+    "./global": "./dist/chromamark.min.js",
+    "./theme.css": "./theme/chromamark.css"
+  },
+  "files": [
+    "src/",
+    "theme/",
+    "dist/"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "build": "node build.js",
+    "prepublishOnly": "node build.js"
+  },
+  "keywords": [
+    "chromamark",
+    "markdown",
+    "markdown-it",
+    "markdown-it-plugin",
+    "commonmark",
+    "gfm",
+    "admonition",
+    "callout"
+  ],
+  "dependencies": {
+    "markdown-it": "^14.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.2",
+    "jsdom": "^29.1.1"
+  }
+}

package/src/browser-core.js

@@ -0,0 +1,111 @@
+/**
+ * DOM-facing ChromaMark browser API, free of the esbuild-only CSS import so it
+ * can be unit-tested under Node/jsdom. The bundle entry (browser.js) supplies
+ * the theme via configureTheme() and adds the CDN auto-init.
+ */
+
+import { createRenderer, render as renderString } from './index.js';
+
+const STYLE_ID = 'chromamark-theme';
+const DONE_ATTR = 'data-chromamark-done';
+const DEFAULT_SELECTOR =
+  'script[type="text/chromamark"], template.chromamark, [data-chromamark], .chromamark';
+
+/** The theme stylesheet (populated by the bundle via configureTheme). */
+export let theme = '';
+
+/** Set the theme CSS used by injectTheme(). Called once by the bundle entry. */
+export function configureTheme(css) {
+  theme = css || '';
+}
+
+/** Render a ChromaMark string to an HTML fragment. */
+export function render(src, options) {
+  return renderString(src, options);
+}
+
+/** Inject the theme <style> once (idempotent). No-op outside a DOM. */
+export function injectTheme(doc) {
+  const d = doc || (typeof document !== 'undefined' ? document : null);
+  if (!d || d.getElementById(STYLE_ID)) return;
+  const style = d.createElement('style');
+  style.id = STYLE_ID;
+  style.textContent = theme;
+  (d.head || d.documentElement).appendChild(style);
+}
+
+/** Strip shared leading indentation so source can be indented inside HTML. */
+function dedent(text) {
+  const lines = text.replace(/\t/g, '  ').replace(/\r/g, '').split('\n');
+  while (lines.length && lines[0].trim() === '') lines.shift();
+  while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+  let min = Infinity;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    min = Math.min(min, line.match(/^ */)[0].length);
+  }
+  if (!Number.isFinite(min)) min = 0;
+  return lines.map((line) => line.slice(min)).join('\n');
+}
+
+function resolve(target) {
+  return typeof target === 'string' ? document.querySelector(target) : target;
+}
+
+/** Read a holder's raw ChromaMark source. <template> keeps its content in a
+ * detached fragment, so read that rather than the (empty) textContent. */
+function sourceOf(el, tag) {
+  if (tag === 'template' && el.content) return el.content.textContent || '';
+  return el.textContent || '';
+}
+
+/**
+ * Render one element in place. For a <script>/<template> holder the rendered
+ * output is inserted as a following sibling; for any other element its own
+ * contents are replaced. Returns the element containing the rendered HTML.
+ */
+export function renderElement(target, options) {
+  const el = resolve(target);
+  if (!el || el.hasAttribute(DONE_ATTR)) return null;
+
+  const tag = (el.tagName || '').toLowerCase();
+  const html = renderString(dedent(sourceOf(el, tag)), options);
+  el.setAttribute(DONE_ATTR, '');
+
+  if (tag === 'script' || tag === 'template') {
+    const out = document.createElement('div');
+    out.className = 'chromamark-output';
+    out.innerHTML = html;
+    el.parentNode.insertBefore(out, el.nextSibling);
+    return out;
+  }
+  el.innerHTML = html;
+  el.classList.add('chromamark-output');
+  return el;
+}
+
+/** Render every element matching the selector (defaults to the standard targets). */
+export function renderAll(selector, options) {
+  const nodes = document.querySelectorAll(selector || DEFAULT_SELECTOR);
+  return Array.from(nodes).map((el) => renderElement(el, options));
+}
+
+/** One-call setup: inject the theme, then render all targets on the page. */
+export function autoRender(options = {}) {
+  injectTheme();
+  return renderAll(options.selector, options);
+}
+
+export const ChromaMark = {
+  render,
+  renderElement,
+  renderAll,
+  injectTheme,
+  autoRender,
+  createRenderer,
+  get theme() {
+    return theme;
+  },
+};
+
+export default ChromaMark;

package/src/browser.js

@@ -0,0 +1,36 @@
+/**
+ * Browser bundle entry point for ChromaMark. Wraps the DOM API in browser-core
+ * with the esbuild-embedded theme and a CDN auto-init:
+ *
+ *   <script type="text/chromamark" id="report">::: success ... :::</script>
+ *   <script src=".../chromamark.min.js" data-chromamark-auto></script>
+ *
+ * Or drive it explicitly:
+ *   import ChromaMark from '.../chromamark.esm.js';
+ *   ChromaMark.autoRender();               // inject theme + render targets
+ *   ChromaMark.renderElement('#report');   // render one section
+ */
+
+import themeCss from '../theme/chromamark.css';
+import ChromaMark, { configureTheme, autoRender } from './browser-core.js';
+
+configureTheme(themeCss);
+
+export * from './browser-core.js';
+export default ChromaMark;
+
+/*
+ * CDN convenience: when loaded as a classic <script … data-chromamark-auto>,
+ * inject the theme and render all targets once the DOM is ready. ES module
+ * imports (currentScript === null) opt in explicitly via autoRender().
+ */
+(function autoInit() {
+  if (typeof document === 'undefined') return;
+  const script = document.currentScript;
+  if (!script || !script.hasAttribute('data-chromamark-auto')) return;
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => autoRender(), { once: true });
+  } else {
+    autoRender();
+  }
+})();

package/src/containers.js

@@ -0,0 +1,197 @@
+/**
+ * Block-level ChromaMark containers, fenced with three or more colons:
+ *   ::: <tone|block> [color=…] [title]   → colored callout
+ *   ::: details [open] [tone] <summary>  → collapsible section
+ *   ::: fields                            → key/value definition list
+ *
+ * Nesting uses more colons on the outer fence. The find-closing algorithm is
+ * adapted from markdown-it-container.
+ */
+
+import { resolveTone, parseSpec } from './tones.js';
+
+const MARKER = 0x3a; // :
+const MIN_FENCE = 3;
+
+const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+
+function parseOpener(info) {
+  if (!info) return null;
+  const tokens = info.split(/\s+/);
+  const kind = tokens.shift().toLowerCase();
+
+  let structure;
+  let tone = null;
+  let color = null;
+  let open = false;
+
+  if (kind === 'details') {
+    structure = 'details';
+  } else if (kind === 'fields') {
+    return { structure: 'fields' };
+  } else if (kind === 'block') {
+    structure = 'callout';
+  } else {
+    const t = resolveTone(kind);
+    if (!t) return null;
+    structure = 'callout';
+    tone = t;
+  }
+
+  while (tokens.length) {
+    const tk = tokens[0];
+    const low = tk.toLowerCase();
+    if (structure === 'details' && low === 'open') {
+      open = true;
+      tokens.shift();
+      continue;
+    }
+    if (low.startsWith('color=')) {
+      const spec = parseSpec(tk);
+      if (spec && spec.color) {
+        color = spec.color;
+        tokens.shift();
+        continue;
+      }
+      break;
+    }
+    if (structure === 'details' && tone === null && resolveTone(tk)) {
+      tone = resolveTone(tk);
+      tokens.shift();
+      continue;
+    }
+    break;
+  }
+
+  const rest = tokens.join(' ').trim();
+  if (structure === 'details') {
+    return { structure, tone, color, open, summary: rest || 'Details' };
+  }
+  return { structure, tone, color, title: rest || (tone ? cap(tone) : '') };
+}
+
+function fenceLength(src, pos, max) {
+  let count = 0;
+  let p = pos;
+  while (p < max && src.charCodeAt(p) === MARKER) {
+    count++;
+    p++;
+  }
+  return count;
+}
+
+function makeRule(enabled) {
+  return function chromaContainer(state, startLine, endLine, silent) {
+    const start = state.bMarks[startLine] + state.tShift[startLine];
+    const max = state.eMarks[startLine];
+    if (state.src.charCodeAt(start) !== MARKER) return false;
+
+    const openLen = fenceLength(state.src, start, max);
+    if (openLen < MIN_FENCE) return false;
+
+    const parsed = parseOpener(state.src.slice(start + openLen, max).trim());
+    if (!parsed || !enabled[parsed.structure]) return false;
+    if (silent) return true;
+
+    let nextLine = startLine;
+    let autoClosed = false;
+    for (;;) {
+      nextLine++;
+      if (nextLine >= endLine) break;
+      const lstart = state.bMarks[nextLine] + state.tShift[nextLine];
+      const lmax = state.eMarks[nextLine];
+      if (state.src.charCodeAt(lstart) !== MARKER) continue;
+      if (state.sCount[nextLine] - state.blkIndent >= 4) continue;
+      const closeLen = fenceLength(state.src, lstart, lmax);
+      if (closeLen < openLen) continue;
+      let p = lstart + closeLen;
+      while (p < lmax && (state.src.charCodeAt(p) === 0x20 || state.src.charCodeAt(p) === 0x09)) p++;
+      if (p < lmax) continue;
+      autoClosed = true;
+      break;
+    }
+
+    const oldParent = state.parentType;
+    const oldLineMax = state.lineMax;
+    state.parentType = 'chroma_container';
+    state.lineMax = nextLine;
+
+    if (parsed.structure === 'fields') {
+      const rows = [];
+      for (let ln = startLine + 1; ln < nextLine; ln++) {
+        const line = state.src.slice(state.bMarks[ln] + state.tShift[ln], state.eMarks[ln]);
+        if (!line.trim()) continue;
+        const ci = line.indexOf(':');
+        if (ci === -1) rows.push([line.trim(), '']);
+        else rows.push([line.slice(0, ci).trim(), line.slice(ci + 1).trim()]);
+      }
+      const token = state.push('cm_fields', '', 0);
+      token.meta = { rows };
+      token.map = [startLine, nextLine];
+    } else {
+      const openToken = state.push('cm_container_open', 'div', 1);
+      openToken.meta = parsed;
+      openToken.block = true;
+      openToken.map = [startLine, nextLine];
+
+      state.md.block.tokenize(state, startLine + 1, nextLine);
+
+      const closeToken = state.push('cm_container_close', 'div', -1);
+      closeToken.meta = parsed;
+      closeToken.block = true;
+    }
+
+    state.parentType = oldParent;
+    state.lineMax = oldLineMax;
+    state.line = nextLine + (autoClosed ? 1 : 0);
+    return true;
+  };
+}
+
+export default function containerPlugin(md, enabled) {
+  md.block.ruler.before('fence', 'cm_container', makeRule(enabled), {
+    alt: ['paragraph', 'reference', 'blockquote', 'list'],
+  });
+  const esc = md.utils.escapeHtml;
+
+  function decorate(meta) {
+    const custom = meta.color ? ' cm-custom' : '';
+    const style = meta.color ? ` style="--fg:${esc(meta.color)}"` : '';
+    const tone = !meta.color && meta.tone ? ` data-tone="${meta.tone}"` : '';
+    return { custom, style, tone };
+  }
+
+  md.renderer.rules.cm_container_open = (tokens, idx) => {
+    const meta = tokens[idx].meta;
+    const { custom, style, tone } = decorate(meta);
+    if (meta.structure === 'details') {
+      const open = meta.open ? ' open' : '';
+      return (
+        `<details class="cm-details${custom}"${tone}${style}${open}>` +
+        `<summary>${esc(meta.summary)}</summary><div class="cm-body">`
+      );
+    }
+    let html = `<div class="cm-block${custom}"${tone}${style}>`;
+    if (meta.title) html += `<div class="cm-title">${esc(meta.title)}</div>`;
+    return html + '<div class="cm-body">';
+  };
+
+  md.renderer.rules.cm_container_close = (tokens, idx) =>
+    tokens[idx].meta.structure === 'details' ? '</div></details>' : '</div></div>';
+
+  md.renderer.rules.cm_fields = (tokens, idx) => {
+    // Field values go through renderInline; force html:false so raw HTML is
+    // escaped regardless of the host markdown-it configuration (defense in depth).
+    const prevHtml = md.options.html;
+    md.options.html = false;
+    try {
+      let html = '<dl class="cm-fields">';
+      for (const [key, value] of tokens[idx].meta.rows) {
+        html += `<dt>${esc(key)}</dt><dd>${md.renderInline(value)}</dd>`;
+      }
+      return html + '</dl>';
+    } finally {
+      md.options.html = prevHtml;
+    }
+  };
+}

package/src/critic.js

@@ -0,0 +1,70 @@
+/**
+ * Inline diff via CriticMarkup (http://criticmarkup.com/):
+ *   {++insert++}  {--delete--}  {~~old~>new~~}  {==highlight==}  {>>comment<<}
+ * Content is treated as plain text and HTML-escaped on output.
+ */
+
+const OPEN = 0x7b; // {
+
+const KINDS = {
+  '++': { kind: 'add', close: '++}' },
+  '--': { kind: 'del', close: '--}' },
+  '~~': { kind: 'sub', close: '~~}' },
+  '==': { kind: 'mark', close: '==}' },
+  '>>': { kind: 'comment', close: '<<}' },
+};
+
+function criticRule(state, silent) {
+  const start = state.pos;
+  const src = state.src;
+  if (src.charCodeAt(start) !== OPEN) return false;
+
+  const spec = KINDS[src.slice(start + 1, start + 3)];
+  if (!spec) return false;
+
+  const contentStart = start + 3;
+  const closeIdx = src.indexOf(spec.close, contentStart);
+  if (closeIdx === -1 || closeIdx + spec.close.length > state.posMax) return false;
+
+  const raw = src.slice(contentStart, closeIdx);
+
+  if (!silent) {
+    const token = state.push('cm_critic', '', 0);
+    if (spec.kind === 'sub') {
+      const cut = raw.indexOf('~>');
+      token.meta = {
+        kind: 'sub',
+        old: cut === -1 ? raw : raw.slice(0, cut),
+        neu: cut === -1 ? '' : raw.slice(cut + 2),
+      };
+    } else {
+      token.meta = { kind: spec.kind, content: raw };
+    }
+  }
+
+  state.pos = closeIdx + spec.close.length;
+  return true;
+}
+
+export default function criticPlugin(md) {
+  md.inline.ruler.before('emphasis', 'cm_critic', criticRule);
+  const esc = md.utils.escapeHtml;
+
+  md.renderer.rules.cm_critic = (tokens, idx) => {
+    const meta = tokens[idx].meta;
+    switch (meta.kind) {
+      case 'add':
+        return `<ins class="crit-add">${esc(meta.content)}</ins>`;
+      case 'del':
+        return `<del class="crit-del">${esc(meta.content)}</del>`;
+      case 'sub':
+        return `<del class="crit-del">${esc(meta.old)}</del><ins class="crit-add">${esc(meta.neu)}</ins>`;
+      case 'mark':
+        return `<mark class="crit-mark">${esc(meta.content)}</mark>`;
+      case 'comment':
+        return `<span class="crit-comment">${esc(meta.content)}</span>`;
+      default:
+        return '';
+    }
+  };
+}

package/src/index.js

@@ -0,0 +1,51 @@
+/**
+ * ChromaMark renderer — a markdown-it plugin adding colored blocks, colored
+ * pills, collapsible sections, fields, meters, and inline diff on top of
+ * CommonMark + GFM.
+ */
+
+import MarkdownIt from 'markdown-it';
+import inlinePlugin from './inline.js';
+import criticPlugin from './critic.js';
+import containerPlugin from './containers.js';
+
+const DEFAULTS = {
+  container: true, // ::: colored callouts
+  details: true, // ::: details collapsibles
+  fields: true, // ::: fields key/value lists
+  pill: true, // [!…] badges
+  text: true, // [.…] colored text
+  meter: true, // [=…] progress meters
+  critic: true, // CriticMarkup inline diff
+};
+
+/** markdown-it plugin entry point: `md.use(chromamark, options)`. */
+export default function chromamark(md, options = {}) {
+  const opts = { ...DEFAULTS, ...options };
+
+  if (opts.pill || opts.text || opts.meter) {
+    inlinePlugin(md, { pill: opts.pill, text: opts.text, meter: opts.meter });
+  }
+  if (opts.critic) {
+    criticPlugin(md);
+  }
+  if (opts.container || opts.details || opts.fields) {
+    containerPlugin(md, {
+      callout: opts.container,
+      details: opts.details,
+      fields: opts.fields,
+    });
+  }
+}
+
+/** Build a markdown-it instance preconfigured with ChromaMark (CommonMark + GFM). */
+export function createRenderer(options = {}) {
+  const md = new MarkdownIt({ html: false, linkify: true, typographer: false });
+  md.use(chromamark, options);
+  return md;
+}
+
+/** Convenience: render a ChromaMark string to an HTML fragment. */
+export function render(src, options = {}) {
+  return createRenderer(options).render(String(src ?? ''));
+}

package/src/inline.js

@@ -0,0 +1,134 @@
+/**
+ * Inline ChromaMark constructs sharing the `[<sigil>…]` family:
+ *   [!spec label]  → pill / badge (filled)
+ *   [.spec label]  → colored text (tint, no fill)
+ *   [=spec value]  → progress meter (bar)
+ *
+ * The leading `spec` is a tone/alias, `color=<hex|name>`, or a bare `#hex`.
+ * An unrecognized spec makes the rule decline so the text stays literal.
+ */
+
+import { parseSpec } from './tones.js';
+
+const OPEN = 0x5b; // [
+const SIGILS = { '!': 'pill', '.': 'text', '=': 'meter' };
+
+function unescape(text) {
+  return text.replace(/\\([\s\S])/g, '$1');
+}
+
+function splitSpec(inner) {
+  const match = inner.match(/^(\S+)(?:\s+([\s\S]*))?$/);
+  if (!match) return null;
+  return { specToken: match[1], rest: (match[2] || '').trim() };
+}
+
+/** Compute a meter fill width (0–100, as a string) from a value like "87%" or "3/10". */
+function meterWidth(value) {
+  let pct;
+  const percent = value.match(/^(\d+(?:\.\d+)?)\s*%$/);
+  const fraction = value.match(/^(\d+(?:\.\d+)?)\s*\/\s*(\d+(?:\.\d+)?)$/);
+  if (percent) {
+    pct = parseFloat(percent[1]);
+  } else if (fraction) {
+    const denom = parseFloat(fraction[2]);
+    if (denom === 0) return null;
+    pct = (parseFloat(fraction[1]) / denom) * 100;
+  } else {
+    return null;
+  }
+  pct = Math.max(0, Math.min(100, pct));
+  return String(+pct.toFixed(2));
+}
+
+function findClose(state, from) {
+  const src = state.src;
+  for (let i = from; i < state.posMax; i++) {
+    const c = src.charCodeAt(i);
+    if (c === 0x5c) { i++; continue; } // backslash escapes next char
+    if (c === 0x0a) return -1; // stay on one line
+    if (c === 0x5d) return i; // ]
+  }
+  return -1;
+}
+
+function makeRule(enabled) {
+  return function chromaInline(state, silent) {
+    const start = state.pos;
+    if (state.src.charCodeAt(start) !== OPEN) return false;
+
+    const kind = SIGILS[state.src[start + 1]];
+    if (!kind || !enabled[kind]) return false;
+
+    const end = findClose(state, start + 2);
+    if (end === -1) return false;
+
+    const inner = state.src.slice(start + 2, end).trim();
+    const parts = inner && splitSpec(inner);
+    if (!parts) return false;
+
+    const spec = parseSpec(parts.specToken);
+    if (!spec) return false;
+
+    const rest = unescape(parts.rest);
+
+    let token;
+    if (kind === 'meter') {
+      if (!rest) return false;
+      const width = meterWidth(rest);
+      if (width === null) return false;
+      if (!silent) {
+        token = state.push('cm_meter', '', 0);
+        token.meta = { ...spec, value: rest, width };
+      }
+    } else if (kind === 'text') {
+      if (!rest) return false;
+      if (!silent) {
+        token = state.push('cm_text', '', 0);
+        token.meta = { ...spec, label: rest };
+      }
+    } else {
+      const label = rest || (spec.tone ? parts.specToken.toUpperCase() : spec.color);
+      if (!silent) {
+        token = state.push('cm_pill', '', 0);
+        token.meta = { ...spec, label };
+      }
+    }
+
+    state.pos = end + 1;
+    return true;
+  };
+}
+
+function toneAttrs(meta, escapeHtml) {
+  const custom = meta.color ? ' cm-custom' : '';
+  const tone = meta.tone ? ` data-tone="${meta.tone}"` : '';
+  const style = meta.color ? ` style="--fg:${escapeHtml(meta.color)}"` : '';
+  return { custom, tone, style };
+}
+
+export default function inlinePlugin(md, enabled) {
+  md.inline.ruler.before('link', 'cm_inline', makeRule(enabled));
+  const esc = md.utils.escapeHtml;
+
+  md.renderer.rules.cm_pill = (tokens, idx) => {
+    const { custom, tone, style } = toneAttrs(tokens[idx].meta, esc);
+    return `<span class="cm-pill${custom}"${tone}${style}>${esc(tokens[idx].meta.label)}</span>`;
+  };
+
+  md.renderer.rules.cm_text = (tokens, idx) => {
+    const { custom, tone, style } = toneAttrs(tokens[idx].meta, esc);
+    return `<span class="cm-text${custom}"${tone}${style}>${esc(tokens[idx].meta.label)}</span>`;
+  };
+
+  md.renderer.rules.cm_meter = (tokens, idx) => {
+    const meta = tokens[idx].meta;
+    const { custom, tone, style } = toneAttrs(meta, esc);
+    return (
+      `<span class="cm-meter${custom}"${tone}${style}>` +
+      `<span class="cm-track"><span class="cm-fill" style="width:${meta.width}%"></span></span>` +
+      `<span class="cm-val">${esc(meta.value)}</span>` +
+      `</span>`
+    );
+  };
+}