gullu-css 1.0.0

package/README.md

@@ -0,0 +1,129 @@
+# CleanCSS Engine
+
+A blazing-fast, **zero-build** runtime utility CSS engine. 
+
+Instead of waiting for Webpack or Vite to compile hundreds of gigabytes of node modules, **CleanCSS Engine operates entirely in the browser at runtime**. By leveraging modern browser JavaScript, CleanCSS reads your utility classes natively and injects styles dynamically. No complicated configurations. No PostCSS process. Just instantly applied styles.
+
+## 🚀 Features
+- **Zero Build Step:** Runs 100% in browser JS. No build pipelines.
+- **O(N) Single-Pass Performance:** Ultra-optimized scanner parses the DOM once.
+- **200+ Semantic Tokens:** Out of the box Oklch color palettes, spacing systems, and scale tiers.
+- **Arbitrary JIT Values:** On-the-fly values using square bracket syntax (e.g., `text-[35px]`). 
+- **Lightweight Core:** Modularized rulesets (Layout, Typography, Backgrounds, Effects, etc.).
+
+---
+
+## 📦 Installation
+
+To install via npm:
+```bash
+npm install clean-css-engine
+```
+
+*(Note: Replace `clean-css-engine` with the exact scoped name you push to npm).*
+
+---
+
+## 🛠️ Usage
+
+Because it's an ES6 module, you can easily drop it into standard HTML, React, Vue, Next.js, or any modern framework. 
+
+### Vanilla JS / HTML
+```html
+<!-- Inside index.html -->
+<script type="module">
+    import { initEngine } from "./node_modules/clean-css-engine/main.js";
+    
+    // Call the engine to compile all styles
+    initEngine();
+</script>
+
+<!-- Build interfaces instantly! -->
+<div class="bg-emerald-500 text-white p-6 rounded-lg shadow-lg d-flex items-center gap-4">
+    <h1 class="text-2xl font-bold">Hello World!</h1>
+</div>
+```
+
+### React / Next.js
+You can trigger the engine during page mount or context initialization:
+```jsx
+import { useEffect } from 'react';
+import { initEngine } from 'clean-css-engine';
+
+export default function App() {
+  useEffect(() => {
+    // Run the engine once the DOM mounts
+    initEngine();
+  }, []);
+
+  return (
+    <div className="bg-slate-900 w-screen h-screen d-flex items-center justify-center">
+        <h1 className="text-4xl font-bold text-emerald-400">Powered by CleanCSS</h1>
+    </div>
+  );
+}
+```
+
+---
+
+## 📖 API & Feature Reference
+
+Below is a complete reference of the modules and utility classes processed by CleanCSS:
+
+### 1. Typography
+Control all text styling properties with simple prefixes.
+- **Size Scale:** `text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl` ... `text-6xl`.
+- **Colors:** Support for `text-white`, `text-gray`, and scales like `text-emerald-500` or `text-blue-700`.
+- **Weight:** `font-medium`, `font-bold`, `font-black`.
+- **Alignment:** `text-center`, `text-right`, `text-left`.
+
+### 2. Layout & Flex
+Handle responsive positioning and flexbox models seamlessly.
+- **Display Nodes:** `d-flex`, `d-inline-flex`.
+- **Direction:** `flex-col`, `flex-row`.
+- **Alignment (Items):** `items-start`, `items-center`, `items-end`.
+- **Alignment (Content):** `justify-start`, `justify-center`, `justify-between`, `justify-around`.
+- **Spacing:** `gap-1`, `gap-4`, `gap-8`.
+- **Wrap:** `flex-wrap`, `flex-nowrap`.
+
+### 3. Box Model & Spacing
+Precise control over margins, padding, sizing, and borders.
+- **Padding:** `p-4`, `pt-2`, `pb-8`, `px-4`, `py-6`.
+- **Margin:** `m-4`, `mt-2`, `mb-8`, `mx-auto`.
+- **Scale:** Spacing values map evenly from 0px up to 96px (`p-0` to `p-24`).
+- **Sizing:** `w-full`, `h-screen`, `w-64`, `max-w-lg`.
+- **Radius:** `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-full`.
+- **Borders:** `border-2`, `border-emerald-500`.
+
+### 4. Backgrounds & Colors
+Paint any container with deep color system integration.
+- **Standard Colors:** `bg-emerald-500`, `bg-slate-900`, `bg-blue-600`.
+- **Special Values:** `bg-white`, `bg-black`, `bg-transparent`.
+- **Color Scale:** Ranges horizontally from `50` (lightest) to `950` (darkest). All predefined palettes use perceptual color modeling.
+
+### 5. Images 
+Style responsive web images seamlessly. 
+- **Background Size/Position:** `bg-cover`, `bg-contain`, `bg-auto`, `bg-center`, `bg-top`.
+- **Object Fits (for Native Images):** `object-cover`, `object-contain`, `object-center`.
+- **Direct URLs:** Embed background images flawlessly via `bg-[url('https://link.com/photo.jpg')]`.
+
+### 6. Effects
+Bring interactions alive.
+- **Shadows:** `shadow-sm`, `shadow-md`, `shadow-lg` (maps high fidelity CSS box-shadows).
+- **Interactivity:** `cursor-pointer`, `transition`, `opacity-50`, `opacity-75`.
+- **Overflow:** `overflow-hidden`, `overflow-visible`.
+
+### 7. Arbitrary Constraints JIT `[...]`
+Sometimes you need to escape the token system. Whenever that happens, cleanly use square bracket arbitrary values.
+- **Custom Texts:** `text-[35px]`
+- **Custom Colors:** `bg-[#ff6b6b]`, `text-[oklch(65%_0.2_145)]`
+- **Dynamic Variables:** `bg-(--brand-color)`
+
+---
+
+## ⚙️ Architecture Core
+CleanCSS is built to be maximally performant at runtime. When `initEngine()` runs, it gathers the DOM layer into `document.querySelectorAll("[class]")` and iterates through standard HTML classes mapping directly up to our array of isolated rule tests (located in cleanly decoupled feature files: `layout.js`, `typography.js`, etc.). If a rule hits dynamically, it instantly overrides the element's inline `.style`, avoiding reflow latency whenever feasible.
+
+---
+### Building the Future of Styling.
+*Developed for unparalleled runtime simplicity.*

package/appliers/background.js

@@ -0,0 +1,27 @@
+import { bgColors } from "../values.js";
+
+export function applyBackground(el, cls) {
+  // Arbitrary background color
+  if (cls.startsWith("bg-[") && cls.endsWith("]")) {
+    const value = cls.slice(4, -1).trim();
+    if (!value.startsWith("url(") && !value.match(/gradient\(/)) {
+      el.style.backgroundColor = value;
+      return true;
+    }
+  }
+
+  // CSS Variables
+  if (cls.startsWith("bg-(") && cls.endsWith(")")) {
+    const varName = cls.slice(4, -1).trim();
+    el.style.backgroundColor = `var(${varName})`;
+    return true;
+  }
+
+  // Standard colors
+  if (bgColors[cls]) {
+    el.style.backgroundColor = bgColors[cls];
+    return true;
+  }
+
+  return false;
+}

package/appliers/boxModel.js

@@ -0,0 +1,58 @@
+import { boxSizing, spacing, sizing, borderRadius, borderWidth, borderColor } from "../values.js";
+
+export function applyBoxModel(el, cls) {
+  // 1. Box Sizing
+  if (boxSizing[cls]) { el.style.boxSizing = boxSizing[cls]; return true; }
+
+  // 2. Spacing
+  const pmMap = { p: "padding", m: "margin" };
+  const sideMap = { t: "Top", b: "Bottom", l: "Left", r: "Right" };
+
+  for (const [pre, prop] of Object.entries(pmMap)) {
+      if (cls.startsWith(`${pre}-`)) {
+          const key = cls.split("-").pop();
+          if (spacing[key]) { el.style[prop] = spacing[key]; return true; }
+          else if (!isNaN(key)) { el.style[prop] = key + "px"; return true; }
+      }
+      for (const [s, side] of Object.entries(sideMap)) {
+          if (cls.startsWith(`${pre}${s}-`)) {
+              const key = cls.split("-").pop();
+              if (spacing[key]) { el.style[`${prop}${side}`] = spacing[key]; return true; }
+              else if (!isNaN(key)) { el.style[`${prop}${side}`] = key + "px"; return true; }
+          }
+      }
+  }
+
+  // 3. Width and Height
+  if (sizing[cls]) {
+      if (cls.startsWith("w-")) el.style.width = sizing[cls];
+      if (cls.startsWith("h-")) el.style.height = sizing[cls];
+      if (cls.startsWith("max-w-")) el.style.maxWidth = sizing[cls];
+      return true;
+  }
+  if (cls.startsWith("w-")) {
+      const val = cls.split("-").pop();
+      el.style.width = isNaN(val) ? val : val + "px";
+      return true;
+  }
+  if (cls.startsWith("h-")) {
+      const val = cls.split("-").pop();
+      el.style.height = isNaN(val) ? val : val + "px";
+      return true;
+  }
+
+  // 4. Borders & Radius
+  if (borderRadius[cls]) { el.style.borderRadius = borderRadius[cls]; return true; }
+  if (borderWidth[cls]) {
+    el.style.borderWidth = borderWidth[cls];
+    el.style.borderStyle = "solid";
+    return true;
+  }
+  if (borderColor[cls]) {
+    el.style.borderColor = borderColor[cls];
+    if (!el.style.borderStyle) el.style.borderStyle = "solid";
+    return true;
+  }
+
+  return false;
+}

package/appliers/effects.js

@@ -0,0 +1,18 @@
+import { shadows, miscEffects } from "../values.js";
+
+export function applyEffects(el, cls) {
+  if (shadows[cls]) {
+    el.style.boxShadow = shadows[cls];
+    return true;
+  }
+
+  if (miscEffects[cls]) {
+    if (cls.includes("transition")) el.style.transition = miscEffects[cls];
+    else if (cls.includes("cursor")) el.style.cursor = miscEffects[cls];
+    else if (cls.includes("opacity")) el.style.opacity = miscEffects[cls];
+    else if (cls.includes("overflow")) el.style.overflow = miscEffects[cls];
+    return true;
+  }
+
+  return false;
+}

package/appliers/image.js

@@ -0,0 +1,30 @@
+import { objectFits, objectPositions, bgSizes, bgRepeats, bgPositions } from "../values.js";
+
+export function applyImage(el, cls) {
+  if (cls.startsWith("bg-[url(") && cls.endsWith(")]")) {
+    const urlStr = cls.slice(4, -1).trim();
+    el.style.backgroundImage = urlStr;
+    return true;
+  }
+  if (objectFits[cls]) {
+    el.style.objectFit = objectFits[cls];
+    return true;
+  }
+  if (objectPositions[cls]) {
+    el.style.objectPosition = objectPositions[cls];
+    return true;
+  }
+  if (bgSizes[cls]) {
+    el.style.backgroundSize = bgSizes[cls];
+    return true;
+  }
+  if (bgRepeats[cls]) {
+    el.style.backgroundRepeat = bgRepeats[cls];
+    return true;
+  }
+  if (bgPositions[cls]) {
+    el.style.backgroundPosition = bgPositions[cls];
+    return true;
+  }
+  return false;
+}

package/appliers/layout.js

@@ -0,0 +1,27 @@
+import { display, layoutDirection, flexWrap, alignment, spacing } from "../values.js";
+
+export function applyLayout(el, cls) {
+  if (display[cls]) {
+    el.style.display = display[cls];
+    return true;
+  }
+  if (layoutDirection[cls]) {
+    el.style.flexDirection = layoutDirection[cls];
+    return true;
+  }
+  if (flexWrap[cls]) {
+    el.style.flexWrap = flexWrap[cls];
+    return true;
+  }
+  if (alignment[cls]) {
+    if (cls.includes("items-")) el.style.alignItems = alignment[cls];
+    else if (cls.includes("justify-")) el.style.justifyContent = alignment[cls];
+    return true;
+  }
+  if (cls.startsWith("gap-")) {
+    const key = cls.split("-").pop();
+    if (spacing[key]) { el.style.gap = spacing[key]; return true; }
+    else if (!isNaN(key)) { el.style.gap = key + "px"; return true; }
+  }
+  return false;
+}

package/appliers/position.js

@@ -0,0 +1,20 @@
+import { positions, spacing } from "../values.js";
+
+export function applyPosition(el, cls) {
+  if (positions[cls]) {
+    el.style.position = positions[cls];
+    return true;
+  }
+  
+  const offsets = ["top", "right", "bottom", "left"];
+  for (const side of offsets) {
+    if (cls.startsWith(`${side}-`)) {
+      const val = cls.split("-").pop();
+      if (spacing[val]) { el.style[side] = spacing[val]; }
+      else if (!isNaN(val)) { el.style[side] = val + "px"; }
+      else { el.style[side] = val; }
+      return true;
+    }
+  }
+  return false;
+}

package/appliers/typography.js

@@ -0,0 +1,44 @@
+import { textSizing, textColor, typographyMisc } from "../values.js";
+
+export function applyTypography(el, cls) {
+  // 1. Arbitrary values: text-[35px]
+  if (cls.startsWith("text-[") && cls.endsWith("]")) {
+    const value = cls.slice(6, -1).trim();
+    if (/^\d+(px|rem|em|vh|vw|%)$/.test(value)) {
+      el.style.fontSize = value;
+      return true;
+    }
+  }
+
+  // 2. Font Sizing & Typography Misc
+  if (textSizing[cls]) {
+    el.style.fontSize = textSizing[cls];
+    return true;
+  } 
+  
+  if (typographyMisc[cls]) {
+    if (cls.includes("text-")) el.style.textAlign = typographyMisc[cls];
+    else if (cls.includes("font-")) el.style.fontWeight = typographyMisc[cls];
+    return true;
+  }
+
+  // 3. Text Color
+  if (textColor[cls]) {
+    el.style.color = textColor[cls];
+    return true;
+  } 
+  
+  if (cls.startsWith("text-")) {
+    const key = cls.replace("text-", "");
+    if (textSizing[key]) { 
+      el.style.fontSize = textSizing[key]; 
+      return true; 
+    }
+    if (textColor[key]) { 
+      el.style.color = textColor[key]; 
+      return true; 
+    }
+  }
+
+  return false;
+}