@valbuild/core 0.109.0 → 0.111.0

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

@@ -4,7 +4,7 @@ export { extractValModules, computeValModuleShas, type ExtractedValModules, type
 export type { InitVal, ValConfig, ValConstructor, ContentConstructor, } from "./initVal.js";
 export { Schema, type SerializedSchema, type SelectorOfSchema } from "./schema/index.js";
 export { hasRemoteFileSchema } from "./schema/hasRemoteFileSchema.js";
-export type { ImageMetadata } from "./schema/image.js";
+export type { ImageMetadata, ImageEncodeOption, ImageEncodeOptions, } from "./schema/image.js";
 export type { FileMetadata } from "./schema/file.js";
 export type { ValModule, SerializedModule, InferValModuleType } from "./module.js";
 export type { SourceObject, SourcePrimitive, Source } from "./source/index.js";
@@ -51,6 +51,7 @@ 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 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";
 export { type SerializedDateTimeSchema, DateTimeSchema, } from "./schema/datetime.js";
 export { type SerializedKeyOfSchema, KeyOfSchema } from "./schema/keyOf.js";
@@ -60,7 +61,7 @@ export { type SerializedUnionSchema, UnionSchema, type SerializedStringUnionSche
 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";
-export { type CodeLanguage, type StringRender, type InlineRender, type FieldRender, CODE_LANGUAGES, } from "./render.js";
+export { type InlineRender, type FieldRender, isInlineRender } from "./render.js";
 export type { ValRouter, RouteValidationError } from "./router.js";
 export { getSourcePathFromRoute } from "./getSourcePathFromRoute.js";
 export declare const FATAL_ERROR_TYPES: readonly ["no-schema", "no-source", "invalid-id", "no-module", "invalid-patch"];

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

@@ -13,6 +13,7 @@ import { file } from "./schema/file.js";
 import { files } from "./schema/files.js";
 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 { route } from "./schema/route.js";
 import { router } from "./schema/router.js";
@@ -206,6 +207,23 @@ export type InitSchema = {
      *
      */
     readonly color: typeof color;
+    /**
+     * Define a string edited in a code editor.
+     *
+     * Pass a `language` to syntax highlight it; leave it out for a plain
+     * monospaced editor. The value is a plain string, and — unlike `s.string()` —
+     * it is never stega encoded, so the code reaches your app as it was written.
+     *
+     * @example
+     * const schema = s.code({ language: "typescript" });
+     * export default c.define("/example.val.ts", schema, "const a = 1;");
+     *
+     * @example
+     * const schema = s.code();
+     * export default c.define("/example.val.ts", schema, "no highlighting here");
+     *
+     */
+    readonly code: typeof code;
     /**
      * Define a string that references a route path in your application.
      *
@@ -317,6 +335,7 @@ export declare function initSchema(): {
     date: (options?: Record<string, never>) => import("./index.js").DateSchema<import("./index.js").RawString>;
     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>;
     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/render.d.ts

@@ -1,9 +1,14 @@
+import type { SerializedSchema } from "./schema/index.js";
 /**
  * A RENDER is how the FIELD ITSELF is laid out in the editor, and it applies
- * only when you are looking at the field: `s.string().render({ as: "textarea"
- * })`, `.render({ as: "code", language })`, `.render({ as: "inline" })` on an
+ * only when you are looking at the field: `.render({ as: "inline" })` on an
  * array/record item.
  *
+ * It is deliberately the ONE thing a render can say. What a string looks like
+ * when it holds more than a line is the schema's own business — `.multiline()`
+ * for a text box, `s.code({ language })` for a code editor — not a layout
+ * bolted onto `s.string()` from outside.
+ *
  * A PREVIEW (`preview.ts`) is the other thing: how the VALUE is shown wherever
  * a preview of it is needed — a list row, a reference dropdown, a search hit —
  * that is, wherever the value is navigable to rather than open. The two never
@@ -24,13 +29,6 @@
  * `render` its own execute/store pair again. It is NOT to re-merge the two:
  * conflating them is what this file was split up to undo.
  */
-/**
- * The list is the declaration and {@link CodeLanguage} is derived from it, so
- * that a validator elsewhere (`shared`'s zod schema) can enumerate the same
- * languages without a second copy that drifts. Same shape as `COLOR_FORMATS`.
- */
-export declare const CODE_LANGUAGES: readonly ["typescript", "javascript", "javascriptreact", "typescriptreact", "json", "java", "html", "css", "xml", "markdown", "sql", "python", "rust", "php", "go", "cpp", "sass", "vue", "angular"];
-export type CodeLanguage = (typeof CODE_LANGUAGES)[number];
 /**
  * `{ as: "inline" }` on a field that is the ITEM of an array or record: the
  * container renders the field itself inside each (sortable) row, instead of a
@@ -48,18 +46,32 @@ export type InlineRender = {
     as: "inline";
 };
 /**
- * What `.render(...)` takes on every field except `s.string()`, and what the
- * serialized schema carries verbatim.
+ * What `.render(...)` takes on every field, and what the serialized schema
+ * carries verbatim.
  */
 export type FieldRender = InlineRender;
 /**
- * What `s.string().render(...)` takes, and what the serialized schema carries
- * verbatim. A string has editor layouts of its own (textarea, code) in
- * addition to the container-facing `inline`.
+ * Is this item schema edited INSIDE its list row, rather than behind a
+ * clickable preview row that navigates to it?
+ *
+ * The one answer, so that the list rows, the nav-stop rule (`getNavPath`) and
+ * the add buttons cannot drift apart — they are three readings of the same
+ * question, and a disagreement between them is a row you can edit in place but
+ * that "add" navigates away from.
+ *
+ * A tagged union counts as inline when the union itself declares it OR when
+ * ANY of its variants does. A page-builder list is `s.array(s.union("type",
+ * block, block, ...))` and the natural place to write the render is on the
+ * blocks, one per block type — the union is a dispatch, not something the
+ * author thinks of as the field. `some` rather than `every` because the row
+ * draws the union's own editor (the tag selector plus the matched variant's
+ * fields), which handles every variant either way: with `every`, adding one
+ * variant and forgetting its `.render` would silently turn the whole list back
+ * into preview rows.
+ *
+ * This is the ONLY place a render is allowed to be read from anywhere but the
+ * schema it was declared on. It stays static (see the top of this file): the
+ * answer is a function of the serialized schema alone, never of the value the
+ * row happens to hold.
  */
-export type StringRender = {
-    as: "textarea";
-} | {
-    as: "code";
-    language: CodeLanguage;
-} | InlineRender;
+export declare function isInlineRender(schema: SerializedSchema): boolean;

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

@@ -0,0 +1,85 @@
+import { CustomValidateFunction, 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 { RawString } from "./string.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+/**
+ * The list is the declaration and {@link CodeLanguage} is derived from it, so
+ * that a validator elsewhere (`shared`'s zod schema) can enumerate the same
+ * languages without a second copy that drifts. Same shape as `COLOR_FORMATS`.
+ */
+export declare const CODE_LANGUAGES: readonly ["typescript", "javascript", "javascriptreact", "typescriptreact", "json", "java", "html", "css", "xml", "markdown", "sql", "python", "rust", "php", "go", "cpp", "sass", "vue", "angular"];
+export type CodeLanguage = (typeof CODE_LANGUAGES)[number];
+export type CodeOptions = {
+    /**
+     * The language to syntax highlight the editor with.
+     *
+     * Omit it for a plain monospaced editor with no highlighting.
+     *
+     * @example
+     * "typescript"
+     * "json"
+     * "markdown"
+     */
+    language?: CodeLanguage;
+};
+export type SerializedCodeSchema = {
+    type: "code";
+    /** 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;
+    options?: CodeOptions;
+    opt: boolean;
+    customValidate?: boolean;
+    readonly?: boolean;
+    hidden?: boolean;
+    description?: string;
+};
+/**
+ * A string edited in a code editor.
+ *
+ * Its own schema type rather than a layout on `s.string()`: the language is
+ * part of what the content IS, not of how one field happens to be drawn, and
+ * being a type is what lets the value stay out of stega encoding — invisible
+ * characters woven into source code are not something a consumer can render.
+ */
+export declare class CodeSchema<Src extends string | null> extends Schema<Src> {
+    private readonly options?;
+    private readonly opt;
+    private readonly customValidateFunctions;
+    private readonly isReadonly;
+    private readonly isHidden;
+    private readonly description?;
+    private readonly renderInput;
+    private readonly previewInput;
+    constructor(options?: CodeOptions | undefined, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    describe(description: string | null): CodeSchema<Src>;
+    validate(validationFunction: (src: Src) => false | string): CodeSchema<Src>;
+    protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
+    protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    nullable(): CodeSchema<Src | null>;
+    readonly(): CodeSchema<Src>;
+    hidden(): CodeSchema<Src>;
+    /**
+     * How this field is laid out in the editor when it is the item of an array
+     * or record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
+     *
+     * Static configuration, not a callback — see `render.ts`.
+     */
+    render(input: FieldRender): CodeSchema<Src>;
+    /**
+     * How this VALUE is shown where a preview of it is needed — a row in a
+     * sortable list, a reference dropdown, a search hit. Never how the field
+     * itself is edited (that is `render`). See `preview.ts`.
+     */
+    preview(select: ItemPreviewInput<Src>): CodeSchema<Src>;
+    protected executePreviewItem(src: NonNullable<Src>): PreviewItem | null;
+    protected declaresItemPreview(): boolean;
+    protected executeSerialize(): SerializedSchema;
+    protected executePreview(): ReifiedPreview;
+}
+export declare const code: (options?: CodeOptions) => CodeSchema<RawString>;

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

@@ -6,11 +6,44 @@ import { ValModule } from "../index.js";
 import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
 import { FieldRender } from "../render.js";
 import { ImagesEntryMetadata } from "./images.js";
+/**
+ * How an uploaded image is re-encoded in the browser, before it is uploaded.
+ *
+ * Off unless a schema asks for it. When it is on, the image is converted to
+ * `type` and scaled down to fit `maxWidth` x `maxHeight` - unless the result
+ * would be BIGGER than the original and no downscale was needed, in which case
+ * the original bytes are kept. See `architecture/media.md`.
+ *
+ * `type` is required so that adding a format later is additive: a schema
+ * written today keeps saying exactly which format it asked for.
+ */
+export type ImageEncodeOptions = {
+    type: "webp";
+    /** Passed to `canvas.toBlob`. Between 0 and 1. @default 0.8 */
+    quality?: number;
+    /** @default 2560 */
+    maxWidth?: number;
+    /** @default 2560 */
+    maxHeight?: number;
+};
+/** `false` (or absent) uploads the bytes exactly as the editor picked them. */
+export type ImageEncodeOption = false | ImageEncodeOptions;
+/**
+ * What a GALLERY-BACKED field may say for itself.
+ *
+ * Not `ImageOptions`: `directory` and `accept` belong to the gallery, and a
+ * field repeating them is how two copies of one fact get to disagree. `encode`
+ * is different — it describes what happens to the bytes on their way IN, so a
+ * field that wants the original where its gallery re-encodes has to be able to
+ * say `encode: false`, and there is nowhere else to say it.
+ */
+export type GalleryImageOptions = {
+    encode?: ImageEncodeOption;
+};
 export type ImageOptions = {
-    ext?: ["jpg"] | ["webp"];
     directory?: string;
-    prefix?: string;
     accept?: string;
+    encode?: ImageEncodeOption;
 };
 export type SerializedImageSchema = {
     type: "image";
@@ -86,6 +119,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>>): ImageSchema<GalleryImageSource>;
+export declare function image(galleryModule: ValModule<Record<string, ImagesEntryMetadata>>, 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

@@ -4,6 +4,7 @@ import { RecordSchema } from "./record.js";
 import { ObjectSchema } from "./object.js";
 import { StringSchema } from "./string.js";
 import { NumberSchema } from "./number.js";
+import type { ImageEncodeOption } from "./image.js";
 /**
  * Alt schema type - can be a string, nullable string, or a record of locale to string
  */
@@ -39,6 +40,13 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
      * @default false
      */
     remote?: boolean;
+    /**
+     * Re-encode uploads in the browser before they are uploaded.
+     *
+     * Off unless set. A field backed by this gallery (`s.image(galleryVal)`)
+     * inherits it, the same way it inherits `accept` and `directory`.
+     */
+    encode?: ImageEncodeOption;
 };
 /**
  * Metadata for an image entry in the images record

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

@@ -12,6 +12,7 @@ import { SerializedRecordSchema } from "./record.js";
 import { SerializedRichTextSchema } from "./richtext.js";
 import { RawString, SerializedStringSchema } from "./string.js";
 import { SerializedUnionSchema } from "./union.js";
+import { SerializedCodeSchema } from "./code.js";
 import { SerializedColorSchema } from "./color.js";
 import { SerializedDateSchema } from "./date.js";
 import { SerializedDateTimeSchema } from "./datetime.js";
@@ -20,7 +21,7 @@ import { ValidationError, ValidationErrors } from "./validation/ValidationError.
 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 | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedRouteSchema | SerializedImageSchema;
+export type SerializedSchema = SerializedStringSchema | SerializedLiteralSchema | SerializedBooleanSchema | SerializedNumberSchema | SerializedObjectSchema | SerializedArraySchema | SerializedUnionSchema | SerializedRichTextSchema | SerializedRecordSchema | SerializedKeyOfSchema | SerializedFileSchema | SerializedDateSchema | SerializedDateTimeSchema | SerializedColorSchema | SerializedCodeSchema | SerializedRouteSchema | SerializedImageSchema;
 type Primitives = number | string | boolean | null | FileSource;
 export type AssertError = {
     message: string;

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

@@ -6,12 +6,15 @@ import { SelectorSource } from "../selector/index.js";
 import { JsonOf, JsonSource } from "../source/json.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+import type { ImageEncodeOption } from "./image.js";
 type MediaOptions = {
     type: "files" | "images";
     accept: string;
     directory: string;
     remote: boolean;
     altSchema?: Schema<SelectorSource>;
+    /** Images only: how uploads are re-encoded in the browser. See `image.ts`. */
+    encode?: ImageEncodeOption;
 };
 export type SerializedRecordSchema = {
     type: "record";
@@ -32,6 +35,7 @@ export type SerializedRecordSchema = {
     accept?: string;
     directory?: string;
     remote?: boolean;
+    encode?: ImageEncodeOption;
     alt?: SerializedSchema;
     jsonValues?: boolean;
     readonly?: boolean;

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

@@ -1,6 +1,6 @@
 import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
 import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
-import { StringRender } from "../render.js";
+import { FieldRender } from "../render.js";
 import { SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 type StringOptions = {
@@ -20,7 +20,17 @@ export type SerializedStringSchema = {
      * off the schema it already has. See `render.ts` for what that assumption
      * buys, and what to do if a render ever needs to stop being static.
      */
-    render?: StringRender;
+    render?: FieldRender;
+    /**
+     * Set by `.multiline()`: the field is a growing text box rather than a
+     * single-line input.
+     *
+     * A property of the schema rather than a `render` variant, because it says
+     * what the string IS — text that may hold line breaks — and not merely how one
+     * field is drawn. It is read the same way a render is, straight off the
+     * serialized schema where the field is drawn.
+     */
+    multiline?: boolean;
     /** Set when this schema declares a `preview`. The closure itself cannot serialize. */
     preview?: true;
     options?: {
@@ -54,7 +64,8 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     private readonly isHidden;
     private readonly description?;
     private readonly previewInput;
-    constructor(options?: StringOptions | undefined, opt?: boolean, isRaw?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], renderInput?: StringRender | null, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null);
+    private readonly isMultiline;
+    constructor(options?: StringOptions | undefined, opt?: boolean, isRaw?: boolean, customValidateFunctions?: ((src: Src) => false | string)[], renderInput?: FieldRender | null, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, previewInput?: ItemPreviewInput<Src> | null, isMultiline?: boolean);
     describe(description: string | null): StringSchema<Src>;
     /**
      * @deprecated Use `minLength` instead
@@ -77,13 +88,27 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;
     /**
-     * How this field is laid out in the editor: a textarea, or a code editor for
-     * the given language.
+     * This string holds text that may run to several lines: the editor gives it a
+     * growing text box instead of a single-line input.
+     *
+     * Nothing else changes — the value is still a plain string, and no validation
+     * is added or removed. For code, use `s.code({ language })` instead, which is
+     * its own schema type.
+     *
+     * @example
+     * const schema = s.string().multiline();
+     * export default c.define("/example.val.ts", schema, "Line one\nLine two");
+     */
+    multiline(): StringSchema<Src>;
+    /**
+     * How this field is laid out in the editor when it is the item of an array or
+     * record: `{ as: "inline" }` renders the field itself inside each row,
+     * instead of a preview row that navigates to it.
      *
      * Static configuration, not a callback — see `render.ts`. What a CONTAINER
      * shows for its items is a `preview`, which is a different thing entirely.
      */
-    render(input: StringRender): StringSchema<Src>;
+    render(input: FieldRender): StringSchema<Src>;
     /**
      * How this VALUE is shown where a preview of it is needed — a row in a
      * sortable list, a reference dropdown, a search hit. Never how the field