@edgepdf/viewer-js 0.0.31 → 0.0.33

package/README.md

@@ -8,20 +8,19 @@ Core JavaScript library for the EdgePDF viewer, providing Leaflet map integratio
 npm install @edgepdf/viewer-js
 # or
 pnpm add @edgepdf/viewer-js
+# or
+yarn add @edgepdf/viewer-js
 ```
 
-**Note:** Leaflet is bundled with this library, so you don't need to install it separately.
-
-**For SSR frameworks (Next.js, Remix, etc.):** This library requires a browser environment. Use dynamic imports or the React component (`@edgepdf/viewer-react`) which handles SSR automatically. See [SSR Support](#ssr-support) section below.
+**Note:** Leaflet is bundled with this library, so you don't need to install it separately. **CSS styles are automatically injected** when you import the library - no manual CSS import needed!
 
-## Usage
+## Quick Start
 
 ### Basic Example
 
 ```typescript
 import { EdgePdfViewer } from '@edgepdf/viewer-js';
 import type { ViewerConfig } from '@edgepdf/types';
-// CSS is automatically injected - no need to import styles manually!
 
 // Get container element
 const container = document.getElementById('map-container');
@@ -42,6 +41,16 @@ const config: ViewerConfig = {
 const viewer = new EdgePdfViewer({ container, config });
 viewer.initialize();
 
+// Access marker manager
+const markerManager = viewer.getMarkerManager();
+if (markerManager) {
+  // Create a marker
+  const marker = markerManager.createMarker({
+    position: [1500, 1000], // [lat, lng] in Leaflet coordinates
+    label: 'My Marker',
+  });
+}
+
 // Cleanup when done
 viewer.dispose();
 ```
@@ -51,7 +60,6 @@ viewer.dispose();
 ```typescript
 import { EdgePdfViewer } from '@edgepdf/viewer-js';
 import type { ViewerConfig, MapOptions } from '@edgepdf/types';
-// CSS is automatically injected - no need to import styles manually!
 
 const config: ViewerConfig = {
   tileUrl: 'https://example.com/tiles/{z}/{x}/{y}.png',
@@ -80,93 +88,6 @@ const viewer = new EdgePdfViewer({
 viewer.initialize();
 ```
 
-## SSR Support
-
-This library uses Leaflet, which requires a browser environment. For SSR frameworks like Next.js, Remix, or other React frameworks, you have two options:
-
-### Option 1: Use the React Component (Recommended)
-
-The `@edgepdf/viewer-react` package handles SSR automatically with dynamic imports:
-
-```tsx
-import { EdgePDFViewer } from '@edgepdf/viewer-react';
-import { ViewerProvider } from '@edgepdf/viewer-react';
-
-// In your component
-<ViewerProvider>
-  <EdgePDFViewer config={config} />
-</ViewerProvider>;
-```
-
-### Option 2: Use Dynamic Imports (Next.js)
-
-If you need to use `@edgepdf/viewer-js` directly in Next.js, use dynamic imports with `ssr: false`:
-
-```tsx
-import dynamic from 'next/dynamic';
-
-const EdgePdfViewer = dynamic(
-  () => import('@edgepdf/viewer-js').then((mod) => mod.EdgePdfViewer),
-  { ssr: false }
-);
-
-// Or use it in a client component
-('use client');
-
-import { useEffect, useRef } from 'react';
-import dynamic from 'next/dynamic';
-
-const EdgePdfViewer = dynamic(
-  () => import('@edgepdf/viewer-js').then((mod) => mod.EdgePdfViewer),
-  { ssr: false }
-);
-
-export default function MyComponent() {
-  const containerRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!containerRef.current) return;
-
-    const { EdgePdfViewer } = require('@edgepdf/viewer-js');
-    const viewer = new EdgePdfViewer({
-      container: containerRef.current,
-      config: yourConfig,
-    });
-    viewer.initialize();
-
-    return () => viewer.dispose();
-  }, []);
-
-  return <div ref={containerRef} style={{ width: '100%', height: '100%' }} />;
-}
-```
-
-### Next.js Configuration
-
-If you're still getting build errors, add this to your `next.config.js`:
-
-```javascript
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  webpack: (config, { isServer }) => {
-    if (isServer) {
-      // Exclude @edgepdf/viewer-js from server-side bundle
-      config.externals = config.externals || [];
-      config.externals.push('@edgepdf/viewer-js');
-    }
-    return config;
-  },
-};
-
-module.exports = nextConfig;
-```
-
-**Note:** You'll also need to import the CSS manually when using dynamic imports:
-
-```tsx
-import '@edgepdf/viewer-js/dist/styles.css';
-```
-
 ## API Reference
 
 ### EdgePdfViewer
@@ -218,10 +139,428 @@ Checks if the map is initialized.
 
 **Returns:** `true` if map is initialized, `false` otherwise
 
+##### `getTileLayerManager(): TileLayerManager | null`
+
+Gets the tile layer manager instance.
+
+**Returns:** The tile layer manager, or `null` if not created
+
+##### `getCoordinateMapper(): CoordinateMapper | null`
+
+Gets the coordinate mapper instance.
+
+**Returns:** The coordinate mapper, or `null` if not created
+
+##### `getZoomController(): ZoomController | null`
+
+Gets the zoom controller instance.
+
+**Returns:** The zoom controller, or `null` if not created
+
+##### `getMarkerManager(): MarkerManager | null`
+
+Gets the marker manager instance.
+
+**Returns:** The marker manager, or `null` if not created
+
+##### `focusMarker(markerOrId: string | Marker, options?: FocusOptions): boolean`
+
+Focuses on a marker by panning and zooming to its position.
+
+**Parameters:**
+
+- `markerOrId` - Marker ID string or Marker object
+- `options` - Optional focus options
+  - `zoom?: number` - Target zoom level (uses marker's zoom or default if not provided)
+  - `animate?: boolean` - Whether to animate the transition (default: true)
+  - `duration?: number` - Animation duration in seconds (default: 0.5)
+
+**Returns:** `true` if focus was successful, `false` if marker not found or viewer not initialized
+
 ##### `dispose(): void`
 
 Disposes of the map instance and cleans up resources. This should be called when the viewer is no longer needed to prevent memory leaks and event listener issues.
 
+---
+
+### MarkerManager
+
+Manages markers on the Leaflet map. Access via `viewer.getMarkerManager()`.
+
+#### Methods
+
+##### `createMarker(options: CreateMarkerOptions): Marker`
+
+Creates a new marker from coordinates.
+
+**Parameters:**
+
+- `options.position?: LeafletCoords` - Leaflet coordinates [lat, lng]
+- `options.imageCoords?: ImageCoords` - Image pixel coordinates {x, y}
+- `options.label?: string` - Marker label/tooltip text
+- `options.description?: string` - Marker description
+- `options.href?: string` - Link URL (optional)
+- `options.target?: string` - Link target (optional)
+- `options.showLabel?: boolean` - Show label/tooltip
+- `options.id?: string` - Custom marker ID (auto-generated if not provided)
+- `options.iconType?: 'pin-gray' | 'pin-yellow'` - Icon type for the marker
+- `options.referenceId?: string` - Reference ID for linking to external systems
+- `options.draggable?: boolean` - Enable dragging for this specific marker
+- `options.editable?: boolean` - Enable editing for this specific marker
+- `options.deletable?: boolean` - Enable deleting for this specific marker
+
+**Returns:** The created marker
+
+**Throws:**
+
+- `Error` if neither position nor imageCoords is provided
+- `Error` if coordinates are invalid or out of bounds
+
+##### `getMarker(id: string): Marker | null`
+
+Gets a marker by ID.
+
+**Returns:** The marker, or `null` if not found
+
+##### `getAllMarkers(): Marker[]`
+
+Gets all markers.
+
+**Returns:** Array of all markers
+
+##### `getMarkerCount(): number`
+
+Gets the total number of markers.
+
+**Returns:** Number of markers
+
+##### `hasMarker(id: string): boolean`
+
+Checks if a marker exists.
+
+**Returns:** `true` if marker exists, `false` otherwise
+
+##### `updateMarker(id: string, updates: Partial<Marker>): boolean`
+
+Updates a marker's properties.
+
+**Parameters:**
+
+- `id` - Marker ID
+- `updates` - Partial marker object with properties to update
+
+**Returns:** `true` if marker was updated, `false` if not found
+
+##### `updateMarkerPosition(id: string, position: LeafletCoords): boolean`
+
+Updates a marker's position.
+
+**Parameters:**
+
+- `id` - Marker ID
+- `position` - New Leaflet coordinates [lat, lng]
+
+**Returns:** `true` if marker was updated, `false` if not found
+
+##### `updateMarkerIcon(id: string, iconType: 'pin-gray' | 'pin-yellow'): boolean`
+
+Updates the icon type for a specific marker.
+
+**Returns:** `true` if marker was updated, `false` if not found
+
+##### `updateAllMarkerIcons(iconType: 'pin-gray' | 'pin-yellow'): void`
+
+Updates all markers to use a new icon type.
+
+##### `removeMarker(id: string): boolean`
+
+Removes a marker by ID.
+
+**Returns:** `true` if marker was removed, `false` if not found
+
+##### `removeAllMarkers(): void`
+
+Removes all markers.
+
+##### `deleteMarker(id: string): boolean`
+
+Deletes a marker by ID (triggers delete event).
+
+**Returns:** `true` if marker was deleted, `false` if not found
+
+##### `exportMarkers(): MarkerData`
+
+Exports all markers as JSON data.
+
+**Returns:** MarkerData object containing all markers and metadata
+
+##### `importMarkers(data: MarkerData, options?: ImportOptions): ImportResult`
+
+Imports markers from MarkerData.
+
+**Parameters:**
+
+- `data` - MarkerData object to import
+- `options` - Import options
+  - `clearExisting?: boolean` - If true, removes all existing markers before import (default: false)
+  - `validateCoordinates?: boolean` - If true, validates coordinates are within bounds (default: true)
+
+**Returns:** Import result with success status and details
+
+##### `setInteractionConfig(config: Partial<MarkerInteractionConfig>): void`
+
+Sets marker interaction configuration.
+
+**Parameters:**
+
+- `config.draggable?: boolean` - Enable dragging markers
+- `config.selectable?: boolean` - Enable selecting markers
+- `config.showTooltips?: boolean` - Show tooltips on hover
+- `config.showPopups?: boolean` - Show popups on click
+- `config.multiSelect?: boolean` - Allow multiple marker selection
+- `config.showEditButton?: boolean` - Show edit button in popups
+- `config.showDeleteButton?: boolean` - Show delete button in popups
+- `config.onEdit?: (marker: Marker) => Promise<Marker | null>` - Custom edit handler
+- `config.onDelete?: (marker: Marker) => Promise<boolean>` - Custom delete handler
+- `config.onActiveMarkerChange?: (marker: Marker | null) => void` - Active marker change callback
+
+##### `getInteractionConfig(): MarkerInteractionConfig`
+
+Gets the current interaction configuration.
+
+**Returns:** Current interaction configuration
+
+##### `selectMarker(id: string): boolean`
+
+Selects a marker.
+
+**Returns:** `true` if marker was selected, `false` if not found
+
+##### `deselectMarker(id: string): boolean`
+
+Deselects a marker.
+
+**Returns:** `true` if marker was deselected, `false` if not found
+
+##### `deselectAllMarkers(): void`
+
+Deselects all markers.
+
+##### `getSelectionState(): MarkerSelectionState`
+
+Gets the current selection state.
+
+**Returns:** Selection state object with selected IDs and count
+
+##### `isMarkerSelected(id: string): boolean`
+
+Checks if a marker is selected.
+
+**Returns:** `true` if marker is selected, `false` otherwise
+
+##### `setActiveMarker(id: string | null): boolean`
+
+Sets the active marker (for popup management).
+
+**Returns:** `true` if active marker was set, `false` if marker not found
+
+##### `getActiveMarker(): Marker | null`
+
+Gets the currently active marker.
+
+**Returns:** The active marker, or `null` if no marker is active
+
+##### `focusMarker(markerOrId: string | Marker, options?: FocusOptions): boolean`
+
+Focuses on a marker by panning and zooming to its position.
+
+**Parameters:**
+
+- `markerOrId` - Marker ID string or Marker object
+- `options` - Optional focus options
+  - `zoom?: number` - Target zoom level
+  - `animate?: boolean` - Whether to animate (default: true)
+  - `duration?: number` - Animation duration in seconds (default: 0.5)
+
+**Returns:** `true` if focus was successful, `false` if marker not found
+
+##### `setDefaultIconType(iconType: 'pin-gray' | 'pin-yellow'): void`
+
+Sets the default icon type for new markers.
+
+##### `getDefaultIconType(): 'pin-gray' | 'pin-yellow'`
+
+Gets the current default icon type.
+
+**Returns:** Current default icon type
+
+##### `setIconBasePath(basePath: string): void`
+
+Sets the base path for marker icons.
+
+**Example:**
+
+```typescript
+// Use library's built-in icons (default)
+markerManager.setIconBasePath('./images/');
+
+// Use custom icons from public folder
+markerManager.setIconBasePath('/');
+
+// Use icons from a CDN
+markerManager.setIconBasePath('https://cdn.example.com/icons/');
+```
+
+##### `getIconBasePath(): string`
+
+Gets the current base path for marker icons.
+
+**Returns:** The current icon base path
+
+##### `on(eventType: MarkerEventType, callback: (event: MarkerEvent) => void): () => void`
+
+Registers an event listener.
+
+**Parameters:**
+
+- `eventType` - Event type: 'click' | 'dragstart' | 'drag' | 'dragend' | 'edit' | 'delete'
+- `callback` - Callback function
+
+**Returns:** Unsubscribe function
+
+**Example:**
+
+```typescript
+const unsubscribe = markerManager.on('click', (event) => {
+  console.log('Marker clicked:', event.marker.id);
+});
+
+// Later, to unsubscribe:
+unsubscribe();
+```
+
+##### `off(eventType: MarkerEventType, callback: (event: MarkerEvent) => void): void`
+
+Unregisters an event listener.
+
+##### `removeAllListeners(eventType?: MarkerEventType): void`
+
+Removes all event listeners for a specific event type, or all events if no type is provided.
+
+##### `dispose(): void`
+
+Disposes of the marker manager and cleans up resources.
+
+---
+
+### ZoomController
+
+Manages zoom state and operations. Access via `viewer.getZoomController()`.
+
+#### Methods
+
+##### `zoomIn(options?: { animate?: boolean }): boolean`
+
+Zooms in by one level.
+
+**Parameters:**
+
+- `options.animate?: boolean` - Whether to animate the zoom (default: true)
+
+**Returns:** `true` if zoomed in, `false` if already at max zoom
+
+##### `zoomOut(options?: { animate?: boolean }): boolean`
+
+Zooms out by one level.
+
+**Parameters:**
+
+- `options.animate?: boolean` - Whether to animate the zoom (default: true)
+
+**Returns:** `true` if zoomed out, `false` if already at min zoom
+
+##### `setZoom(zoom: number, options?: { animate?: boolean }): void`
+
+Sets a specific zoom level.
+
+**Parameters:**
+
+- `zoom` - Target zoom level
+- `options.animate?: boolean` - Whether to animate the zoom (default: true)
+
+**Throws:**
+
+- `Error` if zoom is not a finite number
+
+##### `getZoom(): number`
+
+Gets the current zoom level.
+
+**Returns:** Current zoom level
+
+##### `getZoomState(): ZoomState`
+
+Gets the current zoom state.
+
+**Returns:** Zoom state object with currentZoom, minZoom, maxZoom
+
+##### `getMinZoom(): number`
+
+Gets the minimum zoom level.
+
+**Returns:** Minimum zoom level
+
+##### `getMaxZoom(): number`
+
+Gets the maximum zoom level.
+
+**Returns:** Maximum zoom level
+
+##### `canZoomIn(): boolean`
+
+Checks if can zoom in.
+
+**Returns:** `true` if can zoom in, `false` otherwise
+
+##### `canZoomOut(): boolean`
+
+Checks if can zoom out.
+
+**Returns:** `true` if can zoom out, `false` otherwise
+
+##### `onZoomChange(listener: (state: ZoomState) => void): () => void`
+
+Registers a zoom change listener.
+
+**Returns:** Unsubscribe function
+
+##### `removeAllListeners(): void`
+
+Removes all zoom change listeners.
+
+##### `dispose(): void`
+
+Disposes of the zoom controller and cleans up resources.
+
+---
+
+### Utility Functions
+
+#### `createZoomControls(container: HTMLElement, zoomController: ZoomController, options?: ZoomControlsOptions): HTMLElement`
+
+Creates zoom control buttons (zoom in/out) in the specified container.
+
+**Parameters:**
+
+- `container` - Container element
+- `zoomController` - Zoom controller instance
+- `options` - Optional configuration
+  - `position?: ZoomControlsPosition` - Position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' (default: 'top-right')
+
+**Returns:** The created controls element
+
+---
+
 ## Configuration
 
 ### ViewerConfig
@@ -318,16 +657,77 @@ The viewer uses Leaflet's `CRS.Simple` coordinate system, which treats coordinat
 - Y-axis: vertical pixel position (0 to image height)
 - Origin: top-left corner (0, 0)
 
-## Building
+## Examples
 
-Run `nx build viewer-js` to build the library.
+### Working with Markers
 
-## Running Tests
+```typescript
+const viewer = new EdgePdfViewer({ container, config });
+viewer.initialize();
+
+const markerManager = viewer.getMarkerManager();
+if (!markerManager) return;
+
+// Create a marker
+const marker = markerManager.createMarker({
+  position: [1500, 1000],
+  label: 'My Marker',
+  description: 'This is a marker description',
+  iconType: 'pin-yellow',
+});
 
-Run `nx test viewer-js` to execute the unit tests via [Jest](https://jestjs.io).
+// Update marker
+markerManager.updateMarker(marker.id, {
+  label: 'Updated Label',
+  description: 'Updated description',
+});
 
-Run `nx test viewer-js --coverage` to generate coverage reports.
+// Listen to marker events
+markerManager.on('click', (event) => {
+  console.log('Marker clicked:', event.marker);
+});
 
-## License
+markerManager.on('dragend', (event) => {
+  console.log('Marker dragged to:', event.marker.position);
+});
 
-MIT
+// Export markers
+const markerData = markerManager.exportMarkers();
+console.log(JSON.stringify(markerData, null, 2));
+
+// Import markers
+markerManager.importMarkers(markerData, {
+  clearExisting: true,
+  validateCoordinates: true,
+});
+```
+
+### Working with Zoom
+
+```typescript
+const viewer = new EdgePdfViewer({ container, config });
+viewer.initialize();
+
+const zoomController = viewer.getZoomController();
+if (!zoomController) return;
+
+// Zoom in
+zoomController.zoomIn();
+
+// Zoom out
+zoomController.zoomOut();
+
+// Set specific zoom level
+zoomController.setZoom(3);
+
+// Get zoom state
+const zoomState = zoomController.getZoomState();
+console.log('Current zoom:', zoomState.currentZoom);
+console.log('Min zoom:', zoomState.minZoom);
+console.log('Max zoom:', zoomState.maxZoom);
+
+// Listen to zoom changes
+zoomController.onZoomChange((state) => {
+  console.log('Zoom changed to:', state.currentZoom);
+});
+```