intelliwaketssveltekitv25 1.0.82 → 1.0.84

package/docs/Integration.md

@@ -0,0 +1,215 @@
+# Integration Guide
+
+Complete setup requirements for integrating the IntelliWakeTSSvelteKitV2.5 component library into your SvelteKit project.
+
+## Installation
+
+```bash
+npm install intelliwaketssveltekitv25
+```
+
+## Required Peer Dependencies
+
+```json
+{
+  "@solidbasisventures/intelliwaketsfoundation": "^5.13.57",
+  "@sveltejs/kit": "^2.49.2",
+  "svelte": "^5.46.1"
+}
+```
+
+Install peer dependencies:
+
+```bash
+npm install @solidbasisventures/intelliwaketsfoundation @sveltejs/kit svelte
+```
+
+## CSS Import (Required)
+
+Import the library CSS in your root layout or app.css:
+
+```typescript
+// src/routes/+layout.svelte or src/app.css
+import 'intelliwaketssveltekitv25/dist/app.css';
+```
+
+## Tailwind CSS Configuration (Required)
+
+Your project **MUST** define these custom Tailwind colors in your `tailwind.config.js`:
+
+```javascript
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          main: '#your-color',      // Main primary color
+          face: '#your-color',      // Text color on primary background
+          hover: '#your-color',     // Hover state color
+          light: '#your-color',     // Light variant
+          selected: '#your-color'   // Selected state color
+        },
+        secondary: {
+          main: '#your-color',      // Main secondary color
+          light: '#your-color'      // Light variant
+        }
+      }
+    }
+  }
+}
+```
+
+### Example Color Configuration
+
+```javascript
+colors: {
+  primary: {
+    main: '#3b82f6',      // Blue-500
+    face: '#ffffff',      // White
+    hover: '#2563eb',     // Blue-600
+    light: '#dbeafe',     // Blue-100
+    selected: '#bfdbfe'   // Blue-200
+  },
+  secondary: {
+    main: '#64748b',      // Slate-500
+    light: '#e2e8f0'      // Slate-200
+  }
+}
+```
+
+### Required Custom CSS Classes
+
+Define these custom classes in your `app.css` or Tailwind config:
+
+```css
+/* Master-Detail Layout Horizontal Rules */
+.mdMasterHR {
+  /* Styling for MasterDetailLayout master section header HR */
+  @apply border-gray-300 my-2;
+}
+
+.mdDetailHR {
+  /* Styling for MasterDetailLayout detail section header HR */
+  @apply border-gray-400 my-2;
+}
+```
+
+## Component Import
+
+Import components as needed:
+
+```svelte
+<script>
+  import { Switch, InputNumber, Modal, ArrayTable } from 'intelliwaketssveltekitv25';
+
+  let enabled = $state(false);
+  let price = $state(29.99);
+</script>
+
+<Switch bind:checked={enabled}>Enable Feature</Switch>
+<InputNumber bind:value={price} currency />
+```
+
+## TypeScript Support
+
+The library is fully typed. Import types as needed:
+
+```typescript
+import type {
+  IArrayStructure,
+  IArrayColumn,
+  IDDAction,
+  IFAProps
+} from 'intelliwaketssveltekitv25';
+```
+
+## FontAwesome Icons
+
+Many components support FontAwesome icons via the `IFAProps` interface:
+
+```bash
+npm install @fortawesome/free-solid-svg-icons
+```
+
+```svelte
+<script>
+  import { DropDown } from 'intelliwaketssveltekitv25';
+  import { faEdit, faTrash } from '@fortawesome/free-solid-svg-icons';
+
+  const actions = [
+    { title: 'Edit', faProps: { icon: faEdit }, action: () => {} },
+    { title: 'Delete', faProps: { icon: faTrash }, action: () => {} }
+  ];
+</script>
+
+<DropDown buttonTitle="Actions" ddActions={actions} />
+```
+
+## SvelteKit Configuration
+
+The library uses Svelte 5 experimental features. Your `svelte.config.ts` should include:
+
+```typescript
+import adapter from '@sveltejs/adapter-auto';
+
+export default {
+  kit: {
+    adapter: adapter(),
+    experimental: {
+      remoteFunctions: true
+    }
+  },
+  compilerOptions: {
+    experimental: {
+      async: true
+    }
+  }
+};
+```
+
+## CSS Variables
+
+The library defines these CSS variables (in `dist/app.css`):
+
+```css
+:root {
+  --red-color: red;
+  --color-danger: #fb2c36;
+}
+```
+
+## Global Styles
+
+The library includes global button and input styles. To opt-out on specific elements:
+
+```svelte
+<!-- Skip global button styles -->
+<button class="btnClean">Custom Styled Button</button>
+
+<!-- Skip global input formatting -->
+<input class="noFormat" type="text" />
+```
+
+## Troubleshooting
+
+### Colors Not Showing
+
+Ensure you've defined all required Tailwind colors in your `tailwind.config.js`.
+
+### CSS Not Loading
+
+Verify you've imported `intelliwaketssveltekitv25/dist/app.css` in your root layout.
+
+### TypeScript Errors
+
+Install all peer dependencies and ensure TypeScript version is 5.0+.
+
+### Components Not Rendering
+
+Check browser console for errors related to missing dependencies or CSS.
+
+## Next Steps
+
+- Explore [Svelte 5 Patterns](Svelte-5-Patterns) used in the library
+- Browse component documentation starting with [Switch](Switch)
+- Run Storybook: `pnpm storybook` for interactive examples

package/docs/Modal.md

@@ -0,0 +1,207 @@
+# Modal Component
+
+**Replaces:** Native `<dialog>` element or custom div overlays with manual JavaScript
+
+**Purpose:** Full-featured modal dialog with draggable header, keyboard shortcuts, and flexible content slots
+
+**When to Use:**
+- Confirmation dialogs (delete, save, cancel operations)
+- Forms that need to overlay the main content
+- Multi-step workflows in a focused view
+- Detail views that shouldn't navigate away from current page
+- Any overlay content that requires user interaction before proceeding
+
+## Key Props
+
+- `show: unknown` ($bindable) - Control visibility: value equal to `noShowValue` hides modal, any other value shows it
+- `noShowValue?: unknown` (default: false) - The value to compare against `show` to determine if modal should be hidden
+- `forceNoShow?: boolean` - Force modal to be hidden regardless of `show` value
+- `width?: string` (default: '40em') - Modal width (CSS value like '40em', '500px', '80%')
+- `cancelButton?: string | false` (default: 'Cancel') - Cancel button text, or `false` to hide
+- `okButton?: string | false` (default: 'OK') - OK button text, or `false` to hide
+- `okDisabled?: boolean` - Disable the OK button
+- `okColor?: TDefaultColorPalate | null` - Color theme for OK button
+- `okFAProps?: IFAProps` - FontAwesome icon props for OK button
+- `okType?: 'submit' | 'button'` (default: 'button') - Button type for form integration
+- `okActionNotOnEnter?: boolean` - Prevent Enter key from triggering OK action
+- `noCloseOnOK?: boolean` (default: true) - Keep modal open after OK click (useful for form validation)
+- `overflowY?: 'auto' | 'visible' | 'hidden'` (default: 'auto') - Body overflow behavior
+- `disable?: boolean` - Disable all interactions (shows activity overlay)
+- `marginForStickyHeader?: boolean` - Add margin to body for sticky header support
+- `okButtonWrap?: boolean` - Allow OK/Cancel button text to wrap
+- `borderFooter?: boolean` (default: true) - Show border above footer
+- `class?: string` - Additional CSS classes for dialog element
+- `color?: TDefaultColorPalate | null` - Overall color theme
+- `classHeader?: string` - CSS classes for header section
+- `classBody?: string` - CSS classes for body section
+- `classFooter?: string` - CSS classes for footer section
+- `classButton?: string` - CSS classes for OK button
+- `onOK?: () => void` - Callback when OK button clicked (synchronous)
+- `onOKPromise?: () => Promise<unknown>` - Async callback for OK button (awaits promise before closing)
+- `onCancel?: () => void` - Callback when Cancel button clicked or modal dismissed
+- `onClose?: () => void` - Callback when modal closes (any reason)
+
+## Snippets
+
+- `header?: Snippet` - Header content (displays in colored bar with close button)
+- `body?: Snippet` - Main body content
+- `leftFooter?: Snippet` - Content in footer left section
+- `centerFooter?: Snippet` - Content in footer center section
+- `rightFooter?: Snippet` - Content in footer right section
+
+## Special Features
+
+- **Draggable:** Click and drag the header to reposition the modal
+- **Keyboard shortcuts:** Enter key triggers OK, Escape key cancels
+- **Activity overlay:** Automatically disables interaction when `disable` is true
+- **Backdrop click:** Clicking outside modal closes it (triggers cancel action)
+
+## Usage Examples
+
+```svelte
+<script>
+  import { Modal } from 'intelliwaketssveltekitv25';
+  let showConfirmDelete = $state(false);
+  let showEditForm = $state(null); // null = hidden, object = shown with data
+  let isProcessing = $state(false);
+</script>
+
+<!-- Simple confirmation dialog -->
+<Modal
+  bind:show={showConfirmDelete}
+  width="30em"
+  okButton="Delete"
+  cancelButton="Cancel"
+  onOK={() => {
+    performDelete();
+    showConfirmDelete = false;
+  }}
+>
+  {#snippet header()}
+    Confirm Deletion
+  {/snippet}
+  {#snippet body()}
+    Are you sure you want to delete this item? This action cannot be undone.
+  {/snippet}
+</Modal>
+
+<!-- Form in modal with validation -->
+<Modal
+  bind:show={showEditForm}
+  width="50em"
+  okButton="Save Changes"
+  okType="submit"
+  noCloseOnOK={true}
+  onOKPromise={async () => {
+    // Validate and save
+    const result = await saveForm(showEditForm);
+    if (result.success) {
+      showEditForm = null; // Close on success
+    } else {
+      // Stay open on validation failure
+      throw new Error(result.error);
+    }
+  }}
+>
+  {#snippet header()}
+    Edit User Profile
+  {/snippet}
+  {#snippet body()}
+    <form id="editForm">
+      <!-- Form fields here -->
+      <input type="text" name="name" value={showEditForm?.name} />
+      <input type="email" name="email" value={showEditForm?.email} />
+    </form>
+  {/snippet}
+</Modal>
+
+<!-- Modal with custom footer content -->
+<Modal
+  bind:show={showDetails}
+  okButton={false}
+  cancelButton="Close"
+>
+  {#snippet header()}
+    Item Details
+  {/snippet}
+  {#snippet body()}
+    <p>Detailed information here...</p>
+  {/snippet}
+  {#snippet leftFooter()}
+    <button type="button" onclick={() => printDetails()}>
+      Print
+    </button>
+  {/snippet}
+  {#snippet rightFooter()}
+    <button type="button" onclick={() => exportDetails()}>
+      Export
+    </button>
+  {/snippet}
+</Modal>
+
+<!-- Modal with activity overlay during async operation -->
+<Modal
+  bind:show={showImport}
+  disable={isProcessing}
+  okButton="Import Data"
+  onOKPromise={async () => {
+    isProcessing = true;
+    try {
+      await importData();
+      showImport = false;
+    } finally {
+      isProcessing = false;
+    }
+  }}
+>
+  {#snippet header()}
+    Import Data
+  {/snippet}
+  {#snippet body()}
+    <input type="file" accept=".csv" />
+  {/snippet}
+</Modal>
+
+<!-- Using noShowValue for object-based visibility -->
+<Modal
+  bind:show={selectedUser}
+  noShowValue={null}
+  okButton="Save"
+>
+  {#snippet header()}
+    Edit {selectedUser?.name}
+  {/snippet}
+  {#snippet body()}
+    <!-- Edit form -->
+  {/snippet}
+</Modal>
+<!-- To show: selectedUser = {name: 'John', ...} -->
+<!-- To hide: selectedUser = null -->
+```
+
+## Common Mistakes
+
+- ❌ Not binding `show` prop: `<Modal show={x}>`
+  ✅ Correct: `<Modal bind:show={x}>` (for two-way binding)
+
+- ❌ Unclear `noShowValue` usage: `show={item}` with `noShowValue={null}` but forgetting to set `item = null` to close
+  ✅ Correct: Always set `show = noShowValue` to close the modal
+
+- ❌ Using `noCloseOnOK={false}` with `onOKPromise` without handling errors
+  ✅ Correct: Use `noCloseOnOK={true}` and manually close in promise, or handle all errors
+
+- ❌ Forgetting to prevent Enter key when using forms: Modal submits unexpectedly
+  ✅ Correct: Use `okActionNotOnEnter={true}` or `okType="submit"` with proper form handling
+
+- ❌ Not using `onOKPromise` for async operations, causing modal to close immediately
+  ✅ Correct: Use `onOKPromise` for async operations, not `onOK`
+
+## Related Components
+
+- `ModalFormAction` - Specialized modal for SvelteKit form actions
+- `ModalPromptControl` - Modal with prompt/confirmation patterns
+- `ActivityOverlay` - Loading overlay (used internally by Modal)
+
+## Storybook
+
+See `Components/Modal` stories