@valbuild/core 0.125.0 → 0.126.0

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

@@ -108,7 +108,48 @@ RO extends boolean = false> extends Schema<Src> {
      * sites.
      */
     externalLabel?: string | 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
+     *   .record(s.string())
+     *   .describe("Button labels, keyed by locale");
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
+     */
     describe(description: string | null): RecordSchema<T, K, 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.
+     *
+     * The function is given the whole record. To validate one entry, put a
+     * `.validate(...)` on the ITEM schema instead — that reports the error on
+     * the entry's own row, and on a `.jsonValues()` record it does not force
+     * every entry to be loaded.
+     *
+     * @example
+     * const schema = s.record(s.string()).validate((val) =>
+     *   "en" in val ? false : "There has to be an 'en' entry",
+     * );
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
+     */
     validate(validationFunction: (src: Src) => false | string): RecordSchema<T, K, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     private isRemoteUrl;
@@ -128,10 +169,55 @@ RO extends boolean = false> extends Schema<Src> {
      * must come BEFORE `.external()`: afterwards the value is a `Schema`, and
      * there is no `.readonly()` left to call — which is the error the compiler
      * gives, and a clearer one than a runtime throw.
+     *
+     * @example
+     * const schema = s.record(s.string()).readonly();
+     * export default c.define("/example.val.ts", schema, { en: "Read more" });
      */
     readonly<B extends boolean = true>(isReadonly?: B): RecordSchema<T, K, Src, B>;
     hidden(isHidden?: boolean): RecordSchema<T, K, Src>;
+    /**
+     * Turn this record into a page router: its keys are route paths of your
+     * application, and they are validated against the router's conventions.
+     *
+     * `s.router(router, item)` builds the same thing in one call and is what
+     * most code should use — this is for adding a router to a record that
+     * already exists.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .record(s.object({ title: s.string() }))
+     *   .router(nextAppRouter);
+     * export default c.define("/app/[slug]/page.val.ts", schema, {
+     *   "/a-page-slug": { title: "First Page" },
+     * });
+     */
     router(router: ValRouter): RecordSchema<T, K, Src>;
+    /**
+     * Allow the files in this gallery to be stored on Val's remote content host
+     * instead of in your repository.
+     *
+     * For `s.images()` and `s.files()`, which are records of media. Remote is off
+     * until this is called.
+     *
+     * Each entry is then keyed by its URL on the content host rather than by a
+     * path under `/public`. That key is not something to write by hand: upload
+     * in the Studio, or add a local path and let `npx val validate --fix`
+     * upload it and rewrite the key.
+     *
+     * @example
+     * const schema = s.images({ directory: "/public/val/images" }).remote();
+     * export default c.define("/content/images.val.ts", schema, {
+     *   "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/hero.webp":
+     *     {
+     *       width: 1920,
+     *       height: 1080,
+     *       mimeType: "image/webp",
+     *       alt: "Hero image",
+     *     },
+     * });
+     */
     remote(): RecordSchema<T, K, Src>;
     /**
      * Store each entry's value in its own lazily-loaded `*.val.json` file instead
@@ -146,6 +232,20 @@ RO extends boolean = false> extends Schema<Src> {
      * nested inside an object/array/record is rejected at startup with a module
      * error, because the single-entry fetch endpoint, the Studio's content
      * substitution and content validation are all root-only.
+     *
+     * Must come BEFORE `.validate()` and `.preview()`: those are typed against
+     * the un-lazy source shape, so a validator or preview declared first cannot
+     * be carried over, and declaring one first throws rather than silently
+     * dropping it.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .router(nextAppRouter, s.object({ title: s.string(), body: s.string() }))
+     *   .jsonValues();
+     * export default c.define("/app/support/[slug]/page.val.ts", schema, {
+     *   "/support/faq": c.json(() => import("./content/faq.val.json")),
+     * });
      */
     jsonValues(): RecordSchema<T, K, JsonValuesRecordSrc<T, K>>;
     /**
@@ -166,6 +266,19 @@ RO extends boolean = false> extends Schema<Src> {
      * nested external record would leave a hole in the middle of a module's
      * source, and the Studio, patching and validation all assume a module's
      * source is complete apart from its entries.
+     *
+     * @example
+     * const schema = s.record(s.object({ title: s.string() })).external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
+     *
+     * @example
+     * // A read-only external record: `.readonly()` must come FIRST, because
+     * // afterwards there is no `.readonly()` left on the type to call.
+     * const schema = s
+     *   .record(s.object({ title: s.string() }))
+     *   .readonly()
+     *   .external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
      */
     external<L extends string>(label: L): RecordSchema<T, K, ExternalRecordSrc<SelectorOfSchema<T>, L, RO>, RO>;
     /**
@@ -197,6 +310,25 @@ RO extends boolean = false> extends Schema<Src> {
      * 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`.
+     *
+     * @example
+     * // The preview of the RECORD, for where it is an item of something else.
+     * // What its own rows show is the ITEM schema's preview — see below.
+     * const labels = s.record(s.string()).preview(({ val }) => ({
+     *   title: `${Object.keys(val).length} locales`,
+     * }));
+     * export default c.define("/example.val.ts", s.array(labels), [
+     *   { en: "Read more" },
+     * ]);
+     *
+     * @example
+     * // Rows of a record come from the ITEM's preview, not the record's:
+     * const author = s
+     *   .object({ name: s.string(), role: s.string() })
+     *   .preview(({ val }) => ({ title: val.name, subtitle: val.role }));
+     * export default c.define("/example.val.ts", s.record(author), {
+     *   ada: { name: "Ada", role: "Engineer" },
+     * });
      */
     preview(select: ItemPreviewInput<Src>): RecordSchema<T, K, Src>;
     /**
@@ -205,6 +337,10 @@ RO extends boolean = false> 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.record(s.string()).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [{ en: "Read more" }]);
      */
     render(input: FieldRender): RecordSchema<T, K, Src>;
 }

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

@@ -31,9 +31,71 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     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 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.richtext().describe("The body of the article");
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
     describe(description: string | null): RichTextSchema<O, Src>;
+    /**
+     * Validate that the rich text holds at most `max` characters.
+     *
+     * Counted over the TEXT, not the markup: tags, attributes and the structure
+     * of the document do not add to it.
+     *
+     * @example
+     * const schema = s.richtext().maxLength(280);
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
     maxLength(max: number): RichTextSchema<O, Src>;
+    /**
+     * Validate that the rich text holds at least `min` characters.
+     *
+     * Counted over the TEXT, not the markup: tags, attributes and the structure
+     * of the document do not add to it.
+     *
+     * @example
+     * const schema = s.richtext().minLength(20).maxLength(280);
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Long enough to clear the minimum length."] },
+     * ]);
+     */
     minLength(min: number): RichTextSchema<O, 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.richtext().validate((val) =>
+     *   val.length > 0 ? false : "Write something",
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   { tag: "p", children: ["Hello"] },
+     * ]);
+     */
     validate(validationFunction: (src: Src) => false | string): RichTextSchema<O, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     private internalValidate;
@@ -49,12 +111,28 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.richtext().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [
+     *   [{ tag: "p", children: ["Hello"] }],
+     * ]);
      */
     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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.richtext().preview(({ val }) => ({
+     *     title: val.length > 0 ? "Rich text" : "Empty",
+     *   })),
+     * );
+     * export default c.define("/example.val.ts", schema, [
+     *   [{ tag: "p", children: ["Hello"] }],
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): RichTextSchema<O, Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -40,6 +40,20 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     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 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.route().describe("Where the button goes");
+     * export default c.define("/example.val.ts", schema, "/a-page-slug");
+     */
     describe(description: string | null): RouteSchema<Src>;
     /**
      * Specify a pattern for which routes are allowed.
@@ -67,6 +81,26 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
      * s.route().include(/^\/api\//).exclude(/^\/api\/internal\//)  // API routes except internal
      */
     exclude(pattern: RegExp): RouteSchema<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.route().validate((val) =>
+     *   val.endsWith("/") ? "Leave off the trailing slash" : false,
+     * );
+     * export default c.define("/example.val.ts", schema, "/a-page-slug");
+     */
     validate(validationFunction: (src: Src) => false | string): RouteSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -80,12 +114,22 @@ export declare class RouteSchema<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.route().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["/a-page-slug"]);
      */
     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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.route().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["/a-page-slug"]);
      */
     preview(select: ItemPreviewInput<Src>): RouteSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -66,24 +66,113 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     private readonly previewInput;
     private readonly isMultiline;
     constructor(options?: StringOptions | undefined, opt?: boolean, isRaw?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], renderInput?: FieldRender | null, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null, isMultiline?: boolean);
+    /**
+     * 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
+     *   .string()
+     *   .describe("Shown in the browser tab and in search results");
+     * export default c.define("/example.val.ts", schema, "Hello");
+     */
     describe(description: string | null): StringSchema<Src>;
     /**
      * @deprecated Use `minLength` instead
+     *
+     * @example
+     * const schema = s.string().minLength(2);
+     * export default c.define("/example.val.ts", schema, "Hi");
      */
     min(minLength: number): StringSchema<Src>;
+    /**
+     * Validate that the string is at least `minLength` characters long.
+     *
+     * @example
+     * const schema = s.string().minLength(2);
+     * export default c.define("/example.val.ts", schema, "Hi");
+     */
     minLength(minLength: number): StringSchema<Src>;
     /**
      * @deprecated Use `maxLength` instead
+     *
+     * @example
+     * const schema = s.string().maxLength(60);
+     * export default c.define("/example.val.ts", schema, "A title that fits");
      */
     max(maxLength: number): StringSchema<Src>;
+    /**
+     * Validate that the string is at most `maxLength` characters long.
+     *
+     * @example
+     * const schema = s.string().maxLength(60);
+     * export default c.define("/example.val.ts", schema, "A title that fits");
+     */
     maxLength(maxLength: number): StringSchema<Src>;
+    /**
+     * Validate that the string matches `regexp`.
+     *
+     * `message` is what the editor is shown when it does not match. Without one
+     * the error names the pattern, which is rarely what a non-developer needs.
+     *
+     * @example
+     * const schema = s
+     *   .string()
+     *   .regexp(/^[a-z0-9-]+$/, "Lower case letters, digits and dashes only");
+     * export default c.define("/example.val.ts", schema, "my-slug");
+     */
     regexp(regexp: RegExp, message?: string): StringSchema<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.string().validate((val) =>
+     *   val.trim() === val ? false : "Must not start or end with a space",
+     * );
+     * export default c.define("/example.val.ts", schema, "Hello");
+     */
     validate(validationFunction: (src: Src) => false | string): StringSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): StringSchema<Src | null>;
     readonly(isReadonly?: boolean): StringSchema<Src>;
     hidden(isHidden?: boolean): StringSchema<Src>;
+    /**
+     * Do not stega encode this string.
+     *
+     * Val normally encodes an invisible pointer back to the source into every
+     * string it hands your app, which is what makes click-to-edit work. A raw
+     * string is handed over exactly as written — use it wherever the value is
+     * not rendered as visible text: a slug, a class name, an `id`, a URL,
+     * anything parsed or compared.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string(),
+     *   slug: s.string().raw(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   title: "Hello",
+     *   slug: "hello",
+     * });
+     */
     raw(): StringSchema<Src extends null ? RawString | null : RawString>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
@@ -107,12 +196,22 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
      *
      * Static configuration, not a callback — see `render.ts`. What a CONTAINER
      * shows for its items is a `preview`, which is a different thing entirely.
+     *
+     * @example
+     * const schema = s.array(s.string().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
      */
     render(input: FieldRender): 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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.string().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["First", "Second"]);
      */
     preview(select: ItemPreviewInput<Src>): StringSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -1,93 +1,56 @@
-import { CustomValidateFunction, Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
-import { ItemPreviewInput, PreviewItem, ReifiedPreview, PreviewScope } from "../preview.js";
-import { FieldRender } from "../render.js";
+import { Schema } from "./index.js";
 import { SelectorSource } from "../selector/index.js";
-import { SourceObject } from "../source/index.js";
-import { ModuleFilePath, SourcePath } from "../val/index.js";
-import { SerializedLiteralSchema } from "./literal.js";
-import { SerializedObjectSchema } from "./object.js";
-import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
-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;
-    customValidate?: boolean;
-    readonly?: boolean;
-    hidden?: boolean;
-    description?: string;
-};
-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;
-    customValidate?: boolean;
-    readonly?: boolean;
-    hidden?: boolean;
-    description?: string;
-};
-type SourceOf<Key extends string | Schema<string>, T extends Schema<Key extends string ? SourceObject & {
-    [k in Key]: string;
-} : Key extends Schema<string> ? string : unknown>[]> = T extends Schema<infer S>[] ? S extends SelectorSource ? S | (Key extends Schema<infer K> ? K : never) : never : never;
-export declare class UnionSchema<Key extends string | Schema<string>, T extends Schema<Key extends string ? SourceObject & {
-    [k in Key]: string;
-} : Key extends Schema<string> ? string : unknown>[], Src extends SourceOf<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;
-    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;
-    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
-    nullable(): UnionSchema<Key, T, Src | null>;
-    readonly(isReadonly?: boolean): UnionSchema<Key, T, Src>;
-    hidden(isHidden?: boolean): UnionSchema<Key, T, Src>;
-    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
-    /**
-     * The variant schema a value takes, for a TAGGED union (string `key`). `null`
-     * for a literal union (its variants are leaves with nothing to descend into) or
-     * 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`.
-     */
-    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, 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>>;
+import { DiscriminatedUnionItems, DiscriminatedUnionSchema, DiscriminatedUnionSourceOf, SerializedDiscriminatedUnionSchema } from "./discriminatedUnion.js";
+import { EnumSchema, SerializedEnumSchema } from "./enum.js";
+/**
+ * @deprecated Use {@link SerializedDiscriminatedUnionSchema} or
+ * {@link SerializedEnumSchema}. A serialized union is now one or the other,
+ * distinguished by `type` rather than by the shape of `key`.
+ */
+export type SerializedUnionSchema = SerializedDiscriminatedUnionSchema | SerializedEnumSchema;
+/** @deprecated Use {@link SerializedEnumSchema}. */
+export type SerializedStringUnionSchema = SerializedEnumSchema;
+/** @deprecated Use {@link SerializedDiscriminatedUnionSchema}. */
+export type SerializedObjectUnionSchema = SerializedDiscriminatedUnionSchema;
+/**
+ * @deprecated There is no single union schema class any more: name
+ * {@link DiscriminatedUnionSchema} or {@link EnumSchema}. The type parameters
+ * are kept so existing annotations still compile, but only `Src` is used.
+ */
+export type UnionSchema<_Key = unknown, _T = unknown, Src extends SelectorSource = SelectorSource> = Schema<Src>;
+/**
+ * The value type of a list of literal schemas — how `s.union` typed a union of
+ * literals. Inferred from `Schema<infer S>` rather than `LiteralSchema<infer S>`
+ * because a `LiteralSchema` is invariant in its source (its custom validate
+ * functions put it in a parameter position), so `LiteralSchema<"a">` is not
+ * assignable to `LiteralSchema<"a" | "b">`.
+ */
+type EnumSourceOf<T extends Schema<string>[]> = T extends Schema<infer S>[] ? S extends string ? S : never : never;
+/**
+ * @deprecated Use `s.discriminatedUnion(key, ...objects)` for a tagged union of
+ * objects, or `s.enum("a", "b")` for one of a fixed set of strings.
+ *
+ * One thing does NOT survive the literal form: an enum's values are strings,
+ * so a member literal's own `.validate()` and `.describe()` are dropped rather
+ * than carried over. `s.union(s.literal("a").validate(...), ...)` ran that
+ * validator as part of deciding whether the value matched; `s.enum` has no
+ * member to run. A validator on a single-valued literal could only accept or
+ * reject that one value, which the enum's own value list already decides — but
+ * if you rely on one, keep it by validating the enum itself.
+ *
+ * @example
+ * // was: s.union("type", s.object({ type: s.literal("a"), a: s.string() }))
+ * const schema = s.discriminatedUnion(
+ *   "type",
+ *   s.object({ type: s.literal("a"), a: s.string() }),
+ * );
+ * export default c.define("/example.val.ts", schema, { type: "a", a: "one" });
+ *
+ * @example
+ * // was: s.union(s.literal("a"), s.literal("b"))
+ * const schema = s.enum("a", "b");
+ * export default c.define("/example.val.ts", schema, "a");
+ */
+export declare function union<Key extends string, T extends DiscriminatedUnionItems<Key>>(key: Key, ...objects: T): DiscriminatedUnionSchema<Key, T, DiscriminatedUnionSourceOf<Key, T>>;
+export declare function union<T extends Schema<string>[]>(...literals: T): EnumSchema<EnumSourceOf<T>>;
 export {};