@vamos-ui/react 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,252 @@
+import * as React from "react";
+import { type LucideIcon } from "lucide-react";
+import { type AttachmentData } from "./attachment-list.js";
+export type MentionKind = "user" | "team" | "record";
+/** A suggestion in the `@` / `#` picker, and a resolved mention in a body. */
+export interface MentionItem {
+    id: string;
+    label: string;
+    kind: MentionKind;
+    /** Avatar photo (users) — teams and records get an icon. */
+    avatar?: string;
+    /** Second line in the picker ("Account executive", "Deal · $48,500"). */
+    description?: string;
+}
+/** Where `@` (or `#`) suggestions come from. Search is async; return at most ~8 items. */
+export interface MentionSource {
+    search: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+    /** Default `"@"`. */
+    trigger?: "@" | "#";
+}
+export interface ParsedMention {
+    id: string;
+    kind: MentionKind;
+    label: string;
+    /** Offsets in the plain `text` (start inclusive, end exclusive; includes the trigger). */
+    start: number;
+    end: number;
+    trigger: "@" | "#";
+}
+/** Turns a mention into its stored form: `@[Jane Cooper](user:42)`. */
+export declare function serializeMention(m: Pick<MentionItem, "id" | "label" | "kind">, trigger?: "@" | "#"): string;
+/**
+ * Reads a stored comment body. `text` is what people see ("@Jane Cooper can you check?");
+ * `mentions` carries ids and offsets into `text`. Locale-independent.
+ */
+export declare function parseMentions(body: string): {
+    text: string;
+    mentions: ParsedMention[];
+};
+export interface CommentAuthor {
+    id: string;
+    name: string;
+    avatar?: string;
+}
+export interface CommentReaction {
+    /** Key of a reaction in `reactions` of the thread (default set: like, agree, love, question, seen). */
+    key: string;
+    count: number;
+    /** The current user reacted. */
+    reacted?: boolean;
+    /** Names, for the tooltip ("Ayşe Kaya, Daniel Brooks"). */
+    users?: string[];
+}
+export interface CommentData {
+    id: string;
+    author: CommentAuthor;
+    /** Stored body with serialized mentions: `"@[Jane Cooper](user:42) can you check the totals?"`. */
+    body: string;
+    /** ISO instant. */
+    createdAt: string;
+    editedAt?: string;
+    /** Reply to this top-level comment (one nesting level). */
+    parentId?: string;
+    attachments?: AttachmentData[];
+    /** Top-level only: the discussion is closed and collapses. */
+    resolved?: boolean;
+    resolvedBy?: string;
+    /** Optimistic states while saving. */
+    status?: "sending" | "failed";
+    /** Soft-deleted: shows "This comment was deleted" when it has replies, hidden otherwise. */
+    deleted?: boolean;
+    reactions?: CommentReaction[];
+}
+export interface CommentSubmit {
+    body: string;
+    parentId?: string;
+    attachments: File[];
+    mentions: MentionItem[];
+}
+export interface ReactionOption {
+    key: string;
+    label: string;
+    icon: LucideIcon;
+}
+/** Default reaction set — icons, not emoji, so they follow the theme. */
+export declare const defaultReactions: ReactionOption[];
+export declare const commentLabels: {
+    thread: string;
+    empty: string;
+    emptyHint: string;
+    placeholder: string;
+    replyPlaceholder: string;
+    comment: string;
+    reply: string;
+    replyTo: string;
+    edit: string;
+    save: string;
+    cancel: string;
+    delete: string;
+    copyLink: string;
+    linkCopied: string;
+    resolve: string;
+    reopen: string;
+    resolved: string;
+    resolvedBy: string;
+    show: string;
+    hide: string;
+    replies: string;
+    edited: string;
+    editedAt: string;
+    deleted: string;
+    sending: string;
+    failed: string;
+    retry: string;
+    discard: string;
+    more: string;
+    attach: string;
+    mention: string;
+    submitHint: string;
+    submitError: string;
+    suggestions: string;
+    searching: string;
+    noMatch: string;
+    react: string;
+    reaction: string;
+    you: string;
+    commentBy: string;
+};
+export type CommentThreadLabels = Partial<typeof commentLabels>;
+export interface MentionChipProps extends React.HTMLAttributes<HTMLSpanElement> {
+    mention: Pick<ParsedMention, "label" | "kind"> & {
+        trigger?: "@" | "#";
+    };
+    /** Highlights a mention of the current user. */
+    self?: boolean;
+}
+/** Inline mention token inside a comment body. */
+export declare function MentionChip({ mention, self, className, ...props }: MentionChipProps): React.JSX.Element;
+export interface CommentBodyProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Stored body with serialized mentions. */
+    body: string;
+    currentUserId?: string;
+    renderMention?: (mention: ParsedMention) => React.ReactNode;
+}
+/** A comment's text: line breaks kept, mentions rendered as chips, mixed directions handled (`dir="auto"`). */
+export declare function CommentBody({ body, currentUserId, renderMention, className, ...props }: CommentBodyProps): React.JSX.Element;
+export interface CommentComposerProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "defaultValue"> {
+    onSubmit: (data: CommentSubmit) => void | Promise<void>;
+    onCancel?: () => void;
+    /** Stored body to start from (editing). */
+    defaultValue?: string;
+    parentId?: string;
+    mentionSources?: MentionSource[];
+    /** Paperclip button + chips. */
+    allowAttachments?: boolean;
+    placeholder?: string;
+    /** Submit button text. Default "Comment". */
+    submitLabel?: string;
+    /** Current user's avatar beside the box. */
+    author?: CommentAuthor;
+    autoFocus?: boolean;
+    /** `inline` (default) or `sticky-bottom` (pinned to the bottom of a scrolling panel). */
+    variant?: "inline" | "sticky-bottom";
+    /** Compact sizing for side panels. */
+    compact?: boolean;
+    labels?: CommentThreadLabels;
+}
+/**
+ * The comment box: a plain textarea with an `@` / `#` mention picker (combobox pattern:
+ * ↑/↓ move, Enter or Tab insert, Esc close), optional attachments, and ⌘/Ctrl+Enter to send.
+ * Picked mentions are stored as `@[Name](user:id)` in the submitted body.
+ */
+export declare const CommentComposer: React.ForwardRefExoticComponent<CommentComposerProps & React.RefAttributes<HTMLTextAreaElement>>;
+export interface CommentProps extends Omit<React.HTMLAttributes<HTMLElement>, "onSubmit"> {
+    comment: CommentData;
+    currentUserId?: string;
+    /** Shown as a reply (smaller avatar, no resolve). */
+    isReply?: boolean;
+    /** Show the Reply action. */
+    onReply?: () => void;
+    onEdit?: (id: string, body: string) => void | Promise<void>;
+    onDelete?: (id: string) => void | Promise<void>;
+    onResolve?: (id: string, resolved: boolean) => void | Promise<void>;
+    onRetry?: (comment: CommentData) => void;
+    onDiscard?: (comment: CommentData) => void;
+    onReact?: (id: string, key: string, on: boolean) => void;
+    /** Builds a permalink — shows "Copy link". */
+    getLink?: (comment: CommentData) => string;
+    reactions?: ReactionOption[];
+    mentionSources?: MentionSource[];
+    renderMention?: (mention: ParsedMention) => React.ReactNode;
+    onPreviewAttachment?: (file: AttachmentData) => void;
+    readOnly?: boolean;
+    compact?: boolean;
+    now?: Date | string | number;
+    labels?: CommentThreadLabels;
+    /** Replies / reply composer slot. */
+    children?: React.ReactNode;
+}
+/** One comment: avatar, author and time, body with mention chips, attachments, reactions and actions. An `<article>` labelled by its header. */
+export declare const Comment: React.ForwardRefExoticComponent<CommentProps & React.RefAttributes<HTMLElement>>;
+export interface CommentThreadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSubmit"> {
+    comments: CommentData[];
+    /** Own comments get Edit / Delete. */
+    currentUserId?: string;
+    /** Current user's avatar next to the composer. */
+    currentUser?: CommentAuthor;
+    /** Posting a new comment or reply. Without it (or with `readOnly`) there is no composer. */
+    onSubmit?: (data: CommentSubmit) => void | Promise<void>;
+    onEdit?: (id: string, body: string) => void | Promise<void>;
+    onDelete?: (id: string) => void | Promise<void>;
+    onResolve?: (id: string, resolved: boolean) => void | Promise<void>;
+    /** Failed (optimistic) comments: Retry / Discard. */
+    onRetry?: (comment: CommentData) => void;
+    onDiscard?: (comment: CommentData) => void;
+    /** Toggle a reaction. Shows the reaction picker. */
+    onReact?: (id: string, key: string, on: boolean) => void;
+    reactions?: ReactionOption[];
+    getLink?: (comment: CommentData) => string;
+    /** `@` people / teams and `#` records. */
+    mentionSources?: MentionSource[];
+    renderMention?: (mention: ParsedMention) => React.ReactNode;
+    onPreviewAttachment?: (file: AttachmentData) => void;
+    allowAttachments?: boolean;
+    /** Default `"oldest-first"` (conversation order). Replies are always oldest first. */
+    order?: "oldest-first" | "newest-first";
+    /** `thread` (full) or `compact` (side panel). Default `"thread"`. */
+    layout?: "thread" | "compact";
+    /** Composer position. Default `"inline"`. */
+    composer?: "inline" | "sticky-bottom" | "top";
+    readOnly?: boolean;
+    /** Pin the clock (docs, tests). */
+    now?: Date | string | number;
+    labels?: CommentThreadLabels;
+}
+/**
+ * Threaded discussion on a record: editorial notes on a post, CRM notes on a deal, feedback on
+ * a candidate. One reply level, @mentions with a picker, attachments, reactions, edit / delete,
+ * resolve & collapse, and optimistic sending / failed states. ARIA feed: PageUp / PageDown
+ * move between comments.
+ *
+ * ```tsx
+ * <CommentThread
+ *   comments={comments}
+ *   currentUserId="u1"
+ *   mentionSources={[{ search: searchPeople }]}
+ *   onSubmit={({ body, parentId }) => api.comment(dealId, { body, parentId })}
+ *   onResolve={(id, resolved) => api.resolve(id, resolved)}
+ * />
+ * ```
+ */
+export declare const CommentThread: React.ForwardRefExoticComponent<CommentThreadProps & React.RefAttributes<HTMLDivElement>>;