@pushwoosh/dumb-components 1.1.147 → 1.1.149

package/Checkbox/ai-documentation.md

@@ -1,231 +0,0 @@
-# Checkbox - AI Documentation
-
-> Auto-generated AI agent documentation for Checkbox component
-> Part of @pushwoosh/dumb-components library
-
-## Overview
-
-**Component:** Checkbox
-**Import Path:** `import { Checkbox } from '@pushwoosh/dumb-components'`
-**Files:** Checkbox.tsx, types.ts, styles.ts, maps.ts, index.ts
-**Type:** Form Component / Input Component
-**Description:** Checkbox component with label support, tooltip integration, indeterminate state, and error styling for form inputs
-
-## TypeScript Interface
-
-```typescript
-type CheckboxType = 'normal' | 'error';
-
-interface CheckboxProps {
-  label?: ReactNode;
-  id?: string;
-  name?: string;
-  value?: string | number;
-  type?: CheckboxType;
-  isChecked?: boolean;
-  isDisabled?: boolean;
-  isIndeterminate?: boolean;
-  tooltip?: string;
-  activeCheckboxColor?: string;
-  onChange?: (checked: boolean) => void;
-}
-```
-
-## Import & Usage
-
-**Import:**
-```typescript
-import { Checkbox } from '@pushwoosh/dumb-components';
-import type { CheckboxProps, CheckboxType } from '@pushwoosh/dumb-components';
-```
-
-**Basic Usage:**
-```tsx
-function App() {
-  const [isChecked, setIsChecked] = useState(false);
-  
-  return (
-    <Checkbox 
-      label="Accept terms and conditions"
-      isChecked={isChecked}
-      onChange={setIsChecked}
-    />
-  );
-}
-```
-
-**Advanced Examples:**
-```tsx
-// Form checkbox with validation
-const [agreedToTerms, setAgreedToTerms] = useState(false);
-const [hasError, setHasError] = useState(false);
-
-<Checkbox 
-  label="I agree to the terms and conditions"
-  isChecked={agreedToTerms}
-  type={hasError ? 'error' : 'normal'}
-  onChange={(checked) => {
-    setAgreedToTerms(checked);
-    setHasError(false);
-  }}
-/>
-
-// Checkbox with tooltip
-<Checkbox 
-  label="Enable advanced features"
-  isChecked={enableAdvanced}
-  tooltip="This will unlock additional configuration options"
-  onChange={setEnableAdvanced}
-/>
-
-// Indeterminate state (for "select all" scenarios)
-<Checkbox 
-  label="Select all items"
-  isChecked={selectedItems.length === totalItems}
-  isIndeterminate={selectedItems.length > 0 && selectedItems.length < totalItems}
-  onChange={(checked) => {
-    if (checked) {
-      selectAllItems();
-    } else {
-      deselectAllItems();
-    }
-  }}
-/>
-
-// Disabled checkbox
-<Checkbox 
-  label="This feature is not available"
-  isChecked={false}
-  isDisabled={true}
-/>
-
-// Custom color and form integration
-<form>
-  <Checkbox 
-    name="newsletter"
-    value="subscribe"
-    label="Subscribe to newsletter"
-    isChecked={formData.newsletter}
-    activeCheckboxColor="#007bff"
-    onChange={(checked) => 
-      setFormData(prev => ({ ...prev, newsletter: checked }))
-    }
-  />
-</form>
-
-// List of checkboxes
-{options.map(option => (
-  <Checkbox 
-    key={option.id}
-    label={option.label}
-    isChecked={selectedOptions.includes(option.id)}
-    onChange={(checked) => handleOptionChange(option.id, checked)}
-  />
-))}
-
-// Error state with validation
-<Checkbox 
-  label="Required field"
-  isChecked={isChecked}
-  type={showErrors && !isChecked ? 'error' : 'normal'}
-  onChange={setIsChecked}
-  tooltip={showErrors && !isChecked ? 'This field is required' : undefined}
-/>
-```
-
-## Props Reference
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| label | ReactNode | undefined | Text or element to display next to checkbox |
-| isChecked | boolean | undefined | Whether checkbox is checked |
-| isDisabled | boolean | false | Whether checkbox is disabled |
-| isIndeterminate | boolean | false | Whether checkbox shows indeterminate state |
-| type | 'normal' \| 'error' | 'normal' | Visual style variant |
-| onChange | (checked: boolean) => void | undefined | Callback when checkbox state changes |
-| id | string | auto-generated | HTML id attribute |
-| name | string | undefined | HTML name attribute for forms |
-| value | string \| number | undefined | HTML value attribute |
-| tooltip | string | undefined | Tooltip text to show with question mark |
-| activeCheckboxColor | string | undefined | Custom color for active state |
-
-## AI Agent Guidelines
-
-### ✅ Recommended Patterns
-- Always handle `onChange` to make checkbox controllable
-- Use `type="error"` for validation feedback
-- Add `tooltip` for complex or unclear options
-- Use `isIndeterminate` for "select all" scenarios
-- Provide meaningful labels for accessibility
-- Use `name` and `value` props in forms for proper data collection
-
-### ❌ Common Mistakes to Avoid
-- Don't forget to handle `onChange` - checkbox won't work without it
-- Avoid very long labels - consider using tooltip for details
-- Don't use disabled state unless absolutely necessary
-- Don't rely only on color for error states - use clear labels
-- Avoid custom colors unless part of consistent design system
-
-### Integration Tips
-- Works well with form libraries like react-hook-form
-- Can be grouped for multiple selections
-- Combines effectively with validation libraries
-- Use with consistent spacing in checkbox groups
-- Good for settings panels and preference forms
-
-## States and Behavior
-
-### Visual States
-- **Normal**: Default unchecked state
-- **Checked**: User selected state
-- **Indeterminate**: Partially selected (mixed state)
-- **Disabled**: Non-interactive state
-- **Error**: Validation error state
-
-### Accessibility Features
-- **Auto-generated IDs**: Ensures proper label association
-- **Keyboard Navigation**: Supports space bar and tab navigation
-- **Screen Reader Support**: Proper labeling and state communication
-- **Focus Management**: Visible focus indicators
-
-## Common Patterns
-
-### Select All Checkbox
-```tsx
-const isAllSelected = selectedItems.length === allItems.length;
-const isIndeterminate = selectedItems.length > 0 && selectedItems.length < allItems.length;
-
-<Checkbox 
-  label="Select all"
-  isChecked={isAllSelected}
-  isIndeterminate={isIndeterminate}
-  onChange={(checked) => {
-    if (checked) {
-      setSelectedItems([...allItems]);
-    } else {
-      setSelectedItems([]);
-    }
-  }}
-/>
-```
-
-### Form Validation
-```tsx
-<Checkbox 
-  label="I have read and agree to the terms"
-  isChecked={agreedToTerms}
-  type={submitted && !agreedToTerms ? 'error' : 'normal'}
-  onChange={setAgreedToTerms}
-/>
-{submitted && !agreedToTerms && (
-  <span>You must agree to the terms to continue</span>
-)}
-```
-
-## Related Components
-- Radio - for single selection from multiple options
-- Switch - for on/off toggles
-- TooltipTrigger - used internally for tooltip functionality
-- Button - for form submission actions
-
----

package/Chip/ai-documentation.md

@@ -1,281 +0,0 @@
-# Chip - AI Documentation
-
-> Auto-generated AI agent documentation for Chip component
-> Part of @pushwoosh/dumb-components library
-
-## Overview
-
-**Component:** Chip
-**Import Path:** `import { Chip } from '@pushwoosh/dumb-components'`
-**Files:** Chip.tsx, Chip.types.ts, styles.ts, Chip.constants.ts, index.ts
-**Type:** UI Component / Interactive Tag
-**Description:** Chip component for displaying tags, filters, or removable items with optional close functionality and multiple variants
-
-## TypeScript Interface
-
-```typescript
-type ChipVariant = 'primary' | 'danger' | 'warning';
-
-interface ChipProps extends PropsWithChildren<HTMLAttributes<HTMLDivElement>> {
-  $variant?: ChipVariant;
-  $selected?: boolean;
-  $onClose?: HTMLAttributes<HTMLDivElement>['onClick'];
-  $readOnly?: boolean;
-  $maxWidth?: string;
-  $icon?: ReactNode;
-  $tooltip?: ReactNode;
-  as?: string;
-}
-```
-
-## Import & Usage
-
-**Import:**
-```typescript
-import { Chip } from '@pushwoosh/dumb-components';
-import type { ChipProps, ChipVariant } from '@pushwoosh/dumb-components';
-```
-
-**Basic Usage:**
-```tsx
-function App() {
-  return (
-    <Chip $variant="primary">
-      JavaScript
-    </Chip>
-  );
-}
-```
-
-**Advanced Examples:**
-```tsx
-// Basic tags/categories
-<Chip $variant="primary">React</Chip>
-<Chip $variant="primary">TypeScript</Chip>
-<Chip $variant="warning">Beta</Chip>
-
-// Selected state for filters
-<Chip 
-  $variant="primary" 
-  $selected={selectedTags.includes('react')}
-  onClick={() => toggleTag('react')}
->
-  React
-</Chip>
-
-// Removable chips with close button
-<Chip 
-  $variant="primary"
-  $onClose={() => removeTag('javascript')}
->
-  JavaScript
-</Chip>
-
-// Read-only chips (non-interactive)
-<Chip $variant="warning" $readOnly>
-  Deprecated
-</Chip>
-
-// Different variants for semantic meaning
-<Chip $variant="danger" $onClose={() => removeError(errorId)}>
-  Error: Invalid input
-</Chip>
-<Chip $variant="warning">
-  Warning: Slow query
-</Chip>
-<Chip $variant="primary" $selected>
-  Active filter
-</Chip>
-
-// Filter chips with selection state
-{filters.map(filter => (
-  <Chip
-    key={filter.id}
-    $variant="primary"
-    $selected={activeFilters.includes(filter.id)}
-    onClick={() => toggleFilter(filter.id)}
-  >
-    {filter.name}
-  </Chip>
-))}
-
-// Tag management with removal
-{tags.map(tag => (
-  <Chip
-    key={tag}
-    $variant="primary"
-    $onClose={() => handleRemoveTag(tag)}
-  >
-    {tag}
-  </Chip>
-))}
-
-// Custom element rendering
-<Chip 
-  as="a" 
-  href={`/tags/${tag.slug}`}
-  $variant="primary"
->
-  {tag.name}
-</Chip>
-
-import { TagIcon } from '@pushwoosh/kit-icons';
-
-// Chip with leading icon
-<Chip $variant="primary" $icon={<TagIcon size="small" view="lined" />}>
-  Segment
-</Chip>
-
-// Icon + removable
-<Chip
-  $icon={<TagIcon size="small" view="lined" />}
-  $onClose={() => removeTag(tag)}
->
-  {tag}
-</Chip>
-
-// Read-only chip with "?" tooltip
-<Chip $readOnly $variant="primary" $tooltip="Explanation for this chip">
-  Label
-</Chip>
-
-// Status chips
-function getStatusChip(status: string) {
-  const variantMap = {
-    active: 'primary',
-    warning: 'warning', 
-    error: 'danger'
-  } as const;
-  
-  return (
-    <Chip $variant={variantMap[status] || 'primary'}>
-      {status.toUpperCase()}
-    </Chip>
-  );
-}
-```
-
-## Props Reference
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| $variant | 'primary' \| 'danger' \| 'warning' | 'primary' | Visual style variant |
-| $selected | boolean | false | Whether chip appears in selected state |
-| $onClose | onClick handler | undefined | Makes chip removable with close icon |
-| $maxWidth | string | undefined | CSS max-width; truncates label with ellipsis |
-| $icon | ReactNode | undefined | Leading icon slot; pass a kit-icon with size="small" |
-| $tooltip | ReactNode | undefined | Tooltip content; renders a trailing "?" trigger on read-only chips |
-| $readOnly | boolean | false | Whether chip is interactive |
-| as | string | 'div' | HTML element to render as |
-| children | ReactNode | required | Chip content |
-| ...rest | HTMLDivElement props | | All standard div props (onClick, className, etc.) |
-
-## Variant Guide
-
-| Variant | Usage | Example Use Cases |
-|---------|-------|-------------------|
-| primary | Default, neutral items | Tags, categories, selected filters |
-| danger | Errors, removable warnings | Error messages, dangerous actions |
-| warning | Cautions, temporary states | Beta features, warnings, alerts |
-
-## Hover States
-
-Each variant darkens its background and tint on hover. Hover is only applied to
-interactive chips — it is intentionally disabled when `$selected` (selected chips
-keep the solid `MAIN` background) or `$readOnly` (non-interactive).
-
-| Variant | Background → hover | Tint → hover |
-|---------|--------------------|--------------|
-| primary | BRIGHT_LIGHT → BRIGHT_LIGHT_HOVER | PRIMARY → PRIMARY_HOVER |
-| danger | DANGER_LIGHT → DANGER_LIGHT_HOVER | DANGER → DANGER_HOVER |
-| warning | WARNING_LIGHT → WARNING_LIGHT_HOVER | WARNING → WARNING_HOVER |
-
-## AI Agent Guidelines
-
-### ✅ Recommended Patterns
-- Use `$variant="primary"` for most tags and filters
-- Add `$onClose` for removable items like user-added tags
-- Use `$selected` state for active filters or selections
-- Keep chip text short and descriptive
-- Use semantic variants (danger for errors, warning for cautions)
-- Group related chips together with consistent spacing
-- When adding a leading icon, always use `size="small"` so it fits the chip's 24px height; pass `view` too if the icon defines one
-- Slots are fixed: leading `$icon` on the left; the right side holds exactly one element — the close button on active chips (`$onClose`), or the `$tooltip` "?" trigger on read-only chips. A read-only chip never shows a close button, and the close button + tooltip are mutually exclusive.
-
-### ❌ Common Mistakes to Avoid
-- Don't use chips for very long text content
-- Avoid mixing too many variants in the same group
-- Don't make read-only chips look interactive
-- Avoid using chips for primary navigation
-- Don't nest interactive elements inside chips
-
-### Integration Tips
-- Works well in filter interfaces for multi-select options
-- Effective for tag management systems
-- Can be used in search interfaces for search terms
-- Good for displaying categories, skills, or attributes
-- Combines well with input fields for tag creation
-
-## Interaction Patterns
-
-### Filter Chips
-```tsx
-// Multi-select filter
-{availableFilters.map(filter => (
-  <Chip
-    key={filter.id}
-    $variant="primary"
-    $selected={selectedFilters.includes(filter.id)}
-    onClick={() => {
-      if (selectedFilters.includes(filter.id)) {
-        setSelectedFilters(prev => prev.filter(id => id !== filter.id));
-      } else {
-        setSelectedFilters(prev => [...prev, filter.id]);
-      }
-    }}
-  >
-    {filter.name}
-  </Chip>
-))}
-```
-
-### Tag Management
-```tsx
-// Add/remove tags
-const [tags, setTags] = useState(['react', 'typescript']);
-
-// Display with remove functionality
-{tags.map(tag => (
-  <Chip
-    key={tag}
-    $onClose={() => setTags(prev => prev.filter(t => t !== tag))}
-  >
-    {tag}
-  </Chip>
-))}
-
-// Add new tag
-<input 
-  onKeyPress={(e) => {
-    if (e.key === 'Enter' && e.target.value) {
-      setTags(prev => [...prev, e.target.value]);
-      e.target.value = '';
-    }
-  }}
-  placeholder="Add tag..."
-/>
-```
-
-## Accessibility Features
-- **Keyboard Navigation**: Supports focus and interaction via keyboard
-- **ARIA Support**: Proper roles and states for screen readers
-- **Focus Management**: Clear focus indicators
-- **Close Button**: Accessible close functionality when removable
-
-## Related Components
-- Badge - for status indicators without interaction
-- Button - for more prominent actions
-- Tag - alternative naming for similar functionality
-- Filter components - for complex filtering interfaces
-
----