aberdeen 1.18.2 → 1.19.0

package/skill/darkMode.md

@@ -0,0 +1,26 @@
+## darkMode · function
+
+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 | A and `cssVars` to implement theme switching:
+
+**Signature:** `() => boolean`
+
+**Returns:** `true` if the browser prefers dark mode, `false` if it prefers light mode.
+
+**Examples:**
+
+```javascript
+import A from 'aberdeen';
+
+// Reactively set colors based on browser preference
+A(() => {
+  A.cssVars.bg = A.darkMode() ? '#1a1a1a' : '#ffffff';
+  A.cssVars.fg = A.darkMode() ? '#e5e5e5' : '#000000';
+});
+
+A('div bg:$bg fg:$fg p:1rem #Colors change based on system dark mode preference');
+```

package/skill/derive.md

@@ -0,0 +1,56 @@
+## derive · function
+
+Creates a reactive scope that automatically re-executes the provided function
+whenever any proxied data (created by `proxy`) read during its last execution changes, storing
+its return value in an observable.
+
+Updates are batched and run asynchronously shortly after the changes occur.
+Use `clean` to register cleanup logic for the scope.
+Use `peek` or `unproxy` within the function to read proxied data without subscribing to it.
+
+**Signature:** `<T>(func: () => T) => ValueRef<T>`
+
+**Type Parameters:**
+
+- `T`
+
+**Parameters:**
+
+- `func: () => T` - - The function to execute reactively. Any DOM manipulations should typically
+be done using | A within this function. Its return value will be made available as an
+observable returned by the `derive()` function.
+
+**Returns:** An observable object, with its `value` property containing whatever the last run of `func` returned.
+
+**Examples:**
+
+Observation creating UI components
+```typescript
+const $data = A.proxy({ user: 'Frank', notifications: 42 });
+
+A('main', () => {
+console.log('Welcome');
+A('h3#Welcome, ' + $data.user); // Reactive text
+
+A.derive(() => {
+// When $data.notifications changes, only this inner scope reruns,
+// leaving the `<p>Welcome, ..</p>` untouched.
+console.log('Notifications');
+A('code.notification-badge text=', $data.notifications);
+A('a text=Notify! click=', () => $data.notifications++);
+});
+});
+```
+
+***Note*** that the above could just as easily be done using `A(func)` instead of `derive(func)`.
+
+Observation with return value
+```typescript
+const $counter = A.proxy(0);
+setInterval(() => $counter.value++, 1000);
+const $double = A.derive(() => $counter.value * 2);
+
+A('h3', () => {
+A(`#counter=${$counter.value} double=${$double.value}`);
+})
+```

package/skill/developer-tools.md

@@ -0,0 +1,23 @@
+## Developer tools
+
+Aberdeen has an in-browser inspector for its reactive scope tree. The live examples on this page support it. **Click inside an example's 'Browser' tab to focus it, then press `Ctrl/Cmd+Alt+A`** to open the tools (press again to close). Try it with this one:
+
+```typescript
+import A from 'aberdeen';
+
+const $state = A.proxy({fruits: ['apple', 'banana']});
+
+A('button text="Add cherry" click=', () => $state.fruits.push('cherry'));
+A('ul', () => {
+    A.onEach($state.fruits, fruit => A('li text=', fruit));
+});
+```
+
+A panel opens with two columns. The **left** is the live scope tree — every reactive block (the `<ul>`'s render function, the `onEach`, each of its items, ...), colour-coded by type and labelled with the `file:line` where it was created. The **right** shows details for the selected scope: its DOM nodes and child scopes, what it's observing, where it was created, and which change last triggered it to re-run.
+
+To use it:
+- **Click a scope** in the tree to select it. Its container element (which may contain more than one scope) is outlined in orange, the top-level elements it created in green.
+- **Hold `Alt` and hover** any element to select the scope that drew it.
+- Hit **Add cherry** and switch to the **Recent** tab to watch the re-render stream in, or toggle **Freeze** to pause re-renders while you look around.
+
+This is a development-only aid and is stripped from production builds. By default it's part of Aberdeen's **development** build, which bundlers like Vite select automatically in dev mode (via the `development` export condition) while production builds get the bare core. If you'd rather not rely on bundler settings, `import A from 'aberdeen/tooled'` to *always* include the dev tools, or `aberdeen/untooled` to *always* leave them out. Both expose the exact same API as `aberdeen`.

package/skill/disableCreateDestroy.md

@@ -0,0 +1,11 @@
+## disableCreateDestroy · function
+
+Make the `create` and `destroy` special properties no-ops.
+
+This is useful from within automated testing environments, where the transitioning
+new and lingering old elements may make writing reliable selectors difficult.
+
+As this is only intended for testing, there's no way to re-enable the special properties
+once disabled.
+
+**Signature:** `() => void`

package/skill/dump.md

@@ -0,0 +1,37 @@
+## dump · function
+
+Renders a live, recursive dump of a proxied data structure (or any value)
+into the DOM at the current | A insertion point.
+
+Uses `<ul>` and `<li>` elements to display object properties and array items.
+Updates reactively if the dumped data changes. Primarily intended for debugging purposes.
+
+**Signature:** `<T>(data: T) => T`
+
+**Type Parameters:**
+
+- `T` - The type of the data being dumped.
+
+**Parameters:**
+
+- `data: T` - - The proxied data structure (or any value) to display.
+
+**Returns:** The original `data` argument, allowing for chaining.
+
+**Examples:**
+
+Dumping reactive state
+```typescript
+import A from 'aberdeen';
+
+const $state = A.proxy({
+user: { name: 'Frank', kids: 1 },
+items: ['a', 'b']
+});
+
+A('h2#Live State Dump');
+A.dump($state);
+
+// Change state later, the dump in the DOM will update
+setTimeout(() => { $state.user.kids++; $state.items.push('c'); }, 2000);
+```

package/skill/freeze.md

@@ -0,0 +1,20 @@
+## freeze · function
+
+Pause processing of reactive updates until the returned *thaw* function is called.
+
+While frozen, changes to observed data still accumulate, but no re-renders run. Freezes
+stack: if there are multiple outstanding freezes, redraws resume only once the last one is
+thawed. This is useful to batch an async burst of changes into a single update pass, or to
+hold the UI steady (e.g. the dev tools use it for "freeze redraws").
+
+**Signature:** `() => () => void`
+
+**Returns:** A function that releases this freeze. Calling it more than once has no effect.
+
+**Examples:**
+
+```typescript
+const thaw = A.freeze();
+// ...make many changes without intermediate redraws...
+thaw(); // redraws run now (if no other freezes remain)
+```

package/skill/full-example-multi-page-app.md

@@ -0,0 +1,146 @@
+## Full Example: Multi-page App
+
+Here's a complete example (a contact manager) demonstrating routing, state management, CSS, dark mode, and dynamic content:
+
+```typescript
+import A from 'aberdeen';
+import * as route from 'aberdeen/route';
+import { Dispatcher } from 'aberdeen/dispatcher';
+import { grow, shrink } from 'aberdeen/transitions';
+
+class Contact {
+    constructor(
+        public id: number,
+        public firstName: string,
+        public lastName: string,
+        public email: string,
+        public phone: string
+    ) {}
+}
+
+// Enable link interception for SPA navigation
+route.interceptLinks();
+
+// Initialize $1-$12 CSS variables for consistent spacing ($2=0.5rem, $3=1rem, $4=2rem, etc.)
+A.setSpacingCssVars();
+
+// Reactive theme based on system preference
+A(() => {
+    A.cssVars.primary = '#2563eb';
+    A.cssVars.bg = A.darkMode() ? '#0f172a' : '#ffffff';
+    A.cssVars.fg = A.darkMode() ? '#e2e8f0' : '#1e293b';
+    A.cssVars.cardBg = A.darkMode() ? '#1e293b' : '#f8fafc';
+    A.cssVars.border = A.darkMode() ? '#334155' : '#e2e8f0';
+});
+
+// Global styles for semantic HTML elements that apply everywhere
+A.insertGlobalCss({
+    "*": "m:0 p:0",
+    "body": "bg:$bg fg:$fg font-family: system-ui, sans-serif;",
+    "a": "color:$primary text-decoration:none",
+    "a:hover": "text-decoration:underline",
+    "a[role=button]": "bg:$primary fg:white r:8px p:$2",
+});
+
+// Application state
+const $contacts = A.proxy([
+    new Contact(1, 'Emma', 'Wilson', 'emma.wilson@email.com', '555-0101'),
+    new Contact(2, 'James', 'Anderson', 'j.anderson@email.com', '555-0102'),
+    new Contact(3, 'Sofia', 'Martinez', 'sofia.m@email.com', '555-0103'),
+    new Contact(4, 'Liam', 'Brown', 'liam.brown@email.com', '555-0104')
+]);
+
+// Router setup
+const dispatcher = new Dispatcher();
+dispatcher.addRoute(drawHome);
+dispatcher.addRoute('contacts', drawContactList);
+dispatcher.addRoute('contacts', Number, drawContactDetail);
+
+// Main app
+A('div.app', () => {
+    A('nav display:flex gap:$3 p:$3 border-bottom: 1px solid $border;', () => {
+        A('a href=/ text=Home font-weight:', route.current.p.length === 0 ? 'bold' : 'normal');
+        A('a href=/contacts text=Contacts font-weight:', route.current.p[0] === 'contacts' ? 'bold' : 'normal');
+    });
+    A('main p:$3', () => dispatcher.dispatch(route.current.p));
+});
+
+function drawHome() {
+    A('h1#Contact Manager');
+    A('p#A modern contact list with search, sort, and dark mode support.');
+}
+
+// Contact card styles
+const cardStyle = A.insertCss({
+    "&": "bg:$cardBg border: 1px solid $border; r:8px p:$3 mv:$2 display:block transition: transform 0.2s;",
+    "&:hover": "transform:translateX(4px)",
+    "a&": "color:inherit;",
+});
+
+const filterStyle = A.insertCss({
+    "&": "display:flex gap:$3 mv:$3",
+    "> *": "p:$2 r:4px bg:$bg fg:$fg border: 1px solid $border;",
+});
+
+function drawContactList() {
+    A('h1#Contacts');
+    
+    // Search and sort controls
+    A('div', filterStyle, () => {
+        A('input flex:1 placeholder="Search contacts..." bind=', A.ref(route.current.search, 'q'));
+        A('select bind=', A.ref(route.current.search, 'sort'), () => {
+            A('option value=firstName #First Name');
+            A('option value=lastName #Last Name');
+            A('option value=email #Email');
+        });
+    });
+    
+    // Contact list
+    A('div', () => {
+        const sortBy = route.current.search.sort || 'firstName';
+
+        const $filtered = A.map($contacts, $contact => {
+            const query = route.current.search.q;
+            if (query) {
+                const info = `${$contact.firstName} ${$contact.lastName} ${$contact.email}`;
+                if (!info.toLowerCase().includes(query.toLowerCase())) return; // Skip!
+            }
+            return $contact;
+        });
+        
+        A.onEach($filtered, $contact => {
+            A('a', cardStyle, 'create=', grow, 'destroy=', shrink, `href=/contacts/${$contact.id}`, () => {
+                A('h2', () => {
+                    A('span font-weight:normal text=', $contact.firstName+" ");
+                    A('span text=', $contact.lastName);
+                });
+                A('div text=', $contact.email);
+            });
+        }, $contact => $contact[sortBy].toLowerCase());
+
+        A(`a role=button mt:$3 text="Add new contact" href=/contacts/${$contacts.length}`);
+    });
+}
+
+// Detail form styles
+const detailStyle = A.insertCss({
+    "&": "bg:$cardBg border: 1px solid $border; r:8px p:$4 max-width:600px",
+    "label": "display:block font-weight:600 mt:$3 mb:$2",
+    "input": "w:100% p:$2 r:4px border: 1px solid $border; bg:$bg fg:$fg"
+});
+
+function drawContactDetail(id: number) {
+    $contacts[id] ||= new Contact(id, '', '', '', '');
+    const $contact = $contacts[id];
+    
+    A('a role=button href=/contacts #← Back');
+    
+    A('div mt:$3', detailStyle, () => {
+        A('h2 mb:$2 text=', A.ref($contact, 'firstName'), 'text=', ' ', 'text=', A.ref($contact, 'lastName'));
+        A('label text="First Name" input bind=', A.ref($contact, 'firstName'));
+        A('label text="Last Name" input bind=', A.ref($contact, 'lastName'));
+        A('label text="Email" input type=email bind=', A.ref($contact, 'email'));     
+        A('label text="Phone" input type=tel bind=', A.ref($contact, 'phone'));
+    });
+}
+```

package/skill/go.md

@@ -0,0 +1,25 @@
+## go · function
+
+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.
+
+**Signature:** `(target: RouteTarget, nav?: NavType) => void`
+
+**Parameters:**
+
+- `target: RouteTarget` - A subset of the `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` (optional)

package/skill/grow.md

@@ -0,0 +1,13 @@
+## grow · function
+
+Do a grow transition for the given element. This is meant to be used as a
+handler for the `create` property.
+
+**Signature:** `(el: HTMLElement) => Promise<void>`
+
+**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.

package/skill/html-to-aberdeen.md

@@ -0,0 +1,9 @@
+## html-to-aberdeen
+
+This tool allows you to convert a block of HTML into Aberdeen syntax. 
+
+```sh
+npx html-to-aberdeen
+```
+
+It takes HTML on stdin (paste it and press `ctrl-d` for end-of-file), and outputs JavaScript on stdout.

package/skill/insertCss.md

@@ -0,0 +1,79 @@
+## insertCss · function
+
+Inserts CSS rules into the document, scoping them with a unique class name.
+
+The `style` parameter can be either:
+- A **concise style string** (for rules applying to the root class).
+- An **object** where keys are selectors (with `&` representing the root class) 
+  and values are concise style strings or nested objects. When the key does not contain `&`,
+  it is treated as a descendant selector. So `{p: "color:red"}` becomes `".AbdStlX p { color: red; }"` with `AbdStlX` being the generated class name.
+
+### Concise Style Strings
+
+Concise style strings use two syntaxes (same as inline CSS in | A):
+- **Short form** `key:value` (no space after colon): The value ends at the next whitespace.
+  Example: `'m:$3 bg:red r:8px'`
+- **Long form** `key: value;` (space after colon): The value continues until a semicolon.
+  Example: `'box-shadow: 2px 0 6px black; transition: all 0.3s ease;'`
+
+Both forms can be mixed: `'m:$3 box-shadow: 0 2px 4px rgba(0,0,0,0.2); bg:$cardBg'`
+
+Supports the same CSS shortcuts as | A and CSS variable references with `$` (e.g., `$primary`, `$3`).
+
+CSS is inserted into the <head> in an order relative to other insert(Global)Css items that is consistent
+based on when the containing Aberdeen scope was first defined. This allows changing styles without changing
+order-based precedence.
+
+**Signature:** `(style: string | object) => string`
+
+**Parameters:**
+
+- `style: string | object` - - A concise style string or a style object.
+
+**Returns:** The unique class name prefix used for scoping (e.g., `.AbdStl1`). 
+Use this prefix with | A to apply the styles.
+
+**Examples:**
+
+Basic Usage with Shortcuts and CSS Variables
+```typescript
+const cardClass = A.insertCss({
+'&': 'bg:white p:$4 r:8px transition: background-color 0.3s;',
+'&:hover': 'bg:#f5f5f5',
+});
+
+A('section', cardClass, () => { 
+A('p#Card content'); 
+});
+```
+
+Nested Selectors and Media Queries
+```typescript
+const formClass = A.insertCss({
+'&': 'bg:#0004 p:$3 r:$2',
+button: {
+'&': 'bg:$primary fg:white p:$2 r:4px cursor:pointer',
+'&:hover': 'bg:$primaryHover',
+'&:disabled': 'bg:#ccc cursor:not-allowed',
+'.icon': 'display:inline-block mr:$1',
+'@media (max-width: 600px)': 'p:$1 font-size:14px'
+}
+});
+
+A('form', formClass, () => {
+A('button', () => {
+A('span.icon text=🔥');
+A('#Click Me');
+});
+});
+```
+
+Complex CSS Values
+```typescript
+const badge = A.insertCss({
+'&::before': 'content: "★"; color:gold mr:$1',
+'&': 'position:relative box-shadow: 0 2px 8px rgba(0,0,0,0.15);'
+});
+
+A(badge + ' span#Product Name');
+```

package/skill/insertGlobalCss.md

@@ -0,0 +1,68 @@
+## insertGlobalCss · function
+
+Inserts CSS rules globally (unscoped).
+
+Works exactly like `insertCss`, but without prefixing selectors with a unique class name.
+This is useful for global resets, base styles, or styles that need to apply to the entire document.
+
+Accepts the same concise style string syntax and CSS shortcuts as `insertCss`.
+See `insertCss` for detailed documentation on syntax and shortcuts.
+
+**Signature:** `(style: object) => void`
+
+**Parameters:**
+
+- `style: object` - - Object with selectors as keys and concise CSS strings as values.
+
+CSS is inserted into the <head> in an order relative to other insert(Global)Css items that is consistent
+based on when the containing Aberdeen scope was first defined. This allows changing styles without changing
+order-based precedence.
+
+**Examples:**
+
+Global Reset and Base Styles
+```typescript
+// Set up global styles using CSS shortcuts
+A.insertGlobalCss({
+"*": "m:0 p:0 box-sizing:border-box",
+"body": "font-family: system-ui, sans-serif; m:0 p:$3 bg:#434 fg:#d0dafa",
+"a": "text-decoration:none fg:#57f",
+"a:hover": "text-decoration:underline",
+"code": "font-family:monospace bg:#222 fg:#afc p:4px r:3px"
+});
+
+A('h2#Title without margins');
+A('a#This is a link');
+A('code#const x = 42;');
+```
+
+Responsive Global Styles
+```typescript
+A.insertGlobalCss({
+"html": "font-size:16px",
+"body": "line-height:1.6",
+"h1, h2, h3": "font-weight:600 mt:$4 mb:$2",
+"@media (max-width: 768px)": {
+"html": "font-size:14px",
+"body": "p:$2"
+},
+"@media (prefers-color-scheme: dark)": {
+"body": "bg:#1a1a1a fg:#e5e5e5",
+"code": "bg:#2a2a2a"
+}
+});
+```
+At-rules such as `@media` and `@keyframes` should use nested objects. For keyframes,
+the step selectors (`0%`, `50%`, `100%`, etc.) become the nested keys and each value
+should be a concise CSS declaration string.
+
+Animation Keyframes
+```typescript
+A.insertGlobalCss({
+"@keyframes connection-pulse": {
+"0%": "box-shadow: inset 0 0 0 0 rgba(255, 70, 70, 0.4);",
+"50%": "box-shadow: inset 0 0 0 6px rgba(255, 70, 70, 0.08);",
+"100%": "box-shadow: inset 0 0 0 0 rgba(255, 70, 70, 0.4);"
+}
+});
+```

package/skill/interceptLinks.md

@@ -0,0 +1,19 @@
+## interceptLinks · function
+
+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).
+
+This allows you to use regular HTML anchor tags for navigation without needing to
+manually attach click handlers to each link.
+
+**Signature:** `() => void`
+
+**Examples:**
+
+```js
+// In your root component:
+route.interceptLinks();
+
+// Now you can use regular anchor tags:
+A('a text=About href=/corporate/about');
+```

package/skill/invertString.md

@@ -0,0 +1,32 @@
+## invertString · function
+
+Creates a new string that has the opposite sort order compared to the input string.
+
+This is achieved by flipping the bits of each character code in the input string.
+The resulting string is intended for use as a sort key, particularly with the
+`makeKey` function in `onEach`, to achieve a descending sort order.
+
+**Warning:** The output string will likely contain non-printable characters or
+appear as gibberish and should not be displayed to the user.
+
+**Signature:** `(input: string) => string`
+
+**Parameters:**
+
+- `input: string` - The string whose sort order needs to be inverted.
+
+**Returns:** A new string that will sort in the reverse order of the input string.
+
+**Examples:**
+
+```typescript
+const $users = A.proxy([
+    { id: 1, name: 'Charlie', score: 95 },
+    { id: 2, name: 'Alice', score: 100 },
+    { id: 3, name: 'Bob', score: 90 },
+]);
+
+A.onEach($users, ($user) => {
+    A(`p#${$user.name}: ${$user.score}`);
+}, ($user) => A.invertString($user.name)); // Reverse alphabetic order
+```

package/skill/isEmpty.md

@@ -0,0 +1,38 @@
+## isEmpty · function
+
+Reactively checks if an observable array, object, Map, or Set is empty.
+
+This function not only returns the current emptiness state but also establishes
+a reactive dependency. If the emptiness state of the `proxied` object or array
+changes later (e.g., an item is added to an empty array, or the last property
+is deleted from an object), the scope that called `isEmpty` will be automatically
+scheduled for re-evaluation.
+
+**Signature:** `(proxied: TargetType) => boolean`
+
+**Parameters:**
+
+- `proxied: TargetType` - The observable array, object, Map, or Set to check.
+
+**Returns:** `true` if the array has length 0, the Map/Set has size 0, or the object has no own enumerable properties, `false` otherwise.
+
+**Examples:**
+
+```typescript
+const $items = A.proxy([]);
+
+// Reactively display a message if the items array is empty
+A('div', () => {
+    if (A.isEmpty($items)) {
+        A('p i#No items yet!');
+    } else {
+        A.onEach($items, item => A('p#'+item));
+    }
+});
+
+// Adding an item will automatically remove the "No items yet!" message
+setInterval(() => {
+  if (!$items.length || Math.random()>0.5) $items.push('Item');
+  else $items.length = 0;
+}, 1000)
+```

package/skill/map.md

@@ -0,0 +1,16 @@
+## map · function
+
+When using a Map as `source`.
+
+**Signature:** `{ <K, IN, OUT>(source: Map<K, IN>, func: (value: IN, key: K) => OUT): Map<K, OUT>; <IN, OUT>(source: IN[], func: (value: IN, index: number) => OUT): OUT[]; <IN, const IN_KEY extends string | number | symbol, OUT>(source: Record<...>, func: (value: IN, index: KeyToString<...>) => OUT): Record<...>; }`
+
+**Type Parameters:**
+
+- `K`
+- `IN`
+- `OUT`
+
+**Parameters:**
+
+- `source: Map<K, IN>`
+- `func: (value: IN, key: K) => undefined | OUT`

package/skill/matchCurrent.md

@@ -0,0 +1,27 @@
+## matchCurrent · function
+
+Returns `true` if the current route matches `target`.
+
+Path must match exactly. Any search params specified in `target` must be present
+in the current URL, but extra params in the current URL are allowed.
+
+Reactive: only reevaluates when the path changes to/from the target path, and
+when target k/v search pairs are (un)set.
+
+Primary usage: 'active' status for menu items.
+
+**Signature:** `(target: RouteTarget) => boolean`
+
+**Parameters:**
+
+- `target: RouteTarget`
+
+**Examples:**
+
+```js
+// This example assumes interceptLinks() has been called
+A('a.my-button text=Users href=/users .is-active=', route.matchCurrent('/users'));
+
+// Alternatively a route object can be given
+route.matchCurrent({path: '/users', search: {tab: 'profile'}});
+```