@marktiderman/genesis-forms-web 0.4.0 → 0.6.0

package/README.md

@@ -82,6 +82,21 @@ import { Form } from "@marktiderman/genesis-forms-web";
   `dropdown` (a native select), `number` (min, max, step; the decimal keypad on phones), `date` (the
   browser's date picker) and `consent` (one checkbox). A rating can show end labels (`lowLabel`,
   `highLabel`) and `display: "stars"`; NPS takes the same labels.
+- **Option lists:** an option's `description` is a muted line under its label and its `image` a
+  small picture beside it. A choice question with more than 10 options it shows (or with
+  `searchable: true`) gets a search box over an in-page list instead of radios, checkboxes or a
+  select: typing narrows it (`searchOptions`), arrow keys move, Enter or a tap picks, and it
+  works the same in classic and focus layouts and on a phone. A list filtered by another answer
+  (`optionsFrom.filter`) shows only the matching options and drops a pick that stops matching.
+  `linkParams` (such as `new URLSearchParams(location.search)`) preselects questions with
+  `prefill: { param }`; with `hideWhenPrefilled` a question the link answered isn't shown or
+  counted. Which options show, when to search and what a link picks are all decided in
+  genesis-forms (`visibleOptions`, `isSearchable`, `prefillFromLink`, `respondentPath`), so
+  every renderer agrees with the engine and the server:
+
+  ```tsx
+  <Form form={def} hostOptions={lists} linkParams={new URLSearchParams(location.search)} />
+  ```
 - **Submitting:** the ending shows once `onSubmit` resolves. If it rejects, the completed response
   stays on screen read-only (a completed response is final), Back is hidden, and "Try again"
   (`retryLabel`) resends the same answers.
@@ -91,7 +106,9 @@ import { Form } from "@marktiderman/genesis-forms-web";
   over.
 - **Extension ladder:** `slots` replaces a part (`header`, `brand`, `progress`, `navigation`,
   `ending`, `errorSummary`), `null` removes it, and `slotProps` feeds it (and wins over the defaults). A custom
-  ending can mark an element `data-gf-focus` to receive focus; a custom error summary can mark itself
+  ending can mark an element `data-gf-focus` to receive focus; `slotProps={{ ending: { actions } }}`
+  puts buttons or links (Send another response, Change your answers) in a centred row under the
+  default ending, and `DefaultEnding` is exported for a custom ending to wrap; a custom error summary can mark itself
   `data-gf-error-summary` (with `tabIndex={-1}`) to be focused after a failed submit.
 - **Renderers** come from a registry. `defaultRegistry` is shared by every `<Form>` without a
   `registry` prop, so prefer `extend()`, which returns a new registry and changes nothing else:
@@ -142,10 +159,49 @@ 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.
 
+## Clean form links
+
+A link's query (`?edit=`, prefilled answers, `utm_…`) can be taken out of the address bar once the
+page has read it, so it stays out of screenshots and shared addresses. Cosmetic, not security: the
+server still checks every value. Call it once, after reading the query:
+
+```ts
+import { hideQueryOnLoad, wasReload } from "@marktiderman/genesis-forms-web";
+
+useEffect(() => void hideQueryOnLoad(window, wasReload()), []);
+```
+
+It uses the browser's own `History.prototype.replaceState` (a router that patches the instance's
+would otherwise re-read the address), and keeps the query in sessionStorage (`form-query:<path>`) so
+a reload in the same tab within `HIDDEN_QUERY_KEEP_MS` (30 minutes) brings it back. Blocked storage
+leaves the query visible.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ComponentType } from 'react';
-import { FormDefinition, FormEngine, CreateFormOptions, HostOptions, 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';
 
@@ -107,6 +107,12 @@ interface NavigationSlotProps {
 interface EndingSlotProps {
     title: string;
     description?: string;
+    /**
+     * Buttons or links under the ending, such as "Send another response" or "Change your
+     * answers": pass them through `slotProps.ending`. The default ending shows them in a
+     * centred row.
+     */
+    actions?: ReactNode;
     className?: string;
 }
 interface ErrorSummaryItem {
@@ -133,6 +139,11 @@ interface FormSlotMap {
     ending: EndingSlotProps;
     errorSummary: ErrorSummarySlotProps;
 }
+/**
+ * The built-in ending (a check, the title and description, then any `actions`). Exported
+ * so a custom ending slot can wrap it rather than copy it.
+ */
+declare function DefaultEnding({ title, description, actions, className }: EndingSlotProps): react.JSX.Element;
 interface FormBrand {
     name: string;
     /** An image URL or your own element (decorative: the name is the text). Without one, the name's initials are shown. */
@@ -156,6 +167,15 @@ interface FormProps {
      * `hostOptions`).
      */
     hostOptions?: HostOptions | undefined;
+    /**
+     * The query parameters of the link the form was opened from, such as
+     * `new URLSearchParams(location.search)`. A choice question with
+     * `props.prefill: { param }` starts with that parameter's value picked when
+     * it is one of its options (`prefillFromLink`), and with
+     * `hideWhenPrefilled` it isn't shown at all. Read when the response starts;
+     * unused with `engine` (pass `linkParams` to `useForm` then).
+     */
+    linkParams?: LinkParams | undefined;
     /** Overrides the definition's layout. */
     layout?: "focus" | "classic" | undefined;
     /**
@@ -278,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>;
@@ -300,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
@@ -325,4 +389,29 @@ declare const SourceTextContext: react.Context<string | null>;
 /** The enclosing `SourceTextContext` value, or null. */
 declare function useSourceText(): string | null;
 
-export { type BrandSlotProps, CLASSIC_PROGRESS_DELAY_MS, type EndingSlotProps, type ErrorSummaryItem, type ErrorSummarySlotProps, FieldChrome, type FieldChromeProps, Form, type FormBrand, type FormPresentation, type FormPresentationValue, type FormProps, type FormSlotMap, type FormTheme, type HeaderSlotProps, type MediaTime, MediaTimeContext, type NavigationSlotProps, PROGRESS_DELAY_MS, type ProgressSlotProps, SourceTextContext, type ThemeColors, UPLOAD_WAIT_MESSAGE, UploadContext, type UploadHost, builtInRenderers, defaultRegistry, describedBy, photoAccept, photoFileProblem, photoFileType, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText, useUpload };
+/** How long a reload brings the query back: 30 minutes. */
+declare const HIDDEN_QUERY_KEEP_MS: number;
+/** The parts of `window` `hideQueryOnLoad` uses (pass `window`; tests pass a fake). */
+interface HiddenQueryWindow {
+    location: {
+        pathname: string;
+        search: string;
+        hash: string;
+        replace(url: string): void;
+    };
+    history: {
+        state: unknown;
+        replaceState(data: unknown, unused: string, url: string): void;
+    };
+    sessionStorage: Pick<Storage, "getItem" | "setItem" | "removeItem">;
+}
+/**
+ * Run once when the page has read its query. Returns "hidden" when it took the query out
+ * of the address bar, "restoring" when a reload is bringing a hidden query back (the page
+ * is about to load again), else "none".
+ */
+declare function hideQueryOnLoad(win: HiddenQueryWindow, isReload: boolean, now?: number): "hidden" | "restoring" | "none";
+/** 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, 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 };