@syncify/ansi

Terminal utilities for the Syncify CLI Shopify theme development tool. This module provides CLI enhancements, helpers and various other TUI logic which are used in console logging and reporting for Syncify.

Installation

The module should be included within distributed builds. Given the way the minification algorithms work in most build tools and the hard depedencies this package requires, failure to include within your builds will likely result in headaches.

$ pnpm add @syncify/ansi -D

Colors

Terminal colors are exposed and made available using Ansis. There are custom colors and raw access to Ansis is available.

Standard Colors

Bright Colors

Custom Colors

Symbols

There are various symbols (characters) available as named exports. Symbols in the CLI are color wrapped and injected into strings when composing logs and messaged etc.

Character Helpers

Character are const exports, they are output in darkGray by default.

import {
  PIP // |
  HSH // #
  PLS // +
  MIN // -
  COM // ,
  CHK // ✓
  BAD // 𐄂
  COL // :
  ARR // →
  CHV // ▸
  ARL // ⥂
  TLD // ~
  DSH // —
} from '@syncify/ansi'

Infix Wrappers

Infix wrappers are const exports, they are output in darkGray by default.

import {
  LPR // (
  RPR // )
  LCB // {
  RCB // }
  LSB // [
  RSB // ]
  LAN // <
  RAN // >
} from '@syncify/ansi'

Tree Characters

Tree characters available on the Tree named export and are output in darkGray by default. Characters are also available in red and yellow colors.

import { Tree } from '@syncify/ansi';

Tree.open         // ┌─
Tree.stub         // ├
Tree.dash         // ├─
Tree.line         // │
Tree.base         // └─
Tree.next         // \n│
Tree.after        // │\n
Tree.wrap         // \n│\n

Tree.indent.edge  // ├──┬─
Tree.indent.line  // │  │
Tree.indent.stub  // │  ├
Tree.indent.dash  // │  ├─
Tree.indent.base  // │  └─
Tree.indent.fall  // ├──┐

TUI Create

Log message generator instance which can be used to compose a complex output log.

import { Create } from '@syncify/ansi';

const message = Create();

message.BR;
message.NL;
message.Break();
message.Template();
message.Update();
message.Context();
message.Dash();
message.End();
message.Error();
message.Get();
message.Inline();
message.Insert();
message.Line();
message.Newline();
message.Pop();
message.Remove();
message.Ruler();
message.Top();
message.Warn();
message.Wrap();
message.toLine();
message.toRaw();
message.toString();
message.Log();

Spinner

Symbol Spinner utility which will persist a terminal animation.

import { spinner } from '@syncify/ansi';

spinner('loading', {
  line: true,
  action: {},
  color: 'pink',
  style: 'spinning'
});

spinner.update('');
spinner.stop();

Capture

Regular expression replacers, which capture various text sequences or characters, excluding any ansi occurrences.

Usage

import { capture } from '@syncify/ansi'

capture(/(regex)/, '', match => {})     // sugar matching

capture.punctuation('', match => {})    // [$<[\]>{}:,-]
capture.quoted('', match => {})         // "double" and "single"
capture.brackets('', match => {})       // [ and ]
capture.braces('', match => {})         // { and }
capture.angles('', match => {})         // < and >
capture.colons('', match => {})         // :
capture.dollar('', match => {})         // $
capture.dash('', match => {})           // -
capture.commas('', match => {})         // ,

Progress

Progress bar utility is available on the progress named export. This function returns an instance with methods.

▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱ 50%

Usage

import { progress } from '@syncify/ansi';

const loading = progress(25, {
  showPercentage: true,
  barColor: 'neonGreen',
  percentColor: 'whiteBright',
  barSize: 40,
  clearOnComplete: false
});

loading.increment(1);  // Increment progress
loading.decrement(1);  // Decrement progress
loading.render()       // Render the progress bar, returns string
loading.stop()         // Stop progress
loading.percent        // Returns loading percentage

Terminal Size

The module also exposes a helper utility for obtaining the developers terminal size and will return some information about the terminal dimensions.

import { tsize } from '@syncify/ansi';

const {
  wrap, // number
  cols, // number
  row // number
} = tsize();

Contributing

This package is designed for usage within Syncify. Contributions are not accepted unless they pertain to the core Syncify module. If contributions fall into that category, fork the Syncify project.