@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/native/ai-documentation.md

@@ -1,485 +0,0 @@
-# Native Components - AI Documentation
-
-> Auto-generated AI agent documentation for Native HTML components
-> Part of @pushwoosh/dumb-components library
-
-## Overview
-**Components:** NativeInput, NativeSelect, NativeTextarea, NativeTimeInput
-**Import Path:** `import { NativeInput, NativeSelect, NativeTextarea, NativeTimeInput } from '@pushwoosh/dumb-components'`
-**Files:**
-- `native/Input.tsx` - Styled native input component
-- `native/Select.tsx` - Styled native select component
-- `native/Textarea.tsx` - Styled native textarea component
-- `native/TimeInput.tsx` - Styled native time input component
-- `native/index.ts` - Main exports
-**Type:** Base Form Components / Styled HTML Elements
-**Description:** Styled-components wrappers around native HTML form elements. These provide consistent Pushwoosh Design System styling while maintaining native HTML behavior. Used internally by enhanced components like EnhancedInput.
-
-## TypeScript Interfaces
-
-### NativeInputProps
-```typescript
-interface NativeInputProps {
-  $isErrored?: boolean;    // Error state styling (red border)
-}
-
-// Extends all standard HTMLInputElement attributes:
-// value, onChange, placeholder, type, disabled, readOnly, etc.
-```
-
-### NativeSelectProps
-```typescript
-interface NativeSelectProps {
-  $isErrored?: boolean;    // Error state styling (red border)
-}
-
-// Extends all standard HTMLSelectElement attributes:
-// value, onChange, disabled, multiple, etc.
-```
-
-### NativeTextareaProps
-```typescript
-interface NativeTextareaProps {
-  $width?: string;         // Custom width (default: 100%)
-  $isErrored?: boolean;    // Error state styling (red border)
-}
-
-// Extends all standard HTMLTextAreaElement attributes:
-// value, onChange, placeholder, rows, cols, disabled, etc.
-```
-
-### NativeTimeInputProps
-```typescript
-// NativeTimeInput is a styled input[type="time"] element
-// Extends all standard HTMLInputElement attributes:
-// value, onChange, disabled, readOnly, min, max, step, etc.
-```
-
-## Import & Usage
-
-### NativeInput
-```tsx
-import { NativeInput } from '@pushwoosh/dumb-components';
-
-function BasicInput() {
-  const [value, setValue] = useState('');
-  
-  return (
-    <NativeInput
-      type="text"
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-      placeholder="Enter text..."
-    />
-  );
-}
-```
-
-### NativeSelect
-```tsx
-import { NativeSelect } from '@pushwoosh/dumb-components';
-
-function BasicSelect() {
-  const [value, setValue] = useState('');
-  
-  return (
-    <NativeSelect
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-    >
-      <option value="">Select an option</option>
-      <option value="option1">Option 1</option>
-      <option value="option2">Option 2</option>
-      <option value="option3">Option 3</option>
-    </NativeSelect>
-  );
-}
-```
-
-### NativeTextarea
-```tsx
-import { NativeTextarea } from '@pushwoosh/dumb-components';
-
-function BasicTextarea() {
-  const [value, setValue] = useState('');
-
-  return (
-    <NativeTextarea
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-      placeholder="Enter your message..."
-      rows={4}
-    />
-  );
-}
-```
-
-### NativeTimeInput
-```tsx
-import { NativeTimeInput } from '@pushwoosh/dumb-components';
-
-function BasicTimeInput() {
-  const [time, setTime] = useState('09:00');
-
-  return (
-    <NativeTimeInput
-      value={time}
-      onChange={(e) => setTime(e.target.value)}
-    />
-  );
-}
-```
-
-## Advanced Examples
-
-### Form with Validation
-```tsx
-import { NativeInput, NativeSelect, NativeTextarea } from '@pushwoosh/dumb-components';
-
-function ValidationForm() {
-  const [formData, setFormData] = useState({
-    name: '',
-    category: '',
-    message: ''
-  });
-  const [errors, setErrors] = useState({});
-  
-  const validate = () => {
-    const newErrors = {};
-    if (!formData.name) newErrors.name = 'Name is required';
-    if (!formData.category) newErrors.category = 'Category is required';
-    if (!formData.message) newErrors.message = 'Message is required';
-    
-    setErrors(newErrors);
-    return Object.keys(newErrors).length === 0;
-  };
-  
-  const handleSubmit = (e) => {
-    e.preventDefault();
-    if (validate()) {
-      console.log('Form submitted:', formData);
-    }
-  };
-  
-  return (
-    <form onSubmit={handleSubmit}>
-      <div>
-        <label>Name:</label>
-        <NativeInput
-          type="text"
-          value={formData.name}
-          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
-          $isErrored={!!errors.name}
-          placeholder="Your name"
-        />
-        {errors.name && <span style={{ color: 'red' }}>{errors.name}</span>}
-      </div>
-      
-      <div>
-        <label>Category:</label>
-        <NativeSelect
-          value={formData.category}
-          onChange={(e) => setFormData({ ...formData, category: e.target.value })}
-          $isErrored={!!errors.category}
-        >
-          <option value="">Select category</option>
-          <option value="bug">Bug Report</option>
-          <option value="feature">Feature Request</option>
-          <option value="question">Question</option>
-        </NativeSelect>
-        {errors.category && <span style={{ color: 'red' }}>{errors.category}</span>}
-      </div>
-      
-      <div>
-        <label>Message:</label>
-        <NativeTextarea
-          value={formData.message}
-          onChange={(e) => setFormData({ ...formData, message: e.target.value })}
-          $isErrored={!!errors.message}
-          placeholder="Describe your issue..."
-          rows={5}
-        />
-        {errors.message && <span style={{ color: 'red' }}>{errors.message}</span>}
-      </div>
-      
-      <button type="submit">Submit</button>
-    </form>
-  );
-}
-```
-
-### Different Input Types
-```tsx
-import { NativeInput, NativeTimeInput } from '@pushwoosh/dumb-components';
-
-function InputTypes() {
-  const [formData, setFormData] = useState({
-    email: '',
-    password: '',
-    number: '',
-    date: '',
-    time: '09:00',
-    url: ''
-  });
-
-  return (
-    <div>
-      <NativeInput
-        type="email"
-        value={formData.email}
-        onChange={(e) => setFormData({ ...formData, email: e.target.value })}
-        placeholder="email@example.com"
-      />
-
-      <NativeInput
-        type="password"
-        value={formData.password}
-        onChange={(e) => setFormData({ ...formData, password: e.target.value })}
-        placeholder="Password"
-      />
-
-      <NativeInput
-        type="number"
-        value={formData.number}
-        onChange={(e) => setFormData({ ...formData, number: e.target.value })}
-        placeholder="Enter number"
-        min="0"
-        max="100"
-      />
-
-      <NativeInput
-        type="date"
-        value={formData.date}
-        onChange={(e) => setFormData({ ...formData, date: e.target.value })}
-      />
-
-      <NativeTimeInput
-        value={formData.time}
-        onChange={(e) => setFormData({ ...formData, time: e.target.value })}
-      />
-
-      <NativeInput
-        type="url"
-        value={formData.url}
-        onChange={(e) => setFormData({ ...formData, url: e.target.value })}
-        placeholder="https://example.com"
-      />
-    </div>
-  );
-}
-```
-
-### Custom Textarea Sizes
-```tsx
-import { NativeTextarea } from '@pushwoosh/dumb-components';
-
-function TextareaSizes() {
-  return (
-    <div style={{ display: 'flex', gap: '20px' }}>
-      <NativeTextarea
-        placeholder="Small textarea"
-        $width="200px"
-        rows={3}
-      />
-      
-      <NativeTextarea
-        placeholder="Medium textarea"
-        $width="300px"
-        rows={5}
-      />
-      
-      <NativeTextarea
-        placeholder="Large textarea"
-        $width="400px"
-        rows={8}
-      />
-    </div>
-  );
-}
-```
-
-### Select with Grouped Options
-```tsx
-import { NativeSelect } from '@pushwoosh/dumb-components';
-
-function GroupedSelect() {
-  const [value, setValue] = useState('');
-  
-  return (
-    <NativeSelect
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-    >
-      <option value="">Choose a programming language</option>
-      
-      <optgroup label="Frontend">
-        <option value="javascript">JavaScript</option>
-        <option value="typescript">TypeScript</option>
-        <option value="html">HTML</option>
-        <option value="css">CSS</option>
-      </optgroup>
-      
-      <optgroup label="Backend">
-        <option value="node">Node.js</option>
-        <option value="python">Python</option>
-        <option value="java">Java</option>
-        <option value="csharp">C#</option>
-      </optgroup>
-      
-      <optgroup label="Database">
-        <option value="mysql">MySQL</option>
-        <option value="postgresql">PostgreSQL</option>
-        <option value="mongodb">MongoDB</option>
-      </optgroup>
-    </NativeSelect>
-  );
-}
-```
-
-### Disabled and ReadOnly States
-```tsx
-import { NativeInput, NativeSelect, NativeTextarea, NativeTimeInput } from '@pushwoosh/dumb-components';
-
-function DisabledStates() {
-  return (
-    <div>
-      {/* Disabled inputs */}
-      <NativeInput
-        value="Disabled input"
-        disabled
-        placeholder="This is disabled"
-      />
-
-      <NativeSelect disabled>
-        <option>Disabled select</option>
-      </NativeSelect>
-
-      <NativeTextarea
-        value="Disabled textarea"
-        disabled
-        rows={3}
-      />
-
-      <NativeTimeInput
-        value="09:00"
-        disabled
-      />
-
-      {/* Read-only inputs */}
-      <NativeInput
-        value="Read-only input"
-        readOnly
-      />
-
-      <NativeTimeInput
-        value="09:00"
-        readOnly
-      />
-
-      <NativeTextarea
-        value="Read-only textarea content"
-        readOnly
-        rows={3}
-      />
-    </div>
-  );
-}
-```
-
-## Props Reference
-
-### Common Props (All Components)
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `$isErrored` | `boolean` | - | `false` | Show error state (red border) |
-| `value` | `string` | - | - | Input value |
-| `onChange` | `(e: ChangeEvent) => void` | - | - | Change handler |
-| `disabled` | `boolean` | - | `false` | Disable the input |
-| `readOnly` | `boolean` | - | `false` | Make input read-only |
-| `placeholder` | `string` | - | - | Placeholder text |
-
-### NativeInput Specific Props
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `type` | `string` | - | `'text'` | Input type (text, email, password, number, etc.) |
-| `autoComplete` | `string` | - | - | Browser autocomplete hint |
-| `maxLength` | `number` | - | - | Maximum character length |
-| `pattern` | `string` | - | - | Validation pattern (regex) |
-| `min` | `string \| number` | - | - | Minimum value (for number/date inputs) |
-| `max` | `string \| number` | - | - | Maximum value (for number/date inputs) |
-| `step` | `string \| number` | - | - | Step value (for number inputs) |
-
-### NativeSelect Specific Props
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `multiple` | `boolean` | - | `false` | Allow multiple selections |
-| `size` | `number` | - | - | Number of visible options |
-| `children` | `ReactNode` | - | - | option and optgroup elements |
-
-### NativeTextarea Specific Props
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `$width` | `string` | - | `'100%'` | Custom width |
-| `rows` | `number` | - | - | Number of visible rows |
-| `cols` | `number` | - | - | Number of visible columns |
-| `wrap` | `'soft' \| 'hard'` | - | `'soft'` | Text wrapping behavior |
-| `resize` | `string` | - | - | CSS resize property |
-
-### NativeTimeInput Specific Props
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `value` | `string` | - | - | Time value in HH:MM format |
-| `onChange` | `(e: ChangeEvent) => void` | - | - | Change handler |
-| `min` | `string` | - | - | Minimum time value |
-| `max` | `string` | - | - | Maximum time value |
-| `step` | `number` | - | - | Step value in seconds |
-| `disabled` | `boolean` | - | `false` | Disable the input |
-| `readOnly` | `boolean` | - | `false` | Make input read-only |
-
-## AI Agent Guidelines
-
-### ✅ Recommended Patterns
-- Use native components as building blocks for custom form components
-- Always handle both `value` and `onChange` for controlled components
-- Use `$isErrored` prop consistently for validation feedback
-- Leverage HTML5 input types for better UX (email, number, date, etc.)
-- Provide meaningful placeholder text and labels
-- Use proper form structure with labels and validation messages
-- Consider accessibility with proper ARIA attributes when needed
-
-### ❌ Common Mistakes to Avoid
-- Don't forget the `$` prefix for styled-component props (`$isErrored`, `$width`)
-- Don't mix controlled and uncontrolled patterns
-- Avoid inline styles - use styled-components or CSS classes
-- Don't skip validation feedback when using `$isErrored`
-- Avoid putting complex logic in onChange handlers
-- Don't forget to handle disabled states properly
-- Avoid using these components directly in UI - prefer enhanced versions
-
-### Integration Tips
-- These are **base components** - typically used internally by other components
-- All components use Pushwoosh Design System tokens for consistent styling
-- Error states automatically change border color to red
-- Focus states are styled with bright blue border
-- Disabled states use frozen background color
-- NativeSelect includes custom dropdown arrow styling
-- Components automatically inherit font family from design system
-- Use EnhancedInput, Select, etc. for user-facing forms instead
-
-### Styling Notes
-- Components use `styled-components` with design system constants
-- Border radius uses `ShapeRadius.CONTROL` (4px for TimeInput)
-- Colors are from Pushwoosh color palette
-- Font sizes and line heights are from typography scale
-- Input height is standardized using `UnitSize.FIELD_HEIGHT` (36px for NativeTimeInput)
-- Focus outline is removed in favor of border styling
-- NativeTimeInput hides the native calendar picker indicator for consistent styling
-
-## Related Components
-- **EnhancedInput** - Uses NativeInput internally with icons and clear functionality
-- **Select** - Advanced select component built on react-select
-- **Radio** - For single choice selections
-- **Checkbox** - For boolean/multiple choice inputs
-- **Switch** - For boolean toggle inputs
-- **DateTimePicker** - For date/time selections
-- **InputFile** - For file uploads