santycss 1.0.0

package/lib/purge-core.js

@@ -0,0 +1,223 @@
+'use strict';
+/**
+ * SantyCSS — core purge engine (used by CLI, PostCSS plugin, and Vite plugin)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const EXTS = ['.html','.js','.jsx','.ts','.tsx','.vue','.svelte','.njk','.hbs','.pug','.php','.astro','.mdx','.md'];
+const SKIP  = new Set(['build.js','purge.js','postcss.config.js','postcss.config.cjs','vite.config.js','vite.config.ts','webpack.config.js','next.config.js','nuxt.config.js','nuxt.config.ts']);
+
+// ─── File walker ──────────────────────────────────────────────────────────────
+function walkDir(dir, files = []) {
+  if (!fs.existsSync(dir)) return files;
+  const stat = fs.statSync(dir);
+  if (stat.isFile()) {
+    if (!SKIP.has(path.basename(dir))) files.push(dir);
+    return files;
+  }
+  for (const entry of fs.readdirSync(dir)) {
+    if (['node_modules','.git','dist','.next','.nuxt','.output','build','__pycache__','.svelte-kit'].includes(entry)) continue;
+    walkDir(path.join(dir, entry), files);
+  }
+  return files;
+}
+
+// ─── Class extractor ──────────────────────────────────────────────────────────
+const CLASS_ATTR  = /class(?:Name)?=(?:"([^"]+)"|'([^']+)'|`([^`]+)`)/g;
+const BARE_STRING = /["'`]([\w][\w\-:/]+)["'`]/g;
+
+function extractClasses(content) {
+  const found = new Set();
+
+  // 1. class="..." / className="..." / class='...' / class=`...`
+  CLASS_ATTR.lastIndex = 0;
+  let m;
+  while ((m = CLASS_ATTR.exec(content)) !== null) {
+    const raw = (m[1] || m[2] || m[3] || '').trim();
+    raw.split(/\s+/).forEach(c => c && found.add(c.trim()));
+  }
+
+  // 2. Dynamic: clsx(['foo','bar']), cn('a','b'), classList.add('x')
+  //    Match any quoted string that looks like a CSS class (has a dash, no spaces)
+  BARE_STRING.lastIndex = 0;
+  while ((m = BARE_STRING.exec(content)) !== null) {
+    const c = m[1].trim();
+    if (c.includes('-') && !c.includes(' ')) found.add(c);
+  }
+
+  // 3. Template literals: `make-flex ${condition ? 'add-padding-16' : 'add-padding-8'}`
+  const tpl = content.match(/`[^`]+`/g) || [];
+  tpl.forEach(t => {
+    t.split(/\s+|\$\{[^}]+\}/).forEach(part => {
+      const c = part.replace(/[`'"]/g, '').trim();
+      if (c && c.includes('-')) found.add(c);
+    });
+  });
+
+  return found;
+}
+
+// ─── CSS parser ───────────────────────────────────────────────────────────────
+function parseCSS(css) {
+  const blocks = [];
+  let i = 0, len = css.length;
+
+  while (i < len) {
+    while (i < len && /\s/.test(css[i])) i++;
+    if (i >= len) break;
+
+    if (css[i] === '/' && css[i+1] === '*') {
+      const end = css.indexOf('*/', i + 2);
+      if (end === -1) break;
+      blocks.push({ type: 'comment', raw: css.slice(i, end + 2) });
+      i = end + 2;
+      continue;
+    }
+
+    if (css[i] === '@' || css.slice(i, i+5) === ':root') {
+      let bs = i;
+      while (bs < len && css[bs] !== '{' && css[bs] !== ';') bs++;
+      if (bs >= len) break;
+      if (css[bs] === ';') { blocks.push({ type: 'at-simple', raw: css.slice(i, bs + 1) }); i = bs + 1; continue; }
+      let depth = 0, j = bs;
+      while (j < len) {
+        if (css[j] === '{') depth++;
+        else if (css[j] === '}' && --depth === 0) { j++; break; }
+        j++;
+      }
+      blocks.push({ type: 'at-block', raw: css.slice(i, j) });
+      i = j;
+      continue;
+    }
+
+    let bs = i;
+    while (bs < len && css[bs] !== '{') bs++;
+    if (bs >= len) break;
+    let be = bs;
+    while (be < len && css[be] !== '}') be++;
+    if (be >= len) break;
+    blocks.push({ type: 'rule', selector: css.slice(i, bs).trim(), raw: css.slice(i, be + 1) });
+    i = be + 1;
+  }
+  return blocks;
+}
+
+// ─── Selector usage check ─────────────────────────────────────────────────────
+const BASE_SELECTORS = ['*', ':root', 'html', 'body', ':before', ':after', '::before', '::after'];
+
+function selectorUsed(selector, usedSet) {
+  if (BASE_SELECTORS.some(s => selector.includes(s))) return true;
+  const classMatches = selector.match(/\.([\w\-\\:]+)/g);
+  if (!classMatches) return true; // non-class selector — keep
+  return classMatches.some(cm => usedSet.has(cm.slice(1).replace(/\\/g, '')));
+}
+
+// ─── @media / @keyframes filter ──────────────────────────────────────────────
+function filterAtBlock(raw, usedSet) {
+  const headerMatch = raw.match(/^([^{]+)\{/);
+  if (!headerMatch) return raw;
+  const atRule = headerMatch[1].trim();
+
+  // Always keep keyframes, font-face
+  if (atRule.startsWith('@keyframes') || atRule.startsWith('@font-face')) return raw;
+
+  // :root block — always keep
+  if (atRule.startsWith(':root')) return raw;
+
+  // For @media — filter inner rules
+  const innerStart = raw.indexOf('{') + 1;
+  const innerEnd   = raw.lastIndexOf('}');
+  const inner      = raw.slice(innerStart, innerEnd);
+
+  const kept = [];
+  const ruleRe = /([^{]+)\{([^}]+)\}/g;
+  let m;
+  while ((m = ruleRe.exec(inner)) !== null) {
+    if (selectorUsed(m[1].trim(), usedSet)) {
+      kept.push(`  ${m[1].trim()} { ${m[2].trim()} }`);
+    }
+  }
+  return kept.length ? `${atRule} {\n${kept.join('\n')}\n}` : null;
+}
+
+// ─── Minifier ─────────────────────────────────────────────────────────────────
+function minify(css) {
+  return css
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\s*\n\s*/g, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .replace(/\s*([{}:;,>~+])\s*/g, '$1')
+    .replace(/;}/g, '}')
+    .trim();
+}
+
+// ─── Main purge function ──────────────────────────────────────────────────────
+/**
+ * @param {object} opts
+ * @param {string}   opts.css         Full source CSS string (santy.css contents)
+ * @param {string[]} opts.content     Array of file paths OR raw content strings to scan
+ * @param {string[]} [opts.safelist]  Class names to always keep
+ * @param {boolean}  [opts.minify]    Minify output (default true)
+ * @returns {{ css: string, stats: object }}
+ */
+function purge({ css, content = [], safelist = [], minifyOutput = true }) {
+  const usedClasses = new Set(safelist);
+
+  for (const item of content) {
+    // item is either a file path or raw content
+    let text = item;
+    if (typeof item === 'string' && fs.existsSync(item) && !item.includes('\n')) {
+      try { text = fs.readFileSync(item, 'utf8'); } catch (_) { text = item; }
+    }
+    extractClasses(text).forEach(c => usedClasses.add(c));
+  }
+
+  const blocks = parseCSS(css);
+  const kept = [];
+  let keptRules = 0, droppedRules = 0;
+
+  for (const block of blocks) {
+    if (block.type === 'comment')  { kept.push(block.raw); continue; }
+    if (block.type === 'at-simple'){ kept.push(block.raw); continue; }
+
+    if (block.type === 'at-block') {
+      const filtered = filterAtBlock(block.raw, usedClasses);
+      if (filtered) { kept.push(filtered); keptRules++; }
+      else droppedRules++;
+      continue;
+    }
+
+    if (block.type === 'rule') {
+      if (selectorUsed(block.selector, usedClasses)) {
+        kept.push(block.raw); keptRules++;
+      } else droppedRules++;
+    }
+  }
+
+  const rawOutput = kept.join('\n');
+  const output    = minifyOutput ? minify(rawOutput) : rawOutput;
+
+  return {
+    css: output,
+    stats: {
+      classesFound: usedClasses.size,
+      rulesKept:    keptRules,
+      rulesDropped: droppedRules,
+      originalSize: Buffer.byteLength(css, 'utf8'),
+      outputSize:   Buffer.byteLength(output, 'utf8'),
+    }
+  };
+}
+
+// ─── File-based helper ────────────────────────────────────────────────────────
+function purgeFiles({ cssFile = 'santy.css', inputDirs = ['.'], safelist = [], minifyOutput = true } = {}) {
+  const css = fs.readFileSync(cssFile, 'utf8');
+  const files = [];
+  inputDirs.forEach(d => walkDir(d, files));
+  const sourceFiles = files.filter(f => EXTS.includes(path.extname(f).toLowerCase()));
+  return purge({ css, content: sourceFiles, safelist, minifyOutput });
+}
+
+module.exports = { purge, purgeFiles, extractClasses, walkDir, minify, EXTS };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "santycss",
+  "version": "1.0.0",
+  "description": "Plain-English utility-first CSS framework — no build step, just classes",
+  "main": "index.js",
+  "style": "dist/santy.css",
+  "exports": {
+    ".":                  "./index.js",
+    "./css":              "./dist/santy.css",
+    "./css/core":         "./dist/santy-core.css",
+    "./css/components":   "./dist/santy-components.css",
+    "./css/animations":   "./dist/santy-animations.css",
+    "./min":              "./dist/santy.min.css",
+    "./postcss":          "./postcss/index.js",
+    "./jit":              "./santy-jit.js",
+    "./vite":             "./vite-plugin-santycss.js",
+    "./purge":            "./lib/purge-core.js"
+  },
+  "files": [
+    "dist/",
+    "postcss/",
+    "lib/",
+    "index.js",
+    "santy-jit.js",
+    "vite-plugin-santycss.js",
+    "purge.js",
+    "README.md"
+  ],
+  "bin": {
+    "santycss": "./purge.js"
+  },
+  "keywords": [
+    "css",
+    "framework",
+    "utility-css",
+    "tailwind-alternative",
+    "plain-english",
+    "no-build",
+    "santycss",
+    "postcss",
+    "vite"
+  ],
+  "scripts": {
+    "build":      "node build.js",
+    "purge":      "node purge.js",
+    "dev":        "node build.js && echo 'Watching...'",
+    "prepublish": "node build.js"
+  },
+  "peerDependencies": {
+    "postcss": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "postcss": { "optional": true }
+  },
+  "author": "Santy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChintuSanty/santyCSS.git"
+  },
+  "homepage": "https://santycss.santy.in",
+  "bugs": {
+    "url": "https://github.com/ChintuSanty/santyCSS/issues"
+  }
+}

package/postcss/index.js

@@ -0,0 +1,79 @@
+'use strict';
+/**
+ * postcss-santycss
+ *
+ * PostCSS plugin that purges unused SantyCSS utilities.
+ *
+ * Usage in postcss.config.js:
+ *
+ *   const santycss = require('santycss/postcss');
+ *
+ *   module.exports = {
+ *     plugins: [
+ *       santycss({
+ *         content: ['./src/**\/*.{html,js,jsx,ts,tsx,vue,svelte}'],
+ *         safelist: ['animate-spin', 'make-hidden'],
+ *       }),
+ *     ],
+ *   };
+ */
+
+const path = require('path');
+const fs   = require('fs');
+const { purge, extractClasses, EXTS } = require('../lib/purge-core');
+
+function expandGlobs(patterns) {
+  const files = [];
+  for (const pat of patterns) {
+    if (!pat.includes('*')) {
+      if (fs.existsSync(pat)) files.push(pat);
+      continue;
+    }
+    const parts  = pat.split(/[/\\]/);
+    const base   = parts.slice(0, parts.findIndex(p => p.includes('*'))).join('/') || '.';
+    const extMatch = pat.match(/\.([\w,{}]+)$/);
+    const exts   = extMatch ? extMatch[1].replace(/[{}]/g,'').split(',') : EXTS;
+    function walk(dir) {
+      if (!fs.existsSync(dir)) return;
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = dir + '/' + entry.name;
+        if (entry.isDirectory()) walk(full);
+        else if (exts.some(e => entry.name.endsWith('.' + e))) files.push(full);
+      }
+    }
+    walk(base);
+  }
+  return [...new Set(files)];
+}
+
+module.exports = (opts = {}) => {
+  const { content = [], safelist = [], sourceFile = null } = opts;
+
+  return {
+    postcssPlugin: 'postcss-santycss',
+    async Once(root, { result }) {
+      const files = expandGlobs(content);
+      if (!files.length && !sourceFile) return;
+
+      const sourceCSS = sourceFile
+        ? fs.readFileSync(sourceFile, 'utf8')
+        : fs.readFileSync(path.join(__dirname, '../dist/santy.css'), 'utf8');
+
+      const html = files.map(f => fs.readFileSync(f, 'utf8')).join('\n');
+      const purged = purge(sourceCSS, html, { safelist });
+
+      root.removeAll();
+      const postcss = require('postcss');
+      const parsed  = postcss.parse(purged);
+      parsed.each(node => root.append(node.clone()));
+
+      result.messages.push({
+        type: 'santycss',
+        plugin: 'postcss-santycss',
+        text: `Purged to ${(purged.length / 1024).toFixed(1)}KB from ${files.length} files`,
+      });
+    },
+  };
+};
+
+module.exports.postcss = true;

package/purge.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * SantyCSS CLI Purger  —  node purge.js [options]
+ *
+ *   --input=<dir>        Directories to scan (default: .)
+ *   --out=<file>         Output file (default: santy.min.css)
+ *   --css=<file>         Source CSS (default: santy.css)
+ *   --keep=<a,b,c>       Always-include class names
+ *   --safelist=<file>    JSON file ["class1","class2",...]
+ *   --verbose            List every class found
+ *   --stats              Print stats only, no file written
+ *   --no-minify          Write readable (un-minified) output
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { purge, walkDir, EXTS } = require('./lib/purge-core');
+
+// ─── Parse CLI args ───────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const getArg  = (k, def) => { const m = args.find(a => a.startsWith(`--${k}=`)); return m ? m.slice(k.length + 3) : def; };
+const hasFlag = (k) => args.includes(`--${k}`);
+
+const inputDirs  = getArg('input', '.').split(',').map(d => d.trim());
+const outFile    = getArg('out', 'santy.min.css');
+const cssFile    = getArg('css', 'santy.css');
+const keepArg    = getArg('keep', '');
+const safeFile   = getArg('safelist', '');
+const verbose    = hasFlag('verbose');
+const statsOnly  = hasFlag('stats');
+const noMinify   = hasFlag('no-minify');
+
+// ─── Load source CSS ──────────────────────────────────────────────────────────
+if (!fs.existsSync(cssFile)) {
+  console.error(`❌  Cannot find ${cssFile}. Run: node build.js first.`);
+  process.exit(1);
+}
+const css = fs.readFileSync(cssFile, 'utf8');
+
+// ─── Safelist ─────────────────────────────────────────────────────────────────
+const safelist = [];
+if (safeFile && fs.existsSync(safeFile)) {
+  JSON.parse(fs.readFileSync(safeFile, 'utf8')).forEach(c => safelist.push(c));
+}
+if (keepArg) keepArg.split(',').map(c => c.trim()).filter(Boolean).forEach(c => safelist.push(c));
+
+// ─── Collect files ────────────────────────────────────────────────────────────
+const allFiles = [];
+inputDirs.forEach(d => walkDir(d, allFiles));
+const sourceFiles = allFiles.filter(f => EXTS.includes(path.extname(f).toLowerCase()));
+
+if (sourceFiles.length === 0) {
+  console.warn('⚠️  No source files found. Writing full CSS instead.');
+  fs.writeFileSync(outFile, css, 'utf8');
+  process.exit(0);
+}
+
+// ─── Run purge ────────────────────────────────────────────────────────────────
+const { css: output, stats } = purge({ css, content: sourceFiles, safelist, minifyOutput: !noMinify });
+
+// ─── Stats ────────────────────────────────────────────────────────────────────
+const estGzip  = Math.round(stats.outputSize * 0.15);
+const reduction = (((stats.originalSize - stats.outputSize) / stats.originalSize) * 100).toFixed(1);
+
+console.log('\n📦  SantyCSS Purge Report');
+console.log('─'.repeat(46));
+console.log(`  Source files scanned  : ${sourceFiles.length}`);
+console.log(`  Unique classes found  : ${stats.classesFound}`);
+console.log(`  Rules kept            : ${stats.rulesKept}`);
+console.log(`  Rules dropped         : ${stats.rulesDropped}`);
+console.log('─'.repeat(46));
+console.log(`  Original size   : ${(stats.originalSize/1024).toFixed(1)} KB`);
+console.log(`  Purged size     : ${(stats.outputSize/1024).toFixed(1)} KB`);
+console.log(`  Est. gzip       : ~${(estGzip/1024).toFixed(1)} KB`);
+console.log(`  Reduction       : ${reduction}% smaller`);
+console.log('─'.repeat(46));
+
+if (verbose) {
+  // Re-extract for display (stats don't store them)
+  const { extractClasses } = require('./lib/purge-core');
+  const all = new Set(safelist);
+  sourceFiles.forEach(f => {
+    const text = fs.readFileSync(f, 'utf8');
+    extractClasses(text).forEach(c => all.add(c));
+  });
+  console.log('\nClasses found in source:');
+  [...all].sort().forEach(c => console.log('   ', c));
+}
+
+if (statsOnly) {
+  console.log('\n(--stats: no file written)\n');
+  process.exit(0);
+}
+
+fs.writeFileSync(outFile, output, 'utf8');
+console.log(`\n✅  Written → ${outFile}\n`);