convex-cms 0.0.3 → 0.0.5-alpha.2

package/admin/src/routes/settings.tsx

@@ -0,0 +1,20 @@
+/**
+ * Settings Route (CLI)
+ *
+ * Thin wrapper around the shared SettingsPage component.
+ * Provides TanStack Router integration and API access.
+ */
+
+import { createFileRoute } from "@tanstack/react-router";
+import { api } from "../../convex/_generated/api";
+import { SettingsPage } from "~/pages";
+import { useTanStackNavigation } from "~/lib/tanstack-adapter";
+
+export const Route = createFileRoute("/settings")({
+	component: SettingsRoute,
+});
+
+function SettingsRoute() {
+	const navigation = useTanStackNavigation();
+	return <SettingsPage api={api.admin} navigation={navigation} />;
+}

package/admin/src/routes/taxonomies.tsx

@@ -0,0 +1,20 @@
+/**
+ * Taxonomies Route (CLI)
+ *
+ * Thin wrapper around the shared TaxonomiesPage component.
+ * Provides TanStack Router integration and API access.
+ */
+
+import { createFileRoute } from "@tanstack/react-router";
+import { api } from "../../convex/_generated/api";
+import { TaxonomiesPage } from "~/pages";
+import { useTanStackNavigation } from "~/lib/tanstack-adapter";
+
+export const Route = createFileRoute("/taxonomies")({
+	component: TaxonomiesRoute,
+});
+
+function TaxonomiesRoute() {
+	const navigation = useTanStackNavigation();
+	return <TaxonomiesPage api={api.admin} navigation={navigation} />;
+}

package/admin/src/routes/trash.tsx

@@ -0,0 +1,20 @@
+/**
+ * Trash Route (CLI)
+ *
+ * Thin wrapper around the shared TrashPage component.
+ * Provides TanStack Router integration and API access.
+ */
+
+import { createFileRoute } from "@tanstack/react-router";
+import { api } from "../../convex/_generated/api";
+import { TrashPage } from "~/pages";
+import { useTanStackNavigation } from "~/lib/tanstack-adapter";
+
+export const Route = createFileRoute("/trash")({
+	component: TrashRoute,
+});
+
+function TrashRoute() {
+	const navigation = useTanStackNavigation();
+	return <TrashPage api={api.admin} navigation={navigation} />;
+}

package/admin/src/styles/globals.css

@@ -0,0 +1,69 @@
+@import 'tailwindcss';
+@import "tw-animate-css";
+@import "./theme.css";
+@import "./tailwind-config.css";
+
+/* ============================================
+   CMS Admin - Base & Utility Layers
+   ============================================ */
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+    font-feature-settings: 'rlig' 1, 'calt' 1;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+}
+
+@layer utilities {
+  /* Status badge colors */
+  .status-draft {
+    @apply bg-zinc-100 text-zinc-700 dark:bg-zinc-800 dark:text-zinc-300;
+  }
+
+  .status-published {
+    @apply bg-emerald-100 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-400;
+  }
+
+  .status-scheduled {
+    @apply bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400;
+  }
+
+  .status-archived {
+    @apply bg-amber-100 text-amber-700 dark:bg-amber-900/30 dark:text-amber-400;
+  }
+
+  /* Surface elevations */
+  .surface-base {
+    @apply bg-card border border-border;
+  }
+
+  .surface-elevated {
+    @apply bg-card border border-border shadow-sm;
+  }
+
+  .surface-floating {
+    @apply bg-popover border border-border shadow-lg;
+  }
+
+  /* Focus styles */
+  .focus-ring {
+    @apply focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2;
+  }
+
+  /* Hidden scrollbar - scroll functionality without visible scrollbar */
+  .scrollbar-none {
+    overflow-y: auto;
+    scrollbar-width: none; /* Firefox */
+    -ms-overflow-style: none; /* IE/Edge */
+  }
+
+  .scrollbar-none::-webkit-scrollbar {
+    display: none; /* Chrome/Safari/Opera */
+  }
+}

package/admin/src/styles/tailwind-config.css

@@ -0,0 +1,74 @@
+/* ============================================
+   CMS Admin - Tailwind v4 Configuration
+
+   This file contains Tailwind v4 specific config:
+   - @custom-variant for dark mode
+   - @theme for base tokens (fonts, radii, animations)
+   - @theme inline for color mappings to CSS vars
+   ============================================ */
+
+@custom-variant dark (&:is(.dark *));
+
+@theme {
+  /* Typography */
+  --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', ui-monospace, monospace;
+
+  /* Border Radius */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-xl: 0.75rem;
+
+  /* Sidebar dimensions */
+  --sidebar-width: 16rem;
+  --sidebar-width-icon: 3rem;
+
+  /* Animations */
+  --animate-accordion-down: accordion-down 0.2s ease-out;
+  --animate-accordion-up: accordion-up 0.2s ease-out;
+
+  @keyframes accordion-down {
+    from { height: 0; }
+    to { height: var(--radix-accordion-content-height); }
+  }
+
+  @keyframes accordion-up {
+    from { height: var(--radix-accordion-content-height); }
+    to { height: 0; }
+  }
+}
+
+/* Map CSS custom properties to Tailwind theme colors */
+@theme inline {
+  /* Main colors */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  /* Sidebar */
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}

package/admin/src/styles/theme.css

@@ -0,0 +1,73 @@
+/* ============================================
+   CMS Admin Theme - CSS Custom Properties
+   Professional & Clean (Linear/Notion aesthetic)
+
+   Consumers can import this file and override
+   any variable in their own :root {} block.
+   ============================================ */
+
+:root {
+  /* Main colors */
+  --background: hsl(0 0% 98%);
+  --foreground: hsl(240 10% 3.9%);
+  --card: hsl(0 0% 100%);
+  --card-foreground: hsl(240 10% 3.9%);
+  --popover: hsl(0 0% 100%);
+  --popover-foreground: hsl(240 10% 3.9%);
+  --primary: hsl(240 5.9% 10%);
+  --primary-foreground: hsl(0 0% 98%);
+  --secondary: hsl(240 4.8% 95.9%);
+  --secondary-foreground: hsl(240 5.9% 10%);
+  --muted: hsl(240 4.8% 95.9%);
+  --muted-foreground: hsl(240 3.8% 46.1%);
+  --accent: hsl(240 4.8% 95.9%);
+  --accent-foreground: hsl(240 5.9% 10%);
+  --destructive: hsl(0 84.2% 60.2%);
+  --destructive-foreground: hsl(0 0% 98%);
+  --border: hsl(240 5.9% 90%);
+  --input: hsl(240 5.9% 90%);
+  --ring: hsl(240 5.9% 10%);
+
+  /* Sidebar */
+  --sidebar: hsl(0 0% 98%);
+  --sidebar-foreground: hsl(240 5.3% 26.1%);
+  --sidebar-primary: hsl(240 5.9% 10%);
+  --sidebar-primary-foreground: hsl(0 0% 98%);
+  --sidebar-accent: hsl(240 4.8% 95.9%);
+  --sidebar-accent-foreground: hsl(240 5.9% 10%);
+  --sidebar-border: hsl(220 13% 91%);
+  --sidebar-ring: hsl(217.2 91.2% 59.8%);
+}
+
+.dark {
+  /* Main colors */
+  --background: hsl(240 10% 3.9%);
+  --foreground: hsl(0 0% 98%);
+  --card: hsl(240 10% 7%);
+  --card-foreground: hsl(0 0% 98%);
+  --popover: hsl(240 10% 7%);
+  --popover-foreground: hsl(0 0% 98%);
+  --primary: hsl(0 0% 98%);
+  --primary-foreground: hsl(240 5.9% 10%);
+  --secondary: hsl(240 3.7% 15.9%);
+  --secondary-foreground: hsl(0 0% 98%);
+  --muted: hsl(240 3.7% 15.9%);
+  --muted-foreground: hsl(240 5% 64.9%);
+  --accent: hsl(240 3.7% 15.9%);
+  --accent-foreground: hsl(0 0% 98%);
+  --destructive: hsl(0 62.8% 50.6%);
+  --destructive-foreground: hsl(0 0% 98%);
+  --border: hsl(240 3.7% 20%);
+  --input: hsl(240 3.7% 20%);
+  --ring: hsl(240 4.9% 83.9%);
+
+  /* Sidebar */
+  --sidebar: hsl(240 5.9% 10%);
+  --sidebar-foreground: hsl(240 4.8% 95.9%);
+  --sidebar-primary: hsl(224.3 76.3% 48%);
+  --sidebar-primary-foreground: hsl(0 0% 100%);
+  --sidebar-accent: hsl(240 3.7% 15.9%);
+  --sidebar-accent-foreground: hsl(240 4.8% 95.9%);
+  --sidebar-border: hsl(240 3.7% 15.9%);
+  --sidebar-ring: hsl(217.2 91.2% 59.8%);
+}

package/admin/src/types/index.ts

@@ -0,0 +1,221 @@
+/**
+ * Admin UI Type Definitions
+ *
+ * Since the admin UI has its own Convex schema (only settings table),
+ * we define CMS entity types locally rather than using Doc<> from generated types.
+ * These types mirror the CMS component's document structure.
+ */
+
+// =============================================================================
+// Field Definition Types
+// =============================================================================
+
+export type FieldType =
+  | "text"
+  | "number"
+  | "boolean"
+  | "richText"
+  | "media"
+  | "select"
+  | "multiSelect"
+  | "tags"
+  | "category"
+  | "json"
+  | "date"
+  | "datetime"
+  | "reference";
+
+export interface FieldDefinition {
+  name: string;
+  displayName: string;
+  type: FieldType;
+  required?: boolean;
+  description?: string;
+  options?: Record<string, unknown>;
+}
+
+// =============================================================================
+// Content Type
+// =============================================================================
+
+export interface ContentType {
+  _id: string;
+  _creationTime: number;
+  name: string;
+  displayName: string;
+  description?: string;
+  icon?: string;
+  fields: FieldDefinition[];
+  singleton: boolean;
+  slugField?: string;
+  titleField?: string;
+  sortOrder: number;
+  isActive: boolean;
+  createdBy: string;
+  updatedBy?: string;
+}
+
+export type ContentTypeWithCount = ContentType & {
+  entryCount?: number;
+};
+
+// =============================================================================
+// Content Entry
+// =============================================================================
+
+export type ContentStatus = "draft" | "published" | "scheduled" | "archived";
+
+export interface ContentEntry {
+  _id: string;
+  _creationTime: number;
+  contentTypeId: string;
+  slug?: string;
+  data: Record<string, unknown>;
+  status: ContentStatus;
+  version: number;
+  locale?: string;
+  primaryEntryId?: string;
+  publishedAt?: number;
+  scheduledPublishAt?: number;
+  archivedAt?: number;
+  createdBy?: string;
+  updatedBy?: string;
+  deletedAt?: number;
+  deletedBy?: string;
+}
+
+// =============================================================================
+// Content Version
+// =============================================================================
+
+export interface ContentVersion {
+  _id: string;
+  _creationTime: number;
+  entryId: string;
+  version: number;
+  data: Record<string, unknown>;
+  status: ContentStatus;
+  changeDescription?: string;
+  createdBy?: string;
+}
+
+// =============================================================================
+// Media Item
+// =============================================================================
+
+export type MediaItemKind = "asset" | "folder";
+export type MediaType = "image" | "video" | "audio" | "document" | "other";
+
+export interface MediaItem {
+  _id: string;
+  _creationTime: number;
+  kind: MediaItemKind;
+  name: string;
+  parentId?: string;
+  path?: string;
+  sortOrder?: number;
+  createdBy?: string;
+  deletedAt?: number;
+  deletedBy?: string;
+  // Asset-specific fields
+  storageId?: string;
+  mimeType?: string;
+  size?: number;
+  type?: MediaType;
+  width?: number;
+  height?: number;
+  duration?: number;
+  title?: string;
+  description?: string;
+  altText?: string;
+  tags?: string[];
+  // Folder-specific fields
+  folderDescription?: string;
+}
+
+// =============================================================================
+// Media Variant
+// =============================================================================
+
+export interface MediaVariant {
+  _id: string;
+  _creationTime: number;
+  assetId: string;
+  name: string;
+  storageId: string;
+  width?: number;
+  height?: number;
+  format?: string;
+}
+
+// =============================================================================
+// Taxonomy
+// =============================================================================
+
+export interface Taxonomy {
+  _id: string;
+  _creationTime: number;
+  name: string;
+  displayName: string;
+  description?: string;
+  isHierarchical: boolean;
+  allowInlineCreation: boolean;
+  isActive: boolean;
+  icon?: string;
+  sortOrder?: number;
+  createdBy?: string;
+  deletedAt?: number;
+  deletedBy?: string;
+}
+
+// =============================================================================
+// Taxonomy Term
+// =============================================================================
+
+export interface TaxonomyTerm {
+  _id: string;
+  _creationTime: number;
+  taxonomyId: string;
+  name: string;
+  slug: string;
+  description?: string;
+  parentId?: string;
+  sortOrder?: number;
+  color?: string;
+  metadata?: Record<string, unknown>;
+  createdBy?: string;
+  deletedAt?: number;
+  deletedBy?: string;
+}
+
+export type TaxonomyTermWithChildren = TaxonomyTerm & {
+  children?: TaxonomyTermWithChildren[];
+};
+
+// =============================================================================
+// ID Types (string aliases for documentation)
+// =============================================================================
+
+export type ContentTypeId = string;
+export type ContentEntryId = string;
+export type ContentVersionId = string;
+export type MediaItemId = string;
+export type MediaVariantId = string;
+export type TaxonomyId = string;
+export type TaxonomyTermId = string;
+
+// =============================================================================
+// Type Assertion Helpers
+// =============================================================================
+
+export function asTaxonomyId(id: string): TaxonomyId {
+  return id;
+}
+
+export function asTaxonomyTermId(id: string): TaxonomyTermId {
+  return id;
+}
+
+export function asTaxonomyTermIds(ids: string[]): TaxonomyTermId[] {
+  return ids;
+}

package/admin/src/utils/errorParsing.ts

@@ -0,0 +1,163 @@
+import type { FieldError } from '../components/fields/types';
+
+/**
+ * Parses server validation errors into field-level errors.
+ *
+ * Supported error formats:
+ * 1. JSON format: {"errors": [{"field": "name", "message": "error"}]}
+ * 2. Structured text: "Content validation failed: field1: error1; field2: error2"
+ * 3. Plain message: "Some error message"
+ *
+ * @param error - The error to parse (Error object or string)
+ * @returns Object with fieldErrors map and a general error message
+ */
+export function parseServerError(
+  error: Error | string | unknown
+): { fieldErrors: Record<string, FieldError>; generalError: string | null } {
+  const result: { fieldErrors: Record<string, FieldError>; generalError: string | null } = {
+    fieldErrors: {},
+    generalError: null,
+  };
+
+  if (!error) {
+    return result;
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+
+  // Try to parse JSON error format first
+  try {
+    // Check if the error message contains JSON
+    const jsonMatch = message.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      const parsed = JSON.parse(jsonMatch[0]);
+
+      // Handle {"errors": [{"field": "...", "message": "..."}]} format
+      if (Array.isArray(parsed.errors)) {
+        for (const err of parsed.errors) {
+          if (err.field && err.message) {
+            result.fieldErrors[err.field] = {
+              message: err.message,
+              code: err.code ?? 'SERVER_ERROR',
+            };
+          }
+        }
+        if (Object.keys(result.fieldErrors).length > 0) {
+          return result;
+        }
+      }
+
+      // Handle {"field": "...", "message": "..."} format (single error)
+      if (parsed.field && parsed.message) {
+        result.fieldErrors[parsed.field] = {
+          message: parsed.message,
+          code: parsed.code ?? 'SERVER_ERROR',
+        };
+        return result;
+      }
+
+      // Handle {fieldName: errorMessage} format
+      if (typeof parsed === 'object' && !Array.isArray(parsed)) {
+        let hasFieldErrors = false;
+        for (const [key, value] of Object.entries(parsed)) {
+          if (typeof value === 'string' && key !== 'message' && key !== 'code') {
+            result.fieldErrors[key] = {
+              message: value,
+              code: 'SERVER_ERROR',
+            };
+            hasFieldErrors = true;
+          }
+        }
+        if (hasFieldErrors) {
+          return result;
+        }
+      }
+    }
+  } catch {
+    // JSON parsing failed, continue with text parsing
+  }
+
+  // Try to parse "Content validation failed:" format
+  const validationPattern = /(?:Content validation failed|Validation error|Validation failed):\s*(.+)/i;
+  const validationMatch = message.match(validationPattern);
+
+  if (validationMatch) {
+    const errorPart = validationMatch[1].trim();
+
+    // Split by semicolon to get individual field errors
+    const fieldErrorParts = errorPart.split(/;\s*/);
+
+    for (const part of fieldErrorParts) {
+      // Try to extract "fieldName: errorMessage" pattern
+      const colonIndex = part.indexOf(':');
+      if (colonIndex > 0 && colonIndex < part.length - 1) {
+        const fieldName = part.substring(0, colonIndex).trim();
+        const errorMsg = part.substring(colonIndex + 1).trim();
+
+        // Validate field name looks reasonable (no spaces, reasonable length)
+        if (fieldName && !fieldName.includes(' ') && fieldName.length <= 50 && errorMsg) {
+          result.fieldErrors[fieldName] = {
+            message: errorMsg,
+            code: 'SERVER_ERROR',
+          };
+        }
+      }
+    }
+
+    if (Object.keys(result.fieldErrors).length > 0) {
+      return result;
+    }
+  }
+
+  // If we couldn't parse field errors, return the general error message
+  result.generalError = message;
+  return result;
+}
+
+/**
+ * Format an error for display to users.
+ * Removes technical details and provides a user-friendly message.
+ */
+export function formatErrorForDisplay(error: Error | string | unknown): string {
+  if (!error) {
+    return 'An unexpected error occurred';
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+
+  // Remove common technical prefixes
+  const cleanedMessage = message
+    .replace(/^(Error|ConvexError|ValidationError|ServerError):\s*/i, '')
+    .replace(/^\[.*?\]\s*/, ''); // Remove bracketed prefixes like [HTTP 500]
+
+  // Capitalize first letter
+  return cleanedMessage.charAt(0).toUpperCase() + cleanedMessage.slice(1);
+}
+
+/**
+ * Determines if an error is likely transient (network issue, timeout)
+ * and worth retrying automatically.
+ */
+export function isRetryableError(error: Error | string | unknown): boolean {
+  if (!error) return false;
+
+  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+
+  const retryablePatterns = [
+    'network',
+    'timeout',
+    'timed out',
+    'connection',
+    'fetch failed',
+    'failed to fetch',
+    'offline',
+    'unavailable',
+    'rate limit',
+    'too many requests',
+    '503',
+    '504',
+    '429',
+  ];
+
+  return retryablePatterns.some(pattern => message.includes(pattern));
+}

package/admin/src/utils/index.ts

@@ -0,0 +1,5 @@
+export {
+  parseServerError,
+  formatErrorForDisplay,
+  isRetryableError,
+} from './errorParsing';

package/admin/src/vite-env.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_CONVEX_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+
+declare module '*.css?url' {
+  const url: string
+  export default url
+}