@delightui/components 0.1.105 → 0.1.107

package/docs/components/atoms/RadioButtonItem.md

@@ -0,0 +1,588 @@
+# RadioButtonItem
+
+An enhanced radio button component that extends the basic RadioButton with additional action button functionality. It provides all the standard radio button features plus an optional right-side action button, making it perfect for scenarios where you need both selection and additional actions on radio options.
+
+## Aliases
+
+- RadioButtonItem
+- RadioItem
+- ActionRadioButton
+
+## Props Breakdown
+
+**Extends:** `RadioButtonProps` (which extends `InputHTMLAttributes<HTMLInputElement>` (excluding `type`, `size`, `value`) and `ControlledFormComponentProps<string | number>`)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `showRightButton` | `boolean` | `false` | No | Flag to show right button |
+| `onRightButtonClick` | `() => void` | `undefined` | No | Callback function when the right button is clicked |
+| `rightButtonIcon` | `ReactNode` | `undefined` | No | Custom icon for the right button |
+| `children` | `ReactNode` | `undefined` | No | The label content of the radio button |
+| `size` | `'Small' \| 'Medium' \| 'Large'` | `'Medium'` | No | The size of the radio button |
+| `labelAlignment` | `'Left' \| 'Right'` | `'Right'` | No | Position of the label relative to the radio button |
+| `initialValue` | `string \| number` | `undefined` | No | The initial value for the field |
+| `checked` | `boolean` | `undefined` | No | Whether the radio button is checked |
+| `value` | `string \| number` | `undefined` | No | The current value of the form field |
+| `onValueChange` | `(value: string \| number) => void` | `undefined` | No | Callback function that is called when the field value changes |
+| `disabled` | `boolean` | `false` | No | Whether the form field is disabled and cannot be interacted with |
+| `required` | `boolean` | `false` | No | Whether the form field must have a value |
+| `invalid` | `boolean` | `false` | No | Whether the form field's current value is invalid |
+| `id` | `string` | `undefined` | No | Id for the form field |
+| `name` | `string` | `undefined` | No | Name attribute for the radio button |
+
+Plus all standard HTML input attributes (id, title, aria-*, data-*, etc.).
+
+## Examples
+
+### Basic RadioButtonItem with Action
+
+```tsx
+import { RadioButtonItem, Icon } from '@delightui/components';
+
+function BasicRadioButtonItemExample() {
+  const [selectedOption, setSelectedOption] = useState('');
+
+  const handleEdit = (option: string) => {
+    console.log(`Edit clicked for: ${option}`);
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      <RadioButtonItem
+        name="basicExample"
+        value="option1"
+        checked={selectedOption === 'option1'}
+        onValueChange={setSelectedOption}
+        showRightButton
+        rightButtonIcon={<Icon name="InfoFilled" />}
+        onRightButtonClick={() => handleEdit('option1')}
+      >
+        Option 1 with Edit
+      </RadioButtonItem>
+      
+      <RadioButtonItem
+        name="basicExample"
+        value="option2"
+        checked={selectedOption === 'option2'}
+        onValueChange={setSelectedOption}
+        showRightButton
+        rightButtonIcon={<Icon name="InfoFilled" />}
+        onRightButtonClick={() => handleEdit('option2')}
+      >
+        Option 2 with Edit
+      </RadioButtonItem>
+      
+      <RadioButtonItem
+        name="basicExample"
+        value="option3"
+        checked={selectedOption === 'option3'}
+        onValueChange={setSelectedOption}
+      >
+        Option 3 without Action
+      </RadioButtonItem>
+    </div>
+  );
+}
+```
+
+### Payment Methods with Management
+
+```tsx
+import { RadioButtonItem, Icon, Text } from '@delightui/components';
+
+function PaymentMethodsExample() {
+  const [selectedPayment, setSelectedPayment] = useState('');
+  const [paymentMethods] = useState([
+    { id: 'card1', name: 'Visa ending in 4532', details: 'Expires 12/25' },
+    { id: 'card2', name: 'Mastercard ending in 9876', details: 'Expires 08/26' },
+    { id: 'paypal', name: 'PayPal', details: 'user@example.com' }
+  ]);
+
+  const handleEditPayment = (id: string) => {
+    console.log(`Edit payment method: ${id}`);
+  };
+
+  const handleDeletePayment = (id: string) => {
+    console.log(`Delete payment method: ${id}`);
+  };
+
+  return (
+    <div>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Select Payment Method
+      </Text>
+      
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+        {paymentMethods.map((method) => (
+          <RadioButtonItem
+            key={method.id}
+            name="paymentMethod"
+            value={method.id}
+            checked={selectedPayment === method.id}
+            onValueChange={setSelectedPayment}
+            showRightButton
+            rightButtonIcon={<Icon name="InfoFilled" />}
+            onRightButtonClick={() => handleEditPayment(method.id)}
+          >
+            <div>
+              <div>{method.name}</div>
+              <Text size="small" color="secondary">
+                {method.details}
+              </Text>
+            </div>
+          </RadioButtonItem>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Address Selection with Edit Options
+
+```tsx
+import { RadioButtonItem, Icon, Text } from '@delightui/components';
+
+function AddressSelectionExample() {
+  const [selectedAddress, setSelectedAddress] = useState('');
+  const [addresses] = useState([
+    {
+      id: 'home',
+      label: 'Home',
+      address: '123 Main St, Anytown, ST 12345',
+      type: 'Residential'
+    },
+    {
+      id: 'work',
+      label: 'Work',
+      address: '456 Business Ave, Corporate City, ST 67890',
+      type: 'Business'
+    },
+    {
+      id: 'other',
+      label: 'Other',
+      address: '789 Alternative Rd, Different Town, ST 54321',
+      type: 'Residential'
+    }
+  ]);
+
+  const handleEditAddress = (id: string) => {
+    console.log(`Edit address: ${id}`);
+  };
+
+  return (
+    <div>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Delivery Address
+      </Text>
+      
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+        {addresses.map((addr) => (
+          <RadioButtonItem
+            key={addr.id}
+            name="deliveryAddress"
+            value={addr.id}
+            checked={selectedAddress === addr.id}
+            onValueChange={setSelectedAddress}
+            showRightButton
+            rightButtonIcon={<Icon name="InfoFilled" />}
+            onRightButtonClick={() => handleEditAddress(addr.id)}
+            size="Large"
+          >
+            <div>
+              <Text weight="bold">{addr.label}</Text>
+              <Text size="small" color="secondary" style={{ display: 'block', marginTop: '4px' }}>
+                {addr.address}
+              </Text>
+              <Text size="small" color="primary" style={{ display: 'block', marginTop: '2px' }}>
+                {addr.type}
+              </Text>
+            </div>
+          </RadioButtonItem>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Product Variants with Details
+
+```tsx
+import { RadioButtonItem, Icon, Text } from '@delightui/components';
+
+function ProductVariantsExample() {
+  const [selectedVariant, setSelectedVariant] = useState('');
+  const [variants] = useState([
+    {
+      id: 'small',
+      name: 'Small',
+      price: '$19.99',
+      stock: 15,
+      description: 'Perfect for personal use'
+    },
+    {
+      id: 'medium',
+      name: 'Medium',
+      price: '$29.99',
+      stock: 8,
+      description: 'Great for small teams'
+    },
+    {
+      id: 'large',
+      name: 'Large',
+      price: '$39.99',
+      stock: 3,
+      description: 'Ideal for larger groups'
+    }
+  ]);
+
+  const handleViewDetails = (id: string) => {
+    console.log(`View details for variant: ${id}`);
+  };
+
+  return (
+    <div>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Choose Your Size
+      </Text>
+      
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+        {variants.map((variant) => (
+          <RadioButtonItem
+            key={variant.id}
+            name="productVariant"
+            value={variant.id}
+            checked={selectedVariant === variant.id}
+            onValueChange={setSelectedVariant}
+            showRightButton
+            rightButtonIcon={<Icon name="InfoFilled" />}
+            onRightButtonClick={() => handleViewDetails(variant.id)}
+            disabled={variant.stock === 0}
+          >
+            <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', width: '100%' }}>
+              <div>
+                <Text weight="bold">{variant.name}</Text>
+                <Text size="small" color="secondary" style={{ display: 'block' }}>
+                  {variant.description}
+                </Text>
+                <Text size="small" color={variant.stock > 0 ? 'success' : 'error'}>
+                  {variant.stock > 0 ? `${variant.stock} in stock` : 'Out of stock'}
+                </Text>
+              </div>
+              <Text weight="bold" color="primary">
+                {variant.price}
+              </Text>
+            </div>
+          </RadioButtonItem>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Settings with Configuration
+
+```tsx
+import { RadioButtonItem, Icon, Text } from '@delightui/components';
+
+function SettingsConfigurationExample() {
+  const [selectedTheme, setSelectedTheme] = useState('light');
+  const [themes] = useState([
+    {
+      id: 'light',
+      name: 'Light Theme',
+      description: 'Clean and bright interface',
+      customizable: true
+    },
+    {
+      id: 'dark',
+      name: 'Dark Theme',
+      description: 'Easy on the eyes for low light',
+      customizable: true
+    },
+    {
+      id: 'auto',
+      name: 'Auto Theme',
+      description: 'Follows system preference',
+      customizable: false
+    }
+  ]);
+
+  const handleCustomizeTheme = (id: string) => {
+    console.log(`Customize theme: ${id}`);
+  };
+
+  return (
+    <div>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Theme Settings
+      </Text>
+      
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+        {themes.map((theme) => (
+          <RadioButtonItem
+            key={theme.id}
+            name="theme"
+            value={theme.id}
+            checked={selectedTheme === theme.id}
+            onValueChange={setSelectedTheme}
+            showRightButton={theme.customizable}
+            rightButtonIcon={<Icon name="InfoFilled" />}
+            onRightButtonClick={theme.customizable ? () => handleCustomizeTheme(theme.id) : undefined}
+          >
+            <div>
+              <Text weight="bold">{theme.name}</Text>
+              <Text size="small" color="secondary" style={{ display: 'block', marginTop: '4px' }}>
+                {theme.description}
+              </Text>
+              {theme.customizable && (
+                <Text size="small" color="primary" style={{ display: 'block', marginTop: '2px' }}>
+                  Customizable
+                </Text>
+              )}
+            </div>
+          </RadioButtonItem>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Subscription Plans with Details
+
+```tsx
+import { RadioButtonItem, Icon, Text, Button } from '@delightui/components';
+
+function SubscriptionPlansExample() {
+  const [selectedPlan, setSelectedPlan] = useState('');
+  const [plans] = useState([
+    {
+      id: 'basic',
+      name: 'Basic Plan',
+      price: '$9.99/month',
+      features: ['5 GB Storage', '10 Projects', 'Email Support'],
+      popular: false
+    },
+    {
+      id: 'pro',
+      name: 'Pro Plan',
+      price: '$19.99/month',
+      features: ['50 GB Storage', 'Unlimited Projects', 'Priority Support', 'Advanced Analytics'],
+      popular: true
+    },
+    {
+      id: 'enterprise',
+      name: 'Enterprise Plan',
+      price: '$49.99/month',
+      features: ['500 GB Storage', 'Unlimited Everything', '24/7 Phone Support', 'Custom Integrations'],
+      popular: false
+    }
+  ]);
+
+  const handleViewPlanDetails = (id: string) => {
+    console.log(`View details for plan: ${id}`);
+  };
+
+  return (
+    <div>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Choose Your Plan
+      </Text>
+      
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+        {plans.map((plan) => (
+          <div
+            key={plan.id}
+            style={{
+              border: selectedPlan === plan.id ? '2px solid #007bff' : '1px solid #ccc',
+              borderRadius: '8px',
+              padding: '16px',
+              position: 'relative'
+            }}
+          >
+            {plan.popular && (
+              <div style={{
+                position: 'absolute',
+                top: '-8px',
+                right: '16px',
+                backgroundColor: '#007bff',
+                color: 'white',
+                padding: '4px 8px',
+                borderRadius: '4px',
+                fontSize: '12px',
+                fontWeight: 'bold'
+              }}>
+                POPULAR
+              </div>
+            )}
+            
+            <RadioButtonItem
+              name="subscriptionPlan"
+              value={plan.id}
+              checked={selectedPlan === plan.id}
+              onValueChange={setSelectedPlan}
+              showRightButton
+              rightButtonIcon={<Icon name="InfoFilled" />}
+              onRightButtonClick={() => handleViewPlanDetails(plan.id)}
+              size="Large"
+            >
+              <div style={{ width: '100%' }}>
+                <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '8px' }}>
+                  <Text weight="bold" size="large">{plan.name}</Text>
+                  <Text weight="bold" color="primary" size="large">{plan.price}</Text>
+                </div>
+                
+                <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px' }}>
+                  {plan.features.map((feature, index) => (
+                    <Text key={index} size="small" color="secondary">
+                      • {feature}
+                    </Text>
+                  ))}
+                </div>
+              </div>
+            </RadioButtonItem>
+          </div>
+        ))}
+      </div>
+      
+      {selectedPlan && (
+        <Button style={{ width: '100%', marginTop: '20px' }}>
+          Continue with {plans.find(p => p.id === selectedPlan)?.name}
+        </Button>
+      )}
+    </div>
+  );
+}
+```
+
+### File Selection with Actions
+
+```tsx
+import { RadioButtonItem, Icon, Text } from '@delightui/components';
+
+function FileSelectionExample() {
+  const [selectedFile, setSelectedFile] = useState('');
+  const [files] = useState([
+    {
+      id: 'doc1',
+      name: 'Project Proposal.docx',
+      size: '2.4 MB',
+      modified: '2 hours ago',
+      type: 'document'
+    },
+    {
+      id: 'img1',
+      name: 'Design Mockup.png',
+      size: '1.8 MB',
+      modified: '1 day ago',
+      type: 'image'
+    },
+    {
+      id: 'pdf1',
+      name: 'Final Report.pdf',
+      size: '5.2 MB',
+      modified: '3 days ago',
+      type: 'pdf'
+    }
+  ]);
+
+  const handleDownloadFile = (id: string) => {
+    console.log(`Download file: ${id}`);
+  };
+
+  const getFileIcon = (type: string) => {
+    switch (type) {
+      case 'document': return 'AddFilled';
+      case 'image': return 'SearchFilled';
+      case 'pdf': return 'InfoFilled';
+      default: return 'AddFilled';
+    }
+  };
+
+  return (
+    <div>
+      <Text weight="bold" style={{ marginBottom: '16px' }}>
+        Select File to Process
+      </Text>
+      
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+        {files.map((file) => (
+          <RadioButtonItem
+            key={file.id}
+            name="selectedFile"
+            value={file.id}
+            checked={selectedFile === file.id}
+            onValueChange={setSelectedFile}
+            showRightButton
+            rightButtonIcon={<Icon name="AddFilled" />}
+            onRightButtonClick={() => handleDownloadFile(file.id)}
+          >
+            <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+              <Icon name={getFileIcon(file.type)} />
+              <div>
+                <Text weight="bold">{file.name}</Text>
+                <Text size="small" color="secondary" style={{ display: 'block' }}>
+                  {file.size} • Modified {file.modified}
+                </Text>
+              </div>
+            </div>
+          </RadioButtonItem>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Different Action Icons
+
+```tsx
+import { RadioButtonItem, Icon } from '@delightui/components';
+
+function DifferentActionIconsExample() {
+  const [selectedOption, setSelectedOption] = useState('');
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      <RadioButtonItem
+        name="actionIcons"
+        value="edit"
+        checked={selectedOption === 'edit'}
+        onValueChange={setSelectedOption}
+        showRightButton
+        rightButtonIcon={<Icon name="InfoFilled" />}
+        onRightButtonClick={() => console.log('Edit action')}
+      >
+        Option with Edit Action
+      </RadioButtonItem>
+      
+      <RadioButtonItem
+        name="actionIcons"
+        value="info"
+        checked={selectedOption === 'info'}
+        onValueChange={setSelectedOption}
+        showRightButton
+        rightButtonIcon={<Icon name="InfoFilled" />}
+        onRightButtonClick={() => console.log('Info action')}
+      >
+        Option with Info Action
+      </RadioButtonItem>
+      
+      <RadioButtonItem
+        name="actionIcons"
+        value="delete"
+        checked={selectedOption === 'delete'}
+        onValueChange={setSelectedOption}
+        showRightButton
+        rightButtonIcon={<Icon name="CloseDeleteOutlined" />}
+        onRightButtonClick={() => console.log('Delete action')}
+      >
+        Option with Delete Action
+      </RadioButtonItem>
+    </div>
+  );
+}
+```