@btst/stack 2.7.0 → 2.8.0

package/dist/plugins/comments/client/components/index.d.ts

@@ -0,0 +1,125 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentType } from 'react';
+import { C as CommentsLocalization } from '../../../../shared/stack.Ldfkr5b2.js';
+
+/** Custom input component props */
+interface CommentInputProps {
+    value: string;
+    onChange: (value: string) => void;
+    disabled?: boolean;
+    placeholder?: string;
+}
+/** Custom renderer component props */
+interface CommentRendererProps {
+    body: string;
+}
+/** Override slot for custom input + renderer */
+interface CommentComponents {
+    Input?: ComponentType<CommentInputProps>;
+    Renderer?: ComponentType<CommentRendererProps>;
+}
+interface CommentThreadProps {
+    /** The resource this thread is attached to (e.g. post slug, task ID) */
+    resourceId: string;
+    /** Discriminates resources across plugins (e.g. "blog-post", "kanban-task") */
+    resourceType: string;
+    /** Base URL for API calls */
+    apiBaseURL: string;
+    /** Path where the API is mounted */
+    apiBasePath: string;
+    /** Currently authenticated user ID. Omit for read-only / unauthenticated. */
+    currentUserId?: string;
+    /**
+     * URL to redirect unauthenticated users to.
+     * When provided and currentUserId is absent, shows a "Please login to comment" prompt.
+     */
+    loginHref?: string;
+    /** Optional HTTP headers for API calls (e.g. forwarding cookies) */
+    headers?: HeadersInit;
+    /** Swap in custom Input / Renderer components */
+    components?: CommentComponents;
+    /** Optional className applied to the root wrapper */
+    className?: string;
+    /** Localization strings — defaults to English */
+    localization?: Partial<CommentsLocalization>;
+    /**
+     * Number of top-level comments to load per page.
+     * Clicking "Load more" fetches the next page. Default: 10.
+     */
+    pageSize?: number;
+    /**
+     * When false, the comment form and reply buttons are hidden.
+     * Overrides the global `allowPosting` from `CommentsPluginOverrides`.
+     * Defaults to true.
+     */
+    allowPosting?: boolean;
+    /**
+     * When false, the edit button is hidden on comment cards.
+     * Overrides the global `allowEditing` from `CommentsPluginOverrides`.
+     * Defaults to true.
+     */
+    allowEditing?: boolean;
+}
+declare function CommentThread(props: CommentThreadProps): react_jsx_runtime.JSX.Element;
+
+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"
+ * />
+ * ```
+ */
+declare function CommentCount({ resourceId, resourceType, status, apiBaseURL, apiBasePath, headers, className, }: CommentCountProps): react_jsx_runtime.JSX.Element;
+
+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>;
+}
+declare function CommentForm({ authorId: _authorId, initialBody, submitLabel, onSubmit, onCancel, InputComponent, localization: localizationProp, }: CommentFormProps): react_jsx_runtime.JSX.Element;
+
+declare function ModerationPageComponent(): react_jsx_runtime.JSX.Element;
+
+declare function ResourceCommentsPageComponent({ resourceId, resourceType, }: {
+    resourceId: string;
+    resourceType: string;
+}): react_jsx_runtime.JSX.Element;
+
+export { CommentCount, CommentForm, CommentThread, ModerationPageComponent, ResourceCommentsPageComponent };
+export type { CommentComponents, CommentCountProps, CommentFormProps, CommentInputProps, CommentRendererProps, CommentThreadProps };

package/dist/plugins/comments/client/components/index.mjs

@@ -0,0 +1,5 @@
+export { CommentThread } from '../../../../packages/stack/src/plugins/comments/client/components/comment-thread.mjs';
+export { CommentCount } from '../../../../packages/stack/src/plugins/comments/client/components/comment-count.mjs';
+export { CommentForm } from '../../../../packages/stack/src/plugins/comments/client/components/comment-form.mjs';
+export { ModerationPageComponent } from '../../../../packages/stack/src/plugins/comments/client/components/pages/moderation-page.mjs';
+export { ResourceCommentsPageComponent } from '../../../../packages/stack/src/plugins/comments/client/components/pages/resource-comments-page.mjs';

package/dist/plugins/comments/client/hooks/index.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+const useComments = require('../../../../packages/stack/src/plugins/comments/client/hooks/use-comments.cjs');
+
+
+
+exports.useApproveComment = useComments.useApproveComment;
+exports.useCommentCount = useComments.useCommentCount;
+exports.useComments = useComments.useComments;
+exports.useDeleteComment = useComments.useDeleteComment;
+exports.useInfiniteComments = useComments.useInfiniteComments;
+exports.usePostComment = useComments.usePostComment;
+exports.useSuspenseComments = useComments.useSuspenseComments;
+exports.useSuspenseModerationComments = useComments.useSuspenseModerationComments;
+exports.useToggleLike = useComments.useToggleLike;
+exports.useUpdateComment = useComments.useUpdateComment;
+exports.useUpdateCommentStatus = useComments.useUpdateCommentStatus;

package/dist/plugins/comments/client/hooks/index.d.cts

@@ -0,0 +1,200 @@
+import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C-b3Sn8j.cjs';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { InfiniteData } from '@tanstack/react-query';
+
+interface CommentsClientConfig {
+    apiBaseURL: string;
+    apiBasePath: string;
+    headers?: HeadersInit;
+}
+/**
+ * Fetch a paginated list of comments for a resource.
+ * Returns approved comments by default.
+ */
+declare function useComments(config: CommentsClientConfig, params: {
+    resourceId?: string;
+    resourceType?: string;
+    parentId?: string | null;
+    status?: "pending" | "approved" | "spam";
+    currentUserId?: string;
+    authorId?: string;
+    sort?: "asc" | "desc";
+    limit?: number;
+    offset?: number;
+}, options?: {
+    enabled?: boolean;
+}): {
+    data: CommentListResult | undefined;
+    comments: SerializedComment[];
+    total: number;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<CommentListResult, Error>>;
+};
+/**
+ * useSuspenseQuery version — for use in .internal.tsx files.
+ */
+declare function useSuspenseComments(config: CommentsClientConfig, params: {
+    resourceId?: string;
+    resourceType?: string;
+    parentId?: string | null;
+    status?: "pending" | "approved" | "spam";
+    currentUserId?: string;
+    authorId?: string;
+    sort?: "asc" | "desc";
+    limit?: number;
+    offset?: number;
+}): {
+    comments: SerializedComment[];
+    total: number;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<CommentListResult, Error>>;
+};
+/**
+ * Page-based variant for the moderation dashboard.
+ * Uses useSuspenseQuery with explicit offset so the table always shows exactly
+ * one page of results and navigation is handled by Prev / Next controls.
+ */
+declare function useSuspenseModerationComments(config: CommentsClientConfig, params: {
+    status?: "pending" | "approved" | "spam";
+    limit?: number;
+    page?: number;
+}): {
+    comments: SerializedComment[];
+    total: number;
+    limit: number;
+    offset: number;
+    totalPages: number;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<CommentListResult, Error>>;
+};
+/**
+ * Infinite-scroll variant for the CommentThread component.
+ * Uses the "commentsThread" factory namespace (separate from the plain
+ * useComments / useSuspenseComments queries) to avoid InfiniteData shape conflicts.
+ *
+ * Mirrors the blog's usePosts pattern: spread the factory base query into
+ * useInfiniteQuery, drive pages via pageParam, and derive hasMore from server total.
+ */
+declare function useInfiniteComments(config: CommentsClientConfig, params: {
+    resourceId: string;
+    resourceType: string;
+    parentId?: string | null;
+    status?: "pending" | "approved" | "spam";
+    currentUserId?: string;
+    pageSize?: number;
+}, options?: {
+    enabled?: boolean;
+}): {
+    comments: SerializedComment[];
+    total: number;
+    queryKey: readonly ["commentsThread", "list", CommentsThreadDiscriminator];
+    isLoading: boolean;
+    isFetching: boolean;
+    loadMore: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<InfiniteData<CommentListResult, unknown>, Error>>;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+};
+/**
+ * Fetch the approved comment count for a resource.
+ */
+declare function useCommentCount(config: CommentsClientConfig, params: {
+    resourceId: string;
+    resourceType: string;
+    status?: "pending" | "approved" | "spam";
+}): {
+    count: number;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Post a new comment with optimistic update.
+ * When autoApprove is false the optimistic entry shows as "pending" — visible
+ * only to the comment's own author via the `currentUserId` match in the UI.
+ *
+ * Pass `infiniteKey` (from `useInfiniteComments`) when the thread uses an
+ * infinite query so the optimistic update targets InfiniteData<CommentListResult>
+ * instead of a plain CommentListResult cache entry.
+ */
+declare function usePostComment(config: CommentsClientConfig, params: {
+    resourceId: string;
+    resourceType: string;
+    currentUserId?: string;
+    /** When provided, optimistic updates target this infinite-query cache key. */
+    infiniteKey?: readonly unknown[];
+    /**
+     * Page size used by the corresponding `useInfiniteComments` call.
+     * Used only when the infinite-query cache is empty at the time of the
+     * optimistic update — ensures `getNextPageParam` computes the correct
+     * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
+     */
+    pageSize?: number;
+}): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
+    body: string;
+    parentId?: string | null;
+    limit?: number;
+    offset?: number;
+}, {
+    previous: InfiniteData<CommentListResult, unknown> | undefined;
+    isInfinite: true;
+    listKey: readonly unknown[];
+    optimisticId: string;
+} | {
+    previous: CommentListResult | undefined;
+    isInfinite: false;
+    listKey: readonly unknown[];
+    optimisticId: string;
+}>;
+/**
+ * Edit the body of an existing comment.
+ */
+declare function useUpdateComment(config: CommentsClientConfig): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
+    id: string;
+    body: string;
+}, unknown>;
+/**
+ * Approve a comment (set status to "approved"). Admin use.
+ */
+declare function useApproveComment(config: CommentsClientConfig): _tanstack_react_query.UseMutationResult<SerializedComment, Error, string, unknown>;
+/**
+ * Update comment status (pending / approved / spam). Admin use.
+ */
+declare function useUpdateCommentStatus(config: CommentsClientConfig): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
+    id: string;
+    status: "pending" | "approved" | "spam";
+}, unknown>;
+/**
+ * Delete a comment. Admin use.
+ */
+declare function useDeleteComment(config: CommentsClientConfig): _tanstack_react_query.UseMutationResult<{
+    success: boolean;
+}, Error, string, unknown>;
+/**
+ * Toggle a like on a comment with optimistic update.
+ *
+ * Pass `infiniteKey` (from `useInfiniteComments`) for top-level thread comments
+ * so the optimistic update targets InfiniteData<CommentListResult> instead of
+ * a plain CommentListResult cache entry.
+ */
+declare function useToggleLike(config: CommentsClientConfig, params: {
+    resourceId: string;
+    resourceType: string;
+    /** parentId of the comment being liked — must match the parentId used by
+     *  useComments so the optimistic setQueryData hits the correct cache entry.
+     *  Pass `null` for top-level comments, or the parent comment ID for replies. */
+    parentId?: string | null;
+    currentUserId?: string;
+    /** When the comment lives in an infinite thread, pass the thread's query key
+     *  so the optimistic update targets the correct InfiniteData cache entry. */
+    infiniteKey?: readonly unknown[];
+}): _tanstack_react_query.UseMutationResult<{
+    likes: number;
+    isLiked: boolean;
+}, Error, {
+    commentId: string;
+    authorId: string;
+}, {
+    previous: CommentListResult | InfiniteData<CommentListResult, unknown> | undefined;
+}>;
+
+export { useApproveComment, useCommentCount, useComments, useDeleteComment, useInfiniteComments, usePostComment, useSuspenseComments, useSuspenseModerationComments, useToggleLike, useUpdateComment, useUpdateCommentStatus };

package/dist/plugins/comments/client/hooks/index.d.mts

@@ -0,0 +1,200 @@
+import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C-b3Sn8j.mjs';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { InfiniteData } from '@tanstack/react-query';
+
+interface CommentsClientConfig {
+    apiBaseURL: string;
+    apiBasePath: string;
+    headers?: HeadersInit;
+}
+/**
+ * Fetch a paginated list of comments for a resource.
+ * Returns approved comments by default.
+ */
+declare function useComments(config: CommentsClientConfig, params: {
+    resourceId?: string;
+    resourceType?: string;
+    parentId?: string | null;
+    status?: "pending" | "approved" | "spam";
+    currentUserId?: string;
+    authorId?: string;
+    sort?: "asc" | "desc";
+    limit?: number;
+    offset?: number;
+}, options?: {
+    enabled?: boolean;
+}): {
+    data: CommentListResult | undefined;
+    comments: SerializedComment[];
+    total: number;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<CommentListResult, Error>>;
+};
+/**
+ * useSuspenseQuery version — for use in .internal.tsx files.
+ */
+declare function useSuspenseComments(config: CommentsClientConfig, params: {
+    resourceId?: string;
+    resourceType?: string;
+    parentId?: string | null;
+    status?: "pending" | "approved" | "spam";
+    currentUserId?: string;
+    authorId?: string;
+    sort?: "asc" | "desc";
+    limit?: number;
+    offset?: number;
+}): {
+    comments: SerializedComment[];
+    total: number;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<CommentListResult, Error>>;
+};
+/**
+ * Page-based variant for the moderation dashboard.
+ * Uses useSuspenseQuery with explicit offset so the table always shows exactly
+ * one page of results and navigation is handled by Prev / Next controls.
+ */
+declare function useSuspenseModerationComments(config: CommentsClientConfig, params: {
+    status?: "pending" | "approved" | "spam";
+    limit?: number;
+    page?: number;
+}): {
+    comments: SerializedComment[];
+    total: number;
+    limit: number;
+    offset: number;
+    totalPages: number;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<CommentListResult, Error>>;
+};
+/**
+ * Infinite-scroll variant for the CommentThread component.
+ * Uses the "commentsThread" factory namespace (separate from the plain
+ * useComments / useSuspenseComments queries) to avoid InfiniteData shape conflicts.
+ *
+ * Mirrors the blog's usePosts pattern: spread the factory base query into
+ * useInfiniteQuery, drive pages via pageParam, and derive hasMore from server total.
+ */
+declare function useInfiniteComments(config: CommentsClientConfig, params: {
+    resourceId: string;
+    resourceType: string;
+    parentId?: string | null;
+    status?: "pending" | "approved" | "spam";
+    currentUserId?: string;
+    pageSize?: number;
+}, options?: {
+    enabled?: boolean;
+}): {
+    comments: SerializedComment[];
+    total: number;
+    queryKey: readonly ["commentsThread", "list", CommentsThreadDiscriminator];
+    isLoading: boolean;
+    isFetching: boolean;
+    loadMore: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<InfiniteData<CommentListResult, unknown>, Error>>;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+};
+/**
+ * Fetch the approved comment count for a resource.
+ */
+declare function useCommentCount(config: CommentsClientConfig, params: {
+    resourceId: string;
+    resourceType: string;
+    status?: "pending" | "approved" | "spam";
+}): {
+    count: number;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Post a new comment with optimistic update.
+ * When autoApprove is false the optimistic entry shows as "pending" — visible
+ * only to the comment's own author via the `currentUserId` match in the UI.
+ *
+ * Pass `infiniteKey` (from `useInfiniteComments`) when the thread uses an
+ * infinite query so the optimistic update targets InfiniteData<CommentListResult>
+ * instead of a plain CommentListResult cache entry.
+ */
+declare function usePostComment(config: CommentsClientConfig, params: {
+    resourceId: string;
+    resourceType: string;
+    currentUserId?: string;
+    /** When provided, optimistic updates target this infinite-query cache key. */
+    infiniteKey?: readonly unknown[];
+    /**
+     * Page size used by the corresponding `useInfiniteComments` call.
+     * Used only when the infinite-query cache is empty at the time of the
+     * optimistic update — ensures `getNextPageParam` computes the correct
+     * `nextOffset` from `lastPage.limit` instead of a hardcoded fallback.
+     */
+    pageSize?: number;
+}): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
+    body: string;
+    parentId?: string | null;
+    limit?: number;
+    offset?: number;
+}, {
+    previous: InfiniteData<CommentListResult, unknown> | undefined;
+    isInfinite: true;
+    listKey: readonly unknown[];
+    optimisticId: string;
+} | {
+    previous: CommentListResult | undefined;
+    isInfinite: false;
+    listKey: readonly unknown[];
+    optimisticId: string;
+}>;
+/**
+ * Edit the body of an existing comment.
+ */
+declare function useUpdateComment(config: CommentsClientConfig): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
+    id: string;
+    body: string;
+}, unknown>;
+/**
+ * Approve a comment (set status to "approved"). Admin use.
+ */
+declare function useApproveComment(config: CommentsClientConfig): _tanstack_react_query.UseMutationResult<SerializedComment, Error, string, unknown>;
+/**
+ * Update comment status (pending / approved / spam). Admin use.
+ */
+declare function useUpdateCommentStatus(config: CommentsClientConfig): _tanstack_react_query.UseMutationResult<SerializedComment, Error, {
+    id: string;
+    status: "pending" | "approved" | "spam";
+}, unknown>;
+/**
+ * Delete a comment. Admin use.
+ */
+declare function useDeleteComment(config: CommentsClientConfig): _tanstack_react_query.UseMutationResult<{
+    success: boolean;
+}, Error, string, unknown>;
+/**
+ * Toggle a like on a comment with optimistic update.
+ *
+ * Pass `infiniteKey` (from `useInfiniteComments`) for top-level thread comments
+ * so the optimistic update targets InfiniteData<CommentListResult> instead of
+ * a plain CommentListResult cache entry.
+ */
+declare function useToggleLike(config: CommentsClientConfig, params: {
+    resourceId: string;
+    resourceType: string;
+    /** parentId of the comment being liked — must match the parentId used by
+     *  useComments so the optimistic setQueryData hits the correct cache entry.
+     *  Pass `null` for top-level comments, or the parent comment ID for replies. */
+    parentId?: string | null;
+    currentUserId?: string;
+    /** When the comment lives in an infinite thread, pass the thread's query key
+     *  so the optimistic update targets the correct InfiniteData cache entry. */
+    infiniteKey?: readonly unknown[];
+}): _tanstack_react_query.UseMutationResult<{
+    likes: number;
+    isLiked: boolean;
+}, Error, {
+    commentId: string;
+    authorId: string;
+}, {
+    previous: CommentListResult | InfiniteData<CommentListResult, unknown> | undefined;
+}>;
+
+export { useApproveComment, useCommentCount, useComments, useDeleteComment, useInfiniteComments, usePostComment, useSuspenseComments, useSuspenseModerationComments, useToggleLike, useUpdateComment, useUpdateCommentStatus };