npm - aberdeen - Versions diffs - 1.5.0 → 1.6.0 - Mend

aberdeen 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/dist/aberdeen.d.ts +71 -9
package/dist/aberdeen.js +47 -24
package/dist/aberdeen.js.map +3 -3
package/dist/route.js +4 -4
package/dist/route.js.map +3 -3
package/dist-min/aberdeen.js +7 -7
package/dist-min/aberdeen.js.map +3 -3
package/dist-min/route.js.map +2 -2
package/package.json +5 -2
package/skill/SKILL.md +579 -204
package/skill/aberdeen.md +2322 -0
package/skill/dispatcher.md +126 -0
package/skill/prediction.md +73 -0
package/skill/route.md +249 -0
package/skill/transitions.md +59 -0
package/src/aberdeen.ts +121 -35
package/src/route.ts +3 -3
package/skill/references/prediction.md +0 -45
package/skill/references/routing.md +0 -81
package/skill/references/transitions.md +0 -52

package/src/aberdeen.ts CHANGED Viewed

@@ -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,26 +1704,62 @@ export const NO_COPY = Symbol("NO_COPY");
 (Promise.prototype as any)[NO_COPY] = true;
 /**
- * CSS variables that are output as native CSS custom properties.
- *
- * When a CSS value starts with `@`, it becomes `var(--name)` (or `var(--mN)` for numeric keys).
- * Pre-initialized with keys '1'-'12' mapping to an exponential rem scale (e.g., @1=0.25rem, @3=1rem).
- *
- * Changes to cssVars are automatically reflected in a `<style>` tag in `<head>`, making updates
- * reactive across all elements using those variables.
- *
+ * 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 var(--primary)
- * $('div mt:@3'); // Sets margin-top to var(--m3)
+ * 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/;
@@ -1733,6 +1769,72 @@ function cssVarRef(name: string): string {
 	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;
+}
 /**
  * Clone an (optionally proxied) object or array.
  *
@@ -2188,7 +2290,7 @@ function styleToCss(style: object, prefix: string): string {
 					);
 				}
 			} else {
-				const val = v == null || v === false ? "" : typeof v === 'string' ? (v[0] === '@' ? cssVarRef(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};`;
@@ -2217,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] === '@' ? cssVarRef(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;
@@ -2914,20 +3016,4 @@ export function withEmitHandler(
 	}
 }
-// Initialize the cssVars style tag in document.head
-// This runs at module load time, after all functions are defined
-if (typeof document !== "undefined") {
-	leakScope(() => {
-		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}`);
-			})
-		});
-	});
-}

package/src/route.ts CHANGED Viewed

@@ -170,9 +170,9 @@ export function go(target: RouteTarget, nav: NavType = "go"): void {
  * @param target Same as for {@link go}, but merged into the current route instead deleting all state.
  */
 export function push(target: RouteTarget): void {
-	let copy = clone(unproxy(current));
-	merge(copy, targetToPartial(target));
-	go(copy);
+	const c = clone(unproxy(current));
+	merge(c, targetToPartial(target));
+	go(c);
 }
 /**

package/skill/references/prediction.md DELETED Viewed

@@ -1,45 +0,0 @@
-# Prediction (Optimistic UI)
-Apply UI changes immediately, auto-revert when server responds.
-## API
-```typescript
-import { applyPrediction, applyCanon } from 'aberdeen/prediction';
-```
-### `applyPrediction(func)`
-Runs function and records all proxy changes as a "prediction".
-Returns a `Patch` to use as `dropPatches` later, when the server responds.
-### `applyCanon(func?, dropPatches?)`
-1. Reverts all predictions
-2. Runs `func` (typically applies server data)
-3. Drops specified patches
-4. Re-applies remaining predictions that still apply cleanly
-## Example
-```typescript
-async function toggleTodo(todo: Todo) {
-    // Optimistic update
-    const patch = applyPrediction(() => {
-        todo.done = !todo.done;
-    });
-    try {
-        const data = await api.updateTodo(todo.id, { done: todo.done });
-        // Server responded - apply canonical state
-        applyCanon(() => {
-            Object.assign(todo, data);
-        }, [patch]);
-    } catch {
-        // On error, just drop the prediction to revert
-        applyCanon(undefined, [patch]);
-    }
-}
-```
-## When to Use
-- When you want immediate UI feedback for user actions for which a server is authoritative.
-- As doing this manually for each such case is tedious, this should usually be integrated into the data updating/fetching layer.

package/skill/references/routing.md DELETED Viewed

@@ -1,81 +0,0 @@
-# Routing and Dispatching
-## Router (`aberdeen/route`)
-The `current` object is a reactive proxy of the current URL state.
-### Properties
-| Property | Type | Description |
-|----------|------|-------------|
-| `path` | `string` | Normalized path (e.g., `/users/123`) |
-| `p` | `string[]` | Path segments (e.g., `['users', '123']`) |
-| `search` | `Record<string,string>` | Query parameters |
-| `hash` | `string` | URL hash including `#` |
-| `state` | `Record<string,any>` | JSON-compatible state data |
-| `nav` | `NavType` | How we got here: `load`, `back`, `forward`, `go`, `push` |
-| `depth` | `number` | Navigation stack depth (starts at 1) |
-### Navigation Functions
-```typescript
-import * as route from 'aberdeen/route';
-route.go('/users/42');                    // Navigate to new URL
-route.go({ p: ['users', 42], hash: 'top' }); // Object form
-route.push({ search: { tab: 'feed' } });  // Merge into current route
-route.back();                             // Go back in history
-route.back({ path: '/home' });            // Back to matching entry, or replace
-route.up();                               // Go up one path level
-route.persistScroll();                    // Save/restore scroll position
-```
-### Reactive Routing Example
-```typescript
-import * as route from 'aberdeen/route';
-$(() => {
-    const [section, id] = route.current.p;
-    if (section === 'users') drawUser(id);
-    else if (section === 'settings') drawSettings();
-    else drawHome();
-});
-```
-## Dispatcher (`aberdeen/dispatcher`)
-Type-safe path segment matching for complex routing.
-```typescript
-import { Dispatcher, matchRest } from 'aberdeen/dispatcher';
-import * as route from 'aberdeen/route';
-const d = new Dispatcher();
-// Literal string match
-d.addRoute('home', () => drawHome());
-// Number extraction (uses built-in Number function)
-d.addRoute('user', Number, (id) => drawUser(id));
-// String extraction
-d.addRoute('user', Number, 'post', String, (userId, postId) => {
-    drawPost(userId, postId);
-});
-// Rest of path as array
-d.addRoute('search', matchRest, (terms: string[]) => {
-    performSearch(terms);
-});
-// Dispatch in reactive scope
-$(() => {
-    if (!d.dispatch(route.current.p)) {
-        draw404();
-    }
-});
-```
-### Custom Matchers
-```typescript
-const uuid = (s: string) => /^[0-9a-f-]{36}$/.test(s) ? s : matchFailed;
-d.addRoute('item', uuid, (id) => drawItem(id));
-```

package/skill/references/transitions.md DELETED Viewed

@@ -1,52 +0,0 @@
-# Transitions
-Animate elements entering/leaving the DOM via the `create` and `destroy` properties.
-**Important:** Transitions only trigger for **top-level** elements of a scope being (re-)run. Deeply nested elements drawn as part of a larger redraw do not trigger transitions.
-## Built-in Transitions
-```typescript
-import { grow, shrink } from 'aberdeen/transitions';
-// Apply to individual elements
-$('div create=', grow, 'destroy=', shrink, '#Animated');
-// Common with onEach for list animations
-onEach(items, item => {
-    $('li create=', grow, 'destroy=', shrink, `#${item.text}`);
-});
-```
-- `grow`: Scales element from 0 to full size with margin animation
-- `shrink`: Scales element to 0 and removes from DOM after animation
-Both detect horizontal flex containers and animate width instead of height.
-## CSS-Based Transitions
-For custom transitions, use CSS class strings (dot-separated):
-```typescript
-const fadeStyle = insertCss({
-    transition: 'all 0.3s ease-out',
-    '&.hidden': { opacity: 0, transform: 'translateY(-10px)' }
-});
-// Class added briefly on create (removed after layout)
-// Class added on destroy (element removed after 2s delay)
-$('div', fadeStyle, 'create=.hidden destroy=.hidden#Fading element');
-```
-## Custom Transition Functions
-For full control, pass functions. For `destroy`, your function must remove the element:
-```typescript
-$('div create=', (el: HTMLElement) => {
-    // Animate on mount - element already in DOM
-    el.animate([{ opacity: 0 }, { opacity: 1 }], 300);
-}, 'destroy=', (el: HTMLElement) => {
-    // YOU must remove the element when done
-    el.animate([{ opacity: 1 }, { opacity: 0 }], 300)
-        .finished.then(() => el.remove());
-}, '#Custom animated');
-```