anubis-ui 1.3.0 → 1.4.0

package/README.md

@@ -3,13 +3,67 @@
 
 AnubisUI (Autonomous Nominative Utility Based Intuitive Styler) is a Vite plugin that provides dynamic CSS class generation based on configuration files. It automatically generates CSS rules by scanning your source files and mapping utility classes to their corresponding styles.
 
+## 🚀 Quick Start
+
+AnubisUI automatically generates the CSS classes you need, simply by using them in your code. No need to write CSS manually!
+
+### Concrete Example
+
+**In your Vue/HTML component:**
+```html
+<template>
+  <div class="bg-primary-low text-primary rounded-lg smooth hover:shadow-accent-wide">
+    <button class="bg-accent text-primary size-lg weight-bold hover:bg-accent-high">
+      Click me
+    </button>
+  </div>
+</template>
+```
+
+**AnubisUI automatically generates the CSS:**
+```css
+.bg-primary-low { background: var(--primary-low) !important; }
+.text-primary { color: var(--primary) !important; }
+.rounded-lg { border-radius: 12px !important; }
+.smooth { transition-duration: 0.1s !important; }
+.hover\:shadow-accent-wide:hover { box-shadow: 0px 0px 10px 2px var(--accent) !important; }
+/* ... and much more */
+```
+
+### Key Benefits
+
+✅ **Zero CSS to write** - Use classes, AnubisUI generates the CSS\
+✅ **Light/dark themes** - Automatic support with CSS variables\
+✅ **Hot-reload** - Classes are detected and generated on the fly\
+✅ **Optimized** - Only used classes are generated\
+✅ **Customizable** - Configure your colors, variations and presets
+
+### Typical Use Cases
+
+```html
+<!-- Card with border and shadow on hover -->
+<div class="bg-neutral-lowest border-neutral-thin rounded-lg hover:shadow-primary-wide smooth">
+  <h2 class="text-primary size-2xl weight-bold">Title</h2>
+  <p class="text-neutral-medium size-md">Description</p>
+</div>
+
+<!-- Button with states -->
+<button class="bg-success text-primary rounded smooth hover:bg-success-high">
+  Validate
+</button>
+
+<!-- Badge with inner borders -->
+<span class="bg-warning-lowest inner-border-warning-thin rounded-full text-warning-high size-sm">
+  New
+</span>
+```
+
 > __⚠️ IMPORTANT__ - Dynamic classes like `` `bg-primary-${props.bg}` `` **will NOT work**
 >
 > Classes must be **EXPLICITLY written** in the code to allow the extraction to work correctly. The plugin uses regex pattern matching on your source files.
 >
 > Use the `force` configuration to generate specific classes even if they're not present in the code.
 
-
 ## Table of Contents
 1. [Features](#features)
 2. [Installation](#installation)
@@ -38,6 +92,8 @@ AnubisUI (Autonomous Nominative Utility Based Intuitive Styler) is a Vite plugin
 - 🔍 Smart class detection and parsing
 - 📦 CSS variable generation for reusable values
 - ⚙️ Export variations as CSS variables for custom styling
+- 🎛️ SCSS tokens generation for global color access
+- 🔧 Quasar/global variable overrides from utility defaults
 
 # Installation
 
@@ -65,20 +121,27 @@ css: [
 ```
 <sup>quasar.config.js</sup>
 
-4. Colors are automatically defined from the configuration
+4. AnubisUI generates the following files automatically in `src/css/`:
+   - `_anubis.scss` - Main stylesheet with all generated rules
+   - `anubis/_mixins.scss` - SCSS mixins for color handling
+   - `anubis/_tokens.scss` - Color token variables (`$primary`, `$primary-dark`, etc.)
+   - `anubis/_overrides.scss` - Quasar variable overrides from utilities
+   - `quasar.variables.scss` - Auto-injected imports for tokens and overrides
+
+5. Colors are automatically defined from the configuration
    - AnubisUI generates CSS variables for all colors defined in `colors.config.json`
    - Colors support light/dark themes automatically
    - Each color is exposed as a CSS variable: `--primary`, `--secondary`, etc.
    - Pre-defined color levels: `lowest`, `lower`, `low`, `medium`, `high`, `higher`, `highest`
 
-5. Start adding classes to your HTML files
+6. Start adding classes to your .vue files
 ```html
 <div class="bg-primary-low border-neutral-medium hover:shadow-wide rounded-lg" />
-<button class="bg-accent text-text-invert size-lg weight-bold smooth">Click me</button>
+<button class="bg-accent text-primary size-lg weight-bold smooth">Click me</button>
 ```
-<sup>any .html file</sup>
+<sup>any .vue file</sup>
 
-6. Enjoy
+7. Enjoy
 
 > **Note**: Generated CSS variables (from colors and export) are available for custom styling:
 > ```css
@@ -89,6 +152,16 @@ css: [
 > }
 > ```
 
+> **SCSS Tokens**: Color tokens are also available as SCSS variables for compile-time usage:
+> ```scss
+> @use "anubis/_tokens.scss" as tokens;
+> 
+> .custom-class {
+>   border-color: tokens.$primary;
+>   background: tokens.$accent-dark;
+> }
+> ```
+
 ## Configuration
 AnubisUI uses several configuration files located in the `src/config` directory:
 <br />
@@ -96,33 +169,29 @@ To override default configuration, add a `anubis.config.json` in project root fo
 >Overriding completly replaces default configuration. You need to copy/paste it and add yours if you want to keep the default too.
 <br />
 
-For every config you want to change, add the corresponding section in your config file:
+Only the sections you want to override need to be included - other sections will use default values.\
+For every config you want to change, add the corresponding section in your config file
+<br />
 
+### Some examples:
 ```js
 {
   // files.config.json
   "files": {
     "targets": ["/.vue"],
-    "ignore": []
+    "ignore": ["**/*specificFile.vue"]
   },
 
   // colors.config.json
-  "colors": ["primary", "secondary"],
-
-  // states.config.json
-  "states": ["hover"],
+  "colors": ["primary", "secondary", "..."],
 
-  // qol.config.json
-  "qol": [
+  // utilities.config.json
+  "utilities": [
     {
       "prefix": "bg",
       "declaration": "background: ${color}",
       "export": "all"
     }
-  ],
-
-  // presets.config.json
-  "presets": [
     {
       "prefix": "border",
       "declaration": "border-width: ${value} !important; border-color: ${color} !important; border-style: solid;",
@@ -130,7 +199,7 @@ For every config you want to change, add the corresponding section in your confi
         "default": "4px",
         "thin": "2px"
       },
-      "export": "variation"
+      "export": "variations"
     },
     {
       "prefix": "rounded",
@@ -145,20 +214,13 @@ For every config you want to change, add the corresponding section in your confi
   // force.config.json
   "force": [
     "bg-primary-10",
-    "bg-primary-20",
-    "bg-primary-30"
+    "hover:border-neutral-thin",
+    "text-danger"
   ]
 }
 ```
 <sup>anubis.config.json (example)</sup>
 
-Only the sections you want to override need to be included - other sections will use default values. Not every
-> Presets is still unstable, use at your own risks
-<br />
-You __MUST__ use the exact same [presets](#presets-presetsconfigjson) names syntax to keep it working, but variations key/values can change.
-<br />
-Copy-paste is recommanded
-
 ---
 ### Colors (`colors.config.json`)
 Define your color palette with light/dark theme support. Colors can be defined in three different ways:
@@ -173,7 +235,7 @@ Define your color palette with light/dark theme support. Colors can be defined i
      "dark": "#1a94db"
    }
    ```
-   Generates color variables for both light and dark themes with opacity variations.
+   <sup>Generates color variables for both light and dark themes with opacity variations.</sup>
 
 2. **Light theme only** - Define only `light` value:
    ```json
@@ -181,7 +243,7 @@ Define your color palette with light/dark theme support. Colors can be defined i
      "light": "#ff00ff"
    }
    ```
-   Generates color variables only for light theme. Dark theme will not have this color defined.
+   <sup>Generates color variables only for light theme. Dark theme will not have this color defined.</sup>
 
 3. **Dark theme only** - Define only `dark` value:
    ```json
@@ -189,9 +251,30 @@ Define your color palette with light/dark theme support. Colors can be defined i
      "dark": "#00ffff"
    }
    ```
-   Generates color variables only for dark theme. Light theme will not have this color defined.
-
-Full palette includes: `primary`, `secondary`, `accent`, `neutral`, `success`, `warning`, `danger` with levels: `lowest`, `lower`, `low`, `medium`, `high`, `higher`, `highest`.
+   <sup>Generates color variables only for dark theme. Light theme will not have this color defined.</sup>
+
+Full palette includes:\
+<b>Colors</b>
+<ul>
+  <li>primary</li>
+  <li>secondary</li>
+  <li>accent</li>
+  <li>neutral</li>
+  <li>success</li>
+  <li>warning</li>
+  <li>danger</lu>
+</ul>
+
+<b>Levels</b>
+<ul>
+  <li>lowest <i>- lighest</i></li>
+  <li>lower</li>
+  <li>low</li>
+  <li>medium</li>
+  <li>high</li>
+  <li>higher</li>
+  <li>highest <i>- darkest</i></li>
+</ul>
 
 **Color naming convention**: Colors are automatically converted to CSS variables as `--{color-name}`. Use semantic color levels to ensure proper theme adaptation.
 
@@ -220,27 +303,20 @@ You can add multiple glob patterns to scan different file types:
 ```
 
 ---
-### Presets (`presets.config.json`)
-Configure common style presets that require both color and variation values.
+### Utilities (`utilities.config.json`)
+Configure all utility classes. This includes both color-based utilities and standalone utilities.
 
-**[View default presets config →](./src/config/presets.config.json)**
+**[View default utilities config →](./src/config/utilities.config.json)**
 
-> **Note**: If overriding in your config, the default key/value are __REQUIRED__
+**Color-based utilities** (require a color):
+- `bg` - Background colors
+- `text` - Text colors
+- `border` - Border with width variations and color
+- `inner-border` - Inset box shadow with width variations and color
+- `shadow` - Box shadow with spread variations and color
 
-Presets include:
-- `bg` - Background colors (no variations)
-- `text` - Text colors (no variations)
-- `border` - Border with width variations
-- `inner-border` - Inset box shadow with width variations
-- `shadow` - Box shadow with spread variations
 
----
-### Quality of Life (`qol.config.json`)
-Define simple style rules that can have variations but don't require color values. These are CSS declarations that work independently.
-
-**[View default QoL config →](./src/config/qol.config.json)**
-
-QoL utilities include:
+**Standalone utilities** (no color required):
 - `blur` - Backdrop filter blur effect
 - `smooth` - Transition duration
 - `rounded` - Border radius
@@ -251,15 +327,38 @@ QoL utilities include:
 
 **Configuration options**:
 1. `prefix` - The class name prefix
-2. `declaration` - CSS rule using `${value}` placeholder for variations
+2. `declaration` - CSS rule using `${value}` and/or `${color}` placeholders
 3. `variations` - Key-value pairs of variation names and their CSS values
 4. `export` (optional) - Controls how variations are exported as CSS variables
+5. `overrides` (optional) - List of Quasar/global SCSS variables to override with the default variation
 
 **The `export` flag**:
-- `export: "variation"` → Generates CSS variables every variations
+- `export: "variations"` → Generates CSS variables for every variation
 - `export: "all"` → Generates classes for every possible color
 - These can be used in custom CSS: `font-size: var(--size-xl)`
 
+**The `overrides` option**:
+Override Quasar or global SCSS variables with the `default` variation value:
+```json
+{
+  "prefix": "border",
+  "declaration": "border-width: ${value}; border-color: ${color}; border-style: solid;",
+  "overrides": [
+    "generic-border-radius",
+    "button-border-radius"
+  ],
+  "variations": {
+    "default": "4px",
+    "thin": "2px"
+  }
+}
+```
+This generates in `anubis/_overrides.scss`:
+```scss
+$generic-border-radius: 4px;
+$button-border-radius: 4px;
+```
+
 **Color support**:
 - Use `${color}` in declaration to indicate the utility requires a color
 - Colors are automatically injected as CSS variables: `var(--{color})`
@@ -313,12 +412,12 @@ These utilities require a color from your config:
 
 Examples:
 ```html
-<div class="bg-primary-low text-text-invert">Blue background with inverted text</div>
+<div class="bg-primary-low text-primary">Blue background with primary text</div>
 <div class="bg-success-lowest text-success-highest">Success themed element</div>
 ```
 
-### Preset Variations (Color + Size)
-Presets combine colors with size variations:
+### Utility Variations (Color + Size)
+Utilities can combine colors with size variations:
 
 - `border-{color}-{variation}` - Border with color and width
   - Variations: `thinest`, `thiner`, `thin`, `default`, `thick`, `thicker`, `thickest`, `node`
@@ -373,7 +472,7 @@ Examples:
 
 ## Prefix/Declaration Relations
 
-### Color Presets
+### Color-based Utilities
 | Prefix       | CSS Declaration                                                                 |
 |--------------|---------------------------------------------------------------------------------|
 | bg           | `background: var(--{color}) !important;`                                        |
@@ -393,37 +492,54 @@ Examples:
 | size     | `font-size: {value} !important;`              |
 | weight   | `font-weight: {value} !important;`            |
 
-**Note**: When `export: "variation"` is set, `{value}` becomes `var(--{prefix}-{variation})` instead of the direct value.
+**Note**: When `export: "variations"` is set, `{value}` becomes `var(--{prefix}-{variation})` instead of the direct value.
 
 ## Architecture
 
 ### Build Process Flow
 
+The build process is orchestrated by `src/tools/main.ts` which runs the following steps in sequence:
+
 1. **Configuration Initialization** (`src/tools/config.tool.ts`)
    - Loads default configs from `src/config/*.config.json`
    - Merges with user's `anubis.config.json` if present
    - User config completely replaces default sections (no deep merge)
 
-2. **File Scanning** (`src/tools/fileStuff/file.tools.ts`)
-   - Scans files matching glob patterns from `files.config.json`
-   - Concurrent file reading with configurable limit (default: 10 files)
+2. **Mixins Generation** (`src/tools/output/css.output.ts`)
+   - Generates SCSS mixins for color handling (light/dark theme support)
+   - Outputs to `src/css/anubis/_mixins.scss`
+
+3. **Tokens Generation** (`src/tools/mapping/mapColors.ts`)
+   - Maps all colors from config into SCSS token variables
+   - Generates `$colorname`, `$colorname-light`, `$colorname-dark` variables
+   - Outputs to `src/css/anubis/_tokens.scss`
+
+4. **Overrides Generation** (`src/tools/mapping/mapUtilities.ts`)
+   - Maps utilities with `overrides` property to SCSS variable declarations
+   - Allows overriding Quasar/global variables with utility defaults
+   - Outputs to `src/css/anubis/_overrides.scss`
 
-3. **Class Extraction** (`src/tools/extraction/extractClasses.ts`)
-   - Builds dynamic regex from config (states, presets, qol prefixes)
+5. **Quasar Variables Injection** (`src/tools/fileStuff/quasar-variables.file.ts`)
+   - Automatically adds `@use` imports for tokens and overrides
+   - Updates `src/css/quasar.variables.scss`
+
+6. **Class Extraction** (`src/tools/extraction/extractClasses.ts`)
+   - Scans files matching glob patterns from `files.config.json`
+   - Builds dynamic regex from config (states, utilities prefixes)
    - Extracts classes matching pattern: `(state:)?(prefix-)(-?(color|variation))?`
-   - Merges with forced classes from config
+   - Merges with forced classes and exported classes from config
    - Deduplicates and returns unique classes
 
-4. **Rule Generation** (`src/tools/mapping/mapClassIntoRule.ts`)
+7. **Rule Generation** (`src/tools/mapping/mapClassIntoRule.ts`)
    - Parses each class to identify state, prefix, color, and variation
    - Validates color existence in config
-   - Handles preset variations (direct values or CSS variables)
+   - Handles utility variations (direct values or CSS variables)
    - Generates CSS rules with proper selectors and declarations
    - Collects variants for CSS variable export
 
-5. **CSS Output** (`src/tools/fileStuff/css.file.ts`)
+8. **CSS Output** (`src/tools/extraction/extractClasses.ts`)
    - Generates color CSS variables with light/dark theme support
-   - Generates variation CSS variables (from `export: "variation"` or `export: "all"`)
+   - Generates variation CSS variables (from `export: "variations"` or `export: "all"`)
    - Writes final CSS rules
    - Outputs to `src/css/_anubis.scss`
 
@@ -436,10 +552,14 @@ The plugin (`index.js`) provides:
 
 ### Core Components
 
-- **Config System**: Manages configuration loading and merging
-- **Class Extractor**: Regex-based pattern matching for class detection
-- **Rule Mapper**: Complex parsing logic for class-to-CSS conversion
-- **CSS Generator**: Generates variables and rules with proper formatting
+- **Main Orchestrator** (`main.ts`): Coordinates all initialization steps with timing
+- **Config System** (`config.tool.ts`): Manages configuration loading and merging
+- **Class Extractor** (`extractClasses.ts`): Regex-based pattern matching for class detection
+- **Color Mapper** (`mapColors.ts`): Generates tokens and mixin declarations from colors
+- **Utilities Mapper** (`mapUtilities.ts`): Generates SCSS overrides from utilities config
+- **Rule Mapper** (`mapClassIntoRule.ts`): Complex parsing logic for class-to-CSS conversion
+- **CSS Generator** (`css.output.ts`): Generates variables, mixins and rules with proper formatting
+- **File Tools** (`file.tools.ts`): Centralized file I/O with concurrency control
 
 ### File Structure
 ```
@@ -447,16 +567,28 @@ The plugin (`index.js`) provides:
 ├── src/
 │   ├── config/                     # Default configuration files
 │   │   ├── colors.config.json      # Color palette (light/dark themes)
-│   │   ├── presets.config.json     # Color-based utilities
-│   │   ├── qol.config.json         # Standalone utilities
+│   │   ├── utilities.config.json   # All utility classes (bg, text, border, etc.)
 │   │   ├── states.config.json      # State modifiers
-│   │   └── files.config.json       # File scan patterns
+│   │   ├── files.config.json       # File scan patterns
+│   │   └── force.config.json       # Force specific classes
+│   ├── css/                        # Generated CSS output (in user project)
+│   │   ├── _anubis.scss            # Main generated stylesheet
+│   │   ├── quasar.variables.scss   # Quasar variables with injected imports
+│   │   └── anubis/
+│   │       ├── _mixins.scss        # SCSS mixins for color handling
+│   │       ├── _tokens.scss        # Color token variables
+│   │       └── _overrides.scss     # Quasar/global variable overrides
 │   ├── interfaces/                 # TypeScript type definitions
 │   └── tools/
 │       ├── extraction/             # Class extraction logic
 │       ├── fileStuff/              # File I/O operations
 │       ├── mapping/                # Class-to-CSS mapping
+│       │   ├── mapClassIntoRule.ts # Class to CSS rule conversion
+│       │   ├── mapColors.ts        # Color to tokens/mixins mapping
+│       │   └── mapUtilities.ts     # Utilities to overrides mapping
+│       ├── output/                 # CSS output generation
 │       ├── config.tool.ts          # Configuration loader
+│       ├── main.ts                 # Main orchestration entry point
 │       └── logger.ts               # Logging utilities
 └── index.js                        # Vite plugin entry point
 ```

package/dist/interfaces/color.interface.d.ts

@@ -0,0 +1,8 @@
+export interface IColor {
+    [colorName: string]: {
+        /** @optional Hexadecimal light color code - doesn't include opacity */
+        light?: string[7];
+        /** @optional Hexadecimal dark color code - doesn't include opacity */
+        dark?: string[7];
+    };
+}

package/dist/interfaces/color.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/{src/interfaces/config.interface.ts → dist/interfaces/config.interface.d.ts}

@@ -1,14 +1,11 @@
 import { IColor } from './color.interface';
 import { IUtility } from './preset.interface';
 import { IFileConfig } from './files.interface';
-
 export interface IEnvConfig {
     utilities: IUtility[];
     files: IFileConfig;
-
     /** User-given classes to force the css rule creation */
     force: string[];
-
     colors: IColor;
     states: string[];
     [key: string]: any;

package/dist/interfaces/config.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interfaces/files.interface.d.ts

@@ -0,0 +1,4 @@
+export interface IFileConfig {
+    targets: string | string[];
+    ignore: string[];
+}

package/dist/interfaces/files.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/{src/interfaces/preset.interface.ts → dist/interfaces/preset.interface.d.ts}

@@ -1,27 +1,23 @@
 export interface IVariation {
     [key: string]: string;
 }
-
 export interface IUtility {
-    // [key: string]: string
     prefix: string;
     declaration: string;
-
     /** When true, class can be called without variation, creating a rule with default variation */
     standalone?: boolean;
-
     /**
      * Controls how variations are exported as SCSS variables:
      * - "variation": export every variations
      * - "all": export every possible color class (utility prefix + every colors)
      * - undefined: do not export variations
      */
-    'export'?: 'variations' | 'all';
-
+    export?: 'variations' | 'all';
+    /** Override default global variables with the "default" variation if existing */
+    overrides?: string[];
     /** List of every possible variations */
     variations: IVariation;
 }
-
 export interface IRuleInfo {
     selector: string;
     declaration: string;

package/dist/interfaces/preset.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/tools/config.tool.d.ts

@@ -0,0 +1,4 @@
+import { IEnvConfig } from '../interfaces/config.interface';
+declare const config: IEnvConfig;
+declare const init: () => IEnvConfig;
+export { init, config };

package/dist/tools/config.tool.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = exports.init = void 0;
+const config_file_1 = require("./fileStuff/config.file");
+const logger_1 = require("./logger");
+const color_validation_1 = require("./validation/color.validation");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const anubisConfigFolder = path_1.default.join(__dirname, '..', '..', 'src', 'config');
+const anubisConfigFiles = [
+    'utilities',
+    'files',
+    'colors',
+    'states',
+    'force',
+];
+const config = {
+    utilities: [],
+    force: [],
+    files: { targets: [], ignore: [] },
+    colors: {},
+    states: [],
+};
+exports.config = config;
+const init = () => {
+    (0, config_file_1.readUserConfigFile)();
+    (0, config_file_1.checkUserConfigFile)(anubisConfigFiles);
+    for (const file of anubisConfigFiles) {
+        let configToUse = null;
+        if (config_file_1.userConfig && config_file_1.userConfig[file]) {
+            (0, logger_1.log)(`${file} config found, overriding default.`);
+            configToUse = config_file_1.userConfig[file];
+        }
+        else {
+            const filePath = path_1.default.join(anubisConfigFolder, `${file}.config.json`);
+            const fileExists = fs_1.default.existsSync(filePath);
+            if (!fileExists) {
+                continue;
+            }
+            const configContent = fs_1.default.readFileSync(filePath, { encoding: 'utf-8' });
+            if (!configContent) {
+                continue;
+            }
+            configToUse = JSON.parse(configContent);
+        }
+        config[file] = configToUse;
+        switch (file) {
+            case 'colors':
+                (0, color_validation_1.validateColors)(config.colors);
+                break;
+            case 'force':
+                const forceClasses = config_file_1.userConfig === null || config_file_1.userConfig === void 0 ? void 0 : config_file_1.userConfig['force'];
+                if (forceClasses === null || forceClasses === void 0 ? void 0 : forceClasses.length) {
+                    (0, logger_1.log)(`Forcing the creation of ${forceClasses === null || forceClasses === void 0 ? void 0 : forceClasses.length} classes`);
+                }
+                break;
+        }
+    }
+    return config;
+};
+exports.init = init;

package/dist/tools/extraction/extractClasses.d.ts

@@ -0,0 +1,5 @@
+/** Fetch vue file based on config target patterns */
+export declare const init: () => Promise<string>;
+/** Get all variations from utilities with export: "variations" */
+export declare const getExportedVariations: () => Record<string, string>;
+export declare const handleVariations: (extractedVariations: Record<string, string>) => string;