### Quick Start: Ink Stepper Example

Source: https://archcorsair.github.io/ink-stepper/index

A minimal Ink Stepper example demonstrating a three-step wizard. It uses React and Ink components to render interactive steps in the terminal.

```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 />);
```

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

### Ink Stepper: Basic Stepper Component Setup

Source: https://archcorsair.github.io/ink-stepper/guide/basic-usage

The Stepper component orchestrates the flow of a multi-step interface. It requires an onComplete callback that triggers upon completion and an optional onCancel callback. The initialStep prop can be used to set the starting step.

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

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

### Install Ink Stepper via NPM

Source: https://archcorsair.github.io/ink-stepper/index

Installs the ink-stepper package using npm, pnpm, yarn, or bun. This is the primary method for adding the component to your project.

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

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

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

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

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

### Asynchronous Validation with Ink Stepper

Source: https://archcorsair.github.io/ink-stepper/guide/validation

Demonstrates asynchronous validation in Ink Stepper using a function or Promise passed to the `canProceed` prop. This is useful for operations like server-side checks. The example simulates a network delay and shows how to display a loading state using the `isValidating` context variable.

```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>
```

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

### Install Ink Stepper via JSR

Source: https://archcorsair.github.io/ink-stepper/index

Installs the ink-stepper package from JSR using npx, pnpm, yarn, or bun. This is an alternative package registry for JavaScript.

```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
```

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

### Step Component Usage Example in TSX

Source: https://archcorsair.github.io/ink-stepper/api/components

Demonstrates how to use the '<Step>' component in a React application with TypeScript. It shows how to define a step's name, set a conditional 'canProceed' prop based on a state variable, and render content within the step. The content can be a simple ReactNode or a function that provides access to context.

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

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

### Progress Context Interface (TS)

Source: https://archcorsair.github.io/ink-stepper/guide/customization

Defines the structure of the `ProgressContext` object passed to the `renderProgress` prop. It includes the current step index and an array of step statuses.

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

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

### Hide Progress Bar (TSX)

Source: https://archcorsair.github.io/ink-stepper/guide/customization

Completely hide 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>
```

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

### Custom Progress Bar Renderer (TSX)

Source: https://archcorsair.github.io/ink-stepper/guide/customization

Replace the default progress bar renderer with a custom function using the `renderProgress` prop. This offers full control over the progress bar's appearance.

```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>
```

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

### Customize Stepper Markers (TSX)

Source: https://archcorsair.github.io/ink-stepper/guide/customization

Change the symbols used for completed, current, and pending steps using the `markers` prop. This allows visual differentiation of step states in your CLI.

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

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

### Synchronous Validation with Ink Stepper

Source: https://archcorsair.github.io/ink-stepper/guide/validation

Implements synchronous validation for a step in Ink Stepper by passing a boolean value to the `canProceed` prop. This ensures that the user can only proceed if the condition (e.g., name length greater than 0) is met. The component uses React's `useState` hook to manage the input value.

```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>
  );
}
```

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

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

Source: https://archcorsair.github.io/ink-stepper/guide/controlled-mode

This snippet demonstrates how to use the `step` prop to control the active step in an Ink Stepper component. It utilizes React's `useState` hook to manage the `currentStep` state and updates it via the `onStepChange` callback. Ensure 'react' and 'ink-stepper' are installed.

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

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>
  );
}

```

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

### useStepperContext Hook

Source: https://archcorsair.github.io/ink-stepper/api/hooks

The `useStepperContext` hook provides access to the internal Stepper context. This is useful for building 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
```typescript
import { useStepperContext } from 'ink-stepper';

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

### Returns

- `StepperContextValue`: An object containing the Stepper's context. (See Types for detailed structure).
```

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

### StepContext Interface for Ink Stepper Navigation

Source: https://archcorsair.github.io/ink-stepper/api/types

The StepContext interface defines the available methods and properties for navigating through the stepper. It includes functions to move to the next/previous step, jump to a specific step, cancel the wizard, and provides information about the current step's status.

```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;
}
```

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

### useStepperInput Hook

Source: https://archcorsair.github.io/ink-stepper/api/hooks

The `useStepperInput` hook coordinates input focus with Stepper keyboard navigation. It is designed for use within custom input components to prevent 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
```typescript
import { useStepperInput } from 'ink-stepper';

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

### Returns

| Name | Type | Description |
|---|---|---|
| `disableNavigation` | `() => void` | Disables global Stepper navigation (Enter/Escape). |
| `enableNavigation` | `() => void` | Re-enables global Stepper navigation. |
| `isNavigationDisabled` | `boolean` | Current status of navigation. |
```

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

### Ink Stepper: Programmatic Step Navigation with Context

Source: https://archcorsair.github.io/ink-stepper/guide/basic-usage

Enables programmatic control over step navigation within an Ink Stepper. By using the function-as-child pattern on the Step component, you can access context like goNext, goBack, and isLast to implement custom navigation controls.

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

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

### ProgressContext Interface for Ink Stepper Progress

Source: https://archcorsair.github.io/ink-stepper/api/types

The ProgressContext interface provides information about the current progress within the stepper. It includes the current step index and an array of step metadata, indicating the name, completion status, and current status of each step.

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

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

### Ink Stepper: Defining a Step Component

Source: https://archcorsair.github.io/ink-stepper/guide/basic-usage

The Step component represents an individual page or stage within the Stepper. Each Step must have a unique 'name' prop, which is displayed in the progress bar. The content of the step is rendered as its children.

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

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

### Ink Stepper: useStepperContext Hook for Context Access

Source: https://archcorsair.github.io/ink-stepper/api/hooks

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

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

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

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

### Ink Stepper: Track Step Entry with onEnterStep

Source: https://archcorsair.github.io/ink-stepper/guide/lifecycle

The onEnterStep callback is executed when the active step in the Stepper component changes. It receives the index of the new step, enabling actions like analytics tracking or logging. This hook is synchronous and does not block navigation.

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

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

### Ink Stepper: useStepperInput Hook for Input Coordination

Source: https://archcorsair.github.io/ink-stepper/api/hooks

The `useStepperInput` hook from 'ink-stepper' is designed to synchronize input focus with Stepper keyboard navigation. It's essential for custom input components to avoid conflicts with the Stepper's built-in navigation controls. It returns functions to disable/enable navigation and a boolean to check the current navigation status.

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

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

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

### Ink Stepper: Validate and Save with onExitStep

Source: https://archcorsair.github.io/ink-stepper/guide/lifecycle

The onExitStep callback is triggered before leaving the current step, allowing for data validation, state saving, or cleanup operations. It can return a boolean or a Promise resolving to a boolean to control navigation. Returning false cancels the 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>
```

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

### Ink Stepper: Prevent Navigation with onExitStep returning false

Source: https://archcorsair.github.io/ink-stepper/guide/lifecycle

Navigation can be prevented by having the onExitStep callback return false or a Promise resolving to false. This is useful for conditional logic, such as preventing a user from leaving a step if a form is not yet valid. This affects both goNext() and goBack() actions.

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

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

### Disable Stepper Navigation with useStepperInput Hook (React/TypeScript)

Source: https://archcorsair.github.io/ink-stepper/guide/input-coordination

This snippet demonstrates how to use the `useStepperInput` hook from `ink-stepper` to manage keyboard input within custom components in an Ink Stepper CLI application. The `disableNavigation` and `enableNavigation` functions are called on component focus and blur events respectively, preventing the Stepper from interfering with component-specific input handling. This is crucial for interactive elements like text inputs.

```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()
      }}
    />
  );
}
```

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

### StepperMarkers Interface for Ink Stepper Customization

Source: https://archcorsair.github.io/ink-stepper/api/types

The StepperMarkers interface allows for the customization of the default progress bar markers in the Ink Stepper. You can define specific markers for completed, current, and pending steps, with default values provided if not specified.

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

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