comment-mode 0.1.2 → 0.1.4

package/README.md

@@ -8,22 +8,23 @@ Embeddable commenting for live prototypes (Next.js / React). Add a comment overl
 npm install comment-mode
 ```
 
-### Basic usage
+### Basic usage (recommended)
+
+Wrap your app with **Commentator** so the comment surface (tap-to-pin area) and overlay are wired correctly with one component:
 
 ```tsx
-import { CommentProvider, CommentOverlay } from "comment-mode";
+import { Commentator } from "comment-mode";
 
 function App() {
   return (
-    <CommentProvider
+    <Commentator
       config={{
         projectSlug: "my-prototype",
         surfaceId: window.location.pathname,
       }}
     >
-      {/* your prototype UI */}
-      <CommentOverlay />
-    </CommentProvider>
+      {/* your prototype UI — taps here create comment pins when comment mode is on */}
+    </Commentator>
   );
 }
 ```
@@ -33,9 +34,27 @@ function App() {
 - **projectSlug** — Identifies your project (e.g. `"my-prototype"`).
 - **surfaceId** — Identifies the page/surface (e.g. `window.location.pathname`).
 
+Optional: **position** — `"left"` or `"right"` (default `"right"`) for where the comment panel appears.
+
+### Advanced: separate Provider, Surface, and Overlay
+
+If you need custom layout (e.g. only a specific canvas should receive pins), use the building blocks directly. **You must wrap the tappable area with CommentSurface** or taps will not create pins:
+
+```tsx
+import { CommentProvider, CommentSurface, CommentOverlay } from "comment-mode";
+
+<CommentProvider config={config}>
+  <CommentSurface>
+    {/* only this area receives tap-to-pin */}
+  </CommentSurface>
+  <CommentOverlay position="right" />
+</CommentProvider>
+```
 
 ### What you get
 
-- **CommentProvider** — Wraps your app and connects to the Comment Mode API.
-- **CommentOverlay** — Fullscreen overlay with a toggle, comment pins (threads), and a panel to view/add comments.
+- **Commentator** — One wrapper: Provider + Surface + Overlay (use for minimal setup).
+- **CommentProvider** — Connects to the Comment Mode API.
+- **CommentSurface** — The area that receives taps to create pins; must wrap the content that should be commentable.
+- **CommentOverlay** — Toggle, pins, and comment panel.
 - **useComments** — Hook for creating threads, loading comments, and adding replies.

package/dist/index.d.mts

@@ -3,6 +3,7 @@ import { SupabaseClient, User } from '@supabase/supabase-js';
 
 type CommentConfig = {
     projectSlug: string;
+    /** Identifies the surface (e.g. pathname or pathname+search for tabs). */
     surfaceId: string;
     /**
      * Optional override for the Comment Mode API base URL.
@@ -17,6 +18,26 @@ type CommentProviderProps = {
 };
 declare function CommentProvider(props: CommentProviderProps): JSX.Element;
 
+type CommentatorProps = {
+    /** Project and surface identifiers + optional API URL. */
+    config: CommentConfig;
+    /** Where the comment panel appears. Default `"right"`. */
+    position?: "left" | "right";
+    /** Optional style for the surface wrapper (the tappable area for pins). */
+    surfaceStyle?: React.CSSProperties;
+    /** Optional class for the surface wrapper. */
+    surfaceClassName?: string;
+    children: React.ReactNode;
+};
+/**
+ * All-in-one wrapper: Provider + Surface + Overlay. Use this for minimal setup
+ * so the area that receives taps is correctly wired for creating pins.
+ *
+ * If you need to customize layout (e.g. surface only around a canvas), use
+ * CommentProvider, CommentSurface, and CommentOverlay separately.
+ */
+declare function Commentator(props: CommentatorProps): JSX.Element;
+
 type CommentSurfaceProps = {
     children?: React.ReactNode;
     style?: React.CSSProperties;
@@ -44,7 +65,16 @@ type ThreadAnchor = {
 type Thread = {
     id: string;
     anchor: ThreadAnchor;
+    /** CSS selector to resolve the anchored element within the surface. When set, pin is shown only when element exists and visible. */
+    anchorSelector?: string | null;
+    /** Where within the element the user clicked (0..1). Used with anchorSelector so the pin stays at the exact click spot. */
+    anchorRelative?: {
+        x: number;
+        y: number;
+    } | null;
     status: "open" | "resolved";
+    /** Avatar URL of the first comment author (for pin display). */
+    firstCommentAuthorAvatarUrl?: string | null;
 };
 type Comment = {
     id: string;
@@ -52,6 +82,7 @@ type Comment = {
     body: string;
     createdAt?: string;
     authorName?: string | null;
+    authorAvatarUrl?: string | null;
 };
 
 declare function useComments(): {
@@ -60,9 +91,9 @@ declare function useComments(): {
     commentsByThread: Record<string, Comment[]>;
     isLoading: boolean;
     error: Error | null;
-    createThread: (anchor: ThreadAnchor, initialCommentBody?: string, initialAuthorName?: string | null) => Promise<Thread>;
+    createThread: (anchor: ThreadAnchor, initialCommentBody?: string, initialAuthorName?: string | null, anchorElement?: HTMLElement | null, initialAuthorAvatarUrl?: string | null) => Promise<Thread>;
     loadComments: (threadId: string) => Promise<void>;
-    addComment: (threadId: string, body: string, authorName?: string | null) => Promise<Comment>;
+    addComment: (threadId: string, body: string, authorName?: string | null, authorAvatarUrl?: string | null) => Promise<Comment>;
     deleteThread: (threadId: string) => Promise<void>;
 };
 
@@ -74,6 +105,8 @@ type AuthContextValue = {
     isReady: boolean;
     /** Resolved from GitHub: full_name, or username if name not set. Read-only. */
     displayName: string;
+    /** GitHub avatar URL from user_metadata, if available. */
+    avatarUrl: string | null;
     signInWithEmail: (email: string) => Promise<void>;
     signInWithGitHub: () => Promise<void>;
     signOut: () => Promise<void>;
@@ -81,4 +114,4 @@ type AuthContextValue = {
 
 declare function useCommentAuth(): AuthContextValue;
 
-export { type CommentConfig, CommentOverlay, type CommentOverlayProps, CommentProvider, type CommentProviderProps, CommentSettings, CommentSurface, type CommentSurfaceProps, useCommentAuth, useComments };
+export { type CommentConfig, CommentOverlay, type CommentOverlayProps, CommentProvider, type CommentProviderProps, CommentSettings, CommentSurface, type CommentSurfaceProps, Commentator, type CommentatorProps, useCommentAuth, useComments };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { SupabaseClient, User } from '@supabase/supabase-js';
 
 type CommentConfig = {
     projectSlug: string;
+    /** Identifies the surface (e.g. pathname or pathname+search for tabs). */
     surfaceId: string;
     /**
      * Optional override for the Comment Mode API base URL.
@@ -17,6 +18,26 @@ type CommentProviderProps = {
 };
 declare function CommentProvider(props: CommentProviderProps): JSX.Element;
 
+type CommentatorProps = {
+    /** Project and surface identifiers + optional API URL. */
+    config: CommentConfig;
+    /** Where the comment panel appears. Default `"right"`. */
+    position?: "left" | "right";
+    /** Optional style for the surface wrapper (the tappable area for pins). */
+    surfaceStyle?: React.CSSProperties;
+    /** Optional class for the surface wrapper. */
+    surfaceClassName?: string;
+    children: React.ReactNode;
+};
+/**
+ * All-in-one wrapper: Provider + Surface + Overlay. Use this for minimal setup
+ * so the area that receives taps is correctly wired for creating pins.
+ *
+ * If you need to customize layout (e.g. surface only around a canvas), use
+ * CommentProvider, CommentSurface, and CommentOverlay separately.
+ */
+declare function Commentator(props: CommentatorProps): JSX.Element;
+
 type CommentSurfaceProps = {
     children?: React.ReactNode;
     style?: React.CSSProperties;
@@ -44,7 +65,16 @@ type ThreadAnchor = {
 type Thread = {
     id: string;
     anchor: ThreadAnchor;
+    /** CSS selector to resolve the anchored element within the surface. When set, pin is shown only when element exists and visible. */
+    anchorSelector?: string | null;
+    /** Where within the element the user clicked (0..1). Used with anchorSelector so the pin stays at the exact click spot. */
+    anchorRelative?: {
+        x: number;
+        y: number;
+    } | null;
     status: "open" | "resolved";
+    /** Avatar URL of the first comment author (for pin display). */
+    firstCommentAuthorAvatarUrl?: string | null;
 };
 type Comment = {
     id: string;
@@ -52,6 +82,7 @@ type Comment = {
     body: string;
     createdAt?: string;
     authorName?: string | null;
+    authorAvatarUrl?: string | null;
 };
 
 declare function useComments(): {
@@ -60,9 +91,9 @@ declare function useComments(): {
     commentsByThread: Record<string, Comment[]>;
     isLoading: boolean;
     error: Error | null;
-    createThread: (anchor: ThreadAnchor, initialCommentBody?: string, initialAuthorName?: string | null) => Promise<Thread>;
+    createThread: (anchor: ThreadAnchor, initialCommentBody?: string, initialAuthorName?: string | null, anchorElement?: HTMLElement | null, initialAuthorAvatarUrl?: string | null) => Promise<Thread>;
     loadComments: (threadId: string) => Promise<void>;
-    addComment: (threadId: string, body: string, authorName?: string | null) => Promise<Comment>;
+    addComment: (threadId: string, body: string, authorName?: string | null, authorAvatarUrl?: string | null) => Promise<Comment>;
     deleteThread: (threadId: string) => Promise<void>;
 };
 
@@ -74,6 +105,8 @@ type AuthContextValue = {
     isReady: boolean;
     /** Resolved from GitHub: full_name, or username if name not set. Read-only. */
     displayName: string;
+    /** GitHub avatar URL from user_metadata, if available. */
+    avatarUrl: string | null;
     signInWithEmail: (email: string) => Promise<void>;
     signInWithGitHub: () => Promise<void>;
     signOut: () => Promise<void>;
@@ -81,4 +114,4 @@ type AuthContextValue = {
 
 declare function useCommentAuth(): AuthContextValue;
 
-export { type CommentConfig, CommentOverlay, type CommentOverlayProps, CommentProvider, type CommentProviderProps, CommentSettings, CommentSurface, type CommentSurfaceProps, useCommentAuth, useComments };
+export { type CommentConfig, CommentOverlay, type CommentOverlayProps, CommentProvider, type CommentProviderProps, CommentSettings, CommentSurface, type CommentSurfaceProps, Commentator, type CommentatorProps, useCommentAuth, useComments };