ansimax 1.3.1 → 1.3.3

package/dist/index.mjs

@@ -2270,23 +2270,61 @@ var banner = (text, opts = {}) => {
 };
 var box = (text, opts = {}) => {
   const safe = ensureString2(text, "box(text)");
-  const { padding = 1, borderStyle = "rounded", width = null } = opts;
+  const {
+    padding = 1,
+    borderStyle = "rounded",
+    width = null,
+    title = null,
+    // v1.3.3
+    titleAlign = "center"
+    // v1.3.3
+  } = opts;
   const padNum = typeof padding === "number" && Number.isFinite(padding) ? padding : 1;
   const safePadding = Math.max(0, Math.floor(padNum));
   const b = BOX_STYLES[borderStyle] ?? BOX_STYLES.rounded;
   const lines = safe.split("\n");
   const inner = width != null ? lines.map((l) => padEnd(truncateAnsi(l, width, ""), width)) : lines;
-  const w = inner.length > 0 ? Math.max(0, ...inner.map((l) => visibleLen(l))) : 0;
+  const contentW = inner.length > 0 ? Math.max(0, ...inner.map((l) => visibleLen(l))) : 0;
+  let w = contentW;
+  let titleStr = "";
+  let titleW = 0;
+  if (typeof title === "string" && title.length > 0) {
+    titleStr = ` ${title} `;
+    titleW = visibleLen(titleStr);
+    const titleNeeded = titleW + 2;
+    const innerNeeded = w + safePadding * 2;
+    if (titleNeeded > innerNeeded) {
+      w = titleNeeded - safePadding * 2;
+    }
+  }
+  const innerW = w + safePadding * 2;
   const pad = " ".repeat(safePadding);
-  const top = b.tl + b.h.repeat(w + safePadding * 2) + b.tr;
-  const bottom = b.bl + b.h.repeat(w + safePadding * 2) + b.br;
-  const emptyRow = b.v + " ".repeat(w + safePadding * 2) + b.v;
+  let top;
+  if (titleStr.length > 0 && titleW < innerW) {
+    let before;
+    let after;
+    if (titleAlign === "left") {
+      before = 1;
+      after = innerW - titleW - before;
+    } else if (titleAlign === "right") {
+      after = 1;
+      before = innerW - titleW - after;
+    } else {
+      before = Math.floor((innerW - titleW) / 2);
+      after = innerW - titleW - before;
+    }
+    top = b.tl + b.h.repeat(before) + titleStr + b.h.repeat(after) + b.tr;
+  } else {
+    top = b.tl + b.h.repeat(innerW) + b.tr;
+  }
+  const bottom = b.bl + b.h.repeat(innerW) + b.br;
+  const emptyRow = b.v + " ".repeat(innerW) + b.v;
   const rows = inner.map((l) => b.v + pad + padEnd(l, w) + pad + b.v);
   const vPad = Array(safePadding).fill(emptyRow);
   return [top, ...vPad, ...rows, ...vPad, bottom].join("\n");
 };
 var divider = (opts = {}) => {
-  const { char, width = null, label = null, style = "single" } = opts;
+  const { char, width = null, label = null, style = "single", align = "center" } = opts;
   const { cols } = termSize();
   const w = Math.max(0, width ?? cols);
   const b = BOX_STYLES[style] ?? BOX_STYLES.single;
@@ -2295,8 +2333,18 @@ var divider = (opts = {}) => {
   if (label) {
     const labelLen = visibleLen(label);
     if (labelLen >= w - 2) return label;
-    const side = Math.max(0, Math.floor((w - labelLen - 2) / 2));
-    const trailLen = Math.max(0, w - side - labelLen - 2);
+    let side;
+    let trailLen;
+    if (align === "left") {
+      side = 1;
+      trailLen = Math.max(0, w - labelLen - side - 2);
+    } else if (align === "right") {
+      trailLen = 1;
+      side = Math.max(0, w - labelLen - trailLen - 2);
+    } else {
+      side = Math.max(0, Math.floor((w - labelLen - 2) / 2));
+      trailLen = Math.max(0, w - side - labelLen - 2);
+    }
     return fill.repeat(side) + " " + label + " " + fill.repeat(trailLen);
   }
   return fill.repeat(w);
@@ -4949,16 +4997,16 @@ var ensurePixelGrid = (pixels) => {
   return pixels.map((row) => Array.isArray(row) ? row : []);
 };
 var renderPixelArt = (pixels, opts = {}) => {
-  const grid = ensurePixelGrid(pixels);
-  if (!grid || grid.length === 0) return "";
+  const grid2 = ensurePixelGrid(pixels);
+  if (!grid2 || grid2.length === 0) return "";
   const { scale = 1, halfBlock = true, braille = false } = opts;
   const safeScale = clampInt(scale, 1, 100, 1);
-  if (braille) return _renderBraille(grid);
+  if (braille) return _renderBraille(grid2);
   const lines = [];
   if (halfBlock) {
-    for (let row = 0; row < grid.length; row += 2) {
-      const topRow = grid[row] ?? [];
-      const botRow = grid[row + 1] ?? [];
+    for (let row = 0; row < grid2.length; row += 2) {
+      const topRow = grid2[row] ?? [];
+      const botRow = grid2[row + 1] ?? [];
       const colCount = Math.max(topRow.length, botRow.length);
       let line = "";
       let curFg = -1;
@@ -5015,7 +5063,7 @@ var renderPixelArt = (pixels, opts = {}) => {
       lines.push(line);
     }
   } else {
-    for (const row of grid) {
+    for (const row of grid2) {
       let line = "";
       let curFg = -1;
       for (const pixel of row) {
@@ -5130,24 +5178,24 @@ var SPRITES = {
   ] }
 };
 var flipHorizontal = (pixels) => {
-  const grid = ensurePixelGrid(pixels);
-  if (!grid) return [];
-  return grid.map((row) => [...row].reverse());
+  const grid2 = ensurePixelGrid(pixels);
+  if (!grid2) return [];
+  return grid2.map((row) => [...row].reverse());
 };
 var flipVertical = (pixels) => {
-  const grid = ensurePixelGrid(pixels);
-  if (!grid) return [];
-  return [...grid].reverse();
+  const grid2 = ensurePixelGrid(pixels);
+  if (!grid2) return [];
+  return [...grid2].reverse();
 };
 var rotate90 = (pixels) => {
-  const grid = ensurePixelGrid(pixels);
-  if (!grid || grid.length === 0) return [];
-  const rows = grid.length;
-  const cols = Math.max(0, ...grid.map((r) => r.length));
+  const grid2 = ensurePixelGrid(pixels);
+  if (!grid2 || grid2.length === 0) return [];
+  const rows = grid2.length;
+  const cols = Math.max(0, ...grid2.map((r) => r.length));
   if (cols === 0) return [];
   return Array.from(
     { length: cols },
-    (_, c) => Array.from({ length: rows }, (__, r) => grid[rows - 1 - r]?.[c] ?? null)
+    (_, c) => Array.from({ length: rows }, (__, r) => grid2[rows - 1 - r]?.[c] ?? null)
   );
 };
 var BAYER_4x4 = [
@@ -5542,7 +5590,9 @@ var frame = (block, opts = {}) => {
     paddingX,
     topChar = "\u2500",
     bottomChar,
-    title
+    title,
+    titleAlign = "center"
+    // v1.3.3
   } = opts;
   const safePadY = Math.max(0, Math.floor(paddingY ?? padding));
   const safePadX = Math.max(0, Math.floor(paddingX ?? padding));
@@ -5563,8 +5613,18 @@ var frame = (block, opts = {}) => {
   }
   let topLine;
   if (titleStr.length > 0 && titleW < innerW) {
-    const before = Math.floor((innerW - titleW) / 2);
-    const after = innerW - titleW - before;
+    let before;
+    let after;
+    if (titleAlign === "left") {
+      before = 1;
+      after = innerW - titleW - before;
+    } else if (titleAlign === "right") {
+      after = 1;
+      before = innerW - titleW - after;
+    } else {
+      before = Math.floor((innerW - titleW) / 2);
+      after = innerW - titleW - before;
+    }
     topLine = safeTop.repeat(before) + titleStr + safeTop.repeat(after);
   } else {
     topLine = safeTop.repeat(innerW);
@@ -5585,12 +5645,54 @@ var frame = (block, opts = {}) => {
   out.push(bottomLine);
   return out.join("\n");
 };
+var grid = (blocks, opts) => {
+  if (!Array.isArray(blocks) || blocks.length === 0) return "";
+  if (!opts || typeof opts !== "object") return "";
+  const columns2 = Math.max(1, Math.floor(opts.columns ?? 1));
+  const gapX = Math.max(0, Math.floor(opts.gapX ?? 1));
+  const gapY = Math.max(0, Math.floor(opts.gapY ?? 0));
+  const alignX = opts.alignX ?? "start";
+  const alignY = opts.alignY ?? "start";
+  const cellW = opts.cellWidth != null ? Math.max(0, Math.floor(opts.cellWidth)) : null;
+  const rows = [];
+  for (let i = 0; i < blocks.length; i += columns2) {
+    rows.push(blocks.slice(i, i + columns2));
+  }
+  let widths = null;
+  if (cellW != null) {
+    widths = Array(columns2).fill(cellW);
+  } else {
+    widths = Array(columns2).fill(0);
+    for (const row of rows) {
+      for (let c = 0; c < row.length; c++) {
+        const { maxWidth } = _splitBlock(row[c]);
+        if (maxWidth > widths[c]) {
+          widths[c] = maxWidth;
+        }
+      }
+    }
+  }
+  const renderedRows = rows.map((row) => {
+    const padded = [];
+    for (let c = 0; c < columns2; c++) {
+      padded.push(row[c] ?? "");
+    }
+    return vsplit(padded, {
+      gap: gapX,
+      align: alignY,
+      widths
+    });
+  });
+  return hsplit(renderedRows, { gap: gapY, align: alignX });
+};
 var panels = {
   vsplit,
   hsplit,
   // v1.3.1
   center: center2,
-  frame
+  frame,
+  // v1.3.3
+  grid
 };
 
 // src/json/index.ts
@@ -5610,11 +5712,12 @@ var _truncString = (s, maxLength) => {
   return s.slice(0, maxLength - 3) + "...";
 };
 var _formatPrimitive = (value, opts) => {
-  const { useColor, maxStringLength } = opts;
+  const { useColor, maxStringLength, mode } = opts;
   if (value === null) {
     return _c("null", COLORS.null, useColor);
   }
   if (value === void 0) {
+    if (mode === "json") return _c("null", COLORS.null, useColor);
     return _c("undefined", COLORS.null, useColor);
   }
   if (typeof value === "string") {
@@ -5623,8 +5726,12 @@ var _formatPrimitive = (value, opts) => {
     return _c(quoted, COLORS.string, useColor);
   }
   if (typeof value === "number") {
-    if (Number.isNaN(value)) return _c("NaN", COLORS.number, useColor);
+    if (Number.isNaN(value)) {
+      if (mode === "json") return _c("null", COLORS.null, useColor);
+      return _c("NaN", COLORS.number, useColor);
+    }
     if (!Number.isFinite(value)) {
+      if (mode === "json") return _c("null", COLORS.null, useColor);
       return _c(value > 0 ? "Infinity" : "-Infinity", COLORS.number, useColor);
     }
     return _c(String(value), COLORS.number, useColor);
@@ -5633,16 +5740,23 @@ var _formatPrimitive = (value, opts) => {
     return _c(String(value), COLORS.boolean, useColor);
   }
   if (typeof value === "bigint") {
+    if (mode === "json") {
+      const big2 = value;
+      const asNum = Number(big2);
+      if (Number.isSafeInteger(asNum) && BigInt(asNum) === big2) {
+        return _c(String(asNum), COLORS.number, useColor);
+      }
+      return _c(JSON.stringify(String(big2)), COLORS.string, useColor);
+    }
     return _c(`${value}n`, COLORS.number, useColor);
   }
   if (typeof value === "function") {
+    if (mode === "json") return _c("null", COLORS.null, useColor);
     const name = value.name || "anonymous";
     return _c(`[Function: ${name}]`, COLORS.comment, useColor);
   }
-  if (typeof value === "symbol") {
-    return _c(value.toString(), COLORS.comment, useColor);
-  }
-  return _c(String(value), COLORS.comment, useColor);
+  if (mode === "json") return _c("null", COLORS.null, useColor);
+  return _c(value.toString(), COLORS.comment, useColor);
 };
 var _renderValue = (value, depth, config) => {
   const {
@@ -5653,15 +5767,56 @@ var _renderValue = (value, depth, config) => {
     useColor,
     seen,
     sortKeys,
-    inlineArrayMaxLength
+    inlineArrayMaxLength,
+    mode
   } = config;
   if (value === null || typeof value !== "object") {
-    return _formatPrimitive(value, { useColor, maxStringLength });
+    return _formatPrimitive(value, { useColor, maxStringLength, mode });
   }
   if (seen.has(value)) {
+    if (mode === "json") {
+      throw new TypeError("Cannot serialize circular reference to JSON");
+    }
     return _c("[Circular]", COLORS.comment, useColor);
   }
   seen.add(value);
+  if (value instanceof Date) {
+    const iso = value.toISOString();
+    if (mode === "json") {
+      return _c(JSON.stringify(iso), COLORS.string, useColor);
+    }
+    return _c(`Date(${iso})`, COLORS.comment, useColor);
+  }
+  if (value instanceof Map) {
+    if (mode === "json") {
+      const obj = {};
+      for (const [k, v] of value) {
+        if (typeof k === "string") obj[k] = v;
+        else obj[String(k)] = v;
+      }
+      return _renderValue(obj, depth, config);
+    }
+    const entries2 = Array.from(value);
+    const sizeLabel = _c(`Map(${entries2.length})`, COLORS.comment, useColor);
+    if (entries2.length === 0) {
+      return `${sizeLabel} ${_c("{}", COLORS.bracket, useColor)}`;
+    }
+    if (depth >= maxDepth - 1 && depth > 0) {
+      return `${sizeLabel} ${_c("{...}", COLORS.bracket, useColor)}`;
+    }
+    return `${sizeLabel} ${_renderValue(entries2, depth, config)}`;
+  }
+  if (value instanceof Set) {
+    if (mode === "json") {
+      return _renderValue(Array.from(value), depth, config);
+    }
+    const arr = Array.from(value);
+    const sizeLabel = _c(`Set(${arr.length})`, COLORS.comment, useColor);
+    if (arr.length === 0) {
+      return `${sizeLabel} ${_c("[]", COLORS.bracket, useColor)}`;
+    }
+    return `${sizeLabel} ${_renderValue(arr, depth, config)}`;
+  }
   if (depth >= maxDepth) {
     if (Array.isArray(value)) {
       return _c("[", COLORS.bracket, useColor) + _c("...", COLORS.comment, useColor) + _c("]", COLORS.bracket, useColor);
@@ -5680,7 +5835,7 @@ var _renderValue = (value, depth, config) => {
         const displayCount2 = Math.min(value.length, maxItems);
         const inlineItems = [];
         for (let i = 0; i < displayCount2; i++) {
-          inlineItems.push(_formatPrimitive(value[i], { useColor, maxStringLength }));
+          inlineItems.push(_formatPrimitive(value[i], { useColor, maxStringLength, mode }));
         }
         if (value.length > maxItems) {
           const remaining = value.length - maxItems;
@@ -5706,6 +5861,12 @@ var _renderValue = (value, depth, config) => {
     return _c("[", COLORS.bracket, useColor) + "\n" + items.join(",\n") + "\n" + closePad + _c("]", COLORS.bracket, useColor);
   }
   let keys = Object.keys(value);
+  if (mode === "json") {
+    keys = keys.filter((k) => {
+      const v = value[k];
+      return typeof v !== "function" && typeof v !== "symbol" && v !== void 0;
+    });
+  }
   if (keys.length === 0) {
     return _c("{}", COLORS.bracket, useColor);
   }
@@ -5734,14 +5895,17 @@ var pretty = (value, opts = {}) => {
     maxStringLength = Infinity,
     // v1.3.1
     sortKeys = false,
-    inlineArrayMaxLength = 60
+    inlineArrayMaxLength = 60,
+    // v1.3.3
+    mode = "display"
   } = 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();
+  const safeMode = mode === "json" ? "json" : "display";
+  const useColor = safeMode === "json" ? false : colors && !isNoColor();
   return _renderValue(value, 0, {
     indent: safeIndent,
     maxDepth: safeMaxDepth,
@@ -5750,7 +5914,8 @@ var pretty = (value, opts = {}) => {
     useColor,
     seen: /* @__PURE__ */ new WeakSet(),
     sortKeys: Boolean(sortKeys),
-    inlineArrayMaxLength: safeInlineMax
+    inlineArrayMaxLength: safeInlineMax,
+    mode: safeMode
   });
 };
 var json = {
@@ -6044,6 +6209,7 @@ export {
   gradientColor,
   gradientRect,
   graphemes,
+  grid,
   hasFont,
   hexToRgb,
   hideCursor,

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>