create-questpie 2.0.4 → 2.1.0

package/skills/questpie-admin/SKILL.md

@@ -1,443 +0,0 @@
----
-name: questpie-admin
-description: QUESTPIE admin panel — setup, branding, theming, sidebar, dashboard, views, blocks, custom fields, media, localization, live preview, auth, dark mode, CSS variables. Use when building or customizing the QUESTPIE admin UI.
-license: MIT
-metadata:
-  author: questpie
-  version: "3.0.0"
----
-
-# 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()`
-- QUESTPIE Neutral Design: flat surfaces, soft neutral geometry,
-  tokenized radius, and restrained floating shadows
-
-## Setup
-
-### 1. Install
-
-```bash
-bun add @questpie/admin
-```
-
-### 2. Runtime Config
-
-```ts title="questpie.config.ts"
-import { runtimeConfig } from "questpie/app";
-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 } from "@questpie/admin/modules/admin";
-import { auditModule } from "@questpie/admin/modules/audit";
-
-export default [adminModule, auditModule] as const;
-```
-
-| Module        | Provides                              |
-| ------------- | ------------------------------------- |
-| `adminModule` | User collection, auth pages, admin UI |
-| `auditModule` | Audit log collection, timeline widget |
-
-### Auth/User Contract - Critical
-
-`adminModule` includes the starter auth model and owns the canonical Better Auth `user` collection shape used by admin setup and login guards. That contract includes `user.role` with at least `admin` and `user` values. The built-in setup route checks for `role = "admin"`, and the admin `AuthGuard` expects `session.user.role === "admin"`.
-
-Do not create a replacement `collection("user")` from scratch in an app that uses `adminModule`. If the app needs to customize the user admin UI or add fields, merge the starter user collection and extend it:
-
-```ts title="collections/user.ts"
-import { starterModule } from "questpie/app";
-import { collection } from "#questpie/factories";
-
-export default collection("user")
-	.merge(starterModule.collections.user)
-	.fields(({ f }) => ({
-		// add app-specific user fields here
-		internalNotes: f.textarea(),
-	}));
-```
-
-App-specific authorization tables are fine, but they must not replace or remove the admin user contract unless the app also replaces the built-in admin setup route and auth guard.
-
-### 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.
-
-The full source of truth is `packages/admin/DESIGN.md`. Key defaults:
-
-| Role          | Dark      | Light     |
-| ------------- | --------- | --------- |
-| Background    | `#121212` | `#fafafa` |
-| Foreground    | `#ececec` | `#1c1c1c` |
-| Card          | `#1b1b1b` | `#ffffff` |
-| Surface high  | `#2a2a2a` | `#e8e8e8` |
-| Border        | `#343434` | `#e2e2e2` |
-| Border subtle | `#262626` | `#ebebeb` |
-| Brand primary | `#b700ff` | `#b700ff` |
-
-| Token                    | Default | Use                                         |
-| ------------------------ | ------- | ------------------------------------------- |
-| `--control-radius-inner` | `8px`   | Icon buttons/actions nested inside controls |
-| `--control-radius`       | `12px`  | Inputs, selects, buttons, compact controls  |
-| `--surface-radius`       | `14px`  | Cards, panels, grouped fields, docs blocks  |
-| `--floating-radius`      | `14px`  | Menus, popovers, dialogs, command panels    |
-
-### Typography
-
-| Variable      | Value                                                               |
-| ------------- | ------------------------------------------------------------------- |
-| `--font-sans` | `"Geist Variable"` — UI, prose, headings, labels, navigation        |
-| `--font-mono` | `"JetBrains Mono Variable"` — code, file paths, commands, IDs       |
-
-### 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/app";
-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 is one system: the existing collection `FormView`, Preview button, `LivePreviewMode`, and frontend iframe. Preserve the normal form lifecycle. Do not introduce a separate visual-edit form API, a second default form view, or a parallel preview surface.
-
-The admin form is authoritative. The iframe mirrors form state through `postMessage`, supports field/block focus, and may request inline scalar edits. Persistence still goes through existing save, autosave, Cmd+S, history, workflow, locks, and actions.
-
-### 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`;
-		},
-	});
-```
-
-Preview opens the existing split-screen editor. Patches and refresh/resync messages update the iframe mirror; save/autosave still writes through the form.
-
-### Prepare a Frontend Page
-
-Use exported APIs only: `useCollectionPreview`, `PreviewProvider`, `PreviewField`, and `BlockRenderer`.
-
-Checklist:
-
-1. Configure `.preview({ url })` on the collection.
-2. Load the same record shape the page normally renders.
-3. For workflow-published pages, public reads use `stage: "published"`; if the public client/HTTP API is exposed, anonymous read access also checks `input?.stage === "published"`. Authorized preview/draft reads can load the working record.
-4. Call `useCollectionPreview({ initialData, onRefresh })` in the page renderer.
-5. Wrap the visual output in `PreviewProvider`.
-6. Render from `preview.data`, not the original loader object.
-7. Wrap editable scalar text with `PreviewField field="..." editable="text" | "textarea"`.
-8. Render block content with `BlockRenderer`; pass `selectedBlockId` and `onBlockClick`.
-9. Keep add/remove/reorder/nesting block operations in the existing block editor.
-
-```tsx
-import {
-	BlockRenderer,
-	PreviewField,
-	PreviewProvider,
-	useCollectionPreview,
-} from "@questpie/admin/client";
-import admin from "@/questpie/admin/.generated/client";
-
-function PagePreview({ page }) {
-	const router = useRouter();
-	const preview = useCollectionPreview({
-		initialData: page,
-		onRefresh: () => router.invalidate(),
-	});
-
-	return (
-		<PreviewProvider preview={preview}>
-			<main className={preview.isPreviewMode ? "questpie-preview" : undefined}>
-				<PreviewField field="title" editable="text" as="h1">
-					{preview.data.title}
-				</PreviewField>
-
-				<BlockRenderer
-					content={preview.data.content}
-					data={preview.data.content?._data}
-					renderers={admin.blocks}
-					selectedBlockId={preview.selectedBlockId}
-					onBlockClick={
-						preview.isPreviewMode ? preview.handleBlockClick : undefined
-					}
-				/>
-			</main>
-		</PreviewProvider>
-	);
-}
-```
-
-### Key Principles
-
-- Keep `FormView`, the Preview button, and `LivePreviewMode`
-- Never add a separate visual-edit form API, a second default form view, or parallel preview API names
-- Preserve save/autosave/Cmd+S/history/workflow/locks/actions
-- `useCollectionPreview` handles preview mode, mirrored data, refresh/resync, and focus state
-- `PreviewProvider` supplies preview context to `PreviewField`
-- `PreviewField` annotates scalar fields and can opt into inline editing with `editable`
-- `BlockRenderer` preserves block IDs and block scopes for block annotations
-- Use `BlockScopeProvider` only for custom/manual block rendering outside `BlockRenderer`
-- Validate all iframe messages before updating form state
-
-## 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`.