aberdeen 0.5.0 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aberdeen",
-  "version": "0.5.0",
+  "version": "1.0.4",
   "author": "Frank van Viegen",
   "main": "dist-min/aberdeen.js",
   "devDependencies": {
@@ -12,31 +12,34 @@
     ".": {
       "default": "./dist-min/aberdeen.js",
       "development": "./dist/aberdeen.js",
-      "types`": "./dist/aberdeen.d.ts"
+      "types": "./dist/aberdeen.d.ts"
     },
     "./route": {
       "default": "./dist-min/route.js",
       "development": "./dist/route.js",
-      "types`": "./dist/route.d.ts"
+      "types": "./dist/route.d.ts"
     },
     "./transition": {
       "default": "./dist-min/transition.js",
       "development": "./dist/transition.js",
-      "types`": "./dist/transition.d.ts"
+      "types": "./dist/transition.d.ts"
     },
     "./prediction": {
       "default": "./dist-min/prediction.js",
       "development": "./dist/prediction.js",
-      "types`": "./dist/prediction.d.ts"
+      "types": "./dist/prediction.d.ts"
     },
     "./package.json": "./package.json"
   },
-  "description": "A TypeScript/JavaScript library for quickly building performant declarative user interfaces without the use of a virtual DOM nor any transpilation.",
+  "description": "A TypeScript/JavaScript library for quickly building performant reactive user interfaces without the use of a virtual DOM nor any transpilation.",
   "files": [
     "dist",
     "dist-min",
     "src"
   ],
+  "bin": {
+    "html-to-aberdeen": "./html-to-aberdeen"
+  },
   "license": "MIT",
   "scripts": {
     "build": "bun run build:dist && typedoc && rm -rf dist-docs/assets/aberdeen ; cp -r dist dist-docs/assets/aberdeen",

package/src/aberdeen.ts

@@ -1133,7 +1133,10 @@ export function proxy(target: TargetType): TargetType {
  * 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 function unproxy<T>(target: T): T {
@@ -1469,22 +1472,32 @@ const SPECIAL_PROPS: {[key: string]: (value: any) => void} = {
  *   - `{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 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 Nested Elements & Reactive Scope
+ * @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++ });
  * });
  * ```
@@ -1511,9 +1524,10 @@ const SPECIAL_PROPS: {[key: string]: (value: any) => void} = {
  */
 
 
-export function $(...args: (string | null | undefined | false | (() => void) | Record<string,any>)[]): void {
+export function $(...args: (string | null | undefined | false | (() => void) | Record<string,any>)[]): void | Element {
 	let savedCurrentScope;
 	let err;
+	let result;
 
 	for(let arg of args) {
 		if (arg == null || arg === false) continue;
@@ -1542,15 +1556,15 @@ export function $(...args: (string | null | undefined | false | (() => void) | R
 				err = `Tag '${arg}' cannot contain space`;
 				break;
 			} else {
-				const el = document.createElement(arg);
-				if (classes) el.className = classes.replaceAll('.', ' ');
-				if (text) el.textContent = text;
-				addNode(el);
+				result = document.createElement(arg);
+				if (classes) result.className = classes.replaceAll('.', ' ');
+				if (text) 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;
 			}
@@ -1575,6 +1589,7 @@ export function $(...args: (string | null | undefined | false | (() => void) | R
 		currentScope = savedCurrentScope;
 	}
 	if (err) throw new Error(err);
+	return result;
 }
 
 let cssCount = 0;
@@ -1725,7 +1740,7 @@ let onError: (error: Error) => boolean | undefined = defaultOnError;
  *
  *   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
  *   }
@@ -1733,8 +1748,20 @@ let onError: (error: Error) => boolean | undefined = defaultOnError;
  *   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();
  * })
  * ```
@@ -1751,7 +1778,7 @@ export function setErrorHandler(handler?: (error: Error) => boolean | undefined)
  * 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.
  *