|
|
@@ -5,8 +5,10 @@
|
|
|
A lightweight state management layer for Alpine.js
|
|
|
|
|
|
|
|
|
+
|
|
|
|
|
|
-[](https://www.jsdelivr.com/package/gh/ryangjchandler/spruce)
|
|
|
+
|
|
|
+[](https://www.jsdelivr.com/package/gh/ryangjchandler/spruce)
|
|
|
|
|
|
## About
|
|
|
|
|
|
@@ -18,7 +20,7 @@ Many large frameworks have their own state management solutions. One thing these
|
|
|
|
|
|
Include the following `<script>` tag in the `<head>` of your document:
|
|
|
|
|
|
-```html
|
|
|
+``` html
|
|
|
<script src="https://cdn.jsdelivr.net/gh/ryangjchandler/spruce@0.x.x/dist/spruce.umd.js"></script>
|
|
|
```
|
|
|
|
|
|
@@ -28,19 +30,19 @@ Include the following `<script>` tag in the `<head>` of your document:
|
|
|
|
|
|
If you wish to include Spruce with your own bundle:
|
|
|
|
|
|
-```bash
|
|
|
+``` bash
|
|
|
yarn add @ryangjchandler/spruce
|
|
|
```
|
|
|
|
|
|
or:
|
|
|
|
|
|
-```bash
|
|
|
+``` bash
|
|
|
npm install @ryangjchandler/spruce --save
|
|
|
```
|
|
|
|
|
|
Then add the following to your script:
|
|
|
|
|
|
-```javascript
|
|
|
+``` javascript
|
|
|
import Spruce from '@ryangjchandler/spruce'
|
|
|
```
|
|
|
|
|
|
@@ -48,34 +50,34 @@ import Spruce from '@ryangjchandler/spruce'
|
|
|
|
|
|
To verify you have correctly installed Spruce, copy & paste the following code snippet into your project.
|
|
|
|
|
|
-```html
|
|
|
-<div x-data="{}" x-subscribe>
|
|
|
+``` html
|
|
|
+<div x-data>
|
|
|
<div x-show="$store.modal.open === 'login'">
|
|
|
- <p>
|
|
|
- This "login" modal isn't built with a11y in mind, don't actually use it
|
|
|
- </p>
|
|
|
+ <p>
|
|
|
+ This "login" modal isn't built with a11y in mind, don't actually use it
|
|
|
+ </p>
|
|
|
</div>
|
|
|
</div>
|
|
|
|
|
|
-<div x-data="{}" x-subscribe>
|
|
|
+<div x-data>
|
|
|
<div x-show="$store.modal.open === 'register'">
|
|
|
- <p>
|
|
|
- This "register" modal isn't built with a11y in mind, don't actually use it
|
|
|
- </p>
|
|
|
+ <p>
|
|
|
+ This "register" modal isn't built with a11y in mind, don't actually use it
|
|
|
+ </p>
|
|
|
</div>
|
|
|
</div>
|
|
|
|
|
|
-<div x-data="{}" x-subscribe>
|
|
|
- <select x-model="$store.modal.open">
|
|
|
- <option value="login" selected>login</option>
|
|
|
- <option value="register">register</option>
|
|
|
- </select>
|
|
|
+<div x-data>
|
|
|
+ <select x-model="$store.modal.open">
|
|
|
+ <option value="login" selected>login</option>
|
|
|
+ <option value="register">register</option>
|
|
|
+ </select>
|
|
|
</div>
|
|
|
|
|
|
<script>
|
|
|
- Spruce.store('modal', {
|
|
|
- open: 'login',
|
|
|
- });
|
|
|
+ Spruce.store('modal', {
|
|
|
+ open: 'login',
|
|
|
+ });
|
|
|
</script>
|
|
|
```
|
|
|
|
|
|
@@ -101,7 +103,7 @@ If you are importing Spruce into your own bundle, you can interact with it like
|
|
|
|
|
|
**store.js**
|
|
|
|
|
|
-```javascript
|
|
|
+```js
|
|
|
import Spruce from '@ryangjchandler/spruce'
|
|
|
|
|
|
Spruce.store('modals', {
|
|
|
@@ -113,7 +115,7 @@ export default Spruce
|
|
|
|
|
|
**app.js**
|
|
|
|
|
|
-```javascript
|
|
|
+```js
|
|
|
import './store'
|
|
|
import 'alpinejs'
|
|
|
```
|
|
|
@@ -122,21 +124,19 @@ import 'alpinejs'
|
|
|
|
|
|
### Subscribing your components
|
|
|
|
|
|
-To access the global state from your Alpine components, you can simply add the `x-subscribe` directive to your root component.
|
|
|
+Spruce hooks into Alpine using the "magic properties" API, meaning there are no extra steps needed. Start using the `$store` variable in your components right away.
|
|
|
|
|
|
```html
|
|
|
-<div x-data="{}" x-subscribe>
|
|
|
+<div x-data="{}">
|
|
|
<span x-text="$store.application.name"></span>
|
|
|
</div>
|
|
|
```
|
|
|
|
|
|
-This directive adds a new `$store` magic variable to your component. This can be used to "get" and "set" data in your global store.
|
|
|
-
|
|
|
### Defining global state
|
|
|
|
|
|
To define a piece of global state, you can use the `Spruce.store()` method:
|
|
|
|
|
|
-```javascript
|
|
|
+```js
|
|
|
Spruce.store('application', {
|
|
|
name: 'Amazing Alpine Application'
|
|
|
})
|
|
|
@@ -147,18 +147,18 @@ The first argument defines the top level property of the scope. The second argum
|
|
|
To access the `name` property, you can do the following inside of your component:
|
|
|
|
|
|
```html
|
|
|
-<div x-data="{}" x-subscribe>
|
|
|
+<div x-data="{}">
|
|
|
<span x-text="$store.application.name"></span>
|
|
|
</div>
|
|
|
```
|
|
|
|
|
|
-The `<span>` will now have "Amazing Alpine Application" set as its `innerText`.
|
|
|
+The `<span>` will now have "Amazing Alpine Application" set as its `innerText` .
|
|
|
|
|
|
### Modifying state from outside of Alpine
|
|
|
|
|
|
You can modify your global state from external scripts using the `Spruce.store()` method too:
|
|
|
|
|
|
-```javascript
|
|
|
+```js
|
|
|
Spruce.store('application', {
|
|
|
name: 'Amazing Alpine Application'
|
|
|
})
|
|
|
@@ -172,7 +172,7 @@ This will trigger Alpine to re-evaluate your subscribed components and re-render
|
|
|
|
|
|
A `Spruce.reset()` method is provided so that you can completely overwrite a global store:
|
|
|
|
|
|
-```javascript
|
|
|
+```js
|
|
|
Spruce.store('application', {
|
|
|
name: 'Amazing Alpine Application'
|
|
|
})
|
|
|
@@ -188,17 +188,15 @@ Calling the `reset` method will make the new state reactive and cause subscribed
|
|
|
|
|
|
You can register watchers in a similar fashion to Alpine. All you need is the full dot-notation representation of your piece of state and a callback.
|
|
|
|
|
|
-```html
|
|
|
-<script>
|
|
|
- Spruce.store('form', {
|
|
|
- name: 'Ryan',
|
|
|
- email: 'support@ryangjchandler.co.uk'
|
|
|
- })
|
|
|
+```js
|
|
|
+Spruce.store('form', {
|
|
|
+ name: 'Ryan',
|
|
|
+ email: 'support@ryangjchandler.co.uk'
|
|
|
+})
|
|
|
|
|
|
- Spruce.watch('form.email', (old, next) => {
|
|
|
- // do something with the values here
|
|
|
- })
|
|
|
-<script>
|
|
|
+Spruce.watch('form.email', (old, next) => {
|
|
|
+ // do something with the values here
|
|
|
+})
|
|
|
```
|
|
|
|
|
|
In the above snippet, when we change the value of `form.email` either from a component or externally in a separate JavaScript file, our callback will be invoked and will receive the old value, as well as the new value. This can be useful for running automatic inline validation when a property changes, or triggering an action elsewhere in another component without the need for dispatching events.
|
|
|
@@ -209,7 +207,7 @@ In the above snippet, when we change the value of `form.email` either from a com
|
|
|
|
|
|
Spruce ships with a basic event bus. It exposes two methods:
|
|
|
|
|
|
-* `Spruce.on(eventName, callback)` - this can be used to register an event listener. This will react to any internal events, such as `init`. Your callback will receive a single `detail` property which can any information from the event, as well as the global store.
|
|
|
+* `Spruce.on(eventName, callback)` - this can be used to register an event listener. This will react to any internal events, such as `init` . Your callback will receive a single `detail` property which contains any data sent from the event, as well as the global store.
|
|
|
|
|
|
```js
|
|
|
Spruce.on('init', ({ store }) => {
|
|
|
@@ -219,7 +217,7 @@ Spruce.on('init', ({ store }) => {
|
|
|
|
|
|
* `Spruce.once(eventName, callback)` - this can be used to register an event listener that is only run **a single time**. This is useful for one time events, such as fetching HTML from the server when hovering over a button or similar.
|
|
|
|
|
|
-```js
|
|
|
+``` js
|
|
|
Spruce.once('event', () => {
|
|
|
// do something once...
|
|
|
})
|
|
|
@@ -227,17 +225,15 @@ Spruce.once('event', () => {
|
|
|
|
|
|
* `Spruce.off(eventName, callback)` - this can be used to unhook or de-register an event listener.
|
|
|
|
|
|
-```js
|
|
|
+``` js
|
|
|
var callback = () => {}
|
|
|
|
|
|
Spruce.off('init', callback)
|
|
|
```
|
|
|
|
|
|
-> **Note**: When calling `Spruce.off()` directly, you **must** pass a named callback.
|
|
|
+You can also unhook a listener using the function returned by `Spruce.on()` . This is especially useful for anonymous function callbacks.
|
|
|
|
|
|
-You can also unhook a listener using the function returned by `Spruce.on()`. This is especially useful for anonymous function callbacks.
|
|
|
-
|
|
|
-```js
|
|
|
+``` js
|
|
|
var off = Spruce.on('event', () => {})
|
|
|
|
|
|
off()
|
|
|
@@ -245,35 +241,19 @@ off()
|
|
|
|
|
|
* `Spruce.emit(eventName, data = {})` - this can be used to emit an event. The first argument should be the name of the event, the second should be an object containing data. This will be merged in with the core data, which consists of a `store` property. When emitting an event, a browser event will also be dispatched with a `spruce:` prefix.
|
|
|
|
|
|
-```js
|
|
|
-Spruce.emit('event-name', { foo: 'bar' })
|
|
|
+``` js
|
|
|
+Spruce.emit('event-name', {
|
|
|
+ foo: 'bar'
|
|
|
+})
|
|
|
```
|
|
|
|
|
|
In the example above, a `spruce:event-name` event will be fired on the `window` level, so you could register an event listener inside of your Alpine component:
|
|
|
|
|
|
-```html
|
|
|
+``` html
|
|
|
<div x-data @spruce:event-name.window="foo = $event.detail.store.foo">
|
|
|
</div>
|
|
|
```
|
|
|
|
|
|
-### Removing the need for `x-subscribe`
|
|
|
-
|
|
|
-Alpine offers a Config API. Using this API, you can enable an experimental global `$store` variable that is declared on the `window` object. This means your components do not need to manually "subscribe" to state changes:
|
|
|
-
|
|
|
-```html
|
|
|
-<script>
|
|
|
- Spruce.config({
|
|
|
- globalStoreVariable: true
|
|
|
- })
|
|
|
-</script>
|
|
|
-
|
|
|
-<div x-data>
|
|
|
- <span x-text="$store.foo.bar"></span>
|
|
|
-</div>
|
|
|
-```
|
|
|
-
|
|
|
-> **Important**: This feature is **highly unoptimized** at the moment and will actually cause all of your Alpine components on the page to re-render. This is due to the limited API that Alpine exposes to third party libraries and the `$store` variable has no simple way of knowing which element is currently retrieving data from the global store.
|
|
|
-
|
|
|
## Versioning
|
|
|
|
|
|
This projects follow the [Semantic Versioning](https://semver.org/) guidelines. This means that there *could* be breaking changes on minor version changes, up until v1.x is reached.
|
Ryan Chandler
