From 305badf48305248a8d7ff1d149887c78649a3121 Mon Sep 17 00:00:00 2001 From: Oleh Omelchenko Date: Mon, 13 Oct 2025 11:04:46 +0300 Subject: [PATCH] docs update --- CLAUDE.md | 86 +++++++++++++++++++++++++++++++++++++++--------- docs/dev-plan.md | 54 +++++++++++++++++++++--------- 2 files changed, 109 insertions(+), 31 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 27ed61e..d76d405 100644 --- a/CLAUDE.md +++ b/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 \ No newline at end of file +``` +/ +├── 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 \ No newline at end of file diff --git a/docs/dev-plan.md b/docs/dev-plan.md index 126f105..fa56243 100644 --- a/docs/dev-plan.md +++ b/docs/dev-plan.md @@ -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 -- 🎯 Ready for draft/published workflow implementation \ No newline at end of file +- ✅ 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 \ No newline at end of file