@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/button/IconButton_README.md

@@ -0,0 +1,513 @@
+# IconButton Component
+
+A specialized button component designed for icon-based actions, providing a clean and compact interface for toolbar actions, navigation controls, and interactive elements.
+
+## Features
+
+- **Icon-Focused Design**: Optimized for displaying icons as primary content
+- **Multiple Types**: Default, primary, secondary, third, and forth button styles
+- **Size Options**: Big, medium, and mini sizes
+- **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
+- **Slot Support**: Custom icon content via slots
+
+## Basic Usage
+
+```svelte
+<script>
+import IconButton from '@ticatec/uniface-element/IconButton';
+
+const handleClick = (event) => {
+  console.log('Icon button clicked!', event);
+};
+</script>
+
+<IconButton 
+  icon="fas fa-heart" 
+  onclick={handleClick} 
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'default' \| 'primary' \| 'secondary' \| 'third' \| 'forth'` | `'default'` | Button type/style |
+| `disabled` | `boolean` | `false` | Whether the button is disabled |
+| `size` | `'big' \| 'medium' \| 'mini'` | `'medium'` | Button size |
+| `style` | `string` | `''` | Custom CSS styles |
+| `icon` | `string` | `''` | Icon class name (e.g., FontAwesome classes) |
+| `onclick` | `(event: MouseEvent) => void` | - | Click event handler |
+| `onfocus` | `(event: FocusEvent) => void` | `() => {}` | Focus event handler |
+| `onblur` | `(event: FocusEvent) => void` | `() => {}` | Blur event handler |
+
+## Button Types
+
+```svelte
+<!-- Default icon button -->
+<IconButton icon="fas fa-star" type="default" onclick={handleClick} />
+
+<!-- Primary icon button -->
+<IconButton icon="fas fa-plus" type="primary" onclick={handleClick} />
+
+<!-- Secondary icon button -->
+<IconButton icon="fas fa-edit" type="secondary" onclick={handleClick} />
+
+<!-- Third level icon button -->
+<IconButton icon="fas fa-share" type="third" onclick={handleClick} />
+
+<!-- Fourth level icon button -->
+<IconButton icon="fas fa-info" type="forth" onclick={handleClick} />
+```
+
+## Button Sizes
+
+```svelte
+<!-- Mini icon button -->
+<IconButton icon="fas fa-search" size="mini" onclick={handleClick} />
+
+<!-- Medium icon button (default) -->
+<IconButton icon="fas fa-search" size="medium" onclick={handleClick} />
+
+<!-- Big icon button -->
+<IconButton icon="fas fa-search" size="big" onclick={handleClick} />
+```
+
+## Common Use Cases
+
+### Toolbar Actions
+
+```svelte
+<div class="toolbar">
+  <IconButton icon="fas fa-bold" onclick={toggleBold} />
+  <IconButton icon="fas fa-italic" onclick={toggleItalic} />
+  <IconButton icon="fas fa-underline" onclick={toggleUnderline} />
+  <IconButton icon="fas fa-link" onclick={insertLink} />
+</div>
+
+<style>
+  .toolbar {
+    display: flex;
+    gap: 4px;
+    padding: 8px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+  }
+</style>
+```
+
+### Navigation Controls
+
+```svelte
+<div class="navigation">
+  <IconButton icon="fas fa-chevron-left" onclick={goBack} />
+  <IconButton icon="fas fa-home" onclick={goHome} />
+  <IconButton icon="fas fa-chevron-right" onclick={goForward} />
+</div>
+```
+
+### Action Buttons
+
+```svelte
+<div class="actions">
+  <IconButton icon="fas fa-heart" type="primary" onclick={toggleFavorite} />
+  <IconButton icon="fas fa-share" type="secondary" onclick={shareItem} />
+  <IconButton icon="fas fa-bookmark" onclick={bookmarkItem} />
+  <IconButton icon="fas fa-trash" type="secondary" onclick={deleteItem} />
+</div>
+```
+
+## Event Handling
+
+```svelte
+<script>
+let isLiked = false;
+
+const handleLike = (event) => {
+  isLiked = !isLiked;
+  console.log('Like toggled:', isLiked);
+};
+
+const handleFocus = (event) => {
+  // Show tooltip or highlight
+  showTooltip = true;
+};
+
+const handleBlur = (event) => {
+  // Hide tooltip
+  showTooltip = false;
+};
+</script>
+
+<IconButton 
+  icon={isLiked ? "fas fa-heart" : "far fa-heart"}
+  type={isLiked ? "primary" : "default"}
+  onclick={handleLike}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+/>
+```
+
+## Disabled State
+
+```svelte
+<IconButton 
+  icon="fas fa-save" 
+  disabled={true}
+  onclick={handleSave} 
+/>
+```
+
+## Custom Styling
+
+```svelte
+<IconButton 
+  icon="fas fa-star"
+  style="
+    background: linear-gradient(45deg, #ffd700, #ffed4e);
+    color: #333;
+    border: 2px solid #ffd700;
+    border-radius: 50%;
+  "
+  onclick={handleClick}
+/>
+```
+
+## Slot Usage
+
+```svelte
+<!-- Custom icon content -->
+<IconButton onclick={handleCustomAction}>
+  <svg width="16" height="16" viewBox="0 0 24 24">
+    <path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>
+  </svg>
+</IconButton>
+
+<!-- Multiple icons or complex content -->
+<IconButton onclick={handleMultiAction}>
+  <div class="multi-icon">
+    <i class="fas fa-plus"></i>
+    <i class="fas fa-file"></i>
+  </div>
+</IconButton>
+```
+
+## Advanced Examples
+
+### Toggle Button
+
+```svelte
+<script>
+let isToggled = false;
+
+const handleToggle = (event) => {
+  isToggled = !isToggled;
+};
+</script>
+
+<IconButton 
+  icon={isToggled ? "fas fa-toggle-on" : "fas fa-toggle-off"}
+  type={isToggled ? "primary" : "default"}
+  onclick={handleToggle}
+/>
+```
+
+### Loading State
+
+```svelte
+<script>
+let isLoading = false;
+
+const handleRefresh = async (event) => {
+  isLoading = true;
+  try {
+    await refreshData();
+  } finally {
+    isLoading = false;
+  }
+};
+</script>
+
+<IconButton 
+  icon={isLoading ? "fas fa-spinner fa-spin" : "fas fa-sync"}
+  disabled={isLoading}
+  onclick={handleRefresh}
+/>
+```
+
+### Contextual Actions
+
+```svelte
+<script>
+let showMenu = false;
+
+const toggleMenu = (event) => {
+  showMenu = !showMenu;
+};
+</script>
+
+<div class="menu-container">
+  <IconButton 
+    icon="fas fa-ellipsis-v"
+    type={showMenu ? "primary" : "default"}
+    onclick={toggleMenu}
+  />
+  
+  {#if showMenu}
+    <div class="dropdown-menu">
+      <button on:click={editItem}>Edit</button>
+      <button on:click={duplicateItem}>Duplicate</button>
+      <button on:click={deleteItem}>Delete</button>
+    </div>
+  {/if}
+</div>
+```
+
+### Notification Button
+
+```svelte
+<script>
+let notificationCount = 3;
+
+const handleNotifications = (event) => {
+  // Open notifications panel
+  openNotificationsPanel();
+};
+</script>
+
+<div class="notification-button">
+  <IconButton 
+    icon="fas fa-bell"
+    type={notificationCount > 0 ? "primary" : "default"}
+    onclick={handleNotifications}
+  />
+  {#if notificationCount > 0}
+    <span class="notification-badge">{notificationCount}</span>
+  {/if}
+</div>
+
+<style>
+  .notification-button {
+    position: relative;
+    display: inline-block;
+  }
+  
+  .notification-badge {
+    position: absolute;
+    top: -8px;
+    right: -8px;
+    background: #ff4444;
+    color: white;
+    border-radius: 50%;
+    width: 20px;
+    height: 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 10px;
+    font-weight: bold;
+  }
+</style>
+```
+
+### Media Controls
+
+```svelte
+<script>
+let isPlaying = false;
+
+const togglePlay = (event) => {
+  isPlaying = !isPlaying;
+  if (isPlaying) {
+    startPlayback();
+  } else {
+    pausePlayback();
+  }
+};
+</script>
+
+<div class="media-controls">
+  <IconButton icon="fas fa-step-backward" onclick={previousTrack} />
+  <IconButton 
+    icon={isPlaying ? "fas fa-pause" : "fas fa-play"}
+    type="primary"
+    size="big"
+    onclick={togglePlay}
+  />
+  <IconButton icon="fas fa-step-forward" onclick={nextTrack} />
+</div>
+```
+
+## Accessibility
+
+The IconButton 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
+
+### Adding ARIA Labels
+
+```svelte
+<!-- For screen readers, add aria-label when using icons only -->
+<IconButton 
+  icon="fas fa-search"
+  onclick={handleSearch}
+  style="aria-label: Search"
+/>
+
+<!-- Or use title attribute for tooltips -->
+<IconButton 
+  icon="fas fa-print"
+  onclick={handlePrint}
+  style="title: Print document"
+/>
+```
+
+## Styling
+
+The component uses the following CSS classes:
+
+- `.uniface-button` - Base button class
+- `.icon-button` - Icon button specific styling
+- `.{size}` - Size-specific styles (big, medium, mini)
+- `.{type}` - Type-specific styles (default, primary, etc.)
+- `.disabled` - Disabled state styles
+
+### Example CSS
+
+```css
+.uniface-button.icon-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  padding: 6px;
+  border: 1px solid #ddd;
+  background: #fff;
+  color: #333;
+  border-radius: 4px;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.uniface-button.icon-button:hover:not(.disabled) {
+  background: #f5f5f5;
+}
+
+.uniface-button.icon-button:focus {
+  outline: 2px solid #007acc;
+  outline-offset: 2px;
+}
+
+.uniface-button.icon-button.big {
+  width: 48px;
+  height: 48px;
+  padding: 12px;
+}
+
+.uniface-button.icon-button.mini {
+  width: 24px;
+  height: 24px;
+  padding: 4px;
+}
+
+.uniface-button.icon-button.primary {
+  background: #007acc;
+  color: white;
+  border-color: #007acc;
+}
+
+.uniface-button.icon-button.disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+```
+
+## Best Practices
+
+1. **Consistent Icon Library**: Use a consistent icon library (e.g., FontAwesome) across your application
+2. **Appropriate Sizing**: Choose appropriate sizes based on context (toolbar = mini/medium, main actions = big)
+3. **Accessibility**: Always provide aria-label or title for screen readers
+4. **Visual Feedback**: Use different types to indicate state or importance
+5. **Grouping**: Group related icon buttons together
+6. **Tooltips**: Consider adding tooltips for better user experience
+7. **Context**: Ensure icons are easily recognizable and contextually appropriate
+
+## Common Patterns
+
+### Button Group
+
+```svelte
+<div class="icon-button-group">
+  <IconButton icon="fas fa-align-left" onclick={alignLeft} />
+  <IconButton icon="fas fa-align-center" onclick={alignCenter} />
+  <IconButton icon="fas fa-align-right" onclick={alignRight} />
+</div>
+
+<style>
+  .icon-button-group {
+    display: flex;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    overflow: hidden;
+  }
+  
+  .icon-button-group :global(.uniface-button) {
+    border-radius: 0;
+    border-left: none;
+  }
+  
+  .icon-button-group :global(.uniface-button:first-child) {
+    border-left: 1px solid #ddd;
+  }
+</style>
+```
+
+### Floating Action Button
+
+```svelte
+<IconButton 
+  icon="fas fa-plus"
+  type="primary"
+  size="big"
+  onclick={addNewItem}
+  style="
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    border-radius: 50%;
+    box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+  "
+/>
+```
+
+## Integration with Tooltips
+
+```svelte
+<script>
+import Tooltip from '@ticatec/uniface-element/Tooltip';
+</script>
+
+<Tooltip text="Save document">
+  <IconButton icon="fas fa-save" onclick={handleSave} />
+</Tooltip>
+```
+
+## Browser Support
+
+The IconButton component works in all modern browsers that support:
+- ES6+ JavaScript
+- CSS Flexbox
+- Semantic button elements
+
+## Performance
+
+- Lightweight icon-focused design
+- Built-in click debouncing
+- Efficient event handling
+- Minimal DOM footprint