ansimax 1.3.1 → 1.3.2

package/dist/index.d.ts

@@ -960,7 +960,82 @@ interface RenderOptions$1 {
     /** Use braille (2×4 sub-char resolution). Overrides halfBlock. */
     braille?: boolean;
 }
+/**
+ * Render a 2D grid of pixels (`{r, g, b, a?}` objects) as terminal output
+ * using half-block characters (`▀`) to fit two vertical pixels per row.
+ * This doubles vertical resolution compared to one-character-per-pixel.
+ *
+ * @param pixels - 2D grid of pixel objects.
+ * @param opts   - Render options (scale, background, etc.).
+ *
+ * @example basic pixel art
+ * ```js
+ * import { renderPixelArt } from 'ansimax';
+ *
+ * const heart = [
+ *   [null, {r:255,g:0,b:0}, null, {r:255,g:0,b:0}, null],
+ *   [{r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}],
+ *   [{r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}],
+ *   [null, {r:255,g:0,b:0}, {r:255,g:0,b:0}, {r:255,g:0,b:0}, null],
+ *   [null, null, {r:255,g:0,b:0}, null, null],
+ * ];
+ *
+ * console.log(renderPixelArt(heart));
+ * ```
+ *
+ * @example with scale (each pixel rendered as multiple chars)
+ * ```js
+ * console.log(renderPixelArt(myPixels, { scale: 2 }));
+ * // Each pixel becomes 2x2 in the output
+ * ```
+ *
+ * @example with background color (transparent pixels show through)
+ * ```js
+ * console.log(renderPixelArt(myPixels, {
+ *   background: { r: 30, g: 30, b: 30 },
+ * }));
+ * ```
+ *
+ * @example combined with a sprite from SPRITES
+ * ```js
+ * import { renderPixelArt, SPRITES } from 'ansimax';
+ *
+ * console.log(renderPixelArt(SPRITES.heart.pixels, { scale: 3 }));
+ * ```
+ */
 declare const renderPixelArt: (pixels: PixelGrid, opts?: RenderOptions$1) => string;
+/**
+ * Built-in sprite library — small pre-defined pixel art ready for use.
+ *
+ * Each entry has a `pixels` property containing a `PixelGrid`.
+ *
+ * Currently available: `heart`, `star`, `arrow`, `check`, `x`, `bell`,
+ * `gear`, `bolt`, `flag`, `crown`.
+ *
+ * @example render a built-in sprite
+ * ```js
+ * import { renderPixelArt, SPRITES } from 'ansimax';
+ *
+ * console.log(renderPixelArt(SPRITES.heart.pixels));
+ * console.log(renderPixelArt(SPRITES.star.pixels, { scale: 2 }));
+ * ```
+ *
+ * @example list all available sprites
+ * ```js
+ * console.log('Available sprites:', Object.keys(SPRITES).join(', '));
+ * ```
+ *
+ * @example compose sprites on a canvas
+ * ```js
+ * import { createCanvas, SPRITES } from 'ansimax';
+ *
+ * const canvas = createCanvas(30, 10);
+ * canvas.drawSprite(2,  2, SPRITES.heart.pixels);
+ * canvas.drawSprite(10, 2, SPRITES.star.pixels);
+ * canvas.drawSprite(18, 2, SPRITES.crown.pixels);
+ * canvas.print();
+ * ```
+ */
 declare const SPRITES: Record<string, {
     pixels: PixelGrid;
 }>;
@@ -985,6 +1060,78 @@ interface GradientRectOptions {
     /** Render in braille mode for 2× horizontal × 4× vertical resolution. */
     braille?: boolean;
 }
+/**
+ * Render a rectangle filled with a multi-color gradient. Supports horizontal,
+ * vertical, diagonal, arbitrary-angle, radial, and conic gradient styles.
+ *
+ * @param opts - Configuration: dimensions, colors, style, dithering.
+ *
+ * @example horizontal gradient (default)
+ * ```js
+ * import { gradientRect } from 'ansimax';
+ *
+ * console.log(gradientRect({
+ *   width: 40, height: 10,
+ *   colors: ['#ff0000', '#0000ff'],
+ * }));
+ * ```
+ *
+ * @example vertical gradient with multiple stops
+ * ```js
+ * console.log(gradientRect({
+ *   width: 30, height: 15,
+ *   colors: ['#ff0000', '#ffff00', '#00ff00', '#0000ff'],
+ *   style: 'vertical',
+ * }));
+ * ```
+ *
+ * @example arbitrary angle (45° = bottom-left to top-right)
+ * ```js
+ * console.log(gradientRect({
+ *   width: 40, height: 20,
+ *   colors: ['#bd93f9', '#ff79c6'],
+ *   style: 'diagonal',
+ *   angle: 45,
+ * }));
+ * ```
+ *
+ * @example radial gradient (center to edge)
+ * ```js
+ * console.log(gradientRect({
+ *   width: 30, height: 15,
+ *   colors: ['#ffffff', '#000000'],
+ *   style: 'radial',
+ * }));
+ * ```
+ *
+ * @example conic (rainbow wheel) — v1.2.0+
+ * ```js
+ * console.log(gradientRect({
+ *   width: 30, height: 15,
+ *   colors: ['#ff0000', '#ffff00', '#00ff00', '#00ffff', '#0000ff', '#ff00ff', '#ff0000'],
+ *   style: 'conic',
+ *   startAngle: 0,
+ * }));
+ * ```
+ *
+ * @example with Bayer dithering for smoother tonal transitions
+ * ```js
+ * console.log(gradientRect({
+ *   width: 60, height: 20,
+ *   colors: ['#000033', '#ffcc00'],
+ *   dither: 'bayer',
+ * }));
+ * ```
+ *
+ * @example braille mode (4× vertical resolution per cell)
+ * ```js
+ * console.log(gradientRect({
+ *   width: 60, height: 30,
+ *   colors: ['#ff0000', '#0000ff'],
+ *   braille: true,
+ * }));
+ * ```
+ */
 declare const gradientRect: (opts?: GradientRectOptions) => string;
 interface CanvasRenderOptions extends RenderOptions$1 {
     /** Render only the dirty region instead of the whole canvas. Default: false. */
@@ -1011,6 +1158,61 @@ interface Canvas {
     /** Deep copy of the current pixel grid. Mutations don't affect the canvas. */
     pixels: PixelGrid;
 }
+/**
+ * Create a mutable in-memory canvas with drawing primitives (line, rect,
+ * circle, sprite). The canvas tracks dirty regions so subsequent renders
+ * can update only changed pixels (useful for animation).
+ *
+ * @param width     - Canvas width in pixels (1 to MAX_DIMENSION).
+ * @param height    - Canvas height in pixels (1 to MAX_DIMENSION).
+ * @param fillColor - Initial fill (`null` for transparent). Default `null`.
+ * @returns A Canvas object with drawing methods.
+ *
+ * @example draw and render a simple scene
+ * ```js
+ * import { createCanvas } from 'ansimax';
+ *
+ * const canvas = createCanvas(40, 20, { r: 20, g: 20, b: 30 });
+ *
+ * canvas.drawRect(5, 5, 30, 10, { r: 100, g: 200, b: 255 }, true);
+ * canvas.drawCircle(20, 10, 4, { r: 255, g: 200, b: 0 }, true);
+ * canvas.drawLine(0, 0, 39, 19, { r: 255, g: 0, b: 100 });
+ *
+ * canvas.print();  // render and write to stdout
+ * ```
+ *
+ * @example animated frame with dirty-region tracking
+ * ```js
+ * const canvas = createCanvas(60, 30);
+ *
+ * for (let frame = 0; frame < 100; frame++) {
+ *   canvas.setPixel(frame % 60, 15, { r: 255, g: 0, b: 0 });
+ *
+ *   // Only re-render changed pixels (much faster than full redraw)
+ *   process.stdout.write(canvas.render({ dirtyOnly: true }));
+ *   await new Promise(r => setTimeout(r, 50));
+ * }
+ * ```
+ *
+ * @example composite sprites
+ * ```js
+ * import { createCanvas, SPRITES } from 'ansimax';
+ *
+ * const canvas = createCanvas(40, 20);
+ * canvas.drawSprite(5, 5, SPRITES.heart.pixels);
+ * canvas.drawSprite(20, 5, SPRITES.star.pixels);
+ * canvas.print();
+ * ```
+ *
+ * @example resize while preserving content
+ * ```js
+ * const canvas = createCanvas(20, 10, { r: 50, g: 50, b: 50 });
+ * canvas.drawCircle(10, 5, 3, { r: 255, g: 0, b: 0 });
+ *
+ * canvas.resize(40, 20);  // existing pixels remain in upper-left
+ * canvas.print();
+ * ```
+ */
 declare const createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
 declare const images: {
     render: (pixels: PixelGrid, opts?: RenderOptions$1) => string;

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>