@tscircuit/props 0.0.716 → 0.0.718

package/lib/assembly/bom.ts

@@ -0,0 +1,26 @@
+import { supplierProps, type SupplierProps } from "lib/common/layout"
+import { expectTypesMatch } from "lib/typecheck"
+import { z } from "zod"
+
+/** Purchasing metadata shared by physical assembly elements, not CAD primitives. */
+export interface AssemblyBomProps extends SupplierProps {
+  /** Alternative HTTP(S) purchase links, independent of supplier part numbers.
+   * Omitted and empty arrays are accepted. No SKU-to-URL mapping is inferred.
+   */
+  purchaseUrls?: string[]
+}
+
+export const assemblyBomProps = supplierProps.extend({
+  purchaseUrls: z
+    .array(
+      z
+        .string()
+        .url()
+        .refine((value) => /^https?:\/\//i.test(value), {
+          message: "Purchase links must use HTTP or HTTPS",
+        }),
+    )
+    .optional(),
+})
+
+expectTypesMatch<AssemblyBomProps, z.input<typeof assemblyBomProps>>(true)

package/lib/assembly/cable.ts

@@ -1,9 +1,10 @@
+import { assemblyBomProps, type AssemblyBomProps } from "./bom"
 import { expectTypesMatch } from "lib/typecheck"
 import { z } from "zod"
 
 export type AssemblyCableStandard = "usb_c"
 
-export interface AssemblyCableProps {
+export interface AssemblyCableProps extends AssemblyBomProps {
   /** Stable assembly identity for the cable. */
   name: string
   /** Start connector selector or named assembly reference, e.g. MOTOR.wireside. */
@@ -23,6 +24,7 @@ export interface AssemblyCableProps {
 
 export const assemblyCableProps = z
   .object({
+    ...assemblyBomProps.shape,
     name: z.string().trim().min(1),
     from: z.string().trim().min(1),
     to: z.string().trim().min(1),

package/lib/assembly/device.ts

@@ -1,8 +1,9 @@
+import { assemblyBomProps, type AssemblyBomProps } from "./bom"
 import { url } from "lib/common/url"
 import { expectTypesMatch } from "lib/typecheck"
 import { z } from "zod"
 
-export interface AssemblyDeviceProps {
+export interface AssemblyDeviceProps extends AssemblyBomProps {
   /** Product-level assembly identity. */
   name?: string
   /** Imported CAD model URL. Mutually exclusive with cadModel where supported. */
@@ -13,6 +14,7 @@ export interface AssemblyDeviceProps {
 
 export const assemblyDeviceProps = z
   .object({
+    ...assemblyBomProps.shape,
     name: z.string().optional(),
     model: z.string().trim().min(1).optional(),
     modelUrl: url

package/lib/assembly/index.ts

@@ -12,6 +12,7 @@ import { assemblyScreenProps } from "./screen"
 import { assemblySubassemblyProps } from "./subassembly"
 import { assemblyExplosionProps } from "./explosion"
 
+export * from "./bom"
 export * from "./drawing"
 export * from "./board-mounting"
 export * from "./bolt"

package/lib/assembly/motor.ts

@@ -1,3 +1,4 @@
+import { assemblyBomProps, type AssemblyBomProps } from "./bom"
 import {
   type CadModelAxisDirection,
   cadModelAxisDirection,
@@ -12,7 +13,9 @@ import {
 
 export type AssemblyMotorStandard = "nema8" | "nema17" | "nema23"
 
-export interface AssemblyMotorProps extends AssemblyFaceMountProps {
+export interface AssemblyMotorProps
+  extends AssemblyFaceMountProps,
+    AssemblyBomProps {
   /** Stable assembly identity used by selectors. */
   name: string
   /** Human-facing alternate to the stable name. */
@@ -37,6 +40,7 @@ export interface AssemblyMotorProps extends AssemblyFaceMountProps {
 
 export const assemblyMotorProps = z
   .object({
+    ...assemblyBomProps.shape,
     ...assemblyFaceMountShape,
     name: z.string().refine((value) => value.trim().length > 0, {
       message: "name cannot be empty",

package/lib/assembly/part.ts

@@ -1,3 +1,4 @@
+import { assemblyBomProps, type AssemblyBomProps } from "./bom"
 import { type CadModelProp, cadModelProp } from "lib/common/cadModel"
 import { url } from "lib/common/url"
 import { expectTypesMatch } from "lib/typecheck"
@@ -10,7 +11,9 @@ import {
 } from "./face-mounting"
 
 /** A generic component of an assembly, with optional CAD geometry. */
-export interface AssemblyPartProps extends AssemblyFaceMountProps {
+export interface AssemblyPartProps
+  extends AssemblyFaceMountProps,
+    AssemblyBomProps {
   /** Stable identity used by assembly selectors. */
   name: string
   /** Human-facing alternate to the stable name. */
@@ -29,6 +32,7 @@ export interface AssemblyPartProps extends AssemblyFaceMountProps {
 // Keep model validation separate from ordinary face-mount pairing.
 export const assemblyPartBaseProps = z
   .object({
+    ...assemblyBomProps.shape,
     name: z.string().trim().min(1),
     displayName: z.string().optional(),
     model: z.string().trim().min(1).optional(),

package/lib/assembly/printedpart.ts

@@ -1,3 +1,4 @@
+import { assemblyBomProps, type AssemblyBomProps } from "./bom"
 import { type CadModelProp, cadModelProp } from "lib/common/cadModel"
 import { url } from "lib/common/url"
 import { expectTypesMatch } from "lib/typecheck"
@@ -10,7 +11,9 @@ import {
 } from "./face-mounting"
 
 /** Provide exactly one of jscad, model, modelUrl, or cadModel. */
-export interface AssemblyPrintedPartProps extends AssemblyFaceMountProps {
+export interface AssemblyPrintedPartProps
+  extends AssemblyFaceMountProps,
+    AssemblyBomProps {
   /** Stable identity used by assembly mounting selectors. */
   name: string
   displayName?: string
@@ -33,6 +36,7 @@ export interface AssemblyPrintedPartProps extends AssemblyFaceMountProps {
 
 export const assemblyPrintedPartProps = z
   .object({
+    ...assemblyBomProps.shape,
     ...assemblyFaceMountShape,
     name: z.string().trim().min(1),
     displayName: z.string().optional(),

package/lib/assembly/screen.ts

@@ -1,9 +1,10 @@
+import { assemblyBomProps, type AssemblyBomProps } from "./bom"
 import { url } from "lib/common/url"
 import { type Distance, distance } from "lib/common/distance"
 import { expectTypesMatch } from "lib/typecheck"
 import { z } from "zod"
 
-export interface AssemblyScreenProps {
+export interface AssemblyScreenProps extends AssemblyBomProps {
   /** Stable product-level identity for the screen assembly. */
   name: string
   /** Imported CAD model URL. Mutually exclusive with cadModel where supported. */
@@ -41,6 +42,7 @@ const positiveDistance = (fieldName: "width" | "height") =>
 
 export const assemblyScreenProps = z
   .object({
+    ...assemblyBomProps.shape,
     name: nonemptyString("name"),
     model: z.string().trim().min(1).optional(),
     modelUrl: url

package/lib/assembly/subassembly.ts

@@ -1,3 +1,4 @@
+import { assemblyBomProps, type AssemblyBomProps } from "./bom"
 import { url } from "lib/common/url"
 import { type CadModelProp, cadModelProp } from "lib/common/cadModel"
 import { expectTypesMatch } from "lib/typecheck"
@@ -9,7 +10,9 @@ import {
   type AssemblyFaceMountProps,
 } from "./face-mounting"
 
-export interface AssemblySubassemblyProps extends AssemblyFaceMountProps {
+export interface AssemblySubassemblyProps
+  extends AssemblyFaceMountProps,
+    AssemblyBomProps {
   /** Stable identity used by selectors from other assembly elements. */
   name: string
   /** Imported CAD model URL. Mutually exclusive with cadModel where supported. */
@@ -26,6 +29,7 @@ export interface AssemblySubassemblyProps extends AssemblyFaceMountProps {
 
 export const assemblySubassemblyProps = z
   .object({
+    ...assemblyBomProps.shape,
     ...assemblyFaceMountShape,
     name: z.string().refine((value) => value.trim().length > 0, {
       message: "name cannot be empty",

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