zeus-css 1.0.0

package/scss/scripts/gen-cheatsheet.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Cheatsheet Generator                            ║
+// ║                                                               ║
+// ║  Scans the actual SCSS source (never hand-maintained, so it   ║
+// ║  can't drift) for every public @mixin/@function signature and ║
+// ║  every utility-class family pattern, and emits:                ║
+// ║    llms.txt        — flat, LLM-context-friendly reference      ║
+// ║    cheatsheet.md   — the same content, as readable Markdown    ║
+// ║                                                                ║
+// ║  "Public" = does not start with "_" — the framework's own      ║
+// ║  established convention for internal/private helpers.          ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+import { fileURLToPath } from "node:url";
+import { dirname, join, relative } from "node:path";
+import { readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+
+function walk(dir) {
+  let out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const s = statSync(full);
+    if (s.isDirectory()) out = out.concat(walk(full));
+    else if (entry.endsWith(".scss")) out.push(full);
+  }
+  return out;
+}
+
+// ── 1. Mixins & functions ─────────────────────────────────────────
+const engineFiles = walk(join(ROOT, "foundation/core/engine")).concat(
+  walk(join(ROOT, "foundation/core/buttons"))
+);
+
+const apiEntries = [];
+const defStartRegex = /^(@mixin|@function)\s+([a-zA-Z][a-zA-Z0-9-]*)\s*(\(|\{|$)/;
+
+// A comment line counts as a real description only if it's mostly letters —
+// filters out decorative dividers like "╚══...══╝", "----...----",
+// "= = = = = = =" that would otherwise get picked up as the "description".
+function isProseComment(line) {
+  const stripped = line.trim().replace(/^\/+\s*/, "");
+  if (stripped.length < 3) return false;
+  const letters = (stripped.match(/[a-zA-Z]/g) || []).length;
+  return letters / stripped.length > 0.4;
+}
+
+for (const file of engineFiles) {
+  const raw = readFileSync(file, "utf8");
+  const lines = raw.split("\n");
+  const relPath = relative(ROOT, file).replace(/\\/g, "/");
+
+  // Whole-file opt-out: a header explicitly stating this file is private
+  // (e.g. "Private file — NOT part of the public API", fluid-core.scss)
+  // takes precedence over the underscore-name convention below.
+  const header = lines.slice(0, 15).join("\n");
+  if (/not part of the public api|private file/i.test(header)) continue;
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(defStartRegex);
+    if (!m) continue;
+    const [, kind, name] = m;
+    if (name.startsWith("_")) continue; // private, skip
+
+    // Collect the full signature by tracking paren depth across lines —
+    // handles both multi-line parameter lists (@mixin slide-in(\n $a,\n $b\n))
+    // and default values that themselves contain parens (rgba(59,130,246,0.5)).
+    let sigText = "";
+    let depth = 0;
+    let started = false;
+    outer: for (let j = i; j < lines.length; j++) {
+      for (const ch of lines[j]) {
+        if (ch === "(") {
+          depth++;
+          started = true;
+        } else if (ch === ")") {
+          depth--;
+        }
+        sigText += ch;
+        if (started && depth === 0) break outer;
+        if (!started && ch === "{") break outer; // no-parens mixin: "@mixin foo() {" already handled; "@mixin foo {" edge case
+      }
+      sigText += " ";
+    }
+    const parenMatch = sigText.match(/\(([\s\S]*)\)/);
+    const params = parenMatch
+      ? "(" + parenMatch[1].replace(/\s+/g, " ").trim() + ")"
+      : "()";
+
+    // Find the nearest preceding prose comment line as description
+    let desc = "";
+    for (let j = i - 1; j >= 0 && j > i - 6; j--) {
+      const t = lines[j].trim();
+      if (t === "") continue;
+      if (t.startsWith("//")) {
+        if (isProseComment(t)) desc = t.replace(/^\/+\s*/, "");
+        break;
+      }
+      break;
+    }
+    apiEntries.push({ kind: kind.slice(1), name, params, desc, file: relPath });
+  }
+}
+
+// ── 2. Utility class families ──────────────────────────────────────
+const classFiles = walk(join(ROOT, "foundation/views/render/classes"));
+const classFamilies = [];
+const mixinNameRegex = /@mixin\s+(load-[a-zA-Z-]+)/;
+const classRegex = /\.#\{\$prefix\}([a-zA-Z0-9_\\:-]+)/g;
+
+for (const file of classFiles) {
+  const src = readFileSync(file, "utf8");
+  const relPath = relative(ROOT, file).replace(/\\/g, "/");
+  const mixinMatch = src.match(mixinNameRegex);
+  const loaderName = mixinMatch ? mixinMatch[1] : relPath;
+  const seen = new Set();
+  let m;
+  while ((m = classRegex.exec(src)) !== null) {
+    // The regex boundary already stops before "#{...}" interpolations, so a
+    // dynamic class like ".col-span-#{$i}" is captured as "col-span-" — turn
+    // that trailing dash into a readable "{n}" placeholder. Also strip a
+    // trailing "\\:" left over from the hover:/focus: variant escape.
+    let family = m[1].replace(/\\:$/, "");
+    if (family.endsWith("-")) family += "{n}";
+    if (!seen.has(family)) {
+      seen.add(family);
+      classFamilies.push({ family, loader: loaderName, file: relPath });
+    }
+  }
+}
+
+// ── 3. Render llms.txt ──────────────────────────────────────────────
+let llms = "";
+llms += "# Zeus CSS — LLM Reference\n\n";
+llms += "Auto-generated from source (scripts/gen-cheatsheet.mjs). Two entry points:\n";
+llms += '  @use "zeus" as *;         — mixins/functions only, zero CSS emitted\n';
+llms += '  @use "foundation";        — full compiled CSS, import once at app root\n\n';
+
+llms += "## Mixins & Functions\n\n";
+for (const e of apiEntries) {
+  llms += `${e.kind} ${e.name}${e.params}`;
+  if (e.desc) llms += ` — ${e.desc}`;
+  llms += ` [${e.file}]\n`;
+}
+
+llms += "\n## Utility Class Families\n\n";
+for (const c of classFamilies) {
+  llms += `.${c.family}  (${c.loader})  [${c.file}]\n`;
+}
+
+writeFileSync(join(ROOT, "llms.txt"), llms);
+
+// ── 4. Render cheatsheet.md ──────────────────────────────────────────
+let md = "# Zeus CSS Cheatsheet\n\n";
+md += "> Auto-generated from source — do not hand-edit. Regenerate with `npm run gen:cheatsheet`.\n\n";
+
+md += "## Mixins & Functions\n\n";
+md += "| Kind | Signature | Description | File |\n";
+md += "|---|---|---|---|\n";
+for (const e of apiEntries) {
+  md += `| ${e.kind} | \`${e.name}${e.params}\` | ${e.desc} | \`${e.file}\` |\n`;
+}
+
+md += "\n## Utility Class Families\n\n";
+md += "| Class pattern | Generator mixin | File |\n";
+md += "|---|---|---|\n";
+for (const c of classFamilies) {
+  md += `| \`.${c.family}\` | \`${c.loader}()\` | \`${c.file}\` |\n`;
+}
+
+writeFileSync(join(ROOT, "cheatsheet.md"), md);
+
+console.log(
+  `Wrote llms.txt + cheatsheet.md — ${apiEntries.length} mixins/functions, ${classFamilies.length} utility class families`
+);

package/scss/scripts/gen-tokens.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Design Tokens JSON Generator                    ║
+// ║                                                               ║
+// ║  Compiles foundation.scss, extracts every :root custom         ║
+// ║  property, and emits a W3C Design Tokens Community Group       ║
+// ║  format JSON manifest (zeus.tokens.json) — a single,           ║
+// ║  machine-readable contract of the whole token system for       ║
+// ║  design tools and AI coding agents. Always generated FROM the  ║
+// ║  compiled output, never hand-maintained, so it can never drift ║
+// ║  from what actually ships.                                     ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+import * as sass from "sass";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { writeFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+
+// ── 1. Compile the default build ─────────────────────────────────
+const { css } = sass.compile(join(ROOT, "foundation/foundation.scss"), {
+  loadPaths: [ROOT],
+});
+
+// ── 2. Extract every custom property declaration ─────────────────
+// Matches "  --name: value;" lines anywhere in the compiled CSS —
+// deliberately not limited to a single :root block, since color-scheme
+// strategies ("class"/"attribute") can emit more than one root selector.
+// The value class excludes { and } so this can never accidentally match
+// INTO a BEM modifier selector like ".z-card--flat:hover { ... }" — without
+// that exclusion, "--flat:hover {\n  box-shadow: none" looks exactly like a
+// "--flat: <value>;" custom property declaration to a naive regex.
+const propRegex = /--([a-zA-Z][a-zA-Z0-9-]*):\s*([^;{}]+);/g;
+const tokens = new Map(); // name -> value (first occurrence wins — the
+                          // light/base value, consistent across strategies)
+let match;
+while ((match = propRegex.exec(css)) !== null) {
+  const [, name, value] = match;
+  if (!tokens.has(name)) tokens.set(name, value.trim());
+}
+
+// ── 3. Categorize + assign a W3C token $type ──────────────────────
+// Order matters — first matching prefix wins.
+const CATEGORY_RULES = [
+  { prefix: "color-", group: "color", type: "color" },
+  { prefix: "base-", group: "base", type: "color" },
+  { prefix: "shadow-", group: "shadow", type: "shadow" },
+  { prefix: "text-", group: "typography", type: "typography" },
+  { prefix: "space-", group: "space", type: "dimension" },
+  { prefix: "border-radius-", group: "borderRadius", type: "dimension" },
+  { prefix: "border-line-", group: "borderWidth", type: "dimension" },
+  { prefix: "size-icon-", group: "iconSize", type: "dimension" },
+  { prefix: "col-gap-", group: "columnGap", type: "dimension" },
+  { prefix: "padding-outer", group: "spacing", type: "dimension" },
+  { prefix: "z-", group: "zIndex", type: "number" },
+];
+
+function classify(name) {
+  for (const rule of CATEGORY_RULES) {
+    if (name.startsWith(rule.prefix)) {
+      return { group: rule.group, type: rule.type, key: name.slice(rule.prefix.length) || name };
+    }
+  }
+  return { group: "custom", type: "other", key: name };
+}
+
+// ── 4. Build the W3C Design Tokens tree ───────────────────────────
+const manifest = {
+  $description:
+    "Zeus CSS design tokens — auto-generated from the compiled stylesheet. " +
+    "Do not hand-edit; regenerate with `npm run gen:tokens`.",
+};
+
+for (const [name, rawValue] of tokens) {
+  const { group, type, key } = classify(name);
+  manifest[group] ??= {};
+  // $type: "number" tokens (the z-index scale) get a real JSON number,
+  // per the W3C format — not a numeric-looking string.
+  const value = type === "number" && !Number.isNaN(Number(rawValue)) ? Number(rawValue) : rawValue;
+  manifest[group][key] = {
+    $value: value,
+    $type: type,
+    $description: `--${name}`,
+  };
+}
+
+const outPath = join(ROOT, "zeus.tokens.json");
+writeFileSync(outPath, JSON.stringify(manifest, null, 2) + "\n");
+console.log(`Wrote ${tokens.size} tokens across ${Object.keys(manifest).length - 1} groups to zeus.tokens.json`);