convex-cms 0.0.9-alpha.8 → 0.0.9-alpha.9

package/README.md

@@ -120,6 +120,33 @@ Leverage included features or extend and customize within your own convex functi
 
 Both modes call the same functions from your `convex/admin.ts`.
 
+### Embedding with Theme Modes
+
+When embedding CmsAdmin in your React app, you can control how it handles CSS variables:
+
+```tsx
+// Isolated mode (default) - admin uses its own theme
+<CmsAdmin api={api.admin} auth={authConfig} themeMode="isolated" />
+
+// Inherit mode - admin inherits your app's CSS variables (for shadcn apps)
+<CmsAdmin api={api.admin} auth={authConfig} themeMode="inherit" />
+```
+
+| Mode | Behavior |
+|------|----------|
+| `isolated` | Admin defines all CSS variables, ignoring parent app styles |
+| `inherit` | Admin inherits parent's shadcn variables, only defines sidebar fallbacks |
+
+**Critical for Tailwind 4 apps:** If Tailwind utility classes aren't applying to the embedded admin, add a `@source` directive to your app's CSS:
+
+```css
+/* your-app/src/index.css */
+@import "tailwindcss";
+@source "../node_modules/convex-cms/admin/dist/**/*.js";
+```
+
+This tells Tailwind to scan the admin's compiled JavaScript for utility classes.
+
 ## Documentation
 
 | Guide | Description |

package/admin/src/components/cmsds/CmsFilterBar.tsx

@@ -0,0 +1,74 @@
+import * as React from 'react'
+import { Search, X } from 'lucide-react'
+import { CmsInput } from './CmsInput'
+import { CmsSelect, type CmsSelectOption } from './CmsSelect'
+import { CmsButton } from './CmsButton'
+import { cn } from '~/lib/cn'
+
+export interface CmsFilterBarFilter {
+  key: string
+  value: string
+  onChange: (value: string) => void
+  options: CmsSelectOption[]
+  placeholder?: string
+  className?: string
+}
+
+export interface CmsFilterBarProps {
+  search?: {
+    value: string
+    onChange: (value: string) => void
+    placeholder?: string
+    className?: string
+  }
+  filters?: CmsFilterBarFilter[]
+  actions?: React.ReactNode
+  onClearFilters?: () => void
+  hasActiveFilters?: boolean
+  className?: string
+}
+
+export function CmsFilterBar({
+  search,
+  filters,
+  actions,
+  onClearFilters,
+  hasActiveFilters,
+  className,
+}: CmsFilterBarProps) {
+  return (
+    <div className={cn("flex flex-wrap items-center gap-3 pb-4", className)}>
+      <div className="flex flex-1 flex-wrap items-center gap-2">
+        {search && (
+          <div className="relative w-full max-w-xs">
+            <Search className="absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+            <CmsInput
+              type="search"
+              placeholder={search.placeholder ?? "Search..."}
+              value={search.value}
+              onChange={(e) => search.onChange(e.target.value)}
+              className={cn("pl-9", search.className)}
+            />
+          </div>
+        )}
+        {filters?.map((filter) => (
+          <CmsSelect
+            key={filter.key}
+            value={filter.value}
+            onValueChange={filter.onChange}
+            options={filter.options}
+            placeholder={filter.placeholder}
+            className={cn("w-[150px]", filter.className)}
+          />
+        ))}
+        {hasActiveFilters && onClearFilters && (
+          <CmsButton variant="ghost" size="sm" onClick={onClearFilters}>
+            <X className="mr-1 size-4" />
+            Clear
+          </CmsButton>
+        )}
+      </div>
+      {actions && <div className="flex items-center gap-2">{actions}</div>}
+    </div>
+  )
+}

package/admin/src/components/cmsds/CmsInput.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react'
+import { Input } from '~/components/ui/input'
+import { cn } from '~/lib/cn'
+
+export interface CmsInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  error?: boolean
+}
+
+export const CmsInput = React.forwardRef<HTMLInputElement, CmsInputProps>(
+  ({ className, error, ...props }, ref) => {
+    return (
+      <Input
+        ref={ref}
+        className={cn(
+          error && "border-destructive focus-visible:ring-destructive",
+          className
+        )}
+        aria-invalid={error}
+        {...props}
+      />
+    )
+  }
+)
+CmsInput.displayName = 'CmsInput'

package/admin/src/components/cmsds/CmsPagination.tsx

@@ -0,0 +1,79 @@
+import {
+	ChevronLeft,
+	ChevronRight,
+	ChevronsLeft,
+	ChevronsRight,
+} from "lucide-react";
+import { CmsButton } from "./CmsButton";
+import { cn } from "~/lib/cn";
+
+export interface CmsPaginationProps {
+	currentPage: number;
+	totalPages: number;
+	onPageChange: (page: number) => void;
+	showFirstLast?: boolean;
+	className?: string;
+}
+
+export function CmsPagination({
+	currentPage,
+	totalPages,
+	onPageChange,
+	showFirstLast = true,
+	className,
+}: CmsPaginationProps) {
+	const canGoPrev = currentPage > 1;
+	const canGoNext = currentPage < totalPages;
+
+	if (totalPages <= 1) {
+		return null;
+	}
+
+	return (
+		<div className={cn("flex items-center justify-center gap-1", className)}>
+			{showFirstLast && (
+				<CmsButton
+					variant="ghost"
+					size="sm"
+					onClick={() => onPageChange(1)}
+					disabled={!canGoPrev}
+					aria-label="First page"
+				>
+					<ChevronsLeft className="size-4" />
+				</CmsButton>
+			)}
+			<CmsButton
+				variant="ghost"
+				size="sm"
+				onClick={() => onPageChange(currentPage - 1)}
+				disabled={!canGoPrev}
+				aria-label="Previous page"
+			>
+				<ChevronLeft className="size-4" />
+			</CmsButton>
+			<span className="px-3 text-sm text-muted-foreground">
+				Page {currentPage} of {totalPages}
+			</span>
+			<CmsButton
+				variant="ghost"
+				size="sm"
+				onClick={() => onPageChange(currentPage + 1)}
+				disabled={!canGoNext}
+				aria-label="Next page"
+			>
+				<ChevronRight className="size-4" />
+			</CmsButton>
+			{showFirstLast && (
+				<CmsButton
+					variant="ghost"
+					size="sm"
+					onClick={() => onPageChange(totalPages)}
+					disabled={!canGoNext}
+					aria-label="Last page"
+				>
+					<ChevronsRight className="size-4" />
+				</CmsButton>
+			)}
+		</div>
+	);
+}

package/admin/src/components/cmsds/CmsSelect.tsx

@@ -0,0 +1,59 @@
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from "~/components/ui/select";
+import { cn } from "~/lib/cn";
+
+export interface CmsSelectOption {
+	value: string;
+	label: string;
+	disabled?: boolean;
+}
+
+export interface CmsSelectProps {
+	value?: string;
+	onValueChange?: (value: string) => void;
+	options: CmsSelectOption[];
+	placeholder?: string;
+	disabled?: boolean;
+	error?: boolean;
+	className?: string;
+}
+
+export function CmsSelect({
+	value,
+	onValueChange,
+	options,
+	placeholder = "Select...",
+	disabled,
+	error,
+	className,
+}: CmsSelectProps) {
+	return (
+		<Select value={value} onValueChange={onValueChange} disabled={disabled}>
+			<SelectTrigger
+				className={cn(
+					error && "border-destructive focus:ring-destructive",
+					className,
+				)}
+				aria-invalid={error}
+			>
+				<SelectValue placeholder={placeholder} />
+			</SelectTrigger>
+			<SelectContent>
+				{options.map((option) => (
+					<SelectItem
+						key={option.value}
+						value={option.value}
+						disabled={option.disabled}
+					>
+						{option.label}
+					</SelectItem>
+				))}
+			</SelectContent>
+		</Select>
+	);
+}

package/admin/src/components/cmsds/CmsStatCard.tsx

@@ -0,0 +1,79 @@
+import * as React from 'react'
+import { CmsSurface } from './CmsSurface'
+import { cn } from '~/lib/cn'
+
+export interface CmsStatCardProps {
+  title: string
+  value: string | number
+  description?: string
+  icon?: React.ReactNode
+  trend?: { value: number; label: string }
+  onClick?: () => void
+  isLoading?: boolean
+  className?: string
+}
+
+export function CmsStatCard({
+  title,
+  value,
+  description,
+  icon,
+  trend,
+  onClick,
+  isLoading,
+  className,
+}: CmsStatCardProps) {
+  const content = (
+    <>
+      <div className="flex items-start justify-between">
+        <div className="space-y-1">
+          <p className="text-sm font-medium text-muted-foreground">{title}</p>
+          {isLoading ? (
+            <div className="h-8 w-16 animate-pulse rounded bg-muted" />
+          ) : (
+            <p className="text-2xl font-semibold text-foreground">{value}</p>
+          )}
+          {description && (
+            <p className="text-xs text-muted-foreground">{description}</p>
+          )}
+        </div>
+        {icon && (
+          <div className="flex size-10 items-center justify-center rounded-lg bg-primary/10 text-primary">
+            {icon}
+          </div>
+        )}
+      </div>
+      {trend && !isLoading && (
+        <div className={cn(
+          "mt-2 text-xs font-medium",
+          trend.value >= 0 ? "text-diff-added-foreground" : "text-diff-removed-foreground"
+        )}>
+          {trend.value >= 0 ? "+" : ""}{trend.value}% {trend.label}
+        </div>
+      )}
+    </>
+  )
+
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        onClick={onClick}
+        className={cn(
+          "text-left w-full cursor-pointer transition-colors hover:bg-accent/50",
+          className
+        )}
+      >
+        <CmsSurface elevation="base" padding="md" className="h-full">
+          {content}
+        </CmsSurface>
+      </button>
+    )
+  }
+
+  return (
+    <CmsSurface elevation="base" padding="md" className={cn("h-full", className)}>
+      {content}
+    </CmsSurface>
+  )
+}

package/admin/src/components/cmsds/CmsStatusBadge.tsx

@@ -96,7 +96,7 @@ const colorToClassName: Record<WorkflowStateColor, string> = {
   blue: "bg-info-bg text-info-foreground",
   green: "bg-diff-added-bg text-diff-added-foreground",
   red: "bg-diff-removed-bg text-diff-removed-foreground",
-  purple: "bg-purple-100 text-purple-800 dark:bg-purple-900/30 dark:text-purple-400",
+  purple: "bg-purple-bg text-purple-foreground",
   orange: "bg-diff-modified-bg text-diff-modified-foreground",
 };
 

package/admin/src/components/cmsds/index.ts

@@ -8,3 +8,8 @@ export { CmsToolbar, type CmsToolbarProps } from './CmsToolbar'
 export { CmsDropdown, type CmsDropdownProps, type CmsDropdownAction } from './CmsDropdown'
 export { CmsTable, type CmsTableProps, type CmsTableColumn } from './CmsTable'
 export { CmsDialog, CmsConfirmDialog, type CmsDialogProps, type CmsConfirmDialogProps } from './CmsDialog'
+export { CmsInput, type CmsInputProps } from './CmsInput'
+export { CmsSelect, type CmsSelectProps, type CmsSelectOption } from './CmsSelect'
+export { CmsFilterBar, type CmsFilterBarProps, type CmsFilterBarFilter } from './CmsFilterBar'
+export { CmsStatCard, type CmsStatCardProps } from './CmsStatCard'
+export { CmsPagination, type CmsPaginationProps } from './CmsPagination'

package/admin/src/contexts/ThemeContext.tsx

@@ -13,6 +13,7 @@ interface ThemeContextValue {
   theme: Theme
   resolvedTheme: 'light' | 'dark'
   setTheme: (theme: Theme) => void
+  canToggleDarkMode: boolean
 }
 
 const ThemeContext = createContext<ThemeContextValue | null>(null)
@@ -33,9 +34,36 @@ function getStoredTheme(): Theme {
   return 'system'
 }
 
-export function ThemeProvider({ children }: { children: ReactNode }) {
-  const [theme, setThemeState] = useState<Theme>(() => getStoredTheme())
+function getParentDarkMode(): boolean {
+  if (typeof window === 'undefined') return false
+  return document.documentElement.classList.contains('dark')
+}
+
+export interface ThemeProviderProps {
+  children: ReactNode
+  themeMode?: 'isolated' | 'inherit'
+  darkModeControl?: 'independent' | 'follow-parent'
+}
+
+export function ThemeProvider({
+  children,
+  themeMode = 'isolated',
+  darkModeControl = 'independent',
+}: ThemeProviderProps) {
+  const canToggleDarkMode = themeMode === 'isolated' || darkModeControl === 'independent'
+  const shouldFollowParent = themeMode === 'inherit' && darkModeControl === 'follow-parent'
+
+  const [theme, setThemeState] = useState<Theme>(() => {
+    if (shouldFollowParent) {
+      return getParentDarkMode() ? 'dark' : 'light'
+    }
+    return getStoredTheme()
+  })
+
   const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>(() => {
+    if (shouldFollowParent) {
+      return getParentDarkMode() ? 'dark' : 'light'
+    }
     const stored = getStoredTheme()
     return stored === 'system' ? getSystemTheme() : stored
   })
@@ -44,39 +72,79 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
     const resolved = newTheme === 'system' ? getSystemTheme() : newTheme
     setResolvedTheme(resolved)
 
-    const root = document.documentElement
-    root.classList.remove('light', 'dark')
-    root.classList.add(resolved)
-  }, [])
+    if (canToggleDarkMode) {
+      const root = document.documentElement
+      root.classList.remove('light', 'dark')
+      root.classList.add(resolved)
+    }
+  }, [canToggleDarkMode])
 
   const setTheme = useCallback(
     (newTheme: Theme) => {
+      if (!canToggleDarkMode) return
+
       setThemeState(newTheme)
       localStorage.setItem(STORAGE_KEY, newTheme)
       applyTheme(newTheme)
     },
-    [applyTheme]
+    [applyTheme, canToggleDarkMode]
   )
 
   useEffect(() => {
-    applyTheme(theme)
-  }, [theme, applyTheme])
+    if (!shouldFollowParent) {
+      applyTheme(theme)
+    }
+  }, [theme, applyTheme, shouldFollowParent])
 
   useEffect(() => {
-    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+    if (!shouldFollowParent) {
+      const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
 
-    const handleChange = () => {
-      if (theme === 'system') {
-        applyTheme('system')
+      const handleChange = () => {
+        if (theme === 'system') {
+          applyTheme('system')
+        }
       }
+
+      mediaQuery.addEventListener('change', handleChange)
+      return () => mediaQuery.removeEventListener('change', handleChange)
+    }
+  }, [theme, applyTheme, shouldFollowParent])
+
+  useEffect(() => {
+    if (!shouldFollowParent) return
+
+    const handleParentThemeChange = () => {
+      const isDark = getParentDarkMode()
+      const newTheme = isDark ? 'dark' : 'light'
+      setThemeState(newTheme)
+      setResolvedTheme(newTheme)
     }
 
-    mediaQuery.addEventListener('change', handleChange)
-    return () => mediaQuery.removeEventListener('change', handleChange)
-  }, [theme, applyTheme])
+    handleParentThemeChange()
+
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (
+          mutation.type === 'attributes' &&
+          mutation.attributeName === 'class'
+        ) {
+          handleParentThemeChange()
+          break
+        }
+      }
+    })
+
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['class'],
+    })
+
+    return () => observer.disconnect()
+  }, [shouldFollowParent])
 
   return (
-    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
+    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme, canToggleDarkMode }}>
       {children}
     </ThemeContext.Provider>
   )

package/admin/src/embed/components/EmbedHeader.tsx

@@ -11,7 +11,7 @@ import { useEmbedNavigation } from "../navigation";
 export function EmbedHeader() {
   const { goBack, canGoBack, currentRoute } = useEmbedNavigation();
   const { branding: _branding } = useAdminConfig();
-  const { theme, setTheme } = useTheme();
+  const { theme, setTheme, canToggleDarkMode } = useTheme();
   const { user, logout, isAuthenticated } = useAuth();
 
   const routeTitles: Record<string, string> = {
@@ -44,14 +44,16 @@ export function EmbedHeader() {
       </div>
 
       <div className="flex items-center gap-2">
-        <button
-          type="button"
-          onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
-          className="flex size-9 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground"
-          title={`Switch to ${theme === "dark" ? "light" : "dark"} mode`}
-        >
-          {theme === "dark" ? <Sun className="size-5" /> : <Moon className="size-5" />}
-        </button>
+        {canToggleDarkMode && (
+          <button
+            type="button"
+            onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+            className="flex size-9 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground"
+            title={`Switch to ${theme === "dark" ? "light" : "dark"} mode`}
+          >
+            {theme === "dark" ? <Sun className="size-5" /> : <Moon className="size-5" />}
+          </button>
+        )}
 
         <button
           type="button"

package/admin/src/embed/components/EmbedLayout.tsx

@@ -3,7 +3,6 @@
  *
  * A router-agnostic layout for the embedded admin that uses
  * EmbedSidebar instead of the router-dependent Sidebar.
- * Uses CSS Grid for proper container-relative positioning.
  */
 
 import type { ReactNode } from "react";
@@ -19,12 +18,9 @@ export function EmbedLayout({ children }: EmbedLayoutProps) {
   const { layout } = useAdminConfig();
 
   return (
-    <div
-      className="grid h-full bg-background"
-      style={{ gridTemplateColumns: `${layout.sidebarWidth}px 1fr` }}
-    >
+    <div className="flex min-h-screen bg-background">
       <EmbedSidebar />
-      <div className="flex flex-col overflow-hidden">
+      <div className="flex flex-1 flex-col" style={{ marginLeft: layout.sidebarWidth }}>
         <EmbedHeader />
         <main className="flex-1 overflow-auto p-6">{children}</main>
       </div>

package/admin/src/embed/components/EmbedSidebar.tsx

@@ -36,9 +36,7 @@ function pathToRoute(path: string): EmbedRoute {
 export function EmbedSidebar() {
   const { currentPath, navigate, navigateToContentType } = useEmbedNavigation();
   const config = useAdminConfig();
-  const { navItems, branding,
-    // layout
-  } = config;
+  const { navItems, branding, layout } = config;
   const api = useApi();
 
   const [isCreateModalOpen, setIsCreateModalOpen] = useState(false);
@@ -154,9 +152,14 @@ export function EmbedSidebar() {
     </Collapsible>
   );
 
+  const sidebarWidth = layout.sidebarWidth;
+
   return (
     <>
-      <aside className="sticky top-0 z-40 flex h-full flex-col overflow-hidden border-r border-sidebar-border bg-sidebar">
+      <aside
+        className="fixed inset-y-0 left-0 z-50 flex flex-col border-r border-sidebar-border bg-sidebar"
+        style={{ width: sidebarWidth }}
+      >
         <div className="flex h-14 items-center gap-2 border-b border-sidebar-border px-4">
           <button
             type="button"

package/admin/src/embed/index.tsx

@@ -36,6 +36,7 @@
 
 import { useConvex } from "convex/react";
 import { useMemo } from "react";
+import { cn } from "../lib/cn";
 import { SettingsConfigProvider } from "../contexts/SettingsConfigContext";
 import {
   AuthProvider,
@@ -46,7 +47,6 @@ import {
 import { ThemeProvider } from "../contexts/ThemeContext";
 import { RouteGuard } from "../components/RouteGuard";
 import { resolveAdminConfig } from "../lib/admin-config";
-import { cn } from "../lib/cn";
 import type { CmsAdminProps, CmsAdminAuthConfig } from "./types";
 import { ApiProvider } from "./contexts/ApiContext";
 import {
@@ -129,6 +129,7 @@ export function CmsAdmin({
   basePath = "/admin",
   className,
   themeMode = "isolated",
+  darkModeControl = "independent",
   initialRoute = "dashboard",
   onNavigate,
 }: CmsAdminProps & {
@@ -165,7 +166,7 @@ export function CmsAdmin({
   return (
     <div className={cn("h-full", className)} data-cms-admin={themeMode}>
       <ApiProvider api={api}>
-        <ThemeProvider>
+        <ThemeProvider themeMode={themeMode} darkModeControl={darkModeControl}>
           <SettingsConfigProvider baseConfig={adminConfig} api={settingsApi}>
             <AuthProvider
               getUser={authConfig.getUser}

package/admin/src/embed/types.ts

@@ -26,4 +26,10 @@ export interface CmsAdminProps {
    * - 'inherit': Admin inherits parent app's CSS variables (for shadcn apps)
    */
   themeMode?: "isolated" | "inherit";
+  /**
+   * Dark mode control behavior:
+   * - 'independent' (default): Admin has its own dark mode toggle
+   * - 'follow-parent': Admin follows parent app's dark mode (hides toggle in inherit mode)
+   */
+  darkModeControl?: "independent" | "follow-parent";
 }