@marktiderman/genesis-forms-web 0.3.0 → 0.5.0

package/README.md

@@ -50,6 +50,19 @@ import { Form } from "@marktiderman/genesis-forms-web";
   <Form form={eventFeedback} presentation="page" brand={{ name: "Acme" }} onSubmit={send} />
   ```
 
+- **Save answers as they go:** with the definition's `settings.saveProgress` on, `onProgress(engine,
+  { step, total, fieldId })` is called a moment after each step forward (`PROGRESS_DELAY_MS`; in
+  classic layout, `CLASSIC_PROGRESS_DELAY_MS` after the answers change), with `fieldId` the
+  furthest question reached (`formProgress` from genesis-forms) and `engine.answers()` the answers
+  so far. It never holds up Next: a rejection is ignored (the next call carries every answer
+  again), a pending call goes at once on `pagehide`, and none is made once the form is submitted.
+  Under the first question a note says "Your answers save as you go." (`progressNotice`; `null`
+  hides it). Without `onProgress`, or with the setting off, nothing is saved and nothing is said.
+
+  ```tsx
+  <Form form={feedback} presentation="page" onProgress={(engine, p) => saveDraft(engine.answers(), p.fieldId)} onSubmit={send} />
+  ```
+
 - **Accessible by default:** group questions are a `fieldset` with a `legend`, and rating, NPS and
   yes/no are real radio groups (arrows select). Every control carries `aria-invalid`,
   errors are linked with `aria-describedby`, and the NPS end labels are read with 0 and 10. In
@@ -69,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.
@@ -78,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:
@@ -108,10 +138,48 @@ choice, yes/no, and the structured types:
 
 `useMediaTime()` and `useSourceText()` read them in a custom renderer.
 
+**`photo`** (a picture of broken equipment) has "Choose a photo" and, on a phone or tablet, "Take a
+photo" (the camera), checks each file's type, size and the count before uploading, shows a thumbnail
+(or the file's name when the browser can't draw it, such as HEIC) and removes one. The file goes to
+the host, which stores it and resolves to its reference; the answer keeps only that:
+
+```tsx
+<Form
+  form={feedback}
+  onUpload={async (file, field) => {
+    const { ref } = await uploadSomewhere(file, field.id); // your storage
+    return ref; // { id, name, type, size }
+  }}
+  onSubmit={send}
+/>
+```
+
+A rejected upload shows under the field. While a photo is uploading the form neither moves on nor
+sends (it says "Wait for the photo to finish uploading."). Without `onUpload`, or an
+`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.
+
 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, FormState } from '@marktiderman/genesis-forms';
+import { FormDefinition, FormEngine, CreateFormOptions, HostOptions, LinkParams, FormState, FormProgress, FieldBlock, PhotoRef } 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. */
@@ -146,6 +157,25 @@ interface FormProps {
     /** Bring your own engine (from `useForm`) to read state outside the form. `form` and `options` are then unused. */
     engine?: FormEngine | undefined;
     options?: CreateFormOptions | undefined;
+    /**
+     * Option lists this app supplies, by key, for choice questions whose
+     * options come from the app (`props.optionsFrom: { source: "host", key }`),
+     * such as `{ coaches: [{ value: "8c1…", label: "Ada Lovelace" }] }`. Shown
+     * after the question's own options. Like `options`, read when the response
+     * starts; unused with `engine` (pass `hostOptions` to `useForm` then). Check
+     * answers on the server with the same lists (`validateSubmission`'s
+     * `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;
     /**
@@ -177,6 +207,22 @@ interface FormProps {
      * submit attempt (debounce it to save drafts).
      */
     onChange?: ((state: FormState, engine: FormEngine) => void) | undefined;
+    /**
+     * Save answers as they go: with the definition's `settings.saveProgress` on,
+     * called a moment after each step forward (in classic layout, a moment after
+     * the answers change) with how far the respondent got (`formProgress`); read
+     * the answers so far with `engine.answers()`. It never holds them up: it runs
+     * after the step, and a rejection is ignored (the next call carries every
+     * answer again). A pending call goes at once when the page is hidden, and none
+     * is made once the form is submitted.
+     */
+    onProgress?: ((engine: FormEngine, progress: FormProgress) => void | Promise<void>) | undefined;
+    /**
+     * The note under the first question while answers save as they go (only with
+     * `onProgress` and `settings.saveProgress`). `null` hides it. Default
+     * "Your answers save as you go."
+     */
+    progressNotice?: string | null | undefined;
     /**
      * In focus layout, move on after a single pick (rating, yes/no, one choice).
      * Arrow keys only move through the options; a click, tap or Space picks.
@@ -194,6 +240,14 @@ interface FormProps {
     requiredLabel?: string | null | undefined;
     /** The submit button's label after `onSubmit` failed. Default "Try again". */
     retryLabel?: string | undefined;
+    /**
+     * Stores a file a respondent adds to a `photo` field and resolves to its
+     * reference (`{ id, name, type, size }`), which is all the answer keeps; a
+     * rejection shows under the field. While any upload is in flight the form
+     * neither moves on nor sends. Without it (and without an `UploadContext`
+     * above the form), photo fields say photos can't be added.
+     */
+    onUpload?: ((file: File, field: FieldBlock) => Promise<PhotoRef>) | undefined;
     slots?: {
         [K in keyof FormSlotMap]?: SlotOverride<FormSlotMap[K]>;
     } | undefined;
@@ -203,6 +257,10 @@ interface FormProps {
     className?: string | undefined;
     testID?: string | undefined;
 }
+/** How long after a step forward `onProgress` waits, so quick steps save once. */
+declare const PROGRESS_DELAY_MS = 400;
+/** In classic layout, how long after the last answer changed. */
+declare const CLASSIC_PROGRESS_DELAY_MS = 1500;
 declare function Form(props: FormProps): react.JSX.Element;
 
 interface FieldChromeProps {
@@ -233,6 +291,35 @@ declare const builtInRenderers: RendererEntry[];
  */
 declare const defaultRegistry: _marktiderman_genesis_forms_react.RendererRegistry;
 
+/**
+ * Where a form's files go. The host stores each file (its own bucket, its own
+ * rules) and resolves to a reference, which is all the answer keeps; a
+ * rejection is shown under the field. `photo` fields read it.
+ */
+interface UploadHost {
+    upload(file: File, field: FieldBlock): Promise<PhotoRef>;
+}
+/** Provide it around `<Form>` (or pass `onUpload`) so `photo` fields can store files. */
+declare const UploadContext: react.Context<UploadHost | null>;
+/** The enclosing `UploadContext` value, or null when no host stores files. */
+declare function useUpload(): UploadHost | null;
+/** Said when the respondent tries to move on or send while a photo is still uploading. */
+declare const UPLOAD_WAIT_MESSAGE = "Wait for the photo to finish uploading.";
+
+/** The file's type as the field judges it: some browsers give a HEIC photo no type, so its name decides. */
+declare function photoFileType(file: {
+    name: string;
+    type: string;
+}): string;
+/** Why a picked file can't be added, or null when it can. */
+declare function photoFileProblem(field: FieldBlock, file: {
+    name: string;
+    type: string;
+    size: number;
+}): string | null;
+/** 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;
+
 /**
  * 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
@@ -258,4 +345,29 @@ declare const SourceTextContext: react.Context<string | null>;
 /** The enclosing `SourceTextContext` value, or null. */
 declare function useSourceText(): string | null;
 
-export { type BrandSlotProps, 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, type ProgressSlotProps, SourceTextContext, type ThemeColors, builtInRenderers, defaultRegistry, describedBy, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText };
+/** 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, SourceTextContext, type ThemeColors, UPLOAD_WAIT_MESSAGE, UploadContext, type UploadHost, builtInRenderers, defaultRegistry, describedBy, hideQueryOnLoad, photoAccept, photoFileProblem, photoFileType, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText, useUpload, wasReload };