aberdeen 1.4.0 → 1.4.3

package/README.md

@@ -79,14 +79,10 @@ function drawMain() {
 
     // 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];
-                }
+        $('button text=+ click=', () => items.push(new TodoItem("")));
+        $('button.outline text="Delete checked" click=', () => {
+            for(let idx in items) {
+                if (items[idx].done) delete items[idx];
             }
         });
     });
@@ -99,37 +95,33 @@ function drawItem(item) {
     // 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}, () => {
+    $('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#✅');
+        $('div.checkmark text=✅');
 
         if (editing.value) {
-            // Label <input>. Save using enter or button.
+            // Proxied string to hold label while being edited.
+            const labelCopy = proxy(item.label);
             function save() {
                 editing.value = false;
-                item.label = inputElement.value;
+                item.label = labelCopy.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});
+            // Label <input>. Save using enter or button.
+            $('input placeholder=Label bind=', labelCopy, 'keydown=', e => e.key==='Enter' && save());
+            $('button.outline text=Cancel click=', () => editing.value = false);
+            $('button text=Save click=', save);
         } else {
             // Label as text. 
-            $('p#' + item.label);
+            $('p text=', 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.
-                    },
+                $('a text=Edit click=', e => {
+                    editing.value = true;
+                    e.stopPropagation(); // We don't want to toggle as well.
                 });
             }
             
@@ -165,6 +157,7 @@ Some further examples:
 - [Routing demo](https://aberdeenjs.org/examples/route/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/route)
 - [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/)
@@ -172,81 +165,18 @@ Some further examples:
 
 And you may want to study the examples above, of course!
 
-## Changelog
-
-### 1.4.0 (2025-01-07)
-
-**Enhancements:**
-- Shortcuts for common CSS properties. For instance: `$('div mv:10px')` for setting vertical (top and bottom) margins.
-- Variables you can set and use in CSS styles, e.g. `$('div bg:@myColor')` after setting `cssVars.myColor = 'red'`.
-- Default CSS variables are defined for spacing: `@2` is `0.5rem`, `@3` is `1rem`, etc. For example: `$('r:@3')` sets border radius to (a dynamically configurable) `1rem`.
-- All CSS shortcuts and `@` variables are also supported in `insertCss` and `insertGlobalCss`.
-- Added `insertGlobalCss` for adding global styles. The `global` argument to `insertCss` is now deprecated.
-
-**Fixes:**
-- When doing `$('div #first', () => $('#second'))`, *second* now comes after *first*. It used to be the other way around.
-
-### 1.3.2 (2025-01-07)
-
-**Enhancements:**
-- It's now okay to first define a SELECT binding and then add its OPTIONs right after, while still allowing the binding to set the initial value. This used to throw an async error.
-
-**Fixes:**
-- Turns out some examples were still using old text content syntax.
-
-### 1.3.1 (2025-01-07)
-**Fixes:**
-- Argument types accepted by `$` were too restrictive, as something like `$('prop=', myVal)` should be able to accept any type for `myVal`.
 
-### 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)`.
+## AI Integration
 
-**Enhancements:**
-- New A() string parser, reducing complexity and line count.
+If you use Claude Code, GitHub Copilot or another AI agents that supports Skills, Aberdeen includes a `skill/` directory that provides specialized knowledge to the AI about how to use the library effectively.
 
-### 1.2.0 (2025-09-27)
+To use this, it is recommended to symlink the skill into your project's `.claude/skills` directory:
 
-**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).
-
-**Breaking changes:**
-
-- Functions that iterate objects (like `onEach` and `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 `copy` function no longer ..
-    - Supports `SHALLOW` and `MERGE` flags. The latter has been replaced by a dedicated `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 `derive` to better reflect its purpose and match terminology used in other reactive programming libraries.
-- The `$({element: myElement})` syntax for inserting existing DOM elements has been removed. Use `$(myElement)` instead.
-- The `route` API brings some significant changes. Modifying the `route` observable (which should now be accessed as `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 (`go`), back to a previous URL (`back`), and for going up in the route hierarchy (`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 `route` API. It turned out to be a mistake.
-
-**Enhancements:**
-
-- The `peek` function can no also accept an object and a key as argument (e.g. `peek(obj, 'myKey')`). It does the same as `peek(() => obj.myKey)`, but more concise and faster.
-- The `copy` and `merge` functions now ..
-    - Accept an optional `dstKey` argument, allowing you to assign to a specific key with `copy` semantics, and without subscribing to the key.
-    - Return a boolean indicating whether any changes were made.
-    - Are faster.
-- A new `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 `route` module now also has tests, making the whole project now fully covered by tests.
-
-**Fixes:**
-
-- Browser-back behavior in the `route` module had some reliability issues after page reloads.
-- The `copy` and `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.
+```bash
+mkdir -p .claude/skills
+ln -s ../../node_modules/aberdeen/skill .claude/skills/aberdeen
+```
 
-### 1.0.0 (2025-05-07)
+## Changelog
 
-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.
+See [CHANGELOG.md](CHANGELOG.md) for a full history of changes.

package/dist/aberdeen.d.ts

@@ -16,7 +16,7 @@
  * ```typescript
  * const data = proxy("before");
  *
- * $({text: data});
+ * $('#'+data);
  * console.log(1, document.body.innerHTML); // before
  *
  * // Make an update that should cause the DOM to change.
@@ -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));
  *     }
  * });
  *
@@ -110,7 +110,7 @@ export interface ValueRef<T> {
  * const cnt = count(items);
  *
  * // Create a DOM text node for the count:
- * $('div', {text: cnt});
+ * $('div text=', cnt);
  * // <div>2</div>
 
  * // Or we can use it in an {@link derive} function:
@@ -293,17 +293,10 @@ export declare function clone<T extends object>(src: T): T;
  * const formData = proxy({ color: 'orange', velocity: 42 });
  *
  * // Usage with `bind`
- * $('input', {
- *   type: 'text',
- *   // Creates a two-way binding between the input's value and formData.username
- *   bind: ref(formData, 'color')
- * });
+ * $('input type=text bind=', ref(formData, 'color'));
  *
  * // Usage as a dynamic property, causes a TextNode with just the name to be created and live-updated
- * $('p#Selected color: ', {
- *   text: ref(formData, 'color'),
- *   $color: ref(formData, 'color')
- * });
+ * $('p text="Selected color: " text=', ref(formData, 'color'), 'color:', ref(formData, 'color'));
  *
  * // Changes are actually stored in formData - this causes logs like `{color: "Blue", velocity 42}`
  * $(() => console.log(formData))
@@ -352,16 +345,7 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  *
  * @example Create Element
  * ```typescript
- * $('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!'));
+ * $('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
@@ -369,7 +353,7 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  *
  * @example Create Nested Elements
  * ```typescript
- * let inputElement: Element = $('label#Click me', 'input', {type: 'checkbox'});
+ * let inputElement: Element = $('label text="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);
@@ -381,14 +365,14 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  * $('div', () => { // Outer element
  *   // This scope re-renders when state.count changes
  *   $(`p#Count is ${state.count}`);
- *   $('button#Increment', { click: () => state.count++ });
+ *   $('button text=Increment click=', () => state.count++);
  * });
  * ```
  *
  * @example Two-way Binding
  * ```typescript
  * const user = proxy({ name: '' });
- * $('input', { placeholder: 'Name', bind: ref(user, 'name') });
+ * $('input placeholder=Name bind=', ref(user, 'name'));
  * $('h3', () => { // Reactive scope
  *   $(`#Hello ${user.name || 'stranger'}`);
  * });
@@ -397,7 +381,7 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  * @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!');
@@ -418,7 +402,7 @@ export declare function $(...args: any[]): undefined | Element;
  *   - In case a selector contains a `&`, that character will be replaced by the parent selector.
  *   - Selectors will be split on `,` characters, each combining with the parent selector with *or* semantics.
  *   - Selector starting with `'@'` define at-rules like media queries. They may be nested within regular selectors.
- * @param global - @deprecated Use {@link insertGlobalCss} instead.
+ * @param global - Deprecated! Use {@link insertGlobalCss} instead.
  * @returns The unique class name prefix used for scoping (e.g., `.AbdStl1`). Use this
  *          prefix with {@link $} to apply the styles.
  *
@@ -575,7 +559,7 @@ export declare function getParentElement(): Element;
  * })
  *
  * // Show the sum
- * $('h1', {text: sum});
+ * $('h1 text=', sum);
  *
  * // Make random changes to the array
  * const rnd = () => 0|(Math.random()*20);
@@ -609,8 +593,8 @@ export declare function clean(cleaner: () => void): void;
  *     // 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 text=', data.notifications);
+ *     $('a text=Notify! click=', () => data.notifications++);
  *   });
  * });
  * ```
@@ -707,7 +691,7 @@ export declare function unmountAll(): void;
  * ```
  *
  */
-export declare function peek<T extends object>(target: T, key: keyof T): T[typeof key];
+export declare function peek<T extends object, K extends keyof T>(target: T, key: K): T[K];
 export declare function peek<K, V>(target: Map<K, V>, key: K): V | undefined;
 export declare function peek<T>(target: T[], key: number): T | undefined;
 export declare function peek<T>(target: () => T): T;