@marktiderman/genesis-forms-web 0.1.1 → 0.3.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)}
 />
@@ -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,14 +40,14 @@ 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.
-  `brand={{ name: "CrossFit Fairfield", logo }}` shows a practice's logo (an image URL or an
+  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
   `{ 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
@@ -57,6 +57,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.
@@ -74,7 +86,31 @@ 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.
+
+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
 

package/dist/index.d.ts

@@ -21,14 +21,60 @@ 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 {
-    /** 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;
@@ -110,8 +156,15 @@ interface FormProps {
      * layout the questions are sections on one scrolling page.
      */
     presentation?: FormPresentation | undefined;
-    /** A practice's name and logo, shown small at the top of every step and on the ending. */
+    /** 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.
@@ -130,8 +183,15 @@ interface FormProps {
      * 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;
     slots?: {
@@ -164,6 +224,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
@@ -172,4 +233,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 FormTheme, type HeaderSlotProps, type MediaTime, MediaTimeContext, type NavigationSlotProps, type ProgressSlotProps, SourceTextContext, type ThemeColors, builtInRenderers, defaultRegistry, describedBy, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText };