bdsa-react-components 0.1.2 → 0.1.3

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.3 | **Generated:** 2025-11-01T22:49:22.223Z
 
 > 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,33 @@ const fetchWithAuth = async (url: string, options?: RequestInit) => {
 />
 ```
 
-### 2. SlideViewer with API-Fetched Annotations
+### 2. SlideViewer with API-Fetched Annotations (RECOMMENDED)
+
+**Recommended approach:** Use `onLoadedAnnotationIdsChange` to sync annotation state:
+
+```tsx
+const [annotationIds, setAnnotationIds] = useState<string[]>([])
+const imageId = '6903df8dd26a6d93de19a9b2'
+
+<>
+  <AnnotationManager
+    imageId={imageId}
+    apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+    onLoadedAnnotationIdsChange={(ids) => {
+      // Automatically syncs when user loads/unloads annotations
+      setAnnotationIds(ids)
+    }}
+  />
+  <SlideViewer
+    imageInfo={{ dziUrl: `.../item/${imageId}/tiles/dzi.dzi` }}
+    annotationIds={annotationIds}
+    apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+    height="800px"
+  />
+</>
+```
+
+**Alternative (legacy):** Using `onAnnotationsLoaded` - requires manual ID extraction:
 
 ```tsx
 const [annotationIds, setAnnotationIds] = useState<string[]>([])
@@ -238,6 +264,12 @@ const imageId = '6903df8dd26a6d93de19a9b2'
 </>
 ```
 
+**Additional callbacks available:**
+
+- `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 +311,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,30 @@ 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;
     /** 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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"}