@hamzasaleemorg/convex-comments 1.0.0

package/src/react/Comments.tsx

@@ -0,0 +1,276 @@
+/**
+ * Comments Component
+ *
+ * Top-level component that displays all threads in a zone.
+ */
+
+import { type ReactNode } from "react";
+import { useComments } from "./CommentsProvider";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ThreadData {
+    thread: {
+        _id: string;
+        zoneId: string;
+        resolved: boolean;
+        resolvedBy?: string;
+        resolvedAt?: number;
+        createdAt: number;
+        lastActivityAt: number;
+        position?: { x: number; y: number; anchor?: string };
+        metadata?: unknown;
+    };
+    firstMessage: {
+        _id: string;
+        body: string;
+        authorId: string;
+        createdAt: number;
+    } | null;
+    messageCount: number;
+}
+
+export interface CommentsProps {
+    /** Threads data from getThreads query */
+    threads: ThreadData[];
+    /** Whether there are more threads to load */
+    hasMore?: boolean;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Callback when load more is clicked */
+    onLoadMore?: () => void;
+    /** Callback when a thread is clicked */
+    onThreadClick?: (threadId: string) => void;
+    /** Callback when new thread button is clicked */
+    onNewThread?: () => void;
+    /** Callback when thread is resolved */
+    onResolveThread?: (threadId: string) => void;
+    /** Callback when thread is unresolve */
+    onUnresolveThread?: (threadId: string) => void;
+    /** Whether to show resolved threads */
+    showResolved?: boolean;
+    /** Custom thread renderer */
+    renderThread?: (thread: ThreadData) => ReactNode;
+    /** Empty state message */
+    emptyMessage?: string;
+    /** CSS class name */
+    className?: string;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * Main comments component that displays all threads in a zone.
+ *
+ * Usage:
+ * ```tsx
+ * const { threads, hasMore } = useQuery(api.comments.getThreads, { zoneId });
+ *
+ * <Comments
+ *   threads={threads}
+ *   hasMore={hasMore}
+ *   onLoadMore={loadMore}
+ *   onThreadClick={(id) => setSelectedThread(id)}
+ *   onNewThread={() => createThread()}
+ * />
+ * ```
+ */
+export function Comments({
+    threads,
+    hasMore = false,
+    isLoading = false,
+    onLoadMore,
+    onThreadClick,
+    onNewThread,
+    onResolveThread,
+    onUnresolveThread,
+    showResolved = true,
+    renderThread,
+    emptyMessage = "No comments yet. Start a conversation!",
+    className = "",
+}: CommentsProps) {
+    const { userId, styles } = useComments();
+
+
+    // Filter threads based on showResolved
+    const visibleThreads = showResolved
+        ? threads
+        : threads.filter((t) => !t.thread.resolved);
+
+
+
+    // Default thread renderer
+    const defaultRenderThread = (data: ThreadData) => {
+        const { thread, firstMessage, messageCount } = data;
+        const isResolved = thread.resolved;
+
+        return (
+            <div
+                key={thread._id}
+                className={`comments-thread-preview ${isResolved ? "resolved" : ""}`}
+                onClick={() => onThreadClick?.(thread._id)}
+                style={{
+                    padding: "12px 16px",
+                    borderBottom: "1px solid #e5e7eb",
+                    cursor: "pointer",
+                    opacity: isResolved ? 0.6 : 1,
+                    backgroundColor: isResolved ? "#f9fafb" : "white",
+                }}
+            >
+                <div style={{ display: "flex", justifyContent: "space-between", alignItems: "flex-start" }}>
+                    <div style={{ flex: 1, minWidth: 0 }}>
+                        {firstMessage ? (
+                            <>
+                                <div
+                                    style={{
+                                        fontSize: "14px",
+                                        color: "#111827",
+                                        whiteSpace: "nowrap",
+                                        overflow: "hidden",
+                                        textOverflow: "ellipsis",
+                                    }}
+                                >
+                                    {firstMessage.body}
+                                </div>
+                                <div style={{ fontSize: "12px", color: "#6b7280", marginTop: "4px" }}>
+                                    {messageCount} {messageCount === 1 ? "message" : "messages"}
+                                    {isResolved && " • Resolved"}
+                                </div>
+                            </>
+                        ) : (
+                            <div style={{ fontSize: "14px", color: "#6b7280", fontStyle: "italic" }}>
+                                Empty thread
+                            </div>
+                        )}
+                    </div>
+                    {isResolved && onUnresolveThread && (
+                        <button
+                            onClick={(e) => {
+                                e.stopPropagation();
+                                onUnresolveThread(thread._id);
+                            }}
+                            style={{
+                                padding: "4px 8px",
+                                fontSize: "12px",
+                                border: "1px solid #d1d5db",
+                                borderRadius: "4px",
+                                background: "white",
+                                cursor: "pointer",
+                            }}
+                        >
+                            Reopen
+                        </button>
+                    )}
+                    {!isResolved && onResolveThread && (
+                        <button
+                            onClick={(e) => {
+                                e.stopPropagation();
+                                onResolveThread(thread._id);
+                            }}
+                            style={{
+                                padding: "4px 8px",
+                                fontSize: "12px",
+                                border: "1px solid #d1d5db",
+                                borderRadius: "4px",
+                                background: "white",
+                                cursor: "pointer",
+                            }}
+                        >
+                            Resolve
+                        </button>
+                    )}
+                </div>
+            </div>
+        );
+    };
+
+    return (
+        <div
+            className={`comments-container ${className}`}
+            style={{
+                fontFamily: styles?.fontFamily ?? "system-ui, -apple-system, sans-serif",
+                border: "1px solid #e5e7eb",
+                borderRadius: styles?.borderRadius ?? "8px",
+                overflow: "hidden",
+            }}
+        >
+            {/* Header */}
+            <div
+                style={{
+                    padding: "12px 16px",
+                    borderBottom: "1px solid #e5e7eb",
+                    display: "flex",
+                    justifyContent: "space-between",
+                    alignItems: "center",
+                    backgroundColor: "#f9fafb",
+                }}
+            >
+                <span style={{ fontWeight: 600, fontSize: "14px" }}>
+                    Comments ({threads.length})
+                </span>
+                {onNewThread && userId && (
+                    <button
+                        onClick={onNewThread}
+                        style={{
+                            padding: "6px 12px",
+                            fontSize: "13px",
+                            fontWeight: 500,
+                            border: "none",
+                            borderRadius: "6px",
+                            backgroundColor: styles?.accentColor ?? "#3b82f6",
+                            color: "white",
+                            cursor: "pointer",
+                        }}
+                    >
+                        + New Thread
+                    </button>
+                )}
+            </div>
+
+            {/* Thread list */}
+            <div style={{ maxHeight: "400px", overflowY: "auto" }}>
+                {visibleThreads.length === 0 ? (
+                    <div
+                        style={{
+                            padding: "40px 16px",
+                            textAlign: "center",
+                            color: "#6b7280",
+                            fontSize: "14px",
+                        }}
+                    >
+                        {emptyMessage}
+                    </div>
+                ) : (
+                    visibleThreads.map((data) =>
+                        renderThread ? renderThread(data) : defaultRenderThread(data)
+                    )
+                )}
+
+                {/* Load more */}
+                {hasMore && (
+                    <div style={{ padding: "12px 16px", textAlign: "center" }}>
+                        <button
+                            onClick={onLoadMore}
+                            disabled={isLoading}
+                            style={{
+                                padding: "8px 16px",
+                                fontSize: "13px",
+                                border: "1px solid #d1d5db",
+                                borderRadius: "6px",
+                                background: "white",
+                                cursor: isLoading ? "not-allowed" : "pointer",
+                                opacity: isLoading ? 0.6 : 1,
+                            }}
+                        >
+                            {isLoading ? "Loading..." : "Load More"}
+                        </button>
+                    </div>
+                )}
+            </div>
+        </div>
+    );
+}

package/src/react/CommentsProvider.tsx

@@ -0,0 +1,197 @@
+/**
+ * Comments Context Provider
+ *
+ * Provides the Comments API instance to all child components.
+ */
+
+import { createContext, useContext, useMemo, type ReactNode, type CSSProperties } from "react";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CommentsStyles {
+    /** Primary accent color (buttons, links, highlights) */
+    accentColor?: string;
+    /** Background color for the comments container */
+    backgroundColor?: string;
+    /** Text color */
+    textColor?: string;
+    /** Secondary/muted text color */
+    textColorMuted?: string;
+    /** Border color */
+    borderColor?: string;
+    /** Border radius for cards and buttons */
+    borderRadius?: string;
+    /** Font family */
+    fontFamily?: string;
+    /** Base font size */
+    fontSize?: string;
+}
+
+export interface CommentsContextValue {
+    /** Current user ID */
+    userId: string | null;
+    /** Function to resolve user display info */
+    resolveUser?: (userId: string) => Promise<{ name: string; avatar?: string }> | { name: string; avatar?: string };
+    /** Available reaction emojis */
+    reactionChoices: string[];
+    /** Whether the current user can edit/delete messages */
+    canModerate?: boolean;
+    /** Custom styles */
+    styles?: CommentsStyles;
+    /** CSS variables for theming */
+    cssVars: Record<string, string>;
+}
+
+// ============================================================================
+// Default Theme
+// ============================================================================
+
+const defaultStyles: Required<CommentsStyles> = {
+    accentColor: "#3b82f6",
+    backgroundColor: "#ffffff",
+    textColor: "#1f2937",
+    textColorMuted: "#6b7280",
+    borderColor: "#e5e7eb",
+    borderRadius: "8px",
+    fontFamily: "system-ui, -apple-system, sans-serif",
+    fontSize: "14px",
+};
+
+// ============================================================================
+// Context
+// ============================================================================
+
+const CommentsContext = createContext<CommentsContextValue | null>(null);
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+export interface CommentsProviderProps {
+    /** Current user ID (null if not authenticated) */
+    userId: string | null;
+    /** Function to resolve user info for display */
+    resolveUser?: (userId: string) => Promise<{ name: string; avatar?: string }> | { name: string; avatar?: string };
+    /** Available reaction emojis (defaults to common emojis) */
+    reactionChoices?: string[];
+    /** Whether the current user has moderator privileges */
+    canModerate?: boolean;
+    /** 
+     * Custom styling options. Can also use CSS variables:
+     * --comments-accent-color, --comments-bg-color, etc.
+     */
+    styles?: CommentsStyles;
+    /** Optional class name for the wrapper */
+    className?: string;
+    /** Child components */
+    children: ReactNode;
+}
+
+/**
+ * Provider component that supplies comments configuration to all child components.
+ *
+ * Usage:
+ * ```tsx
+ * <CommentsProvider
+ *   userId={currentUserId}
+ *   resolveUser={async (id) => ({ name: users[id].name, avatar: users[id].avatar })}
+ *   reactionChoices={["👍", "❤️", "😄", "🎉", "😮", "😢"]}
+ *   styles={{
+ *     accentColor: "#8b5cf6",
+ *     borderRadius: "12px",
+ *   }}
+ * >
+ *   <Comments threads={threads} />
+ * </CommentsProvider>
+ * ```
+ * 
+ * CSS Variables (can be set in your CSS):
+ * - --comments-accent-color
+ * - --comments-bg-color
+ * - --comments-text-color
+ * - --comments-text-color-muted
+ * - --comments-border-color
+ * - --comments-border-radius
+ * - --comments-font-family
+ * - --comments-font-size
+ */
+export function CommentsProvider({
+    userId,
+    resolveUser,
+    reactionChoices = ["👍", "❤️", "😄", "🎉", "😮", "😢", "👀", "🚀"],
+    canModerate = false,
+    styles,
+    className,
+    children,
+}: CommentsProviderProps) {
+    const mergedStyles = useMemo<Required<CommentsStyles>>(
+        () => ({
+            ...defaultStyles,
+            ...styles,
+        }),
+        [styles]
+    );
+
+    const cssVars = useMemo<Record<string, string>>(
+        () => ({
+            "--comments-accent-color": mergedStyles.accentColor,
+            "--comments-bg-color": mergedStyles.backgroundColor,
+            "--comments-text-color": mergedStyles.textColor,
+            "--comments-text-color-muted": mergedStyles.textColorMuted,
+            "--comments-border-color": mergedStyles.borderColor,
+            "--comments-border-radius": mergedStyles.borderRadius,
+            "--comments-font-family": mergedStyles.fontFamily,
+            "--comments-font-size": mergedStyles.fontSize,
+        }),
+        [mergedStyles]
+    );
+
+    const value = useMemo<CommentsContextValue>(
+        () => ({
+            userId,
+            resolveUser,
+            reactionChoices,
+            canModerate,
+            styles: mergedStyles,
+            cssVars,
+        }),
+        [userId, resolveUser, reactionChoices, canModerate, mergedStyles, cssVars]
+    );
+
+    const wrapperStyle: CSSProperties = {
+        ...cssVars as CSSProperties,
+        fontFamily: mergedStyles.fontFamily,
+        fontSize: mergedStyles.fontSize,
+        color: mergedStyles.textColor,
+    };
+
+    return (
+        <CommentsContext.Provider value={value}>
+            <div
+                className={`comments-provider ${className ?? ""}`}
+                style={wrapperStyle}
+                data-comments-provider=""
+            >
+                {children}
+            </div>
+        </CommentsContext.Provider>
+    );
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Hook to access the comments context.
+ * Must be used within a CommentsProvider.
+ */
+export function useComments(): CommentsContextValue {
+    const context = useContext(CommentsContext);
+    if (!context) {
+        throw new Error("useComments must be used within a CommentsProvider");
+    }
+    return context;
+}

package/src/react/ReactionPicker.tsx

@@ -0,0 +1,95 @@
+/**
+ * ReactionPicker Component
+ *
+ * A popup picker for selecting emoji reactions.
+ */
+
+import { useComments } from "./CommentsProvider";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ReactionPickerProps {
+    /** Callback when an emoji is selected */
+    onSelect: (emoji: string) => void;
+    /** Callback when the picker is closed */
+    onClose?: () => void;
+    /** Custom reaction choices (overrides provider) */
+    reactionChoices?: string[];
+    /** CSS class name */
+    className?: string;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * Emoji reaction picker popup.
+ *
+ * Usage:
+ * ```tsx
+ * <ReactionPicker
+ *   onSelect={(emoji) => toggleReaction({ messageId, emoji })}
+ *   onClose={() => setShowPicker(false)}
+ * />
+ * ```
+ */
+export function ReactionPicker({
+    onSelect,
+    onClose,
+    reactionChoices: customChoices,
+    className = "",
+}: ReactionPickerProps) {
+    const { reactionChoices: providerChoices, styles } = useComments();
+    const choices = customChoices ?? providerChoices;
+
+    return (
+        <div
+            className={`reaction-picker ${className}`}
+            style={{
+                display: "flex",
+                flexWrap: "wrap",
+                gap: "4px",
+                padding: "8px",
+                backgroundColor: "white",
+                borderRadius: styles?.borderRadius ?? "8px",
+                boxShadow: "0 4px 12px rgba(0,0,0,0.15)",
+                border: "1px solid #e5e7eb",
+                maxWidth: "200px",
+            }}
+        >
+            {choices.map((emoji) => (
+                <button
+                    key={emoji}
+                    onClick={() => {
+                        onSelect(emoji);
+                        onClose?.();
+                    }}
+                    style={{
+                        width: "32px",
+                        height: "32px",
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "center",
+                        border: "none",
+                        background: "transparent",
+                        borderRadius: "4px",
+                        cursor: "pointer",
+                        fontSize: "18px",
+                        transition: "background-color 0.15s",
+                    }}
+                    onMouseEnter={(e) => {
+                        e.currentTarget.style.backgroundColor = "#f3f4f6";
+                    }}
+                    onMouseLeave={(e) => {
+                        e.currentTarget.style.backgroundColor = "transparent";
+                    }}
+                >
+                    {emoji}
+                </button>
+            ))}
+        </div>
+    );
+}