@questpie/admin 2.0.0 → 3.0.1

package/README.md

@@ -19,90 +19,88 @@ bun add @questpie/admin questpie @questpie/tanstack-query @tanstack/react-query
 
 ## Server Setup
 
-The admin module plugs into the QUESTPIE builder on the server:
+Add the admin module to `modules.ts`:
 
 ```ts
-// questpie/server/builder.ts
-import { q } from "questpie";
+// questpie.config.ts
+import { runtimeConfig } from "questpie";
+
+export default runtimeConfig({
+	app: { url: process.env.APP_URL! },
+	db: { url: process.env.DATABASE_URL! },
+	secret: process.env.AUTH_SECRET!,
+});
+```
+
+```ts
+// modules.ts
 import { adminModule } from "@questpie/admin/server";
 
-export const qb = q.use(adminModule);
+export default [adminModule] as const;
 ```
 
-All admin configuration is defined server-side using the builder chain:
+Branding, sidebar, dashboard, and admin locale are configured via `config/admin.ts`:
 
 ```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" },
-          ],
-        }),
-      ],
-    }),
-  )
-  .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: [],
-    }),
-  )
-  .build({ ... });
-
-export type AppCMS = typeof cms;
+// config/admin.ts
+import { adminConfig } from "#questpie/factories";
+
+export default adminConfig({
+	branding: { name: "My Admin" },
+	sidebar: {
+		sections: [
+			{
+				id: "main",
+				title: "Content",
+				items: [{ type: "collection", collection: "posts" }],
+			},
+		],
+	},
+});
 ```
 
+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 = 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(),
-  }))
-  .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({
-      layout: "with-sidebar",
-      sidebar: { position: "right", fields: [f.status, f.publishedAt, f.cover] },
-      fields: [
-        { type: "section", label: "Content", fields: [f.title, f.content] },
-      ],
-    }),
-  );
+const posts = collection("posts")
+	.fields(({ f }) => ({
+		title: f.text(255).required().label("Title"),
+		content: f.richText().label("Content"),
+		status: f
+			.select([
+				{ value: "draft", label: "Draft" },
+				{ value: "published", label: "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] },
+			],
+		}),
+	);
 ```
 
 ### Component References
@@ -122,7 +120,7 @@ Icons use the [Iconify](https://icon-sets.iconify.design/) format with the Phosp
 
 ```ts
 // Sections
-.form(({ v, f }) => v.form({
+.form(({ v, f }) => v.collectionForm({
   fields: [
     { type: "section", label: "Basic Info", layout: "grid", columns: 2,
       fields: [f.name, f.email, f.phone, f.city] },
@@ -131,14 +129,14 @@ Icons use the [Iconify](https://icon-sets.iconify.design/) format with the Phosp
 }))
 
 // Sidebar layout
-.form(({ v, f }) => v.form({
+.form(({ v, f }) => v.collectionForm({
   layout: "with-sidebar",
   sidebar: { position: "right", fields: [f.status, f.image] },
   fields: [f.title, f.content],
 }))
 
 // Tabs
-.form(({ v, f }) => v.form({
+.form(({ v, f }) => v.collectionForm({
   tabs: [
     { id: "content", label: "Content", fields: [f.title, f.body] },
     { id: "meta", label: "Metadata", fields: [f.seoTitle, f.seoDescription] },
@@ -151,7 +149,7 @@ Icons use the [Iconify](https://icon-sets.iconify.design/) format with the Phosp
 Server-evaluated reactive behaviors in form config:
 
 ```ts
-.form(({ v, f }) => v.form({
+.form(({ v, f }) => v.collectionForm({
   fields: [
     {
       field: f.slug,
@@ -170,32 +168,50 @@ Server-evaluated reactive behaviors in form config:
 ### Dashboard Actions
 
 ```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" },
-    ]},
-  ],
-}))
+export default adminConfig({
+	dashboard: {
+		title: "Dashboard",
+		items: [
+			{
+				id: "posts",
+				type: "stats",
+				collection: "posts",
+				label: "Posts",
+			},
+			{
+				id: "quick-actions",
+				type: "quickActions",
+				label: "Quick Actions",
+				actions: [
+					{
+						label: "New Post",
+						action: { type: "create", collection: "posts" },
+					},
+					{
+						label: "Open Site",
+						action: { type: "link", href: "/" },
+					},
+				],
+			},
+		],
+	},
+});
 ```
 
 ## Client Setup
 
-The client creates a typed admin builder and mounts the admin UI in React:
+Codegen creates a typed admin config from the client module registry and the server projection:
 
-### 1. Admin Builder
+### 1. Admin Client Modules
 
 ```ts
-// questpie/admin/builder.ts
-import { qa, adminModule } from "@questpie/admin/client";
-import type { AppCMS } from "../server/cms";
+// questpie/admin/modules.ts
+export { default } from "@questpie/admin/client-module";
+```
 
-export const admin = qa<AppCMS>().use(adminModule);
+```ts
+// questpie/admin/admin.ts
+export { default as admin } from "./.generated/client";
 ```
 
 ### 2. Typed Hooks
@@ -203,17 +219,17 @@ export const admin = qa<AppCMS>().use(adminModule);
 ```ts
 // questpie/admin/hooks.ts
 import { createTypedHooks } from "@questpie/admin/client";
-import type { AppCMS } from "../server/cms";
+import type { App } from "#questpie";
 
 export const {
-  useCollectionList,
-  useCollectionItem,
-  useCollectionCreate,
-  useCollectionUpdate,
-  useCollectionDelete,
-  useGlobal,
-  useGlobalUpdate,
-} = createTypedHooks<AppCMS>();
+	useCollectionList,
+	useCollectionItem,
+	useCollectionCreate,
+	useCollectionUpdate,
+	useCollectionDelete,
+	useGlobal,
+	useGlobalUpdate,
+} = createTypedHooks<App>();
 ```
 
 ### 3. Mount in React
@@ -221,19 +237,19 @@ export const {
 ```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";
+import { admin } from "@/questpie/admin/admin";
+import { appClient } from "@/lib/client";
+import { queryClient } from "@/lib/query-client";
 
 export default function AdminRoute() {
-  return (
-    <AdminRouter
-      admin={admin}
-      client={cmsClient}
-      queryClient={queryClient}
-      basePath="/admin"
-    />
-  );
+	return (
+		<AdminRouter
+			admin={admin}
+			client={appClient}
+			queryClient={queryClient}
+			basePath="/admin"
+		/>
+	);
 }
 ```
 
@@ -253,37 +269,36 @@ Import admin styles and scan the admin package:
 The admin includes a full drag-and-drop block editor. Blocks are defined server-side:
 
 ```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 } });
+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(),
+		subtitle: f.textarea(),
+		backgroundImage: f.upload({ to: "assets", mimeTypes: ["image/*"] }),
+	}))
+	.prefetch({ with: { backgroundImage: true } });
 ```
 
 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} />;
+import { BlockRenderer } from "@questpie/admin/client";
+
+const renderers = {
+	hero: ({ values }) => (
+		<section>
+			<h1>{values.title}</h1>
+			<p>{values.subtitle}</p>
+		</section>
+	),
+};
+
+function Page({ content }) {
+	return <BlockRenderer content={content} renderers={renderers} />;
 }
 ```
 
@@ -310,17 +325,32 @@ SSE-powered live updates are enabled by default. Collection lists and dashboard
 <AdminRouter admin={admin} client={client} realtime={false} />
 
 // Disable per collection view
-.list(({ v }) => v.table({ realtime: false }))
+.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
 
 ```ts
-// Client (React components, builder, hooks)
-import { qa, adminModule, AdminRouter, createTypedHooks, BlockRenderer, createBlockRegistry } from "@questpie/admin/client";
-
-// Server (admin module for QUESTPIE builder)
-import { adminModule, adminRpc } from "@questpie/admin/server";
+// Client (React components, generated admin config, hooks)
+import {
+	AdminRouter,
+	createTypedHooks,
+	BlockRenderer,
+} from "@questpie/admin/client";
+
+// Server (admin module + server factories/config)
+import { adminModule, auditModule } from "@questpie/admin/server";
 
 // Styles
 import "@questpie/admin/styles/index.css";

package/dist/augmentation.d.mts

@@ -205,25 +205,50 @@ interface RelationFieldAdminMeta extends BaseAdminMeta {
   allowEdit?: boolean;
   preload?: boolean;
   maxItems?: number;
+  /**
+   * List table cell rendering for relation values.
+   * - "chip": default text chip
+   * - "avatarChip": chip with avatar image + label
+   */
+  listCell?: {
+    display?: "chip" | "avatarChip";
+    /** Dot-path on related record (e.g. "image" or "avatar.url") */
+    avatarField?: string;
+    /** Dot-path for display label override (e.g. "fullName") */
+    labelField?: string;
+  };
 }
 /**
  * Object field admin options
  */
 interface ObjectFieldAdminMeta extends BaseAdminMeta {
-  displayAs?: "card" | "section" | "inline";
-  collapsible?: boolean;
+  /** Visual wrapper mode */
+  wrapper?: "flat" | "collapsible";
+  /** Field arrangement mode */
+  layout?: "stack" | "inline" | "grid";
+  /** Number of columns (for grid layout) */
+  columns?: number;
+  /** Default collapsed state (for collapsible wrapper) */
   defaultCollapsed?: boolean;
 }
 /**
  * Array field admin options
  */
 interface ArrayFieldAdminMeta extends BaseAdminMeta {
-  displayAs?: "list" | "table" | "cards";
-  collapsible?: boolean;
-  defaultCollapsed?: boolean;
-  addLabel?: string;
-  emptyMessage?: string;
+  /** Enable drag-and-drop reordering */
+  orderable?: boolean;
+  /** Minimum number of items */
+  minItems?: number;
+  /** Maximum number of items */
   maxItems?: number;
+  /** Item editing mode */
+  mode?: "inline" | "modal" | "drawer";
+  /** Field arrangement mode for items */
+  layout?: "stack" | "inline" | "grid";
+  /** Number of columns (for grid layout) */
+  columns?: number;
+  /** Label for array items */
+  itemLabel?: string;
 }
 /**
  * JSON field admin options
@@ -236,8 +261,24 @@ interface JsonFieldAdminMeta extends BaseAdminMeta {
  * Upload field admin options
  */
 interface UploadFieldAdminMeta extends BaseAdminMeta {
-  accept?: string;
+  /** Accepted file types */
+  accept?: string | string[];
+  /** Dropzone placeholder text */
   dropzoneText?: string;
+  /** Show file preview */
+  showPreview?: boolean;
+  /** Allow editing uploaded files */
+  editable?: boolean;
+  /** Preview display variant */
+  previewVariant?: "card" | "compact" | "thumbnail";
+  /** Allow multiple file uploads */
+  multiple?: boolean;
+  /** Maximum number of files */
+  maxItems?: number;
+  /** Enable drag-and-drop reordering */
+  orderable?: boolean;
+  /** Layout for multiple files */
+  layout?: "grid" | "list";
 }
 /**
  * Rich text field admin options
@@ -295,7 +336,7 @@ interface BaseWidgetAdminMeta {
  * ```ts
  * declare module "@questpie/admin" {
  *   interface WidgetTypeRegistry {
- *     myCustomWidget: { fetchFn: (client: any) => Promise<MyData> };
+ *     myCustomWidget: { loader: (client: any) => Promise<MyData> };
  *   }
  * }
  * ```
@@ -310,6 +351,64 @@ interface WidgetTypeRegistry {
   timeline: {};
   progress: {};
 }
+declare global {
+  namespace Questpie {
+    interface TextFieldMeta {
+      admin?: TextFieldAdminMeta;
+    }
+    interface EmailFieldMeta {
+      admin?: EmailFieldAdminMeta;
+    }
+    interface UrlFieldMeta {
+      admin?: UrlFieldAdminMeta;
+    }
+    interface TextareaFieldMeta {
+      admin?: TextareaFieldAdminMeta;
+    }
+    interface NumberFieldMeta {
+      admin?: NumberFieldAdminMeta;
+    }
+    interface BooleanFieldMeta {
+      admin?: BooleanFieldAdminMeta;
+    }
+    interface DateFieldMeta {
+      admin?: DateFieldAdminMeta;
+    }
+    interface DatetimeFieldMeta {
+      admin?: DateFieldAdminMeta;
+    }
+    interface TimeFieldMeta {
+      admin?: TimeFieldAdminMeta;
+    }
+    interface SelectFieldMeta {
+      admin?: SelectFieldAdminMeta;
+    }
+    interface RelationFieldMeta {
+      admin?: RelationFieldAdminMeta;
+    }
+    interface ObjectFieldMeta {
+      admin?: ObjectFieldAdminMeta;
+    }
+    interface ArrayFieldMeta {
+      admin?: ArrayFieldAdminMeta;
+    }
+    interface JsonFieldMeta {
+      admin?: JsonFieldAdminMeta;
+    }
+    interface UploadFieldMeta {
+      admin?: UploadFieldAdminMeta;
+    }
+  }
+}
+declare module "./server/fields/rich-text.js" {
+  interface RichTextFieldMeta {
+    admin?: RichTextFieldAdminMeta;
+  }
+}
+declare module "./server/fields/blocks.js" {
+  interface BlocksFieldMeta {
+    admin?: BlocksFieldAdminMeta;
+  }
+}
 //#endregion
-export { AnyAdminMeta, ArrayFieldAdminMeta, BaseAdminMeta, BaseWidgetAdminMeta, BooleanFieldAdminMeta, DateFieldAdminMeta, JsonFieldAdminMeta, NumberFieldAdminMeta, ObjectFieldAdminMeta, RelationFieldAdminMeta, SelectFieldAdminMeta, TextFieldAdminMeta, TextareaFieldAdminMeta, TimeFieldAdminMeta, UploadFieldAdminMeta, WidgetTypeRegistry };
-//# sourceMappingURL=augmentation.d.mts.map
+export { AnyAdminMeta, ArrayFieldAdminMeta, BaseAdminMeta, BaseWidgetAdminMeta, BooleanFieldAdminMeta, DateFieldAdminMeta, JsonFieldAdminMeta, NumberFieldAdminMeta, ObjectFieldAdminMeta, RelationFieldAdminMeta, SelectFieldAdminMeta, TextFieldAdminMeta, TextareaFieldAdminMeta, TimeFieldAdminMeta, UploadFieldAdminMeta, WidgetTypeRegistry };

package/dist/client/blocks/block-renderer.d.mts

@@ -1,6 +1,6 @@
 import { BlockContent } from "./types.mjs";
-import * as React$1 from "react";
-import * as react_jsx_runtime24 from "react/jsx-runtime";
+import * as React from "react";
+import * as react_jsx_runtime22 from "react/jsx-runtime";
 
 //#region src/client/blocks/block-renderer.d.ts
 
@@ -8,13 +8,7 @@ import * as react_jsx_runtime24 from "react/jsx-runtime";
  * Block renderer function type.
  * Consumers provide their own renderers mapped by block type.
  */
-type BlockRendererFn = (props: {
-  id: string;
-  type: string;
-  values: Record<string, unknown>;
-  data?: Record<string, unknown>;
-  children?: React$1.ReactNode;
-}) => React$1.ReactNode;
+type BlockRendererFn = (props: any) => React.ReactNode;
 /**
  * Props for BlockRenderer component.
  */
@@ -46,7 +40,6 @@ declare function BlockRenderer({
   selectedBlockId,
   onBlockClick,
   className
-}: BlockRendererProps): react_jsx_runtime24.JSX.Element | null;
+}: BlockRendererProps): react_jsx_runtime22.JSX.Element | null;
 //#endregion
-export { BlockRenderer, BlockRendererProps };
-//# sourceMappingURL=block-renderer.d.mts.map
+export { BlockRenderer, BlockRendererProps };