@questpie/admin 1.1.1 → 3.0.0

package/dist/server/augmentation/views.d.mts

@@ -0,0 +1,237 @@
+import { ComponentReference } from "./common.mjs";
+import { FormViewConfig, ListViewConfig } from "./form-layout.mjs";
+
+//#region src/server/augmentation/views.d.ts
+
+/**
+ * Open augmentation point for view kinds.
+ * Plugins extend this interface to register new view kinds.
+ *
+ * The admin plugin registers "list" and "form" by default.
+ * Third-party plugins can add new kinds (e.g., "dashboard", "kanban-board").
+ *
+ * @example
+ * ```ts
+ * // Admin plugin declares:
+ * declare module "@questpie/admin/server" {
+ *   interface ViewKindRegistry {
+ *     list: {};
+ *     edit: {};
+ *   }
+ * }
+ *
+ * // Third-party plugin extends:
+ * declare module "@questpie/admin/server" {
+ *   interface ViewKindRegistry {
+ *     dashboard: {};
+ *   }
+ * }
+ * ```
+ */
+interface ViewKindRegistry {
+  list: {};
+  form: {};
+}
+/**
+ * Union of all registered view kind names.
+ * Derived from ViewKindRegistry — automatically extends when plugins
+ * augment the registry.
+ */
+type ViewKind = keyof ViewKindRegistry;
+/**
+ * Type-level filter that selects views matching a specific kind.
+ *
+ * Used by codegen to derive list/form view types from the unified `views` registry
+ * without needing separate `listViews`/`formViews` categories.
+ *
+ * @example
+ * ```ts
+ * type ListViews = FilterViewsByKind<AllViews, "list">;
+ * type FormViews = FilterViewsByKind<AllViews, "form">;
+ * ```
+ */
+type FilterViewsByKind<TViews, TKind extends ViewKind> = { [K in keyof TViews as TViews[K] extends {
+  kind: TKind;
+} ? K : never]: TViews[K] };
+/**
+ * Unified view definition with `kind` discriminant.
+ *
+ * The `kind` field determines which builder extension this view is used in:
+ * - `"list"` → available in `.list()` callback
+ * - `"form"` → available in `.form()` callback
+ *
+ * Each view carries its own config — codegen extracts the type and
+ * introspection serializes the schema for the client.
+ */
+interface ViewDefinition<TName extends string = string, TKind extends ViewKind = ViewKind, TConfig = unknown> {
+  type: "view";
+  name: TName;
+  kind: TKind;
+  /**
+   * Phantom type marker carrying the view's config type.
+   *
+   * Not used at runtime — only exists for TypeScript to extract
+   * per-view config in `ListViewFactory` / `EditViewFactory`.
+   * When a user calls `v.collectionTable({ columns: [...] })`, TypeScript
+   * infers the config shape from this phantom field.
+   *
+   * @example
+   * ```ts
+   * // views/kanban.ts
+   * export default view<KanbanConfig>("kanban", { kind: "list" });
+   * // → ViewDefinition<"kanban", "list", KanbanConfig>
+   * // → v.kanban({ groupBy: "status" }) type-checks against KanbanConfig
+   * ```
+   */
+  readonly "~config"?: TConfig;
+  [key: string]: unknown;
+}
+/**
+ * View definition for list views (table, cards, etc.)
+ * @deprecated Use ViewDefinition with kind: "list" instead.
+ */
+interface ListViewDefinition<TName extends string = string> {
+  type: "listView";
+  name: TName;
+}
+/**
+ * View definition for edit views (form, wizard, etc.)
+ * @deprecated Use ViewDefinition with kind: "form" instead.
+ */
+interface EditViewDefinition<TName extends string = string> {
+  type: "editView";
+  name: TName;
+}
+/**
+ * Component definition for reusable UI components.
+ *
+ * The `TProps` phantom type carries the input props type that
+ * `c.myComponent(props)` accepts in `.admin()` callbacks.
+ * When omitted, falls back to `Record<string, unknown> | string`.
+ *
+ * @example
+ * ```ts
+ * // components/icon.ts
+ * export default component<string | { name: string }>("icon");
+ * // → c.icon("ph:users") type-checks against string | { name: string }
+ *
+ * // components/rating.ts
+ * interface RatingProps { value: number; max?: number }
+ * export default component<RatingProps>("rating");
+ * // → c.rating({ value: 4, max: 5 }) type-checks against RatingProps
+ * ```
+ */
+interface ComponentDefinition<TName extends string = string, TProps = unknown> {
+  type: "component";
+  name: TName;
+  /** Phantom type marker carrying the component's input props type. */
+  readonly "~props"?: TProps;
+}
+/**
+ * Extract the input props type from a ComponentDefinition.
+ * Falls back to `TFallback` when the component has `unknown` props.
+ */
+type ExtractComponentProps<TComponent, TFallback = Record<string, unknown> | string> = TComponent extends ComponentDefinition<any, infer P> ? unknown extends P ? TFallback : P : TFallback;
+/**
+ * Normalize component input props to output props for ComponentReference.
+ * Handles string shorthand: `string | X` → just `X` (the string is
+ * normalized to the object form at runtime by the proxy).
+ */
+type NormalizeComponentOutput<TProps> = TProps extends string ? Record<string, unknown> : Exclude<TProps, string>;
+/**
+ * Component factory API generated from registered components.
+ *
+ * Each key is a callable that accepts the **per-component props type** extracted
+ * from the ComponentDefinition's `~props` phantom field.
+ *
+ * Accepts either a components record (per-component typed props) or a string
+ * union (fallback: all components use `Record<string, unknown> | string`).
+ *
+ * Note: `c.icon("ph:users")` string shorthand is supported when the component
+ * definition includes `string` in its props union.
+ */
+type ComponentFactory<TComponents extends Record<string, any> | string = string> = TComponents extends Record<string, any> ? { [K in keyof TComponents & string]: (props: ExtractComponentProps<TComponents[K]>) => ComponentReference<K, NormalizeComponentOutput<ExtractComponentProps<TComponents[K]>> extends Record<string, unknown> ? NormalizeComponentOutput<ExtractComponentProps<TComponents[K]>> : Record<string, unknown>> } : { [K in TComponents & string]: (props: Record<string, unknown> | string) => ComponentReference<K, Record<string, unknown>> };
+/**
+ * Extract the config type from a ViewDefinition.
+ * Falls back to `TFallback` when the view has `unknown` config
+ * (i.e. was defined without a config type parameter).
+ */
+type ExtractViewConfig<TView, TFallback = Record<string, unknown>> = TView extends ViewDefinition<any, any, infer C> ? unknown extends C ? TFallback : C : TFallback;
+/**
+ * View factory API generated from registered list views.
+ *
+ * Each key is a callable that accepts the **per-view config type** extracted
+ * from the ViewDefinition's `~config` phantom field. When a view was defined
+ * with `view<ListViewConfig>("collection-table", { kind: "list" })`, calling `v.collectionTable()`
+ * type-checks against `Omit<ListViewConfig, "view">`. A custom
+ * `view<KanbanConfig>("kanban", ...)` would type-check against `KanbanConfig`.
+ *
+ * Accepts either a views record (per-view typed config) or a string union
+ * (fallback: all views use `ListViewConfig`).
+ */
+type ListViewFactory<TListViews extends Record<string, any> | string = string> = TListViews extends Record<string, any> ? { [K in keyof TListViews & string]: (config: Omit<ExtractViewConfig<TListViews[K], ListViewConfig>, "view">) => ExtractViewConfig<TListViews[K], ListViewConfig> & {
+  view: K;
+} } : { [K in TListViews & string]: (config: Omit<ListViewConfig, "view">) => ListViewConfig & {
+  view: K;
+} };
+/**
+ * View factory API generated from registered edit views.
+ *
+ * Same pattern as ListViewFactory but for edit views,
+ * with `FormViewConfig` as the fallback config type.
+ */
+type EditViewFactory<TEditViews extends Record<string, any> | string = string> = TEditViews extends Record<string, any> ? { [K in keyof TEditViews & string]: (config: Omit<ExtractViewConfig<TEditViews[K], FormViewConfig>, "view">) => ExtractViewConfig<TEditViews[K], FormViewConfig> & {
+  view: K;
+} } : { [K in TEditViews & string]: (config: Omit<FormViewConfig, "view">) => FormViewConfig & {
+  view: K;
+} };
+/**
+ * Context for list view config functions.
+ *
+ * `TListViews` can be either a views record (per-view typed config)
+ * or a string union (backward-compatible, all views use `ListViewConfig`).
+ */
+interface ListViewConfigContext<TFields extends Record<string, any> = Record<string, any>, TListViews extends Record<string, any> | string = string> {
+  /** View factory — per-view typed config extracted from ViewDefinition */
+  v: ListViewFactory<TListViews>;
+  /** Field reference proxy - returns field names as strings */
+  f: { [K in keyof TFields]: K };
+  /** Action reference proxy */
+  a: {
+    create: string;
+    save: string;
+    delete: string;
+    deleteMany: string;
+    restore: string;
+    restoreMany: string;
+    duplicate: string;
+    export: string;
+    custom: (name: string, config?: unknown) => {
+      type: string;
+      config?: unknown;
+    };
+  };
+}
+/**
+ * Context for form view config functions.
+ *
+ * `TEditViews` can be either a views record (per-view typed config)
+ * or a string union (backward-compatible, all views use `FormViewConfig`).
+ */
+interface FormViewConfigContext<TFields extends Record<string, any> = Record<string, any>, TEditViews extends Record<string, any> | string = string> {
+  /** View factory — per-view typed config extracted from ViewDefinition */
+  v: EditViewFactory<TEditViews>;
+  /** Field reference proxy - returns field names as strings */
+  f: { [K in keyof TFields]: K };
+}
+/**
+ * Context for admin config functions with component proxy.
+ *
+ * `TComponents` can be either a components record (per-component typed props)
+ * or a string union (backward-compatible, all components use `Record<string, unknown> | string`).
+ */
+interface AdminConfigContext<TComponents extends Record<string, any> | string = string> {
+  c: ComponentFactory<TComponents>;
+}
+//#endregion
+export { AdminConfigContext, ComponentDefinition, ComponentFactory, EditViewDefinition, EditViewFactory, FilterViewsByKind, FormViewConfigContext, ListViewConfigContext, ListViewDefinition, ListViewFactory, ViewDefinition, ViewKind, ViewKindRegistry };

package/dist/server/augmentation.d.mts

@@ -0,0 +1,7 @@
+import { ActionReference, AdminLocaleConfig, ComponentReference, ComponentType, ComponentTypeRegistry } from "./augmentation/common.mjs";
+import { AdminBlockConfig, AdminCollectionConfig, AdminGlobalConfig, BlockCategoryConfig, FieldLayoutItem, FormFieldLayoutItem, FormReactiveConfig, FormReactiveContext, FormSectionLayout, FormSidebarConfig, FormTabConfig, FormTabsLayout, FormViewConfig, ListViewConfig, PreviewConfig } from "./augmentation/form-layout.mjs";
+import { AdminConfigContext, ComponentDefinition, ComponentFactory, EditViewDefinition, EditViewFactory, FilterViewsByKind, FormViewConfigContext, ListViewConfigContext, ListViewDefinition, ListViewFactory, ViewDefinition, ViewKind, ViewKindRegistry } from "./augmentation/views.mjs";
+import { DashboardActionFactory, DashboardActionProxy, DashboardCallback, DashboardCallbackContext, DashboardConfigContext, DashboardContribution, DashboardItemDef, DashboardProxy, DashboardSectionDef, ServerBrandingConfig, ServerChartWidget, ServerCustomWidget, ServerDashboardAction, ServerDashboardConfig, ServerDashboardItem, ServerDashboardSection, ServerDashboardTab, ServerDashboardTabs, ServerDashboardWidget, ServerProgressWidget, ServerQuickAction, ServerQuickActionsWidget, ServerRecentItemsWidget, ServerStatsWidget, ServerTableWidget, ServerTimelineWidget, ServerValueWidget, WidgetAccessRule, WidgetFetchContext } from "./augmentation/dashboard.mjs";
+import { ServerSidebarCollectionItem, ServerSidebarConfig, ServerSidebarDividerItem, ServerSidebarGlobalItem, ServerSidebarItem, ServerSidebarLinkItem, ServerSidebarPageItem, ServerSidebarSection, SidebarCallback, SidebarCallbackContext, SidebarConfigContext, SidebarContribution, SidebarItemDef, SidebarProxy, SidebarSectionDef } from "./augmentation/sidebar.mjs";
+import { ActionsConfigContext, BuiltinActionType, ServerActionContext, ServerActionDefinition, ServerActionDownload, ServerActionEffects, ServerActionError, ServerActionForm, ServerActionFormField, ServerActionFormFieldConfig, ServerActionFormFieldDefinition, ServerActionHandler, ServerActionRedirect, ServerActionResult, ServerActionSuccess, ServerActionsConfig } from "./augmentation/actions.mjs";
+import { AdminConfigInput, adminConfig } from "./augmentation/index.mjs";

package/dist/server/block/index.d.mts

@@ -0,0 +1,4 @@
+import { AnyBlockBuilder, AnyBlockDefinition, BlockBuilder, BlockBuilderState, BlockDefinition, BlockPrefetchContext, BlockPrefetchFn, BlockPrefetchWith, BlockPrefetchWithOptions, ExpandWithResult, ExpandedRecord, InferBlockData, InferBlockValues, block } from "../modules/admin/block/block-builder.mjs";
+import { BlockSchema, getBlocksByCategory, introspectBlock, introspectBlocks } from "../modules/admin/block/introspection.mjs";
+import { BlocksPrefetchContext, createBlocksPrefetchHook, processBlocksDocument, processDocumentBlocksPrefetch } from "../modules/admin/block/prefetch.mjs";
+import "../modules/admin/block/index.mjs";

package/dist/server/codegen/admin-client-template.mjs

@@ -0,0 +1,93 @@
+//#region src/server/codegen/admin-client-template.ts
+/**
+* Generate the admin client config file.
+*
+* Called by `runAllTargets()` for the `admin-client` target.
+* Iterates `ctx.discovered.categories` generically — no hardcoded category names.
+* Any plugin can add categories, any user can add files in any category.
+*/
+function generateAdminClientTemplate(ctx) {
+	const lines = [];
+	const modulesFile = ctx.discovered.singles.get("modules") ?? null;
+	lines.push("/**");
+	lines.push(" * Admin Client Config");
+	lines.push(" *");
+	lines.push(" * Auto-generated by questpie codegen — do not edit.");
+	lines.push(" *");
+	lines.push(" * Pass this directly to <AdminLayoutProvider admin={admin} />");
+	lines.push(" */");
+	lines.push("");
+	if (modulesFile) lines.push(generateImportLine(modulesFile));
+	const categoryFiles = /* @__PURE__ */ new Map();
+	for (const [cat, fileMap] of ctx.discovered.categories) if (fileMap.size > 0) {
+		const sorted = [...fileMap.values()].sort((a, b) => a.key.localeCompare(b.key));
+		categoryFiles.set(cat, sorted);
+		for (const file of sorted) lines.push(generateImportLine(file));
+	}
+	const singleFiles = /* @__PURE__ */ new Map();
+	for (const [key, file] of ctx.discovered.singles) {
+		if (key === "modules") continue;
+		singleFiles.set(key, file);
+		lines.push(generateImportLine(file));
+	}
+	for (const imp of ctx.extraImports) lines.push(`import ${imp.name} from "${imp.path}";`);
+	lines.push("");
+	const hasAnyUserFiles = categoryFiles.size > 0 || singleFiles.size > 0;
+	const hasExtraCode = ctx.extraRuntimeCode.length > 0;
+	const allCategories = /* @__PURE__ */ new Set();
+	for (const cat of ctx.discovered.categories.keys()) allCategories.add(cat);
+	if (ctx.target.categories) for (const cat of Object.keys(ctx.target.categories)) allCategories.add(cat);
+	if (!hasAnyUserFiles && !hasExtraCode && !modulesFile) lines.push("const admin = {};");
+	else if (!hasAnyUserFiles && !hasExtraCode && modulesFile) lines.push(`const admin = ${modulesFile.varName};`);
+	else {
+		lines.push("const admin = {");
+		for (const cat of allCategories) {
+			const files = categoryFiles.get(cat);
+			const catDecl = ctx.target.categories?.[cat];
+			if (modulesFile && files && files.length > 0) {
+				const entries = generateCategoryEntries(files, catDecl);
+				lines.push(`\t${cat}: { ...${modulesFile.varName}.${cat}, ${entries} },`);
+			} else if (modulesFile && (!files || files.length === 0)) lines.push(`\t${cat}: { ...${modulesFile.varName}.${cat} },`);
+			else if (files && files.length > 0) {
+				const entries = generateCategoryEntries(files, catDecl);
+				lines.push(`\t${cat}: { ${entries} },`);
+			}
+		}
+		for (const [key, file] of singleFiles) lines.push(`\t${key}: ${file.varName},`);
+		for (const code of ctx.extraRuntimeCode) lines.push(`\t${code}`);
+		lines.push("};");
+	}
+	if (ctx.extraTypeDeclarations.length > 0) {
+		lines.push("");
+		for (const decl of ctx.extraTypeDeclarations) lines.push(decl);
+	}
+	lines.push("");
+	lines.push("export default admin;");
+	lines.push("");
+	return { code: lines.join("\n") };
+}
+/**
+* Generate category entries string based on the category's key strategy.
+*
+* When `keyFromProperty` is set (e.g., views with `keyFromProperty: "name"`),
+* uses runtime property as key: `[_view_kanban.name]: _view_kanban`.
+*
+* Otherwise uses the file-derived key: `"bookingCta": _block_bookingCta`.
+*/
+function generateCategoryEntries(files, catDecl) {
+	const keyProp = catDecl?.keyFromProperty;
+	return files.map((f) => {
+		if (keyProp) return `[${f.varName}.${keyProp}]: ${f.varName}`;
+		return `${JSON.stringify(f.key)}: ${f.varName}`;
+	}).join(", ");
+}
+/**
+* Generate an import line for a discovered file.
+*/
+function generateImportLine(file) {
+	if (file.exportType === "named" && file.namedExportName) return `import { ${file.namedExportName} as ${file.varName} } from "${file.importPath}";`;
+	return `import ${file.varName} from "${file.importPath}";`;
+}
+
+//#endregion
+export { generateAdminClientTemplate };

package/dist/server/codegen/projection-validator.mjs

@@ -0,0 +1,67 @@
+//#region src/server/codegen/projection-validator.ts
+/**
+* Category projections to validate between server and admin-client.
+*
+* Each entry describes a server-side category whose discovered keys
+* must have a corresponding key in the admin-client target.
+*
+* `serverCategory` = category name in the "server" target discovery
+* `clientCategory` = category name in the "admin-client" target discovery
+* `suggestedDir`   = where the user should create the missing file
+*/
+const PROJECTION_CHECKS = [
+	{
+		serverCategory: "blocks",
+		clientCategory: "blocks",
+		suggestedDir: "questpie/admin/blocks",
+		label: "block renderer"
+	},
+	{
+		serverCategory: "views",
+		clientCategory: "views",
+		suggestedDir: "questpie/admin/views",
+		label: "view definition"
+	},
+	{
+		serverCategory: "components",
+		clientCategory: "components",
+		suggestedDir: "questpie/admin/components",
+		label: "component definition"
+	}
+];
+/**
+* Create a cross-target validator for admin projection checks.
+*
+* Compares discovered file keys between the "server" and "admin-client"
+* targets. Any key present in the server target but missing from the
+* admin-client target produces an error.
+*
+* @returns A `CrossTargetValidator` function
+*/
+function createAdminProjectionValidator() {
+	return (targets) => {
+		const serverResult = targets.get("server");
+		const adminClientResult = targets.get("admin-client");
+		if (!serverResult || !adminClientResult) return [];
+		const errors = [];
+		for (const check of PROJECTION_CHECKS) {
+			const serverFiles = serverResult.discovered.categories.get(check.serverCategory);
+			const clientFiles = adminClientResult.discovered.categories.get(check.clientCategory);
+			if (!serverFiles || serverFiles.size === 0) continue;
+			const clientKeys = /* @__PURE__ */ new Set();
+			if (clientFiles) for (const key of clientFiles.keys()) clientKeys.add(key);
+			for (const [key, file] of serverFiles) if (!clientKeys.has(key)) errors.push({
+				severity: "error",
+				category: check.serverCategory,
+				key,
+				sourceTarget: "server",
+				consumerTarget: "admin-client",
+				message: `Server defines ${check.serverCategory}/${file.key} but no matching ${check.label} was found in the admin client. Create a file at ${check.suggestedDir}/${file.key}.tsx to fix this.`
+			});
+		}
+		return errors;
+	};
+}
+
+//#endregion
+export { createAdminProjectionValidator };

package/dist/server/fields/blocks.d.mts

@@ -0,0 +1,71 @@
+import { DefaultFieldState, Field } from "questpie";
+import { PgJsonbBuilder } from "drizzle-orm/pg-core";
+
+//#region src/server/fields/blocks.d.ts
+
+/**
+ * Block node in the tree structure.
+ * Each block has an id, type, and optional children.
+ */
+interface BlockNode {
+  /** Unique identifier for this block instance */
+  id: string;
+  /** Block type name (e.g., "hero", "text", "image") */
+  type: string;
+  /** Nested child blocks */
+  children: BlockNode[];
+}
+/**
+ * Block field values.
+ * Maps field names to their values for a single block.
+ */
+type BlockValues = Record<string, {}>;
+/**
+ * Blocks document structure.
+ * Normalized format separating tree structure from values.
+ */
+interface BlocksDocument {
+  /** Tree structure defining block hierarchy */
+  _tree: BlockNode[];
+  /** Map of block id to field values */
+  _values: Record<string, BlockValues>;
+  /** Prefetched data for blocks (populated by afterRead hook) */
+  _data?: Record<string, Record<string, {}>>;
+}
+/**
+ * Blocks field metadata - augmentable by external packages.
+ *
+ * @example Admin augmentation:
+ * ```ts
+ * declare module "@questpie/admin/server" {
+ *   interface BlocksFieldMeta {
+ *     admin?: {
+ *       addLabel?: string;
+ *       emptyMessage?: string;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface BlocksFieldMeta {
+  /** Phantom property to prevent interface collapse - enables module augmentation */
+  _?: never;
+}
+/**
+ * Blocks field factory.
+ * Creates a visual block editor field for page builder functionality.
+ *
+ * @example
+ * ```ts
+ * // In collection fields callback:
+ * sections: f.blocks().required()
+ * ```
+ */
+type BlocksFieldState = DefaultFieldState & {
+  type: "blocks";
+  data: BlocksDocument;
+  column: PgJsonbBuilder;
+};
+declare function blocks(): Field<BlocksFieldState>;
+//#endregion
+export { BlockNode, BlockValues, BlocksDocument, BlocksFieldMeta, BlocksFieldState, blocks };

package/dist/server/fields/blocks.mjs

@@ -0,0 +1,151 @@
+import { processBlocksDocument } from "../modules/admin/block/prefetch.mjs";
+import { z } from "zod";
+import { field, fieldType, getContext, isNotNull, isNull, jsonb, sql } from "questpie";
+
+//#region src/server/fields/blocks.ts
+/**
+* Get operators for blocks field.
+* Provides operators for querying block content.
+*/
+function getBlocksOperators() {
+	return {
+		column: {
+			hasBlockType: (col, value) => sql`EXISTS (
+					SELECT 1 FROM jsonb_array_elements(${col}->'_tree') AS block
+					WHERE block->>'type' = ${value}
+				)`,
+			blockCount: (col, value) => {
+				const { op, count } = value;
+				const operator = op === "gte" ? ">=" : op === "lte" ? "<=" : "=";
+				return sql`jsonb_array_length(${col}->'_tree') ${sql.raw(operator)} ${count}`;
+			},
+			isEmpty: (col) => sql`(
+					${col} IS NULL 
+					OR ${col}->'_tree' IS NULL
+					OR jsonb_array_length(${col}->'_tree') = 0
+				)`,
+			isNotEmpty: (col) => sql`(
+					${col} IS NOT NULL 
+					AND ${col}->'_tree' IS NOT NULL
+					AND jsonb_array_length(${col}->'_tree') > 0
+				)`,
+			isNull: (col) => isNull(col),
+			isNotNull: (col) => isNotNull(col)
+		},
+		jsonb: {
+			hasBlockType: (col, value, ctx) => {
+				const path = ctx.jsonbPath?.join(",") ?? "";
+				return sql`EXISTS (
+					SELECT 1 FROM jsonb_array_elements(${col}#>'{${sql.raw(path)},_tree}') AS block
+					WHERE block->>'type' = ${value}
+				)`;
+			},
+			isEmpty: (col, _value, ctx) => {
+				const path = ctx.jsonbPath?.join(",") ?? "";
+				return sql`(
+					${col}#>'{${sql.raw(path)}}' IS NULL 
+					OR ${col}#>'{${sql.raw(path)},_tree}' IS NULL
+					OR jsonb_array_length(${col}#>'{${sql.raw(path)},_tree}') = 0
+				)`;
+			},
+			isNotEmpty: (col, _value, ctx) => {
+				const path = ctx.jsonbPath?.join(",") ?? "";
+				return sql`(
+					${col}#>'{${sql.raw(path)}}' IS NOT NULL 
+					AND ${col}#>'{${sql.raw(path)},_tree}' IS NOT NULL
+					AND jsonb_array_length(${col}#>'{${sql.raw(path)},_tree}') > 0
+				)`;
+			},
+			isNull: (col, _value, ctx) => {
+				const path = ctx.jsonbPath?.join(",") ?? "";
+				return sql`${col}#>'{${sql.raw(path)}}' IS NULL`;
+			},
+			isNotNull: (col, _value, ctx) => {
+				const path = ctx.jsonbPath?.join(",") ?? "";
+				return sql`${col}#>'{${sql.raw(path)}}' IS NOT NULL`;
+			}
+		}
+	};
+}
+/**
+* Create a blocks field.
+*
+* @example
+* ```ts
+* sections: f.blocks().required()
+* ```
+*/
+/**
+* Blocks field runtime state factory.
+* Shared between the legacy `blocks()` function and the new `blocksFieldType`.
+*/
+function createBlocksState() {
+	return {
+		type: "blocks",
+		columnFactory: (name) => jsonb(name),
+		schemaFactory: () => {
+			const blockNodeSchema = z.lazy(() => z.object({
+				id: z.string(),
+				type: z.string(),
+				children: z.array(blockNodeSchema).default([])
+			}));
+			return z.object({
+				_tree: z.array(blockNodeSchema),
+				_values: z.record(z.string(), z.record(z.string(), z.any()))
+			});
+		},
+		operatorSet: {
+			jsonbCast: null,
+			column: getBlocksOperators().column
+		},
+		metadataFactory: (state) => ({
+			type: "blocks",
+			label: state.label,
+			description: state.description,
+			required: state.notNull ?? false,
+			localized: state.localized ?? false,
+			readOnly: state.input === false ? true : void 0,
+			writeOnly: state.output === false ? true : void 0,
+			meta: state.extensions?.admin
+		}),
+		hooks: { afterRead: async (value) => {
+			if (!value || typeof value !== "object") return value;
+			const doc = value;
+			if (!doc._tree || !doc._values) return value;
+			try {
+				const { app, db, locale } = getContext();
+				const blockDefs = app.state?.blocks;
+				if (!blockDefs || Object.keys(blockDefs).length === 0) return value;
+				return await processBlocksDocument(doc, blockDefs, {
+					app,
+					db,
+					locale,
+					collections: app.collections,
+					globals: app.globals
+				});
+			} catch {
+				return value;
+			}
+		} },
+		notNull: false,
+		hasDefault: false,
+		localized: false,
+		virtual: false,
+		input: true,
+		output: true,
+		isArray: false
+	};
+}
+function blocks() {
+	return field(createBlocksState());
+}
+/**
+* Blocks field type definition (v3 API).
+*
+* Use this with the `fieldType()` discovery system instead of the
+* legacy `blocks()` factory function.
+*/
+const blocksFieldType = fieldType("blocks", { create: createBlocksState });
+
+//#endregion
+export { blocks };

package/dist/server/fields/index.d.mts

@@ -0,0 +1,15 @@
+import { BlockNode, BlockValues, BlocksDocument, BlocksFieldMeta, BlocksFieldState, blocks } from "./blocks.mjs";
+import { RichTextFeature, RichTextFieldMeta, RichTextFieldState, TipTapDocument, TipTapNode, richText } from "./rich-text.mjs";
+
+//#region src/server/fields/index.d.ts
+
+/**
+ * Admin field types to be registered with the field registry.
+ * These are V2 factory functions — callable in `.fields()` callbacks.
+ */
+declare const adminFields: {
+  readonly richText: typeof richText;
+  readonly blocks: typeof blocks;
+};
+//#endregion
+export { adminFields };

package/dist/server/fields/index.mjs

@@ -0,0 +1,15 @@
+import { blocks } from "./blocks.mjs";
+import { richText } from "./rich-text.mjs";
+
+//#region src/server/fields/index.ts
+/**
+* Admin field types to be registered with the field registry.
+* These are V2 factory functions — callable in `.fields()` callbacks.
+*/
+const adminFields = {
+	richText,
+	blocks
+};
+
+//#endregion
+export { adminFields };