rimecms 0.28.10 → 0.30.0

package/dist/core/dev/generate/types/index.server.js

@@ -146,7 +146,7 @@ export async function generateTypesString(config) {
     const treeBlocksTypes = [];
     const registeredBlocks = [];
     const registeredTreeBlocks = [];
-    let imports = new Set(['BaseDoc', 'Navigation', 'User']);
+    let imports = new Set(['BaseDoc', 'Navigation', 'RouteHandlers', 'User']);
     const addImport = (string) => {
         imports = new Set([...imports, string]);
     };
@@ -171,50 +171,50 @@ export async function generateTypesString(config) {
         for (const field of fields) {
             if (field instanceof BlocksBuilder) {
                 {
-                    for (const block of field.raw.blocks) {
-                        if (!registeredBlocks.includes(block.raw.name)) {
-                            const templates = await buildFieldsTypes(block.raw.fields
+                    for (const block of field.get.blocks) {
+                        if (!registeredBlocks.includes(block.name)) {
+                            const templates = await buildFieldsTypes(block.get.fields
                                 .filter((field) => field instanceof FormFieldBuilder)
                                 .filter((field) => field.name !== 'type'));
-                            blocksTypes.push(makeBlockType(block.raw.name, templates.join('\n\t')));
-                            registeredBlocks.push(block.raw.name);
-                            buildblocksTypes(block.raw.fields);
+                            blocksTypes.push(makeBlockType(block.name, templates.join('\n\t')));
+                            registeredBlocks.push(block.name);
+                            buildblocksTypes(block.get.fields);
                         }
                     }
                 }
             }
             else if (field instanceof TabsBuilder) {
-                for (const tab of field.raw.tabs) {
-                    await buildblocksTypes(tab.raw.fields);
+                for (const tab of field.get.tabs) {
+                    await buildblocksTypes(tab.get.fields);
                 }
             }
             else if (field instanceof GroupFieldBuilder) {
-                await buildblocksTypes(field.raw.fields);
+                await buildblocksTypes(field.get.fields);
             }
             else if (field instanceof TreeBuilder) {
-                await buildblocksTypes(field.raw.fields);
+                await buildblocksTypes(field.get.fields);
             }
         }
     };
     const buildTreeBlockTypes = async (fields) => {
         for (const field of fields) {
             if (field instanceof BlocksBuilder) {
-                for (const block of field.raw.blocks) {
-                    await buildTreeBlockTypes(block.raw.fields);
+                for (const block of field.get.blocks) {
+                    await buildTreeBlockTypes(block.get.fields);
                 }
             }
             else if (field instanceof TabsBuilder) {
-                for (const tab of field.raw.tabs) {
-                    await buildTreeBlockTypes(tab.raw.fields);
+                for (const tab of field.get.tabs) {
+                    await buildTreeBlockTypes(tab.get.fields);
                 }
             }
             else if (field instanceof GroupFieldBuilder) {
-                await buildTreeBlockTypes(field.raw.fields);
+                await buildTreeBlockTypes(field.get.fields);
             }
             else if (field instanceof TreeBuilder) {
                 const treeBlockTypeName = `Tree${toPascalCase(field.name)}`;
                 if (!registeredTreeBlocks.includes(treeBlockTypeName)) {
-                    const treeFieldsTypes = await buildFieldsTypes(field.raw.fields.filter((field) => field instanceof FormFieldBuilder));
+                    const treeFieldsTypes = await buildFieldsTypes(field.get.fields.filter((field) => field instanceof FormFieldBuilder));
                     const treeBlockType = makeTreeBlockType(treeBlockTypeName, treeFieldsTypes.join('\n'));
                     treeBlocksTypes.push(treeBlockType);
                     registeredTreeBlocks.push(treeBlockTypeName);
@@ -227,7 +227,7 @@ export async function generateTypesString(config) {
         if (isUploadConfig(collection) && collection.upload.imageSizes?.length) {
             fields = collection.fields
                 .filter((f) => f instanceof FormFieldBuilder)
-                .filter((field) => !collection.upload.imageSizes.some((size) => size.name === field.raw.name));
+                .filter((field) => !collection.upload.imageSizes.some((size) => size.name === field.name));
         }
         const fieldsTypesList = await buildFieldsTypes(fields);
         if (collection.versions) {
@@ -297,8 +297,10 @@ export async function generateTypesString(config) {
 			>;
       /** Flag enabled by the core plugin rime.cache when the API cache is ON */
       cacheEnabled: boolean;
-      /** Available in panel, routes for sidebar */
-      routes: Navigation;
+      /** Available in panel, nav routes for sidebar */
+      navigation: Navigation;
+      /** Dispatch facade backing the fixed /panel/[slug]/... and /api/[slug]/... routes */
+      routes: RouteHandlers;
 			/**
 			 * Current locale if applicable
 			 * set following this prioroty :

package/dist/core/dev/vite/index.server.js

@@ -1,6 +1,7 @@
 import dotenv from 'dotenv';
 import { existsSync, rmSync } from 'node:fs';
 import path from 'node:path';
+import { RIME_DEV_CACHE_DIR } from '../../constant.server.js';
 import { ensureHasInit } from '../../ensure.server.js';
 import { logger } from '../../logger/index.server.js';
 import { INPUT_DIR, OUTPUT_DIR } from '../constants.js';
@@ -10,6 +11,13 @@ const dev = process.env.NODE_ENV === 'development';
 export function rime() {
     const VCoreId = '$rime/config';
     const VSchemaId = '$rime/schema';
+    /** General-purpose server/browser split, usable anywhere in the app (not just rime's own
+     *  field code — see relation/index.ts for the first user). `import { x } from '$rime/runtime'`
+     *  resolves to a sibling `server.ts` (server builds) or `browser.ts` (browser builds) next
+     *  to whichever file does the importing — the importer's path travels encoded in the
+     *  resolved id since `load()` only receives the id, not the importer. */
+    const VRuntimeId = '$rime/runtime';
+    const VRuntimeMarker = `\0${VRuntimeId}::`;
     const resolvedVModule = (name) => '\0' + name;
     return {
         name: 'virtual-rime',
@@ -19,10 +27,9 @@ export function rime() {
                 dev && ensureHasInit();
                 // Check if we need to rebuild
                 const shouldRebuild = process.argv.includes('--rebuild');
-                const rimeDevCacheDir = path.resolve(process.cwd(), '.rime');
-                if (shouldRebuild && existsSync(rimeDevCacheDir)) {
-                    rmSync(rimeDevCacheDir, { recursive: true, force: true });
-                    logger.info('--rebuild : .rime folder deleted');
+                if (shouldRebuild && existsSync(RIME_DEV_CACHE_DIR)) {
+                    rmSync(RIME_DEV_CACHE_DIR, { recursive: true, force: true });
+                    logger.info('--rebuild : node_modules/.rime folder deleted');
                 }
             });
             // Add a watcher for sanitizing config changes
@@ -86,19 +93,22 @@ export function rime() {
                     return [module];
             }
         },
-        resolveId(id) {
+        resolveId(id, importer) {
             if (id === VCoreId) {
                 return resolvedVModule(id);
             }
             if (id === VSchemaId) {
                 return resolvedVModule(id);
             }
+            if (id === VRuntimeId && importer) {
+                return `${VRuntimeMarker}${importer}`;
+            }
             return null;
         },
         load(id) {
             const isServer = this.environment?.config?.consumer === 'server';
             if (id === resolvedVModule(VCoreId)) {
-                const corePath = isServer ? 'rimecms/config/server' : 'rimecms/config/client';
+                const corePath = isServer ? 'rimecms/config/server' : 'rimecms/config';
                 return `export * from '${corePath}';`;
             }
             if (id === resolvedVModule(VSchemaId) && isServer) {
@@ -108,6 +118,12 @@ export function rime() {
                     return `export * from '${modulePath}'; export { default } from '${modulePath}';`;
                 }
             }
+            if (id.startsWith(VRuntimeMarker)) {
+                const importer = id.slice(VRuntimeMarker.length);
+                const dir = path.dirname(importer);
+                const target = path.join(dir, isServer ? 'runtime.server.ts' : 'runtime.ts');
+                return `export * from '${target.replace(/\.ts$/, '.js')}';`;
+            }
             return null;
         }
     };

package/dist/core/errors/handler.server.d.ts

@@ -2,13 +2,34 @@ export declare const ERROR_CONTEXT: {
     readonly ACTION: "action";
     readonly API: "api";
     readonly LOAD: "load";
-    readonly HANDLER: "handler";
 };
 export type ErrorContext = (typeof ERROR_CONTEXT)[keyof typeof ERROR_CONTEXT];
 type ErrorHandlerOptions = {
     context: ErrorContext;
     formData?: Record<string, any>;
 };
+/**
+ * Only called at the route boundary: +server.ts handlers, load functions,
+ * form actions. Everywhere else, just `throw new RimeError(...)` (centralizes
+ * error codes/messages) — it bubbles up and gets caught here, where `context`
+ * tells this function which SvelteKit primitive to translate it into:
+ * `error()` (api/load), `redirect()`, or `fail()` (action form errors).
+ *
+ * Always call it as `return handleError(...)`. Most branches throw internally
+ * (`error`/`redirect`), so `return` never runs — but the `fail()` branch (form
+ * errors in actions) is a real return value, so `return` is required there.
+ *
+ * @example +server.ts endpoint
+ * if (!id) return handleError(new RimeError(RimeError.NOT_FOUND), { context: ERROR_CONTEXT.API });
+ *
+ * @example load function
+ * const [err, doc] = await trycatch(() => getDoc(id));
+ * if (err) return handleError(err, { context: ERROR_CONTEXT.LOAD });
+ *
+ * @example form action
+ * const [err] = await trycatch(() => save(data));
+ * if (err) return handleError(err, { context: ERROR_CONTEXT.ACTION, formData: data });
+ */
 export declare function handleError(err: Error, options: ErrorHandlerOptions): import("@sveltejs/kit").ActionFailure<{
     form: Record<string, any>;
     errors: import("../../types.js").FormErrors;

package/dist/core/errors/handler.server.js

@@ -6,9 +6,30 @@ import { RimeError, RimeFormError } from './index.js';
 export const ERROR_CONTEXT = {
     ACTION: 'action',
     API: 'api',
-    LOAD: 'load',
-    HANDLER: 'handler'
+    LOAD: 'load'
 };
+/**
+ * Only called at the route boundary: +server.ts handlers, load functions,
+ * form actions. Everywhere else, just `throw new RimeError(...)` (centralizes
+ * error codes/messages) — it bubbles up and gets caught here, where `context`
+ * tells this function which SvelteKit primitive to translate it into:
+ * `error()` (api/load), `redirect()`, or `fail()` (action form errors).
+ *
+ * Always call it as `return handleError(...)`. Most branches throw internally
+ * (`error`/`redirect`), so `return` never runs — but the `fail()` branch (form
+ * errors in actions) is a real return value, so `return` is required there.
+ *
+ * @example +server.ts endpoint
+ * if (!id) return handleError(new RimeError(RimeError.NOT_FOUND), { context: ERROR_CONTEXT.API });
+ *
+ * @example load function
+ * const [err, doc] = await trycatch(() => getDoc(id));
+ * if (err) return handleError(err, { context: ERROR_CONTEXT.LOAD });
+ *
+ * @example form action
+ * const [err] = await trycatch(() => save(data));
+ * if (err) return handleError(err, { context: ERROR_CONTEXT.ACTION, formData: data });
+ */
 export function handleError(err, options) {
     const { context, formData } = options;
     /****************************************************/
@@ -17,6 +38,8 @@ export function handleError(err, options) {
     if (err instanceof RimeFormError) {
         switch (context) {
             case ERROR_CONTEXT.ACTION:
+                // fail() returns an ActionFailure — lets SvelteKit re-render the form
+                // with `errors`/`form` instead of navigating to the error boundary.
                 return fail(400, {
                     form: formData || {},
                     errors: err.errors

package/dist/core/errors/index.d.ts

@@ -20,7 +20,6 @@ declare class RimeError extends Error {
     constructor(code: string, message?: string, ...args: any);
 }
 declare class RimeFormError extends RimeError {
-    static INVALID_DATA: string;
     static INVALID_EMAIL: string;
     static INVALID_FIELD: string;
     static INVALID_PHONE: string;

package/dist/core/errors/index.js

@@ -33,7 +33,6 @@ class RimeError extends Error {
     }
 }
 class RimeFormError extends RimeError {
-    static INVALID_DATA = 'invalid_data';
     static INVALID_EMAIL = 'invalid_email';
     static INVALID_FIELD = 'invalid_field';
     static INVALID_PHONE = 'invalid_phone';

package/dist/core/fields/builders/boolean-builder.d.ts

@@ -1,4 +1,5 @@
 import type { DefaultValueFn, FieldValidationFunc, FormField } from '../../../fields/types.js';
+import type { DataType } from './form-field-builder.js';
 import { FormFieldBuilder } from './form-field-builder.js';
 type BooleanField = FormField & {
     type: any;
@@ -6,9 +7,10 @@ type BooleanField = FormField & {
     defaultValue?: boolean | DefaultValueFn<boolean>;
     validate?: FieldValidationFunc<BooleanField>;
 };
-export declare class BooleanFieldBuilder<T extends BooleanField> extends FormFieldBuilder<T> {
+export declare class BooleanFieldBuilder<T extends BooleanField = BooleanField> extends FormFieldBuilder<T> {
     constructor(name: string, type: string);
     defaultValue(value: boolean | DefaultValueFn<boolean>): this;
+    get dataType(): DataType;
     compile(): import("../../../util/types.js").WithoutBuilders<T> & {
         component: import("svelte").Component<any>;
         cell?: import("svelte").Component<{

package/dist/core/fields/builders/boolean-builder.js

@@ -8,6 +8,9 @@ export class BooleanFieldBuilder extends FormFieldBuilder {
         this.field.defaultValue = value;
         return this;
     }
+    get dataType() {
+        return 'boolean';
+    }
     compile() {
         if (!this.field.validate) {
             this.field.validate = (value) => typeof value === 'boolean' || 'Should be true/false';

package/dist/core/fields/builders/field-builder.d.ts

@@ -1,10 +1,22 @@
 import type { WithoutBuilders } from '../../../util/types.js';
 import type { Component } from 'svelte';
-import type { Field } from '../../../fields/types.js';
+import type { Field, FieldAccess } from '../../../fields/types.js';
+/** Method-syntax (not `foo: () => ...` property syntax) so subtype checks
+ *  like `FormFieldBuilder<SlugField> -> FormFieldBuilder<FormField>` — used
+ *  all over the panel, where a concrete field builder flows into a
+ *  generically-typed prop — stay bivariant on their params, exactly like the
+ *  class methods this replaced. Property syntax would make TS check those
+ *  params strictly/contravariantly and break that assignability. */
+export type FieldRun = {
+    canRead(...args: Parameters<FieldAccess>): boolean;
+    canCreate(...args: Parameters<FieldAccess>): boolean;
+    canUpdate(...args: Parameters<FieldAccess>): boolean;
+};
 export declare class FieldBuilder<T extends Field = Field> {
     field: T;
     _metaUrl?: string;
     constructor(type: string);
+    get name(): string;
     className(str: string): this;
     compile(): WithoutBuilders<T> & {
         component: Component<any>;
@@ -14,7 +26,28 @@ export declare class FieldBuilder<T extends Field = Field> {
     };
     live(bool: boolean): this;
     get type(): string;
-    get raw(): T;
+    /**
+     * Raw field data, plus the couple of properties that a bare `this.field`
+     * read can't give you: `localized`/`root` default to `false` here since
+     * only FormFieldBuilder fields ever set them — container fields like Tabs
+     * answer `false` rather than making every caller check
+     * `instanceof FormFieldBuilder` first just to ask this one question.
+     * Everything else on `T` (Tabs' `tabs`, Blocks' `blocks`, ...) comes
+     * through unchanged via the spread — no per-subclass override needed.
+     */
+    get get(): T & {
+        localized: boolean;
+        root: boolean;
+    };
+    /** Behavior the builder runs on your behalf (invoking a stored function) —
+     *  see `.get` for plain data reads. Fields without an access concept
+     *  (Tabs) default every check to allowed, matching how the field-less case
+     *  already behaved. Params are unused here but must match FormFieldBuilder's
+     *  override signature — TS checks generic-constraint satisfaction
+     *  (`T extends FieldBuilder<any>`) strictly, not with the bivariant
+     *  leniency normal overrides get, so a param-less base signature breaks
+     *  assignability everywhere. */
+    get run(): FieldRun;
     get component(): Component<any> | null;
     get cell(): Component<{
         value: any;

package/dist/core/fields/builders/field-builder.js

@@ -3,10 +3,14 @@ export class FieldBuilder {
     _metaUrl;
     constructor(type) {
         this.field = {
+            name: '',
             type,
             live: true
         };
     }
+    get name() {
+        return this.field.name;
+    }
     className(str) {
         this.field.className = str;
         return this;
@@ -25,8 +29,35 @@ export class FieldBuilder {
     get type() {
         return this.field.type;
     }
-    get raw() {
-        return this.field;
+    /**
+     * Raw field data, plus the couple of properties that a bare `this.field`
+     * read can't give you: `localized`/`root` default to `false` here since
+     * only FormFieldBuilder fields ever set them — container fields like Tabs
+     * answer `false` rather than making every caller check
+     * `instanceof FormFieldBuilder` first just to ask this one question.
+     * Everything else on `T` (Tabs' `tabs`, Blocks' `blocks`, ...) comes
+     * through unchanged via the spread — no per-subclass override needed.
+     */
+    get get() {
+        return { ...this.field, localized: false, root: false };
+    }
+    /** Behavior the builder runs on your behalf (invoking a stored function) —
+     *  see `.get` for plain data reads. Fields without an access concept
+     *  (Tabs) default every check to allowed, matching how the field-less case
+     *  already behaved. Params are unused here but must match FormFieldBuilder's
+     *  override signature — TS checks generic-constraint satisfaction
+     *  (`T extends FieldBuilder<any>`) strictly, not with the bivariant
+     *  leniency normal overrides get, so a param-less base signature breaks
+     *  assignability everywhere. */
+    get run() {
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            canRead: (..._args) => true,
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            canCreate: (..._args) => true,
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            canUpdate: (..._args) => true
+        };
     }
     get component() {
         return null;

package/dist/core/fields/builders/form-field-builder.d.ts

@@ -1,16 +1,54 @@
 import type { FieldPanelTableConfig } from '../../../types.js';
 import type { Dic } from '../../../util/types.js';
-import type { FieldAccess, FieldHook, FieldHookClient, FieldHookShared, FieldValidationFunc, FieldWidth, FormField } from '../../../fields/types.js';
-import { FieldBuilder } from './field-builder.js';
-type GenerateSchemaFn = (args: {
-    camel: string;
-    snake: string;
-    suffix: string;
-}) => string;
-export declare class FormFieldBuilder<T extends FormField> extends FieldBuilder<T> {
-    _generateSchema: null | GenerateSchemaFn;
+import type { RequestEvent } from '@sveltejs/kit';
+import type { FieldAccess, FieldHook, FieldHookClient, FieldHookContext, FieldHookShared, FieldValidationFunc, FieldWidth, FormField } from '../../../fields/types.js';
+import { FieldBuilder, type FieldRun } from './field-builder.js';
+/** Adapter-agnostic storage primitive — column syntax only, not default-value semantics. */
+export type DataType = 'text' | 'boolean' | 'number' | 'timestamp' | 'json';
+/** Method-syntax, same reasoning as `FieldRun` — keeps `run`'s params
+ *  bivariant across concrete field types so e.g. `SlugFieldBuilder` still
+ *  satisfies a prop typed `FormFieldBuilder<FormField>`. */
+export type FormFieldRun<T extends FormField> = FieldRun & {
+    isEmpty(value: unknown): boolean;
+    validate(value: unknown, context: Parameters<FieldValidationFunc<T>>[1]): true | string;
+    condition(doc: Dic, siblings: Dic): boolean;
+    onChange(value: unknown, context: Parameters<FieldHookClient>[1]): void;
+    beforeRead(value: unknown, context: Omit<FieldHookContext<T>, 'config'>): Promise<any>;
+    beforeSave(value: unknown, context: FieldHookContext<T>): Promise<any>;
+    beforeValidate(value: unknown, context: Parameters<FieldHookShared>[1]): Promise<any>;
+    /** Resolves `field.defaultValue` — calling it if it's a `DefaultValueFn`,
+     *  returning it as-is otherwise. Every field type stores `defaultValue` as
+     *  plain data (never a fluent-setter name collision on `.field` itself),
+     *  but several concrete builders (Select, Link, Slug, Relation) *do* expose
+     *  a `.defaultValue(...)` fluent setter — bare `config.defaultValue` on
+     *  those would silently return that setter, not the stored value. */
+    defaultValue(context?: {
+        event?: RequestEvent;
+    }): unknown;
+};
+export type ReferentialAction = 'cascade' | 'set null' | 'restrict' | 'no action';
+export type FieldReferenceOptions = {
+    onDelete?: ReferentialAction;
+    onUpdate?: ReferentialAction;
+    /** Referenced table is this field's own table (self-FK); adapters need this
+     *  to emit a `(): any =>` accessor and avoid a TS circular-declaration error. */
+    selfReferencing?: boolean;
+};
+export type FieldReference = FieldReferenceOptions & {
+    table: string;
+};
+export declare class FormFieldBuilder<T extends FormField = FormField> extends FieldBuilder<T> {
+    /** Every concrete leaf field builder is expected to implement a
+     *  `get dataType(): DataType` accessor (see e.g. `$lib/fields/text/index.ts`).
+     *  Not declared here — TS doesn't allow `declare` on accessors in this
+     *  project's config, and a plain base field would conflict with subclasses
+     *  that need a computed getter (e.g. `select`, whose dataType depends on
+     *  `many`). Container builders (Group/Tabs/Blocks/Tree) never get asked,
+     *  since the adapter's tree-walker special-cases them before reaching the
+     *  generic column-rendering branch; `column.server.ts` reads `.dataType`
+     *  via a narrow cast for the same reason it already casts `unique`. */
+    _references: FieldReference | null;
     constructor(name: string, type: string);
-    get name(): string;
     label(label: string): this;
     hidden(): this;
     localized(): this;
@@ -19,17 +57,38 @@ export declare class FormFieldBuilder<T extends FormField> extends FieldBuilder<
     table(params?: FieldPanelTableConfig | number): this;
     width(value: FieldWidth): this;
     required(bool?: boolean): this;
+    /**
+     * Force the field to be on the root table — usefull for fields that
+     * should not be versioned (ex: _parent for nested structures should
+     * always be on the root table to prevent different versions from having
+     * different parents).
+     */
+    _root(): this;
+    /** `label`/`localized`/`root`/`required` are the only properties that need
+     *  anything beyond a plain `this.field` read (a fallback default, or a
+     *  boolean coercion) — everything else a concrete field type adds
+     *  (Group's `fields`, Relation's `relationTo`, Select's `options`, ...)
+     *  comes through unchanged via the spread, no per-subclass override needed. */
+    get get(): T & {
+        localized: boolean;
+        root: boolean;
+        label: string;
+        required: boolean;
+    };
     access(access: {
         create?: FieldAccess;
         read?: FieldAccess;
         update?: FieldAccess;
     }): this;
     onChange(hook: FieldHookClient): this;
+    /** Behavior the builder runs on your behalf — invoking a stored function or
+     *  hook list, not a data read (see `.get` for that). */
+    get run(): FormFieldRun<T>;
     hint(hint: string): this;
     clone(): typeof this;
-    $generateSchema(fn: GenerateSchemaFn): this;
+    /** Server-side schema concern, same family as $beforeRead/$beforeSave. */
+    $references(table: string, options?: FieldReferenceOptions): this;
     $beforeRead(hook: FieldHook<T>): this;
     $beforeSave(hook: FieldHook<T>): this;
     beforeValidate(hook: FieldHookShared): this;
 }
-export {};

package/dist/core/fields/builders/form-field-builder.js

@@ -1,7 +1,17 @@
+import { capitalize } from '../../../util/string.js';
 import cloneDeep from 'clone-deep';
 import { FieldBuilder } from './field-builder.js';
 export class FormFieldBuilder extends FieldBuilder {
-    _generateSchema = null;
+    /** Every concrete leaf field builder is expected to implement a
+     *  `get dataType(): DataType` accessor (see e.g. `$lib/fields/text/index.ts`).
+     *  Not declared here — TS doesn't allow `declare` on accessors in this
+     *  project's config, and a plain base field would conflict with subclasses
+     *  that need a computed getter (e.g. `select`, whose dataType depends on
+     *  `many`). Container builders (Group/Tabs/Blocks/Tree) never get asked,
+     *  since the adapter's tree-walker special-cases them before reaching the
+     *  generic column-rendering branch; `column.server.ts` reads `.dataType`
+     *  via a narrow cast for the same reason it already casts `unique`. */
+    _references = null;
     constructor(name, type) {
         super(type);
         this.field.name = name;
@@ -15,9 +25,6 @@ export class FormFieldBuilder extends FieldBuilder {
         };
         return this;
     }
-    get name() {
-        return this.field.name;
-    }
     label(label) {
         this.field.label = label;
         return this;
@@ -58,6 +65,30 @@ export class FormFieldBuilder extends FieldBuilder {
         this.field.required = typeof bool === 'undefined' ? true : bool;
         return this;
     }
+    /**
+     * Force the field to be on the root table — usefull for fields that
+     * should not be versioned (ex: _parent for nested structures should
+     * always be on the root table to prevent different versions from having
+     * different parents).
+     */
+    _root() {
+        this.field._root = true;
+        return this;
+    }
+    /** `label`/`localized`/`root`/`required` are the only properties that need
+     *  anything beyond a plain `this.field` read (a fallback default, or a
+     *  boolean coercion) — everything else a concrete field type adds
+     *  (Group's `fields`, Relation's `relationTo`, Select's `options`, ...)
+     *  comes through unchanged via the spread, no per-subclass override needed. */
+    get get() {
+        return {
+            ...this.field,
+            localized: !!this.field.localized,
+            root: !!this.field._root,
+            label: this.field.label || capitalize(this.field.name),
+            required: !!this.field.required
+        };
+    }
     access(access) {
         this.field.access = { ...this.field.access, ...access };
         return this;
@@ -67,6 +98,64 @@ export class FormFieldBuilder extends FieldBuilder {
         this.field.hooks.onChange.push(hook);
         return this;
     }
+    /** Behavior the builder runs on your behalf — invoking a stored function or
+     *  hook list, not a data read (see `.get` for that). */
+    get run() {
+        return {
+            isEmpty: (value) => this.field.isEmpty(value),
+            validate: (value, context) => {
+                if (this.field.validate) {
+                    return this.field.validate(value, { ...context, config: this.field });
+                }
+                return true;
+            },
+            condition: (doc, siblings) => {
+                if (this.field.condition) {
+                    try {
+                        return this.field.condition(doc, siblings);
+                    }
+                    catch (err) {
+                        console.error(err.message);
+                        return false;
+                    }
+                }
+                return true;
+            },
+            canRead: (...args) => !!this.field.access?.read?.(...args),
+            canCreate: (...args) => !!this.field.access?.create?.(...args),
+            canUpdate: (...args) => !!this.field.access?.update?.(...args),
+            onChange: (value, context) => {
+                for (const hook of this.field.hooks?.onChange ?? []) {
+                    hook(value, context);
+                }
+            },
+            beforeRead: async (value, context) => {
+                let result = value;
+                for (const hook of this.field.hooks?.beforeRead ?? []) {
+                    result = await hook(result, { ...context, config: this.field });
+                }
+                return result;
+            },
+            beforeSave: async (value, context) => {
+                let result = value;
+                for (const hook of this.field.hooks?.beforeSave ?? []) {
+                    result = await hook(result, { ...context, config: this.field });
+                }
+                return result;
+            },
+            beforeValidate: async (value, context) => {
+                let result = value;
+                for (const hook of this.field.hooks?.beforeValidate ?? []) {
+                    result = await hook(result, { ...context, config: this.field });
+                }
+                return result;
+            },
+            defaultValue: (context = {}) => {
+                const value = this.field.defaultValue;
+                return typeof value === 'function' ? value(context) : value;
+            }
+        };
+    }
     hint(hint) {
         this.field.hint = hint;
         return this;
@@ -83,8 +172,9 @@ export class FormFieldBuilder extends FieldBuilder {
         clone.field = cloneDeep(this.field);
         return clone;
     }
-    $generateSchema(fn) {
-        this._generateSchema = fn;
+    /** Server-side schema concern, same family as $beforeRead/$beforeSave. */
+    $references(table, options) {
+        this._references = { table, ...options };
         return this;
     }
     $beforeRead(hook) {