unicode-animations 0.1.9 → 1.0.0

package/README.md

@@ -2,14 +2,15 @@
 
 Unicode spinner animations as raw frame data — no dependencies, works everywhere.
 
-## Preview
+## Demo
 
-```
-braille   ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏
-arc       ◜ ◠ ◝ ◞ ◡ ◟
-halfmoon  ◐ ◓ ◑ ◒
-blocks    ▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ▇ ▆ ▅ ▄ ▃ ▂
-line      | / — \
+See all 18 spinners animating live:
+
+```bash
+npx unicode-animations --web     # open browser demo
+npx unicode-animations           # cycle through all in terminal
+npx unicode-animations helix     # preview a specific spinner
+npx unicode-animations --list    # list all spinners
 ```
 
 ## Install
@@ -32,7 +33,7 @@ Each spinner is a `{ frames: string[], interval: number }` object.
 
 ## Examples
 
-### Spinner while awaiting an async task
+### CLI tool — spinner during async work
 
 ```js
 import spinners from 'unicode-animations';
@@ -41,114 +42,103 @@ const { frames, interval } = spinners.braille;
 let i = 0;
 
 const spinner = setInterval(() => {
-  process.stdout.write(`\r  ${frames[i++ % frames.length]} Installing dependencies...`);
+  process.stdout.write(`\r\x1B[2K  ${frames[i++ % frames.length]} Deploying to production...`);
 }, interval);
 
-await install();
+await deploy();
 
 clearInterval(spinner);
-process.stdout.write('\r  ✔ Installed successfully.\n');
+process.stdout.write('\r\x1B[2K  ✔ Deployed.\n');
 ```
 
-### Multi-character braille spinner
-
-The grid-based spinners produce wider animated patterns — useful for visual flair in CLI tools:
+### Reusable spinner helper
 
 ```js
 import spinners from 'unicode-animations';
 
-const { frames, interval } = spinners.helix;
-let i = 0;
+function createSpinner(msg, name = 'braille') {
+  const { frames, interval } = spinners[name];
+  let i = 0, text = msg;
+  const timer = setInterval(() => {
+    process.stdout.write(`\r\x1B[2K  ${frames[i++ % frames.length]} ${text}`);
+  }, interval);
 
-const spinner = setInterval(() => {
-  process.stdout.write(`\r  ${frames[i++ % frames.length]}  Building...`);
-}, interval);
+  return {
+    update(msg) { text = msg; },
+    stop(msg) { clearInterval(timer); process.stdout.write(`\r\x1B[2K  ✔ ${msg}\n`); },
+  };
+}
+
+const s = createSpinner('Connecting to database...');
+const db = await connect();
+s.update(`Running ${migrations.length} migrations...`);
+await db.migrate(migrations);
+s.stop('Database ready.');
 ```
 
-### Progress indicator with dynamic message
+### Multi-step pipeline
 
 ```js
 import spinners from 'unicode-animations';
 
-function withSpinner(message, spinner = spinners.braille) {
+async function runWithSpinner(label, fn, name = 'braille') {
+  const { frames, interval } = spinners[name];
   let i = 0;
-  const { frames, interval } = spinner;
   const timer = setInterval(() => {
-    process.stdout.write(`\r\x1B[2K  ${frames[i++ % frames.length]} ${message}`);
+    process.stdout.write(`\r\x1B[2K  ${frames[i++ % frames.length]} ${label}`);
   }, interval);
-
-  return {
-    update(msg) { message = msg; },
-    stop(finalMsg) {
-      clearInterval(timer);
-      process.stdout.write(`\r\x1B[2K  ✔ ${finalMsg}\n`);
-    },
-  };
+  const result = await fn();
+  clearInterval(timer);
+  process.stdout.write(`\r\x1B[2K  ✔ ${label}\n`);
+  return result;
 }
 
-const spin = withSpinner('Fetching data...');
-const data = await fetchData();
-spin.update(`Processing ${data.length} records...`);
-await processData(data);
-spin.stop('Done.');
+await runWithSpinner('Linting...', lint, 'scan');
+await runWithSpinner('Running tests...', test, 'helix');
+await runWithSpinner('Building...', build, 'cascade');
+await runWithSpinner('Publishing...', publish, 'braille');
 ```
 
-### Cycle through different spinners
+### React component
 
-```js
+```jsx
+import { useState, useEffect } from 'react';
 import spinners from 'unicode-animations';
 
-const names = ['scan', 'rain', 'helix', 'cascade'];
-let current = 0;
-let i = 0;
+function Spinner({ name = 'braille', children }) {
+  const [frame, setFrame] = useState(0);
+  const s = spinners[name];
 
-setInterval(() => {
-  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);
+  useEffect(() => {
+    const timer = setInterval(
+      () => setFrame(f => (f + 1) % s.frames.length),
+      s.interval
+    );
+    return () => clearInterval(timer);
+  }, [name]);
+
+  return <span style={{ fontFamily: 'monospace' }}>{s.frames[frame]} {children}</span>;
+}
+
+// Usage: <Spinner name="helix">Generating response...</Spinner>
 ```
 
-### Browser — inline loading text
+### Browser — status indicator
 
 ```js
 import spinners from 'unicode-animations';
 
 const el = document.getElementById('status');
-const { frames, interval } = spinners.arc;
+const { frames, interval } = spinners.orbit;
 let i = 0;
 
 const spinner = setInterval(() => {
-  el.textContent = `${frames[i++ % frames.length]} Loading...`;
+  el.textContent = `${frames[i++ % frames.length]} Syncing...`;
 }, 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>;
-}
+await sync();
+clearInterval(spinner);
+el.textContent = '✔ Synced';
 ```
 
 ## All spinners
@@ -158,8 +148,8 @@ function Spinner({ name = 'braille', text = 'Loading...' }) {
 | Name | Preview | Interval |
 |------|---------|----------|
 | `braille` | `⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏` | 80ms |
-| `braillewave` | `⠁⠂⠄⡀⢀⠠⠐⠈` → `⠂⠄⡀⢀⠠⠐⠈⠁` | 100ms |
-| `dna` | `⠋⠉⠙⠚⠒⠂⠂⠒⠲⠴⠤⠄` → `⠙⠚⠒⠂⠂⠒⠲⠴⠤⠄⠄⠠` | 80ms |
+| `braillewave` | `⠁⠂⠄⡀` → `⠂⠄⡀⢀` | 100ms |
+| `dna` | `⠋⠉⠙⠚` → `⠉⠙⠚⠒` | 80ms |
 
 ### Grid animations (braille)
 
@@ -181,15 +171,6 @@ function Spinner({ name = 'braille', text = 'Loading...' }) {
 | `fillsweep` | 11 | 100ms |
 | `diagswipe` | 16 | 60ms |
 
-### Non-braille classics
-
-| Name | Preview | Interval |
-|------|---------|----------|
-| `arc` | `◜ ◠ ◝ ◞ ◡ ◟` | 100ms |
-| `halfmoon` | `◐ ◓ ◑ ◒` | 180ms |
-| `line` | `\| / — \` | 100ms |
-| `blocks` | `▁ ▂ ▃ ▄ ▅ ▆ ▇ █ ▇ ▆ ▅ ▄ ▃ ▂` | 100ms |
-
 ## Custom spinners
 
 Create your own braille spinners using the grid utilities:
@@ -228,7 +209,7 @@ interface Spinner {
 | `gridToBraille(grid)` | `(boolean[][]) => string` |
 | `makeGrid(rows, cols)` | `(number, number) => boolean[][]` |
 | `Spinner` | TypeScript interface |
-| `BrailleSpinnerName` | Union type of all 22 spinner names |
+| `BrailleSpinnerName` | Union type of all 18 spinner names |
 
 ### Exports from `'unicode-animations/braille'`
 

package/dist/braille.cjs

@@ -56,6 +56,7 @@ function gridToBraille(grid) {
   return result;
 }
 function makeGrid(rows, cols) {
+  if (rows <= 0 || cols <= 0) return [];
   return Array.from({ length: rows }, () => Array(cols).fill(false));
 }
 function genScan() {
@@ -334,31 +335,31 @@ var spinners = {
   },
   braillewave: {
     frames: [
-      "\u2801\u2802\u2804\u2840\u2880\u2820\u2810\u2808",
-      "\u2808\u2801\u2802\u2804\u2840\u2880\u2820\u2810",
-      "\u2810\u2808\u2801\u2802\u2804\u2840\u2880\u2820",
-      "\u2820\u2810\u2808\u2801\u2802\u2804\u2840\u2880",
-      "\u2880\u2820\u2810\u2808\u2801\u2802\u2804\u2840",
-      "\u2840\u2880\u2820\u2810\u2808\u2801\u2802\u2804",
-      "\u2804\u2840\u2880\u2820\u2810\u2808\u2801\u2802",
-      "\u2802\u2804\u2840\u2880\u2820\u2810\u2808\u2801"
+      "\u2801\u2802\u2804\u2840",
+      "\u2802\u2804\u2840\u2880",
+      "\u2804\u2840\u2880\u2820",
+      "\u2840\u2880\u2820\u2810",
+      "\u2880\u2820\u2810\u2808",
+      "\u2820\u2810\u2808\u2801",
+      "\u2810\u2808\u2801\u2802",
+      "\u2808\u2801\u2802\u2804"
     ],
     interval: 100
   },
   dna: {
     frames: [
-      "\u280B\u2809\u2819\u281A\u2812\u2802\u2802\u2812\u2832\u2834\u2824\u2804",
-      "\u2819\u281A\u2812\u2802\u2802\u2812\u2832\u2834\u2824\u2804\u2804\u2820",
-      "\u2839\u2812\u2802\u2802\u2812\u2832\u2834\u2824\u2804\u2804\u2820\u2820",
-      "\u2838\u2802\u2802\u2812\u2832\u2834\u2824\u2804\u2804\u2820\u2820\u2804",
-      "\u283C\u2802\u2812\u2832\u2834\u2824\u2804\u2804\u2820\u2820\u2804\u2824",
-      "\u2834\u2812\u2832\u2834\u2824\u2804\u2804\u2820\u2820\u2804\u2824\u2834",
-      "\u2826\u2832\u2834\u2824\u2804\u2804\u2820\u2820\u2804\u2824\u2834\u2832",
-      "\u2827\u2834\u2824\u2804\u2804\u2820\u2820\u2804\u2824\u2834\u2832\u2812",
-      "\u2807\u2824\u2804\u2804\u2820\u2820\u2804\u2824\u2834\u2832\u2812\u2802",
-      "\u280F\u2804\u2804\u2820\u2820\u2804\u2824\u2834\u2832\u2812\u2802\u2802",
-      "\u280B\u2804\u2820\u2820\u2804\u2824\u2834\u2832\u2812\u2802\u2802\u2812",
-      "\u2809\u2820\u2820\u2804\u2824\u2834\u2832\u2812\u2802\u2802\u2812\u2832"
+      "\u280B\u2809\u2819\u281A",
+      "\u2809\u2819\u281A\u2812",
+      "\u2819\u281A\u2812\u2802",
+      "\u281A\u2812\u2802\u2802",
+      "\u2812\u2802\u2802\u2812",
+      "\u2802\u2802\u2812\u2832",
+      "\u2802\u2812\u2832\u2834",
+      "\u2812\u2832\u2834\u2824",
+      "\u2832\u2834\u2824\u2804",
+      "\u2834\u2824\u2804\u280B",
+      "\u2824\u2804\u280B\u2809",
+      "\u2804\u280B\u2809\u2819"
     ],
     interval: 80
   },
@@ -377,24 +378,7 @@ var spinners = {
   checkerboard: { frames: genCheckerboard(), interval: 250 },
   helix: { frames: genHelix(), interval: 80 },
   fillsweep: { frames: genFillSweep(), interval: 100 },
-  diagswipe: { frames: genDiagonalSwipe(), interval: 60 },
-  // === Non-braille classics ===
-  arc: {
-    frames: ["\u25DC", "\u25E0", "\u25DD", "\u25DE", "\u25E1", "\u25DF"],
-    interval: 100
-  },
-  halfmoon: {
-    frames: ["\u25D0", "\u25D3", "\u25D1", "\u25D2"],
-    interval: 180
-  },
-  line: {
-    frames: ["|", "/", "\u2014", "\\"],
-    interval: 100
-  },
-  blocks: {
-    frames: ["\u2581", "\u2582", "\u2583", "\u2584", "\u2585", "\u2586", "\u2587", "\u2588", "\u2587", "\u2586", "\u2585", "\u2584", "\u2583", "\u2582"],
-    interval: 100
-  }
+  diagswipe: { frames: genDiagonalSwipe(), interval: 60 }
 };
 var braille_default = spinners;
 // Annotate the CommonJS export names for ESM import in node:

package/dist/braille.d.cts

@@ -9,7 +9,7 @@ interface Spinner {
     readonly frames: readonly string[];
     readonly interval: number;
 }
-type BrailleSpinnerName = 'braille' | 'braillewave' | 'dna' | 'scan' | 'rain' | 'scanline' | 'pulse' | 'snake' | 'sparkle' | 'cascade' | 'columns' | 'orbit' | 'breathe' | 'waverows' | 'checkerboard' | 'helix' | 'fillsweep' | 'diagswipe' | 'arc' | 'halfmoon' | 'line' | 'blocks';
+type BrailleSpinnerName = 'braille' | 'braillewave' | 'dna' | 'scan' | 'rain' | 'scanline' | 'pulse' | 'snake' | 'sparkle' | 'cascade' | 'columns' | 'orbit' | 'breathe' | 'waverows' | 'checkerboard' | 'helix' | 'fillsweep' | 'diagswipe';
 /**
  * Convert a 2D boolean grid into a braille string.
  * grid[row][col] = true means dot is raised.

package/dist/braille.d.ts

@@ -9,7 +9,7 @@ interface Spinner {
     readonly frames: readonly string[];
     readonly interval: number;
 }
-type BrailleSpinnerName = 'braille' | 'braillewave' | 'dna' | 'scan' | 'rain' | 'scanline' | 'pulse' | 'snake' | 'sparkle' | 'cascade' | 'columns' | 'orbit' | 'breathe' | 'waverows' | 'checkerboard' | 'helix' | 'fillsweep' | 'diagswipe' | 'arc' | 'halfmoon' | 'line' | 'blocks';
+type BrailleSpinnerName = 'braille' | 'braillewave' | 'dna' | 'scan' | 'rain' | 'scanline' | 'pulse' | 'snake' | 'sparkle' | 'cascade' | 'columns' | 'orbit' | 'breathe' | 'waverows' | 'checkerboard' | 'helix' | 'fillsweep' | 'diagswipe';
 /**
  * Convert a 2D boolean grid into a braille string.
  * grid[row][col] = true means dot is raised.