termark 2.1.0 → 3.0.0

package/dist/__internal/styling.d.mts

@@ -0,0 +1,115 @@
+//#region src/__internal/styling.d.ts
+/**
+* Built-in styles.
+*/
+declare const BUILT_INS: {
+  readonly reset: readonly [0, 0];
+  readonly bold: readonly [1, 22];
+  readonly dim: readonly [2, 22];
+  readonly italic: readonly [3, 23];
+  readonly underline: readonly [4, 24];
+  readonly blink: readonly [5, 25];
+  readonly inverse: readonly [7, 27];
+  readonly overline: readonly [53, 55];
+  readonly hidden: readonly [8, 28];
+  readonly strike: readonly [9, 29];
+  readonly black: readonly [30, 39];
+  readonly red: readonly [31, 39];
+  readonly green: readonly [32, 39];
+  readonly yellow: readonly [33, 39];
+  readonly blue: readonly [34, 39];
+  readonly magenta: readonly [35, 39];
+  readonly cyan: readonly [36, 39];
+  readonly white: readonly [37, 39];
+  readonly bgBlack: readonly [40, 49];
+  readonly bgRed: readonly [41, 49];
+  readonly bgGreen: readonly [42, 49];
+  readonly bgYellow: readonly [43, 49];
+  readonly bgBlue: readonly [44, 49];
+  readonly bgMagenta: readonly [45, 49];
+  readonly bgCyan: readonly [46, 49];
+  readonly bgWhite: readonly [47, 49];
+  readonly brightBlack: readonly [90, 39];
+  readonly grey: readonly [90, 39];
+  readonly gray: readonly [90, 39];
+  readonly brightRed: readonly [91, 39];
+  readonly brightGreen: readonly [92, 39];
+  readonly brightYellow: readonly [93, 39];
+  readonly brightBlue: readonly [94, 39];
+  readonly brightMagenta: readonly [95, 39];
+  readonly brightCyan: readonly [96, 39];
+  readonly brightWhite: readonly [97, 39];
+  readonly bgBrightBlack: readonly [100, 49];
+  readonly bgGrey: readonly [100, 49];
+  readonly bgGray: readonly [100, 49];
+  readonly bgBrightRed: readonly [101, 49];
+  readonly bgBrightGreen: readonly [102, 49];
+  readonly bgBrightYellow: readonly [103, 49];
+  readonly bgBrightBlue: readonly [104, 49];
+  readonly bgBrightMagenta: readonly [105, 49];
+  readonly bgBrightCyan: readonly [106, 49];
+  readonly bgBrightWhite: readonly [107, 49];
+};
+/**
+* Styles for the borders of {@linkcode box}.
+*/
+declare const BOX_BORDERS: {
+  readonly sharp: {
+    readonly tl: "┌";
+    readonly tr: "┐";
+    readonly bl: "└";
+    readonly br: "┘";
+    readonly h: "─";
+    readonly v: "│";
+  };
+  readonly rounded: {
+    readonly tl: "╭";
+    readonly tr: "╮";
+    readonly bl: "╰";
+    readonly br: "╯";
+    readonly h: "─";
+    readonly v: "│";
+  };
+  readonly double: {
+    readonly tl: "╔";
+    readonly tr: "╗";
+    readonly bl: "╚";
+    readonly br: "╝";
+    readonly h: "═";
+    readonly v: "║";
+  };
+  readonly heavy: {
+    readonly tl: "┏";
+    readonly tr: "┓";
+    readonly bl: "┗";
+    readonly br: "┛";
+    readonly h: "━";
+    readonly v: "┃";
+  };
+  readonly dashed: {
+    readonly tl: "┌";
+    readonly tr: "┐";
+    readonly bl: "└";
+    readonly br: "┘";
+    readonly h: "⹀";
+    readonly v: "╎";
+  };
+  readonly dotted: {
+    readonly tl: "┌";
+    readonly tr: "┐";
+    readonly bl: "└";
+    readonly br: "┘";
+    readonly h: "╌";
+    readonly v: "┊";
+  };
+  readonly ascii: {
+    readonly tl: "+";
+    readonly tr: "+";
+    readonly bl: "+";
+    readonly br: "+";
+    readonly h: "-";
+    readonly v: "|";
+  };
+};
+//#endregion
+export { BOX_BORDERS, BUILT_INS };

package/dist/__internal/styling.mjs

@@ -0,0 +1 @@
+import{formatForNesting as e,toFormatter as t}from"./format.mjs";import{getColourLevel as n,hasNoColour as r}from"./env.mjs";import{clamp as i,hexColourRegex as a,interpolate as o}from"./util.mjs";import{ansi256To4bit as s,hexToRgb as c,rgbToAnsi256 as l}from"./conversion.mjs";const u={reset:[0,0],bold:[1,22],dim:[2,22],italic:[3,23],underline:[4,24],blink:[5,25],inverse:[7,27],overline:[53,55],hidden:[8,28],strike:[9,29],black:[30,39],red:[31,39],green:[32,39],yellow:[33,39],blue:[34,39],magenta:[35,39],cyan:[36,39],white:[37,39],bgBlack:[40,49],bgRed:[41,49],bgGreen:[42,49],bgYellow:[43,49],bgBlue:[44,49],bgMagenta:[45,49],bgCyan:[46,49],bgWhite:[47,49],brightBlack:[90,39],grey:[90,39],gray:[90,39],brightRed:[91,39],brightGreen:[92,39],brightYellow:[93,39],brightBlue:[94,39],brightMagenta:[95,39],brightCyan:[96,39],brightWhite:[97,39],bgBrightBlack:[100,49],bgGrey:[100,49],bgGray:[100,49],bgBrightRed:[101,49],bgBrightGreen:[102,49],bgBrightYellow:[103,49],bgBrightBlue:[104,49],bgBrightMagenta:[105,49],bgBrightCyan:[106,49],bgBrightWhite:[107,49]},d={sharp:{tl:`┌`,tr:`┐`,bl:`└`,br:`┘`,h:`─`,v:`│`},rounded:{tl:`╭`,tr:`╮`,bl:`╰`,br:`╯`,h:`─`,v:`│`},double:{tl:`╔`,tr:`╗`,bl:`╚`,br:`╝`,h:`═`,v:`║`},heavy:{tl:`┏`,tr:`┓`,bl:`┗`,br:`┛`,h:`━`,v:`┃`},dashed:{tl:`┌`,tr:`┐`,bl:`└`,br:`┘`,h:`⹀`,v:`╎`},dotted:{tl:`┌`,tr:`┐`,bl:`└`,br:`┘`,h:`╌`,v:`┊`},ascii:{tl:`+`,tr:`+`,bl:`+`,br:`+`,h:`-`,v:`|`}};function f(e,r){let i;if(n()===3){let n=e.join(`;`);i=t(r===`fg`?`38;2;${n}`:`48;2;${n}`)}else if(n()===2){let n=l(e);i=t(r===`fg`?`38;5;${n}`:`48;5;${n}`)}else{let n=s(l(e));i=t(r===`fg`?n:n+10)}return i}function p(a,o){if(r()||n()===0)return e=>e;let s=f(a.map(e=>i(e,0,255)),o),c=t(o===`fg`?39:49);return t=>e(t,s,c)}function m(e,t){return a.test(e)?p(c(e),t):e=>e}function h(e,i){return r()||n()===0||e.length===0?e=>e:e.length===1?e.every(e=>typeof e==`string`)?m(e[0],i):p(e[0],i):n=>{let r=e.every(e=>typeof e==`string`)?e.map(e=>c(e)):e,a=r.length,s=Math.min(n.length/(a-1)),l=``,u=t(i===`fg`?39:49);for(let e=0;e<n.length;e++){let t=Math.min(Math.floor(e/s),a-2),c=e%s/s,d=r[t],p=r[t+1],[m,h,g]=o(d,p,c),_=f([m,h,g],i);l+=`${_}${n[e]}${u}`}return l}}function g(a,o){if(r()||n()===0)return e=>e;let c=i(a,0,255),l;if(n()>=2)l=t(o===`fg`?`38;5;${c}`:`48;5;${c}`);else{let e=s(c);l=t(o===`fg`?e:e+10)}let u=t(o===`fg`?39:49);return t=>e(t,l,u)}export{g as $ansi256,h as $gradient,m as $hex,p as $rgb,d as BOX_BORDERS,u as BUILT_INS};

package/dist/__internal/util.cjs

@@ -0,0 +1 @@
+const e=/^#?([a-f\d]{3}|[a-f\d]{6})$/i;function t(e,t,n){return Math.min(Math.max(e,t),n)}function n(e,t,n){return[Math.round(e[0]+n*(t[0]-e[0])),Math.round(e[1]+n*(t[1]-e[1])),Math.round(e[2]+n*(t[2]-e[2]))]}exports.clamp=t,exports.hexColourRegex=e,exports.interpolate=n;

package/dist/__internal/util.mjs

@@ -0,0 +1 @@
+const e=/^#?([a-f\d]{3}|[a-f\d]{6})$/i;function t(e,t,n){return Math.min(Math.max(e,t),n)}function n(e,t,n){return[Math.round(e[0]+n*(t[0]-e[0])),Math.round(e[1]+n*(t[1]-e[1])),Math.round(e[2]+n*(t[2]-e[2]))]}export{t as clamp,e as hexColourRegex,n as interpolate};

package/dist/index.cjs

@@ -1 +1,4 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const e=()=>!process.env.NO_COLOR,r=()=>{const e=process.env.COLORTERM;return{is16bit:!!e&&(e.includes("ansi")&&!e.includes("256")),is256:!!e&&e.includes("ansi256"),isTrueColor:!!e&&(e.includes("truecolor")||e.includes("24bit"))}};function t(r,t,i){if("color"===i&&!e())return e=>e.toString();const o=`[${r}m`,s=`[${t}m`;return e=>{const r=e.toString().trim();return-1===r.indexOf(s)?`${o}${r}${s}`:`${o}${r.replaceAll(s,s+o)}${s}`}}function i(e,r,t){return[Math.round(e[0]+t*(r[0]-e[0])),Math.round(e[1]+t*(r[1]-e[1])),Math.round(e[2]+t*(r[2]-e[2]))]}function o(e,r,t){if("number"!=typeof e)throw new TypeError(`Parameter ${JSON.stringify(e)} must be a finite number, which it currently isn't!`);return Math.min(Math.max(e,r),t)}class s{constructor(){this.areColorsEnabled=e(),this.is8bitEnabled=r().is256,this.is24bitEnabled=r().isTrueColor,this.reset=t(0,0,"format"),this.bold=t(1,22,"format"),this.dim=t(2,22,"format"),this.italic=t(3,23,"format"),this.underline=t(4,24,"format"),this.blink=t(5,25,"format"),this.inverse=t(7,27,"format"),this.overline=t(53,55,"format"),this.hidden=t(8,28,"format"),this.strike=t(9,29,"format"),this.black=t(30,39,"color"),this.red=t(31,39,"color"),this.green=t(32,39,"color"),this.yellow=t(33,39,"color"),this.blue=t(34,39,"color"),this.magenta=t(35,39,"color"),this.cyan=t(36,39,"color"),this.white=t(37,39,"color"),this.blackBright=t(90,39,"color"),this.redBright=t(91,39,"color"),this.greenBright=t(92,39,"color"),this.yellowBright=t(93,39,"color"),this.blueBright=t(94,39,"color"),this.magentaBright=t(95,39,"color"),this.cyanBright=t(96,39,"color"),this.whiteBright=t(97,39,"color"),this.bgBlack=t(40,49,"color"),this.bgRed=t(41,49,"color"),this.bgGreen=t(42,49,"color"),this.bgYellow=t(43,49,"color"),this.bgBlue=t(44,49,"color"),this.bgMagenta=t(45,49,"color"),this.bgCyan=t(46,49,"color"),this.bgWhite=t(47,49,"color"),this.bgBlackBright=t(100,49,"color"),this.bgRedBright=t(101,49,"color"),this.bgGreenBright=t(102,49,"color"),this.bgYellowBright=t(103,49,"color"),this.bgBlueBright=t(104,49,"color"),this.bgMagentaBright=t(105,49,"color"),this.bgCyanBright=t(106,49,"color"),this.bgWhiteBright=t(107,49,"color")}static get init(){return new this.termarkInstance}ansi256(i,s){if(!r().is256||!e())return e=>e.toString();s=o(s,0,255);return t("text"===i?`38;5;${s}`:`48;5;${s}`,"text"===i?39:49,"color")}rgb(e,...i){if(!r().isTrueColor)return e=>e.toString();let s,n,l;Array.isArray(i[0])?(s=o(i[0][0],0,255),n=o(i[0][1],0,255),l=o(i[0][2],0,255)):(s=o(i[0],0,255),n=o(i[1],0,255),l=o(i[2],0,255));return t("text"===e?`38;2;${s};${n};${l}`:`48;2;${s};${n};${l}`,"text"===e?39:49,"color")}gradient(t,o){if(!e()||!r().isTrueColor)return e=>e.toString();const s="text"===t?"[38;2;":"[48;2;",n="text"===t?"":"";return e=>{const r=e.toString().trim(),t=o.length,l=Math.min(r.length/(t-1));let g="";for(let e=0;e<r.length;e++){const c=Math.min(Math.floor(e/l),t-2),a=e%l/l,h=i(o[c],o[c+1],a);g+=`${s}${h[0]};${h[1]};${h[2]}m${r[e]}${n}`}return g}}success(e,r=""){console.info(`${s.successPrefix} ${r}${s.init.green(e)}`)}info(e,r=""){console.info(`${s.infoPrefix} ${r}${s.init.blue(e)}`)}warn(e,r=""){console.warn(`${s.warnPrefix} ${r}${s.init.yellow(e)}`)}error(e,r=""){console.error(`${s.errorPrefix} ${r}${s.init.red(e)}`)}custom(e,r,i){return t(e,r,"asColor"===i?"color":"format")}static createTheme(...e){const r=[];return e.forEach(e=>r.push(e)),e=>{const t=e.toString();return r.reduce((e,r)=>r(e),t)}}static createLogger(e){var r,t,i,o,n,l,g,c;const a=void 0===(null===(r=e.success)||void 0===r?void 0:r.prefix)||""===e.success.prefix?s.successPrefix:!1===e.success.prefix?"":e.success.prefix,h=void 0===(null===(t=e.info)||void 0===t?void 0:t.prefix)||""===e.info.prefix?s.infoPrefix:!1===e.info.prefix?"":e.info.prefix,b=void 0===(null===(i=e.warn)||void 0===i?void 0:i.prefix)||""===e.warn.prefix?s.warnPrefix:!1===e.warn.prefix?"":e.warn.prefix,x=void 0===(null===(o=e.error)||void 0===o?void 0:o.prefix)||""===e.error.prefix?s.errorPrefix:!1===e.error.prefix?"":e.error.prefix,u=s.createTheme(...e.default),d=s.createTheme(...void 0!==(null===(n=e.success)||void 0===n?void 0:n.styles)&&0!==e.success.styles.length?e.success.styles:[s.init.green]),p=s.createTheme(...void 0!==(null===(l=e.info)||void 0===l?void 0:l.styles)&&0!==e.info.styles.length?e.info.styles:[s.init.blue]),f=s.createTheme(...void 0!==(null===(g=e.warn)||void 0===g?void 0:g.styles)&&0!==e.warn.styles.length?e.warn.styles:[s.init.yellow]),B=s.createTheme(...void 0!==(null===(c=e.error)||void 0===c?void 0:c.styles)&&0!==e.error.styles.length?e.error.styles:[s.init.red]);return{log(e,r=""){console.log(`${r}${u(e)}`)},success(e,r=""){console.info(`${a?a+" ":""}${r}${d(e)}`)},info(e,r=""){console.info(`${h?h+" ":""}${r}${p(e)}`)},warn(e,r=""){console.info(`${b?b+" ":""}${r}${f(e)}`)},error(e,r=""){console.info(`${x?x+" ":""}${r}${B(e)}`)}}}}s.termarkInstance=s,s.successPrefix=s.init.green(s.init.bold("[✓]")),s.infoPrefix=s.init.blue(s.init.bold("[i]")),s.warnPrefix=s.init.yellow(s.init.bold("[!]")),s.errorPrefix=s.init.red(s.init.bold("[X]"));const n=s.init,{areColorsEnabled:l,is8bitEnabled:g,is24bitEnabled:c,reset:a,bold:h,dim:b,italic:x,underline:u,blink:d,inverse:p,overline:f,hidden:B,strike:m,black:$,red:w,green:y,yellow:v,blue:k,magenta:C,cyan:M,white:T,blackBright:P,redBright:E,greenBright:R,yellowBright:O,blueBright:S,magentaBright:G,cyanBright:W,whiteBright:Y,bgBlack:L,bgRed:A,bgGreen:_,bgYellow:I,bgBlue:N,bgMagenta:j,bgCyan:J,bgWhite:X,bgBlackBright:q,bgRedBright:z,bgGreenBright:D,bgYellowBright:F,bgBlueBright:H,bgMagentaBright:K,bgCyanBright:Q,bgWhiteBright:U,ansi256:V,rgb:Z,gradient:ee,success:re,info:te,warn:ie,error:oe,custom:se}=n,{createTheme:ne,createLogger:le}=s;exports.Termark=s,exports.ansi256=V,exports.areColorsEnabled=l,exports.bgBlack=L,exports.bgBlackBright=q,exports.bgBlue=N,exports.bgBlueBright=H,exports.bgCyan=J,exports.bgCyanBright=Q,exports.bgGreen=_,exports.bgGreenBright=D,exports.bgMagenta=j,exports.bgMagentaBright=K,exports.bgRed=A,exports.bgRedBright=z,exports.bgWhite=X,exports.bgWhiteBright=U,exports.bgYellow=I,exports.bgYellowBright=F,exports.black=$,exports.blackBright=P,exports.blink=d,exports.blue=k,exports.blueBright=S,exports.bold=h,exports.createLogger=le,exports.createTheme=ne,exports.custom=se,exports.cyan=M,exports.cyanBright=W,exports.default=n,exports.dim=b,exports.error=oe,exports.gradient=ee,exports.green=y,exports.greenBright=R,exports.hidden=B,exports.info=te,exports.inverse=p,exports.is24bitEnabled=c,exports.is8bitEnabled=g,exports.italic=x,exports.magenta=C,exports.magentaBright=G,exports.overline=f,exports.red=w,exports.redBright=E,exports.reset=a,exports.rgb=Z,exports.strike=m,exports.success=re,exports.underline=u,exports.warn=ie,exports.white=T,exports.whiteBright=Y,exports.yellow=v,exports.yellowBright=O;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./__internal/env.cjs`),t=require(`./__internal/styling.cjs`),n=require(`./__internal/impl.cjs`),r=require(`./utilities.cjs`),i=n.createProxy(new n.TermarkImpl);function a(...e){let t={};for(let n of e)Object.assign(t,n(i));return n.createProxy(new n.TermarkImpl,t)}function o(e,n={}){let{kind:i=`sharp`,style:a=e=>e,padding:o=1,margin:s=0}=n,c=t.BOX_BORDERS[i],l=Math.floor(o/4),u=Math.floor(s/4),d=e.split(`
+`),f=d.map(e=>r.stripAnsi(e).length),p=Math.max(...f),m=c.tl+c.h.repeat(p+o*2)+c.tr,h=c.bl+c.h.repeat(p+o*2)+c.br,g=` `.repeat(s),_=`
+`.repeat(u),v=g+a(m)+g,y=g+a(h)+g,b=g+a(c.v),x=a(c.v)+g;return`${_}${v}\n${d.map(e=>{let t=r.stripAnsi(e),n=e+` `.repeat(p-t.length),i=b+` `.repeat(o*2+t.length)+x,a=l===0?``:`${i}\n`.repeat(l),s=l===0?``:`\n${i}`.repeat(l),c=` `.repeat(o);return`${a}${b}${c}${n}${c}${x}${s}`}).join(`
+`)}\n${y}${_}`}function s(e,t){let n={};for(let t in e){let r=e[t];n[t]=i.hex(r)}if(t)for(let t in e){let r=e[t],a=`bg${t.slice(0,1).toUpperCase()}${t.slice(1)}`;n[a]=i.hex(r)}return a(()=>({...n}))}exports.ansiLowerCase=r.ansiLowerCase,exports.ansiUpperCase=r.ansiUpperCase,exports.areColoursSupported=r.areColoursSupported,exports.box=o,exports.extend=a,exports.fmt=i,exports.fromColObject=s,exports.getColourLevel=e.getColourLevel,exports.hasNoColour=e.hasNoColour,exports.stripAnsi=r.stripAnsi,exports.supports=r.supports,exports.supportsAtMost=r.supportsAtMost,exports.transformPreserveAnsi=r.transformPreserveAnsi;

package/dist/index.d.cts

@@ -0,0 +1 @@
+export type * from './index.d.mts'

package/dist/index.d.mts

@@ -0,0 +1,161 @@
+import { ANSICode, BoxOptions, BuiltIn, ColourLevel, ColourObject, FromColObjectReturn, LinkFn, MiscellaneousFns, ParamStyling, RGB, StyleElement, StyleFn, TermarkAPI, TermarkToJSONReturn, Terminator } from "./types.mjs";
+import { getColourLevel, hasNoColour } from "./__internal/env.mjs";
+import { ansiLowerCase, ansiUpperCase, areColoursSupported, stripAnsi, supports, supportsAtMost, transformPreserveAnsi } from "./utilities.mjs";
+
+//#region src/index.d.ts
+/**
+* Style some text for terminal output.
+*
+* @example
+* ```ts
+* import { fmt } from "termark";
+*
+* const styled = fmt.bold.green.italic("Text");
+*
+* console.log(styled);
+* // => "Text" printed in bold, green (if colours are supported/enabled), and italic.
+* ```
+*
+* Each member of the chain can be called by passing a string, or can be accessed to apply further styling.
+* Use `.text()` to finally terminate the styling.
+*
+* @example Terminating the chain with `.text()`
+* ```ts
+* import { fmt } from "termark";
+*
+* const styled = fmt.underline.bgBlue.black.text("Text");
+*
+* console.log(styled);
+* // => "Text" printed in black with a blue background (for both: if colours are supported/enabled) and underlined.
+* ```
+*
+* `.text()` is primarily for methods such as `hex`, `rgb`, or `gradient`, that would be inconvenient to use without it.
+*
+* @example `.text()` on `hex` vs. not using `.text()`
+* ```ts
+* import { fmt } from "termark";
+*
+* const custom = fmt.hex("#ffa500").text("orange");
+*
+* // Not using `.text()` is also possible, but less elegant:
+*
+* const withoutTextCall = fmt.hex("#80b3ff")("Text");
+* ```
+*/
+declare const fmt: TermarkAPI;
+/**
+* Extend the functionality of Termark with custom methods.
+*
+* > **Note:** Methods created this way can be called as the last item in the chain only.
+*
+* @example Creating a `shout` method
+* ```ts
+* import { extend, ansiUpperCase } from "termark";
+*
+* const myLib = extend((base) => ({
+*      shout: (str) => base.bold.red(ansiUpperCase(str)),
+* }));
+*
+* console.log(
+*      myLib.shout("this text is red, bold, and uppercase!"),
+*      myLib.italic.shout("works in the chain, too!")
+* );
+* ```
+*
+* > **Note:** Methods that transform text instead of merely style it need to use {@linkcode transformAnsi} or a
+* function derived from it to work with nesting properly.
+*
+* @example Creating a custom colour method
+* ```ts
+* import { extend } from "termark";
+*
+* const myLib = extend((base) => ({
+*      orange: (str) => base.hex("#ffa500").text(str),
+* }));
+*
+* console.log(
+*      myLib.orange("This is orange text"),
+*      myLib.bold.italic.orange("Bold, italic and orange text")
+* );
+* ```
+*
+* @param factories An array of functions returning custom methods that can be accessed from the return-value of
+* `extend`.
+*/
+declare function extend<M extends Record<string, StyleFn>>(...factories: ((base: TermarkAPI) => M)[]): TermarkAPI<M>;
+/**
+* Create a box around some text.
+*
+* @example
+* ```ts
+* import { box } from "termark";
+*
+* const boxed = box("This text will be in a box")
+*
+* console.log(boxed);
+*
+* // Returned:
+* // ┌────────────────────────────┐
+* // │ This text will be in a box │
+* // └────────────────────────────┘
+* ```
+*
+* @param text The text within the box.
+* @param options Configuration options.
+*/
+declare function box(text: string, options?: BoxOptions): string;
+/**
+* Generate colour-styling from an object literal. This primarily exists for use with
+* [`css-color-names`](https://github.com/bahamas10/css-color-names).
+*
+* Because this function uses {@linkcode extend} under the hood, colour methods created this way must be called as the
+* last one in the chain.
+*
+* @example Using `css-color-names`
+* ```ts
+* import cssColours from "css-color-names";
+* import { fromColObject } from "termark";
+*
+* const css = fromColObject(cssColours);
+*
+* console.log(
+*      css.lemonchiffron("This text uses a CSS colour!"),
+*      css.bold.aliceblue("Works with other styles")
+* );
+* ```
+*
+* @example Enabling background colours
+* ```ts
+* import cssColours from "css-color-names";
+* import { fromColObject } from "termark";
+*
+* const cssWithBg = fromColObject(cssColours, true);
+* ```
+*
+* @example Using [`color-names`](https://github.com/meodai/color-names)
+* ```ts
+* import { colornames } from "color-name-list";
+* import { fromColObject } from "termark";
+*
+* const mapped = colornames.reduce((acc, { name, hex }) => {
+*     acc[name] = hex;
+*     return acc;
+* }, {});
+*
+* const colours = fromColObject(mapped);
+*
+* console.log(
+*      colours["100 Mph"]("This colour is from color-names"),
+*      colours.italic.Alaska("...")
+* );
+* ```
+*
+* @param obj An object whose keys are colour names (which will be used as the method name) and whose values are
+* hex colour codes.
+* @param generateBg Whether to generate background styling for all supplied colours. These will have the format
+* `bgColourName` where `ColourName` is the original name of the colour, capitalized. This name is not formatted,
+* so a name like `100 Mph` will retain its spaces.
+*/
+declare function fromColObject<R extends ColourObject, GenBg extends boolean | undefined = undefined>(obj: R, generateBg?: GenBg): TermarkAPI<FromColObjectReturn<R, GenBg>>;
+//#endregion
+export { ANSICode, BoxOptions, BuiltIn, ColourLevel, ColourObject, FromColObjectReturn, LinkFn, MiscellaneousFns, ParamStyling, RGB, StyleElement, StyleFn, TermarkAPI, TermarkToJSONReturn, Terminator, ansiLowerCase, ansiUpperCase, areColoursSupported, box, extend, fmt, fromColObject, getColourLevel, hasNoColour, stripAnsi, supports, supportsAtMost, transformPreserveAnsi };

package/dist/index.mjs

@@ -1 +1,4 @@
-const r=()=>!process.env.NO_COLOR,e=()=>{const r=process.env.COLORTERM;return{is16bit:!!r&&(r.includes("ansi")&&!r.includes("256")),is256:!!r&&r.includes("ansi256"),isTrueColor:!!r&&(r.includes("truecolor")||r.includes("24bit"))}};function i(e,i,t){if("color"===t&&!r())return r=>r.toString();const o=`[${e}m`,n=`[${i}m`;return r=>{const e=r.toString().trim();return-1===e.indexOf(n)?`${o}${e}${n}`:`${o}${e.replaceAll(n,n+o)}${n}`}}function t(r,e,i){return[Math.round(r[0]+i*(e[0]-r[0])),Math.round(r[1]+i*(e[1]-r[1])),Math.round(r[2]+i*(e[2]-r[2]))]}function o(r,e,i){if("number"!=typeof r)throw new TypeError(`Parameter ${JSON.stringify(r)} must be a finite number, which it currently isn't!`);return Math.min(Math.max(r,e),i)}class n{constructor(){this.areColorsEnabled=r(),this.is8bitEnabled=e().is256,this.is24bitEnabled=e().isTrueColor,this.reset=i(0,0,"format"),this.bold=i(1,22,"format"),this.dim=i(2,22,"format"),this.italic=i(3,23,"format"),this.underline=i(4,24,"format"),this.blink=i(5,25,"format"),this.inverse=i(7,27,"format"),this.overline=i(53,55,"format"),this.hidden=i(8,28,"format"),this.strike=i(9,29,"format"),this.black=i(30,39,"color"),this.red=i(31,39,"color"),this.green=i(32,39,"color"),this.yellow=i(33,39,"color"),this.blue=i(34,39,"color"),this.magenta=i(35,39,"color"),this.cyan=i(36,39,"color"),this.white=i(37,39,"color"),this.blackBright=i(90,39,"color"),this.redBright=i(91,39,"color"),this.greenBright=i(92,39,"color"),this.yellowBright=i(93,39,"color"),this.blueBright=i(94,39,"color"),this.magentaBright=i(95,39,"color"),this.cyanBright=i(96,39,"color"),this.whiteBright=i(97,39,"color"),this.bgBlack=i(40,49,"color"),this.bgRed=i(41,49,"color"),this.bgGreen=i(42,49,"color"),this.bgYellow=i(43,49,"color"),this.bgBlue=i(44,49,"color"),this.bgMagenta=i(45,49,"color"),this.bgCyan=i(46,49,"color"),this.bgWhite=i(47,49,"color"),this.bgBlackBright=i(100,49,"color"),this.bgRedBright=i(101,49,"color"),this.bgGreenBright=i(102,49,"color"),this.bgYellowBright=i(103,49,"color"),this.bgBlueBright=i(104,49,"color"),this.bgMagentaBright=i(105,49,"color"),this.bgCyanBright=i(106,49,"color"),this.bgWhiteBright=i(107,49,"color")}static get init(){return new this.termarkInstance}ansi256(t,n){if(!e().is256||!r())return r=>r.toString();n=o(n,0,255);return i("text"===t?`38;5;${n}`:`48;5;${n}`,"text"===t?39:49,"color")}rgb(r,...t){if(!e().isTrueColor)return r=>r.toString();let n,s,l;Array.isArray(t[0])?(n=o(t[0][0],0,255),s=o(t[0][1],0,255),l=o(t[0][2],0,255)):(n=o(t[0],0,255),s=o(t[1],0,255),l=o(t[2],0,255));return i("text"===r?`38;2;${n};${s};${l}`:`48;2;${n};${s};${l}`,"text"===r?39:49,"color")}gradient(i,o){if(!r()||!e().isTrueColor)return r=>r.toString();const n="text"===i?"[38;2;":"[48;2;",s="text"===i?"":"";return r=>{const e=r.toString().trim(),i=o.length,l=Math.min(e.length/(i-1));let c="";for(let r=0;r<e.length;r++){const h=Math.min(Math.floor(r/l),i-2),a=r%l/l,g=t(o[h],o[h+1],a);c+=`${n}${g[0]};${g[1]};${g[2]}m${e[r]}${s}`}return c}}success(r,e=""){console.info(`${n.successPrefix} ${e}${n.init.green(r)}`)}info(r,e=""){console.info(`${n.infoPrefix} ${e}${n.init.blue(r)}`)}warn(r,e=""){console.warn(`${n.warnPrefix} ${e}${n.init.yellow(r)}`)}error(r,e=""){console.error(`${n.errorPrefix} ${e}${n.init.red(r)}`)}custom(r,e,t){return i(r,e,"asColor"===t?"color":"format")}static createTheme(...r){const e=[];return r.forEach(r=>e.push(r)),r=>{const i=r.toString();return e.reduce((r,e)=>e(r),i)}}static createLogger(r){var e,i,t,o,s,l,c,h;const a=void 0===(null===(e=r.success)||void 0===e?void 0:e.prefix)||""===r.success.prefix?n.successPrefix:!1===r.success.prefix?"":r.success.prefix,g=void 0===(null===(i=r.info)||void 0===i?void 0:i.prefix)||""===r.info.prefix?n.infoPrefix:!1===r.info.prefix?"":r.info.prefix,u=void 0===(null===(t=r.warn)||void 0===t?void 0:t.prefix)||""===r.warn.prefix?n.warnPrefix:!1===r.warn.prefix?"":r.warn.prefix,f=void 0===(null===(o=r.error)||void 0===o?void 0:o.prefix)||""===r.error.prefix?n.errorPrefix:!1===r.error.prefix?"":r.error.prefix,d=n.createTheme(...r.default),b=n.createTheme(...void 0!==(null===(s=r.success)||void 0===s?void 0:s.styles)&&0!==r.success.styles.length?r.success.styles:[n.init.green]),$=n.createTheme(...void 0!==(null===(l=r.info)||void 0===l?void 0:l.styles)&&0!==r.info.styles.length?r.info.styles:[n.init.blue]),m=n.createTheme(...void 0!==(null===(c=r.warn)||void 0===c?void 0:c.styles)&&0!==r.warn.styles.length?r.warn.styles:[n.init.yellow]),B=n.createTheme(...void 0!==(null===(h=r.error)||void 0===h?void 0:h.styles)&&0!==r.error.styles.length?r.error.styles:[n.init.red]);return{log(r,e=""){console.log(`${e}${d(r)}`)},success(r,e=""){console.info(`${a?a+" ":""}${e}${b(r)}`)},info(r,e=""){console.info(`${g?g+" ":""}${e}${$(r)}`)},warn(r,e=""){console.info(`${u?u+" ":""}${e}${m(r)}`)},error(r,e=""){console.info(`${f?f+" ":""}${e}${B(r)}`)}}}}n.termarkInstance=n,n.successPrefix=n.init.green(n.init.bold("[✓]")),n.infoPrefix=n.init.blue(n.init.bold("[i]")),n.warnPrefix=n.init.yellow(n.init.bold("[!]")),n.errorPrefix=n.init.red(n.init.bold("[X]"));const s=n.init,{areColorsEnabled:l,is8bitEnabled:c,is24bitEnabled:h,reset:a,bold:g,dim:u,italic:f,underline:d,blink:b,inverse:$,overline:m,hidden:B,strike:x,black:w,red:y,green:v,yellow:p,blue:k,magenta:C,cyan:M,white:P,blackBright:T,redBright:E,greenBright:S,yellowBright:O,blueBright:R,magentaBright:G,cyanBright:L,whiteBright:W,bgBlack:Y,bgRed:A,bgGreen:I,bgYellow:N,bgBlue:J,bgMagenta:X,bgCyan:_,bgWhite:j,bgBlackBright:q,bgRedBright:z,bgGreenBright:D,bgYellowBright:F,bgBlueBright:H,bgMagentaBright:K,bgCyanBright:Q,bgWhiteBright:U,ansi256:V,rgb:Z,gradient:rr,success:er,info:ir,warn:tr,error:or,custom:nr}=s,{createTheme:sr,createLogger:lr}=n;export{n as Termark,V as ansi256,l as areColorsEnabled,Y as bgBlack,q as bgBlackBright,J as bgBlue,H as bgBlueBright,_ as bgCyan,Q as bgCyanBright,I as bgGreen,D as bgGreenBright,X as bgMagenta,K as bgMagentaBright,A as bgRed,z as bgRedBright,j as bgWhite,U as bgWhiteBright,N as bgYellow,F as bgYellowBright,w as black,T as blackBright,b as blink,k as blue,R as blueBright,g as bold,lr as createLogger,sr as createTheme,nr as custom,M as cyan,L as cyanBright,s as default,u as dim,or as error,rr as gradient,v as green,S as greenBright,B as hidden,ir as info,$ as inverse,h as is24bitEnabled,c as is8bitEnabled,f as italic,C as magenta,G as magentaBright,m as overline,y as red,E as redBright,a as reset,Z as rgb,x as strike,er as success,d as underline,tr as warn,P as white,W as whiteBright,p as yellow,O as yellowBright};
+import{getColourLevel as e,hasNoColour as t}from"./__internal/env.mjs";import{BOX_BORDERS as n}from"./__internal/styling.mjs";import{TermarkImpl as r,createProxy as i}from"./__internal/impl.mjs";import{ansiLowerCase as a,ansiUpperCase as o,areColoursSupported as s,stripAnsi as c,supports as l,supportsAtMost as u,transformPreserveAnsi as d}from"./utilities.mjs";const f=i(new r);function p(...e){let t={};for(let n of e)Object.assign(t,n(f));return i(new r,t)}function m(e,t={}){let{kind:r=`sharp`,style:i=e=>e,padding:a=1,margin:o=0}=t,s=n[r],l=Math.floor(a/4),u=Math.floor(o/4),d=e.split(`
+`),f=d.map(e=>c(e).length),p=Math.max(...f),m=s.tl+s.h.repeat(p+a*2)+s.tr,h=s.bl+s.h.repeat(p+a*2)+s.br,g=` `.repeat(o),_=`
+`.repeat(u),v=g+i(m)+g,y=g+i(h)+g,b=g+i(s.v),x=i(s.v)+g;return`${_}${v}\n${d.map(e=>{let t=c(e),n=e+` `.repeat(p-t.length),r=b+` `.repeat(a*2+t.length)+x,i=l===0?``:`${r}\n`.repeat(l),o=l===0?``:`\n${r}`.repeat(l),s=` `.repeat(a);return`${i}${b}${s}${n}${s}${x}${o}`}).join(`
+`)}\n${y}${_}`}function h(e,t){let n={};for(let t in e){let r=e[t];n[t]=f.hex(r)}if(t)for(let t in e){let r=e[t],i=`bg${t.slice(0,1).toUpperCase()}${t.slice(1)}`;n[i]=f.hex(r)}return p(()=>({...n}))}export{a as ansiLowerCase,o as ansiUpperCase,s as areColoursSupported,m as box,p as extend,f as fmt,h as fromColObject,e as getColourLevel,t as hasNoColour,c as stripAnsi,l as supports,u as supportsAtMost,d as transformPreserveAnsi};

package/dist/types.d.mts

@@ -0,0 +1,279 @@
+import { BOX_BORDERS, BUILT_INS } from "./__internal/styling.mjs";
+
+//#region src/types.d.ts
+/**
+* Array with red, green, and blue colour values.
+*/
+type RGB = [number, number, number];
+/**
+* A number representing the supported colour level.
+*
+* - `0` — No colours, just black-and-white text.
+* - `1` — Basic 4-bit (16) colours.
+* - `2` — 8-bit (256) colours.
+* - `3` — 24-bit (16m; `truecolor`) colours.
+*/
+type ColourLevel = 0 | 1 | 2 | 3;
+/**
+* How an ANSI code (e.g., the code for making text bold) can be represented.
+*
+* `string | number` allow single numbers such as `21`, but also complex codes like `38;5;203`, which are
+* not representable by a number alone.
+*/
+type ANSICode = string | number;
+interface TermarkToJSONReturn {
+  text: string;
+  openingCodes: string[];
+  closingCodes: string[];
+}
+type StyleFn = (str: string) => string;
+interface StyleElement {
+  open: string;
+  close: string;
+}
+/**
+* Base built-in methods like `red` or `bold`.
+*/
+type BuiltIn = keyof typeof BUILT_INS;
+/**
+* Methods that terminate a styling sequence.
+*/
+interface Terminator {
+  /**
+  * Return a string that has been styled. Useful for methods like `hex` or `gradient`.
+  *
+  * @param str An input string.
+  */
+  text(str: string): string;
+}
+/**
+* Styling functions that take parameters.
+*/
+interface ParamStyling {
+  /**
+  * Colour some text using a hex colour code.
+  *
+  * @example
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const customHex = fmt.hex("#338cd1").text("Text");
+  * ```
+  *
+  * @example Without leading hash (`#`)
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const customHex = fmt.hex("008330").text("Text");
+  * ```
+  *
+  * @param code A hex colour code.
+  */
+  hex(code: string): TermarkAPI;
+  /**
+  * Colour some text using red, green, and blue colour values.
+  *
+  * Each passed value is clamped so that values less than `0` are treated as `0` and values greater than `255` are
+  * treated as `255`.
+  *
+  * @example
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const rgbString = fmt.rgb([128, 5, 243]).text("Text");
+  * ```
+  *
+  * @param colours An array of red, green, and blue colour values.
+  */
+  rgb(colours: RGB): TermarkAPI;
+  /**
+  * Make some text have a gradient.
+  *
+  * @example With hex colour codes
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const textWithGradient = fmt.gradient("#80b3ff", "#338cd1").text("Text");
+  * ```
+  *
+  * @example With RGB values
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const textWithGradient = fmt.gradient([128, 179, 255], [51, 140, 209]).text("Text");
+  * ```
+  *
+  * @param colours Colours for the gradient, either as hex colour codes or as RGB tuples (arrays).
+  */
+  gradient(...colours: string[] | RGB[]): TermarkAPI;
+  /**
+  * Use an ANSI number code to apply a specific colour to some text.
+  *
+  * This value is clamped so that values less than `0` are treated as `0` while values greater than `255` are treated
+  * as `255`.
+  *
+  * @example
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const ansi = fmt.fg(57).text("Text");
+  * ```
+  *
+  * @param code An ANSI code for 8-bit colours.
+  *
+  * @see https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
+  */
+  fg(code: number): TermarkAPI;
+  /**
+  * Colour the background of some text using a hex colour code.
+  *
+  * @example
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const customHex = fmt.bgHex("#338cd1").text("Text");
+  * ```
+  *
+  * @example Without leading hash (`#`)
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const customHex = fmt.bgHex("008330").text("Text");
+  * ```
+  *
+  * @param code A hex colour code.
+  */
+  bgHex(code: string): TermarkAPI;
+  /**
+  * Colour the background of some text using red, green, and blue colour values.
+  *
+  * Each passed value is clamped so that values less than `0` are treated as `0` and values greater than `255` are
+  * treated as `255`.
+  *
+  * @example
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const rgbString = fmt.bgRgb([128, 5, 243]).text("Text");
+  * ```
+  *
+  * @param colours An array of red, green, and blue colour values.
+  */
+  bgRgb(colours: RGB): TermarkAPI;
+  /**
+  * Make the background of some text have a gradient.
+  *
+  * @example With hex colour codes
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const textWithGradient = fmt.bgGradient("#80b3ff", "#338cd1").text("Text");
+  * ```
+  *
+  * @example With RGB values
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const textWithGradient = fmt.bgGradient([128, 179, 255], [51, 140, 209]).text("Text");
+  * ```
+  *
+  * @param colours Colours for the gradient, either as hex colour codes or as RGB tuples (arrays).
+  */
+  bgGradient(...colours: string[] | RGB[]): TermarkAPI;
+  /**
+  * Use an ANSI number code to apply a specific colour to the background of some text.
+  *
+  * This value is clamped so that values less than `0` are treated as `0` while values greater than `255` are treated
+  * as `255`.
+  *
+  * @example
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const ansi = fmt.bg(57).text("Text");
+  * ```
+  *
+  * @param code An ANSI code for 8-bit colours.
+  *
+  * @see https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
+  */
+  bg(code: number): TermarkAPI;
+}
+type LinkFn = (url: string, text?: string) => string;
+/**
+* Miscellaneous features that don't fit other category.
+*/
+interface MiscellaneousFns {
+  /**
+  * Construct an OSC 8 hyperlink by specifying a URL and optionally text to display.
+  *
+  * `link` acts as a style chain terminator and is called as the last element of such a chain.
+  *
+  * [OSC 8](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) may not be supported in all terminal
+  * environments. See ["OSC 8 adoption in terminal emulators"](https://github.com/Alhadis/OSC8-Adoption/) for a list
+  * of terminals that support OSC 8 hyperlinks. In terminals where OSC 8 hyperlinks aren't supported, the URL will
+  * be shown as-is, along with the display text (if one was provided).
+  *
+  * @example
+  * ```ts
+  * import { fmt } from "termark";
+  *
+  * const plainLink = fmt.link("https://q-file.com");
+  *
+  * const styledLink = fmt.red.underline.link("https://q-file.com", "Website");
+  * ```
+  *
+  * @param url A URL to some resource, which can be a webpage (`http://`, `https://`), a local file (`file://`), an
+  * email address (`mailto:`), an FTP connection (`ftp://`), etc.
+  * @param text An optional text to display. If omitted, `url` will be displayed.
+  *
+  * @see https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+  * @see https://notes.billmill.org/programming/bash/Hyperlink_escape_codes.html
+  */
+  link: LinkFn;
+}
+/**
+* The API provided by Termark, including all built-in functions as well as user-created extensions.
+*/
+type TermarkAPI<Ext extends Record<string, any> = {}> = { [K in BuiltIn]: TermarkAPI<Ext> } & Ext & StyleFn & Terminator & ParamStyling & MiscellaneousFns;
+/**
+* Configuration options for {@linkcode box}.
+*/
+interface BoxOptions {
+  /**
+  * @default "sharp"
+  */
+  kind?: keyof typeof BOX_BORDERS;
+  /**
+  * Styling to apply to the border such as making it blue.
+  *
+  * @default (str) => str
+  */
+  style?: StyleFn;
+  /**
+  * Padding to apply. Top-bottom padding will always be a quarter of left-right padding (that is, top-bottom padding
+  * will increase by one for every four padding units).
+  *
+  * @default 0
+  */
+  padding?: number;
+  /**
+  * Spacing around the box. Top-bottom margin will always be a quarter of left-right margin (that is, top-bottom
+  * margin will increase by one for every four margin units).
+  *
+  * @default 0
+  */
+  margin?: number;
+}
+/**
+* Object type to be passed into {@linkcode fromColObject}.
+*
+* Represents an object literal whose keys are colour names and whose values are hex colour codes.
+*/
+type ColourObject = Record<string, string>;
+/**
+* The return-value of {@linkcode fromColObject}.
+*/
+type FromColObjectReturn<R extends ColourObject, GenBg extends boolean | undefined> = { [K in keyof R as K | (GenBg extends true ? `bg${Capitalize<K & string>}` : never)]: StyleFn };
+//#endregion
+export { ANSICode, BoxOptions, BuiltIn, ColourLevel, ColourObject, FromColObjectReturn, LinkFn, MiscellaneousFns, ParamStyling, RGB, StyleElement, StyleFn, TermarkAPI, TermarkToJSONReturn, Terminator };

package/dist/utilities.cjs

@@ -0,0 +1 @@
+const e=require(`./__internal/env.cjs`);function t(){return e.getColourLevel()!==0}function n(t){return e.getColourLevel()>=t}function r(t){return e.getColourLevel()<=t}function i(e){return t=>{let n=/(\u{001B}\[[0-9;]*[A-PRZ])|(.+?)/giu,r=``;for(let i of t.matchAll(n)){let t=i[0];r+=t.charCodeAt(0)===27?t:e(t)}return r}}const a=i(e=>e.toUpperCase()),o=i(e=>e.toLowerCase());function s(e){return e.replace(/\u{001B}\[[0-9;]*m/gu,``)}exports.ansiLowerCase=o,exports.ansiUpperCase=a,exports.areColoursSupported=t,exports.stripAnsi=s,exports.supports=n,exports.supportsAtMost=r,exports.transformPreserveAnsi=i;