@ozsarman/clarityjs 0.6.0

package/src/scoped-css.js

@@ -0,0 +1,641 @@
+/**
+ * Clarity.js — Scoped CSS Processor
+ *
+ * Extracts <style scoped> blocks from .clarity source files and transforms
+ * them into component-scoped CSS using a unique data attribute.
+ *
+ * How it works:
+ *   1. Extract the <style scoped> block from source
+ *   2. Generate a stable hash (e.g. "data-c-3f8a1b") from the file path
+ *   3. Rewrite every CSS selector to include the scoped attribute:
+ *        .card { ... }  →  .card[data-c-3f8a1b] { ... }
+ *   4. Inject the data attribute into the root element of the compiled component
+ *
+ * The Vite plugin (vite-plugin.js) calls this during transform.
+ * The CodeGenerator receives the scopeId and injects data-c-{id} automatically.
+ *
+ * Non-scoped <style> blocks are returned as-is (global CSS).
+ *
+ * Usage (from Vite plugin / build tool):
+ *
+ *   import { extractStyles, scopeCSS, hashId } from '@ozsarman/clarityjs/scoped-css';
+ *
+ *   const { scoped, global, scopeId } = extractStyles(source, filename);
+ *   const transformedCSS = scopeCSS(scoped, scopeId);
+ *   // Inject scopeId into codegen options so root element gets data-c-{scopeId}
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+// ─── hashId ──────────────────────────────────────────────────────────────────
+
+/**
+ * Generate a short, stable 6-char hex hash from a string (e.g. file path).
+ * Uses a simple djb2-style hash — collision probability is negligible for
+ * the number of components in a typical application.
+ *
+ * @param {string} str
+ * @returns {string}  6-character hex string  e.g. "3f8a1b"
+ */
+export function hashId(str) {
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) {
+    h = ((h << 5) + h) ^ str.charCodeAt(i);
+    h = h >>> 0; // keep unsigned 32-bit
+  }
+  return (h >>> 0).toString(16).padStart(8, '0').slice(0, 6);
+}
+
+// ─── extractStyles ────────────────────────────────────────────────────────────
+
+/**
+ * Extract <style> and <style scoped> blocks from Clarity source.
+ *
+ * @param {string} source    - Full .clarity file source
+ * @param {string} filename  - File path (used to generate the scope id)
+ * @returns {{
+ *   scoped:   string,   // CSS from <style scoped> (or '')
+ *   global:   string,   // CSS from <style> (or '')
+ *   scopeId:  string,   // e.g. "3f8a1b"
+ *   source:   string,   // source with style blocks stripped
+ * }}
+ */
+export function extractStyles(source, filename = '<anonymous>') {
+  const scopeId = hashId(filename);
+
+  let scoped  = '';
+  let global  = '';
+  let module_ = ''; // <style module> content
+
+  // Match <style scoped> ... </style>
+  const scopedRE  = /<style\s+scoped\s*>([\s\S]*?)<\/style>/gi;
+  // Match <style module> ... </style>
+  const moduleRE  = /<style\s+module\s*>([\s\S]*?)<\/style>/gi;
+  // Match <style> ... </style>  (without scoped/module)
+  const globalRE  = /<style(?!\s+(?:scoped|module))\s*>([\s\S]*?)<\/style>/gi;
+
+  let stripped = source;
+  let m;
+
+  while ((m = scopedRE.exec(source))  !== null) scoped  += m[1];
+  while ((m = moduleRE.exec(source))  !== null) module_ += m[1];
+  while ((m = globalRE.exec(source))  !== null) global  += m[1];
+
+  // Strip all kinds of <style> from source before compilation
+  stripped = stripped
+    .replace(/<style\s+scoped\s*>[\s\S]*?<\/style>/gi, '')
+    .replace(/<style\s+module\s*>[\s\S]*?<\/style>/gi, '')
+    .replace(/<style\s*>[\s\S]*?<\/style>/gi, '');
+
+  return { scoped, global, module: module_, scopeId, source: stripped.trim() };
+}
+
+// ─── scopeCSS ────────────────────────────────────────────────────────────────
+
+/**
+ * Transform CSS by adding a scoped data-attribute to every selector.
+ *
+ * Examples:
+ *   .card { ... }              → .card[data-c-3f8a1b] { ... }
+ *   h1, p { ... }             → h1[data-c-3f8a1b], p[data-c-3f8a1b] { ... }
+ *   .parent .child { ... }    → .parent .child[data-c-3f8a1b] { ... }
+ *   :root { ... }             → :root { ... }  (left untouched)
+ *   @keyframes spin { ... }   → @keyframes spin { ... }  (keyframes untouched)
+ *   @media (…) { .x { } }    → @media (…) { .x[data-c-…] { } }
+ *
+ * @param {string} css      - Raw CSS string
+ * @param {string} scopeId  - e.g. "3f8a1b"
+ * @returns {string}        - Scoped CSS
+ */
+export function scopeCSS(css, scopeId) {
+  if (!css.trim()) return '';
+  const attr = `[data-c-${scopeId}]`;
+  return _transformCSS(css, attr);
+}
+
+// ─── Internal CSS transformer ─────────────────────────────────────────────────
+
+function _transformCSS(css, attr) {
+  const result = [];
+  let   i      = 0;
+
+  while (i < css.length) {
+    // Skip comments
+    if (css[i] === '/' && css[i + 1] === '*') {
+      const end = css.indexOf('*/', i + 2);
+      if (end === -1) {
+        result.push(css.slice(i));
+        break;
+      }
+      result.push(css.slice(i, end + 2));
+      i = end + 2;
+      continue;
+    }
+
+    // At-rules with blocks: @media, @supports, @layer, @container
+    if (css[i] === '@') {
+      const { rule, rest, isBlock } = _readAtRule(css, i);
+      if (isBlock) {
+        // Recurse into the block content to scope nested selectors
+        const blockMatch = rule.match(/^(@[\w-]+[^{]*)\{([\s\S]*)\}$/s);
+        if (blockMatch) {
+          const inner = _transformCSS(blockMatch[2], attr);
+          result.push(`${blockMatch[1]}{${inner}}`);
+        } else {
+          result.push(rule);
+        }
+      } else {
+        // @import, @charset, @keyframes (no inner selectors to scope)
+        result.push(rule);
+      }
+      i += rule.length;
+      continue;
+    }
+
+    // Skip whitespace
+    if (/\s/.test(css[i])) {
+      result.push(css[i]);
+      i++;
+      continue;
+    }
+
+    // Read selector + block
+    const { selector, block, total } = _readSelectorBlock(css, i);
+    if (total === 0) {
+      // Malformed — pass through
+      result.push(css[i]);
+      i++;
+      continue;
+    }
+
+    const scopedSelector = _scopeSelector(selector, attr);
+    result.push(`${scopedSelector}${block}`);
+    i += total;
+  }
+
+  return result.join('');
+}
+
+function _readAtRule(css, start) {
+  // Find the end of the at-rule (either ; or a {…} block)
+  let i = start + 1;
+  let depth = 0;
+  let inStr = false;
+  let strChar = '';
+
+  while (i < css.length) {
+    const c = css[i];
+
+    if (inStr) {
+      if (c === strChar && css[i - 1] !== '\\') inStr = false;
+      i++;
+      continue;
+    }
+
+    if (c === '"' || c === "'") { inStr = true; strChar = c; i++; continue; }
+
+    if (c === '{') {
+      depth++;
+      if (depth === 1 && _isAtRuleWithBlock(css, start, i)) {
+        // Read until matching }
+        i++;
+        while (i < css.length) {
+          if (css[i] === '{') depth++;
+          else if (css[i] === '}') {
+            depth--;
+            if (depth === 0) { i++; break; }
+          }
+          i++;
+        }
+        return { rule: css.slice(start, i), rest: css.slice(i), isBlock: true };
+      }
+    }
+
+    if (c === ';' && depth === 0) {
+      i++;
+      return { rule: css.slice(start, i), rest: css.slice(i), isBlock: false };
+    }
+
+    i++;
+  }
+
+  return { rule: css.slice(start), rest: '', isBlock: false };
+}
+
+function _isAtRuleWithBlock(css, atStart, bracePos) {
+  const name = css.slice(atStart, bracePos).match(/@([\w-]+)/)?.[1] ?? '';
+  // Keyframes, charset, import — do not recurse
+  const noRecurse = new Set(['keyframes', 'charset', 'import', 'font-face', 'namespace']);
+  return !noRecurse.has(name);
+}
+
+function _readSelectorBlock(css, start) {
+  // Read up to the first {
+  let i = start;
+  let inStr = false;
+  let strChar = '';
+
+  while (i < css.length) {
+    const c = css[i];
+    if (inStr) {
+      if (c === strChar && css[i - 1] !== '\\') inStr = false;
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'") { inStr = true; strChar = c; i++; continue; }
+    if (c === '{') break;
+    i++;
+  }
+
+  if (i >= css.length) return { selector: '', block: '', total: 0 };
+
+  const selector = css.slice(start, i).trim();
+  // Now read the block {…}
+  let depth = 0;
+  let blockStart = i;
+  i++;
+  depth = 1;
+  while (i < css.length && depth > 0) {
+    if (css[i] === '{') depth++;
+    else if (css[i] === '}') depth--;
+    i++;
+  }
+
+  const block    = css.slice(blockStart, i);
+  return { selector, block, total: i - start };
+}
+
+/**
+ * Add the scope attribute to the last simple selector in each compound selector.
+ *
+ * Selector list (comma-separated) → each selector gets scoped independently.
+ *
+ * We append to the LAST simple selector in a compound so that:
+ *   .parent .child → .parent .child[attr]  (only the leaf is scoped)
+ *
+ * Special cases left untouched:
+ *   :root, html, body, @keyframes stop selectors, :global(...)
+ */
+function _scopeSelector(selector, attr) {
+  if (!selector.trim()) return selector;
+
+  // Split on top-level commas (not inside parens)
+  const parts = _splitSelectorList(selector);
+
+  return parts.map(part => {
+    const t = part.trim();
+
+    // :root, html, body — never scoped
+    if (/^(:root|html|body)$/i.test(t)) return t;
+
+    // :global(…) — strip the wrapper, output the inner selector as-is (not scoped)
+    if (t.startsWith(':global(') && t.endsWith(')')) {
+      return t.slice(':global('.length, -1).trim();
+    }
+
+    // :local(…) — explicitly scope the inner selector
+    if (t.startsWith(':local(') && t.endsWith(')')) {
+      const inner = t.slice(':local('.length, -1).trim();
+      return _appendToLastSimple(inner, attr);
+    }
+
+    // Mixed selectors may contain :global() or :local() inline fragments:
+    //   .parent :global(.child) → .parent[attr] .child
+    //   :global(.outer) .inner → .outer .inner[attr]
+    // Handle these by splitting on :global()/`:local()` pseudo-functions.
+    if (t.includes(':global(') || t.includes(':local(')) {
+      return _processLocalGlobalFragments(t, attr);
+    }
+
+    // Default: scope the whole selector
+    return _appendToLastSimple(t, attr);
+  }).join(', ');
+}
+
+/**
+ * Handle selectors that mix :local() and :global() fragments inline.
+ * E.g.: ".parent :global(.child)" → ".parent[attr] .child"
+ *       ":global(.header) .body"  → ".header .body[attr]"
+ */
+function _processLocalGlobalFragments(selector, attr) {
+  // Tokenise the selector into scoped and unscoped segments
+  const result = [];
+  let i = 0;
+  let lastWasGlobal = false;
+  let buf = '';
+
+  while (i < selector.length) {
+    // Detect :global(...)
+    if (selector.startsWith(':global(', i)) {
+      // Flush buffered scoped text
+      if (buf.trim()) {
+        result.push(_appendToLastSimple(buf.trim(), attr));
+        buf = '';
+        lastWasGlobal = false;
+      }
+      const end = _findClosingParen(selector, i + ':global('.length - 1);
+      const inner = selector.slice(i + ':global('.length, end);
+      result.push(inner);
+      i = end + 1;
+      lastWasGlobal = true;
+      continue;
+    }
+    // Detect :local(...)
+    if (selector.startsWith(':local(', i)) {
+      if (buf.trim()) {
+        result.push(_appendToLastSimple(buf.trim(), attr));
+        buf = '';
+      }
+      const end = _findClosingParen(selector, i + ':local('.length - 1);
+      const inner = selector.slice(i + ':local('.length, end);
+      result.push(_appendToLastSimple(inner.trim(), attr));
+      i = end + 1;
+      lastWasGlobal = false;
+      continue;
+    }
+    // Accumulate combinator/whitespace between segments
+    if (lastWasGlobal && /[\s>~+]/.test(selector[i])) {
+      result.push(selector[i]);
+      i++;
+      continue;
+    }
+    buf += selector[i];
+    i++;
+  }
+  if (buf.trim()) result.push(_appendToLastSimple(buf.trim(), attr));
+  return result.join('');
+}
+
+function _findClosingParen(str, openPos) {
+  let depth = 0;
+  for (let i = openPos; i < str.length; i++) {
+    if (str[i] === '(') depth++;
+    else if (str[i] === ')') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return str.length - 1;
+}
+
+function _appendToLastSimple(selector, attr) {
+  // Find the last segment (not a combinator: space, >, ~, +)
+  // Split on combinators while keeping them
+  const parts = selector.split(/([\s>~+]+)/);
+  // last non-combinator part
+  let lastIdx = parts.length - 1;
+  while (lastIdx > 0 && /^[\s>~+]+$/.test(parts[lastIdx])) lastIdx--;
+
+  const lastPart = parts[lastIdx];
+
+  // Insert attr before pseudo-elements (::before, ::after)
+  const pseudoElRE = /:{1,2}[a-z-]+(\([^)]*\))?$/i;
+  const peMatch    = lastPart.match(pseudoElRE);
+
+  if (peMatch) {
+    const idx = lastPart.lastIndexOf(peMatch[0]);
+    parts[lastIdx] = lastPart.slice(0, idx) + attr + lastPart.slice(idx);
+  } else {
+    parts[lastIdx] = lastPart + attr;
+  }
+
+  return parts.join('');
+}
+
+function _splitSelectorList(selector) {
+  const parts  = [];
+  let   depth  = 0;
+  let   start  = 0;
+  let   inStr  = false;
+  let   strCh  = '';
+
+  for (let i = 0; i < selector.length; i++) {
+    const c = selector[i];
+    if (inStr) {
+      if (c === strCh && selector[i - 1] !== '\\') inStr = false;
+      continue;
+    }
+    if (c === '"' || c === "'") { inStr = true; strCh = c; continue; }
+    if (c === '(') { depth++; continue; }
+    if (c === ')') { depth--; continue; }
+    if (c === ',' && depth === 0) {
+      parts.push(selector.slice(start, i));
+      start = i + 1;
+    }
+  }
+
+  parts.push(selector.slice(start));
+  return parts;
+}
+
+// ─── injectScopeAttr ─────────────────────────────────────────────────────────
+
+/**
+ * Given generated JavaScript code for a component, inject the scope data
+ * attribute onto the root element.
+ *
+ * The codegen emits something like:
+ *   const _root = h('div', { class: 'card' }, [...]);
+ *
+ * We patch it to:
+ *   const _root = h('div', { class: 'card', 'data-c-3f8a1b': '' }, [...]);
+ *
+ * This is called by the Vite plugin / compiler after codegen, before writing
+ * the final JS output.
+ *
+ * @param {string} code     - Generated JS
+ * @param {string} scopeId  - e.g. "3f8a1b"
+ * @returns {string}        - Patched JS
+ */
+export function injectScopeAttr(code, scopeId) {
+  if (!scopeId) return code;
+  const attr   = `'data-c-${scopeId}': ''`;
+  // The codegen always names the root element variable _root in the component factory.
+  // We insert the attr into the first h(...) call props object.
+  // Pattern: h('tag', {   →   h('tag', { 'data-c-xxx': '',
+  return code.replace(
+    /\bh\((['"`][^'"` ]+['"`]),\s*\{/,
+    `h($1, { ${attr}, `
+  );
+}
+
+// ─── CSS Modules support ──────────────────────────────────────────────────────
+
+/**
+ * Process a `<style module>` block.
+ *
+ * In CSS Modules mode:
+ *   - All class selectors are renamed:  .card → .card_3f8a1b
+ *   - :global(.foo) opts out of renaming
+ *   - :local(.foo)  opts in (always renamed, even if global mode is used)
+ *   - Returns { css: transformedCSS, classMap: { card: 'card_3f8a1b' } }
+ *
+ * Usage:
+ *   const { css, classMap } = cssModules(raw, scopeId);
+ *   // classMap.card === 'card_3f8a1b'
+ *   // Inject classMap as `styles` into the component props
+ *
+ * @param {string} css      - Raw CSS from <style module>
+ * @param {string} scopeId  - Scope hash e.g. "3f8a1b"
+ * @param {object} [opts]
+ * @param {boolean} [opts.globalDefault=false] - If true, classes are global by default (only :local() scopes)
+ * @returns {{ css: string, classMap: object }}
+ */
+export function cssModules(css, scopeId, { globalDefault = false } = {}) {
+  if (!css.trim()) return { css: '', classMap: {} };
+
+  const classMap = {};
+
+  /**
+   * Rename a class name: .card → .card_3f8a1b
+   * Side effect: records the mapping in classMap.
+   */
+  function rename(cls) {
+    const key = cls.slice(1); // strip leading '.'
+    const renamed = `${key}_${scopeId}`;
+    classMap[key] = renamed;
+    return `.${renamed}`;
+  }
+
+  const transformed = _transformCSSModules(css, { rename, globalDefault });
+  return { css: transformed, classMap };
+}
+
+/**
+ * Transform CSS for modules mode: rename .class selectors unless :global() wrapped.
+ */
+function _transformCSSModules(css, { rename, globalDefault }) {
+  const result = [];
+  let i = 0;
+
+  while (i < css.length) {
+    // Skip comments
+    if (css[i] === '/' && css[i + 1] === '*') {
+      const end = css.indexOf('*/', i + 2);
+      if (end === -1) { result.push(css.slice(i)); break; }
+      result.push(css.slice(i, end + 2));
+      i = end + 2;
+      continue;
+    }
+
+    // At-rules with blocks
+    if (css[i] === '@') {
+      const { rule, isBlock } = _readAtRule(css, i);
+      if (isBlock) {
+        const blockMatch = rule.match(/^(@[\w-]+[^{]*)\{([\s\S]*)\}$/s);
+        if (blockMatch) {
+          const inner = _transformCSSModules(blockMatch[2], { rename, globalDefault });
+          result.push(`${blockMatch[1]}{${inner}}`);
+        } else {
+          result.push(rule);
+        }
+      } else {
+        result.push(rule);
+      }
+      i += rule.length;
+      continue;
+    }
+
+    // Whitespace pass-through
+    if (/\s/.test(css[i])) { result.push(css[i]); i++; continue; }
+
+    // Selector block
+    const { selector, block, total } = _readSelectorBlock(css, i);
+    if (total === 0) { result.push(css[i]); i++; continue; }
+
+    const transformedSelector = _transformModuleSelector(selector, { rename, globalDefault });
+    result.push(`${transformedSelector}${block}`);
+    i += total;
+  }
+
+  return result.join('');
+}
+
+function _transformModuleSelector(selector, { rename, globalDefault }) {
+  if (!selector.trim()) return selector;
+  const parts = _splitSelectorList(selector);
+
+  return parts.map(part => {
+    const t = part.trim();
+    return _renameClassesInSelector(t, { rename, globalDefault });
+  }).join(', ');
+}
+
+/**
+ * Walk through a selector string, renaming class tokens.
+ *
+ * Handles:
+ *   .card                 → .card_xxx                 (scoped)
+ *   :global(.card)        → .card                     (not renamed)
+ *   :local(.card)         → .card_xxx                 (always renamed)
+ *   .parent :global(.sub) → .parent_xxx .sub          (mixed)
+ */
+function _renameClassesInSelector(selector, { rename, globalDefault }) {
+  let result = '';
+  let i = 0;
+
+  while (i < selector.length) {
+    // :global(...) — pass through inner content unchanged
+    if (selector.startsWith(':global(', i)) {
+      const end = _findClosingParen(selector, i + ':global('.length - 1);
+      const inner = selector.slice(i + ':global('.length, end);
+      // Keep as-is — don't rename inside :global()
+      result += inner;
+      i = end + 1;
+      continue;
+    }
+
+    // :local(...) — always rename inner classes
+    if (selector.startsWith(':local(', i)) {
+      const end = _findClosingParen(selector, i + ':local('.length - 1);
+      const inner = selector.slice(i + ':local('.length, end);
+      result += _renameRawClasses(inner, rename);
+      i = end + 1;
+      continue;
+    }
+
+    // Class selector token: .foo
+    if (selector[i] === '.' && (i === 0 || /[\s>~+:(]/.test(selector[i - 1]))) {
+      // Read class name
+      let j = i + 1;
+      while (j < selector.length && /[\w-]/.test(selector[j])) j++;
+      const cls = selector.slice(i, j);
+      if (!globalDefault) {
+        result += rename(cls);
+      } else {
+        result += cls; // global-default: leave class as-is (only :local() renames)
+      }
+      i = j;
+      continue;
+    }
+
+    result += selector[i];
+    i++;
+  }
+
+  return result;
+}
+
+function _renameRawClasses(selector, rename) {
+  return selector.replace(/\.([\w-]+)/g, (_, name) => rename(`.${name}`));
+}
+
+// ─── collectStyles (for SSR / build pipeline) ─────────────────────────────────
+
+/**
+ * Aggregate all scoped + global CSS from multiple processed files.
+ * Returns a single CSS string suitable for injection into <head>.
+ *
+ * @param {Array<{ scoped: string, global: string, scopeId: string }>} entries
+ * @returns {string}
+ */
+export function collectStyles(entries) {
+  const parts = [];
+  for (const { scoped, global, scopeId } of entries) {
+    if (global.trim())          parts.push(global.trim());
+    if (scoped.trim() && scopeId) {
+      parts.push(scopeCSS(scoped, scopeId));
+    }
+  }
+  return parts.join('\n');
+}