create-questpie 2.0.0 → 2.0.2

package/skills/questpie-admin/AGENTS.md

@@ -0,0 +1,1442 @@
+# QUESTPIE Admin Panel
+
+The QUESTPIE admin panel is a **projection of your server schema** — not the framework itself. It reads collections, globals, and config via introspection and generates a full admin interface. Your backend works without it.
+
+## Reference Topics
+
+| Topic     | File                      | Covers                                                                                 |
+| --------- | ------------------------- | -------------------------------------------------------------------------------------- |
+| Views     | `references/views.md`     | List views, form views, dashboard, sidebar, filters, bulk actions, visibility, history |
+| Blocks    | `references/blocks.md`    | Block definitions, fields, prefetch, renderers, block picker                           |
+| Custom UI | `references/custom-ui.md` | Custom fields, custom views, registries, reactive fields, widgets                      |
+
+## Full Compiled Document
+
+For the complete admin reference with all topics expanded: `AGENTS.md`
+
+## Tech Stack
+
+- **React** + **Tailwind CSS v4** + **shadcn** components
+- **@base-ui/react** primitives (NOT @radix-ui)
+- **@iconify/react** with Phosphor icon set (`ph:icon-name`)
+- **sonner** for toasts — `toast.error()`, `toast.success()`
+- Brutalist flat design: `--radius: 0px`, no shadows
+
+## Setup
+
+### 1. Install
+
+```bash
+bun add @questpie/admin
+```
+
+### 2. Runtime Config
+
+```ts title="questpie.config.ts"
+import { runtimeConfig } from "questpie";
+
+export default runtimeConfig({
+	app: { url: process.env.APP_URL || "http://localhost:3000" },
+	db: { url: process.env.DATABASE_URL },
+	secret: process.env.APP_SECRET,
+});
+```
+
+The admin module contributes the codegen plugin automatically. It discovers `config/admin.ts`, `blocks/`, views, components, and admin client modules.
+
+### 3. Modules
+
+```ts title="modules.ts"
+import { adminModule, auditModule } from "@questpie/admin/server";
+
+export default [adminModule, auditModule] as const;
+```
+
+| Module        | Provides                              |
+| ------------- | ------------------------------------- |
+| `adminModule` | User collection, auth pages, admin UI |
+| `auditModule` | Audit log collection, timeline widget |
+
+### 4. Admin Config
+
+```ts title="config/admin.ts"
+import { adminConfig } from "#questpie/factories";
+
+export default adminConfig({
+	branding: {
+		name: { en: "My App Admin" },
+	},
+	sidebar: {
+		sections: [
+			{ id: "overview", title: { en: "Overview" } },
+			{ id: "content", title: { en: "Content" } },
+		],
+		items: [
+			{
+				sectionId: "overview",
+				type: "link",
+				label: { en: "Dashboard" },
+				href: "/admin",
+				icon: { type: "icon", props: { name: "ph:house" } },
+			},
+			{
+				sectionId: "content",
+				type: "collection",
+				collection: "posts",
+			},
+		],
+	},
+});
+```
+
+### 5. Codegen
+
+```bash
+bunx questpie generate
+```
+
+### 6. Mount the Admin
+
+```ts title="routes/admin/$.tsx"
+import { AdminRouter } from "@questpie/admin/client";
+import { admin } from "@/questpie/admin/admin";
+
+export default function AdminPage() {
+  return <AdminRouter admin={admin} />;
+}
+```
+
+The admin client config is auto-generated by codegen at `admin/.generated/client.ts`. No manual builder setup needed.
+
+## Branding
+
+```ts title="config/admin.ts"
+import { adminConfig } from "#questpie/factories";
+
+export default adminConfig({
+	branding: {
+		name: { en: "Barbershop Control", sk: "Riadenie barbershopu" },
+	},
+});
+```
+
+| Option | Type             | Description                      |
+| ------ | ---------------- | -------------------------------- |
+| `name` | `string \| i18n` | App name shown in sidebar header |
+| `logo` | `string`         | Logo URL or path                 |
+
+## Theming (CSS Variables)
+
+The admin uses CSS variables for all theming. Override them in your own CSS file.
+
+### Light Theme (`:root`)
+
+| Variable               | Default   | Purpose                          |
+| ---------------------- | --------- | -------------------------------- |
+| `--background`         | `#FFFFFF` | Page background                  |
+| `--foreground`         | `#0A0A0A` | Primary text                     |
+| `--card`               | `#F8F8F8` | Cards, panels, sidebar           |
+| `--popover`            | `#FFFFFF` | Dropdowns, tooltips, dialogs     |
+| `--muted`              | `#F0F0F0` | Hover states, table headers      |
+| `--muted-foreground`   | `#666666` | Secondary text, placeholders     |
+| `--primary`            | `#B700FF` | Brand accent (CTAs, focus rings) |
+| `--primary-foreground` | `#FFFFFF` | Text on primary backgrounds      |
+| `--destructive`        | `#FF3D57` | Errors, delete actions           |
+| `--success`            | `#00E676` | Positive states                  |
+| `--warning`            | `#FFB300` | Caution states                   |
+| `--info`               | `#40C4FF` | Informational emphasis           |
+| `--border`             | `#E0E0E0` | All structural borders           |
+| `--ring`               | `#B700FF` | Focus ring color                 |
+| `--radius`             | `0px`     | Border radius (0 = brutalist)    |
+
+### Dark Theme (`.dark` class)
+
+Dark mode uses the `.dark` class on the root element. Key overrides:
+
+| Variable       | Dark Value |
+| -------------- | ---------- |
+| `--background` | `#0A0A0A`  |
+| `--foreground` | `#FFFFFF`  |
+| `--card`       | `#111111`  |
+| `--border`     | `#333333`  |
+| `--muted`      | `#1A1A1A`  |
+
+### Typography
+
+| Variable      | Value                                                               |
+| ------------- | ------------------------------------------------------------------- |
+| `--font-sans` | `"Geist Variable"` — body text, descriptions                        |
+| `--font-mono` | `"JetBrains Mono Variable"` — UI chrome: nav, buttons, tabs, badges |
+
+### Sidebar Variables
+
+Separate tokens for independent sidebar theming: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-accent`, `--sidebar-border`, `--sidebar-ring`.
+
+### Custom Theme
+
+1. Copy the admin CSS file
+2. Change variable values
+3. Import your copy instead
+4. Zero component changes needed
+
+## Content Localization
+
+When collections have `.localized()` fields, the admin shows a locale switcher:
+
+```ts title="config/app.ts"
+import { appConfig } from "questpie";
+
+export default appConfig({
+	locale: {
+		locales: [
+			{ code: "en", label: { en: "English" }, flagCountryCode: "gb" },
+			{ code: "sk", label: { en: "Slovak" } },
+		],
+		defaultLocale: "en",
+	},
+});
+```
+
+The admin tracks content locale separately from UI locale. Only localized field values change when switching.
+
+## Media & Uploads
+
+```ts
+avatar: f.upload({
+  to: "assets",
+  mimeTypes: ["image/*"],
+  maxSize: 5_000_000,
+}),
+```
+
+The admin renders drag-and-drop upload, image preview, file info, and remove button.
+
+## Live Preview
+
+Live Preview uses a split-screen iframe. The current implementation refreshes the iframe after save/autosave and uses `postMessage` for field/block focus sync.
+
+Preview V2 patch-based docs are design notes until `useQuestpiePreview`, `PreviewRoot`, and `PreviewBlock` are exported.
+
+### Server Config
+
+Add `.preview()` to a collection to enable split-screen editing:
+
+```ts title="collections/pages.ts"
+export const pages = collection("pages")
+	.fields(({ f }) => ({
+		title: f.text().required().localized(),
+		slug: f.text().required(),
+		content: f.blocks().localized(),
+	}))
+	.preview({
+		enabled: true,
+		position: "right",
+		defaultWidth: 50,
+		url: ({ record }) => {
+			const slug = record.slug as string;
+			return slug === "home" ? "/?preview=true" : `/${slug}?preview=true`;
+		},
+	});
+```
+
+Current preview refreshes the iframe after save/autosave and supports field focus through `postMessage`.
+
+### Frontend Integration
+
+Use `useCollectionPreview` with `PreviewProvider` and `PreviewField`:
+
+```tsx
+import {
+	PreviewField,
+	PreviewProvider,
+	useCollectionPreview,
+} from "@questpie/admin/client";
+
+function PagePreview({ initialData }) {
+	const router = useRouter();
+	const preview = useCollectionPreview({
+		initialData,
+		onRefresh: () => router.invalidate(),
+	});
+
+	return (
+		<PreviewProvider
+			isPreviewMode={preview.isPreviewMode}
+			focusedField={preview.focusedField}
+			onFieldClick={preview.handleFieldClick}
+		>
+			<PreviewField field="title" as="h1">
+				{preview.data.title}
+			</PreviewField>
+		</PreviewProvider>
+	);
+}
+```
+
+### Key Principles
+
+- Current preview = save/autosave refresh plus field/block focus sync
+- `useCollectionPreview` sends `PREVIEW_READY`, `FIELD_CLICKED`, and `BLOCK_CLICKED`
+- `PreviewProvider` supplies preview context to `PreviewField`
+- Each message carries `sessionId`, `seq`, `timestamp`, `protocolVersion`
+- Preview wrappers must prevent accidental navigation in the iframe
+
+## History & Versions
+
+Enable `auditModule` for activity timeline. Enable versioning on collections for snapshot restore:
+
+```ts
+export const pages = collection("pages")
+  .fields(({ f }) => ({ ... }))
+  .options({ versioning: true });
+```
+
+## Scope (Multi-Tenancy)
+
+The admin provides scope primitives for multi-tenant applications. Import from `@questpie/admin/client`.
+
+### ScopeProvider
+
+Wraps the admin to enable scope selection. Manages scope ID in React state and persists to localStorage.
+
+```tsx
+import { ScopeProvider } from "@questpie/admin/client";
+
+<ScopeProvider
+	headerName="x-selected-workspace" // HTTP header for scope ID
+	storageKey="admin-workspace" // localStorage key
+	defaultScope={null} // default value
+>
+	<AdminLayout>...</AdminLayout>
+</ScopeProvider>;
+```
+
+### ScopePicker
+
+Dropdown for selecting the current scope. Place in sidebar via `slots.afterBrand`:
+
+```tsx
+import { ScopePicker } from "@questpie/admin/client";
+
+<AdminLayout
+	admin={admin}
+	basePath="/admin"
+	slots={{
+		afterBrand: (
+			<div className="px-3 py-2 border-b">
+				<ScopePicker
+					collection="workspaces"
+					labelField="name"
+					allowClear
+					compact
+				/>
+			</div>
+		),
+	}}
+/>;
+```
+
+Three data sources: `collection` (queries a collection), `options` (static array), `loadOptions` (async function).
+
+### useScopedFetch / createScopedFetch
+
+Inject scope header into all API calls:
+
+```tsx
+import { useScopedFetch, createScopedFetch } from "@questpie/admin/client";
+
+// React hook
+const scopedFetch = useScopedFetch();
+const client = useMemo(
+	() => createClient({ baseURL: "/api", fetch: scopedFetch }),
+	[scopedFetch],
+);
+
+// Non-React
+const scopedFetch = createScopedFetch("x-selected-workspace", () =>
+	getScopeId(),
+);
+```
+
+### useScope / useScopeSafe
+
+Access current scope state in any component:
+
+```tsx
+import { useScope, useScopeSafe } from "@questpie/admin/client";
+
+const { scopeId, setScope, clearScope, headerName } = useScope(); // throws outside ScopeProvider
+const scope = useScopeSafe(); // returns null outside ScopeProvider
+```
+
+For the full server-side setup (context resolver, type augmentation, access rules), see the `questpie` skill's `references/multi-tenancy.md`.
+
+## Common Mistakes
+
+1. **CRITICAL: Using `asChild` prop** — QUESTPIE admin uses `@base-ui/react`, which uses the `render` prop. `asChild` is a Radix pattern and does NOT work here.
+
+   ```tsx
+   // WRONG
+   <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+   // CORRECT
+   <DialogTrigger render={<Button>Open</Button>} />
+   ```
+
+2. **CRITICAL: Importing from `@radix-ui/*`** — use `@base-ui/react` instead.
+
+3. **HIGH: Using `@phosphor-icons/react`** — use `@iconify/react` with `ph:` prefix.
+
+   ```tsx
+   // WRONG
+   import { CaretDown } from "@phosphor-icons/react";
+   // CORRECT
+   import { Icon } from "@iconify/react";
+   <Icon icon="ph:caret-down" width={16} height={16} />;
+   ```
+
+4. **HIGH: Using lucide-react icons** — use `@iconify/react` with Phosphor icon set.
+
+5. **MEDIUM: Custom `<button>` or `<div>` instead of shadcn components** — use `<Button>`, `<Card>`, etc.
+
+6. **MEDIUM: `console.error` for user errors** — use `toast.error()` from `sonner`.
+
+---
+
+# QUESTPIE Admin Views
+
+This skill builds on questpie-admin.
+
+Views control how data appears in the QUESTPIE admin panel. They are configured **server-side** on collections and globals, then rendered by the admin client via registries.
+
+```text
+Server Config                     Admin UI
+.list(({ v }) => v.collectionTable({}))   ->  Table with columns, sort, search
+.form(({ v, f }) => v.collectionForm({})) ->  Form with sections, sidebar, tabs
+sidebar({...})                 ->  Navigation sidebar
+dashboard({...})               ->  Dashboard with widgets
+```
+
+## List Views
+
+Configure table views with `.list()` on a collection.
+
+### Basic Table
+
+```ts
+.list(({ v }) => v.collectionTable({}))
+```
+
+Shows all fields as columns with default rendering.
+
+### Custom Columns and Search
+
+```ts
+.list(({ v, f }) =>
+  v.collectionTable({
+    columns: [f.name, f.email, f.isActive, f.createdAt],
+    searchableFields: [f.name, f.email],
+    defaultSort: { field: f.createdAt, direction: "desc" },
+  }),
+)
+```
+
+| Option             | Type                   | Description                    |
+| ------------------ | ---------------------- | ------------------------------ |
+| `columns`          | `Field[]`              | Fields to show as columns      |
+| `searchableFields` | `Field[]`              | Fields included in text search |
+| `defaultSort`      | `{ field, direction }` | Default sort order             |
+
+## Form Views
+
+Configure edit forms with `.form()`.
+
+### Basic Form
+
+```ts
+.form(({ v, f }) => v.collectionForm({}))
+```
+
+Renders all fields in a single column.
+
+### Sections
+
+Group fields into labeled sections with optional grid layout:
+
+```ts
+.form(({ v, f }) =>
+  v.collectionForm({
+    fields: [
+      {
+        type: "section",
+        label: { en: "Contact Information" },
+        layout: "grid",
+        columns: 2,
+        fields: [f.name, f.email, f.phone],
+      },
+      {
+        type: "section",
+        label: { en: "Profile" },
+        fields: [f.bio],
+      },
+    ],
+  }),
+)
+```
+
+| Option        | Type                | Description                          |
+| ------------- | ------------------- | ------------------------------------ |
+| `type`        | `"section"`         | Required                             |
+| `label`       | `string \| i18n`    | Section heading                      |
+| `description` | `string \| i18n`    | Section description                  |
+| `layout`      | `"grid" \| "stack"` | Field layout                         |
+| `columns`     | `number`            | Grid columns (with `layout: "grid"`) |
+| `fields`      | `Field[]`           | Fields in this section               |
+
+### Form Sidebar
+
+Place fields in a right sidebar panel:
+
+```ts
+.form(({ v, f }) =>
+  v.collectionForm({
+    sidebar: {
+      position: "right",
+      fields: [f.isActive, f.avatar, f.status],
+    },
+    fields: [ /* main content sections */ ],
+  }),
+)
+```
+
+### Computed Fields
+
+Auto-compute values from other fields:
+
+```ts
+{
+  field: f.slug,
+  compute: {
+    handler: ({ data }) => {
+      if (data.name && !data.slug?.trim()) {
+        return slugify(data.name);
+      }
+      return undefined;
+    },
+    deps: ({ data }) => [data.name, data.slug],
+    debounce: 300,
+  },
+}
+```
+
+| Option     | Type             | Description              |
+| ---------- | ---------------- | ------------------------ |
+| `handler`  | `(ctx) => value` | Compute function         |
+| `deps`     | `(ctx) => any[]` | Reactive dependencies    |
+| `debounce` | `number`         | Debounce in milliseconds |
+
+### Conditional Visibility
+
+Show or hide fields based on other field values:
+
+```ts
+{
+  field: f.cancellationReason,
+  hidden: ({ data }) => data.status !== "cancelled",
+}
+```
+
+Read-only fields:
+
+```ts
+{
+  field: f.customerName,
+  readOnly: ({ data }) => !!data.customer,
+}
+```
+
+Section-level visibility:
+
+```ts
+{
+  type: "section",
+  label: { en: "SEO" },
+  hidden: ({ data }) => !data.isPublished,
+  fields: [f.metaTitle, f.metaDescription],
+}
+```
+
+## Dashboard
+
+Configure in `config/admin.ts` under the `dashboard` key:
+
+```ts title="config/admin.ts"
+import { adminConfig } from "#questpie/factories";
+
+export default adminConfig({
+	dashboard: {
+		title: { en: "Dashboard" },
+		description: { en: "Overview of your app" },
+		columns: 4,
+		actions: [
+			{
+				id: "new-post",
+				href: "/admin/collections/posts?create=true",
+				label: { en: "New Post" },
+				icon: { type: "icon", props: { name: "ph:plus" } },
+				variant: "primary",
+			},
+		],
+		sections: [
+			{ id: "today", label: { en: "Today" }, layout: "grid", columns: 4 },
+			{ id: "business", label: { en: "Business" }, layout: "grid", columns: 4 },
+		],
+		items: [
+			/* widget items — see widget types below */
+		],
+	},
+});
+```
+
+### Widget Types
+
+**Stats** — count records with optional filter:
+
+```ts
+{
+  sectionId: "today",
+  id: "pending",
+  type: "stats",
+  collection: "appointments",
+  label: { en: "Pending" },
+  filter: { status: "pending" },
+  span: 1,
+}
+```
+
+**Value** — custom-loaded value with trend:
+
+```ts
+{
+  sectionId: "business",
+  id: "revenue",
+  type: "value",
+  span: 2,
+  refreshInterval: 1000 * 60 * 5,
+  loader: async ({ app }) => ({
+    value: 42000,
+    formatted: "42,000 EUR",
+    label: { en: "Monthly Revenue" },
+    trend: { value: "+12%" },
+  }),
+}
+```
+
+**Progress** — progress bar toward a goal:
+
+```ts
+{
+  sectionId: "business",
+  id: "goal",
+  type: "progress",
+  span: 1,
+  showPercentage: true,
+  label: { en: "Monthly Goal" },
+  loader: async ({ app }) => ({ current: 350, target: 500 }),
+}
+```
+
+**Chart** — chart from field values:
+
+```ts
+{
+  sectionId: "business",
+  id: "by-status",
+  type: "chart",
+  collection: "appointments",
+  field: "status",
+  chartType: "pie",
+  label: { en: "By Status" },
+  span: 1,
+}
+```
+
+**Recent Items** — list recent records:
+
+```ts
+{
+  sectionId: "ops",
+  id: "recent",
+  type: "recentItems",
+  collection: "appointments",
+  label: { en: "Recent" },
+  limit: 6,
+  dateField: "scheduledAt",
+  span: 2,
+}
+```
+
+**Timeline** — activity stream:
+
+```ts
+{
+  sectionId: "ops",
+  id: "activity",
+  type: "timeline",
+  label: { en: "Activity" },
+  maxItems: 8,
+  showTimestamps: true,
+  timestampFormat: "relative",
+  loader: async ({ app }) => {
+    const res = await app.collections.appointments.find({
+      limit: 8,
+      orderBy: { updatedAt: "desc" },
+    });
+    return res.docs.map((apt) => ({
+      id: apt.id,
+      title: apt.displayTitle,
+      description: `Status: ${apt.status}`,
+      timestamp: apt.updatedAt,
+      variant: apt.status === "completed" ? "success" : "warning",
+      href: `/admin/collections/appointments/${apt.id}`,
+    }));
+  },
+  span: 2,
+}
+```
+
+## Sidebar
+
+Configure in `config/admin.ts` under the `sidebar` key:
+
+```ts title="config/admin.ts"
+import { adminConfig } from "#questpie/factories";
+
+export default adminConfig({
+	sidebar: {
+		sections: [
+			{ id: "overview", title: { en: "Overview" } },
+			{ id: "content", title: { en: "Content" } },
+			{ id: "external", title: { en: "External" } },
+		],
+		items: [
+			{
+				sectionId: "overview",
+				type: "link",
+				label: { en: "Dashboard" },
+				href: "/admin",
+				icon: { type: "icon", props: { name: "ph:house" } },
+			},
+			{ sectionId: "overview", type: "global", global: "siteSettings" },
+			{ sectionId: "content", type: "collection", collection: "posts" },
+			{
+				sectionId: "external",
+				type: "link",
+				label: { en: "Open Website" },
+				href: "/",
+				external: true,
+				icon: { type: "icon", props: { name: "ph:arrow-square-out" } },
+			},
+		],
+	},
+});
+```
+
+Items appear in definition order within their section.
+
+Modules contribute sidebar items automatically. `adminModule` adds "Administration" with user management. `auditModule` adds an audit log item.
+
+## Filters & Saved Views
+
+Filters are auto-generated from field definitions:
+
+| Field Type          | Filter Operators                         |
+| ------------------- | ---------------------------------------- |
+| `text`              | Contains, equals, starts with, ends with |
+| `number`            | Equals, greater than, less than, between |
+| `boolean`           | Is true, is false                        |
+| `select`            | Is, is not, in                           |
+| `date` / `datetime` | Before, after, between                   |
+| `relation`          | Is (picker)                              |
+
+Users can save filter + sort + column combinations as named views.
+
+## Bulk Actions
+
+List views support multi-select. Check rows, then use the floating toolbar. Built-in: **Delete** (with confirmation). Soft-delete collections soft-delete instead of permanent removal.
+
+## History & Versions
+
+Click the clock icon in the form toolbar. Two tabs:
+
+| Tab          | Shows                                          | Requires                      |
+| ------------ | ---------------------------------------------- | ----------------------------- |
+| **Activity** | Audit log (create, update, delete, transition) | `auditModule`                 |
+| **Versions** | Full document snapshots with restore           | `.versioning()` on collection |
+
+Enable versioning:
+
+```ts
+export const pages = collection("pages")
+  .fields(({ f }) => ({ ... }))
+  .options({ versioning: true });
+```
+
+Disable audit for a specific collection:
+
+```ts
+export const logs = collection("logs")
+  .admin(() => ({ audit: false }))
+  .fields(({ f }) => ({ ... }));
+```
+
+## Common Mistakes
+
+1. **HIGH: Defining columns that don't match field names** — `columns: [f.name]` requires a `name` field in the collection's `.fields()`. Mismatches cause empty columns.
+
+2. **MEDIUM: Not specifying `searchableFields`** — table search bar won't work unless you explicitly list which fields to search.
+
+3. **MEDIUM: Forgetting sidebar section ordering** — items appear in definition order. If you want "Dashboard" at the top, define it first in the `items` array.
+
+4. **MEDIUM: Missing `sectionId` on sidebar items** — every item must reference an existing section ID.
+
+5. **LOW: Not setting `defaultSort`** — records appear in database insertion order which is usually not what users expect.
+
+## Form Views and Live Preview
+
+Form views connect to the Live Preview V2 system when the collection has `.preview()` configured. The form editor becomes the source of `postMessage` patches — every field change emits a patch through the bus, giving the preview iframe instant updates.
+
+### Enabling Preview on a Collection
+
+Add `.preview()` to the collection definition:
+
+```ts
+export const pages = collection("pages")
+	.fields(({ f }) => ({
+		title: f.text().required().localized(),
+		slug: f.text().required(),
+		content: f.blocks().localized(),
+	}))
+	.preview({
+		enabled: true,
+		position: "right",
+		defaultWidth: 50,
+		url: ({ record }) => `/${record.slug}?preview=true`,
+	});
+```
+
+### How It Works
+
+1. The form view detects `.preview()` config and opens a split-screen layout
+2. Save/autosave sends a `PREVIEW_REFRESH` message to the preview iframe
+3. The preview page handles refreshes through `useCollectionPreview({ initialData, onRefresh })`
+4. `PreviewProvider` and `PreviewField` wire field focus and click-to-focus messages
+
+---
+
+# QUESTPIE Blocks
+
+This skill builds on questpie-admin.
+
+Blocks are reusable content components for page builders. Define them server-side with fields and admin metadata, then render them client-side with React components.
+
+```text
+Server: block("hero")           Client: HeroRenderer
+  .fields({ title, image })  ->    Receives { values, data }
+  .admin({ label, icon })         Returns JSX
+  .prefetch({ with: {...} })
+```
+
+## Defining Blocks
+
+Blocks are defined in `blocks/` using the `block()` factory:
+
+```ts title="blocks/hero.ts"
+import { block } from "#questpie/factories";
+
+export const heroBlock = block("hero")
+	.admin(({ c }) => ({
+		label: { en: "Hero Section", sk: "Hero sekcia" },
+		icon: c.icon("ph:image"),
+		category: "sections",
+	}))
+	.fields(({ f }) => ({
+		title: f.text().localized().required(),
+		subtitle: f.textarea().localized(),
+		backgroundImage: f.upload({ to: "assets" }),
+		overlayOpacity: f.number().default(60),
+		alignment: f
+			.select([
+				{ value: "left", label: "Left" },
+				{ value: "center", label: "Center" },
+				{ value: "right", label: "Right" },
+			])
+			.default("center"),
+		ctaText: f.text().localized(),
+		ctaLink: f.text(),
+	}))
+	.prefetch({ with: { backgroundImage: true } });
+```
+
+### Admin Metadata
+
+```ts
+.admin(({ c }) => ({
+  label: { en: "Hero Section" },      // Display name in block picker
+  icon: c.icon("ph:image"),           // Icon in block picker (Phosphor set)
+  category: "sections",               // Group in block picker
+}))
+```
+
+### Multiple Blocks Per File
+
+Export multiple named blocks from one file:
+
+```ts title="blocks/layout.ts"
+import { block } from "#questpie/factories";
+
+export const twoColumnBlock = block("twoColumn")
+	.admin(({ c }) => ({
+		label: { en: "Two Columns" },
+		icon: c.icon("ph:columns"),
+		category: "layout",
+	}))
+	.fields(({ f }) => ({
+		left: f.blocks(),
+		right: f.blocks(),
+	}));
+
+export const spacerBlock = block("spacer")
+	.admin(({ c }) => ({
+		label: { en: "Spacer" },
+		icon: c.icon("ph:arrows-out-line-vertical"),
+		category: "layout",
+	}))
+	.fields(({ f }) => ({
+		height: f
+			.select([
+				{ value: "sm", label: "Small" },
+				{ value: "md", label: "Medium" },
+				{ value: "lg", label: "Large" },
+				{ value: "xl", label: "Extra Large" },
+			])
+			.default("md"),
+	}));
+```
+
+## Using Blocks in Collections
+
+Add a `blocks` field to any collection:
+
+```ts title="collections/pages.ts"
+import { collection } from "#questpie/factories";
+
+export const pages = collection("pages").fields(({ f }) => ({
+	title: f.text().required().localized(),
+	slug: f.text().required(),
+	content: f.blocks().localized(),
+}));
+```
+
+The admin renders a visual block editor for this field.
+
+## Prefetch
+
+Blocks often reference related data (images, linked records). Use `.prefetch()` to load them alongside block values.
+
+### Declarative Prefetch
+
+```ts
+.prefetch({
+  with: {
+    backgroundImage: true,  // Load the full image record
+  },
+})
+```
+
+### Nested Prefetch
+
+```ts
+.prefetch({
+  with: {
+    featuredBarber: {
+      with: {
+        avatar: true,
+        services: true,
+      },
+    },
+  },
+})
+```
+
+### Functional Prefetch
+
+For complex queries, use a function. The `ctx` parameter provides fully typed `collections` and `globals` via `AppContext` augmentation — no imports needed:
+
+```ts title="blocks/featured.ts"
+import { block } from "#questpie/factories";
+
+export const featuredBlock = block("featured")
+	.fields(({ f }) => ({
+		heading: f.text().required(),
+	}))
+	.prefetch(async ({ values, ctx }) => {
+		return {
+			posts: (await ctx.collections.posts.find({ limit: 5 })).docs,
+		};
+	});
+```
+
+### Using Prefetched Data in Renderers
+
+```tsx
+function HeroRenderer({ values, data }: BlockProps<"hero">) {
+	// values.backgroundImage = "asset-id-123" (just the ID)
+	// data.backgroundImage = { url: "/api/assets/...", filename: "hero.jpg", ... }
+
+	return (
+		<section>
+			{data?.backgroundImage?.url && (
+				<img src={data.backgroundImage.url} alt="" />
+			)}
+			<h1>{values.title}</h1>
+		</section>
+	);
+}
+```
+
+## Block Renderers
+
+React components that receive block data and return JSX.
+
+### Defining a Renderer
+
+```tsx title="admin/blocks/hero.tsx"
+import type { BlockProps } from "../.generated/client";
+
+export function HeroRenderer({ values, data }: BlockProps<"hero">) {
+	return (
+		<section
+			className="relative flex items-center justify-center"
+			style={{ minHeight: "60vh" }}
+		>
+			{data?.backgroundImage?.url && (
+				<img
+					src={data.backgroundImage.url}
+					alt=""
+					className="absolute inset-0 w-full h-full object-cover"
+				/>
+			)}
+			<div className="relative text-center">
+				<h1 className="text-5xl font-bold">{values.title}</h1>
+				{values.subtitle && <p className="text-xl mt-4">{values.subtitle}</p>}
+				{values.ctaText && (
+					<a href={values.ctaLink} className="mt-6 inline-block btn">
+						{values.ctaText}
+					</a>
+				)}
+			</div>
+		</section>
+	);
+}
+```
+
+### BlockProps
+
+| Property   | Type        | Description                                        |
+| ---------- | ----------- | -------------------------------------------------- |
+| `values`   | `object`    | Block field values (title, subtitle, etc.)         |
+| `data`     | `object`    | Prefetched relation data (images, related records) |
+| `children` | `ReactNode` | Nested block content                               |
+
+### Registering Renderers
+
+```tsx title="admin/blocks/index.tsx"
+import { HeroRenderer } from "./hero";
+import { GalleryRenderer } from "./gallery";
+import { CTARenderer } from "./cta";
+
+export const renderers = {
+	hero: HeroRenderer,
+	gallery: GalleryRenderer,
+	cta: CTARenderer,
+};
+```
+
+### Frontend Rendering
+
+Use block renderers on the public frontend:
+
+```tsx title="components/page-renderer.tsx"
+import { renderers } from "@/questpie/admin/blocks";
+
+function PageRenderer({ page }) {
+	return (
+		<div>
+			{page.content?.map((block, i) => {
+				const Renderer = renderers[block.type];
+				if (!Renderer) return null;
+				return <Renderer key={i} values={block.values} data={block.data} />;
+			})}
+		</div>
+	);
+}
+```
+
+## Common Mistakes
+
+1. **HIGH: Not using `ctx.collections.*` in functional prefetch** — use the context-injected collections directly. Do NOT import `app` from `#questpie` inside block files (causes circular dependencies).
+
+   ```ts
+   // WRONG — importing app creates circular dependency
+   import { app } from "#questpie";
+   .prefetch(async ({ values, ctx }) => {
+     const posts = await app.collections.posts.find({});
+   })
+
+   // CORRECT — use ctx.collections directly
+   .prefetch(async ({ values, ctx }) => {
+     const posts = await ctx.collections.posts.find({});
+   })
+   ```
+
+2. **HIGH: Importing from `.generated/` inside block files** — block files are imported BY `.generated/index.ts`, so importing from it back creates circular dependencies. Use the `ctx` parameter instead.
+
+3. **MEDIUM: Block renderer not exported as default or named export** — codegen discovers named exports from block renderer files. Ensure the component is exported.
+
+4. **MEDIUM: Using `{ with: { field: true } }` prefetch for complex queries** — declarative prefetch only loads related records by ID. For filtered/sorted/limited queries, use functional prefetch instead.
+
+5. **MEDIUM: Forgetting `.prefetch()` for upload fields** — without prefetch, `values.backgroundImage` is just an ID string. Add `{ with: { backgroundImage: true } }` to get the full asset record with `url`.
+
+6. **LOW: Missing `category` in `.admin()`** — blocks without a category won't be grouped in the block picker, making it harder to find them.
+
+## Blocks in Live Preview
+
+When a collection has `.preview()` configured, blocks can participate in preview focus by combining `BlockScopeProvider` with `PreviewField`.
+
+### BlockScopeProvider Wrapper
+
+Use `BlockScopeProvider` in your frontend to scope field paths inside a block:
+
+```tsx
+import { BlockScopeProvider } from "@questpie/admin/client";
+
+function PageRenderer({ blocks, previewData }) {
+	return blocks.map((block) => {
+		const Renderer = renderers[block.type];
+		return (
+			<BlockScopeProvider key={block.id} blockId={block.id}>
+				<Renderer values={block.values} data={block.data} />
+			</BlockScopeProvider>
+		);
+	});
+}
+```
+
+`PreviewField` components inside the provider resolve paths like `content._values.{blockId}.title`.
+
+Blocks with declarative prefetch (`{ with: { image: true } }`) resolve relations during reconcile — the preview shows the image URL immediately after the server round-trip completes, not just the asset ID.
+
+---
+
+# QUESTPIE Custom UI
+
+This skill builds on questpie-admin.
+
+Extend the QUESTPIE admin with custom field types, custom view types, custom components, and reactive field behaviors.
+
+## Registries
+
+Registries connect server-side schema to client-side rendering. When the admin encounters a field type, it looks up the renderer in the field registry.
+
+```text
+Server: f.text().required()
+  |
+Generated: { type: "text", options: {...} }
+  |
+Admin Client: fieldRegistry.get("text")
+  |
+React: <TextFieldRenderer value={...} onChange={...} />
+```
+
+### Built-in Field Registry
+
+```
+text       -> TextInput
+textarea   -> TextareaInput
+richText   -> RichTextEditor (TipTap)
+number     -> NumberInput
+boolean    -> Checkbox / Switch
+date       -> DatePicker
+datetime   -> DateTimePicker
+select     -> SelectDropdown
+relation   -> RelationPicker
+upload     -> FileUpload
+object     -> NestedForm
+array      -> RepeatableItems
+blocks     -> BlockEditor
+json       -> JSONEditor
+```
+
+### Extending Registries
+
+Place files in the admin directory. Codegen discovers them automatically:
+
+```
+questpie/admin/
+  fields/
+    color.tsx        # Custom color field renderer
+    currency.tsx     # Custom currency field renderer
+  views/
+    kanban.tsx       # Custom kanban list view
+```
+
+These are merged with built-in defaults during codegen and exported in `.generated/client.ts`.
+
+## Custom Fields
+
+### Server-Side Registration
+
+Register custom fields through modules:
+
+```ts
+const myModule = module({
+	name: "custom-fields",
+	fields: {
+		color: colorField,
+		currency: currencyField,
+		phone: phoneField,
+	},
+});
+```
+
+Once registered and codegen runs, the field becomes available on the `f` builder:
+
+```ts
+.fields(({ f }) => ({
+  brandColor: f.color().default("#000000"),
+  price: f.currency({ currency: "USD" }),
+}))
+```
+
+### Admin Field Renderer
+
+Create a React component for the field's edit form:
+
+```tsx title="admin/fields/color.tsx"
+import { Icon } from "@iconify/react";
+
+function ColorFieldRenderer({ value, onChange }) {
+	return (
+		<div className="flex items-center gap-2">
+			<input
+				type="color"
+				value={value || "#000000"}
+				onChange={(e) => onChange(e.target.value)}
+				className="w-10 h-10 border border-border cursor-pointer"
+			/>
+			<span className="font-mono text-sm text-muted-foreground">
+				{value || "#000000"}
+			</span>
+		</div>
+	);
+}
+```
+
+### Cell Renderer
+
+For custom table column rendering, provide a `cell` component alongside the field renderer:
+
+```tsx title="admin/fields/color.tsx"
+// Cell component for list view table
+export function ColorCell({ value }) {
+	return (
+		<div className="flex items-center gap-2">
+			<div
+				className="w-4 h-4 border border-border"
+				style={{ backgroundColor: value || "transparent" }}
+			/>
+			<span className="text-xs font-mono">{value}</span>
+		</div>
+	);
+}
+```
+
+## Custom Views
+
+Create view types beyond built-in table and form — kanban boards, calendars, galleries.
+
+### Server-Side Declaration
+
+```ts
+const myModule = module({
+	name: "custom-views",
+	views: {
+		kanban: kanbanViewDefinition,
+		calendar: calendarViewDefinition,
+	},
+});
+```
+
+### Usage in Collections
+
+```ts
+.list(({ v }) => v.kanban({
+  columns: "status",
+  cardTitle: "title",
+}))
+```
+
+### Client Rendering
+
+```tsx title="admin/views/kanban.tsx"
+function KanbanView({ data, columns, onDrop }) {
+	return (
+		<div className="flex gap-4">
+			{columns.map((col) => (
+				<div key={col.id} className="flex-1">
+					<h3 className="font-mono text-sm font-semibold mb-2">{col.label}</h3>
+					{data
+						.filter((item) => item.status === col.id)
+						.map((item) => (
+							<div
+								key={item.id}
+								className="border border-border bg-card p-3 mb-2"
+							>
+								{item.title}
+							</div>
+						))}
+				</div>
+			))}
+		</div>
+	);
+}
+```
+
+## Reactive Field System
+
+Fields support reactive behaviors configured in the collection's `.form()` view or on the field definition itself.
+
+### Conditional Visibility
+
+```ts
+{
+  field: f.cancellationReason,
+  hidden: ({ data }) => data.status !== "cancelled",
+}
+```
+
+### Read-Only
+
+```ts
+{
+  field: f.customerName,
+  readOnly: ({ data }) => !!data.customer,
+}
+```
+
+### Computed Values
+
+```ts
+{
+  field: f.slug,
+  compute: {
+    handler: ({ data }) => {
+      if (data.name && !data.slug?.trim()) {
+        return slugify(data.name);
+      }
+      return undefined;
+    },
+    deps: ({ data }) => [data.name, data.slug],
+    debounce: 300,
+  },
+}
+```
+
+### Dynamic Options (Server-Side)
+
+For select/relation fields with options that depend on other field values:
+
+```ts
+city: f.relation("cities").admin({
+  options: {
+    handler: async ({ data, search, ctx }) => {
+      const cities = await ctx.db.query.cities.findMany({
+        where: { countryId: data.country },
+      });
+      return {
+        options: cities.map((c) => ({ value: c.id, label: c.name })),
+      };
+    },
+    deps: ({ data }) => [data.country],
+  },
+}),
+```
+
+The `handler` runs **server-side** with full access to `ctx.db`, `ctx.user`, `ctx.req`. It re-executes when any value in `deps` changes.
+
+## UI Component Reference
+
+When building custom admin UI, use these patterns:
+
+### Icons
+
+```tsx
+import { Icon } from "@iconify/react";
+
+// Phosphor icon set with ph: prefix
+<Icon icon="ph:house" width={20} height={20} />
+<Icon icon="ph:caret-down-bold" width={16} height={16} />  // bold weight
+<Icon icon="ph:heart-fill" width={16} height={16} />        // fill weight
+```
+
+### Toasts
+
+```tsx
+import { toast } from "sonner";
+
+toast.success("Record saved");
+toast.error("Failed to save");
+```
+
+### Primitives (base-ui)
+
+```tsx
+// CORRECT — render prop
+<DialogTrigger render={<Button>Open</Button>} />
+
+// WRONG — asChild is Radix, not base-ui
+<DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+```
+
+### Responsive Components
+
+- `ResponsivePopover` — Popover on desktop, Drawer on mobile
+- `ResponsiveDialog` — Dialog on desktop, fullscreen Drawer on mobile
+- Hooks: `useIsMobile()`, `useIsDesktop()`, `useMediaQuery()`
+
+## Common Mistakes
+
+1. **HIGH: Not registering custom field in the field registry** — if codegen doesn't discover the field renderer file, the admin will render nothing for that field type. Place it in `questpie/admin/fields/<name>.tsx`.
+
+2. **HIGH: Missing `cell` component for custom fields** — without a cell component, the list view table shows raw values for your custom field instead of a formatted display.
+
+3. **MEDIUM: Reactive field handlers running client-side** — `options.handler`, `compute.handler`, and other reactive handlers run **SERVER-SIDE** with access to `ctx.db`, `ctx.user`. Do not import client-side modules or use browser APIs in them.
+
+4. **MEDIUM: Using `onChange` wrong in field components** — the field renderer receives `onChange` that expects the **value directly**, not a DOM event.
+
+   ```tsx
+   // WRONG
+   onChange={(e) => onChange(e)}
+   // CORRECT
+   onChange={(e) => onChange(e.target.value)}
+   // Or for non-DOM values:
+   onChange={newValue}
+   ```
+
+5. **MEDIUM: Importing from `@radix-ui/*`** — QUESTPIE admin uses `@base-ui/react`. Never import Radix primitives.
+
+6. **MEDIUM: Using `@phosphor-icons/react` or `lucide-react`** — use `@iconify/react` with `ph:` prefix for all icons.
+
+7. **LOW: Not using shadcn components** — prefer `<Button>`, `<Card>`, `<Input>` from the shadcn component library instead of raw HTML elements. The admin has a consistent brutalist design system.
+
+---