nicevg 0.15.1 → 0.16.0

package/README.md

@@ -59,13 +59,50 @@ console.log(svg.changes); // 何を直し、何を動かしたか
 | `nodes[].label`、`fontSize` | 中に書く文字（`\n` で改行）。子を持つノードでは左上に、それ以外では中央に置く |
 | `nodes[].parent` | このノードを入れる親ノードの id |
 | `nodes[].allowOverlap` | 意図した重なりなら `true` |
-| `connectors[].from`、`to` | 両端のノードの id |
-| `connectors[].points` | 経路の折れ点。省くと、修正と配置調整が両端のノードの辺から辺へ経路を引く |
-| `connectors[].label`、`fontSize` | コネクタの脇に置く文字 |
+| `nodes[].class` | 描き方を `style` から選ぶ名前。付けたノードは `width`・`height`・`shape`・`label` を使わず、`style` が描く |
+| `edges[].from`、`to` | 両端のノードの id。`edges` は前の名前の `connectors` でも渡せる（両方は渡せない） |
+| `edges[].points` | 経路の折れ点。省くと、修正と配置調整が両端のノードの辺から辺へ経路を引く |
+| `edges[].label`、`fontSize` | コネクタの脇に置く文字 |
+| `style` | クラス名から、そのクラスのノードを描く関数への対応 |
+| `rootAttrs` | ルートの `<svg>` に付ける属性（`{ "font-family": "'Yu Gothic', sans-serif" }` など）。中の文字はこれを継承する。`xmlns`・`viewBox`・`width`・`height` は nicevg が書くので渡せない |
+
+### style
+
+`style` の関数はノードを受け取り、ノードの左上を原点にして描いた SVG を `svg` で返す。ノードに足した項目（下の `no` など）も受け取れる。置く位置は `render` がノードの `x`、`y` と配置調整の移動から `translate` で付ける。
+
+```ts
+import { render, svg, text } from "nicevg";
+
+const image = render({
+  nodes: [
+    { id: "customer", x: 20, y: 40, width: 80, height: 40, label: "顧客" },
+    { id: "orders", class: "store", x: 260, y: 40, no: "D1", label: "注文" },
+  ],
+  edges: [{ from: "customer", to: "orders", label: "注文" }],
+  style: {
+    store: ({ no, label }) => {
+      const id = text(String(no)), name = text(String(label));
+      const sep = id.width + 24, w = sep + name.width + 24, h = Math.max(id.height, name.height) + 20;
+      return svg`
+        <g fill="none" stroke="#333">
+          <path d="M ${w} 0 H 0 V ${h} H ${w}"/>
+          <line x1="${sep}" y1="0" x2="${sep}" y2="${h}"/>
+        </g>
+        ${id.at({ cx: sep / 2, cy: h / 2 })}
+        ${name.at({ left: sep + 12, cy: h / 2 })}`;
+    },
+  },
+});
+```
+
+- `` svg`...` `` の中は SVG そのもの。埋め込んだ文字列はエスケープされ、`svg` の断片、`text`、それらの配列はそのまま入る。断片は `.at(x, y)` で原点をずらせる。
+- `text(文字列, 大きさ)` は 1 行の `<text>`。`width`・`height` は nicevg と同じ見積もり。`.at({ 横, 縦 })` で、横は `left`・`cx`・`right`、縦は `top`・`cy`・`bottom` から 1 つずつ選び、文字の箱のその点をその座標に置く。
+- ノードの範囲は、描いたもの（`rect`、`circle`、`ellipse`、`line`、`polyline`、`polygon`、`path`、`text`）を囲む矩形。コネクタはその辺から出入りする。曲線と円弧は端点だけで数える。
+- 修正と配置調整はノードを動かすが、大きさは変えない。中の `<text>` はラベルとして検査しないので、収まりは描く側が決める。
 
 `Svg` の `report.diagram` は、描いた図を読み直したもので、ノード（`bounds`、ラベルの範囲 `labelBounds`）、コネクタ（`points`）、ラベル（`bounds`、説明するコネクタの id `connector`）を持つ。コネクタは id を持たないので、`from` と `to` で見分ける。文字の幅は、全角を 1 文字あたりフォントサイズ、それ以外を 0.59 倍として見積もる。
 
-形の書き方が違う入力や、存在しないノードを指す `from`・`to`・`parent` は、どこが何を指しているか（`connectors[0].to` など）を書いた `NicevgError` を投げる。
+形の書き方が違う入力、存在しないノードを指す `from`・`to`・`parent`、`style` にないクラス、整形式でない SVG を描いたスタイルは、どこが何を指しているか（`connectors[0].to`、`nodes[1].class` など）を書いた `NicevgError` を投げる。
 
 描画は呼んだスレッドで最後まで走る。大きな図の配置調整は 1〜2 秒かかり、その間すべてのコアを使う。
 

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":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,EAAE,CAC/B,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAEnG,4EAA4E;AAC5E,MAAM,OAAO,WAAW;IACb,OAAO,CAAS;IAEzB,YAAY,MAAc;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,uDAAuD;IACvD,EAAE,CAAC,CAAS,EAAE,CAAS;QACrB,OAAO,GAAG,CAAA,2BAA2B,CAAC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;IAC9D,CAAC;CACF;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,IAAI,KAAK,YAAY,WAAW,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,GAAG,CAAC,OAA6B,EAAE,GAAG,MAAiB;IACrE,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AAChH,CAAC;AAED,mJAAmJ;AACnJ,MAAM,IAAI,GAAG,4DAA4D,CAAC;AAM1E,4EAA4E;AAC5E,MAAM,OAAO,IAAI;IAOJ;IACA;IACA;IARX,qEAAqE;IAC5D,KAAK,CAAS;IACvB,yCAAyC;IAChC,MAAM,CAAS;IAExB,YACW,OAAe,EACf,OAAO,EAAE,EACT,QAAmB,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;QAFtC,YAAO,GAAP,OAAO,CAAQ;QACf,SAAI,GAAJ,IAAI,CAAK;QACT,UAAK,GAAL,KAAK,CAAiC;QAE/C,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,SAAS,IAAI,OAAO,EAAE,CAAC;YAChC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;QACxE,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,qFAAqF;IACrF,EAAE,CAAC,KAAgB;QACjB,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC;QACrE,MAAM,IAAI,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC;QACnE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,SAAS,CACjB,SAAS,IAAI,CAAC,OAAO,wEAAwE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,EAAE,CACvI,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;IAED,wEAAwE;IACxE,QAAQ;QACN,MAAM,KAAK,GAAG,IAAI,CAAC,KAA+B,CAAC;QACnD,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,GACf,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAK,EAAE,OAAO,CAAC,CAAC;QAC5G,MAAM,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,EAAG,CAAC,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,GAAI,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAO,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QACtH,OAAO,YAAY,CAAC,QAAQ,CAAC,gBAAgB,IAAI,CAAC,IAAI,kBAAkB,MAAM,iCAAiC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;IAC/I,CAAC;CACF;AAED,yFAAyF;AACzF,MAAM,UAAU,IAAI,CAAC,OAAe,EAAE,IAAI,GAAG,EAAE;IAC7C,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACjC,CAAC"}

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,10 +62,37 @@ export interface SketchConnector {
     label?: string;
     fontSize?: number;
 }
-/** A diagram as nodes and the connectors between them. */
+/**
+ * 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: StyledNode) => SvgFragment;
+/** A diagram as nodes and the edges (connectors) between them. */
 export interface Sketch {
-    nodes: SketchNode[];
+    nodes: (SketchNode | StyledNode)[];
+    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?: Record<string, Style>;
+    /**
+     * 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 | {

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,32 @@ 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 }) {
+    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(style, node.class) ? style[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.16.0",
   "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,10 +72,39 @@ export interface SketchConnector {
   fontSize?: number;
 }
 
-/** A diagram as nodes and the connectors between them. */
+/**
+ * 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: StyledNode) => SvgFragment;
+
+/** A diagram as nodes and the edges (connectors) between them. */
 export interface Sketch {
-  nodes: SketchNode[];
+  nodes: (SketchNode | StyledNode)[];
+  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?: Record<string, Style>;
+  /**
+   * 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. */
@@ -165,7 +197,9 @@ export class NicevgError extends Error {
  * 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));
+  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 +208,25 @@ 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({ nodes, edges, connectors, style = {}, rootAttrs }: Sketch) {
+  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(style, node.class) ? style[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)])),
+  };
+}