@btst/stack 2.7.0 → 2.8.0

package/src/plugins/comments/api/query-key-defs.ts

@@ -0,0 +1,143 @@
+/**
+ * Internal query key constants for the Comments plugin.
+ * Shared between query-keys.ts (HTTP path) and any SSG/direct DB path
+ * to prevent key drift between loaders and prefetch calls.
+ */
+
+export interface CommentsListDiscriminator {
+	resourceId: string | undefined;
+	resourceType: string | undefined;
+	parentId: string | null | undefined;
+	status: string | undefined;
+	currentUserId: string | undefined;
+	authorId: string | undefined;
+	sort: string | undefined;
+	limit: number;
+	offset: number;
+}
+
+/**
+ * Builds the discriminator object for the comments list query key.
+ */
+export function commentsListDiscriminator(params?: {
+	resourceId?: string;
+	resourceType?: string;
+	parentId?: string | null;
+	status?: string;
+	currentUserId?: string;
+	authorId?: string;
+	sort?: string;
+	limit?: number;
+	offset?: number;
+}): CommentsListDiscriminator {
+	return {
+		resourceId: params?.resourceId,
+		resourceType: params?.resourceType,
+		parentId: params?.parentId,
+		status: params?.status,
+		currentUserId: params?.currentUserId,
+		authorId: params?.authorId,
+		sort: params?.sort,
+		limit: params?.limit ?? 20,
+		offset: params?.offset ?? 0,
+	};
+}
+
+export interface CommentCountDiscriminator {
+	resourceId: string;
+	resourceType: string;
+	status: string | undefined;
+}
+
+export function commentCountDiscriminator(params: {
+	resourceId: string;
+	resourceType: string;
+	status?: string;
+}): CommentCountDiscriminator {
+	return {
+		resourceId: params.resourceId,
+		resourceType: params.resourceType,
+		status: params.status,
+	};
+}
+
+/**
+ * Discriminator for the infinite thread query (top-level comments only).
+ * Intentionally excludes `offset` — pages are driven by `pageParam`, not the key.
+ */
+export interface CommentsThreadDiscriminator {
+	resourceId: string | undefined;
+	resourceType: string | undefined;
+	parentId: string | null | undefined;
+	status: string | undefined;
+	currentUserId: string | undefined;
+	limit: number;
+}
+
+export function commentsThreadDiscriminator(params?: {
+	resourceId?: string;
+	resourceType?: string;
+	parentId?: string | null;
+	status?: string;
+	currentUserId?: string;
+	limit?: number;
+}): CommentsThreadDiscriminator {
+	return {
+		resourceId: params?.resourceId,
+		resourceType: params?.resourceType,
+		parentId: params?.parentId,
+		status: params?.status,
+		currentUserId: params?.currentUserId,
+		limit: params?.limit ?? 20,
+	};
+}
+
+/** Full query key builders — use with queryClient.setQueryData() */
+export const COMMENTS_QUERY_KEYS = {
+	/**
+	 * Key for comments list query.
+	 * Full key: ["comments", "list", { resourceId, resourceType, parentId, status, currentUserId, limit, offset }]
+	 */
+	commentsList: (params?: {
+		resourceId?: string;
+		resourceType?: string;
+		parentId?: string | null;
+		status?: string;
+		currentUserId?: string;
+		authorId?: string;
+		sort?: string;
+		limit?: number;
+		offset?: number;
+	}) => ["comments", "list", commentsListDiscriminator(params)] as const,
+
+	/**
+	 * Key for a single comment detail query.
+	 * Full key: ["comments", "detail", id]
+	 */
+	commentDetail: (id: string) => ["comments", "detail", id] as const,
+
+	/**
+	 * Key for comment count query.
+	 * Full key: ["comments", "count", { resourceId, resourceType, status }]
+	 */
+	commentCount: (params: {
+		resourceId: string;
+		resourceType: string;
+		status?: string;
+	}) => ["comments", "count", commentCountDiscriminator(params)] as const,
+
+	/**
+	 * Key for the infinite thread query (top-level comments, load-more).
+	 * Full key: ["commentsThread", "list", { resourceId, resourceType, parentId, status, currentUserId, limit }]
+	 * Offset is excluded — it is driven by `pageParam`, not baked into the key.
+	 */
+	commentsThread: (params?: {
+		resourceId?: string;
+		resourceType?: string;
+		parentId?: string | null;
+		status?: string;
+		currentUserId?: string;
+		limit?: number;
+	}) =>
+		["commentsThread", "list", commentsThreadDiscriminator(params)] as const,
+};

package/src/plugins/comments/api/serializers.ts

@@ -0,0 +1,37 @@
+import type { Comment, SerializedComment } from "../types";
+
+/**
+ * Serialize a raw Comment DB record into a SerializedComment for SSG/setQueryData.
+ * Note: resolvedAuthorName, resolvedAvatarUrl, and isLikedByCurrentUser are not
+ * available from the DB record alone — use getters.ts enrichment for those.
+ * This serializer is for cases where you already have a SerializedComment from
+ * the HTTP layer and just need a type-safe round-trip.
+ *
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeComment(comment: Comment): Omit<
+	SerializedComment,
+	"resolvedAuthorName" | "resolvedAvatarUrl" | "isLikedByCurrentUser"
+> & {
+	resolvedAuthorName: string;
+	resolvedAvatarUrl: null;
+	isLikedByCurrentUser: false;
+} {
+	return {
+		id: comment.id,
+		resourceId: comment.resourceId,
+		resourceType: comment.resourceType,
+		parentId: comment.parentId ?? null,
+		authorId: comment.authorId,
+		resolvedAuthorName: "[deleted]",
+		resolvedAvatarUrl: null,
+		isLikedByCurrentUser: false,
+		body: comment.body,
+		status: comment.status,
+		likes: comment.likes,
+		editedAt: comment.editedAt?.toISOString() ?? null,
+		createdAt: comment.createdAt.toISOString(),
+		updatedAt: comment.updatedAt.toISOString(),
+		replyCount: 0,
+	};
+}

package/src/plugins/comments/client/components/comment-count.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { MessageSquare } from "lucide-react";
+import { useCommentCount } from "../hooks/use-comments";
+
+export interface CommentCountProps {
+	resourceId: string;
+	resourceType: string;
+	/** Only count approved comments (default) */
+	status?: "pending" | "approved" | "spam";
+	apiBaseURL: string;
+	apiBasePath: string;
+	headers?: HeadersInit;
+	/** Optional className for the wrapper span */
+	className?: string;
+}
+
+/**
+ * Lightweight badge showing the comment count for a resource.
+ * Does not mount a full comment thread — suitable for post list cards.
+ *
+ * @example
+ * ```tsx
+ * <CommentCount
+ *   resourceId={post.slug}
+ *   resourceType="blog-post"
+ *   apiBaseURL="https://example.com"
+ *   apiBasePath="/api/data"
+ * />
+ * ```
+ */
+export function CommentCount({
+	resourceId,
+	resourceType,
+	status = "approved",
+	apiBaseURL,
+	apiBasePath,
+	headers,
+	className,
+}: CommentCountProps) {
+	const { count, isLoading } = useCommentCount(
+		{ apiBaseURL, apiBasePath, headers },
+		{ resourceId, resourceType, status },
+	);
+
+	if (isLoading) {
+		return (
+			<span
+				className={`inline-flex items-center gap-1 text-xs text-muted-foreground ${className ?? ""}`}
+			>
+				<MessageSquare className="h-3.5 w-3.5" />
+				<span className="animate-pulse">…</span>
+			</span>
+		);
+	}
+
+	return (
+		<span
+			className={`inline-flex items-center gap-1 text-xs text-muted-foreground ${className ?? ""}`}
+			data-testid="comment-count"
+		>
+			<MessageSquare className="h-3.5 w-3.5" />
+			{count}
+		</span>
+	);
+}

package/src/plugins/comments/client/components/comment-form.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import { useState, type ComponentType } from "react";
+import { Button } from "@workspace/ui/components/button";
+import { Textarea } from "@workspace/ui/components/textarea";
+import {
+	COMMENTS_LOCALIZATION,
+	type CommentsLocalization,
+} from "../localization";
+
+export interface CommentFormProps {
+	/** Current user's ID — required to post */
+	authorId: string;
+	/** Optional parent comment ID for replies */
+	parentId?: string | null;
+	/** Initial body value (for editing) */
+	initialBody?: string;
+	/** Label for the submit button */
+	submitLabel?: string;
+	/** Called when form is submitted */
+	onSubmit: (body: string) => Promise<void>;
+	/** Called when cancel is clicked (shows Cancel button when provided) */
+	onCancel?: () => void;
+	/** Custom input component — defaults to a plain Textarea */
+	InputComponent?: ComponentType<{
+		value: string;
+		onChange: (value: string) => void;
+		disabled?: boolean;
+		placeholder?: string;
+	}>;
+	/** Localization strings */
+	localization?: Partial<CommentsLocalization>;
+}
+
+export function CommentForm({
+	authorId: _authorId,
+	initialBody = "",
+	submitLabel,
+	onSubmit,
+	onCancel,
+	InputComponent,
+	localization: localizationProp,
+}: CommentFormProps) {
+	const loc = { ...COMMENTS_LOCALIZATION, ...localizationProp };
+	const [body, setBody] = useState(initialBody);
+	const [isPending, setIsPending] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+
+	const resolvedSubmitLabel = submitLabel ?? loc.COMMENTS_FORM_POST_COMMENT;
+
+	const handleSubmit = async (e: React.FormEvent) => {
+		e.preventDefault();
+		if (!body.trim()) return;
+		setError(null);
+		setIsPending(true);
+		try {
+			await onSubmit(body.trim());
+			setBody("");
+		} catch (err) {
+			setError(
+				err instanceof Error ? err.message : loc.COMMENTS_FORM_SUBMIT_ERROR,
+			);
+		} finally {
+			setIsPending(false);
+		}
+	};
+
+	return (
+		<form
+			data-testid="comment-form"
+			onSubmit={handleSubmit}
+			className="flex flex-col gap-2"
+		>
+			{InputComponent ? (
+				<InputComponent
+					value={body}
+					onChange={setBody}
+					disabled={isPending}
+					placeholder={loc.COMMENTS_FORM_PLACEHOLDER}
+				/>
+			) : (
+				<Textarea
+					value={body}
+					onChange={(e) => setBody(e.target.value)}
+					placeholder={loc.COMMENTS_FORM_PLACEHOLDER}
+					disabled={isPending}
+					rows={3}
+					className="resize-none"
+				/>
+			)}
+
+			{error && <p className="text-sm text-destructive">{error}</p>}
+
+			<div className="flex gap-2 justify-end">
+				{onCancel && (
+					<Button
+						type="button"
+						variant="ghost"
+						size="sm"
+						onClick={onCancel}
+						disabled={isPending}
+					>
+						{loc.COMMENTS_FORM_CANCEL}
+					</Button>
+				)}
+				<Button type="submit" size="sm" disabled={isPending || !body.trim()}>
+					{isPending ? loc.COMMENTS_FORM_POSTING : resolvedSubmitLabel}
+				</Button>
+			</div>
+		</form>
+	);
+}