aberdeen 0.5.0 → 1.0.4

package/README.md

@@ -1,177 +1,179 @@
-A TypeScript/JavaScript library for quickly building performant declarative user interfaces *without* the use of a virtual DOM.
+# [Aberdeen](https://aberdeenjs.org/) [![](https://img.shields.io/badge/license-ISC-blue.svg)](https://github.com/vanviegen/aberdeen/blob/master/LICENSE.txt) [![](https://badge.fury.io/js/aberdeen.svg)](https://badge.fury.io/js/aberdeen) ![](https://img.shields.io/bundlejs/size/aberdeen) [![](https://img.shields.io/github/last-commit/vanviegen/aberdeen)](https://github.com/vanviegen/aberdeen)
 
-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.
+Build blazing-fast, reactive UIs in pure TypeScript/JavaScript – no virtual DOM.
+
+Aberdeen offers a refreshingly simple approach to reactive UIs. Its core idea:
+
+> Use many small, anonymous functions for emitting DOM elements, and automatically rerun them when their underlying *proxied* data changes. This proxied data can be anything from simple values to complex, typed, and deeply nested data structures.
+
+Now, let's dive into why this matters...
 
 ## 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, 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.
-  - 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.
+- 🎩 **Simple:** Express UIs naturally in JavaScript/TypeScript, without build steps or JSX, and with a minimal amount of concepts you need to learn.
+- ⏩ **Fast:** No virtual DOM. Aberdeen intelligently updates only the minimal, necessary parts of your UI when proxied data changes.
+- 👥 **Awesome lists**: It's very easy and performant to reactively display data sorted by whatever you like.
+- 🔬 **Tiny:** Around 5KB (minimized and gzipped) and with zero runtime dependencies.
+- 🔋 **Batteries included**: Comes with client-side routing, revertible patches for optimistic user-interface updates, component-local CSS, helper functions for transforming reactive data (mapping, partitioning, filtering, etc) and hide/unhide transition effects. No bikeshedding required!
 
 ## Why *not* use Aberdeen?
 
-- 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.
+- 🤷 **Lack of community:** There are not many of us -Aberdeen developers- yet, so don't expect terribly helpful Stack Overflow/AI answers.
+- 📚 **Lack of ecosystem:** You'd have to code things yourself, instead of duct-taping together a gazillion React ecosystem libraries.
 
-## Example code
+## Examples
 
-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.
+First, let's start with the obligatory reactive counter example. If you're reading this on [the official website](https://aberdeenjs.org) 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 {$, proxy, onEach, insertCss, observe} from "aberdeen";
-
-// Helper functions
-
-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];
-        }
-    }
-}
+import {$, proxy, ref} from 'aberdeen';
 
-function getCurrentMarker(board) {
-	return board.filter(v => v).length % 2 ? "O" : "X";
-}
+// Define some state as a proxied (observable) object
+const state = proxy({question: "How many roads must a man walk down?", answer: 42});
 
-function getBoard(history) {
-    return history.boards[history.current];
-}
+$('h3', () => {
+    // This function reruns whenever the question or the answer changes
+    $(`:${state.question} ↪ ${state.answer || 'Blowing in the wind'}`)
+});
 
-function markSquare(history, position) {
-    const board = getBoard(history);
+// Two-way bind state.question to an <input>
+$('input', {placeholder: 'Question', bind: ref(state, 'question')})
 
-    // Don't allow markers when we already have a winner
-    if (calculateWinner(board)) return;
+// Allow state.answer to be modified using both an <input> and buttons
+$('div.row', {$marginTop: '1em'}, () => {
+    $('button:-', {click: () => state.answer--});
+    $('input', {type: 'number', bind: ref(state, 'answer')})
+    $('button:+', {click: () => state.answer++});
+});
+```
 
-    // 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);
-}
+Okay, next up is a somewhat more complex app - a todo-list with the following behavior:
 
-// 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,
-    },
-});
+- New items open in an 'editing state'.
+- Items that are in 'editing state' show a text input, a save button and a cancel button. Done status cannot be toggled while editing.
+- Pressing one of the buttons, or pressing enter will transition from 'editing state' to 'viewing state', saving the new label text unless cancel was pressed.
+- In 'viewing state', the label is shown as non-editable. There's an 'Edit' link, that will transition the item to 'editing state'. Clicking anywhere else will toggle the done status.
+- The list of items is sorted alphabetically by label. Items move when 'save' changes their label.
+- Items that are created, moved or deleted are grown and shrink as appropriate.
 
-// 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) });
-                }
-            });
-        }
-    })
-}
+Pfew.. now let's look at the code:
 
-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)}`);
-        }
-    });
-}
+```typescript
+import {$, proxy, onEach, insertCss, peek, observe, unproxy, ref} from "aberdeen";
+import {grow, shrink} from "aberdeen/transitions";
 
-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,
-        });
-    });
+// We'll use a simple class to store our data.
+class TodoItem {
+    constructor(public label: string = '', public done: boolean = false) {}
+    toggle() { this.done = !this.done; }
 }
 
+// The top-level user interface.
 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
-    });
+    // Add some initial items. We'll wrap a proxy() around it!
+    let items: TodoItem[] = proxy([
+        new TodoItem('Make todo-list demo', true),
+        new TodoItem('Learn Aberdeen', false),
+    ]);
+    
+    // Draw the list, ordered by label.
+    onEach(items, drawItem, item => item.label);
 
-    $('main.row', () => {
-        $('div.box', () => drawBoard(history));
-        $('div.box', {$flex: 1}, () => {
-            drawStatusMessage(history);
-            drawTurns(history);
+    // Add item and delete checked buttons.
+    $('div.row', () => {
+        $('button:+', {
+            click: () => items.push(new TodoItem("")),
         });
+        $('button.outline:Delete checked', {
+            click: () => {
+                for(let idx in items) {
+                    if (items[idx].done) delete items[idx];
+                }
+            }
+        });
+    });
+};
+
+// Called for each todo list item.
+function drawItem(item) {
+    // Items without a label open in editing state.
+    // Note that we're creating this proxy outside the `div.row` scope
+    // create below, so that it will persist when that state reruns.
+    let editing: {value: boolean} = proxy(item.label == '');
+
+    $('div.row', todoItemStyle, {create:grow, destroy: shrink}, () => {
+        // Conditionally add a class to `div.row`, based on item.done
+        $({".done": ref(item,'done')});
+
+        // The checkmark is hidden using CSS
+        $('div.checkmark:✅');
+
+        if (editing.value) {
+            // Label <input>. Save using enter or button.
+            function save() {
+                editing.value = false;
+                item.label = inputElement.value;
+            }
+            let inputElement = $('input', {
+                placeholder: 'Label',
+                value: item.label,
+                keydown: e => e.key==='Enter' && save(),
+            });
+            $('button.outline:Cancel', {click: () => editing.value = false});
+            $('button:Save', {click: save});
+        } else {
+            // Label as text. 
+            $('p:' + item.label);
+
+            // Edit icon, if not done.
+            if (!item.done) {
+                $('a:Edit', {
+                    click: e => {
+                        editing.value = true;
+                        e.stopPropagation(); // We don't want to toggle as well.
+                    },
+                });
+            }
+            
+            // Clicking a row toggles done.
+            $({click: () => item.done = !item.done, $cursor: 'pointer'});
+        }
     });
 }
 
-// Fire it up! Mounts on document.body by default..
+// Insert some component-local CSS, specific for this demo.
+const todoItemStyle = insertCss({
+    marginBottom: "0.5rem",
+    ".checkmark": {
+        opacity: 0.2,
+    },
+    "&.done": {
+        textDecoration: "line-through",
+        ".checkmark": {
+            opacity: 1,
+        },
+    },
+});
 
+// Go!
 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)
+- [Input demo](https://aberdeenjs.org/examples/input/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/input)
+- [Tic Tac Toe demo](https://aberdeenjs.org/examples/tictactoe/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/tictactoe)
+- [List demo](https://aberdeenjs.org/examples/list/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/list)
+- [Routing demo](https://aberdeenjs.org/examples/router/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/router)
+- [JS Framework Benchmark demo](https://aberdeenjs.org/examples/js-framework-benchmark/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/js-framework-benchmark)
 
+## Learning Aberdeen
 
-## Documentation
+- [Tutorial](https://aberdeenjs.org/Tutorial/)
+- [Reference documentation](https://aberdeenjs.org/modules.html)
 
-- [Tutorial](https://vanviegen.github.io/aberdeen/Tutorial/)
-- [Reference documentation](https://vanviegen.github.io/aberdeen/modules.html)
+And you may want to study the examples above, of course!
 
-## Roadmap
+## News
 
-- [x] Support for (dis)appear transitions.
-- [x] A better alternative for scheduleTask.
-- [x] A simple router.
-- [x] Optimistic client-side predictions.
-- [x] Performance profiling and tuning regarding lists.
-- [x] Support for (component local) CSS
-- [ ] Architecture document.
-- [ ] SVG support.
+- **2025-05-07**: After five years of working on this library on and off, I'm finally happy with its API and the developer experience it offers. I'm calling it 1.0! To celebrate, I've created some pretty fancy (if I may say so myself) interactive documentation and a tutorial.

package/dist/aberdeen.d.ts

@@ -163,7 +163,10 @@ export declare function proxy<T extends DatumType>(target: T): ValueRef<T extend
  * setTimeout(() => rawUser.name += '?', 2000);
  *
  * // Both userProxy and rawUser end up as `{name: 'Frank!?'}`
- * setTimeout(() => console.log('final values', userProxy, rawUser), 3000);
+ * setTimeout(() => {
+ *   console.log('final proxied', userProxy)
+ *   console.log('final unproxied', rawUser)
+ * }, 3000);
  * ```
  */
 export declare function unproxy<T>(target: T): T;
@@ -305,22 +308,32 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  *   - `{html: string}`: Add the value as HTML to the *current* element. This should only be used in exceptional situations. And of course, beware of XSS.
  *   - `{element: Node}`: Add a pre-existing HTML `Node` to the *current* element.
  *
+ * @returns The most inner DOM element that was created (not counting text nodes nor elements created by content functions),
+ *          or undefined if no elements were created.
  *
  * @example Create Element
  * ```typescript
  * $('button.secondary.outline:Submit', {
- *   disabled: true,
+ *   disabled: false,
  *   click: () => console.log('Clicked!'),
  *   $color: 'red'
  * });
  * ```
  *
- * @example Nested Elements & Reactive Scope
+ * @example Create Nested Elements
+ * ```typescript
+ * let inputElement: Element = $('label:Click me', 'input', {type: 'checkbox'});
+ * // You should usually not touch raw DOM elements, unless when integrating
+ * // with non-Aberdeen code.
+ * console.log('DOM element:', inputElement);
+ * ```
+ *
+ * @example Content Functions & Reactive Scope
  * ```typescript
  * const state = proxy({ count: 0 });
  * $('div', () => { // Outer element
  *   // This scope re-renders when state.count changes
- *   $('p:Count is ${state.count}`);
+ *   $(`p:Count is ${state.count}`);
  *   $('button:Increment', { click: () => state.count++ });
  * });
  * ```
@@ -345,7 +358,7 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  * });
  * ```
  */
-export declare function $(...args: (string | null | undefined | false | (() => void) | Record<string, any>)[]): void;
+export declare function $(...args: (string | null | undefined | false | (() => void) | Record<string, any>)[]): void | Element;
 /**
  * Inserts CSS rules into the document, optionally scoping them with a unique class name.
  *
@@ -428,7 +441,7 @@ export declare function insertCss(style: object, global?: boolean): string;
  *
  *   try {
  *     // Attempt to show a custom message in the UI
- *     $('div.error-display:Oops, something went wrong!');
+ *     $('div.error-message:Oops, something went wrong!');
  *   } catch (e) {
  *     // Ignore errors during error handling itself
  *   }
@@ -436,8 +449,20 @@ export declare function insertCss(style: object, global?: boolean): string;
  *   return false; // Suppress default console log and DOM error message
  * });
  *
+ * // Styling for our custom error message
+ * insertCss({
+ *   '.error-message': {
+ *     backgroundColor: '#e31f00',
+ *     display: 'inline-block',
+ *     color: 'white',
+ *     borderRadius: '3px',
+ *     padding: '2px 4px',
+ *   }
+ * }, true); // global style
+ *
  * // Cause an error within a render scope.
  * $('div.box', () => {
+ *   // Will cause our error handler to insert an error message within the box
  *   noSuchFunction();
  * })
  * ```
@@ -450,7 +475,7 @@ export declare function setErrorHandler(handler?: (error: Error) => boolean | un
  * call or a {@link $} element's render function).
  *
  * **Note:** While this provides access to the DOM element, directly manipulating it outside
- * of Aberdeen's control is generally discouraged. Prefer declarative updates using {@link $}.
+ * of Aberdeen's control is generally discouraged. Prefer reactive updates using {@link $}.
  *
  * @returns The current parent `Element` for DOM insertion.
  *

package/dist/aberdeen.js

@@ -903,6 +903,7 @@ var SPECIAL_PROPS = {
 function $(...args) {
   let savedCurrentScope;
   let err;
+  let result;
   for (let arg of args) {
     if (arg == null || arg === false)
       continue;
@@ -932,17 +933,17 @@ function $(...args) {
         err = `Tag '${arg}' cannot contain space`;
         break;
       } else {
-        const el = document.createElement(arg);
+        result = document.createElement(arg);
         if (classes)
-          el.className = classes.replaceAll(".", " ");
+          result.className = classes.replaceAll(".", " ");
         if (text)
-          el.textContent = text;
-        addNode(el);
+          result.textContent = text;
+        addNode(result);
         if (!savedCurrentScope) {
           savedCurrentScope = currentScope;
         }
-        let newScope = new ChainedScope(el, true);
-        newScope.lastChild = el.lastChild || undefined;
+        let newScope = new ChainedScope(result, true);
+        newScope.lastChild = result.lastChild || undefined;
         if (topRedrawScope === currentScope)
           topRedrawScope = newScope;
         currentScope = newScope;
@@ -968,6 +969,7 @@ function $(...args) {
   }
   if (err)
     throw new Error(err);
+  return result;
 }
 var cssCount = 0;
 function insertCss(style, global = false) {
@@ -1195,5 +1197,5 @@ export {
   $
 };
 
-//# debugId=DE860A8F16A3286C64756E2164756E21
+//# debugId=96472D32607348EB64756E2164756E21
 //# sourceMappingURL=aberdeen.js.map