themelia-ui 2.0.0 → 3.0.0

package/.agents/skills/themelia-ui/references/components/features--comments.md

@@ -1,687 +0,0 @@
-<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
-
-# `features/comments`
-
-People discuss a record in a thread, with a composer and attachments.
-
-## Selection
-
-- **Use when:** People discuss a record in a thread, with a composer and attachments.
-- **Avoid when:** The entries are system-generated, or the conversation is with an assistant.
-- **Consider instead:** `features/activities`, `features/ai-chat`
-- **Stability:** stable.
-
-## Import
-
-```tsx fragment — import-only example
-import { CommentAttachmentChip } from "themelia-ui/features/comments"
-import "themelia-ui/features/comments.css"
-```
-
-## Optional peers
-
-Install these only when importing this family:
-
-```bash
-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`.
-
-Application policy—routing, fetching, persistence, permissions, and translation—stays
-outside the package and arrives through the public props, callbacks, slots, or accessors below.
-
-## Public declarations
-
-### `CommentableContext`
-
-Kind: interface.
-
-What the comment is attached to.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `type` | yes | `string` |  |
-| `moduleKey` | no | `string` | A discriminator for an app that threads several kinds against one record. |
-
-### `CommentAttachment`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `name` | yes | `string` |  |
-| `url` | no | `string` | Absent while uploading — there is nothing to link to yet. |
-| `size` | no | `number` |  |
-| `mimeType` | no | `string` |  |
-| `thumbnailUrl` | no | `string` |  |
-| `status` | no | `CommentAttachmentStatus` |  |
-| `progress` | no | `number` | 0–100 while in flight. |
-| `error` | no | `string` | Why the upload failed, as the consumer's message. Kit-side rejections use `CommentAttachmentRejection` codes. |
-
-### `CommentAttachmentChip`
-
-Kind: callable.
-
-```text
-({ attachment, editable, onRemove, onRetry, accessors, strings, className, }: CommentAttachmentChipProps) => import("react").JSX.Element
-```
-
-### `CommentAttachmentChipProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `attachment` | yes | `CommentAttachment` |  |
-| `editable` | no | `boolean` | Reveals the remove control. |
-| `onRemove` | no | `(id: string) => void` |  |
-| `onRetry` | no | `(id: string) => void` |  |
-| `accessors` | no | `CommentsAccessors` |  |
-| `strings` | no | `Partial<CommentsStrings>` |  |
-| `className` | no | `string` |  |
-
-### `CommentAttachmentRejection`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `code` | yes | `CommentAttachmentRejectionCode` |  |
-| `file` | yes | `File` |  |
-| `limit` | yes | `number` | The limit that was exceeded — bytes for `too-large`, a count for `too-many`. |
-
-### `CommentAttachmentRejectionCode`
-
-Kind: type.
-
-Why the composer refused a file before any upload started: a code plus the limit, never a sentence.
-
-```text
-"too-large" | "too-many"
-```
-
-### `CommentAttachmentStatus`
-
-Kind: type.
-
-```text
-"uploading" | "uploaded" | "failed"
-```
-
-### `CommentAttachmentUploadContext`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `file` | yes | `File` |  |
-| `onProgress` | yes | `(progress: number) => void` | Call as the upload progresses. Throttling is the uploader's business. |
-| `signal` | yes | `AbortSignal` | Aborted when the chip is removed mid-upload. Pass it to fetch. |
-
-### `CommentComposer`
-
-Kind: callable.
-
-```text
-({ context, canComment, submitting, errors, resetKey, onSubmit, onCancel, editingComment, replyingTo, strings, resources, onResourceSearch, attachments: attachmentsConfig, maxAttachments, allowAttachments, initialValues, autoFocus, inlineSubmit, placeholder, className, ref, }: CommentComposerProps<TResource> & { ref?: Ref<CommentComposerHandle>; }) => import("react").JSX.Element | null
-```
-
-### `CommentComposerHandle`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `focus` | yes | `void` |  |
-| `clear` | yes | `void` |  |
-| `setBody` | yes | `void` |  |
-
-### `CommentComposerProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `context` | yes | `CommentableContext` |  |
-| `canComment` | no | `boolean` |  |
-| `submitting` | no | `boolean` | Shows the pending state and refuses a second submission. |
-| `errors` | no | `Record<string, string>` |  |
-| `resetKey` | no | `number` | Bumping it clears the draft. The composer is otherwise uncontrolled. |
-| `onSubmit` | yes | `(values: CommentFormValues<TResource>) => void \| Promise<void>` |  |
-| `onCancel` | no | `() => void` |  |
-| `editingComment` | no | `CommentData<CommentUser, unknown, TResource>` | Puts the composer in edit mode for that comment. |
-| `replyingTo` | no | `{ commentId: string; authorName?: string; }` | Names the comment being replied to. |
-| `strings` | no | `Partial<CommentsStrings>` |  |
-| `resources` | no | `Partial<Record<TResource, MentionResource<TResource>>>` |  |
-| `onResourceSearch` | no | `MentionsResourceSearch<TResource>` |  |
-| `attachments` | no | `CommentsAttachmentsConfig` |  |
-| `maxAttachments` | no | `number` |  |
-| `allowAttachments` | no | `boolean` |  |
-| `initialValues` | no | `Partial<CommentFormValues<TResource>>` |  |
-| `autoFocus` | no | `boolean` |  |
-| `inlineSubmit` | no | `boolean` | Puts submit on the toolbar instead of a footer row, for a new comment only (reply and edit keep the footer). Off by default. |
-| `placeholder` | no | `string` |  |
-| `className` | no | `string` |  |
-
-### `CommentContent`
-
-Kind: callable.
-
-```text
-({ comment, resources, renderReference, sanitizer, strings, className, }: CommentContentProps<TUser, TMeta, TResource>) => ReactNode
-```
-
-### `CommentContentProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `comment` | yes | `CommentData<TUser, TMeta, TResource>` |  |
-| `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. |
-| `className` | no | `string` |  |
-
-### `CommentContentType`
-
-Kind: type.
-
-`string & {}` keeps the union open: an app may store a format the kit does not know.
-
-```text
-"text" | "html" | "rich" | (string & {})
-```
-
-### `CommentData`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | no | `string` |  |
-| `content` | no | `string` |  |
-| `contentType` | no | `CommentContentType` |  |
-| `createdAt` | no | `string` |  |
-| `updatedAt` | no | `string` |  |
-| `user` | no | `TUser` |  |
-| `status` | no | `string` | A moderation or workflow state, shown beside the timestamp. |
-| `isPinned` | no | `boolean` |  |
-| `isEdited` | no | `boolean` |  |
-| `canDelete` | no | `boolean` | Per-comment permission override. `undefined` defers to the thread's `canModerate`; `false` refuses regardless. |
-| `canEdit` | no | `boolean` |  |
-| `tagsArray` | no | `string[] \| Record<string, string>` |  |
-| `attachments` | no | `Array<CommentAttachment \| null>` | `null` entries survive a sparse array from an API and are skipped. |
-| `references` | no | `ReadonlyArray<Mention<TResource>>` | The mentions in the body, stored beside it. See features/mentions. |
-| `reactions` | no | `ReadonlyArray<CommentReaction>` |  |
-| `replyToId` | no | `string` | Threading. The id of the comment this replies to. |
-| `meta` | no | `TMeta` |  |
-
-### `CommentDeleteMutationPayload`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `commentId` | yes | `string` |  |
-
-### `CommentFormValues`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `content` | yes | `string` |  |
-| `commentableId` | yes | `string` |  |
-| `commentableType` | yes | `string` |  |
-| `moduleKey` | no | `string` |  |
-| `contentType` | no | `CommentContentType` |  |
-| `references` | no | `ReadonlyArray<Mention<TResource>>` |  |
-| `attachments` | no | `ReadonlyArray<CommentAttachment>` | Already uploaded. The composer does not submit a file still in flight. |
-| `replyToId` | no | `string` |  |
-| `editingId` | no | `string` |  |
-
-### `CommentItem`
-
-Kind: callable.
-
-```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
-```
-
-### `CommentItemProps`
-
-Kind: interface.
-
-Extends: `CommentDisplayProps<TUser, TMeta, TResource>`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `comment` | yes | `CommentData<TUser, TMeta, TResource>` |  |
-| `replies` | no | `ReadonlyArray<CommentData<TUser, TMeta, TResource>>` | Replies to this comment, when the thread is nested. |
-| `className` | no | `string` |  |
-
-### `CommentMutationKind`
-
-Kind: type.
-
-```text
-"create" | "update" | "delete"
-```
-
-### `CommentMutationPayload`
-
-Kind: type.
-
-```text
-CommentFormValues<TResource> | CommentDeleteMutationPayload
-```
-
-### `CommentReaction`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `emoji` | yes | `string` | An emoji or a short token. |
-| `count` | yes | `number` |  |
-| `mine` | no | `boolean` | Whether the viewer is one of them. |
-| `users` | no | `string[]` | Names behind the count, for the tooltip. |
-
-### `CommentRenderItemContext`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `comment` | yes | `CommentData<TUser, TMeta, TResource>` |  |
-| `canModerate` | yes | `boolean` |  |
-| `onDelete` | no | `(commentId: string) => void` |  |
-| `onAttachmentRemove` | no | `(commentId: string, attachmentId: string) => void` |  |
-| `onEdit` | no | `(comment: CommentData<TUser, TMeta, TResource>) => void` |  |
-| `defaultItem` | yes | `ReactNode` | The item the kit would have rendered — for wrapping rather than replacing. |
-
-### `Comments`
-
-Kind: callable.
-
-**Use when:** Compact comments or posts with replies and a composer.
-
-**Avoid when:** A feed of system events or mixed audit history.
-
-**Compose:** Use the ready Comments surface before its parts or useComments; the app owns persistence and permissions.
-
-**Capabilities:** compact comments replies posts; discussion composer attachments.
-
-**Alternatives:** ActivityFeed, ActivityLog.
-
-```text
-(props: CommentsProps<TUser, TMeta, TResource>) => import("react").JSX.Element
-```
-
-### `CommentsAccessors`
-
-Kind: interface.
-
-The domain mapping. Each has a default; each exists for a shape the kit cannot guess.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `getMediaUrl` | no | `(media: CommentAttachment \| null \| undefined) => string \| undefined` |  |
-| `getMediaName` | no | `(media: CommentAttachment \| null \| undefined) => string \| undefined` |  |
-| `getStatusLabel` | no | `(status: string) => string \| undefined` | Turns `comment.status` into something a reader recognises. |
-
-### `CommentsAttachmentsConfig`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `onUpload` | no | `(context: CommentAttachmentUploadContext) => Promise<CommentAttachment>` | The uploader; without it the attachment control does not appear. Must resolve to a<br>`CommentAttachment` with a permanent `url` — that, not the file, is what gets submitted. |
-| `maxSize` | no | `number` | In bytes. |
-| `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. |
-
-### `CommentsComposerPosition`
-
-Kind: type.
-
-Where the composer sits: `top` for a newest-first feed, `bottom` for a chat-like conversation.
-
-```text
-"top" | "bottom"
-```
-
-### `CommentsConfig`
-
-Kind: interface.
-
-Extends: `CommentsAccessors`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `composerPosition` | no | `CommentsComposerPosition` |  |
-| `strings` | no | `Partial<CommentsStrings>` |  |
-| `resources` | no | `Partial<Record<TResource, MentionResource<TResource>>>` |  |
-| `onResourceSearch` | no | `MentionsResourceSearch<TResource>` |  |
-| `attachments` | no | `CommentsAttachmentsConfig` |  |
-| `canComment` | no | `boolean` |  |
-| `canModerate` | no | `boolean` |  |
-| `onSubmit` | no | `(values: CommentFormValues<TResource>, helpers: CommentSubmitHelpers) => void \| Promise<void>` |  |
-| `onDelete` | no | `(commentId: string) => void \| Promise<void>` |  |
-| `onUpdate` | no | `(commentId: string, values: CommentFormValues<TResource>, helpers: CommentSubmitHelpers) => void \| Promise<void>` |  |
-| `onAfterMutate` | no | `(kind: CommentMutationKind, payload: CommentMutationPayload<TResource>) => void` | Fires after a mutation callback settles without throwing. |
-| `onError` | no | `(error: unknown) => void` | Receives a rejected mutation, so a failure never escapes through a DOM event. |
-| `onPinToggle` | no | `(comment: CommentData<TUser, TMeta, TResource>) => void` |  |
-| `onReact` | no | `(commentId: string, emoji: string) => void` |  |
-| `onReply` | no | `(commentId: string) => void` |  |
-| `sanitizer` | no | `(html: string) => string` | Replaces the kit's allow-list. There is no way to render unsanitised HTML. |
-
-### `CommentsProps`
-
-Kind: interface.
-
-Extends: `CommentsAccessors`, `CommentThreadOptions<TUser, TMeta, TResource>`, `CommentsSlots<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. |
-| `canComment` | no | `boolean` |  |
-| `canModerate` | no | `boolean` |  |
-| `composerPosition` | no | `CommentsComposerPosition` |  |
-| `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. |
-| `onAttachmentRemove` | no | `(commentId: string, attachmentId: string) => void \| Promise<void>` |  |
-| `onUpdate` | no | `CommentsConfig<TUser, TMeta, TResource>["onUpdate"]` |  |
-| `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` |  |
-| `sanitizer` | no | `CommentsConfig<TUser, TMeta, TResource>["sanitizer"]` |  |
-| `strings` | no | `Partial<CommentsStrings>` |  |
-| `className` | no | `string` |  |
-| `avatarComponent` | no | `ComponentType<{ user: TUser \| undefined; }>` | Replaces the generated avatar — for an app whose authors have presence or a badge. |
-
-### `CommentsSlots`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `composerSlot` | no | `ReactNode` |  |
-| `emptySlot` | no | `ReactNode` |  |
-| `headerSlot` | no | `ReactNode` |  |
-| `footerSlot` | no | `ReactNode` |  |
-| `renderItem` | no | `(context: CommentRenderItemContext<TUser, TMeta, TResource>) => ReactNode` |  |
-| `renderAttachment` | no | `(attachment: CommentAttachment) => ReactNode` |  |
-| `renderReference` | no | `(reference: Mention<TResource>) => ReactNode` | Overrides the mention registry's own `renderChip`. |
-
-### `CommentsStrings`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `formatQuoteAttribution` | yes | `(caption: string) => string` | Attribution under a quoted block — "— Ada Lovelace". The dash is part of the translatable string. |
-| `title` | yes | `string` |  |
-| `subtitle` | yes | `string` |  |
-| `empty` | yes | `string` |  |
-| `emptyHint` | yes | `string` |  |
-| `composerPlaceholder` | yes | `string` |  |
-| `composerSubmit` | yes | `string` |  |
-| `composerSubmitting` | yes | `string` |  |
-| `composerSave` | yes | `string` | The submit label in edit mode — "Save changes", not "Post". |
-| `composerCancel` | yes | `string` |  |
-| `invalidContent` | yes | `string` |  |
-| `composerEditingEyebrow` | yes | `string` |  |
-| `formatReplyingEyebrow` | yes | `(name: string) => string` | Takes the author's name, so word order is the translator's to decide. |
-| `composerAttachmentLabel` | yes | `string` |  |
-| `composerReferenceLabel` | yes | `string` |  |
-| `replyPlaceholder` | no | `string` | The placeholder (and accessible name) of the reply composer; distinct so two open editors have different names. |
-| `editPlaceholder` | no | `string` | The same, for the editor that replaces a comment while it is being edited. |
-| `composerReply` | no | `string` | The submit label under a reply — "Post reply", so it is not a second "Reply" button. |
-| `actionsLabel` | no | `string` | Accessible name of the moderation menu. |
-| `fallbackAuthor` | yes | `string` |  |
-| `pinned` | yes | `string` |  |
-| `edited` | yes | `string` |  |
-| `deleteLabel` | yes | `string` |  |
-| `editLabel` | yes | `string` |  |
-| `replyLabel` | yes | `string` |  |
-| `pinLabel` | yes | `string` |  |
-| `unpinLabel` | yes | `string` |  |
-| `confirmDeleteTitle` | yes | `string` |  |
-| `confirmDeleteDescription` | yes | `string` |  |
-| `confirmDeleteLabel` | yes | `string` |  |
-| `confirmRemoveAttachmentTitle` | yes | `string` |  |
-| `confirmRemoveAttachmentDescription` | yes | `string` |  |
-| `formatShowReplies` | yes | `(count: number) => string` | Takes the count, because a plural is a language's business. |
-| `hideRepliesLabel` | yes | `string` |  |
-| `formatShowEarlierReplies` | no | `(count: number) => string` | Above an open thread longer than the preview — the replies still folded away. |
-| `formatRepliesLabel` | no | `(name: string) => string` | Names a thread's list of replies after the comment it answers. |
-| `seeMoreLabel` | no | `string` | Unfolds a body clamped to its first lines. |
-| `seeLessLabel` | no | `string` |  |
-| `attachmentFallback` | yes | `string` |  |
-| `attachmentRemoveLabel` | yes | `string` |  |
-| `attachmentUploadingLabel` | yes | `string` |  |
-| `attachmentFailedLabel` | yes | `string` |  |
-| `attachmentRetryLabel` | yes | `string` |  |
-| `attachmentDownloadLabel` | yes | `string` |  |
-| `formatShowMoreAttachments` | no | `(count: number) => string` | Unfolds the attachments past the first few. |
-| `showFewerAttachmentsLabel` | no | `string` |  |
-| `formatTooLarge` | yes | `(maximumBytes: number) => string` | The two refusals, as sentences built from the limit the hook reports. |
-| `formatTooMany` | yes | `(maximumFiles: number) => string` |  |
-| `addReactionLabel` | yes | `string` |  |
-| `reactionPickerLabel` | no | `string` | Names the picker that opens when more than one reaction is offered. |
-
-### `CommentSubmitHelpers`
-
-Kind: interface.
-
-Handed to `onSubmit` so the consumer drives the composer from their own result (a resolved promise may still carry errors).
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `setErrors` | yes | `(errors: Record<string, string>) => void` |  |
-| `reset` | yes | `() => void` |  |
-| `setSubmitting` | yes | `(submitting: boolean) => void` |  |
-
-### `CommentThreadOptions`
-
-Kind: interface.
-
-How a thread reads: what folds away and what a reader can do beyond reply and react. Shared by `Comments`, `CommentTimeline` and `CommentItem`.
-
-| 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 |
-| `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 ["👍"] |
-
-### `CommentTimeline`
-
-Kind: callable.
-
-```text
-({ comments, canModerate, onDelete, onAttachmentRemove, onEdit, onPinToggle, onReact, onReply, allowReactions, allowReplies, commentActions, maxVisibleReplies, clampLines, maxVisibleAttachments, reactionChoices, sanitizer, strings, getMediaUrl, getMediaName, getStatusLabel, resources, renderItem, renderAttachment, renderReference, emptySlot, className, }: CommentTimelineProps<TUser, TMeta, TResource>) => import("react").JSX.Element
-```
-
-### `CommentTimelineProps`
-
-Kind: interface.
-
-Extends: `CommentDisplayProps<TUser, TMeta, TResource>`, `Pick<CommentsSlots<TUser, TMeta, TResource>, "renderItem" | "emptySlot">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `comments` | yes | `ReadonlyArray<CommentData<TUser, TMeta, TResource>>` |  |
-| `className` | no | `string` |  |
-
-### `CommentUser`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | no | `string \| number` |  |
-| `name` | no | `string` |  |
-| `avatar` | no | `string` |  |
-
-### `ComposerMode`
-
-Kind: type.
-
-```text
-{ kind: "idle"; } | { kind: "editing"; comment: CommentData<TUser, TMeta, TResource>; } | { kind: "replying"; commentId: string; authorName?: string; }
-```
-
-### `defaultCommentsStrings`
-
-Kind: const.
-
-```text
-Required<CommentsStrings>
-```
-
-### `useAttachmentUpload`
-
-Kind: callable.
-
-```text
-(options?: UseAttachmentUploadOptions) => UseAttachmentUploadReturn
-```
-
-### `UseAttachmentUploadOptions`
-
-Kind: interface.
-
-Extends: `CommentsAttachmentsConfig`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `initialAttachments` | no | `ReadonlyArray<CommentAttachment>` | Files already on the record, when editing a posted comment. |
-| `onValueChange` | no | `(attachments: ReadonlyArray<CommentAttachment>) => void` |  |
-
-### `UseAttachmentUploadReturn`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `attachments` | yes | `ReadonlyArray<CommentAttachment>` | Everything staged — uploading, uploaded, and failed. |
-| `uploadedAttachments` | yes | `ReadonlyArray<CommentAttachment>` | The subset safe to submit. |
-| `isUploading` | yes | `boolean` |  |
-| `addFiles` | yes | `(files: ReadonlyArray<File> \| FileList) => void` |  |
-| `removeAttachment` | yes | `(id: string) => void` |  |
-| `retryAttachment` | yes | `(id: string) => void` |  |
-| `setAttachments` | yes | `(attachments: ReadonlyArray<CommentAttachment>) => void` |  |
-| `reset` | yes | `() => void` |  |
-
-### `useComments`
-
-Kind: callable.
-
-```text
-(options?: UseCommentsOptions<TUser, TMeta, TResource>) => UseCommentsReturn<TUser, TMeta, TResource>
-```
-
-### `UseCommentsOptions`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `onSubmit` | no | `CommentsConfig<TUser, TMeta, TResource>["onSubmit"]` |  |
-| `onUpdate` | no | `CommentsConfig<TUser, TMeta, TResource>["onUpdate"]` |  |
-| `onDelete` | no | `CommentsConfig<TUser, TMeta, TResource>["onDelete"]` |  |
-| `onAfterMutate` | no | `CommentsConfig<TUser, TMeta, TResource>["onAfterMutate"]` |  |
-| `onError` | no | `CommentsConfig<TUser, TMeta, TResource>["onError"]` |  |
-| `scopeKey` | no | `string` | Invalidates submission-bound helpers when the composer moves to another record. |
-
-### `UseCommentsReturn`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `composerMode` | yes | `ComposerMode<TResource, TUser, TMeta>` |  |
-| `isSubmitting` | yes | `boolean` |  |
-| `formErrors` | yes | `Record<string, string>` |  |
-| `resetKey` | yes | `number` | Bumped to clear the composer, which is otherwise uncontrolled. |
-| `startReply` | yes | `(comment: CommentData<TUser, TMeta, TResource>) => void` |  |
-| `startEdit` | yes | `(comment: CommentData<TUser, TMeta, TResource>) => void` |  |
-| `cancelComposerMode` | yes | `() => void` |  |
-| `submit` | yes | `(values: CommentFormValues<TResource>) => Promise<void>` |  |
-| `deleteComment` | yes | `(id: string) => Promise<void>` |  |
-| `resetComposer` | yes | `() => void` |  |
-| `helpers` | yes | `CommentSubmitHelpers` | Passed to `onSubmit` and `onUpdate`. |
-
-## Preview recipes
-
-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 }}
-/>
-```
-
-### 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()
-  }}
-/>
-```
-
-### Empty, and read-only
-
-```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Comments bare canComment={false} comments={[]} … />
-```