intelliwaketssveltekitv25 1.0.81 → 1.0.83

package/docs/Functions.md

@@ -0,0 +1,796 @@
+# Functions - Utility Functions & Svelte Actions
+
+**Module:** `Functions.ts`
+**Category:** Core Utilities
+**Use Cases:** Browser utilities, keyboard handling, Svelte use: actions, form enhancement, navigation, data export
+
+## Overview
+
+The `Functions` module provides 20+ utility functions and Svelte actions for common browser operations, keyboard navigation, form enhancement, and data manipulation. It includes keyboard constants, GPS capture, clipboard operations, file downloads, and specialized Svelte use: actions for interactive behavior.
+
+## Module Structure
+
+### 1. Keyboard Constants
+### 2. Browser Utilities
+### 3. Data Export Functions
+### 4. Svelte Use Actions
+### 5. Type Definitions
+
+---
+
+## 1. Keyboard Constants
+
+Pre-defined key codes and key strings for event handling.
+
+### Key Code Constants (Legacy)
+
+```typescript
+export const KEY_UP_ARROW = 38
+export const KEY_DOWN_ARROW = 40
+export const KEY_LEFT_ARROW = 37
+export const KEY_RIGHT_ARROW = 39
+export const KEY_SPACE = 32
+export const KEY_ENTER = 13
+export const KEY_TAB = 9
+export const KEY_BACKSPACE = 8
+export const KEY_ESCAPE = 27
+```
+
+### Key String Constants (Modern)
+
+```typescript
+export const KEY_STRING_ENTER = 'Enter'
+export const KEY_STRING_SPACE = 'Space'
+export const KEY_STRING_DOWN_ARROW = 'ArrowDown'
+export const KEY_STRING_UP_ARROW = 'ArrowUp'
+export const KEY_STRING_LEFT_ARROW = 'ArrowLeft'
+export const KEY_STRING_RIGHT_ARROW = 'ArrowRight'
+export const KEY_STRING_TAB = 'Tab'
+export const KEY_STRING_BACKSPACE = 'Backspace'
+export const KEY_STRING_ESCAPE = 'Escape'
+```
+
+### IsMetaKey(e: KeyboardEvent): boolean
+
+Checks if a keyboard event is a meta/control key (Ctrl, Alt, Meta, or navigation keys).
+
+```svelte
+<script>
+  import { IsMetaKey } from 'intelliwaketssveltekitv25'
+
+  function handleKeyDown(e: KeyboardEvent) {
+    if (!IsMetaKey(e)) {
+      // Handle regular character input
+    }
+  }
+</script>
+```
+
+**Returns:** `true` if Ctrl, Alt, Meta, or navigation key (arrows, Enter, Tab, Escape, Backspace)
+
+---
+
+## 2. Browser Utilities
+
+### CaptureGPS(options?: PositionOptions): Promise<GeolocationPosition | null>
+
+Captures the device's GPS location using the Geolocation API.
+
+```svelte
+<script>
+  import { CaptureGPS } from 'intelliwaketssveltekitv25'
+
+  async function getLocation() {
+    const position = await CaptureGPS({ timeout: 5000 })
+    if (position) {
+      console.log('Lat:', position.coords.latitude)
+      console.log('Lng:', position.coords.longitude)
+    }
+  }
+</script>
+```
+
+**Parameters:**
+- `options` - Standard PositionOptions (timeout defaults to 10s, maximumAge to 15min)
+
+**Returns:** `GeolocationPosition` or `null` if unavailable/denied
+
+---
+
+### CopyRefToClipboard(ref: HTMLElement, tryFormatted?: boolean): boolean
+
+Copies an HTML element's content to the clipboard with optional formatting preservation.
+
+```svelte
+<script>
+  import { CopyRefToClipboard } from 'intelliwaketssveltekitv25'
+
+  let contentRef: HTMLElement
+
+  function copyContent() {
+    const success = CopyRefToClipboard(contentRef, true)
+    if (success) alert('Copied!')
+  }
+</script>
+
+<div bind:this={contentRef}>
+  <p>Content to copy</p>
+  <span class="noCopy">This won't be copied</span>
+  <span class="onlyCopy">Only visible when copying</span>
+</div>
+```
+
+**Special Classes:**
+- `.noCopy` - Elements excluded from clipboard
+- `.onlyCopy` - Elements only visible during copy operation
+
+**Parameters:**
+- `ref` - HTML element to copy
+- `tryFormatted` - Preserve formatting (default: true)
+
+**Returns:** `true` if successful
+
+---
+
+### setSearchParam(key: string, value: string | number | null): Promise<void>
+
+Updates a URL search parameter and navigates without page reload.
+
+```svelte
+<script>
+  import { setSearchParam } from 'intelliwaketssveltekitv25'
+
+  function filterByCategory(category: string) {
+    setSearchParam('category', category) // ?category=books
+  }
+
+  function clearFilter() {
+    setSearchParam('category', null) // Removes ?category
+  }
+</script>
+```
+
+**Parameters:**
+- `key` - Search parameter name
+- `value` - Value to set (null/undefined removes the param)
+
+**Navigation:** Uses SvelteKit's `goto()` with `replaceState: true`
+
+---
+
+### IsMobileOrTablet(): boolean
+
+Detects if the current device is mobile or tablet based on user agent.
+
+```svelte
+<script>
+  import { IsMobileOrTablet } from 'intelliwaketssveltekitv25'
+
+  const isMobile = IsMobileOrTablet()
+</script>
+
+{#if isMobile}
+  <MobileNav />
+{:else}
+  <DesktopNav />
+{/if}
+```
+
+**Detection:** Matches user agents for Android, iOS, BlackBerry, Opera Mini, etc.
+
+---
+
+### DoIDsMatch(a: any, b: any): boolean
+
+Compares two objects by value or their `id` properties.
+
+```typescript
+import { DoIDsMatch } from 'intelliwaketssveltekitv25'
+
+DoIDsMatch(5, 5) // true
+DoIDsMatch({ id: 5 }, 5) // true
+DoIDsMatch({ id: 5 }, { id: 5 }) // true
+```
+
+**Use Case:** Comparing records from different sources with consistent ID matching
+
+---
+
+### ErrorMessageStack(e: any): TErrorMessageStack
+
+Extracts error message and stack trace from various error formats.
+
+```typescript
+import { ErrorMessageStack } from 'intelliwaketssveltekitv25'
+
+try {
+  throw new Error('Failed')
+} catch (e) {
+  const { message, stack } = ErrorMessageStack(e)
+  console.error(message) // "Failed"
+  console.log(stack) // Full stack trace
+}
+```
+
+**Returns:** `{ message: string, stack: string }`
+
+---
+
+### PageAdvanceSize(pageCount: number): number | null
+
+Calculates optimal pagination jump size for large page counts.
+
+```typescript
+import { PageAdvanceSize } from 'intelliwaketssveltekitv25'
+
+PageAdvanceSize(500) // 10 (jump by 10 pages)
+PageAdvanceSize(5000) // 100 (jump by 100 pages)
+PageAdvanceSize(30) // null (no jump needed)
+```
+
+**Logic:** Returns powers of 10 based on magnitude (e.g., 10 for hundreds, 100 for thousands)
+
+---
+
+## 3. Data Export Functions
+
+### DownloadBase64Data(fileName: string, base64: string): void
+
+Downloads base64-encoded data as a file.
+
+```typescript
+import { DownloadBase64Data } from 'intelliwaketssveltekitv25'
+
+const base64Image = 'data:image/png;base64,iVBORw0KG...'
+DownloadBase64Data('chart.png', base64Image)
+```
+
+---
+
+### DownloadString(filename: string, text: string): void
+
+Downloads a string as a text file.
+
+```typescript
+import { DownloadString } from 'intelliwaketssveltekitv25'
+
+const csvData = 'Name,Age\nJohn,30\nJane,25'
+DownloadString('users.csv', csvData)
+```
+
+---
+
+### DownloadURL(url: string, filename?: string): void
+
+Triggers download from a URL.
+
+```typescript
+import { DownloadURL } from 'intelliwaketssveltekitv25'
+
+DownloadURL('/api/report.pdf', 'monthly-report.pdf')
+```
+
+---
+
+### TableIDToExcel(tableID: string, fileName?: string, appendDateTime?: boolean): void
+
+Exports an HTML table to Excel format.
+
+```svelte
+<script>
+  import { TableIDToExcel } from 'intelliwaketssveltekitv25'
+</script>
+
+<table id="dataTable">
+  <tr><th>Name</th><th>Value</th></tr>
+  <tr><td>Item 1</td><td>100</td></tr>
+</table>
+
+<button onclick={() => TableIDToExcel('dataTable', 'export')}>
+  Export to Excel
+</button>
+```
+
+**Parameters:**
+- `tableID` - HTML table element ID
+- `fileName` - Output filename (defaults to tableID)
+- `appendDateTime` - Add timestamp to filename (default: true)
+
+**Output Format:** `.xls` file with timestamp
+
+---
+
+## 4. Svelte Use Actions
+
+### autoFocus(el: HTMLElement, enabled?: boolean)
+
+Automatically focuses an element when mounted or when `enabled` changes.
+
+```svelte
+<script>
+  import { autoFocus } from 'intelliwaketssveltekitv25'
+
+  let showInput = $state(false)
+</script>
+
+{#if showInput}
+  <input use:autoFocus placeholder="Auto-focused" />
+{/if}
+```
+
+**With Conditional Enabling:**
+
+```svelte
+<input use:autoFocus={isEditMode} />
+```
+
+**Features:**
+- Waits for DOM tick and animation frame
+- Cancels if element detaches
+- Respects modal/transition timing
+
+---
+
+### autoGrow(node: HTMLTextAreaElement, value?: string | null)
+
+Auto-expands textarea height to fit content, with manual resize detection.
+
+```svelte
+<script>
+  import { autoGrow } from 'intelliwaketssveltekitv25'
+
+  let text = $state('')
+</script>
+
+<textarea use:autoGrow bind:value={text} />
+```
+
+**Features:**
+- Dynamically adjusts height based on content
+- Detects manual user resize and locks auto-grow
+- Sets `data-autogrow-locked="true"` when manually resized
+- Prevents scrollbars during auto-growth
+
+**Manual Resize Detection:** Once user manually resizes, auto-grow stops permanently
+
+---
+
+### scrollToBottom(el: HTMLElement, toggleUpdate?: any)
+
+Scrolls element to bottom on mount or when `toggleUpdate` changes.
+
+```svelte
+<script>
+  import { scrollToBottom } from 'intelliwaketssveltekitv25'
+
+  let messages = $state([])
+</script>
+
+<div use:scrollToBottom={messages.length} class="h-96 overflow-y-auto">
+  {#each messages as msg}
+    <p>{msg}</p>
+  {/each}
+</div>
+```
+
+**Use Case:** Chat interfaces, log viewers, real-time feeds
+
+---
+
+### upDownArrows(el: HTMLElement, options?: TUpDownArrowOptions)
+
+Adds Up/Down arrow key navigation between elements with ID pattern `{id}_{field}`.
+
+```svelte
+<script>
+  import { upDownArrows } from 'intelliwaketssveltekitv25'
+
+  const items = [{ id: 1 }, { id: 2 }, { id: 3 }]
+</script>
+
+{#each items as item}
+  <input
+    id="{item.id}_name"
+    use:upDownArrows={{ list: items }}
+  />
+{/each}
+```
+
+**Options:**
+```typescript
+type TUpDownArrowOptions = {
+  preID?: number | string       // Override previous ID
+  postID?: number | string      // Override next ID
+  list?: { id: number }[]       // Auto-derive pre/post from list
+  enterDown?: boolean           // Treat Enter as Down arrow
+}
+```
+
+**Behavior:**
+- ↑ focuses previous element (wraps to end)
+- ↓ focuses next element (wraps to start)
+- Enter acts as ↓ if `enterDown: true`
+
+**ID Pattern Required:** Element IDs must be `{id}_{fieldName}` (e.g., `1_name`, `2_name`)
+
+---
+
+### nextPrevArrows(el: HTMLElement, options?: TNextPrevArrowsOptions)
+
+Adds Left/Right arrow key navigation between fields with ID pattern `{id}_{field}`.
+
+```svelte
+<script>
+  import { nextPrevArrows } from 'intelliwaketssveltekitv25'
+
+  const fields = ['name', 'email', 'phone']
+  const items = [{ id: 1 }, { id: 2 }]
+</script>
+
+{#each items as item}
+  {#each fields as field}
+    <input
+      id="{item.id}_{field}"
+      use:nextPrevArrows={{ fieldList: fields }}
+    />
+  {/each}
+{/each}
+```
+
+**Options:**
+```typescript
+type TNextPrevArrowsOptions = {
+  preField?: string           // Override previous field
+  postField?: string          // Override next field
+  fieldList?: string[]        // Auto-derive pre/post from list
+}
+```
+
+**Behavior:**
+- ← focuses previous field (wraps to end)
+- → focuses next field (wraps to start)
+
+**Use Case:** Spreadsheet-like navigation, grid editing
+
+---
+
+### textAreaAltEnter(el: HTMLTextAreaElement)
+
+Enables Alt+Enter to insert line breaks while Enter submits the form.
+
+```svelte
+<script>
+  import { textAreaAltEnter } from 'intelliwaketssveltekitv25'
+</script>
+
+<form onsubmit={handleSubmit}>
+  <textarea
+    use:textAreaAltEnter
+    placeholder="Enter submits, Alt+Enter adds line"
+  />
+</form>
+```
+
+**Behavior:**
+- **Enter** - Submits parent form
+- **Alt+Enter** - Inserts `\r\n` at cursor
+
+**Use Case:** Chat interfaces, comment forms
+
+---
+
+### selectOnFocus(el: HTMLInputElement | HTMLTextAreaElement)
+
+Selects all text when input gains focus.
+
+```svelte
+<script>
+  import { selectOnFocus } from 'intelliwaketssveltekitv25'
+</script>
+
+<input use:selectOnFocus value="Click to select all" />
+```
+
+**Timing:** Waits 50ms after focus to ensure value is rendered
+
+**Use Case:** Forms where users typically replace entire value
+
+---
+
+### clickSubmitOnChange(el: HTMLElement)
+
+Auto-submits form when any child input changes.
+
+```svelte
+<script>
+  import { clickSubmitOnChange } from 'intelliwaketssveltekitv25'
+</script>
+
+<form use:clickSubmitOnChange>
+  <select>
+    <option>Option 1</option>
+    <option>Option 2</option>
+  </select>
+  <button type="submit">Submit</button>
+</form>
+```
+
+**Behavior:**
+- Clicks `<button type="submit">` or first `<button>` in form
+- Falls back to `requestSubmit()` if no button found
+- Prevents double-submission on Enter key
+
+---
+
+### clickSubmitOnFocusOut(el: HTMLElement)
+
+Auto-submits form when focus leaves the form.
+
+```svelte
+<form use:clickSubmitOnFocusOut>
+  <input placeholder="Auto-saves on blur" />
+</form>
+```
+
+**Use Case:** Inline editing, auto-save forms
+
+---
+
+## 5. Type Definitions
+
+### TUpDownArrowOptions
+
+```typescript
+type TUpDownArrowOptions = {
+  preID?: number | string | null
+  postID?: number | string | null
+  list?: ({ id: number } & Record<string, any>)[]
+  enterDown?: boolean
+}
+```
+
+---
+
+### TNextPrevArrowsOptions
+
+```typescript
+type TNextPrevArrowsOptions = {
+  preField?: string | null
+  postField?: string | null
+  fieldList?: string[]
+}
+```
+
+---
+
+### TErrorMessageStack
+
+```typescript
+type TErrorMessageStack = {
+  message: string
+  stack: string
+}
+```
+
+---
+
+### TInputNumberAttributes
+
+```typescript
+type TInputNumberAttributes = Omit<
+  HTMLInputAttributes,
+  'value' | 'this' | 'onchange' | 'use'
+> & {
+  value: number | null
+  onchange?: (value: number | null) => void
+  widthNumbers?: number
+  inputClass?: string
+  allowNegative?: boolean
+  delayChange?: boolean | number | 'blur'
+  use?: ActionArray
+  thisRef?: HTMLInputElement
+} & TNumberStringOptions
+```
+
+---
+
+### HandleKeyDownNumerics(event: KeyboardEvent, allowDecimals?: boolean, allowNegative?: boolean)
+
+Validates numeric keyboard input, preventing non-numeric characters.
+
+```svelte
+<script>
+  import { HandleKeyDownNumerics } from 'intelliwaketssveltekitv25'
+</script>
+
+<input
+  type="text"
+  onkeydown={(e) => HandleKeyDownNumerics(e, true, false)}
+  placeholder="Positive decimals only"
+/>
+```
+
+**Parameters:**
+- `allowDecimals` - Allow `.` and `,` (default: true)
+- `allowNegative` - Allow `-` (default: false)
+
+**Allowed Keys:** Digits, navigation keys, Ctrl+A/C/V/X, decimal/negative if enabled
+
+---
+
+## Common Patterns
+
+### Multi-Row Grid Navigation
+
+Combine `upDownArrows` and `nextPrevArrows` for full grid navigation:
+
+```svelte
+<script>
+  import { upDownArrows, nextPrevArrows } from 'intelliwaketssveltekitv25'
+  import { useActions } from 'intelliwaketssveltekitv25'
+
+  const rows = [{ id: 1 }, { id: 2 }, { id: 3 }]
+  const fields = ['name', 'email', 'phone']
+</script>
+
+{#each rows as row}
+  {#each fields as field}
+    <input
+      id="{row.id}_{field}"
+      use:useActions={[
+        [upDownArrows, { list: rows }],
+        [nextPrevArrows, { fieldList: fields }]
+      ]}
+    />
+  {/each}
+{/each}
+```
+
+**Result:** Arrow keys navigate in all directions with wraparound
+
+---
+
+### Auto-Save Form with Focus Tracking
+
+```svelte
+<script>
+  import { clickSubmitOnFocusOut, autoFocus } from 'intelliwaketssveltekitv25'
+
+  let isEditing = $state(false)
+</script>
+
+{#if isEditing}
+  <form use:clickSubmitOnFocusOut>
+    <input use:autoFocus />
+  </form>
+{/if}
+```
+
+---
+
+### Export with Loading State
+
+```svelte
+<script>
+  import { TableIDToExcel } from 'intelliwaketssveltekitv25'
+
+  let isExporting = $state(false)
+
+  async function exportData() {
+    isExporting = true
+    await tick() // Ensure table is rendered
+    TableIDToExcel('reportTable', 'Q4-Report')
+    isExporting = false
+  }
+</script>
+
+<table id="reportTable">...</table>
+<button onclick={exportData} disabled={isExporting}>
+  {isExporting ? 'Exporting...' : 'Export to Excel'}
+</button>
+```
+
+---
+
+## Best Practices
+
+### 1. Action Composition
+
+Use `useActions` for multiple actions on one element:
+
+```svelte
+<textarea
+  use:useActions={[
+    [autoGrow],
+    [textAreaAltEnter],
+    [selectOnFocus]
+  ]}
+/>
+```
+
+---
+
+### 2. Error Handling
+
+Always handle promise rejections with GPS and navigation:
+
+```typescript
+const position = await CaptureGPS().catch(() => null)
+if (!position) {
+  // Handle denial/error
+}
+```
+
+---
+
+### 3. ID Patterns
+
+For navigation actions, use consistent ID patterns:
+
+```svelte
+<!-- Good: {id}_{field} -->
+<input id="1_name" />
+<input id="2_name" />
+
+<!-- Bad: Inconsistent -->
+<input id="name-1" />
+<input id="2_name" />
+```
+
+---
+
+### 4. Mobile Detection
+
+Combine with CSS for responsive behavior:
+
+```svelte
+<script>
+  import { IsMobileOrTablet } from 'intelliwaketssveltekitv25'
+  const isMobile = IsMobileOrTablet()
+</script>
+
+<div class:mobile-layout={isMobile}>
+  ...
+</div>
+```
+
+---
+
+## Related Documentation
+
+- **[InputNumber](InputNumber)** - Uses `HandleKeyDownNumerics` internally
+- **[TextArea](TextArea)** - Uses `autoGrow` internally
+- **[useActions](Home)** - Compose multiple use: actions
+- **[Integration Guide](Integration)** - Browser vs. server utilities
+
+---
+
+## Technical Notes
+
+### Browser-Only Functions
+
+These functions require browser environment:
+- `CaptureGPS` - Geolocation API
+- `CopyRefToClipboard` - Clipboard API
+- `IsMobileOrTablet` - Navigator API
+- `setSearchParam` - SvelteKit navigation
+- All download functions - DOM manipulation
+- All Svelte actions - DOM events
+
+**Server-Side Usage:** Import only when needed in client components, or use dynamic imports.
+
+### Performance Considerations
+
+- **autoGrow** - Uses ResizeObserver, debounce for high-frequency updates
+- **upDownArrows/nextPrevArrows** - Implements 100ms debounce to prevent rapid navigation
+- **CopyRefToClipboard** - Temporarily modifies DOM, immediately restores
+
+### Browser Compatibility
+
+- **Geolocation API** - Requires HTTPS in production
+- **Clipboard API** - Modern browsers only (uses deprecated `document.execCommand`)
+- **ResizeObserver** - Modern browsers (no IE11)
+
+---
+
+*For implementation examples, see Storybook stories or component tests in the package repository.*