@delightui/components 0.1.105 → 0.1.107

package/docs/components/atoms/Input.md

@@ -0,0 +1,430 @@
+# Input
+
+## Description
+
+Text input component with validation, icons, and form integration support. Provides a flexible foundation for collecting user text input with proper accessibility and styling.
+
+## Aliases
+
+- Text Input
+- Text Field
+- Input Field
+- Form Input
+
+## Props Breakdown
+
+**Extends:** `InputHTMLAttributes<HTMLInputElement>` (excluding `type` and `value`) + `ControlledFormComponentProps<string>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `inputType` | `'Text' \| 'Number' \| 'Email' \| 'Password'` | `'Text'` | No | Type of input field |
+| `leadingIcon` | `ReactNode` | - | No | Icon displayed before the input text |
+| `trailingIcon` | `ReactNode` | - | No | Icon displayed after the input text |
+| `component-variant` | `string` | - | No | Override styling variant |
+| `initialValue` | `string` | - | No | Initial value for controlled form usage |
+| `value` | `string` | - | No | Controlled value |
+| `onValueChange` | `(value: string) => void` | - | No | Callback when input value changes |
+| `disabled` | `boolean` | `false` | No | Whether the input is disabled |
+| `required` | `boolean` | `false` | No | Whether the input is required |
+| `invalid` | `boolean` | `false` | No | Whether the input value is invalid |
+| `id` | `string` | - | No | HTML id attribute |
+| `placeholder` | `string` | - | No | Placeholder text |
+| `className` | `string` | - | No | Additional CSS class names |
+
+Plus all standard HTML input attributes (name, autoComplete, autoFocus, min, max, step, pattern, etc.) except `type` and `value`.
+
+## Examples
+
+### Basic Usage
+```tsx
+import { Input } from '@delightui/components';
+
+function BasicExample() {
+  const [value, setValue] = useState('');
+
+  return (
+    <Input
+      placeholder="Enter your name"
+      value={value}
+      onValueChange={setValue}
+    />
+  );
+}
+```
+
+### Input Types
+```tsx
+function InputTypesExample() {
+  return (
+    <div className="input-types">
+      <Input 
+        inputType="Text"
+        placeholder="Enter text"
+      />
+      
+      <Input 
+        inputType="Email"
+        placeholder="Enter email address"
+      />
+      
+      <Input 
+        inputType="Password"
+        placeholder="Enter password"
+      />
+      
+      <Input 
+        inputType="Number"
+        placeholder="Enter number"
+      />
+    </div>
+  );
+}
+```
+
+### With Icons
+```tsx
+import { 
+  UserIcon, 
+  EnvelopeIcon, 
+  LockClosedIcon,
+  MagnifyingGlassIcon,
+  EyeIcon
+} from '@heroicons/react/24/outline';
+
+function IconsExample() {
+  return (
+    <div className="input-icons">
+      <Input 
+        leadingIcon={<UserIcon />}
+        placeholder="Username"
+      />
+      
+      <Input 
+        leadingIcon={<EnvelopeIcon />}
+        inputType="Email"
+        placeholder="Email address"
+      />
+      
+      <Input 
+        leadingIcon={<LockClosedIcon />}
+        trailingIcon={<EyeIcon />}
+        inputType="Password"
+        placeholder="Password"
+      />
+      
+      <Input 
+        leadingIcon={<MagnifyingGlassIcon />}
+        placeholder="Search..."
+      />
+    </div>
+  );
+}
+```
+
+### Form Integration
+```tsx
+import { Input, Form, FormField, Button } from '@delightui/components';
+
+function FormExample() {
+  const handleSubmit = (values, setError) => {
+    // Validate email
+    if (!values.email || !values.email.includes('@')) {
+      setError('email', 'Please enter a valid email address');
+      return;
+    }
+    
+    // Validate password
+    if (!values.password || values.password.length < 8) {
+      setError('password', 'Password must be at least 8 characters');
+      return;
+    }
+    
+    console.log('Form submitted:', values);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField 
+        name="firstName" 
+        label="First Name"
+        required
+      >
+        <Input 
+          placeholder="Enter your first name"
+          leadingIcon={<UserIcon />}
+        />
+      </FormField>
+
+      <FormField 
+        name="lastName" 
+        label="Last Name"
+        required
+      >
+        <Input 
+          placeholder="Enter your last name"
+          leadingIcon={<UserIcon />}
+        />
+      </FormField>
+
+      <FormField 
+        name="email" 
+        label="Email Address"
+        required
+      >
+        <Input 
+          inputType="Email"
+          placeholder="Enter your email"
+          leadingIcon={<EnvelopeIcon />}
+        />
+      </FormField>
+
+      <FormField 
+        name="password" 
+        label="Password"
+        required
+      >
+        <Input 
+          inputType="Password"
+          placeholder="Enter password"
+          leadingIcon={<LockClosedIcon />}
+        />
+      </FormField>
+
+      <Button actionType="submit">
+        Create Account
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Validation States
+```tsx
+import { Text } from '@delightui/components';
+
+function ValidationExample() {
+  const [email, setEmail] = useState('');
+  const [isValid, setIsValid] = useState(true);
+
+  const validateEmail = (value) => {
+    const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+    setIsValid(isValidEmail);
+    return isValidEmail;
+  };
+
+  const handleEmailChange = (value) => {
+    setEmail(value);
+    if (value) {
+      validateEmail(value);
+    } else {
+      setIsValid(true);
+    }
+  };
+
+  return (
+    <div className="validation-example">
+      <Input
+        inputType="Email"
+        value={email}
+        onValueChange={handleEmailChange}
+        invalid={!isValid && email.length > 0}
+        placeholder="Enter email address"
+        leadingIcon={<EnvelopeIcon />}
+      />
+      
+      {!isValid && email.length > 0 && (
+        <Text type="BodySmall" className="error-message">
+          Please enter a valid email address
+        </Text>
+      )}
+    </div>
+  );
+}
+```
+
+### Disabled State
+```tsx
+function DisabledExample() {
+  return (
+    <div className="disabled-inputs">
+      <Input 
+        disabled
+        placeholder="Disabled input"
+        value="Cannot edit this"
+      />
+      
+      <Input 
+        disabled
+        leadingIcon={<UserIcon />}
+        placeholder="Disabled with icon"
+      />
+    </div>
+  );
+}
+```
+
+### Search Input
+```tsx
+import { IconButton, Icon } from '@delightui/components';
+
+function SearchExample() {
+  const [searchTerm, setSearchTerm] = useState('');
+  const [results, setResults] = useState([]);
+
+  const handleSearch = useCallback(
+    debounce((term) => {
+      if (term.length > 2) {
+        // Simulate search
+        setResults([
+          `Result 1 for "${term}"`,
+          `Result 2 for "${term}"`,
+          `Result 3 for "${term}"`
+        ]);
+      } else {
+        setResults([]);
+      }
+    }, 300),
+    []
+  );
+
+  useEffect(() => {
+    handleSearch(searchTerm);
+  }, [searchTerm, handleSearch]);
+
+  const clearSearch = () => {
+    setSearchTerm('');
+    setResults([]);
+  };
+
+  return (
+    <div className="search-input">
+      <Input
+        leadingIcon={<MagnifyingGlassIcon />}
+        trailingIcon={
+          searchTerm ? (
+            <IconButton onClick={clearSearch} size="Small">
+              <Icon icon="Close" />
+            </IconButton>
+          ) : null
+        }
+        placeholder="Search..."
+        value={searchTerm}
+        onValueChange={setSearchTerm}
+      />
+      
+      {results.length > 0 && (
+        <div className="search-results">
+          {results.map((result, index) => (
+            <div key={index} className="result-item">
+              {result}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Number Input with Validation
+```tsx
+import { Text } from '@delightui/components';
+
+function NumberInputExample() {
+  const [age, setAge] = useState('');
+  const [error, setError] = useState('');
+
+  const handleAgeChange = (value) => {
+    setAge(value);
+    
+    const numValue = parseInt(value);
+    if (value && (isNaN(numValue) || numValue < 0 || numValue > 120)) {
+      setError('Please enter a valid age (0-120)');
+    } else {
+      setError('');
+    }
+  };
+
+  return (
+    <div className="number-input">
+      <Input
+        inputType="Number"
+        value={age}
+        onValueChange={handleAgeChange}
+        invalid={!!error}
+        placeholder="Enter your age"
+        min="0"
+        max="120"
+      />
+      
+      {error && (
+        <Text type="BodySmall" className="error-message">{error}</Text>
+      )}
+    </div>
+  );
+}
+```
+
+### Controlled vs Uncontrolled
+```tsx
+import { Button, Text } from '@delightui/components';
+
+function ControlledExample() {
+  // Controlled input
+  const [controlledValue, setControlledValue] = useState('');
+  
+  // Uncontrolled input
+  const uncontrolledRef = useRef(null);
+
+  const getUncontrolledValue = () => {
+    alert(`Uncontrolled value: ${uncontrolledRef.current?.value}`);
+  };
+
+  return (
+    <div className="controlled-comparison">
+      <div>
+        <Text type="Heading4">Controlled Input</Text>
+        <Input
+          value={controlledValue}
+          onValueChange={setControlledValue}
+          placeholder="Controlled input"
+        />
+        <Text>Current value: {controlledValue}</Text>
+      </div>
+
+      <div>
+        <Text type="Heading4">Uncontrolled Input</Text>
+        <Input
+          ref={uncontrolledRef}
+          defaultValue="Initial value"
+          placeholder="Uncontrolled input"
+        />
+        <Button onClick={getUncontrolledValue}>
+          Get Value
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Custom Styling
+```tsx
+function CustomStylingExample() {
+  return (
+    <div className="custom-styling">
+      <Input
+        component-variant="primary"
+        placeholder="Primary variant"
+        leadingIcon={<StarIcon />}
+      />
+      
+      <Input
+        component-variant="secondary"
+        placeholder="Secondary variant"
+        className="custom-input-class"
+      />
+    </div>
+  );
+}
+```