https://github.com/kyleplump/ayr.js
A reactivity model designed for simplicity
https://github.com/kyleplump/ayr.js
javascript javascript-framework reactivity reactivity-system single-page-app
Last synced: 10 months ago
JSON representation
A reactivity model designed for simplicity
- Host: GitHub
- URL: https://github.com/kyleplump/ayr.js
- Owner: kyleplump
- License: mit
- Created: 2023-12-01T21:28:34.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-02-12T20:17:15.000Z (almost 2 years ago)
- Last Synced: 2025-03-21T15:09:37.869Z (11 months ago)
- Topics: javascript, javascript-framework, reactivity, reactivity-system, single-page-app
- Language: JavaScript
- Homepage:
- Size: 866 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# Ayr.js
Ayr.js is a reactivity model designed for simplicity. No build tools. No templating engines. Just HTML and Javascript.
## Installation
Import `Ayr.js` directly into your HTML from a CDN:
```html
import AC from 'https://unpkg.com/ayr.js';
```
Or install it with npm:
```bash
npm install ayr.js
yarn add ayr.js
```
## Usage/Examples
The core of `Ayr.js` is the 'Ayr Component' (`AC`). Ayr components are functions that take an Ayr config and translate that config object to reactive state. The three core pieces of an Ayr component are: `root`, `state`, and `effects`. (Full API below)
| option | Description |
| :-------- | :------------------------- |
| `root` | **Required**. Where the Ayr component should mount in the DOM |
| `state` | Reactive state variables |
| `effects` | Function that returns a function that mutate `state` variables |
An example Ayr component:
```javascript
AC({
root: '#my_component',
state: {
counter: 1,
},
effects: function() {
return {
incrementCounter: () => {
this.state.counter = this.state.counter + 1;
}
}
}
})
```
This Ayr component will be mounted at the HTML element with `id="my_component"`, and has one reactive `state` value ('counter'), with one `effect` ('incrementCounter').
Ayr components also have a HTML counterparts - attributes on your HTML elements telling `Ayr.js` where to render. Using the above Ayr component as an example, the corresponding HTML could look like this:
```html
Increment Value
Counter value:
```
Here you can see the `id="my_component"` (mirroring the `root` value of the `AC`), as well as two Ayr directives: `y-click` and `y-data`.
Whichever tag the `y-data` directive is attached to will render the value of the state variable passed. In this case, the `counter` state variable will render its current value in the `span` tag. The `y-click` directive is passed the 'incrementCounter' effect. When the `button` element is clicked, the 'incrementCounter' effect is called.
The full example:
```javascript
import AC from 'https://unpkg.com/ayr.js';
AC({
root: '#my_component',
state: {
counter: 1,
},
effects: function() {
return {
incrementCounter: () => {
this.state.counter = this.state.counter + 1;
}
}
}
})
Increment Value
Counter value:
```
### More Examples
#### Dependants
`Ayr.js` also has a concept of derived state in the form of `dependants`. '`dependants`' is an option for an Ayr component, which is a function that returns an object of functions, each returning some new state. The function name in the top object can then be used as a regular state variable, and bound using the `y-data` directive. Building off the counter example:
```javascript
import AC from 'https://unpkg.com/ayr.js';
AC({
root: '#my_component',
state: {
counter: 1,
},
effects: function() {
return {
incrementCounter: () => {
this.state.counter = this.state.counter + 1;
}
}
},
dependants: function() {
return {
doubledCounter: (e) => {
return this.state.counter * 2
},
tripledCounter: () => {
return this.state.counter * 3
}
}
}
})
Increment Value
Counter value:
Doubled:
Tripled:
```
These `dependants` will be updated whenever the state variable they depend on (in this case, 'counter') has been updated.
#### Conditional Rendering
The `y-if` directive can be passed a state variable, and that DOM node will only be shown when the state variable evaluates to `true`.
```javascript
import AC from 'https://unpkg.com/ayr.js';
AC({
root: '#my_component',
state: {
showMessage: false,
},
effects: function() {
return {
toggleMessage: () => {
this.state.showMessage = !this.state.showMessage;
}
}
}
})
Toggle Message
This is a dynamic message.
```
* Note: `y-if` does not remove the node completely, it merely toggles `display: none;` on the given element.
#### Looping
The `y-for` directive can be passed an iterable state variable, allowing you to create DOM elements by iterating through a list.
```javascript
import AC from 'https://unpkg.com/ayr.js';
AC({
root: '#my_component',
state: {
values: [ 'First Value', 'Second Value', 'Third Value' ],
}
})
```
## API Reference
#### Ayr Components
| AC option | Description |
| :-------- | :------------------------- |
| `root` | **Required**. Where the Ayr component should mount in the DOM |
| `state` | Reactive state variables |
| `effects` | Function that returns functions which mutate `state` variables |
| `dependants` | Function that returns derived state functions |
#### Ayr Directives
| Directive | Description |
| :-------- | :------------------------- |
| `y-data` | Binds node to AC state variable |
| `y-[event]` | Binds DOM `event` on the node to an AC effect (e.g.: `y-click`, `y-change`). See below for supported events |
| `y-if` | Binds visibility of a DOM node to the truthiness of a state variable |
| `y-for` | Loops over iterable state variable and renders child `y-data` |
* Supported `y-[event]` DOM events: `click`, `change`, `keydown`, `keyup`, `mouseover`, `mouseout`
## Contributing
Contributions are always welcome!
Please open a pull request or open an issue to collaborate.
## Notes
`Ayr.js` is not yet ready for use in production. This is an early stage project and the API is still subject to breaking changes. If you like `Ayr.js` check out the frameworks that inspired it:
- [Solid.js](https://www.solidjs.com/)
- [Alpine.js](https://alpinejs.dev/)
## Authors
- [@kyleplump](https://github.com/kyleplump)