intelliwaketssveltekitv25 1.0.81 → 1.0.83

package/docs/DateRangePicker.md

@@ -0,0 +1,272 @@
+# DateRangePicker Component
+
+**Purpose:** Select predefined or custom date ranges with calendar interface
+
+**When to Use:**
+- Filter reports by date range (Today, Last 7 Days, This Month, etc.)
+- Allow custom date range selection
+- Integrate with SvelteKit's `invalidate()` for data refresh
+- Persist date range selection in cookies
+
+## Key Props
+
+- `dateRange: TDateRangeString` ($bindable, required) - Current date range
+- `dateRanges?: TDateRangeString[]` - Available preset ranges (default: `DefaultRangeStringsReport()`)
+- `allowCustom?: boolean` (default: true) - Enable custom date range selection
+- `show?: boolean` ($bindable, default: false) - Control dropdown open state
+- `fyMonthsAdjust?: number | null` - Fiscal year month adjustment
+- `controlClass?: string` - CSS classes for dropdown wrapper
+- `toggleClass?: string` - CSS classes for toggle button
+- `bodyClass?: string` - CSS classes for dropdown body
+- `setCookieName?: string` - Cookie name to persist selection
+- `invalidate?: string | string[] | 'All' | 'app:All' | null` - SvelteKit invalidation targets
+- `onchange?: (dateRange: TDateRangeString) => void` - Callback when range changes
+
+## TDateRangeString Interface
+
+Date ranges have the following structure:
+```typescript
+interface TDateRangeString {
+  name: string         // Display name
+  start: string        // Start date (ISO format or date string)
+  end: string          // End date (ISO format or date string)
+}
+```
+
+## Default Ranges
+
+The component includes these preset ranges (via `DefaultRangeStringsReport()`):
+- Today
+- Yesterday
+- Last 7 Days
+- Last 14 Days
+- Last 30 Days
+- This Week
+- Last Week
+- This Month
+- Last Month
+- This Quarter
+- Last Quarter
+- This Year
+- Last Year
+- Custom (if `allowCustom` is true)
+
+## Usage Examples
+
+```svelte
+<script>
+  import { DateRangePicker } from 'intelliwaketssveltekitv25';
+  import { DefaultRangeStringsReport } from 'intelliwaketssveltekitv25';
+
+  let dateRange = $state(DefaultRangeStringsReport()[0]); // Today
+</script>
+
+<!-- Basic usage -->
+<DateRangePicker bind:dateRange />
+
+<!-- With SvelteKit invalidation -->
+<DateRangePicker
+  bind:dateRange
+  invalidate="app:loadData"
+/>
+
+<!-- Multiple invalidation targets -->
+<DateRangePicker
+  bind:dateRange
+  invalidate={['app:reports', 'app:charts']}
+/>
+
+<!-- Invalidate all -->
+<DateRangePicker
+  bind:dateRange
+  invalidate="All"
+/>
+
+<!-- Custom date ranges -->
+<DateRangePicker
+  bind:dateRange
+  dateRanges={[
+    { name: 'Today', start: 'today', end: 'today' },
+    { name: 'This Week', start: 'startOfWeek', end: 'today' },
+    { name: 'Last 30 Days', start: '-30', end: 'today' }
+  ]}
+/>
+
+<!-- Persist in cookies -->
+<DateRangePicker
+  bind:dateRange
+  setCookieName="reportDateRange"
+/>
+
+<!-- Without custom range option -->
+<DateRangePicker
+  bind:dateRange
+  allowCustom={false}
+/>
+
+<!-- With callback -->
+<DateRangePicker
+  bind:dateRange
+  onchange={(range) => {
+    console.log('Date range changed:', range);
+    fetchData(range.start, range.end);
+  }}
+/>
+
+<!-- Fiscal year adjustment (e.g., fiscal year starts in July) -->
+<DateRangePicker
+  bind:dateRange
+  fyMonthsAdjust={6}
+/>
+
+<!-- Controlled open state -->
+<DateRangePicker
+  bind:dateRange
+  bind:show={isOpen}
+/>
+<button onclick={() => isOpen = !isOpen}>
+  Toggle Date Picker
+</button>
+```
+
+## Custom Date Range Selection
+
+When `allowCustom` is true (default), users can:
+1. Click "Custom" from the preset list
+2. Use the calendar interface to select start and end dates
+3. Click between dates to toggle which date is being modified
+4. Cancel or Apply the custom range
+
+```svelte
+<script>
+  let dateRange = $state({
+    name: 'Custom',
+    start: '2024-01-01',
+    end: '2024-12-31'
+  });
+</script>
+
+<DateRangePicker bind:dateRange />
+```
+
+## Integration with SvelteKit
+
+### With `invalidate()`
+```svelte
+<script>
+  import { DateRangePicker } from 'intelliwaketssveltekitv25';
+  import { invalidate } from '$app/navigation';
+
+  export let data;
+
+  let dateRange = $state(data.dateRange);
+</script>
+
+<!-- Automatically invalidates and refetches -->
+<DateRangePicker
+  bind:dateRange
+  invalidate="app:reports"
+/>
+
+<!-- +page.server.ts -->
+<script>
+export const load = async ({ depends, url }) => {
+  depends('app:reports');
+
+  const dateRange = getDateRangeFromQuery(url);
+  const reports = await fetchReports(dateRange);
+
+  return { reports, dateRange };
+};
+</script>
+```
+
+### With Cookie Persistence
+```svelte
+<DateRangePicker
+  bind:dateRange
+  setCookieName="dashboardDateRange"
+  invalidate="app:dashboard"
+/>
+
+<!-- Date range is automatically saved to cookie and restored on page load -->
+```
+
+## Common Patterns
+
+### Report Filtering
+```svelte
+<script>
+  let dateRange = $state({ name: 'Last 30 Days', start: '-30', end: 'today' });
+  let reportData = $derived(filterReportByDates(allData, dateRange));
+</script>
+
+<DateRangePicker bind:dateRange />
+
+<table>
+  {#each reportData as item}
+    <tr>...</tr>
+  {/each}
+</table>
+```
+
+### Dashboard with Multiple Widgets
+```svelte
+<script>
+  let dateRange = $state(DefaultRangeStringsReport()[0]);
+</script>
+
+<DateRangePicker
+  bind:dateRange
+  setCookieName="dashboardRange"
+  invalidate="All"
+/>
+
+<SalesChart {dateRange} />
+<RevenueTable {dateRange} />
+<MetricsGrid {dateRange} />
+```
+
+## Common Mistakes
+
+- ❌ Not using `bind:dateRange` for two-way binding
+  ✅ Correct: `<DateRangePicker bind:dateRange />`
+
+- ❌ Using raw date objects instead of TDateRangeString
+  ✅ Correct: `{ name: 'Today', start: 'today', end: 'today' }`
+
+- ❌ Forgetting to import `DefaultRangeStringsReport` for preset ranges
+  ✅ Correct: `import { DefaultRangeStringsReport } from 'intelliwaketssveltekitv25'`
+
+- ❌ Not handling the invalidate effect on data loads
+  ✅ Correct: Use `depends()` in load functions or provide `invalidate` prop
+
+## Related Components
+
+- **Calendar** - Used internally for custom date selection
+- **DropDownControl** - Dropdown mechanism
+- **ListGroupItems** - Preset range list
+- **DateRangeFunctions** - Utilities: `DefaultRangeStringsReport()`, `CustomRangeName`
+- **Cookie** - Cookie persistence via `CookieCreate()`
+
+## Date Range Functions
+
+### DefaultRangeStringsReport(fyMonthsAdjust?)
+Returns array of standard date ranges for reporting.
+
+### CustomRangeName
+Constant for "Custom" range name (exported from `DateRangeFunctions`).
+
+## Styling
+
+The component uses:
+- `inputControl` class for the toggle button
+- Calendar icon (inline SVG)
+- `border-b-secondary-light` for active date indicator
+- Standard button classes (`btnLink`) for Cancel/Apply
+
+## Accessibility
+
+- Calendar date selection is keyboard navigable
+- Toggle shows current range or formatted custom dates
+- Visual indicator shows which date (start/end) is being modified

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`