@mhmo91/schmancy 0.4.18 → 0.4.20

package/ai/chips.md

@@ -1,23 +1,40 @@
 # Schmancy Chips - AI Reference
 
 ```js
-// Single Chip
+// Single Chip - now accepts ANY content!
 <schmancy-chip
   value="chip-value"
   selected?
-  icon="emoji-icon"
   readOnly?
   disabled?
-  @change=${handleChange}
-  @click=${handleClick}>
-  Chip Text
+  @change=${handleChange}>
+  Any content here
 </schmancy-chip>
 
-// Chip with icon
-<schmancy-chip icon="📝" value="javascript">
+// Simple text chip
+<schmancy-chip value="javascript">
   JavaScript
 </schmancy-chip>
 
+// Chip with icon
+<schmancy-chip value="edit">
+  <schmancy-icon>edit</schmancy-icon>
+  Edit
+</schmancy-chip>
+
+// Chip with avatar and text
+<schmancy-chip value="user1" class="flex items-center gap-2">
+  <schmancy-avatar size="sm">JD</schmancy-avatar>
+  <schmancy-typography type="body" token="sm">john.doe@example.com</schmancy-typography>
+</schmancy-chip>
+
+// Chip with badge
+<schmancy-chip value="notifications" class="flex items-center gap-2">
+  <schmancy-icon>notifications</schmancy-icon>
+  <span>Notifications</span>
+  <schmancy-badge>5</schmancy-badge>
+</schmancy-chip>
+
 // Chips Container - Single Selection
 <schmancy-chips
   .value=${selectedValue}
@@ -49,9 +66,8 @@
 // Chip Properties
 value: string           // Value for selection purposes
 selected: boolean       // Whether the chip is selected
-icon: string            // Emoji icon to display
-readOnly: boolean       // Makes chip non-interactive
-disabled: boolean       // Disable the chip
+readOnly: boolean       // Makes chip non-interactive (no selection change)
+disabled: boolean       // Disable the chip (no interaction at all)
 
 // Chips Container Properties
 multi: boolean          // Enable multiple selection mode
@@ -67,13 +83,26 @@ wrap: boolean           // Whether chips wrap to new lines (default: true)
 @change  // Fires when selection changes, with detail being string (single) or string[] (multi)
 
 // Examples
-// Basic chips
+// Basic chips with emoji and Material icons
 <div>
   <schmancy-chip value="basic">Basic</schmancy-chip>
   <schmancy-chip value="javascript" icon="📝">JavaScript</schmancy-chip>
-  <schmancy-chip value="react" icon="⚛️">React</schmancy-chip>
-  <schmancy-chip value="vue" icon="💚">Vue</schmancy-chip>
-  <schmancy-chip value="angular" icon="🅰️">Angular</schmancy-chip>
+  <schmancy-chip value="settings" icon="settings">Settings</schmancy-chip>
+  <schmancy-chip value="star" icon="star">Starred</schmancy-chip>
+  <schmancy-chip value="delete" icon="delete">Delete</schmancy-chip>
+</div>
+
+// User chips with avatars - now fully supported!
+<div class="flex flex-wrap gap-2">
+  <schmancy-chip value="user1" class="flex items-center gap-2">
+    <schmancy-avatar size="sm">JD</schmancy-avatar>
+    <schmancy-typography type="body" token="sm">john.doe@example.com</schmancy-typography>
+  </schmancy-chip>
+  
+  <schmancy-chip value="user2" selected class="flex items-center gap-2">
+    <schmancy-avatar size="sm">AS</schmancy-avatar>
+    <schmancy-typography type="body" token="sm">alice.smith@example.com</schmancy-typography>
+  </schmancy-chip>
 </div>
 
 // Single selection chips

package/ai/context.md

@@ -0,0 +1,545 @@
+# Context API - Schmancy Framework
+
+## Overview
+
+The Context API in Schmancy provides a reactive state management solution with automatic persistence across browser storage mechanisms. It's built on RxJS observables and integrates seamlessly with Lit components.
+
+## Core Concepts
+
+### What is a Context?
+
+A context is a reactive container that:
+- Holds application state
+- Automatically persists to browser storage
+- Notifies all subscribers of changes
+- Works across component boundaries without prop drilling
+
+### Storage Types
+
+| Type | Use Case | Size Limit | Persistence |
+|------|----------|------------|-------------|
+| `'local'` | User preferences, auth tokens | ~5-10MB | Survives browser restart |
+| `'session'` | Temporary UI state, filters | ~5-10MB | Cleared on tab close |
+| `'indexeddb'` | Large datasets, complex objects | GB+ | Survives browser restart |
+| `null` | Non-persisted state | Memory only | Lost on page reload |
+
+## Creating Contexts
+
+### Basic Syntax
+
+```typescript
+import { createContext } from '@mhmo91/schmancy/context'
+
+export const contextName = createContext<Type>(
+  initialValue,    // Default value
+  storageType,     // 'local' | 'session' | 'indexeddb' | null
+  storageKey      // Unique key for storage
+)
+```
+
+### Examples by Use Case
+
+#### User Authentication
+```typescript
+// Single user object that persists across sessions
+export const userContext = createContext<User>(
+  new User(),
+  'local',
+  'auth_user'
+)
+```
+
+#### Application Configuration
+```typescript
+// App-wide settings
+export const configContext = createContext<AppConfig>(
+  { theme: 'light', language: 'en' },
+  'local',
+  'app_config'
+)
+```
+
+#### Collections (Use Maps for Performance)
+```typescript
+// Large collections with frequent lookups
+export const productsContext = createContext<Map<string, Product>>(
+  new Map(),
+  'indexeddb',
+  'products_collection'
+)
+
+// User collection with relationships
+export const usersContext = createContext<Map<string, User>>(
+  new Map(),
+  'indexeddb', 
+  'users_collection'
+)
+```
+
+#### Temporary UI State
+```typescript
+// Filter state cleared on tab close
+export const filterContext = createContext<ProductFilter>(
+  { category: 'all', priceRange: [0, 1000] },
+  'session',
+  'product_filter'
+)
+
+// Selected items in current session
+export const selectedIdsContext = createContext<Set<string>>(
+  new Set(),
+  'session',
+  'selected_items'
+)
+```
+
+#### Non-Persisted State
+```typescript
+// Loading states, temporary flags
+export const loadingContext = createContext<boolean>(
+  false,
+  null,  // No persistence
+  'loading_state'
+)
+```
+
+## Using Contexts in Components
+
+### Basic Component Integration
+
+```typescript
+import { $LitElement } from '@mhmo91/schmancy/core/$lit'
+import { select } from '@mhmo91/schmancy/context'
+import { userContext, productsContext } from './contexts'
+
+@customElement('my-component')
+export class MyComponent extends $LitElement() {
+  // Basic selection
+  @select(userContext) user!: User
+  
+  // With transformation
+  @select(productsContext, products => Array.from(products.values()))
+  productsList!: Product[]
+  
+  // Required context (throws if undefined)
+  @select(configContext, config => config, { required: true })
+  config!: AppConfig
+  
+  render() {
+    return html`
+      <div>Welcome, ${this.user.name}</div>
+      <div>${this.productsList.length} products</div>
+    `
+  }
+}
+```
+
+### Advanced Subscriptions
+
+```typescript
+@customElement('advanced-component')
+export class AdvancedComponent extends $LitElement() {
+  connectedCallback() {
+    super.connectedCallback()
+    
+    // React to context changes
+    userContext.$.pipe(
+      takeUntil(this.disconnecting),
+      filter(user => user.isAuthenticated),
+      debounceTime(300)
+    ).subscribe(user => {
+      console.log('Authenticated user changed:', user)
+    })
+    
+    // Combine multiple contexts
+    combineLatest([
+      userContext.$,
+      organizationContext.$
+    ]).pipe(
+      takeUntil(this.disconnecting)
+    ).subscribe(([user, org]) => {
+      // React to either changing
+    })
+  }
+}
+```
+
+## Context Operations
+
+### Reading Values
+
+```typescript
+// Get current value synchronously
+const currentUser = userContext.value
+
+// Subscribe to changes
+userContext.$.subscribe(user => {
+  console.log('User changed:', user)
+})
+```
+
+### Updating Values
+
+```typescript
+// Partial update (merges with existing)
+userContext.set({ name: 'New Name' })
+
+// Full replacement
+userContext.replace(new User({ id: '123', name: 'John' }))
+
+// For Maps
+productsContext.set(prevMap => {
+  const newMap = new Map(prevMap)
+  newMap.set('123', newProduct)
+  return newMap
+})
+```
+
+### Clearing Values
+
+```typescript
+// Reset to initial value and clear storage
+userContext.clear()
+
+// Clear all contexts (useful for logout)
+export function clearAllContexts() {
+  userContext.clear()
+  configContext.clear()
+  productsContext.clear()
+}
+```
+
+## Best Practices
+
+### 1. Organization
+
+```typescript
+// Feature-based structure
+src/
+  features/
+    auth/
+      context.ts    // Auth-related contexts
+      components/
+    products/
+      context.ts    // Product-related contexts
+      components/
+```
+
+### 2. Type Safety
+
+```typescript
+// Always provide explicit types
+export const userContext = createContext<User>(...)  // ✅
+
+// Avoid any
+export const dataContext = createContext<any>(...)   // ❌
+
+// Use discriminated unions for complex state
+type AuthState = 
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'authenticated'; user: User }
+  | { status: 'error'; error: string }
+
+export const authStateContext = createContext<AuthState>(
+  { status: 'idle' },
+  'session',
+  'auth_state'
+)
+```
+
+### 3. Performance Optimization
+
+```typescript
+// Use Maps for collections with frequent lookups
+export const itemsContext = createContext<Map<string, Item>>(new Map(), ...)
+
+// Avoid storing derived state
+// ❌ Bad: Storing filtered results
+export const filteredProductsContext = createContext<Product[]>([], ...)
+
+// ✅ Good: Compute in component
+@select(productsContext, products => 
+  Array.from(products.values()).filter(p => p.category === 'electronics')
+)
+filteredProducts!: Product[]
+```
+
+### 4. Memory Management
+
+```typescript
+// Always cleanup subscriptions
+connectedCallback() {
+  super.connectedCallback()
+  
+  // Use takeUntil with disconnecting
+  someContext.$.pipe(
+    takeUntil(this.disconnecting)
+  ).subscribe()
+}
+
+// Avoid memory leaks
+disconnectedCallback() {
+  super.disconnectedCallback()
+  // Subscriptions are automatically cleaned up
+}
+```
+
+### 5. Storage Key Naming
+
+```typescript
+// Use consistent, descriptive keys
+'auth_user'         // ✅ Clear purpose
+'app_config'        // ✅ Namespaced
+'products_v2'       // ✅ Versioned if needed
+'data'              // ❌ Too generic
+'u'                 // ❌ Too short
+```
+
+## Common Patterns
+
+### Authentication Flow
+
+```typescript
+// contexts/auth.ts
+export const userContext = createContext<User | null>(null, 'local', 'auth_user')
+export const tokenContext = createContext<string>('', 'local', 'auth_token')
+
+// components/login.ts
+async function login(credentials: Credentials) {
+  const response = await api.login(credentials)
+  userContext.set(response.user)
+  tokenContext.set(response.token)
+}
+
+async function logout() {
+  userContext.clear()
+  tokenContext.clear()
+  // Clear other user-specific contexts
+}
+```
+
+### Master-Detail Pattern
+
+```typescript
+// contexts/products.ts
+export const productsContext = createContext<Map<string, Product>>(
+  new Map(),
+  'indexeddb',
+  'products'
+)
+
+export const selectedProductIdContext = createContext<string | null>(
+  null,
+  'session',
+  'selected_product'
+)
+
+// components/product-list.ts
+@select(productsContext) products!: Map<string, Product>
+@select(selectedProductIdContext) selectedId!: string | null
+
+selectProduct(id: string) {
+  selectedProductIdContext.set(id)
+}
+
+// components/product-detail.ts
+@select(selectedProductIdContext) productId!: string | null
+@select(productsContext, (products, productId) => 
+  productId ? products.get(productId) : null
+)
+selectedProduct!: Product | null
+```
+
+### Form State Management
+
+```typescript
+// contexts/form.ts
+export interface FormData {
+  name?: string
+  email?: string
+  message?: string
+}
+
+export const formContext = createContext<FormData>(
+  {},
+  'session',  // Don't persist incomplete forms
+  'contact_form'
+)
+
+// components/form.ts
+@select(formContext) formData!: FormData
+
+updateField(field: keyof FormData, value: string) {
+  formContext.set({ [field]: value })
+}
+
+submitForm() {
+  const data = formContext.value
+  // Submit logic
+  formContext.clear() // Clear after submit
+}
+```
+
+### Optimistic Updates
+
+```typescript
+// Immediately update UI, then sync with server
+async function updateProduct(id: string, updates: Partial<Product>) {
+  // Optimistic update
+  productsContext.set(prev => {
+    const newMap = new Map(prev)
+    const product = newMap.get(id)
+    if (product) {
+      newMap.set(id, { ...product, ...updates })
+    }
+    return newMap
+  })
+  
+  try {
+    // Sync with server
+    const updated = await api.updateProduct(id, updates)
+    
+    // Update with server response
+    productsContext.set(prev => {
+      const newMap = new Map(prev)
+      newMap.set(id, updated)
+      return newMap
+    })
+  } catch (error) {
+    // Revert on error
+    productsContext.set(prev => {
+      // Restore original state
+    })
+  }
+}
+```
+
+## Testing Contexts
+
+```typescript
+// test/setup.ts
+import { beforeEach } from 'vitest'
+
+beforeEach(() => {
+  // Clear all contexts before each test
+  localStorage.clear()
+  sessionStorage.clear()
+  
+  // Reset to initial values
+  userContext.clear()
+  productsContext.clear()
+})
+
+// test/auth.test.ts
+describe('Authentication', () => {
+  it('should update user context on login', async () => {
+    const mockUser = { id: '1', name: 'Test User' }
+    
+    // Set context value
+    userContext.set(mockUser)
+    
+    // Verify update
+    expect(userContext.value).toEqual(mockUser)
+    expect(localStorage.getItem('auth_user')).toBeTruthy()
+  })
+})
+```
+
+## Troubleshooting
+
+### Context Not Updating
+
+```typescript
+// Check if component is subscribing correctly
+@select(userContext) user!: User  // ✅ Will update
+
+// Manual subscription needs cleanup
+userContext.$.pipe(
+  takeUntil(this.disconnecting)  // ✅ Important!
+).subscribe()
+```
+
+### Storage Quota Exceeded
+
+```typescript
+// For large data, use IndexedDB
+export const largeDataContext = createContext<LargeData>(
+  {},
+  'indexeddb',  // ✅ Much larger quota
+  'large_data'
+)
+```
+
+### Type Errors with Collections
+
+```typescript
+// When using Maps, remember to transform for templates
+@select(itemsContext, items => Array.from(items.values()))
+itemsList!: Item[]  // ✅ Array for template iteration
+```
+
+### Debugging Tips
+
+```typescript
+// Log all context changes
+if (import.meta.env.DEV) {
+  userContext.$.subscribe(user => 
+    console.log('[Context] User:', user)
+  )
+  
+  productsContext.$.subscribe(products => 
+    console.log('[Context] Products:', products.size)
+  )
+}
+
+// Check storage directly
+console.log('LocalStorage:', localStorage.getItem('auth_user'))
+console.log('SessionStorage:', sessionStorage.getItem('filter_state'))
+```
+
+## Migration Guide
+
+### From Redux/Vuex
+
+```typescript
+// Redux pattern
+dispatch({ type: 'SET_USER', payload: user })
+
+// Context pattern
+userContext.set(user)
+```
+
+### From React Context
+
+```typescript
+// React Context
+const UserContext = React.createContext()
+<UserContext.Provider value={user}>
+
+// Schmancy Context
+export const userContext = createContext<User>(...)
+// No provider needed - works globally
+```
+
+### From Local Component State
+
+```typescript
+// Before: Component state
+class MyComponent {
+  @state() private user?: User
+  
+  updateUser(user: User) {
+    this.user = user
+  }
+}
+
+// After: Shared context
+class MyComponent {
+  @select(userContext) user!: User
+  
+  updateUser(user: User) {
+    userContext.set(user)  // Updates all subscribers
+  }
+}
+```

package/ai/typography.md

@@ -52,7 +52,7 @@ import '@mhmo91/schmancy/typography'
 </schmancy-typography>
 
 // 6. With additional styling
-<schmancy-typography type="headline" token="sm" class="text-primary mb-4">
+<schmancy-typography type="headline" token="sm" class="mb-4 text-primary">
   Highlighted Section
 </schmancy-typography>
 
@@ -73,10 +73,10 @@ import '@mhmo91/schmancy/typography'
 
 // 10. Multiple typography in a card
 <schmancy-card class="p-6">
-  <schmancy-typography type="headline" token="sm" class="mb-2 block">
+  <schmancy-typography type="headline" token="sm" class="block mb-2">
     Card Title
   </schmancy-typography>
-  <schmancy-typography type="body" token="md" class="text-surface-onVariant mb-4 block">
+  <schmancy-typography type="body" token="md" class="block mb-4 text-surface-onVariant">
     This is a description that provides more context about the card content.
   </schmancy-typography>
   <schmancy-typography type="label" token="lg" class="text-primary">
@@ -180,17 +180,17 @@ Typography automatically inherits colors from the theme:
 
 1. **Page Layout**
    ```html
-   <schmancy-typography type="display" token="md" class="mb-4 block">
+   <schmancy-typography type="display" token="md" class="block mb-4">
      Dashboard
    </schmancy-typography>
-   <schmancy-typography type="body" token="lg" class="text-surface-onVariant block">
+   <schmancy-typography type="body" token="lg" class="block text-surface-onVariant">
      Welcome back! Here's your activity summary.
    </schmancy-typography>
    ```
 
 2. **Form Fields**
    ```html
-   <schmancy-typography type="label" token="md" class="mb-2 block">
+   <schmancy-typography type="label" token="md" class="block mb-2">
      Username
    </schmancy-typography>
    <schmancy-input placeholder="Enter username"></schmancy-input>
@@ -198,7 +198,7 @@ Typography automatically inherits colors from the theme:
 
 3. **Data Display**
    ```html
-   <schmancy-typography type="headline" token="md" class="text-primary block">
+   <schmancy-typography type="headline" token="md" class="block text-primary">
      $1,234.56
    </schmancy-typography>
    <schmancy-typography type="label" token="sm" class="text-surface-onVariant">
@@ -213,7 +213,7 @@ Typography automatically inherits colors from the theme:
        <schmancy-typography type="title" token="md" class="block">
          Feature One
        </schmancy-typography>
-       <schmancy-typography type="body" token="sm" class="text-surface-onVariant block">
+       <schmancy-typography type="body" token="sm" class="block text-surface-onVariant">
          Description of the first feature
        </schmancy-typography>
      </div>