@pushwoosh/dumb-components 1.1.40 → 1.1.41

package/Button/ai-documentation.mdx

@@ -0,0 +1,228 @@
+# Button - AI Documentation
+
+> Auto-generated AI agent documentation for Button component
+> Part of @pushwoosh/dumb-components library
+
+## Overview
+
+**Component:** Button, GhostButton
+**Import Path:** `import { Button, GhostButton } from '@pushwoosh/dumb-components'`
+**Files:** Button.tsx, GhostButton.tsx, types.ts, styles.ts, maps.ts, index.ts
+**Type:** UI Component / Form Component
+**Description:** Versatile button component with loading states, icons, and multiple styling variants. Also includes a minimal GhostButton for unstyled interactions.
+
+## TypeScript Interface
+
+```typescript
+type RequiredButtonProps = {
+  readonly boxRef?: any;
+  readonly color: 'primary' | 'secondary' | 'danger';
+  readonly size?: 'field' | 'compact';
+  readonly view?: 'shape' | 'ghost';
+  readonly className?: string;
+  readonly isDisabled?: boolean;
+  readonly isLoading?: boolean;
+  readonly isOpen?: boolean;
+  readonly icon?: ReactNode;
+  readonly rightIcon?: ReactNode;
+  readonly children?: ReactNode;
+};
+
+// Main button props extending HTML button
+type ButtonPropsWithoutAs = Omit<JSX.IntrinsicElements['button'], 'ref'> & RequiredButtonProps & {
+  readonly boxRef?: Ref<HTMLButtonElement>;
+  readonly type?: 'button' | 'submit';
+};
+
+// Can be rendered as different HTML elements
+type ButtonPropsWithAsTag<AS extends keyof HTMLElementTagNameMap> = 
+  Omit<JSX.IntrinsicElements[AS], 'ref'> & RequiredButtonProps & {
+    readonly boxRef?: Ref<HTMLElementTagNameMap[AS]>;
+    readonly as?: AS;
+  };
+```
+
+## Import & Usage
+
+**Import:**
+```typescript
+import { Button, GhostButton } from '@pushwoosh/dumb-components';
+import type { 
+  ButtonPropsWithoutAs, 
+  ButtonPropsWithAsTag, 
+  RequiredButtonProps 
+} from '@pushwoosh/dumb-components';
+```
+
+**Basic Usage:**
+```tsx
+function App() {
+  return (
+    <Button color="primary">
+      Click me
+    </Button>
+  );
+}
+```
+
+**Advanced Examples:**
+```tsx
+// Primary action button
+<Button 
+  color="primary" 
+  size="field"
+  onClick={() => handleSave()}
+>
+  Save Changes
+</Button>
+
+// Secondary button with icon
+<Button 
+  color="secondary" 
+  icon={<PlusIcon />}
+  onClick={() => handleAdd()}
+>
+  Add Item
+</Button>
+
+// Danger button with loading state
+<Button 
+  color="danger"
+  isLoading={isDeleting}
+  onClick={() => handleDelete()}
+>
+  {isDeleting ? 'Deleting...' : 'Delete'}
+</Button>
+
+// Compact button with right icon
+<Button 
+  color="primary"
+  size="compact"
+  rightIcon={<ArrowIcon />}
+>
+  Next
+</Button>
+
+// Ghost view button
+<Button 
+  color="primary"
+  view="ghost"
+  icon={<EditIcon />}
+>
+  Edit
+</Button>
+
+// Icon-only button
+<Button 
+  color="secondary"
+  icon={<SearchIcon />}
+  onClick={() => handleSearch()}
+/>
+
+// Submit button for forms
+<Button 
+  type="submit"
+  color="primary"
+  isDisabled={!isFormValid}
+>
+  Submit Form
+</Button>
+
+// Button as different element (link)
+<Button 
+  as="a"
+  href="/dashboard"
+  color="primary"
+>
+  Go to Dashboard
+</Button>
+
+// With loading overlay
+<Button 
+  color="primary"
+  isLoading={isSubmitting}
+  onClick={handleAsyncSubmit}
+>
+  Submit
+</Button>
+```
+
+## GhostButton Usage
+
+```tsx
+// Minimal unstyled button
+<GhostButton onClick={() => handleClick()}>
+  <CustomIcon />
+</GhostButton>
+
+// For custom styled buttons
+const CustomButton = styled(GhostButton)`
+  /* Your custom styles */
+  padding: 8px 16px;
+  color: blue;
+`;
+```
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| color | 'primary' \| 'secondary' \| 'danger' | required | Button color scheme |
+| size | 'field' \| 'compact' | 'field' | Button size variant |
+| view | 'shape' \| 'ghost' | 'shape' | Button visual style |
+| type | 'button' \| 'submit' | 'button' | HTML button type |
+| isDisabled | boolean | false | Whether button is disabled |
+| isLoading | boolean | false | Whether button shows loading state |
+| isOpen | boolean | false | Whether button appears in "open" state |
+| icon | ReactNode | undefined | Left icon element |
+| rightIcon | ReactNode | undefined | Right icon element |
+| children | ReactNode | undefined | Button text content |
+| boxRef | Ref | undefined | Ref to button element |
+| as | string \| Component | undefined | Render as different element/component |
+
+## Color Guide
+
+| Color | Usage | Example Use Cases |
+|-------|--------|-------------------|
+| primary | Main actions, primary CTA | "Save", "Submit", "Continue" |
+| secondary | Secondary actions, alternatives | "Cancel", "Back", "Skip" |
+| danger | Destructive actions | "Delete", "Remove", "Clear" |
+
+## AI Agent Guidelines
+
+### ✅ Recommended Patterns
+- Always provide `color` prop (required)
+- Use `color="primary"` for main actions, `"secondary"` for alternatives
+- Use `color="danger"` for destructive actions like delete
+- Combine `isLoading` with async operations
+- Use `size="compact"` in space-constrained layouts
+- Add icons to improve recognition and usability
+- Use `type="submit"` in forms for proper form submission
+
+### ❌ Common Mistakes to Avoid
+- Missing required `color` prop will render nothing and log error
+- Don't use loading state without showing loading text to user
+- Avoid putting buttons inside other interactive elements
+- Don't use `isDisabled` with `isLoading` simultaneously
+- Avoid very long button text - keep concise
+
+### Integration Tips
+- Works seamlessly with form libraries like react-hook-form
+- Loading state automatically shows spinner overlay
+- Can render as links or other elements using `as` prop
+- Icon-only buttons should have proper aria-labels
+- Combine with Tooltip for additional context when needed
+
+## Loading Behavior
+- **With icon**: Replaces icon with spinner
+- **Text only**: Shows overlay spinner while hiding text
+- **Ghost view**: Shows inline spinner, no overlay
+- **Icon + text**: Icon becomes spinner, text remains visible
+
+## Related Components
+- GhostButton - for unstyled button base
+- Link - for navigation actions
+- IconButton - specialized icon-only buttons
+- Spinner - used internally for loading states
+
+---

package/CardMetric/ai-documentation.mdx

@@ -0,0 +1,277 @@
+# CardMetric - AI Documentation
+
+> Auto-generated AI agent documentation for CardMetric component
+> Part of @pushwoosh/dumb-components library
+
+## Overview
+
+**Component:** CardMetric
+**Import Path:** `import { CardMetric } from '@pushwoosh/dumb-components'`
+**Files:** CardMetric.tsx, CardChildren.tsx, CardCollapse.tsx, types.ts, styles.tsx, index.ts
+**Type:** Data Display Component / Dashboard Component
+**Description:** Card component for displaying metrics and data with optional collapsible content, loading states, and tooltips
+
+## TypeScript Interface
+
+```typescript
+interface CardMetricProps {
+  view?: 'rounded' | 'stacking';
+  focus?: boolean;
+  title?: string | ReactElement;
+  tooltip?: string;
+  loading?: boolean;
+  collapse?: {
+    isCollapsed: boolean;
+  };
+  description?: string;
+  metric?: string | number;
+  extraMetric?: string | number;
+  extraMetricColor?: string;
+  headerExtra?: ReactElement;
+  children?: ReactNode;
+  [key: string]: any; // Additional HTML props
+}
+```
+
+## Import & Usage
+
+**Import:**
+```typescript
+import { CardMetric } from '@pushwoosh/dumb-components';
+import type { CardMetricProps } from '@pushwoosh/dumb-components';
+```
+
+**Basic Usage:**
+```tsx
+function App() {
+  return (
+    <CardMetric 
+      title="Total Users"
+      metric="1,234"
+    />
+  );
+}
+```
+
+**Advanced Examples:**
+```tsx
+// Basic metric card
+<CardMetric 
+  title="Revenue"
+  metric="$45,678"
+  extraMetric="+12%"
+  extraMetricColor="#22c55e"
+/>
+
+// Card with tooltip
+<CardMetric 
+  title="Conversion Rate"
+  tooltip="Percentage of visitors who completed a purchase"
+  metric="3.4%"
+  extraMetric="+0.2%"
+/>
+
+// Card with children content
+<CardMetric 
+  title="Monthly Sales"
+  metric="$125,000"
+>
+  <div>
+    <p>Last month: $118,000</p>
+    <p>Growth: 5.9%</p>
+  </div>
+</CardMetric>
+
+// Collapsible card
+<CardMetric 
+  title="Detailed Analytics"
+  metric="98.5%"
+  collapse={{ isCollapsed: false }}
+>
+  <div>
+    <h4>Performance Breakdown:</h4>
+    <ul>
+      <li>Page Load: 2.3s</li>
+      <li>Time to Interactive: 3.1s</li>
+      <li>First Paint: 1.8s</li>
+    </ul>
+  </div>
+</CardMetric>
+
+// Loading state
+<CardMetric 
+  title="Loading Data..."
+  loading={isLoading}
+>
+  <p>Please wait while we fetch the latest metrics.</p>
+</CardMetric>
+
+// Stacking view with header extra
+<CardMetric 
+  view="stacking"
+  title="User Engagement"
+  metric="2,156"
+  headerExtra={<Button size="compact">View Details</Button>}
+>
+  <p>Daily active users for the past 30 days</p>
+</CardMetric>
+
+// Focused card (highlighted)
+<CardMetric 
+  view="rounded"
+  focus={true}
+  title="Key Metric"
+  metric="87%"
+  extraMetric="Target: 90%"
+  description="This is the most important metric to track"
+/>
+
+// Dashboard grid
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '16px' }}>
+  <CardMetric title="Orders" metric="1,428" extraMetric="+15%" />
+  <CardMetric title="Revenue" metric="$89,204" extraMetric="+8.2%" />
+  <CardMetric title="Customers" metric="892" extraMetric="+23%" />
+  <CardMetric title="Conversion" metric="4.2%" extraMetric="-0.1%" />
+</div>
+
+// With custom content and description
+<CardMetric 
+  title="Server Status"
+  metric="99.9%"
+  description="Uptime for the last 30 days"
+>
+  <div>
+    <div style={{ display: 'flex', gap: '8px', marginBottom: '8px' }}>
+      <Badge color="green">Healthy</Badge>
+      <Badge color="orange">2 Warnings</Badge>
+    </div>
+    <p>Last incident: 3 days ago</p>
+  </div>
+</CardMetric>
+```
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| title | string \| ReactElement | '' | Card title text or element |
+| metric | string \| number | undefined | Main metric value to display |
+| extraMetric | string \| number | undefined | Additional metric (e.g., change percentage) |
+| extraMetricColor | string | Color.MAIN | Color for extra metric text |
+| view | 'rounded' \| 'stacking' | 'rounded' | Card visual style |
+| focus | boolean | false | Whether card should appear highlighted |
+| loading | boolean | false | Whether to show loading spinner |
+| tooltip | string | '' | Tooltip text for info icon |
+| description | string | '' | Description text at bottom of card |
+| collapse | { isCollapsed: boolean } | undefined | Collapsible functionality config |
+| headerExtra | ReactElement | undefined | Extra content in header (buttons, etc.) |
+| children | ReactNode | undefined | Main card content |
+
+## View Types
+
+| View | Description | Best Used For |
+|------|-------------|---------------|
+| rounded | Standard rounded corners | Most dashboard cards, metrics |
+| stacking | Stackable layout style | Dense layouts, card groups |
+
+## AI Agent Guidelines
+
+### ✅ Recommended Patterns
+- Use meaningful titles that clearly describe the metric
+- Include `extraMetric` to show trends or comparisons
+- Add `tooltip` for complex metrics that need explanation
+- Use `loading={true}` during data fetching
+- Group related metrics using consistent `view` types
+- Use `focus={true}` to highlight the most important metric
+
+### ❌ Common Mistakes to Avoid
+- Don't show raw loading states without proper loading prop
+- Avoid very long titles - keep them concise
+- Don't mix view types randomly in the same layout
+- Don't use collapse for simple content that doesn't need hiding
+- Avoid putting too much content in children - keep it focused
+
+### Integration Tips
+- Works well in dashboard grid layouts
+- Combine with charts and graphs in children content
+- Use consistent color schemes for extraMetric across related cards
+- Good for KPI displays and analytics dashboards
+- Can contain other components like charts, lists, or buttons
+
+## Color Coding for Extra Metrics
+
+```tsx
+// Semantic colors for trends
+const getTrendColor = (value: number) => {
+  if (value > 0) return '#22c55e'; // Green for positive
+  if (value < 0) return '#ef4444'; // Red for negative
+  return '#64748b'; // Gray for neutral
+};
+
+<CardMetric 
+  title="Sales Growth"
+  metric="$45,000"
+  extraMetric={`${trend > 0 ? '+' : ''}${trend}%`}
+  extraMetricColor={getTrendColor(trend)}
+/>
+```
+
+## Common Patterns
+
+### Dashboard Grid
+```tsx
+function Dashboard() {
+  const metrics = [
+    { title: 'Total Sales', value: '$125,400', change: '+12%', positive: true },
+    { title: 'New Customers', value: '1,234', change: '+8%', positive: true },
+    { title: 'Bounce Rate', value: '32%', change: '-2%', positive: true },
+    { title: 'Avg. Order', value: '$89', change: '+5%', positive: true },
+  ];
+
+  return (
+    <div className="dashboard-grid">
+      {metrics.map(metric => (
+        <CardMetric 
+          key={metric.title}
+          title={metric.title}
+          metric={metric.value}
+          extraMetric={metric.change}
+          extraMetricColor={metric.positive ? '#22c55e' : '#ef4444'}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+### Detailed Analytics Card
+```tsx
+<CardMetric 
+  title="Website Performance"
+  metric="98.2%"
+  extraMetric="Last 24h"
+  collapse={{ isCollapsed: false }}
+  tooltip="Overall website performance score based on speed, accessibility, and SEO"
+>
+  <div>
+    <div style={{ marginBottom: '12px' }}>
+      <strong>Performance Breakdown:</strong>
+    </div>
+    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '8px' }}>
+      <div>Speed: 95%</div>
+      <div>Accessibility: 100%</div>
+      <div>SEO: 98%</div>
+      <div>Best Practices: 100%</div>
+    </div>
+  </div>
+</CardMetric>
+```
+
+## Related Components
+- StatisticCard - alternative metric display component
+- Badge - for status indicators within cards
+- Spinner - used internally for loading states
+- Tooltip - used internally for info tooltips
+- Button - commonly used in headerExtra
+
+---