@searchwithaura/react-mention-textarea/README.md

A powerful React component for @ mentions with multi-layer navigation, search functionality, and custom action cards

# React Mention Textarea

A powerful React component for @ mentions with multi-layer navigation, search functionality, and custom action cards. Built with TypeScript and designed for Tailwind CSS.

## Features

- 🎯 **Smart Detection** - Automatically detects @ symbols and shows contextual menus
- 🔍 **Real-time Search** - Filter items as you type with fuzzy matching
- ⌨️ **Keyboard Navigation** - Full keyboard support (arrows, Enter, Escape, Tab)
- 📱 **Multi-layer Menus** - Navigate through nested menus with breadcrumb support
- ⚡ **Action Cards** - Custom action cards for complex interactions
- 🎨 **Customizable Themes** - Built-in light/dark mode support
- 🚀 **TypeScript First** - Full type definitions included
- 📦 **Zero Dependencies** - Only requires React as peer dependency
- 🔗 **Source-Aware** - Provides structured data for API integration

## Installation

### From GitHub Packages

```bash
npm install @rohan-krishna/react-mention-textarea
```

### From GitHub Repository

```bash
npm install github:rohan-krishna/react-mention-textarea
```

## Quick Start

```tsx
import React, { useState } from 'react';
import { MentionTextarea, MentionConfig } from '@rohan-krishna/react-mention-textarea';

const users = [
  { id: '1', label: 'John Doe', type: 'user', icon: '👤' },
  { id: '2', label: 'Jane Smith', type: 'user', icon: '👤' },
];

const mentions: MentionConfig[] = [
  {
    trigger: '@',
    data: users
  }
];

function App() {
  const [text, setText] = useState('');

  return (
    <MentionTextarea
      value={text}
      onChange={setText}
      mentions={mentions}
      placeholder="Type @ to mention someone..."
    />
  );
}
```

## Advanced Usage

### Multi-layer Navigation

```tsx
const multiLayerMentions: MentionConfig[] = [
  {
    trigger: '@',
    data: [
      {
        id: 'users',
        label: 'Users',
        icon: '👥',
        children: [
          { id: '1', label: 'John Doe', type: 'user' },
          { id: '2', label: 'Jane Smith', type: 'user' },
        ]
      },
      {
        id: 'actions',
        label: 'Actions',
        icon: '⚡',
        children: [
          {
            id: 'create_notion',
            label: 'Create Notion Page',
            component: 'NotionPageCard'
          }
        ]
      }
    ]
  }
];
```

### Multiple Triggers

```tsx
const advancedMentions: MentionConfig[] = [
  {
    trigger: '@',
    data: users
  },
  {
    trigger: '#',
    data: tags
  },
  {
    trigger: '/',
    data: commands
  }
];
```

### Custom Action Cards

```tsx
import { ActionCardProps } from '@rohan-krishna/react-mention-textarea';

const CustomActionCard: React.FC<ActionCardProps> = ({ item, onSubmit, onCancel }) => {
  const [title, setTitle] = useState('');

  const handleSubmit = () => {
    onSubmit(`[Custom: ${title}]`);
  };

  return (
    <div className="p-4">
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="Enter title..."
      />
      <button onClick={handleSubmit}>Submit</button>
      <button onClick={onCancel}>Cancel</button>
    </div>
  );
};
```

## API Reference

### MentionTextarea Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | - | Current textarea value |
| `onChange` | `(value: string) => void` | - | Value change handler |
| `mentions` | `MentionConfig[]` | - | Mention configurations |
| `placeholder` | `string` | `'Type @ to mention...'` | Textarea placeholder |
| `className` | `string` | `''` | Additional CSS classes |
| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Theme mode |
| `maxMenuHeight` | `number` | `300` | Maximum menu height in pixels |
| `disabled` | `boolean` | `false` | Disable the textarea |
| `rows` | `number` | `4` | Number of textarea rows |
| `autoFocus` | `boolean` | `false` | Auto-focus on mount |
| `onMentionSelect` | `(item: MentionItem, text: string) => void` | - | Mention selection callback |

### MentionConfig

```tsx
interface MentionConfig {
  trigger: string;                    // Trigger character (e.g., '@', '#')
  data: MentionItem[];               // Available items
  renderItem?: (item: MentionItem) => React.ReactNode;  // Custom item renderer
  onSelect?: (item: MentionItem) => string;             // Custom selection handler
  searchPlaceholder?: string;        // Search input placeholder
  maxResults?: number;               // Maximum results to show
}
```

### MentionItem

```tsx
interface MentionItem {
  id: string;                        // Unique identifier
  label: string;                     // Display text
  type?: 'user' | 'source' | 'action' | 'reference';  // Item type
  icon?: string;                     // Icon (emoji or text)
  avatar?: string;                   // Avatar image URL
  description?: string;              // Additional description
  children?: MentionItem[];          // Sub-items for navigation
  component?: string;                // Custom component name
  action?: (params?: any) => string | Promise<string>;  // Custom action
  metadata?: Record<string, any>;    // Additional data
}
```

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate through items |
| `Enter` | Select item or navigate to sub-menu |
| `←` | Navigate back to previous menu level |
| `Escape` | Close menu |
| `Tab` | Close menu and continue |

## Styling

The component is designed to work with Tailwind CSS. All styles use Tailwind classes and CSS custom properties for theming.

### Custom Themes

```tsx
<MentionTextarea
  theme="dark"
  className="custom-textarea"
  // ... other props
/>
```

### CSS Variables

```css
:root {
  --mention-bg: #ffffff;
  --mention-border: #e5e7eb;
  --mention-text: #111827;
  --mention-hover: #f3f4f6;
  --mention-selected: #dbeafe;
}

[data-theme="dark"] {
  --mention-bg: #1f2937;
  --mention-border: #374151;
  --mention-text: #f9fafb;
  --mention-hover: #374151;
  --mention-selected: #1e3a8a;
}
```

## Development

### Building the Package

```bash
cd components/mention-textarea
npm install
npm run build
```

### Publishing to GitHub Packages

See [PUBLISHING.md](./PUBLISHING.md) for detailed instructions.

### Using in Other Projects

```bash
npm install @rohan-krishna/react-mention-textarea
```

```tsx
import { MentionTextarea } from '@rohan-krishna/react-mention-textarea';
```

## Examples

Check out the demo in the main project to see all features in action:

- Basic @ mentions
- Multi-layer navigation
- Multiple triggers
- Custom action cards
- Keyboard navigation
- Search functionality

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 🐛 Issues: [GitHub Issues](https://github.com/rohan-krishna/react-mention-textarea/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/rohan-krishna/react-mention-textarea/discussions)
- � Package: [GitHub Packages](https://github.com/rohan-krishna/react-mention-textarea/packages)