@valbuild/core 0.125.0 → 0.127.0

package/CHANGELOG.md

@@ -1,5 +1,304 @@
 # @valbuild/core
 
+## 0.127.0
+
+### Minor Changes
+
+- [#608](https://github.com/valbuild/val/pull/608) [`7fa8699`](https://github.com/valbuild/val/commit/7fa869974bc895af992a7d5c18b76253636d7d65) Thanks [@freekh](https://github.com/freekh)! - A record whose schema declares its keys now holds every one of them.
+
+  Two key schemas enumerate their keys: `s.locale()`, whose set is the project's
+  `locales.available`, and a union of literals. For those, the keys are part of the
+  schema, so a missing one is a hole in the content rather than content nobody has
+  written yet — and validation now says so, naming what is missing.
+
+  ```typescript
+  s.record(s.locale(), s.object({ title: s.string() }));
+  // Missing key: 'nb-NO'. This record's keys are declared by its schema, so
+  // every one of them is an entry — an entry nobody has written yet is null,
+  // not absent.
+  ```
+
+  **An entry nobody has written yet is `null`.** Not an absent key: a null entry is
+  data you can count, filter and see in a diff, and it means half-translated
+  content stays _valid_ rather than blocking a publish. The value type of such a
+  record widens by `null` to match, so writing one in a `.val.ts` type-checks:
+
+  ```typescript
+  c.define(
+    "/content/jacket.val.ts",
+    s.record(s.locale(), s.object({ title: s.string() })),
+    {
+      "en-US": { title: "Winter jacket" },
+      "nb-NO": null, // nobody has translated this yet
+    },
+  );
+  ```
+
+  **This changes `s.record(s.union(...), item)`**, and closes a gap that was
+  already there: `s.record(s.union(s.literal("a"), s.literal("b")), item)` types as
+  `Record<"a" | "b", T>`, so TypeScript demanded both keys while the validator only
+  checked the ones present. It now checks them too, and — as above — accepts `null`
+  for an entry that has not been filled in. If you have such a record with keys
+  missing, validation will report them; adding the keys with `null` values is the
+  fix, and creating one from the Studio does it for you.
+
+  `emptyOf` creates these records with every key already in them rather than
+  empty, since an empty one is already missing keys. In the Studio use the
+  `useEmptyOf()` hook rather than importing `emptyOf` directly: a locale record's
+  keys are in the settings module, and the hook is what has read it.
+
+- [#608](https://github.com/valbuild/val/pull/608) [`5b7fe05`](https://github.com/valbuild/val/commit/5b7fe05cec6365f9cd1de9ba31e65ed4a87edb63) Thanks [@freekh](https://github.com/freekh)! - `s.locale()`: one of the project's languages.
+
+  The languages themselves are declared in the settings module (`locales.available`);
+  this says that a value is one of them.
+
+  ```typescript
+  // a field: everything in this entry is in this language
+  s.record(s.string(), s.object({ locale: s.locale(), title: s.string() }));
+
+  // a key: one entry per language
+  s.record(s.locale(), s.object({ title: s.string() }));
+  ```
+
+  Every locale in content is checked against the project's list, the way `keyOf`
+  and `route` are checked against what they point at. An undeclared language names
+  the ones the project has; a project that has declared none is told to declare
+  them rather than told the value is wrong.
+
+  A locale is stored as the tag itself — the value in content is `nb-NO`, and a
+  record keyed by `s.locale()` has `nb-NO` as its key. Spelling one differently
+  where it is stored (`/no/…` as a URL segment) is a real need and is deliberately
+  not in this release: it changes what is accepted as well as what is shown, so it
+  is being designed on its own rather than folded in here.
+
+  A locale is **never stega encoded**: it ends up in `<html lang>`, in `hreflang`
+  and in `Intl` constructors, none of which survive invisible characters.
+
+  `assistant.translation` joins the settings module alongside `context` and `tone`
+  — a note per language, keyed by language, so only the target language's rules are
+  sent when translating into it.
+
+- [#608](https://github.com/valbuild/val/pull/608) [`88262ac`](https://github.com/valbuild/val/commit/88262ac8db068650a664981ef73556457d87741a) Thanks [@freekh](https://github.com/freekh)! - Locale scopes: a subtree in one language, and one function that answers which.
+
+  A **locale scope** is content governed by a single language. Two things open one
+  today (a third, locale segments in routes, follows):
+
+  ```typescript
+  // a locale field: this object and everything below it is in one language
+  s.object({ locale: s.locale(), title: s.string(), body: s.richtext() });
+
+  // a locale-keyed record: each entry is in the language its key names
+  s.record(s.locale(), s.object({ title: s.string() }));
+  ```
+
+  **A scope may not contain another scope**, and an object may have only one
+  locale field. Both are reported as schema errors, naming what to move:
+
+  ```
+  An object can be in one language, so it can have one locale field.
+  Found 'locale', 'language'.
+
+  Everything here is already in one language, so 'byLanguage' cannot set
+  another. Move the locale-keyed record out of this object, or take the outer
+  one away.
+  ```
+
+  A scope three levels deep is reported once, by the scope immediately enclosing
+  it, rather than by every ancestor.
+
+  The rule is **validated rather than typed**. Expressing "no scope below this
+  one" as a type constraint means threading it through every schema class's type
+  parameter, and the errors a recursive constraint like that produces name the
+  whole tree — an unrelated typo in a `.val.ts` would print pages.
+
+  `localeAt(path, snapshot)` (from `@valbuild/shared/internal`) answers which
+  language governs a path, and is the one implementation of that question, so the
+  Studio, the server and the validation worker cannot disagree. It returns the
+  tag, which is what `<html lang>`, `Intl` and `locales.available` all want.
+
+  It answers `null` where no scope governs the path, where the project has
+  declared no languages, and where a locale field holds something that is not one
+  of them — validation is already reporting the last, and guessing would put a
+  language in `<html lang>` that nobody chose.
+
+- [#608](https://github.com/valbuild/val/pull/608) [`29811c3`](https://github.com/valbuild/val/commit/29811c3f8c7e001a950e6f4833af6888e6a4efea) Thanks [@freekh](https://github.com/freekh)! - Settings: declare the languages a project publishes.
+
+  A new `locales` section in the settings module says which languages a project
+  has:
+
+  ```typescript
+  export default c.define("/settings.val.ts", s.settings(), {
+    locales: {
+      available: ["en-US", "fr-FR", "nb-NO"],
+    },
+  });
+  ```
+
+  The order is the project's own and is kept rather than sorted: it is the order
+  of the Studio's locale picker and of the rows in a locale-keyed record. There
+  is no default language — every locale-specific field asks which language it is
+  in, and a default is the answer that lets that question go unanswered.
+
+  Like every other settings section it is optional, so a project that is not
+  translated writes nothing and sees nothing: no locale controls appear anywhere
+  until `available` has something in it.
+
+  This is 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`
+  already makes with `enabled`.
+
+  Tags are BCP 47 (`en-US`, `nb-NO`), checked through `Intl.getCanonicalLocales` —
+  the same implementation `<html lang>` and every `Intl` constructor use — and
+  they have to be in canonical form. `nb-no` parses, but nothing else in the stack
+  agrees it is the same string as `nb-NO`, and a locale is compared as a string
+  everywhere it is used. Validation names the spelling to use, and reports a
+  language declared twice on the repeat rather than on the list — that is the row
+  to delete, and a message on the list itself would not say which.
+
+  Edited under Settings → Locales in the Studio, which names each language in its
+  own language.
+
+### Patch Changes
+
+- [#665](https://github.com/valbuild/val/pull/665) [`7072e07`](https://github.com/valbuild/val/commit/7072e07623c953a09ac14388ae22dada0b431ce3) Thanks [@freekh](https://github.com/freekh)! - `.nullable()` no longer drops the field's `.validate(...)` functions.
+
+  `.nullable()` returns a copy of the schema, and most of the schema classes built
+  that copy with an empty list of custom validators — so a validator declared
+  before the `.nullable()` was silently thrown away:
+
+  ```ts
+  s.number()
+    .validate((n) => (n > 100 ? "Too big" : false))
+    .nullable(); // the validator never ran
+  ```
+
+  `array`, `object`, `discriminatedUnion`, `enum`, `number`, `boolean`, `literal`,
+  `keyOf`, `date`, `dateTime`, `code`, `color` and `richtext` were affected;
+  `string`, `record`, `route`, `file` and `image` already carried them over, which
+  is why the bug was easy to miss. Validators now survive `.nullable()` on every
+  schema, in either order.
+
+  A validator on a nullable schema is called with `null` when the value is unset,
+  rather than being skipped — the same thing the schemas that never dropped them
+  have always done. If yours was written before the `.nullable()`, its argument is
+  typed as non-null even though `null` can reach it, so guard for it.
+
+## 0.126.0
+
+### Minor Changes
+
+- [#652](https://github.com/valbuild/val/pull/652) [`f2fe70d`](https://github.com/valbuild/val/commit/f2fe70dab2b65000dfaf289f09c70b4a8291467a) Thanks [@freekh](https://github.com/freekh)! - `s.union` is now `s.discriminatedUnion` and `s.enum`.
+
+  `s.union` did two unrelated jobs and worked out which one you meant from its
+  first argument: a string key meant a tagged union of objects, literal schemas
+  meant a set of allowed strings. Those are now two schemas with two names.
+
+  ```ts
+  // A fixed set of strings — presents as a dropdown
+  s.enum("primary", "secondary", "ghost"); // Schema<"primary" | "secondary" | "ghost">
+
+  // One of several object shapes, told apart by a tag field
+  s.discriminatedUnion(
+    "type",
+    s.object({ type: s.literal("hero"), heading: s.string() }),
+    s.object({ type: s.literal("quote"), text: s.string() }),
+  );
+  ```
+
+  `s.enum` takes the strings directly, so the `s.literal(...)` wrapper is gone.
+
+  **`s.union` still works** — it is deprecated, and it builds exactly the schema
+  above, so nothing has to change today:
+
+  ```ts
+  s.union(s.literal("one"), s.literal("two")); // → s.enum("one", "two")
+  s.union("type", pageA, pageB); // → s.discriminatedUnion("type", pageA, pageB)
+  ```
+
+  The two are different kinds of node, and that is the reason for the split. A
+  discriminated union is a container: the selected variant's fields are the fields
+  being edited, and everything that walks a schema descends through it. An enum is
+  a leaf — a string with a closed domain — so nothing recurses into it. Told apart
+  only by the shape of `key`, every consumer had to re-derive which one it was
+  holding; each now has its own serialized type (`"discriminated-union"` and
+  `"enum"`) and Val Studio has a field per kind rather than one field that
+  branches.
+
+  Two behaviour changes fall out of the split, both of them fixes:
+
+  - A value that is not a string at all now fails an enum's validation with a
+    type error. `s.union` of literals only ever checked the value against its
+    literals when the value WAS a string, so a number or an object where an enum
+    was declared validated clean.
+  - An enum field now shows its validation errors in Val Studio where the field
+    is opened on its own — the module editor and the canvas's fields column — and
+    gets the compact error layout inside an inline list row. It is a leaf now, so
+    it goes through the same error rendering as every other leaf field; the string
+    union bypassed it and showed nothing in those places.
+
+  Several latent crashes in the old `s.union` are fixed on the way past, all of
+  them cases where it threw a `TypeError` instead of reporting:
+
+  - A required discriminated union holding `null` now reports a type error rather
+    than throwing, and resolving a path underneath a nullable one that is `null`
+    gives the error the API promises instead of a crash.
+  - `s.literal("")` is a legal discriminator tag, and `s.enum("")` a legal value.
+    Both used to be treated as absent by a truthiness check — in path resolution,
+    in stega encoding, and in the message that lists a union's valid tags. The
+    editor's dropdowns handle them too: an empty value is reserved by the select
+    component and had to be mapped around.
+  - A variant that omits the discriminator entirely is now reported as the schema
+    error it is, instead of throwing while the check looked for it.
+  - An enum's value is now indexed for search, like every other string leaf. The
+    old string union was never indexed at all, so searching for one of its values
+    could not find the field.
+  - A nullable discriminated union set to `null` no longer renders a spinner that
+    never resolves.
+
+  `s.discriminatedUnion` also requires at least one variant, as `s.enum` requires
+  at least one value: a union with nothing to select is not a thing to write, and
+  everything downstream reads the first variant where it needs any.
+
+  If you read serialized schemas yourself, that is the breaking part: `type` is no
+  longer `"union"`, an enum carries `values: string[]` instead of a `key` plus
+  `items` of literal schemas, and `UnionSchema` is no longer a class.
+  `SerializedUnionSchema`, `SerializedStringUnionSchema`,
+  `SerializedObjectUnionSchema` and `UnionSchema` remain as deprecated type
+  aliases.
+
+### Patch Changes
+
+- [#661](https://github.com/valbuild/val/pull/661) [`171208a`](https://github.com/valbuild/val/commit/171208a20177e68ed5a8b1a6fdaabfe893a6aa5f) Thanks [@freekh](https://github.com/freekh)! - Every schema method now has a worked `@example` in its JSDoc, so hovering it in
+  your editor shows what to write.
+
+  That covers the whole builder surface — `.describe()`, `.validate()`,
+  `.nullable()`, `.readonly()`, `.hidden()`, `.preview()`, `.render()`, and the
+  per-type methods such as `.minLength()`, `.regexp()`, `.raw()`, `.multiline()`,
+  `.from()` / `.to()`, `.remote()`, `.jsonValues()` and `.external()` — as well as
+  `c.define()`, `c.json()`, `c.external()` and the `val` helpers (`val.attrs`,
+  `val.raw`, `val.unstable_getPath` and friends).
+
+  One of the examples corrected a real trap: a custom validator returns
+  `false | string`, so the natural-looking
+
+  ```ts
+  s.string().validate((val) => val.trim() === val || "No surrounding spaces");
+  ```
+
+  does not type check — `||` yields `true`, and `true` is not one of the two
+  answers. Write it as a ternary instead:
+
+  ```ts
+  s.string().validate((val) =>
+    val.trim() === val ? false : "No surrounding spaces",
+  );
+  ```
+
+  The examples are checked in CI, not just written: one test asks the TypeScript
+  checker for the doc each method actually resolves to and fails if it has no
+  `@example`, and another compiles every example it finds.
+
 ## 0.125.0
 
 ### Minor Changes

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

@@ -54,8 +54,12 @@ export { type SerializedImageSchema, ImageSchema } from "./schema/image.js";
 export { type SerializedFileSchema, FileSchema } from "./schema/file.js";
 export { type SerializedDateSchema, DateSchema } from "./schema/date.js";
 export { type SerializedSettingsSchema, SettingsSchema, } from "./schema/settings.js";
-export { type SettingsSource, type AssistantSettingsSource, type AssistantAvailability, ASSISTANT_SETTINGS_MAX_LENGTH, assistantAvailability, } from "./source/settings.js";
+export { type SettingsSource, type AssistantSettingsSource, type LocalesSettingsSource, type AssistantAvailability, ASSISTANT_SETTINGS_MAX_LENGTH, assistantAvailability, } from "./source/settings.js";
 export { type ResolvedSettingsModule, SETTINGS_MODULE_CONVENTION, isRootModuleFilePath, resolveSettingsModule, } from "./settingsModule.js";
+export { type Locale, localeTagError, localeOfValue } from "./locale.js";
+export { type SerializedLocaleSchema, LocaleSchema } from "./schema/locale.js";
+export { type DeclaredKeySet, declaredKeySetOf, missingDeclaredKeys, } from "./schema/declaredKeys.js";
+export { discriminatedUnionBranchOf } from "./schema/discriminatedUnionBranch.js";
 export { type SerializedColorSchema, type ColorOptions, ColorSchema, } from "./schema/color.js";
 export { type SerializedCodeSchema, type CodeOptions, type CodeLanguage, CodeSchema, CODE_LANGUAGES, } from "./schema/code.js";
 export { type ColorFormat, type ParsedColor, COLOR_FORMATS, DEFAULT_COLOR_FORMAT, } from "./schema/colorFormat.js";
@@ -63,7 +67,9 @@ export { type SerializedDateTimeSchema, DateTimeSchema, } from "./schema/datetim
 export { type SerializedKeyOfSchema, KeyOfSchema } from "./schema/keyOf.js";
 export { type SerializedRouteSchema, RouteSchema } from "./schema/route.js";
 export { type SerializedRichTextSchema, RichTextSchema, } from "./schema/richtext.js";
-export { type SerializedUnionSchema, UnionSchema, type SerializedStringUnionSchema, type SerializedObjectUnionSchema, } from "./schema/union.js";
+export { type SerializedDiscriminatedUnionSchema, type DiscriminatedUnionSourceOf, DiscriminatedUnionSchema, } from "./schema/discriminatedUnion.js";
+export { type SerializedEnumSchema, EnumSchema } from "./schema/enum.js";
+export { type SerializedUnionSchema, type UnionSchema, type SerializedStringUnionSchema, type SerializedObjectUnionSchema, } from "./schema/union.js";
 export { type SerializedLiteralSchema, LiteralSchema } from "./schema/literal.js";
 export { deserializeSchema } from "./schema/deserialize.js";
 export { type PreviewItem, type ItemPreviewInput, type RecordPreview, type ArrayPreview, type ReifiedPreview, type PreviewScope, previewScope, } from "./preview.js";

package/dist/declarations/src/initSchema.d.ts

@@ -4,6 +4,8 @@ import { object } from "./schema/object.js";
 import { string } from "./schema/string.js";
 import { boolean } from "./schema/boolean.js";
 import { union } from "./schema/union.js";
+import { discriminatedUnion } from "./schema/discriminatedUnion.js";
+import { enumSchema } from "./schema/enum.js";
 import { richtext } from "./schema/richtext.js";
 import { image } from "./schema/image.js";
 import { literal } from "./schema/literal.js";
@@ -15,6 +17,7 @@ import { date } from "./schema/date.js";
 import { datetime } from "./schema/datetime.js";
 import { code } from "./schema/code.js";
 import { color } from "./schema/color.js";
+import { locale } from "./schema/locale.js";
 import { route } from "./schema/route.js";
 import { router } from "./schema/router.js";
 import { images } from "./schema/images.js";
@@ -67,32 +70,58 @@ export type InitSchema = {
      */
     readonly number: typeof number;
     /**
-     * Define a union.
+     * Define one of several object shapes, told apart by a tag field.
      *
-     * @example // union of string literals
-     * const schema = s.union(s.literal("test"), s.literal("test2"));
-     * export default c.define("/example.val.ts", schema, "test");
+     * The first argument names the field that carries the tag; every object must
+     * set it to a distinct `s.literal(...)`. The editor shows a dropdown of the
+     * tags and the fields of whichever one is selected.
      *
-     * @example // union of string literals
-     * const schema = s.union("type", s.object({
-     *   type: s.literal("test"),
-     *   value: s.string()
-     * }), s.object({
-     *   type: s.literal("test2"),
-     *   value: s.string()
-     * }));
+     * @example
+     * const schema = s.discriminatedUnion("type",
+     *   s.object({ type: s.literal("text"), value: s.string() }),
+     *   s.object({ type: s.literal("image"), value: s.image() }),
+     * );
      * export default c.define("/example.val.ts", schema, {
-     *   type: "test",
+     *   type: "text",
      *   value: "test"
      * });
      *
      */
+    readonly discriminatedUnion: typeof discriminatedUnion;
+    /**
+     * Define a string that must be one of a fixed set of values.
+     *
+     * The editor shows a dropdown of the values, in the order they are given.
+     *
+     * @example
+     * const schema = s.enum("primary", "secondary", "ghost");
+     * export default c.define("/example.val.ts", schema, "primary");
+     *
+     */
+    readonly enum: typeof enumSchema;
+    /**
+     * Define a union.
+     *
+     * @deprecated Use `s.discriminatedUnion` for a tagged union of objects, or
+     * `s.enum` for one of a fixed set of strings.
+     *
+     * @example // was: a union of string literals
+     * const schema = s.enum("test", "test2");
+     *
+     * @example // was: a tagged union of objects
+     * const schema = s.discriminatedUnion("type",
+     *   s.object({ type: s.literal("test"), value: s.string() }),
+     *   s.object({ type: s.literal("test2"), value: s.string() }),
+     * );
+     *
+     */
     readonly union: typeof union;
     /**
      * Define a rich text.
      *
      * @example
-     * const schema = s.richtext();
+     * // Every tag and style is off until the options ask for it.
+     * const schema = s.richtext({ h1: true, bold: true });
      * export default c.define("/example.val.ts", schema, [
      *   { tag: "h1", children: ["Title 1"] },
      * ]);
@@ -119,6 +148,7 @@ export type InitSchema = {
      *
      * @example
      * // Backed by a gallery: width, height and mimeType live there.
+     * import galleryVal from "./gallery.val"; // an s.images() module
      * const schema = s.image(galleryVal);
      * export default c.define("/example.val.ts", schema, {
      *   path: "/public/val/example.png",
@@ -237,6 +267,20 @@ export type InitSchema = {
      * ```
      */
     readonly route: typeof route;
+    /**
+     * 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, which is
+     * checked against that list.
+     *
+     * @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() }));
+     */
+    readonly locale: typeof locale;
     /**
      * Create a page router.
      * Each key is the path of the page.
@@ -346,7 +390,9 @@ export declare function initSchema(): {
         max?: number;
         min?: number;
     }) => import("./index.js").NumberSchema<number>;
-    union: <Key extends string | import("./schema/index.js").Schema<string>, T extends import("./schema/index.js").Schema<Key extends string ? import("./source/index.js").SourceObject & { [k in Key]: string; } : Key extends import("./schema/index.js").Schema<string> ? string : unknown>[]>(key: Key, ...objects: T) => import("./index.js").UnionSchema<Key, T, T extends import("./schema/index.js").Schema<infer S extends import("./selector/index.js").SelectorSource>[] ? S extends import("./selector/index.js").SelectorSource ? S | (Key extends import("./schema/index.js").Schema<infer K extends import("./selector/index.js").SelectorSource> ? K : never) : never : never>;
+    discriminatedUnion: <Key extends string, T extends import("./schema/discriminatedUnion.js").DiscriminatedUnionItems<Key>>(key: Key, ...objects: T) => import("./index.js").DiscriminatedUnionSchema<Key, T, import("./index.js").DiscriminatedUnionSourceOf<Key, T>>;
+    enum: <T extends string>(values_0: T, ...values: T[]) => import("./index.js").EnumSchema<T>;
+    union: typeof union;
     richtext: <O extends import("./index.js").RichTextOptions>(options?: O) => import("./index.js").RichTextSchema<O, import("./index.js").RichTextSource<O>>;
     image: typeof image;
     literal: <T extends string>(value: T) => import("./index.js").LiteralSchema<T>;
@@ -362,6 +408,7 @@ export declare function initSchema(): {
     datetime: (options?: Record<string, never>) => import("./index.js").DateTimeSchema<import("./index.js").RawString>;
     color: (options?: import("./index.js").ColorOptions) => import("./index.js").ColorSchema<import("./index.js").RawString>;
     code: (options?: import("./index.js").CodeOptions) => import("./index.js").CodeSchema<import("./index.js").RawString>;
+    locale: () => import("./index.js").LocaleSchema<string>;
     route: <T extends string>(options?: Record<string, never>) => import("./index.js").RouteSchema<T>;
     router: typeof router;
     images: <Accept extends `image/${string}`>(options: import("./schema/images.js").ImagesOptions<Accept>) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{

package/dist/declarations/src/initVal.d.ts

@@ -4,11 +4,71 @@ import { getValPath as getPath } from "./val/index.js";
 import { json } from "./source/json.js";
 import { external } from "./source/external.js";
 export type ContentConstructor = {
+    /**
+     * Define a content module: a schema, and source that matches it.
+     *
+     * The first argument is the module's own file path, starting at the root of
+     * the project. It has to match the file the call is written in - that is how
+     * the Studio, validation and patching find the module again - so a
+     * `c.define` is always the default export of one `*.val.ts` file.
+     *
+     * @example
+     * const schema = s.object({ title: s.string() });
+     * export default c.define("/content/page.val.ts", schema, {
+     *   title: "Hello",
+     * });
+     */
     define: typeof define;
+    /**
+     * Put one entry of a `.jsonValues()` record in its own `*.val.json` file,
+     * loaded lazily.
+     *
+     * What is written in the module is the `import()` thunk, not the content: the
+     * `.val.ts` stays small, and the runtime, the Studio and validation each work
+     * an entry at a time. That is what lets a record or a router hold many
+     * thousands of entries.
+     *
+     * Only for the entries of a record that said `.jsonValues()`.
+     *
+     * @example
+     * import { nextAppRouter } from "../val.config";
+     * const schema = s
+     *   .router(nextAppRouter, s.object({ title: s.string() }))
+     *   .jsonValues();
+     * export default c.define("/app/support/[slug]/page.val.ts", schema, {
+     *   "/support/faq": c.json(() => import("./content/faq.val.json")),
+     * });
+     */
     json: typeof json;
+    /**
+     * The source of a record whose entries live behind an adapter - a database,
+     * an HTTP API, a bucket - instead of in the module.
+     *
+     * It takes no arguments, and there is nothing to fill in: it says only that
+     * the entries are somewhere else. WHICH adapter is the schema's business
+     * (`.external("posts")`), and the binding is registered where the app is set
+     * up.
+     *
+     * @example
+     * const schema = s.record(s.object({ title: s.string() })).external("posts");
+     * export default c.define("/content/posts.val.ts", schema, c.external());
+     */
     external: typeof external;
 };
 export type ValConstructor = {
+    /**
+     * The source path of a value inside a module, or `undefined` for something
+     * that did not come from Val.
+     *
+     * A path is what every Val API addresses content by, so this is the way from
+     * a value you are holding back to the thing the Studio, a patch or a
+     * validation error names. Unstable: the shape of a path is not part of the
+     * public API yet.
+     *
+     * @example
+     * import pageVal from "./page.val";
+     * const path = val.unstable_getPath(pageVal); // "/page.val.ts"
+     */
     unstable_getPath: typeof getPath;
 };
 export type ConfigDirectory = `/public` | `/public/${string}`;
@@ -39,9 +99,57 @@ export type ValConfig = {
     };
 };
 export type InitVal = {
+    /**
+     * The content constructor: `c.define` for a module, `c.json` and
+     * `c.external` for entries that live outside it.
+     *
+     * @example
+     * const schema = s.object({ title: s.string() });
+     * export default c.define("/content/page.val.ts", schema, {
+     *   title: "Hello",
+     * });
+     */
     c: ContentConstructor;
+    /**
+     * Helpers for working with content your app is already holding, rather than
+     * for declaring it.
+     *
+     * `@valbuild/next` and `@valbuild/tanstack` add to this: `val.attrs` for
+     * visual editing, `val.raw` to strip the stega encoding off a string.
+     *
+     * @example
+     * import pageVal from "./page.val";
+     * const path = val.unstable_getPath(pageVal);
+     */
     val: ValConstructor;
+    /**
+     * The schema constructor: one method per type of content Val can hold.
+     *
+     * @example
+     * const schema = s.object({
+     *   title: s.string().describe("Shown in the browser tab"),
+     *   image: s.image().nullable(),
+     * });
+     * export default c.define("/content/page.val.ts", schema, {
+     *   title: "Hello",
+     *   image: null,
+     * });
+     */
     s: InitSchema;
+    /**
+     * The config this `initVal` was called with, as the rest of Val reads it.
+     *
+     * Exported from `val.config.ts` so that the Val API route and the Studio get
+     * the same object the content modules were built with.
+     *
+     * @example
+     * import { initVal } from "@valbuild/core";
+     * const { s, c, val, config } = initVal({
+     *   project: "myorg/myproject",
+     *   files: { directory: "/public/val" },
+     * });
+     * export { s, c, val, config };
+     */
     config: ValConfig;
 };
 export declare const initVal: (config?: ValConfig) => InitVal;

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

@@ -0,0 +1,55 @@
+/**
+ * Language tags, and what makes one wrong.
+ *
+ * Val does not ship a list of locales. Which languages a project publishes is a
+ * property of that project, so it is declared in the settings module — see
+ * `LocalesSettingsSource` — and everything downstream reads it from there.
+ *
+ * What Val does own is the SPELLING. A tag is checked against BCP 47
+ * (RFC 5646) through `Intl.getCanonicalLocales`, which is the same
+ * implementation the browser, `<html lang>` and every `Intl` constructor use.
+ * Delegating rather than writing a matcher is the point: a tag this accepts is
+ * a tag those accept.
+ */
+/**
+ * What is wrong with `tag` as a language tag, or `false` if nothing is.
+ *
+ * Canonical form, not merely parseable, and the difference is what makes this
+ * worth checking at all. `nb-no` parses; `Intl.DisplayNames` and a
+ * case-sensitive comparison against a stored key do not agree about it. Since a
+ * locale is compared as a string everywhere — a record key, a URL segment, a
+ * value in content — one spelling has to win, and the canonical one is the
+ * spelling every other tool already produces.
+ *
+ * The message names the canonical form where there is one, because "not
+ * canonical" is not an instruction and `nb-NO` is.
+ */
+export declare function localeTagError(tag: string): string | false;
+/**
+ * A language tag, as content holds it.
+ *
+ * A *flavoured* string rather than a union or a strict brand. Which languages a
+ * project has is declared in its settings module, where the project can change
+ * it, so there is no set for a type to enumerate — and a strict brand would make
+ * `"nb-NO"` unassignable, which would mean writing every locale in a `.val.ts`
+ * through a constructor. Content stays plain data.
+ *
+ * So this carries no compile-time guarantee, and is not meant to. It names the
+ * concept where a bare `string` would say nothing, and the guarantee is the
+ * `locale:check-locale` validation against `locales.available`.
+ */
+declare const localeBrand: unique symbol;
+export type Locale = string & {
+    readonly [localeBrand]?: "locale";
+};
+/**
+ * The locale a stored value means, or `null` if it means none of them.
+ *
+ * A lookup against the project's languages, and today that is all it is. It
+ * stays a named function because it is the one place the question is asked —
+ * the Studio, the validation worker and the server all come here rather than
+ * comparing strings themselves, so they cannot disagree about what a stored
+ * value is.
+ */
+export declare function localeOfValue(value: string, available: readonly string[]): string | null;
+export {};