@questpie/admin 2.0.0 → 3.0.0

package/package.json

@@ -1,46 +1,66 @@
 {
 	"name": "@questpie/admin",
-	"version": "2.0.0",
-	"type": "module",
+	"version": "3.0.0",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/questpie/questpie-cms.git",
+		"url": "https://github.com/questpie/questpie.git",
 		"directory": "packages/admin"
 	},
-	"imports": {
-		"#questpie/admin/*": "./src/*"
-	},
 	"files": [
-		"dist"
+		"dist",
+		"skills"
 	],
+	"type": "module",
 	"sideEffects": [
 		"**/*.css"
 	],
+	"main": "./dist/index.mjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"imports": {
+		"#questpie/admin/*": "./src/*"
+	},
 	"exports": {
 		".": "./dist/index.mjs",
 		"./client": "./dist/client.mjs",
+		"./client-module": "./dist/client-module.mjs",
+		"./plugin": "./dist/plugin.mjs",
 		"./server": "./dist/server.mjs",
 		"./shared": "./dist/shared.mjs",
 		"./*": "./*",
 		"./client/styles/index.css": "./dist/client/styles/index.css"
 	},
+	"publishConfig": {
+		"access": "public",
+		"exports": {
+			".": "./dist/index.mjs",
+			"./client": "./dist/client.mjs",
+			"./client-module": "./dist/client-module.mjs",
+			"./plugin": "./dist/plugin.mjs",
+			"./server": "./dist/server.mjs",
+			"./shared": "./dist/shared.mjs",
+			"./*": "./*",
+			"./client/styles/index.css": "./dist/client/styles/index.css"
+		}
+	},
 	"scripts": {
 		"dev": "tsdown --watch",
 		"build": "tsdown",
 		"check-types": "tsc --noEmit",
 		"test": "bun test test/",
-		"test:watch": "bun test --watch test/"
+		"test:watch": "bun test --watch test/",
+		"questpie:generate": "bun x questpie generate --verbose"
 	},
 	"dependencies": {
 		"@base-ui/react": "^1.0.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",
 		"@dnd-kit/utilities": "^3.2.2",
-		"@fontsource-variable/dm-sans": "^5.2.8",
+		"@fontsource-variable/geist": "^5.2.8",
 		"@fontsource-variable/jetbrains-mono": "^5.2.8",
 		"@hookform/resolvers": "^5.1.0",
 		"@iconify/react": "^6.0.2",
-		"@questpie/tanstack-query": "^2.0.0",
+		"@questpie/tanstack-query": "^3.0.0",
 		"@tailwindcss/vite": "^4.0.6",
 		"@tiptap/core": "^2.x",
 		"@tiptap/extension-character-count": "^2.x",
@@ -66,12 +86,11 @@
 		"date-fns": "^4.1.0",
 		"lowlight": "^3.x",
 		"next-themes": "^0.4.6",
-		"questpie": "^2.0.0",
+		"questpie": "^3.0.0",
 		"react-day-picker": "^9.12.0",
 		"react-hook-form": "^7.54.0",
 		"react-resizable-panels": "^4.4.2",
 		"recharts": "2.15.4",
-		"shadcn": "^3.6.1",
 		"sonner": "^2.0.7",
 		"tailwind-merge": "^3.4.0",
 		"tailwindcss": "^4.0.6",
@@ -80,42 +99,33 @@
 		"vaul": "^1.1.2",
 		"zustand": "^5.0.10"
 	},
+	"devDependencies": {
+		"@rollup/plugin-babel": "^6.1.0",
+		"@tanstack/db": "^0.1.1",
+		"@types/react": "^19.2.0",
+		"@types/react-dom": "^19.2.0",
+		"babel-plugin-react-compiler": "^1.0.0",
+		"shadcn": "^3.6.1",
+		"tinyglobby": "^0.2.15",
+		"tsdown": "^0.18.3",
+		"typescript": "^5.9.2"
+	},
 	"peerDependencies": {
-		"react": "^19.2.0",
-		"react-dom": "^19.2.0",
+		"@tanstack/db": "^0.x",
 		"@tanstack/react-query": "^5.x",
 		"@tanstack/react-table": "^8.x",
-		"@tanstack/db": "^0.x",
-		"better-auth": "^1.4.0",
+		"better-auth": "^1.4.9",
 		"drizzle-orm": "1.0.0-beta.6-4414a19",
+		"react": "^19.2.0",
+		"react-dom": "^19.2.0",
 		"zod": "^4.2.1"
 	},
 	"peerDependenciesMeta": {
 		"drizzle-orm": {
 			"optional": true
+		},
+		"@tanstack/db": {
+			"optional": true
 		}
-	},
-	"devDependencies": {
-		"@tanstack/db": "^0.1.1",
-		"drizzle-orm": "1.0.0-beta.6-4414a19",
-		"@types/react": "^19.2.0",
-		"@types/react-dom": "^19.2.0",
-		"tinyglobby": "^0.2.15",
-		"tsdown": "^0.18.3",
-		"typescript": "^5.9.2"
-	},
-	"publishConfig": {
-		"access": "public",
-		"exports": {
-			".": "./dist/index.mjs",
-			"./client": "./dist/client.mjs",
-			"./server": "./dist/server.mjs",
-			"./shared": "./dist/shared.mjs",
-			"./*": "./*",
-			"./client/styles/index.css": "./dist/client/styles/index.css"
-		}
-	},
-	"main": "./dist/index.mjs",
-	"module": "./dist/index.mjs",
-	"types": "./dist/index.d.mts"
+	}
 }

package/skills/questpie-admin/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: questpie-admin
+description: QUESTPIE admin panel setup branding theming sidebar dashboard media localization live-preview auth dark-mode CSS variables configuration
+type: skill
+---
+
+# 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.
+
+## Sub-Skills
+
+| Skill                                            | Covers                                                                                 |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| [questpie-admin/views](./views/SKILL.md)         | List views, form views, dashboard, sidebar, filters, bulk actions, visibility, history |
+| [questpie-admin/blocks](./blocks/SKILL.md)       | Block definitions, fields, prefetch, renderers, block picker                           |
+| [questpie-admin/custom-ui](./custom-ui/SKILL.md) | Custom fields, custom views, registries, reactive fields, widgets                      |
+
+## 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. Server Plugin
+
+```ts title="questpie.config.ts"
+import { adminPlugin } from "@questpie/admin/plugin";
+import { runtimeConfig } from "questpie";
+
+export default runtimeConfig({
+	plugins: [adminPlugin()],
+	app: { url: process.env.APP_URL || "http://localhost:3000" },
+	db: { url: process.env.DATABASE_URL },
+	secret: process.env.APP_SECRET,
+});
+```
+
+The plugin tells codegen to discover admin-specific file conventions: `sidebar.ts`, `dashboard.ts`, `branding.ts`, `blocks/`, `admin-locale.ts`.
+
+### 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. Convention Files
+
+```ts title="sidebar.ts"
+import { sidebar } from "#questpie";
+
+export default 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",
+		},
+	],
+});
+```
+
+```ts title="branding.ts"
+import { branding } from "#questpie";
+
+export default branding({
+	name: { en: "My App Admin" },
+});
+```
+
+### 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="branding.ts"
+import { branding } from "#questpie";
+
+export default 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="questpie.config.ts"
+export default runtimeConfig({
+	localization: {
+		defaultLocale: "en",
+		locales: [
+			{ code: "en", label: { en: "English" }, flagCountryCode: "gb" },
+			{ code: "sk", label: { en: "Slovak" } },
+		],
+	},
+});
+```
+
+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 (V2)
+
+Live Preview V2 uses a direct `postMessage` patch bus for instant same-tab feedback. Save/autosave is persistence only — NOT the live transport. Realtime (SSE/WebSocket) is reserved for detached or shared preview sessions.
+
+For full architecture details, see: `/docs/workspace/live-preview/architecture`
+
+### 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: true, localized: true }),
+		slug: f.text({ required: true }),
+		content: f.blocks({ localized: true }),
+	}))
+	.preview({
+		url: ({ record }) => {
+			const slug = record.slug as string;
+			return slug === "home" ? "/?preview=true" : `/${slug}?preview=true`;
+		},
+		watch: ["title", "slug", "content"],
+		strategy: "hybrid", // "instant" | "server" | "hybrid"
+	});
+```
+
+| Strategy    | Behavior                                                            |
+| ----------- | ------------------------------------------------------------------- |
+| `"instant"` | Patches applied locally only — fastest, no server round-trip        |
+| `"server"`  | Every change round-trips through server before preview updates      |
+| `"hybrid"`  | Local patches for instant response + server reconcile derived data  |
+
+### Frontend Integration
+
+Use `useQuestpiePreview` (replaces the old `useCollectionPreview`) with `<PreviewRoot>`, `<PreviewField>`, and `<PreviewBlock>` components:
+
+```tsx
+import { useQuestpiePreview, PreviewRoot, PreviewField } from "@questpie/admin/client";
+
+function PagePreview({ initialData }) {
+	const router = useRouter();
+	const { data } = useQuestpiePreview({
+		initialData,
+		reconcile: () => router.invalidate(),
+	});
+
+	return (
+		<PreviewRoot>
+			<h1><PreviewField path="title">{data.title}</PreviewField></h1>
+		</PreviewRoot>
+	);
+}
+```
+
+### Key Principles
+
+- Same-tab preview = direct `postMessage` patch bus (NOT save-driven reload)
+- Save/autosave = persistence only
+- Realtime = extension for detached/shared preview only
+- 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")
+  .versioning({ drafts: true, maxVersions: 20 })
+  .fields(({ f }) => ({ ... }));
+```
+
+## 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-core/multi-tenancy` skill.
+
+## 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`.