Vouivre

Vouivre is a lightweight reactive library with easy templating syntax and powerful data binding to enhance your html views. Based on javascript Proxy and a syntax inspired by tinybind/rivets.

Installation

You can install Vouivre using the package manager

npm install vouivre

and import in your project using a bundler like webpack or vite

import vouivre from "vouivre"

Or you can grab the release on github and use it in a script tag directly.

<script src="./vouivre.min.js"></script>

Usage

Template syntax

The templating syntax allows you to bind your HTML DOM elements to an object of data in javascript. The template uses different attributes prefixed with v- or text wrapped in brackets { ... } (aka text interpolation).

<article>
	<address>
		<a rel="author" v-href="author.link">{ author.firstName } { author.lastName }</a>
	</address>
</article>

vouivre.bind(document.body, {
	author: {
		firstName: "John",
		lastName: "Doe",
		link: "/authors/john-doe/"
	}
});

Vouivre binds HTML elements to the model's property and observes modifications using a Proxy. When a property is modified in the model, only the corresponding bindings are updated, ensuring minimal DOM manipulations and maximum performance.
You can use multiple models bound to different parts of your HTML, in this example we use a single model bound to document.body.

Listening to Events

The on directive is used to bind event to an element.

<main>
	<button v-on-click="addOne"></button>
	<span>{ count }</span>
</main>

const model = vouivre.bind(document.body, {
	count: 0,
	addOne() {
		model.count++;
	}
});

Iterating with foreach

The foreach directive is a special one, usable only on template elements. It creates a scope for each iterated item. The name of the scope variable is the parameter of the directive v-foreach-*. Children elements can access this bound variable as well as a special variable $index.

<ol>
	<template v-foreach-person="persons">
		<li>
			<div>{ $index }</div>
			<div>{ person.name }</div>
			<button v-on-click="remove">Remove<button>
		</li>
	</template>
</ol>

Foreach supports all array operations, from adding and removing items to reordering the whole array. Moving elements in the array will just move HTML elements to match the new order with moveBefore, keeping the state of the node.

const model = vouivre.bind(document.body, {
	persons: [
		{
			name: "Kira"
		},
		{
			name: "Wellan"
		}
	],
	remove(event, scope) {
		persons.splice(scope.$index, 1);
	}
});

Event listeners receive a scope object as a second argument, with all the scoped variables, the index $index and the parent scope $parent.

Binding inputs

The binding directive allows you to create a bidirectional bind between the model value and an input element. This means that the model is updated when the user interacts with the form inputs, and the inputs are updated when the model is modified.

<form>
	<input type="text" v-bind="author.firstName" />
	<input type="number" v-bind="author.age" />
	<!-- Select with array of options -->
	<select v-bind="selectedOptions" multiple size="3">
		<template v-foreach-option="options">
			<option v-value="option">{ option }</option>
		</template>
	</select>
	<!-- Checkboxes with array of options -->
	<template v-foreach-option="options">
		<div class="control">
			<input v-id="option" type="checkbox" name="pays" v-bind="selectedOptions" v-value="option" />
			<label v-for="option">{ option }</label>
		</div>
	</template>
</form>

vouivre.bind(document.body, {
	author: {
		firstName: "Alban"
		age: 20,
	},
	options: ["France", "Italie", "Allemagne", "Suisse"],
	selectedOptions: [] // {} and new Set() are also supported
})

Built-in Directives

The asterisk * denotes a directive that receives an argument.
v-foreach-* creates one instance of the template foreach item in the array. Each instance has access to the array item using the variable name you pass as argument.
v-text sets the element text the same way as text interpolation does.
v-show changes the display of the element using css.
v-if adds or removes the element from the DOM depending on the value.
v-enabled enables or disables the element (for example a button).
v-on-* binds a function of the model to the event you pass as argument.
v-class-* adds or removes a css class.
v-attr-* adds or removes an HTML attribute.
v-prop-* sets the value of a property on the element.
v-* sets the value of an HTML attribute.

Modifiers

Modifiers are used to alter the value of a binding. They can format the value as time or percentage, or add simple logic like inverting a value with not or comparing with is. Modifiers are applied after the property path delimited by :. First comes the modifier name, and then a list of parameters if needed. You can also chain modifiers.

<div v-show="isPrivate : not">public</div>
<div v-text="now :time"></div>
<button v-show="status :is connected :not">Login</div>

vouivre.bind(document.body, { isPrivate: true, now: Date.now(), status: "connected" });

Parameters of the modifier can be model properties, scope variables or primitives (string, number etc.). Properties will automatically be resolved and put in the watch list as a dependency of the binding, so that it updates when the value changes.

<button v-on-click="sort :call name">public</div>

Built-in Modifiers

watch [property1] [property2] ... adds model properties to the list of dependencies to watch.
not inverts the value.
is [propertyOrValue] compares the value to the value of a model property or a primitive value.
args [arg1] [arg2] ... add arguments that will be passed to the event listeners bound with on-*.
call [arg1] [arg2] ... calls a function with the list of arguments.
get [prop] returns the property 'prop' of the object. Usually used when 'prop' is a variable name of a property of the object.

Computed properties

<div v-text="fullname"></div>

vouivre.bind(document.body, {
	firstName: "John",
	lastName: "Doe",
	get fullname() {
		return this.firstName + " " + this.lastName;
	},
	fullname_dependencies: ["firstName", "lastName"]
});

You can tell the binding what are the dependencies of this computed property with an array with the same name as the getter + _dependencies. Or if you prefer you can use the watch modifier directly in the attribute.

Custom directives

You can add your own custom directives to vouivre before binding the model to your view.

vouivre.directives["color"] = {
	bind(element, value) {
		// called once before any update
		// can be used to register event listeners
	},
	unbind(element, value) {
		// unregister things
	}
	update(element, value) {
		// called on every watched properties value change
		element.style.color = value;
		// can call your own functions
		this.extra.myFunction();
	},
	// optional extra data and functions
	extra: {
		myFunction() {

		}
	},
};

All hooks are optional. Another example, this time with an argument passed to the directive.

vouivre.directives["on-*"] = {
	bind: function (el, value) {
		el.addEventListener(this.args[0], (e) => value(e));
	},
}

Custom modifiers

Modifiers work almost the same as directives, all hooks are optional, and the binding is accessible via this.binding.
This example uses another feature, the ability to watch changes on all properties of an object by adding * to the object path array.

vouivre.modifiers["toString"] = {
	bind(value) {
		this.binding.watch([...this._path, "*"]);
	},
	unbind(value) {
		
	},
	read(value) {
		if (value instanceof Object) {
			return JSON.stringify(value);
		}
		return value.toString();
	},
	write(value) {
		return value;
	}
};
vouivre.bind(document.body, { author: { firstName: "John", lastName: "Doe" } });

<pre v-text="author : toString"></pre>

Advanced example

In this example we render a list of persons in a table with an input text to filter the entries and buttons on each column to sort the list in ascending or descending order by this column field. The table body is filled by two imbricated foreach, one iterating the list and the other iterating the columns we chose to render.

<input type="text" v-bind="filterName">
<table>
	<thead>
		<tr>
			<th><abbr title="Position">Pos</abbr></th>
			<template v-foreach-column="columns">
				<th>
					<div class="row">
						<span class="flex">{ column }</span>
						<button
							class="sort-btn"
							v-attr-disabled="isCurrentSort :call sortColumn column sortOrder desc"
							v-on-click="sort :args column desc"
						>
							↓</button
						><button
							class="sort-btn"
							v-attr-disabled="isCurrentSort :call sortColumn column sortOrder asc"
							v-on-click="sort :args column asc"
						>
							↑
						</button>
					</div>
				</th>
			</template>
		</tr>
	</thead>
	<tbody>
		<template v-foreach-person="filteredPersons">
			<tr>
				<th>{ $index }</th>
				<template v-foreach-field="columns">
					<td>{ person :get field }</td>
				</template>
			</tr>
		</template>
	</tbody>
</table>

vouivre.bind(document.body, {
	persons: [
		{
			firstName: "Merwyn",
			lastName: "Ril' Avalon",
		},
		{
			firstName: "Edwin",
			lastName: "Til' Illan",
		},
		{
			firstName: "Ewilan",
			lastName: "Gil' Sayan",
		},
		{
			firstName: "Duom",
			lastName: "Nil' Erg",
		},
		{
			firstName: "Bjorn",
			lastName: "Wil' Wayard",
		},
	],
	columns: ["firstName", "lastName"],
	
	sortColumn: undefined,
	sortOrder: "desc",
	sort(e, scope, key, order) {
		model.persons.sort((a, b) => (order == "desc" ? 1 : -1) * a[key].localeCompare(b[key]));
		model.sortColumn = key;
		model.sortOrder = order;
	},
	isCurrentSort(currentKey, key, currentOrder, order) {
		return currentKey == key && currentOrder == order;
	},
	
	filterName: "",
	get filteredPersons() {
		if (this.filterName == "") return this.persons;
		return this.persons.filter((p) =>
			p.firstName.startsWith(this.filterName) || p.lastName.startsWith(this.filterName));
	},
	filteredPersons_dependencies: ["filterName", "persons"]
});