bdsa-react-components 0.1.3 → 0.1.4

package/CURSOR_INTEGRATION.md

@@ -1,6 +1,6 @@
 # bdsa-react-components - CURSOR Integration Guide
 
-**Version:** 0.1.3 | **Generated:** 2025-11-01T22:49:22.223Z
+**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.
@@ -219,31 +219,75 @@ const fetchWithAuth = async (url: string, options?: RequestInit) => {
 
 ### 2. SlideViewer with API-Fetched Annotations (RECOMMENDED)
 
-**Recommended approach:** Use `onLoadedAnnotationIdsChange` to sync annotation state:
+**⭐ 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) => {
-      // Automatically syncs when user loads/unloads annotations
-      setAnnotationIds(ids)
+    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"
   />
 </>
 ```
 
-**Alternative (legacy):** Using `onAnnotationsLoaded` - requires manual ID extraction:
+**Legacy approach:** Using `onAnnotationsLoaded` - requires manual ID extraction:
 
 ```tsx
 const [annotationIds, setAnnotationIds] = useState<string[]>([])
@@ -264,7 +308,7 @@ const imageId = '6903df8dd26a6d93de19a9b2'
 </>
 ```
 
-**Additional callbacks available:**
+**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

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

@@ -71,6 +71,36 @@ export interface AnnotationManagerProps {
      * @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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"}