@pushwoosh/dumb-components 1.1.147 → 1.1.149

package/Tabs/ai-documentation.md

@@ -1,475 +0,0 @@
-# Tabs Component System - @pushwoosh/dumb-components
-
-## Overview
-
-- **Component Name**: Tabs (System)
-- **Import Path**: `@pushwoosh/dumb-components`
-- **Files**:
-  - `/src/Tabs/index.tsx` - Main exports
-  - `/src/Tabs/types.ts` - Core type definitions
-  - `/src/Tabs/context.tsx` - React context for tab state
-  - `/src/Tabs/helpers.tsx` - Helper utilities
-  - `/src/Tabs/components/Tabs/` - Main Tabs container
-  - `/src/Tabs/components/Tab/` - Individual Tab component
-  - `/src/Tabs/components/TabBar/` - Tab navigation bar
-  - `/src/Tabs/components/TabPanel/` - Tab content panel
-  - `/src/Tabs/components/TabBase/` - Base tab styling
-  - `/src/Tabs/components/TabBarScrollableFrame/` - Scrollable tab container
-- **Type**: Navigation/Layout
-- **Description**: A complete tab system with multiple components for creating tabbed interfaces. Supports controlled state management, custom containers, icons, disabled states, and new item indicators.
-
-## TypeScript Interfaces
-
-```typescript
-export type TabCode = string | number;
-
-export type TabContextType = {
-  activeTabCode: TabCode;
-  setActiveTabCode: (code: TabCode) => void;
-};
-
-// Main Tabs container
-export type TabsProps = PropsWithChildren<Readonly<{
-  activeCode: TabCode;
-  onChange: (code: TabCode) => void;
-  container?: ElementType;
-}>>;
-
-// Individual Tab
-export type TabProps = Omit<JSX.IntrinsicElements['div'], 'ref' | 'onClick'> & Readonly<{
-  code: TabCode;
-  onActivate?: (code: TabCode) => void;
-  isDisabled?: boolean;
-  isNew?: boolean;
-  icon?: ReactNode;
-}>;
-
-// Tab Bar (navigation container)
-export type TabBarProps = Omit<JSX.IntrinsicElements['div'], 'ref'> & Readonly<{
-  title?: ReactNode;
-}>;
-
-// Tab Panel (content container)
-export type TabPanelProps = PropsWithChildren<Readonly<{
-  code: TabCode;
-  container?: ElementType;
-}>>;
-```
-
-## Import & Usage
-
-```typescript
-import { Tabs, Tab, TabBar, TabPanel } from '@pushwoosh/dumb-components';
-
-// Basic usage
-function MyTabs() {
-  const [activeTab, setActiveTab] = useState('tab1');
-
-  return (
-    <Tabs activeCode={activeTab} onChange={setActiveTab}>
-      <TabBar>
-        <Tab code="tab1">First Tab</Tab>
-        <Tab code="tab2">Second Tab</Tab>
-        <Tab code="tab3">Third Tab</Tab>
-      </TabBar>
-
-      <TabPanel code="tab1">
-        <h3>First Panel</h3>
-        <p>Content for the first tab</p>
-      </TabPanel>
-
-      <TabPanel code="tab2">
-        <h3>Second Panel</h3>
-        <p>Content for the second tab</p>
-      </TabPanel>
-
-      <TabPanel code="tab3">
-        <h3>Third Panel</h3>
-        <p>Content for the third tab</p>
-      </TabPanel>
-    </Tabs>
-  );
-}
-
-// With tab bar title
-function TitledTabs() {
-  const [activeTab, setActiveTab] = useState('overview');
-
-  return (
-    <Tabs activeCode={activeTab} onChange={setActiveTab}>
-      <TabBar title="Dashboard Settings">
-        <Tab code="overview">Overview</Tab>
-        <Tab code="users">Users</Tab>
-        <Tab code="billing">Billing</Tab>
-      </TabBar>
-
-      <TabPanel code="overview">Overview content</TabPanel>
-      <TabPanel code="users">User management</TabPanel>
-      <TabPanel code="billing">Billing information</TabPanel>
-    </Tabs>
-  );
-}
-```
-
-## Advanced Examples
-
-```typescript
-// Tabs with icons and states
-function AdvancedTabs() {
-  const [activeTab, setActiveTab] = useState('dashboard');
-
-  return (
-    <Tabs activeCode={activeTab} onChange={setActiveTab}>
-      <TabBar title="Application">
-        <Tab 
-          code="dashboard" 
-          icon={<DashboardIcon />}
-        >
-          Dashboard
-        </Tab>
-        
-        <Tab 
-          code="notifications" 
-          icon={<BellIcon />}
-          isNew={true}
-        >
-          Notifications
-        </Tab>
-        
-        <Tab 
-          code="settings" 
-          icon={<SettingsIcon />}
-        >
-          Settings
-        </Tab>
-        
-        <Tab 
-          code="archive" 
-          icon={<ArchiveIcon />}
-          isDisabled={true}
-        >
-          Archive
-        </Tab>
-      </TabBar>
-
-      <TabPanel code="dashboard">
-        <div>Dashboard content with charts and metrics</div>
-      </TabPanel>
-
-      <TabPanel code="notifications">
-        <div>New notification system</div>
-      </TabPanel>
-
-      <TabPanel code="settings">
-        <div>Application settings</div>
-      </TabPanel>
-
-      <TabPanel code="archive">
-        <div>Archived items (disabled)</div>
-      </TabPanel>
-    </Tabs>
-  );
-}
-
-// Dynamic tabs with add/remove functionality
-function DynamicTabs() {
-  const [tabs, setTabs] = useState([
-    { code: 'tab-1', title: 'Tab 1', content: 'Content 1' },
-    { code: 'tab-2', title: 'Tab 2', content: 'Content 2' },
-  ]);
-  const [activeTab, setActiveTab] = useState('tab-1');
-  const [counter, setCounter] = useState(3);
-
-  const addTab = () => {
-    const newTab = {
-      code: `tab-${counter}`,
-      title: `Tab ${counter}`,
-      content: `Content for tab ${counter}`,
-    };
-    setTabs(prev => [...prev, newTab]);
-    setActiveTab(newTab.code);
-    setCounter(prev => prev + 1);
-  };
-
-  const removeTab = (codeToRemove: string) => {
-    setTabs(prev => prev.filter(tab => tab.code !== codeToRemove));
-    
-    // Switch to first tab if active tab is removed
-    if (activeTab === codeToRemove && tabs.length > 1) {
-      const remainingTabs = tabs.filter(tab => tab.code !== codeToRemove);
-      setActiveTab(remainingTabs[0].code);
-    }
-  };
-
-  return (
-    <div>
-      <button onClick={addTab}>Add Tab</button>
-      
-      <Tabs activeCode={activeTab} onChange={setActiveTab}>
-        <TabBar>
-          {tabs.map(tab => (
-            <Tab 
-              key={tab.code}
-              code={tab.code}
-              style={{ display: 'flex', alignItems: 'center', gap: '8px' }}
-            >
-              {tab.title}
-              {tabs.length > 1 && (
-                <button
-                  onClick={(e) => {
-                    e.stopPropagation();
-                    removeTab(tab.code);
-                  }}
-                  style={{ 
-                    marginLeft: '8px', 
-                    padding: '2px 4px',
-                    fontSize: '12px' 
-                  }}
-                >
-                  ×
-                </button>
-              )}
-            </Tab>
-          ))}
-        </TabBar>
-
-        {tabs.map(tab => (
-          <TabPanel key={tab.code} code={tab.code}>
-            <div>{tab.content}</div>
-          </TabPanel>
-        ))}
-      </Tabs>
-    </div>
-  );
-}
-
-// Form tabs with validation states
-function FormTabs() {
-  const [activeTab, setActiveTab] = useState('personal');
-  const [formErrors, setFormErrors] = useState<{[key: string]: boolean}>({});
-
-  const hasErrors = (tabCode: string) => formErrors[tabCode];
-
-  return (
-    <Tabs activeCode={activeTab} onChange={setActiveTab}>
-      <TabBar title="User Profile">
-        <Tab 
-          code="personal"
-          style={{ 
-            color: hasErrors('personal') ? '#dc3545' : undefined 
-          }}
-        >
-          Personal Info
-          {hasErrors('personal') && <span style={{color: '#dc3545'}}>*</span>}
-        </Tab>
-        
-        <Tab 
-          code="contact"
-          style={{ 
-            color: hasErrors('contact') ? '#dc3545' : undefined 
-          }}
-        >
-          Contact Details
-          {hasErrors('contact') && <span style={{color: '#dc3545'}}>*</span>}
-        </Tab>
-        
-        <Tab code="preferences">
-          Preferences
-        </Tab>
-      </TabBar>
-
-      <TabPanel code="personal">
-        <form>
-          <input placeholder="First Name" required />
-          <input placeholder="Last Name" required />
-          <input placeholder="Date of Birth" type="date" />
-        </form>
-      </TabPanel>
-
-      <TabPanel code="contact">
-        <form>
-          <input placeholder="Email" type="email" required />
-          <input placeholder="Phone" type="tel" />
-          <textarea placeholder="Address"></textarea>
-        </form>
-      </TabPanel>
-
-      <TabPanel code="preferences">
-        <form>
-          <label>
-            <input type="checkbox" /> Email notifications
-          </label>
-          <label>
-            <input type="checkbox" /> SMS notifications
-          </label>
-        </form>
-      </TabPanel>
-    </Tabs>
-  );
-}
-
-// Custom containers and styling
-function CustomStyledTabs() {
-  const [activeTab, setActiveTab] = useState('code');
-
-  const CustomTabsContainer = styled.div`
-    background: #f8f9fa;
-    border-radius: 8px;
-    padding: 16px;
-    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
-  `;
-
-  const CustomPanelContainer = styled.div`
-    background: white;
-    padding: 24px;
-    border-radius: 4px;
-    min-height: 200px;
-  `;
-
-  return (
-    <Tabs 
-      activeCode={activeTab} 
-      onChange={setActiveTab}
-      container={CustomTabsContainer}
-    >
-      <TabBar title="Code Editor">
-        <Tab code="code" icon={<CodeIcon />}>Code</Tab>
-        <Tab code="preview" icon={<EyeIcon />}>Preview</Tab>
-        <Tab code="console" icon={<TerminalIcon />}>Console</Tab>
-      </TabBar>
-
-      <TabPanel code="code" container={CustomPanelContainer}>
-        <pre><code>function hello() {`\n`}  console.log('Hello World!');{`\n`}}</code></pre>
-      </TabPanel>
-
-      <TabPanel code="preview" container={CustomPanelContainer}>
-        <iframe src="/preview" style={{width: '100%', height: '300px'}}></iframe>
-      </TabPanel>
-
-      <TabPanel code="console" container={CustomPanelContainer}>
-        <div style={{fontFamily: 'monospace', background: '#000', color: '#fff', padding: '12px'}}>
-          > Hello World!
-        </div>
-      </TabPanel>
-    </Tabs>
-  );
-}
-```
-
-## Props Reference
-
-### Tabs (Main Container)
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `activeCode` | `TabCode` | - | Yes | Currently active tab code |
-| `onChange` | `(code: TabCode) => void` | - | Yes | Callback when active tab changes |
-| `container` | `ElementType` | `TabsContainer` | No | Custom container component |
-| `children` | `ReactNode` | - | Yes | Tab bar and panels |
-
-### Tab (Individual Tab)
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `code` | `TabCode` | - | Yes | Unique identifier for the tab |
-| `onActivate` | `(code: TabCode) => void` | `undefined` | No | Callback when tab is activated |
-| `isDisabled` | `boolean` | `false` | No | Whether the tab is disabled |
-| `isNew` | `boolean` | `false` | No | Whether to show "new" indicator |
-| `icon` | `ReactNode` | `undefined` | No | Icon to display in the tab |
-| `children` | `ReactNode` | - | Yes | Tab label content |
-
-### TabBar (Navigation Container)
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `title` | `ReactNode` | `undefined` | No | Optional title above tabs |
-| `children` | `ReactNode` | - | Yes | Tab components |
-
-### TabPanel (Content Panel)
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `code` | `TabCode` | - | Yes | Tab code this panel belongs to |
-| `container` | `ElementType` | `TabPanelContainer` | No | Custom container component |
-| `children` | `ReactNode` | - | Yes | Panel content |
-
-## AI Agent Guidelines
-
-### Recommended Patterns
-
-1. **Controlled State**: Always use controlled tab state
-```typescript
-const [activeTab, setActiveTab] = useState('defaultTab');
-
-<Tabs activeCode={activeTab} onChange={setActiveTab}>
-  {/* tabs and panels */}
-</Tabs>
-```
-
-2. **Consistent Codes**: Use consistent, meaningful tab codes
-```typescript
-// Good - descriptive codes
-<Tab code="user-profile">Profile</Tab>
-<Tab code="account-settings">Settings</Tab>
-
-// Avoid - generic or unclear codes
-<Tab code="1">Profile</Tab>
-<Tab code="tab2">Settings</Tab>
-```
-
-3. **Panel Matching**: Ensure every Tab has a matching TabPanel
-```typescript
-<TabBar>
-  <Tab code="overview">Overview</Tab>
-  <Tab code="details">Details</Tab>
-</TabBar>
-
-<TabPanel code="overview">...</TabPanel>
-<TabPanel code="details">...</TabPanel>
-```
-
-### Common Mistakes to Avoid
-
-1. **Missing TabBar**: Don't put Tab components directly in Tabs without TabBar
-2. **Mismatched Codes**: Ensure Tab and TabPanel codes match exactly
-3. **Missing onChange**: Always provide an onChange handler
-4. **Uncontrolled State**: Don't mix controlled and uncontrolled patterns
-5. **Invalid HTML**: Tab content should be properly structured HTML
-
-### Integration Tips
-
-1. **State Management**: Works well with global state management
-```typescript
-// Redux integration
-const activeTab = useSelector(state => state.ui.activeTab);
-const dispatch = useDispatch();
-
-<Tabs 
-  activeCode={activeTab}
-  onChange={(code) => dispatch(setActiveTab(code))}
->
-```
-
-2. **Routing Integration**: Sync tabs with URL routing
-```typescript
-const navigate = useNavigate();
-const location = useLocation();
-
-const activeTab = location.pathname.split('/').pop() || 'overview';
-
-<Tabs 
-  activeCode={activeTab}
-  onChange={(code) => navigate(`/dashboard/${code}`)}
->
-```
-
-3. **Form Integration**: Use tabs for multi-step forms
-4. **Accessibility**: Components handle ARIA attributes and keyboard navigation automatically
-5. **Performance**: TabPanels only render when active (conditional rendering)
-
-## Related Components
-
-- **Button**: For tab-like button groups
-- **Modal**: For modal dialogs with tabbed content
-- **Accordion**: Alternative for collapsible content sections
-- **Drawer**: For side navigation with tab-like behavior

package/Toast/ai-documentation.md

@@ -1,220 +0,0 @@
-# Toast Component Documentation
-
-## Component Overview
-
-The Toast component provides a notification system with provider/context pattern for global toast management. It displays temporary messages to users with different types (info, success, warning, error) and supports custom content.
-
-## Component Structure
-
-- `Toast.tsx` - Main toast component with portal rendering
-- `ToastProvider.tsx` - Context provider for global toast management
-- `hooks.ts` - useToast hook for consuming toast context
-- `types.ts` - TypeScript interfaces and type definitions
-- `constants.ts` - Default values and type color mappings
-- `styles.ts` - Styled components for toast styling
-
-## TypeScript Interfaces
-
-```typescript
-export type ToastType = 'info' | 'success' | 'warning' | 'error';
-
-export type ToastParams = {
-  title: string;
-  description?: ReactNode;
-  duration: number | false;
-  type: ToastType;
-};
-
-export type OpenToastParams = {
-  title: string;
-  description?: ReactNode;
-  duration?: number;
-  type?: ToastType;
-};
-
-export interface ToastContextProps {
-  openToast: (params: OpenToastParams) => void;
-  closeToast: () => void;
-}
-
-export interface ToastProviderProps {
-  children: ReactNode;
-}
-
-export interface ToastProps {
-  open: boolean;
-  toast: ToastParams;
-  onClose: () => void;
-}
-```
-
-## Usage Examples
-
-### Basic Setup with Provider
-
-```tsx
-import { ToastProvider } from '@pushwoosh/dumb-components';
-
-function App() {
-  return (
-    <ToastProvider>
-      <YourAppContent />
-    </ToastProvider>
-  );
-}
-```
-
-### Using Toast Hook
-
-```tsx
-import { useToast } from '@pushwoosh/dumb-components';
-
-function MyComponent() {
-  const { openToast, closeToast } = useToast();
-
-  const handleSuccess = () => {
-    openToast({
-      title: 'Success!',
-      description: 'Your action was completed successfully.',
-      type: 'success',
-      duration: 3000,
-    });
-  };
-
-  const handleError = () => {
-    openToast({
-      title: 'Error occurred',
-      description: 'Please try again later.',
-      type: 'error',
-      duration: 5000,
-    });
-  };
-
-  return (
-    <div>
-      <button onClick={handleSuccess}>Show Success</button>
-      <button onClick={handleError}>Show Error</button>
-      <button onClick={closeToast}>Close Toast</button>
-    </div>
-  );
-}
-```
-
-### Toast with Custom Content
-
-```tsx
-import { useToast } from '@pushwoosh/dumb-components';
-
-function ComponentWithCustomToast() {
-  const { openToast } = useToast();
-
-  const handleCustomToast = () => {
-    openToast({
-      title: 'Custom Toast',
-      description: 'This toast has additional content.',
-      type: 'info',
-    });
-  };
-
-  return <button onClick={handleCustomToast}>Show Custom Toast</button>;
-}
-```
-
-## Props Reference
-
-### ToastProvider Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| children | ReactNode | Yes | Child components that can access toast context |
-
-### useToast Hook Returns
-
-| Property | Type | Description |
-|----------|------|-------------|
-| openToast | (params: OpenToastParams) => void | Function to open a new toast |
-| closeToast | () => void | Function to close current toast |
-
-### OpenToastParams
-
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| title | string | Yes | - | Main toast title |
-| description | ReactNode | No | - | Optional description content |
-| duration | number | No | 3000 | Toast display duration in milliseconds |
-| type | ToastType | No | 'info' | Toast type affecting icon and color |
-
-### Toast Types
-
-- `'info'` - Blue info icon with bright color
-- `'success'` - Green checkmark icon
-- `'warning'` - Orange warning icon
-- `'error'` - Red danger triangle icon
-
-## Features
-
-### Auto-dismissal
-Toasts automatically close after the specified duration (default 3000ms).
-
-### Manual Dismissal
-Users can manually close toasts using the close button or the closeToast function.
-
-### Portal Rendering
-Toasts are rendered using React portals to document.body for proper z-index layering.
-
-### Global State Management
-Single toast instance managed through React Context for application-wide access.
-
-### Type-based Styling
-Different toast types have distinct icons and border colors for visual differentiation.
-
-## Constants
-
-```typescript
-export const DEFAULT_DURATION = 3000;
-
-export const TypeColorMap = {
-  info: Color.BRIGHT,
-  success: Color.SUCCESS,
-  warning: Color.WARNING,
-  error: Color.DANGER,
-};
-```
-
-## Styling
-
-The toast uses a fixed positioning system:
-- Positioned at top center of the viewport (50px from top when open)
-- 380px width with responsive design
-- Slide animation from top (-250px when closed)
-- High z-index (999999999) for overlay display
-- Border color matches toast type
-- Large shadow for elevation
-
-## AI Agent Guidelines
-
-When working with the Toast component:
-
-1. **Provider Setup**: Always ensure ToastProvider wraps the application root for global access
-2. **Hook Usage**: Use useToast hook only within components wrapped by ToastProvider
-3. **Error Handling**: The hook throws an error if used outside of provider context
-4. **Duration Management**: Consider appropriate duration based on toast importance and content length
-5. **Type Selection**: Choose appropriate toast type based on user action outcome
-7. **Accessibility**: Toast messages should be descriptive for screen readers
-8. **Portal Rendering**: Remember that toasts render to document.body, not inline
-9. **Single Instance**: Only one toast displays at a time; new toasts replace current ones
-10. **Manual Control**: Provide manual close options for important messages or longer durations
-
-### Common Use Cases
-- Success confirmations after form submissions
-- Error messages for failed operations
-- Information notices about system changes
-- Warning messages before destructive actions
-- Progress notifications with custom action buttons
-
-### Best Practices
-- Keep titles concise and descriptive
-- Use descriptions for additional context
-- Choose appropriate durations (3s for success, 5s+ for errors)
-- Provide manual close for critical messages
-- Test toast behavior in different viewport sizes