snapshot of https://github.com/tldraw/tldraw.git (main, 2026-09-23; blobs > 131072B omitted)

templates/shader/src/config-panel/config-panel.md

@@ -0,0 +1,239 @@
+# Config Panel
+
+A collapsible, reusable configuration panel component for building interactive controls for shader templates. The config panel provides a consistent UI for adjusting shader parameters in real-time.
+
+The config panel system consists of:
+
+- **ConfigPanel**: Container component with collapse/expand functionality and reset button
+- **ConfigPanelSlider**: Slider control for numeric values (int or float)
+- **ConfigPanelBooleanControl**: Checkbox control for boolean values
+- **ConfigPanelLabel**: Text label component
+
+All controls are styled to match the tldraw UI and automatically handle state persistence.
+
+## ConfigPanel Component
+
+The main container component that wraps all configuration controls.
+
+### Props
+
+- `children`: React nodes containing the control components
+- `onReset`: Callback function to reset configuration to defaults
+
+### Features
+
+- **Collapsible**: Click the mixer icon to expand/collapse the panel
+- **Persistent State**: Panel expanded/collapsed state is saved to localStorage
+- **Reset Button**: Visible when expanded, calls the `onReset` callback
+- **Scroll Prevention**: Prevents wheel events from affecting the canvas behind it
+
+### Usage
+
+```tsx
+import { ConfigPanel } from '../config-panel/ConfigPanel'
+import { resetMyConfig } from './config'
+
+function MyConfigPanel() {
+	return <ConfigPanel onReset={resetMyConfig}>{/* Add controls here */}</ConfigPanel>
+}
+```
+
+## ConfigPanelSlider
+
+A slider control for numeric values with automatic range mapping.
+
+### Props
+
+- `prop`: Property name (passed to onChange)
+- `label`: Display label for the slider
+- `min`: Minimum value
+- `max`: Maximum value
+- `value`: Current value
+- `type`: Either `'float'` or `'int'`
+- `onChange`: Callback `(prop: string, value: number) => void`
+
+### Features
+
+- Automatically maps between slider steps (1-100) and actual value range
+- Rounds to integers when `type='int'`
+- Uses tldraw's built-in `TldrawUiSlider` component
+
+### Usage
+
+```tsx
+<ConfigPanelSlider
+	prop="splatRadius"
+	label="Splat Radius"
+	min={0.01}
+	max={1}
+	value={config.splatRadius}
+	type="float"
+	onChange={handleChange}
+/>
+```
+
+## ConfigPanelBooleanControl
+
+A checkbox control for boolean values.
+
+### Props
+
+- `prop`: Property name (passed to onChange)
+- `label`: Display label for the checkbox
+- `value`: Current boolean value
+- `onChange`: Callback `(prop: string, value: boolean) => void`
+
+### Usage
+
+```tsx
+<ConfigPanelBooleanControl
+	prop="paused"
+	label="Paused"
+	value={config.paused}
+	onChange={handleChange}
+/>
+```
+
+## Reactive Configuration Pattern
+
+The config panel works with tldraw's reactive `atom` system for automatic state management and persistence.
+
+### Setting Up Config
+
+```tsx
+import { atom, react } from 'tldraw'
+
+// 1. Define default configuration
+const DEFAULT_CONFIG = {
+	quality: 0.5,
+	paused: false,
+	// ... other properties
+}
+
+// 2. Load from localStorage with fallback
+const STORAGE_KEY = 'my-shader-config'
+let initialValue = DEFAULT_CONFIG
+
+try {
+	const value = localStorage.getItem(STORAGE_KEY)
+	if (value) initialValue = JSON.parse(value)
+} catch {
+	// Use defaults if parse fails
+}
+
+// 3. Create reactive atom
+export const myConfig = atom('my-config', initialValue)
+
+// 4. Reset function
+export function resetMyConfig() {
+	myConfig.set(DEFAULT_CONFIG)
+}
+
+// 5. Auto-save to localStorage
+react('save to local storage', () => {
+	localStorage.setItem(STORAGE_KEY, JSON.stringify(myConfig.get()))
+})
+```
+
+### Using Config in Component
+
+```tsx
+import { useValue } from 'tldraw'
+import { myConfig } from './config'
+
+export function MyConfigPanel() {
+	// Subscribe to reactive config changes
+	const config = useValue('config', () => myConfig.get(), [])
+
+	// Update config properties
+	const handleChange = useCallback((prop: string, value: number | boolean) => {
+		myConfig.update((prev) => ({ ...prev, [prop]: value }))
+	}, [])
+
+	return (
+		<ConfigPanel onReset={resetMyConfig}>
+			<ConfigPanelSlider
+				prop="quality"
+				label="Quality"
+				min={0}
+				max={1}
+				value={config.quality}
+				type="float"
+				onChange={handleChange}
+			/>
+			<ConfigPanelBooleanControl
+				prop="paused"
+				label="Paused"
+				value={config.paused}
+				onChange={handleChange}
+			/>
+		</ConfigPanel>
+	)
+}
+```
+
+## Styling
+
+The config panel uses CSS classes that can be customized:
+
+- `.shader-config-panel`: Main panel container
+- `.shader-config-panel--expanded`: Applied when expanded
+- `.shader-config-panel--collapsed`: Applied when collapsed
+- `.shader-config-panel__header`: Header with reset and toggle buttons
+- `.shader-config-panel__content`: Content area (only visible when expanded)
+- `.shader-config-panel__control`: Base class for individual controls
+- `.shader-config-panel__control--slider`: Modifier for slider controls
+- `.shader-config-panel__control--boolean`: Modifier for boolean controls
+- `.shader-config-panel__boolean-input`: Checkbox input element
+- `.shader-config-panel__label`: Label text for controls
+
+## Integration with Shader Manager
+
+The config panel is typically placed in the tldraw component tree and accessed by a shader manager:
+
+```tsx
+function MyShaderRenderer({ editor }: { editor: Editor }) {
+	const canvas = useRef<HTMLCanvasElement>(null)
+
+	useEffect(() => {
+		if (!canvas.current) return
+		// Initialize shader with reactive config
+		const manager = new MyShaderManager(canvas.current, editor, myConfig)
+		return () => manager.dispose()
+	}, [editor])
+
+	return <canvas ref={canvas} className="shader-app__canvas" />
+}
+
+export default function ShaderExample() {
+	return (
+		<div className="tldraw__editor">
+			<Tldraw>
+				<MyShaderRenderer />
+				<MyConfigPanel />
+			</Tldraw>
+		</div>
+	)
+}
+```
+
+## Best Practices
+
+1. **Group Related Controls**: Organize controls by category (e.g., "General Settings", "Simulation Settings", "Visual Effects")
+2. **Sensible Ranges**: Choose min/max values that provide useful adjustment without breaking the effect
+3. **Clear Labels**: Use concise, descriptive labels (abbreviate if needed to fit the UI)
+4. **Reasonable Defaults**: Set defaults that work well out of the box
+5. **Persist State**: Always use the reactive atom pattern with localStorage persistence
+6. **Type Safety**: Define TypeScript interfaces for your config objects
+7. **Reset Function**: Always provide a reset function for returning to defaults
+
+## Example: Complete Config Panel Setup
+
+See `templates/shader/src/fluid/` for a full example implementing:
+
+- `config.ts`: Reactive atom with localStorage persistence
+- `FluidConfigPanel.tsx`: Complete configuration UI with 20+ controls
+- `FluidManager.ts`: Shader manager that reads from the config atom
+- Integration with WebGL fluid simulation
+
+This demonstrates the full pattern for creating a configurable shader effect with a professional UI.