plug-code 1.1.0 → 1.1.2

package/README.md

@@ -1,16 +1,116 @@
 # Plug&Code
 
-Plug&Code is a multipurpose framework for React, designed for **scalability, reusability, and organized components**.
+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.
 
 ## 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.  
+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.
+
+---
 
 ### Installation
 
-You can install the framework via npm or yarn:
+Install the framework via npm or yarn:
 
 ```bash
 npm install plug-code
 # or
 yarn add plug-code
+
+```
+
+### Core Concepts
+
+Plug&Code is built around the **PLC (Pipeline-Logic-Command)** pattern:
+
+* **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.
+
+---
+
+### Quick Start Guide
+
+#### 1. Initialize your System
+
+Define your system and register features using the fluent API.
+
+```tsx
+import { createPlugAndCode } from 'plug-code';
+
+export const { useSystemPlc, SystemPlcRoot } = createPlugAndCode((api) => {
+  
+  // Define a Sales Feature
+  api.feature("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.feature("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;
+    });
+  });
+});
+
+```
+
+#### 2. Wrap your Application
+
+Use the `useSystemPlc` hook to manage the state and `SystemPlcRoot` to provide the context.
+
+```tsx
+function App() {
+  // Initialize state with initial properties
+  const { api, useSelector } = useSystemPlc({ shopName: "My Store" });
+
+  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>
+      </main>
+    </SystemPlcRoot>
+  );
+}
+
+```
+
+---
+
+### API Reference
+
+#### **UI Management (Slots)**
+
+* `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.
+
+#### **Business Logic (Commands)**
+
+* `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.
+
+#### **Data Processing (Transforms)**
+
+* `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.
+
+#### **State Management**
+
+* `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.0",
+  "version": "1.1.2",
   "description": "",
   "main": "src/plug-code.tsx",
   "types": "types/plug-code.d.ts",

package/src/core/plcAPI.tsx

@@ -37,7 +37,7 @@ export class PlcAPI<S extends ObjectType> {
 
     createFeature(name: string, setupFn: (api: PlcAPI<S>) => void): PlcAPI<S> {
         if (this.installedFeatures.has(name)) {
-            console.warn(`[PlcFramework] La feature '${name}' ya fue registrada. Se omitirá para evitar conflictos.`);
+            console.warn(`[PlcFramework] Feature '${name}' is already registered. It will be skipped to avoid conflicts.`);
             return this;
         }
 
@@ -45,7 +45,7 @@ export class PlcAPI<S extends ObjectType> {
             setupFn(this);
             this.installedFeatures.add(name);
         } catch (error) {
-            console.error(`[PlcFramework] 💥 Error crítico inicializando la feature '${name}':`, error);
+            console.error(`[PlcFramework] 💥 Critical error initializing feature '${name}':`, error);
         }
 
         return this;
@@ -187,7 +187,7 @@ export class PlcAPI<S extends ObjectType> {
             try {
                 currentData = transformer.fn(currentData, context);
             } catch (error) {
-                console.error(`[PlcAPI] Error en transform '${channel as string}/${transformer.id}':`, error);
+                console.error(`[PlcAPI] Error in transform '${channel as string}/${transformer.id}':`, error);
             }
         }
 
@@ -199,7 +199,7 @@ export class PlcAPI<S extends ObjectType> {
         fn: CommandFn<CommandPayload<K>, CommandResult<K>>
     ) {
         if (this.commands.has(id as string)) {
-            console.warn(`[PlcAPI] Sobrescribiendo comando '${id as string}'`);
+            console.warn(`[PlcAPI] Overwriting command '${id as string}'`);
         }
         this.commands.set(id as string, fn as any);
     }
@@ -210,7 +210,7 @@ export class PlcAPI<S extends ObjectType> {
     ) {
         const currentFn = this.commands.get(id as string);
         if (!currentFn) {
-            console.error(`[PlcAPI] No se puede envolver '${id as string}', comando no existe.`);
+            console.error(`[PlcAPI] Cannot wrap '${id as string}', command does not exist.`);
             return;
         }
         this.commands.set(id as string, wrapper(currentFn) as any);
@@ -222,13 +222,13 @@ export class PlcAPI<S extends ObjectType> {
     ): Promise<CommandResult<K>> {
         const fn = this.commands.get(id as string);
         if (!fn) {
-            throw new Error(`[PlcAPI] Comando '${id as string}' no encontrado.`);
+            throw new Error(`[PlcAPI] Command '${id as string}' not found.`);
         }
 
         try {
             return await fn(payload);
         } catch (error) {
-            console.error(`[PlcAPI] Error ejecutando '${id as string}':`, error);
+            console.error(`[PlcAPI] Error executing '${id as string}':`, error);
             throw error;
         }
     }