@btst/stack 1.4.1 → 1.5.1

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

@@ -0,0 +1,409 @@
+import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
+import * as react from 'react';
+import { ComponentType } from 'react';
+import * as _btst_yar from '@btst/yar';
+import { QueryClient } from '@tanstack/react-query';
+import { a as AutoFormInputComponentProps } from '../../../shared/stack.NZJogTUn.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import 'react-hook-form';
+import 'zod';
+
+/**
+ * Context passed to loader hooks
+ */
+interface LoaderContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters (e.g., { typeSlug: "product", id: "123" }) */
+    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 CMS client plugin
+ * All hooks are optional and allow consumers to customize behavior
+ */
+interface CMSClientHooks {
+    /**
+     * Called before loading the dashboard page. Return false to cancel loading.
+     * @param context - Loader context with path, params, etc.
+     */
+    beforeLoadDashboard?: (context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * Called after the dashboard is loaded.
+     * @param context - Loader context
+     */
+    afterLoadDashboard?: (context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called before loading a content list page. Return false to cancel loading.
+     * @param typeSlug - The content type slug
+     * @param context - Loader context
+     */
+    beforeLoadContentList?: (typeSlug: string, context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * Called after a content list is loaded.
+     * @param typeSlug - The content type slug
+     * @param context - Loader context
+     */
+    afterLoadContentList?: (typeSlug: string, context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called before loading the content editor page. Return false to cancel loading.
+     * @param typeSlug - The content type slug
+     * @param id - The content item ID (undefined for new items)
+     * @param context - Loader context
+     */
+    beforeLoadContentEditor?: (typeSlug: string, id: string | undefined, context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * Called after the content editor is loaded.
+     * @param typeSlug - The content type slug
+     * @param id - The content item ID (undefined for new items)
+     * @param context - Loader context
+     */
+    afterLoadContentEditor?: (typeSlug: string, id: string | undefined, context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called when a loading error occurs.
+     * Use this for redirects on authorization failures.
+     * @param error - The error that occurred
+     * @param context - Loader context
+     */
+    onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
+}
+/**
+ * Configuration for CMS client plugin
+ */
+interface CMSClientConfig {
+    /** 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 for caching */
+    queryClient: QueryClient;
+    /** Optional headers for SSR (e.g., forwarding cookies) */
+    headers?: Headers;
+    /** Optional hooks for customizing behavior (authorization, redirects, etc.) */
+    hooks?: CMSClientHooks;
+}
+/**
+ * CMS client plugin
+ * Provides routes and components for the CMS admin interface
+ */
+declare const cmsClientPlugin: (config: CMSClientConfig) => _btst_stack_plugins_client.ClientPlugin<Record<string, never>, {
+    dashboard: {
+        (inputCtx_0?: _btst_yar.InputContext<"/cms", _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;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/cms";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+    contentList: {
+        (inputCtx_0: _btst_yar.InputContext<"/cms/:typeSlug", _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;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/cms/:typeSlug";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+    newContent: {
+        (inputCtx_0: _btst_yar.InputContext<"/cms/:typeSlug/new", _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;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/cms/:typeSlug/new";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+    editContent: {
+        (inputCtx_0: _btst_yar.InputContext<"/cms/:typeSlug/:id", _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;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/cms/:typeSlug/:id";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+}>;
+
+declare const CMS_LOCALIZATION: {
+    CMS_EDITOR_TITLE_NEW: string;
+    CMS_EDITOR_TITLE_EDIT: string;
+    CMS_EDITOR_SLUG_AUTO: string;
+    CMS_EDITOR_SLUG_MANUAL: string;
+    CMS_EDITOR_DELETE_CONFIRM: string;
+    CMS_EDITOR_UNSAVED_CHANGES: string;
+    CMS_LIST_TITLE: string;
+    CMS_LIST_EMPTY: string;
+    CMS_LIST_EMPTY_DESCRIPTION: string;
+    CMS_LIST_COLUMN_SLUG: string;
+    CMS_LIST_COLUMN_CREATED: string;
+    CMS_LIST_COLUMN_UPDATED: string;
+    CMS_LIST_COLUMN_ACTIONS: string;
+    CMS_LIST_ACTION_EDIT: string;
+    CMS_LIST_ACTION_DELETE: string;
+    CMS_LIST_PAGINATION_SHOWING: string;
+    CMS_LIST_PAGINATION_PREVIOUS: string;
+    CMS_LIST_PAGINATION_NEXT: string;
+    CMS_DASHBOARD_TITLE: string;
+    CMS_DASHBOARD_SUBTITLE: string;
+    CMS_DASHBOARD_NO_TYPES: string;
+    CMS_DASHBOARD_NO_TYPES_DESCRIPTION: string;
+    CMS_DASHBOARD_ITEMS_COUNT: string;
+    CMS_DASHBOARD_ITEMS_COUNT_ZERO: string;
+    CMS_DASHBOARD_ITEMS_COUNT_ONE: string;
+    CMS_TOAST_CREATE_SUCCESS: string;
+    CMS_TOAST_UPDATE_SUCCESS: string;
+    CMS_TOAST_DELETE_SUCCESS: string;
+    CMS_TOAST_ERROR: string;
+    CMS_TOAST_VALIDATION_ERROR: string;
+    CMS_TOAST_DUPLICATE_SLUG: string;
+    CMS_BUTTON_SAVE: string;
+    CMS_BUTTON_CANCEL: string;
+    CMS_BUTTON_DELETE: string;
+    CMS_BUTTON_CREATE: string;
+    CMS_BUTTON_BACK: string;
+    CMS_BUTTON_NEW_ITEM: string;
+    CMS_LABEL_SLUG: string;
+    CMS_LABEL_SLUG_DESCRIPTION: string;
+    CMS_LABEL_CREATED_AT: string;
+    CMS_LABEL_UPDATED_AT: string;
+    CMS_LABEL_ACTIONS: string;
+    CMS_STATUS_LOADING: string;
+    CMS_STATUS_SAVING: string;
+    CMS_STATUS_DELETING: string;
+    CMS_ERROR_GENERIC: string;
+    CMS_ERROR_NOT_FOUND: string;
+    CMS_ERROR_VALIDATION: string;
+    CMS_ATTRIBUTION: string;
+};
+type CMSLocalization = typeof CMS_LOCALIZATION;
+
+/**
+ * Context passed to lifecycle hooks
+ */
+interface RouteContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters (e.g., { typeSlug: "product", id: "123" }) */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/**
+ * Overridable components and functions for the CMS plugin
+ *
+ * External consumers can provide their own implementations of these
+ * to customize the behavior for their framework (Next.js, React Router, etc.)
+ */
+interface CMSPluginOverrides {
+    /**
+     * Link component for navigation
+     */
+    Link?: ComponentType<React.ComponentProps<"a"> & Record<string, unknown>>;
+    /**
+     * 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, unknown>>;
+    /**
+     * Function used to upload an image and return its URL.
+     * Used by the default "file" field component.
+     */
+    uploadImage?: (file: File) => Promise<string>;
+    /**
+     * Custom field components for AutoForm fields.
+     *
+     * These map field type names to React components. Use these to:
+     * - Override built-in field types (checkbox, date, select, radio, switch, textarea, file, number, fallback)
+     * - Add custom field types for your content types
+     *
+     * The component receives AutoFormInputComponentProps which includes:
+     * - field: react-hook-form field controller
+     * - label: the field label
+     * - isRequired: whether the field is required
+     * - fieldConfigItem: the field config (description, inputProps, etc.)
+     * - fieldProps: additional props from fieldConfig.inputProps
+     * - zodItem: the Zod schema for this field
+     *
+     * @example
+     * ```tsx
+     * fieldComponents: {
+     *   // Override the file type with custom S3 upload
+     *   file: ({ field, label, isRequired }) => (
+     *     <MyS3Upload
+     *       value={field.value}
+     *       onChange={field.onChange}
+     *       label={label}
+     *       required={isRequired}
+     *     />
+     *   ),
+     *   // Add a custom rich text editor
+     *   richText: ({ field, label }) => (
+     *     <MyRichTextEditor value={field.value} onChange={field.onChange} />
+     *   ),
+     * }
+     * ```
+     */
+    fieldComponents?: Record<string, ComponentType<AutoFormInputComponentProps>>;
+    /**
+     * Localization object for the CMS plugin
+     */
+    localization?: CMSLocalization;
+    /**
+     * API base URL
+     */
+    apiBaseURL: string;
+    /**
+     * API base path
+     */
+    apiBasePath: string;
+    /**
+     * Whether to show the attribution
+     */
+    showAttribution?: boolean;
+    /**
+     * Optional headers to pass with API requests (e.g., for SSR auth)
+     */
+    headers?: HeadersInit;
+    /**
+     * Called when a route is rendered
+     * @param routeName - Name of the route (e.g., 'dashboard', 'contentList', 'contentEditor')
+     * @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 dashboard page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param context - Route context
+     */
+    onBeforeDashboardRendered?: (context: RouteContext) => boolean;
+    /**
+     * Called before the content list page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param typeSlug - The content type slug
+     * @param context - Route context
+     */
+    onBeforeListRendered?: (typeSlug: string, context: RouteContext) => boolean;
+    /**
+     * Called before the content editor page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param typeSlug - The content type slug
+     * @param id - The content item ID (null for new items)
+     * @param context - Route context
+     */
+    onBeforeEditorRendered?: (typeSlug: string, id: string | null, context: RouteContext) => boolean;
+}
+
+/**
+ * Props for the CMSFileUpload component
+ */
+interface CMSFileUploadProps extends AutoFormInputComponentProps {
+    /**
+     * Function to upload an image file and return the URL.
+     * This is required - consumers must provide an upload implementation.
+     */
+    uploadImage: (file: File) => Promise<string>;
+}
+/**
+ * Default file upload component for CMS image fields.
+ *
+ * This component:
+ * - Accepts image files via file input
+ * - Uses the required uploadImage prop to upload and get a URL
+ * - Shows a preview of the uploaded image
+ * - Allows removing the uploaded image
+ *
+ * You can use this component directly in your fieldComponents override,
+ * or create your own custom component using this as a reference.
+ *
+ * @example
+ * ```tsx
+ * // Use the default component with your upload function
+ * fieldComponents: {
+ *   file: (props) => (
+ *     <CMSFileUpload {...props} uploadImage={myUploadFn} />
+ *   ),
+ * }
+ * ```
+ */
+declare function CMSFileUpload({ label, isRequired, fieldConfigItem, fieldProps, field, uploadImage, }: CMSFileUploadProps): react_jsx_runtime.JSX.Element;
+
+export { AutoFormInputComponentProps, CMSFileUpload, cmsClientPlugin };
+export type { CMSClientConfig, CMSClientHooks, CMSFileUploadProps, CMSLocalization, CMSPluginOverrides, LoaderContext, RouteContext };

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

@@ -0,0 +1,2 @@
+export { cmsClientPlugin } from '../../../packages/better-stack/src/plugins/cms/client/plugin.mjs';
+export { CMSFileUpload } from '../../../packages/better-stack/src/plugins/cms/client/components/forms/file-upload.mjs';

package/dist/plugins/cms/client.css

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

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

@@ -0,0 +1,137 @@
+'use strict';
+
+const queryKeyFactory = require('@lukemorales/query-key-factory');
+
+function isErrorResponse(response) {
+  if (typeof response !== "object" || response === null) {
+    return false;
+  }
+  const obj = response;
+  return "error" in obj && obj.error !== null && obj.error !== void 0;
+}
+function toError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (typeof error === "object" && error !== null) {
+    const errorObj = error;
+    const message = (typeof errorObj.message === "string" ? errorObj.message : null) || (typeof errorObj.error === "string" ? errorObj.error : null) || JSON.stringify(error);
+    const err = new Error(message);
+    Object.assign(err, error);
+    return err;
+  }
+  return new Error(String(error));
+}
+function createCMSQueryKeys(client, headers) {
+  const contentTypes = createContentTypesQueries(client, headers);
+  const content = createContentQueries(client, headers);
+  return queryKeyFactory.mergeQueryKeys(contentTypes, content);
+}
+function createContentTypesQueries(client, headers) {
+  return queryKeyFactory.createQueryKeys("cmsTypes", {
+    list: () => ({
+      queryKey: ["list"],
+      queryFn: async () => {
+        try {
+          const response = await client("/content-types", {
+            method: "GET",
+            headers
+          });
+          if (isErrorResponse(response)) {
+            throw toError(response.error);
+          }
+          return response.data ?? [];
+        } catch (error) {
+          throw error;
+        }
+      }
+    }),
+    detail: (slug) => ({
+      queryKey: [slug],
+      queryFn: async () => {
+        if (!slug) return null;
+        try {
+          const response = await client("/content-types/:slug", {
+            method: "GET",
+            params: { slug },
+            headers
+          });
+          if (isErrorResponse(response)) {
+            throw toError(response.error);
+          }
+          return response.data;
+        } catch (error) {
+          throw error;
+        }
+      }
+    })
+  });
+}
+function createContentQueries(client, headers) {
+  return queryKeyFactory.createQueryKeys("cmsContent", {
+    list: (params) => ({
+      queryKey: [params],
+      queryFn: async () => {
+        try {
+          const response = await client("/content/:typeSlug", {
+            method: "GET",
+            params: { typeSlug: params.typeSlug },
+            query: {
+              limit: params.limit ?? 20,
+              offset: params.offset ?? 0
+            },
+            headers
+          });
+          if (isErrorResponse(response)) {
+            throw toError(response.error);
+          }
+          return response.data;
+        } catch (error) {
+          throw error;
+        }
+      }
+    }),
+    detail: (typeSlug, id) => ({
+      queryKey: [typeSlug, id],
+      queryFn: async () => {
+        if (!typeSlug || !id) return null;
+        try {
+          const response = await client("/content/:typeSlug/:id", {
+            method: "GET",
+            params: { typeSlug, id },
+            headers
+          });
+          if (isErrorResponse(response)) {
+            throw toError(response.error);
+          }
+          return response.data;
+        } catch (error) {
+          throw error;
+        }
+      }
+    }),
+    bySlug: (typeSlug, slug) => ({
+      queryKey: ["bySlug", typeSlug, slug],
+      queryFn: async () => {
+        if (!typeSlug || !slug) return null;
+        try {
+          const response = await client("/content/:typeSlug", {
+            method: "GET",
+            params: { typeSlug },
+            query: { slug, limit: 1 },
+            headers
+          });
+          if (isErrorResponse(response)) {
+            throw toError(response.error);
+          }
+          const data = response.data;
+          return data.items[0] ?? null;
+        } catch (error) {
+          throw error;
+        }
+      }
+    })
+  });
+}
+
+exports.createCMSQueryKeys = createCMSQueryKeys;

package/dist/plugins/cms/query-keys.d.cts

@@ -0,0 +1,79 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { createApiClient } from '@btst/stack/plugins/client';
+import { S as SerializedContentType, P as PaginatedContentItems, a as SerializedContentItemWithType } from '../../shared/stack.BwkyFwF8.cjs';
+import { CMSApiRouter } from './api/index.cjs';
+import 'zod';
+import '../../shared/stack.NZJogTUn.cjs';
+import 'react-hook-form';
+import 'react/jsx-runtime';
+import '@btst/stack/plugins/api';
+import 'better-call';
+
+interface ContentListParams {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Create CMS query keys for React Query
+ * Used by consumers to fetch content types and content items
+ */
+declare function createCMSQueryKeys(client: ReturnType<typeof createApiClient<CMSApiRouter>>, headers?: HeadersInit): {
+    cmsTypes: {
+        _def: readonly ["cmsTypes"];
+    } & {
+        list: (() => Omit<{
+            queryKey: readonly ["cmsTypes", "list", string];
+            queryFn: _tanstack_react_query.QueryFunction<(SerializedContentType & {
+                itemCount: number;
+            })[], readonly ["cmsTypes", "list", string]>;
+        } & {
+            _def: readonly ["cmsTypes", "list"];
+        }, "_def">) & {
+            _def: readonly ["cmsTypes", "list"];
+        };
+        detail: ((slug: string) => Omit<{
+            queryKey: readonly ["cmsTypes", "detail", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedContentType | null, readonly ["cmsTypes", "detail", string]>;
+        } & {
+            _def: readonly ["cmsTypes", "detail"];
+        }, "_def">) & {
+            _def: readonly ["cmsTypes", "detail"];
+        };
+    };
+    cmsContent: {
+        _def: readonly ["cmsContent"];
+    } & {
+        list: ((params: {
+            typeSlug: string;
+        } & ContentListParams) => Omit<{
+            queryKey: readonly ["cmsContent", "list", {
+                typeSlug: string;
+            } & ContentListParams];
+            queryFn: _tanstack_react_query.QueryFunction<PaginatedContentItems<Record<string, unknown>>, readonly ["cmsContent", "list", {
+                typeSlug: string;
+            } & ContentListParams]>;
+        } & {
+            _def: readonly ["cmsContent", "list"];
+        }, "_def">) & {
+            _def: readonly ["cmsContent", "list"];
+        };
+        detail: ((typeSlug: string, id: string) => Omit<{
+            queryKey: readonly ["cmsContent", "detail", string, string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedContentItemWithType<Record<string, unknown>> | null, readonly ["cmsContent", "detail", string, string]>;
+        } & {
+            _def: readonly ["cmsContent", "detail"];
+        }, "_def">) & {
+            _def: readonly ["cmsContent", "detail"];
+        };
+        bySlug: ((typeSlug: string, slug: string) => Omit<{
+            queryKey: readonly ["cmsContent", "bySlug", string, string, string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedContentItemWithType<Record<string, unknown>> | null, readonly ["cmsContent", "bySlug", string, string, string]>;
+        } & {
+            _def: readonly ["cmsContent", "bySlug"];
+        }, "_def">) & {
+            _def: readonly ["cmsContent", "bySlug"];
+        };
+    };
+};
+
+export { createCMSQueryKeys };