@marktiderman/genesis-forms-web 0.2.0 → 0.4.0

package/README.md

@@ -24,7 +24,7 @@ import { Form } from "@marktiderman/genesis-forms-web";
   progress bar and Enter to continue (Ctrl/Cmd+Enter in long text; Enter on a focused radio or
   checkbox too). After a single pick (rating, NPS, yes/no, one choice) it moves on by itself
   (`autoAdvance={false}` turns it off): only a click, tap or Space counts as a pick, arrow keys just
-  move through the options, and it never moves on from the last question, so Submit is always a
+  move through the options, and it never moves on from the last question, so Send is always a
   deliberate press. `classic` shows every visible question; a failed submit focuses an error summary
   above the fields that links to each invalid one.
 - **Presentation:** `presentation="embedded"` (the default) is a block inside your own page.
@@ -40,7 +40,7 @@ import { Form } from "@marktiderman/genesis-forms-web";
   button at the top-left. Each new question fades and slides in (CSS `@starting-style`, none with
   `prefers-reduced-motion`). The ending is centred and large. In classic layout, page mode is one
   scrolling page, Google Forms style: a header card with the title and description, each question
-  in its own card (red-edged while invalid), Submit at the end.
+  in its own card (red-edged while invalid), Send at the end.
   `brand={{ name: "Acme", logo }}` shows an organisation's or business's logo (an image URL or an
   element; its initials without one) and name small at the top of every step and on the ending.
   Custom slots and renderers can match with `useFormPresentation()`, which returns
@@ -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
@@ -57,6 +70,18 @@ import { Form } from "@marktiderman/genesis-forms-web";
   question text), a failed Next is announced once through a live region, and the ending heading
   takes focus. Choice rows are full-width labels at least 44px tall; motion respects
   `prefers-reduced-motion`. Ids are unique per form, so two forms can share a page.
+- **Send word and required note:** the send button says `submitLabel` (default **Send**) in every
+  layout. When any question is required, the title shows "\* Required" (`requiredLabel`, default
+  "Required"; `null` hides it).
+- **Theme:** `theme={{ accent: "#f97316", headerImage: url, headerImageAlt }}` sets the form's own
+  primary colour (buttons, selected options, stars, progress, focus rings) and a banner over the
+  title. The accent is adjusted only as far as contrast needs: at least 3:1 against the page in light
+  and dark, and text on it at least 4.5:1. It takes `#rgb`, `#rrggbb` or `rgb()`; anything else is
+  ignored. `themeColors(accent)` returns the colours it would use.
+- **Question types:** besides text, email, phone, rating, NPS, choices and yes/no, there are
+  `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.
 - **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.
@@ -96,6 +121,31 @@ 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.
+
 ## 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, 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';
 
@@ -21,10 +21,56 @@ interface FormPresentationValue {
  */
 declare function useFormPresentation(): FormPresentationValue;
 
+/**
+ * A form's own look: an accent colour and a header image. The accent becomes
+ * the Genesis `--primary` (and `--ring`) inside the form, so every primary
+ * surface follows it: buttons, selected options, stars, progress, focus rings.
+ */
+interface FormTheme {
+    /**
+     * The accent colour, as `#rgb`, `#rrggbb` or `rgb(r, g, b)`, such as a
+     * brand's colour. It is adjusted only as far as needed for contrast: at
+     * least 3:1 against the page (light and dark), with text on it at least
+     * 4.5:1 (white or near-black, whichever reads better). Anything else is ignored.
+     */
+    accent?: string | undefined;
+    /** A banner image URL shown over the form's title. */
+    headerImage?: string | undefined;
+    /** The banner's text alternative. Default "" (decorative). */
+    headerImageAlt?: string | undefined;
+}
+/** Shadcn HSL components (`"221 83% 53%"`), as Genesis tokens hold them. */
+interface ThemeColors {
+    primary: string;
+    primaryForeground: string;
+}
+/**
+ * The accent as Genesis primary colours for a light and a dark page, each
+ * adjusted only as far as contrast needs. Null when `accent` is not a colour
+ * this understands.
+ */
+declare function themeColors(accent: string): {
+    light: ThemeColors;
+    dark: ThemeColors;
+} | null;
+/** The CSS that applies `theme` to the elements matching `selector`, or "" when it changes no colour. */
+declare function themeCss(theme: FormTheme | undefined, selector: string): string;
+
 type SlotOverride<P> = ComponentType<P> | null;
 interface HeaderSlotProps {
     title: string;
     description?: string;
+    /** `theme.headerImage`: a banner over the title. */
+    image?: {
+        src: string;
+        alt: string;
+    } | undefined;
+    /**
+     * The note that marks required questions ("Required", drawn as "* Required"),
+     * set when the form has at least one required question. Empty when it has none
+     * or `requiredLabel` is null.
+     */
+    requiredNote?: string | undefined;
     className?: string;
 }
 interface BrandSlotProps {
@@ -100,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;
     /**
@@ -112,6 +168,13 @@ interface FormProps {
     presentation?: FormPresentation | undefined;
     /** An organisation's or business's name and logo, shown small at the top of every step and on the ending. */
     brand?: FormBrand | undefined;
+    /**
+     * Colours and a header image: `accent` replaces the primary colour (buttons,
+     * selected options, progress, focus ring), adjusted where needed so it keeps
+     * at least 3:1 contrast with the page and its text 4.5:1; `headerImage` is a
+     * banner over the title.
+     */
+    theme?: FormTheme | undefined;
     registry?: RendererRegistry | undefined;
     /**
      * Called once the form completes. The ending shows only after it resolves.
@@ -124,16 +187,47 @@ 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.
      * Never moves on from the last question. Default true.
      */
     autoAdvance?: boolean | undefined;
+    /** The send button's word, the same in every layout. Default "Send". */
     submitLabel?: string | undefined;
+    /** The button that moves to the next question in focus layout. Default "OK". */
     nextLabel?: string | undefined;
+    /**
+     * The note shown with the title when any question is required, after an
+     * asterisk ("* Required"). `null` hides it. Default "Required".
+     */
+    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;
@@ -143,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 {
@@ -173,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
@@ -198,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 HeaderSlotProps, type MediaTime, MediaTimeContext, type NavigationSlotProps, type ProgressSlotProps, SourceTextContext, builtInRenderers, defaultRegistry, describedBy, 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 };