convex-feedback 0.1.5 → 0.2.0-beta.0

package/src/react/README.md

@@ -1,7 +1,7 @@
 # React hooks layer
 
-`createFeedbackHooks(api, options?)` binds the host application's public Convex API to headless React hooks.
+`createFeedbackHooks(api?, options?)` binds the host application's public Convex API to headless React hooks. With no API argument it uses `anyApi.feedback`; pass a generated API namespace when the host module has another name.
 
-The hooks expose entries, search/similarity, lazy direct-child comment pagination, mutations, and the configured client page sizes. Reply queries are not mounted by the hook layer automatically; the UI decides when a comment is expanded.
+The hooks expose public entries, search/similarity, lazy direct-child comment pagination, mutations, admin inbox queries, and roadmap operations. Reply queries are not mounted by the hook layer automatically; the UI decides when a comment is expanded.
 
 Page-size defaults are client concerns. The server-side component still enforces its configured hard maximum. Keep the two aligned when overriding defaults.

package/src/react/index.ts

@@ -2,14 +2,17 @@
 
 import { usePaginatedQuery } from "convex-helpers/react";
 import { useMutation, useQuery } from "convex/react";
+import { anyApi } from "convex/server";
 
 import type { FeedbackPublicApi } from "../client/api.js";
 import type {
   CommentSort,
   EntryKind,
+  EntryPriority,
   EntrySort,
   EntryStatus,
   EntryStatusFilter,
+  RoadmapStatus,
   SimilarEntriesResult,
 } from "../component/model.js";
 
@@ -23,7 +26,8 @@ import type {
  */
 export interface FeedbackHooksOptions {
   /**
-   * Number of entries initially requested by `useEntries`.
+   * Number of entries initially requested by entry-list hooks, including the
+   * public board, admin inbox, admin search, and roadmap attachments.
    *
    * @default 20
    */
@@ -43,6 +47,13 @@ export interface FeedbackHooksOptions {
    * @default 10
    */
   replyPageSize?: number;
+
+  /**
+   * Number of roadmap items initially requested by `useRoadmap`.
+   *
+   * @default 30
+   */
+  roadmapPageSize?: number;
 }
 
 /**
@@ -136,6 +147,16 @@ export interface SearchEntriesArgs {
   limit?: number;
 }
 
+export interface UseAdminEntriesArgs {
+  kinds?: readonly EntryKind[];
+  status?: EntryStatus;
+  priority?: EntryPriority;
+}
+
+export interface UseAdminSearchEntriesArgs extends UseAdminEntriesArgs {
+  searchQuery: string;
+}
+
 /**
  * Arguments accepted by `useSimilarEntries`.
  */
@@ -200,6 +221,7 @@ function createFeedbackHooksImplementation<RateLimitResult>(
   const entryPageSize = positivePageSize(options.entryPageSize, 20);
   const commentPageSize = positivePageSize(options.commentPageSize, 20);
   const replyPageSize = positivePageSize(options.replyPageSize, 10);
+  const roadmapPageSize = positivePageSize(options.roadmapPageSize, 30);
 
   return {
     /**
@@ -210,6 +232,7 @@ function createFeedbackHooksImplementation<RateLimitResult>(
       entries: entryPageSize,
       comments: commentPageSize,
       replies: replyPageSize,
+      roadmap: roadmapPageSize,
     } as const,
 
     /**
@@ -268,6 +291,80 @@ function createFeedbackHooksImplementation<RateLimitResult>(
       return searchQuery.length === 0 ? [] : result;
     },
 
+    /** Returns whether the authenticated host actor is an admin. */
+    useIsAdmin() {
+      return useQuery(api.isAdmin, {});
+    },
+
+    /** Returns whether the current request has an authenticated actor. */
+    useIsAuthenticated() {
+      return useQuery(api.isAuthenticated, {});
+    },
+
+    /** Returns a cursor-paginated admin inbox with private triage relationships. */
+    useAdminEntries(args: UseAdminEntriesArgs = {}) {
+      return usePaginatedQuery(
+        api.adminListEntries,
+        {
+          ...(args.kinds === undefined ? {} : { kinds: [...args.kinds] }),
+          ...(args.status === undefined ? {} : { status: args.status }),
+          ...(args.priority === undefined ? {} : { priority: args.priority }),
+        },
+        { initialNumItems: entryPageSize },
+      );
+    },
+
+    /** Returns one admin-enriched feedback entry. */
+    useAdminEntry(entryId: string | null | undefined) {
+      return useQuery(
+        api.adminGetEntry,
+        entryId === null || entryId === undefined ? "skip" : { entryId },
+      );
+    },
+
+    /** Searches the admin inbox with triage filters. */
+    useAdminSearchEntries(args: UseAdminSearchEntriesArgs) {
+      const searchQuery = args.searchQuery.trim();
+      return usePaginatedQuery(
+        api.adminSearchEntries,
+        searchQuery.length === 0
+          ? "skip"
+          : {
+              searchQuery,
+              ...(args.kinds === undefined ? {} : { kinds: [...args.kinds] }),
+              ...(args.status === undefined ? {} : { status: args.status }),
+              ...(args.priority === undefined
+                ? {}
+                : { priority: args.priority }),
+            },
+        { initialNumItems: entryPageSize },
+      );
+    },
+
+    useRoadmap(status?: RoadmapStatus) {
+      return usePaginatedQuery(
+        api.listRoadmap,
+        status === undefined ? {} : { status },
+        { initialNumItems: roadmapPageSize },
+      );
+    },
+
+    useSearchRoadmap(searchQuery: string, limit = 10) {
+      const normalized = searchQuery.trim();
+      return useQuery(
+        api.searchRoadmap,
+        normalized.length === 0 ? "skip" : { searchQuery: normalized, limit },
+      );
+    },
+
+    useRoadmapFeedback(roadmapId: string | null | undefined) {
+      return usePaginatedQuery(
+        api.listRoadmapFeedback,
+        roadmapId === null || roadmapId === undefined ? "skip" : { roadmapId },
+        { initialNumItems: entryPageSize },
+      );
+    },
+
     /**
      * Reactively finds exact and similar entries for a proposed draft.
      *
@@ -320,6 +417,38 @@ function createFeedbackHooksImplementation<RateLimitResult>(
       return useMutation(api.setEntryStatus);
     },
 
+    useSetEntryPriority() {
+      return useMutation(api.setEntryPriority);
+    },
+
+    useCreateRoadmap() {
+      return useMutation(api.createRoadmap);
+    },
+
+    useCreateRoadmapForEntry() {
+      return useMutation(api.createRoadmapForEntry);
+    },
+
+    useUpdateRoadmap() {
+      return useMutation(api.updateRoadmap);
+    },
+
+    useDeleteRoadmap() {
+      return useMutation(api.deleteRoadmap);
+    },
+
+    useMoveRoadmapItem() {
+      return useMutation(api.moveRoadmapItem);
+    },
+
+    useAttachFeedbackToRoadmap() {
+      return useMutation(api.attachFeedbackToRoadmap);
+    },
+
+    useDetachFeedbackFromRoadmap() {
+      return useMutation(api.detachFeedbackFromRoadmap);
+    },
+
     /** Returns the idempotent entry-upvote state mutation. */
     useSetEntryUpvote() {
       return useMutation(api.setEntryUpvote);
@@ -353,18 +482,24 @@ type CreatedFeedbackHooks<RateLimitResult> = ReturnType<
 
 /** Creates hooks for a feedback API whose rate limiters reject by throwing. */
 export function createFeedbackHooks(
-  api: FeedbackPublicApi<string | undefined, never>,
+  api?: FeedbackPublicApi<string | undefined, never>,
   options?: FeedbackHooksOptions,
 ): CreatedFeedbackHooks<never>;
 
 /** Creates hooks carrying a validated non-throwing rate-limit result. */
 export function createFeedbackHooks<RateLimitResult>(
-  api: FeedbackPublicApi<string | undefined, RateLimitResult>,
+  api?: FeedbackPublicApi<string | undefined, RateLimitResult>,
   options?: FeedbackHooksOptions,
 ): CreatedFeedbackHooks<RateLimitResult>;
 
 export function createFeedbackHooks<RateLimitResult>(
-  api: FeedbackPublicApi<string | undefined, RateLimitResult>,
+  api: FeedbackPublicApi<
+    string | undefined,
+    RateLimitResult
+  > = anyApi.feedback as unknown as FeedbackPublicApi<
+    string | undefined,
+    RateLimitResult
+  >,
   options: FeedbackHooksOptions = {},
 ): CreatedFeedbackHooks<RateLimitResult> {
   return createFeedbackHooksImplementation(api, options);