@tscircuit/props 0.0.626 → 0.0.627

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/package.json

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