@btst/stack 2.6.2 → 2.8.0

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 };

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 };