@btst/stack 2.7.0 → 2.8.0

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

@@ -0,0 +1,200 @@
+import { C as CommentListResult, S as SerializedComment, a as CommentsThreadDiscriminator } from '../../../../shared/stack.C-b3Sn8j.js';
+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.mjs

@@ -0,0 +1 @@
+export { useApproveComment, useCommentCount, useComments, useDeleteComment, useInfiniteComments, usePostComment, useSuspenseComments, useSuspenseModerationComments, useToggleLike, useUpdateComment, useUpdateCommentStatus } from '../../../../packages/stack/src/plugins/comments/client/hooks/use-comments.mjs';

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

@@ -0,0 +1,9 @@
+'use strict';
+
+const plugin = require('../../../packages/stack/src/plugins/comments/client/plugin.cjs');
+const index = require('../../../packages/stack/src/plugins/comments/client/localization/index.cjs');
+
+
+
+exports.commentsClientPlugin = plugin.commentsClientPlugin;
+exports.COMMENTS_LOCALIZATION = index.COMMENTS_LOCALIZATION;

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

@@ -0,0 +1,262 @@
+import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
+import * as React from 'react';
+import * as _btst_yar from '@btst/yar';
+import { QueryClient } from '@tanstack/react-query';
+import { C as CommentsLocalization } from '../../../shared/stack.Ldfkr5b2.cjs';
+export { a as COMMENTS_LOCALIZATION } from '../../../shared/stack.Ldfkr5b2.cjs';
+
+/**
+ * Context passed to loader hooks
+ */
+interface LoaderContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    /** Base URL for API calls */
+    apiBaseURL: string;
+    /** Path where the API is mounted */
+    apiBasePath: string;
+    /** Optional headers for the request */
+    headers?: Headers;
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/**
+ * Hooks for Comments client plugin
+ */
+interface CommentsClientHooks {
+    /**
+     * Called before loading the moderation page. Throw to cancel.
+     */
+    beforeLoadModeration?: (context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called before loading the User Comments page. Throw to cancel.
+     */
+    beforeLoadUserComments?: (context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called when a loading error occurs.
+     */
+    onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
+}
+/**
+ * Configuration for the Comments client plugin
+ */
+interface CommentsClientConfig {
+    /** Base URL for API calls (e.g., "http://localhost:3000") */
+    apiBaseURL: string;
+    /** Path where the API is mounted (e.g., "/api/data") */
+    apiBasePath: string;
+    /** Base URL of your site */
+    siteBaseURL: string;
+    /** Path where pages are mounted (e.g., "/pages") */
+    siteBasePath: string;
+    /** React Query client instance */
+    queryClient: QueryClient;
+    /** Optional headers for SSR */
+    headers?: Headers;
+    /** Optional lifecycle hooks */
+    hooks?: CommentsClientHooks;
+}
+/**
+ * Comments client plugin — registers admin moderation routes.
+ *
+ * The embeddable `CommentThread` and `CommentCount` components are standalone
+ * and do not require this plugin to be registered. Register them manually
+ * via the layout overrides pattern or use them directly in your pages.
+ */
+declare const commentsClientPlugin: (config: CommentsClientConfig) => _btst_stack_plugins_client.ClientPlugin<Record<string, never>, {
+    moderation: {
+        (inputCtx_0?: _btst_yar.InputContext<"/comments/moderation", _btst_yar.RouteOptions> | undefined): {
+            PageComponent?: React.ComponentType<unknown> | undefined;
+            LoadingComponent?: React.ComponentType<unknown> | undefined;
+            ErrorComponent?: React.ComponentType<unknown> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+                property?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+                property?: undefined;
+            } | {
+                property: string;
+                content: string;
+                title?: undefined;
+                name?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/comments/moderation";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+    userComments: {
+        (inputCtx_0?: _btst_yar.InputContext<"/comments", _btst_yar.RouteOptions> | undefined): {
+            PageComponent?: React.ComponentType<unknown> | undefined;
+            LoadingComponent?: React.ComponentType<unknown> | undefined;
+            ErrorComponent?: React.ComponentType<unknown> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+                property?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+                property?: undefined;
+            } | {
+                property: string;
+                content: string;
+                title?: undefined;
+                name?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/comments";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+}>;
+
+/**
+ * Context passed to lifecycle hooks
+ */
+interface RouteContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters (e.g., { resourceId: "my-post", resourceType: "blog-post" }) */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+
+/**
+ * Overridable configuration and hooks for the Comments plugin.
+ *
+ * Provide these in the layout wrapping your pages via `PluginOverridesProvider`.
+ */
+interface CommentsPluginOverrides {
+    /**
+     * Localization strings for all Comments plugin UI.
+     * Defaults to English when not provided.
+     */
+    localization?: Partial<CommentsLocalization>;
+    /**
+     * Base URL for API calls (e.g., "https://example.com")
+     */
+    apiBaseURL: string;
+    /**
+     * Path where the API is mounted (e.g., "/api/data")
+     */
+    apiBasePath: string;
+    /**
+     * Optional headers for authenticated API calls (e.g., forwarding cookies)
+     */
+    headers?: Record<string, string>;
+    /**
+     * Whether to show the "Powered by BTST" attribution on plugin pages.
+     * Defaults to true.
+     */
+    showAttribution?: boolean;
+    /**
+     * The ID of the currently authenticated user.
+     *
+     * Used by the User Comments page and the per-resource comments admin view to
+     * scope the comment list to the current user and to enable posting.
+     * Can be a static string or an async function (useful when the user ID must
+     * be resolved from a session cookie at render time).
+     *
+     * When absent both pages show a "Please log in" prompt.
+     */
+    currentUserId?: string | (() => string | undefined | Promise<string | undefined>);
+    /**
+     * URL to redirect unauthenticated users to when they try to post a comment.
+     *
+     * Forwarded to every embedded `CommentThread` (including the one on the
+     * per-resource admin comments view). When absent no login link is shown.
+     */
+    loginHref?: string;
+    /**
+     * Default number of top-level comments to load per page in `CommentThread`.
+     * Can be overridden per-instance via the `pageSize` prop.
+     * Defaults to 100 when not set.
+     */
+    defaultCommentPageSize?: number;
+    /**
+     * When false, the comment form and reply buttons are hidden in all
+     * `CommentThread` instances. Users can still read existing comments.
+     * Defaults to true.
+     *
+     * Can be overridden per-instance via the `allowPosting` prop on `CommentThread`.
+     */
+    allowPosting?: boolean;
+    /**
+     * When false, the edit button is hidden on all comment cards in all
+     * `CommentThread` instances.
+     * Defaults to true.
+     *
+     * Can be overridden per-instance via the `allowEditing` prop on `CommentThread`.
+     */
+    allowEditing?: boolean;
+    /**
+     * Per-resource-type URL builders used to link each comment back to its
+     * original resource on the User Comments page.
+     *
+     * @example
+     * ```ts
+     * resourceLinks: {
+     *   "blog-post": (slug) => `/pages/blog/${slug}`,
+     *   "kanban-task": (id) => `/pages/kanban?task=${id}`,
+     * }
+     * ```
+     *
+     * When a resource type has no entry the ID is shown as plain text.
+     */
+    resourceLinks?: Record<string, (id: string) => string>;
+    /**
+     * Called before the moderation dashboard page is rendered.
+     * Return false to block rendering (e.g., redirect to login or show 403).
+     * @param context - Route context
+     */
+    onBeforeModerationPageRendered?: (context: RouteContext) => boolean;
+    /**
+     * Called before the per-resource comments page is rendered.
+     * Return false to block rendering (e.g., for authorization).
+     * @param resourceType - The type of resource (e.g., "blog-post")
+     * @param resourceId - The ID of the resource
+     * @param context - Route context
+     */
+    onBeforeResourceCommentsRendered?: (resourceType: string, resourceId: string, context: RouteContext) => boolean;
+    /**
+     * Called before the User Comments page is rendered.
+     * Throw to block rendering (e.g., when the user is not authenticated).
+     * @param context - Route context
+     */
+    onBeforeUserCommentsPageRendered?: (context: RouteContext) => boolean | void;
+    /**
+     * Called when a route is rendered.
+     * @param routeName - Name of the route (e.g., 'moderation', 'resourceComments')
+     * @param context - Route context
+     */
+    onRouteRender?: (routeName: string, context: RouteContext) => void | Promise<void>;
+    /**
+     * Called when a route encounters an error.
+     * @param routeName - Name of the route
+     * @param error - The error that occurred
+     * @param context - Route context
+     */
+    onRouteError?: (routeName: string, error: Error, context: RouteContext) => void | Promise<void>;
+}
+
+export { CommentsLocalization, commentsClientPlugin };
+export type { CommentsClientConfig, CommentsClientHooks, CommentsPluginOverrides, LoaderContext, RouteContext };