@toolpath/tool-drawing 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+import { ViewerAssembly, Outline } from './geometry/index.js';
+export { Provenance, ViewerHolder, ViewerTool } from './geometry/index.js';
+import { F as Frame, S as Sheet, T as Theme, P as Padding } from './sheet-D0LSO7qP.js';
+export { B as Box, E as Extent, a as FrameOptions, O as Orientation, b as SHEETS, f as frameFor, o as orientationFor, t as typeSizeFor } from './sheet-D0LSO7qP.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * What a drawing of this tool dimensions, and where each dimension goes.
+ *
+ * **Pure, and here rather than in the component**, because where a dimension
+ * line sits is arithmetic: which ones apply to this tool, what each one
+ * measures, and — the part a component would get wrong quietly — which lane
+ * each length runs in so that no two lines cross. The drawing turns these into
+ * SVG and nothing else.
+ *
+ * The space is the outline's own: millimetres, `z` above the tip, `r` from the
+ * axis. Every length is measured **from the tip**, which is where a machinist
+ * measures from and where every rule in the sheet measures from.
+ *
+ * Only stated numbers are dimensioned. A drawing that carries a figure the
+ * vendor never published is worse than one that carries fewer — the note under
+ * the drawing already names what was assumed, and a dimension line looks like a
+ * measurement whatever the note says.
+ *
+ * ## Sides are `minus` and `plus`, not `left` and `right`
+ *
+ * This model was written for a drawing that only ran vertically, where the two
+ * flanks of the tool were reliably the left and right of the screen. They are
+ * not any more: the frame lays a tool along whichever axis its panel is longer
+ * on, so the `-r` flank is the screen's left in one orientation and its top in
+ * the other. The names say which flank rather than where it lands, because the
+ * where is `toX`/`toY`'s alone.
+ */
+/** A length along the axis, drawn beside the stack. */
+interface LengthDimension {
+    readonly code: string;
+    /** From the tip, in millimetres — always 0 for now, kept for a dimension that is not. */
+    readonly from: number;
+    readonly to: number;
+    /**
+     * Which line out from the stack this one runs in, 0 nearest.
+     *
+     * Shortest innermost, so the lines nest instead of crossing — the rule a
+     * drafting sheet follows and the reason this is worked out rather than
+     * listed in a fixed order.
+     */
+    readonly lane: number;
+}
+/** A width across the axis, drawn at its own height. */
+interface WidthDimension {
+    readonly code: string;
+    /** Half-width, in millimetres: the dimension runs from `-radius` to `+radius`. */
+    readonly radius: number;
+    /** Where up the tool it is measured, in millimetres above the tip. */
+    readonly at: number;
+}
+/**
+ * An angle called out with a leader rather than measured between two lines.
+ *
+ * **A drill is its point** (Paul, 2026-09-01: "shouldn't a 2d rep of a drill be
+ * showing me a tip angle?"). On a ⌀1 drill the cone is three tenths of a
+ * millimetre tall — drawn to scale it is invisible, and the number is the only
+ * way the drawing says 140° rather than 118°.
+ */
+interface AngleDimension {
+    readonly code: string;
+    readonly degrees: number;
+    /** Where the leader points: a radius from the axis and a height above the tip. */
+    readonly at: {
+        readonly r: number;
+        readonly z: number;
+    };
+}
+interface ToolDimensions {
+    readonly lengths: ReadonlyArray<LengthDimension>;
+    readonly widths: ReadonlyArray<WidthDimension>;
+    readonly angles: ReadonlyArray<AngleDimension>;
+    /** The corner radius, called out on the corner rather than dimensioned across it. */
+    readonly cornerRadius: number | null;
+}
+/**
+ * The dimensions for one assembly.
+ *
+ * With a holder, the tool's overall length is left off: most of the shank is
+ * inside the holder and a line to a face nobody can see reads as a mistake.
+ * What replaces it is the number the holder brings — how far the tool stands
+ * out of it.
+ */
+declare const dimensionsFor: (assembly: ViewerAssembly) => ToolDimensions;
+declare const dimensionLabel: (code: string) => string;
+/**
+ * How a length is written out.
+ *
+ * A function rather than a unit, because a unit system is the application's:
+ * this package has no opinion on whether a shop reads millimetres or inches,
+ * and owning one would mean owning its rounding too. Millimetres in, a string
+ * out; the default is only so the package draws something on its own.
+ */
+type FormatLength = (millimetres: number) => string;
+declare const formatMillimetres: FormatLength;
+/** One label's box on the drawing, before anything has been moved. */
+interface LabelBox {
+    readonly key: string;
+    /** The inboard edge across the axis, and how far the box reaches outward. */
+    readonly across: number;
+    readonly width: number;
+    /** The end nearest the tip, and how far the box reaches along the axis. */
+    readonly along: number;
+    readonly height: number;
+}
+/**
+ * The same labels, moved apart until none covers another.
+ *
+ * **Because a dimension is only worth drawing if it can be read** (Paul,
+ * 2026-09-01). A tool 50 mm long with 4 mm of flute puts its flute length, its
+ * relief and its cutting diameter inside the bottom tenth of the drawing, and
+ * three figures land on each other however carefully each one is placed. Each
+ * label carries a box, so the boxes can be stacked: the one nearest the tip
+ * keeps its place, and anything that would cover it moves **away from the
+ * tip**, which is where the drawing has room.
+ *
+ * Pure arithmetic over rectangles — no measuring of text and no reading of the
+ * DOM, so it runs the same on a server as in a browser.
+ *
+ * **Along the axis, not up the screen.** The original moved a clash "up",
+ * which was the same direction only because the tool was always drawn
+ * standing. Away from the tip is what that meant, and it is what holds when
+ * the tool is laid on its side.
+ */
+declare const stackLabels: (boxes: ReadonlyArray<LabelBox>, gap?: number, 
+/**
+ * Boxes that cannot move: the drawing's own lines, so a figure rises clear
+ * of an extension line rather than sitting on it (Paul, 2026-09-01 — the
+ * figures moved in beside their own lanes, and the lines outboard of them
+ * cross those bands).
+ */
+fixed?: ReadonlyArray<LabelBox>) => Map<string, number>;
+/**
+ * Where every figure on the drawing stands.
+ *
+ * **Each figure beside its own line, in the band just outboard of it** (Paul,
+ * 2026-09-01: "I'd love to put SFDM, LCF and shoulder dia closer to the part —
+ * like, inside the below holder and OAL lines"). One column in the far margin
+ * put the number for a dimension at the tool's edge as far from it as the
+ * number for the overall length, and the eye has to travel the width of the
+ * sheet to pair them up. So the margin is a series of bands: the widths sit in
+ * the first, just past their arrows, and each length's figure sits in the band
+ * outboard of its own lane.
+ *
+ * A band is only as wide as the widest figure in it, because the room it takes
+ * comes out of the tool.
+ */
+/** Which flank of the tool a figure stands off. */
+type Side = 'minus' | 'plus';
+/** The type a figure is set in, given the drawing's own size. */
+declare const figureType: (fontSize: number) => number;
+/** One figure, and the band it stands in. */
+interface DimensionFigure {
+    readonly code: string;
+    readonly side: Side;
+    /** 0 is the band nearest the tool — the widths'; band `i + 1` is outboard of lane `i`. */
+    readonly band: number;
+    /** The lane this figure's dimension runs in on its own side, or null for a width. */
+    readonly lane: number | null;
+    readonly lines: ReadonlyArray<string>;
+    /** How far the figure reaches perpendicular to the tool axis. Bands are sized by this. */
+    readonly across: number;
+    /** How far it reaches parallel to the tool axis. The stacker moves figures along this. */
+    readonly along: number;
+}
+/**
+ * How tall a block of this many lines is, set at that type size.
+ *
+ * The renderer sets type at {@link figureType} and leads it at 1.15, with half
+ * a line of padding above and below; this is that sum, and the two have to
+ * agree or a figure's box is not the size of the figure in it.
+ */
+declare const figureHeight: (lines: number, type: number) => number;
+interface DimensionLayout {
+    readonly figures: ReadonlyArray<DimensionFigure>;
+    /** Per side, the width of every band, nearest the tool first. */
+    readonly bands: Readonly<Record<Side, ReadonlyArray<number>>>;
+}
+/** The room a side's bands take, measured out from the edge of the stack. */
+interface BandRoom {
+    /** How far the width dimensions' arrows reach past the tool. */
+    readonly arrow: number;
+    /** The clearance between a band and the line beside it. */
+    readonly gap: number;
+}
+/** Where a band's inboard edge is: the offset a figure in it reads outward from. */
+declare const bandOffset: (bands: ReadonlyArray<number>, band: number, room: BandRoom) => number;
+/** Where a lane's line runs: just outboard of the band that carries its figure. */
+declare const laneOffset: (bands: ReadonlyArray<number>, lane: number, room: BandRoom) => number;
+/** Everything one side needs, out to the far edge of its last band. */
+declare const bandRoom: (bands: ReadonlyArray<number>, room: BandRoom) => number;
+/**
+ * Every figure, on the side and in the band it belongs to.
+ *
+ * The sides alternate — lengths by lane, widths by their own order — so
+ * neither margin runs away with the whole drawing while the other stands
+ * empty. Where the drawing has something beside it, everything stays on the
+ * one flank.
+ */
+declare const dimensionLayout: (model: ToolDimensions, format: FormatLength, fontSize: number, sides?: "one" | "both", 
+/**
+ * **Whether horizontal text runs parallel to the tool axis.**
+ *
+ * The one fact about the drawing's orientation that this model cannot do
+ * without, and it is here rather than in the renderer so that it is stated
+ * once, in a pure function, with a test on it.
+ *
+ * Everything else in this package is orientation-agnostic because a
+ * millimetre is a millimetre whichever way the axis runs. Type is the
+ * exception: **text does not rotate.** A figure two lines deep and twelve
+ * characters wide is wide on the screen either way, so when the tool is laid
+ * along the screen's width that figure reaches mostly *along* the tool, and
+ * when the tool stands up it reaches *across* it. The bands are sized on the
+ * across measure, so which of the two the type contributes decides how much
+ * room the margins take — and getting it backwards pads the wrong axis by a
+ * factor of about five.
+ */
+textAlongAxis?: boolean) => DimensionLayout;
+
+/**
+ * What `<ToolDrawing>` hands the things drawn inside it.
+ *
+ * **A child cannot work this out for itself, and should not try.** The panel is
+ * measured by a `ResizeObserver` on an `<svg>` the consumer never holds, and
+ * the chrome the dimension bands take is settled from that measurement — so a
+ * child that wanted to draw in the drawing's own coordinates had no way to
+ * learn them. The one consumer that needed them ended up re-deriving the frame
+ * from the same inputs and keeping a lockstep test to catch the drift, which is
+ * a workaround for a hole in this component's surface rather than a design.
+ *
+ * So the frame is published to the subtree instead. `frame` carries the scale,
+ * the viewBox and the two mapping functions; `outline` is what was drawn, for a
+ * child that needs the extent; `sheet` is the ink, so an overlay draws in the
+ * same palette without being told the theme twice.
+ */
+interface DrawingContext {
+    readonly frame: Frame;
+    readonly outline: Outline;
+    readonly sheet: Sheet;
+}
+/**
+ * The frame the surrounding `<ToolDrawing>` settled on, or `null` outside one.
+ *
+ * Null rather than throwing, because a caller may legitimately pass the frame
+ * explicitly — a test framing a fixture, or a drawing composed by hand — and
+ * the props stay the override.
+ */
+declare const useDrawingContext: () => DrawingContext | null;
+
+/**
+ * The assembly, drawn.
+ *
+ * A side elevation from stated dimensions, fitted to the stack so the assembly
+ * fills the panel. Nothing here measures or scales: {@link frameFor} settled
+ * all of that, and this places what it decided.
+ *
+ * **Outlined, not blocked in** (Paul, 2026-09-01, against the drawings in the
+ * geometry write-up): a drawing of a tool is a silhouette with its sections
+ * shaded lightly, so a dimension line that crosses it stays readable.
+ *
+ * **Every line is solid**: flutes pale yellow, shank one light grey whatever
+ * its provenance, the holder grey up to the spindle connection, which is
+ * darker. What was derived or assumed is on the element as `data-provenance`,
+ * and named in the note under the drawing.
+ */
+interface ToolDrawingProps {
+    readonly assembly: ViewerAssembly;
+    /**
+     * The sheet to draw on. A package cannot reach the application's theme hook,
+     * so the application passes its own; dark is the default because the sheet
+     * that needed stating was the dark one.
+     */
+    readonly theme?: Theme;
+    /** The name over the drawing. Falls back to the tool's own label. */
+    readonly caption?: string;
+    /**
+     * Draw the dimensions: every stated length and width, on the tool.
+     *
+     * Off by default, because the drawing is also used small — on a card beside
+     * a list, where a dimension line is noise. The panel that has room turns it
+     * on (Paul, 2026-09-01).
+     */
+    readonly dimensions?: boolean;
+    /**
+     * Which flanks the dimension lanes may use.
+     *
+     * **Both, wherever both are free** (Paul, 2026-09-01): four lengths stacked
+     * down one side push the tool into the other half of the panel and read as a
+     * ladder. Where the drawing has something beside it — a feature section —
+     * the far flank belongs to that and the lanes stay on one.
+     */
+    readonly dimensionSides?: 'one' | 'both';
+    /**
+     * How a length is written out. Millimetres in, a string out.
+     *
+     * The application's, because the unit a shop reads in is the application's
+     * and owning one would mean owning its rounding too.
+     */
+    readonly formatLength?: FormatLength;
+    /**
+     * Extra room for chrome around the drawing, in pixels, on top of whatever
+     * the dimension bands ask for.
+     *
+     * Per flank where the caller needs it asymmetrically — drawing a feature
+     * section beside the tool means reserving the `plus` flank for it, and the
+     * overlay draws in exactly the room reserved.
+     */
+    readonly padding?: number | Partial<Padding>;
+    /**
+     * What the sweep found fouling the material, as data.
+     *
+     * The verdict itself is not this package's: whether an assembly clears is
+     * answered by the caller's own engine, for a dozen callers that draw
+     * nothing. This is that answer's picture — the sections it names are painted
+     * as struck rather than as metal.
+     *
+     * **Matched by height as well as by part**, because one part can emit
+     * several segments: a holder's stated body and the diameter carried up above
+     * it are both `body`, and only one of them may be in the material.
+     */
+    readonly collisions?: ReadonlyArray<{
+        readonly part: string;
+        readonly height: number;
+    }>;
+    /**
+     * The clearance verdict, for the caption: whether it cleared, and a sentence
+     * saying by how much. `@toolpath/tool-drawing/clearance` writes the sentence.
+     */
+    readonly verdict?: {
+        readonly clears: boolean;
+        readonly note?: string | null;
+    } | null;
+    /**
+     * Drawn inside the sheet, over the tool: the clearance overlay, or anything
+     * else the caller wants in the drawing's own coordinates.
+     *
+     * A child rather than a prop of its own, so this module never imports the
+     * overlay and a consumer that does not draw one never loads it. The frame,
+     * the outline and the sheet reach it through context — see
+     * `drawing-context.tsx` for why a child cannot work them out for itself.
+     */
+    readonly children?: ReactNode;
+    readonly className?: string;
+}
+declare const ToolDrawing: ({ assembly, theme, caption, dimensions, dimensionSides, formatLength, padding, collisions, verdict, children, className, }: ToolDrawingProps) => react.JSX.Element;
+
+export { type AngleDimension, type BandRoom, type DimensionFigure, type DimensionLayout, type DrawingContext, type FormatLength, Frame, type LabelBox, type LengthDimension, Padding, Sheet, type Side, Theme, type ToolDimensions, ToolDrawing, type ToolDrawingProps, ViewerAssembly, type WidthDimension, bandOffset, bandRoom, dimensionLabel, dimensionLayout, dimensionsFor, figureHeight, figureType, formatMillimetres, laneOffset, stackLabels, useDrawingContext };