@tscircuit/props 0.0.626 → 0.0.628

package/lib/common/implicitBreakoutPointSolver.ts

@@ -0,0 +1,71 @@
+export interface ImplicitBreakoutPoint {
+  readonly x: number
+  readonly y: number
+}
+
+export interface ImplicitBreakoutBounds {
+  readonly minX: number
+  readonly maxX: number
+  readonly minY: number
+  readonly maxY: number
+}
+
+export type ImplicitBreakoutEdge = "left" | "right" | "bottom" | "top"
+
+export interface ImplicitBreakoutRegion {
+  readonly regionId: string
+  readonly bounds: ImplicitBreakoutBounds
+  readonly edge: ImplicitBreakoutEdge
+}
+
+export interface ImplicitBreakoutConnectionEndpoint {
+  readonly regionId: string
+  readonly position: ImplicitBreakoutPoint
+}
+
+export interface ImplicitBreakoutConnection {
+  readonly connectionId: string
+  readonly endpoints: readonly ImplicitBreakoutConnectionEndpoint[]
+}
+
+export interface ImplicitBreakoutDifferentialPair {
+  readonly type: "differential"
+  readonly connections: readonly [
+    ImplicitBreakoutConnection,
+    ImplicitBreakoutConnection,
+  ]
+}
+
+export type ImplicitBreakoutConnectionOrDifferentialPair =
+  | ImplicitBreakoutConnection
+  | ImplicitBreakoutDifferentialPair
+
+export interface ImplicitBreakoutBus {
+  readonly busId: string
+  readonly connectionIds: readonly string[]
+  /** Ordered candidate layers that the solver may distribute this bus over. */
+  readonly targetLayers?: readonly string[]
+}
+
+export interface ImplicitBreakoutPointSolverInput {
+  readonly regions: readonly ImplicitBreakoutRegion[]
+  readonly connections: readonly ImplicitBreakoutConnectionOrDifferentialPair[]
+  readonly buses: readonly ImplicitBreakoutBus[]
+  readonly boundaryPointSpacing: number
+}
+
+export interface ImplicitBreakoutSolverPoint extends ImplicitBreakoutPoint {
+  readonly regionId: string
+  readonly connectionId: string
+  readonly layer: string
+}
+
+export interface ImplicitBreakoutPointSolverOutput {
+  readonly breakoutPoints: readonly ImplicitBreakoutSolverPoint[]
+}
+
+export type ImplicitBreakoutPointSolverFn = (
+  input: ImplicitBreakoutPointSolverInput,
+) =>
+  | ImplicitBreakoutPointSolverOutput
+  | Promise<ImplicitBreakoutPointSolverOutput>

package/lib/components/group.ts

@@ -33,6 +33,7 @@ import {
 } from "lib/common/schematicPinStyle"
 import { url } from "lib/common/url"
 import type { Connections } from "lib/utility-types/connections-and-selectors"
+import type { ImplicitBreakoutPointSolverFn } from "lib/common/implicitBreakoutPointSolver"
 
 export const layoutConfig = z.object({
   layoutMode: z
@@ -342,6 +343,8 @@ export interface AutorouterConfig {
     | /** @deprecated Use "sequential_trace" */ "sequential-trace"
   local?: boolean
   algorithmFn?: (simpleRouteJson: any) => Promise<any>
+  /** Override the solver used to place implicit breakout points. */
+  implicitBreakoutPointSolverFn?: ImplicitBreakoutPointSolverFn
   preset?:
     | "sequential_trace"
     | "subcircuit"
@@ -423,6 +426,11 @@ export const autorouterConfig = z.object({
       (v) => typeof v === "function" || v === undefined,
     )
     .optional(),
+  implicitBreakoutPointSolverFn: z
+    .custom<ImplicitBreakoutPointSolverFn>(
+      (value) => typeof value === "function" || value === undefined,
+    )
+    .optional(),
   preset: z
     .enum([
       "sequential_trace",

package/lib/components/pin-header.ts

@@ -45,6 +45,27 @@ export interface PinHeaderProps extends CommonComponentProps {
    */
   gender?: "male" | "female" | "unpopulated"
 
+  /**
+   * Mount the header on the top of the board, so it is connected to from
+   * above. An alias for `layer: "top"`, which is the default.
+   *
+   * Which side of the board a part sits on is `layer`, and only `layer`: the
+   * 3D model is always drawn top-side and consumers flip it for a bottom-layer
+   * component. Prefer these names on a connector, where "which side does the
+   * mating connector come from" is the question actually being asked.
+   */
+  connectsFromAbove?: boolean
+
+  /**
+   * Mount the header on the underside of the board, so it is connected to from
+   * below. An alias for `layer: "bottom"`.
+   *
+   * Not to be confused with `invert` on a footprint string, which installs a
+   * header BACKWARDS on whichever side it is on — long pins through the board
+   * rather than short ones.
+   */
+  connectsFromBelow?: boolean
+
   /**
    * Whether to show pin labels in silkscreen
    */
@@ -122,33 +143,61 @@ export interface PinHeaderProps extends CommonComponentProps {
   schHeight?: number | string
 }
 
-export const pinHeaderProps = commonComponentProps.extend({
-  pinCount: z.number(),
-  pitch: distance.optional(),
-  schFacingDirection: z.enum(["up", "down", "left", "right"]).optional(),
-  gender: z.enum(["male", "female", "unpopulated"]).optional().default("male"),
-  showSilkscreenPinLabels: z.boolean().optional(),
-  pcbPinLabels: z.record(z.string(), z.string()).optional(),
-  doubleRow: z.boolean().optional(),
-  rightAngle: z.boolean().optional(),
-  pcbOrientation: pcbOrientationProp.optional(),
-  holeDiameter: distance.optional(),
-  platedDiameter: distance.optional(),
-  pinLabels: z
-    .record(z.string(), schematicPinLabel)
-    .or(z.array(schematicPinLabel))
-    .optional(),
-  connections: z
-    .custom<Connections>()
-    .pipe(z.record(z.string(), connectionTarget))
-    .optional(),
-  facingDirection: z.enum(["left", "right"]).optional(),
-  schPinArrangement: schematicPinArrangement.optional(),
-  schPinStyle: schematicPinStyle.optional(),
-  schPinSpacing: distance.optional(),
-  schWidth: distance.optional(),
-  schHeight: distance.optional(),
-})
+export const pinHeaderProps = commonComponentProps
+  .extend({
+    pinCount: z.number(),
+    pitch: distance.optional(),
+    schFacingDirection: z.enum(["up", "down", "left", "right"]).optional(),
+    gender: z
+      .enum(["male", "female", "unpopulated"])
+      .optional()
+      .default("male"),
+    showSilkscreenPinLabels: z.boolean().optional(),
+    pcbPinLabels: z.record(z.string(), z.string()).optional(),
+    doubleRow: z.boolean().optional(),
+    rightAngle: z.boolean().optional(),
+    pcbOrientation: pcbOrientationProp.optional(),
+    holeDiameter: distance.optional(),
+    platedDiameter: distance.optional(),
+    pinLabels: z
+      .record(z.string(), schematicPinLabel)
+      .or(z.array(schematicPinLabel))
+      .optional(),
+    connections: z
+      .custom<Connections>()
+      .pipe(z.record(z.string(), connectionTarget))
+      .optional(),
+    facingDirection: z.enum(["left", "right"]).optional(),
+    schPinArrangement: schematicPinArrangement.optional(),
+    schPinStyle: schematicPinStyle.optional(),
+    schPinSpacing: distance.optional(),
+    schWidth: distance.optional(),
+    schHeight: distance.optional(),
+    connectsFromAbove: z.boolean().optional(),
+    connectsFromBelow: z.boolean().optional(),
+  })
+  // Resolved HERE rather than in each consumer: `layer` is read in dozens of
+  // places downstream, and an alias that only some of them understand is worse
+  // than no alias. After parsing there is one field to reason about again.
+  .superRefine((props, ctx) => {
+    if (props.connectsFromAbove && props.connectsFromBelow) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "connectsFromAbove and connectsFromBelow are opposites; set at most one",
+      })
+    }
+  })
+  .transform((props) => {
+    const layer =
+      props.layer ??
+      (props.connectsFromBelow
+        ? ("bottom" as const)
+        : props.connectsFromAbove
+          ? ("top" as const)
+          : undefined)
+    return layer === undefined ? props : { ...props, layer }
+  })
 
 type InferredPinHeaderProps = z.input<typeof pinHeaderProps>
 expectTypesMatch<PinHeaderProps, InferredPinHeaderProps>(true)

package/lib/index.ts

@@ -141,3 +141,4 @@ export * from "./utility-types/connections-and-selectors"
 export * from "./common/ninePointAnchor"
 export * from "./common/fanoutBoundaryPadding"
 export * from "./common/fanoutProps"
+export * from "./common/implicitBreakoutPointSolver"

package/package.json

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