@mhmo91/schmancy 0.4.89 → 0.4.90

package/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.