@pushwoosh/dumb-components 1.1.39 → 1.1.41

package/native/ai-documentation.mdx

@@ -0,0 +1,433 @@
+# Native Components - AI Documentation
+
+> Auto-generated AI agent documentation for Native HTML components
+> Part of @pushwoosh/dumb-components library
+
+## Overview
+**Components:** NativeInput, NativeSelect, NativeTextarea
+**Import Path:** `import { NativeInput, NativeSelect, NativeTextarea } 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/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.
+```
+
+## 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}
+    />
+  );
+}
+```
+
+## 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 } from '@pushwoosh/dumb-components';
+
+function InputTypes() {
+  const [formData, setFormData] = useState({
+    email: '',
+    password: '',
+    number: '',
+    date: '',
+    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 })}
+      />
+      
+      <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 } 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}
+      />
+      
+      {/* Read-only inputs */}
+      <NativeInput
+        value="Read-only input"
+        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 |
+
+## 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`
+- Colors are from Pushwoosh color palette
+- Font sizes and line heights are from typography scale
+- Input height is standardized using `UnitSize.FIELD_HEIGHT`
+- Focus outline is removed in favor of border 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/dumb-components",
-  "version": "1.1.39",
+  "version": "1.1.41",
   "description": "React components to build Pushwoosh products",
   "main": "index.js",
   "module": "index.js",
@@ -8,7 +8,8 @@
   "sideEffects": false,
   "scripts": {
     "start": "npm --prefix ./storybook run storybook",
-    "build": "pushwoosh-engine lib:build",
+    "build": "pushwoosh-engine lib:build && npm run copy-docs",
+    "copy-docs": "node scripts/copy-docs.js",
     "check": "npm run check:lint && npm run check:types",
     "check:lint": "echo \"Run check:lint\" && eslint src",
     "check:types": "echo \"Run check:types\" && pushwoosh-engine lib:check-types"
@@ -26,6 +27,7 @@
     "@types/react-dom": "^18.2.22",
     "@types/react-transition-group": "^4.4.12",
     "@types/styled-components": "^5.1.34",
+    "glob": "^11.0.3",
     "pre-commit": "^1.2.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
@@ -37,10 +39,10 @@
     "@codemirror/lang-liquid": "^6.2.2",
     "@floating-ui/react-dom": "^2.1.2",
     "@lezer/highlight": "^1.2.1",
-    "@pushwoosh/kit-constants": "^1.6.9",
-    "@pushwoosh/kit-helpers": "^4.8.2",
-    "@pushwoosh/kit-icons": "^2.1.2",
-    "@pushwoosh/kit-typography": "^1.7.3",
+    "@pushwoosh/kit-constants": "^1.6.12",
+    "@pushwoosh/kit-helpers": "^4.8.5",
+    "@pushwoosh/kit-icons": "^2.1.8",
+    "@pushwoosh/kit-typography": "^1.7.4",
     "@tippyjs/react": "^4.2.6",
     "@uiw/codemirror-themes": "^4.23.8",
     "@uiw/react-codemirror": "^4.23.8",