@ticatec/uniface-element 0.3.23 → 5.0.0

package/dist/group-box/group-check-box/README.md

@@ -1,749 +0,0 @@
-# GroupCheckBox
-
-A flexible group checkbox component that allows users to select multiple options from a predefined list. Supports string-based and bit-based value storage, custom styling variants, and comprehensive state management with focus/blur event handling.
-
-## Installation
-
-```bash
-npm install @ticatec/uniface-element
-```
-
-## Import
-
-```typescript
-import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
-import { DisplayMode } from "@ticatec/uniface-element";
-import type { OnChangeHandler } from "@ticatec/uniface-element";
-```
-
-## Basic Usage
-
-```svelte
-<script>
-  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
-  
-  const options = [
-    { code: "js", text: "JavaScript" },
-    { code: "ts", text: "TypeScript" },
-    { code: "py", text: "Python" },
-    { code: "go", text: "Go" }
-  ];
-  
-  let selectedLanguages = "";
-  
-  function handleChange(value) {
-    console.log('Selected languages:', value);
-  }
-</script>
-
-<GroupCheckBox 
-  {options} 
-  bind:value={selectedLanguages}
-  onchange={handleChange}
-/>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string \| number` | required | Selected values (string with delimiter or bit value) |
-| `options` | `Array<any>` | required | Array of option objects |
-| `keyField` | `string` | `"code"` | Field name for option keys/values |
-| `textField` | `string` | `"text"` | Field name for option display text |
-| `delimiter` | `string` | `";"` | Delimiter for string-based values |
-| `bitBase` | `boolean` | `false` | Whether to use bit-based value storage |
-| `disabled` | `boolean` | `false` | Whether the component is disabled |
-| `readonly` | `boolean` | `false` | Whether the component is read-only |
-| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Display mode (Edit or View) |
-| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Visual variant |
-| `compact` | `boolean` | `false` | Whether to use compact spacing |
-| `disabledOptions` | `Array<string>` | `[]` | Array of option keys to disable |
-| `hideOptions` | `Array<string>` | `[]` | Array of option keys to hide |
-| `style` | `string` | `""` | Additional CSS styles |
-| `item$style` | `string` | `""` | CSS styles for individual checkbox items |
-| `onchange` | `OnChangeHandler<string \| number>` | `null` | Change event handler |
-| `onfocus` | `(() => void) \| null` | `null` | Focus event handler |
-| `onblur` | `(() => void) \| null` | `null` | Blur event handler |
-
-## Methods
-
-| Method | Description |
-|--------|-------------|
-| `setFocus()` | Programmatically focus the first enabled checkbox |
-
-## Examples
-
-### Basic String-Based Selection
-
-```svelte
-<script>
-  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
-  import FormField from "@ticatec/uniface-element/FormField";
-  
-  const technologies = [
-    { code: "react", text: "React" },
-    { code: "vue", text: "Vue.js" },
-    { code: "svelte", text: "Svelte" },
-    { code: "angular", text: "Angular" }
-  ];
-  
-  let selectedTech = "";
-  
-  function handleTechChange(value) {
-    console.log('Selected technologies:', value);
-    console.log('As array:', value ? value.split(';') : []);
-  }
-</script>
-
-<div class="demo-section">
-  <FormField label="Select Your Preferred Technologies">
-    <GroupCheckBox 
-      options={technologies}
-      bind:value={selectedTech}
-      onchange={handleTechChange}
-      onfocus={() => console.log('Focus gained')}
-      onblur={() => console.log('Focus lost')}
-    />
-  </FormField>
-  
-  <p>Selected: {selectedTech || 'None'}</p>
-</div>
-
-<style>
-  .demo-section {
-    margin: 20px;
-    padding: 20px;
-    border: 1px solid #e2e8f0;
-    border-radius: 8px;
-  }
-</style>
-```
-
-### Bit-Based Selection for Performance
-
-```svelte
-<script>
-  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
-  import FormField from "@ticatec/uniface-element/FormField";
-  
-  const permissions = [
-    { code: "read", text: "Read" },      // Bit 0 (value 1)
-    { code: "write", text: "Write" },    // Bit 1 (value 2)
-    { code: "delete", text: "Delete" },  // Bit 2 (value 4)
-    { code: "admin", text: "Admin" }     // Bit 3 (value 8)
-  ];
-  
-  let userPermissions = 0;
-  
-  function handlePermissionChange(value) {
-    console.log('Permission bits:', value);
-    console.log('Binary representation:', value.toString(2));
-    
-    // Decode permissions
-    const activePermissions = [];
-    permissions.forEach((perm, index) => {
-      if (value & (1 << index)) {
-        activePermissions.push(perm.text);
-      }
-    });
-    console.log('Active permissions:', activePermissions);
-  }
-  
-  // Helper function to check if specific permission is enabled
-  function hasPermission(permissionBit) {
-    return (userPermissions & (1 << permissionBit)) !== 0;
-  }
-</script>
-
-<div class="permissions-demo">
-  <FormField label="User Permissions">
-    <GroupCheckBox 
-      options={permissions}
-      bitBase={true}
-      bind:value={userPermissions}
-      onchange={handlePermissionChange}
-    />
-  </FormField>
-  
-  <div class="permission-info">
-    <p>Permission Value: {userPermissions}</p>
-    <p>Binary: {userPermissions.toString(2).padStart(4, '0')}</p>
-    <div class="permission-checks">
-      <p>Can Read: {hasPermission(0) ? '✓' : '✗'}</p>
-      <p>Can Write: {hasPermission(1) ? '✓' : '✗'}</p>
-      <p>Can Delete: {hasPermission(2) ? '✓' : '✗'}</p>
-      <p>Is Admin: {hasPermission(3) ? '✓' : '✗'}</p>
-    </div>
-  </div>
-</div>
-
-<style>
-  .permissions-demo {
-    margin: 20px;
-    padding: 20px;
-    background: #f8fafc;
-    border-radius: 8px;
-  }
-  
-  .permission-info {
-    margin-top: 16px;
-    padding: 12px;
-    background: white;
-    border-radius: 6px;
-  }
-  
-  .permission-checks {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-    gap: 8px;
-    margin-top: 8px;
-  }
-</style>
-```
-
-### Different Visual Variants
-
-```svelte
-<script>
-  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
-  import FormField from "@ticatec/uniface-element/FormField";
-  
-  const colors = [
-    { code: "red", text: "Red" },
-    { code: "blue", text: "Blue" },
-    { code: "green", text: "Green" },
-    { code: "yellow", text: "Yellow" }
-  ];
-  
-  let selectedColors = "";
-</script>
-
-<div class="variants-demo">
-  <div class="variant-section">
-    <h3>Default Variant</h3>
-    <FormField label="Select Colors">
-      <GroupCheckBox options={colors} bind:value={selectedColors} />
-    </FormField>
-  </div>
-  
-  <div class="variant-section">
-    <h3>Outlined Variant</h3>
-    <FormField label="Select Colors">
-      <GroupCheckBox 
-        options={colors} 
-        variant="outlined"
-        bind:value={selectedColors} 
-      />
-    </FormField>
-  </div>
-  
-  <div class="variant-section">
-    <h3>Filled Variant</h3>
-    <FormField label="Select Colors">
-      <GroupCheckBox 
-        options={colors} 
-        variant="filled"
-        bind:value={selectedColors} 
-      />
-    </FormField>
-  </div>
-  
-  <div class="variant-section">
-    <h3>Compact Variant</h3>
-    <FormField label="Select Colors">
-      <GroupCheckBox 
-        options={colors} 
-        compact={true}
-        bind:value={selectedColors} 
-      />
-    </FormField>
-  </div>
-</div>
-
-<style>
-  .variants-demo {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-    gap: 20px;
-    margin: 20px;
-  }
-  
-  .variant-section {
-    padding: 16px;
-    border: 1px solid #e2e8f0;
-    border-radius: 8px;
-  }
-</style>
-```
-
-### Conditional Options and Dynamic Behavior
-
-```svelte
-<script>
-  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
-  import FormField from "@ticatec/uniface-element/FormField";
-  
-  const airlines = [
-    { code: "none", text: "None" },
-    { code: "aa", text: "American Airlines" },
-    { code: "ua", text: "United Airlines" },
-    { code: "dl", text: "Delta Airlines" },
-    { code: "sw", text: "Southwest Airlines" }
-  ];
-  
-  let selectedAirlines = "";
-  let disabledOptions = [];
-  let hideOptions = [];
-  
-  function handleAirlineChange(value) {
-    const selected = value ? value.split(';') : [];
-    
-    // If "None" is selected, disable all other options
-    if (selected.includes('none')) {
-      if (selected.length > 1) {
-        // If other options were selected with "None", keep only "None"
-        selectedAirlines = "none";
-      }
-      disabledOptions = airlines
-        .filter(airline => airline.code !== 'none')
-        .map(airline => airline.code);
-    } else {
-      disabledOptions = [];
-    }
-    
-    // Hide Southwest on weekends (demo logic)
-    const today = new Date();
-    if (today.getDay() === 0 || today.getDay() === 6) {
-      hideOptions = ['sw'];
-    } else {
-      hideOptions = [];
-    }
-  }
-  
-  // Handle special "None" selection logic
-  function handleSpecialLogic(value) {
-    const selected = value ? value.split(';') : [];
-    
-    if (selected.includes('none') && selected.length > 1) {
-      // Remove "none" if other options are selected
-      const filteredSelected = selected.filter(option => option !== 'none');
-      selectedAirlines = filteredSelected.join(';');
-    } else {
-      handleAirlineChange(value);
-    }
-  }
-</script>
-
-<div class="conditional-demo">
-  <FormField label="Select Preferred Airlines">
-    <GroupCheckBox 
-      options={airlines}
-      bind:value={selectedAirlines}
-      {disabledOptions}
-      {hideOptions}
-      onchange={handleSpecialLogic}
-    />
-  </FormField>
-  
-  <div class="info-panel">
-    <p><strong>Selected:</strong> {selectedAirlines || 'None'}</p>
-    <p><strong>Disabled:</strong> {disabledOptions.join(', ') || 'None'}</p>
-    <p><strong>Hidden:</strong> {hideOptions.join(', ') || 'None'}</p>
-    <p class="hint">💡 Select "None" to disable other options</p>
-    {#if hideOptions.includes('sw')}
-      <p class="weekend-notice">🚫 Southwest Airlines is not available on weekends</p>
-    {/if}
-  </div>
-</div>
-
-<style>
-  .conditional-demo {
-    margin: 20px;
-    padding: 20px;
-    border: 1px solid #e2e8f0;
-    border-radius: 8px;
-  }
-  
-  .info-panel {
-    margin-top: 16px;
-    padding: 12px;
-    background: #f8fafc;
-    border-radius: 6px;
-  }
-  
-  .hint {
-    color: #6b7280;
-    font-style: italic;
-  }
-  
-  .weekend-notice {
-    color: #dc2626;
-    font-weight: 500;
-  }
-</style>
-```
-
-### Read-Only and Display Modes
-
-```svelte
-<script>
-  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
-  import FormField from "@ticatec/uniface-element/FormField";
-  import { DisplayMode } from "@ticatec/uniface-element";
-  
-  const skills = [
-    { code: "js", text: "JavaScript" },
-    { code: "ts", text: "TypeScript" },
-    { code: "react", text: "React" },
-    { code: "node", text: "Node.js" }
-  ];
-  
-  let userSkills = "js;react;node";  // Pre-selected skills
-</script>
-
-<div class="readonly-demo">
-  <div class="mode-section">
-    <h3>Editable Mode</h3>
-    <FormField label="Edit Your Skills">
-      <GroupCheckBox 
-        options={skills}
-        bind:value={userSkills}
-      />
-    </FormField>
-  </div>
-  
-  <div class="mode-section">
-    <h3>Read-Only Mode</h3>
-    <FormField label="Your Skills (Read-Only)">
-      <GroupCheckBox 
-        options={skills}
-        value={userSkills}
-        readonly={true}
-      />
-    </FormField>
-  </div>
-  
-  <div class="mode-section">
-    <h3>Disabled Mode</h3>
-    <FormField label="Your Skills (Disabled)">
-      <GroupCheckBox 
-        options={skills}
-        value={userSkills}
-        disabled={true}
-      />
-    </FormField>
-  </div>
-  
-  <div class="mode-section">
-    <h3>Display-Only Mode</h3>
-    <FormField label="Your Skills (Display)">
-      <GroupCheckBox 
-        options={skills}
-        value={userSkills}
-        displayMode={DisplayMode.View}
-      />
-    </FormField>
-  </div>
-</div>
-
-<style>
-  .readonly-demo {
-    display: grid;
-    grid-template-columns: 1fr 1fr;
-    gap: 20px;
-    margin: 20px;
-  }
-  
-  .mode-section {
-    padding: 16px;
-    border: 1px solid #e2e8f0;
-    border-radius: 8px;
-  }
-</style>
-```
-
-### Custom Styling and Field Configuration
-
-```svelte
-<script>
-  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
-  import FormField from "@ticatec/uniface-element/FormField";
-  
-  const departments = [
-    { id: "eng", name: "Engineering", active: true },
-    { id: "sales", name: "Sales", active: true },
-    { id: "marketing", name: "Marketing", active: false },
-    { id: "hr", name: "Human Resources", active: true }
-  ];
-  
-  let selectedDepartments = "";
-</script>
-
-<div class="custom-demo">
-  <FormField label="Select Departments">
-    <GroupCheckBox 
-      options={departments}
-      keyField="id"
-      textField="name"
-      delimiter=","
-      bind:value={selectedDepartments}
-      variant="outlined"
-      style="border: 2px solid #3b82f6; border-radius: 12px; padding: 16px;"
-      item$style="margin: 8px 0; padding: 4px 8px; background: #f0f9ff; border-radius: 6px;"
-    />
-  </FormField>
-  
-  <div class="result">
-    <p><strong>Selected Departments:</strong></p>
-    <p>Raw value: {selectedDepartments}</p>
-    <p>As array: {JSON.stringify(selectedDepartments ? selectedDepartments.split(',') : [])}</p>
-  </div>
-</div>
-
-<style>
-  .custom-demo {
-    margin: 20px;
-    padding: 20px;
-    border: 1px solid #e2e8f0;
-    border-radius: 8px;
-  }
-  
-  .result {
-    margin-top: 16px;
-    padding: 12px;
-    background: #f8fafc;
-    border-radius: 6px;
-  }
-</style>
-```
-
-### Form Integration with Validation
-
-```svelte
-<script>
-  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
-  import FormField from "@ticatec/uniface-element/FormField";
-  
-  const interests = [
-    { code: "sports", text: "Sports" },
-    { code: "music", text: "Music" },
-    { code: "travel", text: "Travel" },
-    { code: "cooking", text: "Cooking" },
-    { code: "reading", text: "Reading" },
-    { code: "gaming", text: "Gaming" }
-  ];
-  
-  let formData = {
-    name: '',
-    interests: '',
-    newsletter: false
-  };
-  
-  let errors = {};
-  let groupCheckBoxRef;
-  
-  function validateForm() {
-    errors = {};
-    
-    if (!formData.name.trim()) {
-      errors.name = 'Name is required';
-    }
-    
-    if (!formData.interests) {
-      errors.interests = 'Please select at least one interest';
-    } else {
-      const selectedCount = formData.interests.split(';').length;
-      if (selectedCount > 3) {
-        errors.interests = 'Please select no more than 3 interests';
-      }
-    }
-    
-    return Object.keys(errors).length === 0;
-  }
-  
-  function handleSubmit() {
-    if (validateForm()) {
-      console.log('Form submitted:', formData);
-      alert('Form submitted successfully!');
-    } else {
-      console.log('Validation errors:', errors);
-      // Focus first error field
-      if (errors.interests) {
-        groupCheckBoxRef.setFocus();
-      }
-    }
-  }
-  
-  function handleInterestChange(value) {
-    formData.interests = value;
-    // Clear error when user makes a selection
-    if (errors.interests && value) {
-      delete errors.interests;
-      errors = { ...errors };
-    }
-  }
-</script>
-
-<div class="form-demo">
-  <form on:submit|preventDefault={handleSubmit}>
-    <FormField label="Your Name" error={errors.name}>
-      <input 
-        type="text" 
-        bind:value={formData.name}
-        class="form-input"
-        class:error={errors.name}
-      />
-    </FormField>
-    
-    <FormField label="Your Interests (Select 1-3)" error={errors.interests}>
-      <GroupCheckBox 
-        bind:this={groupCheckBoxRef}
-        options={interests}
-        bind:value={formData.interests}
-        onchange={handleInterestChange}
-        variant="outlined"
-      />
-      <p class="field-hint">Choose up to 3 interests that best describe you</p>
-    </FormField>
-    
-    <FormField label="Newsletter">
-      <label class="checkbox-label">
-        <input type="checkbox" bind:checked={formData.newsletter} />
-        Subscribe to our newsletter
-      </label>
-    </FormField>
-    
-    <div class="form-actions">
-      <button type="submit" class="submit-btn">Submit</button>
-      <button type="button" on:click={() => console.log(formData)} class="preview-btn">
-        Preview Data
-      </button>
-    </div>
-  </form>
-</div>
-
-<style>
-  .form-demo {
-    max-width: 500px;
-    margin: 20px;
-    padding: 24px;
-    border: 1px solid #e2e8f0;
-    border-radius: 8px;
-  }
-  
-  .form-input {
-    width: 100%;
-    padding: 8px 12px;
-    border: 1px solid #d1d5db;
-    border-radius: 6px;
-  }
-  
-  .form-input.error {
-    border-color: #dc2626;
-  }
-  
-  .field-hint {
-    margin-top: 4px;
-    font-size: 0.875rem;
-    color: #6b7280;
-  }
-  
-  .checkbox-label {
-    display: flex;
-    align-items: center;
-    gap: 8px;
-    cursor: pointer;
-  }
-  
-  .form-actions {
-    display: flex;
-    gap: 12px;
-    margin-top: 20px;
-  }
-  
-  .submit-btn, .preview-btn {
-    padding: 10px 20px;
-    border-radius: 6px;
-    border: none;
-    cursor: pointer;
-  }
-  
-  .submit-btn {
-    background: #3b82f6;
-    color: white;
-  }
-  
-  .preview-btn {
-    background: #f3f4f6;
-    color: #374151;
-    border: 1px solid #d1d5db;
-  }
-</style>
-```
-
-## Value Format
-
-### String-Based Values
-When `bitBase` is `false` (default), selected values are stored as a delimited string:
-- Single selection: `"option1"`
-- Multiple selections: `"option1;option2;option3"`
-- Empty selection: `""`
-
-### Bit-Based Values
-When `bitBase` is `true`, selected values are stored as a number where each bit represents an option:
-- First option (index 0): bit 0 (value 1)
-- Second option (index 1): bit 1 (value 2)
-- Third option (index 2): bit 2 (value 4)
-- Combined: first + third options = 1 + 4 = 5
-
-## Styling
-
-The GroupCheckBox component can be styled using CSS custom properties:
-
-```css
-.uniface-group-box {
-  --checkbox-spacing: 8px;
-  --checkbox-padding: 4px 8px;
-  --border-color: #e2e8f0;
-  --background-color: #ffffff;
-  --hover-background: #f9fafb;
-}
-
-/* Variant-specific styling */
-.uniface-group-box.outlined {
-  border: 1px solid var(--border-color);
-  border-radius: 6px;
-  padding: 12px;
-}
-
-.uniface-group-box.filled {
-  background-color: #f8fafc;
-  border-radius: 6px;
-  padding: 12px;
-}
-
-.uniface-group-box.compact {
-  --checkbox-spacing: 4px;
-  --checkbox-padding: 2px 4px;
-}
-```
-
-## Accessibility
-
-The GroupCheckBox component includes several accessibility features:
-
-- Keyboard navigation between checkboxes
-- Focus management with `setFocus()` method
-- ARIA labels and descriptions
-- Screen reader announcements for state changes
-- Proper tab order management
-
-## Best Practices
-
-1. **Option Management**: Keep option arrays stable to prevent unnecessary re-renders
-2. **Performance**: Use bit-based values for large datasets or when performance is critical
-3. **Validation**: Implement proper validation for required selections
-4. **User Experience**: Provide clear feedback for disabled/hidden options
-5. **Accessibility**: Always provide meaningful labels and descriptions
-6. **State Management**: Handle focus/blur events appropriately for form validation