aberdeen 1.11.1 → 1.12.0

package/README.md

@@ -33,21 +33,22 @@ First, let's start with the obligatory reactive counter example. If you're readi
 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});
+// The '$' prefix is just a convention to make reactive objects stand out
+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('text=', `${state.question} ↪ ${state.answer || 'Blowing in the wind'}`)
+    A('text=', `${$state.question} ↪ ${$state.answer || 'Blowing in the wind'}`)
 });
 
-// Two-way bind state.question to an <input>
-A('input placeholder=Question bind=', A.ref(state, 'question'))
+// Two-way bind $state.question to an <input>
+A('input placeholder=Question bind=', A.ref($state, 'question'))
 
-// Allow state.answer to be modified using both an <input> and buttons
+// Allow $state.answer to be modified using both an <input> and buttons
 A('div.row margin-top:1em', () => {
-    A('button text=- click=', () => state.answer--);
-    A('input type=number bind=', A.ref(state, 'answer'))
-    A('button text=+ click=', () => state.answer++);
+    A('button text=- click=', () => $state.answer--);
+    A('input type=number bind=', A.ref($state, 'answer'))
+    A('button text=+ click=', () => $state.answer++);
 });
 ```
 
@@ -75,64 +76,64 @@ class TodoItem {
 // The top-level user interface.
 function drawMain() {
     // Add some initial items. We'll wrap a A.proxy() around it!
-    let items: TodoItem[] = A.proxy([
+    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);
+    A.onEach($items, drawItem, $item => $item.label);
 
     // Add item and delete checked buttons.
     A('div.row', () => {
-        A('button text=+ click=', () => items.push(new TodoItem("")));
+        A('button text=+ click=', () => $items.push(new TodoItem("")));
         A('button.outline text="Delete checked" click=', () => {
-            for(let idx in items) {
-                if (items[idx].done) delete items[idx];
+            for(let idx in $items) {
+                if ($items[idx].done) delete $items[idx];
             }
         });
     });
 };
 
 // Called for each todo list item.
-function drawItem(item) {
+function drawItem($item) {
     // Items without a label open in editing state.
     // Note that we're creating this A.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 == '');
+    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({".done": A.ref(item,'done')});
+        A({".done": A.ref($item,'done')});
 
         // The checkmark is hidden using CSS
         A('div.checkmark text=✅');
 
-        if (editing.value) {
+        if ($editing.value) {
             // Proxied string to hold label while being edited.
-            const labelCopy = A.proxy(item.label);
+            const $labelCopy = A.proxy($item.label);
             function save() {
-                editing.value = false;
-                item.label = labelCopy.value;
+                $editing.value = false;
+                $item.label = $labelCopy.value;
             }
             // Label <input>. Save using enter or button.
-            A('input placeholder=Label bind=', labelCopy, 'keydown=', e => e.key==='Enter' && save());
-            A('button.outline text=Cancel click=', () => editing.value = false);
+            A('input placeholder=Label bind=', $labelCopy, 'keydown=', e => e.key==='Enter' && save());
+            A('button.outline text=Cancel click=', () => $editing.value = false);
             A('button text=Save click=', save);
         } else {
             // Label as text. 
-            A('p text=', item.label);
+            A('p text=', $item.label);
 
             // Edit icon, if not done.
-            if (!item.done) {
+            if (!$item.done) {
                 A('a text=Edit click=', e => {
-                    editing.value = true;
+                    $editing.value = true;
                     e.stopPropagation(); // We don't want to toggle as well.
                 });
             }
             
             // Clicking a row toggles done.
-            A('cursor:pointer click=', () => item.done = !item.done);
+            A('cursor:pointer click=', () => $item.done = !$item.done);
         }
     });
 }

package/dist/src/aberdeen.d.ts

@@ -14,13 +14,13 @@
  *
  * @example
  * ```typescript
- * const data = A.proxy("before");
+ * const $data = A.proxy("before");
  *
- * A('#', data);
+ * A('#', $data);
  * console.log(1, document.body.innerHTML); // before
  *
  * // Make an update that should cause the DOM to change.
- * data.value = "after";
+ * $data.value = "after";
  *
  * // Normally, the DOM update would happen after a timeout.
  * // But this causes an immediate update:
@@ -42,15 +42,15 @@ export declare function runQueue(): void;
  *
  * @example
  * ```typescript
- * const users = A.proxy([
+ * const $users = A.proxy([
  *     { id: 1, name: 'Charlie', score: 95 },
  *     { id: 2, name: 'Alice', score: 100 },
  *     { id: 3, name: 'Bob', score: 90 },
  * ]);
  *
- * A.onEach(users, (user) => {
- *     A(`p#${user.name}: ${user.score}`);
- * }, (user) => A.invertString(user.name)); // Reverse alphabetic order
+ * A.onEach($users, ($user) => {
+ *     A(`p#${$user.name}: ${$user.score}`);
+ * }, ($user) => A.invertString($user.name)); // Reverse alphabetic order
  * ```
  *
  * @param input The string whose sort order needs to be inverted.
@@ -78,21 +78,21 @@ export declare const EMPTY: unique symbol;
  *
  * @example
  * ```typescript
- * const items = A.proxy([]);
+ * const $items = A.proxy([]);
  *
  * // Reactively display a message if the items array is empty
  * A('div', () => {
- *     if (A.isEmpty(items)) {
+ *     if (A.isEmpty($items)) {
  *         A('p i#No items yet!');
  *     } else {
- *         A.onEach(items, item => A('p#'+item));
+ *         A.onEach($items, item => A('p#'+item));
  *     }
  * });
  *
  * // Adding an item will automatically remove the "No items yet!" message
  * setInterval(() => {
- *   if (!items.length || Math.random()>0.5) items.push('Item');
- *   else items.length = 0;
+ *   if (!$items.length || Math.random()>0.5) $items.push('Item');
+ *   else $items.length = 0;
  * }, 1000)
  * ```
  */
@@ -109,19 +109,19 @@ export interface ValueRef<T> {
  *
  * @example
  * ```typescript
- * const items = A.proxy({x: 3, y: 7} as any);
- * const cnt = A.count(items);
+ * const $items = A.proxy({x: 3, y: 7} as any);
+ * const $count = A.count($items);
  *
  * // Create a DOM text node for the count:
- * A('div text=', cnt);
+ * A('div text=', $count);
  * // <div>2</div>
 
  * // Or we can use it in an {@link derive} function:
- * A(() => console.log("The count is now", cnt.value));
+ * A(() => console.log("The count is now", $count.value));
  * // The count is now 2
  *
  * // Adding/removing items will update the count
- * items.z = 12;
+ * $items.z = 12;
  * // Asynchronously, after 0ms:
  * // <div>3</div>
  * // The count is now 3
@@ -162,23 +162,23 @@ export declare function proxy<T extends any>(target: T): ValueRef<T extends numb
  *
  * @example
  * ```typescript
- * const userProxy = A.proxy({ name: 'Frank' });
- * const rawUser = A.unproxy(userProxy);
+ * const $user = A.proxy({ name: 'Frank' });
+ * const rawUser = A.unproxy($user);
  *
  * // Log reactively
- * A(() => console.log('proxied', userProxy.name));
+ * A(() => console.log('proxied', $user.name));
  * // The following will only ever log once, as we're not subscribing to any observable
  * A(() => console.log('unproxied', rawUser.name));
  *
  * // This cause the first log to run again:
- * setTimeout(() => userProxy.name += '!', 1000);
+ * setTimeout(() => $user.name += '!', 1000);
  *
  * // This doesn't cause any new logs:
  * setTimeout(() => rawUser.name += '?', 2000);
  *
- * // Both userProxy and rawUser end up as `{name: 'Frank!?'}`
+ * // Both $user and rawUser end up as `{name: 'Frank!?'}`
  * setTimeout(() => {
- *   console.log('final proxied', userProxy)
+ *   console.log('final proxied', $user)
  *   console.log('final unproxied', rawUser)
  * }, 3000);
  * ```
@@ -203,12 +203,12 @@ export declare function unproxy<T>(target: T): T;
  *
  * @example Basic Copy
  * ```typescript
- * const source = A.proxy({ a: 1, b: { c: 2 } });
- * const dest = A.proxy({ b: { d: 3 } });
- * A.copy(dest, source);
- * console.log(dest); // proxy({ a: 1, b: { c: 2 } })
- * A.copy(dest, 'b', { e: 4 });
- * console.log(dest); // proxy({ a: 1, b: { e: 4 } })
+ * const $source = A.proxy({ a: 1, b: { c: 2 } });
+ * const $dest = A.proxy({ b: { d: 3 } });
+ * A.copy($dest, $source);
+ * console.log($dest); // proxy({ a: 1, b: { c: 2 } })
+ * A.copy($dest, 'b', { e: 4 });
+ * console.log($dest); // proxy({ a: 1, b: { e: 4 } })
  * ```
  */
 export declare function copy<T extends object>(dst: T, src: T): boolean;
@@ -226,11 +226,11 @@ export declare function copy<T extends object>(dst: T, dstKey: keyof T, src: T[t
  * @example Basic merge
  * ```typescript
  * const source = { b: { c: 99 }, d: undefined }; // d: undefined will delete
- * const dest = A.proxy({ a: 1, b: { x: 5 }, d: 4 });
- * A.merge(dest, source);
- * A.merge(dest, 'b', { y: 6 }); // merge into dest.b
- * A.merge(dest, 'c', { z: 7 }); // merge.c doesn't exist yet, so it will just be assigned
- * console.log(dest); // proxy({ a: 1, b: { c: 99, x: 5, y: 6 }, c: { z: 7 } })
+ * const $dest = A.proxy({ a: 1, b: { x: 5 }, d: 4 });
+ * A.merge($dest, source);
+ * A.merge($dest, 'b', { y: 6 }); // merge into $dest.b
+ * A.merge($dest, 'c', { z: 7 }); // $dest.c doesn't exist yet, so it will just be assigned
+ * console.log($dest); // proxy({ a: 1, b: { c: 99, x: 5, y: 6 }, c: { z: 7 } })
  * ```
  *
  */
@@ -349,16 +349,16 @@ export declare function clone<T extends object>(src: T): T;
  *
  * @example
  * ```javascript
- * const formData = A.proxy({ color: 'orange', velocity: 42 });
+ * const $formData = A.proxy({ color: 'orange', velocity: 42 });
  *
  * // Usage with `bind`
- * A('input type=text bind=', A.ref(formData, 'color'));
+ * A('input type=text bind=', A.ref($formData, 'color'));
  *
  * // Usage as a dynamic property, causes a TextNode with just the name to be created and live-updated
- * A('p text="Selected color: " text=', A.ref(formData, 'color'), 'color:', A.ref(formData, 'color'));
+ * A('p text="Selected color: " text=', A.ref($formData, 'color'), 'color:', A.ref($formData, 'color'));
  *
- * // Changes are actually stored in formData - this causes logs like `{color: "Blue", velocity 42}`
- * A(() => console.log(formData))
+ * // Changes are actually stored in $formData - this causes logs like `{color: "Blue", velocity 42}`
+ * A(() => console.log($formData))
  * ```
  */
 export declare function ref<T extends TargetType, K extends keyof T>(target: T, index: K): ValueRef<T[K]>;
@@ -455,29 +455,29 @@ export declare function disableCreateDestroy(): void;
  *
  * @example Content Functions & Reactive Scope
  * ```typescript
- * const state = A.proxy({ count: 0 });
+ * const $state = A.proxy({ count: 0 });
  * A('div', () => { // Outer element
- *   // This scope re-renders when state.count changes
- *   A(`p#Count is ${state.count}`);
- *   A('button text=Increment click=', () => state.count++);
+ *   // This scope re-renders when $state.count changes
+ *   A(`p#Count is ${$state.count}`);
+ *   A('button text=Increment click=', () => $state.count++);
  * });
  * ```
  *
  * @example Two-way Binding
  * ```typescript
- * const user = A.proxy({ name: '' });
- * A('input placeholder=Name bind=', A.ref(user, 'name'));
+ * const $user = A.proxy({ name: '' });
+ * A('input placeholder=Name bind=', A.ref($user, 'name'));
  * A('h3', () => { // Reactive scope
- *   A(`#Hello ${user.name || 'stranger'}`);
+ *   A(`#Hello ${$user.name || 'stranger'}`);
  * });
  * ```
  *
  * @example Conditional Rendering
  * ```typescript
- * const show = A.proxy(false);
- * A('button click=', () => show.value = !show.value, () => A(show.value ? '#Hide' : '#Show'));
+ * const $show = A.proxy(false);
+ * A('button click=', () => $show.value = !$show.value, () => A($show.value ? '#Hide' : '#Show'));
  * A(() => { // Reactive scope
- *   if (show.value) {
+ *   if ($show.value) {
  *     A('p#Details are visible!');
  *   }
  * });
@@ -485,8 +485,8 @@ export declare function disableCreateDestroy(): void;
  *
  * @example Proxied objects as values
  * ```typescript
- * const myColor = A.proxy('red');
- * A('p text="The color is " text=', myColor, 'click=', () => myColor.value = 'yellow')
+ * const $myColor = A.proxy('red');
+ * A('p text="The color is " text=', $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`.
@@ -604,6 +604,20 @@ export declare function insertCss(style: string | object): string;
  *   }
  * });
  * ```
+ * At-rules such as `@media` and `@keyframes` should use nested objects. For keyframes,
+ * the step selectors (`0%`, `50%`, `100%`, etc.) become the nested keys and each value
+ * should be a concise CSS declaration string.
+ *
+ * @example Animation Keyframes
+ * ```typescript
+ * A.insertGlobalCss({
+ *   "@keyframes connection-pulse": {
+ *     "0%": "box-shadow: inset 0 0 0 0 rgba(255, 70, 70, 0.4);",
+ *     "50%": "box-shadow: inset 0 0 0 6px rgba(255, 70, 70, 0.08);",
+ *     "100%": "box-shadow: inset 0 0 0 0 rgba(255, 70, 70, 0.4);"
+ *   }
+ * });
+ * ```
  */
 export declare function insertGlobalCss(style: object): void;
 /**
@@ -663,27 +677,27 @@ export declare function setErrorHandler(handler?: (error: Error) => boolean | un
  *
  * @example Maintaing a sum for a changing array
  * ```typescript
- * const myArray = A.proxy([3, 5, 10]);
- * let sum = A.proxy(0);
+ * const $numbers = A.proxy([3, 5, 10]);
+ * let $sum = A.proxy(0);
  *
  * // Show the array items and maintain the sum
- * A.onEach(myArray, (item, index) => {
+ * A.onEach($numbers, (item, index) => {
  *     A(`code#${index}→${item}`);
- *     // We'll update sum.value using peek, as += first does a read, but
+ *     // We'll update $sum.value using peek, as += first does a read, but
  *     // we don't want to subscribe.
- *     A.peek(() => sum.value += item);
+ *     A.peek(() => $sum.value += item);
  *     // Clean gets called before each rerun for a certain item index
  *     // No need for peek here, as the clean code doesn't run in an
  *     // observer scope.
- *     A.clean(() => sum.value -= item);
+ *     A.clean(() => $sum.value -= item);
  * })
  *
  * // Show the sum
- * A('h1 text=', sum);
+ * A('h1 text=', $sum);
  *
  * // Make random changes to the array
  * const rnd = () => 0|(Math.random()*20);
- * setInterval(() => myArray[rnd()] = rnd(), 1000);
+ * setInterval(() => $numbers[rnd()] = rnd(), 1000);
  * ```
  */
 export declare function clean(cleaner: () => void): void;
@@ -701,20 +715,20 @@ export declare function clean(cleaner: () => void): void;
  *   observable returned by the `derive()` function.
  * @returns An observable object, with its `value` property containing whatever the last run of `func` returned.
  *
- * @example Observation creating a UI components
+ * @example Observation creating UI components
  * ```typescript
- * const data = A.proxy({ user: 'Frank', notifications: 42 });
+ * const $data = A.proxy({ user: 'Frank', notifications: 42 });
  *
  * A('main', () => {
  *   console.log('Welcome');
- *   A('h3#Welcome, ' + data.user); // Reactive text
+ *   A('h3#Welcome, ' + $data.user); // Reactive text
  *
  *   A.derive(() => {
- *     // When data.notifications changes, only this inner scope reruns,
+ *     // When $data.notifications changes, only this inner scope reruns,
  *     // leaving the `<p>Welcome, ..</p>` untouched.
  *     console.log('Notifications');
- *     A('code.notification-badge text=', data.notifications);
- *     A('a text=Notify! click=', () => data.notifications++);
+ *     A('code.notification-badge text=', $data.notifications);
+ *     A('a text=Notify! click=', () => $data.notifications++);
  *   });
  * });
  * ```
@@ -723,12 +737,12 @@ export declare function clean(cleaner: () => void): void;
  *
  * @example Observation with return value
  * ```typescript
- * const counter = A.proxy(0);
- * setInterval(() => counter.value++, 1000);
- * const double = A.derive(() => counter.value * 2);
+ * const $counter = A.proxy(0);
+ * setInterval(() => $counter.value++, 1000);
+ * const $double = A.derive(() => $counter.value * 2);
  *
  * A('h3', () => {
- *     A(`#counter=${counter.value} double=${double.value}`);
+ *     A(`#counter=${$counter.value} double=${$double.value}`);
  * })
  * ```
  *
@@ -761,16 +775,16 @@ export declare function derive<T>(func: () => T): ValueRef<T>;
  *
  * import A from 'aberdeen';
  *
- * const runTime = A.proxy(0);
- * setInterval(() => runTime.value++, 1000);
+ * const $runTime = A.proxy(0);
+ * setInterval(() => $runTime.value++, 1000);
  *
  * A.mount(document.getElementById('app-root'), () => {
  *   A('h4#Aberdeen App');
- *   A(`p#Run time: ${runTime.value}s`);
+ *   A(`p#Run time: ${$runTime.value}s`);
  *   // Conditionally render some content somewhere else in the static page
- *   if (runTime.value&1) {
+ *   if ($runTime.value&1) {
  *     A.mount(document.getElementById('title-extra'), () =>
- *       A(`i#(${runTime.value}s)`)
+ *       A(`i#(${$runTime.value}s)`)
  *     );
  *   }
  * });
@@ -801,14 +815,14 @@ export declare function unmountAll(): void;
  *
  * @example Peeking within observer
  * ```typescript
- * const data = A.proxy({ a: 1, b: 2 });
+ * const $data = A.proxy({ a: 1, b: 2 });
  * A(() => {
- *   // re-executes only when data.a changes, because data.b is peeked.
- *   const b = A.peek(() => data.b);
- *   console.log(`A is ${data.a}, B was ${b} when A changed.`);
+ *   // re-executes only when $data.a changes, because $data.b is peeked.
+ *   const b = A.peek(() => $data.b);
+ *   console.log(`A is ${$data.a}, B was ${b} when A changed.`);
  * });
- * data.b = 3; // Does not trigger console.log
- * data.a = 2; // Triggers console.log (logs "A is 2, B was 3 when A changed.")
+ * $data.b = 3; // Does not trigger console.log
+ * $data.a = 2; // Triggers console.log (logs "A is 2, B was 3 when A changed.")
  * ```
  *
  */
@@ -855,16 +869,16 @@ export declare function partition<IN_K extends string | number | symbol, OUT_K e
  * ```typescript
  * import A from 'aberdeen';
  *
- * const state = A.proxy({
+ * const $state = A.proxy({
  *   user: { name: 'Frank', kids: 1 },
  *   items: ['a', 'b']
  * });
  *
  * A('h2#Live State Dump');
- * A.dump(state);
+ * A.dump($state);
  *
  * // Change state later, the dump in the DOM will update
- * setTimeout(() => { state.user.kids++; state.items.push('c'); }, 2000);
+ * setTimeout(() => { $state.user.kids++; $state.items.push('c'); }, 2000);
  * ```
  */
 export declare function dump<T>(data: T): T;
@@ -877,10 +891,10 @@ export declare function dump<T>(data: T): T;
  * ```typescript
  * import A from 'aberdeen';
  *
- * const state = A.proxy({ count: 0 });
+ * const $state = A.proxy({ count: 0 });
  * A('div', () => {
- *   A(`p#Count: ${state.count}`);
- *   A('button text=+ click=', () => state.count++);
+ *   A(`p#Count: ${$state.count}`);
+ *   A('button text=+ click=', () => $state.count++);
  * });
  * ```
  */

package/dist/src/aberdeen.js

@@ -1533,6 +1533,7 @@ var KEBAB_SEGMENT = /-([a-z])/g;
 function toCamel(p) {
   return p.replace(KEBAB_SEGMENT, (_, l) => l.toUpperCase());
 }
+var VALID_CSS_KEY = /^[a-zA-Z-]+$/;
 function styleStringToCss(styleStr, selector) {
   let props = "";
   for (let pos = 0, len = styleStr.length;pos < len; ) {
@@ -1542,8 +1543,10 @@ function styleStringToCss(styleStr, selector) {
       break;
     const colon = styleStr.indexOf(":", pos);
     if (colon === -1)
-      break;
+      throw new Error(`Trailing data in style string: "${styleStr.substring(pos)}"`);
     const key = styleStr.substring(pos, colon);
+    if (!VALID_CSS_KEY.test(key))
+      throw new Error(`Invalid CSS key: "${key}" in style string: "${styleStr}"`);
     pos = colon + 1;
     let val;
     if (styleStr[pos] === " ") {
@@ -1868,5 +1871,5 @@ export {
   A
 };
 
-//# debugId=CEB17464CFEBA2F464756E2164756E21
+//# debugId=C25FF24CC098C9BC64756E2164756E21
 //# sourceMappingURL=aberdeen.js.map