picoapp

picoapp uses a shared state model. You can define initial state when creating the app instance, and components interact with this state via the ctx (context) object.

Initializing State

Pass a state object as the second argument to the picoapp constructor:

const app = picoapp({ button }, { count: 0 });

Consuming State

Use ctx.getState() inside a component to access the current state:

export default component((node, ctx) => {
  const count = ctx.getState().count;
});

Updating State via Events

To update state, use ctx.emit(eventName, payload).

• If the payload is an object, it is merged into the global state.
• If the payload is a function, it receives the current state and should return the new state object.

// Emitting an object (merges into state)
ctx.emit("increment", { count: ctx.getState().count + 1 });

// Emitting a function (uses previous state)
ctx.emit("increment", state => {
  return { count: state.count + 1 };
});

Listening to Events

Use ctx.on(eventName, callback) to react to state changes. The callback receives the entire state object.

Subscription patterns:

• Multi-subscribe: ctx.on(["prop1", "prop2"], state => {})
• Wildcard: ctx.on("*", state => {}) (fires on all updates)
• Property keyed: ctx.on("someProp", ({ someProp }) => {}) (fires when someProp updates)

Updating State without Events

Use ctx.hydrate(newState) to update the state directly without triggering an event.

ctx.hydrate({ count: 12 });

export default component((node, ctx) => {
  ctx.on("increment", state => {
    node.innerHTML = `I've been clicked ${state.count} times`;
  });

  node.onclick = () => {
    ctx.emit("increment", { count: ctx.getState().count + 1 });
  };
});

When using AJAX page transitions (like PJAX), you may need to destroy components to prevent memory leaks or stale event listeners.

1. Define a cleanup function: Return a function from your component definition. This function is called when the component is unmounted.
2. Call unmount: Call app.unmount() on your picoapp instance.

Note: All evx event subscriptions within a component are automatically destroyed when the component is unmounted. If a component does not return a cleanup function, it will remain mounted even after app.unmount() is called (useful for persistent elements like global navigation).

Example:

import { component } from "picoapp";

export default component((node, ctx) => {
  function handler(e) { /* ... */ }
  node.addEventListener("click", handler);

  // Return the cleanup function
  return node => {
    node.removeEventListener("click", handler);
  };
});

// Trigger unmounting
app.unmount();

// In your component
export default component((node, ctx) => {
  // ... setup logic ...
  return node => {
    // ... cleanup logic ...
  };
});

// In your app controller
app.unmount();

picoapp automatically instantiates JavaScript modules on specific DOM elements if they exist on the page.

1. Define data attributes: Add a data-component attribute to your HTML nodes.
2. Create a component: Use the component function from picoapp. The function receives the node and a ctx (context) object.
3. Initialize the app: Import your components and create a picoapp instance.
4. Mount: Call app.mount() to bind the components to the DOM.

Example:

HTML

<button data-component="button">I've been clicked 0 times</button>

JavaScript (button.js)

import { component } from "picoapp";

export default component((node, ctx) => {
  let count = 0;

  node.onclick = () => {
    node.innerHTML = `I've been clicked ${++count} times`;
  };
});

JavaScript (main.js)

import { picoapp } from "picoapp";
import button from "./button.js";

const app = picoapp({ button });
app.mount();

The picoapp instance provides several methods to manage the application globally.

Protected Events:

• mount: Fired after all components have mounted.
• unmount: Fired after all unmountable components have unmounted.
• error: Fired if a component throws an error.

Error Handling Example:

app.on("error", ({ error }) => {
  // handle error
});

Use the component function to wrap a factory function that initializes a module. The factory function receives a node (the DOM element) and a ctx (the context containing state, events, and plugins).

To ensure proper cleanup, the component should return an object containing an unmount function and a subs array. The subs array should store the return values of any event subscriptions made via ctx.on to allow the application to clean them up automatically during unmounting.

import { component } from 'picoapp'

export const myComponent = component((node, ctx) => {
  // ctx contains getState, emit, on, etc.
  const subs = []

  // Use ctx.on to subscribe to events
  const unsubscribe = ctx.on('some-event', () => {
    console.log('Event received on', node)
  })
  subs.push(unsubscribe)

  return {
    subs,
    unmount: (node) => {
      console.log('Cleaning up component on', node)
    }
  }
})

The mount(attrs) method scans the DOM for elements containing specific attributes and initializes the corresponding components.

Arguments:

• attrs (String|Array): The attribute used to identify component nodes. Defaults to 'data-component'. You can pass a single string or an array of strings.

Behavior:

1. It finds all elements with the specified attribute(s).
2. It reads the attribute value, which should be a space-separated list of component names (e.g., data-component="comp1 comp2").
3. It executes the component factory, passing the DOM node and the application context (state, events, and plugins).
4. It emits a 'mount' event once all nodes are processed.
5. It removes the attribute from the node after mounting to prevent double-binding.

/* HTML */
// <div data-component="myComponent"></div>

/* JavaScript */
const app = picoapp({ myComponent }, { count: 0 })
app.mount() // Mounts components found in [data-component]

// Or with a custom attribute
// <div data-app="myComponent"></div>
app.mount('data-app')