create-questpie 2.0.4 → 2.1.0

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

@@ -1,331 +0,0 @@
----
-name: questpie-admin/blocks
-description: QUESTPIE blocks content-blocks page-builder block-definition fields prefetch renderers block-picker categories nested-blocks upload relation
----
-
-# 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 participate in the existing Live Preview system through `BlockRenderer` and `PreviewField`. The form remains authoritative; block annotations only mirror values, focus fields, select blocks, or request inline scalar edits.
-
-### Preferred: BlockRenderer
-
-Use `BlockRenderer` for normal frontend page rendering. It preserves `data-block-id`, routes block selection, and scopes nested `PreviewField` paths automatically.
-
-```tsx
-<BlockRenderer
-	content={preview.data.content}
-	data={preview.data.content?._data}
-	renderers={admin.blocks}
-	selectedBlockId={preview.selectedBlockId}
-	onBlockClick={preview.isPreviewMode ? preview.handleBlockClick : undefined}
-/>
-```
-
-Inside custom block renderers, annotate scalar values with `PreviewField`:
-
-```tsx
-<PreviewField field="title" editable="text" as="h2">
-	{values.title}
-</PreviewField>
-```
-
-This resolves to `content._values.{blockId}.title` when rendered inside `BlockRenderer`.
-
-### Manual BlockScopeProvider Wrapper
-
-Use `BlockScopeProvider` only when you manually render blocks outside `BlockRenderer`:
-
-```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`.
-
-Inline block edits target `_values`, for example `content._values.<blockId>.title`. Tree edits such as add, remove, reorder, and nesting stay in the existing block editor and should trigger refresh or resync when patching is not safe.

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

@@ -1,305 +0,0 @@
----
-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
----
-
-# 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 follows QUESTPIE Neutral Design.