|
| 1 | +# linkState |
| 2 | + |
| 3 | +> Create an Event handler function that sets a given state property. Works with [preact] and [react]. |
| 4 | +
|
| 5 | +- **Tiny:** less than **300 bytes** of [ES3](https://unpkg.com/linkstate) gzipped |
| 6 | +- **Familiar:** it's just a function that does what you would have done manually |
| 7 | +- **Standalone:** one function, no dependencies, works everywhere |
| 8 | + |
| 9 | +> 🤔 **Why?** |
| 10 | +> |
| 11 | +> linkState() is memoized: it only creates a handler once for each `(key, eventPath)` combination. |
| 12 | +> |
| 13 | +> This is important for performance, because it prevents handler thrashing and avoids allocations during render. |
| 14 | +
|
| 15 | +* * * |
| 16 | + |
| 17 | +## Table of Contents |
| 18 | + |
| 19 | +- [Installation](#installation) |
| 20 | +- [How It Works](#how-it-works) |
| 21 | +- [Usage](#usage) |
| 22 | +- [Contribute](#contribute) |
| 23 | +- [License](#license) |
| 24 | + |
| 25 | +* * * |
| 26 | + |
| 27 | +## Installation |
| 28 | + |
| 29 | +```sh |
| 30 | +npm install --save linkstate |
| 31 | +``` |
| 32 | + |
| 33 | +The [UMD](https://github.com/umdjs/umd) build is also available on [unpkg](https://unpkg.com/linkstate/dist/linkstate.umd.js): |
| 34 | + |
| 35 | +```html |
| 36 | +<script src="//unpkg.com/linkstate/dist/linkstate.umd.js"></script> |
| 37 | +``` |
| 38 | + |
| 39 | +This exposes the `linkState()` function as a global. |
| 40 | + |
| 41 | +* * * |
| 42 | + |
| 43 | +## How It Works |
| 44 | + |
| 45 | +It's important to understand what linkState does in order to use it comfortably. |
| 46 | + |
| 47 | +**`linkState(component, statePath, [valuePath])`** |
| 48 | + |
| 49 | +- `component`: the Component instance to call `setState()` on |
| 50 | +- `statePath`: a key/path to update in state - can be dot-notated for deep keys |
| 51 | +- `valuePath`: _optional_ key/path into the event object at which to retrieve the new state value |
| 52 | + |
| 53 | +It's easiest to understand these arguments by looking at a simplified implementation of linkState itself: |
| 54 | + |
| 55 | +```js |
| 56 | +function linkState(component, statePath, valuePath) { |
| 57 | + return event => { |
| 58 | + let update = {}; |
| 59 | + update[statePath] = event[valuePath]; |
| 60 | + component.setState(update); |
| 61 | + }; |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +In reality, accounting for dot-notated paths makes this trickier, but the result is the same. |
| 66 | + |
| 67 | +Here's two equivalent event handlers, one created manually and one created with linkState: |
| 68 | + |
| 69 | +```js |
| 70 | +handleInput = e => { |
| 71 | + this.setState({ foo: e.target.value }) |
| 72 | +} |
| 73 | + |
| 74 | +handleInput = linkState(this, 'foo') |
| 75 | +``` |
| 76 | + |
| 77 | +Notice how we didn't specify the event path - if omitted, `linkState()` will use the `checked` or `value` property of the event target, based on its type. |
| 78 | + |
| 79 | +## Usage |
| 80 | + |
| 81 | +Standard usage is simply a function that returns an event handler to update state: |
| 82 | + |
| 83 | +```js |
| 84 | +import linkState from 'linkstate'; |
| 85 | + |
| 86 | +class Foo extends Component { |
| 87 | + state = { |
| 88 | + text: '' |
| 89 | + }; |
| 90 | + render(props, state) { |
| 91 | + return ( |
| 92 | + <input |
| 93 | + value={state.text} |
| 94 | + onInput={linkState(this, 'text')} |
| 95 | + /> |
| 96 | + ); |
| 97 | + } |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +You can also use it as a [**polyfill**](https://ponyfill.com/#polyfill). This emulates the behavior of Preact 7.x, which provided `linkState()` as a method on its `Component` class. Since you're then calling `linkState()` as a method of the component instance, you won't have to pass in `component` as an argument: |
| 102 | + |
| 103 | +```js |
| 104 | +import 'linkstate/polyfill'; |
| 105 | + |
| 106 | +// Component.prototype.linkState is now installed! |
| 107 | + |
| 108 | +class Foo extends Component { |
| 109 | + state = { |
| 110 | + text: '' |
| 111 | + }; |
| 112 | + render(props, state) { |
| 113 | + return ( |
| 114 | + <input |
| 115 | + value={state.text} |
| 116 | + onInput={this.linkState('text')} |
| 117 | + /> |
| 118 | + ); |
| 119 | + } |
| 120 | +} |
| 121 | +``` |
| 122 | + |
| 123 | + |
| 124 | +* * * |
| 125 | + |
| 126 | +## Contribute |
| 127 | + |
| 128 | +First off, thanks for taking the time to contribute! |
| 129 | +Now, take a moment to be sure your contributions make sense to everyone else. |
| 130 | + |
| 131 | +### Reporting Issues |
| 132 | + |
| 133 | +Found a problem? Want a new feature? First of all see if your issue or idea has [already been reported](../../issues). |
| 134 | +If it hasn't, just open a [new clear and descriptive issue](../../issues/new). |
| 135 | + |
| 136 | +### Submitting pull requests |
| 137 | + |
| 138 | +Pull requests are the greatest contributions, so be sure they are focused in scope, and do avoid unrelated commits. |
| 139 | + |
| 140 | +> 💁 **Remember: size is the #1 priority.** |
| 141 | +> |
| 142 | +> Every byte counts! PR's can't be merged if they increase the output size much. |
| 143 | +
|
| 144 | +- Fork it! |
| 145 | +- Clone your fork: `git clone https://github.com/<your-username>/linkstate` |
| 146 | +- Navigate to the newly cloned directory: `cd linkstate` |
| 147 | +- Create a new branch for the new feature: `git checkout -b my-new-feature` |
| 148 | +- Install the tools necessary for development: `npm install` |
| 149 | +- Make your changes. |
| 150 | +- `npm run build` to verify your change doesn't increase output size. |
| 151 | +- `npm test` to make sure your change doesn't break anything. |
| 152 | +- Commit your changes: `git commit -am 'Add some feature'` |
| 153 | +- Push to the branch: `git push origin my-new-feature` |
| 154 | +- Submit a pull request with full remarks documenting your changes. |
| 155 | + |
| 156 | +## License |
| 157 | + |
| 158 | +[MIT License](LICENSE.md) © [Jason Miller](https://jasonformat.com/) |
0 commit comments