aberdeen 1.18.2 → 1.19.0

package/skill/merge.md

@@ -0,0 +1,27 @@
+## merge · function
+
+Like `copy`, but uses merge semantics. Properties in `dst` not present in `src` are kept.
+`null`/`undefined` in `src` delete properties in `dst`.
+
+**Signature:** `{ <T extends object>(dst: T, value: Partial<T>): boolean; <T extends object>(dst: T, dstKey: keyof T, value: Partial<T[keyof T]>): boolean; }`
+
+**Type Parameters:**
+
+- `T extends object`
+
+**Parameters:**
+
+- `dst: T`
+- `value: Partial<T>`
+
+**Examples:**
+
+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 }); // $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 } })
+```

package/skill/mount.md

@@ -0,0 +1,48 @@
+## mount · function
+
+Attaches a reactive Aberdeen UI fragment to an existing DOM element. Without the use of
+this function, | A will assume `document.body` as its root.
+
+It creates a top-level reactive scope associated with the `parentElement`. The provided
+function `func` is executed immediately within this scope. Any proxied data read by `func`
+will cause it to re-execute when the data changes, updating the DOM elements created within it.
+
+Calls to | A inside `func` will append nodes to `parentElement`.
+You can nest `derive` or other | A scopes within `func`.
+Use `unmountAll` to clean up all mounted scopes and their DOM nodes.
+
+Mounting scopes happens reactively, meaning that if this function is called from within another
+(`derive` or | A or `mount`) scope that gets cleaned up, so will the mount.
+
+**Signature:** `(parentElement: Element, func: () => void) => void`
+
+**Parameters:**
+
+- `parentElement: Element` - - The native DOM `Element` to which the UI fragment will be appended.
+- `func: () => void` - - The function that defines the UI fragment, typically containing calls to | A.
+
+**Examples:**
+
+Basic Mount
+```javascript
+// Create a pre-existing DOM structure (without Aberdeen)
+document.body.innerHTML = `<h3>Static content <span id="title-extra"></span></h3><div class="box" id="app-root"></div>`;
+
+import A from 'aberdeen';
+
+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`);
+// Conditionally render some content somewhere else in the static page
+if ($runTime.value&1) {
+A.mount(document.getElementById('title-extra'), () =>
+A(`i#(${$runTime.value}s)`)
+);
+}
+});
+```
+
+Note how the inner mount behaves reactively as well, automatically unmounting when it's parent observer scope re-runs.

package/skill/multiMap.md

@@ -0,0 +1,15 @@
+## multiMap · function
+
+When using an array as `source`.
+
+**Signature:** `{ <IN, OUT extends { [key: string | symbol]: any; }>(source: IN[], func: (value: IN, index: number) => OUT): OUT; <K extends string | number | symbol, IN, OUT extends { [key: string | symbol]: any; }>(source: Record<...>, func: (value: IN, index: KeyToString<...>) => OUT): OUT; <K, IN, OUT extends { [key: string | s...`
+
+**Type Parameters:**
+
+- `IN`
+- `OUT extends { [key: string | symbol]: any }`
+
+**Parameters:**
+
+- `source: Array<IN>`
+- `func: (value: IN, index: number) => OUT | undefined`

package/skill/onEach.md

@@ -0,0 +1,14 @@
+## onEach · function
+
+**Signature:** `{ <K, T>(target: Map<K, T>, render: (value: T, key: K) => void, makeKey?: (value: T, key: K) => SortKeyType): void; <T>(target: Set<T>, render: (value: T) => void, makeKey?: (value: T) => SortKeyType): void; <T>(target: readonly T[], render: (value: T, index: number) => void, makeKey?: (value: T, index: number) => S...`
+
+**Type Parameters:**
+
+- `K`
+- `T`
+
+**Parameters:**
+
+- `target: Map<K, undefined | T>`
+- `render: (value: T, key: K) => void`
+- `makeKey?: (value: T, key: K) => SortKeyType`

package/skill/partition.md

@@ -0,0 +1,15 @@
+## partition · function
+
+When using an object as `array`.
+
+**Signature:** `{ <OUT_K extends string | number | symbol, IN_V>(source: IN_V[], func: (value: IN_V, key: number) => OUT_K | OUT_K[]): Record<OUT_K, Record<number, IN_V>>; <IN_K extends string | number | symbol, OUT_K extends string | number | symbol, IN_V>(source: Record<...>, func: (value: IN_V, key: IN_K) => OUT_K | OUT_K[]): Re...`
+
+**Type Parameters:**
+
+- `OUT_K extends string | number | symbol`
+- `IN_V`
+
+**Parameters:**
+
+- `source: IN_V[]`
+- `func: (value: IN_V, key: number) => undefined | OUT_K | OUT_K[]`

package/skill/peek.md

@@ -0,0 +1,36 @@
+## peek · function
+
+Executes a function or retrieves a value *without* creating subscriptions in the current reactive scope, and returns its result.
+
+This is useful when you need to access reactive data inside a reactive scope (like | A)
+but do not want changes to that specific data to trigger a re-execute of the scope.
+
+Note: You may also use `unproxy` to get to the raw underlying data structure, which can be used to similar effect.
+
+**Signature:** `{ <T extends object, K extends keyof T>(target: T, key: K): T[K]; <K, V>(target: Map<K, V>, key: K): V; <T>(target: T[], key: number): T; <T>(target: () => T): T; }`
+
+**Type Parameters:**
+
+- `T extends object`
+- `K extends keyof T`
+
+**Parameters:**
+
+- `target: T` - - Either a function to execute, or an object (which may also be an Array or a Map) to index.
+- `key: K` - - Optional key/index to use when `target` is an object.
+
+**Returns:** The result of the function call, or the value at `target[key]` when `target` is an object or `target.get(key)` when it's a Map.
+
+**Examples:**
+
+Peeking within observer
+```typescript
+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.`);
+});
+$data.b = 3; // Does not trigger console.log
+$data.a = 2; // Triggers console.log (logs "A is 2, B was 3 when A changed.")
+```

package/skill/persistScroll.md

@@ -0,0 +1,13 @@
+## persistScroll · function
+
+Restore and store the vertical and horizontal scroll position for
+the parent element to the page state.
+
+**Signature:** `(name?: string) => void`
+
+**Parameters:**
+
+- `name: any` (optional) - - A unique (within this page) name for this
+scrollable element. Defaults to 'main'.
+
+The scroll position will be persisted in `route.aux.scroll.<name>`.

package/skill/proxy.md

@@ -0,0 +1,11 @@
+## proxy · function
+
+**Signature:** `{ <T extends unknown>(target: Promise<T>): PromiseProxy<T>; <T extends unknown>(target: T[]): (T extends number ? number : T extends string ? string : T extends boolean ? boolean : T)[]; <T extends object>(target: T): T; <T extends unknown>(target: T): ValueRef<...>; }`
+
+**Type Parameters:**
+
+- `T extends any`
+
+**Parameters:**
+
+- `target: Promise<T>`

package/skill/push.md

@@ -0,0 +1,13 @@
+## push · function
+
+Modify the current route by merging `target` into it (using | A.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.
+
+**Signature:** `(target: RouteTarget, nav?: NavType) => void`
+
+**Parameters:**
+
+- `target: RouteTarget` - Same as for `go`, but merged into the current route instead deleting all state.
+- `nav?: NavType` - The navigation type to use. Defaults to `undefined`, meaning the navigation type is unchanged from the current route,
+preventing unwanted page transition animations.

package/skill/ref.md

@@ -0,0 +1,39 @@
+## ref · function
+
+Creates a reactive reference (`{ value: T }`-like object) to a specific value
+within a proxied object or array.
+
+This is primarily used for the `bind` property in | A to create two-way data bindings
+with form elements, and for passing a reactive property to any of the | A key-value pairs.
+
+Reading `ref.value` accesses the property from the underlying proxy (and subscribes the current scope).
+Assigning to `ref.value` updates the property in the underlying proxy (triggering reactive updates).
+
+**Signature:** `<T extends TargetType, K extends keyof T>(target: T, index: K) => ValueRef<T[K]>`
+
+**Type Parameters:**
+
+- `T extends TargetType`
+- `K extends keyof T`
+
+**Parameters:**
+
+- `target: T` - - The reactive proxy (created by `proxy`) containing the target property.
+- `index: K` - - The key (for objects) or index (for arrays) of the property to reference.
+
+**Returns:** A reference object with a `value` property linked to the specified proxy property.
+
+**Examples:**
+
+```javascript
+const $formData = A.proxy({ color: 'orange', velocity: 42 });
+
+// Usage with `bind`
+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'));
+
+// Changes are actually stored in $formData - this causes logs like `{color: "Blue", velocity 42}`
+A(() => console.log($formData))
+```

package/skill/runQueue.md

@@ -0,0 +1,34 @@
+## runQueue · function
+
+Forces the immediate and synchronous execution of all pending reactive updates.
+
+Normally, changes to observed data sources (like proxied objects or arrays)
+are processed asynchronously in a batch after a brief timeout (0ms). This function
+allows you to bypass the timeout and process the update queue immediately.
+
+This can be useful in specific scenarios where you need the DOM to be updated
+synchronously.
+
+This function is re-entrant, meaning it is safe to call `runQueue` from within
+a function that is itself being executed as part of an update cycle triggered
+by a previous (or the same) `runQueue` call.
+
+**Signature:** `() => void`
+
+**Examples:**
+
+```typescript
+const $data = A.proxy("before");
+
+A('#', $data);
+console.log(1, document.body.innerHTML); // before
+
+// Make an update that should cause the DOM to change.
+$data.value = "after";
+
+// Normally, the DOM update would happen after a timeout.
+// But this causes an immediate update:
+A.runQueue();
+
+console.log(2, document.body.innerHTML); // after
+```

package/skill/setErrorHandler.md

@@ -0,0 +1,48 @@
+## setErrorHandler · function
+
+Sets a custom error handler function for errors that occur asynchronously
+within reactive scopes (e.g., during updates triggered by proxy changes in
+`derive` or | A render functions).
+
+The default handler logs the error to `console.error` and adds a simple
+'Error' message div to the DOM at the location where the error occurred (if possible).
+
+Your handler can provide custom logging, UI feedback, or suppress the default
+error message.
+
+**Signature:** `(handler?: (error: Error) => boolean) => void`
+
+**Parameters:**
+
+- `handler?: (error: Error) => boolean | undefined` - - A function that accepts the `Error` object.
+- Return `false` to prevent adding an error message to the DOM.
+- Return `true` or `undefined` (or throw) to allow the error messages to be added to the DOM.
+
+**Examples:**
+
+Custom Logging and Suppressing Default Message
+```typescript
+A.setErrorHandler(error => {
+console.warn('Aberdeen render error:', error.message);
+// Log to error reporting service
+// myErrorReporter.log(error);
+
+try {
+// Attempt to show a custom message in the UI
+A('div#Oops, something went wrong!', errorClass);
+} catch (e) {
+// Ignore errors during error handling itself
+}
+
+return false; // Suppress default console log and DOM error message
+});
+
+// Styling for our custom error message
+const errorClass = A.insertCss('background-color:#e31f00 display:inline-block color:white r:3px padding: 2px 4px;');
+
+// Cause an error within a render scope.
+A('div.box', () => {
+// Will cause our error handler to insert an error message within the box
+noSuchFunction();
+})
+```

package/skill/setLog.md

@@ -0,0 +1,9 @@
+## setLog · function
+
+Configure logging on route changes.
+
+**Signature:** `(value: boolean | ((...args: any[]) => void)) => void`
+
+**Parameters:**
+
+- `value: boolean | ((...args: any[]) => void)` - `true` to enable logging to console, `false` to disable logging, or a custom logging function. Defaults to `false`.

package/skill/setSpacingCssVars.md

@@ -0,0 +1,31 @@
+## setSpacingCssVars · function
+
+Initializes `cssVars[0]` 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`.
+
+**Signature:** `(base?: number, unit?: string) => void`
+
+**Parameters:**
+
+- `base: any` (optional) - - The base size for the spacing scale that will apply to `cssVars[3]`. Every step up the scale will double this, while every step down will halve it. Defaults to 1.
+- `unit: any` (optional) - - The CSS unit to use, like 'rem', 'em', or 'px'. Defaults to 'rem'.
+
+**Examples:**
+
+```javascript
+import A from 'aberdeen';
+// Use default scale (0.25rem to 512rem)
+A.setSpacingCssVars();
+
+// Use custom base size
+A.setSpacingCssVars(16, 'px'); // 4px to 8192px
+
+// Use em units
+A.setSpacingCssVars(1, 'em'); // 0.25em to 512em
+
+// Show the last generated spacing values
+A.onEach(A.cssVars, (value, key) => {
+	A(`div #${key} → ${value}`)
+}, (value, key) => parseInt(key)); // Numeric sort
+```

package/skill/shrink.md

@@ -0,0 +1,13 @@
+## shrink · function
+
+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.
+
+**Signature:** `(el: HTMLElement) => Promise<void>`
+
+**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.

package/skill/unmountAll.md

@@ -0,0 +1,9 @@
+## unmountAll · function
+
+Removes all Aberdeen-managed DOM nodes and stops all active reactive scopes
+(created by `mount`, `derive`, | A with functions, etc.).
+
+This effectively cleans up the entire Aberdeen application state. Aside from in
+automated tests, there should probably be little reason to call this function.
+
+**Signature:** `() => void`

package/skill/unproxy.md

@@ -0,0 +1,43 @@
+## unproxy · function
+
+Returns the original, underlying data target from a reactive proxy created by `proxy`.
+If the input `target` is not a proxy, it is returned directly.
+
+This is useful when you want to avoid triggering subscriptions during read operations or
+re-executes during write operations. Using `peek` is an alternative way to achieve this.
+
+**Signature:** `<T>(target: T) => T`
+
+**Type Parameters:**
+
+- `T` - The type of the target.
+
+**Parameters:**
+
+- `target: T` - - A proxied object, array, or any other value.
+
+**Returns:** The underlying (unproxied) data, or the input value if it wasn't a proxy.
+
+**Examples:**
+
+```typescript
+const $user = A.proxy({ name: 'Frank' });
+const rawUser = A.unproxy($user);
+
+// Log reactively
+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(() => $user.name += '!', 1000);
+
+// This doesn't cause any new logs:
+setTimeout(() => rawUser.name += '?', 2000);
+
+// Both $user and rawUser end up as `{name: 'Frank!?'}`
+setTimeout(() => {
+  console.log('final proxied', $user)
+  console.log('final unproxied', rawUser)
+}, 3000);
+```

package/skill/up.md

@@ -0,0 +1,13 @@
+## up · function
+
+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.
+
+**Signature:** `(stripCount?: number) => void`
+
+**Parameters:**
+
+- `stripCount: number` (optional)