@byline/core 3.13.3 → 3.14.0

package/dist/@types/field-types.d.ts

@@ -405,6 +405,27 @@ export interface RelationField extends NonlocalizableField {
      * summary. Falls back to the first text field if omitted.
      */
     displayField?: string;
+    /**
+     * When `true`, the field holds an **ordered list** of target references
+     * rather than a single one. The value shape becomes an array of relation
+     * envelopes (`RelatedDocumentValue[]`), persisted as indexed `store_relation`
+     * rows (`<field>.0`, `<field>.1`, …) and reconstructed in order. The admin
+     * widget renders an add / remove / drag-reorder list of summary tiles.
+     *
+     * A given target may appear at most once (the widget dedups on
+     * `targetDocumentId`). Defaults to single-target (`false` / absent).
+     */
+    hasMany?: boolean;
+    /**
+     * Minimum number of references required when `hasMany` is `true`. Enforced by
+     * the generated Zod schema. Ignored for single-target relations.
+     */
+    minItems?: number;
+    /**
+     * Maximum number of references allowed when `hasMany` is `true`. Enforced by
+     * the generated Zod schema. Ignored for single-target relations.
+     */
+    maxItems?: number;
 }
 export interface FileField extends NonlocalizableField {
     type: 'file';

package/dist/schemas/zod/builder.js

@@ -155,7 +155,7 @@ export const fieldToZodSchema = (field, strict = true) => {
             // (recursive) and is not constrained here.
             schema = z.any();
             break;
-        case 'relation':
+        case 'relation': {
             // Relation values are `RelatedDocumentValue` objects:
             //   { targetDocumentId, targetCollectionId,
             //     relationshipType?, cascadeDelete? }
@@ -165,15 +165,26 @@ export const fieldToZodSchema = (field, strict = true) => {
             //
             // Populated responses (depth > 0) skip this schema in the route layer
             // because the tree then contains nested documents, not bare refs.
-            schema = z
-                .object({
+            const relationValue = z.object({
                 targetDocumentId: z.string(),
                 targetCollectionId: z.string(),
                 relationshipType: z.string().optional(),
                 cascadeDelete: z.boolean().optional(),
-            })
-                .nullable();
+            });
+            if (field.hasMany) {
+                // Ordered list of relation values; `minItems` / `maxItems` bound it.
+                let arr = z.array(relationValue);
+                if (typeof field.minItems === 'number')
+                    arr = arr.min(field.minItems);
+                if (typeof field.maxItems === 'number')
+                    arr = arr.max(field.maxItems);
+                schema = arr;
+            }
+            else {
+                schema = relationValue.nullable();
+            }
             break;
+        }
         default:
             schema = z.string();
     }

package/dist/services/populate.js

@@ -317,6 +317,24 @@ function collectRelationLeaves(fields, fieldDefs, populate, acc) {
         const sub = matchesPopulate(leaf.field.name, populate);
         if (sub === undefined)
             continue;
+        // hasMany: the value is an ordered array of relation envelopes. Expand it
+        // into one leaf ref per element, whose `parent` is the array itself and
+        // `key` is the index — so the envelope-assignment pass writes each
+        // populated result back into its array slot, in place.
+        if (leaf.field.hasMany) {
+            if (!Array.isArray(leaf.value))
+                continue;
+            const arr = leaf.value;
+            for (let i = 0; i < arr.length; i++) {
+                const item = arr[i];
+                if (!isRelatedDocumentValue(item))
+                    continue;
+                if ('_resolved' in item)
+                    continue;
+                acc.push({ parent: arr, key: String(i), field: leaf.field, value: item, sub });
+            }
+            continue;
+        }
         if (!isRelatedDocumentValue(leaf.value))
             continue;
         // Skip leaves that have already been replaced (e.g. via shared-ref

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.13.3",
+  "version": "3.14.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.13.3"
+    "@byline/auth": "3.14.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",