@mhmo91/schmancy 0.8.6 → 0.9.3

package/dist/ai/area.md

@@ -1,282 +1,215 @@
-# Schmancy Area - Routing System
-
-Reactive routing system for web components using RxJS. Supports multiple outlets, guards, lazy loading, and nested routing.
-
-## Quick Start
-
-```html
-<!-- Define routes declaratively -->
-<schmancy-area name="main" default="home-page">
-  <schmancy-route when="products" component="product-list"></schmancy-route>
-  <schmancy-route when="about" component="about-page"></schmancy-route>
-  <schmancy-route
-    when="admin"
-    component="admin-panel"
-    .guard=${authState$.asObservable()}
-    @redirect=${() => area.push({ component: 'login', area: 'main' })}>
-  </schmancy-route>
-</schmancy-area>
-```
+# Area — Routing Foundation
 
-```typescript
-// Navigate programmatically
-import { area } from '@schmancy/area';
+> **Not just a component. The routing framework your app runs on.**
+> `area` is the imperative API. `schmancy-area` is the region where a component lives. `schmancy-route` declares the options.
 
-area.push({
-  component: 'product-detail',
-  area: 'main',
-  params: { productId: '123' },
-  state: { fromCart: true }
-});
-```
-
-## Core Components
-
-### `<schmancy-area>` - Router Outlet
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `name` | `string` | ✓ | Unique outlet identifier |
-| `default` | `ComponentType` | | Fallback when no route matches |
+Routing in Schmancy is four things working together:
 
-### `<schmancy-route>` - Route Definition
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `when` | `string` | ✓ | URL segment or component tag to match |
-| `component` | `RouteComponent` | ✓ | Component to render |
-| `guard` | `Observable<boolean>` | | Navigation guard |
-| `exact` | `boolean` | | Currently unused |
+| Piece | Role |
+|-------|------|
+| `<schmancy-area name="...">` | Declares a named region of the screen |
+| `<schmancy-route when="tag">` | Declares which component can occupy it |
+| `area.push(...)` | Imperative navigation (click handlers, guards, effects) |
+| `lazy(() => import('...'))` | Code-split route components |
 
-## URL Matching
+## The Shape of a Real App
 
-Routes match in DOM order. First match wins.
+Real apps nest areas. Outer `name="root"` handles public vs. authenticated. Inner `name="aria"` handles sub-views inside the authenticated shell.
 
-```html
-<!-- Matches URL segments -->
-<schmancy-route when="products" component="product-list"></schmancy-route>
-<!-- URL: /store/products → segments: ['store', 'products'] → MATCHES -->
+```typescript
+// app root — handles sign-in / public / authenticated
+@customElement('my-app')
+class MyApp extends $LitElement() {
+  render() {
+    return html`
+      <schmancy-theme root scheme="dark">
+        <schmancy-surface type="solid" fill="all">
+          <schmancy-scroll>
+            <schmancy-area
+              name="root"
+              .default=${lazy(() => import('./pages/landing.page'))}
+            >
+              <schmancy-route when="landing-page"
+                .component=${lazy(() => import('./pages/landing.page'))}
+              ></schmancy-route>
+
+              <schmancy-route when="methodology-page"
+                .component=${lazy(() => import('./pages/methodology.page'))}
+              ></schmancy-route>
+
+              <!-- Guarded route -->
+              <schmancy-route when="app-index"
+                .component=${lazy(() => import('./app/app.page'))}
+                .guard=${firebaseAuthState$.pipe(
+                  map(u => !!u && !u.isAnonymous),
+                  takeUntil(this.disconnecting),
+                )}
+                @redirect=${() => area.push({
+                  component: 'landing-page',
+                  area: 'root',
+                  historyStrategy: 'replace',
+                })}
+              ></schmancy-route>
+            </schmancy-area>
+          </schmancy-scroll>
+        </schmancy-surface>
+      </schmancy-theme>
+    `
+  }
+}
+```
 
-<!-- Matches component tag for programmatic nav -->
-<schmancy-route when="user-profile" component="user-profile"></schmancy-route>
-<!-- area.push({ component: 'user-profile', area: 'main' }) → MATCHES -->
+```typescript
+// nested area — inside the app shell
+render() {
+  return html`
+    <schmancy-nav-drawer>
+      <schmancy-nav-drawer-navbar width="180px">
+        <schmancy-list-item @click=${() => area.push({ area: 'aria', component: 'aria-agents-page' })}>
+          Agents
+        </schmancy-list-item>
+        <schmancy-list-item @click=${() => area.push({ area: 'aria', component: 'aria-knowledge-page' })}>
+          Knowledge
+        </schmancy-list-item>
+      </schmancy-nav-drawer-navbar>
+
+      <schmancy-nav-drawer-content>
+        <schmancy-area name="aria" default="aria-knowledge-page">
+          <schmancy-route when="aria-agents-page" .component=${lazy(() => import('./pages/agents'))}></schmancy-route>
+          <schmancy-route when="aria-knowledge-page" .component=${lazy(() => import('./pages/knowledge'))}></schmancy-route>
+          <schmancy-route when="aria-templates-page" .component=${lazy(() => import('./pages/templates'))}></schmancy-route>
+        </schmancy-area>
+      </schmancy-nav-drawer-content>
+    </schmancy-nav-drawer>
+  `
+}
 ```
 
-## Navigation Guards
+## `schmancy-area` Properties
 
-Guards are `Observable<boolean>` that emit true to allow, false to block navigation.
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | ✅ | Unique area identifier referenced in `area.push({ area: name })` |
+| `default` | `RouteComponent \| string` | — | Fallback when no route matches — prefer `lazy()` |
 
-```typescript
-// Simple guard
-const authState$ = new BehaviorSubject(false);
-
-<schmancy-route
-  when="protected"
-  component="protected-page"
-  .guard=${authState$.asObservable()}
-  @redirect=${(e) => {
-    // e.detail contains: blockedRoute, area, params, state
-    $notify.error('Access denied');
-    area.push({ component: 'login', area: 'main' });
-  }}>
-</schmancy-route>
-
-// Complex guard with multiple conditions
-const canAccess$ = combineLatest([authState$, roleState$]).pipe(
-  map(([auth, role]) => auth && role === 'admin')
-);
-```
+## `schmancy-route` Properties
 
-**Important**: Guards return `Observable<boolean>` only. No strings, objects, or redirect paths.
-Handle redirects via `@redirect` event.
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `when` | string | ✅ | **Must exactly match** a `@customElement('tag')` tag name |
+| `component` | `RouteComponent` | ✅ | Class, tag name, or `lazy()` wrapper |
+| `guard` | `Observable<boolean>` | — | When emits `false`, route blocks and fires `@redirect` |
+| `exact` | boolean | — | Strict-equality matching |
 
-## Service API
+## `area` service (imperative API)
 
 ```typescript
-import { area } from '@schmancy/area';
+import { area } from '@mhmo91/schmancy'
 
-// Navigation
 area.push({
-  component: string | Constructor | HTMLElement | LazyComponent,
-  area: string,                          // Required
-  state?: any,                          // Stored in history
-  params?: any,                         // Applied to component
-  props?: any,                          // Alias for params
+  area: 'root',               // target area name
+  component: 'app-index',     // tag name (or class reference)
+  params?: { id: '123' },     // pushed onto area.params()
   historyStrategy?: 'push' | 'replace' | 'silent',
-  clearQueryParams?: string[] | boolean
-});
-
-// Clear area
-area.pop('sidebar');
+})
+```
 
-// Subscriptions (return Observables)
-area.on(areaName)                      // Subscribe to route changes
-area.getState<T>(areaName)            // Get typed state
-area.params<T>(areaName)              // Get typed params
+`historyStrategy`:
+- `'push'` (default) — browser back button returns to previous route
+- `'replace'` — overwrites current history entry (use after guards / redirects)
+- `'silent'` — changes the area without adding any history (transient state)
 
-// Configuration
-area.prettyURL = false                 // JSON-encoded URLs (default)
-area.enableHistoryMode = true          // Browser history (default)
+### Subscribe to route state
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+
+  area.on('root').pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe(route => {
+    console.log('root area is now:', route.component)
+  })
+
+  area.params<{ id: string }>('detail').pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe(params => this.loadItem(params.id))
+}
 ```
 
 ## Lazy Loading
 
+Code-split your routes. `lazy()` returns a preloadable reference.
+
 ```typescript
-import { lazy } from '@schmancy/area';
+import { lazy } from '@mhmo91/schmancy'
 
-// Define lazy components
-const LazyDashboard = lazy(() => import('./dashboard'));
+const HomePage = lazy(() => import('./home.page'))
 
-// Use in routes
-<schmancy-route
-  when="dashboard"
-  .component=${LazyDashboard}>
-</schmancy-route>
+// Optional: preload on hover
+<schmancy-button
+  @mouseenter=${() => HomePage.preload()}
+  @click=${() => area.push({ area: 'root', component: 'home-page' })}
+>
+  Home
+</schmancy-button>
+```
 
-// Preload on hover
-button.addEventListener('mouseenter', () => {
-  LazyDashboard.preload();
-});
+## Guards — the production pattern
 
-// Navigate
-area.push({ component: LazyDashboard, area: 'main' });
-```
+Guards are **RxJS Observables**, not booleans. This lets auth state flow through naturally.
 
-## Nested Routing
-
-```html
-<schmancy-area name="main">
-  <schmancy-route when="app" component="app-layout">
-    <!-- Inside app-layout component -->
-    <schmancy-area name="app-content">
-      <schmancy-route when="users" component="user-list"></schmancy-route>
-      <schmancy-route when="settings" component="settings"></schmancy-route>
-    </schmancy-area>
-  </schmancy-route>
-</schmancy-area>
+```typescript
+import { firebaseAuthState$ } from './contexts/user.context'
+
+<schmancy-route when="app-index"
+  .component=${lazy(() => import('./app/app.page'))}
+  .guard=${firebaseAuthState$.pipe(
+    map(user => !!user && !user.isAnonymous),
+    takeUntil(this.disconnecting),
+  )}
+  @redirect=${() => area.push({
+    component: 'landing-page',
+    area: 'root',
+    historyStrategy: 'replace',
+  })}
+></schmancy-route>
 ```
 
-## Common Patterns
+- `guard` emits `true` → route renders.
+- `guard` emits `false` → Schmancy fires a `redirect` event on the route; handle it with `area.push(...)` using `historyStrategy: 'replace'` so the blocked route doesn't stay in history.
 
-### Protected Routes with Authentication
+## Rules
 
-```typescript
-@customElement('app-shell')
-export class AppShell extends $LitElement() {
-  private authState$ = new BehaviorSubject(false);
-
-  render() {
-    return html`
-      <schmancy-area name="main">
-        <schmancy-route when="home" component="home-page"></schmancy-route>
-
-        <schmancy-route
-          when="dashboard"
-          component="dashboard"
-          .guard=${this.authState$.asObservable()}
-          @redirect=${() => {
-            area.push({ component: 'login', area: 'main' });
-          }}>
-        </schmancy-route>
-      </schmancy-area>
-    `;
-  }
-}
-```
+1. `when="tag-name"` **must exactly match** `@customElement('tag-name')` on the component's class.
+2. Every route component should extend `$LitElement` and use `takeUntil(this.disconnecting)` in subscriptions.
+3. Route components are responsible for their own scroll/focus handling on mount.
+4. When calling `area.push` after auth guards or side-effectful redirects, use `historyStrategy: 'replace'`.
+5. Nested areas are not just allowed — they're the default for any app with a shell + sub-views.
 
-### Multi-Area Application
+## Common recipes
 
-```html
-<!-- Multiple independent outlets -->
-<div class="layout">
-  <schmancy-area name="sidebar" default="nav-menu"></schmancy-area>
-  <schmancy-area name="main" default="home"></schmancy-area>
-  <schmancy-area name="modal"></schmancy-area>
-</div>
+### Redirect after sign-in
+```typescript
+await signIn(email, password)
+area.push({ component: 'app-index', area: 'root', historyStrategy: 'replace' })
 ```
 
+### Silent state swap (no history pollution)
 ```typescript
-// Navigate different areas independently
-area.push({ component: 'user-list', area: 'main' });
-area.push({ component: 'quick-stats', area: 'sidebar' });
-area.push({ component: 'edit-dialog', area: 'modal' });
-
-// Clear modal
-area.pop('modal');
+// e.g. swapping between auth screens without adding history
+area.push({ component: 'signup-form', area: 'sign', historyStrategy: 'silent' })
 ```
 
-## Type Definitions
-
+### Click-driven sub-nav
 ```typescript
-// Navigation request
-interface RouteAction {
-  component: ComponentType;
-  area: string;
-  state?: Record<string, any>;
-  params?: Record<string, any>;
-  props?: Record<string, any>;  // Alias for params
-  historyStrategy?: 'push' | 'replace' | 'silent';
-  clearQueryParams?: string[] | boolean;
-}
-
-// Guard type
-type ObservableGuardResult = Observable<boolean>;
-
-// Component types
-type RouteComponent =
-  | string                                           // Tag name
-  | CustomElementConstructor                        // Class
-  | HTMLElement                                     // Instance
-  | (() => Promise<{ default: Constructor }>)      // Lazy
-
-// Redirect event detail
-interface RedirectEventDetail {
-  blockedRoute: string;
-  area: string;
-  params: Record<string, any>;
-  state: Record<string, any>;
-}
+<schmancy-list-item @click=${() => area.push({ area: 'aria', component: 'aria-agents-page' })}>
+  Agents
+</schmancy-list-item>
 ```
 
-## Internal Behavior
-
-### Route Resolution Pipeline
-1. Receives navigation request (programmatic, URL, or browser)
-2. Resolves lazy components to constructors
-3. Deduplicates identical routes
-4. Evaluates guard Observable
-5. Creates element and applies properties
-6. Swaps components with 150ms fade animation
-
-### Route Evaluation Order
-- Routes evaluated in DOM order
-- First matching route wins
-- Empty `when=""` acts as catch-all
-
-### History Management
-- JSON-encoded URLs by default: `/%7B%22main%22%3A%7B%22component%22%3A%22home%22%7D%7D`
-- Pretty URLs optional: `/products?id=123`
-- State stored in `history.state.schmancyAreas`
-
-## Troubleshooting
-
-**Routes not matching**
-- Check route order (specific before general)
-- Verify `when` matches URL segment or component tag
-
-**Guards not working**
-- Must be `Observable<boolean>`, not functions
-- Use `.asObservable()` on BehaviorSubjects
-- Handle redirects in `@redirect` event
-
-**Nested routes failing**
-- Each area needs unique name
-- Parent must render child `<schmancy-area>`
-
-**area.pop() not clearing**
-- Verify area name is correct
-- Check no immediate re-navigation
-
-## Related Components
+### Preload routes on hover
+```typescript
+const DashboardPage = lazy(() => import('./dashboard.page'))
 
-- **[Store](./store.md)** - State management
-- **[Sheet](./sheet.md)** - Modal overlays
-- **[Layout](./layout.md)** - Responsive layouts
+html`<a @mouseenter=${() => DashboardPage.preload()} @click=${() => area.push({ area: 'root', component: 'dashboard-page' })}>Dashboard</a>`
+```