@valbuild/core 0.126.0 → 0.128.0

package/dist/declarations/src/schema/{files.d.ts → fileset.d.ts}

@@ -4,9 +4,9 @@ import { RecordSchema } from "./record.js";
 import { ObjectSchema } from "./object.js";
 import { StringSchema } from "./string.js";
 /**
- * Options for s.files()
+ * Options for s.fileset()
  */
-export type FilesOptions = {
+export type FilesetOptions = {
     /**
      * The accepted mime type pattern (e.g., "application/pdf", "text/*", "*\/*")
      */
@@ -20,19 +20,19 @@ export type FilesOptions = {
      * collection that had simply not said where it wanted its files silently shared
      * a directory with every other one.
      */
-    directory: "/public" | `/public/${string}`;
+    dir: "/public" | `/public/${string}`;
 };
 /**
  * Metadata for a file entry in the files record
  */
-export type FilesEntryMetadata = {
+export type FilesetEntryMetadata = {
     mimeType: string;
 };
-export type SerializedFilesSchema = SerializedRecordSchema;
-type FilesItemProps = {
+export type SerializedFilesetSchema = SerializedRecordSchema;
+type FilesetItemProps = {
     mimeType: StringSchema<string>;
 };
-type FilesItemSrc = {
+type FilesetItemSrc = {
     mimeType: string;
 };
 /**
@@ -42,9 +42,9 @@ type FilesItemSrc = {
  *
  * @example
  * ```typescript
- * const schema = s.files({
+ * const schema = s.fileset({
  *   accept: "application/pdf",
- *   directory: "/public/val/documents",
+ *   dir: "/public/val/documents",
  * });
  * export default c.define("/content/documents.val.ts", schema, {
  *   "/public/val/documents/report.pdf": {
@@ -53,5 +53,5 @@ type FilesItemSrc = {
  * });
  * ```
  */
-export declare const files: (options: FilesOptions) => RecordSchema<ObjectSchema<FilesItemProps, FilesItemSrc>, Schema<string>, Record<string, FilesEntryMetadata>>;
+export declare const fileset: (options: FilesetOptions) => RecordSchema<ObjectSchema<FilesetItemProps, FilesetItemSrc>, Schema<string>, Record<string, FilesetEntryMetadata>>;
 export {};

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

@@ -5,7 +5,7 @@ import type { SerializedSchema } from "./index.js";
  * The one answer to that question. There used to be two — `hasRemoteFileSchema`
  * in the server, gating whether `/save` demands remote credentials, and
  * `findRequiredRemoteFiles` in the Studio, gating the `/remote/settings` fetch —
- * and they disagreed about `s.images({ ... }).remote()`: the Studio's version
+ * and they disagreed about `s.imageset({ ... }).remote()`: the Studio's version
  * counted a remote media record, the server's did not, because a media
  * collection serializes as a `record` of metadata rather than as an image
  * schema.
@@ -43,8 +43,8 @@ export declare function hasRemoteFileSchema(schema: SerializedSchema): boolean;
  *
  * It is a walk over the SERIALIZED schema for the reasons given above, and for
  * one more that is specific to this question: the two cases most likely to be
- * missed are invisible to a value type. A media collection (`s.images()` /
- * `s.files()`) serializes as a record of metadata with no image schema inside
+ * missed are invisible to a value type. A media collection (`s.imageset()` /
+ * `s.fileset()`) serializes as a record of metadata with no image schema inside
  * it, and a richtext inline image lives in a constructor argument. A check
  * written against the item TYPE would silently pass both — and the gallery case
  * already has a data-loss incident attached to it (see above).

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

@@ -5,7 +5,7 @@ import { ValidationError, ValidationErrors } from "./validation/ValidationError.
 import { ValModule } from "../index.js";
 import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
 import { FieldRender } from "../render.js";
-import { ImagesEntryMetadata } from "./images.js";
+import { AltSource, ImagesetEntryMetadata } from "./imageset.js";
 /**
  * How an uploaded image is re-encoded in the browser, before it is uploaded.
  *
@@ -41,7 +41,7 @@ export type GalleryImageOptions = {
     encode?: ImageEncodeOption;
 };
 export type ImageOptions = {
-    directory?: string;
+    dir?: string;
     accept?: string;
     encode?: ImageEncodeOption;
 };
@@ -81,7 +81,7 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     private readonly description?;
     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);
+    constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagesetEntryMetadata<AltSource>>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     /**
      * Describe this field.
      *
@@ -119,7 +119,7 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
      *
      * @example
      * const schema = s
-     *   .image({ accept: "image/webp", directory: "/public/val/images" })
+     *   .image({ accept: "image/webp", dir: "/public/val/images" })
      *   .remote();
      * export default c.define("/example.val.ts", schema, {
      *   path: "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/example.webp",
@@ -163,6 +163,10 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     /**
      * The entries of the gallery this field points at, or null when it is a
      * standalone field.
+     *
+     * `AltSource` rather than a specific alt type: a field never reads an entry's
+     * alt — it carries its own — so it only needs the entry keys and the
+     * dimensions, and a gallery of any alt shape can back it.
      */
     private galleryEntries;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -221,6 +225,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>>, galleryOptions?: GalleryImageOptions): ImageSchema<GalleryImageSource>;
+export declare function image(galleryModule: ValModule<Record<string, ImagesetEntryMetadata<AltSource>>>, 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 → imageset.d.ts}

@@ -1,4 +1,5 @@
 import { Schema } from "./index.js";
+import type { SelectorOfSchema } from "./index.js";
 import type { SerializedRecordSchema } from "./record.js";
 import { RecordSchema } from "./record.js";
 import { ObjectSchema } from "./object.js";
@@ -10,9 +11,43 @@ import type { ImageEncodeOption } from "./image.js";
  */
 export type AltSchema = StringSchema<string> | StringSchema<string | null> | RecordSchema<StringSchema<string>, Schema<string>, Record<string, string>>;
 /**
- * Options for s.images()
+ * What an entry's `alt` holds, for a given `alt` schema.
+ *
+ * This is the schema's own source type, not a second list that has to be kept
+ * in step with `AltSchema`: `s.string()` gives `string`, `s.string().nullable()`
+ * gives `string | null`, and `s.record(s.string())` gives
+ * `Record<string, string>`.
+ */
+export type AltSourceOf<Alt extends AltSchema> = SelectorOfSchema<Alt>;
+/** Every `alt` value any `AltSchema` can produce. */
+export type AltSource = AltSourceOf<AltSchema>;
+/**
+ * Options for s.imageset()
+ */
+export type ImagesetOptions<Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>> = ImagesetOptionsBase<Accept> & ImagesetAltOption<Alt>;
+/**
+ * `alt` is optional only when it is the default schema.
+ *
+ * Naming a different `Alt` and then leaving `alt` out would make the fallback
+ * in `imageset()` a lie — `Alt` would say `s.string()` while the value was a
+ * nullable one. Requiring it in that case is what makes the fallback sound:
+ * the branch that uses it is reachable only when `Alt` IS the default.
  */
-export type ImagesOptions<Accept extends `image/${string}`> = {
+type ImagesetAltOption<Alt extends AltSchema> = [
+    StringSchema<string | null>
+] extends [Alt] ? {
+    /**
+     * Alt text schema. Can be:
+     * - s.string() for required alt text
+     * - s.string().nullable() for optional alt text (default)
+     * - s.record(s.string(), s.string()) for locale-based alt text
+     */
+    alt?: Alt;
+} : {
+    /** Alt text schema — required, because it is not the default one. */
+    alt: Alt;
+};
+type ImagesetOptionsBase<Accept extends `image/${string}`> = {
     /**
      * The accepted mime type pattern. Must be an image type (e.g., "image/png", "image/webp", "image/*")
      * @default "image/*"
@@ -27,14 +62,7 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
      * gallery that had simply not said where it wanted its files silently shared a
      * directory with every other one.
      */
-    directory: "/public" | `/public/${string}`;
-    /**
-     * Alt text schema. Can be:
-     * - s.string() for required alt text
-     * - s.string().nullable() for optional alt text (default)
-     * - s.record(s.string(), s.string()) for locale-based alt text
-     */
-    alt?: AltSchema;
+    dir: "/public" | `/public/${string}`;
     /**
      * Re-encode uploads in the browser before they are uploaded.
      *
@@ -44,30 +72,35 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
     encode?: ImageEncodeOption;
 };
 /**
- * Metadata for an image entry in the images record
+ * Metadata for an image entry in the images record.
+ *
+ * `alt` follows the schema's `alt` option, so it defaults to `string | null`
+ * and becomes `string` under `s.string()` or `Record<string, string>` under
+ * `s.record(s.string())`. Write `ImagesetEntryMetadata<AltSource>` where a
+ * gallery of any alt shape is acceptable.
  */
-export type ImagesEntryMetadata = {
+export type ImagesetEntryMetadata<Alt extends AltSource = string | null> = {
     width: number;
     height: number;
     mimeType: string;
-    alt: string | null;
+    alt: Alt;
     hotspot?: {
         x: number;
         y: number;
     };
 };
-export type SerializedImagesSchema = SerializedRecordSchema;
-type ImagesItemProps = {
+export type SerializedImagesetSchema = SerializedRecordSchema;
+type ImagesetItemProps<Alt extends AltSchema> = {
     width: NumberSchema<number>;
     height: NumberSchema<number>;
     mimeType: StringSchema<string>;
-    alt: StringSchema<string | null>;
+    alt: Alt;
 };
-type ImagesItemSrc = {
+type ImagesetItemSrc<Alt extends AltSchema> = {
     width: number;
     height: number;
     mimeType: string;
-    alt: string | null;
+    alt: AltSourceOf<Alt>;
 };
 /**
  * Define a collection of images.
@@ -78,9 +111,9 @@ type ImagesItemSrc = {
  *
  * @example
  * ```typescript
- * const schema = s.images({
+ * const schema = s.imageset({
  *   accept: "image/webp",
- *   directory: "/public/val/images",
+ *   dir: "/public/val/images",
  *   alt: s.string().minLength(4),
  * });
  * export default c.define("/content/images.val.ts", schema, {
@@ -93,5 +126,5 @@ type ImagesItemSrc = {
  * });
  * ```
  */
-export declare const images: <Accept extends `image/${string}`>(options: ImagesOptions<Accept>) => RecordSchema<ObjectSchema<ImagesItemProps, ImagesItemSrc>, Schema<string>, Record<string, ImagesEntryMetadata>>;
+export declare const imageset: <Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>>(options: ImagesetOptions<Accept, Alt>) => RecordSchema<ObjectSchema<ImagesetItemProps<Alt>, ImagesetItemSrc<Alt>>, Schema<string>, Record<string, ImagesetEntryMetadata<AltSourceOf<Alt>>>>;
 export {};

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

@@ -17,13 +17,14 @@ 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 | SerializedDiscriminatedUnionSchema | SerializedEnumSchema | 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;
@@ -74,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[];
@@ -99,8 +182,38 @@ export declare abstract class Schema<Src extends SelectorSource> {
      * 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.
      *
-     * Declare `.validate(...)` AFTER `.nullable()`: on most schema types a
-     * validator added before it is not carried over.
+     * `.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({

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

@@ -25,6 +25,8 @@ 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.

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/object.d.ts

@@ -102,6 +102,13 @@ export declare class ObjectSchema<Props extends ObjectSchemaProps, Src extends O
     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