npm package: @monygroupcorp/microact
Description: A lean, minimal React-like framework for client-side applications.
Author: arthurt
Latest version: 0.2.4

# microact

A lean, minimal React-like framework for building fast and efficient client-side web applications. `microact` focuses on providing core component functionality, state management, and a flexible rendering system without the heavy overhead of larger frameworks.

## Features

*   **Component-Based:** Build UIs using familiar class-based components with lifecycle methods.
*   **Reactive State:** Simple `this.state` and `this.setState` for managing component-local state.
*   **Granular DOM Updates:** Efficient DOM manipulation to minimize re-renders and optimize performance.
*   **Event Handling:** Declarative event binding for clean and maintainable UI logic.
*   **Context API:** Built-in context system for prop drilling avoidance and global state propagation.
*   **Pluggable Stores:** Designed to integrate seamlessly with external state management solutions.
*   **Small Footprint:** Optimized for client-side execution in statically hosted environments.

## Installation

Install `microact` using npm:

```bash
npm install microact
```

## Usage

### 1. Create a Component

Create a class that extends `Component` and implements a `render()` method:

```javascript
// myComponent.js
import { Component } from 'microact';

class MyComponent extends Component {
  constructor(element) {
    super(element);
    this.state = {
      count: 0,
      message: 'Hello, microact!'
    };
  }

  // Lifecycle method: Called after component is mounted to the DOM
  onMount() {
    console.log('MyComponent mounted!');
  }

  // Define DOM events
  events() {
    return {
      'click button': 'incrementCount',
    };
  }

  incrementCount() {
    this.setState({ count: this.state.count + 1 });
  }

  // Render method returns an HTML string
  render() {
    return `
      <div>
        <h1>${this.state.message}</h1>
        <p>Count: ${this.state.count}</p>
        <button>Click me!</button>
      </div>
    `;
  }
}

export default MyComponent;
```

### 2. Mount Your Component

In your main application file, import and mount your component to a DOM element:

```javascript
// index.js
import MyComponent from './myComponent.js';

const appRoot = document.getElementById('app-root');
const myComponent = new MyComponent(appRoot);
myComponent.mount(appRoot);
```

### 3. Basic HTML Structure

Your HTML file should have a root element for your application:

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Microact App</title>
</head>
<body>
    <div id="app-root"></div>
    <script type="module" src="index.js"></script>
</body>
</html>
```

## API Reference

### `Component` Class

*   `constructor(rootElement)`: Initializes the component.
*   `setState(newState)`: Updates component state and triggers a re-render if `shouldUpdate` returns `true`.
*   `mount(element)`: Mounts the component to the given DOM element.
*   `unmount()`: Removes the component from the DOM and cleans up resources.
*   `render()`: **(Must be implemented by subclasses)** Returns the HTML string representation of the component.
*   `template()`: Optional. If `render()` is not overridden, it defaults to calling `this.template()`.
*   `onMount()`: Lifecycle hook called after mounting.
*   `onUnmount()`: Lifecycle hook called before unmounting.
*   `onStateUpdate(oldState, newState)`: Lifecycle hook called after state update and before rendering.
*   `events()`: Returns an object mapping event selectors to handler methods (e.g., `{ 'click button': 'handleClick' }`).
*   `registerCleanup(cleanupFn)`: Registers a function to be called on `unmount`.
*   `setTimeout(callback, delay)`: Wrapper for `setTimeout` with automatic cleanup.
*   `setInterval(callback, delay)`: Wrapper for `setInterval` with automatic cleanup.
*   `subscribe(eventName, callback)`: Subscribes to an `EventBus` event with automatic cleanup.
*   `subscribeOnce(eventName, callback)`: Subscribes to an `EventBus` event once with automatic cleanup.
*   `useStore(store, selector, onUpdate)`: Hook to subscribe to external store state changes.
*   `provideContext(key, value)`: Provides a context value to child components.
*   `getContext(key)`: Retrieves a context value from the component tree.

### `EventBus`

A simple global event bus for inter-component communication. Access via `import { eventBus } from 'microact';`

*   `eventBus.on(eventName, callback)`: Subscribe to an event.
*   `eventBus.off(eventName, callback)`: Unsubscribe from an event.
*   `eventBus.emit(eventName, data)`: Emit an event.
*   `eventBus.once(eventName, callback)`: Subscribe to an event once.

## Development

To build the project:

```bash
npm install
npm run build
```

The build output will be in the `dist/` directory.

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## License

This project is licensed under the MIT License.