@marktiderman/genesis-forms-web 0.3.0 → 0.4.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
@@ -108,6 +121,27 @@ 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.

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, 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';
 
@@ -146,6 +146,16 @@ 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;
     /** Overrides the definition's layout. */
     layout?: "focus" | "classic" | undefined;
     /**
@@ -177,6 +187,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 +220,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 +237,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 +271,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 +325,4 @@ 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 };
+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 };