aberdeen 1.1.0 → 1.2.0

package/README.md

@@ -31,14 +31,14 @@ 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'}, () => {
+$('div.row $marginTop=1em', () => {
     $('button:-', {click: () => state.answer--});
     $('input', {type: 'number', bind: ref(state, 'answer')})
     $('button:+', {click: () => state.answer++});
@@ -174,7 +174,16 @@ And you may want to study the examples above, of course!
 
 ## Changelog
 
-### 1.1.0 (2024-09-12)
+### 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/dist/aberdeen.d.ts

@@ -125,6 +125,12 @@ export interface ValueRef<T> {
  * ```
  */
 export declare function count(proxied: TargetType): ValueRef<number>;
+interface PromiseProxy<T> {
+    busy: boolean;
+    error?: any;
+    value?: T;
+}
+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>;
@@ -279,11 +285,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.
@@ -318,6 +326,14 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  * });
  * ```
  *
+ * 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'});
@@ -709,3 +725,4 @@ export declare function partition<IN_K extends string | number | symbol, OUT_K e
  * ```
  */
 export declare function dump<T>(data: T): T;
+export {};

package/dist/aberdeen.js

@@ -645,7 +645,7 @@ var objectHandler = {
     return true;
   },
   deleteProperty(target, prop) {
-    const old = target.hasOwnProperty(prop) ? target[prop] : undefined;
+    const old = target.hasOwnProperty(prop) ? target[prop] : EMPTY;
     delete target[prop];
     emit(target, prop, EMPTY, old);
     return true;
@@ -862,6 +862,19 @@ function optProxy(value) {
   return proxied;
 }
 function proxy(target) {
+  if (target instanceof Promise) {
+    const result = optProxy({
+      busy: true
+    });
+    target.then((value) => {
+      result.value = value;
+      result.busy = false;
+    }).catch((err) => {
+      result.error = err;
+      result.busy = false;
+    });
+    return result;
+  }
   return optProxy(typeof target === "object" && target !== null ? target : { value: target });
 }
 function unproxy(target) {
@@ -876,14 +889,14 @@ function destroyWithClass(element, cls) {
 function copy(a, b, c) {
   if (arguments.length > 2)
     return copySet(a, b, c, 0);
-  return copyRecursive(a, b, 0);
+  return copyImpl(a, b, 0);
 }
 function copySet(dst, dstKey, src, flags) {
   let dstVal = peek(dst, dstKey);
   if (src === dstVal)
     return false;
   if (typeof dstVal === "object" && dstVal && typeof src === "object" && src && dstVal.constructor === src.constructor) {
-    return copyRecursive(dstVal, src, flags);
+    return copyImpl(dstVal, src, flags);
   }
   src = clone(src);
   if (dst instanceof Map)
@@ -895,9 +908,9 @@ function copySet(dst, dstKey, src, flags) {
 function merge(a, b, c) {
   if (arguments.length > 2)
     return copySet(a, b, c, MERGE);
-  return copyRecursive(a, b, MERGE);
+  return copyImpl(a, b, MERGE);
 }
-function copyRecursive(dst, src, flags) {
+function copyImpl(dst, src, flags) {
   let unproxied = dst[TARGET_SYMBOL];
   if (unproxied) {
     dst = unproxied;
@@ -909,6 +922,9 @@ function copyRecursive(dst, src, flags) {
     if (currentScope !== ROOT_SCOPE && !peeking)
       flags |= COPY_SUBSCRIBE;
   }
+  return copyRecursive(dst, src, flags);
+}
+function copyRecursive(dst, src, flags) {
   if (flags & COPY_SUBSCRIBE)
     subscribe(src, ANY_SYMBOL);
   let changed = false;
@@ -1025,7 +1041,7 @@ var COPY_SUBSCRIBE = 32;
 var COPY_EMIT = 64;
 function clone(src) {
   const copied = Array.isArray(src) ? [] : src instanceof Map ? new Map : Object.create(Object.getPrototypeOf(src));
-  copyRecursive(copied, src, MERGE);
+  copyImpl(copied, src, MERGE);
   return copied;
 }
 var refHandler = {
@@ -1124,23 +1140,80 @@ function $(...args) {
   let savedCurrentScope;
   let err;
   let result;
+  let nextArgIsProp;
   for (let arg of args) {
-    if (arg == null || arg === false)
-      continue;
-    if (typeof arg === "string") {
-      let text;
-      let classes;
-      const textPos = arg.indexOf(":");
-      if (textPos >= 0) {
-        text = arg.substring(textPos + 1);
-        arg = arg.substring(0, textPos);
-      }
-      const classPos = arg.indexOf(".");
-      if (classPos >= 0) {
-        classes = arg.substring(classPos + 1);
-        arg = arg.substring(0, classPos);
-      }
-      if (arg === "") {
+    if (nextArgIsProp) {
+      applyArg(nextArgIsProp, arg);
+      nextArgIsProp = undefined;
+    } else if (arg == null || arg === false) {} else if (typeof arg === "string") {
+      let pos = 0;
+      let argLen = arg.length;
+      while (pos < argLen) {
+        let nextSpace = arg.indexOf(" ", pos);
+        if (nextSpace < 0)
+          nextSpace = arg.length;
+        let part = arg.substring(pos, nextSpace);
+        const oldPos = pos;
+        pos = nextSpace + 1;
+        const firstIs = part.indexOf("=");
+        const firstColon = part.indexOf(":");
+        if (firstIs >= 0 && (firstColon < 0 || firstIs < firstColon)) {
+          const prop = part.substring(0, firstIs);
+          if (firstIs < part.length - 1) {
+            let value = part.substring(firstIs + 1);
+            if (value[0] === '"') {
+              const closeIndex = arg.indexOf('"', firstIs + 2 + oldPos);
+              if (closeIndex < 0)
+                throw new Error(`Unterminated string for '${prop}'`);
+              value = arg.substring(firstIs + 2 + oldPos, closeIndex);
+              pos = closeIndex + 1;
+              if (arg[pos] === " ")
+                pos++;
+            }
+            applyArg(prop, value);
+            continue;
+          } else {
+            if (pos < argLen)
+              throw new Error(`No value given for '${part}'`);
+            nextArgIsProp = prop;
+            break;
+          }
+        }
+        let text;
+        if (firstColon >= 0) {
+          text = arg.substring(firstColon + 1 + oldPos);
+          part = part.substring(0, firstColon);
+          if (!text) {
+            if (pos < argLen)
+              throw new Error(`No value given for '${part}'`);
+            nextArgIsProp = "text";
+            break;
+          }
+          pos = argLen;
+        }
+        let classes;
+        const classPos = part.indexOf(".");
+        if (classPos >= 0) {
+          classes = part.substring(classPos + 1);
+          part = part.substring(0, classPos);
+        }
+        if (part) {
+          const svg = currentScope.inSvgNamespace || part === "svg";
+          if (svg) {
+            result = document.createElementNS("http://www.w3.org/2000/svg", part);
+          } else {
+            result = document.createElement(part);
+          }
+          addNode(result);
+          if (!savedCurrentScope)
+            savedCurrentScope = currentScope;
+          const newScope = new ChainedScope(result, true);
+          if (svg)
+            newScope.inSvgNamespace = true;
+          if (topRedrawScope === currentScope)
+            topRedrawScope = newScope;
+          currentScope = newScope;
+        }
         if (text)
           addNode(document.createTextNode(text));
         if (classes) {
@@ -1150,32 +1223,6 @@ function $(...args) {
             clean(() => el.classList.remove(...classes.split(".")));
           }
         }
-      } else if (arg.indexOf(" ") >= 0) {
-        err = `Tag '${arg}' cannot contain space`;
-        break;
-      } else {
-        const useNamespace = currentScope.inSvgNamespace || arg === "svg";
-        if (useNamespace) {
-          result = document.createElementNS("http://www.w3.org/2000/svg", arg);
-        } else {
-          result = document.createElement(arg);
-        }
-        if (classes)
-          result.className = classes.replaceAll(".", " ");
-        if (text)
-          result.textContent = text;
-        addNode(result);
-        if (!savedCurrentScope) {
-          savedCurrentScope = currentScope;
-        }
-        const newScope = new ChainedScope(result, true);
-        if (arg === "svg") {
-          newScope.inSvgNamespace = true;
-        }
-        newScope.lastChild = result.lastChild || undefined;
-        if (topRedrawScope === currentScope)
-          topRedrawScope = newScope;
-        currentScope = newScope;
       }
     } else if (typeof arg === "object") {
       if (arg.constructor !== Object) {
@@ -1204,9 +1251,10 @@ function $(...args) {
       break;
     }
   }
-  if (savedCurrentScope) {
+  if (nextArgIsProp !== undefined)
+    throw new Error(`No value given for '${nextArgIsProp}='`);
+  if (savedCurrentScope)
     currentScope = savedCurrentScope;
-  }
   if (err)
     throw new Error(err);
   return result;
@@ -1455,5 +1503,5 @@ export {
   $
 };
 
-//# debugId=37C620855881B81F64756E2164756E21
+//# debugId=1793ACD02DE96EE964756E2164756E21
 //# sourceMappingURL=aberdeen.js.map