@btst/stack 2.12.2 → 3.0.0-rc.1

package/src/plugins/ui-builder/client/hooks/ui-builder-resource.ts

@@ -0,0 +1,10 @@
+"use client";
+
+import { createResource } from "@btst/stack/plugins/client/hooks";
+import { uiBuilderResources } from "../../query-keys";
+
+/** Internal generated resource; public hooks remain in ui-builder-hooks.tsx. */
+export const uiBuilder = createResource({
+	plugin: "ui-builder",
+	resources: uiBuilderResources,
+});

package/src/plugins/ui-builder/client/index.ts

@@ -47,17 +47,21 @@ export {
 	useCreateUIBuilderPage,
 	useUpdateUIBuilderPage,
 	useDeleteUIBuilderPage,
+	useUIBuilderPageForm,
 	// Types
 	type UseUIBuilderPagesOptions,
 	type UseUIBuilderPagesResult,
 	type CreateUIBuilderPageInput,
 	type UpdateUIBuilderPageInput,
+	type UIBuilderPageFormValues,
+	type UIBuilderPageUpdateValues,
 } from "./hooks/ui-builder-hooks";
 
 // Localization
 export {
 	uiBuilderLocalization,
 	type UIBuilderLocalization,
+	type UIBuilderLocalizationOverrides,
 } from "./localization";
 
 // Re-export types

package/src/plugins/ui-builder/client/localization/index.ts

@@ -1,7 +1,73 @@
-/**
- * UI Builder plugin localization strings
- */
-export const uiBuilderLocalization = {
+export interface UIBuilderLocalization {
+	pageList: {
+		title: string;
+		description: string;
+		createButton: string;
+		emptyState: { title: string; description: string };
+		columns: {
+			name: string;
+			slug: string;
+			status: string;
+			updatedAt: string;
+			actions: string;
+		};
+		actions: { label: string; edit: string; delete: string };
+		deleteDialog: {
+			title: string;
+			description: string;
+			cancel: string;
+			confirm: string;
+			deleting: string;
+		};
+		pagination: {
+			showing: string;
+			loadMore: string;
+			loading: string;
+		};
+		deleteSuccess: string;
+		deleteError: string;
+	};
+	pageBuilder: {
+		newPage: string;
+		editPage: string;
+		backToList: string;
+		save: string;
+		saving: string;
+		saved: string;
+		saveError: string;
+		duplicateSlug: string;
+		slugLabel: string;
+		slugPlaceholder: string;
+		slugDescription: string;
+		statusLabel: string;
+		settingsTitle: string;
+		settingsDescription: string;
+		statusOptions: {
+			draft: string;
+			published: string;
+			archived: string;
+		};
+		validation: {
+			slugRequired: string;
+			slugFormat: string;
+			layersRequired: string;
+		};
+	};
+	pageRenderer: { loading: string; notFound: string; error: string };
+	common: {
+		errorTitle: string;
+		unexpectedError: string;
+		tryAgain: string;
+	};
+}
+
+type DeepPartial<T> = {
+	[P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+export type UIBuilderLocalizationOverrides = DeepPartial<UIBuilderLocalization>;
+
+export const uiBuilderLocalization: UIBuilderLocalization = {
 	pageList: {
 		title: "UI Builder Pages",
 		description:
@@ -18,17 +84,22 @@ export const uiBuilderLocalization = {
 			updatedAt: "Updated",
 			actions: "Actions",
 		},
-		actions: {
-			edit: "Edit",
-			delete: "Delete",
-		},
+		actions: { label: "Actions", edit: "Edit", delete: "Delete" },
 		deleteDialog: {
 			title: "Delete Page",
 			description:
 				"Are you sure you want to delete this page? This action cannot be undone.",
 			cancel: "Cancel",
 			confirm: "Delete",
+			deleting: "Deleting...",
 		},
+		pagination: {
+			showing: "Showing {count} of {total}",
+			loadMore: "Load More",
+			loading: "Loading...",
+		},
+		deleteSuccess: "Page deleted successfully",
+		deleteError: "Failed to delete page",
 	},
 	pageBuilder: {
 		newPage: "New Page",
@@ -38,10 +109,13 @@ export const uiBuilderLocalization = {
 		saving: "Saving...",
 		saved: "Saved",
 		saveError: "Failed to save",
+		duplicateSlug: "A page with this slug already exists",
 		slugLabel: "Page Slug",
 		slugPlaceholder: "my-page-slug",
 		slugDescription: "URL-friendly identifier for this page",
 		statusLabel: "Status",
+		settingsTitle: "Page Settings",
+		settingsDescription: "Configure page slug and status",
 		statusOptions: {
 			draft: "Draft",
 			published: "Published",
@@ -59,6 +133,9 @@ export const uiBuilderLocalization = {
 		notFound: "Page not found",
 		error: "Failed to load page",
 	},
-} as const;
-
-export type UIBuilderLocalization = typeof uiBuilderLocalization;
+	common: {
+		errorTitle: "Something went wrong",
+		unexpectedError: "An unexpected error occurred",
+		tryAgain: "Try again",
+	},
+};

package/src/plugins/ui-builder/client/overrides.ts

@@ -1,9 +1,9 @@
-import type { ComponentType } from "react";
 import type {
 	ComponentRegistry,
 	FunctionRegistry,
 } from "@workspace/ui/components/ui-builder/types";
 import type { UIBuilderClientHooks } from "../types";
+import type { UIBuilderLocalizationOverrides } from "./localization";
 
 /**
  * Context passed to lifecycle hooks
@@ -22,35 +22,10 @@ export interface RouteContext {
 /**
  * Plugin overrides interface for UI Builder
  *
- * External consumers can provide their own implementations of these
- * to customize the behavior for their framework (Next.js, React Router, etc.)
+ * External consumers can provide their own implementations to customize
+ * plugin-specific components and behavior.
  */
 export interface UIBuilderPluginOverrides {
-	/**
-	 * 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>;
-
-	/**
-	 * API base URL
-	 */
-	apiBaseURL: string;
-
-	/**
-	 * API base path
-	 */
-	apiBasePath: string;
-
 	/**
 	 * Optional headers to pass with API requests (e.g., for SSR auth)
 	 */
@@ -72,6 +47,9 @@ export interface UIBuilderPluginOverrides {
 	 */
 	functionRegistry?: FunctionRegistry;
 
+	/** Localization overrides for built-in UI Builder plugin pages. */
+	localization?: UIBuilderLocalizationOverrides;
+
 	/**
 	 * Base path for UI Builder admin pages (default: /pages/ui-builder)
 	 */

package/src/plugins/ui-builder/client/plugin.tsx

@@ -4,15 +4,13 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
-	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
-import { createRoute } from "@btst/yar";
+import { defineRoute, defineRoutes } from "@btst/yar";
 import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { CMSApiRouter } from "../../cms/api";
-import { createCMSQueryKeys } from "../../cms/query-keys";
 import { createSanitizedSSRLoaderError } from "../../utils";
-import { UI_BUILDER_TYPE_SLUG } from "../schemas";
+import { createUIBuilderQueryKeys } from "../query-keys";
 import type {
 	UIBuilderClientHooks,
 	LoaderContext,
@@ -63,7 +61,7 @@ export interface UIBuilderClientConfig {
 		/** Replaces the new page builder page */
 		newPage?: ComponentType;
 		/** Replaces the edit page builder page */
-		editPage?: ComponentType<{ id: string }>;
+		editPage?: ComponentType<{ params: { id: string } }>;
 	};
 }
 
@@ -74,8 +72,6 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 	return async () => {
 		if (typeof window === "undefined") {
 			const { queryClient, apiBasePath, apiBaseURL, headers, hooks } = config;
-			const typeSlug = UI_BUILDER_TYPE_SLUG;
-
 			const context: LoaderContext = {
 				path: "/ui-builder",
 				isSSR: true,
@@ -87,44 +83,18 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 				baseURL: apiBaseURL,
 				basePath: apiBasePath,
 			});
-			const queries = createCMSQueryKeys(client, headers);
-			const limit = 20;
-			const listQuery = queries.cmsContent.list({
-				typeSlug,
-				limit,
-				offset: 0,
-			});
-			const uiBuilderListQueryKey = [...listQuery.queryKey, "ui-builder"];
+			const queries = createUIBuilderQueryKeys(client, headers);
+			const listQuery = queries.cmsContent.list({ limit: 10, offset: 0 });
 
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadPageList) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadPageList!(context),
-						"Load prevented by beforeLoadPageList hook",
-					);
+					await hooks.beforeLoadPageList(context);
 				}
 
 				// Prefetch pages using infinite query
 				await queryClient.prefetchInfiniteQuery({
-					queryKey: uiBuilderListQueryKey,
-					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;
-					},
+					...listQuery,
 					initialPageParam: 0,
 				});
 
@@ -134,9 +104,7 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 				}
 
 				// Check if there was an error
-				const queryState = queryClient.getQueryState([
-					...uiBuilderListQueryKey,
-				]);
+				const queryState = queryClient.getQueryState(listQuery.queryKey);
 				if (queryState?.error && hooks?.onLoadError) {
 					const error =
 						queryState.error instanceof Error
@@ -149,12 +117,12 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/ui-builder] route.loader() failed — no server running at build time. " +
-							"Use myStack.api.uiBuilder.prefetchForRoute() for SSG data prefetching.",
+							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
 					);
 				} else {
 					const errToStore = createSanitizedSSRLoaderError();
 					await queryClient.prefetchInfiniteQuery({
-						queryKey: uiBuilderListQueryKey,
+						queryKey: listQuery.queryKey,
 						queryFn: () => {
 							throw errToStore;
 						},
@@ -180,8 +148,6 @@ function createPageBuilderLoader(
 	return async () => {
 		if (typeof window === "undefined") {
 			const { queryClient, apiBasePath, apiBaseURL, headers, hooks } = config;
-			const typeSlug = UI_BUILDER_TYPE_SLUG;
-
 			const context: LoaderContext = {
 				path: id ? `/ui-builder/${id}/edit` : "/ui-builder/new",
 				params: id ? { id } : {},
@@ -194,18 +160,13 @@ function createPageBuilderLoader(
 				baseURL: apiBaseURL,
 				basePath: apiBasePath,
 			});
-			const queries = createCMSQueryKeys(client, headers);
-			const pageQuery = id
-				? queries.cmsContent.detail(typeSlug, id)
-				: undefined;
+			const queries = createUIBuilderQueryKeys(client, headers);
+			const pageQuery = id ? queries.cmsContent.detail(id) : undefined;
 
 			try {
 				// Before hook - authorization check
 				if (hooks?.beforeLoadPageBuilder) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadPageBuilder!(id, context),
-						"Load prevented by beforeLoadPageBuilder hook",
-					);
+					await hooks.beforeLoadPageBuilder(id, context);
 				}
 
 				// Prefetch page if editing
@@ -234,7 +195,7 @@ function createPageBuilderLoader(
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/ui-builder] route.loader() failed — no server running at build time. " +
-							"Use myStack.api.uiBuilder.prefetchForRoute() for SSG data prefetching.",
+							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
 					);
 				} else if (pageQuery) {
 					const errToStore = createSanitizedSSRLoaderError();
@@ -277,17 +238,15 @@ function createPageBuilderMeta(
 ) {
 	return () => {
 		const { queryClient, apiBasePath, apiBaseURL, headers } = config;
-		const typeSlug = UI_BUILDER_TYPE_SLUG;
-
 		let pageSlug = "";
 		if (id) {
 			const client = createApiClient<CMSApiRouter>({
 				baseURL: apiBaseURL,
 				basePath: apiBasePath,
 			});
-			const queries = createCMSQueryKeys(client, headers);
+			const queries = createUIBuilderQueryKeys(client, headers);
 			const page = queryClient.getQueryData(
-				queries.cmsContent.detail(typeSlug, id).queryKey,
+				queries.cmsContent.detail(id).queryKey,
 			) as { slug: string } | undefined;
 			pageSlug = page?.slug || "";
 		}
@@ -334,36 +293,30 @@ export const uiBuilderClientPlugin = (config: UIBuilderClientConfig) =>
 	defineClientPlugin({
 		name: "ui-builder",
 
-		routes: () => ({
-			pageList: createRoute("/ui-builder", () => {
-				const CustomPageList = config.pageComponents?.pageList;
-				return {
-					PageComponent: CustomPageList ?? (() => <PageListPageComponent />),
-					loader: createPageListLoader(config),
-					meta: createPageListMeta(),
-				};
-			}),
+		routes: () =>
+			defineRoutes(
+				{
+					pageList: defineRoute("/ui-builder", {
+						page: PageListPageComponent,
+						loader: createPageListLoader(config),
+						meta: createPageListMeta(),
+					}),
 
-			newPage: createRoute("/ui-builder/new", () => {
-				const CustomNewPage = config.pageComponents?.newPage;
-				return {
-					PageComponent: CustomNewPage ?? (() => <PageBuilderPageComponent />),
-					loader: createPageBuilderLoader(undefined, config),
-					meta: createPageBuilderMeta(undefined, config),
-				};
-			}),
+					newPage: defineRoute("/ui-builder/new", {
+						page: () => <PageBuilderPageComponent />,
+						loader: createPageBuilderLoader(undefined, config),
+						meta: createPageBuilderMeta(undefined, config),
+					}),
 
-			editPage: createRoute("/ui-builder/:id/edit", ({ params }) => {
-				const CustomEditPage = config.pageComponents?.editPage;
-				return {
-					PageComponent: CustomEditPage
-						? () => <CustomEditPage id={params.id} />
-						: () => <PageBuilderPageComponent id={params.id} />,
-					loader: createPageBuilderLoader(params.id, config),
-					meta: createPageBuilderMeta(params.id, config),
-				};
-			}),
-		}),
+					editPage: defineRoute("/ui-builder/:id/edit", {
+						page: ({ params }) => <PageBuilderPageComponent id={params.id} />,
+						loader: ({ params }) =>
+							createPageBuilderLoader(params.id, config)(),
+						meta: ({ params }) => createPageBuilderMeta(params.id, config)(),
+					}),
+				},
+				{ pages: config.pageComponents },
+			),
 
 		sitemap: async () => {
 			// UI Builder admin pages should NOT be in sitemap

package/src/plugins/ui-builder/query-keys.ts

@@ -0,0 +1,216 @@
+import {
+	createApiClient,
+	createResourceQueryKeys,
+	type ResourcesDeclaration,
+} from "@btst/stack/plugins/client";
+import type {
+	ComponentLayer,
+	Variable,
+} from "@workspace/ui/components/ui-builder/types";
+import type { CMSApiRouter } from "../cms/api";
+import { contentListDiscriminator } from "../cms/api/query-key-defs";
+import type {
+	PaginatedContentItems,
+	SerializedContentItemWithType,
+} from "../cms/types";
+import { UI_BUILDER_TYPE_SLUG, type UIBuilderPageSchemaType } from "./schemas";
+import type {
+	PaginatedUIBuilderPages,
+	SerializedUIBuilderPage,
+	UIBuilderPageData,
+} from "./types";
+
+export interface UIBuilderPageListParams {
+	/** Number of items per page (default: 10). */
+	limit?: number;
+	/** Included in the cache discriminator; infinite queries start at zero. */
+	offset?: number;
+}
+
+export interface CreateUIBuilderPageInput {
+	slug: string;
+	layers: ComponentLayer[];
+	variables?: Variable[];
+	status?: "published" | "draft" | "archived";
+}
+
+export interface UpdateUIBuilderPageInput {
+	slug?: string;
+	layers?: ComponentLayer[];
+	variables?: Variable[];
+	status?: "published" | "draft" | "archived";
+}
+
+function toUIBuilderPage(
+	item: SerializedContentItemWithType<UIBuilderPageSchemaType>,
+): SerializedUIBuilderPage {
+	return {
+		...item,
+		parsedData: item.parsedData as UIBuilderPageData,
+	};
+}
+
+function toUIBuilderPageList(
+	data: PaginatedContentItems<UIBuilderPageSchemaType>,
+): PaginatedUIBuilderPages {
+	return {
+		...data,
+		items: data.items.map(toUIBuilderPage),
+	};
+}
+
+function paginatedNextPageParam(
+	lastPage: PaginatedUIBuilderPages,
+	allPages: PaginatedUIBuilderPages[],
+	params: UIBuilderPageListParams,
+): number | undefined {
+	const limit = params.limit ?? 10;
+	const items = Array.isArray(lastPage?.items) ? lastPage.items : [];
+	if (items.length < limit) return undefined;
+
+	const loadedCount = allPages.reduce(
+		(sum, page) => sum + (Array.isArray(page?.items) ? page.items.length : 0),
+		0,
+	);
+	if (loadedCount >= (lastPage?.total ?? 0)) return undefined;
+	return loadedCount;
+}
+
+function serializePageData(input: UpdateUIBuilderPageInput) {
+	const data: Partial<UIBuilderPageSchemaType> = {};
+	if (input.layers !== undefined) data.layers = JSON.stringify(input.layers);
+	if (input.variables !== undefined) {
+		data.variables = JSON.stringify(input.variables);
+	}
+	if (input.status !== undefined) data.status = input.status;
+	return data;
+}
+
+/**
+ * UI Builder resource declaration. The `cmsContent` resource name and key
+ * discriminators intentionally match the CMS plugin because UI Builder pages
+ * are CMS content items. This keeps CMS, SSR-loader, and UI Builder caches in
+ * sync without duplicating the CMS hook implementation.
+ */
+export const uiBuilderResources = {
+	cmsContent: {
+		queries: {
+			list: {
+				path: "/content/:typeSlug",
+				params: (_params: UIBuilderPageListParams = {}) => ({
+					typeSlug: UI_BUILDER_TYPE_SLUG,
+				}),
+				query: (params: UIBuilderPageListParams = {}) => ({
+					limit: params.limit ?? 10,
+				}),
+				key: (params: UIBuilderPageListParams = {}) => [
+					contentListDiscriminator({
+						typeSlug: UI_BUILDER_TYPE_SLUG,
+						limit: params.limit ?? 10,
+						offset: params.offset ?? 0,
+					}),
+				],
+				select: (
+					data: PaginatedContentItems<UIBuilderPageSchemaType>,
+				): PaginatedUIBuilderPages => toUIBuilderPageList(data),
+				infinite: true,
+				pageSize: (params: UIBuilderPageListParams = {}) => params.limit ?? 10,
+				nextPageParam: paginatedNextPageParam,
+			},
+
+			detail: {
+				path: "/content/:typeSlug/:id",
+				params: (id: string) => ({ typeSlug: UI_BUILDER_TYPE_SLUG, id }),
+				key: (id: string) => [UI_BUILDER_TYPE_SLUG, id],
+				select: (
+					data: SerializedContentItemWithType<UIBuilderPageSchemaType> | null,
+				): SerializedUIBuilderPage | null =>
+					data ? toUIBuilderPage(data) : null,
+				skip: (id: string) => !id,
+			},
+
+			bySlug: {
+				path: "/content/:typeSlug",
+				params: (_slug: string) => ({ typeSlug: UI_BUILDER_TYPE_SLUG }),
+				query: (slug: string) => ({ slug, limit: 1 }),
+				key: (slug: string) => ["bySlug", UI_BUILDER_TYPE_SLUG, slug],
+				select: (
+					data: PaginatedContentItems<UIBuilderPageSchemaType>,
+				): SerializedUIBuilderPage | null =>
+					data?.items?.[0] ? toUIBuilderPage(data.items[0]) : null,
+				skip: (slug: string) => !slug,
+			},
+		},
+
+		mutations: {
+			create: {
+				path: "@post/content/:typeSlug",
+				method: "POST" as const,
+				input: (input: CreateUIBuilderPageInput) => ({
+					params: { typeSlug: UI_BUILDER_TYPE_SLUG },
+					body: {
+						slug: input.slug,
+						data: {
+							layers: JSON.stringify(input.layers),
+							variables: JSON.stringify(input.variables ?? []),
+							status: input.status ?? "draft",
+						} satisfies UIBuilderPageSchemaType,
+					},
+				}),
+				select: (
+					data: SerializedContentItemWithType<UIBuilderPageSchemaType>,
+				) => toUIBuilderPage(data),
+				invalidates: ["cmsContent.list", "cmsTypes.list"],
+				refetchType: "all" as const,
+				setData: {
+					query: "detail",
+					args: (created: SerializedUIBuilderPage) => [created.id],
+				},
+			},
+
+			update: {
+				path: "@put/content/:typeSlug/:id",
+				method: "PUT" as const,
+				input: (vars: { id: string; data: UpdateUIBuilderPageInput }) => {
+					const data = serializePageData(vars.data);
+					return {
+						params: { typeSlug: UI_BUILDER_TYPE_SLUG, id: vars.id },
+						body: {
+							...(vars.data.slug !== undefined ? { slug: vars.data.slug } : {}),
+							...(Object.keys(data).length > 0 ? { data } : {}),
+						},
+					};
+				},
+				select: (
+					data: SerializedContentItemWithType<UIBuilderPageSchemaType>,
+				) => toUIBuilderPage(data),
+				invalidates: ["cmsContent.list"],
+				refetchType: "all" as const,
+				setData: {
+					query: "detail",
+					args: (updated: SerializedUIBuilderPage) => [updated.id],
+				},
+			},
+
+			delete: {
+				path: "@delete/content/:typeSlug/:id",
+				method: "DELETE" as const,
+				input: (id: string) => ({
+					params: { typeSlug: UI_BUILDER_TYPE_SLUG, id },
+				}),
+				select: (data: { success: boolean }) => data,
+				invalidates: ["cmsContent", "cmsTypes.list"],
+				refetchType: "all" as const,
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+
+export function createUIBuilderQueryKeys(
+	client: ReturnType<typeof createApiClient<CMSApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createResourceQueryKeys(client, uiBuilderResources, headers);
+}
+
+export type UIBuilderQueryKeys = ReturnType<typeof createUIBuilderQueryKeys>;