### Development Setup Commands

Source: https://github.com/chappy202/modal-manager/blob/master/CONTRIBUTING.md

Commands to set up the development environment for the Modal State Manager project, including installing dependencies and starting the development server.

```bash
pnpm install
pnpm dev
```

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

### Installation

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Instructions for installing the modal-manager package using npm, yarn, or pnpm.

```bash
npm install modal-manager
# or
yarn add modal-manager
# or
pnpm add modal-manager
```

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

### Conventional Commit Examples

Source: https://github.com/chappy202/modal-manager/blob/master/CONTRIBUTING.md

Examples of commit messages following the conventional commit format, used for automated versioning and changelog generation.

```bash
git commit -m "feat: add new transition animation"
git commit -m "fix: resolve issue with back navigation"
git commit -m "docs: update API documentation"
```

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

### Material UI Modal Integration

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Shows how to integrate the modal-manager with Material UI components. This example demonstrates using Material UI's `Dialog`, `DialogTitle`, `DialogContent`, and `DialogActions` to build a modal with navigation controls like 'Back', 'Next', and 'Finish'.

```tsx
import { useModal } from 'modal-manager';
import { Dialog, DialogTitle, DialogContent, DialogActions, Button } from '@mui/material';

function MaterialUIModal() {
  const { isOpen, open, close, currentStep, next, prev, isFirst, isLast } = useModal({
    id: 'mui-modal',
    steps: [{ id: 'step1' }, { id: 'step2' }]
  });

  return (
    <>
      <Button onClick={open}>Open Modal</Button>
      
      <Dialog open={isOpen} onClose={close}>
        <DialogTitle>
          {currentStep === 'step1' ? 'Step 1' : 'Step 2'}
        </DialogTitle>
        
        <DialogContent>
          {currentStep === 'step1' ? (
            <p>Content for step 1</p>
          ) : (
            <p>Content for step 2</p>
          )}
        </DialogContent>
        
        <DialogActions>
          {!isFirst && <Button onClick={prev}>Back</Button>}
          {!isLast ? (
            <Button onClick={next}>Next</Button>
          ) : (
            <Button onClick={close}>Finish</Button>
          )}
        </DialogActions>
      </Dialog>
    </>
  );
}

```

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

### Shadcn/UI Modal Integration

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Demonstrates how to integrate the modal-manager with Shadcn/UI components to create a multi-step modal experience. It shows how to open, close, and navigate between steps using the `useModal` hook.

```tsx
import { useModal } from 'modal-manager';
import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogFooter,
  Button
} from '@/components/ui';

function ShadcnModal() {
  const { isOpen, open, close, currentStep, next, prev, isFirst, isLast } = useModal({
    id: 'shadcn-modal',
    steps: [{ id: 'step1' }, { id: 'step2' }]
  });

  return (
    <>
      <Button onClick={open}>Open Modal</Button>
      
      <Dialog open={isOpen} onOpenChange={open => !open && close()}>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>
              {currentStep === 'step1' ? 'Step 1' : 'Step 2'}
            </DialogTitle>
          </DialogHeader>
          
          {currentStep === 'step1' ? (
            <p>Content for step 1</p>
          ) : (
            <p>Content for step 2</p>
          )}
          
          <DialogFooter>
            {!isFirst && <Button variant="outline" onClick={prev}>Back</Button>}
            {!isLast ? (
              <Button onClick={next}>Next</Button>
            ) : (
              <Button onClick={close}>Finish</Button>
            )}
          </DialogFooter>
        </DialogContent>
      </Dialog>
    </>
  );
}
```

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

### Modal Manager API Reference

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Provides a detailed reference for the `useModal` hook, outlining its returned state variables and action functions, as well as the configuration options for initializing the hook.

```APIDOC
useModal:
  // Initialization Options:
  id: string - Unique identifier for the modal.
  initialData?: object - Initial data for the modal (optional).
  steps?: array - Array of step objects (optional).

  // Returned State:
  isOpen: boolean - Whether the modal is open.
  currentStep: string | null - ID of the current step.
  currentStepIndex: number - Index of the current step.
  totalSteps: number - Total number of steps.
  data: Record<string, unknown> - Current modal data.
  isFirst: boolean - Whether the current step is the first step.
  isLast: boolean - Whether the current step is the last step.

  // Returned Actions:
  open: (data?: any) => void - Opens the modal with optional initial data.
  close: () => void - Closes the modal.
  next: (data?: any) => void - Goes to the next step with optional data.
  prev: () => void - Goes to the previous step.
  goTo: (stepId: string, data?: any) => void - Goes to a specific step with optional data.
  setData: (data: any) => void - Updates the modal data.
  addStep: (modalId: string, stepId: string, data?: any, previousStep?: string) => void - Adds or updates a step.
```

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

### API Reference: useModal Hook

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Details the `useModal` hook, its configuration options, and the returned values for managing modal state and navigation. This includes parameters for modal initialization and the functions/booleans provided for controlling the modal flow.

```APIDOC
useModal(options)
  - Initializes and manages the state of a multi-step modal.
  - Parameters:
    - options (object): Configuration for the modal.
      - id (string): A unique identifier for the modal instance.
      - steps (Array<object>): An array of step configurations. Each step object should have at least an 'id' property.
      - initialStep (string, optional): The ID of the step to display initially. Defaults to the first step.
      - onStepChange (function, optional): Callback function executed when the current step changes.
      - onModalOpen (function, optional): Callback function executed when the modal opens.
      - onModalClose (function, optional): Callback function executed when the modal closes.
  - Returns:
    - isOpen (boolean): Whether the modal is currently open.
    - open (function): Function to open the modal.
    - close (function): Function to close the modal.
    - currentStep (string | undefined): The ID of the currently displayed step.
    - next (function): Navigates to the next step in the sequence.
    - prev (function): Navigates to the previous step in the sequence.
    - goTo (function): Navigates to a specific step by its ID.
    - isFirst (boolean): True if the current step is the first step.
    - isLast (boolean): True if the current step is the last step.
    - stepData (object): An object to store and retrieve data associated with each step.
    - setStepData (function): Function to set data for a specific step.
    - getStepData (function): Function to get data for a specific step.

Example Usage:
const { isOpen, open, close, next, prev, currentStep, isFirst, isLast } = useModal({
  id: 'my-modal',
  steps: [{ id: 'welcome' }, { id: 'details' }, { id: 'confirm' }],
  initialStep: 'welcome'
});

```

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

### Basic Modal Usage

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Demonstrates how to set up and use the useModal hook to manage a multi-step modal in a React application. It includes opening, closing, and navigating between steps, along with rendering different step components.

```tsx
import { useModal, Step, StepRenderer } from 'modal-manager';
import { Dialog } from 'your-ui-library';

function MyModal() {
  const { isOpen, open, close, currentStep, next, prev, isFirst, isLast } = useModal({
    id: 'my-modal',
    steps: [
      { id: 'step1' },
      { id: 'step2' },
      { id: 'step3' },
    ]
  });

  return (
    <>
      <button onClick={open}>Open Modal</button>
      
      <Dialog open={isOpen} onClose={close}>
        <StepRenderer currentStep={currentStep}>
          <Step id="step1">
            <h2>Step 1</h2>
            <p>This is the first step</p>
          </Step>
          
          <Step id="step2">
            <h2>Step 2</h2>
            <p>This is the second step</p>
          </Step>
          
          <Step id="step3">
            <h2>Step 3</h2>
            <p>This is the final step</p>
          </Step>
        </StepRenderer>
        
        <div className="buttons">
          {!isFirst && <button onClick={prev}>Back</button>}
          {!isLast ? (
            <button onClick={next}>Next</button>
          ) : (
            <button onClick={close}>Finish</button>
          )}
        </div>
      </Dialog>
    </>
  );
}
```

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

### Branching and Committing Workflow

Source: https://github.com/chappy202/modal-manager/blob/master/CONTRIBUTING.md

Steps for contributing code, including forking, creating a new branch, making changes, running lint checks, committing with conventional messages, and pushing the branch.

```bash
git checkout -b feature/your-feature-name
pnpm lint
git commit -m "feat: add new transition animation"
git push origin feature/your-feature-name
```

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

### Release Commands

Source: https://github.com/chappy202/modal-manager/blob/master/CONTRIBUTING.md

Commands to trigger different types of releases (patch, minor, major) for the project, which are automated using standard-version and GitHub Actions.

```bash
pnpm release        # for patch release
pnpm release:minor  # for minor release
pnpm release:major  # for major release
```

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

### API Reference: StepRenderer and Step Components

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Documentation for the `StepRenderer` and `Step` components used to define and render individual steps within the modal. `StepRenderer` conditionally displays the current step, while `Step` components wrap the content for each step.

```APIDOC
StepRenderer({ currentStep, children })
  - Renders the appropriate child `Step` component based on the `currentStep` prop.
  - Props:
    - currentStep (string): The ID of the step to render.
    - children (ReactNode): The child `Step` components.

Step({ id, children })
  - A wrapper component for defining the content of a single modal step.
  - Props:
    - id (string): The unique identifier for this step, matching the IDs in the `useModal` configuration.
    - children (ReactNode): The content of the step.

Example Usage:
<StepRenderer currentStep={currentStep}>
  <Step id="welcome">
    <h1>Welcome!</h1>
    <p>Please provide your details.</p>
  </Step>
  <Step id="details">
    <h2>Details</h2>
    <input type="text" placeholder="Name" />
  </Step>
</StepRenderer>

```

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

### API Reference: ModalDebugger Component

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Information about the `ModalDebugger` component, which provides development-time insights into the modal's state, including the current step, available steps, and navigation history. It's intended for debugging purposes.

```APIDOC
ModalDebugger({ modalState })
  - A component that displays the current state of the modal for debugging purposes.
  - Props:
    - modalState (object): The state object returned by the `useModal` hook.

Example Usage:
{isOpen && <ModalDebugger modalState={{ isOpen, currentStep, ...otherStateProperties }} />}

```

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

### Conditional Steps and Branching Flows

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Demonstrates how to create complex modal flows where the next step is determined by user input or specific conditions. It utilizes the `useModal` hook to manage steps and navigation, including setting up relationships between steps using `addStep`.

```tsx
import { useModal, Step, StepRenderer } from 'modal-manager';
import { Dialog } from 'your-ui-library';

function PaymentModal() {
  const { 
    isOpen, 
    open, 
    close, 
    goTo, 
    setData, 
    data, 
    addStep, 
    currentStep, 
    prev 
  } = useModal({
    id: 'payment-modal',
    steps: [
      { id: 'method' },
      { id: 'card-details' },
      { id: 'bank-details' },
      { id: 'confirm' },
    ]
  });

  // Set up the step navigation relationships
  useEffect(() => {
    // Define the previous step for each conditional step
    addStep('payment-modal', 'card-details', {}, 'method');
    addStep('payment-modal', 'bank-details', {}, 'method');
    addStep('payment-modal', 'confirm', {}, data.paymentMethod === 'card' ? 'card-details' : 'bank-details');
  }, [addStep, data.paymentMethod]);

  const handlePaymentMethodSelect = (method) => {
    setData({ paymentMethod: method });
    
    // Go to the appropriate step based on payment method
    if (method === 'card') {
      goTo('card-details');
    } else if (method === 'bank') {
      goTo('bank-details');
    }
  };

  return (
    <>
      <button onClick={open}>Make Payment</button>
      
      <Dialog open={isOpen} onClose={close}>
        <StepRenderer currentStep={currentStep}>
          <Step id="method">
            <h2>Select Payment Method</h2>
            <button onClick={() => handlePaymentMethodSelect('card')}>Credit Card</button>
            <button onClick={() => handlePaymentMethodSelect('bank')}>Bank Transfer</button>
          </Step>
          
          <Step id="card-details">
            <h2>Enter Card Details</h2>
            {/* Card form */}
            <button onClick={() => prev()}>Back</button>
            <button onClick={() => goTo('confirm')}>Continue</button>
          </Step>
          
          <Step id="bank-details">
            <h2>Enter Bank Details</h2>
            {/* Bank form */}
            <button onClick={() => prev()}>Back</button>
            <button onClick={() => goTo('confirm')}>Continue</button>
          </Step>
          
          <Step id="confirm">
            <h2>Confirm Payment</h2>
            <p>Payment Method: {data.paymentMethod}</p>
            <button onClick={() => prev()}>Back</button>
            <button onClick={close}>Confirm</button>
          </Step>
        </StepRenderer>
      </Dialog>
    </>
  );
}

```

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

### Pushing Changes and Tags

Source: https://github.com/chappy202/modal-manager/blob/master/CONTRIBUTING.md

Command to push local changes and tags to the remote repository's main branch, typically after a release.

```bash
git push --follow-tags origin main
```

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

### ModalDebugger Component Props

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Details the available props for the `ModalDebugger` component, allowing customization of its position and initial visibility state.

```APIDOC
ModalDebugger:
  Props:
    position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' - The position of the debugger on the screen (defaults to 'bottom-right').
    initiallyOpen?: boolean - Whether the debugger should be open when the application loads (defaults to false).
```

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

### StepRenderer and Step Components

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Illustrates the usage of `StepRenderer` and `Step` components for conditionally rendering content based on the current modal step. `StepRenderer` takes the `currentStep` as a prop, and `Step` components are identified by their `id` prop.

```APIDOC
StepRenderer:
  Props:
    currentStep: string - The ID of the currently active step.

Step:
  Props:
    id: string - The unique identifier for this step.
    children: ReactNode - The content to render for this step.
```

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

### Smart Navigation History

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Explains the automatic navigation history tracking in modal-manager. It details how the library manages the back button functionality, prioritizing explicit `previousStep` definitions, then navigation history, and finally falling back to simple index decrement for intuitive user experience.

```javascript
// The library automatically tracks navigation history, making it easy to implement "Back" buttons that work intuitively even in complex flows:
// - When a user navigates forward, the current step is added to history
// - When a user navigates backward, the library uses:
//   1. The explicit `previousStep` if defined for the current step
//   2. The navigation history if available
//   3. Simple index decrement as a fallback
// This ensures users always return to the step they came from, even in non-linear flows.
```

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

### Modal Debugger Integration

Source: https://github.com/chappy202/modal-manager/blob/master/README.md

Shows how to include the `ModalDebugger` component in your application during development to inspect modal states. It's conditionally rendered only in development environments.

```tsx
import { ModalDebugger } from 'modal-manager';

function App() {
  return (
    <>
      {/* Your app components */}
      
      {process.env.NODE_ENV === 'development' && (
        <ModalDebugger position="bottom-right" />
      )}
    </>
  );
}
```

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