@mhmo91/schmancy 0.8.6 → 0.9.3

package/ai/store.md

@@ -1,270 +1,192 @@
-# Schmancy Store - AI Reference
-
-```js
-// Store Creation
-import { createStore } from '@schmancy/index';
-// Or specific import: import { createStore } from '@schmancy/store';
-
-// 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)
-);
-
-// Component integration
-function MyComponent() {
-  const count = useSelector(getCount);
-  const activeUsers = useSelector(getActiveUsers);
-  
-  // React to state changes
-}
+# Store — State Foundation
+
+> **Not a utility. The state backbone of a Schmancy app.**
+> `createContext` + `@select` replaces Redux, Zustand, and a route-scoped cache without ceremony.
+
+A real app runs *many* small contexts — not one monolith. Typical production apps sit around 8–10:
 
-// 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;
-    }
-  }
-});
-
-// LocalStorage persistence
-import { StorageManager } from '@mhmo91/schmancy';
-new StorageManager({
-  key: 'theme-store',
-  storage: localStorage
-}).connect(themeStore);
-
-// 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;
-    }
-  }
-});
-
-// 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';
-
-@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
-}
+```
+userContext          ('local')      — signed-in user (persists across sessions)
+organizationContext  ('local')      — current org
+appStateContext      ('local')      — core app state (lists, selections, flags)
+agentsContext        ('memory')     — fetched data (re-fetched on reload)
+contactsContext      ('memory')     — Map<id, Contact> — mass data
+templatesContext     ('memory')     — list fetched from server
+currentTemplateIdCtx ('local')      — small pointer ref that persists
+composeContext       ('local')      — draft form state
+draftCtx             ('session')    — per-thread chat input (tab-scoped)
+strictCtx            ('session')    — per-thread toggles (tab-scoped)
 ```
 
-## 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
+**Split by persistence tier + lifetime**, not by feature area. Per-component ephemeral state → `session`. Cached fetches → `memory`. User-saved preferences → `local`. Large cached data → `indexeddb`.
 
-## Technical Details
+## Creating a context
 
-### Store Interfaces
 ```typescript
-interface StoreOptions<T> {
-  initialState: T;
-  actions?: Record<string, (state: T, ...args: any[]) => void>;
-}
+import { createContext } from '@mhmo91/schmancy'
 
-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 — persisted to localStorage
+export const userContext = createContext<User>(new User(), 'local', 'user')
 
-interface Context<T> {
-  get(): T;
-  update(updater: (state: T) => void): void;
-  subscribe(listener: (state: T) => void): () => void;
-}
+// Collection store — Map keyed by id
+export const contactsContext = createContext<Map<string, Contact>>(new Map(), 'memory', 'contacts')
+
+// Array store — ordered list
+export const tagsContext = createContext<string[]>([], 'memory', 'tags')
+
+// Session-scoped (per browser tab)
+export const draftContext = createContext<{ text: string }>({ text: '' }, 'session', 'compose-draft')
+```
+
+### Storage tiers
+
+| Mode | Backing | Survives refresh? | Survives tab close? | Size |
+|------|---------|-------------------|---------------------|------|
+| `'memory'` | JS heap | ❌ | ❌ | small |
+| `'session'` | `sessionStorage` | ✅ | ❌ (per-tab) | ~5 MB |
+| `'local'` | `localStorage` | ✅ | ✅ | ~5 MB |
+| `'indexeddb'` | IndexedDB | ✅ | ✅ | GB |
+
+Rule of thumb:
+- **User session data, prefs, drafts meant to persist** → `'local'`
+- **Per-tab ephemeral data** (wizard progress, per-thread drafts) → `'session'`
+- **Fetched from API, regenerable** → `'memory'`
+- **Large arrays, file-like data, offline-first** → `'indexeddb'`
 
-interface CollectionContext<T> extends Context<Record<string, T>> {
-  add(item: T): void;
-  update(id: string, updater: (item: T) => void): void;
-  remove(id: string): void;
+## Reading with `@select`
+
+```typescript
+import { select } from '@mhmo91/schmancy'
+
+@customElement('user-card')
+class UserCard extends $LitElement() {
+  // Auto-subscribes, re-renders on change
+  @select(userContext) user!: User
+
+  // Selector function narrows the dependency
+  @select(contactsContext, m => m.size) contactCount!: number
+
+  // Collection → stays as Map
+  @select(contactsContext) contacts!: Map<string, Contact>
 }
 ```
 
-### 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.
+`@select` options:
+- `required` (default `true`) — wait for context `.ready` before `connectedCallback` completes.
+- `updateOnly` — only call `requestUpdate`, don't assign. Use when you read the value imperatively.
+- `deepClone` — `structuredClone` the value to prevent accidental mutation.
+- `debug` — log every emission.
 
-```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
-});
+### Pick one item from a collection
+```typescript
+@selectItem(contactsContext, component => component.contactId)
+contact!: Contact | undefined
 ```
 
-### @select Decorator
-The `@select` decorator connects component properties to store state with automatic subscription management:
+Use this on components that carry the key as a property (e.g. `this.contactId`) — avoids reading the whole map.
+
+## Writing state
 
+### Object store
 ```typescript
-@select(store, selectorFn, options?)
+userContext.set({ name: 'Alice', email: 'alice@test.com' })
+userContext.set({ ...userContext.value, name: 'Bob' })  // partial update pattern
 ```
 
-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
-         );
-       });
-     }
-   );
-   ```
+### Collection (Map) store
+```typescript
+contactsContext.set('id-1', { id: 'id-1', name: 'Alice' })
+contactsContext.delete('id-1')
+contactsContext.replace(new Map([/* fresh batch */]))
+```
+
+### Array store
+```typescript
+tagsContext.push('new-tag')
+tagsContext.replace(['a', 'b', 'c'])
+```
+
+## Observable API
+
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+
+  userContext.$.pipe(
+    filter(() => userContext.ready),               // gate on initialization
+    distinctUntilChanged((a, b) => a.id === b.id), // ignore unrelated writes
+    switchMap(user => this.loadForUser(user)),     // cascade load
+    takeUntil(this.disconnecting),                 // cleanup
+  ).subscribe(data => this.data = data)
+}
+```
+
+- **`ctx.$`** — a `BehaviorSubject`. Use for chained transforms.
+- **`ctx.value`** — synchronous snapshot.
+- **`ctx.ready`** — boolean; becomes `true` after the backing store has loaded.
+
+### The gating pattern
+Every non-trivial subscription starts with `filter(() => ctx.ready)`. When your context is backed by `indexeddb` or re-hydrated from `localStorage`, the initial default value is emitted before the real stored value lands. Gate on `.ready` to skip the default.
+
+## Dynamic contexts (per-instance)
+
+For per-component ephemeral state that still benefits from persistence, instantiate the context **inside** `connectedCallback` with an instance-specific key:
+
+```typescript
+import { createContext, IStore } from '@mhmo91/schmancy'
+
+@customElement('chat-input')
+class ChatInput extends $LitElement() {
+  @property() draftKey?: string
+
+  private draftCtx: IStore<{ text: string }> | null = null
+
+  connectedCallback() {
+    super.connectedCallback()
+
+    if (this.draftKey) {
+      this.draftCtx = createContext<{ text: string }>(
+        { text: '' },
+        'session',
+        this.draftKey,          // e.g. `chat-draft-${threadId}`
+      )
+
+      // Hydrate once
+      this.draftCtx.$.pipe(
+        filter(() => this.draftCtx!.ready),
+        take(1),
+        tap(v => { this.text = v.text }),
+      ).subscribe()
+    }
+  }
+
+  private onInput(v: string) {
+    this.text = v
+    this.draftCtx?.set({ text: v })
+  }
+}
+```
+
+This is the pattern for *every* "draft that persists until sent" input.
+
+## Architectural rules
+
+1. **Declare contexts at module scope**, not inside classes — except dynamic per-instance ones.
+2. **Name the storage key** even for `'memory'` contexts — it helps debugging.
+3. **Keep each context small and single-purpose**. 9 small contexts beat 1 god context.
+4. **Subscribe with `takeUntil(this.disconnecting)`** — every time, no exceptions.
+5. **Gate on `.ready`** before any async cascading work.
+6. **Only the owning component writes**. Everyone else reads via `@select`.
+7. **Don't put functions, observables, or class instances into context** — only plain serializable data (for `'local'` / `'session'` / `'indexeddb'`).
+
+## Anti-patterns
+
+- ❌ Storing Promises in context. Use `memory` contexts for cached fetch *results*, not the in-flight Promise.
+- ❌ Cross-writing: component A writes to context X which is "owned" by component B. Centralize writes.
+- ❌ One monolithic `appContext` holding everything. You lose `distinctUntilChanged` granularity.
+- ❌ Forgetting `.ready` — causes double-fires on load with stale default values.
+- ❌ Using `'local'` for large blobs — hits quota, blocks the main thread on stringify/parse.
+
+## See also
+- [mixins](./mixins.md) — `$LitElement` provides `disconnecting` for every subscription.
+- [area](./area.md) — routing + contexts compose naturally (guards read context state).