@ticatec/topside-elements 1.0.0

package/dist/general/button/IconButton_README.md

@@ -0,0 +1,522 @@
+# 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 small sizes
+- **Tooltip Support**: Built-in tooltip via `data-tip` attribute with markdown support
+- **Keyboard Navigation**: Defaults to `tabindex={-1}` to avoid Tab stops during keyboard navigation; supports explicit `tabindex` override
+- **Event Handling**: Click event support
+- **Accessibility**: Proper semantic button element with disabled state
+- **Custom Styling**: Flexible style customization
+- **Snippet Support**: Custom icon content via children prop
+
+## Basic Usage
+
+```svelte
+<script>
+import IconButton from '@ticatec/topside-elements/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' \| 'small'` | `'medium'` | Button size |
+| `style` | `string` | `''` | Custom CSS styles |
+| `icon` | `string` | `''` | Icon class name (e.g., FontAwesome classes) |
+| `theme` | `string` | - | Theme variant |
+| `tooltip` | `string` | - | Tooltip text (supports markdown, use `\n` for line breaks) |
+| `onclick` | `(event: MouseEvent) => void` | - | Click event handler |
+| `children` | `Snippet` | - | Custom icon content snippet |
+| `tabindex` | `number` | `-1` | Tab index (defaults to -1 so button does not take Tab focus) |
+| `outer` | `boolean` | `true` | Whether to show outer frame/ring when focused or active (defaults to true; set to false to remove focus/active outer frame) |
+
+## 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} />
+```
+
+## Tooltip Support
+
+The IconButton component includes built-in tooltip support via the `tooltip` prop. Tooltips are shown automatically when hovering over the button.
+
+```svelte
+<!-- Icon button with tooltip -->
+<IconButton icon="fas fa-save" tooltip="Save document" type="primary" onclick={handleSave} />
+<IconButton icon="fas fa-download" tooltip="Download file" onclick={handleDownload} />
+<IconButton icon="fas fa-trash" tooltip="Delete item" type="secondary" onclick={handleDelete} />
+
+<!-- Multi-line tooltip with markdown -->
+<IconButton 
+  icon="fas fa-warning"
+  type="secondary"
+  tooltip="> **Warning**:\n> This action cannot be undone"
+  onclick={handleDangerousAction}
+/>
+
+<!-- Tooltip is not shown for disabled buttons -->
+<IconButton icon="fas fa-print" tooltip="Print document" disabled={true} />
+```
+
+**Note**: The `Tooltip` component must be mounted in your app for tooltips to work:
+
+```svelte
+<script>
+  import Tooltip from '@ticatec/topside-elements/Tooltip';
+</script>
+
+<Tooltip />
+<!-- Your app content -->
+```
+
+## Button Sizes
+
+```svelte
+<!-- Small icon button -->
+<IconButton icon="fas fa-search" size="small" 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}
+/>
+```
+
+## Snippet Support
+
+Use the `children` prop to provide custom icon content:
+
+```svelte
+<!-- Custom icon content -->
+<IconButton onclick={handleCustomAction}>
+  {#snippet children()}
+    <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>
+  {/snippet}
+</IconButton>
+
+<!-- Multiple icons or complex content -->
+<IconButton onclick={handleMultiAction}>
+  {#snippet children()}
+    <div class="multi-icon">
+      <i class="fas fa-plus"></i>
+      <i class="fas fa-file"></i>
+    </div>
+  {/snippet}
+</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
+- By default sets `tabindex={-1}` so it does not take Tab keyboard focus, preventing unnecessary tab stops in toolbars and tables
+- Supports explicit `tabindex` override (e.g. `tabindex={0}`) when Tab focus is desired
+- Proper disabled state handling (always not focusable when disabled)
+- Visible focus indicator when focused
+
+### Keyboard Navigation
+
+- **Tab** - Bypassed by default (`tabindex={-1}`); when overridden to `0`, moves focus to/from button
+- **Enter / Space** - Activate button when focused
+- **Focus visible** - Shows an external border ring (4px) with a 3px transparent gap when focused. The ring color matches the button's background color (primary=blue, secondary=red, etc.)
+
+### Adding ARIA Labels
+
+```svelte
+<!-- For screen readers, add aria-label when using icons only -->
+<IconButton
+  icon="fas fa-search"
+  tooltip="Search products"
+  onclick={handleSearch}
+  aria-label="Search"
+/>
+
+<!-- Or use tooltip which also provides context -->
+<IconButton
+  icon="fas fa-print"
+  tooltip="Print document"
+  onclick={handlePrint}
+/>
+```
+
+## Styling
+
+The component uses the following CSS classes:
+
+- `.topside-button` - Base button class
+- `.icon-button` - Icon button specific styling
+- `.{size}` - Size-specific styles (big, medium, small)
+- `.{type}` - Type-specific styles (default, primary, etc.)
+- `.disabled` - Disabled state styles
+
+### CSS Variables
+
+```css
+:root {
+  /* Icon button colors */
+  --icon-btn-bg: #ffffff;
+  --icon-btn-text: #374151;
+  --icon-btn-hover-bg: #f5f5f5;
+  --icon-btn-disabled-bg: #F1F5F9;
+  --icon-btn-disabled-text: #B3BCCA;
+}
+```
+
+### Embedded CSS
+
+The component uses embedded CSS (no external SCSS imports required).
+
+### Focus States
+
+Keyboard focus is handled using `:focus-visible` pseudo-class for keyboard-only focus indication. When focused via keyboard (Tab), the button shows the same background color as hover state.
+
+## 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 = small/medium, main actions = big)
+3. **Accessibility**: Always provide tooltip or aria-label for screen readers
+4. **Visual Feedback**: Use different types to indicate state or importance
+5. **Grouping**: Group related icon buttons together
+6. **Tooltips**: Add tooltips to icon-only buttons for better UX
+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(.topside-button) {
+    border-radius: 0;
+    border-left: none;
+  }
+  
+  .icon-button-group :global(.topside-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);
+  "
+/>
+```
+
+## 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