working on ojs documentation

levizwannah · levizwannah · commit 3be51a23b2ba · 2026-01-23T16:36:57.000+03:00
diff --git a/docs/events.md b/docs/events.md
@@ -0,0 +1,114 @@
+# Events & Broker
+
+OpenScript uses a **Broker** to manage communication between components and mediators. This decoupled architecture relies on a structured event system.
+
+## Event Structure & Registration
+
+Events are typically defined as a structured "fact" object in `events.js`. This structure allows you to use auto-completion and compile-time checking for event names.
+
+When you register this object with the broker using `broker.registerEvents(appEvents)`, OpenScript parses it and replaces the leaf values (set to `true`) with the actual namespaced event string.
+
+```javascript
+// events.js (Before Registration)
+export const appEvents = {
+  auth: {
+    login: true, // Becomes "auth:login"
+    logout: true, // Becomes "auth:logout"
+  },
+  user: {
+    is: {
+      authenticated: true, // Becomes "user:is:authenticated"
+    },
+  },
+};
+```
+
+### Registration (ojs.config.js)
+
+```javascript
+import { appEvents } from "./events.js";
+
+// ... in configureApp()
+broker.registerEvents(appEvents);
+container.value("appEvents", appEvents);
+```
+
+## Using Object Paths
+
+After registration, you can use the `appEvents` object keys to reference the event strings directly. This prevents typo-related bugs.
+
+```javascript
+// Instead of this:
+this.send("auth:login", data);
+
+// Use this:
+this.send(appEvents.auth.login, data);
+```
+
+## Payloads (`payload` / `EventData`)
+
+When sending events, it is best practice to wrap your data in a standard **Payload**. OpenScript provides a `payload` or `eData` helper for this.
+
+A payload consists of:
+
+- **Message**: The actual data (body).
+- **Meta**: Metadata about the event (timestamps, source, etc).
+
+```javascript
+import { payload } from "modular-openscriptjs";
+
+// Sending an event with a payload
+this.send(
+  appEvents.auth.login,
+  payload(
+    { username: "Levi", id: 1 }, // Message
+    { timestamp: Date.now() }, // Meta (optional)
+  ),
+);
+```
+
+### Receiving Payloads
+
+Listeners created with `$$` (or standard broker listeners) receive these arguments.
+
+```javascript
+async $$auth_login(payloadObj) {
+  // payloadObj is the message/data directly if spread,
+  // OR the EventData object depending on how it was sent.
+  // Generally, OpenScript broker spreads arguments.
+
+  // If sent as above:
+  // args[0] = { username: "Levi", id: 1 }
+  // args[1] = { timestamp: ... }
+}
+```
+
+> **Note**: `EventData` is the underlying class, but `payload()` is the convenient helper function to create instances of it.
+
+## Parsing Received Events
+
+When an event is received (e.g., in a Mediator), the payload is often a **JSON string**. You must parse it back into an `EventData` object to access the helpers.
+
+```javascript
+import { EventData } from "modular-openscriptjs";
+
+// ... in a listener
+const eventData = EventData.parse(payloadString);
+```
+
+### EventData Helper Methods
+
+The parsed object provides `message` and `meta` properties, each with the following methods:
+
+- `has(key)`: Checks if a key exists.
+- `get(key, defaultValue)`: Gets a value (returns `defaultValue` if missing).
+- `put(key, value)`: Sets a value.
+- `remove(key)`: Deletes a value.
+- `getAll()`: Returns the raw object.
+
+```javascript
+const userId = eventData.message.get("id");
+if (eventData.meta.has("timestamp")) {
+  // ...
+}
+```
diff --git a/docs/mediators.md b/docs/mediators.md
@@ -0,0 +1,106 @@
+# Mediators
+
+Mediators act as the bridge between your application's logic (backend/services) and the frontend (components). They facilitate a clean separation of concerns by handling business logic and communicating via the unrelated **Broker**.
+
+## Concept & Role
+
+Mediators are **stateless** classes that listen for events, execute logic (like API calls or data processing), and then potentially emit new events. They do not manipulate the DOM directly.
+
+```javascript
+// Example Mediator structure
+export default class AuthMediator extends Mediator {
+  shouldRegister() {
+    return true; // Control registration logic
+  }
+}
+```
+
+## Broker Registration
+
+When you define a Mediator, it is automatically registered with the **Broker** if `shouldRegister()` returns `true`. The broker scans the mediator for special properties to set up event listeners.
+
+## Event Listening (`$$`)
+
+The `$$` prefix is used to define event listeners. OpenScript interprets these property names and values to decide which events to listen to.
+
+### Underscore means "OR"
+
+If you use an underscore in the method name after `$$`, it acts as an **OR** operator. The method will key off **multiple independent events**.
+
+```javascript
+import { EventData } from "modular-openscriptjs";
+
+/*
+ * Listens for:
+ * - 'user' event
+ * - 'login' event
+ * (NOT 'user:login')
+ */
+async $$user_login(eventData) {
+  // Parse the JSON string payload
+  const data = EventData.parse(eventData);
+
+  console.log("Triggered by 'user' OR 'login' event");
+  console.log("User ID:", data.message.get("id"));
+}
+```
+
+### Namespacing (Nested Objects)
+
+To listen to namespaced events (e.g., `user:login`, `user:logout`), you should use **nested objects**. This structure treats events as facts and allows for organized event definitions.
+
+```javascript
+// Property starts with $$ -> 'auth' namespace
+$$auth = {
+  // Listens for 'auth:login'
+  login: async (eventData) => {
+    const data = EventData.parse(eventData);
+    this.handleLogin(data);
+  },
+
+  // Listens for 'auth:logout'
+  logout: async () => {
+    this.handleLogout();
+  },
+
+  // Nested further: 'auth:password:reset'
+  password: {
+    reset: (email) => { ... }
+  }
+}
+```
+
+## Creating "Events as Facts"
+
+It is a best practice to structure your events like facts (`noun:verb` or `subject:predicate:object`). This is typically done in `events.js` and enforced by `broker.requireEventsRegistration(true)`.
+
+```javascript
+// appEvents definition (events.js)
+export const appEvents = {
+  user: {
+    is: {
+      authenticated: true, // event: 'user:is:authenticated'
+      unauthenticated: true,
+    },
+    has: {
+      ordered: true, // event: 'user:has:ordered'
+    },
+  },
+};
+```
+
+## Sending Events
+
+Mediators can send events using `this.send(event, payload(...))` or `this.broadcast(event, payload(...))`.
+
+```javascript
+import { payload } from "modular-openscriptjs";
+
+async $$auth_login(eventData) {
+  // Validate...
+  this.send(
+      "user:is:authenticated",
+      payload({ userProfile })
+  );
+}
+```
diff --git a/docs/osm.md b/docs/osm.md
@@ -190,3 +190,38 @@ h.div(
   ),
 );
 ```
+
+## Fragments (`h.$` or `h._`)
+
+Fragments allow you to group multiple elements without adding an extra node to the DOM. This is particularly useful when returning multiple root elements from a component or `h.call`.
+
+To create a fragment, use `h.$()` or `h._()`.
+
+> [!IMPORTANT]
+> **Single Root Requirement**: Even within a fragment, you must ensure there is a **single top-level element** that acts as the parent for the other elements in that fragment structure.
+
+```javascript
+// Correct Usage
+h.$(
+  h.div(
+    // Top-level parent in the fragment
+    h.span("Part 1"),
+    h.span("Part 2"),
+  ),
+);
+
+// Incorrect Usage (Multiple top-level siblings)
+// h.$ (
+//   h.div("Part 1"),
+//   h.div("Part 2")
+// )
+```
+
+### Component Wrapper Behavior
+
+Normally, a Component's markup is automatically wrapped in a custom element (e.g., `<ojs-my-component>`). However, **if a component returns a fragment**, this wrapper is **NOT** created.
+
+> [!CAUTION]
+> **State Reactivity Limitation**: Components that return fragments **cannot react to state changes** efficiently because there is no wrapper element to anchor the reconciler. Use fragments in components primarily for splitting up large render functions or for static content.
+>
+> **Top-Level Requirement**: While fragments avoid wrappers, your final application structure **Must** typically have a stable top-level element in the final markup for the framework to attach to.
diff --git a/docs/special-attributes.md b/docs/special-attributes.md
@@ -0,0 +1,90 @@
+# Special Attributes
+
+OpenScript provides several special attributes that control how elements are rendered and how component wrappers are styled.
+
+## Render Placement Attributes
+
+These attributes control _where_ and _how_ an element triggers the rendering process relative to a parent.
+
+### `parent`
+
+Specifies the DOM element to append the new element to.
+
+```javascript
+const myContainer = document.getElementById("container");
+h.div({ parent: myContainer }, "I am appended to #container");
+```
+
+### `resetParent`
+
+If `true`, clears the `parent` element's content before appending the new element.
+
+```javascript
+h.div({ parent: myContainer, resetParent: true }, "I am the only child now");
+```
+
+### `replaceParent`
+
+If `true`, the new element **replaces** the `parent` element in the DOM.
+
+```javascript
+h.div(
+  { parent: oldElement, replaceParent: true },
+  "I replaced the old element",
+);
+```
+
+### `firstOfParent`
+
+If `true`, prepends the element to the `parent` instead of appending.
+
+```javascript
+h.div({ parent: myContainer, firstOfParent: true }, "I am first!");
+```
+
+## Component Wrapper Attributes
+
+When a class component is rendered, it is wrapped in a custom element (e.g., `<ojs-my-component>`). You can pass attributes to this wrapper from within the component's render method or when using the component.
+
+### `c_attr` (Component Attributes)
+
+Used to pass a group of attributes to the component's wrapper.
+
+```javascript
+// Inside a component's render method
+render() {
+  return h.div(
+    {
+      c_attr: {
+        class: "my-component-wrapper",
+        "data-theme": "dark",
+        onclick: "console.log('Wrapper clicked')"
+      }
+    },
+    "Component Content"
+  );
+}
+// Renders: <ojs-comp class="my-component-wrapper" data-theme="dark" ...><div>...</div></ojs-comp>
+```
+
+### `$` Prefix Attributes
+
+Attributes starting with `$` are treated as wrapper attributes. This is a shorthand for `c_attr`.
+
+```javascript
+h.MyComponent({
+  $class: "theme-dark",
+  $id: "main-component",
+  $style: "border: 1px solid red;",
+});
+// Renders: <ojs-my-component class="theme-dark" id="main-component" style="...">...</ojs-my-component>
+```
+
+### `withCAttr`
+
+If set to `true`, it serializes the `c_attr` object and adds it as a `c-attr` attribute on the element. This is mostly used internally or for debugging.
+
+```javascript
+h.div({ c_attr: { id: 1 }, withCAttr: true }, "...");
+// <div c-attr='{"id":1}'>...</div>
+```
diff --git a/docs/state.md b/docs/state.md
diff --git a/package.json b/package.json
