@valbuild/core 0.127.0 → 0.128.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # @valbuild/core
 
+## 0.128.0
+
+### Minor Changes
+
+- [#637](https://github.com/valbuild/val/pull/637) [`8b52b33`](https://github.com/valbuild/val/commit/8b52b33e1f629f14f66cc71dcc7cf415d210c7d4) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** the `directory` option is now `dir`, on every schema that takes
+  it — `s.imageset()`, `s.fileset()` and `s.image()`.
+
+  ```ts
+  // before
+  s.imageset({ directory: "/public/val/images" });
+  s.fileset({ accept: "application/pdf", directory: "/public/val/docs" });
+  s.image({ directory: "/public/val/heroes" });
+
+  // after
+  s.imageset({ dir: "/public/val/images" });
+  s.fileset({ accept: "application/pdf", dir: "/public/val/docs" });
+  s.image({ dir: "/public/val/heroes" });
+  ```
+
+  Same meaning: where uploads for that schema land. Still required on
+  `s.imageset()` and `s.fileset()`, still optional on `s.image()`.
+
+  **`files.directory` in `val.config.ts` is NOT renamed.** That is the
+  project-wide files directory, a different option with a different scope, and it
+  keeps its name.
+
+  `dir` is the serialized name too, and two things follow from that. Neither
+  needs any action, but both are worth knowing:
+
+  - **History still reads pre-rename commits.** A commit record stores the schema
+    each module was under, so commits from before this release carry `directory`.
+    The serialized-schema parser accepts that key and reads it as `dir`, which is
+    what keeps a historical gallery from showing up with no directory at all.
+  - **Published remote files re-validate once.** The serialized schema is what a
+    remote file's validation hash is computed from, so a file uploaded under a
+    schema that sets this option gets one re-download and re-check, after which
+    the ref is rewritten with the new hash. This is the same self-healing path a
+    core version bump already takes.
+
+- [#643](https://github.com/valbuild/val/pull/643) [`362fb49`](https://github.com/valbuild/val/commit/362fb49f30d2b04c4ff78d54dca2bf5ad978a05c) Thanks [@freekh](https://github.com/freekh)! - `s.imageset({ alt })` now types an entry's `alt` from the `alt` schema, instead
+  of always calling it `string | null`.
+
+  That single hard-coded type made the locale-record form **unusable** and the
+  required form **unsound**, in opposite directions:
+
+  ```ts
+  // Before: documented, but the source could not be typed.
+  //   Type '{ en: string; no: string; }' is not assignable to type 'string'
+  s.imageset({ dir: "/public/val/img", alt: s.record(s.string()) });
+
+  // Before: this compiled, then failed validation with
+  //   Expected 'string', got 'null'
+  s.imageset({ dir: "/public/val/img", alt: s.string() });
+  // → { width, height, mimeType, alt: null }
+  ```
+
+  Both now behave as the schema says: a locale record types as
+  `Record<string, string>`, a required alt as `string`, and an omitted or
+  `.nullable()` alt as `string | null` exactly as before.
+
+  `ImagesetEntryMetadata` takes an optional alt parameter and defaults to
+  `string | null`, so existing references keep working unchanged. Where a gallery
+  of any alt shape is acceptable — `s.image(galleryModule)` is the one that
+  matters, since a field carries its own alt and never reads the gallery's — write
+  `ImagesetEntryMetadata<AltSource>`.
+
+  The one thing to know if you had worked around this: an explicit
+  `Record<string, ImagesetEntryMetadata>` annotation on the source of a
+  **required**-alt gallery is now too wide and will not compile. Name the alt type
+  (`ImagesetEntryMetadata<string>`), or drop the annotation and let the schema
+  type it.
+
+- [#637](https://github.com/valbuild/val/pull/637) [`c595799`](https://github.com/valbuild/val/commit/c59579977a436ec530c6c69f2b340ab9829d97ab) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** `s.images()` is now `s.imageset()`, and `s.files()` is now
+  `s.fileset()`.
+
+  ```ts
+  // before
+  s.images({ directory: "/public/val/images" });
+  s.files({ accept: "application/pdf", directory: "/public/val/docs" });
+
+  // after
+  s.imageset({ dir: "/public/val/images" });
+  s.fileset({ accept: "application/pdf", dir: "/public/val/docs" });
+  ```
+
+  Nothing about their behaviour changed — same `.remote()`, same
+  record-of-metadata content keyed by file path. (`directory` is renamed to
+  `dir` in the same release; see the separate note.)
+
+  The old names were a trap. `s.images()` and `s.image()` differ by one letter,
+  which reads as "the same thing, but several" — while the real difference is that
+  `s.imageset()` defines a **whole module** and `s.image()` defines a **field**.
+  They are not variants of each other, and the plural spelling suggested they were.
+  `-set` names the container instead, so the two now look as different as they are.
+
+  `s.image(imagesetModule)` and `s.file(filesetModule)` are unchanged: that is
+  still how a field picks one entry out of a set.
+
+  If you are also moving off the `remote` option (removed in the same release),
+  the combined migration is:
+
+  ```ts
+  // before
+  s.images({ directory: "/public/val/images", remote: true });
+
+  // after
+  s.imageset({ dir: "/public/val/images" }).remote();
+  ```
+
+  The rename is a hard error rather than a silent one: `s.images` no longer
+  exists, so an un-migrated call fails immediately in TypeScript and at runtime.
+
 ## 0.127.0
 
 ### Minor Changes

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

@@ -12,7 +12,7 @@ import { literal } from "./schema/literal.js";
 import { keyOf } from "./schema/keyOf.js";
 import { record } from "./schema/record.js";
 import { file } from "./schema/file.js";
-import { files } from "./schema/files.js";
+import { fileset } from "./schema/fileset.js";
 import { date } from "./schema/date.js";
 import { datetime } from "./schema/datetime.js";
 import { code } from "./schema/code.js";
@@ -20,7 +20,7 @@ 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";
+import { imageset } from "./schema/imageset.js";
 import { settings } from "./schema/settings.js";
 export type InitSchema = {
     /**
@@ -148,7 +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
+     * import galleryVal from "./gallery.val"; // an s.imageset() module
      * const schema = s.image(galleryVal);
      * export default c.define("/example.val.ts", schema, {
      *   path: "/public/val/example.png",
@@ -311,9 +311,9 @@ export type InitSchema = {
      *
      * @example
      * ```typescript
-     * const schema = s.images({
+     * const schema = s.imageset({
      *   accept: "image/webp",
-     *   directory: "/public/val/images",
+     *   dir: "/public/val/images",
      *   alt: s.string().minLength(4),
      * });
      * export default c.define("/content/images.val.ts", schema, {
@@ -326,15 +326,15 @@ export type InitSchema = {
      * });
      * ```
      */
-    readonly images: typeof images;
+    readonly imageset: typeof imageset;
     /**
      * Define a collection of files.
      *
      * @example
      * ```typescript
-     * const schema = s.files({
+     * const schema = s.fileset({
      *   accept: "application/pdf",
-     *   directory: "/public/val/documents",
+     *   dir: "/public/val/documents",
      * });
      * export default c.define("/content/documents.val.ts", schema, {
      *   "/public/val/documents/report.pdf": {
@@ -343,7 +343,7 @@ export type InitSchema = {
      * });
      * ```
      */
-    readonly files: typeof files;
+    readonly fileset: typeof fileset;
     /**
      * Define the project's settings.
      *
@@ -399,11 +399,11 @@ export declare function initSchema(): {
     keyOf: <Src extends import("./selector/index.js").GenericSelector<import("./source/index.js").SourceObject> & import("./module.js").ValModuleBrand>(valModule: Src) => import("./index.js").KeyOfSchema<Src, Src extends import("./selector/index.js").GenericSelector<infer S extends import("./source/index.js").Source, undefined> ? S extends readonly import("./source/index.js").Source[] ? number : S extends import("./source/index.js").SourceObject ? string extends keyof S ? import("./index.js").RawString : keyof S : S extends Record<string, import("./source/index.js").Source> ? import("./index.js").RawString : never : never>;
     record: typeof record;
     file: typeof file;
-    files: (options: import("./schema/files.js").FilesOptions) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{
+    fileset: (options: import("./schema/fileset.js").FilesetOptions) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{
         mimeType: import("./index.js").StringSchema<string>;
     }, {
         mimeType: string;
-    }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/files.js").FilesEntryMetadata>>;
+    }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/fileset.js").FilesetEntryMetadata>>;
     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>;
@@ -411,16 +411,16 @@ export declare function initSchema(): {
     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<{
+    imageset: <Accept extends `image/${string}`, Alt extends import("./schema/imageset.js").AltSchema = import("./index.js").StringSchema<string | null>>(options: import("./schema/imageset.js").ImagesetOptions<Accept, Alt>) => import("./index.js").RecordSchema<import("./index.js").ObjectSchema<{
         width: import("./index.js").NumberSchema<number>;
         height: import("./index.js").NumberSchema<number>;
         mimeType: import("./index.js").StringSchema<string>;
-        alt: import("./index.js").StringSchema<string | null>;
+        alt: Alt;
     }, {
         width: number;
         height: number;
         mimeType: string;
-        alt: string | null;
-    }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/images.js").ImagesEntryMetadata>>;
+        alt: import("./schema/index.js").SelectorOfSchema<Alt>;
+    }>, import("./schema/index.js").Schema<string>, Record<string, import("./schema/imageset.js").ImagesetEntryMetadata<import("./schema/imageset.js").AltSourceOf<Alt>>>>;
     settings: typeof settings;
 };

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

@@ -6,7 +6,7 @@ import { ValidationError, ValidationErrors } from "./validation/ValidationError.
 import { ValModule } from "../index.js";
 import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
 import { FieldRender } from "../render.js";
-import { FilesEntryMetadata } from "./files.js";
+import { FilesetEntryMetadata } from "./fileset.js";
 export type FileOptions = {
     accept?: string;
 };
@@ -36,7 +36,7 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
     private readonly description?;
     private readonly renderInput;
     private readonly previewInput;
-    constructor(options?: FileOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, FilesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    constructor(options?: FileOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, FilesetEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     /**
      * Describe this field.
      *
@@ -151,6 +151,6 @@ export declare class FileSchema<Src extends FileSource | null> extends Schema<Sr
  * A file picked from a gallery. Its mime type lives in the gallery, so the
  * field carries only the path.
  */
-export declare function file(galleryModule: ValModule<Record<string, FilesEntryMetadata>>): FileSchema<GalleryFileSource>;
+export declare function file(galleryModule: ValModule<Record<string, FilesetEntryMetadata>>): FileSchema<GalleryFileSource>;
 /** A file of its own, carrying its own mime type. */
 export declare function file(options?: FileOptions): FileSchema<FileSource>;

package/dist/declarations/src/schema/{files.d.ts → fileset.d.ts}

@@ -4,9 +4,9 @@ import { RecordSchema } from "./record.js";
 import { ObjectSchema } from "./object.js";
 import { StringSchema } from "./string.js";
 /**
- * Options for s.files()
+ * Options for s.fileset()
  */
-export type FilesOptions = {
+export type FilesetOptions = {
     /**
      * The accepted mime type pattern (e.g., "application/pdf", "text/*", "*\/*")
      */
@@ -20,19 +20,19 @@ export type FilesOptions = {
      * collection that had simply not said where it wanted its files silently shared
      * a directory with every other one.
      */
-    directory: "/public" | `/public/${string}`;
+    dir: "/public" | `/public/${string}`;
 };
 /**
  * Metadata for a file entry in the files record
  */
-export type FilesEntryMetadata = {
+export type FilesetEntryMetadata = {
     mimeType: string;
 };
-export type SerializedFilesSchema = SerializedRecordSchema;
-type FilesItemProps = {
+export type SerializedFilesetSchema = SerializedRecordSchema;
+type FilesetItemProps = {
     mimeType: StringSchema<string>;
 };
-type FilesItemSrc = {
+type FilesetItemSrc = {
     mimeType: string;
 };
 /**
@@ -42,9 +42,9 @@ type FilesItemSrc = {
  *
  * @example
  * ```typescript
- * const schema = s.files({
+ * const schema = s.fileset({
  *   accept: "application/pdf",
- *   directory: "/public/val/documents",
+ *   dir: "/public/val/documents",
  * });
  * export default c.define("/content/documents.val.ts", schema, {
  *   "/public/val/documents/report.pdf": {
@@ -53,5 +53,5 @@ type FilesItemSrc = {
  * });
  * ```
  */
-export declare const files: (options: FilesOptions) => RecordSchema<ObjectSchema<FilesItemProps, FilesItemSrc>, Schema<string>, Record<string, FilesEntryMetadata>>;
+export declare const fileset: (options: FilesetOptions) => RecordSchema<ObjectSchema<FilesetItemProps, FilesetItemSrc>, Schema<string>, Record<string, FilesetEntryMetadata>>;
 export {};

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

@@ -5,7 +5,7 @@ import type { SerializedSchema } from "./index.js";
  * The one answer to that question. There used to be two — `hasRemoteFileSchema`
  * in the server, gating whether `/save` demands remote credentials, and
  * `findRequiredRemoteFiles` in the Studio, gating the `/remote/settings` fetch —
- * and they disagreed about `s.images({ ... }).remote()`: the Studio's version
+ * and they disagreed about `s.imageset({ ... }).remote()`: the Studio's version
  * counted a remote media record, the server's did not, because a media
  * collection serializes as a `record` of metadata rather than as an image
  * schema.
@@ -43,8 +43,8 @@ export declare function hasRemoteFileSchema(schema: SerializedSchema): boolean;
  *
  * It is a walk over the SERIALIZED schema for the reasons given above, and for
  * one more that is specific to this question: the two cases most likely to be
- * missed are invisible to a value type. A media collection (`s.images()` /
- * `s.files()`) serializes as a record of metadata with no image schema inside
+ * missed are invisible to a value type. A media collection (`s.imageset()` /
+ * `s.fileset()`) serializes as a record of metadata with no image schema inside
  * it, and a richtext inline image lives in a constructor argument. A check
  * written against the item TYPE would silently pass both — and the gallery case
  * already has a data-loss incident attached to it (see above).

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

@@ -5,7 +5,7 @@ import { ValidationError, ValidationErrors } from "./validation/ValidationError.
 import { ValModule } from "../index.js";
 import { ItemPreviewInput, PreviewItem, ReifiedPreview } from "../preview.js";
 import { FieldRender } from "../render.js";
-import { ImagesEntryMetadata } from "./images.js";
+import { AltSource, ImagesetEntryMetadata } from "./imageset.js";
 /**
  * How an uploaded image is re-encoded in the browser, before it is uploaded.
  *
@@ -41,7 +41,7 @@ export type GalleryImageOptions = {
     encode?: ImageEncodeOption;
 };
 export type ImageOptions = {
-    directory?: string;
+    dir?: string;
     accept?: string;
     encode?: ImageEncodeOption;
 };
@@ -81,7 +81,7 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     private readonly description?;
     private readonly renderInput;
     private readonly previewInput;
-    constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagesEntryMetadata>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
+    constructor(options?: ImageOptions | undefined, opt?: boolean, isRemote?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], moduleMetadata?: Record<ModulePath, Record<string, ImagesetEntryMetadata<AltSource>>>, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null, previewInput?: ItemPreviewInput<Src> | null);
     /**
      * Describe this field.
      *
@@ -119,7 +119,7 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
      *
      * @example
      * const schema = s
-     *   .image({ accept: "image/webp", directory: "/public/val/images" })
+     *   .image({ accept: "image/webp", dir: "/public/val/images" })
      *   .remote();
      * export default c.define("/example.val.ts", schema, {
      *   path: "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/example.webp",
@@ -163,6 +163,10 @@ export declare class ImageSchema<Src extends ImageSource | null> extends Schema<
     /**
      * The entries of the gallery this field points at, or null when it is a
      * standalone field.
+     *
+     * `AltSource` rather than a specific alt type: a field never reads an entry's
+     * alt — it carries its own — so it only needs the entry keys and the
+     * dimensions, and a gallery of any alt shape can back it.
      */
     private galleryEntries;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
@@ -221,6 +225,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>>, galleryOptions?: GalleryImageOptions): ImageSchema<GalleryImageSource>;
+export declare function image(galleryModule: ValModule<Record<string, ImagesetEntryMetadata<AltSource>>>, 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 → imageset.d.ts}

@@ -1,4 +1,5 @@
 import { Schema } from "./index.js";
+import type { SelectorOfSchema } from "./index.js";
 import type { SerializedRecordSchema } from "./record.js";
 import { RecordSchema } from "./record.js";
 import { ObjectSchema } from "./object.js";
@@ -10,9 +11,43 @@ import type { ImageEncodeOption } from "./image.js";
  */
 export type AltSchema = StringSchema<string> | StringSchema<string | null> | RecordSchema<StringSchema<string>, Schema<string>, Record<string, string>>;
 /**
- * Options for s.images()
+ * What an entry's `alt` holds, for a given `alt` schema.
+ *
+ * This is the schema's own source type, not a second list that has to be kept
+ * in step with `AltSchema`: `s.string()` gives `string`, `s.string().nullable()`
+ * gives `string | null`, and `s.record(s.string())` gives
+ * `Record<string, string>`.
+ */
+export type AltSourceOf<Alt extends AltSchema> = SelectorOfSchema<Alt>;
+/** Every `alt` value any `AltSchema` can produce. */
+export type AltSource = AltSourceOf<AltSchema>;
+/**
+ * Options for s.imageset()
+ */
+export type ImagesetOptions<Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>> = ImagesetOptionsBase<Accept> & ImagesetAltOption<Alt>;
+/**
+ * `alt` is optional only when it is the default schema.
+ *
+ * Naming a different `Alt` and then leaving `alt` out would make the fallback
+ * in `imageset()` a lie — `Alt` would say `s.string()` while the value was a
+ * nullable one. Requiring it in that case is what makes the fallback sound:
+ * the branch that uses it is reachable only when `Alt` IS the default.
  */
-export type ImagesOptions<Accept extends `image/${string}`> = {
+type ImagesetAltOption<Alt extends AltSchema> = [
+    StringSchema<string | null>
+] extends [Alt] ? {
+    /**
+     * Alt text schema. Can be:
+     * - s.string() for required alt text
+     * - s.string().nullable() for optional alt text (default)
+     * - s.record(s.string(), s.string()) for locale-based alt text
+     */
+    alt?: Alt;
+} : {
+    /** Alt text schema — required, because it is not the default one. */
+    alt: Alt;
+};
+type ImagesetOptionsBase<Accept extends `image/${string}`> = {
     /**
      * The accepted mime type pattern. Must be an image type (e.g., "image/png", "image/webp", "image/*")
      * @default "image/*"
@@ -27,14 +62,7 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
      * gallery that had simply not said where it wanted its files silently shared a
      * directory with every other one.
      */
-    directory: "/public" | `/public/${string}`;
-    /**
-     * Alt text schema. Can be:
-     * - s.string() for required alt text
-     * - s.string().nullable() for optional alt text (default)
-     * - s.record(s.string(), s.string()) for locale-based alt text
-     */
-    alt?: AltSchema;
+    dir: "/public" | `/public/${string}`;
     /**
      * Re-encode uploads in the browser before they are uploaded.
      *
@@ -44,30 +72,35 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
     encode?: ImageEncodeOption;
 };
 /**
- * Metadata for an image entry in the images record
+ * Metadata for an image entry in the images record.
+ *
+ * `alt` follows the schema's `alt` option, so it defaults to `string | null`
+ * and becomes `string` under `s.string()` or `Record<string, string>` under
+ * `s.record(s.string())`. Write `ImagesetEntryMetadata<AltSource>` where a
+ * gallery of any alt shape is acceptable.
  */
-export type ImagesEntryMetadata = {
+export type ImagesetEntryMetadata<Alt extends AltSource = string | null> = {
     width: number;
     height: number;
     mimeType: string;
-    alt: string | null;
+    alt: Alt;
     hotspot?: {
         x: number;
         y: number;
     };
 };
-export type SerializedImagesSchema = SerializedRecordSchema;
-type ImagesItemProps = {
+export type SerializedImagesetSchema = SerializedRecordSchema;
+type ImagesetItemProps<Alt extends AltSchema> = {
     width: NumberSchema<number>;
     height: NumberSchema<number>;
     mimeType: StringSchema<string>;
-    alt: StringSchema<string | null>;
+    alt: Alt;
 };
-type ImagesItemSrc = {
+type ImagesetItemSrc<Alt extends AltSchema> = {
     width: number;
     height: number;
     mimeType: string;
-    alt: string | null;
+    alt: AltSourceOf<Alt>;
 };
 /**
  * Define a collection of images.
@@ -78,9 +111,9 @@ type ImagesItemSrc = {
  *
  * @example
  * ```typescript
- * const schema = s.images({
+ * const schema = s.imageset({
  *   accept: "image/webp",
- *   directory: "/public/val/images",
+ *   dir: "/public/val/images",
  *   alt: s.string().minLength(4),
  * });
  * export default c.define("/content/images.val.ts", schema, {
@@ -93,5 +126,5 @@ type ImagesItemSrc = {
  * });
  * ```
  */
-export declare const images: <Accept extends `image/${string}`>(options: ImagesOptions<Accept>) => RecordSchema<ObjectSchema<ImagesItemProps, ImagesItemSrc>, Schema<string>, Record<string, ImagesEntryMetadata>>;
+export declare const imageset: <Accept extends `image/${string}`, Alt extends AltSchema = StringSchema<string | null>>(options: ImagesetOptions<Accept, Alt>) => RecordSchema<ObjectSchema<ImagesetItemProps<Alt>, ImagesetItemSrc<Alt>>, Schema<string>, Record<string, ImagesetEntryMetadata<AltSourceOf<Alt>>>>;
 export {};

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;
@@ -229,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
@@ -238,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":
      *     {
@@ -257,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
@@ -284,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.
      *