chartforge 0.0.3 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anand Pilania
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -64,6 +64,18 @@
   - [Build Reference](#build-reference)
     - [Build outputs](#build-outputs)
   - [License](#license)
+  - [CLI Usage (`npx chartforge`)](#cli-usage-npx-chartforge)
+    - [Quick examples](#quick-examples)
+    - [Input sources](#input-sources)
+    - [Supported input formats](#supported-input-formats)
+    - [Output formats](#output-formats)
+    - [HTTP / API fetching](#http--api-fetching)
+    - [Live polling (`serve` command)](#live-polling-serve-command)
+    - [File watching (`watch` command)](#file-watching-watch-command)
+    - [All options](#all-options)
+    - [PNG export prerequisites](#png-export-prerequisites)
+    - [HttpAdapter (browser / library)](#httpadapter-browser--library)
+    - [CLI architecture](#cli-architecture)
 
 ---
 
@@ -1337,3 +1349,263 @@ npm run preview
 ## License
 
 MIT © Anand Pilania
+
+---
+
+## CLI Usage (`npx chartforge`)
+
+ChartForge ships a fully-featured CLI. No installation required — just `npx`.
+
+```bash
+npx chartforge [command] [options]
+```
+
+### Quick examples
+
+```bash
+# From a JSON file → HTML page (opens in browser)
+npx chartforge data.json --open
+
+# CSV file → line chart as SVG
+npx chartforge sales.csv -t line --out svg -o chart.svg
+
+# Inline data → terminal bar chart
+npx chartforge --data '[10,25,18,42,35]' -t bar --out terminal
+
+# Pipe from stdin
+echo '[100,120,115,134]' | npx chartforge - --out terminal -t line
+
+# From HTTP URL → HTML export
+npx chartforge --url https://api.example.com/data -o report.html --open
+
+# Live terminal dashboard — polls every 3s
+npx chartforge serve --url https://api.example.com/metrics --interval 3 --out terminal
+
+# Watch a file, re-render on change
+npx chartforge watch --input data.json --out html --open
+```
+
+### Input sources
+
+| Source      | Flag                     | Example                              |
+| ----------- | ------------------------ | ------------------------------------ |
+| File        | `--input` / positional   | `chartforge data.json`               |
+| stdin       | `-` or no flag with pipe | `cat data.csv \| chartforge -`       |
+| Inline JSON | `--data`                 | `--data '[1,2,3]'`                   |
+| HTTP URL    | `--url`                  | `--url https://api.example.com/data` |
+
+### Supported input formats
+
+ChartForge auto-detects format from file extension. Override with `--format`.
+
+| Format | Auto-detect     | Notes                                                                         |
+| ------ | --------------- | ----------------------------------------------------------------------------- |
+| JSON   | `.json`         | ChartForge shape, arrays, key-value objects, arrays of objects                |
+| CSV    | `.csv`          | First non-numeric column = labels. Multiple numeric columns = multiple series |
+| TSV    | `.tsv`          | Same as CSV but tab-delimited                                                 |
+| YAML   | `.yaml`, `.yml` | Simple key:value only; for complex YAML convert to JSON first                 |
+
+**Auto-detected JSON shapes:**
+
+```json
+// ChartForge native shape
+{ "series": [{ "name": "Revenue", "data": [100, 120, 130] }], "labels": ["Jan","Feb","Mar"] }
+
+// Plain array → single series
+[100, 120, 130, 145]
+
+// Key-value object → labels + single series
+{ "Jan": 100, "Feb": 120, "Mar": 130 }
+
+// Array of objects → auto-detect label/value columns
+[{ "month": "Jan", "value": 100 }, { "month": "Feb", "value": 120 }]
+```
+
+### Output formats
+
+| Format   | Flag             | Notes                                                         |
+| -------- | ---------------- | ------------------------------------------------------------- |
+| HTML     | `--out html`     | Standalone HTML page with stats panel (default)               |
+| SVG      | `--out svg`      | Raw SVG file, self-contained                                  |
+| PNG      | `--out png`      | Requires `npm install sharp` or `npm install @resvg/resvg-js` |
+| Terminal | `--out terminal` | Unicode bar/line/pie charts + sparklines, no file created     |
+
+```bash
+# HTML (default) — full standalone page
+npx chartforge data.json
+
+# SVG — vector, embeddable anywhere
+npx chartforge data.json --out svg -o chart.svg
+
+# PNG — raster image (install sharp first)
+npm install sharp
+npx chartforge data.json --out png -o chart.png
+
+# Terminal — stays in your shell
+npx chartforge data.json --out terminal
+```
+
+### HTTP / API fetching
+
+```bash
+# Simple GET
+npx chartforge --url https://api.example.com/data
+
+# Extract nested path with --jq
+npx chartforge --url https://api.example.com/report --jq data.series
+
+# POST with JSON body + auth header
+npx chartforge \
+  --url https://api.example.com/analytics \
+  --method POST \
+  --headers '{"Authorization":"Bearer TOKEN","Content-Type":"application/json"}' \
+  --body '{"range":"7d","metric":"revenue"}'
+
+# CSV from HTTP
+npx chartforge --url https://data.example.com/export.csv --format csv -t line
+```
+
+### Live polling (`serve` command)
+
+```bash
+# Terminal live dashboard — auto-refreshes
+npx chartforge serve \
+  --url https://api.example.com/live \
+  --interval 5 \
+  --out terminal \
+  -t line
+
+# Save updated HTML every poll
+npx chartforge serve \
+  --url https://api.example.com/metrics \
+  --interval 10 \
+  --out html \
+  -o dashboard.html \
+  --open
+```
+
+### File watching (`watch` command)
+
+```bash
+# Re-render when the file changes
+npx chartforge watch --input data.json --out html --open
+
+# Watch + terminal output
+npx chartforge watch --input data.json --out terminal -t line
+```
+
+### All options
+
+```
+  -i, --input <path>       Input file path (JSON/CSV/TSV/YAML) or - for stdin
+  -u, --url <url>          Fetch data from HTTP/HTTPS URL
+  -d, --data <json>        Inline JSON data string
+  -f, --format <fmt>       Input format: json | csv | tsv | yaml
+      --jq <path>          Dot-path to extract from JSON (e.g. data.items)
+  -X, --method <verb>      HTTP method: GET | POST [GET]
+  -H, --headers <json>     JSON string of HTTP headers
+  -b, --body <str>         HTTP request body (for POST)
+      --interval <sec>     Poll interval in seconds for serve [5]
+
+  -t, --type <type>        Chart type [column]
+      --title <text>       Chart title
+  -w, --width <px>         Width in pixels [800]
+  -h, --height <px>        Height in pixels [450]
+      --theme <name>       Theme: light | dark | neon [dark]
+  -l, --labels <a,b,c>     Comma-separated label override
+
+  -o, --output <path>      Output file path (or - for stdout)
+      --out <format>       Output format: html | svg | png | terminal [html]
+      --open               Open output in browser after rendering
+      --watch              Watch input file and re-render on change
+
+  -v, --verbose            Verbose output
+      --no-color           Disable ANSI colors
+      --help               Show help
+  -V, --version            Print version
+```
+
+### PNG export prerequisites
+
+PNG rendering is optional and requires one of:
+
+```bash
+# Option 1: sharp (best quality, most common)
+npm install sharp
+
+# Option 2: @resvg/resvg-js (pure WASM, no native compilation)
+npm install @resvg/resvg-js
+```
+
+### HttpAdapter (browser / library)
+
+For polling HTTP endpoints inside a chart (not CLI), use the `HttpAdapter`:
+
+```ts
+import { ChartForge }  from 'chartforge';
+import { HttpAdapter } from 'chartforge';
+
+const chart = new ChartForge('#c', { type: 'line', data: { series: [] } });
+
+chart.realTime.registerAdapter('http', HttpAdapter);
+chart.realTime.connect('http', {
+  url:      'https://api.example.com/metrics',
+  interval: 5,               // seconds
+  jq:       'data.series',   // optional dot-path extractor
+  transform: (raw) => ({     // optional custom transformer
+    labels: raw.timestamps,
+    series: [{ name: 'CPU', data: raw.cpu }],
+  }),
+});
+
+// Stop polling
+chart.realTime.disconnect('http');
+```
+
+### CLI architecture
+
+```
+cli/
+├── src/
+│   ├── index.ts              # Entry point / npx binary
+│   ├── args.ts               # Zero-dep argument parser
+│   ├── types.ts              # CLI-specific types
+│   ├── logger.ts             # ANSI-colored logger
+│   │
+│   ├── commands/
+│   │   ├── render.ts         # render command (default)
+│   │   ├── watch.ts          # watch command
+│   │   └── serve.ts          # serve command (live poll)
+│   │
+│   ├── inputs/
+│   │   ├── parser.ts         # JSON/CSV/TSV/YAML parsers
+│   │   ├── file.ts           # File + stdin reader
+│   │   └── http.ts           # HTTP fetcher + poll loop
+│   │
+│   ├── renderer/
+│   │   ├── svg.ts            # Node.js SVG renderer (JSDOM)
+│   │   ├── png.ts            # PNG via sharp/@resvg (optional)
+│   │   └── terminal.ts       # Unicode bar/braille/sparkline renderer
+│   │
+│   └── outputs/
+│       ├── html.ts           # Standalone HTML page generator
+│       └── writer.ts         # File writer + browser opener
+│
+└── dist/
+    └── chartforge.cjs        # Bundled CLI binary (built by Vite)
+```
+
+Build the CLI:
+
+```bash
+npm run build:cli     # → cli/dist/chartforge.cjs
+npm run build:all     # lib + cli together
+```
+
+Test without building:
+
+```bash
+npm run cli:dev -- data.json --out terminal
+# or
+npx tsx cli/src/index.ts data.json --out terminal
+```

package/cli/dist/AxisPlugin-Cge0pH5P.cjs

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const BasePlugin = require("./BasePlugin-DcBTEJBs.cjs");
+const misc = require("./misc-tOf-LXeZ.cjs");
+class AxisPlugin extends BasePlugin.BasePlugin {
+  constructor(chart, cfg = {}) {
+    super(chart, cfg);
+    this._opts = misc.merge({
+      x: { enabled: true, label: "", fontSize: 11, tickLength: 5 },
+      y: { enabled: true, label: "", fontSize: 11, tickLength: 5, ticks: 5 }
+    }, cfg);
+  }
+  init() {
+    const c = this._chart;
+    this._group = misc.createSVGElement("g", { className: "cf-axis" });
+    c.svg.appendChild(this._group);
+    this._els.push(this._group);
+    this._draw();
+    c.on("beforeRender", () => this._draw());
+  }
+  _draw() {
+    const c = this._chart;
+    misc.removeChildren(this._group);
+    const vb = c.svg.getAttribute("viewBox").split(" ").map(Number);
+    const W = vb[2], H = vb[3];
+    const pad = c.config.padding ?? {};
+    const p = { top: pad.top ?? 40, right: pad.right ?? 40, bottom: pad.bottom ?? 60, left: pad.left ?? 60 };
+    if (this._opts.x?.enabled) this._drawX(W, H, p);
+    if (this._opts.y?.enabled) this._drawY(W, H, p);
+  }
+  _drawX(W, H, p) {
+    const c = this._chart;
+    const xo = this._opts.x;
+    const y = H - p.bottom;
+    const sx = p.left, ex = W - p.right;
+    this._group.appendChild(misc.createSVGElement("line", {
+      x1: sx,
+      y1: y,
+      x2: ex,
+      y2: y,
+      stroke: c.theme.axis.line,
+      "stroke-width": 1
+    }));
+    const labels = c.config.data.labels ?? [];
+    const step = (ex - sx) / (labels.length || 1);
+    labels.forEach((lbl, i) => {
+      const x = sx + step * i + step / 2;
+      this._group.appendChild(misc.createSVGElement("line", {
+        x1: x,
+        y1: y,
+        x2: x,
+        y2: y + (xo.tickLength ?? 5),
+        stroke: c.theme.axis.line,
+        "stroke-width": 1
+      }));
+      const t = misc.createSVGElement("text", {
+        x,
+        y: y + (xo.tickLength ?? 5) + 13,
+        fill: c.theme.axis.text,
+        "font-size": xo.fontSize ?? 11,
+        "text-anchor": "middle"
+      });
+      t.textContent = lbl;
+      this._group.appendChild(t);
+    });
+    if (xo.label) {
+      const t = misc.createSVGElement("text", {
+        x: (sx + ex) / 2,
+        y: H - 8,
+        fill: c.theme.text,
+        "font-size": (xo.fontSize ?? 11) + 2,
+        "text-anchor": "middle",
+        "font-weight": "bold"
+      });
+      t.textContent = xo.label;
+      this._group.appendChild(t);
+    }
+  }
+  // @ts-ignore
+  _drawY(W, H, p) {
+    const c = this._chart;
+    const yo = this._opts.y;
+    const x = p.left;
+    const sy = p.top, ey = H - p.bottom;
+    this._group.appendChild(misc.createSVGElement("line", {
+      x1: x,
+      y1: sy,
+      x2: x,
+      y2: ey,
+      stroke: c.theme.axis.line,
+      "stroke-width": 1
+    }));
+    const nticks = yo.ticks ?? 5;
+    const step = (ey - sy) / nticks;
+    const allVals = (c.config.data.series ?? []).flatMap((s) => s.data);
+    const maxVal = allVals.length ? Math.max(...allVals) : 100;
+    for (let i = 0; i <= nticks; i++) {
+      const ty = ey - i * step;
+      const val = (maxVal / nticks * i).toFixed(0);
+      this._group.appendChild(misc.createSVGElement("line", {
+        x1: x - (yo.tickLength ?? 5),
+        y1: ty,
+        x2: x,
+        y2: ty,
+        stroke: c.theme.axis.line,
+        "stroke-width": 1
+      }));
+      const t = misc.createSVGElement("text", {
+        x: x - (yo.tickLength ?? 5) - 5,
+        y: ty,
+        fill: c.theme.axis.text,
+        "font-size": yo.fontSize ?? 11,
+        "text-anchor": "end",
+        "dominant-baseline": "middle"
+      });
+      t.textContent = val;
+      this._group.appendChild(t);
+    }
+    if (yo.label) {
+      const mid = (sy + ey) / 2;
+      const t = misc.createSVGElement("text", {
+        x: 15,
+        y: mid,
+        fill: c.theme.text,
+        "font-size": (yo.fontSize ?? 11) + 2,
+        "text-anchor": "middle",
+        "font-weight": "bold",
+        transform: `rotate(-90,15,${mid})`
+      });
+      t.textContent = yo.label;
+      this._group.appendChild(t);
+    }
+  }
+}
+exports.AxisPlugin = AxisPlugin;

package/cli/dist/BasePlugin-DcBTEJBs.cjs

@@ -0,0 +1,13 @@
+"use strict";
+class BasePlugin {
+  constructor(_chart, _cfg) {
+    this._chart = _chart;
+    this._cfg = _cfg;
+    this._els = [];
+  }
+  destroy() {
+    this._els.forEach((el) => el.parentNode?.removeChild(el));
+    this._els.length = 0;
+  }
+}
+exports.BasePlugin = BasePlugin;