UI Builder Plugin

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

const { handler, dbSchema } = stack({
  basePath: "/api/data",
  plugins: {
    cms: cmsBackendPlugin({
      contentTypes: [
        UI_BUILDER_CONTENT_TYPE,
        // ... other content types
      ],
      hooks: {
        // Optional: Add authorization for CMS operations
        onBeforeListContent: async (typeSlug, ctx) => {
          if (typeSlug === "ui-builder-page") {
            const session = await getSession(ctx.headers)
            return session?.user?.isAdmin === true
          }
          return true
        },
      },
    })
  },
  adapter: (db) => createMemoryAdapter(db)({})
})

export { handler, dbSchema }

import { createStackClient } from "@btst/stack/client"
import { cmsClientPlugin } from "@btst/stack/plugins/cms/client"
import { uiBuilderClientPlugin, defaultComponentRegistry } from "@btst/stack/plugins/ui-builder/client"
import { QueryClient } from "@tanstack/react-query"
import { redirect } from "next/navigation"

const getBaseURL = () => 
  process.env.BASE_URL || "http://localhost:3000"

export const getStackClient = (queryClient: QueryClient, options?: { headers?: Headers }) => {
  const baseURL = getBaseURL()
  return createStackClient({
    plugins: {
      // CMS plugin is required
      "cms": cmsClientPlugin({
        apiBaseURL: baseURL,
        apiBasePath: "/api/data",
        siteBaseURL: baseURL,
        siteBasePath: "/pages",
        queryClient,
        headers: options?.headers,
      }),
      // UI Builder plugin
      "ui-builder": uiBuilderClientPlugin({
        apiBaseURL: baseURL,
        apiBasePath: "/api/data",
        siteBaseURL: baseURL,
        siteBasePath: "/pages",
        queryClient,
        componentRegistry: defaultComponentRegistry,
        headers: options?.headers,
        hooks: {
          // SSR authorization hooks
          beforeLoadPageList: async (context) => {
            const session = await getSession(context.headers)
            return session?.user?.isAdmin === true
          },
          beforeLoadPageBuilder: async (pageId, context) => {
            const session = await getSession(context.headers)
            return session?.user?.isAdmin === true
          },
          onLoadError: (error, context) => {
            redirect("/auth/sign-in")
          },
        },
      })
    }
  })
}

import type { UIBuilderPluginOverrides } from "@btst/stack/plugins/ui-builder/client"
import type { CMSPluginOverrides } from "@btst/stack/plugins/cms/client"

type PluginOverrides = {
  "cms": CMSPluginOverrides,
  "ui-builder": UIBuilderPluginOverrides,
}

<StackProvider<PluginOverrides>
  basePath="/pages"
  overrides={{
    "cms": {
      apiBaseURL: baseURL,
      apiBasePath: "/api/data",
      navigate: (path) => router.push(path),
      refresh: () => router.refresh(),
      Link: ({ href, ...props }) => <Link href={href || "#"} {...props} />,
    },
    "ui-builder": {
      apiBaseURL: baseURL,
      apiBasePath: "/api/data",
      navigate: (path) => router.push(path),
      refresh: () => router.refresh(),
      Link: ({ href, ...props }) => <Link href={href || "#"} {...props} />,
      componentRegistry: defaultComponentRegistry,
    }
  }}
>
  {children}
</StackProvider>

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

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

import { 
  createComponentRegistry, 
  defaultComponentRegistry,
  primitiveComponentDefinitions,
} 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",
  },
})

// Use in client plugin
uiBuilderClientPlugin({
  // ...
  componentRegistry: 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 "@workspace/ui/components/ui-builder/types"

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 from "@workspace/ui/components/ui-builder"
import { defaultComponentRegistry } from "@btst/stack/plugins/ui-builder/client"

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 } from "@workspace/ui/components/ui-builder"
import { defaultComponentRegistry } from "@btst/stack/plugins/ui-builder/client"

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 } from "@workspace/ui/components/ui-builder"
import { defaultComponentRegistry } from "@btst/stack/plugins/ui-builder/client"

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 |

### 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 { redirect } from "next/navigation"

"ui-builder": uiBuilderClientPlugin({
  // ... config
  hooks: {
    beforeLoadPageList: async (context) => {
      // context.headers contains request headers
      const session = await getSession(context.headers)
      return session?.user?.isAdmin === true
    },
    beforeLoadPageBuilder: async (pageId, context) => {
      // pageId is undefined for new pages
      const session = await getSession(context.headers)
      return session?.user?.isAdmin === true
    },
    afterLoadPageList: async (context) => {
      console.log("Page list loaded")
    },
    afterLoadPageBuilder: async (pageId, context) => {
      console.log("Page builder loaded for:", pageId)
    },
    onLoadError: (error, context) => {
      // Redirect on authorization failure
      redirect("/auth/sign-in")
    },
  },
})

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 "@workspace/ui/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 "@workspace/ui/components/ui-builder"

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

import { ServerLayerRenderer } from "@workspace/ui/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
}