@toolpath/tool-drawing 0.1.0

package/dist/sheet-D0LSO7qP.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Stage 2 of the drawing: where the millimetres land on the sheet.
+ *
+ * Pure arithmetic over a content extent and a measured box. No React, no DOM,
+ * no SVG — {@link frameFor} returns numbers and two mapping functions, and the
+ * renderer does nothing but place things with them.
+ *
+ * ## The inversion
+ *
+ * **The frame is content plus margins, and the scale absorbs the panel's
+ * shape.** Never the other way round. The component this replaces derived the
+ * *frame* from the panel's aspect ratio while pinning the scale to the tool's
+ * length, so a ⌀1 drill 58 mm long got a 312 mm-wide sheet and then had
+ * `preserveAspectRatio` shrink it to fit — about 85% of the panel rendered
+ * empty. Here `scale` is the smaller of the two px-per-mm ratios that fit the
+ * content in the box, and the viewBox describes the content and its margins.
+ * A wide panel now buys a bigger drawing rather than a wider sheet.
+ *
+ * ## The contract with the renderer
+ *
+ * The `<svg>` must carry `preserveAspectRatio="xMidYMid meet"`, which is the
+ * default. That is not decoration: `meet` fits the viewBox by the smaller of
+ * its own two ratios, and the algebra below chooses `scale` so that the
+ * binding ratio is exactly `scale`. The reported number and the rendered
+ * number are then the same, which is what lets {@link Frame.fontSize} be
+ * trusted. Under `preserveAspectRatio="none"` the drawing would stretch and
+ * `scale` would be a lie on one axis.
+ *
+ * ## Orientation
+ *
+ * {@link Frame.toX} and {@link Frame.toY} are the **only** things in this
+ * package that know which way the tool axis runs. Everything downstream — the
+ * silhouette, the joins, the centreline, the dimensions, the clearance overlay
+ * — is written once against them and is orientation-agnostic. Orientation
+ * being baked into a pair of closures inside the render pass, and assumed by
+ * every renderer below them, is the reason the old component could not be
+ * patched into shape.
+ */
+/** What framing needs from an outline: how far it reaches, in millimetres. */
+interface Extent {
+    /** The tallest point drawn, above the tip. */
+    readonly height: number;
+    /** The widest radius drawn. The drawing is mirrored, so it spans twice this. */
+    readonly radius: number;
+}
+/** A measured panel, in CSS pixels. Zero on the server and before first paint. */
+interface Box {
+    readonly width: number;
+    readonly height: number;
+}
+type Orientation = 'vertical' | 'horizontal';
+interface Frame {
+    readonly orientation: Orientation;
+    /** Pixels per millimetre, as the drawing will actually render. */
+    readonly scale: number;
+    /** `minX minY width height`, in millimetres: the content and its margins. */
+    readonly viewBox: string;
+    /** A point's horizontal place in viewBox coordinates, from radius and height. */
+    readonly toX: (r: number, z: number) => number;
+    /** A point's vertical place in viewBox coordinates, from radius and height. */
+    readonly toY: (r: number, z: number) => number;
+    /** Type size in **millimetres**, back-derived from a target in pixels. */
+    readonly fontSize: number;
+    /**
+     * The chrome actually applied, in pixels — what was asked for, or less.
+     *
+     * The frame reports what it did with the request, the way it reports the
+     * scale it settled on. A caller placing something in the margin has to place
+     * it against the room the margin really has: ask for more than
+     * {@link MOST_OF_A_PANEL} and the request is scaled back rather than
+     * granted, and anything drawn at the full request would then hang off the
+     * sheet.
+     */
+    readonly padding: Padding;
+}
+/**
+ * Room for chrome around the content, in **pixels**, flank by flank.
+ *
+ * **Pixels rather than millimetres because it is chrome**: it should not grow
+ * because the tool is long, and it has to stay independent of `scale` or the
+ * arithmetic closes a loop — more padding shrinks the scale, which changes the
+ * type size, which changes the band widths, which changes the padding.
+ *
+ * **Named by flank rather than by side of the screen.** `minus` is the `-r`
+ * flank and `plus` the `+r` flank; which of them is the screen's left, right,
+ * top or bottom is `toX`/`toY`'s business and nothing else's.
+ *
+ * A plain number is the same room on every side, and that is what a drawing
+ * with no dimensions on it wants.
+ */
+interface Padding {
+    /** Outside the `-r` flank. */
+    readonly minus: number;
+    /** Outside the `+r` flank. */
+    readonly plus: number;
+    /** Past each end of the tool, along its axis. */
+    readonly along: number;
+}
+interface FrameOptions {
+    /**
+     * Room for chrome around the content, in **pixels** — dimension bands, the
+     * arrowheads, the figures.
+     *
+     * **Widened from a plain number in phase 4, deliberately.** The dimension
+     * bands are genuinely asymmetric: with figures on both flanks each side
+     * needs as much room as its own bands take, and those differ. Forcing that
+     * through one scalar would mean padding both flanks by the wider of the two
+     * and throwing away the difference — real drawing area, on the axis where a
+     * long thin tool has least of it. A number still means what it always did.
+     */
+    readonly padding?: number | Partial<Padding>;
+    /**
+     * The box to frame against before the panel has been measured. A
+     * `ResizeObserver` reports nothing on the server or on first paint, and
+     * framing against a zero box would paint at the stack's own width and then
+     * visibly jump. This is a plain landscape sheet instead.
+     */
+    readonly defaultBox?: Box;
+}
+/**
+ * The type size a drawing in this box is set in, in **pixels**.
+ *
+ * Exported because the dimension model has to know it before there is a frame:
+ * its band widths are measured in type, the frame's padding is the total of
+ * those bands, and a frame cannot be built until the padding is known. It
+ * depends only on the panel, so there is no circle to close.
+ */
+declare const typeSizeFor: (box: Box, options?: FrameOptions) => number;
+/**
+ * Which way the tool axis runs in this box: along its long side.
+ *
+ * Exported for the same reason as {@link typeSizeFor} — the dimension model
+ * has to size its bands before there is a frame, and one of its measures
+ * depends on which way the type runs relative to the axis. It reads the panel
+ * only, so there is no circle to close.
+ */
+declare const orientationFor: (box: Box, options?: FrameOptions) => Orientation;
+declare const frameFor: (outline: Extent, box: Box, options?: FrameOptions) => Frame;
+
+/**
+ * The sheet the tool is drawn on, and the ink it is drawn in.
+ *
+ * **Hard colours rather than the application's ramp** (Paul, 2026-09-01): a
+ * drawing is a drawing, and a "light grey" written as a zinc utility comes out
+ * dark under the flipped ramp. So the sheet, the linework and the two shades a
+ * tool has — gold flutes, steel body — are stated here.
+ *
+ * **One set per theme** (Paul, 2026-09-01: "2d tool visualization can't have
+ * the white background in dark mode — make it just barely lighter than any of
+ * the other backgrounds"). A white sheet in a dark application is a torch. In
+ * dark it is a shade above the card it sits on, and the ink turns over with
+ * it: light lines on a dark ground rather than dark lines nobody can see.
+ *
+ * Stated as literals in this package for a second reason as well: it has no
+ * Tailwind, no design-token import and no access to the consumer's ramp, so
+ * every colour the drawing uses has to be a colour rather than a class name.
+ */
+declare const SHEETS: {
+    readonly light: {
+        readonly ground: "#ffffff";
+        readonly ink: "#3f4650";
+        readonly centre: "#15181c";
+        readonly dimension: "#606a76";
+        readonly body: "#c4c8ce";
+        readonly flutes: "#e6bf59";
+        readonly holder: "#9aa2ad";
+        readonly connection: "#78818d";
+    };
+    readonly dark: {
+        readonly ground: "#22252b";
+        readonly ink: "#c7cdd6";
+        readonly centre: "#e8ebef";
+        readonly dimension: "#8d97a4";
+        readonly body: "#5b626c";
+        readonly flutes: "#c9a44b";
+        readonly holder: "#474d57";
+        readonly connection: "#3a4048";
+    };
+};
+type Theme = keyof typeof SHEETS;
+type Sheet = (typeof SHEETS)[Theme];
+
+export { type Box as B, type Extent as E, type Frame as F, type Orientation as O, type Padding as P, type Sheet as S, type Theme as T, type FrameOptions as a, SHEETS as b, frameFor as f, orientationFor as o, typeSizeFor as t };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@toolpath/tool-drawing",
+  "version": "0.1.0",
+  "description": "2D elevation drawing of a cutting tool and its holder",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toolpath/ui-packages.git",
+    "directory": "packages/tool-drawing"
+  },
+  "homepage": "https://developers.toolpath.com",
+  "bugs": {
+    "url": "https://github.com/toolpath/ui-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./geometry": {
+      "types": "./dist/geometry/index.d.ts",
+      "import": "./dist/geometry/index.js"
+    },
+    "./clearance": {
+      "types": "./dist/clearance/index.d.ts",
+      "import": "./dist/clearance/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts src/geometry/index.ts src/clearance/index.ts --format esm --dts --clean --external react --external react-dom",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "24.10.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^30.0.1",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  }
+}