intelliwaketssveltekitv25 1.0.82 → 1.0.83

package/docs/DisplayHTML.md

@@ -0,0 +1,249 @@
+# DisplayHTML Component
+
+**Purpose:** Safely render text, HTML, or Svelte snippets with automatic URL link conversion
+
+**When to Use:**
+- Display user-generated content that may contain HTML
+- Automatically convert URLs to clickable links
+- Render dynamic content from database fields
+- Display formatted text with HTML tags
+- Conditionally render Svelte snippets
+
+## Key Props
+
+- `value: string | null | undefined | Snippet` (required) - Content to display
+- `anchorClasses?: string` (default: '') - CSS classes for auto-generated anchor links
+- `noLinkReplace?: boolean` (default: false) - Disable automatic URL-to-link conversion
+- `hidden?: boolean` - Hide the component
+
+## Features
+
+### Automatic Link Conversion
+By default, the component automatically converts plain URLs in text to clickable anchor links:
+```
+"Visit https://example.com" → "Visit <a href="https://example.com">https://example.com</a>"
+```
+
+### HTML Detection
+The component intelligently detects HTML content and renders it using `{@html}` when needed, while rendering plain text normally.
+
+### Snippet Support
+Pass Svelte snippets as the `value` for dynamic component rendering.
+
+### Text-to-HTML Conversion
+Converts newlines to `<br>` tags for proper text formatting.
+
+## Usage Examples
+
+```svelte
+<script>
+  import { DisplayHTML } from 'intelliwaketssveltekitv25';
+
+  let plainText = 'Hello, world!';
+  let htmlContent = '<strong>Bold text</strong> and <em>italic text</em>';
+  let textWithUrl = 'Visit our site at https://example.com for more info';
+  let multilineText = 'Line 1\nLine 2\nLine 3';
+</script>
+
+<!-- Plain text -->
+<DisplayHTML value={plainText} />
+<!-- Output: Hello, world! -->
+
+<!-- HTML content -->
+<DisplayHTML value={htmlContent} />
+<!-- Output: Bold text and italic text (rendered) -->
+
+<!-- Text with URL (auto-converted to link) -->
+<DisplayHTML value={textWithUrl} />
+<!-- Output: Visit our site at <a href="https://example.com">https://example.com</a> for more info -->
+
+<!-- Disable link conversion -->
+<DisplayHTML value={textWithUrl} noLinkReplace />
+<!-- Output: Visit our site at https://example.com for more info (plain text) -->
+
+<!-- Styled links -->
+<DisplayHTML
+  value={textWithUrl}
+  anchorClasses="text-blue-600 hover:underline"
+/>
+
+<!-- Conditional display -->
+<DisplayHTML value={description} hidden={!showDescription} />
+
+<!-- With Svelte snippet -->
+<DisplayHTML value={mySnippet} />
+
+<!-- Null-safe (won't render if null/undefined) -->
+<DisplayHTML value={maybeNull} />
+
+<!-- Multiline text (newlines converted to <br>) -->
+<DisplayHTML value={multilineText} />
+<!-- Output:
+Line 1<br>
+Line 2<br>
+Line 3
+-->
+```
+
+## Real-World Examples
+
+### User Comments
+```svelte
+<script>
+  let comment = $state('Check out https://example.com - it's great!');
+</script>
+
+<DisplayHTML
+  value={comment}
+  anchorClasses="text-blue-500 hover:underline"
+/>
+```
+
+### Product Description
+```svelte
+<script>
+  export let data;
+  let product = data.product;
+</script>
+
+<h2>{product.name}</h2>
+<DisplayHTML value={product.descriptionHTML} />
+```
+
+### Dynamic Content from Database
+```svelte
+<script>
+  // Database field may contain HTML or plain text
+  let content = $state(data.content); // Could be "<p>HTML</p>" or "Plain text"
+</script>
+
+<DisplayHTML value={content} />
+<!-- Automatically handles both cases -->
+```
+
+### Email Body Display
+```svelte
+<script>
+  let emailBody = $state(email.body);
+</script>
+
+<div class="email-content">
+  <DisplayHTML
+    value={emailBody}
+    anchorClasses="text-blue-600 underline"
+  />
+</div>
+```
+
+### Conditional Rendering with Snippets
+```svelte
+<script>
+  let useCustomRender = $state(true);
+</script>
+
+{#snippet customContent()}
+  <div class="custom">
+    Custom rendered content
+  </div>
+{/snippet}
+
+<DisplayHTML value={useCustomRender ? customContent : 'Plain text'} />
+```
+
+## Security Considerations
+
+**Important:** This component uses `{@html}` to render HTML content. Only use it with **trusted content**. Never pass unsanitized user input directly without server-side sanitization.
+
+### Safe Usage
+```svelte
+<!-- ✅ SAFE: Content from your database (sanitized on server) -->
+<DisplayHTML value={product.description} />
+
+<!-- ✅ SAFE: Static content you control -->
+<DisplayHTML value="<strong>Our Policy</strong>" />
+
+<!-- ❌ UNSAFE: Raw user input without sanitization -->
+<DisplayHTML value={userInput} />
+<!-- Should be: -->
+<DisplayHTML value={sanitizedUserInput} />
+```
+
+### Sanitization Example (Server-side)
+```typescript
+// +page.server.ts
+import DOMPurify from 'isomorphic-dompurify';
+
+export const load = async () => {
+  const rawContent = await db.content.get();
+  const sanitizedContent = DOMPurify.sanitize(rawContent);
+
+  return {
+    content: sanitizedContent
+  };
+};
+```
+
+## Common Patterns
+
+### Table Cell with Links
+```svelte
+<ArrayTable data={items} columns={[
+  {
+    title: 'Description',
+    cell: (item) => ({ snippet: () => (
+      <DisplayHTML
+        value={item.description}
+        anchorClasses="text-primary-main"
+      />
+    )})
+  }
+]} />
+```
+
+### Fallback Content
+```svelte
+<DisplayHTML value={content || 'No description available'} />
+```
+
+### Optional Display
+```svelte
+{#if showDetails}
+  <DisplayHTML value={details} />
+{/if}
+```
+
+## Common Mistakes
+
+- ❌ Passing raw user input without sanitization (XSS risk)
+  ✅ Correct: Sanitize HTML content on the server before rendering
+
+- ❌ Not using `noLinkReplace` when you don't want URL conversion
+  ✅ Correct: Set `noLinkReplace={true}` for technical content with URLs
+
+- ❌ Using this component when simple text rendering would suffice
+  ✅ Correct: Use plain `{value}` for simple text, DisplayHTML only when needed
+
+- ❌ Forgetting that `null` or `undefined` values won't render
+  ✅ Correct: Provide fallback: `value={content || 'Default text'}`
+
+## Related Functions
+
+The component uses these utility functions from `@solidbasisventures/intelliwaketsfoundation`:
+- **ReplaceLinks(html, classes)** - Converts URLs to anchor tags
+- **TextToHTML(text)** - Converts plain text to HTML (newlines to `<br>`)
+- **IncludesHTML(text)** - Detects if string contains HTML tags
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string \| null \| undefined \| Snippet` | (required) | Content to display |
+| `anchorClasses` | `string` | `''` | CSS classes for auto-generated links |
+| `noLinkReplace` | `boolean` | `false` | Skip URL-to-link conversion |
+| `hidden` | `boolean` | `false` | Hide component |
+
+## Performance Notes
+
+- The component efficiently detects HTML vs plain text to minimize unnecessary `{@html}` usage
+- Link replacement only occurs when `noLinkReplace` is false
+- Snippet detection happens once via `$derived`

package/docs/DropDown.md

@@ -0,0 +1,269 @@
+# DropDown Component
+
+**Replaces:** `<select>` elements and custom dropdown menus
+
+**Purpose:** Rich dropdown menu with keyboard navigation, icons, search, and action handling
+
+**When to Use:**
+- Action menus (context menus, toolbar dropdowns)
+- Navigation dropdowns with links
+- Replacing `<select>` when you need icons, dividers, or complex items
+- Any menu that needs better UX than native `<select>`
+
+## Key Props
+
+- `show?: boolean` ($bindable) - Control dropdown open/closed state
+- `position?: TDropDownControlPosition` (default: null) - Menu position relative to button
+- `ddActions?: IDDAction[]` (default: []) - Array of menu items/actions (see IDDAction interface below)
+- `noCaret?: boolean` - Hide the dropdown arrow icon
+- `buttonTitle?: string | null` - Button text (if not using `button` snippet)
+- `buttonClass?: string` - CSS classes for the button
+- `controlClass?: string` - CSS classes for the dropdown wrapper
+- `toggleClass?: string` - CSS classes for the toggle container
+- `inputControl?: boolean` - Style button as input control
+- `fullBlock?: boolean` - Make button full width
+- `bodyClass?: string` - CSS classes for dropdown body/menu
+- `sameSize?: boolean` - Make dropdown menu same width as button
+- `zIndex?: number` (default: 40) - Z-index for dropdown positioning
+- `disabled?: boolean` - Disable the dropdown
+- `hidden?: boolean` - Hide the dropdown
+- `hideEmptyDDActions?: boolean` - Auto-hide if no actions provided
+- `verbose?: boolean` - Enable console logging for debugging
+- `dataColor?: TDefaultColorPalate` - Color theme for button
+- `clientWidth?: number` ($bindable) - Width of the button element
+
+## Snippets
+
+- `button?: Snippet` - Custom button content (overrides `buttonTitle`)
+- `actions?: Snippet` - Custom menu content (in addition to or instead of `ddActions`)
+
+## IDDAction Interface
+
+Menu items configuration:
+
+```typescript
+interface IDDAction {
+  title?: string                    // Display text
+  key?: string | number              // Unique key for item
+  divider?: boolean                  // Render as divider line
+  header?: boolean                   // Render as header text (bold, no click)
+  dividerGroup?: string              // Auto-add divider when group changes
+  headerGroup?: string               // Auto-add header when group changes
+  active?: boolean                   // Highlight as active/selected
+  disabled?: boolean                 // Disable interaction
+  hidden?: boolean                   // Hide from menu
+  indented?: boolean                 // Indent item (for hierarchy)
+
+  // Actions
+  action?: () => void                // Click handler
+  href?: string                      // Navigation URL
+  hrefReplace?: boolean              // Use replaceState navigation
+  hrefDownload?: string              // Download URL
+  hrefDownloadFilename?: string      // Filename for download
+
+  // Visual
+  faProps?: IFAProps                 // FontAwesome icon
+  imageHref?: string                 // Image URL for icon
+
+  // Alternate action (right side button)
+  alternateAction?: () => void       // Right-side button action
+  alternateTitle?: string            // Right-side button text
+  alternateFAProps?: IFAProps        // Right-side button icon
+  alternateNoClose?: boolean         // Keep menu open after alternate action
+
+  // Behavior
+  noCloseMenu?: boolean              // Keep menu open after action
+}
+```
+
+## Keyboard Navigation
+
+- **Arrow Down:** Open menu / Move to next item
+- **Arrow Up:** Move to previous item
+- **Enter:** Execute selected item action
+- **Tab:** Close menu
+- **Type letter:** Jump to first item starting with that letter
+
+## Usage Examples
+
+```svelte
+<script>
+  import { DropDown } from 'intelliwaketssveltekitv25';
+  import { faEdit, faTrash, faCopy } from '@fortawesome/free-solid-svg-icons';
+
+  let showMenu = $state(false);
+  let selectedOption = $state('option1');
+
+  const actions = [
+    {
+      title: 'Edit',
+      faProps: { icon: faEdit },
+      action: () => editItem()
+    },
+    {
+      title: 'Duplicate',
+      faProps: { icon: faCopy },
+      action: () => duplicateItem()
+    },
+    { divider: true },
+    {
+      title: 'Delete',
+      faProps: { icon: faTrash },
+      action: () => deleteItem()
+    }
+  ];
+</script>
+
+<!-- Simple action menu -->
+<DropDown
+  bind:show={showMenu}
+  buttonTitle="Actions"
+  ddActions={actions}
+/>
+
+<!-- As select replacement with active indicator -->
+<DropDown
+  bind:show={showOptions}
+  buttonTitle={selectedOption}
+  ddActions={[
+    {
+      title: 'Option 1',
+      active: selectedOption === 'option1',
+      action: () => selectedOption = 'option1'
+    },
+    {
+      title: 'Option 2',
+      active: selectedOption === 'option2',
+      action: () => selectedOption = 'option2'
+    },
+    {
+      title: 'Option 3',
+      active: selectedOption === 'option3',
+      action: () => selectedOption = 'option3'
+    }
+  ]}
+  inputControl
+/>
+
+<!-- With navigation links -->
+<DropDown
+  buttonTitle="Navigate"
+  ddActions={[
+    { title: 'Dashboard', href: '/dashboard' },
+    { title: 'Settings', href: '/settings' },
+    { divider: true },
+    { title: 'Logout', href: '/logout', hrefReplace: true }
+  ]}
+/>
+
+<!-- With grouped items -->
+<DropDown
+  buttonTitle="Options"
+  ddActions={[
+    { title: 'File Operations', header: true },
+    { title: 'Open', action: () => open() },
+    { title: 'Save', action: () => save() },
+    { divider: true },
+    { title: 'Edit Operations', header: true },
+    { title: 'Cut', action: () => cut() },
+    { title: 'Copy', action: () => copy() },
+    { title: 'Paste', action: () => paste() }
+  ]}
+/>
+
+<!-- With auto-grouping by headerGroup -->
+<DropDown
+  buttonTitle="Grouped"
+  ddActions={[
+    { title: 'Item 1', headerGroup: 'Group A', action: () => {} },
+    { title: 'Item 2', headerGroup: 'Group A', action: () => {} },
+    { title: 'Item 3', headerGroup: 'Group B', action: () => {} },
+    { title: 'Item 4', headerGroup: 'Group B', action: () => {} }
+  ]}
+/>
+<!-- Automatically adds headers "Group A" and "Group B" -->
+
+<!-- Custom button content -->
+<DropDown bind:show={showCustom} ddActions={actions}>
+  {#snippet button()}
+    <Icon icon={faEllipsisV} />
+    More Options
+  {/snippet}
+</DropDown>
+
+<!-- Full width dropdown -->
+<DropDown
+  buttonTitle="Select Option"
+  ddActions={options}
+  fullBlock
+  sameSize
+  inputControl
+/>
+
+<!-- With disabled items -->
+<DropDown
+  buttonTitle="Actions"
+  ddActions={[
+    { title: 'Available Action', action: () => {} },
+    { title: 'Coming Soon', disabled: true },
+    { title: 'Premium Only', disabled: true }
+  ]}
+/>
+
+<!-- With alternate actions (two buttons per row) -->
+<DropDown
+  buttonTitle="Files"
+  ddActions={[
+    {
+      title: 'document.pdf',
+      action: () => openFile('document.pdf'),
+      alternateAction: () => downloadFile('document.pdf'),
+      alternateFAProps: { icon: faDownload }
+    }
+  ]}
+/>
+
+<!-- Download action -->
+<DropDown
+  buttonTitle="Export"
+  ddActions={[
+    {
+      title: 'Export as CSV',
+      hrefDownload: '/api/export?format=csv',
+      hrefDownloadFilename: 'data.csv'
+    },
+    {
+      title: 'Export as PDF',
+      hrefDownload: '/api/export?format=pdf',
+      hrefDownloadFilename: 'data.pdf'
+    }
+  ]}
+/>
+```
+
+## Common Mistakes
+
+- ❌ Not providing `action`, `href`, or `hrefDownload` for menu items
+  ✅ Correct: Every menu item (except dividers/headers) needs an action
+
+- ❌ Using DropDown when MultiSelect is more appropriate
+  ✅ Correct: Use `MultiSelect` for selecting multiple options, `DropDown` for single actions/selections
+
+- ❌ Forgetting to handle menu close in custom `noCloseMenu` actions
+  ✅ Correct: Manually set `show = false` when using `noCloseMenu: true`
+
+- ❌ Not using `bind:show` for controlled dropdowns
+  ✅ Correct: `<DropDown bind:show={showMenu}>` to control open/close state
+
+- ❌ Using complex objects as `key` without providing unique string/number keys
+  ✅ Correct: Always provide `key` prop for array items
+
+## Related Components
+
+- `DropDownControl` - Lower-level dropdown control (used internally by DropDown)
+- `MultiSelect` - For selecting multiple options from a list
+- `Importer` - Specialized dropdown for file imports
+
+## Storybook
+
+See `Components/DropDown` stories