;
139 |
140 | Paragraphs.proptypes = {
141 | paragraphsData = PropTypes.arrayOf(PropTypes.shape({
142 | id: PropTypes.string.isRequired,
143 | content: Proptyes.node.isRequired,
144 | })),
145 | };
146 |
147 | export default Paragraphs;
148 | ```
149 |
150 | ### Complete Examples
151 |
152 | There are some examples in this repo that take advantage of all the different usages of the API:
153 |
154 | - [paragraphs](https://github.com/josepot/react-redux-scroll/tree/master/examples/paragraphs): It's a pretty basic one based on the code above.
155 | - [lottery](https://github.com/josepot/react-redux-scroll/tree/master/examples/lottery): This one is more advanced: it demonstarates how to use multiple ScrollAreas and having more than one scroll happneing at the same time.
156 | In order to try the examples, clone this repo, go the example folder that you want to try and do an `npm install`, `npm start`. For example:
157 | - [fiddler](https://github.com/josepot/react-redux-scroll/tree/master/examples/fiddler): A fiddler of the different `scrollOptions`.
158 |
159 | ## API
160 |
161 | ### `createScrollMiddleware()`
162 | It returns a [redux middleware](http://redux.js.org/docs/advanced/Middleware.html).
163 |
164 | ### `scrollToWhen({pattern, [onEnd], [scrollOptions], [excludeProps]})`
165 |
166 | It returns a Higher Order React Component Function that will trigger scroll to the provided component when the pattern matches the dispatched
167 |
168 | **Arguments**
169 |
170 | #### - `pattern` (*String | Function | Array*):
171 | It will trigger a scroll when a dispatched action matches the pattern. (Very similar to the way that [redux-saga take pattern](https://redux-saga.github.io/redux-saga/docs/api/index.html#takepattern) works).
172 |
173 | - If it's a String: the pattern will match if `action.type === pattern`
174 | - If it's a Function: the pattern will match if the return value of the function is truthy. This function receives the following arguments: `(action, props, newState, oldState)`. It can also return an object containing a different [`onEnd` function](#---onenddispatch-canceled-void--function) (which will take precedence over the one provided in the second parameter of the `scrollToWhen` function) and/or [`scrollOptions`](#---scrolloptions--object) (object which will get merged with the options provided in the third parameter of the `scrollToWhen` function).
175 | - If it's an Array: each item in the array is matched with beforementioned rules, so the mixed array of strings and function predicates is supported.
176 |
177 | #### - `[ onEnd(dispatch, canceled): void ]` (*Function*):
178 | A callback function that will get called once the scroll has finished. The first argument is the [redux store `dispatch` function](http://redux.js.org/docs/api/Store.html#dispatch). The second parameter is a boolean flag indicating whether the scroll got cancelled.
179 |
180 | #### - `[ scrollOptions ]` (*Object*):
181 | If specified further customizes the behavior of the scroll. The possible options are:
182 | - `[ duration ]` (Number): Number of milliseconds that it will take for the scroll to complete. Defaults to `500`.
183 | - `[ transitionTimingFunction ]` (String | Function):
184 | - If a String, one of:
185 | * LINEAR
186 | * EASE_IN_QUAD
187 | * EASE_OUT_QUAD
188 | * EASE_IN_OUT_QUAD
189 | * EASE_IN_CUBIC
190 | * EASE_OUT_CUBIC
191 | * EASE_IN_OUT_CUBIC
192 | * EASE_IN_QUART
193 | * EASE_OUT_QUART
194 | * EASE_IN_OUT_QUART
195 | - If a function: it takes one argument `t` which is a decimal value between 0 and 1 (including both 0 and 1) that represents the proportional amount of time that has passed since the motion started. This function is supposed to returs a value between 0 and 1 that represents the proportional distance that has been completed in `t` time. The only conditions are that if `t` is zero the return value must be zero and that if `t` is 1 the return value must be 1 too.
196 | - Defaults to: `EASE_IN_QUAD`.
197 | - `[ xAlignment ]` (String): Either `LEFT`, `CENTER` or `RIGHT`, pass `null` or `undefined` if you don't want for the scroll function to change the x position. Defaults to `null`. If you want a horizontal scroll set this to any of the possible values and the yAlignment to `null`.
198 | - `[ xMargin ]` (Number): Margin in pixels to the x alignment. Defaults to 0.
199 | - `[ yAlignment ]` (String): Either `TOP`, `CENTER` or `BOTTOM`, pass `null` or `undefined` if you don't want for the scroll function to change the y position. Defaults to `TOP`.
200 | - `[ yMargin ]` (Number): Margin in pixels to the y alignment. Defaults to 0.
201 |
202 | #### - `[ excludeProps ]` (*Array*):
203 | An array of Strings indicating the names of the props that shouldn't be propagated to the enhanced component.
204 |
205 | ### `scrollableArea`
206 |
207 | It returns a Higher Order React Component Function that creates a ScrollableArea for the Scrollable components that it has inside. It's meant to be used for enhancing "overflowing" components. If a Scrollable component is not inside a ScrollableArea, the ScrollableArea defaults to `window`.
208 |
209 |
210 | ## FAQ
211 |
212 | ### Is there an easy way to disable this library for the SSR build?
213 |
214 | Setting the env variable `IS_SSR` to `true` will accomplish that.
215 |
216 | ### - What happens when more than one scroll tries to take place as a result of the latest action that was dispatched?
217 |
218 | Depends. If the scrolls are for different "Scrolling Areas" all
219 | scrolls will happen simultaneusly, no problem. However, if they belong to the
220 | same "Scrolling Area" (i.e. they are all requesting a `window` scroll)
221 | then the middleware will only allow the first scroll that got subscribed to
222 | happen. In the development env you will get warnings in the console
223 | letting you know that some scrolls were prevented from happening because they
224 | all requested a scroll inside the same scrolling area as a result of the latest
225 | action. In the production environemnt the warning won't appear and just one
226 | scroll will happen.
227 |
228 | ### - What if a scroll gets triggered while another scroll is still running (in the same scrolling area)?
229 |
230 | The running scroll will stop and the new scroll will start.
231 |
232 | ### - Is there a way to know when a scroll has finished?
233 |
234 | Yes. You can use the `onEnd` function.
235 |
236 | ### - Can I dispatch an action once a scroll has finished?
237 |
238 | Yes. The first argument of the `onEnd` function is the `store.dispatch`.
239 | Use it to dispatch another action.
240 |
241 | ### - Is there a way to know if the scroll got cancelled?
242 |
243 | Yes. The second argument of the `onEnd` function is a boolean value that
244 | indicates whether or not the scroll got canceled.
245 |
246 | ### - Is this library compatible with IE9?
247 |
248 | Yes.
249 |
250 | ### - What's the size of this library?
251 |
252 | Without its peer dependencies, the gzipped size is < 5Kb.
253 |
254 | ## Rationale
255 |
256 | So, you have your nice and functional React-Redux app: no stateful
257 | components, everything that gets rendered is in response to the
258 | state of your store... And now a new requirement comes in:
259 | "whenever this or that happens we need a smooth scroll towards
260 | that component". Now what? How are we going to make that scroll happen?
261 | Maybe we could add a boolean entry in the state like: `needsToScroll`
262 | and then use the lifecycle event `componentWillReceiveProps` to trigger a scroll
263 | whenever that value changes from `false` to `true`... And hope that no other
264 | component instance is trying to do the same thing. We would also
265 | have to dispatch another action when the scroll finishes to set
266 | that entry back to `false`. And how do we cancel that scroll if now another
267 | acction happened that requires that scroll to be directed somewhere else?
268 | A bit messy, and convoluted, right?
269 |
270 | This library helps you manage the scrolls of your app declaratively,
271 | while keeping your presentational components decoupled from the actions
272 | and the state of the app... You won't need to deal with "refs", "classes" or
273 | lifecycle events.
274 |
--------------------------------------------------------------------------------