@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/Button/ai-documentation.md

@@ -1,247 +0,0 @@
-# Button - AI Documentation
-
-> Auto-generated AI agent documentation for Button component
-> Part of @pushwoosh/dumb-components library
-
-## Overview
-
-**Component:** Button, GhostButton, RemoveButton
-**Import Path:** `import { Button, GhostButton, RemoveButton } from '@pushwoosh/dumb-components'`
-**Files:** Button.tsx, GhostButton.tsx, RemoveButton.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 and a RemoveButton for compact "close/remove" affordances.
-
-## 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, RemoveButton } 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
-// Note: kit-icons require `size` and `view`. Match icon size to Button size:
-// Button size="field" (default) → icon size="medium"
-// Button size="compact"          → icon size="small"
-<Button
-  color="secondary"
-  icon={<PlusIcon size="medium" view="lined" />}
-  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 (size="small" matches size="compact")
-<Button
-  color="primary"
-  size="compact"
-  rightIcon={<ArrowIcon size="small" view="lined" />}
->
-  Next
-</Button>
-
-// Ghost view button
-<Button
-  color="primary"
-  view="ghost"
-  icon={<EditIcon size="medium" view="lined" />}
->
-  Edit
-</Button>
-
-// Icon-only button
-<Button
-  color="secondary"
-  icon={<SearchIcon size="medium" view="lined" />}
-  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;
-`;
-```
-
-## RemoveButton Usage
-
-A compact icon-only button with a built-in `CloseIcon` intended for "remove" / "dismiss" affordances. It has fixed `16x16` size and switches its color to `DANGER_HOVER` / `DANGER_PRESSED` on interaction.
-
-**Props:** accepts all native `<button>` props except `ref` and `children` (the icon is rendered internally).
-
-```tsx
-<RemoveButton
-  type="button"
-  aria-label="Remove item"
-  onClick={() => handleRemove(item.id)}
-/>
-```
-
-## 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. For `@pushwoosh/kit-icons` icons, pass `size` and `view` explicitly (both required). Match icon `size` to Button `size`: `size="medium"` for `field` (default), `size="small"` for `compact`. |
-| rightIcon | ReactNode | undefined | Right icon element. Same icon size/view rules as `icon`. |
-| 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
-- Don't pass icons without `size` and `view` — they are required on `@pushwoosh/kit-icons` and TypeScript won't catch it (Button's `icon` is typed as `ReactNode`)
-- Don't mismatch icon size to button size: `size="small"` icons belong only in `size="compact"` buttons; `field`-sized buttons need `size="medium"` icons
-- 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.md

@@ -1,277 +0,0 @@
-# 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
-
----