@marktiderman/genesis-forms-web 0.1.0 → 0.2.0

package/README.md

@@ -6,9 +6,9 @@ The web renderer for [Genesis Forms](../forms/README.md), built on Genesis UI co
 import { Form } from "@marktiderman/genesis-forms-web";
 
 <Form
-  form={afterClass}                    // a defineForm result or a canonical definition
+  form={eventFeedback}                 // a defineForm result or a canonical definition
   layout="focus"                       // one question at a time; or "classic"
-  options={{ hidden: { coach: "Sam" } }}
+  options={{ hidden: { owner: "Sam" } }}
   onChange={(state) => saveDraft(state)}
   onSubmit={(engine) => submit(engine.getState().events)}
 />
@@ -41,13 +41,13 @@ import { Form } from "@marktiderman/genesis-forms-web";
   `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.
-  `brand={{ name: "CrossFit Fairfield", logo }}` shows a practice's logo (an image URL or an
+  `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
   `{ presentation, layout }`.
 
   ```tsx
-  <Form form={afterClass} presentation="page" brand={{ name: "CrossFit Fairfield" }} onSubmit={send} />
+  <Form form={eventFeedback} presentation="page" brand={{ name: "Acme" }} onSubmit={send} />
   ```
 
 - **Accessible by default:** group questions are a `fieldset` with a `legend`, and rating, NPS and
@@ -74,7 +74,27 @@ import { Form } from "@marktiderman/genesis-forms-web";
   `defaultRegistry.register(entry)` mutates the shared registry in place, for every form in the app.
 
 Renderers: short and long text, email, phone (`type="tel"`), rating, NPS, single choice, multiple
-choice, yes/no.
+choice, yes/no, and the structured types:
+
+- **`list`** (goals, action items, three wins) and **`table`** (an action plan with What / Who /
+  By when, pros and cons) add, remove and reorder entries (SortableList: drag, keyboard and a Move
+  menu).
+- **`media-notes`** (lecture notes, reviewing a recorded call) takes a typed time (`m:ss`,
+  `h:mm:ss` or seconds). Wrap the form in `MediaTimeContext` to link it to your video or audio
+  player: `currentTime` prefills "Add note at 1:23" and `seek` plays from a note.
+- **`text-highlights`** (annotating an article, a policy or a contract) takes highlights by
+  selecting words in the passage or typing them. The passage is the field's `text` prop, or the
+  value of `SourceTextContext` around the form.
+
+```tsx
+<MediaTimeContext.Provider value={{ currentTime: () => player.currentTime, seek: (s) => player.seek(s) }}>
+  <SourceTextContext.Provider value={article.body}>
+    <Form form={videoNotes} onSubmit={send} />
+  </SourceTextContext.Provider>
+</MediaTimeContext.Provider>
+```
+
+`useMediaTime()` and `useSourceText()` read them in a custom renderer.
 
 ## License
 

package/dist/index.d.ts

@@ -28,7 +28,7 @@ interface HeaderSlotProps {
     className?: string;
 }
 interface BrandSlotProps {
-    /** The practice or business name, shown beside the logo. */
+    /** The organisation or business name, shown beside the logo. */
     name: string;
     /** An image URL or your own element. Without one, the name's initials are shown. */
     logo?: ReactNode;
@@ -90,7 +90,7 @@ interface FormSlotMap {
 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. */
-    logo?: ReactNode;
+    logo?: ReactNode | undefined;
 }
 interface FormProps {
     /** A `defineForm` result or a canonical definition. */
@@ -98,10 +98,10 @@ interface FormProps {
         definition: FormDefinition;
     };
     /** Bring your own engine (from `useForm`) to read state outside the form. `form` and `options` are then unused. */
-    engine?: FormEngine;
-    options?: CreateFormOptions;
+    engine?: FormEngine | undefined;
+    options?: CreateFormOptions | undefined;
     /** Overrides the definition's layout. */
-    layout?: "focus" | "classic";
+    layout?: "focus" | "classic" | undefined;
     /**
      * `"embedded"` (default): a block inside your own page. `"page"`: the
      * respondent's whole screen, for a QR code or a shared link. It fills the
@@ -109,36 +109,39 @@ interface FormProps {
      * under a thin progress bar with large type and tap targets, and in classic
      * layout the questions are sections on one scrolling page.
      */
-    presentation?: FormPresentation;
-    /** A practice's name and logo, shown small at the top of every step and on the ending. */
-    brand?: FormBrand;
-    registry?: RendererRegistry;
+    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;
+    registry?: RendererRegistry | undefined;
     /**
      * Called once the form completes. The ending shows only after it resolves.
      * If it rejects, the answers stay on screen, read-only (a completed response
      * is final), with an error and a "Try again" button that sends them again.
      */
-    onSubmit?: (engine: FormEngine) => void | Promise<void>;
-    /** Called after every answer (debounce it to save drafts). */
-    onChange?: (state: FormState, engine: FormEngine) => void;
+    onSubmit?: ((engine: FormEngine) => void | Promise<void>) | undefined;
+    /**
+     * Called on every state change: an answer, a step forward or back, a
+     * submit attempt (debounce it to save drafts).
+     */
+    onChange?: ((state: FormState, engine: FormEngine) => void) | 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;
-    submitLabel?: string;
-    nextLabel?: string;
+    autoAdvance?: boolean | undefined;
+    submitLabel?: string | undefined;
+    nextLabel?: string | undefined;
     /** The submit button's label after `onSubmit` failed. Default "Try again". */
-    retryLabel?: string;
+    retryLabel?: string | undefined;
     slots?: {
         [K in keyof FormSlotMap]?: SlotOverride<FormSlotMap[K]>;
-    };
+    } | undefined;
     slotProps?: {
         [K in keyof FormSlotMap]?: Partial<FormSlotMap[K]>;
-    };
-    className?: string;
-    testID?: string;
+    } | undefined;
+    className?: string | undefined;
+    testID?: string | undefined;
 }
 declare function Form(props: FormProps): react.JSX.Element;
 
@@ -161,6 +164,7 @@ interface FieldChromeProps {
  */
 declare function FieldChrome({ props, children, className }: FieldChromeProps): react.JSX.Element;
 declare function describedBy(props: FieldRendererProps): string | undefined;
+
 declare const builtInRenderers: RendererEntry[];
 /**
  * The built-in web renderers, shared by every `<Form>` that gets no
@@ -169,4 +173,29 @@ declare const builtInRenderers: RendererEntry[];
  */
 declare const defaultRegistry: _marktiderman_genesis_forms_react.RendererRegistry;
 
-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 NavigationSlotProps, type ProgressSlotProps, builtInRenderers, defaultRegistry, describedBy, useFormPresentation };
+/**
+ * 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
+ * ("Add note at 1:23"), with `seek` a note's time plays the media from there.
+ * Both are in seconds from the start of the full recording.
+ */
+interface MediaTime {
+    /** The playhead now, or undefined when it isn't known yet. */
+    currentTime?: (() => number | undefined) | undefined;
+    /** Move the playhead. */
+    seek?: ((seconds: number) => void) | undefined;
+}
+/** Provide it around `<Form>` to link `media-notes` fields to a media player. */
+declare const MediaTimeContext: react.Context<MediaTime | null>;
+/** The enclosing `MediaTimeContext` value, or null. */
+declare function useMediaTime(): MediaTime | null;
+/**
+ * The text a form is about (an article, a policy, a contract). `text-highlights`
+ * fields highlight passages of it; a field's own `props.text` is used when no
+ * host provides one. Offsets are UTF-16 indices into this exact string.
+ */
+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 };