flowlight/react/README.md

A lightweight command interface library with floating button, search functionality, and React integration

# FlowLight React Integration

This directory contains React components and hooks for integrating FlowLight into React applications.

## Installation

```bash
npm install flowlight
```

## Quick Start

### Basic Usage

```jsx
import { FlowLightProvider, useFlowLight } from 'flowlight/react';

function App() {
  return (
    <FlowLightProvider options={{ debug: true }}>
      <YourApp />
    </FlowLightProvider>
  );
}

function SearchComponent() {
  const { showSearch, isSearchVisible } = useFlowLight();
  
  return (
    <button onClick={showSearch}>
      Open Search ({isSearchVisible ? 'Open' : 'Closed'})
    </button>
  );
}
```

## Components

### FlowLightProvider

The main provider component that initializes FlowLight and provides context to child components.

```jsx
<FlowLightProvider options={{ debug: true, position: 'bottom-right' }}>
  <YourApp />
</FlowLightProvider>
```

**Props:**
- `options` (object) - FlowLight configuration options
- `children` (ReactNode) - Child components

### withFlowLight

Higher-order component for class components.

```jsx
import { withFlowLight } from 'flowlight/react';

class MyComponent extends React.Component {
  render() {
    const { showSearch, isSearchVisible } = this.props;
    return (
      <button onClick={showSearch}>
        Search
      </button>
    );
  }
}

export default withFlowLight(MyComponent);
```

## Hooks

### useFlowLight

Main hook for accessing FlowLight functionality.

```jsx
function MyComponent() {
  const {
    flowlight,        // FlowLight instance
    isReady,          // Whether FlowLight is initialized
    isSearchVisible,  // Current search visibility state
    error,            // Any error that occurred
    showSearch,       // Function to show search
    hideSearch,       // Function to hide search
    toggleSearch,     // Function to toggle search
    updateOptions,    // Function to update options
    getSearchState,   // Function to get current state
    destroy           // Function to destroy FlowLight
  } = useFlowLight();

  if (!isReady) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <button onClick={toggleSearch}>
        {isSearchVisible ? 'Hide' : 'Show'} Search
      </button>
    </div>
  );
}
```

### useFlowvana (Deprecated)

Legacy hook name for backward compatibility.

```jsx
import { useFlowvana } from 'flowlight/react';

// This will show a deprecation warning
const flowlightProps = useFlowvana();
```

## Configuration Options

```jsx
const options = {
  debug: false,                    // Enable debug mode
  position: 'bottom-right',        // Button position
  theme: 'auto'                    // Theme: 'light', 'dark', 'auto'
};

<FlowLightProvider options={options}>
  <App />
</FlowLightProvider>
```

## Event Handling

FlowLight provides an event bus for listening to state changes:

```jsx
function MyComponent() {
  const { flowlight } = useFlowLight();

  useEffect(() => {
    if (flowlight) {
      // Listen to search state changes
      flowlight.eventBus.on('search:shown', () => {
        console.log('Search is now visible');
      });

      flowlight.eventBus.on('search:hidden', () => {
        console.log('Search is now hidden');
      });
    }
  }, [flowlight]);

  return <div>My Component</div>;
}
```

## Error Handling

```jsx
function App() {
  const { error, isReady } = useFlowLight();

  if (error) {
    return (
      <div className="error">
        Failed to initialize FlowLight: {error.message}
      </div>
    );
  }

  if (!isReady) {
    return <div>Initializing FlowLight...</div>;
  }

  return <YourApp />;
}
```

## Multiple Providers

FlowLight uses a global instance, so multiple providers will share the same instance:

```jsx
// Both providers will use the same FlowLight instance
<FlowLightProvider options={{ debug: true }}>
  <Component1 />
</FlowLightProvider>

<FlowLightProvider options={{ position: 'top-left' }}>
  <Component2 />
</FlowLightProvider>
```

## TypeScript Support

Full TypeScript support is included:

```tsx
import { FlowLightProvider, useFlowLight, FlowLightOptions } from 'flowlight/react';

const options: FlowLightOptions = {
  debug: true,
  position: 'bottom-right'
};

function MyComponent() {
  const { showSearch, isSearchVisible } = useFlowLight(options);
  // TypeScript will provide full type checking
}
```

## Keyboard Shortcuts

FlowLight automatically handles these keyboard shortcuts:

- `Ctrl/Cmd + K` - Toggle search interface
- `Escape` - Close search interface
- `Tab` - Navigate search results

## Examples

See the main package README for complete examples and usage patterns.