@natoe/colab 0.1.12 → 0.1.14

package/dist/index.d.mts

@@ -2,6 +2,61 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 import { Channel } from 'phoenix';
 
+/** CSS variable names for the themeable color tokens. */
+declare const THEME_VAR: {
+    readonly primary: "--natoe-colab-primary";
+    readonly primaryHover: "--natoe-colab-primary-hover";
+    readonly primaryBg: "--natoe-colab-primary-bg";
+    readonly primaryFg: "--natoe-colab-primary-fg";
+    readonly success: "--natoe-colab-success";
+    readonly warning: "--natoe-colab-warning";
+    readonly danger: "--natoe-colab-danger";
+    readonly dangerBg: "--natoe-colab-danger-bg";
+    readonly dangerBorder: "--natoe-colab-danger-border";
+    readonly dangerFg: "--natoe-colab-danger-fg";
+    readonly fontStack: "--natoe-colab-font-stack";
+    readonly white: "--natoe-colab-white";
+    readonly neutral50: "--natoe-colab-neutral-50";
+    readonly neutral100: "--natoe-colab-neutral-100";
+    readonly neutral200: "--natoe-colab-neutral-200";
+    readonly neutral300: "--natoe-colab-neutral-300";
+    readonly neutral400: "--natoe-colab-neutral-400";
+    readonly neutral500: "--natoe-colab-neutral-500";
+    readonly neutral600: "--natoe-colab-neutral-600";
+    readonly neutral700: "--natoe-colab-neutral-700";
+    readonly neutral800: "--natoe-colab-neutral-800";
+    readonly neutral900: "--natoe-colab-neutral-900";
+};
+/** Default values for the themeable tokens (used by both CSS emission and
+ *  the inline-style fallback inside `var(..., fallback)`). */
+declare const THEME_DEFAULTS: {
+    readonly primary: "#2563eb";
+    readonly primaryHover: "#1d4ed8";
+    readonly primaryBg: "#dbeafe";
+    readonly primaryFg: "#1d4ed8";
+    readonly success: "#059669";
+    readonly warning: "#d97706";
+    readonly danger: "#dc2626";
+    readonly dangerBg: "#fef2f2";
+    readonly dangerBorder: "#fecaca";
+    readonly dangerFg: "#b91c1c";
+    readonly fontStack: "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif";
+    readonly white: "#ffffff";
+    readonly neutral50: "#f9fafb";
+    readonly neutral100: "#f3f4f6";
+    readonly neutral200: "#e5e7eb";
+    readonly neutral300: "#d1d5db";
+    readonly neutral400: "#9ca3af";
+    readonly neutral500: "#6b7280";
+    readonly neutral600: "#4b5563";
+    readonly neutral700: "#374151";
+    readonly neutral800: "#1f2937";
+    readonly neutral900: "#111827";
+};
+/** Public override shape — passed via CollabConfig.theme. Every key is
+ *  optional; unspecified keys fall back to {@link THEME_DEFAULTS}. */
+type Theme = Partial<Record<keyof typeof THEME_DEFAULTS, string>>;
+
 interface CollabConfig {
     /** Phoenix WebSocket URL (e.g. wss://backend.natoe.ai/socket) */
     socketUrl: string;
@@ -12,6 +67,15 @@ interface CollabConfig {
     userRole: UserRole;
     userName: string;
     userAvatar?: string;
+    /**
+     * Optional theme overrides. Any key set here is applied as a CSS custom
+     * property on `:root`, replacing the package's default for that token.
+     * Keys not provided keep their default. See {@link Theme} for the
+     * complete list of overridable tokens (brand + semantic colors + font
+     * stack). Spacing, type scale, radii are deliberately not themeable —
+     * changing those wholesale breaks the package's visual rhythm.
+     */
+    theme?: Theme;
     /** Host app callbacks — colab calls these, never implements them */
     onOpenDicom?: (studyId: string, storageId: string) => void;
     onUploadFile?: (file: File | Blob, fileName?: string) => Promise<string>;
@@ -23,6 +87,8 @@ interface PatientData {
     patientName: string;
     patientAge?: string;
     patientSex?: string;
+    /** Patient MRN — shown on inbox rows and searchable in the inbox filter. */
+    patientId?: string;
     studyType?: string;
     studyId?: string;
     storageId?: string;
@@ -145,8 +211,13 @@ interface SendMessagePayload {
     media_duration?: number;
     file_name?: string;
     metadata?: Record<string, unknown>;
-    /** ID of message being replied to (snapshot is built server-side) */
-    replyToId?: string;
+    /**
+     * ID of message being replied to (snapshot is built server-side).
+     * Wire-level key is snake_case to match the channel handler — the
+     * other optional fields here (media_url, file_name, …) follow the
+     * same convention.
+     */
+    reply_to_id?: string;
 }
 type ChannelEvent = 'message:new' | 'message:read' | 'message:pinned' | 'message:unpinned' | 'user:typing' | 'user:joined' | 'user:left' | 'channel:updated' | 'channel:deleted';
 interface TypingEvent {
@@ -192,6 +263,14 @@ interface CollabPanelProps {
      * relying on potentially-incomplete patientData.
      */
     onConversationChange?: (conversation: Conversation | null) => void;
+    /**
+     * Color mode for the entire panel. Default 'light'. 'dark' is meant for
+     * embedding inside the viewer's left panel (#000 background) — applies
+     * dark overrides for the themeable CSS variables on the panel root, so
+     * every internal surface (PatientHeader, MessageList, MessageBubble,
+     * MessageInput, PinnedMessagesBar, etc.) inherits them via cascade.
+     */
+    themeMode?: 'light' | 'dark';
     /** Custom class name for the outer container */
     className?: string;
     /** Custom inline styles for the outer container */
@@ -201,7 +280,7 @@ interface CollabPanelProps {
  * Full collaboration panel: patient header + pinned bar + message thread + input.
  * Supports reply, pin/unpin, and (optionally) seen-by indicators.
  */
-declare function CollabPanel({ orderId, patientData, participantIds, showSeenBy, onBack, hidePatientName, onConversationChange, className, style, }: CollabPanelProps): react_jsx_runtime.JSX.Element;
+declare function CollabPanel({ orderId, patientData, participantIds, showSeenBy, onBack, hidePatientName, onConversationChange, themeMode, className, style, }: CollabPanelProps): react_jsx_runtime.JSX.Element;
 
 interface CollabPopupProps {
     /** Order ID for this conversation */
@@ -216,6 +295,14 @@ interface CollabPopupProps {
     onClose: () => void;
     /** Optional back navigation — renders a ← button in the title bar when provided */
     onBack?: () => void;
+    /**
+     * When provided, the minimize button calls this callback instead of
+     * toggling the popup's own shrink-to-titlebar state. Hosts use this
+     * to minimize the popup to an external chip / dock. With this set the
+     * minimize button always shows the minimize glyph (no expand state),
+     * since the host owns the open/minimized lifecycle.
+     */
+    onMinimize?: () => void;
     /** Initial position (defaults to bottom-right) */
     initialPosition?: {
         x: number;
@@ -231,8 +318,9 @@ interface CollabPopupProps {
  * Draggable floating chat popup — drop-in replacement for DraggableChatPopup.
  * Renders a CollabPanel inside a movable, resizable container.
  */
-declare function CollabPopup({ orderId, patientData, participantIds, isOpen, onClose, onBack, initialPosition, width, height, className, }: CollabPopupProps): react_jsx_runtime.JSX.Element | null;
+declare function CollabPopup({ orderId, patientData, participantIds, isOpen, onClose, onBack, onMinimize, initialPosition, width, height, className, }: CollabPopupProps): react_jsx_runtime.JSX.Element | null;
 
+type ColabInlineMode = 'light' | 'dark';
 interface CollabInlineProps {
     orderId: string;
     patientData: PatientData;
@@ -240,32 +328,38 @@ interface CollabInlineProps {
     participantIds?: string[];
     /** Called when user clicks the expand button — host opens the floating popup */
     onExpand?: () => void;
-    /** Max inline messages to show (default 5) */
+    /** Max inline messages to show (default 1 — just the latest) */
     messageLimit?: number;
     /** Placeholder text for the input */
     placeholder?: string;
+    /**
+     * Color mode for the inline surface. Defaults to 'light'. 'dark' is meant
+     * for embedding inside the viewer's left panel (black background) — only
+     * neutral/structural colors switch; brand/role/semantic colors stay the
+     * same in both modes.
+     */
+    mode?: ColabInlineMode;
     className?: string;
     style?: React.CSSProperties;
 }
 /**
- * Inline chat for table rows.
+ * Inline chat for table rows or side panels.
  *
  * Two states:
  *   - No conversation yet: just an input bar (no socket, no preview)
- *   - Conversation exists: last N messages + input + expand button
+ *   - Conversation exists: latest message (or last N if messageLimit > 1)
+ *     + input + expand button
  *
  * Supports text and voice messages. File attachments and full chat features
  * stay in the floating popup / inbox.
  */
-declare function CollabInline({ orderId, patientData, participantIds, onExpand, messageLimit, placeholder, className, style, }: CollabInlineProps): react_jsx_runtime.JSX.Element;
+declare function CollabInline({ orderId, patientData, participantIds, onExpand, messageLimit, placeholder, mode, className, style, }: CollabInlineProps): react_jsx_runtime.JSX.Element;
 
 interface CollabInboxProps {
     /** Optional: preselect a specific conversation (by conversation ID) */
     initialConversationId?: string;
     /** Optional callback when the user selects a conversation */
     onSelectConversation?: (item: ConversationListItem$1) => void;
-    /** Title for the sidebar */
-    title?: string;
     className?: string;
     style?: React.CSSProperties;
 }
@@ -276,7 +370,7 @@ interface CollabInboxProps {
  * Uses the same CollabPanel as the floating popup, so all features
  * (reply, pin, seen-by, DICOM, voice, attachments) are available.
  */
-declare function CollabInbox({ initialConversationId, onSelectConversation, title, className, style, }: CollabInboxProps): react_jsx_runtime.JSX.Element;
+declare function CollabInbox({ initialConversationId, onSelectConversation, className, style, }: CollabInboxProps): react_jsx_runtime.JSX.Element;
 
 type MessageCallback = (message: Message) => void;
 type TypingCallback = (event: TypingEvent) => void;
@@ -303,12 +397,31 @@ interface ConversationCallbacks {
         messageId: string;
     }) => void;
 }
+/**
+ * Returned by `joinConversation()`. Each caller gets its own handle and
+ * its own bound listeners — calling `release()` unbinds only THIS
+ * subscriber's listeners. The channel only actually leaves the server
+ * when the last subscriber releases.
+ */
+interface ChannelSubscription {
+    /** Underlying Phoenix channel — callers that need to push/observe directly. */
+    channel: Channel;
+    /** Drop this subscriber. Idempotent — safe to call twice. */
+    release: () => void;
+}
 /**
  * Manages Phoenix WebSocket connection and channel subscriptions.
  * One instance per authenticated user session.
  */
 declare class CollabSocket {
     private socket;
+    /**
+     * Conversation channels keyed by id. Each entry is reference-counted so
+     * multiple surfaces (e.g. inline chat + expanded panel mounted at once
+     * for the same conversation) can coexist without one's `leaveConversation`
+     * tearing the channel out from under the other. See `joinConversation`
+     * and the returned `ChannelSubscription.release`.
+     */
     private channels;
     private presences;
     private userChannel;
@@ -322,10 +435,30 @@ declare class CollabSocket {
     private joinUserChannel;
     /** Register callback for unread count changes */
     onUnreadCountUpdate(callback: (counts: Record<string, number>) => void): void;
-    /** Join a conversation channel and subscribe to events */
-    joinConversation(conversationId: string, callbacks: ConversationCallbacks): Channel | null;
-    /** Leave a conversation channel */
-    leaveConversation(conversationId: string): void;
+    /**
+     * Join a conversation channel and subscribe to events.
+     *
+     * Reference-counted: multiple callers can join the same conversation
+     * (e.g. inline preview + expanded panel mounted side-by-side). Each
+     * call binds its own listeners and gets back a `ChannelSubscription`.
+     * The underlying channel only `.leave()`s the server when the LAST
+     * subscriber calls `release()`.
+     */
+    joinConversation(conversationId: string, callbacks: ConversationCallbacks): ChannelSubscription | null;
+    /**
+     * @deprecated Use the `release()` method returned by `joinConversation()`.
+     * Kept as a no-op so older callers don't throw — but it cannot identify
+     * which subscriber should leave, so it silently does nothing. Any code
+     * still calling this will leak listeners and prevent the channel from
+     * ever being torn down. Migrate to the subscription handle.
+     */
+    leaveConversation(_conversationId: string): void;
+    /**
+     * Look up the underlying Phoenix Channel for a conversation, if any
+     * subscriber is still holding it. All send/push paths go through this
+     * helper so the refcounted entry shape is contained to joinConversation.
+     */
+    private getChannel;
     /** Send a message to a conversation.
      *
      * Phoenix buffers pushes fired while a channel is still joining and
@@ -372,6 +505,13 @@ interface CollabContextValue {
     config: CollabConfig;
     apiBaseUrl: string;
     totalUnread: number;
+    /**
+     * Per-conversation unread counts, keyed by conversation ID. Updated
+     * live via the user_notifications channel's unread_update push, so
+     * surfaces like a minimized-chat chip can reflect changes without
+     * mounting their own useConversation.
+     */
+    unreadCounts: Record<string, number>;
     /** Batched preview lookup — coalesces calls within a microtask */
     requestPreview: (orderId: string) => Promise<ConversationPreview | null>;
     /** Invalidate a cached preview (e.g. when a new message arrives) */
@@ -649,14 +789,21 @@ interface ConversationListProps {
     isLoading: boolean;
     error: string | null;
     onSelect: (item: ConversationListItem$1) => void;
-    /** Optional title shown above the list */
-    title?: string;
     className?: string;
 }
 /**
- * Scrollable sidebar list of conversations with search and unread filter.
+ * Scrollable inbox of conversations. Unread/All tabs (with count pills)
+ * sit at the top, followed by a search field with a focus-within ring.
+ * The inbox lands on Unread by default whenever there are any unread
+ * conversations — the initial choice reads CollabProvider's socket-
+ * pushed `totalUnread`, which is already populated by the time the
+ * FAB is clicked (it drives the badge), so there's no "All flash"
+ * during the conversation-list fetch. A fallback effect handles the
+ * edge case where the conversation list loads with unread items but
+ * `totalUnread` was still zero at mount time. Empty/loading/error
+ * states are illustrated and descriptive rather than terse one-liners.
  */
-declare function ConversationList({ conversations, selectedId, isLoading, error, onSelect, title, className, }: ConversationListProps): react_jsx_runtime.JSX.Element;
+declare function ConversationList({ conversations, selectedId, isLoading, error, onSelect, className, }: ConversationListProps): react_jsx_runtime.JSX.Element;
 
 interface ConversationListItemProps {
     item: ConversationListItem$1;
@@ -665,8 +812,21 @@ interface ConversationListItemProps {
     className?: string;
 }
 /**
- * Single row in the inbox sidebar — shows patient/channel name, last message
- * preview, timestamp, and unread badge.
+ * Single row in the inbox sidebar.
+ *
+ * Three-row layout (top-to-bottom):
+ *   1. Patient/channel name + relative time
+ *   2. Study type + monospace `MRN <patientId>` (surfaced from the
+ *      snapshot; either field is optional and the row collapses if both
+ *      are missing)
+ *   3. Last message preview (sender prefix in stronger weight) + unread
+ *      count badge on the right
+ *
+ * Active row gets a 4px brand-color left-border accent + tinted background.
+ * The avatar is a 52px **square** tile (16px rounded corners) with brand-
+ * coloured fill and white initials — easier to scan than a circle at this
+ * size and consistent across the inbox without depending on any case
+ * status field we don't model.
  */
 declare function ConversationListItem({ item, isSelected, onClick, className, }: ConversationListItemProps): react_jsx_runtime.JSX.Element;
 
@@ -683,7 +843,21 @@ interface PatientHeaderProps {
     displayName?: string;
     className?: string;
 }
-declare function PatientHeader({ patientData, onOpenDicom, onOpenSettings, onBack, hideName, displayName, className, }: PatientHeaderProps): react_jsx_runtime.JSX.Element;
+/**
+ * "Case card" header that sits below the window title bar. Tinted blue-50
+ * background to set it apart from the conversation body. Renders a row
+ * of labelled key-value columns (label uppercase on top, value below) for
+ * the clinical context the host passed in, with the action buttons
+ * (View DICOM + Settings) right-aligned.
+ *
+ * Used in two layouts:
+ *   - Popup path (`hideName=true`): the surrounding title bar already
+ *     shows the patient name, so we render the case card only.
+ *   - Compact-inbox path (`hideName=false`): the panel is a full-page
+ *     experience and there's no outer title, so we still show the name +
+ *     back button stacked above the case card.
+ */
+declare function PatientHeader({ patientData, participants, onOpenDicom, onOpenSettings, onBack, hideName, displayName, className, }: PatientHeaderProps): react_jsx_runtime.JSX.Element;
 
 interface MessageListHandle {
     /** Scroll to a specific message by ID (used by pin jump-to) */
@@ -864,6 +1038,34 @@ interface ParticipantsListProps {
 }
 declare function ParticipantsList({ participants, currentUserId, isAdmin, onRemoveUser, className, }: ParticipantsListProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Shared style tokens + the global stylesheet the package injects once per
+ * page.
+ *
+ * Top-level wrappers (CollabPopup, CollabPanel, CollabInline, CollabInbox)
+ * import {@link FONT_STACK} so every surface renders with the same font
+ * stack, even when the package is mounted inside an iframe whose
+ * surrounding document doesn't set one.
+ *
+ * Themeable tokens (brand + semantic colors + the font stack) are emitted
+ * as CSS custom properties on `:root` so host apps can override them via
+ * `CollabConfig.theme` (see {@link applyThemeOverrides}). Non-themeable
+ * tokens (neutrals, slate, spacing, radius, sizes) live as inline values
+ * in core/theme.ts and stay constant.
+ *
+ * The prefers-contrast / prefers-reduced-motion adjustments are emitted
+ * inside the same stylesheet so they apply wherever a `natoe-colab-root`
+ * wrapper is mounted.
+ */
+
+/**
+ * Apply a host-supplied theme by setting CSS custom properties on the
+ * document root. Keys missing from `theme` have their previously-set
+ * override cleared so toggling overrides back to undefined returns the
+ * default — never leaves stale values behind.
+ */
+declare function applyThemeOverrides(theme: Theme | undefined): void;
+
 /** Phoenix channel event names — must match backend channel implementation */
 declare const EVENTS: {
     readonly MESSAGE_NEW: "message:new";
@@ -902,4 +1104,4 @@ declare const SUPPORTED_IMAGE_TYPES: string[];
 /** Max file size in bytes (20MB) */
 declare const MAX_FILE_SIZE: number;
 
-export { AUDIO_MIME_TYPE, type ChannelEvent, ChannelSettings, type ChannelUpdatePayload, type CollabConfig, type CollabError, CollabInbox, CollabInline, CollabPanel, CollabPopup, CollabProvider, CollabSocket, type Conversation, ConversationList, ConversationListItem, type ConversationListItem$1 as ConversationListItemData, type ConversationPreview, type CreateConversationResponse, DEEP_LINK_PREFIX, EVENTS, type InviteUserPayload, MAX_FILE_SIZE, MAX_PINNED_MESSAGES, MESSAGES_PAGE_SIZE, MESSAGE_TYPES, type Message, MessageActionsMenu, MessageBubble, MessageInput, MessageList, type MessageListHandle, type MessageSnapshot, type MessageType, type Participant, ParticipantsList, type PatientData, PatientHeader, PinnedMessagesBar, type PreviewBatchResponse, ReplyPreview, ReplyQuoteBlock, SUPPORTED_IMAGE_TYPES, SeenByIndicator, type SendMessagePayload, TYPING_DEBOUNCE_MS, type TypingEvent, type UserRole, useAudioRecorder, useChannelSettings, useCollab, useConversation, useConversationList, useDeepLinks, useInlineCollab, useMessages, usePinnedMessages, useUnreadCount };
+export { AUDIO_MIME_TYPE, type ChannelEvent, ChannelSettings, type ChannelUpdatePayload, type CollabConfig, type CollabError, CollabInbox, CollabInline, CollabPanel, CollabPopup, CollabProvider, CollabSocket, type Conversation, ConversationList, ConversationListItem, type ConversationListItem$1 as ConversationListItemData, type ConversationPreview, type CreateConversationResponse, DEEP_LINK_PREFIX, EVENTS, type InviteUserPayload, MAX_FILE_SIZE, MAX_PINNED_MESSAGES, MESSAGES_PAGE_SIZE, MESSAGE_TYPES, type Message, MessageActionsMenu, MessageBubble, MessageInput, MessageList, type MessageListHandle, type MessageSnapshot, type MessageType, type Participant, ParticipantsList, type PatientData, PatientHeader, PinnedMessagesBar, type PreviewBatchResponse, ReplyPreview, ReplyQuoteBlock, SUPPORTED_IMAGE_TYPES, SeenByIndicator, type SendMessagePayload, THEME_DEFAULTS, THEME_VAR, TYPING_DEBOUNCE_MS, type Theme, type TypingEvent, type UserRole, applyThemeOverrides, useAudioRecorder, useChannelSettings, useCollab, useConversation, useConversationList, useDeepLinks, useInlineCollab, useMessages, usePinnedMessages, useUnreadCount };