create-vexcms 0.0.20 → 0.1.0-alpha.2

package/templates/marketing-site/src/app/(frontend)/PageContent.tsx

@@ -1,186 +1,53 @@
 "use client"
 
-import { RenderBlocks } from "@vexcms/ui"
 import { convexQuery } from "@convex-dev/react-query"
 import { useQuery } from "@tanstack/react-query"
-import { useMutation, useQuery as useConvexQuery } from "convex/react"
-import Link from "next/link"
-import { usePathname, useRouter } from "next/navigation"
-import { useEffect, useState } from "react"
 import { anyApi } from "convex/server"
 
-import { api } from "@convex/_generated/api"
-import { useSession } from "~/auth/client"
-import { normalizeSlug } from "~/lib/utils"
+import { RenderBlocks, type RenderableBlock } from "@vexcms/react"
+
+import { WelcomePage } from "~/components/WelcomePage"
 import { blockComponents } from "~/vexcms/blocks"
 
+type PageBlockLike = RenderableBlock
+
+export interface PageContentProps {
+  /** URL slug to render. Omit (or empty) for the home page. */
+  slug?: string
+  /** Server-fetched `pages.getBySlug` result, hydrated as the query's initial data. */
+  initialData?: Record<string, unknown>[]
+}
+
 /**
- * Client component that renders a page using TanStack Query + convexQuery.
- * When initialData is provided (from server fetchQuery), renders immediately.
- * The reactive subscription keeps data up-to-date after hydration.
+ * Renders one marketing page's blocks via `RenderBlocks` (Contract 1), or
+ * falls back to base's bootstrap `WelcomePage` when no `home` page document
+ * exists yet — a fresh scaffold before `pnpm seed` has run (Contract 3).
  *
- * On a fresh project with no "home" page, shows the bootstrap/auth flow
- * so the first user can sign up and become admin.
+ * `pages.getBySlug` always returns an array (empty when no match — the same
+ * shape every collection query returns), so this always reads `pages?.[0]`.
  */
-export function PageContent({
-  slug,
-  initialData,
-}: {
-  slug?: string
-  initialData?: Record<string, unknown> | null
-}) {
-  const normalizedSlug = normalizeSlug(slug)
+export function PageContent({ slug, initialData }: PageContentProps) {
+  const normalizedSlug = slug && slug.length > 0 ? slug : "home"
 
-  const { data: page, isPending } = useQuery({
-    ...convexQuery(anyApi.pages.getBySlug, {
-      slug: normalizedSlug,
-      _vexDrafts: false,
-    }),
-    initialData: initialData ?? undefined,
+  const { data: pages, isPending } = useQuery({
+    ...convexQuery(anyApi.pages.getBySlug, { slug: normalizedSlug }),
+    initialData,
   })
 
+  const page = pages?.[0]
+
   if (isPending && initialData === undefined) {
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <p className="text-muted-foreground">Loading...</p>
-      </div>
-    )
+    return null
   }
 
   if (!page) {
-    if (normalizedSlug === "home") {
-      return <WelcomePage />
-    }
-
-    return (
-      <div className="mx-auto max-w-3xl px-4 py-12">
-        <h1 className="text-2xl font-bold">Page not found</h1>
-        <p className="mt-2 text-muted-foreground">
-          The page &ldquo;{slug}&rdquo; doesn&apos;t exist or hasn&apos;t been
-          published yet.
-        </p>
-        <Link
-          className="mt-4 inline-block text-sm text-primary hover:underline"
-          href="/"
-        >
-          &larr; Back to home
-        </Link>
-      </div>
-    )
+    return <WelcomePage />
   }
 
   return (
     <RenderBlocks
-      blocks={page.content as any}
+      blocks={page.blocks as PageBlockLike[] | null | undefined}
       components={blockComponents}
     />
   )
 }
-
-function LoadingSpinner() {
-  return (
-    <svg className="animate-spin h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
-      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
-      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
-    </svg>
-  )
-}
-
-/**
- * Welcome page shown on fresh projects with no "home" page.
- * Handles the first-user bootstrap flow: sign up → promote to admin → redirect to admin panel.
- */
-function WelcomePage() {
-  const isBootstrapped = useConvexQuery(api.vex.firstUser.isBootstrapped)
-  const promoteFirstAdmin = useMutation(api.vex.firstUser.promoteFirstAdmin)
-  const { data: session } = useSession()
-  const router = useRouter()
-  const pathname = usePathname()
-  const [promoting, setPromoting] = useState(false)
-  const [navigating, setNavigating] = useState(false)
-
-  useEffect(() => {
-    if (pathname === "/") {
-      setNavigating(false)
-    }
-  }, [pathname])
-
-  useEffect(() => {
-    if (session?.user && isBootstrapped === false && !promoting) {
-      setPromoting(true)
-      setNavigating(true)
-      promoteFirstAdmin()
-        .then((result) => {
-          if (result.promoted) {
-            router.push("/admin")
-          } else {
-            setNavigating(false)
-          }
-        })
-        .catch(() => {
-          setPromoting(false)
-          setNavigating(false)
-        })
-    }
-  }, [session, isBootstrapped, promoting, promoteFirstAdmin, router])
-
-  const bootstrapped = isBootstrapped === true
-
-  const buttonClass =
-    "inline-flex items-center justify-center gap-2 rounded-md bg-primary px-6 py-3 text-sm font-medium text-primary-foreground shadow hover:bg-primary/90 disabled:opacity-50 disabled:cursor-not-allowed transition-opacity"
-
-  const handleNavigate = (path: string) => {
-    setNavigating(true)
-    router.push(path)
-  }
-
-  return (
-    <div className="flex min-h-screen flex-col items-center justify-center gap-8 p-8">
-      <div className="text-center">
-        <h1 className="text-4xl font-bold tracking-tight">VEX CMS</h1>
-        <p className="mt-3 text-lg text-muted-foreground">
-          {bootstrapped
-            ? "Your content management system is ready."
-            : "Welcome! Create your admin account to get started."}
-        </p>
-      </div>
-
-      <div className="flex gap-4">
-        {session?.user ? (
-          <button
-            onClick={() => handleNavigate("/admin")}
-            disabled={navigating}
-            className={buttonClass}
-          >
-            {navigating && <LoadingSpinner />}
-            {navigating ? "Loading..." : "Go to Admin Panel"}
-          </button>
-        ) : bootstrapped ? (
-          <button
-            onClick={() => handleNavigate("/auth/sign-in")}
-            disabled={navigating}
-            className={buttonClass}
-          >
-            {navigating && <LoadingSpinner />}
-            {navigating ? "Loading..." : "Sign In"}
-          </button>
-        ) : (
-          <button
-            onClick={() => handleNavigate("/auth/sign-up")}
-            disabled={navigating}
-            className={buttonClass}
-          >
-            {navigating && <LoadingSpinner />}
-            {navigating ? "Loading..." : "Create Admin Account"}
-          </button>
-        )}
-      </div>
-
-      {promoting && (
-        <p className="text-sm text-muted-foreground animate-pulse">
-          Setting up your admin account...
-        </p>
-      )}
-    </div>
-  )
-}

package/templates/marketing-site/src/app/(frontend)/[slug]/page.tsx

@@ -1,25 +1,22 @@
-import { api } from "@convex/_generated/api"
 import { fetchQuery } from "convex/nextjs"
 
+import { api } from "@convex/_generated/api"
+
 import { generatePageMetadata } from "~/lib/metadata"
-import { normalizeSlug } from "~/lib/utils"
 import { PageContent } from "../PageContent"
 
 export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
   const { slug } = await params
-  return generatePageMetadata({ slug: normalizeSlug(slug) })
+  return generatePageMetadata({ slug: slug && slug.length > 0 ? slug : "home" })
 }
 
 export default async function PublicPage({ params }: { params: Promise<{ slug: string }> }) {
   const { slug } = await params
-  const normalized = normalizeSlug(slug)
+  const normalized = slug && slug.length > 0 ? slug : "home"
 
-  let initialData: null | Record<string, unknown> = null
+  let initialData: Record<string, unknown>[] | undefined
   try {
-    initialData = await fetchQuery(api.pages.getBySlug, {
-      slug: normalized,
-      _vexDrafts: false,
-    })
+    initialData = await fetchQuery(api.pages.getBySlug, { slug: normalized })
   } catch {
     // Fall back to client-only fetch
   }

package/templates/marketing-site/src/app/(frontend)/layout.tsx

@@ -1,3 +1,5 @@
+import type { ReactNode } from "react"
+
 import { fetchQuery } from "convex/nextjs"
 
 import { api } from "@convex/_generated/api"
@@ -10,8 +12,8 @@ export default async function FrontendLayout({
   auth,
   children,
 }: Readonly<{
-  auth: React.ReactNode
-  children: React.ReactNode
+  auth: ReactNode
+  children: ReactNode
 }>) {
   let headerData: Record<string, unknown> | null = null
   let footerData: Record<string, unknown> | null = null

package/templates/marketing-site/src/app/(frontend)/page.tsx

@@ -10,12 +10,9 @@ export async function generateMetadata() {
 }
 
 export default async function HomePage() {
-  let initialData: Record<string, unknown> | null = null
+  let initialData: Record<string, unknown>[] | undefined
   try {
-    initialData = await fetchQuery(api.pages.getBySlug, {
-      slug: "home",
-      _vexDrafts: false,
-    })
+    initialData = await fetchQuery(api.pages.getBySlug, { slug: "home" })
   } catch {
     // Fall back to client-only fetch
   }

package/templates/marketing-site/src/components/SiteFooter.tsx

@@ -1,12 +1,14 @@
 "use client"
 
-import { RenderBlocks } from "@vexcms/ui"
+import { RenderBlocks, type RenderableBlock } from "@vexcms/react"
 import { convexQuery } from "@convex-dev/react-query"
 import { useQuery } from "@tanstack/react-query"
 import { anyApi } from "convex/server"
 
 import { blockComponents } from "~/vexcms/blocks"
 
+type PageBlockLike = RenderableBlock
+
 export function SiteFooter({
   initialData,
 }: {
@@ -17,11 +19,12 @@ export function SiteFooter({
     initialData: initialData ?? undefined,
   })
 
-  if (!footer?.content) return null
+  const content = footer?.content as PageBlockLike[] | null | undefined
+  if (!content) return null
 
   return (
     <RenderBlocks
-      blocks={footer.content as any}
+      blocks={content}
       components={blockComponents}
     />
   )

package/templates/marketing-site/src/components/SiteHeader.tsx

@@ -1,12 +1,14 @@
 "use client"
 
-import { RenderBlocks } from "@vexcms/ui"
+import { RenderBlocks, type RenderableBlock } from "@vexcms/react"
 import { convexQuery } from "@convex-dev/react-query"
 import { useQuery } from "@tanstack/react-query"
 import { anyApi } from "convex/server"
 
 import { blockComponents } from "~/vexcms/blocks"
 
+type PageBlockLike = RenderableBlock
+
 export function SiteHeader({
   initialData,
 }: {
@@ -17,11 +19,12 @@ export function SiteHeader({
     initialData: initialData ?? undefined,
   })
 
-  if (!header?.content) return null
+  const content = header?.content as PageBlockLike[] | null | undefined
+  if (!content) return null
 
   return (
     <RenderBlocks
-      blocks={header.content as any}
+      blocks={content}
       components={blockComponents}
     />
   )

package/templates/marketing-site/src/components/ThemeLive.tsx

@@ -0,0 +1,59 @@
+"use client"
+
+import { api } from "@convex/_generated/api"
+import { useQuery } from "convex/react"
+import { useEffect } from "react"
+
+import { buildThemeCss, type ThemeScope } from "@vexcms/core"
+
+/**
+ * Client companion to the server `<ThemeStyle />`: keeps the applied theme
+ * live without a page reload.
+ *
+ * `useQuery` is a Convex subscription — the deployment pushes every change to
+ * the active theme document (or to which theme is active), so saving in the
+ * admin re-skins every open tab immediately. No polling, no preview channel,
+ * no drafts machinery.
+ *
+ * The CSS goes into an effect-managed `<style>` tag appended to `<head>`
+ * rather than a React-hoisted one: hoisted styles are deduplicated by `href`
+ * and are not guaranteed to update in place when their text changes, and an
+ * appended tag deterministically follows the server-rendered block — equal
+ * specificity, later in the document, so it wins the moment it exists. The
+ * first push matches the server CSS byte-for-byte, so nothing visibly changes
+ * until a real edit lands.
+ *
+ * Distinguishes loading from empty: while the query is unresolved
+ * (`undefined`) the server CSS stands; once it resolves to `null` (no active
+ * theme) the override is cleared and `globals.css` shows through.
+ *
+ * @param props - Input props.
+ * @param props.scope - Same contract as `<ThemeStyle />`: `"site"` emits
+ * `:root`, `"admin"` emits `:root:root` with the `adminTheme` fallback.
+ * @returns Nothing — the style element is managed imperatively.
+ */
+export function ThemeLive(props: { scope?: ThemeScope }) {
+  const scope = props.scope ?? "site"
+  const theme = useQuery(scope === "admin" ? api.theme.getAdmin : api.theme.getActive)
+
+  useEffect(() => {
+    if (theme === undefined) {return} // still loading — leave the server CSS alone
+
+    const id = `vex-theme-live-${scope}`
+    let el = document.getElementById(id) as HTMLStyleElement | null
+    if (!el) {
+      el = document.createElement("style")
+      el.id = id
+      document.head.appendChild(el)
+    }
+    el.textContent = theme ? buildThemeCss({ theme, scope }) : ""
+
+    return () => {
+      // Admin routes unmount their scope on navigation back to the site; the
+      // override must not outlive the layout that owns it.
+      el?.remove()
+    }
+  }, [theme, scope])
+
+  return null
+}

package/templates/marketing-site/src/components/ThemeStyle.tsx

@@ -1,104 +1,60 @@
-import { fetchQuery } from "convex/nextjs"
-
 import { api } from "@convex/_generated/api"
+import { fetchQuery } from "convex/nextjs"
 
-/**
- * CSS variable name mapping from camelCase field names to CSS custom property names.
- */
-const FIELD_TO_CSS_VAR: Record<string, string> = {
-  background: "background",
-  foreground: "foreground",
-  card: "card",
-  cardForeground: "card-foreground",
-  popover: "popover",
-  popoverForeground: "popover-foreground",
-  primary: "primary",
-  primaryForeground: "primary-foreground",
-  secondary: "secondary",
-  secondaryForeground: "secondary-foreground",
-  muted: "muted",
-  mutedForeground: "muted-foreground",
-  accent: "accent",
-  accentForeground: "accent-foreground",
-  destructive: "destructive",
-  destructiveForeground: "destructive-foreground",
-  border: "border",
-  input: "input",
-  ring: "ring",
-  chart1: "chart-1",
-  chart2: "chart-2",
-  chart3: "chart-3",
-  chart4: "chart-4",
-  chart5: "chart-5",
-  sidebar: "sidebar",
-  sidebarForeground: "sidebar-foreground",
-  sidebarPrimary: "sidebar-primary",
-  sidebarPrimaryForeground: "sidebar-primary-foreground",
-  sidebarAccent: "sidebar-accent",
-  sidebarAccentForeground: "sidebar-accent-foreground",
-  sidebarBorder: "sidebar-border",
-  sidebarRing: "sidebar-ring",
-}
-
-function buildCSSVars(colors: Record<string, unknown> | null | undefined): string {
-  if (!colors) return ""
-
-  const vars: string[] = []
-  for (const [fieldName, cssVar] of Object.entries(FIELD_TO_CSS_VAR)) {
-    const value = colors[fieldName]
-    if (typeof value === "string" && value) {
-      vars.push(`  --${cssVar}: ${value};`)
-    }
-  }
-  return vars.join("\n")
-}
+import { buildThemeCss, type ThemeScope } from "@vexcms/core"
 
 /**
- * Server component that fetches the active theme and inlines CSS variables
- * into the initial HTML. This eliminates the flash of unstyled content
- * that occurs when theme variables are injected client-side.
+ * Server component that inlines a theme's CSS custom properties.
+ *
+ * Rendered twice per admin request and once per public request:
+ *
+ * - the root layout emits the **site** theme at `:root`;
+ * - the admin layout emits the **admin** theme at `:root:root`.
  *
- * @param props.drafts - When true, fetches the draft/preview theme instead of published.
- *                       Use this in the preview layout so the server-rendered CSS
- *                       matches the draft state the admin is editing.
+ * `:root:root` is specificity (0,2,0) against `:root`'s (0,1,0), so the admin
+ * block wins wherever both are present without depending on style-injection
+ * order. On public routes the admin layout never renders, so there is exactly
+ * one block. Leave `siteSettings.adminTheme` empty and `getAdmin` falls back to
+ * the site theme, which is the default: **the admin adopts the site's palette.**
+ *
+ * Values are written through verbatim. A `color()` field storing
+ * `oklch(60.5% 0.175 42)` needs no conversion, because that is already the
+ * notation `globals.css` declares its tokens in.
+ *
+ * This component covers the **first paint** only — no flash of unthemed
+ * content. Live updates after a save are `<ThemeLive />`'s job, which
+ * subscribes to the same query client-side and overrides this block.
+ *
+ * Renders nothing when Convex is unreachable (e.g. a build with no deployment)
+ * or no theme is active — the app then uses `globals.css` unchanged.
+ *
+ * @param props - Input props.
+ * @param props.scope - `"site"` emits `:root`; `"admin"` emits `:root:root` and
+ * reads `adminTheme` with a fallback to the site theme.
+ * @returns A `<style>` element, or `null`.
  */
-export async function ThemeStyle({ drafts }: { drafts?: boolean } = {}) {
-  let theme: Record<string, unknown> | null = null
+export async function ThemeStyle(props: { scope?: ThemeScope }) {
+  const scope = props.scope ?? "site"
+
+  let theme: null | Record<string, unknown> = null
   try {
-    theme = drafts
-      ? await fetchQuery(api.theme.getActivePreview) as Record<string, unknown> | null
-      : await fetchQuery(api.theme.getActive) as Record<string, unknown> | null
+    theme = await fetchQuery(scope === "admin" ? api.theme.getAdmin : api.theme.getActive)
   } catch {
-    // Convex not available during build — use default styles
+    // No deployment reachable at build time — fall back to globals.css.
     return null
   }
+  if (!theme) {return null}
 
-  if (!theme) return null
-
-  const lightColors = theme.light as Record<string, unknown> | undefined
-  const darkColors = theme.dark as Record<string, unknown> | undefined
-
-  const lightVars = buildCSSVars(lightColors)
-  const darkVars = buildCSSVars(darkColors)
-
-  if (!lightVars && !darkVars) return null
-
-  const css = [
-    lightVars ? `:root {\n${lightVars}\n}` : "",
-    darkVars ? `.dark {\n${darkVars}\n}` : "",
-  ]
-    .filter(Boolean)
-    .join("\n\n")
-
-  const radius = theme.radius as string | undefined
-  const fontFamily = theme.fontFamily as string | undefined
-  const extraVars: string[] = []
-  if (radius) extraVars.push(`  --radius: ${radius};`)
-  if (fontFamily) extraVars.push(`  --font-sans: ${fontFamily};`)
-
-  const extraCSS = extraVars.length > 0 ? `\n:root {\n${extraVars.join("\n")}\n}` : ""
+  const css = buildThemeCss({ theme, scope })
+  if (!css) {return null}
 
+  // `precedence` opts into React 19 style hoisting, so this lands in <head>
+  // before first paint instead of mid-body.
   return (
-    <style dangerouslySetInnerHTML={{ __html: css + extraCSS }} />
+    <style
+      dangerouslySetInnerHTML={{ __html: css }}
+      href={`vex-theme-${scope}`}
+      precedence="high"
+    />
   )
 }