MostJS Framework Documentation

Introduction

MostJS is a lightweight frontend framework that gives you complete control over your code without imposing restrictive patterns. It provides a simple yet powerful approach to building web applications, allowing you to use the framework's utilities while maintaining the freedom to incorporate your preferred JavaScript techniques.

Unlike larger frameworks that dictate how your application should be structured, MostJS provides essential tools for creating reactive web applications while keeping the core API minimal and approachable.

Table of Contents

1. Getting Started
   • Installation
   • Basic Usage
2. Core Concepts
   • Virtual DOM
   • Creating Elements
   • Creation Components
   • Components
   • State Management
   • Handling References
   • Watching for Changes
   • Routing
   • Diffing Algorithm
   • Rendering
3. API Reference
   • Core Functions
   • Creation Components
   • Router API
4. Examples
   • Counter Application
   • Theme Switcher with useRef and Watch
   • Todo List Application
   • SPA with Routing
5. Under the Hood
   • Component Architecture
   • State Management Implementation
   • Component Lifecycle
   • Diffing Algorithm Details
6. Best Practices
   • Component Organization
   • Performance Optimization
   • State Management Patterns
   • Error Handling

Getting Started

Installation

You can install MostJS via npm:

# Using npm
npm i @hacker_man/most-js

Using CDN

For direct use in browsers without a build step:

import { anything } from 'https://cdn.jsdelivr.net/npm/@hacker_man/most-js@1.3.0/index.js'

Basic Usage

Here's a simple example showing how to create a counter application:

import { Div, H1, P, Button, useState, render } from 'https://cdn.jsdelivr.net/npm/@hacker_man/most-js@1.3.0/index.js';

const App = () => {
  const [count, setCount] = useState(0);
  
  return Div({ className: 'app' }, [
    H1({}, ["Hello, MostJS!"]),
    P({}, [`Current count: ${count}`]),
    Button({ 
      onClick: () => setCount((count)=>{count + 1}) 
    }, ["Increment"])
  ]);
}

// Render your app to the DOM
render("App", App);

Core Concepts

Virtual DOM

MostJS uses a virtual DOM approach to efficiently update the real DOM. The virtual DOM is a lightweight JavaScript representation of the actual DOM, allowing the framework to perform optimized updates.

Why use a Virtual DOM?

1. Performance: By comparing virtual DOM trees before updating the real DOM, MostJS minimizes expensive DOM operations.
2. Simplicity: Developers can describe the UI declaratively without worrying about manual DOM manipulations.

At its core, MostJS's virtual DOM nodes are simple JavaScript objects with the following structure:

{
  tag: 'div',           // HTML tag or component name
  props: { /* ... */ }, // Element attributes, event handlers, etc.
  children: [],         // Child nodes or text content
  ref: null             // Reference to actual DOM element (populated after rendering)
}

Creating Elements

In MostJS, you create virtual DOM elements using the Create function:

Create(tag, props, ...children)

Parameters:

• tag: The HTML tag name (like 'div', 'span', etc.)
• props: An object containing attributes, event handlers, and other properties
• children: An array of child elements or text content

Example:

const element = Create('div', { 
  className: 'container',
  id: 'main',
  onClick: () => console.log('Clicked!')
}, [
  Create('h1', {}, ["Title"]),
  Create('p', {}, ["Content"])
]);

Under the hood, the Create function does the following:

1. Processes children, converting strings and numbers to text nodes
2. Returns a virtual DOM node object with the specified tag, props, and children

Creation Components

MostJS provides creation-components, which are predefined functions that use the Create function internally, making your code cleaner and more readable.

Example:

import { Div, P } from 'https://cdn.jsdelivr.net/npm/@hacker_man/most-js@1.3.0/index.js';

return Div({ className: 'container' }, [
  P({ id: "greeting" }, ["Hello world"])
]);

Available Creation Components

MostJS includes creation components for most common HTML elements. Each one follows the same pattern - accepting props and children, then forwarding them to the Create function with the appropriate tag name:

• Button: For <button> elements
• Div: For <div> elements
• Ul: For <ul> elements
• Li: For <li> elements
• H1 through H6: For heading elements
• Input: For <input> elements
• P: For paragraph elements
• Span: For <span> elements
• Link: For <a> elements (with special routing behavior)
• Aside: For <aside> elements
• Header: For <header> elements
• Hr: For <hr> elements
• Blockquote: For <blockquote> elements
• Footer: For <footer> elements
• Section: For <section> elements
• Label: For <label> elements
• Main: For <main> elements

Special Case: Link Component

The Link component deserves special attention as it integrates with the MostJS router:

• Requires an href prop
• Automatically opens external links in a new tab
• Intercepts click events to trigger client-side routing
• Supports a render parameter to control whether the new route should be rendered or just change path

Link(props= {}, children= [], render=true)

render parameter is for choosing to just push the path but not render anything you can acheive same result with

router.pushOnly()

Components

MostJS components are functions that return virtual DOM nodes. Unlike some other frameworks, components in MostJS are pure JavaScript functions, making them intuitive and flexible.

The Component function is used to render and manage reusable components:

Component(componentFn, props, title)

Parameters:

• componentFn: The component function to render
• props: Properties to pass to the component
• title: A unique identifier for the component (required)

Example:

import { Div, Component } from 'https://cdn.jsdelivr.net/npm/@hacker_man/most-js@1.3.0/index.js';
import Sidebar from './Sidebar.js';
import MainContent from './MainContent.js';

const App = () => {
  return Div({ className: 'app' }, [
    Component(Sidebar, { isCollapsed: false }, "sidebar"),
    Component(MainContent, { title: "Welcome" }, "main-content")
  ]);
};

Under the hood, Component does the following:

1. Registers the component function with its title
2. Manages component state tracking
3. Handles the component stack for context during rendering
4. Captures and returns the component's virtual DOM representation

State Management

MostJS provides a simple state management system with the useState fucntion, inspired by React's hook system.

useState

The useState hook allows components to maintain and update state:

const [state, setState] = useState(initialValue);

Parameters:

• initialValue: Initial state value (can be a value or function)

Returns:

• An array containing:
  • state: Current state value
  • setState: Function to update the state

Example:

import { Div, Button, useState } from 'https://cdn.jsdelivr.net/npm/@hacker_man/most-js@1.3.0/index.js';

const Counter = () => {
  const [count, setCount] = useState(0);
  
  return Div({}, [
    `Count: ${count}`,
    Button({ onClick: () => setCount(count + 1) }, ["Increment"])
  ]);
};

How it works:

The useState implementation:

1. Identifies the current component from the component stack
2. Retrieves or initializes the component's state storage
3. Gets or sets the state at the current index
4. Provides a setter function that:
   • Accepts a new value or a function to compute a new value
   • Performs equality checks based on the state type
   • Triggers a re-render only when the state actually changes

Handling References

useRef

The useRef hook provides direct access to DOM elements:

const elementRef = useRef(referenceId);

Parameters:

• referenceId: A unique string identifier that matches a reference prop on an element

Returns:

• The actual DOM element

Example:

import { Div, Input, Button, useRef } from 'https://cdn.jsdelivr.net/npm/@hacker_man/most-js@1.3.0/index.js';

const SearchField = () => {
  const inputRef = useRef("search-input");
  
  const focusInput = () => {
    inputRef.focus();
  };
  
  return Div({}, [
    Input({ 
      reference: "search-input",
      placeholder: "Search..." 
    }, []),
    Button({ onClick: focusInput }, ["Focus Search"])
  ]);
};

How it works:

The reference system in MostJS:

1. Uses a global map to store references to DOM elements
2. Requires elements to have a reference prop with a unique identifier
3. During element creation, elements with a reference prop are added to the refs map
4. The useRef function retrieves an element from the refs map using the provided identifier.
   If the reference is not found, it returns undefined.

This can happen when elements are rendered conditionally and the reference was never attached.

Watchin