ansimax 1.3.0 → 1.3.2

package/dist/index.mjs

@@ -1162,13 +1162,13 @@ var animateGradient = (text, stops, opts = {}) => {
     const elapsed = Date.now() - startTime;
     let phase = elapsed / safeDuration2 % 1;
     if (direction === "reverse") phase = 1 - phase;
-    const frame = gradient(text, stops, { preserveAnsi, easing, phase });
+    const frame2 = gradient(text, stops, { preserveAnsi, easing, phase });
     if (onFrame) {
-      onFrame(frame, phase);
+      onFrame(frame2, phase);
     } else {
       try {
         if (process?.stdout?.write) {
-          process.stdout.write("\r" + frame);
+          process.stdout.write("\r" + frame2);
         }
       } catch {
       }
@@ -1458,9 +1458,9 @@ var safeWrite = (data) => {
   } catch {
   }
 };
-var fireFrame = (hooks, frame) => {
+var fireFrame = (hooks, frame2) => {
   try {
-    hooks?.onFrame?.(frame);
+    hooks?.onFrame?.(frame2);
   } catch {
   }
 };
@@ -1492,7 +1492,7 @@ var typewriter = async (text, opts = {}) => {
   registerCrashHandlers();
   hideCursorSafe();
   let aborted = false;
-  let frame = 0;
+  let frame2 = 0;
   try {
     for (const ch of text) {
       if (isAborted(signal)) {
@@ -1500,7 +1500,7 @@ var typewriter = async (text, opts = {}) => {
         break;
       }
       await safeWriteAsync(colorFn ? colorFn(ch) : ch);
-      fireFrame(hooks, frame++);
+      fireFrame(hooks, frame2++);
       await sleep(ch === " " ? speed * 0.3 : speed, { signal });
     }
   } finally {
@@ -1671,7 +1671,7 @@ var pulse = async (text, opts = {}) => {
   registerCrashHandlers();
   hideCursorSafe();
   let aborted = false;
-  let frame = 0;
+  let frame2 = 0;
   try {
     for (let t = 0; t < cycles; t++) {
       if (isAborted(signal)) {
@@ -1681,7 +1681,7 @@ var pulse = async (text, opts = {}) => {
       await safeWriteAsync(
         cursor.save() + fgRgb(c1.r, c1.g, c1.b) + text + reset() + cursor.restore()
       );
-      fireFrame(hooks, frame++);
+      fireFrame(hooks, frame2++);
       await sleep(halfInterval, { signal });
       if (isAborted(signal)) {
         aborted = true;
@@ -1690,7 +1690,7 @@ var pulse = async (text, opts = {}) => {
       await safeWriteAsync(
         cursor.save() + fgRgb(c2.r, c2.g, c2.b) + text + reset() + cursor.restore()
       );
-      fireFrame(hooks, frame++);
+      fireFrame(hooks, frame2++);
       await sleep(halfInterval, { signal });
     }
     if (!aborted) {
@@ -2835,7 +2835,7 @@ var spin = (text = "Loading", opts = {}) => {
       }
     };
   }
-  let frame = 0;
+  let frame2 = 0;
   let stopped = false;
   let timer = null;
   const animInterval = Math.max(FRAME_MS, safeInterval);
@@ -2844,8 +2844,8 @@ var spin = (text = "Loading", opts = {}) => {
   const render = () => {
     if (stopped) return;
     const elapsed = Date.now() - startTime;
-    frame = Math.floor(elapsed / animInterval) % frames2.length;
-    const f = frames2[frame] ?? "";
+    frame2 = Math.floor(elapsed / animInterval) % frames2.length;
+    const f = frames2[frame2] ?? "";
     const colored = applyColor(f, hex);
     const line = padToTerminalWidth(`${safePrefix}${colored} ${safeText}${safeSuffix}`);
     const buf = createOutputBuffer().push("\r").push(screen.clearLine()).push(line).toString();
@@ -3058,7 +3058,7 @@ var custom = (frames2, text = "", opts = {}) => {
   }
   registerCrashHandlers2();
   acquireCursor();
-  let frame = 0;
+  let frame2 = 0;
   let stopped = false;
   let timer = null;
   const safeInterval = Math.max(FRAME_MS, interval);
@@ -3066,8 +3066,8 @@ var custom = (frames2, text = "", opts = {}) => {
   const render = () => {
     if (stopped) return;
     const elapsed = Date.now() - startTime;
-    frame = Math.floor(elapsed / safeInterval) % frames2.length;
-    const f = frames2[frame] ?? "";
+    frame2 = Math.floor(elapsed / safeInterval) % frames2.length;
+    const f = frames2[frame2] ?? "";
     write("\r" + screen.clearLine() + applyColor(f, hex) + " " + text);
   };
   render();
@@ -3175,7 +3175,7 @@ var multi = (opts = {}) => {
   registerCrashHandlers2();
   let nextId = 0;
   const items = /* @__PURE__ */ new Map();
-  let frame = 0;
+  let frame2 = 0;
   let timer = null;
   let lastLineCount = 0;
   const render = () => {
@@ -3189,13 +3189,13 @@ var multi = (opts = {}) => {
       let glyph;
       if (item.state === "success") glyph = applyColor("\u2713", "#00ff88");
       else if (item.state === "fail") glyph = applyColor("\u2717", "#ff6b6b");
-      else glyph = applyColor(frames2[frame % frames2.length] ?? "", item.color ?? null);
+      else glyph = applyColor(frames2[frame2 % frames2.length] ?? "", item.color ?? null);
       const text = item.finalText ?? item.text;
       buf.pushln(padToTerminalWidth(`${glyph} ${text}`));
     }
     write(buf.toString());
     lastLineCount = itemsArr.length;
-    frame++;
+    frame2++;
   };
   const start = () => {
     if (timer) return;
@@ -3356,9 +3356,9 @@ var registerCrashHandlers3 = () => {
   if (isTestEnv3()) return;
   installCrashHandlersImpl3();
 };
-var lineCount = (frame) => {
-  if (typeof frame !== "string" || frame.length === 0) return 0;
-  const normalized = frame.replace(/\r\n/g, "\n").replace(/\r/g, "");
+var lineCount = (frame2) => {
+  if (typeof frame2 !== "string" || frame2.length === 0) return 0;
+  const normalized = frame2.replace(/\r\n/g, "\n").replace(/\r/g, "");
   return normalized.split("\n").length;
 };
 var clearLines = (n) => {
@@ -3369,7 +3369,7 @@ var clearLines = (n) => {
   }
 };
 var isColorless2 = () => supportsColor() === "none";
-var defaultOnFrame = (frame) => isColorless2() ? stripAnsi(frame) : frame;
+var defaultOnFrame = (frame2) => isColorless2() ? stripAnsi(frame2) : frame2;
 var play = (frames2, opts = {}) => {
   if (!Array.isArray(frames2)) {
     const resolved = Promise.resolve();
@@ -3430,13 +3430,13 @@ var play = (frames2, opts = {}) => {
   const done = new Promise((r) => {
     resolveDone = r;
   });
-  const renderFrame = (frame, idx) => {
+  const renderFrame = (frame2, idx) => {
     if (lastLines > 0) clearLines(lastLines);
     let rendered;
     try {
-      rendered = userOnFrame(frame, idx);
+      rendered = userOnFrame(frame2, idx);
     } catch {
-      rendered = frame;
+      rendered = frame2;
     }
     const safe = ensureString4(rendered);
     try {
@@ -3565,13 +3565,13 @@ var live = (opts = {}) => {
   let abortHandler = null;
   const render = () => {
     if (lastLines > 0) clearLines(lastLines);
-    const frame = isColorless2() ? stripAnsi(currentFrame) : currentFrame;
+    const frame2 = isColorless2() ? stripAnsi(currentFrame) : currentFrame;
     try {
-      write(frame);
+      write(frame2);
     } catch {
     }
-    lastLines = lineCount(frame);
-    if (!frame.endsWith("\n")) writeln();
+    lastLines = lineCount(frame2);
+    if (!frame2.endsWith("\n")) writeln();
   };
   const start = () => {
     if (running) return;
@@ -5515,9 +5515,82 @@ var hsplit = (blocks, opts = {}) => {
   }
   return parts.join("\n");
 };
+var center2 = (block, opts) => {
+  if (!opts || typeof opts !== "object") return block;
+  const width = Math.max(0, Math.floor(opts.width ?? 0));
+  if (width === 0) return block;
+  const { lines, maxWidth } = _splitBlock(block);
+  const hCentered = lines.map((line) => {
+    const w = visibleLen(line);
+    const space = Math.max(0, width - w);
+    if (space === 0) return line.slice(0, width);
+    const left = Math.floor(space / 2);
+    const right = space - left;
+    return " ".repeat(left) + line + " ".repeat(right);
+  });
+  if (opts.height != null) {
+    const targetH = Math.max(1, Math.floor(opts.height));
+    return _alignVertical(hCentered, targetH, width, opts.align ?? "center").join("\n");
+  }
+  void maxWidth;
+  return hCentered.join("\n");
+};
+var frame = (block, opts = {}) => {
+  const {
+    padding = 0,
+    paddingY,
+    paddingX,
+    topChar = "\u2500",
+    bottomChar,
+    title
+  } = opts;
+  const safePadY = Math.max(0, Math.floor(paddingY ?? padding));
+  const safePadX = Math.max(0, Math.floor(paddingX ?? padding));
+  const safeTop = typeof topChar === "string" && topChar.length > 0 ? topChar.charAt(0) : "\u2500";
+  const safeBot = typeof bottomChar === "string" && bottomChar.length > 0 ? bottomChar.charAt(0) : safeTop;
+  const { lines, maxWidth } = _splitBlock(block);
+  const contentInnerW = maxWidth + 2 * safePadX;
+  let innerW = contentInnerW;
+  let titleStr = "";
+  let titleW = 0;
+  if (typeof title === "string" && title.length > 0) {
+    titleStr = ` ${title} `;
+    titleW = visibleLen(titleStr);
+    const titleNeededW = titleW + 2;
+    if (titleNeededW > innerW) {
+      innerW = titleNeededW;
+    }
+  }
+  let topLine;
+  if (titleStr.length > 0 && titleW < innerW) {
+    const before = Math.floor((innerW - titleW) / 2);
+    const after = innerW - titleW - before;
+    topLine = safeTop.repeat(before) + titleStr + safeTop.repeat(after);
+  } else {
+    topLine = safeTop.repeat(innerW);
+  }
+  const bottomLine = safeBot.repeat(innerW);
+  const padX = " ".repeat(safePadX);
+  const padded = lines.map((line) => {
+    const w = visibleLen(line);
+    const tail = " ".repeat(Math.max(0, innerW - safePadX - w - safePadX));
+    return padX + line + tail + padX;
+  });
+  const blank = " ".repeat(innerW);
+  const out = [];
+  out.push(topLine);
+  for (let i = 0; i < safePadY; i++) out.push(blank);
+  out.push(...padded);
+  for (let i = 0; i < safePadY; i++) out.push(blank);
+  out.push(bottomLine);
+  return out.join("\n");
+};
 var panels = {
   vsplit,
-  hsplit
+  hsplit,
+  // v1.3.1
+  center: center2,
+  frame
 };
 
 // src/json/index.ts
@@ -5572,7 +5645,16 @@ var _formatPrimitive = (value, opts) => {
   return _c(String(value), COLORS.comment, useColor);
 };
 var _renderValue = (value, depth, config) => {
-  const { indent, maxDepth, maxItems, maxStringLength, useColor, seen } = config;
+  const {
+    indent,
+    maxDepth,
+    maxItems,
+    maxStringLength,
+    useColor,
+    seen,
+    sortKeys,
+    inlineArrayMaxLength
+  } = config;
   if (value === null || typeof value !== "object") {
     return _formatPrimitive(value, { useColor, maxStringLength });
   }
@@ -5592,6 +5674,25 @@ var _renderValue = (value, depth, config) => {
     if (value.length === 0) {
       return _c("[]", COLORS.bracket, useColor);
     }
+    if (inlineArrayMaxLength > 0) {
+      const allPrimitive = value.every((v) => v === null || typeof v !== "object");
+      if (allPrimitive) {
+        const displayCount2 = Math.min(value.length, maxItems);
+        const inlineItems = [];
+        for (let i = 0; i < displayCount2; i++) {
+          inlineItems.push(_formatPrimitive(value[i], { useColor, maxStringLength }));
+        }
+        if (value.length > maxItems) {
+          const remaining = value.length - maxItems;
+          inlineItems.push(_c(`... (${remaining} more)`, COLORS.comment, useColor));
+        }
+        const candidate = _c("[", COLORS.bracket, useColor) + inlineItems.join(", ") + _c("]", COLORS.bracket, useColor);
+        const visibleLen2 = candidate.replace(/\x1b\[[0-9;]*m/g, "").length;
+        if (visibleLen2 <= inlineArrayMaxLength) {
+          return candidate;
+        }
+      }
+    }
     const items = [];
     const displayCount = Math.min(value.length, maxItems);
     for (let i = 0; i < displayCount; i++) {
@@ -5604,10 +5705,13 @@ var _renderValue = (value, depth, config) => {
     }
     return _c("[", COLORS.bracket, useColor) + "\n" + items.join(",\n") + "\n" + closePad + _c("]", COLORS.bracket, useColor);
   }
-  const keys = Object.keys(value);
+  let keys = Object.keys(value);
   if (keys.length === 0) {
     return _c("{}", COLORS.bracket, useColor);
   }
+  if (sortKeys) {
+    keys = [...keys].sort((a, b) => a.localeCompare(b));
+  }
   const entries = [];
   for (const key of keys) {
     const keyStr = JSON.stringify(key);
@@ -5627,12 +5731,16 @@ var pretty = (value, opts = {}) => {
     colors = true,
     maxDepth = Infinity,
     maxItems = Infinity,
-    maxStringLength = Infinity
+    maxStringLength = Infinity,
+    // v1.3.1
+    sortKeys = false,
+    inlineArrayMaxLength = 60
   } = opts;
   const safeIndent = Math.max(0, Math.floor(Number(indent) || 0));
   const safeMaxDepth = Number.isFinite(maxDepth) ? Math.max(0, Math.floor(maxDepth)) : Infinity;
   const safeMaxItems = Number.isFinite(maxItems) ? Math.max(0, Math.floor(maxItems)) : Infinity;
   const safeMaxStrLen = Number.isFinite(maxStringLength) ? Math.max(0, Math.floor(maxStringLength)) : Infinity;
+  const safeInlineMax = Number.isFinite(inlineArrayMaxLength) ? Math.max(0, Math.floor(inlineArrayMaxLength)) : 60;
   const useColor = colors && !isNoColor();
   return _renderValue(value, 0, {
     indent: safeIndent,
@@ -5640,7 +5748,9 @@ var pretty = (value, opts = {}) => {
     maxItems: safeMaxItems,
     maxStringLength: safeMaxStrLen,
     useColor,
-    seen: /* @__PURE__ */ new WeakSet()
+    seen: /* @__PURE__ */ new WeakSet(),
+    sortKeys: Boolean(sortKeys),
+    inlineArrayMaxLength: safeInlineMax
   });
 };
 var json = {
@@ -5890,6 +6000,7 @@ export {
   canAnimate,
   cancelTerminalFrame,
   center,
+  center2 as centerBlock,
   chain,
   charWidth,
   clamp,
@@ -5920,6 +6031,7 @@ export {
   findInTree,
   flipHorizontal,
   flipVertical,
+  frame,
   frames,
   fromImage,
   getConfig,

package/docs/README.md

@@ -0,0 +1,110 @@
+<div align="center">
+
+# 📚 ansimax — Documentation
+
+Detailed examples covering every module in **ansimax**, with copy-paste runnable code in three formats.
+
+</div>
+
+---
+
+## 📖 Where to start
+
+Pick the document that matches your project setup:
+
+| File | Format | Use when… |
+|---|---|---|
+| [`examples-ts.md`](./examples-ts.md) | **TypeScript** (`.ts`) | Your project uses TypeScript (with `ts-node`, `tsx`, or compiled output) |
+| [`examples-mjs.md`](./examples-mjs.md) | **JavaScript ESM** (`.mjs` / `"type":"module"`) | Modern JavaScript with `import`/`export` |
+| [`examples-cjs.md`](./examples-cjs.md) | **JavaScript CommonJS** (`.cjs` / classic Node) | Legacy or simple Node scripts with `require()` |
+| [`showcase.md`](./showcase.md) | **Complete app** | A single end-to-end JavaScript app combining all modules |
+
+Each `examples-*.md` file covers **all 11 modules** with **3 runnable examples each** (33 examples per file).
+
+---
+
+## 🧩 Modules covered in every file
+
+Each examples file is organized in this order:
+
+1. **`color`** — basic colors, ANSI styling, gradients
+2. **`gradient`** — multi-stop, animated, eased, conic gradients
+3. **`ascii`** — boxes, banners (figlet), image-to-ASCII
+4. **`animations`** — typewriter, fadeIn, fadeOut
+5. **`loaders`** — spinners, tasks, progress bars
+6. **`components`** — table, badge, status, timeline
+7. **`themes`** — built-in themes, custom themes, registry
+8. **`trees`** — hierarchical rendering, max-depth, cycles
+9. **`frames`** — frame-by-frame animation, morphing
+10. **`images`** — pixel art, canvas, gradient rectangles
+11. **`panels`** + **`json`** — split layouts + pretty-printing (v1.3.0+)
+
+---
+
+## 💡 Running the examples
+
+### TypeScript (`examples-ts.md`)
+
+```bash
+# Quickest: tsx (no compile step)
+npx tsx my-example.ts
+
+# Or with ts-node
+npx ts-node my-example.ts
+
+# Or compile then run
+npx tsc my-example.ts && node my-example.js
+```
+
+### JavaScript ESM (`examples-mjs.md`)
+
+Either:
+- Save the file with `.mjs` extension, OR
+- Set `"type": "module"` in your `package.json` and use `.js`
+
+```bash
+node my-example.mjs
+```
+
+### JavaScript CommonJS (`examples-cjs.md`)
+
+```bash
+node my-example.cjs
+```
+
+### Showcase (`showcase.md`)
+
+A complete demo app. Save as `.mjs`, run with `node`. Demonstrates how multiple modules compose in a real CLI.
+
+---
+
+## ⚙️ Project setup
+
+For any of these, your `package.json` needs:
+
+```json
+{
+  "dependencies": {
+    "ansimax": "^1.3.2"
+  }
+}
+```
+
+Then `npm install` and pick an example.
+
+---
+
+## 🔗 More resources
+
+- [Main README](../README.md) — overview, badges, comparison table, roadmap
+- [CHANGELOG](../CHANGELOG.md) — version history
+- [npm package](https://www.npmjs.com/package/ansimax)
+- [GitHub](https://github.com/Brashkie/ansimax)
+
+---
+
+<div align="center">
+
+If any example doesn't work, [open an issue](https://github.com/Brashkie/ansimax/issues) — we'll fix it.
+
+</div>