@valbuild/core 0.124.0 → 0.126.0

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

@@ -24,7 +24,41 @@ export declare class BooleanSchema<Src extends boolean | null> extends Schema<Sr
     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 this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s.boolean().describe("Show this item in the main menu");
+     * export default c.define("/example.val.ts", schema, true);
+     */
     describe(description: string | null): BooleanSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.boolean().validate((val) =>
+     *   val === true ? false : "This has to be on for now",
+     * );
+     * export default c.define("/example.val.ts", schema, true);
+     */
     validate(validationFunction: (src: Src) => false | string): BooleanSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -38,12 +72,22 @@ export declare class BooleanSchema<Src extends boolean | null> extends Schema<Sr
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.boolean().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [true, false]);
      */
     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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.boolean().preview(({ val }) => ({ title: val ? "On" : "Off" })),
+     * );
+     * export default c.define("/example.val.ts", schema, [true, false]);
      */
     preview(select: ItemPreviewInput<Src>): BooleanSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -55,7 +55,52 @@ export declare class CodeSchema<Src extends string | null> extends Schema<Src> {
     private readonly renderInput;
     private readonly previewInput;
     constructor(options?: CodeOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    /**
+     * Describe this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s
+     *   .code({ language: "css" })
+     *   .describe("Injected into the page head — keep it small");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   ".hero { color: red; }",
+     * );
+     */
     describe(description: string | null): CodeSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.code({ language: "json" }).validate((val) => {
+     *   try {
+     *     JSON.parse(val);
+     *     return false;
+     *   } catch {
+     *     return "Must be valid JSON";
+     *   }
+     * });
+     * export default c.define("/example.val.ts", schema, '{ "a": 1 }');
+     */
     validate(validationFunction: (src: Src) => false | string): CodeSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -69,12 +114,30 @@ export declare class CodeSchema<Src extends string | null> extends Schema<Src> {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.code({ language: "css" }).render({ as: "inline" }),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   ".hero { color: red; }",
+     * ]);
      */
     render(input: FieldRender): CodeSchema<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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.code({ language: "css" }).preview(({ val }) => ({
+     *     title: val.split("\n")[0],
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   ".hero { color: red; }",
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): CodeSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -50,7 +50,47 @@ export declare class ColorSchema<Src extends string | null> extends Schema<Src>
     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 this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s.color().describe("Background of the hero section");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "hsl(217.22 91.22% 59.8%)",
+     * );
+     */
     describe(description: string | null): ColorSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s
+     *   .color({ format: "hex" })
+     *   .validate((val) =>
+     *     val === val.toLowerCase() ? false : "Write hex in lower case",
+     *   );
+     * export default c.define("/example.val.ts", schema, "#3b82f6");
+     */
     validate(validationFunction: (src: Src) => false | string): ColorSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -64,12 +104,26 @@ export declare class ColorSchema<Src extends string | null> extends Schema<Src>
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.color().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   "hsl(217.22 91.22% 59.8%)",
+     * ]);
      */
     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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.color().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   "hsl(217.22 91.22% 59.8%)",
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): ColorSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -9,14 +9,14 @@ type DateOptions = {
      * Validate that the date is this date or after (inclusive).
      *
      * @example
-     * 2021-01-01
+     * "2021-01-01"
      */
     from?: string;
     /**
      * Validate that the date is this date or before (inclusive).
      *
      * @example
-     * 2021-01-01
+     * "2021-01-01"
      */
     to?: string;
 };
@@ -43,11 +43,63 @@ export declare class DateSchema<Src extends string | null> extends Schema<Src> {
     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 this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s.date().describe("First day the campaign is live");
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
     describe(description: string | null): DateSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.date().validate((val) =>
+     *   val >= "2025-01-01" ? false : "Must be in 2025 or later",
+     * );
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
     validate(validationFunction: (src: Src) => false | string): DateSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    /**
+     * Validate that the date is this date or after (inclusive).
+     *
+     * Written as `YYYY-MM-DD`, the same shape the value has.
+     *
+     * @example
+     * const schema = s.date().from("2025-01-01");
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
     from(from: string): DateSchema<Src>;
+    /**
+     * Validate that the date is this date or before (inclusive).
+     *
+     * Written as `YYYY-MM-DD`, the same shape the value has.
+     *
+     * @example
+     * const schema = s.date().from("2025-01-01").to("2025-12-31");
+     * export default c.define("/example.val.ts", schema, "2025-06-01");
+     */
     to(to: string): DateSchema<Src>;
     nullable(): DateSchema<Src | null>;
     readonly(isReadonly?: boolean): DateSchema<Src>;
@@ -59,12 +111,22 @@ export declare class DateSchema<Src extends string | null> extends Schema<Src> {
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.date().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["2025-06-01"]);
      */
     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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.date().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["2025-06-01"]);
      */
     preview(select: ItemPreviewInput<Src>): DateSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -11,7 +11,7 @@ type DateTimeOptions = {
      * Accepts any ISO 8601 datetime string parseable by `Date.parse`.
      *
      * @example
-     * 2021-01-01T00:00:00Z
+     * "2021-01-01T00:00:00Z"
      */
     from?: string;
     /**
@@ -20,7 +20,7 @@ type DateTimeOptions = {
      * Accepts any ISO 8601 datetime string parseable by `Date.parse`.
      *
      * @example
-     * 2021-12-31T23:59:59Z
+     * "2021-12-31T23:59:59Z"
      */
     to?: string;
 };
@@ -47,11 +47,82 @@ export declare class DateTimeSchema<Src extends string | null> extends Schema<Sr
     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 this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so
+     * it is where you say what an editor needs to know but the field name cannot
+     * carry. It also travels in the serialized schema, which is what the AI
+     * assistant and the MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s.datetime().describe("When the article goes live");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
     describe(description: string | null): DateTimeSchema<Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Write the check as a ternary, not as `ok || "message"`: that returns `true`
+     * when the value is fine, and `true` is not one of the two answers.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and
+     * before a publish.
+     *
+     * @example
+     * const schema = s.datetime().validate((val) =>
+     *   val.endsWith("Z") ? false : "Must be in UTC",
+     * );
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
     validate(validationFunction: (src: Src) => false | string): DateTimeSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    /**
+     * Validate that the datetime is this datetime or after (inclusive).
+     *
+     * Any ISO 8601 datetime string `Date.parse` understands.
+     *
+     * @example
+     * const schema = s.datetime().from("2025-01-01T00:00:00Z");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
     from(from: string): DateTimeSchema<Src>;
+    /**
+     * Validate that the datetime is this datetime or before (inclusive).
+     *
+     * Any ISO 8601 datetime string `Date.parse` understands.
+     *
+     * @example
+     * const schema = s
+     *   .datetime()
+     *   .from("2025-01-01T00:00:00Z")
+     *   .to("2025-12-31T23:59:59Z");
+     * export default c.define(
+     *   "/example.val.ts",
+     *   schema,
+     *   "2025-06-01T09:00:00.000Z",
+     * );
+     */
     to(to: string): DateTimeSchema<Src>;
     nullable(): DateTimeSchema<Src | null>;
     readonly(isReadonly?: boolean): DateTimeSchema<Src>;
@@ -63,12 +134,26 @@ export declare class DateTimeSchema<Src extends string | null> extends Schema<Sr
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.datetime().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   "2025-06-01T09:00:00.000Z",
+     * ]);
      */
     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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.datetime().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   "2025-06-01T09:00:00.000Z",
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): DateTimeSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -0,0 +1,166 @@
+import { CustomValidateFunction, Schema, SchemaAssertResult } from "./index.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";
+import { SerializedObjectSchema } from "./object.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+export type SerializedDiscriminatedUnionSchema = {
+    type: "discriminated-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;
+    /** The name of the field every variant tags itself with. */
+    key: string;
+    items: SerializedObjectSchema[];
+    opt: boolean;
+    customValidate?: boolean;
+    readonly?: boolean;
+    hidden?: boolean;
+    description?: string;
+};
+/** The variant objects a discriminated union on `Key` may be built from. */
+export type DiscriminatedUnionItem<Key extends string> = Schema<SourceObject & {
+    [k in Key]: string;
+}>;
+/**
+ * At least one variant, so a union with none cannot be written.
+ *
+ * Everything downstream reads the first one where it needs any — `emptyOf`
+ * takes `items[0]` for the value a new entry starts as — and a union with
+ * nothing to select is not a thing an author means. `s.enum` says the same
+ * about its values.
+ */
+export type DiscriminatedUnionItems<Key extends string> = [
+    DiscriminatedUnionItem<Key>,
+    ...DiscriminatedUnionItem<Key>[]
+];
+/** The source type a discriminated union over `T` accepts. */
+export type DiscriminatedUnionSourceOf<Key extends string, T extends DiscriminatedUnionItem<Key>[]> = T extends Schema<infer S>[] ? S extends SelectorSource ? S : never : never;
+/**
+ * One of several object shapes, told apart by a tag field.
+ *
+ * Every variant is an object with `key` set to a distinct `s.literal(...)`, and
+ * the value of that field decides which variant a value is. Unlike
+ * {@link EnumSchema} this is a CONTAINER: the variant's fields are the fields
+ * being edited, and everything that walks the schema tree has to descend
+ * through the matching variant.
+ */
+export declare class DiscriminatedUnionSchema<Key extends string, T extends DiscriminatedUnionItem<Key>[], Src extends DiscriminatedUnionSourceOf<Key, T> | null> extends Schema<Src> {
+    private readonly key;
+    private readonly items;
+    private readonly opt;
+    private readonly customValidateFunctions;
+    private readonly isReadonly;
+    private readonly isHidden;
+    private readonly description?;
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(key: Key, items: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    /**
+     * Describe this field.
+     *
+     * The description is shown next to the field's label in the Val editor, so it is
+     * where you say what an editor needs to know but the field name cannot carry. It
+     * also travels in the serialized schema, which is what the AI assistant and the
+     * MCP tools read.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const schema = s
+     *   .discriminatedUnion("type", hero, text)
+     *   .describe("What this section of the page is");
+     * export default c.define("/example.val.ts", schema, {
+     *   type: "hero",
+     *   title: "Hello",
+     * });
+     */
+    describe(description: string | null): DiscriminatedUnionSchema<Key, T, Src>;
+    /**
+     * Add a custom validation rule to this field.
+     *
+     * The function is called with the field's value and returns `false` when the
+     * value is fine, or a STRING with the message to show when it is not. Call it
+     * more than once to add more rules — they all run, and every message is
+     * reported.
+     *
+     * Validation runs in the Studio as you type, in `npx val validate` and before a
+     * publish.
+     *
+     * The function is given the whole value, whichever variant it took. A rule
+     * that only concerns one variant belongs on that variant's object schema.
+     *
+     * @example
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const schema = s
+     *   .discriminatedUnion("type", hero, text)
+     *   .validate((val) =>
+     *     val.type === "hero" && !val.title ? "A hero needs a title" : false,
+     *   );
+     * export default c.define("/example.val.ts", schema, {
+     *   type: "hero",
+     *   title: "Hello",
+     * });
+     */
+    validate(validationFunction: (src: Src) => false | string): DiscriminatedUnionSchema<Key, T, Src>;
+    protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    nullable(): DiscriminatedUnionSchema<Key, T, Src | null>;
+    readonly(isReadonly?: boolean): DiscriminatedUnionSchema<Key, T, Src>;
+    hidden(isHidden?: boolean): DiscriminatedUnionSchema<Key, T, Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * The variant schema a value takes. `null` when the value matches none of
+     * them — a structural error `executeValidate` 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`.
+     *
+     * @example
+     * // A page builder: the row draws the tag selector and the matched
+     * // variant's fields.
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const block = s.discriminatedUnion("type", hero, text).render({ as: "inline" });
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { type: "hero", title: "Hello" },
+     * ]);
+     */
+    render(input: FieldRender): DiscriminatedUnionSchema<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 discriminated union previews as the VARIANT the
+     * value takes — declare `preview` on the member objects and the union
+     * dispatches.
+     *
+     * @example
+     * const hero = s.object({ type: s.literal("hero"), title: s.string() });
+     * const text = s.object({ type: s.literal("text"), body: s.string() });
+     * const block = s
+     *   .discriminatedUnion("type", hero, text)
+     *   .preview(({ val }) => ({ title: val.type }));
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { type: "hero", title: "Hello" },
+     * ]);
+     */
+    preview(select: ItemPreviewInput<Src>): DiscriminatedUnionSchema<Key, T, Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
+    protected executeSerialize(): SerializedDiscriminatedUnionSchema;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+}
+export declare const discriminatedUnion: <Key extends string, T extends DiscriminatedUnionItems<Key>>(key: Key, ...objects: T) => DiscriminatedUnionSchema<Key, T, DiscriminatedUnionSourceOf<Key, T>>;