@delightui/components 0.1.105 → 0.1.107

package/docs/components/atoms/RadioButton.md

@@ -0,0 +1,614 @@
+# RadioButton
+
+A radio button component that allows users to select one option from a group of mutually exclusive choices. It provides flexible sizing, label positioning, and integrates seamlessly with form handling. RadioButton components are typically used in groups where only one selection is allowed.
+
+## Aliases
+
+- RadioButton
+- Radio
+- OptionButton
+
+## Props Breakdown
+
+**Extends:** `InputHTMLAttributes<HTMLInputElement>` (excluding `type`, `size`, `value`) + `ControlledFormComponentProps<string | number>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `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 (onChange, onFocus, onBlur, aria-*, data-*, etc.).
+
+## Examples
+
+### Basic Radio Button
+
+```tsx
+import { RadioButton } from '@delightui/components';
+
+function BasicRadioButtonExample() {
+  const [selectedOption, setSelectedOption] = useState('');
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      <RadioButton
+        name="basicExample"
+        value="option1"
+        checked={selectedOption === 'option1'}
+        onValueChange={setSelectedOption}
+      >
+        Option 1
+      </RadioButton>
+      
+      <RadioButton
+        name="basicExample"
+        value="option2"
+        checked={selectedOption === 'option2'}
+        onValueChange={setSelectedOption}
+      >
+        Option 2
+      </RadioButton>
+      
+      <RadioButton
+        name="basicExample"
+        value="option3"
+        checked={selectedOption === 'option3'}
+        onValueChange={setSelectedOption}
+      >
+        Option 3
+      </RadioButton>
+    </div>
+  );
+}
+```
+
+### Different Sizes
+
+```tsx
+import { RadioButton } from '@delightui/components';
+
+function SizedRadioButtonExample() {
+  const [selectedSize, setSelectedSize] = useState('medium');
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <RadioButton
+        name="sizeExample"
+        value="small"
+        size="Small"
+        checked={selectedSize === 'small'}
+        onValueChange={setSelectedSize}
+      >
+        Small Radio Button
+      </RadioButton>
+      
+      <RadioButton
+        name="sizeExample"
+        value="medium"
+        size="Medium"
+        checked={selectedSize === 'medium'}
+        onValueChange={setSelectedSize}
+      >
+        Medium Radio Button
+      </RadioButton>
+      
+      <RadioButton
+        name="sizeExample"
+        value="large"
+        size="Large"
+        checked={selectedSize === 'large'}
+        onValueChange={setSelectedSize}
+      >
+        Large Radio Button
+      </RadioButton>
+    </div>
+  );
+}
+```
+
+### Label Alignment
+
+```tsx
+import { RadioButton } from '@delightui/components';
+
+function LabelAlignmentExample() {
+  const [selectedAlignment, setSelectedAlignment] = useState('right');
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <RadioButton
+        name="alignmentExample"
+        value="left"
+        labelAlignment="Left"
+        checked={selectedAlignment === 'left'}
+        onValueChange={setSelectedAlignment}
+      >
+        Label on Left
+      </RadioButton>
+      
+      <RadioButton
+        name="alignmentExample"
+        value="right"
+        labelAlignment="Right"
+        checked={selectedAlignment === 'right'}
+        onValueChange={setSelectedAlignment}
+      >
+        Label on Right
+      </RadioButton>
+    </div>
+  );
+}
+```
+
+### Form Integration
+
+```tsx
+import { Form, FormField, RadioButton, Button } from '@delightui/components';
+
+function RadioButtonFormExample() {
+  const handleSubmit = (data: any) => {
+    console.log('Form submitted:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="paymentMethod"
+        label="Payment Method"
+        required
+      >
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <RadioButton name="paymentMethod" value="credit-card">
+            Credit Card
+          </RadioButton>
+          <RadioButton name="paymentMethod" value="paypal">
+            PayPal
+          </RadioButton>
+          <RadioButton name="paymentMethod" value="bank-transfer">
+            Bank Transfer
+          </RadioButton>
+        </div>
+      </FormField>
+
+      <FormField
+        name="deliverySpeed"
+        label="Delivery Speed"
+        required
+      >
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <RadioButton name="deliverySpeed" value="standard">
+            Standard Delivery (5-7 days)
+          </RadioButton>
+          <RadioButton name="deliverySpeed" value="express">
+            Express Delivery (2-3 days)
+          </RadioButton>
+          <RadioButton name="deliverySpeed" value="overnight">
+            Overnight Delivery
+          </RadioButton>
+        </div>
+      </FormField>
+
+      <Button type="submit">
+        Complete Order
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Survey Example
+
+```tsx
+import { Form, FormField, RadioButton, Button, Text } from '@delightui/components';
+
+function SurveyExample() {
+  const handleSubmit = (data: any) => {
+    console.log('Survey submitted:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="satisfaction"
+        label="How satisfied are you with our service?"
+        required
+      >
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <RadioButton name="satisfaction" value="very-satisfied">
+            Very Satisfied
+          </RadioButton>
+          <RadioButton name="satisfaction" value="satisfied">
+            Satisfied
+          </RadioButton>
+          <RadioButton name="satisfaction" value="neutral">
+            Neutral
+          </RadioButton>
+          <RadioButton name="satisfaction" value="dissatisfied">
+            Dissatisfied
+          </RadioButton>
+          <RadioButton name="satisfaction" value="very-dissatisfied">
+            Very Dissatisfied
+          </RadioButton>
+        </div>
+      </FormField>
+
+      <FormField
+        name="recommendation"
+        label="Would you recommend us to others?"
+        required
+      >
+        <div style={{ display: 'flex', gap: '24px' }}>
+          <RadioButton name="recommendation" value="yes">
+            Yes
+          </RadioButton>
+          <RadioButton name="recommendation" value="no">
+            No
+          </RadioButton>
+          <RadioButton name="recommendation" value="maybe">
+            Maybe
+          </RadioButton>
+        </div>
+      </FormField>
+
+      <Button type="submit">
+        Submit Survey
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Disabled States
+
+```tsx
+import { RadioButton } from '@delightui/components';
+
+function DisabledRadioButtonExample() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+      <RadioButton
+        name="disabledExample"
+        value="enabled"
+        checked={true}
+      >
+        Enabled and Selected
+      </RadioButton>
+      
+      <RadioButton
+        name="disabledExample"
+        value="disabled-unchecked"
+        disabled
+      >
+        Disabled and Unchecked
+      </RadioButton>
+      
+      <RadioButton
+        name="disabledExample"
+        value="disabled-checked"
+        disabled
+        checked={true}
+      >
+        Disabled and Checked
+      </RadioButton>
+    </div>
+  );
+}
+```
+
+### Settings Configuration
+
+```tsx
+import { Form, FormField, RadioButton, Button, Text } from '@delightui/components';
+
+function SettingsConfigExample() {
+  const handleSubmit = (data: any) => {
+    console.log('Settings saved:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="theme"
+        label="Theme Preference"
+      >
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <RadioButton name="theme" value="light">
+            Light Theme
+          </RadioButton>
+          <RadioButton name="theme" value="dark">
+            Dark Theme
+          </RadioButton>
+          <RadioButton name="theme" value="auto">
+            Auto (System Default)
+          </RadioButton>
+        </div>
+      </FormField>
+
+      <FormField
+        name="language"
+        label="Language"
+      >
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <RadioButton name="language" value="en">
+            English
+          </RadioButton>
+          <RadioButton name="language" value="es">
+            Spanish
+          </RadioButton>
+          <RadioButton name="language" value="fr">
+            French
+          </RadioButton>
+          <RadioButton name="language" value="de">
+            German
+          </RadioButton>
+        </div>
+      </FormField>
+
+      <FormField
+        name="notifications"
+        label="Notification Frequency"
+      >
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <RadioButton name="notifications" value="immediate">
+            Immediate
+          </RadioButton>
+          <RadioButton name="notifications" value="daily">
+            Daily Summary
+          </RadioButton>
+          <RadioButton name="notifications" value="weekly">
+            Weekly Summary
+          </RadioButton>
+          <RadioButton name="notifications" value="never">
+            Never
+          </RadioButton>
+        </div>
+      </FormField>
+
+      <Button type="submit">
+        Save Settings
+      </Button>
+    </Form>
+  );
+}
+```
+
+### Quiz Application
+
+```tsx
+import { Form, FormField, RadioButton, Button, Text } from '@delightui/components';
+
+function QuizExample() {
+  const [currentQuestion, setCurrentQuestion] = useState(0);
+  const [answers, setAnswers] = useState<Record<string, string>>({});
+
+  const questions = [
+    {
+      id: 'q1',
+      question: 'What is the capital of France?',
+      options: [
+        { value: 'london', label: 'London' },
+        { value: 'berlin', label: 'Berlin' },
+        { value: 'paris', label: 'Paris' },
+        { value: 'madrid', label: 'Madrid' }
+      ]
+    },
+    {
+      id: 'q2',
+      question: 'Which planet is closest to the Sun?',
+      options: [
+        { value: 'venus', label: 'Venus' },
+        { value: 'mercury', label: 'Mercury' },
+        { value: 'earth', label: 'Earth' },
+        { value: 'mars', label: 'Mars' }
+      ]
+    }
+  ];
+
+  const handleNext = () => {
+    if (currentQuestion < questions.length - 1) {
+      setCurrentQuestion(currentQuestion + 1);
+    }
+  };
+
+  const handleSubmit = () => {
+    console.log('Quiz answers:', answers);
+  };
+
+  const question = questions[currentQuestion];
+
+  return (
+    <div style={{ maxWidth: '500px', margin: '0 auto' }}>
+      <Text weight="bold" size="large" style={{ marginBottom: '16px' }}>
+        Question {currentQuestion + 1} of {questions.length}
+      </Text>
+      
+      <Text style={{ marginBottom: '20px' }}>
+        {question.question}
+      </Text>
+
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', marginBottom: '24px' }}>
+        {question.options.map((option) => (
+          <RadioButton
+            key={option.value}
+            name={question.id}
+            value={option.value}
+            checked={answers[question.id] === option.value}
+            onValueChange={(value) => setAnswers(prev => ({ ...prev, [question.id]: value as string }))}
+          >
+            {option.label}
+          </RadioButton>
+        ))}
+      </div>
+
+      <div style={{ display: 'flex', gap: '12px' }}>
+        {currentQuestion < questions.length - 1 ? (
+          <Button 
+            onClick={handleNext}
+            disabled={!answers[question.id]}
+          >
+            Next Question
+          </Button>
+        ) : (
+          <Button 
+            onClick={handleSubmit}
+            disabled={!answers[question.id]}
+          >
+            Submit Quiz
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Grouped Radio Buttons with Descriptions
+
+```tsx
+import { RadioButton, Text } from '@delightui/components';
+
+function GroupedRadioWithDescriptionExample() {
+  const [selectedPlan, setSelectedPlan] = useState('');
+
+  const plans = [
+    {
+      value: 'basic',
+      title: 'Basic Plan',
+      description: 'Perfect for individuals getting started',
+      price: '$9/month'
+    },
+    {
+      value: 'pro',
+      title: 'Pro Plan',
+      description: 'Best for growing businesses',
+      price: '$29/month'
+    },
+    {
+      value: 'enterprise',
+      title: 'Enterprise Plan',
+      description: 'Advanced features for large organizations',
+      price: '$99/month'
+    }
+  ];
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      {plans.map((plan) => (
+        <div
+          key={plan.value}
+          style={{
+            border: selectedPlan === plan.value ? '2px solid #007bff' : '1px solid #ccc',
+            borderRadius: '8px',
+            padding: '16px',
+            cursor: 'pointer'
+          }}
+          onClick={() => setSelectedPlan(plan.value)}
+        >
+          <RadioButton
+            name="subscriptionPlan"
+            value={plan.value}
+            checked={selectedPlan === plan.value}
+            onValueChange={setSelectedPlan}
+            labelAlignment="Right"
+          >
+            <div style={{ marginLeft: '8px' }}>
+              <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+                <Text weight="bold">{plan.title}</Text>
+                <Text weight="bold" color="primary">{plan.price}</Text>
+              </div>
+              <Text size="small" color="secondary">
+                {plan.description}
+              </Text>
+            </div>
+          </RadioButton>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Invalid State Example
+
+```tsx
+import { Form, FormField, RadioButton, Button, Text } from '@delightui/components';
+
+function InvalidRadioButtonExample() {
+  const [hasError, setHasError] = useState(false);
+  const [selectedValue, setSelectedValue] = useState('');
+
+  const handleSubmit = (data: any) => {
+    if (!data.priority) {
+      setHasError(true);
+      return;
+    }
+    setHasError(false);
+    console.log('Form submitted:', data);
+  };
+
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField
+        name="priority"
+        label="Task Priority"
+        required
+        invalid={hasError}
+        message={hasError ? "Please select a priority level" : undefined}
+      >
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          <RadioButton
+            name="priority"
+            value="low"
+            invalid={hasError}
+            checked={selectedValue === 'low'}
+            onValueChange={(value) => {
+              setSelectedValue(value as string);
+              if (hasError) setHasError(false);
+            }}
+          >
+            Low Priority
+          </RadioButton>
+          <RadioButton
+            name="priority"
+            value="medium"
+            invalid={hasError}
+            checked={selectedValue === 'medium'}
+            onValueChange={(value) => {
+              setSelectedValue(value as string);
+              if (hasError) setHasError(false);
+            }}
+          >
+            Medium Priority
+          </RadioButton>
+          <RadioButton
+            name="priority"
+            value="high"
+            invalid={hasError}
+            checked={selectedValue === 'high'}
+            onValueChange={(value) => {
+              setSelectedValue(value as string);
+              if (hasError) setHasError(false);
+            }}
+          >
+            High Priority
+          </RadioButton>
+        </div>
+      </FormField>
+
+      <Button type="submit">
+        Create Task
+      </Button>
+    </Form>
+  );
+}
+```