termark 3.0.0 → 3.0.1

package/README.md

@@ -22,7 +22,7 @@ Termark is a basic library to format console output to the standard non-browser
 - [**FORCE_COLOR**](https://force-color.org/)-friendly
 - **`truecolor` support** including gradients
 - **Automatic colour-support detection** with **step-wise fallback** (truecolor → 8-bit → 4-bit → plain text)
-- **Extensible** via `extend`; includes **built-in support** for `css-color-names` via `fromColObject`
+- **Extensible** via `extend`; includes built-in support for `css-color-names` via `fromColObject`
 - **Runtime-agnostic** (currently supported: Node, Bun, Deno)
 
 ## Usage
@@ -73,7 +73,9 @@ console.log(fmt.bold.red(`Error: This ${fmt.brightCyan("file")} is corrupted!`))
 
 ### Advanced colouring
 
-Termark features methods like `hex` and `rgb` as well as the powerful `gradient` for advanced, versatile colouring. All of these methods feature `bg*` variants.
+Termark features methods like `hex` and `rgb` as well as the powerful `gradient` for advanced, versatile colouring.
+All of these methods feature `bg*` variants, e.g. `bgHex`, which apply colour to the background of the text rather
+than the text itself.
 
 ```ts
 import { fmt } from "termark";
@@ -98,10 +100,15 @@ import { fmt } from "termark";
 console.log(fmt.fg(57).text("..."));
 ```
 
-**Note:** The `.text()` method is designed for `hex`, `rgb`, `gradient`, and `fg` when they are the last in the chain or when no other styling is needed. However, technically _all_ styling chains can be terminated by `.text()`, e.g., `fmt.bold.red.text("...")`. `.text()` exists to eliminate the need to write `hex("#338cd1")("Coloured text")`, which is still an option, but it's not elegant.
+**Note:** The `.text()` method is designed for `hex`, `rgb`, `gradient` and `fg` (and their `bg*` counterparts) when
+they are the last in the chain or when no other styling is needed. However, technically _all_ styling chains can be
+terminated by `.text()`, e.g. `fmt.bold.red.text("...")`. `.text()` exists to eliminate the need to write
+`hex("#338cd1")("Coloured text")`, which is still an option, but it's not elegant.
 
 ### Layout utilities
 
+#### `box`
+
 Termark features a powerful `box` method which lets you encase your text in a, well, box.
 
 ```ts
@@ -109,14 +116,16 @@ import { fmt, box } from "termark";
 
 const myBox = box(fmt.bold.brightGreen("Deployment successful!"), {
     kind: "rounded",
-    padding: 2, // Vertical padding only increases every four units.
-    margin: 3, // Vertical margin only increases every four units.
+    padding: 2, // Vertical padding only increases every four units by default.
+    margin: 3, // Vertical margin only increases every four units by default.
     style: fmt.hex("#ffa500"), // Orange border
 });
 
 console.log(myBox);
 ```
 
+**Note:** `margin` and `padding` also accept objects to customize top, bottom, left, and right margin/padding.
+
 ### Extensibility
 
 **Note:** All extensions of Termark must be called as the last one in a given chain, and a string must be passed.
@@ -126,23 +135,25 @@ console.log(myBox);
 With the `extend` function, any kind of method can be created as an extension of Termark, such as shortcuts to styles.
 
 ```ts
-import { extend, ansiUpperCase } from "termark";
+import { extend } from "termark";
 
 const myLib = extend((base) => ({
     // Formatting extensions
-    shout: (str) => base.red.bold(ansiUpperCase(str)),
+    shout: (str) => base.red.bold(str.toUpperCase()),
     // Colouring extensions
     orange: (str) => base.hex("#ffa500").text(str),
 }));
 
-console.log(myLib.shout("This text is in red bold and all-caps"));
+console.log(myLib.shout("This text is bold in red and all-caps"));
 ```
 
-**Note:** When transforming text such as making it upper-case, use `transformPreserveAnsi` or a function derived from it (such as `ansiUpperCase` in the above example) if you plan to nest styles. Keep in mind that transformations apply to nested styles, too; for `shout` above, all nested text will be upper-case too by default.
+Transformations apply to nested styles, too; for `shout` above, all nested text will be upper-case.
 
 #### via `fromColObject`
 
-The `fromColObject` function enables mapping mass colour dictionaries into styling methods. Excellent for packages like [`css-color-names`](https://github.com/bahamas10/css-color-names) or [`color-names`](https://github.com/meodai/color-names) (the latter with some additional work).
+The `fromColObject` function enables mapping mass colour dictionaries into styling methods. Excellent for packages
+like [`css-color-names`](https://github.com/bahamas10/css-color-names) or
+[`color-names`](https://github.com/meodai/color-names) (the latter with some additional work).
 
 ```ts
 import { fromColObject } from "termark";
@@ -162,7 +173,8 @@ const withBg = fromColObject(cssColours, true);
 
 ### Hyperlinks
 
-Hyperlinks are achieved by Termark with the help of [OSC 8](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda). Currently, it is non-standard, and may not be supported in every terminal.
+Hyperlinks are achieved by Termark with the help
+of [OSC 8](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda). Currently, it is non-standard, and may not be supported in every terminal.
 
 ```ts
 import { fmt } from "termark";

package/dist/index.cjs

@@ -1,4 +1,5 @@
-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;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e){if(typeof globalThis.process?.env==`object`)return globalThis.process.env[e];if(typeof globalThis.Deno?.env?.get==`function`)try{return globalThis.Deno.env.get(e)}catch{return}}function t(){if(globalThis.process?.stdout?.isTTY)return!0;if(typeof globalThis.Deno?.stdout?.isTerminal==`function`)try{return globalThis.Deno.stdout?.isTerminal()}catch{return!1}return!1}function n(){let t=e(`NO_COLOR`)||e(`NODE_DISABLE_COLORS`);return t!==void 0&&t!==``}function r(){if(n())return 0;let r=e(`FORCE_COLOR`);if(r!==void 0)return r===`0`?0:r===`1`?1:r===`2`?2:r===`3`?3:1;if(!t())return e(`CI`)&&(e(`GITHUB_ACTIONS`)||e(`GITLAB_CI`))?1:0;let i=e(`TERM`);if(i===`dumb`)return 0;let a=e(`COLORTERM`);return a===`truecolor`||a===`24bit`||e(`TERM_PROGRAM`)===`vscode`?3:i&&/-256(color)?$/i.test(i)||e(`TERM_PROGRAM`)===`Apple_Terminal`?2:(i&&/color|ansi|cygwin|linux/i.test(i),1)}const i=/^#?([a-f\d]{3}|[a-f\d]{6})$/i;function a(e,t,n){return Math.min(Math.max(e,t),n)}function o(e,t){if(e.length===1)return e[0];let n=t*(e.length-1),r=Math.min(Math.floor(n),e.length-2),i=n-r,a=e[r],o=e[r+1];return[Math.round(a[0]+(o[0]-a[0])*i),Math.round(a[1]+(o[1]-a[1])*i),Math.round(a[2]+(o[2]-a[2])*i)]}function s(e){return e.slice(0,1).toUpperCase()+e.slice(1)}function c(e){let t=i.exec(e);if(!t)return[255,255,255];let n=t[1].replace(/^#/,``),r=3^n.length?n:n.split(``).map(e=>e+e).join(``),a=parseInt(r,16);return[a>>16&255,a>>8&255,a&255]}function l([e,t,n]){return e^t||t^n?16+36*Math.round(e/51)+6*Math.round(t/51)+Math.round(n/51):e<8?16:e>248?231:Math.round((e-8)*24/247)+232}function u(e){if(e<8)return 30+e;if(e<16)return 82+e;let t,n,r;if(e<232){let i=e-16,a=i%36;t=(i/36|0)/5,n=(a/6|0)/5,r=a%6/5}else t=n=r=((e-232)*10+8)/255;let i=Math.max(t,n,r)*2,a=Math.round(t),o=Math.round(n)<<1,s=Math.round(r)<<2,c=2^i?0:60;return 30+(s|o|a)+c}function d(e){return`\x1b[${e}m`}function f(e,t,n){return e.indexOf(n)===-1?`${t}${e}${n}`:`${t}${e.replaceAll(n,n+t)}${n}`}const p={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]};function m(e,t,n){let r=Array.from(e),i=r.length,a=t?.map(e=>typeof e==`string`?c(e):e),s=n?.map(e=>typeof e==`string`?c(e):e);return r.map((e,t)=>{let n=i>1?t/(i-1):0,r=``,c=``;if(a){let[e,t,i]=o(a,n);r+=`\x1b[38;2;${e};${t};${i}m`,c=`\x1B[39m`+c}if(s){let[e,t,i]=o(s,n);r+=`\x1b[48;2;${e};${t};${i}m`,c=`\x1B[49m`+c}return r+e+c}).join(``)}function h(e){return e.type===`fg`?_(e.code,`fg`):e.type===`bg`?_(e.code,`bg`):e.type===`hex`?y(e.hex,`fg`):e.type===`bgHex`?y(e.hex,`bg`):e.type===`rgb`?v([e.r,e.g,e.b],`fg`):e.type===`bgRgb`?v([e.r,e.g,e.b],`bg`):[``,``]}function g(e,t){let n=t.filter(e=>typeof e!=`string`&&(e.type===`gradient`||e.type===`bgGradient`)),r=n.filter(e=>e.type===`gradient`).at(-1),i=n.filter(e=>e.type===`bgGradient`).at(-1);return t.reduce((t,n)=>{let a=r||i?m(e,r?.colours,i?.colours):t;if(typeof n==`string`)return f(a,d(p[n][0]),d(p[n][1]));{let[e,t]=h(n);return f(a,e,t)}},e)}function _(e,t){if(n()||r()===0)return[``,``];let i=a(e,0,255),o=d(t===`fg`?39:49);if(r()>=2)return[d(t===`fg`?`38;5;${i}`:`48;5;${i}`),o];{let e=u(i);return[d(t===`fg`?e:e+10),o]}}function v(e,t){if(n()||r()===0)return[``,``];let i=e.map(e=>a(e,0,255)),o=d(t===`fg`?39:49);if(r()===3){let e=i.join(`;`);return[d(t===`fg`?`38;2;${e}`:`48;2;${e}`),o]}if(r()===2){let e=l(i);return[d(t===`fg`?`38;5;${e}`:`48;5;${e}`),o]}{let n=u(l(e));return[d(t===`fg`?n:n+10),o]}}function y(e,t){return i.test(e)?v(c(e),t):[``,``]}function b(e,t){let n=`\x1B]8;;`;return`${n}${e}\\${t||e}${n}\\`}function x(e,t){return new Proxy(t=>g(t,e),{get(n,r){return r in p?x([...e,r],t):r===`fg`?n=>x([...e,{type:`fg`,code:n}],t):r===`bg`?n=>x([...e,{type:`bg`,code:n}],t):r===`hex`?n=>x([...e,{type:`hex`,hex:n}],t):r===`bgHex`?n=>x([...e,{type:`bgHex`,hex:n}],t):r===`rgb`?([n,r,i])=>x([...e,{type:`rgb`,r:n,g:r,b:i}],t):r===`bgRgb`?([n,r,i])=>x([...e,{type:`bgRgb`,r:n,g:r,b:i}],t):r===`gradient`?n=>x([...e,{type:`gradient`,colours:n}],t):r===`bgGradient`?n=>x([...e,{type:`bgGradient`,colours:n}],t):r===`link`?(t,n)=>b(t,g(n??t,e)):r===`text`?t=>g(t,e):r in t?n=>g(t[r](n),e):n[r]}})}const S=x([],{});function C(){return r()!==0}function w(e){return r()>=e}function T(e){return r()<=e}function E(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 D=E(e=>e.toUpperCase()),O=E(e=>e.toLowerCase());function k(e){return e.replace(/\u{001B}\[[0-9;]*m/gu,``)}const A={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 j(e,t={}){let{kind:n=`sharp`,style:r=e=>e,padding:i=1,margin:a=0}=t,o=typeof n==`string`?A[n]:n,s=typeof i==`number`?Math.floor(i/4):i.top??0,c=typeof i==`number`?Math.floor(i/4):i.bottom??0,l=typeof a==`number`?Math.floor(a/4):a.top??0,u=typeof a==`number`?Math.floor(a/4):a.bottom??0,d=e.split(`
+`),f=d.map(e=>k(e).length),p=Math.max(...f),m=o.tl+o.h.repeat(p+(typeof i==`number`?i*2:(i.left??0)+(i.right??0)))+o.tr,h=o.bl+o.h.repeat(p+(typeof i==`number`?i*2:(i.left??0)+(i.right??0)))+o.br,g=` `.repeat(typeof a==`number`?a:a.left??0),_=` `.repeat(typeof a==`number`?a:a.right??0),v=`
+`.repeat(l),y=`
+`.repeat(u),b=g+r(m)+_,x=g+r(h)+_,S=g+r(o.v),C=r(o.v)+_;return`${v}${b}\n${d.map(e=>{let t=k(e),n=e+` `.repeat(p-t.length),r=S+` `.repeat((typeof i==`number`?i*2:(i.left??0)+(i.right??0))+t.length)+C,a=i===0?``:`${r}\n`.repeat(s),o=i===0?``:`\n${r}`.repeat(c),l=` `.repeat(typeof i==`number`?i:i.left??0),u=` `.repeat(typeof i==`number`?i:i.right??0);return`${a}${S}${l}${n}${u}${C}${o}`}).join(`
+`)}\n${x}${y}`}function M(e){if(Array.isArray(e)){let t={};for(let n of e)Object.assign(t,n(S));return x([],t)}return x([],e(S))}function N(e,t){let n=Object.entries(e).map(([e,t])=>[e,e=>S.hex(t).text(e)]),r=t?Object.entries(e).map(([e,t])=>[`bg${s(e)}`,e=>S.bgHex(t).text(e)]):null;return M(()=>Object.fromEntries([...n,...r??[]]))}exports.ansiLowerCase=O,exports.ansiUpperCase=D,exports.areColoursSupported=C,exports.box=j,exports.extend=M,exports.fmt=S,exports.termark=S,exports.fromColObject=N,exports.getColorLevel=r,exports.getColourLevel=r,exports.hasNoColor=n,exports.hasNoColour=n,exports.link=b,exports.stripAnsi=k,exports.supports=w,exports.supportsAtMost=T,exports.transformPreserveAnsi=E;

package/dist/index.d.cts

@@ -1 +1,492 @@
-export type * from './index.d.mts'
+type RGB = [r: number, g: number, b: 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 (16 mil; `truecolor`) colours.
+ */
+type ColourLevel = 0 | 1 | 2 | 3;
+type BaseStyle = "reset" | "bold" | "dim" | "italic" | "underline" | "blink" | "inverse" | "overline" | "hidden" | "strike" | "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "bgBlack" | "bgRed" | "bgGreen" | "bgYellow" | "bgBlue" | "bgMagenta" | "bgCyan" | "bgWhite" | "brightBlack" | "grey" | "gray" | "brightRed" | "brightGreen" | "brightYellow" | "brightBlue" | "brightMagenta" | "brightCyan" | "brightWhite" | "bgBrightBlack" | "bgGrey" | "bgGray" | "bgBrightRed" | "bgBrightGreen" | "bgBrightYellow" | "bgBrightBlue" | "bgBrightMagenta" | "bgBrightCyan" | "bgBrightWhite";
+type GradientStyle = {
+  type: "gradient";
+  colours: string[] | RGB[];
+} | {
+  type: "bgGradient";
+  colours: string[] | RGB[];
+};
+type DynamicStyle = {
+  type: "fg";
+  code: number;
+} | {
+  type: "bg";
+  code: number;
+} | {
+  type: "hex";
+  hex: string;
+} | {
+  type: "bgHex";
+  hex: string;
+} | {
+  type: "rgb";
+  r: number;
+  b: number;
+  g: number;
+} | {
+  type: "bgRgb";
+  r: number;
+  b: number;
+  g: number;
+} | GradientStyle;
+type StyleFn = (str: string) => string;
+type AnyStyle = BaseStyle | DynamicStyle;
+type StyleData = [open: string, close: string];
+type Termark<ExtKey extends PropertyKey = string> = { [K in BaseStyle]: Termark<ExtKey>; } & { [K in ExtKey]: StyleFn; } & {
+  /**
+   * Apply a custom colour to the text using an ANSI colour code.
+   *
+   * @param code An ANSI colour code (0–255)
+   */
+  fg(code: number): Termark<ExtKey>;
+  /**
+   * Apply a custom background colour to the text using an ANSI colour code.
+   *
+   * @param code An ANSI colour code (0–255)
+   */
+  bg(code: number): Termark<ExtKey>;
+  /**
+   * Apply a custom colour to the text using a hex colour code.
+   *
+   * @param hex A hex colour code. The preceding `#` symbol is optional.
+   */
+  hex(hex: string): Termark<ExtKey>;
+  /**
+   * Apply a custom background colour to the text using a hex colour code.
+   *
+   * @param hex A hex colour code. The preceding `#` symbol is optional.
+   */
+  bgHex(hex: string): Termark<ExtKey>;
+  /**
+   * Apply a custom colour to the text using an RGB tuple.
+   *
+   * @param col An RGB tuple.
+   */
+  rgb(col: RGB): Termark<ExtKey>;
+  /**
+   * Apply a custom background colour to the text using an RGB tuple.
+   *
+   * @param col An RGB tuple.
+   */
+  bgRgb(col: RGB): Termark<ExtKey>;
+  /**
+   * Set the colour of the text to be a gradient.
+   *
+   * @param cols An array of colours. Each can be either a hex colour code (`#` optional) or an RGB tuple.
+   */
+  gradient(cols: Array<string | RGB>): Termark<ExtKey>;
+  /**
+   * Set the background colour of the text to be a gradient.
+   *
+   * @param cols An array of colours. Each can be either a hex colour code (`#` optional) or an RGB tuple.
+   */
+  bgGradient(cols: Array<string | RGB>): Termark<ExtKey>;
+  /**
+   * Construct an OSC 8 hyperlink.
+   *
+   * **Note:** Whether and how interactive the resulting hyperlink is entirely depends on the current terminal
+   * environment, not all support OSC 8 hyperlinks, especially not ones with custom display text. For a list of which
+   * terminal emulators support OSC 8 hyperlinks, see [here](https://github.com/Alhadis/OSC8-Adoption).
+   *
+   * @example
+   * ```ts
+   * import { fmt } from "termark";
+   *
+   * const l = fmt.link("https://example.com", "Website");
+   * ```
+   *
+   * @example Styling the link
+   * ```ts
+   * import { fmt } from "termark";
+   *
+   * const l = fmt.green.bold.link("https://example.com", "Website");
+   * ```
+   *
+   * @param url The URL the hyperlink points to. Required.
+   * @param text Text to display instead of the URL. Optional; if omitted, `url` is displayed instead.
+   */
+  link(url: string, text?: string): string;
+  /**
+   * Terminate a style chain and apply all collected styles to `input`.
+   *
+   * Can be called by any
+   *
+   * @param input A string to apply styles to.
+   */
+  text(input: string): string;
+} & ((input: string) => string);
+/**
+ * Built-in box border kinds.
+ */
+type BoxBorderKind = "sharp" | "rounded" | "double" | "heavy" | "dashed" | "dotted" | "ascii";
+/**
+ * Type representing an object containing the characters that make up a box border.
+ */
+interface BoxBorder {
+  /**
+   * Top left corner.
+   */
+  tl: string;
+  /**
+   * Top right corner.
+   */
+  tr: string;
+  /**
+   * Bottom left corner.
+   */
+  bl: string;
+  /**
+   * Bottom right corner.
+   */
+  br: string;
+  /**
+   * Top/bottom.
+   */
+  h: string;
+  /**
+   * Left/right.
+   */
+  v: string;
+}
+/**
+ * Custom box spacing (padding/margin). Values are in characters.
+ */
+interface BoxSpacing {
+  /**
+   * @default 0
+   */
+  top?: number;
+  /**
+   * @default 0
+   */
+  bottom?: number;
+  /**
+   * @default 0
+   */
+  left?: number;
+  /**
+   * @default 0
+   */
+  right?: number;
+}
+interface BoxOptions {
+  /**
+   * What the border of the box should be made of.
+   *
+   * This can be a string representing a built-in border style, or an object for custom styling.
+   *
+   * @default "sharp"
+   */
+  kind?: BoxBorderKind | BoxBorder;
+  /**
+   * Styling to apply to the border.
+   *
+   * @example fmt.bold.blue
+   *
+   * @default (str) => str
+   */
+  style?: (str: string) => string;
+  /**
+   * Spacing (in characters) between the border and the content. Can be a number or an object to customize padding.
+   *
+   * When a number is provided, the top-bottom padding will always be a quarter of left-right padding.
+   *
+   * @default 1
+   */
+  padding?: number | BoxSpacing;
+  /**
+   * Spacing (in characters) around the outside of the box. Can be a number or an object to customize margin.
+   *
+   * When a number is provided, the top-bottom margin will always be a quarter of left-right margin.
+   *
+   * @default 0
+   */
+  margin?: number | BoxSpacing;
+}
+type ColourObject = Record<string, string>;
+type FromColObjectReturn<R extends ColourObject, GenBg extends boolean | undefined> = GenBg extends true ? keyof R | `bg${Capitalize<keyof R & string>}` : keyof R;
+/**
+ * Check whether `NO_COLOR` is an existing environment variable with any value that is not an empty string, thereby
+ * disabling colours from being printed.
+ *
+ * This also checks the existence of the `NODE_DISABLE_COLORS` environment variable, behaving the same way if it
+ * exists and not an empty string.
+ *
+ * @see https://no-color.org
+ */
+export declare function hasNoColour(): boolean;
+/**
+ * Get the colour level of the terminal environment.
+ *
+ * @returns {@linkcode ColourLevel}
+ */
+export declare function getColourLevel(): ColourLevel;
+/**
+ * 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, 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");
+ * ```
+ */
+export declare const fmt: Termark;
+/**
+ * Create a box around some text.
+ *
+ * @example
+ * ```ts
+ * import { box } from "termark";
+ *
+ * const boxed = box("This text is boxed in.");
+ * ```
+ *
+ * Use `\n` to split the text along multiple lines.
+ *
+ * ---
+ *
+ * The inner text of the box can be styled with {@linkcode fmt} like regular terminal output.
+ *
+ * @example Styling inner text
+ * ```ts
+ * import { box, fmt } from "termark";
+ *
+ * const boxed = box(fmt.italic.blue("..."));
+ * ```
+ *
+ * ---
+ *
+ * The look of the box can be customized too, using the `options` parameter.
+ *
+ * @example Styling box
+ * ```ts
+ * import { box, fmt } from "termark";
+ *
+ * const boxed = box("...", {
+ *      kind: "rounded", // can be an object with custom border characters
+ *      style: fmt.bold.blue,
+ *      padding: 2, // can be an object with custom spacing
+ *      margin: 2, // can be an object with custom spacing
+ * });
+ * ```
+ *
+ * @param text The text within the box.
+ * @param options Configuration options.
+ * @returns A string that is the box.
+ */
+export declare function box(text: string, options?: BoxOptions): string;
+/**
+ * Extend the functionality of Termark with custom methods.
+ *
+ * **Note:** Methods created this way can only be used as the last item in the chain.
+ *
+ * @example
+ * ```ts
+ * import { extend } from "termark";
+ *
+ * const extended = extend((base) => ({
+ *      shout: (str) => base.red.bold(str.toUpperCase()),
+ *      orange: (str) => base.hex("#ffa500").text(str),
+ * }));
+ *
+ * console.log(
+ *      extended.underline.shout("big red text"),
+ *      extended.italic.orange("orange text"),
+ * );
+ * ```
+ *
+ * When not using arrow functions, it's possible to use an extension method within another extension method:
+ *
+ * @example Deriving methods from each other
+ * ```ts
+ * import { extend } from "termark";
+ *
+ * const extended = extend((base) => ({
+ *      orange(str) {
+ *          return base.hex("#ffa500").text(str);
+ *      },
+ *      uppercaseOrange(str) {
+ *          return this.orange(str.toUpperCase());
+ *      },
+ * }));
+ * ```
+ *
+ * @param fn A function that returns an object containing custom methods. This function has access to a
+ * {@linkcode Termark} instance so it does not need to be imported separately.
+ */
+export declare function extend<E extends Record<PropertyKey, StyleFn>>(fn: (base: Termark) => E): Termark<keyof E>;
+/**
+ * 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.
+ */
+export declare function fromColObject<R extends ColourObject, GenBg extends boolean | undefined = undefined>(obj: R, genBg?: GenBg): Termark<FromColObjectReturn<R, GenBg>>;
+/**
+ * Construct an OSC 8 hyperlink.
+ *
+ * **Note:** Whether and how interactive the resulting hyperlink is entirely depends on the current terminal
+ * environment, not all support OSC 8 hyperlinks, especially not ones with custom display text. For a list of which
+ * terminal emulators support OSC 8 hyperlinks, see [here](https://github.com/Alhadis/OSC8-Adoption).
+ *
+ * @example
+ * ```ts
+ * import { link } from "termark";
+ *
+ * const l = link("https://example.com", "Website");
+ * ```
+ *
+ * @example Styled text
+ * ```ts
+ * import { link, fmt } from "termark";
+ *
+ * const l = link("https://example.com", fmt.italic.green("Website"));
+ * ```
+ *
+ * @param url The URL the hyperlink points to. Required.
+ * @param text Text to display instead of the URL. Optional; if omitted, `url` is displayed instead.
+ */
+export declare function link(url: string, text?: string): string;
+/**
+ * Check whether colours are supported in a given terminal environment.
+ *
+ * Use {@linkcode hasNoColour} for checking whether terminals that *could* support colour don't do so.
+ */
+export declare function areColoursSupported(): boolean;
+/**
+ * Check whether a terminal environment supports at least some level of colours.
+ *
+ * @param level A colour level.
+ */
+export declare function supports(level: ColourLevel): boolean;
+/**
+ * Check whether a terminal environment supports at most a given colour level.
+ *
+ * @param level A colour level.
+ */
+export declare function supportsAtMost(level: ColourLevel): boolean;
+/**
+ * Modify the plain text part of a string with ANSI escape sequences.
+ *
+ * @example Creating a `toUpperCase` method for ANSI strings
+ * ```ts
+ * import { transformPreserveAnsi } from "termark";
+ *
+ * const toUpperCase = transformPreserveAnsi((str) => str.toUpperCase());
+ * ```
+ *
+ * @param fn A function that transforms some string.
+ *
+ * @deprecated Function is no longer necessary.
+ */
+export declare function transformPreserveAnsi(fn: (plain: string) => string): (str: string) => string;
+/**
+ * Make some string upper-case while preserving ANSI escape sequences as-is.
+ *
+ * @str The string to transform.
+ *
+ * @deprecated Function is no longer necessary.
+ */
+export declare const ansiUpperCase: (str: string) => string;
+/**
+ * Make some string lower-case while preserving ANSI escape sequences as-is.
+ *
+ * @param str The string to transform.
+ *
+ * @deprecated Function is no longer necessary.
+ */
+export declare const ansiLowerCase: (str: string) => string;
+/**
+ * Remove ANSI escape sequences from some text.
+ *
+ * @param input The input to strip of ANSI escape sequences.
+ */
+export declare function stripAnsi(input: string): string;
+export { type AnyStyle, type BaseStyle, type BoxBorder, type BoxBorderKind, type BoxOptions, type BoxSpacing, type ColourLevel, type ColourObject, type DynamicStyle, type FromColObjectReturn, type GradientStyle, type RGB, type StyleData, type StyleFn, type Termark, fmt as termark, getColourLevel as getColorLevel, hasNoColour as hasNoColor };