From 99a0cb0bc46a79849de660e8a9be5a958e65d80c Mon Sep 17 00:00:00 2001 From: Rushabh Patil Date: Tue, 14 Jul 2026 16:36:25 +0530 Subject: [PATCH 1/4] Document exposed subcircuit ports --- docs/elements/port.mdx | 87 ++++++++++++++++++++++++++++++++---- docs/elements/subcircuit.mdx | 32 ++++++++++++- 2 files changed, 109 insertions(+), 10 deletions(-) diff --git a/docs/elements/port.mdx b/docs/elements/port.mdx index 5a1a599e..6a23f5da 100644 --- a/docs/elements/port.mdx +++ b/docs/elements/port.mdx @@ -1,18 +1,17 @@ --- title: description: >- - Define connection points within custom schematic symbols. + Define named connection points on custom symbols and subcircuits. --- import CircuitPreview from "@site/src/components/CircuitPreview" ## Overview -The `` element defines connection points within a ``. Ports specify where traces connect to your component in the schematic view. - -:::note -`` can only be used inside a `` element. -::: +The `` element creates a named point where traces can connect. Inside a +[``](./symbol.mdx), it defines the position of a component pin. As a +direct child of a [``](./subcircuit.mdx), it exposes an internal +connection so the rest of the circuit can connect to it by name. ## Basic Usage @@ -47,12 +46,82 @@ export default () => ( | Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| -| name | string | Yes | - | Port identifier used for connections | -| schX | number | Yes | - | X position in schematic units | -| schY | number | Yes | - | Y position in schematic units | +| name | string | No | - | Port identifier used in selectors. Required when `pinNumber` is omitted | +| pinNumber | number | No | - | Numeric pin identifier. Also creates `pinN` and `N` selector aliases | +| aliases | string[] | No | `[]` | Additional names that can select the port | +| connectsTo | string \| string[] | No | - | Internal port selector or selectors connected to a direct subcircuit port | +| schX | number | No | - | X position in schematic units for a custom symbol port | +| schY | number | No | - | Y position in schematic units for a custom symbol port | | direction | "left" \| "right" \| "up" \| "down" | No | - | Direction the port faces | | schStemLength | number | No | - | Length of the stem line extending from the port | +## Exposing a Subcircuit Connection + +A direct child `` becomes part of a subcircuit's public interface. Set +`connectsTo` to a selector for the internal component port, then connect from +the parent circuit using `SUBCIRCUIT_NAME.PORT_NAME`. + + ( + + + + + + + + + + + + + + + +) +`} /> + +Use `connectsTo="R1.pin1"` to choose which internal pin the port exposes. From +outside the subcircuit, reference it as `FILTER.INPUT`, using the subcircuit name +followed by the port name. + +The same connection can be written with an explicit trace selector: + +```tsx + +``` + +Only direct child ports form the subcircuit interface. The `showAsSchematicBox` +prop is optional, but when enabled, those ports become the pins on the collapsed +schematic box and the internal schematic is hidden. + +`connectsTo` also accepts an array when one exposed port must connect to more +than one internal port: + +```tsx + +``` + ## Custom Stem Length Use `schStemLength` to control how far the connection stem extends from the port: diff --git a/docs/elements/subcircuit.mdx b/docs/elements/subcircuit.mdx index 39a62ada..fd08bced 100644 --- a/docs/elements/subcircuit.mdx +++ b/docs/elements/subcircuit.mdx @@ -35,6 +35,37 @@ import CircuitPreview from "@site/src/components/CircuitPreview" `} /> +## Exposing Ports + +Subcircuit selectors are isolated by default. To give the parent circuit a +stable connection point without exposing an internal reference designator, add +a direct child [``](./port.mdx) with `connectsTo`: + +```tsx + + + + + + + +``` + +`connectsTo` is resolved inside the subcircuit, while `FILTER.OUTPUT` is +resolved by the parent circuit against the public port. You can therefore +rename or reorganize internal components without changing connections outside +the subcircuit. + +When `showAsSchematicBox` is enabled, direct child ports are displayed as the +box pins. Without it, the ports still define the public electrical interface. +See [the port documentation](./port.mdx#exposing-a-subcircuit-connection) for a +complete example and explicit trace selector syntax. + ## Reuse Reference Designators Reusing reference designators is typically considered a bad practice, but in @@ -87,4 +118,3 @@ when you have a tricky section of components that have special requirements. Read more about [the autorouter prop here](./board.mdx#setting-the-autorouter). - From 73ecf274a300d7c014754bc596970820de36886a Mon Sep 17 00:00:00 2001 From: Rushabh Patil Date: Tue, 14 Jul 2026 16:46:43 +0530 Subject: [PATCH 2/4] Place the subcircuit example on the PCB --- docs/elements/port.mdx | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/elements/port.mdx b/docs/elements/port.mdx index 6a23f5da..01147478 100644 --- a/docs/elements/port.mdx +++ b/docs/elements/port.mdx @@ -66,15 +66,29 @@ the parent circuit using `SUBCIRCUIT_NAME.PORT_NAME`. defaultView="schematic" code={` export default () => ( - + - - + + @@ -88,6 +102,8 @@ export default () => ( resistance="100" footprint="0402" schX={-5} + pcbX={-8} + pcbY={0} connections={{ pin1: "net.VCC", pin2: "FILTER.INPUT" }} /> ( resistance="10k" footprint="0402" schX={5} + pcbX={8} + pcbY={0} connections={{ pin1: "FILTER.OUTPUT", pin2: "net.GND" }} /> From 4c531a4b9a7a0c560ceba6d6ac150f001baec8a8 Mon Sep 17 00:00:00 2001 From: Rushabh Patil Date: Tue, 14 Jul 2026 16:51:33 +0530 Subject: [PATCH 3/4] Add a preview for exposed subcircuit ports --- docs/elements/subcircuit.mdx | 71 ++++++++++++++++++++++++++++-------- 1 file changed, 56 insertions(+), 15 deletions(-) diff --git a/docs/elements/subcircuit.mdx b/docs/elements/subcircuit.mdx index fd08bced..17bd92d6 100644 --- a/docs/elements/subcircuit.mdx +++ b/docs/elements/subcircuit.mdx @@ -41,20 +41,62 @@ Subcircuit selectors are isolated by default. To give the parent circuit a stable connection point without exposing an internal reference designator, add a direct child [``](./port.mdx) with `connectsTo`: -```tsx - - - - - - - -``` + ( + + + + + + + + + + + + + + + +) +`} /> `connectsTo` is resolved inside the subcircuit, while `FILTER.OUTPUT` is resolved by the parent circuit against the public port. You can therefore @@ -117,4 +159,3 @@ Specifying custom autorouter settings for subcircuits can be extremely useful when you have a tricky section of components that have special requirements. Read more about [the autorouter prop here](./board.mdx#setting-the-autorouter). - From 494a1a0a12b1c764b24b292f0ac6612d3ef840fb Mon Sep 17 00:00:00 2001 From: Rushabh Patil Date: Tue, 14 Jul 2026 17:05:24 +0530 Subject: [PATCH 4/4] Simplify the subcircuit port preview --- docs/elements/subcircuit.mdx | 40 +++++++++--------------------------- 1 file changed, 10 insertions(+), 30 deletions(-) diff --git a/docs/elements/subcircuit.mdx b/docs/elements/subcircuit.mdx index 17bd92d6..3d5ee57b 100644 --- a/docs/elements/subcircuit.mdx +++ b/docs/elements/subcircuit.mdx @@ -46,59 +46,39 @@ a direct child [``](./port.mdx) with `connectsTo`: defaultView="schematic" code={` export default () => ( - - + + - - - - - ) `} /> -`connectsTo` is resolved inside the subcircuit, while `FILTER.OUTPUT` is +`connectsTo` is resolved inside the subcircuit, while `MODULE.OUTPUT` is resolved by the parent circuit against the public port. You can therefore rename or reorganize internal components without changing connections outside the subcircuit.