@sidiousvic/phantom

Phantom

A state—reactive DOM rendering engine for building UIs. 👻

npm i @sidiousvic/phantom

Phantom lets you build state—reactive UIs using raw HTML strings ejected from functions.

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

You update state via actions, and Phantom swaps DOM nodes for you.

phantomStore.fire({ type: "EAT_PIZZA" });

🚀 Get launched

🍕 Manage state

❓ FAQ

🔧 Developers

👻 Examples

🚀 Get launched

1. Create a Phantom store

Phantom will integrate with a Redux—like store to subscribe DOM rendering to state updates. Use createPhantomStore to produce your store.

Show code ↯

import { createPhantomStore } from "@sidiousvic/phantom";

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 = createPhantomStore(reducer);

export default phantomStore;

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 recommend the leet-html VSCode extension for HTML template highlighting.

Show code ↯

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

3. Initialize Phantom and appear()

Start the Phantom engine with the phantomStore and a phantomElement.

Show code ↯

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

const { fire, data, appear } = phantom(phantomStore, phantomComponent);

appear(); // 3, 2, 1... 🚀 initial render!

Phantom will then expose the methods fire, data and appear.

fire and data are pointers to the phantomStore. You're welcome to call them from the store directly.

fire takes an action and fires it through the store.

data returns the current in—store data.

appear will perform the initial DOM render on call, your UI's first apparition. 👻

🍕 Manage state

Use data to read state from the Phantom 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 dispatch 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" });
  }
}

❓ FAQ

Why use Phantom ?

A baby panda dies every time you choose a 1MB+* industrial—level frontend package to code a pomodoro clock 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 a 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 practical, 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 easily identify it visually in the DOM tree.

II. id is one of the mechanisms that the Phantom engine uses to detect which nodes to update.

Is Phantom XSS secure?

Show answer ↯

Yes. Phantom uses its internal phantomExorciser to sanitize HTML strings before injecting them into the DOM.

🔧 Developers

Phantom is written and built using Typescript.

Scripts

• npm run build
  generates a static build in dist/ .

• npm run test
  runs the tests located in spec.

• npm run example/<example-name>
  runs an example app from examples/

If you find a 🐞, please file an issue.

Contributing

Phantom is maintained by @sidiousvic. He is always happy to welcome eager contributors to the project.

Contribution Guidelines

👻 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

Changelog

[v2.1.0] — 2020.07.20

• [x] Using rollup for builds
• [x] Package exports type definitions
• [x] Added tsc types test