@marktiderman/genesis-forms-web 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Tiderman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @marktiderman/genesis-forms-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The web renderer for [Genesis Forms](../forms/README.md), built on Genesis UI components and tokens.
+
+```tsx
+import { Form } from "@marktiderman/genesis-forms-web";
+
+<Form
+  form={afterClass}                    // a defineForm result or a canonical definition
+  layout="focus"                       // one question at a time; or "classic"
+  options={{ hidden: { coach: "Sam" } }}
+  onChange={(state) => saveDraft(state)}
+  onSubmit={(engine) => submit(engine.getState().events)}
+/>
+```
+
+```css
+@import "tailwindcss";
+@import "@marktiderman/genesis-ui/styles.css";
+@import "@marktiderman/genesis-forms-web/styles.css";
+```
+
+- **Layouts:** `focus` moves through the respondent's path one question at a time, with Back, a
+  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
+  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.
+  `presentation="page"` is the respondent's whole screen, for a QR code or a shared link, Typeform
+  style: it fills the viewport (`min-h-dvh`) with no card around it. In focus layout each question
+  sits centred in a `max-w-xl` column under a thin progress bar pinned to the top edge (it fills
+  with questions answered; "Question N of M" is its `aria-valuetext`). The question is large, the
+  form title introduces only the first question (then stays for assistive tech), and rating, NPS
+  and yes/no become an even grid of large targets. Single and multiple choice rows are full width
+  with a letter key, a filled selected state and a check mark; while focus is in the group, pressing
+  an option's letter picks it. OK is a large primary button with a "press Enter ↵" hint ("Ctrl +
+  Enter" or "⌘ + Enter" in long text) shown only on fine-pointer devices, and Back is a quiet icon
+  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
+  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} />
+  ```
+
+- **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
+  focus layout, focus moves to each new question (the input of a text field, otherwise the visible
+  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.
+- **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.
+- **Engines:** `<Form form={def}>` owns an engine and starts a new one when `def` changes identity,
+  so keep the definition stable (module scope or `useMemo`). Pass `engine` (from `useForm`) to read
+  state outside the form; `form` and `options` are then unused, and a new `engine` starts the form
+  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
+  `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:
+  `<Form registry={defaultRegistry.extend([{ type: "email", rank: 10, Component }])} />`.
+  `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.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import * as react from 'react';
+import { ReactNode, ComponentType } from 'react';
+import { FormDefinition, FormEngine, CreateFormOptions, FormState } from '@marktiderman/genesis-forms';
+import * as _marktiderman_genesis_forms_react from '@marktiderman/genesis-forms-react';
+import { RendererRegistry, FieldRendererProps, RendererEntry } from '@marktiderman/genesis-forms-react';
+
+/**
+ * How `<Form>` sits on the page. `"embedded"` is a block inside your app's own
+ * page. `"page"` is the respondent's whole screen (a QR code, a shared link):
+ * it fills the viewport and draws no card around the form.
+ */
+type FormPresentation = "embedded" | "page";
+interface FormPresentationValue {
+    presentation: FormPresentation;
+    layout: "focus" | "classic";
+}
+/**
+ * The presentation and layout of the enclosing `<Form>`, so a custom slot or
+ * renderer can match the built-in ones (larger type and tap targets in page
+ * mode, for example). Outside a `<Form>` it reads embedded and classic.
+ */
+declare function useFormPresentation(): FormPresentationValue;
+
+type SlotOverride<P> = ComponentType<P> | null;
+interface HeaderSlotProps {
+    title: string;
+    description?: string;
+    className?: string;
+}
+interface BrandSlotProps {
+    /** The practice 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;
+    className?: string;
+}
+interface ProgressSlotProps {
+    step: number;
+    total: number;
+    className?: string;
+}
+interface NavigationSlotProps {
+    canGoBack: boolean;
+    isLast: boolean;
+    /** True while `onSubmit` is running. */
+    busy: boolean;
+    /** True after `onSubmit` failed. The answers are kept, and submitting again resends them. */
+    failed: boolean;
+    onBack: () => void;
+    submitLabel: string;
+    nextLabel: string;
+    retryLabel: string;
+    /**
+     * The key that continues from this question ("Enter ↵", or "Ctrl + Enter" in
+     * long text). Set in page presentation's focus layout; the default
+     * navigation shows it only on devices with a fine pointer (mouse, trackpad).
+     */
+    keyHint?: string;
+    className?: string;
+}
+interface EndingSlotProps {
+    title: string;
+    description?: string;
+    className?: string;
+}
+interface ErrorSummaryItem {
+    /** The field's block id. */
+    id: string;
+    /** The question, with recall resolved. */
+    label: string;
+    message: string;
+    /** `#` + the field's element id: the control, or the fieldset of a group. */
+    href: string;
+}
+interface ErrorSummarySlotProps {
+    count: number;
+    /** Every invalid field, in form order. */
+    errors: ErrorSummaryItem[];
+    className?: string;
+}
+/** Every interior part of `<Form>`. Replace one with `slots`, feed one with `slotProps`, drop one with `null`. */
+interface FormSlotMap {
+    header: HeaderSlotProps;
+    brand: BrandSlotProps;
+    progress: ProgressSlotProps;
+    navigation: NavigationSlotProps;
+    ending: EndingSlotProps;
+    errorSummary: ErrorSummarySlotProps;
+}
+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 | undefined;
+}
+interface FormProps {
+    /** A `defineForm` result or a canonical definition. */
+    form: FormDefinition | {
+        definition: FormDefinition;
+    };
+    /** Bring your own engine (from `useForm`) to read state outside the form. `form` and `options` are then unused. */
+    engine?: FormEngine | undefined;
+    options?: CreateFormOptions | undefined;
+    /** Overrides the definition's layout. */
+    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
+     * viewport with no card around it; in focus layout each question is centred
+     * 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 | undefined;
+    /** A practice'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>) | 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 | undefined;
+    submitLabel?: string | undefined;
+    nextLabel?: string | undefined;
+    /** The submit button's label after `onSubmit` failed. Default "Try again". */
+    retryLabel?: string | undefined;
+    slots?: {
+        [K in keyof FormSlotMap]?: SlotOverride<FormSlotMap[K]>;
+    } | undefined;
+    slotProps?: {
+        [K in keyof FormSlotMap]?: Partial<FormSlotMap[K]>;
+    } | undefined;
+    className?: string | undefined;
+    testID?: string | undefined;
+}
+declare function Form(props: FormProps): react.JSX.Element;
+
+interface FieldChromeProps {
+    props: FieldRendererProps;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * Label, description and error around a control. Group types (radio,
+ * checkbox list, rating, scale) get a real `fieldset`/`legend`, so a screen
+ * reader announces the question with every option; the fieldset carries the
+ * field's `inputId` (an error summary links to it) and `aria-describedby`.
+ * `aria-invalid` sits on the controls: ARIA 1.2 doesn't allow it on a group.
+ *
+ * The legend or label is the question text: it has `id="${inputId}-label"`
+ * and `tabIndex={-1}` and is marked `data-gf-question`, which the focus
+ * layout focuses on each new question unless the control is marked
+ * `data-gf-focus` (text fields mark their input, so typing just works).
+ */
+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
+ * `registry`. `extend()` returns a new registry and leaves this one alone;
+ * `register()` changes this one in place, for every form in the app.
+ */
+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 };