@valbuild/core 0.106.0 → 0.109.0

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

@@ -19,7 +19,7 @@ import { SerializedRouteSchema } from "./route.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { FileSource } from "../source/media.js";
 import { GenericRichTextSourceNode, RichTextSource } from "../source/richtext.js";
-import { ReifiedPreview, PreviewScope } from "../preview.js";
+import { ReifiedPreview, PreviewScope, PreviewItem } from "../preview.js";
 export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedRouteSchema | SerializedImageSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
@@ -114,6 +114,24 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * its items are — which is the single-visible-row case.
      */
     protected abstract executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    /**
+     * This value AS A PREVIEW — what a container's row, a reference dropdown or
+     * a search hit shows for it. Runs the schema's own `preview` closure;
+     * `null` when none is declared (the consumer falls back to a generic
+     * preview). A union dispatches to the matching member's closure.
+     *
+     * Containers call this on their ITEM schema per item — that is how
+     * `executePreview` reifies an {@link ArrayPreview} / {@link RecordPreview}
+     * from item-level declarations.
+     */
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    /**
+     * Could {@link executePreviewItem} ever answer? A container reifies a rows
+     * preview only when its item schema says yes — asked here rather than by
+     * running the closure, so an EMPTY list still previews as an empty list
+     * instead of not at all.
+     */
+    protected declaresItemPreview(): boolean;
     /** MUTATES! since internal and perf sensitive */
     protected appendValidationError(current: ValidationErrors, path: SourcePath, message: string, value: unknown, schemaError?: boolean): ValidationErrors;
     /**

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

@@ -5,9 +5,14 @@ import { Source, SourceObject } from "../source/index.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { RawString } from "./string.js";
-import { ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
 export type SerializedKeyOfSchema = {
     type: "keyOf";
+    /** 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;
     path: SourcePath;
     schema?: SerializedRefSchema | undefined;
     opt: boolean;
@@ -34,7 +39,9 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(schema?: SerializedRefSchema | undefined, sourcePath?: SourcePath | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(schema?: SerializedRefSchema | undefined, sourcePath?: SourcePath | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): KeyOfSchema<Sel, Src>;
     validate(validationFunction: (src: Src) => false | string): KeyOfSchema<Sel, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -43,6 +50,22 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     readonly(): KeyOfSchema<Sel, Src>;
     hidden(): KeyOfSchema<Sel, 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): KeyOfSchema<Sel, 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>): KeyOfSchema<Sel, Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }

package/dist/declarations/src/schema/literal.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 SerializedLiteralSchema = {
     type: "literal";
+    /** 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;
     value: string;
     opt: boolean;
     customValidate?: boolean;
@@ -18,7 +23,9 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(value: string, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(value: string, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): LiteralSchema<Src>;
     validate(validationFunction: (src: Src) => false | string): LiteralSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -27,6 +34,22 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     readonly(): LiteralSchema<Src>;
     hidden(): LiteralSchema<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): LiteralSchema<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>): LiteralSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }

package/dist/declarations/src/schema/number.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 { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type NumberOptions = {
@@ -8,6 +9,10 @@ type NumberOptions = {
 };
 export type SerializedNumberSchema = {
     type: "number";
+    /** 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?: NumberOptions;
     opt: boolean;
     customValidate?: boolean;
@@ -22,7 +27,9 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options?: NumberOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(options?: NumberOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): NumberSchema<Src>;
     validate(validationFunction: (src: Src) => false | string): NumberSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -33,6 +40,22 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     max(max: number): NumberSchema<Src>;
     min(min: number): NumberSchema<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): NumberSchema<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>): NumberSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }

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

@@ -1,10 +1,15 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SelectorOfSchema, SerializedSchema } from "./index.js";
-import { 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 SerializedObjectSchema = {
     type: "object";
+    /** 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;
     items: Record<string, SerializedSchema>;
     opt: boolean;
     customValidate?: boolean;
@@ -42,7 +47,9 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(items: Props, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(items: Props, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): ObjectSchema<Props, Src>;
     validate(validationFunction: (src: Src) => false | string): ObjectSchema<Props, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -51,6 +58,22 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     readonly(): ObjectSchema<Props, Src>;
     hidden(): ObjectSchema<Props, 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): ObjectSchema<Props, 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>): ObjectSchema<Props, Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
 }

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

@@ -1,5 +1,6 @@
 import { CustomValidateFunction, 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 { ValRouter } from "../router.js";
 import { SelectorSource } from "../selector/index.js";
 import { JsonOf, JsonSource } from "../source/json.js";
@@ -17,8 +18,14 @@ export type SerializedRecordSchema = {
     item: SerializedSchema;
     key?: SerializedSchema;
     opt: boolean;
-    /** Set when this schema declares a `preview`. See `SerializedArraySchema`. */
+    /**
+     * Set when this schema declares a `preview` — of the RECORD ITSELF as a
+     * value. Whether its ENTRIES preview is carried by the item's serialized
+     * schema. See `SerializedArraySchema`.
+     */
     preview?: true;
+    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
+    render?: FieldRender;
     router?: string;
     customValidate?: boolean;
     mediaType?: "files" | "images";
@@ -45,10 +52,6 @@ export type SerializedRecordSchema = {
  * authoring.
  */
 export type JsonValuesRecordSrc<T extends Schema<SelectorSource>, K extends Schema<string>> = Record<SelectorOfSchema<K>, JsonSource<JsonOf<SelectorOfSchema<T>>> | SelectorOfSchema<T>>;
-type RecordPreviewInput<T extends Schema<SelectorSource>> = (input: {
-    key: string;
-    val: PreviewSelector<T>;
-}) => PreviewItem;
 export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Schema<string>, Src extends Record<SelectorOfSchema<K>, SelectorOfSchema<T>> | JsonValuesRecordSrc<T, K> | null> extends Schema<Src> {
     private readonly item;
     private readonly opt;
@@ -62,9 +65,10 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
     /** When true, entry values are lazily loaded {@link JsonSource} thunks. */
     private readonly isJsonValues;
     private readonly previewInput;
+    private readonly renderInput;
     constructor(item: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], currentRouter?: ValRouter | null, keySchema?: Schema<string> | null, mediaOptions?: MediaOptions | undefined, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, 
     /** When true, entry values are lazily loaded {@link JsonSource} thunks. */
-    isJsonValues?: boolean, previewInput?: RecordPreviewInput<T> | null);
+    isJsonValues?: boolean, previewInput?: ItemPreviewInput<Src> | null, renderInput?: FieldRender | null);
     describe(description: string | null): RecordSchema<T, K, Src>;
     validate(validationFunction: (src: Src) => false | string): RecordSchema<T, K, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -106,15 +110,23 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
      */
     validateJsonEntryContent(path: SourcePath, content: SelectorSource): ValidationErrors;
     protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
+    /**
+     * How this RECORD ITSELF is shown where a preview of it is needed — when it
+     * is the item of another container, in search, in references. What its
+     * entries 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>): RecordSchema<T, K, Src>;
     /**
-     * What the editor shows for each ENTRY of this record: a title, and optionally
-     * a subtitle and an image.
+     * 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 entry's key and source, so it is run on
-     * demand for the entries that are actually being looked at — see
-     * `PreviewScope`.
+     * Static configuration, not a callback — see `render.ts`.
      */
-    preview(select: RecordPreviewInput<T>): RecordSchema<T, K, Src>;
+    render(input: FieldRender): RecordSchema<T, K, Src>;
 }
 export declare function record<K extends Schema<string>, S extends Schema<SelectorSource>>(key: K, schema: S): RecordSchema<S, K, Record<SelectorOfSchema<K>, SelectorOfSchema<S>>>;
 export declare function record<S extends Schema<SelectorSource>>(schema: S): RecordSchema<S, Schema<string>, Record<string, SelectorOfSchema<S>>>;

package/dist/declarations/src/schema/richtext.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 { RichTextSource, RichTextOptions, SerializedRichTextOptions } from "../source/richtext.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -9,6 +10,10 @@ type ValidationOptions = {
 };
 export type SerializedRichTextSchema = {
     type: "richtext";
+    /** 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;
     options?: SerializedRichTextOptions & ValidationOptions;
     customValidate?: boolean;
@@ -23,7 +28,9 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options: O & ValidationOptions, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(options: O & ValidationOptions, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): RichTextSchema<O, Src>;
     maxLength(max: number): RichTextSchema<O, Src>;
     minLength(min: number): RichTextSchema<O, Src>;
@@ -36,6 +43,22 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     readonly(): RichTextSchema<O, Src>;
     hidden(): RichTextSchema<O, 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): RichTextSchema<O, 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>): RichTextSchema<O, Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }

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

@@ -1,6 +1,7 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { SourcePath } from "../val/index.js";
-import { ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type RouteOptions = {
     include?: RegExp;
@@ -8,6 +9,10 @@ type RouteOptions = {
 };
 export type SerializedRouteSchema = {
     type: "route";
+    /** 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?: {
         include?: {
             source: string;
@@ -32,7 +37,9 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options?: RouteOptions | undefined, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(options?: RouteOptions | undefined, opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): RouteSchema<Src>;
     /**
      * Specify a pattern for which routes are allowed.
@@ -67,6 +74,22 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     readonly(): RouteSchema<Src>;
     hidden(): RouteSchema<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): RouteSchema<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>): RouteSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }

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

@@ -1,5 +1,5 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ReifiedPreview } from "../preview.js";
+import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
 import { StringRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
@@ -21,6 +21,8 @@ export type SerializedStringSchema = {
      * buys, and what to do if a render ever needs to stop being static.
      */
     render?: StringRender;
+    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
+    preview?: true;
     options?: {
         maxLength?: number;
         minLength?: number;
@@ -51,7 +53,8 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options?: StringOptions | undefined, opt?: boolean, isRaw?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], renderInput?: StringRender | null, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly previewInput;
+    constructor(options?: StringOptions | undefined, opt?: boolean, isRaw?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], renderInput?: StringRender | null, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): StringSchema<Src>;
     /**
      * @deprecated Use `minLength` instead
@@ -81,6 +84,14 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
      * shows for its items is a `preview`, which is a different thing entirely.
      */
     render(input: StringRender): StringSchema<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>): StringSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     /**
      * Nothing: a string has no items, so there is nothing to preview. Its layout
      * is a `render`, which travels in the serialized schema instead of through

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

@@ -1,5 +1,6 @@
 import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { 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 { SourceObject } from "../source/index.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
@@ -9,6 +10,10 @@ import { ValidationError, ValidationErrors } from "./validation/ValidationError.
 export type SerializedUnionSchema = SerializedStringUnionSchema | SerializedObjectUnionSchema;
 export type SerializedStringUnionSchema = {
     type: "union";
+    /** 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;
     key: SerializedLiteralSchema;
     items: SerializedLiteralSchema[];
     opt: boolean;
@@ -19,6 +24,10 @@ export type SerializedStringUnionSchema = {
 };
 export type SerializedObjectUnionSchema = {
     type: "union";
+    /** 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;
     key: string;
     items: SerializedObjectSchema[];
     opt: boolean;
@@ -40,6 +49,8 @@ export declare class UnionSchema<Key extends string | Schema<string>, T extends
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
+    private readonly renderInput;
+    private readonly previewInput;
     describe(description: string | null): UnionSchema<Key, T, Src>;
     validate(validationFunction: (src: Src) => false | string): UnionSchema<Key, T, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -55,8 +66,27 @@ export declare class UnionSchema<Key extends string | Schema<string>, T extends
      * already reports.
      */
     private matchedVariant;
+    /**
+     * 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): UnionSchema<Key, T, 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`.
+     *
+     * Without one of its own, a tagged union previews as the VARIANT the value
+     * takes — declare `preview` on the member objects and the union dispatches.
+     */
+    preview(select: ItemPreviewInput<Src>): UnionSchema<Key, T, Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
-    constructor(key: Key, items: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    constructor(key: Key, items: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
 }
 export declare const union: <Key extends string | Schema<string>, T extends Schema<Key extends string ? SourceObject & { [k in Key]: string; } : Key extends Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => UnionSchema<Key, T, SourceOf<Key, T>>;