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: update documentation

Browse Source
This commit is contained in:
Oleh Omelchenko
2025-11-17 14:14:35 +02:00
parent 849e7844fe
commit a3d4fed842
5 changed files with 97 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
CHANGELOG.md
View File

@@ -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/). 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 ## [1.0.0] - 2025-10-15

2
README.md
View File

@@ -4,6 +4,7 @@ A lightweight, browser-based snippet manager for Vega-Lite visualizations. Organ
## Key Features ## 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 - **Draft/published workflow**: Experiment safely without losing your working version
- **Dataset library**: Store and reuse datasets across snippets (JSON, CSV, TSV, TopoJSON) - **Dataset library**: Store and reuse datasets across snippets (JSON, CSV, TSV, TopoJSON)
- **Import/export**: Back up your work or move it between browsers - **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 - `app.js` – Application initialization and event handlers
- `snippet-manager.js` – Snippet CRUD operations - `snippet-manager.js` – Snippet CRUD operations
- `dataset-manager.js` – Dataset management with IndexedDB - `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 - `user-settings.js` – Settings persistence and validation
- `editor.js` – Monaco Editor and Vega-Lite rendering - `editor.js` – Monaco Editor and Vega-Lite rendering
- `panel-manager.js` – Resizable layout and persistence - `panel-manager.js` – Resizable layout and persistence

13
project-docs/architecture.md
View File

@@ -158,6 +158,7 @@ web/
│ │ ├── config.js # Global variables, settings API, utilities │ │ ├── config.js # Global variables, settings API, utilities
│ │ ├── snippet-manager.js # Snippet CRUD, storage, search, sort │ │ ├── snippet-manager.js # Snippet CRUD, storage, search, sort
│ │ ├── dataset-manager.js # Dataset CRUD, IndexedDB operations │ │ ├── dataset-manager.js # Dataset CRUD, IndexedDB operations
│ │ ├── chart-builder.js # Visual chart builder for creating specs
│ │ ├── panel-manager.js # Layout resizing and persistence │ │ ├── panel-manager.js # Layout resizing and persistence
│ │ ├── editor.js # Monaco and Vega library integration │ │ ├── editor.js # Monaco and Vega library integration
│ │ ├── user-settings.js # Settings management │ │ ├── user-settings.js # Settings management
@@ -194,7 +195,17 @@ web/
- Table preview rendering with type detection - Table preview rendering with type detection
- Import/export with format conversion - Import/export with format conversion
- Extract inline data to dataset - 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) **panel-manager.js** (~200 lines)
- Drag-to-resize implementation - Drag-to-resize implementation

141
project-docs/chart-builder-implementation.md
View File

@@ -278,100 +278,59 @@ The following should be tested manually:
### Event Flow ### Event Flow
``` ```
User clicks "Build Chart" User clicks "Build Chart" → openChartBuilder(datasetId)
→ openChartBuilder(datasetId) → Fetch dataset, populate dropdowns, auto-select defaults
→ Fetch dataset from IndexedDB → Show modal, update URL to #datasets/dataset-123/build
→ 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) User changes config → Update state → Debounced preview update
→ Event handler captures change
→ Update internal spec state
→ Validate configuration
→ Enable/disable "Create Snippet" button
→ Debounced: updateChartBuilderPreview()
User clicks "Create Snippet" User clicks "Create Snippet" → Validate → Generate spec
→ validateChartConfig() → Create snippet → Close modals → Open in editor
→ generateVegaLiteSpec()
→ Create snippet via SnippetStorage
→ Close builder
→ Close dataset modal
→ Open snippet in editor
→ Update URL to #snippet-123
``` ```
### 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 - `DatasetStorage.getDataset(id)` - Fetch dataset
- `SnippetStorage.saveSnippet(snippet)` - Save new snippet - `resolveDatasetReferences(spec)` - Resolve data.name references
- `createSnippet(spec, name)` - Generate snippet object - `SnippetStorage.saveSnippet()` - Save new snippet
- `generateSnippetId()` / `generateSnippetName()` - Auto-generate IDs/names
- `selectSnippet(id)` - Open snippet in editor - `selectSnippet(id)` - Open snippet in editor
- `URLState.update()` - Update URL state - `URLState.update()` - Update URL state
- `showToast()` - User notifications
**To be refactored:** - `getSetting()` - Access user settings (debounce)
- `renderVegaSpec(containerId, spec, options)` - Generic Vega renderer
**To be created:**
- `openChartBuilder(datasetId)`
- `closeChartBuilder()`
- `generateVegaLiteSpec()`
- `validateChartConfig()`
- etc. (see Step 2 above)
## Design Decisions ## Design Decisions
### Why Vega-Lite Compatible Schema? **Why Vega-Lite Compatible Schema?** - Direct mapping to output spec, no translation layer, easy to debug.
- 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? **Why Type Toggle Buttons?** - Matches existing UI (Draft/Published buttons), single-click interaction, visual clarity.
- 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"? **Why Separate "Build Chart" from "New Snippet"?** - Different workflows (guided vs manual), both valid entry points.
- 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? **Why No Aggregations in v1?** - Keeps UI simple, most common use case is direct mapping, users can add in editor.
- 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)? **Why Center Preview?** - Respects dimensions, consistent with main preview, allows scrolling for large charts.
- Respects user's width/height choices
- Consistent with main preview panel behavior
- Avoids confusion about final size
- Allows scrolling for large charts
## File Structure ## File Structure
``` **Files Modified:**
/src - `src/js/chart-builder.js` - NEW (~457 lines)
/js - `src/js/config.js` - URL state support for `/build` action
- chart-builder.js (NEW - ~400 lines) - `src/js/app.js` - URL handler for chart builder
- editor.js (MODIFIED - refactor ~50 lines) - `src/styles.css` - Chart builder styles (lines 491-547)
- dataset-manager.js (MODIFIED - add button handler ~20 lines) - `index.html` - Chart builder modal HTML + "Build Chart" button
- 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 ## Next Steps
@@ -382,28 +341,22 @@ User clicks "Create Snippet"
5. **Test with real datasets** - READY FOR MANUAL TESTING 5. **Test with real datasets** - READY FOR MANUAL TESTING
6. **Document in CHANGELOG.md** - TODO after testing 6. **Document in CHANGELOG.md** - TODO after testing
## Notes & Considerations ## Notes
- **Performance**: Preview rendering is debounced (use existing render debounce setting) - Performance: Debounced preview using existing render settings
- **Error Handling**: Invalid specs show error overlay in preview (reuse existing pattern) - Error Handling: Shows inline error messages with helpful text
- **Accessibility**: All form controls have labels and proper IDs - Keyboard Support: ESC closes modal, Tab navigation
- **Keyboard Support**: Escape closes modal, Tab navigation works - URL State: Browser back/forward navigation integrated
- **URL State**: Supports browser back/forward navigation - Dark Theme: Full support for experimental theme
- **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) ## Future Enhancements
- Aggregation support (count, sum, mean, etc.) Potential improvements for future versions:
- Transform support (filter, calculate) - Aggregations (count, sum, mean), transforms (filter, calculate)
- Faceting/composition (layer, concat, vconcat, hconcat) - Layering, faceting, and composition
- Advanced mark properties (opacity, stroke, strokeWidth) - Advanced mark properties, axis/legend customization
- Axis/legend customization (title, format, scale) - Custom color schemes, saved templates
- Custom color schemes
- Saved chart templates
- Chart recommendations based on data types - Chart recommendations based on data types
- Export chart as PNG/SVG directly from builder
--- ---

26
project-docs/features-list.md
View File

@@ -243,23 +243,38 @@
- Button in dataset details to create snippet - Button in dataset details to create snippet
- Auto-generated minimal Vega-Lite spec with dataset reference - Auto-generated minimal Vega-Lite spec with dataset reference
- Pre-populated comment and datasetRefs - 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**: - **UI Enhancements**:
- Larger modal (95% width, max 1200px, 85% height) - Larger modal (95% width, max 1200px, 85% height)
- Actions moved to top of dataset details - Actions moved to top of dataset details
- Dataset list with usage badges - 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** ## 📊 **Feature Statistics**
- **Core Feature Groups**: 14 - **Core Feature Groups**: 14
- **Total Individual Capabilities**: ~100+ - **Total Individual Capabilities**: ~110+
- **Storage Systems**: 2 (localStorage for snippets, IndexedDB for datasets) - **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) - **Auto-save Points**: 3 (draft spec, name, comment)
- **Data Formats**: 4 (JSON, CSV, TSV, TopoJSON) - **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) - **Data Sources**: 2 (inline, URL)
- **Type Detection**: 4 types (number, date, boolean, text) - **Type Detection**: 4 types (number, date, boolean, text)
- **Import/Export**: Snippets + Datasets - **Import/Export**: Snippets + Datasets
@@ -274,13 +289,14 @@ src/
│ ├── config.js # Global variables, settings, sample data │ ├── config.js # Global variables, settings, sample data
│ ├── snippet-manager.js # Snippet CRUD, storage, search, sort, extract (1,100+ lines) │ ├── snippet-manager.js # Snippet CRUD, storage, search, sort, extract (1,100+ lines)
│ ├── dataset-manager.js # Dataset CRUD, IndexedDB, preview, types (1,200+ 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) │ ├── panel-manager.js # Layout resizing, toggling, persistence (200 lines)
│ ├── editor.js # Monaco setup, Vega rendering, dataset resolution (150 lines) │ ├── editor.js # Monaco setup, Vega rendering, dataset resolution (150 lines)
│ └── app.js # Event handlers, initialization (250+ 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)
--- ---