@marktiderman/genesis-forms-web 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,19 +1,21 @@
 "use client";
-import { createContext, useState, useEffect, useRef, useId, useContext, useLayoutEffect } from 'react';
+import { createContext, useState, useEffect, useRef, useId, useContext, useMemo, useLayoutEffect } from 'react';
 import { Button } from '@marktiderman/genesis-ui/button';
 import { Progress } from '@marktiderman/genesis-ui/progress';
 import { cn } from '@marktiderman/genesis-ui/utils';
-import { createRendererRegistry, useForm, FormRuntime, useFormContext, useFormSelector, 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';
 import { RadioGroup, RadioGroupItem } from '@marktiderman/genesis-ui/radio-group';
 import { Textarea } from '@marktiderman/genesis-ui/textarea';
-import { ratingDisplay, choiceOptions, numberLimits, dateLimits, listLimits, tableColumns, tableLimits, parseTimestamp, formatTimestamp, formatCalculated, getFieldType, scaleLabels } from '@marktiderman/genesis-forms';
-import { FormDescription, FormError, FormLabel } from '@marktiderman/genesis-ui/form-field';
+import { FormError, FormDescription, FormLabel } from '@marktiderman/genesis-ui/form-field';
 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" });
@@ -772,6 +774,358 @@ var structuredRenderers = [
   { type: "media-notes", Component: MediaNotesField },
   { type: "text-highlights", Component: TextHighlightsField }
 ];
+var UploadContext = createContext(null);
+function useUpload() {
+  return useContext(UploadContext);
+}
+var PendingUploadsContext = createContext(null);
+function createPendingUploads() {
+  let n = 0;
+  return {
+    start() {
+      n++;
+      let done = false;
+      return () => {
+        if (done) return;
+        done = true;
+        n--;
+      };
+    },
+    count: () => n
+  };
+}
+var UPLOAD_WAIT_MESSAGE = "Wait for the photo to finish uploading.";
+function CameraIcon() {
+  return /* @__PURE__ */ jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
+    /* @__PURE__ */ jsx("path", { d: "M14.5 4h-5L7 7H4a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-3l-2.5-3z" }),
+    /* @__PURE__ */ jsx("circle", { cx: "12", cy: "13", r: "3" })
+  ] });
+}
+function ImageIcon({ className }) {
+  return /* @__PURE__ */ jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", className, children: [
+    /* @__PURE__ */ jsx("rect", { x: "3", y: "3", width: "18", height: "18", rx: "2" }),
+    /* @__PURE__ */ jsx("circle", { cx: "9", cy: "9", r: "2" }),
+    /* @__PURE__ */ jsx("path", { d: "m21 15-3.1-3.1a2 2 0 0 0-2.8 0L6 21" })
+  ] });
+}
+function XIcon2() {
+  return /* @__PURE__ */ jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { d: "M18 6 6 18M6 6l12 12" }) });
+}
+var HEIC_NAME = /\.hei[cf]$/i;
+function photoFileType(file) {
+  const type = file.type.toLowerCase();
+  if (type) return type;
+  return HEIC_NAME.test(file.name) ? file.name.toLowerCase().endsWith(".heif") ? "image/heif" : "image/heic" : "";
+}
+function photoFileProblem(field, file) {
+  const limits = photoLimits(field);
+  if (!limits.mimeTypes.includes(photoFileType(file))) return photoTypeMessage(field);
+  if (file.size <= 0 || file.size > limits.maxBytes) return photoSizeMessage(field);
+  return null;
+}
+function photoAccept(field) {
+  const limits = photoLimits(field);
+  return [...limits.mimeTypes, ...limits.formats.includes("heic") ? [".heic", ".heif"] : []].join(",");
+}
+function Tile({ name, preview, busy }) {
+  const [failed, setFailed] = useState(false);
+  return /* @__PURE__ */ jsxs("div", { className: "relative size-24 overflow-hidden rounded-md border bg-muted sm:size-28", children: [
+    preview && !failed ? /* @__PURE__ */ jsx("img", { src: preview, alt: name, className: cn("size-full object-cover", busy && "opacity-60"), onError: () => setFailed(true) }) : /* @__PURE__ */ jsxs("div", { className: "flex size-full flex-col items-center justify-center gap-1 p-2 text-center text-xs text-muted-foreground", children: [
+      /* @__PURE__ */ jsx(ImageIcon, { className: "size-6" }),
+      /* @__PURE__ */ jsx("span", { className: "line-clamp-2 break-all", children: name })
+    ] }),
+    busy ? /* @__PURE__ */ jsx("div", { className: "absolute inset-0 flex items-center justify-center", children: /* @__PURE__ */ jsx(Spinner, { size: "sm", "aria-hidden": "true" }) }) : null
+  ] });
+}
+var nextKey = 0;
+function PhotoField(props) {
+  const { binding, inputId, engine } = props;
+  const { field } = binding;
+  const host = useUpload();
+  const pending = useContext(PendingUploadsContext);
+  const locked = useFormSelector(engine, (s) => s.status === "completed");
+  const limits = photoLimits(field);
+  const refs = photoRefs(binding.value);
+  const [uploading, setUploading] = useState([]);
+  const [problem, setProblem] = useState(null);
+  const [coarse, setCoarse] = useState(false);
+  const previews = useRef(/* @__PURE__ */ new Map());
+  const releases = useRef(/* @__PURE__ */ new Set());
+  const mounted = useRef(true);
+  const chooseRef = useRef(null);
+  const takeRef = useRef(null);
+  useEffect(() => {
+    setCoarse(typeof window !== "undefined" && !!window.matchMedia?.("(pointer: coarse)").matches);
+  }, []);
+  useEffect(() => {
+    const urls = previews.current;
+    const pendingReleases = releases.current;
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      for (const url of urls.values()) URL.revokeObjectURL(url);
+      urls.clear();
+      for (const release of pendingReleases) release();
+      pendingReleases.clear();
+    };
+  }, []);
+  const currentRefs = () => photoRefs(engine.getState().values[field.id]);
+  const full = refs.length + uploading.length >= limits.maxFiles;
+  const disabled = !host || locked;
+  const add = (files) => {
+    if (!host) return;
+    setProblem(null);
+    let room = limits.maxFiles - currentRefs().length - uploading.length;
+    for (const file of files) {
+      if (room <= 0) {
+        setProblem(photoCountMessage(field));
+        break;
+      }
+      const why = photoFileProblem(field, file);
+      if (why) {
+        setProblem(why);
+        continue;
+      }
+      room--;
+      const key = `u${nextKey++}`;
+      const preview = typeof URL.createObjectURL === "function" ? URL.createObjectURL(file) : null;
+      setUploading((list) => [...list, { key, name: file.name, preview }]);
+      const release = pending?.start() ?? (() => {
+      });
+      releases.current.add(release);
+      const finish = () => {
+        release();
+        releases.current.delete(release);
+        setUploading((list) => list.filter((u) => u.key !== key));
+      };
+      Promise.resolve().then(() => host.upload(file, field)).then((ref) => {
+        if (!isPhotoRef(ref)) throw new Error("The upload returned no photo reference.");
+        if (preview) {
+          const old = previews.current.get(ref.id);
+          if (old && old !== preview) URL.revokeObjectURL(old);
+          if (mounted.current) previews.current.set(ref.id, preview);
+          else URL.revokeObjectURL(preview);
+        }
+        const next = [...currentRefs().filter((r) => r.id !== ref.id), { id: ref.id, name: ref.name, type: ref.type, size: ref.size }];
+        binding.setValue(next);
+        finish();
+      }).catch(() => {
+        if (preview) URL.revokeObjectURL(preview);
+        setProblem(`\u201C${file.name}\u201D didn't upload. Try again.`);
+        finish();
+      });
+    }
+  };
+  const onPick = (e) => {
+    const files = Array.from(e.target.files ?? []);
+    e.target.value = "";
+    add(files);
+  };
+  const remove = (ref) => {
+    const url = previews.current.get(ref.id);
+    if (url) URL.revokeObjectURL(url);
+    previews.current.delete(ref.id);
+    const next = currentRefs().filter((r) => r.id !== ref.id);
+    binding.setValue(next.length ? next : void 0);
+    setProblem(null);
+  };
+  const accept = photoAccept(field);
+  const errorId = `${inputId}-upload-error`;
+  const hasAny = refs.length > 0 || uploading.length > 0;
+  return /* @__PURE__ */ jsx(FieldChrome, { props, children: /* @__PURE__ */ jsxs("div", { className: "space-y-3", children: [
+    hasAny ? /* @__PURE__ */ jsxs("ul", { className: "flex flex-wrap gap-3", "aria-label": "Photos", children: [
+      refs.map((ref) => /* @__PURE__ */ jsxs("li", { className: "relative", children: [
+        /* @__PURE__ */ jsx(Tile, { name: ref.name, preview: previews.current.get(ref.id) ?? null }),
+        locked ? null : /* @__PURE__ */ jsx(
+          Button,
+          {
+            type: "button",
+            variant: "secondary",
+            size: "icon",
+            "aria-label": `Remove ${ref.name}`,
+            onClick: () => remove(ref),
+            className: "absolute right-1 top-1 size-7 rounded-full shadow-sm",
+            children: /* @__PURE__ */ jsx(XIcon2, {})
+          }
+        )
+      ] }, ref.id)),
+      uploading.map((u) => /* @__PURE__ */ jsx("li", { "aria-label": `Uploading ${u.name}`, children: /* @__PURE__ */ jsx(Tile, { name: u.name, preview: u.preview, busy: true }) }, u.key))
+    ] }) : null,
+    /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap gap-2", children: [
+      /* @__PURE__ */ jsxs(
+        Button,
+        {
+          type: "button",
+          variant: "outline",
+          disabled: disabled || full,
+          "aria-invalid": binding.error ? true : void 0,
+          onClick: () => chooseRef.current?.click(),
+          children: [
+            /* @__PURE__ */ jsx(ImageIcon, {}),
+            " ",
+            refs.length ? "Add another photo" : "Choose a photo"
+          ]
+        }
+      ),
+      coarse ? /* @__PURE__ */ jsxs(Button, { type: "button", variant: "outline", disabled: disabled || full, onClick: () => takeRef.current?.click(), children: [
+        /* @__PURE__ */ jsx(CameraIcon, {}),
+        " Take a photo"
+      ] }) : null
+    ] }),
+    /* @__PURE__ */ jsx(
+      Input,
+      {
+        ref: chooseRef,
+        type: "file",
+        accept,
+        multiple: limits.maxFiles > 1,
+        className: "hidden",
+        tabIndex: -1,
+        "aria-hidden": "true",
+        disabled,
+        onChange: onPick
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      Input,
+      {
+        ref: takeRef,
+        type: "file",
+        accept,
+        capture: "environment",
+        className: "hidden",
+        tabIndex: -1,
+        "aria-hidden": "true",
+        disabled,
+        onChange: onPick
+      }
+    ),
+    !host ? /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", children: "Photos can't be added here." }) : /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", children: `Up to ${limits.maxFiles} ${limits.maxFiles === 1 ? "photo" : "photos"}, ${limits.maxSizeMb} MB each.` }),
+    problem ? /* @__PURE__ */ jsx(FormError, { id: errorId, role: "alert", children: problem }) : null
+  ] }) });
+}
+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`,
@@ -1035,6 +1389,7 @@ function useChoiceLook(inputId, count) {
     control: pageFocus ? pageChoiceKey : void 0,
     onKeyDown: pageFocus ? (e) => {
       if (e.altKey || e.ctrlKey || e.metaKey || e.key.length !== 1) return;
+      if (e.target.tagName === "INPUT") return;
       const index = KEYS.indexOf(e.key.toUpperCase());
       if (index < 0 || index >= count) return;
       const option = document.getElementById(`${inputId}-${index}`);
@@ -1045,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",
@@ -1056,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",
       {
@@ -1073,44 +1440,223 @@ function ChoiceContent({ look, index, label }) {
     )
   ] });
 }
+var OTHER_VALUE = "\0other";
+function OtherText({
+  id,
+  label,
+  value,
+  onChange,
+  invalid: invalid2
+}) {
+  const line = useLineClass();
+  return /* @__PURE__ */ jsx(
+    Input,
+    {
+      id,
+      value,
+      maxLength: OTHER_MAX_LENGTH,
+      "aria-label": `${label}: your answer`,
+      "aria-invalid": invalid2 || void 0,
+      placeholder: "Type your answer",
+      onChange: (e) => onChange(e.target.value),
+      className: cn("mt-2", line)
+    }
+  );
+}
+var focusSoon = (id) => requestAnimationFrame(() => document.getElementById(id)?.focus());
+function useOtherText(typed) {
+  const [on, setOn] = useState(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 look = useChoiceLook(inputId, options.length);
-  return /* @__PURE__ */ jsx(FieldChrome, { props, children: /* @__PURE__ */ jsx(
-    RadioGroup,
-    {
-      ...groupAria(props),
-      ...pick.rootProps,
-      onKeyDown: look.onKeyDown,
-      className: look.pageFocus ? "gap-2.5" : void 0,
-      value: typeof binding.value === "string" ? binding.value : "",
-      onValueChange: (v) => binding.setValue(v),
-      children: options.map((o, i) => /* @__PURE__ */ jsxs(Label, { htmlFor: `${inputId}-${i}`, className: look.row, children: [
-        /* @__PURE__ */ jsx(
-          RadioGroupItem,
-          {
-            id: `${inputId}-${i}`,
-            value: o.value,
-            onClick: pick.onItemClick,
-            className: look.control
-          }
-        ),
-        /* @__PURE__ */ jsx(ChoiceContent, { look, index: i, label: o.label ?? o.value })
-      ] }, o.value))
+  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 look = useChoiceLook(inputId, options.length + (other ? 1 : 0));
+  const textId = `${inputId}-other-text`;
+  const choose = (v) => {
+    if (v !== OTHER_VALUE) {
+      otherText.setOn(false);
+      binding.setValue(v);
+      return;
     }
-  ) });
+    otherText.setOn(true);
+    binding.setValue(otherText.text.trim() ? otherText.text : void 0);
+    focusSoon(textId);
+  };
+  return /* @__PURE__ */ jsxs(FieldChrome, { props, children: [
+    /* @__PURE__ */ jsxs(
+      RadioGroup,
+      {
+        ...groupAria(props),
+        ...pick.rootProps,
+        onKeyDown: look.onKeyDown,
+        className: look.pageFocus ? "gap-2.5" : void 0,
+        value: otherText.on ? OTHER_VALUE : current,
+        onValueChange: choose,
+        children: [
+          options.map((o, i) => /* @__PURE__ */ jsxs(Label, { htmlFor: `${inputId}-${i}`, className: look.row, children: [
+            /* @__PURE__ */ jsx(
+              RadioGroupItem,
+              {
+                id: `${inputId}-${i}`,
+                value: o.value,
+                onClick: pick.onItemClick,
+                className: look.control
+              }
+            ),
+            /* @__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.
+            /* @__PURE__ */ jsxs(Label, { htmlFor: `${inputId}-${options.length}`, className: look.row, children: [
+              /* @__PURE__ */ jsx(RadioGroupItem, { id: `${inputId}-${options.length}`, value: OTHER_VALUE, className: look.control }),
+              /* @__PURE__ */ jsx(ChoiceContent, { look, index: options.length, label: other.label })
+            ] })
+          ) : null
+        ]
+      }
+    ),
+    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 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 look = useChoiceLook(inputId, options.length);
-  const toggle = (value, on) => {
-    const next = on ? [...selected, value] : selected.filter((v) => v !== value);
+  const options = useChoiceOptions(props.engine, binding.field.id);
+  const other = otherOption(binding.field);
+  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));
+  const textId = `${inputId}-other-text`;
+  const commit = (picked, otherOn, text) => {
+    const next = otherOn && text.trim() ? [...picked, text] : picked;
     binding.setValue(next.length ? next : void 0);
   };
+  const toggle = (value, on) => commit(on ? [...chosen, value] : chosen.filter((v) => v !== value), otherText.on, otherText.text);
   return /* @__PURE__ */ jsx(FieldChrome, { props, children: /* @__PURE__ */ jsxs("div", { className: cn("grid gap-2", look.pageFocus && "gap-2.5"), onKeyDown: look.onKeyDown, children: [
     look.pageFocus ? /* @__PURE__ */ jsx("p", { className: "-mt-2 mb-1 text-sm text-muted-foreground", children: "Choose as many as you like" }) : null,
     options.map((o, i) => /* @__PURE__ */ jsxs(Label, { htmlFor: `${inputId}-${i}`, className: look.row, children: [
@@ -1124,8 +1670,38 @@ function MultiChoiceField(props) {
           className: look.control
         }
       ),
-      /* @__PURE__ */ jsx(ChoiceContent, { look, index: i, label: o.label ?? o.value })
-    ] }, 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(
+        Checkbox,
+        {
+          id: `${inputId}-${options.length}`,
+          checked: otherText.on,
+          "aria-invalid": binding.error ? true : void 0,
+          onCheckedChange: (c) => {
+            otherText.setOn(c === true);
+            commit(chosen, c === true, otherText.text);
+            if (c === true) focusSoon(textId);
+          },
+          className: look.control
+        }
+      ),
+      /* @__PURE__ */ jsx(ChoiceContent, { look, index: options.length, label: other.label })
+    ] }) : null,
+    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 useLineClass() {
@@ -1145,27 +1721,58 @@ 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 value = typeof binding.value === "string" ? binding.value : "";
-  return /* @__PURE__ */ jsx(FieldChrome, { props, children: /* @__PURE__ */ jsxs(
-    "select",
-    {
-      ...controlAria(props),
-      value,
-      onChange: (e) => binding.setValue(e.target.value === "" ? void 0 : e.target.value),
-      className: cn(
-        "flex h-10 w-full min-w-0 rounded-md border border-input bg-background px-3 py-2 text-base ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm aria-invalid:border-destructive",
-        value === "" && "text-muted-foreground",
-        line
-      ),
-      children: [
-        /* @__PURE__ */ jsx("option", { value: "", children: binding.field.placeholder ?? "Choose\u2026" }),
-        options.map((o) => /* @__PURE__ */ jsx("option", { value: o.value, children: o.label ?? o.value }, o.value))
-      ]
-    }
-  ) });
+  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 value = otherText.on ? OTHER_VALUE : current;
+  const textId = `${props.inputId}-other-text`;
+  return /* @__PURE__ */ jsxs(FieldChrome, { props, children: [
+    /* @__PURE__ */ jsxs(
+      "select",
+      {
+        ...controlAria(props),
+        value,
+        onChange: (e) => {
+          const v = e.target.value;
+          otherText.setOn(v === OTHER_VALUE);
+          if (v === OTHER_VALUE) {
+            binding.setValue(otherText.text.trim() ? otherText.text : void 0);
+            focusSoon(textId);
+          } else binding.setValue(v === "" ? void 0 : v);
+        },
+        className: cn(
+          "flex h-10 w-full min-w-0 rounded-md border border-input bg-background px-3 py-2 text-base ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm aria-invalid:border-destructive",
+          value === "" && "text-muted-foreground",
+          line
+        ),
+        children: [
+          /* @__PURE__ */ jsx("option", { value: "", children: binding.field.placeholder ?? "Choose\u2026" }),
+          options.map((o) => /* @__PURE__ */ jsx("option", { value: o.value, children: o.label ?? o.value }, o.value)),
+          other ? /* @__PURE__ */ jsx("option", { value: OTHER_VALUE, children: other.label }) : null
+        ]
+      }
+    ),
+    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 NumberField(props) {
   const { binding } = props;
@@ -1254,7 +1861,8 @@ var builtInRenderers = [
   { type: "date", Component: DateField },
   { type: "consent", Component: ConsentField },
   ...structuredRenderers,
-  ...calculatedRenderers
+  ...calculatedRenderers,
+  ...photoRenderers
 ];
 var defaultRegistry = createRendererRegistry(builtInRenderers);
 
@@ -1533,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(
@@ -1557,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) {
@@ -1598,6 +2209,8 @@ function DefaultErrorSummary({ count, errors, className }) {
   );
 }
 var ADVANCE_DELAY_MS = 250;
+var PROGRESS_DELAY_MS = 400;
+var CLASSIC_PROGRESS_DELAY_MS = 1500;
 var engineKeys = /* @__PURE__ */ new WeakMap();
 var nextEngineKey = 0;
 function keyOf(engine) {
@@ -1612,11 +2225,20 @@ 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.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) {
-  return /* @__PURE__ */ jsx(FormRuntime, { engine: props.engine, registry: props.registry ?? defaultRegistry, children: /* @__PURE__ */ jsx(FormBody, { ...props }, keyOf(props.engine)) });
+  const { onUpload } = props;
+  const outer = useContext(UploadContext);
+  const host = useMemo(() => onUpload ? { upload: onUpload } : outer, [onUpload, outer]);
+  const [pending] = useState(createPendingUploads);
+  return /* @__PURE__ */ jsx(UploadContext.Provider, { value: host, children: /* @__PURE__ */ jsx(PendingUploadsContext.Provider, { value: pending, children: /* @__PURE__ */ jsx(FormRuntime, { engine: props.engine, registry: props.registry ?? defaultRegistry, children: /* @__PURE__ */ jsx(FormBody, { ...props, pendingUploads: pending }, keyOf(props.engine)) }) }) });
 }
 function focusWithin(root) {
   if (!root) return;
@@ -1632,6 +2254,8 @@ function FormBody({
   theme,
   onSubmit,
   onChange,
+  onProgress,
+  progressNotice = "Your answers save as you go.",
   autoAdvance = true,
   submitLabel = "Send",
   requiredLabel = "Required",
@@ -1640,14 +2264,15 @@ function FormBody({
   slots,
   slotProps,
   className,
-  testID
+  testID,
+  pendingUploads
 }) {
   const { idPrefix } = useFormContext();
   const def = engine.definition;
   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);
@@ -1675,6 +2300,52 @@ function FormBody({
     if (!onChange) return;
     return engine.subscribe(() => onChange(engine.getState(), engine));
   }, [engine, onChange]);
+  const saveProgress = def.settings?.saveProgress === true && !!onProgress;
+  const onProgressRef = useRef(onProgress);
+  onProgressRef.current = onProgress;
+  useEffect(() => {
+    if (!saveProgress) return;
+    let timer;
+    let last = engine.getState();
+    const fire = () => {
+      timer = void 0;
+      if (engine.getState().status === "completed") return;
+      try {
+        void Promise.resolve(onProgressRef.current?.(engine, formProgress(engine))).catch(() => {
+        });
+      } catch {
+      }
+    };
+    const schedule = (delay) => {
+      clearTimeout(timer);
+      timer = setTimeout(fire, delay);
+    };
+    const unsubscribe = engine.subscribe(() => {
+      const state = engine.getState();
+      const previous = last;
+      last = state;
+      if (state.status === "completed") {
+        clearTimeout(timer);
+        timer = void 0;
+        return;
+      }
+      const event = state.events[state.events.length - 1];
+      if (layout === "focus") {
+        if (event?.type === "next" && state.current !== previous.current) schedule(PROGRESS_DELAY_MS);
+      } else if (event?.type === "answer") schedule(CLASSIC_PROGRESS_DELAY_MS);
+    });
+    const flush = () => {
+      if (timer === void 0) return;
+      clearTimeout(timer);
+      fire();
+    };
+    window.addEventListener("pagehide", flush);
+    return () => {
+      unsubscribe();
+      window.removeEventListener("pagehide", flush);
+      flush();
+    };
+  }, [engine, saveProgress, layout]);
   useLayoutEffect(() => {
     if (previousCurrent.current === current) return;
     previousCurrent.current = current;
@@ -1703,8 +2374,14 @@ function FormBody({
     const message = state.current ? state.errors[state.current] : void 0;
     if (message) announce(message);
   };
+  const waitingForUploads = () => {
+    if (pendingUploads.count() === 0) return false;
+    announce(UPLOAD_WAIT_MESSAGE);
+    return true;
+  };
   const finish = async () => {
     if (sending.current) return;
+    if (engine.getState().status !== "completed" && waitingForUploads()) return;
     if (engine.getState().status !== "completed" && !engine.submit()) {
       if (layout === "classic") setSummaryRequest((n) => n + 1);
       else announceStepError();
@@ -1725,8 +2402,12 @@ 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";
     if (isLastStep(engine.getState())) void finish();
     else if (!engine.next()) announceStepError();
@@ -1811,6 +2492,7 @@ function FormBody({
   }
   const pageFocus = page && layout === "focus";
   const pageClassic = page && layout === "classic";
+  const notice = saveProgress && progressNotice && historyLength === 0 ? /* @__PURE__ */ jsx("p", { className: "text-sm text-muted-foreground", "data-gf-progress-notice": "", children: progressNotice }) : null;
   const renderBlock = (id, focus) => {
     const block = engine.block(id);
     if (!block || block.kind === "page-break") return null;
@@ -1940,6 +2622,7 @@ function FormBody({
           /* @__PURE__ */ jsx("div", { className: "flex flex-1 flex-col justify-center px-4 pb-20 pt-4 sm:px-6 sm:pb-28", children: /* @__PURE__ */ jsxs("div", { className: "mx-auto w-full max-w-xl", children: [
             /* @__PURE__ */ jsx("div", { className: historyLength === 0 ? "mb-5" : "sr-only", children: header }),
             fields,
+            notice ? /* @__PURE__ */ jsx("div", { className: "mt-4", children: notice }) : null,
             failure ? /* @__PURE__ */ jsx("div", { className: "mt-6", children: failure }) : null,
             /* @__PURE__ */ jsx("div", { className: "mt-10", children: navigation })
           ] }) })
@@ -1953,6 +2636,7 @@ function FormBody({
         children: /* @__PURE__ */ jsxs("div", { className: "mx-auto w-full max-w-2xl space-y-4", children: [
           brandNode ? /* @__PURE__ */ jsx("div", { className: "flex justify-center pb-2", children: brandNode }) : null,
           header,
+          notice,
           errorSummary,
           fields,
           failure,
@@ -1962,9 +2646,11 @@ function FormBody({
     ) : /* @__PURE__ */ jsxs("form", { ...formProps, className: cn("mx-auto w-full max-w-xl space-y-8", className), children: [
       brandNode,
       header,
+      layout === "classic" ? notice : null,
       errorSummary,
       progress,
       fields,
+      layout === "focus" ? notice : null,
       failure,
       navigation
     ] })
@@ -1972,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 { FieldChrome, Form, MediaTimeContext, SourceTextContext, builtInRenderers, defaultRegistry, describedBy, themeColors, themeCss, useFormPresentation, useMediaTime, useSourceText };
+// 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