@natoe/colab 0.1.13 → 0.1.16

package/dist/index.d.mts

@@ -15,6 +15,17 @@ declare const THEME_VAR: {
     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)`). */
@@ -30,6 +41,17 @@ declare const THEME_DEFAULTS: {
     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}. */
@@ -241,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 */
@@ -250,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 */
@@ -290,6 +320,7 @@ interface CollabPopupProps {
  */
 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;
@@ -297,24 +328,32 @@ 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) */
@@ -341,6 +380,20 @@ type PresenceCallback = (presences: Record<string, {
     userId: string;
     isOnline: boolean;
 }>) => void;
+/**
+ * Server-pushed unread counts. The backend broadcasts BOTH keyings in
+ * one payload so consumers can render badges at either granularity (FAB
+ * + inbox row use `conversation`; table-row chat icons use `order`) off
+ * a single socket event. Legacy backends that send a flat
+ * `Record<string, number>` are normalised at the socket boundary into
+ * `{ conversation: <flat>, order: {} }` for forward compatibility.
+ */
+interface UnreadCounts {
+    /** keyed by conversation id */
+    conversation: Record<string, number>;
+    /** keyed by order id — used for table-row chat-icon badges */
+    order: Record<string, number>;
+}
 interface ConversationCallbacks {
     onMessage?: MessageCallback;
     onTyping?: TypingCallback;
@@ -358,12 +411,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;
@@ -375,12 +447,34 @@ declare class CollabSocket {
     connect(config: CollabConfig): void;
     /** Subscribe to user-level events (unread counts, notifications) */
     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;
+    /** Register callback for unread count changes. The callback receives
+     *  the normalised {@link UnreadCounts} shape regardless of which
+     *  payload format the backend pushed. */
+    onUnreadCountUpdate(callback: (counts: UnreadCounts) => void): 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
@@ -434,6 +528,13 @@ interface CollabContextValue {
      * mounting their own useConversation.
      */
     unreadCounts: Record<string, number>;
+    /**
+     * Same unread counts, but keyed by **order ID** instead of
+     * conversation ID. Useful for table-row chat-icon badges where the
+     * row only knows its order_id, not the conversation_id. Same socket
+     * push updates both maps in lock-step.
+     */
+    unreadCountsByOrder: 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) */
@@ -716,8 +817,13 @@ interface ConversationListProps {
 /**
  * Scrollable inbox of conversations. Unread/All tabs (with count pills)
  * sit at the top, followed by a search field with a focus-within ring.
- * On first data load with any unread items the inbox auto-defaults to
- * the Unread tab so triage starts on what matters. Empty/loading/error
+ * 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, className, }: ConversationListProps): react_jsx_runtime.JSX.Element;
@@ -774,7 +880,7 @@ interface PatientHeaderProps {
  *     experience and there's no outer title, so we still show the name +
  *     back button stacked above the case card.
  */
-declare function PatientHeader({ patientData, onOpenDicom, onOpenSettings, onBack, hideName, displayName, className, }: PatientHeaderProps): react_jsx_runtime.JSX.Element;
+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) */

package/dist/index.d.ts

@@ -15,6 +15,17 @@ declare const THEME_VAR: {
     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)`). */
@@ -30,6 +41,17 @@ declare const THEME_DEFAULTS: {
     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}. */
@@ -241,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 */
@@ -250,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 */
@@ -290,6 +320,7 @@ interface CollabPopupProps {
  */
 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;
@@ -297,24 +328,32 @@ 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) */
@@ -341,6 +380,20 @@ type PresenceCallback = (presences: Record<string, {
     userId: string;
     isOnline: boolean;
 }>) => void;
+/**
+ * Server-pushed unread counts. The backend broadcasts BOTH keyings in
+ * one payload so consumers can render badges at either granularity (FAB
+ * + inbox row use `conversation`; table-row chat icons use `order`) off
+ * a single socket event. Legacy backends that send a flat
+ * `Record<string, number>` are normalised at the socket boundary into
+ * `{ conversation: <flat>, order: {} }` for forward compatibility.
+ */
+interface UnreadCounts {
+    /** keyed by conversation id */
+    conversation: Record<string, number>;
+    /** keyed by order id — used for table-row chat-icon badges */
+    order: Record<string, number>;
+}
 interface ConversationCallbacks {
     onMessage?: MessageCallback;
     onTyping?: TypingCallback;
@@ -358,12 +411,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;
@@ -375,12 +447,34 @@ declare class CollabSocket {
     connect(config: CollabConfig): void;
     /** Subscribe to user-level events (unread counts, notifications) */
     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;
+    /** Register callback for unread count changes. The callback receives
+     *  the normalised {@link UnreadCounts} shape regardless of which
+     *  payload format the backend pushed. */
+    onUnreadCountUpdate(callback: (counts: UnreadCounts) => void): 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
@@ -434,6 +528,13 @@ interface CollabContextValue {
      * mounting their own useConversation.
      */
     unreadCounts: Record<string, number>;
+    /**
+     * Same unread counts, but keyed by **order ID** instead of
+     * conversation ID. Useful for table-row chat-icon badges where the
+     * row only knows its order_id, not the conversation_id. Same socket
+     * push updates both maps in lock-step.
+     */
+    unreadCountsByOrder: 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) */
@@ -716,8 +817,13 @@ interface ConversationListProps {
 /**
  * Scrollable inbox of conversations. Unread/All tabs (with count pills)
  * sit at the top, followed by a search field with a focus-within ring.
- * On first data load with any unread items the inbox auto-defaults to
- * the Unread tab so triage starts on what matters. Empty/loading/error
+ * 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, className, }: ConversationListProps): react_jsx_runtime.JSX.Element;
@@ -774,7 +880,7 @@ interface PatientHeaderProps {
  *     experience and there's no outer title, so we still show the name +
  *     back button stacked above the case card.
  */
-declare function PatientHeader({ patientData, onOpenDicom, onOpenSettings, onBack, hideName, displayName, className, }: PatientHeaderProps): react_jsx_runtime.JSX.Element;
+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) */