@mhmo91/schmancy 0.2.194 → 0.2.196

package/dist/ai/area.md

@@ -1,125 +1,205 @@
-# Schmancy Area - AI Reference
+# Schmancy Area
 
-```js
-// Area Router Component
-<schmancy-area
-  name="root"
+Schmancy Area is a lightweight, reactive routing and state management system for web components with RxJS integration.
+
+## Component Usage
+
+```html
+<!-- Basic router outlet -->
+<schmancy-area 
+  name="main"
   default="home-component">
 </schmancy-area>
+```
 
-// Area Service
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | **Required**. Unique identifier for this router outlet. |
+| `default` | `string \| Promise<NodeModule> \| CustomElementConstructor \| TemplateResult` | Default component to display if none is specified. |
+
+## Service API
+
+```ts
+// Import the area service
 import { area } from '@schmancy/area';
 
 // Navigation methods
 area.push({
-  component: UserProfileComponent,  // Component constructor, string tag name, or element instance
-  area: 'root',                     // Target area name
-  state?: { view: 'profile' },      // Optional state object
-  params?: { id: '123' },           // Optional parameters
-  historyStrategy: 'push'           // 'push', 'replace', 'pop', 'silent'
+  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 parameters
+  historyStrategy: 'push',        // 'push', 'replace', 'pop', 'silent'
+  clearQueryParams?: ['sort']     // Clear specific query params
 });
 
-area.pop('sidebar');                // Remove an area
+area.pop('sidebar');              // Remove an area
 
-// Subscription methods
-area.on(areaName, skipCurrent?) -> Observable<ActiveRoute>
-area.all(skipCurrent?) -> Observable<Map<string, ActiveRoute>>
-area.getState<T>(areaName) -> Observable<T>
-area.params<T>(areaName) -> Observable<T>
-area.param<T>(areaName, key) -> Observable<T>
+// 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 params from an area
+area.param<T>(areaName, key)      // Get a specific param value
+```
 
-// Event name format for DOM event listeners
-schmancy-area-${areaName}-changed
+## Examples
 
-// Examples
-// 1. Basic navigation
+### Basic Navigation
+
+```ts
+// Navigate to a component
 area.push({
   component: 'home-page',
-  area: 'main',
-  historyStrategy: 'push'
+  area: 'main'
 });
 
-// 2. Navigation with params
+// Navigate with parameters and state
 area.push({
   component: ProductDetailComponent,
   area: 'main',
   params: { productId: '12345' },
+  state: { showReviews: true },
   historyStrategy: 'push'
 });
+```
 
-// 3. Subscribe to an area
+### Multiple Independent Areas
+
+```ts
+// Update multiple areas independently
+area.push({ component: 'product-list', area: 'main' });
+area.push({ component: 'filter-panel', area: 'sidebar' });
+
+// Open a modal dialog
+area.push({ 
+  component: 'dialog-component', 
+  area: 'modal',
+  params: { id: '123' }
+});
+
+// Close a modal
+area.pop('modal');
+```
+
+### Reactive Subscriptions
+
+```ts
+// Subscribe to area changes
 area.on('main').subscribe(route => {
-  console.log(`Component: ${route.component}, Params: ${route.params}`);
+  console.log(`Component: ${route.component}`);
+  console.log(`Params:`, route.params);
+});
+
+// Type-safe state and params
+interface UserState { name: string; role: string; }
+interface UserParams { id: string; tab?: string; }
+
+area.getState<UserState>('user').subscribe(state => {
+  updateUserInfo(state.name, state.role);
 });
 
-// 4. Get and react to a specific param
+area.params<UserParams>('user').subscribe(params => {
+  fetchUser(params.id);
+  setActiveTab(params.tab || 'profile');
+});
+
+// Get a specific parameter
 area.param<string>('product', 'productId').subscribe(id => {
   fetchProductDetails(id);
 });
+```
+
+### DOM Events
 
-// 5. DOM event listening (non-RxJS approach)
+Areas also dispatch DOM events for non-RxJS consumers:
+
+```js
+// Format: schmancy-area-${areaName}-changed
 window.addEventListener('schmancy-area-main-changed', event => {
-  const { component, params } = event.detail;
-  updateUI(component, params);
+  const { component, params, state } = event.detail;
+  updateUI(component, params, state);
 });
 ```
 
-## Related Components
-- **[Teleport](./teleport.md)**: Can be used with Area for advanced component transportation
-- **[Store](./store.md)**: Complements Area for more complex state management
-- **[Layout](./layout.md)**: Often used as a container for areas
+## Advanced Usage
 
-## Technical Details
+### Lazy Loading Components
 
-### ActiveRoute Interface
-```typescript
-interface ActiveRoute {
-  component: string;        // Component tag name
-  area: string;             // Area name
-  state?: Record<string, unknown>;  // Optional state
-  params?: Record<string, unknown>; // Optional parameters
-}
+```ts
+area.push({
+  component: import('./components/heavy-dashboard.js'),
+  area: 'main'
+});
+```
+
+### Navigation Guards
+
+```ts
+import { switchMap, EMPTY, of } from 'rxjs';
+
+area.on('protected-area').pipe(
+  switchMap(route => {
+    if (!isAuthenticated()) {
+      area.push({ component: 'login-page', area: 'main' });
+      return EMPTY;
+    }
+    return of(route);
+  })
+).subscribe(handleProtectedRoute);
 ```
 
-### RouteAction Interface
-```typescript
+### Component Reloading Pattern
+
+When updating the same component with different parameters, use this pattern to ensure re-rendering:
+
+```ts
+// First push to the main routing area to force component re-creation
+area.push({
+  area: 'main-area',
+  component: 'user-profile',
+  params: { userId: '456' },
+  historyStrategy: 'push'
+});
+
+// Then update any subscription areas with the silent history strategy
+area.push({
+  area: 'user-area',
+  component: 'user-profile',
+  params: { userId: '456' },
+  historyStrategy: 'silent' // Don't create history entry
+});
+```
+
+This works around the `distinctUntilChanged` behavior in the Area component that compares only component names, not params.
+
+## Related Components
+
+- **[Store](./store.md)** - For more complex state management
+- **[Layout](./layout.md)** - For responsive layouts
+- **[Teleport](./teleport.md)** - For advanced component transportation
+- **[Sheet](./sheet.md)** - For modal overlays
+
+## Type Definitions
+
+```ts
+// Route Action - used for navigation
 interface RouteAction {
-  component: CustomElementConstructor | string | HTMLElement;
+  component: CustomElementConstructor | string | HTMLElement | Promise<NodeModule>;
   area: string;
   state?: Record<string, unknown>;
   params?: Record<string, unknown>;
   historyStrategy?: 'push' | 'replace' | 'pop' | 'silent';
   clearQueryParams?: string[] | null;
 }
-```
 
-### Common Use Cases
-
-1. **Single Page Applications**: Define multiple areas for different sections of your app
-   ```html
-   <schmancy-area name="main"></schmancy-area>
-   <schmancy-area name="sidebar"></schmancy-area>
-   <schmancy-area name="modal"></schmancy-area>
-   ```
-
-2. **Typed Params and State**: Use TypeScript generics for type safety
-   ```typescript
-   interface UserParams { id: string; tab?: string; }
-   area.params<UserParams>('user').subscribe(params => {
-     fetchUser(params.id);
-     setActiveTab(params.tab || 'profile');
-   });
-   ```
-
-3. **Navigation Guards**: Implement navigation guards with RxJS operators
-   ```typescript
-   area.on('protected').pipe(
-     switchMap(route => {
-       if (!isAuthenticated()) {
-         area.push({ component: 'login-page', area: 'main' });
-         return EMPTY;
-       }
-       return of(route);
-     })
-   ).subscribe(handleProtectedRoute);
-   ```
+// Active Route - current state of an area
+interface ActiveRoute {
+  component: string;
+  area: string;
+  state?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+}
+```

package/dist/ai/card.md

@@ -1,155 +1,186 @@
 # Schmancy Card - AI Reference
 
 ```js
-// Basic Card
-<schmancy-card>
-  <div>Card content goes here</div>
+// Card Component
+<schmancy-card
+  type="elevated|filled|outlined"
+  elevation="0|1|2|3|4|5">
+  Card content
 </schmancy-card>
 
-// Card with title and content
-<schmancy-card>
-  <schmancy-card-content>
-    <h2>Card Title</h2>
-    <p>Card description text goes here.</p>
-  </schmancy-card-content>
-</schmancy-card>
+// Properties
+type: string          // "elevated", "filled", "outlined" (default: "elevated")
+elevation: number     // Shadow depth 0-5 (default: 0)
 
-// Card with media
-<schmancy-card>
-  <schmancy-card-media
-    image="path/to/image.jpg"
-    alt="Image description"
-    height="200px">
-  </schmancy-card-media>
-  
-  <schmancy-card-content>
-    <h2>Card with Media</h2>
-    <p>Card content below the image.</p>
-  </schmancy-card-content>
-</schmancy-card>
+// Card Types
+"elevated"            // Surface with shadow, uses surface-low color
+"filled"              // Filled background, uses surface-highest color
+"outlined"            // Border outline, uses surface color
 
-// Card with actions
+// Examples
+// 1. Basic elevated card
 <schmancy-card>
-  <schmancy-card-content>
-    <h2>Card Title</h2>
-    <p>Card content with action buttons.</p>
-  </schmancy-card-content>
-  
-  <schmancy-card-actions>
-    <schmancy-button>Action 1</schmancy-button>
-    <schmancy-button>Action 2</schmancy-button>
-  </schmancy-card-actions>
+  <h3>Card Title</h3>
+  <p>Card content goes here</p>
 </schmancy-card>
 
-// Complete card with all components
-<schmancy-card>
-  <schmancy-card-media
-    image="path/to/image.jpg"
-    alt="Image description">
+// 2. Filled card with custom elevation
+<schmancy-card type="filled" elevation="2">
+  <schmancy-card-media>
+    <img src="image.jpg" alt="Card image">
   </schmancy-card-media>
-  
   <schmancy-card-content>
-    <h2>Card Title</h2>
-    <p>Card description text goes here. This can contain any content.</p>
+    <h3>Product Name</h3>
+    <p>Product description</p>
   </schmancy-card-content>
-  
   <schmancy-card-actions>
-    <schmancy-button kind="tertiary">Cancel</schmancy-button>
-    <schmancy-button kind="primary">Submit</schmancy-button>
+    <schmancy-button>Add to Cart</schmancy-button>
   </schmancy-card-actions>
 </schmancy-card>
 
-// Card Properties
-outlined: boolean        // Shows an outline instead of elevation
-elevation: number        // Shadow elevation level (1-5)
-interactive: boolean     // Enables hover and click effects
+// 3. Outlined card
+<schmancy-card type="outlined">
+  <div style="padding: 16px;">
+    <h4>Settings</h4>
+    <p>Configure your preferences</p>
+  </div>
+</schmancy-card>
 
-// Card Media Properties
-image: string           // URL of the image
-alt: string             // Alt text for the image
-height: string          // Height of the media area
-title: string           // Title to display over the media
+// 4. Interactive card with hover effect
+<schmancy-card elevation="1">
+  <a href="/details" style="text-decoration: none; color: inherit;">
+    <div style="padding: 16px;">
+      <h3>Click for Details</h3>
+      <p>This card has hover elevation changes</p>
+    </div>
+  </a>
+</schmancy-card>
+```
 
-// Card Actions Properties
-align: string           // Alignment of actions: "start", "end", "space-between", "center"
-direction: string       // Direction of actions: "row", "column"
+## Related Components
+- **[Surface](./surface.md)**: Base container component with more options
+- **[Card Content](./card.md#content)**: Structured content area
+- **[Card Media](./card.md#media)**: Media container for cards
+- **[Card Actions](./card.md#actions)**: Action button container
 
-// Examples
-// Basic card with content
-<schmancy-card>
-  <schmancy-card-content>
-    <h2>Welcome to Schmancy</h2>
-    <p>A modern component library for web applications.</p>
-  </schmancy-card-content>
-</schmancy-card>
+## Technical Details
 
-// Interactive card
-<schmancy-card 
-  interactive
-  @click=${handleCardClick}>
-  <schmancy-card-content>
-    <h3>Click Me</h3>
-    <p>This entire card is clickable.</p>
-  </schmancy-card-content>
-</schmancy-card>
+### CSS Host Styling
+The component uses `:host` selectors for all styling:
+- No wrapper elements - clean component boundary
+- Type and elevation properties reflect to HTML attributes
+- Automatic hover states for elevated and outlined types
 
-// Outlined card
-<schmancy-card outlined>
-  <schmancy-card-content>
-    <h3>Outlined Card</h3>
-    <p>This card has an outline instead of elevation.</p>
-  </schmancy-card-content>
-</schmancy-card>
+### Theme Integration
+```css
+/* Type-based colors */
+type="elevated"  -> --schmancy-sys-color-surface-low
+type="filled"    -> --schmancy-sys-color-surface-highest  
+type="outlined"  -> --schmancy-sys-color-surface-default
 
-// Product card
-<schmancy-card>
-  <schmancy-card-media
-    image="/products/headphones.jpg"
-    alt="Wireless Headphones"
-    height="180px">
-  </schmancy-card-media>
-  
-  <schmancy-card-content>
-    <h3>Wireless Headphones</h3>
-    <p>Premium sound quality with noise cancellation.</p>
-    <p><strong>$149.99</strong></p>
-  </schmancy-card-content>
-  
-  <schmancy-card-actions>
-    <schmancy-button kind="tertiary">Details</schmancy-button>
-    <schmancy-button kind="primary">Add to Cart</schmancy-button>
-  </schmancy-card-actions>
-</schmancy-card>
+/* Outline color */
+--schmancy-sys-color-outlineVariant
+
+/* Elevation shadows */
+--schmancy-sys-elevation-1 through --schmancy-sys-elevation-5
+```
+
+### Hover Behavior
+- Elevated cards: elevation 1 → 2 on hover
+- Filled cards: no elevation → 1 on hover
+- Outlined cards: no elevation → 1 on hover
+
+## Card Sub-components
+
+### Card Content
+```html
+<schmancy-card-content>
+  <h3>Title</h3>
+  <p>Description text</p>
+</schmancy-card-content>
+```
+
+### Card Media  
+```html
+<schmancy-card-media>
+  <img src="image.jpg" alt="Media">
+</schmancy-card-media>
+```
+
+### Card Actions
+```html
+<schmancy-card-actions>
+  <schmancy-button>Action 1</schmancy-button>
+  <schmancy-button variant="text">Action 2</schmancy-button>
+</schmancy-card-actions>
+```
+
+## Common Use Cases
+
+1. **Product Cards**: E-commerce product display
+   ```html
+   <schmancy-card type="elevated">
+     <schmancy-card-media>
+       <img src="product.jpg" alt="Product">
+     </schmancy-card-media>
+     <schmancy-card-content>
+       <h3>Product Name</h3>
+       <p class="price">$29.99</p>
+       <p class="description">Product description...</p>
+     </schmancy-card-content>
+     <schmancy-card-actions>
+       <schmancy-button variant="filled">Add to Cart</schmancy-button>
+       <schmancy-button variant="text">Details</schmancy-button>
+     </schmancy-card-actions>
+   </schmancy-card>
+   ```
+
+2. **Info Cards**: Dashboard or stats display
+   ```html
+   <schmancy-card type="filled" elevation="0">
+     <div style="padding: 24px;">
+       <schmancy-icon icon="users" size="32"></schmancy-icon>
+       <h2>1,234</h2>
+       <p>Active Users</p>
+     </div>
+   </schmancy-card>
+   ```
+
+3. **Settings Cards**: Options or configuration
+   ```html
+   <schmancy-card type="outlined">
+     <schmancy-card-content>
+       <h4>Notification Settings</h4>
+       <schmancy-form>
+         <schmancy-checkbox>Email notifications</schmancy-checkbox>
+         <schmancy-checkbox>Push notifications</schmancy-checkbox>
+       </schmancy-form>
+     </schmancy-card-content>
+   </schmancy-card>
+   ```
+
+4. **Media Cards**: Image galleries
+   ```html
+   <schmancy-card elevation="2">
+     <schmancy-card-media aspect-ratio="16:9">
+       <img src="gallery-image.jpg" alt="Gallery">
+     </schmancy-card-media>
+     <schmancy-card-content>
+       <p>Image caption or description</p>
+     </schmancy-card-content>
+   </schmancy-card>
+   ```
 
-// Card grid layout
-<schmancy-grid
-  columns="1"
-  columns-md="2"
-  columns-lg="3"
-  gap="16px">
-  
-  ${products.map(product => html`
-    <schmancy-card>
-      <schmancy-card-media
-        image=${product.image}
-        alt=${product.name}>
-      </schmancy-card-media>
-      
-      <schmancy-card-content>
-        <h3>${product.name}</h3>
-        <p>${product.description}</p>
-        <p><strong>${product.price}</strong></p>
-      </schmancy-card-content>
-      
-      <schmancy-card-actions>
-        <schmancy-button @click=${() => viewProduct(product)}>
-          View
-        </schmancy-button>
-        <schmancy-button kind="primary" @click=${() => addToCart(product)}>
-          Add to Cart
-        </schmancy-button>
-      </schmancy-card-actions>
-    </schmancy-card>
-  `)}
-</schmancy-grid>
-```
+5. **List Item Cards**: Clickable list items
+   ```html
+   <schmancy-card type="elevated" elevation="1">
+     <a href="/user/123" style="display: flex; padding: 16px; align-items: center; text-decoration: none; color: inherit;">
+       <schmancy-avatar src="user.jpg"></schmancy-avatar>
+       <div style="margin-left: 16px; flex: 1;">
+         <h4>User Name</h4>
+         <p>user@example.com</p>
+       </div>
+       <schmancy-icon icon="chevron-right"></schmancy-icon>
+     </a>
+   </schmancy-card>
+   ```