intelliwaketssveltekitv25 1.0.82 → 1.0.84

package/docs/Search.md

@@ -0,0 +1,364 @@
+# Search Component
+
+**Purpose:** Debounced search input with session storage persistence
+
+**When to Use:**
+- Filter lists, tables, or search results
+- Debounced input to reduce API calls
+- Persist search value across page navigation
+- Clean, consistent search UI
+
+## Key Props
+
+- `value?: string` ($bindable, default: '') - Search query
+- `delayMS?: number` (default: 500) - Debounce delay in milliseconds
+- `placeholder?: string` (default: 'Search') - Input placeholder text
+- `onChange?: (val: string) => void` - Callback when value changes (after debounce)
+- `sessionKey?: string` - Session storage key for persistence
+- `bordered?: boolean` (default: false) - Show input border
+- `noMagnifyingGlass?: boolean` - Hide search icon
+- `element?: HTMLInputElement` - Bind to input element reference
+- `use?: ActionArray` - Svelte actions to apply
+- `hidden?: boolean` - Hide the component
+- `id?: string` - Input element ID
+- `class?: string` - Additional CSS classes
+- ...HTMLInputAttributes - All standard input props
+
+## Key Features
+
+### Debouncing
+- User types → Wait for `delayMS` → Trigger `onChange` and update `value`
+- Press Enter → Immediate trigger (bypass debounce)
+- Blur input → Immediate trigger
+- Reduces API calls and improves performance
+
+### Session Storage
+When `sessionKey` is provided:
+- Saves search value to `sessionStorage`
+- Restores value on component mount
+- Clears storage when value returns to original state
+- Persists across page refreshes
+
+### Auto-Select on Focus
+Built-in `selectOnFocus` action automatically selects text when input is focused.
+
+## Usage Examples
+
+```svelte
+<script>
+  import { Search } from 'intelliwaketssveltekitv25';
+
+  let searchQuery = $state('');
+</script>
+
+<!-- Basic search -->
+<Search bind:value={searchQuery} />
+
+<!-- With callback -->
+<Search
+  bind:value={searchQuery}
+  onChange={(val) => {
+    console.log('Search for:', val);
+    performSearch(val);
+  }}
+/>
+
+<!-- Custom debounce delay -->
+<Search
+  bind:value={searchQuery}
+  delayMS={300}
+/>
+<!-- Triggers 300ms after typing stops -->
+
+<!-- Immediate (no debounce) -->
+<Search
+  bind:value={searchQuery}
+  delayMS={0}
+/>
+
+<!-- With session storage -->
+<Search
+  bind:value={searchQuery}
+  sessionKey="productSearch"
+/>
+<!-- Value persists across page refreshes -->
+
+<!-- Custom placeholder -->
+<Search
+  bind:value={searchQuery}
+  placeholder="Search products..."
+/>
+
+<!-- With border -->
+<Search
+  bind:value={searchQuery}
+  bordered
+/>
+
+<!-- Without magnifying glass icon -->
+<Search
+  bind:value={searchQuery}
+  noMagnifyingGlass
+/>
+
+<!-- Custom styling -->
+<Search
+  bind:value={searchQuery}
+  class="w-full md:w-96"
+/>
+
+<!-- Get input element reference -->
+<script>
+  let inputElement: HTMLInputElement | undefined;
+</script>
+
+<Search
+  bind:value={searchQuery}
+  bind:element={inputElement}
+/>
+<button onclick={() => inputElement?.focus()}>
+  Focus Search
+</button>
+
+<!-- With additional input attributes -->
+<Search
+  bind:value={searchQuery}
+  maxlength={50}
+  autocomplete="off"
+  autofocus
+/>
+```
+
+## Integration Patterns
+
+### Filter Table Data
+```svelte
+<script>
+  let searchQuery = $state('');
+  let allItems = $state([...]);
+
+  let filteredItems = $derived(
+    allItems.filter(item =>
+      item.name.toLowerCase().includes(searchQuery.toLowerCase())
+    )
+  );
+</script>
+
+<Search bind:value={searchQuery} />
+
+<ArrayTable data={filteredItems} {columns} />
+```
+
+### API Search with SvelteKit
+```svelte
+<script>
+  let searchQuery = $state('');
+
+  async function handleSearch(query: string) {
+    if (query.length >= 2) {
+      await goto(`/search?q=${encodeURIComponent(query)}`);
+    }
+  }
+</script>
+
+<Search
+  bind:value={searchQuery}
+  onChange={handleSearch}
+  delayMS={500}
+  sessionKey="globalSearch"
+/>
+```
+
+### With Loading Indicator
+```svelte
+<script>
+  let searchQuery = $state('');
+  let searching = $state(false);
+
+  async function performSearch(query: string) {
+    searching = true;
+    try {
+      const results = await api.search(query);
+      // ...
+    } finally {
+      searching = false;
+    }
+  }
+</script>
+
+<div class="relative">
+  <Search
+    bind:value={searchQuery}
+    onChange={performSearch}
+  />
+  {#if searching}
+    <div class="absolute right-2 top-1/2 -translate-y-1/2">
+      <Icon icon={faSpinner} spin />
+    </div>
+  {/if}
+</div>
+```
+
+### Multi-Field Search
+```svelte
+<script>
+  let nameSearch = $state('');
+  let emailSearch = $state('');
+
+  let filtered = $derived(
+    users.filter(user =>
+      user.name.includes(nameSearch) &&
+      user.email.includes(emailSearch)
+    )
+  );
+</script>
+
+<div class="grid grid-cols-2 gap-4">
+  <Search bind:value={nameSearch} placeholder="Search by name..." />
+  <Search bind:value={emailSearch} placeholder="Search by email..." />
+</div>
+```
+
+### With Clear Button
+```svelte
+<script>
+  let searchQuery = $state('');
+</script>
+
+<div class="flex gap-2">
+  <Search bind:value={searchQuery} class="flex-1" />
+  {#if searchQuery}
+    <button onclick={() => searchQuery = ''}>
+      Clear
+    </button>
+  {/if}
+</div>
+```
+
+## Keyboard Shortcuts
+
+- **Enter** - Immediately trigger search (bypass debounce)
+- **Escape** - (Native) Clear input
+- **Focus** - Automatically select all text
+
+## Session Storage Behavior
+
+When `sessionKey="mySearch"`:
+
+1. **On mount:** Restore value from `sessionStorage.getItem('mySearch')`
+2. **On change:** Save to `sessionStorage.setItem('mySearch', value)`
+3. **On clear:** Remove from `sessionStorage.removeItem('mySearch')`
+
+Use cases:
+- Preserve search across tab navigation
+- Remember last search on page refresh
+- Share search state between components
+
+```svelte
+<!-- Page 1 -->
+<Search
+  bind:value={query1}
+  sessionKey="mainSearch"
+/>
+
+<!-- Page 2 (preserves the same search) -->
+<Search
+  bind:value={query2}
+  sessionKey="mainSearch"
+/>
+```
+
+## Common Patterns
+
+### Master-Detail Layout Search
+```svelte
+<MasterDetailLayout>
+  {#snippet list()}
+    <Search bind:value={filterQuery} sessionKey="itemFilter" />
+    {#each filteredItems as item}
+      <ItemCard {item} />
+    {/each}
+  {/snippet}
+</MasterDetailLayout>
+```
+
+### Real-Time Filter
+```svelte
+<script>
+  let products = $state([...]);
+  let filter = $state('');
+
+  // Updates immediately as user types (after debounce)
+  let visible = $derived(
+    products.filter(p =>
+      p.name.toLowerCase().includes(filter.toLowerCase()) ||
+      p.sku.includes(filter)
+    )
+  );
+</script>
+
+<Search bind:value={filter} delayMS={300} />
+
+<div class="text-sm text-gray-600">
+  Showing {visible.length} of {products.length} products
+</div>
+
+{#each visible as product}
+  <ProductCard {product} />
+{/each}
+```
+
+## Common Mistakes
+
+- ❌ Not using `bind:value` for two-way binding
+  ✅ Correct: `<Search bind:value={searchQuery} />`
+
+- ❌ Using very short debounce delays (< 200ms)
+  ✅ Correct: Use 300-500ms for best UX and performance
+
+- ❌ Triggering expensive operations in `onChange` without checks
+  ✅ Correct: Check minimum query length: `if (query.length >= 2)`
+
+- ❌ Not handling empty string in filter logic
+  ✅ Correct: `if (!query) return allItems;`
+
+- ❌ Using same `sessionKey` for different search contexts
+  ✅ Correct: Use unique keys: `sessionKey="userSearch"`, `sessionKey="productSearch"`
+
+## Related Components
+
+- **MultiSelect** - Has built-in search functionality
+- **ArrayTable** - Often paired with Search for filtering
+- **MasterDetailLayout** - Common container for search + results
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | `''` | Search query ($bindable) |
+| `delayMS` | `number` | `500` | Debounce delay (ms) |
+| `placeholder` | `string` | `'Search'` | Input placeholder |
+| `onChange` | `(val: string) => void` | - | Debounced callback |
+| `sessionKey` | `string` | - | Session storage key |
+| `bordered` | `boolean` | `false` | Show border |
+| `noMagnifyingGlass` | `boolean` | `false` | Hide search icon |
+| `element` | `HTMLInputElement` | - | Input element ref |
+| `use` | `ActionArray` | `[]` | Svelte actions |
+| `hidden` | `boolean` | `false` | Hide component |
+| `class` | `string` | `''` | CSS classes |
+| `id` | `string` | - | Input ID |
+
+## Styling
+
+- Uses `inputSearch` wrapper class
+- Icon: Absolute positioned left with `text-slate-300`
+- Input: Standard input styling with `ps-6` (left padding) when icon visible
+- Border: Transparent by default, visible when `bordered={true}`
+- Print: Hidden if value is empty (`forcePrintHidden`)
+
+## Performance Tips
+
+- Use appropriate `delayMS` (500ms recommended)
+- Implement minimum query length checks in `onChange`
+- Use `$derived` for reactive filtering (efficient)
+- Consider virtualization for large result sets

package/docs/SlideDown.md

@@ -0,0 +1,358 @@
+# SlideDown Component
+
+**Purpose:** Animated dropdown menu with keyboard navigation and flexible content
+
+**When to Use:**
+- Dropdown menus without form input styling
+- Standalone dropdown menus
+- Custom menu implementations
+- Menus with mixed content (actions + custom snippets)
+
+## Key Props
+
+- `ddActions: IDDAction[]` (required) - Menu items array
+- `show?: boolean` ($bindable, default: false) - Control open/closed state
+- `button?: Snippet` - Custom button content
+- `actions?: Snippet` - Custom menu content (in addition to ddActions)
+- `buttonTitle?: string | null` - Button text (if not using button snippet)
+- `buttonClass?: string` (default: '') - CSS classes for button
+- `width?: string` (default: 'auto') - Menu width
+- `maxHeight?: string | null` (default: '60vh') - Max height for scrolling
+- `caret?: boolean` (default: false) - Show dropdown caret icon
+- `use?: ActionArray` - Svelte actions to apply
+- `highlightedIndex?: number` (default: -1) - Keyboard navigation index
+
+## IDDAction Interface
+
+Same as **DropDown** component. See [DropDown.md](DropDown.md#iddaction-interface) for full details.
+
+## Key Differences from DropDown
+
+| Feature | SlideDown | DropDown |
+|---------|-----------|----------|
+| Styling | Clean, minimal | Input control styling option |
+| Animation | Slide + fade | Slide only |
+| Position | Centered, auto | Configurable position |
+| Use Case | Menus, navigation | Form controls, selects |
+| Complexity | Simpler | More features |
+
+## Keyboard Navigation
+
+- **Arrow Down** - Move to next item / Open menu
+- **Arrow Up** - Move to previous item
+- **Enter** - Execute highlighted action
+- **Escape** - Close menu
+- **Click outside** - Close menu
+
+## Usage Examples
+
+```svelte
+<script>
+  import { SlideDown } from 'intelliwaketssveltekitv25';
+  import { faUser, faCog, faSignOut } from '@fortawesome/free-solid-svg-icons';
+
+  let showMenu = $state(false);
+</script>
+
+<!-- Basic menu -->
+<SlideDown
+  bind:show={showMenu}
+  buttonTitle="Menu"
+  ddActions={[
+    {
+      title: 'Profile',
+      faProps: { icon: faUser },
+      action: () => goto('/profile')
+    },
+    {
+      title: 'Settings',
+      faProps: { icon: faCog },
+      action: () => goto('/settings')
+    },
+    { divider: true },
+    {
+      title: 'Logout',
+      faProps: { icon: faSignOut },
+      action: () => logout()
+    }
+  ]}
+/>
+
+<!-- With caret icon -->
+<SlideDown
+  bind:show={showMenu}
+  buttonTitle="Options"
+  ddActions={actions}
+  caret
+/>
+
+<!-- Custom button content -->
+<SlideDown
+  bind:show={showMenu}
+  ddActions={actions}
+>
+  {#snippet button()}
+    <div class="flex items-center gap-2">
+      <Avatar src={user.avatar} />
+      <span>{user.name}</span>
+    </div>
+  {/snippet}
+</SlideDown>
+
+<!-- Custom menu content -->
+<SlideDown
+  bind:show={showMenu}
+  ddActions={[]}
+>
+  {#snippet actions()}
+    <div class="p-4">
+      <h3>Custom Content</h3>
+      <p>Any content here</p>
+    </div>
+  {/snippet}
+</SlideDown>
+
+<!-- Mixed custom + actions -->
+<SlideDown
+  bind:show={showMenu}
+  ddActions={standardActions}
+>
+  {#snippet actions()}
+    <div class="p-2 bg-gray-50">
+      <p class="text-xs">Recent Activity:</p>
+      {#each recentItems as item}
+        <div>{item.name}</div>
+      {/each}
+    </div>
+  {/snippet}
+</SlideDown>
+
+<!-- Fixed width -->
+<SlideDown
+  bind:show={showMenu}
+  buttonTitle="Select"
+  ddActions={options}
+  width="300px"
+/>
+
+<!-- No max height (full scrollable) -->
+<SlideDown
+  bind:show={showMenu}
+  buttonTitle="All Items"
+  ddActions={manyItems}
+  maxHeight={null}
+/>
+
+<!-- With custom button styling -->
+<SlideDown
+  bind:show={showMenu}
+  buttonTitle="Actions"
+  buttonClass="text-blue-600 font-bold hover:text-blue-800"
+  ddActions={actions}
+/>
+```
+
+## Common Patterns
+
+### User Menu
+```svelte
+<script>
+  let userMenuOpen = $state(false);
+</script>
+
+<SlideDown
+  bind:show={userMenuOpen}
+  ddActions={[
+    {
+      title: user.name,
+      header: true
+    },
+    { divider: true },
+    {
+      title: 'Profile',
+      faProps: { icon: faUser },
+      href: '/profile'
+    },
+    {
+      title: 'Settings',
+      faProps: { icon: faCog },
+      href: '/settings'
+    },
+    { divider: true },
+    {
+      title: 'Logout',
+      faProps: { icon: faSignOut },
+      action: () => handleLogout()
+    }
+  ]}
+>
+  {#snippet button()}
+    <Avatar src={user.avatar} size="sm" />
+  {/snippet}
+</SlideDown>
+```
+
+### Context Menu
+```svelte
+<script>
+  let contextMenu = $state(false);
+</script>
+
+<div class="relative">
+  <button onclick={() => contextMenu = !contextMenu}>
+    <Icon icon={faEllipsisV} />
+  </button>
+
+  <SlideDown
+    bind:show={contextMenu}
+    ddActions={[
+      { title: 'Edit', faProps: { icon: faEdit }, action: () => edit() },
+      { title: 'Duplicate', faProps: { icon: faCopy }, action: () => duplicate() },
+      { divider: true },
+      { title: 'Delete', faProps: { icon: faTrash }, action: () => remove() }
+    ]}
+  >
+    {#snippet button()}
+      <!-- Empty, controlled by external button -->
+    {/snippet}
+  </SlideDown>
+</div>
+```
+
+### Grouped Menu
+```svelte
+<SlideDown
+  buttonTitle="Tools"
+  ddActions={[
+    { title: 'File Tools', header: true },
+    { title: 'New File', action: () => {} },
+    { title: 'Open File', action: () => {} },
+    { title: 'Save File', action: () => {} },
+    { divider: true },
+    { title: 'Edit Tools', header: true },
+    { title: 'Cut', action: () => {} },
+    { title: 'Copy', action: () => {} },
+    { title: 'Paste', action: () => {} }
+  ]}
+/>
+```
+
+### With Active State
+```svelte
+<script>
+  let selectedOption = $state('option1');
+</script>
+
+<SlideDown
+  buttonTitle={options.find(o => o.id === selectedOption)?.title}
+  ddActions={options.map(opt => ({
+    title: opt.title,
+    active: opt.id === selectedOption,
+    action: () => selectedOption = opt.id
+  }))}
+/>
+```
+
+### Navigation Dropdown
+```svelte
+<SlideDown
+  buttonTitle="Products"
+  ddActions={[
+    { title: 'All Products', href: '/products' },
+    { title: 'Electronics', href: '/products/electronics' },
+    { title: 'Clothing', href: '/products/clothing' },
+    { title: 'Food', href: '/products/food' }
+  ]}
+/>
+```
+
+## Advanced Features
+
+### Auto-Scroll to Active Item
+When menu opens, automatically scrolls to the active item.
+
+### Indentation Support
+```svelte
+<SlideDown
+  buttonTitle="Nested Menu"
+  ddActions={[
+    { title: 'Parent Item', action: () => {} },
+    { title: 'Child Item 1', indented: true, action: () => {} },
+    { title: 'Child Item 2', indented: true, action: () => {} },
+    { title: 'Another Parent', action: () => {} }
+  ]}
+/>
+```
+
+### Auto Headers/Dividers
+```svelte
+<!-- Auto-adds headers when headerGroup changes -->
+<SlideDown
+  buttonTitle="Grouped"
+  ddActions={[
+    { title: 'Item A1', headerGroup: 'Group A', action: () => {} },
+    { title: 'Item A2', headerGroup: 'Group A', action: () => {} },
+    { title: 'Item B1', headerGroup: 'Group B', action: () => {} },
+    { title: 'Item B2', headerGroup: 'Group B', action: () => {} }
+  ]}
+/>
+<!-- Renders: Group A (header), Item A1, Item A2, Group B (header), Item B1, Item B2 -->
+```
+
+## Common Mistakes
+
+- ❌ Not providing button content or buttonTitle
+  ✅ Correct: Provide buttonTitle or button snippet
+
+- ❌ Using SlideDown when DropDown is more appropriate
+  ✅ Correct: Use DropDown for form inputs, SlideDown for menus
+
+- ❌ Forgetting to bind `show` for controlled state
+  ✅ Correct: `bind:show={isOpen}` to control externally
+
+- ❌ Not providing action or href for menu items
+  ✅ Correct: Every item needs action, href, or be a divider/header
+
+- ❌ Very long menus without maxHeight
+  ✅ Correct: Keep default maxHeight or set reasonable limit
+
+## Related Components
+
+- **DropDown** - More feature-rich dropdown with positioning
+- **DropDownControl** - Lower-level dropdown primitive
+- **Icon** - Used for menu item icons
+- **IDDAction** - Shared action item interface
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `ddActions` | `IDDAction[]` | (required) | Menu items |
+| `show` | `boolean` | `false` | Open state ($bindable) |
+| `button` | `Snippet` | - | Custom button |
+| `actions` | `Snippet` | - | Custom menu content |
+| `buttonTitle` | `string \| null` | `null` | Button text |
+| `buttonClass` | `string` | `''` | Button CSS classes |
+| `width` | `string` | `'auto'` | Menu width |
+| `maxHeight` | `string \| null` | `'60vh'` | Max menu height |
+| `caret` | `boolean` | `false` | Show caret icon |
+| `use` | `ActionArray` | `[]` | Svelte actions |
+| `highlightedIndex` | `number` | `-1` | Keyboard nav index |
+
+## Styling
+
+- Clean button styling (no default borders)
+- White background on open (`bg-white`, `dark:bg-slate-700`)
+- Shadow on open (`shadow-lg`)
+- Slide animation (200ms cubic-in-out)
+- Hover: `hover:bg-slate-100` for items
+- Active: `bg-primary-main text-white`
+- Disabled: `text-slate-300`
+
+## Accessibility
+
+- Keyboard navigation fully supported
+- `role="button"` and `role="menuitem"` attributes
+- `aria-expanded` on container
+- `aria-haspopup="true"` on button
+- Tab index managed for proper focus flow