intelliwaketssveltekitv25 1.0.82 → 1.0.84

package/docs/Svelte-5-Patterns.md

@@ -0,0 +1,364 @@
+# Svelte 5 Patterns
+
+This library extensively uses modern Svelte 5 features including runes, snippets, and TypeScript generics. Understanding these patterns will help you use the library effectively.
+
+## Runes
+
+Svelte 5 introduces runes for reactive state management. This library uses them extensively in component examples.
+
+### $state() - Reactive State
+
+Creates reactive local state:
+
+```svelte
+<script>
+  import { Switch } from 'intelliwaketssveltekitv25';
+
+  let enabled = $state(false);
+  let count = $state(0);
+</script>
+
+<Switch bind:checked={enabled}>Enable</Switch>
+<p>Status: {enabled ? 'On' : 'Off'}</p>
+```
+
+### $derived() - Computed Values
+
+Automatically updates when dependencies change:
+
+```svelte
+<script>
+  import { InputNumber } from 'intelliwaketssveltekitv25';
+
+  let price = $state(100);
+  let taxRate = $state(0.08);
+
+  // Computed value
+  let total = $derived(price * (1 + taxRate));
+</script>
+
+<InputNumber bind:value={price} currency />
+<InputNumber bind:value={taxRate} percent />
+<p>Total: ${total.toFixed(2)}</p>
+```
+
+### $effect() - Side Effects
+
+Runs when dependencies change:
+
+```svelte
+<script>
+  import { Switch } from 'intelliwaketssveltekitv25';
+
+  let darkMode = $state(false);
+
+  $effect(() => {
+    // Runs whenever darkMode changes
+    document.body.classList.toggle('dark', darkMode);
+  });
+</script>
+
+<Switch bind:checked={darkMode}>Dark Mode</Switch>
+```
+
+### $bindable() - Two-Way Binding Props
+
+Used internally by library components for props that support `bind:`:
+
+```svelte
+<script>
+  // Inside a component
+  let {
+    checked = $bindable(false)
+  } = $props();
+</script>
+
+<!-- Usage -->
+<Switch bind:checked={myValue} />
+```
+
+## Snippets
+
+Svelte 5's snippet system replaces slots for flexible content projection.
+
+### Basic Snippet Usage
+
+```svelte
+<script>
+  import { Modal } from 'intelliwaketssveltekitv25';
+  let showModal = $state(false);
+</script>
+
+<Modal bind:show={showModal}>
+  {#snippet header()}
+    Modal Title
+  {/snippet}
+
+  {#snippet body()}
+    <p>Modal content goes here</p>
+  {/snippet}
+</Modal>
+```
+
+### Snippets with Parameters
+
+Some components pass data to snippets:
+
+```typescript
+// Component prop type
+{
+  row?: Snippet<[T, number]>  // Receives item and index
+}
+```
+
+```svelte
+<VirtualList items={users}>
+  {#snippet row(user, index)}
+    <div>
+      {index + 1}. {user.name}
+    </div>
+  {/snippet}
+</VirtualList>
+```
+
+### Multiple Snippets
+
+Components can accept multiple snippets:
+
+```svelte
+<Modal bind:show={showModal}>
+  {#snippet header()}
+    Header Content
+  {/snippet}
+
+  {#snippet body()}
+    Body Content
+  {/snippet}
+
+  {#snippet leftFooter()}
+    <button>Cancel</button>
+  {/snippet}
+
+  {#snippet rightFooter()}
+    <button>Save</button>
+  {/snippet}
+</Modal>
+```
+
+### Optional Snippets
+
+Most snippets are optional. Components check before rendering:
+
+```svelte
+<!-- Component internals -->
+{#if header}
+  {@render header()}
+{/if}
+```
+
+## TypeScript Generics
+
+Components like ArrayTable and VirtualList use generics for type safety.
+
+### Generic Component Usage
+
+```svelte
+<script lang="ts">
+  import { ArrayTable } from 'intelliwaketssveltekitv25';
+  import type { IArrayStructure } from 'intelliwaketssveltekitv25';
+
+  interface User {
+    id: number;
+    name: string;
+    email: string;
+  }
+
+  let users: User[] = $state([
+    { id: 1, name: 'John', email: 'john@example.com' }
+  ]);
+
+  // Type-safe structure definition
+  const structure: IArrayStructure<User> = {
+    columns: [
+      { fieldName: 'id', title: 'ID' },        // TypeScript ensures 'id' exists
+      { fieldName: 'name', title: 'Name' },    // on User interface
+      { fieldName: 'email', title: 'Email' }
+    ]
+  };
+</script>
+
+<ArrayTable arrayData={users} arrayStructure={structure} />
+```
+
+### Generic Constraints
+
+Some components require specific type shapes:
+
+```typescript
+// MultiSelect requires id or name
+interface TGenericMultiSelect {
+  id?: string | number;
+  name?: string;
+  [key: string]: any;
+}
+
+interface Tag extends TGenericMultiSelect {
+  id: number;
+  name: string;
+  color: string;
+}
+```
+
+### Custom Value Functions
+
+Override default generic behavior:
+
+```svelte
+<script lang="ts">
+  import { MultiSelect } from 'intelliwaketssveltekitv25';
+
+  interface CustomItem {
+    uuid: string;
+    displayName: string;
+  }
+
+  const items: CustomItem[] = [
+    { uuid: 'abc123', displayName: 'Item 1' }
+  ];
+
+  let selected = $state<CustomItem[]>([]);
+</script>
+
+<MultiSelect
+  possibles={items}
+  bind:selected={selected}
+  idValue={(item) => item.uuid}
+  displayValue={(item) => item.displayName}
+/>
+```
+
+## Component Generics Declaration
+
+When creating components that use generics:
+
+```svelte
+<script lang="ts" generics="T extends Record<string, any>">
+  import type { Snippet } from 'svelte';
+
+  let {
+    items,
+    row
+  }: {
+    items: T[];
+    row?: Snippet<[T, number]>;
+  } = $props();
+</script>
+
+{#each items as item, index}
+  {#if row}
+    {@render row(item, index)}
+  {/if}
+{/each}
+```
+
+## Action Arrays
+
+Components support Svelte actions via the `use` prop:
+
+```typescript
+import type { ActionArray } from 'svelte/action';
+```
+
+```svelte
+<script>
+  import { TextArea } from 'intelliwaketssveltekitv25';
+
+  function customAction(node: HTMLElement) {
+    console.log('Action applied:', node);
+    return {
+      destroy() {
+        console.log('Action destroyed');
+      }
+    };
+  }
+
+  const actions: ActionArray = [customAction];
+</script>
+
+<TextArea bind:value={text} use={actions} />
+```
+
+## Best Practices
+
+### 1. Always Use Runes in Svelte 5
+
+```svelte
+<!-- ❌ Old Svelte 4 syntax -->
+<script>
+  let count = 0;  // Not reactive in Svelte 5
+</script>
+
+<!-- ✅ Svelte 5 with runes -->
+<script>
+  let count = $state(0);  // Reactive
+</script>
+```
+
+### 2. Use TypeScript Generics for Type Safety
+
+```svelte
+<!-- ❌ No type safety -->
+<script>
+  const structure = {
+    columns: [
+      { fieldName: 'naam' }  // Typo not caught
+    ]
+  };
+</script>
+
+<!-- ✅ Type-safe with generics -->
+<script lang="ts">
+  interface User {
+    name: string;
+  }
+
+  const structure: IArrayStructure<User> = {
+    columns: [
+      { fieldName: 'naam' }  // TypeScript error!
+    ]
+  };
+</script>
+```
+
+### 3. Always Bind Two-Way Props
+
+```svelte
+<!-- ❌ One-way binding (component state won't update parent) -->
+<Switch checked={enabled} />
+
+<!-- ✅ Two-way binding -->
+<Switch bind:checked={enabled} />
+```
+
+### 4. Use Snippets Instead of Slots
+
+```svelte
+<!-- ❌ Old Svelte 4 slots -->
+<Modal>
+  <svelte:fragment slot="header">Title</svelte:fragment>
+</Modal>
+
+<!-- ✅ Svelte 5 snippets -->
+<Modal>
+  {#snippet header()}
+    Title
+  {/snippet}
+</Modal>
+```
+
+## Further Reading
+
+- [Official Svelte 5 Documentation](https://svelte.dev)
+- [Svelte 5 Runes Guide](https://svelte.dev/docs/svelte/$state)
+- [Svelte 5 Snippets Guide](https://svelte.dev/docs/svelte/snippet)
+- Component examples in this library's Storybook: `pnpm storybook`

package/docs/Switch.md

@@ -0,0 +1,107 @@
+# Switch Component
+
+**Replaces:** `<input type="checkbox">` for ALL toggle switches and boolean controls
+
+**Purpose:** Custom styled toggle switch with smooth animations, accessibility, and two-way data binding
+
+**When to Use:**
+- Feature toggles (enable/disable settings)
+- Boolean preferences (notifications on/off)
+- Any on/off state in settings or forms
+- **NOT for multiple selections** (use CheckBox component for that)
+
+## Key Props
+
+- `checked?: boolean` ($bindable) - Current checked state, use `bind:checked` for two-way binding
+- `disabled?: boolean` (default: false) - Disables user interaction, grays out the switch
+- `readonly?: boolean` (default: false) - Visual display only, no interaction allowed
+- `name?: string` - Form field name for HTML form submissions
+- `value?: unknown` - Value to submit when checked (default: boolean checked state)
+- `offValue?: unknown` - Value to submit when unchecked (default: undefined)
+- `displayCheckInverse?: boolean` - Inverts visual display (useful for "disabled" semantics)
+- `hidden?: boolean` - Hides the component
+- `class?: string` - Additional CSS classes for the wrapper
+- `oncheck?: (val: boolean) => void` - Callback fired when checked state changes
+- `use?: ActionArray` - Svelte actions array
+- `id?: string` - HTML id attribute
+- `form?: string` - Associate with a specific form by ID
+
+## Snippets
+
+- `children?: Snippet` - Label content displayed to the right of the switch
+
+## Usage Examples
+
+```svelte
+<!-- Basic toggle -->
+<script>
+  import { Switch } from 'intelliwaketssveltekitv25';
+  let notificationsEnabled = $state(false);
+</script>
+
+<Switch bind:checked={notificationsEnabled}>
+  Enable Email Notifications
+</Switch>
+
+<!-- In a form with name attribute -->
+<form method="POST">
+  <Switch name="agreeToTerms" bind:checked={agreedToTerms}>
+    I agree to the terms and conditions
+  </Switch>
+  <button type="submit">Submit</button>
+</form>
+
+<!-- Disabled state -->
+<Switch checked={true} disabled>
+  Premium Feature (Upgrade Required)
+</Switch>
+
+<!-- With oncheck callback -->
+<Switch
+  bind:checked={darkModeEnabled}
+  oncheck={(isChecked) => {
+    console.log('Dark mode:', isChecked);
+    // Apply theme changes
+  }}
+>
+  Dark Mode
+</Switch>
+
+<!-- Custom value submission -->
+<Switch
+  name="subscription"
+  bind:checked={isSubscribed}
+  value="premium"
+  offValue="free"
+>
+  Premium Subscription
+</Switch>
+
+<!-- Display inverse (show as "on" when feature is disabled) -->
+<Switch bind:checked={disableTracking} displayCheckInverse>
+  Disable Tracking
+</Switch>
+```
+
+## Common Mistakes
+
+- ❌ Using `value` prop for binding: `<Switch bind:value={x}>`
+  ✅ Correct: `<Switch bind:checked={x}>`
+
+- ❌ Forgetting `bind:` directive: `<Switch checked={x}>`
+  ✅ Correct: `<Switch bind:checked={x}>` (for two-way binding)
+
+- ❌ Wrapping in `<label>`: `<label><Switch /></label>`
+  ✅ Correct: `<Switch>Label Text</Switch>` (uses children snippet internally)
+
+- ❌ Using Switch for multiple selections from a list
+  ✅ Correct: Use `CheckBox` component for multi-select scenarios
+
+## Related Components
+
+- `CheckBox` - For custom checkbox styling (not toggle appearance)
+- `SwitchDateNull` - Toggle that sets/clears a date value
+
+## Storybook
+
+See `Components/Switch` stories for interactive examples