{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "newsletter-signup", "title": "Newsletter Signup", "description": "An email capture band driven by a real submit state machine: zod validation, a duplicate-submit guard, a role=status confirmation, an idempotent already-subscribed branch, and a failure that keeps the address you typed.", "dependencies": [ "zod", "lucide-react" ], "registryDependencies": [ "utils" ], "files": [ { "path": "src/registry/blocks/newsletter-signup.tsx", "content": "\"use client\"\n\nimport * as React from \"react\"\nimport { Check, LoaderCircle, Mail, MailCheck } from \"lucide-react\"\nimport { z } from \"zod\"\n\nimport { cn } from \"@/lib/utils\"\n\n/**\n * The single validation rule, exported so the host can run the identical check\n * server-side. zod owns validation on purpose: `type=\"email\"` is kept only for\n * the mobile keyboard, and the browser's own rule accepts `a@b` (no TLD) —\n * which every mail provider bounces. `noValidate` on the form keeps the two\n * from fighting over the same field.\n */\nexport const newsletterEmailSchema = z.email()\n\nexport type NewsletterSignupStatus = \"idle\" | \"submitting\" | \"success\" | \"already\" | \"error\"\n\nexport interface NewsletterSignupResult {\n /**\n * `\"already-subscribed\"` renders the idempotent variant of the confirmation\n * panel — a second signup is a success, not a failure.\n */\n status: \"subscribed\" | \"already-subscribed\"\n /** Server copy that replaces the built-in confirmation line, verbatim. */\n message?: string\n}\n\n/** A rejection that is not an Error still has to become a sentence a human can read. */\nfunction rejectionText(error: unknown, fallback: string): string {\n if (error instanceof Error && error.message) return error.message\n if (typeof error === \"string\" && error) return error\n return fallback\n}\n\nexport interface NewsletterSignupProps\n extends Omit, \"onSubmit\" | \"children\"> {\n /**\n * Receives the trimmed address and owns the network call — the block never\n * fetches anything itself. Resolve to confirm, resolve with\n * `{ status: \"already-subscribed\" }` for the idempotent notice, reject to\n * show a retryable error (an `Error`'s message is shown verbatim).\n */\n onSubmit: (email: string) => Promise\n /** Section heading; also the accessible name of the region. Pass `\"\"` to drop it. */\n heading?: string\n /** Optional line under the heading. */\n description?: string\n /** Seeds the field (a known address, an `?email=` query param). */\n defaultEmail?: string\n /** Accessible name of the input — visually hidden, because a placeholder is not a label. */\n emailLabel?: string\n placeholder?: string\n submitLabel?: string\n /** Button label while the promise is in flight. Default \"Subscribing…\". */\n pendingLabel?: string\n /** Button label after a rejection. Default \"Try again\". */\n retryLabel?: string\n /** Shown when the field is blank. */\n emptyMessage?: string\n /** Shown when zod rejects the format. */\n invalidMessage?: string\n /** Shown when the rejection carries no readable message of its own. */\n failureMessage?: string\n successTitle?: string\n successDescription?: string\n alreadyTitle?: string\n alreadyDescription?: string\n /** Returns the confirmation panel to an empty form. Default \"Use a different email\". */\n resetLabel?: string\n /** Fine print under the form — consent line, privacy link, cadence promise. */\n footnote?: React.ReactNode\n className?: string\n}\n\n/**\n * An email capture band whose real subject is the submit state machine:\n * `idle → submitting → success | already | error`, plus a field-level invalid\n * flash that never leaves `idle`.\n *\n * Three things make it shippable rather than decorative: a rejection keeps the\n * address the visitor typed, a repeated press cannot fire a second request, and\n * \"you are already subscribed\" reads as success instead of as an error.\n */\nexport const NewsletterSignup = React.forwardRef(\n (\n {\n onSubmit,\n heading = \"Subscribe to the newsletter\",\n description = \"One email a month with what shipped, what broke and what we learned.\",\n defaultEmail = \"\",\n emailLabel = \"Email address\",\n placeholder = \"you@example.com\",\n submitLabel = \"Subscribe\",\n pendingLabel = \"Subscribing…\",\n retryLabel = \"Try again\",\n emptyMessage = \"Enter your email address.\",\n invalidMessage = \"That doesn't look like an email address.\",\n failureMessage = \"We couldn't sign you up just now. Please try again.\",\n successTitle = \"You're on the list\",\n successDescription = \"Check your inbox for a confirmation email.\",\n alreadyTitle = \"You're already subscribed\",\n alreadyDescription = \"This address is on the list already — nothing else to do.\",\n resetLabel = \"Use a different email\",\n footnote,\n className,\n ...rest\n },\n forwardedRef,\n ) => {\n const baseId = React.useId()\n const headingId = `${baseId}-heading`\n const emailId = `${baseId}-email`\n const alertId = `${baseId}-alert`\n\n const inputRef = React.useRef(null)\n const mountedRef = React.useRef(false)\n // Flipped synchronously at the top of the handler. State cannot do this job:\n // several presses inside one tick would all read the same stale `status`.\n const pendingRef = React.useRef(false)\n // Set by the reset button, so the effect below knows the caret is owed a home.\n const refocusRef = React.useRef(false)\n\n const [email, setEmail] = React.useState(defaultEmail)\n const [submitted, setSubmitted] = React.useState(\"\")\n const [status, setStatus] = React.useState(\"idle\")\n const [message, setMessage] = React.useState(null)\n // Distinguishes \"the field is wrong\" (clears on the next keystroke) from\n // \"the request failed\" (survives editing, so the retry keeps its reason).\n const [invalid, setInvalid] = React.useState(false)\n\n // Latest-ref: consumers pass an inline arrow function, so this must never\n // sit in a dependency array.\n const onSubmitRef = React.useRef(onSubmit)\n React.useEffect(() => {\n onSubmitRef.current = onSubmit\n })\n\n React.useEffect(() => {\n // Set in the effect BODY, not only cleared in cleanup: StrictMode runs\n // mount → cleanup → mount in dev, so a ref that is merely cleared would\n // read false for the live instance and no submit would ever land.\n mountedRef.current = true\n return () => {\n mountedRef.current = false\n }\n }, [])\n\n React.useEffect(() => {\n if (status !== \"idle\" || !refocusRef.current) return\n refocusRef.current = false\n inputRef.current?.focus()\n }, [status])\n\n const busy = status === \"submitting\"\n const done = status === \"success\" || status === \"already\"\n\n const rejectField = (text: string) => {\n setInvalid(true)\n setMessage(text)\n // A stale network failure is superseded by a field problem: the button\n // must not keep offering \"Try again\" for something it can no longer send.\n setStatus(\"idle\")\n inputRef.current?.focus()\n }\n\n const handleSubmit = async (event: React.FormEvent) => {\n event.preventDefault()\n if (pendingRef.current) return\n\n const candidate = email.trim()\n if (candidate === \"\") {\n rejectField(emptyMessage)\n return\n }\n if (!newsletterEmailSchema.safeParse(candidate).success) {\n rejectField(invalidMessage)\n return\n }\n\n pendingRef.current = true\n setInvalid(false)\n setMessage(null)\n setStatus(\"submitting\")\n\n let result: NewsletterSignupResult | void\n try {\n result = await onSubmitRef.current(candidate)\n } catch (error) {\n pendingRef.current = false\n // Re-check liveness after the await: a late rejection landing on an\n // unmounted instance would setState on a dead component.\n if (!mountedRef.current) return\n setStatus(\"error\")\n setMessage(rejectionText(error, failureMessage))\n return\n }\n pendingRef.current = false\n if (!mountedRef.current) return\n setSubmitted(candidate)\n setMessage(result?.message ?? null)\n setStatus(result?.status === \"already-subscribed\" ? \"already\" : \"success\")\n }\n\n const startOver = () => {\n refocusRef.current = true\n setEmail(\"\")\n setSubmitted(\"\")\n setMessage(null)\n setInvalid(false)\n setStatus(\"idle\")\n }\n\n const buttonLabel = busy ? pendingLabel : status === \"error\" ? retryLabel : submitLabel\n\n return (\n \n
\n {/* Always mounted, so a transition is announced by a live region that\n already existed — one inserted at the same moment as its text is\n unreliable in most screen readers. It carries the pending label\n only; the confirmation panel below is its own role=\"status\", so\n nothing gets announced twice. */}\n \n {busy ? pendingLabel : \"\"}\n \n\n {heading || description ? (\n
\n {heading ? (\n

\n {heading}\n

\n ) : null}\n {description ? (\n

{description}

\n ) : null}\n
\n ) : null}\n\n {done ? (\n \n \n {status === \"success\" ? (\n \n ) : (\n \n )}\n \n
\n

\n {status === \"success\" ? successTitle : alreadyTitle}\n

\n

\n {message ?? (status === \"success\" ? successDescription : alreadyDescription)}\n

\n
\n {/* The exact address that was accepted: a confirmation that cannot\n say which inbox to check is not a confirmation. */}\n

\n {submitted}\n

\n \n {resetLabel}\n \n
\n ) : (\n /* A real
, not a button with an onClick: that is the\n only way Enter in the field submits, and it keeps the whole flow\n working with the mouse unplugged. */\n \n
\n \n
\n \n {\n setEmail(event.target.value)\n if (invalid) {\n setInvalid(false)\n setMessage(null)\n }\n }}\n placeholder={placeholder}\n ref={inputRef}\n required\n // Kept for the mobile keyboard only — zod is the validator.\n type=\"email\"\n value={email}\n />\n
\n {/* aria-disabled, never the native `disabled` attribute: the\n browser blurs a control the instant it becomes disabled, so a\n keyboard user who pressed Enter would be dumped on \n while the pending state is announced from nowhere. The\n handler's ref guard is what actually stops a second request. */}\n \n {busy ? (\n \n ) : null}\n {buttonLabel}\n \n
\n\n {message ? (\n \n {message}\n

\n ) : null}\n \n )}\n\n {footnote ?

{footnote}

: null}\n \n \n )\n },\n)\n\nNewsletterSignup.displayName = \"NewsletterSignup\"\n\nexport default NewsletterSignup\n", "type": "registry:block" } ], "type": "registry:block" }