flowlight/README.md

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

# FlowLight

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

## Features

- 🚀 **Lightweight** - Minimal bundle size with zero dependencies
- 🎯 **Floating Button** - Always accessible command interface
- 🔍 **Search Interface** - Powerful search with keyboard shortcuts
- ⚡ **React Integration** - Hooks and providers for React apps
- 🎨 **Customizable** - Easy to style and configure
- 📱 **Responsive** - Works on desktop and mobile

## Installation

```bash
npm install flowlight
```

## Quick Start

### Vanilla JavaScript

```javascript
import FlowLight from 'flowlight';

// Initialize FlowLight
const flowlight = new FlowLight({
  debug: true,
  position: 'bottom-right'
});

// Show the search interface
flowlight.showSearch();
```

### React

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

## API Reference

### FlowLight Constructor

```javascript
new FlowLight(options)
```

**Options:**
- `debug` (boolean) - Enable debug mode
- `position` (string) - Button position: 'top-left', 'top-right', 'bottom-left', 'bottom-right'
- `theme` (string) - Theme: 'light', 'dark', 'auto'

### Methods

- `showSearch()` - Show the search interface
- `hideSearch()` - Hide the search interface
- `toggleSearch()` - Toggle search visibility
- `updateOptions(options)` - Update configuration
- `destroy()` - Clean up and remove from DOM

### React Hooks

- `useFlowLight()` - Access FlowLight functionality
- `useFlowvana()` - Legacy hook (deprecated)

### React Components

- `FlowLightProvider` - Provider component for React apps
- `withFlowLight(Component)` - HOC for class components

## Keyboard Shortcuts

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

## Environment Configuration

FlowLight supports different API endpoints for development and production environments.

### Build-time Configuration

The library automatically uses the correct API endpoints based on the build environment:

- **Development**: `http://localhost:8000`
- **Production**: `https://api.flowvana.tech`

```bash
# Development build (default)
npm run build

# Production build
npm run build:prod
```

### Runtime Configuration

You can also configure the API base URL at runtime by setting a global configuration:

```javascript
// Set before initializing FlowLight
window.__FLOWLIGHT_CONFIG__ = {
  apiBaseUrl: 'https://your-custom-api.com'
};

// Then initialize FlowLight
const flowlight = new FlowLight();
```

### Environment Variables

For advanced configuration, you can set environment variables:

```bash
# Set API base URL
export API_BASE_URL=https://your-custom-api.com

# Build with custom configuration
NODE_ENV=production API_BASE_URL=https://your-custom-api.com npm run build
```

## Examples

See the `react/` directory for complete examples:
- `FlowvanaExample.js` - Full-featured React example
- `README.md` - Detailed React integration guide

## License

MIT