@sidiousvic/phantom - npm Package Compare versions

Comparing version 2.1.2 to 2.1.4

CHANGELOG.md

@@ -9,2 +9,9 @@ # Changelog
 
+<!-- ## [v0.0.0] — y.m.d
+[v0.0.0]: https://github.com/sidiousvic/phantom/compare/vz.z.z...v0.0.0 -->
+
+## [v2.1.4] — 2020.07.21
+
+- [x] Updated README.
+
 ## [v2.1.2] — 2020.07.21
@@ -16,8 +23,8 @@
 
-- [x] Fixed exporting/importing bug.
+- [x] Fixed exporting/importing bug
 
 ## [v2.1.0] — 2020.07.20
 
-- [x] Using `rollup` for builds.
-- [x] Package exports type definitions.
+- [x] Using `rollup` for builds
+- [x] Package exports type definitions
 - [x] [Added tsc types test](./spec/types.test.ts)
@@ -41,3 +48,3 @@
 
-- [x] Replaced Webpack for build, building with Typescript.
+- [x] Replaced Webpack for build, building with Typescript
 
@@ -48,5 +55,5 @@ ## [v1.6.0] — 2020.07.11
 
-- [x] Danger JS for automated PR messaging.
-- [x] Kermitoid is implemented, and will respond to certain PR events. 🐸
-- [x] Added `CHANGELOG.md`.
+- [x] Danger JS for automated PR messaging
+- [x] Kermitoid is implemented, and will respond to certain PR events 🐸
+- [x] Added `CHANGELOG.md`
 
@@ -70,5 +77,6 @@ ## [v1.4.94] — 2020.07.08
 
-- [x] In `phantom.ts` instances of `innerHTML` injection were reinforced with the sanitizer. HMTL is now sanitized before rendering to DOM.
+- [x] In `phantom.ts` instances of `innerHTML` injection were reinforced with the sanitizer. HMTL is now sanitized before rendering to DOM
 
 [unreleased]: https://github.com/sidiousvic/phantom/compare/v2.1.2...HEAD
+[v2.1.4]: https://github.com/sidiousvic/phantom/compare/v2.1.2...v2.1.4
 [v2.1.2]: https://github.com/sidiousvic/phantom/compare/v2.1.1...v2.1.2
@@ -83,3 +91,2 @@ [v2.1.1]: https://github.com/sidiousvic/phantom/compare/v2.1.0...v2.1.1
 
-<sub>The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).</sub>
+<sub>This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).</sub>

package.json

 {
   "name": "@sidiousvic/phantom",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "A state—reactive DOM rendering engine for building UIs. 👻",
@@ -5,0 +5,0 @@ "main": "lib/phantom.js",

README.md

@@ -33,3 +33,3 @@ # **Phantom**
 
-### 🍕 [Manage state](#manage-state)
+### 🍕 [Data management](#data-management)
 
@@ -44,22 +44,19 @@ ### ❓ [FAQ](#faq)
 
-# 🚀 <a name="get-launched">Get launched</a>
+# 💥 <a name="get-launched">Get launched</a>
 
 ### 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.
-
 <details>
 <summary><b>Show code ↯</b></summary>
 
+Use `createPhantomStore` to produce your store.
+
 ```js
 import { createPhantomStore } from "@sidiousvic/phantom";
 
-const data = {
-  slices: ["🍕", "🍕", "🍕"],
-};
+const data = { slices: ["🍕", "🍕", "🍕"] };
 
 function reducer(state = data, action) {
   switch (action.type) {
-    case "EAT_SLICE":
-      // remove a slice from array
+    case "EAT_SLICE": // remove a slice from array
       return { ...state, slices: state.slices.slice(0, -1) };
@@ -71,3 +68,3 @@ default:
 
-const store = createPhantomStore(reducer);
+const phantomStore = createPhantomStore(reducer);
 
@@ -81,17 +78,23 @@ export default phantomStore;
 
-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`](https://marketplace.visualstudio.com/items?itemName=EldarGerfanov.leet-html) VSCode extension for HTML template highlighting.
-
 <details>
 <summary><b>Show code ↯</b></summary>
 
+Phantom components are functions that return HTML template strings. This allows you to inject dynamic data (including other components) via template literal placeholders `${}`.
+
 ```js
-function phantomComponent() {
+export default function phantomComponent() {
+  const slices
   return `
-    ${Pizza()} // inject the Pizza component from above
+    <div id="pizza-box">
+      <h1 id="slices-h1">🍕</h1>
+    </div>
   `;
 }
+
 ```
 
+| 👻 &nbsp; We recommend the [`leet-html` VSCode extension](https://marketplace.visualstudio.com/items?itemName=EldarGerfanov.leet-html) for HTML string highlighting. |
+| :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+
+
 </details>
@@ -101,4 +104,33 @@
 
-Start the Phantom engine with the `phantomStore` and a `phantomElement`.
+<details>
+<summary><b>Show code ↯</b></summary>
 
+Start the Phantom engine by feeding it a component and a store.
+
+```js
+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 then expose the `appear` method. 💥
+
+`appear` will perform the initial DOM render on call, your UI's first _apparition_. 👻
+
+</details>
+
+<br>
+
+# 🍕 <a name="data-management">Data management</a>
+
+Templating is cool and all, but what if we want to inject dynamic data to our components? 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.
+
 <details>
@@ -109,6 +141,6 @@ <summary><b>Show code ↯</b></summary>
 import phantom from "@sidiousvic/phantom";
+import phantomComponent from "./phantomComponent.js";
 import phantomStore from "./phantomStore.js";
-import Pizza from "./ui/Pizza.js";
 
-const { fire, data, appear } = phantom(phantomStore, phantomComponent);
+const { appear, fire, data } = phantom(phantomComponent, phantomStore);
 
@@ -118,6 +150,4 @@ appear(); // 3, 2, 1... 🚀 initial render!
 
-Phantom will then expose the methods `fire`, `data` and `appear`.
+`fire` and `data` are pointers to the phantom store. You're welcome to call them from the store directly.
 
-`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.
@@ -127,12 +157,9 @@
 
-`appear` will perform the initial DOM render on call, your UI's first _apparition_. 👻
-
 </details>
 
-<br>
+### 2. Use `data` to read state from the Phantom store.
 
-# 🍕 <a name="manage-state">Manage state</a>
+<details>
+<summary><b>Show code ↯</b></summary>
 
-### Use `data` to read state from the Phantom store.
-
 ```js
@@ -147,4 +174,11 @@ function phantomComponent() {
 
-### Pass data as arguments to components, and use them in your HTML templating.
+</details>
 
+### 3. Inject data into your component using template literals.
+
+<details>
+<summary><b>Show code ↯</b></summary>
+
+You can use [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) placeholders to inject pieces of state into a component.
+
 ```js
@@ -160,13 +194,38 @@ export default function Pizza(slices) {
 
-| ⚠️ &nbsp; Always bind _stateful_ elements with the `data-phantom` attribute. |
-| :--------------------------------------------------------------------------- |
+</details>
 
+### 4. Subscribe a component to data changes
 
-| ⚠️ &nbsp; Specify an id attribute for _all_ elements. |
-| :---------------------------------------------------- |
+<details>
+<summary><b>Show code ↯</b></summary>
 
+Phantom can perform DOM differentiation and swap only the nodes whose state has updated. To activate this behavior,
 
-### Use `fire` to dispatch an action and trigger a state update + re—render.
+- [x] Include a `data-phantom` attribute with the piece(s) of state that you want to subscribe to.
+- [x] An id attribute.
 
 ```js
+return `<element data-phantom="${your - data}">${your - data}</element>`;
+```
+
+| ⚠️ &nbsp; If you don't do this, Phantom will repaint the entire DOM tree on data updates 👻 |
+| :------------------------------------------------------------------------------------------ |
+
+
+Phantom will look at at both the `data-phantom` and `id` attributes in order to compute if a DOM node has to be repainted.
+
+</details>
+
+### 5. Use `fire` to dispatch an action and trigger a state update and rerender.
+
+<details>
+<summary><b>Show code ↯</b></summary>
+
+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)`**.
+
+```js
 document.addEventListener("click", eatPizza);
@@ -176,3 +235,3 @@
   if (e.target.id === "slices-h1") {
-    fire({ type: "EAT_PIZZA" });
+    fire({ type: "EAT_PIZZA" }); // DOM will update
   }
@@ -182,2 +241,4 @@ }
 
+</details>
+
 <br>
@@ -189,3 +250,3 @@
 
-#### A baby panda dies every time you choose a 1MB+\* industrial—level frontend package to code a pomodoro clock or a personal portfolio page. 🐼
+#### A baby panda dies every time you choose a 1MB+\* industrial—level frontend framework to code a pomodoro clock or a personal portfolio page. 🐼
 
@@ -201,2 +262,4 @@ <details>
 
+No JSX, no complex API, no syntactic hyperglycemia.
+
 #### 🍕 Component—based
@@ -210,7 +273,7 @@
 
-#### 👩🏾‍🏭 Closer to the JS _metal_
+#### 👩🏾‍🏭 Closer to the DOM _metal_
 
-Phantom only helps with DOM rendering. Listeners, effects, style manipulation, routing—the _fun_ stuff—is still in your hands. 🙌🏼
+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.
 
-No JSX, no complex API, no syntactic hyperglycemia.
+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.
 
@@ -230,24 +293,2 @@ <sub>\* unpacked size of ReactDOM is 3MB. Vue is 2.98MB. **Phantom is < 99 kB.**</sub>
 
-### Why should I always include the `data-phantom` attribute in stateful elements?
-
-<details>
-<summary><b>Show answer ↯</b></summary>
-
-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.
-
-</details>
-
-### Why should I always include an `id` attribute in stateful elements?
-
-<details>
-<summary><b>Show answer ↯</b></summary>
-
-Two reasons, one practical, one technical:
-
-**I.** Once you get into the habit, specifying `id`s 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.
-
-</details>
-
 ### Is Phantom XSS secure?
@@ -268,3 +309,3 @@
 
-## Scripts
+## ⌨️ Scripts
 
@@ -282,8 +323,14 @@ - [x] **`npm run build`**
 
-## Contributing
+## 👩🏽‍🔧 Contributing
 
-Phantom is maintained by [@sidiousvic](https://github.com/sidiousvic). He is always happy to welcome eager contributors to the project.
+We are always psyched to welcome contributors to Phantom.
 
-#### [Contribution Guidelines](./CONTRIBUTING.md)
+Feel free to **[raise issues](https://github.com/sidiousvic/phantom/issues)**, **[ask questions](mailto:[e-mail])** or fork the project and play with it.
 
+If you want to submit a contribution, please read our
+
+#### 👷🏽‍♂️ [Contribution Guidelines](./CONTRIBUTING.md)
+
+Phantom is maintained regularly by [@sidiousvic](https://github.com/sidiousvic) and [@nayelyrodarte](https://github.com/nayelyrodarte).
+
 <br>
@@ -305,2 +352,4 @@
 
-### <img src="https://media.giphy.com/media/jjBmeA29nxCrm/giphy.gif" width="40px"> Phantom is made with love and pepperoni by [@sidiousvic](https://www.github.com/sidiousvic)
+### <img src="https://media.giphy.com/media/jjBmeA29nxCrm/giphy.gif" width="40px"> Phantom is built with love and pepperoni by [@sidiousvic](https://www.github.com/sidiousvic)
+
+[![ko-fi](https://www.ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/T6T81Y1BK)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

96905

increased by1.85%

Number of lines in readme file

337

increased by17.01%

No dependency changes