gum-jsx 1.5.0 → 1.5.1

package/README.md

@@ -1,23 +1,25 @@
 <div align="center">
-<img src="image/logo.png" alt="logo" width="500" />
+<img src="images/logo.svg" alt="logo" width="500" />
 <br/>
 </div>
 
 <div align="center">
-<img src="image/nexus.svg" alt="nexus" width="250" />
+<img src="images/nexus.svg" alt="nexus" width="250" />
 <br/><br/>
 </div>
 
-A language for creating visualizations using a React-like JSX dialect that evaluates to SVG. Designed for general graphics, plots, graphs, and network diagrams.
+Gum is a JSX language for creating visualizations that evaluates to SVG. It's designed for general graphics, plots, graphs, and network diagrams.
 
 Head to **[compendiumlabs.ai/gum](https://compendiumlabs.ai/gum)** for a live demo and documentation. For Python bindings, see [gum.py](https://github.com/CompendiumLabs/gum.py).
 
 # Installation
 
 ```bash
-bun i gum-jsx
+bun i -g gum-jsx
 ```
 
+To download the skill file (which is just a zip), click on the release on the right or use `skills/gum-jsx.skill`.
+
 # Usage
 
 Write some `gum.jsx` code:
@@ -38,7 +40,7 @@ const svg = elem.svg()
 
 Which will produce the following:
 
-<img src="image/plot.png" alt="sine wave plot" width="750" />
+<img src="images/plot.svg" alt="sine wave plot" width="750" />
 
 You can also use JavaScript directly:
 
@@ -58,25 +60,25 @@ You can use the `gum` command to convert `gum.jsx` into SVG text or PNG data. Yo
 Generate an SVG from a `gum.jsx` file:
 
 ```bash
-cat input.jsx | bun run cli -f svg > output.svg
+cat input.jsx | gum -f svg > output.svg
 ```
 
 Generate a PNG from a `gum.jsx` file:
 
 ```bash
-cat input.jsx | bun run cli -f png > output.png
+cat input.jsx | gum -f png > output.png
 ```
 
 Display a `gum.jsx` file in the terminal:
 ```bash
-cat input.jsx | bun run cli
+cat input.jsx | gum
 ```
 
 CLI options:
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `-s, --size <size>` | Image size in pixels | 500 |
+| `-s, --size <size>` | Image size in pixels | 1000 |
 | `-t, --theme <theme>` | Theme: `light` or `dark` | light |
 | `-w, --width <width>` | Width of the PNG | null |
 | `-h, --height <height>` | Height of the PNG | null |

package/package.json

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

package/prompt/gen.md

@@ -1,6 +1,6 @@
 # Using CLI commands
 
-To test the output of a particular `gum.jsx` snippet or file, you can pipe it to the `gum` command, which is assumed to be installed globally. If you have vision capabilities, this can be useful for see the actual output of the code, either in SVG or PNG format. Even without vision, one can infer properties of the output by reading the SVG output directly.
+To test the output of a particular Gum JSX snippet or file, you can pipe it to the `gum` command, which is assumed to be installed globally. If you have vision capabilities, this can be useful for see the actual output of the code, either in SVG or PNG format. Even without vision, one can infer properties of the output by reading the SVG output directly.
 
 For one off tests, pipe the code using `echo`. It is recommended that you use single quotes as the outer delimiter, to accommodate code that includes double quotes for component properties (e.g. `justify="left"`).
 
@@ -10,10 +10,10 @@ In general, it makes a lot of sense to write a draft to a file, view its output,
 
 **Examples:**
 ```bash
-# Generate SVG from a gum.jsx snippet
+# Generate SVG from a Gum JSX snippet
 echo '<Rectangle rounded fill={blue} />' | gum -f svg > output.svg
 
-# Generate PNG from a gum.jsx snippet
+# Generate PNG from a Gum JSX snippet
 echo '<Rectangle rounded fill={blue} />' | gum -f png > output.png
 
 # Generate SVG from a .jsx file
@@ -30,7 +30,7 @@ gum test.jsx -o output.png
 ```
 
 **CLI options:**
-- `file`: gum.jsx file to render (reads from stdin if not provided)
+- `file`: Gum JSX file to render (reads from stdin if not provided)
 - `-t, --theme <theme>`: theme to use (default: light)
 - `-b, --background <color>`: background color (default: white)
 - `-i, --input <input>`: input format (default: jsx)
@@ -41,9 +41,9 @@ gum test.jsx -o output.png
 - `-h, --height <height>`: height of the PNG (default: auto)
 - `-u, --update`: enable live update display
 
-# Using in TypeScript
+# Using Gum in TypeScript
 
-You can use gum.jsx directly in TypeScript/JavaScript code by importing from the `gum-jsx` package. This is useful for programmatic generation, integration into other tools, or when you want to avoid the CLI.
+There are a couple of ways to use Gum in TypeScript. You can evaluate JSX strings directly, or you can construct Gum components directly. If you want to use Gum components in React, you can use the `react-gum-jsx` package.
 
 ## Evaluating JSX strings
 
@@ -77,7 +77,7 @@ const tree = evaluateGum(code, {
 
 ## Using components directly
 
-You can also construct components directly by importing them from `gum-jsx` and calling their constructors. Each component takes a single args object.
+You can also construct Gum components directly by importing them from `gum-jsx` and calling their constructors. Each component takes a single args object.
 
 ```typescript
 import { Svg, Rectangle, Circle, HStack, Text, blue, red, white } from 'gum-jsx'
@@ -99,3 +99,38 @@ When constructing manually, note that:
 - Utility functions like `range`, `linspace`, `zip` are also available from `gum-jsx`
 - Call `.svg()` on the top-level `Svg` element to get the SVG string output
 - The realized size of the SVG is available on the `Svg` element as `size`
+
+## Using in React with `react-gum-jsx`
+
+You can use Gum components directly in React components by importing from the `react-gum-jsx` package. This is useful for creating interactive visualizations in React.
+
+Here's an example of how to use Gum in a React component. It's basically the same as what you would pass to `evaluateGum` but as a default export:
+
+```tsx
+import { blue, red } from 'gum-jsx'
+import { GUM } from 'react-gum-jsx'
+const { Frame, HStack, Square, Circle, Text } = GUM
+
+export default function Demo() {
+  return <Frame padding margin rounded>
+    <HStack padding>
+      <Square fill={blue} />
+      <Circle fill={red} />
+      <Text>Hello</Text>
+    </HStack>
+  </Frame>
+}
+```
+
+To run this in a CLI setting, just pass a file with a default export to the `gum-react` command that comes with the `react-gum-jsx` package. This takes very similar arguments to the regular `gum` command.
+
+If you are in a web setting, you'll need to wrap this export in a `<Gum>` component, which takes roughly the same arguments as `evaluateGum`. This would look like:
+
+```tsx
+import { Gum } from 'react-gum-jsx'
+<Gum size={[640, 360]}>
+  <Demo />
+</Gum>
+```
+
+If the inner component has an `aspect` it will be embedded inside the given size bounds. If it is aspectless, it will be stretched to fill the given size bounds.

package/skills/gum-jsx/SKILL.md

@@ -401,7 +401,7 @@ There is a gallery of more complex examples available. Each is a single markdown
 
 # Using CLI commands
 
-To test the output of a particular `gum.jsx` snippet or file, you can pipe it to the `gum` command, which is assumed to be installed globally. If you have vision capabilities, this can be useful for see the actual output of the code, either in SVG or PNG format. Even without vision, one can infer properties of the output by reading the SVG output directly.
+To test the output of a particular Gum JSX snippet or file, you can pipe it to the `gum` command, which is assumed to be installed globally. If you have vision capabilities, this can be useful for see the actual output of the code, either in SVG or PNG format. Even without vision, one can infer properties of the output by reading the SVG output directly.
 
 For one off tests, pipe the code using `echo`. It is recommended that you use single quotes as the outer delimiter, to accommodate code that includes double quotes for component properties (e.g. `justify="left"`).
 
@@ -411,10 +411,10 @@ In general, it makes a lot of sense to write a draft to a file, view its output,
 
 **Examples:**
 ```bash
-# Generate SVG from a gum.jsx snippet
+# Generate SVG from a Gum JSX snippet
 echo '<Rectangle rounded fill={blue} />' | gum -f svg > output.svg
 
-# Generate PNG from a gum.jsx snippet
+# Generate PNG from a Gum JSX snippet
 echo '<Rectangle rounded fill={blue} />' | gum -f png > output.png
 
 # Generate SVG from a .jsx file
@@ -431,7 +431,7 @@ gum test.jsx -o output.png
 ```
 
 **CLI options:**
-- `file`: gum.jsx file to render (reads from stdin if not provided)
+- `file`: Gum JSX file to render (reads from stdin if not provided)
 - `-t, --theme <theme>`: theme to use (default: light)
 - `-b, --background <color>`: background color (default: white)
 - `-i, --input <input>`: input format (default: jsx)
@@ -442,9 +442,9 @@ gum test.jsx -o output.png
 - `-h, --height <height>`: height of the PNG (default: auto)
 - `-u, --update`: enable live update display
 
-# Using in TypeScript
+# Using Gum in TypeScript
 
-You can use gum.jsx directly in TypeScript/JavaScript code by importing from the `gum-jsx` package. This is useful for programmatic generation, integration into other tools, or when you want to avoid the CLI.
+There are a couple of ways to use Gum in TypeScript. You can evaluate JSX strings directly, or you can construct Gum components directly. If you want to use Gum components in React, you can use the `react-gum-jsx` package.
 
 ## Evaluating JSX strings
 
@@ -478,7 +478,7 @@ const tree = evaluateGum(code, {
 
 ## Using components directly
 
-You can also construct components directly by importing them from `gum-jsx` and calling their constructors. Each component takes a single args object.
+You can also construct Gum components directly by importing them from `gum-jsx` and calling their constructors. Each component takes a single args object.
 
 ```typescript
 import { Svg, Rectangle, Circle, HStack, Text, blue, red, white } from 'gum-jsx'
@@ -500,3 +500,38 @@ When constructing manually, note that:
 - Utility functions like `range`, `linspace`, `zip` are also available from `gum-jsx`
 - Call `.svg()` on the top-level `Svg` element to get the SVG string output
 - The realized size of the SVG is available on the `Svg` element as `size`
+
+## Using in React with `react-gum-jsx`
+
+You can use Gum components directly in React components by importing from the `react-gum-jsx` package. This is useful for creating interactive visualizations in React.
+
+Here's an example of how to use Gum in a React component. It's basically the same as what you would pass to `evaluateGum` but as a default export:
+
+```tsx
+import { blue, red } from 'gum-jsx'
+import { GUM } from 'react-gum-jsx'
+const { Frame, HStack, Square, Circle, Text } = GUM
+
+export default function Demo() {
+  return <Frame padding margin rounded>
+    <HStack padding>
+      <Square fill={blue} />
+      <Circle fill={red} />
+      <Text>Hello</Text>
+    </HStack>
+  </Frame>
+}
+```
+
+To run this in a CLI setting, just pass a file with a default export to the `gum-react` command that comes with the `react-gum-jsx` package. This takes very similar arguments to the regular `gum` command.
+
+If you are in a web setting, you'll need to wrap this export in a `<Gum>` component, which takes roughly the same arguments as `evaluateGum`. This would look like:
+
+```tsx
+import { Gum } from 'react-gum-jsx'
+<Gum size={[640, 360]}>
+  <Demo />
+</Gum>
+```
+
+If the inner component has an `aspect` it will be embedded inside the given size bounds. If it is aspectless, it will be stretched to fill the given size bounds.

package/src/elems/core.ts

@@ -245,7 +245,8 @@ function props_repr(d: Attrs, prec: number): string {
 // reserved keys
 const SPEC_KEYS = [ 'rect', 'aspect', 'expand', 'align', 'upright', 'rotate', 'rotate_adjust', 'invar', 'coord' ]
 const HELP_KEYS = [ 'pos', 'size', 'xsize', 'ysize', 'flex', 'spin', 'orient' ]
-const RESERVED_KEYS = [ ...SPEC_KEYS, ...HELP_KEYS ]
+const EXTR_KEYS = [ 'stack_size', 'stack_expand' ]
+const RESERVED_KEYS = [ ...SPEC_KEYS, ...HELP_KEYS, ...EXTR_KEYS ]
 
 function spec_split(attr: Attrs, extended: boolean = true): [Attrs, Attrs] {
     const SPLIT_KEYS = extended ? RESERVED_KEYS : SPEC_KEYS

package/src/elems/plot.ts

@@ -134,7 +134,7 @@ class Scale extends Group {
         const ticks = ticks0.map((t: Element) => {
             const { tick_loc, tick_span } = t.args
             const rect = join_limits({ [direc]: [tick_loc, tick_loc], [tick_dir]: tick_span })
-            return t.clone({ rect, expand: true, ...tick_attr })
+            return t.clone({ rect, expand: true, tick_loc: undefined, tick_span: undefined, ...tick_attr })
         })
 
         // set coordinate system
@@ -307,7 +307,7 @@ class Axis extends Group {
     locs: number[]
 
     constructor(args: AxisArgs = {}) {
-        const { children, lim = D.lim, direc = 'h', ticks: ticks0, tick_side = 'inner', label_side = 'outer', label_size = 1.35, label_offset = 0, label_justify: label_justify0, label_loc, discrete = false, prec = D.prec, debug, ...attr0 } = THEME(args, 'Axis')
+        const { children, lim = D.lim, direc = 'h', ticks: ticks0, tick_side = 'inner', label_side = 'outer', label_size = 1.5, label_offset = 0, label_justify: label_justify0, label_loc, discrete = false, prec = D.prec, debug, ...attr0 } = THEME(args, 'Axis')
         const [ label_attr, tick_attr, line_attr, attr ] = prefix_split([ 'label', 'tick', 'line' ], attr0)
         const tick_lim = get_tick_lim(tick_side)
         const [ tick_lo, tick_hi ] = tick_lim