@toolpath/dfm 0.0.0-stage → 0.1.0

package/dist/reach-CfmYU_yQ.d.ts

@@ -0,0 +1,415 @@
+/** The unit a length is shown in. The Engine's meshes are always millimetres. */
+type Units = 'mm' | 'inch';
+
+/**
+ * At or above, above, at or below, below, equal, not equal, or between —
+ * equal meaning within half a percent, since figures are measured, and not
+ * equal anything further off; between from a low end up to, not including, a
+ * high one.
+ */
+type DfmOp = 'gte' | 'gt' | 'lte' | 'lt' | 'eq' | 'ne' | 'between';
+/**
+ * How a figure is read and typed: a length (mm), an area (mm²), an angle
+ * (degrees), a plain ratio, a count, a percentage, yes/no, or — for "any
+ * size" — nothing at all.
+ */
+type DfmQuantity = 'length' | 'area' | 'angle' | 'ratio' | 'count' | 'percent' | 'flag' | 'presence';
+/** A datasheet's `facts.kind`: which family of measurements the Engine took. */
+type FactsKind = 'Hole' | 'Pocket' | 'Boss' | 'Wall' | 'Face' | 'Three' | 'Chamfer' | 'Profile' | 'Dovetail' | 'Tslot';
+interface DfmMetric {
+    key: string;
+    /** As the rule sentence reads it: "L/D", "depth below top". */
+    label: string;
+    /** The heading it is listed under when choosing. */
+    group: string;
+    quantity: DfmQuantity;
+    /** Which way is worse, for a new rule: deep is bad (≥), a tiny corner is bad (≤). */
+    op: DfmOp;
+    /** What a new rule starts at: millimetres and inches kept apart, so both read as round numbers. */
+    start: Record<Units, number>;
+    /** What it means, in a few plain words. */
+    hint: string;
+    /** The kinds of datasheet that report it; every kind when left out. */
+    kinds?: readonly FactsKind[];
+    /**
+     * Where it sits in the datasheet, first found wins: a chamfer keeps its
+     * cutter band under its surface reading (`facts.three.cd`). Left out for a
+     * measure worked out rather than read (see `dfm-flags.ts`).
+     */
+    path?: readonly string[];
+    /** Whether a rule may name a value below zero: a height, or a signed radius. */
+    signed?: true;
+}
+
+/** How a range holds its low end: at or above it, or above it. */
+type RangeLow = 'gte' | 'gt';
+/** How a range holds its high end: below it, or at or below it. */
+type RangeHigh = 'lt' | 'lte';
+interface DfmRule {
+    /** Stable, so a list can key its rows and a feature can name the rule it broke. */
+    id: string;
+    /** Which features: a value from {@link FEATURE_SUBJECTS}. */
+    subject: string;
+    /** What is measured: a key from {@link FEATURE_METRICS}. */
+    metric: string;
+    op: DfmOp;
+    /** Canonical — mm or a ratio. Ignored by a yes/no metric. The low end of a range. */
+    value: number;
+    /** A range's high end. Only a `between` rule has one. */
+    max?: number;
+    /** How a range holds its low end; ≥ where unsaid. Only a `between` rule has one. */
+    lowOp?: RangeLow;
+    /** How a range holds its high end; < where unsaid. Only a `between` rule has one. */
+    highOp?: RangeHigh;
+    /** `#rrggbb`: what the features that break it are painted. */
+    color: string;
+}
+/**
+ * The colours a rule can wear: vivid, and far enough apart in hue and
+ * lightness to tell apart on the part at a glance (no two closer than ΔE 37,
+ * and none within 50 of the selection's blue). Warm first, since most
+ * rules call out trouble; then cool ones for a rule that marks something
+ * good.
+ */
+declare const RULE_COLORS: readonly {
+    name: string;
+    value: string;
+}[];
+/**
+ * Which colour shows where a feature breaks rules of two: the one earliest in
+ * the palette, so red over yellow. Colours from outside it come after, in an
+ * order of their own, so a tie never falls back on the list.
+ */
+declare const compareColors: (a: string, b: string) => number;
+/** The quoting app's two severities, as the colours a rule starts in. */
+declare const CRITICAL_COLOR = "#e5484d";
+declare const WARNING_COLOR = "#ffd60a";
+/**
+ * A rule as one plain line: "Holes with L/D ≥ 8", "Holes with 4 ≤ L/D < 8",
+ * "Any feature with a sharp inside corner", "Undercut T-slots, any size".
+ */
+declare const describeRule: (rule: DfmRule, units: Units) => string;
+/** A new rule for a subject and metric, at the metric's own starting value in the reader's units. */
+declare const makeRule: (subject: string, metricKey: string, units: Units, color?: string) => DfmRule;
+/** Stored rules, the ones that read; null when what is stored is not a list at all. */
+declare const parseRules: (raw: unknown) => DfmRule[] | null;
+
+/**
+ * Where a feature is at its tightest (the datasheet's `pinchPoints`, API
+ * 1.12.1): one disc per stretch of the feature that reaches its minimum
+ * clearance, tightest first and never more than ten.
+ *
+ * As the API defines it, a disc fits in the space the clearance was measured
+ * in and touches the feature's boundary, so a cylinder of its diameter
+ * standing at its centre and spanning the datasheet's `zMin`..`zMax` is
+ * exactly the widest tool that reaches the boundary there. That is what makes
+ * them drawable: each is the tool the feature allows, standing where the
+ * feature stops a larger one.
+ *
+ * The Engine measures each disc to a tolerance (`toleranceBand.atolIgnore`),
+ * which lets it read a little wider than the gap it sits in. The discs here
+ * have that slack taken out (see {@link clearanceFit}), so each is the
+ * clearance itself: in a 2.5 mm corner, a 5 mm disc.
+ *
+ * Empty for the kinds whose clearance is not measured off a single medial
+ * axis (a hole, a facing pass, the undercut and layered kinds), so empty is
+ * "nowhere to point at", never "nowhere is tight".
+ *
+ * Millimetres, in the datasheet's tool frame: x and y across the tool, z up
+ * it.
+ */
+/** One disc: its centre across the tool, and its diameter. */
+interface PinchDisc {
+    x: number;
+    y: number;
+    diameter: number;
+}
+/** A feature's pinch discs, and the band along the tool they stand through. */
+interface FeaturePinch {
+    discs: readonly PinchDisc[];
+    zMin: number;
+    zMax: number;
+    /**
+     * The Engine measured the clearance at one tolerance only, so the slack
+     * could not be taken out: each disc is as measured, the most the clearance
+     * can be.
+     */
+    unresolved?: true;
+}
+/**
+ * The figures a feature's clearance is run back from, as the datasheet has
+ * them: the widest tool that reaches every point (`min` of the cutter band,
+ * which is also its tightest pinch disc) at the strict tolerance, and at the
+ * looser one where the Engine reports it.
+ */
+interface ClearanceFit {
+    /** `facts.cd`, or `facts.three.cd` for a chamfer. */
+    bandPath: string;
+    strict: number;
+    loose?: number;
+    atStrict?: number;
+    atLoose?: number;
+    /**
+     * How much wider, mm, the tolerance lets the widest tool read than the
+     * clearance it fits: what to take off a measured disc. Zero where the
+     * Engine measured at one tolerance only (`resolved` false), or where the
+     * tool does not grow with tolerance (a gap between walls, not a corner).
+     */
+    slack: number;
+    resolved: boolean;
+}
+/** A datasheet's pinch discs, the tolerance taken out of each, or null where it has none to draw. */
+declare const readPinch: (datasheet: unknown) => FeaturePinch | null;
+
+/**
+ * The few numbers of a feature's datasheet that the DFM rules and the
+ * feature details read. All millimetres, as the Engine reports them. Each is
+ * left out where this kind of feature does not report it, rather than sent as
+ * a zero that reads as measured.
+ *
+ * From the quoting app (quoting-ui `server/lib/engine.ts`). A datasheet is
+ * large, so the worker cuts each one down to this before it sends it.
+ */
+interface FeatureSheet {
+    /** The Engine's family for it: `Hole`, `Pocket`, … */
+    kind?: string;
+    /** Along the machining direction, the feature's own bottom and top. */
+    zMin?: number;
+    zMax?: number;
+    /** Its top extended to the stock, which the highest of stands in for the part's top. */
+    extendedZMax?: number;
+    /** The widest cutter that still reaches the tightest corner. */
+    maxTool?: number;
+    diameter?: number;
+    /** For a hole: the full angle of the cone at its bottom, degrees; 180 for a flat bottom. */
+    tipAngle?: number;
+    filletRadius?: number;
+    chamferAngle?: number;
+    /**
+     * For a milled feature with walls: the radius of its tightest inside corner
+     * between walls, as the geometry has it rather than as a tool reaches it —
+     * zero for a sharp one. Half its minimum clearance: see {@link insideCornerRadius}.
+     */
+    cornerRadius?: number;
+    /**
+     * The Engine measured the clearance at one tolerance only, so neither
+     * `cornerRadius` nor `pinchDiameter` could be run back to none: each is as
+     * a tool reads it at that tolerance, the most the clearance can be.
+     */
+    cornerRadiusUnresolved?: true;
+    /** What the clearance was worked out from, so a reader can follow it. See {@link ClearanceFit}. */
+    clearance?: ClearanceFit;
+    /**
+     * A vertical inside corner between its walls with no radius, which no end
+     * mill makes; and where, in the datasheet's tool frame (x, y across the
+     * tool; its `zMin`..`zMax` along it).
+     */
+    sharpCorners?: readonly {
+        x: number;
+        y: number;
+    }[];
+    /**
+     * For a contour surface: the largest tool its shape admits (`facts.toolFit`)
+     * — its diameter, and the radius on its corner, no larger than the
+     * surface's tightest concave curve; half the diameter for a ball.
+     */
+    fitToolDiameter?: number;
+    fitCornerRadius?: number;
+    /** Where the tool fit was read: `facts.toolFit` or `facts.three.toolFit`. */
+    toolFitPath?: string;
+    /** For a contour surface: only a ball end mill can finish it, not a bull nose. */
+    ballOnly?: true;
+    /**
+     * The feature's minimum clearance: the smallest of its pinch discs
+     * (`pinchPoints`), the tolerance taken out, leaving out the zero-wide ones
+     * a sharp corner reports. The widest tool that fits where it is tightest,
+     * and what a milled feature's L/D is taken over.
+     */
+    pinchDiameter?: number;
+    /** How many places are that tight: the pinch discs counted in `pinchDiameter`. */
+    pinchPlaces?: number;
+    /** No cutter fits anywhere in the feature. */
+    noToolFits?: true;
+    /** For a hole the model threads: its thread. */
+    threading?: FeatureThreading;
+}
+/** A modelled thread, from a hole's `facts.threading`. Millimetres. */
+interface FeatureThreading {
+    basicDiameter: number;
+    threadPitch: number;
+}
+/** Feature tag, lower-cased → its sheet. */
+type FeatureSheets = Record<string, FeatureSheet>;
+/** Narrower than this, mm, a pinch disc is a sharp corner, which no tool fits: not a pinch tool. */
+declare const PINCH_TOOL_MM = 0.01;
+/** A feature that is no reading of its faces at all, which the analysis leaves out. */
+declare const isNoReading: (featureType: unknown, datasheet: unknown) => boolean;
+/** One datasheet, cut down to what the rules read. Read loosely: kinds report different fields. */
+declare const featureSheet: (datasheet: unknown) => FeatureSheet;
+
+type Direction = {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+};
+/**
+ * A feature as the Engine's report gives it, cut down to the fields the rules
+ * read. `@toolpath/api`'s `PartFeature` is one, so the package takes no
+ * dependency on the SDK for a type.
+ */
+interface ReportFeature {
+    readonly featureTag: string;
+    readonly featureType: string;
+    readonly machiningDirection: Direction;
+    readonly regionIdxs: readonly number[];
+}
+/** A feature as the DFM rules read it: which it is, what kind, the way it is machined, and its faces. */
+interface DfmFeature {
+    readonly tag: string;
+    readonly featureType: string;
+    readonly machiningDirection: Direction;
+    readonly regionIdxs: readonly number[];
+    /**
+     * What the panels call it, after its type: 1, 2, 3… across the part,
+     * numbered a machining direction at a time, so the features cut one way
+     * run together. Arbitrary otherwise, but steady for one analysis.
+     */
+    readonly number: number;
+}
+/** The report's features, cut down to what the rules read, and numbered by direction. */
+declare const dfmFeatures: (features: readonly ReportFeature[]) => DfmFeature[];
+/** `through_hole` as `Through hole`. The Engine's feature types are open-ended snake case. */
+declare const featureTypeLabel: (featureType: string) => string;
+
+/** What the checks read of the part, beyond its features. */
+interface DfmSources {
+    /** Each feature's measurements, cut down (`feature-sheet.ts`), by lower-cased tag. */
+    sheets: FeatureSheets;
+    /** Each feature's datasheet as the API sent it, by lower-cased tag. */
+    datasheets: Readonly<Record<string, unknown>>;
+    /** Each face's area, mm², by region index. */
+    regionAreas: ReadonlyMap<number, number>;
+}
+/** One rule a feature broke, with the figure that broke it. */
+interface DfmHit {
+    rule: DfmRule;
+    metric: DfmMetric;
+    /** What was measured, canonical. */
+    value: number;
+    /** For an L/D: against a drill's bore rather than the widest cutter. */
+    drilling?: boolean;
+}
+/** One rule and the features that break it. */
+interface RuleResult {
+    rule: DfmRule;
+    /** The required features' tags, as the report spells them: the worst first, the furthest past the rule. */
+    tags: string[];
+    /**
+     * The other readings that break it, worst first: features some other
+     * reading could stand in for, so they are not counted or painted, but a
+     * reader opening the rule should see everything it caught.
+     */
+    otherTags: string[];
+}
+/** The part checked against the rules. */
+interface DfmCheck {
+    /** Lower-cased tag → the rules the feature breaks, in the rules' order. Every feature, required or not. */
+    hitsByTag: ReadonlyMap<string, DfmHit[]>;
+    /** Lower-cased tags of the features a plan cannot do without. */
+    required: ReadonlySet<string>;
+    /** Each rule in order, with the required features that break it. */
+    byRule: RuleResult[];
+    /**
+     * Region → the colour a face is painted alone, and the reading it is painted for. See
+     * {@link unavoidableFaces}, and {@link withSurroundedFaces} for the faces painted with their surroundings.
+     */
+    paintedFaces: ReadonlyMap<number, {
+        tag: string;
+        color: string;
+    }>;
+    /** Lower-cased tag → a contour surface painted whole in its own worst colour. See {@link unavoidableFaces}. */
+    paintedWhole: ReadonlyMap<string, {
+        tag: string;
+        color: string;
+    }>;
+}
+/**
+ * The check with the faces its paint surrounds painted too. A face some
+ * reading cuts clean is left unpainted, but where that face is one of the
+ * feature that paints most of its painted neighbours, it is part of that
+ * feature, cut with it: a through hole in a flagged pocket's wall, say, read
+ * clean as a hole drilled from a floor far below that no plan would drill it
+ * from. Leaving it bare punches a hole in the feature's paint, so it takes
+ * the feature's colour. Where two features paint as many neighbours, the
+ * face takes the worse colour of those it is one of.
+ *
+ * One pass, over the paint as the check left it, so paint never spreads
+ * from a face that was itself only surrounded.
+ */
+declare const withSurroundedFaces: (check: DfmCheck, features: readonly DfmFeature[], adjacency: ReadonlyMap<number, ReadonlySet<number>>) => DfmCheck;
+/**
+ * Checks every feature against every rule. Only the required features count
+ * against a rule: a feature some other reading could stand in for may never
+ * be cut, so flagging it would bury the ones that will be.
+ */
+declare const checkPart: (features: readonly DfmFeature[], sources: DfmSources, rules: readonly DfmRule[]) => DfmCheck;
+
+/**
+ * A feature's reach curve (the datasheet's `reachCurve`, API 1.12.1): how
+ * high the material around a feature stands, by how far out from it.
+ *
+ * As the API defines it: material within `horizontalOffset[i]` of the
+ * feature rises to `verticalOffset[i]` above it. Both lists ascend, the
+ * curve is a step that never falls, and past its last knot it holds. So the
+ * rise comes at the *start* of each run, not at its knot: between two knots
+ * the material could stand anywhere out to the next one, and the next one's
+ * height is the bound — as the tool catalog's sweep reads it
+ * (`@toolpath/tool-support` `heightAt`), so a stack clears here where it
+ * clears there. Offsets
+ * are measured from the feature — zero is the wall of the cut — so material
+ * at offset `d` meets a tool at radius `d` plus the cutter's radius. Each
+ * reading is the worst case over the whole feature, with no direction to it.
+ *
+ * Millimetres throughout.
+ */
+
+interface ReachCurve {
+    /** Outward from the feature's wall, ascending. */
+    offsets: readonly number[];
+    /** How high the material within each offset rises above the feature, ascending. */
+    heights: readonly number[];
+}
+/** A datasheet's reach curve, or null where it has none worth drawing. */
+declare const readReachCurve: (datasheet: unknown) => ReachCurve | null;
+/** Where a knot's run starts, and so the nearest its material may stand: just past the knot before. */
+declare const runStart: ({ offsets }: ReachCurve, index: number) => number;
+/** The tallest the material stands anywhere the curve reaches. */
+declare const peakHeight: ({ heights }: ReachCurve) => number;
+/**
+ * The curve as the drawings show it: whole, where it keeps rising nearly to
+ * its end, and otherwise cut off {@link TAIL_MM} past where it reaches its
+ * full height, the height there held to the cut. `cut` says which, so the
+ * drawing can mark the break.
+ */
+declare const trimmedCurve: (curve: ReachCurve) => {
+    curve: ReachCurve;
+    cut: boolean;
+};
+/** How wide the feature itself is, across the tool, and what that width is. */
+interface FeatureAcross {
+    width: number;
+    /** A hole's bore, or a milled feature's tightest clearance (its smallest pinch disc). */
+    kind: 'diameter' | 'clearance';
+}
+/** The feature as the reach section draws it, left of its wall. */
+interface FeatureProfile {
+    /** Its width, to draw it to scale; null draws it at a set share. */
+    across: FeatureAcross | null;
+    /** Its own depth, top to bottom (`zMax − zMin`), over the same floor the curve stands on. */
+    depth: number | null;
+    /** It runs out through the part, so there is no floor under it. */
+    through: boolean;
+}
+declare const featureProfile: (sheet: FeatureSheet | undefined, featureType: string) => FeatureProfile;
+
+export { featureTypeLabel as A, isNoReading as B, CRITICAL_COLOR as C, type DfmRule as D, makeRule as E, type FeatureSheets as F, parseRules as G, peakHeight as H, readPinch as I, readReachCurve as J, runStart as K, trimmedCurve as L, withSurroundedFaces as M, PINCH_TOOL_MM as P, type ReachCurve as R, type Units as U, WARNING_COLOR as W, type DfmCheck as a, type DfmFeature as b, type FeatureProfile as c, type DfmHit as d, type FeatureSheet as e, type ClearanceFit as f, type DfmMetric as g, type DfmOp as h, type DfmQuantity as i, type DfmSources as j, type FactsKind as k, type FeatureAcross as l, type FeaturePinch as m, type FeatureThreading as n, type PinchDisc as o, RULE_COLORS as p, type RangeHigh as q, type RangeLow as r, type ReportFeature as s, type RuleResult as t, checkPart as u, compareColors as v, describeRule as w, dfmFeatures as x, featureProfile as y, featureSheet as z };

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@toolpath/dfm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Toolpath DFM rules: the rule list component, the rules and the part checker",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toolpath/ui-packages.git",
+    "directory": "packages/dfm"
+  },
+  "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"
+    },
+    "./model": {
+      "types": "./dist/model/index.d.ts",
+      "import": "./dist/model/index.js"
+    },
+    "./dfm.css": "./dfm.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "dfm.css",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "dependencies": {
+    "@phosphor-icons/react": "2.1.10",
+    "@toolpath/tool-support": "^0.6.0"
+  },
+  "peerDependencies": {
+    "@toolpath/ui": "^1.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^7.0.1",
+    "@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.8",
+    "react-dom": "19.2.8",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10",
+    "@toolpath/api": "^0.6.0",
+    "@toolpath/ui": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/model/index.ts --format esm --dts --clean --external react --external react-dom --external @toolpath/ui",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }