@gesslar/sassy 2.0.1 → 3.1.0

package/README.md

@@ -33,11 +33,16 @@ Write themes like a human, compile for VS Code:
 **After (Sassy):**
 
 ```yaml
+palette:
+  blue: "#4b8ebd"
+  white: "#e6e6e6"
+  dark: "#1a1a1a"
+
 vars:
-  accent: "#4b8ebd"
+  accent: $$blue
   std:
-    fg: "#e6e6e6"
-    bg: "#1a1a1a"
+    fg: $$white
+    bg: $$dark
     bg.panel: lighten($(std.bg), 15)
     bg.accent: darken($(accent), 15)
 
@@ -233,16 +238,23 @@ config:
   name: "My Awesome Theme"
   type: dark
 
+palette:
+  # Raw colour values — self-contained, evaluated first
+  blue: "#4b8ebd"
+  green: "#4ab792"
+  red: "#b74a4a"
+  white: "#e6e6e6"
+  dark: "#1a1a1a"
+
 vars:
-  # Your colour palette
-  primary: "#4b8ebd"
-  success: "#4ab792"
-  error: "#b74a4a"
+  # Semantic relationships referencing palette via $$
+  primary: $$blue
+  success: $$green
+  error: $$red
 
-  # Build semantic relationships
   std:
-    fg: "#e6e6e6"
-    bg: "#1a1a1a"
+    fg: $$white
+    bg: $$dark
     accent: $(primary)
     bg.accent: darken($(accent), 15)
 
@@ -271,17 +283,18 @@ While Sassy provides common functions like `lighten()`, `darken()`, and
 `mix()`, you have access to the entire spectrum of colour formats:
 
 ```yaml
-vars:
+palette:
   # Use any colour space Culori understands
   lab_colour: lab(50 20 -30)           # LAB colour space
   hwb_colour: hwb(180 30% 20%)         # HWB (Hue-Whiteness-Blackness)
   lch_colour: lch(70 40 180)           # LCH colour space
   p3_colour: color(display-p3 0.4 0.8 0.2)  # Display P3 gamut
   rec2020: color(rec2020 0.42 0.85 0.31)    # Rec. 2020 colour space
+  primary: oklch(0.6, 20, 220)
 
+vars:
   # Mix and match freely
-  primary: oklch(0.6, 20, 220)
-  secondary: mix($(primary), lab(80 -20 40), 30)
+  secondary: mix($$primary, lab(80 -20 40), 30)
   accent: lighten(hwb(240 20% 10%), 15)
 ```
 
@@ -326,15 +339,16 @@ function (`rgba(255, 100, 200, 0.5)`, `darken($(bg), 20)`,
 Use CSS colour names with the `css()` function:
 
 ```yaml
-vars:
+palette:
   # CSS named colours
   danger: css(crimson)
   ocean: css(deepskyblue)
   nature: css(forestgreen)
 
-  # Mix named colours with functions
-  muted_red: fade(css(tomato), 0.6)
-  light_blue: lighten(css(navy), 40)
+vars:
+  # Mix palette colours with functions
+  muted_red: fade($$danger, 0.6)
+  light_blue: lighten($$ocean, 40)
 ```
 
 > **Reference:** See the complete list of CSS named colours at [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/CSS/named-color) or [Wikipedia](https://en.wikipedia.org/wiki/Web_colors#HTML_color_names).
@@ -353,6 +367,24 @@ vars:
   variant3: ${accent}          # Braced form
 ```
 
+### Palette Aliases
+
+The `$$` prefix is shorthand for referencing `palette.*` values:
+
+```yaml
+palette:
+  cyan: "#56b6c2"
+
+vars:
+  # All equivalent — resolve to palette.cyan:
+  a: $$cyan
+  b: $($cyan)
+  c: ${$cyan}
+```
+
+This expansion happens before any variable resolution, so downstream tools
+(resolve, lint) see the canonical `$palette.cyan` form.
+
 ## Theme Development Workflow
 
 ### 1. Create Your Theme File
@@ -400,13 +432,12 @@ extension.
 Break your themes into reusable components using the import system:
 
 ```yaml
-# colours.yaml
-vars:
-  palette:
-    primary: "#4b8ebd"
-    success: "#4ab792"
-    error: "#b74a4a"
-    warning: "#b36b47"
+# palette.yaml
+palette:
+  blue: "#4b8ebd"
+  green: "#4ab792"
+  red: "#b74a4a"
+  orange: "#b36b47"
 
 ---
 
@@ -415,11 +446,11 @@ config:
   name: "My Theme"
   type: dark
   import:
-    - "./colours.yaml"
+    - "./palette.yaml"
 
 vars:
-  # Use imported colours
-  accent: $(palette.primary)
+  # Use imported palette via $$ alias
+  accent: $$blue
 
   # Build your design system
   std:
@@ -459,7 +490,7 @@ Imports are a simple array of file paths. Each file gets merged into your theme:
 
 The merge behaviour depends on the type of theme content:
 
-**Objects (composable):** `colors`, `semanticTokenColors`, `vars`, `config`
+**Objects (composable):** `palette`, `colors`, `semanticTokenColors`, `vars`, `config`
 
 1. Imported files (merged in import order)
 2. Your theme file's own definitions (final override)
@@ -499,41 +530,40 @@ Now edit your YAML file and watch VS Code update automatically!
 ### Start with Meaning, Not Colours
 
 ```yaml
-# ❌ Don't start with random colours
-vars:
-  red: "#ff0000"
-  blue: "#0000ff"
+# ✅ Raw colours go in palette
+palette:
+  red: "#b74a4a"
+  green: "#4ab792"
+  dark: "#1a1a1a"
 
-# ✅ Start with semantic meaning
+# ✅ Semantic meaning goes in vars
 vars:
   status:
-    error: "#b74a4a"
-    success: "#4ab792"
+    error: $$red
+    success: $$green
 
   ui:
-    background: "#1a1a1a"
+    background: $$dark
     surface: lighten($(ui.background), 15)
 ```
 
 ### Use Mathematical Relationships
 
 ```yaml
-# Colours that harmonize automatically
-vars:
+palette:
   base: "#4b8ebd"
+  gray: "#808080"
+  # OKLCH for perceptually uniform colours
+  primary: oklch(0.6, 20, 220)
+  accent: oklch(0.7, 25, 45)
 
+vars:
+  # Colours that harmonize automatically
   harmonies:
-    lighter: lighten($(base), 20)
-    darker: darken($(base), 20)
-    complement: mix($(base), invert($(base)), 50)
-    muted: mix($(base), "#808080", 30)
-
-  # OKLCH colours for perceptually uniform adjustments
-  oklch_palette:
-    primary: oklch(0.6, 20, 220)        # Blue with controlled chroma
-    accent: oklch(0.7, 25, 45)          # Warm orange complement
-    muted: oklch(0.5, 8, 220)           # Desaturated blue
-    bright: oklcha(0.8, 30, 220, 0.9)   # Bright blue with transparency
+    lighter: lighten($$base, 20)
+    darker: darken($$base, 20)
+    complement: mix($$base, invert($$base), 50)
+    muted: mix($$base, $$gray, 30)
 ```
 
 ### Test with Real Code

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "2.0.1",
+  "version": "3.1.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/sassy#readme",
   "repository": {
@@ -44,10 +44,10 @@
   },
   "dependencies": {
     "@gesslar/colours": "^0.8.0",
-    "@gesslar/toolkit": "^3.30.0",
+    "@gesslar/toolkit": "^3.31.0",
     "chokidar": "^5.0.0",
     "color-support": "^1.1.3",
-    "commander": "^14.0.2",
+    "commander": "^14.0.3",
     "culori": "^4.0.2",
     "globby": "^16.1.0",
     "json5": "^2.2.3",

package/src/Compiler.js

@@ -35,6 +35,7 @@ export default class Compiler {
     try {
       const source = theme.getSource()
       const {config: sourceConfig} = source ?? {}
+      const {palette: sourcePalette} = source
       const {vars: sourceVars} = source
       const {theme: sourceTheme} = source
 
@@ -71,6 +72,7 @@ export default class Compiler {
       const merged = Data.mergeObject({},
         imported,
         {
+          palette: sourcePalette ?? {},
           vars: sourceVars ?? {},
           colors: sourceTheme?.colors ?? {},
           semanticTokenColors: sourceTheme?.semanticTokenColors ?? {},
@@ -80,6 +82,11 @@ export default class Compiler {
       // Add tokenColors after merging to avoid mergeObject processing
       merged.tokenColors = mergedTokenColors
 
+      // Palette first — self-contained, cannot reach outside itself
+      const palette = this.#decomposeObject({palette: merged.palette ?? {}})
+
+      evaluate(palette)
+
       // Shred them up! Kinda. And evaluate the variables in place
       const vars = this.#decomposeObject(merged.vars)
 
@@ -110,7 +117,7 @@ export default class Compiler {
       // Assemble into one object with the proper keys
       const colors = workColors.reduce(reducer, {})
       const tokenColors = this.#composeArray(workTokenColors)
-      const semanticTokenColors = workSemanticTokenColors.reduce(reducer, {})
+      const semanticTokenColors = this.#composeObject(workSemanticTokenColors)
 
       // Mix and maaatch all jumbly wumbly...
       const output = Data.mergeObject(
@@ -142,6 +149,7 @@ export default class Compiler {
    */
   async #import(imports, theme) {
     const imported = {
+      palette: {},
       vars: {},
       colors: {},
       tokenColors: [],
@@ -191,18 +199,22 @@ export default class Compiler {
     }
 
     loaded.forEach((load, file) => {
+      const palette = load?.palette ?? {}
       const vars = load?.vars ?? {}
       const colors = load?.theme?.colors ?? {}
       const tokenColors = load?.theme?.tokenColors ?? []
       const semanticTokenColors = load?.theme?.semanticTokenColors ?? {}
 
       importByFile.set(file, new Map([
+        ["palette", palette],
         ["vars", vars],
         ["colors", colors],
         ["tokenColors", tokenColors],
         ["semanticTokenColors", semanticTokenColors]
       ]))
 
+      imported.palette =
+        Data.mergeObject(imported.palette, palette)
       imported.vars =
         Data.mergeObject(imported.vars, vars)
       imported.colors =

package/src/Evaluator.js

@@ -92,6 +92,35 @@ export default class Evaluator {
     return this.#pool
   }
 
+  /**
+   * Regular expression for expanding palette alias syntax. The `$` prefix
+   * inside variable references is shorthand for `palette.`:
+   *  - `$$name`    → `$palette.name`
+   *  - `$($name)`  → `$(palette.name)`
+   *  - `${$name}`  → `${palette.name}`
+   *
+   * @type {RegExp}
+   */
+  static paletteAlias = /\$\(\$([^()]+)\)|\$\{\$([^{}]+)\}|\$\$([\w]+(?:\.[\w]+)*)/g
+
+  /**
+   * Expands palette alias references in a string value.
+   * Converts `$$name`, `$($name)`, and `${$name}` to their
+   * full `palette.` equivalents before variable resolution.
+   *
+   * @param {string} value - The string potentially containing palette aliases
+   * @returns {string} The string with palette aliases expanded
+   */
+  static expandPaletteAliases(value) {
+    return value.replace(Evaluator.paletteAlias, (match, parens, braces, bare) => {
+      if(parens) return `$(palette.${parens})`
+      if(braces) return `\${palette.${braces}}`
+      if(bare) return `$palette.${bare}`
+
+      return match
+    })
+  }
+
   /**
    * Resolve variables and theme token entries in two distinct passes to ensure
    * deterministic scoping and to prevent partially-resolved values from
@@ -126,6 +155,12 @@ export default class Evaluator {
    * // decomposed[2].value === '#5588dd' (lightened color)
    */
   evaluate(decomposed) {
+    // Expand palette aliases before resolution
+    decomposed.forEach(item => {
+      if(typeof item.value === "string")
+        item.value = Evaluator.expandPaletteAliases(item.value)
+    })
+
     let it = 0
 
     do {

package/types/BuildCommand.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Command handler for building VS Code themes from source files.
+ * Handles compilation, watching for changes, and output generation.
+ */
+export default class BuildCommand extends Command {
+    /**
+     * Creates a new BuildCommand instance.
+     *
+     * @param {object} base - Base configuration object
+     * @param {string} base.cwd - Current working directory path
+     * @param {object} base.packageJson - Package.json configuration data
+     */
+    constructor(base: {
+        cwd: string;
+        packageJson: object;
+    });
+    /** @type {EventEmitter} Internal event emitter for watch mode coordination */
+    emitter: EventEmitter;
+    /**
+     * Emits an event asynchronously using the internal emitter.
+     * This method wraps Util.asyncEmit for convenience.
+     *
+     * @param {string} event - The event name to emit
+     * @param {...any} args - Arguments to pass to the event handlers
+     * @returns {Promise<void>} Resolves when all event handlers have completed
+     */
+    asyncEmit(event: string, ...args: any[]): Promise<void>;
+    /**
+     * @typedef {object} BuildCommandOptions
+     * @property {boolean} [watch] - Enable watch mode for file changes
+     * @property {string} [outputDir] - Custom output directory path
+     * @property {boolean} [dryRun] - Print JSON to stdout without writing files
+     * @property {boolean} [silent] - Silent mode, only show errors or dry-run output
+     */
+    /**
+     * Executes the build command for the provided theme files.
+     * Processes each file in parallel, optionally watching for changes.
+     *
+     * @param {Array<string>} fileNames - Array of theme file paths to process
+     * @param {BuildCommandOptions} options - {@link BuildCommandOptions}
+     * @returns {Promise<void>} Resolves when all files are processed
+     * @throws {Error} When theme compilation fails
+     */
+    execute(fileNames: Array<string>, options: {
+        /**
+         * - Enable watch mode for file changes
+         */
+        watch?: boolean;
+        /**
+         * - Custom output directory path
+         */
+        outputDir?: string;
+        /**
+         * - Print JSON to stdout without writing files
+         */
+        dryRun?: boolean;
+        /**
+         * - Silent mode, only show errors or dry-run output
+         */
+        silent?: boolean;
+    }): Promise<void>;
+    #private;
+}
+import Command from "./Command.js";
+//# sourceMappingURL=BuildCommand.d.ts.map

package/types/BuildCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuildCommand.d.ts","sourceRoot":"","sources":["../src/BuildCommand.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH;IAOE;;;;;;OAMG;IACH,kBAHG;QAAqB,GAAG,EAAhB,MAAM;QACO,WAAW,EAAxB,MAAM;KAChB,EAWA;IAvBD,8EAA8E;IAC9E,SADW,YAAY,CACK;IAwB5B;;;;;;;OAOG;IACH,iBAJW,MAAM,WACH,GAAG,EAAA,GACJ,OAAO,CAAC,IAAI,CAAC,CAIzB;IAED;;;;;;OAMG;IAEH;;;;;;;;OAQG;IACH,mBALW,KAAK,CAAC,MAAM,CAAC;;;;gBAVV,OAAO;;;;oBACP,MAAM;;;;iBACN,OAAO;;;;iBACP,OAAO;QASR,OAAO,CAAC,IAAI,CAAC,CAmCzB;;CAuFF;oBAtLmB,cAAc"}

package/types/Colour.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Colour manipulation utility class providing static methods for colour operations.
+ * Handles hex colour parsing, alpha manipulation, mixing, and format conversions.
+ */
+export default class Colour {
+    /**
+     * Regular expression for matching long hex colour codes with optional alpha.
+     * Matches patterns like #ff0000 or #ff0000ff
+     *
+     * @type {RegExp}
+     */
+    static longHex: RegExp;
+    /**
+     * Regular expression for matching short hex colour codes with optional alpha.
+     * Matches patterns like #f00 or #f00f
+     *
+     * @type {RegExp}
+     */
+    static shortHex: RegExp;
+    /**
+     * Lightens or darkens a hex colour by a specified amount.
+     * Always uses OKLCH as the working color space for consistent perceptual results.
+     *
+     * @param {string} hex - The hex colour code (e.g., "#ff0000" or "#f00")
+     * @param {number} amount - The amount to lighten (+) or darken (-) as a percentage
+     * @returns {string} The modified hex colour with preserved alpha
+     */
+    static lightenOrDarken(hex: string, amount?: number): string;
+    /**
+     * Lightens or darkens a color using OKLCH as working space for consistent results.
+     * Preserves original color information from tokens when available.
+     *
+     * @param {ThemeToken|object|string} tokenOrColor - ThemeToken, Culori color object, or hex string
+     * @param {number} amount - The amount to lighten (+) or darken (-) as a percentage
+     * @returns {string} The modified hex colour
+     */
+    static lightenOrDarkenWithToken(tokenOrColor: converter | object | string, amount?: number): string;
+    /**
+     * Inverts a hex colour by flipping its lightness value.
+     * Preserves hue and saturation while inverting the lightness component.
+     *
+     * @param {string} hex - The hex colour code to invert
+     * @returns {string} The inverted hex colour with preserved alpha
+     */
+    static invert(hex: string): string;
+    /**
+     * Converts a hex alpha value to a decimal percentage.
+     * Takes a 2-digit hex alpha value and converts it to a percentage (0-100).
+     *
+     * @param {string} hex - The hex alpha value (e.g., "ff", "80")
+     * @returns {number} The alpha as a percentage rounded to 2 decimal places
+     */
+    static hexAlphaToDecimal(hex: string): number;
+    /**
+     * Converts a decimal percentage to a hex alpha value.
+     * Takes a percentage (0-100) and converts it to a 2-digit hex alpha value.
+     *
+     * @param {number} dec - The alpha percentage (0-100)
+     * @returns {string} The hex alpha value (e.g., "ff", "80")
+     */
+    static decimalAlphaToHex(dec: number): string;
+    static isHex(value: any): boolean;
+    /**
+     * Normalises a short hex colour code to a full 6-character format.
+     * Converts 3-character hex codes like "#f00" to "#ff0000".
+     *
+     * @param {string} code - The short hex colour code
+     * @returns {string} The normalized 6-character hex colour code
+     */
+    static normaliseHex(code: string): string;
+    /**
+     * Parses a hex colour string and extracts colour and alpha components.
+     * Supports both short (#f00) and long (#ff0000) formats with optional alpha.
+     *
+     * @param {string} hex - The hex colour string to parse
+     * @returns {object} Object containing colour and optional alpha information
+     * @throws {Sass} If the hex value is invalid or missing
+     */
+    static parseHexColour(hex: string): object;
+    /**
+     * Sets the alpha transparency of a hex colour to a specific value.
+     * Replaces any existing alpha with the new value.
+     *
+     * @param {string} hex - The hex colour code
+     * @param {number} amount - The alpha value (0-1, where 0 is transparent and 1 is opaque)
+     * @returns {string} The hex colour with the new alpha value
+     */
+    static setAlpha(hex: string, amount: number): string;
+    /**
+     * Adjusts the alpha transparency of a hex colour by a relative amount.
+     * Multiplies the current alpha by (1 + amount) and clamps the result.
+     *
+     * @param {string} hex - The hex colour code
+     * @param {number} amount - The relative amount to adjust alpha (-1 to make transparent, positive to increase)
+     * @returns {string} The hex colour with adjusted alpha
+     */
+    static addAlpha(hex: string, amount: number): string;
+    /**
+     * Removes alpha channel from a hex colour, returning only the solid colour.
+     *
+     * @param {string} hex - The hex colour code with or without alpha
+     * @returns {string} The solid hex colour without alpha
+     */
+    static solid(hex: string): string;
+    /**
+     * Mixes two hex colours together in a specified ratio.
+     * Blends both the colours and their alpha channels if present.
+     *
+     * @param {string} colourA - The first hex colour
+     * @param {string} colourB - The second hex colour
+     * @param {number} ratio - The mixing ratio as percentage (0-100, where 50 is equal mix)
+     * @returns {string} The mixed hex colour with blended alpha
+     */
+    static mix(colourA: string, colourB: string, ratio?: number): string;
+    static getColourParser(name: any): Promise<any>;
+    /**
+     * Converts colour values from various formats to hex.
+     * Supports RGB, RGBA, HSL, HSLA, OKLCH, and OKLCHA colour modes, and MORE!
+     *
+     * @param {string} input - The colour expression
+     * @returns {string} The resulting hex colour
+     * @throws {Sass} If the wrong function or value is provided
+     */
+    static toHex(input: string): string;
+}
+//# sourceMappingURL=Colour.d.ts.map

package/types/Colour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Colour.d.ts","sourceRoot":"","sources":["../src/Colour.js"],"names":[],"mappings":"AA2GA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,gBAFU,MAAM,CAEmD;IAEnE;;;;;OAKG;IACH,iBAFU,MAAM,CAEoD;IAEpE;;;;;;;OAOG;IACH,4BAJW,MAAM,WACN,MAAM,GACJ,MAAM,CAiBlB;IAED;;;;;;;OAOG;IACH,8CAJW,SAAU,GAAC,MAAM,GAAC,MAAM,WACxB,MAAM,GACJ,MAAM,CA6BlB;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;OAMG;IACH,8BAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;;OAMG;IACH,8BAHW,MAAM,GACJ,MAAM,CAWlB;IAED,kCAGC;IAED;;;;;;OAMG;IACH,0BAHW,MAAM,GACJ,MAAM,CAgBlB;IAED;;;;;;;OAOG;IACH,2BAJW,MAAM,GACJ,MAAM,CA8BlB;IAED;;;;;;;OAOG;IACH,qBAJW,MAAM,UACN,MAAM,GACJ,MAAM,CASlB;IAED;;;;;;;OAOG;IACH,qBAJW,MAAM,UACN,MAAM,GACJ,MAAM,CASlB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,oBALW,MAAM,WACN,MAAM,UACN,MAAM,GACJ,MAAM,CA6BlB;IAED,gDAOC;IAED;;;;;;;OAOG;IACH,oBAJW,MAAM,GACJ,MAAM,CAclB;CACF"}