bdsa-react-components 0.1.2 → 0.1.4

package/CURSOR_INTEGRATION.md

@@ -1,6 +1,6 @@
 # bdsa-react-components - CURSOR Integration Guide
 
-**Version:** 0.1.2 | **Generated:** 2025-11-01T20:15:49.818Z
+**Version:** 0.1.4 | **Generated:** 2025-11-02T18:53:09.742Z
 
 > This document provides everything Cursor needs to integrate and use the bdsa-react-components library.
 > Copy this entire document into your project's .cursorrules or docs folder.
@@ -217,7 +217,77 @@ const fetchWithAuth = async (url: string, options?: RequestInit) => {
 />
 ```
 
-### 2. SlideViewer with API-Fetched Annotations
+### 2. SlideViewer with API-Fetched Annotations (RECOMMENDED)
+
+**⭐ RECOMMENDED APPROACH:** Use `onAnnotationStateChange` - unified callback with complete state sync:
+
+```tsx
+// Unified state - single state object for all annotation state
+const [annotationState, setAnnotationState] = useState({
+  loadedIds: [] as string[],
+  opacities: new Map<string, number>(),
+  visibility: new Map<string, boolean>(),
+})
+
+const imageId = '6903df8dd26a6d93de19a9b2'
+
+<>
+  <AnnotationManager
+    imageId={imageId}
+    apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+    onAnnotationStateChange={(state) => {
+      // Single callback fires for all state changes (load, opacity, visibility)
+      // 70% less boilerplate than individual callbacks!
+      setAnnotationState({
+        loadedIds: state.loadedAnnotationIds,
+        opacities: state.opacities,
+        visibility: state.visibility,
+      })
+    }}
+    onAnnotationReady={(id) => {
+      // Shared handler - both components can use this
+      console.log('Annotation ready:', id)
+    }}
+  />
+  <SlideViewer
+    imageInfo={{ dziUrl: `.../item/${imageId}/tiles/dzi.dzi` }}
+    annotationIds={annotationState.loadedIds}
+    annotationOpacities={annotationState.opacities}
+    visibleAnnotations={annotationState.visibility}
+    apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+    onAnnotationReady={(id) => console.log('Annotation ready:', id)}
+    height="800px"
+  />
+</>
+```
+
+**Alternative approach:** Using individual callbacks - more verbose but still supported:
+
+```tsx
+const [annotationIds, setAnnotationIds] = useState<string[]>([])
+const [opacities, setOpacities] = useState(new Map<string, number>())
+const imageId = '6903df8dd26a6d93de19a9b2'
+
+<>
+  <AnnotationManager
+    imageId={imageId}
+    apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+    onLoadedAnnotationIdsChange={(ids) => setAnnotationIds(ids)}
+    onAnnotationOpacityChange={(id, opacity) => {
+      setOpacities(prev => new Map(prev).set(id, opacity))
+    }}
+  />
+  <SlideViewer
+    imageInfo={{ dziUrl: `.../item/${imageId}/tiles/dzi.dzi` }}
+    annotationIds={annotationIds}
+    annotationOpacities={opacities}
+    apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+    height="800px"
+  />
+</>
+```
+
+**Legacy approach:** Using `onAnnotationsLoaded` - requires manual ID extraction:
 
 ```tsx
 const [annotationIds, setAnnotationIds] = useState<string[]>([])
@@ -238,6 +308,12 @@ const imageId = '6903df8dd26a6d93de19a9b2'
 </>
 ```
 
+**Additional callbacks available (legacy - prefer `onAnnotationStateChange` for new code):**
+
+- `onAnnotationLoad(id, data?)` - Fires when an annotation is loaded
+- `onAnnotationHide(id)` - Fires when an annotation is hidden/unloaded
+- `onAnnotationOpacityChange(id, opacity)` - Fires when opacity changes
+
 ### 3. FolderBrowser
 
 ```tsx
@@ -279,6 +355,67 @@ const imageId = '6903df8dd26a6d93de19a9b2'
 - Ensure `dist/index.d.ts` exists in the library
 - Restart TypeScript server in your editor (VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server")
 
+## Annotation Caching
+
+The library includes automatic IndexedDB-based caching for annotation documents to speed up loading and reduce server requests.
+
+### Auto-Enabled Caching
+
+Both `AnnotationManager` and `SlideViewer` automatically create and use an `IndexedDBAnnotationCache` instance by default. This provides:
+
+- **Persistent caching** across page refreshes (uses IndexedDB, 50MB+ capacity)
+- **Automatic cache validation** using version hashes from annotation headers
+- **Per-annotation cache indicators** (database icon) when cached
+- **Per-annotation cache bypass** (refresh icon) to clear and reload specific annotations
+
+### Disabling Cache
+
+To disable caching globally for debugging:
+
+```tsx
+<AnnotationManager
+  imageId="..."
+  apiBaseUrl="..."
+  disableCache={true}  // Disables all caching
+/>
+<SlideViewer
+  annotationIds={[...]}
+  disableCache={true}  // Disables all caching
+/>
+```
+
+### Cache Implementation
+
+```tsx
+import { IndexedDBAnnotationCache, MemoryAnnotationCache } from 'bdsa-react-components'
+
+// Use a specific cache implementation (optional)
+const cache = new IndexedDBAnnotationCache()
+<AnnotationManager annotationCache={cache} ... />
+<SlideViewer annotationCache={cache} ... />
+```
+
+### Cache Utilities
+
+```tsx
+import { checkIndexedDBQuota, requestPersistentStorage, logQuotaInfo } from 'bdsa-react-components'
+
+// Check cache quota and usage
+const quotaInfo = await checkIndexedDBQuota()
+if (quotaInfo) {
+  console.log(`Usage: ${quotaInfo.usagePercent.toFixed(1)}%`)
+  console.log(`Available: ${quotaInfo.available} bytes`)
+}
+
+// Request persistent storage (prevents browser cleanup)
+await requestPersistentStorage()
+
+// Log quota info in readable format
+await logQuotaInfo()
+```
+
+**Note:** IndexedDB storage limits are automatically managed by the browser. When quota is exceeded, the browser will prompt the user for permission to expand storage.
+
 ## Dependencies
 
 **Peer:** react ^18.0.0, react-dom ^18.0.0

package/dist/components/AnnotationManager/AnnotationManager.d.ts

@@ -47,6 +47,60 @@ export interface AnnotationManagerProps {
     onAnnotationOpacityChange?: (annotationId: string, opacity: number) => void;
     /** Callback when annotation has finished loading and is ready (called by SlideViewer after rendering) */
     onAnnotationReady?: (annotationId: string) => void;
+    /**
+     * Callback fired whenever the list of loaded annotation IDs changes.
+     * This is called when:
+     * - User clicks "Load" on an annotation
+     * - User clicks "Hide" on an annotation
+     * - Annotations are unloaded
+     *
+     * @param annotationIds - Array of currently loaded annotation IDs
+     */
+    onLoadedAnnotationIdsChange?: (annotationIds: string[]) => void;
+    /**
+     * Callback fired when an individual annotation is loaded.
+     * Useful for tracking which specific annotation was just loaded.
+     *
+     * @param annotationId - The ID of the annotation that was loaded
+     * @param annotationData - The full annotation document (optional, for performance)
+     */
+    onAnnotationLoad?: (annotationId: string, annotationData?: unknown) => void;
+    /**
+     * Callback fired when an individual annotation is hidden/unloaded.
+     *
+     * @param annotationId - The ID of the annotation that was hidden
+     */
+    onAnnotationHide?: (annotationId: string) => void;
+    /**
+     * Callback fired whenever annotation state changes.
+     * Provides complete state snapshot - annotation IDs, opacities, visibility, etc.
+     * This is the primary way to sync with SlideViewer and eliminates the need for
+     * multiple individual callbacks.
+     *
+     * This callback fires whenever:
+     * - An annotation is loaded/unloaded
+     * - Annotation opacity changes
+     * - Annotation visibility changes
+     *
+     * @param state - Complete annotation state snapshot
+     */
+    onAnnotationStateChange?: (state: {
+        /** Array of currently loaded annotation IDs */
+        loadedAnnotationIds: string[];
+        /** Map of annotation ID -> opacity (0.0 to 1.0) */
+        opacities: Map<string, number>;
+        /** Map of annotation ID -> visibility (true = visible, false = hidden) */
+        visibility: Map<string, boolean>;
+    }) => void;
+    /**
+     * Callback fired whenever any annotation opacity changes.
+     * Provides complete map of all opacities - convenience alternative to individual callbacks.
+     *
+     * This is a convenience callback. For complete state sync, use `onAnnotationStateChange` instead.
+     *
+     * @param opacities - Map of all annotation ID -> opacity values
+     */
+    onAnnotationOpacitiesChange?: (opacities: Map<string, number>) => void;
     /** Map of annotation IDs to their loaded state */
     loadedAnnotations?: Set<string>;
     /** Map of annotation IDs to their visibility state */

package/dist/components/AnnotationManager/AnnotationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnnotationManager.d.ts","sourceRoot":"","sources":["../../../src/components/AnnotationManager/AnnotationManager.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"AnnotationManager.d.ts","sourceRoot":"","sources":["../../../src/components/AnnotationManager/AnnotationManager.tsx"],"names":[],"mappings":"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"}