convex-feedback 0.1.0 → 0.1.2

package/src/component/model.ts

@@ -66,11 +66,169 @@ export const similarEntriesValidator = v.object({
   similar: v.array(publicEntryValidator),
 });
 
+/**
+ * Category of feedback represented by an entry.
+ *
+ * - `"feedback"` — general feedback that is not specifically a bug or feature request.
+ * - `"feature_request"` — a request for new or changed functionality.
+ * - `"bug_report"` — a report describing incorrect or broken behavior.
+ */
 export type EntryKind = Infer<typeof entryKindValidator>;
+
+/**
+ * Workflow state of a feedback entry.
+ *
+ * Status values are fixed by the component so consumers can rely on a stable,
+ * fully typed lifecycle. UI labels and presentation can be customized.
+ */
 export type EntryStatus = Infer<typeof entryStatusValidator>;
+
+/**
+ * Server-side ordering strategy for feedback entries.
+ *
+ * - `"top"` — entries with the most upvotes first, with creation time used as
+ *   the deterministic tie-breaker.
+ * - `"newest"` — newest entries first.
+ */
 export type EntrySort = Infer<typeof entrySortValidator>;
+
+/**
+ * Server-side ordering strategy for comments and replies.
+ *
+ * - `"top"` — comments with the most likes first, with creation time used as
+ *   the deterministic tie-breaker.
+ * - `"newest"` — newest comments first.
+ * - `"oldest"` — oldest comments first.
+ */
 export type CommentSort = Infer<typeof commentSortValidator>;
+
+/**
+ * Authenticated or anonymous actor resolved by the host application.
+ *
+ * The component does not access the host application's authentication system
+ * directly. The host resolves its current user/session into this shape.
+ *
+ * @property id
+ * Stable identifier for the actor. This can be a Clerk ID, Convex Auth ID,
+ * application user ID, anonymous installation ID, or another stable
+ * host-controlled identifier.
+ *
+ * @property isModerator
+ * Whether the actor can perform moderator-only actions such as changing entry
+ * status or modifying content they do not own.
+ */
 export type FeedbackActor = Infer<typeof actorValidator>;
+
+/**
+ * Public representation of a feedback, feature-request, or bug-report entry.
+ *
+ * @property id
+ * Public component document identifier.
+ *
+ * @property creationTime
+ * Convex document creation timestamp in milliseconds since the Unix epoch.
+ *
+ * @property actorId
+ * Stable identifier of the actor who created the entry.
+ *
+ * @property kind
+ * Entry category.
+ *
+ * @property status
+ * Current workflow status.
+ *
+ * @property title
+ * User-provided entry title.
+ *
+ * @property body
+ * User-provided entry description.
+ *
+ * @property upvoteCount
+ * Denormalized number of actors currently upvoting this entry.
+ *
+ * @property commentCount
+ * Denormalized total number of comments belonging to the entry, including
+ * nested replies.
+ *
+ * @property updatedAt
+ * Millisecond timestamp of the most recent content update. Absent when the
+ * entry has never been edited.
+ *
+ * @property viewerHasUpvoted
+ * Whether the actor associated with the current query has upvoted the entry.
+ * `false` when no viewer actor is available.
+ */
 export type FeedbackEntry = Infer<typeof publicEntryValidator>;
+
+/**
+ * Public representation of a comment or reply.
+ *
+ * Comments are returned one level at a time. Child comments are not included
+ * automatically; query them separately using the comment's `id` as
+ * `parentCommentId`.
+ *
+ * @property id
+ * Public component document identifier.
+ *
+ * @property creationTime
+ * Convex document creation timestamp in milliseconds since the Unix epoch.
+ *
+ * @property entryId
+ * Entry this comment belongs to.
+ *
+ * @property parentCommentId
+ * Direct parent comment. Absent for top-level comments.
+ *
+ * @property actorId
+ * Stable identifier of the actor who created the comment.
+ *
+ * @property depth
+ * Zero-based nesting depth. Top-level comments have depth `0`.
+ *
+ * @property body
+ * User-provided comment text. `null` when the comment was soft-deleted so
+ * nested replies can retain their place in the conversation.
+ *
+ * @property likeCount
+ * Denormalized number of actors currently liking this comment.
+ *
+ * @property replyCount
+ * Number of direct child replies. Descendants below those direct children are
+ * not included in this count.
+ *
+ * @property updatedAt
+ * Millisecond timestamp of the latest edit, when the comment has been edited.
+ *
+ * @property deletedAt
+ * Millisecond timestamp at which the comment was soft-deleted.
+ *
+ * @property viewerHasLiked
+ * Whether the actor associated with the current query likes this comment.
+ * `false` when no viewer actor is available.
+ */
 export type FeedbackComment = Infer<typeof publicCommentValidator>;
+
+/**
+ * Duplicate-detection result for a proposed entry.
+ *
+ * Exact normalized-title matches always receive priority. The requested
+ * `limit` is a combined limit across both arrays: exact matches consume the
+ * available slots first and only the remaining slots can be populated by
+ * relevance-ranked full-text matches.
+ *
+ * For `limit: 3`:
+ *
+ * - 3 exact matches → `3 exact + 0 similar`
+ * - 2 exact matches → `2 exact + at most 1 similar`
+ * - 0 exact matches → `0 exact + at most 3 similar`
+ *
+ * An entry returned in `exact` is never repeated in `similar`.
+ *
+ * @property exact
+ * Entries whose normalized title exactly matches the proposed title.
+ *
+ * @property similar
+ * Full-text matches ordered by search relevance after exact matches have been
+ * removed.
+ */
 export type SimilarEntriesResult = Infer<typeof similarEntriesValidator>;

package/src/react/index.ts

@@ -9,48 +9,185 @@ import type {
   EntryKind,
   EntrySort,
   EntryStatus,
+  SimilarEntriesResult,
 } from "../component/model.js";
 
+/**
+ * Client-side pagination defaults used by hooks created with
+ * `createFeedbackHooks`.
+ *
+ * These values control initial page sizes and subsequent `loadMore` sizes in
+ * the UI. They do not override the server-side maximum page sizes configured
+ * on the component.
+ */
 export interface FeedbackHooksOptions {
+  /**
+   * Number of entries initially requested by `useEntries`.
+   *
+   * @default 20
+   */
   entryPageSize?: number;
+
+  /**
+   * Number of top-level comments initially requested by `useComments`.
+   *
+   * @default 20
+   */
   commentPageSize?: number;
+
+  /**
+   * Number of direct child replies initially requested when
+   * `parentCommentId` is supplied to `useComments`.
+   *
+   * @default 10
+   */
   replyPageSize?: number;
 }
 
+/**
+ * Arguments accepted by `useEntries`.
+ */
 export interface UseEntriesArgs {
-  kind?: EntryKind;
+  /**
+   * Entry kinds to include.
+   *
+   * Filtering occurs in Convex before pagination. Omit to include every kind.
+   *
+   * The hook accepts a readonly array so configuration constants such as
+   * `readonly EntryKind[]` can be passed directly.
+   */
+  kinds?: readonly EntryKind[];
+
+  /** Optional workflow-status filter. */
   status?: EntryStatus;
+
+  /**
+   * Server-side entry ordering.
+   *
+   * When omitted, the host's configured default is used.
+   */
   sort?: EntrySort;
 }
 
+/**
+ * Arguments accepted by `useComments`.
+ *
+ * Comment trees are intentionally loaded lazily. Every invocation retrieves
+ * exactly one level of the tree.
+ */
 export interface UseCommentsArgs {
+  /** Entry whose comments are being requested. */
   entryId: string;
+
+  /**
+   * Direct parent whose replies should be requested.
+   *
+   * - Omitted → returns top-level comments.
+   * - Supplied → returns only direct children of this comment.
+   *
+   * Grandchildren and deeper descendants are never automatically loaded.
+   * Call `useComments` again with the child comment's ID when that branch is
+   * expanded.
+   */
   parentCommentId?: string;
+
+  /**
+   * Server-side ordering for this level of comments.
+   *
+   * When omitted, the host's configured default is used.
+   */
   sort?: CommentSort;
 }
 
+/**
+ * Arguments accepted by `useSearchEntries`.
+ */
 export interface SearchEntriesArgs {
+  /**
+   * Full-text query.
+   *
+   * Whitespace-only values skip the Convex query and return an empty array.
+   */
   searchQuery: string;
-  kind?: EntryKind;
+
+  /**
+   * Entry kinds to include.
+   *
+   * Filtering occurs on the server.
+   */
+  kinds?: readonly EntryKind[];
+
+  /** Optional workflow-status filter. */
   status?: EntryStatus;
+
+  /**
+   * Maximum number of results requested.
+   *
+   * The server applies its configured default when omitted and clamps the
+   * value to its configured maximum.
+   */
   limit?: number;
 }
 
+/**
+ * Arguments accepted by `useSimilarEntries`.
+ */
 export interface SimilarEntriesArgs {
+  /**
+   * Proposed entry title.
+   *
+   * Used both for normalized exact-title matching and full-text search.
+   */
   title: string;
+
+  /**
+   * Proposed entry body.
+   *
+   * Used together with the title for full-text similarity search.
+   */
   body: string;
+
+  /**
+   * Restricts duplicate detection to one entry kind.
+   *
+   * Omit to search every kind.
+   */
   kind?: EntryKind;
+
+  /**
+   * Maximum combined number of suggestions requested.
+   *
+   * Exact normalized-title matches consume the limit first. Only remaining
+   * slots may be filled by relevance-ranked full-text matches.
+   *
+   * For example, `limit: 3` with two exact matches can return at most one
+   * additional similar match.
+   */
   limit?: number;
 }
 
+const emptySimilarEntriesResult: SimilarEntriesResult = {
+  exact: [],
+  similar: [],
+};
+
 function positivePageSize(value: number | undefined, fallback: number): number {
   return value !== undefined && Number.isInteger(value) && value > 0
     ? value
     : fallback;
 }
 
-export function createFeedbackHooks(
-  api: FeedbackPublicApi,
+/**
+ * Creates React hooks bound to a host application's exposed feedback API.
+ *
+ * Create this once in the consuming application and reuse the returned hook
+ * collection.
+ *
+ * @typeParam RateLimitResult The validated non-throwing rate-limit rejection
+ * type returned by mutation hooks. It is inferred from the supplied API.
+ */
+export function createFeedbackHooks<RateLimitResult = never>(
+  api: FeedbackPublicApi<string | undefined, RateLimitResult>,
   options: FeedbackHooksOptions = {},
 ) {
   const entryPageSize = positivePageSize(options.entryPageSize, 20);
@@ -58,18 +195,36 @@ export function createFeedbackHooks(
   const replyPageSize = positivePageSize(options.replyPageSize, 10);
 
   return {
+    /**
+     * Resolved client-side page sizes used by the generated hooks and useful
+     * when calling their `loadMore` functions.
+     */
     pageSizes: {
       entries: entryPageSize,
       comments: commentPageSize,
       replies: replyPageSize,
     } as const,
 
+    /**
+     * Returns a cursor-paginated, server-filtered entry list.
+     */
     useEntries(args: UseEntriesArgs = {}) {
-      return usePaginatedQuery(api.listEntries, args, {
+      const queryArgs = {
+        ...(args.kinds === undefined ? {} : { kinds: [...args.kinds] }),
+        ...(args.status === undefined ? {} : { status: args.status }),
+        ...(args.sort === undefined ? {} : { sort: args.sort }),
+      };
+
+      return usePaginatedQuery(api.listEntries, queryArgs, {
         initialNumItems: entryPageSize,
       });
     },
 
+    /**
+     * Reactively retrieves one entry.
+     *
+     * Passing `null` or `undefined` skips the query.
+     */
     useEntry(entryId: string | null | undefined) {
       return useQuery(
         api.getEntry,
@@ -77,25 +232,59 @@ export function createFeedbackHooks(
       );
     },
 
+    /**
+     * Performs reactive full-text entry search.
+     *
+     * An empty/whitespace-only query returns `[]` without running Convex.
+     */
     useSearchEntries(args: SearchEntriesArgs) {
       const searchQuery = args.searchQuery.trim();
+
+      const queryArgs = {
+        searchQuery,
+        ...(args.kinds === undefined ? {} : { kinds: [...args.kinds] }),
+        ...(args.status === undefined ? {} : { status: args.status }),
+        ...(args.limit === undefined ? {} : { limit: args.limit }),
+      };
+
       const result = useQuery(
         api.searchEntries,
-        searchQuery.length === 0 ? "skip" : { ...args, searchQuery },
+        searchQuery.length === 0 ? "skip" : queryArgs,
       );
+
       return searchQuery.length === 0 ? [] : result;
     },
 
+    /**
+     * Reactively finds exact and similar entries for a proposed draft.
+     *
+     * The query is skipped only when both title and body are blank.
+     *
+     * `limit` is forwarded to the server unchanged. The server applies the
+     * combined exact-first limit semantics documented by `SimilarEntriesArgs`.
+     */
     useSimilarEntries(args: SimilarEntriesArgs) {
       const shouldSkip =
         args.title.trim().length === 0 && args.body.trim().length === 0;
+
+      const queryArgs = {
+        title: args.title,
+        body: args.body,
+        ...(args.kind === undefined ? {} : { kind: args.kind }),
+        ...(args.limit === undefined ? {} : { limit: args.limit }),
+      };
+
       const result = useQuery(
         api.findSimilarEntries,
-        shouldSkip ? "skip" : args,
+        shouldSkip ? "skip" : queryArgs,
       );
-      return shouldSkip ? { exact: [], similar: [] } : result;
+
+      return shouldSkip ? emptySimilarEntriesResult : result;
     },
 
+    /**
+     * Returns one independently paginated level of comments.
+     */
     useComments(args: UseCommentsArgs) {
       return usePaginatedQuery(api.listComments, args, {
         initialNumItems:
@@ -103,38 +292,57 @@ export function createFeedbackHooks(
       });
     },
 
+    /** Returns the bound create-entry mutation. */
     useCreateEntry() {
       return useMutation(api.createEntry);
     },
 
+    /** Returns the bound update-entry mutation. */
     useUpdateEntry() {
       return useMutation(api.updateEntry);
     },
 
+    /** Returns the bound status mutation. */
     useSetEntryStatus() {
       return useMutation(api.setEntryStatus);
     },
 
+    /** Returns the idempotent entry-upvote state mutation. */
     useSetEntryUpvote() {
       return useMutation(api.setEntryUpvote);
     },
 
+    /** Returns the create-comment/reply mutation. */
     useCreateComment() {
       return useMutation(api.createComment);
     },
 
+    /** Returns the update-comment mutation. */
     useUpdateComment() {
       return useMutation(api.updateComment);
     },
 
+    /** Returns the soft-delete-comment mutation. */
     useDeleteComment() {
       return useMutation(api.deleteComment);
     },
 
+    /** Returns the idempotent comment-like state mutation. */
     useSetCommentLike() {
       return useMutation(api.setCommentLike);
     },
   };
 }
 
-export type FeedbackHooks = ReturnType<typeof createFeedbackHooks>;
+/**
+ * Hook collection returned by `createFeedbackHooks`.
+ *
+ * This type is intended to be passed to `FeedbackScreen` and other
+ * `convex-feedback-ui` integrations.
+ *
+ * @typeParam RateLimitResult The validated non-throwing rate-limit rejection
+ * type returned by mutation hooks.
+ */
+export type FeedbackHooks<RateLimitResult = never> = ReturnType<
+  typeof createFeedbackHooks<RateLimitResult>
+>;