Forgot Password

Request a password-reset link by email, with a privacy-safe confirmation.

<!-- GENERATED FILE. Do not edit by hand. Source: components/help/content/. Run npm run gen:docs. -->

Purpose & Business Context

Forgot Password is the recovery on-ramp for anyone locked out of their account. Losing access mid-case is high-stakes in medical travel, so the flow is deliberately simple: one email field, one button, and a calm confirmation.

It is also written to avoid leaking who has an account. The confirmation says a link was sent 'if an account exists', which keeps the screen from confirming or denying any specific email, a small but important privacy and security choice.

Screen Overview

The shared split-screen auth layout. In its initial state the card shows a 'Forgot password' eyebrow, the title 'Reset your password', a short instruction, an email field, a Send reset link button, and a Back to sign in link.

After submitting, the card swaps to a success state: a mail icon, the message that a link was sent if an account exists for that email, an I have a reset link button to /reset, and the same Back to sign in link.

Controls & Components

• Email field: an email input with a mail icon; its value is echoed back in the confirmation message.
• Send reset link button: the primary submit; it switches the card into the success state.
• Back to sign in link: returns to /signin (present in both the form and success states).
• Success panel: a mail-icon mark plus the privacy-safe confirmation text (success state only).
• I have a reset link button: appears after submit and routes to /reset to enter a new password (success state only).

Field Definitions

• Email: Required email input (type=email), empty by default. Native email-format validation applies. Its value is stored and shown back in the confirmation ('we've sent a link to <email>'); if left blank in some path it falls back to the phrase 'that email'.
• Sent (state): Internal boolean, not a visible field. It starts false (form view) and flips to true on submit, replacing the form with the success panel. There is no real email dispatch in this prototype.

User Actions & Workflows

1. Enter the email tied to your account.
2. Press Send reset link.
3. Read the confirmation: a reset link has been sent if an account exists for that address.
4. Open the link from your inbox in a real deployment; in this demo, press I have a reset link to jump straight to /reset.
5. Or use Back to sign in if you remember your password after all.

Navigation & Relationships

Reached from: the Sign In screen's 'Forgot password?' link.

Leads to: /reset via the 'I have a reset link' button in the success state, and /signin via 'Back to sign in' in either state.

Pairs with: Reset Password (/reset), which is the destination where the new password is actually set. Together they form the two-step recovery flow.

Business Rules & Constraints

• The email field is required; the browser blocks an empty submit.
• The confirmation never reveals whether the email is registered; it always uses 'if an account exists', protecting account privacy.
• Submitting only toggles the view to the success state; no email is actually sent in this prototype.
• Back to sign in is available from both the form and the confirmation, so the user is never stranded.
• The reset link itself is not generated here; the success state simply links to /reset.

Data Dependencies

Fully self-contained: the screen holds local state for the typed email and the sent flag, and reads no shared data. In production the Send action would call a password-reset API and email a tokenised /reset link; here it just advances the local view.

• Local state: email (echoed in the confirmation), sent (toggles the view)
• No external data source or auth call on this screen

Error Handling & Edge Cases

• An empty or malformed email is caught by native validation before submit.
• If the email value is somehow empty when shown back, the confirmation degrades gracefully to 'that email'.
• The privacy-safe wording means an unknown email produces the same confirmation as a known one, by design.
• Re-rendering into the success state preserves the Back to sign in escape hatch.
• Mobile: the marketing panel is hidden, the card fills the width, and the floating Help button stays top-right.

User Roles & Permissions

• Public (no sign-in required): Anyone can request a reset; the screen never requires authentication.
• Patient or clinic (account owner): In production, only the real owner of the mailbox can act on the emailed link. Recovery is role-agnostic: the same flow serves patients and clinics, and the new password works at /signin for either.

Related Features & Functionalities

Sign In (/signin), which links here and is where recovered credentials are used, and Reset Password (/reset), the second half of the flow. The privacy-safe confirmation pattern mirrors the security posture used across the auth area. Shares the AuthShell and floating Help button.

Flow & Screenshots

flowchart LR
  SignIn[/signin/] -->|Forgot password| Forgot[Forgot Password]
  Forgot --> Email[Enter email]
  Email --> Send[Send reset link]
  Send --> Sent[If an account exists, link sent]
  Sent -->|I have a reset link| Reset[/reset/]
  Forgot -->|Back to sign in| SignIn

Guided Walkthrough Steps

The in-app walkthrough for this screen has 4 steps (auto-advances every 5 seconds; Prev / Pause / Next; click outside to exit):

1. Your account email ([data-tour="forgot.email"])

Enter the email tied to your account. We will send a reset link to it, if an account exists for that address.

1. Send the link ([data-tour="forgot.submit"])

Press to request the reset link. The card then confirms a link has been sent, without revealing whether the email is registered.

1. Remembered it? ([data-tour="forgot.back"])

If your password comes back to you, head straight back to sign in from here. This link is available before and after sending.

1. Help is always here ([data-tour="topbar.help"])

Open this Help button on any screen for documentation, and press Play to replay a walkthrough like this one.