@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/popup-hint/README.md

@@ -1,841 +0,0 @@
-# PopupHint
-
-A global tooltip system that provides contextual hints and information when users hover over elements, with automatic positioning and timing controls.
-
-## Features
-
-- **Global Access**: Available throughout the application via `window.Hint`
-- **Mouse Tracking**: Automatically positions hints near mouse cursor
-- **Delayed Display**: 500ms delay before showing to prevent flickering
-- **Auto Hide**: Automatically hides when mouse leaves the element
-- **Portal Rendering**: Renders hints in document body for proper z-index layering
-- **Responsive Positioning**: Automatically adjusts position to stay within viewport
-- **Event Management**: Proper cleanup of event listeners
-- **Lightweight**: Minimal performance impact with efficient event handling
-
-## Installation
-
-```bash
-npm install @ticatec/uniface-element
-```
-
-## Setup
-
-First, add the PopupHint component to your root layout or app component:
-
-```svelte
-<script>
-  import PopupHint from '@ticatec/uniface-element/PopupHint';
-</script>
-
-<!-- Your app content -->
-<main>
-  <!-- Your components -->
-</main>
-
-<!-- PopupHint - Global instance -->
-<PopupHint />
-```
-
-## Basic Usage
-
-Once the PopupHint is mounted, you can show hints from anywhere in your application:
-
-```javascript
-// Show a hint when hovering over an element
-function handleMouseEnter(event) {
-  window.Hint.show(
-    event.target,           // Target element
-    'This is a helpful hint!', // Hint text
-    event.clientX,          // Mouse X position
-    event.clientY           // Mouse Y position
-  );
-}
-```
-
-## API Reference
-
-### Global Methods
-
-#### `window.Hint.show(element, text, x, y)`
-
-Shows a hint tooltip near the specified coordinates.
-
-**Parameters:**
-- `element` (Element): The target element that triggered the hint
-- `text` (string): The hint text to display
-- `x` (number): Mouse X coordinate
-- `y` (number): Mouse Y coordinate
-
-**Behavior:**
-- Adds automatic `mouseleave` event listener to hide hint
-- 500ms delay before showing to prevent accidental triggers
-- Automatically positions hint near cursor with offset
-
-### Types
-
-```typescript
-export type ShowHint = (element: Element, text: string, x: number, y: number) => void;
-
-export default interface IHint {
-  show: ShowHint;
-}
-```
-
-## Examples
-
-### Basic Button Hints
-
-```svelte
-<script>
-  function showHint(text) {
-    return function(event) {
-      window.Hint.show(event.target, text, event.clientX, event.clientY);
-    };
-  }
-</script>
-
-<div class="button-group">
-  <button on:mouseenter={showHint('Save your current work')}>
-    Save
-  </button>
-  
-  <button on:mouseenter={showHint('Cancel all changes')}>
-    Cancel
-  </button>
-  
-  <button on:mouseenter={showHint('Export data to Excel format')}>
-    Export
-  </button>
-</div>
-```
-
-### Icon Tooltips
-
-```svelte
-<script>
-  import Icon from '@ticatec/uniface-element/Icon';
-  
-  const iconHints = {
-    edit: 'Edit this item',
-    delete: 'Delete this item (cannot be undone)',
-    share: 'Share with others',
-    bookmark: 'Add to bookmarks',
-    download: 'Download file'
-  };
-  
-  function handleIconHover(iconType) {
-    return function(event) {
-      const hint = iconHints[iconType];
-      if (hint) {
-        window.Hint.show(event.target, hint, event.clientX, event.clientY);
-      }
-    };
-  }
-</script>
-
-<div class="toolbar">
-  <Icon 
-    name="icon_google_edit" 
-    on:mouseenter={handleIconHover('edit')}
-  />
-  <Icon 
-    name="icon_google_delete" 
-    on:mouseenter={handleIconHover('delete')}
-  />
-  <Icon 
-    name="icon_google_share" 
-    on:mouseenter={handleIconHover('share')}
-  />
-  <Icon 
-    name="icon_google_bookmark" 
-    on:mouseenter={handleIconHover('bookmark')}
-  />
-  <Icon 
-    name="icon_google_download" 
-    on:mouseenter={handleIconHover('download')}
-  />
-</div>
-
-<style>
-  .toolbar {
-    display: flex;
-    gap: 8px;
-    padding: 12px;
-  }
-</style>
-```
-
-### Form Field Hints
-
-```svelte
-<script>
-  import FormField from '@ticatec/uniface-element/FormField';
-  import TextEditor from '@ticatec/uniface-element/TextEditor';
-  
-  let formData = {
-    username: '',
-    email: '',
-    password: ''
-  };
-  
-  const fieldHints = {
-    username: 'Username must be 3-20 characters, letters and numbers only',
-    email: 'We\'ll use this email for account recovery and notifications',
-    password: 'Password must be at least 8 characters with uppercase, lowercase, and numbers'
-  };
-  
-  function showFieldHint(fieldName) {
-    return function(event) {
-      window.Hint.show(event.target, fieldHints[fieldName], event.clientX, event.clientY);
-    };
-  }
-</script>
-
-<form class="registration-form">
-  <FormField label="Username">
-    <TextEditor 
-      variant="outlined"
-      bind:value={formData.username}
-      placeholder="Enter username"
-      on:mouseenter={showFieldHint('username')}
-    />
-  </FormField>
-  
-  <FormField label="Email">
-    <TextEditor 
-      variant="outlined"
-      bind:value={formData.email}
-      placeholder="Enter email address"
-      on:mouseenter={showFieldHint('email')}
-    />
-  </FormField>
-  
-  <FormField label="Password">
-    <TextEditor 
-      variant="outlined"
-      type="password"
-      bind:value={formData.password}
-      placeholder="Enter password"
-      on:mouseenter={showFieldHint('password')}
-    />
-  </FormField>
-</form>
-```
-
-### Data Table Row Hints
-
-```svelte
-<script>
-  let users = [
-    { 
-      id: 1, 
-      name: 'John Doe', 
-      email: 'john@example.com', 
-      status: 'active',
-      lastLogin: '2024-01-15 14:30:00',
-      role: 'Administrator'
-    },
-    { 
-      id: 2, 
-      name: 'Jane Smith', 
-      email: 'jane@example.com', 
-      status: 'inactive',
-      lastLogin: '2024-01-10 09:15:00',
-      role: 'User'
-    }
-  ];
-  
-  function showUserHint(user) {
-    return function(event) {
-      const hint = `
-        Last Login: ${user.lastLogin}
-        Role: ${user.role}
-        Status: ${user.status.toUpperCase()}
-        ID: ${user.id}
-      `;
-      window.Hint.show(event.target, hint, event.clientX, event.clientY);
-    };
-  }
-  
-  function showStatusHint(status) {
-    return function(event) {
-      const hints = {
-        active: 'User is currently active and can access the system',
-        inactive: 'User account has been deactivated',
-        pending: 'User registration is pending approval',
-        suspended: 'User account has been temporarily suspended'
-      };
-      
-      window.Hint.show(event.target, hints[status] || 'Unknown status', event.clientX, event.clientY);
-    };
-  }
-</script>
-
-<table class="user-table">
-  <thead>
-    <tr>
-      <th>Name</th>
-      <th>Email</th>
-      <th>Status</th>
-    </tr>
-  </thead>
-  <tbody>
-    {#each users as user}
-      <tr on:mouseenter={showUserHint(user)}>
-        <td>{user.name}</td>
-        <td>{user.email}</td>
-        <td>
-          <span 
-            class="status status-{user.status}"
-            on:mouseenter={showStatusHint(user.status)}
-          >
-            {user.status}
-          </span>
-        </td>
-      </tr>
-    {/each}
-  </tbody>
-</table>
-
-<style>
-  .user-table {
-    width: 100%;
-    border-collapse: collapse;
-  }
-  
-  .user-table th,
-  .user-table td {
-    padding: 12px;
-    text-align: left;
-    border-bottom: 1px solid #ddd;
-  }
-  
-  .user-table tr:hover {
-    background-color: #f5f5f5;
-  }
-  
-  .status {
-    padding: 4px 8px;
-    border-radius: 12px;
-    font-size: 12px;
-    font-weight: 600;
-    text-transform: uppercase;
-  }
-  
-  .status-active {
-    background: #d4edda;
-    color: #155724;
-  }
-  
-  .status-inactive {
-    background: #f8d7da;
-    color: #721c24;
-  }
-</style>
-```
-
-### Chart and Graph Hints
-
-```svelte
-<script>
-  let chartData = [
-    { month: 'Jan', sales: 12000, growth: '+15%' },
-    { month: 'Feb', sales: 13500, growth: '+12.5%' },
-    { month: 'Mar', sales: 11200, growth: '-17%' },
-    { month: 'Apr', sales: 14800, growth: '+32%' },
-    { month: 'May', sales: 16200, growth: '+9.5%' }
-  ];
-  
-  function showChartHint(dataPoint) {
-    return function(event) {
-      const hint = `
-        Month: ${dataPoint.month}
-        Sales: $${dataPoint.sales.toLocaleString()}
-        Growth: ${dataPoint.growth}
-      `;
-      window.Hint.show(event.target, hint, event.clientX, event.clientY);
-    };
-  }
-</script>
-
-<div class="chart-container">
-  <h3>Sales Chart</h3>
-  <div class="chart">
-    {#each chartData as data, i}
-      <div 
-        class="chart-bar"
-        style="height: {(data.sales / 20000) * 200}px;"
-        on:mouseenter={showChartHint(data)}
-      >
-        <div class="bar-label">{data.month}</div>
-      </div>
-    {/each}
-  </div>
-</div>
-
-<style>
-  .chart-container {
-    padding: 20px;
-  }
-  
-  .chart {
-    display: flex;
-    align-items: flex-end;
-    gap: 12px;
-    height: 250px;
-    border-bottom: 2px solid #333;
-    padding: 20px 0;
-  }
-  
-  .chart-bar {
-    background: linear-gradient(to top, #007bff, #66b3ff);
-    width: 60px;
-    border-radius: 4px 4px 0 0;
-    cursor: pointer;
-    transition: transform 0.2s;
-    position: relative;
-  }
-  
-  .chart-bar:hover {
-    transform: scale(1.05);
-  }
-  
-  .bar-label {
-    position: absolute;
-    bottom: -25px;
-    left: 50%;
-    transform: translateX(-50%);
-    font-size: 12px;
-    font-weight: 600;
-  }
-</style>
-```
-
-### Image Gallery with Metadata
-
-```svelte
-<script>
-  let images = [
-    {
-      id: 1,
-      src: 'https://picsum.photos/300/200?random=1',
-      title: 'Sunset Landscape',
-      description: 'Beautiful sunset over mountains',
-      camera: 'Canon EOS R5',
-      settings: 'f/8, 1/250s, ISO 100',
-      location: 'Rocky Mountains, Colorado'
-    },
-    {
-      id: 2,
-      src: 'https://picsum.photos/300/200?random=2',
-      title: 'Urban Architecture',
-      description: 'Modern building design',
-      camera: 'Sony A7R IV',
-      settings: 'f/11, 1/125s, ISO 200',
-      location: 'Downtown Seattle'
-    }
-  ];
-  
-  function showImageHint(image) {
-    return function(event) {
-      const hint = `
-        ${image.title}
-        
-        ${image.description}
-        
-        Camera: ${image.camera}
-        Settings: ${image.settings}
-        Location: ${image.location}
-      `;
-      window.Hint.show(event.target, hint, event.clientX, event.clientY);
-    };
-  }
-</script>
-
-<div class="gallery">
-  {#each images as image}
-    <div 
-      class="image-card"
-      on:mouseenter={showImageHint(image)}
-    >
-      <img src={image.src} alt={image.title} />
-      <div class="image-overlay">
-        <h4>{image.title}</h4>
-      </div>
-    </div>
-  {/each}
-</div>
-
-<style>
-  .gallery {
-    display: grid;
-    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
-    gap: 20px;
-    padding: 20px;
-  }
-  
-  .image-card {
-    position: relative;
-    border-radius: 8px;
-    overflow: hidden;
-    cursor: pointer;
-    transition: transform 0.2s;
-  }
-  
-  .image-card:hover {
-    transform: translateY(-4px);
-  }
-  
-  .image-card img {
-    width: 100%;
-    height: 200px;
-    object-fit: cover;
-  }
-  
-  .image-overlay {
-    position: absolute;
-    bottom: 0;
-    left: 0;
-    right: 0;
-    background: linear-gradient(transparent, rgba(0,0,0,0.7));
-    color: white;
-    padding: 20px;
-  }
-  
-  .image-overlay h4 {
-    margin: 0;
-    font-size: 16px;
-  }
-</style>
-```
-
-### Progress Indicators with Status
-
-```svelte
-<script>
-  let tasks = [
-    { 
-      id: 1, 
-      name: 'Database Migration', 
-      progress: 75, 
-      status: 'In Progress',
-      eta: '2 hours remaining',
-      details: 'Migrating user data tables (3 of 4 completed)'
-    },
-    { 
-      id: 2, 
-      name: 'API Testing', 
-      progress: 100, 
-      status: 'Completed',
-      eta: 'Finished',
-      details: 'All endpoints tested successfully with 100% coverage'
-    },
-    { 
-      id: 3, 
-      name: 'UI Updates', 
-      progress: 45, 
-      status: 'In Progress',
-      eta: '4 hours remaining',
-      details: 'Updating 12 components (5 of 12 completed)'
-    }
-  ];
-  
-  function showProgressHint(task) {
-    return function(event) {
-      const hint = `
-        Task: ${task.name}
-        Status: ${task.status}
-        Progress: ${task.progress}%
-        ETA: ${task.eta}
-        
-        Details: ${task.details}
-      `;
-      window.Hint.show(event.target, hint, event.clientX, event.clientY);
-    };
-  }
-</script>
-
-<div class="progress-dashboard">
-  <h3>Task Progress</h3>
-  {#each tasks as task}
-    <div class="progress-item">
-      <div class="progress-info">
-        <span class="task-name">{task.name}</span>
-        <span class="progress-percent">{task.progress}%</span>
-      </div>
-      <div 
-        class="progress-bar"
-        on:mouseenter={showProgressHint(task)}
-      >
-        <div 
-          class="progress-fill"
-          style="width: {task.progress}%"
-        ></div>
-      </div>
-    </div>
-  {/each}
-</div>
-
-<style>
-  .progress-dashboard {
-    max-width: 500px;
-    padding: 20px;
-  }
-  
-  .progress-item {
-    margin-bottom: 16px;
-  }
-  
-  .progress-info {
-    display: flex;
-    justify-content: space-between;
-    margin-bottom: 8px;
-  }
-  
-  .task-name {
-    font-weight: 600;
-  }
-  
-  .progress-percent {
-    color: #666;
-  }
-  
-  .progress-bar {
-    height: 8px;
-    background: #e0e0e0;
-    border-radius: 4px;
-    overflow: hidden;
-    cursor: pointer;
-  }
-  
-  .progress-fill {
-    height: 100%;
-    background: linear-gradient(90deg, #007bff, #28a745);
-    transition: width 0.3s ease;
-  }
-</style>
-```
-
-### Conditional Hints with Dynamic Content
-
-```svelte
-<script>
-  let user = {
-    name: 'John Doe',
-    email: 'john@example.com',
-    role: 'admin',
-    lastActive: '2024-01-15T10:30:00Z',
-    permissions: ['read', 'write', 'delete', 'admin']
-  };
-  
-  function showUserBadgeHint(event) {
-    const now = new Date();
-    const lastActive = new Date(user.lastActive);
-    const hoursAgo = Math.floor((now - lastActive) / (1000 * 60 * 60));
-    
-    let activityStatus;
-    if (hoursAgo < 1) {
-      activityStatus = 'Active now';
-    } else if (hoursAgo < 24) {
-      activityStatus = `Active ${hoursAgo} hours ago`;
-    } else {
-      const daysAgo = Math.floor(hoursAgo / 24);
-      activityStatus = `Active ${daysAgo} days ago`;
-    }
-    
-    const hint = `
-      ${user.name} (${user.role.toUpperCase()})
-      ${user.email}
-      
-      ${activityStatus}
-      
-      Permissions: ${user.permissions.join(', ')}
-    `;
-    
-    window.Hint.show(event.target, hint, event.clientX, event.clientY);
-  }
-  
-  function showPermissionHint(permission) {
-    return function(event) {
-      const permissionDescriptions = {
-        read: 'Can view all content and data',
-        write: 'Can create and edit content',
-        delete: 'Can remove content and data',
-        admin: 'Full administrative access to all features'
-      };
-      
-      const hint = permissionDescriptions[permission] || 'Unknown permission';
-      window.Hint.show(event.target, hint, event.clientX, event.clientY);
-    };
-  }
-</script>
-
-<div class="user-profile">
-  <div 
-    class="user-badge"
-    on:mouseenter={showUserBadgeHint}
-  >
-    <div class="avatar">
-      {user.name.split(' ').map(n => n[0]).join('')}
-    </div>
-    <div class="user-info">
-      <div class="user-name">{user.name}</div>
-      <div class="user-role">{user.role}</div>
-    </div>
-  </div>
-  
-  <div class="permissions">
-    <h4>Permissions</h4>
-    <div class="permission-badges">
-      {#each user.permissions as permission}
-        <span 
-          class="permission-badge"
-          on:mouseenter={showPermissionHint(permission)}
-        >
-          {permission}
-        </span>
-      {/each}
-    </div>
-  </div>
-</div>
-
-<style>
-  .user-profile {
-    max-width: 300px;
-    padding: 20px;
-    border: 1px solid #ddd;
-    border-radius: 8px;
-  }
-  
-  .user-badge {
-    display: flex;
-    align-items: center;
-    gap: 12px;
-    cursor: pointer;
-    padding: 8px;
-    border-radius: 6px;
-    transition: background-color 0.2s;
-  }
-  
-  .user-badge:hover {
-    background-color: #f5f5f5;
-  }
-  
-  .avatar {
-    width: 40px;
-    height: 40px;
-    background: #007bff;
-    color: white;
-    border-radius: 50%;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    font-weight: bold;
-  }
-  
-  .user-name {
-    font-weight: 600;
-  }
-  
-  .user-role {
-    color: #666;
-    font-size: 14px;
-    text-transform: capitalize;
-  }
-  
-  .permissions {
-    margin-top: 20px;
-  }
-  
-  .permissions h4 {
-    margin: 0 0 12px 0;
-  }
-  
-  .permission-badges {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 6px;
-  }
-  
-  .permission-badge {
-    background: #e3f2fd;
-    color: #1976d2;
-    padding: 4px 8px;
-    border-radius: 12px;
-    font-size: 12px;
-    font-weight: 600;
-    cursor: pointer;
-    transition: background-color 0.2s;
-  }
-  
-  .permission-badge:hover {
-    background: #bbdefb;
-  }
-</style>
-```
-
-## Best Practices
-
-1. **Meaningful Content**: Provide genuinely helpful information in hints
-2. **Appropriate Timing**: The 500ms delay prevents accidental triggers
-3. **Concise Text**: Keep hint text brief but informative
-4. **Consistent Positioning**: Use mouse coordinates for natural positioning
-5. **Performance**: Avoid complex calculations in hint generation
-6. **Accessibility**: Consider keyboard users and screen readers
-7. **Content Hierarchy**: Use hints for secondary information, not primary actions
-
-## Styling
-
-The PopupHint component can be styled through CSS:
-
-```css
-.uniface-popup-hint {
-  position: fixed;
-  background: rgba(0, 0, 0, 0.8);
-  color: white;
-  padding: 8px 12px;
-  border-radius: 6px;
-  font-size: 13px;
-  line-height: 1.4;
-  z-index: 10000;
-  pointer-events: none;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
-  max-width: 300px;
-  word-wrap: break-word;
-}
-
-.uniface-popup-hint::before {
-  content: '';
-  position: absolute;
-  top: -4px;
-  left: 8px;
-  width: 0;
-  height: 0;
-  border-left: 4px solid transparent;
-  border-right: 4px solid transparent;
-  border-bottom: 4px solid rgba(0, 0, 0, 0.8);
-}
-```
-
-## Accessibility
-
-- Hints are supplementary information, not critical UI elements
-- Does not interfere with keyboard navigation
-- Content is descriptive text that enhances understanding
-- Compatible with screen readers when used appropriately
-- Does not trap focus or block interaction
-
-## Performance Considerations
-
-- Uses event delegation for efficient memory management
-- Automatic cleanup of event listeners prevents memory leaks
-- Portal rendering ensures proper layering without layout recalculation
-- Minimal DOM manipulation for smooth performance
-
-## Related Components
-
-- [Tooltip](../tooltip/README.md) - For more structured tooltip content
-- [MessageBox](../message-box/README.md) - For modal information dialogs
-- [Toast](../toast/README.md) - For notification messages
-- [Dialog](../dialog/README.md) - For complex interactive content