@gesslar/sassy 1.2.0 → 2.0.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "1.2.0",
+  "version": "2.0.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/sassy#readme",
   "repository": {
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "@gesslar/colours": "^0.8.0",
-    "@gesslar/toolkit": "^3.29.0",
+    "@gesslar/toolkit": "^3.30.0",
     "chokidar": "^5.0.0",
     "color-support": "^1.1.3",
     "commander": "^14.0.2",
@@ -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/BuildCommand.js

@@ -48,39 +48,33 @@ export default class BuildCommand extends Command {
     return await Util.asyncEmit(this.emitter, event, ...args)
   }
 
+  /**
+   * @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 {string[]} fileNames - Array of theme file paths to process
-   * @param {object} options - Build options
-   * @param {boolean} [options.watch] - Enable watch mode for file changes
-  * @param {string} [options.outputDir] - Custom output directory path
-  * @param {boolean} [options.dryRun] - Print JSON to stdout without writing files
-  * @param {boolean} [options.silent] - Silent mode, only show errors or dry-run output
+   * @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
    */
   async execute(fileNames, options) {
-
-    /**
- * @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
- */
     const cwd = this.getCwd()
 
     if(options.watch) {
       options.watch && this.#initialiseInputHandler()
 
-      this.emitter.on("quit", async() =>
-        await this.#handleQuit())
-
-      this.emitter.on("building", async() => await this.#startBuilding())
+      this.emitter.on("quit", async() => await this.#handleQuit())
+      this.emitter.on("building", () => this.#startBuilding())
       this.emitter.on("finishedBuilding", () => this.#finishBuilding())
-      this.emitter.on("erasePrompt", async() => await this.#erasePrompt())
+      this.emitter.on("erasePrompt", () => this.#erasePrompt())
       this.emitter.on("printPrompt", () => this.#printPrompt())
     }
 
@@ -97,16 +91,6 @@ export default class BuildCommand extends Command {
     if(Promised.hasRejected(sessionResults))
       Promised.throw("Creating sessions.", sessionResults)
 
-    // if(sessionResults.some(theme => theme.status === "rejected")) {
-    //   const rejected = sessionResults.filter(result => result.status === "rejected")
-
-    //   rejected.forEach(item => {
-    //     const sassError = Sass.new("Creating session for theme file.", item.reason)
-    //     sassError.report(options.nerd)
-    //   })
-    //   process.exit(1)
-    // }
-
     const sessions = Promised.values(sessionResults)
     const firstRun = await Promised.settle(sessions.map(
       async session => await session.run()))
@@ -123,7 +107,7 @@ export default class BuildCommand extends Command {
   async #handleQuit() {
     await this.asyncEmit("closeSession")
 
-    await Term.directWrite("\x1b[?25h")
+    Term.write("\x1b[?25h")
 
     Term.info()
     Term.info("Exiting.")
@@ -160,16 +144,16 @@ export default class BuildCommand extends Command {
       }
     })
 
-    await Term.directWrite("\x1b[?25l")
+    Term.write("\x1b[?25l")
   }
 
-  async #printPrompt() {
+  #printPrompt() {
     if(this.#hasPrompt && this.#building > 0)
       return
 
-    await Term.directWrite("\n")
+    Term.write("\n")
 
-    await Term.directWrite(Term.terminalMessage([
+    Term.write(Term.terminalMessage([
       ["info", "F5", ["<",">"]],
       "rebuild all,",
       ["info", "Ctrl-C", ["<",">"]],
@@ -179,17 +163,18 @@ export default class BuildCommand extends Command {
     this.#hasPrompt = true
   }
 
-  async #erasePrompt() {
+  #erasePrompt() {
     if(!this.#hasPrompt)
       return
 
     this.#hasPrompt = false
 
-    await Term.clearLines(1)
+    Term.clearLine().moveStart()
   }
 
-  async #startBuilding() {
-    await this.#erasePrompt()
+  #startBuilding() {
+    this.#erasePrompt()
+
     this.#building++
   }
 

package/src/Command.js

@@ -115,7 +115,7 @@ export default class Command {
   /**
    * Gets the array of CLI option names.
    *
-   * @returns {string[]} Array of option names
+   * @returns {Array<string>} Array of option names
    */
   getCliOptionNames() {
     return this.#optionNames
@@ -192,7 +192,7 @@ export default class Command {
    * Adds a single CLI option to the command.
    *
    * @param {string} name - The option name
-   * @param {string[]} options - Array containing option flag and description
+   * @param {Array<string>} options - Array containing option flag and description
    * @param {boolean} preserve - Whether to preserve this option name in the list
    * @returns {Promise<this>} Returns this instance for method chaining
    */

package/src/Compiler.js

@@ -222,7 +222,7 @@ export default class Compiler {
    * evaluation.
    *
    * @param {object} work - The object to decompose
-   * @param {string[]} path - Current path array for nested properties
+   * @param {Array<string>} path - Current path array for nested properties
    * @returns {Array<object>} Array of decomposed object entries with path information
    */
   #decomposeObject(work, path = []) {

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/Session.js

@@ -6,6 +6,7 @@ import {Promised, Sass, Term, Util} from "@gesslar/toolkit"
 /**
  * @import {Command} from "./Command.js"
  * @import {Theme} from "./Theme.js"
+ * @import {FSWatcher} from "chokidar"
  */
 
 /**
@@ -58,7 +59,7 @@ export default class Session {
   /**
    * Active file system watcher for theme dependencies.
    *
-   * @type {import("chokidar").FSWatcher|null}
+   * @type {FSWatcher}
    * @private
    */
   #watcher = null

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

@@ -16,7 +16,7 @@
  *    sourceFile: FileObject          // entry theme file
  *    source: object                  // raw parsed data (must contain `config`)
  *    output: object                  // final theme JSON object
- *    dependencies: FileObject[]      // secondary sources discovered during compile
+ *    dependencies: Array<FileObject> // secondary sources discovered during compile
  *    lookup: object                  // variable lookup data for compilation
  *    breadcrumbs: Map                // variable resolution tracking
  *  }
@@ -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()