phantom

A Redux powered, state—reactive DOM rendering engine. 👻

npm i @sidiousvic/phantom

phantom lets you build state—reactive UIs using raw HTML in functional components.

export default function Pizza(slices) {
  return `
    <div id="pizza-box">
      <h1 data-phantom="${slices}" id="slices-h1">${slices}</h1>
    </div>
  `;
}

You update data via Redux, and phantom swaps DOM nodes for you.

🚀 Get launched

🍕 Manage state

❓ FAQ

🔧 Developers

🚀 Get launched

1. Create a Redux Store

phantom will couple with Redux to subscribe DOM rendering to state updates.

Install Redux  npm i redux

import { createStore } from "redux";

const data = {
  slices: ["🍕", "🍕", "🍕"],
};

function reducer(state = data, action) {
  switch (action.type) {
    case "EAT_SLICE":
      // remove a slice from array
      return { ...state, slices: state.slices.slice(0, -1) };
    default:
      return state;
  }
}

const store = createStore(reducer);

export default reduxStore;

2. Write an entry phantom component

phantom components are functions that return HTML template strings. This allows you to inject dynamic data (including other components) via template literals ${}.

We leet-html extension for VSCode is recommended for HTML template highlighting.

function phantomComponent() {
  return `
    ${Pizza()} // inject the Pizza component from above
  `;
}

3. Initialize and phantom.launch()

Start the phantom engine with the reduxStore and a phantomElement.

import phantom from "@sidiousvic/phantom";
import reduxStore from "./reduxStore.js";
import Pizza from "./ui/Pizza.js";

export const { fire, data, launch } = phantom(reduxStore, phantomComponent);

launch(); // initial render

🍕 Manage state

Use data() to read state from the Redux store.

function phantomComponent() {
  const { slices } = data();
  return `
    ${Pizza(slices)}
  `;
}

Pass data as arguments to components, and use them in your HTML templating.

export default function Pizza(slices) {
  return `
    <div id="pizza-box">
      <h1 data-phantom="${slices}" id="slices-h1">${slices}</h1>
    </div>
  `;
}

Use fire() to fire an action and trigger a state update + re—render.

document.addEventListener("click", eatPizza);

function eatPizza(e) {
  if (e.target.id === "slices-h1") {
    fire({ type: "EAT_PIZZA" }); // fire an action to the store
  }
}

❓ FAQ

Why use phantom ?

A baby panda dies every time you choose a 1MB+* industrial—level frontend framework to code a pomodoro or a personal portfolio page. 🐼

Does phantom use a virtual DOM?

When a component's data changes, phantom will re—render that node in the DOM by diffing its internal PseudoDOM, an object representation of the DOM.

Why should I always include the data-phantom attribute in stateful elements?

In order for your element to be reactive to data changes, phantom needs to know which nodes are bound to the updated data. Specifying a data-phantom="${yourData}" attribute is a simple way to do that.

Why should I always include an id attribute in stateful elements?

Two reasons, one philosophical, one technical:

1. Once you get into the habit, specifying ids results in remarkably declarative markup. It encourages you to think about each element's specific function in the UI and also helps to identify it visually.

2. id is one of the mechanisms that the phantom engine uses to detect which nodes to update.

🔧 Developers

phantom is written in TypeScript and bundled using Webpack.

Instructions

0. Read the Code of Conduct
1. Fork the repo on GitHub
2. Clone the project to your machine
3. Install dependencies with npm i
4. Commit updates to your own branch
5. Push your work to your fork
6. Pull request for your changes to be reviewed

Scripts

npm run build generates a static build in dist/ .

npm run test runs the tests located in __tests__/.

npm run example/[example name] runs an example app from examples/ via webpack-dev-server.

Examples

There are several examples you can run, each furnished with their own devServer configuration.

Use npm run example/[example name] and navigate to the url that appears in your terminal.

If you find a 🐞, please file an issue.