Skip to content

Commit ca9b4b3

Browse files
committed
Refactors presence package to FSM based implementation
1 parent b288ae5 commit ca9b4b3

File tree

8 files changed

+287
-606
lines changed

8 files changed

+287
-606
lines changed

packages/presence/CHANGELOG.md

Whitespace-only changes.

packages/presence/README.md

Lines changed: 148 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,6 @@
99
[![version](https://img.shields.io/npm/v/@solid-primitives/presence?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/presence)
1010
[![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)
1111

12-
A small SolidJS utility to animate the presence of an element. Inspired by & directly forked from [`use-presence`](https://www.npmjs.com/package/use-presence).
13-
14-
### The problem
15-
16-
There are two problems that you have to solve when animating the presence of an element:
17-
18-
1. During enter animations, you have to render an initial state where the element is hidden and only after the latest state has propagated to the DOM, you can can animate the final state that the element should animate towards.
19-
2. Exit animations are a bit tricky in SolidJS, since this typically means that a component unmounts. However when the component has already unmounted, you can't animate it anymore. A workaround is often to keep the element mounted, but that keeps unnecessary elements around and can hurt accessibility, as hidden interactive elements might still be focusable.
20-
21-
### This solution
22-
23-
This utility provides a lightweight solution where the animating element is only mounted the minimum of time, while making sure the animation is fully visible to the user. The rendering is left to the user to support all kinds of styling solutions.
24-
2512
## Installation
2613

2714
```bash
@@ -32,143 +19,184 @@ yarn add @solid-primitives/presence
3219
pnpm add @solid-primitives/presence
3320
```
3421

35-
## How to use it
22+
A small, reactive utility to exert stronger control over an element's presence in the DOM in order to apply enter and exit transitions/animations.
3623

37-
### `createPresence` boolean example
24+
## How to use it?
3825

39-
```tsx
40-
const FirstExample = () => {
41-
const [showStuff, setShowStuff] = createSignal(true);
42-
const { isVisible, isMounted } = createPresence(showStuff, {
43-
transitionDuration: 500,
44-
});
26+
```typescript
27+
const App = () => {
28+
const [show, setShow] = createSignal(true);
29+
const state = createPresence(show, { duration: 300, initialRun: true });
30+
const isMounted = createMemo(() => state() !== "exited");
4531

4632
return (
47-
<div
48-
style={{
49-
padding: "2em",
50-
margin: "2em",
51-
"border-radius": "2em",
52-
"box-shadow": "-5px 0px 10px rgba(0, 0, 0, 0.2)",
53-
}}
54-
>
55-
<button onclick={() => setShowStuff(!showStuff())}>{`${
56-
showStuff() ? "Hide" : "Show"
57-
} stuff`}</button>
33+
<div>
34+
<div>
35+
<button onClick={() => setShow(p => !p)}>{show() ? "Hide" : "Show"}</button>
36+
</div>
5837
<Show when={isMounted()}>
5938
<div
6039
style={{
61-
transition: "all .5s ease",
62-
opacity: isVisible() ? "1" : "0",
63-
transform: isVisible() ? "translateX(0)" : "translateX(50px)",
64-
}}
65-
>
66-
I am the stuff!
67-
</div>
68-
</Show>
69-
</div>
70-
);
71-
};
72-
```
73-
74-
### `createPresence` switching example
40+
transition: "all .3s linear",
7541

76-
The first argument of `createPresence` is a signal accessor of arbitrary type. This allows you to use it with any kind of data, not just booleans. This is useful if you want to animate between different items. If you utilize the returned `mountedItem` property, you can get the data which should be currently mounted regardless of the animation state
77-
78-
```tsx
79-
const SecondExample = () => {
80-
const items = ["foo", "bar", "baz", "qux"];
81-
const [activeItem, setActiveItem] = createSignal(items[0]);
82-
const presence = createPresence(activeItem, {
83-
transitionDuration: 500,
84-
});
85-
86-
return (
87-
<div
88-
style={{
89-
padding: "2em",
90-
margin: "2em",
91-
"border-radius": "2em",
92-
"box-shadow": "-5px 0px 10px rgba(0, 0, 0, 0.2)",
93-
}}
94-
>
95-
<For each={items}>
96-
{item => (
97-
<button onClick={() => setActiveItem(p => (p === item ? undefined : item))}>
98-
{item}
99-
</button>
100-
)}
101-
</For>
102-
<Show when={presence.isMounted()}>
103-
<div
104-
style={{
105-
transition: "all .5s linear",
106-
...(presence.isEntering() && {
42+
...(state() === "initial" && {
10743
opacity: "0",
10844
transform: "translateX(-25px)",
10945
}),
110-
...(presence.isExiting() && {
111-
opacity: "0",
112-
transform: "translateX(25px)",
113-
}),
114-
...(presence.isVisible() && {
46+
47+
...(state() === "entering" && {
11548
opacity: "1",
11649
transform: "translateX(0)",
11750
}),
51+
52+
...(state() === "exiting" && {
53+
opacity: "0",
54+
transform: "translateX(25px)",
55+
}),
11856
}}
11957
>
120-
{presence.mountedItem()}
58+
Hello World!
12159
</div>
12260
</Show>
12361
</div>
12462
);
12563
};
12664
```
12765

128-
### `createPresence` options API
66+
Here is how to run css animations:
67+
68+
```css
69+
.hidden {
70+
opacity: 0;
71+
}
72+
73+
.fadein {
74+
animation: 0.5s linear fadein;
75+
}
76+
77+
.fadeout {
78+
animation: 0.5s linear fadeout;
79+
}
80+
81+
@keyframes fadein {
82+
0% {
83+
opacity: 0;
84+
color: red;
85+
}
86+
100% {
87+
opacity: 1;
88+
color: green;
89+
}
90+
}
91+
92+
@keyframes fadeout {
93+
0% {
94+
opacity: 1;
95+
color: green;
96+
}
97+
100% {
98+
opacity: 0;
99+
color: blue;
100+
}
101+
}
102+
```
103+
104+
```typescript
105+
<Show when={isMounted()}>
106+
<div
107+
classList={{
108+
hidden: state() === 'initial',
109+
fadein: state() === 'entering',
110+
fadeout: state() === 'exiting',
111+
}}
112+
>
113+
Hello World!
114+
</div>
115+
</Show>
116+
```
117+
118+
119+
120+
## How it works?
121+
122+
When an elements visibilty tied to a signal, the elements gets mounted and unmounted abruptly, not permitting to apply any css transitions.
129123

130124
```ts
131-
function createPresence<TItem>(
132-
item: Accessor<TItem | undefined>,
133-
options: Options,
134-
): PresenceResult<TItem>;
135-
136-
type Options = {
137-
/** Duration in milliseconds used both for enter and exit transitions. */
138-
transitionDuration: MaybeAccessor<number>;
139-
/** Duration in milliseconds used for enter transitions (overrides `transitionDuration` if provided). */
140-
enterDuration: MaybeAccessor<number>;
141-
/** Duration in milliseconds used for exit transitions (overrides `transitionDuration` if provided). */
142-
exitDuration: MaybeAccessor<number>;
143-
/** Opt-in to animating the entering of an element if `isVisible` is `true` during the initial mount. */
144-
initialEnter?: boolean;
145-
};
125+
<Show when={show()}>
126+
<div>Hello World!</div>
127+
</Show>
128+
```
146129

147-
type PresenceResult<TItem> = {
148-
/** Should the component be returned from render? */
149-
isMounted: Accessor<boolean>;
150-
/** The item that is currently mounted. */
151-
mountedItem: Accessor<TItem | undefined>;
152-
/** Should the component have its visible styles applied? */
153-
isVisible: Accessor<boolean>;
154-
/** Is the component either entering or exiting currently? */
155-
isAnimating: Accessor<boolean>;
156-
/** Is the component entering currently? */
157-
isEntering: Accessor<boolean>;
158-
/** Is the component exiting currently? */
159-
isExiting: Accessor<boolean>;
160-
};
130+
`createPresence` creates a derived signal, through which we transition from `false` to `true` in two steps, `entering` and `entered`, and again from `true` to `false` in two steps `exiting` and `exited`.
131+
132+
```ts
133+
const [show, setShow] = createSignal(true);
134+
135+
const state = createPresence(show, {
136+
duration: 500,
137+
initialTransition: true,
138+
});
139+
```
140+
141+
This allows us to apply enter and exit transitions on an element but first we need to hand over the control of the element's visibilty to the `state`:
142+
143+
```ts
144+
const isMounted = () => state() !== 'exited';
145+
<Show when={isMounted()}>
146+
<div>Hello World!</div>
147+
</Show>
161148
```
162149

163-
## Demo
150+
`createPresence` returns a derived signal with five states, three of them being resting states, `initial`, `entered`, `exited` and two of them being transitioning states, `entering` and `exiting`.
164151

165-
Demo can be seen [here](https://stackblitz.com/edit/presence-demo).
152+
```ts
153+
type State = "initial" | "entering" | "entered" | "exiting" | "exited";
154+
```
166155

167-
## Changelog
156+
Element is mounted at `initial` state. This state is short-lived since `entering` is flushed immediately via event loop however it can be used to set css properties.
157+
158+
When `show` is set to `true`, component gets mounted at `initial` state which changes to `entering` almost immediately and remain there for the duration of `500ms`, then moves to `entered` state and remain there indefinitely.
159+
160+
This allow us to transition from a property loaded with `entering` state to the one loaded with `entered` state:
168161

169-
See [CHANGELOG.md](./CHANGELOG.md)
162+
```ts
163+
<div
164+
style={{
165+
transition: 'all .5s linear',
166+
167+
...(state() === 'entering' && {
168+
color: 'green',
169+
}),
170+
171+
...(state() === 'entered' && {
172+
color: 'red',
173+
}),
174+
}}
175+
>
176+
Hello World!
177+
</div>
178+
```
170179

171-
## Related
180+
Now, when `show` is set to `false`, the `div` elemement does not disappear immediately but waits for the duration of `exiting` state. In other words, we extended element's presence in the DOM for `500ms` which allows us to apply exit transitions:
181+
182+
```ts
183+
<div
184+
style={{
185+
transition: 'all .5s linear',
186+
187+
...(state() === 'exiting' && {
188+
color: 'orange',
189+
}),
190+
191+
...(state() === 'exited' && {
192+
color: 'blue',
193+
}),
194+
}}
195+
>
196+
Hello World!
197+
</div>
198+
```
199+
200+
## Changelog
172201

173-
- [`use-presence`](https://www.npmjs.com/package/use-presence)
174-
- [`@solid-primitives/transition-group`](https://www.npmjs.com/package/@solid-primitives/transition-group)
202+
See [CHANGELOG.md](./CHANGELOG.md)

0 commit comments

Comments
 (0)