@valbuild/shared 0.126.0 → 0.127.0

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # @valbuild/shared
 
+## 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.
+
+### Patch Changes
+
+- Updated dependencies [[`7fa8699`](https://github.com/valbuild/val/commit/7fa869974bc895af992a7d5c18b76253636d7d65), [`5b7fe05`](https://github.com/valbuild/val/commit/5b7fe05cec6365f9cd1de9ba31e65ed4a87edb63), [`88262ac`](https://github.com/valbuild/val/commit/88262ac8db068650a664981ef73556457d87741a), [`7072e07`](https://github.com/valbuild/val/commit/7072e07623c953a09ac14388ae22dada0b431ce3), [`29811c3`](https://github.com/valbuild/val/commit/29811c3f8c7e001a950e6f4833af6888e6a4efea)]:
+  - @valbuild/core@0.127.0
+
 ## 0.126.0
 
 ### Minor Changes

package/dist/declarations/src/internal/ApiRoutes.d.ts

@@ -948,7 +948,7 @@ export declare const Api: {
                             message: z.ZodString;
                             value: z.ZodOptional<z.ZodUnknown>;
                             fatal: z.ZodOptional<z.ZodBoolean>;
-                            fixes: z.ZodOptional<z.ZodArray<z.ZodType<"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", unknown, z.core.$ZodTypeInternals<"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", unknown>>>>;
+                            fixes: z.ZodOptional<z.ZodArray<z.ZodType<"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", unknown, z.core.$ZodTypeInternals<"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", unknown>>>>;
                         }, z.core.$strip>>>>;
                     }, z.core.$strip>>;
                 }, z.core.$strip>;

package/dist/declarations/src/internal/aiTools/aiSourceToolPatches.d.ts

@@ -1,4 +1,5 @@
 import type { SerializedSchema, Source } from "@valbuild/core";
+import { type EmptyOfContext } from "../emptyOf.js";
 import { type BuildResult } from "./aiImageToolPatches.js";
 export declare function buildDuplicatePatch(args: {
     sourcePath: string[];
@@ -6,7 +7,7 @@ export declare function buildDuplicatePatch(args: {
 }, moduleSchema: SerializedSchema, moduleSource: Source | undefined): BuildResult;
 export declare function buildEmptyAtPathPatch(args: {
     destinationPath: string[];
-}, moduleSchema: SerializedSchema, moduleSource: Source | undefined): BuildResult;
+}, moduleSchema: SerializedSchema, moduleSource: Source | undefined, context?: EmptyOfContext): BuildResult;
 /**
  * What kind of container a path points at.
  *

package/dist/declarations/src/internal/emptyOf.d.ts

@@ -1,2 +1,25 @@
 import { SerializedSchema, Json } from "@valbuild/core";
-export declare function emptyOf(schema: SerializedSchema): Json;
+/**
+ * What `emptyOf` cannot read off a serialized schema.
+ *
+ * The project's languages, and which one is being worked in. Neither is in the
+ * schema: a locale-keyed record has one entry per language and the languages
+ * are declared in the settings module, and "which language am I writing" is a
+ * fact about the editor, not about the content. Optional throughout: a caller
+ * that has no context gets an empty record and an unset locale, which
+ * validation then reports, rather than wrong ones.
+ */
+export type EmptyOfContext = {
+    /** `locales.available` from the settings module. */
+    locales?: string[];
+    /**
+     * The one language being worked in, where the editor has narrowed to one.
+     *
+     * A new `s.locale()` field is created already set to it. Someone filtered to
+     * Norwegian is writing Norwegian, and a new item that defaulted to unset
+     * would fail validation and vanish from the list they are looking at, in
+     * that order.
+     */
+    selectedLocale?: string;
+};
+export declare function emptyOf(schema: SerializedSchema, context?: EmptyOfContext): Json;

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

@@ -16,6 +16,7 @@ export * from "./parseRoutePattern.js";
 export * from "./getNextAppRouterSourceFolder.js";
 export * from "./routeValidation.js";
 export * from "./resolveSchemaSourceFixes.js";
+export * from "./localeAt.js";
 export * from "./getErrorMessageFromUnknownJson.js";
 export * from "./zod/SerializedSchema.js";
 export * from "./valCanvasProtocol.js";

package/dist/declarations/src/internal/localeAt.d.ts

@@ -0,0 +1,19 @@
+import { type SourcePath } from "@valbuild/core";
+import { type SchemaSourceSnapshot } from "./resolveSchemaSourceFixes.js";
+/**
+ * Which of the project's languages governs a path, or `null` for none.
+ *
+ * THE question the whole feature turns on. A locale scope is a subtree in one
+ * language, and three things open one: a `locale` field on an object, a record
+ * keyed by `s.locale()`, and a locale segment in a segmented key. Once this can
+ * be answered from the schema and the source alone, everything downstream falls
+ * out of it — the Studio's locale filter, deep links, `<html lang>`, and knowing
+ * what to translate from and into.
+ *
+ * One implementation, so the Studio, the server and the validation worker cannot
+ * disagree about what language a piece of content is in.
+ *
+ * `null` means no scope governs the path — which is the answer for most content
+ * in most projects, and for every project that has not declared any languages.
+ */
+export declare function localeAt(path: SourcePath, snapshot: SchemaSourceSnapshot): string | null;

package/dist/declarations/src/internal/resolveSchemaSourceFixes.d.ts

@@ -1,4 +1,4 @@
-import { type Json, type ModuleFilePath, type SerializedSchema, type SourcePath, type ValidationError } from "@valbuild/core";
+import { type Json, type ModuleFilePath, type SerializedSchema, type SourcePath, type ValidationError, type ValidationFix } from "@valbuild/core";
 export type SchemaSourceSnapshot = {
     schemas: Record<ModuleFilePath, SerializedSchema>;
     sources: Record<ModuleFilePath, Json>;
@@ -28,12 +28,36 @@ export declare function getKeyOfRecordAt(sourcePath: SourcePath, snapshot: Schem
     source: unknown;
     schema: SerializedSchema | undefined;
 };
+/**
+ * The languages the project declares, from its settings module.
+ *
+ * Empty where there is no settings module, no `locales` section, or nothing in
+ * it — all of which mean the same thing: this project has not said it is
+ * translated.
+ */
+export declare function declaredLocales(snapshot: SchemaSourceSnapshot): string[];
 export type ResolvedFix = {
     status: "resolved";
 } | {
     status: "remaining";
     error: ValidationError;
 };
+/**
+ * The fixes {@link resolveSchemaSourceFixForError} answers for.
+ *
+ * A marker error carrying one of these is NOT a message: it says "ask the whole
+ * project about this" and carries the value to ask with, because the schema
+ * that raised it can only see its own module. Left unresolved, what a user sees
+ * is the marker's own placeholder text — "should typically be processed by Val
+ * internally … version mismatch" — which is alarming and says nothing.
+ *
+ * A list rather than a check per call site: every caller that resolves some of
+ * these has to resolve all of them, and the two that leaked did so by adding a
+ * fix here and not to a condition somewhere else.
+ */
+export declare const SCHEMA_SOURCE_FIXES: ValidationFix[];
+/** Whether an error is a marker only the whole project can answer. */
+export declare function isSchemaSourceFixError(error: ValidationError): boolean;
 /**
  * The record a `keyof:check-keys` error resolves against, or null for any other
  * error — including a malformed marker, which
@@ -46,20 +70,20 @@ export type ResolvedFix = {
  */
 export declare function keyOfRecordPath(error: ValidationError): SourcePath | null;
 /**
- * Resolves a single `keyof:check-keys` or `router:check-route` error against
- * the given schema/source snapshot. Returns:
+ * Resolves a single marker error (see {@link SCHEMA_SOURCE_FIXES}) against the
+ * given schema/source snapshot. Returns:
  *   - null if the error is not one of these fixes (caller should pass through)
- *   - { status: "resolved" } if the referenced key/route is valid (drop error)
+ *   - { status: "resolved" } if the reference is valid (drop error)
  *   - { status: "remaining"; error } if invalid (rewritten error to surface)
  */
 export declare function resolveSchemaSourceFixForError(error: ValidationError, snapshot: SchemaSourceSnapshot): ResolvedFix | null;
 /**
  * Apply schema/source fix resolution across a map of validation errors.
  *
- * Errors with `keyof:check-keys` or `router:check-route` are resolved against
- * the in-memory schema/source snapshot — valid references drop the error,
- * invalid ones are rewritten with a "did you mean…" message and have their
- * `fixes` cleared (so downstream code reports them as plain validation errors).
+ * Errors carrying one of {@link SCHEMA_SOURCE_FIXES} are resolved against the
+ * in-memory schema/source snapshot — valid references drop the error, invalid
+ * ones are rewritten with a "did you mean…" message and have their `fixes`
+ * cleared (so downstream code reports them as plain validation errors).
  * All other errors pass through untouched.
  *
  * Source paths with no remaining errors are removed from the result.

package/dist/declarations/src/internal/zod/SerializedSchema.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type SerializedSchema as SerializedSchemaT, type SerializedStringSchema as SerializedStringSchemaT, type SerializedLiteralSchema as SerializedLiteralSchemaT, type SerializedBooleanSchema as SerializedBooleanSchemaT, type SerializedNumberSchema as SerializedNumberSchemaT, type SerializedObjectSchema as SerializedObjectSchemaT, type SerializedArraySchema as SerializedArraySchemaT, type SerializedDiscriminatedUnionSchema as SerializedDiscriminatedUnionSchemaT, type SerializedEnumSchema as SerializedEnumSchemaT, type SerializedRichTextSchema as SerializedRichTextSchemaT, type SerializedRichTextOptions as SerializedRichTextOptionsT, type SerializedRecordSchema as SerializedRecordSchemaT, type SerializedKeyOfSchema as SerializedKeyOfSchemaT, type SerializedRouteSchema as SerializedRouteSchemaT, type SerializedFileSchema as SerializedFileSchemaT, type SerializedDateSchema as SerializedDateSchemaT, type SerializedDateTimeSchema as SerializedDateTimeSchemaT, type SerializedColorSchema as SerializedColorSchemaT, type SerializedCodeSchema as SerializedCodeSchemaT, type SerializedImageSchema as SerializedImageSchemaT, type SerializedSettingsSchema as SerializedSettingsSchemaT } from "@valbuild/core";
+import { type SerializedSchema as SerializedSchemaT, type SerializedStringSchema as SerializedStringSchemaT, type SerializedLiteralSchema as SerializedLiteralSchemaT, type SerializedBooleanSchema as SerializedBooleanSchemaT, type SerializedNumberSchema as SerializedNumberSchemaT, type SerializedObjectSchema as SerializedObjectSchemaT, type SerializedArraySchema as SerializedArraySchemaT, type SerializedDiscriminatedUnionSchema as SerializedDiscriminatedUnionSchemaT, type SerializedEnumSchema as SerializedEnumSchemaT, type SerializedRichTextSchema as SerializedRichTextSchemaT, type SerializedRichTextOptions as SerializedRichTextOptionsT, type SerializedRecordSchema as SerializedRecordSchemaT, type SerializedKeyOfSchema as SerializedKeyOfSchemaT, type SerializedLocaleSchema as SerializedLocaleSchemaT, type SerializedRouteSchema as SerializedRouteSchemaT, type SerializedFileSchema as SerializedFileSchemaT, type SerializedDateSchema as SerializedDateSchemaT, type SerializedDateTimeSchema as SerializedDateTimeSchemaT, type SerializedColorSchema as SerializedColorSchemaT, type SerializedCodeSchema as SerializedCodeSchemaT, type SerializedImageSchema as SerializedImageSchemaT, type SerializedSettingsSchema as SerializedSettingsSchemaT } from "@valbuild/core";
 export declare const SerializedStringSchema: z.ZodType<SerializedStringSchemaT>;
 export declare const SerializedLiteralSchema: z.ZodType<SerializedLiteralSchemaT>;
 export declare const SerializedBooleanSchema: z.ZodType<SerializedBooleanSchemaT>;
@@ -73,6 +73,7 @@ export declare const CodeOptions: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export declare const SerializedCodeSchema: z.ZodType<SerializedCodeSchemaT>;
+export declare const SerializedLocaleSchema: z.ZodType<SerializedLocaleSchemaT>;
 export declare const SerializedRouteSchema: z.ZodType<SerializedRouteSchemaT>;
 export declare const SerializedSettingsSchema: z.ZodType<SerializedSettingsSchemaT>;
 export declare const SerializedSchema: z.ZodType<SerializedSchemaT>;