@pushwoosh/dumb-components 1.1.147 → 1.1.149

package/Radio/ai-documentation.md

@@ -1,243 +0,0 @@
-# Radio Component - @pushwoosh/dumb-components
-
-## Overview
-
-- **Component Name**: Radio
-- **Import Path**: `@pushwoosh/dumb-components`
-- **Files**:
-  - `/src/Radio/Radio.tsx` - Main component implementation
-  - `/src/Radio/types.ts` - TypeScript type definitions
-  - `/src/Radio/styles.ts` - Styled components
-  - `/src/Radio/mappers.ts` - Color mapping utilities
-  - `/src/Radio/index.ts` - Component exports
-- **Type**: Form Control
-- **Description**: A radio button input component with label, tooltip support, and customizable styling. Supports both regular and compact sizes with normal and error states.
-
-## TypeScript Interfaces
-
-```typescript
-export type RadioType = 'normal' | 'error';
-
-export type RadioSize = 'regular' | 'compact';
-
-export type RadioProps = {
-  label?: string;
-  id?: string;
-  name?: string;
-  value?: string;
-  type?: RadioType;
-  isChecked?: boolean;
-  isDisabled?: boolean;
-  size?: RadioSize;
-  tooltip?: string;
-  onChange?: (checked: string | number) => void;
-  onBlur?: () => void;
-};
-```
-
-## Import & Usage
-
-```typescript
-import { Radio } from '@pushwoosh/dumb-components';
-
-// Basic usage
-function MyComponent() {
-  const [selected, setSelected] = useState('');
-
-  return (
-    <Radio
-      label="Option 1"
-      name="options"
-      value="option1"
-      isChecked={selected === 'option1'}
-      onChange={(value) => setSelected(value)}
-    />
-  );
-}
-
-// Radio group
-function RadioGroup() {
-  const [selected, setSelected] = useState('option1');
-
-  return (
-    <div>
-      <Radio
-        label="First Option"
-        name="radioGroup"
-        value="option1"
-        isChecked={selected === 'option1'}
-        onChange={setSelected}
-      />
-      <Radio
-        label="Second Option"
-        name="radioGroup"
-        value="option2"
-        isChecked={selected === 'option2'}
-        onChange={setSelected}
-      />
-    </div>
-  );
-}
-```
-
-## Advanced Examples
-
-```typescript
-// Radio with tooltip
-function RadioWithTooltip() {
-  return (
-    <Radio
-      label="Advanced Setting"
-      name="settings"
-      value="advanced"
-      tooltip="This enables advanced configuration options"
-      onChange={(value) => console.log(value)}
-    />
-  );
-}
-
-// Error state radio
-function ErrorStateRadio() {
-  return (
-    <Radio
-      label="Invalid Option"
-      name="validation"
-      value="invalid"
-      type="error"
-      onChange={(value) => console.log(value)}
-    />
-  );
-}
-
-// Disabled radio
-function DisabledRadio() {
-  return (
-    <Radio
-      label="Unavailable Option"
-      name="options"
-      value="unavailable"
-      isDisabled
-      onChange={(value) => console.log(value)}
-    />
-  );
-}
-
-// Compact size radio
-function CompactRadio() {
-  return (
-    <Radio
-      label="Compact Option"
-      name="compact"
-      value="compact"
-      size="compact"
-      onChange={(value) => console.log(value)}
-    />
-  );
-}
-
-// Custom form integration
-function FormRadio() {
-  const [formData, setFormData] = useState({ preference: '' });
-
-  return (
-    <form>
-      <fieldset>
-        <legend>Preferences</legend>
-        <Radio
-          label="Email Notifications"
-          name="preference"
-          value="email"
-          isChecked={formData.preference === 'email'}
-          onChange={(value) => setFormData(prev => ({ ...prev, preference: value }))}
-        />
-        <Radio
-          label="SMS Notifications"
-          name="preference"
-          value="sms"
-          isChecked={formData.preference === 'sms'}
-          onChange={(value) => setFormData(prev => ({ ...prev, preference: value }))}
-        />
-      </fieldset>
-    </form>
-  );
-}
-```
-
-## Props Reference
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `label` | `string` | `undefined` | No | Text label displayed next to the radio button |
-| `id` | `string` | auto-generated | No | Unique identifier for the input element |
-| `name` | `string` | `undefined` | No | Name attribute for grouping radio buttons |
-| `value` | `string` | `undefined` | No | Value of the radio button when selected |
-| `type` | `'normal' \| 'error'` | `'normal'` | No | Visual state of the radio button |
-| `isChecked` | `boolean` | `undefined` | No | Whether the radio button is selected |
-| `isDisabled` | `boolean` | `undefined` | No | Whether the radio button is disabled |
-| `size` | `'regular' \| 'compact'` | `'regular'` | No | Size variant of the radio button |
-| `tooltip` | `string` | `undefined` | No | Tooltip content shown on hover |
-| `onChange` | `(checked: string \| number) => void` | `undefined` | No | Callback fired when radio is selected |
-| `onBlur` | `() => void` | `undefined` | No | Callback fired when radio loses focus |
-
-## AI Agent Guidelines
-
-### Recommended Patterns
-
-1. **Radio Groups**: Always use the same `name` attribute for related radio buttons
-```typescript
-// Correct - same name for grouped options
-<Radio name="theme" value="light" />
-<Radio name="theme" value="dark" />
-
-// Incorrect - different names break grouping
-<Radio name="theme1" value="light" />
-<Radio name="theme2" value="dark" />
-```
-
-2. **State Management**: Use controlled components with proper state handling
-```typescript
-const [selectedValue, setSelectedValue] = useState('');
-
-<Radio
-  name="options"
-  value="option1"
-  isChecked={selectedValue === 'option1'}
-  onChange={setSelectedValue}
-/>
-```
-
-3. **Form Integration**: Integrate properly with form libraries
-```typescript
-// With React Hook Form
-const { register, watch } = useForm();
-const selectedValue = watch('radioField');
-
-<Radio
-  {...register('radioField')}
-  value="option1"
-  isChecked={selectedValue === 'option1'}
-/>
-```
-
-### Common Mistakes to Avoid
-
-1. **Missing Name Attribute**: Don't forget the `name` prop for radio groups
-2. **Inconsistent State**: Ensure only one radio in a group is checked
-3. **Missing onChange**: Always provide an `onChange` handler for interactive radios
-4. **Wrong Value Type**: The `onChange` callback receives a string, not a boolean
-
-### Integration Tips
-
-1. **Accessibility**: Component automatically generates IDs and associates labels
-2. **Keyboard Navigation**: Native radio behavior is preserved for keyboard users
-3. **Styling**: Use `type="error"` for validation states
-4. **Tooltips**: Add contextual help with the `tooltip` prop
-5. **Responsive**: Use `size="compact"` for mobile or dense layouts
-
-## Related Components
-
-- **Checkbox**: For multiple selection scenarios
-- **Switch**: For boolean toggle controls
-- **Select**: For dropdown selection lists
-- **Button**: For action-based selections
-- **Tooltip**: Used internally for tooltip functionality

package/Select/ai-documentation.md

@@ -1,374 +0,0 @@
-# Select - AI Documentation
-
-> Auto-generated AI agent documentation for Select component
-> Part of @pushwoosh/dumb-components library
-
-## Overview
-**Component:** Select, SelectAsync, CreatableSelect
-**Import Path:** `import { Select, SelectAsync, CreatableSelect } from '@pushwoosh/dumb-components'`
-**Files:** 
-- `Select/Select.tsx` - Main select components
-- `Select/types.ts` - TypeScript interfaces
-- `Select/styles.ts` - Styled components wrapper
-- `Select/constants.ts` - Configuration constants
-**Type:** Form Component / Input
-**Description:** Advanced select components built on react-select library. Provides standard select, async loading select, and creatable select variants with consistent Pushwoosh styling.
-
-## TypeScript Interfaces
-
-### SelectOption
-```typescript
-interface SelectOption {
-  label: string;    // Display text
-  value: string;    // Option value
-}
-```
-
-### SelectBase
-```typescript
-interface SelectBase {
-  width?: string;         // Custom width
-  $isErrored?: boolean;   // Error state styling
-}
-```
-
-### SelectProps
-```typescript
-type SelectProps<Option, IsMulti extends boolean = false> = 
-  ReactSelectProps<Option, IsMulti> & SelectBase;
-```
-
-### SelectAsyncProps
-```typescript
-type SelectAsyncProps<Option, IsMulti extends boolean = false> = 
-  SelectProps<Option, IsMulti> & AsyncProps<Option, IsMulti> & SelectBase;
-```
-
-### SelectCreatableProps
-```typescript
-type SelectCreatableProps<Option, IsMulti extends boolean = false> = 
-  SelectProps<Option, IsMulti> & CreatableProps<Option, IsMulti> & SelectBase;
-```
-
-## Import & Usage
-
-### Basic Select
-```tsx
-import { Select } from '@pushwoosh/dumb-components';
-
-const options = [
-  { value: 'apple', label: 'Apple' },
-  { value: 'banana', label: 'Banana' },
-  { value: 'orange', label: 'Orange' }
-];
-
-function BasicExample() {
-  const [selected, setSelected] = useState(null);
-  
-  return (
-    <Select
-      options={options}
-      value={selected}
-      onChange={setSelected}
-      placeholder="Select a fruit..."
-    />
-  );
-}
-```
-
-### Multi-Select
-```tsx
-import { Select, MultiSelectOptions } from '@pushwoosh/dumb-components';
-
-function MultiSelectExample() {
-  const [selected, setSelected] = useState<MultiSelectOptions>([]);
-  
-  return (
-    <Select
-      isMulti
-      options={options}
-      value={selected}
-      onChange={setSelected}
-      placeholder="Select fruits..."
-    />
-  );
-}
-```
-
-### Async Select
-```tsx
-import { SelectAsync } from '@pushwoosh/dumb-components';
-
-function AsyncExample() {
-  const [selected, setSelected] = useState(null);
-  
-  const loadOptions = async (inputValue: string) => {
-    const response = await fetch(`/api/search?q=${inputValue}`);
-    const data = await response.json();
-    return data.map(item => ({
-      value: item.id,
-      label: item.name
-    }));
-  };
-  
-  return (
-    <SelectAsync
-      loadOptions={loadOptions}
-      value={selected}
-      onChange={setSelected}
-      placeholder="Search..."
-      cacheOptions
-      defaultOptions
-    />
-  );
-}
-```
-
-### Creatable Select
-```tsx
-import { CreatableSelect } from '@pushwoosh/dumb-components';
-
-function CreatableExample() {
-  const [options, setOptions] = useState([
-    { value: 'red', label: 'Red' },
-    { value: 'blue', label: 'Blue' }
-  ]);
-  const [selected, setSelected] = useState(null);
-  
-  const handleCreate = (inputValue: string) => {
-    const newOption = { value: inputValue.toLowerCase(), label: inputValue };
-    setOptions([...options, newOption]);
-    setSelected(newOption);
-  };
-  
-  return (
-    <CreatableSelect
-      options={options}
-      value={selected}
-      onChange={setSelected}
-      onCreateOption={handleCreate}
-      placeholder="Select or create..."
-    />
-  );
-}
-```
-
-## Advanced Examples
-
-### Select with Error State
-```tsx
-function FormSelect({ error, ...props }) {
-  return (
-    <div>
-      <Select
-        {...props}
-        $isErrored={!!error}
-        width="300px"
-      />
-      {error && <span style={{ color: 'red' }}>{error}</span>}
-    </div>
-  );
-}
-```
-
-### Grouped Options
-```tsx
-const groupedOptions = [
-  {
-    label: 'Fruits',
-    options: [
-      { value: 'apple', label: 'Apple' },
-      { value: 'banana', label: 'Banana' }
-    ]
-  },
-  {
-    label: 'Vegetables',
-    options: [
-      { value: 'carrot', label: 'Carrot' },
-      { value: 'potato', label: 'Potato' }
-    ]
-  }
-];
-
-function GroupedSelect() {
-  return (
-    <Select
-      options={groupedOptions}
-      placeholder="Select item..."
-    />
-  );
-}
-```
-
-### Custom Option Rendering
-```tsx
-import { components } from 'react-select';
-
-const CustomOption = (props) => (
-  <components.Option {...props}>
-    <div style={{ display: 'flex', alignItems: 'center' }}>
-      <img src={props.data.icon} width={20} height={20} />
-      <span style={{ marginLeft: 10 }}>{props.data.label}</span>
-    </div>
-  </components.Option>
-);
-
-function SelectWithIcons() {
-  const options = [
-    { value: 'js', label: 'JavaScript', icon: '/icons/js.png' },
-    { value: 'py', label: 'Python', icon: '/icons/py.png' }
-  ];
-  
-  return (
-    <Select
-      options={options}
-      components={{ Option: CustomOption }}
-      placeholder="Select language..."
-    />
-  );
-}
-```
-
-### Async Select with Debounce
-```tsx
-import { useMemo } from 'react';
-import debounce from 'lodash/debounce';
-
-function DebouncedAsyncSelect() {
-  const loadOptions = useMemo(
-    () => debounce(async (inputValue: string, callback: (options: any[]) => void) => {
-      const response = await fetch(`/api/users?search=${inputValue}`);
-      const users = await response.json();
-      callback(users.map(u => ({ value: u.id, label: u.name })));
-    }, 300),
-    []
-  );
-  
-  return (
-    <SelectAsync
-      loadOptions={loadOptions}
-      placeholder="Search users..."
-      noOptionsMessage={() => "No users found"}
-      loadingMessage={() => "Searching..."}
-    />
-  );
-}
-```
-
-### Controlled Select with Form
-```tsx
-function UserForm() {
-  const [formData, setFormData] = useState({
-    name: '',
-    country: null,
-    skills: []
-  });
-  
-  const countries = [
-    { value: 'us', label: 'United States' },
-    { value: 'uk', label: 'United Kingdom' },
-    { value: 'ca', label: 'Canada' }
-  ];
-  
-  const skills = [
-    { value: 'react', label: 'React' },
-    { value: 'node', label: 'Node.js' },
-    { value: 'python', label: 'Python' }
-  ];
-  
-  return (
-    <form>
-      <Select
-        options={countries}
-        value={formData.country}
-        onChange={(value) => setFormData({ ...formData, country: value })}
-        placeholder="Select country..."
-        isClearable
-      />
-      
-      <Select
-        isMulti
-        options={skills}
-        value={formData.skills}
-        onChange={(value) => setFormData({ ...formData, skills: value })}
-        placeholder="Select skills..."
-        closeMenuOnSelect={false}
-      />
-    </form>
-  );
-}
-```
-
-## Props Reference
-
-### Common Props (All Variants)
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `options` | `Option[]` | - | - | Array of options |
-| `value` | `Option \| Option[] \| null` | - | - | Selected value(s) |
-| `onChange` | `(value: Option) => void` | - | - | Change handler |
-| `placeholder` | `string` | - | `'Select...'` | Placeholder text |
-| `isMulti` | `boolean` | - | `false` | Enable multi-select |
-| `isDisabled` | `boolean` | - | `false` | Disable the select |
-| `isLoading` | `boolean` | - | `false` | Show loading state |
-| `isClearable` | `boolean` | - | `false` | Show clear button |
-| `isSearchable` | `boolean` | - | `true` | Enable search |
-| `width` | `string` | - | - | Custom width |
-| `$isErrored` | `boolean` | - | `false` | Error state styling |
-| `menuIsOpen` | `boolean` | - | - | Control menu visibility |
-| `closeMenuOnSelect` | `boolean` | - | `true` | Close menu on selection |
-| `classNamePrefix` | `string` | - | `'kit-select'` | CSS class prefix |
-
-### SelectAsync Additional Props
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `loadOptions` | `(inputValue: string) => Promise<Option[]>` | ✓ | - | Async options loader |
-| `cacheOptions` | `boolean` | - | `false` | Cache loaded options |
-| `defaultOptions` | `boolean \| Option[]` | - | `false` | Initial options or load on mount |
-| `loadingMessage` | `() => string` | - | `'Loading...'` | Loading message |
-| `noOptionsMessage` | `() => string` | - | `'No options'` | No options message |
-
-### CreatableSelect Additional Props
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `onCreateOption` | `(inputValue: string) => void` | - | - | Handler for creating new options |
-| `formatCreateLabel` | `(inputValue: string) => string` | - | `'Create "{input}"'` | Format create option label |
-| `isValidNewOption` | `(inputValue: string) => boolean` | - | - | Validate new option |
-| `getNewOptionData` | `(inputValue: string, label: string) => Option` | - | - | Format new option data |
-
-## AI Agent Guidelines
-
-### ✅ Recommended Patterns
-- Always provide both `value` and `onChange` for controlled components
-- Use `SelectOption` type for consistent option structure
-- Enable `isClearable` for optional fields
-- Use `isMulti` for multiple selections
-- Implement proper loading states with `SelectAsync`
-- Cache options in async selects when appropriate
-- Use `placeholder` to guide user input
-- Handle empty states with `noOptionsMessage`
-
-### ❌ Common Mistakes to Avoid
-- Don't forget to handle `null` values in onChange
-- Don't use inline option arrays - define outside render
-- Avoid not handling loading/error states in async selects
-- Don't forget `defaultOptions` for initial load in async
-- Avoid complex objects as values - use simple strings/numbers
-- Don't modify options array directly - use state
-- Avoid missing `key` props in custom components
-
-### Integration Tips
-- Select is built on react-select v5
-- All react-select props are supported
-- Custom styling via `classNamePrefix` and styled-components
-- Clear indicator uses CloseIcon from kit-icons
-- Works with form libraries (react-hook-form, formik)
-- Supports keyboard navigation and accessibility
-- Menu portal can be used for overflow issues
-
-## Related Components
-- **EnhancedInput** - For text input fields
-- **Checkbox** - For multiple boolean options
-- **Radio** - For single choice from few options
-- **Button** - For form submission
-- **DateTimePicker** - For date/time selection