### Quick Start ink-stepper Example

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/index.md

A minimal example demonstrating how to use the ink-stepper component to create a three-step wizard. It utilizes React, Ink, and the Stepper and Step components.

```tsx
import React from 'react';
import { render, Text } from 'ink';
import { Stepper, Step } from 'ink-stepper';

function App() {
  return (
    <Stepper
      onComplete={() => console.log('All done!')}
      onCancel={() => console.log('Cancelled.')}
    >
      <Step name="Welcome">
        <Text>Welcome to the wizard! Press Enter to continue.</Text>
      </Step>

      <Step name="Info">
        <Text>This is step 2.</Text>
      </Step>

      <Step name="Finish">
        <Text>Ready to submit? Press Enter to finish.</Text>
      </Step>
    </Stepper>
  );
}

render(<App />);
```

--------------------------------

### Install ink-stepper using npm, jsr, pnpm, or bun

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Provides commands for installing the ink-stepper package using various package managers like npm, jsr, pnpm, and bun. Ensure you have the respective package manager installed.

```bash
# npm
npm install ink-stepper

# jsr
npx jsr add @archcorsair/ink-stepper

# pnpm
pnpm add ink-stepper

# bun
bun add ink-stepper
```

--------------------------------

### Install ink-stepper with NPM

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/index.md

Installs the ink-stepper package using various package managers. Supported managers include npm, pnpm, yarn, bun, and deno.

```bash
npm install ink-stepper
```

```bash
pnpm add ink-stepper
```

```bash
yarn add ink-stepper
```

```bash
bun add ink-stepper
```

```bash
deno add npm:ink-stepper
```

--------------------------------

### Basic Stepper Setup with Ink-Stepper

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

Demonstrates a simple multi-step wizard using ink-stepper with automatic progress tracking and keyboard navigation. It requires the 'ink-stepper' and 'ink' libraries. The wizard progresses through defined steps and handles completion or cancellation events.

```tsx
import { Stepper, Step } from "ink-stepper";
import { Text, Box } from "ink";
import { render } from "ink";

function App() {
  return (
    <Stepper
      onComplete={() => {
        console.log("Wizard completed!");
        process.exit(0);
      }}
      onCancel={() => {
        console.log("Wizard cancelled");
        process.exit(1);
      }}
    >
      <Step name="Welcome">
        <Box flexDirection="column">
          <Text>Welcome to the setup wizard!</Text>
          <Text color="gray">Press Enter to continue</Text>
        </Box>
      </Step>

      <Step name="Configuration">
        <Text>Configure your settings here</Text>
      </Step>

      <Step name="Review">
        <Text>Review your selections</Text>
      </Step>
    </Stepper>
  );
}

render(<App />);
```

--------------------------------

### Install ink-stepper with JSR

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/index.md

Installs the ink-stepper package from JSR using various package managers. Supported managers include npm, pnpm, yarn, bun, and deno.

```bash
npx jsr add @archcorsair/ink-stepper
```

```bash
pnpm i jsr:@archcorsair/ink-stepper
```

```bash
yarn add jsr:@archcorsair/ink-stepper
```

```bash
bunx jsr add @archcorsair/ink-stepper
```

```bash
deno add jsr:@archcorsair/ink-stepper
```

--------------------------------

### Example Usage of Step Component in React

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/api/components.md

Demonstrates how to use the `<Step>` component to define a single step within a stepper. It shows how to provide a name, content, and a condition to control step progression using the `canProceed` prop.

```tsx
<Step name="Verification" canProceed={isVerified}>
  <Text>Please verify your identity.</Text>
</Step>
```

--------------------------------

### Dynamic Step Rendering with Ink-Stepper (React/TSX)

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

This example demonstrates how to create a dynamic stepper where steps are conditionally rendered based on user selection or state. It utilizes React's useState hook to manage the visibility of steps and the 'ink-stepper' library for the Stepper and Step components. The example includes a wrapper component for grouping steps, conditional steps based on a boolean state, and dynamic steps based on an array of features.

```tsx
import { Stepper, Step } from "ink-stepper";
import { Text, Box } from "ink";
import { useState } from "react";

function DynamicWizard() {
  const [needsAdvanced, setNeedsAdvanced] = useState(false);
  const [features, setFeatures] = useState<string[]>([]);

  // Wrapper component for grouping steps
  const StepGroup = ({ children }: { children: React.ReactNode }) => {
    return <>{children}</>;
  };

  return (
    <Stepper onComplete={() => console.log({ features, needsAdvanced })}>
      <StepGroup>
        <Step name="Welcome">
          <Text>Welcome! Let's get started.</Text>
        </Step>

        <Step name="Mode">
          {({
            goNext
          }) => (
            <Box flexDirection="column">
              <Text>Select installation mode:</Text>
              <Text
                color="blue"
                onPress={() => {
                  setNeedsAdvanced(false);
                  goNext();
                }}
              >
                [ Basic ]
              </Text>
              <Text
                color="blue"
                onPress={() => {
                  setNeedsAdvanced(true);
                  goNext();
                }}
              >
                [ Advanced ]
              </Text>
            </Box>
          )}
        </Step>
      </StepGroup>

      {/* Conditional step - only shown for advanced mode */}
      {needsAdvanced && (
        <Step name="Advanced">
          <Text>Advanced configuration options...</Text>
        </Step>
      )}

      {/* Dynamic steps based on feature selection */}
      {features.includes("database") && (
        <Step name="Database">
          <Text>Configure database settings</Text>
        </Step>
      )}

      {features.includes("api") && (
        <Step name="API">
          <Text>Configure API endpoints</Text>
        </Step>
      )}

      <Step name="Review">
        <Box flexDirection="column">
          <Text>Review your selections:</Text>
          <Text>Mode: {needsAdvanced ? "Advanced" : "Basic"}</Text>
          <Text>Features: {features.join(", ") || "None"}</Text>
        </Box>
      </Step>
    </Stepper>
  );
}

```

--------------------------------

### Lifecycle Hooks with Ink Stepper

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

Utilize `onEnterStep` and `onExitStep` callbacks to execute logic during step transitions. This example demonstrates tracking analytics when entering a step and potentially saving drafts or showing confirmation dialogues when exiting a step.

```tsx
import { Stepper, Step } from "ink-stepper";
import { Text } from "ink";
import { useState } from "react";

function LifecycleExample() {
  const [drafts, setDrafts] = useState<Record<number, any>>({});
  const [analytics, setAnalytics] = useState<string[]>([]);

  const saveDraft = async (step: number) => {
    // Simulate saving draft data
    setDrafts(prev => ({ ...prev, [step]: { timestamp: Date.now() } }));
    await new Promise(resolve => setTimeout(resolve, 500));
  };

  const trackEvent = (step: number) => {
    setAnalytics(prev => [...prev, `entered_step_${step}`]);
  };

  const confirmLeaveWithChanges = async (step: number): Promise<boolean> => {
    // In real app, show confirmation dialog
    const hasUnsavedChanges = Math.random() > 0.5;

    if (hasUnsavedChanges) {
      console.log("Saving changes before leaving...");
      await saveDraft(step);
    }

    return true; // Allow navigation
  };

  return (
    <Stepper
      onComplete={() => console.log("Complete!", { drafts, analytics })}
      onEnterStep={trackEvent}
      onExitStep={confirmLeaveWithChanges}
      onStepChange={(step) => console.log("Step changed to:", step)}
    >
      <Step name="Page 1">
        <Text>First page with auto-save</Text>
      </Step>

      <Step name="Page 2">
        <Text>Second page with tracking</Text>
      </Step>

      <Step name="Page 3">
        <Text>Third page</Text>
      </Step>
    </Stepper>
  );
}

```

--------------------------------

### Synchronous Validation with canProceed in ink-stepper

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Shows how to implement synchronous validation for step navigation using the `canProceed` prop in ink-stepper. The example demonstrates disabling advancement until a condition (e.g., input field not empty) is met.

```tsx
import { useState } from "react";
import { Stepper, Step } from "ink-stepper";

function App() {
  const [isValid, setIsValid] = useState(false);

  return (
    <Stepper onComplete={handleComplete}>
      <Step name="Input" canProceed={isValid}>
        {(ctx) => (
          <TextInput
            onChange={(value) => setIsValid(value.length > 0)}
            onSubmit={ctx.goNext}
          />
        )}
      </Step>
    </Stepper>
  );
}
```

--------------------------------

### Stepper Component for Wizard Flow

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/basic-usage.md

The Stepper component orchestrates the wizard flow. It requires an onComplete callback that triggers when the user finishes the last step, and an onCancel callback for when the user cancels on the first step. An optional initialStep prop can set the starting step.

```tsx
<Stepper
  onComplete={() => process.exit(0)}
  onCancel={() => process.exit(1)}
>
  {/* Steps go here */}
</Stepper>
```

--------------------------------

### Synchronous Validation with Ink Stepper

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

Implement synchronous validation to control step progression using the `canProceed` prop. This example uses `ink-stepper` and `ink-text-input` to validate user input for name and email before allowing the user to proceed. It ensures that required fields are filled and email format is valid.

```tsx
import { Stepper, Step } from "ink-stepper";
import { Text, Box } from "ink";
import { useState } from "react";
import TextInput from "ink-text-input";

function UserInput() {
  const [name, setName] = useState("");
  const [email, setEmail] = useState("");

  const isValidEmail = (email: string) => {
    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
  };

  return (
    <Stepper onComplete={() => console.log({ name, email })}>
      <Step name="Name" canProceed={name.length > 0}>
        {({
          goNext
        }) => (
          <Box flexDirection="column">
            <Text>Enter your name:</Text>
            <TextInput
              value={name}
              onChange={setName}
              onSubmit={goNext}
            />
            {name.length === 0 && (
              <Text color="red">Name is required</Text>
            )}
          </Box>
        )}
      </Step>

      <Step name="Email" canProceed={isValidEmail(email)}>
        {({
          goNext
        }) => (
          <Box flexDirection="column">
            <Text>Enter your email:</Text>
            <TextInput
              value={email}
              onChange={setEmail}
              onSubmit={goNext}
            />
            {email && !isValidEmail(email) && (
              <Text color="red">Invalid email format</Text>
            )}
          </Box>
        )}
      </Step>

      <Step name="Review">
        <Box flexDirection="column">
          <Text>Name: {name}</Text>
          <Text>Email: {email}</Text>
        </Box>
      </Step>
    </Stepper>
  );
}

```

--------------------------------

### Asynchronous Validation with Ink Stepper

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

Handle asynchronous validation, such as server-side checks, with loading states using the `canProceed` prop and `isValidating` state. This example demonstrates how to check username availability with a simulated API call, showing a loading indicator during the check.

```tsx
import { Stepper, Step } from "ink-stepper";
import { Text, Box, Spinner } from "ink";
import { useState } from "react";
import TextInput from "ink-text-input";

function AsyncValidation() {
  const [username, setUsername] = useState("");

  const checkUsernameAvailable = async () => {
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 1500));

    const taken = ["admin", "root", "user"];
    return !taken.includes(username.toLowerCase());
  };

  return (
    <Stepper onComplete={() => console.log("Username:", username)}>
      <Step
        name="Username"
        canProceed={username.length > 0 ? checkUsernameAvailable : false}
      >
        {({
          goNext,
          isValidating
        }) => (
          <Box flexDirection="column">
            <Text>Choose a username:</Text>

            <TextInput
              value={username}
              onChange={setUsername}
              onSubmit={goNext}
            />

            {isValidating && (
              <Box marginTop={1}>
                <Spinner type="dots" />
                <Text> Checking availability...</Text>
              </Box>
            )}

            {!isValidating && username.length === 0 && (
              <Text color="red">Username cannot be empty</Text>
            )}
          </Box>
        )}
      </Step>

      <Step name="Complete">
        <Text color="green">Username "{username}" is available!</Text>
      </Step>
    </Stepper>
  );
}

```

--------------------------------

### Execute logic on entering a step using onEnterStep in React

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/lifecycle.md

The `onEnterStep` callback is triggered when the active step in the `Stepper` component changes. It receives the index of the new step and is useful for tracking navigation or triggering step-specific actions. This example logs the navigation and tracks a view in an analytics service.

```tsx
<Stepper
  onEnterStep={(stepIndex) => {
    console.log(`Navigated to step ${stepIndex}`);
    analytics.trackView(`step_${stepIndex}`);
  }}
>
  {/* ... */}
</Stepper>
```

--------------------------------

### Controlled Stepper Mode with External State Management in Ink

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

This example demonstrates how to use the controlled mode of `ink-stepper` to manage the stepper's current step externally. This is useful for integrating with external state management solutions or routing. The `step` prop controls the active step, and `onStepChange` allows the parent component to react to step changes. External buttons are provided to jump to specific steps and reset the stepper.

```tsx
import { Stepper, Step } from "ink-stepper";
import { Text, Box } from "ink";
import { useState, useEffect } from "react";

function ControlledStepper() {
  const [currentStep, setCurrentStep] = useState(0);
  const [history, setHistory] = useState<number[]>([0]);

  useEffect(() => {
    // Log step changes
    console.log("Current step:", currentStep);
  }, [currentStep]);

  const handleStepChange = (step: number) => {
    setCurrentStep(step);
    setHistory(prev => [...prev, step]);
  };

  // External navigation controls
  const jumpToReview = () => setCurrentStep(2);
  const resetToStart = () => setCurrentStep(0);

  return (
    <Box flexDirection="column">
      <Box marginBottom={1}>
        <Text color="blue" onPress={jumpToReview}>
          [Skip to Review]
        </Text>
        <Text> "</Text>
        <Text color="yellow" onPress={resetToStart}>
          [Reset]
        </Text>
      </Box>

      <Stepper
        step={currentStep}
        onStepChange={handleStepChange}
        onComplete={() => console.log("History:", history)}
      >
        <Step name="Intro">
          <Text>Introduction (externally controlled)</Text>
        </Step>

        <Step name="Setup">
          <Text>Setup configuration</Text>
        </Step>

        <Step name="Review">
          <Text>Review and finish</Text>
        </Step>
      </Stepper>

      <Box marginTop={1}>
        <Text color="gray">
          Navigation history: {history.join(" → ")}
        </Text>
      </Box>
    </Box>
  );
}
```

--------------------------------

### Control Ink Stepper State with `step` Prop (React)

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/controlled-mode.md

This React example demonstrates how to use the `step` prop to control the active step in the Ink Stepper component and the `onStepChange` callback to update the external state. It requires React's `useState` hook and the `Stepper` and `Step` components from 'ink-stepper'. The input is the current step index and the output is the updated step index via the callback.

```tsx
import { useState } from 'react';
import { Stepper, Step } from 'ink-stepper';

function App() {
  const [currentStep, setCurrentStep] = useState(0);

  return (
    <Stepper
      step={currentStep}
      onStepChange={(newStep) => {
        // You can intercept or modify the change here if needed
        setCurrentStep(newStep);
      }}
      onComplete={() => console.log('Done')}
    >
      <Step name="A"><Text>Step A</Text></Step>
      <Step name="B"><Text>Step B</Text></Step>
      <Step name="C"><Text>Step C</Text></Step>
    </Stepper>
  );
}

```

--------------------------------

### Coordinate Input with Ink Stepper in React (TypeScript)

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/input-coordination.md

This example demonstrates using the `useStepperInput` hook from `ink-stepper` within a custom component to disable Stepper navigation when the component has focus. This prevents accidental step changes when interacting with elements like `TextInput`. It uses `onFocus` to call `disableNavigation` and `onBlur` to call `enableNavigation`.

```tsx
import { useStepperInput } from 'ink-stepper';
import { TextInput } from 'ink-text-input'; // hypothetically
import { useState } from 'react';

function MyInput() {
  const { disableNavigation, enableNavigation } = useStepperInput();
  const [value, setValue] = useState('');

  return (
    <TextInput
      value={value}
      onChange={setValue}
      onFocus={disableNavigation} // Disable Stepper nav
      onBlur={enableNavigation}   // Re-enable Stepper nav
      onSubmit={() => {
        // Handle submission logic here
        // Then potentially manually trigger goNext()
      }}
    />
  );
}
```

--------------------------------

### Prevent navigation by returning false from onExitStep in React

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/lifecycle.md

Navigation can be cancelled by returning `false` from the `onExitStep` callback. This is useful for implementing validation checks, ensuring that a user cannot proceed to the next step until certain conditions are met. The example shows how to prevent navigation from step 0 if a form is not valid.

```tsx
<Stepper
  onExitStep={(step) => {
    if (step === 0 && !formIsValid) {
      console.log('Cannot leave step 0 yet!');
      return false;
    }
    return true;
  }}
>
  {/* ... */}
</Stepper>
```

--------------------------------

### Basic Usage of ink-stepper Component in React

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Demonstrates the fundamental usage of the Stepper and Step components from ink-stepper within a React application. It shows how to define steps, their names, and associated content, along with navigation callbacks.

```tsx
import { Stepper, Step } from "ink-stepper";
import { Text } from "ink";

function App() {
  return (
    <Stepper onComplete={() => process.exit(0)} onCancel={() => process.exit(1)}>
      <Step name="Theme">
        <ThemeSelector />
      </Step>
      <Step name="Directory" canProceed={pathIsValid}>
        {(ctx) => (
          <PathInput onConfirm={ctx.goNext} onBack={ctx.goBack} />
        )}
      </Step>
      <Step name="Review">
        {(ctx) => (
          <Review onBack={ctx.goBack} showFinish={ctx.isLast} />
        )}
      </Step>
    </Stepper>
  );
}
```

--------------------------------

### Step Context and Manual Navigation in Ink-Stepper

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

Illustrates how to use the render prop pattern within ink-stepper to access step context, including navigation functions (goNext, goBack) and step metadata (currentStep, totalSteps, isFirst, isLast). This allows for custom navigation logic and dynamic UI updates based on the wizard's state.

```tsx
import { Stepper, Step } from "ink-stepper";
import { Text, Box } from "ink";
import { useState } from "react";

function ThemeSelector() {
  const [theme, setTheme] = useState("dark");

  return (
    <Stepper onComplete={() => process.exit(0)}>
      <Step name="Theme">
        {({ goNext, goBack, currentStep, totalSteps, isFirst, isLast }) => (
          <Box flexDirection="column">
            <Text>
              Step {currentStep + 1} of {totalSteps}
            </Text>
            <Text>Select theme: {theme}</Text>

            <Box marginTop={1}>
              <Text
                color="blue"
                onPress={() => setTheme("dark")}
              >
                [ Dark ]
              </Text>
              <Text> </Text>
              <Text
                color="blue"
                onPress={() => setTheme("light")}
              >
                [ Light ]
              </Text>
            </Box>

            <Box marginTop={1}>
              {!isFirst && (
                <Text color="yellow" onPress={goBack}>
                  &lt; Back
                </Text>
              )}
              <Text> </Text>
              <Text color="green" onPress={goNext}>
                {isLast ? "Finish" : "Next >"}
              </Text>
            </Box>
          </Box>
        )}
      </Step>

      <Step name="Confirm">
        {({ goBack }) => (
          <Box flexDirection="column">
            <Text>You selected: {theme}</Text>
            <Text color="yellow" onPress={goBack}>
              &lt; Back to change
            </Text>
          </Box>
        )}
      </Step>
    </Stepper>
  );
}
```

--------------------------------

### Step Context for Manual Navigation

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/basic-usage.md

The Step component supports a function-as-child pattern to access StepContext, enabling programmatic control over navigation. This context provides functions like goNext, goBack, and goTo, along with status flags like isLast.

```tsx
<Step name="Manual Control">
  {({
    goNext,
    goBack,
    isLast,
  }) => (
    <Box flexDirection="column">
      <Text>Custom controls:</Text>
      <Text color="blue" onPress={goNext}>
        [ Next > ]
      </Text>
    </Box>
  )}
</Step>
```

--------------------------------

### Accessing Stepper Context with useStepperContext

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Demonstrates advanced usage by accessing the full stepper context using the `useStepperContext` hook. This provides access to `stepContext` and `currentStepId` for custom step content implementations.

```tsx
import { useStepperContext } from "ink-stepper";

function CustomStepContent() {
  const { stepContext, currentStepId } = useStepperContext();

  return (
    <Box>
      <Text>Step {stepContext.currentStep + 1}</Text>
      <Button onPress={stepContext.goNext}>Next</Button>
    </Box>
  );
}
```

--------------------------------

### Lifecycle Hooks in Ink-Stepper (onEnterStep, onExitStep)

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Illustrates the usage of `onEnterStep` and `onExitStep` lifecycle hooks in Ink-Stepper. These hooks allow executing logic when a user enters or exits a step, with `onExitStep` supporting asynchronous operations and navigation cancellation.

```tsx
<Stepper
  onComplete={handleComplete}
  onEnterStep={(step) => {
    analytics.track(`entered_step_${step}`);
  }}
  onExitStep={async (step) => {
    // Save draft before leaving
    await saveDraft(step);
    return true; // Allow navigation
  }}
>
  ...
</Stepper>
```

```tsx
<Stepper
  onComplete={handleComplete}
  onExitStep={(step) => {
    if (hasUnsavedChanges) {
      return confirm("Discard changes?");
    }
    return true;
  }}
>
  ...
</Stepper>
```

--------------------------------

### Ink-Stepper Exports: Components, Hooks, and Types

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Lists the main exports from the 'ink-stepper' library, including components (`Stepper`, `Step`), hooks (`useStepperContext`, `useStepperInput`), and various TypeScript types for props and context values.

```tsx
// Components
export { Stepper, Step } from "ink-stepper";

// Hooks
export { useStepperContext, useStepperInput } from "ink-stepper";

// Types
export type {
  StepperProps,
  StepProps,
  StepContext,
  ProgressContext,
  StepperMarkers,
  StepperContextValue,
  RegisteredStep,
  UseStepperInputReturn,
} from "ink-stepper";
```

--------------------------------

### StepContext Interface for ink-stepper

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Illustrates the StepContext interface provided by ink-stepper, detailing the available methods and properties for interacting with the current step. This context is passed to step content when using the render function pattern.

```typescript
interface StepContext {
  goNext: () => void;           // Navigate to next step (respects canProceed)
  goBack: () => void;           // Navigate to previous step
  goTo: (step: number) => void; // Jump to specific step (zero-based)
  cancel: () => void;           // Cancel the wizard
  currentStep: number;          // Current step index (zero-based)
  totalSteps: number;           // Total number of steps
  isFirst: boolean;             // Whether this is the first step
  isLast: boolean;              // Whether this is the last step
  isValidating: boolean;        // Whether async validation is in progress
}
```

--------------------------------

### Step Component Definition

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/basic-usage.md

The Step component defines individual pages within the stepper wizard. Each step must have a unique 'name' prop, which is displayed in the progress bar. Content for the step is placed as children of the Step component.

```tsx
<Step name="Configuration">
  <Text>Step content goes here.</Text>
</Step>
```

--------------------------------

### Customize Ink Stepper Progress Bar Rendering

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

Allows for custom visualization of stepper progress. Includes options for custom markers, a completely custom progress renderer function, or hiding the progress bar entirely. Dependencies include 'ink-stepper' and 'ink'.

```tsx
import { Stepper, Step } from "ink-stepper";
import { Text, Box } from "ink";
import type { ProgressContext } from "ink-stepper";

// Example 1: Custom markers
function CustomMarkersExample() {
  return (
    <Stepper
      onComplete={() => process.exit(0)}
      markers={{
        completed: "[✓]",
        current: "[→]",
        pending: "[ ]"
      }}
    >
      <Step name="Install">
        <Text>Installing dependencies...</Text>
      </Step>
      <Step name="Configure">
        <Text>Configuring settings...</Text>
      </Step>
      <Step name="Build">
        <Text>Building project...</Text>
      </Step>
    </Stepper>
  );
}

// Example 2: Completely custom progress renderer
function CustomProgressExample() {
  const renderProgress = ({ currentStep, steps }: ProgressContext) => {
    return (
      <Box flexDirection="column" marginBottom={1}>
        <Text bold>
          Progress: {currentStep + 1}/{steps.length}
        </Text>

        <Box>
          {steps.map((step, idx) => (
            <Box key={idx} marginRight={1}>
              {step.completed && <Text color="green">✓ {step.name}</Text>}
              {step.current && <Text color="blue" bold>→ {step.name}</Text>}
              {!step.completed && !step.current && (
                <Text color="gray">{step.name}</Text>
              )}
            </Box>
          ))}
        </Box>

        <Text color="gray">
          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
        </Text>
      </Box>
    );
  };

  return (
    <Stepper
      onComplete={() => process.exit(0)}
      renderProgress={renderProgress}
    >
      <Step name="Start">
        <Text>Getting started...</Text>
      </Step>
      <Step name="Middle">
        <Text>Processing...</Text>
      </Step>
      <Step name="End">
        <Text>Finishing up...</Text>
      </Step>
    </Stepper>
  );
}

// Example 3: Hide progress bar entirely
function NoProgressExample() {
  return (
    <Stepper
      onComplete={() => process.exit(0)}
      showProgress={false}
    >
      <Step name="Silent Step 1">
        <Text>No progress bar shown</Text>
      </Step>
      <Step name="Silent Step 2">
        <Text>Clean interface</Text>
      </Step>
    </Stepper>
  );
}

```

--------------------------------

### Async Validation in Ink-Stepper

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Demonstrates how to use asynchronous functions for server-side validation within a stepper step. The `isValidating` flag from `StepContext` is utilized to display loading states during validation.

```tsx
function App() {
  const validateEmail = async () => {
    const response = await fetch(`/api/validate?email=${email}`);
    return response.ok;
  };

  return (
    <Stepper onComplete={handleComplete}>
      <Step name="Email" canProceed={validateEmail}>
        {( { goNext, isValidating } ) => (
          <Box flexDirection="column">
            <TextInput value={email} onChange={setEmail} />
            {isValidating && <Text color="yellow">Validating...</Text>}
            <Button onPress={goNext} disabled={isValidating}>
              Continue
            </Button>
          </Box>
        )}
      </Step>
    </Stepper>
  );
}
```

--------------------------------

### Input Coordination with useStepperInput Hook

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Shows how to use the `useStepperInput` hook to prevent keyboard conflicts with stepper navigation. This is useful when inputs like `TextInput` are focused, disabling default navigation keys like Enter or Escape.

```tsx
import { useStepperInput } from "ink-stepper";

function EmailInput() {
  const { disableNavigation, enableNavigation } = useStepperInput();
  const [value, setValue] = useState("");

  return (
    <TextInput
      value={value}
      onChange={setValue}
      onFocus={disableNavigation}  // Disable Enter/Escape handling
      onBlur={enableNavigation}    // Re-enable when done
    />
  );
}
```

--------------------------------

### Integrate Custom Components with Ink Stepper Context

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

Enables building custom components that interact with the stepper's internal state, such as navigation buttons or step indicators. Utilizes the `useStepperContext` hook. Requires 'ink-stepper' and 'ink'.

```tsx
import { Stepper, Step, useStepperContext } from "ink-stepper";
import { Text, Box } from "ink";

function CustomNavigationButtons() {
  const { stepContext, currentStepId } = useStepperContext();

  if (!stepContext) return null;

  return (
    <Box marginTop={1} gap={1}>
      <Text
        color={stepContext.isFirst ? "gray" : "blue"}
        onPress={stepContext.isFirst ? undefined : stepContext.goBack}
      >
        ← Previous
      </Text>

      <Text color="gray">|</Text>

      <Text
        color="green"
        onPress={stepContext.goNext}
      >
        {stepContext.isLast ? "Finish" : "Next →"}
      </Text>

      <Text color="gray">|</Text>

      <Text
        color="red"
        onPress={stepContext.cancel}
      >
        Cancel
      </Text>
    </Box>
  );
}

function StepIndicator() {
  const { stepContext } = useStepperContext();

  if (!stepContext) return null;

  return (
    <Text color="cyan">
      Step {stepContext.currentStep + 1} of {stepContext.totalSteps}
      {stepContext.isValidating && " (validating...)"}
    </Text>
  );
}

function App() {
  return (
    <Stepper
      onComplete={() => console.log("Done!")}
      keyboardNav={false}  // Disable default keyboard nav
    >
      <Step name="Page 1">
        <Box flexDirection="column">
          <StepIndicator />
          <Text>Content for page 1</Text>
          <CustomNavigationButtons />
        </Box>
      </Step>

      <Step name="Page 2">
        <Box flexDirection="column">
          <StepIndicator />
          <Text>Content for page 2</Text>
          <CustomNavigationButtons />
        </Box>
      </Step>

      <Step name="Page 3">
        <Box flexDirection="column">
          <StepIndicator />
          <Text>Final page</Text>
          <CustomNavigationButtons />
        </Box>
      </Step>
    </Stepper>
  );
}

```

--------------------------------

### Controlled Mode with Step Prop

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Demonstrates how to control the stepper's current step externally using the `step` prop and update it via `onStepChange`. This is useful for integrating with external state management solutions.

```tsx
function App() {
  const [currentStep, setCurrentStep] = useState(0);

  return (
    <Stepper
      step={currentStep}
      onStepChange={setCurrentStep}
      onComplete={handleComplete}
    >
      <Step name="One">...</Step>
      <Step name="Two">...</Step>
    </Stepper>
  );
}
```

--------------------------------

### Wrapped and Nested Steps in Ink-Stepper

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Illustrates how `Step` components can be wrapped in custom components, fragments, or conditionally rendered. This allows for flexible structuring of stepper content.

```tsx
const StepGroup = ({ children }) => <>{children}</>;

<Stepper onComplete={handleComplete}>
  <StepGroup>
    <Step name="Wrapped">
      <Text>This works!</Text>
    </Step>
  </StepGroup>
  {showOptional && (
    <Step name="Optional">
      <Text>Conditional step</Text>
    </Step>
  )}
</Stepper>
```

--------------------------------

### ProgressContext Interface for ink-stepper

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Defines the ProgressContext interface used by ink-stepper for custom progress bar rendering. It provides information about the current step and the status of all steps.

```typescript
interface ProgressContext {
  currentStep: number;
  steps: Array<{
    name: string;
    completed: boolean;
    current: boolean;
  }>;
}
```

--------------------------------

### useStepperContext Hook

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/api/hooks.md

The `useStepperContext` hook provides access to the internal Stepper context. This is particularly useful for creating deeply nested components that require control over the wizard's state.

```APIDOC
## `useStepperContext` Hook

### Description
A hook to access the internal Stepper context. Useful for building deeply nested components that need to control the wizard.

### Usage
```tsx
import { useStepperContext } from 'ink-stepper';

const { stepContext, currentStepId } = useStepperContext();
```

### Returns
- `StepperContextValue` - An object containing the Stepper's internal context and current step ID. (Refer to Types for detailed structure).
```

--------------------------------

### useStepperInput Hook

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/api/hooks.md

The `useStepperInput` hook is designed to coordinate input focus with Stepper keyboard navigation. It is recommended for use within custom input components to avoid potential keyboard conflicts.

```APIDOC
## `useStepperInput` Hook

### Description
A hook for coordinating input focus with Stepper keyboard navigation. Use this in custom input components to prevent keyboard conflicts.

### Usage
```tsx
import { useStepperInput } from 'ink-stepper';

const { disableNavigation, enableNavigation, isNavigationDisabled } = useStepperInput();
```

### Returns
- **`disableNavigation`** (`() => void`) - Disables global Stepper navigation (Enter/Escape).
- **`enableNavigation`** (`() => void`) - Re-enables global Stepper navigation.
- **`isNavigationDisabled`** (`boolean`) - Current status of navigation.
```

--------------------------------

### StepContext Interface in TypeScript

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/api/types.md

Defines the context object passed to the render function of a `<Step>` component or accessible via `useStepperContext().stepContext`. It provides methods for navigating steps (goNext, goBack, goTo, cancel) and properties for the current step's state (currentStep, totalSteps, isFirst, isLast, isValidating).

```typescript
interface StepContext {
  /** Navigate to the next step (respects canProceed) */
  goNext: () => void;
  /** Navigate to the previous step */
  goBack: () => void;
  /** Jump to a specific step by index (zero-based) */
  goTo: (step: number) => void;
  /** Cancel the wizard (calls onCancel) */
  cancel: () => void;
  /** Current step index (zero-based) */
  currentStep: number;
  /** Total number of steps */
  totalSteps: number;
  /** Whether this is the first step */
  isFirst: boolean;
  /** Whether this is the last step */
  isLast: boolean;
  /** Whether async validation is in progress */
  isValidating: boolean;
}
```

--------------------------------

### useStepperContext Hook for Stepper State Access

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/api/hooks.md

The useStepperContext hook provides access to the internal Stepper context, which is valuable for creating deeply nested components that require control over the wizard's state. It returns the step context and the ID of the current step.

```tsx
import { useStepperContext } from 'ink-stepper';

const { stepContext, currentStepId } = useStepperContext();
```

--------------------------------

### ProgressContext Interface in TypeScript

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/api/types.md

Defines the context object passed to the `renderProgress` function. It includes the current step index and an array of step metadata, where each step indicates its name, completion status, and whether it's the current step.

```typescript
interface ProgressContext {
  /** Current step index (zero-based) */
  currentStep: number;
  /** Array of step metadata */
  steps: Array<{ 
    name: string;
    completed: boolean;
    current: boolean;
  }>;
}
```

--------------------------------

### Customizing Step Markers in Ink Stepper (React)

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/customization.md

Allows customization of symbols for completed, current, and pending steps using the `markers` prop. Defaults are provided if not explicitly set. This prop accepts an object with `completed`, `current`, and `pending` keys.

```tsx
<Stepper
  markers={{
    completed: '[x]',
    current: '[o]',
    pending: '[ ]'
  }}
  onComplete={handleComplete}>
  {/* ... */}
</Stepper>
```

--------------------------------

### Perform actions before exiting a step using onExitStep in React

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/lifecycle.md

The `onExitStep` callback is executed just before leaving the current step. It's ideal for tasks like data validation, saving state, or performing cleanup operations. The callback receives the index of the step being exited and can return a boolean to control navigation.

```tsx
<Stepper
  onExitStep={async (stepIndex) => {
    console.log(`Leaving step ${stepIndex}`);
    
    // Perform cleanup or save
    await saveData(stepIndex);

    // Return true to allow navigation, false to cancel
    return true; 
  }}
>
  {/* ... */}
</Stepper>
```

--------------------------------

### useStepperInput Hook for Input Focus Coordination

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/api/hooks.md

The useStepperInput hook is designed to coordinate input focus with Stepper keyboard navigation. It should be used within custom input components to prevent conflicts with the Stepper's global navigation keys (Enter/Escape). It returns functions to disable/enable navigation and a boolean indicating the current navigation state.

```tsx
import { useStepperInput } from 'ink-stepper';

const { disableNavigation, enableNavigation, isNavigationDisabled } = useStepperInput();
```

--------------------------------

### Synchronous Validation with Boolean

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/validation.md

Implement synchronous validation by passing a boolean value to the `canProceed` prop of the `<Step>` component. This immediately determines if the user can proceed, and navigation is blocked if the condition is false.

```tsx
function NameStep() {
  const [name, setName] = useState('');

  return (
    <Step name="Name" canProceed={name.length > 0}>
      <Text>Enter your name:</Text>
      <TextInput value={name} onChange={setName} />
      {name.length === 0 && <Text color="red">Name is required</Text>}
    </Step>
  );
}
```

--------------------------------

### Custom Progress Rendering in Ink Stepper (React)

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/customization.md

Provides complete control over the progress bar's appearance by replacing the default renderer with a custom function via the `renderProgress` prop. This function receives a `ProgressContext` object containing the current step and all steps' completion status.

```tsx
<Stepper
  renderProgress={({ currentStep, steps }) => (
    <Box flexDirection="column" marginBottom={1}>
      <Text>
        Step {currentStep + 1} of {steps.length}
      </Text>
      <Text color="green">
        {steps.map(s => s.completed ? '■' : '□').join(' ')}
      </Text>
    </Box>
  )}
  onComplete={handleComplete}>
  {/* ... */}
</Stepper>
```

--------------------------------

### Custom Progress Bar Renderer in Ink-Stepper

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Provides full control over the progress bar's rendering by supplying a custom `renderProgress` function. This function receives `currentStep` and `steps` information to display custom progress information.

```tsx
<Stepper
  onComplete={handleComplete}
  renderProgress={({ currentStep, steps }) => (
    <Text>
      Step {currentStep + 1} of {steps.length}: {steps[currentStep].name}
    </Text>
  )}
>
  ...
</Stepper>
```

--------------------------------

### Asynchronous Validation with Promise

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/validation.md

Enable asynchronous validation by providing a function to `canProceed` that returns a `Promise<boolean>`. This is ideal for server-side checks or simulating network requests. During validation, `isValidating` is set to true, and navigation is temporarily disabled.

```tsx
const checkServer = async () => {
  // simulate delay
  await new Promise(r => setTimeout(r, 1000));
  return true; 
};

<Step name="Server Check" canProceed={checkServer}>
  {({
    isValidating
  }) => (
    <Box>
      <Text>Checking server status...</Text>
      {isValidating && <Spinner />}
    </Box>
  )}
</Step>
```

--------------------------------

### Custom Progress Bar Markers in Ink-Stepper

Source: https://github.com/archcorsair/ink-stepper/blob/main/README.md

Shows how to customize the progress bar markers (completed, current, pending) without replacing the entire progress bar component. Default markers are `✓`, `●`, and `○`.

```tsx
<Stepper
  onComplete={handleComplete}
  markers={{ completed: "[X]", current: "[>]", pending: "[ ]" }}
>
  ...
</Stepper>
```

--------------------------------

### StepperMarkers Interface in TypeScript

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/api/types.md

Defines the configuration object for customizing the default progress bar markers in the Ink Stepper. It allows setting custom strings for completed, current, and pending steps, with default values provided.

```typescript
interface StepperMarkers {
  /** Marker for completed steps (default: ' ✓ ') */
  completed?: string;
  /** Marker for current step (default: '●') */
  current?: string;
  /** Marker for pending steps (default: '○') */
  pending?: string;
}
```

--------------------------------

### Prevent Input Conflicts with useStepperInput in Ink Stepper

Source: https://context7.com/archcorsair/ink-stepper/llms.txt

This snippet shows how to use the `useStepperInput` hook to disable stepper navigation when an interactive input element within a step is focused. This prevents accidental navigation (e.g., pressing Enter or Escape) while the user is typing. It requires the `ink-stepper` and `ink-text-input` libraries.

```tsx
import { Stepper, Step, useStepperInput } from "ink-stepper";
import { Text, Box } from "ink";
import { useState } from "react";
import TextInput from "ink-text-input";

function EmailStep() {
  const { disableNavigation, enableNavigation } = useStepperInput();
  const [email, setEmail] = useState("");

  return (
    <Box flexDirection="column">
      <Text>Enter your email:</Text>
      <TextInput
        value={email}
        onChange={setEmail}
        onFocus={disableNavigation}  // Disable Enter/Escape navigation
        onBlur={enableNavigation}     // Re-enable when done
      />
      <Text color="gray">
        Type your email and press Enter
      </Text>
    </Box>
  );
}

function App() {
  return (
    <Stepper onComplete={() => process.exit(0)}>
      <Step name="Email">
        <EmailStep />
      </Step>

      <Step name="Done">
        <Text color="green">Thank you!</Text>
      </Step>
    </Stepper>
  );
}
```

--------------------------------

### Hiding Progress Bar in Ink Stepper (React)

Source: https://github.com/archcorsair/ink-stepper/blob/main/docs/guide/customization.md

Allows the complete hiding of the progress bar by setting the `showProgress` prop to `false`. This is useful when a visual progress indicator is not desired.

```tsx
<Stepper showProgress={false} onComplete={handleComplete}>
  {/* ... */}
</Stepper>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.