intelliwaketssveltekitv25 1.0.95 → 1.0.98

package/docs/MasterDetailLayout.md

@@ -0,0 +1,557 @@
+# MasterDetailLayout Component
+
+**Purpose:** Responsive master-detail pattern with automatic routing integration and breakpoint-based mobile/desktop views
+
+**When to Use:**
+- List-detail interfaces (users list → user detail, products → product detail)
+- Navigation sidebars with dynamic content areas
+- Inbox/message viewers, file browsers, or any hierarchical data view
+- When you need automatic mobile/tablet responsive behavior
+- Master list needs to hide on mobile when detail is shown
+
+## Key Features
+
+- **Automatic Mobile Behavior:** Master list hides when detail opens on smaller screens
+- **PathAnalyzer Integration:** Automatically syncs with SvelteKit routing
+- **Breakpoint Control:** Choose when layout switches from mobile to desktop view
+- **ListGroupItems Integration:** Built-in list navigation with data attributes for testing
+- **Hierarchical Support:** Parent-child relationships in list items
+- **Snippet-Based:** Flexible content slots for header, list, footer, and detail areas
+
+## Key Props
+
+### Required Props
+
+- `pageRoute: string` - Base route for navigation (e.g., 'Users', 'Products'). Used with PathAnalyzer for routing.
+
+### Optional Props
+
+- `breakAt?: TBreakAt` (default: 'md') - Responsive breakpoint: 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+- `backName?: string | null` - Text for back navigation button on mobile
+- `listItems?: TMasterDetailListGroupItem[] | null` - Array of items for the list
+- `caret?: boolean | 'left' | 'right'` - Show selection indicator arrow
+- `emptyListMessage?: string | null` - Message when list is empty
+- `active?: TFindIsActive` - Filter items: `true` (non-hidden), `false` (hidden), `null` (all)
+- `useValueInHref?: boolean` (default: false) - Append `:value` to generated hrefs
+
+### Styling Props
+
+- `mdClass?: string` - CSS classes for root container
+- `masterClass?: string` - CSS classes for master (list) section
+- `detailClass?: string` - CSS classes for detail section
+- `wrapText?: boolean` (default: false) - Allow list item text to wrap
+- `ellipses?: boolean` (default: false) - Truncate long text with ellipses
+- `borders?: boolean` (default: false) - Show borders between list items
+- `rounded?: boolean` (default: false) - Use rounded card style
+- `roundedDetailFormatted?: boolean` (default: true) - Apply rounded style to detail when `rounded` is true
+- `roundedDetailFormattedHome?: boolean` - Override rounded detail style for home/no-selection view
+
+### Detail Header Props
+
+- `detailShowHeader?: boolean | string` (default: false) - Show header in detail area (true = item title, string = custom text)
+- `detailShowHeaderFAProps?: IFAProps | null` - FontAwesome icon props for detail header
+- `noLinkReplace?: boolean` (default: false) - Disable automatic link conversion in DisplayHTML
+
+## Snippets
+
+- `empty?: Snippet` - Content when list is empty
+- `header?: Snippet` - Master section header (typically title or search)
+- `subheader?: Snippet` - Additional header content below main header
+- `list?: Snippet` - Custom list implementation (replaces default ListGroupItems)
+- `footer?: Snippet` - Master section footer
+- `detail?: Snippet` - Detail/content area (right side on desktop, full screen on mobile)
+
+## TMasterDetailListGroupItem Type
+
+Extends `TListGroupItem` with additional properties:
+
+```typescript
+type TMasterDetailListGroupItem = Omit<TListGroupItem, 'subs'> & {
+  subs?: TMasterDetailListGroupItem[]          // Child items
+  roundedDetailFormatted?: boolean             // Override rounded style for this item's detail
+  detailShowHeader?: boolean | string          // Override header visibility for this item
+}
+```
+
+### Common TListGroupItem Properties
+
+- `key?: string` - Custom key for testing (recommended)
+- `value?: string` - Item identifier (used for routing and hierarchy)
+- `title?: string | Snippet` - Primary text
+- `sub_title?: string | Snippet` - Secondary text
+- `section?: string` - Section header grouping
+- `href?: string` - Custom navigation path
+- `parent_value?: string` - Parent item value (creates hierarchy)
+- `selected?: boolean` - Item is selected
+- `disabled?: boolean` - Item is disabled
+- `hidden?: boolean` - Item is hidden (respects `active` prop)
+- `faProps?: IFAProps` - FontAwesome icon
+- `icon?: IconDefinition` - FontAwesome icon (alternative)
+- `imageHref?: string` - Image URL
+- `badgeValue?: string | number` - Badge content
+- `badgeColor?: string` - Badge color theme
+- `rightText?: string` - Right-aligned text
+- `linkClick?: () => void` - Custom click handler (overrides href)
+- `hover_title?: string` - Tooltip text
+
+## Usage Examples
+
+### Basic Master-Detail
+
+```svelte
+<script>
+  import { MasterDetailLayout } from 'intelliwaketssveltekitv25';
+
+  const users = [
+    { value: '1', title: 'Alice Johnson', href: 'User/1' },
+    { value: '2', title: 'Bob Smith', href: 'User/2' },
+    { value: '3', title: 'Carol White', href: 'User/3' }
+  ];
+</script>
+
+<MasterDetailLayout
+  pageRoute="Users"
+  listItems={users}
+  backName="Users"
+>
+  {#snippet header()}
+    <h1 class="text-center p-2">Users</h1>
+  {/snippet}
+
+  {#snippet detail()}
+    <slot />  <!-- Child route renders here -->
+  {/snippet}
+</MasterDetailLayout>
+```
+
+### With Search and Hierarchical Items
+
+```svelte
+<script>
+  import { MasterDetailLayout, Search } from 'intelliwaketssveltekitv25';
+  import { SearchRows } from '@solidbasisventures/intelliwaketsfoundation';
+
+  let search = $state('');
+
+  const allItems = [
+    { value: '1', title: 'Parent Item', href: 'Item/1' },
+    { value: '2', title: 'Child Item A', parent_value: '1', href: 'Item/2' },
+    { value: '3', title: 'Child Item B', parent_value: '1', href: 'Item/3' }
+  ];
+
+  let filteredItems = $derived(SearchRows(allItems, search));
+</script>
+
+<MasterDetailLayout
+  pageRoute="Items"
+  listItems={filteredItems}
+  breakAt="lg"
+  rounded
+  caret="right"
+>
+  {#snippet header()}
+    <div class="p-2">
+      <h1 class="text-center">Items</h1>
+      <Search bind:value={search} placeholder="Search items..." />
+    </div>
+  {/snippet}
+
+  {#snippet detail()}
+    <slot />
+  {/snippet}
+</MasterDetailLayout>
+```
+
+### With Sections and Custom Keys
+
+```svelte
+<script>
+  import { MasterDetailLayout } from 'intelliwaketssveltekitv25';
+
+  const products = [
+    {
+      key: 'electronics-laptop',
+      value: 'laptop',
+      title: 'Laptop',
+      section: 'Electronics',
+      badgeValue: 5,
+      href: 'Product/laptop'
+    },
+    {
+      key: 'electronics-phone',
+      value: 'phone',
+      title: 'Phone',
+      section: 'Electronics',
+      badgeValue: 12,
+      href: 'Product/phone'
+    },
+    {
+      key: 'furniture-desk',
+      value: 'desk',
+      title: 'Desk',
+      section: 'Furniture',
+      rightText: 'In Stock',
+      href: 'Product/desk'
+    }
+  ];
+</script>
+
+<MasterDetailLayout
+  pageRoute="Products"
+  listItems={products}
+  detailShowHeader={true}
+  borders
+>
+  {#snippet header()}
+    <h1 class="text-center p-2">Products</h1>
+  {/snippet}
+
+  {#snippet footer()}
+    <div class="p-2 text-sm text-gray-500">
+      {products.length} products
+    </div>
+  {/snippet}
+
+  {#snippet detail()}
+    <slot />
+  {/snippet}
+</MasterDetailLayout>
+```
+
+---
+
+## PathAnalyzer Integration
+
+MasterDetailLayout automatically creates a `PathAnalyzer` instance to manage navigation state. The PathAnalyzer:
+
+- Parses the current SvelteKit route
+- Determines which list item is "open" based on the URL
+- Generates navigation paths for list items
+- Provides `isOpen()` method to check if a path is active
+
+### How Item Paths Are Generated
+
+If an item doesn't have an explicit `href`, the path is generated:
+
+```typescript
+// Without useValueInHref
+ToPascalCase(item.title) // "User Settings" → "UserSettings"
+
+// With useValueInHref={true}
+ToPascalCase(item.title) + ':' + item.value // "User Settings" → "UserSettings:123"
+```
+
+**Example Routes:**
+- `pageRoute="Users"` + item `{ title: "Alice", value: "1" }` → `/Users/Alice` (or `/Users/Alice:1` with useValueInHref)
+- `pageRoute="Products"` + item `{ href: "Item/special-123" }` → `/Products/Item/special-123`
+
+---
+
+## Responsive Behavior
+
+The `breakAt` prop controls when the layout switches from mobile to desktop:
+
+| breakAt | Mobile (stacked) | Desktop (side-by-side) |
+|---------|------------------|------------------------|
+| `sm` | < 640px | ≥ 640px |
+| `md` | < 768px | ≥ 768px (default) |
+| `lg` | < 1024px | ≥ 1024px |
+| `xl` | < 1280px | ≥ 1280px |
+| `2xl` | < 1536px | ≥ 1536px |
+
+**Mobile Behavior:**
+- Master list visible when no item selected (URL at base route)
+- Detail area visible when item selected (URL includes item path)
+- Master list hidden when detail shown
+- "Back" button appears (using `backName` prop) via BreakAtManager
+
+**Desktop Behavior:**
+- Master and detail visible side-by-side
+- Master list always visible
+- Detail updates without hiding master
+
+---
+
+## Testing with Playwright
+
+Since MasterDetailLayout uses `ListGroupItems` internally, you can use the same testing patterns documented in [ListGroupItems Testing Guide](ListGroupItems).
+
+### Locating List Items
+
+MasterDetailLayout automatically adds `data-listgroupitem-key` attributes to all list items:
+
+```typescript
+import { test, expect } from '@playwright/test';
+import { ListGroupItemKeyCalc } from 'intelliwaketssveltekitv25';
+
+test('navigate to user detail', async ({ page }) => {
+  await page.goto('/Users');
+
+  // Using custom key
+  await page.locator('[data-listgroupitem-key="user-alice"]').click();
+
+  // Or using ListGroupItemKeyCalc for auto-generated keys
+  const userItem = { value: '1', title: 'Alice Johnson' };
+  const key = ListGroupItemKeyCalc(userItem);
+  await page.locator(`[data-listgroupitem-key="${key}"]`).click();
+
+  // Verify navigation
+  await expect(page).toHaveURL(/.*Alice/);
+});
+```
+
+### Testing Master-Detail Navigation
+
+```typescript
+test('master-detail responsive behavior', async ({ page }) => {
+  await page.goto('/Products');
+
+  // Desktop: Both master and detail visible
+  await page.setViewportSize({ width: 1024, height: 768 });
+
+  await page.locator('[data-listgroupitem-key="electronics-laptop"]').click();
+
+  await expect(page.locator('.masterDetailMaster')).toBeVisible();
+  await expect(page.locator('.masterDetailDetail')).toBeVisible();
+
+  // Mobile: Only detail visible when item open
+  await page.setViewportSize({ width: 375, height: 667 });
+
+  await expect(page.locator('.masterDetailMaster')).toBeHidden();
+  await expect(page.locator('.masterDetailDetail')).toBeVisible();
+});
+```
+
+### Testing List Item Selection
+
+```typescript
+test('verify selected item styling', async ({ page }) => {
+  await page.goto('/Users/Alice');
+
+  // Find selected item
+  const selectedItem = page.locator('.listGroupItem.selected');
+  await expect(selectedItem).toBeVisible();
+
+  // Verify correct item is selected
+  await expect(selectedItem).toHaveAttribute('data-listgroupitem-key', 'user-alice');
+
+  // Selection indicator should be visible
+  await expect(page.locator('.list_group_indicator')).toBeVisible();
+});
+```
+
+### Testing Hierarchical Items
+
+```typescript
+test('expand and navigate to child item', async ({ page }) => {
+  await page.goto('/Items');
+
+  // Parent item with children
+  const parentItem = page.locator('[data-listgroupitem-key="parent-item"]');
+
+  // Click expand toggle (first button in the item)
+  await parentItem.locator('div[role="button"]').first().click();
+
+  // Child item becomes visible
+  const childItem = page.locator('[data-listgroupitem-key="child-item-a"]');
+  await expect(childItem).toBeVisible();
+
+  // Navigate to child
+  await childItem.locator('a').click();
+  await expect(page).toHaveURL(/.*ChildItemA/);
+});
+```
+
+### Testing with Custom Keys (Recommended)
+
+For more reliable testing, always provide custom `key` properties:
+
+```typescript
+// In your component
+const listItems = [
+  { key: 'user-alice', value: '1', title: 'Alice', href: 'User/1' },
+  { key: 'user-bob', value: '2', title: 'Bob', href: 'User/2' }
+];
+
+// In your test
+await page.locator('[data-listgroupitem-key="user-alice"]').click();
+```
+
+### Testing Empty State
+
+```typescript
+test('display empty message', async ({ page }) => {
+  await page.goto('/Products');
+
+  // When no items
+  const emptyMessage = page.locator('.listEmpty');
+  await expect(emptyMessage).toContainText('No products available');
+});
+```
+
+---
+
+## Advanced Patterns
+
+### Filter by Hidden State
+
+Control which items are visible using the `active` prop:
+
+```typescript
+const items = [
+  { value: '1', title: 'Active User', hidden: false },
+  { value: '2', title: 'Inactive User', hidden: true },
+  { value: '3', title: 'Archived User', hidden: true }
+];
+
+// Show only active items (hidden: false)
+<MasterDetailLayout listItems={items} active={true} />
+
+// Show only hidden items (hidden: true)
+<MasterDetailLayout listItems={items} active={false} />
+
+// Show all items regardless of hidden property
+<MasterDetailLayout listItems={items} active={null} />
+```
+
+### Dynamic Detail Headers
+
+Show item-specific headers in the detail area:
+
+```typescript
+const items = [
+  {
+    value: '1',
+    title: 'Dashboard',
+    detailShowHeader: 'Overview Dashboard',
+    faProps: { icon: 'chart-line' }
+  },
+  {
+    value: '2',
+    title: 'Settings',
+    detailShowHeader: true, // Uses item title
+    faProps: { icon: 'cog' }
+  },
+  {
+    value: '3',
+    title: 'Profile',
+    detailShowHeader: false // No header
+  }
+];
+
+<MasterDetailLayout
+  listItems={items}
+  detailShowHeader={false}  // Default for all items
+  detailShowHeaderFAProps={{ icon: 'info-circle' }}  // Default icon
+/>
+```
+
+### Custom List Implementation
+
+Replace the default ListGroupItems with your own:
+
+```svelte
+<MasterDetailLayout pageRoute="Custom">
+  {#snippet list()}
+    <ul class="custom-list">
+      {#each items as item}
+        <li><a href={item.href}>{item.title}</a></li>
+      {/each}
+    </ul>
+  {/snippet}
+
+  {#snippet detail()}
+    <slot />
+  {/snippet}
+</MasterDetailLayout>
+```
+
+---
+
+## Common Issues & Solutions
+
+### Master List Not Showing on Desktop
+
+**Problem:** Master list is hidden even on large screens.
+
+**Solution:** Check that an item is not selected (URL is at base route). The master hides when `pathAnalyzer.activePageSlug` exists.
+
+### Item Not Getting Selected
+
+**Problem:** Clicking an item doesn't show selection styling.
+
+**Solution:** Ensure the `href` matches the actual route structure. Use PathAnalyzer's `isOpen()` logic by matching your route params.
+
+### Links Not Clickable
+
+**Problem:** List items don't navigate when clicked.
+
+**Solution:**
+1. Ensure `href` is set on items, or title can be converted to a path
+2. Check that `linkClick` isn't set (it overrides href navigation)
+3. Verify items aren't `disabled`
+
+### Children Not Expanding
+
+**Problem:** Clicking expand icon doesn't show child items.
+
+**Solution:**
+1. Ensure child items have `parent_value` matching parent's `value`
+2. Check that `subsExist` is true or items have `subs` array
+3. Verify children aren't filtered out by `active` prop
+
+---
+
+## Styling Customization
+
+### CSS Classes Used
+
+| Class | Element | Purpose |
+|-------|---------|---------|
+| `.masterDetail` | Root container | Grid layout container |
+| `.masterDetailMaster` | Master section | Left sidebar with list |
+| `.masterDetailDetail` | Detail section | Right content area |
+| `.masterDetailDetailWithHeader` | Detail section | Applied when header is shown |
+| `.listGroupItem` | List items | Individual list entries |
+| `.selected` | Active list item | Currently selected item |
+| `.list_group_indicator` | Selection indicator | Animated selection highlight |
+
+### Custom Styling Examples
+
+```svelte
+<!-- Wider master section -->
+<MasterDetailLayout
+  mdClass="md:grid-cols-[400px_1fr]"
+  pageRoute="Users"
+  {listItems}
+/>
+
+<!-- Custom colors -->
+<MasterDetailLayout
+  masterClass="bg-blue-50 dark:bg-blue-900"
+  detailClass="bg-white dark:bg-slate-800"
+  pageRoute="Products"
+  {listItems}
+/>
+
+<!-- Compact rounded style -->
+<MasterDetailLayout
+  rounded
+  mdClass="p-1 gap-1"
+  pageRoute="Items"
+  {listItems}
+/>
+```
+
+---
+
+## Related Components
+
+- **[ListGroupItems](ListGroupItems)** - Testing guide for list item data attributes
+- **[PathAnalyzer](Functions#pathanalyzer)** - URL parsing and navigation helper
+- **[Search](Search)** - Integrate search with filtered list items
+- **[TabHref](TabHref)** - Alternative navigation pattern
+
+---
+
+For more details on testing list items with Playwright, see the complete [ListGroupItems Testing Guide](ListGroupItems).

package/docs/_Sidebar.md

@@ -17,6 +17,7 @@
 
 ### Layout & Overlays
 - [Modal](Modal)
+- [MasterDetailLayout](MasterDetailLayout)
 - [TabHeader](TabHeader)
 - [TabHref](TabHref)
 - [SlideDown](SlideDown)
@@ -35,4 +36,7 @@
 - [ImporterLoad](ImporterLoad)
 - [ImporterAnalysis](ImporterAnalysis)
 
+### Testing
+- [ListGroupItems](ListGroupItems)
+
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intelliwaketssveltekitv25",
-  "version": "1.0.95",
+  "version": "1.0.98",
   "private": false,
   "license": "MIT",
   "exports": {