@btst/stack 2.7.0 → 2.8.1

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

@@ -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.mjs';
+export { a as COMMENTS_LOCALIZATION } from '../../../shared/stack.Ldfkr5b2.mjs';
+
+/**
+ * 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 };

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

@@ -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.js';
+export { a as COMMENTS_LOCALIZATION } from '../../../shared/stack.Ldfkr5b2.js';
+
+/**
+ * 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 };

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

@@ -0,0 +1,2 @@
+export { commentsClientPlugin } from '../../../packages/stack/src/plugins/comments/client/plugin.mjs';
+export { COMMENTS_LOCALIZATION } from '../../../packages/stack/src/plugins/comments/client/localization/index.mjs';

package/dist/plugins/comments/client.css

@@ -0,0 +1,2 @@
+/* Comments Plugin Client CSS */
+/* No custom styles needed - uses shadcn/ui components */

package/dist/plugins/comments/query-keys.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+const queryKeyFactory = require('@lukemorales/query-key-factory');
+const queryKeyDefs = require('../../packages/stack/src/plugins/comments/api/query-key-defs.cjs');
+const utils = require('../../packages/stack/src/plugins/comments/client/utils.cjs');
+
+function isErrorResponse(response) {
+  return typeof response === "object" && response !== null && "error" in response && response.error !== null && response.error !== void 0;
+}
+function createCommentsQueryKeys(client, headers) {
+  return queryKeyFactory.mergeQueryKeys(
+    createCommentsQueries(client, headers),
+    createCommentCountQueries(client, headers),
+    createCommentsThreadQueries(client, headers)
+  );
+}
+function createCommentsQueries(client, headers) {
+  return queryKeyFactory.createQueryKeys("comments", {
+    list: (params) => ({
+      queryKey: [queryKeyDefs.commentsListDiscriminator(params)],
+      queryFn: async () => {
+        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 utils.toError(response.error);
+        }
+        const data = response.data;
+        return data ?? { items: [], total: 0, limit: 20, offset: 0 };
+      }
+    })
+  });
+}
+function createCommentCountQueries(client, headers) {
+  return queryKeyFactory.createQueryKeys("commentCount", {
+    byResource: (params) => ({
+      queryKey: [queryKeyDefs.commentCountDiscriminator(params)],
+      queryFn: async () => {
+        const response = await client("/comments/count", {
+          method: "GET",
+          query: {
+            resourceId: params.resourceId,
+            resourceType: params.resourceType,
+            status: params.status
+          },
+          headers
+        });
+        if (isErrorResponse(response)) {
+          throw utils.toError(response.error);
+        }
+        const data = response.data;
+        return data?.count ?? 0;
+      }
+    })
+  });
+}
+function createCommentsThreadQueries(client, headers) {
+  return queryKeyFactory.createQueryKeys("commentsThread", {
+    list: (params) => ({
+      // Offset is excluded from the key — it is driven by pageParam.
+      queryKey: [queryKeyDefs.commentsThreadDiscriminator(params)],
+      queryFn: async ({
+        pageParam
+      } = {}) => {
+        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 utils.toError(response.error);
+        }
+        const data = response.data;
+        return data ?? {
+          items: [],
+          total: 0,
+          limit: params?.limit ?? 20,
+          offset: pageParam ?? 0
+        };
+      }
+    })
+  });
+}
+
+exports.createCommentsQueryKeys = createCommentsQueryKeys;