cli-kiss 0.2.3 → 0.2.5

package/src/lib/Typo.ts

@@ -25,6 +25,10 @@ export type TypoColor =
  * All fields are optional; ignored entirely in `"none"` mode.
  */
 export type TypoStyle = {
+  /**
+   * Letter case.
+   */
+  case?: "upper" | "lower";
   /**
    * Foreground (text) color.
    */
@@ -34,43 +38,43 @@ export type TypoStyle = {
    */
   bgColor?: TypoColor;
   /**
-   * Render with reduced intensity.
+   * Reduced intensity.
    */
   dim?: boolean;
   /**
-   * Render in bold.
+   * Bold.
    */
   bold?: boolean;
   /**
-   * Render in italic.
+   * Italic.
    */
   italic?: boolean;
   /**
-   * Render with an underline.
+   * Underline.
    */
   underline?: boolean;
   /**
-   * Render with a strikethrough.
+   * Strikethrough.
    */
   strikethrough?: boolean;
 };
 
 /**
- * Pre-defined style for section titles (e.g. `"Positionals:"`). Bold dark-green.
+ * Section title style. Bold dark-green.
  */
 export const typoStyleTitle: TypoStyle = {
   fgColor: "darkGreen",
   bold: true,
 };
 /**
- * Pre-defined style for logic/type identifiers in error messages. Bold dark-magenta.
+ * Logic/type identifier style. Bold dark-magenta.
  */
 export const typoStyleLogic: TypoStyle = {
   fgColor: "darkMagenta",
   bold: true,
 };
 /**
- * Pre-defined style for quoted user-supplied values in error messages. Bold dark-yellow.
+ * Quoted user-input style. Bold dark-yellow.
  */
 export const typoStyleQuote: TypoStyle = {
   fgColor: "darkYellow",
@@ -78,7 +82,7 @@ export const typoStyleQuote: TypoStyle = {
 };
 
 /**
- * Pre-defined style for failure/error labels (e.g. `"Error:"`). Bold dark-red.
+ * Error label style. Bold dark-red.
  */
 export const typoStyleFailure: TypoStyle = {
   fgColor: "darkRed",
@@ -86,14 +90,14 @@ export const typoStyleFailure: TypoStyle = {
 };
 
 /**
- * Pre-defined style for CLI flag/option/command names. Bold dark-cyan.
+ * Option/command name style. Bold dark-cyan.
  */
 export const typoStyleConstants: TypoStyle = {
   fgColor: "darkCyan",
   bold: true,
 };
 /**
- * Pre-defined style for positional placeholders and user-input labels. Bold dark-blue.
+ * Positional/user-input label style. Bold dark-blue.
  */
 export const typoStyleUserInput: TypoStyle = {
   fgColor: "darkBlue",
@@ -101,13 +105,13 @@ export const typoStyleUserInput: TypoStyle = {
 };
 
 /**
- * Pre-defined style for strong regular text (e.g. command descriptions). Bold.
+ * Strong text style. Bold.
  */
 export const typoStyleRegularStrong: TypoStyle = {
   bold: true,
 };
 /**
- * Pre-defined style for subtle supplementary text (e.g. hints). Italic and dim.
+ * Subtle text style. Italic and dim.
  */
 export const typoStyleRegularWeaker: TypoStyle = {
   italic: true,
@@ -115,8 +119,7 @@ export const typoStyleRegularWeaker: TypoStyle = {
 };
 
 /**
- * An immutable styled string segment: a raw text value paired with a {@link TypoStyle}.
- * Compose multiple segments into a {@link TypoText}; rendering is deferred to {@link TypoString.computeStyledString}.
+ * Immutable styled string segment. Compose into a {@link TypoText}.
  */
 export class TypoString {
   #value: string;
@@ -129,12 +132,6 @@ export class TypoString {
     this.#value = value;
     this.#typoStyle = typoStyle;
   }
-  /**
-   * Returns the unstyled raw text content.
-   */
-  getRawString(): string {
-    return this.#value;
-  }
   /**
    * Returns the text styled by `typoSupport`.
    *
@@ -143,53 +140,46 @@ export class TypoString {
   computeStyledString(typoSupport: TypoSupport): string {
     return typoSupport.computeStyledString(this.#value, this.#typoStyle);
   }
+  /**
+   * Returns the raw text.
+   */
+  getRawString(): string {
+    return this.#value;
+  }
 }
 
 /**
- * A mutable sequence of {@link TypoString} segments forming a styled multi-part message.
- * Rendering is deferred to {@link TypoText.computeStyledString}.
+ * Mutable sequence of {@link TypoString} segments.
  */
 export class TypoText {
   #typoStrings: Array<TypoString>;
   /**
-   * @param typoParts - Initial segments; `TypoText` is flattened, `string` is wrapped unstyled.
+   * @param segments - Initial text segments
    */
-  constructor(...typoParts: Array<TypoText | TypoString | string>) {
+  constructor(
+    ...segments: Array<TypoText | Array<TypoString> | TypoString | string>
+  ) {
     this.#typoStrings = [];
-    for (const typoPart of typoParts) {
-      if (typoPart instanceof TypoText) {
-        this.pushText(typoPart);
-      } else if (typoPart instanceof TypoString) {
-        this.pushString(typoPart);
-      } else if (typeof typoPart === "string") {
-        this.pushString(new TypoString(typoPart));
-      }
-    }
-  }
-  /**
-   * Appends a {@link TypoString} segment.
-   *
-   * @param typoString - Segment to append.
-   */
-  pushString(typoString: TypoString | string) {
-    if (typeof typoString === "string") {
-      this.#typoStrings.push(new TypoString(typoString));
-    } else {
-      this.#typoStrings.push(typoString);
+    for (const typoPart of segments) {
+      this.push(typoPart);
     }
   }
   /**
-   * Appends all segments from another {@link TypoText} (shallow copy).
+   * Appends new text segment(s).
    *
-   * @param typoText - Source text.
+   * @param segment - Text segment(s) to append.
    */
-  pushText(typoText: TypoText | string) {
-    if (typeof typoText === "string") {
-      this.pushString(typoText);
-    } else {
-      for (const typoString of typoText.#typoStrings) {
+  push(segment: TypoText | Array<TypoString> | TypoString | string) {
+    if (typeof segment === "string") {
+      this.#typoStrings.push(new TypoString(segment));
+    } else if (segment instanceof TypoText) {
+      this.#typoStrings.push(...segment.#typoStrings);
+    } else if (Array.isArray(segment)) {
+      for (const typoString of segment) {
         this.#typoStrings.push(typoString);
       }
+    } else {
+      this.#typoStrings.push(segment);
     }
   }
   /**
@@ -204,13 +194,13 @@ export class TypoText {
       .join("");
   }
   /**
-   * Returns the concatenation of all segments' raw (unstyled) text.
+   * Returns the concatenated raw text.
    */
   computeRawString(): string {
     return this.#typoStrings.map((t) => t.getRawString()).join("");
   }
   /**
-   * Returns the total character count of the raw (unstyled) text.
+   * Returns the total raw character count.
    */
   computeRawLength(): number {
     let length = 0;
@@ -222,9 +212,8 @@ export class TypoText {
 }
 
 /**
- * A column-aligned grid of {@link TypoText} cells.
+ * Column-aligned grid of {@link TypoText} cells.
  * Each column is padded to the widest cell (raw chars); the last column is not padded.
- * Used by {@link usageToStyledLines} to render `Positionals:`, `Subcommands:`, and `Options:`.
  */
 export class TypoGrid {
   #typoRows: Array<Array<TypoText>>;
@@ -232,7 +221,7 @@ export class TypoGrid {
     this.#typoRows = [];
   }
   /**
-   * Appends a row. All rows should have the same cell count for alignment to be meaningful.
+   * Appends a row. All rows should have the same cell count.
    *
    * @param cells - Ordered {@link TypoText} cells.
    */
@@ -240,15 +229,14 @@ export class TypoGrid {
     this.#typoRows.push(cells);
   }
   /**
-   * Renders the grid as a 2-D array of styled (and column-padded) strings.
-   * Join each inner array with `""` to get a line.
+   * Renders as an array of styled, column-padded strings.
    *
    * @param typoSupport - Rendering mode.
-   * @returns 2-D array of styled strings.
+   * @returns Array of styled strings.
    */
-  computeStyledGrid(typoSupport: TypoSupport): Array<Array<string>> {
+  computeStyledLines(typoSupport: TypoSupport): Array<string> {
     const widths = new Array<number>();
-    const printableGrid = new Array<Array<string>>();
+    const styledLines = new Array<string>();
     for (const typoGridRow of this.#typoRows) {
       for (
         let typoGridColumnIndex = 0;
@@ -266,31 +254,29 @@ export class TypoGrid {
       }
     }
     for (const typoGridRow of this.#typoRows) {
-      const printableGridRow = new Array<string>();
+      const styledGridRow = new Array<string>();
       for (
         let typoGridColumnIndex = 0;
         typoGridColumnIndex < typoGridRow.length;
         typoGridColumnIndex++
       ) {
         const typoGridCell = typoGridRow[typoGridColumnIndex]!;
-        const printableGridCell = typoGridCell.computeStyledString(typoSupport);
-        printableGridRow.push(printableGridCell);
+        styledGridRow.push(typoGridCell.computeStyledString(typoSupport));
         if (typoGridColumnIndex < typoGridRow.length - 1) {
           const width = typoGridCell.computeRawLength();
           const padding = " ".repeat(widths[typoGridColumnIndex]! - width);
-          printableGridRow.push(padding);
+          styledGridRow.push(padding);
         }
       }
-      printableGrid.push(printableGridRow);
+      styledLines.push(styledGridRow.join(""));
     }
-    return printableGrid;
+    return styledLines;
   }
 }
 
 /**
  * `Error` subclass with a {@link TypoText} styled message for rich terminal output.
- * Used throughout the library for parse failures (unknown option, type decode error, etc.).
- * If `source` is a `TypoError`, its styled text is chained after `": "`.
+ * Chains `TypoError` sources after `": "`.
  */
 export class TypoError extends Error {
   #typoText: TypoText;
@@ -300,20 +286,20 @@ export class TypoError extends Error {
    */
   constructor(currentTypoText: TypoText, source?: unknown) {
     const typoText = new TypoText();
-    typoText.pushText(currentTypoText);
+    typoText.push(currentTypoText);
     if (source instanceof TypoError) {
-      typoText.pushString(new TypoString(": "));
-      typoText.pushText(source.#typoText);
+      typoText.push(new TypoString(": "));
+      typoText.push(source.#typoText);
     } else if (source instanceof Error) {
-      typoText.pushString(new TypoString(`: ${source.message}`));
+      typoText.push(new TypoString(`: ${source.message}`));
     } else if (source !== undefined) {
-      typoText.pushString(new TypoString(`: ${String(source)}`));
+      typoText.push(new TypoString(`: ${String(source)}`));
     }
     super(typoText.computeRawString());
     this.#typoText = typoText;
   }
   /**
-   * Renders the styled error message (without a `"Error:"` prefix).
+   * Renders the styled message (without `"Error:"` prefix).
    *
    * @param typoSupport - Rendering mode.
    * @returns Styled error string.
@@ -322,8 +308,7 @@ export class TypoError extends Error {
     return this.#typoText.computeStyledString(typoSupport);
   }
   /**
-   * Runs `thrower`; on any throw wraps it as a `TypoError` with `context()` prepended.
-   * Useful for adding call-chain context (e.g. `"at 0: Number: ..."`).
+   * Runs `thrower`; wraps any thrown error as a `TypoError` with `context()` prepended.
    *
    * @typeParam Value - Return type of `thrower`.
    * @param thrower - Function to execute; result passed through on success.
@@ -344,9 +329,7 @@ export class TypoError extends Error {
 }
 
 /**
- * Controls ANSI terminal styling for {@link TypoString}, {@link TypoText}, and error rendering.
- * Create via {@link TypoSupport.none}, {@link TypoSupport.tty}, {@link TypoSupport.mock},
- * or {@link TypoSupport.inferFromProcess}.
+ * Controls ANSI terminal styling. Create via the static factory methods.
  */
 export class TypoSupport {
   #kind: "none" | "tty" | "mock";
@@ -354,49 +337,50 @@ export class TypoSupport {
     this.#kind = kind;
   }
   /**
-   * Returns a `TypoSupport` that strips all styling (plain text, no ANSI codes).
+   * Plain text — no ANSI codes.
    */
   static none(): TypoSupport {
     return new TypoSupport("none");
   }
   /**
-   * Returns a `TypoSupport` that applies ANSI escape codes (for color-capable terminals).
+   * ANSI escape codes for color terminals.
    */
   static tty(): TypoSupport {
     return new TypoSupport("tty");
   }
   /**
-   * Returns a `TypoSupport` with deterministic textual styling for snapshot tests.
-   * Style flags appear as suffixes: `{text}@color`, `{text}+` (bold), `{text}-` (dim),
-   * `{text}*` (italic), `{text}_` (underline), `{text}~` (strikethrough).
+   * Deterministic textual styling for snapshot tests.
    */
   static mock(): TypoSupport {
     return new TypoSupport("mock");
   }
   /**
-   * Auto-detects styling mode from the process environment.
-   * `FORCE_COLOR=0` / `NO_COLOR` → none; `FORCE_COLOR` (truthy) / `isTTY` → tty; else → none.
-   * Falls back to none if `process` is unavailable.
+   * Auto-detects styling mode from the process environment on best-effort basis.
    */
-  static inferFromProcess(): TypoSupport {
-    if (!process) {
+  static inferFromEnv(): TypoSupport {
+    if (!process || !process.env) {
       return TypoSupport.none();
     }
-    if (process.env) {
-      if (process.env["FORCE_COLOR"] === "0") {
-        return TypoSupport.none();
-      }
-      if (process.env["FORCE_COLOR"]) {
-        return TypoSupport.tty();
-      }
-      if ("NO_COLOR" in process.env) {
-        return TypoSupport.none();
+    function readEnvVar(name: string) {
+      if (!(name in process.env)) {
+        return undefined;
       }
+      return process.env[name];
     }
-    if (process.stdout && process.stdout.isTTY) {
-      return TypoSupport.tty();
+    const envForceColor = readEnvVar("FORCE_COLOR");
+    if (envForceColor === "0") {
+      return TypoSupport.none();
+    }
+    if (envForceColor !== undefined) {
+      TypoSupport.tty();
+    }
+    if (readEnvVar("NO_COLOR") !== undefined) {
+      return TypoSupport.none();
     }
-    return TypoSupport.none();
+    if (readEnvVar("MOCK_COLOR") !== undefined) {
+      return TypoSupport.mock();
+    }
+    return TypoSupport.tty();
   }
   /**
    * Applies `typoStyle` to `value` according to the current mode.
@@ -406,8 +390,15 @@ export class TypoSupport {
    * @returns Styled string.
    */
   computeStyledString(value: string, typoStyle: TypoStyle): string {
+    let styledValue = value;
+    if (typoStyle.case === "upper") {
+      styledValue = styledValue.toUpperCase();
+    }
+    if (typoStyle.case === "lower") {
+      styledValue = styledValue.toLowerCase();
+    }
     if (this.#kind === "none") {
-      return value;
+      return styledValue;
     }
     if (this.#kind === "tty") {
       const fgColorCode = typoStyle.fgColor
@@ -423,12 +414,12 @@ export class TypoSupport {
       const strikethroughCode = typoStyle.strikethrough
         ? ttyCodeStrikethrough
         : "";
-      return `${fgColorCode}${bgColorCode}${boldCode}${dimCode}${italicCode}${underlineCode}${strikethroughCode}${value}${ttyCodeReset}`;
+      return `${fgColorCode}${bgColorCode}${boldCode}${dimCode}${italicCode}${underlineCode}${strikethroughCode}${styledValue}${ttyCodeReset}`;
     }
     if (this.#kind === "mock") {
       const fgColorPart = typoStyle.fgColor
-        ? `{${value}}@${typoStyle.fgColor}`
-        : value;
+        ? `{${styledValue}}@${typoStyle.fgColor}`
+        : styledValue;
       const bgColorPart = typoStyle.bgColor
         ? `{${fgColorPart}}#${typoStyle.bgColor}`
         : fgColorPart;