@dtducas/wh-forge-viewer 1.0.8-beta → 1.0.9-beta0

package/README.md

@@ -1,331 +1,415 @@
 # wh-forge-viewer
 
-A professional Autodesk Forge Viewer component for React with advanced PDF support, intelligent navigation, and production-ready architecture.
+A professional Autodesk Forge Viewer component for React with advanced PDF support, comprehensive markup tools, and real-time collaboration capabilities.
 
 ## Features
 
-### Core Features
-- ✅ **Custom Toolbar** - Pre-configured toolbar with Pan, Document Browser, Download, and Pagination controls
-- ✅ **Enhanced PDF Support** - Optimized for viewing PDF documents with intelligent page navigation
-- ✅ **Smart Document Browser** - Auto-opens with adaptive panel sizing (single/multi-page)
-- ✅ **3D/2D Models** - Full support for Autodesk Forge 3D and 2D models (DWF, DWFX)
-- ✅ **React Integration** - Easy-to-use React component with hooks support
-
-### Advanced Navigation
-- 🚀 **No-Refresh Navigation** - Document Browser panel doesn't refresh when using pagination buttons
-- 🚀 **Smart Thumbnail Selection** - Auto-select and scroll to current thumbnail
-- 🚀 **Persistent State** - State survives extension unload/reload cycles
-- 🚀 **Synchronized Button States** - Document Browser button always reflects actual panel state
-- 🚀 **Smooth Scrolling** - Auto-scroll thumbnails to center in viewport
-
-### Architecture & Quality
-- 🏗️ **SOLID Architecture** - Manager pattern with clear separation of concerns
-- 🏗️ **Type Safety** - Full TypeScript type definitions included
-- 🏗️ **Dependency Injection** - Clean, testable, and maintainable code
-- 🏗️ **Self-Healing Toolbar** - Automatic recovery mechanism ensures UI persistence
-- 🏗️ **Production Ready** - Clean code, no debug logs, optimized performance
+### Core Viewer
+
+- **Custom Toolbar** - Pan, Document Browser, Download, and Pagination controls
+- **Enhanced PDF Support** - Optimized for viewing PDF documents with intelligent page navigation
+- **Smart Document Browser** - Auto-opens with adaptive panel sizing
+- **3D/2D Models** - Full support for DWF, DWFX formats
+- **React Integration** - Easy-to-use React component with hooks support
+
+### Markup Tools
+
+- **12 Markup Tools** - Arrow, Rectangle, Circle, Cloud, Text, Freehand, Line, Polyline, Polycloud, Callout, Image/Stamp
+- **SelectTool with Multi-Select** - Drag rectangle to select multiple markups
+- **Property Panel** - Excalidraw-inspired UI for editing markup properties
+- **Undo/Redo** - Full undo/redo support for all operations
+- **Custom Stamps** - Insert images as stamps with drag-drop support
+
+### Collaboration
+
+- **Real-Time Sync** - Subscribe to markup changes for WebSocket broadcasting
+- **User Presence** - Track and display remote user cursors
+- **Persistence API** - Save/load markups with JSON or SVG formats
+- **Page Change Events** - Handle markup data during page navigation
+
+### Architecture
+
+- **SOLID Principles** - Manager pattern with clear separation of concerns
+- **Type Safety** - Full TypeScript definitions included
+- **Event-Driven** - Decoupled communication via EventBus
+- **Extensible** - Factory pattern for adding custom tools
 
 ## Installation
 
 ```bash
-npm install wh-forge-viewer
+npm install @dtducas/wh-forge-viewer
 ```
 
-## Usage
+## Quick Start
 
-```jsx
-import { ViewerForgePDF } from 'wh-forge-viewer';
+### Basic Viewer
 
-function MyApp() {
-  const [viewer, setViewer] = useState(null);
+```jsx
+import { ViewerForgePDF } from '@dtducas/wh-forge-viewer';
 
+function App() {
   return (
     <ViewerForgePDF
       filePath='https://example.com/document.pdf'
       fileExt='pdf'
-      setViewer={setViewer}
+      onViewerReady={(viewer) => console.log('Ready:', viewer)}
     />
   );
 }
 ```
 
-## Props
+### With Markup Tools
 
-| Prop        | Type     | Required | Description                           |
-| ----------- | -------- | -------- | ------------------------------------- |
-| `filePath`  | string   | Yes      | URL to the document to load           |
-| `fileExt`   | string   | Yes      | File extension (pdf, dwf, dwfx, etc.) |
-| `setViewer` | function | No       | Callback to receive viewer instance   |
+```jsx
+import {
+  ViewerForgePDF,
+  DrawingManager,
+  MarkupToolbar,
+  PropertyPanel,
+  EventBus,
+} from '@dtducas/wh-forge-viewer';
+
+function MarkupViewer() {
+  const [viewer, setViewer] = useState(null);
+  const [drawingManager, setDrawingManager] = useState(null);
+  const [activeTool, setActiveTool] = useState(null);
+  const [propertyConfig, setPropertyConfig] = useState(null);
+  const [propertyValues, setPropertyValues] = useState({});
 
-## Custom Toolbar
+  const eventBus = EventBus.getInstance();
 
-The viewer includes a production-ready custom toolbar with two control groups:
+  useEffect(() => {
+    if (!viewer) return;
 
-### Tools Group
+    const manager = new DrawingManager(viewer, eventBus, {
+      autoEnterEditMode: true,
+      defaultTool: 'arrow',
+    });
 
-- **Pan Tool** - Enable pan navigation mode
-  - Auto-activates on viewer load
-  - Synced with Forge Viewer navigation state
-  
-- **Document Browser** - Toggle document tree/thumbnail view
-  - Auto-opens for all documents (single/multi-page)
-  - Positioned on right side with custom styling
-  - Default tab: Thumbnails view
-  - Adaptive panel height based on content
-  - State persists across page navigation
-  
-- **Download** - Download the current document
-  - One-click file download
-  - Preserves original filename
+    setDrawingManager(manager);
 
-### Pagination Group
+    return () => manager.destroy();
+  }, [viewer]);
 
-- **Previous Page** ◀ - Navigate to previous page
-- **Page Counter** - Display "current / total" pages (e.g., "3 / 9")
-- **Next Page** ▶ - Navigate to next page
+  const handleToolChange = (tool) => {
+    drawingManager?.setActiveTool(tool);
+    setActiveTool(tool);
+    setPropertyConfig(drawingManager?.getCurrentToolPropertyConfig());
+    setPropertyValues(drawingManager?.getCurrentToolPropertyValues() || {});
+  };
 
-**Smart Navigation:**
-- When Document Browser is open: Uses internal API to prevent panel refresh
-- When Document Browser is closed: Uses standard navigation with panel restore
-- Thumbnail selection and scroll automatically sync with current page
+  return (
+    <div style={{ position: 'relative', width: '100%', height: '100vh' }}>
+      <ViewerForgePDF
+        filePath='/document.pdf'
+        fileExt='pdf'
+        onViewerReady={setViewer}
+      />
+
+      {drawingManager && (
+        <>
+          <MarkupToolbar
+            activeTool={activeTool}
+            onToolChange={handleToolChange}
+            onUndo={() => drawingManager.undo()}
+            onRedo={() => drawingManager.redo()}
+          />
+
+          <PropertyPanel
+            config={propertyConfig}
+            values={propertyValues}
+            onChange={(key, value) => {
+              drawingManager.handlePropertyChange(key, value);
+              setPropertyValues(drawingManager.getCurrentToolPropertyValues());
+            }}
+          />
+        </>
+      )}
+    </div>
+  );
+}
+```
 
-## Requirements
+### Real-Time Collaboration
 
-### Peer Dependencies
-- React ^17.0.0 || ^18.0.0
-- Ant Design ^5.0.0
+```jsx
+import {
+  DrawingManager,
+  EventBus,
+  CursorOverlay,
+} from '@dtducas/wh-forge-viewer';
 
-### Browser Support
-- Modern browsers with ES6+ support
-- Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
+function CollaborativeViewer({ socket }) {
+  const [drawingManager, setDrawingManager] = useState(null);
+  const [remoteCursors, setRemoteCursors] = useState(new Map());
 
-### Autodesk Forge Viewer
-- Uses v7.108.0 (loaded from CDN)
-- Pinned version for production stability
+  useEffect(() => {
+    if (!drawingManager) return;
+
+    // Subscribe to local markup changes
+    const unsubscribe = drawingManager.onMarkupChange((delta) => {
+      socket.emit('markup:delta', delta);
+    });
+
+    // Subscribe to local cursor movement
+    const unsubCursor = drawingManager.onLocalCursorMove((position) => {
+      socket.emit('cursor:move', { userId: currentUser.id, position });
+    });
+
+    // Handle remote changes
+    socket.on('markup:delta', (delta) => {
+      drawingManager.applyDelta(delta);
+    });
+
+    // Handle remote cursors
+    socket.on('cursor:move', (cursor) => {
+      drawingManager.updateUserCursor(cursor);
+      setRemoteCursors(new Map(drawingManager.getRemoteCursors()));
+    });
+
+    return () => {
+      unsubscribe();
+      unsubCursor();
+    };
+  }, [drawingManager, socket]);
 
-## Important Notes
+  return (
+    <>
+      {/* ... viewer components ... */}
+      <CursorOverlay cursors={remoteCursors} />
+    </>
+  );
+}
+```
 
-### Viewer Versioning
+### Persistence
 
-This package uses a **specific version** of Autodesk Forge Viewer (v7.108.0) loaded from CDN, instead of wildcards (7.*), to ensure production stability and avoid unexpected breaking changes.
+```javascript
+// Save to localStorage
+const data = drawingManager.getMarkupData();
+localStorage.setItem('markups', JSON.stringify(data));
 
-**Why pinned version?**
-- ✅ Predictable behavior in production
-- ✅ No surprise updates from Autodesk
-- ✅ Tested and verified functionality
-- ✅ Easy to upgrade when ready
+// Load from localStorage
+const saved = JSON.parse(localStorage.getItem('markups'));
+await drawingManager.loadMarkupData(saved, { mode: 'replace' });
 
-📖 See [docs/VERSIONING.md](docs/VERSIONING.md) for version update guide.
+// Save to database (JSON format)
+const jsonData = drawingManager.getMarkupDataAsJson('page-guid-123');
+await db.collection('markups').doc('page-guid-123').set(jsonData);
 
-### Known Behaviors
+// Load from database
+const doc = await db.collection('markups').doc('page-guid-123').get();
+await drawingManager.loadMarkupDataFromJson(doc.data());
+```
 
-**Extension Lifecycle:**
-- Forge Viewer unloads extensions when navigating between pages
-- This package handles this gracefully with GLOBAL_STATE persistence
-- All states (viewables, page index, panel state) are preserved
+### PDF Export with Markup
 
-**Document Browser Panel:**
-- Auto-opens for both single and multi-page documents
-- Panel height adapts to content (compact for 1 page, scrollable for many)
-- Positioned on right side by default
-- Uses Thumbnails tab as default view
+```javascript
+// Export current page with markup as vector overlay
+const result = await drawingManager.exportCurrentPagePDF(filePath, 0);
+if (result.success && result.blob) {
+  const url = URL.createObjectURL(result.blob);
+  window.open(url); // Preview in new tab
+}
 
-## Architecture
+// Multi-page export
+const markupsByPage = [
+  { pageIndex: 0, svgString: savedPage0Svg },
+  { pageIndex: 1, svgString: drawingManager.getMarkupSVG() }, // current page
+];
+await drawingManager.exportAndDownloadPDF(filePath, markupsByPage, {
+  filename: 'annotated-document',
+});
+```
 
-This package follows **SOLID principles** and uses a production-ready modular architecture:
+## Components
 
-### Core Components
+### ViewerForgePDF
 
-**Managers** (Business Logic)
-- `PaginationManager` - Handles page navigation, viewables management, and smart Document Browser API integration
-- `ToolbarManager` - Creates and manages custom toolbar buttons and their states
-- `DocumentBrowserManager` - Controls Document Browser panel visibility, styling, and state persistence
+Main viewer component.
 
-**Services** (Utilities)
-- `EventBus` - Singleton event bus for decoupled communication between managers
-- `FileLoader` - Loads PDF/DWF/DWFX files into viewer with viewables extraction
-- `DownloadService` - Handles file downloads with proper filename extraction
+| Prop               | Type     | Required | Description                     |
+| ------------------ | -------- | -------- | ------------------------------- |
+| `filePath`         | string   | Yes      | URL to the document             |
+| `fileExt`          | string   | Yes      | File extension (pdf, dwf, dwfx) |
+| `onViewerReady`    | function | No       | Callback with viewer instance   |
+| `onDocumentLoaded` | function | No       | Callback with viewables array   |
+| `onError`          | function | No       | Callback for errors             |
 
-**Extension**
-- `ToolbarExtension` - Main extension that orchestrates all managers and services
+### MarkupToolbar
 
-### Key Features
+Floating toolbar for tool selection.
 
-**Global State Persistence**
-- State survives Forge Viewer's extension unload/reload cycles
-- Preserves viewables, current page index, and Document Browser state
-- Seamless navigation without losing context
+| Prop           | Type     | Description           |
+| -------------- | -------- | --------------------- |
+| `activeTool`   | string   | Currently active tool |
+| `onToolChange` | function | Tool change callback  |
+| `onUndo`       | function | Undo callback         |
+| `onRedo`       | function | Redo callback         |
 
-**Smart Navigation**
-- Detects if Document Browser panel is open
-- Uses `_changeModelFn` API when open (no panel refresh)
-- Falls back to `loadDocumentNode` when closed (with state restoration)
-- Automatic thumbnail selection and scroll synchronization
+### PropertyPanel
 
-**Self-Healing Mechanism**
-- Polls every 8ms to detect missing toolbar groups
-- Automatically recreates toolbar if removed by Forge Viewer
-- Syncs button states with actual panel visibility
-- Ensures UI consistency at all times
+Side panel for editing properties.
 
-📖 See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture documentation.
+| Prop       | Type                | Description              |
+| ---------- | ------------------- | ------------------------ |
+| `config`   | IToolPropertyConfig | Property configuration   |
+| `values`   | object              | Current property values  |
+| `onChange` | function            | Property change callback |
+| `onAction` | function            | Action button callback   |
 
-## Advanced Usage
+### CursorOverlay
 
-### Accessing Viewer Instance
+Overlay for displaying remote cursors.
 
-```jsx
-function MyApp() {
-  const [viewer, setViewer] = useState(null);
+| Prop           | Type    | Description                   |
+| -------------- | ------- | ----------------------------- |
+| `cursors`      | Map     | Remote user cursors           |
+| `viewerBounds` | DOMRect | Viewer bounds for positioning |
 
-  useEffect(() => {
-    if (viewer) {
-      // Access viewer API
-      console.log('Viewer loaded:', viewer);
-      
-      // Listen to Forge Viewer events
-      viewer.addEventListener(Autodesk.Viewing.GEOMETRY_LOADED_EVENT, () => {
-        console.log('Geometry loaded');
-      });
-    }
-  }, [viewer]);
+## DrawingManager API
 
-  return (
-    <ViewerForgePDF
-      filePath="/path/to/document.pdf"
-      fileExt="pdf"
-      setViewer={setViewer}
-    />
-  );
-}
+### Edit Mode
+
+```typescript
+await drawingManager.enterEditMode(); // Enter markup mode
+drawingManager.leaveEditMode(); // Exit markup mode
+drawingManager.isEditMode(); // Check if in edit mode
 ```
 
-### Event Bus Integration
+### Tools
 
-The package exposes an EventBus for custom integrations:
+```typescript
+drawingManager.setActiveTool('arrow'); // Set active tool
+drawingManager.getActiveTool(); // Get current tool
+drawingManager.setStrokeStyle('#e03131', 2, 1.0); // Set stroke
+drawingManager.setFillStyle('#228be6', 0.3); // Set fill
+```
 
-```javascript
-import { EventBus } from '@dtducas/wh-forge-viewer';
+**Available Tools:**
+`select`, `arrow`, `rectangle`, `ellipse`, `cloud`, `label`, `freehand`, `line`, `polyline`, `polycloud`, `callout`, `image`
 
-const eventBus = EventBus.getInstance();
+### Markup Operations
 
-// Listen to page changes
-eventBus.on('page:changed', (data) => {
-  console.log('Page changed to:', data.index);
-  console.log('From Document Browser:', data.fromDocBrowser);
-  console.log('From Pagination:', data.fromPagination);
-});
+```typescript
+drawingManager.saveMarkups(); // Save current markups
+drawingManager.loadMarkups(data); // Load markups
+drawingManager.clearMarkups(); // Clear all markups
+drawingManager.exportToSVG(); // Export to SVG string
+drawingManager.undo(); // Undo last action
+drawingManager.redo(); // Redo last undone action
+```
 
-// Listen to Document Browser events
-eventBus.on('docBrowser:opened', () => {
-  console.log('Document Browser opened');
-});
+### Collaborative API
 
-eventBus.on('docBrowser:closed', () => {
-  console.log('Document Browser closed');
-});
-```
+```typescript
+// Get markup data for persistence
+const data = drawingManager.getMarkupData(viewableGUID);
 
-## Performance Optimizations
+// Load markup data
+await drawingManager.loadMarkupData(data, { mode: 'replace' });
 
-### No-Refresh Navigation
-When Document Browser panel is open, pagination uses internal Forge Viewer API (`_changeModelFn`) instead of full page reload. This provides:
-- ⚡ Faster page navigation
-- ✨ No panel refresh/flicker
-- 🎯 Smooth user experience
-- 💾 Memory efficient
+// Subscribe to changes
+const unsubscribe = drawingManager.onMarkupChange((delta) => {
+  // delta: { type: 'create'|'update'|'delete', markupId, data, timestamp }
+  socket.emit('markup:delta', delta);
+});
 
-### Intelligent State Management
-- Global state persists across extension lifecycles
-- Minimal re-renders and DOM updates
-- Efficient event-driven architecture
-- Debounced toolbar healing checks
+// Apply remote changes
+drawingManager.applyDelta(delta);
 
-### Adaptive UI
-- Panel height adjusts based on thumbnail count
-- Single page: Compact panel
-- Multi-page: Optimized for scrolling (max 80% viewport)
+// Batch apply (for initial load)
+drawingManager.applyBatch(elements, true);
+```
 
-## Development
+### User Presence
 
-```bash
-# Install dependencies
-npm install
+```typescript
+// Broadcast local cursor
+const unsub = drawingManager.onLocalCursorMove((position) => {
+  socket.emit('cursor:move', { userId, position });
+});
 
-# Build package
-npm run build
+// Update remote cursor
+drawingManager.updateUserCursor({ userId, userName, color, position });
 
-# Watch mode for development
-npm run dev
+// Remove cursor when user leaves
+drawingManager.removeUserCursor(userId);
+
+// Get all remote cursors
+const cursors = drawingManager.getRemoteCursors();
 ```
 
-## Testing
+## EventBus Events
 
-A complete test app is included in `/test/app`:
+| Event                      | Payload                  | Description            |
+| -------------------------- | ------------------------ | ---------------------- |
+| `page:changing`            | `{ fromIndex, toIndex }` | Before page navigation |
+| `page:changed`             | `{ index, viewable }`    | After page navigation  |
+| `drawing:editModeEntered`  | `{}`                     | Entered markup mode    |
+| `drawing:editModeExited`   | `{}`                     | Exited markup mode     |
+| `drawing:toolChanged`      | `{ tool }`               | Tool changed           |
+| `drawing:propertiesSynced` | `{ values }`             | Properties updated     |
 
-```bash
-cd test/app
-npm install
-npm run dev
+```javascript
+import { EventBus, EVENT_NAMES } from '@dtducas/wh-forge-viewer';
+
+const eventBus = EventBus.getInstance();
+
+eventBus.on(EVENT_NAMES.PAGE_CHANGED, ({ index }) => {
+  console.log('Now on page:', index);
+});
 ```
 
-## Publishing
+## Custom Toolbar
 
-The package is automatically published to NPM when you push a version tag:
+Built-in toolbar includes:
 
-```bash
-# Update version in package.json
-npm version patch  # or minor, major
+**Tools Group:**
 
-# Push tag
-git push origin v1.0.x
-```
+- Pan Tool - Navigate the document
+- Document Browser - Toggle thumbnail/tree view
+- Download - Download current document
 
-## Troubleshooting
+**Pagination Group:**
 
-### Browser Console Warning: "runtime.lastError"
+- Previous/Next Page navigation
+- Current page indicator
 
-**Error:** `Unchecked runtime.lastError: Could not establish connection. Receiving end does not exist.`
+**Smart Features:**
 
-**Cause:** This comes from browser extensions (React DevTools, Redux DevTools, etc.) trying to inject into your page.
+- No-refresh navigation when Document Browser is open
+- Self-healing mechanism for toolbar persistence
+- Synchronized button states
 
-**Solution:** This is safe to ignore. It doesn't affect your application. To remove the warning:
-- Disable browser extensions during development, OR
-- Add error boundary to catch extension errors
+## Requirements
 
-### Document Browser Button Not Syncing
+- React ^17.0.0 || ^18.0.0
+- Ant Design ^5.0.0 (peer dependency)
+- Modern browsers (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
 
-If the Document Browser button state doesn't match panel visibility:
-1. Check browser console for errors
-2. Verify Autodesk Forge Viewer version (should be v7.108.0)
-3. Try refreshing the page
-4. The self-healing mechanism should auto-fix within seconds
+## Development
 
-### Pagination Display Not Updating
+```bash
+# Install dependencies
+npm install
+
+# Build package
+npm run build
 
-If page numbers don't update after navigation:
-1. Extension includes aggressive update mechanism (10+ retries)
-2. Should auto-correct within 500ms
-3. Check if toolbar group is being removed by other extensions
+# Watch mode
+npm run dev
 
-## Changelog
+# Test app
+cd test/app && npm install && npm run dev
+```
 
-### v1.0.7 (Latest)
-- ✨ Smart navigation: Document Browser panel no longer refreshes when using pagination buttons
-- ✨ Auto-scroll thumbnails to center selected page
-- ✨ Adaptive panel height for single vs multi-page documents
-- ✨ Global state persistence across extension reload cycles
-- 🐛 Fixed: Document Browser button state sync after thumbnail navigation
-- 🐛 Fixed: Thumbnail selection not updating when using pagination buttons
-- 🧹 Removed all debug console logs for production
-- 📝 Full code cleanup and optimization
+## Documentation
 
-### v1.0.5
-- Initial public release
-- Custom toolbar with Pan, Document Browser, Download buttons
-- Pagination controls for multi-page documents
-- Self-healing toolbar mechanism
-- SOLID architecture refactor
+- [API Reference](docs/API.md) - Complete API documentation
+- [Architecture](ARCHITECTURE.md) - Detailed architecture documentation
+- [Versioning Guide](docs/VERSIONING.md) - Forge Viewer version management
+- [Collaborative API](docs/COLLABORATIVE-API.md) - Real-time collaboration guide
 
 ## License
 
@@ -335,20 +419,15 @@ MIT
 
 **Duong Tran Quang**
 
-- Email: <baymax.contact@gmail.com>
+- Email: baymax.contact@gmail.com
 - GitHub: [@DTDucas](https://github.com/DTDucas)
 - LinkedIn: [dtducas](https://www.linkedin.com/in/dtducas)
 
-## Support & Issues
-
-- 🐛 [Report bugs](https://github.com/DTDucas/wh-forge-viewer/issues)
-- 💡 [Request features](https://github.com/DTDucas/wh-forge-viewer/issues)
-- 📖 [View documentation](https://github.com/DTDucas/wh-forge-viewer#readme)
-
-## Contributing
+## Support
 
-Contributions are welcome! Please read [ARCHITECTURE.md](ARCHITECTURE.md) before submitting PRs.
+- [Report bugs](https://github.com/DTDucas/wh-forge-viewer/issues)
+- [Request features](https://github.com/DTDucas/wh-forge-viewer/issues)
 
 ---
 
-Made with ❤️ by [DTDucas](https://github.com/DTDucas)
+Made with care by [DTDucas](https://github.com/DTDucas)