@tscircuit/props 0.0.715 → 0.0.717

package/lib/assembly/face-mounting.ts

@@ -0,0 +1,73 @@
+import { distance, type Distance } from "lib/common/distance"
+import { z } from "zod"
+
+/** Signed distances along the target face's local in-plane X/Y axes, in mm. */
+export interface AssemblyMountOffset {
+  x?: Distance
+  y?: Distance
+}
+
+export interface AssemblyFaceMountProps {
+  /** Target face reference, e.g. "BRIDGE.rail" or ".BRIDGE > .rail".
+   * CSS selectors and compact identity paths are resolved by core.
+   * References are resolved in the containing device, independently of order.
+   */
+  mountedTo?: string
+  /** This element's named mating face. Outward normals oppose and in-plane
+   * X directions align. A mount determines the complete local rigid pose.
+   */
+  mountFace?: string
+  /** Finite nonnegative clearance, in mm or a distance string.
+   * Requires mountedTo. Omission stays absent and means zero in core.
+   * Positive gaps separate the faces along the target's outward normal.
+   */
+  mountGap?: Distance
+  /** Signed in-plane offset in the target face frame; requires mountedTo.
+   * Supplied axes accept mm numbers or distance strings; omitted axes are zero.
+   * Normal separation is expressed by mountGap, not a third offset axis.
+   */
+  mountOffset?: AssemblyMountOffset
+}
+
+export const assemblyMountOffset = z
+  .object({
+    x: distance.pipe(z.number().finite()).default(0),
+    y: distance.pipe(z.number().finite()).default(0),
+  })
+  .strict()
+
+// Shared fields/refinement are internal composition helpers. Consumers use
+// each element's complete validator rather than a partial mounting schema.
+export const assemblyFaceMountShape = {
+  mountedTo: z.string().trim().min(1).optional(),
+  mountFace: z.string().trim().min(1).optional(),
+  mountGap: distance.pipe(z.number().nonnegative().finite()).optional(),
+  mountOffset: assemblyMountOffset.optional(),
+}
+
+export const refineAssemblyFaceMount = (
+  part: AssemblyFaceMountProps,
+  context: z.RefinementCtx,
+) => {
+  if ((part.mountedTo === undefined) !== (part.mountFace === undefined)) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["mountFace"],
+      message: "Provide mountedTo and mountFace together",
+    })
+  }
+  if (part.mountGap !== undefined && part.mountedTo === undefined) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["mountGap"],
+      message: "mountGap requires mountedTo",
+    })
+  }
+  if (part.mountOffset !== undefined && part.mountedTo === undefined) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["mountOffset"],
+      message: "mountOffset requires mountedTo",
+    })
+  }
+}

package/lib/assembly/fastener.ts

@@ -1,11 +1,13 @@
 import { distance, type Distance } from "lib/common/distance"
 import { expectTypesMatch } from "lib/typecheck"
 import { z } from "zod"
-import { assemblyPartProps, type AssemblyPartProps } from "./part"
+import { assemblyPartBaseProps, type AssemblyPartProps } from "./part"
+import { assemblyMountOffset } from "./face-mounting"
 
 /** 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.
+  /** Reference surface, e.g. "FRAME.boltHole" or ".FRAME > .boltHole".
+   * CSS selectors and compact paths are resolved by core. Implies fastening.
    * Without mountFace, use the fastener's authored local mounting origin.
    */
   mountedTo?: string
@@ -23,21 +25,16 @@ export interface AssemblyFastenerProps extends AssemblyPartProps {
   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",
-  )
+const mountingTarget = z.string().trim().min(1)
 
-export const assemblyFastenerProps = assemblyPartProps
+export const assemblyFastenerProps = assemblyPartBaseProps
   .and(
     z.object({
       mountedTo: mountingTarget.optional(),
       fastenedTo: mountingTarget.optional(),
       mountFace: z.string().trim().min(1).optional(),
       mountGap: distance.pipe(z.number().nonnegative().finite()).optional(),
+      mountOffset: assemblyMountOffset.optional(),
     }),
   )
   .superRefine((fastener, ctx) => {
@@ -53,7 +50,7 @@ export const assemblyFastenerProps = assemblyPartProps
       })
     }
     if (fastener.mountedTo === undefined && fastener.fastenedTo === undefined) {
-      for (const prop of ["mountFace", "mountGap"] as const) {
+      for (const prop of ["mountFace", "mountGap", "mountOffset"] as const) {
         if (fastener[prop] !== undefined) {
           ctx.addIssue({
             code: z.ZodIssueCode.custom,

package/lib/assembly/index.ts

@@ -19,7 +19,15 @@ export * from "./fastener"
 export * from "./cable"
 export * from "./device"
 export * from "./motor"
-export * from "./part"
+export {
+  assemblyPartProps,
+  type AssemblyPartProps,
+  type AssemblyPartPropsInput,
+} from "./part"
+export type {
+  AssemblyFaceMountProps,
+  AssemblyMountOffset,
+} from "./face-mounting"
 export * from "./referencesurface"
 export * from "./printedpart"
 export * from "./screen"

package/lib/assembly/motor.ts

@@ -2,13 +2,17 @@ import {
   type CadModelAxisDirection,
   cadModelAxisDirection,
 } from "lib/common/cadModel"
-import { distance, type Distance } from "lib/common/distance"
 import { expectTypesMatch } from "lib/typecheck"
 import { z } from "zod"
+import {
+  assemblyFaceMountShape,
+  refineAssemblyFaceMount,
+  type AssemblyFaceMountProps,
+} from "./face-mounting"
 
 export type AssemblyMotorStandard = "nema8" | "nema17" | "nema23"
 
-export interface AssemblyMotorProps {
+export interface AssemblyMotorProps extends AssemblyFaceMountProps {
   /** Stable assembly identity used by selectors. */
   name: string
   /** Human-facing alternate to the stable name. */
@@ -21,29 +25,19 @@ export interface AssemblyMotorProps {
    * Direction from the motor body toward the shaft tip in the right-handed
    * circuit frame: +X right, +Y top, +Z above the board. This is a direction,
    * not a position; it does not specify translation or rotation about the
-   * shaft. Defaults to "z+", the native shaft axis of the NEMA models.
+   * shaft. Defaults to "z+" only when unmounted. Omit it when mounted;
+   * the mating faces then determine the complete motor orientation.
    */
   shaftFacingDirection?: CadModelAxisDirection
   /** Cable connection string, e.g. "jst6_ph".
    * Omit to use the model's default termination.
    */
   wireConnection?: string
-  /** Assembly mounting target, e.g. "FRAME.xMotor"; paired with mountFace.
-   * Face mating determines orientation, so shaftFacingDirection must be omitted.
-   */
-  mountedTo?: string
-  /** This motor's mating face, e.g. "frontface" or "backface".
-   * Outward normals oppose and in-plane X directions align with the target.
-   */
-  mountFace?: string
-  /** Nonnegative surface clearance in mm or a unit string; defaults to zero.
-   * Requires mountedTo. Positive values separate the mating faces.
-   */
-  mountGap?: Distance
 }
 
 export const assemblyMotorProps = z
   .object({
+    ...assemblyFaceMountShape,
     name: z.string().refine((value) => value.trim().length > 0, {
       message: "name cannot be empty",
     }),
@@ -52,29 +46,9 @@ export const assemblyMotorProps = z
     model: z.string().trim().min(1).optional(),
     shaftFacingDirection: cadModelAxisDirection.optional(),
     wireConnection: z.string().optional(),
-    mountedTo: z
-      .string()
-      .trim()
-      .regex(/^.+\.[^.]+$/, "Expected part.face")
-      .optional(),
-    mountFace: z.string().trim().min(1).optional(),
-    mountGap: distance.pipe(z.number().nonnegative().finite()).optional(),
   })
   .superRefine((motor, context) => {
-    if ((motor.mountedTo === undefined) !== (motor.mountFace === undefined)) {
-      context.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: "Provide mountedTo and mountFace together",
-        path: ["mountFace"],
-      })
-    }
-    if (motor.mountGap !== undefined && motor.mountedTo === undefined) {
-      context.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: "mountGap requires mountedTo",
-        path: ["mountGap"],
-      })
-    }
+    refineAssemblyFaceMount(motor, context)
     if (
       motor.mountedTo !== undefined &&
       motor.shaftFacingDirection !== undefined

package/lib/assembly/part.ts

@@ -3,9 +3,14 @@ import { url } from "lib/common/url"
 import { expectTypesMatch } from "lib/typecheck"
 import { z } from "zod"
 import type { ReactNode } from "react"
+import {
+  assemblyFaceMountShape,
+  refineAssemblyFaceMount,
+  type AssemblyFaceMountProps,
+} from "./face-mounting"
 
 /** A generic component of an assembly, with optional CAD geometry. */
-export interface AssemblyPartProps {
+export interface AssemblyPartProps extends AssemblyFaceMountProps {
   /** Stable identity used by assembly selectors. */
   name: string
   /** Human-facing alternate to the stable name. */
@@ -20,7 +25,9 @@ export interface AssemblyPartProps {
   children?: ReactNode
 }
 
-export const assemblyPartProps = z
+// Internal base for elements with their own mounting semantics, e.g. fasteners.
+// Keep model validation separate from ordinary face-mount pairing.
+export const assemblyPartBaseProps = z
   .object({
     name: z.string().trim().min(1),
     displayName: z.string().optional(),
@@ -42,6 +49,14 @@ export const assemblyPartProps = z
     },
   )
 
-export type AssemblyPartPropsInput = z.input<typeof assemblyPartProps>
+export const assemblyPartProps = assemblyPartBaseProps
+  .and(z.object(assemblyFaceMountShape))
+  .superRefine(refineAssemblyFaceMount)
+
+export type AssemblyPartPropsInput = {
+  [K in keyof z.input<typeof assemblyPartProps>]: z.input<
+    typeof assemblyPartProps
+  >[K]
+}
 
 expectTypesMatch<AssemblyPartProps, AssemblyPartPropsInput>(true)

package/lib/assembly/printedpart.ts

@@ -1,12 +1,16 @@
 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, type ReactNode } from "react"
 import { z } from "zod"
+import {
+  assemblyFaceMountShape,
+  refineAssemblyFaceMount,
+  type AssemblyFaceMountProps,
+} from "./face-mounting"
 
 /** Provide exactly one of jscad, model, modelUrl, or cadModel. */
-export interface AssemblyPrintedPartProps {
+export interface AssemblyPrintedPartProps extends AssemblyFaceMountProps {
   /** Stable identity used by assembly mounting selectors. */
   name: string
   displayName?: string
@@ -25,21 +29,11 @@ export interface AssemblyPrintedPartProps {
   model?: string
   modelUrl?: string
   cadModel?: CadModelProp
-  /** Assembly mounting target. */
-  mountedTo?: string
-  /** Name of this part's reference rectangle to mate with mountedTo.
-   * Both props must be supplied together; outward normals oppose and local
-   * in-plane X directions align. Without them the part uses its local origin.
-   */
-  mountFace?: string
-  /** Nonnegative surface clearance in mm or a unit string; defaults to zero.
-   * Requires mountedTo. Positive values separate the mating faces.
-   */
-  mountGap?: Distance
 }
 
 export const assemblyPrintedPartProps = z
   .object({
+    ...assemblyFaceMountShape,
     name: z.string().trim().min(1),
     displayName: z.string().optional(),
     color: z.string().trim().min(1).optional(),
@@ -53,15 +47,9 @@ export const assemblyPrintedPartProps = z
       .refine((value) => value.trim().length > 0, "modelUrl cannot be empty")
       .optional(),
     cadModel: cadModelProp.optional(),
-    mountedTo: z
-      .string()
-      .trim()
-      .regex(/^.+\.[^.]+$/, "Expected part.face")
-      .optional(),
-    mountFace: z.string().trim().min(1).optional(),
-    mountGap: distance.pipe(z.number().nonnegative().finite()).optional(),
   })
   .superRefine((part, ctx) => {
+    refineAssemblyFaceMount(part, ctx)
     if (
       [part.jscad, part.model, part.modelUrl, part.cadModel].filter(
         (value) => value !== undefined,
@@ -73,20 +61,6 @@ export const assemblyPrintedPartProps = z
         message: "Provide exactly one of jscad, model, modelUrl, or cadModel",
       })
     }
-    if ((part.mountedTo === undefined) !== (part.mountFace === undefined)) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ["mountFace"],
-        message: "Provide mountedTo and mountFace together",
-      })
-    }
-    if (part.mountGap !== undefined && part.mountedTo === undefined) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ["mountGap"],
-        message: "mountGap requires mountedTo",
-      })
-    }
   })
 
 export type AssemblyPrintedPartPropsInput = z.input<

package/lib/assembly/subassembly.ts

@@ -3,8 +3,13 @@ import { type CadModelProp, cadModelProp } from "lib/common/cadModel"
 import { expectTypesMatch } from "lib/typecheck"
 import type { ReactNode } from "react"
 import { z } from "zod"
+import {
+  assemblyFaceMountShape,
+  refineAssemblyFaceMount,
+  type AssemblyFaceMountProps,
+} from "./face-mounting"
 
-export interface AssemblySubassemblyProps {
+export interface AssemblySubassemblyProps extends AssemblyFaceMountProps {
   /** Stable identity used by selectors from other assembly elements. */
   name: string
   /** Imported CAD model URL. Mutually exclusive with cadModel where supported. */
@@ -21,6 +26,7 @@ export interface AssemblySubassemblyProps {
 
 export const assemblySubassemblyProps = z
   .object({
+    ...assemblyFaceMountShape,
     name: z.string().refine((value) => value.trim().length > 0, {
       message: "name cannot be empty",
     }),
@@ -51,6 +57,7 @@ export const assemblySubassemblyProps = z
       path: ["model"],
     },
   )
+  .superRefine(refineAssemblyFaceMount)
 
 export type AssemblySubassemblyPropsInput = z.input<
   typeof assemblySubassemblyProps

package/lib/components/system-block-component.ts

@@ -0,0 +1,35 @@
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+import {
+  type SystemBlockPcbReferenceProps,
+  refineSystemBlockPcbReference,
+  systemBlockPcbReferenceShape,
+} from "../systemblock/pcb-reference"
+
+/** A functional block, optionally associated with one or more PCB components. */
+export interface SystemBlockComponentProps
+  extends SystemBlockPcbReferenceProps {
+  /** Stable block identity, unique across its page; trimmed and nonempty. */
+  name: string
+  /** Human-facing title; consumers fall back to name when omitted. */
+  displayName?: string
+  /** Plain-text explanation of what the block does. */
+  description?: string
+}
+
+export const systemBlockComponentProps = z
+  .object({
+    ...systemBlockPcbReferenceShape,
+    name: z.string().trim().min(1),
+    displayName: z.string().trim().min(1).optional(),
+    description: z.string().optional(),
+  })
+  .superRefine(refineSystemBlockPcbReference)
+
+export type SystemBlockComponentPropsInput = z.input<
+  typeof systemBlockComponentProps
+>
+
+expectTypesMatch<SystemBlockComponentProps, SystemBlockComponentPropsInput>(
+  true,
+)

package/lib/components/system-block-connection.ts

@@ -0,0 +1,35 @@
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+
+/** A logical relationship between two blocks; does not create electrical traces. */
+export interface SystemBlockConnectionProps {
+  /** Optional stable connection identity, unique within its page when supplied. */
+  name?: string
+  /** Component name within the containing page, including inside nested groups. */
+  from: string
+  /** Component name within the same page; group names and pin selectors are not endpoints. */
+  to: string
+  /** Interface annotation such as I2C, SPI, or 3.3 V; not the connection's identity. */
+  label?: string
+  /** Relationship category; defaults to signal. */
+  kind?: "signal" | "power"
+  /** Arrowheads: from → to, both ends, or neither. Defaults to forward. */
+  direction?: "forward" | "both" | "none"
+}
+
+export const systemBlockConnectionProps = z.object({
+  name: z.string().trim().min(1).optional(),
+  from: z.string().trim().min(1),
+  to: z.string().trim().min(1),
+  label: z.string().optional(),
+  kind: z.enum(["signal", "power"]).default("signal"),
+  direction: z.enum(["forward", "both", "none"]).default("forward"),
+})
+
+export type SystemBlockConnectionPropsInput = z.input<
+  typeof systemBlockConnectionProps
+>
+
+expectTypesMatch<SystemBlockConnectionProps, SystemBlockConnectionPropsInput>(
+  true,
+)

package/lib/components/system-block-group.ts

@@ -0,0 +1,34 @@
+import { expectTypesMatch } from "lib/typecheck"
+import type { ReactNode } from "react"
+import { z } from "zod"
+import {
+  type SystemBlockPcbReferenceProps,
+  refineSystemBlockPcbReference,
+  systemBlockPcbReferenceShape,
+} from "../systemblock/pcb-reference"
+
+/** A subsystem boundary containing blocks, nested groups, and connections. */
+export interface SystemBlockGroupProps extends SystemBlockPcbReferenceProps {
+  /** Stable group identity, unique across its page; trimmed and nonempty. */
+  name: string
+  /** Human-facing title; consumers fall back to name when omitted. */
+  displayName?: string
+  /** Plain-text explanation of the subsystem's responsibility. */
+  description?: string
+  /** Preserved unchanged; grouping does not create electrical connectivity. */
+  children?: ReactNode
+}
+
+export const systemBlockGroupProps = z
+  .object({
+    ...systemBlockPcbReferenceShape,
+    name: z.string().trim().min(1),
+    displayName: z.string().trim().min(1).optional(),
+    description: z.string().optional(),
+    children: z.custom<ReactNode>().optional(),
+  })
+  .superRefine(refineSystemBlockPcbReference)
+
+export type SystemBlockGroupPropsInput = z.input<typeof systemBlockGroupProps>
+
+expectTypesMatch<SystemBlockGroupProps, SystemBlockGroupPropsInput>(true)

package/lib/components/system-block-page.ts

@@ -0,0 +1,29 @@
+import { expectTypesMatch } from "lib/typecheck"
+import type { ReactNode } from "react"
+import { z } from "zod"
+
+/** One high-level system overview, independent of schematic or PCB geometry. */
+export interface SystemBlockPageProps {
+  /** Stable page identity, unique within the circuit; trimmed and nonempty. */
+  name: string
+  /** Human-facing title; consumers fall back to name when omitted. */
+  displayName?: string
+  /** Plain-text explanation of the system's purpose. */
+  description?: string
+  /** Preferred automatic layout direction; defaults to right. */
+  direction?: "right" | "left" | "down" | "up"
+  /** System blocks, nested groups, and connections; preserved unchanged. */
+  children?: ReactNode
+}
+
+export const systemBlockPageProps = z.object({
+  name: z.string().trim().min(1),
+  displayName: z.string().trim().min(1).optional(),
+  description: z.string().optional(),
+  direction: z.enum(["right", "left", "down", "up"]).default("right"),
+  children: z.custom<ReactNode>().optional(),
+})
+
+export type SystemBlockPagePropsInput = z.input<typeof systemBlockPageProps>
+
+expectTypesMatch<SystemBlockPageProps, SystemBlockPagePropsInput>(true)

package/lib/index.ts

@@ -1,6 +1,7 @@
 export * from "./common/direction"
 export * from "./common/commonShape"
 export * from "./assembly"
+export * from "./systemblock"
 export * from "./enclosure"
 export * from "./common/portHints"
 export * from "./common/layout"

package/lib/systemblock/index.ts

@@ -0,0 +1,18 @@
+import { systemBlockPageProps } from "../components/system-block-page"
+import { systemBlockGroupProps } from "../components/system-block-group"
+import { systemBlockComponentProps } from "../components/system-block-component"
+import { systemBlockConnectionProps } from "../components/system-block-connection"
+
+export * from "../components/system-block-page"
+export * from "../components/system-block-group"
+export * from "../components/system-block-component"
+export * from "../components/system-block-connection"
+export type { SystemBlockPcbReferenceProps } from "./pcb-reference"
+
+/** Validators for the systemblock JSX namespace; rendering is supplied by core. */
+export const systemBlockProps = {
+  page: systemBlockPageProps,
+  group: systemBlockGroupProps,
+  component: systemBlockComponentProps,
+  connection: systemBlockConnectionProps,
+} as const

package/lib/systemblock/pcb-reference.ts

@@ -0,0 +1,39 @@
+import { z } from "zod"
+
+/** Optional PCB associations shared only by system blocks and their groups. */
+export interface SystemBlockPcbReferenceProps {
+  /** One PCB component name; mutually exclusive with pcbComponentNames. */
+  pcbComponentName?: string
+  /** Nonempty list of PCB component names; mutually exclusive with pcbComponentName. */
+  pcbComponentNames?: string[]
+  /**
+   * Named PCB subcircuit in which component names are resolved. Without component
+   * names, associates the entire subcircuit. Omitted uses the owning circuit scope.
+   * References are names, not selectors; resolution is performed by the consumer.
+   */
+  pcbSubcircuitName?: string
+}
+
+const pcbName = z.string().trim().min(1)
+
+export const systemBlockPcbReferenceShape = {
+  pcbComponentName: pcbName.optional(),
+  pcbComponentNames: z.array(pcbName).min(1).optional(),
+  pcbSubcircuitName: pcbName.optional(),
+}
+
+export function refineSystemBlockPcbReference(
+  props: SystemBlockPcbReferenceProps,
+  ctx: z.RefinementCtx,
+) {
+  if (
+    props.pcbComponentName !== undefined &&
+    props.pcbComponentNames !== undefined
+  ) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["pcbComponentNames"],
+      message: "Provide either pcbComponentName or pcbComponentNames, not both",
+    })
+  }
+}

package/package.json

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