intelliwaketssveltekitv25 1.0.81 → 1.0.83

package/docs/TabHeader.md

@@ -0,0 +1,333 @@
+# TabHeader Component
+
+**Purpose:** Client-side tab navigation with animated indicator
+
+**When to Use:**
+- Switch between views without URL changes
+- Local state tab management
+- Modal or component-level tabs
+- Conditional content display
+
+## Key Props
+
+- `tabItems: ITabItem<T>[]` (required) - Array of tab definitions
+- `currentKey: T | undefined` ($bindable, required) - Active tab key
+- `printAllTabs?: boolean` (default: false) - Print all tabs or just active
+- `rounded?: boolean` (default: false) - Rounded pill style vs underline style
+- `onchange?: (key: T) => void` - Callback when tab changes
+
+## ITabItem Interface
+
+```typescript
+interface ITabItem<T> {
+  key: T                      // Unique tab identifier (any type via generics)
+  title?: string              // Display text (falls back to key if omitted)
+  hidden?: boolean            // Hide this tab
+  disabled?: boolean          // Disable interaction
+  faProps?: IFAProps          // FontAwesome icon
+  action?: (key: T) => void   // Custom action instead of tab switch
+}
+```
+
+## Tab Styles
+
+### Default (Underline)
+```
+─────────────────────────
+Tab 1  Tab 2  Tab 3
+══════
+```
+- Animated underline indicator
+- Clean, modern look
+- Default style
+
+### Rounded
+```
+┌─────┐  ┌─────┐  ┌─────┐
+│Tab 1│  │Tab 2│  │Tab 3│
+└─────┘  └─────┘  └─────┘
+```
+- Pill-shaped buttons
+- Gray background for active tab
+- Set `rounded={true}`
+
+## Usage Examples
+
+```svelte
+<script>
+  import { TabHeader } from 'intelliwaketssveltekitv25';
+
+  let activeTab = $state<string>('overview');
+
+  const tabs = [
+    { key: 'overview', title: 'Overview' },
+    { key: 'details', title: 'Details' },
+    { key: 'settings', title: 'Settings' }
+  ];
+</script>
+
+<!-- Basic tabs -->
+<TabHeader
+  tabItems={tabs}
+  bind:currentKey={activeTab}
+/>
+
+{#if activeTab === 'overview'}
+  <Overview />
+{:else if activeTab === 'details'}
+  <Details />
+{:else if activeTab === 'settings'}
+  <Settings />
+{/if}
+
+<!-- With icons -->
+<script>
+  import { faUser, faCog, faChartBar } from '@fortawesome/free-solid-svg-icons';
+</script>
+
+<TabHeader
+  bind:currentKey={activeTab}
+  tabItems={[
+    { key: 'profile', title: 'Profile', faProps: { icon: faUser } },
+    { key: 'settings', title: 'Settings', faProps: { icon: faCog } },
+    { key: 'analytics', title: 'Analytics', faProps: { icon: faChartBar } }
+  ]}
+/>
+
+<!-- Rounded style -->
+<TabHeader
+  bind:currentKey={activeTab}
+  tabItems={tabs}
+  rounded
+/>
+
+<!-- With callback -->
+<TabHeader
+  bind:currentKey={activeTab}
+  tabItems={tabs}
+  onchange={(key) => {
+    console.log('Tab changed to:', key);
+    trackTabChange(key);
+  }}
+/>
+
+<!-- Conditional tabs -->
+<script>
+  let isPremium = $state(true);
+</script>
+
+<TabHeader
+  bind:currentKey={activeTab}
+  tabItems={[
+    { key: 'basic', title: 'Basic Features' },
+    { key: 'premium', title: 'Premium', hidden: !isPremium },
+    { key: 'admin', title: 'Admin', disabled: !isAdmin }
+  ]}
+/>
+
+<!-- Custom action (doesn't switch tabs) -->
+<TabHeader
+  bind:currentKey={activeTab}
+  tabItems={[
+    { key: 'tab1', title: 'Tab 1' },
+    { key: 'tab2', title: 'Tab 2' },
+    {
+      key: 'refresh',
+      title: 'Refresh',
+      faProps: { icon: faRefresh },
+      action: () => refreshData()
+    }
+  ]}
+/>
+
+<!-- TypeScript generics support -->
+<script lang="ts">
+  type TabKey = 'home' | 'about' | 'contact';
+  let current = $state<TabKey>('home');
+</script>
+
+<TabHeader<TabKey>
+  bind:currentKey={current}
+  tabItems={[
+    { key: 'home', title: 'Home' },
+    { key: 'about', title: 'About' },
+    { key: 'contact', title: 'Contact' }
+  ]}
+/>
+```
+
+## Common Patterns
+
+### Modal Tabs
+```svelte
+<Modal show={showModal} title="User Settings">
+  <TabHeader
+    bind:currentKey={modalTab}
+    tabItems={[
+      { key: 'general', title: 'General' },
+      { key: 'security', title: 'Security' },
+      { key: 'notifications', title: 'Notifications' }
+    ]}
+  />
+
+  <div class="mt-4">
+    {#if modalTab === 'general'}
+      <GeneralSettings />
+    {:else if modalTab === 'security'}
+      <SecuritySettings />
+    {:else}
+      <NotificationSettings />
+    {/if}
+  </div>
+</Modal>
+```
+
+### Wizard Steps
+```svelte
+<script>
+  let step = $state(1);
+  let canProceed = $derived(validateStep(step));
+</script>
+
+<TabHeader
+  bind:currentKey={step}
+  tabItems={[
+    { key: 1, title: 'Step 1: Info' },
+    { key: 2, title: 'Step 2: Details', disabled: step < 2 },
+    { key: 3, title: 'Step 3: Confirm', disabled: step < 3 }
+  ]}
+/>
+
+<button
+  disabled={!canProceed}
+  onclick={() => step++}
+>
+  Next
+</button>
+```
+
+### Dashboard Tabs
+```svelte
+<script>
+  let dashboardView = $state('stats');
+</script>
+
+<TabHeader
+  bind:currentKey={dashboardView}
+  tabItems={[
+    { key: 'stats', title: 'Statistics', faProps: { icon: faChartLine } },
+    { key: 'users', title: 'Users', faProps: { icon: faUsers } },
+    { key: 'reports', title: 'Reports', faProps: { icon: faFileAlt } }
+  ]}
+/>
+
+{#if dashboardView === 'stats'}
+  <StatsPanel />
+{:else if dashboardView === 'users'}
+  <UsersPanel />
+{:else}
+  <ReportsPanel />
+{/if}
+```
+
+### Numbered Tabs
+```svelte
+<TabHeader
+  bind:currentKey={activeTab}
+  tabItems={[
+    { key: 1, title: '1. Select Items' },
+    { key: 2, title: '2. Configure' },
+    { key: 3, title: '3. Review' },
+    { key: 4, title: '4. Complete' }
+  ]}
+/>
+```
+
+## Auto-Selection Behavior
+
+- If `currentKey` is undefined, first visible tab is selected
+- If `currentKey` references hidden tab, switches to first visible
+- If all tabs are hidden, `currentKey` becomes undefined
+
+## Print Behavior
+
+### Default (`printAllTabs={false}`)
+- Only active tab button visible in print
+- Inactive tabs hidden
+
+### With `printAllTabs={true}`
+- All tab buttons visible in print
+- Active tab still highlighted
+
+## Animated Indicator
+
+The component includes a smooth animated indicator:
+- Slides to active tab position
+- 300ms transition with easing
+- Calculates position based on button width/position
+- Border-bottom indicator (2px)
+- Uses `primary-selected` color
+
+## Common Mistakes
+
+- ❌ Not using `bind:currentKey` for two-way binding
+  ✅ Correct: `bind:currentKey={activeTab}`
+
+- ❌ Forgetting to handle tab content switching
+  ✅ Correct: Use `{#if currentKey === 'tab1'}` to show/hide content
+
+- ❌ Using same key for multiple tabs
+  ✅ Correct: Each tab must have unique key
+
+- ❌ Not providing title (shows key instead)
+  ✅ Correct: Set `title` property for display text
+
+- ❌ Using TabHeader when TabHref is more appropriate
+  ✅ Correct: Use TabHref for URL-based navigation
+
+## Comparison: TabHeader vs TabHref
+
+| Feature | TabHeader | TabHref |
+|---------|-----------|---------|
+| Navigation | Local state | URL-based |
+| Persistence | Session only | URL shareable |
+| Use case | Modal, components | Page navigation |
+| Browser back | No effect | Works naturally |
+| Performance | Instant | Page load |
+
+## Related Components
+
+- **TabHref** - URL-based tab navigation
+- **Icon** - Used for tab icons
+- **ITabItem** - Tab configuration interface
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tabItems` | `ITabItem<T>[]` | (required) | Tab definitions |
+| `currentKey` | `T \| undefined` | (required) | Active tab ($bindable) |
+| `printAllTabs` | `boolean` | `false` | Show all tabs in print |
+| `rounded` | `boolean` | `false` | Pill style vs underline |
+| `onchange` | `(key: T) => void` | - | Tab change callback |
+
+## Styling
+
+### Default Style
+- Border bottom: `border-b-2 border-b-slate-200`
+- Active: `border-b-primary-selected`
+- Text: Black for active, `text-slate-600` for inactive
+- Indicator: Animated border-bottom
+
+### Rounded Style
+- Background: `bg-gray-200` for active
+- Text: `text-gray-900 font-semibold` for active
+- Padding: `px-2.5`
+- Rounded: `rounded-md`
+
+## Accessibility
+
+- Keyboard navigable (standard button behavior)
+- Visual indicator for active state
+- Disabled state prevents interaction
+- Print-friendly with visibility controls

package/docs/TabHref.md

@@ -0,0 +1,370 @@
+# TabHref Component
+
+**Purpose:** URL-based tab navigation with SvelteKit routing and session/local storage persistence
+
+**When to Use:**
+- Page-level tab navigation with URL sync
+- Shareable tab states via URL
+- Persistent tab selection across page refreshes
+- Master-detail layouts with sub-navigation
+
+## Key Props
+
+- `tabHrefs: ITabHref[]` (required) - Array of tab definitions
+- `basePath?: string` - Base path for tab navigation (optional)
+- `slug?: string | null` ($bindable) - Current tab slug
+- `storage?: 'local' | 'session' | null` (default: 'session') - Persistence method
+- `saveKey?: string | null` - Custom storage key
+- `noIDRemember?: boolean` (default: false) - Disable ID persistence
+- `noTabAdjustments?: boolean` (default: false) - Skip 'Tab' prefix in URLs
+- `reclickToClose?: boolean` (default: false) - Allow closing active tab
+- `bottomMargin?: boolean` (default: true) - Add bottom margin
+- `consoleLogs?: boolean` (default: false) - Enable debug logging
+- `noResolveHidden?: boolean` (default: false) - Don't auto-redirect from hidden tabs
+- `printAllTabs?: boolean` (default: false) - Print all tabs or just active
+- `rounded?: boolean` (default: false) - Rounded pill style
+
+## ITabHref Interface
+
+```typescript
+interface ITabHref {
+  key: string                     // Tab identifier
+  title?: string                  // Display text (falls back to key)
+  href?: string                   // Custom URL (overrides default)
+  hidden?: boolean                // Hide this tab
+  disabled?: boolean              // Disable interaction
+  isInitial?: boolean             // Default tab when none selected
+  isOpen?: boolean                // Manually control open state
+  faProps?: IFAProps              // FontAwesome icon
+  dataSvelteKitPreloadData?: string  // Preload strategy
+}
+```
+
+## Key Features
+
+### URL Integration
+- Automatically generates tab URLs: `{basePath}/Tab{key}`
+- Custom hrefs override default URL generation
+- Works with SvelteKit's `goto()` and preloading
+- Clean URLs (removes trailing slashes)
+
+### Persistence
+- **Session Storage** (default): Persists within browser session
+- **Local Storage**: Persists across browser sessions
+- **None**: No persistence
+- Remembers last tab per base path
+- Optional ID-based memory (e.g., /Users/123 remembers tab separately from /Users/456)
+
+### PathAnalyzer Integration
+Uses `PathAnalyzer` utility for:
+- Route parsing and navigation
+- Predecessor/successor patterns (`~/`)
+- Active state detection
+- Dynamic URL generation
+
+## Usage Examples
+
+```svelte
+<script>
+  import { TabHref } from 'intelliwaketssveltekitv25';
+  import { faUser, faCog, faChartBar } from '@fortawesome/free-solid-svg-icons';
+
+  const tabs = [
+    { key: 'Profile', faProps: { icon: faUser } },
+    { key: 'Settings', faProps: { icon: faCog } },
+    { key: 'Analytics', faProps: { icon: faChartBar } }
+  ];
+</script>
+
+<!-- Basic usage -->
+<TabHref
+  tabHrefs={tabs}
+  basePath="Dashboard"
+/>
+<!-- Generates: /Dashboard/TabProfile, /Dashboard/TabSettings, /Dashboard/TabAnalytics -->
+
+<!-- Custom hrefs -->
+<TabHref
+  tabHrefs={[
+    { key: 'Overview', href: '/dashboard' },
+    { key: 'Details', href: '/dashboard/details' },
+    { key: 'History', href: '/dashboard/history' }
+  ]}
+  basePath="Dashboard"
+/>
+
+<!-- With initial tab -->
+<TabHref
+  tabHrefs={[
+    { key: 'Info', isInitial: true },
+    { key: 'Details' },
+    { key: 'Settings' }
+  ]}
+  basePath="Product"
+/>
+<!-- If no tab in URL, redirects to /Product/TabInfo -->
+
+<!-- Local storage persistence -->
+<TabHref
+  tabHrefs={tabs}
+  basePath="Settings"
+  storage="local"
+/>
+<!-- Persists across browser sessions -->
+
+<!-- No persistence -->
+<TabHref
+  tabHrefs={tabs}
+  basePath="Wizard"
+  storage={null}
+/>
+
+<!-- Custom save key -->
+<TabHref
+  tabHrefs={tabs}
+  basePath="Users"
+  saveKey="userDetailTabs"
+/>
+
+<!-- Rounded style -->
+<TabHref
+  tabHrefs={tabs}
+  basePath="Profile"
+  rounded
+/>
+
+<!-- Without Tab prefix in URLs -->
+<TabHref
+  tabHrefs={tabs}
+  basePath="Admin"
+  noTabAdjustments
+/>
+<!-- Generates: /Admin/Profile, /Admin/Settings (no "Tab" prefix) -->
+
+<!-- Bind to slug -->
+<script>
+  let currentSlug = $state<string | null>(null);
+</script>
+
+<TabHref
+  tabHrefs={tabs}
+  basePath="Dashboard"
+  bind:slug={currentSlug}
+/>
+<div>Current tab: {currentSlug}</div>
+
+<!-- Debug mode -->
+<TabHref
+  tabHrefs={tabs}
+  basePath="Debug"
+  consoleLogs
+/>
+```
+
+## Common Patterns
+
+### User Profile Tabs
+```svelte
+<!-- src/routes/Users/User[user_id=integer]/+page.svelte -->
+<script>
+  export let data;
+</script>
+
+<h1>{data.user.name}</h1>
+
+<TabHref
+  tabHrefs={[
+    { key: 'Info', faProps: { icon: faUser } },
+    { key: 'Activity', faProps: { icon: faChartLine } },
+    { key: 'Settings', faProps: { icon: faCog } }
+  ]}
+  basePath="Users/User{data.user.id}"
+  storage="session"
+/>
+<!-- URLs: /Users/User123/TabInfo, /Users/User123/TabActivity, etc. -->
+```
+
+### Master-Detail Layout
+```svelte
+<MasterDetailLayout basePath="Products">
+  {#snippet list()}
+    {#each products as product}
+      <ProductCard {product} />
+    {/each}
+  {/snippet}
+
+  {#snippet detail()}
+    <TabHref
+      tabHrefs={[
+        { key: 'Overview', isInitial: true },
+        { key: 'Specs' },
+        { key: 'Reviews' }
+      ]}
+      basePath="Products/Product{selectedId}"
+    />
+  {/snippet}
+</MasterDetailLayout>
+```
+
+### Conditional Tabs
+```svelte
+<script>
+  let isAdmin = $state(false);
+</script>
+
+<TabHref
+  tabHrefs={[
+    { key: 'Public', title: 'Public Info' },
+    { key: 'Private', title: 'Private Info', hidden: !isAdmin },
+    { key: 'Admin', title: 'Admin Panel', hidden: !isAdmin }
+  ]}
+  basePath="Dashboard"
+/>
+```
+
+### Nested Routes
+```svelte
+<!-- Parent: /Settings -->
+<TabHref
+  tabHrefs={[
+    { key: 'Profile' },
+    { key: 'Security' },
+    { key: 'Billing' }
+  ]}
+  basePath="Settings"
+/>
+
+<!-- Each tab can have its own route file: -->
+<!-- src/routes/Settings/TabProfile/+page.svelte -->
+<!-- src/routes/Settings/TabSecurity/+page.svelte -->
+<!-- src/routes/Settings/TabBilling/+page.svelte -->
+```
+
+## Persistence Behavior
+
+### Session Storage (Default)
+```
+Key: Tab{basePath}
+Example: "TabDashboard" → "TabProfile"
+Lifetime: Until tab/window closed
+```
+
+### Local Storage
+```
+Key: Tab{basePath}
+Example: "TabSettings" → "TabSecurity"
+Lifetime: Permanent (until cleared)
+```
+
+### ID Memory (noIDRemember=false)
+```
+Key: IDTab{basePath}
+Example: "IDTabUsers/User" → "123"
+Remembers: Which user ID you were viewing
+Use case: Return to last viewed user on page revisit
+```
+
+## URL Generation
+
+### Default (with Tab prefix)
+```
+basePath="Dashboard"
+key="Profile"
+→ /Dashboard/TabProfile
+```
+
+### Without Tab prefix (noTabAdjustments=true)
+```
+basePath="Admin"
+key="Users"
+→ /Admin/Users
+```
+
+### Custom href
+```
+basePath="Reports"
+key="Sales"
+href="/reports/sales-summary"
+→ /reports/sales-summary
+```
+
+## Auto-Redirect Behavior
+
+When landing on base path without tab slug:
+1. Check session/local storage for last tab
+2. Use tab with `isInitial: true`
+3. Fall back to first visible tab
+4. Redirect using `replaceState` (no history entry)
+
+## Common Mistakes
+
+- ❌ Not matching route structure to tab paths
+  ✅ Correct: Ensure route files match generated URLs
+
+- ❌ Using TabHref for local state tabs
+  ✅ Correct: Use TabHeader for non-URL tabs
+
+- ❌ Not providing basePath correctly
+  ✅ Correct: Match your SvelteKit route structure
+
+- ❌ Conflicting saveKey across different tab sets
+  ✅ Correct: Use unique saveKey for each TabHref instance
+
+- ❌ Expecting immediate tab switch (it uses goto)
+  ✅ Correct: Navigation is async, uses SvelteKit routing
+
+## Comparison: TabHref vs TabHeader
+
+| Feature | TabHref | TabHeader |
+|---------|---------|-----------|
+| Navigation | URL-based | State-based |
+| Shareable | ✅ Yes | ❌ No |
+| Browser back | ✅ Works | ❌ No effect |
+| Persistence | Storage + URL | Session only |
+| Speed | Page load | Instant |
+| Use case | Pages | Components |
+
+## Related Components
+
+- **TabHeader** - Local state tab navigation
+- **PathAnalyzer** - URL parsing utility
+- **MasterDetailLayout** - Common container
+- **Icon** - Tab icons
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tabHrefs` | `ITabHref[]` | (required) | Tab definitions |
+| `basePath` | `string` | - | Base route path |
+| `slug` | `string \| null` | `null` | Current tab slug ($bindable) |
+| `storage` | `'local' \| 'session' \| null` | `'session'` | Persistence method |
+| `saveKey` | `string \| null` | `null` | Custom storage key |
+| `noIDRemember` | `boolean` | `false` | Disable ID persistence |
+| `noTabAdjustments` | `boolean` | `false` | Skip 'Tab' prefix |
+| `reclickToClose` | `boolean` | `false` | Allow closing active |
+| `bottomMargin` | `boolean` | `true` | Add margin-bottom |
+| `consoleLogs` | `boolean` | `false` | Debug logging |
+| `noResolveHidden` | `boolean` | `false` | Skip hidden redirect |
+| `printAllTabs` | `boolean` | `false` | Print behavior |
+| `rounded` | `boolean` | `false` | Rounded style |
+
+## Styling
+
+Same as TabHeader:
+- Underline style (default)
+- Rounded pill style (rounded=true)
+- Animated indicator
+- `primary-selected` color for active state
+
+## Advanced: PathAnalyzer
+
+The component uses PathAnalyzer for navigation:
+```typescript
+const analyzer = new PathAnalyzer(page, basePath);
+analyzer.open('TabProfile')  // Generate URL
+analyzer.activePageSlug      // Current tab slug
+analyzer.isOpen('TabProfile') // Check if active
+```
+
+See PathAnalyzer utility documentation for advanced usage.