Skip to content

Commit 51b7088

Browse files
cdoublevcdoublev
committed
doc(README) Rewording/reformatting
1 parent ef1c460 commit 51b7088

1 file changed

Lines changed: 71 additions & 58 deletions

File tree

‎README.md‎

Lines changed: 71 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ It will stop executing `Function` if:
101101

102102
## useGatherMemo
103103

104-
`useGatherMemo` abstracts merging, gathering, and/or picking properties from object(s), while memoizing the result, ie. by preserving reference(s).
104+
`useGatherMemo` abstracts gathering (merging) and/or picking (destructuring) properties from object(s) while memoizing the result to avoid unneeded updates in the component and its children.
105105

106106
It's a low level hook that can be usefull eg. when you want to merge options or props received in a hook or a component with a large default options object, instead of listing each option argument with a default value and/or listing each one as a dependency of a hook.
107107

@@ -110,20 +110,31 @@ It's a low level hook that can be usefull eg. when you want to merge options or
110110
**Example:**
111111

112112
```js
113-
const options = { color: 'red', size: 'large' }
114-
115-
// 1. Pick prop(s) and gather the rest
116-
// Both constants will be defined with a memoized value/reference,
117-
// if `options` shallow equals its previous render value
118-
const [color, subOptions] = useGatherMemo(options, 'color')
119-
/* { color, ...rest } = options */
120-
console.log(color, subOptions) // 'red' { size: 'large' }
121-
122-
// 2. Merge properties
123-
// `allOptions` will be defined with a memoized reference,
124-
// if `subOptions` shallow equals its previous render value
125-
const allOptions = useGatherMemo({ ...subOptions, display: 'fullscreen' })
126-
console.log(allOptions) // { size: 'large', display: 'fullscreen' }
113+
const options = { color: 'red', size: 'large' }
114+
115+
/**
116+
* 1. Pick prop(s) and gather the rest
117+
*
118+
* Both constants will be defined with a memoized value/reference, if `options`
119+
* shallow equals its previous render value
120+
*/
121+
122+
// Write this:
123+
const [color, subOptions] = useGatherMemo(options, 'color')
124+
// Instead of this:
125+
const { color, ...subOptions } = options
126+
127+
/**
128+
* 2. Gather properties
129+
*
130+
* `allOptions` will be defined with a memoized reference, if `subOptions`
131+
* shallow equals its previous render value.
132+
*/
133+
134+
// Write this:
135+
const allOptions = useGatherMemo({ ...subOptions, display: 'fullscreen' })
136+
// Instead of this:
137+
const allOptions = { ...subOptions, display: 'fullscreen' }
127138
```
128139

129140
**Warning:** don't over use it, ie. use it only with large objects, otherwise it will negatively impact performances by increasing the call stack as well as the amount of data stored in memory.
@@ -246,59 +257,61 @@ It returns any error message from the Constraint Validation API, and a collectio
246257

247258
`<Filter>` provides common filter effects to use in a `SVGElement`.
248259

249-
**Effect `name`s and props:**
260+
**Usage for a single filter effect:**
250261

251-
| Name | Props |
252-
| ---------------- | ------------------------------------------- |
253-
| color-correction | lightness, opacity, saturation |
254-
| glow | blur, spread, lightness, opacity |
255-
| glow-inset | blur, threshold, lightness, opacity |
256-
| gooey | tolerance |
257-
| noise | frequency, blend, color, lightness, opacity |
258-
| shadow | offsetX, offsetY, blur, spread, opacity |
259-
| shadow-inset | offsetX, offsetY, blur, threshold, opacity |
262+
```js
263+
<svg viewBox='0 0 100 100'>
264+
<Filter id='glow-large' name='glow' blur='10' spread='3' opacity='0.3' />
265+
<Filter id='glow-small' name='glow' blur='5' spread='2' opacity='0.7' />
266+
<circle filter='url(#glow-large)' cx='25' cy='25' r='25'>
267+
<circle filter='url(#glow-small)' cx='75' cy='75' r='25'>
268+
</svg>
269+
```
260270

261-
Default values:
271+
When used alone, `<Filter>` should not have a `in` or `result` and it will automatically be wrapped in a `<filter>` with the following default prop values:
262272

263-
- color: `'black'`
264-
- lightness: `1`
265-
- opacity: `0.5`
266-
- offsetX: `0`
267-
- offsetY: `0`
268-
- saturation: `1`
273+
- `'colorInterpolation'` (for the `color-interpolation-filter` attribute): `'sRGB'`
274+
- `'id'`: `'name'`
275+
- `'width'` and `'height'`: based on `'name'`
276+
- `'x'` and `'y'`: based on `'width'` and `'height'`
269277

270-
All props require a number, except `blend` (CSS blend mode) and `color` (CSS color).
278+
`'width'`, `'height'`, `'x'`, `'y'` should be provided as percentage values.
271279

272-
**Usage for a single filter effect:**
280+
All effect's names are listed further below.
281+
282+
**Usage for composing filter effects:**
273283

274284
```js
275-
<svg viewBox='0 0 100 100'>
276-
<Filter id='glow-large' name='glow' blur='10' spread='3' opacity='0.3' />
277-
<Filter id='glow-small' name='glow' blur='5' spread='2' opacity='0.7' />
278-
<circle filter='url(#glow-large)' cx='25' cy='25' r='25'>
279-
<circle filter='url(#glow-small)' cx='75' cy='75' r='25'>
280-
</svg>
285+
<svg viewBox='0 0 100 100'>
286+
<filter id='glow-noise' x='-100%' y='-100%' height='300%' width='300%'>
287+
<Filter name='glow' blur='10' spread='3' result='glow' />
288+
<Filter name='noise' in='glow' opacity='0.2' frequency='0.2' />
289+
</filter>
290+
<circle filter='url(#glow-noise)' cx='50' cy='50' r='25'>
291+
</svg>
281292
```
282293

283-
- it should not have a `in` or `result` prop
284-
- it will automatically be wrapped in a `<filter>`
285-
- default `'colorInterpolation'` (for the `color-interpolation-filter` attribute) is `'sRGB'`
286-
- default `'id'` is `'name'`
287-
- default `'width'`, `'height'` are based on `'name'`
288-
- default `'x'` is based on `'width'` and default `'y'` is based on `'height'`
289-
- `'width'`, `'height'`, `'x'`, `'y'` should be provided as percentage values
294+
When composed with each other, `<Filter>`s should have a `in` and a `result` prop, except the last `<Filter>`, which should only have a `in` prop.
290295

296+
**Effect `name`s and props:**
291297

292-
**Usage for composing filter effects:**
298+
| Name | Props |
299+
| ---------------- | --------------------------------------------------- |
300+
| color-correction | lightness, opacity, saturation |
301+
| glow | blur, spread, lightness, opacity |
302+
| glow-inset | blur, threshold, lightness, opacity |
303+
| gooey | tolerance |
304+
| noise | frequency, blend, color, lightness, opacity |
305+
| shadow | offsetX, offsetY, blur, spread, opacity, saturation |
306+
| shadow-inset | offsetX, offsetY, blur, spread, opacity, saturation |
293307

294-
```js
295-
<svg viewBox='0 0 100 100'>
296-
<filter id='glow-noise' x='-100%' y='-100%' height='300%' width='300%'>
297-
<Filter name='glow' blur='10' spread='3' result='glow' />
298-
<Filter name='noise' in='glow' opacity='0.2' frequency='0.2' />
299-
</filter>
300-
<circle filter='url(#glow-noise)' cx='50' cy='50' r='25'>
301-
</svg>
302-
```
308+
Default values:
309+
310+
- color: `'black'`
311+
- lightness: `1`
312+
- opacity: `0.5`
313+
- offsetX: `0`
314+
- offsetY: `0`
315+
- saturation: `1`
303316

304-
It should have a `in` and/or a `result` prop.
317+
All props require a number, except `blend` (CSS blend mode) and `color` (CSS color).

0 commit comments

Comments
 (0)