unicode-animations 0.1.3 → 0.1.9

package/README.md

@@ -30,7 +30,9 @@ const spinners = require('unicode-animations');
 
 Each spinner is a `{ frames: string[], interval: number }` object.
 
-## Terminal example
+## Examples
+
+### Spinner while awaiting an async task
 
 ```js
 import spinners from 'unicode-animations';
@@ -38,29 +40,115 @@ import spinners from 'unicode-animations';
 const { frames, interval } = spinners.braille;
 let i = 0;
 
-const timer = setInterval(() => {
-  process.stdout.write(`\r${frames[i++ % frames.length]} Loading...`);
+const spinner = setInterval(() => {
+  process.stdout.write(`\r  ${frames[i++ % frames.length]} Installing dependencies...`);
 }, interval);
 
-// Stop after 3s
-setTimeout(() => {
-  clearInterval(timer);
-  process.stdout.write('\r✔ Done!     \n');
-}, 3000);
+await install();
+
+clearInterval(spinner);
+process.stdout.write('\r  ✔ Installed successfully.\n');
 ```
 
-## Browser example
+### Multi-character braille spinner
+
+The grid-based spinners produce wider animated patterns — useful for visual flair in CLI tools:
 
 ```js
 import spinners from 'unicode-animations';
 
-const el = document.getElementById('spinner');
-const { frames, interval } = spinners.arc;
+const { frames, interval } = spinners.helix;
+let i = 0;
+
+const spinner = setInterval(() => {
+  process.stdout.write(`\r  ${frames[i++ % frames.length]}  Building...`);
+}, interval);
+```
+
+### Progress indicator with dynamic message
+
+```js
+import spinners from 'unicode-animations';
+
+function withSpinner(message, spinner = spinners.braille) {
+  let i = 0;
+  const { frames, interval } = spinner;
+  const timer = setInterval(() => {
+    process.stdout.write(`\r\x1B[2K  ${frames[i++ % frames.length]} ${message}`);
+  }, interval);
+
+  return {
+    update(msg) { message = msg; },
+    stop(finalMsg) {
+      clearInterval(timer);
+      process.stdout.write(`\r\x1B[2K  ✔ ${finalMsg}\n`);
+    },
+  };
+}
+
+const spin = withSpinner('Fetching data...');
+const data = await fetchData();
+spin.update(`Processing ${data.length} records...`);
+await processData(data);
+spin.stop('Done.');
+```
+
+### Cycle through different spinners
+
+```js
+import spinners from 'unicode-animations';
+
+const names = ['scan', 'rain', 'helix', 'cascade'];
+let current = 0;
 let i = 0;
 
 setInterval(() => {
-  el.textContent = frames[i++ % frames.length];
+  const s = spinners[names[current]];
+  process.stdout.write(`\r\x1B[2K  ${s.frames[i % s.frames.length]}  ${names[current]}`);
+  i++;
+  if (i % 20 === 0) current = (current + 1) % names.length;
+}, 80);
+```
+
+### Browser — inline loading text
+
+```js
+import spinners from 'unicode-animations';
+
+const el = document.getElementById('status');
+const { frames, interval } = spinners.arc;
+let i = 0;
+
+const spinner = setInterval(() => {
+  el.textContent = `${frames[i++ % frames.length]} Loading...`;
 }, interval);
+
+// Stop when done
+function onLoaded() {
+  clearInterval(spinner);
+  el.textContent = '✔ Ready';
+}
+```
+
+### React component
+
+```jsx
+import { useState, useEffect } from 'react';
+import spinners from 'unicode-animations';
+
+function Spinner({ name = 'braille', text = 'Loading...' }) {
+  const [frame, setFrame] = useState(0);
+  const spinner = spinners[name];
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setFrame(f => (f + 1) % spinner.frames.length);
+    }, spinner.interval);
+    return () => clearInterval(timer);
+  }, [name]);
+
+  return <span>{spinner.frames[frame]} {text}</span>;
+}
 ```
 
 ## All spinners

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unicode-animations",
-  "version": "0.1.3",
+  "version": "0.1.9",
   "description": "Unicode spinner animations as raw frame data",
   "type": "module",
   "exports": {
@@ -13,6 +13,9 @@
       "require": { "types": "./dist/braille.d.cts", "default": "./dist/braille.cjs" }
     }
   },
+  "bin": {
+    "unicode-animations": "./scripts/demo.cjs"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,7 +23,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsup",
-    "postinstall": "node scripts/postinstall.js",
+    "postinstall": "node scripts/postinstall.cjs",
     "prepublishOnly": "npm run build"
   },
   "repository": {

package/scripts/demo.cjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+const path = require('path');
+
+let S;
+try {
+  S = require(path.join(__dirname, '..', 'dist', 'index.cjs'));
+  S = S.spinners || S.default;
+} catch {
+  console.error('Run `npm run build` first.');
+  process.exit(1);
+}
+
+const names = Object.keys(S);
+const args = process.argv.slice(2);
+
+// Usage: npx unicode-animations [name]
+// No args = cycle through all spinners
+// With name = show that specific spinner
+
+const hide = '\x1B[?25l';
+const show = '\x1B[?25h';
+const clear = '\x1B[2K\r';
+const bold = '\x1B[1m';
+const dim = '\x1B[2m';
+const cyan = '\x1B[36m';
+const magenta = '\x1B[35m';
+const reset = '\x1B[0m';
+
+process.stdout.write(hide);
+const cleanup = () => process.stdout.write(show);
+process.on('SIGINT', () => { cleanup(); console.log(); process.exit(0); });
+process.on('exit', cleanup);
+
+if (args[0] === '--list' || args[0] === '-l') {
+  cleanup();
+  console.log(`\n${bold}22 spinners available:${reset}\n`);
+  for (const name of names) {
+    const s = S[name];
+    console.log(`  ${magenta}${s.frames[0]}${reset}  ${name} ${dim}(${s.frames.length} frames, ${s.interval}ms)${reset}`);
+  }
+  console.log();
+  process.exit(0);
+}
+
+if (args[0] && !names.includes(args[0])) {
+  cleanup();
+  console.error(`Unknown spinner: "${args[0]}"\nRun with --list to see all spinners.`);
+  process.exit(1);
+}
+
+let current = args[0] ? names.indexOf(args[0]) : 0;
+const single = !!args[0];
+let i = 0;
+let ticksOnCurrent = 0;
+
+const TICKS_PER_SPINNER = 40; // ~3.2s per spinner when cycling
+
+const timer = setInterval(() => {
+  const name = names[current];
+  const s = S[name];
+  const frame = s.frames[i % s.frames.length];
+  const count = `${dim}[${current + 1}/${names.length}]${reset}`;
+
+  process.stdout.write(`${clear}  ${magenta}${frame}${reset}  ${bold}${name}${reset} ${dim}${s.interval}ms${reset}  ${single ? '' : count}`);
+
+  i++;
+  ticksOnCurrent++;
+
+  if (!single && ticksOnCurrent >= TICKS_PER_SPINNER) {
+    ticksOnCurrent = 0;
+    i = 0;
+    current = (current + 1) % names.length;
+  }
+}, 80);

package/scripts/postinstall.cjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const tty = require('tty');
+const path = require('path');
+
+const ci = process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.GITHUB_ACTIONS;
+if (ci) process.exit(0);
+
+let out;
+try {
+  const fd = fs.openSync('/dev/tty', 'w');
+  out = new tty.WriteStream(fd);
+} catch {
+  process.exit(0);
+}
+
+let S;
+try {
+  const mod = require(path.join(__dirname, '..', 'dist', 'index.cjs'));
+  S = mod.spinners || mod.default;
+  if (!S || !S.braille) throw new Error();
+} catch {
+  process.exit(0);
+}
+
+try {
+  const DURATION = 3000;
+  const INTERVAL = 80;
+
+  const d = '\x1B[2m';
+  const b = '\x1B[1m';
+  const r = '\x1B[0m';
+  const c = '\x1B[36m';
+  const g = '\x1B[32m';
+  const w = '\x1B[37m';
+  const m = '\x1B[35m';
+  const hide = '\x1B[?25l';
+  const show = '\x1B[?25h';
+
+  out.write(hide);
+  const cleanup = () => { try { out.write(show); } catch {} };
+  process.on('SIGINT', () => { cleanup(); process.exit(0); });
+
+  // Header
+  out.write(`
+${b}${w}  ██╗   ██╗███╗   ██╗██╗ ██████╗ ██████╗ ██████╗ ███████╗${r}
+${b}${w}  ██║   ██║████╗  ██║██║██╔════╝██╔═══██╗██╔══██╗██╔════╝${r}
+${b}${w}  ██║   ██║██╔██╗ ██║██║██║     ██║   ██║██║  ██║█████╗${r}
+${b}${w}  ██║   ██║██║╚██╗██║██║██║     ██║   ██║██║  ██║██╔══╝${r}
+${b}${w}  ╚██████╔╝██║ ╚████║██║╚██████╗╚██████╔╝██████╔╝███████╗${r}
+${d}   ╚═════╝ ╚═╝  ╚═══╝╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝${r}
+${b}${c}            a n i m a t i o n s${r}
+
+`);
+
+  // Braille spinners only, 2 columns of 9
+  const left = [
+    ['Braille',    S.braille],
+    ['Orbit',      S.orbit],
+    ['Breathe',    S.breathe],
+    ['Snake',      S.snake],
+    ['Fill Sweep', S.fillsweep],
+    ['Diag Swipe', S.diagswipe],
+    ['Pulse',      S.pulse],
+    ['Scanline',   S.scanline],
+    ['Columns',    S.columns],
+  ];
+
+  const right = [
+    ['Checkerboard', S.checkerboard],
+    ['Scan',         S.scan],
+    ['Rain',         S.rain],
+    ['Sparkle',      S.sparkle],
+    ['Cascade',      S.cascade],
+    ['Wave Rows',    S.waverows],
+    ['Helix',        S.helix],
+    ['Braille Wave', S.braillewave],
+    ['DNA',          S.dna],
+  ];
+
+  const ROWS = left.length;
+
+  function pad(str, n) { return str + ' '.repeat(Math.max(0, n - str.length)); }
+
+  function renderGrid(tick) {
+    let buf = '';
+    for (let i = 0; i < ROWS; i++) {
+      const [ln, ls] = left[i];
+      const [rn, rs] = right[i];
+      const lf = ls.frames[tick % ls.frames.length];
+      const rf = rs.frames[tick % rs.frames.length];
+      buf += `    ${m}${pad(lf, 3)}${r}  ${d}${pad(ln, 12)}${r}  ${m}${pad(rf, 12)}${r}  ${d}${rn}${r}\n`;
+    }
+    return buf;
+  }
+
+  out.write(renderGrid(0));
+
+  let tick = 1;
+  const start = Date.now();
+
+  const timer = setInterval(() => {
+    if (Date.now() - start >= DURATION) {
+      clearInterval(timer);
+      out.write(`\n  ${g}${b}✔${r} ${b}unicode-animations${r} ${d}— 18 braille spinners + 4 classics${r}\n\n`);
+      cleanup();
+      return;
+    }
+    out.write(`\x1B[${ROWS}A`);
+    out.write(renderGrid(tick));
+    tick++;
+  }, INTERVAL);
+} catch {
+  try { out.write('\x1B[?25h'); } catch {}
+  process.exit(0);
+}

package/scripts/postinstall.js

@@ -1,67 +0,0 @@
-#!/usr/bin/env node
-
-// Postinstall animation — showcases a few spinners side-by-side for ~1.5s
-// Skips gracefully in CI or non-interactive environments
-
-// npm 7+ captures ALL lifecycle script stdio (stdout + stderr) and swallows
-// output on success. The only way to reach the real terminal is /dev/tty.
-const fs = require('fs');
-const tty = require('tty');
-
-const ci = process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.GITHUB_ACTIONS;
-if (ci) process.exit(0);
-
-let out;
-try {
-  const fd = fs.openSync('/dev/tty', 'w');
-  out = new tty.WriteStream(fd);
-} catch {
-  // No controlling terminal (CI, Docker, piped, etc.)
-  process.exit(0);
-}
-
-try {
-  const DURATION = 1500;
-  const INTERVAL = 80;
-
-  // Inline a few single-char spinners to avoid importing dist (may not exist yet)
-  const spinners = [
-    { frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] }, // braille
-    { frames: ['◜', '◠', '◝', '◞', '◡', '◟'] },                           // arc
-    { frames: ['◐', '◓', '◑', '◒'] },                                       // halfmoon
-    { frames: ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█', '▇', '▆', '▅', '▄', '▃', '▂'] }, // blocks
-    { frames: ['|', '/', '—', '\\'] },                                        // line
-  ];
-
-  const hide = '\x1B[?25l';
-  const show = '\x1B[?25h';
-  const clearLine = '\x1B[2K\r';
-  const bold = '\x1B[1m';
-  const green = '\x1B[32m';
-  const reset = '\x1B[0m';
-
-  out.write(hide);
-
-  const cleanup = () => { try { out.write(show); } catch {} };
-  process.on('SIGINT', () => { cleanup(); process.exit(0); });
-
-  let tick = 0;
-  const start = Date.now();
-
-  const timer = setInterval(() => {
-    if (Date.now() - start >= DURATION) {
-      clearInterval(timer);
-      const done = `${clearLine}  ${green}${bold}✔${reset} ${bold}unicode-animations${reset} — 22 spinners ready\n`;
-      out.write(done);
-      cleanup();
-      return;
-    }
-
-    const chars = spinners.map(s => s.frames[tick % s.frames.length]);
-    out.write(`${clearLine}  ${chars.join('  ')}`);
-    tick++;
-  }, INTERVAL);
-} catch {
-  // Never block install
-  process.exit(0);
-}