bdsa-react-components 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+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.0] - 2025-10-30
+
+### Added
+- Initial project setup with TypeScript, Vite, and Vitest
+- Storybook configuration for component documentation
+- Button component with variants (primary, secondary, danger, success)
+- Button component with sizes (small, medium, large)
+- Button component with loading state
+- Card component with header and footer support
+- Card component with configurable shadow and padding
+- Comprehensive test suite for all components
+- Storybook stories for all components
+- ESLint configuration
+- TypeScript type definitions
+- Build system for library distribution
+

package/CURSOR_INTEGRATION.md

@@ -0,0 +1,290 @@
+# bdsa-react-components - CURSOR Integration Guide
+
+**Version:** 0.1.0 | **Generated:** 2025-11-01T17:13:05.783Z
+
+> 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.
+> **Auto-generated from source code** - Updated automatically on build.
+
+## Quick Start
+
+### Published Package (when available)
+
+```bash
+npm install bdsa-react-components
+```
+
+### Local Development (npm link)
+
+If the library is local/unpublished, use npm link:
+
+**Step 1:** In the library directory (`bdsaReactComponents`):
+```bash
+npm link
+```
+
+**Step 2:** In your project directory:
+```bash
+npm link bdsa-react-components
+```
+
+**Step 3:** Install peer dependencies in your project (if not already installed):
+```bash
+npm install react@^18.0.0 react-dom@^18.0.0
+```
+
+**Note:** After making changes to the library, rebuild it:
+```bash
+# In library directory
+npm run build
+```
+
+### Import
+
+```tsx
+import { AnnotationManager, Button, Card, FolderBrowser, SlideViewer } from 'bdsa-react-components'
+import 'bdsa-react-components/styles.css'
+```
+
+## Components API
+
+### AnnotationManager
+
+AnnotationManager component
+
+**Example:**
+
+```tsx
+<AnnotationManager
+  imageId="6903df8dd26a6d93de19a9b2"
+  apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+  onAnnotationsLoaded={(anns) => console.log(anns)}
+/>
+```
+
+**API Endpoints:**
+
+- `GET /annotation?itemId={id}&limit={limit}&offset=0` - Search annotations by itemId
+
+### Button
+
+A versatile button component for the BDSA project
+
+**Extends:** `React.ButtonHTMLAttributes<HTMLButtonElement>`
+
+**Props:**
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'primary' \| 'secondary' \| 'danger' \| 'success'` | `'primary'` | No | The variant style of the button |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | No | The size of the button |
+| `fullWidth` | `boolean` | `false` | No | Whether the button should take the full width of its container |
+| `loading` | `boolean` | `false` | No | Whether the button is in a loading state |
+
+### Card
+
+A flexible card component for the BDSA project
+
+**Extends:** `React.HTMLAttributes<HTMLDivElement>`
+
+**Props:**
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `header` | `React.ReactNode` | `undefined` | No | Optional header content |
+| `footer` | `React.ReactNode` | `undefined` | No | Optional footer content |
+| `shadow` | `'none' \| 'small' \| 'medium' \| 'large'` | `'small'` | No | Whether the card has a shadow |
+| `bordered` | `boolean` | `true` | No | Whether the card has a border |
+| `hoverable` | `boolean` | `false` | No | Whether the card is hoverable (shows hover effect) |
+| `padding` | `'none' \| 'small' \| 'medium' \| 'large'` | `'medium'` | No | Padding size |
+
+### FolderBrowser
+
+FolderBrowser component
+
+**Example:**
+
+```tsx
+<FolderBrowser
+  apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+  onResourceSelect={(resource) => console.log(resource)}
+/>
+```
+
+**API Endpoints:**
+
+- `GET /collection` - List collections
+- `GET /folder?parentType={type}&parentId={id}` - List folders
+
+### SlideViewer
+
+A slide viewer component that integrates OpenSeadragon with Paper.js annotations for viewing Digital Slide Archive images with annotation overlays.
+
+**Example:**
+
+```tsx
+<SlideViewer
+  imageInfo={{
+    dziUrl: 'http://bdsa.pathology.emory.edu:8080/api/v1/item/IMAGE_ID/tiles/dzi.dzi'
+  }}
+  annotations={[]}
+  height="800px"
+/>
+```
+
+**API Endpoints:**
+
+- `GET /annotation/{id}` - Fetch annotation document by ID
+
+## Type Definitions
+
+Import types:
+
+```tsx
+import type {
+  ButtonProps,
+  CardProps,
+  SlideViewerProps,
+  SlideImageInfo,
+  AnnotationFeature,
+  AnnotationInfoConfig,
+  AnnotationInfoProperty,
+  AnnotationManagerProps,
+  AnnotationSearchResult,
+  FolderBrowserProps,
+  Collection,
+  Folder,
+  Resource,
+} 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:
+
+1. **`fetchFn` prop:** Custom fetch function `(url: string, options?: RequestInit) => Promise<Response>`
+2. **`apiHeaders` prop:** Headers object `HeadersInit`
+
+**Example:**
+
+```tsx
+const fetchWithAuth = async (url: string, options?: RequestInit) => {
+  return fetch(url, {
+    ...options,
+    headers: {
+      ...options?.headers,
+      'Authorization': `Bearer ${token}`,
+    },
+  })
+}
+
+<SlideViewer
+  imageInfo={{ dziUrl: '...' }}
+  fetchFn={fetchWithAuth}
+  // OR: apiHeaders={{ 'Authorization': `Bearer ${token}` }}
+/>
+```
+
+## Common Integration Patterns
+
+### 1. SlideViewer with Manual Annotations
+
+```tsx
+<SlideViewer
+  imageInfo={{
+    dziUrl: 'http://bdsa.pathology.emory.edu:8080/api/v1/item/IMAGE_ID/tiles/dzi.dzi'
+  }}
+  annotations={[
+    { id: 'ann-1', left: 100, top: 200, width: 150, height: 100, color: '#ff0000' }
+  ]}
+  height="800px"
+  onAnnotationClick={(ann) => console.log(ann)}
+/>
+```
+
+### 2. SlideViewer with API-Fetched Annotations
+
+```tsx
+const [annotationIds, setAnnotationIds] = useState<string[]>([])
+const imageId = '6903df8dd26a6d93de19a9b2'
+
+<>
+  <AnnotationManager
+    imageId={imageId}
+    apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+    onAnnotationsLoaded={(anns) => setAnnotationIds(anns.map(a => a._id))}
+  />
+  <SlideViewer
+    imageInfo={{ dziUrl: `.../item/${imageId}/tiles/dzi.dzi` }}
+    annotationIds={annotationIds}
+    apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+    height="800px"
+  />
+</>
+```
+
+### 3. FolderBrowser
+
+```tsx
+<FolderBrowser
+  apiBaseUrl="http://bdsa.pathology.emory.edu:8080/api/v1"
+  showCollections={true}
+  onResourceSelect={(resource) => console.log(resource)}
+  foldersPerPage={50}
+/>
+```
+
+## Important Notes
+
+- **SlideViewer height:** Must specify explicit `height` prop (e.g., `"600px"`, `"100vh"`) - OpenSeadragon requirement
+- **DZI URL vs Manual:** Provide either `dziUrl` OR all manual fields (`imageId`, `width`, `height`, `tileWidth`, `levels`, `baseUrl`)
+- **Annotations format:** Accepts `AnnotationFeature[]` or GeoJSON `FeatureCollection`
+- **API Base URL:** Format: `http://bdsa.pathology.emory.edu:8080/api/v1` (no trailing slash)
+- **Styles:** Always import `'bdsa-react-components/styles.css'`
+- **Peer deps:** Requires React 18+
+
+## Troubleshooting (npm link)
+
+**"Module not found" error:**
+- Ensure `npm link` was run in the library directory
+- Ensure `npm link bdsa-react-components` was run in your project
+- Check that `node_modules/bdsa-react-components` is a symlink (not a regular folder)
+- Try removing and re-linking: `npm unlink bdsa-react-components && npm link bdsa-react-components`
+
+**Styles not loading:**
+- Ensure you've imported `'bdsa-react-components/styles.css'`
+- Check that the CSS file exists at `node_modules/bdsa-react-components/dist/style.css`
+
+**Changes not appearing:**
+- Rebuild the library: `cd /path/to/bdsaReactComponents && npm run build`
+- Restart your dev server (Vite/CRA/etc) after rebuilding
+- For faster iteration, run `npm run build -- --watch` in the library directory
+
+**TypeScript errors:**
+- Ensure `dist/index.d.ts` exists in the library
+- Restart TypeScript server in your editor (VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server")
+
+## Dependencies
+
+**Peer:** react ^18.0.0, react-dom ^18.0.0
+
+**Direct:** openseadragon ^5.0.1, osd-paperjs-annotation, paper ^0.12.18
+
+---
+
+_Auto-generated from source code - Regenerate with: npm run generate:cursor-doc_

package/INTEGRATION.md

@@ -0,0 +1,189 @@
+# Integration Guide for bdsa-react-components
+
+## Local Development Setup (Using npm link)
+
+### Step 1: Link the library in this repository
+
+From the `bdsaReactComponents` directory:
+
+```bash
+npm link
+```
+
+This creates a global symlink to your library.
+
+### Step 2: Use it in your other React application
+
+In your other React application directory:
+
+```bash
+npm link bdsa-react-components
+```
+
+This creates a symlink from your app's `node_modules` to the library.
+
+### Step 3: Install peer dependencies in your app
+
+Your app needs React 18+:
+
+```bash
+npm install react@^18.0.0 react-dom@^18.0.0
+```
+
+### Step 4: Use the components
+
+```tsx
+import { SlideViewer, Button, Card } from 'bdsa-react-components'
+import 'bdsa-react-components/styles.css'
+
+function App() {
+  return (
+    <div style={{ width: '100%', height: '600px' }}>
+      <SlideViewer
+        imageInfo={{
+          dziUrl: 'http://bdsa.pathology.emory.edu:8080/api/v1/item/YOUR_IMAGE_ID/tiles/dzi.dzi'
+        }}
+        annotations={[]}
+      />
+    </div>
+  )
+}
+```
+
+## Alternative: Using GitHub Repository
+
+### Step 1: Push to GitHub
+
+```bash
+git init
+git add .
+git commit -m "Initial commit"
+git remote add origin https://github.com/YOUR_USERNAME/bdsa-react-components.git
+git push -u origin main
+```
+
+### Step 2: Install from GitHub in your app
+
+```bash
+npm install git+https://github.com/YOUR_USERNAME/bdsa-react-components.git
+```
+
+Or if you want to point to a specific branch:
+
+```bash
+npm install git+https://github.com/YOUR_USERNAME/bdsa-react-components.git#main
+```
+
+## VSCode IntelliSense Setup
+
+The library includes full TypeScript definitions, so VSCode should automatically provide:
+- Autocomplete for component props
+- Type checking
+- Inline documentation
+- Go to definition
+
+If IntelliSense isn't working:
+
+1. **Make sure TypeScript is installed** in your project:
+   ```bash
+   npm install --save-dev typescript @types/react @types/react-dom
+   ```
+
+2. **Restart VSCode** or reload the window (Cmd+Shift+P → "Reload Window")
+
+3. **Check VSCode TypeScript version**: 
+   - Open a `.tsx` file
+   - Click the TypeScript version in the bottom right
+   - Select "Use Workspace Version"
+
+## Component Usage Examples
+
+### SlideViewer
+
+```tsx
+import { SlideViewer } from 'bdsa-react-components'
+import 'bdsa-react-components/styles.css'
+
+function MySlideView() {
+  const imageInfo = {
+    dziUrl: 'http://bdsa.pathology.emory.edu:8080/api/v1/item/6903df8dd26a6d93de19a9b2/tiles/dzi.dzi'
+  }
+
+  const annotations = [
+    {
+      id: 'ann-1',
+      left: 5000,
+      top: 6000,
+      width: 2000,
+      height: 1500,
+      color: '#ff0000',
+      label: 'Region of Interest'
+    }
+  ]
+
+  return (
+    <SlideViewer
+      imageInfo={imageInfo}
+      annotations={annotations}
+      height="800px"
+      onAnnotationClick={(annotation) => {
+        console.log('Clicked:', annotation)
+      }}
+    />
+  )
+}
+```
+
+### Button
+
+```tsx
+import { Button } from 'bdsa-react-components'
+import 'bdsa-react-components/styles.css'
+
+<Button variant="primary" size="large" onClick={() => alert('Clicked!')}>
+  Click Me
+</Button>
+```
+
+### Card
+
+```tsx
+import { Card } from 'bdsa-react-components'
+import 'bdsa-react-components/styles.css'
+
+<Card header="Title" footer="Footer" shadow="medium" hoverable>
+  Content here
+</Card>
+```
+
+## Troubleshooting
+
+### "Module not found" error
+
+Make sure you've:
+1. Run `npm link` in the library directory
+2. Run `npm link bdsa-react-components` in your app directory
+3. Installed peer dependencies (`react`, `react-dom`)
+
+### Styles not loading
+
+Don't forget to import the CSS:
+```tsx
+import 'bdsa-react-components/styles.css'
+```
+
+### OpenSeadragon not working
+
+Make sure the SlideViewer has an explicit height:
+```tsx
+<SlideViewer height="600px" ... />
+```
+
+## Hot Reloading with npm link
+
+If you make changes to the library:
+1. Rebuild: `npm run build` in the library directory
+2. Your app should automatically pick up changes (if using Vite/CRA with watch mode)
+
+For faster development, you can run `npm run build -- --watch` in one terminal while developing.
+