tiktok-comments 0.2.0 → 0.3.0

package/README.md

@@ -11,28 +11,15 @@ npm install tiktok-comments
 ## Usage (React SPA)
 
 ```tsx
-import { useState, useCallback } from "react";
-import { CommentSection } from "tiktok-comments";
-import type { Attachment, Comment } from "tiktok-comments";
+import { CommentSection, type CommentApiPayload } from "tiktok-comments";
 import "tiktok-comments/styles.css";
 
+function mapResponse(raw: unknown): CommentApiPayload {
+  return raw as CommentApiPayload;
+}
+
 export function VideoComments() {
-  const [comments, setComments] = useState<Comment[]>([]);
-
-  const handleSubmit = useCallback((text: string, attachment?: Attachment, replyTo?: string) => {
-    // persist to your API, then update state
-  }, []);
-
-  return (
-    <CommentSection
-      comments={comments}
-      currentUser={{ name: "You", avatar: "/avatar.png" }}
-      onSubmit={handleSubmit}
-      onLike={(id) => { /* ... */ }}
-      onLikeReply={(commentId, replyId) => { /* ... */ }}
-      theme="dark"
-    />
-  );
+  return <CommentSection url="/api/comments" response={mapResponse} theme="dark" />;
 }
 ```
 
@@ -49,29 +36,59 @@ Use the component in a client page or client component:
 ```tsx
 "use client";
 
-import { CommentSection } from "tiktok-comments";
+import { CommentSection, type CommentApiPayload } from "tiktok-comments";
 
 export default function CommentsPage() {
-  return <CommentSection comments={[]} onSubmit={() => {}} onLike={() => {}} onLikeReply={() => {}} />;
+  return <CommentSection url="/api/comments" response={(raw) => raw as CommentApiPayload} />;
 }
 ```
 
 ## API
 
-`CommentSection` is a controlled component. You own comment state and wire it to your backend.
+`CommentSection` fetches from `url`. Map your API JSON with `response`.
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `comments` | `Comment[]` | Comment list to render |
-| `currentUser` | `{ name, avatar }` | Shown in the input bar |
-| `onSubmit` | `(text, attachment?, replyTo?) => void` | New comment submitted |
-| `onLike` | `(commentId) => void` | Top-level comment liked |
-| `onLikeReply` | `(commentId, replyId) => void` | Reply liked |
-| `onReply` | `(commentId, username) => void` | Optional reply intent callback |
+| `url` | `string` | Comments resource, e.g. `/api/comments` |
+| `response` | `(raw: unknown) => CommentApiPayload` | Maps list and mutation JSON |
+| `endpoints` | `Partial<CommentSectionEndpoints>` | Per-route URL overrides; unset keys default from `url` (see below) |
 | `theme` | `"dark" \| "light"` | Default `"dark"` |
 | `className` | `string` | Extra classes on root |
+| `showThemeToggle` | `boolean` | Show theme toggle beside search. Default `false` |
+| `onThemeChange` | `(theme: "dark" \| "light") => void` | Called when user toggles theme (use with `theme` for controlled mode) |
+| `onViewProfile` | `(profile: CommentProfile) => void` | Optional host navigation for View profile (overrides `profile.profileUrl`) |
+| `onReportSticker` | `(src: string) => void` | Optional host handler when user reports a posted sticker |
+
+**`endpoints` defaults** (all derived from `url` unless overridden):
+
+| Key | Default | Method |
+|-----|---------|--------|
+| `list` | `url` | GET + `q`, `sort`, `offset`, `limit` |
+| `submit` | `url` | POST |
+| `likeComment(id)` | `{url}/{id}/like` | POST |
+| `dislikeComment(id)` | `{url}/{id}/dislike` | POST |
+| `likeReply(commentId, replyId)` | `{url}/{commentId}/replies/{replyId}/like` | POST |
+| `dislikeReply(commentId, replyId)` | `{url}/{commentId}/replies/{replyId}/dislike` | POST |
+| `users` | `{url}/users` | GET |
+| `userByName(name)` | `{url}/users?name=` | GET |
+| `stickers` | `{url}/stickers` | GET + query |
+| `stickerFavorite(id)` | `{url}/stickers/{id}/favorite` | POST |
+
+```tsx
+<CommentSection
+  url="/api/comments"
+  response={mapResponse}
+  endpoints={{
+    users: "/api/authors",
+    userByName: (name) => `/api/authors?name=${encodeURIComponent(name)}`,
+    stickers: "/api/sticker-catalog",
+  }}
+/>
+```
+
+Exported helpers: `defaultCommentSectionEndpoints`, `resolveCommentSectionEndpoints`, types `CommentSectionEndpoints`, `CommentSectionEndpointsConfig`.
 
-Exported types: `Comment`, `Reply`, `Attachment`, `CommentUser`, `EarnedBadge`, `SubscriptionTier`.
+Exported types: `Comment`, `Reply`, `Attachment`, `CommentUser`, `CommentProfile`, `EarnedBadge`, `SubscriptionTier`, `ReplyTarget`, `CommentSort`, `CommentApiPayload`.
 
 ## CSS isolation
 
@@ -81,7 +98,7 @@ All Tailwind utilities use the `tcm:` prefix (e.g. `tcm:flex`, `tcm:hover:tcm:bg
 
 ```bash
 npm install
-npm run dev        # demo playground
+npm run dev        # demo playground + in-memory mock API (`/api/comments`)
 npm run check      # typecheck + lint
 npm run build      # library + CSS to dist/
 ```

package/dist/components/badge-drawer.d.ts

@@ -2,6 +2,7 @@ import { EarnedBadge } from './comment-data';
 interface BadgeDrawerProps {
     badge: EarnedBadge;
     onClose: () => void;
+    className?: string;
 }
-export declare function BadgeDrawer({ badge, onClose }: BadgeDrawerProps): import("react").JSX.Element;
+export declare function BadgeDrawer({ badge, onClose, className }: BadgeDrawerProps): import("react").JSX.Element;
 export {};

package/dist/components/comment-data.d.ts

@@ -3,6 +3,18 @@ export interface CommentUser {
     name: string;
     avatar: string;
 }
+export interface CommentProfile extends CommentUser {
+    subscription?: SubscriptionTier;
+    badges?: string[];
+    /** Net score (e.g. likes minus downvotes on the user's comments). */
+    aura?: number;
+    commentCount?: number;
+    mangaReadCount?: number;
+    /** Leaderboard position (1 = top). */
+    rank?: number;
+    /** When set, View profile opens this URL (new tab). */
+    profileUrl?: string;
+}
 export interface EarnedBadge {
     id: string;
     lucideIcon: string;
@@ -12,6 +24,19 @@ export interface EarnedBadge {
     rarity: "common" | "rare" | "epic" | "legendary";
 }
 export declare const BADGE_CATALOG: EarnedBadge[];
+export interface StickerPack {
+    id: string;
+    icon: string;
+    name: string;
+}
+export interface StickerItem {
+    id: string;
+    url: string;
+    packId: string;
+    kind: "sticker" | "emoji";
+    label?: string;
+    favorited?: boolean;
+}
 export interface Reply {
     id: string;
     name: string;
@@ -19,6 +44,8 @@ export interface Reply {
     text: string;
     likes: number;
     liked: boolean;
+    disliked?: boolean;
+    /** ISO 8601 UTC instant. The library formats this for display. */
     timestamp: string;
     replyingTo?: string;
     image?: string;
@@ -32,6 +59,8 @@ export interface Comment {
     text: string;
     likes: number;
     liked: boolean;
+    disliked?: boolean;
+    /** ISO 8601 UTC instant. The library formats this for display. */
     timestamp: string;
     pinned?: boolean;
     replies: Reply[];

package/dist/components/comment-input-bar.d.ts

@@ -1,13 +1,27 @@
-import { CommentUser } from './comment-data';
+import { StickerFetchParams } from '../lib/comments-client';
+import { CommentProfile, CommentUser, StickerItem, StickerPack } from './comment-data';
 export interface Attachment {
     type: "image" | "sticker";
     url: string;
 }
+interface ReplyPreview {
+    username: string;
+    text: string;
+}
 interface CommentInputBarProps {
-    replyingTo: string | null;
+    replyingTo: ReplyPreview | null;
     onCancelReply: () => void;
     onSubmit: (text: string, attachment?: Attachment) => void;
     currentUser?: CommentUser;
+    mentionUsers?: CommentProfile[];
+    mentionUsersLoading?: boolean;
+    onOpenMentions?: () => void;
+    stickerPacks?: StickerPack[];
+    stickers?: StickerItem[];
+    stickersLoading?: boolean;
+    onFetchStickers?: (params: StickerFetchParams) => void;
+    onToggleStickerFavorite?: (id: string) => void;
+    onOpenStickers?: () => void;
 }
-export declare function CommentInputBar({ replyingTo, onCancelReply, onSubmit, currentUser }: CommentInputBarProps): import("react").JSX.Element;
+export declare function CommentInputBar({ replyingTo, onCancelReply, onSubmit, currentUser, mentionUsers, mentionUsersLoading, onOpenMentions, stickerPacks, stickers, stickersLoading, onFetchStickers, onToggleStickerFavorite, onOpenStickers, }: CommentInputBarProps): import("react").JSX.Element;
 export {};

package/dist/components/comment-item.d.ts

@@ -1,9 +1,16 @@
-import { Comment } from './comment-data';
+import { Comment, CommentProfile } from './comment-data';
 interface CommentItemProps {
     comment: Comment;
+    expandReplies?: boolean;
+    mentionNames: string[];
     onLike: (id: string) => void;
+    onDislike: (id: string) => void;
     onLikeReply: (commentId: string, replyId: string) => void;
-    onReply: (name: string) => void;
+    onDislikeReply: (commentId: string, replyId: string) => void;
+    onReply: (name: string, replyId: string | undefined, text: string) => void;
+    onMentionClick: (name: string) => Promise<CommentProfile | undefined>;
+    onViewProfile?: (profile: CommentProfile) => void;
+    onReportSticker?: (src: string) => void;
 }
-export declare function CommentItem({ comment, onLike, onLikeReply, onReply }: CommentItemProps): import("react").JSX.Element;
+export declare function CommentItem({ comment, expandReplies, mentionNames, onLike, onDislike, onLikeReply, onDislikeReply, onReply, onMentionClick, onViewProfile, onReportSticker, }: CommentItemProps): import("react").JSX.Element;
 export {};

package/dist/components/comment-section.d.ts

@@ -1,13 +1,31 @@
-import { Comment, CommentUser } from './comment-data';
-import { Attachment } from './comment-input-bar';
+import { CommentApiPayload, CommentSectionEndpointsConfig } from '../lib/comments-client';
+import { CommentProfile } from './comment-data';
+export type { CommentApiPayload, CommentSectionEndpoints, CommentSectionEndpointsConfig, CommentSort, StickerFetchParams, } from '../lib/comments-client';
+export interface ReplyTarget {
+    commentId: string;
+    replyId?: string;
+    username: string;
+    text: string;
+}
 export interface CommentSectionProps {
-    comments: Comment[];
-    currentUser?: CommentUser;
-    onSubmit: (text: string, attachment?: Attachment, replyTo?: string) => void;
-    onLike: (commentId: string) => void;
-    onLikeReply: (commentId: string, replyId: string) => void;
-    onReply?: (commentId: string, username: string) => void;
+    /** Comments resource, e.g. `/api/comments`. */
+    url: string;
+    /** Maps any server JSON into the library payload. */
+    response: (raw: unknown) => CommentApiPayload;
+    /**
+     * Optional per-route overrides. Unset keys default from `url`:
+     * list/submit → `url`; like → `{url}/{id}/like`; users → `{url}/users`; etc.
+     */
+    endpoints?: CommentSectionEndpointsConfig;
     className?: string;
     theme?: "dark" | "light";
+    /** Show theme toggle beside search. Default `false`. */
+    showThemeToggle?: boolean;
+    /** Called when the user toggles theme (controlled mode with `theme`). */
+    onThemeChange?: (theme: "dark" | "light") => void;
+    /** Host navigation when View profile is tapped (overrides `profile.profileUrl`). */
+    onViewProfile?: (profile: CommentProfile) => void;
+    /** Host moderation when a posted sticker is reported. */
+    onReportSticker?: (src: string) => void;
 }
-export declare function CommentSection({ comments, currentUser, onSubmit, onLike, onLikeReply, onReply, className, theme, }: CommentSectionProps): import("react").JSX.Element;
+export declare function CommentSection({ url, response, endpoints: endpointsConfig, className, theme, showThemeToggle, onThemeChange, onViewProfile, onReportSticker, }: CommentSectionProps): import("react").JSX.Element;

package/dist/components/image-picker.d.ts

@@ -0,0 +1,6 @@
+interface ImagePickerProps {
+    onSelect: (url: string) => void;
+    onClose: () => void;
+}
+export declare function ImagePicker({ onSelect, onClose }: ImagePickerProps): import("react").JSX.Element;
+export {};

package/dist/components/mention-selector.d.ts

@@ -1,6 +1,10 @@
+import { CommentProfile } from './comment-data';
 interface MentionSelectorProps {
-    onSelect: (username: string) => void;
+    users: CommentProfile[];
+    loading?: boolean;
+    onSelect: (name: string) => void;
+    onInsertEmoji: (emoji: string) => void;
     onClose: () => void;
 }
-export declare function MentionSelector({ onSelect, onClose }: MentionSelectorProps): import("react").JSX.Element;
+export declare function MentionSelector({ users, loading, onSelect, onInsertEmoji, onClose, }: MentionSelectorProps): import("react").JSX.Element;
 export {};

package/dist/components/profile-drawer.d.ts

@@ -1,10 +1,8 @@
-import { SubscriptionTier } from './comment-data';
+import { CommentProfile } from './comment-data';
 interface ProfileDrawerProps {
-    name: string;
-    avatar: string;
-    subscription?: SubscriptionTier;
-    badges?: string[];
+    profile: CommentProfile;
     onClose: () => void;
+    onViewProfile?: (profile: CommentProfile) => void;
 }
-export declare function ProfileDrawer({ name, avatar, subscription, badges, onClose }: ProfileDrawerProps): import("react").JSX.Element;
+export declare function ProfileDrawer({ profile, onClose, onViewProfile }: ProfileDrawerProps): import("react").JSX.Element;
 export {};

package/dist/components/reply-item.d.ts

@@ -1,8 +1,14 @@
-import { Reply } from './comment-data';
+import { Reply, CommentProfile } from './comment-data';
 interface ReplyListProps {
     replies: Reply[];
+    expandReplies?: boolean;
+    mentionNames: string[];
     onLikeReply: (replyId: string) => void;
-    onReply: (username: string) => void;
+    onDislikeReply: (replyId: string) => void;
+    onReply: (username: string, replyId: string | undefined, text: string) => void;
+    onMentionClick: (name: string) => Promise<CommentProfile | undefined>;
+    onViewProfile?: (profile: CommentProfile) => void;
+    onReportSticker?: (src: string) => void;
 }
-export declare function ReplyList({ replies, onLikeReply, onReply }: ReplyListProps): import("react").JSX.Element | null;
+export declare function ReplyList({ replies, expandReplies, mentionNames, onLikeReply, onDislikeReply, onReply, onMentionClick, onViewProfile, onReportSticker, }: ReplyListProps): import("react").JSX.Element | null;
 export {};

package/dist/components/sticker-drawer.d.ts

@@ -1,6 +1,7 @@
 interface StickerDrawerProps {
     src: string;
     onClose: () => void;
+    onReport?: (src: string) => void;
 }
-export declare function StickerDrawer({ src, onClose }: StickerDrawerProps): import("react").JSX.Element;
+export declare function StickerDrawer({ src, onClose, onReport }: StickerDrawerProps): import("react").JSX.Element;
 export {};

package/dist/components/sticker-selector.d.ts

@@ -1,6 +1,13 @@
+import { StickerFetchParams } from '../lib/comments-client';
+import { StickerItem, StickerPack } from './comment-data';
 interface StickerSelectorProps {
+    packs: StickerPack[];
+    stickers: StickerItem[];
+    loading?: boolean;
     onSelect: (stickerUrl: string) => void;
     onClose: () => void;
+    onFetchStickers: (params: StickerFetchParams) => void;
+    onToggleFavorite: (id: string) => void;
 }
-export declare function StickerSelector({ onSelect, onClose }: StickerSelectorProps): import("react").JSX.Element;
+export declare function StickerSelector({ packs, stickers, loading, onSelect, onClose, onFetchStickers, onToggleFavorite, }: StickerSelectorProps): import("react").JSX.Element;
 export {};