@dtducas/wh-forge-viewer 1.0.7 → 1.0.9-beta0

package/README.md

@@ -1,92 +1,392 @@
 # wh-forge-viewer
 
-A customized Autodesk Forge Viewer component for React with enhanced PDF support and custom toolbar.
+A professional Autodesk Forge Viewer component for React with advanced PDF support, comprehensive markup tools, and real-time collaboration capabilities.
 
 ## Features
 
-- ✅ **Custom Toolbar** - Pre-configured toolbar with Pan, Document Browser, Download, and Pagination controls
-- ✅ **PDF Support** - Optimized for viewing PDF documents with page navigation
-- ✅ **Auto Document Browser** - Automatically opens on startup, positioned on left side
-- ✅ **Smooth Pagination** - Page navigation without toolbar flickering
-- ✅ **Self-Healing** - Automatic toolbar recovery mechanism ensures UI persistence
-- ✅ **3D/2D Models** - Full support for Autodesk Forge 3D and 2D models
-- ✅ **React Integration** - Easy-to-use React component with hooks support
-- ✅ **SOLID Architecture** - Follows SOLID principles with Manager pattern for maintainability
+### 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 custom toolbar with:
+  useEffect(() => {
+    if (!viewer) return;
 
-### Tools Group
+    const manager = new DrawingManager(viewer, eventBus, {
+      autoEnterEditMode: true,
+      defaultTool: 'arrow',
+    });
 
-- **Pan** - Enable pan navigation
-- **Document Browser** - Toggle document tree view
-- **Download** - Download the current document
+    setDrawingManager(manager);
 
-### Pagination Group
+    return () => manager.destroy();
+  }, [viewer]);
 
-- **Previous Page** - Navigate to previous page
-- **Page Counter** - Display current page / total pages
-- **Next Page** - Navigate to next page
+  const handleToolChange = (tool) => {
+    drawingManager?.setActiveTool(tool);
+    setActiveTool(tool);
+    setPropertyConfig(drawingManager?.getCurrentToolPropertyConfig());
+    setPropertyValues(drawingManager?.getCurrentToolPropertyValues() || {});
+  };
 
-## Requirements
+  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>
+  );
+}
+```
 
-- React ^17.0.0 || ^18.0.0
-- Ant Design ^5.0.0
-- Autodesk Forge Viewer v7.108.0 (pinned for stability)
+### Real-Time Collaboration
+
+```jsx
+import {
+  DrawingManager,
+  EventBus,
+  CursorOverlay,
+} from '@dtducas/wh-forge-viewer';
+
+function CollaborativeViewer({ socket }) {
+  const [drawingManager, setDrawingManager] = useState(null);
+  const [remoteCursors, setRemoteCursors] = useState(new Map());
+
+  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]);
+
+  return (
+    <>
+      {/* ... viewer components ... */}
+      <CursorOverlay cursors={remoteCursors} />
+    </>
+  );
+}
+```
+
+### Persistence
+
+```javascript
+// Save to localStorage
+const data = drawingManager.getMarkupData();
+localStorage.setItem('markups', JSON.stringify(data));
+
+// Load from localStorage
+const saved = JSON.parse(localStorage.getItem('markups'));
+await drawingManager.loadMarkupData(saved, { mode: 'replace' });
+
+// Save to database (JSON format)
+const jsonData = drawingManager.getMarkupDataAsJson('page-guid-123');
+await db.collection('markups').doc('page-guid-123').set(jsonData);
+
+// Load from database
+const doc = await db.collection('markups').doc('page-guid-123').get();
+await drawingManager.loadMarkupDataFromJson(doc.data());
+```
+
+### PDF Export with Markup
+
+```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
+}
+
+// Multi-page export
+const markupsByPage = [
+  { pageIndex: 0, svgString: savedPage0Svg },
+  { pageIndex: 1, svgString: drawingManager.getMarkupSVG() }, // current page
+];
+await drawingManager.exportAndDownloadPDF(filePath, markupsByPage, {
+  filename: 'annotated-document',
+});
+```
+
+## Components
+
+### ViewerForgePDF
+
+Main viewer component.
+
+| 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             |
+
+### MarkupToolbar
+
+Floating toolbar for tool selection.
+
+| Prop           | Type     | Description           |
+| -------------- | -------- | --------------------- |
+| `activeTool`   | string   | Currently active tool |
+| `onToolChange` | function | Tool change callback  |
+| `onUndo`       | function | Undo callback         |
+| `onRedo`       | function | Redo callback         |
+
+### PropertyPanel
 
-## Important Notes
+Side panel for editing properties.
 
-### Viewer Versioning
+| Prop       | Type                | Description              |
+| ---------- | ------------------- | ------------------------ |
+| `config`   | IToolPropertyConfig | Property configuration   |
+| `values`   | object              | Current property values  |
+| `onChange` | function            | Property change callback |
+| `onAction` | function            | Action button callback   |
 
-This package uses a **specific version** of Autodesk Forge Viewer (v7.108.0) instead of wildcards (7.*) to ensure production stability and avoid unexpected breaking changes.
+### CursorOverlay
 
-**Why?** Using wildcards can introduce unexpected behavior changes when Autodesk releases updates. For production applications, always use a specific tested version.
+Overlay for displaying remote cursors.
 
-📖 See [docs/VERSIONING.md](docs/VERSIONING.md) for version update guide.
+| Prop           | Type    | Description                   |
+| -------------- | ------- | ----------------------------- |
+| `cursors`      | Map     | Remote user cursors           |
+| `viewerBounds` | DOMRect | Viewer bounds for positioning |
 
-## Architecture
+## DrawingManager API
 
-This package follows **SOLID principles** and uses a modular architecture:
+### Edit Mode
 
-- **Managers Pattern** - Separate managers for Pagination, Toolbar, and Document Browser
-- **Service Layer** - EventBus, FileLoader, DownloadService
-- **Type Safety** - Full TypeScript type definitions
-- **Dependency Injection** - Clean separation of concerns
+```typescript
+await drawingManager.enterEditMode(); // Enter markup mode
+drawingManager.leaveEditMode(); // Exit markup mode
+drawingManager.isEditMode(); // Check if in edit mode
+```
+
+### Tools
+
+```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
+```
+
+**Available Tools:**
+`select`, `arrow`, `rectangle`, `ellipse`, `cloud`, `label`, `freehand`, `line`, `polyline`, `polycloud`, `callout`, `image`
+
+### Markup Operations
+
+```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
+```
+
+### Collaborative API
+
+```typescript
+// Get markup data for persistence
+const data = drawingManager.getMarkupData(viewableGUID);
+
+// Load markup data
+await drawingManager.loadMarkupData(data, { mode: 'replace' });
+
+// Subscribe to changes
+const unsubscribe = drawingManager.onMarkupChange((delta) => {
+  // delta: { type: 'create'|'update'|'delete', markupId, data, timestamp }
+  socket.emit('markup:delta', delta);
+});
+
+// Apply remote changes
+drawingManager.applyDelta(delta);
+
+// Batch apply (for initial load)
+drawingManager.applyBatch(elements, true);
+```
+
+### User Presence
+
+```typescript
+// Broadcast local cursor
+const unsub = drawingManager.onLocalCursorMove((position) => {
+  socket.emit('cursor:move', { userId, position });
+});
+
+// Update remote cursor
+drawingManager.updateUserCursor({ userId, userName, color, position });
+
+// Remove cursor when user leaves
+drawingManager.removeUserCursor(userId);
+
+// Get all remote cursors
+const cursors = drawingManager.getRemoteCursors();
+```
+
+## EventBus Events
+
+| 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     |
 
-📖 See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture documentation.
+```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);
+});
+```
+
+## Custom Toolbar
+
+Built-in toolbar includes:
+
+**Tools Group:**
+
+- Pan Tool - Navigate the document
+- Document Browser - Toggle thumbnail/tree view
+- Download - Download current document
+
+**Pagination Group:**
+
+- Previous/Next Page navigation
+- Current page indicator
+
+**Smart Features:**
+
+- No-refresh navigation when Document Browser is open
+- Self-healing mechanism for toolbar persistence
+- Synchronized button states
+
+## Requirements
+
+- React ^17.0.0 || ^18.0.0
+- Ant Design ^5.0.0 (peer dependency)
+- Modern browsers (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
 
 ## Development
 
@@ -99,16 +399,17 @@ npm run build
 
 # Watch mode
 npm run dev
-```
 
-## Publishing
+# Test app
+cd test/app && npm install && npm run dev
+```
 
-The package is automatically published to NPM when you push a version tag:
+## Documentation
 
-```bash
-git tag v1.0.0
-git push origin v1.0.0
-```
+- [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
 
@@ -118,10 +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)
 
-## Issues
+## Support
+
+- [Report bugs](https://github.com/DTDucas/wh-forge-viewer/issues)
+- [Request features](https://github.com/DTDucas/wh-forge-viewer/issues)
+
+---
 
-Report bugs and feature requests at [GitHub Issues](https://github.com/DTDucas/wh-forge-viewer/issues)
+Made with care by [DTDucas](https://github.com/DTDucas)