gum-jsx 1.6.2 → 1.6.3

package/README.md

@@ -91,11 +91,10 @@ CLI options:
 | Option | Description | Default |
 |--------|-------------|---------|
 | `file` | Gum JSX file to render | stdin |
-| `-s, --size <size>` | Image size in pixels | 1000 |
+| `-s, --size <size>` | SVG/viewBox size in pixels | 1000 |
 | `-t, --theme <theme>` | Theme: `light` or `dark` | light |
 | `-b, --background <color>` | Background color | white |
 | `-f, --format <format>` | Format: `json`, `svg`, `png`, `kitty` | auto |
 | `-o, --output <output>` | Output file | stdout |
-| `-w, --width <width>` | Max width of the PNG | auto |
-| `-h, --height <height>` | Max height of the PNG | auto |
+| `-r, --raster-size <size>` | Max rasterized PNG size | auto |
 | `-d, --dev` | Live update display | off |

package/docs/code/Arc.jsx

@@ -1,5 +1,5 @@
 // elliptical and circular arcs using start and end angles
 <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>

package/docs/code/Ellipse.jsx

@@ -1,5 +1,5 @@
 // two ellipses, one wider and one taller
 <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>

package/docs/code/Images.jsx

@@ -1,6 +1,6 @@
 // load "image.png" and display a 2x1 clip from the center
 <Box rounded clip>
   <Group aspect={2}>
-    <LoadImage id="image.png" xsize={1} />
+    <LoadImage id="image.png" xrect={[0, 1]} />
   </Group>
 </Box>

package/docs/code/Line.jsx

@@ -1,5 +1,5 @@
 // draw a piecewise line spiraling outwards (with dots at vertices)
-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} />

package/docs/code/Math.jsx

@@ -1,10 +1,12 @@
-// embed a five point star in a circle. place red dots at its vertices.
-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>
+// draw a spirograph in a box for a set of example parameters
+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>

package/docs/code/Network.jsx

@@ -4,5 +4,5 @@
   <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/docs/code/Points.jsx

@@ -1,5 +1,8 @@
 // A plot of three different increasing curves of varying steepness and multiple points spaced at regular intervals. The x-axis label is "time (seconds)", the y-axis label is "space (meters)", and the title is "Spacetime Vibes". There are axis ticks in both directions with assiated faint grid lines.
-<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/docs/code/Shape.jsx

@@ -1,5 +1,5 @@
 // draw a stop sign
-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/docs/code/SymFill.jsx

@@ -1,6 +1,6 @@
 // a decaying sine wave filled in with blue
 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/docs/code/SymShape.jsx

@@ -1,9 +1,8 @@
 // Draw a rounded star shape with a blue fill. Wrap it in a rounded frame.
-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>
+</Frame>

package/docs/code/Tables.jsx

@@ -1,6 +1,7 @@
 // load "data.csv" and plot each row as a blue dot
-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>

package/docs/text/Box.md

@@ -4,7 +4,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](/docs/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](/docs/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/docs/text/Element.md

@@ -1,26 +1,23 @@
 # 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](/docs/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](/docs/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

package/docs/text/Gum.md

@@ -1,15 +1,15 @@
 # Gum
 
-Welcome to the `gum.jsx` docs! Click on an item in the list on the left to get more info about a particular class (usually an [Element](/docs/Element), function, or constant).
+Welcome to the Gum documentation! Click on an item in the list on the left to get more info about a particular class (usually an [Element](/docs/Element), function, or constant).
 
-Each entry has a description of the operation and arguments of the item and an associated example code snippet. You can edit the code snippet, but note that these will get clobbered if you navigate to another entry! Go to the [main editor](/) for non-ephemeral work.
+Each entry has a description of the operation and arguments of the item and an associated example code snippet. You can edit the code snippet, but note that these will get clobbered if you navigate to another entry! Go to the [main editor](/gum/studio) for non-ephemeral work.
 
-The syntax is an XML component style one familiar to React developers. The output is pure SVG. You can nest objects in interesting ways and specify their parameters. Positions and sizes are specified proportionally (i.e. between `0` and `1`), but some quantities like `border` or `stroke-width` are specified in absolute units.
+The syntax is a JSX component style familiar to React developers. The output is pure SVG. You can nest objects in interesting ways and specify their parameters. Positions and sizes are specified proportionally (i.e. between `0` and `1`), but some quantities like `border` or `stroke-width` are still specified in pixel units.
 
 ## Common Patterns
 
 *Parameter specification*: You can specify boolean parameters like `border` just by writing their name. Some parameters, such as `margin` or `padding` default to `0` when not specified, but also take a specific value when specified as boolean `true` (in both cases `0.1`). You can also pass SVG properties such as `stroke-width` directly.
 
-*Subunit arguments*: for compound elements that inherit [Group](/docs/Group), some keyword arguments are passed down to the constituent parts. For instance, in [Plot](/docs/Plot), one can specify arguments intended for the `XAxis` unit by prefixing them with `xaxis-`. For example, setting the `stroke-width` for this subunit can be achieved with `xaxis-stroke-width`.
+*Subunit arguments*: for compound elements that inherit [Group](/docs/Group), some keyword arguments are passed down to the constituent parts. For instance, in [Plot](/docs/Plot), one can specify arguments intended for the [XAxis](/docs/Axis) unit by prefixing them with `xaxis-`. For example, setting the `stroke-width` for this subunit can be achieved with `xaxis-stroke-width`.
 
-*Constructive layout*: we try to avoid hard-coding absolute values as much as possible. Instead, we use proportions relative to the parent element's size. For instance, `margin = 0.1` means "10% of the parent's width/height". Similarly, instead of manually positioning elements in a row, we use [HStack](/docs/HStack) or [VStack](/docs/VStack) to automatically arrange them.
+*Constructive layout*: we try to avoid hard-coding absolute values as much as possible. Instead, we use proportions relative to the parent element's size. For instance, `margin = 0.1` means "10% of the parent's width/height". Similarly, instead of manually positioning elements in a row, we use [HStack](/docs/Stack) or [VStack](/docs/Stack) to automatically arrange them.

package/docs/text/Math.md

@@ -27,6 +27,7 @@ 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.

package/docs/text/SymFill.md

@@ -2,9 +2,10 @@
 
 *Inherits*: [Fill](/docs/Fill) > [Shape](/docs/Shape)  > **Pointstring** > [Element](/docs/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

package/docs/text/SymLine.md

@@ -4,9 +4,10 @@
 
 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](/docs/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

package/docs/text/SymPoints.md

@@ -2,11 +2,12 @@
 
 *Inherits*: [Group](/docs/Group) > [Element](/docs/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

package/docs/text/SymShape.md

@@ -2,9 +2,10 @@
 
 *Inherits*: [Shape](/docs/Shape) > **Pointstring** > [Element](/docs/Element)
 
-Flexible interface to generate shapes symbolically or in combination with fixed inputs. Operates similarly to [Shape](/docs/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](/docs/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

package/docs/text/SymSpline.md

@@ -6,6 +6,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

package/gala/code/atomic_orbitals.jsx

@@ -27,8 +27,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/gala/code/complex_plot.jsx

@@ -3,7 +3,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/gala/code/pendulum_physics.jsx

@@ -18,9 +18,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/gala/code/plot_manual.jsx

@@ -2,8 +2,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/gala/code/polygon_slide.jsx

@@ -5,11 +5,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/gala/code/spline_star.jsx

@@ -8,8 +8,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gum-jsx",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "Language for vector graphics generation.",
   "type": "module",
   "author": "Douglas Hanley",

package/scripts/gum.ts

@@ -4,7 +4,7 @@ import { Command } from 'commander'
 import { readFileSync, writeFileSync } from 'fs'
 import { dirname, resolve } from 'path'
 
-import { evaluateGum } from '../src/eval'
+import { evaluateGum, fitSize } from '../src/eval'
 import { rasterizeSvg, formatImage, readStdin } from '../src/render'
 import { Element, Group } from '../src/elems/core'
 import type { CliArgs, LoadFile } from '../src/lib/types'
@@ -16,7 +16,7 @@ import { devCommand } from './dev'
 
 function transformArgs(cmd: Command) {
   const [ file0 ] = cmd.args
-  let { format, output, theme, background, size, width, height, dev } = cmd.opts()
+  let { format, output, theme, background, size, rasterSize, dev } = cmd.opts()
 
   // add white background for light theme
   if (theme == 'light' && background == null) background = 'white'
@@ -41,7 +41,7 @@ function transformArgs(cmd: Command) {
       : readFileSync(file, encoding as BufferEncoding)
   }
 
-  return { file, format, output, theme, background, size, width, height, dev, loadFile }
+  return { file, format, output, theme, background, size, rasterSize, dev, loadFile }
 }
 
 //
@@ -64,7 +64,7 @@ function convertToTree(elem: Element): any {
 //
 
 async function runCommand(args: CliArgs) {
-  const { file, format, output, theme, background, size: size0 = 1000, width, height, dev, loadFile } = args
+  const { file, format, output, theme, background, size: size0 = 1000, rasterSize, dev, loadFile } = args
 
   // divert to dev command if update is on
   if (dev) {
@@ -77,8 +77,6 @@ async function runCommand(args: CliArgs) {
 
   // evaluate gum with size
   const elem = evaluateGum(code, { size: size0, theme, loadFile })
-  const svg = format != 'json' ? elem.svg() : ''
-  const size = elem.size
 
   // rasterize output
   let out: string | Buffer
@@ -86,9 +84,15 @@ async function runCommand(args: CliArgs) {
     const tree = convertToTree(elem)
     out = JSON.stringify(tree, null, 2)
   } else if (format == 'svg') {
-    out = svg
+    out = elem.svg()
   } else if (format == 'png' || format == 'kitty') {
-    const dat = await rasterizeSvg(svg, { size, width, height, background })
+    let svg = elem.svg()
+    if (rasterSize != null) {
+      const [ rasterWidth, rasterHeight ] = fitSize(elem.size, rasterSize)
+      const elem1 = elem.clone({ width: rasterWidth, height: rasterHeight })
+      svg = elem1.svg()
+    }
+    const dat = await rasterizeSvg(svg, { background })
     out = (format == 'kitty') ? (formatImage(dat) + '\n') : dat
   } else {
     throw new Error(`Unsupported output format: ${format}`)
@@ -112,9 +116,8 @@ program.name('gum')
   .option('-f, --format <format>', 'format to output')
   .option('-t, --theme <theme>', 'theme to use', 'light')
   .option('-b, --background <background>', 'background color')
-  .option('-s, --size <size>', 'size of the SVG', (value: string) => parseInt(value))
-  .option('-w, --width <width>', 'width of the PNG', (value: string) => parseInt(value))
-  .option('-h, --height <height>', 'height of the PNG', (value: string) => parseInt(value))
+  .option('-s, --size <size>', 'SVG/viewBox size', (value: string) => parseInt(value))
+  .option('-r, --raster-size <size>', 'max rasterized PNG size', (value: string) => parseInt(value))
   .option('-o, --output <output>', 'output file')
   .action(async function(this: Command) {
     const args = transformArgs(this)

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} />