intelliwaketssveltekitv25 1.0.81 → 1.0.82

package/INTEGRATION.md

@@ -0,0 +1,574 @@
+# IntelliWakeTSSvelteKitV2.5 - Integration Guide
+
+This guide helps you integrate the `intelliwaketssveltekitv25` component library into your SvelteKit application and configure AI assistants to use it effectively.
+
+---
+
+## Installation
+
+### 1. Install the Package
+
+```bash
+# Using pnpm (recommended)
+pnpm add intelliwaketssveltekitv25
+
+# Using npm
+npm install intelliwaketssveltekitv25
+
+# Using yarn
+yarn add intelliwaketssveltekitv25
+```
+
+### 2. Install Peer Dependencies
+
+These are required dependencies that must be installed in your project:
+
+```bash
+pnpm add -D @solidbasisventures/intelliwaketsfoundation @sveltejs/kit svelte
+```
+
+**Required versions:**
+- `@solidbasisventures/intelliwaketsfoundation`: ^5.13.57
+- `@sveltejs/kit`: ^2.49.2
+- `svelte`: ^5.46.1
+
+---
+
+## CSS Configuration
+
+### Import the Library Styles (Required)
+
+Add this import to your root layout file (`src/routes/+layout.svelte`) or your global CSS file:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import 'intelliwaketssveltekitv25/dist/app.css';
+  // Your other imports...
+</script>
+
+<slot />
+```
+
+**Or** in your `src/app.css`:
+
+```css
+@import 'intelliwaketssveltekitv25/dist/app.css';
+```
+
+---
+
+## Tailwind CSS Configuration (Required)
+
+This library requires custom Tailwind colors and utility classes to be defined in your project.
+
+### Add Required Colors
+
+Edit your `tailwind.config.js` (or `tailwind.config.ts`):
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    './src/**/*.{html,js,svelte,ts}',
+    // Important: Include library components in Tailwind scan
+    './node_modules/intelliwaketssveltekitv25/**/*.{html,js,svelte,ts}'
+  ],
+  theme: {
+    extend: {
+      colors: {
+        // Required primary colors
+        primary: {
+          main: '#3b82f6',      // Your primary brand color
+          face: '#2563eb',      // Darker shade for contrast
+          hover: '#60a5fa',     // Lighter shade for hover states
+          light: '#dbeafe',     // Very light shade for backgrounds
+          selected: '#bfdbfe'   // Selected item background
+        },
+        // Required secondary colors
+        secondary: {
+          main: '#64748b',      // Secondary brand color
+          light: '#e2e8f0'      // Light secondary shade
+        }
+      }
+    }
+  },
+  plugins: []
+}
+```
+
+**Color Guidelines:**
+- Use your own brand colors for these values
+- Ensure sufficient contrast for accessibility
+- `face` should be darker than `main` for text on `main` backgrounds
+- `light` and `selected` should be very light variants for subtle backgrounds
+
+### Add Custom Utility Classes
+
+If you're using the `MasterDetailLayout` component, add these custom classes to your global CSS:
+
+```css
+/* In your src/app.css or similar */
+
+/* Horizontal rule styling for MasterDetailLayout master section header */
+.mdMasterHR {
+  @apply border-slate-300 dark:border-slate-600;
+}
+
+/* Horizontal rule styling for MasterDetailLayout detail section header */
+.mdDetailHR {
+  @apply border-slate-200 dark:border-slate-500;
+}
+```
+
+---
+
+## LLM Integration (AI Assistants)
+
+### For Claude Code
+
+If your project uses Claude Code, add this section to your project's `CLAUDE.md` file:
+
+```markdown
+## Component Library: intelliwaketssveltekitv25
+
+This project uses the `intelliwaketssveltekitv25` component library (v1.0.81).
+
+### CRITICAL: Use Library Components Instead of Native HTML
+
+Before implementing UI components or form elements, **always check for library replacements**:
+
+| User Request | ❌ Don't Use | ✅ Use Instead |
+|--------------|--------------|----------------|
+| Checkboxes, toggles | `<input type="checkbox">` | `<Switch>` from intelliwaketssveltekitv25 |
+| Numeric inputs | `<input type="number">` | `<InputNumber>` from intelliwaketssveltekitv25 |
+| Dropdowns, selects | `<select>` | `<DropDown>` from intelliwaketssveltekitv25 |
+| Modals, dialogs | `<dialog>` or custom divs | `<Modal>` from intelliwaketssveltekitv25 |
+| Data tables | `<table>` with manual code | `<ArrayTable>` from intelliwaketssveltekitv25 |
+
+### Full Documentation
+
+Complete component reference with usage examples and common mistakes:
+**See:** `node_modules/intelliwaketssveltekitv25/LLM.md`
+
+### Example Usage
+
+```svelte
+<script>
+  import { Switch, InputNumber, Modal, DropDown, ArrayTable } from 'intelliwaketssveltekitv25';
+
+  let enabled = $state(false);
+  let price = $state(0);
+</script>
+
+<Switch bind:checked={enabled}>Enable Feature</Switch>
+<InputNumber bind:value={price} currency />
+```
+```
+
+### For GitHub Copilot
+
+If using GitHub Copilot, create or update `.github/copilot-instructions.md`:
+
+```markdown
+# Project Instructions for GitHub Copilot
+
+## UI Component Library
+
+This project uses `intelliwaketssveltekitv25` for UI components.
+
+### Important: Always use library components instead of native HTML
+
+- For checkboxes/toggles: Use `<Switch>` component, not `<input type="checkbox">`
+- For numeric inputs: Use `<InputNumber>` component, not `<input type="number">`
+- For dropdowns: Use `<DropDown>` component, not `<select>`
+- For modals: Use `<Modal>` component, not `<dialog>`
+- For data tables: Use `<ArrayTable>` component, not manual `<table>`
+
+Import from: `intelliwaketssveltekitv25`
+
+Full documentation: `node_modules/intelliwaketssveltekitv25/LLM.md`
+```
+
+### For Other AI Tools (Cursor, Continue, etc.)
+
+Most AI coding assistants can read project documentation files. Add a file like `.cursorrules` or `.continue/config.json` with:
+
+```json
+{
+  "docs": [
+    "node_modules/intelliwaketssveltekitv25/LLM.md",
+    "node_modules/intelliwaketssveltekitv25/INTEGRATION.md"
+  ],
+  "rules": [
+    "Always use Switch component instead of <input type='checkbox'>",
+    "Always use InputNumber component instead of <input type='number'>",
+    "Always use DropDown component instead of <select>",
+    "Always use Modal component instead of <dialog>",
+    "Always use ArrayTable component instead of manual tables"
+  ]
+}
+```
+
+---
+
+## Usage Examples
+
+### Basic Component Import and Usage
+
+```svelte
+<script lang="ts">
+  import { Switch, InputNumber, Modal } from 'intelliwaketssveltekitv25';
+
+  // State management with Svelte 5 runes
+  let darkMode = $state(false);
+  let price = $state(29.99);
+  let showModal = $state(false);
+</script>
+
+<!-- Toggle Switch -->
+<Switch bind:checked={darkMode}>
+  Dark Mode
+</Switch>
+
+<!-- Formatted Number Input -->
+<label>
+  Price:
+  <InputNumber bind:value={price} currency required />
+</label>
+
+<!-- Modal Dialog -->
+<button onclick={() => showModal = true}>
+  Open Modal
+</button>
+
+<Modal
+  bind:show={showModal}
+  okButton="Save"
+  cancelButton="Cancel"
+>
+  {#snippet header()}
+    Edit Settings
+  {/snippet}
+  {#snippet body()}
+    <p>Modal content goes here...</p>
+  {/snippet}
+</Modal>
+```
+
+### Type-Safe Data Table
+
+```svelte
+<script lang="ts">
+  import { ArrayTable, type IArrayStructure } from 'intelliwaketssveltekitv25';
+
+  interface Product {
+    id: number;
+    name: string;
+    price: number;
+    inStock: boolean;
+  }
+
+  let products: Product[] = $state([
+    { id: 1, name: 'Widget', price: 19.99, inStock: true },
+    { id: 2, name: 'Gadget', price: 29.99, inStock: false }
+  ]);
+
+  const tableStructure: IArrayStructure<Product> = {
+    columns: [
+      { fieldName: 'id', title: 'ID', size: 'sm' },
+      { fieldName: 'name', title: 'Product Name' },
+      { fieldName: 'price', title: 'Price', type: 'currency' },
+      {
+        fieldName: 'inStock',
+        title: 'Availability',
+        compute: (val) => val ? 'In Stock' : 'Out of Stock'
+      }
+    ],
+    sortable: true,
+    defaultSortColumn: 'name'
+  };
+</script>
+
+<ArrayTable
+  arrayData={products}
+  arrayStructure={tableStructure}
+  bordered
+/>
+```
+
+---
+
+## Version Management
+
+### Checking Your Installed Version
+
+```bash
+pnpm list intelliwaketssveltekitv25
+# or
+npm list intelliwaketssveltekitv25
+```
+
+### Updating the Library
+
+```bash
+pnpm update intelliwaketssveltekitv25
+# or
+npm update intelliwaketssveltekitv25
+```
+
+### Version Compatibility
+
+This documentation is for version **1.0.81**.
+
+When upgrading to a new version:
+1. Read the changelog for breaking changes
+2. Update your `CLAUDE.md` or AI assistant config with the new version number
+3. Test critical components in your application
+4. Update any custom Tailwind colors if required by the new version
+
+---
+
+## Storybook (Component Examples)
+
+The library includes comprehensive Storybook documentation for all components.
+
+### View Storybook Locally
+
+1. Navigate to the library in `node_modules`:
+   ```bash
+   cd node_modules/intelliwaketssveltekitv25
+   ```
+
+2. Install dependencies (if needed):
+   ```bash
+   pnpm install
+   ```
+
+3. Run Storybook:
+   ```bash
+   pnpm storybook
+   ```
+
+4. Open browser to `http://localhost:6006`
+
+**Tip:** Storybook provides interactive examples of all components with editable props.
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. "Module not found" errors
+
+**Problem:** `Cannot find module 'intelliwaketssveltekitv25'`
+
+**Solution:**
+- Ensure the package is installed: `pnpm list intelliwaketssveltekitv25`
+- Restart your dev server
+- Check that your import path is correct: `import { Switch } from 'intelliwaketssveltekitv25'`
+
+#### 2. Components not styled correctly
+
+**Problem:** Components render but don't look right
+
+**Solution:**
+- Verify you've imported the CSS: `import 'intelliwaketssveltekitv25/dist/app.css'`
+- Check that your Tailwind config includes the library components in the `content` array
+- Ensure you've defined the required primary and secondary colors in Tailwind config
+
+#### 3. TypeScript errors about missing types
+
+**Problem:** `Cannot find type definitions`
+
+**Solution:**
+- The library includes TypeScript definitions automatically
+- Ensure you're using TypeScript 5.x or later
+- Check that your `tsconfig.json` has `"moduleResolution": "bundler"` or `"node16"`
+
+#### 4. Tailwind classes not working
+
+**Problem:** Custom classes not applying
+
+**Solution:**
+- Make sure your `tailwind.config.js` content array includes library files:
+  ```javascript
+  content: [
+    './src/**/*.{html,js,svelte,ts}',
+    './node_modules/intelliwaketssveltekitv25/**/*.{html,js,svelte,ts}'
+  ]
+  ```
+- Restart your dev server after changing Tailwind config
+- Run `pnpm exec tailwindcss -i src/app.css -o dist/output.css` to rebuild if needed
+
+#### 5. "Cannot find @solidbasisventures/intelliwaketsfoundation"
+
+**Problem:** Peer dependency not installed
+
+**Solution:**
+```bash
+pnpm add -D @solidbasisventures/intelliwaketsfoundation
+```
+
+---
+
+## Migration from Native HTML
+
+### Checkbox → Switch
+
+**Before:**
+```svelte
+<label>
+  <input type="checkbox" bind:checked={value} />
+  Enable Feature
+</label>
+```
+
+**After:**
+```svelte
+<Switch bind:checked={value}>
+  Enable Feature
+</Switch>
+```
+
+### Number Input → InputNumber
+
+**Before:**
+```svelte
+<input type="number" bind:value={price} step="0.01" />
+```
+
+**After:**
+```svelte
+<InputNumber bind:value={price} currency />
+```
+
+### Select → DropDown
+
+**Before:**
+```svelte
+<select bind:value={selected}>
+  <option value="1">Option 1</option>
+  <option value="2">Option 2</option>
+</select>
+```
+
+**After:**
+```svelte
+<DropDown
+  bind:show={showDropdown}
+  buttonTitle={selected}
+  ddActions={[
+    { title: 'Option 1', action: () => selected = 'Option 1' },
+    { title: 'Option 2', action: () => selected = 'Option 2' }
+  ]}
+  inputControl
+/>
+```
+
+### Dialog → Modal
+
+**Before:**
+```svelte
+<dialog bind:this={dialogElement}>
+  <h2>Title</h2>
+  <p>Content</p>
+  <button onclick={() => dialogElement.close()}>Close</button>
+</dialog>
+```
+
+**After:**
+```svelte
+<Modal
+  bind:show={showModal}
+  okButton="OK"
+  cancelButton="Close"
+>
+  {#snippet header()}
+    Title
+  {/snippet}
+  {#snippet body()}
+    <p>Content</p>
+  {/snippet}
+</Modal>
+```
+
+---
+
+## Support
+
+### Documentation Resources
+
+1. **LLM.md** - AI-optimized component reference (in package root)
+2. **CLAUDE.md** - Library development guide (in package root)
+3. **Storybook** - Interactive component examples (`pnpm storybook`)
+4. **README.md** - Quick start guide (in package root)
+
+### Getting Help
+
+- Check the LLM.md file for detailed component usage and common mistakes
+- Review Storybook examples for your use case
+- Ensure all peer dependencies are installed and up to date
+- Verify Tailwind configuration matches requirements
+
+### Reporting Issues
+
+If you encounter bugs or have feature requests:
+1. Check that you're using the latest version
+2. Verify your configuration matches this integration guide
+3. Report issues to the library maintainer with:
+   - Library version
+   - SvelteKit version
+   - Minimal reproduction example
+   - Error messages or screenshots
+
+---
+
+## Best Practices
+
+### 1. Always Use TypeScript
+
+The library is built with TypeScript and provides excellent type safety. Use types for component props:
+
+```typescript
+import { type IArrayStructure } from 'intelliwaketssveltekitv25';
+
+const structure: IArrayStructure<YourDataType> = { ... };
+```
+
+### 2. Prefer $bindable Props
+
+Use `bind:` directive for props marked as `$bindable`:
+
+```svelte
+<!-- ✅ Good: Two-way binding -->
+<Switch bind:checked={myValue} />
+<InputNumber bind:value={myNumber} />
+
+<!-- ❌ Bad: One-way binding (won't update parent) -->
+<Switch checked={myValue} />
+```
+
+### 3. Leverage Snippets
+
+Use Svelte 5 snippets for flexible content:
+
+```svelte
+<Modal bind:show={showModal}>
+  {#snippet header()}
+    <!-- Custom header content -->
+  {/snippet}
+  {#snippet body()}
+    <!-- Custom body content -->
+  {/snippet}
+</Modal>
+```
+
+### 4. Read LLM.md Common Mistakes
+
+Each component in LLM.md has a "Common Mistakes" section. Review these before using a component for the first time.
+
+---
+
+**Version:** 1.0.81 | **Last Updated:** 2026-01-08