@questpie/admin 1.1.1 → 2.0.0

package/README.md

@@ -1,453 +1,211 @@
 # @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 module plugs into the QUESTPIE builder on the server:
 
-```typescript
-// src/admin/builder.ts
-import { qa, adminModule } from "@questpie/admin/client";
-import type { AppCMS } from "./server/cms";
+```ts
+// questpie/server/builder.ts
+import { q } from "questpie";
+import { adminModule } from "@questpie/admin/server";
 
-// Create typed builder with admin fields/views
-export const qab = qa<AppCMS>().use(adminModule).toNamespace();
+export const qb = q.use(adminModule);
 ```
 
-### 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" },
+All admin configuration is defined server-side using the builder chain:
+
+```ts
+// questpie/server/cms.ts
+import { qb } from "./builder";
+
+export const cms = qb
+  .collections({ posts, pages })
+  .globals({ siteSettings })
+  .branding({ name: { en: "My Admin Panel" } })
+  .sidebar(({ s, c }) =>
+    s.sidebar({
+      sections: [
+        s.section({
+          id: "content",
+          title: { en: "Content" },
+          items: [
+            { type: "link", label: "Dashboard", href: "/admin", icon: c.icon("ph:house") },
+            { type: "collection", collection: "posts" },
+            { type: "collection", collection: "pages" },
+            { type: "divider" },
+            { type: "global", global: "siteSettings" },
+          ],
+        }),
       ],
     }),
-    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],
-        },
+  .dashboard(({ d, c, a }) =>
+    d.dashboard({
+      title: { en: "Dashboard" },
+      actions: [
+        a.create({ collection: "posts", label: { en: "New Post" }, icon: c.icon("ph:plus") }),
+        a.global({ global: "siteSettings", label: { en: "Settings" }, icon: c.icon("ph:gear-six") }),
       ],
+      items: [],
     }),
-  );
-```
-
-### 3. Build Admin Configuration
-
-```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;
-  }
-}
-```
-
-### 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 }]),
-  );
-```
-
-### 5. Setup Tailwind CSS
+  .build({ ... });
 
-In your main CSS file, import admin styles and configure Tailwind to scan the admin package:
-
-```css
-/* src/styles.css */
-@import "tailwindcss";
-@import "tw-animate-css";
-@import "shadcn/tailwind.css";
-@import "@questpie/admin/styles/index.css";
-
-/* IMPORTANT: Tell Tailwind to scan admin package for utility classes */
-@source "../node_modules/@questpie/admin/dist";
-
-/* Your app's theme variables... */
-```
-
-### 6. Mount in React
-
-```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>
-  );
-}
+export type AppCMS = typeof cms;
 ```
 
-## Builder API
+### Collection Admin Config
 
-### Main Entry Point
-
-```typescript
-import { qa, adminModule } from "@questpie/admin/client";
+Admin metadata, list views, and form views are defined on the collection itself:
 
-// 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);
-```
-
-### 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: [...] }),
+```ts
+const posts = qb.collection("posts")
+  .fields((f) => ({
+    title: f.text({ label: "Title", required: true }),
+    content: f.richText({ label: "Content" }),
+    status: f.select({ label: "Status", options: ["draft", "published"] }),
+    cover: f.upload({ to: "assets", mimeTypes: ["image/*"] }),
+    publishedAt: f.date(),
   }))
-  .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],
-  }));
-```
-
-### 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
+  .title(({ f }) => f.title)
+  .admin(({ c }) => ({
+    label: { en: "Blog Posts" },
+    icon: c.icon("ph:article"),
   }))
+  .list(({ v, f }) =>
+    v.table({
+      columns: [f.title, f.status, f.publishedAt],
+    }),
+  )
   .form(({ v, f }) =>
     v.form({
-      fields: [f.siteName, f.logo],
+      layout: "with-sidebar",
+      sidebar: { position: "right", fields: [f.status, f.publishedAt, f.cover] },
+      fields: [
+        { type: "section", label: "Content", fields: [f.title, f.content] },
+      ],
     }),
   );
 ```
 
-### 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" },
-      ]),
-  );
-```
-
-**Typed Sidebar (Recommended)**
-
-```typescript
-import type { AppCMS } from "./server/cms";
-import type { SidebarItemForApp } from "@questpie/admin/client";
+### Component References
 
-const sidebarConfig = qa.sidebar<AppCMS>().section("content", (s) =>
-  s.title("Content").items([
-    { type: "collection", collection: "posts" },
-    { type: "global", global: "settings" },
-  ]),
-);
+The server emits serializable `ComponentReference` objects instead of React elements. Use the `c` factory in admin config callbacks:
 
-// Standalone typed items
-const items: SidebarItemForApp<AppCMS>[] = [
-  { type: "collection", collection: "posts" },
-  { type: "global", global: "settings" },
-];
+```ts
+.admin(({ c }) => ({
+  icon: c.icon("ph:article"),       // → { type: "icon", props: { name: "ph:article" } }
+  badge: c.badge({ text: "New" }),   // → { type: "badge", props: { text: "New" } }
+}))
 ```
 
-## Built-in Field Types
-
-The `adminModule` provides these field types:
+Icons use the [Iconify](https://icon-sets.iconify.design/) format with the Phosphor set (`ph:icon-name`).
 
-| 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
 
-## Form Layouts
+```ts
+// Sections
+.form(({ v, f }) => v.form({
+  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] },
+  ],
+}))
 
-### Sections
+// Sidebar layout
+.form(({ v, f }) => v.form({
+  layout: "with-sidebar",
+  sidebar: { position: "right", fields: [f.status, f.image] },
+  fields: [f.title, f.content],
+}))
 
-```typescript
+// Tabs
 .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],
-    },
+  tabs: [
+    { id: "content", label: "Content", fields: [f.title, f.body] },
+    { id: "meta", label: "Metadata", fields: [f.seoTitle, f.seoDescription] },
   ],
 }))
 ```
 
-### Columns Layout
-
-```typescript
-sections: [
-  {
-    title: "Contact",
-    layout: "columns",
-    columns: 2,
-    fields: [f.firstName, f.lastName, f.email, f.phone],
-  },
-];
-```
+### Reactive Fields
 
-### 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
-    ],
-  },
-];
-```
-
-### Tabs
+Server-evaluated reactive behaviors in form config:
 
-```typescript
+```ts
 .form(({ v, f }) => v.form({
-  tabs: [
+  fields: [
     {
-      id: "content",
-      label: "Content",
-      fields: [f.title, f.content],
-    },
-    {
-      id: "meta",
-      label: "Metadata",
-      fields: [f.seo, f.tags],
+      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" },
   ],
 }))
 ```
 
-### Sidebar Layout
+### Dashboard Actions
 
-```typescript
-.form(({ v, f }) => v.form({
-  layout: "with-sidebar",
-  sections: [
-    { title: "Content", fields: [f.title, f.content] },
+```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: {
-    position: "right",
-    width: "300px",
-    fields: [f.status, f.publishedAt],
-  },
 }))
 ```
 
-## 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",
-  }),
-}))
-```
+## Client Setup
 
-## 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,
-  }),
-}))
+The client creates a typed admin builder and mounts the admin UI in React:
+
+### 1. Admin Builder
+
+```ts
+// questpie/admin/builder.ts
+import { qa, adminModule } from "@questpie/admin/client";
+import type { AppCMS } from "../server/cms";
+
+export const admin = qa<AppCMS>().use(adminModule);
 ```
 
-## Hooks
+### 2. Typed Hooks
 
-```typescript
-import {
-  useAdminStore,
-  useAdminContext,
+```ts
+// questpie/admin/hooks.ts
+import { createTypedHooks } from "@questpie/admin/client";
+import type { AppCMS } from "../server/cms";
+
+export const {
   useCollectionList,
   useCollectionItem,
   useCollectionCreate,
@@ -455,116 +213,129 @@ import {
   useCollectionDelete,
   useGlobal,
   useGlobalUpdate,
-  useAuthClient,
-  useAdminRoutes,
-} from "@questpie/admin/client";
-
-// Collection list with pagination
-const { data, isLoading } = useCollectionList("posts", {
-  limit: 10,
-  offset: 0,
-});
+} = createTypedHooks<AppCMS>();
+```
+
+### 3. Mount in React
+
+```tsx
+// routes/admin.tsx
+import { AdminRouter } from "@questpie/admin/client";
+import { admin } from "~/questpie/admin/builder";
+import { cmsClient } from "~/lib/cms-client";
+import { queryClient } from "~/lib/query-client";
+
+export default function AdminRoute() {
+  return (
+    <AdminRouter
+      admin={admin}
+      client={cmsClient}
+      queryClient={queryClient}
+      basePath="/admin"
+    />
+  );
+}
+```
 
-// Single item
-const { data: post } = useCollectionItem("posts", id);
+### 4. Tailwind CSS
 
-// CRUD mutations
-const createPost = useCollectionCreate("posts");
-const updatePost = useCollectionUpdate("posts");
-const deletePost = useCollectionDelete("posts");
+Import admin styles and scan the admin package:
 
-// Global data
-const { data: settings } = useGlobal("settings");
-const updateSettings = useGlobalUpdate("settings");
+```css
+@import "tailwindcss";
+@import "@questpie/admin/styles/index.css";
 
-// Admin store
-const { admin, client, basePath } = useAdminStore((s) => ({
-  admin: s.admin,
-  client: s.client,
-  basePath: s.basePath,
-}));
+@source "../node_modules/@questpie/admin/dist";
+```
+
+## Block Editor
 
-// Auth
-const authClient = useAuthClient();
-const session = authClient.useSession();
+The admin includes a full drag-and-drop block editor. Blocks are defined server-side:
 
-// Routes
-const { routes, navigate } = useAdminRoutes();
-navigate({ collection: "posts", action: "create" });
+```ts
+const heroBlock = qb
+  .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 } });
 ```
 
-## Components
-
-```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";
+Render blocks on the client with `BlockRenderer`:
+
+```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>
+  ),
+});
+
+function Page({ blocks }) {
+  return <BlockRenderer blocks={blocks} registry={registry} />;
+}
+```
+
+## Actions System
+
+Collection-level actions with multiple handler types:
+
+| 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                  |
+
+Actions can be scoped to `header` (list toolbar), `bulk` (selected items), `single` (per-item), or `row`.
+
+## Realtime
+
+SSE-powered live updates are enabled by default. Collection lists and dashboard widgets auto-refresh when data changes.
+
+```ts
+// Disable globally
+<AdminRouter admin={admin} client={client} realtime={false} />
+
+// Disable per collection view
+.list(({ v }) => v.table({ realtime: false }))
 ```
 
 ## Package Exports
 
-```typescript
-// Main client exports (recommended)
-import {
-  qa,
-  Admin,
-  AdminBuilder,
-  adminModule,
-  AdminProvider,
-  useAdminStore,
-  useCollectionList,
-  useAdminRoutes,
-  AdminLayoutProvider,
-  CollectionList,
-  CollectionForm,
-} from "@questpie/admin/client";
+```ts
+// Client (React components, builder, hooks)
+import { 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 for QUESTPIE builder)
+import { adminModule, adminRpc } from "@questpie/admin/server";
 
 // 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