@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/button/README.md

@@ -0,0 +1,428 @@
+# Button Component
+
+A versatile button component with multiple variants, sizes, and types, supporting icons, custom styling, and comprehensive event handling.
+
+## Features
+
+- **Multiple Types**: Default, primary, secondary, third, and forth button styles
+- **Size Options**: Big, medium, and mini sizes
+- **Icon Support**: Optional icon display with flexible positioning
+- **Variant Styles**: Plain and round variants
+- **Event Handling**: Click, focus, and blur event support
+- **Accessibility**: Proper semantic button element with disabled state
+- **Debounce Protection**: Built-in click debouncing to prevent rapid firing
+- **Custom Styling**: Flexible style customization
+
+## Basic Usage
+
+```svelte
+<script>
+import Button from '@ticatec/uniface-element/Button';
+
+const handleClick = (event) => {
+  console.log('Button clicked!', event);
+};
+</script>
+
+<Button 
+  label="Click Me" 
+  onclick={handleClick} 
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `ButtonType` | `'default'` | Button type (default, primary, secondary, third, forth) |
+| `label` | `string` | `''` | Button text label |
+| `variant` | `'plain' \| 'round' \| ''` | `''` | Button variant style |
+| `disabled` | `boolean` | `false` | Whether the button is disabled |
+| `style` | `string` | `''` | Custom CSS styles |
+| `size` | `'big' \| 'medium' \| 'mini'` | `'medium'` | Button size |
+| `onclick` | `(event: MouseEvent) => void` | - | Click event handler |
+| `onfocus` | `(event: FocusEvent) => void` | `() => {}` | Focus event handler |
+| `onblur` | `(event: FocusEvent) => void` | `() => {}` | Blur event handler |
+| `icon` | `string \| null` | `null` | Icon class name |
+
+## Button Types
+
+```svelte
+<!-- Default button -->
+<Button label="Default" type="default" onclick={handleClick} />
+
+<!-- Primary button -->
+<Button label="Primary" type="primary" onclick={handleClick} />
+
+<!-- Secondary button -->
+<Button label="Secondary" type="secondary" onclick={handleClick} />
+
+<!-- Third level button -->
+<Button label="Third" type="third" onclick={handleClick} />
+
+<!-- Fourth level button -->
+<Button label="Fourth" type="forth" onclick={handleClick} />
+```
+
+## Button Sizes
+
+```svelte
+<!-- Mini button -->
+<Button label="Mini" size="mini" onclick={handleClick} />
+
+<!-- Medium button (default) -->
+<Button label="Medium" size="medium" onclick={handleClick} />
+
+<!-- Big button -->
+<Button label="Big" size="big" onclick={handleClick} />
+```
+
+## Button Variants
+
+```svelte
+<!-- Plain variant -->
+<Button label="Plain" variant="plain" onclick={handleClick} />
+
+<!-- Round variant -->
+<Button label="Round" variant="round" onclick={handleClick} />
+```
+
+## With Icons
+
+```svelte
+<!-- Button with icon -->
+<Button 
+  label="Save" 
+  icon="fas fa-save" 
+  onclick={handleSave} 
+/>
+
+<!-- Icon only (use empty label) -->
+<Button 
+  icon="fas fa-plus" 
+  onclick={handleAdd} 
+/>
+```
+
+## Event Handling
+
+```svelte
+<script>
+const handleClick = (event) => {
+  console.log('Button clicked:', event);
+};
+
+const handleFocus = (event) => {
+  console.log('Button focused:', event);
+  // Show tooltip or highlight
+};
+
+const handleBlur = (event) => {
+  console.log('Button blurred:', event);
+  // Hide tooltip or remove highlight
+};
+</script>
+
+<Button 
+  label="Interactive Button"
+  onclick={handleClick}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+/>
+```
+
+## Disabled State
+
+```svelte
+<Button 
+  label="Disabled Button" 
+  disabled={true}
+  onclick={handleClick} 
+/>
+```
+
+## Custom Styling
+
+```svelte
+<Button 
+  label="Custom Styled"
+  style="background: linear-gradient(45deg, #ff6b6b, #4ecdc4); color: white; border: none;"
+  onclick={handleClick}
+/>
+```
+
+## Advanced Examples
+
+### Form Submit Button
+
+```svelte
+<script>
+let isSubmitting = false;
+
+const handleSubmit = async (event) => {
+  isSubmitting = true;
+  try {
+    await submitForm();
+    console.log('Form submitted successfully');
+  } catch (error) {
+    console.error('Submit failed:', error);
+  } finally {
+    isSubmitting = false;
+  }
+};
+</script>
+
+<Button 
+  label={isSubmitting ? "Submitting..." : "Submit"}
+  type="primary"
+  disabled={isSubmitting}
+  icon={isSubmitting ? "fas fa-spinner fa-spin" : "fas fa-check"}
+  onclick={handleSubmit}
+/>
+```
+
+### Action Button with Confirmation
+
+```svelte
+<script>
+let showConfirm = false;
+
+const handleDelete = (event) => {
+  if (!showConfirm) {
+    showConfirm = true;
+    setTimeout(() => showConfirm = false, 3000);
+    return;
+  }
+  
+  // Proceed with deletion
+  deleteItem();
+  showConfirm = false;
+};
+</script>
+
+<Button 
+  label={showConfirm ? "Confirm Delete?" : "Delete"}
+  type={showConfirm ? "primary" : "secondary"}
+  icon="fas fa-trash"
+  onclick={handleDelete}
+  style={showConfirm ? "background-color: #dc3545;" : ""}
+/>
+```
+
+### Navigation Button
+
+```svelte
+<script>
+import { goto } from '$app/navigation';
+
+const navigateToPage = (event) => {
+  goto('/dashboard');
+};
+</script>
+
+<Button 
+  label="Go to Dashboard"
+  type="primary"
+  icon="fas fa-arrow-right"
+  onclick={navigateToPage}
+/>
+```
+
+### Button Group
+
+```svelte
+<div class="button-group">
+  <Button label="Save" type="primary" onclick={handleSave} />
+  <Button label="Cancel" type="secondary" onclick={handleCancel} />
+  <Button label="Reset" type="third" onclick={handleReset} />
+</div>
+
+<style>
+  .button-group {
+    display: flex;
+    gap: 8px;
+    align-items: center;
+  }
+</style>
+```
+
+### Loading Button
+
+```svelte
+<script>
+let loading = false;
+
+const handleAsyncAction = async (event) => {
+  loading = true;
+  try {
+    await performAsyncOperation();
+  } finally {
+    loading = false;
+  }
+};
+</script>
+
+<Button 
+  label={loading ? "Loading..." : "Start Process"}
+  disabled={loading}
+  icon={loading ? "fas fa-spinner fa-spin" : "fas fa-play"}
+  onclick={handleAsyncAction}
+/>
+```
+
+## Slot Usage
+
+```svelte
+<!-- Custom content instead of label -->
+<Button onclick={handleClick}>
+  <div class="custom-content">
+    <i class="fas fa-star"></i>
+    <span>Custom Content</span>
+    <span class="badge">NEW</span>
+  </div>
+</Button>
+```
+
+## Accessibility
+
+The Button component follows accessibility best practices:
+
+- Uses semantic `<button>` element
+- Supports keyboard navigation (Tab, Enter, Space)
+- Proper disabled state handling
+- Focus and blur events for screen readers
+- ARIA attributes when needed
+
+```svelte
+<!-- Accessible button with ARIA label -->
+<Button 
+  icon="fas fa-search"
+  onclick={handleSearch}
+  style="aria-label: Search products"
+/>
+```
+
+## Styling
+
+The component uses the following CSS classes:
+
+- `.uniface-button` - Base button class
+- `.common-button` - Common button styling
+- `.{variant}` - Variant-specific styles (plain, round)
+- `.{size}` - Size-specific styles (big, medium, mini)
+- `.{type}` - Type-specific styles (default, primary, etc.)
+- `.disabled` - Disabled state styles
+
+### Example CSS
+
+```css
+.uniface-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding: 8px 16px;
+  border: 1px solid #ddd;
+  background: #fff;
+  color: #333;
+  font-size: 14px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.uniface-button:hover:not(.disabled) {
+  background: #f5f5f5;
+}
+
+.uniface-button:focus {
+  outline: 2px solid #007acc;
+  outline-offset: 2px;
+}
+
+.uniface-button.disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.uniface-button.primary {
+  background: #007acc;
+  color: white;
+  border-color: #007acc;
+}
+
+.uniface-button.round {
+  border-radius: 20px;
+}
+
+.uniface-button.big {
+  padding: 12px 24px;
+  font-size: 16px;
+}
+
+.uniface-button.mini {
+  padding: 4px 8px;
+  font-size: 12px;
+}
+```
+
+## Best Practices
+
+1. **Consistent Styling**: Use the same button types consistently across your application
+2. **Clear Labels**: Provide descriptive labels that clearly indicate the action
+3. **Appropriate Types**: Use primary for main actions, secondary for supporting actions
+4. **Loading States**: Show loading indicators for async operations
+5. **Keyboard Navigation**: Ensure buttons are accessible via keyboard
+6. **Icon Usage**: Use icons to enhance understanding, not replace clear text
+7. **Debouncing**: The component includes built-in debouncing to prevent accidental double-clicks
+
+## Common Patterns
+
+### Modal Actions
+
+```svelte
+<div class="modal-actions">
+  <Button 
+    label="Cancel" 
+    type="secondary" 
+    onclick={closeModal} 
+  />
+  <Button 
+    label="Confirm" 
+    type="primary" 
+    onclick={confirmAction} 
+  />
+</div>
+```
+
+### Toolbar Actions
+
+```svelte
+<div class="toolbar">
+  <Button icon="fas fa-bold" variant="plain" onclick={toggleBold} />
+  <Button icon="fas fa-italic" variant="plain" onclick={toggleItalic} />
+  <Button icon="fas fa-underline" variant="plain" onclick={toggleUnderline} />
+</div>
+```
+
+### Form Actions
+
+```svelte
+<div class="form-actions">
+  <Button label="Reset" type="third" onclick={resetForm} />
+  <Button label="Save Draft" type="secondary" onclick={saveDraft} />
+  <Button label="Submit" type="primary" onclick={submitForm} />
+</div>
+```
+
+## Browser Support
+
+The Button component works in all modern browsers that support:
+- ES6+ JavaScript
+- CSS Flexbox
+- Semantic button elements
+
+## Performance
+
+- Built-in click debouncing prevents performance issues from rapid clicking
+- Lightweight implementation with minimal re-renders
+- Efficient event handling with proper cleanup