@doany-ai/forms 0.0.0-stage → 0.1.0-alpha.1

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @doany-ai/forms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The business's forms on a Doany site: contact, inquiry, subscription, application, quiz. The business defines a form (its questions, which services it asks about, what to show after); the site renders it and submits what the visitor fills in. A submission lands in the business's Inbox. Nothing here creates forms.
+
+```jsx
+import { Form } from "@doany-ai/forms";
+
+// /contact — the form by its id, as the business defined it
+<Form formId="…" context={{ page_path: "/contact" }} />
+```
+
+List the page in `doany/features.jsonc` under `forms`.
+
+## Records
+
+- **FormView** (`useForm`): `id`, `type` (`contact` | `inquiry` | `subscription` | `promotion` | `application` | `quiz` | `custom…`), `definition_hash` (identifies what the visitor saw; sent back with the answers), `definition` (`title`, `description`, `fields[]`, `settings`), `availability` (`can_submit`, `reason`: `preview_only` on a preview address, `no_service_options` when a required service question has nothing to offer).
+- **FormField**: `key`, `type`, `label`, `help`, `required`, `control` (`radio` | `dropdown` for a choice), `validation` (`min_length`, `max_length`, `min`, `max`), `options[]` (`value`, `label`), `selection` and `resolved_options[]` (`service` questions: the services on offer, `service_mode` `booking` | `inquiry`), `consent` (`mode` `checkbox` | `on_submit`).
+- Field types: `text`, `textarea`, `email`, `phone`, `number`, `date`, `select`, `multiselect`, `checkbox`, `scale`, `agreement`, `consent`, `hidden`, `statement`, `service`.
+- **FormSubmitReceipt** (`useSubmitForm`): `id`, `submitted_at`, `score` and `outcome` (a quiz), `completion` (the form's `thank_you_message`, `redirect_url`, `cta`).
+
+## `Form`
+
+Renders the questions, submits the answers, shows the confirmation the form sets (or a quiz's outcome), redirects when the form says so.
+
+| prop | |
+| --- | --- |
+| `formId` | required |
+| `context` | `{ page_path?, referrer?, utm?, language?, timezone?, source_service_id? }`, kept with the submission |
+| `defaultAnswers` | answers to start with, by field key (a `hidden` value, a preselected service) |
+| `submitLabel` | wins over the `submit` label |
+| `renderSuccess` | `(receipt) => node`: replaces the confirmation |
+| `showTitle` | the form's title and description above the questions; default `true` |
+| `variant` | `"single"` (default): every question on one page. `"steps"`: the questions in pages with a progress bar and Back / Next — a survey. The pages are `steps` when given, else one page per `statement` question (the statement heads its page), else one page. Each page's required questions gate Next |
+| `steps` | for `variant="steps"`: the field keys of each page, in order; keys left out go on the last page |
+| `frame` | `"plain"` (default): just the questions. `"card"`: on a raised card, the way a form embeds on a page |
+| `onSubmitted` | `(receipt) => void` |
+| `labels`, `className` | |
+
+Answers go to the platform by field key: text, date and single choices as strings, several choices as arrays, `checkbox` / `agreement` / `consent` as booleans, numbers as numbers; blanks are left out. A `consent` with `mode: "on_submit"` is sent as agreed when the form is submitted.
+
+Failures: `VERSION_CONFLICT` (the questions changed meanwhile) re-reads the form and says so; `RATE_LIMITED` asks to wait; anything else shows the site's `submitFailed` label when set, else the platform's message.
+
+To put the form in a popup, a sidebar or a slide-in panel, wrap it in `Embed` from `@doany-ai/app-core/ui`; inside, `useEmbed().markSubmitted()` and `close()` tell the shell the visitor is done.
+
+## Hooks
+
+| hook | returns |
+| --- | --- |
+| `useForm(formId)` | query of the `FormView` |
+| `useSubmitForm(formId)` | mutation: `mutate({ definition_hash, answers, context? })` → `FormSubmitReceipt` |
+
+## Labels
+
+`submit`, `submitting`, `thanks`, `score(score)`, `loadError`, `submitFailed`, `previewOnly`, `noServiceOptions`, `definitionChanged`, `rateLimited`, `tryAgain`, `notFound`, `choose`, `required`. The questions' own words come from the form's definition.
+
+## Customizing
+
+1. **Theme**: the site's variables style the inputs, buttons and the confirmation.
+2. **Props**: `labels`, `submitLabel`, `renderSuccess`, `defaultAnswers`, `className`.
+3. **Hooks**: draw the form yourself on `useForm` and `useSubmitForm`.
+
+The package ships no CSS: the site's Tailwind build scans `node_modules/@doany-ai/forms/dist`.
+
+## Develop
+
+```bash
+npm install
+npm run typecheck   # includes tests/sdk-contract.types.ts
+npm test
+npm run build
+```

package/dist/components/form.d.ts

@@ -0,0 +1,37 @@
+import { type ReactNode } from "react";
+import { type FormLabels } from "../labels.js";
+import type { FormAnswers, FormSubmitParams, FormSubmitReceipt } from "../types.js";
+export interface FormProps {
+    /** The form, as the business defined it (its id from the platform). */
+    formId: string;
+    /** Where it is filled in, kept with the submission; all optional. */
+    context?: FormSubmitParams["context"];
+    /** Answers to start with, by field key (a `hidden` field's value, a preselected service). */
+    defaultAnswers?: FormAnswers;
+    /** Wins over the `submit` label. */
+    submitLabel?: string;
+    /** Replaces the default confirmation. Receives the receipt (its `completion`, a quiz's `outcome`). */
+    renderSuccess?: (receipt: FormSubmitReceipt) => ReactNode;
+    /** Show the form's title and description above the questions. Default `true`. */
+    showTitle?: boolean;
+    /**
+     * `single` (default): every question on one page. `steps`: the questions
+     * in pages with a progress bar and Back / Next — a survey. The pages are
+     * `steps` when given, else one page per `statement` question (the
+     * statement heads its page), else one page.
+     */
+    variant?: "single" | "steps";
+    /** For `variant="steps"`: the field keys of each page, in order. Keys left out go on the last page. */
+    steps?: string[][];
+    /** `plain` (default): just the questions. `card`: on a raised card, the way a form embeds on a page. */
+    frame?: "plain" | "card";
+    onSubmitted?: (receipt: FormSubmitReceipt) => void;
+    labels?: Partial<FormLabels>;
+    className?: string;
+}
+/**
+ * A form as the business defined it: renders its questions, submits the
+ * answers, shows the confirmation the form sets (or a quiz's outcome). A
+ * submission lands in the business's Inbox.
+ */
+export declare function Form({ formId, context, defaultAnswers, submitLabel, renderSuccess, showTitle, variant, steps, frame, onSubmitted, labels: given, className }: FormProps): import("react").JSX.Element;

package/dist/components/form.js

@@ -0,0 +1,191 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@doany-ai/app-core";
+import { Button } from "@doany-ai/app-core/ui/button";
+import { Checkbox } from "@doany-ai/app-core/ui/checkbox";
+import { Input } from "@doany-ai/app-core/ui/input";
+import { Label } from "@doany-ai/app-core/ui/label";
+import { Skeleton } from "@doany-ai/app-core/ui/skeleton";
+import { Textarea } from "@doany-ai/app-core/ui/textarea";
+import { CheckCircle2, Loader2 } from "lucide-react";
+import { isE164, normalizePhone } from "../phone.js";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useForm, useSubmitForm } from "../hooks.js";
+import { formLabels } from "../labels.js";
+const selectClass = "h-11 w-full rounded-lg border border-input bg-background px-3 text-sm text-foreground focus:outline-none focus:ring-2 focus:ring-ring";
+const fieldClass = "h-11 rounded-lg";
+function messageOf(cause, labels, given) {
+    const { code, message } = (cause ?? {});
+    if (code === "VERSION_CONFLICT")
+        return labels.definitionChanged;
+    if (code === "RATE_LIMITED")
+        return labels.rateLimited;
+    return given?.submitFailed ?? (message || labels.submitFailed);
+}
+function Required({ on, labels }) {
+    return on ? _jsxs("span", { className: "ml-1 font-normal text-muted-foreground", children: ["(", labels.required, ")"] }) : null;
+}
+function Question({ field, value, onChange, labels }) {
+    const id = `doany-form-${field.key}`;
+    const text = typeof value === "string" ? value : "";
+    const label = (_jsxs(Label, { htmlFor: id, className: "text-sm font-semibold", children: [field.label, _jsx(Required, { on: field.required, labels: labels })] }));
+    const help = field.help ? _jsx("p", { className: "text-xs text-muted-foreground", children: field.help }) : null;
+    if (field.type === "hidden")
+        return null;
+    if (field.type === "statement") {
+        return (_jsxs("div", { className: "space-y-1", children: [_jsx("p", { className: "font-heading text-lg font-semibold", children: field.label }), field.help ? _jsx("p", { className: "text-sm text-muted-foreground", children: field.help }) : null] }));
+    }
+    if (field.type === "checkbox" || field.type === "agreement" || field.type === "consent") {
+        if (field.type === "consent" && field.consent?.mode === "on_submit")
+            return null;
+        return (_jsxs("div", { className: "space-y-1", children: [_jsxs("div", { className: "flex items-start gap-3", children: [_jsx(Checkbox, { id: id, checked: Boolean(value), onCheckedChange: (checked) => onChange(checked === true), required: field.required, className: "mt-0.5" }), _jsxs(Label, { htmlFor: id, className: "text-sm font-normal leading-snug", children: [field.label, _jsx(Required, { on: field.required, labels: labels })] })] }), help] }));
+    }
+    if (field.type === "service") {
+        const options = field.resolved_options ?? [];
+        if (field.selection === "multiple") {
+            const chosen = Array.isArray(value) ? value : [];
+            return (_jsxs("fieldset", { className: "space-y-2", children: [_jsxs("legend", { className: "text-sm font-semibold", children: [field.label, _jsx(Required, { on: field.required, labels: labels })] }), help, _jsx("div", { className: "grid gap-2 sm:grid-cols-2", children: options.map((option) => {
+                            const optionId = `${id}-${option.value}`;
+                            const on = chosen.includes(option.value);
+                            return (_jsxs("div", { className: cn("flex items-center gap-3 rounded-lg border px-3 py-2.5", on ? "border-primary bg-primary/5" : "border-border"), children: [_jsx(Checkbox, { id: optionId, checked: on, onCheckedChange: (checked) => onChange(checked === true ? [...chosen, option.value] : chosen.filter((v) => v !== option.value)) }), _jsx(Label, { htmlFor: optionId, className: "font-normal", children: option.label })] }, option.value));
+                        }) })] }));
+        }
+        return (_jsxs("div", { className: "space-y-2", children: [label, help, _jsxs("select", { id: id, value: text, onChange: (e) => onChange(e.target.value), required: field.required, className: selectClass, children: [_jsx("option", { value: "", children: labels.choose }), options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value)))] })] }));
+    }
+    if (field.type === "select") {
+        const options = field.options ?? [];
+        if (field.control === "radio") {
+            return (_jsxs("fieldset", { className: "space-y-2", children: [_jsxs("legend", { className: "text-sm font-semibold", children: [field.label, _jsx(Required, { on: field.required, labels: labels })] }), help, _jsx("div", { className: "grid gap-2 sm:grid-cols-2", children: options.map((option) => {
+                            const optionId = `${id}-${option.value}`;
+                            const on = text === option.value;
+                            return (_jsxs("label", { htmlFor: optionId, className: cn("flex cursor-pointer items-center gap-3 rounded-lg border px-3 py-2.5 text-sm", on ? "border-primary bg-primary/5" : "border-border"), children: [_jsx("input", { type: "radio", id: optionId, name: id, value: option.value, checked: on, onChange: () => onChange(option.value), required: field.required, className: "h-4 w-4 accent-primary" }), option.label] }, option.value));
+                        }) })] }));
+        }
+        return (_jsxs("div", { className: "space-y-2", children: [label, help, _jsxs("select", { id: id, value: text, onChange: (e) => onChange(e.target.value), required: field.required, className: selectClass, children: [_jsx("option", { value: "", children: labels.choose }), options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value)))] })] }));
+    }
+    if (field.type === "multiselect") {
+        const chosen = Array.isArray(value) ? value : [];
+        return (_jsxs("fieldset", { className: "space-y-2", children: [_jsxs("legend", { className: "text-sm font-semibold", children: [field.label, _jsx(Required, { on: field.required, labels: labels })] }), help, _jsx("div", { className: "grid gap-2 sm:grid-cols-2", children: (field.options ?? []).map((option) => {
+                        const optionId = `${id}-${option.value}`;
+                        const on = chosen.includes(option.value);
+                        return (_jsxs("div", { className: cn("flex items-center gap-3 rounded-lg border px-3 py-2.5", on ? "border-primary bg-primary/5" : "border-border"), children: [_jsx(Checkbox, { id: optionId, checked: on, onCheckedChange: (checked) => onChange(checked === true ? [...chosen, option.value] : chosen.filter((v) => v !== option.value)) }), _jsx(Label, { htmlFor: optionId, className: "font-normal", children: option.label })] }, option.value));
+                    }) })] }));
+    }
+    if (field.type === "scale") {
+        const min = field.validation?.min ?? 1;
+        const max = field.validation?.max ?? 5;
+        const steps = Array.from({ length: Math.max(0, max - min + 1) }, (_, i) => min + i);
+        return (_jsxs("fieldset", { className: "space-y-2", children: [_jsxs("legend", { className: "text-sm font-semibold", children: [field.label, _jsx(Required, { on: field.required, labels: labels })] }), help, _jsx("div", { role: "radiogroup", className: "flex flex-wrap gap-2", children: steps.map((n) => (_jsx("button", { type: "button", role: "radio", "aria-checked": value === n, onClick: () => onChange(n), className: cn("h-11 w-11 rounded-lg border text-sm font-semibold transition-colors", value === n ? "border-primary bg-primary text-primary-foreground" : "border-border hover:border-primary/60"), children: n }, n))) })] }));
+    }
+    if (field.type === "textarea") {
+        return (_jsxs("div", { className: "space-y-2", children: [label, help, _jsx(Textarea, { id: id, value: text, onChange: (e) => onChange(e.target.value), required: field.required, minLength: field.validation?.min_length, maxLength: field.validation?.max_length, rows: 4, className: "rounded-lg" })] }));
+    }
+    const inputType = field.type === "email" ? "email" : field.type === "phone" ? "tel" : field.type === "number" ? "number" : field.type === "date" ? "date" : "text";
+    const autoComplete = field.type === "email" ? "email" : field.type === "phone" ? "tel" : undefined;
+    return (_jsxs("div", { className: "space-y-2", children: [label, help, _jsx(Input, { id: id, type: inputType, autoComplete: autoComplete, value: typeof value === "number" ? String(value) : text, onChange: (e) => {
+                    if (field.type === "phone") {
+                        // The platform takes E.164 only: say so before the submit does.
+                        const normalized = normalizePhone(e.target.value);
+                        e.target.setCustomValidity(!normalized || isE164(normalized) ? "" : labels.phoneFormat);
+                    }
+                    onChange(field.type === "number" ? (e.target.value === "" ? "" : Number(e.target.value)) : e.target.value);
+                }, required: field.required, minLength: field.validation?.min_length, maxLength: field.validation?.max_length, min: field.validation?.min, max: field.validation?.max, className: fieldClass })] }));
+}
+/** The answers the platform takes: `hidden` values as given, numbers as numbers, nothing for blanks. */
+function answersOf(view, answers) {
+    const out = {};
+    for (const field of view.definition.fields) {
+        if (field.type === "statement")
+            continue;
+        // The backend writes an on-submit consent itself and refuses a value for it.
+        if (field.type === "consent" && field.consent?.mode === "on_submit")
+            continue;
+        const value = answers[field.key];
+        if (value === undefined || value === "" || value === null)
+            continue;
+        // Every option cleared again is no answer: the platform refuses an empty list.
+        if (Array.isArray(value) && value.length === 0)
+            continue;
+        out[field.key] = field.type === "phone" && typeof value === "string" ? normalizePhone(value) : value;
+    }
+    return out;
+}
+/** The questions in pages: as `steps` says, else one page per statement, else one page. */
+function pagesOf(fields, steps) {
+    const shown = fields.filter((f) => f.type !== "hidden");
+    if (steps && steps.length) {
+        const placed = new Set(steps.flat());
+        const pages = steps.map((keys) => keys.map((key) => shown.find((f) => f.key === key)).filter((f) => Boolean(f)));
+        const rest = shown.filter((f) => !placed.has(f.key));
+        if (rest.length)
+            pages[pages.length - 1] = [...pages[pages.length - 1], ...rest];
+        return pages.filter((page) => page.length);
+    }
+    if (shown.some((f) => f.type === "statement")) {
+        const pages = [];
+        for (const field of shown) {
+            if (field.type === "statement" || !pages.length)
+                pages.push([field]);
+            else
+                pages[pages.length - 1].push(field);
+        }
+        return pages;
+    }
+    return [shown];
+}
+function Success({ receipt, labels }) {
+    const completion = receipt.completion ?? {};
+    useEffect(() => {
+        if (completion.redirect_url && typeof window !== "undefined")
+            window.location.assign(completion.redirect_url);
+    }, [completion.redirect_url]);
+    return (_jsxs("div", { role: "status", className: "space-y-4 rounded-xl bg-success/10 p-5 text-success", children: [_jsxs("div", { className: "flex items-start gap-3", children: [_jsx(CheckCircle2, { className: "mt-0.5 h-5 w-5 shrink-0", "aria-hidden": "true" }), _jsxs("div", { className: "space-y-1", children: [_jsx("p", { className: "font-semibold", children: receipt.outcome?.label ?? completion.thank_you_message ?? labels.thanks }), receipt.outcome?.description ? _jsx("p", { className: "text-sm", children: receipt.outcome.description }) : null, receipt.score !== null && receipt.score !== undefined ? _jsx("p", { className: "text-sm", children: labels.score(receipt.score) }) : null] })] }), (receipt.outcome?.cta ?? completion.cta) && (_jsx(Button, { asChild: true, className: "rounded-lg", children: _jsx("a", { href: (receipt.outcome?.cta ?? completion.cta)?.url, children: (receipt.outcome?.cta ?? completion.cta)?.label }) }))] }));
+}
+/**
+ * A form as the business defined it: renders its questions, submits the
+ * answers, shows the confirmation the form sets (or a quiz's outcome). A
+ * submission lands in the business's Inbox.
+ */
+export function Form({ formId, context, defaultAnswers, submitLabel, renderSuccess, showTitle = true, variant = "single", steps, frame = "plain", onSubmitted, labels: given, className }) {
+    const labels = formLabels(given);
+    const { data: view, isLoading, isError, error, refetch } = useForm(formId);
+    const submit = useSubmitForm(formId);
+    const [answers, setAnswers] = useState(defaultAnswers ?? {});
+    const [receipt, setReceipt] = useState(null);
+    const [page, setPage] = useState(0);
+    const formRef = useRef(null);
+    const pages = useMemo(() => (view ? (variant === "steps" ? pagesOf(view.definition.fields, steps) : [view.definition.fields]) : []), [view, variant, steps]);
+    const framed = (node) => (frame === "card" ? _jsx("div", { className: cn("rounded-2xl border border-border bg-card p-6 text-card-foreground shadow-card sm:p-8", className), children: node }) : _jsx("div", { className: className, children: node }));
+    if (isLoading) {
+        return framed(_jsxs("div", { className: "space-y-4", "aria-busy": "true", children: [_jsx(Skeleton, { className: "h-6 w-1/2" }), _jsx(Skeleton, { className: "h-11 w-full" }), _jsx(Skeleton, { className: "h-11 w-full" }), _jsx(Skeleton, { className: "h-24 w-full" })] }));
+    }
+    if (isError || !view) {
+        const missing = error?.status === 404;
+        return framed(_jsxs("div", { role: "alert", className: "space-y-3 py-10 text-center text-sm", children: [_jsx("p", { className: "text-destructive", children: missing ? labels.notFound : (given?.loadError ?? (error?.message || labels.loadError)) }), !missing && (_jsx(Button, { variant: "outline", size: "sm", onClick: () => void refetch(), children: labels.tryAgain }))] }));
+    }
+    if (receipt)
+        return framed(renderSuccess ? renderSuccess(receipt) : _jsx(Success, { receipt: receipt, labels: labels }));
+    const blocked = !view.availability.can_submit;
+    const blockedText = view.availability.reason === "preview_only" ? labels.previewOnly : labels.noServiceOptions;
+    const stepped = variant === "steps" && pages.length > 1;
+    const last = !stepped || page === pages.length - 1;
+    const fields = stepped ? pages[page] : view.definition.fields;
+    const next = () => {
+        if (formRef.current && !formRef.current.reportValidity())
+            return;
+        setPage((p) => Math.min(p + 1, pages.length - 1));
+    };
+    const onSubmit = (event) => {
+        event.preventDefault();
+        if (!last) {
+            next();
+            return;
+        }
+        submit.mutate({ definition_hash: view.definition_hash, answers: answersOf(view, answers), ...(context ? { context } : {}) }, {
+            onSuccess: (r) => {
+                setReceipt(r);
+                onSubmitted?.(r);
+            },
+        });
+    };
+    return framed(_jsxs("form", { ref: formRef, onSubmit: onSubmit, className: "space-y-5", "aria-label": view.definition.title, children: [showTitle && (_jsxs("header", { className: "space-y-1", children: [_jsx("h2", { className: "font-heading text-2xl font-semibold tracking-tight", children: view.definition.title }), view.definition.description ? _jsx("p", { className: "text-sm text-muted-foreground", children: view.definition.description }) : null] })), stepped && (_jsxs("div", { className: "space-y-1.5", "aria-live": "polite", children: [_jsx("p", { className: "text-xs font-medium text-muted-foreground", children: labels.stepOf(page + 1, pages.length) }), _jsx("div", { className: "h-1.5 w-full overflow-hidden rounded-full bg-muted", role: "progressbar", "aria-valuemin": 1, "aria-valuemax": pages.length, "aria-valuenow": page + 1, children: _jsx("div", { className: "h-full rounded-full bg-primary transition-[width]", style: { width: `${((page + 1) / pages.length) * 100}%` } }) })] })), fields.map((field) => (_jsx(Question, { field: field, value: answers[field.key], onChange: (v) => setAnswers((a) => ({ ...a, [field.key]: v })), labels: labels }, field.key))), blocked && _jsx("p", { className: "text-sm text-muted-foreground", children: blockedText }), submit.isError && (_jsx("p", { role: "alert", className: "text-sm text-destructive", children: messageOf(submit.error, labels, given) })), _jsxs("div", { className: cn("flex items-center gap-3 pt-1", stepped && page > 0 ? "justify-between" : "justify-end"), children: [stepped && page > 0 ? (_jsx(Button, { type: "button", variant: "outline", className: "h-11 rounded-lg px-6", onClick: () => setPage((p) => Math.max(0, p - 1)), disabled: submit.isPending, children: labels.back })) : null, _jsxs(Button, { type: "submit", className: cn("h-11 rounded-lg font-semibold", last ? "w-full px-8 sm:w-auto" : "px-8"), disabled: blocked || submit.isPending, children: [submit.isPending && _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }), submit.isPending ? labels.submitting : last ? (submitLabel ?? labels.submit) : labels.next] })] })] }));
+}

package/dist/hooks.d.ts

@@ -0,0 +1,14 @@
+import type { FormSubmitParams, FormSubmitReceipt, FormView } from "./types.js";
+/** The query keys this package reads under, for invalidating from elsewhere. */
+export declare const formKeys: {
+    all: readonly ["doany", "forms"];
+    form: (formId: string) => readonly ["doany", "forms", "form", string];
+};
+/** A form's questions, and the hash a submission must carry. */
+export declare function useForm(formId: string | null | undefined): import("@tanstack/react-query").UseQueryResult<FormView, Error>;
+/**
+ * Submits one filled form. The platform refuses answers to a definition that
+ * changed since it was read (`VERSION_CONFLICT`); the hook then re-reads the
+ * form so the page can show the current questions.
+ */
+export declare function useSubmitForm(formId: string): import("@tanstack/react-query").UseMutationResult<FormSubmitReceipt, unknown, FormSubmitParams, unknown>;

package/dist/hooks.js

@@ -0,0 +1,36 @@
+import { useDoany } from "@doany-ai/app-core";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+/** The query keys this package reads under, for invalidating from elsewhere. */
+export const formKeys = {
+    all: ["doany", "forms"],
+    form: (formId) => [...formKeys.all, "form", formId],
+};
+/** A form's questions, and the hash a submission must carry. */
+export function useForm(formId) {
+    const doany = useDoany();
+    return useQuery({
+        queryKey: formKeys.form(formId ?? ""),
+        queryFn: () => doany.forms.get(formId),
+        enabled: Boolean(formId),
+        // The questions and the services on offer can change; a page open for a
+        // while asks again before the visitor fills it in.
+        staleTime: 60 * 1000,
+    });
+}
+/**
+ * Submits one filled form. The platform refuses answers to a definition that
+ * changed since it was read (`VERSION_CONFLICT`); the hook then re-reads the
+ * form so the page can show the current questions.
+ */
+export function useSubmitForm(formId) {
+    const doany = useDoany();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (params) => doany.forms.submit(formId, params),
+        onError: (cause) => {
+            const code = cause?.code;
+            if (code === "VERSION_CONFLICT")
+                void queryClient.invalidateQueries({ queryKey: formKeys.form(formId) });
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { formKeys, useForm, useSubmitForm } from "./hooks.js";
+export { defaultFormLabels, formLabels, type FormLabels } from "./labels.js";
+export { Form, type FormProps } from "./components/form.js";
+export type { FormAnswers, FormAvailability, FormCompletion, FormDefinition, FormField, FormFieldType, FormOption, FormsClient, FormServiceOption, FormSubmitParams, FormSubmitReceipt, FormView, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+// @doany-ai/forms: the business's forms, on its site.
+//
+// The hooks read and submit through the SDK client given to app-core's
+// <DoanyProvider>; <Form> is a default a site can restyle through the theme
+// variables, adjust through props (its words through `labels`), or replace
+// while keeping the hooks. The package ships no CSS: the site's Tailwind
+// build scans it (see @doany-ai/app-core/tailwind-preset).
+export { formKeys, useForm, useSubmitForm } from "./hooks.js";
+export { defaultFormLabels, formLabels } from "./labels.js";
+export { Form } from "./components/form.js";

package/dist/labels.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Every word the form components show besides the form's own questions,
+ * which come from the business's definition. A component takes a part of it
+ * as `labels` and keeps the default for the rest:
+ *
+ *   <Form formId={id} labels={{ submit: "Send", thanks: "Merci" }} />
+ */
+export interface FormLabels {
+    submit: string;
+    submitting: string;
+    /** The default confirmation, when the form sets no `thank_you_message`. */
+    thanks: string;
+    /** Under the confirmation of a quiz: its score. */
+    score: (score: number) => string;
+    /** The platform's words are shown instead, unless the site sets this. */
+    loadError: string;
+    submitFailed: string;
+    /** The form was read on a preview address: it does not take real submissions. */
+    previewOnly: string;
+    /** A required service question has nothing to offer. */
+    noServiceOptions: string;
+    /** The questions changed while the visitor filled them. */
+    definitionChanged: string;
+    rateLimited: string;
+    tryAgain: string;
+    notFound: string;
+    /** A multi-step form. */
+    next: string;
+    back: string;
+    stepOf: (step: number, of: number) => string;
+    /** A choice with nothing chosen yet. */
+    choose: string;
+    /** Beside a required question. */
+    required: string;
+    /** Shown while a phone number is not in the international format. */
+    phoneFormat: string;
+}
+export declare const defaultFormLabels: FormLabels;
+/** The defaults with a site's changes on top. */
+export declare const formLabels: (labels?: Partial<FormLabels>) => FormLabels;

package/dist/labels.js

@@ -0,0 +1,22 @@
+export const defaultFormLabels = {
+    submit: "Submit",
+    submitting: "Sending…",
+    thanks: "Thanks. Your message has been received.",
+    score: (score) => `Your score: ${score}`,
+    loadError: "This form could not be loaded.",
+    submitFailed: "Your message could not be sent.",
+    previewOnly: "This is a preview: submissions are not sent.",
+    noServiceOptions: "This form cannot be sent right now.",
+    definitionChanged: "This form was updated. Please review your answers and send again.",
+    rateLimited: "Too many attempts. Please wait a moment and try again.",
+    tryAgain: "Try again",
+    notFound: "This form is not available.",
+    next: "Next",
+    back: "Back",
+    stepOf: (step, of) => `Step ${step} of ${of}`,
+    choose: "Choose…",
+    required: "required",
+    phoneFormat: "Use the international format, like +1 415 555 0132.",
+};
+/** The defaults with a site's changes on top. */
+export const formLabels = (labels) => (labels ? { ...defaultFormLabels, ...labels } : defaultFormLabels);

package/dist/phone.d.ts

@@ -0,0 +1,4 @@
+/** The platform takes phone numbers in E.164 (`+14155550132`): the visitor's
+ * spaces, dots, dashes and brackets are dropped and a `00` prefix becomes `+`. */
+export declare function normalizePhone(raw: string): string;
+export declare const isE164: (value: string) => boolean;

package/dist/phone.js

@@ -0,0 +1,7 @@
+/** The platform takes phone numbers in E.164 (`+14155550132`): the visitor's
+ * spaces, dots, dashes and brackets are dropped and a `00` prefix becomes `+`. */
+export function normalizePhone(raw) {
+    const trimmed = raw.trim().replace(/[\s().-]/g, "");
+    return trimmed.startsWith("00") ? `+${trimmed.slice(2)}` : trimmed;
+}
+export const isE164 = (value) => /^\+[1-9][0-9]{1,14}$/.test(value);

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+import type { DoanyClientLike } from "@doany-ai/app-core";
+/**
+ * A form as `@doany-ai/sdk` 0.3.0-alpha.2 returns it to the website — the
+ * fields this package reads. A real SDK client satisfies `FormsClient`.
+ */
+export type FormFieldType = "text" | "textarea" | "email" | "phone" | "number" | "date" | "select" | "multiselect" | "checkbox" | "scale" | "agreement" | "consent" | "hidden" | "statement" | "service";
+export interface FormOption {
+    value: string;
+    label: string;
+}
+export interface FormServiceOption extends FormOption {
+    service_mode: "booking" | "inquiry";
+}
+export interface FormField {
+    key: string;
+    type: FormFieldType;
+    label: string;
+    help?: string;
+    required?: boolean;
+    /** `radio` or `dropdown` for a choice; the default is a dropdown. */
+    control?: string;
+    validation?: {
+        min_length?: number;
+        max_length?: number;
+        min?: number;
+        max?: number;
+    };
+    options?: FormOption[];
+    selection?: "single" | "multiple";
+    resolved_options?: FormServiceOption[];
+    consent?: {
+        mode: "checkbox" | "on_submit";
+    };
+}
+export interface FormCompletion {
+    thank_you_message?: string;
+    redirect_url?: string;
+    cta?: {
+        label: string;
+        url: string;
+    };
+}
+export interface FormDefinition {
+    schema_version: number;
+    title: string;
+    description?: string;
+    fields: FormField[];
+    settings?: FormCompletion;
+}
+export interface FormAvailability {
+    can_submit: boolean;
+    reason: "preview_only" | "no_service_options" | null;
+    field_keys: string[];
+}
+export interface FormView {
+    id: string;
+    type: string;
+    definition_hash: string;
+    definition: FormDefinition;
+    availability: FormAvailability;
+}
+export type FormAnswers = Record<string, unknown>;
+export interface FormSubmitParams {
+    definition_hash: string;
+    answers: FormAnswers;
+    context?: {
+        page_path?: string;
+        referrer?: string;
+        utm?: Partial<Record<"source" | "medium" | "campaign" | "term" | "content", string>>;
+        language?: string;
+        timezone?: string;
+        source_service_id?: string;
+    };
+}
+export interface FormSubmitReceipt {
+    id: string;
+    submitted_at: string;
+    score: number | null;
+    outcome: {
+        key: string;
+        label: string;
+        description?: string;
+        cta?: {
+            label: string;
+            url: string;
+        };
+    } | null;
+    completion: FormCompletion | undefined;
+}
+/** The part of the SDK client this package calls. */
+export interface FormsClient extends DoanyClientLike {
+    forms: {
+        get(formId: string): Promise<FormView>;
+        submit(formId: string, params: FormSubmitParams, options?: {
+            idempotencyKey?: string;
+        }): Promise<FormSubmitReceipt>;
+    };
+}

package/dist/types.js

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

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@doany-ai/forms",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "description": "The business's forms on a Doany site: a form hook and a default component that renders a form's questions and submits the answers",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@doany-ai/app-core": "^0.1.0-alpha.0",
+    "@doany-ai/sdk": "^0.3.0-alpha.2",
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@doany-ai/sdk": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "lucide-react": "^0.475.0"
+  },
+  "devDependencies": {
+    "@doany-ai/app-core": "file:../doany-app-core",
+    "@doany-ai/sdk": "file:../doany-sdk",
+    "@tanstack/react-query": "^5.84.1",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
+    "@types/node": "^22.20.4",
+    "@types/react": "^18.2.66",
+    "@types/react-dom": "^18.2.22",
+    "jsdom": "^26.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.0"
+  },
+  "license": "MIT"
+}