convex-cms 0.0.9-alpha.7 → 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/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,
@@ -127,6 +128,8 @@ export function CmsAdmin({
   auth,
   basePath = "/admin",
   className,
+  themeMode = "isolated",
+  darkModeControl = "independent",
   initialRoute = "dashboard",
   onNavigate,
 }: CmsAdminProps & {
@@ -143,7 +146,10 @@ export function CmsAdmin({
 
   if (!convex) {
     return (
-      <div className="flex min-h-full items-center justify-center bg-background p-6">
+      <div
+        className={cn("flex h-full items-center justify-center bg-background p-6", className)}
+        data-cms-admin={themeMode}
+      >
         <div className="diff-modified max-w-lg space-y-4 rounded-lg border p-6 text-center">
           <h2 className="text-xl font-semibold text-diff-modified">
             ConvexProvider Required
@@ -158,9 +164,9 @@ export function CmsAdmin({
   }
 
   return (
-    <div className={className}>
+    <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}
@@ -173,9 +179,7 @@ export function CmsAdmin({
                 onNavigate={onNavigate}
               >
                 <RouteGuard>
-                  <div className="min-h-screen">
-                    <EmbedRouter />
-                  </div>
+                  <EmbedRouter />
                 </RouteGuard>
               </EmbedNavigationProvider>
             </AuthProvider>

package/admin/src/embed/types.ts

@@ -20,4 +20,16 @@ export interface CmsAdminProps {
   auth: CmsAdminAuthConfig;
   basePath?: string;
   className?: string;
+  /**
+   * Theme mode for CSS variable scoping:
+   * - 'isolated' (default): Admin uses its own theme, ignores parent app styles
+   * - '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";
 }