@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/Popover/ai-documentation.md

@@ -1,625 +0,0 @@
-# Popover Component - @pushwoosh/dumb-components
-
-## Overview
-
-- **Component Name**: Popover
-- **Import Path**: `@pushwoosh/dumb-components`
-- **Files**:
-  - `/src/Popover/Popover.tsx` - Main component implementation
-  - `/src/Popover/types.ts` - TypeScript type definitions
-  - `/src/Popover/styles.ts` - Styled components and container
-  - `/src/Popover/index.ts` - Component exports
-- **Type**: Overlay/Display
-- **Description**: A floating popover component that displays content positioned relative to an anchor element. Built on tippy.js for robust positioning and portal rendering, with support for custom positioning, loading states, and responsive behavior.
-
-## TypeScript Interfaces
-
-```typescript
-import type { Placement } from 'tippy.js';
-
-export interface PopoverProps {
-  readonly anchorEl: RefObject<HTMLElement>;
-  readonly internalWindowRef?: RefObject<HTMLDivElement> | null;
-  readonly position?: Placement;
-  readonly open: boolean;
-  readonly loading?: boolean;
-  readonly zIndex?: number;
-  readonly windowWidth?: number;
-  readonly children: ReactNode | undefined;
-}
-
-// Re-exported from tippy.js
-export type Placement = 
-  | 'top' | 'top-start' | 'top-end'
-  | 'bottom' | 'bottom-start' | 'bottom-end'
-  | 'left' | 'left-start' | 'left-end'
-  | 'right' | 'right-start' | 'right-end';
-```
-
-## Import & Usage
-
-```typescript
-import { Popover, type Placement } from '@pushwoosh/dumb-components';
-
-// Basic usage
-function MyComponent() {
-  const [isOpen, setIsOpen] = useState(false);
-  const anchorRef = useRef<HTMLButtonElement>(null);
-
-  return (
-    <div>
-      <button
-        ref={anchorRef}
-        onClick={() => setIsOpen(!isOpen)}
-      >
-        Open Popover
-      </button>
-      
-      <Popover
-        open={isOpen}
-        anchorEl={anchorRef}
-        position="bottom-start"
-      >
-        <div style={{ padding: '16px' }}>
-          <h3>Popover Content</h3>
-          <p>This is the content inside the popover.</p>
-          <button onClick={() => setIsOpen(false)}>
-            Close
-          </button>
-        </div>
-      </Popover>
-    </div>
-  );
-}
-
-// Click outside to close
-function ClickOutsidePopover() {
-  const [isOpen, setIsOpen] = useState(false);
-  const anchorRef = useRef<HTMLButtonElement>(null);
-  const popoverRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    const handleClickOutside = (event: MouseEvent) => {
-      if (
-        isOpen &&
-        anchorRef.current &&
-        popoverRef.current &&
-        !anchorRef.current.contains(event.target as Node) &&
-        !popoverRef.current.contains(event.target as Node)
-      ) {
-        setIsOpen(false);
-      }
-    };
-
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, [isOpen]);
-
-  return (
-    <div>
-      <button
-        ref={anchorRef}
-        onClick={() => setIsOpen(!isOpen)}
-      >
-        Click Outside to Close
-      </button>
-      
-      <Popover
-        open={isOpen}
-        anchorEl={anchorRef}
-        internalWindowRef={popoverRef}
-        position="bottom"
-      >
-        <div style={{ padding: '20px', minWidth: '200px' }}>
-          <h4>Interactive Popover</h4>
-          <input placeholder="Type something..." />
-          <br />
-          <button style={{ marginTop: '10px' }}>Action</button>
-        </div>
-      </Popover>
-    </div>
-  );
-}
-```
-
-## Advanced Examples
-
-```typescript
-// Menu popover
-function MenuPopover() {
-  const [isOpen, setIsOpen] = useState(false);
-  const [selectedOption, setSelectedOption] = useState('');
-  const anchorRef = useRef<HTMLButtonElement>(null);
-
-  const menuItems = [
-    { id: 'edit', label: 'Edit', icon: '✏️' },
-    { id: 'copy', label: 'Copy', icon: '📋' },
-    { id: 'move', label: 'Move', icon: '📁' },
-    { id: 'delete', label: 'Delete', icon: '🗑️', danger: true },
-  ];
-
-  const handleMenuItemClick = (itemId: string) => {
-    setSelectedOption(itemId);
-    setIsOpen(false);
-    
-    // Handle the action
-    switch (itemId) {
-      case 'edit':
-        console.log('Edit action');
-        break;
-      case 'copy':
-        console.log('Copy action');
-        break;
-      // ... other actions
-    }
-  };
-
-  return (
-    <div>
-      <button
-        ref={anchorRef}
-        onClick={() => setIsOpen(!isOpen)}
-        style={{ 
-          padding: '8px 16px', 
-          display: 'flex', 
-          alignItems: 'center', 
-          gap: '8px' 
-        }}
-      >
-        Actions ▼
-      </button>
-      
-      <Popover
-        open={isOpen}
-        anchorEl={anchorRef}
-        position="bottom-start"
-        windowWidth={180}
-      >
-        <div style={{ padding: '8px 0' }}>
-          {menuItems.map(item => (
-            <button
-              key={item.id}
-              onClick={() => handleMenuItemClick(item.id)}
-              style={{
-                width: '100%',
-                padding: '12px 16px',
-                border: 'none',
-                background: 'transparent',
-                textAlign: 'left',
-                display: 'flex',
-                alignItems: 'center',
-                gap: '8px',
-                cursor: 'pointer',
-                color: item.danger ? '#dc3545' : 'inherit',
-              }}
-              onMouseEnter={(e) => {
-                e.currentTarget.style.backgroundColor = '#f8f9fa';
-              }}
-              onMouseLeave={(e) => {
-                e.currentTarget.style.backgroundColor = 'transparent';
-              }}
-            >
-              <span>{item.icon}</span>
-              {item.label}
-            </button>
-          ))}
-        </div>
-      </Popover>
-    </div>
-  );
-}
-
-// Form popover
-function FormPopover() {
-  const [isOpen, setIsOpen] = useState(false);
-  const [formData, setFormData] = useState({ name: '', email: '' });
-  const [isLoading, setIsLoading] = useState(false);
-  const anchorRef = useRef<HTMLButtonElement>(null);
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    setIsLoading(true);
-    
-    try {
-      // Simulate API call
-      await new Promise(resolve => setTimeout(resolve, 1000));
-      console.log('Form submitted:', formData);
-      setIsOpen(false);
-      setFormData({ name: '', email: '' });
-    } catch (error) {
-      console.error('Failed to submit:', error);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  return (
-    <div>
-      <button
-        ref={anchorRef}
-        onClick={() => setIsOpen(!isOpen)}
-      >
-        Add User
-      </button>
-      
-      <Popover
-        open={isOpen}
-        anchorEl={anchorRef}
-        position="bottom-start"
-        loading={isLoading}
-        windowWidth={300}
-      >
-        <form onSubmit={handleSubmit} style={{ padding: '20px' }}>
-          <h4 style={{ marginTop: 0 }}>Add New User</h4>
-          
-          <div style={{ marginBottom: '16px' }}>
-            <label style={{ display: 'block', marginBottom: '4px' }}>
-              Name
-            </label>
-            <input
-              type="text"
-              value={formData.name}
-              onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}
-              style={{ width: '100%', padding: '8px' }}
-              required
-            />
-          </div>
-          
-          <div style={{ marginBottom: '16px' }}>
-            <label style={{ display: 'block', marginBottom: '4px' }}>
-              Email
-            </label>
-            <input
-              type="email"
-              value={formData.email}
-              onChange={(e) => setFormData(prev => ({ ...prev, email: e.target.value }))}
-              style={{ width: '100%', padding: '8px' }}
-              required
-            />
-          </div>
-          
-          <div style={{ display: 'flex', gap: '8px', justifyContent: 'flex-end' }}>
-            <button
-              type="button"
-              onClick={() => setIsOpen(false)}
-              disabled={isLoading}
-              style={{ padding: '8px 16px' }}
-            >
-              Cancel
-            </button>
-            <button
-              type="submit"
-              disabled={isLoading}
-              style={{ padding: '8px 16px', backgroundColor: '#007bff', color: 'white' }}
-            >
-              {isLoading ? 'Adding...' : 'Add User'}
-            </button>
-          </div>
-        </form>
-      </Popover>
-    </div>
-  );
-}
-
-// Info popover with rich content
-function InfoPopover() {
-  const [isOpen, setIsOpen] = useState(false);
-  const anchorRef = useRef<HTMLSpanElement>(null);
-
-  return (
-    <div>
-      <p>
-        Our premium plan includes{' '}
-        <span
-          ref={anchorRef}
-          onMouseEnter={() => setIsOpen(true)}
-          onMouseLeave={() => setIsOpen(false)}
-          style={{
-            textDecoration: 'underline',
-            cursor: 'help',
-            color: '#007bff',
-          }}
-        >
-          advanced analytics
-        </span>
-        {' '}and reporting features.
-      </p>
-      
-      <Popover
-        open={isOpen}
-        anchorEl={anchorRef}
-        position="top"
-        windowWidth={320}
-      >
-        <div style={{ padding: '16px' }}>
-          <h4 style={{ marginTop: 0, marginBottom: '12px' }}>
-            Advanced Analytics
-          </h4>
-          <ul style={{ margin: 0, paddingLeft: '20px' }}>
-            <li>Real-time dashboard updates</li>
-            <li>Custom report generation</li>
-            <li>Data export capabilities</li>
-            <li>Advanced filtering options</li>
-            <li>Historical trend analysis</li>
-          </ul>
-          
-          <div style={{ marginTop: '12px', padding: '8px', backgroundColor: '#f8f9fa', borderRadius: '4px' }}>
-            <small style={{ color: '#666' }}>
-              💡 Tip: Use keyboard shortcuts to navigate dashboards faster
-            </small>
-          </div>
-        </div>
-      </Popover>
-    </div>
-  );
-}
-
-// Multi-step popover
-function MultiStepPopover() {
-  const [isOpen, setIsOpen] = useState(false);
-  const [currentStep, setCurrentStep] = useState(1);
-  const [formData, setFormData] = useState({
-    category: '',
-    title: '',
-    description: '',
-  });
-  const anchorRef = useRef<HTMLButtonElement>(null);
-
-  const totalSteps = 3;
-
-  const renderStepContent = () => {
-    switch (currentStep) {
-      case 1:
-        return (
-          <div>
-            <h4>Step 1: Category</h4>
-            <select
-              value={formData.category}
-              onChange={(e) => setFormData(prev => ({ ...prev, category: e.target.value }))}
-              style={{ width: '100%', padding: '8px' }}
-            >
-              <option value="">Select category...</option>
-              <option value="bug">Bug Report</option>
-              <option value="feature">Feature Request</option>
-              <option value="question">Question</option>
-            </select>
-          </div>
-        );
-      case 2:
-        return (
-          <div>
-            <h4>Step 2: Title</h4>
-            <input
-              type="text"
-              placeholder="Enter a title..."
-              value={formData.title}
-              onChange={(e) => setFormData(prev => ({ ...prev, title: e.target.value }))}
-              style={{ width: '100%', padding: '8px' }}
-            />
-          </div>
-        );
-      case 3:
-        return (
-          <div>
-            <h4>Step 3: Description</h4>
-            <textarea
-              placeholder="Describe your request..."
-              value={formData.description}
-              onChange={(e) => setFormData(prev => ({ ...prev, description: e.target.value }))}
-              style={{ width: '100%', padding: '8px', height: '80px' }}
-            />
-          </div>
-        );
-      default:
-        return null;
-    }
-  };
-
-  const handleNext = () => {
-    if (currentStep < totalSteps) {
-      setCurrentStep(prev => prev + 1);
-    } else {
-      // Submit form
-      console.log('Form submitted:', formData);
-      setIsOpen(false);
-      setCurrentStep(1);
-      setFormData({ category: '', title: '', description: '' });
-    }
-  };
-
-  const handleBack = () => {
-    if (currentStep > 1) {
-      setCurrentStep(prev => prev - 1);
-    }
-  };
-
-  return (
-    <div>
-      <button
-        ref={anchorRef}
-        onClick={() => setIsOpen(!isOpen)}
-      >
-        Create Request
-      </button>
-      
-      <Popover
-        open={isOpen}
-        anchorEl={anchorRef}
-        position="bottom-start"
-        windowWidth={350}
-      >
-        <div style={{ padding: '20px' }}>
-          <div style={{ marginBottom: '16px' }}>
-            <div style={{ fontSize: '14px', color: '#666' }}>
-              Step {currentStep} of {totalSteps}
-            </div>
-            <div style={{ 
-              width: '100%', 
-              height: '4px', 
-              backgroundColor: '#e9ecef', 
-              borderRadius: '2px',
-              marginTop: '4px'
-            }}>
-              <div style={{
-                width: `${(currentStep / totalSteps) * 100}%`,
-                height: '100%',
-                backgroundColor: '#007bff',
-                borderRadius: '2px',
-                transition: 'width 0.3s ease'
-              }} />
-            </div>
-          </div>
-
-          {renderStepContent()}
-
-          <div style={{ 
-            display: 'flex', 
-            gap: '8px', 
-            justifyContent: 'flex-end',
-            marginTop: '20px'
-          }}>
-            {currentStep > 1 && (
-              <button
-                onClick={handleBack}
-                style={{ padding: '8px 16px' }}
-              >
-                Back
-              </button>
-            )}
-            <button
-              onClick={() => setIsOpen(false)}
-              style={{ padding: '8px 16px' }}
-            >
-              Cancel
-            </button>
-            <button
-              onClick={handleNext}
-              style={{ 
-                padding: '8px 16px', 
-                backgroundColor: '#007bff', 
-                color: 'white' 
-              }}
-            >
-              {currentStep === totalSteps ? 'Submit' : 'Next'}
-            </button>
-          </div>
-        </div>
-      </Popover>
-    </div>
-  );
-}
-```
-
-## Props Reference
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `anchorEl` | `RefObject<HTMLElement>` | - | Yes | Reference to the element that anchors the popover |
-| `internalWindowRef` | `RefObject<HTMLDivElement> \| null` | `null` | No | Reference to the popover window for external access |
-| `position` | `Placement` | `'right-start'` | No | Position of the popover relative to anchor |
-| `open` | `boolean` | - | Yes | Whether the popover is visible |
-| `loading` | `boolean` | `false` | No | Whether the popover shows a loading state |
-| `zIndex` | `number` | `1000` | No | CSS z-index for the popover |
-| `windowWidth` | `number` | `undefined` | No | Fixed width for the popover window |
-| `children` | `ReactNode \| undefined` | - | Yes | Content to display inside the popover |
-
-## AI Agent Guidelines
-
-### Recommended Patterns
-
-1. **Anchor Element**: Always use refs for anchor elements
-```typescript
-const anchorRef = useRef<HTMLButtonElement>(null);
-
-<button ref={anchorRef}>Trigger</button>
-<Popover anchorEl={anchorRef} open={isOpen}>
-  {/* content */}
-</Popover>
-```
-
-2. **Controlled State**: Manage popover visibility in parent component
-```typescript
-const [isOpen, setIsOpen] = useState(false);
-
-// Good - controlled
-<Popover open={isOpen} onClose={() => setIsOpen(false)}>
-```
-
-3. **Click Outside Handling**: Implement click outside to close
-```typescript
-useEffect(() => {
-  const handleClickOutside = (event: MouseEvent) => {
-    if (isOpen && !anchorRef.current?.contains(event.target as Node)) {
-      setIsOpen(false);
-    }
-  };
-
-  document.addEventListener('mousedown', handleClickOutside);
-  return () => document.removeEventListener('mousedown', handleClickOutside);
-}, [isOpen]);
-```
-
-### Common Mistakes to Avoid
-
-1. **Missing Anchor Ref**: Don't forget to attach the ref to the anchor element
-2. **Portal Issues**: The popover uses portal rendering - don't nest it inside positioned containers
-3. **Z-Index Conflicts**: Ensure proper z-index layering with other overlays
-4. **Memory Leaks**: Clean up event listeners in useEffect cleanup
-5. **Accessibility**: Ensure keyboard navigation and ARIA attributes are handled
-
-### Integration Tips
-
-1. **Positioning**: Use appropriate placement for your use case
-```typescript
-// Common placements
-position="bottom-start"  // Dropdown menus
-position="top"          // Tooltips above
-position="right"        // Side panels
-position="left-end"     // Context menus
-```
-
-2. **Content Sizing**: Use windowWidth for consistent sizing
-```typescript
-// Fixed width popover
-<Popover windowWidth={300}>
-  {/* content will be max 300px wide */}
-</Popover>
-```
-
-3. **Loading States**: Handle async content loading
-```typescript
-<Popover loading={isLoading}>
-  {isLoading ? <div>Loading...</div> : <div>Content</div>}
-</Popover>
-```
-
-4. **Form Integration**: Works well with forms inside popover content
-```typescript
-<Popover>
-  <form onSubmit={handleSubmit}>
-    {/* form fields */}
-  </form>
-</Popover>
-```
-
-5. **Keyboard Accessibility**: Handle Escape key to close
-```typescript
-useEffect(() => {
-  const handleKeyDown = (event: KeyboardEvent) => {
-    if (event.key === 'Escape' && isOpen) {
-      setIsOpen(false);
-    }
-  };
-
-  document.addEventListener('keydown', handleKeyDown);
-  return () => document.removeEventListener('keydown', handleKeyDown);
-}, [isOpen]);
-```
-
-## Related Components
-
-- **Tooltip**: For simple hover-based information display
-- **Modal**: For full-screen overlays
-- **Dropdown**: For select-style interfaces
-- **Menu**: For navigation or action lists
-- **Button**: Often used as popover triggers