@mhmo91/schmancy 0.4.89 → 0.4.90

package/dist/ai/area.md

@@ -22,7 +22,7 @@ The main container that displays routed components.
 ```
 
 ### 2. `<schmancy-route>` - Declarative Routing
-Define routes declaratively with segment matching and guards.
+Define routes declaratively with segment matching and guards. Routes are detected via slot change detection and are evaluated in order.
 
 ```html
 <!-- Simple route -->
@@ -44,13 +44,6 @@ Define routes declaratively with segment matching and guards.
   component="admin-panel"
   .guard=${() => isAuthenticated()}>
 </schmancy-route>
-
-<!-- Route with default component -->
-<schmancy-route
-  when="dashboard"
-  component="dashboard-main"
-  default="dashboard-overview">
-</schmancy-route>
 ```
 
 ## Properties Reference
@@ -60,53 +53,69 @@ Define routes declaratively with segment matching and guards.
 | Property | Type | Description |
 |----------|------|-------------|
 | `name` | `string` | **Required**. Unique identifier for this router outlet. |
-| `default` | `string \| Promise<NodeModule> \| CustomElementConstructor \| TemplateResult` | Default component to display when no route matches or area is empty. |
+| `default` | `string \| Promise<NodeModule> \| CustomElementConstructor \| HTMLElement \| LazyComponent` | Default component to display when no route matches or area is empty. |
 
 ### `<schmancy-route>` Properties
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `when` | `string` | **Required**. URL segment name OR component tag name to match. NOT a full path! |
-| `component` | `any` | Component to render when route matches (string, constructor, element). |
+| `when` | `string` | **Required**. URL segment to match OR component tag name for programmatic navigation. |
+| `component` | `RouteComponent` | Component to render when route matches (string, constructor, element, lazy component). |
 | `exact` | `boolean` | Whether route should match exactly (default: false). |
-| `guard` | `() => GuardResult \| Promise<GuardResult>` | Navigation guard function returning boolean, string, or redirect object. |
+| `guard` | `() => GuardResult \| Promise<GuardResult>` | Navigation guard function. |
+
+Note: `<schmancy-route>` does NOT have a `default` property - that's only available on `<schmancy-area>`.
 
-## URL Segment Matching
+## URL Matching Behavior
 
-The `when` attribute supports powerful segment-based routing:
+The routing system uses multiple strategies to match routes:
+
+### 1. **URL Segment Matching**
+The URL path is split by '/' and the `when` attribute is checked against each segment in the array:
 
 ```html
 <!-- Segment name matching -->
-<schmancy-route when="home" component="home-page"></schmancy-route>
-<!-- Matches: /home, /app/home, any URL containing 'home' segment -->
+<schmancy-route when="products" component="product-list"></schmancy-route>
+<!-- URL: /store/products/123 → segments: ['store', 'products', '123'] → MATCHES (products is in array) -->
+<!-- URL: /products → segments: ['products'] → MATCHES -->
+<!-- URL: /home → segments: ['home'] → DOES NOT MATCH -->
+```
 
-<!-- Component name matching -->
-<schmancy-route when="user-profile" component="user-profile"></schmancy-route>
-<!-- Matches when routing to 'user-profile' component -->
+### 2. **Component Tag Name Matching**
+For programmatic navigation, the `when` attribute can match the component tag name:
 
-<!-- Admin section matching -->
-<schmancy-route when="admin" component="admin-layout"></schmancy-route>
-<!-- Matches: /admin, /admin/users, /app/admin, etc. -->
+```html
+<schmancy-route when="user-profile" component="user-profile"></schmancy-route>
+<!-- When navigating with: area.push({ component: 'user-profile', area: 'main' }) → MATCHES -->
+```
 
-<!-- Product section matching -->
-<schmancy-route when="products" component="product-list"></schmancy-route>
-<!-- Matches: /products, /store/products, /products/123, etc. -->
+### 3. **JSON-Encoded State in URL**
+When pretty URLs are disabled (default), the router encodes state as JSON in the URL:
 
-<!-- About page matching -->
-<schmancy-route when="about" component="about-page"></schmancy-route>
-<!-- Matches: /about, /info/about, /about/team, etc. -->
+```javascript
+// URL: /%7B%22main%22%3A%7B%22component%22%3A%22user-profile%22%7D%7D
+// Decoded: {"main":{"component":"user-profile"}}
+// The router extracts this and matches against routes
 ```
 
-### Segment Matching Rules
+### Matching Priority
 
-1. **Exact segments**: `/products` matches only `/products`
-2. **Dynamic parameters**: `:id` captures any value in that position
-3. **Wildcards**: `*` matches any remaining path segments
-4. **Priority**: More specific routes take precedence over wildcards
+Routes are evaluated in the order they appear in the DOM. The first matching route wins:
+
+```html
+<schmancy-area name="main">
+  <!-- Evaluated first -->
+  <schmancy-route when="user" component="user-detail"></schmancy-route>
+  <!-- Evaluated second -->
+  <schmancy-route when="users" component="user-list"></schmancy-route>
+  <!-- Catch-all (empty when) evaluated last -->
+  <schmancy-route when="" component="not-found"></schmancy-route>
+</schmancy-area>
+```
 
 ## Navigation Guards
 
-Guards protect routes and can redirect navigation:
+Guards protect routes and can redirect navigation. Guards are executed before component creation for better performance:
 
 ```typescript
 // Boolean guard - simple allow/deny
@@ -154,11 +163,13 @@ Guards protect routes and can redirect navigation:
 | Return Value | Behavior |
 |--------------|----------|
 | `true` | Allow navigation to proceed |
-| `false` | Block navigation silently |
-| `"/path"` (string) | Redirect to the specified path |
+| `false` | Block navigation silently, falls back to default if specified |
+| `"/path"` (string) | Redirect to the specified path segment |
 | `{redirect: "/path"}` | Explicit redirect object |
 | `Promise<...>` | Async guard, resolved before navigation |
 
+**Note**: Guard failures (`false` return) will fall back to the area's `default` component if specified. Redirects trigger a new route lookup based on the redirect path segment.
+
 ## Nested Routing
 
 Create complex nested routing structures:
@@ -220,28 +231,44 @@ import { area } from '@schmancy/index';
 
 // Navigation methods
 area.push({
-  component: 'user-profile',      // Component constructor, string tag name, or element instance
-  area: 'main',                   // Target area name
-  state?: { view: 'profile' },    // Optional state object
-  params?: { id: '123' },         // Optional query parameters
-  props?: { userId: '123' },      // Optional component properties
-  historyStrategy: 'push',        // 'push', 'replace', 'pop', 'silent'
-  clearQueryParams?: ['sort']     // Clear specific query params
+  component: 'user-profile',      // Component constructor, string tag name, element instance, or lazy component
+  area: 'main',                   // Target area name (required)
+  state?: { view: 'profile' },    // Optional state object (stored in history)
+  params?: { id: '123' },         // Optional query parameters (NOT URL query params - these are component params)
+  props?: { userId: '123' },      // Optional component properties (alias for params, applied to component)
+  historyStrategy?: 'push',       // 'push' | 'replace' | 'pop' | 'silent' (default: 'push')
+  clearQueryParams?: ['sort']     // Clear specific URL query params
 });
 
-// Remove/clear an area (fixed in latest version)
-area.pop('sidebar');              // Properly removes content from area
+// Remove/clear an area - sends clearing signal to area
+area.pop('sidebar');              // Clears the area content and updates history
 
 // Subscription methods (return RxJS Observables)
-area.on(areaName, skipCurrent?)   // Subscribe to an area
-area.all(skipCurrent?)            // Subscribe to all areas
-area.getState<T>(areaName)        // Get typed state from an area
-area.params<T>(areaName)          // Get typed query params from an area
-area.param<T>(areaName, key)      // Get a specific query param value
-area.props<T>(areaName)           // Get typed component props from an area
-area.prop<T>(areaName, key)       // Get a specific component prop value
+area.on(areaName, skipCurrent?)          // Subscribe to an area's route changes
+area.all(skipCurrent?)                   // Subscribe to all areas
+area.getState<T>(areaName)              // Get typed state from an area
+area.params<T>(areaName)                // Get typed params from an area
+area.param<T>(areaName, key)            // Get a specific param value
+area.props<T>(areaName)                 // Get typed props from an area
+area.prop<T>(areaName, key)             // Get a specific prop value
+
+// Utility methods
+area.hasArea(areaName)                  // Check if an area exists
+area.getActiveAreas()                    // Get array of active area names
+area.getRoute(areaName)                 // Get route synchronously (returns ActiveRoute | undefined)
+
+// Configuration
+area.prettyURL = false                  // Enable pretty URLs (default: false uses JSON encoding)
+area.mode = 'HISTORY'                   // 'HISTORY' | 'SILENT' (default: 'HISTORY')
+area.enableHistoryMode = true           // Enable browser history management (default: true)
 ```
 
+### Important Distinctions:
+- **`params`**: Component-level parameters that are passed as properties to the component instance
+- **`props`**: Alias for params - both are applied directly to the component element
+- **`state`**: Arbitrary data stored in browser history, accessible via subscriptions
+- **URL Query Parameters**: Managed separately via `clearQueryParams` option
+
 ## Common Patterns
 
 ### Basic Navigation
@@ -302,7 +329,7 @@ area.push({
 </schmancy-area>
 ```
 
-### Programmatic Navigation with area.pop()
+### Clearing Areas with area.pop()
 
 ```typescript
 // Open a modal or sidebar
@@ -312,11 +339,14 @@ area.push({
   props: { userId: '123' }
 });
 
-// Close/clear the modal (fixed in latest version)
-area.pop('modal');  // This now properly clears the area
+// Clear the modal - sends clearing signal to area component
+area.pop('modal');  // Component receives null signal and clears content
 
 // Clear multiple areas
 ['modal', 'sidebar', 'overlay'].forEach(name => area.pop(name));
+
+// Note: area.pop() now properly sends a clearing signal through the RxJS pipeline
+// The area component will receive a route with null component and remove its content
 ```
 
 ### Reactive Subscriptions
@@ -438,12 +468,12 @@ class AppLayout extends LitElement {
 
 #### Using the `lazy()` helper function
 
-Schmancy Area provides a powerful `lazy()` function similar to React.lazy() for optimal code splitting:
+Schmancy Area provides a powerful `lazy()` function similar to React.lazy() for optimal code splitting. Lazy components are resolved to constructors before element creation for better performance:
 
 ```typescript
 import { lazy } from '@schmancy/area';
 
-// Create lazy-loaded components
+// Create lazy-loaded components with default exports
 const LazyDashboard = lazy(() => import('./components/dashboard'));
 const LazyAnalytics = lazy(() => import('./components/analytics'));
 const LazyReports = lazy(() => import('./components/reports'));
@@ -467,20 +497,23 @@ area.push({
 
 #### Preloading Components
 
-Lazy components support preloading for better perceived performance:
+Lazy components support preloading for better perceived performance. The lazy() function caches both the loading promise and the loaded module:
 
 ```typescript
 const LazyProfile = lazy(() => import('./profile'));
 
 // Preload on hover for instant navigation
 button.addEventListener('mouseenter', () => {
-  LazyProfile.preload();
+  LazyProfile.preload();  // Starts loading and caches the promise
 });
 
-// Preload after initial page load
+// The component will be instantly available when navigated to
+area.push({ component: LazyProfile, area: 'main' });  // Uses cached module
+
+// Preload critical routes after initial page load
 window.addEventListener('load', () => {
   setTimeout(() => {
-    LazyProfile.preload();
+    LazyProfile.preload();    // Caches for future use
     LazySettings.preload();
   }, 2000);
 });
@@ -673,6 +706,123 @@ html`
 `;
 ```
 
+## History Management
+
+The router manages browser history automatically, storing state in `history.state.schmancyAreas`:
+
+### Browser State Structure
+```javascript
+// Browser history.state structure:
+{
+  schmancyAreas: {
+    main: {
+      component: 'user-profile',
+      state: { view: 'edit' },
+      params: { userId: '123' },
+      area: 'main'
+    },
+    sidebar: {
+      component: 'nav-menu',
+      area: 'sidebar'
+    }
+  }
+}
+```
+
+### URL Encoding Modes
+
+#### 1. **JSON Encoding (Default)**
+When `area.prettyURL = false` (default), state is encoded as JSON in the URL:
+```javascript
+// URL: /%7B%22main%22%3A%7B%22component%22%3A%22user-profile%22%7D%7D
+// Decoded: {"main":{"component":"user-profile"}}
+```
+
+#### 2. **Pretty URLs**
+When `area.prettyURL = true`, creates cleaner URLs:
+```javascript
+area.prettyURL = true;
+// URL: /user-profile?userId=123
+// Component and simple params are included in the URL
+```
+
+### History Strategies
+
+```typescript
+area.push({
+  component: 'page',
+  area: 'main',
+  historyStrategy: 'push'  // Options: 'push' | 'replace' | 'pop' | 'silent'
+});
+
+// 'push': Adds new entry to history (default)
+// 'replace': Replaces current history entry
+// 'pop': Updates during back/forward navigation
+// 'silent': No history update
+```
+
+## Internal Behaviors
+
+### Component Lifecycle
+
+1. **Route Resolution Pipeline**:
+   - Route request received (programmatic, URL, or browser navigation)
+   - Lazy components resolved to constructors (if applicable)
+   - Component identifier extracted for deduplication
+   - Route deduplicated using `distinctUntilChanged`
+   - HTMLElement created and properties applied
+   - Component swapped with animation
+
+2. **Component Swapping Animation**:
+   - Old component fades out (150ms)
+   - Old component removed from DOM
+   - New component added to shadow DOM
+   - New component fades in (150ms)
+
+3. **Deduplication Strategy**:
+   Components are deduplicated based on:
+   - Component identifier (tag name or constructor name)
+   - JSON stringified params
+   - JSON stringified state
+
+   This prevents unnecessary re-renders when navigating to the same route.
+
+### RxJS Pipeline Architecture
+
+The area component uses a sophisticated RxJS pipeline:
+
+```typescript
+// Three navigation sources merged into one stream:
+merge(
+  area.request,           // Programmatic navigation
+  of(location.pathname),  // Initial load
+  fromEvent('popstate')    // Browser back/forward
+)
+.pipe(
+  // Resolve lazy components
+  switchMap(/* ... */),
+
+  // Deduplicate identical routes
+  distinctUntilChanged(/* ... */),
+
+  // Share single subscription
+  shareReplay(1),
+
+  // Handle errors gracefully
+  catchError(/* ... */),
+
+  // Cleanup on disconnect
+  takeUntil(this.disconnecting)
+)
+```
+
+### Error Handling
+
+- **Lazy Load Failures**: Logged to console, component set to null
+- **Component Creation Failures**: Logged to console, gracefully skipped
+- **Guard Errors**: Caught and fall back to default component
+- **Navigation Errors**: Logged and return EMPTY observable
+
 ## Migration Guide
 
 ### From Direct area.push() to Declarative Routes
@@ -815,47 +965,67 @@ area.on('protected-area').pipe(
 ```typescript
 // Route Action - used for navigation
 interface RouteAction {
-  component: CustomElementConstructor | string | HTMLElement | Promise<NodeModule> | LazyComponent;
-  area: string;
-  state?: Record<string, unknown>;
-  params?: Record<string, unknown>;  // Query parameters
-  props?: Record<string, unknown>;   // Component properties
+  component: CustomElementConstructor | string | HTMLElement | (() => Promise<{ default: CustomElementConstructor }>);
+  area: string;                                        // Required
+  state?: Record<string, unknown>;                     // State stored in history
+  params?: Record<string, unknown>;                    // Component properties
+  props?: Record<string, unknown>;                     // Alias for params
   historyStrategy?: 'push' | 'replace' | 'pop' | 'silent';
-  clearQueryParams?: string[] | null;
+  clearQueryParams?: string[] | boolean | null;        // Clear URL query params
+  _source?: 'programmatic' | 'browser' | 'initial';    // Internal use only
 }
 
 // Active Route - current state of an area
 interface ActiveRoute {
-  component: string;
+  component: string;                    // Always resolved to tag name
   area: string;
   state?: Record<string, unknown>;
-  params?: Record<string, unknown>;  // Query parameters
-  props?: Record<string, unknown>;   // Component properties
+  params?: Record<string, unknown>;     // Component properties
+  props?: Record<string, unknown>;      // Component properties
 }
 
-// Guard function signatures (from route.component.ts)
+// Guard function signatures
 export type GuardResult = boolean | string | { redirect: string };
 type GuardFunction = () => GuardResult | Promise<GuardResult>;
 
-// Route component props
-interface RouteProps {
-  when: string;                    // URL segment pattern
-  component?: string | CustomElementConstructor | HTMLElement | LazyComponent;
-  default?: string | CustomElementConstructor | HTMLElement | LazyComponent;
-  guard?: GuardFunction;
+// Route Component Types
+export type RouteComponent =
+  | string                                              // Tag name
+  | CustomElementConstructor                           // Constructor function
+  | HTMLElement                                        // Existing element
+  | TemplateResult<1>                                  // Lit template
+  | (() => Promise<{ default: CustomElementConstructor }>) // Lazy loader
+  | Promise<{ default: CustomElementConstructor }>;    // Dynamic import
+
+// Route configuration (from route.component.ts)
+interface RouteConfig {
+  when: string;                         // URL segment to match
+  component: RouteComponent;
+  exact?: boolean;                      // Not actively used in current implementation
+  guard?: () => GuardResult | Promise<GuardResult>;
 }
 
-// Lazy Loading Types (from lazy.ts)
-type CustomElementConstructor = typeof HTMLElement;
-
 // LazyComponent interface with preload capability
 interface LazyComponent<T extends CustomElementConstructor = CustomElementConstructor> {
   (): Promise<{ default: T }>;
   preload(): Promise<void>;
-  _promise?: Promise<{ default: T }>;
-  _module?: { default: T };
+  _promise?: Promise<{ default: T }>;   // Cached loading promise
+  _module?: { default: T };             // Cached loaded module
 }
 
+// Browser History State Structure
+interface SchmancyHistoryState {
+  schmancyAreas: Record<string, ActiveRoute>;
+  [key: string]: any;                   // Allow other apps to store additional state
+}
+
+// History Strategy Enum
+enum HISTORY_STRATEGY {
+  push = 'push',
+  replace = 'replace',
+  pop = 'pop',
+  silent = 'silent'
+}
 ```
 
 ## Related Components
@@ -881,14 +1051,19 @@ interface LazyComponent<T extends CustomElementConstructor = CustomElementConstr
 ## Summary
 
 Schmancy Area provides a complete routing solution with:
-- ✅ **Declarative routing** with `<schmancy-route>`
-- ✅ **Segment-based matching** with parameters and wildcards
-- ✅ **Navigation guards** with multiple return types
+- ✅ **Declarative routing** with `<schmancy-route>` using slot detection
+- ✅ **URL segment matching** - splits paths and checks for segment presence
+- ✅ **Navigation guards** with boolean, string, and object return types
 - ✅ **Nested routing** support for complex applications
-- ✅ **Default components** for fallback UI
-- ✅ **Reactive subscriptions** with RxJS
-- ✅ **Type-safe** API with TypeScript
+- ✅ **Default components** for fallback UI (area-level only)
+- ✅ **Reactive subscriptions** with RxJS observables
+- ✅ **Type-safe** API with TypeScript support
 - ✅ **Multiple router outlets** for complex layouts
-- ✅ **Fixed area.pop()** functionality for proper cleanup
+- ✅ **Proper area.pop()** sends clearing signals through RxJS pipeline
+- ✅ **Lazy loading** with caching and preload support
+- ✅ **History management** with JSON encoding or pretty URLs
+- ✅ **Animation transitions** during component swapping (150ms fade)
+- ✅ **Deduplication** prevents unnecessary re-renders
+- ✅ **Error handling** with graceful fallbacks
 
 The combination of declarative routes and programmatic navigation provides maximum flexibility for building modern web applications.

package/dist/area.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("./route.component-B-uzbNko.cjs"),e=require("./lazy-DObpkuL6.cjs");exports.FINDING_MORTIES=t.FINDING_MORTIES,exports.HERE_RICKY=t.HERE_RICKY,exports.HISTORY_STRATEGY=t.HISTORY_STRATEGY,Object.defineProperty(exports,"SchmancyArea",{enumerable:!0,get:()=>t.SchmancyArea}),Object.defineProperty(exports,"SchmancyRoute",{enumerable:!0,get:()=>t.SchmancyRoute}),exports.area=t.area,exports.routerHistory=t.routerHistory,exports.buildQueryString=e.buildQueryString,exports.compareActiveRoutes=e.compareActiveRoutes,exports.compareCustomElementConstructors=e.compareCustomElementConstructors,exports.compareRouteActions=e.compareRouteActions,exports.createRouteCacheKey=e.createRouteCacheKey,exports.debounce=e.debounce,exports.decodeRouteState=e.decodeRouteState,exports.deepMerge=e.deepMerge,exports.encodeRouteState=e.encodeRouteState,exports.extractQueryParams=e.extractQueryParams,exports.getTagName=e.getTagName,exports.isObject=e.isObject,exports.lazy=e.lazy,exports.normalizeTagName=e.normalizeTagName,exports.sanitizeRouteState=e.sanitizeRouteState;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("./route.component-kP_bl5DX.cjs"),e=require("./lazy-DObpkuL6.cjs");exports.FINDING_MORTIES=t.FINDING_MORTIES,exports.HERE_RICKY=t.HERE_RICKY,exports.HISTORY_STRATEGY=t.HISTORY_STRATEGY,Object.defineProperty(exports,"SchmancyArea",{enumerable:!0,get:()=>t.SchmancyArea}),Object.defineProperty(exports,"SchmancyRoute",{enumerable:!0,get:()=>t.SchmancyRoute}),exports.area=t.area,exports.routerHistory=t.routerHistory,exports.buildQueryString=e.buildQueryString,exports.compareActiveRoutes=e.compareActiveRoutes,exports.compareCustomElementConstructors=e.compareCustomElementConstructors,exports.compareRouteActions=e.compareRouteActions,exports.createRouteCacheKey=e.createRouteCacheKey,exports.debounce=e.debounce,exports.decodeRouteState=e.decodeRouteState,exports.deepMerge=e.deepMerge,exports.encodeRouteState=e.encodeRouteState,exports.extractQueryParams=e.extractQueryParams,exports.getTagName=e.getTagName,exports.isObject=e.isObject,exports.lazy=e.lazy,exports.normalizeTagName=e.normalizeTagName,exports.sanitizeRouteState=e.sanitizeRouteState;
 //# sourceMappingURL=area.cjs.map

package/dist/area.js

@@ -1,4 +1,4 @@
-import { F as s, H as t, c as o, S as r, a as c, b as m, r as u } from "./route.component-d8kvuxqB.js";
+import { F as s, H as t, c as o, S as r, a as c, b as m, r as u } from "./route.component-CGJfnuN5.js";
 import { l as n, h as i, c as S, f as d, j as y, a as g, b as p, d as T, e as b, k as l, g as E, i as I, m as h, n as A, s as C } from "./lazy-E2LCDm7n.js";
 export {
   s as FINDING_MORTIES,

package/dist/{avatar-CBVbma9p.js → avatar-BNmDgcCL.js}

@@ -2,7 +2,7 @@ import { css as O, html as c, nothing as lt } from "lit";
 import { property as l, customElement as y, state as d, queryAssignedElements as ct, query as F } from "lit/decorators.js";
 import { Subject as V, merge as G, fromEvent as f, startWith as bt, map as v, debounceTime as R, tap as D, distinctUntilChanged as K, takeUntil as m, from as st, of as U, Observable as gt, zip as it, filter as dt, take as ft, timeout as vt, bufferTime as wt, concatMap as xt, interval as $t, throwIfEmpty as Ct } from "rxjs";
 import "./animated-text-CE25uxIq.js";
-import { b as rt, F as St, H as Et } from "./route.component-d8kvuxqB.js";
+import { b as rt, F as St, H as Et } from "./route.component-CGJfnuN5.js";
 import "./autocomplete-BrcVARei.js";
 import "lit/directives/class-map.js";
 import "lit/directives/style-map.js";
@@ -651,4 +651,4 @@ export {
   os as s,
   A as t
 };
-//# sourceMappingURL=avatar-CBVbma9p.js.map
+//# sourceMappingURL=avatar-BNmDgcCL.js.map