@mhmo91/schmancy 0.9.3 → 0.9.5

package/src/area/readme.md

@@ -1,338 +0,0 @@
-# Schmancy Area
-
-A lightweight, reactive routing and state management system for web components.
-
-## Overview
-
-Schmancy Area simplifies client-side routing for web component applications by providing a seamless way to handle navigation, component loading, and state management with a minimal API.
-
-```typescript
-// Define router outlets in your template
-<schmancy-area name="main" default="home-page"></schmancy-area>
-
-// Navigate to a component
-area.push({
-  component: 'user-profile',
-  area: 'main',
-  params: { userId: '123' }
-});
-
-// Subscribe to changes
-area.on('main').subscribe(route => {
-  console.log(`Component: ${route.component}`);
-});
-```
-
-## Installation
-
-```bash
-npm install @schmancy/area
-```
-
-## Basic Usage
-
-### Define Router Areas
-
-Place `<schmancy-area>` elements wherever you want dynamic components to render:
-
-```html
-<!-- Main content area -->
-<schmancy-area name="main" default="home-page"></schmancy-area>
-
-<!-- Optional additional areas -->
-<schmancy-area name="sidebar"></schmancy-area>
-<schmancy-area name="modal"></schmancy-area>
-```
-
-Each area is an independent router outlet that can display different components.
-
-### Navigate Between Views
-
-```typescript
-import { area } from '@schmancy/area';
-
-// Using a tag name
-area.push({
-  component: 'user-profile',
-  area: 'main',
-  params: { userId: '123' }
-});
-
-// Using a component constructor
-area.push({
-  component: UserProfileComponent,
-  area: 'main',
-  state: { view: 'details' }
-});
-
-// Using a component instance
-const customElement = document.createElement('custom-element');
-customElement.setAttribute('custom-attr', 'value');
-area.push({
-  component: customElement,
-  area: 'main'
-});
-
-// Using a dynamic import (lazy-loading)
-area.push({
-  component: import('./components/heavy-dashboard.js'),
-  area: 'main'
-});
-```
-
-### Subscribe to Area Changes
-
-The area service provides a reactive API for subscribing to navigation changes:
-
-```typescript
-// Subscribe to a specific area
-area.on('main').subscribe(route => {
-  console.log('Component:', route.component);
-  console.log('Params:', route.params);
-  console.log('State:', route.state);
-});
-
-// Monitor all active routes
-area.all().subscribe(routes => {
-  console.log('Active routes:', routes);
-});
-```
-
-### Type-Safe State and Parameters
-
-Use TypeScript generics for type safety:
-
-```typescript
-// Type-safe state
-interface UserState {
-  name: string;
-  permissions: string[];
-}
-
-area.getState<UserState>('user').subscribe(state => {
-  console.log(`User: ${state.name}`);
-  console.log(`Permissions: ${state.permissions.join(', ')}`);
-});
-
-// Type-safe parameters
-area.params<{ id: string }>('user').subscribe(params => {
-  fetchUser(params.id);
-});
-
-// Get a specific parameter value
-area.param<string>('user', 'id').subscribe(id => {
-  console.log('User ID:', id);
-});
-```
-
-## Advanced Features
-
-### History Strategy Options
-
-Control how the browser history is updated:
-
-```typescript
-area.push({
-  component: 'user-profile',
-  area: 'main',
-  historyStrategy: 'push'    // Adds a new history entry (default)
-});
-
-area.push({
-  component: 'settings',
-  area: 'main',
-  historyStrategy: 'replace' // Replaces the current history entry
-});
-
-area.push({
-  component: 'sidebar-menu',
-  area: 'sidebar',
-  historyStrategy: 'silent'  // No history change
-});
-
-area.push({
-  component: 'menu',
-  area: 'popup',
-  historyStrategy: 'pop'     // Similar to replace
-});
-```
-
-### Managing Query Parameters
-
-Clear specific query parameters during navigation:
-
-```typescript
-area.push({
-  component: 'search-results',
-  area: 'main',
-  params: { query: 'new-search' },
-  clearQueryParams: ['page', 'sort'] // Removes these query params
-});
-```
-
-### Remove Areas
-
-Remove an area from the current state:
-
-```typescript
-// Remove the 'modal' area
-area.pop('modal');
-```
-
-### DOM Event Listening
-
-For non-RxJS consumers, area changes also dispatch DOM events:
-
-```javascript
-// Format: schmancy-area-${areaName}-changed
-window.addEventListener('schmancy-area-main-changed', event => {
-  const { component, params, state } = event.detail;
-  updateUI(component, params, state);
-});
-```
-
-## API Reference
-
-### SchmancyArea Component
-
-```typescript
-@customElement('schmancy-area')
-export class SchmancyArea extends LitElement {
-  /**
-   * The name of the router outlet
-   * @required
-   */
-  @property() name!: string;
-  
-  /**
-   * Default component to display if none is specified
-   * Can be a tag name, component constructor, or template
-   */
-  @property() default!: string | Promise<NodeModule> | CustomElementConstructor | TemplateResult<1>;
-}
-```
-
-### Area Service
-
-```typescript
-// Navigation
-area.push(routeAction: RouteAction): void
-area.pop(areaName: string): void
-
-// Subscriptions
-area.on(areaName: string, skipCurrent?: boolean): Observable<ActiveRoute>
-area.all(skipCurrent?: boolean): Observable<Map<string, ActiveRoute>>
-area.getState<T>(areaName: string): Observable<T>
-area.params<T>(areaName: string): Observable<T>
-area.param<T>(areaName: string, key: string): Observable<T>
-
-// URL State
-area.state: Record<string, unknown> // Current URL state object
-```
-
-### Types
-
-```typescript
-// Route Action - used for navigation
-interface RouteAction {
-  component: CustomElementConstructor | string | HTMLElement | Promise<NodeModule>;
-  area: string;
-  state?: Record<string, unknown>;
-  params?: Record<string, unknown>;
-  historyStrategy?: 'push' | 'replace' | 'pop' | 'silent';
-  clearQueryParams?: string[] | null;
-}
-
-// Active Route - current state of an area
-interface ActiveRoute {
-  component: string;
-  area: string;
-  state?: Record<string, unknown>;
-  params?: Record<string, unknown>;
-}
-```
-
-## Integration with Other Schmancy Components
-
-Schmancy Area works seamlessly with:
-- **Schmancy Store** for more complex state management
-- **Schmancy Layout** for responsive layouts
-- **Schmancy Teleport** for advanced component transportation
-- **Schmancy Sheet** for modal overlays
-
-## Examples
-
-### Basic Navigation
-
-```typescript
-// Define router outlets
-<schmancy-area name="main" default="home-page"></schmancy-area>
-
-// Navigate to a component
-area.push({
-  component: 'user-profile',
-  area: 'main'
-});
-```
-
-### Parameters and State
-
-```typescript
-// Navigate with params and state
-area.push({
-  component: 'product-detail',
-  area: 'main',
-  params: { productId: '12345' },
-  state: { showReviews: true }
-});
-
-// Access params and state
-area.param<string>('main', 'productId').subscribe(id => {
-  fetchProduct(id);
-});
-
-area.getState<{ showReviews: boolean }>('main').subscribe(state => {
-  if (state.showReviews) {
-    loadReviews();
-  }
-});
-```
-
-### Multiple Independent Areas
-
-```typescript
-// Define multiple areas
-<schmancy-area name="main"></schmancy-area>
-<schmancy-area name="sidebar"></schmancy-area>
-<schmancy-area name="modal"></schmancy-area>
-
-// Update each area independently
-area.push({ component: 'product-list', area: 'main' });
-area.push({ component: 'filter-panel', area: 'sidebar' });
-area.push({ component: 'quick-view', area: 'modal', params: { id: '123' } });
-
-// Remove a modal
-area.pop('modal');
-```
-
-### Navigation Guards
-
-```typescript
-area.on('protected-area').pipe(
-  switchMap(route => {
-    if (!isAuthenticated()) {
-      area.push({ component: 'login-page', area: 'main' });
-      return EMPTY;
-    }
-    return of(route);
-  })
-).subscribe(handleProtectedRoute);
-```
-
-## Best Practices
-
-1. **Define clear area responsibilities** - Each area should have a well-defined purpose
-2. **Use type-safe state and params** - Leverage TypeScript generics for type safety
-3. **Unsubscribe from observables** - Always clean up subscriptions in disconnectedCallback()
-4. **Be consistent with history strategies** - Use the same strategy for similar navigation patterns
-5. **Consider using default components** - Provide fallback components for empty areas

package/src/area/router-guide.md

@@ -1,360 +0,0 @@
-# Schmancy Area Router - Developer Guide
-
-## Quick Start Examples
-
-### Example 1: Basic Navigation
-
-```typescript
-import { area, HISTORY_STRATEGY } from '@schmancy/area'
-import { LitElement, html } from 'lit'
-import { customElement } from 'lit/decorators.js'
-
-// Define your page components
-@customElement('page-home')
-class PageHome extends LitElement {
-  render() {
-    return html`<h1>Welcome Home!</h1>`
-  }
-}
-
-@customElement('page-about')
-class PageAbout extends LitElement {
-  render() {
-    return html`<h1>About Us</h1>`
-  }
-}
-
-// Main app with navigation
-@customElement('my-app')
-class MyApp extends LitElement {
-  navigate(page: string) {
-    area.push({
-      area: 'main',
-      component: `page-${page}`,
-      historyStrategy: HISTORY_STRATEGY.push
-    })
-  }
-  
-  render() {
-    return html`
-      <nav>
-        <button @click=${() => this.navigate('home')}>Home</button>
-        <button @click=${() => this.navigate('about')}>About</button>
-      </nav>
-      
-      <schmancy-area name="main" default="page-home"></schmancy-area>
-    `
-  }
-}
-```
-
-### Example 2: Route Parameters
-
-```typescript
-@customElement('user-profile')
-class UserProfile extends LitElement {
-  @state() userId = ''
-  @state() userData: any = {}
-  
-  connectedCallback() {
-    super.connectedCallback()
-    
-    // Subscribe to userId parameter
-    area.param<string>('main', 'userId').subscribe(id => {
-      if (id) {
-        this.userId = id
-        this.loadUserData(id)
-      }
-    })
-  }
-  
-  async loadUserData(id: string) {
-    // Fetch user data
-    this.userData = await fetch(`/api/users/${id}`).then(r => r.json())
-  }
-  
-  render() {
-    return html`
-      <div>
-        <h1>User: ${this.userData.name}</h1>
-        <p>ID: ${this.userId}</p>
-      </div>
-    `
-  }
-}
-
-// Navigate with parameters
-area.push({
-  area: 'main',
-  component: 'user-profile',
-  params: { userId: '12345' },
-  historyStrategy: HISTORY_STRATEGY.push
-})
-```
-
-### Example 3: Persistent Form State
-
-```typescript
-@customElement('contact-form')
-class ContactForm extends LitElement {
-  @state() formData = {
-    name: '',
-    email: '',
-    message: ''
-  }
-  
-  connectedCallback() {
-    super.connectedCallback()
-    
-    // Restore form state from route
-    area.getState<typeof this.formData>('main').subscribe(state => {
-      if (state) {
-        this.formData = { ...this.formData, ...state }
-      }
-    })
-  }
-  
-  updateField(field: string, value: string) {
-    this.formData = { ...this.formData, [field]: value }
-    
-    // Save form state to route (replace to avoid history spam)
-    area.push({
-      area: 'main',
-      component: 'contact-form',
-      state: this.formData,
-      historyStrategy: HISTORY_STRATEGY.replace
-    })
-  }
-  
-  render() {
-    return html`
-      <form>
-        <input 
-          .value=${this.formData.name}
-          @input=${(e: Event) => this.updateField('name', (e.target as HTMLInputElement).value)}
-          placeholder="Name"
-        />
-        <input 
-          .value=${this.formData.email}
-          @input=${(e: Event) => this.updateField('email', (e.target as HTMLInputElement).value)}
-          placeholder="Email"
-        />
-        <textarea 
-          .value=${this.formData.message}
-          @input=${(e: Event) => this.updateField('message', (e.target as HTMLTextAreaElement).value)}
-          placeholder="Message"
-        ></textarea>
-      </form>
-    `
-  }
-}
-```
-
-### Example 4: Modal Router
-
-```typescript
-@customElement('app-modal')
-class AppModal extends LitElement {
-  @property() title = ''
-  @property() content = ''
-  
-  connectedCallback() {
-    super.connectedCallback()
-    
-    area.params<{title: string, content: string}>('modal').subscribe(params => {
-      this.title = params.title || ''
-      this.content = params.content || ''
-    })
-  }
-  
-  close() {
-    area.pop('modal')
-  }
-  
-  render() {
-    return html`
-      <div class="modal-backdrop" @click=${this.close}>
-        <div class="modal-content" @click=${(e: Event) => e.stopPropagation()}>
-          <h2>${this.title}</h2>
-          <p>${this.content}</p>
-          <button @click=${this.close}>Close</button>
-        </div>
-      </div>
-    `
-  }
-}
-
-// Open modal
-area.push({
-  area: 'modal',
-  component: 'app-modal',
-  params: {
-    title: 'Confirm Action',
-    content: 'Are you sure you want to proceed?'
-  },
-  historyStrategy: HISTORY_STRATEGY.push
-})
-
-// In your main app template
-render() {
-  return html`
-    <main>
-      <schmancy-area name="main" default="page-home"></schmancy-area>
-    </main>
-    
-    ${this.modalOpen ? html`
-      <schmancy-area name="modal"></schmancy-area>
-    ` : ''}
-  `
-}
-```
-
-### Example 5: Tab Navigation
-
-```typescript
-@customElement('settings-page')
-class SettingsPage extends LitElement {
-  @state() activeTab = 'general'
-  
-  connectedCallback() {
-    super.connectedCallback()
-    
-    area.param<string>('main', 'tab').subscribe(tab => {
-      this.activeTab = tab || 'general'
-    })
-  }
-  
-  switchTab(tab: string) {
-    area.push({
-      area: 'main',
-      component: 'settings-page',
-      params: { tab },
-      historyStrategy: HISTORY_STRATEGY.push
-    })
-  }
-  
-  render() {
-    return html`
-      <div class="tabs">
-        <button 
-          class=${this.activeTab === 'general' ? 'active' : ''}
-          @click=${() => this.switchTab('general')}
-        >
-          General
-        </button>
-        <button 
-          class=${this.activeTab === 'privacy' ? 'active' : ''}
-          @click=${() => this.switchTab('privacy')}
-        >
-          Privacy
-        </button>
-        <button 
-          class=${this.activeTab === 'notifications' ? 'active' : ''}
-          @click=${() => this.switchTab('notifications')}
-        >
-          Notifications
-        </button>
-      </div>
-      
-      <div class="tab-content">
-        ${this.activeTab === 'general' ? html`
-          <h3>General Settings</h3>
-          <!-- General settings content -->
-        ` : this.activeTab === 'privacy' ? html`
-          <h3>Privacy Settings</h3>
-          <!-- Privacy settings content -->
-        ` : html`
-          <h3>Notification Settings</h3>
-          <!-- Notification settings content -->
-        `}
-      </div>
-    `
-  }
-}
-```
-
-## Common Patterns
-
-### Protected Routes
-
-```typescript
-// Check authentication before navigation
-function navigateToProtected(component: string) {
-  if (!isAuthenticated()) {
-    area.push({
-      area: 'main',
-      component: 'login-page',
-      state: { redirect: component }
-    })
-    return
-  }
-  
-  area.push({
-    area: 'main',
-    component,
-    historyStrategy: HISTORY_STRATEGY.push
-  })
-}
-```
-
-### Nested Routes
-
-```typescript
-// Parent component with sub-area
-@customElement('dashboard-layout')
-class DashboardLayout extends LitElement {
-  render() {
-    return html`
-      <div class="dashboard">
-        <aside class="sidebar">
-          <nav><!-- Dashboard navigation --></nav>
-        </aside>
-        <main>
-          <schmancy-area name="dashboard-content" default="dashboard-overview"></schmancy-area>
-        </main>
-      </div>
-    `
-  }
-}
-```
-
-### Route Guards
-
-```typescript
-// Intercept navigation
-const originalPush = area.push.bind(area)
-area.push = (route) => {
-  // Check permissions
-  if (route.component === 'admin-panel' && !hasAdminRole()) {
-    console.warn('Access denied')
-    return
-  }
-  
-  // Proceed with navigation
-  originalPush(route)
-}
-```
-
-### Query Parameters
-
-```typescript
-// Handle query params separately
-const urlParams = new URLSearchParams(window.location.search)
-const searchQuery = urlParams.get('q')
-
-// Include in navigation
-area.push({
-  area: 'main',
-  component: 'search-results',
-  params: { query: searchQuery },
-  clearQueryParams: ['q'] // Optional: clear from URL
-})
-```
-
-## Tips & Tricks
-
-1. **Preload Components**: Import components at app start for instant navigation
-2. **Use Replace for Filters**: When updating filters/sorting, use `replace` strategy
-3. **Handle Deep Links**: Always handle direct navigation to any route
-4. **Clean Subscriptions**: Unsubscribe in `disconnectedCallback`
-5. **Type Your Routes**: Create interfaces for your route params and state