aberdeen 1.4.3 → 1.6.0

package/skill/dispatcher.md

@@ -0,0 +1,126 @@
+[**Aberdeen v1.6.0**](README.md)
+
+***
+
+[Aberdeen](README.md) / dispatcher
+
+# dispatcher
+
+## Classes
+
+### Dispatcher
+
+Defined in: [dispatcher.ts:58](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/dispatcher.ts#L58)
+
+Simple route matcher and dispatcher.
+
+Example usage:
+
+```ts
+const dispatcher = new Dispatcher();
+
+dispatcher.addRoute("user", Number, "stream", String, (id, stream) => {
+   console.log(`User ${id}, stream ${stream}`);
+});
+
+dispatcher.dispatch(["user", "42", "stream", "music"]);
+// Logs: User 42, stream music
+
+dispatcher.addRoute("search", matchRest, (terms: string[]) => {
+    console.log("Search terms:", terms);
+});
+
+dispatcher.dispatch(["search", "classical", "piano"]);
+// Logs: Search terms: [ 'classical', 'piano' ]
+```
+
+#### Constructors
+
+##### Constructor
+
+> **new Dispatcher**(): [`Dispatcher`](#dispatcher)
+
+###### Returns
+
+[`Dispatcher`](#dispatcher)
+
+#### Methods
+
+##### addRoute()
+
+> **addRoute**\<`T`, `H`\>(...`args`): `void`
+
+Defined in: [dispatcher.ts:70](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/dispatcher.ts#L70)
+
+Add a route with matchers and a handler function.
+
+###### Type Parameters
+
+###### T
+
+`T` *extends* `Matcher`[]
+
+Array of matcher types.
+
+###### H
+
+`H` *extends* (...`args`) => `void`
+
+Handler function type, inferred from the matchers.
+
+###### Parameters
+
+###### args
+
+...\[`...T[]`, `H`\]
+
+An array of matchers followed by a handler function. Each matcher can be:
+- A string: matches exactly that string.
+- A function: takes a string segment and returns a value (of any type) if it matches, or [matchFailed](#matchfailed) if it doesn't match. The return value (if not `matchFailed` and not `NaN`) is passed as a parameter to the handler function. The built-in functions `Number` and `String` can be used to match numeric and string segments respectively.
+- The special [matchRest](#matchrest) symbol: matches the rest of the segments as an array of strings. Only one `matchRest` is allowed, and it must be the last matcher.
+
+###### Returns
+
+`void`
+
+##### dispatch()
+
+> **dispatch**(`segments`): `boolean`
+
+Defined in: [dispatcher.ts:91](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/dispatcher.ts#L91)
+
+Dispatches the given segments to the first route handler that matches.
+
+###### Parameters
+
+###### segments
+
+`string`[]
+
+Array of string segments to match against the added routes. When using this class with the Aberdeen `route` module, one would typically pass `route.current.p`.
+
+###### Returns
+
+`boolean`
+
+True if a matching route was found and handled, false otherwise.
+
+## Variables
+
+### matchFailed
+
+> `const` **matchFailed**: unique `symbol`
+
+Defined in: [dispatcher.ts:4](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/dispatcher.ts#L4)
+
+Symbol to return when a custom [Dispatcher.addRoute](#addroute) matcher cannot match a segment.
+
+***
+
+### matchRest
+
+> `const` **matchRest**: unique `symbol`
+
+Defined in: [dispatcher.ts:9](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/dispatcher.ts#L9)
+
+Special [Dispatcher.addRoute](#addroute) matcher that matches the rest of the segments as an array of strings.

package/skill/prediction.md

@@ -0,0 +1,73 @@
+[**Aberdeen v1.6.0**](README.md)
+
+***
+
+[Aberdeen](README.md) / prediction
+
+# prediction
+
+## Functions
+
+### applyCanon()
+
+> **applyCanon**(`canonFunc?`, `dropPredictions?`): `void`
+
+Defined in: [prediction.ts:115](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/prediction.ts#L115)
+
+Temporarily revert all outstanding predictions, optionally run the provided function
+(which will generally make authoritative changes to the data based on a server response),
+and then attempt to reapply the predictions on top of the new canonical state, dropping
+any predictions that can no longer be applied cleanly (the data has been modified) or
+that were specified in `dropPredictions`.
+
+All of this is done such that redraws are only triggered if the overall effect is an
+actual change to an `Observable`.
+
+#### Parameters
+
+##### canonFunc?
+
+() => `void`
+
+The function to run without any predictions applied. This will typically
+ make authoritative changes to the data, based on a server response.
+
+##### dropPredictions?
+
+`Patch`[] = `[]`
+
+An optional list of predictions (as returned by `applyPrediction`)
+ to undo. Typically, when a server response for a certain request is being handled,
+ you'd want to drop the prediction that was done for that request.
+
+#### Returns
+
+`void`
+
+***
+
+### applyPrediction()
+
+> **applyPrediction**(`predictFunc`): `Patch`
+
+Defined in: [prediction.ts:93](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/prediction.ts#L93)
+
+Run the provided function, while treating all changes to Observables as predictions,
+meaning they will be reverted when changes come back from the server (or some other
+async source).
+
+#### Parameters
+
+##### predictFunc
+
+() => `void`
+
+The function to run. It will generally modify some Observables
+	to immediately reflect state (as closely as possible) that we expect the server
+ to communicate back to us later on.
+
+#### Returns
+
+`Patch`
+
+A `Patch` object. Don't modify it. This is only meant to be passed to `applyCanon`.

package/skill/route.md

@@ -0,0 +1,249 @@
+[**Aberdeen v1.6.0**](README.md)
+
+***
+
+[Aberdeen](README.md) / route
+
+# route
+
+## Interfaces
+
+### Route
+
+Defined in: [route.ts:8](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L8)
+
+The class for the global `route` object.
+
+#### Properties
+
+##### depth
+
+> **depth**: `number`
+
+Defined in: [route.ts:20](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L20)
+
+The navigation depth of the current session. Starts at 1. Writing to this property has no effect.
+
+##### hash
+
+> **hash**: `string`
+
+Defined in: [route.ts:14](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L14)
+
+The hash fragment including the leading `#`, or an empty string. For instance `"#my_section"` or `""`.
+
+##### nav
+
+> **nav**: `NavType`
+
+Defined in: [route.ts:28](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/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.
+- `"back"` or `"forward"`: When we navigated backwards or forwards in the stack.
+- `"go"`: When we added a new page on top of the stack.
+- `"push"`: When we added a new page on top of the stack, merging with the current page.
+Mostly useful for page transition animations. Writing to this property has no effect.
+
+##### p
+
+> **p**: `string`[]
+
+Defined in: [route.ts:12](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L12)
+
+An convenience array containing path segments, mapping to `path`. For instance `[]` (for `"/"`) or `['users', '123', 'feed']` (for `"/users/123/feed"`).
+
+##### path
+
+> **path**: `string`
+
+Defined in: [route.ts:10](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/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).
+
+##### search
+
+> **search**: `Record`\<`string`, `string`\>
+
+Defined in: [route.ts:16](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L16)
+
+The query string interpreted as search parameters. So `"a=x&b=y"` becomes `{a: "x", b: "y"}`.
+
+##### state
+
+> **state**: `Record`\<`string`, `any`\>
+
+Defined in: [route.ts:18](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/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.
+
+## Variables
+
+### current
+
+> `const` **current**: [`Route`](#route)
+
+Defined in: [route.ts:261](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L261)
+
+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).
+
+## Functions
+
+### back()
+
+> **back**(`target`): `void`
+
+Defined in: [route.ts:185](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L185)
+
+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).
+
+Consider using [up](#up) to go up in the path hierarchy.
+
+#### Parameters
+
+##### target
+
+`RouteTarget` = `{}`
+
+The target route to go back to. May be a subset of [Route](#route), or a string (for `path`), or an array of strings (for `p`).
+
+#### Returns
+
+`void`
+
+***
+
+### go()
+
+> **go**(`target`, `nav`): `void`
+
+Defined in: [route.ts:151](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L151)
+
+Navigate to a new URL by pushing a new history entry.
+
+Note that this happens synchronously, immediately updating `route` and processing any reactive updates based on that.
+
+#### Parameters
+
+##### target
+
+`RouteTarget`
+
+A subset of the [Route](#route) properties to navigate to. If neither `p` nor `path` is given, the current path is used. For other properties, an empty/default value is assumed if not given. For convenience:
+- You may pass a string instead of an object, which is interpreted as the `path`.
+- You may pass an array instead of an object, which is interpreted as the `p` array.
+- If you pass `p`, it may contain numbers, which will be converted to strings.
+- If you pass `search`, its values may be numbers, which will be converted to strings.
+
+Examples:
+```js
+// Navigate to /users/123
+route.go("/users/123");
+
+// Navigate to /users/123?tab=feed#top
+route.go({p: ["users", 123], search: {tab: "feed"}, hash: "top"});
+```
+
+##### nav
+
+`NavType` = `"go"`
+
+#### Returns
+
+`void`
+
+***
+
+### persistScroll()
+
+> **persistScroll**(`name`): `void`
+
+Defined in: [route.ts:237](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L237)
+
+Restore and store the vertical and horizontal scroll position for
+the parent element to the page state.
+
+#### Parameters
+
+##### name
+
+`string` = `"main"`
+
+A unique (within this page) name for this
+scrollable element. Defaults to 'main'.
+
+The scroll position will be persisted in `route.aux.scroll.<name>`.
+
+#### Returns
+
+`void`
+
+***
+
+### push()
+
+> **push**(`target`): `void`
+
+Defined in: [route.ts:172](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L172)
+
+Modify the current route by merging `target` into it (using [merge](aberdeen.md#merge)), pushing a new history entry.
+
+This is useful for things like opening modals or side panels, where you want a browser back action to return to the previous state.
+
+#### Parameters
+
+##### target
+
+`RouteTarget`
+
+Same as for [go](#go), but merged into the current route instead deleting all state.
+
+#### Returns
+
+`void`
+
+***
+
+### setLog()
+
+> **setLog**(`value`): `void`
+
+Defined in: [route.ts:37](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L37)
+
+Configure logging on route changes.
+
+#### Parameters
+
+##### value
+
+`true` to enable logging to console, `false` to disable logging, or a custom logging function. Defaults to `false`.
+
+`boolean` | (...`args`) => `void`
+
+#### Returns
+
+`void`
+
+***
+
+### up()
+
+> **up**(`stripCount`): `void`
+
+Defined in: [route.ts:210](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/src/route.ts#L210)
+
+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
+the current path.
+
+Note that going back in browser history happens asynchronously, so `route` will not be updated immediately.
+
+#### Parameters
+
+##### stripCount
+
+`number` = `1`
+
+#### Returns
+
+`void`

package/skill/transitions.md

@@ -0,0 +1,59 @@
+[**Aberdeen v1.6.0**](README.md)
+
+***
+
+[Aberdeen](README.md) / transitions
+
+# transitions
+
+## Functions
+
+### grow()
+
+> **grow**(`el`): `Promise`\<`void`\>
+
+Defined in: [transitions.ts:33](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/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.
+
+#### Parameters
+
+##### el
+
+`HTMLElement`
+
+The element to transition.
+
+The transition doesn't look great for table elements, and may have problems
+for other specific cases as well.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### shrink()
+
+> **shrink**(`el`): `Promise`\<`void`\>
+
+Defined in: [transitions.ts:56](https://github.com/vanviegen/aberdeen/blob/6b79c7fce769810bdcbd326b8ee6ef1c8e1fc011/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.
+
+#### Parameters
+
+##### el
+
+`HTMLElement`
+
+The element to transition and remove.
+
+The transition doesn't look great for table elements, and may have problems
+for other specific cases as well.
+
+#### Returns
+
+`Promise`\<`void`\>

package/src/aberdeen.ts

@@ -1644,7 +1644,7 @@ function copyRecursive<T extends object>(dst: T, src: T, flags: number): boolean
 					const old = dst.get(k);
 					dst.delete(k);
 					if (flags & COPY_EMIT) {
-						emit(dst, k, undefined, old);
+						emit(dst, k, EMPTY, old);
 					}
 					changed = true;
 				}
@@ -1677,7 +1677,7 @@ function copyRecursive<T extends object>(dst: T, src: T, flags: number): boolean
 					const old = dst[k];
 					delete dst[k];
 					if (flags & COPY_EMIT && old !== undefined) {
-						emit(dst, k, undefined, old);
+						emit(dst, k, EMPTY, old);
 					}
 					changed = true;
 				}
@@ -1704,23 +1704,135 @@ export const NO_COPY = Symbol("NO_COPY");
 (Promise.prototype as any)[NO_COPY] = true;
 
 /**
- * CSS variable lookup table for the `@` value prefix.
- * 
- * When a CSS value starts with `@`, the rest is used as a key to look up the actual value.
- * Pre-initialized with keys '1'-'12' mapping to an exponential rem scale (e.g., @1=0.25rem, @3=1rem).
- * 
+ * A reactive object containing CSS variable definitions.
+ *
+ * Any property you assign to `cssVars` becomes available as a CSS custom property throughout your application.
+ *
+ * Use {@link setSpacingCssVars} to optionally initialize `cssVars[1]` through `cssVars[12]` with an exponential spacing scale.
+ *
+ * When you reference a CSS variable in Aberdeen using the `$` prefix (e.g., `$primary`), it automatically resolves to `var(--primary)`.
+ * For numeric keys (which can't be used directly as CSS custom property names), Aberdeen prefixes them with `m` (e.g., `$3` becomes `var(--m3)`).
+ *
+ * When you add the first property to cssVars, Aberdeen automatically creates a reactive `<style>` tag in `<head>`
+ * containing the `:root` CSS custom property declarations. The style tag is automatically removed if cssVars becomes empty.
+ *
  * @example
- * ```typescript
+ * ```javascript
+ * import { cssVars, setSpacingCssVars, $ } from 'aberdeen';
+ *
+ * // Optionally initialize spacing scale
+ * setSpacingCssVars(); // Uses defaults: base=1, unit='rem'
+ *
+ * // Define custom colors - style tag is automatically created
  * cssVars.primary = '#3b82f6';
- * cssVars[3] = '16px'; // Override @3 to be 16px instead of 1rem
- * $('p color:@primary'); // Sets color to #3b82f6
- * $('div mt:@3'); // Sets margin-top to 16px
+ * cssVars.danger = '#ef4444';
+ *
+ * // Use in elements with the $ prefix
+ * $('button bg:$primary fg:white');
+ *
+ * // Use spacing (if setSpacingCssVars() was called)
+ * $('div mt:$3'); // Sets margin-top to var(--m3)
  * ```
  */
 export const cssVars: Record<string, string> = optProxy({});
 
-for (let i = 1; i <= 12; i++) {
-	cssVars[i] = 2 ** (i - 3) + "rem";
+/**
+ * Initializes `cssVars[1]` through `cssVars[12]` with an exponential spacing scale.
+ *
+ * The scale is calculated as `2^(n-3) * base`, providing values from `0.25 * base` to `512 * base`.
+ *
+ * @param base - The base size for the spacing scale (default: 1). If unit is 'rem' or 'em', this is in that unit. If unit is 'px', this is the pixel value.
+ * @param unit - The CSS unit to use (default: 'rem'). Can be 'rem', 'em', 'px', or any other valid CSS unit.
+ *
+ * @example
+ * ```javascript
+ * // Use default scale (0.25rem to 512rem)
+ * setSpacingCssVars();
+ *
+ * // Use custom base size
+ * setSpacingCssVars(16, 'px'); // 4px to 8192px
+ *
+ * // Use em units
+ * setSpacingCssVars(1, 'em'); // 0.25em to 512em
+ * ```
+ */
+export function setSpacingCssVars(base = 1, unit = 'rem'): void {
+	for (let i = 1; i <= 12; i++) {
+		cssVars[i] = 2 ** (i - 3) * base + unit;
+	}
+}
+
+const DIGIT_FIRST = /^\d/;
+function cssVarRef(name: string): string {
+	// Prefix numeric keys with 'm' (CSS custom property names can't start with a digit)
+	const varName = DIGIT_FIRST.test(name) ? `m${name}` : name;
+	return `var(--${varName})`;
+}
+
+// Automatically mount cssVars style tag to document.head when cssVars is not empty
+if (typeof document !== "undefined") {
+	leakScope(() => {
+		$(() => {
+			if (!isEmpty(cssVars)) {
+				mount(document.head, () => {
+					$('style', () => {
+						let css = ":root {\n";
+						for(const [key, value] of Object.entries(cssVars)) {
+							const varName = DIGIT_FIRST.test(String(key)) ? `m${key}` : key;
+							css += `  --${varName}: ${value};\n`;
+						}
+						css += "}";
+						$(`#${css}`);
+					});
+				});
+			}
+		});
+	});
+}
+
+/**
+ * Returns whether the user's browser prefers a dark color scheme.
+ *
+ * This function is reactive - scopes that call it will re-execute when the
+ * browser's color scheme preference changes (via the `prefers-color-scheme` media query).
+ *
+ * Use this in combination with {@link $} and {@link cssVars} to implement theme switching:
+ *
+ * @returns `true` if the browser prefers dark mode, `false` if it prefers light mode.
+ *
+ * @example
+ * ```javascript
+ * import { darkMode, cssVars, $, mount } from 'aberdeen';
+ *
+ * // Reactively set colors based on browser preference
+ * $(() => {
+ *   if (darkMode()) { // Optionally override this with user settings
+ *     cssVars.bg = '#1a1a1a';
+ *     cssVars.fg = '#e5e5e5';
+ *   } else {
+ *     cssVars.bg = '#ffffff';
+ *     cssVars.fg = '#000000';
+ *   }
+ * });
+ * ```
+ */
+export function darkMode(): boolean {
+	if (typeof window === 'undefined' || !window.matchMedia) return false;
+	
+	const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+	
+	// Read from proxy to establish reactivity
+	const changed = proxy(false);
+	changed.value; // Subscribe caller reactive scope
+	function onChange() {
+		changed.value = true;
+	}
+	mediaQuery.addEventListener('change', onChange);
+	clean(() => {
+		mediaQuery.removeEventListener('change', onChange);
+	})
+	
+	return mediaQuery.matches;
 }
 
 /**
@@ -2178,7 +2290,7 @@ function styleToCss(style: object, prefix: string): string {
 					);
 				}
 			} else {
-				const val = v == null || v === false ? "" : typeof v === 'string' ? (v[0] === '@' ? (cssVars as any)[v.substring(1)] || "" : v) : String(v);
+				const val = v == null || v === false ? "" : typeof v === 'string' ? (v[0] === '$' ? cssVarRef(v.substring(1)) : v) : String(v);
 				const expanded = CSS_SHORT[k] || k;
 				for (const prop of (Array.isArray(expanded) ? expanded : [expanded])) {
 					props += `${prop.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}:${val};`;
@@ -2207,7 +2319,7 @@ function applyArg(el: Element, key: string, value: any) {
 	} else if (key[0] === "$") {
 		// Style (with shortcuts)
 		key = key.substring(1);
-		const val = value == null || value === false ? "" : typeof value === 'string' ? (value[0] === '@' ? (cssVars as any)[value.substring(1)] || "" : value) : String(value);
+		const val = value == null || value === false ? "" : typeof value === 'string' ? (value[0] === '$' ? cssVarRef(value.substring(1)) : value) : String(value);
 		const expanded = CSS_SHORT[key] || key;
 		if (typeof expanded === "string") {
 			(el as any).style[expanded] = val;
@@ -2903,3 +3015,5 @@ export function withEmitHandler(
 		emit = oldEmitHandler;
 	}
 }
+
+