@pushwoosh/dumb-components 1.1.147 → 1.1.149

package/Spinner/ai-documentation.md

@@ -1,607 +0,0 @@
-# Spinner Component - @pushwoosh/dumb-components
-
-## Overview
-
-- **Component Name**: Spinner
-- **Import Path**: `@pushwoosh/dumb-components`
-- **Files**:
-  - `/src/Spinner/Spinner.tsx` - Main component implementation
-  - `/src/Spinner/types.ts` - TypeScript type definitions
-  - `/src/Spinner/styles.ts` - Styled components and animations
-  - `/src/Spinner/maps.ts` - Size mapping utilities
-  - `/src/Spinner/assets/` - SVG icon assets
-  - `/src/Spinner/index.ts` - Component exports
-- **Type**: Feedback/Loading
-- **Description**: A spinning loading indicator component available in small and medium sizes. Features smooth CSS animations and customizable colors to indicate loading or processing states.
-
-## TypeScript Interfaces
-
-```typescript
-export interface SpinnerProps {
-  readonly boxRef?: Ref<HTMLDivElement>;
-  readonly color?: string;
-  readonly size: 'small' | 'medium';
-}
-```
-
-## Import & Usage
-
-```typescript
-import { Spinner } from '@pushwoosh/dumb-components';
-
-// Basic usage
-function MyComponent() {
-  const [isLoading, setIsLoading] = useState(false);
-
-  const handleLoad = async () => {
-    setIsLoading(true);
-    try {
-      await fetchData();
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  return (
-    <div>
-      <button onClick={handleLoad} disabled={isLoading}>
-        {isLoading ? 'Loading...' : 'Load Data'}
-      </button>
-      
-      {isLoading && (
-        <div style={{ marginTop: '16px' }}>
-          <Spinner size="medium" />
-        </div>
-      )}
-    </div>
-  );
-}
-
-// Different sizes
-function SpinnerSizes() {
-  return (
-    <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
-      <div>
-        <p>Small:</p>
-        <Spinner size="small" />
-      </div>
-      
-      <div>
-        <p>Medium:</p>
-        <Spinner size="medium" />
-      </div>
-    </div>
-  );
-}
-
-// Custom colors
-function ColoredSpinners() {
-  return (
-    <div style={{ display: 'flex', gap: '16px' }}>
-      <Spinner size="medium" color="#007bff" />
-      <Spinner size="medium" color="#28a745" />
-      <Spinner size="medium" color="#dc3545" />
-      <Spinner size="medium" color="#ffc107" />
-    </div>
-  );
-}
-```
-
-## Advanced Examples
-
-```typescript
-// Loading button
-function LoadingButton() {
-  const [isLoading, setIsLoading] = useState(false);
-
-  const handleClick = async () => {
-    setIsLoading(true);
-    try {
-      await performAction();
-      console.log('Action completed');
-    } catch (error) {
-      console.error('Action failed:', error);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  return (
-    <button
-      onClick={handleClick}
-      disabled={isLoading}
-      style={{
-        padding: '12px 20px',
-        display: 'flex',
-        alignItems: 'center',
-        gap: '8px',
-        backgroundColor: '#007bff',
-        color: 'white',
-        border: 'none',
-        borderRadius: '4px',
-        cursor: isLoading ? 'not-allowed' : 'pointer',
-        opacity: isLoading ? 0.7 : 1,
-      }}
-    >
-      {isLoading && <Spinner size="small" color="white" />}
-      {isLoading ? 'Processing...' : 'Submit'}
-    </button>
-  );
-}
-
-// Loading overlay
-function LoadingOverlay({ isLoading, children }: { isLoading: boolean, children: React.ReactNode }) {
-  return (
-    <div style={{ position: 'relative' }}>
-      {children}
-      
-      {isLoading && (
-        <div
-          style={{
-            position: 'absolute',
-            top: 0,
-            left: 0,
-            right: 0,
-            bottom: 0,
-            backgroundColor: 'rgba(255, 255, 255, 0.8)',
-            display: 'flex',
-            flexDirection: 'column',
-            alignItems: 'center',
-            justifyContent: 'center',
-            gap: '16px',
-            zIndex: 10,
-          }}
-        >
-          <Spinner size="medium" color="#007bff" />
-          <p style={{ margin: 0, color: '#666' }}>Loading...</p>
-        </div>
-      )}
-    </div>
-  );
-}
-
-// Usage with LoadingOverlay
-function DataTable() {
-  const [data, setData] = useState([]);
-  const [isLoading, setIsLoading] = useState(false);
-
-  const loadData = async () => {
-    setIsLoading(true);
-    try {
-      const result = await fetchTableData();
-      setData(result);
-    } catch (error) {
-      console.error('Failed to load data:', error);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  useEffect(() => {
-    loadData();
-  }, []);
-
-  return (
-    <LoadingOverlay isLoading={isLoading}>
-      <table style={{ width: '100%', minHeight: '200px' }}>
-        <thead>
-          <tr>
-            <th>ID</th>
-            <th>Name</th>
-            <th>Status</th>
-          </tr>
-        </thead>
-        <tbody>
-          {data.map(item => (
-            <tr key={item.id}>
-              <td>{item.id}</td>
-              <td>{item.name}</td>
-              <td>{item.status}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-    </LoadingOverlay>
-  );
-}
-
-// Conditional loading states
-function ConditionalLoading() {
-  const [loadingStates, setLoadingStates] = useState({
-    user: false,
-    posts: false,
-    comments: false,
-  });
-
-  const loadResource = async (resource: keyof typeof loadingStates) => {
-    setLoadingStates(prev => ({ ...prev, [resource]: true }));
-    
-    try {
-      // Simulate different loading times
-      const delay = resource === 'user' ? 1000 : resource === 'posts' ? 2000 : 1500;
-      await new Promise(resolve => setTimeout(resolve, delay));
-      
-      console.log(`${resource} loaded`);
-    } catch (error) {
-      console.error(`Failed to load ${resource}:`, error);
-    } finally {
-      setLoadingStates(prev => ({ ...prev, [resource]: false }));
-    }
-  };
-
-  return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
-      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
-        <button
-          onClick={() => loadResource('user')}
-          disabled={loadingStates.user}
-        >
-          Load User
-        </button>
-        {loadingStates.user && <Spinner size="small" color="#007bff" />}
-      </div>
-
-      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
-        <button
-          onClick={() => loadResource('posts')}
-          disabled={loadingStates.posts}
-        >
-          Load Posts
-        </button>
-        {loadingStates.posts && <Spinner size="small" color="#28a745" />}
-      </div>
-
-      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
-        <button
-          onClick={() => loadResource('comments')}
-          disabled={loadingStates.comments}
-        >
-          Load Comments
-        </button>
-        {loadingStates.comments && <Spinner size="small" color="#ffc107" />}
-      </div>
-    </div>
-  );
-}
-
-// Page loading spinner
-function PageLoader() {
-  const [isPageLoading, setIsPageLoading] = useState(true);
-
-  useEffect(() => {
-    // Simulate page load
-    const timer = setTimeout(() => {
-      setIsPageLoading(false);
-    }, 2000);
-
-    return () => clearTimeout(timer);
-  }, []);
-
-  if (isPageLoading) {
-    return (
-      <div
-        style={{
-          position: 'fixed',
-          top: 0,
-          left: 0,
-          right: 0,
-          bottom: 0,
-          backgroundColor: 'white',
-          display: 'flex',
-          flexDirection: 'column',
-          alignItems: 'center',
-          justifyContent: 'center',
-          gap: '20px',
-          zIndex: 9999,
-        }}
-      >
-        <Spinner size="medium" color="#007bff" />
-        <h2 style={{ margin: 0, color: '#333' }}>Loading Application...</h2>
-        <p style={{ margin: 0, color: '#666' }}>Please wait while we set things up</p>
-      </div>
-    );
-  }
-
-  return (
-    <div>
-      <h1>Welcome to the Application!</h1>
-      <p>The application has finished loading.</p>
-    </div>
-  );
-}
-
-// Inline loading states
-function InlineLoading() {
-  const [sections, setSections] = useState({
-    header: { loading: false, loaded: false },
-    sidebar: { loading: false, loaded: false },
-    content: { loading: false, loaded: false },
-  });
-
-  const loadSection = async (sectionName: keyof typeof sections) => {
-    setSections(prev => ({
-      ...prev,
-      [sectionName]: { loading: true, loaded: false }
-    }));
-
-    try {
-      await new Promise(resolve => setTimeout(resolve, 1500));
-      
-      setSections(prev => ({
-        ...prev,
-        [sectionName]: { loading: false, loaded: true }
-      }));
-    } catch (error) {
-      setSections(prev => ({
-        ...prev,
-        [sectionName]: { loading: false, loaded: false }
-      }));
-    }
-  };
-
-  const renderSection = (name: keyof typeof sections, title: string) => {
-    const section = sections[name];
-    
-    return (
-      <div
-        style={{
-          padding: '20px',
-          border: '1px solid #ddd',
-          borderRadius: '4px',
-          minHeight: '100px',
-          display: 'flex',
-          flexDirection: 'column',
-          justifyContent: 'center',
-          alignItems: 'center',
-        }}
-      >
-        {!section.loaded && !section.loading && (
-          <button onClick={() => loadSection(name)}>
-            Load {title}
-          </button>
-        )}
-        
-        {section.loading && (
-          <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
-            <Spinner size="small" />
-            <span>Loading {title.toLowerCase()}...</span>
-          </div>
-        )}
-        
-        {section.loaded && (
-          <div>
-            <h3>{title}</h3>
-            <p>{title} content has been loaded successfully!</p>
-          </div>
-        )}
-      </div>
-    );
-  };
-
-  return (
-    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '16px' }}>
-      {renderSection('header', 'Header')}
-      {renderSection('sidebar', 'Sidebar')}
-      {renderSection('content', 'Content')}
-      <div style={{ gridColumn: '1 / -1' }}>
-        <button
-          onClick={() => {
-            Object.keys(sections).forEach(section => {
-              loadSection(section as keyof typeof sections);
-            });
-          }}
-          style={{
-            padding: '12px 24px',
-            backgroundColor: '#28a745',
-            color: 'white',
-            border: 'none',
-            borderRadius: '4px',
-            cursor: 'pointer',
-          }}
-        >
-          Load All Sections
-        </button>
-      </div>
-    </div>
-  );
-}
-
-// Search with debounced loading
-function SearchWithSpinner() {
-  const [query, setQuery] = useState('');
-  const [results, setResults] = useState([]);
-  const [isSearching, setIsSearching] = useState(false);
-  const [debouncedQuery, setDebouncedQuery] = useState('');
-
-  // Debounce the search query
-  useEffect(() => {
-    const timer = setTimeout(() => {
-      setDebouncedQuery(query);
-    }, 500);
-
-    return () => clearTimeout(timer);
-  }, [query]);
-
-  // Perform search when debounced query changes
-  useEffect(() => {
-    if (debouncedQuery) {
-      performSearch(debouncedQuery);
-    } else {
-      setResults([]);
-    }
-  }, [debouncedQuery]);
-
-  const performSearch = async (searchQuery: string) => {
-    setIsSearching(true);
-    
-    try {
-      // Simulate search API call
-      await new Promise(resolve => setTimeout(resolve, 1000));
-      
-      // Mock results
-      const mockResults = [
-        `Result 1 for "${searchQuery}"`,
-        `Result 2 for "${searchQuery}"`,
-        `Result 3 for "${searchQuery}"`,
-      ];
-      
-      setResults(mockResults);
-    } catch (error) {
-      console.error('Search failed:', error);
-      setResults([]);
-    } finally {
-      setIsSearching(false);
-    }
-  };
-
-  return (
-    <div>
-      <div style={{ display: 'flex', alignItems: 'center', gap: '12px', marginBottom: '16px' }}>
-        <input
-          type="text"
-          placeholder="Search..."
-          value={query}
-          onChange={(e) => setQuery(e.target.value)}
-          style={{
-            padding: '8px 12px',
-            border: '1px solid #ddd',
-            borderRadius: '4px',
-            flex: 1,
-          }}
-        />
-        {isSearching && <Spinner size="small" color="#007bff" />}
-      </div>
-
-      <div>
-        {results.length > 0 ? (
-          <div>
-            <h4>Search Results:</h4>
-            <ul>
-              {results.map((result, index) => (
-                <li key={index}>{result}</li>
-              ))}
-            </ul>
-          </div>
-        ) : query && !isSearching ? (
-          <p>No results found for "{query}"</p>
-        ) : null}
-      </div>
-    </div>
-  );
-}
-```
-
-## Props Reference
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `boxRef` | `Ref<HTMLDivElement>` | `undefined` | No | Ref for the spinner container element |
-| `color` | `string` | `undefined` | No | Custom color for the spinner |
-| `size` | `'small' \| 'medium'` | - | Yes | Size variant of the spinner |
-
-## AI Agent Guidelines
-
-### Recommended Patterns
-
-1. **Size Selection**: Choose appropriate size for context
-```typescript
-// Small for inline elements
-<Button disabled={loading}>
-  {loading && <Spinner size="small" />}
-  Submit
-</Button>
-
-// Medium for standalone loading states
-<div>
-  <Spinner size="medium" />
-  <p>Loading content...</p>
-</div>
-```
-
-2. **Color Consistency**: Match spinner colors to your theme
-```typescript
-// Match brand colors
-<Spinner size="medium" color="#007bff" />  // Primary
-<Spinner size="medium" color="#28a745" />  // Success
-<Spinner size="medium" color="#dc3545" />  // Error
-```
-
-3. **Conditional Rendering**: Only show when actually loading
-```typescript
-const [isLoading, setIsLoading] = useState(false);
-
-// Good - conditional rendering
-{isLoading && <Spinner size="medium" />}
-
-// Avoid - always rendered
-<Spinner size="medium" style={{ display: isLoading ? 'block' : 'none' }} />
-```
-
-### Common Mistakes to Avoid
-
-1. **Missing Size Prop**: Always provide the required `size` prop
-2. **Performance Issues**: Don't render multiple spinners unnecessarily
-3. **Accessibility**: Provide appropriate ARIA labels for screen readers
-4. **Overlapping Spinners**: Avoid multiple spinners in the same area
-5. **Infinite Loading**: Always have a timeout or error handling for loading states
-
-### Integration Tips
-
-1. **Loading States**: Use with React state management
-```typescript
-const [isLoading, setIsLoading] = useState(false);
-
-const handleAction = async () => {
-  setIsLoading(true);
-  try {
-    await performAction();
-  } finally {
-    setIsLoading(false);
-  }
-};
-```
-
-2. **Button Integration**: Common pattern for loading buttons
-```typescript
-<button disabled={isLoading}>
-  {isLoading && <Spinner size="small" color="white" />}
-  {isLoading ? 'Loading...' : 'Click Me'}
-</button>
-```
-
-3. **Overlay Pattern**: For loading overlays
-```typescript
-{isLoading && (
-  <div style={{ 
-    position: 'absolute', 
-    top: 0, 
-    left: 0, 
-    right: 0, 
-    bottom: 0,
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    backgroundColor: 'rgba(255,255,255,0.8)'
-  }}>
-    <Spinner size="medium" />
-  </div>
-)}
-```
-
-4. **Accessibility**: Include proper ARIA labels
-```typescript
-<div role="status" aria-live="polite">
-  <Spinner size="medium" />
-  <span className="sr-only">Loading...</span>
-</div>
-```
-
-5. **Performance**: Use React.memo for components with spinners to prevent unnecessary re-renders
-
-## Related Components
-
-- **Button**: Often used together for loading button states
-- **ProgressBar**: Alternative for progress indication
-- **Modal**: For loading dialogs
-- **Skeleton**: Alternative loading pattern for content placeholders
-- **Alert**: For loading completion notifications