@tscircuit/props 0.0.716 → 0.0.717

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