@asafarim/react-dropdowns 1.7.0 → 1.8.0

package/README.md

@@ -1,101 +1,136 @@
 # @asafarim/react-dropdowns
 
-Comprehensive, accessible, and mobile-first dropdown components for React with TypeScript support.
+**Production-ready dropdown components for React** with full TypeScript support, accessibility, and mobile optimization. Built on ASafariM design tokens.
 
-## Features
+[Live Demo](https://alisafari-it.github.io/react-dropdowns/) • [GitHub](https://github.com/AliSafari-IT/react-dropdowns) • [npm](https://www.npmjs.com/package/@asafarim/react-dropdowns)
 
-- 🎯 **Comprehensive**: Multiple components for different use cases
-- ♿ **Accessible**: Full keyboard navigation and screen reader support
-- 📱 **Mobile-First**: Optimized for touch devices with responsive design
-- 🎨 **Themeable**: Uses ASafariM design tokens with dark theme support
-- 🔧 **TypeScript**: Full type safety and IntelliSense support
-- ⚡ **Performant**: Lightweight with minimal dependencies
-- 🎪 **Flexible**: Multiple placement options and customization
+---
 
-## Installation
+## ✨ Features
+
+- **🎯 Comprehensive** — Multiple components for different use cases (simple dropdowns, custom triggers, advanced menus)
+- **♿ Fully Accessible** — WCAG 2.1 compliant with keyboard navigation, screen reader support, and ARIA attributes
+- **📱 Mobile-First** — Touch-friendly, responsive design with automatic viewport adjustment
+- **🎨 Design Token Integration** — Seamless integration with ASafariM design tokens and dark mode support
+- **🔧 TypeScript** — Full type safety with IntelliSense and zero runtime overhead
+- **⚡ Performant** — Lightweight (~5KB gzipped) with minimal dependencies
+- **🎪 Flexible** — 12 placement options, 3 sizes, multiple button variants, and extensive customization
+
+---
+
+## 📦 Installation
+
+```bash
+pnpm add @asafarim/react-dropdowns
+```
+
+Or with your preferred package manager:
 
 ```bash
 npm install @asafarim/react-dropdowns
-# or
+or
 yarn add @asafarim/react-dropdowns
-# or
-pnpm add @asafarim/react-dropdowns
 ```
 
-## Quick Start
+Then import the styles in your app (in index.tsx or main.tsx):
+
+```tsx
+import '@asafarim/react-dropdowns/dist/dropdown.css';
+```
+
+---
+
+## 🚀 Quick Start
+
+The simplest way to get started with a basic dropdown menu:
 
 ```tsx
 import { Dropdown } from '@asafarim/react-dropdowns';
 import '@asafarim/react-dropdowns/dist/dropdown.css';
 
-function App() {
+export function App() {
   return (
     <Dropdown
       items={[
-        {
-          id: 'edit',
-          label: 'Edit',
-          onClick: () => console.log('Edit clicked')
-        },
-        {
-          id: 'delete',
-          label: 'Delete',
-          danger: true,
-          onClick: () => console.log('Delete clicked')
-        }
+        { id: 'edit', label: 'Edit', onClick: () => console.log('Edit') },
+        { id: 'delete', label: 'Delete', danger: true, onClick: () => console.log('Delete') }
       ]}
       placement="bottom-start"
     >
-      <button>Actions</button>
+      Actions
     </Dropdown>
   );
 }
 ```
 
-## Components
+That's it! The dropdown handles state, positioning, keyboard navigation, and accessibility automatically.
+
+---
+
+## 📚 Components
+
+### Dropdown (Recommended)
 
-### Dropdown
+The main component that combines trigger and menu functionality. Use this for most cases.
 
-The main dropdown component that combines trigger and menu functionality.
+**Features:**
+
+- Automatic state management
+- Built-in click-outside detection
+- Keyboard navigation (arrow keys, Enter, Escape)
+- Automatic menu positioning
+- Optional controlled state
+
+**Basic Usage:**
 
 ```tsx
 <Dropdown
   items={[
     {
-      id: 'option1',
-      label: 'Option 1',
-      icon: <Icon />,
-      onClick: () => {},
-      disabled: false,
-      danger: false
+      id: 'edit',
+      label: 'Edit',
+      icon: <Edit size={16} />,
+      onClick: () => handleEdit()
     },
-    { divider: true }, // Separator
     {
-      id: 'option2',
-      label: 'Option 2',
-      onClick: () => {}
+      id: 'delete',
+      label: 'Delete',
+      icon: <Trash2 size={16} />,
+      danger: true,
+      onClick: () => handleDelete()
     }
   ]}
+  placement="bottom-start"
+  size="md"
+>
+  Actions
+</Dropdown>
+```
+
+**With Controlled State:**
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<Dropdown
+  items={items}
   isOpen={isOpen}
   onToggle={setIsOpen}
   placement="bottom-start"
-  size="md"
-  disabled={false}
-  closeOnSelect={true}
 >
-  <button>Trigger</button>
+  Menu
 </Dropdown>
 ```
 
 ### DropdownItem
 
-Individual menu item component.
+Individual menu item component. Used inside `Dropdown` or `DropdownMenu`.
 
 ```tsx
 <DropdownItem
-  label="Edit Item"
-  icon={<EditIcon />}
-  onClick={() => {}}
+  label="Edit"
+  icon={<Edit size={16} />}
+  onClick={() => handleEdit()}
   disabled={false}
   danger={false}
 />
@@ -103,82 +138,182 @@ Individual menu item component.
 
 ### DropdownMenu
 
-Standalone menu component for custom implementations.
+Low-level menu component for advanced custom implementations. Use with `useDropdown` hook for full control.
+
+**When to use:**
+
+- Custom trigger designs (cards, images, etc.)
+- Complex menu layouts
+- Integration with other positioning libraries
+
+**Example:**
 
 ```tsx
-<DropdownMenu
-  isOpen={isOpen}
-  position={{ top: 100, left: 50 }}
-  size="md"
->
-  <DropdownItem label="Option 1" onClick={() => {}} />
-  <DropdownItem label="Option 2" onClick={() => {}} />
-</DropdownMenu>
+import { createPortal } from 'react-dom';
+import { DropdownMenu, DropdownItem, useDropdown, useClickOutside } from '@asafarim/react-dropdowns';
+
+function CustomDropdown() {
+  const { isOpen, position, toggle, triggerRef, menuRef, close } = useDropdown();
+  const containerRef = useRef(null);
+
+  useClickOutside({
+    ref: containerRef,
+    handler: close,
+    enabled: isOpen,
+    excludeRefs: [menuRef]
+  });
+
+  return (
+    <div ref={containerRef}>
+      <div ref={triggerRef} onClick={toggle} style={{ cursor: 'pointer' }}>
+        Click me
+      </div>
+
+      {isOpen && createPortal(
+        <DropdownMenu ref={menuRef} isOpen={isOpen} position={position}>
+          <DropdownItem label="Option 1" onClick={() => {}} />
+          <DropdownItem label="Option 2" onClick={() => {}} />
+        </DropdownMenu>,
+        document.body
+      )}
+    </div>
+  );
+}
 ```
 
-## Props
+---
 
-### DropdownProps
+## 🎛️ Props Reference
+
+### Dropdown Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children` | `ReactNode` | - | Trigger element |
-| `items` | `DropdownItemData[]` | `[]` | Menu items |
-| `isOpen` | `boolean` | - | Controlled open state |
-| `onToggle` | `(isOpen: boolean) => void` | - | Open state change handler |
-| `placement` | `DropdownPlacement` | `'bottom-start'` | Menu position |
-| `size` | `DropdownSize` | `'md'` | Menu size |
+| `children` | `ReactNode` | — | Trigger element content |
+| `items` | `DropdownItemData[]` | `[]` | Menu items to display |
+| `isOpen` | `boolean` | — | (Optional) Controlled open state |
+| `onToggle` | `(isOpen: boolean) => void` | — | (Optional) State change callback |
+| `placement` | `DropdownPlacement` | `'bottom-start'` | Menu position relative to trigger |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Menu size |
+| `variant` | `ButtonVariant` | `'primary'` | Trigger button style |
 | `disabled` | `boolean` | `false` | Disable the dropdown |
-| `closeOnSelect` | `boolean` | `true` | Close menu on item select |
+| `closeOnSelect` | `boolean` | `true` | Auto-close menu on item click |
+| `showChevron` | `boolean` | `true` | Show chevron icon on trigger |
+| `className` | `string` | — | Custom CSS class for wrapper |
+| `data-testid` | `string` | — | Test ID for testing |
 
-### DropdownItemData
+### DropdownItemData Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `id` | `string` | - | Unique identifier |
-| `label` | `string` | - | Item text |
-| `value` | `string` | - | Item value |
-| `icon` | `ReactNode` | - | Item icon |
+| `id` | `string` | — | Unique identifier |
+| `label` | `string` | — | Item display text |
+| `icon` | `ReactNode` | — | Icon to display before label |
+| `onClick` | `(event: MouseEvent) => void` | — | Click handler |
 | `disabled` | `boolean` | `false` | Disable the item |
-| `danger` | `boolean` | `false` | Danger styling |
-| `divider` | `boolean` | `false` | Render as divider |
-| `onClick` | `(event: MouseEvent) => void` | - | Click handler |
+| `danger` | `boolean` | `false` | Red danger styling |
+| `divider` | `boolean` | `false` | Render as visual separator |
+| `value` | `string` | — | Optional data value |
 
-## Placement Options
+### DropdownMenu Props
 
-The dropdown supports 12 different placement options:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | Menu content |
+| `isOpen` | `boolean` | — | Show/hide menu |
+| `position` | `DropdownPosition` | — | Absolute position (from `useDropdown`) |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Menu size |
+| `className` | `string` | — | Custom CSS class |
+| `ref` | `RefObject<HTMLDivElement>` | — | Menu element reference |
 
-- `top`, `top-start`, `top-end`
-- `bottom`, `bottom-start`, `bottom-end`
-- `left`, `left-start`, `left-end`
-- `right`, `right-start`, `right-end`
+---
 
-## Size Options
+## 🎨 Customization
 
-Three size variants are available:
+### Placement Options
 
-- `sm` - Compact size for tight spaces
-- `md` - Default size for most use cases
-- `lg` - Large size for better touch targets
+Position the menu relative to the trigger:
 
-## Hooks
+```
+Top:        top | top-start | top-end
+Bottom:     bottom | bottom-start | bottom-end
+Left:       left | left-start | left-end
+Right:      right | right-start | right-end
+```
 
-### useDropdown
+```tsx
+<Dropdown items={items} placement="top-end">
+  Menu
+</Dropdown>
+```
 
-Custom hook for building dropdown functionality:
+### Size Options
 
 ```tsx
-import { useDropdown } from '@asafarim/react-dropdowns';
+<Dropdown items={items} size="sm">Compact</Dropdown>
+<Dropdown items={items} size="md">Default</Dropdown>
+<Dropdown items={items} size="lg">Large</Dropdown>
+```
+
+### Button Variants
+
+Style the trigger button:
+
+```tsx
+<Dropdown items={items} variant="primary">Primary</Dropdown>
+<Dropdown items={items} variant="secondary">Secondary</Dropdown>
+<Dropdown items={items} variant="ghost">Ghost</Dropdown>
+<Dropdown items={items} variant="outline">Outline</Dropdown>
+<Dropdown items={items} variant="danger">Danger</Dropdown>
+```
+
+### Custom Styling
+
+Override default styles using CSS classes:
+
+```css
+/* Menu container */
+.asm-dropdown-menu {
+  background: var(--asm-color-surface);
+  border: 1px solid var(--asm-color-border);
+}
+
+/* Menu item */
+.asm-dropdown-item {
+  padding: var(--asm-space-3);
+}
+
+/* Danger item */
+.asm-dropdown-item--danger {
+  color: var(--asm-color-danger);
+}
+
+/* Disabled item */
+.asm-dropdown-item:disabled {
+  opacity: 0.5;
+}
+```
+
+---
+
+## 🪝 Hooks
+
+### useDropdown
+
+Build custom dropdowns with full control over positioning and state.
+
+**Returns:**
 
+```tsx
 const {
-  isOpen,
-  position,
-  triggerRef,
-  menuRef,
-  toggle,
-  open,
-  close,
-  handleItemClick
+  isOpen,           // boolean - Menu visibility state
+  position,         // DropdownPosition - Calculated position
+  triggerRef,       // RefObject - Attach to trigger element
+  menuRef,          // RefObject - Attach to menu element
+  toggle,           // () => void - Toggle open/closed
+  open,             // () => void - Open menu
+  close,            // () => void - Close menu
+  handleItemClick   // () => void - Handle item selection
 } = useDropdown({
   placement: 'bottom-start',
   offset: 8,
@@ -186,133 +321,119 @@ const {
 });
 ```
 
+**Example:**
+
+```tsx
+function CustomDropdown() {
+  const { isOpen, position, toggle, triggerRef, menuRef } = useDropdown();
+
+  return (
+    <>
+      <button ref={triggerRef} onClick={toggle}>
+        Open Menu
+      </button>
+      {isOpen && (
+        <DropdownMenu ref={menuRef} isOpen={isOpen} position={position}>
+          {/* Menu items */}
+        </DropdownMenu>
+      )}
+    </>
+  );
+}
+```
+
 ### useClickOutside
 
-Hook for detecting clicks outside an element:
+Detect clicks outside an element to close menus.
 
 ```tsx
-import { useClickOutside } from '@asafarim/react-dropdowns';
-
 useClickOutside({
-  ref: elementRef,
-  handler: () => setIsOpen(false),
-  enabled: isOpen
+  ref: containerRef,           // Element to monitor
+  handler: () => setIsOpen(false), // Callback on outside click
+  enabled: isOpen,             // Enable/disable detection
+  excludeRefs: [menuRef]       // Refs to exclude from detection
 });
 ```
 
 ### useKeyboardNavigation
 
-Hook for keyboard navigation support:
+Add keyboard navigation to custom dropdowns.
 
 ```tsx
-import { useKeyboardNavigation } from '@asafarim/react-dropdowns';
-
 useKeyboardNavigation({
-  isOpen,
-  menuRef,
+  isOpen,                      // boolean
+  menuRef,                     // RefObject to menu
   onClose: () => setIsOpen(false),
   onSelect: (index) => selectItem(index)
 });
 ```
 
-## Styling
-
-The components use CSS custom properties (CSS variables) from the ASafariM design token system. Import the CSS file:
-
-```tsx
-import '@asafarim/react-dropdowns/dist/dropdown.css';
-```
-
-### Custom Styling
-
-You can override the default styles by targeting the CSS classes:
+---
 
-```css
-.asm-dropdown-menu {
-  /* Custom menu styles */
-}
+## ♿ Accessibility
 
-.asm-dropdown-item {
-  /* Custom item styles */
-}
+Built with WCAG 2.1 AA compliance in mind:
 
-.asm-dropdown-item--danger {
-  /* Custom danger item styles */
-}
-```
-
-## Accessibility
-
-The dropdown components are built with accessibility in mind:
-
-- **Keyboard Navigation**: Arrow keys, Enter, Escape, Home, End
-- **Screen Reader Support**: Proper ARIA attributes and roles
-- **Focus Management**: Automatic focus handling and restoration
-- **High Contrast**: Support for high contrast mode
-- **Reduced Motion**: Respects user's motion preferences
+- **Keyboard Navigation** — Full support for arrow keys, Enter, Escape, Home, End
+- **Screen Readers** — Proper ARIA roles, labels, and live regions
+- **Focus Management** — Automatic focus handling and restoration
+- **High Contrast** — Works with high contrast mode
+- **Reduced Motion** — Respects `prefers-reduced-motion` setting
 
 ### Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
-| `Space` / `Enter` | Open/close dropdown or select item |
-| `Arrow Down` | Navigate to next item or open dropdown |
-| `Arrow Up` | Navigate to previous item |
-| `Home` | Navigate to first item |
-| `End` | Navigate to last item |
-| `Escape` | Close dropdown |
-| `Tab` | Close dropdown and move to next element |
+| `Space` / `Enter` | Toggle menu or select item |
+| `Arrow Down` | Next item / Open menu |
+| `Arrow Up` | Previous item |
+| `Home` | First item |
+| `End` | Last item |
+| `Escape` | Close menu |
+| `Tab` | Close menu and move focus |
 
-## Examples
+---
 
-### Basic Menu
+## 💡 Real-World Examples
+
+### File Menu
 
 ```tsx
 <Dropdown
   items={[
-    { id: 'new', label: 'New', onClick: () => {} },
-    { id: 'edit', label: 'Edit', onClick: () => {} },
+    { id: 'new', label: 'New', icon: <FileText size={16} /> },
+    { id: 'open', label: 'Open', icon: <FolderOpen size={16} /> },
+    { divider: true },
+    { id: 'save', label: 'Save', icon: <Save size={16} /> },
+    { id: 'export', label: 'Export', icon: <Download size={16} /> },
     { divider: true },
-    { id: 'delete', label: 'Delete', danger: true, onClick: () => {} }
+    { id: 'exit', label: 'Exit', danger: true, icon: <X size={16} /> }
   ]}
+  placement="bottom-start"
 >
-  <button>File</button>
+  File
 </Dropdown>
 ```
 
-### User Menu
+### User Account Menu
 
 ```tsx
+const [user, setUser] = useState({ name: 'John Doe', avatar: '...' });
+
 <Dropdown
   items={[
-    {
-      id: 'profile',
-      label: 'Profile',
-      icon: <UserIcon />,
-      onClick: () => navigate('/profile')
-    },
-    {
-      id: 'settings',
-      label: 'Settings',
-      icon: <SettingsIcon />,
-      onClick: () => navigate('/settings')
-    },
+    { id: 'profile', label: 'Profile', icon: <User size={16} /> },
+    { id: 'settings', label: 'Settings', icon: <Settings size={16} /> },
     { divider: true },
-    {
-      id: 'logout',
-      label: 'Logout',
-      icon: <LogoutIcon />,
-      danger: true,
-      onClick: handleLogout
-    }
+    { id: 'logout', label: 'Logout', danger: true, icon: <LogOut size={16} /> }
   ]}
   placement="bottom-end"
 >
-  <img src={user.avatar} alt={user.name} />
+  <img src={user.avatar} alt={user.name} style={{ width: 32, height: 32, borderRadius: '50%' }} />
 </Dropdown>
 ```
 
-### Filter Dropdown
+### Filter Selector
 
 ```tsx
 const [filter, setFilter] = useState('all');
@@ -322,100 +443,105 @@ const [filter, setFilter] = useState('all');
     {
       id: 'all',
       label: 'All Items',
-      icon: filter === 'all' ? <CheckIcon /> : undefined,
+      icon: filter === 'all' ? <Check size={16} /> : undefined,
       onClick: () => setFilter('all')
     },
     {
       id: 'active',
       label: 'Active Only',
-      icon: filter === 'active' ? <CheckIcon /> : undefined,
+      icon: filter === 'active' ? <Check size={16} /> : undefined,
       onClick: () => setFilter('active')
     },
     {
       id: 'archived',
       label: 'Archived',
-      icon: filter === 'archived' ? <CheckIcon /> : undefined,
+      icon: filter === 'archived' ? <Check size={16} /> : undefined,
       onClick: () => setFilter('archived')
     }
   ]}
+  placement="bottom-start"
 >
-  <button>
-    <FilterIcon />
-    Filter: {filter}
-    <ChevronDownIcon />
-  </button>
+  <Filter size={16} />
+  {filter}
 </Dropdown>
 ```
 
-## Demo
+### Context Menu (Advanced)
 
-Run the demo application to see all features in action:
+See the demo app for a complete example using `useDropdown` with custom card trigger styling.
 
-```bash
-cd packages/react-dropdowns/demo
-npm install
-npm start
+---
+
+## 🧪 Testing
+
+All components are fully testable with standard React testing libraries:
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('opens dropdown on click', async () => {
+  render(
+    <Dropdown items={[{ id: 'test', label: 'Test', onClick: jest.fn() }]}>
+      Trigger
+    </Dropdown>
+  );
+
+  const trigger = screen.getByText('Trigger');
+  await userEvent.click(trigger);
+
+  expect(screen.getByText('Test')).toBeInTheDocument();
+});
 ```
 
-The demo showcases:
-- Basic usage examples
-- All placement options
-- Interactive examples (filters, user selectors)
-- Different sizes and states
-- Mobile optimizations
-- Dark theme support
+---
+
+## 🌐 Browser Support
 
-## Browser Support
+| Browser | Version |
+|---------|---------|
+| Chrome | 88+ |
+| Firefox | 78+ |
+| Safari | 14+ |
+| Edge | 88+ |
 
-- Chrome 88+
-- Firefox 78+
-- Safari 14+
-- Edge 88+
+---
 
-## Contributing
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
 
 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`)
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Commit changes: `git commit -m 'Add your feature'`
+4. Push to branch: `git push origin feature/your-feature`
 5. Open a Pull Request
 
-## License
+---
+
+## 📄 License
 
 MIT © ASafariM
 
-## Button Variants
+---
 
-The dropdown trigger supports multiple button style variants:
+## 🔗 Resources
 
-- `primary` - Default primary button style
-- `secondary` - Secondary button with border
-- `success` - Green success button
-- `warning` - Orange warning button
-- `danger` - Red destructive button
-- `info` - Cyan info button
-- `ghost` - Transparent ghost button
-- `outline` - Outlined button
-- `link` - Text link style
-- `brand` - Brand-specific color
+- [Live Demo](https://alisafari-it.github.io/react-dropdowns/)
+- [GitHub Repository](https://github.com/AliSafari-IT/react-dropdowns)
+- [npm Package](https://www.npmjs.com/package/@asafarim/react-dropdowns)
+- [ASafariM Design Tokens](https://github.com/AliSafari-IT/design-tokens)
 
-```tsx
-<Dropdown variant="secondary" items={items}>
-  <button>Secondary Dropdown</button>
-</Dropdown>
-```
+---
 
-## Chevron Icon
+## 📋 Changelog
 
-The dropdown automatically adds a chevron icon to the trigger button. You can disable it with the `showChevron` prop:
-
-```tsx
-<Dropdown showChevron={false} items={items}>
-  <button>No Chevron</button>
-</Dropdown>
-```
+### 1.8.0
 
-## Changelog
+- Added an advanced `useDropdown` demo section with custom trigger, portal rendering, and click-outside handling
+- Documented low-level hook usage with full examples and testing guidance
+- Rewrote README for clearer onboarding (installation, components, customization)
+- Improved demo styles and behavior (auto-close on outside click, refined trigger states)
 
 ### 1.1.1
 
@@ -424,6 +550,7 @@ The dropdown automatically adds a chevron icon to the trigger button. You can di
 - Fixed Vite base path configuration for GitHub Pages deployment
 - Improved demo app layout with grid-based examples
 - Added support for multiple button variants in trigger
+- Added advanced custom dropdown example with `useDropdown` hook
 
 ### 1.1.0
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asafarim/react-dropdowns",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "Comprehensive reusable dropdown components for React with TypeScript and mobile-first design",
   "main": "dist/index.js",