refactor into reusable component

Author: OliverDudgeon

REFACTORING.md

@@ -0,0 +1,189 @@
+# Refactoring Summary
+
+## Overview
+
+The scatter plot component has been refactored into a modular, reusable component library structure suitable for inclusion in a larger component library.
+
+## New Structure
+
+```
+src/components/ScatterPlot/
+├── index.ts              # Main exports and public API
+├── types.ts              # TypeScript interfaces and types
+├── ScatterPlot.tsx       # Main React component
+├── plot.ts               # Observable Plot utilities
+├── brush.ts              # D3 brush selection utilities
+├── legends.ts            # Legend creation utilities
+├── utils.ts              # Data generation utilities
+├── examples.tsx          # Usage examples
+└── README.md             # Component documentation
+```
+
+## Key Improvements
+
+### 1. **Modularity**
+
+- Separated concerns into dedicated files
+- Each module has a single, well-defined responsibility
+- Easy to import and use individual utilities
+
+### 2. **Reusability**
+
+- Component accepts data and configuration as props
+- Customizable through comprehensive config object
+- Callback support for selection events
+- Feature flags for brush and legends
+
+### 3. **Type Safety**
+
+- Comprehensive TypeScript interfaces
+- Exported types for consumer use
+- Proper generic typing for D3 selections
+
+### 4. **Extensibility**
+
+- Utility functions exported for advanced use
+- Easy to extend with new features
+- Custom data generation support
+- Flexible configuration options
+
+### 5. **Developer Experience**
+
+- Clear, documented API
+- Multiple usage examples
+- Inline JSDoc comments
+- README with API reference
+
+## Migration Guide
+
+### Before (Old Component)
+
+```tsx
+import { PlotScatterBrush } from "./components/PlotScatterBrush";
+
+function App() {
+  return <PlotScatterBrush />;
+}
+```
+
+### After (New Component)
+
+```tsx
+import { ScatterPlot, generateRandomData } from "./components/ScatterPlot";
+
+function App() {
+  const data = generateRandomData(800);
+
+  return (
+    <ScatterPlot
+      data={data}
+      config={{
+        xLabel: "Variable X",
+        yLabel: "Variable Y",
+        colorScheme: "turbo",
+      }}
+      enableBrush={true}
+      onSelectionChange={(points, selection) => {
+        console.log(`Selected ${points.length} points`);
+      }}
+    />
+  );
+}
+```
+
+## Public API
+
+### Components
+
+- `ScatterPlot` - Main React component
+
+### Types
+
+- `Point` - Data point interface
+- `ScatterPlotConfig` - Configuration options
+- `ScatterPlotProps` - Component props
+- `BrushSelection` - Selection bounds
+
+### Utilities
+
+- `generateRandomData(n, seed)` - Generate sample data
+- `createScatterPlot(data, config)` - Create Observable Plot
+- `findMainSvg(plotElement)` - Find main SVG in plot
+- `getSizeExtentAndTicks(data)` - Calculate size legend data
+- `createBrush(...)` - Create D3 brush
+- `clearBrushSelection(...)` - Clear brush selection
+- `createSizeLegend(...)` - Create size legend
+- `createLegendWrapper()` - Create legend container
+
+## Features Preserved
+
+All original features have been preserved:
+
+- ✅ 4-variable visualization (x, y, size, color)
+- ✅ Brush selection with drag, resize, and pan
+- ✅ Escape key to clear selection
+- ✅ Color bar legend
+- ✅ Size legend
+- ✅ Selection counter
+- ✅ Opacity-based selection feedback
+
+## New Features Added
+
+- ✅ Configurable through props
+- ✅ Selection change callbacks
+- ✅ Feature flags (brush, legends)
+- ✅ Custom data support
+- ✅ Exported utilities for advanced use
+- ✅ Comprehensive TypeScript types
+- ✅ Usage examples
+- ✅ Full documentation
+
+## Testing Recommendations
+
+1. **Unit Tests**
+
+   - Test utility functions (data generation, calculations)
+   - Test legend creation
+   - Test brush configuration
+
+2. **Integration Tests**
+
+   - Test component rendering with different configs
+   - Test brush interactions
+   - Test selection callbacks
+
+3. **Visual Tests**
+   - Screenshot tests for different configurations
+   - Test different color schemes
+   - Test legend rendering
+
+## Next Steps for Component Library Integration
+
+1. **Package Configuration**
+
+   - Set up proper package.json for library
+   - Configure build output (ES modules + CommonJS)
+   - Set up peer dependencies
+
+2. **Documentation**
+
+   - Add Storybook stories
+   - Create interactive docs
+   - Add more examples
+
+3. **Testing**
+
+   - Add Jest/Vitest tests
+   - Add React Testing Library tests
+   - Set up visual regression tests
+
+4. **Build System**
+
+   - Configure bundler (Rollup/Vite)
+   - Generate type declarations
+   - Set up tree-shaking
+
+5. **Publishing**
+   - Set up NPM publishing
+   - Create GitHub releases
+   - Add CI/CD pipeline