snapshot of https://github.com/tldraw/tldraw.git (main, 2026-09-23; blobs > 131072B omitted)

packages/commenting/api-report.api.md

@@ -0,0 +1,693 @@
+## API Report File for "@tldraw/commenting"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { Avatar } from '@tldraw/mentions';
+import { AvatarProps } from '@tldraw/mentions';
+import { CommentAuthor } from '@tldraw/mentions';
+import { ComponentType } from 'react';
+import { createMentionSuggestion } from '@tldraw/mentions';
+import { Editor } from 'tldraw';
+import { EditorAtom } from 'tldraw';
+import { filterMentionMembers } from '@tldraw/mentions';
+import { JSX } from 'react/jsx-runtime';
+import { KeyboardEvent as KeyboardEvent_2 } from 'react';
+import { Mention } from '@tldraw/mentions';
+import { MentionList } from '@tldraw/mentions';
+import { MentionListProps } from '@tldraw/mentions';
+import { MentionMember } from '@tldraw/mentions';
+import { MentionProps } from '@tldraw/mentions';
+import { MentionSuggestionOptions } from '@tldraw/mentions';
+import { MouseEvent as MouseEvent_2 } from 'react';
+import { ReactNode } from 'react';
+import { StateNode } from 'tldraw';
+import { TLComment } from 'tldraw';
+import { TLCommentAnchor } from 'tldraw';
+import { TLCommentId } from 'tldraw';
+import { TLCommentReaction } from 'tldraw';
+import { TLCommentReactionId } from 'tldraw';
+import { TLCommentThread } from 'tldraw';
+import { TLCommentThreadId } from 'tldraw';
+import { TLHistoryBatchOptions } from 'tldraw';
+import { TLRichText } from 'tldraw';
+import { TLShapeId } from 'tldraw';
+import { TLStateNodeConstructor } from 'tldraw';
+import { TLUiOverrides } from 'tldraw';
+import { VecLike } from 'tldraw';
+
+// @public
+export function anchorPagePoint(editor: Editor, anchor: TLCommentAnchor): {
+    x: number;
+    y: number;
+} | null;
+
+export { Avatar }
+
+export { AvatarProps }
+
+// @public
+export function Byline({ author, date, edited }: BylineProps): JSX.Element;
+
+// @public (undocumented)
+export interface BylineProps {
+    // (undocumented)
+    author: CommentAuthor;
+    date: string;
+    edited?: boolean;
+}
+
+// @public
+export function CanvasComments(props: CanvasCommentsProps): JSX.Element | null;
+
+// @public
+export type CanvasCommentsProps = CommentingContext;
+
+// @public
+export function CanvasCommentsSidebar(props: CanvasCommentsSidebarProps): JSX.Element | null;
+
+// @public
+export interface CanvasCommentsSidebarProps extends Pick<CommentingContext, 'currentUserId' | 'getThreadHref' | 'isCommentUnread' | 'resolveAuthor'> {
+    empty?: ReactNode;
+    header?: ReactNode;
+}
+
+export { CommentAuthor }
+
+// @public
+export function CommentBody({ richText, resolveName }: CommentBodyProps): JSX.Element;
+
+// @public (undocumented)
+export interface CommentBodyProps {
+    resolveName?(id: string): string | undefined;
+    // (undocumented)
+    richText: TLRichText;
+}
+
+// @public
+export function CommentCard({ author, body, date, you, edited, actions, footer, }: CommentCardProps): JSX.Element;
+
+// @public (undocumented)
+export interface CommentCardProps {
+    actions?: ReactNode;
+    // (undocumented)
+    author: CommentAuthor;
+    body: ReactNode;
+    date: string;
+    edited?: boolean;
+    footer?: ReactNode;
+    // (undocumented)
+    you: boolean;
+}
+
+// @public
+export function CommentComposer({ author, placeholder, value, onChange, onSubmit, sendLabel, onArrowUpWhenEmpty, disabled, autoFocus, leading, getMentionSuggestions, renderMentionSuggestion, }: CommentComposerProps): JSX.Element;
+
+// @public (undocumented)
+export interface CommentComposerProps {
+    // (undocumented)
+    author: CommentAuthor;
+    // (undocumented)
+    autoFocus?: boolean;
+    // (undocumented)
+    disabled?: boolean;
+    getMentionSuggestions?(query: string): MentionMember[] | Promise<MentionMember[]>;
+    leading?: ReactNode;
+    onArrowUpWhenEmpty?(): void;
+    // (undocumented)
+    onChange?(value: TLRichText): void;
+    onSubmit?(): void;
+    // (undocumented)
+    placeholder: string;
+    renderMentionSuggestion?(member: MentionMember): ReactNode;
+    // (undocumented)
+    sendLabel?: string;
+    value?: TLRichText;
+}
+
+// @public
+export interface CommentingComponents {
+    CommentBody?: ComponentType<{
+        comment: TLComment;
+    }>;
+    ComposerFallback?: ComponentType<{
+        context: 'pending' | 'thread';
+    }>;
+    PinContent?: ComponentType<{
+        comments: TLComment[];
+        thread: TLCommentThread;
+    }>;
+    ReactionContent?: ComponentType<{
+        token: string;
+    }>;
+    ReactionPalette?: ComponentType<EmojiPickerProps>;
+    ReactionTooltip?: ComponentType<ReactionTooltipProps>;
+    ThreadActions?: ComponentType<{
+        comments: TLComment[];
+        thread: TLCommentThread;
+    }>;
+    ThreadPreview?: ComponentType<{
+        comment: TLComment;
+    }>;
+    ThreadRow?: ComponentType<CommentListItemRenderProps & {
+        thread: TLCommentThread;
+    }>;
+}
+
+// @public
+export interface CommentingContext {
+    currentUserId: null | string;
+    getMentionSuggestions?(query: string): MentionMember[] | Promise<MentionMember[]>;
+    getThreadHref?(threadId: TLCommentThreadId): string | undefined;
+    isCommentUnread?(commentId: TLCommentId): boolean;
+    onCommentsRead?(commentIds: TLCommentId[]): void;
+    onPostComment?(comment: TLComment): void;
+    renderMentionSuggestion?(member: MentionMember): ReactNode;
+    resolveAuthor(id: string): CommentAuthor | undefined;
+}
+
+// @public
+export interface CommentingOptions {
+    readonly allowMultipleReactions: boolean;
+    readonly canComment: ((ctx: {
+        currentUserId: null | string;
+        editor: Editor;
+    }) => boolean) | undefined;
+    readonly canModifyComment: ((ctx: CommentModificationContext) => boolean) | undefined;
+    readonly components: CommentingComponents;
+    readonly dragHistory: TLHistoryBatchOptions['history'] | undefined;
+    readonly enableClustering: boolean;
+    readonly enableRegions: boolean;
+    readonly history: TLHistoryBatchOptions['history'];
+    readonly impreciseShapeAnchor: {
+        readonly x: number;
+        readonly y: number;
+    };
+    isAllowedReaction(token: string): boolean;
+    shouldBePrecise(editor: Editor, context: ShapeCommentPrecisionContext): boolean;
+}
+
+// @public
+export function CommentListItem({ id, author, preview, date, resolved, page, count, selected, reactions, href, resolvedLabel, onSelect, }: CommentListItemRenderProps): JSX.Element;
+
+// @public (undocumented)
+export interface CommentListItemProps {
+    // (undocumented)
+    author: CommentAuthor;
+    count?: number;
+    date: string;
+    href?: string;
+    // (undocumented)
+    id: string;
+    page?: string;
+    preview: ReactNode;
+    reactions?: ReactionSummary[];
+    // (undocumented)
+    resolved?: boolean;
+    selected?: boolean;
+}
+
+// @public
+export interface CommentListItemRenderProps extends CommentListItemProps {
+    onSelect?(id: string): void;
+    resolvedLabel?: string;
+}
+
+// @public
+export type CommentModification = {
+    readonly action: 'delete-comment';
+    readonly comment: TLComment;
+} | {
+    readonly action: 'delete-thread';
+    readonly thread: TLCommentThread;
+} | {
+    readonly action: 'edit-comment';
+    readonly comment: TLComment;
+};
+
+// @public
+export type CommentModificationContext = {
+    readonly currentUserId: null | string;
+    readonly editor: Editor;
+} & CommentModification;
+
+// @public
+export function CommentPin({ children, resolved, open }: CommentPinProps): JSX.Element;
+
+// @public (undocumented)
+export interface CommentPinProps {
+    children?: ReactNode;
+    open?: boolean;
+    // (undocumented)
+    resolved?: boolean;
+}
+
+// @public
+export function CommentReactionPicker({ comment, currentUserId, emoji, }: CommentReactionPickerProps): JSX.Element | null;
+
+// @public (undocumented)
+export interface CommentReactionPickerProps {
+    // (undocumented)
+    comment: TLComment;
+    currentUserId?: null | string;
+    emoji?: string[];
+}
+
+// @public
+export function CommentReactions({ comment, currentUserId, resolveName }: CommentReactionsProps): JSX.Element;
+
+// @public (undocumented)
+export interface CommentReactionsProps {
+    // (undocumented)
+    comment: TLComment;
+    currentUserId?: null | string;
+    resolveName?(userId: string): string | undefined;
+}
+
+// @public
+export function CommentsFilterMenu({ canFilterByAuthor, canFilterByUnread, }: CommentsFilterMenuProps): JSX.Element;
+
+// @public (undocumented)
+export interface CommentsFilterMenuProps {
+    canFilterByAuthor?: boolean;
+    canFilterByUnread?: boolean;
+}
+
+// @public
+export const commentsHidden: EditorAtom<boolean>;
+
+// @public
+export function CommentsList({ items, onSelect, header, headerAction, empty, resolvedLabel, renderItem, }: CommentsListProps): JSX.Element;
+
+// @public (undocumented)
+export interface CommentsListProps {
+    empty?: ReactNode;
+    header?: ReactNode;
+    headerAction?: ReactNode;
+    // (undocumented)
+    items: CommentListItemProps[];
+    onSelect?(id: string): void;
+    renderItem?(props: CommentListItemRenderProps): ReactNode;
+    resolvedLabel?: string;
+}
+
+// @public
+export function CommentsMenuItem(): JSX.Element;
+
+// @public
+export function CommentsOverflowMenu(): JSX.Element;
+
+// @public
+export const commentsSidebarOpen: EditorAtom<boolean>;
+
+// @public
+export function CommentsVisibilityToggle(): JSX.Element;
+
+// @public
+export function CommentThread({ comments, header, headerActions, resolvedBanner, composer, footer, renderComment, }: CommentThreadProps): JSX.Element;
+
+// @public (undocumented)
+export interface CommentThreadProps {
+    comments: CommentCardProps[];
+    composer?: CommentComposerProps;
+    footer?: ReactNode;
+    header?: ReactNode;
+    headerActions?: ReactNode;
+    renderComment?(comment: CommentCardProps, index: number): ReactNode;
+    resolvedBanner?: ReactNode;
+}
+
+// @public
+export class CommentTool extends StateNode {
+    // (undocumented)
+    static children(): TLStateNodeConstructor[];
+    static configure<T extends TLStateNodeConstructor>(this: T, options: T extends new (...args: any[]) => {
+        options: infer Options;
+    } ? Partial<Options> : never): T;
+    // (undocumented)
+    static id: string;
+    // (undocumented)
+    static initial: string;
+    // (undocumented)
+    onCancel(): void;
+    // (undocumented)
+    onEnter(): void;
+    // (undocumented)
+    onExit(): void;
+    options: CommentingOptions;
+}
+
+// @public
+export const commentToolOverrides: TLUiOverrides;
+
+// @public (undocumented)
+export const commentTools: (typeof CommentTool)[];
+
+// @public (undocumented)
+export function CountBadge({ count, open }: CountBadgeProps): JSX.Element;
+
+// @public (undocumented)
+export interface CountBadgeProps {
+    // (undocumented)
+    count: number;
+    open?: boolean;
+}
+
+export { createMentionSuggestion }
+
+// @public
+export const DEFAULT_REACTION_EMOJI: string[];
+
+// @public
+export const DEFAULT_SIDEBAR_FILTERS: SidebarFilters;
+
+// @public
+export function defaultCanModifyComment(ctx: CommentModificationContext): boolean;
+
+// @public
+export const defaultCommentingOptions: {
+    readonly allowMultipleReactions: true;
+    readonly canComment: undefined;
+    readonly canModifyComment: undefined;
+    readonly components: {};
+    readonly dragHistory: undefined;
+    readonly enableClustering: true;
+    readonly enableRegions: false;
+    readonly history: 'ignore';
+    readonly impreciseShapeAnchor: {
+        readonly x: 1;
+        readonly y: 0;
+    };
+    readonly isAllowedReaction: typeof isAllowedReactionEmoji;
+    readonly shouldBePrecise: () => true;
+};
+
+// @public
+export function DefaultReactionTooltip({ reactors, children }: ReactionTooltipProps): JSX.Element;
+
+// @public
+export function DefaultReactionTooltipContent({ reactors }: {
+    reactors: ReactionReactor[];
+}): JSX.Element | null;
+
+// @public
+export function defaultRenderReaction(token: string): ReactNode;
+
+// @public
+export function deleteComment(editor: Editor, comment: TLComment): void;
+
+// @public
+export function deleteThread(editor: Editor, thread: TLCommentThread): void;
+
+// @public
+export function editComment(editor: Editor, comment: TLComment, body: TLRichText): void;
+
+// @public
+export function EmojiPicker({ emoji, selected, onSelect, renderReaction, }: EmojiPickerProps): JSX.Element;
+
+// @public (undocumented)
+export interface EmojiPickerProps {
+    emoji?: string[];
+    onSelect?(emoji: string, event?: KeyboardEvent_2 | MouseEvent_2): void;
+    renderReaction?: RenderReaction;
+    selected?: string[];
+}
+
+// @public
+export function EmptyState({ message }: EmptyStateProps): JSX.Element;
+
+// @public (undocumented)
+export interface EmptyStateProps {
+    // (undocumented)
+    message: string;
+}
+
+export { filterMentionMembers }
+
+// @public
+export function focusThread(editor: Editor, thread: TLCommentThread): void;
+
+// @public
+export function formatFullDateTime(iso: string, locale?: string): string;
+
+// @public
+export function formatRelativeTime(iso: string, locale?: string): string;
+
+// @public
+export function getCanComment(editor: Editor, currentUserId: null | string | undefined): boolean;
+
+// @public
+export function getCanModifyComment(editor: Editor, currentUserId: null | string | undefined, modification: CommentModification): boolean;
+
+// @public
+export function getCommentingOptions(editor: Editor): CommentingOptions;
+
+// @public
+export function getCommentReactions(editor: Editor): TLCommentReaction[];
+
+// @public
+export function getCommentRecord(editor: Editor, id: string): TLCommentRecord | undefined;
+
+// @public
+export function getComments(editor: Editor): TLComment[];
+
+// @public
+export function getCommentThreads(editor: Editor): TLCommentThread[];
+
+// @public
+export function getLiveComments(editor: Editor): TLComment[];
+
+// @public
+export function getLiveCommentThreads(editor: Editor): TLCommentThread[];
+
+// @public
+export function getRevealThreadPending(editor: Editor): null | string;
+
+// @public
+export function isAllowedReactionEmoji(emoji: string, palette?: readonly string[]): boolean;
+
+// @public
+export function isOpenInNewTabClick(e: MouseEvent_2): boolean;
+
+export { Mention }
+
+export { MentionList }
+
+export { MentionListProps }
+
+export { MentionMember }
+
+export { MentionProps }
+
+export { MentionSuggestionOptions }
+
+// @public
+export const openThreadId: EditorAtom<null | string>;
+
+// @public
+export function putCommentRecords(editor: Editor, records: TLCommentRecord[]): void;
+
+// @public
+export function Reaction({ emoji, count, active, reactors, enableHoverList, renderReaction, ReactionTooltip, onClick, }: ReactionProps): JSX.Element;
+
+// @public
+export function ReactionPicker({ emoji, selected, onSelect, renderReaction, palette: Palette, menuId, className, }: ReactionPickerProps): JSX.Element;
+
+// @public (undocumented)
+export interface ReactionPickerProps {
+    className?: string;
+    emoji?: string[];
+    menuId?: string;
+    onSelect?(emoji: string): void;
+    palette?: ComponentType<EmojiPickerProps>;
+    renderReaction?: RenderReaction;
+    selected?: string[];
+}
+
+// @public (undocumented)
+export interface ReactionProps {
+    // (undocumented)
+    active: boolean;
+    // (undocumented)
+    count: number;
+    // (undocumented)
+    emoji: string;
+    enableHoverList?: boolean;
+    onClick?(): void;
+    ReactionTooltip?: ComponentType<ReactionTooltipProps>;
+    reactors: ReactionReactor[];
+    renderReaction?: RenderReaction;
+}
+
+// @public
+export interface ReactionReactor {
+    name: string;
+    you: boolean;
+}
+
+// @public
+export function Reactions({ reactions, onToggle, canReact, enableHoverList, renderReaction, ReactionTooltip, }: ReactionsProps): JSX.Element | null;
+
+// @public (undocumented)
+export interface ReactionsProps {
+    canReact?: boolean;
+    enableHoverList?: boolean;
+    onToggle?(emoji: string): void;
+    reactions: ReactionSummary[];
+    ReactionTooltip?: ComponentType<ReactionTooltipProps>;
+    renderReaction?: RenderReaction;
+}
+
+// @public
+export interface ReactionSummary {
+    active: boolean;
+    count: number;
+    // (undocumented)
+    emoji: string;
+    reactors: ReactionReactor[];
+}
+
+// @public
+export interface ReactionSummaryInput {
+    // (undocumented)
+    createdAt: number;
+    // (undocumented)
+    emoji: string;
+    // (undocumented)
+    userId: string;
+}
+
+// @public (undocumented)
+export interface ReactionTooltipProps {
+    children: ReactNode;
+    reactors: ReactionReactor[];
+}
+
+// @public
+export function registerCommentAnchorLifecycle(editor: Editor): () => void;
+
+// @public
+export function removeCommentRecords(editor: Editor, ids: (TLCommentId | TLCommentReactionId | TLCommentThreadId)[]): void;
+
+// @public
+export type RenderReaction = (token: string) => ReactNode;
+
+// @public
+export function reopenThread(editor: Editor, thread: TLCommentThread): void;
+
+// @public
+export function resolveThread(editor: Editor, thread: TLCommentThread, userId: string): void;
+
+// @public
+export function revealThread(editor: Editor, threadOrCommentId: string): void;
+
+// @public
+export function richTextToPlaintext(body: TLRichText, resolveName?: (id: string) => string | undefined): string;
+
+// @public
+export function SendButton({ label, disabled, onClick }: SendButtonProps): JSX.Element;
+
+// @public (undocumented)
+export interface SendButtonProps {
+    // (undocumented)
+    disabled?: boolean;
+    label: string;
+    // (undocumented)
+    onClick?(): void;
+}
+
+// @public
+export function shapeAnchorAt(editor: Editor, shapeId: TLShapeId, page: {
+    x: number;
+    y: number;
+}, precise: boolean): TLCommentAnchor;
+
+// @public
+export interface ShapeCommentPrecisionContext {
+    // (undocumented)
+    readonly altKey: boolean;
+    // (undocumented)
+    readonly point: VecLike;
+    // (undocumented)
+    readonly shapeId: TLShapeId;
+}
+
+// @public
+export interface SidebarFilters {
+    onlyCurrentPage: boolean;
+    onlyMine: boolean;
+    onlyUnread: boolean;
+    showResolved: boolean;
+}
+
+// @public
+export const sidebarFilters: EditorAtom<SidebarFilters>;
+
+// @public
+export interface SidebarRow {
+    // (undocumented)
+    item: CommentListItemProps;
+    lastActivity: number;
+}
+
+// @public
+export function sortSidebarRows(rows: readonly SidebarRow[]): readonly SidebarRow[];
+
+// @public
+export function summarizeReactions(reactions: readonly ReactionSummaryInput[], currentUserId?: null | string, resolveName?: (userId: string) => string | undefined): ReactionSummary[];
+
+// @public
+export type TLCommentRecord = TLComment | TLCommentReaction | TLCommentThread;
+
+// @public
+export function toggleCommentReaction(editor: Editor, comment: TLComment, userId: string, emoji: string, now?: number): void;
+
+// @public
+export function toggleCommentsHidden(editor: Editor): void;
+
+// @public
+export function toggleCommentsSidebar(editor: Editor): void;
+
+// @public
+export function useCanComment(currentUserId: null | string | undefined): boolean;
+
+// @public
+export function useCanModifyComment(currentUserId: null | string | undefined, modification: CommentModification): boolean;
+
+// @public
+export function useCommentingEnabled(): boolean;
+
+// @public
+export function useCommentingOptions(): CommentingOptions;
+
+// @public
+export function useCommentReactions(editor: Editor, commentId: TLComment['id']): TLCommentReaction[];
+
+// @public
+export function useComments(editor: Editor): TLComment[];
+
+// @public
+export function useCommentsHidden(): boolean;
+
+// @public
+export function useCommentsSidebarOpen(): boolean;
+
+// @public
+export function useCommentThreads(editor: Editor): TLCommentThread[];
+
+// @public
+export function useOpenThreadId(): null | string;
+
+// @public
+export function useRevealThreadPending(): null | string;
+
+// @public
+export function useSidebarFilters(): SidebarFilters;
+
+// @public
+export function useThreadComments(editor: Editor, threadId: TLCommentThreadId): TLComment[];
+
+// (No @packageDocumentation comment for this package)
+
+```