aberdeen 1.18.1 → 1.18.2

package/skill/route.md

@@ -1,4 +1,4 @@
-[**Aberdeen v1.18.1**](README.md)
+[**Aberdeen v1.18.2**](README.md)
 
 ***
 
@@ -10,7 +10,7 @@
 
 ### Route
 
-Defined in: [route.ts:8](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L8)
+Defined in: [route.ts:8](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L8)
 
 The class for the global `route` object.
 
@@ -20,7 +20,7 @@ The class for the global `route` object.
 
 > **depth**: `number`
 
-Defined in: [route.ts:20](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L20)
+Defined in: [route.ts:20](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L20)
 
 The navigation depth of the current session. Starts at 1. Writing to this property has no effect.
 
@@ -28,7 +28,7 @@ The navigation depth of the current session. Starts at 1. Writing to this proper
 
 > **hash**: `string`
 
-Defined in: [route.ts:14](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L14)
+Defined in: [route.ts:14](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L14)
 
 The hash fragment including the leading `#`, or an empty string. For instance `"#my_section"` or `""`.
 
@@ -36,7 +36,7 @@ The hash fragment including the leading `#`, or an empty string. For instance `"
 
 > **nav**: `NavType`
 
-Defined in: [route.ts:28](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L28)
+Defined in: [route.ts:28](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L28)
 
 The navigation action that got us to this page. Writing to this property has no effect.
 - `"load"`: An initial page load.
@@ -49,7 +49,7 @@ Mostly useful for page transition animations. Writing to this property has no ef
 
 > **p**: `string`[]
 
-Defined in: [route.ts:12](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L12)
+Defined in: [route.ts:12](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L12)
 
 An convenience array containing path segments, mapping to `path`. For instance `[]` (for `"/"`) or `['users', '123', 'feed']` (for `"/users/123/feed"`).
 
@@ -57,7 +57,7 @@ An convenience array containing path segments, mapping to `path`. For instance `
 
 > **path**: `string`
 
-Defined in: [route.ts:10](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L10)
+Defined in: [route.ts:10](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L10)
 
 The current path of the URL as a string. For instance `"/"` or `"/users/123/feed"`. Paths are normalized to always start with a `/` and never end with a `/` (unless it's the root path).
 
@@ -65,7 +65,7 @@ The current path of the URL as a string. For instance `"/"` or `"/users/123/feed
 
 > **search**: `Record`\<`string`, `string`\>
 
-Defined in: [route.ts:16](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L16)
+Defined in: [route.ts:16](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L16)
 
 The query string interpreted as search parameters. So `"a=x&b=y"` becomes `{a: "x", b: "y"}`.
 
@@ -73,7 +73,7 @@ The query string interpreted as search parameters. So `"a=x&b=y"` becomes `{a: "
 
 > **state**: `Record`\<`string`, `any`\>
 
-Defined in: [route.ts:18](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L18)
+Defined in: [route.ts:18](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L18)
 
 An object to be used for any additional data you want to associate with the current page. Data should be JSON-compatible.
 
@@ -83,7 +83,7 @@ An object to be used for any additional data you want to associate with the curr
 
 > `const` **current**: [`Route`](#route)
 
-Defined in: [route.ts:312](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L312)
+Defined in: [route.ts:312](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L312)
 
 The global [Route](#route) object reflecting the current URL and browser history state. Changes you make to this affect the current browser history item (modifying the URL if needed).
 
@@ -93,7 +93,7 @@ The global [Route](#route) object reflecting the current URL and browser history
 
 > **back**(`target`): `void`
 
-Defined in: [route.ts:246](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L246)
+Defined in: [route.ts:246](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L246)
 
 Try to go back in history to the first entry that matches the given target. If none is found, the given state will replace the current page. This is useful for "cancel" or "close" actions that should return to the previous page if possible, but create a new page if not (for instance when arriving at the current page through a direct link).
 
@@ -117,7 +117,7 @@ The target route to go back to. May be a subset of [Route](#route), or a string
 
 > **go**(`target`, `nav`): `void`
 
-Defined in: [route.ts:170](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L170)
+Defined in: [route.ts:170](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L170)
 
 Navigate to a new URL by pushing a new history entry.
 
@@ -158,7 +158,7 @@ route.go({p: ["users", 123], search: {tab: "feed"}, hash: "top"});
 
 > **interceptLinks**(): `void`
 
-Defined in: [route.ts:432](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L432)
+Defined in: [route.ts:432](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L432)
 
 Intercept clicks and Enter key presses on links (`<a>` tags) and use Aberdeen routing
 instead of browser navigation for local paths (paths without a protocol or host).
@@ -186,7 +186,7 @@ A('a text=About href=/corporate/about');
 
 > **matchCurrent**(`target`): `boolean`
 
-Defined in: [route.ts:205](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L205)
+Defined in: [route.ts:205](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L205)
 
 Returns `true` if the current route matches `target`.
 
@@ -224,7 +224,7 @@ route.matchCurrent({path: '/users', search: {tab: 'profile'}});
 
 > **persistScroll**(`name`): `void`
 
-Defined in: [route.ts:398](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L398)
+Defined in: [route.ts:398](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L398)
 
 Restore and store the vertical and horizontal scroll position for
 the parent element to the page state.
@@ -250,7 +250,7 @@ The scroll position will be persisted in `route.aux.scroll.<name>`.
 
 > **push**(`target`, `nav?`): `void`
 
-Defined in: [route.ts:233](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L233)
+Defined in: [route.ts:233](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L233)
 
 Modify the current route by merging `target` into it (using [A.merge](aberdeen.md#merge)), pushing a new history entry.
 
@@ -281,7 +281,7 @@ The navigation type to use. Defaults to `undefined`, meaning the navigation type
 
 > **setLog**(`value`): `void`
 
-Defined in: [route.ts:37](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L37)
+Defined in: [route.ts:37](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L37)
 
 Configure logging on route changes.
 
@@ -303,7 +303,7 @@ Configure logging on route changes.
 
 > **up**(`stripCount`): `void`
 
-Defined in: [route.ts:272](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/route.ts#L272)
+Defined in: [route.ts:272](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/route.ts#L272)
 
 Navigate up in the path hierarchy, by going back to the first history entry
 that has a shorter path than the current one. If there's none, we just shorten

package/skill/transitions.md

@@ -1,4 +1,4 @@
-[**Aberdeen v1.18.1**](README.md)
+[**Aberdeen v1.18.2**](README.md)
 
 ***
 
@@ -12,7 +12,7 @@
 
 > **grow**(`el`): `Promise`\<`void`\>
 
-Defined in: [transitions.ts:33](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/transitions.ts#L33)
+Defined in: [transitions.ts:33](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/transitions.ts#L33)
 
 Do a grow transition for the given element. This is meant to be used as a
 handler for the `create` property.
@@ -38,7 +38,7 @@ for other specific cases as well.
 
 > **shrink**(`el`): `Promise`\<`void`\>
 
-Defined in: [transitions.ts:56](https://github.com/vanviegen/aberdeen/blob/55a4fa0c4453a12cdb744d6fa13f1a739c06c0a0/src/transitions.ts#L56)
+Defined in: [transitions.ts:56](https://github.com/vanviegen/aberdeen/blob/ae96ee5d2bf101de8d04c7efc61a03e8fe8fe6f7/src/transitions.ts#L56)
 
 Do a shrink transition for the given element, and remove it from the DOM
 afterwards. This is meant to be used as a handler for the `destroy` property.

package/src/aberdeen.ts

@@ -31,7 +31,7 @@ let survivingEl: Element | undefined;
 // scope's own element, so whether they need undoing can be decided once per scope (see `delete`).
 const enum SideEffect {
 	Class = 0, // key: class name           value: whether the class was present before (boolean)
-	Style = 1, // key: camelCase style prop  value: previous style value (string)
+	Style = 1, // key: camelCase style prop or `--custom-prop`  value: previous style value (string)
 	Prop = 2,  // key: DOM property name     value: previous property value
 	Attr = 3,  // key: attribute name        value: previous attribute value (string | null)
 	Event = 4, // key: event name            value: the listener function to remove
@@ -48,7 +48,10 @@ function undoSideEffects(el: any, se: any[]) {
 		const value = se[i + 2];
 		switch (se[i] as SideEffect) {
 			case SideEffect.Class: value ? el.classList.add(key) : el.classList.remove(key); break;
-			case SideEffect.Style: el.style[key] = value == null ? "" : value; break;
+			case SideEffect.Style:
+				if (key[0] === "-" && key[1] === "-") value ? el.style.setProperty(key, value) : el.style.removeProperty(key);
+				else el.style[key] = value == null ? "" : value;
+				break;
 			case SideEffect.Prop: el[key] = value; break;
 			case SideEffect.Attr: value == null ? el.removeAttribute(key) : el.setAttribute(key, value); break;
 			case SideEffect.Event: el.removeEventListener(key, value); break;
@@ -2004,13 +2007,14 @@ export function setSpacingCssVars(base = 1, unit = 'rem'): void {
 }
 
 // Matches: (1) url() content, (2) quoted content, (3) $varName at start or after space
-const CSS_VAR_PATTERN = /(\burl\([^)]*\))|("[^"]*")|(^| )\$([\w-]+)/g;
+const CSS_VAR_PATTERN = /(\burl\([^)]*\))|("[^"]*")|(^|[\s(,])\$([\w-]+)/g;
 const DIGIT_FIRST = /^\d/;
 
 /**
  * Expands all `$varName` patterns in a CSS value to `var(--varName)`.
- * Only matches `$` at the start of the value or after a space.
- * Content inside parentheses or quotes is preserved as-is.
+ * Only matches `$` at the start of the value or after a space, `(` or `,`
+ * (so e.g. `linear-gradient($a, $b)` expands as expected).
+ * Content inside `url(...)` or quotes is preserved as-is.
  * Numeric names get an 'm' prefix (e.g., `$3` → `var(--m3)`).
  * Variable names may include dashes (e.g., `$primary-color` → `var(--primary-color)`).
  */
@@ -2351,6 +2355,8 @@ export function disableCreateDestroy() {
  * | `r` | `border-radius` |
  * 
  * Also, when the value is a string starting with `$`, it is treated as a reference to a CSS variable, expanding to `var(--variableName)`. For numeric variable names (which can't be used directly as CSS custom property names), Aberdeen prefixes them with `m`, so `$3` expands to `var(--m3)`. This is primarily intended for use with {@link setSpacingCssVars}, which initializes spacing variables named `0` through `12` with an exponential spacing scale.
+ *
+ * To *set* a CSS custom property inline on an element, use a `--name` or (symmetrically with the `$`-reference syntax above) a `$name` key. For example `A('div --primary:red')` and `A('div $primary:red')` both set `--primary` to `red`.
  * 
  * @returns The most inner DOM element that was created (not counting text nodes nor elements created by content functions), or the current element if no new element was created. You should normally not need to use the return value - use this function's DOM manipulation abilities instead. One valid use case is when integrating with non-Aberdeen code that requires a reference to a DOM element.
  *
@@ -2816,16 +2822,27 @@ function applyArg(el: Element, key: string, value: any) {
 	} else if (key[0] === "$") {
 		// Style (with shortcuts)
 		key = key.substring(1);
+		// A leading `$` denotes a custom property, for symmetry with `$var` value references
+		// (e.g. `$$primary: red` sets `--primary`). `--primary` works too.
+		if (key[0] === "$") key = "--" + key.substring(1);
 		const val = value == null || value === false ? "" : typeof value === 'string' ? cssVarRef(value) : String(value);
 		const expanded = CSS_SHORT[key] || key;
 		const style = (el as any).style;
 		const setOwn = el === currentScope.el;
 		const props = typeof expanded === "string" ? [expanded] : expanded;
 		for (const prop of props) {
-			const cm = toCamel(prop);
-			// Record the style property's pre-scope value so it can be restored when the scope is cleaned.
-			if (setOwn) recordSideEffect(currentScope, SideEffect.Style, cm, style[cm]);
-			style[cm] = val;
+			if (prop[0] === "-" && prop[1] === "-") {
+				// Custom property: must go through setProperty/removeProperty, as bracket
+				// assignment of `--*` names is a no-op on a real CSSStyleDeclaration.
+				if (setOwn) recordSideEffect(currentScope, SideEffect.Style, prop, style.getPropertyValue(prop));
+				if (val === "") style.removeProperty(prop);
+				else style.setProperty(prop, val);
+			} else {
+				const cm = toCamel(prop);
+				// Record the style property's pre-scope value so it can be restored when the scope is cleaned.
+				if (setOwn) recordSideEffect(currentScope, SideEffect.Style, cm, style[cm]);
+				style[cm] = val;
+			}
 		}
 	} else if (value == null) {
 		// Value left empty