From a3d4fed842ea11aac34b073c2e0f515d1c19520b Mon Sep 17 00:00:00 2001 From: Oleh Omelchenko Date: Mon, 17 Nov 2025 14:14:35 +0200 Subject: [PATCH] feat: update documentation --- CHANGELOG.md | 15 ++ README.md | 2 + project-docs/architecture.md | 13 +- project-docs/chart-builder-implementation.md | 141 +++++++------------ project-docs/features-list.md | 26 +++- 5 files changed, 97 insertions(+), 100 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 90a888b..502f470 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 7eba34d..78d62d5 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/project-docs/architecture.md b/project-docs/architecture.md index 66fc8f1..b9d2eba 100644 --- a/project-docs/architecture.md +++ b/project-docs/architecture.md @@ -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 diff --git a/project-docs/chart-builder-implementation.md b/project-docs/chart-builder-implementation.md index 6392a2b..3bd9100 100644 --- a/project-docs/chart-builder-implementation.md +++ b/project-docs/chart-builder-implementation.md @@ -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 --- diff --git a/project-docs/features-list.md b/project-docs/features-list.md index 00e8374..df7a85b 100644 --- a/project-docs/features-list.md +++ b/project-docs/features-list.md @@ -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) ---