@mhmo91/schmancy 0.2.193 → 0.2.194

package/ai/select.md

@@ -0,0 +1,174 @@
+# Schmancy Select - AI Reference
+
+```js
+// Basic Select
+<schmancy-select
+  name="select-name"
+  label="Select Label"
+  value="selected-value"
+  placeholder="Choose an option"
+  required?
+  disabled?
+  error="Error message"
+  @change=${handleChange}>
+  
+  <schmancy-option value="option1">Option 1</schmancy-option>
+  <schmancy-option value="option2">Option 2</schmancy-option>
+  <schmancy-option value="option3" disabled>Option 3</schmancy-option>
+</schmancy-select>
+
+// Select with helper text
+<schmancy-select
+  label="Country"
+  helper-text="Select your country of residence"
+  required>
+  <!-- Options -->
+</schmancy-select>
+
+// Multiple select
+<schmancy-select
+  multiple
+  label="Select Skills"
+  .value=${['html', 'css']}
+  @change=${(e) => console.log('Selected:', e.detail.value)}>
+  
+  <schmancy-option value="html">HTML</schmancy-option>
+  <schmancy-option value="css">CSS</schmancy-option>
+  <schmancy-option value="js">JavaScript</schmancy-option>
+  <schmancy-option value="ts">TypeScript</schmancy-option>
+</schmancy-select>
+
+// Select with option groups
+<schmancy-select label="Programming Language">
+  <optgroup label="Frontend">
+    <schmancy-option value="html">HTML</schmancy-option>
+    <schmancy-option value="css">CSS</schmancy-option>
+    <schmancy-option value="js">JavaScript</schmancy-option>
+  </optgroup>
+  
+  <optgroup label="Backend">
+    <schmancy-option value="node">Node.js</schmancy-option>
+    <schmancy-option value="python">Python</schmancy-option>
+    <schmancy-option value="java">Java</schmancy-option>
+  </optgroup>
+</schmancy-select>
+
+// Select with search
+<schmancy-select
+  searchable
+  label="Search Countries"
+  placeholder="Type to search...">
+  <!-- Many options -->
+</schmancy-select>
+
+// Select Methods
+select.focus() -> void          // Focus the select
+select.blur() -> void           // Remove focus
+select.open() -> void           // Open the dropdown
+select.close() -> void          // Close the dropdown
+select.validate() -> boolean    // Validate and show error if invalid
+select.reset() -> void          // Reset to initial value
+
+// Select Properties
+value: string | string[]   // Currently selected value(s)
+name: string               // The name attribute
+label: string              // Label text
+placeholder: string        // Placeholder text
+multiple: boolean          // Whether multiple selection is allowed
+disabled: boolean          // Whether the select is disabled
+required: boolean          // Whether a selection is required
+error: string              // Error message to display
+searchable: boolean        // Whether to allow searching within options
+open: boolean              // Whether the dropdown is open
+
+// Option Properties
+value: string              // Value of this option
+disabled: boolean          // Whether this option is disabled
+selected: boolean          // Whether this option is selected
+
+// Select Events
+@change  // Fires when selection changes, with { detail: { value } }
+@input   // Fires during interaction
+@focus   // Fires when select gains focus
+@blur    // Fires when select loses focus
+@open    // Fires when dropdown opens
+@close   // Fires when dropdown closes
+@search  // Fires during search with { detail: { query } }
+
+// Examples
+// Basic usage
+<schmancy-select
+  name="category"
+  label="Category"
+  value="electronics"
+  @change=${(e) => console.log('Selected:', e.detail.value)}>
+  
+  <schmancy-option value="electronics">Electronics</schmancy-option>
+  <schmancy-option value="clothing">Clothing</schmancy-option>
+  <schmancy-option value="books">Books</schmancy-option>
+  <schmancy-option value="food">Food & Beverages</schmancy-option>
+</schmancy-select>
+
+// Multiple select with initial values
+<schmancy-select
+  name="interests"
+  label="Interests"
+  multiple
+  .value=${userInterests} // Array of selected values
+  @change=${(e) => updateInterests(e.detail.value)}>
+  
+  <schmancy-option value="tech">Technology</schmancy-option>
+  <schmancy-option value="sports">Sports</schmancy-option>
+  <schmancy-option value="music">Music</schmancy-option>
+  <schmancy-option value="movies">Movies</schmancy-option>
+  <schmancy-option value="travel">Travel</schmancy-option>
+  <schmancy-option value="food">Food</schmancy-option>
+</schmancy-select>
+
+// Searchable select with many options
+<schmancy-select
+  name="country"
+  label="Country"
+  searchable
+  placeholder="Search for a country">
+  
+  ${countries.map(country => html`
+    <schmancy-option value=${country.code}>${country.name}</schmancy-option>
+  `)}
+</schmancy-select>
+
+// Usage in a form
+<schmancy-form @submit=${handleSubmit}>
+  <schmancy-input name="name" label="Name" required></schmancy-input>
+  
+  <schmancy-select
+    name="department"
+    label="Department"
+    required>
+    
+    <schmancy-option value="hr">Human Resources</schmancy-option>
+    <schmancy-option value="engineering">Engineering</schmancy-option>
+    <schmancy-option value="marketing">Marketing</schmancy-option>
+    <schmancy-option value="finance">Finance</schmancy-option>
+  </schmancy-select>
+  
+  <schmancy-button type="submit">Submit</schmancy-button>
+</schmancy-form>
+
+// Select with custom rendering
+<schmancy-select
+  name="user"
+  label="Assign to User"
+  @change=${assignToUser}>
+  
+  ${users.map(user => html`
+    <schmancy-option value=${user.id}>
+      <div style="display: flex; align-items: center;">
+        <schmancy-avatar src=${user.avatar} size="small"></schmancy-avatar>
+        <span style="margin-left: 8px;">${user.name}</span>
+        <span style="margin-left: auto; color: gray; font-size: 0.8em;">${user.role}</span>
+      </div>
+    </schmancy-option>
+  `)}
+</schmancy-select>
+```

package/ai/sheet.md

@@ -0,0 +1,122 @@
+# Schmancy Sheet - AI Reference
+
+```js
+// Sheet Service API
+import { $sheet } from 'schmancy';
+
+// Open a sheet
+$sheet.open({
+  title?: string,
+  content: TemplateResult|HTMLElement|Function,
+  width?: string|number, // default "600px"
+  height?: string|number, // default "auto"
+  position?: 'right'|'left'|'bottom'|'top', // default "right"
+  closable?: boolean, // default true
+  backdrop?: boolean, // default false
+  onClose?: Function,
+  hooks?: {
+    beforeOpen?: Function,
+    afterOpen?: Function,
+    beforeClose?: Function,
+    afterClose?: Function
+  }
+}) -> SheetRef
+
+// SheetRef object
+{
+  close(): Promise<void>, // Programmatically close the sheet
+  id: string,            // Unique ID of the sheet
+  element: HTMLElement   // The sheet element
+}
+
+// Sheet Component
+<schmancy-sheet
+  title="Sheet Title"
+  position="right|left|bottom|top"
+  width="600px"
+  height="auto"
+  closable?
+  backdrop?
+  @close=${handleClose}>
+  
+  <div slot="header">
+    <!-- Custom header content -->
+  </div>
+  
+  <!-- Main content -->
+  <div>Sheet content goes here</div>
+  
+  <div slot="footer">
+    <!-- Footer content -->
+    <schmancy-button @click=${closeSheet}>Close</schmancy-button>
+  </div>
+</schmancy-sheet>
+
+// Sheet Header Component
+<schmancy-sheet-header
+  title="Sheet Title"
+  closable?
+  @close=${handleClose}>
+  <!-- Optional additional header content -->
+</schmancy-sheet-header>
+
+// Sheet Hook (for programmatic usage)
+const [openSheet, SheetComponent] = useSheet({
+  title: "Sheet Title",
+  content: () => html`<div>Sheet content</div>`,
+  position: "right"
+});
+
+// Examples
+// Basic usage
+$sheet.open({
+  title: "User Details",
+  content: html`
+    <div>
+      <schmancy-form>
+        <schmancy-input label="Name" value="John Doe"></schmancy-input>
+        <schmancy-input label="Email" value="john@example.com"></schmancy-input>
+      </schmancy-form>
+    </div>
+  `,
+  onClose: () => console.log("Sheet closed")
+});
+
+// Using with form submission
+const sheetRef = $sheet.open({
+  title: "Add User",
+  content: html`
+    <schmancy-form @submit=${(e) => {
+      const values = e.detail.values;
+      saveUser(values);
+      sheetRef.close();
+    }}>
+      <schmancy-input name="name" label="Name" required></schmancy-input>
+      <schmancy-input name="email" label="Email" required></schmancy-input>
+      
+      <div slot="footer">
+        <schmancy-button type="submit">Save</schmancy-button>
+        <schmancy-button kind="secondary" @click=${() => sheetRef.close()}>Cancel</schmancy-button>
+      </div>
+    </schmancy-form>
+  `
+});
+
+// Using the sheet component directly
+<schmancy-sheet
+  title="Settings"
+  position="right"
+  width="400px"
+  @close=${() => this.sheetOpen = false}>
+  
+  <div>
+    <h3>Preferences</h3>
+    <schmancy-checkbox label="Enable notifications"></schmancy-checkbox>
+    <schmancy-checkbox label="Dark mode"></schmancy-checkbox>
+  </div>
+  
+  <div slot="footer">
+    <schmancy-button @click=${saveSettings}>Save</schmancy-button>
+  </div>
+</schmancy-sheet>
+```

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