feat: Add parameter shell to block (alternative to group)

Defining a block and placing elements into that block has the benefit
that you can use the ports to align the elements within the block to the
ports of that outer ("shell") block

doc/examples.typ

@@ -351,6 +351,29 @@ wire.stub("b-port-clk", "north")
 wire.stub("b-port-rdy", "south")
 ```)
 
+#let shell = example(```
+// A shell block acts as a container: port name labels are drawn
+// outside by default, and wires attach at the *inside* tip of
+// pentagon-shaped ports so child elements can sit within.
+element.block(
+  id: "sh", w: 5, h: 3, x: 0, y: 0,
+  shell: true,
+  port-shape: "pentagon",
+  fill: util.colors.blue.lighten(80%),
+  ports: (
+    west: ((id: "in",  name: "IN"),),
+    east: ((id: "out", name: "OUT", kind: "out"),),
+  ),
+  {
+    element.block(id: "inner", w: 2, h: 1.5, x: 1.5, y: 0.75,
+      fill: util.colors.yellow,
+      ports: (west: ((id: "a"),), east: ((id: "b"),)))
+  }
+)
+wire.wire("w-in",  ("sh-port-in",  "inner-port-a"))
+wire.wire("w-out", ("inner-port-b", "sh-port-out"))
+```)
+
 #let intersection = example(```
 wire.wire("w1", ((0, 0), (1, 1)), style: "zigzag")
 wire.wire("w2", ((0, 0), (1, -.5)),

src/elements/block.typ

@@ -25,7 +25,13 @@
 /// #examples.port-names-outside
 /// For other parameters description, see #doc-ref("element.elmt")
 /// - radius (number, length, ratio, dictionary): The corner radius of the block. See CeTZ documentation for more information
+/// - shell (bool): If true, the block behaves like a shell/container (analogous to a group): port name labels default to being drawn outside the block, and wires attach to the inside tip of pentagon-shaped ports. See #doc-ref("element.elmt")
+///
+/// Use `shell: true` to wrap child elements inside a bordered container without
+/// having ports overlap the interior:
+/// #examples.shell
 #let block(
+  ..args,
   x: none,
   y: none,
   w: none,
@@ -35,7 +41,7 @@
   ports: (),
   ports-margins: (),
   port-name-padding: 2pt,
-  port-names-outside: false,
+  port-names-outside: auto,
   port-shape: none,
   port-kind: "in",
   port-size: 1em,
@@ -43,11 +49,13 @@
   radius: 0.5em,
   stroke: black + 1pt,
   id: "",
+  shell: false,
   debug: (
     ports: false
   )
 ) = element.elmt(
   draw-shape: draw-shape.with(radius: radius),
+  body: if args.pos().len() > 0 { args.pos().first() } else { none },
   x: x,
   y: y,
   w: w,
@@ -64,5 +72,6 @@
   fill: fill,
   stroke: stroke,
   id: id,
+  shell: shell,
   debug: debug
 )

src/elements/element.typ

@@ -38,7 +38,7 @@
 ///   - `vertical` (`bool`): Whether the name should be drawn vertically
 /// - ports-margins (dictionary): Dictionary of ports margins (used with automatic port placement). They keys are cardinal directions ("north", "east", "south", "west"). The values are tuples of (`<start>`, `<end>`) margins (numbers)
 /// - port-name-padding (number, length): Padding between the port name label and the port anchor point (default `2pt`)
-/// - port-names-outside (bool): If true, port name labels are drawn on the outside of the block instead of the inside (default `false`)
+/// - port-names-outside (bool, auto): If true, port name labels are drawn on the outside of the block instead of the inside. When `auto` (default), follows the `shell` setting (outside if `shell: true`, inside otherwise)
 /// - port-shape (none, str): Default port shape for all ports of this element. Set to `"pentagon"` to draw pentagon-shaped ports. Overridable per port via the port's `shape` field. See #examples.port-shape
 /// - port-kind (str): Default direction of ports (`"in"` or `"out"`). Overridable per port via the port's `kind` field
 /// - port-size (length): Default unit size of pentagon-shaped ports (default `1em`). Overridable per port via the port's `size` field
@@ -47,6 +47,7 @@
 /// - id (str): The block id (for future reference)
 /// - auto-ports (bool): Whether to use auto port placements or not. If false, `draw-shape` is responsible for adding the appropiate ports
 /// - ports-y (dictionary): Dictionary of the ports y offsets (used with `auto-ports: false`)
+/// - shell (bool): If true, the block behaves like a shell/container (analogous to a group): port name labels default to being drawn *outside* the block border, and wires attach to the *inside* tip of pentagon-shaped ports instead of the outside base. Useful for wrapping child elements without having ports overlap them (default `false`)
 /// - debug (dictionary): Dictionary of debug options.
 ///
 ///   Supported fields include:
@@ -62,7 +63,7 @@
   ports: (:),
   ports-margins: (:),
   port-name-padding: 2pt,
-  port-names-outside: false,
+  port-names-outside: auto,
   port-shape: none,
   port-kind: "in",
   port-size: 1em,
@@ -71,6 +72,8 @@
   id: "",
   auto-ports: true,
   ports-y: (:),
+  shell: false,
+  body: none,
   debug: (
     ports: false
   )
@@ -145,6 +148,7 @@
   }
 
   if auto-ports {
+    let outside-name = if port-names-outside == auto { shell } else { port-names-outside }
     add-ports(
       id,
       tl, tr, br, bl,
@@ -152,12 +156,17 @@
       ports-margins,
       debug: debug.ports,
       name-padding: port-name-padding,
-      outside-name: port-names-outside,
+      outside-name: outside-name,
       port-shape: port-shape,
       port-kind: port-kind,
       port-size: port-size,
       elmt-stroke: stroke,
       elmt-fill: fill,
+      wire-inside: shell,
     )
   }
+
+  if body != none {
+    body
+  }
 })

src/elements/ports.typ

@@ -13,6 +13,7 @@
   port-size: 1em,
   elmt-stroke: black + 1pt,
   elmt-fill: none,
+  wire-inside: false,
 ) = {
   let name = port.at("name", default: "")
   let name-rotate = port.at("vertical", default: false)
@@ -80,6 +81,10 @@
   // (or from the boundary when shape is disabled).
   let label-pos = if outside-name { outer-pos } else { inner-pos }
 
+  // For "shell" containers, wires must attach at the inside of the pentagon
+  // (the tip that points inward), not at the exterior base.
+  let anchor-pos = if wire-inside and shape == "pentagon" { inner-pos } else { outer-pos }
+
   draw.content(
     label-pos,
     anchor: name-anchor,
@@ -91,7 +96,7 @@
 
   if debug {
     draw.circle(
-      outer-pos,
+      anchor-pos,
       name: id,
       radius: .1,
       stroke: none,
@@ -100,7 +105,7 @@
     
   } else {
     draw.hide(draw.circle(
-      outer-pos,
+      anchor-pos,
       radius: 0,
       stroke: none,
       name: id
@@ -121,6 +126,7 @@
   port-size: 1em,
   elmt-stroke: black + 1pt,
   elmt-fill: none,
+  wire-inside: false,
 ) = {
   let sides = (
     "north": (tl, tr),
@@ -177,6 +183,7 @@
         port-size: port-size,
         elmt-stroke: elmt-stroke,
         elmt-fill: elmt-fill,
+        wire-inside: wire-inside,
       )
     }
   }