@valbuild/core 0.126.0 → 0.127.0

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

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

@@ -152,6 +152,37 @@ RO extends boolean = false> extends Schema<Src> {
      */
     validate(validationFunction: (src: Src) => false | string): RecordSchema<T, K, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    /**
+     * The check that a record with a DECLARED key set holds every one of them.
+     *
+     * `s.record(s.locale(), item)` has one entry per language and
+     * `s.record(s.union(s.literal("a"), s.literal("b")), item)` has both — the
+     * keys are part of the schema either way, so a missing one is a hole in the
+     * content rather than content nobody has written yet. TypeScript already
+     * demanded both keys of the second; this is the validator catching up, which
+     * is why the two now behave the same.
+     *
+     * Deferred to `resolveSchemaSourceFixes` even for the literal case, where the
+     * keys are known right here: a locale record's keys are in another file, and
+     * one code path for both is one message, one fix and one thing to be wrong.
+     */
+    private getDeclaredKeysValidation;
+    /**
+     * The key set this record's schema declares, computed once.
+     *
+     * `declaredKeySetOf` reads a SERIALIZED schema, and serializing the key
+     * schema walks it — twice per validate, and once per record instance, for an
+     * answer that is a property of the schema and cannot move between them. A
+     * schema is built once and validated against many times, so the walk happens
+     * on the first question and not on any after it.
+     */
+    private declaredKeys;
+    private declaredKeySet;
+    protected opensLocaleScope(): "field" | "key" | null;
+    protected localeScopeChildren(): {
+        key: string;
+        schema: Schema<SelectorSource>;
+    }[];
     private isRemoteUrl;
     /** Marks the validation errors reported at `path` as key errors (in place). */
     private markKeyErrorsAtPath;
@@ -344,6 +375,25 @@ RO extends boolean = false> extends Schema<Src> {
      */
     render(input: FieldRender): RecordSchema<T, K, Src>;
 }
-export declare function record<K extends Schema<string>, S extends Schema<SelectorSource>>(key: K, schema: S): RecordSchema<S, K, Record<SelectorOfSchema<K>, SelectorOfSchema<S>>>;
+/**
+ * The source of a record, given what its key schema says about its keys.
+ *
+ * A key schema that ENUMERATES its keys (a union of literals, or `s.locale()`)
+ * makes every one of them an entry of the record, and an entry nobody has
+ * written yet is `null` rather than absent — so the value type widens by
+ * `null`. That is the whole of option F at the type level: a half-translated
+ * record is a record with nulls in it, which is data you can count, filter and
+ * see in a diff, rather than keys that are simply not there.
+ *
+ * For a union of literals TypeScript already required every key, since
+ * `SelectorOfSchema<K>` is the literal union itself. `s.locale()` is a flavoured
+ * string, so it requires nothing here and the requirement is the validator's —
+ * deliberately: which languages exist is in the settings module, where the
+ * project can change it without a deploy.
+ */
+export type RecordSrcOf<K extends Schema<string>, S extends Schema<SelectorSource>> = K extends {
+    __declaresRecordKeys: true;
+} ? Record<SelectorOfSchema<K>, SelectorOfSchema<S> | null> : Record<SelectorOfSchema<K>, SelectorOfSchema<S>>;
+export declare function record<K extends Schema<string>, S extends Schema<SelectorSource>>(key: K, schema: S): RecordSchema<S, K, RecordSrcOf<K, S>>;
 export declare function record<S extends Schema<SelectorSource>>(schema: S): RecordSchema<S, Schema<string>, Record<string, SelectorOfSchema<S>>>;
 export {};

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

@@ -38,6 +38,19 @@ export type SerializedSettingsSchema = {
     readonly?: boolean;
     hidden?: boolean;
     description?: string;
+    /**
+     * Which of Val's sections this is, where it is one.
+     *
+     * The name rather than the rule itself, because the rule is a closure and a
+     * closure does not survive JSON. Val owns both ends — every section's rules
+     * are in {@link sectionValidators} in this file — so the name is enough for
+     * {@link deserializeSchema} to put the same rules back, and a Studio that
+     * does not recognise the name simply runs none (see `sectionValidate`).
+     *
+     * Absent on the settings module itself, which is a bag of sections and has no
+     * rules of its own.
+     */
+    section?: string;
 };
 /**
  * An object whose keys are all optional: absent means unset.
@@ -58,7 +71,47 @@ export declare class SettingsSchema<Src extends {
     private readonly isReadonly;
     private readonly isHidden;
     private readonly description?;
-    constructor(items: Record<string, Schema<SelectorSource>>, opt?: boolean, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    /**
+     * Which section this is, where Val has rules about it beyond its keys.
+     *
+     * Not the `validate` the class deliberately does not offer: that one is the
+     * schema author's, and `s.settings()` takes no arguments to declare it
+     * with. This names a rule Val states about a shape Val owns — no language
+     * declared twice in `locales.available` is true of every project, and
+     * there is nowhere else it can be said. A single value's rules stay on its
+     * own schema; this is for the ones that need to see more than one value,
+     * or to report on a row of a list.
+     *
+     * A NAME rather than the function, so it survives serialization: the schema
+     * reaches the Studio's validation worker as JSON, and a closure would be
+     * dropped on the way — which is how these rules once went missing there.
+     */
+    private readonly section?;
+    constructor(items: Record<string, Schema<SelectorSource>>, opt?: boolean, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, 
+    /**
+     * Which section this is, where Val has rules about it beyond its keys.
+     *
+     * Not the `validate` the class deliberately does not offer: that one is the
+     * schema author's, and `s.settings()` takes no arguments to declare it
+     * with. This names a rule Val states about a shape Val owns — no language
+     * declared twice in `locales.available` is true of every project, and
+     * there is nowhere else it can be said. A single value's rules stay on its
+     * own schema; this is for the ones that need to see more than one value,
+     * or to report on a row of a list.
+     *
+     * A NAME rather than the function, so it survives serialization: the schema
+     * reaches the Studio's validation worker as JSON, and a closure would be
+     * dropped on the way — which is how these rules once went missing there.
+     */
+    section?: string | undefined);
+    /**
+     * This section's rules, or `undefined` where there are none to run.
+     *
+     * A name this Val does not know means a schema written by a newer one. Its
+     * per-field validation still runs; only the section's own rule is missed,
+     * which is the mild half of the failure and better than refusing the schema.
+     */
+    private sectionValidate;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): SettingsSchema<Src | null>;

package/dist/declarations/src/schema/validation/ValidationFix.d.ts

@@ -1,2 +1,2 @@
-export declare const ValidationFix: readonly ["image:add-metadata", "image:check-metadata", "image:upload-remote", "image:download-remote", "image:check-remote", "images:check-remote", "images:upload-remote", "file:add-metadata", "file:check-metadata", "file:upload-remote", "file:download-remote", "file:check-remote", "files:check-remote", "files:upload-remote", "keyof:check-keys", "router:check-route", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry", "external:upload"];
+export declare const ValidationFix: readonly ["image:add-metadata", "image:check-metadata", "image:upload-remote", "image:download-remote", "image:check-remote", "images:check-remote", "images:upload-remote", "file:add-metadata", "file:check-metadata", "file:upload-remote", "file:download-remote", "file:check-remote", "files:check-remote", "files:upload-remote", "keyof:check-keys", "router:check-route", "locale:check-locale", "images:check-unique-folder", "files:check-unique-folder", "images:check-all-files", "files:check-all-files", "jsonValues:extract-entry", "record:fill-keys", "external:upload"];
 export type ValidationFix = (typeof ValidationFix)[number];

package/dist/declarations/src/source/settings.d.ts

@@ -22,6 +22,41 @@
  */
 export type SettingsSource = {
     assistant?: AssistantSettingsSource;
+    locales?: LocalesSettingsSource;
+};
+/**
+ * The languages this project publishes.
+ *
+ * Content rather than configuration, and deliberately: which languages a site
+ * has is a decision the people who write it make, and under a build-time
+ * constant it took a developer and a deploy. It is the same move `assistant`
+ * makes with `enabled`.
+ *
+ * Val ships no list of its own. A project with no `locales` section has not
+ * said it is translated, and nothing about locales appears anywhere — no picker
+ * in the Studio, no checks, nothing.
+ *
+ * **This list is a decision with a blast radius.** Every locale in content is
+ * checked against it, so removing one invalidates the content that uses it, and
+ * adding one leaves every locale-keyed record short of a language until it is
+ * filled in. That is the intended behaviour — a language that is declared and
+ * missing everywhere is worth being told about — but it is why the Studio warns
+ * before saving a removal rather than treating this as an ordinary field.
+ *
+ * There is no default language, deliberately. Every locale-specific field asks
+ * which language it is in, and a default is exactly the answer that lets that
+ * question go unanswered — content ends up filed under a language nobody chose,
+ * which is the state translation is meant to make visible.
+ */
+export type LocalesSettingsSource = {
+    /**
+     * The languages, as canonical BCP 47 tags: `en-US`, `nb-NO`.
+     *
+     * Order is the project's own, and it is kept: it decides the order of the
+     * Studio's picker and of the rows in a locale-keyed record, so a project can
+     * put the language it works in first.
+     */
+    available?: string[] | null;
 };
 /**
  * The assistant: whether editors have one, and what it is told about the
@@ -55,6 +90,22 @@ export type AssistantSettingsSource = {
      * `glossary`) rather than a field that looks like it should absorb them.
      */
     tone?: string | null;
+    /**
+     * How to translate into each language, keyed by language.
+     *
+     * Per language rather than one field, because translation rules are per
+     * language: bokmål or nynorsk, `du` or `De`, which product names stay in
+     * English. Only the target language's note is sent, so a French rule does not
+     * ride along in a Norwegian request.
+     *
+     * Keyed by language, so it holds every one of them once it exists at all —
+     * `null` where a language needs no special instruction, which is most of them.
+     * That is the same rule every locale-keyed record follows (see
+     * `declaredKeys.ts`): a gap you can count and see in a diff, rather than a key
+     * that is simply not there. A project with no notes at all leaves the whole
+     * field unset and nothing is required.
+     */
+    translation?: Record<string, string | null> | null;
 };
 /**
  * The cap on each of the assistant's prose fields, in characters.