@marktiderman/genesis-forms-web 0.5.0 → 0.6.0

package/README.md

@@ -159,6 +159,28 @@ sends (it says "Wait for the photo to finish uploading."). Without `onUpload`, o
 `UploadContext` around the form, a photo field says photos can't be added here. `photoFileProblem`,
 `photoFileType` and `photoAccept` are the renderer's own checks, for a custom one.
 
+`signedUploadHost` is an upload host for genesis-forms/server's `createUploadHandler`: for each file
+it asks your endpoint for a signed upload, sends the bytes with `send`, and resolves to the
+server's reference. A refusal rejects with the server's words. `url(ref)` reads a stored file
+through your `readUrl`, null when it can't (for thumbnails in a staff view):
+
+```tsx
+const host = signedUploadHost({
+  endpoint: `/api/upload/${slug}`,
+  claim: () => (editToken ? { edit: editToken } : { attemptId }), // read at each upload
+  // Supabase Storage; without `send`, the file is PUT to `upload.url`.
+  send: async (file, upload, contentType) => {
+    const { error } = await supabase.storage
+      .from(upload.bucket!)
+      .uploadToSignedUrl(upload.path, upload.token, file, { contentType });
+    if (error) throw error;
+  },
+  readUrl: async (ref) => signedReadUrl(ref), // your storage, or null
+});
+
+<Form form={feedback} onUpload={host.upload} onSubmit={send} />;
+```
+
 A **`calculated`** field shows the value the engine worked out from other answers, read-only, in an
 `<output>` named by the question that announces changes politely. It follows the field's `format`
 and `decimals`, and shows a dash until there is a value.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ComponentType } from 'react';
-import { FormDefinition, FormEngine, CreateFormOptions, HostOptions, LinkParams, FormState, FormProgress, FieldBlock, PhotoRef } from '@marktiderman/genesis-forms';
+import { FormDefinition, FormEngine, CreateFormOptions, HostOptions, LinkParams, FormState, FormProgress, FieldBlock, PhotoRef, SignedUpload } from '@marktiderman/genesis-forms';
 import * as _marktiderman_genesis_forms_react from '@marktiderman/genesis-forms-react';
 import { RendererRegistry, FieldRendererProps, RendererEntry } from '@marktiderman/genesis-forms-react';
 
@@ -298,6 +298,8 @@ declare const defaultRegistry: _marktiderman_genesis_forms_react.RendererRegistr
  */
 interface UploadHost {
     upload(file: File, field: FieldBlock): Promise<PhotoRef>;
+    /** A link to read a stored file (the host's storage signs it), or null when it can't be read. */
+    url?(ref: PhotoRef, field?: FieldBlock): Promise<string | null>;
 }
 /** Provide it around `<Form>` (or pass `onUpload`) so `photo` fields can store files. */
 declare const UploadContext: react.Context<UploadHost | null>;
@@ -320,6 +322,48 @@ declare function photoFileProblem(field: FieldBlock, file: {
 /** The `accept` attribute for a field: its MIME types, plus HEIC's file names for browsers that give it no type. */
 declare function photoAccept(field: FieldBlock): string;
 
+/**
+ * Who is uploading: a new response's visit (`attemptId`, a UUID the page keeps for the
+ * visit), or an edit link's token while changing a sent response.
+ */
+type UploadClaim = {
+    attemptId: string;
+} | {
+    edit: string;
+};
+interface SignedUploadHostOptions {
+    /** The app's upload endpoint (`createUploadHandler`'s route), or one per field. */
+    endpoint: string | ((field: FieldBlock) => string);
+    /** Who is uploading, read at each upload. */
+    claim: UploadClaim | (() => UploadClaim);
+    /**
+     * Sends the bytes where the server signed. Default: PUT the file to `upload.url`
+     * (with its type), which a store that signs plain URLs sets. Supabase Storage:
+     * `supabase.storage.from(upload.bucket).uploadToSignedUrl(upload.path, upload.token, file, { contentType })`.
+     * A throw (or rejection) is the upload failing.
+     */
+    send?: ((file: File, upload: SignedUpload, contentType: string) => Promise<void>) | undefined;
+    /**
+     * A link to read a stored file, for thumbnails and staff views: the app's storage signs
+     * it. Null when the reader can't open it. Without it, `url` resolves null.
+     */
+    readUrl?: ((ref: PhotoRef, field?: FieldBlock) => Promise<string | null>) | undefined;
+    /** Default the global `fetch`. */
+    fetch?: typeof fetch | undefined;
+}
+/** An `UploadHost` that always has `url`. */
+interface SignedUploadHost extends UploadHost {
+    url(ref: PhotoRef, field?: FieldBlock): Promise<string | null>;
+}
+/**
+ * The browser half of the upload handshake (genesis-forms/server's `createUploadHandler`):
+ * for each file it asks `endpoint` for a signed upload (`UploadRequest` as JSON), sends
+ * the bytes with `send`, and resolves to the reference the server handed back, which is
+ * all the answer keeps. A refusal rejects with the server's words. Pass it as `<Form
+ * onUpload={host.upload}>` or in an `UploadContext`.
+ */
+declare function signedUploadHost(options: SignedUploadHostOptions): SignedUploadHost;
+
 /**
  * The video or audio a form is about, as the host app plays it. `media-notes`
  * fields read it: with `currentTime` the add row starts at the current moment
@@ -370,4 +414,4 @@ declare function hideQueryOnLoad(win: HiddenQueryWindow, isReload: boolean, now?
 /** Whether this page load was a reload (Navigation Timing), in the browser; false elsewhere. */
 declare const wasReload: () => boolean;
 
-export { type BrandSlotProps, CLASSIC_PROGRESS_DELAY_MS, DefaultEnding, type EndingSlotProps, type ErrorSummaryItem, type ErrorSummarySlotProps, FieldChrome, type FieldChromeProps, Form, type FormBrand, type FormPresentation, type FormPresentationValue, type FormProps, type FormSlotMap, type FormTheme, HIDDEN_QUERY_KEEP_MS, type HeaderSlotProps, type HiddenQueryWindow, type MediaTime, MediaTimeContext, type NavigationSlotProps, PROGRESS_DELAY_MS, type ProgressSlotProps, SourceTextContext, type ThemeColors, UPLOAD_WAIT_MESSAGE, UploadContext, type UploadHost, builtInRenderers, defaultRegistry, describedBy, hideQueryOnLoad, photoAccept, photoFileProblem, photoFileType, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText, useUpload, wasReload };
+export { type BrandSlotProps, CLASSIC_PROGRESS_DELAY_MS, DefaultEnding, type EndingSlotProps, type ErrorSummaryItem, type ErrorSummarySlotProps, FieldChrome, type FieldChromeProps, Form, type FormBrand, type FormPresentation, type FormPresentationValue, type FormProps, type FormSlotMap, type FormTheme, HIDDEN_QUERY_KEEP_MS, type HeaderSlotProps, type HiddenQueryWindow, type MediaTime, MediaTimeContext, type NavigationSlotProps, PROGRESS_DELAY_MS, type ProgressSlotProps, type SignedUploadHost, type SignedUploadHostOptions, SourceTextContext, type ThemeColors, UPLOAD_WAIT_MESSAGE, type UploadClaim, UploadContext, type UploadHost, builtInRenderers, defaultRegistry, describedBy, hideQueryOnLoad, photoAccept, photoFileProblem, photoFileType, signedUploadHost, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText, useUpload, wasReload };

package/dist/index.js

@@ -2658,6 +2658,44 @@ function FormBody({
 }
 var classicSection = "rounded-xl border bg-card px-5 py-6 text-card-foreground sm:px-8 has-[[aria-invalid=true]]:border-destructive";
 
+// src/signed-upload.ts
+async function putToUrl(file, upload, contentType, fetcher) {
+  if (!upload.url) throw new Error("The server signed no URL to send the file to; pass `send`.");
+  const res = await fetcher(upload.url, { method: "PUT", headers: { "content-type": contentType }, body: file });
+  if (!res.ok) throw new Error(`The file wasn't stored (${res.status}).`);
+}
+function signedUploadHost(options) {
+  const fetcher = (...args) => (options.fetch ?? fetch)(...args);
+  return {
+    async upload(file, field) {
+      const type = photoFileType(file);
+      const claim = typeof options.claim === "function" ? options.claim() : options.claim;
+      const endpoint = typeof options.endpoint === "function" ? options.endpoint(field) : options.endpoint;
+      const request = { fieldId: field.id, name: file.name, type, size: file.size, ...claim };
+      const response = await fetcher(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(request)
+      });
+      const body = await response.json().catch(() => ({}));
+      if (!response.ok || !body.ref || !body.upload) {
+        throw new Error(typeof body.error === "string" ? body.error : `The photo wasn't accepted (${response.status}).`);
+      }
+      if (options.send) await options.send(file, body.upload, type);
+      else await putToUrl(file, body.upload, type, fetcher);
+      return body.ref;
+    },
+    async url(ref, field) {
+      if (!options.readUrl) return null;
+      try {
+        return await options.readUrl(ref, field);
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+
 // src/clean-url.ts
 var KEY_PREFIX = "form-query:";
 var HIDDEN_QUERY_KEEP_MS = 30 * 60 * 1e3;
@@ -2689,6 +2727,6 @@ function nativeReplaceState(history) {
 }
 var wasReload = () => typeof performance !== "undefined" && performance.getEntriesByType?.("navigation")[0]?.type === "reload";
 
-export { CLASSIC_PROGRESS_DELAY_MS, DefaultEnding, FieldChrome, Form, HIDDEN_QUERY_KEEP_MS, MediaTimeContext, PROGRESS_DELAY_MS, SourceTextContext, UPLOAD_WAIT_MESSAGE, UploadContext, builtInRenderers, defaultRegistry, describedBy, hideQueryOnLoad, photoAccept, photoFileProblem, photoFileType, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText, useUpload, wasReload };
+export { CLASSIC_PROGRESS_DELAY_MS, DefaultEnding, FieldChrome, Form, HIDDEN_QUERY_KEEP_MS, MediaTimeContext, PROGRESS_DELAY_MS, SourceTextContext, UPLOAD_WAIT_MESSAGE, UploadContext, builtInRenderers, defaultRegistry, describedBy, hideQueryOnLoad, photoAccept, photoFileProblem, photoFileType, signedUploadHost, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText, useUpload, wasReload };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map