intelliwaketssveltekitv25 1.0.82 → 1.0.83

package/docs/Home.md

@@ -0,0 +1,109 @@
+# IntelliWakeTSSvelteKitV2.5 Component Library
+
+**Package:** `intelliwaketssveltekitv25`
+**Technologies:** Svelte 5 | TypeScript | Tailwind CSS v4
+
+## Overview
+
+Professional SvelteKit component library providing 41 reusable UI components and 17 utility modules. Built with modern Svelte 5 features (runes, snippets, generics) and optimized for TypeScript developers building data-driven applications.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install intelliwaketssveltekitv25
+```
+
+### Required Setup
+
+1. **Import CSS** (in your root `+layout.svelte` or `app.css`):
+```typescript
+import 'intelliwaketssveltekitv25/dist/app.css';
+```
+
+2. **Configure Tailwind** - See [Integration Guide](Integration) for required color configuration
+
+3. **Install Peer Dependencies**:
+```bash
+npm install @solidbasisventures/intelliwaketsfoundation @sveltejs/kit svelte
+```
+
+## Component Categories
+
+### 🎛️ Form Controls
+Replace native HTML form elements with enhanced features:
+- **[Switch](Switch)** - Toggle switches for boolean values
+- **[InputNumber](InputNumber)** - Numeric inputs with formatting (currency, percent, decimals)
+- **[TextArea](TextArea)** - Auto-resizing text areas
+- **[DropDown](DropDown)** - Rich dropdown menus (replaces `<select>`)
+- **[MultiSelect](MultiSelect)** - Multi-select with search and creation
+
+### 📊 Data Display
+Present data with performance and style:
+- **VirtualList** - High-performance lists for large datasets
+- **VirtualTable** - Virtual scrolling tables
+- **Calendar** - Date selection
+- **[DateRangePicker](DateRangePicker)** - Date range selection with presets
+
+### 🪟 Layout & Overlays
+Structure your application:
+- **[Modal](Modal)** - Feature-rich dialog overlays
+- **MasterDetailLayout** - Responsive master-detail pattern
+- **[TabHeader](TabHeader)** - Client-side tab navigation
+- **[TabHref](TabHref)** - URL-based tab navigation
+- **[SlideDown](SlideDown)** - Animated dropdown menus
+
+### 🎨 Visual & Utilities
+Icons, notifications, and helpers:
+- **[Icon](Icon)** - FontAwesome icon integration
+- **[DisplayHTML](DisplayHTML)** - Safe HTML rendering with link conversion
+- **MessageBoxes** - Toast notifications
+- **[Functions](Functions)** - 20+ utility functions and Svelte use: actions
+
+### 🔍 Navigation & Search
+Navigation and filtering tools:
+- **[Search](Search)** - Debounced search input
+- **[Paginator](Paginator)** - Responsive pagination controls
+
+### 📥 Data Import
+CSV import workflow components:
+- **[Importer](Importer)** - Complete CSV import with validation
+- **[ImporterLoad](ImporterLoad)** - File upload and template download
+- **[ImporterAnalysis](ImporterAnalysis)** - Column mapping and validation
+
+## Native HTML Replacement Guide
+
+| Instead of... | Use... |
+|--------------|--------|
+| `<input type="checkbox">` | **[Switch](Switch)** |
+| `<input type="number">` | **[InputNumber](InputNumber)** |
+| `<textarea>` | **[TextArea](TextArea)** |
+| `<select>` | **[DropDown](DropDown)** |
+| `<select multiple>` | **[MultiSelect](MultiSelect)** |
+| `<dialog>` | **[Modal](Modal)** |
+
+## Key Features
+
+- ✅ **Svelte 5 Runes** - Modern reactive syntax with `$state`, `$derived`, `$effect`, `$bindable`
+- ✅ **TypeScript Generics** - Type-safe data handling
+- ✅ **Tailwind CSS v4** - Custom theme integration
+- ✅ **Two-way Binding** - Comprehensive form controls with `bind:` support
+- ✅ **Performance Optimized** - Virtual scrolling for large datasets
+- ✅ **Responsive Design** - Mobile-first layout patterns
+
+## Documentation Structure
+
+- **[Component Docs](Home#component-categories)** - Detailed documentation for each component
+- **[Integration Guide](Integration)** - Setup requirements and Tailwind configuration
+- **[Svelte 5 Patterns](Svelte-5-Patterns)** - Runes, snippets, and TypeScript generics usage
+
+## Support
+
+- **Storybook:** Run `pnpm storybook` for interactive component demos
+- **Project Docs:** See `CLAUDE.md` in package root for development guide
+- **Issues:** Report bugs or request features on GitHub
+
+---
+
+*For AI/LLM usage: See the main `llms.txt` file for progressive disclosure guidance.*

package/docs/Icon.md

@@ -0,0 +1,203 @@
+# Icon Component
+
+**Purpose:** Render FontAwesome icons with extensive customization options
+
+**When to Use:**
+- Display icons throughout your application
+- Add visual indicators to buttons, menus, or text
+- Use duotone icons with custom colors
+- Animate icons with spin or pulse effects
+
+## Key Props
+
+- `icon: IconDefinition` (required) - FontAwesome icon from `@fortawesome/free-solid-svg-icons`
+- `size?: string` - Icon size: 'xs', 'sm', 'lg', '1x' through '10x' (default: inherits font size)
+- `color?: string` - Icon color (default: 'currentColor')
+- `dataColor?: TDefaultColorPalate` - Theme color palette
+- `fw?: boolean` (default: true) - Fixed width for consistent alignment
+- `pull?: 'left' | 'right'` - Float icon left or right
+
+### Transform Props
+- `scale?: number` (default: 1) - Scale the icon
+- `translateX?: number` (default: 0) - Horizontal offset
+- `translateY?: number` (default: 0) - Vertical offset
+- `rotate?: number | string` - Rotation angle in degrees
+- `flip?: 'horizontal' | 'vertical' | 'both' | boolean` - Flip the icon
+
+### Animation Props
+- `spin?: boolean` - Continuous rotation animation
+- `pulse?: boolean` - Pulsing animation
+
+### Duotone Icon Props
+- `primaryColor?: string` - Color for primary layer
+- `secondaryColor?: string` - Color for secondary layer
+- `primaryOpacity?: number` (default: 1) - Opacity of primary layer
+- `secondaryOpacity?: number` (default: 0.4) - Opacity of secondary layer
+- `swapOpacity?: boolean` - Swap opacity values between layers
+
+### Other Props
+- `title?: string` - Accessible title for screen readers
+- `invisible?: boolean` - Hide icon (keeps space)
+- `hidden?: boolean` - Completely remove icon
+- `class?: string` - Additional CSS classes
+- `id?: string` - HTML id attribute
+- `style?: string` - Inline styles
+
+## Usage Examples
+
+```svelte
+<script>
+  import { Icon } from 'intelliwaketssveltekitv25';
+  import {
+    faUser,
+    faSpinner,
+    faCheck,
+    faExclamation,
+    faHeart
+  } from '@fortawesome/free-solid-svg-icons';
+</script>
+
+<!-- Basic icon -->
+<Icon icon={faUser} />
+
+<!-- Sized icons -->
+<Icon icon={faUser} size="xs" />
+<Icon icon={faUser} size="sm" />
+<Icon icon={faUser} size="lg" />
+<Icon icon={faUser} size="2x" />
+<Icon icon={faUser} size="5x" />
+
+<!-- Colored icon -->
+<Icon icon={faHeart} color="red" />
+<Icon icon={faCheck} color="green" />
+
+<!-- Spinning icons (loading indicators) -->
+<Icon icon={faSpinner} spin />
+<Icon icon={faSpinner} pulse />
+
+<!-- With title for accessibility -->
+<Icon icon={faUser} title="User profile" />
+
+<!-- Rotated and scaled -->
+<Icon icon={faExclamation} rotate={45} scale={1.5} />
+
+<!-- Flipped icons -->
+<Icon icon={faUser} flip="horizontal" />
+<Icon icon={faUser} flip="vertical" />
+<Icon icon={faUser} flip="both" />
+
+<!-- Fixed width for alignment -->
+<div>
+  <Icon icon={faUser} fw /> User
+  <Icon icon={faCheck} fw /> Verified
+</div>
+
+<!-- Pulled left/right -->
+<p>
+  <Icon icon={faUser} pull="left" />
+  This text wraps around the icon
+</p>
+
+<!-- In buttons -->
+<button>
+  <Icon icon={faUser} class="mr-1" />
+  Profile
+</button>
+
+<!-- Duotone icons (if using duotone FontAwesome icons) -->
+<Icon
+  icon={myDuotoneIcon}
+  primaryColor="#3b82f6"
+  secondaryColor="#93c5fd"
+  primaryOpacity={1}
+  secondaryOpacity={0.4}
+/>
+
+<!-- Conditional visibility -->
+<Icon icon={faCheck} hidden={!isComplete} />
+<Icon icon={faSpinner} invisible={!isLoading} />
+```
+
+## Common Patterns
+
+### Loading Indicator
+```svelte
+<Icon icon={faSpinner} spin size="2x" />
+```
+
+### Status Icons with Colors
+```svelte
+{#if status === 'success'}
+  <Icon icon={faCheck} color="green" />
+{:else if status === 'error'}
+  <Icon icon={faExclamation} color="red" />
+{:else if status === 'warning'}
+  <Icon icon={faExclamation} color="orange" />
+{/if}
+```
+
+### Icon List (Aligned)
+```svelte
+<ul class="list-none">
+  <li><Icon icon={faUser} fw /> User Management</li>
+  <li><Icon icon={faCog} fw /> Settings</li>
+  <li><Icon icon={faChartBar} fw /> Analytics</li>
+</ul>
+```
+
+### Button with Icon
+```svelte
+<button>
+  <Icon icon={faSave} class="inline-block mr-1" />
+  Save Changes
+</button>
+```
+
+## Common Mistakes
+
+- ❌ Not importing the icon definition from FontAwesome
+  ✅ Correct: `import { faUser } from '@fortawesome/free-solid-svg-icons'`
+
+- ❌ Using string icon names instead of icon objects
+  ✅ Correct: `<Icon icon={faUser} />` not `<Icon icon="user" />`
+
+- ❌ Forgetting `fw` prop when aligning multiple icons
+  ✅ Correct: Use `fw` for consistent width in lists or navigation
+
+- ❌ Not providing `title` for accessibility
+  ✅ Correct: Add `title` prop for screen reader users when icon conveys meaning
+
+## Integration with Other Components
+
+Many library components accept `IFAProps` or `faProps` to include icons:
+- **DropDown** - `ddActions[].faProps`
+- **TabHeader** - `tabItems[].faProps`
+- **TabHref** - `tabHrefs[].faProps`
+- **MultiSelect** - `faProps` for selected items
+- **ButtonGroup** - `buttons[].faProps`
+
+Example with DropDown:
+```svelte
+<DropDown ddActions={[
+  { title: 'Edit', faProps: { icon: faEdit }, action: () => {} },
+  { title: 'Delete', faProps: { icon: faTrash }, action: () => {} }
+]} />
+```
+
+## Related Components
+
+- `IFAProps` interface in `Definitions.ts` defines all icon props
+- Used throughout the library for consistent icon support
+
+## FontAwesome Icons
+
+This component works with FontAwesome 6 icons:
+- `@fortawesome/free-solid-svg-icons` - Solid style icons
+- `@fortawesome/free-regular-svg-icons` - Regular style icons
+- `@fortawesome/free-brands-svg-icons` - Brand icons
+- Duotone icons (Pro license required)
+
+Install FontAwesome:
+```bash
+npm install @fortawesome/free-solid-svg-icons
+```

package/docs/Importer.md

@@ -0,0 +1,328 @@
+# Importer Component
+
+**Purpose:** Complete CSV import workflow with file upload, column mapping, validation, and data processing
+
+**When to Use:**
+- Import CSV data with predefined column definitions
+- Validate imported data with custom rules
+- Map CSV columns to database fields
+- Provide user-friendly import interface with error reporting
+
+## Key Props
+
+- `definition: TDataImportProcessorDefinition<T>` (required) - Import configuration with column definitions
+- `alternateNames?: Record<string, string[]>` ($bindable) - Column name mappings
+- `csvData?: string | null` ($bindable) - CSV file content
+- `arrayData?: string[][] | null` ($bindable) - Alternative: Array of arrays instead of CSV
+- `onprocess?: (results: TDataImportProcessorResult<T>[]) => Promise<boolean>` - Process validated rows
+- `description?: Snippet` - Custom description/instructions
+- `currentData?: object[]` - Existing data for download template
+
+## Component Flow
+
+The Importer component is a state machine with two phases:
+
+1. **ImporterLoad** (csvData/arrayData is null) - File selection and template download
+2. **ImporterAnalysis** (csvData/arrayData exists) - Column mapping, validation, and import
+
+## TDataImportProcessorDefinition Structure
+
+```typescript
+interface TDataImportProcessorDefinition<T> {
+  descriptionHTML?: string           // HTML description shown in upload phase
+  columns: Record<string, {
+    required?: boolean               // Column must be present
+    description?: string             // Column description
+    sampleData?: string | string[]   // Example data for template
+    validate?: (value: any) => string | null  // Custom validation function
+    transform?: (value: any) => any  // Transform imported value
+  }>
+}
+```
+
+## Usage Examples
+
+```svelte
+<script>
+  import { Importer } from 'intelliwaketssveltekitv25';
+  import type { TDataImportProcessorDefinition } from '@solidbasisventures/intelliwaketsfoundation';
+
+  // Define import structure
+  const userImportDefinition: TDataImportProcessorDefinition<any> = {
+    descriptionHTML: '<p>Import users from CSV file</p>',
+    columns: {
+      'Email': {
+        required: true,
+        description: 'User email address',
+        sampleData: 'user@example.com',
+        validate: (val) => val?.includes('@') ? null : 'Invalid email'
+      },
+      'Name': {
+        required: true,
+        description: 'Full name',
+        sampleData: 'John Doe'
+      },
+      'Age': {
+        required: false,
+        description: 'User age',
+        sampleData: '25',
+        validate: (val) => {
+          const age = parseInt(val);
+          return age > 0 && age < 150 ? null : 'Invalid age';
+        }
+      },
+      'Role': {
+        required: false,
+        description: 'User role',
+        sampleData: ['Admin', 'User', 'Guest']
+      }
+    }
+  };
+
+  let alternateNames = $state<Record<string, string[]> | null>(null);
+  let csvData = $state<string | null>(null);
+
+  async function handleImport(validRows) {
+    console.log('Importing', validRows.length, 'users');
+
+    // Process each validated row
+    for (const row of validRows) {
+      await createUser({
+        email: row.Email,
+        name: row.Name,
+        age: row.Age ? parseInt(row.Age) : null,
+        role: row.Role || 'User'
+      });
+    }
+
+    // Return true to clear the importer
+    return true;
+  }
+</script>
+
+<Importer
+  definition={userImportDefinition}
+  bind:alternateNames
+  bind:csvData
+  onprocess={handleImport}
+/>
+```
+
+### With Custom Description
+```svelte
+<Importer
+  definition={importDef}
+  bind:csvData
+  onprocess={handleImport}
+>
+  {#snippet description()}
+    <div class="bg-blue-50 p-4 mb-4 rounded">
+      <h3>Import Instructions</h3>
+      <ul>
+        <li>Use the template to ensure correct format</li>
+        <li>Email column is required</li>
+        <li>Maximum 1000 rows per import</li>
+      </ul>
+    </div>
+  {/snippet}
+</Importer>
+```
+
+### With Existing Data Download
+```svelte
+<script>
+  // Allows users to download current data as template
+  let existingUsers = [
+    { email: 'john@example.com', name: 'John', age: 30 },
+    { email: 'jane@example.com', name: 'Jane', age: 28 }
+  ];
+</script>
+
+<Importer
+  definition={userImportDefinition}
+  bind:csvData
+  currentData={existingUsers}
+  onprocess={handleImport}
+/>
+```
+
+### Product Import Example
+```svelte
+<script>
+  const productImportDef = {
+    columns: {
+      'SKU': {
+        required: true,
+        description: 'Product SKU',
+        sampleData: 'PROD-001'
+      },
+      'Name': {
+        required: true,
+        description: 'Product name',
+        sampleData: 'Widget Pro'
+      },
+      'Price': {
+        required: true,
+        description: 'Price in USD',
+        sampleData: '29.99',
+        validate: (val) => !isNaN(parseFloat(val)) ? null : 'Must be a number',
+        transform: (val) => parseFloat(val)
+      },
+      'Stock': {
+        required: false,
+        description: 'Quantity in stock',
+        sampleData: '100',
+        transform: (val) => parseInt(val) || 0
+      },
+      'Category': {
+        required: false,
+        description: 'Product category',
+        sampleData: ['Electronics', 'Clothing', 'Food']
+      }
+    }
+  };
+
+  async function importProducts(products) {
+    const result = await fetch('/api/products/import', {
+      method: 'POST',
+      body: JSON.stringify({ products }),
+      headers: { 'Content-Type': 'application/json' }
+    });
+
+    return result.ok;
+  }
+</script>
+
+<Importer
+  definition={productImportDef}
+  bind:csvData
+  onprocess={importProducts}
+/>
+```
+
+## Column Mapping
+
+The `alternateNames` prop enables flexible column mapping:
+```typescript
+// If CSV has "E-mail" but you expect "Email"
+alternateNames = {
+  "Email": ["E-mail", "email", "Email Address"]
+};
+```
+
+This is automatically managed by ImporterAnalysis when users manually map columns in the UI.
+
+## Process Flow
+
+1. **Upload Phase (ImporterLoad)**
+   - User clicks "Import CSV" to upload file
+   - OR downloads template (empty, with samples, or with current data)
+   - File content stored in `csvData` binding
+
+2. **Analysis Phase (ImporterAnalysis)**
+   - CSV parsed and validated
+   - Column headers mapped to definition
+   - Errors and warnings displayed
+   - User can filter by errors/warnings
+   - User can manually remap columns (if `alternateNames` bound)
+
+3. **Import Phase**
+   - User clicks "Import" button
+   - `onprocess` called with valid rows
+   - Return `true` to clear and reset
+   - Return `false` to keep data visible
+
+## Validation Results
+
+The component displays:
+- **Errors** (red) - Invalid data, missing required columns
+- **Warnings** (yellow) - Non-critical issues
+
+Users can filter the preview to show only rows with errors or warnings.
+
+## Common Patterns
+
+### With Modal
+```svelte
+<Modal bind:show={showImporter} title="Import Users">
+  <Importer
+    definition={userImportDef}
+    bind:csvData
+    onprocess={async (rows) => {
+      await handleImport(rows);
+      showImporter = false;
+      return true;
+    }}
+  />
+</Modal>
+```
+
+### With Progress Indicator
+```svelte
+<script>
+  let importing = $state(false);
+
+  async function handleImport(rows) {
+    importing = true;
+    try {
+      for (const row of rows) {
+        await importRow(row);
+      }
+      return true;
+    } finally {
+      importing = false;
+    }
+  }
+</script>
+
+{#if importing}
+  <div>Importing... Please wait</div>
+{/if}
+
+<Importer
+  definition={def}
+  bind:csvData
+  onprocess={handleImport}
+/>
+```
+
+## Common Mistakes
+
+- ❌ Not returning boolean from `onprocess`
+  ✅ Correct: Return `true` to clear, `false` to keep data
+
+- ❌ Not using `$bindable` for csvData and alternateNames
+  ✅ Correct: `bind:csvData` and `bind:alternateNames`
+
+- ❌ Complex validation logic that blocks UI
+  ✅ Correct: Keep validation functions fast and synchronous
+
+- ❌ Not providing required column definitions
+  ✅ Correct: Mark essential columns with `required: true`
+
+## Related Components
+
+- **ImporterLoad** - File upload and template download phase
+- **ImporterAnalysis** - Column mapping and validation phase
+- **DataImportProcessor** - Core processing logic from `@solidbasisventures/intelliwaketsfoundation`
+- **DropDown** - Used for column mapping
+- **Modal** - Often used as container
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `definition` | `TDataImportProcessorDefinition<T>` | (required) | Import configuration |
+| `alternateNames` | `Record<string, string[]>` | `null` | Column name mappings ($bindable) |
+| `csvData` | `string \| null` | `null` | CSV content ($bindable) |
+| `arrayData` | `string[][] \| null` | `null` | Alternative array format ($bindable) |
+| `onprocess` | `(rows) => Promise<boolean>` | - | Process validated rows |
+| `description` | `Snippet` | - | Custom instructions |
+| `currentData` | `object[]` | - | Existing data for template |
+
+## Performance Tips
+
+- Limit imports to reasonable size (e.g., 1000-5000 rows)
+- Use transform functions to normalize data during import
+- Implement server-side batch processing for large imports
+- Show progress feedback during `onprocess`