@tscircuit/props 0.0.697 → 0.0.699

package/lib/assembly/bolt.ts

@@ -0,0 +1,79 @@
+import { distance, type Distance } from "lib/common/distance"
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+import { assemblyFastenerProps, type AssemblyFastenerProps } from "./fastener"
+
+export type AssemblyBoltHeadType = "socket" | "hex" | "pan" | "countersunk"
+
+/** A bolt specified by dimensions, or by one existing assembly CAD source. */
+export interface AssemblyBoltProps extends AssemblyFastenerProps {
+  /** Nominal thread diameter in mm or a unit string. Required with length
+   * when no model, modelUrl, or cadModel is supplied.
+   */
+  diameter?: Distance
+  /** Shaft length in mm or a unit string, excluding the head (including the
+   * head for countersunk bolts). Required with diameter for dimensional bolts.
+   */
+  length?: Distance
+  /** Optional thread pitch in mm or a unit string. No pitch is inferred. */
+  threadPitch?: Distance
+  /** Head shape for dimensional bolts; defaults to socket. */
+  headType?: AssemblyBoltHeadType
+}
+
+const positiveDistance = distance.pipe(z.number().positive().finite())
+
+export const assemblyBoltProps = assemblyFastenerProps
+  .and(
+    z.object({
+      diameter: positiveDistance.optional(),
+      length: positiveDistance.optional(),
+      threadPitch: positiveDistance.optional(),
+      headType: z.enum(["socket", "hex", "pan", "countersunk"]).optional(),
+    }),
+  )
+  .superRefine((bolt, ctx) => {
+    const hasModel = [bolt.model, bolt.modelUrl, bolt.cadModel].some(
+      (value) => value !== undefined,
+    )
+    if (hasModel) {
+      for (const prop of [
+        "diameter",
+        "length",
+        "threadPitch",
+        "headType",
+      ] as const) {
+        if (bolt[prop] !== undefined) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [prop],
+            message:
+              "Bolt dimensions and headType are exclusive with CAD sources",
+          })
+        }
+      }
+    } else {
+      for (const prop of ["diameter", "length"] as const) {
+        if (bolt[prop] === undefined) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [prop],
+            message: "Provide diameter and length, or an assembly CAD source",
+          })
+        }
+      }
+    }
+  })
+  .transform((bolt) =>
+    bolt.diameter === undefined
+      ? bolt
+      : { ...bolt, headType: bolt.headType ?? ("socket" as const) },
+  )
+
+export type AssemblyBoltPropsInput = {
+  [K in keyof z.input<typeof assemblyBoltProps>]: z.input<
+    typeof assemblyBoltProps
+  >[K]
+}
+
+expectTypesMatch<AssemblyBoltProps, AssemblyBoltPropsInput>(true)

package/lib/assembly/fastener.ts

@@ -0,0 +1,78 @@
+import { distance, type Distance } from "lib/common/distance"
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+import { assemblyPartProps, type AssemblyPartProps } from "./part"
+
+/** An assembly part that fastens to its mounting target, even without geometry. */
+export interface AssemblyFastenerProps extends AssemblyPartProps {
+  /** Qualified reference surface, e.g. "FRAME.boltHole". Implies fastening.
+   * Without mountFace, use the fastener's authored local mounting origin.
+   */
+  mountedTo?: string
+  /** Common fastener vocabulary for mountedTo; parsed output uses mountedTo.
+   * Both may be supplied only when their trimmed values agree.
+   */
+  fastenedTo?: string
+  /** Optional named mating face on this fastener; requires a mounting target.
+   * When supplied, outward normals oppose and in-plane X directions align.
+   */
+  mountFace?: string
+  /** Nonnegative surface clearance in mm or a unit string; defaults to zero
+   * in the consumer. Requires a mounting target; omitted values stay omitted.
+   */
+  mountGap?: Distance
+}
+
+const mountingTarget = z
+  .string()
+  .trim()
+  .regex(
+    /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)+$/,
+    "Expected a qualified reference surface, e.g. part.face",
+  )
+
+export const assemblyFastenerProps = assemblyPartProps
+  .and(
+    z.object({
+      mountedTo: mountingTarget.optional(),
+      fastenedTo: mountingTarget.optional(),
+      mountFace: z.string().trim().min(1).optional(),
+      mountGap: distance.pipe(z.number().nonnegative().finite()).optional(),
+    }),
+  )
+  .superRefine((fastener, ctx) => {
+    if (
+      fastener.mountedTo !== undefined &&
+      fastener.fastenedTo !== undefined &&
+      fastener.mountedTo !== fastener.fastenedTo
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["fastenedTo"],
+        message: "mountedTo and fastenedTo must refer to the same surface",
+      })
+    }
+    if (fastener.mountedTo === undefined && fastener.fastenedTo === undefined) {
+      for (const prop of ["mountFace", "mountGap"] as const) {
+        if (fastener[prop] !== undefined) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [prop],
+            message: `${prop} requires mountedTo or fastenedTo`,
+          })
+        }
+      }
+    }
+  })
+  .transform(({ fastenedTo, ...fastener }) => {
+    const mountedTo = fastener.mountedTo ?? fastenedTo
+    return mountedTo === undefined ? fastener : { ...fastener, mountedTo }
+  })
+
+export type AssemblyFastenerPropsInput = {
+  [K in keyof z.input<typeof assemblyFastenerProps>]: z.input<
+    typeof assemblyFastenerProps
+  >[K]
+}
+
+expectTypesMatch<AssemblyFastenerProps, AssemblyFastenerPropsInput>(true)

package/lib/assembly/index.ts

@@ -1,5 +1,7 @@
 import { assemblyCadAssemblyProps } from "./cadassembly"
 import { assemblyCableProps } from "./cable"
+import { assemblyBoltProps } from "./bolt"
+import { assemblyFastenerProps } from "./fastener"
 import { assemblyDeviceProps } from "./device"
 import { assemblyPartProps } from "./part"
 import { assemblyReferenceSurfaceProps } from "./referencesurface"
@@ -9,6 +11,8 @@ import { assemblyScreenProps } from "./screen"
 import { assemblySubassemblyProps } from "./subassembly"
 
 export * from "./board-mounting"
+export * from "./bolt"
+export * from "./fastener"
 export * from "./cable"
 export * from "./device"
 export * from "./motor"
@@ -20,6 +24,8 @@ export * from "./subassembly"
 export * from "./cadassembly"
 
 export const assemblyProps = {
+  bolt: assemblyBoltProps,
+  fastener: assemblyFastenerProps,
   cable: assemblyCableProps,
   device: assemblyDeviceProps,
   motor: assemblyMotorProps,

package/lib/components/pcb-return-current-excitation.ts

@@ -0,0 +1,110 @@
+import { layer_ref, type LayerRefInput } from "circuit-json"
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+
+/** A signal driver/load pair and its explicit ground return terminals.
+ * Selectors resolve inside the containing board/subcircuit. The initial core
+ * implementation accepts physical PCB ports/pads, not standalone via contacts.
+ * This definition neither connects the selected pins nor runs a simulation.
+ */
+export interface PcbReturnCurrentExcitationProps {
+  /** Readable excitation name for diagnostics; not stored on its Circuit JSON record. */
+  name?: string
+  /** Signal driver port selector, e.g. ".U1 > .OUT". */
+  source: string
+  /** Signal receiving port selector, e.g. ".U2 > .IN". */
+  load: string
+  /** Ground net selector, e.g. "net.GND"; its copper and connections must already exist. */
+  ground: string
+  /** Positive in-phase peak signal current. Numbers are amperes, not RMS; strings use ampere units. */
+  current: number | string
+  /** Load-side GND port where positive return current enters the return conductor. */
+  returnSource: string
+  /** Driver-side GND port where positive return current leaves the return conductor. */
+  returnSink: string
+  /** Positive real source-port resistance. Numbers are ohms; complex impedances are unsupported. */
+  sourceImpedance: number | string
+  /** Positive real load-port resistance. Numbers are ohms; complex impedances are unsupported. */
+  loadImpedance: number | string
+  /** Optional trace selector to disambiguate multiple routes between the signal ports. */
+  trace?: string
+  /** Contact layer for a load-side PCB port spanning multiple copper layers. */
+  returnSourceLayer?: LayerRefInput
+  /** Contact layer for a driver-side PCB port spanning multiple copper layers. */
+  returnSinkLayer?: LayerRefInput
+}
+
+const selector = z.string().trim().min(1, "Provide a nonempty selector")
+const quantity = "[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[eE][+-]?\\d+)?"
+const prefixScale: Record<string, number> = {
+  "": 1,
+  y: 1e-24,
+  z: 1e-21,
+  a: 1e-18,
+  f: 1e-15,
+  p: 1e-12,
+  n: 1e-9,
+  u: 1e-6,
+  µ: 1e-6,
+  μ: 1e-6,
+  m: 1e-3,
+  k: 1e3,
+  M: 1e6,
+  G: 1e9,
+  T: 1e12,
+  P: 1e15,
+  E: 1e18,
+  Z: 1e21,
+  Y: 1e24,
+}
+
+// Full-string parsing preserves scientific notation and rejects other
+// dimensions. The generic Circuit JSON converters currently do neither.
+function positiveQuantity(unit: string, label: string, example: string) {
+  const pattern = new RegExp(
+    `^(${quantity})\\s*(?:([yzafpnumkMGTPEZYµμ]?)(?:${unit}))?$`,
+  )
+  return z
+    .union([
+      z.number(),
+      z
+        .string()
+        .trim()
+        .regex(pattern, `Use ${label} or a unit string, e.g. ${example}`),
+    ])
+    .transform((value) => {
+      if (typeof value === "number") return value
+      const match = pattern.exec(value)!
+      return Number(match[1]) * prefixScale[match[2] ?? ""]!
+    })
+    .pipe(z.number().finite().positive(`${label} must be greater than zero`))
+}
+
+const positiveCurrent = positiveQuantity("A", "peak amperes", "5mA")
+const positiveResistance = positiveQuantity(
+  "ohms?|Ohms?|Ω",
+  "real ohms",
+  "100ohm",
+)
+
+export const pcbReturnCurrentExcitationProps = z
+  .object({
+    name: z.string().trim().min(1).optional(),
+    source: selector,
+    load: selector,
+    ground: selector,
+    current: positiveCurrent,
+    returnSource: selector,
+    returnSink: selector,
+    sourceImpedance: positiveResistance,
+    loadImpedance: positiveResistance,
+    trace: selector.optional(),
+    returnSourceLayer: layer_ref.optional(),
+    returnSinkLayer: layer_ref.optional(),
+  })
+  .strict()
+
+expectTypesMatch<
+  PcbReturnCurrentExcitationProps,
+  z.input<typeof pcbReturnCurrentExcitationProps>
+>(true)

package/lib/components/pcb-return-current-simulation.ts

@@ -0,0 +1,25 @@
+import { expectTypesMatch } from "lib/typecheck"
+import type { ReactNode } from "react"
+import { z } from "zod"
+
+/** Defines a pending PCB return-current experiment; rendering does not run it.
+ * Frequency, mesh and sampling settings are supplied to the simulation CLI.
+ */
+export interface PcbReturnCurrentSimulationProps {
+  /** Stable identity and readable name for the experiment. */
+  name?: string
+  /** One or more nested simulation.pcbreturncurrentexcitation elements. */
+  children?: ReactNode
+}
+
+export const pcbReturnCurrentSimulationProps = z
+  .object({
+    name: z.string().trim().min(1).optional(),
+    children: z.custom<ReactNode>().optional(),
+  })
+  .strict()
+
+expectTypesMatch<
+  PcbReturnCurrentSimulationProps,
+  z.input<typeof pcbReturnCurrentSimulationProps>
+>(true)

package/lib/index.ts

@@ -81,6 +81,7 @@ export * from "./components/analogtransientsimulation"
 export * from "./components/analogdcoperatingpointsimulation"
 export * from "./components/analogdcsweepsimulation"
 export * from "./components/analogacsweepsimulation"
+export * from "./simulation"
 export * from "./components/analogsweepparameter"
 export * from "./components/autoroutingphase"
 export * from "./components/spicemodel"

package/lib/simulation/index.ts

@@ -0,0 +1,10 @@
+import { pcbReturnCurrentExcitationProps } from "../components/pcb-return-current-excitation"
+import { pcbReturnCurrentSimulationProps } from "../components/pcb-return-current-simulation"
+
+export * from "../components/pcb-return-current-excitation"
+export * from "../components/pcb-return-current-simulation"
+
+export const simulationProps = {
+  pcbreturncurrentsimulation: pcbReturnCurrentSimulationProps,
+  pcbreturncurrentexcitation: pcbReturnCurrentExcitationProps,
+} as const

package/package.json

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