mirror of
https://github.com/olehomelchenko/astrolabe-nvc.git
synced 2025-12-21 13:12:23 +00:00
feat: update documentation
This commit is contained in:
15
CHANGELOG.md
15
CHANGELOG.md
@@ -5,6 +5,21 @@ All notable changes to Astrolabe will be documented in this file.
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
||||
|
||||
---
|
||||
## [1.1.0] - 2025-11-17
|
||||
|
||||
### Added
|
||||
- **Visual Chart Builder**: Create Vega-Lite visualizations without writing JSON
|
||||
- Access via "Build Chart" button in dataset details panel
|
||||
- Support for 5 mark types: Bar, Line, Point, Area, Circle
|
||||
- Map dataset columns to encoding channels: X, Y, Color, Size
|
||||
- 4 data type options per encoding: Quantitative, Ordinal, Nominal, Temporal
|
||||
- Smart defaults based on column type detection
|
||||
- Live preview with debounced rendering
|
||||
- Width/Height dimension controls
|
||||
- Validation with helpful error messages
|
||||
- URL state support (`#datasets/dataset-123/build`)
|
||||
- Browser back/forward navigation integrated
|
||||
- Creates snippets with auto-generated names and dataset references
|
||||
|
||||
## [1.0.0] - 2025-10-15
|
||||
|
||||
|
||||
@@ -4,6 +4,7 @@ A lightweight, browser-based snippet manager for Vega-Lite visualizations. Organ
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Visual chart builder**: Create charts without writing JSON – select mark type, map fields to encodings, and see live preview
|
||||
- **Draft/published workflow**: Experiment safely without losing your working version
|
||||
- **Dataset library**: Store and reuse datasets across snippets (JSON, CSV, TSV, TopoJSON)
|
||||
- **Import/export**: Back up your work or move it between browsers
|
||||
@@ -67,6 +68,7 @@ A lightweight, browser-based snippet manager for Vega-Lite visualizations. Organ
|
||||
- `app.js` – Application initialization and event handlers
|
||||
- `snippet-manager.js` – Snippet CRUD operations
|
||||
- `dataset-manager.js` – Dataset management with IndexedDB
|
||||
- `chart-builder.js` – Visual chart builder for creating specs from datasets
|
||||
- `user-settings.js` – Settings persistence and validation
|
||||
- `editor.js` – Monaco Editor and Vega-Lite rendering
|
||||
- `panel-manager.js` – Resizable layout and persistence
|
||||
|
||||
@@ -158,6 +158,7 @@ web/
|
||||
│ │ ├── config.js # Global variables, settings API, utilities
|
||||
│ │ ├── snippet-manager.js # Snippet CRUD, storage, search, sort
|
||||
│ │ ├── dataset-manager.js # Dataset CRUD, IndexedDB operations
|
||||
│ │ ├── chart-builder.js # Visual chart builder for creating specs
|
||||
│ │ ├── panel-manager.js # Layout resizing and persistence
|
||||
│ │ ├── editor.js # Monaco and Vega library integration
|
||||
│ │ ├── user-settings.js # Settings management
|
||||
@@ -194,7 +195,17 @@ web/
|
||||
- Table preview rendering with type detection
|
||||
- Import/export with format conversion
|
||||
- Extract inline data to dataset
|
||||
- Usage tracking (snippet ↔ dataset linking)
|
||||
|
||||
**chart-builder.js** (~457 lines)
|
||||
- Visual chart builder for creating Vega-Lite specs from datasets
|
||||
- Mark type selection (Bar, Line, Point, Area, Circle)
|
||||
- Encoding channel mapping (X, Y, Color, Size)
|
||||
- Data type selection (Quantitative, Ordinal, Nominal, Temporal)
|
||||
- Smart defaults based on column type detection
|
||||
- Live preview with debounced rendering
|
||||
- Width/Height dimension controls
|
||||
- Validation and error handling
|
||||
- Snippet creation with auto-generated metadata
|
||||
|
||||
**panel-manager.js** (~200 lines)
|
||||
- Drag-to-resize implementation
|
||||
|
||||
@@ -278,100 +278,59 @@ The following should be tested manually:
|
||||
### 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 clicks "Build Chart" → openChartBuilder(datasetId)
|
||||
→ Fetch dataset, populate dropdowns, auto-select defaults
|
||||
→ 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 changes config → Update state → Debounced preview update
|
||||
|
||||
User clicks "Create Snippet"
|
||||
→ validateChartConfig()
|
||||
→ generateVegaLiteSpec()
|
||||
→ Create snippet via SnippetStorage
|
||||
→ Close builder
|
||||
→ Close dataset modal
|
||||
→ Open snippet in editor
|
||||
→ Update URL to #snippet-123
|
||||
User clicks "Create Snippet" → Validate → Generate spec
|
||||
→ Create snippet → Close modals → Open in editor
|
||||
```
|
||||
|
||||
### Reusable Functions
|
||||
### Key Functions
|
||||
|
||||
- `openChartBuilder(datasetId)` - Initialize builder with dataset
|
||||
- `populateFieldDropdowns(dataset)` - Fill dropdowns with columns
|
||||
- `autoSelectDefaults(dataset)` - Smart defaults based on types
|
||||
- `setEncoding(channel, field, type)` - Update UI and state
|
||||
- `generateVegaLiteSpec()` - Build spec from UI state
|
||||
- `validateChartConfig()` - Check if config is valid
|
||||
- `renderChartBuilderPreview()` - Render preview with error handling
|
||||
- `createSnippetFromBuilder()` - Generate and save snippet
|
||||
- `closeChartBuilder()` - Close modal and cleanup
|
||||
|
||||
### Reuses From Existing Codebase
|
||||
|
||||
**From existing codebase:**
|
||||
- `DatasetStorage.getDataset(id)` - Fetch dataset
|
||||
- `SnippetStorage.saveSnippet(snippet)` - Save new snippet
|
||||
- `createSnippet(spec, name)` - Generate snippet object
|
||||
- `resolveDatasetReferences(spec)` - Resolve data.name references
|
||||
- `SnippetStorage.saveSnippet()` - Save new snippet
|
||||
- `generateSnippetId()` / `generateSnippetName()` - Auto-generate IDs/names
|
||||
- `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)
|
||||
- `showToast()` - User notifications
|
||||
- `getSetting()` - Access user settings (debounce)
|
||||
|
||||
## 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 Vega-Lite Compatible Schema?** - Direct mapping to output spec, no translation layer, easy to debug.
|
||||
|
||||
### 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 Type Toggle Buttons?** - Matches existing UI (Draft/Published buttons), single-click interaction, visual clarity.
|
||||
|
||||
### 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 Separate "Build Chart" from "New Snippet"?** - Different workflows (guided vs manual), both valid entry points.
|
||||
|
||||
### 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 No Aggregations in v1?** - Keeps UI simple, most common use case is direct mapping, users can add in editor.
|
||||
|
||||
### 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
|
||||
**Why Center Preview?** - Respects dimensions, consistent with main preview, 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)
|
||||
```
|
||||
**Files Modified:**
|
||||
- `src/js/chart-builder.js` - NEW (~457 lines)
|
||||
- `src/js/config.js` - URL state support for `/build` action
|
||||
- `src/js/app.js` - URL handler for chart builder
|
||||
- `src/styles.css` - Chart builder styles (lines 491-547)
|
||||
- `index.html` - Chart builder modal HTML + "Build Chart" button
|
||||
|
||||
## Next Steps
|
||||
|
||||
@@ -382,28 +341,22 @@ User clicks "Create Snippet"
|
||||
5. **Test with real datasets** - READY FOR MANUAL TESTING
|
||||
6. **Document in CHANGELOG.md** - TODO after testing
|
||||
|
||||
## Notes & Considerations
|
||||
## Notes
|
||||
|
||||
- **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
|
||||
- Performance: Debounced preview using existing render settings
|
||||
- Error Handling: Shows inline error messages with helpful text
|
||||
- Keyboard Support: ESC closes modal, Tab navigation
|
||||
- URL State: Browser back/forward navigation integrated
|
||||
- Dark Theme: Full support for experimental theme
|
||||
|
||||
## Future Enhancements (Not in Scope)
|
||||
## Future Enhancements
|
||||
|
||||
- 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
|
||||
Potential improvements for future versions:
|
||||
- Aggregations (count, sum, mean), transforms (filter, calculate)
|
||||
- Layering, faceting, and composition
|
||||
- Advanced mark properties, axis/legend customization
|
||||
- Custom color schemes, saved templates
|
||||
- Chart recommendations based on data types
|
||||
- Export chart as PNG/SVG directly from builder
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -243,23 +243,38 @@
|
||||
- Button in dataset details to create snippet
|
||||
- Auto-generated minimal Vega-Lite spec with dataset reference
|
||||
- Pre-populated comment and datasetRefs
|
||||
- **Visual Chart Builder**:
|
||||
- "Build Chart" button in dataset details panel
|
||||
- Modal interface with configuration (33%) and preview (67%) panels
|
||||
- Mark type selection: Bar, Line, Point, Area, Circle
|
||||
- Encoding channels: X, Y, Color, Size (all optional)
|
||||
- Data type selection: Q (quantitative), O (ordinal), N (nominal), T (temporal)
|
||||
- Smart defaults based on column type detection
|
||||
- Live preview with debounced rendering
|
||||
- Width/Height dimension controls
|
||||
- Validation (requires at least one encoding)
|
||||
- URL state support: `#datasets/dataset-123/build`
|
||||
- Creates snippets with auto-generated names and metadata
|
||||
- **UI Enhancements**:
|
||||
- Larger modal (95% width, max 1200px, 85% height)
|
||||
- Actions moved to top of dataset details
|
||||
- Dataset list with usage badges
|
||||
|
||||
**Files**: `dataset-manager.js` (lines 19-1165), `snippet-manager.js` (dataset tracking), `app.js` (event handlers), `index.html` (UI), `styles.css` (table styles)
|
||||
**Files**: `dataset-manager.js` (lines 19-1165), `chart-builder.js` (~457 lines), `snippet-manager.js` (dataset tracking), `app.js` (event handlers), `config.js` (URL state), `index.html` (UI), `styles.css` (table styles, chart builder)
|
||||
|
||||
---
|
||||
|
||||
## 📊 **Feature Statistics**
|
||||
|
||||
- **Core Feature Groups**: 14
|
||||
- **Total Individual Capabilities**: ~100+
|
||||
- **Total Individual Capabilities**: ~110+
|
||||
- **Storage Systems**: 2 (localStorage for snippets, IndexedDB for datasets)
|
||||
- **UI Panels**: 3 main + 1 modal
|
||||
- **UI Panels**: 3 main + 2 modals (Dataset Manager, Chart Builder)
|
||||
- **Auto-save Points**: 3 (draft spec, name, comment)
|
||||
- **Data Formats**: 4 (JSON, CSV, TSV, TopoJSON)
|
||||
- **Chart Builder Mark Types**: 5 (Bar, Line, Point, Area, Circle)
|
||||
- **Chart Builder Encoding Channels**: 4 (X, Y, Color, Size)
|
||||
- **Chart Builder Data Types**: 4 (Quantitative, Ordinal, Nominal, Temporal)
|
||||
- **Data Sources**: 2 (inline, URL)
|
||||
- **Type Detection**: 4 types (number, date, boolean, text)
|
||||
- **Import/Export**: Snippets + Datasets
|
||||
@@ -274,13 +289,14 @@ src/
|
||||
│ ├── config.js # Global variables, settings, sample data
|
||||
│ ├── snippet-manager.js # Snippet CRUD, storage, search, sort, extract (1,100+ lines)
|
||||
│ ├── dataset-manager.js # Dataset CRUD, IndexedDB, preview, types (1,200+ lines)
|
||||
│ ├── chart-builder.js # Visual chart builder for datasets (457 lines)
|
||||
│ ├── panel-manager.js # Layout resizing, toggling, persistence (200 lines)
|
||||
│ ├── editor.js # Monaco setup, Vega rendering, dataset resolution (150 lines)
|
||||
│ └── app.js # Event handlers, initialization (250+ lines)
|
||||
└── styles.css # Retro Windows 2000 aesthetic (280+ lines)
|
||||
└── styles.css # Retro Windows 2000 aesthetic (330+ lines)
|
||||
```
|
||||
|
||||
**Total JS Lines**: ~2,900+ lines (excluding comments and blank lines)
|
||||
**Total JS Lines**: ~3,350+ lines (excluding comments and blank lines)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user