@valbuild/core 0.106.0 → 0.110.0

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

@@ -3,16 +3,54 @@ import { GalleryImageSource, ImageSource } from "../source/media.js";
 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 { ImagesEntryMetadata } from "./images.js";
+/**
+ * How an uploaded image is re-encoded in the browser, before it is uploaded.
+ *
+ * Off unless a schema asks for it. When it is on, the image is converted to
+ * `type` and scaled down to fit `maxWidth` x `maxHeight` - unless the result
+ * would be BIGGER than the original and no downscale was needed, in which case
+ * the original bytes are kept. See `architecture/media.md`.
+ *
+ * `type` is required so that adding a format later is additive: a schema
+ * written today keeps saying exactly which format it asked for.
+ */
+export type ImageEncodeOptions = {
+    type: "webp";
+    /** Passed to `canvas.toBlob`. Between 0 and 1. @default 0.8 */
+    quality?: number;
+    /** @default 2560 */
+    maxWidth?: number;
+    /** @default 2560 */
+    maxHeight?: number;
+};
+/** `false` (or absent) uploads the bytes exactly as the editor picked them. */
+export type ImageEncodeOption = false | ImageEncodeOptions;
+/**
+ * What a GALLERY-BACKED field may say for itself.
+ *
+ * Not `ImageOptions`: `directory` and `accept` belong to the gallery, and a
+ * field repeating them is how two copies of one fact get to disagree. `encode`
+ * is different — it describes what happens to the bytes on their way IN, so a
+ * field that wants the original where its gallery re-encodes has to be able to
+ * say `encode: false`, and there is nowhere else to say it.
+ */
+export type GalleryImageOptions = {
+    encode?: ImageEncodeOption;
+};
 export type ImageOptions = {
-    ext?: ["jpg"] | ["webp"];
     directory?: string;
-    prefix?: string;
     accept?: string;
+    encode?: ImageEncodeOption;
 };
 export type SerializedImageSchema = {
     type: "image";
+    /** 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?: ImageOptions;
     opt: boolean;
     remote?: boolean;
@@ -41,7 +79,9 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     describe(description: string | null): ImageSchema<Src>;
     remote(): ImageSchema<Src>;
     validate(validationFunction: CustomValidateFunction<Src>): ImageSchema<Src>;
@@ -56,6 +96,22 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     readonly(): ImageSchema<Src>;
     hidden(): ImageSchema<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): ImageSchema<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>): ImageSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
     protected executeSerialize(): SerializedSchema;
     protected executePreview(): ReifiedPreview;
 }
@@ -63,6 +119,6 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
  * An image picked from a gallery. Its dimensions and mime type live in the
  * gallery, so the field carries only what a person typed.
  */
-export declare function image(galleryModule: ValModule<Record<string, ImagesEntryMetadata>>): ImageSchema<GalleryImageSource>;
+export declare function image(galleryModule: ValModule<Record<string, ImagesEntryMetadata>>, galleryOptions?: GalleryImageOptions): ImageSchema<GalleryImageSource>;
 /** An image of its own, carrying its own dimensions and mime type. */
 export declare function image(options?: ImageOptions): ImageSchema<ImageSource>;

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

@@ -4,6 +4,7 @@ import { RecordSchema } from "./record.js";
 import { ObjectSchema } from "./object.js";
 import { StringSchema } from "./string.js";
 import { NumberSchema } from "./number.js";
+import type { ImageEncodeOption } from "./image.js";
 /**
  * Alt schema type - can be a string, nullable string, or a record of locale to string
  */
@@ -39,6 +40,13 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
      * @default false
      */
     remote?: boolean;
+    /**
+     * Re-encode uploads in the browser before they are uploaded.
+     *
+     * Off unless set. A field backed by this gallery (`s.image(galleryVal)`)
+     * inherits it, the same way it inherits `accept` and `directory`.
+     */
+    encode?: ImageEncodeOption;
 };
 /**
  * Metadata for an image entry in the images record

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,30 +1,41 @@
 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";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+import type { ImageEncodeOption } from "./image.js";
 type MediaOptions = {
     type: "files" | "images";
     accept: string;
     directory: string;
     remote: boolean;
     altSchema?: Schema<SelectorSource>;
+    /** Images only: how uploads are re-encoded in the browser. See `image.ts`. */
+    encode?: ImageEncodeOption;
 };
 export type SerializedRecordSchema = {
     type: "record";
     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";
     accept?: string;
     directory?: string;
     remote?: boolean;
+    encode?: ImageEncodeOption;
     alt?: SerializedSchema;
     jsonValues?: boolean;
     readonly?: boolean;
@@ -45,10 +56,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 +69,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 +114,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