README.npm.md

Modular OpenScript Framework

A modern, lightweight, reactive JavaScript framework for building scalable web applications with zero runtime dependencies. OpenScript combines IoC, reactive state management, and component-based architecture into a powerful yet simple package.

✨ Why OpenScript?

• ⚡️ Reactive State - Automatic UI updates with proxy-based state
• 🧩 Component-Based - Modular, reusable components with lifecycle hooks
• 🔄 Client-Side Routing - Fluent API with parameters and nested routes
• 📡 Event-Driven - Broker/Mediator pattern for decoupled architecture
• 🎯 IoC Container - Centralized dependency management
• 🎨 Framework Agnostic - Works with Tailwind, Bootstrap, or vanilla CSS
• 🛠️ Vite Plugin - Production-ready build tools
• 📦 Zero Dependencies - No runtime dependencies

---

🚀 Quick Start

Installation

npm install modular-openscriptjs

Scaffold a New Project

The fastest way to start:

npx create-ojs-app my-app
cd my-app
npm run dev

Choose from templates:

• basic - Clean starter with vanilla CSS
• tailwind - TailwindCSS with responsive design
• bootstrap - Bootstrap 5 integration

Your First Component

import { Component, app, state, ojs } from "modular-openscriptjs";

const h = app("h");

class Counter extends Component {
  constructor() {
    super();
    this.count = state(0);
  }

  increment() {
    this.count.value++;
  }

  render() {
    return h.div(
      h.h2("Count: ", this.count.value),
      h.button({ onclick: this.increment.bind(this) }, "Increment")
    );
  }
}

ojs(Counter);

---

📖 Core Concepts

1. Components

Class Components with lifecycle hooks:

import { Component, app } from "modular-openscriptjs";

const h = app("h");

class UserCard extends Component {
  async mount() {
    // Called when component mounts
    console.log("Component mounted");
  }

  unmount() {
    // Called when component unmounts
    console.log("Component unmounted");
  }

  render(...args) {
    return h.div(
      { class: "card" },
      h.h3("User Profile"),
      h.p("Content here"),
      ...args
    );
  }
}

Functional Components for simple UI:

const Button = (text, onClick) => {
  return h.button({ onclick: onClick }, text);
};

const Card = (title, content) => {
  return h.div({ class: "card" }, h.h2(title), h.div(content));
};

2. Reactive State

State automatically triggers re-renders:

import { state } from "modular-openscriptjs";

// Create reactive state
const count = state(0);

// Read value
console.log(count.value); // 0

// Update value (triggers re-render)
count.value++;

// Listen to changes
count.listener((s) => {
  console.log("New:", s.value);
  console.log("Previous:", s.previousValue);
});

State in Components:

class TodoList extends Component {
  constructor() {
    super();
    this.todos = state([]);
  }

  addTodo(text) {
    this.todos.value = [
      ...this.todos.value,
      { id: Date.now(), text, done: false },
    ];
  }

  toggleTodo(id) {
    this.todos.value = this.todos.value.map((t) =>
      t.id === id ? { ...t, done: !t.done } : t
    );
  }

  render() {
    return h.div(
      h.input({
        placeholder: "Add todo...",
        onkeypress: (e) => {
          if (e.key === "Enter") {
            this.addTodo(e.target.value);
            e.target.value = "";
          }
        },
      }),
      h.ul(
        ...this.todos.value.map((todo) =>
          h.li(
            { class: todo.done ? "done" : "" },
            h.input({
              type: "checkbox",
              checked: todo.done,
              onchange: () => this.toggleTodo(todo.id),
            }),
            h.span(todo.text)
          )
        )
      )
    );
  }
}

3. Routing

Simple yet powerful client-side routing:

import { app } from "modular-openscriptjs";

const router = app("router");
const h = app("h");

// Basic routes
router.on(
  "/",
  () => {
    h.HomePage({ parent: document.body, resetParent: true });
  },
  "home"
);

router.on(
  "/about",
  () => {
    h.AboutPage({ parent: document.body, resetParent: true });
  },
  "about"
);

// Routes with parameters
router.on(
  "/users/{id}",
  () => {
    const userId = router.params.id;
    h.UserProfile(userId, { parent: document.body, resetParent: true });
  },
  "users.view"
);

// Grouped routes
router.prefix("admin").group(() => {
  router.on(
    "/dashboard",
    () => {
      h.AdminDashboard({ parent: document.body, resetParent: true });
    },
    "admin.dashboard"
  );

  router.on(
    "/users",
    () => {
      h.AdminUsers({ parent: document.body, resetParent: true });
    },
    "admin.users"
  );
});

router.listen();

Navigation:

// Navigate to named route
router.to("home");

// Navigate with parameters
router.push("/users/123");

// Go back
router.back();

4. Global State with Contexts

Share state across your entire application:

import { context, putContext, app } from "modular-openscriptjs";

const h = app("h");

// Register contexts
putContext(["app", "user"], "AppContext");

// Initialize state
const ac = context("app");
ac.states({
  theme: "light",
  language: "en",
});

const uc = context("user");
uc.states({
  name: "Guest",
  isLoggedIn: false,
});

// Use in any component
class Header extends Component {
  toggleTheme() {
    ac.theme.value = ac.theme.value === "light" ? "dark" : "light";
  }

  render() {
    return h.header(
      h.h1(`Welcome, ${uc.name.value}`),
      h.button(
        { onclick: this.toggleTheme.bind(this) },
        `Theme: ${ac.theme.value}`
      )
    );
  }
}

5. Event System

Decouple business logic with events:

import { Mediator, app, payload, Utils } from "modular-openscriptjs";

const broker = app("broker");

// Register events
broker.registerEvents({
  user: {
    login: true,
    logout: true,
  },
  notification: {
    show: true,
  },
});

// Create mediator for business logic
class UserMediator extends Mediator {
  $$user = {
    login: (ed, event) => {
      const data = Utils.parsePayload(ed);
      console.log("User logged in:", data.message);

      // Update UI
      broker.send(
        "notification:show",
        payload({
          message: "Login successful!",
        })
      );
    },

    logout: (ed, event) => {
      console.log("User logged out");

      broker.send(
        "notification:show",
        payload({
          message: "Goodbye!",
        })
      );
    },
  };
}

new UserMediator();

// Emit events from anywhere
class LoginButton extends Component {
  handleLogin() {
    broker.send(
      "user:login",
      payload({
        username: "john_doe",
        id: 123,
      })
    );
  }

  render() {
    return h.button({ onclick: this.handleLogin.bind(this) }, "Login");
  }
}

6. IoC Container

Access services through the container:

import { app } from "modular-openscriptjs";

// Get services
const h = app("h");
const router = app("router");
const broker = app("broker");
const contextProvider = app("contextProvider");

// Register custom values
app().value("apiUrl", "https://api.example.com");
app().value("config", { debug: true });

// Access custom values
const apiUrl = app("apiUrl");
const config = app("config");

---

🏗️ Project Structure

Typical project layout:

my-app/
├── src/
│   ├── components/
│   │   ├── Header.js
│   │   ├── Footer.js
│   │   └── TodoList.js
│   ├── contexts.js      # Global state
│   ├── routes.js        # Route definitions
│   ├── events.js        # Event registry
│   ├── mediators/       # Business logic
│   │   └── UserMediator.js
│   ├── main.js          # Entry point
│   └── style.css
├── index.html
├── vite.config.js
└── package.json

---

🎨 Framework Integration

TailwindCSS

import { app } from "modular-openscriptjs";

const h = app("h");

class Card extends Component {
  render() {
    return h.div(
      { class: "bg-white rounded-lg shadow-lg p-6" },
      h.h2({ class: "text-2xl font-bold mb-4" }, "Card Title"),
      h.p({ class: "text-gray-600" }, "Card content here")
    );
  }
}

Bootstrap

class Alert extends Component {
  render(message, type = "info") {
    return h.div({ class: `alert alert-${type}` }, message);
  }
}

---

🔧 Build Configuration

Vite Setup

// vite.config.js
import { defineConfig } from "vite";
import { openScriptComponentPlugin } from "modular-openscriptjs/plugin";

export default defineConfig({
  plugins: [openScriptComponentPlugin()],
  build: {
    target: "es2015",
    minify: "terser",
  },
});

This plugin ensures component names survive minification.

Build Commands

# Development server
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

---

💡 Advanced Features

Fragments

Return multiple elements without a wrapper:

class List extends Component {
  render() {
    return h.$(
      // Fragment
      h.h1("Title"),
      h.p("Paragraph 1"),
      h.p("Paragraph 2")
    );
  }
}

State Listeners

React to state changes:

const count = state(0);

count.listener((s) => {
  console.log(`Count changed from ${s.previousValue} to ${s.value}`);

  if (s.value > 10) {
    console.warn("Count is getting high!");
  }
});

Multi-Event Listeners

Listen to multiple events:

class NotificationMediator extends Mediator {
  $$user = {
    // Triggers on BOTH login AND logout
    login_logout: (ed, event) => {
      console.log(`User event: ${event}`);
      this.showNotification(`User ${event.split(":")[1]}`);
    },
  };
}

Computed Properties

Use getters for derived state:

class TodoList extends Component {
  constructor() {
    super();
    this.todos = state([]);
  }

  get completedCount() {
    return this.todos.value.filter((t) => t.done).length;
  }

  get activeCount() {
    return this.todos.value.length - this.completedCount;
  }

  render() {
    return h.div(
      h.p(`${this.activeCount} active, ${this.completedCount} completed`)
      // ... rest of render
    );
  }
}

---

📚 Complete Example

Here's a full-featured app:

import {
  Component,
  app,
  state,
  context,
  putContext,
  Mediator,
  payload,
  ojs,
} from "modular-openscriptjs";

const h = app("h");
const broker = app("broker");

// Setup context
putContext("todos", "TodoContext");
const tc = context("todos");
tc.states({ todos: [], filter: "all" });

// Register events
broker.registerEvents({
  todo: {
    added: true,
    removed: true,
    toggled: true,
  },
});

// Business logic mediator
class TodoMediator extends Mediator {
  $$todo = {
    added: (ed) => {
      console.log("Todo added:", ed);
    },

    removed: (ed) => {
      console.log("Todo removed:", ed);
    },

    toggled: (ed) => {
      console.log("Todo toggled:", ed);
    },
  };
}

new TodoMediator();

// Main component
class TodoApp extends Component {
  constructor() {
    super();
    this.input = state("");
  }

  addTodo() {
    if (this.input.value.trim()) {
      const todo = {
        id: Date.now(),
        text: this.input.value,
        done: false,
      };

      tc.todos.value = [...tc.todos.value, todo];
      broker.send("todo:added", payload(todo));
      this.input.value = "";
    }
  }

  toggleTodo(id) {
    tc.todos.value = tc.todos.value.map((t) =>
      t.id === id ? { ...t, done: !t.done } : t
    );
    broker.send("todo:toggled", payload({ id }));
  }

  removeTodo(id) {
    tc.todos.value = tc.todos.value.filter((t) => t.id !== id);
    broker.send("todo:removed", payload({ id }));
  }

  get filteredTodos() {
    switch (tc.filter.value) {
      case "active":
        return tc.todos.value.filter((t) => !t.done);
      case "done":
        return tc.todos.value.filter((t) => t.done);
      default:
        return tc.todos.value;
    }
  }

  render() {
    return h.div(
      { class: "todo-app" },

      // Header
      h.header(
        h.h1("My Todos"),
        h.div(
          { class: "input-group" },
          h.input({
            value: this.input.value,
            placeholder: "What needs to be done?",
            oninput: (e) => (this.input.value = e.target.value),
            onkeypress: (e) => e.key === "Enter" && this.addTodo(),
          }),
          h.button({ onclick: () => this.addTodo() }, "Add")
        )
      ),

      // Filters
      h.div(
        { class: "filters" },
        ...["all", "active", "done"].map((f) =>
          h.button(
            {
              class: tc.filter.value === f ? "active" : "",
              onclick: () => (tc.filter.value = f),
            },
            f.toUpperCase()
          )
        )
      ),

      // Todo list
      h.ul(
        ...this.filteredTodos.map((todo) =>
          h.li(
            h.input({
              type: "checkbox",
              checked: todo.done,
              onchange: () => this.toggleTodo(todo.id),
            }),
            h.span({ class: todo.done ? "done" : "" }, todo.text),
            h.button({ onclick: () => this.removeTodo(todo.id) }, "×")
          )
        )
      ),

      // Stats
      h.footer(h.span(`${this.filteredTodos.length} items`))
    );
  }
}

ojs(TodoApp);

---

📖 API Reference

Core Exports

Export	Type	Description
Component	Class	Base component class
app	Function	Access IoC container
state	Function	Create reactive state
ojs	Function	Bootstrap application
context	Function	Access context
putContext	Function	Register context
Mediator	Class	Base mediator class
payload	Function	Create event payload
Utils	Object	Utility functions

Component Lifecycle

Method	Description
constructor()	Initialize component
mount()	Component mounted (async supported)
render()	Generate component UI
unmount()	Component unmounted

State API

Property/Method	Description
.value	Get/set state value
.listener(fn)	Add state change listener
.previousValue	Previous state value (in listener)

---

🎯 Best Practices

✅ Do's

• Use contexts for global state
• Keep components small and focused
• Leverage lifecycle hooks appropriately
• Use mediators for business logic
• Use computed properties for derived state

❌ Don'ts

• Don't mutate state directly
• Don't mix business logic with UI
• Don't create functions in render
• Don't emit events in tight loops

---

🐛 Troubleshooting

Component not re-rendering?

• Ensure state is updated via .value =
• Verify state is used in render()

Events not firing?

• Check events are registered
• Verify event names match exactly

Router not working?

• Call router.listen() after defining routes
• Check route paths are correct

---

📦 Package Info

• Size: ~95KB (ES), ~42KB (UMD)
• Dependencies: Zero runtime dependencies
• Browser Support: Modern browsers (ES6+)
• License: MIT

---

📚 Learn More

• Full Documentation
• Examples
• API Reference
• Issue Tracker

---

🤝 Contributing

We welcome contributions! See our Contributing Guide.

---

📄 License

MIT © Levi Kamara Zwannah

---

Built with ❤️ using OpenScript

⭐ Star on GitHub | 📦 View on npm