oleh/astrolabe-nvc
1
0
Fork 0
mirror of https://github.com/olehomelchenko/astrolabe-nvc.git synced 2025-12-21 21:22:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Implement Chart Builder feature with UI and functionality

Browse Source 
- Added a new modal for the Chart Builder to allow users to create visualizations from datasets.
- Integrated chart builder state management and validation for encoding configurations.
- Implemented auto-selection of default fields based on dataset column types.
- Added live preview functionality for real-time chart rendering.
- Created a new JavaScript file (chart-builder.js) to handle chart building logic.
- Updated app.js to initialize the chart builder and handle URL state changes.
- Enhanced styles in styles.css for the chart builder UI components.
- Documented the implementation details in project-docs/chart-builder-implementation.md.
This commit is contained in:
Oleh Omelchenko
2025-11-17 14:11:01 +02:00
parent 9645644d26
commit 849e7844fe
7 changed files with 1147 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

435
project-docs/chart-builder-implementation.md Normal file
View File

@@ -0,0 +1,435 @@
# Chart Builder Feature - Implementation Document
## Overview
Add a "Build Chart" button to the dataset details panel that launches a visual chart builder. This helps users bootstrap visualizations from datasets without writing Vega-Lite JSON manually.
## Feature Scope
### Included
- **Mark types**: bar, line, point, area, circle
- **Encoding channels**: X, Y, Color, Size (all optional, but at least one required)
- **Field type selection**: Q (quantitative), O (ordinal), N (nominal), T (temporal)
- **Dimensions**: Width and Height controls (number inputs, empty = auto)
- **Live preview**: Real-time chart preview in right panel
- **Auto-defaults**: Pre-populate based on detected column types
- **URL state**: Support `#datasets/dataset-123/build` routing
### Explicitly Out of Scope
- No transform support (filter, calculate, etc.)
- No layer/concat/facet composition
- No conditional encodings
- No legend/axis customization
- No mark properties (opacity, stroke, etc.)
- No aggregation functions (count, sum, mean)
Users can manually edit generated specs in the editor for advanced features.
## User Flow
1. **Entry Point**: User selects dataset → clicks "Build Chart" button (next to "New Snippet")
2. **Builder Modal Opens**: Chart builder interface with config + preview
3. **Configuration**:
- Select mark type from dropdown
- Set width/height (optional)
- Map columns to encoding channels (X, Y, Color, Size)
- Select data type for each encoding (Q/O/N/T)
4. **Live Preview**: Right panel shows real-time chart as user configures
5. **Validation**: "Create Snippet" button disabled until at least one encoding is set
6. **Save**: Creates new snippet with generated spec, closes builder, opens snippet
## Technical Architecture
### Configuration Schema (Vega-Lite Compatible)
```javascript
// Chart builder state - directly maps to Vega-Lite spec
{
"$schema": "https://vega.github.io/schema/vega-lite/v5.json",
"data": {"name": "dataset-name"}, // Set when opening builder
"mark": {"type": "bar", "tooltip": true},
"width": undefined, // undefined = omit from spec (auto)
"height": undefined,
"encoding": {
"x": {"field": "column1", "type": "quantitative"},
"y": {"field": "column2", "type": "nominal"}
// color, size added conditionally if set
}
}
```
- `currentDatasetName` stored separately in window state (not in spec)
- Empty encodings omitted from final spec
- Tooltip always enabled on marks
### Generated Vega-Lite Spec Example
```json
{
"$schema": "https://vega.github.io/schema/vega-lite/v5.json",
"data": {"name": "my-dataset"},
"mark": {"type": "bar", "tooltip": true},
"width": 400,
"height": 300,
"encoding": {
"x": {"field": "category", "type": "nominal"},
"y": {"field": "value", "type": "quantitative"}
}
}
```
### Column Type Auto-Mapping
Based on existing `dataset.columnTypes`:
- `number` → Q (quantitative)
- `date` → T (temporal)
- `text` → N (nominal)
- `boolean` → N (nominal)
### Default Behavior
When opening builder:
1. Mark type: `bar`
2. Width/Height: empty (auto)
3. X axis: First column with auto-detected type
4. Y axis: Second column (if exists) with auto-detected type
5. Color/Size: Empty (none)
6. Preview renders immediately with defaults
### Validation Rules
- At least one encoding (X or Y) must have a field selected
- "Create Snippet" button disabled until valid
- Error message displayed if configuration is invalid
## UI Layout
### Modal Structure
```
┌────────────────────────────────────────────────────────────┐
│ Build Chart [×] │
├─────────────────────┬──────────────────────────────────────┤
│ [← Back to Dataset] │ │
│ │ │
│ Mark Type * │ PREVIEW PANEL │
│ [Dropdown: bar ▾] │ │
│ │ Live chart preview │
│ Dimensions │ (centered, auto overflow) │
│ Width: [ auto ] │ │
│ Height:[ auto ] │ │
│ │ │
│ Encodings │ │
│ │ │
│ X Axis │ │
│ Field: [Drop ▾] │ │
│ Type: [Q][O][N][T]│ │
│ │ │
│ Y Axis │ │
│ Field: [Drop ▾] │ │
│ Type: [Q][O][N][T]│ │
│ │ │
│ Color (optional) │ │
│ Field: [Drop ▾] │ │
│ Type: [Q][O][N][T]│ │
│ │ │
│ Size (optional) │ │
│ Field: [Drop ▾] │ │
│ Type: [Q][O][N][T]│ │
│ │ │
│ [Cancel] │ │
│ [Create Snippet] │ │
└─────────────────────┴──────────────────────────────────────┘
33.33% width 66.67% width
```
### Type Toggle Buttons
Styled like existing "Draft/Published" buttons in editor header:
- Four buttons per encoding: `[Q] [O] [N] [T]`
- Toggle group with border
- Active state: blue background with white text
- Single selection (radio button behavior)
## Implementation Status
### ✅ FEATURE COMPLETE - Chart Builder Fully Functional
All implementation steps have been completed. The chart builder is now fully functional and ready for testing.
### ✅ Completed: Step 1 - HTML Frame, CSS & Basic Wiring
#### Files Modified:
1. **`index.html`**
- Added `#chart-builder-modal` after `#extract-modal` (lines 361-508)
- Added "Build Chart" button to dataset actions (line 204)
- Added script tag for chart-builder.js (line 876)
- Modal structure includes:
- Header with title + close button
- Left panel: configuration controls (33.33% width)
- Right panel: preview area (66.67% width)
- All form controls with proper IDs
2. **`src/styles.css`**
- Added chart builder styles (lines 491-547)
- Two-column layout: `.chart-builder-container`
- Config panel: `.chart-builder-config` (scrollable with light gray background)
- Preview panel: `.chart-builder-preview` (centered content)
- Mark type toggle group: `.mark-toggle-group` (Bar/Line/Point/Area/Circle buttons)
- Type toggle groups: `.type-toggle-group` (Q/O/N/T buttons)
- Dark theme support for all elements
- Fixed button height/padding to prevent text clipping
3. **`src/js/chart-builder.js`** (NEW)
- `openChartBuilder(datasetId)` - Opens modal and stores dataset ID
- `closeChartBuilder()` - Closes modal and cleans up state
- `initializeChartBuilder()` - Sets up event listeners for buttons
- Global state: `window.chartBuilderState`
4. **`src/js/app.js`**
- Added "Build Chart" button click handler (lines 286-294)
- Added `initializeChartBuilder()` call (line 115)
- Button triggers `openChartBuilder(window.currentDatasetId)`
#### UI Components Added:
- **Mark type toggle buttons** (Bar/Line/Point/Area/Circle) - on same line as label
- **Width/Height number inputs** - at bottom of config panel
- **4 encoding sections** (X, Y, Color, Size):
- Label + dropdown on same row
- Type buttons (Q/O/N/T) on row below
- **Error display area**
- **Action buttons** (Create Snippet, Cancel)
- **Back button** (returns to dataset details)
#### Current State:
✅ Modal opens when clicking "Build Chart" from dataset details
✅ Modal closes with X button, Cancel button, or Back button
✅ UI layout matches design requirements
✅ All styling issues resolved (text no longer clipped)
### ✅ Completed: Step 2 - Full JavaScript Implementation
#### Files Modified:
1. **`src/js/chart-builder.js`** ✅ COMPLETE
- ✅ Populate field dropdowns from dataset columns
- ✅ Implement mark type toggle functionality (Bar/Line/Point/Area/Circle)
- ✅ Implement encoding type toggle functionality (Q/O/N/T)
- ✅ Generate Vega-Lite spec from UI state
- ✅ Validate configuration (at least one encoding required)
- ✅ Create snippet from generated spec
- ✅ Auto-select smart defaults based on column types
- ✅ Debounced preview rendering using existing settings
- ✅ URL state management integration
- ✅ Reuse `resolveDatasetReferences()` from editor.js
- ~468 lines of fully functional code
2. **`src/js/config.js`** ✅ COMPLETE
- ✅ Updated URLState.parse() to support `#datasets/dataset-123/build`
- ✅ Updated URLState.update() to generate chart builder URLs
- ✅ Added chart-builder-modal to ModalManager.closeAny() for ESC key support
3. **`src/js/app.js`** ✅ COMPLETE
- ✅ Updated handleURLStateChange() to handle chart builder action
- ✅ Opens chart builder when URL contains `/build` suffix
- ✅ Chart builder integrated with browser back/forward navigation
### ✅ All Core Tasks Complete
#### ✅ Step 2: Core JavaScript Functionality
All functions implemented in `chart-builder.js`:
- ✅ `openChartBuilder(datasetId)` - Initialize builder with dataset
- ✅ `closeChartBuilder()` - Close modal and cleanup
- ✅ `initializeChartBuilder()` - Set up event listeners
- ✅ `updateChartBuilderPreview()` - Debounced preview render
- ✅ `generateVegaLiteSpec()` - Build spec from UI state
- ✅ `validateChartConfig()` - Check if config is valid
- ✅ `createSnippetFromBuilder()` - Generate and save snippet
- ✅ `populateFieldDropdowns(dataset)` - Fill dropdowns with columns
- ✅ `autoSelectDefaults(dataset)` - Smart defaults based on types
- ✅ `mapColumnTypeToVegaType()` - Convert dataset types to Vega-Lite types
- ✅ `setEncoding()` - Update UI and state for encodings
- ✅ `renderChartBuilderPreview()` - Render preview with error handling
#### ✅ Step 3: Preview Rendering (No Refactor Needed)
- ✅ Reused existing `resolveDatasetReferences()` from editor.js
- ✅ Used `window.vegaEmbed()` directly in chart builder
- ✅ No need for additional refactoring - kept code simple
#### ✅ Step 4: Integration
- ✅ "Build Chart" button already wired in `index.html` (line 204)
- ✅ Button handler already set up in `app.js` (lines 286-294)
- ✅ URL state handling implemented in `config.js` and `app.js`
- ✅ Back button, Cancel, Close, and ESC key all work correctly
- ✅ URL updates properly when opening/closing builder
- ✅ Browser back/forward navigation fully supported
#### 📋 Step 5: Testing & Polish (Ready for Manual Testing)
The following should be tested manually:
- [ ] Test with datasets of different types (JSON, CSV, TSV)
- [ ] Test with datasets with many columns
- [ ] Test with datasets with few columns (edge cases)
- [ ] Test URL state navigation (back/forward buttons)
- [ ] Test keyboard shortcuts (ESC to close)
- [ ] Test dark theme compatibility
- [ ] Test all mark types (Bar, Line, Point, Area, Circle)
- [ ] Test all encoding types (Q, O, N, T)
- [ ] Test dimension inputs (width/height)
- [ ] Test error handling (invalid specs, missing data)
## Code Organization
### Event Flow
```
User clicks "Build Chart"
→ openChartBuilder(datasetId)
→ Fetch dataset from IndexedDB
→ Populate field dropdowns with columns
→ Auto-select defaults (first 2 columns)
→ Show modal
→ Update URL to #datasets/dataset-123/build
User changes config (mark/field/type)
→ Event handler captures change
→ Update internal spec state
→ Validate configuration
→ Enable/disable "Create Snippet" button
→ Debounced: updateChartBuilderPreview()
User clicks "Create Snippet"
→ validateChartConfig()
→ generateVegaLiteSpec()
→ Create snippet via SnippetStorage
→ Close builder
→ Close dataset modal
→ Open snippet in editor
→ Update URL to #snippet-123
```
### Reusable Functions
**From existing codebase:**
- `DatasetStorage.getDataset(id)` - Fetch dataset
- `SnippetStorage.saveSnippet(snippet)` - Save new snippet
- `createSnippet(spec, name)` - Generate snippet object
- `selectSnippet(id)` - Open snippet in editor
- `URLState.update()` - Update URL state
**To be refactored:**
- `renderVegaSpec(containerId, spec, options)` - Generic Vega renderer
**To be created:**
- `openChartBuilder(datasetId)`
- `closeChartBuilder()`
- `generateVegaLiteSpec()`
- `validateChartConfig()`
- etc. (see Step 2 above)
## Design Decisions
### Why Vega-Lite Compatible Schema?
- Keeps builder state directly mappable to output spec
- No translation layer needed
- Easy to serialize/debug
- Can potentially expose spec editor later
### Why Type Toggle Buttons?
- Matches existing UI patterns (Draft/Published)
- Single-click interaction (vs dropdown)
- Visual clarity for 4 options
- Familiar to users who use editor
### Why Separate "Build Chart" from "New Snippet"?
- Different workflows: guided vs manual
- Both are valid entry points
- Allows users to choose their preferred method
- Doesn't force beginners into code
### Why No Aggregations in v1?
- Keeps UI simple and focused
- Most common use case: direct field mapping
- Aggregations add significant complexity
- Users can add manually in editor after
### Why Center Preview (Not Fit)?
- Respects user's width/height choices
- Consistent with main preview panel behavior
- Avoids confusion about final size
- Allows scrolling for large charts
## File Structure
```
/src
/js
- chart-builder.js (NEW - ~400 lines)
- editor.js (MODIFIED - refactor ~50 lines)
- dataset-manager.js (MODIFIED - add button handler ~20 lines)
- app.js (MODIFIED - URL state + init ~30 lines)
- snippet-manager.js (NO CHANGES)
- config.js (NO CHANGES)
- styles.css (MODIFIED - added chart builder styles)
/index.html (MODIFIED - added modal HTML + button)
/project-docs
- chart-builder-implementation.md (THIS FILE)
```
## Next Steps
1. ✅ Get approval on HTML/CSS frame - DONE
2. ✅ Implement chart-builder.js (core logic) - DONE
3. ✅ Refactor editor.js (reusable preview) - NOT NEEDED (reused existing functions)
4. ✅ Wire up integrations (dataset-manager.js, app.js) - DONE
5. **Test with real datasets** - READY FOR MANUAL TESTING
6. **Document in CHANGELOG.md** - TODO after testing
## Notes & Considerations
- **Performance**: Preview rendering is debounced (use existing render debounce setting)
- **Error Handling**: Invalid specs show error overlay in preview (reuse existing pattern)
- **Accessibility**: All form controls have labels and proper IDs
- **Keyboard Support**: Escape closes modal, Tab navigation works
- **URL State**: Supports browser back/forward navigation
- **Dark Theme**: All styles support experimental theme
- **Empty State**: Placeholder text when no valid config yet
- **Validation**: Clear error messages for invalid states
## Future Enhancements (Not in Scope)
- Aggregation support (count, sum, mean, etc.)
- Transform support (filter, calculate)
- Faceting/composition (layer, concat, vconcat, hconcat)
- Advanced mark properties (opacity, stroke, strokeWidth)
- Axis/legend customization (title, format, scale)
- Custom color schemes
- Saved chart templates
- Chart recommendations based on data types
- Export chart as PNG/SVG directly from builder
---
**Document Status**: ✅ IMPLEMENTATION COMPLETE - Ready for Manual Testing
**Last Updated**: 2025-11-17
**Current Phase**: All Steps Complete - Chart Builder Fully Functional
## Summary of Completed Work
### ✅ Fully Functional Features:
- ✅ Complete modal UI with proper layout (1/3 config, 2/3 preview)
- ✅ Mark type toggle buttons (Bar/Line/Point/Area/Circle) - fully interactive
- ✅ Encoding sections with field dropdowns and type buttons (Q/O/N/T) - fully interactive
- ✅ Dimensions inputs (Width/Height) - functional with live preview
- ✅ Modal open/close functionality (Build Chart button, X, Cancel, Back, ESC)
- ✅ Proper styling without text clipping issues
- ✅ Dark theme support
- ✅ Dropdowns populated with dataset columns
- ✅ Interactive toggles for mark type and encoding types
- ✅ Vega-Lite spec generation from UI state
- ✅ Live preview with debounced rendering
- ✅ Validation and "Create Snippet" functionality
- ✅ URL state integration (#datasets/dataset-123/build)
- ✅ Browser back/forward navigation support
- ✅ Auto-defaults based on column types
- ✅ Error handling and validation messages
### Ready for Testing:
The chart builder is now feature-complete and ready for manual testing with real datasets. All core functionality has been implemented and integrated.