convex-cms 0.0.5-alpha.0 → 0.0.5-alpha.3

package/admin/src/contexts/BreadcrumbContext.tsx

@@ -0,0 +1,49 @@
+import { createContext, useContext, useState, useCallback, useMemo } from 'react'
+import type { ReactNode } from 'react'
+
+interface BreadcrumbContextValue {
+  overrides: Map<string, string>
+  setOverride: (path: string, label: string) => void
+  clearOverride: (path: string) => void
+}
+
+const BreadcrumbContext = createContext<BreadcrumbContextValue | null>(null)
+
+export function BreadcrumbProvider({ children }: { children: ReactNode }) {
+  const [overrides, setOverrides] = useState<Map<string, string>>(new Map())
+
+  const setOverride = useCallback((path: string, label: string) => {
+    setOverrides((prev) => {
+      const next = new Map(prev)
+      next.set(path, label)
+      return next
+    })
+  }, [])
+
+  const clearOverride = useCallback((path: string) => {
+    setOverrides((prev) => {
+      const next = new Map(prev)
+      next.delete(path)
+      return next
+    })
+  }, [])
+
+  const value = useMemo(
+    () => ({ overrides, setOverride, clearOverride }),
+    [overrides, setOverride, clearOverride]
+  )
+
+  return (
+    <BreadcrumbContext.Provider value={value}>
+      {children}
+    </BreadcrumbContext.Provider>
+  )
+}
+
+export function useBreadcrumbContext() {
+  const context = useContext(BreadcrumbContext)
+  if (!context) {
+    throw new Error('useBreadcrumbContext must be used within a BreadcrumbProvider')
+  }
+  return context
+}

package/admin/src/contexts/SettingsConfigContext.tsx

@@ -0,0 +1,57 @@
+import { useQuery } from "convex/react";
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { api } from "../../convex/_generated/api";
+import type { AdminConfig } from "~/lib/admin-config";
+import { AdminConfigProvider } from "./AdminConfigContext";
+
+type Settings = NonNullable<typeof api.settings.get._returnType>;
+
+interface SettingsConfigContextValue {
+  baseConfig: AdminConfig;
+  settings: Settings | undefined;
+}
+
+const SettingsConfigContext = createContext<SettingsConfigContextValue | null>(null);
+
+export function SettingsConfigProvider({
+  baseConfig,
+  children,
+}: {
+  baseConfig: AdminConfig;
+  children: ReactNode;
+}) {
+  const settings = useQuery(api.settings.get);
+
+  const mergedConfig = useMemo((): AdminConfig => {
+    if (!settings) return baseConfig;
+
+    return {
+      ...baseConfig,
+      navigation: {
+        ...baseConfig.navigation,
+        showMedia: baseConfig.navigation.showMedia && settings.features.mediaManagement,
+      },
+    };
+  }, [baseConfig, settings]);
+
+  const contextValue = useMemo(
+    () => ({ baseConfig, settings }),
+    [baseConfig, settings]
+  );
+
+  return (
+    <SettingsConfigContext.Provider value={contextValue}>
+      <AdminConfigProvider config={mergedConfig}>
+        {children}
+      </AdminConfigProvider>
+    </SettingsConfigContext.Provider>
+  );
+}
+
+export function useSettingsConfig(): SettingsConfigContextValue {
+  const ctx = useContext(SettingsConfigContext);
+  if (!ctx) {
+    throw new Error("useSettingsConfig must be used within SettingsConfigProvider");
+  }
+  return ctx;
+}

package/admin/src/contexts/ThemeContext.tsx

@@ -0,0 +1,91 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  useCallback,
+  type ReactNode,
+} from 'react'
+
+type Theme = 'light' | 'dark' | 'system'
+
+interface ThemeContextValue {
+  theme: Theme
+  resolvedTheme: 'light' | 'dark'
+  setTheme: (theme: Theme) => void
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null)
+
+const STORAGE_KEY = 'convex-cms-theme'
+
+function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined') return 'light'
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+
+function getStoredTheme(): Theme {
+  if (typeof window === 'undefined') return 'system'
+  const stored = localStorage.getItem(STORAGE_KEY)
+  if (stored === 'light' || stored === 'dark' || stored === 'system') {
+    return stored
+  }
+  return 'system'
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setThemeState] = useState<Theme>(() => getStoredTheme())
+  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>(() => {
+    const stored = getStoredTheme()
+    return stored === 'system' ? getSystemTheme() : stored
+  })
+
+  const applyTheme = useCallback((newTheme: Theme) => {
+    const resolved = newTheme === 'system' ? getSystemTheme() : newTheme
+    setResolvedTheme(resolved)
+
+    const root = document.documentElement
+    root.classList.remove('light', 'dark')
+    root.classList.add(resolved)
+  }, [])
+
+  const setTheme = useCallback(
+    (newTheme: Theme) => {
+      setThemeState(newTheme)
+      localStorage.setItem(STORAGE_KEY, newTheme)
+      applyTheme(newTheme)
+    },
+    [applyTheme]
+  )
+
+  useEffect(() => {
+    applyTheme(theme)
+  }, [theme, applyTheme])
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+
+    const handleChange = () => {
+      if (theme === 'system') {
+        applyTheme('system')
+      }
+    }
+
+    mediaQuery.addEventListener('change', handleChange)
+    return () => mediaQuery.removeEventListener('change', handleChange)
+  }, [theme, applyTheme])
+
+  return (
+    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  )
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext)
+  if (!context) {
+    throw new Error('useTheme must be used within a ThemeProvider')
+  }
+  return context
+}

package/admin/src/contexts/index.ts

@@ -0,0 +1,20 @@
+export {
+  AuthProvider,
+  useAuth,
+  type AuthUser,
+  type AuthState,
+  type AuthContextValue,
+  type AuthProviderProps,
+  type GetUserHook,
+  type GetUserRoleHook,
+  type LogoutHook,
+  type PermissionCheck,
+} from './AuthContext';
+
+export { ThemeProvider, useTheme } from './ThemeContext';
+
+export { AdminConfigProvider, useAdminConfig } from './AdminConfigContext';
+
+export { SettingsConfigProvider, useSettingsConfig } from './SettingsConfigContext';
+
+export { BreadcrumbProvider, useBreadcrumbContext } from './BreadcrumbContext';

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

@@ -0,0 +1,103 @@
+/**
+ * Embed Header
+ *
+ * A simplified header for the embedded admin without router dependencies.
+ */
+
+import { ChevronLeft, Bell, HelpCircle, User, LogOut, Moon, Sun } from "lucide-react";
+import { useAdminConfig, useTheme, useAuth } from "../../contexts";
+import { useEmbedNavigation } from "../navigation";
+
+export function EmbedHeader() {
+  const { goBack, canGoBack, currentRoute } = useEmbedNavigation();
+  const { branding: _branding } = useAdminConfig();
+  const { theme, setTheme } = useTheme();
+  const { user, logout, isAuthenticated } = useAuth();
+
+  const routeTitles: Record<string, string> = {
+    dashboard: "Dashboard",
+    content: "Content",
+    "content-types": "Content Types",
+    media: "Media Library",
+    taxonomies: "Taxonomies",
+    settings: "Settings",
+    trash: "Trash",
+    entries: "Entries",
+  };
+
+  const title = routeTitles[currentRoute.route] || "Dashboard";
+
+  return (
+    <header className="sticky top-0 z-40 flex h-14 items-center justify-between border-b border-border bg-background px-6">
+      <div className="flex items-center gap-4">
+        {canGoBack && (
+          <button
+            type="button"
+            onClick={goBack}
+            className="flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground"
+          >
+            <ChevronLeft className="size-4" />
+            Back
+          </button>
+        )}
+        <h1 className="text-lg font-semibold text-foreground">{title}</h1>
+      </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>
+
+        <button
+          type="button"
+          className="flex size-9 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground"
+          title="Notifications"
+        >
+          <Bell className="size-5" />
+        </button>
+
+        <button
+          type="button"
+          className="flex size-9 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground"
+          title="Help"
+        >
+          <HelpCircle className="size-5" />
+        </button>
+
+        {isAuthenticated && user && (
+          <div className="ml-2 flex items-center gap-2 border-l border-border pl-4">
+            <div className="flex size-8 items-center justify-center rounded-full bg-primary text-primary-foreground">
+              {user.avatarUrl ? (
+                <img
+                  src={user.avatarUrl}
+                  alt={user.name || "User"}
+                  className="size-full rounded-full object-cover"
+                />
+              ) : (
+                <User className="size-4" />
+              )}
+            </div>
+            {user.name && (
+              <span className="text-sm font-medium text-foreground">
+                {user.name}
+              </span>
+            )}
+            <button
+              type="button"
+              onClick={() => logout()}
+              className="flex size-8 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground"
+              title="Log out"
+            >
+              <LogOut className="size-4" />
+            </button>
+          </div>
+        )}
+      </div>
+    </header>
+  );
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Embed Layout
+ *
+ * A router-agnostic layout for the embedded admin that uses
+ * EmbedSidebar instead of the router-dependent Sidebar.
+ */
+
+import type { ReactNode } from "react";
+import { EmbedSidebar } from "./EmbedSidebar";
+import { EmbedHeader } from "./EmbedHeader";
+import { useAdminConfig } from "../../contexts";
+
+interface EmbedLayoutProps {
+  children: ReactNode;
+}
+
+export function EmbedLayout({ children }: EmbedLayoutProps) {
+  const { layout } = useAdminConfig();
+
+  return (
+    <div className="flex min-h-screen bg-background">
+      <EmbedSidebar />
+      <div className="flex flex-1 flex-col" style={{ marginLeft: layout.sidebarWidth }}>
+        <EmbedHeader />
+        <main className="flex-1 overflow-auto p-6">{children}</main>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,119 @@
+/**
+ * Embed Sidebar
+ *
+ * A router-agnostic version of the Sidebar component that uses
+ * the EmbedNavigation context for navigation instead of TanStack Router.
+ */
+
+import { Layers } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { useAdminConfig } from "../../contexts";
+import { Icon } from "../../lib/icons";
+import { useEmbedNavigation, type EmbedRoute } from "../navigation";
+import type { NavItem } from "../../lib/admin-config";
+
+function pathToRoute(path: string): EmbedRoute {
+  if (path === "/" || path === "") return "dashboard";
+  if (path.startsWith("/content-types")) return "content-types";
+  if (path.startsWith("/entries")) return "entries";
+  if (path.startsWith("/content")) return "content";
+  if (path.startsWith("/media")) return "media";
+  if (path.startsWith("/taxonomies")) return "taxonomies";
+  if (path.startsWith("/settings")) return "settings";
+  if (path.startsWith("/trash")) return "trash";
+  return "dashboard";
+}
+
+export function EmbedSidebar() {
+  const { currentPath, navigate } = useEmbedNavigation();
+  const config = useAdminConfig();
+  const { navItems, branding, layout } = config;
+
+  const isActive = (path: string, exact?: boolean) => {
+    const normalizedCurrent = currentPath.replace(/^\/admin/, "");
+    if (exact) {
+      return normalizedCurrent === path;
+    }
+    return normalizedCurrent.startsWith(path);
+  };
+
+  const handleNavClick = (item: NavItem) => {
+    const route = pathToRoute(item.path);
+    navigate(route);
+  };
+
+  const renderNavItem = (item: NavItem) => (
+    <button
+      key={item.id}
+      type="button"
+      onClick={() => handleNavClick(item)}
+      className={cn(
+        "flex w-full items-center gap-3 rounded-md px-2 py-2 text-left text-sm font-medium transition-colors",
+        isActive(item.path, item.exact)
+          ? "bg-sidebar-accent text-sidebar-accent-foreground"
+          : "text-sidebar-foreground hover:bg-sidebar-accent/50 hover:text-sidebar-accent-foreground"
+      )}
+    >
+      <Icon name={item.icon} className="size-5" />
+      <span className="flex-1">{item.label}</span>
+      {item.badge && (
+        <span className="rounded-full bg-sidebar-primary px-2 py-0.5 text-xs text-sidebar-primary-foreground">
+          {item.badge}
+        </span>
+      )}
+    </button>
+  );
+
+  const sidebarWidth = layout.sidebarWidth;
+
+  return (
+    <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"
+          onClick={() => navigate("dashboard")}
+          className="flex items-center gap-2 font-semibold text-sidebar-foreground"
+        >
+          {branding.logo ? (
+            <img src={branding.logo} alt={branding.appName} className="size-8" />
+          ) : (
+            <div className="flex size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+              <Layers className="size-4" />
+            </div>
+          )}
+          <span className="text-base">{branding.appName}</span>
+        </button>
+      </div>
+
+      <nav className="flex-1 space-y-6 overflow-y-auto p-4">
+        {navItems.main.length > 0 && (
+          <div className="space-y-1">
+            <span className="px-2 text-xs font-medium uppercase tracking-wider text-sidebar-foreground/60">
+              Main
+            </span>
+            <div className="space-y-1 pt-2">{navItems.main.map(renderNavItem)}</div>
+          </div>
+        )}
+
+        {navItems.config.length > 0 && (
+          <div className="space-y-1">
+            <span className="px-2 text-xs font-medium uppercase tracking-wider text-sidebar-foreground/60">
+              Configuration
+            </span>
+            <div className="space-y-1 pt-2">{navItems.config.map(renderNavItem)}</div>
+          </div>
+        )}
+      </nav>
+
+      <div className="border-t border-sidebar-border p-4">
+        <div className="flex items-center justify-between text-xs text-sidebar-foreground/60">
+          <span>Version</span>
+          <span className="font-mono">0.1.0</span>
+        </div>
+      </div>
+    </aside>
+  );
+}

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

@@ -0,0 +1,3 @@
+export { EmbedSidebar } from "./EmbedSidebar";
+export { EmbedHeader } from "./EmbedHeader";
+export { EmbedLayout } from "./EmbedLayout";

package/admin/src/embed/contexts/ApiContext.tsx

@@ -0,0 +1,32 @@
+/**
+ * Embed API Context
+ *
+ * Provides the Convex API to embedded CMS admin pages.
+ * The API structure matches the namespaced exports from defineAdminAPI,
+ * allowing shared page components to work with the generated api object.
+ */
+
+import { createContext, useContext, type ReactNode } from "react";
+import { api } from "../../../convex/_generated/api";
+
+export type CmsAdminApi = typeof api["admin"];
+
+const ApiContext = createContext<CmsAdminApi | null>(null);
+
+export function ApiProvider({
+  api,
+  children,
+}: {
+  api: CmsAdminApi;
+  children: ReactNode;
+}) {
+  return <ApiContext.Provider value={api}>{children}</ApiContext.Provider>;
+}
+
+export function useApi(): CmsAdminApi {
+  const api = useContext(ApiContext);
+  if (!api) {
+    throw new Error("useApi must be used within ApiProvider");
+  }
+  return api;
+}

package/admin/src/embed/index.tsx

@@ -0,0 +1,184 @@
+/**
+ * Embeddable CMS Admin Component
+ *
+ * Use this component to embed the CMS admin UI into your existing React app.
+ * Provides a fully functional admin interface with router-agnostic navigation.
+ *
+ * @example
+ * ```tsx
+ * import { CmsAdmin } from "@convex-cms/admin/embed";
+ *
+ * function App() {
+ *   return (
+ *     <CmsAdmin
+ *       convexUrl="https://your-deployment.convex.cloud"
+ *       auth={{
+ *         getUser: () => currentUser,
+ *         getUserRole: (userId) => userRoles[userId] ?? null,
+ *         onLogout: () => signOut(),
+ *       }}
+ *       config={{
+ *         branding: { appName: "My CMS" },
+ *         navigation: { showTaxonomies: false },
+ *       }}
+ *       basePath="/admin"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+import { useMemo, type ReactNode } from "react";
+import { AdminConfigProvider } from "../contexts/AdminConfigContext";
+import {
+  AuthProvider,
+  type GetUserHook,
+  type GetUserRoleHook,
+  type LogoutHook,
+} from "../contexts/AuthContext";
+import { ThemeProvider } from "../contexts/ThemeContext";
+import { RouteGuard } from "../components/RouteGuard";
+import { resolveAdminConfig } from "../lib/admin-config";
+import type { CmsAdminProps, CmsAdminAuthConfig } from "./types";
+import { ApiProvider } from "./contexts/ApiContext";
+import {
+  EmbedNavigationProvider,
+  useEmbedNavigation,
+  type EmbedRoute,
+} from "./navigation";
+import { EmbedLayout } from "./components/EmbedLayout";
+import {
+  EmbedDashboard,
+  EmbedContent,
+  EmbedContentTypes,
+  EmbedMedia,
+  EmbedSettings,
+  EmbedTrash,
+  EmbedTaxonomies,
+} from "./pages";
+
+function adaptAuthConfig(auth: CmsAdminAuthConfig): {
+  getUser: GetUserHook;
+  getUserRole: GetUserRoleHook;
+  onLogout: LogoutHook;
+} {
+  return {
+    getUser: auth.getUser,
+    getUserRole: ({ userId }) => auth.getUserRole(userId),
+    onLogout: auth.onLogout ?? (() => {}),
+  };
+}
+
+function ConvexProviderWrapper({
+  convexUrl,
+  children,
+}: {
+  convexUrl: string;
+  children: ReactNode;
+}) {
+  const convex = useMemo(() => {
+    if (!convexUrl) return null;
+    return new ConvexReactClient(convexUrl);
+  }, [convexUrl]);
+
+  if (!convex) {
+    return (
+      <div className="flex min-h-full items-center justify-center bg-background p-6">
+        <div className="max-w-lg space-y-4 rounded-lg border border-amber-200 bg-amber-50 p-6 text-center">
+          <h2 className="text-xl font-semibold text-amber-900">
+            Convex Configuration Required
+          </h2>
+          <p className="text-sm text-amber-800">
+            Please provide a valid convexUrl prop to the CmsAdmin component.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
+}
+
+function EmbedRouter() {
+  const { currentRoute } = useEmbedNavigation();
+
+  const renderPage = () => {
+    switch (currentRoute.route) {
+      case "dashboard":
+        return <EmbedDashboard />;
+      case "content":
+        return <EmbedContent />;
+      case "content-types":
+        return <EmbedContentTypes />;
+      case "media":
+        return <EmbedMedia />;
+      case "settings":
+        return <EmbedSettings />;
+      case "taxonomies":
+        return <EmbedTaxonomies />;
+      case "trash":
+        return <EmbedTrash />;
+      case "entries":
+        return <EmbedContent />;
+      default:
+        return <EmbedDashboard />;
+    }
+  };
+
+  return <EmbedLayout>{renderPage()}</EmbedLayout>;
+}
+
+export function CmsAdmin({
+  api,
+  convexUrl,
+  config,
+  auth,
+  basePath = "/admin",
+  className,
+  initialRoute = "dashboard",
+  onNavigate,
+}: CmsAdminProps & {
+  initialRoute?: EmbedRoute;
+  onNavigate?: (path: string, params: Record<string, string>) => void;
+}) {
+  const adminConfig = useMemo(() => resolveAdminConfig(config), [config]);
+  const authConfig = useMemo(() => adaptAuthConfig(auth), [auth]);
+
+  return (
+    <div className={className}>
+      <ApiProvider api={api}>
+        <ThemeProvider>
+          <AdminConfigProvider config={adminConfig}>
+            <ConvexProviderWrapper convexUrl={convexUrl}>
+              <AuthProvider
+                getUser={authConfig.getUser}
+                getUserRole={authConfig.getUserRole}
+                onLogout={authConfig.onLogout}
+              >
+                <EmbedNavigationProvider
+                  initialRoute={initialRoute}
+                  basePath={basePath}
+                  onNavigate={onNavigate}
+                >
+                  <RouteGuard>
+                    <div className="min-h-screen">
+                      <EmbedRouter />
+                    </div>
+                  </RouteGuard>
+                </EmbedNavigationProvider>
+              </AuthProvider>
+            </ConvexProviderWrapper>
+          </AdminConfigProvider>
+        </ThemeProvider>
+      </ApiProvider>
+    </div>
+  );
+}
+
+export type { CmsAdminProps, CmsAdminAuthConfig, CmsAdminUser } from "./types";
+export type { CmsAdminApi } from "./contexts/ApiContext";
+export type { AdminConfig, NavItem } from "../lib/admin-config";
+export { resolveAdminConfig, defineAdminConfig } from "../lib/admin-config";
+export type { EmbedRoute, EmbedRouteState } from "./navigation";
+export { useEmbedNavigation, useEmbedParams, useEmbedRoute } from "./navigation";