@valbuild/core 0.125.0 → 0.127.0

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

@@ -11,18 +11,20 @@ import { SerializedObjectSchema } from "./object.js";
 import { SerializedRecordSchema } from "./record.js";
 import { SerializedRichTextSchema } from "./richtext.js";
 import { RawString, SerializedStringSchema } from "./string.js";
-import { SerializedUnionSchema } from "./union.js";
+import { SerializedDiscriminatedUnionSchema } from "./discriminatedUnion.js";
+import { SerializedEnumSchema } from "./enum.js";
 import { SerializedCodeSchema } from "./code.js";
 import { SerializedColorSchema } from "./color.js";
 import { SerializedDateSchema } from "./date.js";
 import { SerializedDateTimeSchema } from "./datetime.js";
+import { SerializedLocaleSchema } from "./locale.js";
 import { SerializedRouteSchema } from "./route.js";
 import { SerializedSettingsSchema } from "./settings.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import { FileSource } from "../source/media.js";
 import { GenericRichTextSourceNode, RichTextSource } from "../source/richtext.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 | SerializedCodeSchema | SerializedRouteSchema | SerializedSettingsSchema | SerializedImageSchema;
+export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedDiscriminatedUnionSchema | SerializedEnumSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedLocaleSchema | SerializedSettingsSchema | SerializedImageSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
     message: string;
@@ -73,6 +75,88 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * against the real instance. Structural errors publish first; these merge in.
      */
     protected abstract executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * Whether this node is a locale — the field that MARKS a scope, `s.locale()`.
+     *
+     * Only `LocaleSchema` overrides this. A base implementation rather than an
+     * abstract one on purpose: every other schema class answers no, and a
+     * question every class had to answer would be twenty edits for one yes.
+     *
+     * Not the same question as {@link opensLocaleScope}: a locale field marks the
+     * scope, the object AROUND it is the scope. See `localeScope.ts`.
+     */
+    protected isLocaleField(): boolean;
+    /**
+     * Whether this node OPENS a locale scope, and what opens it.
+     *
+     * An object with a `s.locale()` field opens one; so does a record keyed by
+     * `s.locale()`. Everything below such a node is in that one language, which
+     * is why a scope may not contain another — see `localeScope.ts` for the rule
+     * and the reason it is validated rather than typed.
+     */
+    protected opensLocaleScope(): "field" | "key" | null;
+    /**
+     * The child schemas a locale scope reaches, by the path segment that reaches
+     * them.
+     *
+     * A structural walk that deliberately does NOT go through `executeSerialize`:
+     * serializing a subtree at every node to ask a question about its shape is
+     * quadratic, and this is asked during validation. `*` stands for the item of
+     * an array or record, which has no name of its own.
+     */
+    protected localeScopeChildren(): {
+        key: string;
+        schema: Schema<SelectorSource>;
+    }[];
+    /**
+     * Every locale scope opened strictly BELOW this node, by path.
+     *
+     * Stops descending at each one it finds, so a scope three deep is reported
+     * once, by the scope immediately enclosing it, rather than by every ancestor.
+     */
+    protected localeScopesBelow(prefix?: string[]): {
+        path: string[];
+        kind: "field" | "key";
+    }[];
+    /**
+     * The scope rule, as errors at this node — or `false` if it is not broken.
+     *
+     * Two things are wrong and both are wrong in the SCHEMA rather than in the
+     * content, so both are `schemaError`s: an object with two locale fields (the
+     * subtree below it would be in two languages at once), and a locale scope
+     * inside another (the inner one would silently override the outer for part
+     * of a subtree that is supposed to be one language throughout).
+     *
+     * Validated rather than typed on purpose. Expressing "no scope below this
+     * one" as a constraint means threading it through every schema class's type
+     * parameter, and the errors that fall out of a recursive constraint like
+     * that name the whole tree — an unrelated typo in a `.val.ts` would print
+     * pages. See the design notes on the locales PR.
+     */
+    protected localeScopeErrors(): ValidationError[];
+    /**
+     * The answer, computed once per schema.
+     *
+     * Memoised because the question is asked from `executeValidate`, which runs
+     * once per SOURCE instance: an array of five hundred blocks asks the item
+     * schema five hundred times, and each answer walks the schema below it
+     * looking for a nested scope. The answer cannot differ between two instances
+     * of the same schema — nothing here reads the source — so the walk is done
+     * once and the result handed back after that.
+     *
+     * The error is still reported at every instance's path. Val's validation
+     * errors are keyed by source path and that is where the Studio draws them, so
+     * a schema error on a row is a schema error on every row; reporting it on one
+     * arbitrary row would put it somewhere nobody was looking.
+     */
+    private localeScopeErrorsMemo?;
+    private computeLocaleScopeErrors;
+    /**
+     * This node's own `s.locale()` fields, where it is an object that has any.
+     *
+     * Empty everywhere else, so `localeScopeErrors` can live on the base class.
+     */
+    protected localeFieldNames(): string[];
     protected executeCustomValidateFunctions(src: Src, customValidateFunctions: CustomValidateFunction<Src>[], ctx: {
         path: SourcePath;
     }): ValidationError[];
@@ -92,6 +176,55 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * For example, if you have an object schema, you must assert each key / value pair manually.
      */
     protected abstract executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    /**
+     * Allow `null` as a value for this field.
+     *
+     * The editor gets a way to clear the field, and the type of the source
+     * widens to include `null` — so consuming code has to handle it.
+     *
+     * `.validate(...)` may be declared before or after `.nullable()`: the
+     * validator is carried over either way. Declared before, its argument is
+     * typed as non-null even though `null` can reach it, so guard for it.
+     *
+     * Implementations MUST carry `customValidateFunctions` over to the new
+     * instance. `.nullable()` returns a copy, so dropping them there silently
+     * un-declares the user's `.validate(...)` whenever it was written before the
+     * `.nullable()` — which is the order most people write it in. Thirteen schema
+     * classes passed `[]` here until this was fixed; `nullableCustomValidate.test.ts`
+     * pins one instance of every factory on `s` against that, and does not compile
+     * until a newly added schema is listed in it.
+     *
+     * The validators keep running when the value IS null: a nullable schema's
+     * validator sees `Src | null` and decides for itself. That is what the
+     * classes that never dropped them (string, record, route, file, image) have
+     * always done.
+     *
+     * Carrying them over needs a cast, because `Src` sits in a PARAMETER position
+     * of {@link CustomValidateFunction} and so `CustomValidateFunction<Src>[]` is
+     * not assignable to `CustomValidateFunction<Src | null>[]`. Widening what the
+     * functions can be CALLED with is the intent here rather than something the
+     * cast gets away with: `null` is handed to them, and the paragraph above is
+     * the behaviour that buys.
+     *
+     * A validator's parameter type was never a runtime guarantee to begin with.
+     * `executeValidate` runs the custom validators BEFORE the structural checks
+     * (see {@link CustomValidateFunction}'s callers, e.g. `NumberSchema`, which
+     * calls them ahead of its `typeof src !== "number"`), so one can already be
+     * called with a value of the wrong type entirely — hand-written content, or
+     * a node the Studio's walker reached before its type was checked. That is why
+     * {@link executeCustomValidateFunctions} catches what a validator throws and
+     * reports it as a `schemaError` instead of letting it escape.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string(),
+     *   subtitle: s.string().nullable(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   title: "Hello",
+     *   subtitle: null,
+     * });
+     */
     abstract nullable(): Schema<Src | null>;
     /**
      * Mark this field as read-only in the Val editor.
@@ -102,6 +235,16 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * The flag defaults to `true`, so `.readonly()` and `.readonly(true)` are the
      * same thing. `.readonly(false)` leaves the field editable, which is what a
      * schema is anyway - pass it when the decision comes from a variable.
+     *
+     * @example
+     * const schema = s.object({
+     *   id: s.string().readonly(),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   id: "generated-by-the-build",
+     *   title: "Hello",
+     * });
      */
     abstract readonly(isReadonly?: boolean): Schema<Src>;
     /**
@@ -113,6 +256,16 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * The flag defaults to `true`, so `.hidden()` and `.hidden(true)` are the
      * same thing. `.hidden(false)` leaves the field visible, which is what a
      * schema is anyway - pass it when the decision comes from a variable.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string(),
+     *   internalNotes: s.string().hidden(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   title: "Hello",
+     *   internalNotes: "Not shown in the editor",
+     * });
      */
     abstract hidden(isHidden?: boolean): Schema<Src>;
     protected abstract executeSerialize(): SerializedSchema;

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

@@ -42,7 +42,45 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
     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 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
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.keyOf(authorsVal).describe("Who wrote this post");
+     * export default c.define("/example.val.ts", schema, "ada");
+     */
     describe(description: string | null): KeyOfSchema<Sel, 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
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s
+     *   .keyOf(authorsVal)
+     *   .validate((val) =>
+     *     val === "placeholder" ? "Pick a real author" : false,
+     *   );
+     * export default c.define("/example.val.ts", schema, "ada");
+     */
     validate(validationFunction: (src: Src) => false | string): KeyOfSchema<Sel, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -56,12 +94,24 @@ export declare class KeyOfSchema<Sel extends GenericSelector<SourceObject>, Src
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.array(s.keyOf(authorsVal).render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["ada"]);
      */
     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`.
+     *
+     * @example
+     * import authorsVal from "./authors.val"; // a record module
+     * const schema = s.array(
+     *   s.keyOf(authorsVal).preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["ada"]);
      */
     preview(select: ItemPreviewInput<Src>): KeyOfSchema<Sel, Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -25,8 +25,46 @@ export declare class LiteralSchema<Src extends string | null> extends Schema<Src
     private readonly description?;
     private readonly renderInput;
     private readonly previewInput;
+    /** Type-only marker: as a record key, this declares the key set. See `LocaleSchema`. */
+    readonly __declaresRecordKeys: true;
     constructor(value: string, 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
+     *   .literal("hero")
+     *   .describe("The block type — it identifies the variant");
+     * export default c.define("/example.val.ts", schema, "hero");
+     */
     describe(description: string | null): LiteralSchema<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.literal("hero").validate((val) =>
+     *   val === "hero" ? false : "Unknown block type",
+     * );
+     * export default c.define("/example.val.ts", schema, "hero");
+     */
     validate(validationFunction: (src: Src) => false | string): LiteralSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -40,12 +78,22 @@ export declare class LiteralSchema<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.literal("hero").render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["hero"]);
      */
     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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.literal("hero").preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["hero"]);
      */
     preview(select: ItemPreviewInput<Src>): LiteralSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -0,0 +1,132 @@
+import { Schema, SchemaAssertResult, SerializedSchema } from "./index.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 SerializedLocaleSchema = {
+    type: "locale";
+    /** Static layout config, carried whole in the serialized schema — see `render.ts`. */
+    render?: FieldRender;
+    /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
+    preview?: true;
+    opt: boolean;
+    customValidate?: boolean;
+    readonly?: boolean;
+    hidden?: boolean;
+    description?: string;
+};
+/**
+ * One of the languages the project publishes.
+ *
+ * The set is NOT here. It is declared in the settings module — `locales.available`
+ * — so that adding a language is something the people who write the content can
+ * do, and so that one list drives validation, the Studio's picker and the
+ * translation notes. This schema knows only that the value is one of them, which
+ * is checked cross-module through the `locale:check-locale` fix, exactly as
+ * `keyOf` and `route` check theirs.
+ *
+ * Never stega encoded (see `stegaEncode.ts`): a locale goes into `<html lang>`,
+ * into `hreflang` and into `Intl` constructors, none of which survive invisible
+ * characters.
+ */
+export declare class LocaleSchema<Src extends string | null> extends Schema<Src> {
+    private readonly opt;
+    private readonly customValidateFunctions;
+    private readonly isReadonly;
+    private readonly isHidden;
+    private readonly description?;
+    private readonly renderInput;
+    private readonly previewInput;
+    /**
+     * Type-only marker: as a record key, this schema DECLARES the key set.
+     *
+     * `declare` so it exists in the type and nowhere at runtime — reading it off
+     * an instance gives `undefined`, and nothing should. It is how `record()`
+     * knows to type entries as `Item | null`: a language nobody has translated
+     * into is a null entry, not an absent key. See `DeclaredKeySet` and
+     * `RecordSrcOf`.
+     */
+    readonly __declaresRecordKeys: true;
+    constructor(opt?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    /**
+     * A note to whoever edits this field, shown under it in the Studio.
+     *
+     * Pass `null` to clear a description set earlier.
+     *
+     * @example
+     * const schema = s.object({
+     *   locale: s.locale().describe("The language everything below is written in"),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   locale: "nb-NO",
+     *   title: "Vinterjakke",
+     * });
+     */
+    describe(description: string | null): LocaleSchema<Src>;
+    /**
+     * A check of your own, on top of "is this one of the project's languages".
+     *
+     * Return a message when the value is WRONG and `false` when it is fine — the
+     * two answers are a complaint and no complaint, so write the check as a
+     * ternary rather than as `ok || "message"`, which returns `true` and `true`
+     * is neither.
+     *
+     * @example
+     * const schema = s.object({
+     *   locale: s.locale().validate((val) =>
+     *     val === "en-US" ? "This section is not translated into English yet" : false,
+     *   ),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   locale: "nb-NO",
+     *   title: "Vinterjakke",
+     * });
+     */
+    validate(validationFunction: (src: Src) => false | string): LocaleSchema<Src>;
+    protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    nullable(): LocaleSchema<Src | null>;
+    readonly(): LocaleSchema<Src>;
+    hidden(): LocaleSchema<Src>;
+    protected isLocaleField(): boolean;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    /**
+     * How this field is laid out where it is the item of an array or a record.
+     * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * const schema = s.array(s.locale().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, ["nb-NO", "en-US"]);
+     */
+    render(input: FieldRender): LocaleSchema<Src>;
+    /**
+     * How this VALUE is shown where a preview of it is needed. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.locale().preview(({ val }) => ({ title: val })),
+     * );
+     * export default c.define("/example.val.ts", schema, ["nb-NO", "en-US"]);
+     */
+    preview(select: ItemPreviewInput<Src>): LocaleSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
+    protected executeSerialize(): SerializedSchema;
+    protected executePreview(): ReifiedPreview;
+}
+/**
+ * Define one of the project's languages.
+ *
+ * The languages themselves are declared in the settings module, under
+ * `locales.available` — this says only that a value is one of them.
+ *
+ * @example // a field: everything under this object is in this language
+ * const schema = s.object({ locale: s.locale(), title: s.string() });
+ *
+ * @example // a key: one entry per language
+ * const schema = s.record(s.locale(), s.object({ title: s.string() }));
+ */
+export declare const locale: () => LocaleSchema<string>;

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

@@ -30,14 +30,62 @@ export declare class NumberSchema<Src extends number | null> extends Schema<Src>
     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 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.number().describe("How many columns the grid uses");
+     * export default c.define("/example.val.ts", schema, 3);
+     */
     describe(description: string | null): NumberSchema<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.number().validate((val) =>
+     *   Number.isInteger(val) ? false : "Must be a whole number",
+     * );
+     * export default c.define("/example.val.ts", schema, 3);
+     */
     validate(validationFunction: (src: Src) => false | string): NumberSchema<Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): NumberSchema<Src | null>;
     readonly(isReadonly?: boolean): NumberSchema<Src>;
     hidden(isHidden?: boolean): NumberSchema<Src>;
+    /**
+     * Validate that the number is at most `max` (inclusive).
+     *
+     * @example
+     * const schema = s.number().max(4);
+     * export default c.define("/example.val.ts", schema, 3);
+     */
     max(max: number): NumberSchema<Src>;
+    /**
+     * Validate that the number is at least `min` (inclusive).
+     *
+     * @example
+     * const schema = s.number().min(1).max(4);
+     * export default c.define("/example.val.ts", schema, 3);
+     */
     min(min: number): NumberSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
@@ -46,12 +94,22 @@ export declare class NumberSchema<Src extends number | 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.number().render({ as: "inline" }));
+     * export default c.define("/example.val.ts", schema, [1, 2]);
      */
     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`.
+     *
+     * @example
+     * const schema = s.array(
+     *   s.number().preview(({ val }) => ({ title: String(val) })),
+     * );
+     * export default c.define("/example.val.ts", schema, [1, 2]);
      */
     preview(select: ItemPreviewInput<Src>): NumberSchema<Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;

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

@@ -50,13 +50,65 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     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 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
+     *   .object({ street: s.string(), city: s.string() })
+     *   .describe("Where the office is — shown on the contact page");
+     * export default c.define("/example.val.ts", schema, {
+     *   street: "Torggata 1",
+     *   city: "Oslo",
+     * });
+     */
     describe(description: string | null): ObjectSchema<Props, 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.
+     *
+     * An object validator is the place for a rule that spans FIELDS — one field
+     * validated on its own belongs on that field's schema, where the error lands
+     * on the field itself.
+     *
+     * @example
+     * const schema = s
+     *   .object({ from: s.number(), to: s.number() })
+     *   .validate((val) =>
+     *     val.from <= val.to ? false : "'from' must not be after 'to'",
+     *   );
+     * export default c.define("/example.val.ts", schema, { from: 1, to: 4 });
+     */
     validate(validationFunction: (src: Src) => false | string): ObjectSchema<Props, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): ObjectSchema<Props, Src | null>;
     readonly(isReadonly?: boolean): ObjectSchema<Props, Src>;
     hidden(isHidden?: boolean): ObjectSchema<Props, Src>;
+    /** The names of this object's `s.locale()` fields, in declaration order. */
+    protected localeFieldNames(): string[];
+    protected opensLocaleScope(): "field" | "key" | null;
+    protected localeScopeChildren(): {
+        key: string;
+        schema: Schema<SelectorSource>;
+    }[];
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array
@@ -64,12 +116,30 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
      * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`.
+     *
+     * @example
+     * // A page builder: each row edits the object in place, instead of
+     * // navigating to it.
+     * const block = s
+     *   .object({ heading: s.string(), body: s.string() })
+     *   .render({ as: "inline" });
+     * export default c.define("/example.val.ts", s.array(block), [
+     *   { heading: "Hello", body: "World" },
+     * ]);
      */
     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`.
+     *
+     * @example
+     * 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.array(author), [
+     *   { name: "Ada", role: "Engineer" },
+     * ]);
      */
     preview(select: ItemPreviewInput<Src>): ObjectSchema<Props, Src>;
     protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;