@gesslar/toolkit 3.29.0 → 3.30.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.29.0",
+  "version": "3.30.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {

package/src/node/lib/Term.js

@@ -3,9 +3,29 @@ import process from "node:process"
 import {Writable} from "node:stream"
 import supportsColor from "supports-color"
 import {stripVTControlCharacters} from "node:util"
+import c from "@gesslar/colours"
 
 import Sass from "./Sass.js"
 
+c.alias.set("success", "{F035}")
+c.alias.set("info", "{F033}")
+c.alias.set("warn", "{F208}")
+c.alias.set("error", "{F032}")
+c.alias.set("modified", "{F147}")
+
+/**
+ * Terminal output utilities with ANSI colour support.
+ *
+ * Provides console logging wrappers, cursor control, and formatted message
+ * output with colour styling via `@gesslar/colours`.
+ *
+ * Predefined colour aliases:
+ * - `success` - green (F035)
+ * - `info` - blue (F033)
+ * - `warn` - orange (F208)
+ * - `error` - red (F032)
+ * - `modified` - purple (F147)
+ */
 export default class Term {
   static #cache = new Map()
 
@@ -217,17 +237,17 @@ export default class Term {
   }
 
   /**
-   * Constructs a formatted status line.
+   * Constructs a formatted status line with optional colour styling.
    *
    * Input forms:
    *  - string: printed as-is
    *  - array: each element is either:
    *    - a plain string (emitted unchanged), or
-   *    - a tuple: [level, text] where `level` maps to an ansiColors alias
-   *        (e.g. success, info, warn, error, modified).
-   *    - a tuple: [level, text, [openBracket,closeBracket]] where `level` maps to an ansiColors alias
-   *        (e.g. success, info, warn, error, modified). These are rendered as
-   *        colourised bracketed segments: [TEXT].
+   *    - a tuple: [colourCode, text] where `colourCode` is a colour alias
+   *        (e.g. success, info, warn, error, modified) or any valid
+   *        `@gesslar/colours` format string.
+   *    - a tuple: [colourCode, text, [openBracket, closeBracket]] for custom
+   *        brackets around the colourised text.
    *
    * The function performs a shallow validation: tuple elements must both be
    * strings; otherwise a TypeError is thrown. Nested arrays beyond depth 1 are
@@ -236,8 +256,8 @@ export default class Term {
    * Recursion: array input is normalised into a single string then re-dispatched
    * through `status` to leverage the string branch (keeps logic DRY).
    *
-   * @param {string | Array<string | [string, string] | [string, string, string]>} argList - Message spec.
-   * @returns {void}
+   * @param {string | Array<string | [string, string] | [string, string, [string, string]]>} argList - Message spec.
+   * @returns {string} The formatted message string.
    */
   static terminalMessage(argList) {
     if(typeof argList === "string")
@@ -269,34 +289,33 @@ export default class Term {
 
   /**
    * Construct a single coloured bracketed segment from a tuple specifying
-   * the style level and the text. The first element ("level") maps to an
-   * `ansiColors` alias (e.g. success, info, warn, error, modified) and is
-   * used both for the inner text colour and to locate its matching
-   * "-bracket" alias for the surrounding square brackets. The second
-   * element is the raw text to display.
+   * the colour code and text. The first element is a colour code that can be
+   * a predefined alias (success, info, warn, error, modified) or any valid
+   * `@gesslar/colours` format string. The brackets are coloured while the
+   * inner text remains uncoloured.
    *
-   * Input validation: every element of `parts` must be a string; otherwise
-   * an `Sass` error is thrown. (Additional elements beyond the first two are
-   * ignored – the method destructures only the first pair.)
+   * Input validation: colourCode and text must both be strings; otherwise
+   * a `Sass` error is thrown.
    *
    * Example:
-   *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with coloured
-   *  brackets + inner text (assuming colour support is available in the
-   *  terminal).
+   *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with green
+   *  brackets (assuming colour support is available in the terminal).
+   *
+   *  terminalBracket(["info", "STATUS", ["<", ">"]]) → "<STATUS>" with blue
+   *  angle brackets.
    *
    * This method does not append trailing spaces; callers are responsible for
    * joining multiple segments with appropriate separators.
    *
-   * @param {Array<string>} parts - Tuple: [level, text]. Additional entries ignored.
+   * @param {[string, string, [string, string]?]} parts - Tuple: [colourCode, text, brackets?].
    * @returns {string} Colourised bracketed segment (e.g. "[TEXT]").
-   * @throws {Sass} If any element of `parts` is not a string.
+   * @throws {Sass} If colourCode or text is not a string.
    */
-  static terminalBracket([level, text, brackets=["[","]"]]) {
-    if(!(typeof level === "string" && typeof text === "string"))
+  static terminalBracket([colourCode="", text, brackets=["[","]"]]) {
+    if(!(typeof colourCode === "string" && typeof text === "string"))
       throw Sass.new("Each element must be a string.")
 
-    // Simplified version without color support - just return bracketed text
-    return `${brackets[0]}${text}${brackets[1]}`
+    return this.#preformat(c`{${colourCode}}${brackets[0]}{/}${text}{${colourCode}}${brackets[1]}{/}`)
   }
 
   /**

package/types/node/lib/Term.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Terminal output utilities with ANSI colour support.
+ *
+ * Provides console logging wrappers, cursor control, and formatted message
+ * output with colour styling via `@gesslar/colours`.
+ *
+ * Predefined colour aliases:
+ * - `success` - green (F035)
+ * - `info` - blue (F033)
+ * - `warn` - orange (F208)
+ * - `error` - red (F032)
+ * - `modified` - purple (F147)
+ */
 export default class Term {
     static "__#private@#cache": Map<any, any>;
     static "__#private@#preformat"(text: any): any;
@@ -107,17 +120,17 @@ export default class Term {
         silent: boolean;
     }): void;
     /**
-     * Constructs a formatted status line.
+     * Constructs a formatted status line with optional colour styling.
      *
      * Input forms:
      *  - string: printed as-is
      *  - array: each element is either:
      *    - a plain string (emitted unchanged), or
-     *    - a tuple: [level, text] where `level` maps to an ansiColors alias
-     *        (e.g. success, info, warn, error, modified).
-     *    - a tuple: [level, text, [openBracket,closeBracket]] where `level` maps to an ansiColors alias
-     *        (e.g. success, info, warn, error, modified). These are rendered as
-     *        colourised bracketed segments: [TEXT].
+     *    - a tuple: [colourCode, text] where `colourCode` is a colour alias
+     *        (e.g. success, info, warn, error, modified) or any valid
+     *        `@gesslar/colours` format string.
+     *    - a tuple: [colourCode, text, [openBracket, closeBracket]] for custom
+     *        brackets around the colourised text.
      *
      * The function performs a shallow validation: tuple elements must both be
      * strings; otherwise a TypeError is thrown. Nested arrays beyond depth 1 are
@@ -126,35 +139,35 @@ export default class Term {
      * Recursion: array input is normalised into a single string then re-dispatched
      * through `status` to leverage the string branch (keeps logic DRY).
      *
-     * @param {string | Array<string | [string, string] | [string, string, string]>} argList - Message spec.
-     * @returns {void}
+     * @param {string | Array<string | [string, string] | [string, string, [string, string]]>} argList - Message spec.
+     * @returns {string} The formatted message string.
      */
-    static terminalMessage(argList: string | Array<string | [string, string] | [string, string, string]>): void;
+    static terminalMessage(argList: string | Array<string | [string, string] | [string, string, [string, string]]>): string;
     /**
      * Construct a single coloured bracketed segment from a tuple specifying
-     * the style level and the text. The first element ("level") maps to an
-     * `ansiColors` alias (e.g. success, info, warn, error, modified) and is
-     * used both for the inner text colour and to locate its matching
-     * "-bracket" alias for the surrounding square brackets. The second
-     * element is the raw text to display.
+     * the colour code and text. The first element is a colour code that can be
+     * a predefined alias (success, info, warn, error, modified) or any valid
+     * `@gesslar/colours` format string. The brackets are coloured while the
+     * inner text remains uncoloured.
      *
-     * Input validation: every element of `parts` must be a string; otherwise
-     * an `Sass` error is thrown. (Additional elements beyond the first two are
-     * ignored – the method destructures only the first pair.)
+     * Input validation: colourCode and text must both be strings; otherwise
+     * a `Sass` error is thrown.
      *
      * Example:
-     *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with coloured
-     *  brackets + inner text (assuming colour support is available in the
-     *  terminal).
+     *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with green
+     *  brackets (assuming colour support is available in the terminal).
+     *
+     *  terminalBracket(["info", "STATUS", ["<", ">"]]) → "<STATUS>" with blue
+     *  angle brackets.
      *
      * This method does not append trailing spaces; callers are responsible for
      * joining multiple segments with appropriate separators.
      *
-     * @param {Array<string>} parts - Tuple: [level, text]. Additional entries ignored.
+     * @param {[string, string, [string, string]?]} parts - Tuple: [colourCode, text, brackets?].
      * @returns {string} Colourised bracketed segment (e.g. "[TEXT]").
-     * @throws {Sass} If any element of `parts` is not a string.
+     * @throws {Sass} If colourCode or text is not a string.
      */
-    static terminalBracket([level, text, brackets]: Array<string>): string;
+    static terminalBracket([colourCode, text, brackets]: [string, string, [string, string]?]): string;
     /**
      * ANSI escape sequence to move cursor to start of line.
      *

package/types/node/lib/Term.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Term.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Term.js"],"names":[],"mappings":"AAQA;IACE,0CAAyB;IAEzB,+CAIC;IAED;;;;OAIG;IACH,sBAFU,MAAM,GAAG,SAAS,CAI3B;IAED;;;;OAIG;IACH,mBAFU,MAAM,GAAG,SAAS,CAI3B;IAED;;;;OAIG;IACH,kBAFU;QAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;KAAC,CAIhE;IAED;;;;OAIG;IACH,4BAFU,OAAO,CAMhB;IAED;;;;OAIG;IACH,uBAFU,OAAO,CAMhB;IAED;;;;OAIG;IACH,oBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,qBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,qBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,sBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,sBAFc,OAAO,EAAA,QAIpB;IAED;;;;OAIG;IACH,sBAFc,OAAO,EAAA,QAIpB;IAED;;OAEG;IACH,wBAEC;IAED;;;;;;;;OAQG;IACH,0BANW,MAAM,QAAQ,YAEtB;QAAgC,UAAU,GAAlC,KAAK,CAAC,MAAM,CAAC;QACK,UAAU,GAA5B,OAAO;QACW,aAAa,GAA/B,OAAO;KACjB,QA2DA;IAED;;;;;;;;;;;;;;OAcG;IACH,oBALW,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,eAEjD;QAAyB,MAAM,EAAvB,OAAO;KACf,GAAU,IAAI,CAOhB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gCAHW,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,GAClE,IAAI,CA4BhB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,gDAJW,KAAK,CAAC,MAAM,CAAC,GACX,MAAM,CASlB;IAED;;;;OAIG;IACH,oBAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,oBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,kBAFU,MAAM,CAIf;IAED;;;;OAIG;IACH,kBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,iBAFU,MAAM,CAIf;IAED;;;;;OAKG;IACH,mBAHW,MAAM,GACJ,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,qBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,qBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,yBAFU,OAAO,CAOhB;IAED;;;;OAIG;IACH,yBAFU,OAAO,CAOhB;IAED;;;;OAIG;IACH,sBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,sBAFa,OAAO,IAAI,CAMvB;IAED;;;;OAIG;IACH,oBAFa,OAAO,IAAI,CAMvB;IAED;;;;;OAKG;IACH,uBAHW,MAAM,GACJ,OAAO,IAAI,CAOvB;IAED;;;;;OAKG;IACH,qBAHW,MAAM,GACJ,OAAO,IAAI,CAMvB;IAED;;;;;;OAMG;IACH,yBAHW,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACvB,OAAO,CAAC,MAAM,CAAC,CAyD3B;IAED;;;;OAIG;IACH,4BAFa,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAqCrC;IAED;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAMzB;IAID,0CAAuE;CAYxE"}
+{"version":3,"file":"Term.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Term.js"],"names":[],"mappings":"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"}