convex-cms 0.0.3 → 0.0.5-alpha.2

package/admin/src/lib/admin-config.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+
+export interface NavItem {
+  id: string;
+  path: string;
+  label: string;
+  icon: string;
+  visible?: boolean;
+  section: "main" | "config";
+  badge?: string;
+  exact?: boolean;
+}
+
+const navItemSchema = z.object({
+  id: z.string(),
+  path: z.string(),
+  label: z.string(),
+  icon: z.string(),
+  visible: z.boolean().default(true),
+  section: z.enum(["main", "config"]).default("main"),
+  badge: z.string().optional(),
+  exact: z.boolean().optional(),
+}) satisfies z.ZodType<NavItem>;
+
+const brandingSchema = z.object({
+  appName: z.string().default("Convex CMS"),
+  logo: z.string().optional(),
+  favicon: z.string().optional(),
+});
+
+const layoutSchema = z.object({
+  sidebarWidth: z.number().min(200).max(400).default(256),
+  sidebarCollapsible: z.boolean().default(false),
+});
+
+const navigationSchema = z.object({
+  showDashboard: z.boolean().default(true),
+  showContent: z.boolean().default(true),
+  showMedia: z.boolean().default(true),
+  showTaxonomies: z.boolean().default(true),
+  showContentTypes: z.boolean().default(true),
+  showTrash: z.boolean().default(true),
+  showSettings: z.boolean().default(true),
+  customItems: z.array(navItemSchema).default([]),
+});
+
+const themeSchema = z.object({
+  mode: z.enum(["light", "dark", "system"]).default("system"),
+  allowModeSwitch: z.boolean().default(true),
+  tokens: z.record(z.string(), z.string()).optional(),
+});
+
+export const adminConfigSchema = z.object({
+  branding: brandingSchema.default(() => brandingSchema.parse({})),
+  layout: layoutSchema.default(() => layoutSchema.parse({})),
+  navigation: navigationSchema.default(() => navigationSchema.parse({})),
+  theme: themeSchema.default(() => themeSchema.parse({})),
+});
+
+export type AdminConfig = z.infer<typeof adminConfigSchema>;
+
+export const DEFAULT_NAV_ITEMS: NavItem[] = [
+  {
+    id: "dashboard",
+    path: "/",
+    label: "Dashboard",
+    icon: "LayoutDashboard",
+    section: "main",
+    exact: true,
+  },
+  { id: "content", path: "/content", label: "Content", icon: "FileText", section: "main" },
+  { id: "media", path: "/media", label: "Media", icon: "Image", section: "main" },
+  { id: "taxonomies", path: "/taxonomies", label: "Taxonomies", icon: "Tags", section: "main" },
+  {
+    id: "content-types",
+    path: "/content-types",
+    label: "Content Types",
+    icon: "Layers",
+    section: "config",
+  },
+  { id: "trash", path: "/trash", label: "Trash", icon: "Trash2", section: "config" },
+  { id: "settings", path: "/settings", label: "Settings", icon: "Settings", section: "config" },
+];
+
+export function resolveAdminConfig(input?: Partial<AdminConfig>): AdminConfig {
+  return adminConfigSchema.parse(input ?? {});
+}
+
+export function getVisibleNavItems(config: AdminConfig): { main: NavItem[]; config: NavItem[] } {
+  const visibilityMap: Record<string, boolean> = {
+    dashboard: config.navigation.showDashboard,
+    content: config.navigation.showContent,
+    media: config.navigation.showMedia,
+    taxonomies: config.navigation.showTaxonomies,
+    "content-types": config.navigation.showContentTypes,
+    trash: config.navigation.showTrash,
+    settings: config.navigation.showSettings,
+  };
+
+  const filtered = DEFAULT_NAV_ITEMS.filter((item) => visibilityMap[item.id] !== false);
+  const allItems = [...filtered, ...config.navigation.customItems.filter((i) => i.visible !== false)];
+
+  return {
+    main: allItems.filter((i) => i.section === "main"),
+    config: allItems.filter((i) => i.section === "config"),
+  };
+}
+
+export function defineAdminConfig(config: Partial<AdminConfig>): Partial<AdminConfig> {
+  return config;
+}

package/admin/src/lib/cn.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/admin/src/lib/config.server.ts

@@ -0,0 +1,56 @@
+import { createServerFn } from "@tanstack/react-start";
+import type { AdminConfig } from "./admin-config";
+import { loadAdminConfig } from "./loadAdminConfig";
+
+/**
+ * Server function to retrieve runtime configuration.
+ *
+ * Configuration is loaded from (in order of precedence):
+ * 1. Environment variable CONVEX_CMS_ADMIN_CONFIG (JSON string)
+ * 2. Config file (cms-admin.config.ts/js/mjs) in project root
+ *
+ * This code-first approach allows configuration to be:
+ * - Committed to git and reviewed in PRs
+ * - Type-safe with TypeScript
+ * - Consistent across dev/staging/production
+ *
+ * @example
+ * // cms-admin.config.ts
+ * import { defineAdminConfig } from "convex-cms";
+ *
+ * export default defineAdminConfig({
+ *   branding: { appName: "My CMS" },
+ *   navigation: { showTaxonomies: false },
+ * });
+ */
+export const getServerConfig = createServerFn({ method: "GET" }).handler(
+	async () => {
+		let adminConfig: Partial<AdminConfig> = {};
+
+		const configEnv = process.env.CONVEX_CMS_ADMIN_CONFIG;
+		if (configEnv) {
+			try {
+				adminConfig = JSON.parse(configEnv) as Partial<AdminConfig>;
+			} catch {
+				console.warn("Failed to parse CONVEX_CMS_ADMIN_CONFIG as JSON");
+			}
+		} else {
+			try {
+				adminConfig = await loadAdminConfig();
+			} catch (error) {
+				console.warn("Failed to load admin config from file:", error);
+			}
+		}
+
+		return {
+			convexUrl: process.env.CONVEX_URL || process.env.VITE_CONVEX_URL || "",
+			authMode: process.env.AUTH_MODE || process.env.VITE_AUTH_MODE || "demo",
+			adminConfig,
+		};
+	},
+);
+
+/**
+ * Type for the server config response.
+ */
+export type ServerConfig = Awaited<ReturnType<typeof getServerConfig>>;

package/admin/src/lib/convex.ts

@@ -0,0 +1,26 @@
+/**
+ * Convex client utilities for the Admin UI
+ *
+ * This module provides helpers for interacting with the Convex CMS component
+ * from within the admin application.
+ *
+ * NOTE: The Convex API types are generated when running `npx convex dev`.
+ * Until then, TypeScript may show import errors which can be ignored.
+ */
+
+import { useQuery, useMutation } from "convex/react";
+
+/**
+ * Re-export Convex hooks for convenience
+ */
+export { useQuery, useMutation };
+
+/**
+ * Access to the generated Convex API
+ * This will be available once `npx convex dev` is run
+ *
+ * Usage:
+ *   import { api } from '~/lib/convex'
+ *   const contentTypes = useQuery(api.convexCms.contentEntries.get, { id: '...' })
+ */
+export { api } from "../../convex/_generated/api";

package/admin/src/lib/embed-adapter.ts

@@ -0,0 +1,80 @@
+/**
+ * Embed Navigation Adapter
+ *
+ * Implements the AdminNavigation interface for the embed navigation system,
+ * allowing shared page components to work with embedded CMS.
+ */
+
+import { useMemo, useCallback } from "react";
+import type { AdminNavigation } from "./navigation";
+import type { EmbedNavigationContextValue, EmbedRoute } from "../embed/navigation";
+
+function pathToRoute(path: string): { route: EmbedRoute; params: Record<string, string> } {
+  if (path === "/" || path === "") {
+    return { route: "dashboard", params: {} };
+  }
+  if (path === "/content") {
+    return { route: "content", params: {} };
+  }
+  if (path === "/content-types") {
+    return { route: "content-types", params: {} };
+  }
+  if (path === "/media") {
+    return { route: "media", params: {} };
+  }
+  if (path === "/taxonomies") {
+    return { route: "taxonomies", params: {} };
+  }
+  if (path === "/settings") {
+    return { route: "settings", params: {} };
+  }
+  if (path === "/trash") {
+    return { route: "trash", params: {} };
+  }
+
+  const entryMatch = path.match(/^\/entries\/([^/]+)$/);
+  if (entryMatch) {
+    return { route: "entries", params: { entryId: entryMatch[1] } };
+  }
+
+  const typeMatch = path.match(/^\/entries\/type\/([^/]+)$/);
+  if (typeMatch) {
+    return { route: "entries", params: { contentTypeId: typeMatch[1] } };
+  }
+
+  const newEntryMatch = path.match(/^\/entries\/new\/([^/]+)$/);
+  if (newEntryMatch) {
+    return { route: "entries", params: { contentTypeId: newEntryMatch[1], action: "new" } };
+  }
+
+  return { route: "dashboard", params: {} };
+}
+
+export function useEmbedAdapter(
+  embedNav: EmbedNavigationContextValue
+): AdminNavigation {
+  const handleNavigate = useCallback(
+    (path: string, params?: Record<string, string>) => {
+      const resolved = pathToRoute(path);
+      const mergedParams = { ...resolved.params, ...params };
+      embedNav.navigate(resolved.route, mergedParams);
+    },
+    [embedNav]
+  );
+
+  return useMemo(
+    () => ({
+      navigate: handleNavigate,
+      currentRoute: embedNav.currentPath,
+      params: embedNav.currentRoute.params,
+      canGoBack: embedNav.canGoBack,
+      goBack: embedNav.goBack,
+      navigateToEntry: embedNav.navigateToEntry,
+      navigateToContentType: embedNav.navigateToContentType,
+      navigateToNewEntry: (contentTypeId: string) => {
+        embedNav.navigate("entries", { contentTypeId, action: "new" });
+      },
+    }),
+    [handleNavigate, embedNav]
+  );
+}

package/admin/src/lib/icons.tsx

@@ -0,0 +1,96 @@
+import {
+  LayoutDashboard,
+  FileText,
+  Image,
+  Layers,
+  Tags,
+  FileCode,
+  Settings,
+  Trash2,
+  type LucideIcon,
+  HelpCircle,
+  Home,
+  User,
+  Bell,
+  Lock,
+  Globe,
+  Calendar,
+  Clock,
+  Link,
+  Hash,
+  ToggleLeft,
+  ChevronDown,
+  CheckSquare,
+  Braces,
+  Folder,
+  MapPin,
+  DollarSign,
+  Mail,
+  Phone,
+  Package,
+  Star,
+  Heart,
+  Flag,
+  Bookmark,
+  Archive,
+  Edit,
+  Eye,
+  AlertCircle,
+} from "lucide-react";
+
+const iconRegistry: Record<string, LucideIcon> = {
+  LayoutDashboard,
+  FileText,
+  Image,
+  Layers,
+  Tags,
+  FileCode,
+  Settings,
+  Trash2,
+  HelpCircle,
+  Home,
+  User,
+  Bell,
+  Lock,
+  Globe,
+  Calendar,
+  Clock,
+  Link,
+  Hash,
+  ToggleLeft,
+  ChevronDown,
+  CheckSquare,
+  Braces,
+  Folder,
+  MapPin,
+  DollarSign,
+  Mail,
+  Phone,
+  Package,
+  Star,
+  Heart,
+  Flag,
+  Bookmark,
+  Archive,
+  Edit,
+  Eye,
+  AlertCircle,
+};
+
+export function getIcon(name: string): LucideIcon | undefined {
+  return iconRegistry[name];
+}
+
+export function Icon({
+  name,
+  className = "size-5",
+}: {
+  name: string;
+  className?: string;
+}) {
+  const IconComponent = iconRegistry[name];
+  if (!IconComponent) {
+    return null;
+  }
+  return <IconComponent className={className} />;
+}

package/admin/src/lib/loadAdminConfig.ts

@@ -0,0 +1,92 @@
+/**
+ * Admin Config File Loader
+ *
+ * Loads admin configuration from a config file in the user's project directory.
+ * Similar to how Vite loads vite.config.ts, this enables code-first configuration
+ * that can be committed to git and reviewed in PRs.
+ *
+ * Supported file names (in order of precedence):
+ * - cms-admin.config.ts
+ * - cms-admin.config.js
+ * - cms-admin.config.mjs
+ *
+ * @example
+ * // cms-admin.config.ts
+ * import { defineAdminConfig } from "convex-cms";
+ *
+ * export default defineAdminConfig({
+ *   branding: { appName: "My CMS" },
+ *   navigation: { showTaxonomies: false },
+ * });
+ */
+
+import { pathToFileURL } from "url";
+import { existsSync } from "fs";
+import { resolve, dirname } from "path";
+import type { AdminConfig } from "./admin-config";
+
+const CONFIG_FILE_NAMES = [
+	"cms-admin.config.ts",
+	"cms-admin.config.js",
+	"cms-admin.config.mjs",
+];
+
+let cachedConfig: Partial<AdminConfig> | null = null;
+let cachedConfigPath: string | null = null;
+
+function findProjectRoot(startDir: string): string {
+	let dir = startDir;
+	while (dir !== dirname(dir)) {
+		if (existsSync(resolve(dir, "package.json"))) {
+			return dir;
+		}
+		dir = dirname(dir);
+	}
+	return startDir;
+}
+
+export async function loadAdminConfig(
+	cwd?: string,
+): Promise<Partial<AdminConfig>> {
+	const projectRoot = cwd ?? findProjectRoot(process.cwd());
+
+	for (const fileName of CONFIG_FILE_NAMES) {
+		const configPath = resolve(projectRoot, fileName);
+		if (existsSync(configPath)) {
+			if (cachedConfig && cachedConfigPath === configPath) {
+				return cachedConfig;
+			}
+
+			try {
+				const configUrl = pathToFileURL(configPath).href;
+				let loadedConfig: Partial<AdminConfig>;
+
+				if (configPath.endsWith(".ts")) {
+					const importPath = `${configUrl}?ts=${Date.now()}`;
+					const configModule = await import(importPath);
+					loadedConfig = configModule.default ?? configModule;
+				} else {
+					const configModule = await import(configUrl);
+					loadedConfig = configModule.default ?? configModule;
+				}
+
+				cachedConfig = loadedConfig;
+				cachedConfigPath = configPath;
+				return loadedConfig;
+			} catch (error) {
+				console.warn(`Failed to load ${fileName}:`, error);
+			}
+		}
+	}
+
+	return {};
+}
+
+export function clearConfigCache(): void {
+	cachedConfig = null;
+	cachedConfigPath = null;
+}
+
+export function getConfigPath(): string | null {
+	return cachedConfigPath;
+}

package/admin/src/lib/motion.ts

@@ -0,0 +1,29 @@
+export const motion = {
+  fast: 'duration-100 ease-out',
+  base: 'duration-200 ease-out',
+  smooth: 'duration-300 ease-out',
+  spring: 'duration-300 ease-[cubic-bezier(0.34,1.56,0.64,1)]',
+} as const
+
+export const transitions = {
+  fadeIn: 'animate-in fade-in',
+  fadeOut: 'animate-out fade-out',
+  slideInFromTop: 'animate-in slide-in-from-top-2',
+  slideInFromBottom: 'animate-in slide-in-from-bottom-2',
+  slideInFromLeft: 'animate-in slide-in-from-left-2',
+  slideInFromRight: 'animate-in slide-in-from-right-2',
+  zoomIn: 'animate-in zoom-in-95',
+  zoomOut: 'animate-out zoom-out-95',
+} as const
+
+export const hover = {
+  lift: 'hover:-translate-y-0.5 hover:shadow-md',
+  glow: 'hover:shadow-[0_0_15px_-3px_var(--color-primary)]',
+  scale: 'hover:scale-[1.02]',
+  brighten: 'hover:brightness-110',
+} as const
+
+export const focus = {
+  ring: 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+  subtle: 'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+} as const

package/admin/src/lib/navigation.ts

@@ -0,0 +1,43 @@
+/**
+ * Unified Navigation Interface
+ *
+ * Provides router-agnostic navigation that works with both TanStack Router (CLI)
+ * and the custom embed navigation system.
+ */
+
+export const ROUTES = {
+  DASHBOARD: "/",
+  CONTENT: "/content",
+  CONTENT_TYPES: "/content-types",
+  MEDIA: "/media",
+  SETTINGS: "/settings",
+  TRASH: "/trash",
+  TAXONOMIES: "/taxonomies",
+  ENTRY: "/entries/:entryId",
+  ENTRIES_BY_TYPE: "/entries/type/:contentTypeId",
+  NEW_ENTRY: "/entries/new/:contentTypeId",
+} as const;
+
+export type RouteKey = keyof typeof ROUTES;
+
+export interface AdminNavigation {
+  navigate: (route: string, params?: Record<string, string>) => void;
+  currentRoute: string;
+  params: Record<string, string>;
+  canGoBack: boolean;
+  goBack: () => void;
+  navigateToEntry: (entryId: string) => void;
+  navigateToContentType: (contentTypeId: string) => void;
+  navigateToNewEntry: (contentTypeId: string) => void;
+}
+
+export function buildRoute(
+  template: string,
+  params: Record<string, string>
+): string {
+  let result = template;
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(`:${key}`, value);
+  }
+  return result;
+}

package/admin/src/lib/tanstack-adapter.ts

@@ -0,0 +1,82 @@
+/**
+ * TanStack Router Adapter
+ *
+ * Implements the AdminNavigation interface for TanStack Router,
+ * allowing shared page components to work with CLI routes.
+ */
+
+import { useNavigate, useLocation, useParams } from "@tanstack/react-router";
+import { useMemo, useCallback } from "react";
+import type { AdminNavigation } from "./navigation";
+
+export function useTanStackNavigation(): AdminNavigation {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const params = useParams({ strict: false }) as Record<string, string>;
+
+  const handleNavigate = useCallback(
+    (route: string, routeParams?: Record<string, string>) => {
+      let path = route;
+      if (routeParams) {
+        for (const [key, value] of Object.entries(routeParams)) {
+          path = path.replace(`:${key}`, value).replace(`$${key}`, value);
+        }
+      }
+      navigate({ to: path as any });
+    },
+    [navigate]
+  );
+
+  const navigateToEntry = useCallback(
+    (entryId: string) => {
+      navigate({ to: "/entries/$entryId", params: { entryId } });
+    },
+    [navigate]
+  );
+
+  const navigateToContentType = useCallback(
+    (contentTypeId: string) => {
+      navigate({
+        to: "/entries/type/$contentTypeId",
+        params: { contentTypeId },
+      });
+    },
+    [navigate]
+  );
+
+  const navigateToNewEntry = useCallback(
+    (contentTypeId: string) => {
+      navigate({
+        to: "/entries/new/$contentTypeId",
+        params: { contentTypeId },
+      });
+    },
+    [navigate]
+  );
+
+  const goBack = useCallback(() => {
+    window.history.back();
+  }, []);
+
+  return useMemo(
+    () => ({
+      navigate: handleNavigate,
+      currentRoute: location.pathname,
+      params: params ?? {},
+      canGoBack: window.history.length > 1,
+      goBack,
+      navigateToEntry,
+      navigateToContentType,
+      navigateToNewEntry,
+    }),
+    [
+      handleNavigate,
+      location.pathname,
+      params,
+      goBack,
+      navigateToEntry,
+      navigateToContentType,
+      navigateToNewEntry,
+    ]
+  );
+}