diff --git a/docs/api/combine-state.md b/docs/api/combine-state.md new file mode 100644 index 0000000..8318b53 --- /dev/null +++ b/docs/api/combine-state.md @@ -0,0 +1,48 @@ +--- +layout: default +title: combineState +nav_order: 6 +parent: API +--- + +## combineState + +> Note: this function needs to be imported from `"veles/utils"` +> This function is also available as `combine` + +Sooner or later you'll run into a situation where you depend on several states. While in theory you can make a subscription inside another one and access both current values that way, you should not do that. Not only it is cumbersome to write, it is also not very flexible and can't be used with other states. + +To help with that, there is a `combineState` or `combine` function, which merges several states together for you. It accepts any number of states and creates a new state which will have an array with values from all passed states. + +```jsx +import { createState } from "veles"; +import { combineState } from "veles/utils"; + +function Component() { + const nameState = createState(""); + const lastNameState = createState(""); + const fullNameState = combineState(nameState, lastNameState); + + return ( +
+ nameState.setValue(e.target.value)} + value={nameState.useAttribute()} + /> + lastNameState.setValue(e.target.value)} + value={lastNameState.useAttribute()} + /> + {fullNameState.useValueSelector( + ([firstName, lastName]) => `Full name is ${firstName} ${lastName}` + )} +
+ ); +} +``` + +The advantage here is that we can combine several states, we can pass that state down as a prop to another components, we can use `trackValue` and do side-effects when either of them change. diff --git a/docs/api/create-element.md b/docs/api/create-element.md index d5432fd..9630228 100644 --- a/docs/api/create-element.md +++ b/docs/api/create-element.md @@ -61,5 +61,3 @@ function Component() { ); } ``` - -> `` cannot be returned directly from `useValue/useValueSelector` at the time diff --git a/docs/api/create-ref.md b/docs/api/create-ref.md new file mode 100644 index 0000000..2e6cbd3 --- /dev/null +++ b/docs/api/create-ref.md @@ -0,0 +1,30 @@ +--- +layout: default +title: createElement +nav_order: 5 +parent: API +--- + +## createRef + +Since components don't re-render, and the component's code is executed only one time when the component is being mounted, you probably don't need refs for anything except for more convenient access to DOM elements. Every element accepts `ref` and it will be assigned the correct HTML node at the time of execution. If you want to pass the ref down, there is no need for wrapping components into anything, just pass it as any other prop (`ref` on components is ignored and treated like any other property). + +```jsx +import { createRef } from "veles"; +function App() { + const inputRef = createRef(); + + return ( +
+ + +
+ ); +} +``` diff --git a/docs/api/select-state.md b/docs/api/select-state.md new file mode 100644 index 0000000..656e434 --- /dev/null +++ b/docs/api/select-state.md @@ -0,0 +1,47 @@ +--- +layout: default +title: selectState +nav_order: 7 +parent: API +--- + +## selectState + +> Note: this function needs to be imported from `"veles/utils"` +> This function is also available as `select` + +When working with multiple states, often by using [combineState](./combine-state.html), you end up with not the ideal state value representation. E.g. if you want to pass it down as a property to multiple component, you might want to avoid doing the same selector work on all of them, and want to do them at once. It becomes even more important if you want to combine that state with something else. + +To change the state value, you can use `selectState`/`select` functions. Here is an example: + +```jsx +import { createState } from "veles"; +import { combineState, selectState } from "veles/utils"; + +function Component() { + const nameState = createState(""); + const lastNameState = createState(""); + const fullNameState = selectState( + combineState(nameState, lastNameState), + ([firstName, lastName]) => `${firstName} ${lastName}` + ); + + return ( +
+ nameState.setValue(e.target.value)} + value={nameState.useAttribute()} + /> + lastNameState.setValue(e.target.value)} + value={lastNameState.useAttribute()} + /> + {fullNameState.useValue((fullName) => `Full name is ${fullName}`)} +
+ ); +} +``` diff --git a/docs/frameworks-difference.md b/docs/frameworks-difference.md index 5e3ded7..3056ddd 100644 --- a/docs/frameworks-difference.md +++ b/docs/frameworks-difference.md @@ -8,6 +8,25 @@ nav_order: 5 The main difference with other reactive based frameworks is that the tracking primitive (`createState` in Veles' case) allows for specific subscriptions, and that arrays are highly optimized and effectively will be rendered only one time, and all subsequent updates will only cause atomic changes in actual HTML. +Let's compare with a couple of popular libraries: + +### React + +Veles aims for a very similar composability as React provides, so the component approach should be pretty close, allowing for passing JSX down as props, logic reusability, etc. +Underneath there is a very big difference between these libraries. React re-renders components as soon as any of their internal states change, and then builds that into an internal presentation (Virtual DOM), and after comparing the existing and the new structure, applies updates to the changed components. + +Veles approaches updates differently. Instead of global component state updates, all changes are atomic, and updates are applied only to relevant subscriptions. There is also no diffing algorithm, meaning that in case there is a new state, all subscribers will re-execute their code. Because of that, there is no concept of re-rendering, components mount only one time. + +## Solidjs + +[Solidjs](https://www.solidjs.com/) is a very close library to Veles conceptually. It also has atomic updates, the state primitive (Signals) is close to `createState`, and component lifecycle is pretty much identical: the body is executed one time, and then there is `mount` and `cleanup` events. + +The implementation is slightly different. Solidjs tries to be more streamlined in its API, working as expected in most cases, but that comes with the expense that if you need a bit different approach, it might be a bit more cumbersome. By default Solidjs' Signal primitive does not allow for selector subscriptions; it does have a way to do so, but you need to use a different primitive for it. + +You need to use specific components for control flows in Solidjs (conditionals, arrays), and also array elements are non-dynamic, which can cause potential issues if you have nested array within arrays. + +Overall, with the correct approach, both libraries should give you good interactive performance. + ## Veles' drawbacks The library is pretty much in alpha state, and there are several missing concepts: diff --git a/docs/guides/index.md b/docs/guides/index.md deleted file mode 100644 index d556714..0000000 --- a/docs/guides/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: default -title: Guides -nav_order: 3 -has_children: true ---- - -# Guides - -This library provides a somewhat limited API with tools tailored for specific situations. As long as you follow them, you should get good interactive performance out of the box (the main goal of this library). diff --git a/docs/guides/working-with-multiple-states.md b/docs/guides/working-with-multiple-states.md deleted file mode 100644 index bffb59f..0000000 --- a/docs/guides/working-with-multiple-states.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: default -title: Working with multiple states -nav_order: 1 -parent: Guides ---- - -## `createState` primitive - -The only way to get reactivity in the Veles' application is to subscribe to `createState` primitives. You can pass the states around, and child components will be able to subscribe only to specific parts they are interested in; while it is great for performance, it means that sooner or later you'll have some parts of the application which depend on several states. - -Right now the library provides only one function (`combineStates`) to help with that, but it will be expanded in the future. While I was working on an application, I came up with this helper: - -```ts -function selectState( - state: State, - selector: (state: F) => T -): State { - const initialValue = selector(state.getValue()); - - const newState = createState(initialValue); - state.trackValueSelector( - selector, - (selectedState) => { - newState.setValue(selectedState); - }, - { skipFirstCall: true } - ); - - return newState; -} -``` - -This function basically allows you to create substates, so you can map data into something else; you can combine several states together, which makes them into `State<[state1, state2, state3]>` shape, and then process into a more expressive form. diff --git a/docs/typescript.md b/docs/typescript.md deleted file mode 100644 index 9b07a2f..0000000 --- a/docs/typescript.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: default -title: TypeScript support -nav_order: 4 ---- - -The library itself is written in TypeScript, so you can import type definitions without installing an additional types library. That being said, the types are not perfect (for example, you need to manually select element type for `useValueIterator`, even if the state value is `State`), and hopefully I will be able to improve that in the future.