@evinvest/kitstart 0.5.0 → 0.6.0

package/dist/react/LeadCapture.js

@@ -0,0 +1,60 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, cn } from "@evinvest/uikit";
+import { useRef, useState } from "react";
+import { resolveChannels } from "../core/channels.js";
+import { fillText, openingText } from "../core/lead-capture-format.js";
+import { servedLocalities } from "../core/place/types.js";
+import { CallbackForm, ChannelLink, ExperimentFields } from "./LeadCaptureChannels.js";
+import { LocalityField, NameField, PhoneField } from "./LeadCaptureFields.js";
+import { NeedField } from "./LeadCaptureNeed.js";
+import { QuoteFormShell } from "./QuoteFormShell.js";
+import { useHydrated, useNeed, useNow, useOpenOnHash } from "./use-lead-context.js";
+import { useLeadEvents } from "./use-lead-events.js";
+/**
+ * The lead form every brand shares: the need (asked once, or not at all when
+ * the page knows it), the postcode, the phone, and the other ways to reach the
+ * business ordered by the place's hours. Over `QuoteFormShell`, so without a
+ * script it is the plain POST to `/quote` it always was.
+ */
+export function LeadCapture(props) {
+    const { place, contact, locale, renderedAt, wire, needs, layout = "single", text, classNames: c } = props;
+    const { formId = "quote", id = "quote", experiment } = props;
+    const root = useRef(null);
+    const hydrated = useHydrated();
+    const [editing, setEditing] = useState(false);
+    const [need, setNeed] = useNeed(props.need, needs.map(n => n.value), () => setEditing(false));
+    const events = useLeadEvents(root, { formId, layout, experiment });
+    useOpenOnHash(`${id}-callback`);
+    const resolved = resolveChannels({ ...contact, hours: place.hours }, { now: new Date(useNow(renderedAt)), timeZone: props.timeZone, prefer: props.prefer });
+    const opening = openingText(resolved.nextOpening, text, locale);
+    const needLabel = needs.find(n => n.value === need)?.label;
+    const message = needLabel ? fillText(text.message, { need: needLabel }) : text.messageGeneric;
+    const [lead = "form", ...rest] = resolved.order;
+    const links = rest.filter((ch) => ch !== "form" && ch !== "callback");
+    const pick = (value) => {
+        if (layout === "single") {
+            setNeed(value);
+            setEditing(true);
+            return;
+        }
+        // The checked radio has already shown the contact step (`:has`, below), so
+        // the first empty field — the postcode unless filled, else the phone —
+        // takes focus inside the tap: iOS opens the keyboard only for a focus a
+        // gesture made, and a re-render is too late for it.
+        const fields = root.current?.querySelectorAll(`#${CSS.escape(id)} [data-lead-field="locality"], #${CSS.escape(id)} [data-lead-field="phone"]`);
+        [...(fields ?? [])].find(f => f.value === "")?.focus();
+        setNeed(value);
+        setEditing(false);
+        events.step("contact");
+    };
+    const channel = (ch, primary) => ch === "callback" ? (_jsx(CallbackForm, { id: `${id}-callback`, open: primary, formId: formId, placeSlug: place.slug, locale: locale, renderedAt: renderedAt, mobileName: wire.mobile, subject: need ? { name: wire.subject, value: need } : null, opening: opening, text: text, experiment: experiment, classNames: c }, ch)) : ch === "form" ? null : (_jsx(ChannelLink, { channel: ch, contact: contact, message: message, text: text, primary: primary, experiment: experiment, classNames: c }, ch));
+    // `qualify-first` shows the contact step as soon as a need's radio is
+    // checked (`:has`) — without a script, and inside the tap with one.
+    const contactShown = layout === "single" || (need !== undefined && !editing);
+    const contactClass = contactShown ? "flex" : "hidden group-has-[[data-need-option]:checked]/lead:flex";
+    return (_jsxs("div", { ref: root, className: cn("flex w-full flex-col gap-6", props.className, c?.root), "data-experiment": experiment?.name, "data-variant": experiment?.variant, children: [props.head ?? (_jsxs("div", { className: cn("flex flex-col gap-1", c?.head), children: [_jsx("p", { className: cn("font-display text-2xl font-bold text-ink", c?.title), children: text.title }), _jsx("p", { className: cn("text-ink-soft", c?.lede), children: text.lede })] })), lead !== "form" && channel(lead, true), _jsxs(QuoteFormShell, { id: id, placeSlug: place.slug, locale: locale, renderedAt: renderedAt, honeypotLabel: text.honeypotLabel, formId: formId, className: cn("group/lead", c?.form), children: [_jsx(ExperimentFields, { experiment: experiment }), _jsx(NeedField, { layout: layout, name: wire.subject, needs: needs, need: need, editing: editing, hydrated: hydrated, label: text.needLabel, changeLabel: text.needChange, onPick: pick, onEdit: () => {
+                            setEditing(true);
+                            events.step("need");
+                        }, classNames: c }), _jsxs("div", { className: cn("flex-col gap-5", contactClass, c?.contact), children: [_jsx(LocalityField, { name: wire.locality, label: text.localityLabel, servedLabel: text.servedLabel, served: servedLocalities(place), required: props.locality !== "optional", optional: text.optional, hydrated: hydrated, classNames: c }), _jsx(PhoneField, { name: wire.mobile, label: text.phoneLabel, hint: text.phoneHint, onSoftError: () => events.fieldError("phone"), classNames: c }), props.name && _jsx(NameField, { name: props.name.field, label: text.nameLabel, required: props.name.required ?? false, optional: text.optional, classNames: c }), props.extras, _jsxs("div", { className: cn("flex flex-col gap-3", c?.trust), children: [_jsx(Button, { type: "submit", size: "touch", className: cn("w-full", c?.submit), children: text.submit }), props.trust] }), opening && lead !== "callback" && _jsx("p", { className: cn("text-sm text-ink-soft", c?.opening), children: opening }), _jsx("p", { className: cn("text-sm text-ink-soft", c?.privacy), children: text.privacy })] })] }), (links.length > 0 || rest.includes("callback")) && (_jsxs("div", { className: cn("flex flex-col gap-3", c?.others), children: [_jsx("p", { className: "text-sm font-medium text-ink", children: text.otherChannels }), links.length > 0 && _jsx("div", { className: "flex flex-wrap gap-2", children: links.map(ch => channel(ch, false)) }), rest.includes("callback") && channel("callback", false)] }))] }));
+}

package/dist/react/LeadCaptureChannels.d.ts

@@ -0,0 +1,54 @@
+import { type CaptureChannel } from "../core/channels.js";
+import type { LeadCaptureText } from "../core/lead-capture-text.js";
+import type { PartClassNames } from "./parts.js";
+export type ChannelPart = "channel" | "primary" | "callback" | "consent";
+export interface Experiment {
+    name: string;
+    variant: string;
+}
+/** The site's assignment, posted with the form so the submit counts in its arm. */
+export declare function ExperimentFields({ experiment }: {
+    experiment: Experiment | undefined;
+}): import("react").JSX.Element | null;
+/**
+ * A channel that leaves the page — `tel:`, `wa.me`, `sms:` — as a link the
+ * boundary counts: the tracker reads `tel:` and WhatsApp itself, `data-intent`
+ * names the text message it cannot classify. The assignment rides on the link
+ * because the tracker reads the link's own `data-*`.
+ */
+export declare function ChannelLink(props: {
+    channel: Exclude<CaptureChannel, "form" | "callback">;
+    contact: {
+        phone: string | null;
+        whatsapp: string | null;
+    };
+    message: string;
+    text: LeadCaptureText;
+    primary: boolean;
+    experiment: Experiment | undefined;
+    classNames?: PartClassNames<ChannelPart> | undefined;
+}): import("react").JSX.Element | null;
+/**
+ * "Call me back": the form cut to a phone number and a consent, posted to the
+ * same `/quote` with `channel=callback` — a lead like any other, without a
+ * script. A `<details>` so it opens without one too; open from the start when
+ * it is the channel that leads (the place is closed), or when the page is
+ * opened at its id (`#quote-callback`, the call bar's link).
+ */
+export declare function CallbackForm(props: {
+    id: string;
+    open: boolean;
+    formId: string;
+    placeSlug: string | null;
+    locale: string;
+    renderedAt: number;
+    mobileName: string;
+    subject: {
+        name: string;
+        value: string;
+    } | null;
+    opening: string | null;
+    text: LeadCaptureText;
+    experiment: Experiment | undefined;
+    classNames?: PartClassNames<ChannelPart> | undefined;
+}): import("react").JSX.Element;

package/dist/react/LeadCaptureChannels.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, buttonVariants, cn, FieldLabel, Input } from "@evinvest/uikit";
+import { EXPERIMENT_FIELD, VARIANT_FIELD } from "../core/accept.js";
+import { channelHref } from "../core/channels.js";
+import { CHANNEL_FIELD, CONSENT_FIELD } from "../core/lead.js";
+import { PHONE_INPUT_PROPS, QuoteFormShell } from "./QuoteFormShell.js";
+/** The site's assignment, posted with the form so the submit counts in its arm. */
+export function ExperimentFields({ experiment }) {
+    if (!experiment)
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsx("input", { type: "hidden", name: EXPERIMENT_FIELD, value: experiment.name }), _jsx("input", { type: "hidden", name: VARIANT_FIELD, value: experiment.variant })] }));
+}
+const LABEL = { phone: "call", whatsapp: "whatsapp", sms: "sms" };
+/**
+ * A channel that leaves the page — `tel:`, `wa.me`, `sms:` — as a link the
+ * boundary counts: the tracker reads `tel:` and WhatsApp itself, `data-intent`
+ * names the text message it cannot classify. The assignment rides on the link
+ * because the tracker reads the link's own `data-*`.
+ */
+export function ChannelLink(props) {
+    const { channel, contact, message, text, primary, experiment, classNames: c } = props;
+    const href = channelHref(channel, contact, message);
+    if (!href)
+        return null;
+    return (_jsx(Button, { href: href, variant: primary ? "primary" : "outline", size: "touch", className: cn(primary ? "w-full" : "flex-1", c?.channel, primary && c?.primary), "data-intent": channel === "sms" ? "sms" : undefined, "data-experiment": experiment?.name, "data-variant": experiment?.variant, children: text[LABEL[channel]] }));
+}
+/**
+ * "Call me back": the form cut to a phone number and a consent, posted to the
+ * same `/quote` with `channel=callback` — a lead like any other, without a
+ * script. A `<details>` so it opens without one too; open from the start when
+ * it is the channel that leads (the place is closed), or when the page is
+ * opened at its id (`#quote-callback`, the call bar's link).
+ */
+export function CallbackForm(props) {
+    const { id, open, formId, placeSlug, locale, renderedAt, mobileName, subject, opening, text, experiment, classNames: c } = props;
+    return (_jsxs("details", { id: id, open: open, className: cn("w-full", c?.callback), children: [_jsx("summary", { "data-intent": "callback", className: buttonVariants({ variant: open ? "primary" : "outline", size: "touch", className: cn("w-full list-none [&::-webkit-details-marker]:hidden", c?.channel, open && c?.primary) }), children: text.callback }), _jsxs(QuoteFormShell, { id: `${id}-form`, placeSlug: placeSlug, locale: locale, renderedAt: renderedAt, honeypotLabel: text.honeypotLabel, formId: formId, className: "mt-4 gap-4", children: [_jsx("input", { type: "hidden", name: CHANNEL_FIELD, value: "callback" }), subject && _jsx("input", { type: "hidden", name: subject.name, value: subject.value }), _jsx(ExperimentFields, { experiment: experiment }), _jsx("p", { className: "text-ink-soft", children: opening ?? text.callbackLede }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(FieldLabel, { htmlFor: `${id}-phone`, children: text.phoneLabel }), _jsx(Input, { id: `${id}-phone`, name: mobileName, size: "lg", ...PHONE_INPUT_PROPS, enterKeyHint: "send", required: true, "data-lead-field": "phone" })] }), _jsxs("label", { className: cn("flex min-h-11 items-start gap-3 text-sm text-ink", c?.consent), children: [_jsx("input", { type: "checkbox", name: CONSENT_FIELD, value: text.callbackConsent, required: true, "data-lead-field": "consent", className: "mt-0.5 size-5 shrink-0 accent-primary" }), _jsx("span", { children: text.callbackConsent })] }), _jsx(Button, { type: "submit", size: "touch", className: "w-full", children: text.callbackSubmit })] })] }));
+}

package/dist/react/LeadCaptureFields.d.ts

@@ -0,0 +1,32 @@
+import type { PartClassNames } from "./parts.js";
+export type FieldPart = "field" | "label" | "control" | "hint" | "chips" | "chip";
+export declare function LocalityField(props: {
+    name: string;
+    label: string;
+    servedLabel: string;
+    /** The communes the place names: one is filled in, a few are a tap each. */
+    served: readonly string[];
+    required: boolean;
+    optional: string;
+    hydrated: boolean;
+    classNames?: PartClassNames<FieldPart> | undefined;
+}): import("react").JSX.Element;
+/**
+ * The number, required and never masked. A value that does not read as a
+ * phone gets a hint under it when the visitor leaves the field — a hint, not
+ * a refusal: the server keeps what it cannot parse, as typed.
+ */
+export declare function PhoneField(props: {
+    name: string;
+    label: string;
+    hint: string;
+    onSoftError: () => void;
+    classNames?: PartClassNames<FieldPart> | undefined;
+}): import("react").JSX.Element;
+export declare function NameField(props: {
+    name: string;
+    label: string;
+    required: boolean;
+    optional: string;
+    classNames?: PartClassNames<FieldPart> | undefined;
+}): import("react").JSX.Element;

package/dist/react/LeadCaptureFields.js

@@ -0,0 +1,42 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, cn, Field, FieldDescription, FieldLabel, Input } from "@evinvest/uikit";
+import { useId, useRef, useState } from "react";
+import { isPlausiblePhone } from "../core/phone.js";
+import { PHONE_INPUT_PROPS } from "./QuoteFormShell.js";
+/** More than this and the row is a list to read, not a tap to save typing. */
+const MAX_CHIPS = 6;
+const optionalLabel = (label, optional) => (optional ? `${label} (${optional})` : label);
+export function LocalityField(props) {
+    const { name, label, servedLabel, served, required, optional, hydrated, classNames: c } = props;
+    const input = useRef(null);
+    const chips = hydrated && served.length > 1 && served.length <= MAX_CHIPS;
+    return (_jsxs(Field, { className: cn("flex flex-col gap-2", c?.field), children: [_jsx(FieldLabel, { className: c?.label, children: optionalLabel(label, required ? null : optional) }), _jsx(Input, { ref: input, name: name, size: "lg", inputMode: "numeric", autoComplete: "postal-code", enterKeyHint: "next", required: required, defaultValue: served.length === 1 ? served[0] : undefined, "data-lead-field": "locality", className: c?.control }), chips && (_jsx("div", { role: "group", "aria-label": servedLabel, className: cn("flex flex-wrap gap-2", c?.chips), children: served.map(commune => (_jsx(Button, { type: "button", variant: "outline", size: "touch", className: cn("px-3", c?.chip), onClick: () => {
+                        if (input.current)
+                            input.current.value = commune;
+                    }, children: commune }, commune))) }))] }));
+}
+/**
+ * The number, required and never masked. A value that does not read as a
+ * phone gets a hint under it when the visitor leaves the field — a hint, not
+ * a refusal: the server keeps what it cannot parse, as typed.
+ */
+export function PhoneField(props) {
+    const { name, label, hint, onSoftError, classNames: c } = props;
+    const hintId = useId();
+    const [doubtful, setDoubtful] = useState(false);
+    return (_jsxs(Field, { className: cn("flex flex-col gap-2", c?.field), children: [_jsx(FieldLabel, { className: c?.label, children: label }), _jsx(Input, { name: name, size: "lg", ...PHONE_INPUT_PROPS, enterKeyHint: "send", required: true, "data-lead-field": "phone", "aria-invalid": doubtful || undefined, "aria-describedby": doubtful ? hintId : undefined, onBlur: e => {
+                    const value = e.currentTarget.value;
+                    const bad = value.trim() !== "" && !isPlausiblePhone(value);
+                    if (bad && !doubtful)
+                        onSoftError();
+                    setDoubtful(bad);
+                }, onInput: e => {
+                    if (doubtful && isPlausiblePhone(e.currentTarget.value))
+                        setDoubtful(false);
+                }, className: c?.control }), doubtful && (_jsx(FieldDescription, { id: hintId, className: cn("text-accent-error", c?.hint), children: hint }))] }));
+}
+export function NameField(props) {
+    const { name, label, required, optional, classNames: c } = props;
+    return (_jsxs(Field, { className: cn("flex flex-col gap-2", c?.field), children: [_jsx(FieldLabel, { className: c?.label, children: optionalLabel(label, required ? null : optional) }), _jsx(Input, { name: name, size: "lg", autoComplete: "name", enterKeyHint: "next", required: required, "data-lead-field": "name", className: c?.control })] }));
+}

package/dist/react/LeadCaptureNeed.d.ts

@@ -0,0 +1,27 @@
+import { type FormSelectOption } from "./FormSelect.js";
+import type { PartClassNames } from "./parts.js";
+export type LeadCaptureLayout = "single" | "qualify-first";
+type NeedPart = "field" | "label" | "need" | "needs" | "summary";
+export interface NeedFieldProps {
+    layout: LeadCaptureLayout;
+    name: string;
+    needs: readonly FormSelectOption[];
+    need: string | undefined;
+    /** Showing the choice again after it was made for the visitor. */
+    editing: boolean;
+    hydrated: boolean;
+    label: string;
+    changeLabel: string;
+    onPick: (need: string) => void;
+    onEdit: () => void;
+    classNames?: PartClassNames<NeedPart> | undefined;
+}
+/**
+ * What the job is. A need already known — from the page, `?need=` or the card
+ * tapped — is not asked again: it is a line with its label and, once the
+ * script runs, a way to change it. Otherwise `single` asks with the kit's
+ * select (first need by default, as before) and `qualify-first` with a tile
+ * per need: one tap answers it.
+ */
+export declare function NeedField(props: NeedFieldProps): import("react").JSX.Element;
+export {};

package/dist/react/LeadCaptureNeed.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, cn, Field, FieldLabel } from "@evinvest/uikit";
+import { FormSelect } from "./FormSelect.js";
+/**
+ * What the job is. A need already known — from the page, `?need=` or the card
+ * tapped — is not asked again: it is a line with its label and, once the
+ * script runs, a way to change it. Otherwise `single` asks with the kit's
+ * select (first need by default, as before) and `qualify-first` with a tile
+ * per need: one tap answers it.
+ */
+export function NeedField(props) {
+    const { layout, name, needs, need, editing, hydrated, label, changeLabel, onPick, onEdit, classNames: c } = props;
+    const chosen = needs.find(n => n.value === need);
+    if (chosen && !editing) {
+        return (_jsxs("div", { className: cn("flex flex-wrap items-center gap-x-3 gap-y-1 text-ink", c?.summary), children: [_jsx("input", { type: "hidden", name: name, value: chosen.value }), _jsx("span", { className: "text-sm text-ink-soft", children: label }), _jsx("span", { className: "font-medium", children: chosen.label }), hydrated && (_jsx(Button, { type: "button", variant: "link", size: "touch", className: "px-1", onClick: onEdit, children: changeLabel }))] }));
+    }
+    if (layout === "single") {
+        return (_jsxs(Field, { className: cn("flex flex-col gap-2", c?.field), children: [_jsx(FieldLabel, { className: c?.label, children: label }), _jsx(FormSelect, { name: name, size: "lg", defaultValue: need ?? needs[0]?.value, options: needs, onValueChange: onPick })] }));
+    }
+    return (_jsxs("fieldset", { className: cn("flex flex-col gap-2", c?.field), children: [_jsx("legend", { className: cn("mb-2 text-sm font-medium text-ink", c?.label), children: label }), _jsx("div", { className: cn("grid grid-cols-1 gap-2 sm:grid-cols-2", c?.needs), children: needs.map(n => (_jsxs("label", { className: "relative block cursor-pointer", children: [_jsx("input", { type: "radio", name: name, value: n.value, required: true, checked: need === n.value, onChange: () => onPick(n.value), className: "peer absolute inset-0 opacity-0", "data-need-option": "", "data-lead-field": "need" }), _jsx("span", { className: cn("flex min-h-11 items-center rounded-[var(--control-radius)] border border-input px-4 py-3 text-ink transition-colors", "peer-checked:border-primary peer-checked:bg-hover peer-focus-visible:ring-[3px] peer-focus-visible:ring-ring/50", c?.need), children: n.label })] }, n.value))) })] }));
+}

package/dist/react/analytics-context.d.ts

@@ -0,0 +1,11 @@
+import type { AnalyticsSink } from "@evinvest/analytics";
+import { experimentProps } from "../core/analytics.js";
+/**
+ * The sink `AnalyticsBoundary` built, for an island inside it that reports
+ * events of its own (`LeadCapture`). Outside a boundary there is none, and the
+ * island reports nothing — the same as a boundary with no key.
+ */
+export declare const AnalyticsSinkContext: import("react").Context<AnalyticsSink | null>;
+export declare const useAnalyticsSink: () => AnalyticsSink | null;
+/** `data-experiment` / `data-variant` on an element or its ancestors, for an intent's event. */
+export declare function experimentOf(el: Element | null): ReturnType<typeof experimentProps>;

package/dist/react/analytics-context.js

@@ -0,0 +1,15 @@
+"use client";
+import { createContext, useContext } from "react";
+import { experimentProps } from "../core/analytics.js";
+/**
+ * The sink `AnalyticsBoundary` built, for an island inside it that reports
+ * events of its own (`LeadCapture`). Outside a boundary there is none, and the
+ * island reports nothing — the same as a boundary with no key.
+ */
+export const AnalyticsSinkContext = createContext(null);
+export const useAnalyticsSink = () => useContext(AnalyticsSinkContext);
+/** `data-experiment` / `data-variant` on an element or its ancestors, for an intent's event. */
+export function experimentOf(el) {
+    const host = el?.closest("[data-experiment]");
+    return experimentProps(host?.getAttribute("data-experiment"), host?.getAttribute("data-variant"));
+}

package/dist/react/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * `@evinvest/kitstart/react` — the structural widgets every landing shares,
  * where behaviour matters more than look. Server components by default; only
- * `MapFacade`, `AnalyticsBoundary` and `FormSelect` are client modules, each its own file
+ * `MapFacade`, `AnalyticsBoundary`, `FormSelect` and `LeadCapture` are client modules, each its own file
  * with its own `"use client"`, so a page pays for what it renders.
  *
  * Styled with the kit's token roles only (`text-ink`, `border-border`,
@@ -17,6 +17,8 @@ export { Coverage, type CoveragePart, type CoverageProps } from "./Coverage.js";
 export { Faq, type FaqPart, type FaqProps } from "./Faq.js";
 export { FormSelect, type FormSelectOption, type FormSelectPart, type FormSelectProps } from "./FormSelect.js";
 export { LangSwitch, withLang, type LangSwitchProps } from "./LangSwitch.js";
+export { LeadCapture, type LeadCapturePart, type LeadCaptureProps } from "./LeadCapture.js";
+export type { LeadCaptureLayout } from "./LeadCaptureNeed.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,7 +1,7 @@
 /**
  * `@evinvest/kitstart/react` — the structural widgets every landing shares,
  * where behaviour matters more than look. Server components by default; only
- * `MapFacade`, `AnalyticsBoundary` and `FormSelect` are client modules, each its own file
+ * `MapFacade`, `AnalyticsBoundary`, `FormSelect` and `LeadCapture` are client modules, each its own file
  * with its own `"use client"`, so a page pays for what it renders.
  *
  * Styled with the kit's token roles only (`text-ink`, `border-border`,
@@ -17,6 +17,7 @@ export { Coverage } from "./Coverage.js";
 export { Faq } from "./Faq.js";
 export { FormSelect } from "./FormSelect.js";
 export { LangSwitch, withLang } from "./LangSwitch.js";
+export { LeadCapture } from "./LeadCapture.js";
 export { MapFacade } from "./MapFacade.js";
 export { PlaceDirectory } from "./PlaceDirectory.js";
 export { PHONE_INPUT_PROPS, QuoteFormShell } from "./QuoteFormShell.js";

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

@@ -0,0 +1,24 @@
+/** The attribute a trigger elsewhere on the page names the need it is about in. */
+export declare const NEED_ATTR = "data-need";
+/**
+ * "Now" for the opening hours: the render's stamp on the server and while
+ * hydrating — so the two agree — then the visitor's clock, a minute at a time.
+ * A page cached for ten minutes is put right once it runs.
+ */
+export declare function useNow(renderedAt: number): number;
+/** `false` on the server and while hydrating, `true` from the render after. */
+export declare const useHydrated: () => boolean;
+/**
+ * The need, chosen for the visitor when the page knows it: the prop, then
+ * `?need=` once the script runs (a cached page cannot read the query), then a
+ * tap on any `[data-need]` trigger — the card the visitor came from. Only one
+ * of `needs` is taken; anything else is ignored.
+ */
+export declare function useNeed(initial: string | undefined, needs: readonly string[], 
+/** Told when the page, not the visitor's own pick, set the need. */
+onPreset: () => void): [string | undefined, (need: string) => void];
+/**
+ * Opens the `<details>` the page's fragment names — the call bar links to the
+ * callback by id, and not every browser opens a closed one it scrolls to.
+ */
+export declare function useOpenOnHash(id: string): void;

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

@@ -0,0 +1,71 @@
+"use client";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+/** The attribute a trigger elsewhere on the page names the need it is about in. */
+export const NEED_ATTR = "data-need";
+const MINUTE = 60_000;
+const subscribeMinute = (tick) => {
+    const timer = setInterval(tick, MINUTE);
+    return () => clearInterval(timer);
+};
+// The minute, not the millisecond: the snapshot must be stable between reads.
+const minuteNow = () => Math.floor(Date.now() / MINUTE) * MINUTE;
+/**
+ * "Now" for the opening hours: the render's stamp on the server and while
+ * hydrating — so the two agree — then the visitor's clock, a minute at a time.
+ * A page cached for ten minutes is put right once it runs.
+ */
+export function useNow(renderedAt) {
+    return useSyncExternalStore(subscribeMinute, minuteNow, () => renderedAt);
+}
+const subscribeNothing = () => () => { };
+/** `false` on the server and while hydrating, `true` from the render after. */
+export const useHydrated = () => useSyncExternalStore(subscribeNothing, () => true, () => false);
+/**
+ * The need, chosen for the visitor when the page knows it: the prop, then
+ * `?need=` once the script runs (a cached page cannot read the query), then a
+ * tap on any `[data-need]` trigger — the card the visitor came from. Only one
+ * of `needs` is taken; anything else is ignored.
+ */
+export function useNeed(initial, needs, 
+/** Told when the page, not the visitor's own pick, set the need. */
+onPreset) {
+    const [need, setNeed] = useState(initial !== undefined && needs.includes(initial) ? initial : undefined);
+    const key = needs.join("\n");
+    const preset = useRef(onPreset);
+    preset.current = onPreset;
+    useEffect(() => {
+        const list = key.split("\n");
+        const take = (value) => {
+            if (!value || !list.includes(value))
+                return;
+            setNeed(value);
+            preset.current();
+        };
+        take(new URLSearchParams(window.location.search).get("need"));
+        const onClick = (event) => {
+            const trigger = event.target instanceof Element ? event.target.closest(`[${NEED_ATTR}]`) : null;
+            take(trigger?.getAttribute(NEED_ATTR));
+        };
+        document.addEventListener("click", onClick, { capture: true });
+        return () => document.removeEventListener("click", onClick, { capture: true });
+    }, [key]);
+    return [need, setNeed];
+}
+/**
+ * Opens the `<details>` the page's fragment names — the call bar links to the
+ * callback by id, and not every browser opens a closed one it scrolls to.
+ */
+export function useOpenOnHash(id) {
+    useEffect(() => {
+        const open = () => {
+            if (window.location.hash !== `#${id}`)
+                return;
+            const el = document.getElementById(id);
+            if (el instanceof HTMLDetailsElement)
+                el.open = true;
+        };
+        open();
+        window.addEventListener("hashchange", open);
+        return () => window.removeEventListener("hashchange", open);
+    }, [id]);
+}

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

@@ -0,0 +1,23 @@
+import { type RefObject } from "react";
+import { type LeadField, type LeadStep } from "../core/analytics.js";
+/** The attribute a lead form's control names its role in, for `lead_form_field_error`. */
+export declare const FIELD_ATTR = "data-lead-field";
+export interface LeadEvents {
+    step(step: LeadStep): void;
+    fieldError(field: LeadField): void;
+}
+/**
+ * The lead form's own funnel, reported through the boundary's sink: seen
+ * (half of it in view, once), started (the first focus inside, once), a
+ * field the browser refused (`invalid`, by role — never the value), and the
+ * step `qualify-first` moved to. Every event carries the form, the layout and
+ * the site's experiment, so the arms of a test compare on one schema.
+ */
+export declare function useLeadEvents(root: RefObject<HTMLElement | null>, tags: {
+    formId: string;
+    layout: string;
+    experiment?: {
+        name: string;
+        variant: string;
+    } | undefined;
+}): LeadEvents;

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

@@ -0,0 +1,62 @@
+"use client";
+import { useEffect, useMemo, useRef } from "react";
+import { EVENTS, experimentProps } from "../core/analytics.js";
+import { useAnalyticsSink } from "./analytics-context.js";
+/** The attribute a lead form's control names its role in, for `lead_form_field_error`. */
+export const FIELD_ATTR = "data-lead-field";
+/**
+ * The lead form's own funnel, reported through the boundary's sink: seen
+ * (half of it in view, once), started (the first focus inside, once), a
+ * field the browser refused (`invalid`, by role — never the value), and the
+ * step `qualify-first` moved to. Every event carries the form, the layout and
+ * the site's experiment, so the arms of a test compare on one schema.
+ */
+export function useLeadEvents(root, tags) {
+    const sink = useAnalyticsSink();
+    const { formId, layout } = tags;
+    const name = tags.experiment?.name;
+    const variant = tags.experiment?.variant;
+    const props = useMemo(() => ({ form_id: formId, layout, ...experimentProps(name, variant) }), [formId, layout, name, variant]);
+    const started = useRef(false);
+    useEffect(() => {
+        const el = root.current;
+        if (!sink || !el)
+            return;
+        let seen = false;
+        const view = () => {
+            if (seen)
+                return;
+            seen = true;
+            sink.capture(EVENTS.formView, props);
+        };
+        // Without an observer (an old browser, a test DOM) rendering is seeing.
+        const observer = typeof IntersectionObserver === "function" ? new IntersectionObserver(es => es.some(e => e.isIntersecting) && view(), { threshold: 0.5 }) : null;
+        if (observer)
+            observer.observe(el);
+        else
+            view();
+        const focus = () => {
+            if (started.current)
+                return;
+            started.current = true;
+            sink.capture(EVENTS.formStart, props);
+        };
+        // `invalid` does not bubble: listened to on the way down.
+        const invalid = (event) => {
+            const field = event.target instanceof Element ? event.target.getAttribute(FIELD_ATTR) : null;
+            if (field)
+                sink.capture(EVENTS.fieldError, { ...props, field });
+        };
+        el.addEventListener("focusin", focus);
+        el.addEventListener("invalid", invalid, true);
+        return () => {
+            observer?.disconnect();
+            el.removeEventListener("focusin", focus);
+            el.removeEventListener("invalid", invalid, true);
+        };
+    }, [sink, root, props]);
+    return useMemo(() => ({
+        step: step => sink?.capture(EVENTS.formStep, { ...props, step }),
+        fieldError: field => sink?.capture(EVENTS.fieldError, { ...props, field }),
+    }), [sink, props]);
+}

package/dist/server/index.d.ts

@@ -13,6 +13,6 @@ export { parseSmtpUrl, sendMail, type Mail, type SendOptions } from "./smtp.js";
 export { defaultLeadMail, leadNotifier, MAIL_PER_MINUTE, type LeadMail, type LeadNotifier, type NotifyEnv } from "./notify.js";
 export { clientKey, NO_CLIENT_ADDRESS, parseProxyTrust, type ProxyTrust } from "./client-key.js";
 export { checkLeadStore } from "./boot.js";
-export { leadWebhook, type BuildWebhookBody, type LeadWebhook, type LeadWebhookContext, type LeadWebhookOptions } from "./lead-webhook.js";
+export { leadWebhook, panelChannel, type BuildWebhookBody, type LeadWebhook, type LeadWebhookContext, type LeadWebhookOptions } from "./lead-webhook.js";
 export { checkWebhookUrl, openWebhookOutbox, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_TICK_MS, type OutboxRow, type OutboxState, type TickReport, type WebhookOutbox, type WebhookOutboxOptions, type WebhookTarget, } from "./webhook-outbox.js";
 export { signatureHeaders, signWebhook, type WebhookSignatureHeaders, type WebhookSigning } from "./webhook-signature.js";

package/dist/server/index.js

@@ -13,6 +13,6 @@ export { parseSmtpUrl, sendMail } from "./smtp.js";
 export { defaultLeadMail, leadNotifier, MAIL_PER_MINUTE } from "./notify.js";
 export { clientKey, NO_CLIENT_ADDRESS, parseProxyTrust } from "./client-key.js";
 export { checkLeadStore } from "./boot.js";
-export { leadWebhook } from "./lead-webhook.js";
+export { leadWebhook, panelChannel } from "./lead-webhook.js";
 export { checkWebhookUrl, openWebhookOutbox, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_TICK_MS, } from "./webhook-outbox.js";
 export { signatureHeaders, signWebhook } from "./webhook-signature.js";

package/dist/server/lead-store-sqlite.js

@@ -1,7 +1,7 @@
 import "server-only";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import { LEAD_SCHEMA_VERSION } from "../core/lead.js";
+import { channelOf, LEAD_SCHEMA_VERSION } from "../core/lead.js";
 // `node:sqlite` is reached through `getBuiltinModule` rather than an import so
 // the bundler never has to resolve a builtin it may not know yet; the type is
 // the module's own.
@@ -42,6 +42,14 @@ const STEPS = [
     db => db.exec("ALTER TABLE leads ADD COLUMN spam_verdict TEXT"),
     // 4 — the brand's extra fields, as a JSON object; `NULL` when there are none.
     db => db.exec("ALTER TABLE leads ADD COLUMN extras TEXT"),
+    // 5 — how the lead was asked for (`form`, `callback`), and a callback's
+    // consent: when the server accepted it and the sentence shown. Nullable: a
+    // row from before is a form lead, and a form lead has no consent to keep.
+    db => {
+        db.exec("ALTER TABLE leads ADD COLUMN channel TEXT");
+        db.exec("ALTER TABLE leads ADD COLUMN consent_at TEXT");
+        db.exec("ALTER TABLE leads ADD COLUMN consent_text TEXT");
+    },
 ];
 if (STEPS.length !== LEAD_SCHEMA_VERSION) {
     // The version belongs to the port, shared by every adapter; this table of
@@ -66,7 +74,7 @@ function recognise(db) {
         throw new Error(`leads: an unrecognised table (${columns.join(", ")}); refusing to migrate it`);
     }
     let at = 1;
-    for (const [step, added] of [[2, "location_id"], [3, "spam_verdict"], [4, "extras"]]) {
+    for (const [step, added] of [[2, "location_id"], [3, "spam_verdict"], [4, "extras"], [5, "consent_text"]]) {
         if (!columns.includes(added))
             break;
         at = step;
@@ -130,12 +138,12 @@ export function openSqliteLeadStore(path) {
         db.close();
         throw error;
     }
-    const insert = db.prepare("INSERT INTO leads (job, zip, mobile, location_id, spam_verdict, extras) VALUES (?, ?, ?, ?, ?, ?) RETURNING id");
+    const insert = db.prepare("INSERT INTO leads (job, zip, mobile, location_id, spam_verdict, extras, channel, consent_at, consent_text) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id");
     const count = db.prepare("SELECT COUNT(*) AS n FROM leads");
     return {
         async insert(lead) {
             const extras = Object.keys(lead.extras).length > 0 ? JSON.stringify(lead.extras) : null;
-            return integer(insert.get(lead.subject, lead.locality, lead.mobile, lead.placeSlug, lead.spamVerdict, extras), "id");
+            return integer(insert.get(lead.subject, lead.locality, lead.mobile, lead.placeSlug, lead.spamVerdict, extras, channelOf(lead), lead.consent?.at ?? null, lead.consent?.text ?? null), "id");
         },
         async count() {
             return integer(count.get(), "n");

package/dist/server/lead-webhook.d.ts

@@ -1,5 +1,5 @@
 import "server-only";
-import type { Lead } from "../core/lead.js";
+import type { Lead, LeadChannel } from "../core/lead.js";
 import type { ServerEnv } from "./env.js";
 import { type TickReport, type WebhookOutbox, type WebhookOutboxOptions } from "./webhook-outbox.js";
 import type { WebhookSigning } from "./webhook-signature.js";
@@ -15,6 +15,16 @@ export interface LeadWebhookContext {
     /** Fresh per lead and stored with the body, so every retry carries the same one. */
     idempotencyKey: string;
 }
+/**
+ * What the Service-Arb panel's `lead.created` calls a callback request. Its
+ * `properties.channel` is a closed set (`form` | `phone_inbound`) and an event
+ * outside it is refused whole — the outbox would park the lead — so until the
+ * panel's `sa.funnel.v1` accepts `callback`, a callback travels as `form`.
+ * TODO(panel): set to "callback" once the panel accepts it; nothing else changes.
+ */
+declare const PANEL_CALLBACK = "form";
+/** A lead's channel as the panel's `properties.channel` may carry it: `panelChannel(channelOf(lead))`. */
+export declare function panelChannel(channel: LeadChannel): "form" | typeof PANEL_CALLBACK;
 /**
  * The receiver's body, built by the brand: the kit serialises and signs
  * whatever this returns and knows nothing of its shape. Called once, when the
@@ -48,3 +58,4 @@ export declare function leadWebhook(site: {
         id: string;
     };
 }, env: Pick<ServerEnv, "leadsDb" | "leadWebhook">, options: LeadWebhookOptions): LeadWebhook | null;
+export {};