kicadts 0.0.1 → 0.0.3

package/.github/workflows/bun-formatcheck.yml

@@ -0,0 +1,26 @@
+# Created using @tscircuit/plop (npm install -g @tscircuit/plop)
+name: Format Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  format-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run format check
+        run: bun run format:check

package/.github/workflows/bun-pver-release.yml

@@ -0,0 +1,70 @@
+# Created using @tscircuit/plop (npm install -g @tscircuit/plop)
+name: Publish to npm
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  UPSTREAM_REPOS: "" # comma-separated list, e.g. "eval,tscircuit,docs"
+  UPSTREAM_PACKAGES_TO_UPDATE: "" # comma-separated list, e.g. "@tscircuit/core,@tscircuit/protos"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.TSCIRCUIT_BOT_GITHUB_TOKEN }}
+      - name: Setup bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm install -g pver
+      - run: bun install --frozen-lockfile
+      - run: bun run build
+      - run: pver release
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.TSCIRCUIT_BOT_GITHUB_TOKEN }}
+
+      # - name: Create Pull Request
+      #   id: create-pr
+      #   uses: peter-evans/create-pull-request@v5
+      #   with:
+      #     commit-message: "chore: bump version"
+      #     title: "chore: bump version"
+      #     body: "Automated package update"
+      #     branch: bump-version-${{ github.run_number }}
+      #     base: main
+      #     token: ${{ secrets.TSCIRCUIT_BOT_GITHUB_TOKEN }}
+      #     committer: tscircuitbot <githubbot@tscircuit.com>
+      #     author: tscircuitbot <githubbot@tscircuit.com>
+
+      # - name: Enable auto-merge
+      #   if: steps.create-pr.outputs.pull-request-number != ''
+      #   run: |
+      #     gh pr merge ${{ steps.create-pr.outputs.pull-request-number }} --rebase --delete-branch
+      #   env:
+      #     GH_TOKEN: ${{ secrets.TSCIRCUIT_BOT_GITHUB_TOKEN }}
+
+      # - name: Trigger upstream repo updates
+      #   if: env.UPSTREAM_REPOS && env.UPSTREAM_PACKAGES_TO_UPDATE
+      #   run: |
+      #     IFS=',' read -ra REPOS <<< "${{ env.UPSTREAM_REPOS }}"
+      #     for repo in "${REPOS[@]}"; do
+      #       if [[ -n "$repo" ]]; then
+      #         echo "Triggering update for repo: $repo"
+      #         curl -X POST \
+      #           -H "Accept: application/vnd.github.v3+json" \
+      #           -H "Authorization: token ${{ secrets.TSCIRCUIT_BOT_GITHUB_TOKEN }}" \
+      #           -H "Content-Type: application/json" \
+      #           "https://api.github.com/repos/tscircuit/$repo/actions/workflows/update-package.yml/dispatches" \
+      #           -d "{\"ref\":\"main\",\"inputs\":{\"package_names\":\"${{ env.UPSTREAM_PACKAGES_TO_UPDATE }}\"}}"
+      #       fi
+      #     done

package/.github/workflows/bun-test.yml

@@ -0,0 +1,32 @@
+# Created using @tscircuit/plop (npm install -g @tscircuit/plop)
+name: Bun Test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    # Skip test for PRs that not chore: bump version
+    if: "${{ github.event_name != 'pull_request' || github.event.pull_request.title != 'chore: bump version' }}"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+      - run: bun run download-demos
+
+      - name: Run tests
+        run: bun test

package/.github/workflows/bun-typecheck.yml

@@ -0,0 +1,26 @@
+# Created using @tscircuit/plop (npm install -g @tscircuit/plop)
+name: Type Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  type-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun i
+
+      - name: Run type check
+        run: bunx tsc --noEmit

package/.vscode/settings.json

@@ -13,4 +13,4 @@
     "titleBar.inactiveForeground": "#15202b99"
   },
   "peacock.color": "#07d5c7"
-}
+}

package/AGENTS.md

@@ -28,3 +28,4 @@ most extensive one is `references/SEXPR_MAIN.adoc` (use `bun run scripts/downloa
 - NEW PATTERN: Never track the order of children unless absolutely necessary, use the `_sx*` properties and `getChildren` to return the children in a predefined order
 - NEW PATTERN: Never track unknown children, throw an error/allow an error to be thrown if you encounter a child PrimitiveSExpr that can't be parsed. You can introduce new `_sx*` properties and a new class to prevent the error
 - NEW PATTERN: One class per file
+- NEW PATTERN: Ergonomic constructors for classes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tscircuit Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -28,33 +28,33 @@ import {
   Xy,
 } from "kicadts"
 
-const schematic = new KicadSch()
-schematic.version = 20240101
-schematic.generator = "kicadts-demo"
-
-const title = new TitleBlock()
-title.title = "Demo Schematic"
-title.company = "Example Labs"
-schematic.titleBlock = title
-
-const paper = new Paper()
-paper.size = "A4"
-schematic.paper = paper
-schematic.properties = [new Property("Sheetfile", "demo.kicad_sch")]
-
-const sheet = new Sheet()
-sheet.position = new At([0, 0, 0])
-sheet.size = { width: 100, height: 80 }
-schematic.sheets = [sheet]
-
-const symbol = new SchematicSymbol()
-symbol.libraryId = "Device:R"
-symbol.at = new At([25.4, 12.7])
-schematic.symbols = [symbol]
-
-const wire = new Wire()
-wire.points = new Pts([new Xy(0, 0), new Xy(25.4, 12.7)])
-schematic.wires = [wire]
+const schematic = new KicadSch({
+  version: 20240101,
+  generator: "kicadts-demo",
+  titleBlock: new TitleBlock({
+    title: "Demo Schematic",
+    company: "Example Labs",
+  }),
+  paper: new Paper({ size: "A4" }),
+  properties: [new Property({ key: "Sheetfile", value: "demo.kicad_sch" })],
+  sheets: [
+    new Sheet({
+      position: [0, 0, 0], // Can use array instead of new At([0, 0, 0])
+      size: { width: 100, height: 80 },
+    }),
+  ],
+  symbols: [
+    new SchematicSymbol({
+      libraryId: "Device:R",
+      at: { x: 25.4, y: 12.7 }, // Can use object instead of new At([25.4, 12.7])
+    }),
+  ],
+  wires: [
+    new Wire({
+      points: new Pts([new Xy(0, 0), new Xy(25.4, 12.7)]),
+    }),
+  ],
+})
 
 await fs.writeFile("demo.kicad_sch", schematic.getString())
 ```
@@ -78,51 +78,57 @@ import {
   TextEffects,
 } from "kicadts"
 
-const pcb = new KicadPcb()
-pcb.version = 20240101
-pcb.generator = "kicadts-demo"
-
 const netGnd = new PcbNet(1, "GND")
 const netSignal = new PcbNet(2, "Net-(R1-Pad2)")
-pcb.nets = [netGnd, netSignal]
-
-const footprint = new Footprint()
-footprint.libraryLink = "Resistor_SMD:R_0603"
-footprint.layer = "F.Cu"
-footprint.position = new At([10, 5, 90])
-
-const makeText = (type: string, text: string, x: number, y: number, layer: string) => {
-  const fpText = new FpText()
-  fpText.type = type
-  fpText.text = text
-  fpText.position = new At([x, y])
-  fpText.layer = layer
-  const effects = new TextEffects()
-  effects.font.size = { height: 1, width: 1 }
-  effects.font.thickness = 0.15
-  fpText.effects = effects
-  return fpText
-}
-
-footprint.fpTexts = [
-  makeText("reference", "R1", 0, -1.5, "F.SilkS"),
-  makeText("value", "10k", 0, 1.5, "F.Fab"),
-]
-
-const pad = (number: string, x: number, net: PcbNet) => {
-  const fpPad = new FootprintPad(number, "smd", "roundrect")
-  fpPad.at = new At([x, 0])
-  fpPad.size = new PadSize(1.05, 0.95)
-  fpPad.layers = new PadLayers(["F.Cu", "F.Paste", "F.Mask"])
-  fpPad.roundrectRatio = 0.25
-  fpPad.net = new PadNet(net.id, net.name)
-  fpPad.pinfunction = number
-  fpPad.pintype = "passive"
-  return fpPad
-}
 
-footprint.fpPads = [pad("1", -0.8, netGnd), pad("2", 0.8, netSignal)]
-pcb.footprints = [footprint]
+const makeText = (
+  type: string,
+  text: string,
+  x: number,
+  y: number,
+  layer: string
+) =>
+  new FpText({
+    type,
+    text,
+    position: { x, y },
+    layer,
+    effects: new TextEffects({
+      font: { size: { height: 1, width: 1 }, thickness: 0.15 },
+    }),
+  })
+
+const pad = (number: string, x: number, net: PcbNet) =>
+  new FootprintPad({
+    number,
+    padType: "smd",
+    shape: "roundrect",
+    at: { x, y: 0 },
+    size: { width: 1.05, height: 0.95 },
+    layers: ["F.Cu", "F.Paste", "F.Mask"],
+    roundrectRatio: 0.25,
+    net: new PadNet(net.id, net.name),
+    pinfunction: number,
+    pintype: "passive",
+  })
+
+const pcb = new KicadPcb({
+  version: 20240101,
+  generator: "kicadts-demo",
+  nets: [netGnd, netSignal],
+  footprints: [
+    new Footprint({
+      libraryLink: "Resistor_SMD:R_0603",
+      layer: "F.Cu",
+      position: { x: 10, y: 5, angle: 90 },
+      fpTexts: [
+        makeText("reference", "R1", 0, -1.5, "F.SilkS"),
+        makeText("value", "10k", 0, 1.5, "F.Fab"),
+      ],
+      fpPads: [pad("1", -0.8, netGnd), pad("2", 0.8, netSignal)],
+    }),
+  ],
+})
 
 await fs.writeFile("demo.kicad_pcb", pcb.getString())
 ```
@@ -143,28 +149,32 @@ import {
   TextEffects,
 } from "kicadts"
 
-const footprint = new Footprint()
-footprint.libraryLink = "Demo:TestPad"
-footprint.layer = "F.Cu"
-footprint.position = new At([0, 0])
-
-const label = new FpText()
-label.type = "reference"
-label.text = "REF**"
-label.position = new At([0, -1.5])
-label.layer = "F.SilkS"
-const effects = new TextEffects()
-effects.font.size = { height: 1, width: 1 }
-effects.font.thickness = 0.15
-label.effects = effects
-
-footprint.fpTexts = [label]
-
-const pad = new FootprintPad("1", "smd", "rect")
-pad.at = new At([0, 0])
-pad.size = new PadSize(1.5, 1.5)
-pad.layers = new PadLayers(["F.Cu", "F.Paste", "F.Mask"])
-footprint.fpPads = [pad]
+const footprint = new Footprint({
+  libraryLink: "Demo:TestPad",
+  layer: "F.Cu",
+  position: [0, 0], // Array format
+  fpTexts: [
+    new FpText({
+      type: "reference",
+      text: "REF**",
+      position: { x: 0, y: -1.5 },
+      layer: "F.SilkS",
+      effects: new TextEffects({
+        font: { size: { height: 1, width: 1 }, thickness: 0.15 },
+      }),
+    }),
+  ],
+  fpPads: [
+    new FootprintPad({
+      number: "1",
+      padType: "smd",
+      shape: "rect",
+      at: [0, 0], // You can also use { x, y } form
+      size: { width: 1.5, height: 1.5 },
+      layers: ["F.Cu", "F.Paste", "F.Mask"],
+    }),
+  ],
+})
 
 await fs.writeFile("Demo_TestPad.kicad_mod", footprint.getString())
 ```

package/TODO.md

@@ -0,0 +1,46 @@
+# TODO: Ergonomic Constructors
+
+The following classes need ergonomic constructors created (similar to the pattern in `KicadSch.ts`):
+
+## Main Container Classes
+
+- [x] **KicadSch** - `lib/sexpr/classes/KicadSch.ts`
+- [ ] **Bus** - `lib/sexpr/classes/Bus.ts`
+- [ ] **BusEntry** - `lib/sexpr/classes/BusEntry.ts`
+- [ ] **Footprint** - `lib/sexpr/classes/Footprint.ts`
+- [ ] **FootprintPad** - `lib/sexpr/classes/FootprintPad.ts`
+- [ ] **FpArc** - `lib/sexpr/classes/FpArc.ts`
+- [ ] **FpCircle** - `lib/sexpr/classes/FpCircle.ts`
+- [ ] **FpLine** - `lib/sexpr/classes/FpLine.ts`
+- [ ] **FpPoly** - `lib/sexpr/classes/FpPoly.ts`
+- [ ] **FpRect** - `lib/sexpr/classes/FpRect.ts`
+- [ ] **FpText** - `lib/sexpr/classes/FpText.ts`
+- [ ] **FpTextBox** - `lib/sexpr/classes/FpTextBox.ts`
+- [ ] **GrLine** - `lib/sexpr/classes/GrLine.ts`
+- [ ] **GrText** - `lib/sexpr/classes/GrText.ts`
+- [ ] **Image** - `lib/sexpr/classes/Image.ts`
+- [ ] **Junction** - `lib/sexpr/classes/Junction.ts`
+- [ ] **KicadPcb** - `lib/sexpr/classes/KicadPcb.ts`
+- [ ] **Label** - `lib/sexpr/classes/Label.ts`
+- [ ] **NoConnect** - `lib/sexpr/classes/NoConnect.ts`
+- [ ] **PadPrimitiveGrArc** - `lib/sexpr/classes/PadPrimitiveGrArc.ts`
+- [ ] **PadPrimitiveGrCircle** - `lib/sexpr/classes/PadPrimitiveGrCircle.ts`
+- [ ] **Property** - `lib/sexpr/classes/Property.ts`
+- [ ] **SchematicText** - `lib/sexpr/classes/SchematicText.ts`
+- [ ] **Segment** - `lib/sexpr/classes/Segment.ts`
+- [ ] **Sheet** - `lib/sexpr/classes/Sheet.ts`
+- [ ] **Symbol** (SchematicSymbol) - `lib/sexpr/classes/Symbol.ts`
+- [ ] **TextEffects** - `lib/sexpr/classes/TextEffects.ts`
+- [ ] **TitleBlock** - `lib/sexpr/classes/TitleBlock.ts`
+- [ ] **Via** - `lib/sexpr/classes/Via.ts`
+- [ ] **Wire** - `lib/sexpr/classes/Wire.ts`
+
+## Pattern Requirements
+
+Each class needs:
+1. A TypeScript interface `{ClassName}ConstructorParams` with optional properties
+2. Properties should accept either primitive values (strings, numbers) OR SxClass wrapper objects
+3. Constructor that accepts the params interface and handles both cases
+4. Getter/setter pairs working with primitive values while storing SxClass objects internally
+
+See `lib/sexpr/classes/KicadSch.ts` for reference implementation.

package/bunfig.toml

@@ -1,5 +1,5 @@
-# [test]
-# preload = ["./tests/fixtures/preload.ts"]
+[test]
+preload = ["./tests/fixtures/preload.ts"]
 
 [install.lockfile]
 save = false

package/lib/sexpr/classes/At.ts

@@ -1,6 +1,11 @@
 import { SxClass } from "../base-classes/SxClass"
 import type { PrimitiveSExpr } from "../parseToPrimitiveSExpr"
 
+export type AtInput =
+  | At
+  | [x: number, y: number, angle?: number]
+  | { x: number; y: number; angle?: number }
+
 export class At extends SxClass {
   static override token = "at"
   token = "at"
@@ -22,6 +27,16 @@ export class At extends SxClass {
   y: number
   angle?: number
 
+  static from(input: AtInput, opts: { isTextSymbol?: boolean } = {}): At {
+    if (input instanceof At) {
+      return input
+    }
+    if (Array.isArray(input)) {
+      return new At(input, opts)
+    }
+    return new At([input.x, input.y, input.angle], opts)
+  }
+
   static override fromSexprPrimitives(primitiveSexprs: PrimitiveSExpr[]): At {
     const [x, y, angle] = primitiveSexprs
     return new At([x as number, y as number, angle as number])

package/lib/sexpr/classes/Bus.ts

@@ -6,6 +6,12 @@ import { Uuid } from "./Uuid"
 
 const SUPPORTED_TOKENS = new Set(["pts", "stroke", "uuid"])
 
+export interface BusConstructorParams {
+  points?: Pts
+  stroke?: Stroke
+  uuid?: string | Uuid
+}
+
 export class Bus extends SxClass {
   static override token = "bus"
   static override parentToken = "kicad_sch"
@@ -15,9 +21,23 @@ export class Bus extends SxClass {
   private _sxStroke?: Stroke
   private _sxUuid?: Uuid
 
-  static override fromSexprPrimitives(
-    primitiveSexprs: PrimitiveSExpr[],
-  ): Bus {
+  constructor(params: BusConstructorParams = {}) {
+    super()
+
+    if (params.points !== undefined) {
+      this.points = params.points
+    }
+
+    if (params.stroke !== undefined) {
+      this.stroke = params.stroke
+    }
+
+    if (params.uuid !== undefined) {
+      this.uuid = params.uuid
+    }
+  }
+
+  static override fromSexprPrimitives(primitiveSexprs: PrimitiveSExpr[]): Bus {
     const bus = new Bus()
 
     const { propertyMap, arrayPropertyMap } =

package/lib/sexpr/classes/BusEntry.ts

@@ -1,11 +1,18 @@
 import { SxClass } from "../base-classes/SxClass"
 import type { PrimitiveSExpr } from "../parseToPrimitiveSExpr"
-import { At } from "./At"
+import { At, type AtInput } from "./At"
 import { Stroke } from "./Stroke"
 import { Uuid } from "./Uuid"
 
 const SUPPORTED_TOKENS = new Set(["at", "size", "stroke", "uuid"])
 
+export interface BusEntryConstructorParams {
+  at?: AtInput
+  size?: BusEntrySize | { x: number; y: number }
+  stroke?: Stroke
+  uuid?: string | Uuid
+}
+
 export class BusEntry extends SxClass {
   static override token = "bus_entry"
   static override parentToken = "kicad_sch"
@@ -16,6 +23,26 @@ export class BusEntry extends SxClass {
   private _sxStroke?: Stroke
   private _sxUuid?: Uuid
 
+  constructor(params: BusEntryConstructorParams = {}) {
+    super()
+
+    if (params.at !== undefined) {
+      this.at = params.at
+    }
+
+    if (params.size !== undefined) {
+      this.size = params.size
+    }
+
+    if (params.stroke !== undefined) {
+      this.stroke = params.stroke
+    }
+
+    if (params.uuid !== undefined) {
+      this.uuid = params.uuid
+    }
+  }
+
   static override fromSexprPrimitives(
     primitiveSexprs: PrimitiveSExpr[],
   ): BusEntry {
@@ -52,8 +79,8 @@ export class BusEntry extends SxClass {
     return this._sxAt
   }
 
-  set at(value: At | undefined) {
-    this._sxAt = value
+  set at(value: AtInput | undefined) {
+    this._sxAt = value !== undefined ? At.from(value) : undefined
   }
 
   get size(): { x: number; y: number } | undefined {

package/lib/sexpr/classes/EmbeddedFonts.ts

@@ -41,9 +41,7 @@ export class EmbeddedFonts extends SxClass {
       if (normalized === "no") {
         return new EmbeddedFonts(false)
       }
-      throw new Error(
-        `embedded_fonts expects "yes" or "no", received "${raw}"`,
-      )
+      throw new Error(`embedded_fonts expects "yes" or "no", received "${raw}"`)
     }
 
     throw new Error(