eva-css-for-tailwind 1.0.0

package/README.md

@@ -0,0 +1,226 @@
+# eva-css-for-tailwind
+
+> Fluid design tokens bridge for Tailwind CSS 4 — converts static arbitrary values (`text-[32px]`, `p-[24px]`) into fluid `clamp()` values using eva-css calculations.
+
+## Features
+
+- **Zero runtime dependencies** — pure CSS string generation
+- **Modular API** — use only what you need, compose freely
+- **Exact match** with eva-css SCSS clamp calculations
+- **4 fluid intensities** — extreme (`__`), strong (`_`), normal, light (`-`)
+- **Per-property intensity** — `p-[32px]__` for extreme padding, `gap-[16px]-` for light gap
+- **Spacing + font-size** — separate phi ratios, separate CSS vars (`--{size}` / `--fs-{size}`)
+- **TW4 @theme support** — native utilities (`p-32`) via `generateTheme()`
+- **CLI + programmatic API**
+
+## Installation
+
+```bash
+npm install eva-css-for-tailwind
+```
+
+## API
+
+### `generateVars(config)`
+
+Generate all CSS custom properties. Always complete — these vars are used by the nocode UI.
+
+```typescript
+import { generateVars } from 'eva-css-for-tailwind';
+
+const css = generateVars({
+  sizes: [4, 8, 16, 24, 32, 48, 64, 96],
+  fontSizes: [12, 14, 16, 18, 24, 32, 48],
+});
+```
+
+```css
+:root {
+  --32__: clamp(0.5rem, 3.16vw - 1.11rem, 2.22rem);   /* extreme */
+  --32_:  clamp(0.69rem, 1.67vw + 0.5rem, 2.22rem);    /* strong */
+  --32:   clamp(1.11rem, 1.11vw + 1rem, 2.22rem);       /* normal */
+  --32-:  clamp(1.8rem, 0.56vw + 1.5rem, 2.22rem);      /* light */
+
+  --fs-32__: clamp(0.85rem, 1.67vw + 0.5rem, 2.22rem);
+  --fs-32_:  clamp(1.11rem, 1.11vw + 1rem, 2.22rem);
+  --fs-32:   clamp(1.44rem, 0.56vw + 1.5rem, 2.22rem);
+}
+```
+
+### `generateClassOverrides(classes)`
+
+Generate CSS overrides for specific Tailwind arbitrary classes. Each class gets all its intensity variants. Only generates what you need.
+
+```typescript
+import { generateClassOverrides } from 'eva-css-for-tailwind';
+
+const css = generateClassOverrides([
+  'p-[32px]',
+  'text-[48px]',
+  'gap-[16px]',
+]);
+```
+
+```css
+/* Default + intensity variants per class */
+.p-\[32px\]   { padding: var(--32) }
+.p-\[32px\]__ { padding: var(--32__) }
+.p-\[32px\]_  { padding: var(--32_) }
+.p-\[32px\]-  { padding: var(--32-) }
+
+.text-\[48px\]   { font-size: var(--fs-48) }
+.text-\[48px\]__ { font-size: var(--fs-48__) }
+.text-\[48px\]_  { font-size: var(--fs-48_) }
+
+.gap-\[16px\]   { gap: var(--16) }
+.gap-\[16px\]__ { gap: var(--16__) }
+.gap-\[16px\]_  { gap: var(--16_) }
+.gap-\[16px\]-  { gap: var(--16-) }
+```
+
+Per-property intensity control directly in the class name:
+
+```html
+<section class="pt-[140px]__ pb-[140px] gap-[32px]-">
+  <!--  pt = extreme | pb = normal | gap = light  -->
+  <h1 class="text-[48px]_">Strong fluid font</h1>
+</section>
+```
+
+### `generateTheme(config)`
+
+Generate a TW4 `@theme` block mapping native utilities to eva vars. Use this if your project uses named utilities (`p-32`) instead of arbitrary values (`p-[32px]`).
+
+```typescript
+import { generateTheme } from 'eva-css-for-tailwind';
+
+const css = generateTheme({
+  sizes: [16, 32, 48],
+  fontSizes: [16, 32],
+});
+```
+
+```css
+@theme {
+  --spacing-16: var(--16);
+  --spacing-32: var(--32);
+  --spacing-48: var(--48);
+
+  --font-size-16: var(--fs-16);
+  --font-size-32: var(--fs-32);
+}
+```
+
+### `generateClamp(size, type, intensity)`
+
+Generate a single `clamp()` value. Useful for the nocode UI (preview, inspector...).
+
+```typescript
+import { generateClamp } from 'eva-css-for-tailwind';
+
+generateClamp(32, 'spacing');
+// → "clamp(1.11rem, 1.11vw + 1rem, 2.22rem)"
+
+generateClamp(32, 'spacing', '__');
+// → "clamp(0.5rem, 3.16vw - 1.11rem, 2.22rem)"
+
+generateClamp(16, 'font');
+// → "clamp(0.73rem, 0.28vw + 0.75rem, 1.11rem)"
+```
+
+### `parseClass(className)`
+
+Parse a Tailwind arbitrary class into its components.
+
+```typescript
+import { parseClass } from 'eva-css-for-tailwind';
+
+parseClass('pt-[140px]');
+// → { prefix: 'pt', property: 'padding-top', size: 140, unit: 'px', type: 'spacing' }
+
+parseClass('text-[48px]');
+// → { prefix: 'text', property: 'font-size', size: 48, unit: 'px', type: 'font' }
+```
+
+### `generateBridge(config)`
+
+All-in-one shortcut — generates vars + theme + class overrides. Used by the CLI.
+
+```typescript
+import { generateBridge } from 'eva-css-for-tailwind';
+
+// Full bridge (vars + @theme)
+const css = generateBridge({
+  sizes: [4, 8, 16, 24, 32, 48],
+  fontSizes: [12, 16, 24, 32, 48],
+});
+
+// With specific classes (vars + class overrides only)
+const css = generateBridge({
+  sizes: [4, 8, 16, 24, 32, 48],
+  fontSizes: [12, 16, 24, 32, 48],
+  classes: ['p-[32px]', 'text-[48px]', 'gap-[16px]'],
+});
+```
+
+## Configuration
+
+```javascript
+// eva-tw.config.cjs
+module.exports = {
+  sizes: [4, 8, 12, 16, 24, 32, 48, 64, 96, 128],
+  fontSizes: [12, 14, 16, 18, 20, 24, 32, 48],
+  screen: 1440,
+  defaultIntensity: '',
+};
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `sizes` | — | Spacing sizes in px (from Figma tokens) |
+| `fontSizes` | — | Font sizes in px (from Figma tokens) |
+| `screen` | `1440` | Reference screen width |
+| `phi` | `1.618` | Golden ratio for spacing |
+| `fontPhi` | `1.3` | Ratio for font scaling |
+| `min` | `0.5` | Min fluid factor for spacing |
+| `fontMin` | `0.5` | Min fluid factor for fonts |
+| `max` | `1` | Max fluid factor |
+| `ez` | `142.4` | Extreme intensity factor |
+| `defaultIntensity` | `''` | Default: `__`, `_`, `''`, or `-` |
+
+## Intensity Levels
+
+| Suffix | Fluid behavior |
+|--------|----------------|
+| `__` | Extreme — most responsive, biggest min/max range |
+| `_` | Strong |
+| *(none)* | Normal — balanced (default) |
+| `-` | Light — near-static, smallest range |
+
+Spacing uses all 4 levels. Font-sizes use 3 levels (`__`, `_`, default).
+
+## CLI
+
+```
+eva-css-for-tailwind init                        Create eva-tw.config.cjs
+eva-css-for-tailwind generate                    Write bridge.css
+eva-css-for-tailwind generate --stdout           Output to stdout
+eva-css-for-tailwind generate --out=custom.css   Custom output path
+eva-css-for-tailwind generate --sizes="4,8,16"   Override sizes inline
+eva-css-for-tailwind generate --font-sizes="16"  Override font sizes inline
+eva-css-for-tailwind generate --intensity=_      Set default intensity
+```
+
+## License
+
+MIT
+
+## Author
+
+EVA CSS Framework
+
+## Links
+
+- [eva-css](https://www.npmjs.com/package/eva-css-fluid) — Core fluid framework
+- [eva-colors](https://www.npmjs.com/package/eva-colors) — OKLCH color utilities
+- [eva-purge](https://www.npmjs.com/package/eva-css-purge) — CSS optimization

package/dist/cli.js

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli.ts
+var import_fs = require("fs");
+var import_path = require("path");
+
+// src/clamp.ts
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+function getPercent(size, screen, ratio = 100) {
+  return round2(size / screen * ratio);
+}
+function toRem(size) {
+  return size / 16;
+}
+function getMinRem(percent, min) {
+  return round2(percent * min);
+}
+function getMaxRem(percent, max) {
+  return round2(percent * max);
+}
+function getVW(percent) {
+  return round2(percent);
+}
+function getFinalMinDiv(size, ratio) {
+  return round2(size / ratio);
+}
+function getFinalMinMulti(size, ratio) {
+  return round2(size * ratio);
+}
+function vwLight(calcPercent, sizeRem) {
+  return {
+    vw: round2(getVW(calcPercent) / 4),
+    offset: round2(sizeRem / 1.33)
+  };
+}
+function vwMedium(calcPercent, sizeRem) {
+  return {
+    vw: round2(getVW(calcPercent) / 2),
+    offset: round2(sizeRem / 2)
+  };
+}
+function vwStrong(calcPercent, sizeRem) {
+  return {
+    vw: round2(getVW(calcPercent) / 1.33),
+    offset: round2(sizeRem / 4)
+  };
+}
+function vwExtrem(calcPercentEz, remMin) {
+  return {
+    vw: getVW(calcPercentEz),
+    offset: round2(-remMin)
+  };
+}
+function formatClamp(min, fluid, max) {
+  const minStr = `${round2(min)}rem`;
+  const maxStr = `${round2(max)}rem`;
+  const sign = fluid.offset >= 0 ? "+" : "-";
+  const absOffset = round2(Math.abs(fluid.offset));
+  const fluidStr = `${fluid.vw}vw ${sign} ${absOffset}rem`;
+  return `clamp(${minStr}, ${fluidStr}, ${maxStr})`;
+}
+function generateSpacingClamp(sizePx, screen, phi, min, max, ez, intensity) {
+  const calcPercent = getPercent(sizePx, screen);
+  const calcPercentEz = getPercent(sizePx, screen, ez);
+  const sizeRem = toRem(sizePx);
+  const remMin = getMinRem(calcPercent, min);
+  const remMax = getMaxRem(calcPercent, max);
+  switch (intensity) {
+    // __ = extreme (most fluid)
+    case "__": {
+      const fluid = vwExtrem(calcPercentEz, remMin);
+      return formatClamp(min, fluid, remMax);
+    }
+    // _ = strong
+    case "_": {
+      const finalMin = getFinalMinDiv(remMin, phi);
+      const fluid = vwStrong(calcPercent, sizeRem);
+      return formatClamp(finalMin, fluid, remMax);
+    }
+    // '' = normal (default)
+    case "": {
+      const fluid = vwMedium(calcPercent, sizeRem);
+      return formatClamp(remMin, fluid, remMax);
+    }
+    // - = light (least fluid)
+    case "-": {
+      const finalMin = getFinalMinMulti(remMin, phi);
+      const fluid = vwLight(calcPercent, sizeRem);
+      return formatClamp(finalMin, fluid, remMax);
+    }
+  }
+}
+function generateFontClamp(sizePx, screen, phi, min, max, intensity) {
+  const calcPercent = getPercent(sizePx, screen);
+  const sizeRem = toRem(sizePx);
+  const remMin = getMinRem(calcPercent, min);
+  const remMax = getMaxRem(calcPercent, max);
+  switch (intensity) {
+    // __ = most fluid (uses vw-strong + min/phi)
+    case "__": {
+      const finalMin = getFinalMinDiv(remMin, phi);
+      const fluid = vwStrong(calcPercent, sizeRem);
+      return formatClamp(finalMin, fluid, remMax);
+    }
+    // _ = medium (uses vw-medium + remMin)
+    case "_": {
+      const fluid = vwMedium(calcPercent, sizeRem);
+      return formatClamp(remMin, fluid, remMax);
+    }
+    // '' = least fluid (uses vw-light + min*phi)
+    case "": {
+      const finalMin = getFinalMinMulti(remMin, phi);
+      const fluid = vwLight(calcPercent, sizeRem);
+      return formatClamp(finalMin, fluid, remMax);
+    }
+  }
+}
+
+// src/types.ts
+var PROPERTY_MAP = {
+  // Sizing
+  h: "height",
+  w: "width",
+  "min-h": "min-height",
+  "min-w": "min-width",
+  "max-w": "max-width",
+  "max-h": "max-height",
+  // Padding
+  p: "padding",
+  px: "padding-inline",
+  py: "padding-block",
+  pt: "padding-top",
+  pr: "padding-right",
+  pb: "padding-bottom",
+  pl: "padding-left",
+  // Margin
+  m: "margin",
+  mx: "margin-inline",
+  my: "margin-block",
+  mt: "margin-top",
+  mr: "margin-right",
+  mb: "margin-bottom",
+  ml: "margin-left",
+  // Layout
+  gap: "gap",
+  // Borders
+  rounded: "border-radius"
+};
+var FONT_PROPERTY_MAP = {
+  text: "font-size"
+};
+var SPACING_INTENSITIES = ["__", "_", "", "-"];
+var FONT_INTENSITIES = ["__", "_", ""];
+function resolveConfig(config) {
+  return {
+    sizes: config.sizes,
+    fontSizes: config.fontSizes,
+    screen: config.screen ?? 1440,
+    phi: config.phi ?? 1.61803398875,
+    fontPhi: config.fontPhi ?? 1.3,
+    min: config.min ?? 0.5,
+    fontMin: config.fontMin ?? 0.5,
+    max: config.max ?? 1,
+    ez: config.ez ?? 142.4,
+    defaultIntensity: config.defaultIntensity ?? ""
+  };
+}
+
+// src/generator.ts
+function parseClass(className) {
+  const match = className.match(/^(.+)-\[(\d+(?:\.\d+)?)(px|rem)\]$/);
+  if (!match) return null;
+  const [, prefix, valueStr, unit] = match;
+  const value = parseFloat(valueStr);
+  if (prefix in FONT_PROPERTY_MAP) {
+    const sizePx = unit === "rem" ? value * 16 : value;
+    return {
+      raw: className,
+      prefix,
+      property: FONT_PROPERTY_MAP[prefix],
+      size: sizePx,
+      unit,
+      type: "font"
+    };
+  }
+  if (prefix in PROPERTY_MAP) {
+    const sizePx = unit === "rem" ? value * 16 : value;
+    return {
+      raw: className,
+      prefix,
+      property: PROPERTY_MAP[prefix],
+      size: sizePx,
+      unit,
+      type: "spacing"
+    };
+  }
+  return null;
+}
+function generateVars(config) {
+  const cfg = resolveConfig(config);
+  const lines = [":root {"];
+  for (const size of cfg.sizes) {
+    lines.push(`  /* ---- ${size}px ---- */`);
+    for (const intensity of SPACING_INTENSITIES) {
+      const clamp = generateSpacingClamp(
+        size,
+        cfg.screen,
+        cfg.phi,
+        cfg.min,
+        cfg.max,
+        cfg.ez,
+        intensity
+      );
+      lines.push(`  --${size}${intensity}: ${clamp};`);
+    }
+    lines.push("");
+  }
+  for (const size of cfg.fontSizes) {
+    lines.push(`  /* ---- fs-${size}px ---- */`);
+    for (const intensity of FONT_INTENSITIES) {
+      const clamp = generateFontClamp(
+        size,
+        cfg.screen,
+        cfg.fontPhi,
+        cfg.fontMin,
+        cfg.max,
+        intensity
+      );
+      lines.push(`  --fs-${size}${intensity}: ${clamp};`);
+    }
+    lines.push("");
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+function escapeTwClass(prefix, value, suffix) {
+  return `.${prefix}-\\[${value}\\]${suffix}`;
+}
+function generateClassOverrides(classes, config) {
+  const cfg = resolveConfig({ sizes: [], fontSizes: [], ...config });
+  const lines = [];
+  for (const cls of classes) {
+    const parsed = parseClass(cls);
+    if (!parsed) continue;
+    const valueStr = parsed.unit === "rem" ? `${parsed.size / 16}rem` : `${parsed.size}px`;
+    if (parsed.type === "font") {
+      for (const intensity of FONT_INTENSITIES) {
+        const varRef = `var(--fs-${parsed.size}${intensity})`;
+        const selector = escapeTwClass(parsed.prefix, valueStr, intensity);
+        lines.push(`${selector} { ${parsed.property}: ${varRef} }`);
+      }
+    } else {
+      for (const intensity of SPACING_INTENSITIES) {
+        const varRef = `var(--${parsed.size}${intensity})`;
+        const selector = escapeTwClass(parsed.prefix, valueStr, intensity);
+        lines.push(`${selector} { ${parsed.property}: ${varRef} }`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function generateTheme(config) {
+  const cfg = resolveConfig(config);
+  const lines = ["@theme {"];
+  for (const size of cfg.sizes) {
+    lines.push(`  --spacing-${size}: var(--${size}${cfg.defaultIntensity});`);
+  }
+  if (cfg.sizes.length > 0 && cfg.fontSizes.length > 0) {
+    lines.push("");
+  }
+  const fontSuffix = cfg.defaultIntensity === "-" ? "" : cfg.defaultIntensity;
+  for (const size of cfg.fontSizes) {
+    lines.push(`  --font-size-${size}: var(--fs-${size}${fontSuffix});`);
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+function generateBridge(config) {
+  const sections = [
+    "/* =============================================================",
+    "   EVA CSS \u2014 Tailwind Fluid Bridge",
+    "   Generated by eva-css-for-tailwind",
+    "   ============================================================= */",
+    "",
+    generateVars(config)
+  ];
+  if (!config.classes) {
+    sections.push("");
+    sections.push(generateTheme(config));
+  }
+  if (config.classes && config.classes.length > 0) {
+    sections.push("");
+    sections.push(generateClassOverrides(config.classes, config));
+  }
+  return sections.join("\n");
+}
+
+// src/cli.ts
+var DEFAULT_CONFIG = `module.exports = {
+  sizes: [4, 8, 12, 16, 24, 32, 48, 64, 96, 128],
+  fontSizes: [12, 14, 16, 18, 20, 24, 32, 48],
+  screen: 1440,
+  defaultIntensity: '',
+};
+`;
+function parseArgs(args) {
+  const parsed = {};
+  for (const arg of args) {
+    if (arg.startsWith("--")) {
+      const [key, ...rest] = arg.slice(2).split("=");
+      parsed[key] = rest.length > 0 ? rest.join("=") : true;
+    }
+  }
+  return parsed;
+}
+function loadConfig(cwd) {
+  const candidates = [
+    "eva-tw.config.cjs",
+    "eva-tw.config.js"
+  ];
+  for (const name of candidates) {
+    const configPath = (0, import_path.resolve)(cwd, name);
+    if ((0, import_fs.existsSync)(configPath)) {
+      return require(configPath);
+    }
+  }
+  return null;
+}
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const flags = parseArgs(args.slice(1));
+  const cwd = process.cwd();
+  if (!command || command === "--help" || command === "-h") {
+    console.log(`
+eva-css-for-tailwind \u2014 Fluid design tokens bridge for Tailwind CSS 4
+
+Commands:
+  init        Create eva-tw.config.cjs with defaults
+  generate    Generate bridge.css from config
+
+Options (generate):
+  --sizes="4,8,16,24,32,48"        Override sizes
+  --font-sizes="12,14,16,18,24"    Override font sizes
+  --intensity=<suffix>             Default intensity (__,_,,-)
+  --stdout                         Output to stdout instead of file
+  --out=<path>                     Output file path (default: bridge.css)
+`);
+    return;
+  }
+  if (command === "init") {
+    const configPath = (0, import_path.join)(cwd, "eva-tw.config.cjs");
+    if ((0, import_fs.existsSync)(configPath)) {
+      console.log("eva-tw.config.cjs already exists.");
+      return;
+    }
+    (0, import_fs.writeFileSync)(configPath, DEFAULT_CONFIG, "utf-8");
+    console.log("Created eva-tw.config.cjs");
+    return;
+  }
+  if (command === "generate") {
+    let config = loadConfig(cwd);
+    if (flags["sizes"] && typeof flags["sizes"] === "string") {
+      const sizes = flags["sizes"].split(",").map(Number);
+      config = { ...config, sizes, fontSizes: config?.fontSizes ?? [] };
+    }
+    if (flags["font-sizes"] && typeof flags["font-sizes"] === "string") {
+      const fontSizes = flags["font-sizes"].split(",").map(Number);
+      config = { ...config, sizes: config?.sizes ?? [], fontSizes };
+    }
+    if (flags["intensity"] !== void 0 && typeof flags["intensity"] === "string") {
+      config = {
+        ...config,
+        sizes: config?.sizes ?? [],
+        fontSizes: config?.fontSizes ?? [],
+        defaultIntensity: flags["intensity"]
+      };
+    }
+    if (!config) {
+      console.error('No config found. Run "eva-css-for-tailwind init" first, or pass --sizes and --font-sizes.');
+      process.exit(1);
+    }
+    const css = generateBridge(config);
+    if (flags["stdout"]) {
+      process.stdout.write(css);
+    } else {
+      const outPath = typeof flags["out"] === "string" ? (0, import_path.resolve)(cwd, flags["out"]) : (0, import_path.join)(cwd, "bridge.css");
+      (0, import_fs.writeFileSync)(outPath, css, "utf-8");
+      console.log(`Generated ${outPath}`);
+    }
+    return;
+  }
+  console.error(`Unknown command: ${command}. Use --help for usage.`);
+  process.exit(1);
+}
+main();