# RadioButton

A radio button component for single selection from a group of options. Radio buttons allow users to select exactly one option from a predefined set of mutually exclusive choices.

## Installation

```bash
npm install @ticatec/uniface-element
```

## Import

```typescript
import RadioButton from "@ticatec/uniface-element/RadioButton";
```

## Basic Usage

```svelte
<script>
  import RadioButton from "@ticatec/uniface-element/RadioButton";
  
  let selectedSize = '';
</script>

<RadioButton bind:group={selectedSize} value="small" label="Small" />
<RadioButton bind:group={selectedSize} value="medium" label="Medium" />
<RadioButton bind:group={selectedSize} value="large" label="Large" />

<p>Selected: {selectedSize}</p>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `any` | Required | Value of this radio button option |
| `label` | `string` | Required | Display label for the radio button |
| `group` | `any` | Required | Bind to a variable that holds the selected value |
| `disabled` | `boolean` | `false` | Whether the radio button is disabled |
| `readonly` | `boolean` | `false` | Whether the radio button is read-only |
| `compact` | `boolean` | `false` | Whether to use compact spacing |
| `style` | `string` | `""` | Additional CSS styles |
| `onfocus` | `((event: FocusEvent) => void) \| null` | `null` | Callback when radio button gains focus |
| `onblur` | `((event: FocusEvent) => void) \| null` | `null` | Callback when radio button loses focus |
| `onchange` | `((event: Event) => void) \| null` | `null` | Callback when selection changes |

## Events

| Event | Description |
|-------|-------------|
| `focus` | Fired when the radio button gains focus |
| `blur` | Fired when the radio button loses focus |
| `change` | Fired when the selection changes |
| `click` | Fired when the radio button is clicked |

## Methods

| Method | Description |
|--------|-------------|
| `setFocus()` | Programmatically focus the radio button |

## Examples

### Basic Radio Group

```svelte
<script>
  import RadioButton from "@ticatec/uniface-element/RadioButton";
  
  let selectedOption = 'option1';
</script>

<h3>Choose an option:</h3>
<RadioButton bind:group={selectedOption} value="option1" label="Option 1" />
<RadioButton bind:group={selectedOption} value="option2" label="Option 2" />
<RadioButton bind:group={selectedOption} value="option3" label="Option 3" />

<p>You selected: {selectedOption}</p>
```

### With Event Handlers

```svelte
<script>
  import RadioButton from "@ticatec/uniface-element/RadioButton";
  
  let selectedColor = '';
  
  function handleChange(event) {
    console.log('Color changed:', event.target.value);
  }
  
  function handleFocus(event) {
    console.log('Radio button focused');
  }
  
  function handleBlur(event) {
    console.log('Radio button blurred');
  }
</script>

<h3>Select a color:</h3>
<RadioButton 
  bind:group={selectedColor} 
  value="red" 
  label="Red" 
  onchange={handleChange}
  onfocus={handleFocus}
  onblur={handleBlur}
/>
<RadioButton 
  bind:group={selectedColor} 
  value="green" 
  label="Green" 
  onchange={handleChange}
  onfocus={handleFocus}
  onblur={handleBlur}
/>
<RadioButton 
  bind:group={selectedColor} 
  value="blue" 
  label="Blue" 
  onchange={handleChange}
  onfocus={handleFocus}
  onblur={handleBlur}
/>
```

### Disabled and Readonly States

```svelte
<script>
  import RadioButton from "@ticatec/uniface-element/RadioButton";
  
  let selectedPlan = 'basic';
</script>

<h3>Subscription Plan:</h3>
<RadioButton bind:group={selectedPlan} value="free" label="Free (Limited)" disabled />
<RadioButton bind:group={selectedPlan} value="basic" label="Basic" />
<RadioButton bind:group={selectedPlan} value="premium" label="Premium" />
<RadioButton bind:group={selectedPlan} value="enterprise" label="Enterprise" readonly />
```

### Compact Style

```svelte
<script>
  import RadioButton from "@ticatec/uniface-element/RadioButton";
  
  let selectedTheme = 'light';
</script>

<div style="display: flex; gap: 16px;">
  <RadioButton bind:group={selectedTheme} value="light" label="Light" compact />
  <RadioButton bind:group={selectedTheme} value="dark" label="Dark" compact />
  <RadioButton bind:group={selectedTheme} value="auto" label="Auto" compact />
</div>
```

### Form Integration

```svelte
<script>
  import RadioButton from "@ticatec/uniface-element/RadioButton";
  import Button from "@ticatec/uniface-element/Button";
  
  let formData = {
    priority: '',
    category: '',
    urgency: ''
  };
  
  function handleSubmit() {
    console.log('Form submitted:', formData);
  }
</script>

<form on:submit|preventDefault={handleSubmit}>
  <fieldset>
    <legend>Priority Level</legend>
    <RadioButton bind:group={formData.priority} value="low" label="Low Priority" />
    <RadioButton bind:group={formData.priority} value="medium" label="Medium Priority" />
    <RadioButton bind:group={formData.priority} value="high" label="High Priority" />
  </fieldset>
  
  <fieldset>
    <legend>Category</legend>
    <RadioButton bind:group={formData.category} value="bug" label="Bug Report" />
    <RadioButton bind:group={formData.category} value="feature" label="Feature Request" />
    <RadioButton bind:group={formData.category} value="support" label="Support Question" />
  </fieldset>
  
  <fieldset>
    <legend>Urgency</legend>
    <RadioButton bind:group={formData.urgency} value="immediate" label="Immediate" />
    <RadioButton bind:group={formData.urgency} value="soon" label="This Week" />
    <RadioButton bind:group={formData.urgency} value="later" label="Whenever" />
  </fieldset>
  
  <Button type="primary" label="Submit" onClick={handleSubmit} />
</form>

<style>
  fieldset {
    border: 1px solid #ddd;
    border-radius: 4px;
    padding: 16px;
    margin-bottom: 16px;
  }
  
  legend {
    font-weight: bold;
    padding: 0 8px;
  }
</style>
```

### Dynamic Options

```svelte
<script>
  import RadioButton from "@ticatec/uniface-element/RadioButton";
  
  let selectedLanguage = '';
  let languages = [
    { value: 'js', label: 'JavaScript' },
    { value: 'ts', label: 'TypeScript' },
    { value: 'py', label: 'Python' },
    { value: 'java', label: 'Java' },
    { value: 'go', label: 'Go' }
  ];
</script>

<h3>Preferred Programming Language:</h3>
{#each languages as lang}
  <RadioButton 
    bind:group={selectedLanguage} 
    value={lang.value} 
    label={lang.label} 
  />
{/each}

{#if selectedLanguage}
  <p>You chose: {languages.find(l => l.value === selectedLanguage)?.label}</p>
{/if}
```

### With Custom Styling

```svelte
<script>
  import RadioButton from "@ticatec/uniface-element/RadioButton";
  
  let selectedSize = 'medium';
</script>

<div class="size-selector">
  <RadioButton 
    bind:group={selectedSize} 
    value="small" 
    label="Small (S)" 
    style="margin-right: 24px;"
  />
  <RadioButton 
    bind:group={selectedSize} 
    value="medium" 
    label="Medium (M)" 
    style="margin-right: 24px;"
  />
  <RadioButton 
    bind:group={selectedSize} 
    value="large" 
    label="Large (L)" 
  />
</div>

<style>
  .size-selector {
    padding: 16px;
    background: #f8f9fa;
    border-radius: 8px;
    display: flex;
    align-items: center;
  }
</style>
```

### Programmatic Focus

```svelte
<script>
  import RadioButton from "@ticatec/uniface-element/RadioButton";
  import Button from "@ticatec/uniface-element/Button";
  
  let selectedAnswer = '';
  let firstRadio, secondRadio, thirdRadio;
  
  function focusFirst() {
    firstRadio.setFocus();
  }
  
  function focusSecond() {
    secondRadio.setFocus();
  }
  
  function focusThird() {
    thirdRadio.setFocus();
  }
</script>

<h3>Survey Question:</h3>
<RadioButton bind:this={firstRadio} bind:group={selectedAnswer} value="yes" label="Yes" />
<RadioButton bind:this={secondRadio} bind:group={selectedAnswer} value="no" label="No" />
<RadioButton bind:this={thirdRadio} bind:group={selectedAnswer} value="maybe" label="Maybe" />

<div style="margin-top: 16px;">
  <Button label="Focus Yes" onClick={focusFirst} />
  <Button label="Focus No" onClick={focusSecond} />
  <Button label="Focus Maybe" onClick={focusThird} />
</div>
```

## Features

- **Single Selection**: Ensures only one option can be selected in a group
- **Keyboard Navigation**: Full keyboard accessibility with tab and arrow key support
- **Focus Management**: Programmatic focus control and event handling
- **State Management**: Disabled and readonly states
- **Custom Styling**: Flexible styling options and compact mode
- **Event Handling**: Comprehensive event support for user interactions

## Behavior

1. **Selection**: Clicking a radio button selects it and deselects all others in the group
2. **Keyboard**: Arrow keys navigate between options, Space selects the focused option
3. **Focus**: Tab key moves focus between radio button groups
4. **Label**: Clicking the label selects the associated radio button
5. **Disabled**: Disabled radio buttons cannot be selected or focused
6. **Readonly**: Readonly radio buttons cannot be changed but can be focused

## Accessibility

- Proper ARIA attributes and roles
- Keyboard navigation support
- Screen reader compatible labels
- Focus indicators and management
- Semantic HTML structure with proper labeling

## Best Practices

1. **Group Related Options**: Use radio buttons for mutually exclusive choices
2. **Clear Labels**: Provide descriptive, concise labels for each option
3. **Default Selection**: Consider providing a sensible default selection
4. **Option Count**: Limit to 2-7 options for optimal usability
5. **Logical Order**: Arrange options in a logical sequence
6. **Visual Grouping**: Use fieldsets and legends to group related radio buttons

## Browser Support

- Modern browsers with full form control support
- Compatible with Svelte 5+
- Responsive design principles
- Touch-friendly interface

## Related Components

- `CheckBox` - For multiple selections
- `Switch` - For binary on/off states
- `OptionsSelect` - For dropdown single selection
- `Button` - For action-based selections