gum-jsx 1.6.2 → 1.6.4

package/scripts/test.ts

@@ -13,51 +13,6 @@ function loadFile(path: string, encoding: string = 'utf8') {
         : readFileSync(file, encoding as BufferEncoding)
 }
 
-function matchNumbers(text: string, pattern: RegExp, message: string): number[] {
-    const match = text.match(pattern)
-    if (match == null) throw new Error(message)
-    return match.slice(1).map(Number)
-}
-
-function rotatePoint([ x, y ]: number[], angle: number, [ cx, cy ]: number[]): number[] {
-    const theta = angle * Math.PI / 180
-    const [ dx, dy ] = [ x - cx, y - cy ]
-    const [ COS, SIN ] = [ Math.cos(theta), Math.sin(theta) ]
-    return [ cx + dx * COS - dy * SIN, cy + dx * SIN + dy * COS ]
-}
-
-function midpoint(p0: number[], p1: number[]): number[] {
-    return [ (p0[0] + p1[0]) / 2, (p0[1] + p1[1]) / 2 ]
-}
-
-function dot(p0: number[], p1: number[]): number {
-    return p0[0] * p1[0] + p0[1] * p1[1]
-}
-
-function assertGraphArrowHeadForward(svg: string) {
-    const line = matchNumbers(svg, /<line x1="([-\d.]+)" y1="([-\d.]+)" x2="([-\d.]+)" y2="([-\d.]+)"/, 'Missing arrow shaft')
-    const path = matchNumbers(svg, /<path d="M ([-\d.]+),([-\d.]+) L ([-\d.]+),([-\d.]+) M [-\d.]+,[-\d.]+ L ([-\d.]+),([-\d.]+)"/, 'Missing arrow head')
-    const rotate = matchNumbers(svg, /transform="rotate\(([-\d.]+), ([-\d.]+), ([-\d.]+)\)"/, 'Missing arrow head transform')
-
-    const [ x1, y1, x2, y2 ] = line
-    const [ tipx, tipy, base0x, base0y, base1x, base1y ] = path
-    const [ angle, cx, cy ] = rotate
-    const center = [ cx, cy ]
-    const tip = rotatePoint([ tipx, tipy ], angle, center)
-    const base = midpoint(
-        rotatePoint([ base0x, base0y ], angle, center),
-        rotatePoint([ base1x, base1y ], angle, center),
-    )
-    const shaft = [ x2 - x1, y2 - y1 ]
-    const head = [ tip[0] - base[0], tip[1] - base[1] ]
-    if (dot(shaft, head) <= 0) throw new Error('Arrow head points opposite the shaft')
-}
-
-function assertRoundedLineCornerCircular(svg: string) {
-    const [ rx, ry ] = matchNumbers(svg, /<path d="[^"]* A ([-\d.]+),([-\d.]+) /, 'Missing rounded corner arc')
-    if (Math.abs(rx - ry) > 1e-6) throw new Error(`RoundedLine corner arc is skewed: ${rx},${ry}`)
-}
-
 const dirs = ['docs/code', 'gala/code']
 let passed = 0
 let failed = 0
@@ -80,30 +35,6 @@ for (const dir of dirs) {
     }
 }
 
-try {
-    const code = '<Frame aspect={1.2}><Graph coord={[0, 0, 1, 1]}><Arrow points={[[0.25, 0.25], [0.75, 0.75]]} /></Graph></Frame>'
-    const elem = evaluateGum(code, { size: 500, theme: 'dark', loadFile })
-    assertGraphArrowHeadForward(elem.svg())
-    console.log('PASS regression Graph Arrow wide aspect')
-    passed++
-} catch (e: any) {
-    const { message = 'Unknown error' } = e
-    console.error(`FAIL regression Graph Arrow wide aspect: ${message}`)
-    failed++
-}
-
-try {
-    const code = '<Frame aspect={4}><RoundedLine points={[[0.1,0.2],[0.5,0.2],[0.5,0.8]]} radius={0.1} /></Frame>'
-    const elem = evaluateGum(code, { size: 500, theme: 'dark', loadFile })
-    assertRoundedLineCornerCircular(elem.svg())
-    console.log('PASS regression RoundedLine circular corners')
-    passed++
-} catch (e: any) {
-    const { message = 'Unknown error' } = e
-    console.error(`FAIL regression RoundedLine circular corners: ${message}`)
-    failed++
-}
-
 console.log()
 console.error(`${passed} passed`)
 console.error(`${failed} failed`)

package/skills/gum-jsx/SKILL.md

@@ -160,30 +160,27 @@ Below is the full documentation for the core `gum.jsx` components: `Element`, `G
 
 ## Element
 
-The base class for all `gum.jsx` objects. You will usually not be working with this object directly unless you are implementing your own custom elements. An **Element** has a few methods that can be overriden, each of which takes a **Context** object as an argument. The vast majority of implementations will override only `props` and `inner` (for non-unary elements).
+The base class for all Gum objects. You will usually not be working with this object directly unless you are implementing your own custom elements. However, many of the arguments are common to all elements and are documented here.
 
-The position and size of an element are specified in the internal coordinates (`coord`) of its parent, which defaults to the unit square. Rectangles are always specified in `[left, top, right, bottom]` format. You can also specify the placement by specifying `pos` and `size` or various combinations of `xsize`/`ysize`. When not specified, `rect` defaults to the unit square.
+The position and size of an element are specified in the internal coordinates (`coord`) of its parent, which defaults to the unit square. Rectangles are always specified in `[left, top, right, bottom]` format. Where the element is placed is ultimately determined by its `rect`. However, it is more common to specify the `rect` using one of the convenience parameters below.
+
+There are several convenience parameters that can be used to specify the `rect` in a more intuitive way. These include `size`/`xsize`/`ysize` for controlling the extent of the rectangle around `pos` and the analogous `rad`/`xrad`/`yrad` for radial specification. You can also specify the limits in either or both dimensions with `xrect`/`yrect`, where a single number is interpreted as a zero-length limit at that position.
+
+The `expand` parameter can be used to control whether the element should be expanded to fully contain its `rect`. This is useful if you have an aspected element with a desired size in one dimension. A very common case is a **Text** element where you specify `pos` and `ysize` and leave the width to be determined by the aspect ratio.
 
 Parameters:
-- `tag` = `g` — the SVG tag associated with this element
-- `unary` = `false` — whether there is inner text for this element
 - `aspect` = `null` — the width to height ratio for this element
+- `rect` — a fully specified rectangle to place the child in (takes precedence over other parameters)
 - `pos` — the desired position of the center of the child's rectangle
-- `size` ­— the desired size of the child's rectangle (can be single number or pair)
-- `xsize`/`ysize` ­— specify the size for a specific dimension (and expand the other)
-- `rect` — a fully specified rectangle to place the child in (this will override `pos`/`size`)
-- `aspect` — the aspect ratio of the child's rectangle
+- `size`/`xsize`/`ysize` ­— the desired size of the child's rectangle (`size` can be single number or pair)
+- `rad`/`xrad`/`yrad` — the desired radius of the child's rectangle (`rad` can be single number or pair)
+- `xrect`/`yrect` — the limits of the child's rectangle in the x and y dimensions (both can be single number or pair)
 - `expand` — when `true`, instead of embedding the child within `rect`, it will make the child just large enough to fully contain `rect`
 - `align` — how to align the child when it doesn't fit exactly within `rect`, options are `left`, `right`, `center`, or a fractional position (can set vertical and horizontal separately with a pair)
 - `rotate` — how much to rotate the child by (degrees counterclockwise)
 - `spin` — like rotate but will maintain the same size
 - `flex` ­— override to set `aspect = null`
-- `...` = `{}` — additional attributes that are included in `props`
-
-Methods:
-- `props(ctx)` — returns a dictionary of attributes for the SVG element. The default implementation returns the non-null `attr` passed to the constructor
-- `inner(ctx)` — returns the inner text of the SVG element (for non-unary). Defaults to returing empty string
-- `svg(ctx)` — returns the rendered SVG of the element as a `String`. Default implementation constructs SVG from `tag`, `unary`, `props`, and `inner`
+- `...` = `{}` — additional attributes are applied directly to the resulting SVG
 
 **Example**
 
@@ -234,7 +231,7 @@ Generated code:
 
 This is a simple container class allowing you to add padding, margins, and a border to a single **Element**. It's pretty versatile and is often used to set up the outermost positioning of a figure. Mirroring the standard CSS definitions, padding is space inside the border and margin is space outside the border. This has no border by default, but there is a specialized subclass of this called **Frame** that defaults to `border = 1`.
 
-**Box** can be pretty handly in various situations. It is differentiated from **Group** in that it will adopt the `aspect` of the child element. This is useful if you want to do something like shift an element up or down by a certain amount while maintaining its aspect ratio. Simply wrap it in a **Box** and set child's `pos` to the desired offset.
+**Box** can be pretty handly in various situations. It is differentiated from **Group** in that it will adopt the `aspect` of the first child element. This is useful if you want to do something like shift an element up or down by a certain amount while maintaining its aspect ratio. Simply wrap it in a **Box** and set child's `pos` to the desired offset.
 
 There are multiple ways to specify padding and margins. If given as a scalar, it is constant across all sides. If two values are given, they correspond to the horizontal and vertical sides. If four values are given, they correspond to `[left, top, right, bottom]`.
 

package/skills/gum-jsx/references/gala/atomic_orbitals.md

@@ -38,8 +38,7 @@ const dz2_r = (t) => 0.28 * abs(3 * cos(t) ** 2 - 1)
 // plot radial orbital lobes via SymSpline
 const OrbitalLobe = ({ rfn, t0, t1, sign }) =>
   <SymSpline N={50} tlim={[t0, t1]}
-    fx={t => rfn(t) * cos(t)}
-    fy={t => rfn(t) * sin(t)}
+    f={t => polar(t, rfn(t))}
     stroke={sign ? pos_col : neg_col}
     fill={sign ? pos_fill : neg_fill}
     stroke-width={2} opacity={0.6}

package/skills/gum-jsx/references/gala/complex_plot.md

@@ -14,7 +14,7 @@ const Curve = ({ fx, stroke }) => <SymLine fx={fx} ylim={ylim} stroke={stroke} s
 const xlabel = <Latex>x = a + bi</Latex>
 const ylabel = <Latex>c</Latex>
 return <Plot aspect={2} margin={0.3} xlim={xlim} ylabel={ylabel} xlabel={xlabel} ylabel-offset={0.075}>
-  <Mesh2D xlocs={41} ylocs={21} xlim={xlim} ylim={ylim} opacity={0.3} />
+  <Mesh2D xlocs={41} ylocs={21} xlim={xlim} ylim={ylim} opacity={0.1} />
   <HLine loc={0} lim={xlim} opacity={0.3} />
   <VLine loc={0} lim={ylim} opacity={0.3} />
   <Curve fx={y => -y + sqrt(maximum(0, y*y-1))} stroke={blue} />

package/skills/gum-jsx/references/gala/pendulum_physics.md

@@ -29,9 +29,9 @@ const arcRad = 0.25
 // Computed positions
 const rodRot = 90 - rodAng
 const eqnY = pivotY + rodLen
-const [ bobX, bobY ] = polar(rodRot, rodLen, [pivotX, pivotY])
-const [ midX, midY ] = polar(rodRot, 0.50 * rodLen, [pivotX, pivotY])
-const [ tenX, tenY ] = polar(rodRot, 0.75 * rodLen, [pivotX, pivotY])
+const [ bobX, bobY ] = polard(rodRot, rodLen, [pivotX, pivotY])
+const [ midX, midY ] = polard(rodRot, 0.50 * rodLen, [pivotX, pivotY])
+const [ tenX, tenY ] = polard(rodRot, 0.75 * rodLen, [pivotX, pivotY])
 
 return <Box margin={0.06}>
   <VStack spacing={0.05}>

package/skills/gum-jsx/references/gala/plot_manual.md

@@ -11,8 +11,8 @@ const aspect = 2
 const ratio = pi / aspect
 return <Box margin={0.3}>
   <Group coord={[0, 1, 2*pi, -1]} aspect={aspect}>
-    <HMesh locs={5} lim={[0, 2*pi]} opacity={0.3} />
-    <VMesh locs={5} lim={[-1, 1]} opacity={0.3} />
+    <HMesh locs={5} opacity={0.15} />
+    <VMesh locs={5} opacity={0.15} />
     <HAxis ticks={5} lim={[0, 2*pi]} pos={[pi, -1]} size={[2*pi, 0.08]} />
     <VAxis ticks={5} lim={[-1, 1]} pos={[0, 0]} size={[0.08*ratio, 2]} />
     <SymLine fy={sin} xlim={[0, 2*pi]} />

package/skills/gum-jsx/references/gala/polygon_slide.md

@@ -16,11 +16,10 @@ const shapes = [
 ]
 
 const RegularPolygon = ({ n, ...args }) =>
-  <SymShape {...args}
-    aspect spin={90*(n-2)/n}
+  <SymShape {...args} aspect
     xlim={[-1, 1]} ylim={[-1, 1]}
-    tvals={linspace(0, 2*pi, n+1)}
-    fx={cos} fy={sin}
+    tvals={linspace(0, 2*pi, n, false)}
+    f={t => polar(t+pi/2*(n-2)/n)}
   />
 
 return <Slide title="Simple Regular Polygons" wrap={25}>

package/skills/gum-jsx/references/gala/spline_star.md

@@ -19,8 +19,8 @@ const theta0 = linspace(0, 2 * pi, n, false).map(t => t - pi / 2)
 const theta1 = theta0.map(t => t + pi / n)
 
 // get inner/outer point positions
-const points0 = theta0.map(t => polar(t * r2d))
-const points1 = theta1.map(t => polar(t * r2d, R))
+const points0 = theta0.map(t => polar(t))
+const points1 = theta1.map(t => polar(t, R))
 const points = zip(points0, points1).flat()
 
 // return full spline

package/skills/gum-jsx/references/geometry.md

@@ -33,8 +33,8 @@ Prompt: two ellipses, one wider and one taller
 Generated code:
 ```jsx
 <Group>
-  <Ellipse pos={[0.3, 0.2]} size={[0.4, 0.2]} />
-  <Ellipse pos={[0.6, 0.6]} size={[0.4, 0.5]} />
+  <Ellipse pos={[0.3, 0.2]} rad={[0.2, 0.1]} />
+  <Ellipse pos={[0.6, 0.6]} rad={[0.2, 0.25]} />
 </Group>
 ```
 
@@ -57,8 +57,8 @@ Prompt: elliptical and circular arcs using start and end angles
 Generated code:
 ```jsx
 <Group>
-  <Arc pos={[0.3, 0.5]} size={[0.4, 0.3]} start={-45} end={210} stroke={blue} stroke-width={2} />
-  <Arc pos={[0.7, 0.5]} size={0.3} start={90} end={-150} stroke={red} stroke-width={2} />
+  <Arc pos={[0.3, 0.5]} rad={[0.2, 0.15]} start={-45} end={210} stroke={blue} stroke-width={2} />
+  <Arc pos={[0.7, 0.5]} rad={0.15} start={90} end={-150} stroke={red} stroke-width={2} />
 </Group>
 ```
 
@@ -81,7 +81,7 @@ Prompt: draw a piecewise line spiraling outwards (with dots at vertices)
 
 Generated code:
 ```jsx
-const spiral = linspace(0, 5, 25).map(t => polar(360 * t, t/5))
+const spiral = linspace(0, 5, 25).map(t => polar(2*pi * t, t/5))
 return <Box margin>
   <Graph coord={[-1, -1, 1, 1]}>
     <Line points={spiral} />
@@ -107,7 +107,7 @@ Prompt: draw a stop sign
 
 Generated code:
 ```jsx
-const hexagon = linspace(0, 360, 8, false).map(t => polar(t))
+const hexagon = linspace(0, 2*pi, 8, false).map(t => polar(t))
 return <Box fill="#bbb" rounded padding margin>
   <Graph xlim={[-1, 1]} ylim={[-1, 1]} aspect={1}>
     <Shape points={hexagon} fill="#CC0202" stroke={white} stroke_width={20} spin={180/8} />

package/skills/gum-jsx/references/layout.md

@@ -6,7 +6,7 @@
 
 This is a simple container class allowing you to add padding, margins, and a border to a single **Element**. It's pretty versatile and is often used to set up the outermost positioning of a figure. Mirroring the standard CSS definitions, padding is space inside the border and margin is space outside the border. This has no border by default, but there is a specialized subclass of this called **Frame** that defaults to `border = 1`.
 
-**Box** can be pretty handly in various situations. It is differentiated from **Group** in that it will adopt the `aspect` of the child element. This is useful if you want to do something like shift an element up or down by a certain amount while maintaining its aspect ratio. Simply wrap it in a **Box** and set child's `pos` to the desired offset.
+**Box** can be pretty handly in various situations. It is differentiated from **Group** in that it will adopt the `aspect` of the first child element. This is useful if you want to do something like shift an element up or down by a certain amount while maintaining its aspect ratio. Simply wrap it in a **Box** and set child's `pos` to the desired offset.
 
 There are multiple ways to specify padding and margins. If given as a scalar, it is constant across all sides. If two values are given, they correspond to the horizontal and vertical sides. If four values are given, they correspond to `[left, top, right, bottom]`.
 
@@ -124,7 +124,10 @@ Prompt: A plot of three different increasing curves of varying steepness and mul
 
 Generated code:
 ```jsx
-<Plot xlim={[-1, 1]} ylim={[-1, 1]} grid margin={0.3} aspect xlabel="time (seconds)" ylabel="space (meters)" title="Spacetime Vibes">
+<Plot coord={[-1, -1, 1, 1]} margin={0.2} grid
+  xlabel="time (seconds)" ylabel="space (meters)"
+  title="Spacetime Vibes"
+>
   <Points point-size={0.04} points={[
     [0, 0.5], [0.5, 0], [-0.5, 0], [0, -0.5]
   ]} />

package/skills/gum-jsx/references/networks.md

@@ -103,6 +103,6 @@ Generated code:
   <Node id="test" pos={[0.75, 0.25]} wrap={6}>This is a test of wrapping capabilities</Node>
   <Node id="ball" pos={[0.75, 0.75]}><Ellipse aspect={1.5} fill={blue}/></Node>
   <Edge start="hello" end="test" />
-  <Edge start="hello" end="ball" start-side="s" curve={3} />
+  <Edge start="hello" end="ball" start-side="s" />
 </Network>
 ```

package/skills/gum-jsx/references/symbolic.md

@@ -4,11 +4,12 @@
 
 *Inherits*: **Group** > **Element**
 
-Flexible interface to generate sets of points symbolically or in combination with fixed inputs. The most common usage is to specify the range for x-values with `xlim` and a function to plot with `fy`. But you can specify the transpose with `ylim`/`fx`, or do a fully parametric path using `tlim`/`fx`/`fy`.
+Flexible interface to generate sets of points symbolically or in combination with fixed inputs. The most common usage is to specify the range for x-values with `xlim` and a function to plot with `fy`. But you can specify the transpose with `ylim`/`fx`, or do a fully parametric path using `tlim` with either `f` or `fx`/`fy`.
 
 You can also specify point size functionally with `point-size` and the shape with `point-shape`. Both of these functions take `(x, y, t, i)` values as inputs and return the desired value for each point. As with other groups, the **SymPoints** element itself can still be laid out with the normal `size`/`xsize`/`ysize` element parameters.
 
 Parameters:
+- `f` — a function mapping t-values to `[x, y]` points
 - `fx`/`fy` — a function mapping from x-values, y-values, or t-values
 - `point-size` = `0.05` — a size or a function mapping from `(x, y, t, i)` values to a size
 - `point-shape` = `Dot` — a shape or function mapping from `(x, y, t, i)` values to a shape
@@ -35,9 +36,10 @@ return <Plot xlim={[0, 2*pi]} ylim={[-1.5, 1.5]} grid fill={lightgray} margin={[
 
 Flexible interface to generate two-dimensional paths symbolically or in combination with fixed inputs. There are variety of acceptable input combinations, but the most common usage is to specify the range to use for x-values with `xlim` and a function to plot with `fy`. To plot a polygon instead of a line, use **SymShape**.
 
-Alternatively, you can specify the transpose with `ylim`/`fx`, or even do a fully parametric path using `tlim`/`fx`/`fy`. In any of these cases, one can either specify limits with `xlim`/`ylim`/`tlim` or specific values with `xvals`/`yvals`/`tvals`.
+Alternatively, you can specify the transpose with `ylim`/`fx`, or do a fully parametric path using `tlim` with either `f` or `fx`/`fy`. In any of these cases, one can either specify limits with `xlim`/`ylim`/`tlim` or specific values with `xvals`/`yvals`/`tvals`.
 
 Parameters:
+- `f` — a function mapping t-values to `[x, y]` points
 - `fx`/`fy` — a function mapping from x-values, y-values, or t-values
 - `xlim`/`ylim`/`tlim` — a pair of numbers specifying variable limits
 - `xvals`/`yvals`/`tvals` — a list of x-values, y-values, or t-values to use
@@ -59,9 +61,10 @@ Generated code:
 
 *Inherits*: **Shape** > **Pointstring** > **Element**
 
-Flexible interface to generate shapes symbolically or in combination with fixed inputs. Operates similarly to **Shape**, but generates a shape from the points generated by `fx`/`fy`.
+Flexible interface to generate shapes symbolically or in combination with fixed inputs. Operates similarly to **Shape**, but generates a shape from points generated by `f` or `fx`/`fy`.
 
 Parameters:
+- `f` — a function mapping t-values to `[x, y]` points
 - `fx`/`fy` — a function mapping from x-values, y-values, or t-values
 - `xlim`/`ylim`/`tlim` — a pair of numbers specifying variable limits
 - `xvals`/`yvals`/`tvals` — a list of x-values, y-values, or t-values to use
@@ -73,12 +76,11 @@ Prompt: Draw a rounded star shape with a blue fill. Wrap it in a rounded frame.
 
 Generated code:
 ```jsx
-const rad = t => 1 - 0.3 * cos(2.5 * t)**2
+const rad = t => 1 - 0.2 * cos(5 * (t - pi/2))
 return <Frame rounded padding margin>
   <SymShape aspect fill={blue}
     tlim={[0, 2*pi]} N={200}
-    fx={t => rad(t) * sin(t)}
-    fy={t => rad(t) * cos(t)}
+    f={t => polar(t, rad(t))}
   />
 </Frame>
 ```
@@ -91,6 +93,7 @@ Flexible interface to generate smooth two-dimensional spline curves symbolically
 
 
 Parameters:
+- `f` — a function mapping t-values to `[x, y]` points
 - `fx`/`fy` — a function mapping from x-values, y-values, or t-values
 - `xlim`/`ylim`/`tlim` — a pair of numbers specifying variable limits
 - `xvals`/`yvals`/`tvals` — a list of x-values, y-values, or t-values to use
@@ -118,9 +121,10 @@ return <Plot xlim={[0, 2*pi]} ylim={[-1, 1]} grid margin={0.15} aspect={phi}>
 
 *Inherits*: **Fill** > **Shape**  > **Pointstring** > **Element**
 
-Flexible interface to generate filled in paths symbolically or in combination with fixed inputs. This generates a polygon by running through the points generated by `fx1`/`fy1` and then backwards through the points generated by `fx2`/`fy2`. To generate a simple filled curve, pass your function to `fy1` and let `fy2` be `0`.
+Flexible interface to generate filled in paths symbolically or in combination with fixed inputs. This generates a polygon by running through the points generated by `f1` or `fx1`/`fy1` and then backwards through the points generated by `f2` or `fx2`/`fy2`. To generate a simple filled curve, pass your function to `fy1` and let `fy2` be `0`.
 
 Parameters:
+- `f1`/`f2` — functions mapping t-values to `[x, y]` points for either bound
 - `fx1`/`fy1` — a function generating one of the bounds for the fill (or a constant)
 - `fx2`/`fy2` — a function generating the other bound for the fill (or a constant)
 - `xlim`/`ylim`/`tlim` — a pair of numbers specifying variable limits
@@ -135,7 +139,7 @@ Generated code:
 ```jsx
 const decay = x => exp(-0.1*x) * sin(x)
 return <Graph xlim={[0, 6*pi]} ylim={[-1, 1]} aspect={phi}>
-  <SymFill fy1={decay} fy2={0} fill={blue} fill-opacity={0.5} N={250} />
+  <SymFill f1={t => [t, decay(t)]} f2={t => [t, 0]} tlim={[0, 6*pi]} fill={blue} fill-opacity={0.5} N={250} />
   <SymLine fy={decay} N={250} />
 </Graph>
 ```

package/skills/gum-jsx/references/utilities.md

@@ -29,25 +29,28 @@ Here we collect a variety of global mathematical functions and constants. You ca
 - `round(x)` — the rounding function
 - `clamp(x, lim=[0, 1])` — clamp `x` to the range `lim`
 - `rescale(x, lim=[0, 1])` — linearly rescale `x` to the range `lim`
-- `polar(angle, radius=1, center=[0, 0])` — convert polar coordinates (`angle` in degrees, `radius` scalar or size vector) to a 2D point around `center`
+- `polar(theta, radius=1, center=[0, 0])` — convert polar coordinates (`theta` in radians, `radius` scalar or size vector) to a 2D point around `center`
+- `polard(angle, radius=1, center=[0, 0])` — same as `polar` but takes `angle` in degrees
 
 Angles use gum's usual screen-space convention: `0` points right and `90` points down.
 
 **Example**
 
-Prompt: embed a five point star in a circle. place red dots at its vertices.
+Prompt: draw a spirograph in a box for a set of example parameters
 
 Generated code:
 ```jsx
-const verts = linspace(0, 360, 10, false).map((t, i) => {
-  const radius = i % 2 == 0 ? 1 : 0.5
-  return polar(90 + t, radius)
-})
-return <Graph aspect coord={[-1, -1, 1, 1]}>
-  <Circle pos={[0, 0]} size={2} stroke={darkgray} />
-  <Shape points={verts} stroke={blue} stroke-width={2} />
-  {verts.map(pos => <Dot pos={pos} size={0.05} fill={red} />)}
-</Graph>
+const [R, r, d, k] = [10, 7, 4, 7]
+const fx = t => (R - r) * cos(t) + d * cos(((R - r) / r) * t)
+const fy = t => (R - r) * sin(t) - d * sin(((R - r) / r) * t)
+return <TitleFrame title="Spirograph" padding={0.2} margin rounded>
+  <Graph aspect coord={[-R, -R, R, R]}>
+    <Circle pos={[0, 0]} rad={R} stroke={darkgray} stroke-dasharray={10} />
+    <Circle pos={[0, 0]} rad={R - r} stroke-dasharray={5} />
+    <SymSpline fx={fx} fy={fy} tlim={[0, 2*pi*k]} stroke={blue} stroke-width={2} />
+  </Graph>
+  <Span pos={[0.5, 1.1]} ysize={0.05} font-family={mono}>R = 10 | r = 7 | d = 4</Span>
+</TitleFrame>
 ```
 
 ## Arrays
@@ -146,9 +149,10 @@ Prompt: load "data.csv" and plot each row as a blue dot
 
 Generated code:
 ```jsx
-return <Graph xlim={[0, 10]} ylim={[0, 10]}>
+return <Graph aspect coord={[0, 0, 10, 10]}>
+  <Mesh2D xlocs={10} ylocs={10} opacity={0.25} />
   {loadTable('data.csv').map(({ x, y }) =>
-    <Dot pos={[x, y]} rad={0.1} fill={blue} />
+    <Dot pos={[x, y]} size={0.5} fill={blue} />
   )}
 </Graph>
 ```
@@ -171,7 +175,7 @@ Generated code:
 ```jsx
 <Box rounded clip>
   <Group aspect={2}>
-    <LoadImage id="image.png" xsize={1} />
+    <LoadImage id="image.png" xrect={[0, 1]} />
   </Group>
 </Box>
 ```

package/src/elems/core.ts

@@ -2,10 +2,10 @@
 
 import { THEME } from '../lib/theme'
 import { DEFAULTS as D, svgns, sans, light, blue, red, d2r } from '../lib/const'
-import { is_scalar, abs, cos, sin, tan, cot, mul2, div2, filter_object, expand_rect, rect_box, cbox_rect, rect_cbox, merge_points, merge_rects, ensure_vector, broadcast_point, rounder, heavisign, abs_min, abs_max, rect_radial, rotate_aspect, remap_rect, rescaler, resizer, rect_size, vector_angle, polar, upright_rect } from '../lib/utils'
+import { is_scalar, abs, cos, sin, tan, cot, mul2, div2, filter_object, expand_rect, rect_box, cbox_rect, rect_cbox, merge_points, merge_rects, join_limits, ensure_pair, rounder, heavisign, abs_min, abs_max, rect_radial, rotate_aspect, remap_rect, rescaler, resizer, rect_size, vector_angle, polard, upright_rect } from '../lib/utils'
 import { random } from '../lib/rng'
 
-import type { Point, Rect, Size, AlignValue, Align, Side, Attrs, MNumber, MPoint, Spec } from '../lib/types'
+import type { Point, Rect, Size, AlignValue, Align, Side, Attrs, MNumber, MPoint, Spec, Limit } from '../lib/types'
 
 //
 // rect embedding
@@ -118,7 +118,7 @@ function adjust_rotate(rotate: number, prect: Rect, coord: Rect): number {
     const csize = rect_size(coord)
     const psize = rect_size(prect)
     const proj = div2(psize, csize)
-    const vec = polar(rotate, proj)
+    const vec = polard(rotate, proj)
     return vector_angle(vec)
 }
 
@@ -217,7 +217,7 @@ class Context {
         const transform = rotate1 ? rotate_repr(rotate1, [ x0, y0 ], this.prec) : undefined
 
         // broadcast align into [ halign, valign ] components
-        const [ hafrac, vafrac ] = ensure_vector(align, 2).map(align_frac)
+        const [ hafrac, vafrac ] = ensure_pair(align).map(align_frac)
         const [ x, y ] = [
             x0 + (0.5 - hafrac) * (w - w0),
             y0 + (0.5 - vafrac) * (h - h0),
@@ -259,7 +259,7 @@ function props_repr(d: Attrs, prec: number): string {
 
 // reserved keys
 const SPEC_KEYS = [ 'rect', 'coord', 'aspect', 'aspect0', 'expand', 'align', 'upright', 'offset', 'rotate', 'rotate_adjust', 'rotate_invar' ]
-const HELP_KEYS = [ 'pos', 'size', 'xsize', 'ysize', 'flex', 'spin', 'orient' ]
+const HELP_KEYS = [ 'pos', 'size', 'xsize', 'ysize', 'rad', 'xrad', 'yrad', 'xrect', 'yrect', 'flex', 'spin', 'orient' ]
 const EXTR_KEYS = [ 'stack_size' ]
 const RESERVED_KEYS = [ ...SPEC_KEYS, ...HELP_KEYS, ...EXTR_KEYS ]
 
@@ -300,6 +300,11 @@ interface ElementArgs extends SpecArgs {
     size?: number | Size
     xsize?: number
     ysize?: number
+    rad?: number | Size
+    xrad?: number
+    yrad?: number
+    xrect?: number | Limit
+    yrect?: number | Limit
     flex?: boolean
     spin?: number
     orient?: number
@@ -316,7 +321,7 @@ class Element {
     attr: Attrs
 
     constructor(args: ElementArgs = {}) {
-        const { tag, unary, children, pos, size, xsize, ysize, flex, spin, orient, ...attr0 } = args
+        const { tag, unary, children, pos, size: size0, xsize: xsize0, ysize: ysize0, rad, xrad, yrad, xrect, yrect, flex, spin, orient, ...attr0 } = args
         const [ spec, attr ] = spec_split(attr0, false)
         this.args = args
 
@@ -332,12 +337,27 @@ class Element {
         this.spec = spec
         this.attr = attr
 
-        // handle pos/size conveniences
-        if (pos != null || size != null || xsize != null || ysize != null) {
-            const has_xy = xsize != null || ysize != null
-            const size1 = has_xy ? [ xsize ?? 0, ysize ?? 0 ] as Point : undefined
-            this.spec.rect ??= cbox_rect([ ...(pos ?? D.pos), ...(broadcast_point(size ?? size1 ?? D.size)) ])
-            if (has_xy) this.spec.expand = true
+        // handle pos/rad/xrad/yrad conveniences
+        const [ x, y ] = pos ?? D.pos
+        const size = rad != null ? mul2(rad, 2) : size0
+        const xsize = xrad != null ? 2 * xrad : xsize0
+        const ysize = yrad != null ? 2 * yrad : ysize0
+
+        // handle rect conveniences
+        if (this.spec.rect != null) {
+            // already have a rect
+        } else if (size != null) {
+            const [ w, h ] = ensure_pair(size)
+            this.spec.rect = cbox_rect([ x, y, w, h ])
+        } else if (xrect != null || yrect != null) {
+            const xrect1 = ensure_pair(xrect ?? x)
+            const yrect1 = ensure_pair(yrect ?? y)
+            this.spec.rect = join_limits({ h: xrect1, v: yrect1 })
+            if (xrect == null || yrect == null) this.spec.expand = true
+        } else if (xsize != null || ysize != null) {
+            const [ w, h ] = ensure_pair([ xsize ?? 0, ysize ?? 0 ])
+            this.spec.rect = cbox_rect([ x, y, w, h ])
+            if (xsize == null || ysize == null) this.spec.expand = true
         }
 
         // various convenience conversions
@@ -642,7 +662,7 @@ class Svg extends Group {
     constructor(args: SvgArgs = {}) {
         const { children: children0, size : size0 = D.svg_size, padding = 1, bare = false, dims = true, filters, aspect: aspect0 = 'auto', view: view0, style, xmlns = svgns, font_family = sans, font_weight = light, prec = D.prec, ...attr } = THEME(args, 'Svg')
         const children = ensure_children(children0)
-        const size_base = broadcast_point(size0)
+        const size_base = ensure_pair(size0)
 
         // precompute aspect info
         const aspect = aspect0 == 'auto' ? children_aspect(children) : aspect0

package/src/elems/geometry.ts

@@ -1,9 +1,9 @@
 // geometry elements
 
 import { THEME } from '../lib/theme'
-import { DEFAULTS as D, d2r, none, gray } from '../lib/const'
-import { is_boolean, is_scalar, is_array, ensure_vector, ensure_point, check_array, upright_limits, rounder, abs, rect_radial, make_mpoint, squeeze_mpoint, merge_points, broadcast_point, sub2m, add2, sub2, mul2, div2, norm, angle_direc, unit_direc, vector_angle, polar, prefix_split} from '../lib/utils'
-import { cubic_spline_data } from '../lib/interp'
+import { DEFAULTS as D, none, gray } from '../lib/const'
+import { is_boolean, is_scalar, is_array, ensure_vector, ensure_point, check_array, upright_limits, rounder, abs, rect_radial, make_mpoint, merge_points, ensure_pair, add2, sub2, mul2, div2, norm, angle_direc, unit_direc, vector_angle, polard, prefix_split} from '../lib/utils'
+import { cubic_spline_data, cubic_spline_tangent } from '../lib/interp'
 import { Context, Element, Group, Rectangle } from './core'
 
 import type { Point, Rect, Limit, Grad, Attrs, MPoint, Orient, Rounded, Direc } from '../lib/types'
@@ -126,6 +126,31 @@ class CoordLine extends Line {
     }
 }
 
+interface SegmentsArgs extends ElementArgs {
+  edges?: [Point, Point][]
+}
+
+class Segments extends Element {
+  edges: [Point, Point][]
+
+  constructor(args: SegmentsArgs = {}) {
+    const { edges = [], ...attr } = args
+    super({ tag: 'path', unary: true, ...attr })
+    this.args = args
+    this.edges = edges
+  }
+
+  props(ctx: Context): Attrs {
+    const attr = super.props(ctx)
+    const d = this.edges.map(([e0, e1]) => {
+      const [p0, p1] = ctx.mapPoint(e0)
+      const [q0, q1] = ctx.mapPoint(e1)
+      return `M ${rounder(p0, ctx.prec)},${rounder(p1, ctx.prec)} L ${rounder(q0, ctx.prec)},${rounder(q1, ctx.prec)}`
+    }).join(' ')
+    return { d, ...attr }
+  }
+}
+
 //
 // shape classes
 //
@@ -186,12 +211,11 @@ interface RayArgs extends LineArgs {
 class Ray extends Line {
     constructor(args: RayArgs = {}) {
         const { angle = 0, loc = D.pos, size = 0.5, ...attr } = THEME(args, 'Ray')
-        const theta = angle * d2r
         const [ x, y ] = loc
         const [ rx, ry ] = ensure_vector(size, 2)
         const points: Point[] = [
             [ x, y ],
-            polar(theta, [ rx, ry ], [ x, y ])
+            polard(angle, [ rx, ry ], [ x, y ])
         ]
         super({ points, ...attr })
         this.args = args
@@ -553,9 +577,8 @@ class CubicSplineCmd extends Command {
 
     args(ctx: Context): string {
         // use dir if provided, otherwise use tan
-        const dist = squeeze_mpoint(sub2m(this.pos2, this.pos1)).map(abs) as Point
-        const tan1 = this.dir1 != null ? mul2(this.dir1, dist) : this.tan1
-        const tan2 = this.dir2 != null ? mul2(this.dir2, dist) : this.tan2
+        const tan1 = cubic_spline_tangent(this.pos1, this.pos2, this.dir1, this.tan1)
+        const tan2 = cubic_spline_tangent(this.pos1, this.pos2, this.dir2, this.tan2)
         if (tan1 == null || tan2 == null) throw new Error('Spline tangent must be defined')
 
         // compute scaled tangents
@@ -624,7 +647,7 @@ function parse_rounded(rounded: Rounded): Point[] {
         const [ rx, ry ] = rounded
         rounded = [[rx, ry], [rx, ry], [rx, ry], [rx, ry]]
     }
-    return rounded.map(broadcast_point)
+    return rounded.map(ensure_pair)
 }
 
 interface RoundedRectArgs extends ElementArgs {
@@ -717,9 +740,9 @@ class Arc extends Path {
     constructor(args: ArcArgs = {}) {
         const { start, end, upright = true, ...attr } = THEME(args, 'Arc')
         if (start == null || end == null) throw new Error('Must provide `start` and `end` angles')
-        const [ theta0, theta1 ] = upright_limits([ start, end ])
-        const large = (theta1 - theta0) > 180
-        const [ point0, point1 ] = [ theta0, theta1 ].map(t => polar(t, 0.5, [0.5, 0.5]))
+        const [ angle0, angle1 ] = upright_limits([ start, end ])
+        const large = (angle1 - angle0) > 180
+        const [ point0, point1 ] = [ angle0, angle1 ].map(t => polard(t, 0.5, [0.5, 0.5]))
         const children = [ new MoveCmd(point0), new ArcCmd(point1, 0.5, true, large) ]
         super({ children, upright, ...attr })
         this.args = args
@@ -837,5 +860,5 @@ class Arrow extends Group {
 // exports
 //
 
-export { Line, UnitLine, VLine, HLine, CoordLine, Square, Ellipse, Arc, Circle, Dot, Ray, Pointstring, Shape, Triangle, Fill, VFill, HFill, Path, Command, MoveCmd, LineCmd, ArcCmd, CornerCmd, RoundedCornerCmd, CubicSplineCmd, Spline, RoundedRect, RoundedLine, ArrowHead, Arrow }
-export type { LineArgs, UnitLineArgs, CoordLineArgs, ArcArgs, DotArgs, RayArgs, SplineArgs, RoundedRectArgs, RoundedLineArgs, ArrowHeadArgs, ArrowArgs, CubicSplineCmdArgs, FillArgs }
+export { Line, UnitLine, VLine, HLine, CoordLine, Segments, Square, Ellipse, Arc, Circle, Dot, Ray, Pointstring, Shape, Triangle, Fill, VFill, HFill, Path, Command, MoveCmd, LineCmd, ArcCmd, CornerCmd, RoundedCornerCmd, CubicSplineCmd, Spline, RoundedRect, RoundedLine, ArrowHead, Arrow }
+export type { LineArgs, UnitLineArgs, CoordLineArgs, SegmentsArgs, ArcArgs, DotArgs, RayArgs, SplineArgs, RoundedRectArgs, RoundedLineArgs, ArrowHeadArgs, ArrowArgs, CubicSplineCmdArgs, FillArgs }