aberdeen 1.1.0 → 1.3.0

package/README.md

@@ -31,17 +31,17 @@ const state = proxy({question: "How many roads must a man walk down?", answer: 4
 
 $('h3', () => {
     // This function reruns whenever the question or the answer changes
-    $(`:${state.question} ↪ ${state.answer || 'Blowing in the wind'}`)
+    $('text=', `${state.question} ↪ ${state.answer || 'Blowing in the wind'}`)
 });
 
 // Two-way bind state.question to an <input>
-$('input', {placeholder: 'Question', bind: ref(state, 'question')})
+$('input placeholder=Question bind=', ref(state, 'question'))
 
 // 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++});
+$('div.row marginTop:1em', () => {
+    $('button text=- click=', () => state.answer--);
+    $('input type=number bind=', ref(state, 'answer'))
+    $('button text=+ click=', () => state.answer++);
 });
 ```
 
@@ -79,10 +79,10 @@ function drawMain() {
 
     // Add item and delete checked buttons.
     $('div.row', () => {
-        $('button:+', {
+        $('button#+', {
             click: () => items.push(new TodoItem("")),
         });
-        $('button.outline:Delete checked', {
+        $('button.outline#Delete checked', {
             click: () => {
                 for(let idx in items) {
                     if (items[idx].done) delete items[idx];
@@ -104,7 +104,7 @@ function drawItem(item) {
         $({".done": ref(item,'done')});
 
         // The checkmark is hidden using CSS
-        $('div.checkmark:✅');
+        $('div.checkmark#✅');
 
         if (editing.value) {
             // Label <input>. Save using enter or button.
@@ -117,15 +117,15 @@ function drawItem(item) {
                 value: item.label,
                 keydown: e => e.key==='Enter' && save(),
             });
-            $('button.outline:Cancel', {click: () => editing.value = false});
-            $('button:Save', {click: save});
+            $('button.outline#Cancel', {click: () => editing.value = false});
+            $('button#Save', {click: save});
         } else {
             // Label as text. 
-            $('p:' + item.label);
+            $('p#' + item.label);
 
             // Edit icon, if not done.
             if (!item.done) {
-                $('a:Edit', {
+                $('a#Edit', {
                     click: e => {
                         editing.value = true;
                         e.stopPropagation(); // We don't want to toggle as well.
@@ -134,7 +134,7 @@ function drawItem(item) {
             }
             
             // Clicking a row toggles done.
-            $({click: () => item.done = !item.done, $cursor: 'pointer'});
+            $('cursor:pointer click=', () => item.done = !item.done);
         }
     });
 }
@@ -174,7 +174,24 @@ And you may want to study the examples above, of course!
 
 ## Changelog
 
-### 1.1.0 (2024-09-12)
+### 1.3.0 (2025-12-03)
+**Breaking changes:**
+- The shortcut for setting inline CSS styles in now `$('div color:red')` instead of `$('div $color=red')`.
+- The shortcut for adding text content is now `$('p#Hello')` instead of `$('p:Hello')`. It now also works with dynamic content: `$('p#', myObservable)`.
+
+**Enhancements:**
+- New A() string parser, reducing complexity and line count.
+
+### 1.2.0 (2025-09-27)
+
+**Enhancements:**
+- The `$` function now supports a more concise syntax for setting attributes and properties. Instead of writing `$('p', 'button', {$color: 'red', click: () => ...})`, you can now write `$('p button $color=red click=', () => ...)`.
+- The `proxy()` function can now accept `Promise`s, which will return an observable object with properties for `busy` status, `error` (if any), and the resolved `value`. This makes it easier to call async functions from within UI code.
+
+**Breaking changes:**
+- When a UI render function returns a `Promise`, that will now be reported as an error. Async render functions are fundamentally incompatible with Aberdeen's reactive model, so it's helpful to point that out. Use the new `proxy()` async support instead.
+
+### 1.1.0 (2025-09-12)
 
 This major release aims to reduce surprises in our API, aligning more closely with regular JavaScript semantics (for better or worse).
 

package/README.md.bak

@@ -0,0 +1,212 @@
+# [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)
+
+Build fast reactive UIs in pure TypeScript/JavaScript without a virtual DOM.
+
+Aberdeen's approach is refreshingly simple:
+
+> Use many small anonymous functions for emitting DOM elements, and automatically rerun them when their underlying data changes. JavaScript `Proxy` is used to track reads and updates to this data, which can consist of anything, from simple values to complex, typed, and deeply nested data structures. 
+
+## Why use Aberdeen?
+
+- 🎩 **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 6KB (minimized and gzipped) for the core system. Zero runtime dependencies.
+- 🔋 **Batteries included**: Comes with browser history management, routing, revertible patches for optimistic user-interface updates, component-local CSS, SVG support, helper functions for transforming reactive data (mapping, partitioning, filtering, etc) and hide/unhide transition effects. No bikeshedding required!
+
+## Why *not* use Aberdeen?
+
+- 🤷 **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.
+
+## Examples
+
+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 A from 'aberdeen';
+
+// Define some state as a proxied (observable) object
+const state = A.proxy({question: "How many roads must a man walk down?", answer: 42});
+
+A`h3`(() => {
+    // This function reruns whenever the question or the answer changes
+    A`"${state.question} ↪ ${state.answer || 'Blowing in the wind'}"`;
+});
+
+// Two-way bind state.question to an <input>
+A`input placeholder=Question bind!${A.at(state, 'question')}`;
+
+// Allow state.answer to be modified using both an <input> and buttons
+A`div.row`(() => {
+    A`button click=${() => state.answer--} "-"`;
+    A`input type=number bind!${A.at(state, 'answer')}`;
+    A`button click=${() => state.answer++} "+"`;
+});
+```
+
+Okay, next up is a somewhat more complex app - a todo-list with the following behavior:
+
+- 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 grow and shrink as appropriate.
+
+Pfew.. now let's look at the code:
+
+```typescript
+import A from "aberdeen";
+import {grow, shrink} from "aberdeen/transitions";
+
+// 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() {
+    // Add some initial items. We'll wrap a proxy() around it!
+    let items: TodoItem[] = A.proxy([
+        new TodoItem('Make todo-list demo', true),
+        new TodoItem('Learn Aberdeen', false),
+    ]);
+    
+    // Draw the list, ordered by label.
+    A.onEach(items, drawItem, item => item.label);
+
+    // Add item and delete checked buttons.
+    A`div.row`(() => {
+        A`button click=${() => items.push(new TodoItem(""))} "+"`;
+        A`button.outline click=${() => {
+            for(let idx in items) {
+                if (items[idx].done) delete items[idx];
+            }
+        }} "Delete checked"`;
+    });
+};
+
+// 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} = A.proxy(item.label == '');
+
+    A`div.row.${todoItemStyle} create!${grow} destroy!${shrink}`(() => {
+        // Conditionally add a class to `div.row`, based on item.done
+        A`if!${A.at(item,'done')} .done`;
+
+        // The checkmark is hidden using CSS
+        A`div.checkmark "✅"`;
+
+        if (editing.value) {
+            // Label <input>. Save using enter or button.
+            function save() {
+                editing.value = false;
+                item.label = inputElement.value;
+            }
+            let inputElement = A`input placeholder=Label value~${item.label} keydown=${e => e.key==='Enter' && save()}`;
+            A`button.outline click=${() => editing.value = false} "Cancel"`;
+            A`button click=${save} "Save"`;
+        } else {
+            // Label as text. 
+            A`p "${item.label}"`;
+
+            // Edit icon, if not done.
+            if (!item.done) {
+                A`a click=${e => {
+                    editing.value = true;
+                    e.stopPropagation(); // We don't want to toggle as well.
+                }} "Edit"`;
+            }
+            
+            // Clicking a row toggles done.
+            A`click=${() => item.done = !item.done} cursor:pointer`;
+        }
+    });
+}
+
+// Insert some component-local CSS, specific for this demo.
+const todoItemStyle = A.insertCss({
+    marginBottom: "0.5rem",
+    ".checkmark": {
+        opacity: 0.2,
+    },
+    "&.done": {
+        textDecoration: "line-through",
+        ".checkmark": {
+            opacity: 1,
+        },
+    },
+});
+
+// Go!
+drawMain();
+```
+
+Some further examples:
+
+- [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
+
+- [Tutorial](https://aberdeenjs.org/Tutorial/)
+- [Reference documentation](https://aberdeenjs.org/modules.html)
+
+And you may want to study the examples above, of course!
+
+## Changelog
+
+### 1.2.0 (2025-09-27)
+
+**Enhancements:**
+- The `A` function now supports a concise template literal syntax for creating elements, setting attributes and properties, adding classes, etc. See the documentation for details.
+- The `A.proxy()` function can now accept `Promise`s, which will return an observable object with properties for `busy` status, `error` (if any), and the resolved `value`. This makes it easier to call async functions from within UI code.
+
+**Breaking changes:**
+- When a UI render function returns a `Promise`, that will now be reported as an error. Async render functions are fundamentally incompatible with Aberdeen's reactive model, so it's helpful to point that out. Use the new `A.proxy()` async support instead.
+- Setting attributes versus properties is no longer automatically inferred. Use `name=value` for attributes and `name~value` for properties.
+- Special attributes (like `bind`, `create`, `destroy`, `if`, `else`, `end`, and `html`) now use a different syntax: `name!value` or just `name!`.
+- Conditional rendering has been completely redesigned, now using `if!`, `else!`, and `end!` special attributes with different semantics.
+
+### 1.1.0 (2025-09-12)
+
+This major release aims to reduce surprises in our API, aligning more closely with regular JavaScript semantics (for better or worse).
+
+**Breaking changes:**
+
+- Functions that iterate objects (like `A.onEach` and `A.map`) will now only work on *own* properties of the object, ignoring those in the prototype chain. The new behavior should be more consistent and faster. 
+- These iteration function now properly distinguish between `undefined` and *empty*. Previously, object/array/map items with `undefined` values were considered non-existent. The new behavior (though arguably confusing) is more consistent with regular JavaScript semantics.
+- The `A.copy` function no longer ..
+    - Supports `SHALLOW` and `MERGE` flags. The latter has been replaced by a dedicated `A.merge` function. The former turned out not to be particularly useful.
+    - Has weird special cases that would allow copying objects into maps and merging objects into arrays.
+    - Copies properties from the prototype chain of objects. Only *own* properties are copied now. As the prototype link itself *is* copied over, this should actually result in copies being *more* similar to the original.
+- The `observe` function has been renamed to `A.derive` to better reflect its purpose and match terminology used in other reactive programming libraries.
+- The `A.route` API brings some significant changes. Modifying the `A.route` observable (which should now be accessed as `A.route.current`) will now always result in changing the current browser history item (URL and state, using `replaceState`), instead of using a heuristic to figure out what you probably want. Dedicated functions have been added for navigating to a new URL (`A.go`), back to a previous URL (`A.back`), and for going up in the route hierarchy (`A.up`). 
+- The concept of immediate observers (through the `immediateObserve` function) no longer exists. It caused unexpected behavior (for instance due to the fact that an array `pop()` in JavaScript is implemented as a delete followed by a length change, so happens in two steps that would each call immediate observers). The reason it existed was mostly to enable a pre-1.0 version of the `A.route` API. It turned out to be a mistake.
+
+**Enhancements:**
+
+- The `A.peek` function can now also accept an object and a key as argument (e.g. `A.peek(obj, 'myKey')`). It does the same as `A.peek(() => obj.myKey)`, but more concise and faster.
+- The `A.copy` and `A.merge` functions now ..
+    - Accept an optional `dstKey` argument, allowing you to assign to a specific key with `A.copy` semantics, and without subscribing to the key.
+    - Return a boolean indicating whether any changes were made.
+    - Are faster.
+- A new `A.dispatcher` module has been added. It provides a simple and type-safe way to match URL paths to handler functions, and extract parameters from the path. You can still use your own routing solution if you prefer, of course.
+- The `A.route` module now also has tests, making the whole project now fully covered by tests.
+
+**Fixes:**
+
+- Browser-back behavior in the `A.route` module had some reliability issues after page reloads.
+- The `A.copy` and `A.clone` function created Maps and Arrays with the wrong internal type. So `instanceof Array` would say yes, while `Array.isArray` would say no. JavaScript is weird.
+
+### 1.0.0 (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

@@ -49,7 +49,7 @@ export declare function runQueue(): void;
  * ]);
  *
  * onEach(users, (user) => {
- *     $(`p:${user.name}: ${user.score}`);
+ *     $(`p#${user.name}: ${user.score}`);
  * }, (user) => invertString(user.name)); // Reverse alphabetic order
  * ```
  *
@@ -80,9 +80,9 @@ export declare function onEach<K extends string | number | symbol, T>(target: Re
  * // Reactively display a message if the items array is empty
  * $('div', () => {
  *     if (isEmpty(items)) {
- *         $('p', 'i:No items yet!');
+ *         $('p', 'i#No items yet!');
  *     } else {
- * 		   onEach(items, item=>$('p:'+item));
+ * 		   onEach(items, item=>$('p#'+item));
  *     }
  * });
  *
@@ -125,6 +125,24 @@ export interface ValueRef<T> {
  * ```
  */
 export declare function count(proxied: TargetType): ValueRef<number>;
+/**
+ * When `proxy` is called with a Promise, the returned object has this shape.
+ */
+export interface PromiseProxy<T> {
+    /**
+     * True if the promise is still pending, false if it has resolved or rejected.
+     */
+    busy: boolean;
+    /**
+     * If the promise has resolved, this contains the resolved value.
+     */
+    value?: T;
+    /**
+     * If the promise has rejected, this contains the rejection error.
+     */
+    error?: any;
+}
+export declare function proxy<T extends any>(target: Promise<T>): PromiseProxy<T>;
 export declare function proxy<T extends any>(target: Array<T>): Array<T extends number ? number : T extends string ? string : T extends boolean ? boolean : T>;
 export declare function proxy<T extends object>(target: T): T;
 export declare function proxy<T extends any>(target: T): ValueRef<T extends number ? number : T extends string ? string : T extends boolean ? boolean : T>;
@@ -227,6 +245,12 @@ export declare function copy<T extends object>(dst: T, dstKey: keyof T, src: T[t
  */
 export declare function merge<T extends object>(dst: T, value: Partial<T>): boolean;
 export declare function merge<T extends object>(dst: T, dstKey: keyof T, value: Partial<T[typeof dstKey]>): boolean;
+/**
+ * A symbol that can be added to an object to prevent it from being cloned by {@link clone} or {@link copy}.
+ * This is useful for objects that should be shared by reference. That also mean that their contents won't
+ * be observed for changes.
+ */
+export declare const NO_COPY: unique symbol;
 /**
  * Clone an (optionally proxied) object or array.
  *
@@ -261,7 +285,7 @@ export declare function clone<T extends object>(src: T): T;
  * });
  *
  * // Usage as a dynamic property, causes a TextNode with just the name to be created and live-updated
- * $('p:Selected color: ', {
+ * $('p#Selected color: ', {
  *   text: ref(formData, 'color'),
  *   $color: ref(formData, 'color')
  * });
@@ -279,11 +303,13 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  * @param {...(string | function | object | false | undefined | null)} args - Any number of arguments can be given. How they're interpreted depends on their types:
  *
  * - `string`: Strings can be used to create and insert new elements, set classnames for the *current* element, and add text to the current element.
- *   The format of a string is: **tag**? (`.` **class**)* (':' **text**)?
- *   meaning it consists of...
- *   - An optional HTML **tag**, something like `h1`. If present, a DOM element of that tag is created, and that element will be the *current* element for the rest of this `$` function execution.
- *   - Any number of CSS classes prefixed by `.` characters. These classes will be added to the *current* element.
- *   - Optional content **text** prefixed by a `:` character, ranging til the end of the string. This will be added as a TextNode to the *current* element.
+ *   The format of a string is: (**tag** | `.` **class** | **key**=**val** | **key**="**long val**")* ('#' **text** | **key**=)?
+ *   So there can be:
+ *   - Any number of **tag** element, like `h1` or `div`. These elements are created, added to the *current* element, and become the new *current* element for the rest of this `$` function execution.
+ *   - Any number of CSS classes prefixed by `.` characters. These classes will be added to the *current* element. Optionally, CSS classes can be appended to a **tag** without a space. So both `div.myclass` and `div .myclass` are valid and do the same thing.
+ *   - Any number of key/value pairs with string values, like `placeholder="Your name"` or `data-id=123`. These will be handled according to the rules specified for `object`, below, but with the caveat that values can only be strings. The quotes around string values are optional, unless the value contains spaces. It's not possible to escape quotes within the value. If you want to do that, or if you have user-provided values, use the `object` syntax (see below) or end your string with `key=` followed by the data as a separate argument (see below).
+ *   - The string may end in a '#' followed by text, which will be added as a TextNode to the *current* element. The text ranges til the end of the string, and may contain any characters, including spaces and quotes.
+ *   - Alternatively, the string may end in a key followed by an '=' character, in which case the value is expected as a separate argument. The key/value pair is set according to the rules specified for `object` below. This is useful when the value is not a string or contains spaces or user data. Example: `$('button text="Click me" click=', () => alert('Clicked!'))` or `$('input.value=', someUserData, "placeholder=", "Type your stuff")`.
  * - `function`: When a function (without argument nor a return value) is passed in, it will be reactively executed in its own observer scope, preserving the *current element*. So any `$()` invocations within this function will create DOM elements with our *current* element as parent. If the function reads observable data, and that data is changed later on, the function we re-execute (after side effects, such as DOM modifications through `$`, have been cleaned - see also {@link clean}).
  * - `object`: When an object is passed in, its key-value pairs are used to modify the *current* element in the following ways...
  *   - `{<attrName>: any}`: The common case is setting the value as an HTML attribute named key. So `{placeholder: "Your name"}` would add `placeholder="Your name"` to the current HTML element.
@@ -298,7 +324,7 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  *   - `{<any>: <obsvalue>}`: Create a new observer scope and read the `value` property of the given observable (proxy) variable from within it, and apply the contained value using any of the other rules in this list. Example:
  *      ```typescript
  *      const myColor = proxy('red');
- *      $('p:Test', {$color: myColor, click: () => myColor.value = 'yellow'})
+ *      $('p#Test', {$color: myColor, click: () => myColor.value = 'yellow'})
  *      // Clicking the text will cause it to change color without recreating the <p> itself
  *      ```
  *      This is often used together with {@link ref}, in order to use properties other than `.value`.
@@ -311,16 +337,24 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  *
  * @example Create Element
  * ```typescript
- * $('button.secondary.outline:Submit', {
+ * $('button.secondary.outline#Submit', {
  *   disabled: false,
  *   click: () => console.log('Clicked!'),
  *   $color: 'red'
  * });
  * ```
  *
+ * Which can also be written as:
+ * ```typescript
+ * $('button.secondary.outline text=Submit $color=red disabled=', false, 'click=', () => console.log('Clicked!'));
+ * ```
+ *
+ * We want to set `disabled` as a property instead of an attribute, so we must use the `key=` syntax in order to provide
+ * `false` as a boolean instead of a string.
+ *
  * @example Create Nested Elements
  * ```typescript
- * let inputElement: Element = $('label:Click me', 'input', {type: 'checkbox'});
+ * 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);
@@ -331,8 +365,8 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  * const state = proxy({ count: 0 });
  * $('div', () => { // Outer element
  *   // This scope re-renders when state.count changes
- *   $(`p:Count is ${state.count}`);
- *   $('button:Increment', { click: () => state.count++ });
+ *   $(`p#Count is ${state.count}`);
+ *   $('button#Increment', { click: () => state.count++ });
  * });
  * ```
  *
@@ -341,17 +375,17 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  * const user = proxy({ name: '' });
  * $('input', { placeholder: 'Name', bind: ref(user, 'name') });
  * $('h3', () => { // Reactive scope
- *   $(`:Hello ${user.name || 'stranger'}`);
+ *   $(`#Hello ${user.name || 'stranger'}`);
  * });
  * ```
  *
  * @example Conditional Rendering
  * ```typescript
  * const show = proxy(false);
- * $('button', { click: () => show.value = !show.value }, () => $(show.value ? ':Hide' : ':Show'));
+ * $('button', { click: () => show.value = !show.value }, () => $(show.value ? '#Hide' : '#Show'));
  * $(() => { // Reactive scope
  *   if (show.value) {
- *     $('p:Details are visible!');
+ *     $('p#Details are visible!');
  *   }
  * });
  * ```
@@ -394,8 +428,8 @@ export declare function $(...args: (string | null | undefined | false | (() => v
  *
  * // Apply the styles
  * $(scopeClass, () => { // Add class to the div
- *   $(`:Scoped content`);
- *   $('div.child-element:Child'); // .AbdStl1 .child-element rule applies
+ *   $(`#Scoped content`);
+ *   $('div.child-element#Child'); // .AbdStl1 .child-element rule applies
  * });
  * ```
  *
@@ -411,7 +445,7 @@ export declare function $(...args: (string | null | undefined | false | (() => v
  *   }
  * }, true); // Pass true for global
  *
- * $('a:Styled link');
+ * $('a#Styled link');
  * ```
  */
 export declare function insertCss(style: object, global?: boolean): string;
@@ -439,7 +473,7 @@ export declare function insertCss(style: object, global?: boolean): string;
  *
  *   try {
  *     // Attempt to show a custom message in the UI
- *     $('div.error-message:Oops, something went wrong!');
+ *     $('div.error-message#Oops, something went wrong!');
  *   } catch (e) {
  *     // Ignore errors during error handling itself
  *   }
@@ -510,7 +544,7 @@ export declare function getParentElement(): Element;
  *
  * // Show the array items and maintain the sum
  * onEach(myArray, (item, index) => {
- *     $(`code:${index}→${item}`);
+ *     $(`code#${index}→${item}`);
  *     // We'll update sum.value using peek, as += first does a read, but
  *     // we don't want to subscribe.
  *     peek(() => sum.value += item);
@@ -549,14 +583,14 @@ export declare function clean(cleaner: () => void): void;
  *
  * $('main', () => {
  *   console.log('Welcome');
- *   $('h3:Welcome, ' + data.user); // Reactive text
+ *   $('h3#Welcome, ' + data.user); // Reactive text
  *
  *   derive(() => {
  *     // When data.notifications changes, only this inner scope reruns,
  *     // leaving the `<p>Welcome, ..</p>` untouched.
  *     console.log('Notifications');
- *     $('code.notification-badge:' + data.notifications);
- *     $('a:Notify!', {click: () => data.notifications++});
+ *     $('code.notification-badge#' + data.notifications);
+ *     $('a#Notify!', {click: () => data.notifications++});
  *   });
  * });
  * ```
@@ -570,7 +604,7 @@ export declare function clean(cleaner: () => void): void;
  * const double = derive(() => counter.value * 2);
  *
  * $('h3', () => {
- *     $(`:counter=${counter.value} double=${double.value}`);
+ *     $(`#counter=${counter.value} double=${double.value}`);
  * })
  * ```
  *
@@ -607,12 +641,12 @@ export declare function derive<T>(func: () => T): ValueRef<T>;
  * setInterval(() => runTime.value++, 1000);
  *
  * mount(document.getElementById('app-root'), () => {
- *   $('h4:Aberdeen App');
- *   $(`p:Run time: ${runTime.value}s`);
+ *   $('h4#Aberdeen App');
+ *   $(`p#Run time: ${runTime.value}s`);
  *   // Conditionally render some content somewhere else in the static page
  *   if (runTime.value&1) {
  *     mount(document.getElementById('title-extra'), () =>
- *       $(`i:(${runTime.value}s)`)
+ *       $(`i#(${runTime.value}s)`)
  *     );
  *   }
  * });
@@ -701,7 +735,7 @@ export declare function partition<IN_K extends string | number | symbol, OUT_K e
  *   items: ['a', 'b']
  * });
  *
- * $('h2:Live State Dump');
+ * $('h2#Live State Dump');
  * dump(state);
  *
  * // Change state later, the dump in the DOM will update