bdsa-react-components 0.1.20 → 0.1.22

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.20] - 2025-11-12
+
+### Added - Debug Mode for Clean Console Output 🔇
+
+#### Debug Logging System
+- **New `debug` prop** added to all major components:
+  - `FolderBrowser` - `debug?: boolean` (default: `false`)
+  - `SlideViewer` - `debug?: boolean` (default: `false`)
+  - `AnnotationManager` - `debug?: boolean` (default: `false`)
+- **All `console.log()` calls now respect debug flag** - no console spam in production
+- **`console.error()` always logs** - important errors still visible
+- **New utility**: `createDebugLogger(componentName, debug)` for custom debug logging
+- **Exported types**: `DebugLogger` interface for TypeScript support
+
+#### Benefits
+- ✅ **Clean console by default** - No more debug log spam in production apps
+- ✅ **Opt-in debugging** - Enable `debug={true}` when troubleshooting
+- ✅ **Backward compatible** - Existing code works unchanged (just cleaner output)
+- ✅ **Prefixed logs** - Easy to identify which component logged what
+
+#### Usage
+```typescript
+// Production (no console spam)
+<FolderBrowser apiBaseUrl="..." />
+
+// Development/debugging
+<FolderBrowser apiBaseUrl="..." debug={true} />
+```
+
+### Changed
+- **Default behavior**: Console logs are now suppressed by default (was always on)
+- This is a **non-breaking change** - existing code works the same, just cleaner
+
 ## [0.1.19] - 2025-11-10
 
 ### Added - Major UX Improvements and AI Model Detection 🚀
@@ -427,3 +460,36 @@ None - all changes are backward compatible.
 - Initial project setup
 - Basic project structure
 - Build configuration
+
+
+### Changed
+- Improved SlideViewer component cleanup and error handling
+- Enhanced AnnotationManager state management to prevent infinite loops
+
+### Fixed
+- Fixed `_transformBounds` error in consuming applications
+- Fixed race conditions in annotation state updates
+- Fixed loading state not clearing properly in AnnotationManager
+- Fixed annotation rendering issues when toggling visibility
+
+## [0.1.11] - 2025-11-04
+
+### Added
+- SlideViewer component with OpenSeadragon integration
+- AnnotationManager component for DSA annotations
+- FolderBrowser component for navigating DSA resources
+- Annotation caching system (Memory and IndexedDB)
+- Button and Card components
+
+### Changed
+- Initial component library setup
+- Added TypeScript support
+- Configured Vite build system
+- Set up Storybook for component documentation
+
+## [0.1.0] - 2025-11-01
+
+### Added
+- Initial project setup
+- Basic project structure
+- Build configuration

package/CURSOR_INTEGRATION.md

@@ -1,6 +1,6 @@
 # bdsa-react-components - CURSOR Integration Guide
 
-**Version:** 0.1.20 | **Generated:** 2025-11-12T21:56:05.713Z
+**Version:** 0.1.22 | **Generated:** 2025-11-19T15:48:44.677Z
 
 > 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.
@@ -42,7 +42,7 @@ npm run build
 ### Import
 
 ```tsx
-import { AnnotationManager, Button, Card, DsaAuthManager, FolderBrowser, SlideViewer } from 'bdsa-react-components'
+import { AnnotationManager, Button, Card, DsaAuthManager, FolderBrowser, FolderThumbnailBrowser, SlideViewer, ThumbnailGrid, ThumbnailViewer } from 'bdsa-react-components'
 import 'bdsa-react-components/styles.css'
 ```
 
@@ -120,6 +120,40 @@ FolderBrowser component
 - `GET /collection` - List collections
 - `GET /folder?parentType={type}&parentId={id}` - List folders
 
+### FolderThumbnailBrowser
+
+Size presets for thumbnails
+
+**Example:**
+
+```tsx
+<FolderThumbnailBrowser
+  apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+  folderId="6903df87d26a6d93de19a9b0"
+  viewerSize="l"
+  itemsPerPage={12}
+  showViewerControls={false}
+  selectedAnnotationName="Gray White Segmentation"
+  annotationOpacity={0.7}
+  onAnnotationOpacityChange={(opacity) => console.log(opacity)}
+/>
+```
+
+**Features:**
+
+- Displays thumbnails using OpenSeadragon (full viewer with zoom/pan)
+- Supports annotation overlays with opacity control
+- Automatic pagination based on container size
+- Size presets: 's' (120px), 'm' (180px), 'l' (240px), 'xl' (320px)
+- Authentication via `apiHeaders` or `fetchFn`
+- Token query parameter support via `tokenQueryParam` prop
+
+**API Endpoints:**
+
+- `GET /item?folderId={id}` - Fetch items from folder
+- `GET /item/{id}/tiles/dzi.dzi` - DZI descriptor for thumbnail
+- `GET /annotation?itemId={id}` - Fetch annotations for item
+
 ### SlideViewer
 
 A slide viewer component that integrates OpenSeadragon with Paper.js annotations for viewing Digital Slide Archive images with annotation overlays.
@@ -140,6 +174,42 @@ A slide viewer component that integrates OpenSeadragon with Paper.js annotations
 
 - `GET /annotation/{id}` - Fetch annotation document by ID
 
+### ThumbnailGrid
+
+Size presets for thumbnails
+
+**Example:**
+
+```tsx
+<ThumbnailGrid
+  apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+  folderId="6903df87d26a6d93de19a9b0"
+  thumbnailSize="l"
+  itemsPerPage={12}
+  tokenQueryParam={true}
+  apiHeaders={{ 'Girder-Token': token }}
+  onThumbnailClick={(item) => console.log(item)}
+/>
+```
+
+**Features:**
+
+- Lightweight thumbnail grid (static images, no OpenSeadragon)
+- Faster loading for simple thumbnail browsing
+- Automatic pagination based on container size
+- Size presets: 's' (120px), 'm' (180px), 'l' (240px), 'xl' (320px)
+- Thumbnail URLs include `?width={size}` for optimized loading
+- Authentication via `apiHeaders` with optional `tokenQueryParam`
+
+**API Endpoints:**
+
+- `GET /item?folderId={id}` - Fetch items from folder
+- `GET /item/{id}/tiles/thumbnail?width={size}&token={token}` - Thumbnail image
+
+### ThumbnailViewer
+
+Individual thumbnail component that wraps SlideViewer for displaying a single DSA item with optional annotation overlay.
+
 ## Type Definitions
 
 Import types:
@@ -161,24 +231,14 @@ import type {
   Item as FolderBrowserItem,
   Resource,
   DsaAuthManagerProps,
+  FolderThumbnailBrowserProps,
+  ThumbnailViewerProps,
+  ThumbnailGridProps,
 } from 'bdsa-react-components'
 ```
 
 ### Key Types
 
-**SlideImageInfo:**
-```typescript
-interface SlideImageInfo {
-  imageId?: string | number
-  width?: number
-  height?: number
-  tileWidth?: number
-  levels?: number
-  baseUrl?: string
-  http: //bdsa.pathology.emory.edu:8080/api/v1/item/{itemId
-}
-```
-
 ## Authentication
 
 Components making API calls (`SlideViewer`, `AnnotationManager`, `FolderBrowser`) support auth via:

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

@@ -1,190 +1,7 @@
 import { default as React } from 'react';
+import { AnnotationSearchResult, AnnotationManagerProps, AnnotationManagerHandle, AnnotationManagerContext } from './AnnotationManager.types';
 
-export interface AnnotationSearchResult {
-    _id: string;
-    _modelType: string;
-    _elementCount?: number;
-    _detailsCount?: number;
-    _version?: number;
-    _accessLevel?: number;
-    itemId?: string;
-    public?: boolean;
-    created?: string;
-    updated?: string;
-    creatorId?: string;
-    updatedId?: string;
-    groups?: (string | null)[];
-    annotation?: {
-        name?: string;
-        description?: string;
-        attributes?: Record<string, unknown>;
-        display?: Record<string, unknown>;
-    };
-    [key: string]: unknown;
-}
-export interface AnnotationManagerProps {
-    /** Image/Item ID to search annotations for */
-    imageId?: string;
-    /** Base URL for DSA API (e.g., http://bdsa.pathology.emory.edu:8080/api/v1) */
-    apiBaseUrl?: string;
-    /** Maximum number of annotations to fetch per request (default: 50) */
-    limit?: number;
-    /** Custom fetch function for API requests. Useful for adding authentication headers. */
-    fetchFn?: (url: string, options?: RequestInit) => Promise<Response>;
-    /** Custom headers to add to all API requests. Merged with fetchFn headers if both are provided. */
-    apiHeaders?: HeadersInit;
-    /** Callback when annotations are loaded */
-    onAnnotationsLoaded?: (annotations: AnnotationSearchResult[]) => void;
-    /** Callback when annotation loading fails */
-    onError?: (error: Error) => void;
-    /** Show debug panel with raw API response (default: false, hidden in production) */
-    showDebugPanel?: boolean;
-    /** Callback when annotation is loaded/unloaded */
-    onAnnotationLoadChange?: (annotationId: string, loaded: boolean) => void;
-    /** Callback when annotation visibility is toggled */
-    onAnnotationVisibilityChange?: (annotationId: string, visible: boolean) => void;
-    /** Callback when annotation opacity changes */
-    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 from SlideViewer that should be called when annotations are ready.
-     * This simplifies integration - just pass the same callback function to both
-     * AnnotationManager and SlideViewer. AnnotationManager will handle forwarding
-     * internally to clear loading states.
-     *
-     * Use this instead of the render prop pattern for simpler integration.
-     */
-    slideViewerOnAnnotationReady?: (annotationId: string | number) => 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>;
-        /** Callback function that should be passed to SlideViewer's onAnnotationReady prop.
-         * This automatically clears loading states in AnnotationManager when called. */
-        onAnnotationReady?: (annotationId: string | number) => void;
-    }) => 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;
-    /**
-     * Callback fired whenever annotation headers change.
-     * Provides a map of annotation ID -> header document.
-     *
-     * This eliminates the need to extract headers from the render prop pattern.
-     * Use this to automatically sync annotationHeaders to SlideViewer.
-     *
-     * @param headers - Map of annotation ID -> annotation header document
-     */
-    onAnnotationHeadersChange?: (headers: Map<string | number, AnnotationSearchResult>) => void;
-    /** Map of annotation IDs to their loaded state */
-    loadedAnnotations?: Set<string>;
-    /** Map of annotation IDs to their visibility state */
-    visibleAnnotations?: Map<string, boolean>;
-    /** Map of annotation IDs to their opacity (0-1) */
-    annotationOpacities?: Map<string, number>;
-    /** Optional cache instance to check if annotations are cached locally. If not provided, automatically creates an IndexedDBAnnotationCache.
-     * Set to `null` to disable caching. If provided, will show a cache indicator icon when annotations are cached. */
-    annotationCache?: {
-        has(annotationId: string | number, versionHash?: string): Promise<boolean>;
-        delete?(annotationId: string | number): Promise<void>;
-    } | null;
-    /** If true, disables caching entirely (equivalent to annotationCache={null}). Useful for debugging or forcing fresh fetches. */
-    disableCache?: boolean;
-    /** Show default vertical UI (default: true). Set to false to use custom render prop. */
-    showDefaultUI?: boolean;
-    className?: string;
-    children?: React.ReactNode | ((context: {
-        annotations: AnnotationSearchResult[];
-        loading: boolean;
-        error: Error | null;
-        annotationIds: string[];
-        loadedAnnotations: Set<string>;
-        visibleAnnotations: Map<string, boolean>;
-        annotationOpacities: Map<string, number>;
-        toggleLoad: (annotationId: string) => void;
-        toggleVisibility: (annotationId: string) => void;
-        setOpacity: (annotationId: string, opacity: number) => void;
-        onAnnotationReady: (annotationId: string | number) => void;
-    }) => React.ReactNode);
-    /** If true, enables debug logging to console. Default: false */
-    debug?: boolean;
-}
-/**
- * Imperative handle interface for AnnotationManager.
- * Allows parent components to query annotation state programmatically.
- */
-export interface AnnotationManagerHandle {
-    /** Get all available annotations */
-    getAnnotations: () => AnnotationSearchResult[];
-    /** Get annotation by ID */
-    getAnnotation: (id: string) => AnnotationSearchResult | undefined;
-    /** Get all loaded annotation IDs */
-    getLoadedAnnotationIds: () => string[];
-    /** Check if an annotation is loaded */
-    isAnnotationLoaded: (id: string) => boolean;
-    /** Check if an annotation is visible */
-    isAnnotationVisible: (id: string) => boolean;
-    /** Get opacity for an annotation (0-1) */
-    getAnnotationOpacity: (id: string) => number;
-    /** Get loading state for an annotation */
-    isAnnotationLoading: (id: string) => boolean;
-    /** Get all visible annotation IDs */
-    getVisibleAnnotationIds: () => string[];
-    /** Get complete annotation state snapshot */
-    getAnnotationState: () => {
-        loadedAnnotationIds: string[];
-        opacities: Map<string, number>;
-        visibility: Map<string, boolean>;
-        loadingAnnotationIds: string[];
-    };
-}
+export type { AnnotationSearchResult, AnnotationManagerProps, AnnotationManagerHandle, AnnotationManagerContext };
 /**
  * AnnotationManager component for managing annotation loading, visibility, and state.
  * This component handles the business logic for annotations while keeping SlideViewer

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":"AAAA,OAAO,KAAiF,MAAM,OAAO,CAAA;AAGrG,OAAO,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAElJ,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,CAAA;AAEjH;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,wGAq2B7B,CAAA"}

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

@@ -0,0 +1,120 @@
+import { default as React } from 'react';
+import { IndexedDBAnnotationCache } from '../../cache';
+
+export interface AnnotationSearchResult {
+    _id: string;
+    _modelType: string;
+    _elementCount?: number;
+    _detailsCount?: number;
+    _version?: number;
+    _accessLevel?: number;
+    itemId?: string;
+    public?: boolean;
+    created?: string;
+    updated?: string;
+    creatorId?: string;
+    updatedId?: string;
+    groups?: (string | null)[];
+    annotation?: {
+        name?: string;
+        description?: string;
+        attributes?: Record<string, unknown>;
+        display?: Record<string, unknown>;
+    };
+    [key: string]: unknown;
+}
+export interface AnnotationManagerProps {
+    /** Image/Item ID to search annotations for */
+    imageId?: string;
+    /** Base URL for DSA API (e.g., http://bdsa.pathology.emory.edu:8080/api/v1) */
+    apiBaseUrl?: string;
+    /** Maximum number of annotations to fetch per request (default: 50) */
+    limit?: number;
+    /** Custom fetch function for API requests. Useful for adding authentication headers. */
+    fetchFn?: (url: string, options?: RequestInit) => Promise<Response>;
+    /** Custom headers to add to all API requests. Merged with fetchFn headers if both are provided. */
+    apiHeaders?: HeadersInit;
+    /** Callback when annotations are loaded */
+    onAnnotationsLoaded?: (annotations: AnnotationSearchResult[]) => void;
+    /** Callback when annotation loading fails */
+    onError?: (error: Error) => void;
+    /** Show debug panel with raw API response (default: false, hidden in production) */
+    showDebugPanel?: boolean;
+    /** Callback when annotation is loaded/unloaded */
+    onAnnotationLoadChange?: (annotationId: string, loaded: boolean) => void;
+    /** Callback when annotation visibility is toggled */
+    onAnnotationVisibilityChange?: (annotationId: string, visible: boolean) => void;
+    /** Callback when annotation opacity changes */
+    onAnnotationOpacityChange?: (annotationId: string, opacity: number) => void;
+    /** Callback when annotation is ready (fully rendered) */
+    onAnnotationReady?: (annotationId: string) => void;
+    /** Callback for SlideViewer's onAnnotationReady (internal use) */
+    slideViewerOnAnnotationReady?: (annotationId: string | number) => void;
+    /** Callback when loaded annotation IDs change */
+    onLoadedAnnotationIdsChange?: (annotationIds: string[]) => void;
+    /** Callback when annotation is loaded */
+    onAnnotationLoad?: (annotationId: string) => void;
+    /** Callback when annotation is hidden */
+    onAnnotationHide?: (annotationId: string) => void;
+    /** Unified callback for annotation state changes */
+    onAnnotationStateChange?: (state: {
+        loadedAnnotationIds: string[];
+        opacities: Map<string, number>;
+        visibility: Map<string, boolean>;
+        onAnnotationReady?: (id: string | number) => void;
+    }) => void;
+    /** Callback when annotation opacities change */
+    onAnnotationOpacitiesChange?: (opacities: Map<string, number>) => void;
+    /** Callback when annotation headers change */
+    onAnnotationHeadersChange?: (headers: Map<string | number, AnnotationSearchResult>) => void;
+    /** External state: loaded annotation IDs */
+    loadedAnnotations?: Set<string>;
+    /** External state: visible annotation IDs */
+    visibleAnnotations?: Map<string, boolean>;
+    /** External state: annotation opacities */
+    annotationOpacities?: Map<string, number>;
+    /** External annotation cache */
+    annotationCache?: IndexedDBAnnotationCache | null;
+    /** Disable annotation caching (default: false) */
+    disableCache?: boolean;
+    /** Show default UI (default: true) */
+    showDefaultUI?: boolean;
+    /** Custom CSS class name */
+    className?: string;
+    /** Custom render function (render prop) */
+    children?: ((context: AnnotationManagerContext) => React.ReactNode) | React.ReactNode;
+    /** If true, enables debug logging to console. Default: false */
+    debug?: boolean;
+}
+export interface AnnotationManagerContext {
+    annotations: AnnotationSearchResult[];
+    loading: boolean;
+    error: Error | null;
+    annotationIds: string[];
+    loadedAnnotations: Set<string>;
+    visibleAnnotations: Map<string, boolean>;
+    annotationOpacities: Map<string, number>;
+    toggleLoad: (annotationId: string) => void;
+    toggleVisibility: (annotationId: string) => void;
+    setOpacity: (annotationId: string, opacity: number) => void;
+    handleAnnotationReady: (id: string | number) => void;
+    onAnnotationReady: (id: string | number) => void;
+    loadingAnnotations: Set<string>;
+}
+export interface AnnotationManagerHandle {
+    getAnnotations: () => AnnotationSearchResult[];
+    getAnnotation: (id: string) => AnnotationSearchResult | undefined;
+    getLoadedAnnotationIds: () => string[];
+    isAnnotationLoaded: (id: string) => boolean;
+    isAnnotationVisible: (id: string) => boolean;
+    getAnnotationOpacity: (id: string) => number;
+    isAnnotationLoading: (id: string) => boolean;
+    getVisibleAnnotationIds: () => string[];
+    getAnnotationState: () => {
+        loadedAnnotationIds: string[];
+        opacities: Map<string, number>;
+        visibility: Map<string, boolean>;
+        loadingAnnotationIds: string[];
+    };
+}
+//# sourceMappingURL=AnnotationManager.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnnotationManager.types.d.ts","sourceRoot":"","sources":["../../../src/components/AnnotationManager/AnnotationManager.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAE3D,MAAM,WAAW,sBAAsB;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAA;IAC1B,UAAU,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACpC,CAAA;IACD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,sBAAsB;IACnC,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wFAAwF;IACxF,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnE,mGAAmG;IACnG,UAAU,CAAC,EAAE,WAAW,CAAA;IACxB,2CAA2C;IAC3C,mBAAmB,CAAC,EAAE,CAAC,WAAW,EAAE,sBAAsB,EAAE,KAAK,IAAI,CAAA;IACrE,6CAA6C;IAC7C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAChC,oFAAoF;IACpF,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,kDAAkD;IAClD,sBAAsB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;IACxE,qDAAqD;IACrD,4BAA4B,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAC/E,+CAA+C;IAC/C,yBAAyB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3E,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IAClD,kEAAkE;IAClE,4BAA4B,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAA;IACtE,iDAAiD;IACjD,2BAA2B,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IAC/D,yCAAyC;IACzC,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IACjD,yCAAyC;IACzC,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IACjD,oDAAoD;IACpD,uBAAuB,CAAC,EAAE,CAAC,KAAK,EAAE;QAC9B,mBAAmB,EAAE,MAAM,EAAE,CAAA;QAC7B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAChC,iBAAiB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAA;KACpD,KAAK,IAAI,CAAA;IACV,gDAAgD;IAChD,2BAA2B,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAA;IACtE,8CAA8C;IAC9C,yBAAyB,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,sBAAsB,CAAC,KAAK,IAAI,CAAA;IAC3F,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,2CAA2C;IAC3C,mBAAmB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC,gCAAgC;IAChC,eAAe,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAA;IACjD,kDAAkD;IAClD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,sCAAsC;IACtC,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,wBAAwB,KAAK,KAAK,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,SAAS,CAAA;IACrF,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,wBAAwB;IACrC,WAAW,EAAE,sBAAsB,EAAE,CAAA;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC9B,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,UAAU,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,gBAAgB,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD,UAAU,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3D,qBAAqB,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAA;IACpD,iBAAiB,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAA;IAChD,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAClC;AAED,MAAM,WAAW,uBAAuB;IACpC,cAAc,EAAE,MAAM,sBAAsB,EAAE,CAAA;IAC9C,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,sBAAsB,GAAG,SAAS,CAAA;IACjE,sBAAsB,EAAE,MAAM,MAAM,EAAE,CAAA;IACtC,kBAAkB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAA;IAC3C,mBAAmB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAA;IAC5C,oBAAoB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAA;IAC5C,mBAAmB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAA;IAC5C,uBAAuB,EAAE,MAAM,MAAM,EAAE,CAAA;IACvC,kBAAkB,EAAE,MAAM;QACtB,mBAAmB,EAAE,MAAM,EAAE,CAAA;QAC7B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAChC,oBAAoB,EAAE,MAAM,EAAE,CAAA;KACjC,CAAA;CACJ"}

package/dist/components/FolderBrowser/FolderBrowser.d.ts

@@ -1,122 +1,7 @@
 import { default as React } from 'react';
+import { Collection, Folder, Item, Resource, FolderBrowserProps } from './FolderBrowser.types';
 
-export interface Collection {
-    _id: string;
-    name: string;
-    description?: string;
-    public?: boolean;
-    created?: string;
-    updated?: string;
-    [key: string]: unknown;
-}
-export interface Folder {
-    _id: string;
-    name: string;
-    description?: string;
-    public?: boolean;
-    created?: string;
-    updated?: string;
-    parentId?: string;
-    parentType?: 'collection' | 'folder';
-    [key: string]: unknown;
-}
-export interface Item {
-    _id: string;
-    name: string;
-    description?: string;
-    folderId?: string;
-    collectionId?: string;
-    public?: boolean;
-    created?: string;
-    updated?: string;
-    [key: string]: unknown;
-}
-export type Resource = (Collection | Folder | Item) & {
-    type: 'collection' | 'folder' | 'item';
-};
-export interface FolderBrowserProps {
-    /** Base URL for DSA API (e.g., http://bdsa.pathology.emory.edu:8080/api/v1) */
-    apiBaseUrl?: string;
-    /** Custom fetch function for API requests. Useful for adding authentication headers. */
-    fetchFn?: (url: string, options?: RequestInit) => Promise<Response>;
-    /** Custom headers to add to all API requests. Merged with fetchFn headers if both are provided. */
-    apiHeaders?: HeadersInit;
-    /** Callback when a resource (collection or folder) is selected */
-    onResourceSelect?: (resource: Resource) => void;
-    /** Callback when resource selection changes */
-    onSelectionChange?: (resource: Resource | null) => void;
-    /** Show collections at the root level (default: true, ignored if rootId is provided) */
-    showCollections?: boolean;
-    /** Root directory ID to start from (if provided, only shows this collection/folder and its children) */
-    rootId?: string;
-    /** Type of root directory - 'collection' or 'folder' (required if rootId is provided) */
-    rootType?: 'collection' | 'folder';
-    /** Number of folders to load per page (default: 50, set to 0 to load all) */
-    foldersPerPage?: number;
-    /** Start at a specific collection ID instead of showing all collections (deprecated: use rootId and rootType) */
-    startCollectionId?: string;
-    /** Start at a specific folder ID (requires startCollectionId or parentFolderId) (deprecated: use rootId and rootType) */
-    startFolderId?: string;
-    /** Start at a folder's subfolder (requires parentFolderId) (deprecated: use rootId and rootType) */
-    parentFolderId?: string;
-    className?: string;
-    /** Custom render for collections */
-    renderCollection?: (collection: Collection, isExpanded: boolean, onToggle: () => void, itemCount?: number) => React.ReactNode;
-    /** Custom render for folders */
-    renderFolder?: (folder: Folder, depth: number, isExpanded: boolean, onToggle: () => void, itemCount?: number) => React.ReactNode;
-    /** If true, shows items (files) within folders and collections in the tree view. Default: false */
-    showItems?: boolean;
-    /** If true, fetches items from folders even if showItems is false. Useful for getting item counts or filtering. Default: value of showItems */
-    fetchItems?: boolean;
-    /** Number of items to load per page when items are fetched (default: 50, set to 0 to load all) */
-    itemsPerPage?: number;
-    /** Callback when an item is selected (only used when showItems is true) */
-    onItemSelect?: (item: Item) => void;
-    /** Custom render for items */
-    renderItem?: (item: Item, depth: number) => React.ReactNode;
-    /**
-     * Filter function for items. Called for each item fetched from API.
-     * Return true to include the item, false to exclude it.
-     * Receives the full Item object, so you can filter by name, extension, metadata, or any other property.
-     *
-     * ⚠️ IMPORTANT: This function must be stable (wrapped in useCallback) to prevent infinite re-renders.
-     *
-     * @example
-     * // Filter by extension
-     * const itemFilter = useCallback((item) => {
-     *   return item.name.endsWith('.jpg') || item.name.endsWith('.png');
-     * }, []);
-     *
-     * @example
-     * // Filter by metadata
-     * const itemFilter = useCallback((item) => {
-     *   return item.meta?.type === 'model' && item.meta?.status === 'published';
-     * }, []);
-     *
-     * @example
-     * // Combine name and metadata filters
-     * const itemFilter = useCallback((item) => {
-     *   const hasValidExtension = item.name.endsWith('.tif') || item.name.endsWith('.svs');
-     *   const hasLargeImage = item.largeImage != null;
-     *   return hasValidExtension && hasLargeImage;
-     * }, []);
-     */
-    itemFilter?: (item: Item) => boolean;
-    /** Callback when items are fetched for a folder. Receives folder/collection ID and all fetched items (before filtering). */
-    onItemsFetched?: (folderId: string, items: Item[]) => void;
-    /** If true, shows item count next to folder/collection names. Default: false */
-    showItemCount?: boolean;
-    /** If true, persists the selected resource to localStorage and restores it on mount. Default: false */
-    persistSelection?: boolean;
-    /** Custom key for localStorage persistence. Default: 'bdsa_folder_browser_selection' */
-    persistSelectionKey?: string;
-    /** If true, persists the expansion state (which folders/collections are expanded) to localStorage and restores it on mount. Default: false */
-    persistExpansion?: boolean;
-    /** Custom key for localStorage expansion state persistence. Default: 'bdsa_folder_browser_expansion' */
-    persistExpansionKey?: string;
-    /** If true, enables debug logging to console. Default: false */
-    debug?: boolean;
-}
+export type { Collection, Folder, Item, Resource, FolderBrowserProps };
 /**
  * FolderBrowser component for browsing DSA collections and folders.
  *