graphics-debug 0.0.21 → 0.0.23

package/README.md

@@ -36,23 +36,52 @@ https://github.com/user-attachments/assets/9f3f41e6-b0fe-416a-a551-ba5c5b920cad
 The `graphics` json object is very simple, here's the basic schema:
 
 ```typescript
+interface Point {
+  x: number
+  y: number
+  color?: string
+  label?: string
+  layer?: string
+  step?: number
+}
+
+interface Line {
+  points: { x: number; y: number }[]
+  strokeWidth?: number
+  strokeColor?: string
+  strokeDash?: string
+  layer?: string
+  step?: number
+  label?: string
+}
+
+interface Rect {
+  center: { x: number; y: number }
+  width: number
+  height: number
+  fill?: string
+  stroke?: string
+  color?: string
+  layer?: string
+  step?: number
+  label?: string
+}
+
+interface Circle {
+  center: { x: number; y: number }
+  radius: number
+  fill?: string
+  stroke?: string
+  layer?: string
+  step?: number
+  label?: string
+}
+
 interface GraphicsObject {
-  points?: { x: number; y: number; color?: string; label?: string }[]
-  lines?: { points: { x: number; y: number; stroke?: number }[] }[]
-  rects?: Array<{
-    center: { x: number; y: number }
-    width: number
-    height: number
-    fill?: string
-    stroke?: string
-  }>
-  circles?: Array<{
-    center: { x: number; y: number }
-    radius: number
-    fill?: string
-    stroke?: string
-  }>
-  grid?: { cellSize: number; label?: boolean }
+  points?: Point[]
+  lines?: Line[]
+  rects?: Rect[]
+  circles?: Circle[]
   coordinateSystem?: "cartesian" | "screen"
   title?: string
 }
@@ -131,6 +160,65 @@ const graphicsObjects = getGraphicsObjectsFromLogString(logString)
 // Array<GraphicsObject>
 ```
 
+### Generate SVG directly from a GraphicsObject
+
+```tsx
+import { getSvgFromGraphicsObject } from "graphics-debug"
+
+// Create your graphics object
+const graphicsObject = {
+  points: [{ x: 0, y: 0, label: "Origin" }, { x: 100, y: 100, color: "red" }],
+  lines: [{ points: [{ x: 0, y: 0 }, { x: 100, y: 100 }], strokeColor: "blue" }],
+  title: "My Graph"
+}
+
+// Generate SVG string directly from the object
+const svg = getSvgFromGraphicsObject(graphicsObject)
+// Returns a formatted SVG string ready to be written to a file or embedded in HTML
+```
+
+### Testing GraphicsObjects with Bun's Test Framework
+
+If you're using Bun for testing, you can use the `toMatchGraphicsSvg` matcher to compare graphics objects against saved snapshots.
+
+First, install the required peer dependencies:
+
+```bash
+bun add -d bun-match-svg looksSame
+```
+
+Then use the matcher in your tests:
+
+```tsx
+import { expect, test } from "bun:test"
+import "graphics-debug/matcher"
+import type { GraphicsObject } from "graphics-debug" 
+
+// Your test graphics object
+const graphicsObject: GraphicsObject = {
+  points: [{ x: 0, y: 0, label: "Origin" }, { x: 100, y: 100, color: "red" }],
+  lines: [{ points: [{ x: 0, y: 0 }, { x: 100, y: 100 }], strokeColor: "blue" }],
+  title: "My Test Graphics"
+}
+
+test("should match the expected visualization", async () => {
+  // First run creates the snapshot
+  // Subsequent runs will compare against saved snapshot
+  await expect(graphicsObject).toMatchGraphicsSvg(import.meta.path)
+  
+  // You can also provide a custom name for the snapshot:
+  await expect(graphicsObject).toMatchGraphicsSvg(import.meta.path, "custom-name")
+})
+```
+
+Snapshots are stored as SVG files in an `__snapshots__` directory next to your test file. To update snapshots, run your tests with the `-u` or `--update-snapshots` flag:
+
+```bash
+bun test -u
+```
+
+This is powered by the same technology as bun-match-svg but integrated specifically for GraphicsObject testing.
+
 ### Example Graphics JSON
 
 An example graphics JSON file is provided in the repository to help you get started quickly.

package/dist/lib/matcher.d.ts

@@ -0,0 +1,5 @@
+declare module "bun:test" {
+    interface Matchers<T = unknown> {
+        toMatchGraphicsSvg(testPath: string, svgName?: string): Promise<MatcherResult>;
+    }
+}

package/dist/lib/matcher.js

@@ -0,0 +1,60 @@
+import {
+  getSvgFromGraphicsObject
+} from "../chunk-5FZF67ET.js";
+
+// lib/matcher.ts
+import { expect } from "bun:test";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import looksSame from "looks-same";
+async function toMatchGraphicsSvg(receivedMaybePromise, testPathOriginal, svgName) {
+  const received = await receivedMaybePromise;
+  const testPath = testPathOriginal.replace(/\.test\.tsx?$/, "");
+  const snapshotDir = path.join(path.dirname(testPath), "__snapshots__");
+  const snapshotName = svgName ? `${svgName}.snap.svg` : `${path.basename(testPath)}.snap.svg`;
+  const filePath = path.join(snapshotDir, snapshotName);
+  if (!fs.existsSync(snapshotDir)) {
+    fs.mkdirSync(snapshotDir, { recursive: true });
+  }
+  const receivedSvg = getSvgFromGraphicsObject(received);
+  const updateSnapshot = process.argv.includes("--update-snapshots") || process.argv.includes("-u") || Boolean(process.env["BUN_UPDATE_SNAPSHOTS"]);
+  if (!fs.existsSync(filePath) || updateSnapshot) {
+    console.log("Writing snapshot to", filePath);
+    fs.writeFileSync(filePath, receivedSvg);
+    return {
+      message: () => `Snapshot created at ${filePath}`,
+      pass: true
+    };
+  }
+  const existingSnapshot = fs.readFileSync(filePath, "utf-8");
+  const result = await looksSame(
+    Buffer.from(receivedSvg),
+    Buffer.from(existingSnapshot),
+    {
+      strict: false,
+      tolerance: 2
+    }
+  );
+  if (result.equal) {
+    return {
+      message: () => "Snapshot matches",
+      pass: true
+    };
+  }
+  const diffPath = filePath.replace(".snap.svg", ".diff.png");
+  await looksSame.createDiff({
+    reference: Buffer.from(existingSnapshot),
+    current: Buffer.from(receivedSvg),
+    diff: diffPath,
+    highlightColor: "#ff00ff"
+  });
+  return {
+    message: () => `Snapshot does not match. Diff saved at ${diffPath}`,
+    pass: false
+  };
+}
+expect.extend({
+  // biome-ignore lint/suspicious/noExplicitAny: bun's types don't expose matcher type
+  toMatchGraphicsSvg
+});
+//# sourceMappingURL=matcher.js.map

package/dist/lib/matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../lib/matcher.ts"],"sourcesContent":["import { expect, type MatcherResult } from \"bun:test\"\nimport * as fs from \"node:fs\"\nimport * as path from \"node:path\"\nimport looksSame from \"looks-same\"\nimport { GraphicsObject } from \"./types\"\nimport { getSvgFromGraphicsObject } from \"./getSvgFromGraphicsObject\"\n\n/**\n * Custom matcher for Bun tests to compare GraphicsObjects as SVGs\n * \n * @param this Matcher context\n * @param receivedMaybePromise GraphicsObject or Promise<GraphicsObject> to test\n * @param testPathOriginal Path to the test file\n * @param svgName Optional name for the snapshot\n * @returns Matcher result\n */\nasync function toMatchGraphicsSvg(\n  // biome-ignore lint/suspicious/noExplicitAny: bun doesn't expose matcher type\n  this: any,\n  receivedMaybePromise: GraphicsObject | Promise<GraphicsObject>,\n  testPathOriginal: string,\n  svgName?: string,\n): Promise<MatcherResult> {\n  const received = await receivedMaybePromise\n  const testPath = testPathOriginal.replace(/\\.test\\.tsx?$/, \"\")\n  const snapshotDir = path.join(path.dirname(testPath), \"__snapshots__\")\n  const snapshotName = svgName\n    ? `${svgName}.snap.svg`\n    : `${path.basename(testPath)}.snap.svg`\n  const filePath = path.join(snapshotDir, snapshotName)\n\n  if (!fs.existsSync(snapshotDir)) {\n    fs.mkdirSync(snapshotDir, { recursive: true })\n  }\n\n  // Convert GraphicsObject to SVG\n  const receivedSvg = getSvgFromGraphicsObject(received)\n\n  const updateSnapshot =\n    process.argv.includes(\"--update-snapshots\") ||\n    process.argv.includes(\"-u\") ||\n    Boolean(process.env[\"BUN_UPDATE_SNAPSHOTS\"])\n\n  if (!fs.existsSync(filePath) || updateSnapshot) {\n    console.log(\"Writing snapshot to\", filePath)\n    fs.writeFileSync(filePath, receivedSvg)\n    return {\n      message: () => `Snapshot created at ${filePath}`,\n      pass: true,\n    }\n  }\n\n  const existingSnapshot = fs.readFileSync(filePath, \"utf-8\")\n\n  const result: any = await looksSame(\n    Buffer.from(receivedSvg),\n    Buffer.from(existingSnapshot),\n    {\n      strict: false,\n      tolerance: 2,\n    },\n  )\n\n  if (result.equal) {\n    return {\n      message: () => \"Snapshot matches\",\n      pass: true,\n    }\n  }\n\n  const diffPath = filePath.replace(\".snap.svg\", \".diff.png\")\n  await looksSame.createDiff({\n    reference: Buffer.from(existingSnapshot),\n    current: Buffer.from(receivedSvg),\n    diff: diffPath,\n    highlightColor: \"#ff00ff\",\n  })\n\n  return {\n    message: () => `Snapshot does not match. Diff saved at ${diffPath}`,\n    pass: false,\n  }\n}\n\n// Add the custom matcher to the expect object\nexpect.extend({\n  // biome-ignore lint/suspicious/noExplicitAny: bun's types don't expose matcher type\n  toMatchGraphicsSvg: toMatchGraphicsSvg as any,\n})\n\n// Extend the TypeScript interface for the matcher\ndeclare module \"bun:test\" {\n  interface Matchers<T = unknown> {\n    toMatchGraphicsSvg(\n      testPath: string,\n      svgName?: string,\n    ): Promise<MatcherResult>\n  }\n}"],"mappings":";;;;;AAAA,SAAS,cAAkC;AAC3C,YAAY,QAAQ;AACpB,YAAY,UAAU;AACtB,OAAO,eAAe;AAatB,eAAe,mBAGb,sBACA,kBACA,SACwB;AACxB,QAAM,WAAW,MAAM;AACvB,QAAM,WAAW,iBAAiB,QAAQ,iBAAiB,EAAE;AAC7D,QAAM,cAAmB,UAAU,aAAQ,QAAQ,GAAG,eAAe;AACrE,QAAM,eAAe,UACjB,GAAG,OAAO,cACV,GAAQ,cAAS,QAAQ,CAAC;AAC9B,QAAM,WAAgB,UAAK,aAAa,YAAY;AAEpD,MAAI,CAAI,cAAW,WAAW,GAAG;AAC/B,IAAG,aAAU,aAAa,EAAE,WAAW,KAAK,CAAC;AAAA,EAC/C;AAGA,QAAM,cAAc,yBAAyB,QAAQ;AAErD,QAAM,iBACJ,QAAQ,KAAK,SAAS,oBAAoB,KAC1C,QAAQ,KAAK,SAAS,IAAI,KAC1B,QAAQ,QAAQ,IAAI,sBAAsB,CAAC;AAE7C,MAAI,CAAI,cAAW,QAAQ,KAAK,gBAAgB;AAC9C,YAAQ,IAAI,uBAAuB,QAAQ;AAC3C,IAAG,iBAAc,UAAU,WAAW;AACtC,WAAO;AAAA,MACL,SAAS,MAAM,uBAAuB,QAAQ;AAAA,MAC9C,MAAM;AAAA,IACR;AAAA,EACF;AAEA,QAAM,mBAAsB,gBAAa,UAAU,OAAO;AAE1D,QAAM,SAAc,MAAM;AAAA,IACxB,OAAO,KAAK,WAAW;AAAA,IACvB,OAAO,KAAK,gBAAgB;AAAA,IAC5B;AAAA,MACE,QAAQ;AAAA,MACR,WAAW;AAAA,IACb;AAAA,EACF;AAEA,MAAI,OAAO,OAAO;AAChB,WAAO;AAAA,MACL,SAAS,MAAM;AAAA,MACf,MAAM;AAAA,IACR;AAAA,EACF;AAEA,QAAM,WAAW,SAAS,QAAQ,aAAa,WAAW;AAC1D,QAAM,UAAU,WAAW;AAAA,IACzB,WAAW,OAAO,KAAK,gBAAgB;AAAA,IACvC,SAAS,OAAO,KAAK,WAAW;AAAA,IAChC,MAAM;AAAA,IACN,gBAAgB;AAAA,EAClB,CAAC;AAED,SAAO;AAAA,IACL,SAAS,MAAM,0CAA0C,QAAQ;AAAA,IACjE,MAAM;AAAA,EACR;AACF;AAGA,OAAO,OAAO;AAAA;AAAA,EAEZ;AACF,CAAC;","names":[]}

package/package.json

@@ -2,7 +2,7 @@
   "name": "graphics-debug",
   "main": "dist/lib/index.js",
   "type": "module",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "files": [
     "dist"
   ],
@@ -14,6 +14,10 @@
     "./react": {
       "types": "./dist/lib/react.d.ts",
       "import": "./dist/lib/react.js"
+    },
+    "./matcher": {
+      "types": "./dist/lib/matcher.d.ts",
+      "import": "./dist/lib/matcher.js"
     }
   },
   "bin": {
@@ -38,7 +42,6 @@
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
     "@vitejs/plugin-react": "^4.3.3",
-    "bun-match-svg": "^0.0.8",
     "commander": "^12.1.0",
     "debug": "^4.3.7",
     "jsdom": "^25.0.1",
@@ -51,7 +54,9 @@
     "vite-tsconfig-paths": "^5.1.4"
   },
   "peerDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "bun-match-svg": "^0.0.9",
+    "looks-same": "^9.0.1"
   },
   "dependencies": {
     "@types/react-router-dom": "^5.3.3",