hooks.ts

Overview

The hooks.ts file provides a lightweight, reusable React hook utility designed to manage and synchronize authentication-related workflow steps with the URL's query parameters. It primarily facilitates switching between different user authentication states (such as Sign In, Sign Up, Forgot Password, etc.) by updating the step parameter in the URL using umi's useSearchParams hook. This enables deep linking and browser navigation support for different authentication views within a React application.

Detailed Explanation

Enum: Step

export enum Step {
  SignIn,
  SignUp,
  ForgotPassword,
  ResetPassword,
  VerifyEmail,
}

Description

The Step enum defines the possible states or steps in the authentication flow. Each member corresponds to a specific step or screen in the user authentication process.

• SignIn: Represents the sign-in step.

• SignUp: Represents the sign-up or registration step.

• ForgotPassword: Represents the "forgot password" recovery step.

• ResetPassword: Represents the password reset step.

• VerifyEmail: Represents the email verification step.

Usage Example

const currentStep = Step.SignIn;

This enum is used to strongly type the step parameter in the useSwitchStep hook.

Hook: useSwitchStep

export const useSwitchStep = (step: Step) => {
  const [_, setSearchParams] = useSearchParams();
  console.log('🚀 ~ useSwitchStep ~ _:', _);
  const switchStep = useCallback(() => {
    setSearchParams(new URLSearchParams({ step: step.toString() }));
  }, [setSearchParams, step]);

  return { switchStep };
};

Purpose

useSwitchStep is a custom React hook that returns a function to update the URL search parameter step to the specified authentication step. This allows the application to reflect the current authentication UI state in the URL, supporting direct linking and back/forward navigation.

Parameters

• step: Step — The target step to switch to, from the Step enum.

Returns

• An object containing:

  • switchStep: () => void — A function that, when called, updates the step query parameter in the URL to the specified step.

How It Works

• Uses useSearchParams from umi to get and set URL query parameters.

• Defines a memoized callback switchStep using useCallback that sets the URL parameter step to the string representation of the provided step.

• Returns the switchStep function, which can be invoked by any component to trigger the URL update.

Usage Example

import React from 'react';
import { Step, useSwitchStep } from './hooks';

const AuthNavigator = () => {
  const { switchStep } = useSwitchStep(Step.SignUp);

  return (
    <button onClick={switchStep}>
      Go to Sign Up
    </button>
  );
};

In this example, clicking the button updates the URL query parameter to ?step=1 (assuming SignUp corresponds to 1), signaling the app to show the Sign Up screen.

Implementation Details

• The hook leverages useSearchParams from the umi framework, which is an abstraction over the native browser URLSearchParams and React Router's location management.

• The step value is converted to a string using .toString() to ensure it is suitable for URL parameters.

• The switchStep function is memoized to avoid unnecessary re-creations on component re-renders unless step or setSearchParams changes.

• The hook logs the current search parameters to the console for debugging purposes (console.log), which could be removed or replaced with a more sophisticated logging mechanism in production.

Interaction with Other Parts of the System

• URL Query Parameters: The hook directly manipulates the URL query string, specifically the step parameter, to reflect the current authentication step.

• Routing and State Management: Other parts of the application—such as authentication components or pages—can read the step query parameter from the URL to decide which UI to render.

• umi Framework: This hook depends on umi's useSearchParams for handling URL parameters, making it specific to applications built with the umi framework (or compatible routing mechanisms).

• Authentication Pages/Components: Components responsible for rendering the different authentication steps (sign-in, sign-up, etc.) will likely use this hook or the step URL parameter to control their displayed content dynamically.

Summary

hooks.ts provides an enum and a custom hook for controlling authentication flow steps via URL query parameters. This design enhances navigation and state persistence by encoding the current step in the URL, enabling better user experience with browser navigation and direct linking capabilities.

Visual Diagram

flowchart TD
    A[useSwitchStep(step: Step)] --> B[useSearchParams()]
    A --> C[switchStep() callback]
    C --> D[setSearchParams(new URLSearchParams({ step }))]

    classDef hook fill:#f9f,stroke:#333,stroke-width:1px;
    class A hook;

Diagram Explanation:

• The useSwitchStep hook internally calls useSearchParams to gain access to URL parameter setters.

• It defines a switchStep callback function that updates the URL's step parameter to the specified authentication step.

• This flow illustrates the relationship between the hook, the internal useSearchParams hook, and the switchStep function used by components.

End of Documentation for hooks.ts