@tscircuit/props 0.0.696 → 0.0.698

package/lib/assembly/index.ts

@@ -2,6 +2,7 @@ import { assemblyCadAssemblyProps } from "./cadassembly"
 import { assemblyCableProps } from "./cable"
 import { assemblyDeviceProps } from "./device"
 import { assemblyPartProps } from "./part"
+import { assemblyReferenceSurfaceProps } from "./referencesurface"
 import { assemblyPrintedPartProps } from "./printedpart"
 import { assemblyMotorProps } from "./motor"
 import { assemblyScreenProps } from "./screen"
@@ -12,6 +13,7 @@ export * from "./cable"
 export * from "./device"
 export * from "./motor"
 export * from "./part"
+export * from "./referencesurface"
 export * from "./printedpart"
 export * from "./screen"
 export * from "./subassembly"
@@ -22,6 +24,7 @@ export const assemblyProps = {
   device: assemblyDeviceProps,
   motor: assemblyMotorProps,
   part: assemblyPartProps,
+  referencesurface: assemblyReferenceSurfaceProps,
   printedpart: assemblyPrintedPartProps,
   screen: assemblyScreenProps,
   subassembly: assemblySubassemblyProps,

package/lib/assembly/part.ts

@@ -2,6 +2,7 @@ import { type CadModelProp, cadModelProp } from "lib/common/cadModel"
 import { url } from "lib/common/url"
 import { expectTypesMatch } from "lib/typecheck"
 import { z } from "zod"
+import type { ReactNode } from "react"
 
 /** A generic component of an assembly, with optional CAD geometry. */
 export interface AssemblyPartProps {
@@ -15,6 +16,8 @@ export interface AssemblyPartProps {
   modelUrl?: string
   /** Existing component CAD model formats; mutually exclusive with model and modelUrl. */
   cadModel?: CadModelProp
+  /** Reference surfaces defining named mounting frames for this part. */
+  children?: ReactNode
 }
 
 export const assemblyPartProps = z
@@ -26,6 +29,7 @@ export const assemblyPartProps = z
       .refine((value) => value.trim().length > 0, "modelUrl cannot be empty")
       .optional(),
     cadModel: cadModelProp.optional(),
+    children: z.custom<ReactNode>().optional(),
   })
   .refine(
     (part) =>

package/lib/assembly/printedpart.ts

@@ -2,7 +2,7 @@ import { type CadModelProp, cadModelProp } from "lib/common/cadModel"
 import { url } from "lib/common/url"
 import { distance, type Distance } from "lib/common/distance"
 import { expectTypesMatch } from "lib/typecheck"
-import { isValidElement, type ReactElement } from "react"
+import { isValidElement, type ReactElement, type ReactNode } from "react"
 import { z } from "zod"
 
 /** Provide exactly one of jscad, model, modelUrl, or cadModel. */
@@ -10,6 +10,12 @@ export interface AssemblyPrintedPartProps {
   /** Stable identity used by assembly mounting selectors. */
   name: string
   displayName?: string
+  /** Color for the rendered printed part. Omit to retain authored materials. */
+  color?: string
+  /** Printable material classification; omitted when unspecified. */
+  material?: "pla" | "petg" | "nylon"
+  /** Reference surfaces defining named mounting frames, alongside CAD children. */
+  children?: ReactNode
   /** Pure jscad-fiber JSX in right-handed local XYZ, dimensions in millimeters.
    * Named reference rectangles define attachment faces; they add no material.
    * Hooks, async components, and raw kernel geometry are not supported.
@@ -36,6 +42,9 @@ export const assemblyPrintedPartProps = z
   .object({
     name: z.string().trim().min(1),
     displayName: z.string().optional(),
+    color: z.string().trim().min(1).optional(),
+    material: z.enum(["pla", "petg", "nylon"]).optional(),
+    children: z.custom<ReactNode>().optional(),
     jscad: z
       .custom<ReactElement>(isValidElement, "Expected jscad-fiber JSX")
       .optional(),

package/lib/assembly/referencesurface.ts

@@ -0,0 +1,80 @@
+import { type Distance, distance } from "lib/common/distance"
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+
+/** A named, non-solid mounting frame in the owning part's local, right-handed
+ * XYZ (mm). Offsets locate its origin; its normal and tangent are directions.
+ */
+export interface AssemblyReferenceSurfaceProps {
+  /** Unique within the part; defaults to "anchor". Use PART.name to mount to it. */
+  name?: string
+  /** Reference shape; defaults to rect. Does not create solid geometry. */
+  shape?: "rect"
+  /** Defaults to xy. Positive normals: xy +Z, xz +Y, yz +X. */
+  plane?: "xy" | "xz" | "yz"
+  /** Outward normal, perpendicular to plane. Defaults: xy z+, xz y+, yz x+.
+   * Reversing the normal retains the local X tangent. Replaces positive/negative.
+   */
+  normalDirection?: "x+" | "x-" | "y+" | "y-" | "z+" | "z-"
+  /** Surface center offsets from the part origin, in mm or unit strings; each defaults to zero. */
+  centerXOffset?: Distance
+  centerYOffset?: Distance
+  centerZOffset?: Distance
+  /** Optional rectangular extents along the tangent and its perpendicular.
+   * Supply width and height together. Mounting uses the center, not the edges.
+   */
+  width?: Distance
+  height?: Distance
+}
+
+const offset = distance.pipe(z.number().finite())
+const extent = distance.pipe(z.number().positive().finite())
+
+export const assemblyReferenceSurfaceProps = z
+  .object({
+    name: z.string().trim().min(1).default("anchor"),
+    shape: z.literal("rect").default("rect"),
+    plane: z.enum(["xy", "xz", "yz"]).default("xy"),
+    normalDirection: z.enum(["x+", "x-", "y+", "y-", "z+", "z-"]).optional(),
+    centerXOffset: offset.default(0),
+    centerYOffset: offset.default(0),
+    centerZOffset: offset.default(0),
+    width: extent.optional(),
+    height: extent.optional(),
+  })
+  .refine(
+    (surface) =>
+      (surface.width === undefined) === (surface.height === undefined),
+    {
+      message: "Provide width and height together",
+      path: ["width"],
+    },
+  )
+  .superRefine((surface, ctx) => {
+    const normalAxis =
+      surface.plane === "xy" ? "z" : surface.plane === "xz" ? "y" : "x"
+    if (surface.normalDirection && surface.normalDirection[0] !== normalAxis)
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["normalDirection"],
+        message: `normalDirection must be ${normalAxis}+ or ${normalAxis}- for plane ${surface.plane}`,
+      })
+  })
+  .transform((surface) => ({
+    ...surface,
+    normalDirection:
+      surface.normalDirection ??
+      (surface.plane === "xy"
+        ? ("z+" as const)
+        : surface.plane === "xz"
+          ? ("y+" as const)
+          : ("x+" as const)),
+  }))
+
+export type AssemblyReferenceSurfacePropsInput = z.input<
+  typeof assemblyReferenceSurfaceProps
+>
+expectTypesMatch<
+  AssemblyReferenceSurfaceProps,
+  AssemblyReferenceSurfacePropsInput
+>(true)

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.696",
+  "version": "0.0.698",
   "description": "Props for tscircuit builtin component types",
   "main": "dist/index.js",
   "type": "module",