@linktr.ee/messaging-react 1.3.0 → 1.4.0-rc-1761053580

package/src/components/MessagingShell/EmptyState.tsx

@@ -8,7 +8,7 @@ export const EmptyState: React.FC<{
   onStartConversation?: () => void
   participantLabel: string
 }> = ({ hasChannels, onStartConversation, participantLabel }) => (
-  <div className="flex items-center justify-center h-full p-8 text-balance">
+  <div className="messaging-empty-state flex items-center justify-center h-full p-8 text-balance">
     <div className="text-center max-w-sm">
       <div className="w-24 h-24 bg-primary-alt/10 rounded-full flex items-center justify-center mx-auto mb-6">
         <span className="text-4xl">💬</span>

package/src/components/MessagingShell/ErrorState.stories.tsx

@@ -25,19 +25,19 @@ const Template: StoryFn<ComponentProps> = (args) => {
 
 export const ConnectionError: StoryFn<ComponentProps> = Template.bind({})
 ConnectionError.args = {
-  error: 'Unable to connect to messaging service. Please check your connection and try again.',
-  onRetry: () => console.log('Retry clicked'),
+  message:
+    'Unable to connect to messaging service. Please check your connection and try again.',
+  onBack: () => console.log('Go Back clicked'),
 }
 
-export const NoRetry: StoryFn<ComponentProps> = Template.bind({})
-NoRetry.args = {
-  error: 'Failed to load messages.',
-  onRetry: undefined,
+export const NoBackButton: StoryFn<ComponentProps> = Template.bind({})
+NoBackButton.args = {
+  message: 'Failed to load messages.',
+  onBack: undefined,
 }
 
 export const CustomError: StoryFn<ComponentProps> = Template.bind({})
 CustomError.args = {
-  error: 'Your session has expired. Please refresh the page to continue.',
-  onRetry: () => console.log('Retry clicked'),
+  message: 'Your session has expired. Please refresh the page to continue.',
+  onBack: () => console.log('Go Back clicked'),
 }
-

package/src/components/MessagingShell/ErrorState.tsx

@@ -1,33 +1,31 @@
-import React from 'react';
+import React from 'react'
 
 /**
- * Error state component
+ * Error state component shown when something goes wrong
  */
-export const ErrorState: React.FC<{ error: string; onRetry?: () => void }> = ({ error, onRetry }) => (
-  <div className="flex items-center justify-center h-full p-8">
-    <div className="text-center max-w-md">
-      <div className="w-24 h-24 bg-danger-alt rounded-full flex items-center justify-center mx-auto mb-6">
+export const ErrorState: React.FC<{
+  message: string
+  onBack?: () => void
+}> = ({ message, onBack }) => (
+  <div className="messaging-error-state flex items-center justify-center h-full p-8">
+    <div className="text-center max-w-sm">
+      <div className="w-24 h-24 bg-danger-alt/20 rounded-full flex items-center justify-center mx-auto mb-6">
         <span className="text-4xl">⚠️</span>
       </div>
-      
-      <h2 className="text-xl font-semibold text-charcoal mb-3">
-        Connection Error
-      </h2>
-      
-      <p className="text-stone text-sm mb-6">
-        {error}
-      </p>
 
-      {onRetry && (
+      <h2 className="font-semibold text-charcoal mb-2">Oops!</h2>
+
+      <p className="text-stone text-sm mb-6">{message}</p>
+
+      {onBack && (
         <button
           type="button"
-          onClick={onRetry}
-          className="inline-flex items-center px-4 py-2 bg-primary text-white rounded-lg hover:bg-primary-alt focus:outline-none focus:ring-2 focus:ring-primary transition-colors"
+          onClick={onBack}
+          className="inline-flex items-center gap-2 px-4 py-2 text-sm font-medium text-white bg-primary hover:bg-primary-alt rounded-lg focus:outline-none focus:ring-2 focus:ring-primary transition-colors"
         >
-          Try Again
+          Go Back
         </button>
       )}
     </div>
   </div>
-);
-
+)

package/src/components/MessagingShell/LoadingState.tsx

@@ -4,7 +4,7 @@ import Loading from '../Loading'
  * Loading state component
  */
 export const LoadingState = () => (
-  <div className="flex items-center justify-center h-full">
+  <div className="messaging-loading-state flex items-center justify-center h-full">
     <div className="flex items-center">
       <Loading className="w-6 h-6" />
       <span className="text-sm text-stone">Loading messages</span>

package/src/components/MessagingShell/index.tsx

@@ -21,6 +21,8 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
   renderMessageInputActions,
   onChannelSelect,
   onParticipantSelect,
+  initialParticipantFilter,
+  initialParticipantData,
 }) => {
   const {
     service,
@@ -39,6 +41,10 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
     Set<string>
   >(new Set())
   const [pickerKey, setPickerKey] = useState(0) // Key to force remount of ParticipantPicker
+  const [directConversationMode, setDirectConversationMode] = useState(false)
+  const [directConversationError, setDirectConversationError] = useState<
+    string | null
+  >(null)
 
   const participantPickerRef = useRef<HTMLDialogElement>(null)
 
@@ -112,6 +118,111 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
     syncChannels()
   }, [client, isConnected, syncChannels])
 
+  // Load initial channel for direct conversation mode
+  useEffect(() => {
+    if (!initialParticipantFilter || !client || !isConnected) return
+
+    const loadInitialChannel = async () => {
+      const userId = client.userID
+      if (!userId) return
+
+      try {
+        if (debug) {
+          console.log(
+            '[MessagingShell] Loading initial conversation with:',
+            initialParticipantFilter
+          )
+        }
+
+        const channels = await client.queryChannels(
+          {
+            type: 'messaging',
+            members: { $eq: [userId, initialParticipantFilter] },
+          },
+          {},
+          { limit: 1 }
+        )
+
+        if (channels.length > 0) {
+          setSelectedChannel(channels[0])
+          setDirectConversationMode(true)
+          setDirectConversationError(null)
+
+          if (debug) {
+            console.log(
+              '[MessagingShell] Initial conversation loaded:',
+              channels[0].id
+            )
+          }
+        } else {
+          // No channel found - try to create one if participant data is provided
+          if (initialParticipantData && service) {
+            if (debug) {
+              console.log(
+                '[MessagingShell] No conversation found, creating one for:',
+                initialParticipantData
+              )
+            }
+
+            try {
+              // Use the existing service method to create the channel
+              const channel = await service.startChannelWithParticipant({
+                id: initialParticipantData.id,
+                name: initialParticipantData.name,
+                email: initialParticipantData.email,
+                phone: initialParticipantData.phone,
+              })
+
+              setSelectedChannel(channel)
+              setDirectConversationMode(true)
+              setDirectConversationError(null)
+
+              if (debug) {
+                console.log(
+                  '[MessagingShell] Channel created and loaded:',
+                  channel.id
+                )
+              }
+            } catch (createErr) {
+              console.error(
+                '[MessagingShell] Failed to create conversation:',
+                createErr
+              )
+              setDirectConversationError('Failed to create conversation')
+            }
+          } else {
+            // No participant data provided, show error
+            setDirectConversationError(
+              'No conversation found with this account'
+            )
+
+            if (debug) {
+              console.log(
+                '[MessagingShell] No conversation found for:',
+                initialParticipantFilter
+              )
+            }
+          }
+        }
+      } catch (err) {
+        console.error(
+          '[MessagingShell] Failed to load initial conversation:',
+          err
+        )
+        setDirectConversationError('Failed to load conversation')
+      }
+    }
+
+    loadInitialChannel()
+  }, [
+    initialParticipantFilter,
+    initialParticipantData,
+    client,
+    isConnected,
+    service,
+    debug,
+  ])
+
   const handleChannelSelect = useCallback(
     (channel: Channel) => {
       setSelectedChannel(channel)
@@ -121,8 +232,12 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
   )
 
   const handleBackToChannelList = useCallback(() => {
+    // In direct conversation mode, don't allow going back to channel list
+    // The parent component should handle navigation
+    if (directConversationMode) return
+
     setSelectedChannel(null)
-  }, [])
+  }, [directConversationMode])
 
   const handleStartConversation = useCallback(() => {
     if (participantSource) {
@@ -181,6 +296,7 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
         console.log('[MessagingShell] Leaving conversation:', channel.id)
       }
       setSelectedChannel(null)
+      setDirectConversationMode(false) // Exit direct conversation mode
 
       // Force re-sync to update the existing participants list
       syncedRef.current = null
@@ -195,6 +311,7 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
         console.log('[MessagingShell] Blocking participant:', participantId)
       }
       setSelectedChannel(null)
+      setDirectConversationMode(false) // Exit direct conversation mode
 
       // Force re-sync to update the existing participants list
       syncedRef.current = null
@@ -218,7 +335,7 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
   if (error) {
     return (
       <div className={classNames('h-full', className)}>
-        <ErrorState error={error} onRetry={refreshConnection} />
+        <ErrorState message={error} onBack={refreshConnection} />
       </div>
     )
   }
@@ -228,24 +345,43 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
     return (
       <div className={classNames('h-full', className)}>
         <ErrorState
-          error="Not connected to messaging service"
-          onRetry={refreshConnection}
+          message="Not connected to messaging service"
+          onBack={refreshConnection}
         />
       </div>
     )
   }
 
+  // Show direct conversation error state
+  if (directConversationError) {
+    return (
+      <div className={classNames('h-full', className)}>
+        <ErrorState message={directConversationError} />
+      </div>
+    )
+  }
+
   return (
-    <div className={classNames('h-full bg-white overflow-hidden', className)}>
+    <div
+      className={classNames(
+        'messaging-shell h-full bg-white overflow-hidden',
+        className
+      )}
+    >
       <div className="flex h-full min-h-0">
         {/* Channel List Sidebar */}
         <div
           className={classNames(
-            'min-h-0 min-w-0 bg-white lg:bg-chalk lg:flex lg:flex-col lg:border-r lg:border-sand',
+            'messaging-channel-list-sidebar min-h-0 min-w-0 bg-white lg:bg-chalk lg:flex lg:flex-col lg:border-r lg:border-sand',
             {
+              // In direct conversation mode, always hide the channel list
+              hidden: directConversationMode,
+              // Normal mode: hide on mobile when channel selected, show on desktop
               'hidden lg:flex lg:w-80 lg:min-w-[280px] lg:max-w-[360px]':
-                isChannelSelected,
-              'flex flex-col w-full lg:flex-1 lg:max-w-2xl': !isChannelSelected,
+                !directConversationMode && isChannelSelected,
+              // Normal mode: show when no channel selected
+              'flex flex-col w-full lg:flex-1 lg:max-w-2xl':
+                !directConversationMode && !isChannelSelected,
             }
           )}
         >
@@ -262,10 +398,15 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
 
         {/* Channel View */}
         <div
-          className={classNames('flex-1 flex-col min-w-0 min-h-0', {
-            'hidden lg:flex': !isChannelSelected,
-            flex: isChannelSelected,
-          })}
+          className={classNames(
+            'messaging-conversation-view flex-1 flex-col min-w-0 min-h-0',
+            {
+              // In direct conversation mode, always show (full width)
+              flex: directConversationMode || isChannelSelected,
+              // Normal mode: hide on mobile when no channel selected
+              'hidden lg:flex': !directConversationMode && !isChannelSelected,
+            }
+          )}
         >
           {selectedChannel ? (
             <div className="flex-1 min-h-0 flex flex-col">
@@ -273,7 +414,7 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
                 channel={selectedChannel}
                 key={selectedChannel.id}
                 onBack={handleBackToChannelList}
-                showBackButton
+                showBackButton={!directConversationMode}
                 renderMessageInputActions={renderMessageInputActions}
                 onLeaveConversation={handleLeaveConversation}
                 onBlockParticipant={handleBlockParticipant}

package/src/components/ParticipantPicker/ParticipantPicker.tsx

@@ -123,7 +123,12 @@ export const ParticipantPicker: React.FC<ParticipantPickerProps> = ({
   }
 
   return (
-    <div className={classNames('flex flex-col h-full', className)}>
+    <div
+      className={classNames(
+        'messaging-participant-picker flex flex-col h-full',
+        className
+      )}
+    >
       {/* Header */}
       <div className="px-4 py-4 border-b border-sand bg-chalk">
         <div className="flex items-center justify-between mb-3">

package/src/types.ts

@@ -1,113 +1,135 @@
-import type { MessagingUser, StreamChatServiceConfig } from '@linktr.ee/messaging-core';
-import type { Channel } from 'stream-chat';
+import type {
+  MessagingUser,
+  StreamChatServiceConfig,
+} from '@linktr.ee/messaging-core'
+import type { Channel } from 'stream-chat'
 
 /**
  * Generic participant interface for different host environments
  */
 export interface Participant {
-  id: string;
-  name: string;
-  email?: string;
-  image?: string;
-  username?: string;
-  phone?: string;
-  metadata?: Record<string, any>;
+  id: string
+  name: string
+  email?: string
+  image?: string
+  username?: string
+  phone?: string
+  metadata?: Record<string, any>
 }
 
 /**
  * Source for loading participants (followers, team members, etc.)
  */
 export interface ParticipantSource {
-  loadParticipants: (options?: { 
-    search?: string; 
-    limit?: number; 
-    cursor?: string;
+  loadParticipants: (options?: {
+    search?: string
+    limit?: number
+    cursor?: string
   }) => Promise<{
-    participants: Participant[];
-    hasMore: boolean;
-    nextCursor?: string;
-  }>;
-  totalCount?: number;
-  loading?: boolean;
+    participants: Participant[]
+    hasMore: boolean
+    nextCursor?: string
+  }>
+  totalCount?: number
+  loading?: boolean
 }
 
 /**
  * Messaging capabilities configuration
  */
 export interface MessagingCapabilities {
-  showStartConversation?: boolean;
-  participantSource?: ParticipantSource;
-  participantLabel?: string; // e.g., "followers", "team members"
+  showStartConversation?: boolean
+  participantSource?: ParticipantSource
+  participantLabel?: string // e.g., "followers", "team members"
 }
 
 /**
  * Customization options
  */
 export interface MessagingCustomization {
-  theme?: 'light' | 'dark' | 'auto';
-  accentColor?: string;
-  showParticipantStatus?: boolean;
+  theme?: 'light' | 'dark' | 'auto'
+  accentColor?: string
+  showParticipantStatus?: boolean
 }
 
 /**
  * Main MessagingShell component props
  */
 export interface MessagingShellProps {
-  capabilities?: MessagingCapabilities;
-  customization?: MessagingCustomization;
-  className?: string;
-  renderMessageInputActions?: (channel: Channel) => React.ReactNode;
-  onChannelSelect?: (channel: Channel) => void;
-  onParticipantSelect?: (participant: Participant) => void;
+  capabilities?: MessagingCapabilities
+  customization?: MessagingCustomization
+  className?: string
+  renderMessageInputActions?: (channel: Channel) => React.ReactNode
+  onChannelSelect?: (channel: Channel) => void
+  onParticipantSelect?: (participant: Participant) => void
+
+  /**
+   * Auto-select a conversation with this participant on mount.
+   * Useful for deep-linking to a specific conversation (e.g., /messages/[accountUuid])
+   *
+   * If a channel with this participant exists, it will be auto-selected.
+   * If no channel exists, you can provide initialParticipantData to automatically
+   * create the channel using the existing ChannelCreator.
+   */
+  initialParticipantFilter?: string
+
+  /**
+   * Participant data for auto-creating a channel when initialParticipantFilter
+   * is provided but no channel exists. If this is provided, MessagingShell will
+   * automatically call service.startChannelWithParticipant() to create the channel.
+   *
+   * This reuses the existing ChannelCreator from StreamChatServiceConfig.
+   */
+  initialParticipantData?: Participant
 }
 
 /**
  * ChannelList component props
  */
 export interface ChannelListProps {
-  onChannelSelect: (channel: Channel) => void;
-  selectedChannel?: Channel;
-  showStartConversation?: boolean;
-  onStartConversation?: () => void;
-  participantLabel?: string;
-  className?: string;
+  onChannelSelect: (channel: Channel) => void
+  selectedChannel?: Channel
+  showStartConversation?: boolean
+  onStartConversation?: () => void
+  participantLabel?: string
+  className?: string
 }
 
 /**
  * ChannelView component props
  */
 export interface ChannelViewProps {
-  channel: Channel;
-  onBack?: () => void;
-  showBackButton?: boolean;
-  renderMessageInputActions?: (channel: Channel) => React.ReactNode;
-  onLeaveConversation?: (channel: Channel) => void;
-  onBlockParticipant?: (participantId?: string) => void;
-  className?: string;
+  channel: Channel
+  onBack?: () => void
+  showBackButton?: boolean
+  renderMessageInputActions?: (channel: Channel) => React.ReactNode
+  onLeaveConversation?: (channel: Channel) => void
+  onBlockParticipant?: (participantId?: string) => void
+  className?: string
 }
 
 /**
  * ParticipantPicker component props
  */
 export interface ParticipantPickerProps {
-  participantSource: ParticipantSource;
-  onSelectParticipant: (participant: Participant) => void;
-  onClose: () => void;
-  existingParticipantIds?: Set<string>;
-  participantLabel?: string;
-  searchPlaceholder?: string;
-  className?: string;
+  participantSource: ParticipantSource
+  onSelectParticipant: (participant: Participant) => void
+  onClose: () => void
+  existingParticipantIds?: Set<string>
+  participantLabel?: string
+  searchPlaceholder?: string
+  className?: string
 }
 
 /**
  * MessagingProvider component props
  */
 export interface MessagingProviderProps {
-  children: React.ReactNode;
-  user: MessagingUser | null;
-  serviceConfig: Omit<StreamChatServiceConfig, 'apiKey'>;
-  apiKey: string;
-  capabilities?: MessagingCapabilities;
-  customization?: MessagingCustomization;
-  debug?: boolean;
+  children: React.ReactNode
+  user: MessagingUser | null
+  serviceConfig: Omit<StreamChatServiceConfig, 'apiKey'>
+  apiKey: string
+  capabilities?: MessagingCapabilities
+  customization?: MessagingCustomization
+  debug?: boolean
 }