@valbuild/core 0.143.0 → 0.145.0

package/dist/declarations/src/schema/{videoset.d.ts → videodir.d.ts}

@@ -1,18 +1,29 @@
 import { Schema } from "./index.js";
-import type { SerializedRecordSchema } from "./record.js";
+import type { MediaDir, SerializedRecordSchema } from "./record.js";
 import { RecordSchema } from "./record.js";
 import { ObjectSchema } from "./object.js";
 import { StringSchema } from "./string.js";
 import { NumberSchema } from "./number.js";
-import type { AltSchema, AltSource, AltSourceOf } from "./imageset.js";
+import type { AltSchema, AltSource, AltSourceOf } from "./imagedir.js";
 import type { SerializedVideoSchema, VideoStreamOption } from "./video.js";
 import type { MediaHotspot, VideoCaptionSource, VideoPosterSource } from "../source/media.js";
 /**
- * Options for s.videoset()
+ * Options for `s.videodir(dir, options)`: everything but the directory, which
+ * is the first argument.
  */
-export type VideosetOptions<Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>> = VideosetOptionsBase<Accept> & VideosetAltOption<Alt>;
-/** See `ImagesetAltOption`: `alt` is optional only when it is the default. */
-type VideosetAltOption<Alt extends AltSchema> = [
+export type VideodirOptions<Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>> = VideodirOptionsBase<Accept> & VideodirAltOption<Alt>;
+/**
+ * Options for the deprecated `s.videoset(options)`, which took the directory
+ * as `dir`.
+ *
+ * @deprecated Use `s.videodir(dir, options)` and `VideodirOptions`.
+ */
+export type VideosetOptions<Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>> = VideodirOptions<Accept, Alt> & {
+    /** The directory where videos are stored. Must start with "/public". */
+    dir: MediaDir;
+};
+/** See `ImagedirAltOption`: `alt` is optional only when it is the default. */
+type VideodirAltOption<Alt extends AltSchema> = [
     StringSchema<string | null>
 ] extends [Alt] ? {
     /**
@@ -26,25 +37,20 @@ type VideosetAltOption<Alt extends AltSchema> = [
     /** Description schema — required, because it is not the default one. */
     alt: Alt;
 };
-type VideosetOptionsBase<Accept extends `video/${string}`> = {
+/** See `ImagedirOptionsArg`: the options are optional only when `alt` is. */
+type VideodirOptionsArg<Accept extends `video/${string}`, Alt extends AltSchema> = [StringSchema<string | null>] extends [Alt] ? [options?: VideodirOptions<Accept, Alt>] : [options: VideodirOptions<Accept, Alt>];
+type VideodirOptionsBase<Accept extends `video/${string}`> = {
     /**
      * What may be UPLOADED, in `<input accept>` syntax. Must be a video type.
      * Not checked against an HLS stream: see `VideoOptions.accept`.
      * @default "video/*"
      */
     accept?: Accept;
-    /**
-     * The directory where videos are stored. Must start with "/public".
-     *
-     * Required for the same reason it is on `s.imageset()`: it decides where
-     * every upload in the set lands, and a default is a directory shared with
-     * every other set that did not say.
-     */
-    dir: "/public" | `/public/${string}`;
     /**
      * Turn every upload into an HLS stream, in the browser. See
-     * `VideoStreamOptions`. A field backed by this set (`s.video(videosVal)`)
-     * inherits it, as it inherits `accept` and `dir`.
+     * `VideoStreamOptions`. A field backed by this directory
+     * (`s.video(videosVal)`) inherits it, as it inherits `accept` and the
+     * directory.
      */
     stream?: VideoStreamOption;
 };
@@ -63,7 +69,7 @@ type VideosetOptionsBase<Accept extends `video/${string}`> = {
  * The poster is also the set's thumbnail of the entry: there is no separate
  * still for the gallery, because two stills of one video would disagree.
  */
-export type VideosetEntryMetadata<Alt extends AltSource = string | null> = {
+export type VideodirEntryMetadata<Alt extends AltSource = string | null> = {
     mimeType: string;
     width: number;
     height: number;
@@ -81,34 +87,38 @@ export type VideosetEntryMetadata<Alt extends AltSource = string | null> = {
     /** Overridden as a whole: a field with its own tracks has none of these. */
     captions?: readonly VideoCaptionSource[];
 };
-export type SerializedVideosetSchema = SerializedRecordSchema;
-type VideosetItemProps<Alt extends AltSchema> = {
+/** @deprecated Use `VideodirEntryMetadata`. */
+export type VideosetEntryMetadata<Alt extends AltSource = string | null> = VideodirEntryMetadata<Alt>;
+export type SerializedVideodirSchema = SerializedRecordSchema;
+/** @deprecated Use `SerializedVideodirSchema`. */
+export type SerializedVideosetSchema = SerializedVideodirSchema;
+type VideodirItemProps<Alt extends AltSchema> = {
     mimeType: StringSchema<string>;
     width: NumberSchema<number>;
     height: NumberSchema<number>;
     duration: NumberSchema<number>;
     alt: Alt;
 };
-type VideosetItemSrc<Alt extends AltSchema> = {
+type VideodirItemSrc<Alt extends AltSchema> = {
     mimeType: string;
     width: number;
     height: number;
     duration: number;
     alt: AltSourceOf<Alt>;
 };
+type VideodirSchema<Alt extends AltSchema> = RecordSchema<ObjectSchema<VideodirItemProps<Alt>, VideodirItemSrc<Alt>>, Schema<string>, Record<string, VideodirEntryMetadata<AltSourceOf<Alt>>>>;
 /**
- * Define a collection of videos — the video twin of `s.imageset()`.
+ * Define a directory of videos — the video twin of `s.imagedir()`.
  *
  * A field picks from it with `s.video(videosVal)`. An entry may hold the
  * description, poster, start and end, focal point and captions as defaults,
  * and a field overrides any of them by setting its own. Uploading in such a
- * field adds to the set. Call `.remote()` on the result
- * to store the set on Val Remote.
+ * field adds to the directory. Call `.remote()` on the result to store the
+ * videos on Val Remote.
  *
  * @example
  * ```typescript
- * const schema = s.videoset({
- *   dir: "/public/val/videos",
+ * const schema = s.videodir("/public/val/videos", {
  *   stream: { type: "hls" },
  * });
  * export default c.define("/content/videos.val.ts", schema, {
@@ -123,7 +133,25 @@ type VideosetItemSrc<Alt extends AltSchema> = {
  * });
  * ```
  */
-export declare const videoset: <Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>>(options: VideosetOptions<Accept, Alt>) => RecordSchema<ObjectSchema<VideosetItemProps<Alt>, VideosetItemSrc<Alt>>, Schema<string>, Record<string, VideosetEntryMetadata<AltSourceOf<Alt>>>>;
+export declare const videodir: <Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>>(dir: MediaDir, ...[options]: VideodirOptionsArg<Accept, Alt>) => VideodirSchema<Alt>;
+/**
+ * `s.videodir()` with `.remote()` applied: what `s.videodir` is under
+ * `files: { remote: true }`.
+ */
+export declare const remoteVideodir: <Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>>(dir: MediaDir, ...[options]: VideodirOptionsArg<Accept, Alt>) => VideodirSchema<Alt>;
+/**
+ * Define a collection of videos.
+ *
+ * @deprecated Use `s.videodir(dir, options)`: the directory moved out of the
+ * options and into the first argument, and nothing else changed.
+ *
+ * @example
+ * ```typescript
+ * // was: s.videoset({ dir: "/public/val/videos", stream: { type: "hls" } })
+ * const schema = s.videodir("/public/val/videos", { stream: { type: "hls" } });
+ * ```
+ */
+export declare const videoset: <Accept extends `video/${string}`, Alt extends AltSchema = StringSchema<string | null>>(options: VideosetOptions<Accept, Alt>) => VideodirSchema<Alt>;
 /**
  * The video schema a set's entry is hashed against, for a remote ref.
  *

package/dist/declarations/src/source/media.d.ts

@@ -81,7 +81,7 @@ export type VideoCaptionSource = {
  * What a video FIELD authors, on top of the file it names: the description,
  * the crop, the poster, the trim and the caption tracks.
  *
- * This is the whole value of a field picked from an `s.videoset()`
+ * This is the whole value of a field picked from an `s.videodir()`
  * (`s.video(videosetVal)`) — the mime type, size and length live in the set,
  * keyed by `path`, and repeating them here is how two copies of one fact get
  * to disagree. The poster, captions and times stay with the FIELD: one video
@@ -112,7 +112,7 @@ export type GalleryVideoSource = {
 /**
  * What one page chooses about a video — as opposed to what is true of the
  * file. A field (`s.video()`) carries these for itself; the entry of a set
- * (`s.videoset()`) carries them as DEFAULTS, which every field picked from the
+ * (`s.videodir()`) carries them as DEFAULTS, which every field picked from the
  * set starts from and may override key by key. See {@link fillFromGallery}.
  */
 export type VideoDefaults = Pick<GalleryVideoSource, "hotspot" | "posterTime" | "poster" | "startTime" | "endTime" | "captions">;
@@ -211,6 +211,27 @@ export type ResolvedVideo<S extends GalleryVideoSource = VideoSource> = Omit<S,
  * the poster's and the captions', which are not where an edit lands.
  */
 export declare function resolveVideo<S extends GalleryVideoSource>(src: S, videoUrl?: (src: S) => string): ResolvedVideo<S>;
+/**
+ * The key of a gallery (an `s.imagedir()`, `s.filedir()` or `s.videodir()`)
+ * that a field's `path` names, or `null` when it names none.
+ *
+ * Usually the path IS the key. It is not for an image uploaded THROUGH an
+ * `s.image(remoteGallery)` field in the Studio, which stores the remote ref in
+ * the field and keys the entry by the local path inside it — so a path that is
+ * not a key falls back to that embedded path. Exact first, because a gallery
+ * can hold both shapes for one file, and the field then names the entry that
+ * IS its path.
+ *
+ * One implementation of the question, asked by everything that has to agree on
+ * the answer: reading a field (`galleryEntryOf`), validating it (`ImageSchema`
+ * and `FileSchema` ask whether the gallery has it), the Studio's reference
+ * scans and renames, and `val validate --fix` when it renames a key and has to
+ * find the fields that hold it.
+ *
+ * The embedded path is tried with its leading slash (how a key is written) and
+ * without (how `splitRemoteRef` returns it).
+ */
+export declare function galleryKeyOf(path: string, isKey: (key: string) => boolean): string | null;
 /**
  * What a gallery entry holds as a DEFAULT for the fields picked from it, in
  * the groups a field overrides together.
@@ -226,7 +247,9 @@ export declare const GALLERY_DEFAULT_GROUPS: readonly (readonly string[])[];
  * gallery-backed or the gallery has no such entry.
  *
  * The double lookup is load-bearing: a remote gallery keys its entries by the
- * remote URL while the file itself stays on disk under its local path.
+ * remote URL while the file itself stays on disk under its local path, and an
+ * upload through the field does it the other way round (see
+ * {@link galleryKeyOf}).
  */
 export declare function galleryEntryOf(src: {
     readonly path: string;