@byline/admin 4.3.0 → 4.4.1

package/src/forms/repeating-items.ts

@@ -0,0 +1,48 @@
+/** Return a canonical identity that is safe in an instance-path selector. */
+export function repeatingItemId(item: unknown): string | undefined {
+  if (item == null || typeof item !== 'object' || !('_id' in item)) return undefined
+  const id = (item as { _id: unknown })._id
+  return typeof id === 'string' && id !== '' && !/[.[\]]/.test(id) ? id : undefined
+}
+
+/**
+ * Address an array/block item by stable identity when its id is path-safe.
+ * Positional fallback is retained for noncanonical create defaults and legacy
+ * adapter data that does not carry storage identity yet.
+ */
+export function repeatingItemPath(parentPath: string, item: unknown, index: number): string {
+  const id = repeatingItemId(item)
+  return id != null ? `${parentPath}[id=${id}]` : `${parentPath}[${index}]`
+}
+
+export interface RepeatingItemMove<T> {
+  items: T[]
+  itemId: string
+  fromIndex: number
+  toIndex: number
+}
+
+/** Build one synchronized form-store move and its matching patch identity. */
+export function moveRepeatingItems<T>(
+  items: readonly T[],
+  moveFromIndex: number,
+  moveToIndex: number
+): RepeatingItemMove<T> | null {
+  if (items.length === 0) return null
+
+  const fromIndex = Math.max(0, Math.min(moveFromIndex, items.length - 1))
+  const toIndex = Math.max(0, Math.min(moveToIndex, items.length - 1))
+  if (fromIndex === toIndex) return null
+
+  const source = items[fromIndex]
+  const moved = [...items]
+  const [item] = moved.splice(fromIndex, 1)
+  moved.splice(toIndex, 0, item as T)
+
+  return {
+    items: moved,
+    itemId: repeatingItemId(source) ?? String(fromIndex),
+    fromIndex,
+    toIndex,
+  }
+}

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

@@ -56,6 +56,91 @@ const publicationsFields: Field[] = [
   },
 ]
 
+/**
+ * Two block types that both declare an array named `gallery`, each holding a
+ * different upload-capable leaf. Leaf names stay unique across the
+ * collection, so this passes the boot-time uniqueness constraint — the shape
+ * is legal, and it is the shape that made block resolution ambiguous.
+ */
+const blocksFields: Field[] = [
+  { name: 'title', label: 'Title', type: 'text' },
+  {
+    name: 'content',
+    label: 'Content',
+    type: 'blocks',
+    blocks: [
+      {
+        blockType: 'photoBlock',
+        fields: [
+          {
+            name: 'gallery',
+            label: 'Gallery',
+            type: 'array',
+            fields: [
+              {
+                name: 'heroImage',
+                label: 'Hero',
+                type: 'image',
+                upload: { context: ['/title'] },
+              },
+            ],
+          },
+        ],
+      },
+      {
+        blockType: 'videoBlock',
+        fields: [
+          {
+            name: 'gallery',
+            label: 'Gallery',
+            type: 'array',
+            fields: [
+              {
+                name: 'poster',
+                label: 'Poster',
+                type: 'image',
+                upload: { context: ['../caption', '/title'] },
+              },
+            ],
+          },
+          { name: 'caption', label: 'Caption', type: 'text' },
+          {
+            // Declared directly on the block, unlike `poster` above. This is
+            // the only depth at which `..` must leave the block entirely, so
+            // it is the only depth that can detect a scope miscount.
+            name: 'blockFile',
+            label: 'Block file',
+            type: 'file',
+            upload: { context: ['caption', '../title'] },
+          },
+        ],
+      },
+    ],
+  },
+]
+
+/** Form state for `blocksFields`: a photoBlock then a videoBlock. */
+const blocksFormValues = () => ({
+  title: 'Hello',
+  content: [
+    { _type: 'photoBlock', _id: 'blk-photo', gallery: [{ _id: 'gallery-photo' }] },
+    {
+      _type: 'videoBlock',
+      _id: 'blk-video',
+      gallery: [{ _id: 'gallery-video' }],
+      caption: 'Video caption',
+    },
+  ],
+})
+
+function imageUpload(name = 'p.png'): PendingUpload {
+  return {
+    file: new File(['x'], name, { type: 'image/png' }),
+    previewUrl: 'blob:mock',
+    collectionPath: 'pages',
+  }
+}
+
 function pendingUpload(name = 'test.pdf'): PendingUpload {
   return {
     file: new File(['%PDF'], name, { type: 'application/pdf' }),
@@ -174,3 +259,166 @@ describe('executeUploads — context transmission', () => {
     expect(body.get('documentId')).toBeNull()
   })
 })
+
+// ---------------------------------------------------------------------------
+// Block resolution
+//
+// A form field path is an INSTANCE path — `content[1].gallery[0].poster` — and
+// carries no block type, because a block item holds its own `_type`. Resolving
+// an upload field inside a block therefore means reading that item.
+// ---------------------------------------------------------------------------
+
+describe('executeUploads — upload fields inside blocks', () => {
+  it('resolves upload.context for a field in the first block', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['content[0].gallery[0].heroImage', imageUpload('h.png')]])
+
+    await executeUploads(uploads, fn, {
+      fields: blocksFields,
+      getFormValues: blocksFormValues,
+    })
+
+    expect(bodies[0]?.get('title')).toBe('Hello')
+  })
+
+  it('resolves upload.context for a field in a later block', async () => {
+    // Regression: block resolution used to match the first block declaring a
+    // field named by the next path segment. Both blocks declare `gallery`, so
+    // `photoBlock` won, `poster` was not found in it, and the declared context
+    // was dropped silently — no error, just a missing value the server-side
+    // beforeStore / afterStore hooks were relying on.
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['content[1].gallery[0].poster', imageUpload()]])
+
+    await executeUploads(uploads, fn, {
+      fields: blocksFields,
+      getFormValues: blocksFormValues,
+    })
+
+    expect(bodies[0]?.get('title')).toBe('Hello')
+  })
+
+  it('addresses a block item by stable id as well as position', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['content[id=blk-video].gallery[0].poster', imageUpload()]])
+
+    await executeUploads(uploads, fn, {
+      fields: blocksFields,
+      getFormValues: blocksFormValues,
+    })
+
+    expect(bodies[0]?.get('title')).toBe('Hello')
+  })
+
+  it('resolves sibling context through stable outer and inner item paths', async () => {
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([
+      ['content[id=blk-video].gallery[id=gallery-video].poster', imageUpload()],
+    ])
+
+    await executeUploads(uploads, fn, {
+      fields: blocksFields,
+      getFormValues: blocksFormValues,
+    })
+
+    expect(bodies[0]?.get('caption')).toBe('Video caption')
+    expect(bodies[0]?.get('title')).toBe('Hello')
+  })
+
+  it('climbs out of the block to the document root for an upload declared on the block', async () => {
+    // The scope boundary, and the one case that can catch a miscount.
+    //
+    // `poster` sits inside `gallery[]`, so its `../caption` climbs from the
+    // array item to the *block item* — a hop that stays inside the block.
+    // `blockFile` sits on the block itself, so `../title` has to leave the
+    // block and land at the document root.
+    //
+    // Those two behave differently under a path that carries a segment which
+    // addresses nothing. An abandoned experiment qualified instance paths with
+    // the block type (`content[1].videoBlock.blockFile`), and because
+    // `resolveContextPath` counts every dotted segment as one scope,`..`
+    // stopped one level short: `../title` resolved to `content[1].title`
+    // inside the block rather than the root, and arrived empty. The
+    // inside-the-block case absorbed the extra segment and kept passing —
+    // which is exactly why it cannot stand in for this one.
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['content[1].blockFile', pendingUpload()]])
+
+    await executeUploads(uploads, fn, {
+      fields: blocksFields,
+      getFormValues: blocksFormValues,
+    })
+
+    // Root-level `title`, not the block's own `caption` scope.
+    expect(bodies[0]?.get('title')).toBe('Hello')
+    // The sibling still resolves, so a failure above is the climb specifically
+    // and not block resolution having gone wrong generally.
+    expect(bodies[0]?.get('caption')).toBe('Video caption')
+  })
+
+  it('still resolves when the addressed block item is missing from form state', async () => {
+    // Form state can lag a pending upload. The item is what supplies `_type`,
+    // so its absence drops us to the unique-match fallback — but the *field*
+    // is a declaration, and `poster` is declared in exactly one block, so the
+    // answer is unchanged. Staleness costs nothing here; genuine ambiguity
+    // would still return nothing (see the ambiguous case below).
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['content[7].gallery[0].poster', imageUpload()]])
+
+    await executeUploads(uploads, fn, {
+      fields: blocksFields,
+      getFormValues: blocksFormValues,
+    })
+
+    expect(bodies[0]?.get('title')).toBe('Hello')
+    expect(bodies[0]?.get('fieldPath')).toBe('content[7].gallery[0].poster')
+  })
+
+  it('falls back to a unique match when form values cannot disambiguate', async () => {
+    // Without data the block type is unknowable from the path. `poster` is
+    // declared in exactly one block, so the answer is still unambiguous.
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['content[1].gallery[0].poster', imageUpload()]])
+
+    await executeUploads(uploads, fn, {
+      fields: blocksFields,
+      getFormValues: () => ({ title: 'Hello' }),
+    })
+
+    expect(bodies[0]?.get('title')).toBe('Hello')
+  })
+
+  it('sends no context when the path genuinely identifies no single declaration', async () => {
+    // Same leaf name in both blocks and no data to choose between them. A
+    // guess would be wrong half the time, so nothing is sent.
+    const ambiguous: Field[] = [
+      { name: 'title', label: 'Title', type: 'text' },
+      {
+        name: 'content',
+        label: 'Content',
+        type: 'blocks',
+        blocks: [
+          {
+            blockType: 'aBlock',
+            fields: [
+              { name: 'shared', label: 'S', type: 'image', upload: { context: ['/title'] } },
+            ],
+          },
+          {
+            blockType: 'bBlock',
+            fields: [
+              { name: 'shared', label: 'S', type: 'image', upload: { context: ['/title'] } },
+            ],
+          },
+        ],
+      },
+    ]
+
+    const { fn, bodies } = captureUploadField()
+    const uploads = new Map([['content[1].shared', imageUpload()]])
+
+    await executeUploads(uploads, fn, { fields: ambiguous, getFormValues: () => ({ title: 'x' }) })
+
+    expect(bodies[0]?.get('title')).toBeNull()
+  })
+})

package/src/forms/upload-executor.ts

@@ -15,6 +15,7 @@
  */
 
 import type { Field, StoredFileValue, UploadConfig } from '@byline/core'
+import { type PathSegment, parseInstancePath } from '@byline/core'
 
 import { get as getNestedValue } from './nested-path'
 import type { UploadFieldFn } from '../fields/field-services-types'
@@ -149,13 +150,16 @@ function buildUploadFormData(
     formData.append('documentId', executionContext.documentId)
   }
 
+  // Resolved once per upload, before locating the field: a `blocks` hop in
+  // the path can only be resolved by reading the addressed item's `_type`.
+  const formValues = executionContext?.getFormValues?.()
+
   const contextPaths =
     executionContext?.fields != null
-      ? findUploadFieldByPath(executionContext.fields, fieldPath)?.context
+      ? findUploadFieldByPath(executionContext.fields, fieldPath, formValues)?.context
       : undefined
 
-  if (contextPaths && contextPaths.length > 0 && executionContext?.getFormValues) {
-    const formValues = executionContext.getFormValues()
+  if (contextPaths && contextPaths.length > 0 && formValues) {
     for (const contextPath of contextPaths) {
       const resolvedPath = resolveContextPath(fieldPath, contextPath)
       if (resolvedPath === undefined) continue
@@ -212,7 +216,10 @@ function resolveContextPath(fieldPath: string, contextPath: string): string | un
   }
 
   // Scope = the upload field's containing segments (dot-split keeps array
-  // indices attached to their segment: `files[2]` stays one hop).
+  // selectors attached to their segment: `files[id=x]` stays one hop).
+  // This relies on every dotted form-path segment being a real data scope. If
+  // the grammar ever adds descriptive/non-navigating segments, classify and
+  // remove them before counting `..` hops rather than changing parent scope.
   const scope = fieldPath.split('.')
   scope.pop() // drop the upload field's own leaf segment
 
@@ -263,43 +270,100 @@ function isRelationEnvelope(value: unknown): value is { 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).
+ * field path, walking `group` / `array` / `blocks` structures.
+ *
+ * The path is an *instance* path (`content[1].gallery[0].poster`), so it
+ * carries no block type — a block item's type lives on the item itself, as
+ * `_type`. Passing `formValues` therefore lets a `blocks` hop be resolved
+ * exactly: read the addressed item, take its `_type`, descend into that
+ * block. Without form values the block type is genuinely unknowable from the
+ * path, so every block is tried and the result is accepted only when exactly
+ * one resolves — ambiguity returns `undefined` rather than a guess.
  */
 function findUploadFieldByPath(
   fields: readonly Field[],
-  fieldPath: string
+  fieldPath: string,
+  formValues?: Record<string, any>
 ): UploadConfig | undefined {
-  const segments = fieldPath.split('.').map((s) => s.replace(/\[\d+\]$/, ''))
+  const parsed = parseInstancePath(fieldPath)
+  if (!parsed.ok) return undefined
+  return resolveUploadConfig(fields, parsed.segments, formValues)
+}
 
-  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
+/** Select the item an index / id segment addresses, when data is available. */
+function selectItem(value: unknown, segment: PathSegment): unknown {
+  if (!Array.isArray(value)) return undefined
+  if (segment.kind === 'index') return value[segment.index]
+  if (segment.kind === 'id') {
+    return value.find((item) => (item as { _id?: unknown } | null)?._id === segment.id)
+  }
+  return undefined
+}
+
+/**
+ * Walk instance-path segments against the schema, carrying the corresponding
+ * slice of form data alongside so `blocks` hops can read `_type`.
+ */
+function resolveUploadConfig(
+  fields: readonly Field[],
+  segments: readonly PathSegment[],
+  value: unknown
+): UploadConfig | undefined {
+  const head = segments[0]
+  if (head == null || head.kind !== 'field') return undefined
 
-    if (isLeaf) {
-      return field.type === 'image' || field.type === 'file' ? field.upload : undefined
+  const field = fields.find((candidate) => candidate.name === head.name)
+  if (field == null) return undefined
+
+  const fieldValue = (value as Record<string, unknown> | undefined)?.[head.name]
+  const rest = segments.slice(1)
+
+  if (rest.length === 0) {
+    return field.type === 'image' || field.type === 'file' ? field.upload : undefined
+  }
+
+  if (field.type === 'group') {
+    return resolveUploadConfig(field.fields, rest, fieldValue)
+  }
+
+  if (field.type === 'array') {
+    // An item selector may be absent when the caller addresses the array's
+    // child declaration rather than one item; the child fields are the same.
+    const selector = rest[0]
+    if (selector?.kind === 'index' || selector?.kind === 'id') {
+      return resolveUploadConfig(field.fields, rest.slice(1), selectItem(fieldValue, selector))
     }
+    return resolveUploadConfig(field.fields, rest, undefined)
+  }
 
-    if (field.type === 'group' || field.type === 'array') {
-      currentFields = field.fields
-      continue
+  if (field.type === 'blocks') {
+    const selector = rest[0]
+    const remainder = selector?.kind === 'index' || selector?.kind === 'id' ? rest.slice(1) : rest
+    const item =
+      selector?.kind === 'index' || selector?.kind === 'id'
+        ? selectItem(fieldValue, selector)
+        : undefined
+
+    const blockType = (item as { _type?: unknown } | undefined)?._type
+    if (typeof blockType === 'string') {
+      const block = field.blocks.find((candidate) => candidate.blockType === blockType)
+      return block == null ? undefined : resolveUploadConfig(block.fields, remainder, item)
     }
-    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
+
+    // No data to disambiguate. Try every block and accept a unique answer;
+    // two matches mean the path genuinely does not identify one declaration.
+    let found: UploadConfig | undefined
+    let matches = 0
+    for (const block of field.blocks) {
+      const result = resolveUploadConfig(block.fields, remainder, undefined)
+      if (result !== undefined) {
+        matches += 1
+        found = result
+      }
     }
-    return undefined
+    return matches === 1 ? found : undefined
   }
+
   return undefined
 }