@mhmo91/schmancy 0.2.193 → 0.2.195

package/ai/store.md

@@ -0,0 +1,235 @@
+# Schmancy Store - AI Reference
+
+```js
+// Store Creation
+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/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/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
+}
+
+// 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 'schmancy/store';
+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;
+    }
+  }
+);
+```
+
+## 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
+```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;
+}
+
+interface Context<T> {
+  get(): T;
+  update(updater: (state: T) => void): void;
+  subscribe(listener: (state: T) => void): () => void;
+}
+
+interface CollectionContext<T> extends Context<Record<string, T>> {
+  add(item: T): void;
+  update(id: string, updater: (item: T) => void): void;
+  remove(id: string): void;
+}
+```
+
+### 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.
+
+```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
+});
+```
+
+### 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/ai/surface.md

@@ -0,0 +1,221 @@
+# Schmancy Surface - AI Reference
+
+```js
+// Basic Surface
+<schmancy-surface
+  elevation="0|1|2|3|4|5"
+  rounded="none|sm|md|lg|xl|full"
+  padding="none|xs|sm|md|lg|xl">
+  Surface content goes here
+</schmancy-surface>
+
+// Surface with color
+<schmancy-surface
+  color="primary|secondary|tertiary|surface|background|error"
+  theme="light|dark">
+  Colored surface content
+</schmancy-surface>
+
+// Interactive surface
+<schmancy-surface
+  interactive
+  @click=${handleClick}>
+  Click me!
+</schmancy-surface>
+
+// Surface with border
+<schmancy-surface
+  bordered
+  border-color="primary|secondary|tertiary|divider|error"
+  border-width="thin|medium|thick"
+  border-style="solid|dashed|dotted">
+  Surface with border
+</schmancy-surface>
+
+// Surface with dimensions
+<schmancy-surface
+  width="300px"
+  height="200px"
+  min-width="200px"
+  max-width="500px"
+  min-height="100px"
+  max-height="300px">
+  Fixed size surface
+</schmancy-surface>
+
+// Surface Properties
+elevation: number|string  // Shadow elevation (0-5)
+rounded: string           // Border radius: "none", "sm", "md", "lg", "xl", "full"
+padding: string           // Padding: "none", "xs", "sm", "md", "lg", "xl"
+margin: string            // Margin: "none", "xs", "sm", "md", "lg", "xl"
+color: string             // Background color (theme color or CSS value)
+theme: string             // Theme: "light", "dark"
+interactive: boolean      // Enable hover and active states
+bordered: boolean         // Show border
+borderColor: string       // Border color
+borderWidth: string       // Border width: "thin", "medium", "thick"
+borderStyle: string       // Border style: "solid", "dashed", "dotted"
+width: string             // Width
+height: string            // Height
+minWidth: string          // Minimum width
+maxWidth: string          // Maximum width
+minHeight: string         // Minimum height
+maxHeight: string         // Maximum height
+fullWidth: boolean        // Take full width of parent
+fullHeight: boolean       // Take full height of parent
+
+// Surface Context
+// For theme-aware surfaces and consistent styling
+import { SurfaceContext } from 'schmancy/surface';
+
+const surfaceContext = new SurfaceContext({
+  elevation: 1,
+  rounded: 'md',
+  padding: 'md',
+  theme: 'light'
+});
+
+// Examples
+// Basic card-like surface
+<schmancy-surface
+  elevation="2"
+  rounded="lg"
+  padding="lg">
+  <h3>Card Title</h3>
+  <p>This is a basic card surface with elevation, rounded corners, and padding.</p>
+</schmancy-surface>
+
+// Interactive card
+<schmancy-surface
+  elevation="1"
+  rounded="md"
+  padding="md"
+  interactive
+  @click=${navigateToDetails}>
+  <div style="display: flex; align-items: center; gap: 16px;">
+    <schmancy-avatar
+      src="path/to/avatar.jpg"
+      size="large">
+    </schmancy-avatar>
+    
+    <div>
+      <h3>John Doe</h3>
+      <p>Software Engineer</p>
+    </div>
+    
+    <schmancy-icon
+      icon="chevron-right"
+      style="margin-left: auto;">
+    </schmancy-icon>
+  </div>
+</schmancy-surface>
+
+// Alert surfaces
+<schmancy-surface
+  color="primary"
+  rounded="md"
+  padding="md"
+  bordered
+  border-color="primary"
+  style="--surface-color-opacity: 0.1;">
+  <div style="display: flex; align-items: center; gap: 16px;">
+    <schmancy-icon icon="info" color="primary"></schmancy-icon>
+    <div>
+      <h4>Information</h4>
+      <p>This is an informational message.</p>
+    </div>
+  </div>
+</schmancy-surface>
+
+<schmancy-surface
+  color="error"
+  rounded="md"
+  padding="md"
+  bordered
+  border-color="error"
+  style="--surface-color-opacity: 0.1;">
+  <div style="display: flex; align-items: center; gap: 16px;">
+    <schmancy-icon icon="alert-triangle" color="error"></schmancy-icon>
+    <div>
+      <h4>Error</h4>
+      <p>Something went wrong. Please try again.</p>
+    </div>
+  </div>
+</schmancy-surface>
+
+// Surface grid layout
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
+  <schmancy-surface
+    elevation="1"
+    rounded="md"
+    padding="md">
+    <h3>Card 1</h3>
+    <p>Content for card 1.</p>
+  </schmancy-surface>
+  
+  <schmancy-surface
+    elevation="1"
+    rounded="md"
+    padding="md">
+    <h3>Card 2</h3>
+    <p>Content for card 2.</p>
+  </schmancy-surface>
+  
+  <schmancy-surface
+    elevation="1"
+    rounded="md"
+    padding="md">
+    <h3>Card 3</h3>
+    <p>Content for card 3.</p>
+  </schmancy-surface>
+</div>
+
+// Dashboard panel
+<schmancy-surface
+  elevation="2"
+  rounded="lg"
+  padding="lg"
+  height="300px">
+  <div style="display: flex; flex-direction: column; height: 100%;">
+    <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px;">
+      <h3>Sales Overview</h3>
+      <schmancy-dropdown>
+        <schmancy-button slot="trigger" variant="tertiary" size="small">
+          <span>This Week</span>
+          <schmancy-icon slot="suffix" icon="chevron-down"></schmancy-icon>
+        </schmancy-button>
+        
+        <schmancy-menu slot="content">
+          <schmancy-menu-item value="day">Today</schmancy-menu-item>
+          <schmancy-menu-item value="week">This Week</schmancy-menu-item>
+          <schmancy-menu-item value="month">This Month</schmancy-menu-item>
+          <schmancy-menu-item value="year">This Year</schmancy-menu-item>
+        </schmancy-menu>
+      </schmancy-dropdown>
+    </div>
+    
+    <div style="flex: 1; display: flex; align-items: center; justify-content: center;">
+      <!-- Chart or content would go here -->
+      <p>Chart placeholder</p>
+    </div>
+  </div>
+</schmancy-surface>
+
+// Using surface context
+<div .context=${surfaceContext}>
+  <schmancy-surface>
+    <h3>First Panel</h3>
+    <p>This surface inherits settings from the context.</p>
+  </schmancy-surface>
+  
+  <schmancy-surface>
+    <h3>Second Panel</h3>
+    <p>This surface also inherits settings from the context.</p>
+  </schmancy-surface>
+  
+  <schmancy-surface elevation="3" rounded="xl">
+    <h3>Custom Panel</h3>
+    <p>This surface overrides some context settings.</p>
+  </schmancy-surface>
+</div>
+```