21 |
22 | To schedule events one-after another. To play _lazy_ animations in order, correlated with their position on the page.
23 |
24 | # API
25 | ## Scheduler
26 | - `Scheduler` - task scheduler. Collect tasks and execute them with `stepDelay` between in the `priority` order.
27 | - `stepDelay` - delay between two events
28 | - `[reverse]` - reverses the queue
29 | - `[source]` - priority calculation function
30 | - `[withSideEffect]` - indicates that Scheduler has side effects, and enabled auto update(re-render) on task execution. __Affects performance__.
31 | - `[observe]` - cache buster property. Scheduler sorts queue only on element change, in case of using `source` you might need "inform"
32 | - `[noInitialDelay]` - remove delay from the first task.
33 | - `[disabled]` - disables ticking
34 | it to resort queue.
35 |
36 |
37 | ```js
38 | import {Scheduler} from 'react-queue';
39 |
40 |
41 | {channel => .... }
42 |
43 |
44 | // use source to create priority based on element position on the page
45 | ref.getBoundingClientRect().top} />
46 | ```
47 | `channel` also provides `channel.reset()` function, to clear all `executed` bits, and start everything from the scratch.
48 |
49 | ## Queue
50 | - `Queue` - queued event. It just got executed, nothing more. "When", in "when order" - that is the question.
51 | - `channel` - channel acquired from Scheduler
52 | - `callback` - callback to execute. In case if callback will return a number, or a promise resolving to number, it would be used to _shift_ delay to the next step.
53 | - `priority` - pririty in queue, where 0-s should be executed before 1-s.
54 | - [`shift`] - sub priority change. `shift={-1}` will swap this task with previous sibling.
55 | - [`disabled`] - holds queue execution (sets priority to Infitity).
56 | next tick will be moved by {number}ms. In case of just Promise - next tick will wait to for promise to be resolved.
57 | - [`children`] - any DOM node, Queue will pass as `ref` into scheduler's `source`
58 |
59 | ```js
60 | import {Scheduler, Queue} from 'react-queue';
61 |
62 |
63 | {channel =>
64 |
65 |
66 | // this one will report `ref` to the scheduler
67 |
68 |
42
69 |
70 |
71 | this.setState({x: 1})}>
72 |
1 {x == 1 && "selected!!"}
73 |
74 |
75 | this.setState({x: 2})}>
76 |
2 {x == 2 && "selected!!"}
77 |
78 |
79 | this.setState({x: 3})}>
80 |
3 {x == 3 && "selected!!"}
81 |
82 | }
83 |
84 | ```
85 |
86 | ## FlattenPriorityGroup
87 | - `FlattenPriorityGroup` - "flattens" all priority changes inside. Could help manage nested tasks.
88 | - `channel` - channel acquired from Scheduler
89 | - [`children`] - render function
90 | - [`priority`] - task priority. Would be set for all nested tasks.
91 | - [`shift`] - sub priority change. `shift={-1}` will swap this task with previous sibling.
92 | - [`disabled`] - holds queue execution (sets priority to Infitity).
93 |
94 | In the next example executing order would be - 2, 1, 4, 3.
95 | ```js
96 |
97 | {channel => (
98 |
99 |
100 | { pchannel => [
101 | 1,
102 | 2
103 | ]}
104 |
105 |
106 | { pchannel => [
107 | 3,
108 | 4
109 | ]}
110 |
111 |
112 | )}
113 |
114 | ```
115 |
116 |
117 | ## Promised
118 | - `Promised` - promised event. Once it started it should all `done` when it's done. This is a more complex form of queue, with much stronger feedback.
119 | - `channel` - channel acquired from Scheduler
120 | - [`children`] - render function
121 | - [`autoexecuted`] - auto "done" the promised. boolean or number. If number - would be used to shift next step.
122 | - [`priority`] - task priority. Lower goes first
123 | - [`shift`] - sub priority change. `shift={-1}` will swap this task with previous sibling.
124 | - [`disabled`] - holds queue execution (sets priority to Infitity).
125 | ```js
126 | import {Scheduler, Promised} from 'react-queue';
127 | import {Trigger} from 'recondition';
128 |
129 |
130 | {channel =>
131 |
132 | {({executed, active, done, forwardRed}) => (
133 |
134 | {executed && "task is done"}
135 | {active && "task is running"}
136 | // don't call anything in render
137 | done(42/* make next step by 42ms later*/)}/>
138 |
139 | )
140 |
141 | }
142 |
143 |
144 | // this code has the same behavior
145 |
146 | {channel =>
147 |
148 | {({executed, active, done, forwardRed}) => (
149 |
150 | {executed && "task is done"}
151 | {active && "task is running"}
152 |
153 | )
154 |
155 | }
156 |
157 | ```
158 |
159 | For example - animation - it will execute one `Promised` after another, and triggering waterfall animation.
160 | ```js
161 | import {Scheduler, Promised} from 'react-queue';
162 | import {Trigger} from 'recondition';
163 |
164 |
165 | {channel =>
166 |
167 | {({executed, active, fired}) => (
9 |
10 |
11 |
12 | 
13 |
14 |
15 |
16 | 
17 |
18 |
19 |