Web Synth/Patcher Surface

Pan/zoom patcher canvas hosting module cards, cables, and viewport toolbar actions.

Web Synth

Edit

Play

Preview

Narrow touch edit

Narrow inline play

/** @jsxRuntime automatic */ /** @jsxImportSource preact */ // Migrated to the default-export story contract (issue #2051). The old v2 // module-level `controls: ControlsMap` (from the now-deleted styleguide-v2) is // gone — each mode is enumerated as its own variant instead. `render` returns // the client island `<ControlledStory />` without executing it, so the module is // SSR-import-safe; the patcher surface only runs inside the preview iframe. import { defineStory } from '@lib/styleguide/story-contract'; import type { StoryMeta } from '@lib/styleguide/story-contract'; import type { TargetedEvent } from 'preact'; import { useCallback, useMemo, useRef, useState } from 'preact/hooks'; import type { WebSynthPatchDoc } from './doc/patch-doc-types'; import type { PatcherModuleCardProps, PatcherModuleMenuActions, PatcherPortRef, PatcherSelection, PatcherSurfaceController, PatcherViewport, } from './patcher-contract'; import { createPatcherToolbarActions, PatcherSurface } from './patcher-surface'; import './patcher-surface.stories.css'; const meta: StoryMeta = { title: 'Web Synth/Patcher Surface', category: 'Web Synth', description: 'Pan/zoom patcher canvas hosting module cards, cables, and viewport toolbar actions.', usage: `import { PatcherSurface } from '@/src/components/web-synth/patcher-surface';\n\n<PatcherSurface doc={doc} mode="edit" renderModuleCard={renderCard} />`, }; export default meta; const STORY_DOC: WebSynthPatchDoc = { version: 1, name: 'Variable-height patch', modules: [ { id: 'mod-noise', type: 'noise', x: -420, y: -150, params: { color: 'white' } }, { id: 'mod-filter', type: 'vcf', x: -90, y: -220, params: { cutoff: 900, q: 4, mode: 'lowpass' }, }, { id: 'mod-out', type: 'out', x: 280, y: -80, params: { level: 0.7 } }, { id: 'mod-panel', type: 'panel', x: -150, y: 180, w: 300, h: 150, params: {}, ui: { text: 'Touch edit: drag headers, jacks, and the resize corner.', fontSize: 'm' }, }, ], cables: [ { id: 'cable-noise-filter', from: { module: 'mod-noise', port: 'out' }, to: { module: 'mod-filter', port: 'in' }, kind: 'audio', }, { id: 'cable-filter-out', from: { module: 'mod-filter', port: 'out' }, to: { module: 'mod-out', port: 'in' }, kind: 'audio', }, ], }; function StoryPort({ port, label, registerPortAnchor, registerPortHitTarget, onPortPointerDown, }: { port: PatcherPortRef; label: string; registerPortAnchor: PatcherModuleCardProps['registerPortAnchor']; registerPortHitTarget: PatcherModuleCardProps['registerPortHitTarget']; onPortPointerDown: PatcherModuleCardProps['onPortPointerDown']; }) { const { moduleId, portId, direction, kind } = port; const stablePort = useMemo( () => ({ moduleId, portId, direction, kind }), [direction, kind, moduleId, portId], ); const anchorRef = useCallback( (element: HTMLElement | null) => registerPortAnchor(stablePort, element), [registerPortAnchor, stablePort], ); const hitRef = useCallback( (element: HTMLButtonElement | null) => registerPortHitTarget(stablePort, element), [registerPortHitTarget, stablePort], ); return ( <button ref={hitRef} type="button" class="zws-patcher-story-card__port" data-direction={port.direction} data-kind={port.kind} aria-label={`${label}, ${port.kind} ${port.direction === 'out' ? 'output' : 'input'}`} onPointerDown={(event) => onPortPointerDown(port, event)} > <i ref={anchorRef} class="zws-patcher-story-card__pin" aria-hidden="true" /> <span>{label}</span> </button> ); } function StoryCard(props: PatcherModuleCardProps) { const uiText = props.instance.ui?.text ?? ''; return ( <article ref={props.registerCardElement} class="zws-patcher-story-card" data-mode={props.mode} data-story-height={ props.manifest.type === 'noise' ? 'short' : props.manifest.type === 'vcf' ? 'tall' : 'medium' } style={{ width: `${props.manifest.resizable ? (props.instance.w ?? 224) : 224}px`, ...(props.manifest.resizable && props.instance.h !== undefined && { height: `${props.instance.h}px` }), }} > <header class="zws-patcher-story-card__header" onPointerDown={props.onHeaderPointerDown}> <span> <strong>{props.manifest.picker.label}</strong> <small>{props.manifest.type}</small> </span> {props.mode === 'edit' && ( <button type="button" class="zws-patcher-story-card__menu" aria-label={`Open ${props.manifest.picker.label} module menu`} onClick={(event) => props.onOpenMenu(event.currentTarget)} > ⋮ </button> )} </header> <div class="zws-patcher-story-card__body"> {props.manifest.type === 'panel' ? ( <textarea aria-label="Panel text" value={uiText} readOnly={props.mode !== 'edit'} onInput={(event: TargetedEvent<HTMLTextAreaElement>) => props.onUiChange({ text: event.currentTarget.value }) } /> ) : ( <> <p>{props.manifest.picker.description}</p> {props.manifest.params.slice(0, 3).map((param) => ( <label key={param.id}> <span>{param.label}</span> <input type="range" min={param.min ?? 0} max={param.max ?? 1} step={param.step ?? 0.01} value={ typeof props.instance.params[param.id] === 'number' ? props.instance.params[param.id] : typeof param.initial === 'number' ? param.initial : 0 } disabled={props.mode === 'preview' || param.kind !== 'slider'} aria-label={param.label} onInput={(event: TargetedEvent<HTMLInputElement>) => props.onParamChange(param.id, Number(event.currentTarget.value)) } /> </label> ))} </> )} </div> <div class="zws-patcher-story-card__ports zws-patcher-story-card__ports--in"> {props.manifest.ports .filter(({ direction }) => direction === 'in') .map((manifestPort) => { const port: PatcherPortRef = { moduleId: props.instance.id, portId: manifestPort.id, direction: manifestPort.direction, kind: manifestPort.kind, }; return ( <StoryPort key={port.portId} port={port} label={manifestPort.label} registerPortAnchor={props.registerPortAnchor} registerPortHitTarget={props.registerPortHitTarget} onPortPointerDown={props.onPortPointerDown} /> ); })} </div> <div class="zws-patcher-story-card__ports zws-patcher-story-card__ports--out"> {props.manifest.ports .filter(({ direction }) => direction === 'out') .map((manifestPort) => { const port: PatcherPortRef = { moduleId: props.instance.id, portId: manifestPort.id, direction: manifestPort.direction, kind: manifestPort.kind, }; return ( <StoryPort key={port.portId} port={port} label={manifestPort.label} registerPortAnchor={props.registerPortAnchor} registerPortHitTarget={props.registerPortHitTarget} onPortPointerDown={props.onPortPointerDown} /> ); })} </div> {props.mode === 'edit' && props.manifest.resizable && ( <button type="button" class="zws-patcher-story-card__resize" aria-label={`Resize ${props.manifest.picker.label} module`} onPointerDown={props.onResizePointerDown} /> )} </article> ); } function ControlledStory({ mode, narrow = false, }: { mode: PatcherModuleCardProps['mode']; narrow?: boolean; }) { const [doc, setDoc] = useState<WebSynthPatchDoc>(STORY_DOC); const [selection, setSelection] = useState<PatcherSelection>(null); const [viewport, setViewport] = useState<PatcherViewport>({ panX: 0, panY: 0, zoom: 0.82 }); const [menu, setMenu] = useState<{ moduleId: string; actions: PatcherModuleMenuActions; } | null>(null); const [lastChange, setLastChange] = useState('No document change yet'); const controllerRef = useRef<PatcherSurfaceController | null>(null); const runToolbar = (action: keyof ReturnType<typeof createPatcherToolbarActions>) => { if (!controllerRef.current) return; createPatcherToolbarActions(controllerRef.current)[action](); }; return ( <section class="zws-patcher-story" data-narrow={narrow ? '' : undefined} aria-label={`${mode} patcher story`} > <div class="zws-patcher-story__toolbar" aria-label="Patcher viewport controls"> <strong>{mode}</strong> <button type="button" aria-label="Zoom out" onClick={() => runToolbar('zoomOut')}> − </button> <button type="button" aria-label="Zoom in" onClick={() => runToolbar('zoomIn')}> + </button> <button type="button" onClick={() => runToolbar('fit')}> Fit </button> <button type="button" onClick={() => runToolbar('resetView')}> Reset </button> <small>{lastChange}</small> </div> <div class="zws-patcher-story__surface"> <PatcherSurface doc={doc} mode={mode} selection={selection} viewport={viewport} renderModuleCard={(cardProps) => <StoryCard {...cardProps} />} onPatchChange={(nextDoc, change) => { setDoc(nextDoc); setLastChange(change.type); }} onSelectionChange={setSelection} onViewportChange={setViewport} registerController={(controller) => { controllerRef.current = controller; }} onRequestModuleMenu={(moduleId, _anchor, actions) => setMenu({ moduleId, actions })} /> </div> {menu && ( <div class="zws-patcher-story__menu" role="group" aria-label="Stub module menu"> <span>{menu.moduleId}</span> <button type="button" onClick={() => menu.actions.duplicate()}> Duplicate </button> <button type="button" onClick={() => menu.actions.delete()}> Delete </button> <button type="button" onClick={() => setMenu(null)}> Close </button> </div> )} {mode === 'play' && narrow && ( <p class="zws-patcher-story__policy-note"> Narrow inline play keeps one-finger page scrolling; use these toolbar controls for the canvas. </p> )} </section> ); } export const Edit = defineStory({ name: 'Edit', render: () => <ControlledStory mode="edit" />, }); export const Play = defineStory({ name: 'Play', render: () => <ControlledStory mode="play" />, }); export const Preview = defineStory({ name: 'Preview', render: () => <ControlledStory mode="preview" />, }); export const NarrowTouchEdit = defineStory({ name: 'Narrow touch edit', render: () => <ControlledStory mode="edit" narrow />, }); export const NarrowInlinePlay = defineStory({ name: 'Narrow inline play', render: () => <ControlledStory mode="play" narrow />, });