@neveranyart/weaver 1.0.13 → 1.0.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -139
- package/docs/ROUTING.md +128 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,146 +6,15 @@ An in-house core package by neveranyart for making performant, interactive React
|
|
|
6
6
|
|
|
7
7
|
|
|
8
8
|
|
|
9
|
-
|
|
10
9
|
## Introduction
|
|
11
|
-
This package is published as an in-depth on `neverany` technicals.
|
|
12
|
-
|
|
13
|
-
## Usage
|
|
14
|
-
|
|
15
|
-
### Routing
|
|
16
|
-
The package wraps around `react-router` as a base for working with routing because it provides us a way to postpone parent components mounting.
|
|
17
|
-
|
|
18
|
-
There are 2 components for composing delayed routing for animations: `DelayedOutlet`, `Pipeline`.
|
|
19
|
-
|
|
20
|
-
- `DelayedOutlet`:
|
|
21
|
-
- Drop-in replacement for `Outlet` component from `react-router`.
|
|
22
|
-
- `Pipeline`:
|
|
23
|
-
- Declare parent for an endpoint, handle route changes and communicates with `DelayedOutlet`.
|
|
24
|
-
- As long as it's the ONLY instance on the route endpoint, it should works just fine.
|
|
25
|
-
- Can be placed anywhere, but please put it as a parent for all of your endpoint's components.
|
|
26
|
-
- It can't nest itself.
|
|
27
|
-
|
|
28
|
-
> [!CAUTION]
|
|
29
|
-
> There can only be ONE `DelayedOutlet` per app and ONE `Pipeline` per parent path.
|
|
30
|
-
|
|
31
|
-
Other than that, just use `react-router` like intended. `weaver/routing` has especially tested against going back and forth rapidly and works flawlessly in strict mode, so you don't have to think about the logic behind it!
|
|
32
|
-
|
|
33
|
-
While the route is delayed, the previous route is still displayed to ensure a smooth tranition to your likings.
|
|
34
|
-
|
|
35
|
-
Example usage with 2 endpoints, router delayed for `500ms`:
|
|
36
|
-
|
|
37
|
-
```tsx
|
|
38
|
-
import { DelayedOutlet, Pipeline } from '@neveranyart/weaver/routing';
|
|
39
|
-
import { StrictMode, Suspense } from 'react';
|
|
40
|
-
import { createRoot } from 'react-dom/client';
|
|
41
|
-
import { createBrowserRouter, Link, RouterProvider } from 'react-router';
|
|
42
|
-
|
|
43
|
-
function Root() {
|
|
44
|
-
return (
|
|
45
|
-
<main>
|
|
46
|
-
<DelayedOutlet delay={500} />
|
|
47
|
-
</main>
|
|
48
|
-
);
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
function Home() {
|
|
52
|
-
return (
|
|
53
|
-
<Pipeline title={'Home'} debugName={'Home'}>
|
|
54
|
-
<p>Home</p>
|
|
55
|
-
<Link to="/projects">Navigate</Link>
|
|
56
|
-
</Pipeline>
|
|
57
|
-
);
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
const router = createBrowserRouter([
|
|
61
|
-
{
|
|
62
|
-
path: '/',
|
|
63
|
-
element: <Root />,
|
|
64
|
-
children: [
|
|
65
|
-
{
|
|
66
|
-
index: true,
|
|
67
|
-
element: (
|
|
68
|
-
<Suspense>
|
|
69
|
-
<Home />
|
|
70
|
-
</Suspense>
|
|
71
|
-
),
|
|
72
|
-
},
|
|
73
|
-
{
|
|
74
|
-
path: '/projects/*',
|
|
75
|
-
element: (
|
|
76
|
-
<Suspense>
|
|
77
|
-
<Pipeline title={'Projects'} debugName={'Projects'}>
|
|
78
|
-
<p>Projects</p>
|
|
79
|
-
<Link to="/">Navigate</Link>
|
|
80
|
-
</Pipeline>
|
|
81
|
-
</Suspense>
|
|
82
|
-
),
|
|
83
|
-
},
|
|
84
|
-
],
|
|
85
|
-
},
|
|
86
|
-
]);
|
|
87
|
-
|
|
88
|
-
createRoot(document.getElementById('root')!).render(
|
|
89
|
-
<StrictMode>
|
|
90
|
-
<RouterProvider router={router} />
|
|
91
|
-
</StrictMode>
|
|
92
|
-
);
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
`weaver/routing` also provides a quick way to react to state changes with a cool hook called `useWeaverState`. Containing 4 states for you to play with:
|
|
96
|
-
|
|
97
|
-
```ts
|
|
98
|
-
const pageRendered = useWeaverState('pageRendered');
|
|
99
|
-
const activePipeline = useWeaverState('activePipeline');
|
|
100
|
-
const activeParent = useWeaverState('activeParent');
|
|
101
|
-
const navigating = useWeaverState('navigating');
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
When a route change happens, this is how states in `weaver/routing` changes when a route change is successful:
|
|
105
|
-
|
|
106
|
-
`+`: Other events/information.
|
|
107
|
-
`!`: State changes.
|
|
108
|
-
|
|
109
|
-
```
|
|
110
|
-
+ Current `Pipeline` path: "/""
|
|
111
|
-
! pageRendered -> false, navigating -> true.
|
|
112
|
-
+ Receives new parent.
|
|
113
|
-
+ Delay route change.
|
|
114
|
-
+ Set new `Pipeline`.
|
|
115
|
-
+ `Pipeline` path "/" start unmounting process.
|
|
116
|
-
+ New `Pipeline` path: "/projects".
|
|
117
|
-
! activePipeline -> "/projects".
|
|
118
|
-
! navigating -> false.
|
|
119
|
-
+ New `Pipeline` start mounting process.
|
|
120
|
-
! pageRendered -> true, activeParent -> "/projects".
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
When a route change is cancelled by user going back mid delay:
|
|
124
|
-
|
|
125
|
-
```
|
|
126
|
-
+ Current `Pipeline` path: "/""
|
|
127
|
-
! pageRendered -> false, navigating -> true.
|
|
128
|
-
+ Receives new parent.
|
|
129
|
-
+ Delay route change.
|
|
130
|
-
+ User cancelled.
|
|
131
|
-
! pageRendered -> true, navigating -> false.
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
Overall:
|
|
135
|
-
- `pageRendered` covers the whole routing process. It is the recommended way of knowing if the content is ready to be displayed or not.
|
|
136
|
-
- `activePipeline` is for knowing which Pipeline has taken over previous one.
|
|
137
|
-
- `activeParent` tells which Pipeline has delivered its components on screen.
|
|
138
|
-
- `navigating` tells when `DelayedOutlet` handles routing.
|
|
139
|
-
|
|
140
|
-
### Hooks
|
|
141
|
-
`weaver` provides a reasonable amount of DOM hooks, intensive hooks will only allow callbacks usage to avoid React re-render.
|
|
10
|
+
This package is published as an in-depth on `neverany` technicals. It is not intended for broad usage so it has a strict choice of dependencies and a specific way of use.
|
|
142
11
|
|
|
143
|
-
|
|
12
|
+
But, most components and tools are built with flexibility in mind, providing a balance between abstraction and verbose.
|
|
144
13
|
|
|
14
|
+
## Documentations
|
|
15
|
+
1. [Routing](https://github.com/neveranyart/weaver/blob/main/docs/ROUTING.md)
|
|
16
|
+
2. Hooks
|
|
17
|
+
3. Scene
|
|
145
18
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
- `BakeScene`: Wait and notify when a 3D scene has finished rendering and ready to be shown, usually paired with `Pipeline`.
|
|
149
|
-
- `Orbit`: ResizeObserver & IntersectionObserver simplified.
|
|
150
|
-
- `SceneSync`: Sync `@react-three/fiber` scene with DOM element.
|
|
151
|
-
- And a big directory of DOM hooks.
|
|
19
|
+
## About copyleft license
|
|
20
|
+
This project is relatively new, we'll consider switching to a more permissive license when the project is mature enough.
|
package/docs/ROUTING.md
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# Routing
|
|
2
|
+
The package wraps around `react-router` as a base for working with routing because it provides us a way to postpone parent components mounting.
|
|
3
|
+
|
|
4
|
+
## `DelayedOutlet`, `Pipeline`
|
|
5
|
+
- `DelayedOutlet`:
|
|
6
|
+
- Drop-in replacement for `Outlet`.
|
|
7
|
+
- `Pipeline`:
|
|
8
|
+
- Declares parent for a route, handle route changes and communicates with `DelayedOutlet`.
|
|
9
|
+
- Recommended place to put the component is the parent for a route's components, see example below.
|
|
10
|
+
- It can't nest itself.
|
|
11
|
+
|
|
12
|
+
> [!CAUTION]
|
|
13
|
+
> The only officially supported router is `BrowserRouter`, we don't test with other methods.
|
|
14
|
+
>
|
|
15
|
+
> There can only be ONE `DelayedOutlet` per app and ONE `Pipeline` per parent path.
|
|
16
|
+
|
|
17
|
+
Other than that, use `react-router` like intended. `weaver/routing` has especially tested against going back and forth rapidly and works flawlessly in strict mode, even with throttle the CPU to a good x20 slowdown, so you don't have to suffer like we did developing the package!
|
|
18
|
+
|
|
19
|
+
While the route is delayed, the previous route is still displayed to ensure a smooth tranition to your likings.
|
|
20
|
+
|
|
21
|
+
Example usage with 2 endpoints, router delayed for `500ms`:
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import { DelayedOutlet, Pipeline } from '@neveranyart/weaver/routing';
|
|
25
|
+
import { StrictMode, Suspense } from 'react';
|
|
26
|
+
import { createRoot } from 'react-dom/client';
|
|
27
|
+
import { createBrowserRouter, Link, RouterProvider } from 'react-router';
|
|
28
|
+
|
|
29
|
+
function Root() {
|
|
30
|
+
return (
|
|
31
|
+
<main>
|
|
32
|
+
<DelayedOutlet delay={500} />
|
|
33
|
+
</main>
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function Home() {
|
|
38
|
+
return (
|
|
39
|
+
<Pipeline title='Home' debugName='Home' parentPath='/'>
|
|
40
|
+
<p>Home</p>
|
|
41
|
+
<Link to="/projects">Navigate</Link>
|
|
42
|
+
</Pipeline>
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const router = createBrowserRouter([
|
|
47
|
+
{
|
|
48
|
+
path: '/',
|
|
49
|
+
element: <Root />,
|
|
50
|
+
children: [
|
|
51
|
+
{
|
|
52
|
+
index: true,
|
|
53
|
+
element: (
|
|
54
|
+
<Suspense>
|
|
55
|
+
<Home />
|
|
56
|
+
</Suspense>
|
|
57
|
+
),
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
path: '/projects/*',
|
|
61
|
+
element: (
|
|
62
|
+
<Suspense>
|
|
63
|
+
<Pipeline title='Projects' debugName='Projects' parentPath='/projects/*'>
|
|
64
|
+
<p>Projects</p>
|
|
65
|
+
<Link to="/">Navigate</Link>
|
|
66
|
+
</Pipeline>
|
|
67
|
+
</Suspense>
|
|
68
|
+
),
|
|
69
|
+
},
|
|
70
|
+
],
|
|
71
|
+
},
|
|
72
|
+
]);
|
|
73
|
+
|
|
74
|
+
createRoot(document.getElementById('root')!).render(
|
|
75
|
+
<StrictMode>
|
|
76
|
+
<RouterProvider router={router} />
|
|
77
|
+
</StrictMode>
|
|
78
|
+
);
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Routing also provides a quick way to react to state changes with a cool hook called `useWeaverState`. Containing 4 states for you to play with:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
// Covers the whole routing process. It is the recommended way of knowing if the content is ready to be displayed or not
|
|
85
|
+
const pageRendered = useWeaverState('pageRendered');
|
|
86
|
+
|
|
87
|
+
// Knowing which Pipeline has taken over previous one.
|
|
88
|
+
const activePipeline = useWeaverState('activePipeline');
|
|
89
|
+
|
|
90
|
+
// Which Pipeline has delivered its components on screen.
|
|
91
|
+
const activeParent = useWeaverState('activeParent');
|
|
92
|
+
|
|
93
|
+
// Tells when `DelayedOutlet` handles routing.
|
|
94
|
+
const navigating = useWeaverState('navigating');
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
When a route change happens, this is how states in `weaver/routing` changes when a route change is successful:
|
|
98
|
+
|
|
99
|
+
- `+`: Other events/information.
|
|
100
|
+
- `!`: State changes.
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
+ Current `Pipeline` path: "/"
|
|
104
|
+
+ User navigates.
|
|
105
|
+
! pageRendered -> false, navigating -> true.
|
|
106
|
+
+ Receives new parent.
|
|
107
|
+
+ Delay route change.
|
|
108
|
+
+ Set new `Pipeline`.
|
|
109
|
+
+ `Pipeline` path "/" start unmounting process.
|
|
110
|
+
+ New `Pipeline` path: "/projects".
|
|
111
|
+
! activePipeline -> "/projects".
|
|
112
|
+
! navigating -> false.
|
|
113
|
+
+ New `Pipeline` start mounting process.
|
|
114
|
+
! pageRendered -> true, activeParent -> "/projects".
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
When a route change is cancelled by user:
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
+ Current `Pipeline` path: "/"
|
|
121
|
+
+ User navigates.
|
|
122
|
+
! pageRendered -> false, navigating -> true.
|
|
123
|
+
+ Receives new parent.
|
|
124
|
+
+ Delay route change.
|
|
125
|
+
+ User cancelled.
|
|
126
|
+
+ `Pipeline` path "/" detects cancel.
|
|
127
|
+
! pageRendered -> true, navigating -> false.
|
|
128
|
+
```
|
package/package.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"author": "neveranyart",
|
|
3
3
|
"license": "GPL-3.0-or-later",
|
|
4
4
|
"name": "@neveranyart/weaver",
|
|
5
|
-
"version": "1.0.
|
|
5
|
+
"version": "1.0.15",
|
|
6
6
|
"description": "An in-house package by neverany for making interactive React CSR.",
|
|
7
7
|
"packageManager": "yarn@4.10.3",
|
|
8
8
|
"publishConfig": {
|