intelliwaketssveltekitv25 1.0.96 → 1.0.98

package/docs/ListGroupItems.md

@@ -0,0 +1,484 @@
+# ListGroupItems Testing Guide
+
+A guide for testing ListGroupItems components in downstream applications using Playwright.
+
+## Quick Start
+
+ListGroupItems automatically adds data attributes to help you locate items in tests:
+
+```typescript
+// Select a list item by its key
+await page.locator('[data-listgroupitem-key="myValue:MyTitle:st:bv:rt:sect"]').click()
+
+// Select a link within a list item
+await page.locator('[data-listgroupitem-key-a="myValue:MyTitle:st:bv:rt:sect"]').click()
+
+// Access a badge within an item
+await page.locator('[data-listgroupitem-key="myValue:MyTitle:st:bv:rt:sect"] .listGroupBadgeValue')
+```
+
+**Pro Tip:** Use the exported `ListGroupItemKeyCalc` function to generate keys that match the component:
+
+```typescript
+import { ListGroupItemKeyCalc } from 'intelliwaketssveltekitv25'
+
+const item = { value: 'myValue', title: 'MyTitle' }
+const key = ListGroupItemKeyCalc(item)
+await page.locator(`[data-listgroupitem-key="${key}"]`).click()
+```
+
+## Core Concepts
+
+### Data Attributes
+
+ListGroupItems provides two data attributes for targeting elements:
+
+| Attribute | Location | Purpose |
+|-----------|----------|---------|
+| `data-listgroupitem-key` | `<li>` element (class `listGroupItem`) | Identifies the entire list item container |
+| `data-listgroupitem-key-a` | `<a>` element (when item has href) | Identifies the clickable link within the item |
+
+### Badge Selection
+
+Badges within list items use the `listGroupBadgeValue` class and can be located relative to their parent item:
+
+```typescript
+// Find badge value
+const badge = page.locator('[data-listgroupitem-key="user:123:..."] .listGroupBadgeValue')
+await expect(badge).toHaveText('5')
+```
+
+---
+
+## Common Testing Patterns
+
+### Clicking List Items
+
+```typescript
+// Click an item with a link (href)
+await page.locator('[data-listgroupitem-key-a="settings:Settings:st:bv:rt:sect"]').click()
+
+// Click an item with a custom click handler (no href)
+await page.locator('[data-listgroupitem-key="action:ActionItem:st:bv:rt:sect"]').click()
+```
+
+### Verifying Item State
+
+```typescript
+// Check if item is selected
+const item = page.locator('[data-listgroupitem-key="dashboard:Dashboard:st:bv:rt:sect"]')
+await expect(item).toHaveClass(/selected/)
+
+// Check if item is disabled
+await expect(item).toHaveClass(/disabled/)
+
+// Verify badge value
+const badge = item.locator('.listGroupBadgeValue')
+await expect(badge).toHaveText('12')
+```
+
+### Testing Hierarchical Items
+
+```typescript
+// Parent item
+const parent = page.locator('[data-listgroupitem-key="folder:Folder:st:bv:rt:sect"]')
+
+// Expand/collapse toggle (when subsExist is true)
+await parent.locator('div[role="button"]').first().click()
+
+// Child items appear in nested ListGroupItems components
+const child = page.locator('[data-listgroupitem-key="subfolder:SubFolder:st:bv:rt:sect"]')
+await expect(child).toBeVisible()
+```
+
+### Testing Sections
+
+```typescript
+// Section headers have class 'listGroupHeader'
+const section = page.locator('.listGroupHeader').filter({ hasText: 'My Section' })
+await section.click() // Collapses/expands the section
+
+// Items within collapsed sections are hidden
+const item = page.locator('[data-listgroupitem-key="item:SectionItem:st:bv:rt:sect"]')
+await expect(item).toBeHidden()
+```
+
+---
+
+## Understanding Key Generation
+
+### Automatic Key Format
+
+When a list item doesn't have a custom `key` property, ListGroupItems generates one from available properties:
+
+```
+{value}:{title}:{sub_title}:{badgeValue}:{rightText}:{section}
+```
+
+**Default values when properties are missing:**
+- `value` → `'v'`
+- `title` → `paneName` → `'t'`
+- `sub_title` → `'st'`
+- `badgeValue` → `'bv'`
+- `rightText` → `'rt'`
+- `section` → `'sect'`
+
+**Example:**
+```typescript
+{
+  value: 'user123',
+  title: 'John Doe',
+  sub_title: 'Admin',
+  badgeValue: '5',
+  rightText: 'Active',
+  section: 'Users'
+}
+// Generates: "user123:John Doe:Admin:5:Active:Users"
+```
+
+### Custom Keys
+
+For more predictable testing, provide a custom `key` property:
+
+```typescript
+const items: TListGroupItem[] = [
+  {
+    key: 'user-john-doe', // Custom key for testing
+    title: 'John Doe',
+    value: 'user123',
+    // ... other properties
+  }
+]
+```
+
+Then in your test:
+```typescript
+await page.locator('[data-listgroupitem-key="user-john-doe"]').click()
+```
+
+### Using ListGroupItemKeyCalc in Tests
+
+The library exports the `ListGroupItemKeyCalc` function so your tests can generate the exact same keys as the component. This ensures consistency and prevents key mismatches:
+
+```typescript
+import { test, expect } from '@playwright/test'
+import { ListGroupItemKeyCalc } from 'intelliwaketssveltekitv25'
+import type { TListGroupItem } from 'intelliwaketssveltekitv25'
+
+test('navigate to user settings', async ({ page }) => {
+  // Define your item (this could come from your app's data)
+  const settingsItem: TListGroupItem = {
+    value: 'settings',
+    title: 'User Settings',
+    section: 'Configuration'
+  }
+
+  // Generate the key using the same function the component uses
+  const key = ListGroupItemKeyCalc(settingsItem)
+  // key = "settings:User Settings:st:bv:rt:Configuration"
+
+  // Use the key to locate and click the item
+  await page.locator(`[data-listgroupitem-key="${key}"]`).click()
+
+  // Verify navigation
+  await expect(page).toHaveURL(/.*settings/)
+})
+```
+
+**Benefits:**
+- **No manual key construction** - Avoid errors from typos or format mismatches
+- **Type safety** - TypeScript ensures your item has valid properties
+- **Consistency** - Same function used by component and tests
+- **Easy refactoring** - If key format changes, only update one function
+
+**Advanced Pattern - Test Fixtures:**
+
+Create reusable test fixtures with pre-calculated keys:
+
+```typescript
+// test-fixtures.ts
+import { ListGroupItemKeyCalc, type TListGroupItem } from 'intelliwaketssveltekitv25'
+
+export const testItems = {
+  dashboard: {
+    value: 'dashboard',
+    title: 'Dashboard',
+    section: 'Main'
+  },
+  settings: {
+    value: 'settings',
+    title: 'Settings',
+    section: 'Configuration'
+  }
+} as const satisfies Record<string, TListGroupItem>
+
+// Pre-calculate keys
+export const testKeys = Object.fromEntries(
+  Object.entries(testItems).map(([name, item]) => [name, ListGroupItemKeyCalc(item)])
+) as Record<keyof typeof testItems, string>
+
+// Usage in tests:
+// await page.locator(`[data-listgroupitem-key="${testKeys.dashboard}"]`).click()
+```
+
+---
+
+## Advanced Testing Scenarios
+
+### Working with Dynamic Content
+
+When titles contain HTML or special characters:
+
+```typescript
+// ListGroupItems converts title to string for key generation
+// HTML tags and entities are preserved in the key
+const item = {
+  title: 'User <strong>Admin</strong>', // HTML in title
+  value: 'admin'
+}
+// Generated key: "admin:User <strong>Admin</strong>:st:bv:rt:sect"
+
+// For reliable testing, use custom keys or match on value only
+await page.locator('[data-listgroupitem-key^="admin:"]').click()
+```
+
+**Best Practices:**
+1. **Preferred:** Use custom `key` property for items with dynamic or HTML content
+2. **Recommended:** Use `ListGroupItemKeyCalc` function to generate keys programmatically
+3. **Fallback:** Use partial matching with `^=` or `*=` selectors
+
+### Testing Icons and Images
+
+```typescript
+// Items with icons (via faProps or icon property)
+const item = page.locator('[data-listgroupitem-key="settings:Settings:st:bv:rt:sect"]')
+
+// Icon is inside the item
+const icon = item.locator('svg') // FontAwesome icons render as SVG
+await expect(icon).toBeVisible()
+
+// Images
+const img = item.locator('img')
+await expect(img).toHaveAttribute('alt', 'Settings')
+```
+
+### Testing Right Text and Badges
+
+```typescript
+const item = page.locator('[data-listgroupitem-key="task:MyTask:st:bv:rt:sect"]')
+
+// Right text appears in a div with inline-block float-right
+const rightText = item.locator('div.inline-block.float-right')
+await expect(rightText).toHaveText('Due Soon')
+
+// Badges have specific styling and data-color-dark attribute
+const badge = item.locator('.listGroupBadgeValue')
+await expect(badge).toHaveAttribute('data-color-dark', 'primary')
+await expect(badge).toHaveText('3')
+```
+
+### Testing Ellipsis and Wrap Behavior
+
+```typescript
+// When ellipses prop is true, title attribute contains full text
+const item = page.locator('[data-listgroupitem-key="long:Very Long Title...:st:bv:rt:sect"]')
+const titleDiv = item.locator('div.overflow-hidden').first()
+await expect(titleDiv).toHaveAttribute('title', 'Very Long Title That Was Truncated')
+```
+
+---
+
+## Component Props Affecting Testing
+
+### Key Props
+
+| Prop | Type | Impact on Testing |
+|------|------|-------------------|
+| `listItems` | `TListGroupItem[]` | Source of all items and their keys |
+| `subsExist` | `boolean` | Adds collapse/expand controls to items with children |
+| `useValueInHref` | `boolean` | Appends `:value` to href paths, affecting navigation |
+| `active` | `TFindIsActive` | Filters which items are visible (`true` shows non-hidden, `false` shows hidden, `null` shows all) |
+| `collapsedValues` | `string[]` | Controls which parent items are collapsed (children hidden) |
+| `collapsedSections` | `string[]` | Controls which sections are collapsed (items hidden) |
+| `parentSection` | `string \| null` | Filters section headers (section won't show if it matches parent) |
+
+### Testing with Different Props
+
+```typescript
+// Test item visibility based on 'active' prop
+// When active={true}, only items with hidden !== true are shown
+const hiddenItem = page.locator('[data-listgroupitem-key="archived:Archived:st:bv:rt:sect"]')
+await expect(hiddenItem).toBeHidden()
+
+// When active={null}, all items are shown
+await expect(hiddenItem).toBeVisible()
+```
+
+---
+
+## CSS Classes for Testing
+
+ListGroupItems uses several CSS classes that can aid in test selection:
+
+| Class | Element | Purpose |
+|-------|---------|---------|
+| `listGroup` | `<ul>` | Root container |
+| `listGroupItem` | `<li>` | Individual list item |
+| `listGroupHeader` | `<li>` | Section header (clickable to collapse) |
+| `listGroupBadgeValue` | `<div>` | Badge value indicator |
+| `listEmpty` | `<li>` | Shown when list is empty |
+| `selected` | `<li>` | Item is currently selected/active |
+| `disabled` | `<li>` | Item is disabled |
+| `list_group_indicator` | `<li>` | Animated selection indicator |
+
+### Example: Testing Selection States
+
+```typescript
+// Wait for selection indicator to appear
+await page.locator('.list_group_indicator').waitFor({ state: 'visible' })
+
+// Verify correct item is selected
+const selectedItem = page.locator('.listGroupItem.selected')
+await expect(selectedItem).toHaveAttribute('data-listgroupitem-key', 'expected:key:st:bv:rt:sect')
+```
+
+---
+
+## Troubleshooting
+
+### Key Not Found
+
+**Problem:** `locator('[data-listgroupitem-key="..."]')` doesn't find the element.
+
+**Solutions:**
+1. Check if item is filtered by `active` prop
+2. Check if item is in a collapsed section (`collapsedSections`)
+3. Check if parent item is collapsed (`collapsedValues`)
+4. Verify key format matches generated key (check console/inspector)
+5. Use partial match: `locator('[data-listgroupitem-key^="value:"]')`
+
+### Link Not Clickable
+
+**Problem:** `data-listgroupitem-key-a` attribute not found.
+
+**Explanation:** This attribute only exists when:
+- Item has `pathFromItem` (generated from `href` or `title`)
+- Item does NOT have `linkClick` handler
+
+**Solution:** If item has `linkClick`, use `data-listgroupitem-key` on the `<li>` instead.
+
+### Item Hidden But Should Be Visible
+
+**Problem:** Item exists in DOM but is not visible.
+
+**Check:**
+1. Is parent item collapsed? Look for `collapsed` property in parent
+2. Is section collapsed? Check `collapsedSections` array
+3. Is item filtered by `active` prop? Check `hidden` property on item
+4. Is item in a nested ListGroupItems? Parent's `topValue` determines which items show
+
+---
+
+## Complete Example
+
+```typescript
+import { test, expect } from '@playwright/test'
+import { ListGroupItemKeyCalc, type TListGroupItem } from 'intelliwaketssveltekitv25'
+
+test('navigate and interact with list group', async ({ page }) => {
+  await page.goto('/dashboard')
+
+  // Wait for list to load
+  await page.locator('.listGroup').waitFor()
+
+  // Click a section header to expand it
+  await page.locator('.listGroupHeader').filter({ hasText: 'Settings' }).click()
+
+  // Define the item we want to interact with
+  const profileItem: TListGroupItem = {
+    value: 'profile',
+    title: 'Profile Settings',
+    section: 'sect'
+  }
+  const profileKey = ListGroupItemKeyCalc(profileItem)
+
+  // Click a list item using generated key
+  await page.locator(`[data-listgroupitem-key-a="${profileKey}"]`).click()
+
+  // Verify navigation occurred
+  await expect(page).toHaveURL(/.*profile/)
+
+  // Verify item is selected
+  const selectedItem = page.locator(`[data-listgroupitem-key="${profileKey}"]`)
+  await expect(selectedItem).toHaveClass(/selected/)
+
+  // Check badge value
+  const badge = selectedItem.locator('.listGroupBadgeValue')
+  await expect(badge).toHaveText('3')
+
+  // Expand an item with children using generated key
+  const usersItem: TListGroupItem = {
+    value: 'users',
+    title: 'Users',
+    section: 'sect'
+  }
+  const usersKey = ListGroupItemKeyCalc(usersItem)
+  const parentItem = page.locator(`[data-listgroupitem-key="${usersKey}"]`)
+  await parentItem.locator('div[role="button"]').first().click()
+
+  // Child items now visible
+  const adminUsersItem: TListGroupItem = {
+    value: 'users-admin',
+    title: 'Admin Users',
+    section: 'sect'
+  }
+  const adminUsersKey = ListGroupItemKeyCalc(adminUsersItem)
+  const childItem = page.locator(`[data-listgroupitem-key="${adminUsersKey}"]`)
+  await expect(childItem).toBeVisible()
+})
+```
+
+---
+
+## Reference: TListGroupItem Properties
+
+Key properties that affect testing:
+
+```typescript
+type TListGroupItem = {
+  key?: string                    // Custom key (recommended for testing)
+  value?: string                  // Used in auto-generated key and for hierarchy
+  title?: string | Snippet        // Primary display text, used in key
+  sub_title?: string | Snippet    // Secondary text, used in key
+  section?: string                // Section header, used in key
+  badgeValue?: string | number    // Badge content, used in key
+  rightText?: string              // Right-aligned text, used in key
+
+  href?: string                   // Custom navigation path
+  linkClick?: () => void          // Custom click handler (overrides href)
+
+  parent_value?: string           // Parent item value (for hierarchy)
+  subs?: TListGroupItem[]         // Child items
+
+  selected?: boolean              // Item is selected
+  disabled?: boolean              // Item is disabled
+  hidden?: boolean                // Item is hidden (respects 'active' prop)
+  collapsed?: boolean             // Item's children are collapsed
+
+  // Visual properties
+  faProps?: IFAProps              // FontAwesome icon props
+  icon?: IconDefinition           // FontAwesome icon
+  imageHref?: string              // Image URL
+  bigIcon?: boolean               // Larger icon size
+  badgeClass?: string             // Additional badge CSS classes
+  badgeColor?: string             // Badge color theme
+  itemClass?: string              // Additional item CSS classes
+
+  // Other
+  paneName?: string               // Fallback for title in key generation
+  hover_title?: string            // Tooltip text
+  noLinkReplace?: boolean         // Affects DisplayHTML link processing
+  strikeThrough?: boolean         // Strike-through styling
+  dataSvelteKitPreloadData?: string // SvelteKit preload behavior
+}
+```