convex-cms 0.0.3 → 0.0.5-alpha.2

package/README.md

@@ -1,26 +1,84 @@
 # Convex CMS
 
-A developer-first headless CMS built as a [Convex Component](https://docs.convex.dev/components).
+A headless CMS built as a [Convex Component](https://docs.convex.dev/components) — content management that runs inside your Convex app.
 
-## Features
+## Choose Your Path
 
-- **Type-safe APIs** - Full TypeScript support with generated types
-- **Flexible content modeling** - Define content types with 13 field types
-- **Publishing workflows** - Draft, publish, schedule, and version content
-- **Media management** - Upload, organize, and serve media with variants
-- **Role-based access control** - Fine-grained permissions with custom roles
-- **Multi-locale support** - Content localization with fallback chains
-- **Admin UI** - Ready-to-use React admin interface
+### Need an Admin Interface?
 
-## Installation
+Use **`defineAdminAPI`** — one line creates all the backend functions for a working admin UI.
 
-```bash
-npm install convex-cms
 ```
+Your App                         Admin UI
+    │                               │
+    └── convex/admin.ts ────────────┘
+        defineAdminAPI()
+            │
+            ├── listContentTypes
+            ├── getEntry
+            ├── publishEntry
+            └── ... (30+ functions)
+                    │
+                    ▼
+            CMS Component
+```
+
+→ **[Admin UI Setup Guide](./docs/guides/admin-ui-setup.md)**
+
+### Building Custom Content Logic?
+
+Use **`createCmsClient`** — full programmatic control with typed methods in your Convex functions.
+
+```
+Your Convex Functions
+    │
+    └── cms.contentEntries.list(ctx, { status: "published" })
+        cms.contentTypes.create(ctx, { name: "blog", ... })
+        cms.mediaAssets.upload(ctx, { ... })
+            │
+            ▼
+        CMS Component
+```
+
+→ **[Getting Started Guide](./docs/guides/getting-started.md)**
+
+### Want Full Type Safety?
+
+Use **code-first schemas** — define content types with Convex validators, get TypeScript inference.
+
+```typescript
+const blogPost = defineContentType({
+  name: "blog_post",
+  validator: v.object({
+    title: v.string(),
+    content: v.string(),
+  }),
+});
+
+// TypeScript knows entry.data.title is string
+const entry = await cms.typedContentEntries.get<"blog_post">(ctx, id);
+```
+
+→ **[Code-First Schema Reference](./docs/api/code-first-schema.md)**
+
+### Need Both?
+
+**Most apps use both.** This is the typical setup:
+
+- `defineAdminAPI` powers the admin interface for content editors
+- `createCmsClient` gives you typed methods for custom queries on your frontend
+
+They work together through the same CMS component.
 
 ## Quick Start
 
-### 1. Configure Convex Component
+### 1. Install
+
+```bash
+npm install convex-cms
+```
+
+### 2. Add the Component
 
 ```typescript
 // convex/convex.config.ts
@@ -32,62 +90,51 @@ app.use(convexCms);
 export default app;
 ```
 
-### 2. Create CMS Client
+### 3. Choose Your Setup
 
-```typescript
-// convex/cms.ts
-import { createCmsClient } from "convex-cms";
-import { components } from "./_generated/api";
+**For Admin UI:** Run `npx convex-cms init` then `npx convex-cms admin`
+→ [Full Admin UI Setup](./docs/guides/admin-ui-setup.md)
 
-export const cms = createCmsClient(components.convexCms, {
-  defaultLocale: "en",
-  permissiveMode: true, // For development only
-});
-```
+**For Custom Functions:** Create a CMS client and use it in your functions
+→ [Full Getting Started Guide](./docs/guides/getting-started.md)
 
-### 3. Use in Your Functions
+## What's Included
 
-```typescript
-// convex/blog.ts
-import { query, mutation } from "./_generated/server";
-import { v } from "convex/values";
-import { cms } from "./cms";
-
-export const getPosts = query({
-  handler: async (ctx) => {
-    const result = await cms.contentEntries.list(ctx, {
-      status: "published",
-    });
-    return result.items;
-  },
-});
+- **13 field types** — text, richText, media, reference, select, and more
+- **Publishing workflows** — draft → scheduled → published with version history
+- **Media management** — uploads, folders, variants, and metadata
+- **RBAC** — 4 built-in roles + custom roles with fine-grained permissions
+- **Multi-locale** — content localization with fallback chains
+- **Admin UI** — pre-built React interface (CLI or embeddable)
+- **Agent tools** — Zod schemas for AI integration
 
-export const createPost = mutation({
-  args: { title: v.string(), content: v.string() },
-  handler: async (ctx, args) => {
-    return await cms.contentEntries.create(ctx, {
-      contentTypeId: blogTypeId,
-      data: args,
-    });
-  },
-});
-```
+## Admin UI Modes
 
-## Documentation
+| Mode | Command | Best For |
+|------|---------|----------|
+| **CLI** | `npx convex-cms admin` | Development |
+| **Embed** | `<CmsAdmin api={api.admin} />` | Production |
 
-- [Getting Started Guide](./docs/guides/getting-started.md)
-- [Content Modeling](./docs/guides/content-modeling.md)
-- [Media Management](./docs/guides/media.md)
-- [Authorization](./docs/guides/authorization.md)
-- [API Reference](./docs/api/client-api.md)
+Both modes call the same functions from your `convex/admin.ts`.
 
-## Admin UI
-
-Convex CMS includes a ready-to-use admin interface:
+## Documentation
 
-```bash
-npx convex-cms admin
-```
+| Guide | Description |
+|-------|-------------|
+| [Admin UI Setup](./docs/guides/admin-ui-setup.md) | CLI and embed modes, auth integration |
+| [Getting Started](./docs/guides/getting-started.md) | Programmatic usage with createCmsClient |
+| [Integration Patterns](./docs/guides/integration-patterns.md) | Common setups and when to use each |
+| [Content Modeling](./docs/guides/content-modeling.md) | Content types and field definitions |
+| [Authorization](./docs/guides/authorization.md) | Roles, permissions, and custom auth |
+| [Media Management](./docs/guides/media.md) | Uploads, folders, and variants |
+
+| Reference | Description |
+|-----------|-------------|
+| [Client API](./docs/api/client-api.md) | createCmsClient methods |
+| [Admin API](./docs/api/admin-api.md) | defineAdminAPI functions |
+| [Code-First Schema](./docs/api/code-first-schema.md) | TypeScript-first content types |
+| [Field Types](./docs/api/field-types.md) | All 13 field types |
+| [Configuration](./docs/api/configuration.md) | All config options |
 
 ## Requirements
 

package/admin/README.md

@@ -0,0 +1,99 @@
+# Convex CMS Admin UI
+
+The Admin UI for Convex CMS, built with TanStack Start and React.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- A Convex account and project
+
+### Installation
+
+```bash
+cd admin
+npm install
+```
+
+### Development
+
+1. Start the Convex development server:
+
+```bash
+npx convex dev
+```
+
+This will generate the Convex API types and provide a `VITE_CONVEX_URL`.
+
+2. Create a `.env` file with your Convex URL:
+
+```bash
+cp .env.example .env
+# Edit .env with your VITE_CONVEX_URL from step 1
+```
+
+3. Start the development server:
+
+```bash
+npm run dev:vite
+```
+
+Or run both Convex and Vite together:
+
+```bash
+npm run dev
+```
+
+4. Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Project Structure
+
+```
+admin/
+├── convex/                 # Convex configuration
+│   └── convex.config.ts    # CMS component integration
+├── src/
+│   ├── routes/             # TanStack Router routes
+│   │   ├── __root.tsx      # Root layout with Convex provider
+│   │   ├── index.tsx       # Dashboard page
+│   │   ├── content.tsx     # Content entries list
+│   │   ├── media.tsx       # Media library
+│   │   ├── content-types.tsx # Content type management
+│   │   └── settings.tsx    # CMS settings
+│   ├── components/         # Reusable React components
+│   ├── lib/                # Utilities and helpers
+│   │   └── convex.ts       # Convex client utilities
+│   ├── styles/             # CSS styles
+│   │   └── app.css         # Main stylesheet
+│   └── router.tsx          # Router configuration
+├── public/                 # Static assets
+├── vite.config.ts          # Vite + TanStack Start configuration
+├── tsconfig.json           # TypeScript configuration
+└── package.json            # Dependencies and scripts
+```
+
+## Available Scripts
+
+- `npm run dev` - Start Convex and Vite development servers
+- `npm run dev:vite` - Start only the Vite development server
+- `npm run dev:convex` - Start only the Convex development server
+- `npm run build` - Build for production
+- `npm run preview` - Preview production build
+- `npm run typecheck` - Run TypeScript type checking
+
+## Features
+
+- **Dashboard** - Overview of CMS status and quick navigation
+- **Content Management** - Browse and manage content entries
+- **Media Library** - Upload and organize media assets
+- **Content Types** - Define content schemas with custom fields
+- **Settings** - Configure CMS features and preferences
+
+## Technology Stack
+
+- [TanStack Start](https://tanstack.com/start) - Full-stack React framework
+- [TanStack Router](https://tanstack.com/router) - Type-safe routing
+- [Convex](https://convex.dev) - Real-time backend platform
+- [React 19](https://react.dev) - UI library
+- [Vite 7](https://vitejs.dev) - Build tool

package/admin/src/components/AdminLayout.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+import { Sidebar } from "./Sidebar";
+import { Header } from "./Header";
+import { useAdminConfig } from "~/contexts";
+
+interface AdminLayoutProps {
+  children: ReactNode;
+}
+
+export function AdminLayout({ children }: AdminLayoutProps) {
+  const { layout } = useAdminConfig();
+
+  return (
+    <div className="flex min-h-screen bg-background">
+      <Sidebar />
+      <div className="flex flex-1 flex-col" style={{ marginLeft: layout.sidebarWidth }}>
+        <Header />
+        <main className="flex-1 overflow-auto p-6">{children}</main>
+      </div>
+    </div>
+  );
+}

package/admin/src/components/BreakingChangesWarningDialog.tsx

@@ -0,0 +1,81 @@
+import { AlertTriangle } from 'lucide-react'
+import { CmsDialog } from '~/components/cmsds/CmsDialog'
+import { CmsButton } from '~/components/cmsds/CmsButton'
+
+interface BreakingChangesWarningDialogProps {
+  isOpen: boolean
+  onClose: () => void
+  breakingChanges: string[]
+  onForceUpdate: () => void
+  onCancel: () => void
+  isLoading: boolean
+}
+
+export function BreakingChangesWarningDialog({
+  isOpen,
+  onClose,
+  breakingChanges,
+  onForceUpdate,
+  onCancel,
+  isLoading,
+}: BreakingChangesWarningDialogProps) {
+  const handleCancel = () => {
+    onCancel()
+    onClose()
+  }
+
+  return (
+    <CmsDialog
+      open={isOpen}
+      onOpenChange={(open) => !open && !isLoading && handleCancel()}
+      title="Breaking Changes Detected"
+      size="lg"
+      footer={
+        <>
+          <CmsButton variant="outline" onClick={handleCancel} disabled={isLoading}>
+            Cancel
+          </CmsButton>
+          <CmsButton variant="danger" onClick={onForceUpdate} loading={isLoading}>
+            Force Update
+          </CmsButton>
+        </>
+      }
+    >
+      <div className="space-y-4">
+        <div className="flex items-start gap-3 rounded-lg border border-amber-200 bg-amber-50 p-3">
+          <AlertTriangle className="mt-0.5 size-5 shrink-0 text-amber-600" />
+          <div className="space-y-1">
+            <p className="text-sm font-medium text-amber-800">
+              These changes may affect existing content
+            </p>
+            <p className="text-sm text-amber-700">
+              The following changes could cause data loss or validation errors for existing entries.
+              Review carefully before proceeding.
+            </p>
+          </div>
+        </div>
+
+        <div className="space-y-2">
+          <p className="text-sm font-medium text-foreground">
+            {breakingChanges.length} breaking change{breakingChanges.length !== 1 ? 's' : ''} detected:
+          </p>
+          <ul className="space-y-2">
+            {breakingChanges.map((change, index) => (
+              <li
+                key={index}
+                className="flex items-start gap-2 rounded-md border bg-muted/30 px-3 py-2 text-sm"
+              >
+                <span className="mt-0.5 size-1.5 shrink-0 rounded-full bg-amber-500" />
+                <span className="text-muted-foreground">{change}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+
+        <p className="text-xs text-muted-foreground">
+          Click "Force Update" to apply these changes anyway, or "Cancel" to go back and modify your changes.
+        </p>
+      </div>
+    </CmsDialog>
+  )
+}

package/admin/src/components/BulkActionBar.tsx

@@ -0,0 +1,190 @@
+import { useState, useCallback } from 'react'
+import { useMutation } from 'convex/react'
+import { api } from '../../convex/_generated/api'
+import { BulkOperationModal } from './BulkOperationModal'
+import { CmsButton } from '~/components/cmsds/CmsButton'
+import { Badge } from '~/components/ui/badge'
+import { X } from 'lucide-react'
+
+type BulkAction = 'publish' | 'unpublish' | 'delete' | 'archive'
+
+interface BulkActionBarProps {
+  selectedIds: string[]
+  onClearSelection: () => void
+  onOperationComplete?: () => void
+}
+
+export function BulkActionBar({
+  selectedIds,
+  onClearSelection,
+  onOperationComplete,
+}: BulkActionBarProps) {
+  const [activeAction, setActiveAction] = useState<BulkAction | null>(null)
+  const [isProcessing, setIsProcessing] = useState(false)
+  const [result, setResult] = useState<{
+    succeeded: number
+    failed: number
+    errors?: string[]
+  } | null>(null)
+
+  const bulkPublish = useMutation(api.bulkOperations.bulkPublish)
+  const bulkUnpublish = useMutation(api.bulkOperations.bulkUnpublish)
+  const bulkDelete = useMutation(api.bulkOperations.bulkDelete)
+  const bulkUpdate = useMutation(api.bulkOperations.bulkUpdate)
+
+  const handleAction = useCallback((action: BulkAction) => {
+    setActiveAction(action)
+    setResult(null)
+  }, [])
+
+  const handleConfirm = useCallback(async () => {
+    if (!activeAction || selectedIds.length === 0) return
+
+    setIsProcessing(true)
+    setResult(null)
+
+    try {
+      let response: {
+        succeeded: number
+        failed: number
+        errors?: { id: string; error: string }[]
+      }
+
+      switch (activeAction) {
+        case 'publish':
+          response = await bulkPublish({
+            ids: selectedIds,
+            changeDescription: 'Bulk published from admin',
+          })
+          break
+        case 'unpublish':
+          response = await bulkUnpublish({
+            ids: selectedIds,
+          })
+          break
+        case 'delete':
+          response = await bulkDelete({
+            ids: selectedIds,
+            hardDelete: false,
+          })
+          break
+        case 'archive':
+          response = await bulkUpdate({
+            ids: selectedIds,
+            status: 'archived',
+          })
+          break
+        default:
+          throw new Error(`Unknown action: ${activeAction}`)
+      }
+
+      setResult({
+        succeeded: response.succeeded,
+        failed: response.failed,
+        errors: response.errors?.map((e) => `${e.id}: ${e.error}`),
+      })
+
+      if (response.failed === 0) {
+        setTimeout(() => {
+          setActiveAction(null)
+          onClearSelection()
+          onOperationComplete?.()
+        }, 1500)
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Operation failed'
+      setResult({
+        succeeded: 0,
+        failed: selectedIds.length,
+        errors: [message],
+      })
+    } finally {
+      setIsProcessing(false)
+    }
+  }, [
+    activeAction,
+    selectedIds,
+    bulkPublish,
+    bulkUnpublish,
+    bulkDelete,
+    bulkUpdate,
+    onClearSelection,
+    onOperationComplete,
+  ])
+
+  const handleCancel = useCallback(() => {
+    setActiveAction(null)
+    setResult(null)
+  }, [])
+
+  if (selectedIds.length === 0) {
+    return null
+  }
+
+  return (
+    <>
+      <div className="fixed inset-x-0 bottom-0 z-50 border-t bg-background/95 px-6 py-3 shadow-lg backdrop-blur supports-[backdrop-filter]:bg-background/80">
+        <div className="mx-auto flex max-w-7xl items-center justify-between">
+          <div className="flex items-center gap-3">
+            <Badge variant="secondary" className="text-sm font-semibold">
+              {selectedIds.length}
+            </Badge>
+            <span className="text-sm text-muted-foreground">
+              {selectedIds.length === 1 ? 'item' : 'items'} selected
+            </span>
+            <button
+              type="button"
+              onClick={onClearSelection}
+              className="flex items-center gap-1 text-sm text-muted-foreground transition-colors hover:text-foreground"
+            >
+              <X className="size-3" />
+              Clear
+            </button>
+          </div>
+
+          <div className="flex items-center gap-2">
+            <CmsButton
+              variant="success"
+              size="sm"
+              onClick={() => handleAction('publish')}
+            >
+              Publish
+            </CmsButton>
+            <CmsButton
+              variant="warning"
+              size="sm"
+              onClick={() => handleAction('unpublish')}
+            >
+              Unpublish
+            </CmsButton>
+            <CmsButton
+              variant="secondary"
+              size="sm"
+              onClick={() => handleAction('archive')}
+            >
+              Archive
+            </CmsButton>
+            <CmsButton
+              variant="danger"
+              size="sm"
+              onClick={() => handleAction('delete')}
+            >
+              Delete
+            </CmsButton>
+          </div>
+        </div>
+      </div>
+
+      {activeAction && (
+        <BulkOperationModal
+          action={activeAction}
+          count={selectedIds.length}
+          isProcessing={isProcessing}
+          result={result}
+          onConfirm={handleConfirm}
+          onCancel={handleCancel}
+        />
+      )}
+    </>
+  )
+}