ansimax 1.3.3 → 1.3.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +141 -0
- package/README.es.md +31 -3
- package/README.md +31 -3
- package/dist/index.d.mts +346 -195
- package/dist/index.d.ts +346 -195
- package/dist/index.js +187 -4
- package/dist/index.mjs +180 -4
- package/examples/all-in-one.cjs +1 -1
- package/examples/all-in-one.mjs +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -95,203 +95,36 @@ declare const getConfigValue: <K extends keyof AnsimaxConfig>(key: K) => Require
|
|
|
95
95
|
* });
|
|
96
96
|
*/
|
|
97
97
|
declare const withConfig: <T>(overrides: AnsimaxConfig, fn: () => T | Promise<T>) => T | Promise<T>;
|
|
98
|
-
|
|
99
|
-
declare const ESC = "\u001B";
|
|
100
|
-
declare const CSI = "\u001B[";
|
|
101
|
-
/** OSC sequence introducer (Operating System Command). */
|
|
102
|
-
declare const OSC = "\u001B]";
|
|
103
|
-
/** String terminator used to close OSC sequences. */
|
|
104
|
-
declare const ST = "\u001B\\";
|
|
105
|
-
/** BEL — alternative OSC terminator (older terminals). */
|
|
106
|
-
declare const BEL = "\u0007";
|
|
107
|
-
type AnsiCode = number;
|
|
108
|
-
/** Default fallback dimensions when stdout is not a TTY. */
|
|
109
|
-
declare const DEFAULT_TERM_COLS = 80;
|
|
110
|
-
declare const DEFAULT_TERM_ROWS = 24;
|
|
111
|
-
declare const cursor: {
|
|
112
|
-
readonly up: (n?: number) => string;
|
|
113
|
-
readonly down: (n?: number) => string;
|
|
114
|
-
readonly right: (n?: number) => string;
|
|
115
|
-
readonly left: (n?: number) => string;
|
|
116
|
-
readonly to: (x: number, y: number) => string;
|
|
117
|
-
/** Move cursor to absolute column n (1-based). */
|
|
118
|
-
readonly column: (n: number) => string;
|
|
119
|
-
/** Save cursor (CSI s — DEC private). */
|
|
120
|
-
readonly save: () => string;
|
|
121
|
-
/** Restore cursor (CSI u). */
|
|
122
|
-
readonly restore: () => string;
|
|
123
|
-
/** Save cursor (ESC 7 — VT100 standard). */
|
|
124
|
-
readonly saveCompat: () => string;
|
|
125
|
-
/** Restore cursor (ESC 8). */
|
|
126
|
-
readonly restoreCompat: () => string;
|
|
127
|
-
readonly hide: () => string;
|
|
128
|
-
readonly show: () => string;
|
|
129
|
-
/** Query cursor position. Terminal responds with CSI <row>;<col>R. */
|
|
130
|
-
readonly position: () => string;
|
|
131
|
-
/** Move cursor to next line (CR + line down). */
|
|
132
|
-
readonly nextLine: (n?: number) => string;
|
|
133
|
-
/** Move cursor to previous line. */
|
|
134
|
-
readonly prevLine: (n?: number) => string;
|
|
135
|
-
};
|
|
136
|
-
/**
|
|
137
|
-
* Hide cursor and register an exit handler that restores it on crash/SIGINT.
|
|
138
|
-
* Use this instead of writing `cursor.hide()` directly when you care about
|
|
139
|
-
* leaving the user's shell in a clean state.
|
|
140
|
-
*/
|
|
141
|
-
declare const hideCursor: () => boolean;
|
|
142
|
-
declare const showCursor: () => boolean;
|
|
143
|
-
type EraseMode = 'down' | 'up' | 'all';
|
|
144
|
-
declare const screen: {
|
|
145
|
-
readonly clear: () => string;
|
|
146
|
-
/** Alias for clear() — covers `screen.clearAll()` callers. */
|
|
147
|
-
readonly clearAll: () => string;
|
|
148
|
-
readonly clearLine: () => string;
|
|
149
|
-
readonly clearRight: () => string;
|
|
150
|
-
readonly clearLeft: () => string;
|
|
151
|
-
readonly clearDown: () => string;
|
|
152
|
-
readonly clearUp: () => string;
|
|
153
|
-
readonly eraseDisplay: (mode?: EraseMode) => string;
|
|
154
|
-
readonly scrollUp: (n?: number) => string;
|
|
155
|
-
readonly scrollDown: (n?: number) => string;
|
|
156
|
-
};
|
|
157
|
-
declare const FG: {
|
|
158
|
-
readonly black: 30;
|
|
159
|
-
readonly red: 31;
|
|
160
|
-
readonly green: 32;
|
|
161
|
-
readonly yellow: 33;
|
|
162
|
-
readonly blue: 34;
|
|
163
|
-
readonly magenta: 35;
|
|
164
|
-
readonly cyan: 36;
|
|
165
|
-
readonly white: 37;
|
|
166
|
-
readonly brightBlack: 90;
|
|
167
|
-
readonly brightRed: 91;
|
|
168
|
-
readonly brightGreen: 92;
|
|
169
|
-
readonly brightYellow: 93;
|
|
170
|
-
readonly brightBlue: 94;
|
|
171
|
-
readonly brightMagenta: 95;
|
|
172
|
-
readonly brightCyan: 96;
|
|
173
|
-
readonly brightWhite: 97;
|
|
174
|
-
};
|
|
175
|
-
declare const BG: {
|
|
176
|
-
readonly black: 40;
|
|
177
|
-
readonly red: 41;
|
|
178
|
-
readonly green: 42;
|
|
179
|
-
readonly yellow: 43;
|
|
180
|
-
readonly blue: 44;
|
|
181
|
-
readonly magenta: 45;
|
|
182
|
-
readonly cyan: 46;
|
|
183
|
-
readonly white: 47;
|
|
184
|
-
readonly brightBlack: 100;
|
|
185
|
-
readonly brightRed: 101;
|
|
186
|
-
readonly brightGreen: 102;
|
|
187
|
-
readonly brightYellow: 103;
|
|
188
|
-
readonly brightBlue: 104;
|
|
189
|
-
readonly brightMagenta: 105;
|
|
190
|
-
readonly brightCyan: 106;
|
|
191
|
-
readonly brightWhite: 107;
|
|
192
|
-
};
|
|
193
|
-
declare const STYLE: {
|
|
194
|
-
readonly reset: 0;
|
|
195
|
-
readonly bold: 1;
|
|
196
|
-
readonly dim: 2;
|
|
197
|
-
readonly italic: 3;
|
|
198
|
-
readonly underline: 4;
|
|
199
|
-
readonly blink: 5;
|
|
200
|
-
readonly inverse: 7;
|
|
201
|
-
readonly hidden: 8;
|
|
202
|
-
readonly strikethrough: 9;
|
|
203
|
-
};
|
|
204
|
-
declare const sgr: (...codes: AnsiCode[]) => string;
|
|
205
|
-
declare const reset: () => string;
|
|
206
|
-
declare const fgRgb: (r: number, g: number, b: number) => string;
|
|
207
|
-
declare const bgRgb: (r: number, g: number, b: number) => string;
|
|
208
|
-
declare const fg256: (n: number) => string;
|
|
209
|
-
declare const bg256: (n: number) => string;
|
|
210
98
|
/**
|
|
211
|
-
* Set
|
|
212
|
-
*
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
/** Ring the terminal bell. Most modern terminals visualize, not audio. */
|
|
222
|
-
declare const bell: () => string;
|
|
223
|
-
type ColorSupport = 'none' | 'basic' | '256' | 'truecolor';
|
|
224
|
-
type ColorLevel = 0 | 1 | 2 | 3;
|
|
225
|
-
declare const supportsColor: () => ColorSupport;
|
|
226
|
-
declare const supportsColorLevel: () => ColorLevel;
|
|
227
|
-
/**
|
|
228
|
-
* Reset the cached capability — call after changing FORCE_COLOR /
|
|
229
|
-
* NO_COLOR env vars at runtime, or before a test that needs to
|
|
230
|
-
* exercise different code paths.
|
|
231
|
-
*/
|
|
232
|
-
declare const resetColorSupportCache: () => void;
|
|
233
|
-
/** Returns terminal width in columns. Falls back to DEFAULT_TERM_COLS. */
|
|
234
|
-
declare const getTerminalWidth: () => number;
|
|
235
|
-
/** Returns terminal height in rows. Falls back to DEFAULT_TERM_ROWS. */
|
|
236
|
-
declare const getTerminalHeight: () => number;
|
|
237
|
-
declare const stripAnsi$2: (str: string) => string;
|
|
238
|
-
/** Sync write to stdout. Returns false if stdout is missing or full. */
|
|
239
|
-
declare const write: (str: string) => boolean;
|
|
240
|
-
/** Sync write to stderr. Useful for CLI errors and logs. */
|
|
241
|
-
declare const writeErr: (str: string) => boolean;
|
|
242
|
-
declare const writeln: (str?: string) => boolean;
|
|
243
|
-
declare const writelnErr: (str?: string) => boolean;
|
|
244
|
-
/**
|
|
245
|
-
* Async write with backpressure handling.
|
|
246
|
-
* - Resolves immediately when the buffer accepted the data
|
|
247
|
-
* - Waits for `'drain'` when full
|
|
248
|
-
* - Resolves on `'error'` instead of hanging forever
|
|
249
|
-
* - No-ops gracefully if stdout is missing
|
|
250
|
-
* - Optional timeout (ms) — resolves anyway after timeout to prevent
|
|
251
|
-
* infinite hangs on broken streams
|
|
252
|
-
*/
|
|
253
|
-
interface WriteAsyncOptions {
|
|
254
|
-
/** Max time (ms) to wait for drain. Default: 5000. 0 disables. */
|
|
255
|
-
timeout?: number;
|
|
256
|
-
}
|
|
257
|
-
declare const writeAsync: (str: string, opts?: WriteAsyncOptions) => Promise<void>;
|
|
258
|
-
interface OutputBuffer {
|
|
259
|
-
/** Append a string to the buffer. */
|
|
260
|
-
push(str: string): OutputBuffer;
|
|
261
|
-
/** Append a string with a trailing newline. */
|
|
262
|
-
pushln(str?: string): OutputBuffer;
|
|
263
|
-
/** Append `str` only when `cond` is truthy. Useful for conditional escapes. */
|
|
264
|
-
pushIf(cond: unknown, str: string): OutputBuffer;
|
|
265
|
-
/** Get the buffered content without flushing. */
|
|
266
|
-
toString(): string;
|
|
267
|
-
/** Number of characters currently buffered. */
|
|
268
|
-
length(): number;
|
|
269
|
-
/** Clear the buffer without writing. */
|
|
270
|
-
reset(): OutputBuffer;
|
|
271
|
-
/** Flush to stdout synchronously. Returns false on backpressure. */
|
|
272
|
-
flush(): boolean;
|
|
273
|
-
/** Flush to stdout asynchronously. Awaits drain on backpressure. */
|
|
274
|
-
flushAsync(opts?: WriteAsyncOptions): Promise<void>;
|
|
275
|
-
}
|
|
276
|
-
declare const createOutputBuffer: () => OutputBuffer;
|
|
277
|
-
/** Recommended frame interval (ms) for animations. ~60 fps. */
|
|
278
|
-
declare const FRAME_MS = 16;
|
|
279
|
-
interface SleepOptions {
|
|
280
|
-
/** Optional AbortSignal — sleep resolves immediately when aborted. */
|
|
281
|
-
signal?: AbortSignal;
|
|
282
|
-
}
|
|
283
|
-
/**
|
|
284
|
-
* Pause for `ms` milliseconds. Cancellable via AbortSignal.
|
|
285
|
-
* - Negative or NaN ms is clamped to 0
|
|
286
|
-
* - Resolves silently on abort (no rejection)
|
|
287
|
-
* - Cleans up timer + listener on every path
|
|
99
|
+
* Set a single config key without wrapping in an object. Convenience
|
|
100
|
+
* shortcut equivalent to `configure({ [key]: value })`.
|
|
101
|
+
*
|
|
102
|
+
* @example
|
|
103
|
+
* ```ts
|
|
104
|
+
* import { setConfigValue } from 'ansimax';
|
|
105
|
+
*
|
|
106
|
+
* setConfigValue('theme', 'dracula');
|
|
107
|
+
* setConfigValue('animationSpeed', 'fast');
|
|
108
|
+
* ```
|
|
288
109
|
*/
|
|
289
|
-
declare const
|
|
110
|
+
declare const setConfigValue: <K extends keyof AnsimaxConfig>(key: K, value: AnsimaxConfig[K]) => void;
|
|
290
111
|
/**
|
|
291
|
-
*
|
|
292
|
-
*
|
|
112
|
+
* Alias for `onConfigChange` — matches the naming convention used by
|
|
113
|
+
* `themes.onChange` and other observers in the codebase. Returns an
|
|
114
|
+
* unsubscribe function.
|
|
115
|
+
*
|
|
116
|
+
* @example
|
|
117
|
+
* ```ts
|
|
118
|
+
* import { subscribeConfig } from 'ansimax';
|
|
119
|
+
*
|
|
120
|
+
* const unsubscribe = subscribeConfig((newCfg, oldCfg) => {
|
|
121
|
+
* console.log('Config changed:', newCfg);
|
|
122
|
+
* });
|
|
123
|
+
*
|
|
124
|
+
* // Later: unsubscribe();
|
|
125
|
+
* ```
|
|
293
126
|
*/
|
|
294
|
-
declare const
|
|
127
|
+
declare const subscribeConfig: (listener: ConfigChangeListener) => (() => void);
|
|
295
128
|
|
|
296
129
|
interface RGB {
|
|
297
130
|
r: number;
|
|
@@ -326,7 +159,7 @@ declare const lerpColor: (a: RGB, b: RGB, t: number) => RGB;
|
|
|
326
159
|
*/
|
|
327
160
|
declare const gradientColor: (colors: RGB[], t: number) => RGB;
|
|
328
161
|
declare const rgbTo256: (r: number, g: number, b: number) => number;
|
|
329
|
-
declare const stripAnsi$
|
|
162
|
+
declare const stripAnsi$2: (str: string) => string;
|
|
330
163
|
/**
|
|
331
164
|
* Width of a single character (or grapheme) in terminal cells.
|
|
332
165
|
* - 0 for combining marks, ZWJ, VS, BOM
|
|
@@ -524,6 +357,286 @@ declare const safeJson: (value: unknown, indent?: number) => string;
|
|
|
524
357
|
* padBoth('hi', 5) → ' hi '
|
|
525
358
|
*/
|
|
526
359
|
declare const padBoth: (str: string, width: number, ch?: string) => string;
|
|
360
|
+
/**
|
|
361
|
+
* Interpolate a sequence of N colors between two endpoint hex colors.
|
|
362
|
+
* Useful for procedurally generating gradient stops without calling the
|
|
363
|
+
* full gradient pipeline.
|
|
364
|
+
*
|
|
365
|
+
* @param start - Start hex color (e.g. `'#ff0000'`).
|
|
366
|
+
* @param end - End hex color (e.g. `'#0000ff'`).
|
|
367
|
+
* @param count - Number of stops (>= 2; clamped if smaller).
|
|
368
|
+
* @returns Array of hex strings, including both endpoints.
|
|
369
|
+
*
|
|
370
|
+
* @example
|
|
371
|
+
* ```ts
|
|
372
|
+
* import { gradientStops } from 'ansimax';
|
|
373
|
+
*
|
|
374
|
+
* const stops = gradientStops('#ff0000', '#0000ff', 5);
|
|
375
|
+
* // → ['#ff0000', '#bf003f', '#7f007f', '#3f00bf', '#0000ff']
|
|
376
|
+
* ```
|
|
377
|
+
*/
|
|
378
|
+
declare const gradientStops: (start: string, end: string, count: number) => string[];
|
|
379
|
+
/**
|
|
380
|
+
* Escape a string for safe use inside a regular expression literal.
|
|
381
|
+
* Escapes all 12 regex meta-characters: `. * + ? ^ $ { } ( ) | [ ] \`.
|
|
382
|
+
*
|
|
383
|
+
* @example
|
|
384
|
+
* ```ts
|
|
385
|
+
* import { escapeForRegex } from 'ansimax';
|
|
386
|
+
*
|
|
387
|
+
* const userInput = 'hello.world+code';
|
|
388
|
+
* const re = new RegExp(escapeForRegex(userInput));
|
|
389
|
+
* // Matches the literal string, not as a regex pattern
|
|
390
|
+
* ```
|
|
391
|
+
*/
|
|
392
|
+
declare const escapeForRegex: (str: string) => string;
|
|
393
|
+
/**
|
|
394
|
+
* Measure a pre-rendered string block's dimensions: width (max visible
|
|
395
|
+
* width of any line) and height (line count). ANSI escapes are ignored.
|
|
396
|
+
*
|
|
397
|
+
* @example
|
|
398
|
+
* ```ts
|
|
399
|
+
* import { measureBlock } from 'ansimax';
|
|
400
|
+
*
|
|
401
|
+
* const box = ascii.box('Hello world!');
|
|
402
|
+
* const { width, height } = measureBlock(box);
|
|
403
|
+
* // → { width: 15, height: 3 }
|
|
404
|
+
* ```
|
|
405
|
+
*/
|
|
406
|
+
declare const measureBlock: (block: string) => {
|
|
407
|
+
width: number;
|
|
408
|
+
height: number;
|
|
409
|
+
};
|
|
410
|
+
|
|
411
|
+
declare const ESC = "\u001B";
|
|
412
|
+
declare const CSI = "\u001B[";
|
|
413
|
+
/** OSC sequence introducer (Operating System Command). */
|
|
414
|
+
declare const OSC = "\u001B]";
|
|
415
|
+
/** String terminator used to close OSC sequences. */
|
|
416
|
+
declare const ST = "\u001B\\";
|
|
417
|
+
/** BEL — alternative OSC terminator (older terminals). */
|
|
418
|
+
declare const BEL = "\u0007";
|
|
419
|
+
type AnsiCode = number;
|
|
420
|
+
/** Default fallback dimensions when stdout is not a TTY. */
|
|
421
|
+
declare const DEFAULT_TERM_COLS = 80;
|
|
422
|
+
declare const DEFAULT_TERM_ROWS = 24;
|
|
423
|
+
declare const cursor: {
|
|
424
|
+
readonly up: (n?: number) => string;
|
|
425
|
+
readonly down: (n?: number) => string;
|
|
426
|
+
readonly right: (n?: number) => string;
|
|
427
|
+
readonly left: (n?: number) => string;
|
|
428
|
+
readonly to: (x: number, y: number) => string;
|
|
429
|
+
/** Move cursor to absolute column n (1-based). */
|
|
430
|
+
readonly column: (n: number) => string;
|
|
431
|
+
/** Save cursor (CSI s — DEC private). */
|
|
432
|
+
readonly save: () => string;
|
|
433
|
+
/** Restore cursor (CSI u). */
|
|
434
|
+
readonly restore: () => string;
|
|
435
|
+
/** Save cursor (ESC 7 — VT100 standard). */
|
|
436
|
+
readonly saveCompat: () => string;
|
|
437
|
+
/** Restore cursor (ESC 8). */
|
|
438
|
+
readonly restoreCompat: () => string;
|
|
439
|
+
readonly hide: () => string;
|
|
440
|
+
readonly show: () => string;
|
|
441
|
+
/** Query cursor position. Terminal responds with CSI <row>;<col>R. */
|
|
442
|
+
readonly position: () => string;
|
|
443
|
+
/** Move cursor to next line (CR + line down). */
|
|
444
|
+
readonly nextLine: (n?: number) => string;
|
|
445
|
+
/** Move cursor to previous line. */
|
|
446
|
+
readonly prevLine: (n?: number) => string;
|
|
447
|
+
};
|
|
448
|
+
/**
|
|
449
|
+
* Hide cursor and register an exit handler that restores it on crash/SIGINT.
|
|
450
|
+
* Use this instead of writing `cursor.hide()` directly when you care about
|
|
451
|
+
* leaving the user's shell in a clean state.
|
|
452
|
+
*/
|
|
453
|
+
declare const hideCursor: () => boolean;
|
|
454
|
+
declare const showCursor: () => boolean;
|
|
455
|
+
type EraseMode = 'down' | 'up' | 'all';
|
|
456
|
+
declare const screen: {
|
|
457
|
+
readonly clear: () => string;
|
|
458
|
+
/** Alias for clear() — covers `screen.clearAll()` callers. */
|
|
459
|
+
readonly clearAll: () => string;
|
|
460
|
+
readonly clearLine: () => string;
|
|
461
|
+
readonly clearRight: () => string;
|
|
462
|
+
readonly clearLeft: () => string;
|
|
463
|
+
readonly clearDown: () => string;
|
|
464
|
+
readonly clearUp: () => string;
|
|
465
|
+
readonly eraseDisplay: (mode?: EraseMode) => string;
|
|
466
|
+
readonly scrollUp: (n?: number) => string;
|
|
467
|
+
readonly scrollDown: (n?: number) => string;
|
|
468
|
+
};
|
|
469
|
+
declare const FG: {
|
|
470
|
+
readonly black: 30;
|
|
471
|
+
readonly red: 31;
|
|
472
|
+
readonly green: 32;
|
|
473
|
+
readonly yellow: 33;
|
|
474
|
+
readonly blue: 34;
|
|
475
|
+
readonly magenta: 35;
|
|
476
|
+
readonly cyan: 36;
|
|
477
|
+
readonly white: 37;
|
|
478
|
+
readonly brightBlack: 90;
|
|
479
|
+
readonly brightRed: 91;
|
|
480
|
+
readonly brightGreen: 92;
|
|
481
|
+
readonly brightYellow: 93;
|
|
482
|
+
readonly brightBlue: 94;
|
|
483
|
+
readonly brightMagenta: 95;
|
|
484
|
+
readonly brightCyan: 96;
|
|
485
|
+
readonly brightWhite: 97;
|
|
486
|
+
};
|
|
487
|
+
declare const BG: {
|
|
488
|
+
readonly black: 40;
|
|
489
|
+
readonly red: 41;
|
|
490
|
+
readonly green: 42;
|
|
491
|
+
readonly yellow: 43;
|
|
492
|
+
readonly blue: 44;
|
|
493
|
+
readonly magenta: 45;
|
|
494
|
+
readonly cyan: 46;
|
|
495
|
+
readonly white: 47;
|
|
496
|
+
readonly brightBlack: 100;
|
|
497
|
+
readonly brightRed: 101;
|
|
498
|
+
readonly brightGreen: 102;
|
|
499
|
+
readonly brightYellow: 103;
|
|
500
|
+
readonly brightBlue: 104;
|
|
501
|
+
readonly brightMagenta: 105;
|
|
502
|
+
readonly brightCyan: 106;
|
|
503
|
+
readonly brightWhite: 107;
|
|
504
|
+
};
|
|
505
|
+
declare const STYLE: {
|
|
506
|
+
readonly reset: 0;
|
|
507
|
+
readonly bold: 1;
|
|
508
|
+
readonly dim: 2;
|
|
509
|
+
readonly italic: 3;
|
|
510
|
+
readonly underline: 4;
|
|
511
|
+
readonly blink: 5;
|
|
512
|
+
readonly inverse: 7;
|
|
513
|
+
readonly hidden: 8;
|
|
514
|
+
readonly strikethrough: 9;
|
|
515
|
+
};
|
|
516
|
+
declare const sgr: (...codes: AnsiCode[]) => string;
|
|
517
|
+
declare const reset: () => string;
|
|
518
|
+
declare const fgRgb: (r: number, g: number, b: number) => string;
|
|
519
|
+
declare const bgRgb: (r: number, g: number, b: number) => string;
|
|
520
|
+
declare const fg256: (n: number) => string;
|
|
521
|
+
declare const bg256: (n: number) => string;
|
|
522
|
+
/**
|
|
523
|
+
* Set the terminal window title (OSC 2). Most terminals support this.
|
|
524
|
+
* Returns the escape sequence; caller is responsible for writing it.
|
|
525
|
+
*/
|
|
526
|
+
declare const setTitle: (text: string) => string;
|
|
527
|
+
/**
|
|
528
|
+
* Make `text` a clickable hyperlink to `url` (OSC 8).
|
|
529
|
+
* Supported by iTerm2, Terminal.app (macOS 13+), WezTerm, Kitty, modern xterm.
|
|
530
|
+
* Falls back gracefully (just prints text) on terminals that don't support it.
|
|
531
|
+
*/
|
|
532
|
+
declare const link: (text: string, url: string) => string;
|
|
533
|
+
/** Ring the terminal bell. Most modern terminals visualize, not audio. */
|
|
534
|
+
declare const bell: () => string;
|
|
535
|
+
type ColorSupport = 'none' | 'basic' | '256' | 'truecolor';
|
|
536
|
+
type ColorLevel = 0 | 1 | 2 | 3;
|
|
537
|
+
declare const supportsColor: () => ColorSupport;
|
|
538
|
+
declare const supportsColorLevel: () => ColorLevel;
|
|
539
|
+
/**
|
|
540
|
+
* Reset the cached capability — call after changing FORCE_COLOR /
|
|
541
|
+
* NO_COLOR env vars at runtime, or before a test that needs to
|
|
542
|
+
* exercise different code paths.
|
|
543
|
+
*/
|
|
544
|
+
declare const resetColorSupportCache: () => void;
|
|
545
|
+
/** Returns terminal width in columns. Falls back to DEFAULT_TERM_COLS. */
|
|
546
|
+
declare const getTerminalWidth: () => number;
|
|
547
|
+
/** Returns terminal height in rows. Falls back to DEFAULT_TERM_ROWS. */
|
|
548
|
+
declare const getTerminalHeight: () => number;
|
|
549
|
+
declare const stripAnsi$1: (str: string) => string;
|
|
550
|
+
/** Sync write to stdout. Returns false if stdout is missing or full. */
|
|
551
|
+
declare const write: (str: string) => boolean;
|
|
552
|
+
/** Sync write to stderr. Useful for CLI errors and logs. */
|
|
553
|
+
declare const writeErr: (str: string) => boolean;
|
|
554
|
+
declare const writeln: (str?: string) => boolean;
|
|
555
|
+
declare const writelnErr: (str?: string) => boolean;
|
|
556
|
+
/**
|
|
557
|
+
* Async write with backpressure handling.
|
|
558
|
+
* - Resolves immediately when the buffer accepted the data
|
|
559
|
+
* - Waits for `'drain'` when full
|
|
560
|
+
* - Resolves on `'error'` instead of hanging forever
|
|
561
|
+
* - No-ops gracefully if stdout is missing
|
|
562
|
+
* - Optional timeout (ms) — resolves anyway after timeout to prevent
|
|
563
|
+
* infinite hangs on broken streams
|
|
564
|
+
*/
|
|
565
|
+
interface WriteAsyncOptions {
|
|
566
|
+
/** Max time (ms) to wait for drain. Default: 5000. 0 disables. */
|
|
567
|
+
timeout?: number;
|
|
568
|
+
}
|
|
569
|
+
declare const writeAsync: (str: string, opts?: WriteAsyncOptions) => Promise<void>;
|
|
570
|
+
interface OutputBuffer {
|
|
571
|
+
/** Append a string to the buffer. */
|
|
572
|
+
push(str: string): OutputBuffer;
|
|
573
|
+
/** Append a string with a trailing newline. */
|
|
574
|
+
pushln(str?: string): OutputBuffer;
|
|
575
|
+
/** Append `str` only when `cond` is truthy. Useful for conditional escapes. */
|
|
576
|
+
pushIf(cond: unknown, str: string): OutputBuffer;
|
|
577
|
+
/** Get the buffered content without flushing. */
|
|
578
|
+
toString(): string;
|
|
579
|
+
/** Number of characters currently buffered. */
|
|
580
|
+
length(): number;
|
|
581
|
+
/** Clear the buffer without writing. */
|
|
582
|
+
reset(): OutputBuffer;
|
|
583
|
+
/** Flush to stdout synchronously. Returns false on backpressure. */
|
|
584
|
+
flush(): boolean;
|
|
585
|
+
/** Flush to stdout asynchronously. Awaits drain on backpressure. */
|
|
586
|
+
flushAsync(opts?: WriteAsyncOptions): Promise<void>;
|
|
587
|
+
}
|
|
588
|
+
declare const createOutputBuffer: () => OutputBuffer;
|
|
589
|
+
/** Recommended frame interval (ms) for animations. ~60 fps. */
|
|
590
|
+
declare const FRAME_MS = 16;
|
|
591
|
+
interface SleepOptions {
|
|
592
|
+
/** Optional AbortSignal — sleep resolves immediately when aborted. */
|
|
593
|
+
signal?: AbortSignal;
|
|
594
|
+
}
|
|
595
|
+
/**
|
|
596
|
+
* Pause for `ms` milliseconds. Cancellable via AbortSignal.
|
|
597
|
+
* - Negative or NaN ms is clamped to 0
|
|
598
|
+
* - Resolves silently on abort (no rejection)
|
|
599
|
+
* - Cleans up timer + listener on every path
|
|
600
|
+
*/
|
|
601
|
+
declare const sleep: (ms: number, opts?: SleepOptions) => Promise<void>;
|
|
602
|
+
/**
|
|
603
|
+
* Like sleep, but rounds the wait time up to the next frame boundary.
|
|
604
|
+
* Useful inside animation loops to throttle output to a reasonable framerate.
|
|
605
|
+
*/
|
|
606
|
+
declare const sleepFrame: (ms?: number, opts?: SleepOptions) => Promise<void>;
|
|
607
|
+
/**
|
|
608
|
+
* Wrap a label in an OSC 8 hyperlink escape sequence. Terminals that
|
|
609
|
+
* support hyperlinks (VS Code, iTerm2, WezTerm, Kitty, etc.) render it
|
|
610
|
+
* as clickable. Terminals without support just show the label text.
|
|
611
|
+
*
|
|
612
|
+
* @param url - Target URL (https://, mailto:, file://, etc.)
|
|
613
|
+
* @param label - Visible text. Defaults to the URL itself.
|
|
614
|
+
* @returns String with OSC 8 wrappers around the label.
|
|
615
|
+
*
|
|
616
|
+
* @example
|
|
617
|
+
* ```ts
|
|
618
|
+
* import { hyperlink } from 'ansimax';
|
|
619
|
+
*
|
|
620
|
+
* console.log(`Visit ${hyperlink('https://github.com/Brashkie/ansimax', 'the repo')}`);
|
|
621
|
+
* console.log(`Email: ${hyperlink('mailto:hi@example.com')}`);
|
|
622
|
+
* ```
|
|
623
|
+
*/
|
|
624
|
+
declare const hyperlink: (url: string, label?: string) => string;
|
|
625
|
+
/**
|
|
626
|
+
* Returns the escape sequence to clear the entire current line and move
|
|
627
|
+
* the cursor back to column 1. Equivalent to `screen.clearLine() + '\r'`.
|
|
628
|
+
*
|
|
629
|
+
* @example
|
|
630
|
+
* ```ts
|
|
631
|
+
* import { clearLine } from 'ansimax';
|
|
632
|
+
*
|
|
633
|
+
* for (let i = 0; i <= 100; i++) {
|
|
634
|
+
* process.stdout.write(clearLine() + `Progress: ${i}%`);
|
|
635
|
+
* await sleep(30);
|
|
636
|
+
* }
|
|
637
|
+
* ```
|
|
638
|
+
*/
|
|
639
|
+
declare const clearLine: () => string;
|
|
527
640
|
|
|
528
641
|
type ColorFn = (text: string) => string;
|
|
529
642
|
|
|
@@ -921,6 +1034,40 @@ interface ParallelOptions {
|
|
|
921
1034
|
*/
|
|
922
1035
|
type AnimFn = (text: string, opts?: Record<string, unknown>) => Promise<void>;
|
|
923
1036
|
type ChainStep = AnimFn | [AnimFn] | [AnimFn, Record<string, unknown>];
|
|
1037
|
+
interface ShakeOptions extends AnimationHooks {
|
|
1038
|
+
/** Number of shake cycles. Default `5`. */
|
|
1039
|
+
times?: number;
|
|
1040
|
+
/** Pixels of horizontal displacement per frame. Default `2`. */
|
|
1041
|
+
intensity?: number;
|
|
1042
|
+
/** Milliseconds between frames. Default `50`. */
|
|
1043
|
+
interval?: number;
|
|
1044
|
+
/** Emit newline at end. Default `true`. */
|
|
1045
|
+
newline?: boolean;
|
|
1046
|
+
signal?: AbortSignal;
|
|
1047
|
+
reducedMotion?: boolean;
|
|
1048
|
+
}
|
|
1049
|
+
interface CountUpOptions extends AnimationHooks {
|
|
1050
|
+
/** Total animation duration in ms. Default `1500`. */
|
|
1051
|
+
duration?: number;
|
|
1052
|
+
/** Frame count — more = smoother but slower. Default `60`. */
|
|
1053
|
+
steps?: number;
|
|
1054
|
+
/** Decimal places to show. Default `0`. */
|
|
1055
|
+
decimals?: number;
|
|
1056
|
+
/**
|
|
1057
|
+
* Format the displayed value. Default: `(n) => n.toString()`.
|
|
1058
|
+
* Use this to add prefixes/suffixes, commas, etc.
|
|
1059
|
+
*/
|
|
1060
|
+
format?: (value: number) => string;
|
|
1061
|
+
/**
|
|
1062
|
+
* Easing function — input/output both in [0, 1]. Default linear.
|
|
1063
|
+
* Try `(t) => t * t` for accelerate, `(t) => 1 - (1-t)**2` for decelerate.
|
|
1064
|
+
*/
|
|
1065
|
+
easing?: (t: number) => number;
|
|
1066
|
+
/** Emit newline at end. Default `true`. */
|
|
1067
|
+
newline?: boolean;
|
|
1068
|
+
signal?: AbortSignal;
|
|
1069
|
+
reducedMotion?: boolean;
|
|
1070
|
+
}
|
|
924
1071
|
declare const animate: {
|
|
925
1072
|
typewriter: (text: string, opts?: TypewriterOptions) => Promise<void>;
|
|
926
1073
|
fadeIn: (text: string, opts?: FadeOptions) => Promise<void>;
|
|
@@ -940,6 +1087,8 @@ declare const animate: {
|
|
|
940
1087
|
delay: (ms: number) => (opts?: {
|
|
941
1088
|
signal?: AbortSignal;
|
|
942
1089
|
}) => Promise<void>;
|
|
1090
|
+
shake: (text: string, opts?: ShakeOptions) => Promise<void>;
|
|
1091
|
+
countUp: (from: number, to: number, opts?: CountUpOptions) => Promise<void>;
|
|
943
1092
|
};
|
|
944
1093
|
|
|
945
1094
|
interface RGBA {
|
|
@@ -2624,6 +2773,8 @@ declare const ansimax: {
|
|
|
2624
2773
|
delay: (ms: number) => (opts?: {
|
|
2625
2774
|
signal?: AbortSignal;
|
|
2626
2775
|
}) => Promise<void>;
|
|
2776
|
+
shake: (text: string, opts?: ShakeOptions) => Promise<void>;
|
|
2777
|
+
countUp: (from: number, to: number, opts?: CountUpOptions) => Promise<void>;
|
|
2627
2778
|
};
|
|
2628
2779
|
ascii: {
|
|
2629
2780
|
big: (text: string) => string;
|
|
@@ -2723,4 +2874,4 @@ declare const ansimax: {
|
|
|
2723
2874
|
configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
|
|
2724
2875
|
};
|
|
2725
2876
|
|
|
2726
|
-
export { ASCII_RAMPS, type Alignment, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type CenterOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EasingFn, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FrameOptions, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type GridOptions, type HsplitOptions, type PrettyOptions as JsonPrettyOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions$1 as RenderOptions, type ResizeListener, type ReusableGradient, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type VsplitOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center$1 as center, center as centerBlock, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frame, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, graphemes, grid, hasFont, hexToRgb, hideCursor, hsplit, images, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, pauseListeners, presetNames, presets, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rotate90, safeJson, screen, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$
|
|
2877
|
+
export { ASCII_RAMPS, type Alignment, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type CenterOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EasingFn, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FrameOptions, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type GridOptions, type HsplitOptions, type PrettyOptions as JsonPrettyOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions$1 as RenderOptions, type ResizeListener, type ReusableGradient, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type VsplitOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center$1 as center, center as centerBlock, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearLine, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeForRegex, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frame, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, gradientStops, graphemes, grid, hasFont, hexToRgb, hideCursor, hsplit, hyperlink, images, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureBlock, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, pauseListeners, presetNames, presets, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rotate90, safeJson, screen, setConfigValue, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$2 as stripAnsi, stripAnsi$1 as stripAnsiCodes, stripAnsi as stripAnsiColors, subscribeConfig, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, vsplit, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };
|