@substrate-kit/cli 0.1.1 → 0.2.0

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         |

package/docs/components/timeline.mdx

@@ -0,0 +1,96 @@
+---
+title: Timeline
+description: Compound timeline for keyframe animation editing with playhead, tracks, and transport controls.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/timeline
+```
+
+This also installs the `animation-store` dependency (Zustand).
+
+## Examples
+
+<ComponentPreview name="timeline-demo" />
+
+## Theme variables
+
+| Variable              | Tailwind class         | Fallback                   | Description             |
+| --------------------- | ---------------------- | -------------------------- | ----------------------- |
+| `--timeline-playhead` | `bg-timeline-playhead` | `--color-destructive`      | Playhead colour         |
+| `--timeline-keyframe` | `bg-timeline-keyframe` | `--color-muted-foreground` | Keyframe diamond colour |
+| `--timeline-track`    | `bg-timeline-track`    | `--color-panel`            | Track background        |
+
+## Components
+
+| Component           | Description                                                                       |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `Timeline`          | Flex-column container with panel background and top border                        |
+| `TimelineRuler`     | Second-interval tick marks with time labels. Fixed label column at 128px width    |
+| `TimelinePlayhead`  | Draggable vertical line with triangular handle. Updates `animation-store` on drag |
+| `TimelineTrack`     | Single track row with a label column and a content area for keyframes             |
+| `TimelineKeyframe`  | Diamond-shaped marker positioned by `time * zoomLevel` pixels                     |
+| `TimelineTransport` | Play/pause, loop, and time display. Reads directly from `animation-store`         |
+
+## Props
+
+### Timeline
+
+| Prop       | Type     | Default | Description                                           |
+| ---------- | -------- | ------- | ----------------------------------------------------- |
+| `duration` | `number` | `5`     | Total duration (unused internally — pass to children) |
+
+### TimelineRuler
+
+| Prop        | Type     | Default | Description               |
+| ----------- | -------- | ------- | ------------------------- |
+| `duration`  | `number` | —       | Total duration in seconds |
+| `zoomLevel` | `number` | —       | Pixels per second         |
+
+### TimelinePlayhead
+
+| Prop        | Type     | Default | Description               |
+| ----------- | -------- | ------- | ------------------------- |
+| `time`      | `number` | —       | Current time in seconds   |
+| `duration`  | `number` | —       | Total duration in seconds |
+| `zoomLevel` | `number` | —       | Pixels per second         |
+
+### TimelineKeyframe
+
+| Prop        | Type         | Default | Description                  |
+| ----------- | ------------ | ------- | ---------------------------- |
+| `time`      | `number`     | —       | Keyframe time in seconds     |
+| `duration`  | `number`     | —       | Total duration in seconds    |
+| `zoomLevel` | `number`     | —       | Pixels per second            |
+| `selected`  | `boolean`    | `false` | Whether keyframe is selected |
+| `onSelect`  | `() => void` | —       | Click handler for selection  |
+
+### TimelineTransport
+
+No additional props. Reads state from `useAnimationStore`.
+
+## Animation store
+
+The timeline uses a shared Zustand store (`animation-store`) for playback state:
+
+```tsx
+import { useAnimationStore } from "@/stores/substrate/animation-store"
+
+const { currentTime, isPlaying, togglePlayback } = useAnimationStore()
+```
+
+| Property                 | Type                                       | Description                 |
+| ------------------------ | ------------------------------------------ | --------------------------- |
+| `duration`               | `number`                                   | Total duration (default 5s) |
+| `currentTime`            | `number`                                   | Current playhead time       |
+| `isPlaying`              | `boolean`                                  | Playback state              |
+| `fps`                    | `number`                                   | Frames per second (60)      |
+| `zoomLevel`              | `number`                                   | Pixels per second (100)     |
+| `selectedKeyframeIds`    | `Set<string>`                              | Selected keyframe IDs       |
+| `setCurrentTime`         | `(time: number) => void`                   | Set time (clamped)          |
+| `togglePlayback`         | `() => void`                               | Toggle play/pause           |
+| `setZoomLevel`           | `(level: number) => void`                  | Set zoom (clamped 20–500)   |
+| `selectKeyframe`         | `(id: string, additive?: boolean) => void` | Select keyframe             |
+| `clearKeyframeSelection` | `() => void`                               | Clear selection             |

package/docs/components/toast.mdx

@@ -0,0 +1,42 @@
+---
+title: Toast
+description: Lightweight notifications for creative app actions – export, delete, copy, save.
+---
+
+## Install
+
+Requires the `sonner` package and the `Toaster` component mounted in your layout (already included in the Substrate CLI scaffold).
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/toast
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="toast-demo" />
+
+## API
+
+```ts
+import { toast } from "@/components/substrate/toast"
+
+toast("3 elements duplicated")
+toast.success("Exported to PNG")
+toast.error("Failed to save", { description: "Network unavailable" })
+toast.warning("Unsaved changes")
+toast.info("Tip: hold Shift for larger increments")
+toast.undo("Deleted 2 elements", () => undo())
+toast.dismiss()
+```
+
+| Method          | Default duration | Description                        |
+| --------------- | ---------------- | ---------------------------------- |
+| `toast()`       | 3s               | Neutral notification               |
+| `toast.success` | 3s               | Success with checkmark icon        |
+| `toast.error`   | 5s               | Error with longer display time     |
+| `toast.warning` | 4s               | Warning                            |
+| `toast.info`    | 3s               | Informational                      |
+| `toast.undo`    | 5s               | Message with an Undo action button |
+| `toast.dismiss` | —                | Dismiss all toasts                 |

package/docs/components/toggle-group.mdx

@@ -0,0 +1,40 @@
+---
+title: Toggle Group
+description: Grouped set of toggles for single or multi-select choices. Built on Radix ToggleGroup.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/toggle-group
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="toggle-group-demo" />
+
+## Props
+
+### ToggleGroup
+
+Extends all Radix `ToggleGroup.Root` props.
+
+| Prop            | Type                                                 | Default        | Description                                    |
+| --------------- | ---------------------------------------------------- | -------------- | ---------------------------------------------- |
+| `type`          | `"single" \| "multiple"`                             | —              | Single or multi-select behaviour               |
+| `value`         | `string \| string[]`                                 | —              | Controlled selected value(s)                   |
+| `defaultValue`  | `string \| string[]`                                 | —              | Uncontrolled initial value(s)                  |
+| `onValueChange` | `(value: string) => void \| (value: string[]) => void` | —            | Called when selection changes                  |
+| `orientation`   | `"horizontal" \| "vertical"`                         | `"horizontal"` | Layout direction and arrow-key navigation axis |
+| `disabled`      | `boolean`                                            | —              | Disables all items                             |
+
+### ToggleGroupItem
+
+Extends all Radix `ToggleGroup.Item` props.
+
+| Prop       | Type      | Default | Description            |
+| ---------- | --------- | ------- | ---------------------- |
+| `value`    | `string`  | —       | Unique value of item   |
+| `disabled` | `boolean` | —       | Disables this item     |

package/docs/components/toggle.mdx

@@ -0,0 +1,27 @@
+---
+title: Toggle
+description: Pressable boolean toggle button built on Radix Toggle. Use for snap, grid, rulers, and other on/off states.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/toggle
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="toggle-demo" />
+
+## Props
+
+Extends all Radix `Toggle.Root` props.
+
+| Prop              | Type                         | Default | Description                       |
+| ----------------- | ---------------------------- | ------- | --------------------------------- |
+| `pressed`         | `boolean`                    | —       | Controlled pressed state          |
+| `onPressedChange` | `(pressed: boolean) => void` | —       | Called when pressed state changes |
+| `defaultPressed`  | `boolean`                    | —       | Uncontrolled initial state        |
+| `disabled`        | `boolean`                    | —       | Disables the toggle               |

package/docs/components/toolbar.mdx

@@ -0,0 +1,24 @@
+---
+title: Toolbar
+description: Floating toolbar with toggle groups, dropdowns, and tooltips built on Radix primitives.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/toolbar
+```
+
+## Examples
+
+<ComponentPreview name="toolbar-demo" />
+
+## Components
+
+| Component            | Description                                                                   |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `Toolbar`            | Fixed-position container with `role="toolbar"` and built-in `TooltipProvider` |
+| `ToolbarToggleGroup` | Single-select toggle group (wraps Radix ToggleGroup)                          |
+| `ToolbarToggle`      | Toggle button with optional tooltip and keyboard shortcut display             |
+| `ToolbarSeparator`   | Vertical divider between tool groups                                          |
+| `ToolbarDropdown`    | Button with dropdown menu for tool variant selection, active state highlight  |

package/docs/components/tree-list.mdx

@@ -0,0 +1,46 @@
+---
+title: Tree list
+description: Hierarchical list with expand/collapse, selection, and depth indentation. Ideal for layer panels with nested frames.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/tree-list
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="tree-list-demo" />
+
+## Components
+
+| Component          | Description                                |
+| ------------------ | ------------------------------------------ |
+| `TreeList`         | Root container with `role="tree"`          |
+| `TreeItem`         | Row with depth, selection, expand/collapse |
+| `TreeExpandButton` | Chevron toggle that rotates when expanded  |
+| `TreeItemContent`  | Truncated text label                       |
+| `TreeItemIcon`     | Colour dot or icon                         |
+| `TreeItemActions`  | Right-aligned actions, visible on hover    |
+
+## Hooks
+
+### useTreeExpansion
+
+Manages expand/collapse state for a set of node IDs.
+
+```ts
+const { isExpanded, toggle, expandAll, collapseAll } = useTreeExpansion([
+	"root",
+])
+```
+
+| Method        | Description                    |
+| ------------- | ------------------------------ |
+| `isExpanded`  | Check if a node is expanded    |
+| `toggle`      | Toggle a node's expanded state |
+| `expandAll`   | Expand a list of node IDs      |
+| `collapseAll` | Collapse all nodes             |

package/docs/components/xy-pad.mdx

@@ -0,0 +1,49 @@
+---
+title: XY pad
+description: Two-dimensional pad for setting two values at once.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/xy-pad
+```
+
+## Examples
+
+### Default
+
+<ComponentPreview name="xy-pad-demo" />
+
+## Usage
+
+Drag anywhere on the pad, or focus it and use the arrow keys. Hold Shift for steps ten times larger. Positive y points up.
+
+```tsx
+const [offset, setOffset] = useState({ x: 0, y: 0 })
+
+<XYPad
+  aria-label="Shadow offset"
+  value={offset}
+  onChange={setOffset}
+  x={{ min: -40, max: 40, step: 1 }}
+  y={{ min: -40, max: 40, step: 1 }}
+/>
+```
+
+## Theme variables
+
+| Variable          | Tailwind class      | Fallback    | Description              |
+| ----------------- | ------------------- | ----------- | ------------------------ |
+| `--xy-pad-handle` | `bg-xy-pad-handle`  | Text colour | Handle and crosshair     |
+
+## Props
+
+| Prop       | Type                           | Default                         | Description                                          |
+| ---------- | ------------------------------ | ------------------------------- | ---------------------------------------------------- |
+| `value`    | `{ x: number, y: number }`     | —                               | Current point                                        |
+| `onChange` | `(value: XYPadValue) => void`  | —                               | Called while dragging and on each key press          |
+| `onStart`  | `() => void`                   | —                               | Fires when a drag or key press begins, for undo      |
+| `x`        | `{ min, max, step? }`          | `{ min: -1, max: 1, step: 0.01 }` | Horizontal axis                                    |
+| `y`        | `{ min, max, step? }`          | `{ min: -1, max: 1, step: 0.01 }` | Vertical axis, positive upwards                    |
+| `disabled` | `boolean`                      | `false`                         | Disables dragging and keys                           |

package/docs/hooks/use-clipboard.mdx

@@ -0,0 +1,70 @@
+---
+title: useClipboard
+description: Copy, cut, and paste with keyboard shortcuts and system clipboard integration.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/use-clipboard
+```
+
+## Usage
+
+```tsx
+import { useClipboard } from "@/hooks/substrate/use-clipboard"
+
+function Canvas() {
+  const { copy, cut, paste } = useClipboard({
+    onCopy: () => {
+      // Return the items to be copied
+      return selectedElements.map((el) => ({ ...el }))
+    },
+    onPaste: (items) => {
+      // Offset pasted items slightly so they don't overlap
+      const offset = items.map((el) => ({
+        ...el,
+        id: generateId(),
+        x: el.x + 20,
+        y: el.y + 20,
+      }))
+      addElements(offset)
+    },
+    onCut: () => {
+      const items = selectedElements.map((el) => ({ ...el }))
+      removeSelected()
+      return items
+    },
+  })
+
+  return <div>...</div>
+}
+```
+
+## Features
+
+The hook automatically listens for ⌘C / ⌘X / ⌘V (Ctrl on Windows/Linux) and ignores shortcuts when the focus is inside an `<input>`, `<textarea>`, or `contentEditable` element. It writes to the system clipboard when the browser permits, falling back to an internal ref-based clipboard otherwise.
+
+Custom `serialize` and `deserialize` functions can be provided to support non-JSON data formats. The `dataType` option sets the clipboard MIME type key.
+
+## API
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onCopy` | `() => T[]` | — | Return items to copy from the current selection |
+| `onPaste` | `(items: T[]) => void` | — | Called with deserialized items when pasting |
+| `onCut` | `() => T[]` | `onCopy` | Return items to copy, then remove them |
+| `serialize` | `(items: T[]) => string` | `JSON.stringify` | Custom serialization |
+| `deserialize` | `(data: string) => T[]` | `JSON.parse` | Custom deserialization |
+| `dataType` | `string` | `"application/x-substrate-clipboard"` | Clipboard data type key |
+| `disabled` | `boolean` | `false` | Disable the hook |
+
+### Returns
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `copy` | `() => void` | Copy the current selection |
+| `cut` | `() => void` | Cut the current selection |
+| `paste` | `() => Promise<void>` | Paste from clipboard |

package/docs/hooks/use-drag-reorder.mdx

@@ -0,0 +1,60 @@
+---
+title: useDragReorder
+description: Pointer-based list reordering with visual feedback.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/use-drag-reorder
+```
+
+## Usage
+
+```tsx
+import { useDragReorder } from "@/hooks/substrate/use-drag-reorder"
+
+function SortableList() {
+  const [items, setItems] = useState(["Layer 1", "Layer 2", "Layer 3"])
+
+  const { getDragItemProps, isDragging } = useDragReorder({
+    items,
+    onReorder: setItems,
+  })
+
+  return (
+    <ul>
+      {items.map((item, i) => (
+        <li key={item} {...getDragItemProps(i)}>
+          {item}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## How it works
+
+The hook uses pointer capture to track drag movement without relying on the HTML drag-and-drop API. It calculates drop position from the vertical distance moved divided by item height, giving smooth index-based reordering. A configurable threshold (default 3px) prevents accidental drags from firing on normal clicks.
+
+The `getDragItemProps` function returns `onPointerDown`, inline `style` for opacity and CSS transforms, and a `data-dragging` attribute – so non-dragged items visually shift out of the way while the dragged item becomes translucent.
+
+## API
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `T[]` | — | The current ordered list |
+| `onReorder` | `(items: T[]) => void` | — | Called with the new order on drop |
+| `threshold` | `number` | `3` | Pixels to move before a drag starts |
+
+### Returns
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `getDragItemProps` | `(index: number) => DragItemProps` | Spread on each draggable item |
+| `dragIndex` | `number \| null` | Index of the item being dragged |
+| `dropIndex` | `number \| null` | Index where it would be dropped |
+| `isDragging` | `boolean` | Whether a drag is in progress |

package/docs/hooks/use-selection.mdx

@@ -0,0 +1,68 @@
+---
+title: useSelection
+description: Multi-select hook with cmd-click toggle and shift-click range selection.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/use-selection
+```
+
+## Usage
+
+```tsx
+import { useSelection } from "@/hooks/substrate/use-selection"
+
+const itemIds = ["a", "b", "c", "d", "e"]
+
+function LayerPanel() {
+  const { selectedIds, select, selectAll, deselectAll, isSelected } =
+    useSelection({
+      items: itemIds,
+      onSelectionChange: (ids) => console.log("Selected:", ids),
+    })
+
+  return (
+    <ul>
+      {itemIds.map((id) => (
+        <li
+          key={id}
+          onClick={(e) => select(id, e)}
+          style={{ background: isSelected(id) ? "var(--accent)" : undefined }}
+        >
+          {id}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Features
+
+The hook handles three interaction modes automatically based on modifier keys held during a click:
+
+- **Plain click** – selects only the clicked item, deselecting everything else.
+- **⌘/Ctrl + click** – toggles the clicked item without affecting the rest of the selection.
+- **Shift + click** – selects a contiguous range from the last-clicked item to the current one. When combined with ⌘/Ctrl, the range is added to the existing selection rather than replacing it.
+
+## API
+
+### Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `items` | `T[]` | All item IDs in display order – needed for shift-click range calculation |
+| `onSelectionChange` | `(ids: Set<T>) => void` | Called whenever the selection changes |
+
+### Returns
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `selectedIds` | `Set<T>` | The current selection |
+| `select` | `(id: T, event?) => void` | Handle a click – reads `metaKey`, `ctrlKey`, `shiftKey` from the event |
+| `setSelection` | `(ids: T[]) => void` | Replace the selection with specific IDs |
+| `selectAll` | `() => void` | Select every item |
+| `deselectAll` | `() => void` | Clear the selection |
+| `isSelected` | `(id: T) => boolean` | Check whether an item is selected |

package/docs/hooks/use-undoable.mdx

@@ -0,0 +1,83 @@
+---
+title: useUndoable
+description: Lightweight undo/redo stack using refs for performance.
+---
+
+## Install
+
+```bash
+npx shadcn@latest add https://substrate.georgedrury.co.uk/r/use-undoable
+```
+
+## Usage
+
+```tsx
+import { useUndoable } from "@/hooks/substrate/use-undoable"
+
+type CanvasState = { elements: Element[] }
+
+function Editor() {
+  const [state, setState] = useState<CanvasState>({ elements: [] })
+
+  const { pushSnapshot, undo, redo, canUndo, canRedo } =
+    useUndoable<CanvasState>({ maxHistory: 100 })
+
+  function handleMove(id: string, x: number, y: number) {
+    pushSnapshot(state) // save before mutating
+    setState((prev) => ({
+      elements: prev.elements.map((el) =>
+        el.id === id ? { ...el, x, y } : el
+      ),
+    }))
+  }
+
+  function handleUndo() {
+    const previous = undo()
+    if (previous) setState(previous)
+  }
+
+  function handleRedo() {
+    const next = redo()
+    if (next) setState(next)
+  }
+
+  return (
+    <>
+      <HistoryControls
+        canUndo={canUndo}
+        canRedo={canRedo}
+        onUndo={handleUndo}
+        onRedo={handleRedo}
+      />
+      {/* Canvas */}
+    </>
+  )
+}
+```
+
+## Design
+
+The hook stores history in refs rather than state to avoid re-renders on every snapshot push. It only triggers a re-render (via a counter state) when `canUndo` or `canRedo` changes. The `undo()` and `redo()` functions return the restored state (or `null` if empty) – the caller is responsible for applying it.
+
+This pattern keeps the hook generic and framework-agnostic. It works equally well with `useState`, Zustand, or any external state management.
+
+## API
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maxHistory` | `number` | `50` | Maximum number of undo snapshots to keep |
+
+### Returns
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `pushSnapshot` | `(state: T) => void` | Save the current state before a mutation |
+| `undo` | `() => T \| null` | Pop the previous state, or `null` |
+| `redo` | `() => T \| null` | Pop the next state, or `null` |
+| `canUndo` | `boolean` | Whether undo is available |
+| `canRedo` | `boolean` | Whether redo is available |
+| `undoCount` | `number` | Number of undo states |
+| `redoCount` | `number` | Number of redo states |
+| `clear` | `() => void` | Clear all history |