@delightui/components 0.1.105 → 0.1.107

package/docs/components/atoms/Button.md

@@ -0,0 +1,197 @@
+# Button
+
+## Description
+
+Flexible button component with multiple variants, sizes, and states. Supports icons, loading states, and various styling options to fit different use cases throughout the application.
+
+## Aliases
+
+- Action Button
+- CTA (Call to Action)
+- Click Button
+- Submit Button
+
+## Props Breakdown
+
+**Extends:** `HTMLAttributes<HTMLButtonElement>` (excluding `style`)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `appearance` | `'Default' \| 'Inverse'` | `'Default'` | No | Visual appearance theme of the button |
+| `type` | `'Filled' \| 'Outlined' \| 'Ghost'` | `'Filled'` | No | Visual style variant of the button |
+| `style` | `'Primary' \| 'Secondary' \| 'Destructive'` | `'Primary'` | No | Color scheme and intent of the button |
+| `size` | `'Small' \| 'Medium' \| 'Large'` | `'Medium'` | No | Size variant of the button |
+| `loading` | `boolean` | `false` | No | Shows loading spinner and disables interaction |
+| `disabled` | `boolean` | `false` | No | Disables the button and shows disabled state |
+| `leadingIcon` | `ReactNode` | - | No | Icon to display before the button text |
+| `trailingIcon` | `ReactNode` | - | No | Icon to display after the button text |
+| `onClick` | `(event?: MouseEvent<HTMLElement>) => void` | - | No | Click event handler |
+| `className` | `string` | - | No | Additional CSS class names |
+| `actionType` | `'button' \| 'submit' \| 'reset'` | `'button'` | No | HTML button type attribute |
+| `children` | `ReactNode` | - | No | Button content/text |
+
+Plus all standard HTML button attributes (id, title, aria-*, data-*, etc.).
+
+## Examples
+
+### Basic Usage
+```tsx
+import { Button } from '@delightui/components';
+
+function BasicExample() {
+  return (
+    <Button onClick={() => console.log('Clicked')}>
+      Click Me
+    </Button>
+  );
+}
+```
+
+### Button Variants
+```tsx
+function VariantsExample() {
+  return (
+    <div className="button-group">
+      {/* Different types */}
+      <Button type="Filled">Filled Button</Button>
+      <Button type="Outlined">Outlined Button</Button>
+      <Button type="Ghost">Ghost Button</Button>
+      
+      {/* Different styles */}
+      <Button style="Primary">Primary</Button>
+      <Button style="Secondary">Secondary</Button>
+      <Button style="Destructive">Delete</Button>
+    </div>
+  );
+}
+```
+
+### Button Sizes
+```tsx
+function SizesExample() {
+  return (
+    <div className="button-sizes">
+      <Button size="Small">Small</Button>
+      <Button size="Medium">Medium</Button>
+      <Button size="Large">Large</Button>
+    </div>
+  );
+}
+```
+
+### Buttons with Icons
+```tsx
+import { PlusIcon, ArrowRightIcon } from '@heroicons/react/24/outline';
+
+function IconButtonsExample() {
+  return (
+    <div className="icon-buttons">
+      <Button leadingIcon={<PlusIcon />}>
+        Add Item
+      </Button>
+      
+      <Button trailingIcon={<ArrowRightIcon />}>
+        Continue
+      </Button>
+      
+      <Button 
+        leadingIcon={<PlusIcon />}
+        trailingIcon={<ArrowRightIcon />}
+      >
+        Add & Continue
+      </Button>
+    </div>
+  );
+}
+```
+
+### Loading and Disabled States
+```tsx
+function StatesExample() {
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async () => {
+    setLoading(true);
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    setLoading(false);
+  };
+
+  return (
+    <div className="button-states">
+      <Button 
+        loading={loading}
+        onClick={handleSubmit}
+      >
+        Submit with loading
+      </Button>
+      
+      <Button disabled>
+        Disabled Button
+      </Button>
+    </div>
+  );
+}
+```
+
+### Form Integration
+```tsx
+import { Button, Form, FormField, Input } from '@delightui/components';
+
+function FormExample() {
+  const handleSubmit = (values, setError) => {
+    console.log('Form submitted with values:', values);
+    // Handle form submission
+  };
+
+  const handleReset = () => {
+    console.log('Form reset');
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField name="name" label="Full Name" required>
+        <Input placeholder="Enter your name" />
+      </FormField>
+      
+      <FormField name="email" label="Email" required>
+        <Input inputType="Email" placeholder="Enter your email" />
+      </FormField>
+      
+      <div className="form-actions">
+        <Button 
+          actionType="reset"
+          type="Outlined"
+          style="Secondary"
+          onClick={handleReset}
+        >
+          Reset
+        </Button>
+        
+        <Button 
+          actionType="submit"
+          style="Primary"
+        >
+          Submit Form
+        </Button>
+      </div>
+    </Form>
+  );
+}
+```
+
+### Appearance Variants
+```tsx
+function AppearanceExample() {
+  return (
+    <div className="appearance-variants">
+      {/* Default appearance */}
+      <Button appearance="Default">Default Theme</Button>
+      
+      {/* Inverse appearance for dark backgrounds */}
+      <div className="dark-background">
+        <Button appearance="Inverse">Inverse Theme</Button>
+      </div>
+    </div>
+  );
+}
+```

package/docs/components/atoms/Checkbox.md

@@ -0,0 +1,299 @@
+# Checkbox
+
+## Description
+
+Customizable checkbox input component with support for controlled and uncontrolled states, various sizes, label positioning, and form integration. Includes proper accessibility features and validation support.
+
+## Aliases
+
+- Check Box
+- Tick Box
+- Selection Box
+- Boolean Input
+- Toggle Checkbox
+
+## Props Breakdown
+
+**Extends:** `InputHTMLAttributes<HTMLInputElement>` (excluding 'type', 'size') + `ControlledFormComponentProps<boolean>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `ReactNode` | - | No | Label content for the checkbox |
+| `size` | `'Small' \| 'Medium' \| 'Large'` | `'Medium'` | No | Size variant of the checkbox |
+| `type` | `'Default' \| 'Inverse'` | `'Default'` | No | Visual theme of the checkbox |
+| `defaultChecked` | `boolean` | `false` | No | Default checked state for uncontrolled usage |
+| `labelAlignment` | `'Left' \| 'Right'` | - | No | Position of the label relative to the checkbox |
+| `initialValue` | `boolean` | - | No | Initial value for controlled form usage |
+| `checked` | `boolean` | - | No | Controlled checked state |
+| `value` | `boolean` | - | No | Current value for controlled form usage |
+| `onValueChange` | `(value: boolean) => void` | - | No | Callback when checkbox value changes |
+| `disabled` | `boolean` | `false` | No | Whether the checkbox is disabled |
+| `required` | `boolean` | `false` | No | Whether the checkbox is required |
+| `invalid` | `boolean` | `false` | No | Whether the checkbox value is invalid |
+| `id` | `string` | - | No | HTML id attribute |
+| `className` | `string` | - | No | Additional CSS class names |
+| `name` | `string` | - | No | HTML name attribute |
+
+*Note: In addition to the props listed above, this component inherits all HTML input attributes (except 'type' and 'size') such as `onChange`, `onFocus`, `onBlur`, `aria-*`, `data-*`, etc. It also includes controlled form component properties for integration with form libraries.*
+
+## Examples
+
+### Basic Usage
+```tsx
+import { Checkbox } from '@delightui/components';
+
+function BasicExample() {
+  const [checked, setChecked] = useState(false);
+
+  return (
+    <Checkbox
+      checked={checked}
+      onValueChange={setChecked}
+    >
+      Accept terms and conditions
+    </Checkbox>
+  );
+}
+```
+
+### Checkbox Sizes
+```tsx
+function SizesExample() {
+  return (
+    <div className="checkbox-sizes">
+      <Checkbox size="Small">Small checkbox</Checkbox>
+      <Checkbox size="Medium">Medium checkbox</Checkbox>
+      <Checkbox size="Large">Large checkbox</Checkbox>
+    </div>
+  );
+}
+```
+
+### Label Alignment
+```tsx
+function AlignmentExample() {
+  return (
+    <div className="checkbox-alignment">
+      <Checkbox labelAlignment="Left">
+        Label on the left
+      </Checkbox>
+      
+      <Checkbox labelAlignment="Right">
+        Label on the right
+      </Checkbox>
+    </div>
+  );
+}
+```
+
+### Checkbox Types
+```tsx
+function TypesExample() {
+  return (
+    <div className="checkbox-types">
+      <Checkbox type="Default">
+        Default theme
+      </Checkbox>
+      
+      {/* Use inverse for dark backgrounds */}
+      <div className="dark-background">
+        <Checkbox type="Inverse">
+          Inverse theme
+        </Checkbox>
+      </div>
+    </div>
+  );
+}
+```
+
+### Disabled and Invalid States
+```tsx
+function StatesExample() {
+  return (
+    <div className="checkbox-states">
+      <Checkbox disabled>
+        Disabled checkbox
+      </Checkbox>
+      
+      <Checkbox disabled checked>
+        Disabled checked
+      </Checkbox>
+      
+      <Checkbox invalid>
+        Invalid checkbox
+      </Checkbox>
+      
+      <Checkbox required>
+        Required checkbox
+      </Checkbox>
+    </div>
+  );
+}
+```
+
+### Uncontrolled Usage
+```tsx
+function UncontrolledExample() {
+  const handleChange = (event) => {
+    console.log('Checkbox changed:', event.target.checked);
+  };
+
+  return (
+    <div className="uncontrolled-checkboxes">
+      <Checkbox 
+        defaultChecked={false}
+        onChange={handleChange}
+        name="newsletter"
+      >
+        Subscribe to newsletter
+      </Checkbox>
+      
+      <Checkbox 
+        defaultChecked={true}
+        onChange={handleChange}
+        name="notifications"
+      >
+        Enable notifications
+      </Checkbox>
+    </div>
+  );
+}
+```
+
+### Form Integration
+```tsx
+import { Checkbox, Form, FormField } from '@delightui/components';
+
+function FormExample() {
+  const handleSubmit = (values, setError) => {
+    if (!values.terms) {
+      setError('terms', 'You must accept the terms and conditions');
+      return;
+    }
+    
+    console.log('Form submitted:', values);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField 
+        name="terms" 
+        required
+        message="Please accept the terms to continue"
+      >
+        <Checkbox>
+          I accept the <a href="/terms">terms and conditions</a>
+        </Checkbox>
+      </FormField>
+      
+      <FormField name="newsletter">
+        <Checkbox>
+          Subscribe to our newsletter for updates
+        </Checkbox>
+      </FormField>
+      
+      <FormField name="marketing">
+        <Checkbox>
+          Receive marketing communications
+        </Checkbox>
+      </FormField>
+      
+      <Button actionType="submit">
+        Submit
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Multi-Selection List
+```tsx
+function MultiSelectionExample() {
+  const [selectedItems, setSelectedItems] = useState([]);
+  
+  const options = [
+    { id: 'react', label: 'React' },
+    { id: 'vue', label: 'Vue.js' },
+    { id: 'angular', label: 'Angular' },
+    { id: 'svelte', label: 'Svelte' }
+  ];
+
+  const handleItemToggle = (itemId, checked) => {
+    setSelectedItems(prev => 
+      checked 
+        ? [...prev, itemId]
+        : prev.filter(id => id !== itemId)
+    );
+  };
+
+  return (
+    <div className="multi-selection">
+      <h3>Select your preferred frameworks:</h3>
+      {options.map(option => (
+        <Checkbox
+          key={option.id}
+          checked={selectedItems.includes(option.id)}
+          onValueChange={(checked) => handleItemToggle(option.id, checked)}
+        >
+          {option.label}
+        </Checkbox>
+      ))}
+      
+      <p>Selected: {selectedItems.join(', ')}</p>
+    </div>
+  );
+}
+```
+
+### Select All Pattern
+```tsx
+function SelectAllExample() {
+  const [items, setItems] = useState([
+    { id: 1, name: 'Item 1', selected: false },
+    { id: 2, name: 'Item 2', selected: false },
+    { id: 3, name: 'Item 3', selected: false },
+  ]);
+
+  const allSelected = items.every(item => item.selected);
+  const someSelected = items.some(item => item.selected);
+
+  const handleSelectAll = (checked) => {
+    setItems(items.map(item => ({ ...item, selected: checked })));
+  };
+
+  const handleItemToggle = (itemId, checked) => {
+    setItems(items.map(item => 
+      item.id === itemId ? { ...item, selected: checked } : item
+    ));
+  };
+
+  return (
+    <div className="select-all-pattern">
+      <Checkbox
+        checked={allSelected}
+        // Show indeterminate state when some but not all are selected
+        ref={checkbox => {
+          if (checkbox) {
+            checkbox.indeterminate = someSelected && !allSelected;
+          }
+        }}
+        onValueChange={handleSelectAll}
+      >
+        Select All
+      </Checkbox>
+      
+      <hr />
+      
+      {items.map(item => (
+        <Checkbox
+          key={item.id}
+          checked={item.selected}
+          onValueChange={(checked) => handleItemToggle(item.id, checked)}
+        >
+          {item.name}
+        </Checkbox>
+      ))}
+    </div>
+  );
+}
+```