@uniweb/kit 0.10.16 → 0.10.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.10.16",
+  "version": "0.10.18",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -43,8 +43,8 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/core": "0.8.2",
     "@uniweb/scene": "0.1.2",
+    "@uniweb/core": "0.8.2",
     "@uniweb/semantic-parser": "1.2.1"
   },
   "peerDependencies": {

package/src/hooks/useFormSubmit.js

@@ -104,6 +104,20 @@ export function useFormSubmit(defaults = {}) {
     response,
     canSubmit: !!target,
     unavailableReason,
+    // Whether attachments can be delivered. True once there is a target: the
+    // client sends the manifest, then the bytes, then finalizes.
+    //
+    // It tracks `canSubmit` because it is a statement about THIS client, not
+    // about the endpoint — whether a given endpoint accepts uploads is
+    // discovered on submit, and a failure there throws with a message saying
+    // the submission landed and the attachment did not. What this rules out is
+    // the case that has no honest report: offering a file input when nothing
+    // could ever send the bytes.
+    //
+    // Kept as its own field rather than folded into `canSubmit` because a
+    // component decides *whether to render a file input* separately from
+    // whether to render the form, and that decision belongs at render time.
+    canUploadFiles: !!target,
     submit,
     reset,
   }

package/src/utils/submitForm.js

@@ -35,8 +35,17 @@
  *                                                   pageId, pageLabel
  * @param {string} [args.verificationToken]        — bot-protection token, when the
  *                                                   endpoint verifies one
+ * @param {Array<File|{file:File,field?:string}>} [args.files]
+ *                                                 — attachments to upload. The
+ *                                                   manifest is derived from
+ *                                                   these; phase two sends the
+ *                                                   bytes. The `{file, field}`
+ *                                                   form records which field an
+ *                                                   attachment came from.
  * @param {Array<{name:string,size:number,mime?:string}>} [args.fileSlots]
- *                                                 — declared file uploads
+ *                                                 — a manifest with no bytes.
+ *                                                   Accepted, but ONLY sends the
+ *                                                   declaration; prefer `files`
  * @param {typeof fetch} [args.fetchFn=fetch]      — fetch override (testing / SSR)
  *
  * @returns {Promise<{ submissionId: string, uploadUrls?: Array }>}
@@ -48,6 +57,7 @@ export async function submitForm({
   summary,
   context = {},
   verificationToken,
+  files,
   fileSlots,
   fetchFn = typeof fetch === 'function' ? fetch : null,
 } = {}) {
@@ -64,12 +74,33 @@ export async function submitForm({
     throw new Error('submitForm: fetch is unavailable in this environment')
   }
 
+  const entries = normalizeFiles(files)
+
+  // A manifest without the files it describes cannot be delivered — the bytes
+  // are what phase two sends. Passing `fileSlots` alone declares attachments
+  // nobody receives, which is a success that is not one, so say so.
+  if (entries.length === 0 && Array.isArray(fileSlots) && fileSlots.length > 0) {
+    console.warn(
+      `[uniweb] submitForm: ${fileSlots.length} file(s) declared via \`fileSlots\` with no ` +
+      '`files` — the manifest is sent and the bytes are NOT. Pass `files` so they upload.',
+    )
+  }
+
+  const slots = entries.length
+    ? entries.map(({ file, field }) => ({
+        name: file.name,
+        size: file.size,
+        mime: file.type || 'application/octet-stream',
+        ...(field ? { field } : {}),
+      }))
+    : fileSlots
+
   // ── API name → wire name. See the header before "correcting" these. ──
   const body = {
     formData,
     metadata: { ...context, preview: summary || deriveSummary(formData) },
     ...(verificationToken ? { turnstileToken: verificationToken } : {}),
-    ...(Array.isArray(fileSlots) && fileSlots.length ? { fileSlots } : {}),
+    ...(Array.isArray(slots) && slots.length ? { fileSlots: slots } : {}),
   }
 
   const res = await fetchFn(target, {
@@ -84,7 +115,143 @@ export async function submitForm({
     throw new Error(serverMessage || `Submission failed (HTTP ${res.status})`)
   }
 
-  return res.json()
+  const result = await res.json()
+
+  // A submission with no attachments is COMPLETE at this point — the create
+  // call wrote the whole record. Finalizing anyway would re-assert the state it
+  // already has: accepted, and pointless.
+  if (entries.length === 0) return result
+
+  const report = await uploadFiles(entries, result, target, fetchFn)
+  return { ...result, filesUploaded: entries.length, ...report }
+}
+
+/**
+ * Accept either bare `File`s or `{ file, field }` pairs, and drop anything that
+ * is not a file. The pair form exists so a submission can say WHICH field an
+ * attachment came from — a form may have more than one file input.
+ */
+function normalizeFiles(files) {
+  if (!Array.isArray(files)) return []
+  return files
+    .map((f) => (f && typeof f === 'object' && 'file' in f ? f : { file: f }))
+    .filter(({ file }) => file && typeof file === 'object' && 'name' in file)
+}
+
+/**
+ * Phase two — send the bytes.
+ *
+ * Phase one posts a *manifest* and gets back a submission id; the bytes go
+ * separately so they never ride inside the JSON. Two shapes are honoured:
+ *
+ *  - **`uploadUrls` in the response** — one per slot, in slot order. Used when
+ *    present, because an endpoint returning them is telling you where to write.
+ *  - **Otherwise `{target}/upload`** — raw body, `X-Submission-Id` and `X-Slot`
+ *    headers, then `{target}/finalize`. This is the shape the endpoint
+ *    documents, and it is the default rather than a fallback.
+ *
+ * `X-Slot` is the **0-based index into the manifest sent in phase one** — which
+ * is why the entries and the slots are built from one list in one order, and
+ * why nothing here reorders them. An endpoint bounds it to the declared count
+ * and rejects anything outside the range.
+ *
+ * The filename is NOT sent as a header. It travels in the manifest, which is
+ * the contract; an endpoint takes the name from there.
+ *
+ * **Failures throw, and the message says what did land.** The submission row
+ * already exists at this point, so a silent failure here is the same
+ * discarded-attachment bug in a new place — a caller must be able to tell the
+ * visitor that their message arrived and their file did not.
+ */
+async function uploadFiles(entries, result, target, fetchFn) {
+  const submissionId = result?.submissionId
+  if (!submissionId) {
+    throw new Error(
+      'submitForm: the submission was recorded but returned no submissionId, so its ' +
+      `${entries.length} attachment(s) could not be uploaded.`,
+    )
+  }
+
+  const base = String(target).replace(/\/+$/, '')
+  const urls = Array.isArray(result?.uploadUrls) ? result.uploadUrls : []
+
+  for (const [slot, { file }] of entries.entries()) {
+    const url = urls[slot] || `${base}/upload`
+    let res
+    try {
+      res = await fetchFn(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': file.type || 'application/octet-stream',
+          'X-Submission-Id': submissionId,
+          'X-Slot': String(slot),
+        },
+        body: file,
+      })
+    } catch (err) {
+      throw new Error(
+        `submitForm: submission ${submissionId} was recorded, but uploading ` +
+        `"${file.name}" failed — ${err.message}`,
+      )
+    }
+    if (!res.ok) {
+      throw new Error(
+        `submitForm: submission ${submissionId} was recorded, but uploading ` +
+        `"${file.name}" failed (HTTP ${res.status}).`,
+      )
+    }
+  }
+
+  // The manifest rides the finalize body as well as the create body. An
+  // endpoint may or may not trust it — the one we are built against verifies
+  // each slot against storage instead, precisely because a client-supplied
+  // count is what a quota or an invoice would otherwise derive from. Sending it
+  // costs a few bytes and satisfies the stricter reading of the contract, in
+  // which `files` is required and its absence is a malformed call.
+  const manifest = entries.map(({ file }, slot) => ({
+    slot,
+    name: file.name,
+    size: file.size,
+    mime: file.type || 'application/octet-stream',
+  }))
+
+  const done = await fetchFn(`${base}/finalize`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ submissionId, files: manifest }),
+  })
+  if (!done.ok) {
+    throw new Error(
+      `submitForm: submission ${submissionId} and its ${entries.length} attachment(s) ` +
+      `were uploaded, but finalizing failed (HTTP ${done.status}).`,
+    )
+  }
+
+  // Finalize reports what the endpoint actually found in storage, which is not
+  // necessarily what we believe we sent. Checking it is the whole point of
+  // reading this body: every upload can return 2xx and one can still be absent,
+  // and the alternative to catching it here is a support ticket about an
+  // attachment nobody received.
+  //
+  // Only acted on when the endpoint reports a number — an endpoint that returns
+  // nothing (or something else) is not thereby claiming a loss.
+  let report
+  try {
+    report = await done.json()
+  } catch {
+    return undefined // not JSON — nothing to verify against
+  }
+
+  const recorded = report?.filesRecorded
+  if (typeof recorded === 'number' && recorded < entries.length) {
+    throw new Error(
+      `submitForm: submission ${submissionId} was recorded, but only ${recorded} of ` +
+      `${entries.length} attachment(s) reached storage. The endpoint verifies each upload, ` +
+      'so the difference did not arrive.',
+    )
+  }
+
+  return report && typeof report === 'object' ? report : undefined
 }
 
 /**