@sidiousvic/phantom

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

👻 Examples

🚀 Get launched

1. Create a Redux Store

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

Install Redux  npm i redux

Show code ↯

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.

Show code ↯

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.

Show code ↯

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

Phantom will expose three key methods: fire, data, and launch.

fire and data are only syntactic pointers to the reduxStore's dispatch and getState methods respectively. You are welcome to avoid them and call the store directly for action dispatching and state getting.

launch will perform the initial DOM render on call.

🍕 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>
  `;
}

⚠️   Always bind stateful elements with the data-phantom attribute.

⚠️   Specify an id attribute for all elements.

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. 🐼

Show rationale ↯

You don't drive to the corner store, but walking is overrated. Phantom is the bike you need.

🖍 Declarative

With Phantom, you can write markup in a declarative way ala JSX using raw HTML strings, and inject dynamic data using template literals—staying fully JS native.

🍕 Component—based

Phantom lets you divide your UI into components, abstracting markup into composable functions.

🧪 Reactive

The Phantom engine integrates with your Redux store and subscribes to state updates. It swaps nodes when their data changes.

👩🏾‍🏭 Closer to the JS metal

Phantom only helps with DOM rendering. Listeners, effects, style manipulation, routing—the fun stuff—is still in your hands. 🙌🏼

No JSX, no complex API, no syntactic hyperglycemia.

_{* unpacked size of ReactDOM is 3MB. Vue is 2.98MB. Phantom is < 99 kB.}

Does Phantom use a virtual DOM?

Show answer ↯

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?

Show answer ↯

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?

Show answer ↯

Two reasons, one philosophical, one technical:

I. 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.

II. 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

1. Read the Code of Conduct
2. Fork the repo on GitHub
3. Clone the project to your machine
4. Install dependencies with npm i
5. Commit updates to your own branch
6. Push your work to your fork
7. 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.

If you find a 🐞, please file an issue.

👻 Examples

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

Phantom in CodeSandbox

Click on one of the images above to be taken to an online sandbox.

Devs who have cloned Phantom may use npm run example/[example name] and navigate to the url that appears in their terminal.

Phantom is made with love and pepperoni by @sidiousvic