@byline/admin 3.18.0 → 3.19.0

package/dist/fields/file/file-field.js

@@ -25,7 +25,7 @@ const FileField = ({ field, collectionPath, value, defaultValue, onChange: _onCh
     const isDirty = useIsDirty(fieldPath);
     const fieldValue = useFieldValue(fieldPath);
     const isUploading = useIsFieldUploading(fieldPath);
-    const { removePendingUpload } = useFormContext();
+    const { removePendingUpload, documentId } = useFormContext();
     const handleChange = useFieldChangeHandler(field, fieldPath);
     const incomingValue = isDirty ? fieldValue ?? null : value ?? fieldValue ?? defaultValue ?? null;
     const isPending = isPendingStoredFileValue(incomingValue);
@@ -35,6 +35,7 @@ const FileField = ({ field, collectionPath, value, defaultValue, onChange: _onCh
         return 'placeholder' === maybe.storageProvider && 'pending' === maybe.storagePath;
     };
     const showUploadWidget = null == incomingValue || isOldPlaceholder(incomingValue);
+    const uploadGated = field.upload?.requireSavedDocument === true && null == documentId;
     const handleRemove = ()=>{
         if (isPending) removePendingUpload(fieldPath);
         handleChange(null);
@@ -54,7 +55,12 @@ const FileField = ({ field, collectionPath, value, defaultValue, onChange: _onCh
                     required: !field.optional
                 })
             }),
-            showUploadWidget ? collectionPath ? /*#__PURE__*/ jsx(FileUploadField, {
+            showUploadWidget ? uploadGated ? /*#__PURE__*/ jsx("div", {
+                className: classnames('byline-field-file-empty', file_field_module.empty),
+                role: "note",
+                "data-testid": "upload-require-saved-document",
+                children: t('fields.upload.requireSavedDocument')
+            }) : collectionPath ? /*#__PURE__*/ jsx(FileUploadField, {
                 field: field,
                 collectionPath: collectionPath,
                 fieldPath: fieldPath,

package/dist/fields/image/image-field.js

@@ -14,7 +14,7 @@ const ImageField = ({ field, collectionPath, value, defaultValue, onChange: _onC
     const isDirty = useIsDirty(fieldPath);
     const fieldValue = useFieldValue(fieldPath);
     const isUploading = useIsFieldUploading(fieldPath);
-    const { removePendingUpload } = useFormContext();
+    const { removePendingUpload, documentId } = useFormContext();
     const { t } = useTranslation('byline-admin');
     const handleChange = useFieldChangeHandler(field, fieldPath);
     const incomingValue = isDirty ? fieldValue ?? null : value ?? fieldValue ?? defaultValue ?? null;
@@ -25,6 +25,7 @@ const ImageField = ({ field, collectionPath, value, defaultValue, onChange: _onC
         return 'placeholder' === maybe.storageProvider && 'pending' === maybe.storagePath;
     };
     const showUploadWidget = null == incomingValue || isOldPlaceholder(incomingValue);
+    const uploadGated = field.upload?.requireSavedDocument === true && null == documentId;
     const thumbVariant = incomingValue && !isPendingStoredFileValue(incomingValue) ? incomingValue.variants?.find((v)=>'thumbnail' === v.name) : void 0;
     const previewUrl = thumbVariant?.storageUrl ?? incomingValue?.storageUrl;
     const handleRemove = ()=>{
@@ -46,7 +47,12 @@ const ImageField = ({ field, collectionPath, value, defaultValue, onChange: _onC
                     required: !field.optional
                 })
             }),
-            showUploadWidget ? collectionPath ? /*#__PURE__*/ jsx(ImageUploadField, {
+            showUploadWidget ? uploadGated ? /*#__PURE__*/ jsx("div", {
+                className: classnames('byline-field-image-empty', image_field_module.empty),
+                role: "note",
+                "data-testid": "upload-require-saved-document",
+                children: t('fields.upload.requireSavedDocument')
+            }) : collectionPath ? /*#__PURE__*/ jsx(ImageUploadField, {
                 field: field,
                 collectionPath: collectionPath,
                 fieldPath: fieldPath,

package/dist/forms/form-context.d.ts

@@ -48,6 +48,13 @@ export interface DirtyBreakdown {
     availableLocalesDirty: boolean;
 }
 interface FormContextType {
+    /**
+     * The persisted document id when the form edits an existing document,
+     * `null` while the document is unsaved (create mode). Upload widgets use
+     * this to honour `upload.requireSavedDocument` (see `UploadConfig` in
+     * `@byline/core`).
+     */
+    documentId: string | null;
     setFieldValue: (name: string, value: any) => void;
     setFieldStore: (name: string, value: any) => void;
     getFieldValue: (name: string) => any;
@@ -90,9 +97,14 @@ interface FormContextType {
     subscribeSystemAvailableLocales: (listener: SystemAvailableLocalesListener) => () => void;
 }
 export declare const useFormContext: () => FormContextType;
-export declare const FormProvider: ({ children, initialData, }: {
+export declare const FormProvider: ({ children, initialData, documentId, }: {
     children: React.ReactNode;
     initialData?: Record<string, any>;
+    /**
+     * The persisted document id (edit mode); `null` while unsaved. Exposed on
+     * the context for upload widgets honouring `upload.requireSavedDocument`.
+     */
+    documentId?: string | null;
 }) => React.JSX.Element;
 /**
  * Subscribe to the system `path` slot edited by the path widget.

package/dist/forms/form-context.js

@@ -22,7 +22,7 @@ const useFormContext = ()=>{
     if (null == context) throw new Error('useFormContext must be used within a FormProvider');
     return context;
 };
-const FormProvider = ({ children, initialData = {} })=>{
+const FormProvider = ({ children, initialData = {}, documentId = null })=>{
     const fieldValues = useRef(JSON.parse(JSON.stringify(initialData?.fields ?? initialData)));
     const initialValues = useRef(initialData?.fields ?? initialData);
     const errorsRef = useRef([]);
@@ -376,6 +376,7 @@ const FormProvider = ({ children, initialData = {} })=>{
     ]);
     return /*#__PURE__*/ jsx(FormContext.Provider, {
         value: {
+            documentId,
             setFieldValue,
             setFieldStore,
             getFieldValue,

package/dist/forms/form-renderer.js

@@ -122,6 +122,10 @@ const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpub
                 try {
                     const uploadResult = await executeUploadsWithProgress(pendingUploads, uploadField, ({ fieldPath, status })=>{
                         setFieldUploading(fieldPath, 'uploading' === status);
+                    }, {
+                        documentId: 'edit' === mode && 'string' == typeof initialData?.id ? initialData.id : void 0,
+                        fields,
+                        getFormValues: getFieldValues
                     });
                     if (!uploadResult.allSucceeded) {
                         for (const [fieldPath, errorMessage] of uploadResult.errors.entries())setFieldError(fieldPath, t('forms.uploadFailedFieldError', {
@@ -398,6 +402,7 @@ const FormRenderer = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpu
     const savedTabsRef = useRef({});
     return /*#__PURE__*/ jsx(FormProvider, {
         initialData: initialData,
+        documentId: 'edit' === mode && 'string' == typeof initialData?.id ? initialData.id : null,
         children: /*#__PURE__*/ jsx(FormContent, {
             mode: mode,
             fields: fields,

package/dist/forms/upload-executor.d.ts

@@ -12,7 +12,7 @@
  * This enables "deferred uploads" — files are selected/previewed immediately
  * but only uploaded when the user clicks Save.
  */
-import type { StoredFileValue } from '@byline/core';
+import type { Field, StoredFileValue } from '@byline/core';
 import type { UploadFieldFn } from '../fields/field-services-types';
 import type { PendingUpload } from './form-context';
 export interface UploadResult {
@@ -31,6 +31,28 @@ export interface ExecuteUploadsResult {
     /** Whether all uploads succeeded */
     allSucceeded: boolean;
 }
+/**
+ * Optional document context threaded from the form renderer so upload
+ * requests carry the state that server-side `beforeStore` / `afterStore`
+ * hooks need (see `UploadConfig.context` in `@byline/core`).
+ */
+export interface UploadExecutionContext {
+    /**
+     * The persisted document id (edit mode). Posted as `documentId` on every
+     * upload request; omitted while the document is unsaved (create mode).
+     */
+    documentId?: string;
+    /**
+     * The collection's schema fields — used to locate each upload field's
+     * `upload.context` declaration by walking the pending upload's field path.
+     */
+    fields?: readonly Field[];
+    /**
+     * Snapshot accessor for the live form values, resolved lazily per upload
+     * so context reflects the state at the moment the request is built.
+     */
+    getFormValues?: () => Record<string, any>;
+}
 /**
  * Execute all pending uploads sequentially.
  * Returns a result object with successful uploads and any errors.
@@ -38,9 +60,11 @@ export interface ExecuteUploadsResult {
  * @param pendingUploads - Map of field path to PendingUpload
  * @param uploadField - Host-provided upload transport (resolved via
  *                         `useBylineFieldServices()` in the calling React tree)
+ * @param executionContext - Optional document/form context appended to each
+ *                         upload request (documentId, `upload.context` values)
  * @returns Promise resolving to ExecuteUploadsResult
  */
-export declare function executeUploads(pendingUploads: Map<string, PendingUpload>, uploadField: UploadFieldFn): Promise<ExecuteUploadsResult>;
+export declare function executeUploads(pendingUploads: Map<string, PendingUpload>, uploadField: UploadFieldFn, executionContext?: UploadExecutionContext): Promise<ExecuteUploadsResult>;
 /**
  * Progress callback type for upload execution with progress tracking.
  */
@@ -54,4 +78,4 @@ export type UploadProgressCallback = (info: {
  * Execute uploads with progress callbacks.
  * Useful for showing upload progress in the UI.
  */
-export declare function executeUploadsWithProgress(pendingUploads: Map<string, PendingUpload>, uploadField: UploadFieldFn, onProgress?: UploadProgressCallback): Promise<ExecuteUploadsResult>;
+export declare function executeUploadsWithProgress(pendingUploads: Map<string, PendingUpload>, uploadField: UploadFieldFn, onProgress?: UploadProgressCallback, executionContext?: UploadExecutionContext): Promise<ExecuteUploadsResult>;

package/dist/forms/upload-executor.js

@@ -1,11 +1,10 @@
-async function executeUploads(pendingUploads, uploadField) {
+import { get } from "./nested-path.js";
+async function executeUploads(pendingUploads, uploadField, executionContext) {
     const results = [];
     const successful = new Map();
     const errors = new Map();
     for (const [fieldPath, upload] of pendingUploads.entries()){
-        const formData = new FormData();
-        formData.append('file', upload.file);
-        formData.append('field', uploadFieldName(fieldPath));
+        const formData = buildUploadFormData(fieldPath, upload, executionContext);
         try {
             const result = await uploadField(upload.collectionPath, formData, false);
             results.push({
@@ -31,11 +30,89 @@ async function executeUploads(pendingUploads, uploadField) {
         allSucceeded: 0 === errors.size
     };
 }
+function buildUploadFormData(fieldPath, upload, executionContext) {
+    const formData = new FormData();
+    formData.append('file', upload.file);
+    formData.append('field', uploadFieldName(fieldPath));
+    formData.append('fieldPath', fieldPath);
+    if (executionContext?.documentId) formData.append('documentId', executionContext.documentId);
+    const contextPaths = executionContext?.fields != null ? findUploadFieldByPath(executionContext.fields, fieldPath)?.context : void 0;
+    if (contextPaths && contextPaths.length > 0 && executionContext?.getFormValues) {
+        const formValues = executionContext.getFormValues();
+        for (const contextPath of contextPaths){
+            const resolvedPath = resolveContextPath(fieldPath, contextPath);
+            if (void 0 === resolvedPath) continue;
+            const value = '' === resolvedPath ? formValues : get(formValues, resolvedPath);
+            const serialized = serializeContextValue(value);
+            if (void 0 !== serialized) formData.append(leafName(contextPath), serialized);
+        }
+    }
+    return formData;
+}
 function uploadFieldName(fieldPath) {
     const dot = fieldPath.lastIndexOf('.');
     return -1 === dot ? fieldPath : fieldPath.slice(dot + 1);
 }
-async function executeUploadsWithProgress(pendingUploads, uploadField, onProgress) {
+function leafName(contextPath) {
+    const segments = contextPath.split('/').pop() ?? contextPath;
+    const dot = segments.lastIndexOf('.');
+    return -1 === dot ? segments : segments.slice(dot + 1);
+}
+function resolveContextPath(fieldPath, contextPath) {
+    if (contextPath.startsWith('/')) return contextPath.slice(1);
+    const scope = fieldPath.split('.');
+    scope.pop();
+    const parts = contextPath.split('/');
+    const leaf = parts.pop() ?? '';
+    for (const part of parts)if ('.' !== part && '' !== part) {
+        if ('..' === part) {
+            if (0 === scope.length) return;
+            scope.pop();
+            continue;
+        }
+        scope.push(part);
+    }
+    return 0 === scope.length ? leaf : `${scope.join('.')}${leaf ? `.${leaf}` : ''}`;
+}
+function serializeContextValue(value) {
+    if (null == value) return;
+    if ('string' == typeof value) return value;
+    if ('number' == typeof value || 'boolean' == typeof value) return String(value);
+    if (isRelationEnvelope(value)) return value.targetDocumentId;
+    if (Array.isArray(value) && value.length > 0 && value.every(isRelationEnvelope)) return value.map((v)=>v.targetDocumentId).join(',');
+    try {
+        return JSON.stringify(value);
+    } catch  {
+        return;
+    }
+}
+function isRelationEnvelope(value) {
+    return 'object' == typeof value && null !== value && 'string' == typeof value.targetDocumentId;
+}
+function findUploadFieldByPath(fields, fieldPath) {
+    const segments = fieldPath.split('.').map((s)=>s.replace(/\[\d+\]$/, ''));
+    let currentFields = fields;
+    for(let i = 0; i < segments.length; i++){
+        const name = segments[i];
+        const isLeaf = i === segments.length - 1;
+        const field = currentFields.find((f)=>f.name === name);
+        if (!field) break;
+        if (isLeaf) return 'image' === field.type || 'file' === field.type ? field.upload : void 0;
+        if ('group' === field.type || 'array' === field.type) {
+            currentFields = field.fields;
+            continue;
+        }
+        if ('blocks' === field.type) {
+            const remaining = segments[i + 1];
+            const block = field.blocks.find((b)=>b.fields.some((f)=>f.name === remaining));
+            if (!block) return;
+            currentFields = block.fields;
+            continue;
+        }
+        break;
+    }
+}
+async function executeUploadsWithProgress(pendingUploads, uploadField, onProgress, executionContext) {
     const results = [];
     const successful = new Map();
     const errors = new Map();
@@ -51,9 +128,7 @@ async function executeUploadsWithProgress(pendingUploads, uploadField, onProgres
             fieldPath,
             status: 'uploading'
         });
-        const formData = new FormData();
-        formData.append('file', upload.file);
-        formData.append('field', uploadFieldName(fieldPath));
+        const formData = buildUploadFormData(fieldPath, upload, executionContext);
         try {
             const result = await uploadField(upload.collectionPath, formData, false);
             results.push({

package/dist/forms/upload-executor.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/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -155,10 +155,10 @@
     "react-diff-viewer-continued": "^4.2.2",
     "uuid": "^14.0.1",
     "zod": "^4.4.3",
-    "@byline/auth": "3.18.0",
-    "@byline/i18n": "3.18.0",
-    "@byline/ui": "3.18.0",
-    "@byline/core": "3.18.0"
+    "@byline/auth": "3.19.0",
+    "@byline/ui": "3.19.0",
+    "@byline/core": "3.19.0",
+    "@byline/i18n": "3.19.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/fields/file/file-field.tsx

@@ -79,7 +79,7 @@ export const FileField = ({
   const isDirty = useIsDirty(fieldPath)
   const fieldValue = useFieldValue<StoredFileValue | null | undefined>(fieldPath)
   const isUploading = useIsFieldUploading(fieldPath)
-  const { removePendingUpload } = useFormContext()
+  const { removePendingUpload, documentId } = useFormContext()
 
   const handleChange = useFieldChangeHandler(field, fieldPath)
 
@@ -102,6 +102,12 @@ export const FileField = ({
 
   const showUploadWidget = incomingValue == null || isOldPlaceholder(incomingValue)
 
+  // `upload.requireSavedDocument` gate: until the document is persisted,
+  // render a "save first" notice in place of the upload zone. Server-side
+  // upload hooks that depend on save-time state (counters, document id)
+  // rely on this; existing stored values still render normally below.
+  const uploadGated = field.upload?.requireSavedDocument === true && documentId == null
+
   const handleRemove = () => {
     if (isPending) {
       removePendingUpload(fieldPath)
@@ -131,7 +137,15 @@ export const FileField = ({
       </div>
 
       {showUploadWidget ? (
-        collectionPath ? (
+        uploadGated ? (
+          <div
+            className={cx('byline-field-file-empty', styles.empty)}
+            role="note"
+            data-testid="upload-require-saved-document"
+          >
+            {t('fields.upload.requireSavedDocument')}
+          </div>
+        ) : collectionPath ? (
           <FileUploadField
             field={field}
             collectionPath={collectionPath}

package/src/fields/image/image-field.tsx

@@ -61,7 +61,7 @@ export const ImageField = ({
   const isDirty = useIsDirty(fieldPath)
   const fieldValue = useFieldValue<StoredFileValue | null | undefined>(fieldPath)
   const isUploading = useIsFieldUploading(fieldPath)
-  const { removePendingUpload } = useFormContext()
+  const { removePendingUpload, documentId } = useFormContext()
   const { t } = useTranslation('byline-admin')
 
   // Re-use the standard field change handler so patches are emitted correctly.
@@ -87,6 +87,12 @@ export const ImageField = ({
   // Show upload widget only if no value or old placeholder
   const showUploadWidget = incomingValue == null || isOldPlaceholder(incomingValue)
 
+  // `upload.requireSavedDocument` gate: until the document is persisted,
+  // render a "save first" notice in place of the upload zone. Server-side
+  // upload hooks that depend on save-time state (counters, document id)
+  // rely on this; existing stored values still render normally below.
+  const uploadGated = field.upload?.requireSavedDocument === true && documentId == null
+
   // Prefer the generated thumbnail variant for the preview tile. SVGs and
   // other bypass types have no variants — fall back to the original.
   const thumbVariant =
@@ -122,7 +128,15 @@ export const ImageField = ({
       </div>
 
       {showUploadWidget ? (
-        collectionPath ? (
+        uploadGated ? (
+          <div
+            className={cx('byline-field-image-empty', styles.empty)}
+            role="note"
+            data-testid="upload-require-saved-document"
+          >
+            {t('fields.upload.requireSavedDocument')}
+          </div>
+        ) : collectionPath ? (
           <ImageUploadField
             field={field}
             collectionPath={collectionPath}

package/src/forms/form-context.tsx

@@ -83,6 +83,13 @@ const SYSTEM_PATH_DIRTY_KEY = '__systemPath__'
 const SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY = '__systemAvailableLocales__'
 
 interface FormContextType {
+  /**
+   * The persisted document id when the form edits an existing document,
+   * `null` while the document is unsaved (create mode). Upload widgets use
+   * this to honour `upload.requireSavedDocument` (see `UploadConfig` in
+   * `@byline/core`).
+   */
+  documentId: string | null
   setFieldValue: (name: string, value: any) => void
   setFieldStore: (name: string, value: any) => void
   getFieldValue: (name: string) => any
@@ -150,9 +157,15 @@ export const useFormContext = () => {
 export const FormProvider = ({
   children,
   initialData = {},
+  documentId = null,
 }: {
   children: React.ReactNode
   initialData?: Record<string, any>
+  /**
+   * The persisted document id (edit mode); `null` while unsaved. Exposed on
+   * the context for upload widgets honouring `upload.requireSavedDocument`.
+   */
+  documentId?: string | null
 }) => {
   const fieldValues = useRef<Record<string, any>>(
     JSON.parse(JSON.stringify(initialData?.fields ?? initialData))
@@ -640,6 +653,7 @@ export const FormProvider = ({
   return (
     <FormContext.Provider
       value={{
+        documentId,
         setFieldValue,
         setFieldStore,
         getFieldValue,

package/src/forms/form-renderer.tsx

@@ -387,6 +387,16 @@ const FormContent = ({
             uploadField,
             ({ fieldPath, status }) => {
               setFieldUploading(fieldPath, status === 'uploading')
+            },
+            {
+              // Document context for server-side upload hooks: the persisted
+              // document id (edit mode only) plus any `upload.context` form
+              // values declared on the schema field. See UploadConfig.context
+              // in @byline/core.
+              documentId:
+                mode === 'edit' && typeof initialData?.id === 'string' ? initialData.id : undefined,
+              fields,
+              getFormValues: getFieldValues,
             }
           )
 
@@ -765,6 +775,7 @@ export const FormRenderer = ({
     <FormProvider
       key={`${initialLocale ?? 'default'}-${initialData?.versionId ?? ''}`}
       initialData={initialData}
+      documentId={mode === 'edit' && typeof initialData?.id === 'string' ? initialData.id : null}
     >
       <FormContent
         mode={mode}

package/src/forms/upload-executor.test.node.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 type { Field } from '@byline/core'
+import { describe, expect, it, vi } from 'vitest'
+
+import { executeUploads } from './upload-executor'
+import type { PendingUpload } from './form-context'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/** Schema mirroring the publications files-array shape. */
+const publicationsFields: Field[] = [
+  { name: 'title', label: 'Title', type: 'text' },
+  { name: 'serialNumber', label: 'Serial', type: 'counter', group: 'test-serial' },
+  {
+    name: 'files',
+    label: 'Files',
+    type: 'array',
+    fields: [
+      {
+        name: 'filesGroup',
+        type: 'group',
+        fields: [
+          {
+            name: 'publicationFile',
+            label: 'File',
+            type: 'file',
+            upload: {
+              mimeTypes: ['application/pdf'],
+              context: ['language', '/serialNumber', '../missingSibling'],
+            },
+          },
+          {
+            name: 'language',
+            label: 'Language',
+            type: 'relation',
+            targetCollection: 'languages',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    name: 'cover',
+    label: 'Cover',
+    type: 'image',
+    upload: { mimeTypes: ['image/*'] },
+  },
+]
+
+function pendingUpload(name = 'test.pdf'): PendingUpload {
+  return {
+    file: new File(['%PDF'], name, { type: 'application/pdf' }),
+    previewUrl: 'blob:mock',
+    collectionPath: 'publications',
+  }
+}
+
+/** Capture the FormData each call receives; echo a minimal result. */
+function captureUploadField() {
+  const bodies: FormData[] = []
+  const fn = vi.fn(async (_collection: string, formData: FormData) => {
+    bodies.push(formData)
+    return { storedFile: { fileId: '1', filename: 'stored.pdf' } as any }
+  })
+  return { fn, bodies }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('executeUploads — context transmission', () => {
+  it('always sends field (leaf name) and fieldPath; documentId only when provided', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['files[0].filesGroup.publicationFile', pendingUpload()]])
+
+    await executeUploads(uploads, fn, {
+      documentId: 'doc-123',
+      fields: publicationsFields,
+      getFormValues: () => ({}),
+    })
+
+    const body = bodies[0]!
+    expect(body.get('field')).toBe('publicationFile')
+    expect(body.get('fieldPath')).toBe('files[0].filesGroup.publicationFile')
+    expect(body.get('documentId')).toBe('doc-123')
+  })
+
+  it('omits documentId in create mode (undefined)', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['cover', pendingUpload('c.png')]])
+
+    await executeUploads(uploads, fn, { fields: publicationsFields, getFormValues: () => ({}) })
+
+    expect(bodies[0]?.get('documentId')).toBeNull()
+  })
+
+  it('resolves sibling, root-absolute, and missing context paths against the item scope', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['files[1].filesGroup.publicationFile', pendingUpload()]])
+
+    await executeUploads(uploads, fn, {
+      documentId: 'doc-123',
+      fields: publicationsFields,
+      getFormValues: () => ({
+        serialNumber: 447,
+        files: [
+          { filesGroup: { language: { targetDocumentId: 'lang-th', targetCollectionId: 'c' } } },
+          { filesGroup: { language: { targetDocumentId: 'lang-en', targetCollectionId: 'c' } } },
+        ],
+      }),
+    })
+
+    const body = bodies[0]!
+    // Sibling path reads THIS item's language, not item 0's.
+    expect(body.get('language')).toBe('lang-en')
+    // Root-absolute path.
+    expect(body.get('serialNumber')).toBe('447')
+    // Unresolvable context values are omitted, not sent as ''.
+    expect(body.get('missingSibling')).toBeNull()
+  })
+
+  it('serialises relation envelopes to their targetDocumentId', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['files[0].filesGroup.publicationFile', pendingUpload()]])
+
+    await executeUploads(uploads, fn, {
+      fields: publicationsFields,
+      getFormValues: () => ({
+        serialNumber: 1,
+        files: [
+          { filesGroup: { language: { targetDocumentId: 'lang-de', targetCollectionId: 'c' } } },
+        ],
+      }),
+    })
+
+    expect(bodies[0]?.get('language')).toBe('lang-de')
+  })
+
+  it('fields without upload.context send no extra entries', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['cover', pendingUpload('c.png')]])
+
+    await executeUploads(uploads, fn, {
+      documentId: 'doc-9',
+      fields: publicationsFields,
+      getFormValues: () => ({ serialNumber: 5 }),
+    })
+
+    const body = bodies[0]!
+    expect(body.get('field')).toBe('cover')
+    expect(body.get('serialNumber')).toBeNull()
+  })
+
+  it('works without an execution context (legacy call shape)', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['cover', pendingUpload('c.png')]])
+
+    const result = await executeUploads(uploads, fn)
+
+    expect(result.allSucceeded).toBe(true)
+    const body = bodies[0]!
+    expect(body.get('field')).toBe('cover')
+    expect(body.get('fieldPath')).toBe('cover')
+    expect(body.get('documentId')).toBeNull()
+  })
+})

package/src/forms/upload-executor.ts

@@ -14,8 +14,9 @@
  * but only uploaded when the user clicks Save.
  */
 
-import type { StoredFileValue } from '@byline/core'
+import type { Field, StoredFileValue, UploadConfig } from '@byline/core'
 
+import { get as getNestedValue } from './nested-path'
 import type { UploadFieldFn } from '../fields/field-services-types'
 import type { PendingUpload } from './form-context'
 
@@ -37,6 +38,29 @@ export interface ExecuteUploadsResult {
   allSucceeded: boolean
 }
 
+/**
+ * Optional document context threaded from the form renderer so upload
+ * requests carry the state that server-side `beforeStore` / `afterStore`
+ * hooks need (see `UploadConfig.context` in `@byline/core`).
+ */
+export interface UploadExecutionContext {
+  /**
+   * The persisted document id (edit mode). Posted as `documentId` on every
+   * upload request; omitted while the document is unsaved (create mode).
+   */
+  documentId?: string
+  /**
+   * The collection's schema fields — used to locate each upload field's
+   * `upload.context` declaration by walking the pending upload's field path.
+   */
+  fields?: readonly Field[]
+  /**
+   * Snapshot accessor for the live form values, resolved lazily per upload
+   * so context reflects the state at the moment the request is built.
+   */
+  getFormValues?: () => Record<string, any>
+}
+
 /**
  * Execute all pending uploads sequentially.
  * Returns a result object with successful uploads and any errors.
@@ -44,25 +68,21 @@ export interface ExecuteUploadsResult {
  * @param pendingUploads - Map of field path to PendingUpload
  * @param uploadField - Host-provided upload transport (resolved via
  *                         `useBylineFieldServices()` in the calling React tree)
+ * @param executionContext - Optional document/form context appended to each
+ *                         upload request (documentId, `upload.context` values)
  * @returns Promise resolving to ExecuteUploadsResult
  */
 export async function executeUploads(
   pendingUploads: Map<string, PendingUpload>,
-  uploadField: UploadFieldFn
+  uploadField: UploadFieldFn,
+  executionContext?: UploadExecutionContext
 ): Promise<ExecuteUploadsResult> {
   const results: UploadResult[] = []
   const successful = new Map<string, StoredFileValue>()
   const errors = new Map<string, string>()
 
   for (const [fieldPath, upload] of pendingUploads.entries()) {
-    const formData = new FormData()
-    formData.append('file', upload.file)
-    // Tell the server which upload-capable field this file belongs to.
-    // With per-field upload config a collection can have multiple
-    // image/file fields, each with its own constraints; the server's
-    // unique-default fallback covers the single-field case but rejects
-    // multi-field collections without an explicit selector.
-    formData.append('field', uploadFieldName(fieldPath))
+    const formData = buildUploadFormData(fieldPath, upload, executionContext)
 
     try {
       // Pass createDocument=false — we're uploading for an embedded field,
@@ -94,6 +114,61 @@ export async function executeUploads(
   }
 }
 
+/**
+ * Compose the multipart body for one pending upload.
+ *
+ * Beyond the file itself, the request carries:
+ *   - `field`     — leaf name of the upload-capable field (server-side
+ *                   resolver matches upload fields by leaf name at any
+ *                   nesting depth, so leaf names must be unique among a
+ *                   collection's upload-capable fields).
+ *   - `fieldPath` — the full form path (e.g.
+ *                   `files[2].filesGroup.publicationFile`), so hooks can
+ *                   distinguish array items.
+ *   - `documentId` — the persisted document id (edit mode only).
+ *   - one entry per resolved `upload.context` path (see
+ *     `UploadConfig.context` in `@byline/core` for path semantics and
+ *     serialisation rules).
+ */
+function buildUploadFormData(
+  fieldPath: string,
+  upload: PendingUpload,
+  executionContext?: UploadExecutionContext
+): FormData {
+  const formData = new FormData()
+  formData.append('file', upload.file)
+  // Tell the server which upload-capable field this file belongs to.
+  // With per-field upload config a collection can have multiple
+  // image/file fields, each with its own constraints; the server's
+  // unique-default fallback covers the single-field case but rejects
+  // multi-field collections without an explicit selector.
+  formData.append('field', uploadFieldName(fieldPath))
+  formData.append('fieldPath', fieldPath)
+
+  if (executionContext?.documentId) {
+    formData.append('documentId', executionContext.documentId)
+  }
+
+  const contextPaths =
+    executionContext?.fields != null
+      ? findUploadFieldByPath(executionContext.fields, fieldPath)?.context
+      : undefined
+
+  if (contextPaths && contextPaths.length > 0 && executionContext?.getFormValues) {
+    const formValues = executionContext.getFormValues()
+    for (const contextPath of contextPaths) {
+      const resolvedPath = resolveContextPath(fieldPath, contextPath)
+      if (resolvedPath === undefined) continue
+      const value = resolvedPath === '' ? formValues : getNestedValue(formValues, resolvedPath)
+      const serialized = serializeContextValue(value)
+      if (serialized === undefined) continue
+      formData.append(leafName(contextPath), serialized)
+    }
+  }
+
+  return formData
+}
+
 /**
  * Extract the leaf field name from a `fieldPath`. Top-level upload
  * fields (`'image'`, `'avatar'`) pass through unchanged; nested paths
@@ -107,6 +182,127 @@ function uploadFieldName(fieldPath: string): string {
   return dot === -1 ? fieldPath : fieldPath.slice(dot + 1)
 }
 
+/** Leaf segment of a context path: `'../a.b'` → `'b'`, `'/x'` → `'x'`. */
+function leafName(contextPath: string): string {
+  const segments = contextPath.split('/').pop() ?? contextPath
+  const dot = segments.lastIndexOf('.')
+  return dot === -1 ? segments : segments.slice(dot + 1)
+}
+
+/**
+ * Resolve an `upload.context` path declaration against the upload field's
+ * position in the form, filesystem-style. The upload field is treated as a
+ * "file" living in the directory formed by its containing scope:
+ *
+ *   fieldPath `files[2].filesGroup.publicationFile` → scope
+ *   `['files[2]', 'filesGroup']`
+ *
+ *   - `'language'` / `'./language'` → `files[2].filesGroup.language`
+ *   - `'../label'`                  → `files[2].label`
+ *   - `'/serialNumber'`             → `serialNumber` (document root)
+ *
+ * Returns the dotted form path to read, `''` for the form root itself, or
+ * `undefined` when `../` climbs past the root (declaration bug — the value
+ * is skipped rather than mis-resolved).
+ */
+function resolveContextPath(fieldPath: string, contextPath: string): string | undefined {
+  // Root-absolute: strip the slash, done.
+  if (contextPath.startsWith('/')) {
+    return contextPath.slice(1)
+  }
+
+  // Scope = the upload field's containing segments (dot-split keeps array
+  // indices attached to their segment: `files[2]` stays one hop).
+  const scope = fieldPath.split('.')
+  scope.pop() // drop the upload field's own leaf segment
+
+  const parts = contextPath.split('/')
+  const leaf = parts.pop() ?? ''
+  for (const part of parts) {
+    if (part === '.' || part === '') continue
+    if (part === '..') {
+      if (scope.length === 0) return undefined
+      scope.pop()
+      continue
+    }
+    // A directory-style intermediate segment (`a/b`) descends.
+    scope.push(part)
+  }
+
+  return scope.length === 0 ? leaf : `${scope.join('.')}${leaf ? `.${leaf}` : ''}`
+}
+
+/**
+ * Serialise a resolved form value for the multipart `fields` bag.
+ * See `UploadConfig.context` for the contract.
+ */
+function serializeContextValue(value: unknown): string | undefined {
+  if (value == null) return undefined
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  // Relation envelope → its target document id.
+  if (isRelationEnvelope(value)) return value.targetDocumentId
+  // hasMany relation → comma-joined ids.
+  if (Array.isArray(value) && value.length > 0 && value.every(isRelationEnvelope)) {
+    return value.map((v) => v.targetDocumentId).join(',')
+  }
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return undefined
+  }
+}
+
+function isRelationEnvelope(value: unknown): value is { targetDocumentId: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { targetDocumentId?: unknown }).targetDocumentId === 'string'
+  )
+}
+
+/**
+ * Locate the upload-capable `image | file` schema field addressed by a form
+ * field path, walking `group` / `array` / `blocks` structures. Array indices
+ * in the path (`files[2]`) map onto the schema's repeating field (`files`);
+ * blocks are matched by trying each block's field set (block-type info is
+ * not encoded in the path, so the first block containing the remaining path
+ * wins — upload leaf names must be unique among a collection's
+ * upload-capable fields anyway, per the server-side resolver's contract).
+ */
+function findUploadFieldByPath(
+  fields: readonly Field[],
+  fieldPath: string
+): UploadConfig | undefined {
+  const segments = fieldPath.split('.').map((s) => s.replace(/\[\d+\]$/, ''))
+
+  let currentFields: readonly Field[] = fields
+  for (let i = 0; i < segments.length; i++) {
+    const name = segments[i]
+    const isLeaf = i === segments.length - 1
+    const field = currentFields.find((f) => f.name === name)
+    if (!field) return undefined
+
+    if (isLeaf) {
+      return field.type === 'image' || field.type === 'file' ? field.upload : undefined
+    }
+
+    if (field.type === 'group' || field.type === 'array') {
+      currentFields = field.fields
+      continue
+    }
+    if (field.type === 'blocks') {
+      const remaining = segments[i + 1]
+      const block = field.blocks.find((b) => b.fields.some((f) => f.name === remaining))
+      if (!block) return undefined
+      currentFields = block.fields
+      continue
+    }
+    return undefined
+  }
+  return undefined
+}
+
 /**
  * Progress callback type for upload execution with progress tracking.
  */
@@ -124,7 +320,8 @@ export type UploadProgressCallback = (info: {
 export async function executeUploadsWithProgress(
   pendingUploads: Map<string, PendingUpload>,
   uploadField: UploadFieldFn,
-  onProgress?: UploadProgressCallback
+  onProgress?: UploadProgressCallback,
+  executionContext?: UploadExecutionContext
 ): Promise<ExecuteUploadsResult> {
   const results: UploadResult[] = []
   const successful = new Map<string, StoredFileValue>()
@@ -145,9 +342,7 @@ export async function executeUploadsWithProgress(
       status: 'uploading',
     })
 
-    const formData = new FormData()
-    formData.append('file', upload.file)
-    formData.append('field', uploadFieldName(fieldPath))
+    const formData = buildUploadFormData(fieldPath, upload, executionContext)
 
     try {
       const result = await uploadField(upload.collectionPath, formData, false)