edytor 1.0.0-rc.3 → 2.0.0

package/dist/plugins/comments/CommentsSidebar.svelte

@@ -1,25 +1,36 @@
 <script lang="ts">
-	import { onMount, tick, type Snippet } from 'svelte';
-	import type { Action } from 'svelte/action';
+	import { onMount, type Snippet } from 'svelte';
 	import type { Edytor } from '../../edytor.svelte.js';
 	import { rangeRects } from '../../collaboration/remoteSelection.js';
+	import Ranges, { runOf } from '../../components/Ranges.svelte';
 	import { hidden } from '../../selection/visibility.js';
 	import type { CommentRun } from '../../crdt/protocols/comments.js';
-	import type { CommentsController } from './CommentsController.svelte.js';
+	import type { CommentsController, PlacedThread } from './CommentsController.svelte.js';
 	import type { CommentCardPayload } from './commentsPlugin.js';
+	import { commentsEnglish, labelsOf } from '../../labels.js';
 
+	/**
+	 * The comments' place in the overlay: the threads' highlight, the text of
+	 * the comment being written, and the sidebar beside the text (Notion's
+	 * margin; under its text on a narrow screen, the active one only) whose
+	 * cards the plugin's `card` snippet draws (the comment being written:
+	 * `thread` is `null`), under its `header` snippet.
+	 */
 	let {
 		edytor,
 		comments,
-		card
+		card,
+		header
 	}: {
 		edytor: Edytor;
 		comments: CommentsController;
-		/** Replace a thread card's markup (the plugin's `card` option). */
-		card?: Snippet<[CommentCardPayload]>;
+		/** A card's markup (the plugin's `card` option). */
+		card: Snippet<[CommentCardPayload]>;
+		/** The margin's top (the plugin's `header` option). */
+		header?: Snippet<[CommentsController]>;
 	} = $props();
 
-	const labels = $derived(comments.labels);
+	const labels = $derived(labelsOf(edytor, 'comments', commentsEnglish));
 
 	/** The sidebar's width, and the gap between the text and the sidebar, and between cards. */
 	const WIDTH = 288;
@@ -35,28 +46,27 @@
 		left: number;
 		/** Each placed card's position, by thread id (the draft's: `DRAFT`). */
 		cards: Record<string, { top: number; left: number }>;
-		/** The draft's text, highlighted until it is posted. */
-		draft: Rect[];
-		/** Where the resolved toggle sits. */
-		toggle: number;
+		/** Where the header sits. */
+		header: number;
 	};
 
-	let layout: Layout = $state.raw({ mode: 'margin', left: 0, cards: {}, draft: [], toggle: 0 });
+	let layout: Layout = $state.raw({ mode: 'margin', left: 0, cards: {}, header: 0 });
 	let container: HTMLElement | undefined = $state();
+	let top: HTMLElement | undefined = $state();
 
-	/** The runs' first line box, relative to the overlay: the text's own, else its block's. */
-	const anchorOf = (runs: CommentRun[], origin: DOMRect): Rect | null => {
+	/** A run's text boxes, relative to the overlay. */
+	const rectsOf = (run: CommentRun, origin: DOMRect): Rect[] =>
+		runOf(edytor, run.block, run.offset, run.length).flatMap(({ start, end }) =>
+			rangeRects(edytor, start, end, origin)
+		);
+
+	/** The runs' first line box, relative to the overlay: the text's own, else its block's, else the host's top. */
+	const anchorOf = (runs: CommentRun[], origin: DOMRect, top: number): Rect => {
 		for (const run of runs) {
 			const block = edytor.idToBlock.get(run.block);
 			if (!block) continue;
-			if (!hidden(block)) {
-				const [start, end] = [
-					block.textAtOffset(run.offset),
-					block.textAtOffset(run.offset + run.length)
-				];
-				const rect = start && end ? rangeRects(edytor, start, end, origin)[0] : undefined;
-				if (rect) return rect;
-			}
+			const rect = hidden(block) ? undefined : rectsOf(run, origin)[0];
+			if (rect) return rect;
 			const node = block.node?.closest('details:not([open])') ?? block.node;
 			if (!node) continue;
 			const box = node.getBoundingClientRect();
@@ -67,7 +77,7 @@
 				height: 20
 			};
 		}
-		return null;
+		return { left: 0, top, width: 0, height: 20 };
 	};
 
 	/**
@@ -83,38 +93,22 @@
 		const hostRect = host.getBoundingClientRect();
 		const margin = hostRect.right + GAP + WIDTH <= view.innerWidth - 8;
 		const draftRuns = comments.draft ? comments.draftRuns() : [];
-		const draft = draftRuns.flatMap((run) => {
-			const block = edytor.idToBlock.get(run.block);
-			const [start, end] = [
-				block?.textAtOffset(run.offset),
-				block?.textAtOffset(run.offset + run.length)
-			];
-			return start && end ? rangeRects(edytor, start, end, origin) : [];
-		});
 		const heights = new Map<string, number>();
 		for (const node of container.querySelectorAll<HTMLElement>('[data-edytor-comment-card]'))
 			heights.set(node.dataset.edytorCommentCard!, node.getBoundingClientRect().height);
 		const heightOf = (id: string) => heights.get(id) || 96;
 		const hostTop = hostRect.top - origin.top;
-		const items: Array<{ id: string; anchor: Rect }> = [];
-		if (comments.draft) {
-			const anchor = anchorOf(draftRuns, origin);
-			items.push({ id: DRAFT, anchor: anchor ?? { left: 0, top: hostTop, width: 0, height: 20 } });
-		}
 		const active = comments.draft ? DRAFT : comments.active;
-		for (const thread of comments.shown) {
-			if (!margin && thread.id !== active) continue;
-			const anchor = anchorOf(thread.runs, origin);
-			items.push({
-				id: thread.id,
-				anchor: anchor ?? { left: 0, top: hostTop, width: 0, height: 20 }
-			});
-		}
-		items.sort((a, b) => a.anchor.top - b.anchor.top);
+		const items = [
+			...(comments.draft ? [{ id: DRAFT, runs: draftRuns }] : []),
+			...comments.shown.filter((thread) => margin || thread.id === active)
+		]
+			.map(({ id, runs }) => ({ id, anchor: anchorOf(runs, origin, hostTop) }))
+			.sort((a, b) => a.anchor.top - b.anchor.top);
 		const cards: Layout['cards'] = {};
-		const left = margin ? hostRect.right - origin.left + GAP : 0;
 		if (margin) {
-			const floor = hostTop + (comments.resolved.length > 0 ? 36 : 0);
+			const head = top?.getBoundingClientRect().height ?? 0;
+			const floor = hostTop + (head ? head + SPACING : 0);
 			const at = items.findIndex((item) => item.id === active);
 			const place = (from: number, y: number) => {
 				for (let i = from; i < items.length; i++) {
@@ -147,10 +141,9 @@
 		}
 		const next: Layout = {
 			mode: margin ? 'margin' : 'popover',
-			left,
+			left: margin ? hostRect.right - origin.left + GAP : 0,
 			cards,
-			draft,
-			toggle: hostTop
+			header: hostTop
 		};
 		if (JSON.stringify(next) === JSON.stringify(layout)) return;
 		return () => (layout = next);
@@ -168,54 +161,16 @@
 	});
 
 	/**
-	 * What the sidebar shows: on a narrow screen only the active thread. A
-	 * card the overlay has not placed yet renders hidden until its frame.
+	 * The cards: the draft's first (`null`), then the threads; on a narrow
+	 * screen only the active thread. A card the overlay has not placed yet
+	 * renders hidden until its frame.
 	 */
-	const placed = $derived(
-		layout.mode === 'margin'
+	const cards: (PlacedThread | null)[] = $derived([
+		...(comments.draft ? [null] : []),
+		...(layout.mode === 'margin'
 			? comments.shown
-			: comments.shown.filter((thread) => thread.id === comments.active)
-	);
-
-	/**
-	 * A composer field: Enter posts (Shift+Enter is a new line), Escape
-	 * gives up; it takes the focus when it mounts if `focus`.
-	 */
-	const composer: Action<
-		HTMLTextAreaElement,
-		{ submit: (body: string) => Promise<boolean> | boolean; cancel?: () => void; focus?: boolean }
-	> = (node, initial) => {
-		let params = initial;
-		if (params.focus) void tick().then(() => node.focus({ preventScroll: true }));
-		const keydown = async (event: KeyboardEvent) => {
-			if (event.isComposing) return;
-			if (event.key === 'Escape' && params.cancel) {
-				event.preventDefault();
-				params.cancel();
-			} else if (event.key === 'Enter' && !event.shiftKey) {
-				event.preventDefault();
-				const body = node.value;
-				if (await params.submit(body)) {
-					node.value = '';
-					node.dispatchEvent(new Event('input', { bubbles: true }));
-				}
-			}
-		};
-		node.addEventListener('keydown', keydown);
-		return {
-			update: (next) => (params = next),
-			destroy: () => node.removeEventListener('keydown', keydown)
-		};
-	};
-
-	let draftBody = $state('');
-	const postDraft = async () => {
-		if (await comments.submit(draftBody)) draftBody = '';
-	};
-	const replies: Record<string, string> = $state({});
-	const postReply = async (thread: string) => {
-		if (await comments.reply(thread, replies[thread] ?? '')) replies[thread] = '';
-	};
+			: comments.shown.filter((thread) => thread.id === comments.active))
+	]);
 </script>
 
 <!-- The highlight of the threads' text: one stylesheet, never an attribute of the editor's own elements. -->
@@ -223,17 +178,14 @@
 	<svelte:element this={'style'} data-edytor-comments-style>{comments.css}</svelte:element>
 </svelte:head>
 
-<div data-edytor-comment-ranges aria-hidden="true">
-	{#each layout.draft as rect, index (index)}
-		<span
-			data-edytor-comment-draft
-			style:left={`${rect.left}px`}
-			style:top={`${rect.top}px`}
-			style:width={`${rect.width}px`}
-			style:height={`${rect.height}px`}
-		></span>
-	{/each}
-</div>
+<!-- The text of the comment being written, highlighted until it is posted. -->
+<Ranges
+	{edytor}
+	name="comment-draft"
+	z={17}
+	ranges={() =>
+		comments.draftRuns().flatMap((run) => runOf(edytor, run.block, run.offset, run.length))}
+/>
 
 <div
 	bind:this={container}
@@ -244,220 +196,51 @@
 	style:left={`${layout.left}px`}
 	style:--edytor-comments-width={`${WIDTH}px`}
 >
-	{#if layout.mode === 'margin' && comments.resolved.length > 0}
-		<button
-			type="button"
-			data-edytor-comments-toggle
-			style:top={`${layout.toggle}px`}
-			aria-pressed={comments.showResolved}
-			onclick={() => (comments.showResolved = !comments.showResolved)}
-			>{comments.showResolved
-				? labels.hideResolved
-				: labels.showResolved(comments.resolved.length)}</button
-		>
-	{/if}
-
-	{#if comments.draft}
-		<div
-			data-edytor-comment-card={DRAFT}
-			data-edytor-comment-new
-			data-active
-			data-unplaced={layout.cards[DRAFT] ? undefined : ''}
-			style:top={`${layout.cards[DRAFT]?.top ?? 0}px`}
-			style:left={`${layout.cards[DRAFT]?.left ?? 0}px`}
-		>
-			{#if comments.draft.quote}
-				<blockquote data-edytor-comment-quote>{comments.draft.quote}</blockquote>
-			{/if}
-			<div data-edytor-comment-composer>
-				<textarea
-					data-edytor-comment-field
-					rows="1"
-					placeholder={labels.placeholder}
-					aria-label={labels.placeholder}
-					bind:value={draftBody}
-					use:composer={{
-						submit: (body) => comments.submit(body),
-						cancel: comments.cancel,
-						focus: true
-					}}
-				></textarea>
-				<div data-edytor-comment-actions>
-					<button type="button" data-edytor-comment-cancel onclick={comments.cancel}
-						>{labels.cancel}</button
-					>
-					<button
-						type="button"
-						data-edytor-comment-post
-						disabled={!draftBody.trim()}
-						onclick={postDraft}>{labels.post}</button
-					>
-				</div>
-			</div>
-			{#if comments.error}<p data-edytor-comment-error role="alert">{labels.failed}</p>{/if}
+	{#if header && layout.mode === 'margin'}
+		<div bind:this={top} data-edytor-comments-header style:top={`${layout.header}px`}>
+			{@render header(comments)}
 		</div>
 	{/if}
 
-	{#each placed as thread (thread.id)}
-		{@const active = thread.id === comments.active}
-		<!-- A press on a card makes its thread the active one; its buttons and fields keep their keys. -->
-		<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_noninteractive_element_interactions -->
+	{#each cards as thread (thread?.id ?? DRAFT)}
+		{@const id = thread?.id ?? DRAFT}
+		{@const active = thread?.id === comments.active}
+		{@const at = layout.cards[id]}
+		<!-- A press on a thread's card makes it the active one; its buttons and fields keep their keys. -->
 		<div
-			data-edytor-comment-card={thread.id}
-			data-active={active || undefined}
-			data-resolved={thread.resolved ? '' : undefined}
-			data-unplaced={layout.cards[thread.id] ? undefined : ''}
-			role="article"
-			aria-label={labels.comment}
-			style:top={`${layout.cards[thread.id]?.top ?? 0}px`}
-			style:left={`${layout.cards[thread.id]?.left ?? 0}px`}
+			data-edytor-comment-card={id}
+			data-edytor-comment-new={thread ? undefined : ''}
+			data-active={thread ? active || undefined : ''}
+			data-resolved={thread?.resolved ? '' : undefined}
+			data-unplaced={at ? undefined : ''}
+			role={thread ? 'article' : undefined}
+			aria-label={thread ? labels.comment : undefined}
+			style:top={`${at?.top ?? 0}px`}
+			style:left={`${at?.left ?? 0}px`}
 			onclick={(event) => {
-				if (!(event.target as Element).closest('button, textarea')) comments.focus(thread.id);
+				if (thread && !(event.target as Element).closest('button, textarea'))
+					comments.focus(thread.id);
 			}}
 		>
-			{#if card}
-				{@render card({ thread, comments, active })}
-			{:else}
-				<div data-edytor-comment-head>
-					{#if thread.quote}
-						<blockquote data-edytor-comment-quote>{thread.quote}</blockquote>
-					{/if}
-					{#if comments.canComment}
-						{#if thread.resolved}
-							<button
-								type="button"
-								data-edytor-comment-reopen
-								title={labels.reopen}
-								onclick={() => comments.reopen(thread.id)}>{labels.reopen}</button
-							>
-						{:else}
-							<button
-								type="button"
-								data-edytor-comment-resolve
-								title={labels.resolve}
-								aria-label={labels.resolve}
-								onclick={() => comments.resolve(thread.id)}>✓</button
-							>
-						{/if}
-					{/if}
-				</div>
-				{#if thread.resolved}
-					<p data-edytor-comment-resolved>
-						{labels.resolvedBy(comments.userOf(thread.resolved.by).name!)}
-					</p>
-				{/if}
-				<ol data-edytor-comment-list>
-					{#each thread.comments as comment (comment.id)}
-						{@const author = comments.userOf(comment.author)}
-						<li data-edytor-comment={comment.id}>
-							<div data-edytor-comment-meta>
-								{#if author.avatar}
-									<img data-edytor-comment-avatar src={author.avatar} alt="" />
-								{:else}
-									<span
-										data-edytor-comment-avatar
-										style:background={author.color}
-										aria-hidden="true">{author.name!.slice(0, 1).toUpperCase()}</span
-									>
-								{/if}
-								<span data-edytor-comment-author>{author.name}</span>
-								<time data-edytor-comment-time datetime={new Date(comment.createdAt).toISOString()}
-									>{labels.when(comment.createdAt)}</time
-								>
-								{#if comments.mayDelete(thread, comment)}
-									<button
-										type="button"
-										data-edytor-comment-delete
-										title={labels.delete}
-										aria-label={labels.delete}
-										onclick={() =>
-											comments.remove(
-												thread.id,
-												comment.id === thread.comments[0]?.id ? undefined : comment.id
-											)}>×</button
-									>
-								{/if}
-							</div>
-							<p data-edytor-comment-body>{comment.body}</p>
-						</li>
-					{/each}
-				</ol>
-				{#if active && comments.canComment && !thread.resolved}
-					<div data-edytor-comment-composer>
-						<textarea
-							data-edytor-comment-reply
-							rows="1"
-							placeholder={labels.reply}
-							aria-label={labels.reply}
-							bind:value={replies[thread.id]}
-							use:composer={{ submit: (body) => comments.reply(thread.id, body) }}
-						></textarea>
-						{#if replies[thread.id]?.trim()}
-							<div data-edytor-comment-actions>
-								<button type="button" data-edytor-comment-post onclick={() => postReply(thread.id)}
-									>{labels.post}</button
-								>
-							</div>
-						{/if}
-					</div>
-				{/if}
-			{/if}
+			{@render card({ thread, comments, active })}
 		</div>
 	{/each}
 </div>
 
 <style>
-	[data-edytor-comment-ranges] {
-		position: absolute;
-		left: 0;
-		top: 0;
-		pointer-events: none;
-		z-index: 17;
-	}
-	[data-edytor-comment-draft] {
-		position: absolute;
-		background: var(--edytor-comment-active, rgb(255 212 0 / 0.42));
-		mix-blend-mode: multiply;
-	}
 	[data-edytor-comments] {
 		position: absolute;
 		top: 0;
 		width: 0;
 		z-index: 30;
-		font:
-			14px/1.45 ui-sans-serif,
-			-apple-system,
-			BlinkMacSystemFont,
-			'Segoe UI',
-			Helvetica,
-			sans-serif;
-		color: var(--edytor-comments-color, rgb(55 53 47));
-	}
-	[data-edytor-comments-toggle] {
-		position: absolute;
-		left: 0;
-		border: 0;
-		border-radius: 6px;
-		padding: 2px 8px;
-		background: transparent;
-		color: rgb(120 119 116);
-		font: inherit;
-		font-size: 13px;
-		cursor: pointer;
-	}
-	[data-edytor-comments-toggle]:hover {
-		background: rgb(55 53 47 / 0.08);
 	}
+	[data-edytor-comments-header],
 	[data-edytor-comment-card] {
 		position: absolute;
 		box-sizing: border-box;
 		width: var(--edytor-comments-width);
-		padding: 10px 12px;
-		border-radius: 8px;
-		background: var(--edytor-comments-background, #fff);
-		box-shadow:
-			rgb(15 15 15 / 0.05) 0 0 0 1px,
-			rgb(15 15 15 / 0.1) 0 3px 6px;
+	}
+	[data-edytor-comment-card] {
 		transition:
 			top 120ms ease,
 			left 120ms ease;
@@ -467,136 +250,4 @@
 		opacity: 0;
 		pointer-events: none;
 	}
-	[data-edytor-comment-card][data-active] {
-		box-shadow:
-			rgb(15 15 15 / 0.08) 0 0 0 1px,
-			rgb(15 15 15 / 0.16) 0 6px 14px;
-	}
-	[data-edytor-comment-card][data-resolved] {
-		opacity: 0.75;
-	}
-	[data-edytor-comment-head] {
-		display: flex;
-		align-items: flex-start;
-		gap: 6px;
-	}
-	[data-edytor-comment-quote] {
-		flex: 1;
-		margin: 0 0 6px;
-		padding-left: 8px;
-		border-left: 2px solid rgb(255 212 0 / 0.8);
-		color: rgb(120 119 116);
-		font-size: 13px;
-		overflow: hidden;
-		display: -webkit-box;
-		-webkit-line-clamp: 2;
-		line-clamp: 2;
-		-webkit-box-orient: vertical;
-	}
-	[data-edytor-comment-head] button,
-	[data-edytor-comment-delete] {
-		border: 0;
-		border-radius: 4px;
-		background: transparent;
-		color: rgb(120 119 116);
-		font: inherit;
-		font-size: 13px;
-		cursor: pointer;
-		padding: 0 6px;
-	}
-	[data-edytor-comment-head] button:hover,
-	[data-edytor-comment-delete]:hover {
-		background: rgb(55 53 47 / 0.08);
-	}
-	[data-edytor-comment-resolved] {
-		margin: 0 0 6px;
-		font-size: 12px;
-		color: rgb(120 119 116);
-	}
-	[data-edytor-comment-list] {
-		list-style: none;
-		margin: 0;
-		padding: 0;
-		display: flex;
-		flex-direction: column;
-		gap: 10px;
-	}
-	[data-edytor-comment-meta] {
-		display: flex;
-		align-items: center;
-		gap: 6px;
-	}
-	[data-edytor-comment-avatar] {
-		width: 20px;
-		height: 20px;
-		border-radius: 50%;
-		display: inline-flex;
-		align-items: center;
-		justify-content: center;
-		color: #fff;
-		font-size: 11px;
-		font-weight: 600;
-		object-fit: cover;
-	}
-	[data-edytor-comment-author] {
-		font-weight: 600;
-		font-size: 13px;
-	}
-	[data-edytor-comment-time] {
-		color: rgb(120 119 116);
-		font-size: 12px;
-	}
-	[data-edytor-comment-delete] {
-		margin-left: auto;
-	}
-	[data-edytor-comment-body] {
-		margin: 2px 0 0 26px;
-		white-space: pre-wrap;
-		overflow-wrap: anywhere;
-	}
-	[data-edytor-comment-composer] {
-		margin-top: 8px;
-	}
-	[data-edytor-comment-composer] textarea {
-		box-sizing: border-box;
-		width: 100%;
-		min-height: 32px;
-		resize: vertical;
-		border: 1px solid rgb(55 53 47 / 0.16);
-		border-radius: 6px;
-		padding: 6px 8px;
-		font: inherit;
-		color: inherit;
-		background: transparent;
-		field-sizing: content;
-	}
-	[data-edytor-comment-actions] {
-		display: flex;
-		justify-content: flex-end;
-		gap: 6px;
-		margin-top: 6px;
-	}
-	[data-edytor-comment-actions] button {
-		border: 0;
-		border-radius: 6px;
-		padding: 4px 10px;
-		font: inherit;
-		font-size: 13px;
-		cursor: pointer;
-		background: rgb(55 53 47 / 0.06);
-		color: inherit;
-	}
-	[data-edytor-comment-post] {
-		background: rgb(35 131 226) !important;
-		color: #fff !important;
-	}
-	[data-edytor-comment-post]:disabled {
-		opacity: 0.4;
-		cursor: default;
-	}
-	[data-edytor-comment-error] {
-		margin: 6px 0 0;
-		font-size: 12px;
-		color: rgb(212 76 71);
-	}
 </style>

package/dist/plugins/comments/CommentsSidebar.svelte.d.ts

@@ -5,8 +5,10 @@ import type { CommentCardPayload } from './commentsPlugin.js';
 type $$ComponentProps = {
     edytor: Edytor;
     comments: CommentsController;
-    /** Replace a thread card's markup (the plugin's `card` option). */
-    card?: Snippet<[CommentCardPayload]>;
+    /** A card's markup (the plugin's `card` option). */
+    card: Snippet<[CommentCardPayload]>;
+    /** The margin's top (the plugin's `header` option). */
+    header?: Snippet<[CommentsController]>;
 };
 declare const CommentsSidebar: import("svelte").Component<$$ComponentProps, {}, "">;
 type CommentsSidebar = ReturnType<typeof CommentsSidebar>;

package/dist/plugins/comments/commentsPlugin.d.ts

@@ -3,13 +3,21 @@ import type { Edytor } from '../../edytor.svelte.js';
 import type { Plugin } from '../../plugins.js';
 import type { CommentChange } from '../../crdt/protocols/comments.js';
 import type { CommentsClient } from '../../collaboration/comments/client.js';
-import { type PartialLabels } from '../../labels.js';
 import { CommentsController, type CommentNotice, type CommentUser, type PlacedThread } from './CommentsController.svelte.js';
-/** What a `card` snippet receives: one thread, the view's comments controller, and whether it is the active one. */
+/**
+ * What a `card` snippet receives: one thread (`null`: the comment being
+ * written, `comments.draft`), the view's comments controller, and whether
+ * it is the active one.
+ */
 export type CommentCardPayload = {
-    /** The thread, placed beside its text (its comments, its anchor's text, `resolved`). */
-    thread: PlacedThread;
-    /** The view's comments: the actions (reply, resolve, delete, `activate`), the user, `labels`. */
+    /**
+     * The thread, placed beside its text (its comments, its anchor's text,
+     * `resolved`); `null` for the comment being written (its text
+     * `comments.draft.quote`: post it with `comments.submit(body)`, give it
+     * up with `comments.cancel()`).
+     */
+    thread: PlacedThread | null;
+    /** The view's comments: the actions (reply, resolve, delete, `activate`), the user. */
     comments: CommentsController;
     /** It is the active thread (its text is selected, or its card was pressed). */
     active: boolean;
@@ -34,10 +42,18 @@ export type CommentsPluginOptions = {
      * it (in this view or another).
      */
     onComment?: (change: CommentChange, notice: CommentNotice) => void;
-    /** Replace a thread card's markup (the sidebar still places it). */
+    /**
+     * A card's markup: a thread's (its comments, a reply field, Resolve) or
+     * the comment being written (`thread: null`). The sidebar places each
+     * card beside its text; without it, no sidebar shows (the threads are
+     * still highlighted and kept).
+     */
     card?: Snippet<[CommentCardPayload]>;
-    /** The words the sidebar and the toolbar button show, over the English ones. */
-    labels?: PartialLabels<'comments'>;
+    /**
+     * The top of the sidebar's margin (Notion's "Show resolved"): the cards
+     * stack under it. Not shown on a narrow screen.
+     */
+    header?: Snippet<[CommentsController]>;
 };
 /** The comments plugin's controller of `edytor`; `undefined` when the plugin is not listed. */
 export declare const commentsController: (edytor: Edytor) => CommentsController | undefined;
@@ -48,6 +64,6 @@ export declare const commentsController: (edytor: Edytor) => CommentsController
  * merges and that copy and cut leave behind; its comments live in the
  * client's store (the room's `threads` and `comments` tables). Open threads
  * are highlighted, and a sidebar beside the text (under it, on a narrow
- * screen) shows each one with its replies, a composer, Resolve and Re-open.
+ * screen) places a `card` for each one.
  */
 export declare const createCommentsPlugin: (options: CommentsPluginOptions) => Plugin;