@valbuild/core 0.126.0 → 0.128.0

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

@@ -11,7 +11,7 @@ import type { ImageEncodeOption } from "./image.js";
 type MediaOptions = {
     type: "files" | "images";
     accept: string;
-    directory: string;
+    dir: string;
     remote: boolean;
     altSchema?: Schema<SelectorSource>;
     /** Images only: how uploads are re-encoded in the browser. See `image.ts`. */
@@ -34,7 +34,7 @@ export type SerializedRecordSchema = {
     customValidate?: boolean;
     mediaType?: "files" | "images";
     accept?: string;
-    directory?: string;
+    dir?: string;
     remote?: boolean;
     encode?: ImageEncodeOption;
     alt?: SerializedSchema;
@@ -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;
@@ -198,7 +229,7 @@ RO extends boolean = false> extends Schema<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
+     * For `s.imageset()` and `s.fileset()`, 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
@@ -207,7 +238,7 @@ RO extends boolean = false> extends Schema<Src> {
      * upload it and rewrite the key.
      *
      * @example
-     * const schema = s.images({ directory: "/public/val/images" }).remote();
+     * const schema = s.imageset({ dir: "/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":
      *     {
@@ -226,7 +257,7 @@ RO extends boolean = false> extends Schema<Src> {
      * which lets the runtime, the Studio and validation work one entry at a time
      * so a record/router can scale to many thousands of entries.
      *
-     * Not supported on image/file galleries (`s.images()` / `s.files()`).
+     * Not supported on image/file galleries (`s.imageset()` / `s.fileset()`).
      *
      * Only supported on a module's ROOT record/router — a `.jsonValues()` record
      * nested inside an object/array/record is rejected at startup with a module
@@ -253,7 +284,7 @@ RO extends boolean = false> extends Schema<Src> {
      * bucket — instead of in the module.
      *
      * Available on every record-derived schema, which is `s.record()`,
-     * `s.router()`, `s.images()` and `s.files()` alike: a router is a
+     * `s.router()`, `s.imageset()` and `s.fileset()` alike: a router is a
      * `RecordSchema` with a `ValRouter`, a gallery one with media options, so all
      * four get external storage from this one method.
      *
@@ -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.