Forms & Data Capture

// src/lib/optimizely/componentRegistry.ts
//
// initForms() is the whole registration: it registers the SDK's own OptiForms type
// schemas AND maps your components onto them. Nothing here is ever pushed - the
// types are already in the CMS after activation, and opti:push only globs
// src/components/**/*.tsx anyway.
//
// Import from react/server, NOT the package root. 3.0.0 exported it from both,
// which made the root entry pull in react (a peer dependency) and broke every
// standalone npx @optimizely/cms-cli call. 3.0.1 reverted that re-export.
import { initForms } from "@optimizely/cms-sdk/react/server";

initForms({
  container: OptiFormsContainer,
  textbox:   OptiFormsTextbox,
  textarea:  OptiFormsTextarea,
  selection: OptiFormsSelection,
  submit:    OptiFormsSubmit,
  // The SDK registers all ten element types whether or not you map one, and an
  // unmapped type renders a visible "No component found" box rather than nothing.
  // So map every one. Range shares the number component: the CMS models both as a
  // numeric field, and a slider with no configured bounds is worse than an input.
  number: OptiFormsNumber, range: OptiFormsNumber, url: OptiFormsUrl,
  choice: OptiFormsChoice, reset: OptiFormsReset,
});

// Order does not matter: initForms writes to lists the SDK keeps separate from
// initContentTypeRegistry / initReactComponentRegistry, so neither wipes the other.
initContentTypeRegistry([...yourOwnTypes]);
initReactComponentRegistry({ resolver: yourOwnResolver });

// Native Optimizely Forms types - no contentType() needed. The SDK ships their
// schemas and initForms() registers them, so a field component is only ever the
// markup: useFormField does the naming, validation and rule visibility.

// src/components/blocks/OptiFormsTextbox/index.tsx - "use client"
export default function OptiFormsTextbox(props) {
  const data = props.content ?? props;
  const validators = toValidators(data.Validators);   // Graph returns JSON, not a string

  const { fieldProps, isRequired, errors, showErrors, errorProps } = useFormField({
    content: asFieldContent(data),
    name: fieldName(data),                            // slugify(getFieldName(data))
    validators,
  });

  // EmailValidator -> type="email", RegularExpressionValidator -> pattern="..."
  const { type, ...validationAttrs } = getHtmlValidationAttributes(validators);

  return (
    <FormElement content={data}>                      {/* dependency rules can hide it */}
      <label htmlFor={fieldProps.id}>{data.Label}{isRequired && " *"}</label>
      <input {...fieldProps} {...validationAttrs} type={type ?? "text"} />
      {showErrors && <p {...errorProps}>{errors[0]}</p>}
    </FormElement>
  );
}

// src/components/blocks/OptiFormsContainer/index.tsx - a SERVER component.
// It keeps its "use cache" Graph self-fetch (a referenced shared Form Container
// arrives without its scalar props) and renders the client shell around
// server-rendered children.

// Editors put Next / Previous / Submit wherever they like, often each in its own
// row. partitionFormNodes pulls them out at any depth and drops the rows left
// empty behind them, so they lay out as one footer however the form was authored.
const { content, buttons } = partitionFormNodes(nodes);
const steps = content.filter(n => n.nodeType === "step");

<FormShell action={...} steps={steps} rules={data.DependencyRules}>
  {steps.map((step, index) => (
    // OptimizelyGridSection has NO handler for nodeType "step" - it renders one as
    // a bare fragment, which is why every step used to show at once. Wrapping is
    // the consumer's job.
    <FormStep key={step.key} index={index} node={step}>
      <OptimizelyGridSection nodes={step.nodes} row={NodeWrapper} column={NodeWrapper} />
    </FormStep>
  ))}
  <OptimizelyGridSection nodes={buttons} row={NodeWrapper} column={NodeWrapper} />
</FormShell>

// @optimizely/cms-sdk/forms/validation - framework-free, usable on the server too.

isFieldRequired(validators)          // folds "requirevalidator" / "requiredvalidator"
validateField(value, validators)     // -> FormFieldError[], all seven validator types
getErrorMessages(errors)             // -> the editor's own ErrorMessage strings
getHtmlValidationAttributes(v)       // -> { required, type: "email", pattern, ... }
getFieldName(field)                  // SubmissionFieldName || Label - see the note below
getSelectionOptions(field)           // Options as an array, string form accepted too
toValidators(value)                  // Validators is unknown JSON; [] for a non-array

// extractValidatorType() lowercases and folds the naming variants, so you never
// compare raw CMS casing by hand. Verified against live Graph, a seeded form's
// Validators come back as:
//   [{ "type": "RequiredValidator", "errorMessage": "This field is required." },
//    { "type": "EmailValidator",    "errorMessage": "Please enter a valid email address." }]

// Multi-step forms. The composition nests one level deeper than a grid section:
//   section(layoutType:"form") > step > row > column > element
// The SDK probes whether a page holds a form and expands the composition to depth
// 8 when it does, leaving ordinary compositions at 4. Nothing to configure.

<FormWrapper steps={steps}>        // steps let rules resolve their jump targets
  <FormStep index={0} node={step}> // inactive steps stay mounted under display:none,
    ...fields                      // so values survive stepping back and submitting
  </FormStep>                      // validates every step, not just the visible one
</FormWrapper>

// Buttons carry no role property. Optimizely Forms has ONE button element for
// Next, Previous, Submit and Reset, told apart only by the label:
useFormButton(content)             // "next" -> next, "previous"/"back" -> previous,
                                   // anything else -> submit (case-insensitive)
useFormButton(content, { role: "reset" })   // reset has to be passed explicitly

// Dependency rules (OptiFormsDependencyRule) show and hide fields:
<FormRulesProvider rules={container.DependencyRules}>   // FormWrapper does this
  <FormElement content={field}>...</FormElement>        // each field opts in
// A field hidden by a rule is unregistered from validation, so a hidden required
// field cannot block submission. In edit mode it renders anyway, or an editor
// would be left with an empty selectable block.

// src/app/api/form-submit/route.ts
export async function POST(request: NextRequest) {
  // The SDK's createJsonSubmitHandler posts { targetUrl, payload, formKey } rather
  // than the field values on their own. The hand-built ContactFormBlock still posts
  // a flat object, so accept both and unwrap to the same shape.
  const { body, envelope } = unwrap(await request.json());
  // body = { full_name: "Jane", email: "jane@...", topic: "account", message: "..." }

  console.log("[Form Submission]", body);

  // Forwarded to Optimizely Data Platform as a customer event. Fire and forget:
  // a failure is warned and the route still returns 200, so a visitor's submission
  // never fails because ODP is down.
  await forwardToOdp(body).catch(err => console.warn(err));

  return NextResponse.json({ success: true, message: "...", received: body });
}

// forwardToOdp keys on email and fs_user_id - NOT vuid. OdpSetup stitches the FX
// visitor id into ODP under fs_user_id, so that is where the profile lives.

// src/components/blocks/ContactFormBlock/ContactForm.tsx - "use client"
// The hand-built alternative: a normal content type with normal properties, and a
// field list fixed in code rather than authored in the CMS.

const [values, setValues] = useState({ full_name: "", email: "", message: "" });

async function handleSubmit(e) {
  e.preventDefault();
  const res = await fetch(submitUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(values),          // flat body, no envelope
  });
  if (res.ok) { trackSubmit(...); identifyCustomer({ email: values.email }); }
}

// contentType({ key: "ContactFormBlock", properties: {
//   heading, intro, submitLabel, successMessage, submitUrl
// }})
// An editor controls the copy and the endpoint. They cannot add, remove, reorder
// or validate a field without a developer.

// The submit to ODP to FX loop:

// 1. User submits the form (email captured in body.email)

// 2. /api/form-submit POSTs to ODP as a customer event
//    ODP builds a customer profile: { email, logged_in: true, ... }

// 3. Next request: FX evaluates "cms_personalization" flag for this user
//    Audience condition: logged_in = true to variation "returning_users"

// 4. [[...slug]]/page.tsx passes a variation filter to Graph.
//    includeOriginal: true keeps a visitor who matches no variation served:
//    Graph returns the base version alongside any match. stored: false is
//    required with it - a Graph stored query template binds the variation
//    value of whichever request registered it, so every visitor would get
//    the first variation served.
const [page] = await client.getContentByPath(url, {
  variation: {
    include: "SOME",
    value: ["returning_users"],
    includeOriginal: true,
  },
  stored: false,
});

// 5. Graph returns the CMS variation an editor built in Visual Builder
//    specifically for logged-in / returning users
return <OptimizelyComponent content={page} />;