plug-code 1.1.13 → 1.1.14

package/README.md

@@ -1,14 +1,12 @@
-# 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 are welcome to use Plug&Code in your personal or commercial projects. Modification or redistribution of the framework source code is prohibited without explicit permission.
 
 ---
 
-### Installation
+## 📦 Installation
 
 Install the framework via npm or yarn:
 
@@ -16,101 +14,158 @@ Install the framework via npm or yarn:
 npm install plug-code
 # or
 yarn add plug-code
+🧠 Core Concepts
+Plug&Code is built around the PLC (Pipeline-Logic-Command) pattern combined with a specialized Reactive State Machine:
 
-```
+Features: Independent functions that encapsulate Logic, UI, and Data. No more monolithic configurations.
 
-### Core Concepts
+Stores (State): Isolated state containers (substores) that can be linked reactively.
 
-Plug&Code is built around the **PLC (Pipeline-Logic-Command)** pattern:
+Slots (UI Pipeline): Inject components into pre-defined locations from any feature.
 
-* **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.
+Commands (Logic): Execute and wrap business actions (e.g., checkout, print) with middleware support.
 
----
+Transforms (Data): Pass data through named channels to be modified by different features before rendering.
+
+🚀 Quick Start Guide
+1. Create a Feature Module
+Define features in separate files. A feature is simply a function that receives the api.
+
+TypeScript
+
+// features/PaginationFeature.ts
+import type { PlcAPI } from 'plug-code';
+
+export const PaginationFeature = (api: PlcAPI<any>) => {
+    // 1. Initialize State
+    api.createData("pagination", { currentPage: 1, pageSize: 10, total: 0 });
+
+    // 2. Reactive Linking (Derive)
+    // Automatically update 'root.activePage' when 'pagination' changes
+    api.derive("activePage", ["pagination"], () => api.getData("pagination"));
 
-### Quick Start Guide
+    // 3. Register UI Component
+    // The 3rd argument ("pagination") subscribes this component to the store.
+    api.register("table-footer", (pageData) => {
+        const { currentPage } = pageData;
+        
+        // Use the extended update to modify data
+        const goNext = () => api.update(
+            "pagination",            // Store to update
+            d => { d.currentPage++ } // Updater (Immer draft)
+        );
 
-#### 1. Initialize your System
+        return <button onClick={goNext}>Page {currentPage}</button>;
+    }, "pagination");
+};
+2. Initialize your System
+Import your feature functions and inject them into the system.
 
-Define your system and register features using the fluent API.
+TypeScript
 
-```tsx
+// 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;
-    });
-  });
-});
+    // Initialize global root data
+    api.createData("root", { appName: "My Dashboard", theme: "dark" });
 
-```
+    // Install Features
+    PaginationFeature(api);
+    SalesFeature(api);
+});
+3. Wrap your Application
+Use the hooks to provide context and render slots.
 
-#### 2. Wrap your Application
+TypeScript
 
-Use the `useSystemPlc` hook to manage the state and `SystemPlcRoot` to provide the context.
+// App.tsx
+import { useSystemPlc, SystemPlcRoot } from './system';
 
-```tsx
 function App() {
-  // Initialize state with initial properties
-  const { api, useSelector } = useSystemPlc({ shopName: "My Store" });
+  // Initialize system with props (synced to "root" store automatically)
+  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>
+        
+        {/* Render slots: The pipeline assembles all registered components */}
+        <div className="footer-area">
+            {api.render("table-footer")}
+        </div>
       </main>
     </SystemPlcRoot>
   );
 }
+📚 API Reference
+State Management & Reactivity
+The framework uses an isolated store architecture with reactive capabilities using Immer.
 
-```
+api.createData(key, initialData)
+Initializes a new substore.
 
----
+key: Unique identifier (e.g., "pagination").
+
+initialData: The starting object.
+
+api.getData(key)
+Imperatively retrieves the current snapshot of a store.
+
+api.update(key, updater, [slot], [triggerKey])
+Updates the state using Immer-powered drafts.
+
+key: The store to update.
+
+updater: (draft) => void. Mutate the draft directly.
+
+slot (Optional): Name of the UI slot to invalidate (clears visual cache).
+
+triggerKey (Optional): Name of another store to force-update (useful for manual dependency triggering without derive).
+
+api.derive(targetKey, dependencies, calculator)
+Creates a reactive link. When dependencies change, the target is recalculated automatically.
+
+targetKey: Where to save the result.
+
+dependencies: Array of store keys to listen to.
+
+api.watch(key, selector, callback)
+Listens for changes to perform side effects (logging, analytics, etc.).
+
+UI Management (Slots)
+api.register(slotName, componentFn, [dependencyKey])
+Adds a component to a pipeline.
+
+slotName: Where to inject the component.
+
+componentFn: Function receiving data and returning JSX.
+
+dependencyKey: The store key this component subscribes to. It triggers a re-render only when that specific store changes.
+
+api.render(slotName, [props])
+Renders the pipeline for the given slot name.
 
-### API Reference
+Business Logic (Commands)
+api.registerCommand(id, fn): Registers an executable action.
 
-#### **UI Management (Slots)**
+api.execute(id, payload): Runs a command and returns a Promise.
 
-* `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.
+api.wrapCommand(id, middlewareFn): Intercepts a command to add logic before/after execution.
 
-#### **Business Logic (Commands)**
+Data Processing (Transforms)
+api.send(channel, id, fn, priority): Adds a transformation step to a data pipeline.
 
-* `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.
+api.receive(channel, initialData): Pipes data through all transformers in the channel.
 
-#### **Data Processing (Transforms)**
+🌟 Best Practices
+Independent Files: Keep each feature in its own file (e.g., AuthFeature.ts, TableFeature.ts).
 
-* `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.
+Use Derive: Prefer api.derive over manual updates to sync data between stores.
 
-#### **State Management**
+Scope Dependencies: Always pass the dependencyKey (3rd arg) in api.register to ensure optimal performance.
 
-* `useSelector(selector)`: Reactively listen to state changes.
-* `api.update(key, updater)`: Update store data using Immer-powered drafts.
+Avoid "Root" Spam: Create specific stores ("filters", "auth", "cart") instead of putting everything in "root". This prevents unnecessary re-renders.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plug-code",
-  "version": "1.1.13",
+  "version": "1.1.14",
   "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;