@tscircuit/props 0.0.618 → 0.0.619

package/lib/common/cadModel.ts

@@ -38,6 +38,27 @@ export interface CadModelBase {
     y: number | string
     z: number | string
   }
+  /**
+   * Axis-aligned extent of the model measured in its own coordinate frame, the
+   * same frame as `modelOriginPosition`.
+   *
+   * `size` gives the extent but not where the box sits relative to the model
+   * origin, and the box is generally not centered on it, so `size` alone cannot
+   * say how much of the part is above the board. Since `modelOriginPosition` is
+   * the point placed on the board surface, these bounds supply the missing
+   * term. `modelBoardNormalDirection` names the axis (default `z+`): for a
+   * positive normal the outward reach is `max[axis] - origin[axis]`, and for a
+   * negative one it is `origin[axis] - min[axis]`.
+   *
+   * These are the model's own bounds, before `modelUnitToMmScale` or any
+   * object-fit scaling is applied.
+   *
+   * Whatever generates a part file already measures this to produce `size`.
+   */
+  modelBounds?: {
+    min: { x: number | string; y: number | string; z: number | string }
+    max: { x: number | string; y: number | string; z: number | string }
+  }
   size?: { x: number | string; y: number | string; z: number | string }
   modelUnitToMmScale?: Distance
   modelBoardNormalDirection?: CadModelAxisDirection
@@ -51,6 +72,7 @@ export const cadModelBase = z.object({
   rotationOffset: z.number().or(rotationPoint3).optional(),
   positionOffset: point3.optional(),
   modelOriginPosition: point3.optional(),
+  modelBounds: z.object({ min: point3, max: point3 }).optional(),
   size: point3.optional(),
   modelUnitToMmScale: distance.optional(),
   modelBoardNormalDirection: cadModelAxisDirection.optional(),

package/lib/components/footprint.ts

@@ -81,6 +81,26 @@ export interface FootprintProps {
    * makes the distinction easy to miss.
    */
   insertionDirection?: FootprintInsertionDirection
+  /**
+   * Direction the part's enclosure opening faces, named the same way as
+   * `insertionDirection` and in the same unrotated part frame.
+   *
+   * These are two different physical facts and a part may need both. A
+   * side-actuated switch is *installed* from above and *actuated* from the side:
+   * its aperture must pierce a side wall, while nothing is ever inserted into
+   * it. Reusing `insertionDirection` for that would either put the opening on
+   * the wrong face or overload a field documented as "the side exposing the
+   * receptacle where the cable is attached".
+   *
+   * Like `insertionDirection`, this is a property of the part, authored without
+   * regard to placement: rotating or flipping the component rotates it too, and
+   * `pcb_component.cutout_aperture_direction` reports the result in board
+   * coordinates.
+   *
+   * When absent, the aperture falls back to `insertionDirection`, which is
+   * correct for every connector -- a cable enters through the opening it needs.
+   */
+  cutoutApertureDirection?: FootprintInsertionDirection
 }
 
 export const footprintProps = z.object({
@@ -94,6 +114,11 @@ export const footprintProps = z.object({
     .describe(
       "Direction a cable or mating part is attached from, named for the side of the footprint it approaches from, in its unrotated orientation.",
     ),
+  cutoutApertureDirection: footprintInsertionDirection
+    .optional()
+    .describe(
+      "Direction the part's enclosure opening faces, in its unrotated orientation. Distinct from insertionDirection: a side-actuated switch is installed from above and actuated from the side. Falls back to insertionDirection when absent.",
+    ),
 })
 
 export type FootprintPropsInput = z.input<typeof footprintProps>

package/lib/enclosure/cutout-aperture.ts

@@ -19,30 +19,91 @@ export type EnclosureCutoutApertureShape = CommonShapeProps["shape"]
  * Describes the nominal enclosure opening required by a component.
  *
  * Numeric values are interpreted as mm.
+ *
+ * ## Frame of reference
+ *
+ * An aperture is authored around the owning part's interaction axis, derived
+ * from its footprint `cutoutApertureDirection` or `insertionDirection`. On a
+ * side opening, `height` is board Z, `width` is perpendicular to that axis in
+ * the board plane, and `depth` follows the axis inboard. On the lid or floor,
+ * width and height rotate in-plane with the footprint and depth is vertical.
+ *
+ * The enclosure face is resolved later from where the transformed axis first
+ * intersects the box; it supplies a material plane, not the aperture's original
+ * coordinate frame.
  */
-export interface PillEnclosureCutoutApertureProps extends PillShapeProps {
+export interface CutoutApertureProps {
   /** Additional clearance around the nominal opening. */
   margin?: Distance
+  /**
+   * Move the opening's **center** across the face it pierces, along the same two
+   * axes its `width` and `height` are measured in. Both may be negative.
+   *
+   * Sharing a frame with the dimensions is the point. These replace
+   * `zExtentAboveBoard`, which only made sense on the four walls: on the lid and
+   * the floor an opening does not move in Z at all, so a "Z extent" had no
+   * meaning there.
+   *
+   * Zero means "wherever the part puts it", which is usually right. On a side
+   * face the opening is centred on the part's body above the board, taken from
+   * the model's measured bounds, so it lines up with the connector without
+   * anyone computing a height. On the lid or the floor it is centred on the
+   * part's own position, and both offsets turn with the part.
+   *
+   * `heightDimensionOffset` runs **outward** from the mounting surface on a side
+   * face -- up for a top-mounted part, down for a bottom-mounted one -- so, like
+   * the default it shifts, it describes the part rather than where the part was
+   * placed. A negative value pulls the opening back toward and past the board,
+   * which is what a cable jacket fatter than its connector needs; the binding
+   * constraint is that the opening must not cut into the floor.
+   */
+  widthDimensionOffset?: Distance
+  /** See `widthDimensionOffset`. */
+  heightDimensionOffset?: Distance
+  /**
+   * How far the cutting tool continues inboard along the part's interaction
+   * axis, so the lid lip or other material behind the wall cannot obstruct it.
+   * On a side opening this axis may be oblique to X/Y; on the lid or floor it is
+   * vertical. The profile is cut as authored and never capped, so an explicitly
+   * excessive depth can reach the shell on the far side.
+   *
+   * Usually unnecessary: side depth is derived from the rotated CAD-body/PCB
+   * envelope. Horizontal depth uses the model's measured reach from the board
+   * and converts it to the cavity span beyond the plate's inner surface; where
+   * bounds are absent, `cadModel.size.z` is a less accurate fallback because it
+   * can include pins and through-board geometry.
+   *
+   * Set this where that envelope is wrong for the purpose -- for example a
+   * tapered body -- or where a part has no CAD model.
+   */
+  depth?: Distance
 }
 
-export interface RectEnclosureCutoutApertureProps extends RectShapeProps {
-  /** Additional clearance around the nominal opening. */
-  margin?: Distance
-}
+export interface PillEnclosureCutoutApertureProps
+  extends PillShapeProps,
+    CutoutApertureProps {}
 
-export interface CircleEnclosureCutoutApertureProps extends CircleShapeProps {
-  /** Additional clearance around the nominal opening. */
-  margin?: Distance
-}
+export interface RectEnclosureCutoutApertureProps
+  extends RectShapeProps,
+    CutoutApertureProps {}
+
+export interface CircleEnclosureCutoutApertureProps
+  extends CircleShapeProps,
+    CutoutApertureProps {}
 
 export type EnclosureCutoutApertureProps =
   | PillEnclosureCutoutApertureProps
   | RectEnclosureCutoutApertureProps
   | CircleEnclosureCutoutApertureProps
 
-const apertureOnlyProps = {
+export const cutoutApertureBaseProps = z.object({
   margin: distance.optional(),
-}
+  widthDimensionOffset: distance.optional(),
+  heightDimensionOffset: distance.optional(),
+  depth: distance.optional(),
+})
+
+const apertureOnlyProps = cutoutApertureBaseProps.shape
 
 export const enclosureCutoutApertureProps = z.discriminatedUnion("shape", [
   pillShapeProps.extend(apertureOnlyProps),
@@ -50,10 +111,11 @@ export const enclosureCutoutApertureProps = z.discriminatedUnion("shape", [
   circleShapeProps.extend(apertureOnlyProps),
 ])
 
-type InferredEnclosureCutoutApertureProps = z.input<
+export type ParsedEnclosureCutoutApertureProps = z.output<
   typeof enclosureCutoutApertureProps
 >
-export type ParsedEnclosureCutoutApertureProps = z.output<
+
+type InferredEnclosureCutoutApertureProps = z.input<
   typeof enclosureCutoutApertureProps
 >
 

package/lib/enclosure/fdm/box.ts

@@ -3,20 +3,60 @@ import { expectTypesMatch } from "lib/typecheck"
 import { z } from "zod"
 
 export interface EnclosureFdmBoxProps {
+  /** Stable enclosure identity. */
+  name?: string
   /** The name or selector of the board enclosed by this box. */
   boardRef: string
+  /** Optional outside X dimension; inferred from the board when omitted. */
   width?: Distance
+  /** Optional outside Y dimension; inferred from the board when omitted. */
   height?: Distance
+  /** Optional total outside Z dimension; inferred from the board stack. */
   depth?: Distance
+  /** Printed side-wall thickness. */
   wallThickness?: Distance
+  /** Base floor thickness. */
+  floorThickness?: Distance
+  /** Lid top-plate thickness. */
+  lidThickness?: Distance
+  /** Horizontal clearance between the board edge and inside wall. */
+  boardClearance?: Distance
+  /** Gap from the inside floor to the PCB bottom. */
+  standoffHeight?: Distance
+  /**
+   * Clearance from the PCB top surface up to the inside of the lid.
+   *
+   * This is measured from the *board*, not from the tallest component: only
+   * parts that declare an aperture report their height, so an arbitrary tall
+   * capacitor is invisible here and setting this does not guarantee it clears.
+   *
+   * Omit it and the depth is inferred instead -- grown until the lid and its lip
+   * clear every side-wall aperture, so a connector taller than the default
+   * cannot end up straddling the base/lid seam. Setting it explicitly opts out
+   * of that: the value is then taken literally, which is what allows a part to
+   * deliberately poke through the lid.
+   */
+  topHeadroom?: Distance
+  /** Depth of the friction-fit lid lip. */
+  lidLipDepth?: Distance
+  /** Disable placement of apertures explicitly declared by enclosed components. */
+  disableCutouts?: boolean
 }
 
 export const enclosureFdmBoxProps = z.object({
+  name: z.string().optional(),
   boardRef: z.string().min(1),
   width: distance.optional(),
   height: distance.optional(),
   depth: distance.optional(),
   wallThickness: distance.default("2mm"),
+  floorThickness: distance.optional(),
+  lidThickness: distance.optional(),
+  boardClearance: distance.optional(),
+  standoffHeight: distance.optional(),
+  topHeadroom: distance.optional(),
+  lidLipDepth: distance.optional(),
+  disableCutouts: z.boolean().optional(),
 })
 
 export type EnclosureFdmBoxPropsInput = z.input<typeof enclosureFdmBoxProps>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/props",
-  "version": "0.0.618",
+  "version": "0.0.619",
   "description": "Props for tscircuit builtin component types",
   "main": "dist/index.js",
   "type": "module",