cogsbox-state 0.5.7 → 0.5.8

package/README.md

@@ -1,386 +1,580 @@
-# Cobgsbox State
+# Cogsbox State: A Practical Guide
 
-> ⚠️ **Warning**: This package is currently a work in progress and not ready for production use. The API is unstable and subject to breaking changes. Please do not use in production environments.
+## Getting Started
 
----
+Cogsbox State is a React state management library that provides a fluent interface for managing complex state.
 
-Cobgsbox State is a state management library that provides a fluent interface for managing complex state in React applications.
+### Basic Setup
 
-## Installation
+```typescript
+// 1. Define your initial state
+const InitialState = {
+  users: [],
+  settings: {
+    darkMode: false,
+    notifications: true
+  },
+  cart: {
+    items: [],
+    total: 0
+  }
+};
 
-```bash
-npm install cogsbox-state
-```
+// 2. Create the state hook
+export const { useCogsState } = createCogsState(InitialState);
 
-## Features
+// 3. Use in your component
+function MyComponent() {
+  const [state, updater] = useCogsState("cart");
 
-- 🎯 **Simplified Deep Updates**
+  // Access values
+  const cartItems = updater.items.get();
+  const total = updater.total.get();
 
-    ```typescript
-    // Instead of setState(prev => ({ ...prev, deep: { ...prev.deep, value: newValue }}))
-    updater.deep.value.update(newValue);
-    ```
+  // Update values
+  const addItem = (item) => {
+    updater.items.insert(item);
+    updater.total.update(total + item.price);
+  };
 
-- 🔄 **Fluent Array Operations**
+  return (
+    // Your component JSX
+  );
+}
+```
 
-    ```typescript
-    // Find, filter, and update in one chain
-    updater.items.findWith("id", "123").status.update("complete");
-    ```
+## Core Concepts
 
-- 📝 **Smart Form Handling**
+### Accessing State
 
-    - Automatic debouncing
-    - Validation integration
-    - Form state synchronization
+```typescript
+// Get the entire state object
+const entireCart = updater.get();
 
-- 🔍 **Powerful Array Methods**
+// Access a specific property
+const cartItems = updater.items.get();
 
-    - Filter with state access
-    - Flatten nested arrays
-    - Unique insertions
-    - Map with updaters
+// Access nested properties
+const firstItemPrice = updater.items[0].price.get();
+```
 
-- 🔄 **State Sync Features**
+### Updating State
 
-    - Server synchronization
-    - Local storage persistence
-    - Optimistic updates
+```typescript
+// Direct update
+updater.settings.darkMode.update(true);
 
-- 🛠 **Developer Experience**
+// Functional update (based on previous value)
+updater.cart.total.update((prev) => prev + 10);
 
-    - Full TypeScript support
-    - Path autocompletion
-    - Runtime type checking
+// Deep update
+updater.users.findWith("id", "123").name.update("New Name");
+```
 
-- ⚡ **Performance**
-    - Granular updates
-    - Automatic optimization
-    - Path-based subscriptions
+## Working with Arrays
 
-## Initialization
+### Basic Array Operations
 
 ```typescript
-// Define your state shape
-interface Product {
-    id: string;
-    name: string;
-    price: number;
-    categories: string[];
-    variants: {
-        id: string;
-        color: string;
-        size: string;
-        stock: number;
-    }[];
-}
+// Add an item
+updater.cart.items.insert({ id: "prod1", name: "Product 1", price: 29.99 });
 
-interface CartItem {
-    productId: string;
-    variantId: string;
-    quantity: number;
-}
-
-const InitialState = {
-    catalog: {
-        products: [] as Product[],
-        categories: [] as string[],
-        filters: {
-            priceRange: { min: 0, max: 100 },
-            selectedCategories: [] as string[],
-            search: "",
-        },
-        sortBy: "price_asc" as "price_asc" | "price_desc" | "name",
-    },
-    cart: {
-        items: [] as CartItem[],
-        couponCode: "",
-        shipping: {
-            address: "",
-            method: "standard" as "standard" | "express",
-            cost: 0,
-        },
-    },
-    ui: {
-        sidebarOpen: false,
-        activeProductId: null as string | null,
-        notifications: [] as {
-            id: string;
-            message: string;
-            type: "success" | "error";
-        }[],
-    },
-};
+// Remove an item at index
+updater.cart.items.cut(2);
 
-// Create state hook
-export const { useCogsState } = createCogsState(InitialState);
+// Find and update an item
+updater.cart.items.findWith("id", "prod1").quantity.update((prev) => prev + 1);
 
-// Use in component
-const [state, updater] = useCogsState("catalog");
+// Update item at specific index
+updater.cart.items.index(0).price.update(19.99);
 ```
 
-## Updater API
+### Advanced Array Methods
 
-### Basic Updates
+```typescript
+// Map with access to updaters
+updater.cart.items.stateMap((item, itemUpdater) => (
+  <CartItem
+    key={item.id}
+    item={item}
+    onQuantityChange={qty => itemUpdater.quantity.update(qty)}
+  />
+));
+
+// Filter items while maintaining updater capabilities
+const inStockItems = updater.products.stateFilter(product => product.stock > 0);
+
+// Insert only if the item doesn't exist
+updater.cart.items.uniqueInsert(
+  { id: "prod1", quantity: 1 },
+  ["id"] // fields to check for uniqueness
+);
 
-#### `.update()`
+// Flatten nested arrays by property
+const allVariants = updater.products.stateFlattenOn("variants");
+```
 
-Updates state value directly.
+## Reactivity Control
 
-```typescript
-// Direct update
-updater.catalog.filters.search.update("blue shoes");
+Cogsbox offers different ways to control when components re-render:
 
-// Functional update
-updater.cart.items[0].quantity.update((prev) => prev + 1);
+### Component Reactivity (Default)
 
-// Deep update
-updater.catalog.products
-    .findWith("id", "123")
-    .variants[0].stock.update((prev) => prev - 1);
+Re-renders when any accessed value changes.
+
+```typescript
+// Default behavior - re-renders when cart.items or cart.total changes
+const cart = useCogsState("cart");
+
+return (
+  <div>
+    <div>Items: {cart.items.get().length}</div>
+    <div>Total: {cart.total.get()}</div>
+  </div>
+);
 ```
 
-#### `.get()`
+### Dependency-Based Reactivity
 
-Gets current state value.
+Re-renders only when specified dependencies change.
 
 ```typescript
-const searchTerm = updater.catalog.filters.search.get();
-const cartTotal = updater.cart.items
-    .get()
-    .reduce((sum, item) => sum + item.quantity, 0);
+// Only re-renders when items array or status changes
+const cart = useCogsState("cart", {
+  reactiveType: ["deps"],
+  reactiveDeps: (state) => [state.items, state.status],
+});
 ```
 
-### Array Operations
-
-#### `.insert()`
+### Full Reactivity
 
-Inserts an item into an array.
+Re-renders on any state change, even for unused properties.
 
 ```typescript
-// Add product
-updater.catalog.products.insert({
-    id: "123",
-    name: "Running Shoes",
-    price: 99.99,
-    categories: ["shoes", "sports"],
-    variants: [],
+// Re-renders on any change to cart state
+const cart = useCogsState("cart", {
+  reactiveType: ["all"],
 });
-
-// Add to cart
-updater.cart.items.insert((prev) => ({
-    productId: "123",
-    variantId: "v1",
-    quantity: 1,
-}));
 ```
 
-#### `.uniqueInsert()`
+### Signal-Based Reactivity
 
-Inserts only if item doesn't exist (checks deep equality).
+Updates only the DOM elements that depend on changed values.
 
 ```typescript
-// Add category if not exists
-updater.catalog.categories.uniqueInsert("sports");
-
-// Add notification with unique ID
-updater.ui.notifications.uniqueInsert(
-    {
-        id: generateId(),
-        message: "Item added to cart",
-        type: "success",
-    },
-    ["id"],
+// Most efficient - updates just the specific DOM elements
+return (
+  <div>
+    <div>Items: {cart.items.$derive(items => items.length)}</div>
+    <div>Total: {cart.total.$get()}</div>
+  </div>
 );
 ```
 
-#### `.cut()`
+## Form Integration
 
-Removes an item from an array.
+Cogsbox State provides an intuitive form system to connect your state to form controls with built-in validation, error handling, and array support.
 
-```typescript
-// Remove from cart
-updater.cart.items.cut(index);
+### Basic Form Element Usage
 
-// Remove notification
-updater.ui.notifications.findWith("id", "notif-123").cut();
-```
-
-#### `.findWith()`
-
-Finds an item in array by property comparison.
+The `formElement` method serves as the bridge between state and UI:
 
 ```typescript
-// Find and update product
-updater.catalog.products.findWith("id", 123).price.update(99.99);
-
-// Find and update cart item
-updater.cart.items
-    .findWith("productId", 123)
-    .quantity.update((prev) => prev + 1);
+// Direct value/onChange pattern for complete control
+user.firstName.formElement((params) => (
+  <div>
+    <label className="block text-sm font-medium">First Name</label>
+    <input
+      type="text"
+      className="mt-1 block w-full rounded-md border-2 p-2"
+      value={params.get()}
+      onChange={(e) => params.set(e.target.value)}
+      onBlur={params.inputProps.onBlur}
+      ref={params.inputProps.ref}
+    />
+  </div>
+));
+
+// Using inputProps shorthand for simpler binding
+user.lastName.formElement((params) => (
+  <div>
+    <label className="block text-sm font-medium">Last Name</label>
+    <input
+      type="text"
+      className="mt-1 block w-full rounded-md border-2 p-2"
+      {...params.inputProps}
+    />
+  </div>
+));
 ```
 
-#### `.index()`
+### Form Validation Options
 
-Gets item at specific index with updater methods.
+Cogsbox provides several approaches to validation:
 
 ```typescript
-// Update first cart item
-updater.cart.items.index(0).quantity.update(2);
-```
-
-#### `.stateEach()`
+// Custom validation message
+user.email.formElement(
+  (params) => (
+    <div>
+      <label>Email Address</label>
+      <input {...params.inputProps} type="email" />
+    </div>
+  ),
+  {
+    validation: {
+      message: "Please enter a valid email address"
+    }
+  }
+);
 
-Maps over array with access to item updater.
+// Hidden validation (show border but no message)
+user.lastName.formElement(
+  (params) => (
+    <div>
+      <label>Last Name</label>
+      <input
+        {...params.inputProps}
+        className={`input ${params.validationErrors().length > 0 ? 'border-red-500' : ''}`}
+      />
+    </div>
+  ),
+  {
+    validation: {
+      hideMessage: true
+    }
+  }
+);
 
-```typescript
-// Apply discount to all products
-updater.catalog.products.stateEach((product, productUpdater) => {
-    productUpdater.price.update((price) => price * 0.9);
-});
+// Custom validation with onBlur
+user.phone.formElement((params) => (
+  <div>
+    <label>Phone Number</label>
+    <input
+      {...params.inputProps}
+      onBlur={(e) => {
+        if (e.target.value.length == 0 || isNaN(Number(e.target.value))) {
+          params.addValidationError("Please enter a valid phone number");
+        }
+      }}
+      placeholder="(555) 123-4567"
+    />
+  </div>
+));
 ```
 
-#### `.stateFilter()`
+### Working with Form Arrays
 
-Creates filtered view of array with updater methods.
+For managing collections like addresses:
 
 ```typescript
-// Get low stock variants
-const lowStock = updater.catalog.products.stateFilter((product) =>
-    product.variants.some((v) => v.stock < 5),
-);
+function AddressesManager() {
+  const [currentAddressIndex, setCurrentAddressIndex] = useState(0);
+  const user = useCogsState("user");
+
+  // Add new address
+  const addNewAddress = () => {
+    user.addresses.insert({
+      street: "",
+      city: "",
+      state: "",
+      zipCode: "",
+      country: "USA",
+      isDefault: false,
+    });
+    setCurrentAddressIndex(user.addresses.get().length - 1);
+  };
 
-// Update prices for filtered products
-lowStock.stateEach((product, productUpdater) => {
-    productUpdater.price.update((price) => price * 0.8);
-});
+  return (
+    <div>
+      {/* Address tabs with validation indicators */}
+      <div className="flex space-x-2 mt-2">
+        {user.addresses.stateMap((_, setter, index) => {
+          const errorCount = setter.showValidationErrors().length;
+          return (
+            <button
+              key={index}
+              onClick={() => setCurrentAddressIndex(index)}
+              className={`rounded-lg flex items-center justify-center ${
+                errorCount > 0
+                  ? "border-red-500 bg-red-400"
+                  : currentAddressIndex === index
+                  ? "bg-blue-500 text-white"
+                  : "bg-gray-200"
+              }`}
+            >
+              {index + 1}
+              {errorCount > 0 && (
+                <div className="bg-red-500 text-white rounded-full">
+                  {errorCount}
+                </div>
+              )}
+            </button>
+          );
+        })}
+        <button onClick={addNewAddress}>Add</button>
+      </div>
+
+      {/* Current address form */}
+      {user.addresses.get().length > 0 && (
+        <div className="grid grid-cols-1 gap-4">
+          {/* Access fields with index() method */}
+          {user.addresses.index(currentAddressIndex).street.formElement(
+            (params) => (
+              <div>
+                <label>Street</label>
+                <input value={params.get()} onChange={(e) => params.set(e.target.value)} />
+              </div>
+            ),
+            {
+              validation: {
+                message: "Street address is required"
+              }
+            }
+          )}
+
+          {/* City and State in a row */}
+          <div className="grid grid-cols-2 gap-4">
+            {user.addresses.index(currentAddressIndex).city.formElement((params) => (
+              <div>
+                <label>City</label>
+                <input {...params.inputProps} />
+              </div>
+            ))}
+
+            {user.addresses.index(currentAddressIndex).state.formElement((params) => (
+              <div>
+                <label>State</label>
+                <input {...params.inputProps} />
+              </div>
+            ))}
+          </div>
+
+          {/* Boolean field handling */}
+          {user.addresses.index(currentAddressIndex).isDefault.formElement((params) => (
+            <div className="flex items-center">
+              <input
+                type="checkbox"
+                checked={params.get()}
+                onChange={(e) => params.set(e.target.checked)}
+                id={`default-address-${currentAddressIndex}`}
+              />
+              <label htmlFor={`default-address-${currentAddressIndex}`}>
+                Set as default address
+              </label>
+            </div>
+          ))}
+
+          {/* Remove address button */}
+          {user.addresses.get().length > 1 && (
+            <button
+              onClick={() => {
+                user.addresses.cut(currentAddressIndex);
+                setCurrentAddressIndex(Math.max(0, currentAddressIndex - 1));
+              }}
+            >
+              Remove Selected Address
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
 ```
 
-#### `.stateFlattenOn()`
+### Form Actions
 
-Flattens nested arrays by property.
+Cogsbox provides methods to manage form state:
 
 ```typescript
-// Get all variants across products
-const allVariants = updater.catalog.products.stateFlattenOn("variants");
-```
-
-### Form Integration
+// Reset form to initial state
+const handleReset = () => {
+  user.revertToInitialState();
+};
 
-#### `.formElement()`
+// Validate all fields using Zod schema
+const handleSubmit = () => {
+  if (user.validateZodSchema()) {
+    // All valid, proceed with submission
+    submitData(user.get());
+  }
+};
+```
 
-Creates form control with validation.
+### Setting Up Zod Validation
 
 ```typescript
-updater.cart.shipping.address.formElement("shipping", ({ inputProps }) => (
-  <input {...inputProps} placeholder="Shipping address" />
-), {
-  validation: {
-    message: "Address is required",
-    onChange: { clear: ["shipping.address"] }
+// Setting up validation at initialization
+export const { useCogsState } = createCogsState({
+  user: {
+    initialState: {
+      firstName: "",
+      lastName: "",
+      email: "",
+      phone: "",
+      addresses: [
+        {
+          street: "",
+          city: "",
+          state: "",
+          zipCode: "",
+          country: "USA",
+          isDefault: false,
+        },
+      ],
+    },
+    validation: {
+      key: "userForm", // Used for error tracking
+      zodSchema: z.object({
+        firstName: z.string().min(1, "First name is required"),
+        lastName: z.string().min(1, "Last name is required"),
+        email: z.string().email("Please enter a valid email"),
+        phone: z.string().min(10, "Phone number must be at least 10 digits"),
+        addresses: z.array(
+          z.object({
+            street: z.string().min(1, "Street is required"),
+            city: z.string().min(1, "City is required"),
+            state: z.string().min(1, "State is required"),
+            zipCode: z
+              .string()
+              .min(5, "Zip code must be at least 5 characters"),
+            country: z.string(),
+            isDefault: z.boolean(),
+          })
+        ),
+      }),
+    },
   },
-  debounceTime: 300
-})
+});
 ```
 
-### Menu & Selection API
-
-#### `.setSelected()`
-
-Marks an item as selected in a list.
+## Server Synchronization
 
 ```typescript
-// Select product
-updater.catalog.products[0].setSelected(true);
+// Setting up server sync
+const products = useCogsState("products", {
+  serverSync: {
+    syncKey: "products",
+    syncFunction: ({ state }) => api.updateProducts(state),
+    debounce: 1000, // ms
+    mutation: useMutation(api.updateProducts),
+  },
+});
 
-// Select category
-updater.catalog.categories.findWith("name", "sports").setSelected(true);
+// State is automatically synced with server after changes
+products.items[0].stock.update((prev) => prev - 1);
 ```
 
-#### `.getSelected()`
-
-Gets currently selected item from a list.
+## Local Storage Persistence
 
 ```typescript
-const selectedProduct = updater.catalog.products.getSelected();
+// Automatically save state to localStorage
+const cart = useCogsState("cart", {
+  localStorage: {
+    key: "shopping-cart",
+  },
+});
 ```
 
-[Rest of documentation remains the same...]
-
-## Examples
-
-### Product Catalog Management
+## Example: Shopping Cart
 
 ```typescript
-function ProductList() {
-  const [state, updater] = useCogsState("catalog", {
-    serverSync: {
-      syncKey: "products",
-      syncFunction: async ({ state }) => {
-        await api.updateProducts(state.products)
-      }
-    }
-  });
-
-  const filteredProducts = updater.products
-    .stateFilter(product =>
-      product.price >= state.filters.priceRange.min &&
-      product.price <= state.filters.priceRange.max &&
-      (state.filters.selectedCategories.length === 0 ||
-        product.categories.some(c => state.filters.selectedCategories.includes(c)))
+function ShoppingCart() {
+  const cart = useCogsState("cart");
+  const products = useCogsState("products");
+
+  const addToCart = (productId) => {
+    const product = products.items.findWith("id", productId).get();
+
+    cart.items.uniqueInsert(
+      {
+        productId,
+        name: product.name,
+        price: product.price,
+        quantity: 1
+      },
+      ["productId"],
+      // If product exists, update quantity instead
+      (existingItem) => ({
+        ...existingItem,
+        quantity: existingItem.quantity + 1
+      })
     );
 
+    // Update total
+    cart.total.update(prev => prev + product.price);
+  };
+
   return (
     <div>
-      {filteredProducts.stateEach((product, productUpdater) => (
-        <ProductCard
-          key={product.id}
-          product={product}
-          onUpdateStock={(variantId, newStock) =>
-            productUpdater
-              .variants
-              .findWith("id", variantId)
-              .stock
-              .update(newStock)
-          }
-        />
-      ))}
-    </div>
-  );
-}
-```
+      <h2>Your Cart</h2>
 
-### Shopping Cart Management
+      {cart.items.stateMap((item, itemUpdater) => (
+        <div key={item.productId} className="cart-item">
+          <div>{item.name}</div>
+          <div>${item.price}</div>
 
-```typescript
-function CartManager() {
-  const [state, updater] = useCogsState("cart", {
-    localStorage: {
-      key: "shopping-cart"
-    }
-  });
-
-  const addToCart = (product: Product, variantId: string) => {
-    updater.items.uniqueInsert({
-      productId: product.id,
-      variantId,
-      quantity: 1
-    }, ['productId', 'variantId']);
-  };
+          <div className="quantity">
+            <button onClick={() =>
+              itemUpdater.quantity.update(prev => Math.max(prev - 1, 0))
+            }>-</button>
 
-  return (
-    <div>
-      {updater.items.stateEach((item, itemUpdater) => (
-        <CartItem
-          key={item.productId}
-          item={item}
-          onUpdateQuantity={qty => itemUpdater.quantity.update(qty)}
-          onRemove={() => itemUpdater.cut()}
-        />
+            <span>{item.quantity}</span>
+
+            <button onClick={() =>
+              itemUpdater.quantity.update(prev => prev + 1)
+            }>+</button>
+          </div>
+
+          <button onClick={() => itemUpdater.cut()}>Remove</button>
+        </div>
       ))}
+
+      <div className="cart-total">
+        <strong>Total:</strong> ${cart.total.get()}
+      </div>
     </div>
   );
 }
 ```
 
-[Rest of TypeScript section remains the same...]
+## Common Patterns and Tips
+
+1. **Path-based Updates**: Always use the fluent API to update nested properties.
+
+   ```typescript
+   // Good
+   updater.users[0].address.city.update("New York");
+
+   // Avoid
+   updater.update({ ...state, users: [...] });
+   ```
+
+2. **Working with Arrays**: Use the built-in array methods instead of manually updating array state.
+
+   ```typescript
+   // Good
+   updater.users.insert(newUser);
+   updater.users.findWith("id", 123).active.update(true);
+
+   // Avoid
+   updater.users.update([...users, newUser]);
+   ```
+
+3. **Optimization**: Use the appropriate reactivity type for your needs.
+
+   ```typescript
+   // For lists where only specific items change frequently
+   updater.items.stateMap((item) => (
+     <div>{item.$get()}</div>  // Only this item re-renders when changed
+   ));
+   ```
+
+4. **Form Management**: Use formElement for all form inputs to get automatic validation and debouncing.
+   ```typescript
+   profile.name.formElement(
+     ({ inputProps }) => <input {...inputProps} />,
+     { debounceTime: 300 }
+   );
+   ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogsbox-state",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "React state management library with form controls and server sync",
   "type": "module",
   "main": "./dist/index.js",