ansimax 1.0.0 → 1.1.1

package/examples/01-cli-installer.ts

@@ -0,0 +1,96 @@
+// ─────────────────────────────────────────────
+//  EXAMPLE 1 — CLI installer with hierarchical tasks
+//
+//  Demonstrates a realistic project setup flow:
+//   - Banner intro with theme gradient
+//   - Hierarchical tasks (parent + subtasks with rollup)
+//   - Status indicators with custom icons
+//   - Box for final summary
+//
+//  Run:
+//    npx ts-node examples/01-cli-installer.ts
+// ─────────────────────────────────────────────
+
+import {
+  ascii,
+  themes,
+  loader,
+  components,
+  configure,
+  sleep,
+} from '../dist/index.js';
+
+// Configure global defaults
+configure({
+  theme: 'dracula',
+  animationSpeed: 'fast',
+});
+
+// Simulated work
+const work = (ms: number, fail = false) => async (): Promise<string> => {
+  await sleep(ms);
+  if (fail) throw new Error('Simulated failure');
+  return 'ok';
+};
+
+const main = async (): Promise<void> => {
+  // ── Intro banner ──────────────────────────────
+  console.log();
+  console.log(themes.banner('CREATE-APP', { font: 'small' }));
+  console.log();
+  console.log(components.section(themes.primary('Initializing project'), { width: 60 }));
+  console.log();
+
+  // ── Hierarchical task list ────────────────────
+  const results = await loader.tasks([
+    {
+      text: 'Setup environment',
+      fn: work(300),
+      subtasks: [
+        { text: 'Detect Node version',  fn: work(150) },
+        { text: 'Verify npm registry',  fn: work(200) },
+        { text: 'Create project dir',   fn: work(100) },
+      ],
+    },
+    {
+      text: 'Install dependencies',
+      fn: work(400),
+      subtasks: [
+        { text: 'Resolve package tree', fn: work(250) },
+        { text: 'Download tarballs',    fn: work(500) },
+        { text: 'Build native modules', fn: work(300) },
+      ],
+    },
+    {
+      text: 'Run post-install hooks',
+      fn: work(200),
+      subtasks: [
+        { text: 'Generate types',  fn: work(150) },
+        { text: 'Lint workspace',  fn: work(180) },
+      ],
+    },
+  ]);
+
+  // ── Final summary box ─────────────────────────
+  console.log();
+  const succeeded = results.filter((r) => r.success).length;
+  const failed = results.length - succeeded;
+
+  const summary = [
+    components.status('success', `${succeeded} steps completed`),
+    failed > 0
+      ? components.status('error',  `${failed} steps failed`)
+      : components.status('info',   'No errors'),
+    '',
+    themes.muted('Next steps:'),
+    '  ' + themes.accent('cd my-app && npm run dev'),
+  ].join('\n');
+
+  console.log(components.box(summary, { borderStyle: 'rounded', padding: 1 }));
+  console.log();
+};
+
+main().catch((err) => {
+  console.error(themes.error('✗ ' + err.message));
+  process.exit(1);
+});

package/examples/01-quick-smoke.ts

@@ -0,0 +1,121 @@
+/**
+ * 01 — Quick Smoke Test
+ *
+ * Verifies all major named exports from `ansimax` are importable and callable.
+ * This is the FIRST test to run — if it fails, the package is broken.
+ *
+ * Run: npx tsx examples/01-quick-smoke.ts
+ */
+
+import {
+  color,
+  gradient,
+  rainbow,
+  ascii,
+  loader,
+  animate,
+  frames,
+  components,
+  themes,
+  images,
+  trees,
+  tree,
+  configure,
+  getConfig,
+  // Utils
+  stripAnsi,
+  visibleLen,
+  hexToRgb,
+  rgbToHex,
+  clamp,
+  // ANSI primitives
+  cursor,
+  screen,
+  supportsColor,
+} from '../src/index.js';
+
+const pass = (msg: string): void => console.log(color.green('✓'), msg);
+const info = (label: string, value: unknown): void =>
+  console.log('  ' + color.dim(label.padEnd(20)), value);
+
+console.log();
+console.log(color.bold(color.cyan('━━━ Ansimax v1.1.0 Smoke Test ━━━')));
+console.log();
+
+// 1. Colors
+pass('color.red / color.green / color.blue');
+info('color.red:', color.red('red text'));
+info('color.green:', color.green('green text'));
+
+// 2. Gradient
+pass('gradient with multi-stop');
+info('gradient:', gradient('rainbow text', ['#ff0000', '#00ff00', '#0000ff']));
+
+// 3. Rainbow preset
+pass('rainbow preset');
+info('rainbow:', rainbow('hello rainbow!'));
+
+// 4. Style modifiers
+pass('color.bold / italic / underline');
+info('bold:', color.bold('bold text'));
+info('italic:', color.italic('italic text'));
+info('underline:', color.underline('underlined text'));
+
+// 5. Hex & RGB
+pass('color.hex / color.rgb');
+info('color.hex:', color.hex('#ff79c6')('Dracula pink'));
+info('color.rgb:', color.rgb(189, 147, 249)('Dracula purple'));
+
+// 6. ANSI utils
+pass('stripAnsi / visibleLen');
+const colored = color.red('hello');
+info('stripAnsi:', JSON.stringify(stripAnsi(colored)));
+info('visibleLen:', visibleLen(colored));
+
+// 7. hexToRgb / rgbToHex
+pass('hexToRgb / rgbToHex');
+info('hexToRgb #ff79c6:', JSON.stringify(hexToRgb('#ff79c6')));
+info('rgbToHex 189,147,249:', rgbToHex(189, 147, 249));
+
+// 8. clamp
+pass('clamp');
+info('clamp(15, 0, 10):', clamp(15, 0, 10));
+
+// 9. Capability detection
+pass('supportsColor');
+info('supportsColor():', supportsColor());
+
+// 10. Module namespaces
+pass('All namespaces accessible');
+info('color:', typeof color);
+info('ascii:', typeof ascii);
+info('loader:', typeof loader);
+info('animate:', typeof animate);
+info('frames:', typeof frames);
+info('components:', typeof components);
+info('themes:', typeof themes);
+info('images:', typeof images);
+info('trees:', typeof trees);
+
+// 11. tree() builder
+pass('tree() builder');
+const t = tree({ label: 'root', icon: '📦' });
+t.addLeaf({ label: 'child1', icon: '📄' });
+info('tree.render():', '\n' + t.render());
+
+// 12. configure
+pass('configure / getConfig');
+const cfg = getConfig();
+info('theme:', cfg.theme);
+info('colorMode:', cfg.colorMode);
+
+// 13. cursor / screen primitives
+pass('cursor / screen primitives');
+info('cursor.hide():', JSON.stringify(cursor.hide()));
+info('cursor.show():', JSON.stringify(cursor.show()));
+info('screen.clearLine():', JSON.stringify(screen.clearLine()));
+
+console.log();
+console.log(color.bold(color.green('✅ All smoke tests passed!')));
+console.log(color.dim('You have a working ansimax installation.'));
+console.log();

package/examples/02-colors-gradients.ts

@@ -0,0 +1,108 @@
+/**
+ * 02 — Colors & Gradients
+ * Tests verified against actual ansimax@1.1.0 exports.
+ *
+ * Run: npx tsx examples/02-colors-gradients.ts
+ */
+
+import {
+  color,
+  gradient,
+  rainbow,
+  colorPresets,
+  presetNames,
+  compose,
+  chain,
+  registerPreset,
+  listPresets,
+} from '../src/index.js';
+
+console.log();
+console.log(color.bold('━━━ Basic Colors ━━━'));
+console.log();
+
+const basic = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'] as const;
+console.log('Basic 8 colors:');
+for (const c of basic) process.stdout.write(color[c](c.padEnd(8)) + ' ');
+console.log('\n');
+
+const bright = ['brightRed', 'brightGreen', 'brightYellow', 'brightBlue', 'brightMagenta', 'brightCyan'] as const;
+console.log('Bright variants:');
+for (const c of bright) process.stdout.write(color[c](c.padEnd(15)) + ' ');
+console.log('\n');
+
+const bg = ['bgRed', 'bgGreen', 'bgBlue', 'bgYellow', 'bgMagenta', 'bgCyan'] as const;
+console.log('Backgrounds:');
+for (const c of bg) process.stdout.write(color[c](` ${c} `) + ' ');
+console.log('\n');
+
+console.log('Modifiers:');
+console.log(' ',
+  color.bold('bold'),
+  color.italic('italic'),
+  color.underline('underline'),
+  color.dim('dim'),
+  color.inverse('inverse'),
+  color.strikethrough('strikethrough'),
+);
+console.log();
+
+console.log(color.bold('━━━ Hex / RGB / 256 ━━━'));
+console.log();
+
+const hexes = ['#ff79c6', '#bd93f9', '#8be9fd', '#50fa7b', '#ffb86c', '#ff5555'];
+console.log('Hex colors:');
+for (const hex of hexes) process.stdout.write(color.hex(hex)(hex) + ' ');
+console.log('\n');
+
+console.log('RGB:');
+console.log(' ', color.rgb(255, 121, 198)('rgb(255, 121, 198)'));
+console.log(' ', color.rgb(189, 147, 249)('rgb(189, 147, 249)'));
+console.log();
+
+console.log('256-color (palette indices):');
+for (const n of [196, 208, 226, 46, 51, 21, 201]) {
+  process.stdout.write(color.color256(n)(`[${n}]`) + ' ');
+}
+console.log('\n');
+
+console.log(color.bold('━━━ Gradients ━━━'));
+console.log();
+
+console.log('Multi-stop gradients:');
+console.log(' ', gradient('Hello gradient world!', ['#ff0000', '#00ff00', '#0000ff']));
+console.log(' ', gradient('Fire to ice', ['#ff6b6b', '#feca57', '#48dbfb']));
+console.log(' ', gradient('Dracula theme', ['#ff79c6', '#bd93f9', '#8be9fd']));
+console.log();
+
+console.log(color.bold('━━━ Built-in colorPresets ━━━'));
+console.log();
+console.log(' Available:', presetNames.join(', '));
+console.log();
+console.log(' rainbow: ', rainbow('rainbow text!'));
+console.log(' sunset:  ', colorPresets.sunset!('sunset preset'));
+console.log(' ocean:   ', colorPresets.ocean!('ocean preset'));
+console.log(' fire:    ', colorPresets.fire!('fire preset'));
+console.log(' neon:    ', colorPresets.neon!('neon preset'));
+console.log(' forest:  ', colorPresets.forest!('forest preset'));
+console.log(' aurora:  ', colorPresets.aurora!('aurora preset'));
+console.log(' candy:   ', colorPresets.candy!('candy preset'));
+console.log(' gold:    ', colorPresets.gold!('gold preset'));
+console.log();
+
+console.log(color.bold('━━━ Custom presets ━━━'));
+console.log();
+registerPreset('my-pink', ['#ff6b6b', '#ff79c6', '#ffb6c1']);
+console.log(' Registered. All presets now:', listPresets().join(', '));
+console.log(' my-pink: ', colorPresets['my-pink']!('My custom pink preset!'));
+console.log();
+
+console.log(color.bold('━━━ Compose & Chain ━━━'));
+console.log();
+const fancy = compose(color.red, color.bold, color.underline);
+console.log(' compose: ', fancy('red + bold + underline'));
+console.log(' chain:   ', chain().magenta().italic().underline().apply('chained styles'));
+console.log();
+
+console.log(color.bold(color.green('✓ Colors & gradients test complete')));
+console.log();

package/examples/02-live-dashboard.ts

@@ -0,0 +1,152 @@
+// ─────────────────────────────────────────────
+//  EXAMPLE 2 — Real-time dashboard with live updates
+//
+//  Demonstrates:
+//   - frames.live() for sticky bottom-of-screen UI
+//   - components.progressBar with gradient
+//   - components.table for data display
+//   - onResize listener for responsive layout
+//   - throttle for rate-limited updates
+//   - AbortSignal cleanup
+//
+//  Run:
+//    npx ts-node examples/02-live-dashboard.ts
+// ─────────────────────────────────────────────
+
+import {
+  themes,
+  components,
+  frames,
+  onResize,
+  throttle,
+  termSize,
+  sleep,
+  cursor,
+  screen,
+  write,
+} from '../dist/index.js';
+
+interface Stat {
+  service: string;
+  status:  'up' | 'down' | 'pending';
+  latency: number;
+  load:    number; // 0..100
+}
+
+// Simulated metrics that drift over time
+const stats: Stat[] = [
+  { service: 'api-gateway',  status: 'up',      latency: 14, load: 32 },
+  { service: 'auth-service', status: 'up',      latency: 22, load: 58 },
+  { service: 'database',     status: 'pending', latency: 0,  load: 0  },
+  { service: 'cdn-edge',     status: 'up',      latency: 8,  load: 18 },
+  { service: 'cache-layer',  status: 'up',      latency: 3,  load: 71 },
+];
+
+const drift = (): void => {
+  for (const s of stats) {
+    if (s.status === 'pending') {
+      // Pending services come online randomly
+      if (Math.random() < 0.1) {
+        s.status = 'up';
+        s.latency = 10 + Math.floor(Math.random() * 30);
+      }
+    } else if (s.status === 'up') {
+      // Slight load + latency wander
+      s.load = Math.max(0, Math.min(100, s.load + (Math.random() - 0.5) * 8));
+      s.latency = Math.max(1, s.latency + (Math.random() - 0.5) * 3);
+      // Tiny chance of going down
+      if (Math.random() < 0.005) s.status = 'down';
+    }
+  }
+};
+
+const renderFrame = (): string => {
+  const { cols } = termSize();
+  const innerWidth = Math.max(40, Math.min(cols - 4, 80));
+
+  // ── Header with theme gradient ──
+  const title = themes.banner('STATUS', { font: 'small', perCharColor: false });
+
+  // ── Service rows ──
+  const rows: string[][] = [
+    ['Service', 'Status', 'Latency', 'Load'],
+    ...stats.map((s) => {
+      const statusIcon =
+        s.status === 'up'      ? themes.accent('● up')
+      : s.status === 'down'    ? themes.error('● down')
+                               : themes.warning('● pending');
+
+      const latencyStr = s.status === 'up'
+        ? (s.latency < 20 ? themes.accent : s.latency < 50 ? themes.warning : themes.error)
+            (`${s.latency.toFixed(0)}ms`)
+        : themes.muted('—');
+
+      const loadBar = s.status === 'up'
+        ? components.progressBar(s.load, {
+            width: 20,
+            gradient: ['#00ff88', '#fdcb6e', '#ff6b6b'],
+            showPercentage: true,
+          })
+        : themes.muted('—');
+
+      return [s.service, statusIcon, latencyStr, loadBar];
+    }),
+  ];
+
+  const table = components.table(rows, { borderStyle: 'rounded', maxColWidth: innerWidth / 4 });
+
+  // ── Footer ──
+  const upCount   = stats.filter((s) => s.status === 'up').length;
+  const downCount = stats.filter((s) => s.status === 'down').length;
+  const footer = themes.muted(
+    `${upCount} up · ${downCount} down · ${stats.length} total · ` +
+    `${cols}×${termSize().rows} terminal · Ctrl+C to exit`,
+  );
+
+  return [title, '', table, '', footer].join('\n');
+};
+
+const main = async (): Promise<void> => {
+  // Hide cursor while live UI runs
+  write(cursor.hide());
+
+  // Throttled resize redraw — coalesce rapid resize events into one render
+  const onAnyResize = throttle(() => {
+    // Frame engine will pick up the new size on its next tick
+  }, 100);
+  const offResize = onResize(onAnyResize);
+
+  // Start live engine at 4 fps (smooth but not CPU-hungry)
+  const live = frames.live({ fps: 4, autoStart: true });
+
+  // Drift loop
+  const ctrl = new AbortController();
+  process.on('SIGINT', () => {
+    ctrl.abort();
+    live.stop({ clear: false });
+    offResize();
+    write(cursor.show());
+    write('\n');
+    console.log(themes.muted('Dashboard stopped.'));
+    process.exit(0);
+  });
+
+  try {
+    while (!ctrl.signal.aborted) {
+      drift();
+      live.update(renderFrame());
+      await sleep(250, { signal: ctrl.signal });
+    }
+  } catch {
+    // Aborted — fall through to cleanup
+  } finally {
+    live.stop({ clear: false });
+    offResize();
+    write(cursor.show());
+  }
+};
+
+main().catch((err) => {
+  console.error(themes.error('✗ ' + (err as Error).message));
+  process.exit(1);
+});

package/examples/03-ascii-banners.ts

@@ -0,0 +1,81 @@
+/**
+ * 03 — ASCII Banners & Boxes
+ * Real box styles: single, double, rounded, heavy, dashed, ascii
+ *
+ * Run: npx tsx examples/03-ascii-banners.ts
+ */
+
+import { ascii, gradient, color, listFonts, hasFont } from '../src/index.js';
+
+console.log();
+console.log(color.bold('━━━ ASCII Banners ━━━'));
+console.log();
+
+console.log(color.dim('// Big font (default)'));
+console.log(ascii.banner('HELLO'));
+
+console.log(color.dim('// Small font'));
+console.log(ascii.banner('HELLO', { font: 'small' }));
+
+console.log(color.dim('// With gradient'));
+console.log(ascii.banner('ANSIMAX', {
+  font: 'big',
+  colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9', '#8be9fd']),
+}));
+
+console.log(color.dim('// Aligned center'));
+console.log(ascii.banner('CENTER', { align: 'center' }));
+
+console.log(color.dim('// Available fonts:'));
+console.log('  fonts:', listFonts().join(', '));
+console.log('  has "big":', hasFont('big'));
+console.log('  has "small":', hasFont('small'));
+console.log('  has "unicorn":', hasFont('unicorn'));
+console.log();
+
+console.log(color.bold('━━━ Boxes (6 real styles) ━━━'));
+console.log();
+
+// REAL box styles: single, double, rounded, heavy, dashed, ascii
+const boxStyles = ['single', 'double', 'rounded', 'heavy', 'dashed', 'ascii'] as const;
+for (const style of boxStyles) {
+  console.log(color.dim(`// borderStyle: ${style}`));
+  console.log(ascii.box(`This is a ${style} box`, {
+    padding: 1,
+    borderStyle: style,
+  }));
+}
+
+console.log(color.dim('// Multi-line box'));
+console.log(ascii.box(
+  'Line 1\nLine 2 with a bit longer text\nLine 3',
+  { padding: 1, borderStyle: 'rounded' },
+));
+
+console.log();
+console.log(color.bold('━━━ Dividers ━━━'));
+console.log();
+
+console.log(ascii.divider({ char: '─', width: 50 }));
+console.log(ascii.divider({ char: '═', width: 50 }));
+console.log(ascii.divider({ char: '━', width: 50, label: 'Section' }));
+console.log();
+
+console.log(color.bold('━━━ Logo composer ━━━'));
+console.log();
+
+console.log(ascii.logo('LOGO', {
+  font: 'big',
+  colorFn: (t) => gradient(t, ['#ff6b6b', '#feca57', '#48dbfb']),
+  borderStyle: 'rounded',
+}));
+
+console.log();
+console.log(color.bold('━━━ ascii.measure ━━━'));
+console.log();
+const dim = ascii.measure('Hello World', { font: 'big' });
+console.log(`  Banner dimensions: ${dim.width} × ${dim.height}`);
+console.log();
+
+console.log(color.bold(color.green('✓ ASCII test complete')));
+console.log();