nicevg 0.15.1 → 0.17.1

package/README.md

@@ -1,102 +1,92 @@
-# nicevg for TypeScript (Bun and Node)
+# nicevg
 
-nicevg で図を SVG に描く。TypeScript や JavaScript から、Bun では `bun:ffi`、Node では [koffi](https://koffi.dev/) でネイティブライブラリを呼ぶ。図はノードとコネクタの配列（Sketch）のほか、SVG の文字列でも渡せる。処理は Rust のネイティブコードで動くので、CLI と同じ速さで、出力も同じになる。
+[![npm](https://img.shields.io/npm/v/nicevg)](https://www.npmjs.com/package/nicevg)
+[![CI](https://github.com/takagiy/nicevg/actions/workflows/ci.yml/badge.svg)](https://github.com/takagiy/nicevg/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/takagiy/nicevg/blob/main/LICENSE)
 
-## インストール
+An SVG diagram tool for AI agents, for TypeScript and JavaScript on Bun and Node. It fixes a diagram's problems mechanically on the agent's behalf, and optimizes the layout while preserving the original intent.
 
-```sh
-npm install nicevg   # または bun add nicevg
-```
-
-パッケージには、次の環境向けにビルド済みのネイティブライブラリが入っているので、インストール時にスクリプトは走らず、Rust も要らない。
-
-| 環境 | 対象 |
+| Before | After |
 |---|---|
-| Linux | x64、arm64（glibc 2.17 以降） |
-| macOS | arm64、x64 |
-| Windows | x64 |
+| ![A service diagram with overlapping boxes, an overflowing label, a diagonal line, lines through a box, a box cut off at the edge and labels far from their lines](https://cdn.jsdelivr.net/gh/takagiy/nicevg@main/docs/images/before.svg) | ![The same diagram repaired by nicevg](https://cdn.jsdelivr.net/gh/takagiy/nicevg@main/docs/images/after.svg) |
+
+## Install
 
-## 使い方
+```sh
+npm install nicevg
+# or
+bun add nicevg
+```
 
-入口は `render()` 1 つ。図を受け取り、配置の問題を直し、ノードを少し動かして折れ・交差・混雑を減らして、SVG を表す `Svg` を返す。
+## Example
 
 ```ts
-import { render } from "nicevg";
+import { render, svg, text } from "nicevg";
 
-const svg = render({
+const image = render({
   nodes: [
     { id: "order", x: 20, y: 20, width: 120, height: 56, label: "Order" },
-    { id: "bill", x: 300, y: 160, width: 120, height: 56, label: "Bill" },
-    { id: "user", x: 40, y: 200, width: 80, height: 80, shape: "circle", label: "User" },
-  ],
-  connectors: [
-    { from: "order", to: "bill", label: "invoice" },
-    { from: "user", to: "order" },
+    { id: "orders", class: "pill", x: 300, y: 160, label: "Orders" },
   ],
+  edges: [{ from: "order", to: "orders", label: "save" }],
+  style: {
+    pill: ({ label }) => {
+      const name = text(label);
+      const w = name.width + 32, h = name.height + 20;
+      return svg`
+        <rect width="${w}" height="${h}" rx="${h / 2}" fill="white" stroke="black"/>
+        ${name.at({ cx: w / 2, cy: h / 2 })}`;
+    },
+  },
+  rootAttrs: { "font-family": "sans-serif" },
 });
-
-await svg.write("diagram.svg"); // ファイルに書く
-const text = svg.toString(); // SVG の文字列（`${svg}` でも同じ）
-
-for (const node of svg.report.diagram.nodes) {
-  console.log(node.id, node.bounds); // 動いた後の位置と大きさ
-}
-for (const connector of svg.report.diagram.connectors) {
-  console.log(connector.from, connector.to, connector.points); // 両端のノードと、直交する経路の折れ点
-}
-console.log(svg.report.issues); // 残った問題（なければ空）
-console.log(svg.changes); // 何を直し、何を動かしたか
+await image.write("diagram.svg");
 ```
 
-- `input` は `Sketch`、`{ svg: string }`、または前に返った `Svg`。
-
-### Sketch
-
-| 項目 | 内容 |
-|---|---|
-| `nodes[].id`、`x`、`y`、`width`、`height` | ノードの id と、左上の位置と大きさ |
-| `nodes[].shape` | `"rect"`（既定）か `"circle"`。円は外接する正方形を `x`〜`height` で渡す |
-| `nodes[].label`、`fontSize` | 中に書く文字（`\n` で改行）。子を持つノードでは左上に、それ以外では中央に置く |
-| `nodes[].parent` | このノードを入れる親ノードの id |
-| `nodes[].allowOverlap` | 意図した重なりなら `true` |
-| `connectors[].from`、`to` | 両端のノードの id |
-| `connectors[].points` | 経路の折れ点。省くと、修正と配置調整が両端のノードの辺から辺へ経路を引く |
-| `connectors[].label`、`fontSize` | コネクタの脇に置く文字 |
+## API
 
-`Svg` の `report.diagram` は、描いた図を読み直したもので、ノード（`bounds`、ラベルの範囲 `labelBounds`）、コネクタ（`points`）、ラベル（`bounds`、説明するコネクタの id `connector`）を持つ。コネクタは id を持たないので、`from` と `to` で見分ける。文字の幅は、全角を 1 文字あたりフォントサイズ、それ以外を 0.59 倍として見積もる。
+### `render(input)`
 
-形の書き方が違う入力や、存在しないノードを指す `from`・`to`・`parent` は、どこが何を指しているか（`connectors[0].to` など）を書いた `NicevgError` を投げる。
+Fixes the diagram, nudges its nodes into a cleaner layout and returns an `Svg`. `input` is a sketch (below), `{ svg: string }` with SVG text, or an `Svg` returned before. Bad input throws a `NicevgError` that says which field is wrong, such as `edges[0].to` or `nodes[1].class`.
 
-描画は呼んだスレッドで最後まで走る。大きな図の配置調整は 1〜2 秒かかり、その間すべてのコアを使う。
-
-## 開発
-
-Bun と Node（型を取り除いて .ts を動かせる 22.18 以降）、Rust のツールチェーンが要る。
-
-```sh
-bun install
-bun run build       # cargo でネイティブライブラリを作って native/ に置き、tsc で src/ を dist/ に書き出す
-bun run test        # Bun で src/ を、Node でビルドした dist/ をテストする
-bun run typecheck
-```
-
-パッケージは Bun には `src/` の TypeScript を、Node には `dist/` の JavaScript と型定義を渡す（`package.json` の `exports`）。ネイティブライブラリは `NICEVG_LIBRARY` 環境変数、`native/<platform>-<arch>/`（`bun run build` が置く場所で、公開するパッケージでは全環境ぶん）、リポジトリの `target/release/` の順に探す。
+| Option | |
+|---|---|
+| `nodes` | The boxes, circles and styled nodes (below). |
+| `edges` | The lines between nodes (below). `connectors` is accepted as its old name. |
+| `style` | For each `class` used by a node, a function drawing that node with `svg` and `text`. |
+| `rootAttrs` | Attributes for the root `<svg>`, such as `{ "font-family": "sans-serif" }`. |
 
-`v*` のタグを push すると、`.github/workflows/npm.yml` が各環境のネイティブライブラリを作ってパッケージに入れ、Bun と Node でテストしてから npm に公開する。タグの版と `package.json` の `version` が違えば止まるので、リリースのときは Rust の `Cargo.toml`（ルートと `bindings/js`）と一緒に `package.json` の版も上げる。手で実行すると、公開せずにビルドとパックだけを確かめられる。
+| Node field | |
+|---|---|
+| `id`, `x`, `y` | Its id and its top left corner. |
+| `width`, `height` | Its size. Not used with `class`. |
+| `label`, `fontSize` | Its text, lines split at `\n`. |
+| `shape` | `"rect"` (the default) or `"circle"`. |
+| `parent` | The id of the node it sits inside. |
+| `class` | The `style` that draws it. Other fields you add are passed to that style. |
+| `allowOverlap` | `true` if it overlaps other nodes on purpose. |
+
+| Edge field | |
+|---|---|
+| `from`, `to` | The ids of the nodes it joins. |
+| `label`, `fontSize` | Its text, placed beside it. |
+| `points` | Its route. Without one, rendering routes it from side to side. |
 
-公開は npm の Trusted Publishing（GitHub Actions の OIDC）で、npm のトークンを使わず、配布元の証明（provenance）も自動で付く。
+### `Svg`
 
-Trusted Publisher はすでに npm にあるパッケージにしか登録できないので、最初の 1 回だけは手元から公開する。npm のアカウントで 2FA を有効にしたうえで、次のようにする。
+| Member | |
+|---|---|
+| `write(path)` | Writes the SVG to a file. |
+| `toString()` | The SVG text. |
+| `report.issues` | Problems left after rendering; empty when there are none. |
+| `report.diagram` | The diagram read back: `nodes` with their `bounds`, `connectors` with their `points`, and `labels`. |
+| `changes` | What rendering fixed and moved, in order. |
 
-1. Actions の「Publish to npm」を手で実行する（手での実行は公開しない）。全環境のライブラリをそれぞれの環境でテストし、まとめたパッケージが、成果物 `npm-package` に残る。
-2. それを手元に落として公開する（2FA のワンタイムコードを聞かれる）。手元からの公開なので、この版には配布元の証明が付かない。
-   ```sh
-   gh run download <run-id> -n npm-package
-   npm publish ./nicevg-<version>.tgz
-   ```
-3. このリポジトリと `npm.yml` を Trusted Publisher に登録する（npmjs.com のパッケージの設定か、次のコマンド。どちらも 2FA が要る）。
-   ```sh
-   npm trust github nicevg --file npm.yml --repo takagiy/nicevg --allow-publish
-   ```
+### Drawing a style
 
-以後はタグの push だけで公開される。npm のトークンは作らない（2FA を回避するトークンは、npm が段階的に廃止している）。
+| Function | |
+|---|---|
+| `` svg`...` `` | SVG markup. Embedded strings are escaped; `svg` fragments, texts and arrays of them go in as they are. |
+| `text(content, size = 14)` | One line of text, with the `width` and `height` nicevg measures it at. |
+| `text(...).at({ left \| cx \| right, top \| cy \| bottom })` | Places the text so that point of its box sits at those coordinates. |
+| `` svg`...`.at(x, y) `` | The fragment with its origin moved to `x`, `y`. |

package/dist/draw.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Drawing a node's picture for `render()`'s `style`, as SVG written out:
+ *
+ * ```ts
+ * const store = ({ no, label }) => {
+ *   const id = text(no), name = text(label);
+ *   const sep = id.width + 24, w = sep + name.width + 24, h = Math.max(id.height, name.height) + 20;
+ *   return svg`
+ *     <path d="M ${w} 0 H 0 V ${h} H ${w}" fill="none" stroke="#333"/>
+ *     <line x1="${sep}" y1="0" x2="${sep}" y2="${h}" stroke="#333"/>
+ *     ${id.at({ cx: sep / 2, cy: h / 2 })}
+ *     ${name.at({ left: sep + 12, cy: h / 2 })}`;
+ * };
+ * ```
+ */
+/** SVG written with `svg`: embedded as it is, where strings are escaped. */
+export declare class SvgFragment {
+    #private;
+    constructor(markup: string);
+    toString(): string;
+    /** This fragment with its origin moved to `x`, `y`. */
+    at(x: number, y: number): SvgFragment;
+}
+/** SVG markup with values embedded: strings escaped, fragments, texts and arrays of them as they are. */
+export declare function svg(strings: TemplateStringsArray, ...values: unknown[]): SvgFragment;
+/** Where a text goes: one of `left`, `cx`, `right` across, one of `top`, `cy`, `bottom` down. */
+export type TextPlace = ({
+    left: number;
+} | {
+    cx: number;
+} | {
+    right: number;
+}) & ({
+    top: number;
+} | {
+    cy: number;
+} | {
+    bottom: number;
+});
+/** A line of text, sized the way nicevg measures text, placed with `at`. */
+export declare class Text {
+    readonly content: string;
+    readonly size: number;
+    readonly place: TextPlace;
+    /** Its width, wide characters one font size each and others 0.59. */
+    readonly width: number;
+    /** Its line's height, 1.2 font sizes. */
+    readonly height: number;
+    constructor(content: string, size?: number, place?: TextPlace);
+    /** This text with the point of its box named in `place` at the coordinates given. */
+    at(place: TextPlace): Text;
+    /** The `<text>` element, centred on its line by `dominant-baseline`. */
+    toString(): string;
+}
+/** A line of text at `size` (14 by default), to embed in `svg` once placed with `at`. */
+export declare function text(content: string, size?: number): Text;

package/dist/draw.js

@@ -0,0 +1,87 @@
+/**
+ * Drawing a node's picture for `render()`'s `style`, as SVG written out:
+ *
+ * ```ts
+ * const store = ({ no, label }) => {
+ *   const id = text(no), name = text(label);
+ *   const sep = id.width + 24, w = sep + name.width + 24, h = Math.max(id.height, name.height) + 20;
+ *   return svg`
+ *     <path d="M ${w} 0 H 0 V ${h} H ${w}" fill="none" stroke="#333"/>
+ *     <line x1="${sep}" y1="0" x2="${sep}" y2="${h}" stroke="#333"/>
+ *     ${id.at({ cx: sep / 2, cy: h / 2 })}
+ *     ${name.at({ left: sep + 12, cy: h / 2 })}`;
+ * };
+ * ```
+ */
+const escape = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/** SVG written with `svg`: embedded as it is, where strings are escaped. */
+export class SvgFragment {
+    #markup;
+    constructor(markup) {
+        this.#markup = markup;
+    }
+    toString() {
+        return this.#markup;
+    }
+    /** This fragment with its origin moved to `x`, `y`. */
+    at(x, y) {
+        return svg `<g transform="translate(${x} ${y})">${this}</g>`;
+    }
+}
+function embed(value) {
+    if (value instanceof SvgFragment || value instanceof Text) {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(embed).join("");
+    }
+    return escape(String(value));
+}
+/** SVG markup with values embedded: strings escaped, fragments, texts and arrays of them as they are. */
+export function svg(strings, ...values) {
+    return new SvgFragment(strings.reduce((markup, string, index) => markup + embed(values[index - 1]) + string));
+}
+// shortcut: the common wide ranges (CJK, kana, hangul, fullwidth forms), not every East Asian Wide character; widen it if a script measures short.
+const WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]|[\u{20000}-\u{3fffd}]/u;
+/** A line of text, sized the way nicevg measures text, placed with `at`. */
+export class Text {
+    content;
+    size;
+    place;
+    /** Its width, wide characters one font size each and others 0.59. */
+    width;
+    /** Its line's height, 1.2 font sizes. */
+    height;
+    constructor(content, size = 14, place = { left: 0, top: 0 }) {
+        this.content = content;
+        this.size = size;
+        this.place = place;
+        let width = 0;
+        for (const character of content) {
+            width += WIDE.test(character) ? size : character.length * size * 0.59;
+        }
+        this.width = Math.ceil(width);
+        this.height = Math.ceil(size * 1.2);
+    }
+    /** This text with the point of its box named in `place` at the coordinates given. */
+    at(place) {
+        const across = ["left", "cx", "right"].filter((key) => key in place);
+        const down = ["top", "cy", "bottom"].filter((key) => key in place);
+        if (across.length !== 1 || down.length !== 1) {
+            throw new TypeError(`text "${this.content}": at() takes one of left, cx, right and one of top, cy, bottom, not ${Object.keys(place).join(", ") || "none"}`);
+        }
+        return new Text(this.content, this.size, place);
+    }
+    /** The `<text>` element, centred on its line by `dominant-baseline`. */
+    toString() {
+        const place = this.place;
+        const [x, anchor] = "cx" in place ? [place.cx, "middle"] : "right" in place ? [place.right, "end"] : [place.left, "start"];
+        const y = "cy" in place ? place.cy : "top" in place ? place.top + this.height / 2 : place.bottom - this.height / 2;
+        return `<text x="${x}" y="${y}" font-size="${this.size}" text-anchor="${anchor}" dominant-baseline="central">${escape(this.content)}</text>`;
+    }
+}
+/** A line of text at `size` (14 by default), to embed in `svg` once placed with `at`. */
+export function text(content, size = 14) {
+    return new Text(content, size);
+}
+//# sourceMappingURL=draw.js.map

package/dist/draw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"draw.js","sourceRoot":"","sources":["../src/draw.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -20,6 +20,8 @@
  * Rendering runs on the calling thread and blocks it until done; arranging
  * a large diagram takes a second or two, using every core.
  */
+import type { SvgFragment } from "./draw.ts";
+export { SvgFragment, Text, type TextPlace, svg, text } from "./draw.ts";
 export interface Point {
     x: number;
     y: number;
@@ -60,13 +62,46 @@ export interface SketchConnector {
     label?: string;
     fontSize?: number;
 }
-/** A diagram as nodes and the connectors between them. */
-export interface Sketch {
-    nodes: SketchNode[];
+/**
+ * A node drawn by the style its `class` names, with its origin at `x`, `y`.
+ * It lies around what the style draws, and rendering moves it but never
+ * resizes it. Its other fields, such as `label`, are for the style to use.
+ */
+export interface StyledNode {
+    id: string;
+    x: number;
+    y: number;
+    class: string;
+    /** The node this one sits inside. */
+    parent?: string;
+    /** Whether it may overlap other nodes on purpose. */
+    allowOverlap?: boolean;
+    [field: string]: unknown;
+}
+/** Draws a styled node's picture, from its own origin, with `svg` and `text`. */
+export type Style<Node extends StyledNode = StyledNode> = (node: Node) => SvgFragment;
+/** A style for each class the nodes name, each given the nodes of its class. */
+export type Styles<Node extends SketchNode | StyledNode> = {
+    [Class in Extract<Node, StyledNode>["class"]]: Style<Extract<Node, {
+        class: Class;
+    }>>;
+};
+/** A diagram as nodes and the edges (connectors) between them. */
+export interface Sketch<Node extends SketchNode | StyledNode = SketchNode | StyledNode> {
+    nodes: readonly Node[];
+    edges?: SketchConnector[];
+    /** The same as `edges`, its name before; pass one or the other. */
     connectors?: SketchConnector[];
+    /** How to draw the nodes of each class. */
+    style?: Styles<NoInfer<Node>>;
+    /**
+     * Attributes for the root `<svg>`, such as `font-family`, which its texts
+     * inherit. nicevg writes `xmlns`, `viewBox`, `width` and `height` itself.
+     */
+    rootAttrs?: Record<string, string | number>;
 }
 /** A diagram to render: a sketch, SVG text following nicevg's SVG contract, or an Svg rendered before. */
-export type Input = Sketch | {
+export type Input<Node extends SketchNode | StyledNode = SketchNode | StyledNode> = Sketch<Node> | {
     svg: string;
 } | Svg;
 export interface DiagramNode {
@@ -142,4 +177,4 @@ export declare class NicevgError extends Error {
  * routes through nodes, stray labels and more), routes the connectors given
  * no points, and moves nodes a little where that reads better.
  */
-export declare function render(input: Input): Svg;
+export declare function render<const Node extends SketchNode | StyledNode>(input: Input<Node>): Svg;

package/dist/index.js

@@ -22,6 +22,7 @@
  */
 import { writeFile } from "node:fs/promises";
 import { call as native } from "./native.js";
+export { SvgFragment, Text, svg, text } from "./draw.js";
 /** A rendered diagram as SVG, with what rendering changed and the diagram read back from it. */
 export class Svg {
     changes;
@@ -55,11 +56,34 @@ export class NicevgError extends Error {
  * no points, and moves nodes a little where that reads better.
  */
 export function render(input) {
-    const request = new TextEncoder().encode(JSON.stringify(input instanceof Svg ? { svg: input.toString() } : input));
+    const request = new TextEncoder().encode(JSON.stringify(input instanceof Svg ? { svg: input.toString() } : "svg" in input ? input : sketchRequest(input)));
     const reply = JSON.parse(native(request));
     if ("error" in reply) {
         throw new NicevgError(reply.error);
     }
     return new Svg(reply.ok.svg, reply.ok.changes, reply.ok.report);
 }
+/** The sketch as the native library reads it: styled nodes drawn, edges as connectors. */
+function sketchRequest({ nodes, edges, connectors, style, rootAttrs }) {
+    // Each style is called only with nodes of its own class.
+    const styles = (style ?? {});
+    if (edges && connectors) {
+        throw new NicevgError("edges and connectors are the same; pass one of them");
+    }
+    return {
+        nodes: nodes.map((node, index) => {
+            if (!("class" in node)) {
+                return node;
+            }
+            const draw = Object.hasOwn(styles, node.class) ? styles[node.class] : undefined;
+            if (!draw) {
+                throw new NicevgError(`nodes[${index}].class: no style named "${node.class}"`);
+            }
+            const { id, x, y, parent, allowOverlap } = node;
+            return { id, x, y, parent, allowOverlap, svg: String(draw(node)) };
+        }),
+        connectors: edges ?? connectors,
+        rootAttrs: rootAttrs && Object.fromEntries(Object.entries(rootAttrs).map(([name, value]) => [name, String(value)])),
+    };
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,IAAI,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AA0G7C,gGAAgG;AAChG,MAAM,OAAO,GAAG;IAMH;IAEA;IAPF,KAAK,CAAS;IAEvB,YACE,IAAY;IACZ,mDAAmD;IAC1C,OAAiB;IAC1B,8FAA8F;IACrF,MAAsB;QAFtB,YAAO,GAAP,OAAO,CAAU;QAEjB,WAAM,GAAN,MAAM,CAAgB;QAE/B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,oBAAoB;IACpB,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,qCAAqC;IACrC,KAAK,CAAC,IAAkB;QACtB,OAAO,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,GAAG,aAAa,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,KAAY;IACjC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,YAAY,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACnH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAEnB,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;QACrB,MAAM,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nicevg",
-  "version": "0.15.1",
+  "version": "0.17.1",
   "description": "Deterministic checks and repairs for diagrams, given as shapes or SVG, on Bun and Node through native FFI.",
   "keywords": [
     "diagram",

package/src/draw.ts

@@ -0,0 +1,105 @@
+/**
+ * Drawing a node's picture for `render()`'s `style`, as SVG written out:
+ *
+ * ```ts
+ * const store = ({ no, label }) => {
+ *   const id = text(no), name = text(label);
+ *   const sep = id.width + 24, w = sep + name.width + 24, h = Math.max(id.height, name.height) + 20;
+ *   return svg`
+ *     <path d="M ${w} 0 H 0 V ${h} H ${w}" fill="none" stroke="#333"/>
+ *     <line x1="${sep}" y1="0" x2="${sep}" y2="${h}" stroke="#333"/>
+ *     ${id.at({ cx: sep / 2, cy: h / 2 })}
+ *     ${name.at({ left: sep + 12, cy: h / 2 })}`;
+ * };
+ * ```
+ */
+
+const escape = (value: string) =>
+  value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/** SVG written with `svg`: embedded as it is, where strings are escaped. */
+export class SvgFragment {
+  readonly #markup: string;
+
+  constructor(markup: string) {
+    this.#markup = markup;
+  }
+
+  toString(): string {
+    return this.#markup;
+  }
+
+  /** This fragment with its origin moved to `x`, `y`. */
+  at(x: number, y: number): SvgFragment {
+    return svg`<g transform="translate(${x} ${y})">${this}</g>`;
+  }
+}
+
+function embed(value: unknown): string {
+  if (value instanceof SvgFragment || value instanceof Text) {
+    return value.toString();
+  }
+  if (Array.isArray(value)) {
+    return value.map(embed).join("");
+  }
+  return escape(String(value));
+}
+
+/** SVG markup with values embedded: strings escaped, fragments, texts and arrays of them as they are. */
+export function svg(strings: TemplateStringsArray, ...values: unknown[]): SvgFragment {
+  return new SvgFragment(strings.reduce((markup, string, index) => markup + embed(values[index - 1]) + string));
+}
+
+// shortcut: the common wide ranges (CJK, kana, hangul, fullwidth forms), not every East Asian Wide character; widen it if a script measures short.
+const WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]|[\u{20000}-\u{3fffd}]/u;
+
+/** Where a text goes: one of `left`, `cx`, `right` across, one of `top`, `cy`, `bottom` down. */
+export type TextPlace = ({ left: number } | { cx: number } | { right: number }) &
+  ({ top: number } | { cy: number } | { bottom: number });
+
+/** A line of text, sized the way nicevg measures text, placed with `at`. */
+export class Text {
+  /** Its width, wide characters one font size each and others 0.59. */
+  readonly width: number;
+  /** Its line's height, 1.2 font sizes. */
+  readonly height: number;
+
+  constructor(
+    readonly content: string,
+    readonly size = 14,
+    readonly place: TextPlace = { left: 0, top: 0 },
+  ) {
+    let width = 0;
+    for (const character of content) {
+      width += WIDE.test(character) ? size : character.length * size * 0.59;
+    }
+    this.width = Math.ceil(width);
+    this.height = Math.ceil(size * 1.2);
+  }
+
+  /** This text with the point of its box named in `place` at the coordinates given. */
+  at(place: TextPlace): Text {
+    const across = ["left", "cx", "right"].filter((key) => key in place);
+    const down = ["top", "cy", "bottom"].filter((key) => key in place);
+    if (across.length !== 1 || down.length !== 1) {
+      throw new TypeError(
+        `text "${this.content}": at() takes one of left, cx, right and one of top, cy, bottom, not ${Object.keys(place).join(", ") || "none"}`,
+      );
+    }
+    return new Text(this.content, this.size, place);
+  }
+
+  /** The `<text>` element, centred on its line by `dominant-baseline`. */
+  toString(): string {
+    const place = this.place as Record<string, number>;
+    const [x, anchor] =
+      "cx" in place ? [place.cx!, "middle"] : "right" in place ? [place.right!, "end"] : [place.left!, "start"];
+    const y = "cy" in place ? place.cy! : "top" in place ? place.top! + this.height / 2 : place.bottom! - this.height / 2;
+    return `<text x="${x}" y="${y}" font-size="${this.size}" text-anchor="${anchor}" dominant-baseline="central">${escape(this.content)}</text>`;
+  }
+}
+
+/** A line of text at `size` (14 by default), to embed in `svg` once placed with `at`. */
+export function text(content: string, size = 14): Text {
+  return new Text(content, size);
+}

package/src/index.ts

@@ -23,8 +23,11 @@
 
 import { writeFile } from "node:fs/promises";
 
+import type { SvgFragment } from "./draw.ts";
 import { call as native } from "./native.ts";
 
+export { SvgFragment, Text, type TextPlace, svg, text } from "./draw.ts";
+
 export interface Point {
   x: number;
   y: number;
@@ -69,14 +72,48 @@ export interface SketchConnector {
   fontSize?: number;
 }
 
-/** A diagram as nodes and the connectors between them. */
-export interface Sketch {
-  nodes: SketchNode[];
+/**
+ * A node drawn by the style its `class` names, with its origin at `x`, `y`.
+ * It lies around what the style draws, and rendering moves it but never
+ * resizes it. Its other fields, such as `label`, are for the style to use.
+ */
+export interface StyledNode {
+  id: string;
+  x: number;
+  y: number;
+  class: string;
+  /** The node this one sits inside. */
+  parent?: string;
+  /** Whether it may overlap other nodes on purpose. */
+  allowOverlap?: boolean;
+  [field: string]: unknown;
+}
+
+/** Draws a styled node's picture, from its own origin, with `svg` and `text`. */
+export type Style<Node extends StyledNode = StyledNode> = (node: Node) => SvgFragment;
+
+/** A style for each class the nodes name, each given the nodes of its class. */
+export type Styles<Node extends SketchNode | StyledNode> = {
+  [Class in Extract<Node, StyledNode>["class"]]: Style<Extract<Node, { class: Class }>>;
+};
+
+/** A diagram as nodes and the edges (connectors) between them. */
+export interface Sketch<Node extends SketchNode | StyledNode = SketchNode | StyledNode> {
+  nodes: readonly Node[];
+  edges?: SketchConnector[];
+  /** The same as `edges`, its name before; pass one or the other. */
   connectors?: SketchConnector[];
+  /** How to draw the nodes of each class. */
+  style?: Styles<NoInfer<Node>>;
+  /**
+   * Attributes for the root `<svg>`, such as `font-family`, which its texts
+   * inherit. nicevg writes `xmlns`, `viewBox`, `width` and `height` itself.
+   */
+  rootAttrs?: Record<string, string | number>;
 }
 
 /** A diagram to render: a sketch, SVG text following nicevg's SVG contract, or an Svg rendered before. */
-export type Input = Sketch | { svg: string } | Svg;
+export type Input<Node extends SketchNode | StyledNode = SketchNode | StyledNode> = Sketch<Node> | { svg: string } | Svg;
 
 export interface DiagramNode {
   id: string;
@@ -164,8 +201,10 @@ export class NicevgError extends Error {
  * routes through nodes, stray labels and more), routes the connectors given
  * no points, and moves nodes a little where that reads better.
  */
-export function render(input: Input): Svg {
-  const request = new TextEncoder().encode(JSON.stringify(input instanceof Svg ? { svg: input.toString() } : input));
+export function render<const Node extends SketchNode | StyledNode>(input: Input<Node>): Svg {
+  const request = new TextEncoder().encode(
+    JSON.stringify(input instanceof Svg ? { svg: input.toString() } : "svg" in input ? input : sketchRequest(input)),
+  );
   const reply = JSON.parse(native(request)) as
     | { ok: { svg: string; changes: Change[]; report: AnalysisReport } }
     | { error: string };
@@ -174,3 +213,27 @@ export function render(input: Input): Svg {
   }
   return new Svg(reply.ok.svg, reply.ok.changes, reply.ok.report);
 }
+
+/** The sketch as the native library reads it: styled nodes drawn, edges as connectors. */
+function sketchRequest<Node extends SketchNode | StyledNode>({ nodes, edges, connectors, style, rootAttrs }: Sketch<Node>) {
+  // Each style is called only with nodes of its own class.
+  const styles = (style ?? {}) as Record<string, Style>;
+  if (edges && connectors) {
+    throw new NicevgError("edges and connectors are the same; pass one of them");
+  }
+  return {
+    nodes: nodes.map((node, index) => {
+      if (!("class" in node)) {
+        return node;
+      }
+      const draw = Object.hasOwn(styles, node.class) ? styles[node.class] : undefined;
+      if (!draw) {
+        throw new NicevgError(`nodes[${index}].class: no style named "${node.class}"`);
+      }
+      const { id, x, y, parent, allowOverlap } = node;
+      return { id, x, y, parent, allowOverlap, svg: String(draw(node)) };
+    }),
+    connectors: edges ?? connectors,
+    rootAttrs: rootAttrs && Object.fromEntries(Object.entries(rootAttrs).map(([name, value]) => [name, String(value)])),
+  };
+}