@gesslar/sassy 1.3.0 → 2.0.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "1.3.0",
+  "version": "2.0.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/sassy#readme",
   "repository": {
@@ -54,6 +54,7 @@
     "yaml": "^2.8.2"
   },
   "devDependencies": {
+    "@docusaurus/eslint-plugin": "^3.9.2",
     "@gesslar/uglier": "^1.2.0",
     "eslint": "^9.39.2",
     "typescript": "^5.9.3"
@@ -69,6 +70,9 @@
     "submit": "pnpm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
     "examples": "node ./examples/validator.js",
     "update": "pnpm self-update && pnpx npm-check-updates -u && pnpm install",
+    "docs:dev": "pnpm --dir docs start",
+    "docs:build": "pnpm --dir docs build",
+    "docs:deploy": "gh workflow run deploy-docs.yml",
     "pr": "gt submit -p --ai",
     "patch": "pnpm version patch",
     "minor": "pnpm version minor",

package/src/Evaluator.js

@@ -318,11 +318,16 @@ export default class Evaluator {
       return null
 
     const resolved = value.replace(captured, applied)
-
-    return new ThemeToken(value)
+    const token = new ThemeToken(value)
       .setKind("function")
       .setRawValue(captured)
       .setValue(resolved)
+
+    if(resolved !== applied) {
+      token.setFunctionResult(applied)
+    }
+
+    return token
   }
 
   /**

package/src/ResolveCommand.js

@@ -14,6 +14,9 @@ import Theme from "./Theme.js"
  * Provides introspection into the theme resolution process and variable dependencies.
  */
 export default class ResolveCommand extends Command {
+  #extraOptions = null
+  #bg = null
+
   /**
    * Creates a new ResolveCommand instance.
    *
@@ -28,6 +31,22 @@ export default class ResolveCommand extends Command {
       "tokenColor": ["-t, --tokenColor <scope>", "resolve a tokenColors scope to its final evaluated value"],
       "semanticTokenColor": ["-s, --semanticTokenColor <scope>", "resolve a semanticTokenColors scope to its final evaluated value"],
     })
+    this.#extraOptions = {
+      "bg": ["--bg <hex>", "background colour for alpha swatch preview (e.g. 1a1a1a or '#1a1a1a')"],
+    }
+  }
+
+  /**
+   * Builds the CLI command, adding extra options that are not mutually exclusive.
+   *
+   * @param {object} program - The commander.js program instance
+   * @returns {Promise<this>} Returns this instance for method chaining
+   */
+  async buildCli(program) {
+    await super.buildCli(program)
+    this.addCliOptions(this.#extraOptions, false)
+
+    return this
   }
 
   /**
@@ -59,6 +78,16 @@ export default class ResolveCommand extends Command {
       )
     }
 
+    if(options.bg) {
+      const bg = options.bg.startsWith("#") ? options.bg : `#${options.bg}`
+
+      if(!Colour.isHex(bg)) {
+        throw Sass.new(`Invalid --bg colour: ${options.bg}`)
+      }
+
+      this.#bg = Colour.normaliseHex(bg)
+    }
+
     const resolveFunctionName = `resolve${Util.capitalize(optionName)}`
     const optionValue = options[optionName]
     const resolverFunction = this[resolveFunctionName]
@@ -334,6 +363,18 @@ export default class ResolveCommand extends Command {
         }
       }
 
+      // For function tokens embedded in a larger expression, show the
+      // direct function output before showing the full substituted result
+      const funcResult = token.getFunctionResult?.()
+
+      if(funcResult && !steps.some(s => s.value === funcResult)) {
+        steps.push({
+          value: funcResult,
+          type: "result",
+          level
+        })
+      }
+
       // Add final result for this token
       if(rawValue !== finalValue && !steps.some(s => s.value === finalValue)) {
         steps.push({
@@ -387,13 +428,13 @@ export default class ResolveCommand extends Command {
       const {value, depth, type} = step
       const [line, kind] = this.#formatLeaf(value)
 
-      // Simple logic: only hex results get extra indentation with arrow, everything else is clean
+      // Simple logic: only hex results get extra indentation with arrow/swatch, everything else is clean
       if(type === "result" && kind === "hex") {
-        // Hex results are indented one extra level with just spaces and arrow
+        // Hex results are indented one extra level with swatch or arrow
         const prefix = "   ".repeat(depth + 1)
-        const arrow = c`{arrow}→{/} `
+        const indicator = this.#makeIndicator(value, this.#bg)
 
-        out.push(`${prefix}${arrow}${line}`)
+        out.push(`${prefix}${indicator} ${line}`)
       } else {
         // Everything else just gets clean indentation
         const prefix = "   ".repeat(depth)
@@ -409,6 +450,59 @@ export default class ResolveCommand extends Command {
   #sub = Evaluator.sub
   #hex = value => Colour.isHex(value)
 
+  /**
+   * Creates a truecolor swatch glyph from a hex value.
+   *
+   * @private
+   * @param {string} hex - A 6- or 8-digit hex colour.
+   * @returns {string} A truecolor `■` character.
+   */
+  #swatch(hex) {
+    const solid = Colour.parseHexColour(hex).colour
+    const r = parseInt(solid.slice(1, 3), 16)
+    const g = parseInt(solid.slice(3, 5), 16)
+    const b = parseInt(solid.slice(5, 7), 16)
+
+    return `\x1b[38;2;${r};${g};${b}m■\x1b[0m`
+  }
+
+  /**
+   * Creates a colour swatch or fallback arrow indicator for a hex value.
+   * When the colour has alpha and no --bg is provided, shows two swatches
+   * (against black and white). With --bg, shows a single swatch composited
+   * against the specified background.
+   *
+   * @private
+   * @param {string} hex - The hex colour value.
+   * @param {string|null} bg - Optional background hex for alpha compositing.
+   * @returns {string} Swatch indicator(s) or styled arrow.
+   */
+  #makeIndicator(hex, bg = null) {
+    if(!Term.hasColor) {
+      return c`{arrow}→{/}`
+    }
+
+    const parsed = Colour.parseHexColour(hex)
+    const hasAlpha = !!parsed.alpha
+
+    if(!hasAlpha) {
+      return this.#swatch(hex)
+    }
+
+    const alphaPercent = Math.round(parsed.alpha.decimal * 100)
+
+    if(bg) {
+      const composited = Colour.mix(parsed.colour, bg, alphaPercent)
+
+      return this.#swatch(composited)
+    }
+
+    const onBlack = Colour.mix(parsed.colour, "#000000", alphaPercent)
+    const onWhite = Colour.mix(parsed.colour, "#ffffff", alphaPercent)
+
+    return `${this.#swatch(onBlack)}${this.#swatch(onWhite)}`
+  }
+
   /**
    * Formats a single ThemeToken for display in the theme resolution output,
    * applying colour and style based on its type.
@@ -432,12 +526,12 @@ export default class ResolveCommand extends Command {
     }
 
     if(this.#func.test(value)) {
-      const result = Evaluator.extractFunctionCall(value)
+      const match = this.#func.exec(value)
 
-      if(!result)
+      if(!match?.groups)
         return [c`{leaf}${value}{/}`, "literal"]
 
-      const {func, args} = result
+      const {func, args} = match.groups
 
       return [
         c`{func}${func}{/}{parens}${"("}{/}{leaf}${args}{/}{parens}${")"}{/}`,

package/src/ThemeToken.js

@@ -30,6 +30,7 @@ export default class ThemeToken {
   #parentTokenKey = null
   #trail = new Array()
   #parsedColor = null
+  #functionResult = null
 
   /**
    * Constructs a ThemeToken with a given token name.
@@ -242,6 +243,28 @@ export default class ThemeToken {
     return this.#parsedColor
   }
 
+  /**
+   * Sets the direct result of a colour function evaluation, before
+   * substitution back into the enclosing expression.
+   *
+   * @param {string} result - The direct function output.
+   * @returns {ThemeToken} This token instance.
+   */
+  setFunctionResult(result) {
+    this.#functionResult = result
+
+    return this
+  }
+
+  /**
+   * Gets the direct result of a colour function evaluation.
+   *
+   * @returns {string|null} The direct function output or null.
+   */
+  getFunctionResult() {
+    return this.#functionResult
+  }
+
   /**
    * Checks if this token has an ancestor with the given token name.
    *

package/src/cli.js

@@ -80,14 +80,13 @@ void (async function main() {
     c.alias.set("loc", "{F148}")
 
     // Resolve command
-    c.alias.set("head", "{F220}")
-    c.alias.set("leaf", "{F151}")
-    c.alias.set("func", "{F111}")
-    c.alias.set("parens", "{F098}")
-    c.alias.set("line", "{F142}")
-    c.alias.set("hex", "{F140}")
-    c.alias.set("hash", "{F147}{<B}")
-    c.alias.set("hexAlpha", "{F127}{<I}")
+    c.alias.set("head", "{F250}")
+    c.alias.set("leaf", "{F243}")
+    c.alias.set("func", "{<B}")
+    c.alias.set("parens", "{F208}")
+    c.alias.set("hash", "{F172}")
+    c.alias.set("hex", "{F025}")
+    c.alias.set("hexAlpha", "{F073}{<I}")
     c.alias.set("arrow", "{F033}")
 
     const cache = new Cache()