@design-core/core 51.1.0 → 51.2.0

package/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+# Publishes @design-core/core to npm when a semver tag (e.g. v51.1.0) is pushed.
+# Requires an NPM_TOKEN repository secret (an "Automation" type npm access token).
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.x
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+      - run: npm test -- --coverage
+      - run: npx eslint . --ext .js
+
+      # Fail fast if the tag and package.json version have drifted apart
+      - name: Verify tag matches package.json version
+        run: |
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          TAG_VERSION=${GITHUB_REF_NAME#v}
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Tag v$TAG_VERSION does not match package.json version $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -14,10 +14,23 @@ Design-Core uses the industry standard Drawing Exchange Format (DXF) to read and
 * Design-Web: https://github.com/dubstar-04/Design-Web
 * HTML Canvas: https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API
 * Cairo: https://www.cairographics.org/
+* npm package: https://www.npmjs.com/package/@design-core/core
 
 
 ## Publishing
 
-npm login
+Releases are published to npm automatically by the [Publish to npm](.github/workflows/publish.yml) workflow whenever a `v*.*.*` tag is pushed:
+
+```bash
+npm version patch   # or minor / major, bumps package.json and creates a git tag
+git push --follow-tags
+```
+
+The workflow runs the test suite and linter, verifies the tag matches `package.json`'s version, then publishes.
 
+To publish manually instead:
+
+```bash
+npm login
 npm publish --access public
+```

package/core/lib/canvas.js

@@ -305,7 +305,9 @@ export class Canvas {
    */
   exportTo(renderer, plotOptions) {
     let area;
-    if (plotOptions.plotArea === PlotOptions.Area.DISPLAY) {
+    if (plotOptions.plotArea === PlotOptions.Area.WINDOW) {
+      area = new BoundingBox(plotOptions.windowArea.point1, plotOptions.windowArea.point2);
+    } else if (plotOptions.plotArea === PlotOptions.Area.DISPLAY) {
       const viewport = this.getSceneOffset();
       area = new BoundingBox(new Point(viewport.xmin, viewport.ymin), new Point(viewport.xmax, viewport.ymax));
     } else {
@@ -318,6 +320,7 @@ export class Canvas {
       pageWidth: plotOptions.pageWidth,
       pageHeight: plotOptions.pageHeight,
       plotScale: plotOptions.plotScale,
+      margin: plotOptions.margin,
     });
     if (!matrix) return false;
 

package/core/lib/commandManager.js

@@ -43,6 +43,9 @@ import { Purge } from '../tools/purge.js';
 import { Pan } from '../tools/pan.js';
 import { Zoom } from '../tools/zoom.js';
 
+// Internal tools (not shown in any toolbar, invoked programmatically)
+import { WindowPick } from '../tools/windowPick.js';
+
 // Clipboard tools
 import { Copybase } from '../tools/copybase.js';
 import { Copyclip } from '../tools/copyclip.js';
@@ -99,6 +102,8 @@ const classes = {
   Zoom,
   Pan,
 
+  WindowPick,
+
   Copybase,
   Copyclip,
   Cutclip,

package/core/lib/inputManager.js

@@ -39,6 +39,7 @@ export class InputManager {
     }
 
     this.promptOption = undefined;
+    DesignCore.Mouse.reset();
     DesignCore.Scene.reset();
     DesignCore.Canvas.setCursorForInputTypes([]);
   }

package/core/lib/mouse.js

@@ -15,6 +15,16 @@ export class Mouse {
     this.lastButton = 0; // last button for double click check
   }
 
+  /**
+   * Clear button state - guards against a stuck button when a mouseUp
+   * never reaches the canvas (e.g. focus stolen by another window mid-click)
+   */
+  reset() {
+    this.buttonOneDown = false;
+    this.buttonTwoDown = false;
+    this.buttonThreeDown = false;
+  }
+
   /**
    * Returns the point on the design canvas
    * @return {Point}

package/core/lib/plotOptions.js

@@ -9,6 +9,7 @@ export class PlotOptions {
   static Area = {
     EXTENTS: 'Extents',
     DISPLAY: 'Display',
+    WINDOW: 'Window',
   };
 
   static #fileTypes = ['pdf', 'svg'];
@@ -22,6 +23,8 @@ export class PlotOptions {
     this.setOption('pageHeight', pageHeight);
     this.plotScale = null;
     this.plotArea = PlotOptions.Area.EXTENTS;
+    this.windowArea = null;
+    this.margin = 40;
     this.style = RendererBase.Styles.NONE;
     this.fileType = 'pdf';
   }
@@ -49,6 +52,20 @@ export class PlotOptions {
           throw new Error(`PlotOptions: plotArea must be one of: ${Object.values(PlotOptions.Area).join(', ')}`);
         }
         break;
+      case 'windowArea':
+        // required when plotArea is WINDOW - two points defining the plot window, e.g. { point1, point2 }
+        if (value !== null && (!value || value.point1 === undefined || value.point2 === undefined)) {
+          throw new Error('PlotOptions: windowArea must be null or an object with point1 and point2');
+        }
+        break;
+      case 'margin':
+        if (!Number.isFinite(value) || value < 0) {
+          throw new Error('PlotOptions: margin must be a non-negative finite number');
+        }
+        if (this.pageWidth - 2 * value <= 0 || this.pageHeight - 2 * value <= 0) {
+          throw new Error('PlotOptions: margin leaves no usable page area');
+        }
+        break;
       case 'style':
         if (typeof value !== 'function') {
           throw new Error('PlotOptions: style must be a function');

package/core/lib/strings.js

@@ -110,6 +110,8 @@ export class Strings {
     DESTINATIONSET: 'Select destination object(s)',
     MIRRORFIRST: 'Specify first point of mirror line',
     MIRRORSECOND: 'Specify second point of mirror line',
+    FIRSTCORNER: 'Specify first corner',
+    SECONDCORNER: 'Specify second corner',
     ERASESOURCE: 'Erase source objects?',
     SCALEFACTOR: 'Specify scale factor',
     REFERENCELENGTH: 'Specify reference length',

package/core/tools/windowPick.js

@@ -0,0 +1,75 @@
+import { Tool } from './tool.js';
+import { Input, PromptOptions } from '../lib/inputManager.js';
+import { Strings } from '../lib/strings.js';
+import { Logging } from '../lib/logging.js';
+import { Point } from '../entities/point.js';
+
+import { DesignCore } from '../designCore.js';
+
+/**
+ * WindowPick Command Class
+ * Internal tool used to interactively pick two corner points defining a rectangular window (e.g. for the plot window area).
+ * Not shown in any toolbar; invoked programmatically.
+ * @extends Tool
+ */
+export class WindowPick extends Tool {
+  static type = 'WindowPick';
+
+  /** Create a WindowPick command */
+  constructor() {
+    super();
+  }
+
+  /**
+   * Register the command
+   * @return {Object}
+   * command = name of the command
+   */
+  static register() {
+    const command = { command: 'WindowPick' };
+    return command;
+  }
+
+  /**
+   * Execute method
+   * requests the two corner points defining the plot window
+   */
+  async execute() {
+    try {
+      const op1 = new PromptOptions(Strings.Input.FIRSTCORNER, [Input.Type.POINT]);
+      const pt1 = await DesignCore.Scene.inputManager.requestInput(op1);
+      if (pt1 === undefined) return;
+      this.points.push(pt1);
+
+      const op2 = new PromptOptions(Strings.Input.SECONDCORNER, [Input.Type.POINT]);
+      const pt2 = await DesignCore.Scene.inputManager.requestInput(op2);
+      if (pt2 === undefined) return;
+      this.points.push(pt2);
+
+      DesignCore.Scene.inputManager.executeCommand();
+    } catch (err) {
+      Logging.instance.error(`${this.type} - ${err}`);
+    }
+  }
+
+  /**
+   * Preview the command during execution
+   */
+  preview() {
+    if (this.points.length === 1) {
+      const mousePoint = DesignCore.Mouse.pointOnScene();
+      const p1 = this.points[0];
+      const p2 = mousePoint;
+
+      const points = [
+        new Point(p1.x, p1.y),
+        new Point(p2.x, p1.y),
+        new Point(p2.x, p2.y),
+        new Point(p1.x, p2.y),
+        new Point(p1.x, p1.y),
+      ];
+
+      DesignCore.Scene.previewEntities.create('Polyline', { points: points });
+    }
+  }
+}

package/cspell.json

@@ -195,6 +195,7 @@
         "RRGGBB",
         "rubberbandcolour",
         "SCALEFACTOR",
+        "SECONDCORNER",
         "selectedchild",
         "SELECTIONSET",
         "SEQEND",
@@ -277,6 +278,7 @@
         "INVALIDFILE",
         "INVALIDGROUPCODE",
         "INVALIDINTERSECTTYPE",
+        "FIRSTCORNER",
         "INVALIDNUMBER",
         "INVALIDPOINT",
         "INVALIDTYPE",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-core/core",
-  "version": "51.1.0",
+  "version": "51.2.0",
   "type": "module",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
@@ -19,7 +19,12 @@
     ".": "./core/core/core.js",
     "./designCore.js": "./core/designCore.js",
     "./property.js": "./core/properties/property.js",
-    "./canvasRenderer.js": "./core/lib/renderers/canvasRenderer.js"
+    "./canvasRenderer.js": "./core/lib/renderers/canvasRenderer.js",
+    "./constants.js": "./core/lib/constants.js",
+    "./plotOptions.js": "./core/lib/plotOptions.js",
+    "./rendererBase.js": "./core/lib/renderers/rendererBase.js",
+    "./svgRenderer.js": "./core/lib/renderers/svgRenderer.js",
+    "./pdfRenderer.js": "./core/lib/renderers/pdfRenderer.js"
   },
   "directories": {
     "test": "test"

package/test/integration/plotPageSizeIntegration.test.js

@@ -0,0 +1,113 @@
+import { Core } from '../../core/core/core.js';
+import { Point } from '../../core/entities/point.js';
+import { Constants } from '../../core/lib/constants.js';
+import { PlotOptions } from '../../core/lib/plotOptions.js';
+import { BoundingBox } from '../../core/lib/boundingBox.js';
+import { SvgRenderer } from '../../core/lib/renderers/svgRenderer.js';
+import { jest } from '@jest/globals';
+
+// smallest -> largest; each rectangle fully contains all previous ones when aligned at the origin
+const PAGE_NAMES_ASC = ['A4', 'A3', 'A2', 'A1', 'A0'];
+
+// Portrait uses the raw (width < height) page size; Landscape swaps the two axes,
+// matching the orientation toggle in the GTK plot dialog (plotWindow.js)
+const ORIENTATIONS = {
+  Portrait: (size) => ({ pageWidth: size.width, pageHeight: size.height }),
+  Landscape: (size) => ({ pageWidth: size.height, pageHeight: size.width }),
+};
+
+/**
+ * Build a closed 4-corner loop, mirroring Rectangle.rectPoints()
+ * @param {Point} pt1
+ * @param {Point} pt2
+ * @return {Array}
+ */
+function rectPoints(pt1, pt2) {
+  return [
+    new Point(pt1.x, pt1.y),
+    new Point(pt2.x, pt1.y),
+    new Point(pt2.x, pt2.y),
+    new Point(pt1.x, pt2.y),
+    new Point(pt1.x, pt1.y),
+  ];
+}
+
+describe.each(Object.keys(ORIENTATIONS))('%s orientation', (orientation) => {
+  const toPage = ORIENTATIONS[orientation];
+
+  test.each(PAGE_NAMES_ASC)('Extents matches %s page size exactly', (name) => {
+    const { pageWidth, pageHeight } = toPage(Constants.PageSizes[name]);
+    const core = new Core();
+    core.activate();
+    core.scene.addEntity('Polyline', { points: rectPoints(new Point(0, 0), new Point(pageWidth, pageHeight)) });
+
+    const area = core.scene.boundingBox();
+    expect(area.xLength).toBeCloseTo(pageWidth, 5);
+    expect(area.yLength).toBeCloseTo(pageHeight, 5);
+
+    const matrix = core.canvas.buildExportMatrix({
+      area, pageWidth, pageHeight, plotScale: 1, margin: 0,
+    });
+    expect(matrix.a).toBe(1);
+    expect(matrix.e).toBeCloseTo(0, 5);
+    expect(matrix.f).toBeCloseTo(0, 5);
+  });
+
+  test('Extents grows to match each page size as rectangles are added smallest to largest', () => {
+    const core = new Core();
+    core.activate();
+
+    for (const name of PAGE_NAMES_ASC) {
+      const { pageWidth, pageHeight } = toPage(Constants.PageSizes[name]);
+      core.scene.addEntity('Polyline', { points: rectPoints(new Point(0, 0), new Point(pageWidth, pageHeight)) });
+
+      const area = core.scene.boundingBox();
+      expect(area.xLength).toBeCloseTo(pageWidth, 5);
+      expect(area.yLength).toBeCloseTo(pageHeight, 5);
+    }
+  });
+
+  test('Window area isolates each nested rectangle regardless of surrounding sizes', () => {
+    const core = new Core();
+    core.activate();
+
+    const rects = {};
+    for (const name of PAGE_NAMES_ASC) {
+      const { pageWidth, pageHeight } = toPage(Constants.PageSizes[name]);
+      rects[name] = { p1: new Point(0, 0), p2: new Point(pageWidth, pageHeight) };
+      core.scene.addEntity('Polyline', { points: rectPoints(rects[name].p1, rects[name].p2) });
+    }
+
+    for (const name of PAGE_NAMES_ASC) {
+      const { pageWidth, pageHeight } = toPage(Constants.PageSizes[name]);
+      const { p1, p2 } = rects[name];
+
+      const windowArea = new BoundingBox(p1, p2);
+      expect(windowArea.xLength).toBeCloseTo(pageWidth, 5);
+      expect(windowArea.yLength).toBeCloseTo(pageHeight, 5);
+
+      // full exportTo path: WINDOW plotArea must isolate only this rectangle's bounds,
+      // not the full-scene extents (which would be A0 for every iteration)
+      const plotOptions = new PlotOptions(pageWidth, pageHeight);
+      plotOptions.setOption('plotArea', PlotOptions.Area.WINDOW);
+      plotOptions.setOption('windowArea', { point1: p1, point2: p2 });
+      plotOptions.setOption('plotScale', 1);
+      plotOptions.setOption('margin', 0);
+
+      const renderer = new SvgRenderer(pageWidth, pageHeight);
+      const setTransformSpy = jest.spyOn(renderer, 'setTransform');
+      expect(core.canvas.exportTo(renderer, plotOptions)).toBe(true);
+
+      // with plotScale 1 and margin 0, the matrix must map exactly this rectangle's
+      // own bounds onto the page - a full-scene (A0) fallback would produce a very
+      // different translation since every rect shares the same (0,0) origin
+      const matrix = setTransformSpy.mock.calls[0][0];
+      expect(matrix.a).toBe(1);
+      expect(matrix.d).toBe(1);
+      expect(matrix.e).toBeCloseTo(0, 5);
+      expect(matrix.f).toBeCloseTo(0, 5);
+
+      setTransformSpy.mockRestore();
+    }
+  });
+});

package/test/lib/plotOptions.test.js

@@ -130,7 +130,7 @@ test('setOption accepts PlotOptions.Area.DISPLAY for plotArea', () => {
 
 test('setOption throws for an unknown plotArea value', () => {
   const po = new PlotOptions(595, 842);
-  expect(() => po.setOption('plotArea', 'Window')).toThrow('plotArea');
+  expect(() => po.setOption('plotArea', 'Unknown')).toThrow('plotArea');
 });
 
 // ─── setOption — style ────────────────────────────────────────────────────────
@@ -152,6 +152,63 @@ test('setOption throws when style is not a function', () => {
   expect(() => po.setOption('style', 'monochrome')).toThrow('style');
 });
 
+// ─── setOption — margin ───────────────────────────────────────────────────────
+
+test('setOption accepts a valid margin', () => {
+  const po = new PlotOptions(595, 842);
+  po.setOption('margin', 40);
+  expect(po.margin).toBe(40);
+});
+
+test('setOption accepts zero margin', () => {
+  const po = new PlotOptions(595, 842);
+  po.setOption('margin', 0);
+  expect(po.margin).toBe(0);
+});
+
+test('setOption throws for negative margin', () => {
+  const po = new PlotOptions(595, 842);
+  expect(() => po.setOption('margin', -1)).toThrow('margin');
+});
+
+test('setOption throws for non-numeric margin', () => {
+  const po = new PlotOptions(595, 842);
+  expect(() => po.setOption('margin', '40')).toThrow('margin');
+});
+
+test('setOption throws for NaN margin', () => {
+  const po = new PlotOptions(595, 842);
+  expect(() => po.setOption('margin', NaN)).toThrow('margin');
+});
+
+test('setOption throws for Infinity margin', () => {
+  const po = new PlotOptions(595, 842);
+  expect(() => po.setOption('margin', Infinity)).toThrow('margin');
+});
+
+test('setOption throws when margin leaves zero usable width', () => {
+  const po = new PlotOptions(595, 842);
+  // 297.5 * 2 === pageWidth -> usable width would be exactly 0
+  expect(() => po.setOption('margin', 297.5)).toThrow('usable page area');
+});
+
+test('setOption throws when margin leaves zero usable height', () => {
+  const po = new PlotOptions(842, 595);
+  expect(() => po.setOption('margin', 297.5)).toThrow('usable page area');
+});
+
+test('setOption throws when margin exceeds half the narrower page dimension only', () => {
+  const po = new PlotOptions(595, 842);
+  // exceeds half of pageWidth (297.5) but not half of pageHeight (421)
+  expect(() => po.setOption('margin', 300)).toThrow('usable page area');
+});
+
+test('setOption accepts a margin just under half the narrower page dimension', () => {
+  const po = new PlotOptions(595, 842);
+  po.setOption('margin', 297);
+  expect(po.margin).toBe(297);
+});
+
 // ─── setOption — fileType ─────────────────────────────────────────────────────
 
 test('setOption accepts pdf for fileType', () => {

package/test/tools/windowPick.test.js

@@ -0,0 +1,129 @@
+import { Core } from '../../core/core/core.js';
+import { DesignCore } from '../../core/designCore.js';
+import { Point } from '../../core/entities/point.js';
+import { WindowPick } from '../../core/tools/windowPick.js';
+import { expect, jest } from '@jest/globals';
+import { withMockInput } from '../test-helpers/test-helpers.js';
+
+const core = new Core();
+
+// ─── register ────────────────────────────────────────────────────────────────
+
+test('WindowPick.register returns correct command object', () => {
+  const reg = WindowPick.register();
+  expect(reg.command).toBe('WindowPick');
+  expect(reg.shortcut).toBeUndefined();
+  expect(reg.type).toBeUndefined();
+});
+
+// ─── execute ──────────────────────────────────────────────────────────────────
+
+test('WindowPick.execute collects two points and calls executeCommand', async () => {
+  const executeCommandSpy = jest.fn();
+
+  await withMockInput(
+      core.scene,
+      [new Point(0, 0), new Point(10, 10)],
+      async () => {
+        const tool = new WindowPick();
+        await tool.execute();
+      },
+      { extraMethods: { executeCommand: executeCommandSpy } },
+  );
+
+  expect(executeCommandSpy).toHaveBeenCalled();
+});
+
+test('WindowPick.execute returns early when first point is undefined', async () => {
+  const executeCommandSpy = jest.fn();
+
+  await withMockInput(
+      core.scene,
+      [],
+      async () => {
+        const tool = new WindowPick();
+        await tool.execute();
+      },
+      { extraMethods: { executeCommand: executeCommandSpy } },
+  );
+
+  expect(executeCommandSpy).not.toHaveBeenCalled();
+});
+
+test('WindowPick.execute returns early when second point is undefined', async () => {
+  const executeCommandSpy = jest.fn();
+
+  await withMockInput(
+      core.scene,
+      [new Point(0, 0)],
+      async () => {
+        const tool = new WindowPick();
+        await tool.execute();
+      },
+      { extraMethods: { executeCommand: executeCommandSpy } },
+  );
+
+  expect(executeCommandSpy).not.toHaveBeenCalled();
+});
+
+test('WindowPick.execute stores the two collected points', async () => {
+  let capturedTool;
+  const executeCommandSpy = jest.fn();
+
+  await withMockInput(
+      core.scene,
+      [new Point(1, 2), new Point(30, 40)],
+      async () => {
+        capturedTool = new WindowPick();
+        await capturedTool.execute();
+      },
+      { extraMethods: { executeCommand: executeCommandSpy } },
+  );
+
+  expect(capturedTool.points).toHaveLength(2);
+  expect(capturedTool.points[0].x).toBe(1);
+  expect(capturedTool.points[0].y).toBe(2);
+  expect(capturedTool.points[1].x).toBe(30);
+  expect(capturedTool.points[1].y).toBe(40);
+});
+
+// ─── preview ──────────────────────────────────────────────────────────────────
+
+test('WindowPick.preview with one point creates a rectangle polyline preview', () => {
+  const tool = new WindowPick();
+  tool.points.push(new Point(10, 10));
+
+  core.mouse.mouseMoved(50, 50);
+
+  const initialCount = DesignCore.Scene.previewEntities.count();
+
+  tool.preview();
+
+  expect(DesignCore.Scene.previewEntities.count()).toBe(initialCount + 1);
+
+  const tempItem = DesignCore.Scene.previewEntities.get(DesignCore.Scene.previewEntities.count() - 1);
+  expect(tempItem.type).toBe('Polyline');
+  expect(tempItem.points.length).toBe(4);
+});
+
+test('WindowPick.preview with no points does not create a preview', () => {
+  const tool = new WindowPick();
+
+  const initialCount = DesignCore.Scene.previewEntities.count();
+
+  tool.preview();
+
+  expect(DesignCore.Scene.previewEntities.count()).toBe(initialCount);
+});
+
+test('WindowPick.preview with two points does not create another preview', () => {
+  const tool = new WindowPick();
+  tool.points.push(new Point(0, 0));
+  tool.points.push(new Point(10, 10));
+
+  const initialCount = DesignCore.Scene.previewEntities.count();
+
+  tool.preview();
+
+  expect(DesignCore.Scene.previewEntities.count()).toBe(initialCount);
+});