mates 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,356 @@
+# 🧪 Mates
+
+**Mates** is a lightweight, reactive state management framework for web applications that makes managing state a breeze! Think React hooks, but for any framework (or no framework at all)!
+
+## 🚀 Features
+
+- 🔄 **Reactive State**: Automatic UI updates when state changes
+- 🧩 **Composable**: Mix and match different state types
+- 🔍 **Transparent**: See exactly how data flows through your app
+- 🏎️ **Fast**: Minimal re-renders, optimized updates
+- 🪶 **Lightweight**: Tiny footprint, big capabilities
+- 🔌 **Framework-Agnostic**: Works with any framework or vanilla JS/TS
+
+## 📦 Installation
+
+```bash
+npm install mates
+# or
+yarn add mates
+```
+
+## 🧠 Core Concepts
+
+Mates offers several types of state management tools that work together seamlessly as part of the framework:
+
+### 🔍 Views: Building Reactive UIs
+
+Views are the building blocks of your UI. They're functions that return HTML templates and automatically subscribe to state changes.
+
+```typescript
+import { view, atom } from "mates";
+import { html } from "lit-html";
+
+// Create a view that uses this state
+const CounterView = (props) => {
+  let count = 0;
+  const incr = setter(() => count++);
+  return () => {
+    // This function renders the template
+    return html`
+      <div>
+        <h1>Count: ${count}</h1>
+        <button @click=${incr}>Increment</button>
+      </div>
+    `;
+  };
+};
+
+// Render the view in your app in an element
+// second param should be id of the element
+renderView(CounterView, "app");
+```
+
+### ⚛️ Atoms: Simple Reactive State
+
+Atoms are the simplest form of state. They store a single value that can be read and updated.
+
+```typescript
+import { atom } from "mates";
+
+// Create an atom with initial value
+const username = atom("guest");
+
+// Read the value
+console.log(username()); // "guest"
+
+// Update the value
+username.set("alice");
+
+// Use setter function
+username.set((prev) => prev.toUpperCase());
+
+// you can also update the values in an object or array using .update()
+
+const address = atom({ street: "" });
+address.update((s) => (s.street = "newstreet"));
+```
+
+### Counter app using atoms
+
+```typescript
+
+```
+
+### 🧪 Units: Object-Based State
+
+Units are perfect for managing object-based state with methods.
+
+```typescript
+import { unit } from "mates";
+
+// Create a unit
+const todoList = unit({
+  items: [],
+
+  // Methods with _ prefix automatically trigger updates
+  _addItem(text) {
+    this.items.push({ text, completed: false });
+  },
+
+  _toggleItem(index) {
+    this.items[index].completed = !this.items[index].completed;
+  },
+
+  // Computed property (cached and recalculated when dependencies change)
+  get completedCount() {
+    return this.items.filter((item) => item.completed).length;
+  },
+
+  async loadData() {
+    const data = await fetchData();
+    this._addItem(data); // updates items
+  },
+});
+
+// Use the unit
+todoList().items; // []
+todoList()._addItem("Learn Mates");
+```
+
+### 🫧 Bubbles: Encapsulated Logic
+
+Bubbles help you encapsulate complex state logic into a reusable entity.
+
+```typescript
+import { bubble } from "mates";
+
+const counterBubble = bubble((setter) => {
+  let count = 0;
+
+  // Create functions that update state with setter
+  const increment = setter(() => count++);
+  const decrement = setter(() => count--);
+  const reset = setter(() => (count = 0));
+
+  // Return a function that returns the state object
+  return () => ({
+    count,
+    increment,
+    decrement,
+    reset,
+  });
+});
+
+// Use the bubble
+const { count, increment } = counterBubble();
+console.log(count); // 0
+increment();
+console.log(counterBubble().count); // 1
+```
+
+### 📊 Getters: Computed Values
+
+Getters create computed values that only recalculate when their dependencies change.
+
+```typescript
+import { atom, getter } from "mates";
+
+const firstName = atom("John");
+const lastName = atom("Doe");
+
+const fullName = getter(() => {
+  return `${firstName()} ${lastName()}`;
+});
+
+console.log(fullName()); // "John Doe"
+
+// Only recalculates when dependencies change
+firstName.set("Jane");
+console.log(fullName()); // "Jane Doe"
+```
+
+### 🧬 Molecules: Organizing State
+
+Molecules help you organize your state into classes for better structure.
+
+```typescript
+import { molecule, atom } from "mates";
+
+class UserStore {
+  name = atom("Guest");
+  isLoggedIn = atom(false);
+
+  login(username) {
+    this.name.set(username);
+    this.isLoggedIn.set(true);
+  }
+
+  logout() {
+    this.name.set("Guest");
+    this.isLoggedIn.set(false);
+  }
+}
+
+// Create a molecule from the class
+const userStore = molecule(UserStore);
+
+// Use the molecule
+console.log(userStore().name()); // "Guest"
+userStore().login("Alice");
+console.log(userStore().isLoggedIn()); // true
+```
+
+### 🔄 XProvider: Context Management
+
+XProvider allows you to provide and consume context across your application.
+
+```typescript
+import { html } from "lit-html";
+import { view, useContext } from "mates";
+
+// Create a context class
+class ThemeContext {
+  theme = "light";
+
+  toggleTheme() {
+    this.theme = this.theme === "light" ? "dark" : "light";
+  }
+}
+
+// Provider component
+const ThemeProvider = view(
+  (props) => {
+    const themeContext = new ThemeContext();
+
+    return () => html`
+      <x-provider .value=${themeContext}> ${props().children} </x-provider>
+    `;
+  },
+  { children: [] }
+);
+
+// Consumer component
+const ThemedButton = view(() => {
+  // Get context instance
+  const theme = useContext(ThemeContext);
+
+  return () => html`
+    <button class="${theme.theme}-theme" @click=${() => theme.toggleTheme()}>
+      Toggle Theme (Current: ${theme.theme})
+    </button>
+  `;
+}, {});
+```
+
+## 🎮 Complete Example
+
+Here's a complete todo list example that showcases Mates' features:
+
+```typescript
+import { html } from "lit-html";
+import { view, bubble, atom } from "mates";
+
+// Create state with a bubble
+const todos = bubble((setter) => {
+  let items = [];
+  let newTodoText = "";
+
+  const setNewTodoText = setter((text) => {
+    newTodoText = text;
+  });
+
+  const addTodo = setter(() => {
+    if (newTodoText.trim()) {
+      items.push({ text: newTodoText, completed: false });
+      newTodoText = "";
+    }
+  });
+
+  const toggleTodo = setter((index) => {
+    items[index].completed = !items[index].completed;
+  });
+
+  const deleteTodo = setter((index) => {
+    items.splice(index, 1);
+  });
+
+  return () => ({
+    items,
+    newTodoText,
+    setNewTodoText,
+    addTodo,
+    toggleTodo,
+    deleteTodo,
+  });
+});
+
+// Create a view for the todo app
+const TodoApp = view(() => {
+  return () => {
+    const {
+      items,
+      newTodoText,
+      setNewTodoText,
+      addTodo,
+      toggleTodo,
+      deleteTodo,
+    } = todos();
+
+    return html`
+      <div class="todo-app">
+        <h1>Todo List</h1>
+        <div class="add-todo">
+          <input
+            value=${newTodoText}
+            @input=${(e) => setNewTodoText(e.target.value)}
+            @keypress=${(e) => e.key === "Enter" && addTodo()}
+            placeholder="Add new todo"
+          />
+          <button @click=${addTodo}>Add</button>
+        </div>
+
+        <ul class="todo-list">
+          ${items.map(
+            (item, index) => html`
+              <li class=${item.completed ? "completed" : ""}>
+                <input
+                  type="checkbox"
+                  .checked=${item.completed}
+                  @change=${() => toggleTodo(index)}
+                />
+                <span>${item.text}</span>
+                <button @click=${() => deleteTodo(index)}>Delete</button>
+              </li>
+            `
+          )}
+        </ul>
+
+        <div class="todo-stats">
+          <p>${items.filter((item) => !item.completed).length} items left</p>
+        </div>
+      </div>
+    `;
+  };
+}, {});
+
+// Mount the app
+document.body.appendChild(TodoApp);
+```
+
+## 🔄 Why Mates?
+
+Mates gives you the power and simplicity of React hooks without the React! As a complete framework, it's perfect for:
+
+- Building lightweight web apps without other heavy frameworks
+- Adding reactivity to existing applications
+- Creating reusable, reactive components
+- Prototyping ideas quickly
+
+## 📚 Learn More
+
+Check out our [examples](https://github.com/yourusername/mates/tree/main/examples) to see more usage patterns and advanced framework features.
+
+## 📄 License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mates",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "description": "Mates is a front end framework for building web applications",
   "main": "dist/index.js",