@nextgensoftwares/folio-plugin-comments

Google-Docs-style comments: anchored threads, margin rail, sidebar, host-configurable permissions, live updates, DOCX/PDF export. Guide: Comments plugin. The DOM- and React-free half (model, validation, policy, REST mapping, stores, schema) is also published as @nextgensoftwares/folio-plugin-comments/core for servers.

Plugin

Export	Signature	Description
commentsPlugin	(options?: CommentsPluginOptions) => CommentsPlugin	schema part, anchor index + paste guard PM plugins, Mod-Alt-m, the Comment item, highlight page layer + painter, overlay rail, sidebar and settings slots
type CommentsPlugin		FolioPlugin plus controller, setUser, setOptions, getOptions, setStore, forEditor(editor), docxComments(editor), pdfAnnotations(editor), subscribe
type CommentsPluginOptions		policy options plus user, store, mentionables, onMention, onError, canEditDocument, blockTypes, shortcut, rail, sidebar, settings, exportComments, reactions, highlight, typing, now
type LiveOptions		the options setOptions accepts (all but blockTypes, shortcut, sidebar, settings)
type MentionEvent		{ thread, comment, mentioned, by }
type SlotOption		boolean | { slot?, label?, order? }
CommentsController	class	options, user, policy, stores; forEditor, editorOf(state), run(editor, op), visible(), setOptions, setStore, subscribe
EditorComments	class	one editor's state: active, draft, mode, threads(), anchors(), startComment(), submitDraft(body), reply, edit, remove, resolve, react, jumpTo(id), typing, setActive, subscribe
type AnchorSpan		{ from, to, node } where a thread is anchored now
type Draft		{ id, target }: a comment being written
DEFAULT_REACTIONS, RAIL_WIDTH, RAIL_GAP	constants	['👍', '❤️', '🎉'], 272, 20

Model

Export	Description
type CommentUser	{ id, name, color?, avatarUrl?, role? } (role: 'reader' = reader by default)
type CommentAuthor	a user without role, as stored
type Comment	{ id, author, createdAt, editedAt?, body, mentions?, reactions? }
type CommentThread	Comment plus anchor, replies, resolved, resolvedBy?, resolvedAt?
type CommentAnchor	text (quote, positions, detached?, context), node (nodeType?, pos?) or point (pos, context)
type CommentOp	create, reply, edit, delete, resolve, react, anchor
type CommentAction	'view' | 'comment' | 'reply' | 'resolve' | 'edit' | 'delete' | 'react' | 'anchor'
CommentError	class; code: 'invalid' | 'not-found' | 'forbidden' | 'conflict'
applyOp	(threads, op, actor, now) => OpResult: the shared, validating reducer (client, store and server)
type OpResult	{ threads, threadId, thread } (thread null = deleted)
parseOp	validates an untrusted op (sanitized copy or CommentError)
findComment, authorOf	a thread's root or reply by id; a user as an author
sanitizeBody, sanitizeAnchor, sanitizeAuthor, sanitizeEmoji, isId	input hygiene (plain text, controls and bidi overrides removed, limits)
mentionsOf, bodyParts, mentionToken, MENTION	@[Name](id) mention tokens
COMMENT_LIMITS	body/quote/name/reply/reaction limits
newCommentId	random id

Permissions

Export	Description
type CommentPolicyOptions	readers, isReader, canView, canComment, canResolve, canEdit, canDelete, canReact
type ReaderAccess	'hidden' | 'view' | 'comment'
resolvePolicy	(options) => CommentPolicy with defaults; a throwing rule denies
type CommentPolicy	the resolved checks
authorizeOp	(policy, op, user, threads) => boolean
actionOf	the CommentAction an op needs

Stores

Export	Description
type CommentStore	threads(), subscribe, apply(op, actor), optional status, error, typing, typists, dispose
type CommentStoreStatus	'loading' | 'ready' | 'offline' | 'error'
MemoryCommentStore	in memory (replace(threads) too); type MemoryCommentStoreOptions
ServerCommentStore	REST + live events + ETag polling, optimistic with rollback; setLive(source), refresh(); type ServerCommentStoreOptions, type CommentLiveSource (onEvent, e.g. a CollabClient)
OptimisticThreads, type PendingOp	confirmed state + pending local ops, version-ordered
TypingBoard	typing indicators with expiry
opToRequest, requestToOp	the REST mapping (shared with the server); type CommentRequest
type CommentsSnapshot, type CommentWriteResult	{ version, threads }; { version, threadId, thread }
type CommentEvent, type CommentChangeEvent, type CommentTypingEvent, isCommentEvent	live events (kind: 'comments' | 'comments-typing')

Anchors

Export	Description
commentSchema	(blockTypes?) => Partial<SchemaSpec>: the comment mark (inclusive: false, excludes: '') and the commentIds block attr; servers add it to their schema
COMMENT_MARK, COMMENT_ATTR, COMMENT_META, DEFAULT_BLOCK_TYPES	'comment', 'commentIds', the plugin's transaction meta, default block types
AnchorIndex, anchorIndexPlugin, anchorsOf, anchorKey, updateIndex	the incremental anchor index (of(id), has(id), at(pos))
type AnchorRange	{ id, from, to, node }
pasteGuardPlugin	drops anchors of pasted copies (cut + paste moves them)
addAnchor, removeAnchor, anchorFor, targetOf, type AnchorTarget	anchor transactions and the selection's target
contextOf, findQuote, findPoint	quote/context capture and re-finding for floating anchors

UI helpers and export

Export	Description
stackCards, type CardSlot	the rail's overlap-free stacking around the active card
railFrame, type RailFrame	room for the rail (page shift, or collapse)
matchesShortcut, shortcutLabel	'Mod-Alt-m' matching and labels
relativeTime	"5 minutes ago"
COMMENTS_CSS, ensureCommentStyles	the stylesheet (injected once)
docxComments, type DocxThreadExport	threads for docxExportPlugin({ comments })
pdfAnnotations, type PdfAnnotationExport	annotations for pdfExportPlugin({ annotationsFor })
type ExportedComment	{ author, initials, text, date }