@pushwoosh/dumb-components 1.1.39 → 1.1.41

package/Tabs/ai-documentation.mdx

@@ -0,0 +1,475 @@
+# 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.mdx

@@ -0,0 +1,230 @@
+# 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?: string;
+  duration: number;
+  type: ToastType;
+  additionalContent?: ReactNode;
+};
+
+export type OpenToastParams = {
+  title: string;
+  description?: string;
+  duration?: number;
+  type?: ToastType;
+  additionalContent?: ReactNode;
+};
+
+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',
+      additionalContent: (
+        <div style={{ marginTop: 8 }}>
+          <button>Action 1</button>
+          <button>Action 2</button>
+        </div>
+      ),
+    });
+  };
+
+  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 | string | No | - | Optional description text |
+| duration | number | No | 3000 | Toast display duration in milliseconds |
+| type | ToastType | No | 'info' | Toast type affecting icon and color |
+| additionalContent | ReactNode | No | - | Custom content to display below description |
+
+### 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
+6. **Custom Content**: Use additionalContent for action buttons or extra information
+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