@btst/stack 2.7.0 → 2.8.0

package/src/plugins/comments/query-keys.ts

@@ -0,0 +1,189 @@
+import {
+	mergeQueryKeys,
+	createQueryKeys,
+} from "@lukemorales/query-key-factory";
+import type { CommentsApiRouter } from "./api";
+import { createApiClient } from "@btst/stack/plugins/client";
+import type { CommentListResult } from "./types";
+import {
+	commentsListDiscriminator,
+	commentCountDiscriminator,
+	commentsThreadDiscriminator,
+} from "./api/query-key-defs";
+import { toError } from "./client/utils";
+
+interface CommentsListParams {
+	resourceId?: string;
+	resourceType?: string;
+	parentId?: string | null;
+	status?: "pending" | "approved" | "spam";
+	currentUserId?: string;
+	authorId?: string;
+	sort?: "asc" | "desc";
+	limit?: number;
+	offset?: number;
+}
+
+interface CommentCountParams {
+	resourceId: string;
+	resourceType: string;
+	status?: "pending" | "approved" | "spam";
+}
+
+function isErrorResponse(
+	response: unknown,
+): response is { error: unknown; data?: never } {
+	return (
+		typeof response === "object" &&
+		response !== null &&
+		"error" in response &&
+		(response as Record<string, unknown>).error !== null &&
+		(response as Record<string, unknown>).error !== undefined
+	);
+}
+
+export function createCommentsQueryKeys(
+	client: ReturnType<typeof createApiClient<CommentsApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return mergeQueryKeys(
+		createCommentsQueries(client, headers),
+		createCommentCountQueries(client, headers),
+		createCommentsThreadQueries(client, headers),
+	);
+}
+
+function createCommentsQueries(
+	client: ReturnType<typeof createApiClient<CommentsApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createQueryKeys("comments", {
+		list: (params?: CommentsListParams) => ({
+			queryKey: [commentsListDiscriminator(params)],
+			queryFn: async (): Promise<CommentListResult> => {
+				const response = await client("/comments", {
+					method: "GET",
+					query: {
+						resourceId: params?.resourceId,
+						resourceType: params?.resourceType,
+						parentId: params?.parentId === null ? "null" : params?.parentId,
+						status: params?.status,
+						// currentUserId is intentionally NOT sent to the server.
+						// The server resolves the caller's identity server-side via the
+						// resolveCurrentUserId hook. Sending it would allow any caller to
+						// impersonate another user and read their pending comments.
+						// It is still included in the queryKey above for client-side
+						// cache segregation (different users get different cache entries).
+						authorId: params?.authorId,
+						sort: params?.sort,
+						limit: params?.limit ?? 20,
+						offset: params?.offset ?? 0,
+					},
+					headers,
+				});
+
+				if (isErrorResponse(response)) {
+					throw toError((response as { error: unknown }).error);
+				}
+
+				const data = (response as { data?: unknown }).data as
+					| CommentListResult
+					| undefined;
+				return data ?? { items: [], total: 0, limit: 20, offset: 0 };
+			},
+		}),
+	});
+}
+
+function createCommentCountQueries(
+	client: ReturnType<typeof createApiClient<CommentsApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createQueryKeys("commentCount", {
+		byResource: (params: CommentCountParams) => ({
+			queryKey: [commentCountDiscriminator(params)],
+			queryFn: async (): Promise<number> => {
+				const response = await client("/comments/count", {
+					method: "GET",
+					query: {
+						resourceId: params.resourceId,
+						resourceType: params.resourceType,
+						status: params.status,
+					},
+					headers,
+				});
+
+				if (isErrorResponse(response)) {
+					throw toError((response as { error: unknown }).error);
+				}
+
+				const data = (response as { data?: unknown }).data as
+					| { count: number }
+					| undefined;
+				return data?.count ?? 0;
+			},
+		}),
+	});
+}
+
+/**
+ * Factory for the infinite thread query key family.
+ * Mirrors the blog's `createPostsQueries` pattern: the key is stable (no offset),
+ * and pages are fetched via `pageParam` passed to the queryFn.
+ */
+function createCommentsThreadQueries(
+	client: ReturnType<typeof createApiClient<CommentsApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createQueryKeys("commentsThread", {
+		list: (params?: {
+			resourceId?: string;
+			resourceType?: string;
+			parentId?: string | null;
+			status?: "pending" | "approved" | "spam";
+			currentUserId?: string;
+			limit?: number;
+		}) => ({
+			// Offset is excluded from the key — it is driven by pageParam.
+			queryKey: [commentsThreadDiscriminator(params)],
+			queryFn: async ({
+				pageParam,
+			}: {
+				pageParam?: number;
+			} = {}): Promise<CommentListResult> => {
+				const response = await client("/comments", {
+					method: "GET",
+					query: {
+						resourceId: params?.resourceId,
+						resourceType: params?.resourceType,
+						parentId: params?.parentId === null ? "null" : params?.parentId,
+						status: params?.status,
+						// currentUserId is intentionally NOT sent to the server.
+						// The server resolves the caller's identity server-side via the
+						// resolveCurrentUserId hook. It is still included in the queryKey
+						// above for client-side cache segregation.
+						limit: params?.limit ?? 20,
+						offset: pageParam ?? 0,
+					},
+					headers,
+				});
+
+				if (isErrorResponse(response)) {
+					throw toError((response as { error: unknown }).error);
+				}
+
+				const data = (response as { data?: unknown }).data as
+					| CommentListResult
+					| undefined;
+				return (
+					data ?? {
+						items: [],
+						total: 0,
+						limit: params?.limit ?? 20,
+						offset: pageParam ?? 0,
+					}
+				);
+			},
+		}),
+	});
+}

package/src/plugins/comments/schemas.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+
+export const CommentStatusSchema = z.enum(["pending", "approved", "spam"]);
+
+// ============ Comment Schemas ============
+
+/**
+ * Schema for the POST /comments request body.
+ * authorId is intentionally absent — the server resolves identity from the
+ * session inside onBeforePost and injects it. Never trust authorId from the
+ * client body.
+ */
+export const createCommentSchema = z.object({
+	resourceId: z.string().min(1, "Resource ID is required"),
+	resourceType: z.string().min(1, "Resource type is required"),
+	parentId: z.string().optional().nullable(),
+	body: z.string().min(1, "Body is required").max(10000, "Comment too long"),
+});
+
+/**
+ * Internal schema used after the authorId has been resolved server-side.
+ * This is what gets passed to createComment() in mutations.ts.
+ */
+export const createCommentInternalSchema = createCommentSchema.extend({
+	authorId: z.string().min(1, "Author ID is required"),
+});
+
+export const updateCommentSchema = z.object({
+	body: z.string().min(1, "Body is required").max(10000, "Comment too long"),
+});
+
+export const updateCommentStatusSchema = z.object({
+	status: CommentStatusSchema,
+});
+
+// ============ Query Schemas ============
+
+/**
+ * Schema for GET /comments query parameters.
+ *
+ * `currentUserId` is intentionally absent — it is never accepted from the client.
+ * The server always resolves the caller's identity via the `resolveCurrentUserId`
+ * hook and injects it internally. Accepting it from the client would allow any
+ * anonymous caller to supply an arbitrary user ID and read that user's pending
+ * (pre-moderation) comments.
+ */
+export const CommentListQuerySchema = z.object({
+	resourceId: z.string().optional(),
+	resourceType: z.string().optional(),
+	parentId: z.string().optional().nullable(),
+	status: CommentStatusSchema.optional(),
+	authorId: z.string().optional(),
+	sort: z.enum(["asc", "desc"]).optional(),
+	limit: z.coerce.number().int().min(1).max(100).optional(),
+	offset: z.coerce.number().int().min(0).optional(),
+});
+
+/**
+ * Internal params schema used by `listComments()` and the `api` factory.
+ * Extends the HTTP query schema with `currentUserId`, which is always injected
+ * server-side (either by the HTTP handler via `resolveCurrentUserId`, or by a
+ * trusted server-side caller such as a Server Component or cron job).
+ */
+export const CommentListParamsSchema = CommentListQuerySchema.extend({
+	currentUserId: z.string().optional(),
+});
+
+export const CommentCountQuerySchema = z.object({
+	resourceId: z.string().min(1),
+	resourceType: z.string().min(1),
+	status: CommentStatusSchema.optional(),
+});

package/src/plugins/comments/style.css

@@ -0,0 +1,15 @@
+@import "./client.css";
+
+/*
+ * Comments Plugin CSS - Includes Tailwind class scanning
+ *
+ * When consumed from npm, Tailwind v4 will automatically scan this package's
+ * source files for Tailwind classes. Consumers only need:
+ *   @import "@btst/stack/plugins/comments/css";
+ */
+
+/* Scan this package's source files for Tailwind classes */
+@source "../../../src/**/*.{ts,tsx}";
+
+/* Scan UI package components (when installed as npm package the UI package will be in this dir) */
+@source "../../packages/ui/src";

package/src/plugins/comments/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Comment status values
+ */
+export type CommentStatus = "pending" | "approved" | "spam";
+
+/**
+ * A comment record as stored in the database
+ */
+export type Comment = {
+	id: string;
+	resourceId: string;
+	resourceType: string;
+	parentId: string | null;
+	authorId: string;
+	body: string;
+	status: CommentStatus;
+	likes: number;
+	editedAt?: Date;
+	createdAt: Date;
+	updatedAt: Date;
+};
+
+/**
+ * A like record linking an author to a comment
+ */
+export type CommentLike = {
+	id: string;
+	commentId: string;
+	authorId: string;
+	createdAt: Date;
+};
+
+/**
+ * A comment enriched with server-resolved author info and like status.
+ * All dates are ISO strings (safe for serialisation over HTTP / React Query cache).
+ */
+export interface SerializedComment {
+	id: string;
+	resourceId: string;
+	resourceType: string;
+	parentId: string | null;
+	authorId: string;
+	/** Resolved from resolveUser(authorId). Falls back to "[deleted]" when user cannot be found. */
+	resolvedAuthorName: string;
+	/** Resolved avatar URL or null */
+	resolvedAvatarUrl: string | null;
+	body: string;
+	status: CommentStatus;
+	/** Denormalized counter — updated atomically on toggleLike */
+	likes: number;
+	/** True when the currentUserId query param matches an existing commentLike row */
+	isLikedByCurrentUser: boolean;
+	/** ISO string set when the comment body was edited; null for unedited comments */
+	editedAt: string | null;
+	createdAt: string;
+	updatedAt: string;
+	/**
+	 * Number of direct replies visible to the requesting user.
+	 * Includes approved replies plus any pending replies authored by `currentUserId`.
+	 * Always 0 for reply comments (non-null parentId).
+	 */
+	replyCount: number;
+}
+
+/**
+ * Paginated list result for comments
+ */
+export interface CommentListResult {
+	items: SerializedComment[];
+	total: number;
+	limit: number;
+	offset: number;
+}

package/src/plugins/kanban/client/components/forms/task-form.tsx

@@ -226,7 +226,6 @@ export function TaskForm({
 					}
 					output="markdown"
 					placeholder="Describe the task..."
-					editable={!isPending}
 					className="min-h-[150px]"
 				/>
 			</div>

package/src/plugins/kanban/client/components/pages/board-page.internal.tsx

@@ -66,8 +66,11 @@ export function BoardPage({ boardId }: BoardPageProps) {
 		throw error;
 	}
 
-	const { Link: OverrideLink, navigate: overrideNavigate } =
-		usePluginOverrides<KanbanPluginOverrides>("kanban");
+	const {
+		Link: OverrideLink,
+		navigate: overrideNavigate,
+		taskDetailBottomSlot,
+	} = usePluginOverrides<KanbanPluginOverrides>("kanban");
 	const navigate =
 		overrideNavigate ||
 		((path: string) => {
@@ -540,33 +543,49 @@ export function BoardPage({ boardId }: BoardPageProps) {
 						<DialogDescription>Update task details.</DialogDescription>
 					</DialogHeader>
 					{modalState.type === "editTask" && (
-						<TaskForm
-							columnId={modalState.columnId}
-							boardId={boardId}
-							taskId={modalState.taskId}
-							task={board.columns
-								?.find((c) => c.id === modalState.columnId)
-								?.tasks?.find((t) => t.id === modalState.taskId)}
-							columns={board.columns || []}
-							onClose={closeModal}
-							onSuccess={() => {
-								closeModal();
-								refetch();
-							}}
-							onDelete={async () => {
-								try {
-									await deleteTask(modalState.taskId);
+						<>
+							<TaskForm
+								columnId={modalState.columnId}
+								boardId={boardId}
+								taskId={modalState.taskId}
+								task={board.columns
+									?.find((c) => c.id === modalState.columnId)
+									?.tasks?.find((t) => t.id === modalState.taskId)}
+								columns={board.columns || []}
+								onClose={closeModal}
+								onSuccess={() => {
 									closeModal();
 									refetch();
-								} catch (error) {
-									const message =
-										error instanceof Error
-											? error.message
-											: "Failed to delete task";
-									toast.error(message);
-								}
-							}}
-						/>
+								}}
+								onDelete={async () => {
+									try {
+										await deleteTask(modalState.taskId);
+										closeModal();
+										refetch();
+									} catch (error) {
+										const message =
+											error instanceof Error
+												? error.message
+												: "Failed to delete task";
+										toast.error(message);
+									}
+								}}
+							/>
+							{taskDetailBottomSlot &&
+								(() => {
+									const task = board.columns
+										?.find((c) => c.id === modalState.columnId)
+										?.tasks?.find((t) => t.id === modalState.taskId);
+									return task ? (
+										<div
+											className="mt-4 pt-4 border-t"
+											data-testid="task-detail-bottom-slot"
+										>
+											{taskDetailBottomSlot(task)}
+										</div>
+									) : null;
+								})()}
+						</>
 					)}
 				</DialogContent>
 			</Dialog>

package/src/plugins/kanban/client/overrides.ts

@@ -1,5 +1,6 @@
-import type { ComponentType } from "react";
+import type { ComponentType, ReactNode } from "react";
 import type { KanbanLocalization } from "./localization";
+import type { SerializedTask } from "../types";
 
 /**
  * User information for assignee display/selection
@@ -142,4 +143,29 @@ export interface KanbanPluginOverrides {
 	 * @param context - Route context
 	 */
 	onBeforeNewBoardPageRendered?: (context: RouteContext) => boolean;
+
+	// ============ Slot Overrides ============
+
+	/**
+	 * Optional slot rendered at the bottom of the task detail dialog.
+	 * Use this to inject a comment thread or any custom content without
+	 * coupling the kanban plugin to the comments plugin.
+	 *
+	 * @example
+	 * ```tsx
+	 * kanban: {
+	 *   taskDetailBottomSlot: (task) => (
+	 *     <CommentThread
+	 *       resourceId={task.id}
+	 *       resourceType="kanban-task"
+	 *       apiBaseURL={apiBaseURL}
+	 *       apiBasePath="/api/data"
+	 *       currentUserId={session?.userId}
+	 *       loginHref="/login"
+	 *     />
+	 *   ),
+	 * }
+	 * ```
+	 */
+	taskDetailBottomSlot?: (task: SerializedTask) => ReactNode;
 }

package/dist/shared/{stack.Rtcvl8sS.d.cts → stack.BOokfhZD.d.cts}

@@ -28,8 +28,8 @@ declare const createColumnSchema: z.ZodObject<{
     title: z.ZodString;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     boardId: z.ZodString;
+    order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, z.core.$strip>;
 declare const updateColumnSchema: z.ZodObject<{
     createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
@@ -404,14 +404,14 @@ declare const kanbanBackendPlugin: (hooks?: KanbanBackendHooks) => _btst_stack_p
             title?: string | undefined;
             createdAt?: unknown;
             updatedAt?: unknown;
-            order?: number | undefined;
             boardId?: string | undefined;
+            order?: number | undefined;
         }, {
             title?: string | undefined;
             createdAt?: unknown;
             updatedAt?: unknown;
-            order?: number | undefined;
             boardId?: string | undefined;
+            order?: number | undefined;
         }>;
     }, Column>;
     readonly deleteColumn: better_call.StrictEndpoint<"/columns/:id", {} & {

package/dist/shared/{stack.D4Cea8II.d.ts → stack.BvCR4-9H.d.ts}

@@ -28,8 +28,8 @@ declare const createColumnSchema: z.ZodObject<{
     title: z.ZodString;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     boardId: z.ZodString;
+    order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, z.core.$strip>;
 declare const updateColumnSchema: z.ZodObject<{
     createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
@@ -404,14 +404,14 @@ declare const kanbanBackendPlugin: (hooks?: KanbanBackendHooks) => _btst_stack_p
             title?: string | undefined;
             createdAt?: unknown;
             updatedAt?: unknown;
-            order?: number | undefined;
             boardId?: string | undefined;
+            order?: number | undefined;
         }, {
             title?: string | undefined;
             createdAt?: unknown;
             updatedAt?: unknown;
-            order?: number | undefined;
             boardId?: string | undefined;
+            order?: number | undefined;
         }>;
     }, Column>;
     readonly deleteColumn: better_call.StrictEndpoint<"/columns/:id", {} & {

package/dist/shared/{stack.HE_IvqV5.d.mts → stack.CWxAl9K3.d.mts}

@@ -28,8 +28,8 @@ declare const createColumnSchema: z.ZodObject<{
     title: z.ZodString;
     createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
-    order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     boardId: z.ZodString;
+    order: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, z.core.$strip>;
 declare const updateColumnSchema: z.ZodObject<{
     createdAt: z.ZodOptional<z.ZodOptional<z.ZodCoercedDate<unknown>>>;
@@ -404,14 +404,14 @@ declare const kanbanBackendPlugin: (hooks?: KanbanBackendHooks) => _btst_stack_p
             title?: string | undefined;
             createdAt?: unknown;
             updatedAt?: unknown;
-            order?: number | undefined;
             boardId?: string | undefined;
+            order?: number | undefined;
         }, {
             title?: string | undefined;
             createdAt?: unknown;
             updatedAt?: unknown;
-            order?: number | undefined;
             boardId?: string | undefined;
+            order?: number | undefined;
         }>;
     }, Column>;
     readonly deleteColumn: better_call.StrictEndpoint<"/columns/:id", {} & {