@mhmo91/schmancy 0.8.6 → 0.9.2

package/dist/ai/store.md

@@ -1,270 +1,83 @@
-# Schmancy Store - AI Reference
+# Schmancy Store (Context System)
 
-```js
-// Store Creation
-import { createStore } from '@schmancy/index';
-// Or specific import: import { createStore } from '@schmancy/store';
+> Reactive state management with `createContext`, `@select` decorator, and persistent storage.
 
-// Basic store creation
-const store = createStore({
-  initialState: {
-    count: 0,
-    users: [],
-    settings: { darkMode: false }
-  }
-});
-
-// Store with actions
-const counterStore = createStore({
-  initialState: { count: 0 },
-  actions: {
-    increment: (state, amount = 1) => { state.count += amount; },
-    decrement: (state, amount = 1) => { state.count -= amount; },
-    reset: (state) => { state.count = 0; }
-  }
-});
-
-// Store Context Creation
-import { createContext, createCollectionContext } from '@schmancy/index';
-// Or specific import: import { createContext, createCollectionContext } from '@schmancy/store';
-
-// Object/array/collection contexts
-const settingsContext = createContext(store, 'settings');           // Object
-const usersContext = createContext(store, 'users');                 // Array
-const todoCollection = createCollectionContext(store, 'todos');     // Collection with IDs
-
-// State Manipulation Methods
-store.createAction('addUser', (state, user) => {                    // Custom action
-  state.users.push(user);
-});
-
-store.update(state => {                                             // Direct update
-  state.count++;
-  state.settings.darkMode = true;
-});
-
-todoCollection.add({ id: '1', text: 'Buy milk' });                  // Collection add
-todoCollection.update('1', item => { item.completed = true; });     // Collection update
-todoCollection.remove('1');                                         // Collection remove
-
-// Selectors
-import { createSelector, useSelector } from '@schmancy/index';
-// Or specific import: import { createSelector, useSelector } from '@schmancy/store';
-
-// Basic and computed selectors
-const getCount = state => state.count;
-const getActiveUsers = createSelector(
-  state => state.users,
-  (users) => users.filter(user => user.active)
-);
+## Creating a Context
+```typescript
+import { createContext } from '@mhmo91/schmancy'
 
-// Component integration
-function MyComponent() {
-  const count = useSelector(getCount);
-  const activeUsers = useSelector(getActiveUsers);
-  
-  // React to state changes
-}
+// Object store
+const userContext = createContext({ name: '', email: '' }, 'local', 'user')
 
-// Examples
-// 1. Theme store with persistence
-const themeStore = createStore({
-  initialState: { mode: 'light', fontSize: 'medium' },
-  actions: {
-    toggleTheme: state => {
-      state.mode = state.mode === 'light' ? 'dark' : 'light';
-    },
-    setFontSize: (state, size) => {
-      state.fontSize = size;
-    }
-  }
-});
+// Collection store (Map-based)
+const itemsContext = createContext(new Map<string, Item>(), 'indexeddb', 'items')
 
-// LocalStorage persistence
-import { StorageManager } from '@mhmo91/schmancy';
-new StorageManager({
-  key: 'theme-store',
-  storage: localStorage
-}).connect(themeStore);
+// Array store
+const tagsContext = createContext<string>([], 'memory', 'tags')
+```
 
-// 2. Todo application store
-const todoStore = createStore({
-  initialState: {
-    todos: [],
-    filter: 'all'
-  },
-  actions: {
-    addTodo: (state, text) => {
-      state.todos.push({
-        id: Date.now().toString(),
-        text,
-        completed: false
-      });
-    },
-    toggleTodo: (state, id) => {
-      const todo = state.todos.find(todo => todo.id === id);
-      if (todo) todo.completed = !todo.completed;
-    },
-    setFilter: (state, filter) => {
-      state.filter = filter;
-    }
-  }
-});
+## Storage Types
+| Type | Description |
+|------|-------------|
+| `'memory'` | In-memory only (lost on refresh) |
+| `'local'` | localStorage (persistent) |
+| `'session'` | sessionStorage (per tab) |
+| `'indexeddb'` | IndexedDB (large data, persistent) |
 
-// 3. Filtered todos selector
-const getFilteredTodos = createSelector(
-  state => state.todos,
-  state => state.filter,
-  (todos, filter) => {
-    switch (filter) {
-      case 'active': return todos.filter(t => !t.completed);
-      case 'completed': return todos.filter(t => t.completed);
-      default: return todos;
-    }
-  }
-);
-// 4. Using @select decorator in components
-import { select } from '@schmancy/index';
-// Or specific import: import { select } from '@schmancy/store';
+## Reading State with @select
+```typescript
+import { select } from '@mhmo91/schmancy'
 
 @customElement('my-component')
-class MyComponent extends LitElement {
-  // Auto-subscribes to store state
-  @select(store, state => state.count)
-  count!: number;
-  
-  // With options
-  @select(store, state => state.user, { required: false })
-  user?: User;
-  
-  // The component will automatically update when these values change
+class MyComponent extends $LitElement() {
+  // Auto-subscribes to context changes, triggers re-render
+  @select(userContext)
+  user!: { name: string; email: string }
+
+  // With selector function
+  @select(itemsContext, (items) => items.size)
+  itemCount!: number
+
+  // Collection as Map
+  @select(itemsContext)
+  items!: Map<string, Item>
 }
 ```
 
-## Related Components
-- **[Area](./area.md)**: Uses similar reactive patterns for routing state
-- **[Theme](./theme.md)**: Often uses store for theme state management
-- **[Form](./form.md)**: Can use store for form state management
-
-## Technical Details
-
-### Store Interfaces
+## Writing State
 ```typescript
-interface StoreOptions<T> {
-  initialState: T;
-  actions?: Record<string, (state: T, ...args: any[]) => void>;
-}
-
-interface Store<T> {
-  getState(): T;
-  update(updater: (state: T) => void): void;
-  subscribe(listener: (state: T) => void): () => void;
-  createAction<Args extends any[]>(
-    name: string,
-    action: (state: T, ...args: Args) => void
-  ): (...args: Args) => void;
-}
+// Object store
+userContext.set({ name: 'Alice', email: 'alice@test.com' })
 
-interface Context<T> {
-  get(): T;
-  update(updater: (state: T) => void): void;
-  subscribe(listener: (state: T) => void): () => void;
-}
+// Collection store
+itemsContext.set('item-1', { name: 'Widget' })
+itemsContext.delete('item-1')
+itemsContext.replace(new Map([...]))
 
-interface CollectionContext<T> extends Context<Record<string, T>> {
-  add(item: T): void;
-  update(id: string, updater: (item: T) => void): void;
-  remove(id: string): void;
-}
+// Array store
+tagsContext.push('new-tag')
+tagsContext.replace(['a', 'b', 'c'])
 ```
 
-### Integration with Immer
-The store uses Immer under the hood to enable immutable updates with mutable syntax. This means you can write code that appears to directly modify the state, but behind the scenes, it's creating a new immutable state tree.
+## Observable API
+```typescript
+// Subscribe to changes
+userContext.$.pipe(
+  takeUntil(this.disconnecting)
+).subscribe(user => { ... })
+
+// Current value (synchronous)
+const current = userContext.value
 
-```js
-// This looks like direct mutation but is actually immutable
-store.update(state => {
-  state.count++;           // Modifying a primitive
-  state.users.push(user);  // Modifying an array
-  state.deep.nested.value = true; // Modifying a nested property
-});
+// Ready state
+if (userContext.ready) { ... }
 ```
 
-### @select Decorator
-The `@select` decorator connects component properties to store state with automatic subscription management:
+## @select Options
+`required` (default true): wait for value before connectedCallback. `updateOnly`: only requestUpdate. `deepClone`: structuredClone. `debug`: log activity.
 
+## selectItem (Collection Helper)
 ```typescript
-@select(store, selectorFn, options?)
+@selectItem(itemsContext, (component) => component.itemId)
+selectedItem!: Item | undefined
 ```
-
-Options:
-- `required: boolean` (default: true) - Wait for non-undefined value before calling connectedCallback
-- `updateOnly: boolean` - Only trigger updates, don't set property value
-- `deepClone: boolean` - Use structuredClone for deep cloning values
-- `equals: (a, b) => boolean` - Custom equality function
-- `debug: boolean` - Enable debug logging
-
-The decorator ensures `connectedCallback` is called only once, even with multiple @select decorators.
-
-### Common Use Cases
-
-1. **Application theme state**
-   ```js
-   const themeStore = createStore({
-     initialState: { mode: 'light' },
-     actions: {
-       toggleTheme: state => {
-         state.mode = state.mode === 'light' ? 'dark' : 'light';
-       }
-     }
-   });
-   
-   // In a component
-   const mode = useSelector(state => state.mode);
-   const toggleTheme = () => themeStore.actions.toggleTheme();
-   ```
-
-2. **Form state management**
-   ```js
-   const formStore = createStore({
-     initialState: {
-       values: { name: '', email: '' },
-       errors: {},
-       isDirty: false,
-       isSubmitting: false
-     },
-     actions: {
-       setField: (state, field, value) => {
-         state.values[field] = value;
-         state.isDirty = true;
-       },
-       setError: (state, field, error) => {
-         state.errors[field] = error;
-       },
-       submit: (state) => {
-         state.isSubmitting = true;
-       },
-       reset: (state) => {
-         state.values = { name: '', email: '' };
-         state.errors = {};
-         state.isDirty = false;
-       }
-     }
-   });
-   ```
-
-3. **Filtered data with memoization**
-   ```js
-   const getFilteredItems = createSelector(
-     state => state.items,
-     state => state.filters,
-     (items, filters) => {
-       return items.filter(item => {
-         // Apply filters
-         return Object.entries(filters).every(([key, value]) => 
-           !value || item[key] === value
-         );
-       });
-     }
-   );
-   ```

package/dist/ai/surface.md

@@ -1,273 +1,86 @@
-# Schmancy Surface - AI Reference
+# Surface
 
-```js
-// Surface Component
-<schmancy-surface
-  fill="all|width|height|auto"
-  rounded="none|top|left|right|bottom|all"
-  type="surface|surfaceDim|surfaceBright|containerLowest|containerLow|container|containerHigh|containerHighest|glass|glassOforim|transparent|primary|primaryContainer|secondary|secondaryContainer|tertiary|tertiaryContainer|error|errorContainer"
-  elevation="0|1|2|3|4|5">
-  Content goes here
+> Glass depth container. Every surface is translucent — depth comes from blur intensity.
+
+## Usage
+
+```html
+<schmancy-surface type="subtle" rounded="all" fill="all">
+  Content on frosted glass
 </schmancy-surface>
+```
 
-// Properties
-fill: string          // "all", "width", "height", "auto" (default: "auto")
-rounded: string       // Corner rounding: "none", "top", "left", "right", "bottom", "all" (default: "none")
-type: string          // Surface color variant (default: "container")
-elevation: number     // Shadow depth 0-5 (default: 0)
+## Properties
 
-// Surface Types (19 total variants)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | string | `'subtle'` | Glass depth level (see below) |
+| `fill` | string | `'auto'` | `'all'`, `'width'`, `'height'`, `'auto'` |
+| `rounded` | string | `'none'` | `'none'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'all'` |
+| `elevation` | number | `0` | Glow intensity 0-5 (primary-colored glow, not shadow) |
+| `clickable` | boolean | `false` | Adds luminous hover + spring press |
 
-// Neutral Surfaces (8 types) - for general backgrounds
-"surface"             // Default surface color
-"surfaceDim"          // Dimmed surface
-"surfaceBright"       // Bright surface
-"containerLowest"     // Lowest container elevation
-"containerLow"        // Low container elevation
-"container"           // Standard container (default)
-"containerHigh"       // High container elevation
-"containerHighest"    // Highest container elevation
+## Surface Types
 
-// Glass Effects (3 types) - for modern glassmorphism
-"glass"               // Standard glass effect with backdrop blur
-"glassOforim"         // Enhanced glass with stronger blur effect
-"transparent"         // Fully transparent background
+### Structural (glass depth model)
 
-// State-Based Surfaces (8 types) - for selection/semantic meaning
-"primary"             // High emphasis primary (selected/active states)
-"primaryContainer"    // Lower emphasis primary container
-"secondary"           // High emphasis secondary
-"secondaryContainer"  // Lower emphasis secondary container
-"tertiary"            // High emphasis tertiary
-"tertiaryContainer"   // Lower emphasis tertiary container
-"error"               // High emphasis error state
-"errorContainer"      // Lower emphasis error container
+| Type | Opacity | Blur | Use for |
+|------|---------|------|---------|
+| `solid` | 92% | — | Dense glass ground layer, highest readability |
+| `subtle` | 78% | 8px | Frosted panels, default containers |
+| `glass` | 55% | 16px | Dialogs, dropdowns, overlays |
+| `luminous` | 42% | 20px | Hero panels, featured content |
 
-// Examples
-// 1. Basic surface
-<schmancy-surface>
-  Basic content
-</schmancy-surface>
+### Semantic (tinted glass)
+`primary`, `secondary`, `tertiary`, `error`, `success`, `warning`, `info`
+Each applies a translucent tint of its color + 4px blur.
 
-// 2. Elevated card
-<schmancy-surface
-  elevation="2"
-  rounded="all"
-  type="containerLow">
-  <h3>Card Title</h3>
-  <p>Card content</p>
-</schmancy-surface>
+### Utility
+- `transparent` — no background
+- `outlined` — border only
+
+## Examples
 
-// 3. Full-width surface
-<schmancy-surface
-  fill="width"
-  type="surfaceDim"
-  elevation="1">
-  Full width content
+```html
+<!-- Page background -->
+<schmancy-surface type="solid" fill="all" rounded="none">
+  <slot></slot>
 </schmancy-surface>
 
-// 4. Dashboard panel
-<schmancy-surface
-  elevation="3"
-  rounded="all"
-  type="containerHighest"
-  fill="all">
-  <div class="dashboard-content">
-    <!-- Content -->
-  </div>
+<!-- Card-like container -->
+<schmancy-surface type="subtle" rounded="all" elevation="1">
+  <div class="p-4">Frosted panel with glow</div>
 </schmancy-surface>
 
-// 5. Glass effect surface
-<schmancy-surface
-  type="glass"
-  rounded="all"
-  elevation="2"
-  class="p-6">
-  Modern glassmorphism card
+<!-- Dialog surface (used internally by schmancy-dialog) -->
+<schmancy-surface type="glass" rounded="all">
+  <div class="p-6">Glass overlay content</div>
 </schmancy-surface>
 
-// 6. Selected state (interactive list item)
-<schmancy-surface
-  type=${isSelected ? 'primaryContainer' : 'containerHighest'}
-  rounded="all"
-  class="cursor-pointer p-4">
-  Selectable item
+<!-- Hero panel with glow halo -->
+<schmancy-surface type="luminous" rounded="all" elevation="3">
+  <div class="p-8">Featured content</div>
 </schmancy-surface>
 
-// 7. Error message container
-<schmancy-surface
-  type="errorContainer"
-  rounded="all"
-  class="p-4">
-  <p>Validation error message</p>
+<!-- Clickable surface with spring physics -->
+<schmancy-surface type="subtle" rounded="all" clickable @click=${handler}>
+  Hover: lift + glow. Press: spring compress.
 </schmancy-surface>
 
-// 8. Transparent overlay
-<schmancy-surface
-  type="transparent"
-  fill="all"
-  class="absolute inset-0">
-  Transparent overlay content
+<!-- Error state -->
+<schmancy-surface type="error" rounded="all">
+  <div class="p-3">Something went wrong</div>
 </schmancy-surface>
 ```
 
-## Related Components
-- **[Card](./card.md)**: Pre-styled surface for card layouts
-- **[Sheet](./sheet.md)**: Modal surface overlay
-- **[Dialog](./dialog.md)**: Elevated modal surface
-- **[Layout](./layout.md)**: Layout components that often contain surfaces
+## Elevation (Glow-based)
 
-## Technical Details
-
-### CSS Host Styling
-The component uses `:host` selectors for all styling:
-- No wrapper elements - styles apply directly to the component
-- Properties reflect to HTML attributes for CSS targeting
-- Uses CSS custom properties from the theme system
-
-### Theme Integration
-```css
-/* Background colors use theme variables */
---schmancy-sys-color-surface-default
---schmancy-sys-color-surface-dim
---schmancy-sys-color-surface-bright
---schmancy-sys-color-surface-lowest
---schmancy-sys-color-surface-low
---schmancy-sys-color-surface-container
---schmancy-sys-color-surface-high
---schmancy-sys-color-surface-highest
-
-/* Text color */
---schmancy-sys-color-surface-on
-
-/* Elevation shadows */
---schmancy-sys-elevation-1 through --schmancy-sys-elevation-5
+Elevation 1-5 applies a primary-colored glow underneath the surface:
 ```
-
-### Context Provider
-Surface provides its type to descendant components via Lit Context:
-```js
-import { SchmancySurfaceTypeContext } from '@schmancy/index'
-// Or specific import: import { SchmancySurfaceTypeContext } from '@schmancy/surface'
+Level 1: subtle glow (15% primary)
+Level 5: strong glow (42% primary)
 ```
 
-## Common Use Cases
-
-1. **Content Cards**: Elevated surfaces for grouped content
-   ```html
-   <schmancy-surface elevation="2" rounded="all" type="containerLow">
-     <h3>Feature Card</h3>
-     <p>Description of the feature</p>
-     <schmancy-button>Learn More</schmancy-button>
-   </schmancy-surface>
-   ```
-
-2. **Page Sections**: Full-width background surfaces
-   ```html
-   <schmancy-surface fill="width" type="surfaceDim">
-     <section class="hero-section">
-       <h1>Welcome</h1>
-       <p>Hero content here</p>
-     </section>
-   </schmancy-surface>
-   ```
-
-3. **Modal Backgrounds**: High elevation surfaces
-   ```html
-   <schmancy-surface 
-     elevation="5" 
-     rounded="all" 
-     type="containerHighest">
-     <div class="modal-content">
-       <h2>Modal Title</h2>
-       <p>Modal body content</p>
-     </div>
-   </schmancy-surface>
-   ```
-
-4. **Nested Surfaces**: Different elevation levels
-   ```html
-   <schmancy-surface type="surface" fill="all">
-     <schmancy-surface 
-       elevation="1" 
-       rounded="all" 
-       type="containerLow">
-       <p>Nested content with different elevation</p>
-     </schmancy-surface>
-   </schmancy-surface>
-   ```
-
-5. **Sidebar Panels**: Directional rounding
-   ```html
-   <schmancy-surface
-     fill="height"
-     rounded="right"
-     elevation="2"
-     type="containerHigh">
-     <nav class="sidebar">
-       <!-- Navigation items -->
-     </nav>
-   </schmancy-surface>
-   ```
-
-6. **Glass Effect Cards**: Modern glassmorphism
-   ```html
-   <schmancy-surface
-     type="glass"
-     elevation="3"
-     rounded="all"
-     class="p-6">
-     <h3>Premium Feature</h3>
-     <p>Glass effect with backdrop blur</p>
-   </schmancy-surface>
-   ```
-
-7. **Selected List Items**: Selection states
-   ```html
-   <schmancy-surface
-     type=${item.selected ? 'primaryContainer' : 'containerHighest'}
-     rounded="all"
-     class="cursor-pointer p-4 transition-all hover:scale-[1.01]"
-     @click=${() => toggleSelection(item)}>
-     ${item.name}
-   </schmancy-surface>
-   ```
-
-8. **Error/Warning Messages**: Semantic containers
-   ```html
-   <!-- Error message -->
-   <schmancy-surface type="errorContainer" rounded="all" class="p-4 mb-4">
-     <strong>Error:</strong> Please fix the validation errors
-   </schmancy-surface>
-
-   <!-- Info message -->
-   <schmancy-surface type="primaryContainer" rounded="all" class="p-4">
-     <strong>Info:</strong> Your changes have been saved
-   </schmancy-surface>
-   ```
-
-9. **Transparent Overlays**: Modal backgrounds
-   ```html
-   <schmancy-surface
-     type="transparent"
-     fill="all"
-     class="absolute inset-0 flex items-center justify-center">
-     <schmancy-surface type="glass" elevation="5" rounded="all" class="p-8">
-       <h2>Modal Content</h2>
-       <p>Transparent overlay with glass modal</p>
-     </schmancy-surface>
-   </schmancy-surface>
-   ```
+## Paint Containment
 
-10. **Interactive Cards**: Hover states with type switching
-    ```html
-    <schmancy-surface
-      type=${isHovered ? 'secondaryContainer' : 'container'}
-      elevation="2"
-      rounded="all"
-      class="p-6 transition-all cursor-pointer"
-      @mouseenter=${() => setHovered(true)}
-      @mouseleave=${() => setHovered(false)}>
-      Hover me!
-    </schmancy-surface>
-    ```
+`glass` and `luminous` types automatically apply `contain: content` for GPU optimization.