@arach/arc 0.4.0 → 0.4.2

package/README.md

@@ -1,8 +1,62 @@
+<div align="center">
+
 # Arc
 
-A visual diagram editor for creating architecture diagrams. Design visually, export as code.
+### Design architecture diagrams visually. Ship them as code.
+
+Arc is a React component **and** a visual editor for building clean, themeable
+architecture diagrams — then exporting them as **TypeScript, JSON, SVG, PNG, or
+crisp ASCII**. Design in the canvas, drop the component in your app, or render
+straight to text for a README. Same diagram, everywhere.
+
+[![npm version](https://img.shields.io/npm/v/@arach/arc.svg?color=6d5efc&label=%40arach%2Farc)](https://www.npmjs.com/package/@arach/arc)
+[![license](https://img.shields.io/npm/l/@arach/arc.svg?color=41b883)](./LICENSE)
+[![types](https://img.shields.io/npm/types/@arach/arc.svg?color=3b82f6)](./lib/index.d.ts)
+
+![A microservices architecture rendered by Arc's ArcDiagram component](public/hero.png)
+
+<sub>Not a screenshot of a drawing tool — that's the config in <a href="#example-output">Example Output</a>, rendered live by <code>&lt;ArcDiagram /&gt;</code>.</sub>
+
+</div>
+
+---
+
+## Install
+
+```bash
+npm install @arach/arc
+# or:  bun add @arach/arc  ·  pnpm add @arach/arc  ·  yarn add @arach/arc
+```
+
+`react`, `react-dom`, and `lucide-react` are peer dependencies.
+
+## Quick Start
+
+Render any diagram config as a polished, interactive component:
+
+```tsx
+import { ArcDiagram } from '@arach/arc'
+import type { ArcDiagramData } from '@arach/arc'
 
-![Arc Editor](public/og-editor.png)
+export function Architecture() {
+  return (
+    <ArcDiagram
+      data={diagram}      // your ArcDiagramData (see below)
+      theme="default"     // default · warm · cool · mono · ibm · palantir · anduril
+      mode="dark"         // light · dark
+      defaultZoom="fit"   // auto-fit to the container
+    />
+  )
+}
+```
+
+You get pan/zoom, hover highlighting, light/dark modes, and seven color themes
+out of the box. Prefer to design visually? Clone the repo and open the editor:
+
+```bash
+git clone https://github.com/arach/arc && cd arc
+bun install && bun dev      # → http://localhost:5188
+```
 
 ## Features
 
@@ -10,21 +64,15 @@ A visual diagram editor for creating architecture diagrams. Design visually, exp
 - **Multiple Node Sizes** - Large, medium, small
 - **Color Themes** - Violet, emerald, blue, amber, sky, zinc, rose, orange
 - **Connector Styles** - Solid/dashed lines, labels, curved paths
-- **Export Options** - TypeScript, JSON, SVG, PNG, shareable links
+- **Export Options** - TypeScript, JSON, SVG, PNG, ASCII, shareable links
 - **Interactive Canvas** - Infinite pan/zoom, grid snapping
 - **Groups & Images** - Visual grouping, background images
 - **Templates** - Quick-start layouts
 
-## Getting Started
-
-```bash
-pnpm install
-pnpm dev
-```
-
 ## Example Output
 
-Arc exports diagrams as clean TypeScript. Here's a microservices architecture:
+Arc stores diagrams as plain, typed data — the same config that renders the
+diagram at the top of this README:
 
 ```typescript
 const diagram: ArcDiagramData = {
@@ -61,6 +109,46 @@ const diagram: ArcDiagramData = {
 }
 ```
 
+## ASCII Renderer
+
+The same diagram renders as precise monospace text — for READMEs, CLI output, or anywhere you can't embed a React component:
+
+```
+                                                     ┌──────────────────┐
+                                                     │ ◆ Auth           │
+                                                   ┌▶│ JWT              │
+                                                   │ └──────────────────┘
+                                                   │
+┌──────────────────┐   ╔═════════════════════════╗ │
+│ ◆ Client         │   ║ ◆ API Gateway           ║ │ ┌──────────────────┐       ┌──────────────────┐
+│ React App        │─┐ ║ Express                 ║ │ │ ◆ API            │ SQL   │ ◆ PostgreSQL     │
+│                  │ └▶║ Load balanced           ║─┴▶│ REST             │──────▶│ Primary          │
+└──────────────────┘   ║                         ║╌┐ └──────────────────┘       └──────────────────┘
+                       ╚═════════════════════════╝ ╎
+                                                   ╎
+                                                   ╎ ┌───────────┐
+                                                   └▶│ ◆ Cache   │
+                                                     └───────────┘
+```
+
+### Programmatic
+
+```typescript
+import { renderAscii } from '@arach/arc'
+
+const ascii = renderAscii(diagram)                          // Unicode box-drawing
+const plain = renderAscii(diagram, { charset: 'ascii' })    // +-- style
+const narrow = renderAscii(diagram, { maxWidth: 80 })       // Auto-scale to 80 cols
+```
+
+### CLI
+
+```bash
+bunx tsx bin/arc-ascii.mjs diagram.json
+cat diagram.json | bunx tsx bin/arc-ascii.mjs
+bunx tsx bin/arc-ascii.mjs diagram.json --charset ascii --max-width 80
+```
+
 ## Requirements
 
 The `ArcDiagram` player component requires:

package/bin/arc-ascii.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * arc-ascii — Render Arc diagram JSON as monospace ASCII art.
+ *
+ * Usage:
+ *   bunx @arach/arc diagram.json
+ *   cat diagram.json | bunx @arach/arc
+ *   bunx @arach/arc diagram.json --charset ascii
+ *   bunx @arach/arc diagram.json --max-width 80
+ */
+
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// Import renderAscii from the built lib (works when installed from npm)
+// or from source (works during local dev with tsx)
+let renderAscii
+try {
+  const lib = await import(resolve(__dirname, '..', 'lib', 'arc.es.js'))
+  renderAscii = lib.renderAscii
+} catch {
+  const src = await import(resolve(__dirname, '..', 'src', 'utils', 'asciiRenderer.ts'))
+  renderAscii = src.renderAscii
+}
+
+// ── Parse args ──────────────────────────────
+
+const args = process.argv.slice(2)
+let filePath = null
+const opts = {}
+
+for (let i = 0; i < args.length; i++) {
+  const a = args[i]
+  if (a === '--charset' || a === '-c') { opts.charset = args[++i]; continue }
+  if (a === '--max-width' || a === '-w') { opts.maxWidth = Number(args[++i]); continue }
+  if (a === '--no-labels') { opts.showLabels = false; continue }
+  if (a === '--scale-x') { opts.scaleX = Number(args[++i]); continue }
+  if (a === '--scale-y') { opts.scaleY = Number(args[++i]); continue }
+  if (a === '--help' || a === '-h') { printHelp(); process.exit(0) }
+  if (!a.startsWith('-')) filePath = a
+}
+
+// ── Read input ──────────────────────────────
+
+let json
+try {
+  if (filePath) {
+    json = readFileSync(filePath, 'utf-8')
+  } else if (!process.stdin.isTTY) {
+    const chunks = []
+    for await (const chunk of process.stdin) chunks.push(chunk)
+    json = Buffer.concat(chunks).toString('utf-8')
+  } else {
+    printHelp()
+    process.exit(1)
+  }
+} catch (err) {
+  console.error(`Error reading input: ${err.message}`)
+  process.exit(1)
+}
+
+// ── Parse & render ──────────────────────────
+
+let data
+try {
+  data = JSON.parse(json)
+} catch {
+  const match = json.match(/(?:export\s+default\s+|(?:const|let|var)\s+\w+(?::\s*\S+)?\s*=\s*)(\{[\s\S]*\})/)
+  if (match) {
+    try {
+      const normalized = match[1]
+        .replace(/'/g, '"')
+        .replace(/,(\s*[}\]])/g, '$1')
+        .replace(/([{,]\s*)(\w+)(\s*:)/g, '$1"$2"$3')
+      data = JSON.parse(normalized)
+    } catch {
+      console.error('Error: Could not parse diagram data.')
+      process.exit(1)
+    }
+  } else {
+    console.error('Error: Input is not valid JSON or a recognizable diagram module.')
+    process.exit(1)
+  }
+}
+
+if (!data.layout || !data.nodes || !data.nodeData) {
+  console.error('Error: Input does not look like ArcDiagramData (missing layout, nodes, or nodeData).')
+  process.exit(1)
+}
+
+if (!data.connectorStyles) data.connectorStyles = {}
+
+console.log(renderAscii(data, opts))
+
+// ── Help ────────────────────────────────────
+
+function printHelp() {
+  console.log(`
+arc-ascii — Render Arc diagrams as ASCII art
+
+Usage:
+  bunx @arach/arc <file.json>        Read diagram from file
+  cat diagram.json | bunx @arach/arc Read from stdin
+
+Options:
+  -c, --charset <unicode|ascii>      Character set (default: unicode)
+  -w, --max-width <cols>             Max output width in columns
+      --no-labels                    Hide connector labels
+      --scale-x <n>                  Pixels per char horizontally (default: 8)
+      --scale-y <n>                  Pixels per char vertically (default: 16)
+  -h, --help                         Show this help
+`.trim())
+}