@questpie/admin 2.0.0 → 3.0.0

package/skills/questpie-admin/blocks/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: questpie-admin/blocks
+description: QUESTPIE blocks content-blocks page-builder block-definition fields prefetch renderers block-picker categories nested-blocks upload relation
+type: skill
+---
+
+# 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";
+
+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: true, required: true }),
+		subtitle: f.textarea({ localized: true }),
+		backgroundImage: f.upload({ to: "assets" }),
+		overlayOpacity: f.number({ defaultValue: 60 }),
+		alignment: f.select({
+			options: ["left", "center", "right"],
+			defaultValue: "center",
+		}),
+		ctaText: f.text({ localized: true }),
+		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";
+
+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({
+			options: ["sm", "md", "lg", "xl"],
+			defaultValue: "md",
+		}),
+	}));
+```
+
+## Using Blocks in Collections
+
+Add a `blocks` field to any collection:
+
+```ts title="collections/pages.ts"
+import { collection } from "#questpie";
+
+export const pages = collection("pages").fields(({ f }) => ({
+	title: f.text({ required: true, localized: true }),
+	slug: f.text({ required: true }),
+	content: f.blocks({ localized: true }),
+}));
+```
+
+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";
+
+export const featuredBlock = block("featured")
+	.fields(({ f }) => ({
+		heading: f.text({ required: true }),
+	}))
+	.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 "@questpie/admin/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 participate in the live preview patch bus.
+
+### PreviewBlock Wrapper
+
+Use `<PreviewBlock>` in your frontend to mark block regions for live preview focus and patch targeting:
+
+```tsx
+import { PreviewBlock } from "@questpie/admin/client";
+
+function PageRenderer({ blocks, previewData }) {
+	return blocks.map((block) => {
+		const Renderer = renderers[block.type];
+		return (
+			<PreviewBlock key={block.id} id={block.id}>
+				<Renderer values={block.values} data={block.data} />
+			</PreviewBlock>
+		);
+	});
+}
+```
+
+When the editor focuses a block, `<PreviewBlock>` highlights it in the preview. Patches target individual blocks by ID for granular updates.
+
+### Block Prefetch and Server Reconcile
+
+In `"hybrid"` preview strategy, blocks with functional `.prefetch()` trigger a server reconcile when their field values change. For example, a "featured posts" block with a `limit` field will re-run its prefetch handler on the server to fetch updated data, while simple field changes (title, subtitle) apply instantly via the local patch bus.
+
+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.

package/skills/questpie-admin/custom-ui/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: questpie-admin/custom-ui
+description: QUESTPIE custom-fields custom-views registries field-registry view-registry component-registry reactive-fields dynamic-options widgets field-renderer cell-renderer
+type: skill
+---
+
+# 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({ ... })
+  |
+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({
+  to: "cities",
+  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.