@mhmo91/schmancy 0.2.194 → 0.2.196

package/ai/animated-text.md

@@ -0,0 +1,114 @@
+# Schmancy Animated Text - AI Reference
+
+```js
+// Animated Text Component
+<schmancy-animated-text
+  ease="outExpo"
+  delay="0"
+  stagger="50"
+  duration="750"
+  scale="[0, 1]"
+  opacity="[0, 1]"
+  translateX="['0.55em', '0em']"
+  translateY="['1.1em', '0em']"
+  rotate3d="[0, 0, 1, 45]">
+  Text to animate
+</schmancy-animated-text>
+
+// Animation Properties
+ease: string           // Animation easing function (default: "outExpo")
+delay: number          // Initial delay in milliseconds (default: 0)
+stagger: number        // Delay between letter animations (default: 50)
+duration: number       // Animation duration in milliseconds (default: 750)
+scale: number[]        // Scale transformation [from, to] (default: [0, 1])
+opacity: number[]      // Opacity transition [from, to] (default: [0, 1])
+translateX: string[]   // X translation ["from", "to"] (default: ['0.55em', '0em'])
+translateY: string[]   // Y translation ["from", "to"] (default: ['1.1em', '0em'])
+rotate3d: number[]     // 3D rotation [x, y, z, angle] (default: [0, 0, 1, 45])
+
+// Examples
+// 1. Basic fade in
+<schmancy-animated-text>
+  Welcome to our application
+</schmancy-animated-text>
+
+// 2. Custom stagger effect
+<schmancy-animated-text
+  stagger="100"
+  duration="1000"
+  translateY="['2em', '0em']">
+  Cascading Letters
+</schmancy-animated-text>
+
+// 3. Scale and rotate effect
+<schmancy-animated-text
+  scale="[0.5, 1]"
+  rotate3d="[0, 1, 0, 180]"
+  duration="1500">
+  Dramatic Entrance
+</schmancy-animated-text>
+
+// 4. No translation effect
+<schmancy-animated-text
+  translateX="['0em', '0em']"
+  translateY="['0em', '0em']"
+  opacity="[0, 1]">
+  Fade Only
+</schmancy-animated-text>
+```
+
+## Related Components
+- **[Typography](./typography.md)**: Base text styling component
+- **[Typewriter](./typewriter.md)**: Alternative text animation with typing effect
+
+## Technical Details
+
+### Animation Behavior
+- Text is split into individual letter spans
+- Each letter animates with the specified stagger delay
+- Uses Web Animations API for performance
+- Animations trigger on component mount and when text changes
+- Responsive to viewport visibility
+
+### CSS Classes
+- `.ml7`: Main wrapper class
+- `.text-wrapper`: Container for animated text
+- `.letter`: Individual animated letter span
+
+## Common Use Cases
+
+1. **Hero Text**: Large headings with dramatic entrance animations
+   ```html
+   <h1>
+     <schmancy-animated-text duration="2000" scale="[0.3, 1]">
+       Welcome to Schmancy
+     </schmancy-animated-text>
+   </h1>
+   ```
+
+2. **Loading Messages**: Staggered letter animations for loading states
+   ```html
+   <schmancy-animated-text stagger="100" translateY="['1em', '0em']">
+     Loading...
+   </schmancy-animated-text>
+   ```
+
+3. **Notifications**: Subtle fade-in for status messages
+   ```html
+   <schmancy-animated-text 
+     duration="500" 
+     translateX="['0em', '0em']"
+     translateY="['0em', '0em']">
+     Operation completed successfully
+   </schmancy-animated-text>
+   ```
+
+4. **Interactive Reveals**: Combined with visibility triggers
+   ```html
+   <schmancy-animated-text 
+     delay="500"
+     stagger="75"
+     opacity="[0, 1]">
+     Scroll to reveal this text
+   </schmancy-animated-text>
+   ```

package/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>;
+}
+```