intelliwaketssveltekitv25 1.0.82 → 1.0.83

package/docs/MultiSelect.md

@@ -0,0 +1,304 @@
+# MultiSelect Component
+
+**Replaces:** Multiple `<select multiple>` and custom multi-select implementations
+
+**Purpose:** Type-safe, searchable multi-select dropdown with dynamic item creation and keyboard navigation
+
+**When to Use:**
+- Selecting multiple items from a list (tags, categories, assignees)
+- Searchable selection with many options
+- Dynamic item creation (creating new tags on the fly)
+- Single-select with search (set `isMulti={false}`)
+- Type-safe selections with TypeScript generics
+
+## Key Props
+
+- `possibles: T[]` - Array of available items to select from (required)
+- `selected?: T[]` ($bindable) - Currently selected items array
+- `selectedIDs?: (number | string)[]` ($bindable) - Selected item IDs (alternative to selected)
+- `created?: T[]` ($bindable) - Items that were created (not in possibles)
+- `existing?: T[]` ($bindable) - Items that exist in possibles
+- `isMulti?: boolean` (default: true) - Allow multiple selections or single select
+- `allowClearAll?: boolean` (default: true) - Show clear all button
+- `create?: (value: string) => T | null` - Function to create new items from search text
+- `createValid?: (value: string) => boolean | string` - Validate new item creation (return string for error message)
+- `createPrefix?: string` (default: 'Create:') - Prefix text for create option
+- `displayValue?: (item: T) => string | number` - How to display items (default: item.name or item.id)
+- `idValue?: (item: T) => any` - How to get unique ID from items (default: item.id)
+- `keyValue?: (item: T) => any` - Key for Svelte each blocks (default: same as idValue)
+- `inputValue?: (item: T) => any` - Value for hidden form inputs (default: same as idValue)
+- `headerValue?: (item: T) => string | null` - Extract header/category from items for grouping
+- `show?: boolean` ($bindable) - Control dropdown open/closed state
+- `placeholder?: string` - Input placeholder text
+- `disabled?: boolean` - Disable all interactions
+- `readonly?: boolean` - Display only, no interaction
+- `required?: boolean` - Mark as required field
+- `invalid?: boolean` - Show invalid state
+- `autoFocus?: boolean` - Auto-focus input on mount
+- `name?: string` - Form field name (creates hidden inputs for each selected item)
+- `form?: string` - Associate with form by ID
+- Callback props: `onadd`, `onselect`, `oncreate`, `onchange`, `onclear`, `onclearall`
+
+**TypeScript:** Uses generics `<T extends TGenericMultiSelect>` for type safety
+
+## TGenericMultiSelect Interface
+
+```typescript
+interface TGenericMultiSelect {
+  id?: string | number;
+  name?: string;
+  header?: string; // For grouping
+  [key: string]: any; // Additional properties
+}
+```
+
+## Keyboard Navigation
+
+- **Arrow Down/Up**: Navigate dropdown options
+- **Enter**: Select highlighted option or create new item
+- **Backspace**: Remove last selected item (when search is empty)
+- **Type**: Filter options by search
+
+## Usage Examples
+
+```svelte
+<script lang="ts">
+  import { MultiSelect } from 'intelliwaketssveltekitv25';
+
+  interface Tag {
+    id: number;
+    name: string;
+  }
+
+  const availableTags: Tag[] = [
+    { id: 1, name: 'JavaScript' },
+    { id: 2, name: 'TypeScript' },
+    { id: 3, name: 'Svelte' }
+  ];
+
+  let selectedTags = $state<Tag[]>([]);
+</script>
+
+<!-- Basic multi-select -->
+<MultiSelect
+  possibles={availableTags}
+  bind:selected={selectedTags}
+  placeholder="Select tags..."
+/>
+
+<!-- With dynamic item creation -->
+<MultiSelect
+  possibles={availableTags}
+  bind:selected={selectedTags}
+  placeholder="Select or create tags..."
+  create={(name) => ({
+    id: Date.now(),
+    name: name
+  })}
+/>
+
+<!-- With creation validation -->
+<MultiSelect
+  possibles={availableTags}
+  bind:selected={selectedTags}
+  create={(name) => ({ id: Date.now(), name })}
+  createValid={(name) => {
+    if (name.length < 3) return 'Tag must be at least 3 characters';
+    if (availableTags.some(t => t.name.toLowerCase() === name.toLowerCase())) {
+      return 'Tag already exists';
+    }
+    return true;
+  }}
+/>
+
+<!-- Single select mode -->
+<MultiSelect
+  possibles={availableTags}
+  bind:selected={selectedTags}
+  isMulti={false}
+  placeholder="Select one..."
+/>
+
+<!-- With selected IDs binding -->
+<script>
+  let selectedTagIDs = $state<number[]>([1, 3]);
+</script>
+
+<MultiSelect
+  possibles={availableTags}
+  bind:selectedIDs={selectedTagIDs}
+  placeholder="Select tags..."
+/>
+
+<!-- With custom display function -->
+<script>
+  interface User {
+    id: number;
+    firstName: string;
+    lastName: string;
+    email: string;
+  }
+
+  const users: User[] = [
+    { id: 1, firstName: 'John', lastName: 'Doe', email: 'john@example.com' },
+    { id: 2, firstName: 'Jane', lastName: 'Smith', email: 'jane@example.com' }
+  ];
+
+  let assignees = $state<User[]>([]);
+</script>
+
+<MultiSelect
+  possibles={users}
+  bind:selected={assignees}
+  displayValue={(user) => `${user.firstName} ${user.lastName}`}
+  placeholder="Assign to..."
+/>
+
+<!-- With grouping/headers -->
+<script>
+  interface Item {
+    id: number;
+    name: string;
+    category: string;
+  }
+
+  const items: Item[] = [
+    { id: 1, name: 'Apple', category: 'Fruits' },
+    { id: 2, name: 'Banana', category: 'Fruits' },
+    { id: 3, name: 'Carrot', category: 'Vegetables' },
+    { id: 4, name: 'Lettuce', category: 'Vegetables' }
+  ];
+</script>
+
+<MultiSelect
+  possibles={items}
+  bind:selected={selectedItems}
+  headerValue={(item) => item.category}
+  placeholder="Select items..."
+/>
+
+<!-- In a form -->
+<form method="POST">
+  <MultiSelect
+    name="tags"
+    possibles={availableTags}
+    bind:selected={selectedTags}
+    required
+    placeholder="Select at least one tag..."
+  />
+  <button type="submit">Submit</button>
+</form>
+
+<!-- With callbacks -->
+<MultiSelect
+  possibles={availableTags}
+  bind:selected={selectedTags}
+  onadd={(id) => console.log('Added:', id)}
+  onselect={(id) => console.log('Selected existing:', id)}
+  oncreate={(id) => console.log('Created new:', id)}
+  onchange={(items) => console.log('Selection changed:', items)}
+  onclear={(id) => console.log('Removed:', id)}
+  onclearall={() => console.log('Cleared all')}
+/>
+
+<!-- Readonly/disabled -->
+<MultiSelect
+  possibles={availableTags}
+  selected={[availableTags[0], availableTags[2]]}
+  readonly
+/>
+
+<MultiSelect
+  possibles={availableTags}
+  bind:selected={selectedTags}
+  disabled
+/>
+
+<!-- Without clear all button -->
+<MultiSelect
+  possibles={availableTags}
+  bind:selected={selectedTags}
+  allowClearAll={false}
+/>
+```
+
+## Common Mistakes
+
+- ❌ Not providing `possibles` array: `<MultiSelect bind:selected={x} />`
+  ✅ Correct: `<MultiSelect possibles={items} bind:selected={x} />`
+
+- ❌ Binding to non-array for multi-select: `bind:selected={singleItem}`
+  ✅ Correct: `bind:selected={arrayOfItems}` (always an array, even for single select)
+
+- ❌ Not using TypeScript generics: `possibles: any[]`
+  ✅ Correct: `possibles: Tag[]` with `interface Tag extends TGenericMultiSelect`
+
+- ❌ Forgetting id or name in data objects: `possibles={[{label: 'Item'}]}`
+  ✅ Correct: `possibles={[{id: 1, name: 'Item'}]}` or provide custom `idValue` and `displayValue` functions
+
+- ❌ Using create without validation when it can fail
+  ✅ Correct: Use `createValid` to validate and show error messages
+
+- ❌ Not handling created vs existing items separately
+  ✅ Correct: Use `bind:created` and `bind:existing` to differentiate
+
+## Advanced Features
+
+### 1. Dynamic Item Creation
+
+```svelte
+<MultiSelect
+  possibles={tags}
+  bind:selected={selectedTags}
+  bind:created={newlyCreatedTags}
+  bind:existing={existingSelectedTags}
+  create={(name) => ({ id: Date.now(), name })}
+  createPrefix="Add new:"
+  oncreate={(id) => {
+    // Save new tag to backend
+    saveNewTag(id);
+  }}
+/>
+```
+
+### 2. Custom Value Functions
+
+```svelte
+<script>
+  interface ComplexItem {
+    uuid: string;
+    displayName: string;
+    sortOrder: number;
+  }
+</script>
+
+<MultiSelect
+  possibles={complexItems}
+  bind:selected={selectedItems}
+  idValue={(item) => item.uuid}
+  displayValue={(item) => item.displayName}
+  keyValue={(item) => item.uuid}
+  inputValue={(item) => item.uuid}
+/>
+```
+
+### 3. Grouped Options
+
+```svelte
+<MultiSelect
+  possibles={groupedItems}
+  bind:selected={selectedItems}
+  headerValue={(item) => item.category}
+/>
+<!-- Automatically adds category headers when category changes -->
+```
+
+## Related Components
+
+- `DropDown` - For single action/selection without search
+- `DropDownControl` - Lower-level dropdown control (used internally)
+- `DisplayHTML` - Used to render item text
+
+## Storybook
+
+See `Components/MultiSelect` stories

package/docs/Paginator.md

@@ -0,0 +1,332 @@
+# Paginator Component
+
+**Purpose:** Responsive pagination controls with SvelteKit integration
+
+**When to Use:**
+- Navigate through multi-page data sets
+- Integrate with SvelteKit query parameters
+- Automatic data invalidation on page change
+- Responsive design adapting to screen width
+
+## Key Props
+
+- `page: number` ($bindable, required) - Current page number (1-indexed)
+- `pageCount: number` (required) - Total number of pages
+- `updateQueryParams?: boolean | string` (default: false) - Sync with URL query params
+- `invalidate?: string | string[] | 'All'` - SvelteKit invalidation targets
+- `onPageChange?: (page: number) => void` - Callback when page changes
+- `verbose?: boolean` (default: false) - Enable console logging for debugging
+- `class?: string` - Additional CSS classes
+
+## Display Modes
+
+The paginator automatically adapts based on screen width and page count:
+
+1. **Full Range** (few pages, wide screen)
+   - Shows all page buttons: `[1] [2] [3] [4] [5]`
+
+2. **Condensed Range** (many pages)
+   - Shows subset with ellipsis: `[1] ... [5] [6] [7] ... [20]`
+   - Centers around current page
+
+3. **Dropdown Mode** (narrow screen)
+   - Shows: `‹ [5 of 20 ▼] ›`
+   - Click dropdown to select page
+
+4. **With Fast Navigation** (many pages, wider screen)
+   - Shows: `« ‹ [5 of 20 ▼] › »`
+   - `«` - Jump back by 10/25/50 pages
+   - `»` - Jump forward by 10/25/50 pages
+
+## Usage Examples
+
+```svelte
+<script>
+  import { Paginator } from 'intelliwaketssveltekitv25';
+
+  let currentPage = $state(1);
+  let totalPages = $state(10);
+</script>
+
+<!-- Basic usage -->
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+/>
+
+<!-- With URL query parameter sync -->
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+  updateQueryParams
+/>
+<!-- Updates ?page=5 in URL -->
+
+<!-- Custom query parameter name -->
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+  updateQueryParams="p"
+/>
+<!-- Updates ?p=5 in URL -->
+
+<!-- With SvelteKit invalidation -->
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+  invalidate="app:data"
+/>
+
+<!-- Multiple invalidation targets -->
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+  invalidate={['app:products', 'app:stats']}
+/>
+
+<!-- Invalidate all -->
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+  invalidate="All"
+/>
+
+<!-- With page change callback -->
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+  onPageChange={(page) => {
+    console.log('Page changed to:', page);
+    fetchData(page);
+  }}
+/>
+
+<!-- With custom styling -->
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+  class="mt-4 border-t pt-4"
+/>
+
+<!-- Enable debug logging -->
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+  verbose
+/>
+```
+
+## Integration with SvelteKit
+
+### Basic Load Function Integration
+```svelte
+<!-- +page.svelte -->
+<script>
+  export let data;
+
+  let currentPage = $state(data.page);
+</script>
+
+<Paginator
+  bind:page={currentPage}
+  pageCount={data.totalPages}
+  updateQueryParams
+  invalidate="app:products"
+/>
+
+<div>
+  {#each data.products as product}
+    <ProductCard {product} />
+  {/each}
+</div>
+
+<!-- +page.ts -->
+export const load = async ({ depends, url }) => {
+  depends('app:products');
+
+  const page = parseInt(url.searchParams.get('page') || '1');
+  const pageSize = 20;
+
+  const { products, total } = await fetchProducts({ page, pageSize });
+
+  return {
+    products,
+    page,
+    totalPages: Math.ceil(total / pageSize)
+  };
+};
+```
+
+### With Server-Side Pagination
+```svelte
+<!-- +page.server.ts -->
+export const load = async ({ depends, url }) => {
+  depends('app:items');
+
+  const page = parseInt(url.searchParams.get('page') || '1');
+  const limit = 25;
+  const offset = (page - 1) * limit;
+
+  const items = await db.items.findMany({
+    skip: offset,
+    take: limit
+  });
+
+  const total = await db.items.count();
+
+  return {
+    items,
+    page,
+    pageCount: Math.ceil(total / limit)
+  };
+};
+```
+
+### Without Query Parameters (State Only)
+```svelte
+<script>
+  let page = $state(1);
+  let pageSize = 20;
+
+  let data = $derived(allData.slice((page - 1) * pageSize, page * pageSize));
+  let pageCount = $derived(Math.ceil(allData.length / pageSize));
+</script>
+
+<Paginator
+  bind:page
+  {pageCount}
+/>
+
+{#each data as item}
+  <div>{item.name}</div>
+{/each}
+```
+
+## Responsive Behavior
+
+### Wide Screen (800px+)
+```
+« ‹ [1] [2] [3] [4] [5] › »
+```
+
+### Medium Screen (500-800px)
+```
+‹ [1] ... [4] [5] [6] ... [20] ›
+```
+
+### Narrow Screen (<500px)
+```
+‹ [5 of 20 ▼] ›
+```
+
+## Common Patterns
+
+### Table Pagination
+```svelte
+<ArrayTable {data} {columns} />
+
+<Paginator
+  bind:page={currentPage}
+  pageCount={totalPages}
+  updateQueryParams
+  invalidate="app:tableData"
+  class="mt-4"
+/>
+```
+
+### Search Results
+```svelte
+<Search bind:value={query} />
+
+<SearchResults results={data.results} />
+
+<Paginator
+  bind:page={currentPage}
+  pageCount={data.totalPages}
+  updateQueryParams="page"
+  invalidate="app:search"
+/>
+```
+
+### Infinite Scroll Alternative
+```svelte
+<script>
+  let page = $state(1);
+
+  async function loadMore() {
+    page += 1;
+    // Paginator with invalidate will trigger data load
+  }
+</script>
+
+{#each data.items as item}
+  <Item {item} />
+{/each}
+
+<Paginator bind:page pageCount={totalPages} invalidate="app:items" />
+
+<button onclick={loadMore}>Load More</button>
+```
+
+## Common Mistakes
+
+- ❌ Using 0-indexed page numbers
+  ✅ Correct: Pages are 1-indexed (page 1, 2, 3...)
+
+- ❌ Not using `bind:page` for two-way binding
+  ✅ Correct: `<Paginator bind:page={currentPage} />`
+
+- ❌ Forgetting `depends()` in load function when using invalidate
+  ✅ Correct: Add `depends('app:identifier')` in load function
+
+- ❌ Setting pageCount to 0
+  ✅ Correct: Always ensure pageCount ≥ 1, use conditional rendering if no data
+
+- ❌ Using both `updateQueryParams` and manual `onPageChange` invalidation
+  ✅ Correct: Use one or the other, not both
+
+## Advanced Features
+
+### Fast Navigation
+For large page counts (>15 pages), fast navigation buttons appear:
+- `«` jumps back by calculated amount (10/25/50 depending on total pages)
+- `»` jumps forward by same amount
+- Auto-hides when not useful (near start/end)
+
+### Auto Page Bounds
+- Page is automatically clamped to `1 ≤ page ≤ pageCount`
+- Out-of-bounds pages are corrected on render
+
+### Query Parameter Behavior
+When `updateQueryParams` is enabled:
+- Page 1: Query parameter removed (clean URLs)
+- Page 2+: Query parameter added
+- Uses `replaceState` (no browser history clutter)
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `page` | `number` | (required) | Current page ($bindable) |
+| `pageCount` | `number` | (required) | Total pages |
+| `updateQueryParams` | `boolean \| string` | `false` | Query param name or true for 'page' |
+| `invalidate` | `string \| string[] \| 'All'` | - | SvelteKit invalidation |
+| `onPageChange` | `(page: number) => void` | - | Page change callback |
+| `verbose` | `boolean` | `false` | Debug logging |
+| `class` | `string` | `''` | Additional CSS classes |
+
+## Styling
+
+Uses these classes:
+- `pagination` - Container
+- `btnClean` - Button base style
+- `btnLink` - Dropdown button
+- `active` - Active page button
+- `invisible` - Hidden navigation buttons (vs `hidden` which removes from layout)
+
+## Performance
+
+- Efficiently calculates visible page range
+- Uses `$derived` for reactive page display
+- Minimal re-renders on page change
+- Responsive layout calculated from `clientWidth` measurement