# Signup Wizard

A three-page signup form on a single `/signup` route. A `signupDrafts` row keyed
by an app-generated client id holds the user's inputs and the step they have
reached. Each save rpc updates only its own columns and advances `step` to the
next one. A page refresh reloads the draft and renders the same step. The final
step collects the password, creates the user, deletes the draft, and signs the
user in.

The client id is minted once by the browser (`crypto.randomUUID()`), kept in
`localStorage`, and passed explicitly to every rpc as the draft key. A session
in Elements exists only after login, so anonymous draft state cannot hang off
the session. The app owns the key instead. See the note at the end.

The wizard does not depend on a single shared client-side form object. Each
step's rpc takes its own input shape and updates only the columns that belong to
that step. The template re-loads its inputs from the draft when it mounts, so
the only state that survives between reloads is the row in the database.

## Migration

```bash
elements create migration 'add users and signup drafts' -tables=users,signupDrafts
```

`app/migrations/<timestamp>-add-users-and-signup-drafts.migration.sql`:

```sql
-- add users and signup drafts

-- Auto-update updatedAt on row changes.
create or replace function touchUpdatedAt()
returns trigger
language plpgsql
as $$
begin
  new.updatedAt = now();
  return new;
end;
$$;

create table users (
  id uuid primary key default uuidGenerateV7(),
  createdAt timestamptz not null default now(),
  updatedAt timestamptz not null default now(),
  email text not null unique,
  handle text not null unique,
  passwordHash text not null,
  displayName text not null,
  bio text not null default ''
);

create trigger usersTouchUpdatedAt
  before update on users
  for each row execute function touchUpdatedAt();

create type signupStep as enum ('account', 'profile', 'review');

create table signupDrafts (
  id uuid primary key default uuidGenerateV7(),
  createdAt timestamptz not null default now(),
  updatedAt timestamptz not null default now(),
  expiresAt timestamptz not null default (now() + interval '24 hours'),
  clientId text not null unique,
  step signupStep not null default 'account',
  email text not null default '',
  handle text not null default '',
  displayName text not null default '',
  bio text not null default ''
);

create trigger signupDraftsTouchUpdatedAt
  before update on signupDrafts
  for each row execute function touchUpdatedAt();
```

The `signupStep` Postgres enum gives the column ordered values:
`'account' < 'profile' < 'review'`. Each save rpc uses
`greatest(step, '<next-step>'::signupStep)` to advance the step to its own next
value without ever regressing a user who has reached a later stage. The password
column lives only on `users` and is collected on the final step, so a
half-completed signup never leaves credentials in the database.

`signupDrafts.clientId` is the app-generated id the browser passes on every rpc.
The unique constraint enforces one in-progress draft per browser.

## Page setup

```bash
elements create page signup
```

The page scaffold writes
`app/pages/signup/{index.ts, template.html, style.css, test.ts}`. Add a
`services.ts` sibling by hand for the rpc functions and the shared interfaces
both `index.ts` and `template.html` need. The route only checks whether the visitor is already
signed in; the draft is loaded by the template on mount via an rpc, so the
server never needs the client id.

`app/pages/signup/services.ts`:

```ts
import { sql, session, ValidationError, FieldErrors } from "@elements/app";

export type Step = "account" | "profile" | "review";

export interface Draft {
  id: string;
  step: Step;
  email: string;
  handle: string;
  displayName: string;
  bio: string;
}

export interface AccountInput {
  email: string;
  handle: string;
}

export interface ProfileInput {
  displayName: string;
  bio: string;
}

export interface ReviewInput {
  password: string;
}

export interface SignupFields {
  email: string;
  handle: string;
  displayName: string;
  password: string;
}

const STEP_ORDER: Step[] = ["account", "profile", "review"];

export function stepIndex(s: Step): number {
  return STEP_ORDER.indexOf(s);
}

/** @rpc */
export function loadOrCreateDraft(clientId: string): Draft {
  let existing = sql<Draft>(
    `select id, step, email, handle, displayName, bio from signupDrafts
     where clientId = ${clientId} and expiresAt > now()`,
  ).first();

  if (existing) {
    return existing;
  }

  return sql<Draft>(
    `insert into signupDrafts (clientId) values (${clientId})
     on conflict (clientId) do update set updatedAt = now()
     returning id, step, email, handle, displayName, bio`,
  ).firstOrThrow();
}

/** @rpc */
export function saveAccount(clientId: string, input: AccountInput): Draft {
  return sql<Draft>(
    `update signupDrafts
     set email = ${input.email}, handle = ${input.handle},
         step = greatest(step, 'profile'::signupStep)
     where clientId = ${clientId}
     returning id, step, email, handle, displayName, bio`,
  ).firstOrThrow();
}

/** @rpc */
export function saveProfile(clientId: string, input: ProfileInput): Draft {
  return sql<Draft>(
    `update signupDrafts
     set displayName = ${input.displayName}, bio = ${input.bio},
         step = greatest(step, 'review'::signupStep)
     where clientId = ${clientId}
     returning id, step, email, handle, displayName, bio`,
  ).firstOrThrow();
}

/** @rpc */
export function createAccount(clientId: string, input: ReviewInput) {
  let draft = sql<Draft>(
    `select id, step, email, handle, displayName, bio from signupDrafts where clientId = ${clientId}`,
  ).firstOrThrow();

  let errors: FieldErrors<SignupFields> = {};

  if (!draft.email.includes("@")) {
    errors.email = ["must be a valid email"];
  } else if (!sql(`select 1 from users where email = ${draft.email}`).empty()) {
    errors.email = ["already taken"];
  }

  if (!/^[a-z0-9_]+$/.test(draft.handle)) {
    errors.handle = ["letters, numbers, and underscores only"];
  } else if (!sql(`select 1 from users where handle = ${draft.handle}`).empty()) {
    errors.handle = ["already taken"];
  }

  if (!draft.displayName.trim()) {
    errors.displayName = ["required"];
  }

  if (input.password.length < 8) {
    errors.password = ["must be at least 8 characters"];
  }

  if (Object.keys(errors).length > 0) {
    throw new ValidationError(errors);
  }

  let user = sql<{ id: string }>(
    `insert into users (email, handle, passwordHash, displayName, bio)
     values (${draft.email}, ${draft.handle},
             crypt(${input.password}, genSalt('bf', 12)),
             ${draft.displayName}, ${draft.bio})
     returning id`,
  ).firstOrThrow();

  sql(`delete from signupDrafts where clientId = ${clientId}`);

  session.login({ userId: user.id, userName: draft.displayName });
}
```

Each save rpc takes the client id plus its own input type. Adding a fourth step
means a new column and a new input interface, not a reshape of an existing one.
The save rpc do not validate; light required-field checks happen in the browser
via `<input required>`. Format and uniqueness checks are reserved for
`createAccount`, so a reload of any earlier step never re-runs them.

`greatest(step, 'profile'::signupStep)` advances the step but never regresses
one. A user who reached `review`, went back to fix their email, and clicked
"next" stays at `step = 'review'`. The template uses that returned step to
navigate.

For live per-field validation (format on blur, availability check) layered on
top of these save rpc, see `elements man recipes form-validation`.

`app/pages/signup/index.ts`:

```ts
import { redirect, session } from "@elements/app";
import signup from "./template";

export default function route(req, res) {
  if (session.isLoggedIn()) {
    redirect("/");
    return;
  }

  return new signup();
}
```

The route only bounces a signed-in user to the home route so the wizard is never
visible after the account exists. Which step renders is decided on the client
after the draft loads.

`app/pages/signup/template.html`:

```html
import "./style.css";
import { ValidationError, FieldErrors, redirect } from "@elements/app";
import {
  Draft,
  Step,
  AccountInput,
  ProfileInput,
  ReviewInput,
  SignupFields,
  stepIndex,
  loadOrCreateDraft,
  saveAccount,
  saveProfile,
  createAccount,
} from "./services";

function getClientId(): string {
  let id = localStorage.getItem("signupClientId");

  if (!id) {
    id = crypto.randomUUID();
    localStorage.setItem("signupClientId", id);
  }

  return id;
}

function go(step: { value: Step }, to: Step) {
  step.value = to;
  history.replaceState(null, "", `/signup?step=${to}`);
}

function setup(
  clientId: { value: string },
  step: { value: Step },
  account: AccountInput,
  profile: ProfileInput,
) {
  let cid = getClientId();
  clientId.value = cid;

  let draft = loadOrCreateDraft(cid);
  account.email = draft.email;
  account.handle = draft.handle;
  profile.displayName = draft.displayName;
  profile.bio = draft.bio;

  let requested = new URLSearchParams(window.location.search).get("step") as Step | null;

  if (requested && stepIndex(requested) <= stepIndex(draft.step)) {
    step.value = requested;
  } else {
    step.value = draft.step;
  }
}

function submitAccount(clientId: { value: string }, step: { value: Step }, account: AccountInput) {
  let updated = saveAccount(clientId.value, account);
  go(step, updated.step);
}

function submitProfile(clientId: { value: string }, step: { value: Step }, profile: ProfileInput) {
  let updated = saveProfile(clientId.value, profile);
  go(step, updated.step);
}

function submitReview(
  clientId: { value: string },
  review: ReviewInput,
  errors: { value: FieldErrors<SignupFields> },
) {
  try {
    createAccount(clientId.value, review);
    redirect("/");
  } catch (err: any) {
    if (err instanceof ValidationError) {
      errors.value = err.errors;
    } else {
      throw err;
    }
  }
}

<html class="signup"
      (private clientId: { value: string } = { value: "" },
       private step: { value: Step } = { value: "account" },
       private account: AccountInput = { email: "", handle: "" },
       private profile: ProfileInput = { displayName: "", bio: "" },
       private review: ReviewInput = { password: "" },
       private errors: { value: FieldErrors<SignupFields> } = { value: {} })
      oninit={() => setup(clientId, step, account, profile)}>
  <p class="progress">step {step.value === "account" ? 1 : step.value === "profile" ? 2 : 3} of 3</p>

  <form e:if={step.value === "account"} onsubmit={() => submitAccount(clientId, step, account)}>
    <h1>create your account</h1>

    <div class="field">
      <label>email</label>
      <input type="email" value={account.email} required>
    </div>

    <div class="field">
      <label>handle</label>
      <input type="text" value={account.handle} required>
    </div>

    <button type="submit">next</button>
  </form>

  <form e:elseif={step.value === "profile"} onsubmit={() => submitProfile(clientId, step, profile)}>
    <h1>your profile</h1>

    <div class="field">
      <label>display name</label>
      <input type="text" value={profile.displayName} required>
    </div>

    <div class="field">
      <label>bio (optional)</label>
      <textarea value={profile.bio}/>
    </div>

    <button type="button" onclick={() => go(step, "account")}>back</button>
    <button type="submit">next</button>
  </form>

  <form e:else onsubmit={() => submitReview(clientId, review, errors)}>
    <h1>review and create</h1>

    <dl class="review">
      <dt>email</dt>        <dd>{account.email}</dd>
      <dt>handle</dt>       <dd>{account.handle}</dd>
      <dt>display name</dt> <dd>{profile.displayName}</dd>
      <dt>bio</dt>          <dd>{profile.bio || "(none)"}</dd>
    </dl>

    <p e:if={errors.value.email?.length} class="error">
      email: {errors.value.email[0]} (<button type="button" onclick={() => go(step, "account")}>fix</button>)
    </p>
    <p e:if={errors.value.handle?.length} class="error">
      handle: {errors.value.handle[0]} (<button type="button" onclick={() => go(step, "account")}>fix</button>)
    </p>
    <p e:if={errors.value.displayName?.length} class="error">
      display name: {errors.value.displayName[0]} (<button type="button" onclick={() => go(step, "profile")}>fix</button>)
    </p>

    <div class="field">
      <label>password</label>
      <input type="password"
             value={review.password}
             class={errors.value.password?.length && "is-error"}
             required>
      <p e:for={msg of errors.value.password ?? []} class="error">{msg}</p>
    </div>

    <button type="button" onclick={() => go(step, "profile")}>back</button>
    <button type="submit">create account</button>
  </form>
</html>
```

Structure to notice:

- `setup` runs on mount: it reads (or mints) the client id from `localStorage`,
  calls `loadOrCreateDraft` with it, and seeds the `account` and `profile`
  inputs from the returned draft by mutating those objects in place. The
  bindings on each step's inputs write back to those same objects. On submit,
  the matching save rpc is called with the client id and the matching input
  shape. Each input type is its own; the template never treats the form as one
  object.
- Each save handler navigates to the step returned by the rpc. Because the save
  rpc advances `step` via `greatest`, a user fixing an earlier field is routed
  back to whatever step they had reached, not bumped forward through every later
  step again.
- `clientId`, `step`, and `errors` are wrapped in `{ value: ... }` so a handler
  can reassign them (`step.value = ...`, `errors.value = err.errors`). Plain
  reassignment of a function parameter would not flow back to template state, so
  the wrapper gives the handler a reference it can mutate.
- `go` also mirrors the step into the URL with `history.replaceState`, so a
  refresh re-runs `setup`, reads `?step=` back, clamps it against the draft's
  saved step, and renders the same step with values pre-filled from the
  database.

## Routes

Register the page in `index.ts`:

```ts
import signup from "#app/pages/signup";

// ...
app.route("/signup", signup);
```

## Notes

- **Draft cleanup.** `expiresAt` is set to 24 hours from creation. A nightly
  cron job can run `delete from signupDrafts where expiresAt < now()` to reap
  abandoned drafts. Until then, the unique `clientId` constraint keeps storage
  bounded to one row per browser.
- **Password placement.** The password column lives only on `users`. Collecting
  it on the final step means a half-completed signup never leaves credentials in
  the database. Moving the password earlier would require either storing a hash
  in the draft or rehashing on every save.
- **Adding a step.** Add a value to the `signupStep` enum, add a column to
  `signupDrafts`, add a new input interface and rpc in `services.ts`, and add an
  `e:elseif` branch in the template. The other steps are not touched.
- **Per-step validation.** This recipe validates only on `createAccount`. To add
  live per-field feedback (format on blur, availability check), reuse the
  pattern from `elements man recipes form-validation`: pure validators imported
  by both the template and the save rpc, called from `onblur` on the relevant
  inputs.
- **Anonymous draft keying.** A session in Elements exists only after login, so
  there is no session id to key an in-progress signup on. The app mints its own
  key instead: `crypto.randomUUID()` stored in `localStorage`, passed to every
  draft rpc as an explicit `clientId` argument. It persists across reloads for
  that browser, so the draft row is reachable on every navigation, and it never
  touches session state.