UI Builder Plugin

import { createBackendStack } from "@btst/stack/api"
import { createServerAuth } from "@btst/stack/authorization/server"
import { cmsBackendPlugin } from "@btst/stack/plugins/cms/api"
import {
  UI_BUILDER_CONTENT_TYPE,
  UI_BUILDER_TYPE_SLUG,
} from "@btst/stack/plugins/ui-builder"
import { authorization } from "./authorization"

const auth = createServerAuth({
  authorization,
  getIdentity: async ({ request }) => {
    const session = await getSession(request.headers)
    return session?.user ?? null
  },
})

const { handler, dbSchema } = createBackendStack({
  basePath: "/api/data",
  plugins: {
    cms: cmsBackendPlugin({
      contentTypes: [
        UI_BUILDER_CONTENT_TYPE,
        // ... other content types
      ],
    })
  },
  adapter: (db) => createMemoryAdapter(db)({}),
  auth,
})

export { handler, dbSchema }

import { createClientStack } from "@btst/stack/client"
import { cmsClientPlugin } from "@btst/stack/plugins/cms/client"
import { uiBuilderClientPlugin } from "@btst/stack/plugins/ui-builder/client"
import { QueryClient } from "@tanstack/react-query"

function getBaseURL(serverOrigin?: string) {
  if (typeof window !== "undefined") return window.location.origin
  return (
    serverOrigin ||
    process.env.BTST_SITE_URL ||
    process.env.BASE_URL ||
    "http://localhost:3000"
  )
}

export const getStackClient = (
  queryClient: QueryClient,
  options?: { headers?: Headers; origin?: string },
) => {
  const baseURL = getBaseURL(options?.origin)
  return createClientStack({
    api: {
      baseURL,
      basePath: "/api/data",
      ...(options?.headers ? { headers: options.headers } : {}),
    },
    site: { baseURL, basePath: "/pages" },
    queryClient,
    plugins: {
      // CMS plugin is required
      cms: cmsClientPlugin(),
      // Programmatic ID is camelCase; the package and route slug stay ui-builder.
      uiBuilder: uiBuilderClientPlugin()
    }
  })
}

import { nextRouter } from "@btst/stack/next"

const stack = getStackClient(queryClient, clientOrigins)

<StackProvider
  stack={stack}
  router={nextRouter()}
>
  {children}
</StackProvider>

npm install @tailwindcss/typography
# or
pnpm add @tailwindcss/typography

@import "@btst/stack/plugins/ui-builder/css";

uiBuilderClientPlugin({
  // ... other config
  pageComponents: {
    // Replace the page list page
    pageList: MyCustomPageList,
    // Replace the new page builder page
    newPage: MyCustomNewPage,
    // Replace the edit page builder page — receives the route context as props
    editPage: ({ params }) => <MyCustomPageBuilder id={params.id} />,
  },
})

import { 
  createComponentRegistry, 
  defaultComponentRegistry,
  uiBuilderClientPlugin,
} from "@btst/stack/plugins/ui-builder/client"
import { z } from "zod"

// Extend the default registry
const customRegistry = createComponentRegistry({
  ...defaultComponentRegistry,
  
  // Add a custom component
  HeroSection: {
    component: HeroSection,
    schema: z.object({
      title: z.string().default("Welcome"),
      subtitle: z.string().optional(),
      backgroundImage: z.string().optional(),
      ctaText: z.string().default("Get Started"),
      ctaLink: z.string().default("#"),
    }),
    from: "@/components/hero-section",
  },
  
  // Add a pricing card
  PricingCard: {
    component: PricingCard,
    schema: z.object({
      plan: z.string(),
      price: z.string(),
      features: z.array(z.string()).default([]),
      highlighted: z.boolean().default(false),
    }),
    from: "@/components/pricing-card",
  },
})

// Register once; the editor and PageRenderer consume the same registry.
const uiBuilder = uiBuilderClientPlugin({ components: customRegistry })

const registry = createComponentRegistry({
  ...defaultComponentRegistry,
  
  // TabsTrigger can only be added inside TabsList
  TabsTrigger: {
    component: TabsTrigger,
    schema: z.object({
      value: z.string(),
      children: z.any(),
    }),
    childOf: ["TabsList"], // Can only be a child of TabsList
  },
  
  // CarouselItem can only be inside Carousel
  CarouselItem: {
    component: CarouselItem,
    schema: z.object({
      children: z.any(),
    }),
    childOf: ["Carousel"],
  },
})

const minimalRegistry = createComponentRegistry({
  div: primitiveComponentDefinitions.div,
  span: primitiveComponentDefinitions.span,
  Flexbox: complexComponentDefinitions.Flexbox,
  Button: complexComponentDefinitions.Button,
})

import type { BlockRegistry, ComponentLayer } from "@btst/stack/components/ui-builder"

const myBlocks: BlockRegistry = {
  "hero-01": {
    name: "hero-01",
    category: "hero",
    description: "Hero section with title, subtitle, and CTA button",
    thumbnail: "/blocks/hero-01.png", // Optional preview image
    template: {
      id: "hero-root",
      type: "Flexbox",
      name: "Hero Section",
      props: {
        className: "min-h-[60vh] items-center justify-center bg-gradient-to-b from-primary/10 to-background",
        direction: "column",
        gap: 4,
      },
      children: [
        {
          id: "hero-title",
          type: "h1",
          name: "Title",
          props: { className: "text-5xl font-bold text-center" },
          children: "Welcome to Our Platform",
        },
        {
          id: "hero-subtitle",
          type: "p",
          name: "Subtitle",
          props: { className: "text-xl text-muted-foreground text-center max-w-2xl" },
          children: "Build amazing experiences with our powerful tools",
        },
        {
          id: "hero-cta",
          type: "Button",
          name: "CTA Button",
          props: { variant: "default", size: "lg" },
          children: [
            { id: "cta-text", type: "span", name: "Button Text", props: {}, children: "Get Started" }
          ],
        },
      ],
    },
  },
  "pricing-01": {
    name: "pricing-01",
    category: "pricing",
    description: "Simple pricing card",
    template: {
      id: "pricing-root",
      type: "Card",
      name: "Pricing Card",
      props: { className: "w-full max-w-sm" },
      children: [
        {
          id: "pricing-header",
          type: "CardHeader",
          name: "Header",
          props: {},
          children: [
            { id: "plan-name", type: "CardTitle", name: "Plan", props: {}, children: [
              { id: "plan-text", type: "span", name: "Plan Text", props: {}, children: "Pro" }
            ]},
            { id: "plan-desc", type: "CardDescription", name: "Description", props: {}, children: [
              { id: "desc-text", type: "span", name: "Description Text", props: {}, children: "For professionals" }
            ]},
          ],
        },
        {
          id: "pricing-content",
          type: "CardContent",
          name: "Content",
          props: {},
          children: [
            { id: "price", type: "p", name: "Price", props: { className: "text-4xl font-bold" }, children: "$29/mo" },
          ],
        },
      ],
    },
  },
}

import { UIBuilder, defaultComponentRegistry } from "@btst/stack/components/ui-builder"

function PageEditor() {
  return (
    <UIBuilder
      componentRegistry={defaultComponentRegistry}
      blocks={myBlocks}
      initialLayers={[]}
      onChange={(layers) => console.log("Layers changed:", layers)}
    />
  )
}

"use client"

import { PageRenderer } from "@btst/stack/plugins/ui-builder/client"

export default function PreviewPage({ params }: { params: { slug: string } }) {
  return (
    <PageRenderer
      slug={params.slug}
      className="min-h-screen"
    />
  )
}

"use client"

import { LayerRenderer, defaultComponentRegistry } from "@btst/stack/components/ui-builder"

export default function DynamicPage({ page, variables }: { 
  page: ComponentLayer, 
  variables: Variable[] 
}) {
  return (
    <LayerRenderer
      page={page}
      componentRegistry={defaultComponentRegistry}
      variables={variables}
      variableValues={{
        userName: "John Doe",
      }}
      className="min-h-screen"
    />
  )
}

// No "use client" needed - this is a Server Component
import { ServerLayerRenderer, defaultComponentRegistry } from "@btst/stack/components/ui-builder"

export default async function StaticPage({ params }: { params: { slug: string } }) {
  // Fetch page data on the server
  const page = await fetchPageFromDatabase(params.slug)
  
  if (!page) {
    return <NotFound />
  }
  
  const layers = JSON.parse(page.parsedData.layers)
  const variables = JSON.parse(page.parsedData.variables)
  
  return (
    <ServerLayerRenderer
      page={layers[0]}
      componentRegistry={defaultComponentRegistry}
      variables={variables}
      variableValues={{
        // Pass any runtime values
        currentYear: new Date().getFullYear(),
      }}
      className="min-h-screen"
    />
  )
}

import { PageRenderer } from "@btst/stack/plugins/ui-builder/client"

export default function UserPage({ params }: { params: { slug: string } }) {
  const user = useCurrentUser()
  
  return (
    <PageRenderer
      slug={params.slug}
      variableValues={{
        userName: user?.name ?? "Guest",
        userEmail: user?.email,
        isLoggedIn: !!user,
      }}
    />
  )
}

import { Suspense } from "react"
import { SuspensePageRenderer } from "@btst/stack/plugins/ui-builder/client"

export default function Page({ params }: { params: { slug: string } }) {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <SuspensePageRenderer slug={params.slug} />
    </Suspense>
  )
}

## Client Hooks

Access UI Builder data with React Query hooks:

### Available Hooks

| Hook | Description | Returns |
|------|-------------|---------|
| `useUIBuilderPages()` | List all pages | `{ pages, total, isLoading, loadMore, hasMore }` |
| `useSuspenseUIBuilderPages()` | Suspense variant | `{ pages, total, loadMore, hasMore }` |
| `useUIBuilderPage(id)` | Get page by ID | `{ page, isLoading, error }` |
| `useUIBuilderPageBySlug(slug)` | Get page by slug | `{ page, layers, variables, isLoading }` |
| `useCreateUIBuilderPage()` | Create mutation | React Query mutation |
| `useUpdateUIBuilderPage()` | Update mutation | React Query mutation |
| `useDeleteUIBuilderPage()` | Delete mutation | React Query mutation |
| `useUIBuilderPageForm(config)` | Create/edit lifecycle | `{ submit, isSubmitting, fieldErrors, error }` |

`useUIBuilderPageForm` uses the shared resource-form lifecycle: it selects the
create or update mutation, awaits cache invalidation, sends messages through the
`notify` provider, redirects through the router adapter, and exposes structured
server validation errors through `fieldErrors`.

For SSR loaders or custom cache prefetching, import
`createUIBuilderQueryKeys` from
`@btst/stack/plugins/ui-builder/query-keys`. Its keys intentionally match the
underlying CMS content-item keys.

### Usage Examples

```tsx
import { 
  useUIBuilderPageBySlug,
  useCreateUIBuilderPage,
  useUIBuilderPages 
} from "@btst/stack/plugins/ui-builder/client"

// Public: Fetch page by slug
function DynamicPage({ slug }: { slug: string }) {
  const { page, layers, variables, isLoading } = useUIBuilderPageBySlug(slug)
  
  if (isLoading || !page) return <Loading />
  
  return (
    <LayerRenderer
      page={layers[0]}
      componentRegistry={defaultComponentRegistry}
      variables={variables}
    />
  )
}

// Admin: Create new page
function CreatePage() {
  const createPage = useCreateUIBuilderPage()
  
  const handleCreate = async () => {
    await createPage.mutateAsync({
      slug: "my-new-page",
      layers: [
        {
          id: "root",
          type: "div",
          name: "Page Root",
          props: { className: "min-h-screen p-8" },
          children: [],
        }
      ],
      status: "draft",
    })
  }
  
  return <Button onClick={handleCreate}>Create Page</Button>
}

import { z } from "zod"
import { defineAuthorization } from "@btst/stack/authorization"
import { cmsPermissions } from "@btst/stack/plugins/cms/permissions"
import { UI_BUILDER_TYPE_SLUG } from "@btst/stack/plugins/ui-builder"

export const authorization = defineAuthorization({
  identity: z.object({ id: z.string(), role: z.enum(["editor", "admin"]) }),
  permissions: [cmsPermissions] as const,
  rules: ({ cms }) => [
    // Public page reads are explicit. Other CMS types can use a stricter rule.
    cms.contentType.read.when(
      ({ identity, facts }) =>
        facts.contentType === UI_BUILDER_TYPE_SLUG || identity?.role === "admin",
    ),
    cms.record.read.when(
      ({ identity, facts }) =>
        (facts.contentType === UI_BUILDER_TYPE_SLUG && facts.scope === "record") ||
        identity?.role === "admin",
    ),
    cms.record.create.when(({ identity }) => identity?.role === "admin"),
    cms.record.update.when(
      ({ identity, facts }) =>
        identity?.role === "admin" || identity?.id === facts.authorId,
    ),
    cms.record.delete.when(({ identity }) => identity?.role === "admin"),
  ],
})

uiBuilder: uiBuilderClientPlugin({
  hooks: {
    beforeLoadPageList: async (context) => {
      await warmPageListDependencies(context.headers)
    },
    beforeLoadPageBuilder: async (pageId, context) => {
      await recordPageBuilderLoad(pageId, context.headers)
    },
    afterLoadPageList: async (context) => {
      console.log("Page list loaded")
    },
    afterLoadPageBuilder: async (pageId, context) => {
      console.log("Page builder loaded for:", pageId)
    },
    onErrorLoad: (error, context) => {
      reportPageLoaderError(error, context)
    },
  },
})

<StackProvider
  stack={stack}
  router={nextRouter()}
  auth={createClientAuth({
    authorization,
    getIdentity: () => getBrowserSession()?.user ?? null,
  })}
  initialIdentity={initialIdentity}
  // optional plugin-specific overrides
>
  {children}
</StackProvider>

interface UIBuilderPage {
  id: string
  slug: string              // URL-friendly identifier
  parsedData: {
    layers: string          // JSON-serialized ComponentLayer[]
    variables: string       // JSON-serialized Variable[]
    status: "published" | "draft" | "archived"
  }
  createdAt: string
  updatedAt: string
}

interface ComponentLayer {
  id: string
  type: string              // Component type from registry
  name?: string             // Display name in layers panel
  props: Record<string, any>
  children: ComponentLayer[] | string | VariableReference
}

interface Variable {
  id: string
  name: string
  type: "string" | "number" | "boolean" | "function"
  defaultValue: any
}

// Variable reference for dynamic content
interface VariableReference {
  __variableRef: string     // Variable ID
}

const layer: ComponentLayer = {
  id: "greeting",
  type: "h1",
  name: "Greeting",
  props: { className: "text-2xl font-bold" },
  // Children bound to a variable
  children: { __variableRef: "userName" }
}

const variables: Variable[] = [
  { id: "userName", name: "User Name", type: "string", defaultValue: "Guest" }
]

<PageRenderer
  slug="welcome"
  variableValues={{ userName: "John Doe" }}
/>

import { UI_BUILDER_CONTENT_TYPE } from "@btst/stack/plugins/ui-builder"

cms: cmsBackendPlugin({
  contentTypes: [UI_BUILDER_CONTENT_TYPE]
})

const registry = createComponentRegistry({
  ...defaultComponentRegistry,
  CustomComponent: { component: CustomComponent, schema: customSchema },
})

import { UIBuilder } from "@btst/stack/components/ui-builder"

<UIBuilder
  componentRegistry={myRegistry}
  blocks={myBlocks}
  functionRegistry={myFunctionRegistry}
  initialLayers={initialLayers}
  initialVariables={initialVariables}
  onChange={(layers) => saveLayers(layers)}
  onVariablesChange={(variables) => saveVariables(variables)}
  allowPagesCreation={true}
  allowPagesDeletion={true}
  allowVariableEditing={true}
  persistLayerStore={false}
  showExport={true}
  navLeftChildren={<Logo />}
  navRightChildren={<SaveButton />}
/>

<PageRenderer
  slug="homepage"
  componentRegistry={customRegistry}
  variableValues={{ userName: "John" }}
/>

import { LayerRenderer } from "@btst/stack/components/ui-builder"

<LayerRenderer
  page={rootLayer}
  componentRegistry={customRegistry}
  variables={variables}
  variableValues={{ userName: "John" }}
/>

import { ServerLayerRenderer } from "@btst/stack/components/ui-builder"

// In a Server Component (no "use client" needed)
<ServerLayerRenderer
  page={rootLayer}
  componentRegistry={customRegistry}
  variables={variables}
  variableValues={{ currentYear: 2024 }}
/>

interface BlockDefinition {
  name: string           // Unique block name, e.g., "login-01"
  category: string       // Block category, e.g., "login", "sidebar"
  description?: string   // Human-readable description
  template: ComponentLayer  // ComponentLayer tree to insert
  thumbnail?: string     // Optional preview image URL
  requiredComponents?: string[]  // Required shadcn components
}

type BlockRegistry = Record<string, BlockDefinition>

interface FunctionDefinition {
  name: string                // Human-readable name
  schema: ZodTuple | ZodObject | ZodSchema  // Parameter schema
  fn: (...args: any[]) => any // The actual function
  description?: string        // Description shown in UI
  typeSignature?: string      // TS type signature for code generation
}

type FunctionRegistry = Record<string, FunctionDefinition>

import { z } from "zod"

const functionRegistry: FunctionRegistry = {
  handleSubmit: {
    name: "Handle Submit",
    description: "Process form submission",
    schema: z.tuple([z.custom<React.FormEvent<HTMLFormElement>>()]),
    fn: (e) => { e.preventDefault(); console.log("submitted") },
    typeSignature: "(e: React.FormEvent<HTMLFormElement>) => void",
  },
}

<UIBuilder
  componentRegistry={myRegistry}
  functionRegistry={functionRegistry}
  // ...
/>

interface ComponentLayer {
  id: string
  type: string                          // Component type from registry
  name?: string                         // Display name in layers panel
  props: Record<string, PropValue>
  children: ComponentLayer[] | string | VariableReference
}

interface Variable {
  id: string
  name: string
  type: "string" | "number" | "boolean" | "function"
  defaultValue: any
}

interface VariableReference {
  __variableRef: string  // Variable ID
}

import { uiBuilderClientPlugin } from "@btst/stack/plugins/ui-builder/client"
// Import your ejected (and customized) page components
import { PageListPage } from "@/components/btst/ui-builder/client/components/pages/page-list-page"
import { PageBuilderPage } from "@/components/btst/ui-builder/client/components/pages/page-builder-page"

uiBuilderClientPlugin({
  pageComponents: {
    pageList: PageListPage, // replaces the page list page
    // Param routes receive the route context ({ params }) as props
    editPage: ({ params }) => <PageBuilderPage id={params.id} />,
    // newPage — omit to keep built-in default
  },
})