@substrate-kit/cli 0.1.2 → 0.2.0

package/docs/components/node.mdx

@@ -0,0 +1,85 @@
+---
+title: Node
+description: Compound card for node-based editors – typed ports, composable body, and themeable port colours via CSS variables.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/node
+```
+
+## Examples
+
+### Default
+
+Three node types demonstrating the component anatomy: a filter node with controls, a generator node with colour and dimensions, and an output node with a preview area.
+
+<ComponentPreview name="node-demo" />
+
+### Port types
+
+Each port type maps to a CSS variable that consumers can override to match their brand.
+
+<ComponentPreview name="node-port-types" />
+
+## Port type system
+
+Ports are typed. Each type has a corresponding CSS variable for its colour:
+
+| Type       | CSS variable           | Default |
+| ---------- | ---------------------- | ------- |
+| `number`   | `--node-port-number`   | Blue    |
+| `colour`   | `--node-port-colour`   | Pink    |
+| `image`    | `--node-port-image`    | Purple  |
+| `geometry` | `--node-port-geometry` | Green   |
+| `text`     | `--node-port-text`     | Amber   |
+| `boolean`  | `--node-port-boolean`  | Orange  |
+| `any`      | `--node-port-any`      | Grey    |
+
+Override any of these in your `globals.css` to change port colours globally.
+
+## Node chrome variables
+
+| Variable          | Tailwind class       | Fallback   | Description           |
+| ----------------- | -------------------- | ---------- | --------------------- |
+| `--node-bg`       | `bg-node-bg`         | `--card`   | Card background       |
+| `--node-border`   | `border-node-border` | `--border` | Card border           |
+| `--node-header`   | `bg-node-header`     | `--muted`  | Header background     |
+| `--node-selected` | `ring-node-selected` | `--ring`   | Selection ring colour |
+
+## Components
+
+| Component     | Description                                                     |
+| ------------- | --------------------------------------------------------------- |
+| `NodeCard`    | Outer card with border, shadow, and selected ring               |
+| `NodeHeader`  | Title bar with optional custom `colour` background              |
+| `NodeTitle`   | Truncated title text                                            |
+| `NodeBadge`   | Small type/category badge in the header                         |
+| `NodeBody`    | Content area for controls (compose Action, NumberSlider, etc.)  |
+| `NodePorts`   | Vertical list of input/output ports                             |
+| `NodePort`    | A single typed port with dot, label, and direction              |
+| `NodePortDot` | Coloured dot indicator (filled when connected, hollow when not) |
+| `NodePreview` | Optional image/canvas preview area                              |
+| `NodeDivider` | Horizontal separator between sections                           |
+
+## Composing node bodies
+
+The body of a node uses the same components you'd use in a panel pane. ActionControls automatically adapts nested components:
+
+```tsx
+<NodeBody>
+	<Action>
+		<ActionLabel>Radius</ActionLabel>
+		<ActionControls>
+			<NumberSlider
+				value={blur}
+				onChange={setBlur}
+				min={0}
+				max={50}
+				suffix="px"
+			/>
+		</ActionControls>
+	</Action>
+</NodeBody>
+```

package/docs/components/number-input.mdx

@@ -0,0 +1,44 @@
+---
+title: Number input
+description: Numeric input with drag-to-scrub on the label, arrow key stepping, and shift for larger increments.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/number-input
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="number-input-demo" />
+
+### With labels and suffix
+
+<ComponentPreview name="number-input-labels" />
+
+## Interaction
+
+- **Drag on label** — pointer left/right to scrub the value. Hold Shift for larger increments.
+- **Arrow keys** — Up/Down to step the value when the input is focused. Hold Shift for `shiftStep`.
+- **Click label** — focuses and selects the input for direct typing.
+- **Enter** — commits the typed value.
+- **Escape** — cancels editing and blurs.
+
+## Props
+
+| Prop        | Type                      | Default | Description                                                                             |
+| ----------- | ------------------------- | ------- | --------------------------------------------------------------------------------------- |
+| `value`     | `number`                  | —       | Current value                                                                           |
+| `onChange`  | `(value: number) => void` | —       | Called when the value changes                                                           |
+| `onStart`   | `() => void`              | —       | Called once at the start of a drag or before a step. Useful for pushing undo snapshots. |
+| `label`     | `string`                  | —       | Inline label with drag-to-scrub cursor                                                  |
+| `suffix`    | `string`                  | —       | Trailing text (e.g. `°`, `%`, `px`)                                                     |
+| `min`       | `number`                  | —       | Minimum value                                                                           |
+| `max`       | `number`                  | —       | Maximum value                                                                           |
+| `step`      | `number`                  | `1`     | Increment per pixel of drag or arrow key press                                          |
+| `shiftStep` | `number`                  | `10`    | Increment when Shift is held                                                            |
+| `precision` | `number`                  | `2`     | Decimal places for display                                                              |
+| `disabled`  | `boolean`                 | —       | Disables input and drag                                                                 |

package/docs/components/number-slider.mdx

@@ -0,0 +1,32 @@
+---
+title: Number slider
+description: Linked slider and numeric input – drag the track or type a value.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/number-slider
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="number-slider-demo" />
+
+## Props
+
+| Prop        | Type                      | Default | Description                                                       |
+| ----------- | ------------------------- | ------- | ----------------------------------------------------------------- |
+| `value`     | `number`                  | —       | Current value                                                     |
+| `onChange`  | `(value: number) => void` | —       | Called when the value changes                                     |
+| `onStart`   | `() => void`              | —       | Called once at the start of a gesture. Useful for undo snapshots. |
+| `min`       | `number`                  | `0`     | Minimum value                                                     |
+| `max`       | `number`                  | `100`   | Maximum value                                                     |
+| `step`      | `number`                  | `1`     | Increment per step                                                |
+| `shiftStep` | `number`                  | `10`    | Increment when Shift is held (number input only)                  |
+| `precision` | `number`                  | `2`     | Decimal places for display                                        |
+| `label`     | `string`                  | —       | Label on the number input (with drag-to-scrub)                    |
+| `suffix`    | `string`                  | —       | Trailing text (e.g. `%`, `px`)                                    |
+| `disabled`  | `boolean`                 | —       | Disables both slider and input                                    |

package/docs/components/pane.mdx

@@ -0,0 +1,39 @@
+---
+title: Pane
+description: Content section within a panel for composing property editors.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/pane
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="pane-demo" />
+
+### With history controls
+
+Drop `HistoryControls` (or individual `HistoryButton` elements) into a `PaneHeader` and they auto-push to the right and compact to match the header height.
+
+<ComponentPreview name="pane-history" />
+
+## Theme variables
+
+Pane inherits panel tokens. `PaneAction` uses `bg-panel` for its background.
+
+| Variable  | Tailwind class | Fallback | Description              |
+| --------- | -------------- | -------- | ------------------------ |
+| `--panel` | `bg-panel`     | `--card` | Action button background |
+
+## Components
+
+| Component    | Description                                            |
+| ------------ | ------------------------------------------------------ |
+| `Pane`       | Container with vertical spacing and horizontal padding |
+| `PaneHeader` | Flex row for label + action                            |
+| `PaneLabel`  | Section title text                                     |
+| `PaneAction` | Button slot in the header                              |

package/docs/components/panel.mdx

@@ -0,0 +1,28 @@
+---
+title: Panel
+description: Side panel container with position variants and scroll area.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/panel
+```
+
+## Examples
+
+<ComponentPreview background="canvas" name="panel-demo" />
+
+## Theme variables
+
+| Variable             | Tailwind class          | Fallback            | Description             |
+| -------------------- | ----------------------- | ------------------- | ----------------------- |
+| `--panel`            | `bg-panel`              | `--card`            | Panel background colour |
+| `--panel-foreground` | `text-panel-foreground` | `--card-foreground` | Panel text colour       |
+
+## Props
+
+| Prop       | Type                  | Default     | Description                                              |
+| ---------- | --------------------- | ----------- | -------------------------------------------------------- |
+| `position` | `"left" \| "right"`   | `"right"`   | Which side the panel sits on. Controls border direction. |
+| `variant`  | `"tool" \| "default"` | `"default"` | Panel variant. Tool variant uses flex column layout.     |

package/docs/components/popover.mdx

@@ -0,0 +1,32 @@
+---
+title: Popover
+description: Floating panel built on Radix Popover. Use for mini-inspectors, quick settings, and overflow controls.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/popover
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="popover-demo" />
+
+## Components
+
+| Component        | Description                        |
+| ---------------- | ---------------------------------- |
+| `Popover`        | Root wrapper (Radix Popover.Root)  |
+| `PopoverTrigger` | Element that opens the popover     |
+| `PopoverContent` | Floating panel with optional arrow |
+| `PopoverClose`   | Positioned close button            |
+
+## Props (PopoverContent)
+
+| Prop         | Type      | Default | Description                     |
+| ------------ | --------- | ------- | ------------------------------- |
+| `showArrow`  | `boolean` | —       | Show a directional arrow        |
+| `sideOffset` | `number`  | `6`     | Gap between trigger and popover |

package/docs/components/progress-bar.mdx

@@ -0,0 +1,24 @@
+---
+title: Progress bar
+description: Thin progress indicator for exports, asset loading, and generation. Supports determinate and indeterminate states.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/progress-bar
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="progress-bar-demo" />
+
+## Props
+
+| Prop            | Type      | Default | Description                              |
+| --------------- | --------- | ------- | ---------------------------------------- |
+| `value`         | `number`  | —       | Current progress value                   |
+| `max`           | `number`  | `100`   | Maximum value                            |
+| `indeterminate` | `boolean` | —       | Show an animated indeterminate indicator |

package/docs/components/resizer.mdx

@@ -0,0 +1,24 @@
+---
+title: Resizer
+description: Drag handle for resizing adjacent panels or panes. Visual grab dots on hover.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/resizer
+```
+
+## Examples
+
+### Default
+
+Hover over the divider to see the grab dots.
+
+<ComponentPreview name="resizer-demo" />
+
+## Props
+
+| Prop          | Type                           | Default      | Description      |
+| ------------- | ------------------------------ | ------------ | ---------------- |
+| `orientation` | `"horizontal"` \| `"vertical"` | `"vertical"` | Resize direction |

package/docs/components/select.mdx

@@ -0,0 +1,31 @@
+---
+title: Select
+description: Dropdown select for blend modes, fonts, export formats. Built on Radix Select with ActionControls awareness.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/select
+```
+
+## Examples
+
+### Default
+
+Placed inside an `ActionControls` row, the trigger automatically loses its border and fills the available width.
+
+<ComponentPreview name="select-demo" />
+
+## Components
+
+| Component         | Description                            |
+| ----------------- | -------------------------------------- |
+| `Select`          | Root wrapper (Radix Select.Root)       |
+| `SelectTrigger`   | Button that opens the dropdown         |
+| `SelectValue`     | Displays the currently selected value  |
+| `SelectContent`   | Dropdown panel with items              |
+| `SelectItem`      | Selectable option with check indicator |
+| `SelectGroup`     | Labelled group of items                |
+| `SelectLabel`     | Non-interactive group heading          |
+| `SelectSeparator` | Horizontal divider                     |

package/docs/components/shortcut-overlay.mdx

@@ -0,0 +1,43 @@
+---
+title: Shortcut overlay
+description: Modal showing all registered keyboard shortcuts, triggered by pressing ?.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/shortcut-overlay
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="shortcut-overlay-demo" />
+
+## Props
+
+| Prop           | Type                      | Default | Description                    |
+| -------------- | ------------------------- | ------- | ------------------------------ |
+| `groups`       | `ShortcutGroup[]`         | —       | Groups of shortcuts to display |
+| `open`         | `boolean`                 | —       | Controlled open state          |
+| `onOpenChange` | `(open: boolean) => void` | —       | Controlled open change handler |
+| `trigger`      | `string`                  | `"?"`   | Key that toggles the overlay   |
+
+### ShortcutGroup
+
+```ts
+type ShortcutGroup = {
+	heading: string
+	shortcuts: { key: string; label: string }[]
+}
+```
+
+The `key` string is split on `+` and each part rendered as an individual `<kbd>`. For example `"⌘ + Z"` renders as two separate key badges.
+
+## Components
+
+| Component         | Description                                          |
+| ----------------- | ---------------------------------------------------- |
+| `ShortcutOverlay` | Dialog modal with ? key listener                     |
+| `ShortcutKey`     | Inline keyboard shortcut badge (reusable standalone) |

package/docs/components/slider.mdx

@@ -0,0 +1,20 @@
+---
+title: Slider
+description: Slider component built on Radix Slider primitive.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/slider
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="slider-demo" />
+
+### Range
+
+<ComponentPreview name="slider-range" />

package/docs/components/spring-editor.mdx

@@ -0,0 +1,85 @@
+---
+title: Spring editor
+description: Spring curve preview with duration and bounce, or stiffness, damping and mass.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/spring-editor
+```
+
+This also installs the `spring` utility library.
+
+## Examples
+
+### Default
+
+<ComponentPreview name="spring-editor-demo" />
+
+## Usage
+
+A spring is described one of two ways. A time spring sets how long the motion appears to take and how much it overshoots. A physics spring sets stiffness, damping and mass directly. The editor shows the sliders for whichever shape the value has, and the Type switch converts between them, restoring the previous settings when you switch back.
+
+```tsx
+const [spring, setSpring] = useState<Spring>({
+  type: "spring",
+  visualDuration: 0.3,
+  bounce: 0.2,
+})
+
+<SpringEditor value={spring} onChange={setSpring} />
+```
+
+The value matches Motion's spring transition, so it can be passed straight to `transition`.
+
+## Theme variables
+
+| Variable        | Tailwind class   | Fallback    | Description         |
+| --------------- | ---------------- | ----------- | ------------------- |
+| `--spring-curve` | `bg-spring-curve` | Text colour | Spring curve stroke |
+
+## Components
+
+| Component      | Description                                                       |
+| -------------- | ----------------------------------------------------------------- |
+| `SpringEditor` | Curve, Time / Physics switch and sliders in a vertical stack      |
+| `SpringCurve`  | SVG plot of the spring's progress over time, overshoot included   |
+| `SpringFields` | The sliders alone, for the value's own mode                       |
+
+## Props
+
+### SpringEditor and SpringFields
+
+| Prop       | Type                       | Default | Description                                    |
+| ---------- | -------------------------- | ------- | ---------------------------------------------- |
+| `value`    | `Spring`                   | —       | Current spring                                 |
+| `onChange` | `(spring: Spring) => void` | —       | Called when the spring changes                 |
+| `onStart`  | `() => void`               | —       | Fires when a drag or edit begins, for undo     |
+
+### SpringCurve
+
+| Prop       | Type     | Default | Description                  |
+| ---------- | -------- | ------- | ---------------------------- |
+| `value`    | `Spring` | —       | Spring to plot               |
+| `duration` | `number` | `2`     | Seconds shown across the width |
+
+## Spring utility
+
+```tsx
+import {
+  type Spring,
+  springMode,
+  springParams,
+  springProgress,
+  springSettleDuration,
+} from "@/lib/substrate/spring"
+```
+
+| Export                 | Description                                                          |
+| ---------------------- | -------------------------------------------------------------------- |
+| `Spring`               | Type: `{ type: "spring", visualDuration?, bounce?, stiffness?, damping?, mass? }` |
+| `springMode`           | `"physics"` when stiffness, damping or mass is set, `"time"` otherwise |
+| `springParams`         | Resolves either shape to stiffness, damping and mass                 |
+| `springProgress`       | Progress at a time in seconds; goes past 1 when the spring overshoots |
+| `springSettleDuration` | Seconds until the spring is within 0.5% of its target                |

package/docs/components/status-bar.mdx

@@ -0,0 +1,42 @@
+---
+title: Status bar
+description: Bottom information strip showing document metadata, cursor position, and zoom controls.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/status-bar
+```
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/zoom-controls
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="status-bar-demo" />
+
+## Components
+
+### StatusBar
+
+| Component            | Description                                  |
+| -------------------- | -------------------------------------------- |
+| `StatusBar`          | Fixed-height strip with border-top           |
+| `StatusBarSection`   | Aligned group (`left`, `center`, or `right`) |
+| `StatusBarItem`      | Inline text item with tabular-nums           |
+| `StatusBarSeparator` | Thin vertical divider                        |
+
+### ZoomControls
+
+| Prop           | Type                     | Default | Description                   |
+| -------------- | ------------------------ | ------- | ----------------------------- |
+| `zoom`         | `number`                 | —       | Current zoom level (1 = 100%) |
+| `onZoomChange` | `(zoom: number) => void` | —       | Called when zoom changes      |
+| `onZoomToFit`  | `() => void`             | —       | Optional fit-to-view callback |
+| `min`          | `number`                 | `0.1`   | Minimum zoom                  |
+| `max`          | `number`                 | `10`    | Maximum zoom                  |
+| `step`         | `number`                 | `0.25`  | Zoom increment per click      |

package/docs/components/surface.mdx

@@ -0,0 +1,47 @@
+---
+title: Surface
+description: Full-bleed container for rendering engines — canvas, WebGL, video or any visual content.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/surface
+```
+
+## Examples
+
+<ComponentPreview name="surface-demo" background="canvas" />
+
+## Theme variables
+
+| Variable              | Tailwind class           | Fallback             | Description             |
+| --------------------- | ------------------------ | -------------------- | ----------------------- |
+| `--canvas`            | `bg-canvas`              | `--background`       | Surface background      |
+| `--canvas-foreground` | `text-canvas-foreground` | `--foreground-muted` | Surface foreground/grid |
+
+## Components
+
+| Component         | Description                                                        |
+| ----------------- | ------------------------------------------------------------------ |
+| `Surface`         | Absolute-positioned container with `bg-canvas` and overflow hidden |
+| `SurfaceControls` | Overlay layer with pointer-events pass-through except on children  |
+| `SurfaceGrid`     | CSS radial-gradient dot pattern sized via the `size` prop          |
+
+## Props
+
+### Surface
+
+Extends `React.ComponentProps<"div">`.
+
+### SurfaceControls
+
+| Prop       | Type                                                           | Default          | Description                        |
+| ---------- | -------------------------------------------------------------- | ---------------- | ---------------------------------- |
+| `position` | `"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"` | `"bottom-right"` | Which corner to anchor controls to |
+
+### SurfaceGrid
+
+| Prop   | Type     | Default | Description                |
+| ------ | -------- | ------- | -------------------------- |
+| `size` | `number` | `20`    | Grid dot spacing in pixels |

package/docs/components/swatch-palette.mdx

@@ -0,0 +1,36 @@
+---
+title: Swatch palette
+description: Grid of colour swatches for quick selection. Pairs with ColourPicker.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/swatch-palette
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="swatch-palette-demo" />
+
+## Props
+
+| Prop       | Type                       | Default | Description                     |
+| ---------- | -------------------------- | ------- | ------------------------------- |
+| `colours`  | `string[]`                 | —       | Array of hex colour strings     |
+| `value`    | `string`                   | —       | Currently selected colour       |
+| `onSelect` | `(colour: string) => void` | —       | Called when a swatch is clicked |
+| `columns`  | `number`                   | `8`     | Grid column count               |
+
+## Presets
+
+Two built-in palettes are exported for convenience:
+
+```ts
+import {
+	MATERIAL_COLOURS,
+	TAILWIND_COLOURS,
+} from "@/components/substrate/swatch-palette"
+```

package/docs/components/text-area.mdx

@@ -0,0 +1,26 @@
+---
+title: Text area
+description: Auto-resizing textarea with minimal styling. Fits inside node bodies and property panels.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/text-area
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="text-area-demo" />
+
+## Props
+
+Extends all native `<textarea>` props.
+
+| Prop         | Type      | Default | Description                             |
+| ------------ | --------- | ------- | --------------------------------------- |
+| `autoResize` | `boolean` | `true`  | Automatically adjusts height to content |
+| `minRows`    | `number`  | `2`     | Minimum visible rows                    |
+| `maxRows`    | `number`  | `10`    | Maximum height before scrolling         |