Skip to content

Phase 2 Complete - Core Infrastructure

Phase 2 of the Apitomy OpenAPI Editor project has been successfully completed!

What Was Accomplished

1. Zustand Stores Created

Document Store (src/stores/documentStore.ts) - Manages OpenAPI document state - Tracks loading state, errors, and dirty flag - Actions: loadDocument, updateDocument, markDirty, markClean, setError, reset

Selection Store (src/stores/selectionStore.ts) - Tracks currently selected node in the document - Stores selected path, node, and type - Actions: selectNode, clearSelection, setHighlight, reset

Command Store (src/stores/commandStore.ts) - Manages command history for undo/redo - Maintains undo and redo stacks with configurable max size (100) - Actions: addCommand, popUndo, popRedo, canUndo, canRedo, reset

UI Store (src/stores/uiStore.ts) - Manages UI state (modals, drawers, panels, theme) - Actions: openModal, closeModal, toggleProblemsDrawer, toggleMasterPanel, setTheme

2. Service Layer Implemented

DocumentService (src/services/DocumentService.ts) - Load and parse OpenAPI documents using @apitomy/data-models - Serialize documents to JSON/object - Validate documents and map validation problems - Integrates with Zustand document store

CommandService (src/services/CommandService.ts) - Execute ICommand instances on the document - Full undo/redo support - Command history tracking - Integrates with both command and document stores

SelectionService (src/services/SelectionService.ts) - Select nodes by path or direct reference - Determine node types (path, operation, schema, etc.) - Support for highlighting selections - Simplified implementation (full node resolution to be added later)

ValidationService (src/services/ValidationService.ts) - Validate OpenAPI documents - Cache validation problems - Filter problems by path - Count errors, warnings, and info messages by severity

3. React Context and Hooks

EditorContext (src/services/EditorContext.tsx) - React Context provider for all editor services - Creates service instances with proper lifecycle - Prevents prop drilling throughout component tree

Custom Hooks: - useDocument - Access document state and operations - useCommand - Execute commands, undo/redo - useSelection - Manage node selection - useUI - Control UI state (modals, drawers, theme)

4. Updated Editor Component

OpenAPIEditor (main component) - Wraps content with EditorProvider - Passes props through to OpenAPIEditorContent

OpenAPIEditorContent (implementation) - PatternFly 6 layout with Masthead and Page components - Displays document title in masthead - Undo/redo buttons with proper enabled/disabled states - Loads initial content on mount - Calls onChange callback when document changes - Shows document info (version, title, OpenAPI version)

5. TypeScript Models

Created comprehensive type definitions: - DocumentTypes.ts - Document state and validation problems - SelectionTypes.ts - Selection state and events - CommandTypes.ts - Command history entries - UITypes.ts - UI state and modal types

6. Integration with @apitomy/data-models v2.2.6

Successfully integrated with the latest data-models library: - Using ICommand interface instead of Command class - Using Library.readDocument() for parsing - Using Library.writeNode() for serialization - Using Library.validate() for validation - Proper handling of NodePath API changes

Key Technical Decisions

1. Zustand for State Management

  • Chose Zustand over Redux/MobX for simplicity and performance
  • Stores are independent but can be accessed from services
  • Easy to test and reason about

2. Service Layer Pattern

  • Services encapsulate business logic
  • Services interact with Zustand stores
  • React components use hooks to access services
  • Clean separation of concerns

3. Command Pattern

  • All document mutations go through commands
  • Enables undo/redo naturally
  • Commands are serializable (important for future collaboration)
  • Consistent with data-models library design

4. Context + Hooks

  • Context provides service instances
  • Hooks provide reactive state access
  • Best of both worlds: dependency injection + reactivity

Verified Functionality

✅ Project builds successfully ✅ Document can be loaded and parsed ✅ Document state is reactive ✅ Services are accessible via hooks ✅ Undo/redo UI buttons respond to state ✅ PatternFly components render correctly ✅ TypeScript strict mode passes ✅ No console errors or warnings

What's Working

  1. Document Loading: Can load OpenAPI documents (JSON object or string)
  2. Document Parsing: Uses apitomy-data-models to parse into Document object
  3. State Management: Reactive state updates via Zustand
  4. Service Access: Services available via React Context and hooks
  5. UI Layout: PatternFly masthead with title and toolbar
  6. Undo/Redo Buttons: Functional (though no commands exist yet to undo)
  7. onChange Callback: Fires when document changes

Known Limitations / TODO

  1. Node Selection: Simplified implementation - full NodePath resolution not yet implemented
  2. Validation: Validation service exists but not yet integrated into UI
  3. No Forms Yet: Phase 3 will add master/detail layout and editing forms
  4. No Commands Yet: Need to create custom commands for editing operations

File Structure Added

src/
├── components/editor/
│   ├── OpenAPIEditor.tsx (updated)
│   └── OpenAPIEditorContent.tsx (new)
├── hooks/
│   ├── useCommand.ts
│   ├── useDocument.ts
│   ├── useSelection.ts
│   └── useUI.ts
├── models/
│   ├── CommandTypes.ts
│   ├── DocumentTypes.ts
│   ├── EditorProps.ts
│   ├── SelectionTypes.ts
│   └── UITypes.ts
├── services/
│   ├── CommandService.ts
│   ├── DocumentService.ts
│   ├── EditorContext.tsx
│   ├── SelectionService.ts
│   └── ValidationService.ts
└── stores/
    ├── commandStore.ts
    ├── documentStore.ts
    ├── selectionStore.ts
    └── uiStore.ts

Test Application

A test application was created in test-app/ directory to manually test the editor component during development.

Next Steps - Phase 3: Basic Layout & Navigation

Phase 3 will focus on building the master/detail UI:

  1. Master/Detail Layout: Split view with navigation tree and content panel
  2. Navigation Tree: Display paths, schemas, responses
  3. Title Bar Enhancements: Validation status, save/export actions
  4. Basic Search/Filter: Filter items in navigation

Status: ✅ Phase 2 Complete Ready For: Phase 3 - Basic Layout & Navigation Commit: ea1f0f6