create-questpie 2.0.1 → 2.0.3

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

@@ -0,0 +1,449 @@
+---
+name: questpie-admin/views
+description: QUESTPIE admin views list-view table form-view sections sidebar dashboard widgets filters bulk-actions visibility history versioning sorting search
+---
+
+# 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.showSeo,
+  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 existing Live Preview system when the collection has `.preview()` configured. Keep `v.collectionForm()` as the form surface; do not introduce a separate visual-edit form API, a second default form view, or parallel preview API names. The form editor remains the source of patches, refreshes, commits, and resyncs.
+
+### 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. The preview iframe mirrors form state with snapshot, patch, refresh, commit, and resync messages
+3. Save/autosave/Cmd+S/history/workflow/locks/actions stay in the form lifecycle
+4. The preview page uses `useCollectionPreview({ initialData, onRefresh })`
+5. `PreviewProvider`, `PreviewField`, and `BlockRenderer` wire field and block annotations
+
+### Frontend Preparation Checklist
+
+Use this checklist before expecting visual editing to work:
+
+1. The collection has `.preview({ url })`.
+2. The page loader returns the complete rendered record shape.
+3. Public workflow reads use `stage: "published"`; if public client/HTTP access is enabled, anonymous read access also requires `input?.stage === "published"`. Preview/draft-mode reads load the working record for authorized editors.
+4. The page renderer calls `useCollectionPreview({ initialData, onRefresh })`.
+5. The rendered page is wrapped in `PreviewProvider preview={preview}`.
+6. UI reads from `preview.data`, not directly from loader data.
+7. Scalar text uses `PreviewField field="..." editable="text" | "textarea"` when inline editing is expected.
+8. Blocks render through `BlockRenderer` with `selectedBlockId` and `onBlockClick`.
+9. `BlockScopeProvider` is only needed for custom/manual block rendering outside `BlockRenderer`.
+10. Add/remove/reorder/nesting block operations stay in the existing block editor.

package/templates/tanstack-start/AGENTS.md

@@ -116,10 +116,10 @@ src/
 - **`src/questpie/server/modules.ts`** — Module dependencies: `export default [adminModule, openApiModule] as const`.
 - **`src/questpie/server/config/auth.ts`** — Auth config via `authConfig()` factory.
 - **`src/questpie/server/config/admin.ts`** — Admin config (sidebar, dashboard, branding, locale) via `adminConfig()` factory.
-- **`src/questpie/server/config/app.ts`** — *(optional, not scaffolded)* App config (locale, access, hooks, context) via `appConfig()`. Create when needed.
+- **`src/questpie/server/config/app.ts`** — _(optional, not scaffolded)_ App config (locale, access, hooks, context) via `appConfig()`. Create when needed.
 - **`src/questpie/server/config/openapi.ts`** — OpenAPI config via `openApiConfig()` factory.
-- **`src/questpie/server/.generated/index.ts`** — Codegen output. Exports typed `app` instance and `App` type. Run `bunx questpie generate` to regenerate.
-- **`src/questpie/admin/.generated/client.ts`** — Codegen output: pre-built admin client config. Run `bunx questpie generate` to regenerate.
+- **`src/questpie/server/.generated/index.ts`** — Codegen output. Exports typed `app` instance and `App` type. Run `bun run questpie:generate` to regenerate.
+- **`src/questpie/admin/.generated/client.ts`** — Codegen output: pre-built admin client config. Run `bun run questpie:generate` to regenerate.
 - **`src/lib/env.ts`** — Type-safe env variables via `@t3-oss/env-core`. Add new env vars here with Zod schemas.
 - **`questpie.config.ts`** — CLI config (migration directory, app reference).
 - **`src/routes/api/$.ts`** — API catch-all handler. Serves REST + OpenAPI docs at `/api/docs`.
@@ -194,12 +194,12 @@ Then (preferred):
 
 1. Use `bun questpie add collection <name>` to scaffold files
 2. Codegen runs automatically
-3. Run `bun questpie migrate:create` to generate migration
+3. Run `bun run migrate:create` to generate migration
 
 Manual workflow (if you create files yourself):
 
-1. Run `bunx questpie generate` to regenerate `.generated/index.ts`
-2. Run `bun questpie migrate:create` to generate migration
+1. Run `bun run questpie:generate` to regenerate `.generated/index.ts`
+2. Run `bun run migrate:create` to generate migration
 
 Collections are auto-discovered by codegen — no manual registration needed.
 
@@ -233,12 +233,12 @@ Then (preferred):
 
 1. Use `bun questpie add global <name>` to scaffold files
 2. Codegen runs automatically
-3. Run `bun questpie migrate:create`
+3. Run `bun run migrate:create`
 
 Manual workflow (if you create files yourself):
 
-1. Run `bunx questpie generate` to regenerate `.generated/index.ts`
-2. Run `bun questpie migrate:create`
+1. Run `bun run questpie:generate` to regenerate `.generated/index.ts`
+2. Run `bun run migrate:create`
 
 Globals are auto-discovered by codegen — no manual registration needed.
 
@@ -270,7 +270,7 @@ export default route()
 **Step 2 — Run codegen:**
 
 ```bash
-bunx questpie generate
+bun run questpie:generate
 ```
 
 The route is auto-discovered and available at `/api/get-stats`.
@@ -429,7 +429,7 @@ fields: ({ f }) => ({
 ### Admin Configuration (Client-Side)
 
 The admin client config is auto-generated by codegen into `admin/.generated/client.ts`.
-No manual builder setup is needed. Run `bunx questpie generate` to regenerate.
+No manual builder setup is needed. Run `bun run questpie:generate` to regenerate.
 
 ```ts
 // src/questpie/admin/admin.ts (re-export for convenience)
@@ -498,8 +498,12 @@ Optional (with defaults):
 bun dev                     # Start dev server
 bun build                   # Build for production
 bun start                   # Start production server
-bun questpie migrate        # Run database migrations
-bun questpie migrate:create # Create new migration
+bun run migrate             # Run database migrations
+bun run migrate:create      # Create new migration
+bun run routes:generate     # Regenerate TanStack Router route tree
+bun run questpie:generate   # Regenerate codegen output
+bun run scaffold:generate   # Regenerate route tree and QUESTPIE output
+bun run scaffold:verify     # Regenerate codegen and type-check
 docker compose up -d        # Start PostgreSQL
 ```
 

package/templates/tanstack-start/CLAUDE.md

@@ -11,9 +11,12 @@ This is a [QUESTPIE](https://questpie.com) project scaffolded with `create-quest
 | `bun start`                      | Start production server                        |
 | `bun questpie add <type> <name>` | Scaffold a new entity (collection, seed, etc.) |
 | `bun questpie add --list`        | List all available scaffold types              |
-| `bun questpie generate`          | Regenerate .generated/index.ts                 |
-| `bun questpie migrate:create`    | Generate a migration from schema diff          |
-| `bun questpie migrate`           | Run pending migrations                         |
+| `bun run routes:generate`        | Regenerate TanStack Router route tree          |
+| `bun run questpie:generate`      | Regenerate .generated/index.ts                 |
+| `bun run scaffold:generate`      | Regenerate route tree and QUESTPIE output      |
+| `bun run scaffold:verify`        | Regenerate codegen and type-check              |
+| `bun run migrate:create`         | Generate a migration from schema diff          |
+| `bun run migrate`                | Run pending migrations                         |
 | `bun questpie seed`              | Run pending seeds                              |
 | `docker compose up -d`           | Start PostgreSQL                               |
 
@@ -53,8 +56,8 @@ src/questpie/
 - **`src/questpie/server/modules.ts`** — Module dependencies: `export default [adminModule, openApiModule] as const`.
 - **`src/questpie/server/config/auth.ts`** — Auth config via `authConfig()` factory.
 - **`src/questpie/server/config/admin.ts`** — Admin config (sidebar, dashboard, branding, locale) via `adminConfig()` factory.
-- **`src/questpie/server/config/app.ts`** — *(optional, not scaffolded)* App config (locale, access, hooks, context) via `appConfig()`. Create when needed.
-- **`src/questpie/server/.generated/index.ts`** — Codegen output. Exports typed `app` instance and `App` type. Run `bunx questpie generate` to regenerate.
+- **`src/questpie/server/config/app.ts`** — _(optional, not scaffolded)_ App config (locale, access, hooks, context) via `appConfig()`. Create when needed.
+- **`src/questpie/server/.generated/index.ts`** — Codegen output. Exports typed `app` instance and `App` type. Run `bun run questpie:generate` to regenerate.
 - **`src/lib/env.ts`** — Type-safe env variables via `@t3-oss/env-core`. Add new env vars here with Zod schemas.
 - **`questpie.config.ts`** — CLI config (migration directory, app reference).
 - **`src/routes/api/$.ts`** — API catch-all handler. Serves REST + OpenAPI docs at `/api/docs`.
@@ -81,7 +84,7 @@ Preferred workflow:
 
 1. Run `bun questpie add collection my-thing`
 2. The CLI creates the file and auto-runs codegen
-3. Run `bun questpie migrate:create`
+3. Run `bun run migrate:create`
 
 Manual workflow:
 
@@ -90,8 +93,8 @@ Manual workflow:
    import { collection } from "#questpie/factories";
    export const myThing = collection("my-thing").fields(({ f }) => ({ ... }));
    ```
-2. Run `bunx questpie generate` to regenerate `.generated/index.ts`
-3. Run `bun questpie migrate:create` to generate migration
+2. Run `bun run questpie:generate` to regenerate `.generated/index.ts`
+3. Run `bun run migrate:create` to generate migration
 
 Collections are auto-discovered by codegen — no manual registration needed.
 
@@ -101,13 +104,13 @@ Preferred workflow:
 
 1. Run `bun questpie add global my-global`
 2. The CLI creates the file and auto-runs codegen
-3. Run `bun questpie migrate:create`
+3. Run `bun run migrate:create`
 
 Manual workflow:
 
 1. Create `src/questpie/server/globals/my-global.ts` with a named export
-2. Run `bunx questpie generate`
-3. Run `bun questpie migrate:create`
+2. Run `bun run questpie:generate`
+3. Run `bun run migrate:create`
 
 ### Add a server route (end-to-end type-safe)
 
@@ -126,7 +129,7 @@ Manual workflow:
    	});
    ```
 
-2. Run `bunx questpie generate` — route is auto-discovered and available at `/api/my-function`
+2. Run `bun run questpie:generate` — route is auto-discovered and available at `/api/my-function`
 
 See AGENTS.md for detailed route patterns, access control, and TanStack Query integration.
 

package/templates/tanstack-start/README.md

@@ -15,11 +15,14 @@ A [QUESTPIE](https://questpie.com) app built with TanStack Start.
 # 1) Start PostgreSQL
 docker compose up -d
 
-# 2) Run migrations
-bun questpie migrate
+# 2) Regenerate codegen and type-check
+bun run scaffold:verify
 
-# 3) Start development server
-bun dev
+# 3) Run migrations
+bun run migrate
+
+# 4) Start development server
+bun run dev
 ```
 
 - Admin panel: `http://localhost:3000/admin`
@@ -67,10 +70,13 @@ migrations/
 | `bun build`                      | Build for production                          |
 | `bun start`                      | Start production server                       |
 | `bun check-types`                | Type check                                    |
+| `bun run scaffold:generate`      | Regenerate routes and QUESTPIE codegen        |
+| `bun run scaffold:verify`        | Regenerate codegen and type-check             |
+| `bun run routes:generate`        | Regenerate TanStack Router route tree         |
+| `bun run questpie:generate`      | Regenerate `src/questpie/server/.generated/*` |
 | `bun questpie add <type> <name>` | Scaffold entity files (auto-runs codegen)     |
-| `bun questpie migrate`           | Run migrations                                |
-| `bun questpie migrate:create`    | Create migration                              |
-| `bunx questpie generate`         | Regenerate `src/questpie/server/.generated/*` |
+| `bun run migrate`                | Run migrations                                |
+| `bun run migrate:create`         | Create migration                              |
 
 ## Adding a Collection
 
@@ -78,14 +84,14 @@ Preferred workflow:
 
 1. Run `bun questpie add collection products`.
 2. The CLI creates the file and runs codegen automatically.
-3. Run `bun questpie migrate:create`.
+3. Run `bun run migrate:create`.
 
 Manual workflow (when you create files by hand):
 
 1. Create a file in `src/questpie/server/collections/`.
 2. Export a collection builder from that file.
-3. Run `bunx questpie generate`.
-4. Run `bun questpie migrate:create`.
+3. Run `bun run questpie:generate`.
+4. Run `bun run migrate:create`.
 
 Collections are discovered automatically by codegen. No manual `app.ts` registration is required.
 
@@ -95,13 +101,13 @@ Preferred workflow:
 
 1. Run `bun questpie add global marketing`.
 2. The CLI creates the file and runs codegen automatically.
-3. Run `bun questpie migrate:create`.
+3. Run `bun run migrate:create`.
 
 Manual workflow (when you create files by hand):
 
 1. Create a file in `src/questpie/server/globals/`.
 2. Export a global builder from that file.
-3. Run `bunx questpie generate`.
-4. Run `bun questpie migrate:create`.
+3. Run `bun run questpie:generate`.
+4. Run `bun run migrate:create`.
 
 Globals are discovered automatically by codegen. No manual `app.ts` registration is required.

package/templates/tanstack-start/env.example

@@ -6,7 +6,7 @@ APP_URL=http://localhost:3000
 PORT=3000
 
 # Auth (Better Auth)
-BETTER_AUTH_SECRET=your-secret-key-change-in-production
+BETTER_AUTH_SECRET={{authSecret}}
 
 # Email Adapter (console | smtp)
 MAIL_ADAPTER=console