ansimax 1.0.0 → 1.1.1

package/examples/03-pixel-art-game.ts

@@ -0,0 +1,170 @@
+// ─────────────────────────────────────────────
+//  EXAMPLE 3 — Pixel art game loop
+//
+//  Demonstrates:
+//   - Canvas with dirty-region rendering for FPS
+//   - Sprite drawing with alpha blending
+//   - Gradient backgrounds with Bayer dithering
+//   - Frame-rate locked game loop (drift-corrected)
+//   - Braille mode for high-resolution detail
+//
+//  A bouncing rocket on a sunset gradient with a star field.
+//
+//  Run:
+//    npx ts-node examples/03-pixel-art-game.ts
+// ─────────────────────────────────────────────
+
+import {
+  createCanvas,
+  images,
+  themes,
+  cursor,
+  screen,
+  write,
+  sleep,
+  termSize,
+  type RGBA,
+} from '../dist/index.js';
+
+const WIDTH  = 60;
+const HEIGHT = 30;
+
+// ── Build static background once ───────────────
+const buildBackground = (): ReturnType<typeof createCanvas> => {
+  const canvas = createCanvas(WIDTH, HEIGHT);
+
+  // Sunset gradient with Bayer dithering for smooth bands
+  const gradStr = images.gradientRect({
+    width: WIDTH,
+    height: HEIGHT,
+    colors: ['#1a1a2e', '#16213e', '#fd7272', '#f9ca24'],
+    style: 'vertical',
+    dither: 'bayer',
+  });
+  // gradientRect returns rendered text; instead we build pixels manually
+  // so we can composite sprites on top.
+  for (let y = 0; y < HEIGHT; y++) {
+    for (let x = 0; x < WIDTH; x++) {
+      // Simple vertical sunset
+      const t = y / (HEIGHT - 1);
+      const r = Math.round(0x1a + (0xf9 - 0x1a) * t);
+      const g = Math.round(0x1a + (0xca - 0x1a) * t);
+      const b = Math.round(0x2e + (0x24 - 0x2e) * t);
+      canvas.set(x, y, { r, g, b });
+    }
+  }
+
+  // Star field — random white dots in upper half
+  for (let i = 0; i < 30; i++) {
+    const x = Math.floor(Math.random() * WIDTH);
+    const y = Math.floor(Math.random() * (HEIGHT / 2));
+    const brightness = 150 + Math.floor(Math.random() * 100);
+    canvas.set(x, y, { r: brightness, g: brightness, b: brightness });
+  }
+
+  return canvas;
+};
+
+// ── Rocket sprite (5×5) with alpha edges for soft blending ──
+const ROCKET = [
+  [null,  null,  { r: 255, g: 255, b: 255 }, null,  null ],
+  [null,  { r: 255, g: 100, b: 100 }, { r: 255, g: 200, b: 200 }, { r: 255, g: 100, b: 100 }, null ],
+  [{ r: 200, g: 50, b: 50, a: 0.7 } as RGBA, { r: 255, g: 100, b: 100 }, { r: 255, g: 150, b: 150 }, { r: 255, g: 100, b: 100 }, { r: 200, g: 50, b: 50, a: 0.7 } as RGBA],
+  [null,  { r: 255, g: 200, b: 50 }, { r: 255, g: 240, b: 100 }, { r: 255, g: 200, b: 50 }, null ],
+  [null,  null,  { r: 255, g: 150, b: 50, a: 0.6 } as RGBA, null,  null ],
+];
+
+// ── Main loop ──────────────────────────────────
+const main = async (): Promise<void> => {
+  const { rows } = termSize();
+  if (rows < HEIGHT + 5) {
+    console.log(themes.error(`Terminal too small. Needs at least ${HEIGHT + 5} rows.`));
+    process.exit(1);
+  }
+
+  write(screen.clear());
+  write(cursor.hide());
+  write(cursor.to(1, 1));
+  console.log(themes.banner('ROCKET', { font: 'small' }));
+
+  const bg = buildBackground();
+
+  let rocketX = WIDTH / 2;
+  let rocketY = HEIGHT - 8;
+  let vx = 0.4;
+  let vy = -0.25;
+
+  const ctrl = new AbortController();
+  process.on('SIGINT', () => {
+    ctrl.abort();
+    write(cursor.show());
+    write(cursor.to(1, HEIGHT + 8));
+    console.log(themes.muted('\nGame stopped.'));
+    process.exit(0);
+  });
+
+  // Frame loop — drift-corrected via wall clock
+  const FRAME_MS = 60; // ~16 FPS
+  const startTime = Date.now();
+  let frame = 0;
+
+  const FPS_HIST: number[] = [];
+  let lastFrameTime = Date.now();
+
+  while (!ctrl.signal.aborted) {
+    // Clone background to a frame canvas (so sprites don't mutate the bg)
+    const frameCanvas = createCanvas(WIDTH, HEIGHT);
+    for (let y = 0; y < HEIGHT; y++) {
+      for (let x = 0; x < WIDTH; x++) {
+        frameCanvas.set(x, y, bg.get(x, y));
+      }
+    }
+
+    // Update rocket physics
+    rocketX += vx;
+    rocketY += vy;
+    if (rocketX <= 2 || rocketX >= WIDTH - 5) vx = -vx;
+    if (rocketY <= 2 || rocketY >= HEIGHT - 5) vy = -vy;
+
+    // Draw the rocket with alpha blending
+    frameCanvas.drawSprite(Math.round(rocketX), Math.round(rocketY), ROCKET);
+
+    // FPS calc
+    const now = Date.now();
+    const delta = now - lastFrameTime;
+    lastFrameTime = now;
+    if (delta > 0) {
+      FPS_HIST.push(1000 / delta);
+      if (FPS_HIST.length > 30) FPS_HIST.shift();
+    }
+    const avgFps = FPS_HIST.reduce((s, n) => s + n, 0) / Math.max(1, FPS_HIST.length);
+
+    // Render
+    write(cursor.to(1, 7));
+    write(frameCanvas.render());
+    write(cursor.to(1, HEIGHT + 8));
+    write(themes.muted(
+      `Frame ${frame.toString().padStart(4)} · ` +
+      `${avgFps.toFixed(1)} fps · ` +
+      `Ctrl+C to exit`,
+    ));
+
+    // Drift-correct sleep
+    frame++;
+    const targetTime = startTime + frame * FRAME_MS;
+    const waitMs = Math.max(0, targetTime - Date.now());
+    try {
+      await sleep(waitMs, { signal: ctrl.signal });
+    } catch {
+      break;
+    }
+  }
+
+  write(cursor.show());
+};
+
+main().catch((err) => {
+  write(cursor.show());
+  console.error(themes.error('✗ ' + (err as Error).message));
+  process.exit(1);
+});

package/examples/04-interactive-deploy.ts

@@ -0,0 +1,163 @@
+// ─────────────────────────────────────────────
+//  EXAMPLE 4 — Interactive prompt with menu + multi-loader
+//
+//  Demonstrates:
+//   - components.menu (interactive arrow-key navigation)
+//   - MENU_CANCELLED handling
+//   - loader.multi() — concurrent named operations
+//   - configure() side effects + onConfigChange
+//   - Theme switching at runtime
+//   - createTheme() for isolated theme instances
+//
+//  Walks the user through choosing a theme, then runs parallel
+//  "deployment" operations under a multi-loader.
+//
+//  Run:
+//    npx ts-node examples/04-interactive-deploy.ts
+// ─────────────────────────────────────────────
+
+import {
+  components,
+  loader,
+  themes,
+  createTheme,
+  configure,
+  onConfigChange,
+  sleep,
+  MENU_CANCELLED,
+} from '../dist/index.js';
+
+const main = async (): Promise<void> => {
+  // ── Subscribe to config changes globally ──
+  const offChange = onConfigChange((c) => {
+    // Each time the theme changes, the global `themes` follows automatically
+    // thanks to configure() side effects. We just log it.
+    console.log(themes.muted(`  [config] theme=${c.theme} colorMode=${c.colorMode}`));
+  });
+
+  // ── Step 1: Banner ─────────────────────────────
+  console.log();
+  console.log(themes.banner('DEPLOY', { font: 'small' }));
+  console.log(components.section(themes.primary('Configure deployment'), { width: 60 }));
+  console.log();
+
+  // ── Step 2: Pick a theme via menu ─────────────
+  console.log(themes.text('Select a theme for the output:'));
+  console.log();
+
+  const themeChoices = ['dracula', 'nord', 'monokai', 'matrix', 'cyberpunk'];
+  const choice = await components.menu(themeChoices, {
+    title: '  Available themes',
+    pointer: '▸',
+  });
+
+  if (choice === MENU_CANCELLED) {
+    console.log();
+    console.log(themes.warning('⚠ Cancelled by user'));
+    offChange();
+    return;
+  }
+
+  const themeName = themeChoices[choice as number]!;
+  configure({ theme: themeName });
+  console.log();
+  console.log(themes.accent(`✓ Theme set to ${themeName}`));
+  console.log();
+
+  // ── Step 3: Pick deployment regions (multi-select) ──
+  const regionChoices = ['us-east-1', 'us-west-2', 'eu-west-1', 'ap-south-1', 'sa-east-1'];
+  console.log(themes.text('Select target regions (Space to toggle, Enter to confirm):'));
+  console.log();
+
+  const regions = await components.menu(regionChoices, {
+    title: '  Regions',
+    pointer: '▸',
+    multiSelect: true,
+  });
+
+  if (regions === MENU_CANCELLED) {
+    console.log();
+    console.log(themes.warning('⚠ Cancelled by user'));
+    offChange();
+    return;
+  }
+
+  const selectedRegions = (regions as number[]).map((i) => regionChoices[i]!);
+  if (selectedRegions.length === 0) {
+    console.log(themes.warning('⚠ No regions selected — aborting'));
+    offChange();
+    return;
+  }
+
+  console.log();
+  console.log(components.box(
+    themes.primary('Plan:') + '\n' +
+    selectedRegions.map((r) => `  • ${r}`).join('\n'),
+    { borderStyle: 'rounded', padding: 1 },
+  ));
+  console.log();
+
+  // ── Step 4: Multi-loader for parallel deployments ──
+  console.log(themes.text('Starting parallel deployments...'));
+  console.log();
+
+  const m = loader.multi();
+  const items = selectedRegions.map((region) => {
+    const item = m.add(`Deploying to ${region}`, { color: '#48dbfb' });
+    return { region, item };
+  });
+
+  // Run each region in parallel
+  await Promise.all(items.map(async ({ region, item }) => {
+    // Stage 1: build
+    item.update(`[${region}] Building image...`);
+    await sleep(400 + Math.random() * 600);
+
+    // Stage 2: upload
+    item.update(`[${region}] Uploading...`);
+    await sleep(600 + Math.random() * 800);
+
+    // Stage 3: switch
+    item.update(`[${region}] Switching traffic...`);
+    await sleep(300 + Math.random() * 400);
+
+    // Random failure chance for one region
+    if (Math.random() < 0.15) {
+      item.fail(`[${region}] Failed: health check timeout`);
+    } else {
+      item.succeed(`[${region}] Live`);
+    }
+  }));
+
+  // Wait for the multi-loader to settle (final renders)
+  await sleep(150);
+
+  // ── Step 5: Multi-tenant theme demo ───────────
+  // Create an isolated theme instance for the summary
+  // (does not affect global state)
+  const summary = createTheme('matrix');
+
+  console.log();
+  console.log(components.section(summary.primary('Deployment summary'), { width: 60 }));
+  console.log();
+
+  console.log(components.timeline(
+    selectedRegions.map((r) => ({
+      label: `Deployed to ${r}`,
+      time: new Date().toLocaleTimeString(),
+      done: true,
+    })),
+  ));
+
+  console.log();
+  console.log(summary.muted('Global theme remains: ' + themes.current().name));
+  console.log(summary.muted('Isolated summary theme: ' + summary.current().name));
+  console.log();
+
+  offChange();
+};
+
+main().catch((err) => {
+  console.error(themes.error('✗ ' + (err as Error).message));
+  process.exit(1);
+});

package/examples/04-trees.ts

@@ -0,0 +1,117 @@
+/**
+ * 04 — Trees
+ *
+ * Run: npx tsx examples/04-trees.ts
+ */
+
+import {
+  tree,
+  renderTree,
+  walkTree,
+  findInTree,
+  countNodes,
+  mapTree,
+  filterTree,
+  measureTree,
+  color,
+  type TreeData,
+} from '../src/index.js';
+
+console.log();
+console.log(color.bold('━━━ Builder API ━━━'));
+console.log();
+
+const project = tree({ label: 'my-app', icon: '📦', color: color.bold });
+const src = project.add({ label: 'src', icon: '📁' });
+src.addLeaf({ label: 'index.ts', icon: '📄' });
+src.addLeaf({ label: 'app.ts', icon: '📄' });
+const utils = src.add({ label: 'utils', icon: '📁' });
+utils.addLeaf({ label: 'helpers.ts', icon: '📄' });
+utils.addLeaf({ label: 'logger.ts', icon: '📄' });
+project.addLeaf({ label: 'package.json', icon: '📦' });
+project.addLeaf({ label: 'README.md', icon: '📝' });
+
+console.log(project.render());
+console.log();
+
+console.log(color.bold('━━━ Tree styles ━━━'));
+console.log();
+
+const styles = ['rounded', 'classic', 'thick', 'double', 'ascii', 'heavy'] as const;
+for (const style of styles) {
+  console.log(color.dim(`// style: ${style}`));
+  console.log(project.render({ style }));
+}
+
+console.log(color.bold('━━━ Palette colors ━━━'));
+console.log();
+
+console.log(project.render({
+  style: 'rounded',
+  palette: [color.cyan, color.green, color.magenta, color.yellow],
+  guideColor: color.dim,
+}));
+console.log();
+
+console.log(color.bold('━━━ Plain-data API ━━━'));
+console.log();
+
+const tree2: TreeData = {
+  label: 'dependencies',
+  icon: '📦',
+  children: [
+    {
+      label: 'production',
+      icon: '🔒',
+      children: [
+        { label: 'react@18.2.0', icon: '⚛️' },
+        { label: 'tailwind@3.4.1', icon: '🎨' },
+      ],
+    },
+    {
+      label: 'development',
+      icon: '🛠️',
+      children: [
+        { label: 'typescript@5.4.0', icon: '🔷' },
+        { label: 'jest@29.7.0', icon: '🧪' },
+        { label: 'eslint@8.57.0', icon: '✅' },
+      ],
+    },
+  ],
+};
+
+console.log(renderTree(tree2));
+console.log();
+
+console.log(color.bold('━━━ maxDepth truncation ━━━'));
+console.log();
+console.log(color.dim('// maxDepth: 1'));
+console.log(renderTree(tree2, { maxDepth: 1 }));
+console.log();
+
+console.log(color.bold('━━━ Algorithms ━━━'));
+console.log();
+console.log('  countNodes:', countNodes(tree2));
+
+const found = findInTree(tree2, (n) => n.label.includes('react'));
+console.log('  findInTree (react):', found?.label);
+
+console.log('  walkTree paths:');
+walkTree(tree2, (node, depth) => {
+  if (depth > 0) console.log('    ' + '  '.repeat(depth) + '→ ' + node.label);
+});
+
+const upper = mapTree(tree2, (node) => ({ ...node, label: node.label.toUpperCase() }));
+console.log('\n  mapTree (uppercase):');
+console.log(renderTree(upper));
+
+const onlyDev = filterTree(tree2, (n) => n.label !== 'production', { prune: true });
+console.log('  filterTree (no production):');
+if (onlyDev) console.log(renderTree(onlyDev));
+
+const dim = measureTree(tree2);
+console.log(`  measureTree: ${dim.width} × ${dim.height}`);
+console.log();
+
+console.log(color.bold(color.green('✓ Trees test complete')));
+console.log();

package/examples/05-components.ts

@@ -0,0 +1,96 @@
+/**
+ * 05 — Components (NO interactive menu — tested separately)
+ *
+ * Run: npx tsx examples/05-components.ts
+ */
+
+import { components, box, color } from '../src/index.js';
+
+console.log();
+console.log(color.bold('━━━ Tables ━━━'));
+console.log();
+
+console.log(components.table([
+  ['Module', 'Status', 'Coverage', 'Tests'],
+  ['colors', color.green('● ready'), '100%', '180'],
+  ['animations', color.green('● ready'), '99%', '245'],
+  ['loaders', color.green('● ready'), '99%', '210'],
+  ['frames', color.green('● ready'), '99%', '125'],
+  ['components', color.green('● ready'), '100%', '198'],
+  ['themes', color.green('● ready'), '100%', '94'],
+  ['trees', color.green('● ready'), '100%', '87'],
+], { borderStyle: 'rounded' }));
+console.log();
+
+console.log(color.dim('// Table with double border'));
+console.log(components.table([
+  ['Name', 'Age', 'City'],
+  ['Ana', '25', 'Madrid'],
+  ['Carlos', '30', 'Lima'],
+], { borderStyle: 'double' }));
+console.log();
+
+console.log(color.bold('━━━ Badges ━━━'));
+console.log();
+console.log(' ',
+  components.badge('VERSION', 'v1.1.0'),
+  components.badge('BUILD', 'passing'),
+  components.badge('LICENSE', 'Apache 2.0'),
+  components.badge('NPM', 'ansimax'),
+);
+console.log();
+
+console.log(color.bold('━━━ Status ━━━'));
+console.log();
+console.log(components.status('Build started', { type: 'info' }));
+console.log(components.status('Linting passed', { type: 'success' }));
+console.log(components.status('5 deprecation warnings', { type: 'warning' }));
+console.log(components.status('Build failed', { type: 'error' }));
+console.log();
+
+console.log(color.bold('━━━ Section ━━━'));
+console.log();
+console.log(components.section('Installation Steps', { width: 60 }));
+console.log();
+console.log(components.section('Configuration', { width: 60 }));
+console.log();
+
+console.log(color.bold('━━━ Columns ━━━'));
+console.log();
+console.log(components.columns([
+  'Lorem ipsum dolor sit amet',
+  'Consectetur adipiscing elit',
+  'Sed do eiusmod tempor',
+], { cols: 3, gap: 2, width: 60 }));
+console.log();
+
+console.log(color.bold('━━━ Timeline ━━━'));
+console.log();
+console.log(components.timeline([
+  { label: 'Project initialized', done: true, time: '10:00' },
+  { label: 'Dependencies installed', done: true, time: '10:05' },
+  { label: 'Build pipeline configured', done: true, time: '10:15' },
+  { label: 'Tests running', done: false, time: '10:32' },
+  { label: 'Deploy to npm', done: false },
+]));
+console.log();
+
+console.log(color.bold('━━━ Static progress bars ━━━'));
+console.log();
+for (const pct of [10, 25, 50, 75, 90, 100]) {
+  console.log(' ', `${pct.toString().padStart(3)}%`, components.progressBar(pct, { width: 30 }));
+}
+console.log();
+
+console.log(color.bold('━━━ box utility ━━━'));
+console.log();
+console.log(box('Simple box utility', { padding: 1 }));
+console.log();
+console.log(box('Padded + bordered\nwith multiple lines', {
+  padding: 2,
+  borderStyle: 'rounded',
+}));
+console.log();
+
+console.log(color.bold(color.green('✓ Components test complete')));
+console.log();