themelia-ui 2.0.0 → 3.0.0

package/dist/components/features/async-preview/async-preview.types.d.ts

@@ -30,6 +30,7 @@ export interface AsyncPreviewState<TData, TContext = unknown, TType extends stri
     prefetch: () => void;
     close: () => void;
 }
+/** What `onShow` is given. */
 export interface AsyncPreviewShowArgs<TContext, TType extends string> {
     type: TType;
     context: TContext;
@@ -40,6 +41,7 @@ export interface AsyncPreviewShowArgs<TContext, TType extends string> {
     cached: boolean;
     /** Reports a slow step — "Decrypting…" — without resolving. */
     setLoading: (loading: AsyncPreviewLoadingState) => void;
+    /** Carries a count or a permission alongside the record. */
     setMeta: (meta: Record<string, unknown>) => void;
 }
 interface AsyncPreviewCallbacks<TData, TContext, TType extends string> {
@@ -51,14 +53,29 @@ interface AsyncPreviewCallbacks<TData, TContext, TType extends string> {
     onRefresh?: (state: AsyncPreviewState<TData, TContext, TType>) => void;
 }
 export interface AsyncPreviewRootBaseProps<TData, TContext, TType extends string> extends AsyncPreviewCallbacks<TData, TContext, TType> {
-    /** Names the kind of record, passed to the fetcher. Caching requires cacheKey. */
+    /**
+     * Names the kind of record. Passed back to `onShow`, so one fetcher can serve several types.
+     * Caching requires `cacheKey`.
+     */
     type: TType;
-    /** Whatever the fetcher needs — usually an id. */
+    /** Whatever the fetcher needs — usually an id. Handed to `onShow` unchanged. */
     context: TContext;
-    /** The record identity and cache key. Change it when switching records; without one nothing is cached. */
+    /**
+     * The record identity and cache key: it enables the cache. Change it when the record
+     * changes; absent, nothing is cached, and each open fetches or consumes its hover prefetch.
+     */
     cacheKey?: string;
+    /**
+     * `cache-first` serves a fresh cache entry without a request. `always` refetches on every
+     * open — for a value that changes while the reader is on the page.
+     * @default "cache-first"
+     */
     cachePolicy?: AsyncPreviewCachePolicy;
-    /** How long a cache entry counts as fresh. Defaults to five minutes. */
+    /**
+     * How long a cache entry counts as fresh, in ms: five minutes. Entries are evicted on read;
+     * nothing wakes up on a timer.
+     * @default 300_000
+     */
     staleTime?: number;
     open?: boolean;
     defaultOpen?: boolean;
@@ -67,11 +84,19 @@ export interface AsyncPreviewRootBaseProps<TData, TContext, TType extends string
 }
 /** A preview that fetches. */
 export interface AsyncPreviewDynamicRootProps<TData, TContext, TType extends string> extends AsyncPreviewRootBaseProps<TData, TContext, TType> {
+    /**
+     * The fetcher, run when the preview opens or the trigger prefetches it. Supply this or
+     * `data`, not both.
+     */
     onShow: (args: AsyncPreviewShowArgs<TContext, TType>) => Promise<TData | null | undefined>;
     data?: never;
 }
 /** A preview whose data is already in hand: same component and states, no request. */
 export interface AsyncPreviewStaticRootProps<TData, TContext, TType extends string> extends AsyncPreviewRootBaseProps<TData, TContext, TType> {
+    /**
+     * The static form, in place of `onShow`: same component, same states, no request, for a row
+     * that already loaded what the preview shows.
+     */
     data: TData | null;
     onShow?: never;
 }
@@ -82,7 +107,10 @@ export interface AsyncPreviewTriggerRenderProps<TData, TContext, TType extends s
 export interface AsyncPreviewTriggerProps<TData, TContext, TType extends string> {
     /** The element the preview hangs off. */
     children?: ReactNode | ((props: AsyncPreviewTriggerRenderProps<TData, TContext, TType>) => ReactElement);
-    /** Starts the fetch on pointer-enter, before the popover opens. */
+    /**
+     * Starts the fetch on pointer-enter, before the popover opens — once per record. Not on
+     * focus: prefetching for every trigger a keyboard user tabs past would fire a request per row.
+     */
     prefetchOnHover?: boolean;
     className?: string;
 }
@@ -98,12 +126,16 @@ export interface AsyncPreviewStateProps<TData, TContext, TType extends string> {
     children: (state: AsyncPreviewState<TData, TContext, TType>) => ReactNode;
 }
 export interface AsyncPreviewBodyProps<TData, TContext, TType extends string> {
-    /** Rendered only in the `success` state, with the data non-null. */
+    /** Runs only in the `success` state, with the data non-null — so `data.name` needs no guard. */
     children: (data: TData, state: AsyncPreviewState<TData, TContext, TType>) => ReactNode;
 }
 /** The three placeholder slots. `children` may be a function of the state, e.g. to read the error. */
 export interface AsyncPreviewSlotProps<TData = unknown, TContext = unknown, TType extends string = string> {
     className?: string;
+    /**
+     * Replaces the default. The function form is what an error slot wants — it is the only way
+     * to show the error.
+     */
     children?: ReactNode | ((state: AsyncPreviewState<TData, TContext, TType>) => ReactNode);
 }
 export type AsyncPreviewLoadingProps<TData = unknown, TContext = unknown, TType extends string = string> = AsyncPreviewSlotProps<TData, TContext, TType>;

package/dist/components/features/async-preview/preview-trigger-cell.d.ts

@@ -17,7 +17,10 @@ export interface PreviewTriggerCellProps extends Omit<ComponentProps<"button">,
     }>;
     /** Shown when `value` is absent — the em dash, unless a column wants its own word. */
     emptyLabel?: ReactNode;
-    /** Whether this row has a preview at all. Off renders plain text. */
+    /**
+     * Whether this row has a preview at all. Off renders an inert span with the same text and
+     * rhythm, and no caret, pointer or popup ARIA.
+     */
     hasPreview?: boolean;
     /** Why it is unavailable. Shown as a tooltip on the inert cell. */
     disabledReason?: ReactNode;
@@ -25,5 +28,9 @@ export interface PreviewTriggerCellProps extends Omit<ComponentProps<"button">,
     asName?: boolean;
     className?: string;
 }
+/**
+ * The trigger, shaped for a table cell. It is a button only when there is something to open;
+ * otherwise the same text renders inert.
+ */
 export declare function PreviewTriggerCell({ value, secondary, leading, trailing, badge, icon: Icon, emptyLabel, hasPreview, disabledReason, asName, disabled, className, ...props }: PreviewTriggerCellProps): import("react").JSX.Element;
 export {};

package/dist/components/features/async-preview/use-async-preview.d.ts

@@ -6,4 +6,8 @@ export interface UseAsyncPreviewOptions<TData, TContext = unknown, TType extends
 export type UseAsyncPreviewReturn<TData, TContext = unknown, TType extends string = string> = AsyncPreviewState<TData, TContext, TType> & {
     setOpen: (open: boolean) => void;
 };
+/**
+ * Fetching tied to a popover's open state. Closing aborts the request, only the newest request
+ * may write state, and a module cache keyed by `cacheKey` spares a repeat within `staleTime`.
+ */
 export declare function useAsyncPreview<TData, TContext = unknown, TType extends string = string>(options: UseAsyncPreviewOptions<TData, TContext, TType>): UseAsyncPreviewReturn<TData, TContext, TType>;

package/dist/components/features/combobox/async-combobox.d.ts

@@ -1,3 +1,13 @@
 import { AsyncComboboxProps, AsyncMultiComboboxProps } from './combobox.types.js';
+/**
+ * The search-driven single-select picker, for a screen that already holds its results: the
+ * consumer supplies the items, the query and the loading flag. It does not filter `items` —
+ * what is passed is what renders. The field shows the query while open and the selection's
+ * label while closed.
+ */
 export declare function AsyncCombobox<T>({ selectedValue, onSelectedValueChange, clearSearchOnClose, minSearchLength, loading, showListContent, disabled, clearable, ...shared }: AsyncComboboxProps<T>): import("react").JSX.Element;
+/**
+ * The multi-select twin of `AsyncCombobox`: chips in the field, checks in the list, and an
+ * optional apply footer. Selections are merged ahead of the results, so they stay visible.
+ */
 export declare function AsyncMultiCombobox<T>({ selectedValues, onSelectedValuesChange, minSearchLength, loading, showListContent, disabled, closeOnSelect, applyButton, onApply, onCancel, open, onOpenChange, ...shared }: AsyncMultiComboboxProps<T>): import("react").JSX.Element;

package/dist/components/features/combobox/combobox-dropdown.d.ts

@@ -29,4 +29,9 @@ export interface ComboboxDropdownProps<T> {
     /** Error content, shown instead of everything else. */
     errorSlot?: ReactNode;
 }
+/**
+ * The popup: status row, results, create row, pager and footer. It renders an empty popup
+ * rather than nothing, because a popup that vanishes mid-type reads as a broken control
+ * rather than an empty result.
+ */
 export declare function ComboboxDropdown<T>({ loading, showStatus, showEmpty, trimmedSearch, minSearchLength, items, groupedItems, createOptionItem, renderItemContent, getItemReactKey, getItemDisabled, renderGroupLabel, loadingMore, strings, portalContainer, listRef, anchor, applyFooter, errorSlot, }: ComboboxDropdownProps<T>): import("react").JSX.Element;

package/dist/components/features/combobox/combobox.types.d.ts

@@ -14,7 +14,10 @@ export interface AsyncComboboxSharedProps<T> {
      * create row's duplicate check compares against.
      */
     getItemLabel: (item: T) => string;
-    /** Stable identity. Defaults to the label; supply it whenever labels are not unique. */
+    /**
+     * Stable identity. Defaults to the label, so supply it whenever labels are not unique:
+     * two people of one name would collide, and de-duplicating would drop one.
+     */
     getItemKey?: (item: T) => string;
     loading?: boolean;
     /**
@@ -27,6 +30,10 @@ export interface AsyncComboboxSharedProps<T> {
      * row replaces results and `onSearch` does not fire; `0` allows browsing before typing.
      */
     minSearchLength?: number;
+    /**
+     * Overrides every word the pickers render, including the clear and chevron controls' names
+     * and each chip's remove control.
+     */
     strings?: Partial<AsyncComboboxStrings>;
     disabled?: boolean;
     className?: string;
@@ -46,16 +53,31 @@ export interface AsyncComboboxSharedProps<T> {
      * `minSearchLength`. To clear results below the threshold, use `onSearchValueChange`.
      */
     onSearch?: (value: string) => void;
+    /**
+     * The quiet period before `onSearch` fires, in milliseconds.
+     * @default 300
+     */
     debounceMs?: number;
     /** Offers an inline create row when nothing matches. Needs `onCreate` to do anything. */
     creatable?: boolean;
+    /**
+     * Receives the create row's text: a created entry arrives here, not as a selection. The row
+     * is withheld while nothing is typed, below `minSearchLength`, and when the text matches an
+     * existing label case-insensitively.
+     */
     onCreate?: (value: string) => void;
     /** Returns a group name per item. Absent means no grouping. */
     getItemGroup?: (item: T) => string;
     renderGroupLabel?: (group: string) => ReactNode;
     /** Enables scroll-triggered pagination. */
     hasMore?: boolean;
+    /**
+     * Asks for the next page once the list is scrolled 80% of the way down. A cooldown after
+     * each request stops a second page being asked for while the first is in flight — the list
+     * has not grown, so the scroll position is still past the threshold.
+     */
     onLoadMore?: () => void;
+    /** Shows that the next page is loading, and holds off asking for another. */
     loadingMore?: boolean;
     /** Renders an option unselectable without hiding it. */
     getItemDisabled?: (item: T) => boolean;
@@ -68,7 +90,11 @@ export interface AsyncComboboxProps<T> extends AsyncComboboxSharedProps<T> {
     /** The selected item (not a key), or `null`. Controlled; survives `items` being replaced. */
     selectedValue: T | null;
     onSelectedValueChange: (value: T | null) => void;
-    /** Clears the query when the popup closes. Defaults to `true`. */
+    /**
+     * Clears the query when the popup closes, so the next open is not filtered by something
+     * forgotten.
+     * @default true
+     */
     clearSearchOnClose?: boolean;
 }
 export interface AsyncMultiComboboxProps<T> extends AsyncComboboxSharedProps<T> {
@@ -80,7 +106,9 @@ export interface AsyncMultiComboboxProps<T> extends AsyncComboboxSharedProps<T>
     closeOnSelect?: boolean;
     /** Renders an Apply / Cancel footer and holds edits in a draft until Apply. Without it every toggle commits. */
     applyButton?: boolean;
+    /** Called when Apply commits the draft. */
     onApply?: () => void;
+    /** Called when Cancel discards the draft. Cancel and dismissal both restore the committed set. */
     onCancel?: () => void;
 }
 /** What a custom option renderer is told about the row it is drawing. */

package/dist/components/features/combobox/highlighted-text.d.ts

@@ -1,3 +1,7 @@
+/**
+ * The matched span inside a result label. Exported so a custom row keeps the highlight
+ * rather than rendering a plain string beside ones that have it.
+ */
 export declare function HighlightedText({ text, highlight }: {
     text: string;
     highlight: string;

package/dist/components/features/combobox/resource-combobox.d.ts

@@ -12,6 +12,10 @@ export interface ResourceComboboxFetcherArgs {
 }
 export type ResourceComboboxFetcher<T> = (args: ResourceComboboxFetcherArgs) => Promise<T[]>;
 export interface ResourceComboboxProps<T> extends Omit<AsyncComboboxProps<T>, "items" | "selectedValue" | "onSelectedValueChange" | "clearSearchOnClose" | "searchValue" | "onSearchValueChange" | "getItemLabel" | "getItemKey" | "loading" | "showListContent" | "renderItem" | "error"> {
+    /**
+     * Fetches the options for a query. Debounce, abort, and the race guard are owned for you,
+     * and the query arrives trimmed. Honour `signal`, so an abort does not surface as a failure.
+     */
     fetcher: ResourceComboboxFetcher<T>;
     /** Controlled. Omit entirely to let the component own the selection. */
     value?: T | null;
@@ -28,7 +32,11 @@ export interface ResourceComboboxProps<T> extends Omit<AsyncComboboxProps<T>, "i
     defaultOpen?: boolean;
     /** Clears the query when the popup closes. Defaults to `false`. A failed query is always kept for retry. */
     clearSearchOnClose?: boolean;
-    /** A further wait before the fetcher runs, after the loading state is showing. For rate-limited endpoints. */
+    /**
+     * A further wait before the fetcher runs, after the loading state is showing. For
+     * rate-limited endpoints: the reader sees something is happening, and the request that
+     * would have been refused is never made.
+     */
     requestDelay?: number;
     onAfterFetch?: (items: T[], context: ResourceComboboxFetcherArgs) => void;
     /** Aborted and superseded requests never reach this. */
@@ -45,10 +53,20 @@ export interface ResourceComboboxProps<T> extends Omit<AsyncComboboxProps<T>, "i
     limit?: number;
     /** Characters required before fetching. Defaults to `0` (unlike `AsyncCombobox`'s `3`); an empty input follows `preload`. */
     minSearchLength?: number;
-    /** Fetches with an empty query, so there is something to look at before typing. */
+    /**
+     * Fetches with an empty query as the popup opens, without waiting out the debounce, so
+     * there is something to look at before typing. Off, an empty field asks the reader to type
+     * instead of claiming there are no results.
+     */
     preload?: boolean;
     errorMessage?: ReactNode;
     renderError?: (context: ResourceComboboxErrorContext) => ReactNode;
     strings?: Partial<AsyncComboboxStrings>;
 }
+/**
+ * A self-fetching picker: give it a `fetcher` and it owns debounce, abort and the race guard.
+ * Browsable from the first keystroke, and preloaded on mount so the list is there on open. A
+ * failed fetch replaces the list content, as `AsyncCombobox`'s `showListContent` does when
+ * off, but keeps the selection and the query, for retry.
+ */
 export declare function ResourceCombobox<T>({ fetcher, onAfterFetch, onError, getKey, getLabel, limit, debounceMs, preload, minSearchLength, defaultValue, errorMessage, ...props }: ResourceComboboxProps<T>): import("react").JSX.Element;

package/dist/components/features/combobox/suggestions-combobox.d.ts

@@ -9,7 +9,9 @@ export interface SuggestionsErrorContext {
 export interface SuggestionsComboboxProps<T> extends UseSuggestionsConfig<T> {
     /** Applied to the search input, so a `FormField` label can address it. */
     id?: string;
+    /** Stable identity for an item. */
     itemKey: (item: T) => string | number;
+    /** The item's label: what its row and the chosen value show. */
     itemText: (item: T) => string;
     renderItem?: (item: T) => ReactNode;
     renderError?: (context: SuggestionsErrorContext) => ReactNode;
@@ -29,4 +31,10 @@ export interface SuggestionsComboboxProps<T> extends UseSuggestionsConfig<T> {
     /** Emphasises the matched substring. Ignored when `renderItem` is set. */
     highlightMatch?: boolean;
 }
+/**
+ * `useSuggestions` behind the kit's combobox: the same engine as `ResourceCombobox` in the
+ * hook's words — `fetchData(query, { signal })`, `itemKey`, `itemText`,
+ * `query`/`onQueryChange` — and with its defaults: one character before a request, and no
+ * preload.
+ */
 export declare function SuggestionsCombobox<T>({ fetchData, itemKey, itemText, renderItem, minQueryLength, preload, query, defaultQuery, onQueryChange, allowClear, clearInputOnClose, disabled, strings, ...props }: SuggestionsComboboxProps<T>): import("react").JSX.Element;

package/dist/components/features/combobox/use-combobox-core.d.ts

@@ -30,5 +30,10 @@ export interface UseComboboxCoreReturn<T> {
     getItemReactKey: (item: T) => string;
     handleScroll: (event: Event) => void;
 }
+/**
+ * The list state every picker shares: the threshold, the selection merged ahead of the
+ * results, the groups, the create row and the pager. The pickers differ only in what
+ * selected means, the field, and where the results come from.
+ */
 export declare function useComboboxCore<T>({ items, searchValue, getItemLabel, getItemKey, loading, showListContent, minSearchLength, strings, renderItem, onSearch, debounceMs, creatable, onCreate, getItemGroup, hasMore, onLoadMore, loadingMore, highlightMatch, ensuredItems, }: UseComboboxCoreOptions<T>): UseComboboxCoreReturn<T>;
 export {};

package/dist/components/features/combobox/use-suggestions.d.ts

@@ -4,6 +4,10 @@ export interface SuggestionsFetchContext {
     signal?: AbortSignal;
 }
 export interface UseSuggestionsConfig<T> {
+    /**
+     * Fetches the suggestions for a query, as an array or a promise of one. Pass
+     * `context.signal` to the request: it aborts when a newer query starts.
+     */
     fetchData: (query: string, context?: SuggestionsFetchContext) => MaybePromise<T[]>;
     /**
      * Characters required before a request is issued, not counting surrounding whitespace.
@@ -15,6 +19,7 @@ export interface UseSuggestionsConfig<T> {
     /**
      * A further wait before the fetcher runs, after the loading state is showing (unlike
      * `debounceMs`, which delays deciding to fetch). For rate-limited endpoints.
+     * @default 0
      */
     requestDelay?: number;
     /** Fetches the empty query, so there is something before typing. Not debounced. */
@@ -47,4 +52,9 @@ export interface UseSuggestionsResult<T> {
     open: boolean;
     setOpen: (value: boolean) => void;
 }
+/**
+ * The request lifecycle the self-fetching pickers run on — query, results, loading, error,
+ * selection and open, each controllable on its own — for a caller putting it behind their
+ * own field, or a surface that is not a combobox at all.
+ */
 export declare function useSuggestions<T>(config: UseSuggestionsConfig<T>): UseSuggestionsResult<T>;

package/dist/components/features/comments/comment-attachment-chip.d.ts

@@ -10,4 +10,9 @@ export interface CommentAttachmentChipProps {
     strings?: Partial<CommentsStrings>;
     className?: string;
 }
+/**
+ * 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.
+ */
 export declare function CommentAttachmentChip({ attachment, editable, onRemove, onRetry, accessors, strings, className, }: CommentAttachmentChipProps): import("react").JSX.Element;

package/dist/components/features/comments/comment-content.d.ts

@@ -7,8 +7,13 @@ export interface CommentContentProps<TUser extends CommentUser = CommentUser, TM
     renderReference?: CommentsSlots<TUser, TMeta, TResource>["renderReference"];
     /** Replaces the kit's allow-list. There is no way to skip sanitising. */
     sanitizer?: (html: string) => string;
-    /** Overrides this component's own copy — the quote attribution, so far. */
+    /** Overrides this component's own copy — the quote attribution. */
     strings?: Partial<CommentsStrings>;
     className?: string;
 }
+/**
+ * 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.
+ */
 export declare function CommentContent<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string>({ comment, resources, renderReference, sanitizer, strings, className, }: CommentContentProps<TUser, TMeta, TResource>): ReactNode;

package/dist/components/features/comments/comment-item.d.ts

@@ -1,2 +1,8 @@
 import { CommentItemProps, CommentUser } from './comments.types.js';
+/**
+ * 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.
+ */
 export declare function CommentItem<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string>({ 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;

package/dist/components/features/comments/comments.d.ts

@@ -1,2 +1,7 @@
 import { CommentUser, CommentsProps } from './comments.types.js';
+/**
+ * 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.
+ */
 export declare function Comments<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string>(props: CommentsProps<TUser, TMeta, TResource>): import("react").JSX.Element;

package/dist/components/features/comments/comments.types.d.ts

@@ -123,7 +123,11 @@ export interface CommentsAttachmentsConfig {
     /** Passed straight to the file input. */
     accept?: string;
     disabled?: boolean;
-    /** Receives a refusal before any upload starts. */
+    /**
+     * Receives a refusal before any upload starts, as a code and the number behind it — never a
+     * sentence. The hook has no idea what language the reader speaks, and “too large” is useless
+     * without the limit.
+     */
     onReject?: (rejection: CommentAttachmentRejection) => void;
 }
 export interface CommentsConfig<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> extends CommentsAccessors {
@@ -161,7 +165,12 @@ export interface CommentsSlots<TUser extends CommentUser = CommentUser, TMeta =
     emptySlot?: ReactNode;
     headerSlot?: ReactNode;
     footerSlot?: ReactNode;
+    /**
+     * Replaces a comment. It receives `defaultItem`, so a consumer can wrap the kit's comment
+     * rather than rebuild it.
+     */
     renderItem?: (context: CommentRenderItemContext<TUser, TMeta, TResource>) => ReactNode;
+    /** Replaces an attachment's chip. */
     renderAttachment?: (attachment: CommentAttachment) => ReactNode;
     /** Overrides the mention registry's own `renderChip`. */
     renderReference?: (reference: Mention<TResource>) => ReactNode;
@@ -169,12 +178,15 @@ export interface CommentsSlots<TUser extends CommentUser = CommentUser, TMeta =
 /** How a thread reads: what folds away and what a reader can do beyond reply and react. Shared by `Comments`, `CommentTimeline` and `CommentItem`. */
 export interface CommentThreadOptions<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> {
     /**
-     * Extra entries for each comment's overflow menu, bound to the comment (`visible`,
-     * `disabled` and `onClick` receive it). Listed above pin, edit and delete; `destructive` sorts last.
+     * Extra entries for each comment's overflow menu — copy a link, report, resolve. Bound to the
+     * comment like a table row's actions: `visible` and `disabled` may be predicates, and
+     * `onClick` receives the comment. They sit after pin and edit, before delete; a
+     * `destructive` entry still sorts last.
      */
     commentActions?: ContextActionSource<CommentData<TUser, TMeta, TResource>>;
     /**
-     * Latest replies shown before earlier ones fold behind "Show N earlier replies". `0` shows all.
+     * Replies an open thread shows; the earlier ones fold behind "Show N earlier replies". The
+     * LAST ones are kept, so list replies oldest first. `0` shows them all.
      * @default 3
      */
     maxVisibleReplies?: number;
@@ -184,12 +196,14 @@ export interface CommentThreadOptions<TUser extends CommentUser = CommentUser, T
      */
     clampLines?: number;
     /**
-     * Attachments shown before the rest fold behind "Show N more". `0` shows every file.
+     * Attachments shown before the rest fold behind "Show N more". Folding one file saves
+     * nothing, so the fold starts at two hidden. `0` shows every file.
      * @default 3
      */
     maxVisibleAttachments?: number;
     /**
-     * The reactions "Add reaction" offers. One reacts immediately; more open a picker.
+     * The reactions "Add reaction" offers. One reacts at once; more open a picker that marks the
+     * reader's own. Every choice arrives through `onReact`.
      * @default ["👍"]
      */
     reactionChoices?: readonly string[];
@@ -251,11 +265,25 @@ export interface CommentComposerProps<TResource extends string = string> {
     className?: string;
 }
 export interface CommentsProps<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> extends CommentsAccessors, CommentThreadOptions<TUser, TMeta, TResource>, CommentsSlots<TUser, TMeta, TResource> {
+    /**
+     * What the thread hangs off: an `id` and a `type`, and a `moduleKey` where one record carries
+     * several threads. Passed straight through to `onSubmit`. Changing it clears the draft — a
+     * composer that stays mounted must not carry one record's text to the next.
+     */
     context: CommentableContext;
-    /** In display order. Replies are nested by `replyToId`, not by position. */
+    /**
+     * Flat, in display order. Replies nest by `replyToId`, not by position, so one posted an hour
+     * late still appears under its parent. A reply whose parent is not in the array is promoted
+     * rather than dropped.
+     */
     comments: ReadonlyArray<CommentData<TUser, TMeta, TResource>>;
     canComment?: boolean;
     canModerate?: boolean;
+    /**
+     * Where the composer sits — a real per-thread decision: an activity log reads newest-first
+     * and a discussion reads like a chat, and the same page can want both. Replies and edits open
+     * inside the thread either way.
+     */
     composerPosition?: CommentsComposerPosition;
     maxAttachments?: number;
     allowAttachments?: boolean;
@@ -263,21 +291,44 @@ export interface CommentsProps<TUser extends CommentUser = CommentUser, TMeta =
     allowReplies?: boolean;
     /** Drops the card chrome, for a thread already inside a panel. */
     bare?: boolean;
-    /** `false` hides the title outright. */
+    /** The heading. `false` hides it outright. */
     title?: ReactNode | false;
+    /**
+     * Posts a comment or a reply. `helpers.reset()` is what clears the composer — a resolved
+     * promise is not proof of success, and a server answering validation with a 200 would
+     * otherwise throw away what the writer typed.
+     */
     onSubmit?: CommentsConfig<TUser, TMeta, TResource>["onSubmit"];
+    /** Deletes a comment, after a confirmation unless `confirmDelete` is off. */
     onDelete?: CommentsConfig<TUser, TMeta, TResource>["onDelete"];
-    /** Asks before deleting. Off when the app already confirms upstream. */
+    /**
+     * Asks before deleting. The confirmation is opt-out because deleting takes the replies with
+     * it; turn it off when the app already asks upstream.
+     */
     confirmDelete?: boolean;
     onAttachmentRemove?: (commentId: string, attachmentId: string) => void | Promise<void>;
+    /** Saves an edit. As with `onSubmit`, `helpers.reset()` is what clears the composer. */
     onUpdate?: CommentsConfig<TUser, TMeta, TResource>["onUpdate"];
     onAfterMutate?: CommentsConfig<TUser, TMeta, TResource>["onAfterMutate"];
     onError?: CommentsConfig<TUser, TMeta, TResource>["onError"];
     onPinToggle?: CommentsConfig<TUser, TMeta, TResource>["onPinToggle"];
     onReact?: CommentsConfig<TUser, TMeta, TResource>["onReact"];
     onReply?: CommentsConfig<TUser, TMeta, TResource>["onReply"];
+    /**
+     * The mention registry, as `useMentions` takes it. Without it the reference control does not
+     * appear.
+     */
     resources?: CommentsConfig<TUser, TMeta, TResource>["resources"];
+    /**
+     * The fallback search, for a mention kind that registers neither `search` nor
+     * `suggestions`.
+     */
     onResourceSearch?: CommentsConfig<TUser, TMeta, TResource>["onResourceSearch"];
+    /**
+     * Uploads: `onUpload`, `maxSize`, `maxFiles`, `accept`. Without `onUpload` there is no
+     * attachment control. The uploader resolves to a `CommentAttachment` with a permanent `url`;
+     * the composer submits what it returns, not the file it was given.
+     */
     attachments?: CommentsAttachmentsConfig;
     sanitizer?: CommentsConfig<TUser, TMeta, TResource>["sanitizer"];
     strings?: Partial<CommentsStrings>;

package/dist/components/features/comments/use-attachment-upload.d.ts

@@ -16,4 +16,9 @@ export interface UseAttachmentUploadReturn {
     setAttachments: (attachments: ReadonlyArray<CommentAttachment>) => void;
     reset: () => void;
 }
+/**
+ * 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.
+ */
 export declare function useAttachmentUpload(options?: UseAttachmentUploadOptions): UseAttachmentUploadReturn;

package/dist/components/features/comments/use-comments.d.ts

@@ -33,4 +33,9 @@ export interface UseCommentsReturn<TUser extends CommentUser = CommentUser, TMet
     /** Passed to `onSubmit` and `onUpdate`. */
     helpers: CommentSubmitHelpers;
 }
+/**
+ * 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.
+ */
 export declare function useComments<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string>(options?: UseCommentsOptions<TUser, TMeta, TResource>): UseCommentsReturn<TUser, TMeta, TResource>;

package/dist/components/features/data-view/data-view.d.ts

@@ -1,9 +1,33 @@
 import { RowData } from '@tanstack/react-table';
 import { DataViewPaginationProps, DataViewProps, DataViewShellProps, DataViewTableFrameProps, DataViewToolbarProps, SavedViewTabsProps } from './data-view.types.js';
+/** The plain shell, for composing the same rhythm around something that is not a DataTable. */
 export declare function DataViewShell({ children, header, toolbar, footer, emptySlot, empty, className, contentClassName, }: DataViewShellProps): import("react").JSX.Element;
+/**
+ * The filter bar. In a DataView it lives inside the table's topbar rather than above it, so
+ * filtering and the data it filters are one surface and scroll as one. It works bare too,
+ * around something that is not a DataTable.
+ */
 export declare function DataViewToolbar({ leading, search, filters, views, actions, className, }: DataViewToolbarProps): import("react").JSX.Element;
+/**
+ * The table frame the filter bar sits in, with the bar in the table's topbar so filtering and
+ * the data it filters scroll as one. It works bare too, around something that is not a
+ * DataTable.
+ */
 export declare function DataViewTableFrame({ toolbar, children, footer, className, toolbarClassName, contentClassName, footerClassName, }: DataViewTableFrameProps): import("react").JSX.Element;
-/** A saved-view row that is NOT filter-driven — for a consumer holding views themselves. */
+/**
+ * A compact select of saved views that is NOT filter-driven — for a consumer holding views
+ * themselves. The caller controls the selected view and applies its state through
+ * `onValueChange`. For filter-driven tabs, or a select with exact preset matching, use
+ * DataView's `filtering.tabs` or FilterTabs.
+ */
 export declare function SavedViewTabs({ views, value, onValueChange, className }: SavedViewTabsProps): import("react").JSX.Element;
+/**
+ * Keeps the result summary visible, including zero results. Page controls appear only above
+ * one page; `disabled` makes every control unavailable to pointer and keyboard users.
+ */
 export declare function DataViewPagination({ page, pageCount, total, onPageChange, disabled, className, strings, }: DataViewPaginationProps): import("react").JSX.Element | null;
+/**
+ * The filter bar and the table as one surface: filter state, row filtering, the bar inside the
+ * table's topbar, and pagination, all against one row set.
+ */
 export declare function DataView<TData extends RowData, TValue = unknown>({ data, columns, filtering, strings, table, slots, className, }: DataViewProps<TData, TValue>): import("react").JSX.Element;