plug-code 1.2.0 → 2.0.1

package/README.md

@@ -1,35 +1,77 @@
-# 🔌 Plug&Code
 
-**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.
+# 🔌 Plug&Code (v2)
 
-> **License**
-> This project is licensed under the Plug&Code License.
-> See the LICENSE file for details.
+[![NPM Version](https://img.shields.io/npm/v/plug-code?color=blue)](https://www.npmjs.com/package/plug-code)
+[![License](https://img.shields.io/npm/l/plug-code?color=green)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.9-blue)](https://www.typescriptlang.org/)
+
+**Plug&Code** is a **high-performance**, strongly-typed, **modular React framework**.  
+It’s designed for complex enterprise apps (Dashboards, CRMs, ERPs), decoupling **logic**, **UI**, and **data** via a **Feature-based architecture**.
+
+> **v2 Highlights:** Full TypeScript support (Generics & Registry Pattern), native virtualization, immutable state management with Immer, and lazy-loaded modules.
+
+---
+
+## 🚀 Key Features
+
+- 🛡️ **Strong Typing:** Autocomplete and type inference in **Stores**, **Commands**, and **Slots** via the Registry pattern.
+- 🧩 **Feature-First Architecture:** Organize code in portable `ModuleManifests` that encapsulate **state**, **logic**, and **UI**.
+- ⚡ **Native Performance:** Built-in virtual rendering (`markVirtual`) and priority management via **Scheduler**.
+- 🧠 **Reactive State Machine:** Global & module-level state with **Immer** and granular subscriptions.
+- 🎨 **UI Composition Pipeline:** Slots system with **multiple injections**, **priorities**, and **keepAlive** support.
 
 ---
 
 ## 📦 Installation
 
+<details>
+<summary>Click to expand</summary>
+
 ```bash
-npm install plug-code
+npm install plug-code immer
 # or
-yarn add plug-code
-```
+yarn add plug-code immer
+````
+
+</details>
 
 ---
 
-## 🧠 Core Concepts
+## 🛡️ The Type Contract (Registry)
+
+Plug&Code requires defining the **shape of your app** in a central registry file, enabling **IntelliSense** everywhere.
+
+<details>
+<summary>Example: types/registry.ts</summary>
 
-Plug&Code is built around the **PLC (Pipeline–Logic–Command)** pattern combined with a specialized **Reactive State Machine**.
+```ts
+export type User = { id: string; name: string };
+
+// 1. App State
+export interface RootStoreRegistry {
+  "users:list": User[];
+  "app:loading": boolean;
+}
+
+// 2. Commands (Payload -> Result)
+export interface CommandRegistry {
+  "users:add": { payload: User; result: void };
+  "users:delete": { payload: { id: string }; result: boolean };
+}
+
+// 3. UI Slots
+export interface SlotRegistry {
+  "main-layout": {};
+  "sidebar": { collapsed: boolean };
+}
+
+// 4. Feature State
+export interface FeatureRegistry {
+  "auth": { token: string | null };
+}
+```
 
-| 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             |
+</details>
 
 ---
 
@@ -37,115 +79,114 @@ Plug&Code is built around the **PLC (Pipeline–Logic–Command)** pattern combi
 
 ### 1️⃣ Create a Feature Module
 
-```ts
-// features/PaginationFeature.ts
-import type { PlcAPI } from 'plug-code';
-
-export const PaginationFeature = (api: PlcAPI<any>) => {
-  api.createData("pagination", { currentPage: 1, pageSize: 10, total: 0 });
+<details>
+<summary>Example: UsersFeature</summary>
 
-  api.derive("activePage", ["pagination"], () => api.getData("pagination"));
+```ts
+import { ModuleManifest } from 'plug-code';
+import { useCommand, useStore } from '../framework/plcHooks';
 
-  api.register("table-footer", (pageData) => {
-    const { currentPage } = pageData;
+const UserList = () => {
+  const users = useStore("users:list", s => s); 
+  const deleteCmd = useCommand("users:delete");
 
-    const goNext = () => api.update("pagination", d => { d.currentPage++ });
+  return (
+    <ul>
+      {users.map(u => (
+        <li key={u.id}>
+          {u.name} <button onClick={() => deleteCmd({ id: u.id })}>x</button>
+        </li>
+      ))}
+    </ul>
+  );
+};
 
-    return <button onClick={goNext}>Page {currentPage}</button>;
-  }, "pagination");
+export const UsersFeature: ModuleManifest = {
+  name: "users",
+  state: { "users:list": [] },
+  commands: {
+    "users:delete": ({ id }) => {
+      console.log("Deleting", id);
+      return true;
+    }
+  },
+  slots: {
+    "main-layout": [{ id: "user-list-view", component: UserList, priority: 10 }]
+  },
+  onLoad: (api) => {
+    api.markVirtual("main-layout", { itemHeight: 50 });
+  }
 };
 ```
 
+</details>
+
 ---
 
 ### 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) => {
-  // It creates root automatically | root = {}
-  PaginationFeature(api);
-  SalesFeature(api);
-});
-```
-
----
+<details>
+<summary>Example: main.tsx</summary>
 
-### 3️⃣ Wrap Your Application
+```ts
+import { PlcStore, PlcAPI, PlcProvider } from 'plug-code';
+import { UsersFeature } from './features/UsersFeature';
 
-```tsx
-// App.tsx
-import { useSystemPlc, SystemPlcRoot } from './system';
+const store = new PlcStore();
+const api = new PlcAPI(store);
 
-function App() {
-  const { api, useSelector } = useSystemPlc({ mode: "production" });
+api.registerModule(UsersFeature);
 
-  return (
-    <SystemPlcRoot api={api}>
-      <main>
-        <h1>Welcome to {useSelector(s => s.root.appName)}</h1>
-        <div className="footer-area">
-          {api.render("table-footer")}
-        </div>
-      </main>
-    </SystemPlcRoot>
-  );
-}
+const App = () => (
+  <PlcProvider api={api}>
+    <div className="app">
+      {api.render("main-layout")}
+    </div>
+  </PlcProvider>
+);
 ```
 
+</details>
+
 ---
 
 ## 📚 API Reference
 
-### 🧬 State & Reactivity
+### 🧬 State Management (`api`)
 
-| 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  |
+* `createStore<K>(key, initial)`: Initialize a key in the root store.
+* `setStore<K>(key, updater, priority?, useTransition?)`: Update state using **Immer**. Supports React 18 concurrency.
+* `getStore<K>(key)`: Get a snapshot of the state.
+* `watch<K>(key, selector, callback)`: Listen to reactive changes outside components.
 
----
-
-### 🎨 UI Slots
+### 🎨 UI & Layout (`api.layout`)
 
-| Method                               | Description          |
-| ------------------------------------ | -------------------- |
-| `register(slot, component, depKey?)` | Attach UI to slot    |
-| `render(slot, props?)`               | Render slot pipeline |
+* `register(slot, id, component, priority, keepAlive)`: Inject a component in a slot.
 
----
+  * `priority`: higher number = higher placement.
+  * `keepAlive`: keeps the component in memory (hidden DOM) between view changes.
+* `render(slot, props)`: Render slot content.
+* `markVirtual(slot, config)`: Transform a slot into a **high-performance virtual list** (supports 10k+ items).
 
-### 🧠 Business Logic (Commands)
+### 🧠 Logic & Commands
 
-| Method                        | Description       |
-| ----------------------------- | ----------------- |
-| `registerCommand(id, fn)`     | Register action   |
-| `execute(id, payload)`        | Run command       |
-| `wrapCommand(id, middleware)` | Intercept command |
-
----
+* `registerCommand(id, fn)`: Register a global command.
+* `execute(id, payload)`: Execute a command and return a typed Promise.
+* `wrapCommand(id, middleware)`: Intercept commands (logging, confirmation, etc).
 
-### 🔄 Data Transforms
+### ⚛️ React Hooks
 
-| Method                            | Description   |
-| --------------------------------- | ------------- |
-| `send(channel, id, fn, priority)` | Add transform |
-| `receive(channel, data)`          | Run pipeline  |
+* `useStore(key, selector)`: Reactive, selective state subscription.
+* `useCommand(id)`: Get an executable command function.
+* `useSlot(slot)`: Render a slot dynamically.
 
 ---
 
 ## 🌟 Best Practices
 
-* Keep **one feature per file**
-* Prefer `derive` over manual syncing
-* Always specify `dependencyKey` in `register`
-* Avoid putting everything in `root` — create focused stores
+* **Define types first:** Everything starts in `registry.ts`.
+* **Atomic Features:** A feature should contain all it needs (Store, UI, Commands).
+* **Data-Driven UI:** Change the store, let watchers/hooks update the view.
+* **Use Virtualization:** For large or growing lists, call `api.markVirtual` in `onLoad`.
 
 ---

package/dist/core/helpers/core.d.ts

@@ -0,0 +1,2 @@
+export declare function isEqual(a: any, b: any): boolean;
+export declare function shallowCompare(obj1: any, obj2: any): boolean;

package/dist/core/helpers/core.js

@@ -0,0 +1,32 @@
+export function isEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object' || !a || !b)
+        return false;
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (a[key] !== b[key])
+            return false;
+    }
+    return true;
+}
+export function shallowCompare(obj1, obj2) {
+    if (obj1 === obj2)
+        return true;
+    if (!obj1 || !obj2)
+        return false;
+    const keys1 = Object.keys(obj1);
+    const keys2 = Object.keys(obj2);
+    if (keys1.length !== keys2.length)
+        return false;
+    for (const key of keys1) {
+        if (obj1[key] !== obj2[key])
+            return false;
+    }
+    return true;
+}

package/dist/core/hooks/plcHooks.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+import { PlcAPI } from "../plcAPI";
+import { StoreKey, StoreValue, CommandKey, CmdPayload, CmdResult, SlotKey, SlotProps, FeatureRegistry, FeatureKey } from "../../types/registry";
+type SafeFeatureValue<F, K> = F extends keyof FeatureRegistry ? (K extends keyof FeatureRegistry[F] ? FeatureRegistry[F][K] : any) : any;
+export declare const PlcProvider: React.FC<{
+    api: PlcAPI;
+    children: React.ReactNode;
+}>;
+export declare function useStore<K extends StoreKey, T = StoreValue<K>>(key: K, selector?: (data: StoreValue<K>) => T): T;
+export declare function useStore<F extends FeatureKey, K extends keyof SafeFeatureValue<F, K> & string, T = SafeFeatureValue<F, K>>(key: `${F}:${K}`, selector?: (data: SafeFeatureValue<F, K>) => T): T;
+export declare function useCommand<K extends CommandKey>(commandId: K): (payload?: CmdPayload<K>) => Promise<CmdResult<K>>;
+export declare function useSlot<K extends SlotKey>(slotName: K): (props?: SlotProps<K>) => React.ReactNode;
+export declare function useTransientStore<K extends StoreKey, T>(key: K, selector: (state: StoreValue<K>) => T, effect: (value: T) => void, deps?: any[]): void;
+export declare function useTransientStore<F extends FeatureKey, K extends keyof SafeFeatureValue<F, K> & string, T>(key: `${F}:${K}`, selector: (state: SafeFeatureValue<F, K>) => T, effect: (value: T) => void, deps?: any[]): void;
+export {};

package/dist/core/hooks/plcHooks.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+const PlcContext = createContext(null);
+export const PlcProvider = ({ api, children }) => {
+    return _jsx(PlcContext.Provider, { value: api, children: children });
+};
+const usePlcApi = () => {
+    const api = useContext(PlcContext);
+    if (!api)
+        throw new Error("usePlcApi must be used within a PlcProvider");
+    return api;
+};
+export function useStore(key, selector = (d) => d) {
+    const api = usePlcApi();
+    const [value, setValue] = useState(() => {
+        const storeVal = key.includes(":")
+            ? api.getSubstore(...key.split(":"))
+            : api.getStore(key);
+        return selector(storeVal);
+    });
+    useEffect(() => {
+        const unsubscribe = api.watch(key, selector, (newValue) => {
+            setValue(newValue);
+        });
+        return unsubscribe;
+    }, [api, key, selector]);
+    return value;
+}
+export function useCommand(commandId) {
+    const api = usePlcApi();
+    return useMemo(() => {
+        return (payload) => api.execute(commandId, payload);
+    }, [api, commandId]);
+}
+export function useSlot(slotName) {
+    const api = usePlcApi();
+    return (props) => api.render(slotName, props);
+}
+export function useTransientStore(key, selector, effect, deps = []) {
+    const api = usePlcApi();
+    useEffect(() => {
+        const unsubscribe = api.watch(key, selector, (newValue) => {
+            effect(newValue);
+        });
+        return unsubscribe;
+    }, [api, key, ...deps]);
+}

package/dist/core/plcAPI.d.ts

@@ -0,0 +1,83 @@
+import React from "react";
+import { CommandFn } from "../types/core/api";
+import { ModuleManifest } from "../types/core/general";
+import { PlcStore } from "./plcStore";
+import { Priority } from "./plcScheduler";
+import { Draft } from "immer";
+import { PlcLayout } from "./ui/plcLayout";
+import { SlotWrapper } from "../types/core/ui";
+import { CommandRegistry, FeatureRegistry, StoreKey, CommandKey, SlotKey, FeatureKey, StoreValue, SlotProps } from "../types/registry";
+type SafeCmdPayload<K> = K extends keyof CommandRegistry ? (CommandRegistry[K] extends {
+    payload: infer P;
+} ? P : void) : any;
+type SafeCmdResult<K> = K extends keyof CommandRegistry ? (CommandRegistry[K] extends {
+    result: infer R;
+} ? R : void) : any;
+type SafeFeatureValue<F, K> = F extends keyof FeatureRegistry ? (K extends keyof FeatureRegistry[F] ? FeatureRegistry[F][K] : any) : any;
+export declare class PlcAPI {
+    private store;
+    private pipeline;
+    private scheduler;
+    layout: PlcLayout;
+    private compiledPipelines;
+    private receiveCache;
+    private commands;
+    private activeDependencyTracker;
+    private loadedFeatures;
+    constructor(store: PlcStore);
+    createStore<K extends StoreKey>(key: K, initial: StoreValue<K>): void;
+    getStore<K extends StoreKey>(key: K): StoreValue<K>;
+    setStore<K extends StoreKey>(key: K, updater: StoreValue<K> | ((draft: Draft<StoreValue<K>>) => void | StoreValue<K>), priority?: Priority, useTransition?: boolean): void;
+    createSubstore<F extends FeatureKey, K extends keyof any>(substore: F, key: K, initial: SafeFeatureValue<F, K>): void;
+    getSubstore<F extends FeatureKey, K extends keyof any>(substore: F, key: K): SafeFeatureValue<F, K>;
+    setSubstore<F extends FeatureKey, K extends keyof any>(substore: F, key: K, updater: SafeFeatureValue<F, K> | ((draft: Draft<SafeFeatureValue<F, K>>) => void | SafeFeatureValue<F, K>), priority?: Priority, useTransition?: boolean): void;
+    protected recordDependency(key: string, value: any): void;
+    makeTransform<T = any>(channel: string, id: string, fn: (data: T, ctx: any) => T | Promise<T>, priority?: number): void;
+    getTransform<T = any>(channel: string, initialData: T, context?: any, opts?: {
+        equality?: 'identity' | 'shallow' | 'deep';
+    }): Promise<T>;
+    receive<K extends string>(channel: K, initialData: any, context?: any): any;
+    registerCommand<K extends CommandKey>(id: K, fn: (payload?: SafeCmdPayload<K>) => SafeCmdResult<K> | Promise<SafeCmdResult<K>>): void;
+    wrapCommand<K extends CommandKey>(id: K, wrapper: (next: CommandFn<SafeCmdPayload<K>, SafeCmdResult<K>>) => CommandFn<SafeCmdPayload<K>, SafeCmdResult<K>>): void;
+    execute<K extends CommandKey>(id: K, payload?: SafeCmdPayload<K>): Promise<SafeCmdResult<K>>;
+    deriveStore<K extends StoreKey, Output>(outputKey: K, outputSlot: StoreKey, dependencies: StoreKey[], calculator: (...args: any[]) => Output): {
+        getValue: () => any;
+        trigger: () => void;
+        dispose: () => void;
+    };
+    deriveSubstore<F extends FeatureKey, K extends keyof any, Output>(substore: F, outputKey: K, outputSlot: keyof any, dependencies: string[], calculator: (...args: any[]) => Output): {
+        getValue: () => any;
+        trigger: () => void;
+        dispose: () => void;
+    };
+    private _triggerVersion;
+    private bumpVersion;
+    watch<K extends StoreKey, T>(key: K, selector: (data: StoreValue<K>) => T, callback: (newValue: T, oldValue: T) => void): () => void;
+    watch<F extends FeatureKey, K extends keyof any, T>(key: `${F}:${string & K}`, selector: (data: SafeFeatureValue<F, K>) => T, callback: (newValue: T, oldValue: T) => void): () => void;
+    watchStore<T>(storeKey: string, selector: (data: any) => T, callback: (newValue: T, oldValue: T) => void): () => void;
+    watchSubstore<T>(substore: string, key: string, selector: (data: any) => T, callback: (newValue: T, oldValue: T) => void): () => void;
+    watchAllStores<T = any>(definitions: Array<{
+        substore?: string;
+        store: string;
+        selector: (data: any) => Partial<T>;
+    }>, callback: (newValues: T, oldValues: T) => void): () => void;
+    redraw(keyOrSlot: string): void;
+    register<K extends SlotKey>(slot: K, id: string, componentFn: (props?: SlotProps<K>) => React.ReactNode, priority?: number, keepAlive?: boolean): void;
+    wrap<K extends SlotKey>(slot: K, wrapper: SlotWrapper): void;
+    after<K extends SlotKey>(slot: K, targetId: string, newId: string, componentFn: () => React.ReactNode): void;
+    render<K extends SlotKey>(slot: K, props?: SlotProps<K>): React.ReactNode;
+    markVirtual(slot: SlotKey, config?: {
+        itemHeight?: number;
+        overscan?: number;
+    }): void;
+    connect(renderFn: (props?: any) => React.ReactNode, dependencies: Array<string | {
+        store: string;
+        keys?: string[];
+    }>): React.FC<any>;
+    registerModule(manifest: ModuleManifest): void;
+    loadFeature(importer: () => Promise<{
+        default: ModuleManifest;
+    }>): Promise<void>;
+    createSelector<S, R>(extractor: (state: S) => any[], calculator: (...args: any[]) => R): (state: S) => R;
+}
+export {};