Skip to content

Commit

Permalink
docs: Mutatable is now stable
Browse files Browse the repository at this point in the history
  • Loading branch information
@d-exclaimation
d-exclaimation committed Jun 1, 2023
1 parent 0da0460 commit ee57f9a
Show file tree
Hide file tree
Showing 4 changed files with 36 additions and 40 deletions.
24 changes: 12 additions & 12 deletions docs/concepts/components.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Seraph components are the building blocks of your application. They are used to
In Seraph, components are simply functions that return an actual DOM element. They are no different from plain HTML elements, except that they are written declaratively and can integrated with Seraph's state.

```ts
import { html } from '@d-exclaimation/seraph'
import { html } from "@d-exclaimation/seraph";

const App = () => {
return html.h1({
Expand All @@ -24,7 +24,7 @@ const myH1 = App(); // HTMLHeadingElement
This meant that you opt out of Seraph's style of writing components, you can still use plain HTML elements in your application.

```ts
import { html } from '@d-exclaimation/seraph'
import { html } from "@d-exclaimation/seraph";

const App = () => {
return html.h1({
Expand All @@ -42,7 +42,7 @@ document.body.appendChild(myH1);
or vice versa

```ts
import { html } from '@d-exclaimation/seraph'
import { html } from "@d-exclaimation/seraph";

const subtitleElement = document.getElementById("subtitle")!;

Expand All @@ -63,7 +63,7 @@ const App = () => {
The `html` object have feature parity with all the built-in HTML elements. All you need to do is to prefix the element name with `html.`.

```ts
import { html } from '@d-exclaimation/seraph'
import { html } from "@d-exclaimation/seraph";

html.h1({ c: "Hello World!" }); // HTMLHeadingElement
html.div({ c: "Hello World!" }); // HTMLDivElement
Expand All @@ -88,7 +88,7 @@ You can also use existing DOM elements as components using `hydrate`. This is us
```

```ts
import { state, hydrate, use } from '@d-exclaimation/seraph'
import { state, hydrate, use } from "@d-exclaimation/seraph";

const $state = state("Hello world!");

Expand Down Expand Up @@ -124,7 +124,7 @@ type DefaultProps = {
The `classes` prop is used to add CSS classes to the component. It can be a string or an array of strings.

```ts
import { html } from '@d-exclaimation/seraph'
import { html } from "@d-exclaimation/seraph";

const App = () => {
return html.h1({
Expand All @@ -144,7 +144,7 @@ Result in
The `style` prop is used to add inline CSS styles to the component.

```ts
import { html } from '@d-exclaimation/seraph'
import { html } from "@d-exclaimation/seraph";

const App = () => {
return html.h1({
Expand All @@ -167,7 +167,7 @@ Result in
The `c` prop is used to add children to the component. It can be a string and HTMLElements or an array of strings and HTMLElements.

```ts
import { html } from '@d-exclaimation/seraph'
import { html } from "@d-exclaimation/seraph";

const App = () => {
return html.div({
Expand Down Expand Up @@ -197,7 +197,7 @@ Result in
The `on` prop is used to add event listeners to the component. All events are using the same callback type as `addEventListener`.

```ts
import { html } from '@d-exclaimation/seraph'
import { html } from "@d-exclaimation/seraph";

const App = () => {
return html.div({
Expand All @@ -215,7 +215,7 @@ const App = () => {
The `attr` prop is used to add any other attributes to the component.

```ts
import { html } from '@d-exclaimation/seraph'
import { html } from "@d-exclaimation/seraph";

const App = () => {
return html.div({
Expand All @@ -237,7 +237,7 @@ Result in
Components can be bound to state using the `use` function. This will automatically update the component properties when the state changes.

```ts
import { html, state, use } from '@d-exclaimation/seraph'
import { html, state, use } from "@d-exclaimation/seraph";

const App = () => {
const $count = state(0);
Expand Down Expand Up @@ -268,7 +268,7 @@ const App = () => {
This means that you smartly use `use` to only update the component props that are actually changed, and even only passed certain states that you is relevant to the component.

```ts
import { html, state, use } from '@d-exclaimation/seraph'
import { html, state, use } from "@d-exclaimation/seraph";

const App = () => {
const $count = state(0);
Expand Down
10 changes: 5 additions & 5 deletions docs/concepts/rendering.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Seraph comes with some built-in utilities for rendering components to the DOM.
You can do a simple mounting where a component will just be appended to the target element.

```ts
import { html, mount } from '@d-exclaimation/seraph'
import { html, mount } from "@d-exclaimation/seraph";

const App = () => {
return html.h1({
Expand All @@ -29,7 +29,7 @@ This can be useful if you are integrating Seraph into an existing application an
You can also do a full rendering where the target element inner content will be replaced with the component.

```ts
import { html, render } from '@d-exclaimation/seraph'
import { html, render } from "@d-exclaimation/seraph";

const App = () => {
return html.h1({
Expand All @@ -53,7 +53,7 @@ To load data from a DOM element's `sr-props`, you need to explicitly call the `l
```

```ts
import { load, html, use } from '@d-exclaimation/seraph'
import { load, html, use } from "@d-exclaimation/seraph";

const $props = load<{ count: number }>('count-data');

Expand All @@ -75,7 +75,7 @@ Loaded data may instead be stored a json script element. In this case, you can u
```

```ts
import { resource } from '@d-exclaimation/seraph'
import { resource } from "@d-exclaimation/seraph";

const $props = resource<{ count: number }>('count-data');
```
Expand Down Expand Up @@ -130,7 +130,7 @@ You can combine `load` / `resouce` and `hydrate` to perform selective hydration
```

```ts
import { resource, state, from, zip, hydrate, html, use } from '@d-exclaimation/seraph'
import { resource, state, from, zip, hydrate, html, use } from "@d-exclaimation/seraph";

type Product = {
id: number;
Expand Down
36 changes: 16 additions & 20 deletions docs/concepts/states.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ $user.subscribe((state) => {
This is the basic state function that can be used to create a state. It takes an initial value and return a state object.

```ts
import { state } from '@d-exclaimation/seraph'
import { state } from "@d-exclaimation/seraph";

const $count = state(0);

Expand All @@ -67,7 +67,7 @@ const $count = state(0);
This is a function that can be used to run some code whenever the state changes. It takes a state and a callback function that will be called whenever the state changes.

```ts
import { state, effect } from '@d-exclaimation/seraph'
import { state, effect } from "@d-exclaimation/seraph";

const $count = state(0);

Expand All @@ -87,7 +87,7 @@ None :grin:.
This is a function that can be used to create a computed state from another. It takes a callback function that will be called whenever the state changes to compute the new value.

```ts
import { state, from } from '@d-exclaimation/seraph'
import { state, from } from "@d-exclaimation/seraph";

const $count = state(0);

Expand All @@ -105,7 +105,7 @@ console.log($double.current); // 2
This is a function that can be used to create a readonly zipped state from multiple states. Useful for creating a readonly state that depends on multiple states.

```ts
import { state, zip } from '@d-exclaimation/seraph'
import { state, zip } from "@d-exclaimation/seraph";

const $count = state(0);
const $name = state("John Doe");
Expand All @@ -128,7 +128,7 @@ console.log($user.current); // [1, "Jane Doe"]
This is a function that can be used to create a readonly combined object state from multiple states. Similar to `zip`, but instead of an array, it will return an object with the same keys as the states.

```ts
import { state, all } from '@d-exclaimation/seraph'
import { state, all } from "@d-exclaimation/seraph";

const $count = state(0);
const $name = state("John Doe");
Expand All @@ -151,7 +151,7 @@ console.log($user.current); // { count: 1, name: "Jane Doe" }
This is a function that can be used to create a readonly state from a data fetched logic. This is highly insipired by [@tanstack/query](https://tanstack.com/query/).

```ts
import { query } from '@d-exclaimation/seraph'
import { query } from "@d-exclaimation/seraph";

const $query = query({
queryFn: async () => {
Expand All @@ -173,15 +173,15 @@ const $query = query({
This is a function that can be used to determine the progress of an action.

```ts
import { transition, query, effect } from '@d-exclaimation/seraph'
import { transition, query, effect } from "@d-exclaimation/seraph";

const $isMutating = transition();
const $mutation = transition();

const $data = query({ ... });

console.log($isMutating.current); // false
console.log($mutation.current); // false

$isMutating.start(async () => {
$mutation.start(async () => {
const res = await fetch("..."):

if (!res.ok) {
Expand All @@ -191,24 +191,20 @@ $isMutating.start(async () => {
$data.invalidate();
});

console.log($isMutating.current); // true
console.log($mutation.current); // true

// - After the fetch resolves

console.log($isMutating.current); // false
console.log($mutation.current); // false

```

### `mutable`

::: danger Experimental
This is an experimental feature. Mutable state is still being optimised as currently it uses `Proxy` which may have performance issues.
:::

This is a function that can be used to create a mutable object state. It takes an initial value and return a mutable state object.

```ts
import { mutable } from '@d-exclaimation/seraph'
import { mutable } from "@d-exclaimation/seraph";

const $count = mutable({ count: 0 });

Expand All @@ -222,15 +218,15 @@ console.log($count.current); // { count: 1 }

### `memo`

::: danger Experimental
This is an experimental feature. Validating state changes is using `Object.is` which may not be enough for some cases.
::: danger Beta
This feature is currently still being heavily developed. Validating state changes is using `Object.is` which may not be enough for some cases and API may change in the future.
:::

This is a function that can be used to create a memoized state from another. It takes a callback function that will be called whenever the state changes to compute the new value. The callback function will only be called when the state changes, and the result will be cached.


```ts
import { sr } from '@d-exclaimation/seraph'
import { sr } from "@d-exclaimation/seraph";

const $count = state(0);

Expand Down
6 changes: 3 additions & 3 deletions docs/getting-started/quickstart.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ npm install @d-exclaimation/seraph
Let's start simple, create a new component called `HelloWorld`:

```ts
import { html, render } from '@d-exclaimation/seraph'
import { html, render } from "@d-exclaimation/seraph";

const App = () => {
return html.h1({
Expand All @@ -45,7 +45,7 @@ Let's spice things up a bit by adding some interactivity to our component. We'll


```ts{6-20}
import { html, render, state, use } from '@d-exclaimation/seraph' // [!code ++]
import { html, render, state, use } from "@d-exclaimation/seraph"; // [!code ++]
const App = () => {
const $count = state(0); // [!code ++]
Expand Down Expand Up @@ -85,7 +85,7 @@ To change the state, we only need to reassign the state's `current` property. In
We can use the `effect` function to run some code whenever the state changes. Let's add a `console.log` whenever the state changes:

```ts
import { html, render, state, use, effect } from '@d-exclaimation/seraph' // [!code ++]
import { html, render, state, use, effect } from "@d-exclaimation/seraph"; // [!code ++]

const App = () => {
const $count = state(0);
Expand Down

0 comments on commit ee57f9a

Please sign in to comment.