intelliwaketssveltekitv25 1.0.81 → 1.0.83

package/docs/ImporterAnalysis.md

@@ -0,0 +1,249 @@
+# ImporterAnalysis Component
+
+**Purpose:** CSV validation, column mapping, and error reporting phase of import workflow
+
+**When to Use:**
+- Rarely used directly (use **Importer** instead)
+- Advanced use cases requiring custom import flow
+- When you need granular control over validation display
+
+## Overview
+
+ImporterAnalysis is the second phase of the **Importer** component. It displays CSV data in a table format with:
+- Column header mapping (manual remapping if alternateNames provided)
+- Row-by-row validation with error/warning highlighting
+- Filter by errors or warnings
+- Import/Clear actions
+
+**Note:** Most applications should use the parent **Importer** component instead of ImporterAnalysis directly.
+
+## Key Props
+
+- `definition: TDataImportProcessorDefinition<T>` (required) - Import column definitions
+- `alternateNames?: Record<string, string[]>` ($bindable) - Column name mappings
+- `csvData?: string | null` ($bindable) - CSV content
+- `arrayData?: string[][] | null` ($bindable) - Array of arrays format
+- `onprocess?: (results: TDataImportProcessorResult<T>[]) => Promise<boolean>` - Process validated rows
+
+## Features
+
+### Error/Warning Filtering
+- Red "Errors" button - Shows rows with validation errors
+- Yellow "Warnings" button - Shows rows with warnings
+- Click to toggle filter, shows count
+
+### Column Remapping
+When `alternateNames` is bound, users can:
+- Click column header dropdown
+- Select target column from definition
+- Reset mapping
+- System remembers alternate names for future imports
+
+### Data Preview
+- Table view with all columns
+- Missing required columns highlighted in red
+- Error/warning messages shown in cells
+- Text alignment based on data type
+
+## Usage Examples
+
+### Direct Usage (Advanced)
+```svelte
+<script>
+  import { ImporterAnalysis } from 'intelliwaketssveltekitv25';
+
+  const definition = {
+    columns: {
+      'Name': { required: true },
+      'Email': { required: true }
+    }
+  };
+
+  let csvData = $state('Name,Email\nJohn,john@example.com');
+  let alternateNames = $state<Record<string, string[]> | null>({});
+
+  async function processData(validRows) {
+    console.log('Processing', validRows);
+    return true;
+  }
+</script>
+
+<ImporterAnalysis
+  {definition}
+  bind:alternateNames
+  bind:csvData
+  onprocess={processData}
+/>
+```
+
+### With Array Data
+```svelte
+<script>
+  let arrayData = $state([
+    ['Name', 'Email'],
+    ['John', 'john@example.com'],
+    ['Jane', 'jane@example.com']
+  ]);
+</script>
+
+<ImporterAnalysis
+  {definition}
+  bind:arrayData
+  onprocess={processData}
+/>
+```
+
+## Validation Display
+
+### Error Cells (Red Background)
+- Invalid data
+- Missing required column
+- Failed custom validation
+
+### Warning Cells (Yellow Background)
+- Non-critical issues
+- Data transformations applied
+
+### Gray Cells
+- Unmapped columns (not in definition)
+
+### Normal Cells
+- Valid data
+
+## Column Header Mapping
+
+Headers show:
+1. **Mapped column name** (from definition) - Bold
+2. **Original CSV header** (if different) - Normal weight
+
+Example:
+```
+Email Address        ← Definition column (bold)
+email_addr          ← CSV header (normal)
+```
+
+### Manual Remapping
+If alternateNames is bound:
+1. Click column header dropdown
+2. Select correct target column
+3. Mapping is saved in alternateNames
+4. Future imports remember the mapping
+
+## Actions
+
+### Import Button
+- Disabled if validation errors exist
+- Calls `onprocess` with valid rows only
+- Clears data if `onprocess` returns true
+
+### Clear Button
+- Resets csvData/arrayData to null
+- Returns to ImporterLoad phase (if using Importer)
+
+## DataImportProcessor
+
+The component uses `DataImportProcessor` from `@solidbasisventures/intelliwaketsfoundation`:
+```typescript
+const processor = new DataImportProcessor(definition.columns, {
+  alternateNames: alternateNames ?? {}
+});
+processor.populateFromCSV(csvData);
+// or
+processor.populateFromArray(arrayData);
+
+// Access results:
+processor.allErrors      // All error messages
+processor.allWarnings    // All warning messages
+processor.validRows      // Rows passing validation
+processor.analysisRows   // All rows with metadata
+processor.isValid        // True if no errors
+```
+
+## Common Patterns
+
+### Custom Import Flow
+```svelte
+<script>
+  let step = $state<'upload' | 'analyze' | 'complete'>('upload');
+  let csvData = $state(null);
+</script>
+
+{#if step === 'upload'}
+  <ImporterLoad bind:csvData {definition} />
+  <button onclick={() => step = 'analyze'}>
+    Analyze
+  </button>
+{:else if step === 'analyze'}
+  <ImporterAnalysis
+    bind:csvData
+    {definition}
+    onprocess={async (rows) => {
+      await import(rows);
+      step = 'complete';
+      return true;
+    }}
+  />
+{:else}
+  <div>Import complete!</div>
+{/if}
+```
+
+### Programmatic Validation
+```svelte
+<script>
+  import { DataImportProcessor } from '@solidbasisventures/intelliwaketsfoundation';
+
+  function validateCSV(csv: string) {
+    const processor = new DataImportProcessor(definition.columns);
+    processor.populateFromCSV(csv);
+
+    if (!processor.isValid) {
+      console.error('Validation failed:', processor.allErrors);
+      return false;
+    }
+
+    return processor.validRows;
+  }
+</script>
+```
+
+## Common Mistakes
+
+- ❌ Using ImporterAnalysis without providing csvData or arrayData
+  ✅ Correct: Ensure data is bound and populated
+
+- ❌ Not providing `onprocess` callback
+  ✅ Correct: Always provide onprocess to handle validated rows
+
+- ❌ Forgetting that `onprocess` should return boolean
+  ✅ Correct: Return true to clear, false to keep data
+
+- ❌ Using this component when Importer would suffice
+  ✅ Correct: Use Importer for standard workflows
+
+## Related Components
+
+- **Importer** - Complete import workflow (recommended)
+- **ImporterLoad** - File upload and template download phase
+- **DropDown** - Used for column mapping dropdown
+- **DataImportProcessor** - Core validation logic
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `definition` | `TDataImportProcessorDefinition<T>` | (required) | Column definitions |
+| `alternateNames` | `Record<string, string[]>` | `null` | Column mappings ($bindable) |
+| `csvData` | `string \| null` | `null` | CSV content ($bindable) |
+| `arrayData` | `string[][] \| null` | `null` | Array format ($bindable) |
+| `onprocess` | `(rows) => Promise<boolean>` | - | Process valid rows |
+
+## Styling
+
+Uses standard table classes:
+- `table` - Base table styles
+- `tableBordered` - Cell borders
+- `tableSticky` - Sticky header
+- `data-color-light="danger"` - Error highlighting
+- `data-color-light="warning"` - Warning highlighting
+- `data-color-light="gray"` - Unmapped columns

package/docs/ImporterLoad.md

@@ -0,0 +1,288 @@
+# ImporterLoad Component
+
+**Purpose:** File upload and CSV template download phase of import workflow
+
+**When to Use:**
+- Rarely used directly (use **Importer** instead)
+- Advanced use cases requiring custom import UI
+- When building multi-step import wizards
+
+## Overview
+
+ImporterLoad is the first phase of the **Importer** component. It provides:
+- CSV file upload via button or drag-and-drop
+- Download empty template
+- Download template with sample data
+- Download current data as template
+
+**Note:** Most applications should use the parent **Importer** component instead of ImporterLoad directly.
+
+## Key Props
+
+- `definition: TDataImportProcessorDefinition<T>` (required) - Import column definitions
+- `csvData?: string | null` ($bindable) - CSV content (set when file uploaded)
+- `description?: Snippet` - Custom description/instructions
+- `currentData?: object[]` - Existing data for "Download Current Data" option
+- `templateName?: string` (default: 'Template') - Filename prefix for downloads
+- `fileAccept?: string` (default: '.csv') - Accepted file types
+
+## Features
+
+### File Upload
+- **Button upload** - Click "Import CSV" button to select file
+- **Drag-and-drop** - Drag CSV file onto component area
+- Visual feedback on drag (blue background)
+- File content stored in `csvData` binding
+
+### Template Downloads
+Three template download options:
+
+1. **Download Empty Template**
+   - CSV with just column headers
+   - Filename: `{templateName}_YYYY-MM-DD_HH-mm-ss.csv`
+
+2. **Download with Sample Data**
+   - Headers + description row + sample data row
+   - Only shown if columns have `description` or `sampleData`
+
+3. **Download Current Data**
+   - Current data exported as CSV template
+   - Only shown if `currentData` prop provided
+   - Helps users see expected format
+
+## Usage Examples
+
+### Direct Usage (Advanced)
+```svelte
+<script>
+  import { ImporterLoad } from 'intelliwaketssveltekitv25';
+
+  const definition = {
+    descriptionHTML: '<p>Upload CSV with user data</p>',
+    columns: {
+      'Name': {
+        required: true,
+        description: 'Full name',
+        sampleData: 'John Doe'
+      },
+      'Email': {
+        required: true,
+        description: 'Email address',
+        sampleData: 'john@example.com'
+      }
+    }
+  };
+
+  let csvData = $state<string | null>(null);
+</script>
+
+<!-- Upload phase -->
+{#if csvData === null}
+  <ImporterLoad
+    {definition}
+    bind:csvData
+  />
+{:else}
+  <!-- Process csvData or show ImporterAnalysis -->
+{/if}
+```
+
+### With Custom Description
+```svelte
+<ImporterLoad
+  {definition}
+  bind:csvData
+>
+  {#snippet description()}
+    <div class="alert alert-info">
+      <h4>Before uploading:</h4>
+      <ul>
+        <li>Ensure email addresses are valid</li>
+        <li>Names should be in "First Last" format</li>
+        <li>Maximum 500 rows per import</li>
+      </ul>
+    </div>
+  {/snippet}
+</ImporterLoad>
+```
+
+### With Current Data Download
+```svelte
+<script>
+  let existingUsers = [
+    { Name: 'John Doe', Email: 'john@example.com', Age: 30 },
+    { Name: 'Jane Smith', Email: 'jane@example.com', Age: 28 }
+  ];
+</script>
+
+<ImporterLoad
+  {definition}
+  bind:csvData
+  currentData={existingUsers}
+  templateName="Users"
+/>
+<!-- Users can download existing data as reference -->
+```
+
+### Custom File Types
+```svelte
+<ImporterLoad
+  {definition}
+  bind:csvData
+  fileAccept=".csv,.txt"
+/>
+```
+
+## Template Generation
+
+### Empty Template
+```csv
+Name,Email,Age
+```
+
+### With Sample Data
+```csv
+Name,Email,Age
+Full name,Email address,User age
+John Doe,john@example.com,25
+```
+
+### Current Data
+```csv
+Name,Email,Age
+John Doe,john@example.com,30
+Jane Smith,jane@example.com,28
+```
+
+## Drag-and-Drop
+
+Visual feedback during drag:
+- Component background turns blue (`bg-blue-50`)
+- Drop zone covers entire component
+- Accepts single file only
+- File content immediately loaded into `csvData`
+
+## Column Definition Display
+
+The component shows a table with:
+- **Header row:** Column names from definition
+- **Description row:** If any column has `description` (optional)
+- **Sample row:** If any column has `sampleData` (optional)
+
+## Common Patterns
+
+### Multi-Step Import
+```svelte
+<script>
+  let csvData = $state(null);
+  let step = $state<'upload' | 'validate'>('upload');
+</script>
+
+{#if step === 'upload'}
+  <ImporterLoad
+    {definition}
+    bind:csvData
+  />
+  <button
+    disabled={!csvData}
+    onclick={() => step = 'validate'}
+  >
+    Next
+  </button>
+{:else}
+  <ImporterAnalysis
+    {definition}
+    bind:csvData
+    onprocess={handleImport}
+  />
+{/if}
+```
+
+### With Progress Indicator
+```svelte
+<script>
+  let uploading = $state(false);
+
+  $effect(() => {
+    if (csvData !== null) {
+      uploading = false;
+    }
+  });
+</script>
+
+{#if uploading}
+  <div>Processing file...</div>
+{/if}
+
+<ImporterLoad
+  {definition}
+  bind:csvData
+/>
+```
+
+### Reset Upload
+```svelte
+<script>
+  let csvData = $state(null);
+</script>
+
+<ImporterLoad {definition} bind:csvData />
+
+{#if csvData}
+  <button onclick={() => csvData = null}>
+    Reset
+  </button>
+{/if}
+```
+
+## Common Mistakes
+
+- ❌ Not binding `csvData` prop
+  ✅ Correct: Use `bind:csvData` for two-way binding
+
+- ❌ Not checking if csvData exists before processing
+  ✅ Correct: Check `if (csvData !== null)` before analysis
+
+- ❌ Using complex objects in `currentData` that don't match definition
+  ✅ Correct: Ensure currentData keys match column definitions
+
+- ❌ Not providing sample data for complex formats
+  ✅ Correct: Add `sampleData` to help users understand format
+
+## Related Components
+
+- **Importer** - Complete import workflow (recommended)
+- **ImporterAnalysis** - Validation and processing phase
+- **DropDown** - Used for template download options
+- **DisplayHTML** - Renders definition.descriptionHTML
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `definition` | `TDataImportProcessorDefinition<T>` | (required) | Column definitions |
+| `csvData` | `string \| null` | `null` | CSV content ($bindable) |
+| `description` | `Snippet` | - | Custom instructions |
+| `currentData` | `object[]` | - | Data for template download |
+| `templateName` | `string` | `'Template'` | Download filename prefix |
+| `fileAccept` | `string` | `'.csv'` | Accepted file extensions |
+
+## Utility Functions
+
+Uses these functions from the library:
+- **DataToCSVExport(filename, data)** - Generate and download CSV
+- **YYYY_MM_DD_HH_mm_ss(date)** - Format timestamp for filename
+
+## Styling
+
+- Drag-and-drop zone: `bg-blue-50` on dragover
+- Upload button: Standard button styles with upload icon (SVG)
+- Table: Uses `table`, `tableBordered`, `tableSticky` classes
+- Icons: Inline SVG for upload/download icons
+
+## Accessibility
+
+- File input hidden, triggered by button click
+- Drag-and-drop zone marked with `role="region"` and `aria-label`
+- Upload button has descriptive SVG icon
+- All interactive elements keyboard accessible

package/docs/InputNumber.md

@@ -0,0 +1,159 @@
+# InputNumber Component
+
+**Replaces:** `<input type="number">` for ALL numeric inputs
+
+**Purpose:** Formatted numeric input with automatic currency, percentage, and decimal handling
+
+**When to Use:**
+- Currency amounts (prices, costs, payments)
+- Percentages (tax rates, discounts, progress)
+- Decimal numbers (measurements, weights, quantities)
+- Integer counts with min/max constraints
+- Any numeric data entry where formatting matters
+
+## Key Props
+
+- `value?: number | null` ($bindable) - Current numeric value, use `bind:value`
+- `currency?: boolean` - Format as currency (adds $ prefix, 2 decimal places)
+- `percent?: boolean` - Format as percentage (adds % suffix, stores as decimal 0-1, displays as 0-100)
+- `fixedDecimals?: number` - Force exact number of decimal places
+- `minDecimals?: number` - Minimum decimal places to show
+- `maxDecimals?: number` - Maximum decimal places allowed
+- `min?: number` - Minimum allowed value (enforced on input)
+- `max?: number` - Maximum allowed value (enforced on input)
+- `allowNegative?: boolean` - Allow negative numbers (default: false)
+- `zeroBlank?: boolean` - Display empty string instead of 0
+- `zeroDash?: boolean` - Display "-" instead of 0
+- `nullBlank?: boolean` - Display empty string for null values
+- `nullDash?: boolean` - Display "-" for null values
+- `prefix?: string` - Custom prefix (overrides currency $)
+- `suffix?: string` - Custom suffix (overrides percent %)
+- `delayChange?: boolean | number | 'blur'` - Delay before updating bound value
+  - `true`: 1500ms delay
+  - `number`: Custom milliseconds delay
+  - `'blur'`: Update only on blur event
+- `widthNumbers?: number` - Set input width based on number of digits
+- `class?: string` - Additional CSS classes for wrapper div
+- `inputClass?: string` - CSS classes for the input element itself
+- `onchange?: (value: number | null) => void` - Callback when value changes
+- Standard HTML input props: `disabled`, `readonly`, `required`, `name`, `placeholder`, `id`, etc.
+
+**TypeScript Type:** `TInputNumberAttributes` (extends standard input attributes)
+
+## Usage Examples
+
+```svelte
+<script>
+  import { InputNumber } from 'intelliwaketssveltekitv25';
+  let price = $state(29.99);
+  let taxRate = $state(0.08); // 8% stored as 0.08, displays as 8
+  let quantity = $state(1);
+  let weight = $state(null);
+</script>
+
+<!-- Currency input -->
+<label>
+  Price:
+  <InputNumber bind:value={price} currency required />
+</label>
+<!-- Displays: $29.99 -->
+
+<!-- Percentage input -->
+<label>
+  Tax Rate:
+  <InputNumber bind:value={taxRate} percent />
+</label>
+<!-- Displays: 8% (user enters 8, stored as 0.08) -->
+
+<!-- Integer quantity with constraints -->
+<label>
+  Quantity:
+  <InputNumber bind:value={quantity} fixedDecimals={0} min={1} max={999} />
+</label>
+
+<!-- Decimal with custom suffix -->
+<label>
+  Weight:
+  <InputNumber bind:value={weight} suffix="kg" maxDecimals={2} zeroBlank />
+</label>
+
+<!-- With delayed change (for expensive calculations) -->
+<InputNumber
+  bind:value={searchAmount}
+  currency
+  delayChange={true}
+  placeholder="Filter by amount..."
+/>
+<!-- Value updates 1.5 seconds after user stops typing -->
+
+<!-- Update only on blur -->
+<InputNumber
+  bind:value={finalTotal}
+  currency
+  delayChange="blur"
+/>
+
+<!-- Readonly display -->
+<InputNumber value={calculatedTotal} currency readonly />
+
+<!-- Allow negative numbers -->
+<InputNumber
+  bind:value={profitLoss}
+  currency
+  allowNegative
+  zeroDash
+/>
+
+<!-- Width based on digit count -->
+<InputNumber
+  bind:value={zipCode}
+  fixedDecimals={0}
+  widthNumbers={5}
+/>
+
+<!-- With change handler -->
+<InputNumber
+  bind:value={discount}
+  percent
+  onchange={(val) => {
+    console.log('Discount changed to:', val);
+    recalculateTotal();
+  }}
+/>
+```
+
+## Common Mistakes
+
+- ❌ Using `<input type="number">` for currency: `<input type="number" step="0.01">`
+  ✅ Correct: `<InputNumber currency bind:value={amount} />`
+
+- ❌ Storing percentages as whole numbers (8) instead of decimals (0.08)
+  ✅ Correct: Store as decimal (0.08), use `percent` prop to display as 8%
+
+- ❌ Not using `bind:value`: `<InputNumber value={x} />`
+  ✅ Correct: `<InputNumber bind:value={x} />` (for two-way binding)
+
+- ❌ Expecting immediate updates without considering `delayChange`
+  ✅ Correct: Use `delayChange="blur"` or `delayChange={false}` for immediate updates
+
+- ❌ Using both `currency` and `percent` props together
+  ✅ Correct: Use only one formatting option at a time
+
+## Props Combinations
+
+- **Currency:** `currency` (auto-adds $ prefix, 2 decimals)
+- **Percentage:** `percent` (auto-adds % suffix, multiplies display by 100)
+- **Integer:** `fixedDecimals={0}`
+- **Range validation:** `min={x} max={y}`
+- **Performance optimization:** `delayChange={true}` or `delayChange={500}` (ms) or `delayChange="blur"`
+- **Zero handling:** `zeroBlank` or `zeroDash`
+- **Null handling:** `nullBlank` or `nullDash`
+
+## Related Components
+
+- `InputNumberScroll` - Numeric input with scroll wheel adjustment support
+- `NumberFormat` - Display-only formatted number component
+
+## Storybook
+
+See `Components/InputNumber` stories