aberdeen 0.4.0 → 0.5.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2021-2024 Frank van Viegen
+Copyright (c) 2021-2025 Frank van Viegen
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

package/README.md

@@ -1,130 +1,169 @@
 A TypeScript/JavaScript library for quickly building performant declarative user interfaces *without* the use of a virtual DOM.
 
-The key insight is the use of many small anonymous functions, that will automatically rerun when the underlying data changes. In order to trigger updates, that data should be encapsulated in any number of `Store` objects. They can hold anything, from simple values to deeply nested data structures, in which case user-interface functions can (automatically) subscribe to just the parts they depend upon.
-
+The key insight is the use of many small anonymous functions, that will automatically rerun when the underlying data changes. In order to trigger updates, that data should be encapsulated in any number of *proxied* JavaScript objects. They can hold anything, from simple values to complex and deeply nested data structures, in which case user-interface functions can (automatically) subscribe to just the parts they depend upon.
 
 ## Why use Aberdeen?
 
 - It provides a flexible and simple to understand model for reactive user-interface building.
 - It allows you to express user-interfaces in plain JavaScript (or TypeScript) in an easy to read form, without (JSX-like) compilation steps.
-- It's fast, as it doesn't use a *virtual DOM* and only reruns small pieces of code in response to updated data. It also makes displaying and updating sorted lists very easy and very fast.
-- It's lightweight, at about 16kb minimized and without any run-time dependencies.
-- It comes with batteries included, providing modules for..
+- It's fast, as it doesn't use a *virtual DOM* and only reruns small pieces of code, redrawing minimal pieces of the UI, in response to updated data. 
+- It makes displaying and updating sorted lists very easy and very fast.
+- It's tiny, at about 5kb (minimized and gzipped) and without any run-time dependencies.
+- It comes with batteries included:
   - Client-side routing.
-  - Optimistic user-interface updates (predictions) while awaiting a server response.
-  - Transitions.
+  - Revertible patches, for optimistic user-interface updates.
+  - Component-local CSS generator.
+  - Helper functions for reactively working with data, such as for deriving, (multi)mapping, filtering, partitioning and counting.
+  - A couple of add/remove transition effects, to get you started.
 
-## Examples
+## Why *not* use Aberdeen?
 
-- [Tic-tac-toe demo](https://vanviegen.github.io/aberdeen/examples/tic-tac-toe/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/tic-tac-toe)
-- [Input example demo](https://vanviegen.github.io/aberdeen/examples/input/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/input)
-- [List example demo](https://vanviegen.github.io/aberdeen/examples/list/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/list)
-- [Routing example demo](https://vanviegen.github.io/aberdeen/examples/router/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/router)
+- There are not many of us -Aberdeen developers- yet, so don't expect terribly helpful StackOver/AI answers.
+- You'd have to code things yourself, instead of duct-taping together a gazillion React ecosystem libraries.
 
+## Example code
 
-To get a quick impression of what Aberdeen code looks like, this is all of the JavaScript for the above Tic-tac-toe demo:
+To get a quick impression of what Aberdeen code looks like, below is a Tic-tac-toe app with undo history. If you're reading this on [the official website](https://vanviegen.github.io/aberdeen/README/) you should see a working demo below the code, and an 'edit' button in the top-right corner of the code, to play around.
 
 ```javascript
-import {$, mount, Store} from 'https://cdn.jsdelivr.net/npm/aberdeen/+esm';
+import {$, proxy, onEach, insertCss, observe} from "aberdeen";
 
-// Observable data
-const squares = new Store([]) // eg. ['X', undefined, 'O', 'X']
-const history = new Store([[]]) // eg. [[], [undefined, undefined, undefined, X], ...]
-const historyPos = new Store(null) // set while 'time traveling' our undo history
+// Helper functions
 
-// Derived data
-const winner = squares.derive(calculateWinner) // 'X', 'O' or undefined
-const player = squares.derive(sq => sq.filter(v => v).length % 2 ? "O" : "X") // 'X' or 'O'
+function calculateWinner(board) {
+    const lines = [
+        [0, 1, 2], [3, 4, 5], [6, 7, 8], // horizontal
+        [0, 3, 6], [1, 4, 7], [2, 5, 8], // vertical
+        [0, 4, 8], [2, 4, 6] // diagonal
+    ];
+    for (const [a, b, c] of lines) {
+        if (board[a] && board[a] === board[b] && board[a] === board[c]) {
+            return board[a];
+        }
+    }
+}
 
-// Rendering functions
+function getCurrentMarker(board) {
+	return board.filter(v => v).length % 2 ? "O" : "X";
+}
 
-function drawSquare(position) {
-	$('button.square', () => {
-		let value = squares(position).get()
-		if (value) $({text: value})
-		else $({click: () => fillSquare(position)})
-	})
+function getBoard(history) {
+    return history.boards[history.current];
 }
 
-function drawBoard() {
-	for(let y=0; y<3; y++) {
-		$('div.board-row', () => {
-			for(let x=0; x<3; x++) {
-				drawSquare(y*3 + x)
-			}
-		})
-	}
+function markSquare(history, position) {
+    const board = getBoard(history);
+
+    // Don't allow markers when we already have a winner
+    if (calculateWinner(board)) return;
+
+    // Copy the current board, and insert the marker into it
+    const newBoard = board.slice();
+    newBoard[position] = getCurrentMarker(board);
+    
+    // Truncate any future states, and write a new future
+    history.current++;
+    history.boards.length = history.current;
+    history.boards.push(newBoard);
 }
 
-function drawInfo() {
-	$('div', () => {
-		if (winner.get()) {
-			$({text: `Winner: ${winner.get()}!`})
-		} else {
-			$({text: `Current player: ${player.get()}`})	
-		}
-	})
-	$('.buttons', () => {
-		history.onEach(item => {
-			$('button', {
-				text: item.index() ? `Go to move ${item.index()}` : `Go to game start`,
-				click: () => {
-					historyPos.set(item.index())
-					squares.set(item.get())
-				},
-			})
-		})
-	})
+// Define component-local CSS, which we'll utilize in the drawBoard function.
+// Of course, you can use any other styling solution instead, if you prefer.
+
+const boardStyle = insertCss({
+    display: 'grid',
+    gap: '0.5em',
+    gridTemplateColumns: '1fr 1fr 1fr',
+    '> *': {
+        width: '2em',
+        height: '2em',
+        padding: 0,
+    },
+});
+
+// UI drawing functions.
+
+function drawBoard(history) {
+    $('div', boardStyle, () => {
+        for(let pos=0; pos<9; pos++) {
+            $('button.square', () => {
+                let marker = getBoard(history)[pos];
+                if (marker) {
+                    $({ text: marker });
+                } else {
+                    $({ click: () => markSquare(history, pos) });
+                }
+            });
+        }
+    })
 }
 
-// Helper functions
+function drawStatusMessage(history) {
+    $('h4', () => {
+        // Reruns whenever observable data read by calculateWinner or getCurrentMarker changes
+        const board = getBoard(history);
+        const winner = calculateWinner(board);
+        if (winner) {
+            $(`:Winner: ${winner}!`);
+        } else if (board.filter(square=>square).length === 9) {
+            $(`:It's a draw...`);
+        } else {
+            $(`:Current player: ${getCurrentMarker(board)}`);
+        }
+    });
+}
 
-function fillSquare(position) {
-	// If there's already a winner, don't allow a new square to be filled
-	if (winner.peek()) return
-
-	// Fill the square
-	squares(position).set(player.get())
-	
-	if (historyPos.get() != null) {
-		// Truncate everything after history pos
-		history.modify(h => h.slice(0, historyPos.get()+1))
-		// Stop 'time traveling'
-		historyPos.set(null)
-	}
-	
-	// Append the current squares-state to the history array 
-	history.push(squares.get())
+function drawTurns(history) {
+    $('div:Select a turn:')
+    // Reactively iterate all (historic) board versions
+    onEach(history.boards, (_, index) => {
+        $('button', {
+            // A text node:
+            text: index,
+            // Conditional css class:
+            ".outline": observe(() => history.current != index),
+            // Inline styles:
+            $marginRight: "0.5em",
+            $marginTop: "0.5em",
+            // Event listener:
+            click: () => history.current = index,
+        });
+    });
 }
 
-function calculateWinner(squares) {
-	const lines = [
-		[0, 1, 2], [3, 4, 5], [6, 7, 8], // horizontal
-		[0, 3, 6], [1, 4, 7], [2, 5, 8], // vertical
-		[0, 4, 8], [2, 4, 6] // diagonal
-	];
-	for (const [a, b, c] of lines) {
-		if (squares[a] && squares[a] === squares[b] && squares[a] === squares[c]) {
-			return squares[a];
-		}
-	}
+function drawMain() {
+    // Define our state, wrapped by an observable proxy
+    const history = proxy({
+        boards: [[]], // eg. [[], [undefined, 'O', undefined, 'X'], ...]
+        current: 0, // indicates which of the boards is currently showing
+    });
+
+    $('main.row', () => {
+        $('div.box', () => drawBoard(history));
+        $('div.box', {$flex: 1}, () => {
+            drawStatusMessage(history);
+            drawTurns(history);
+        });
+    });
 }
 
-// Fire it up!
- 
-mount(document.body, () => {
-	$('.game', () => {
-		$('.game-board', drawBoard)
-		$('.game-info', drawInfo)
-	})
-})
+// Fire it up! Mounts on document.body by default..
+
+drawMain();
 ```
 
+Some further examples:
+
+- [Input example demo](https://vanviegen.github.io/aberdeen/examples/input/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/input)
+- [List example demo](https://vanviegen.github.io/aberdeen/examples/list/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/list)
+- [Routing example demo](https://vanviegen.github.io/aberdeen/examples/router/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/router)
+- [JS Framework Benchmark demo](https://vanviegen.github.io/aberdeen/examples/js-framework-benchmark/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/js-framework-benchmark)
 
-## Reference documentation
 
-https://vanviegen.github.io/aberdeen/modules.html
+## Documentation
 
+- [Tutorial](https://vanviegen.github.io/aberdeen/Tutorial/)
+- [Reference documentation](https://vanviegen.github.io/aberdeen/modules.html)
 
 ## Roadmap
 
@@ -132,8 +171,7 @@ https://vanviegen.github.io/aberdeen/modules.html
 - [x] A better alternative for scheduleTask.
 - [x] A simple router.
 - [x] Optimistic client-side predictions.
-- [ ] Support for (component local) CSS or possibly a tailwind-like abstraction.
-- [ ] More user friendly documentation generator.
+- [x] Performance profiling and tuning regarding lists.
+- [x] Support for (component local) CSS
 - [ ] Architecture document.
 - [ ] SVG support.
-- [ ] Performance profiling and tuning regarding lists.