veles 0.0.7 → 0.0.9

package/README.md

@@ -4,7 +4,7 @@
 [![Build Size](https://img.shields.io/bundlephobia/minzip/veles?label=bundle%20size)](https://bundlephobia.com/result?p=veles)
 [![Version](https://img.shields.io/npm/v/veles)](https://www.npmjs.com/package/veles)
 
-> The library is in very early stages and some features, like proper TypeScript support, are not fully implemented yet
+> This library is still in early stages, so the API is not 100% finalized
 
 `Veles` is a component-based performance-focused UI library. The main goal of this library is to provide a composable way to build highly interactive interfaces, which should be performant out of the box, as long as you follow the recommendations.
 
@@ -12,272 +12,50 @@
 
 This library's primary focus is in performance. What this means is that it allows you to write your code in a way which will ensure that when the data in your app changes, only the smallest relevant parts will update. Despite of similarities with React in syntax, it does not follow the same waterfall style for component re-renders. Instead, it gives you API to subscribe to atomic changes in your tracked state and re-render only parts of the UI which actually depend on the value. Internally, it renders new HTML and replaces the old node. A similar approach is done for attributes, where in case of changes, only the relevant attribute will be updated in place, but nothing else will change.
 
-It is important to note that the performance benefits will only be observed (and relevant as well) in case of a pretty high interactivity. It might not be faster than any other UI framework on the first render, the biggest improvement lies in the power of subscribing to individual changes.
+It is important to note that the performance benefits will only be observed (and relevant as well) in case of a pretty high interactivity. It might not be faster than any other UI framework on the first render, the biggest improvement lies in the power of subscribing to individual changes, which is especially powerful in case of lists.
 
-## API
+## Installation
 
-### AttachComponent
+The library is available on npm. To add it to your project, execute this in your project folder:
 
-Attach Veles tree to a regular DOM Node.
-
-> [!NOTE]
-> As of right now, this method will wrap the component's HTML into one additional `div`. This will probably go away in the future, but for now it simplifies some things significantly.
-
-```js
-import { attachComponent } from "veles";
-
-const App () => <div>App</div>
-
-const appContainer = document.getElementById("app");
-attachComponent({ htmlElement: appContainer, component: <App /> });
-```
-
-### JSX support
-
-Veles supports JSX transformation, so as long as you specify `importSource: "veles"` (this is for Babel, the other JS transpilers should have similar options) it will work as expected.
-
-```jsx
-function App() {
-  return (
-    <div class="app-container">
-      <h1>Veles App</h1>
-      <p>Random description</p>
-    </div>
-  );
-}
-```
-
-### createState
-
-`createState` is the API which is responsible for the interactivity in Veles applications, and it is the only one. You can either pass the initial value and then update it manually in callbacks or some other subscriptions, or you can pass a function as the second argument and you can subscribe to any external data store and update the state reacting to it.
-
-`createState` returns an object with a variety of subscription methods. It is important to understand that just creating the state object does not affect the component at all. When the state value updates, only the components which are rendered by these subscription methods will update, but the component where the state was created is not affected.
-
-The simplest way to react to state changes in the UI is to use `useValue` method from the state object. Let's build a simple counter to demonstrate:
-
-```jsx
-import { createState } from "veles";
-
-function Counter() {
-  const counterState = createState(0);
-  const increment = () =>
-    counterState.setValue((currentValue) => currentValue + 1);
-  const decrement = () =>
-    counterState.setValue((currentValue) => currentValue - 1);
-  return (
-    <div>
-      <h1>Counter</h1>
-      <div>
-        {counterState.useValue(
-          (counterValue) => `counter value is: ${counterValue}`
-        )}
-      </div>
-      <button onClick={increment}>+</button>
-      <button onClick={decrement}>-</button>
-    </div>
-  );
-}
-```
-
-### createState and partial subscriptions
-
-If you have an object in your store, even atomic updates will be wasteful. Let's say you have an object with several fields, but you are only interested in the `title` property. If you use `useValue`, it will do unnecessary work. To help with that, there is a `useValueSelector` state method, which accepts a selector function as the first parameter. Here is an example:
-
-```jsx
-import { createState } from "veles";
-
-function App() {
-  const taskState = createState({
-    id: 5,
-    title: "title",
-    description: "long description",
-  });
-  return (
-    <div>
-      <h1>App</h1>
-      <div>
-        {taskState.useSelectorValue(
-          (task) => task.title,
-          (title) => `task title: ${title}`
-        )}
-      </div>
-    </div>
-  );
-}
-```
-
-The component which listens for `title` will only be rendered again when the title changes.
-
-### createState and lists
-
-Lists performance is one of the cornerstones of this library, and to help with that, it provides a special state method `useValueIterator`. This method ensures that when the state changes, instead of re-rendering the whole list, it checks each list element individually, moves them into correct order without unnecessary re-renders, and in case of changes element data, it will update the passed state object, so that only subscribed parts will re-render.
-
-> [!NOTE]
-> the library determines the uniqueness by calculating the key. You can either pass a string which will be a property name, or you can pass a function which will be executed with the element and the index. If the result is different from any previous calculations, it treats it as a new component.
-
-Let's build a simple list component:
-
-```jsx
-import { createState } from "veles";
-
-function List() {
-  const listState = createState([
-    { id: 1, name: "first task" },
-    { id: 2, name: "second task" },
-    { id: 3, name: "third task" },
-  ]);
-
-  return <div>
-    <h1>List</h1>
-    {listState.useValueIterator<{ id: number; name: string }>(
-        { key: "id" },
-        ({ elementState }) => <div>
-          {elementState.useValueSelector(
-            (element) => element.name,
-            (name) => <div>{name}</div>
-          )}
-        </div>
-      )}
-  </div>
-}
-```
-
-### createState and attributes
-
-In order to avoid unnecessary re-renders when you to change properties on a wrapper element/component, there is a special state method `useAttribute`. It allows to recalculate value for an attribute every time the state changes, but instead of re-rendering, it calls the `htmlNode.setAttribute` method. Here is an example:
-
-```jsx
-import { createState } from "veles";
-
-function Counter() {
-  const counterState = createState(0);
-  const increment = () =>
-    counterState.setValue((currentValue) => currentValue + 1);
-  return (
-    <div>
-      <h1>Counter</h1>
-      <div>{counterState.useValue((value) => `counter value is ${value}`)}</div>
-      <button
-        onClick={increment}
-        style={counterState.useAttribute(
-          (currentValue) => `width: ${50 + currentValue}px;`
-        )}
-      >
-        +
-      </button>
-    </div>
-  );
-}
+```sh
+npm install --save veles
 ```
 
-You can see that we dynamically change the width of the button with every press. This will be the only change, the rest of the application will not be re-rendered or any code will not be executed. You still need to be mindful what are you changing, as with some CSS changes you can force reflows/repaints and that can still cause some performance issues.
+Types are installed automatically with the same package.
 
-### createState and subscribing to updates
-
-What if you don't want to render anything when the value changes, but you want to call your code? The state provides `trackValue` method, which does exactly that. Here is an example:
+## A basic example
 
 ```jsx
 import { createState } from "veles";
 
-function Counter() {
-  const counterState = createState(0);
-
-  counterState.trackValue((counterValue) => {
-    console.log(`new counter value is ${counterValue}`);
-  });
-  const increment = () =>
-    counterState.setValue((currentValue) => currentValue + 1);
-  const decrement = () =>
-    counterState.setValue((currentValue) => currentValue - 1);
-
+function NameComponent() {
+  const nameState = createState("");
   return (
     <div>
-      <h1>Counter</h1>
-      <div>
-        {counterState.useValue(
-          (counterValue) => `counter value is: ${counterValue}`
-        )}
-      </div>
-      <button onClick={increment}>+</button>
-      <button onClick={decrement}>-</button>
+      <input
+        type="text"
+        name="name"
+        value={nameState.useAttribute()}
+        onInput={(e) => nameState.setValue(e.target.value)}
+      />
+      <p>{nameState.useValue()}</p>
     </div>
   );
 }
 ```
 
-This subscription will not cause any re-renders. By default, the first call will happen during the component initialization, and you can pass a second options object to alter this behaviour. You can either set `{ skipFirstCall: true }` to completely skip it, or you can specify to run it when the component is mounted in DOM: `{ callOnMount: true }`.
+This will render an input and will update the Text node dynamically, without re-rendering the whole component. For a more advanced example, please head to [the docs](https://bloomca.github.io/veles/#advanced-example).
 
-### Subscribing to partial updates
+### Resources
 
-In case you don't want to subscribe to the whole state, you have 2 options. You can either provide a `{ comparator: (prevValue, nextValue) => prevValue === nextValue }` property in the options object, or you can use `state.trackValueSelector()` method. You can also combine them, if you need that for some reason.
+- [Getting started](https://bloomca.github.io/veles/)
+- [API docs](https://bloomca.github.io/veles/api/)
+- [Guides](https://bloomca.github.io/veles/guides/)
+- [Differences from other frameworks](https://bloomca.github.io/veles/frameworks-difference.html)
 
-### Combining different states
+There also a companion app ([veles-calendar-app](https://github.com/Bloomca/veles-calendar-app)), which is developed using Veles and is supposed to push it to the limits, identify the issues and ideally improve performance even more.
 
-Since `createState` is the only way to add dynamic behaviour to the application, sooner or later you'll need to build UI which depends on several states. To do so, you can use `combineState` function which accepts any amount of state objects, and returns an array with all combined values in it.
-
-```jsx
-import { createState } from "veles";
+### Features
 
-function Counter() {
-  const firstcounterState = createState(0);
-  const secondCounterState = createState(0);
-  const combinedCounterState = combineState(
-    firstcounterState,
-    secondCounterState
-  );
-  const incrementFirstCounter = () =>
-    firstcounterState.setValue(
-      (currentCounterValue) => currentCounterValue + 1
-    );
-  const incrementSecondCounter = () =>
-    secondCounterState.setValue(
-      (currentCounterValue) => currentCounterValue + 1
-    );
-  return (
-    <div>
-      <h1>Counters</h1>
-      <div>
-        {firstcounterState.useValue(
-          (value) => `first counter value is: ${value}`
-        )}
-      </div>
-      <div>
-        {secondCounterState.useValue(
-          (value) => `second counter value is: ${value}`
-        )}
-      </div>
-      <div>
-        {combinedCounterState.useValueSelector(
-          ([firstValue, secondValue]) => firstValue + secondValue,
-          (counterValue) => `combined counter value is: ${counterValue}`
-        )}
-      </div>
-      <button onClick={incrementFirstCounter}>Increment first counter</button>
-      <button onClick={incrementSecondCounter}>Increment second counter</button>
-    </div>
-  );
-}
-```
-
-### Components lifecycle
-
-Right now there are `onMount` and `onUnmount` lifecycle hooks. In your component, just import and call them to add a callback.
-
-> [!NOTE]
-> You can only use them during the original initialization of the component. If you want to add some callbacks later, use the same version passed as a second argument to your component
-
-```jsx
-import { onMount, onUnmount } from "veles";
-
-function App(_props, componentAPI) {
-  // could be used as `componentAPI.onMount()`
-  onMount(() => {
-    console.log("called when the component mounts");
-  });
-  // could be used as `componentAPI.onUnmount()`
-  onUnmount(() => {
-    console.log("called when the component unmounts");
-  });
-  return <div>Application<div>
-}
-```
+The library is under development, so some features are not available yet. Namely the TypeScript type inferring is not the best (although the library does support TypeScript), and Portals are not implemented yet.

package/dist/{chunk-ILNLS6QO.js → chunk-2KPVWPOL.js}

@@ -24,56 +24,30 @@ function onUnmount(cb) {
   }
 }
 
-// src/_utils.ts
-function getComponentVelesNode(component) {
-  const componentsTree = [];
-  if ("velesStringElement" in component) {
-    return {
-      velesElementNode: component,
-      componentsTree: []
-    };
-  }
-  let childNode = component;
-  while ("velesComponent" in childNode) {
-    componentsTree.push(childNode);
-    if ("velesStringElement" in childNode.tree) {
-      return {
-        velesElementNode: childNode.tree,
-        componentsTree
-      };
-    } else {
-      childNode = childNode.tree;
+// src/create-element/create-text-element.ts
+function createTextElement(text) {
+  const mountHandlers = [];
+  const unmountHandlers = [];
+  return {
+    velesStringElement: true,
+    // in case there is no text, we create an empty Text node, so we still can
+    // have a reference to it, replace it, call lifecycle methods, etc
+    html: document.createTextNode(text || ""),
+    _privateMethods: {
+      _addMountHandler(cb) {
+        mountHandlers.push(cb);
+      },
+      _callMountHandlers() {
+        mountHandlers.forEach((cb) => cb());
+      },
+      _addUnmountHandler: (cb) => {
+        unmountHandlers.push(cb);
+      },
+      _callUnmountHandlers: () => {
+        unmountHandlers.forEach((cb) => cb());
+      }
     }
-  }
-  return { velesElementNode: childNode, componentsTree };
-}
-function callMountHandlers(component) {
-  if ("velesStringElement" in component) {
-    return;
-  }
-  if ("velesComponent" in component) {
-    component._privateMethods._callMountHandlers();
-    callMountHandlers(component.tree);
-  }
-  if ("velesNode" in component) {
-    component.childComponents.forEach(
-      (childComponent) => callMountHandlers(childComponent)
-    );
-  }
-}
-function identity(value1, value2) {
-  return value1 === value2;
-}
-function unique(arr) {
-  const map = /* @__PURE__ */ new Map();
-  const resultArr = [];
-  arr.forEach((element) => {
-    if (map.has(element))
-      return;
-    map.set(element, true);
-    resultArr.push(element);
-  });
-  return resultArr;
+  };
 }
 
 // src/create-element/parse-children.ts
@@ -86,30 +60,36 @@ function parseChildren({
   if (children === void 0 || children === null) {
     return childComponents;
   }
+  let lastInsertedNode = null;
   (Array.isArray(children) ? children : [children]).forEach(
     (childComponent) => {
       if (typeof childComponent === "string") {
-        const text = document.createTextNode(childComponent);
-        htmlElement.append(text);
+        const textNode = createTextElement(childComponent);
+        htmlElement.append(textNode.html);
+        lastInsertedNode = textNode.html;
+        childComponents.push(textNode);
       } else if (typeof childComponent === "number") {
-        const text = document.createTextNode(String(childComponent));
-        htmlElement.append(text);
+        const textNode = createTextElement(String(childComponent));
+        htmlElement.append(textNode.html);
+        lastInsertedNode = textNode.html;
+        childComponents.push(textNode);
       } else if (typeof childComponent === "object" && childComponent && "velesNode" in childComponent && (childComponent == null ? void 0 : childComponent.velesNode)) {
         if (childComponent.phantom) {
           childComponent.childComponents.forEach((childComponentofPhantom) => {
             if ("velesNode" in childComponentofPhantom) {
               htmlElement.append(childComponentofPhantom.html);
               childComponentofPhantom.parentVelesElement = velesNode;
-            } else {
-              const { velesElementNode } = getComponentVelesNode(
-                childComponentofPhantom
-              );
+              lastInsertedNode = childComponentofPhantom.html;
+            } else if ("velesStringElement" in childComponentofPhantom) {
+              const velesElementNode = childComponentofPhantom;
               if (!velesElementNode) {
                 console.error("can't find HTML tree in a component chain");
               } else {
                 htmlElement.append(velesElementNode.html);
+                lastInsertedNode = velesElementNode.html;
                 velesElementNode.parentVelesElement = velesNode;
               }
+            } else {
             }
           });
           childComponent.parentVelesElement = velesNode;
@@ -118,39 +98,18 @@ function parseChildren({
           htmlElement.append(childComponent.html);
           childComponent.parentVelesElement = velesNode;
           childComponents.push(childComponent);
+          lastInsertedNode = childComponent.html;
         }
-      } else if (typeof childComponent === "object" && childComponent && "velesComponent" in childComponent && (childComponent == null ? void 0 : childComponent.velesComponent)) {
-        const { componentsTree, velesElementNode } = getComponentVelesNode(childComponent);
-        if (!velesElementNode) {
-          console.error("can't find HTML tree in a component chain");
-        } else {
-          if ("velesNode" in velesElementNode && velesElementNode.phantom) {
-            velesElementNode.childComponents.forEach(
-              (childComponentofPhantom) => {
-                if ("velesNode" in childComponentofPhantom) {
-                  htmlElement.append(childComponentofPhantom.html);
-                  childComponentofPhantom.parentVelesElement = velesNode;
-                } else {
-                  const { componentsTree: componentsTree2, velesElementNode: velesElementNode2 } = getComponentVelesNode(childComponentofPhantom);
-                  if (!velesElementNode2) {
-                    console.error("can't find HTML tree in a component chain");
-                  } else {
-                    htmlElement.append(velesElementNode2.html);
-                    velesElementNode2.parentVelesElement = velesNode;
-                  }
-                }
-              }
-            );
-          } else {
-            htmlElement.append(velesElementNode.html);
-          }
-          velesElementNode.parentVelesElement = velesNode;
-          childComponents.push(childComponent);
-        }
+      } else if (typeof childComponent === "object" && childComponent && "velesComponentObject" in childComponent) {
+        childComponent.insertAfter = lastInsertedNode;
+        childComponent.parentVelesElement = velesNode;
+        childComponents.push(childComponent);
+        lastInsertedNode = childComponent;
       } else if (typeof childComponent === "object" && childComponent && "velesStringElement" in childComponent && (childComponent == null ? void 0 : childComponent.velesStringElement)) {
         htmlElement.append(childComponent.html);
         childComponent.parentVelesElement = velesNode;
         childComponents.push(childComponent);
+        lastInsertedNode = childComponent.html;
       }
     }
   );
@@ -167,28 +126,65 @@ function assignAttributes({
     const isFunction = typeof value === "function";
     if (isFunction && value.velesAttribute === true) {
       const attributeValue = value(htmlElement, key, velesNode);
-      htmlElement.setAttribute(key, attributeValue);
-    } else if (
-      // basically, any form of `on` handlers, like `onClick`, `onCopy`, etc
-      isFunction && key.length > 2 && key.startsWith("on")
-    ) {
-      htmlElement.addEventListener(
-        key[2].toLocaleLowerCase() + key.slice(3),
-        value
-      );
+      assignAttribute({ key, value: attributeValue, htmlElement });
     } else {
-      htmlElement.setAttribute(key, value);
+      assignAttribute({ key, value, htmlElement });
     }
   });
 }
+function assignAttribute({
+  key,
+  value,
+  htmlElement
+}) {
+  if (
+    // basically, any form of `on` handlers, like `onClick`, `onCopy`, etc
+    typeof value === "function" && key.startsWith("on")
+  ) {
+    htmlElement.addEventListener(key.slice(2).toLocaleLowerCase(), value);
+  } else {
+    if (typeof value === "boolean") {
+      if (value)
+        htmlElement.setAttribute(key, "");
+    } else {
+      htmlElement.setAttribute(key, value);
+    }
+  }
+}
 
 // src/create-element/parse-component.ts
 function parseComponent({
   element,
   props
 }) {
-  const componentUnmountCbs = [];
-  const componentMountCbs = [];
+  const mountCbs = [];
+  const unmountCbs = [];
+  return {
+    velesComponentObject: true,
+    element,
+    props,
+    _privateMethods: {
+      _addMountHandler(cb) {
+        mountCbs.push(cb);
+      },
+      _addUnmountHandler: (cb) => {
+        unmountCbs.push(cb);
+      },
+      _callMountHandlers: () => {
+        mountCbs.forEach((cb) => cb());
+      },
+      _callUnmountHandlers: () => {
+        unmountCbs.forEach((cb) => cb());
+      }
+    }
+  };
+}
+function executeComponent({
+  element,
+  props
+}) {
+  let componentUnmountCbs = [];
+  let componentMountCbs = [];
   const componentAPI = {
     onMount: (cb) => {
       componentMountCbs.push(cb);
@@ -199,17 +195,15 @@ function parseComponent({
   };
   addContext(componentAPI);
   const _componentTree = element(props, componentAPI);
-  const componentTree = typeof _componentTree === "string" || !_componentTree ? {
-    velesStringElement: true,
-    html: document.createTextNode(
-      typeof _componentTree === "string" ? _componentTree : ""
-    )
-  } : _componentTree;
+  const componentTree = typeof _componentTree === "string" || !_componentTree ? createTextElement(_componentTree) : _componentTree;
   popContext();
   const velesComponent = {
     velesComponent: true,
     tree: componentTree,
     _privateMethods: {
+      _addMountHandler(cb) {
+        componentMountCbs.push(cb);
+      },
       _addUnmountHandler: (cb) => {
         componentAPI.onUnmount(cb);
       },
@@ -223,9 +217,6 @@ function parseComponent({
       },
       _callUnmountHandlers: () => {
         componentUnmountCbs.forEach((cb) => cb());
-        if ("_privateMethods" in velesComponent.tree) {
-          velesComponent.tree._privateMethods._callUnmountHandlers();
-        }
       }
     }
   };
@@ -246,23 +237,25 @@ function createElement(element, props = {}) {
       htmlElement: newElement,
       velesNode
     });
-    let unmountHandlers = [];
-    const callUnmountHandlers = () => {
-      unmountHandlers.forEach((cb) => cb());
-      unmountHandlers = [];
-      childComponents.forEach((childComponent) => {
-        childComponent._privateMethods._callUnmountHandlers();
-      });
-    };
+    const unmountHandlers = [];
     velesNode.html = newElement;
     velesNode.velesNode = true;
     velesNode.childComponents = childComponents;
     velesNode.phantom = phantom;
+    const mountHandlers = [];
     velesNode._privateMethods = {
-      _addUnmountHandler: (cb) => {
+      _addMountHandler(cb) {
+        mountHandlers.push(cb);
+      },
+      _callMountHandlers() {
+        mountHandlers.forEach((cb) => cb());
+      },
+      _addUnmountHandler(cb) {
         unmountHandlers.push(cb);
       },
-      _callUnmountHandlers: callUnmountHandlers
+      _callUnmountHandlers() {
+        unmountHandlers.forEach((cb) => cb());
+      }
     };
     assignAttributes({ props: otherProps, htmlElement: newElement, velesNode });
     return velesNode;
@@ -274,12 +267,19 @@ function createElement(element, props = {}) {
   );
 }
 
+// src/fragment.ts
+function Fragment({ children }) {
+  return createElement("div", {
+    phantom: true,
+    children
+  });
+}
+
 export {
-  getComponentVelesNode,
-  callMountHandlers,
-  identity,
-  unique,
   onMount,
   onUnmount,
-  createElement
+  createTextElement,
+  executeComponent,
+  createElement,
+  Fragment
 };