create-vexcms 0.1.0-alpha.2 → 0.1.0-alpha.21

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

@@ -0,0 +1,98 @@
+"use client"
+
+import { cn } from "@vexcms/react"
+
+import { useCodeHighlight } from "~/components/CodeHighlightContext"
+import { CopyButton } from "~/components/CopyButton"
+import { toCodeLanguage } from "~/lib/highlight"
+
+export type CodePaneProps = {
+  /** Extra classes for the scroll body. */
+  bodyClassName?: string
+  /** Source text exactly as authored in the CMS. */
+  code: string
+  /** Optional filename shown in the chrome bar. */
+  filename?: string
+  /** Uppercase pane label. `text-primary` marks the hand-written pane. */
+  label?: string
+  /** Raw `language` field value — a `select`, so usually an array. */
+  language?: string | string[]
+  /** Marks this pane as the authored one, which is the only colour signal
+   *  distinguishing human input from generated output. */
+  tone?: "authored" | "generated"
+}
+
+/**
+ * One code pane: a chrome bar and a scrolling body on the fixed dark surface.
+ *
+ * Shared by CodeShowcase and Split so the two never drift.
+ *
+ * Synchronous, and a client component, because it renders inside
+ * `PageContent` — which is client-side so live preview can overlay its query
+ * result. Highlighting therefore happens outside it: the server pre-highlights
+ * the fetched document's panes (`highlightPageBlocks`) and this reads the
+ * result through `useCodeHighlight`. An async component here is the error
+ * "<CodePane> is an async Client Component".
+ */
+export function CodePane({
+  bodyClassName,
+  code,
+  filename,
+  language,
+  label,
+  tone = "generated",
+}: CodePaneProps) {
+  const resolvedLanguage = toCodeLanguage(language)
+  const html = useCodeHighlight({ code, language: resolvedLanguage })
+
+  return (
+    // `min-w-0` is not optional. In a `1fr` grid track the longest line would
+    // otherwise set the min-content width, the column would outgrow the frame,
+    // and `overflow-x-auto` would never engage — the code gets clipped instead
+    // of scrolling.
+    <div className="flex min-w-0 flex-col">
+      <div className="flex h-10 shrink-0 items-center justify-between gap-3 border-b border-border bg-card px-3.5">
+        <div className="flex min-w-0 items-center gap-3">
+          {label ? (
+            <span
+              className={cn(
+                "shrink-0 text-[11px] font-medium tracking-[0.08em] uppercase",
+                tone === "authored" ? "text-primary" : "text-muted-foreground"
+              )}
+            >
+              {label}
+            </span>
+          ) : null}
+          {filename ? (
+            <span className="hidden truncate font-mono text-xs text-muted-foreground sm:block">
+              {filename}
+            </span>
+          ) : null}
+        </div>
+
+        <div className="flex shrink-0 items-center gap-1.5">
+          <span className="rounded-sm border border-border px-1.5 py-0.5 font-mono text-[11px] text-muted-foreground">
+            {resolvedLanguage}
+          </span>
+          <CopyButton label={`Copy ${filename ?? "code"}`} value={code} />
+        </div>
+      </div>
+
+      <div
+        className={cn(
+          "min-w-0 flex-1 overflow-auto overscroll-x-contain bg-[--color-code-bg] p-4 xl:px-4 xl:py-[18px]",
+          "max-h-[420px] md:max-h-[560px]",
+          bodyClassName
+        )}
+      >
+        <pre className="font-mono text-xs leading-[1.7] whitespace-pre text-[--color-code-fg] xl:text-[12.5px]">
+          {/* Pre-highlighted on the server for anything the page fetched. A
+              pane the server never saw (code being typed in live preview)
+              renders as plain source until the lazy browser highlighter
+              resolves — never blank, never a spinner over a code block. */}
+          {html === undefined ? <code>{code}</code> : <code dangerouslySetInnerHTML={{ __html: html }} />}
+        </pre>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react"
+
+import { cn } from "@vexcms/react"
+
+/**
+ * The site's single container. Every block uses it, so the left edge of a
+ * heading in one block lines up with the left edge of a card in the next.
+ *
+ * `max-w-[1280px]` with 20 / 32 / 40px gutters. Nothing changes above `xl`
+ * except centring. Prose-only sections nest a second `max-w-[46rem]` measure
+ * inside this one rather than narrowing it.
+ */
+export function Container({
+  children,
+  className,
+}: {
+  children: ReactNode
+  className?: string
+}) {
+  return (
+    <div className={cn("mx-auto w-full max-w-[1280px] px-5 md:px-8 xl:px-10", className)}>
+      {children}
+    </div>
+  )
+}

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

@@ -0,0 +1,80 @@
+"use client"
+
+import { Button, cn, Tooltip, TooltipContent, TooltipTrigger } from "@vexcms/react"
+import { Check, Copy } from "lucide-react"
+import { useEffect, useRef, useState } from "react"
+
+/** How long the confirmed state holds before reverting to the copy glyph. */
+const CONFIRM_MS = 1600
+
+/**
+ * Copy-to-clipboard control shared by the hero install row and every code
+ * pane, so the confirmation timing and the screen-reader announcement are
+ * identical everywhere they appear.
+ *
+ * @param props - Component props.
+ * @param props.value - Exact string written to the clipboard. Callers strip
+ *   decoration (the `$` prompt, chrome) before passing it.
+ * @param props.label - Accessible name for the control.
+ * @param props.className - Extra classes for the trigger.
+ */
+export function CopyButton({
+  className,
+  label = "Copy",
+  value,
+}: {
+  className?: string
+  label?: string
+  value: string
+}) {
+  const [isCopied, setIsCopied] = useState(false)
+  const timeoutRef = useRef<null | number>(null)
+
+  useEffect(() => {
+    return () => {
+      window.clearTimeout(timeoutRef.current ?? undefined)
+    }
+  }, [])
+
+  const handleCopy = () => {
+    void navigator.clipboard.writeText(value).then(() => {
+      setIsCopied(true)
+      window.clearTimeout(timeoutRef.current ?? undefined)
+      timeoutRef.current = window.setTimeout(() => setIsCopied(false), CONFIRM_MS)
+    })
+  }
+
+  const trigger = (
+    <Button
+      aria-label={label}
+      className={cn(
+        "shrink-0 transition-colors duration-[180ms] ease-[var(--ease-emphasized)] active:translate-y-px",
+        isCopied && "text-primary",
+        className
+      )}
+      onClick={handleCopy}
+      size="icon-xs"
+      type="button"
+      variant="ghost"
+    >
+      {isCopied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
+    </Button>
+  )
+
+  return (
+    <>
+      {/* Tooltips are pointer affordances; the live region is what carries the
+          confirmation to assistive tech. */}
+      <span aria-live="polite" className="sr-only">
+        {isCopied ? "Copied" : ""}
+      </span>
+      <span className="hidden md:contents">
+        <Tooltip>
+          <TooltipTrigger render={trigger} />
+          <TooltipContent>{isCopied ? "Copied" : label}</TooltipContent>
+        </Tooltip>
+      </span>
+      <span className="contents md:hidden">{trigger}</span>
+    </>
+  )
+}

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

@@ -0,0 +1,54 @@
+"use client"
+
+import { api } from "@convex/_generated/api"
+import { useMutation, useQuery } from "convex/react"
+import { useRouter } from "next/navigation"
+import { useEffect, useRef } from "react"
+
+import { useSession } from "~/auth/client"
+
+/**
+ * Promotes the first signed-in user to admin when no admin exists yet, then
+ * redirects to `/admin`. Headless — renders nothing.
+ *
+ * `WelcomePage`'s own trigger (`convex/vex/firstUser.ts`'s
+ * `promoteFirstAdmin`) only runs while `PageContent` is showing its
+ * no-page-found fallback — which stops rendering the instant a `home` page
+ * document exists. A fresh marketing scaffold gets a `home` document from
+ * `pnpm seed` on day one, so that fallback may never mount again and the
+ * bootstrap trigger would never fire. This mounts unconditionally in
+ * `(frontend)/layout.tsx` instead, so the trigger survives seeding.
+ *
+ * `promoteFirstAdmin` is a Convex mutation, so concurrent signups cannot
+ * both win — Convex serializes mutations, and the loser observes
+ * `isBootstrapped` already true.
+ */
+export function FirstAdminBootstrap() {
+  const isBootstrapped = useQuery(api.vex.firstUser.isBootstrapped)
+  const promoteFirstAdmin = useMutation(api.vex.firstUser.promoteFirstAdmin)
+  const { data: session } = useSession()
+  const router = useRouter()
+  // A ref, not state: this is a run-once latch, and nothing renders from it.
+  // Setting state inside the effect re-runs the effect to reach the same
+  // conclusion, which is what `react-hooks/set-state-in-effect` objects to.
+  const promotingRef = useRef(false)
+
+  useEffect(() => {
+    if (!session?.user || isBootstrapped !== false || promotingRef.current) {return}
+
+    promotingRef.current = true
+    promoteFirstAdmin()
+      .then((result) => {
+        if (result.promoted) {
+          router.push("/admin")
+        } else {
+          promotingRef.current = false
+        }
+      })
+      .catch(() => {
+        promotingRef.current = false
+      })
+  }, [session, isBootstrapped, promoteFirstAdmin, router])
+
+  return null
+}

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

@@ -0,0 +1,29 @@
+"use client"
+
+import { CopyButton } from "~/components/CopyButton"
+
+/**
+ * The hero's install row — a mono command on the code-pane surface with a copy
+ * control. The only client component in the hero.
+ *
+ * The `$` prompt is decoration: it is `aria-hidden` and never part of the
+ * copied string, so pasting the result runs.
+ *
+ * @param props - Component props.
+ * @param props.command - The command to display and copy.
+ */
+export function InstallCommand({ command }: { command: string }) {
+  return (
+    <div className="flex w-full max-w-full items-center gap-2 rounded-sm border border-border bg-[--color-code-bg] py-1.5 pr-1.5 pl-3 sm:w-auto">
+      <span aria-hidden className="shrink-0 font-mono text-[13px] text-muted-foreground">
+        $
+      </span>
+      {/* Below 640 the command scrolls rather than wrapping to two lines — a
+          wrapped shell command reads as two commands. */}
+      <code className="overflow-x-auto overscroll-x-contain font-mono text-[13px] whitespace-pre text-[--color-code-fg]">
+        {command}
+      </code>
+      <CopyButton label="Copy install command" value={command} />
+    </div>
+  )
+}

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

@@ -0,0 +1,59 @@
+"use client"
+
+import { convexQuery } from "@convex-dev/react-query"
+import { api } from "@convex/_generated/api"
+import { useQuery } from "@tanstack/react-query"
+import Image from "next/image"
+
+/**
+ * Renders an `upload()` field value as a `next/image`.
+ *
+ * An `upload()` field stores an **array of media ids**, not a URL, so the id
+ * has to be exchanged for a public URL through the storage adapter before
+ * anything can be rendered. Passing the field value straight to `src` sets it
+ * to a Convex document id and renders a broken image.
+ *
+ * Client-side by design: it is used from both the client Header and the
+ * server Footer, and one component with one code path beats a server and a
+ * client variant that can drift.
+ *
+ * Renders nothing while resolving, and nothing if the media document is gone —
+ * callers pair it with a text fallback rather than reserving empty space.
+ *
+ * @param props - Component props.
+ * @param props.value - Raw `upload()` field value.
+ * @param props.alt - Accessible name. Empty string for decorative marks.
+ * @param props.width - Intrinsic width hint for `next/image`.
+ * @param props.height - Intrinsic height hint for `next/image`.
+ * @param props.className - Classes applied to the rendered image.
+ */
+export function MediaImage({
+  alt,
+  className,
+  height,
+  value,
+  width,
+}: {
+  alt: string
+  className?: string
+  height: number
+  value: string | string[] | undefined
+  width: number
+}) {
+  const mediaId = Array.isArray(value) ? value[0] : value
+
+  const { data } = useQuery({
+    ...convexQuery(
+      api.vex.media.getUrl,
+      mediaId ? { adapter: "convex", mediaId } : "skip"
+    ),
+    enabled: Boolean(mediaId),
+  })
+
+  const url = (data as undefined | { url?: string })?.url
+  if (!url) {return null}
+
+  return (
+    <Image alt={alt} className={className} height={height} src={url} width={width} />
+  )
+}

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

@@ -0,0 +1,51 @@
+import { cn } from "@vexcms/react"
+
+/**
+ * The one section-header pattern: left-aligned, capped at a 36rem measure,
+ * h2 then subheading, 40px above the block's content.
+ *
+ * When `subheading` is blank the gap drops to 32px rather than the h2 growing
+ * to compensate — every block that has a heading uses this, so the rhythm has
+ * to be decided once.
+ *
+ * @param props - Component props.
+ * @param props.heading - Section h2.
+ * @param props.subheading - Optional supporting line.
+ * @param props.align - `center` is used only by FAQ and CTA.
+ * @param props.className - Extra classes on the wrapper.
+ */
+export function SectionHeader({
+  align = "left",
+  className,
+  heading,
+  subheading,
+}: {
+  align?: "center" | "left"
+  className?: string
+  heading?: string
+  subheading?: string
+}) {
+  if (!heading && !subheading) {return null}
+
+  return (
+    <div
+      className={cn(
+        "max-w-[36rem]",
+        align === "center" && "mx-auto text-center",
+        subheading ? "mb-8 xl:mb-10" : "mb-7 xl:mb-8",
+        className
+      )}
+    >
+      {heading ? (
+        <h2 className="text-[26px] leading-[1.18] font-bold tracking-[-0.025em] text-balance text-foreground md:text-3xl xl:text-4xl">
+          {heading}
+        </h2>
+      ) : null}
+      {subheading ? (
+        <p className="mt-4 text-[17px] leading-[1.6] text-pretty text-muted-foreground md:text-lg">
+          {subheading}
+        </p>
+      ) : null}
+    </div>
+  )
+}

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

@@ -1,9 +1,11 @@
 "use client"
 
-import { RenderBlocks, type RenderableBlock } from "@vexcms/react"
 import { convexQuery } from "@convex-dev/react-query"
+import { api } from "@convex/_generated/api"
 import { useQuery } from "@tanstack/react-query"
-import { anyApi } from "convex/server"
+import { type RenderableBlock, RenderBlocks } from "@vexcms/react"
+
+import type { FootersDocument } from "~/vex.types"
 
 import { blockComponents } from "~/vexcms/blocks"
 
@@ -12,15 +14,15 @@ type PageBlockLike = RenderableBlock
 export function SiteFooter({
   initialData,
 }: {
-  initialData?: Record<string, unknown> | null
+  initialData?: FootersDocument | null
 }) {
   const { data: footer } = useQuery({
-    ...convexQuery(anyApi.footers.getFirst, {}),
+    ...convexQuery(api.footers.getFirst, {}),
     initialData: initialData ?? undefined,
   })
 
-  const content = footer?.content as PageBlockLike[] | null | undefined
-  if (!content) return null
+  const content = footer?.content as null | PageBlockLike[] | undefined
+  if (!content) {return null}
 
   return (
     <RenderBlocks

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

@@ -1,9 +1,11 @@
 "use client"
 
-import { RenderBlocks, type RenderableBlock } from "@vexcms/react"
 import { convexQuery } from "@convex-dev/react-query"
+import { api } from "@convex/_generated/api"
 import { useQuery } from "@tanstack/react-query"
-import { anyApi } from "convex/server"
+import { type RenderableBlock, RenderBlocks } from "@vexcms/react"
+
+import type { HeadersDocument } from "~/vex.types"
 
 import { blockComponents } from "~/vexcms/blocks"
 
@@ -12,15 +14,15 @@ type PageBlockLike = RenderableBlock
 export function SiteHeader({
   initialData,
 }: {
-  initialData?: Record<string, unknown> | null
+  initialData?: HeadersDocument | null
 }) {
   const { data: header } = useQuery({
-    ...convexQuery(anyApi.headers.getFirst, {}),
+    ...convexQuery(api.headers.getFirst, {}),
     initialData: initialData ?? undefined,
   })
 
-  const content = header?.content as PageBlockLike[] | null | undefined
-  if (!content) return null
+  const content = header?.content as null | PageBlockLike[] | undefined
+  if (!content) {return null}
 
   return (
     <RenderBlocks

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

@@ -1,11 +1,10 @@
 "use client"
 
 import { api } from "@convex/_generated/api"
+import { buildThemeCss, type ThemeScope } from "@vexcms/core"
 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.

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

@@ -1,8 +1,8 @@
 import { api } from "@convex/_generated/api"
-import { fetchQuery } from "convex/nextjs"
-
 import { buildThemeCss, type ThemeScope } from "@vexcms/core"
 
+import { vex } from "~/lib/vex"
+
 /**
  * Server component that inlines a theme's CSS custom properties.
  *
@@ -38,7 +38,7 @@ export async function ThemeStyle(props: { scope?: ThemeScope }) {
 
   let theme: null | Record<string, unknown> = null
   try {
-    theme = await fetchQuery(scope === "admin" ? api.theme.getAdmin : api.theme.getActive)
+    theme = await vex.query(scope === "admin" ? api.theme.getAdmin : api.theme.getActive)
   } catch {
     // No deployment reachable at build time — fall back to globals.css.
     return null

package/templates/marketing-site/src/components/motion-primitives/animated-group.tsx

@@ -1,138 +1,62 @@
-"use client"
+import React, { type ComponentPropsWithRef, type CSSProperties } from "react"
 
-import { motion, type Variants } from "motion/react"
-import React, { type ComponentPropsWithRef } from "react"
+import { cn } from "~/lib/utils"
 
-export type PresetType =
-  | "blur"
-  | "blur-slide"
-  | "bounce"
-  | "fade"
-  | "flip"
-  | "rotate"
-  | "scale"
-  | "slide"
-  | "swing"
-  | "zoom"
+import styles from "./reveal.module.css"
 
 export type AnimatedGroupProps = ComponentPropsWithRef<"div"> & {
   as?: React.ElementType
-  asChild?: React.ElementType
-  className?: string
-  preset?: PresetType
-  variants?: {
-    container?: Variants
-    item?: Variants
-  }
+  /** Seconds before the first child starts animating. */
+  delay?: number
+  /** Seconds between each child's start. */
+  stagger?: number
 }
 
-const defaultContainerVariants: Variants = {
-  visible: {
-    transition: {
-      staggerChildren: 0.1,
-    },
-  },
-}
-
-const defaultItemVariants: Variants = {
-  hidden: { opacity: 0 },
-  visible: { opacity: 1 },
-}
-
-const presetVariants: Record<PresetType, Variants> = {
-  "blur-slide": {
-    hidden: { filter: "blur(4px)", y: 20 },
-    visible: { filter: "blur(0px)", y: 0 },
-  },
-  slide: {
-    hidden: { y: 20 },
-    visible: { y: 0 },
-  },
-  blur: {
-    hidden: { filter: "blur(4px)" },
-    visible: { filter: "blur(0px)" },
-  },
-  bounce: {
-    hidden: { y: -50 },
-    visible: {
-      transition: { type: "spring", damping: 10, stiffness: 400 },
-      y: 0,
-    },
-  },
-  fade: {},
-  flip: {
-    hidden: { rotateX: -90 },
-    visible: {
-      rotateX: 0,
-      transition: { type: "spring", damping: 20, stiffness: 300 },
-    },
-  },
-  rotate: {
-    hidden: { rotate: -180 },
-    visible: {
-      rotate: 0,
-      transition: { type: "spring", damping: 15, stiffness: 200 },
-    },
-  },
-  scale: {
-    hidden: { scale: 0.8 },
-    visible: { scale: 1 },
-  },
-  swing: {
-    hidden: { rotate: -10 },
-    visible: {
-      rotate: 0,
-      transition: { type: "spring", damping: 8, stiffness: 300 },
-    },
-  },
-  zoom: {
-    hidden: { scale: 0.5 },
-    visible: {
-      scale: 1,
-      transition: { type: "spring", damping: 20, stiffness: 300 },
-    },
-  },
-}
-
-const addDefaultVariants = (variants: Variants) => ({
-  hidden: { ...defaultItemVariants.hidden, ...variants.hidden },
-  visible: { ...defaultItemVariants.visible, ...variants.visible },
-})
-
-function AnimatedGroup({
-  as = "div",
-  asChild = "div",
+/**
+ * Staggers a blur + fade + rise entrance across its direct children using a
+ * pure-CSS keyframe (see `reveal.module.css`) — no animation-library
+ * dependency. Each child is wrapped in a div carrying the animation with an
+ * incremented `animation-delay`.
+ */
+export function AnimatedGroup({
+  as: Tag = "div",
   children,
   className,
-  preset,
-  variants,
+  delay = 0,
+  stagger = 0.05,
   ...divProps
 }: AnimatedGroupProps) {
-  const selectedVariants = {
-    container: addDefaultVariants(defaultContainerVariants),
-    item: addDefaultVariants(preset ? presetVariants[preset] : {}),
-  }
-  const containerVariants = variants?.container ?? selectedVariants.container
-  const itemVariants = variants?.item ?? selectedVariants.item
-
-  const MotionComponent = motion.create(as)
-  const MotionChild = motion.create(asChild)
-
   return (
-    <MotionComponent
-      animate="visible"
-      className={className}
-      initial="hidden"
-      variants={containerVariants}
-      {...divProps}
-    >
+    <Tag className={className} {...divProps}>
       {React.Children.map(children, (child, index) => (
-        <MotionChild key={index} variants={itemVariants}>
+        <div
+          className={styles.item}
+          style={{ "--reveal-delay": `${delay + index * stagger}s` } as CSSProperties}
+        >
           {child}
-        </MotionChild>
+        </div>
       ))}
-    </MotionComponent>
+    </Tag>
   )
 }
 
-export { AnimatedGroup }
+/**
+ * Applies the same reveal animation to a single element without adding a
+ * wrapper div — for callers that only need one animated child.
+ */
+export function AnimatedItem({
+  children,
+  className,
+  delay = 0,
+  ...divProps
+}: ComponentPropsWithRef<"div"> & { delay?: number }) {
+  return (
+    <div
+      className={cn(styles.item, className)}
+      style={{ "--reveal-delay": `${delay}s` } as CSSProperties}
+      {...divProps}
+    >
+      {children}
+    </div>
+  )
+}