@questpie/admin 1.1.1 → 3.0.0

package/README.md

@@ -1,570 +1,338 @@
 # @questpie/admin
 
-**Config-driven, batteries-included admin UI for QUESTPIE CMS**
+Server-driven admin UI for QUESTPIE. Reads your server schema via introspection and generates a complete admin panel — dashboard, table views, form editors, sidebar navigation, block editor — all from the definitions you already wrote on the server.
 
-A fully-featured admin interface using the `qa()` builder pattern for type-safe configuration.
+## How It Works
 
-## Features
+QUESTPIE follows a **server-first** architecture. All schema, layout, and behavior is defined on the server with the `questpie` core package. The admin UI consumes this via introspection — no duplicate config needed on the client.
 
-- **Builder Pattern** - Type-safe `qa()` builder with autocomplete
-- **Config-Driven** - UI auto-generated from builder configuration
-- **Type-Safe** - Full TypeScript inference with module augmentation
-- **Tailwind v4** - Built with Tailwind CSS v4 + shadcn/ui components
-- **Rich Text** - Tiptap editor with toolbar controls
-- **Relations** - Single select, multi-picker with drag-and-drop
-- **Layouts** - Sections, tabs, columns, grids, sidebars
-- **Realtime** - SSE-powered live updates
-- **Versioning** - Built-in version history
-- **i18n Ready** - Localization support for content
+| Layer      | Package                               | Defines                                                           |
+| ---------- | ------------------------------------- | ----------------------------------------------------------------- |
+| **Server** | `questpie` + `@questpie/admin/server` | Schema, fields, access, hooks, sidebar, dashboard, branding       |
+| **Client** | `@questpie/admin/client`              | Field renderers, view renderers, component registry, UI overrides |
 
 ## Installation
 
 ```bash
-bun add @questpie/admin questpie @questpie/tanstack-query
-bun add @tanstack/react-query
+bun add @questpie/admin questpie @questpie/tanstack-query @tanstack/react-query
 ```
 
-## Quick Start
+## Server Setup
 
-### 1. Create Admin Builder
+The admin plugin is registered in `questpie.config.ts`, and the admin module is added to `modules.ts`:
 
-```typescript
-// src/admin/builder.ts
-import { qa, adminModule } from "@questpie/admin/client";
-import type { AppCMS } from "./server/cms";
-
-// Create typed builder with admin fields/views
-export const qab = qa<AppCMS>().use(adminModule).toNamespace();
-```
+```ts
+// questpie.config.ts
+import { runtimeConfig } from "questpie";
+import { adminPlugin } from "@questpie/admin/plugin";
 
-### 2. Define Collection Configs
-
-```typescript
-// src/admin/collections/posts.ts
-import { qab } from "../builder";
-
-export const postsAdmin = qab
-  .collection("posts")
-  .meta({
-    label: "Blog Posts",
-    icon: FileTextIcon, // React component
-  })
-  // Fields with registry callback - ({ r }) gives autocomplete!
-  .fields(({ r }) => ({
-    title: r.text({
-      label: "Title",
-      placeholder: "Post title...",
-      maxLength: 200,
-    }),
-    slug: r.text({
-      label: "Slug",
-    }),
-    content: r.textarea({
-      label: "Content",
-    }),
-    status: r.select({
-      label: "Status",
-      options: [
-        { label: "Draft", value: "draft" },
-        { label: "Published", value: "published" },
-      ],
-    }),
-    publishedAt: r.datetime({
-      label: "Publish Date",
-    }),
-    authorId: r.relation({
-      label: "Author",
-      targetCollection: "users",
-    }),
-  }))
-  // List view with field proxy - ({ v, f }) gives autocomplete!
-  .list(({ v, f }) =>
-    v.table({
-      columns: [f.title, f.status, f.authorId, f.publishedAt],
-    }),
-  )
-  // Form view
-  .form(({ v, f }) =>
-    v.form({
-      sections: [
-        {
-          title: "Content",
-          fields: [f.title, f.slug, f.content],
-        },
-        {
-          title: "Publishing",
-          fields: [f.status, f.publishedAt, f.authorId],
-        },
-      ],
-    }),
-  );
+export default runtimeConfig({
+	plugins: [adminPlugin()],
+	app: { url: process.env.APP_URL! },
+	db: { url: process.env.DATABASE_URL! },
+	secret: process.env.AUTH_SECRET!,
+});
 ```
 
-### 3. Build Admin Configuration
+```ts
+// modules.ts
+import { adminModule } from "@questpie/admin/server";
 
-```typescript
-// src/admin/admin.ts
-import { qa, adminModule } from "@questpie/admin/client";
-import { postsAdmin } from "./collections/posts";
-import { sidebarConfig } from "./sidebar";
-
-export const admin = qa()
-  .use(adminModule)
-  .branding({
-    name: "My Admin",
-  })
-  .collections({
-    posts: postsAdmin,
-  })
-  .sidebar(sidebarConfig);
-
-// Module augmentation for global type inference
-declare module "@questpie/admin/client" {
-  interface AdminTypeRegistry {
-    cms: AppCMS;
-    admin: typeof admin;
-  }
-}
+export default [adminModule] as const;
 ```
 
-### 4. Configure Sidebar
-
-```typescript
-// src/admin/sidebar.ts
-import { qa } from "@questpie/admin/client";
-import { HouseIcon, FileTextIcon } from "@phosphor-icons/react";
-
-export const sidebarConfig = qa
-  .sidebar()
-  .section("main", (s) =>
-    s.items([
-      { type: "link", label: "Dashboard", href: "/admin", icon: HouseIcon },
-    ]),
-  )
-  .section("content", (s) =>
-    s
-      .title("Content")
-      .icon(FileTextIcon)
-      .items([{ type: "collection", collection: "posts", icon: FileTextIcon }]),
-  );
+Branding, sidebar, and dashboard are configured via the file convention (e.g. `branding.ts`, `sidebar.ts`, `dashboard.ts`) and auto-discovered by codegen.
+
+Collections, globals, routes, and jobs are auto-discovered via file convention. Codegen produces a `.generated/index.ts` with the fully-typed `App` and runtime `app` instance.
+
+### Collection Admin Config
+
+Admin metadata, list views, and form views are defined on the collection itself:
+
+```ts
+const posts = collection("posts")
+	.fields(({ f }) => ({
+		title: f.text(255).required().label("Title"),
+		content: f.richText().label("Content"),
+		status: f.select(["draft", "published"]).label("Status"),
+		cover: f.upload({ to: "assets", mimeTypes: ["image/*"] }),
+		publishedAt: f.date(),
+	}))
+	.title(({ f }) => f.title)
+	.admin(({ c }) => ({
+		label: { en: "Blog Posts" },
+		icon: c.icon("ph:article"),
+	}))
+	.list(({ v, f }) =>
+		v.collectionTable({
+			columns: [f.title, f.status, f.publishedAt],
+		}),
+	)
+	.form(({ v, f }) =>
+		v.collectionForm({
+			layout: "with-sidebar",
+			sidebar: {
+				position: "right",
+				fields: [f.status, f.publishedAt, f.cover],
+			},
+			fields: [
+				{ type: "section", label: "Content", fields: [f.title, f.content] },
+			],
+		}),
+	);
 ```
 
-### 5. Setup Tailwind CSS
+### Component References
 
-In your main CSS file, import admin styles and configure Tailwind to scan the admin package:
+The server emits serializable `ComponentReference` objects instead of React elements. Use the `c` factory in admin config callbacks:
 
-```css
-/* src/styles.css */
-@import "tailwindcss";
-@import "tw-animate-css";
-@import "shadcn/tailwind.css";
-@import "@questpie/admin/styles/index.css";
+```ts
+.admin(({ c }) => ({
+  icon: c.icon("ph:article"),       // → { type: "icon", props: { name: "ph:article" } }
+  badge: c.badge({ text: "New" }),   // → { type: "badge", props: { text: "New" } }
+}))
+```
 
-/* IMPORTANT: Tell Tailwind to scan admin package for utility classes */
-@source "../node_modules/@questpie/admin/dist";
+Icons use the [Iconify](https://icon-sets.iconify.design/) format with the Phosphor set (`ph:icon-name`).
 
-/* Your app's theme variables... */
-```
+### Form Layouts
 
-### 6. Mount in React
+```ts
+// Sections
+.form(({ v, f }) => v.collectionForm({
+  fields: [
+    { type: "section", label: "Basic Info", layout: "grid", columns: 2,
+      fields: [f.name, f.email, f.phone, f.city] },
+    { type: "section", label: "Content", fields: [f.body] },
+  ],
+}))
 
-```tsx
-// routes/admin.tsx (TanStack Router example)
-import { Admin, AdminLayoutProvider } from "@questpie/admin/client";
-import { Link, Outlet, useLocation } from "@tanstack/react-router";
-import { admin } from "~/admin/admin";
-import { cmsClient } from "~/lib/cms-client";
-import { queryClient } from "~/lib/query-client";
-
-// Create runtime instance
-const adminInstance = Admin.from(admin);
-
-function AdminLayout() {
-  const location = useLocation();
-
-  return (
-    <AdminLayoutProvider
-      admin={adminInstance}
-      client={cmsClient}
-      queryClient={queryClient}
-      LinkComponent={Link}
-      activeRoute={location.pathname}
-      basePath="/admin"
-    >
-      <Outlet />
-    </AdminLayoutProvider>
-  );
-}
-```
+// Sidebar layout
+.form(({ v, f }) => v.collectionForm({
+  layout: "with-sidebar",
+  sidebar: { position: "right", fields: [f.status, f.image] },
+  fields: [f.title, f.content],
+}))
 
-## Builder API
+// Tabs
+.form(({ v, f }) => v.collectionForm({
+  tabs: [
+    { id: "content", label: "Content", fields: [f.title, f.body] },
+    { id: "meta", label: "Metadata", fields: [f.seoTitle, f.seoDescription] },
+  ],
+}))
+```
 
-### Main Entry Point
+### Reactive Fields
 
-```typescript
-import { qa, adminModule } from "@questpie/admin/client";
+Server-evaluated reactive behaviors in form config:
 
-// Start from admin module (includes built-in fields/views + user management)
-const admin = qa()
-  .use(adminModule)
-  .branding({ name: "My Admin" })
-  .collections({ posts: postsAdmin })
-  .globals({ settings: settingsAdmin })
-  .sidebar(sidebarConfig)
-  .dashboard(dashboardConfig);
+```ts
+.form(({ v, f }) => v.collectionForm({
+  fields: [
+    {
+      field: f.slug,
+      compute: {
+        handler: ({ data }) => slugify(data.title),
+        deps: ({ data }) => [data.title],
+        debounce: 300,
+      },
+    },
+    { field: f.publishedAt, hidden: ({ data }) => !data.published },
+    { field: f.reason, readOnly: ({ data }) => data.status !== "cancelled" },
+  ],
+}))
 ```
 
-### Collection Builder
-
-```typescript
-const postsAdmin = qa
-  .collection("posts")
-  .meta({ label: "Posts", icon: PostIcon })
-  .fields(({ r }) => ({
-    // r = FieldRegistryProxy with autocomplete for registered fields
-    title: r.text({ maxLength: 200 }),
-    content: r.richText(),
-    status: r.select({ options: [...] }),
-  }))
-  .list(({ v, f }) => v.table({
-    // v = ViewRegistryProxy, f = FieldProxy
-    columns: [f.title, f.status],
-  }))
-  .form(({ v, f }) => v.form({
-    fields: [f.title, f.content, f.status],
-  }));
-```
+### Dashboard Actions
 
-### Global Builder
-
-```typescript
-const settingsAdmin = qa
-  .global("settings")
-  .meta({ label: "Site Settings", icon: SettingsIcon })
-  .fields(({ r }) => ({
-    siteName: r.text({ maxLength: 100 }),
-    logo: r.text(), // TODO: image field
-  }))
-  .form(({ v, f }) =>
-    v.form({
-      fields: [f.siteName, f.logo],
-    }),
-  );
+```ts
+.dashboard(({ d, c, a }) => d.dashboard({
+  actions: [
+    a.create({ collection: "posts", label: { en: "New Post" }, icon: c.icon("ph:plus"), variant: "primary" }),
+    a.global({ global: "siteSettings", label: { en: "Settings" }, icon: c.icon("ph:gear-six") }),
+    a.link({ href: "/", label: { en: "Open Site" }, icon: c.icon("ph:arrow-square-out"), variant: "outline" }),
+  ],
+  items: [
+    { type: "section", items: [
+      { type: "stats", collection: "posts", label: "Posts" },
+    ]},
+  ],
+}))
 ```
 
-### Sidebar Builder
-
-```typescript
-const sidebarConfig = qa
-  .sidebar()
-  .section("main", (s) =>
-    s.items([
-      { type: "link", label: "Dashboard", href: "/admin", icon: HomeIcon },
-    ]),
-  )
-  .section("content", (s) =>
-    s
-      .title("Content")
-      .items([
-        { type: "collection", collection: "posts" },
-        { type: "collection", collection: "pages" },
-        { type: "divider" },
-        { type: "global", global: "settings" },
-      ]),
-  );
-```
+## Client Setup
 
-**Typed Sidebar (Recommended)**
+The client creates a typed admin builder and mounts the admin UI in React:
 
-```typescript
-import type { AppCMS } from "./server/cms";
-import type { SidebarItemForApp } from "@questpie/admin/client";
+### 1. Admin Builder
 
-const sidebarConfig = qa.sidebar<AppCMS>().section("content", (s) =>
-  s.title("Content").items([
-    { type: "collection", collection: "posts" },
-    { type: "global", global: "settings" },
-  ]),
-);
+```ts
+// questpie/admin/builder.ts
+import { qa, adminModule } from "@questpie/admin/client";
+import type { App } from "#questpie";
 
-// Standalone typed items
-const items: SidebarItemForApp<AppCMS>[] = [
-  { type: "collection", collection: "posts" },
-  { type: "global", global: "settings" },
-];
+export const admin = qa<App>().use(adminModule);
 ```
 
-## Built-in Field Types
-
-The `adminModule` provides these field types:
-
-| Field      | Usage                              | Description                 |
-| ---------- | ---------------------------------- | --------------------------- |
-| `text`     | `r.text({ maxLength })`            | Single-line text input      |
-| `email`    | `r.email()`                        | Email input with validation |
-| `password` | `r.password()`                     | Password input              |
-| `textarea` | `r.textarea({ rows })`             | Multi-line text             |
-| `number`   | `r.number({ min, max })`           | Numeric input               |
-| `checkbox` | `r.checkbox()`                     | Boolean checkbox            |
-| `switch`   | `r.switch()`                       | Toggle switch               |
-| `select`   | `r.select({ options })`            | Dropdown select             |
-| `date`     | `r.date()`                         | Date picker                 |
-| `datetime` | `r.datetime()`                     | Date + time picker          |
-| `relation` | `r.relation({ targetCollection })` | Relation field              |
-| `json`     | `r.json()`                         | JSON editor                 |
-| `richText` | `r.richText()`                     | Rich text editor (Tiptap)   |
-
-## Form Layouts
-
-### Sections
-
-```typescript
-.form(({ v, f }) => v.form({
-  sections: [
-    {
-      title: "Basic Info",
-      description: "Main details",
-      fields: [f.title, f.slug],
-      collapsible: true,
-      defaultOpen: true,
-    },
-    {
-      title: "Content",
-      fields: [f.content],
-    },
-  ],
-}))
-```
+> **Note:** The old `.toNamespace()` call has been removed. `qa<App>().use(adminModule)` is the complete builder.
 
-### Columns Layout
-
-```typescript
-sections: [
-  {
-    title: "Contact",
-    layout: "columns",
-    columns: 2,
-    fields: [f.firstName, f.lastName, f.email, f.phone],
-  },
-];
-```
+### 2. Typed Hooks
 
-### Grid Layout
-
-```typescript
-sections: [
-  {
-    layout: "grid",
-    grid: { columns: 4, gap: 4 },
-    fields: [
-      { field: f.title, span: 4 }, // full width
-      { field: f.price, span: 1 }, // 1/4
-      { field: f.currency, span: 1 }, // 1/4
-      { field: f.stock, span: 2 }, // 2/4
-    ],
-  },
-];
+```ts
+// questpie/admin/hooks.ts
+import { createTypedHooks } from "@questpie/admin/client";
+import type { App } from "#questpie";
+
+export const {
+	useCollectionList,
+	useCollectionItem,
+	useCollectionCreate,
+	useCollectionUpdate,
+	useCollectionDelete,
+	useGlobal,
+	useGlobalUpdate,
+} = createTypedHooks<App>();
 ```
 
-### Tabs
+### 3. Mount in React
 
-```typescript
-.form(({ v, f }) => v.form({
-  tabs: [
-    {
-      id: "content",
-      label: "Content",
-      fields: [f.title, f.content],
-    },
-    {
-      id: "meta",
-      label: "Metadata",
-      fields: [f.seo, f.tags],
-    },
-  ],
-}))
+```tsx
+// routes/admin.tsx
+import { AdminRouter } from "@questpie/admin/client";
+import { admin } from "@/questpie/admin/builder";
+import { appClient } from "@/lib/client";
+import { queryClient } from "@/lib/query-client";
+
+export default function AdminRoute() {
+	return (
+		<AdminRouter
+			admin={admin}
+			client={client}
+			queryClient={queryClient}
+			basePath="/admin"
+		/>
+	);
+}
 ```
 
-### Sidebar Layout
+### 4. Tailwind CSS
 
-```typescript
-.form(({ v, f }) => v.form({
-  layout: "with-sidebar",
-  sections: [
-    { title: "Content", fields: [f.title, f.content] },
-  ],
-  sidebar: {
-    position: "right",
-    width: "300px",
-    fields: [f.status, f.publishedAt],
-  },
-}))
-```
+Import admin styles and scan the admin package:
 
-## Conditional Fields
-
-```typescript
-.fields(({ r }) => ({
-  status: r.select({
-    options: [
-      { label: "Active", value: "active" },
-      { label: "Cancelled", value: "cancelled" },
-    ],
-  }),
-  // Show only when status is "cancelled"
-  cancellationReason: r.textarea({
-    visible: (values) => values.status === "cancelled",
-    required: (values) => values.status === "cancelled",
-  }),
-  // Readonly unless draft
-  publishedAt: r.datetime({
-    readOnly: (values) => values.status !== "draft",
-  }),
-}))
-```
+```css
+@import "tailwindcss";
+@import "@questpie/admin/styles/index.css";
 
-## Relation Fields
-
-```typescript
-.fields(({ r }) => ({
-  // Single relation
-  authorId: r.relation({
-    label: "Author",
-    targetCollection: "users",
-  }),
-  // Multiple relations with ordering
-  tags: r.relation({
-    label: "Tags",
-    targetCollection: "tags",
-    type: "multiple",
-    orderable: true,
-  }),
-}))
+@source "../node_modules/@questpie/admin/dist";
 ```
 
-## Hooks
+## Block Editor
+
+The admin includes a full drag-and-drop block editor. Blocks are defined server-side:
+
+```ts
+const heroBlock = block("hero")
+	.admin(({ c }) => ({
+		label: { en: "Hero Section" },
+		icon: c.icon("ph:image"),
+		category: { label: "Sections", icon: c.icon("ph:layout") },
+	}))
+	.fields(({ f }) => ({
+		title: f.text({ required: true }),
+		subtitle: f.textarea(),
+		backgroundImage: f.upload({ to: "assets", mimeTypes: ["image/*"] }),
+	}))
+	.prefetch({ with: { backgroundImage: true } });
+```
 
-```typescript
-import {
-  useAdminStore,
-  useAdminContext,
-  useCollectionList,
-  useCollectionItem,
-  useCollectionCreate,
-  useCollectionUpdate,
-  useCollectionDelete,
-  useGlobal,
-  useGlobalUpdate,
-  useAuthClient,
-  useAdminRoutes,
-} from "@questpie/admin/client";
+Render blocks on the client with `BlockRenderer`:
 
-// Collection list with pagination
-const { data, isLoading } = useCollectionList("posts", {
-  limit: 10,
-  offset: 0,
+```tsx
+import { BlockRenderer, createBlockRegistry } from "@questpie/admin/client";
+
+const registry = createBlockRegistry({
+	hero: ({ block }) => (
+		<section style={{ backgroundImage: `url(${block.backgroundImage?.url})` }}>
+			<h1>{block.title}</h1>
+			<p>{block.subtitle}</p>
+		</section>
+	),
 });
 
-// Single item
-const { data: post } = useCollectionItem("posts", id);
+function Page({ blocks }) {
+	return <BlockRenderer blocks={blocks} registry={registry} />;
+}
+```
+
+## Actions System
 
-// CRUD mutations
-const createPost = useCollectionCreate("posts");
-const updatePost = useCollectionUpdate("posts");
-const deletePost = useCollectionDelete("posts");
+Collection-level actions with multiple handler types:
 
-// Global data
-const { data: settings } = useGlobal("settings");
-const updateSettings = useGlobalUpdate("settings");
+| Type       | Description                                 |
+| ---------- | ------------------------------------------- |
+| `navigate` | Client-side routing                         |
+| `api`      | HTTP API call                               |
+| `form`     | Dialog with field inputs                    |
+| `server`   | Server-side execution with full app context |
+| `custom`   | Arbitrary client-side code                  |
 
-// Admin store
-const { admin, client, basePath } = useAdminStore((s) => ({
-  admin: s.admin,
-  client: s.client,
-  basePath: s.basePath,
-}));
+Actions can be scoped to `header` (list toolbar), `bulk` (selected items), `single` (per-item), or `row`.
 
-// Auth
-const authClient = useAuthClient();
-const session = authClient.useSession();
+## Realtime
 
-// Routes
-const { routes, navigate } = useAdminRoutes();
-navigate({ collection: "posts", action: "create" });
-```
+SSE-powered live updates are enabled by default. Collection lists and dashboard widgets auto-refresh when data changes.
 
-## Components
+```ts
+// Disable globally
+<AdminRouter admin={admin} client={client} realtime={false} />
 
-```typescript
-import {
-  // Navigation
-  AdminLink,
-  CollectionLink,
-  CollectionCreateLink,
-  CollectionEditLink,
-  GlobalLink,
-  DashboardLink,
-
-  // Fields
-  TextField,
-  EmailField,
-  NumberField,
-  SelectField,
-  CheckboxField,
-  SwitchField,
-  DateField,
-  RelationField,
-  JsonField,
-
-  // UI (shadcn)
-  Button,
-  Card,
-  Dialog,
-  Sheet,
-  Tabs,
-  Table,
-  // ... 27+ shadcn components
-} from "@questpie/admin/client";
+// Disable per collection view
+.list(({ v }) => v.collectionTable({ realtime: false }))
 ```
 
+## URL-Synced Panels
+
+Admin keeps major panel states in URL search params so links are shareable and browser navigation works as expected.
+
+- `sidebar=view-options` - collection list view options sheet
+- `sidebar=history` - version history sidebar (collection/global forms)
+- `sidebar=block-library` - block editor library sidebar
+- `preview=true` - live preview mode (collection form)
+
+Legacy params (`history`, `viewOptions`, and `sidebar=preview`) are still read for backward compatibility.
+
 ## Package Exports
 
-```typescript
-// Main client exports (recommended)
+```ts
+// Client (React components, builder, hooks)
 import {
-  qa,
-  Admin,
-  AdminBuilder,
-  adminModule,
-  AdminProvider,
-  useAdminStore,
-  useCollectionList,
-  useAdminRoutes,
-  AdminLayoutProvider,
-  CollectionList,
-  CollectionForm,
+	qa,
+	adminModule,
+	AdminRouter,
+	createTypedHooks,
+	BlockRenderer,
+	createBlockRegistry,
 } from "@questpie/admin/client";
 
-// Server exports (for backend CMS setup)
-import { adminModule } from "@questpie/admin/server";
+// Server (admin module + plugin for QUESTPIE config)
+import { adminModule, auditModule } from "@questpie/admin/server";
+import { adminPlugin } from "@questpie/admin/plugin";
 
 // Styles
-import "@questpie/admin/client/styles/index.css";
+import "@questpie/admin/styles/index.css";
 ```
 
-## Styling
-
-Built with Tailwind CSS v4 + shadcn/ui:
+## Component Stack
 
-- 27+ pre-built components
-- Light/dark theme support
-- oklch color space
-- Customizable via Tailwind tokens
-- Styles scoped under `.questpie-admin`
+- **Primitives**: `@base-ui/react` (NOT Radix)
+- **Icons**: `@iconify/react` with Phosphor set (`ph:icon-name`)
+- **Styling**: Tailwind CSS v4 + shadcn components
+- **Toast**: `sonner`
 
-## Examples
+## Documentation
 
-See [tanstack-barbershop](../../examples/tanstack-barbershop) for a complete working example.
+Full documentation: [https://questpie.com/docs/admin](https://questpie.com/docs/admin)
 
 ## License