@valbuild/core 0.105.1 → 0.109.0

package/dist/declarations/src/index.d.ts

@@ -23,7 +23,7 @@ export type { ValidationFix } from "./schema/validation/ValidationFix.js";
 export { VAL_EXTENSION, type SourceArray } from "./source/index.js";
 export { derefPatch } from "./patch/deref.js";
 export { type SelectorSource, type SelectorOf, GenericSelector, } from "./selector/index.js";
-import { getSource, splitModulePath, splitModuleFilePath, resolvePath, safeResolvePath, splitModuleFilePathAndModulePath, joinModuleFilePathAndModulePath, parentOfSourcePath, patchPathToModulePath, splitJoinedSourcePaths, type ValModule } from "./module.js";
+import { getSource, isValModule, splitModulePath, splitModuleFilePath, resolvePath, safeResolvePath, splitModuleFilePathAndModulePath, joinModuleFilePathAndModulePath, parentOfSourcePath, patchPathToModulePath, splitJoinedSourcePaths, type ValModule } from "./module.js";
 declare const ModuleFilePathSep = "?p=";
 export { ModuleFilePathSep };
 import { SelectorSource, getSchema } from "./selector/index.js";
@@ -59,8 +59,8 @@ export { type SerializedRichTextSchema, RichTextSchema, } from "./schema/richtex
 export { type SerializedUnionSchema, UnionSchema, type SerializedStringUnionSchema, type SerializedObjectUnionSchema, } from "./schema/union.js";
 export { type SerializedLiteralSchema, LiteralSchema } from "./schema/literal.js";
 export { deserializeSchema } from "./schema/deserialize.js";
-export { type PreviewItem, type RecordPreview, type ArrayPreview, type ReifiedPreview, type PreviewScope, previewScope, } from "./preview.js";
-export { type CodeLanguage, type StringRender, CODE_LANGUAGES } from "./render.js";
+export { type PreviewItem, type ItemPreviewInput, type RecordPreview, type ArrayPreview, type ReifiedPreview, type PreviewScope, previewScope, } from "./preview.js";
+export { type CodeLanguage, type StringRender, type InlineRender, type FieldRender, CODE_LANGUAGES, } from "./render.js";
 export type { ValRouter, RouteValidationError } from "./router.js";
 export { getSourcePathFromRoute } from "./getSourcePathFromRoute.js";
 export declare const FATAL_ERROR_TYPES: readonly ["no-schema", "no-source", "invalid-id", "no-module", "invalid-patch"];
@@ -80,6 +80,7 @@ declare const Internal: {
     getSchema: typeof getSchema;
     getValPath: typeof getValPath;
     getSource: typeof getSource;
+    isValModule: typeof isValModule;
     resolvePath: typeof resolvePath;
     safeResolvePath: typeof safeResolvePath;
     splitModuleFilePathAndModulePath: typeof splitModuleFilePathAndModulePath;
@@ -101,7 +102,7 @@ declare const Internal: {
         hashToRemoteFileHash: typeof hashToRemoteFileHash;
         splitRemoteRef: typeof splitRemoteRef;
     };
-    validate: (val: ValModule<SelectorSource>, path: SourcePath, src: unknown) => import("./schema/validation/ValidationError.js").ValidationErrors | undefined;
+    validate: (val: ValModule<SelectorSource>, path: SourcePath, src: unknown) => import("./index.js").ValidationErrors | undefined;
     isVal: typeof isVal;
     isJson: typeof isJson;
     getJsonImport: typeof getJsonImport;

package/dist/declarations/src/initSchema.d.ts

@@ -283,9 +283,9 @@ export type InitSchema = {
     readonly files: typeof files;
 };
 export declare function initSchema(): {
-    string: <T extends string>(options?: Record<string, never>) => import("./schema/string.js").StringSchema<T>;
-    boolean: () => import("./schema/boolean.js").BooleanSchema<boolean>;
-    array: <S extends import("./schema/index.js").Schema<import("./selector/index.js").SelectorSource>>(schema: S) => import("./schema/array.js").ArraySchema<S, import("./schema/index.js").SelectorOfSchema<S>[]>;
+    string: <T extends string>(options?: Record<string, never>) => import("./index.js").StringSchema<T>;
+    boolean: () => import("./index.js").BooleanSchema<boolean>;
+    array: <S extends import("./schema/index.js").Schema<import("./selector/index.js").SelectorSource>>(schema: S) => import("./index.js").ArraySchema<S, import("./schema/index.js").SelectorOfSchema<S>[]>;
     object: <Props extends {
         [key: string]: import("./schema/index.js").Schema<import("./selector/index.js").SelectorSource>;
     } & {
@@ -297,33 +297,33 @@ export declare function initSchema(): {
         assert?: never;
         fold?: never;
         patch_id?: never;
-    }>(schema: Props) => import("./schema/object.js").ObjectSchema<Props, { [key in keyof Props]: import("./schema/index.js").SelectorOfSchema<Props[key]>; }>;
+    }>(schema: Props) => import("./index.js").ObjectSchema<Props, { [key in keyof Props]: import("./schema/index.js").SelectorOfSchema<Props[key]>; }>;
     number: (options?: {
         max?: number;
         min?: number;
-    }) => import("./schema/number.js").NumberSchema<number>;
-    union: <Key extends string | import("./schema/index.js").Schema<string>, T extends import("./schema/index.js").Schema<Key extends string ? import("./source/index.js").SourceObject & { [k in Key]: string; } : Key extends import("./schema/index.js").Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => import("./schema/union.js").UnionSchema<Key, T, T extends import("./schema/index.js").Schema<infer S extends import("./selector/index.js").SelectorSource>[] ? S extends import("./selector/index.js").SelectorSource ? S | (Key extends import("./schema/index.js").Schema<infer K extends import("./selector/index.js").SelectorSource> ? K : never) : never : never>;
-    richtext: <O extends import("./index.js").RichTextOptions>(options?: O) => import("./schema/richtext.js").RichTextSchema<O, import("./index.js").RichTextSource<O>>;
+    }) => import("./index.js").NumberSchema<number>;
+    union: <Key extends string | import("./schema/index.js").Schema<string>, T extends import("./schema/index.js").Schema<Key extends string ? import("./source/index.js").SourceObject & { [k in Key]: string; } : Key extends import("./schema/index.js").Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => import("./index.js").UnionSchema<Key, T, T extends import("./schema/index.js").Schema<infer S extends import("./selector/index.js").SelectorSource>[] ? S extends import("./selector/index.js").SelectorSource ? S | (Key extends import("./schema/index.js").Schema<infer K extends import("./selector/index.js").SelectorSource> ? K : never) : never : never>;
+    richtext: <O extends import("./index.js").RichTextOptions>(options?: O) => import("./index.js").RichTextSchema<O, import("./index.js").RichTextSource<O>>;
     image: typeof image;
-    literal: <T extends string>(value: T) => import("./schema/literal.js").LiteralSchema<T>;
-    keyOf: <Src extends import("./selector/index.js").GenericSelector<import("./source/index.js").SourceObject> & import("./module.js").ValModuleBrand>(valModule: Src) => import("./schema/keyOf.js").KeyOfSchema<Src, Src extends import("./selector/index.js").GenericSelector<infer S extends import("./source/index.js").Source, undefined> ? S extends readonly import("./source/index.js").Source[] ? number : S extends import("./source/index.js").SourceObject ? string extends keyof S ? import("./schema/string.js").RawString : keyof S : S extends Record<string, import("./source/index.js").Source> ? import("./schema/string.js").RawString : never : never>;
+    literal: <T extends string>(value: T) => import("./index.js").LiteralSchema<T>;
+    keyOf: <Src extends import("./selector/index.js").GenericSelector<import("./source/index.js").SourceObject> & import("./module.js").ValModuleBrand>(valModule: Src) => import("./index.js").KeyOfSchema<Src, Src extends import("./selector/index.js").GenericSelector<infer S extends import("./source/index.js").Source, undefined> ? S extends readonly import("./source/index.js").Source[] ? number : S extends import("./source/index.js").SourceObject ? string extends keyof S ? import("./index.js").RawString : keyof S : S extends Record<string, import("./source/index.js").Source> ? import("./index.js").RawString : never : never>;
     record: typeof record;
     file: typeof file;
-    files: (options: import("./schema/files.js").FilesOptions) => import("./schema/record.js").RecordSchema<import("./schema/object.js").ObjectSchema<{
-        mimeType: import("./schema/string.js").StringSchema<string>;
+    files: (options: import("./schema/files.js").FilesOptions) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{
+        mimeType: import("./index.js").StringSchema<string>;
     }, {
         mimeType: string;
     }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/files.js").FilesEntryMetadata>>;
-    date: (options?: Record<string, never>) => import("./schema/date.js").DateSchema<import("./schema/string.js").RawString>;
-    datetime: (options?: Record<string, never>) => import("./schema/datetime.js").DateTimeSchema<import("./schema/string.js").RawString>;
-    color: (options?: import("./schema/color.js").ColorOptions) => import("./schema/color.js").ColorSchema<import("./schema/string.js").RawString>;
-    route: <T extends string>(options?: Record<string, never>) => import("./schema/route.js").RouteSchema<T>;
+    date: (options?: Record<string, never>) => import("./index.js").DateSchema<import("./index.js").RawString>;
+    datetime: (options?: Record<string, never>) => import("./index.js").DateTimeSchema<import("./index.js").RawString>;
+    color: (options?: import("./index.js").ColorOptions) => import("./index.js").ColorSchema<import("./index.js").RawString>;
+    route: <T extends string>(options?: Record<string, never>) => import("./index.js").RouteSchema<T>;
     router: typeof router;
-    images: <Accept extends `image/${string}`>(options: import("./schema/images.js").ImagesOptions<Accept>) => import("./schema/record.js").RecordSchema<import("./schema/object.js").ObjectSchema<{
-        width: import("./schema/number.js").NumberSchema<number>;
-        height: import("./schema/number.js").NumberSchema<number>;
-        mimeType: import("./schema/string.js").StringSchema<string>;
-        alt: import("./schema/string.js").StringSchema<string | null>;
+    images: <Accept extends `image/${string}`>(options: import("./schema/images.js").ImagesOptions<Accept>) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{
+        width: import("./index.js").NumberSchema<number>;
+        height: import("./index.js").NumberSchema<number>;
+        mimeType: import("./index.js").StringSchema<string>;
+        alt: import("./index.js").StringSchema<string | null>;
     }, {
         width: number;
         height: number;

package/dist/declarations/src/module.d.ts

@@ -18,6 +18,16 @@ export type ReplaceRawStringWithString<T extends SelectorSource> = SelectorSourc
 export declare function define<T extends Schema<SelectorSource>>(id: string, // TODO: `/${string}`
 schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>>;
 export declare function getSource<T extends Source>(valModule: ValModule<T>): T;
+/**
+ * Whether `value` is a Val module, i.e. something {@link define} produced.
+ *
+ * Checks for the three symbols `define` writes, rather than a class identity:
+ * a module may have been created by a different copy of `@valbuild/core` (the
+ * editor SPA and the host bundle each ship their own, and the CLI evaluates
+ * user modules inside a `node:vm` context). The symbols are created with
+ * `Symbol.for`, so they are shared across all of those; a constructor is not.
+ */
+export declare function isValModule(value: unknown): value is ValModule<SelectorSource>;
 export declare function splitModuleFilePathAndModulePath(path: SourcePath | ModuleFilePath): [moduleId: ModuleFilePath, path: ModulePath];
 export declare function joinModuleFilePathAndModulePath(moduleFilePath: ModuleFilePath, modulePath: ModulePath): SourcePath;
 export declare function getSourceAtPath(modulePath: ModulePath, valModule: ValModule<SelectorSource> | Source): any;

package/dist/declarations/src/preview.d.ts

@@ -3,8 +3,29 @@ import { SelectorSource } from "./selector/index.js";
 import { ImageSource } from "./source/media.js";
 import { ModuleFilePath, SourcePath } from "./val/index.js";
 /**
- * What a container shows for ONE of its items: the user's `preview` callback
- * returns this, and the Studio draws a row from it.
+ * A PREVIEW is how a VALUE is shown wherever a preview of it is needed — a row
+ * in a sortable list, a key in a reference dropdown, a search hit, a
+ * reference — which is everywhere the value is NAVIGABLE to rather than open.
+ * It is never how the field itself is edited: that is a RENDER (`render.ts`),
+ * which applies only when you are looking at the field. The two do not
+ * intersect — a schema can carry both, and each is read in its own places.
+ *
+ * A preview is declared on the schema of the VALUE being previewed:
+ *
+ * ```ts
+ * const author = s.object({ name: s.string() })
+ *   .preview(({ val }) => ({ title: val.name }));
+ * const authors = s.array(author);
+ * ```
+ *
+ * The container reifies its rows by running each ITEM's preview closure — see
+ * {@link ArrayPreview} / {@link RecordPreview}. (Previews used to be declared
+ * on the container instead; a `.preview` on an array/record now previews the
+ * array/record itself as a value, for when IT is the item of something.)
+ */
+/**
+ * What a preview shows for one value: the user's `preview` callback returns
+ * this, and the Studio draws a row from it.
  *
  * NB: {@link ArrayPreview} / {@link RecordPreview} name the DATA a container
  * previews with. The Studio also has React components called `ArrayPreview` /
@@ -18,6 +39,23 @@ export type PreviewItem = {
     subtitle?: string | null;
     image?: ImageSource | null;
 };
+/**
+ * What `.preview(...)` takes, on every schema: the value's own source in, a
+ * {@link PreviewItem} out. `NonNullable` because a container skips null items
+ * rather than previewing them.
+ *
+ * Declared through method syntax deliberately (the same bivariance shape
+ * React's event handler types use): `nullable()` copies a schema's closure
+ * into the `Src | null` variant of the same class, and with a plain function
+ * type the checker cannot see that `NonNullable<Src | null>` IS
+ * `NonNullable<Src>` while `Src` is still a type parameter — every schema's
+ * `nullable()` would need a cast instead.
+ */
+export type ItemPreviewInput<Src> = {
+    bivarianceHack(input: {
+        val: NonNullable<Src>;
+    }): PreviewItem;
+}["bivarianceHack"];
 export type RecordPreview = {
     parent: "record";
     items: [key: string, value: PreviewItem][];

package/dist/declarations/src/render.d.ts

@@ -1,9 +1,19 @@
 /**
- * A RENDER is how one field is laid out in the editor: `s.string().render({ as:
- * "textarea" })`, `.render({ as: "code", language })`.
+ * A RENDER is how the FIELD ITSELF is laid out in the editor, and it applies
+ * only when you are looking at the field: `s.string().render({ as: "textarea"
+ * })`, `.render({ as: "code", language })`, `.render({ as: "inline" })` on an
+ * array/record item.
  *
- * It is static configuration - plain data, with no closure behind it and no
- * dependency on source - which is why it lives in the SERIALIZED schema
+ * A PREVIEW (`preview.ts`) is the other thing: how the VALUE is shown wherever
+ * a preview of it is needed — a list row, a reference dropdown, a search hit —
+ * that is, wherever the value is navigable to rather than open. The two never
+ * intersect: a schema can carry both, a `render` is read where the field is
+ * edited and a `preview` where the value is previewed. A second `.render(...)`
+ * on the same schema REPLACES the first (last one wins), exactly like a second
+ * `.preview(...)` replaces the first — they do not merge.
+ *
+ * A render is static configuration - plain data, with no closure behind it and
+ * no dependency on source - which is why it lives in the SERIALIZED schema
  * (`SerializedStringSchema.render`) and is read straight off it where the field
  * is drawn. There is no render pipeline, no store and no host round-trip.
  *
@@ -13,9 +23,6 @@
  * the shape it needs back is `executePreview`'s, and the honest move is to give
  * `render` its own execute/store pair again. It is NOT to re-merge the two:
  * conflating them is what this file was split up to undo.
- *
- * The dynamic, source-dependent, demand-scoped thing - what a container shows
- * for its items - is a PREVIEW. See `preview.ts`.
  */
 /**
  * The list is the declaration and {@link CodeLanguage} is derived from it, so
@@ -24,13 +31,35 @@
  */
 export declare const CODE_LANGUAGES: readonly ["typescript", "javascript", "javascriptreact", "typescriptreact", "json", "java", "html", "css", "xml", "markdown", "sql", "python", "rust", "php", "go", "cpp", "sass", "vue", "angular"];
 export type CodeLanguage = (typeof CODE_LANGUAGES)[number];
+/**
+ * `{ as: "inline" }` on a field that is the ITEM of an array or record: the
+ * container renders the field itself inside each (sortable) row, instead of a
+ * clickable preview row that navigates to it. This is what a page-builder list
+ * is made of: `s.array(s.object({...}).render({ as: "inline" }))`.
+ *
+ * On a field that is not directly under an array or record it is inert — an
+ * object's fields are already laid out in place.
+ *
+ * Like every render it is static configuration (see the top of this file): it
+ * travels whole in the serialized schema and the editor reads it straight off
+ * the item schema it already has.
+ */
+export type InlineRender = {
+    as: "inline";
+};
+/**
+ * What `.render(...)` takes on every field except `s.string()`, and what the
+ * serialized schema carries verbatim.
+ */
+export type FieldRender = InlineRender;
 /**
  * What `s.string().render(...)` takes, and what the serialized schema carries
- * verbatim.
+ * verbatim. A string has editor layouts of its own (textarea, code) in
+ * addition to the container-facing `inline`.
  */
 export type StringRender = {
     as: "textarea";
 } | {
     as: "code";
     language: CodeLanguage;
-};
+} | InlineRender;

package/dist/declarations/src/schema/array.d.ts

@@ -1,14 +1,20 @@
 import { Schema, SchemaAssertResult, SelectorOfSchema, SerializedSchema } from "./index.js";
-import { PreviewItem, PreviewSelector, ReifiedPreview, PreviewScope } from "../preview.js";
+import { ItemPreviewInput, PreviewItem, ReifiedPreview, PreviewScope } from "../preview.js";
+import { FieldRender } from "../render.js";
 import { SelectorSource } from "../selector/index.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedArraySchema = {
     type: "array";
+    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
+    render?: FieldRender;
     item: SerializedSchema;
     opt: boolean;
     /**
-     * Set when this schema declares a `preview`.
+     * Set when this schema declares a `preview` — of the ARRAY ITSELF as a
+     * value, for when it is the item of another container. Whether this array's
+     * ROWS preview is carried by the ITEM's serialized schema, where the closure
+     * is declared.
      *
      * The preview itself cannot be serialized — it is a user closure — but whether
      * one EXISTS can be, and that is worth carrying: it lets the non-host side
@@ -22,9 +28,6 @@ export type SerializedArraySchema = {
     hidden?: boolean;
     description?: string;
 };
-type ArrayPreviewInput<T extends Schema<SelectorSource>> = (input: {
-    val: PreviewSelector<T>;
-}) => PreviewItem;
 export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends SelectorOfSchema<T>[] | null> extends Schema<Src> {
     private readonly item;
     private readonly opt;
@@ -33,7 +36,8 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     private readonly isHidden;
     private readonly description?;
     private readonly previewInput;
-    constructor(item: T, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ArrayPreviewInput<T> | null);
+    private readonly renderInput;
+    constructor(item: T, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null, renderInput?: FieldRender | null);
     describe(description: string | null): ArraySchema<T, Src>;
     validate(validationFunction: (src: Src) => false | string): ArraySchema<T, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -44,14 +48,22 @@ export declare class ArraySchema<T extends Schema<SelectorSource>, Src extends S
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedArraySchema;
     protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     /**
-     * What the editor shows for each ITEM of this array: a title, and optionally a
-     * subtitle and an image.
+     * How this ARRAY ITSELF is shown where a preview of it is needed — when it
+     * is the item of another container, in search, in references. What its rows
+     * show is the ITEM schema's `preview`, not this. Never how the field is
+     * edited (that is `render`). See `preview.ts`.
+     */
+    preview(select: ItemPreviewInput<Src>): ArraySchema<T, Src>;
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
      *
-     * `select` is your own code over the item's source, so it is run on demand for
-     * the rows that are actually being looked at — see `PreviewScope`.
+     * Static configuration, not a callback — see `render.ts`.
      */
-    preview(select: ArrayPreviewInput<T>): ArraySchema<T, Src>;
+    render(input: FieldRender): ArraySchema<T, Src>;
 }
 export declare const array: <S extends Schema<SelectorSource>>(schema: S) => ArraySchema<S, SelectorOfSchema<S>[]>;
-export {};

package/dist/declarations/src/schema/boolean.d.ts

@@ -1,9 +1,14 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 export type SerializedBooleanSchema = {
     type: "boolean";
+    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
+    render?: FieldRender;
+    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
+    preview?: true;
     opt: boolean;
     customValidate?: boolean;
     readonly?: boolean;
@@ -16,7 +21,9 @@ export declare class BooleanSchema<Src extends boolean | null> extends Schema<Sr
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): BooleanSchema<Src>;
     validate(validationFunction: (src: Src) => false | string): BooleanSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -25,6 +32,22 @@ export declare class BooleanSchema<Src extends boolean | null> extends Schema<Sr
     readonly(): BooleanSchema<Src>;
     hidden(): BooleanSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     */
+    render(input: FieldRender): BooleanSchema<Src>;
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     */
+    preview(select: ItemPreviewInput<Src>): BooleanSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }

package/dist/declarations/src/schema/color.d.ts

@@ -1,5 +1,6 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ColorFormat } from "./colorFormat.js";
 import { RawString } from "./string.js";
@@ -28,6 +29,10 @@ export type ColorOptions = {
 };
 export type SerializedColorSchema = {
     type: "color";
+    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
+    render?: FieldRender;
+    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
+    preview?: true;
     options?: ColorOptions;
     opt: boolean;
     customValidate?: boolean;
@@ -42,7 +47,9 @@ export declare class ColorSchema<Src extends string | null> extends Schema<Src>
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options?: ColorOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(options?: ColorOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): ColorSchema<Src>;
     validate(validationFunction: (src: Src) => false | string): ColorSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
@@ -51,6 +58,22 @@ export declare class ColorSchema<Src extends string | null> extends Schema<Src>
     nullable(): ColorSchema<Src | null>;
     readonly(): ColorSchema<Src>;
     hidden(): ColorSchema<Src>;
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     */
+    render(input: FieldRender): ColorSchema<Src>;
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     */
+    preview(select: ItemPreviewInput<Src>): ColorSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }

package/dist/declarations/src/schema/date.d.ts

@@ -1,5 +1,6 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { RawString } from "./string.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -21,6 +22,10 @@ type DateOptions = {
 };
 export type SerializedDateSchema = {
     type: "date";
+    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
+    render?: FieldRender;
+    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
+    preview?: true;
     options?: DateOptions;
     opt: boolean;
     customValidate?: boolean;
@@ -35,7 +40,9 @@ export declare class DateSchema<Src extends string | null> extends Schema<Src> {
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options?: DateOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(options?: DateOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): DateSchema<Src>;
     validate(validationFunction: (src: Src) => false | string): DateSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -46,6 +53,22 @@ export declare class DateSchema<Src extends string | null> extends Schema<Src> {
     readonly(): DateSchema<Src>;
     hidden(): DateSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     */
+    render(input: FieldRender): DateSchema<Src>;
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     */
+    preview(select: ItemPreviewInput<Src>): DateSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }

package/dist/declarations/src/schema/datetime.d.ts

@@ -1,5 +1,6 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { RawString } from "./string.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -25,6 +26,10 @@ type DateTimeOptions = {
 };
 export type SerializedDateTimeSchema = {
     type: "dateTime";
+    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
+    render?: FieldRender;
+    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
+    preview?: true;
     options?: DateTimeOptions;
     opt: boolean;
     customValidate?: boolean;
@@ -39,7 +44,9 @@ export declare class DateTimeSchema<Src extends string | null> extends Schema<Sr
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options?: DateTimeOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(options?: DateTimeOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): DateTimeSchema<Src>;
     validate(validationFunction: (src: Src) => false | string): DateTimeSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -50,6 +57,22 @@ export declare class DateTimeSchema<Src extends string | null> extends Schema<Sr
     readonly(): DateTimeSchema<Src>;
     hidden(): DateTimeSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     */
+    render(input: FieldRender): DateTimeSchema<Src>;
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     */
+    preview(select: ItemPreviewInput<Src>): DateTimeSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }

package/dist/declarations/src/schema/file.d.ts

@@ -4,13 +4,18 @@ import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema }
 import { ModulePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { ValModule } from "../index.js";
-import { ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
 import { FilesEntryMetadata } from "./files.js";
 export type FileOptions = {
     accept?: string;
 };
 export type SerializedFileSchema = {
     type: "file";
+    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
+    render?: FieldRender;
+    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
+    preview?: true;
     options?: FileOptions;
     remote?: boolean;
     opt: boolean;
@@ -29,7 +34,9 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options?: FileOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, FilesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(options?: FileOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, FilesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): FileSchema<Src>;
     remote(): FileSchema<Src>;
     validate(validationFunction: CustomValidateFunction<Src>): FileSchema<Src>;
@@ -44,6 +51,22 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     readonly(): FileSchema<Src>;
     hidden(): FileSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     */
+    render(input: FieldRender): FileSchema<Src>;
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     */
+    preview(select: ItemPreviewInput<Src>): FileSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }