use-funnel

In @use-funnel, the context property is dynamically typed based on the current step. This means that as you narrow down the step using type guards (e.g., if (funnel.step === 'B')), the TypeScript compiler automatically knows the exact shape of funnel.context for that specific step.

This solves the problem of "leaky" state requirements where transitioning from Step A to Step B might require properties that were only relevant to Step A, or conversely, failing to provide properties required by Step B.

const funnel = useFunnel<{
  A: { a?: string; b?: string };
  B: { a: string; b?: string };
}>({
  id: "strongly-typed",
  initial: { step: "A" }
});

// When the step is "A", context.a is string | undefined
if (funnel.step === "A") {
  console.log(typeof funnel.context.a); // "string" | "undefined"
}

// When the step is "B", context.a is strictly string
if (funnel.step === "B") {
  console.log(typeof funnel.context.a); // "string"
}

The funnel.Render.overlay method allows you to display UI components like modals or bottom sheets while keeping the previous step visible in the background. This is useful for transient inputs that don't require a full screen transition.

When using an overlay, the render function provides a close method. If the overlay is closed via user interaction (e.g., clicking a backdrop or a cancel button) rather than the browser's back button, you must explicitly call close() to navigate the funnel history back to the previous step.

<funnel.Render
  PreviousStep={({ history }) => (
    <PreviousStep onNext={() => history.push('OverlayStep')} />
  )}
  OverlayStep={funnel.Render.overlay({
    render({ history, close }) {
      return (
        <MyModal
          onNext={(data) => history.push('NextStep', { data })}
          onClose={() => close()} // Explicitly call close() to navigate back in history
        />
      );
    }
  })}
/>

You can divide a complex funnel into smaller, manageable sub-funnels or reuse specific sequences of steps in different contexts. This is achieved by nesting a new funnel instance inside a step of a parent funnel.

To implement a sub-funnel:

1. Inside a component rendered by a parent funnel's step, call useFunnel() again.
2. Crucially, provide a unique id to the sub-funnel configuration to distinguish its history and state from the parent funnel.
3. Pass necessary data from the parent context to the sub-funnel via props, and use callbacks (like onNext) to communicate the sub-funnel's completion back to the parent funnel's history.

This approach allows for modularity and prevents the main funnel's type definition from becoming overly bloated with every intermediate step of a sub-process.

import { useFunnel } from '@use-funnel/react-router-dom';

// Parent Funnel
const mainFunnel = useFunnel({
  id: 'main-funnel',
  initial: { step: 'A' }
});

// Inside a step of the parent funnel (e.g., Step B)
// We render a component that manages its own sub-funnel
function BStep({ context }) {
  return <BSubFunnel a={context.a} onComplete={(val) => mainFunnel.history.push('C', { b: val })} />;
}

// Sub-funnel Component
function BSubFunnel({ a, onComplete }) {
  const subFunnel = useFunnel({
    id: 'b-funnel', // Unique ID is required
    initial: { step: 'B1' }
  });

  return subFunnel.Render({
    B1: ({ history }) => <button onClick={() => history.push('B2')}>Next</button>,
    // ... other steps
    B3: ({ context }) => <button onClick={() => onComplete(context.someValue)}>Finish Sub-funnel</button>
  });
}

The useFunnel hook allows you to define a multi-step workflow where each step has its own unique, strongly-typed context. This prevents common errors in manual state management where required properties for future steps are accidentally omitted or incorrectly typed during transitions.

When defining a funnel, you provide a generic object where keys are the step names and values are the shape of the context for that step. @use-funnel ensures that when you transition to a new step, you provide the exact context required by that step's definition.

const funnel = useFunnel<{
  A: { a?: string; b?: string };
  B: { a: string; b?: string };
}>({
  id: "strongly-typed",
  initial: {
    step: "A",
  }
});

// Type safety in action:
if (funnel.step === "A") {
  // Transitioning to B requires providing 'a' because it is required in step B's context
  funnel.history.push("B", { a: "some value" });
}

Transition events allow you to define and control how a funnel transitions from the current step to the next based on specific conditions or user actions. This is the recommended way to handle multiple paths (branching logic) within a single step, such as handling success vs. failure scenarios.

To implement transition events:

1. Define an events object within the step configuration passed to funnel.Render.with().
2. In the events object, map event names to handler functions. These handlers receive a payload and a history object, allowing you to call history.push() to navigate.
3. In the render function, use the provided dispatch function to trigger the defined events.

Important: Do not attempt to use history directly inside the render function. Always use dispatch('eventName', payload) to trigger the logic defined in your events object.

import { useFunnel } from "@use-funnel/next";

const funnel = useFunnel(/* ... */);

<funnel.Render
  EmailInput={funnel.Render.with({
    events: {
      // Email input success event
      EmailInputSuccess: (email: string, { history }) => {
        // Transition to the password input step
        history.push('PasswordInput', { email });
      },
      // Email input fail event
      EmailInputFail: (error: Error, { history }) => {
        // Transition to the error page
        history.push('ErrorPage', { error: error.message });
      }
    },
    render({ context, dispatch }) {
      return (
        <EmailInput
          email={context.email}
          // Dispatch EmailInputSuccess event when email input is successful
          onNext={(email) => dispatch('EmailInputSuccess', email)}
          // Dispatch EmailInputFail event when email input fails
          onError={(error) => dispatch('EmailInputFail', error)}
        />
      );
    }
  })}
/>