Skip to content

Latest commit

 

History

History
361 lines (218 loc) · 9.88 KB

README.md

File metadata and controls

361 lines (218 loc) · 9.88 KB
Raw

Phantom

npm version install size

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

🍕 Data management

❓ FAQ

🔧 Developers

👻 Examples


💥 Get launched

1. Write an entry Phantom component

In Phantom, components are functions that return HTML template literals.

Show code ↯

Template strings allow you to inject dynamic data (including other components) via template literal placeholders ${}.

export default function phantomComponent() {
  const slices
  return `
    <div id="pizza-box">
      <h1 id="slices-h1">🍕</h1>
    </div>
  `;
}

👻   We recommend the leet-html VSCode extension for HTML string highlighting.

2. Create a Phantom store

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

export default phantomStore;

3. Initialize Phantom and appear()

Start the Phantom engine by feeding it a component and a store.

Show code ↯ 
import phantom from "@sidiousvic/phantom";
import phantomComponent from "./phantomComponent.js";
import phantomStore from "./phantomStore.js";

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

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

Phantom will expose the appear method. 💥

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


🍕 Data management

Components are cool and all, but what if we want to use dynamic data?

What if we want our UI to react to data changes?

Phantom integrates with a Redux—like store to subscribe the DOM to state updates.

1. Initialize Phantom.

Show code ↯

Pass Phantom a component and a store.

import phantom from "@sidiousvic/phantom";
import phantomComponent from "./phantomComponent.js";
import phantomStore from "./phantomStore.js";

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

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

Besides appear, Phantom exposes two more handy methods, data and fire.

We can use them to retrieve and update data from the Phantom store.

2. Use data to read state from the Phantom store.

Show code ↯

data returns the current in—store data.

const { slices } = data(); // where data = { slices: ["🍕","🍕","🍕"] }

Data can be passed as arguments to child components.

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

You can use template literal placeholders to inject pieces of state into a component.

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

3. Use fire to dispatch an action and trigger a state update and rerender.

Show code ↯

An action is an object with a type key and optional data payload.

fire takes an action and dispatches it to the phantomStore, triggering a state change.

Phantom will update the DOM on every fire(action).

document.addEventListener("click", eatPizza);

function eatPizza(e) {
  if (e.target.id === "slices-h1") {
    fire({ type: "EAT_PIZZA" }); // DOM will update
  }
}

4. Subscribe a component to data changes

Show code ↯

Phantom can perform DOM differentiation and swap only the nodes whose state has updated. To activate this behavior,

return `<element data-phantom="${yourData}">${yourData}</element>`;
  • Include a data-phantom attribute with the piece(s) of state that you want to subscribe to.
  • An id attribute.

Phantom will look at at both the data-phantom and id attributes in order to compute if a DOM node has to be repainted.

⚠️   If you don't do this, Phantom will repaint the entire DOM on data updates.

❓ FAQ

Why use Phantom ?

A baby panda dies every time you choose a 1MB+* industrial—level frontend framework 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.

No JSX, no complex API, no syntactic hyperglycemia.

🍕 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 DOM metal

Frameworks often abstract too much architecture and functionality out of the DOM. They make you yield too much to their way of doing things—events, effects, styling, routing—you have to find the solutions withing their ecosystem.

Phantom only helps with DOM rendering. It's convenient, but close enough to the DOM that you can integrate it with other solutions without using fibers, combiners or adapters of any kind.

* 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 an internal PhantomDOM, a map representation of the DOM.

Is Phantom XSS secure?

Show answer ↯

Yes. Phantom uses the 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

We are always psyched to welcome contributors to Phantom.

Feel free to raise issues, ask questions or fork the project and play with it.

If you want to submit a contribution, please read our

👷🏽‍♂️ Contribution Guidelines

Phantom is maintained regularly by @sidiousvic and @nayelyrodarte.


👻 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 built with love and pepperoni by @sidiousvic


ko-fi