@ticatec/uniface-element 0.2.4 → 0.3.0

package/dist/radio-button/README.md

@@ -0,0 +1,372 @@
+# 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