plug-code 1.1.13 → 1.1.15

package/README.md

@@ -1,116 +1,152 @@
-# Plug&Code
+# 🔌 Plug&Code
 
-Plug&Code is a multipurpose framework for React designed for **scalability, reusability, and modular organization**. It allows you to build complex applications by "plugging in" features without tightly coupling your codebase.
+**Plug&Code** is a multipurpose React framework designed for **scalability, reusability, and modular organization**.
+It empowers developers to build complex applications by **plugging in independent feature modules** without tightly coupling the codebase.
 
-## Usage
-
-You are welcome to use Plug&Code in your projects, **personal or commercial**, as long as you **do not modify or redistribute the framework** without explicit permission from the author.
+> **License**
+> You may use Plug&Code in personal or commercial projects.
+> **Modification or redistribution of the framework source code is prohibited** without explicit permission.
 
 ---
 
-### Installation
-
-Install the framework via npm or yarn:
+## 📦 Installation
 
 ```bash
 npm install plug-code
 # or
 yarn add plug-code
-
 ```
 
-### Core Concepts
+---
+
+## 🧠 Core Concepts
 
-Plug&Code is built around the **PLC (Pipeline-Logic-Command)** pattern:
+Plug&Code is built around the **PLC (Pipeline–Logic–Command)** pattern combined with a specialized **Reactive State Machine**.
 
-* **Slots (UI Pipeline):** Inject components into pre-defined locations from any feature.
-* **Commands (Logic):** Execute and wrap business actions (e.g., `checkout`, `print`, `save`).
-* **Transforms (Data):** Pass data through named channels to be modified by different features.
+| Concept                 | Description                                              |
+| ----------------------- | -------------------------------------------------------- |
+| **Features**            | Independent modules that encapsulate logic, UI, and data |
+| **Stores (State)**      | Isolated substores with reactive linking                 |
+| **Slots (UI Pipeline)** | Injection points for UI from any feature                 |
+| **Commands (Logic)**    | Executable business actions with middleware              |
+| **Transforms (Data)**   | Data pipelines modified by multiple features             |
 
 ---
 
-### Quick Start Guide
+## 🚀 Quick Start
 
-#### 1. Initialize your System
+### 1️⃣ Create a Feature Module
 
-Define your system and register features using the fluent API.
+```ts
+// features/PaginationFeature.ts
+import type { PlcAPI } from 'plug-code';
 
-```tsx
+export const PaginationFeature = (api: PlcAPI<any>) => {
+  api.createData("pagination", { currentPage: 1, pageSize: 10, total: 0 });
+
+  api.derive("activePage", ["pagination"], () => api.getData("pagination"));
+
+  api.register("table-footer", (pageData) => {
+    const { currentPage } = pageData;
+
+    const goNext = () => api.update("pagination", d => { d.currentPage++ });
+
+    return <button onClick={goNext}>Page {currentPage}</button>;
+  }, "pagination");
+};
+```
+
+---
+
+### 2️⃣ Initialize the System
+
+```ts
+// system.ts
 import { createPlugAndCode } from 'plug-code';
+import { PaginationFeature } from './features/PaginationFeature';
+import { SalesFeature } from './features/SalesFeature';
 
 export const { useSystemPlc, SystemPlcRoot } = createPlugAndCode((api) => {
-  
-  // Define a Sales Feature
-  api.createFuture("sales", (api) => {
-    // Register a UI component into a slot
-    api.register("header.cart", () => <CartIcon />);
-
-    // Register a business command
-    api.registerCommand("sales.checkout", async (items) => {
-      console.log("Saving items to database...", items);
-      return { success: true };
-    });
-  });
-
-  // Define a Logger Feature that wraps existing logic
-  api.createFuture("logger", (api) => {
-    api.wrapCommand("sales.checkout", (next) => async (items) => {
-      console.log("Checkout started...");
-      const result = await next(items);
-      console.log("Checkout finished:", result);
-      return result;
-    });
-  });
-});
+  api.createData("root", { appName: "My Dashboard", theme: "dark" });
 
+  PaginationFeature(api);
+  SalesFeature(api);
+});
 ```
 
-#### 2. Wrap your Application
+---
 
-Use the `useSystemPlc` hook to manage the state and `SystemPlcRoot` to provide the context.
+### 3️⃣ Wrap Your Application
 
 ```tsx
+// App.tsx
+import { useSystemPlc, SystemPlcRoot } from './system';
+
 function App() {
-  // Initialize state with initial properties
-  const { api, useSelector } = useSystemPlc({ shopName: "My Store" });
+  const { api, useSelector } = useSystemPlc({ mode: "production" });
 
   return (
     <SystemPlcRoot api={api}>
-      <nav>
-        {/* Render slots from any feature */}
-        {api.render("header.cart")}
-      </nav>
       <main>
-        <h1>Welcome to {useSelector(s => s.root.shopName)}</h1>
+        <h1>Welcome to {useSelector(s => s.root.appName)}</h1>
+        <div className="footer-area">
+          {api.render("table-footer")}
+        </div>
       </main>
     </SystemPlcRoot>
   );
 }
-
 ```
 
 ---
 
-### API Reference
+## 📚 API Reference
 
-#### **UI Management (Slots)**
+### 🧬 State & Reactivity
 
-* `api.register(slotName, component)`: Adds a UI component to a slot.
-* `api.render(slotName)`: Renders all components registered in that slot.
-* `api.wrap(slot, wrapper)`: Wraps a slot's content with higher-order components.
+| Method                                  | Description              |
+| --------------------------------------- | ------------------------ |
+| `createData(key, initial)`              | Create a new store       |
+| `getData(key)`                          | Get snapshot of store    |
+| `update(key, updater, slot?, trigger?)` | Mutate store using Immer |
+| `derive(target, deps, calc)`            | Create reactive linkage  |
+| `watch(key, selector, cb)`              | Listen to store changes  |
 
-#### **Business Logic (Commands)**
+---
+
+### 🎨 UI Slots
 
-* `api.registerCommand(id, fn)`: Registers an executable action.
-* `api.execute(id, payload)`: Runs a command and returns a Promise.
-* `api.wrapCommand(id, (next) => ...)`: Intercepts a command to add side-effects or validations.
+| Method                               | Description          |
+| ------------------------------------ | -------------------- |
+| `register(slot, component, depKey?)` | Attach UI to slot    |
+| `render(slot, props?)`               | Render slot pipeline |
+
+---
 
-#### **Data Processing (Transforms)**
+### 🧠 Business Logic (Commands)
+
+| Method                        | Description       |
+| ----------------------------- | ----------------- |
+| `registerCommand(id, fn)`     | Register action   |
+| `execute(id, payload)`        | Run command       |
+| `wrapCommand(id, middleware)` | Intercept command |
+
+---
+
+### 🔄 Data Transforms
+
+| Method                            | Description   |
+| --------------------------------- | ------------- |
+| `send(channel, id, fn, priority)` | Add transform |
+| `receive(channel, data)`          | Run pipeline  |
+
+---
 
-* `api.send(channel, id, fn, priority)`: Adds a data transformer to a specific channel.
-* `api.receive(channel, initialData)`: Pipes data through all transformers in the channel.
+## 🌟 Best Practices
 
-#### **State Management**
+* Keep **one feature per file**
+* Prefer `derive` over manual syncing
+* Always specify `dependencyKey` in `register`
+* Avoid putting everything in `root` — create focused stores
 
-* `useSelector(selector)`: Reactively listen to state changes.
-* `api.update(key, updater)`: Update store data using Immer-powered drafts.
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plug-code",
-  "version": "1.1.13",
+  "version": "1.1.15",
   "description": "",
   "main": "src/plug-code.tsx",
   "types": "types/plug-code.d.ts",

package/src/core/plcAPI.tsx

@@ -35,20 +35,33 @@ export class PlcAPI<S extends ObjectType> {
         this.pipeline = new PlcPipeline(store)
     }
 
-    createFeature(name: string, setupFn: (api: PlcAPI<S>) => void): PlcAPI<S> {
-        if (this.installedFeatures.has(name)) {
-            console.warn(`[PlcFramework] Feature '${name}' is already registered. It will be skipped to avoid conflicts.`);
-            return this;
-        }
+    watch<T>(
+        storeKey: string,
+        selector: (data: any) => T,
+        callback: (newValue: T, oldValue: T) => void
+    ): () => void {
+        let previousValue = selector(this.getData(storeKey));
+        const unsubscribe = this.store.subscribe(storeKey as any, () => {
+            const currentData = this.getData(storeKey);
+            const newValue = selector(currentData);
+
+            if (newValue !== previousValue) {
+                const old = previousValue;
+                previousValue = newValue;
+                callback(newValue, old);
+            }
+        });
 
-        try {
-            setupFn(this);
-            this.installedFeatures.add(name);
-        } catch (error) {
-            console.error(`[PlcFramework] 💥 Critical error initializing feature '${name}':`, error);
-        }
+        return unsubscribe;
+    }
 
-        return this;
+    override<K extends string>(key: K & "root", data: any, slot?: string) {
+        this.substores.set(key, data);
+        this.store.set(key as any, data);
+
+        if (slot) {
+            this.invalidate(slot);
+        }
     }
 
     replace<K extends string>(key: K & "root", data: Partial<any>, slot?: string) {
@@ -71,7 +84,19 @@ export class PlcAPI<S extends ObjectType> {
         let lastValue: any
         let isComputing = false
 
-        const runUpdate = () => {
+        let scheduled = false
+
+        const scheduleUpdate = () => {
+            if (scheduled) return
+            scheduled = true
+
+            queueMicrotask(() => {
+                scheduled = false
+                runCompute()
+            })
+        }
+
+        const runCompute = () => {
             if (isComputing) return
 
             isComputing = true
@@ -84,21 +109,19 @@ export class PlcAPI<S extends ObjectType> {
             }
         }
 
-        runUpdate()
+
+        runCompute()
 
         dependencies.forEach(dep => {
             this.store.subscribe(dep as any, () => {
                 if (isComputing) return
-                runUpdate()
+                scheduleUpdate()
             })
         })
 
         return () => lastValue
     }
 
-
-
-
     register(slot: SlotKey, node: () => React.ReactNode): void;
     register<K extends string>(slot: SlotKey, node: (data: any) => React.ReactNode, dependencyKey: K): void;
     register(slot: SlotKey, node: (data?: any) => React.ReactNode, dependencyKey?: string) {
@@ -294,7 +317,7 @@ export class PlcAPI<S extends ObjectType> {
         this.substores.set(key, initialState)
     }
 
-    update<K extends keyof S>(key: string & "root", updater: (draft: any) => void, slot?: string) {
+    update<K extends keyof S>(key: string & "root", updater: (draft: any) => void, slot?: string, triggerKey?: string) {
         const sub = this.substores.get(key)
         if (!sub) return
 
@@ -305,5 +328,16 @@ export class PlcAPI<S extends ObjectType> {
         if (slot) {
             this.invalidate(slot)
         }
+
+        if (triggerKey && triggerKey !== key) {
+
+            const triggerData = this.substores.get(triggerKey);
+
+            if (triggerData) {
+                const newTriggerRef = { ...triggerData };
+                this.substores.set(triggerKey, newTriggerRef);
+                this.store.set(triggerKey as any, newTriggerRef);
+            }
+        }
     }
 }

package/src/plug-code.tsx

@@ -39,7 +39,7 @@ export function createPlugAndCode<S extends ObjectType>(
         }, []);
 
         useEffect(() => {
-            api.replace("root", initialProps)
+            api.override("root", initialProps)
         }, [initialProps, api]);
 
         const useSelector = <Result,>(selector: (state: any) => Result): Result => {

package/types/plug-code.d.ts

@@ -52,8 +52,8 @@ export declare class PlcAPI<S extends ObjectType> {
      * @param name Identificador único para debugging y prevención de duplicados.
      * @param setupFn Función de configuración donde registras slots, comandos, etc.
      */
-    createFeature(name: string, setupFn: (api: PlcAPI<S>) => void): PlcAPI<S>;
-
+    watch<T>(storeKey: string, selector: (data: any) => T, callback: (newValue: T, oldValue: T) => void): () => void
+    override<K extends string>(key: K & "root", data: any, slot?: string): void
     // --- Gestión de UI (Slots & Rendering) ---
 
     register(slot: string, node: () => React.ReactNode): void;
@@ -79,7 +79,7 @@ export declare class PlcAPI<S extends ObjectType> {
     
     derive<K extends string>(outputKey: K, dependencies: string[], calculator: () => any): void
 
-    update(key: string | "root", updater: (draft: any) => void, slot?: string): void;
+    update(key: string | "root", updater: (draft: any) => void, slot?: string, triggerKey?: string): void;
 
     subscribe(listener: () => void): () => void;