@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/EnhancedInput/ai-documentation.md

@@ -1,352 +0,0 @@
-# EnhancedInput - AI Documentation
-
-> Auto-generated AI agent documentation for EnhancedInput component
-> Part of @pushwoosh/dumb-components library
-
-## Overview
-**Component:** EnhancedInput, SearchInput
-**Import Path:** `import { EnhancedInput, SearchInput } from '@pushwoosh/dumb-components'`
-**Files:**
-- `EnhancedInput/EnhancedInput.tsx` - Main enhanced input component
-- `EnhancedInput/SearchInput.tsx` - Search input variant
-- `EnhancedInput/types.ts` - TypeScript interfaces
-- `EnhancedInput/styles.ts` - Styled components wrapper
-**Type:** Form Component / Input
-**Description:** Enhanced text input component with icon support and clear functionality. Built on top of NativeInput with additional features like prefix icons and clear buttons. SearchInput is a pre-configured variant with search icon.
-
-## TypeScript Interfaces
-
-### EnhancedInputProps
-```typescript
-interface EnhancedInputProps extends InputHTMLAttributes<HTMLInputElement>, NativeInputProps {
-  $icon?: ReactNode;        // Prefix icon element
-  $onClear?: () => void;    // Clear button handler
-  $isErrored?: boolean;     // Error state styling (from NativeInputProps)
-}
-```
-
-### SearchInputProps
-```typescript
-type SearchInputProps = Omit<EnhancedInputProps, '$icon'>;
-// SearchInput automatically includes search icon
-```
-
-### NativeInputProps (inherited)
-```typescript
-interface NativeInputProps {
-  $isErrored?: boolean;     // Error state styling
-}
-```
-
-## Import & Usage
-
-### Basic EnhancedInput
-```tsx
-import { EnhancedInput } from '@pushwoosh/dumb-components';
-
-function BasicExample() {
-  const [value, setValue] = useState('');
-
-  return (
-    <EnhancedInput
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-      placeholder="Enter text..."
-    />
-  );
-}
-```
-
-### EnhancedInput with Icon
-```tsx
-import { EnhancedInput } from '@pushwoosh/dumb-components';
-import { UserIcon } from '@pushwoosh/kit-icons';
-
-function InputWithIcon() {
-  const [username, setUsername] = useState('');
-
-  return (
-    <EnhancedInput
-      $icon={<UserIcon size="small" />}
-      value={username}
-      onChange={(e) => setUsername(e.target.value)}
-      placeholder="Username"
-    />
-  );
-}
-```
-
-### EnhancedInput with Clear Button
-```tsx
-import { EnhancedInput } from '@pushwoosh/dumb-components';
-
-function ClearableInput() {
-  const [value, setValue] = useState('');
-
-  return (
-    <EnhancedInput
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-      $onClear={() => setValue('')}
-      placeholder="Clearable input..."
-    />
-  );
-}
-```
-
-### SearchInput
-```tsx
-import { SearchInput } from '@pushwoosh/dumb-components';
-
-function SearchExample() {
-  const [searchTerm, setSearchTerm] = useState('');
-
-  return (
-    <SearchInput
-      value={searchTerm}
-      onChange={(e) => setSearchTerm(e.target.value)}
-      $onClear={() => setSearchTerm('')}
-      placeholder="Search..."
-    />
-
-  );
-}
-```
-
-## Advanced Examples
-
-### Form with Validation
-```tsx
-import { EnhancedInput } from '@pushwoosh/dumb-components';
-import { EmailIcon } from '@pushwoosh/kit-icons';
-
-function EmailInput() {
-  const [email, setEmail] = useState('');
-  const [error, setError] = useState('');
-
-  const validateEmail = (value: string) => {
-    const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
-    setError(isValid ? '' : 'Invalid email address');
-    return isValid;
-  };
-
-  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const value = e.target.value;
-    setEmail(value);
-    if (value) validateEmail(value);
-  };
-
-  return (
-    <div>
-      <EnhancedInput
-        $icon={<EmailIcon size="small" />}
-        type="email"
-        value={email}
-        onChange={handleChange}
-        $isErrored={!!error}
-        $onClear={() => {
-          setEmail('');
-          setError('');
-        }}
-        placeholder="Email address"
-      />
-      {error && <span style={{ color: 'red', fontSize: '12px' }}>{error}</span>}
-    </div>
-  );
-}
-```
-
-### Password Input with Toggle
-```tsx
-import { EnhancedInput } from '@pushwoosh/dumb-components';
-import { LockIcon, EyeIcon, EyeClosedIcon } from '@pushwoosh/kit-icons';
-
-function PasswordInput() {
-  const [password, setPassword] = useState('');
-  const [showPassword, setShowPassword] = useState(false);
-
-  return (
-    <EnhancedInput
-      $icon={<LockIcon size="small" />}
-      type={showPassword ? 'text' : 'password'}
-      value={password}
-      onChange={(e) => setPassword(e.target.value)}
-      placeholder="Password"
-      $onClear={() => setPassword('')}
-      // Custom action icon instead of clear
-      endAdornment={
-        <button onClick={() => setShowPassword(!showPassword)}>
-          {showPassword ? <EyeClosedIcon /> : <EyeIcon />}
-        </button>
-      }
-    />
-  );
-}
-```
-
-### Debounced Search
-```tsx
-import { SearchInput } from '@pushwoosh/dumb-components';
-import { useEffect, useState } from 'react';
-
-function DebouncedSearch({ onSearch }) {
-  const [value, setValue] = useState('');
-  const [debouncedValue, setDebouncedValue] = useState('');
-
-  useEffect(() => {
-    const timer = setTimeout(() => {
-      setDebouncedValue(value);
-    }, 300);
-
-    return () => clearTimeout(timer);
-  }, [value]);
-
-  useEffect(() => {
-    if (debouncedValue) {
-      onSearch(debouncedValue);
-    }
-  }, [debouncedValue, onSearch]);
-
-  return (
-    <SearchInput
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-      $onClear={() => {
-        setValue('');
-        setDebouncedValue('');
-        onSearch('');
-      }}
-      placeholder="Search (debounced)..."
-    />
-  );
-}
-```
-
-### Controlled Input with Character Limit
-```tsx
-import { EnhancedInput } from '@pushwoosh/dumb-components';
-
-function LimitedInput({ maxLength = 50 }) {
-  const [value, setValue] = useState('');
-
-  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const newValue = e.target.value;
-    if (newValue.length <= maxLength) {
-      setValue(newValue);
-    }
-  };
-
-  return (
-    <div>
-      <EnhancedInput
-        value={value}
-        onChange={handleChange}
-        $onClear={() => setValue('')}
-        placeholder={`Max ${maxLength} characters`}
-      />
-      <span style={{ fontSize: '12px', color: '#666' }}>
-        {value.length}/{maxLength}
-      </span>
-    </div>
-  );
-}
-```
-
-### Input with Loading State
-```tsx
-import { EnhancedInput } from '@pushwoosh/dumb-components';
-import { Spinner } from '@pushwoosh/dumb-components';
-
-function AsyncInput() {
-  const [value, setValue] = useState('');
-  const [loading, setLoading] = useState(false);
-
-  const handleChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
-    const newValue = e.target.value;
-    setValue(newValue);
-
-    if (newValue) {
-      setLoading(true);
-      // Simulate async validation
-      await new Promise(resolve => setTimeout(resolve, 1000));
-      setLoading(false);
-    }
-  };
-
-  return (
-    <EnhancedInput
-      value={value}
-      onChange={handleChange}
-      placeholder="Type to validate..."
-      disabled={loading}
-      $icon={loading ? <Spinner size="small" /> : null}
-      $onClear={() => setValue('')}
-    />
-  );
-}
-```
-
-## Props Reference
-
-### EnhancedInput Props
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `$icon` | `ReactNode` | - | - | Icon element to display at start of input |
-| `$onClear` | `() => void` | - | - | Shows clear button and handles clear action |
-| `$isErrored` | `boolean` | - | `false` | Error state styling (red border) |
-| `value` | `string \| number` | - | - | Input value |
-| `onChange` | `(e: ChangeEvent) => void` | - | - | Change handler |
-| `placeholder` | `string` | - | - | Placeholder text |
-| `type` | `string` | - | `'text'` | Input type (text, email, password, etc.) |
-| `disabled` | `boolean` | - | `false` | Disable input |
-| `readOnly` | `boolean` | - | `false` | Make input read-only |
-| `autoFocus` | `boolean` | - | `false` | Auto-focus on mount |
-| `autoComplete` | `string` | - | - | Browser autocomplete hint |
-| `maxLength` | `number` | - | - | Maximum character length |
-| `pattern` | `string` | - | - | Validation pattern |
-| `required` | `boolean` | - | `false` | Mark as required field |
-| `ref` | `Ref<HTMLInputElement>` | - | - | Forward ref to input element |
-
-### SearchInput Props
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| All EnhancedInput props except `$icon` | - | - | - | SearchInput automatically includes search icon |
-
-## AI Agent Guidelines
-
-### ✅ Recommended Patterns
-- Use `SearchInput` for search functionality (includes icon automatically)
-- Always handle both `value` and `onChange` for controlled inputs
-- Provide `$onClear` for better UX when input has value
-- Use `$isErrored` prop for validation feedback
-- Combine with icons from `@pushwoosh/kit-icons` for context
-- Use `ref` forwarding when needed for focus management
-- Implement debouncing for search/filter inputs
-- Show character limits for restricted inputs
-
-### ❌ Common Mistakes to Avoid
-- Don't use `$icon` prop with `SearchInput` (it's preset)
-- Don't forget to handle empty state in `$onClear`
-- Avoid inline function definitions for `$onClear`
-- Don't mix controlled and uncontrolled patterns
-- Avoid complex logic in onChange - extract to separate function
-- Don't forget to clear errors when clearing input
-- Avoid using native HTML validation with custom error states
-
-### Integration Tips
-- Component uses forwardRef for ref access
-- Built on styled-components with Pushwoosh design tokens
-- Clear button uses CloseIcon from kit-icons
-- Works with all native input attributes
-- Wrapper handles icon and clear button positioning
-- Supports all HTML5 input types
-- Compatible with form libraries (react-hook-form, formik)
-
-## Related Components
-- **NativeInput** - Base input component (used internally)
-- **Select** - For dropdown selections
-- **DateTimePicker** - For date/time inputs
-- **Button** - For form submission
-- **Checkbox** - For boolean inputs
-- **Radio** - For single choice inputs
-- **Toast** - For input action feedback