mirror of
https://github.com/olehomelchenko/astrolabe-nvc.git
synced 2025-12-21 21:22:23 +00:00
docs update
This commit is contained in:
86
CLAUDE.md
86
CLAUDE.md
@@ -12,6 +12,7 @@ Astrolabe is a lightweight, browser-based snippet manager for Vega-Lite visualiz
|
||||
- **Storage**: localStorage (initial), planned migration to IndexedDB for scale
|
||||
- **Key Dependencies**: Monaco Editor and Vega-Embed loaded via CDN
|
||||
- **Structure**: Three-panel resizable interface (snippet library, editor, preview)
|
||||
- **Styling**: Retro Windows 2000 aesthetic with square edges and classic colors
|
||||
|
||||
## Development Commands
|
||||
|
||||
@@ -20,32 +21,87 @@ This project uses no build tools or package managers. Development is done by:
|
||||
- Using browser dev tools for debugging
|
||||
- No npm, yarn, or build commands needed
|
||||
|
||||
## Current Features
|
||||
|
||||
### ✅ **Core Interface** (Phases 1-4)
|
||||
- **Three-panel layout**: Resizable snippet library, Monaco editor, live preview
|
||||
- **Panel controls**: Toggle buttons (📄 ✏️ 👁️) for show/hide with proportional expansion
|
||||
- **Resize handles**: Drag to adjust panel widths with memory system
|
||||
- **Monaco Editor**: Full JSON schema validation for Vega-Lite with autocomplete
|
||||
- **Live preview**: Debounced Vega-Lite rendering with error handling
|
||||
|
||||
### ✅ **Data Management** (Phases 5-6)
|
||||
- **localStorage persistence**: Robust snippet storage with error handling
|
||||
- **Auto-save system**: Debounced draft saving for both specs and metadata
|
||||
- **CRUD operations**: Create, read, update, delete with visual feedback
|
||||
- **Ghost card interface**: "Create New Snippet" card at top of list
|
||||
- **Smart timestamps**: Auto-generated names using ISO datetime format
|
||||
|
||||
### ✅ **Advanced Organization**
|
||||
- **Multi-field sorting**: Sort by Modified/Created/Name with ascending/descending toggle
|
||||
- **Visual sort indicators**: Arrow icons (⬇⬆) showing current sort direction
|
||||
- **Comprehensive search**: Filter by name, comment, and spec content with real-time results
|
||||
- **Search integration**: Works seamlessly with sorting and maintains selection
|
||||
- **Settings persistence**: Sort preferences and UI state saved to localStorage
|
||||
|
||||
### ✅ **User Experience Enhancements**
|
||||
- **Metadata panel**: Shaded section with inline name editing, comments, and timestamp info
|
||||
- **Operation buttons**: Duplicate and Delete buttons in metadata panel
|
||||
- **Smart state management**: Maintains selection during operations, clears when filtered out
|
||||
- **Performance optimizations**: Prevents auto-save/render timeouts during snippet switching
|
||||
- **Intuitive interactions**: Right-click removed in favor of accessible button controls
|
||||
|
||||
## Core Data Model
|
||||
|
||||
The application centers around two main entities:
|
||||
- **Snippets**: `{id, name, created, modified, spec, draftSpec, comment, tags[], datasetRefs[], published}`
|
||||
- **Datasets**: `{id, name, created, modified, data, format, size}`
|
||||
**Snippets**: `{id, name, created, modified, spec, draftSpec, comment, tags[], datasetRefs[], meta}`
|
||||
**Settings**: `{sortBy, sortOrder, panelWidths[], panelVisibility[], autoSaveDelay, meta}`
|
||||
|
||||
## Development Phases
|
||||
|
||||
The project follows a structured 14-phase development plan (see docs/dev-plan.md):
|
||||
- Phase 0: Storage architecture design
|
||||
- Phase 1-4: Basic UI layout and editor integration
|
||||
- Phase 5-7: Data persistence and draft/publish workflow
|
||||
- Phase 8-12: Polish and advanced features
|
||||
- Phase 13-14: Future enhancements (search, cloud sync)
|
||||
**Current Status**: Enhanced Phase 6 - Advanced Snippet Management
|
||||
|
||||
**Current Status**: Phase 0 - Storage Architecture Design
|
||||
**Completed Phases**:
|
||||
- ✅ **Phase 0**: Storage Architecture Design
|
||||
- ✅ **Phase 1**: Static HTML Structure with retro styling
|
||||
- ✅ **Phase 2**: Resizable Panels with memory system
|
||||
- ✅ **Phase 3**: Monaco Editor Integration with Vega-Lite schema
|
||||
- ✅ **Phase 4**: Vega-Lite Rendering with live preview
|
||||
- ✅ **Phase 5**: Data Model + LocalStorage with comprehensive snippet storage
|
||||
- ✅ **Phase 6+**: Enhanced CRUD with sorting, searching, and advanced UX
|
||||
|
||||
**Next Phase**: Phase 7 - Draft/Published Workflow
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
- **Lean**: No frameworks, no build step, minimal dependencies
|
||||
- **Local-first**: All data stored in browser initially
|
||||
- **Local-first**: All data stored in browser with robust error handling
|
||||
- **Developer-friendly**: Full JSON schema support with Monaco Editor
|
||||
- **Safe experimentation**: Draft/published workflow prevents data loss
|
||||
- **Safe experimentation**: Auto-save drafts with future draft/publish workflow
|
||||
- **Performance-focused**: Debounced operations and smart state management
|
||||
- **Retro aesthetic**: Consistent Windows 2000 styling throughout
|
||||
|
||||
## File Structure
|
||||
|
||||
Currently minimal:
|
||||
- `docs/dev-plan.md` - Complete development roadmap
|
||||
- Future: `index.html`, CSS, and JavaScript files in root
|
||||
```
|
||||
/
|
||||
├── index.html # Main application entry point & initialization
|
||||
├── src/
|
||||
│ ├── styles.css # Retro Windows 2000 styling
|
||||
│ └── js/ # Modular JavaScript organization
|
||||
│ ├── config.js # Global variables, settings & sample data
|
||||
│ ├── snippet-manager.js # Snippet storage, CRUD & localStorage wrapper
|
||||
│ ├── panel-manager.js # Panel resize, toggle & memory system
|
||||
│ ├── editor.js # Monaco Editor & Vega-Lite rendering
|
||||
│ └── app.js # Event handlers & coordination
|
||||
└── docs/
|
||||
├── dev-plan.md # Complete development roadmap
|
||||
└── storage-examples.md # Data model specifications
|
||||
```
|
||||
|
||||
## Technical Notes
|
||||
|
||||
- **AMD Conflicts**: Resolved between Monaco Editor and Vega libraries using UMD builds
|
||||
- **State Management**: Global flags prevent unwanted timeouts during programmatic updates
|
||||
- **Memory System**: Panels remember preferred sizes across hide/show cycles
|
||||
- **Search Performance**: 300ms debounced input with smart result caching
|
||||
- **Auto-save Logic**: 1-second debounce for user edits, immediate for snippet switching
|
||||
@@ -167,29 +167,41 @@ Astrolabe is a focused tool for managing, editing, and previewing Vega-Lite visu
|
||||
|
||||
---
|
||||
|
||||
### **Phase 6: Snippet Selection & Basic CRUD** ✅ **COMPLETE**
|
||||
**Goal**: Core snippet management
|
||||
### **Phase 6: Snippet Selection & Basic CRUD** ✅ **COMPLETE + ENHANCED**
|
||||
**Goal**: Core snippet management with advanced organization
|
||||
|
||||
- [x] Click snippet in list → load into editor + render
|
||||
- [x] Highlight selected snippet in list
|
||||
- [x] **Create**: "New Snippet" button → generates datetime name
|
||||
- [x] **Create**: Ghost card interface → generates datetime name
|
||||
- [x] **Duplicate**: Duplicate button creates copy with timestamp suffix
|
||||
- [x] **Delete**: Delete button per snippet (with confirmation)
|
||||
- [x] **Rename**: Inline or modal rename functionality
|
||||
- [x] **Rename**: Inline editing in metadata panel with auto-save
|
||||
- [x] Auto-save draft on editor change (debounced)
|
||||
- [x] Add comment/meta text field (below snippet list or in sidebar)
|
||||
- [x] Add comment/meta text field with creation/modified timestamps
|
||||
|
||||
**Deliverable**: Complete basic CRUD with auto-saving drafts
|
||||
**Enhanced Features Added**:
|
||||
- [x] **Multi-field sorting**: Sort by Modified/Created/Name with visual indicators
|
||||
- [x] **Ascending/Descending toggle**: Click same button to reverse sort with ⬇⬆ arrows
|
||||
- [x] **Comprehensive search**: Real-time filtering by name, comment, and spec content
|
||||
- [x] **Search integration**: Works seamlessly with sorting, maintains selection state
|
||||
- [x] **Ghost card creation**: Intuitive "Create New Snippet" card at top of list
|
||||
- [x] **Enhanced metadata panel**: Shaded section with inline editing and timestamp display
|
||||
- [x] **Settings persistence**: Sort preferences and search state saved to localStorage
|
||||
- [x] **Performance optimizations**: Prevents unwanted timeouts during snippet switching
|
||||
- [x] **Smart state management**: Maintains selection during operations, clears when filtered
|
||||
|
||||
**Deliverable**: Complete snippet management system with advanced organization
|
||||
|
||||
**Key Achievements**:
|
||||
- Implemented comprehensive snippet selection with visual highlighting
|
||||
- Connected "New" header button to `createNewSnippet()` function for easy snippet creation
|
||||
- Added right-click context menu for snippet operations (Rename, Duplicate, Delete)
|
||||
- Implemented auto-save functionality for both spec changes and comment field edits
|
||||
- Added comment field that appears when a snippet is selected and auto-saves changes
|
||||
- Created intuitive UX with proper state management (hiding/showing comment field)
|
||||
- Added confirmation dialogs for destructive operations like delete
|
||||
- Maintained consistent retro styling for all new UI elements
|
||||
- **Intuitive Interface**: Ghost card replaces header button for snippet creation
|
||||
- **Powerful Organization**: Multi-criteria sorting with direction toggle and visual feedback
|
||||
- **Comprehensive Search**: Searches across all snippet content with 300ms debounced input
|
||||
- **Enhanced Metadata**: Shaded panel with inline name editing, comments, and timestamp info
|
||||
- **Smart Operations**: Duplicate/Delete buttons in metadata panel with proper state management
|
||||
- **Performance**: Optimized auto-save and rendering to prevent delays during navigation
|
||||
- **Settings Persistence**: User preferences for sorting and UI state saved across sessions
|
||||
- **Seamless Integration**: Search and sort work together while preserving selection state
|
||||
- **User Experience**: Removed context menus in favor of accessible, discoverable controls
|
||||
|
||||
---
|
||||
|
||||
@@ -352,8 +364,18 @@ Astrolabe is a focused tool for managing, editing, and previewing Vega-Lite visu
|
||||
**Status**: Ready to begin implementation
|
||||
|
||||
**Completion Status**:
|
||||
- ✅ Phases 0, 1, 2, 3, 4, 5, 6 complete
|
||||
- ✅ Phases 0, 1, 2, 3, 4, 5, 6+ complete with major enhancements
|
||||
- ✅ Code organization and cleanup complete
|
||||
- ✅ Snippet storage infrastructure complete
|
||||
- ✅ Complete CRUD operations with auto-save functionality
|
||||
- ✅ Advanced snippet organization with sorting and search
|
||||
- ✅ Enhanced user interface with metadata panel and performance optimizations
|
||||
- ✅ Settings persistence and smart state management
|
||||
- 🎯 Ready for draft/published workflow implementation
|
||||
|
||||
**Recent Major Enhancements Beyond Original Plan**:
|
||||
- **Advanced Sorting**: Multi-field sorting with ascending/descending toggle and visual indicators
|
||||
- **Comprehensive Search**: Real-time filtering across all snippet content with seamless integration
|
||||
- **Enhanced Interface**: Ghost card creation, shaded metadata panel, inline editing
|
||||
- **Performance Optimizations**: Smart timeout prevention, debounced operations
|
||||
- **Settings System**: Persistent user preferences for sorting and UI state
|
||||
Reference in New Issue
Block a user