@evinvest/kitstart 0.13.0 → 0.15.0

package/dist/react/LeadCaptureTiles.d.ts

@@ -0,0 +1,53 @@
+import { type ReactNode } from "react";
+/** One answer as a tile: its words, and what a brand or the price adds to them. */
+export interface TileOption {
+    value: string;
+    label: string;
+    /** Drawn instead of `label` on a phone (under `sm`); the radio is still named by the whole `label`. */
+    shortLabel?: string | undefined;
+    /** Two columns of the grid (an "I don't know" under a row of answers). */
+    span?: 2 | undefined;
+    /** More classes for this tile alone, after the group's. */
+    className?: string | undefined;
+    /** Above the label, the brand's (a need's icon). */
+    icon?: ReactNode;
+    /** A short tag beside the label ("Le plus choisi"). */
+    badge?: string | undefined;
+    /** At the end of the tile: what this answer would cost. */
+    aside?: string | null | undefined;
+}
+export interface TileGroupProps {
+    name: string;
+    legend: string;
+    options: readonly TileOption[];
+    value: string | undefined;
+    required: boolean;
+    /** Blocks the submit while nothing is chosen, in the page's words; none → the browser's own. */
+    requiredText?: string | undefined;
+    /** `data-lead-field` on each radio: the role events and the focus read. */
+    field: string;
+    /** A bare attribute on each radio, for a selector of the caller's (`data-need-option`). */
+    marker?: string | undefined;
+    /** Enter on a tile answers it, instead of submitting a form half filled. Off: Enter is the form's. */
+    enterPicks: boolean;
+    /** The visitor's answer — a tap, Enter or Space — with the radio it came from. */
+    onPick: (value: string, radio: HTMLInputElement) => void;
+    /** An arrow key moved the choice: chosen, but the visitor is still choosing. */
+    onSelect: (value: string) => void;
+    classNames: {
+        field?: string | undefined;
+        legend?: string | undefined;
+        grid?: string | undefined;
+        tile?: string | undefined;
+        icon?: string | undefined;
+        badge?: string | undefined;
+        aside?: string | undefined;
+    };
+}
+/**
+ * A question answered by a tap: touch-sized native radios, so the answer
+ * posts without a script, over a tile the brand dresses. A radio group
+ * answers arrows with a click (`detail` 0) and a change, the same events a
+ * tap makes: what moves on is told apart by its key or pointer.
+ */
+export declare function TileGroup(props: TileGroupProps): import("react").JSX.Element;

package/dist/react/LeadCaptureTiles.js

@@ -0,0 +1,50 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@evinvest/uikit";
+import { useEffect, useRef } from "react";
+/**
+ * A question answered by a tap: touch-sized native radios, so the answer
+ * posts without a script, over a tile the brand dresses. A radio group
+ * answers arrows with a click (`detail` 0) and a change, the same events a
+ * tap makes: what moves on is told apart by its key or pointer.
+ */
+export function TileGroup(props) {
+    const { name, legend, options, value, required, field, marker, enterPicks, onPick, onSelect, classNames: c } = props;
+    const group = useRef(null);
+    const pointer = useRef(false);
+    const answered = useRef(false);
+    const requiredText = props.requiredText;
+    useEffect(() => {
+        if (requiredText === undefined)
+            return;
+        for (const radio of group.current?.querySelectorAll("input[type=radio]") ?? [])
+            radio.setCustomValidity(value === undefined ? requiredText : "");
+    });
+    const markerProps = marker ? { [marker]: "" } : {};
+    return (_jsxs("fieldset", { ref: group, className: cn("flex flex-col gap-2", c.field), children: [_jsx("legend", { className: cn("mb-2 text-sm font-medium text-ink", c.legend), children: legend }), _jsx("div", { className: c.grid, children: options.map(o => (_jsxs("label", { className: cn("relative block cursor-pointer", o.span === 2 && "col-span-2"), children: [_jsx("input", { type: "radio", name: name, value: o.value, required: required, checked: value === o.value, onPointerDown: () => {
+                                pointer.current = true;
+                            }, onKeyDown: (e) => {
+                                pointer.current = false;
+                                answered.current = false;
+                                if (e.key !== "Enter" || !enterPicks)
+                                    return;
+                                e.preventDefault();
+                                answered.current = true;
+                                onPick(o.value, e.currentTarget);
+                            }, onKeyUp: (e) => {
+                                if (e.key !== " ")
+                                    return;
+                                answered.current = true;
+                                onPick(o.value, e.currentTarget);
+                            }, onClick: (e) => {
+                                if (e.detail === 0 && !pointer.current)
+                                    return;
+                                pointer.current = false;
+                                answered.current = true;
+                                onPick(o.value, e.currentTarget);
+                            }, onChange: () => {
+                                if (!answered.current)
+                                    onSelect(o.value);
+                                answered.current = false;
+                            }, className: "peer absolute inset-0 opacity-0", "data-lead-field": field, "aria-label": o.shortLabel !== undefined ? [o.label, o.badge, o.aside].filter(Boolean).join(", ") : undefined, ...markerProps }), _jsxs("span", { className: cn("flex min-h-11 items-center rounded-[var(--control-radius)] border border-input text-ink transition-colors", "peer-checked:border-primary peer-checked:bg-hover peer-focus-visible:ring-[3px] peer-focus-visible:ring-ring/50", c.tile, o.className), children: [o.icon !== undefined && (_jsx("span", { "aria-hidden": "true", className: cn("flex shrink-0 items-center justify-center [&_svg]:size-6", c.icon), children: o.icon })), o.shortLabel !== undefined ? (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", className: "min-w-0 sm:hidden", children: o.shortLabel }), _jsx("span", { className: "min-w-0 max-sm:hidden", children: o.label })] })) : (_jsx("span", { className: "min-w-0", children: o.label })), o.badge && _jsx("span", { className: cn("rounded-full bg-hover px-2 py-0.5 text-xs font-medium text-ink", c.badge), children: o.badge }), o.aside && _jsx("span", { className: cn("ms-auto shrink-0 font-medium tabular-nums", c.aside), children: o.aside })] })] }, o.value))) })] }));
+}

package/dist/react/QuoteFormShell.d.ts

@@ -1,4 +1,4 @@
-import type { FormEventHandler, ReactNode } from "react";
+import type { FormEventHandler, KeyboardEventHandler, ReactNode } from "react";
 /**
  * The quote form's frame: a plain `<form method="post" action="/quote">`
  * answered with a 303, so it works before any JavaScript arrives — which is
@@ -27,6 +27,10 @@ export interface QuoteFormShellProps {
     className?: string;
     /** A script's own submit (an in-place success); the 303 stays the path without one. */
     onSubmit?: FormEventHandler<HTMLFormElement> | undefined;
+    /** A key in any field — `LeadCapture`'s Enter that moves to the next field. */
+    onKeyDown?: KeyboardEventHandler<HTMLFormElement> | undefined;
+    /** Bare `data-*` attributes on the form, for a stylesheet of the caller's. */
+    data?: Readonly<Record<`data-${string}`, string>> | undefined;
     children: ReactNode;
 }
 /** The mobile field's attributes: the numeric keypad and the phone's autofill. */

package/dist/react/QuoteFormShell.js

@@ -6,6 +6,6 @@ import { CARD_FIELD, SUBMISSION_FIELD } from "../core/lead.js";
 /** The mobile field's attributes: the numeric keypad and the phone's autofill. */
 export const PHONE_INPUT_PROPS = { type: "tel", inputMode: "tel", autoComplete: "tel" };
 export function QuoteFormShell(props) {
-    const { placeSlug, locale, renderedAt, honeypotLabel, formId = "quote", card, action = "/quote", id = "quote", className, onSubmit, children } = props;
-    return (_jsxs("form", { id: id, method: "post", action: action, onSubmit: onSubmit, className: cn("relative flex w-full flex-col gap-5", className), children: [placeSlug && _jsx("input", { type: "hidden", name: LOCATION_FIELD, value: placeSlug }), _jsx("input", { type: "hidden", name: LOCALE_FIELD, value: locale }), _jsx("input", { type: "hidden", name: FORM_ID_FIELD, value: formId }), _jsx("input", { type: "hidden", name: RENDERED_AT_FIELD, value: String(renderedAt) }), card && _jsx("input", { type: "hidden", name: CARD_FIELD, value: card }), _jsx("input", { type: "hidden", name: SUBMISSION_FIELD }), children, _jsx("div", { "aria-hidden": "true", style: { position: "absolute", left: "-10000px", width: 1, height: 1, overflow: "hidden" }, children: _jsxs("label", { children: [honeypotLabel, _jsx("input", { type: "text", name: HONEYPOT_FIELD, tabIndex: -1, autoComplete: "off", defaultValue: "" })] }) })] }));
+    const { placeSlug, locale, renderedAt, honeypotLabel, formId = "quote", card, action = "/quote", id = "quote", className, onSubmit, onKeyDown, children } = props;
+    return (_jsxs("form", { id: id, method: "post", action: action, onSubmit: onSubmit, onKeyDown: onKeyDown, ...props.data, className: cn("relative flex w-full flex-col gap-5", className), children: [placeSlug && _jsx("input", { type: "hidden", name: LOCATION_FIELD, value: placeSlug }), _jsx("input", { type: "hidden", name: LOCALE_FIELD, value: locale }), _jsx("input", { type: "hidden", name: FORM_ID_FIELD, value: formId }), _jsx("input", { type: "hidden", name: RENDERED_AT_FIELD, value: String(renderedAt) }), card && _jsx("input", { type: "hidden", name: CARD_FIELD, value: card }), _jsx("input", { type: "hidden", name: SUBMISSION_FIELD }), children, _jsx("div", { "aria-hidden": "true", style: { position: "absolute", left: "-10000px", width: 1, height: 1, overflow: "hidden" }, children: _jsxs("label", { children: [honeypotLabel, _jsx("input", { type: "text", name: HONEYPOT_FIELD, tabIndex: -1, autoComplete: "off", defaultValue: "" })] }) })] }));
 }

package/dist/react/ab-switcher-types.d.ts

@@ -0,0 +1,39 @@
+/** One variant of an experiment, as the menu offers it. */
+export interface AbSwitcherVariant {
+    /** The value the force parameter carries and the cookie holds: `b`. */
+    value: string;
+    label: string;
+}
+/** One experiment the menu switches. */
+export interface AbSwitcherExperiment {
+    /** The experiment's key: the cookie is `ab_<key>`, the force parameter `<forceParam><key>`. */
+    key: string;
+    label?: string;
+    variants: readonly AbSwitcherVariant[];
+}
+/** The menu's words; English unless the brand says otherwise. */
+export interface AbSwitcherText {
+    /** The chip's and the panel's accessible name. */
+    title: string;
+    reset: string;
+    leave: string;
+    minimize: string;
+    hide: string;
+    /** Shown for an experiment no cookie assigns yet. */
+    unassigned: string;
+}
+/**
+ * Plain data, so a server layout mounts it. Positioned by `className`: a brand
+ * lifts the chip over its own sticky bars.
+ */
+export interface AbSwitcherProps {
+    experiments: readonly AbSwitcherExperiment[];
+    /** The cookie the brand's force parameter sets to mark a test visit: `ab__qa`. */
+    qaCookie: string;
+    /** The assignments, when the caller knows them; otherwise read from `ab_<key>` cookies. */
+    current?: Readonly<Record<string, string>>;
+    /** The prefix of the parameter that forces a variant; `ab_` by default. */
+    forceParam?: string;
+    className?: string;
+    text?: Partial<AbSwitcherText>;
+}

package/dist/react/ab-switcher-types.js

@@ -0,0 +1 @@
+export {};

package/dist/react/focus-next.d.ts

@@ -0,0 +1,11 @@
+/** `LeadSteps`' mark of a screen that is off (`STEP_OFF`), and the attribute. */
+export declare const OFF_SELECTOR = "[data-lead-off], [hidden]";
+/**
+ * The next empty field of `form` after `from` (from the top without one), or
+ * `null`. `hiddenToo`: on a screen not shown yet, too — the next screen's.
+ */
+export declare function nextEmpty(form: HTMLFormElement, from: Element | null, hiddenToo?: boolean): HTMLInputElement | null;
+/** Focuses the next empty field after `from`; `true` when there was one. */
+export declare function focusNext(form: HTMLFormElement | null | undefined, from: Element | null): boolean;
+/** Focuses a step's first empty field, else its first field: what the screen asks. */
+export declare function focusStep(step: Element | null | undefined): void;

package/dist/react/focus-next.js

@@ -0,0 +1,58 @@
+/**
+ * Where the focus goes after an answer: the next field the visitor has not
+ * filled — a radio group with nothing checked takes it at its first radio, a
+ * typed field when empty. Read from the DOM, in document order, so a brand's
+ * extras take their turn too; a field on a screen that is off (another step) is
+ * not there to be filled.
+ */
+const FIELDS = "[data-lead-field]";
+function empty(el, form) {
+    if (el.type === "radio")
+        return !form.querySelector(`input[type=radio][name="${CSS.escape(el.name)}"]:checked`);
+    if (el.type === "checkbox")
+        return !el.checked;
+    return el.value.trim() === "";
+}
+/** `LeadSteps`' mark of a screen that is off (`STEP_OFF`), and the attribute. */
+export const OFF_SELECTOR = "[data-lead-off], [hidden]";
+const shown = (el) => el.closest(OFF_SELECTOR) === null;
+/** The fields of `scope` in document order, a radio group once — at its checked radio, else its first. */
+function fields(scope, hiddenToo = false) {
+    const seen = new Set();
+    const out = [];
+    for (const el of scope.querySelectorAll(FIELDS)) {
+        if (!(el instanceof HTMLInputElement) || el.disabled || el.type === "hidden" || (!hiddenToo && !shown(el)))
+            continue;
+        if (el.type === "radio") {
+            if (seen.has(el.name))
+                continue;
+            seen.add(el.name);
+            out.push(el.form?.querySelector(`input[type=radio][name="${CSS.escape(el.name)}"]:checked`) ?? el);
+            continue;
+        }
+        out.push(el);
+    }
+    return out;
+}
+/**
+ * The next empty field of `form` after `from` (from the top without one), or
+ * `null`. `hiddenToo`: on a screen not shown yet, too — the next screen's.
+ */
+export function nextEmpty(form, from, hiddenToo = false) {
+    const after = (el) => from === null || (from.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
+    return fields(form, hiddenToo).find(el => after(el) && !from?.contains(el) && empty(el, form)) ?? null;
+}
+/** Focuses the next empty field after `from`; `true` when there was one. */
+export function focusNext(form, from) {
+    const next = form ? nextEmpty(form, from) : null;
+    next?.focus();
+    return next !== null;
+}
+/** Focuses a step's first empty field, else its first field: what the screen asks. */
+export function focusStep(step) {
+    const form = step?.closest("form");
+    if (!step || !form)
+        return;
+    const all = fields(step);
+    (all.find(el => empty(el, form)) ?? all[0])?.focus();
+}

package/dist/react/form-select-value.d.ts

@@ -3,9 +3,15 @@ import { type InvalidEvent, type RefObject } from "react";
  * The value `FormSelect` posts, across the swap from the native select and
  * through the form's own life: a reset, and a required check that points at
  * the kit's trigger instead of an input nobody sees.
+ *
+ * `controlled` (a `value` prop) follows React's input idiom: the prop is the
+ * value, a choice reaches the parent only through `onValueChange`, and a reset
+ * leaves it where the parent holds it. The own state still follows the prop,
+ * so a switch back to uncontrolled keeps the last value, as an `<input>` does.
  */
 export declare function useFormSelectValue(opts: {
     initial: string;
+    controlled: string | undefined;
     native: RefObject<HTMLSelectElement | null>;
     box: RefObject<HTMLElement | null>;
     scripted: boolean;

package/dist/react/form-select-value.js

@@ -1,23 +1,45 @@
 "use client";
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
+const DEV = typeof process !== "undefined" && process.env.NODE_ENV !== "production";
 /**
  * The value `FormSelect` posts, across the swap from the native select and
  * through the form's own life: a reset, and a required check that points at
  * the kit's trigger instead of an input nobody sees.
+ *
+ * `controlled` (a `value` prop) follows React's input idiom: the prop is the
+ * value, a choice reaches the parent only through `onValueChange`, and a reset
+ * leaves it where the parent holds it. The own state still follows the prop,
+ * so a switch back to uncontrolled keeps the last value, as an `<input>` does.
  */
 export function useFormSelectValue(opts) {
-    const { initial, native, box, scripted, onValueChange } = opts;
-    const [value, setValue] = useState(initial);
+    const { initial, controlled, native, box, scripted, onValueChange } = opts;
+    const [own, setOwn] = useState(controlled ?? initial);
     const [invalid, setInvalid] = useState(false);
     const [open, setOpen] = useState(false);
-    const initialRef = useRef(initial);
-    initialRef.current = initial;
+    const isControlled = controlled !== undefined;
+    if (isControlled && own !== controlled)
+        setOwn(controlled);
+    const value = isControlled ? controlled : own;
+    useModeWarning(isControlled);
+    // The effects below run once or on a form event: they read the latest props here.
+    const latest = useRef({ initial, isControlled, value, onValueChange });
+    latest.current = { initial, isControlled, value, onValueChange };
     // A choice made in the native select before the script arrived survives the
     // swap: read in the hydration commit, before the scripted render. Once —
-    // later renders never hold the native select.
+    // later renders never hold the native select. Under a `value` it is the
+    // parent's to take, so it is reported instead of kept — and only a real
+    // pick: a `value` no option carries leaves the browser on its own default,
+    // which is no choice of the visitor's.
     useLayoutEffect(() => {
-        if (native.current)
-            setValue(native.current.value);
+        const select = native.current;
+        if (!select)
+            return;
+        const picked = select.value;
+        const { isControlled: held, value: shown, onValueChange: report } = latest.current;
+        if (!held)
+            setOwn(picked);
+        else if (picked !== shown && picked !== untouched(select))
+            report?.(picked);
     }, [native]);
     // A form reset puts a native select back on its default; so does this.
     // Interactive validation — the browser's own, on a submit — is told apart
@@ -27,7 +49,10 @@ export function useFormSelectValue(opts) {
         const form = box.current?.closest("form");
         if (!scripted || !form)
             return;
-        const reset = () => setValue(initialRef.current);
+        const reset = () => {
+            if (!latest.current.isControlled)
+                setOwn(latest.current.initial);
+        };
         // On the document, not the form: a submit button may sit outside it
         // (`form="…"`), and the click may land on an icon inside the button.
         const submit = (e) => {
@@ -48,7 +73,8 @@ export function useFormSelectValue(opts) {
         };
     }, [box, scripted]);
     const choose = (next) => {
-        setValue(next);
+        if (!isControlled)
+            setOwn(next);
         setInvalid(false);
         onValueChange?.(next);
     };
@@ -70,3 +96,22 @@ export function useFormSelectValue(opts) {
     };
     return { value, choose, invalid, open, setOpen, onInvalid };
 }
+/**
+ * What a single select shows before anyone touches it: the option marked
+ * `selected` in the markup, else the first enabled one (HTML's selectedness
+ * setting). A pick of that same option is indistinguishable, and harmless.
+ */
+function untouched(select) {
+    const options = Array.from(select.options);
+    return (options.find(o => o.defaultSelected) ?? options.find(o => !o.disabled))?.value;
+}
+/** React's warning for an `<input>` that changes mode: once, and nothing else changes. */
+function useModeWarning(isControlled) {
+    const first = useRef(isControlled);
+    const warned = useRef(false);
+    if (!DEV || warned.current || first.current === isControlled)
+        return;
+    warned.current = true;
+    console.error(`@evinvest/kitstart: a FormSelect is changing from ${first.current ? "controlled to uncontrolled" : "uncontrolled to controlled"}. ` +
+        "Keep one of `value` and `defaultValue` for its lifetime; `value={undefined}` makes it uncontrolled.");
+}

package/dist/react/index.d.ts

@@ -1,8 +1,11 @@
 /**
  * `@evinvest/kitstart/react` — the structural widgets every landing shares,
  * where behaviour matters more than look. Server components by default; only
- * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture` and `LeadBooking` are client modules, each its own file
- * with its own `"use client"`, so a page pays for what it renders.
+ * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture`, `LeadBooking`
+ * and `AbSwitcher` are client modules, each its own file with its own
+ * `"use client"`, so a page pays for what it renders. `AbSwitcher` is a gate
+ * of a few hundred bytes; its panel (`AbSwitcherPanel`) is a dynamic import,
+ * fetched only by a QA visit.
  *
  * Styled with the kit's token roles only (`text-ink`, `border-border`,
  * `bg-card`…); a brand restyles through `className`, a widget's named parts
@@ -10,6 +13,8 @@
  * must scan the package: `@source "<path to>/node_modules/@evinvest/kitstart/dist";`,
  * relative to the stylesheet (`../../node_modules/…` from `src/app/`).
  */
+export { AbSwitcher } from "./AbSwitcher.js";
+export type { AbSwitcherExperiment, AbSwitcherProps, AbSwitcherText, AbSwitcherVariant } from "./ab-switcher-types.js";
 export { AnalyticsBoundary } from "./AnalyticsBoundary.js";
 export { AreaChips } from "./AreaChips.js";
 export { CallBar, type CallBarPart, type CallBarProps } from "./CallBar.js";
@@ -23,7 +28,10 @@ export type { BookingPart } from "./LeadBookingManual.js";
 export { BOOKING_ADAPTERS, BOOKING_EMBEDS, bookingAdapters, calComAdapter, calComEmbedAdapter, calComEmbedOrigin, googleCalendarAdapter, linkAdapter, manualAdapter, type BookedSlot, type BookingAdapter, type BookingAdapters, type BookingContext, } from "./booking-adapters.js";
 export { BOOKING_ACTION } from "./use-booking.js";
 export type { LeadSent } from "./use-lead-submit.js";
-export type { LeadCaptureLayout } from "./LeadCaptureNeed.js";
+export type { LeadCaptureLayout, LeadNeedDisplay, LeadNeedOption } from "./LeadCaptureNeed.js";
+export type { EstimateQuestion, EstimateQuestions } from "./LeadCaptureEstimate.js";
+export type { LeadIntro, LeadIntroOption } from "./lead-steps.js";
+export type { ChannelIconKey } from "./LeadCaptureChannels.js";
 export { MapFacade, type MapFacadePart, type MapFacadeProps } from "./MapFacade.js";
 export { PlaceDirectory, type PlaceDirectoryPart, type PlaceDirectoryProps } from "./PlaceDirectory.js";
 export { PHONE_INPUT_PROPS, QuoteFormShell, type QuoteFormShellProps } from "./QuoteFormShell.js";

package/dist/react/index.js

@@ -1,8 +1,11 @@
 /**
  * `@evinvest/kitstart/react` — the structural widgets every landing shares,
  * where behaviour matters more than look. Server components by default; only
- * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture` and `LeadBooking` are client modules, each its own file
- * with its own `"use client"`, so a page pays for what it renders.
+ * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture`, `LeadBooking`
+ * and `AbSwitcher` are client modules, each its own file with its own
+ * `"use client"`, so a page pays for what it renders. `AbSwitcher` is a gate
+ * of a few hundred bytes; its panel (`AbSwitcherPanel`) is a dynamic import,
+ * fetched only by a QA visit.
  *
  * Styled with the kit's token roles only (`text-ink`, `border-border`,
  * `bg-card`…); a brand restyles through `className`, a widget's named parts
@@ -10,6 +13,7 @@
  * must scan the package: `@source "<path to>/node_modules/@evinvest/kitstart/dist";`,
  * relative to the stylesheet (`../../node_modules/…` from `src/app/`).
  */
+export { AbSwitcher } from "./AbSwitcher.js";
 export { AnalyticsBoundary } from "./AnalyticsBoundary.js";
 export { AreaChips } from "./AreaChips.js";
 export { CallBar } from "./CallBar.js";

package/dist/react/lead-steps.d.ts

@@ -0,0 +1,53 @@
+import { type ReactNode } from "react";
+import type { LeadStep } from "../core/analytics.js";
+/** One answer to the intro question. */
+export interface LeadIntroOption {
+    /** Posted under the intro's `field`: a slug. */
+    value: string;
+    label: string;
+    /** Drawn on its tile, the brand's own. */
+    icon?: ReactNode;
+    /** `callback`: the rest of the form is the phone and its consent, posted as a callback. `form` (default): the form. */
+    channel?: "form" | "callback" | undefined;
+}
+/**
+ * A question asked before the need (`steps`) — how urgent, who is asking —
+ * whose answer goes with the lead as one of the brand's extras: declare
+ * `field` in `site.lead.extras`, or the server drops it.
+ */
+export interface LeadIntro {
+    label: string;
+    field: string;
+    options: readonly LeadIntroOption[];
+}
+/** A screen of `layout="steps"`, named as `lead_form_step` reports it. */
+export type StepId = Exclude<LeadStep, "contact">;
+/**
+ * The screens, in order: the intro question when there is one; then — unless
+ * its answer asked for a call back, which needs the phone alone — the need,
+ * the estimate's screens asked now (a question each, or a few sharing one,
+ * named by the first), the postcode on its own screen (`localityStep="own"`),
+ * and the phone, always last.
+ */
+export declare function stepsOf(o: {
+    intro: boolean;
+    callback: boolean;
+    estimate: readonly (readonly string[])[];
+    localityOwn: boolean;
+}): StepId[];
+/** The screen a refused field is shown on: its own (an estimate's, the screen it shares), else the last. */
+export declare function stepOfField(steps: readonly StepId[], field: string, estimate?: readonly (readonly string[])[]): StepId | null;
+/**
+ * Which screen is on: the one a refusal points at, else the one the visitor
+ * went back to (`back`, `edit`), else the first not yet answered. An answer
+ * calls `next`, and the first open screen comes back on. Each move is
+ * reported once (`onStep`) — never the first screen, which `lead_form_view`
+ * already counts.
+ */
+export declare function useLeadSteps(steps: readonly StepId[], answered: (id: StepId) => boolean, refused: StepId | null, onStep: (id: StepId) => void): {
+    current: StepId;
+    index: number;
+    back: () => void;
+    edit: (id: StepId) => void;
+    next: () => void;
+};

package/dist/react/lead-steps.js

@@ -0,0 +1,58 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { estimateField } from "../core/pricing/flow.js";
+/**
+ * The screens, in order: the intro question when there is one; then — unless
+ * its answer asked for a call back, which needs the phone alone — the need,
+ * the estimate's screens asked now (a question each, or a few sharing one,
+ * named by the first), the postcode on its own screen (`localityStep="own"`),
+ * and the phone, always last.
+ */
+export function stepsOf(o) {
+    const out = o.intro ? ["intro"] : [];
+    if (o.callback)
+        return [...out, "phone"];
+    out.push("need", ...o.estimate.flatMap(screen => (screen[0] === undefined ? [] : [estimateField(screen[0])])));
+    if (o.localityOwn)
+        out.push("locality");
+    out.push("phone");
+    return out;
+}
+/** The screen a refused field is shown on: its own (an estimate's, the screen it shares), else the last. */
+export function stepOfField(steps, field, estimate = []) {
+    if (steps.length === 0)
+        return null;
+    const shared = estimate.find(screen => screen.some(id => estimateField(id) === field))?.[0];
+    const own = field === "need" || field === "locality" ? field : shared !== undefined ? estimateField(shared) : null;
+    const step = own !== null ? steps.find(s => s === own) : undefined;
+    return step ?? steps[steps.length - 1] ?? null;
+}
+/**
+ * Which screen is on: the one a refusal points at, else the one the visitor
+ * went back to (`back`, `edit`), else the first not yet answered. An answer
+ * calls `next`, and the first open screen comes back on. Each move is
+ * reported once (`onStep`) — never the first screen, which `lead_form_view`
+ * already counts.
+ */
+export function useLeadSteps(steps, answered, refused, onStep) {
+    const [at, setAt] = useState(null);
+    const open = steps.find(s => !answered(s)) ?? steps[steps.length - 1] ?? "phone";
+    const current = refused !== null && steps.includes(refused) ? refused : at !== null && steps.includes(at) ? at : open;
+    const index = steps.indexOf(current);
+    const shown = useRef(current);
+    const report = useRef(onStep);
+    report.current = onStep;
+    useEffect(() => {
+        if (shown.current === current)
+            return;
+        shown.current = current;
+        report.current(current);
+    }, [current]);
+    return {
+        current,
+        index,
+        back: () => setAt(steps[index - 1] ?? null),
+        edit: (id) => setAt(id),
+        next: () => setAt(null),
+    };
+}

package/dist/react/use-lead-context.d.ts

@@ -29,3 +29,9 @@ onPreset: () => void): [string | undefined, (need: string) => void];
  * callback by id, and not every browser opens a closed one it scrolls to.
  */
 export declare function useOpenOnHash(id: string): void;
+/**
+ * The postcode the page already knows: `?postcode=` once the script runs (a
+ * cached page cannot read the query) — the link from an ad or a card that
+ * asked it already. Anything that does not read as a postcode is ignored.
+ */
+export declare function usePostcode(): string | undefined;

package/dist/react/use-lead-context.js

@@ -84,3 +84,19 @@ export function useOpenOnHash(id) {
         return () => window.removeEventListener("hashchange", open);
     }, [id]);
 }
+/** What `?postcode=` may carry into the form: a short postcode, letters for the few countries that use them, never more. */
+const POSTCODE_PARAM = /^[0-9A-Za-z][0-9A-Za-z -]{1,9}$/;
+/**
+ * The postcode the page already knows: `?postcode=` once the script runs (a
+ * cached page cannot read the query) — the link from an ad or a card that
+ * asked it already. Anything that does not read as a postcode is ignored.
+ */
+export function usePostcode() {
+    const [postcode, setPostcode] = useState(undefined);
+    useEffect(() => {
+        const value = new URLSearchParams(window.location.search).get("postcode")?.trim();
+        if (value && POSTCODE_PARAM.test(value))
+            setPostcode(value);
+    }, []);
+    return postcode;
+}

package/dist/react/use-lead-focus.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where the focus goes once the visitor has answered: to the next screen in
+ * `steps`, else — with `focusNext` — to the next empty field.
+ *
+ * `moveOn(change, from, stable)` applies the answer. When it changes no
+ * screen (`stable`) and what comes next is a typed field, that field is
+ * revealed and focused inside the tap: iOS opens the keyboard only for a
+ * focus a gesture made. Otherwise the focus moves once React has drawn the
+ * change. `focusAfterSelect()`: the same after the kit's select, whose list
+ * hands the focus back to its trigger as it closes — so it waits for that.
+ */
+export declare function useLeadFocus(form: () => HTMLFormElement | null, o: {
+    steps: boolean;
+    focusNext: boolean;
+    current: string;
+}): {
+    moveOn(change: () => void, from: Element | null, stable: boolean): void;
+    focusAfterSelect(): void;
+};