@inovusmedical/avatar 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,386 @@
-# Temporary Holding Version
+# @inovusmedical/avatar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components and hooks for user avatars in the Totum app ecosystem.
+
+Uses the shared `user_data` Supabase project directly via Third-Party Auth with Cognito.
+
+## Installation
+
+```bash
+npm install @inovusmedical/avatar
+# or
+pnpm add @inovusmedical/avatar
+```
+
+## Peer Dependencies
+
+- `react` ^18.0.0 || ^19.0.0
+- `react-dom` ^18.0.0 || ^19.0.0
+- `@tanstack/react-query` ^5.0.0
+- `@supabase/supabase-js` ^2.0.0
+
+## Quick Start
+
+### 1. Add the Provider
+
+Wrap your app with `AvatarProvider`:
+
+```tsx
+import { AvatarProvider } from '@inovusmedical/avatar';
+import '@inovusmedical/avatar/styles';
+import { getAccessToken } from '@inovusmedical/unified-auth';
+
+function App() {
+  return (
+    <AvatarProvider
+      supabaseAnonKey={import.meta.env.VITE_USER_DATA_ANON_KEY}
+      getAccessToken={getAccessToken}
+    >
+      <YourApp />
+    </AvatarProvider>
+  );
+}
+```
+
+The `supabaseUrl` defaults to the `user_data` project. Only override if using a different Supabase instance.
+
+### 2. Display Avatars
+
+```tsx
+import { UserAvatar } from '@inovusmedical/avatar';
+
+function UserCard({ userId, name }) {
+  return (
+    <div>
+      <UserAvatar userId={userId} name={name} size="lg" />
+      <span>{name}</span>
+    </div>
+  );
+}
+```
+
+### 3. Upload Avatars
+
+```tsx
+import { AvatarUploader } from '@inovusmedical/avatar';
+
+function ProfileSettings() {
+  return (
+    <AvatarUploader
+      onUploadSuccess={(url) => console.log('Uploaded:', url)}
+      onUploadError={(error) => console.error('Error:', error)}
+      allowWebcam={true}
+      showRemoveButton={true}
+    />
+  );
+}
+```
+
+## Integration Guide for totum-live
+
+### Step 1: Install the package
+
+```bash
+pnpm add @inovusmedical/avatar @supabase/supabase-js
+```
+
+### Step 2: Add environment variable
+
+Add to your `.env`:
+
+```
+VITE_USER_DATA_ANON_KEY=your-user-data-anon-key
+```
+
+Get the anon key from the `user_data` Supabase project (Settings → API → anon public key).
+
+### Step 3: Set up the provider
+
+In your main `App.tsx` or layout component:
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { AvatarProvider } from '@inovusmedical/avatar';
+import '@inovusmedical/avatar/styles';
+import { getAccessToken } from '@inovusmedical/unified-auth';
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <AvatarProvider
+        supabaseAnonKey={import.meta.env.VITE_USER_DATA_ANON_KEY}
+        getAccessToken={getAccessToken}
+      >
+        {/* Your app */}
+      </AvatarProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+### Step 4: Replace Header avatar
+
+In your `Header.tsx`:
+
+```tsx
+import { UserAvatar, AvatarMenu } from '@inovusmedical/avatar';
+import { useLoggedInUser } from '@inovusmedical/unified-auth';
+
+function Header() {
+  const { user } = useLoggedInUser();
+
+  return (
+    <header>
+      {/* Option A: Just the avatar */}
+      <UserAvatar
+        userId={user.sub}
+        name={user.name}
+        size="sm"
+      />
+
+      {/* Option B: Avatar with dropdown menu */}
+      <AvatarMenu
+        userId={user.sub}
+        name={user.name}
+        size="sm"
+        menuItems={
+          <>
+            <a href="/profile">My Profile</a>
+            <button onClick={logout}>Sign Out</button>
+          </>
+        }
+      />
+    </header>
+  );
+}
+```
+
+### Step 5: Use batch lookups for lists
+
+For chat panels, attendee lists, and people grids:
+
+```tsx
+import { useAvatars, UserAvatar } from '@inovusmedical/avatar';
+
+function ChatPanel({ messages }) {
+  // Extract unique user IDs
+  const userIds = [...new Set(messages.map(m => m.sender_guid))];
+  
+  // Batch fetch all avatars (single Supabase query)
+  const { data: avatars } = useAvatars(userIds);
+
+  return (
+    <div>
+      {messages.map(msg => (
+        <div key={msg.id}>
+          <UserAvatar
+            userId={msg.sender_guid}
+            name={msg.sender_name}
+            size="sm"
+          />
+          <span>{msg.content}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Step 6: Add profile page uploader
+
+```tsx
+import { UserAvatar, AvatarUploader } from '@inovusmedical/avatar';
+import { useLoggedInUser } from '@inovusmedical/unified-auth';
+
+function ProfilePage() {
+  const { user } = useLoggedInUser();
+  const [showUploader, setShowUploader] = useState(false);
+
+  return (
+    <div>
+      <UserAvatar userId={user.sub} name={user.name} size="xl" />
+      
+      <button onClick={() => setShowUploader(true)}>
+        Change Photo
+      </button>
+
+      {showUploader && (
+        <AvatarUploader
+          onUploadSuccess={() => setShowUploader(false)}
+          onRemoveSuccess={() => setShowUploader(false)}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+## Components
+
+### `<AvatarProvider>`
+
+Context provider that configures the avatar service.
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `supabaseUrl` | `string` | No | Supabase project URL (defaults to user_data) |
+| `supabaseAnonKey` | `string` | Yes | Supabase anon/public key |
+| `getAccessToken` | `() => Promise<string \| null>` | Yes | Function to get Cognito token |
+| `batchDelay` | `number` | No | Debounce delay for batch requests (default: 50ms) |
+
+### `<UserAvatar>`
+
+Displays a user's avatar with automatic batched lookups.
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `userId` | `string` | Yes | User's Cognito sub (user_guid) |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number` | No | Avatar size (default: `'md'`) |
+| `name` | `string` | No | User's name for initials fallback |
+| `fallback` | `'initials' \| 'icon' \| ReactNode` | No | Fallback when no avatar (default: `'initials'`) |
+| `className` | `string` | No | Additional CSS class |
+| `onClick` | `() => void` | No | Click handler (makes avatar interactive) |
+
+### `<AvatarUploader>`
+
+Upload interface with file picker, webcam capture, and cropping.
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `onUploadSuccess` | `(url: string) => void` | No | Called after successful upload |
+| `onUploadError` | `(error: Error) => void` | No | Called on upload error |
+| `onRemoveSuccess` | `() => void` | No | Called after successful removal |
+| `onRemoveError` | `(error: Error) => void` | No | Called on removal error |
+| `showRemoveButton` | `boolean` | No | Show remove photo button (default: `true`) |
+| `allowWebcam` | `boolean` | No | Enable webcam capture (default: `true`) |
+| `cropShape` | `'round' \| 'rect'` | No | Crop area shape (default: `'round'`) |
+| `maxFileSizeMB` | `number` | No | Max file size in MB (default: `10`) |
+| `className` | `string` | No | Additional CSS class |
+
+### `<AvatarMenu>`
+
+Drop-in header component with avatar and change photo dropdown.
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `userId` | `string` | Yes | User's Cognito sub |
+| `name` | `string` | No | User's name |
+| `size` | `AvatarSize` | No | Avatar size (default: `'md'`) |
+| `menuItems` | `ReactNode` | No | Additional menu items |
+| `className` | `string` | No | Additional CSS class |
+
+## Hooks
+
+### `useAvatar(userId)`
+
+Fetch a single user's avatar URL.
+
+```tsx
+const { data: url, isLoading, error } = useAvatar('user-id');
+```
+
+### `useAvatars(userIds)`
+
+Fetch multiple avatar URLs in one batched Supabase query.
+
+```tsx
+const { data: avatarMap, isLoading } = useAvatars(['user1', 'user2', 'user3']);
+// avatarMap is Map<string, string | null>
+```
+
+### `useCurrentUserId()`
+
+Get the current user's ID from their Cognito token.
+
+```tsx
+const { data: userId } = useCurrentUserId();
+```
+
+### `useUploadAvatar()`
+
+Upload a new avatar.
+
+```tsx
+const { mutateAsync: upload, isPending } = useUploadAvatar();
+
+const blob = await cropAndResizeImage(imageSrc, cropArea);
+const result = await upload(blob);
+console.log('New URL:', result.url);
+```
+
+### `useDeleteAvatar()`
+
+Delete the current user's avatar.
+
+```tsx
+const { mutateAsync: deleteAvatar, isPending } = useDeleteAvatar();
+
+await deleteAvatar();
+```
+
+### `useDeleteAvatarAdmin()`
+
+Admin: delete any user's avatar (requires Admin Cognito group).
+
+```tsx
+const { mutateAsync: adminDelete } = useDeleteAvatarAdmin();
+
+await adminDelete('target-user-id');
+```
+
+## Styling
+
+Import the default styles:
+
+```tsx
+import '@inovusmedical/avatar/styles';
+```
+
+### Tailwind Integration
+
+The components use BEM-style classes that won't conflict with Tailwind:
+
+```tsx
+<UserAvatar
+  userId={user.sub}
+  className="ring-2 ring-blue-500"
+/>
+```
+
+## Architecture
+
+```
+┌─────────────────┐     ┌─────────────────────────┐
+│  Totum Apps     │     │  user_data Supabase     │
+│  (React)        │────▶│  - profile_images table │
+│                 │     │  - profile-images bucket│
+│  @inovusmedical │     │  - Third-Party Auth     │
+│  /avatar        │     │    (Cognito)            │
+└─────────────────┘     └─────────────────────────┘
+        │
+        ▼
+┌─────────────────┐
+│  unified-auth   │
+│  (Cognito JWT)  │
+└─────────────────┘
+```
+
+The package connects directly to the `user_data` Supabase project using the Cognito JWT from unified-auth. No separate backend service is needed.
+
+## Backwards Compatibility
+
+This package is compatible with existing widgets-dashboard avatars:
+- Reads from the same `profile_images` table
+- Uses the same `profile-images` storage bucket
+- Existing image paths continue to work
+- New uploads use versioned paths to fix stale-cache issues
+
+## Stale Cache Fix
+
+New uploads use versioned file paths (`{user_guid}/{timestamp}-{random}.webp`) instead of overwriting the same file. This ensures browsers and CDNs always show the latest image.
+
+## Version
+
+0.1.0