create-questpie 2.0.4 → 2.1.0

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

@@ -1,449 +0,0 @@
----
-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.