@btst/stack 1.4.1 → 1.5.0

package/src/plugins/cms/client/index.ts

@@ -0,0 +1,13 @@
+export { cmsClientPlugin } from "./plugin";
+export type { CMSClientConfig, LoaderContext } from "./plugin";
+export type { CMSPluginOverrides, RouteContext } from "./overrides";
+export type { CMSLocalization } from "./localization";
+
+// Re-export AutoFormInputComponentProps for custom field components
+export type { AutoFormInputComponentProps } from "@workspace/ui/components/ui/auto-form/types";
+
+// Export CMSFileUpload for consumers to use or extend
+export {
+	CMSFileUpload,
+	type CMSFileUploadProps,
+} from "./components/forms/file-upload";

package/src/plugins/cms/client/localization/cms-common.ts

@@ -0,0 +1,29 @@
+export const CMS_COMMON = {
+	// Buttons
+	CMS_BUTTON_SAVE: "Save",
+	CMS_BUTTON_CANCEL: "Cancel",
+	CMS_BUTTON_DELETE: "Delete",
+	CMS_BUTTON_CREATE: "Create",
+	CMS_BUTTON_BACK: "Back",
+	CMS_BUTTON_NEW_ITEM: "New Item",
+
+	// Labels
+	CMS_LABEL_SLUG: "Slug",
+	CMS_LABEL_SLUG_DESCRIPTION: "URL-friendly identifier for this item",
+	CMS_LABEL_CREATED_AT: "Created",
+	CMS_LABEL_UPDATED_AT: "Last Updated",
+	CMS_LABEL_ACTIONS: "Actions",
+
+	// Status
+	CMS_STATUS_LOADING: "Loading...",
+	CMS_STATUS_SAVING: "Saving...",
+	CMS_STATUS_DELETING: "Deleting...",
+
+	// Errors
+	CMS_ERROR_GENERIC: "Something went wrong",
+	CMS_ERROR_NOT_FOUND: "Not found",
+	CMS_ERROR_VALIDATION: "Please fix the errors above",
+
+	// Attribution
+	CMS_ATTRIBUTION: "Powered by Better Stack",
+};

package/src/plugins/cms/client/localization/cms-dashboard.ts

@@ -0,0 +1,10 @@
+export const CMS_DASHBOARD = {
+	CMS_DASHBOARD_TITLE: "Content",
+	CMS_DASHBOARD_SUBTITLE: "Manage your content types",
+	CMS_DASHBOARD_NO_TYPES: "No content types configured",
+	CMS_DASHBOARD_NO_TYPES_DESCRIPTION:
+		"Add content types to your CMS configuration to get started.",
+	CMS_DASHBOARD_ITEMS_COUNT: "{count} items",
+	CMS_DASHBOARD_ITEMS_COUNT_ZERO: "No items",
+	CMS_DASHBOARD_ITEMS_COUNT_ONE: "1 item",
+};

package/src/plugins/cms/client/localization/cms-editor.ts

@@ -0,0 +1,8 @@
+export const CMS_EDITOR = {
+	CMS_EDITOR_TITLE_NEW: "New {typeName}",
+	CMS_EDITOR_TITLE_EDIT: "Edit {typeName}",
+	CMS_EDITOR_SLUG_AUTO: "Auto-generated from first field",
+	CMS_EDITOR_SLUG_MANUAL: "Manually set",
+	CMS_EDITOR_DELETE_CONFIRM: "Are you sure you want to delete this item?",
+	CMS_EDITOR_UNSAVED_CHANGES: "You have unsaved changes",
+};

package/src/plugins/cms/client/localization/cms-list.ts

@@ -0,0 +1,14 @@
+export const CMS_LIST = {
+	CMS_LIST_TITLE: "{typeName}",
+	CMS_LIST_EMPTY: "No items yet",
+	CMS_LIST_EMPTY_DESCRIPTION: "Create your first item to get started.",
+	CMS_LIST_COLUMN_SLUG: "Slug",
+	CMS_LIST_COLUMN_CREATED: "Created",
+	CMS_LIST_COLUMN_UPDATED: "Updated",
+	CMS_LIST_COLUMN_ACTIONS: "Actions",
+	CMS_LIST_ACTION_EDIT: "Edit",
+	CMS_LIST_ACTION_DELETE: "Delete",
+	CMS_LIST_PAGINATION_SHOWING: "Showing {from}-{to} of {total}",
+	CMS_LIST_PAGINATION_PREVIOUS: "Previous",
+	CMS_LIST_PAGINATION_NEXT: "Next",
+};

package/src/plugins/cms/client/localization/cms-toasts.ts

@@ -0,0 +1,8 @@
+export const CMS_TOASTS = {
+	CMS_TOAST_CREATE_SUCCESS: "Item created successfully",
+	CMS_TOAST_UPDATE_SUCCESS: "Item updated successfully",
+	CMS_TOAST_DELETE_SUCCESS: "Item deleted successfully",
+	CMS_TOAST_ERROR: "An error occurred. Please try again.",
+	CMS_TOAST_VALIDATION_ERROR: "Please fix the validation errors",
+	CMS_TOAST_DUPLICATE_SLUG: "An item with this slug already exists",
+};

package/src/plugins/cms/client/localization/index.ts

@@ -0,0 +1,15 @@
+import { CMS_COMMON } from "./cms-common";
+import { CMS_TOASTS } from "./cms-toasts";
+import { CMS_DASHBOARD } from "./cms-dashboard";
+import { CMS_LIST } from "./cms-list";
+import { CMS_EDITOR } from "./cms-editor";
+
+export const CMS_LOCALIZATION = {
+	...CMS_COMMON,
+	...CMS_TOASTS,
+	...CMS_DASHBOARD,
+	...CMS_LIST,
+	...CMS_EDITOR,
+};
+
+export type CMSLocalization = typeof CMS_LOCALIZATION;

package/src/plugins/cms/client/overrides.ts

@@ -0,0 +1,166 @@
+import type { ComponentType } from "react";
+import type { CMSLocalization } from "./localization";
+import type { AutoFormInputComponentProps } from "@workspace/ui/components/ui/auto-form/types";
+
+/**
+ * Context passed to lifecycle hooks
+ */
+export 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.)
+ */
+export 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;
+
+	// Lifecycle Hooks (optional)
+
+	/**
+	 * 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;
+}

package/src/plugins/cms/client/plugin.tsx

@@ -0,0 +1,283 @@
+import { lazy } from "react";
+import {
+	defineClientPlugin,
+	createApiClient,
+} from "@btst/stack/plugins/client";
+import { createRoute } from "@btst/yar";
+import type { QueryClient } from "@tanstack/react-query";
+import type { CMSApiRouter } from "../api";
+import { createCMSQueryKeys } from "../query-keys";
+
+// Lazy load page components for code splitting
+const DashboardPageComponent = lazy(() =>
+	import("./components/pages/dashboard-page").then((m) => ({
+		default: m.DashboardPageComponent,
+	})),
+);
+const ContentListPageComponent = lazy(() =>
+	import("./components/pages/content-list-page").then((m) => ({
+		default: m.ContentListPageComponent,
+	})),
+);
+const ContentEditorPageComponent = lazy(() =>
+	import("./components/pages/content-editor-page").then((m) => ({
+		default: m.ContentEditorPageComponent,
+	})),
+);
+
+/**
+ * Context passed to loader hooks
+ */
+export interface LoaderContext {
+	path: string;
+	params?: Record<string, string>;
+	isSSR: boolean;
+	apiBaseURL: string;
+	apiBasePath: string;
+	headers?: Headers;
+}
+
+/**
+ * Configuration for CMS client plugin
+ */
+export interface CMSClientConfig {
+	apiBaseURL: string;
+	apiBasePath: string;
+	siteBaseURL: string;
+	siteBasePath: string;
+	queryClient: QueryClient;
+	headers?: Headers;
+}
+
+/**
+ * Create dashboard loader for SSR
+ */
+function createDashboardLoader(config: CMSClientConfig) {
+	return async () => {
+		if (typeof window === "undefined") {
+			const { queryClient, apiBasePath, apiBaseURL, headers } = config;
+			const client = createApiClient<CMSApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCMSQueryKeys(client, headers);
+
+			try {
+				await queryClient.prefetchQuery(queries.cmsTypes.list());
+			} catch {
+				// Let Error Boundaries handle errors during render
+			}
+		}
+	};
+}
+
+/**
+ * Create content list loader for SSR
+ */
+function createContentListLoader(typeSlug: string, config: CMSClientConfig) {
+	return async () => {
+		if (typeof window === "undefined") {
+			const { queryClient, apiBasePath, apiBaseURL, headers } = config;
+			const client = createApiClient<CMSApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCMSQueryKeys(client, headers);
+			const limit = 20;
+
+			try {
+				// Prefetch content types
+				await queryClient.prefetchQuery(queries.cmsTypes.list());
+
+				// Prefetch content list using infinite query (matches useSuspenseInfiniteQuery in hooks)
+				const listQuery = queries.cmsContent.list({
+					typeSlug,
+					limit,
+					offset: 0,
+				});
+				await queryClient.prefetchInfiniteQuery({
+					queryKey: listQuery.queryKey,
+					queryFn: async ({ pageParam = 0 }) => {
+						const response: unknown = await client("/content/:typeSlug", {
+							method: "GET",
+							params: { typeSlug },
+							query: { limit, offset: pageParam },
+							headers,
+						});
+						if (
+							typeof response === "object" &&
+							response !== null &&
+							"error" in response &&
+							response.error
+						) {
+							throw new Error(String(response.error));
+						}
+						return (response as { data?: unknown }).data;
+					},
+					initialPageParam: 0,
+				});
+			} catch {
+				// Let Error Boundaries handle errors during render
+			}
+		}
+	};
+}
+
+/**
+ * Create content editor loader for SSR
+ */
+function createContentEditorLoader(
+	typeSlug: string,
+	id: string | undefined,
+	config: CMSClientConfig,
+) {
+	return async () => {
+		if (typeof window === "undefined") {
+			const { queryClient, apiBasePath, apiBaseURL, headers } = config;
+			const client = createApiClient<CMSApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const queries = createCMSQueryKeys(client, headers);
+
+			try {
+				const promises = [queryClient.prefetchQuery(queries.cmsTypes.list())];
+				if (id) {
+					promises.push(
+						queryClient.prefetchQuery(queries.cmsContent.detail(typeSlug, id)),
+					);
+				}
+				await Promise.all(promises);
+			} catch {
+				// Let Error Boundaries handle errors during render
+			}
+		}
+	};
+}
+
+/**
+ * Create dashboard meta generator
+ */
+function createDashboardMeta() {
+	return () => {
+		const title = "CMS Dashboard";
+		return [
+			{ title },
+			{ name: "title", content: title },
+			{ name: "robots", content: "noindex" },
+		];
+	};
+}
+
+/**
+ * Create content list meta generator
+ */
+function createContentListMeta(typeSlug: string, config: CMSClientConfig) {
+	return () => {
+		const { queryClient, apiBasePath, apiBaseURL } = config;
+		const client = createApiClient<CMSApiRouter>({
+			baseURL: apiBaseURL,
+			basePath: apiBasePath,
+		});
+		const queries = createCMSQueryKeys(client);
+		const contentTypes = queryClient.getQueryData(
+			queries.cmsTypes.list().queryKey,
+		);
+		const contentType = (
+			contentTypes as Array<{ slug: string; name: string }> | undefined
+		)?.find((ct) => ct.slug === typeSlug);
+
+		const title = contentType?.name
+			? `${contentType.name} | CMS`
+			: "Content | CMS";
+
+		return [
+			{ title },
+			{ name: "title", content: title },
+			{ name: "robots", content: "noindex" },
+		];
+	};
+}
+
+/**
+ * Create content editor meta generator
+ */
+function createContentEditorMeta(
+	typeSlug: string,
+	id: string | undefined,
+	config: CMSClientConfig,
+) {
+	return () => {
+		const { queryClient, apiBasePath, apiBaseURL } = config;
+		const client = createApiClient<CMSApiRouter>({
+			baseURL: apiBaseURL,
+			basePath: apiBasePath,
+		});
+		const queries = createCMSQueryKeys(client);
+		const contentTypes = queryClient.getQueryData(
+			queries.cmsTypes.list().queryKey,
+		);
+		const contentType = (
+			contentTypes as Array<{ slug: string; name: string }> | undefined
+		)?.find((ct) => ct.slug === typeSlug);
+
+		const title = id
+			? `Edit ${contentType?.name || "Content"} | CMS`
+			: `New ${contentType?.name || "Content"} | CMS`;
+
+		return [
+			{ title },
+			{ name: "title", content: title },
+			{ name: "robots", content: "noindex" },
+		];
+	};
+}
+
+/**
+ * CMS client plugin
+ * Provides routes and components for the CMS admin interface
+ */
+export const cmsClientPlugin = (config: CMSClientConfig) =>
+	defineClientPlugin({
+		name: "cms",
+
+		routes: () => ({
+			dashboard: createRoute("/cms", () => ({
+				PageComponent: () => <DashboardPageComponent />,
+				loader: createDashboardLoader(config),
+				meta: createDashboardMeta(),
+			})),
+
+			contentList: createRoute("/cms/:typeSlug", ({ params }) => ({
+				PageComponent: () => (
+					<ContentListPageComponent typeSlug={params.typeSlug} />
+				),
+				loader: createContentListLoader(params.typeSlug, config),
+				meta: createContentListMeta(params.typeSlug, config),
+			})),
+
+			newContent: createRoute("/cms/:typeSlug/new", ({ params }) => ({
+				PageComponent: () => (
+					<ContentEditorPageComponent typeSlug={params.typeSlug} />
+				),
+				loader: createContentEditorLoader(params.typeSlug, undefined, config),
+				meta: createContentEditorMeta(params.typeSlug, undefined, config),
+			})),
+
+			editContent: createRoute("/cms/:typeSlug/:id", ({ params }) => ({
+				PageComponent: () => (
+					<ContentEditorPageComponent
+						typeSlug={params.typeSlug}
+						id={params.id}
+					/>
+				),
+				loader: createContentEditorLoader(params.typeSlug, params.id, config),
+				meta: createContentEditorMeta(params.typeSlug, params.id, config),
+			})),
+		}),
+
+		sitemap: async () => {
+			// CMS admin pages should NOT be in sitemap
+			return [];
+		},
+	});

package/src/plugins/cms/client.css

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

package/src/plugins/cms/db.ts

@@ -0,0 +1,76 @@
+import { createDbPlugin } from "@btst/db";
+
+/**
+ * CMS plugin schema
+ * Defines the database tables for content types and content items
+ */
+export const cmsSchema = createDbPlugin("cms", {
+	contentType: {
+		modelName: "contentType",
+		fields: {
+			name: {
+				type: "string",
+				required: true,
+			},
+			slug: {
+				type: "string",
+				required: true,
+				unique: true,
+			},
+			description: {
+				type: "string",
+				required: false,
+			},
+			jsonSchema: {
+				type: "string",
+				required: true,
+			},
+			fieldConfig: {
+				type: "string",
+				required: false,
+			},
+			createdAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+			updatedAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+		},
+	},
+	contentItem: {
+		modelName: "contentItem",
+		fields: {
+			contentTypeId: {
+				type: "string",
+				required: true,
+				references: {
+					model: "contentType",
+					field: "id",
+					onDelete: "cascade",
+				},
+			},
+			slug: {
+				type: "string",
+				required: true,
+			},
+			data: {
+				type: "string",
+				required: true,
+			},
+			authorId: {
+				type: "string",
+				required: false,
+			},
+			createdAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+			updatedAt: {
+				type: "date",
+				defaultValue: () => new Date(),
+			},
+		},
+	},
+});