@byline/core 3.16.1 → 3.17.1

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

@@ -71,6 +71,21 @@ export interface FieldHookContext {
      * derived value at submit time while showing advisory errors on change.
      */
     operation: 'change' | 'submit';
+    /**
+     * Write **another** field's value in the form store.
+     *
+     * This is a raw write: the target field's own hooks do NOT run (which
+     * forecloses hook recursion), but the write is otherwise a normal form
+     * edit — it emits a `field.set` patch (so it persists on save), marks the
+     * form dirty, and store-subscribed widgets re-render immediately.
+     *
+     * Use for cross-field behaviour such as mutual exclusivity across array
+     * items (a checkbox that unchecks its siblings) or clearing a dependent
+     * field when its driver changes. Paths use the same dot + bracket
+     * notation as `FieldHookContext.path`, e.g.
+     * `files[1].filesGroup.generateThumbnail`.
+     */
+    setFieldValue: (path: string, value: any) => void;
 }
 /**
  * Return type of `beforeValidate` hooks.
@@ -140,6 +155,17 @@ export interface ValidationRule {
     message?: string;
 }
 type FieldValidateFn = (value: any, data: Record<string, any>) => string | undefined;
+/**
+ * Visibility predicate for a field — see {@link BaseField.condition}.
+ *
+ * @param data - The full live form data (the document's field values).
+ * @param siblingData - The field's immediate scope: the enclosing group /
+ *   array item's values. For a field at `files[2].filesGroup.thumbnailPage`
+ *   this is the item's `filesGroup` object, so conditions inside array items
+ *   observe their own item, not the document root. For root-level fields
+ *   `siblingData` is the same object as `data`.
+ */
+export type FieldCondition = (data: Record<string, any>, siblingData: Record<string, any>) => boolean;
 /**
  * Base properties shared by all fields
  */
@@ -178,6 +204,23 @@ interface BaseField {
      * @see FieldHooks
      */
     hooks?: FieldHooks;
+    /**
+     * Optional visibility condition. When provided, the admin form renders
+     * this field only while the function returns `true`. Receives the full
+     * live form data plus the field's sibling scope (the enclosing group /
+     * array item), and is re-evaluated on every form edit — so a field can
+     * appear and disappear in response to its neighbours, e.g.
+     *
+     *     condition: (_data, siblingData) => Boolean(siblingData.generateThumbnail)
+     *
+     * Like `readOnly`, this is a **rendering hint only** — it is not enforced
+     * server-side. While hidden, the field's stored value is retained (no
+     * clearing write is emitted) and the field is exempt from client-side
+     * validation. Server-side schema validation knows nothing about
+     * conditions, so pair conditionally-hidden required fields with
+     * `optional: true` or a `defaultValue`.
+     */
+    condition?: FieldCondition;
     /**
      * Optional submit-time validator. Called by `validateForm()` for every field
      * type — including structure fields (group, array, blocks).

package/dist/services/document-lifecycle/delete.js

@@ -9,7 +9,8 @@ import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
-import { getUploadFields } from '../../utils/storage-utils.js';
+import { hasUploadField, isUploadField } from '../../utils/storage-utils.js';
+import { walkFieldTree } from '../walk-field-tree.js';
 import { AUDIT_ACTIONS, auditActor, requireAuditCapability } from './audit.js';
 import { invokeHook } from './internals.js';
 import { promoteChildrenAndRemove } from './tree.js';
@@ -46,8 +47,7 @@ export async function deleteDocument(ctx, params) {
         //    AND a storage provider, fetch with reconstruct: true so we
         //    can read the stored file paths (and persisted variant paths)
         //    from the field values before the DB rows are deleted.
-        const uploadFieldNames = getUploadFields(definition).map((f) => f.name);
-        const isUploadCollection = uploadFieldNames.length > 0 && ctx.storage != null;
+        const isUploadCollection = hasUploadField(definition) && ctx.storage != null;
         const latest = await db.queries.documents.getDocumentById({
             collection_id: ctx.collectionId,
             document_id: params.documentId,
@@ -60,21 +60,27 @@ export async function deleteDocument(ctx, params) {
             }).log(ctx.logger);
         }
         // Collect storage paths for every upload-capable field on the doc:
-        // the original file plus every persisted variant. Reading the
+        // the original file plus every persisted variant. The schema/data
+        // walk descends into `group` / `array` / `blocks`, so upload fields
+        // nested in repeating structures are cleaned up too. Reading the
         // variants from the field value (rather than re-deriving from
         // `upload.sizes`) keeps cleanup correct even when the size set
         // changes between upload and delete.
         const storagePathsToDelete = [];
         if (isUploadCollection) {
-            for (const fieldName of uploadFieldNames) {
-                const fieldValue = latest?.fields?.[fieldName];
+            const data = latest?.fields;
+            for (const leaf of walkFieldTree(definition.fields, data)) {
+                if (!isUploadField(leaf.field))
+                    continue;
+                const fieldValue = leaf.value;
                 if (!fieldValue || typeof fieldValue !== 'object')
                     continue;
-                if (typeof fieldValue.storagePath === 'string') {
-                    storagePathsToDelete.push(fieldValue.storagePath);
+                const stored = fieldValue;
+                if (typeof stored.storagePath === 'string') {
+                    storagePathsToDelete.push(stored.storagePath);
                 }
-                if (Array.isArray(fieldValue.variants)) {
-                    for (const variant of fieldValue.variants) {
+                if (Array.isArray(stored.variants)) {
+                    for (const variant of stored.variants) {
                         if (variant && typeof variant.storagePath === 'string') {
                             storagePathsToDelete.push(variant.storagePath);
                         }

package/dist/services/document-lifecycle.test.node.js

@@ -926,6 +926,58 @@ describe('Document lifecycle service', () => {
                 action: 'document.deleted',
             }));
         });
+        it('cleans up stored files for upload fields at any nesting depth', async () => {
+            const { db, getDocumentById } = createMockDb();
+            const upload = { mimeTypes: ['application/pdf'], maxFileSize: 1024 };
+            const definition = {
+                ...minimalCollection,
+                fields: [
+                    { name: 'cover', label: 'Cover', type: 'image', upload },
+                    {
+                        name: 'files',
+                        label: 'Files',
+                        type: 'array',
+                        fields: [
+                            {
+                                name: 'filesGroup',
+                                type: 'group',
+                                fields: [{ name: 'publicationFile', label: 'File', type: 'file', upload }],
+                            },
+                        ],
+                    },
+                ],
+            };
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-1',
+                document_id: 'doc-1',
+                path: 'doc-to-delete',
+                fields: {
+                    cover: {
+                        storagePath: 'covers/original.jpg',
+                        variants: [{ storagePath: 'covers/thumb.avif' }],
+                    },
+                    files: [
+                        { filesGroup: { publicationFile: { storagePath: 'files/a.pdf' } } },
+                        { filesGroup: { publicationFile: null } },
+                        { filesGroup: { publicationFile: { storagePath: 'files/b.pdf' } } },
+                    ],
+                },
+            });
+            const storageDelete = vi.fn().mockResolvedValue(undefined);
+            const ctx = {
+                ...buildCtx(db, definition),
+                storage: { delete: storageDelete },
+            };
+            await deleteDocument(ctx, { documentId: 'doc-1' });
+            // reconstruct: true because the collection is upload-capable
+            expect(getDocumentById).toHaveBeenCalledWith(expect.objectContaining({ reconstruct: true }));
+            expect(storageDelete.mock.calls.map((c) => c[0])).toEqual([
+                'covers/original.jpg',
+                'covers/thumb.avif',
+                'files/a.pdf',
+                'files/b.pdf',
+            ]);
+        });
     });
     // -----------------------------------------------------------------------
     // updateDocumentSystemFields (audited, non-versioned)

package/dist/utils/storage-utils.d.ts

@@ -5,8 +5,8 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { type Field, type FileField, type ImageField } from '../@types/field-types.js';
 import type { CollectionDefinition } from '../@types/collection-types.js';
-import type { Field, FileField, ImageField } from '../@types/field-types.js';
 /**
  * Predicate: does this field carry an `upload` config? True for any
  * `image` / `file` field with an `upload` block declared.
@@ -15,20 +15,21 @@ export declare function isUploadField(field: Field): field is (ImageField | File
     upload: NonNullable<(ImageField | FileField)['upload']>;
 };
 /**
- * Walk the top-level field set and return every upload-capable
- * image/file field on the collection. Used by the delete path,
- * the upload-route resolver, and any UI that needs to reason about
- * "is this collection upload-capable, and which fields take uploads?"
+ * Walk the field set and return every upload-capable image/file field
+ * on the collection, recursing into `group` / `array` / `blocks`
+ * structure fields. Used by the delete path, the upload-route resolver,
+ * and any UI that needs to reason about "is this collection
+ * upload-capable, and which fields take uploads?"
  *
- * Does not recurse into `group` / `array` / `blocks` — the supported
- * transport surface is top-level upload fields. Nested upload fields
- * are reachable through the core upload service via `findUploadField`,
- * but require a richer transport selector.
+ * Field names are the upload transport's selector, so a schema should
+ * not declare two upload fields with the same name in different nesting
+ * scopes — resolvers match by name and take the first hit in
+ * declaration order.
  */
 export declare function getUploadFields(definition: Pick<CollectionDefinition, 'fields'>): (ImageField | FileField)[];
 /**
  * Convenience: does this collection have at least one upload-capable
- * image/file field at the top level? Replaces the old
+ * image/file field at any nesting depth? Replaces the old
  * `definition.upload != null` discriminator that "this collection is
  * an upload collection / media library."
  */

package/dist/utils/storage-utils.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { isArrayField, isBlocksField, isGroupField, } from '../@types/field-types.js';
 /**
  * Predicate: does this field carry an `upload` config? True for any
  * `image` / `file` field with an `upload` block declared.
@@ -13,25 +14,43 @@ export function isUploadField(field) {
     return (field.type === 'image' || field.type === 'file') && field.upload != null;
 }
 /**
- * Walk the top-level field set and return every upload-capable
- * image/file field on the collection. Used by the delete path,
- * the upload-route resolver, and any UI that needs to reason about
- * "is this collection upload-capable, and which fields take uploads?"
+ * Walk the field set and return every upload-capable image/file field
+ * on the collection, recursing into `group` / `array` / `blocks`
+ * structure fields. Used by the delete path, the upload-route resolver,
+ * and any UI that needs to reason about "is this collection
+ * upload-capable, and which fields take uploads?"
  *
- * Does not recurse into `group` / `array` / `blocks` — the supported
- * transport surface is top-level upload fields. Nested upload fields
- * are reachable through the core upload service via `findUploadField`,
- * but require a richer transport selector.
+ * Field names are the upload transport's selector, so a schema should
+ * not declare two upload fields with the same name in different nesting
+ * scopes — resolvers match by name and take the first hit in
+ * declaration order.
  */
 export function getUploadFields(definition) {
-    return definition.fields.filter(isUploadField);
+    const found = [];
+    collectUploadFields(definition.fields, found);
+    return found;
+}
+function collectUploadFields(fields, found) {
+    for (const field of fields) {
+        if (isUploadField(field)) {
+            found.push(field);
+        }
+        else if (isGroupField(field) || isArrayField(field)) {
+            collectUploadFields(field.fields, found);
+        }
+        else if (isBlocksField(field)) {
+            for (const block of field.blocks) {
+                collectUploadFields(block.fields, found);
+            }
+        }
+    }
 }
 /**
  * Convenience: does this collection have at least one upload-capable
- * image/file field at the top level? Replaces the old
+ * image/file field at any nesting depth? Replaces the old
  * `definition.upload != null` discriminator that "this collection is
  * an upload collection / media library."
  */
 export function hasUploadField(definition) {
-    return definition.fields.some(isUploadField);
+    return getUploadFields(definition).length > 0;
 }

package/dist/utils/storage-utils.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/utils/storage-utils.test.node.js

@@ -0,0 +1,90 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { getUploadFields, hasUploadField, isUploadField } from './storage-utils.js';
+const upload = { mimeTypes: ['application/pdf'], maxFileSize: 1024 };
+const coverField = { name: 'cover', label: 'Cover', type: 'image', upload };
+const nestedFileField = { name: 'publicationFile', label: 'File', type: 'file', upload };
+describe('isUploadField', () => {
+    it('is true for image/file fields with an upload block', () => {
+        expect(isUploadField(coverField)).toBe(true);
+        expect(isUploadField(nestedFileField)).toBe(true);
+    });
+    it('is false for image/file fields without an upload block', () => {
+        expect(isUploadField({ name: 'pic', label: 'Pic', type: 'image' })).toBe(false);
+        expect(isUploadField({ name: 'doc', label: 'Doc', type: 'file' })).toBe(false);
+    });
+    it('is false for non-media fields', () => {
+        expect(isUploadField({ name: 'title', label: 'Title', type: 'text' })).toBe(false);
+    });
+});
+describe('getUploadFields', () => {
+    it('returns top-level upload fields', () => {
+        const fields = [{ name: 'title', label: 'Title', type: 'text' }, coverField];
+        expect(getUploadFields({ fields }).map((f) => f.name)).toEqual(['cover']);
+    });
+    it('recurses into group / array / blocks structure fields', () => {
+        const fields = [
+            coverField,
+            {
+                name: 'files',
+                label: 'Files',
+                type: 'array',
+                fields: [
+                    {
+                        name: 'filesGroup',
+                        type: 'group',
+                        fields: [nestedFileField, { name: 'label', label: 'Label', type: 'text' }],
+                    },
+                ],
+            },
+            {
+                name: 'content',
+                label: 'Content',
+                type: 'blocks',
+                blocks: [
+                    {
+                        blockType: 'photo',
+                        label: 'Photo',
+                        fields: [{ name: 'photo', label: 'Photo', type: 'image', upload }],
+                    },
+                ],
+            },
+        ];
+        expect(getUploadFields({ fields }).map((f) => f.name)).toEqual([
+            'cover',
+            'publicationFile',
+            'photo',
+        ]);
+    });
+    it('skips nested image/file fields without an upload block', () => {
+        const fields = [
+            {
+                name: 'gallery',
+                label: 'Gallery',
+                type: 'group',
+                fields: [{ name: 'pic', label: 'Pic', type: 'image' }],
+            },
+        ];
+        expect(getUploadFields({ fields })).toEqual([]);
+    });
+});
+describe('hasUploadField', () => {
+    it('detects upload fields at any nesting depth', () => {
+        const fields = [
+            {
+                name: 'files',
+                label: 'Files',
+                type: 'array',
+                fields: [{ name: 'filesGroup', type: 'group', fields: [nestedFileField] }],
+            },
+        ];
+        expect(hasUploadField({ fields })).toBe(true);
+        expect(hasUploadField({ fields: [{ name: 'title', label: 'Title', type: 'text' }] })).toBe(false);
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.16.1",
+  "version": "3.17.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -76,7 +76,7 @@
     "pino": "^10.3.1",
     "sharp": "^0.34.5",
     "zod": "^4.4.3",
-    "@byline/auth": "3.16.1"
+    "@byline/auth": "3.17.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",