@btst/stack 1.0.1 → 1.1.1

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

@@ -0,0 +1,150 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { S as SerializedPost, c as createPostSchema, u as updatePostSchema, a as SerializedTag } from '../../../../shared/stack.CoPoHVfV.js';
+import { z } from 'zod';
+
+interface UsePostsOptions {
+    tag?: string;
+    tagSlug?: string;
+    limit?: number;
+    enabled?: boolean;
+    query?: string;
+    published?: boolean;
+    slug?: string;
+}
+interface UsePostsResult {
+    posts: SerializedPost[];
+    isLoading: boolean;
+    error: Error | null;
+    loadMore: () => void;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+    refetch: () => void;
+}
+interface UsePostSearchOptions {
+    query: string;
+    enabled?: boolean;
+    debounceMs?: number;
+    limit?: number;
+    published?: boolean;
+}
+interface UsePostSearchResult {
+    posts: SerializedPost[];
+    data: SerializedPost[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+    isSearching: boolean;
+    searchQuery: string;
+}
+interface UsePostResult {
+    post: SerializedPost | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+type PostCreateInput = z.infer<typeof createPostSchema>;
+type PostUpdateInput = z.infer<typeof updatePostSchema>;
+/**
+ * Hook for fetching paginated posts with load more functionality
+ */
+declare function usePosts(options?: UsePostsOptions): UsePostsResult;
+/** Suspense variant of usePosts */
+declare function useSuspensePosts(options?: UsePostsOptions): {
+    posts: SerializedPost[];
+    loadMore: () => Promise<unknown>;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+    refetch: () => Promise<unknown>;
+};
+/**
+ * Hook for fetching a single post by slug
+ */
+declare function usePost(slug?: string): UsePostResult;
+/** Suspense variant of usePost */
+declare function useSuspensePost(slug: string): {
+    post: SerializedPost | null;
+    refetch: () => Promise<unknown>;
+};
+/**
+ * Hook for fetching all unique tags across posts
+ */
+declare function useTags(): {
+    tags: SerializedTag[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+};
+/** Suspense variant of useTags */
+declare function useSuspenseTags(): {
+    tags: SerializedTag[];
+    refetch: () => Promise<unknown>;
+};
+/** Create a new post */
+declare function useCreatePost(): _tanstack_react_query.UseMutationResult<SerializedPost | null, Error, {
+    published: boolean;
+    title: string;
+    content: string;
+    excerpt: string;
+    tags: ({
+        name: string;
+    } | {
+        id: string;
+        name: string;
+        slug: string;
+    })[];
+    slug?: string | undefined;
+    createdAt?: Date | undefined;
+    publishedAt?: Date | undefined;
+    updatedAt?: Date | undefined;
+    image?: string | undefined;
+}, unknown>;
+/** Update an existing post by id */
+declare function useUpdatePost(): _tanstack_react_query.UseMutationResult<SerializedPost | null, Error, {
+    id: string;
+    data: PostUpdateInput;
+}, unknown>;
+/**
+ * Hook for searching posts by a free-text query. Uses `usePosts` under the hood.
+ * Debounces the query and preserves last successful results to avoid flicker.
+ */
+declare function usePostSearch({ query, enabled, debounceMs, limit, published, }: UsePostSearchOptions): UsePostSearchResult;
+interface UseNextPreviousPostsOptions {
+    enabled?: boolean;
+}
+interface UseNextPreviousPostsResult {
+    previousPost: SerializedPost | null;
+    nextPost: SerializedPost | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+/**
+ * Hook for fetching previous and next posts relative to a given date
+ * Uses useInView to only fetch when the component is in view
+ */
+declare function useNextPreviousPosts(createdAt: string | Date, options?: UseNextPreviousPostsOptions): UseNextPreviousPostsResult & {
+    ref: (node: Element | null) => void;
+    inView: boolean;
+};
+interface UseRecentPostsOptions {
+    limit?: number;
+    excludeSlug?: string;
+    enabled?: boolean;
+}
+interface UseRecentPostsResult {
+    recentPosts: SerializedPost[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+/**
+ * Hook for fetching recent posts
+ * Uses useInView to only fetch when the component is in view
+ */
+declare function useRecentPosts(options?: UseRecentPostsOptions): UseRecentPostsResult & {
+    ref: (node: Element | null) => void;
+    inView: boolean;
+};
+
+export { useCreatePost, useNextPreviousPosts, usePost, usePostSearch, usePosts, useRecentPosts, useSuspensePost, useSuspensePosts, useSuspenseTags, useTags, useUpdatePost };
+export type { PostCreateInput, PostUpdateInput, UseNextPreviousPostsOptions, UseNextPreviousPostsResult, UsePostResult, UsePostSearchOptions, UsePostSearchResult, UsePostsOptions, UsePostsResult, UseRecentPostsOptions, UseRecentPostsResult };

package/dist/plugins/blog/client/hooks/index.mjs

@@ -0,0 +1 @@
+export { useCreatePost, useNextPreviousPosts, usePost, usePostSearch, usePosts, useRecentPosts, useSuspensePost, useSuspensePosts, useSuspenseTags, useTags, useUpdatePost } from './blog-hooks.mjs';

package/dist/plugins/blog/client/hooks/use-debounce.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+const React = require('react');
+
+function useDebounce(value, delay) {
+  const [debouncedValue, setDebouncedValue] = React.useState(value);
+  React.useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay || 500);
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [value, delay]);
+  return debouncedValue;
+}
+
+exports.useDebounce = useDebounce;

package/dist/plugins/blog/client/hooks/use-debounce.mjs

@@ -0,0 +1,14 @@
+import { useState, useEffect } from 'react';
+
+function useDebounce(value, delay) {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay || 500);
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [value, delay]);
+  return debouncedValue;
+}
+
+export { useDebounce };

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

@@ -0,0 +1,7 @@
+'use strict';
+
+const plugin = require('./plugin.cjs');
+
+
+
+exports.blogClientPlugin = plugin.blogClientPlugin;

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

@@ -0,0 +1,414 @@
+import * as react from 'react';
+import { ComponentType } from 'react';
+import * as _btst_yar from '@btst/yar';
+import { QueryClient } from '@tanstack/react-query';
+import { P as Post, S as SerializedPost } from '../../../shared/stack.CoPoHVfV.cjs';
+export { UsePostsOptions, UsePostsResult } from './hooks/index.cjs';
+import 'zod';
+
+/**
+ * Context passed to route hooks
+ */
+interface RouteContext$1 {
+    path: string;
+    params?: Record<string, string>;
+    isSSR: boolean;
+    [key: string]: any;
+}
+/**
+ * Context passed to loader hooks
+ */
+interface LoaderContext {
+    path: string;
+    params?: Record<string, string>;
+    isSSR: boolean;
+    apiBaseURL: string;
+    apiBasePath: string;
+    [key: string]: any;
+}
+/**
+ * Configuration for blog client plugin
+ * Note: queryClient is passed at runtime to both loader and meta (for SSR isolation)
+ */
+interface BlogClientConfig {
+    apiBaseURL: string;
+    apiBasePath: string;
+    siteBaseURL: string;
+    siteBasePath: string;
+    queryClient: QueryClient;
+    seo?: {
+        siteName?: string;
+        author?: string;
+        twitterHandle?: string;
+        locale?: string;
+        defaultImage?: string;
+    };
+    hooks?: BlogClientHooks;
+}
+/**
+ * Hooks for blog client plugin
+ * All hooks are optional and allow consumers to customize behavior
+ */
+interface BlogClientHooks {
+    beforeLoadPosts?: (filter: {
+        published: boolean;
+    }, context: LoaderContext) => Promise<boolean> | boolean;
+    afterLoadPosts?: (posts: Post[] | null, filter: {
+        published: boolean;
+    }, context: LoaderContext) => Promise<void> | void;
+    beforeLoadPost?: (slug: string, context: LoaderContext) => Promise<boolean> | boolean;
+    afterLoadPost?: (post: Post | null, slug: string, context: LoaderContext) => Promise<void> | void;
+    onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
+}
+/**
+ * Blog client plugin
+ * Provides routes, components, and React Query hooks for blog posts
+ *
+ * @param config - Configuration including queryClient, baseURL, and optional hooks
+ */
+declare const blogClientPlugin: (config: BlogClientConfig) => {
+    name: string;
+    routes: () => {
+        posts: {
+            (inputCtx_0?: _btst_yar.InputContext<"/blog", _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: "/blog";
+            meta: _btst_yar.RouteMeta | undefined;
+        };
+        drafts: {
+            (inputCtx_0?: _btst_yar.InputContext<"/blog/drafts", _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: "/blog/drafts";
+            meta: _btst_yar.RouteMeta | undefined;
+        };
+        newPost: {
+            (inputCtx_0?: _btst_yar.InputContext<"/blog/new", _btst_yar.RouteOptions> | undefined): {
+                PageComponent?: react.ComponentType<unknown> | undefined;
+                LoadingComponent?: react.ComponentType<unknown> | undefined;
+                ErrorComponent?: react.ComponentType<unknown> | undefined;
+                loader?: (() => any) | 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: "/blog/new";
+            meta: _btst_yar.RouteMeta | undefined;
+        };
+        editPost: {
+            (inputCtx_0: _btst_yar.InputContext<"/blog/:slug/edit", _btst_yar.RouteOptions>): {
+                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: "/blog/:slug/edit";
+            meta: _btst_yar.RouteMeta | undefined;
+        };
+        tag: {
+            (inputCtx_0: _btst_yar.InputContext<"/blog/tag/:tagSlug", _btst_yar.RouteOptions>): {
+                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: "/blog/tag/:tagSlug";
+            meta: _btst_yar.RouteMeta | undefined;
+        };
+        post: {
+            (inputCtx_0: _btst_yar.InputContext<"/blog/:slug", _btst_yar.RouteOptions>): {
+                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 | undefined;
+                    title?: undefined;
+                    property?: undefined;
+                } | {
+                    property: string;
+                    content: string;
+                    title?: undefined;
+                    name?: undefined;
+                })[]) | undefined;
+                extra?: (() => any) | undefined;
+            };
+            options: _btst_yar.RouteOptions | undefined;
+            path: "/blog/:slug";
+            meta: _btst_yar.RouteMeta | undefined;
+        };
+    };
+    sitemap: () => Promise<({
+        url: string;
+        lastModified: Date | undefined;
+        changeFrequency: "monthly";
+        priority: number;
+    } | {
+        url: string;
+        lastModified: Date | undefined;
+        changeFrequency: "daily";
+        priority: number;
+    })[]>;
+};
+
+declare const BLOG_LOCALIZATION: {
+    BLOG_FORMS_TITLE_LABEL: string;
+    BLOG_FORMS_REQUIRED_ASTERISK: string;
+    BLOG_FORMS_TITLE_PLACEHOLDER: string;
+    BLOG_FORMS_SLUG_LABEL: string;
+    BLOG_FORMS_SLUG_PLACEHOLDER: string;
+    BLOG_FORMS_EXCERPT_LABEL: string;
+    BLOG_FORMS_EXCERPT_PLACEHOLDER: string;
+    BLOG_FORMS_TAGS_LABEL: string;
+    BLOG_FORMS_TAGS_PLACEHOLDER: string;
+    BLOG_FORMS_CONTENT_LABEL: string;
+    BLOG_FORMS_PUBLISHED_LABEL: string;
+    BLOG_FORMS_PUBLISHED_DESCRIPTION: string;
+    BLOG_FORMS_SUBMIT_CREATE_IDLE: string;
+    BLOG_FORMS_SUBMIT_CREATE_PENDING: string;
+    BLOG_FORMS_SUBMIT_UPDATE_IDLE: string;
+    BLOG_FORMS_SUBMIT_UPDATE_PENDING: string;
+    BLOG_FORMS_CANCEL_BUTTON: string;
+    BLOG_FORMS_TOAST_CREATE_SUCCESS: string;
+    BLOG_FORMS_TOAST_UPDATE_SUCCESS: string;
+    BLOG_FORMS_LOADING_POST: string;
+    BLOG_FORMS_EDITOR_PLACEHOLDER: string;
+    BLOG_FORMS_FEATURED_IMAGE_LABEL: string;
+    BLOG_FORMS_FEATURED_IMAGE_REQUIRED_ASTERISK: string;
+    BLOG_FORMS_FEATURED_IMAGE_INPUT_PLACEHOLDER: string;
+    BLOG_FORMS_FEATURED_IMAGE_UPLOAD_BUTTON: string;
+    BLOG_FORMS_FEATURED_IMAGE_UPLOADING_BUTTON: string;
+    BLOG_FORMS_FEATURED_IMAGE_UPLOADING_TEXT: string;
+    BLOG_FORMS_FEATURED_IMAGE_PREVIEW_ALT: string;
+    BLOG_FORMS_FEATURED_IMAGE_ERROR_NOT_IMAGE: string;
+    BLOG_FORMS_FEATURED_IMAGE_ERROR_TOO_LARGE: string;
+    BLOG_FORMS_FEATURED_IMAGE_TOAST_SUCCESS: string;
+    BLOG_FORMS_FEATURED_IMAGE_TOAST_FAILURE: string;
+    BLOG_POST_ADD_TITLE: string;
+    BLOG_POST_ADD_DESCRIPTION: string;
+    BLOG_POST_EDIT_TITLE: string;
+    BLOG_POST_EDIT_DESCRIPTION: string;
+    BLOG_POST_ON_THIS_PAGE: string;
+    BLOG_POST_KEEP_READING: string;
+    BLOG_POST_VIEW_ALL: string;
+    BLOG_CARD_DRAFT_BADGE: string;
+    BLOG_LIST_TITLE: string;
+    BLOG_LIST_DRAFTS_TITLE: string;
+    BLOG_LIST_EMPTY: string;
+    BLOG_LIST_LOAD_MORE: string;
+    BLOG_LIST_LOADING_MORE: string;
+    BLOG_LIST_SEARCH_PLACEHOLDER: string;
+    BLOG_LIST_SEARCH_BUTTON: string;
+    BLOG_LIST_SEARCH_EMPTY: string;
+    BLOG_TAG_PAGE_TITLE: string;
+    BLOG_TAG_PAGE_DESCRIPTION: string;
+    BLOG_TAG_NOT_FOUND: string;
+    BLOG_TAG_NOT_FOUND_DESCRIPTION: string;
+    BLOG_GENERIC_ERROR_TITLE: string;
+    BLOG_GENERIC_ERROR_MESSAGE: string;
+    BLOG_PAGE_NOT_FOUND_TITLE: string;
+    BLOG_PAGE_NOT_FOUND_DESCRIPTION: string;
+};
+type BlogLocalization = typeof BLOG_LOCALIZATION;
+
+/**
+ * Context passed to lifecycle hooks
+ */
+interface RouteContext {
+    path: string;
+    params?: Record<string, string>;
+    isSSR: boolean;
+    [key: string]: any;
+}
+/**
+ * Overridable components and functions for the Blog plugin
+ *
+ * External consumers can provide their own implementations of these
+ * to customize the behavior for their framework (Next.js, React Router, etc.)
+ */
+interface BlogPluginOverrides {
+    Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
+    PostCard?: ComponentType<{
+        post: SerializedPost;
+    }>;
+    /**
+     * Navigation function for programmatic navigation
+     */
+    navigate: (path: string) => void | Promise<void>;
+    /**
+     * Refresh function to invalidate server-side cache (e.g., Next.js router.refresh())
+     */
+    refresh?: () => void | Promise<void>;
+    /**
+     * Image component for displaying images
+     */
+    Image?: ComponentType<React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>>;
+    /**
+     * Function used to upload an image and return its URL.
+     */
+    uploadImage: (file: File) => Promise<string>;
+    /**
+     * Localization object for the blog plugin
+     */
+    localization?: BlogLocalization;
+    /**
+     * API base URL
+     */
+    apiBaseURL: string;
+    /**
+     * API base path
+     */
+    apiBasePath: string;
+    /**
+     * Whether to show the attribution
+     */
+    showAttribution?: boolean;
+    /**
+     * Called when a route is rendered
+     * @param routeName - Name of the route (e.g., 'posts', 'post', 'newPost')
+     * @param context - Route context with path, params, etc.
+     */
+    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>;
+    /**
+     * Called before the posts list page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param context - Route context
+     */
+    onBeforePostsPageRendered?: (context: RouteContext) => boolean;
+    /**
+     * Called before a single post page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param slug - The post slug
+     * @param context - Route context
+     */
+    onBeforePostPageRendered?: (slug: string, context: RouteContext) => boolean;
+    /**
+     * Called before the new post page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param context - Route context
+     */
+    onBeforeNewPostPageRendered?: (context: RouteContext) => boolean;
+    /**
+     * Called before the edit post page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param slug - The post slug being edited
+     * @param context - Route context
+     */
+    onBeforeEditPostPageRendered?: (slug: string, context: RouteContext) => boolean;
+    /**
+     * Called before the drafts page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param context - Route context
+     */
+    onBeforeDraftsPageRendered?: (context: RouteContext) => boolean;
+}
+
+export { blogClientPlugin };
+export type { BlogClientConfig, BlogClientHooks, BlogPluginOverrides, LoaderContext, RouteContext$1 as RouteContext };