@marktiderman/genesis-forms-web 0.4.0 → 0.5.0

package/README.md

@@ -82,6 +82,21 @@ import { Form } from "@marktiderman/genesis-forms-web";
   `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.
+- **Option lists:** an option's `description` is a muted line under its label and its `image` a
+  small picture beside it. A choice question with more than 10 options it shows (or with
+  `searchable: true`) gets a search box over an in-page list instead of radios, checkboxes or a
+  select: typing narrows it (`searchOptions`), arrow keys move, Enter or a tap picks, and it
+  works the same in classic and focus layouts and on a phone. A list filtered by another answer
+  (`optionsFrom.filter`) shows only the matching options and drops a pick that stops matching.
+  `linkParams` (such as `new URLSearchParams(location.search)`) preselects questions with
+  `prefill: { param }`; with `hideWhenPrefilled` a question the link answered isn't shown or
+  counted. Which options show, when to search and what a link picks are all decided in
+  genesis-forms (`visibleOptions`, `isSearchable`, `prefillFromLink`, `respondentPath`), so
+  every renderer agrees with the engine and the server:
+
+  ```tsx
+  <Form form={def} hostOptions={lists} linkParams={new URLSearchParams(location.search)} />
+  ```
 - **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.
@@ -91,7 +106,9 @@ import { Form } from "@marktiderman/genesis-forms-web";
   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
+  ending can mark an element `data-gf-focus` to receive focus; `slotProps={{ ending: { actions } }}`
+  puts buttons or links (Send another response, Change your answers) in a centred row under the
+  default ending, and `DefaultEnding` is exported for a custom ending to wrap; 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:
@@ -146,6 +163,23 @@ A **`calculated`** field shows the value the engine worked out from other answer
 `<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.
 
+## Clean form links
+
+A link's query (`?edit=`, prefilled answers, `utm_…`) can be taken out of the address bar once the
+page has read it, so it stays out of screenshots and shared addresses. Cosmetic, not security: the
+server still checks every value. Call it once, after reading the query:
+
+```ts
+import { hideQueryOnLoad, wasReload } from "@marktiderman/genesis-forms-web";
+
+useEffect(() => void hideQueryOnLoad(window, wasReload()), []);
+```
+
+It uses the browser's own `History.prototype.replaceState` (a router that patches the instance's
+would otherwise re-read the address), and keeps the query in sessionStorage (`form-query:<path>`) so
+a reload in the same tab within `HIDDEN_QUERY_KEEP_MS` (30 minutes) brings it back. Blocked storage
+leaves the query visible.
+
 ## 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, HostOptions, FormState, FormProgress, FieldBlock, PhotoRef } from '@marktiderman/genesis-forms';
+import { FormDefinition, FormEngine, CreateFormOptions, HostOptions, LinkParams, 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';
 
@@ -107,6 +107,12 @@ interface NavigationSlotProps {
 interface EndingSlotProps {
     title: string;
     description?: string;
+    /**
+     * Buttons or links under the ending, such as "Send another response" or "Change your
+     * answers": pass them through `slotProps.ending`. The default ending shows them in a
+     * centred row.
+     */
+    actions?: ReactNode;
     className?: string;
 }
 interface ErrorSummaryItem {
@@ -133,6 +139,11 @@ interface FormSlotMap {
     ending: EndingSlotProps;
     errorSummary: ErrorSummarySlotProps;
 }
+/**
+ * The built-in ending (a check, the title and description, then any `actions`). Exported
+ * so a custom ending slot can wrap it rather than copy it.
+ */
+declare function DefaultEnding({ title, description, actions, className }: EndingSlotProps): react.JSX.Element;
 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. */
@@ -156,6 +167,15 @@ interface FormProps {
      * `hostOptions`).
      */
     hostOptions?: HostOptions | undefined;
+    /**
+     * The query parameters of the link the form was opened from, such as
+     * `new URLSearchParams(location.search)`. A choice question with
+     * `props.prefill: { param }` starts with that parameter's value picked when
+     * it is one of its options (`prefillFromLink`), and with
+     * `hideWhenPrefilled` it isn't shown at all. Read when the response starts;
+     * unused with `engine` (pass `linkParams` to `useForm` then).
+     */
+    linkParams?: LinkParams | undefined;
     /** Overrides the definition's layout. */
     layout?: "focus" | "classic" | undefined;
     /**
@@ -325,4 +345,29 @@ declare const SourceTextContext: react.Context<string | null>;
 /** The enclosing `SourceTextContext` value, or null. */
 declare function useSourceText(): string | null;
 
-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 };
+/** How long a reload brings the query back: 30 minutes. */
+declare const HIDDEN_QUERY_KEEP_MS: number;
+/** The parts of `window` `hideQueryOnLoad` uses (pass `window`; tests pass a fake). */
+interface HiddenQueryWindow {
+    location: {
+        pathname: string;
+        search: string;
+        hash: string;
+        replace(url: string): void;
+    };
+    history: {
+        state: unknown;
+        replaceState(data: unknown, unused: string, url: string): void;
+    };
+    sessionStorage: Pick<Storage, "getItem" | "setItem" | "removeItem">;
+}
+/**
+ * Run once when the page has read its query. Returns "hidden" when it took the query out
+ * of the address bar, "restoring" when a reload is bringing a hidden query back (the page
+ * is about to load again), else "none".
+ */
+declare function hideQueryOnLoad(win: HiddenQueryWindow, isReload: boolean, now?: number): "hidden" | "restoring" | "none";
+/** Whether this page load was a reload (Navigation Timing), in the browser; false elsewhere. */
+declare const wasReload: () => boolean;
+
+export { type BrandSlotProps, CLASSIC_PROGRESS_DELAY_MS, DefaultEnding, type EndingSlotProps, type ErrorSummaryItem, type ErrorSummarySlotProps, FieldChrome, type FieldChromeProps, Form, type FormBrand, type FormPresentation, type FormPresentationValue, type FormProps, type FormSlotMap, type FormTheme, HIDDEN_QUERY_KEEP_MS, type HeaderSlotProps, type HiddenQueryWindow, type MediaTime, MediaTimeContext, type NavigationSlotProps, PROGRESS_DELAY_MS, type ProgressSlotProps, SourceTextContext, type ThemeColors, UPLOAD_WAIT_MESSAGE, UploadContext, type UploadHost, builtInRenderers, defaultRegistry, describedBy, hideQueryOnLoad, photoAccept, photoFileProblem, photoFileType, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText, useUpload, wasReload };

package/dist/index.js

@@ -3,8 +3,8 @@ import { createContext, useState, useEffect, useRef, useId, useContext, useMemo,
 import { Button } from '@marktiderman/genesis-ui/button';
 import { Progress } from '@marktiderman/genesis-ui/progress';
 import { cn } from '@marktiderman/genesis-ui/utils';
-import { ratingDisplay, choiceOptions, otherOption, numberLimits, dateLimits, listLimits, tableColumns, tableLimits, parseTimestamp, formatTimestamp, formatCalculated, photoLimits, photoRefs, getFieldType, scaleLabels, OTHER_MAX_LENGTH, photoCountMessage, isPhotoRef, photoTypeMessage, photoSizeMessage, formProgress } from '@marktiderman/genesis-forms';
-import { createRendererRegistry, useFormSelector, useForm, FormRuntime, useFormContext, FieldRenderer } from '@marktiderman/genesis-forms-react';
+import { ratingDisplay, numberLimits, dateLimits, listLimits, tableColumns, tableLimits, parseTimestamp, formatTimestamp, formatCalculated, photoLimits, photoRefs, getFieldType, scaleLabels, isSearchable, otherOption, choiceOptions, searchOptions, OTHER_MAX_LENGTH, photoCountMessage, isPhotoRef, photoTypeMessage, photoSizeMessage, respondentPath, formProgress } from '@marktiderman/genesis-forms';
+import { createRendererRegistry, useFormSelector, useChoiceOptions, useForm, FormRuntime, useFormContext, FieldRenderer } from '@marktiderman/genesis-forms-react';
 import { Checkbox } from '@marktiderman/genesis-ui/checkbox';
 import { Input } from '@marktiderman/genesis-ui/input';
 import { Label } from '@marktiderman/genesis-ui/label';
@@ -15,6 +15,7 @@ import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { Stack } from '@marktiderman/genesis-ui/layout';
 import { SortableList } from '@marktiderman/genesis-ui/sortable-list';
 import { Spinner } from '@marktiderman/genesis-ui/spinner';
+import { Command, CommandInput, CommandList, CommandEmpty, CommandItem } from '@marktiderman/genesis-ui/command';
 
 // src/Form.tsx
 var FormPresentationContext = createContext({ presentation: "embedded", layout: "classic" });
@@ -1004,6 +1005,127 @@ function PhotoField(props) {
   ] }) });
 }
 var photoRenderers = [{ type: "photo", Component: PhotoField }];
+function OptionImage({ src, large }) {
+  return /* @__PURE__ */ jsx(
+    "img",
+    {
+      src,
+      alt: "",
+      loading: "lazy",
+      "data-gf-option-image": "",
+      className: cn("shrink-0 rounded-md bg-muted object-cover", large ? "size-12" : "size-10")
+    }
+  );
+}
+function OptionText({ label, description }) {
+  return /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [
+    /* @__PURE__ */ jsx("span", { children: label }),
+    description ? /* @__PURE__ */ jsx("span", { className: "text-sm text-muted-foreground", "data-gf-option-description": "", children: description }) : null
+  ] });
+}
+function CheckMark({ on }) {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2.5",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true",
+      className: cn("size-4 shrink-0 text-primary", on ? "opacity-100" : "opacity-0"),
+      children: /* @__PURE__ */ jsx("path", { d: "M20 6 9 17l-5-5" })
+    }
+  );
+}
+var SEARCH_OTHER_VALUE = "\0other";
+function SearchableOptions({
+  props,
+  options,
+  selected,
+  multiple,
+  otherLabel,
+  otherOn,
+  onPick
+}) {
+  const { binding, inputId } = props;
+  const [query, setQuery] = useState("");
+  const { presentation } = useFormPresentation();
+  const page = presentation === "page";
+  const shown = searchOptions(options, query);
+  const chosen = options.filter((o) => selected.includes(o.value));
+  const labelOf = (o) => o.label ?? o.value;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: "space-y-2",
+      "data-gf-searchable": "",
+      onKeyDown: (e) => {
+        if (e.key === "Enter" && e.target.tagName === "INPUT") e.preventDefault();
+      },
+      children: [
+        /* @__PURE__ */ jsxs(Command, { shouldFilter: false, label: binding.label, className: "rounded-md border border-input bg-background", children: [
+          /* @__PURE__ */ jsx(
+            CommandInput,
+            {
+              id: inputId,
+              "data-gf-focus": "",
+              value: query,
+              onValueChange: setQuery,
+              placeholder: "Type to search",
+              "aria-label": `Search: ${binding.label}`,
+              "aria-invalid": binding.error ? true : void 0,
+              "aria-required": binding.field.required || void 0,
+              className: cn(page && "text-base")
+            }
+          ),
+          /* @__PURE__ */ jsxs(CommandList, { className: "max-h-72", "aria-multiselectable": multiple || void 0, children: [
+            /* @__PURE__ */ jsx(CommandEmpty, { children: "No matches." }),
+            shown.map((o) => {
+              const on = selected.includes(o.value);
+              return /* @__PURE__ */ jsxs(
+                CommandItem,
+                {
+                  value: o.value,
+                  keywords: [labelOf(o)],
+                  "aria-checked": on,
+                  onSelect: () => onPick(o.value),
+                  className: cn("min-h-11 gap-3 text-base", page && "min-h-12"),
+                  "data-gf-option": o.value,
+                  children: [
+                    /* @__PURE__ */ jsx(CheckMark, { on }),
+                    o.image ? /* @__PURE__ */ jsx(OptionImage, { src: o.image }) : null,
+                    /* @__PURE__ */ jsx(OptionText, { label: labelOf(o), description: o.description })
+                  ]
+                },
+                o.value
+              );
+            }),
+            otherLabel ? /* @__PURE__ */ jsxs(
+              CommandItem,
+              {
+                value: SEARCH_OTHER_VALUE,
+                "aria-checked": !!otherOn,
+                onSelect: () => onPick(SEARCH_OTHER_VALUE),
+                className: cn("min-h-11 gap-3 text-base", page && "min-h-12"),
+                children: [
+                  /* @__PURE__ */ jsx(CheckMark, { on: !!otherOn }),
+                  /* @__PURE__ */ jsx(OptionText, { label: otherLabel })
+                ]
+              }
+            ) : null
+          ] })
+        ] }),
+        chosen.length ? /* @__PURE__ */ jsxs("p", { className: "text-sm text-muted-foreground", "aria-live": "polite", "data-gf-chosen": "", children: [
+          multiple ? "Chosen" : "Your choice",
+          ": ",
+          chosen.map(labelOf).join(", ")
+        ] }) : null
+      ]
+    }
+  );
+}
 function groupAria(props) {
   return {
     "aria-labelledby": `${props.inputId}-label`,
@@ -1278,8 +1400,19 @@ function useChoiceLook(inputId, count) {
     } : void 0
   };
 }
-function ChoiceContent({ look, index, label }) {
-  if (!look.pageFocus) return /* @__PURE__ */ jsx("span", { children: label });
+function ChoiceContent({
+  look,
+  index,
+  label,
+  description,
+  image
+}) {
+  if (!look.pageFocus) {
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      image ? /* @__PURE__ */ jsx(OptionImage, { src: image }) : null,
+      /* @__PURE__ */ jsx(OptionText, { label, description })
+    ] });
+  }
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx(
       "span",
@@ -1289,7 +1422,8 @@ function ChoiceContent({ look, index, label }) {
         children: KEYS[index] ?? ""
       }
     ),
-    /* @__PURE__ */ jsx("span", { className: "flex-1", children: label }),
+    image ? /* @__PURE__ */ jsx(OptionImage, { src: image, large: true }) : null,
+    /* @__PURE__ */ jsx(OptionText, { label, description }),
     /* @__PURE__ */ jsx(
       "svg",
       {
@@ -1335,13 +1469,115 @@ function useOtherText(typed) {
   const [text, setText] = useState(typed);
   return { on, setOn, text, setText };
 }
+function SearchableSingleField(props) {
+  const { binding, onAdvance } = props;
+  const options = useChoiceOptions(props.engine, binding.field.id);
+  const other = otherOption(binding.field);
+  const current = typeof binding.value === "string" ? binding.value : "";
+  const typed = other && current && !choiceOptions(binding.field).some((o) => o.value === current) ? current : "";
+  const otherText = useOtherText(typed);
+  const textId = `${props.inputId}-other-text`;
+  return /* @__PURE__ */ jsxs(FieldChrome, { props, children: [
+    /* @__PURE__ */ jsx(
+      SearchableOptions,
+      {
+        props,
+        options,
+        selected: otherText.on ? [] : [current],
+        multiple: false,
+        otherLabel: other?.label,
+        otherOn: otherText.on,
+        onPick: (v) => {
+          if (v === SEARCH_OTHER_VALUE) {
+            otherText.setOn(true);
+            binding.setValue(otherText.text.trim() ? otherText.text : void 0);
+            focusSoon(textId);
+            return;
+          }
+          otherText.setOn(false);
+          binding.setValue(v);
+          onAdvance?.();
+        }
+      }
+    ),
+    other && otherText.on ? /* @__PURE__ */ jsx(
+      OtherText,
+      {
+        id: textId,
+        label: other.label,
+        value: otherText.text,
+        invalid: !!binding.error,
+        onChange: (text) => {
+          otherText.setText(text);
+          binding.setValue(text.trim() ? text : void 0);
+        }
+      }
+    ) : null
+  ] });
+}
+function SearchableMultiField(props) {
+  const { binding } = props;
+  const options = useChoiceOptions(props.engine, binding.field.id);
+  const other = otherOption(binding.field);
+  const selected = Array.isArray(binding.value) ? binding.value : [];
+  const known = new Set(choiceOptions(binding.field).map((o) => o.value));
+  const chosen = selected.filter((v) => known.has(v));
+  const otherText = useOtherText(other ? selected.find((v) => !known.has(v)) ?? "" : "");
+  const textId = `${props.inputId}-other-text`;
+  const commit = (picked, otherOn, text) => {
+    const next = otherOn && text.trim() ? [...picked, text] : picked;
+    binding.setValue(next.length ? next : void 0);
+  };
+  return /* @__PURE__ */ jsxs(FieldChrome, { props, children: [
+    /* @__PURE__ */ jsx(
+      SearchableOptions,
+      {
+        props,
+        options,
+        selected: chosen,
+        multiple: true,
+        otherLabel: other?.label,
+        otherOn: otherText.on,
+        onPick: (v) => {
+          if (v === SEARCH_OTHER_VALUE) {
+            const on = !otherText.on;
+            otherText.setOn(on);
+            commit(chosen, on, otherText.text);
+            if (on) focusSoon(textId);
+            return;
+          }
+          commit(chosen.includes(v) ? chosen.filter((x) => x !== v) : [...chosen, v], otherText.on, otherText.text);
+        }
+      }
+    ),
+    other && otherText.on ? /* @__PURE__ */ jsx(
+      OtherText,
+      {
+        id: textId,
+        label: other.label,
+        value: otherText.text,
+        invalid: !!binding.error,
+        onChange: (text) => {
+          otherText.setText(text);
+          commit(chosen, true, text);
+        }
+      }
+    ) : null
+  ] });
+}
+function useSearchable(props) {
+  return isSearchable(props.binding.field);
+}
 function SingleChoiceField(props) {
+  return useSearchable(props) ? /* @__PURE__ */ jsx(SearchableSingleField, { ...props }) : /* @__PURE__ */ jsx(SingleChoiceList, { ...props });
+}
+function SingleChoiceList(props) {
   const { binding, inputId, onAdvance } = props;
   const pick = useDeliberatePick(onAdvance);
-  const options = choiceOptions(binding.field);
+  const options = useChoiceOptions(props.engine, binding.field.id);
   const other = otherOption(binding.field);
   const current = typeof binding.value === "string" ? binding.value : "";
-  const typed = other && current && !options.some((o) => o.value === current) ? current : "";
+  const typed = other && current && !choiceOptions(binding.field).some((o) => o.value === current) ? current : "";
   const otherText = useOtherText(typed);
   const look = useChoiceLook(inputId, options.length + (other ? 1 : 0));
   const textId = `${inputId}-other-text`;
@@ -1376,7 +1612,7 @@ function SingleChoiceField(props) {
                 className: look.control
               }
             ),
-            /* @__PURE__ */ jsx(ChoiceContent, { look, index: i, label: o.label ?? o.value })
+            /* @__PURE__ */ jsx(ChoiceContent, { look, index: i, label: o.label ?? o.value, description: o.description, image: o.image })
           ] }, o.value)),
           other ? (
             // No auto-advance: the respondent still has to type.
@@ -1404,11 +1640,14 @@ function SingleChoiceField(props) {
   ] });
 }
 function MultiChoiceField(props) {
+  return useSearchable(props) ? /* @__PURE__ */ jsx(SearchableMultiField, { ...props }) : /* @__PURE__ */ jsx(MultiChoiceList, { ...props });
+}
+function MultiChoiceList(props) {
   const { binding, inputId } = props;
   const selected = Array.isArray(binding.value) ? binding.value : [];
-  const options = choiceOptions(binding.field);
+  const options = useChoiceOptions(props.engine, binding.field.id);
   const other = otherOption(binding.field);
-  const known = new Set(options.map((o) => o.value));
+  const known = new Set(choiceOptions(binding.field).map((o) => o.value));
   const chosen = selected.filter((v) => known.has(v));
   const otherText = useOtherText(other ? selected.find((v) => !known.has(v)) ?? "" : "");
   const look = useChoiceLook(inputId, options.length + (other ? 1 : 0));
@@ -1431,7 +1670,7 @@ function MultiChoiceField(props) {
           className: look.control
         }
       ),
-      /* @__PURE__ */ jsx(ChoiceContent, { look, index: i, label: o.label ?? o.value })
+      /* @__PURE__ */ jsx(ChoiceContent, { look, index: i, label: o.label ?? o.value, description: o.description, image: o.image })
     ] }, o.value)),
     other ? /* @__PURE__ */ jsxs(Label, { htmlFor: `${inputId}-${options.length}`, className: look.row, children: [
       /* @__PURE__ */ jsx(
@@ -1482,12 +1721,15 @@ function controlAria(props) {
   };
 }
 function DropdownField(props) {
+  return useSearchable(props) ? /* @__PURE__ */ jsx(SearchableSingleField, { ...props }) : /* @__PURE__ */ jsx(DropdownSelect, { ...props });
+}
+function DropdownSelect(props) {
   const { binding } = props;
-  const options = choiceOptions(binding.field);
+  const options = useChoiceOptions(props.engine, binding.field.id);
   const other = otherOption(binding.field);
   const line = useLineClass();
   const current = typeof binding.value === "string" ? binding.value : "";
-  const typed = other && current && !options.some((o) => o.value === current) ? current : "";
+  const typed = other && current && !choiceOptions(binding.field).some((o) => o.value === current) ? current : "";
   const otherText = useOtherText(typed);
   const value = otherText.on ? OTHER_VALUE : current;
   const textId = `${props.inputId}-other-text`;
@@ -1899,8 +2141,9 @@ function DefaultNavigation({
     /* @__PURE__ */ jsx(Button, { type: "submit", size: "lg", loading: busy, className: "motion-reduce:[&_.animate-spin]:animate-none", children: label })
   ] });
 }
-function DefaultEnding({ title, description, className }) {
+function DefaultEnding({ title, description, actions, className }) {
   const { presentation } = useFormPresentation();
+  const actionRow = actions ? /* @__PURE__ */ jsx("div", { className: "mt-4 flex flex-wrap justify-center gap-2", children: actions }) : null;
   if (presentation === "page") {
     return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col items-center gap-4 text-center", className), children: [
       /* @__PURE__ */ jsx(
@@ -1923,12 +2166,14 @@ function DefaultEnding({ title, description, className }) {
           children: title
         }
       ),
-      description ? /* @__PURE__ */ jsx("p", { className: "max-w-md text-lg text-muted-foreground text-pretty", children: description }) : null
+      description ? /* @__PURE__ */ jsx("p", { className: "max-w-md text-lg text-muted-foreground text-pretty", children: description }) : null,
+      actionRow
     ] });
   }
   return /* @__PURE__ */ jsxs("div", { className: cn("space-y-2 py-8 text-center", className), children: [
     /* @__PURE__ */ jsx("h2", { tabIndex: -1, "data-gf-focus": "", className: cn("rounded-sm text-2xl font-semibold", focusRing), children: title }),
-    description ? /* @__PURE__ */ jsx("p", { className: "text-muted-foreground", children: description }) : null
+    description ? /* @__PURE__ */ jsx("p", { className: "text-muted-foreground", children: description }) : null,
+    actionRow
   ] });
 }
 function focusErrorTarget(event) {
@@ -1980,7 +2225,12 @@ function Form(props) {
   return props.engine ? /* @__PURE__ */ jsx(FormWithEngine, { ...props, engine: props.engine }) : /* @__PURE__ */ jsx(OwnedForm, { ...props });
 }
 function OwnedForm(props) {
-  const engine = useForm(props.form, props.hostOptions ? { ...props.options, hostOptions: props.hostOptions } : props.options);
+  const options = props.hostOptions || props.linkParams ? {
+    ...props.options,
+    ...props.hostOptions ? { hostOptions: props.hostOptions } : {},
+    ...props.linkParams ? { linkParams: props.linkParams } : {}
+  } : props.options;
+  const engine = useForm(props.form, options);
   return /* @__PURE__ */ jsx(FormWithEngine, { ...props, engine });
 }
 function FormWithEngine(props) {
@@ -2022,7 +2272,7 @@ function FormBody({
   const layout = layoutProp ?? def.layout?.mode ?? "classic";
   const status = useFormSelector(engine, (s) => s.status);
   const current = useFormSelector(engine, (s) => s.current);
-  const pathKey = useFormSelector(engine, (s) => JSON.stringify(s.path));
+  const pathKey = useFormSelector(engine, (s) => JSON.stringify(respondentPath(def, s)));
   const errorsKey = useFormSelector(engine, (s) => JSON.stringify(s.errors));
   const ending = useFormSelector(engine, (s) => s.ending);
   const historyLength = useFormSelector(engine, (s) => s.history.length);
@@ -2152,7 +2402,10 @@ function FormBody({
       sending.current = false;
     }
   };
-  const isLastStep = (state) => state.current === state.path[state.path.length - 1];
+  const isLastStep = (state) => {
+    const shown = respondentPath(def, state);
+    return state.current === shown[shown.length - 1];
+  };
   const advance = () => {
     if (waitingForUploads()) return;
     direction.current = "forward";
@@ -2405,6 +2658,37 @@ function FormBody({
 }
 var classicSection = "rounded-xl border bg-card px-5 py-6 text-card-foreground sm:px-8 has-[[aria-invalid=true]]:border-destructive";
 
-export { CLASSIC_PROGRESS_DELAY_MS, FieldChrome, Form, MediaTimeContext, PROGRESS_DELAY_MS, SourceTextContext, UPLOAD_WAIT_MESSAGE, UploadContext, builtInRenderers, defaultRegistry, describedBy, photoAccept, photoFileProblem, photoFileType, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText, useUpload };
+// src/clean-url.ts
+var KEY_PREFIX = "form-query:";
+var HIDDEN_QUERY_KEEP_MS = 30 * 60 * 1e3;
+function hideQueryOnLoad(win, isReload, now = Date.now()) {
+  const { pathname, search, hash } = win.location;
+  const key = KEY_PREFIX + pathname;
+  try {
+    if (search && search !== "?") {
+      win.sessionStorage.setItem(key, JSON.stringify({ search, at: now }));
+      const replace = nativeReplaceState(win.history);
+      replace.call(win.history, win.history.state, "", pathname + hash);
+      return "hidden";
+    }
+    const saved = win.sessionStorage.getItem(key);
+    if (!saved) return "none";
+    const { search: kept, at } = JSON.parse(saved);
+    if (isReload && typeof kept === "string" && typeof at === "number" && now - at < HIDDEN_QUERY_KEEP_MS) {
+      win.location.replace(pathname + kept + hash);
+      return "restoring";
+    }
+    win.sessionStorage.removeItem(key);
+  } catch {
+  }
+  return "none";
+}
+function nativeReplaceState(history) {
+  const proto = Object.getPrototypeOf(history);
+  return typeof proto?.replaceState === "function" ? proto.replaceState : history.replaceState;
+}
+var wasReload = () => typeof performance !== "undefined" && performance.getEntriesByType?.("navigation")[0]?.type === "reload";
+
+export { CLASSIC_PROGRESS_DELAY_MS, DefaultEnding, FieldChrome, Form, HIDDEN_QUERY_KEEP_MS, MediaTimeContext, PROGRESS_DELAY_MS, SourceTextContext, UPLOAD_WAIT_MESSAGE, UploadContext, builtInRenderers, defaultRegistry, describedBy, hideQueryOnLoad, photoAccept, photoFileProblem, photoFileType, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText, useUpload, wasReload };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map