convex-cms 0.0.3 → 0.0.5-alpha.2

package/admin/src/embed/navigation.tsx

@@ -0,0 +1,202 @@
+/**
+ * Embed Navigation Context
+ *
+ * Provides router-agnostic navigation for the embedded CMS admin.
+ * This allows the embed to manage its own routing state without
+ * depending on TanStack Router or any specific router implementation.
+ */
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  type ReactNode,
+} from "react";
+
+export type EmbedRoute =
+  | "dashboard"
+  | "content"
+  | "content-types"
+  | "media"
+  | "taxonomies"
+  | "settings"
+  | "trash"
+  | "entries";
+
+export interface EmbedRouteState {
+  route: EmbedRoute;
+  params: Record<string, string>;
+}
+
+export interface EmbedNavigationContextValue {
+  currentRoute: EmbedRouteState;
+  currentPath: string;
+  navigate: (route: EmbedRoute, params?: Record<string, string>) => void;
+  navigateToEntry: (entryId: string) => void;
+  navigateToContentType: (contentTypeId: string) => void;
+  navigateToNewEntry: (contentTypeId: string) => void;
+  goBack: () => void;
+  canGoBack: boolean;
+}
+
+const EmbedNavigationContext = createContext<EmbedNavigationContextValue | null>(
+  null
+);
+
+function routeToPath(route: EmbedRoute, params: Record<string, string>): string {
+  switch (route) {
+    case "dashboard":
+      return "/";
+    case "content":
+      return "/content";
+    case "content-types":
+      return "/content-types";
+    case "media":
+      return "/media";
+    case "taxonomies":
+      return "/taxonomies";
+    case "settings":
+      return "/settings";
+    case "trash":
+      return "/trash";
+    case "entries": {
+      if (params.entryId) return `/entries/${params.entryId}`;
+      if (params.contentTypeId) return `/entries/type/${params.contentTypeId}`;
+      return "/content";
+    }
+    default:
+      return "/";
+  }
+}
+
+export interface EmbedNavigationProviderProps {
+  children: ReactNode;
+  initialRoute?: EmbedRoute;
+  basePath?: string;
+  onNavigate?: (path: string, params: Record<string, string>) => void;
+}
+
+export function EmbedNavigationProvider({
+  children,
+  initialRoute = "dashboard",
+  basePath = "/admin",
+  onNavigate,
+}: EmbedNavigationProviderProps) {
+  const [history, setHistory] = useState<EmbedRouteState[]>([
+    { route: initialRoute, params: {} },
+  ]);
+  const [currentIndex, setCurrentIndex] = useState(0);
+
+  const currentRoute = history[currentIndex];
+  const currentPath = basePath + routeToPath(currentRoute.route, currentRoute.params);
+
+  const navigate = useCallback(
+    (route: EmbedRoute, params: Record<string, string> = {}) => {
+      const newState = { route, params };
+      const newHistory = [...history.slice(0, currentIndex + 1), newState];
+      setHistory(newHistory);
+      setCurrentIndex(newHistory.length - 1);
+
+      if (onNavigate) {
+        onNavigate(routeToPath(route, params), params);
+      }
+    },
+    [history, currentIndex, onNavigate]
+  );
+
+  const navigateToEntry = useCallback(
+    (entryId: string) => {
+      navigate("entries", { entryId });
+    },
+    [navigate]
+  );
+
+  const navigateToContentType = useCallback(
+    (contentTypeId: string) => {
+      navigate("entries", { contentTypeId });
+    },
+    [navigate]
+  );
+
+  const navigateToNewEntry = useCallback(
+    (contentTypeId: string) => {
+      navigate("entries", { contentTypeId, action: "new" });
+    },
+    [navigate]
+  );
+
+  const goBack = useCallback(() => {
+    if (currentIndex > 0) {
+      setCurrentIndex(currentIndex - 1);
+    }
+  }, [currentIndex]);
+
+  const value: EmbedNavigationContextValue = {
+    currentRoute,
+    currentPath,
+    navigate,
+    navigateToEntry,
+    navigateToContentType,
+    navigateToNewEntry,
+    goBack,
+    canGoBack: currentIndex > 0,
+  };
+
+  return (
+    <EmbedNavigationContext.Provider value={value}>
+      {children}
+    </EmbedNavigationContext.Provider>
+  );
+}
+
+export function useEmbedNavigation(): EmbedNavigationContextValue {
+  const context = useContext(EmbedNavigationContext);
+  if (!context) {
+    throw new Error(
+      "useEmbedNavigation must be used within EmbedNavigationProvider"
+    );
+  }
+  return context;
+}
+
+export function useEmbedParams(): Record<string, string> {
+  const { currentRoute } = useEmbedNavigation();
+  return currentRoute.params;
+}
+
+export function useEmbedRoute(): EmbedRoute {
+  const { currentRoute } = useEmbedNavigation();
+  return currentRoute.route;
+}
+
+export interface EmbedLinkProps {
+  to: EmbedRoute;
+  params?: Record<string, string>;
+  children: ReactNode;
+  className?: string;
+  activeClassName?: string;
+}
+
+export function EmbedLink({
+  to,
+  params = {},
+  children,
+  className = "",
+  activeClassName = "",
+}: EmbedLinkProps) {
+  const { navigate, currentRoute } = useEmbedNavigation();
+
+  const isActive = currentRoute.route === to;
+  const finalClassName = `${className} ${isActive ? activeClassName : ""}`.trim();
+
+  return (
+    <button
+      type="button"
+      onClick={() => navigate(to, params)}
+      className={finalClassName}
+    >
+      {children}
+    </button>
+  );
+}

package/admin/src/embed/pages/Content.tsx

@@ -0,0 +1,19 @@
+/**
+ * Embed Content Page
+ *
+ * Thin wrapper around the shared ContentPage component.
+ * Provides embed navigation and API access.
+ */
+
+import { useApi } from "../contexts/ApiContext";
+import { useEmbedNavigation } from "../navigation";
+import { useEmbedAdapter } from "../../lib/embed-adapter";
+import { ContentPage } from "../../pages";
+
+export function EmbedContent() {
+	const api = useApi();
+	const embedNav = useEmbedNavigation();
+	const navigation = useEmbedAdapter(embedNav);
+
+	return <ContentPage api={api} navigation={navigation} />;
+}

package/admin/src/embed/pages/ContentTypes.tsx

@@ -0,0 +1,19 @@
+/**
+ * Embed Content Types Page
+ *
+ * Thin wrapper around the shared ContentTypesPage component.
+ * Provides embed navigation and API access.
+ */
+
+import { useApi } from "../contexts/ApiContext";
+import { useEmbedNavigation } from "../navigation";
+import { useEmbedAdapter } from "../../lib/embed-adapter";
+import { ContentTypesPage } from "../../pages";
+
+export function EmbedContentTypes() {
+	const api = useApi();
+	const embedNav = useEmbedNavigation();
+	const navigation = useEmbedAdapter(embedNav);
+
+	return <ContentTypesPage api={api} navigation={navigation} />;
+}

package/admin/src/embed/pages/Dashboard.tsx

@@ -0,0 +1,19 @@
+/**
+ * Embed Dashboard Page
+ *
+ * Thin wrapper around the shared DashboardPage component.
+ * Provides embed navigation and API access.
+ */
+
+import { useApi } from "../contexts/ApiContext";
+import { useEmbedNavigation } from "../navigation";
+import { useEmbedAdapter } from "../../lib/embed-adapter";
+import { DashboardPage } from "../../pages";
+
+export function EmbedDashboard() {
+	const api = useApi();
+	const embedNav = useEmbedNavigation();
+	const navigation = useEmbedAdapter(embedNav);
+
+	return <DashboardPage api={api} navigation={navigation} />;
+}

package/admin/src/embed/pages/Media.tsx

@@ -0,0 +1,19 @@
+/**
+ * Embed Media Page
+ *
+ * Thin wrapper around the shared MediaPage component.
+ * Provides embed navigation and API access.
+ */
+
+import { useApi } from "../contexts/ApiContext";
+import { useEmbedNavigation } from "../navigation";
+import { useEmbedAdapter } from "../../lib/embed-adapter";
+import { MediaPage } from "../../pages";
+
+export function EmbedMedia() {
+	const api = useApi();
+	const embedNav = useEmbedNavigation();
+	const navigation = useEmbedAdapter(embedNav);
+
+	return <MediaPage api={api} navigation={navigation} />;
+}

package/admin/src/embed/pages/Settings.tsx

@@ -0,0 +1,22 @@
+/**
+ * Embed Settings Page
+ *
+ * Thin wrapper around the shared SettingsPage component.
+ * Provides embed navigation and API access.
+ *
+ * Note: Requires the settings namespace to be exported from defineAdminAPI.
+ * This feature is currently in development.
+ */
+
+import { useApi } from "../contexts/ApiContext";
+import { useEmbedNavigation } from "../navigation";
+import { useEmbedAdapter } from "../../lib/embed-adapter";
+import { SettingsPage, type SettingsPageProps } from "../../pages";
+
+export function EmbedSettings() {
+	const api = useApi();
+	const embedNav = useEmbedNavigation();
+	const navigation = useEmbedAdapter(embedNav);
+
+	return <SettingsPage api={api as SettingsPageProps["api"]} navigation={navigation} />;
+}

package/admin/src/embed/pages/Taxonomies.tsx

@@ -0,0 +1,22 @@
+/**
+ * Embed Taxonomies Page
+ *
+ * Thin wrapper around the shared TaxonomiesPage component.
+ * Provides embed navigation and API access.
+ *
+ * Note: Requires the taxonomies namespace to be exported from defineAdminAPI.
+ * This feature is currently in development.
+ */
+
+import { useApi } from "../contexts/ApiContext";
+import { useEmbedNavigation } from "../navigation";
+import { useEmbedAdapter } from "../../lib/embed-adapter";
+import { TaxonomiesPage, type TaxonomiesPageProps } from "../../pages";
+
+export function EmbedTaxonomies() {
+	const api = useApi();
+	const embedNav = useEmbedNavigation();
+	const navigation = useEmbedAdapter(embedNav);
+
+	return <TaxonomiesPage api={api as TaxonomiesPageProps["api"]} navigation={navigation} />;
+}

package/admin/src/embed/pages/Trash.tsx

@@ -0,0 +1,22 @@
+/**
+ * Embed Trash Page
+ *
+ * Thin wrapper around the shared TrashPage component.
+ * Provides embed navigation and API access.
+ *
+ * Note: Requires the trash and bulkOperations namespaces to be exported
+ * from defineAdminAPI. This feature is currently in development.
+ */
+
+import { useApi } from "../contexts/ApiContext";
+import { useEmbedNavigation } from "../navigation";
+import { useEmbedAdapter } from "../../lib/embed-adapter";
+import { TrashPage, type TrashPageProps } from "../../pages";
+
+export function EmbedTrash() {
+	const api = useApi();
+	const embedNav = useEmbedNavigation();
+	const navigation = useEmbedAdapter(embedNav);
+
+	return <TrashPage api={api as TrashPageProps["api"]} navigation={navigation} />;
+}

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

@@ -0,0 +1,7 @@
+export { EmbedDashboard } from "./Dashboard";
+export { EmbedContent } from "./Content";
+export { EmbedContentTypes } from "./ContentTypes";
+export { EmbedMedia } from "./Media";
+export { EmbedSettings } from "./Settings";
+export { EmbedTrash } from "./Trash";
+export { EmbedTaxonomies } from "./Taxonomies";

package/admin/src/embed/types.ts

@@ -0,0 +1,24 @@
+import type { AdminConfig } from "../lib/admin-config";
+import type { CmsAdminApi } from "./contexts/ApiContext";
+
+export interface CmsAdminUser {
+  id: string;
+  name?: string;
+  email?: string;
+  avatarUrl?: string;
+}
+
+export interface CmsAdminAuthConfig {
+  getUser: () => CmsAdminUser | null | Promise<CmsAdminUser | null>;
+  getUserRole: (userId: string) => string | null | Promise<string | null>;
+  onLogout?: () => void | Promise<void>;
+}
+
+export interface CmsAdminProps {
+  api: CmsAdminApi;
+  convexUrl: string;
+  config?: Partial<AdminConfig>;
+  auth: CmsAdminAuthConfig;
+  basePath?: string;
+  className?: string;
+}

package/admin/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export { usePermissions, type UsePermissionsResult } from './usePermissions';
+export { useBreadcrumbLabel } from './useBreadcrumbLabel';

package/admin/src/hooks/use-mobile.ts

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}

package/admin/src/hooks/useBreadcrumbLabel.ts

@@ -0,0 +1,15 @@
+import { useEffect } from 'react'
+import { useBreadcrumbContext } from '~/contexts/BreadcrumbContext'
+
+export function useBreadcrumbLabel(path: string, label: string | undefined) {
+  const { setOverride, clearOverride } = useBreadcrumbContext()
+
+  useEffect(() => {
+    if (label) {
+      setOverride(path, label)
+    }
+    return () => {
+      clearOverride(path)
+    }
+  }, [path, label, setOverride, clearOverride])
+}

package/admin/src/hooks/usePermissions.ts

@@ -0,0 +1,211 @@
+/**
+ * usePermissions Hook
+ *
+ * Provides permission checking utilities for UI components.
+ * Enables showing/hiding or enabling/disabling features based on user permissions.
+ *
+ * @example
+ * ```tsx
+ * function ContentActions({ entry }) {
+ *   const { canEdit, canPublish, canDelete } = usePermissions();
+ *
+ *   return (
+ *     <div>
+ *       {canEdit('contentEntries') && <button>Edit</button>}
+ *       {canPublish() && <button>Publish</button>}
+ *       {canDelete('contentEntries') && <button>Delete</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+import { useMemo } from 'react';
+import { useAuth } from '../contexts/AuthContext';
+import {
+  hasPermission,
+  canAccessResource,
+  getResourcePermissions,
+  type Resource,
+  type Action,
+  type OwnershipScope,
+  type Permission,
+} from '../../../src/component/roles';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface UsePermissionsResult {
+  /** Current user's role */
+  role: string | null;
+  /** Whether user is authenticated with a valid role */
+  hasRole: boolean;
+  /** Check a specific permission */
+  check: (
+    resource: Resource,
+    action: Action,
+    scope?: OwnershipScope
+  ) => boolean;
+  /** Check if user can access a resource at all */
+  canAccess: (resource: Resource) => boolean;
+  /** Check if user can create resources of a type */
+  canCreate: (resource: Resource) => boolean;
+  /** Check if user can read resources of a type */
+  canRead: (resource: Resource, scope?: OwnershipScope) => boolean;
+  /** Check if user can update resources of a type */
+  canUpdate: (resource: Resource, scope?: OwnershipScope) => boolean;
+  /** Check if user can delete resources of a type */
+  canDelete: (resource: Resource, scope?: OwnershipScope) => boolean;
+  /** Check if user can publish content */
+  canPublish: (scope?: OwnershipScope) => boolean;
+  /** Check if user can unpublish content */
+  canUnpublish: (scope?: OwnershipScope) => boolean;
+  /** Check if user can manage settings */
+  canManageSettings: () => boolean;
+  /** Check if user can manage content types */
+  canManageContentTypes: () => boolean;
+  /** Get all permissions for a resource */
+  getPermissions: (resource: Resource) => Permission[];
+  /** Check if user is an admin */
+  isAdmin: boolean;
+  /** Check if user is at least an editor */
+  isEditor: boolean;
+  /** Check if user is at least an author */
+  isAuthor: boolean;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Hook for checking user permissions in UI components.
+ *
+ * Provides convenient methods for common permission checks,
+ * enabling permission-based UI rendering.
+ */
+export function usePermissions(): UsePermissionsResult {
+  const { role } = useAuth();
+
+  return useMemo(() => {
+    const hasRole = !!role;
+
+    /**
+     * Check a specific permission.
+     */
+    const check = (
+      resource: Resource,
+      action: Action,
+      scope?: OwnershipScope
+    ): boolean => {
+      if (!role) return false;
+      return hasPermission(role, { resource, action, scope });
+    };
+
+    /**
+     * Check if user can access a resource at all.
+     */
+    const canAccess = (resource: Resource): boolean => {
+      if (!role) return false;
+      return canAccessResource(role, resource);
+    };
+
+    /**
+     * Check if user can create resources.
+     */
+    const canCreate = (resource: Resource): boolean => {
+      return check(resource, 'create');
+    };
+
+    /**
+     * Check if user can read resources.
+     */
+    const canRead = (resource: Resource, scope?: OwnershipScope): boolean => {
+      return check(resource, 'read', scope);
+    };
+
+    /**
+     * Check if user can update resources.
+     */
+    const canUpdate = (resource: Resource, scope?: OwnershipScope): boolean => {
+      return check(resource, 'update', scope);
+    };
+
+    /**
+     * Check if user can delete resources.
+     */
+    const canDelete = (resource: Resource, scope?: OwnershipScope): boolean => {
+      return check(resource, 'delete', scope);
+    };
+
+    /**
+     * Check if user can publish content.
+     */
+    const canPublish = (scope?: OwnershipScope): boolean => {
+      return check('contentEntries', 'publish', scope);
+    };
+
+    /**
+     * Check if user can unpublish content.
+     */
+    const canUnpublish = (scope?: OwnershipScope): boolean => {
+      return check('contentEntries', 'unpublish', scope);
+    };
+
+    /**
+     * Check if user can manage settings.
+     */
+    const canManageSettings = (): boolean => {
+      return check('settings', 'manage');
+    };
+
+    /**
+     * Check if user can manage content types.
+     */
+    const canManageContentTypes = (): boolean => {
+      // Need create, update, or delete on content types
+      return (
+        check('contentTypes', 'create') ||
+        check('contentTypes', 'update') ||
+        check('contentTypes', 'delete')
+      );
+    };
+
+    /**
+     * Get all permissions for a resource.
+     */
+    const getPermissions = (resource: Resource): Permission[] => {
+      if (!role) return [];
+      return getResourcePermissions(role, resource);
+    };
+
+    /**
+     * Role-based checks for convenience.
+     */
+    const isAdmin = role === 'admin';
+    const isEditor = role === 'admin' || role === 'editor';
+    const isAuthor = role === 'admin' || role === 'editor' || role === 'author';
+
+    return {
+      role,
+      hasRole,
+      check,
+      canAccess,
+      canCreate,
+      canRead,
+      canUpdate,
+      canDelete,
+      canPublish,
+      canUnpublish,
+      canManageSettings,
+      canManageContentTypes,
+      getPermissions,
+      isAdmin,
+      isEditor,
+      isAuthor,
+    };
+  }, [role]);
+}
+
+export default usePermissions;