themelia-ui 2.0.1 → 3.0.0

package/docs/generated/components/features--comments.md

@@ -20,7 +20,7 @@ import "themelia-ui/features/comments.css"
 
 ## Optional peers
 
-Install these only when importing this family:
+Install these only when importing this module:
 
 ```bash
 npm install @tiptap/core @tiptap/pm @tiptap/starter-kit
@@ -28,7 +28,7 @@ npm install @tiptap/core @tiptap/pm @tiptap/starter-kit
 
 ## Composition
 
-This family composes `base/action-menu`, `base/avatar`, `base/badge`, `base/buttons`, `base/display`, `base/feedback`, `base/popover`, `base/spinner`, `base/structure`, `base/tooltip`, `base/typography`, `features/mentions`, `features/overlays`, `features/rich-text-editor`.
+This module composes `base/action-menu`, `base/avatar`, `base/badge`, `base/buttons`, `base/display`, `base/feedback`, `base/popover`, `base/spinner`, `base/structure`, `base/tooltip`, `base/typography`, `features/mentions`, `features/overlays`, `features/rich-text-editor`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -67,6 +67,10 @@ Kind: interface.
 
 Kind: callable.
 
+One file, in four states: staged, uploading, failed and posted. One row for all four,
+because a failed upload that looks different from a staged one is a row the reader has to
+learn twice — and finishing an upload never reflows.
+
 ```text
 ({ attachment, editable, onRemove, onRetry, accessors, strings, className, }: CommentAttachmentChipProps) => import("react").JSX.Element
 ```
@@ -172,6 +176,10 @@ Kind: interface.
 
 Kind: callable.
 
+A comment's body in whichever format it was stored — plain `text`, sanitised `html`, or a
+read-only `rich` block document. Three of them, because a comments table outlives any one
+editor and the rows written last year still have to render.
+
 ```text
 ({ comment, resources, renderReference, sanitizer, strings, className, }: CommentContentProps<TUser, TMeta, TResource>) => ReactNode
 ```
@@ -186,7 +194,7 @@ Kind: interface.
 | `resources` | no | `CommentsConfig<TUser, TMeta, TResource>["resources"]` |  |
 | `renderReference` | no | `CommentsSlots<TUser, TMeta, TResource>["renderReference"]` |  |
 | `sanitizer` | no | `(html: string) => string` | Replaces the kit's allow-list. There is no way to skip sanitising. |
-| `strings` | no | `Partial<CommentsStrings>` | Overrides this component's own copy — the quote attribution, so far. |
+| `strings` | no | `Partial<CommentsStrings>` | Overrides this component's own copy — the quote attribution. |
 | `className` | no | `string` |  |
 
 ### `CommentContentType`
@@ -251,6 +259,11 @@ Kind: interface.
 
 Kind: callable.
 
+One comment and the controls that act on it: the author, time and message in a bubble,
+reactions and Reply under it, everything else in the overflow menu beside it. Its replies
+hang off a rail from its avatar, so who answered whom is a line to follow rather than an
+indent to infer.
+
 ```text
 ({ comment, replies: suppliedReplies, canModerate, onDelete, onAttachmentRemove, onEdit, onPinToggle, onReact, onReply, allowReactions, allowReplies, commentActions, maxVisibleReplies, clampLines, maxVisibleAttachments, reactionChoices, sanitizer, strings, getMediaUrl, getMediaName, getStatusLabel, resources, renderAttachment, renderReference, className, }: CommentItemProps<TUser, TMeta, TResource>) => import("react").JSX.Element
 ```
@@ -311,6 +324,10 @@ Kind: interface.
 
 Kind: callable.
 
+The composer and the timeline, wired together. A control appears only when its callback is
+supplied (`onDelete`, `onUpdate`, …); `canComment`, `canModerate` and `allowReplies` cover
+viewer permission and thread shape.
+
 **Use when:** Compact comments or posts with replies and a composer.
 
 **Avoid when:** A feed of system events or mixed audit history.
@@ -348,7 +365,7 @@ Kind: interface.
 | `maxFiles` | no | `number` |  |
 | `accept` | no | `string` | Passed straight to the file input. |
 | `disabled` | no | `boolean` |  |
-| `onReject` | no | `(rejection: CommentAttachmentRejection) => void` | Receives a refusal before any upload starts. |
+| `onReject` | no | `(rejection: CommentAttachmentRejection) => void` | Receives a refusal before any upload starts, as a code and the number behind it — never a<br>sentence. The hook has no idea what language the reader speaks, and “too large” is useless<br>without the limit. |
 
 ### `CommentsComposerPosition`
 
@@ -393,30 +410,30 @@ Extends: `CommentsAccessors`, `CommentThreadOptions<TUser, TMeta, TResource>`, `
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `context` | yes | `CommentableContext` |  |
-| `comments` | yes | `ReadonlyArray<CommentData<TUser, TMeta, TResource>>` | In display order. Replies are nested by `replyToId`, not by position. |
+| `context` | yes | `CommentableContext` | What the thread hangs off: an `id` and a `type`, and a `moduleKey` where one record carries<br>several threads. Passed straight through to `onSubmit`. Changing it clears the draft — a<br>composer that stays mounted must not carry one record's text to the next. |
+| `comments` | yes | `ReadonlyArray<CommentData<TUser, TMeta, TResource>>` | Flat, in display order. Replies nest by `replyToId`, not by position, so one posted an hour<br>late still appears under its parent. A reply whose parent is not in the array is promoted<br>rather than dropped. |
 | `canComment` | no | `boolean` |  |
 | `canModerate` | no | `boolean` |  |
-| `composerPosition` | no | `CommentsComposerPosition` |  |
+| `composerPosition` | no | `CommentsComposerPosition` | Where the composer sits — a real per-thread decision: an activity log reads newest-first<br>and a discussion reads like a chat, and the same page can want both. Replies and edits open<br>inside the thread either way. |
 | `maxAttachments` | no | `number` |  |
 | `allowAttachments` | no | `boolean` |  |
 | `allowReactions` | no | `boolean` |  |
 | `allowReplies` | no | `boolean` |  |
 | `bare` | no | `boolean` | Drops the card chrome, for a thread already inside a panel. |
-| `title` | no | `ReactNode \| false` | `false` hides the title outright. |
-| `onSubmit` | no | `CommentsConfig<TUser, TMeta, TResource>["onSubmit"]` |  |
-| `onDelete` | no | `CommentsConfig<TUser, TMeta, TResource>["onDelete"]` |  |
-| `confirmDelete` | no | `boolean` | Asks before deleting. Off when the app already confirms upstream. |
+| `title` | no | `ReactNode \| false` | The heading. `false` hides it outright. |
+| `onSubmit` | no | `CommentsConfig<TUser, TMeta, TResource>["onSubmit"]` | Posts a comment or a reply. `helpers.reset()` is what clears the composer — a resolved<br>promise is not proof of success, and a server answering validation with a 200 would<br>otherwise throw away what the writer typed. |
+| `onDelete` | no | `CommentsConfig<TUser, TMeta, TResource>["onDelete"]` | Deletes a comment, after a confirmation unless `confirmDelete` is off. |
+| `confirmDelete` | no | `boolean` | Asks before deleting. The confirmation is opt-out because deleting takes the replies with<br>it; turn it off when the app already asks upstream. |
 | `onAttachmentRemove` | no | `(commentId: string, attachmentId: string) => void \| Promise<void>` |  |
-| `onUpdate` | no | `CommentsConfig<TUser, TMeta, TResource>["onUpdate"]` |  |
+| `onUpdate` | no | `CommentsConfig<TUser, TMeta, TResource>["onUpdate"]` | Saves an edit. As with `onSubmit`, `helpers.reset()` is what clears the composer. |
 | `onAfterMutate` | no | `CommentsConfig<TUser, TMeta, TResource>["onAfterMutate"]` |  |
 | `onError` | no | `CommentsConfig<TUser, TMeta, TResource>["onError"]` |  |
 | `onPinToggle` | no | `CommentsConfig<TUser, TMeta, TResource>["onPinToggle"]` |  |
 | `onReact` | no | `CommentsConfig<TUser, TMeta, TResource>["onReact"]` |  |
 | `onReply` | no | `CommentsConfig<TUser, TMeta, TResource>["onReply"]` |  |
-| `resources` | no | `CommentsConfig<TUser, TMeta, TResource>["resources"]` |  |
-| `onResourceSearch` | no | `CommentsConfig<TUser, TMeta, TResource>["onResourceSearch"]` |  |
-| `attachments` | no | `CommentsAttachmentsConfig` |  |
+| `resources` | no | `CommentsConfig<TUser, TMeta, TResource>["resources"]` | The mention registry, as `useMentions` takes it. Without it the reference control does not<br>appear. |
+| `onResourceSearch` | no | `CommentsConfig<TUser, TMeta, TResource>["onResourceSearch"]` | The fallback search, for a mention kind that registers neither `search` nor<br>`suggestions`. |
+| `attachments` | no | `CommentsAttachmentsConfig` | Uploads: `onUpload`, `maxSize`, `maxFiles`, `accept`. Without `onUpload` there is no<br>attachment control. The uploader resolves to a `CommentAttachment` with a permanent `url`;<br>the composer submits what it returns, not the file it was given. |
 | `sanitizer` | no | `CommentsConfig<TUser, TMeta, TResource>["sanitizer"]` |  |
 | `strings` | no | `Partial<CommentsStrings>` |  |
 | `className` | no | `string` |  |
@@ -432,8 +449,8 @@ Kind: interface.
 | `emptySlot` | no | `ReactNode` |  |
 | `headerSlot` | no | `ReactNode` |  |
 | `footerSlot` | no | `ReactNode` |  |
-| `renderItem` | no | `(context: CommentRenderItemContext<TUser, TMeta, TResource>) => ReactNode` |  |
-| `renderAttachment` | no | `(attachment: CommentAttachment) => ReactNode` |  |
+| `renderItem` | no | `(context: CommentRenderItemContext<TUser, TMeta, TResource>) => ReactNode` | Replaces a comment. It receives `defaultItem`, so a consumer can wrap the kit's comment<br>rather than rebuild it. |
+| `renderAttachment` | no | `(attachment: CommentAttachment) => ReactNode` | Replaces an attachment's chip. |
 | `renderReference` | no | `(reference: Mention<TResource>) => ReactNode` | Overrides the mention registry's own `renderChip`. |
 
 ### `CommentsStrings`
@@ -513,11 +530,11 @@ How a thread reads: what folds away and what a reader can do beyond reply and re
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `commentActions` | no | `ContextActionSource<CommentData<TUser, TMeta, TResource>>` | Extra entries for each comment's overflow menu, bound to the comment (`visible`,<br>`disabled` and `onClick` receive it). Listed above pin, edit and delete; `destructive` sorts last. |
-| `maxVisibleReplies` | no | `number` | Latest replies shown before earlier ones fold behind "Show N earlier replies". `0` shows all. @default 3 |
+| `commentActions` | no | `ContextActionSource<CommentData<TUser, TMeta, TResource>>` | Extra entries for each comment's overflow menu — copy a link, report, resolve. Bound to the<br>comment like a table row's actions: `visible` and `disabled` may be predicates, and<br>`onClick` receives the comment. They sit after pin and edit, before delete; a<br>`destructive` entry still sorts last. |
+| `maxVisibleReplies` | no | `number` | Replies an open thread shows; the earlier ones fold behind "Show N earlier replies". The<br>LAST ones are kept, so list replies oldest first. `0` shows them all. @default 3 |
 | `clampLines` | no | `number` | Lines of a long body shown before "See more" (measured, so short bodies get no control). `0` never clamps. @default 6 |
-| `maxVisibleAttachments` | no | `number` | Attachments shown before the rest fold behind "Show N more". `0` shows every file. @default 3 |
-| `reactionChoices` | no | `readonly string[]` | The reactions "Add reaction" offers. One reacts immediately; more open a picker. @default ["👍"] |
+| `maxVisibleAttachments` | no | `number` | Attachments shown before the rest fold behind "Show N more". Folding one file saves<br>nothing, so the fold starts at two hidden. `0` shows every file. @default 3 |
+| `reactionChoices` | no | `readonly string[]` | The reactions "Add reaction" offers. One reacts at once; more open a picker that marks the<br>reader's own. Every choice arrives through `onReact`. @default ["👍"] |
 
 ### `CommentTimeline`
 
@@ -568,6 +585,10 @@ Required<CommentsStrings>
 
 Kind: callable.
 
+The files staged on a draft and their uploads — the part with three things that are easy to
+get wrong: cancelling in flight, retrying one of several, and discarding a draft that still
+has uploads running.
+
 ```text
 (options?: UseAttachmentUploadOptions) => UseAttachmentUploadReturn
 ```
@@ -602,6 +623,10 @@ Kind: interface.
 
 Kind: callable.
 
+The state machine on its own — `composerMode`, `submit`, `deleteComment`, `resetKey` — for a
+fully custom thread. The mode is one union rather than three booleans, so “editing a reply
+while replying” cannot be represented.
+
 ```text
 (options?: UseCommentsOptions<TUser, TMeta, TResource>) => UseCommentsReturn<TUser, TMeta, TResource>
 ```
@@ -644,44 +669,303 @@ Preview route: Comments — `/comments`
 ### A thread
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Comments
-  context={{ id: "4417", type: "booking" }}
-  comments={comments}
-  canModerate
-  resources={resources}
-  onSubmit={async (values, helpers) => {
-    await post(values)
-    helpers.reset()
-  }}
-  onUpdate={update}
-  onDelete={remove}
-  onReact={react}
-  reactionChoices={["👍", "❤️", "🎉", "😄", "👀", "🎯"]}
-  commentActions={[
-    { id: "copy-link", label: "Copy link", icon: LinkIcon, onClick: copyLink },
-  ]}
-  attachments={{ onUpload, maxSize: 5_000_000, maxFiles: 3 }}
-/>
+import { LinkIcon } from "lucide-react"
+import { useCallback, useState } from "react"
+
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import {
+	Comments, type CommentAttachment, type CommentData, type CommentUser,
+} from "themelia-ui/features/comments"
+
+import { RESOURCES, SEED, type Kind } from "./data"
+
+/**
+ * A longer conversation for the main thread: a body past the clamp, more files than the
+ * fold shows, more replies than an open thread shows, and one reply answered in turn.
+ * Replies are listed oldest first, so the latest are the ones an open thread keeps.
+ */
+const CONVERSATION: CommentData<CommentUser, unknown, Kind>[] = [
+	{
+		id: "c4",
+		contentType: "text",
+		content: [
+			"Run-of-show for Marlow Hall, so everyone is working from the same page:",
+			"Doors at 18:00, welcome drinks on the terrace until 18:45. Dinner service starts at 19:00 sharp — the kitchen needs the final numbers by Wednesday noon or they plate for the contracted 120.",
+			"Speeches at 20:30, then the band until 23:30. The venue's hard curfew is midnight and the late-bar extension is not in the contract, so please do not promise it to the client.",
+			"Load-in for the band is through the service entrance from 15:00. Parking on site is limited to six vehicles; everyone else uses the public car park on Mill Lane.",
+			"Suppliers: florist sets up from 14:00, the cake arrives at 16:30 and goes straight to the cold room, and the photographer shoots the room before guests arrive.",
+			"Open items: the signed rider, the final dietary list, and confirmation of the second photographer.",
+		].join("\n"),
+		createdAt: "2026-08-25T08:30:00Z",
+		user: { id: "4", name: "Priya Raman" },
+		reactions: [{ emoji: "🙌", count: 2, users: ["Marcus Webb", "Maria Petrova"] }],
+		attachments: [
+			{ id: "a4", name: "run-of-show-v3.pdf", size: 96_256, mimeType: "application/pdf", url: "#" },
+			{ id: "a5", name: "floor-plan.png", size: 412_000, mimeType: "image/png", url: "#" },
+			{ id: "a6", name: "supplier-contacts.pdf", size: 38_912, mimeType: "application/pdf", url: "#" },
+			{ id: "a7", name: "parking-map.png", size: 221_184, mimeType: "image/png", url: "#" },
+			{ id: "a8", name: "menu-final.pdf", size: 64_512, mimeType: "application/pdf", url: "#" },
+		],
+	},
+	{
+		id: "r1",
+		contentType: "text",
+		content: "Agreed on the timings. I'll hold the balance invoice until the rider is back.",
+		createdAt: "2026-08-25T09:02:00Z",
+		user: { id: "2", name: "Marcus Webb" },
+		replyToId: "c4",
+	},
+	{
+		id: "r2",
+		contentType: "text",
+		content: "The rider is with their legal team. They promised it by Thursday.",
+		createdAt: "2026-08-25T09:40:00Z",
+		user: { id: "1", name: "Maria Petrova" },
+		replyToId: "c4",
+	},
+	{
+		id: "r2a",
+		contentType: "text",
+		content: "Thursday works — forward it the moment it lands, please.",
+		createdAt: "2026-08-25T10:05:00Z",
+		user: { id: "4", name: "Priya Raman" },
+		replyToId: "r2",
+	},
+	{
+		id: "r3",
+		contentType: "text",
+		content: "I've moved the catering tasting to next Tuesday so it doesn't clash with load-in.",
+		createdAt: "2026-08-25T11:15:00Z",
+		user: { id: "3", name: "Alice Mercer" },
+		replyToId: "c4",
+	},
+	{
+		id: "r4",
+		contentType: "text",
+		content: "Second photographer confirmed. Contact details are in the supplier sheet.",
+		createdAt: "2026-08-25T13:20:00Z",
+		user: { id: "2", name: "Marcus Webb" },
+		replyToId: "c4",
+		reactions: [{ emoji: "🎉", count: 1, users: ["Priya Raman"] }],
+	},
+	{
+		id: "r5",
+		contentType: "text",
+		content: "Signed rider received, attaching it here.",
+		createdAt: "2026-08-25T15:48:00Z",
+		user: { id: "1", name: "Maria Petrova" },
+		replyToId: "c4",
+		attachments: [
+			{ id: "a9", name: "rider-signed.pdf", size: 152_064, mimeType: "application/pdf", url: "#" },
+		],
+	},
+]
+
+/** The picker's choices. A single entry would react at once, as the default does. */
+const REACTION_CHOICES = ["👍", "❤️", "🎉", "😄", "👀", "🎯"]
+
+const uploadAttempts = new WeakMap<File, number>()
+
+/** A fake uploader, so failure and successful retry are both reachable. */
+function fakeUpload(file: File, onProgress: (n: number) => void, signal: AbortSignal) {
+	return new Promise<CommentAttachment>((resolve, reject) => {
+		let progress = 0
+		const tick = setInterval(() => {
+			progress += 20
+			onProgress(Math.min(progress, 100))
+			if (progress >= 100) {
+				clearInterval(tick)
+				const attempt = (uploadAttempts.get(file) ?? 0) + 1
+				uploadAttempts.set(file, attempt)
+				// A file named "fail" fails once; Retry then demonstrates actual recovery.
+				if (/fail/i.test(file.name) && attempt === 1) reject(new Error("The storage service refused it."))
+				else resolve({ id: "", name: file.name, size: file.size, mimeType: file.type, url: "#" })
+			}
+		}, 250)
+		signal.addEventListener("abort", () => {
+			clearInterval(tick)
+			reject(new DOMException("Aborted", "AbortError"))
+		})
+	})
+}
+
+export default function CommentsExample() {
+	const [comments, setComments] = useState([...SEED, ...CONVERSATION])
+	const [log, setLog] = useState<string[]>([])
+
+	const note = useCallback((line: string) => setLog((lines) => [line, ...lines].slice(0, 4)), [])
+
+	return (
+		<>
+			<Comments<CommentUser, unknown, Kind>
+				context={{ id: "4417", type: "booking" }}
+				comments={comments}
+				canModerate
+				resources={RESOURCES}
+				attachments={{
+					onUpload: ({ file, onProgress, signal }) => fakeUpload(file, onProgress, signal),
+					maxSize: 5_000_000,
+					maxFiles: 3,
+					accept: "image/*,application/pdf",
+				}}
+				reactionChoices={REACTION_CHOICES}
+				commentActions={[
+					{
+						id: "copy-link",
+						label: "Copy link",
+						icon: LinkIcon,
+						onClick: (comment) => {
+							const link = `${window.location.href.split("#")[0]}#/comments?comment=${comment.id}`
+							void navigator.clipboard?.writeText(link).catch(() => undefined)
+							note(`copied link to ${comment.id}`)
+						},
+					},
+				]}
+				onSubmit={(values, helpers) => {
+					const posted: CommentData<CommentUser, unknown, Kind> = {
+						id: `c${Date.now()}`,
+						contentType: "html",
+						content: values.content,
+						createdAt: new Date().toISOString(),
+						user: { id: "me", name: "You" },
+						references: values.references,
+						attachments: [...(values.attachments ?? [])],
+						replyToId: values.replyToId,
+					}
+					// A new thread goes to the top; a reply joins the end of its conversation.
+					setComments((prev) => (values.replyToId ? [...prev, posted] : [posted, ...prev]))
+					note(values.replyToId ? "replied" : "posted")
+					helpers.reset()
+				}}
+				onUpdate={(id, values, helpers) => {
+					setComments((prev) =>
+						prev.map((comment) =>
+							comment.id === id
+								? { ...comment, content: values.content, isEdited: true, references: values.references }
+								: comment,
+						),
+					)
+					note(`edited ${id}`)
+					helpers.reset()
+				}}
+				onDelete={(id) => {
+					setComments((prev) => prev.filter((comment) => comment.id !== id))
+					note(`deleted ${id}`)
+				}}
+				onPinToggle={(comment) => {
+					setComments((prev) =>
+						prev.map((item) =>
+							item.id === comment.id ? { ...item, isPinned: !item.isPinned } : item,
+						),
+					)
+					note(`${comment.isPinned ? "unpinned" : "pinned"} ${comment.id}`)
+				}}
+				onReact={(id, emoji) => {
+					setComments(prev => prev.map(comment => {
+						if (comment.id !== id) return comment
+						const current = comment.reactions?.find(reaction => reaction.emoji === emoji)
+						const reactions = current
+							? comment.reactions!.map(reaction => reaction.emoji === emoji
+								? { ...reaction, mine: !reaction.mine, count: reaction.count + (reaction.mine ? -1 : 1) }
+								: reaction).filter(reaction => reaction.count > 0)
+							: [...(comment.reactions ?? []), { emoji, count: 1, mine: true }]
+						return { ...comment, reactions }
+					}))
+					note(`reacted ${emoji} on ${id}`)
+				}}
+				getStatusLabel={(status) => (status === "pending_review" ? "Pending review" : undefined)}
+			/>
+
+			{log.length > 0 && (
+				<Stack gap="none">
+					{log.map((line, index) => (
+						<Text key={`${line}-${index}`} size="xs" type="secondary">
+							{line}
+						</Text>
+					))}
+				</Stack>
+			)}
+		</>
+	)
+}
 ```
 
 ### Submit failure and retry
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Comments
-  comments={comments}
-  onSubmit={async (values, helpers) => {
-    const result = await post(values)
-    if (!result.ok) {
-      helpers.setErrors({ content: result.message })
-      return
-    }
-    helpers.reset()
-  }}
-/>
+import { useState } from "react"
+
+import { Comments, type CommentData } from "themelia-ui/features/comments"
+
+export default function CommentsSubmitRecovery() {
+	const [comments, setComments] = useState<CommentData[]>([])
+	const [failedOnce, setFailedOnce] = useState(false)
+
+	return (
+		<Comments
+			bare
+			title={false}
+			context={{ id: "recovery", type: "booking" }}
+			comments={comments}
+			onSubmit={async (values, helpers) => {
+				await new Promise((resolve) => setTimeout(resolve, 600))
+				if (!failedOnce) {
+					setFailedOnce(true)
+					helpers.setErrors({ content: "The comment could not be saved. Try again." })
+					return
+				}
+				setComments([{
+					id: "recovered-comment",
+					content: values.content,
+					contentType: "html",
+					createdAt: new Date().toISOString(),
+					user: { id: "me", name: "You" },
+				}])
+				helpers.reset()
+			}}
+		/>
+	)
+}
+```
+
+### Three stored formats
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { Comments, type CommentUser } from "themelia-ui/features/comments"
+
+import { RESOURCES, SEED, type Kind } from "./data"
+
+export default function CommentsFormats() {
+	return (
+		<Comments<CommentUser, unknown, Kind>
+			bare
+			title={false}
+			context={{ id: "demo", type: "format" }}
+			// Flattened here: nesting the text one under the html one would hide it.
+			comments={SEED.map(({ replyToId: _replyToId, ...comment }) => comment)}
+			canComment={false}
+			resources={RESOURCES}
+			getStatusLabel={(status) => (status === "pending_review" ? "Pending review" : undefined)}
+		/>
+	)
+}
 ```
 
 ### Empty, and read-only
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Comments bare canComment={false} comments={[]} … />
+import { Comments } from "themelia-ui/features/comments"
+
+export default function CommentsEmpty() {
+	return (
+		<Comments
+			bare
+			title={false}
+			context={{ id: "empty", type: "booking" }}
+			comments={[]}
+			canComment={false}
+		/>
+	)
+}
 ```