@dtducas/wh-forge-viewer 1.0.6 → 1.0.8-beta

package/README.md

@@ -1,17 +1,29 @@
 # 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, intelligent navigation, and production-ready architecture.
 
 ## Features
 
+### Core 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
+- ✅ **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
-- ✅ **SOLID Architecture** - Follows SOLID principles with Manager pattern for maintainability
+
+### 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
 
 ## Installation
 
@@ -47,47 +59,193 @@ function MyApp() {
 
 ## Custom Toolbar
 
-The viewer includes a custom toolbar with:
+The viewer includes a production-ready custom toolbar with two control groups:
 
 ### Tools Group
 
-- **Pan** - Enable pan navigation
-- **Document Browser** - Toggle document tree view
+- **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
 
 ### Pagination Group
 
-- **Previous Page** - Navigate to previous page
-- **Page Counter** - Display current page / total pages
-- **Next Page** - Navigate to next page
+- **Previous Page** ◀ - Navigate to previous page
+- **Page Counter** - Display "current / total" pages (e.g., "3 / 9")
+- **Next Page** ▶ - Navigate to next page
+
+**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
 
 ## Requirements
 
+### Peer Dependencies
 - React ^17.0.0 || ^18.0.0
 - Ant Design ^5.0.0
-- Autodesk Forge Viewer v7.108.0 (pinned for stability)
+
+### Browser Support
+- Modern browsers with ES6+ support
+- Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
+
+### Autodesk Forge Viewer
+- Uses v7.108.0 (loaded from CDN)
+- Pinned version for production stability
 
 ## Important Notes
 
 ### Viewer Versioning
 
-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.
+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.
 
-**Why?** Using wildcards can introduce unexpected behavior changes when Autodesk releases updates. For production applications, always use a specific tested version.
+**Why pinned version?**
+- ✅ Predictable behavior in production
+- ✅ No surprise updates from Autodesk
+- ✅ Tested and verified functionality
+- ✅ Easy to upgrade when ready
 
 📖 See [docs/VERSIONING.md](docs/VERSIONING.md) for version update guide.
 
+### Known Behaviors
+
+**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
+
+**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
+
 ## Architecture
 
-This package follows **SOLID principles** and uses a modular architecture:
+This package follows **SOLID principles** and uses a production-ready modular architecture:
+
+### Core Components
 
-- **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
+**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
+
+**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
+
+**Extension**
+- `ToolbarExtension` - Main extension that orchestrates all managers and services
+
+### Key Features
+
+**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
+
+**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
+
+**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
 
 📖 See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture documentation.
 
+## Advanced Usage
+
+### Accessing Viewer Instance
+
+```jsx
+function MyApp() {
+  const [viewer, setViewer] = useState(null);
+
+  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]);
+
+  return (
+    <ViewerForgePDF
+      filePath="/path/to/document.pdf"
+      fileExt="pdf"
+      setViewer={setViewer}
+    />
+  );
+}
+```
+
+### Event Bus Integration
+
+The package exposes an EventBus for custom integrations:
+
+```javascript
+import { EventBus } from '@dtducas/wh-forge-viewer';
+
+const eventBus = EventBus.getInstance();
+
+// 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);
+});
+
+// Listen to Document Browser events
+eventBus.on('docBrowser:opened', () => {
+  console.log('Document Browser opened');
+});
+
+eventBus.on('docBrowser:closed', () => {
+  console.log('Document Browser closed');
+});
+```
+
+## Performance Optimizations
+
+### 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
+
+### Intelligent State Management
+- Global state persists across extension lifecycles
+- Minimal re-renders and DOM updates
+- Efficient event-driven architecture
+- Debounced toolbar healing checks
+
+### Adaptive UI
+- Panel height adjusts based on thumbnail count
+- Single page: Compact panel
+- Multi-page: Optimized for scrolling (max 80% viewport)
+
 ## Development
 
 ```bash
@@ -97,7 +255,17 @@ npm install
 # Build package
 npm run build
 
-# Watch mode
+# Watch mode for development
+npm run dev
+```
+
+## Testing
+
+A complete test app is included in `/test/app`:
+
+```bash
+cd test/app
+npm install
 npm run dev
 ```
 
@@ -106,10 +274,59 @@ npm run dev
 The package is automatically published to NPM when you push a version tag:
 
 ```bash
-git tag v1.0.0
-git push origin v1.0.0
+# Update version in package.json
+npm version patch  # or minor, major
+
+# Push tag
+git push origin v1.0.x
 ```
 
+## Troubleshooting
+
+### Browser Console Warning: "runtime.lastError"
+
+**Error:** `Unchecked runtime.lastError: Could not establish connection. Receiving end does not exist.`
+
+**Cause:** This comes from browser extensions (React DevTools, Redux DevTools, etc.) trying to inject into your page.
+
+**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
+
+### Document Browser Button Not Syncing
+
+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
+
+### Pagination Display Not Updating
+
+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
+
+## Changelog
+
+### 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
+
+### 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
+
 ## License
 
 MIT
@@ -122,6 +339,16 @@ MIT
 - GitHub: [@DTDucas](https://github.com/DTDucas)
 - LinkedIn: [dtducas](https://www.linkedin.com/in/dtducas)
 
-## Issues
+## 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
+
+Contributions are welcome! Please read [ARCHITECTURE.md](ARCHITECTURE.md) before submitting PRs.
+
+---
 
-Report bugs and feature requests at [GitHub Issues](https://github.com/DTDucas/wh-forge-viewer/issues)
+Made with ❤️ by [DTDucas](https://github.com/DTDucas)

package/dist/index.d.ts

@@ -7,7 +7,23 @@ declare module '@dtducas/wh-forge-viewer' {
   /**
    * Supported file extensions for the Forge Viewer
    */
-  export type TSupportedFileExtension = 'pdf' | 'dwf' | 'dwfx';
+  export type TSupportedFileExtension = 'pdf' | 'dwf' | 'dwfx' | 'gltf' | 'glb';
+
+  /**
+   * Toolbar visibility options
+   */
+  export interface IToolbarOptions {
+    /** Show Pan button (default: true) */
+    showPan?: boolean;
+    /** Show Document Browser button (default: true) */
+    showDocBrowser?: boolean;
+    /** Show Download button (default: true) */
+    showDownload?: boolean;
+    /** Show Pagination controls (default: true) */
+    showPagination?: boolean;
+    /** Master switch - show entire custom toolbar (default: true) */
+    showToolbar?: boolean;
+  }
   /**
    * Autodesk Forge Viewer namespace
    * For full type definitions, see Autodesk Forge Viewer documentation
@@ -47,9 +63,14 @@ declare module '@dtducas/wh-forge-viewer' {
      */
     filePath: string;
     /**
-     * File extension (pdf, dwf, dwfx)
+     * File extension (pdf, dwf, dwfx, gltf, glb)
      */
     fileExt: TSupportedFileExtension;
+    /**
+     * Toolbar visibility options
+     * Controls which toolbar buttons and controls are displayed
+     */
+    toolbarOptions?: IToolbarOptions;
     /**
      * Callback to receive viewer instance when initialized
      */
@@ -69,6 +90,7 @@ declare module '@dtducas/wh-forge-viewer' {
    *     <ViewerForgePDF
    *       filePath="https://example.com/document.pdf"
    *       fileExt="pdf"
+   *       toolbarOptions={{ showDownload: true, showDocBrowser: true }}
    *       setViewer={setViewer}
    *     />
    *   );