@linktr.ee/messaging-react 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# @linktr.ee/messaging-react
+
+React messaging components built on `@linktr.ee/messaging-core` for web applications.
+
+## Features
+
+- **Web-optimized**: Uses Tailwind CSS and web APIs for responsive design
+- **Component-based**: Modular components that can be used individually or together
+- **Capability-driven**: Inject different data sources and capabilities per host
+- **Stream Chat integration**: Built on Stream Chat React for reliable messaging
+- **TypeScript**: Full type safety throughout
+
+## Components
+
+### MessagingShell
+Main container component that provides complete messaging interface.
+
+```tsx
+import { MessagingShell, MessagingProvider } from '@linktr.ee/messaging-react';
+
+<MessagingProvider user={user} serviceConfig={config} apiKey={apiKey}>
+  <MessagingShell 
+    capabilities={{
+      showStartConversation: true,
+      participantSource: followersSource,
+      participantLabel: 'followers'
+    }}
+  />
+</MessagingProvider>
+```
+
+### Individual Components
+- **ChannelList**: Sidebar with conversations and start conversation button
+- **ChannelView**: Message interface with customizable actions via render props
+- **ParticipantPicker**: Generic dialog for selecting conversation participants
+- **MessagingProvider**: Context provider for messaging state
+
+## Integration Patterns
+
+### MFE Pattern (Current)
+```tsx
+// Uses existing adapters and data sources
+import { createFollowersParticipantSource } from '../adapters/followersAdapter';
+
+const capabilities = {
+  showStartConversation: true,
+  participantSource: createFollowersParticipantSource(),
+  participantLabel: 'followers'
+};
+```
+
+### Next.js Pattern (Future)
+```tsx
+// Custom data sources for Next.js environment
+const capabilities = {
+  showStartConversation: true,
+  participantSource: createCustomParticipantSource(),
+  attachmentSource: createLinksAttachmentSource()
+};
+```
+
+### Embedded Pattern (Future)
+```tsx
+// Use individual components in existing layouts
+<div className="sidebar">
+  <ChannelList onChannelSelect={handleSelect} />
+</div>
+<div className="main">
+  <ChannelView channel={selectedChannel} />
+</div>
+```
+
+## Capability System
+
+The package uses a capability-based architecture to customize functionality:
+
+```typescript
+interface MessagingCapabilities {
+  showStartConversation?: boolean;
+  showAttachments?: boolean;
+  participantSource?: ParticipantSource;
+  attachmentSource?: AttachmentSource;
+  participantLabel?: string; // e.g., "followers", "team members"
+  attachmentLabel?: string; // e.g., "links", "files"
+}
+```
+
+## Data Source Interfaces
+
+### ParticipantSource
+Interface for loading conversation participants:
+
+```typescript
+interface ParticipantSource {
+  loadParticipants: (options?: { 
+    search?: string; 
+    limit?: number; 
+    cursor?: string;
+  }) => Promise<{
+    participants: Participant[];
+    hasMore: boolean;
+    nextCursor?: string;
+  }>;
+  totalCount?: number;
+  loading?: boolean;
+}
+```
+
+### AttachmentSource (Future)
+Interface for loading attachments like links or files.
+
+## Architecture Benefits
+
+- **Portability**: Works across different host environments
+- **Customization**: Inject different data sources per host
+- **Consistency**: Maintains Linktree design system
+- **Performance**: Web-optimized with lazy loading and pagination
+- **Maintainability**: Clean separation between UI and business logic
+
+## Development Status
+
+✅ Core messaging functionality
+✅ Follower participant selection
+✅ Responsive design
+✅ TypeScript safety
+⏳ Attachment system (planned)
+⏳ Advanced customization options (planned)

package/dist/index.d.ts

@@ -0,0 +1,194 @@
+import { Channel } from 'stream-chat';
+import { default as default_2 } from 'react';
+import { MessagingUser } from '@linktr.ee/messaging-core';
+import { StreamChatService } from '@linktr.ee/messaging-core';
+import { StreamChatServiceConfig } from '@linktr.ee/messaging-core';
+
+/**
+ * Avatar component that displays a user image or colored initial fallback
+ */
+export declare const Avatar: default_2.FC<AvatarProps>;
+
+export declare interface AvatarProps {
+    id: string;
+    name: string;
+    image?: string;
+    size?: number;
+    className?: string;
+}
+
+/**
+ * Channel list component with customizable header and actions
+ */
+export declare const ChannelList: default_2.FC<ChannelListProps>;
+
+/**
+ * ChannelList component props
+ */
+export declare interface ChannelListProps {
+    onChannelSelect: (channel: Channel) => void;
+    selectedChannel?: Channel;
+    showStartConversation?: boolean;
+    onStartConversation?: () => void;
+    participantLabel?: string;
+    className?: string;
+}
+
+/**
+ * Channel view component with message list and input
+ */
+export declare const ChannelView: default_2.FC<ChannelViewProps>;
+
+/**
+ * ChannelView component props
+ */
+export declare interface ChannelViewProps {
+    channel: Channel;
+    onBack?: () => void;
+    showBackButton?: boolean;
+    renderMessageInputActions?: (channel: Channel) => React.ReactNode;
+    onLeaveConversation?: (channel: Channel) => void;
+    onBlockParticipant?: (participantId?: string) => void;
+    className?: string;
+}
+
+/**
+ * Messaging capabilities configuration
+ */
+export declare interface MessagingCapabilities {
+    showStartConversation?: boolean;
+    participantSource?: ParticipantSource;
+    participantLabel?: string;
+}
+
+/**
+ * Context value for messaging state and service
+ */
+declare interface MessagingContextValue {
+    service: StreamChatService | null;
+    client: any;
+    isConnected: boolean;
+    isLoading: boolean;
+    error: string | null;
+    capabilities: MessagingCapabilities;
+    customization: MessagingCustomization;
+    refreshConnection: () => Promise<void>;
+    debug: boolean;
+}
+
+/**
+ * Customization options
+ */
+declare interface MessagingCustomization {
+    theme?: 'light' | 'dark' | 'auto';
+    accentColor?: string;
+    showParticipantStatus?: boolean;
+}
+
+/**
+ * Provider component that wraps messaging-core with React state management
+ */
+export declare const MessagingProvider: default_2.FC<MessagingProviderProps>;
+
+/**
+ * MessagingProvider component props
+ */
+export declare interface MessagingProviderProps {
+    children: React.ReactNode;
+    user: MessagingUser | null;
+    serviceConfig: Omit<StreamChatServiceConfig, 'apiKey'>;
+    apiKey: string;
+    capabilities?: MessagingCapabilities;
+    customization?: MessagingCustomization;
+    debug?: boolean;
+}
+
+/**
+ * Main messaging interface component that combines channel list and channel view
+ */
+export declare const MessagingShell: default_2.FC<MessagingShellProps>;
+
+/**
+ * Main MessagingShell component props
+ */
+export declare interface MessagingShellProps {
+    capabilities?: MessagingCapabilities;
+    customization?: MessagingCustomization;
+    className?: string;
+    renderMessageInputActions?: (channel: Channel) => React.ReactNode;
+    onChannelSelect?: (channel: Channel) => void;
+    onParticipantSelect?: (participant: Participant) => void;
+}
+
+/**
+ * Generic participant interface for different host environments
+ */
+export declare interface Participant {
+    id: string;
+    name: string;
+    email?: string;
+    image?: string;
+    username?: string;
+    phone?: string;
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Generic participant picker component for starting conversations
+ */
+export declare const ParticipantPicker: default_2.FC<ParticipantPickerProps>;
+
+/**
+ * ParticipantPicker component props
+ */
+export declare interface ParticipantPickerProps {
+    participantSource: ParticipantSource;
+    onSelectParticipant: (participant: Participant) => void;
+    onClose: () => void;
+    existingParticipantIds?: Set<string>;
+    participantLabel?: string;
+    searchPlaceholder?: string;
+    className?: string;
+}
+
+/**
+ * Source for loading participants (followers, team members, etc.)
+ */
+export declare interface ParticipantSource {
+    loadParticipants: (options?: {
+        search?: string;
+        limit?: number;
+        cursor?: string;
+    }) => Promise<{
+        participants: Participant[];
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    totalCount?: number;
+    loading?: boolean;
+}
+
+/**
+ * Hook to access messaging service and state
+ */
+export declare const useMessaging: () => MessagingContextValue;
+
+/**
+ * Hook for managing participant loading with search and pagination
+ */
+export declare const useParticipants: (participantSource: ParticipantSource, options?: {
+    initialSearch?: string;
+    pageSize?: number;
+}) => {
+    participants: Participant[];
+    loading: boolean;
+    error: string | null;
+    searchQuery: string;
+    hasMore: boolean;
+    totalCount: number | undefined;
+    loadMore: () => void;
+    search: (query: string) => void;
+    refresh: () => void;
+};
+
+export { }