aberdeen 1.4.0 → 1.4.1

package/README.md

@@ -172,7 +172,30 @@ Some further examples:
 
 And you may want to study the examples above, of course!
 
+
+## AI Integration
+
+If you use Claude Code, GitHub Copilot or another AI agents that supports Skills, Aberdeen includes a `skill/` directory that provides specialized knowledge to the AI about how to use the library effectively.
+
+To use this, it is recommended to symlink the skill into your project's `.claude/skills` directory:
+
+```bash
+mkdir -p .claude/skills
+ln -s ../../node_modules/aberdeen/skill .claude/skills/aberdeen
+```
+
+
 ## Changelog
+### 1.4.1 (2026-01-14)
+
+**Additions:**
+- Created an AI agent Skill (Claude Code, GitHub Copilot) for using Aberdeen in your projects.
+
+**Enhancements:**
+- The `html-to-aberdeen` tool now automatically converts `style` attributes to Aberdeen's CSS shortcuts (like `mt:10px` for `margin-top: 10px`) and uses the modern `#text` syntax.
+
+**Fixes:**
+- Fixed an issue in `docs/live-code.js` where it was still trying to import the removed `observe` function.
 
 ### 1.4.0 (2025-01-07)
 

package/html-to-aberdeen

@@ -227,13 +227,77 @@ function convertHTMLToAberdeen(html) {
 }
 
 // Process a node and return Aberdeen code
+const CSS_PROPERTY_TO_SHORTCUT = {
+  'margin': 'm',
+  'margin-top': 'mt',
+  'margin-bottom': 'mb',
+  'margin-left': 'ml',
+  'margin-right': 'mr',
+  'padding': 'p',
+  'padding-top': 'pt',
+  'padding-bottom': 'pb',
+  'padding-left': 'pl',
+  'padding-right': 'pr',
+  'width': 'w',
+  'height': 'h',
+  'background': 'bg',
+  'color': 'fg',
+  'border-radius': 'r',
+};
+
+function kebabToCamel(str) {
+  return str.replace(/-([a-z])/g, (g) => g[1].toUpperCase());
+}
+
+function convertStyleToAberdeen(styleString) {
+  const rules = styleString.split(';').map(s => s.trim()).filter(Boolean);
+  const resultParts = [];
+  
+  const props = {};
+  for (const rule of rules) {
+    const colonIndex = rule.indexOf(':');
+    if (colonIndex === -1) continue;
+    const key = rule.substring(0, colonIndex).trim();
+    const value = rule.substring(colonIndex + 1).trim();
+    props[key] = value;
+  }
+
+  const addPart = (key, value) => {
+    if (value.includes(' ')) {
+      resultParts.push(`${key}:"${value}"`);
+    } else {
+      resultParts.push(`${key}:${value}`);
+    }
+  };
+
+  const handleGroup = (prop1, prop2, shortcut) => {
+    if (props[prop1] && props[prop2] && props[prop1] === props[prop2]) {
+      addPart(shortcut, props[prop1]);
+      delete props[prop1];
+      delete props[prop2];
+    }
+  };
+
+  handleGroup('margin-top', 'margin-bottom', 'mv');
+  handleGroup('margin-left', 'margin-right', 'mh');
+  handleGroup('padding-top', 'padding-bottom', 'pv');
+  handleGroup('padding-left', 'padding-right', 'ph');
+
+  for (const [key, value] of Object.entries(props)) {
+    const shortcut = CSS_PROPERTY_TO_SHORTCUT[key] || kebabToCamel(key);
+    addPart(shortcut, value);
+  }
+
+  return resultParts.join(' ');
+}
+
 function processNode(node, indentLevel = 0) {
   const indent = '    '.repeat(indentLevel);
   
   // Handle text nodes
   if (node.type === 'text') {
     const text = node.content.trim();
-    return text ? `${indent}$(':${escapeString(text)}');\n` : ``;
+    return text ? `${indent}$('#${escapeString(text)}');\n` : ``;
   }
   
   // Handle comments
@@ -273,8 +337,17 @@ function processElement(node, indentLevel) {
     
     result += tagName + classes;
     
-    // Add attributes (excluding class)
-    const attributes = element.attributes.filter(attr => attr.name !== 'class');
+    // Add style shorthand
+    const styleAttr = element.attributes.find(attr => attr.name === 'style');
+    if (styleAttr) {
+      const styleShorthand = convertStyleToAberdeen(styleAttr.value);
+      if (styleShorthand) {
+        result += ' ' + styleShorthand;
+      }
+    }
+    
+    // Add attributes (excluding class and style)
+    const attributes = element.attributes.filter(attr => attr.name !== 'class' && attr.name !== 'style');
     const { attrString, separateArgs } = buildAttributeString(attributes);
     result += attrString;
     
@@ -287,8 +360,8 @@ function processElement(node, indentLevel) {
       const textContent = element.children[0].content.trim();
       if (i === chain.length - 1) {
         // If it's the last element in the chain and there are no other children,
-        // use the ':' syntax for text
-        result += ':' + escapeString(textContent);
+        // use the '#' syntax for text
+        result += '#' + escapeString(textContent);
       } else {
         // Treat text like any other attribute
         const textAttr = { name: 'text', value: textContent };
@@ -379,7 +452,7 @@ function buildAttributeString(attributes) {
     
     if (value === '') {
       // Boolean attribute
-      attrString += ` ${attr.name}`;
+      attrString += ` ${attr.name}=""`;
     } else if (value.includes('"')) {
       // Contains double quotes - must use separate argument
       attrString += ` ${attr.name}=`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aberdeen",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "author": "Frank van Viegen",
   "main": "dist-min/aberdeen.js",
   "devDependencies": {
@@ -41,7 +41,8 @@
   "files": [
     "dist",
     "dist-min",
-    "src"
+    "src",
+    "skill"
   ],
   "bin": {
     "html-to-aberdeen": "./html-to-aberdeen"

package/skill/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: aberdeen
+description: Expert guidance for building reactive UIs with the Aberdeen library. Covers element creation with $, reactive state with proxy(), efficient lists with onEach(), two-way binding, CSS shortcuts, and advanced features like routing, transitions, and optimistic updates.
+---
+
+# Aberdeen
+
+Reactive UI library using fine-grained reactivity via JS Proxies. No virtual DOM.
+
+## Imports
+```typescript
+import { $, proxy, onEach, ref, mount, insertCss, insertGlobalCss, cssVars, derive, map, multiMap, partition, count, isEmpty, clean, invertString } from 'aberdeen';
+import { grow, shrink } from 'aberdeen/transitions';  // Optional
+import * as route from 'aberdeen/route';              // Optional
+```
+
+## Element Creation: `$`
+```typescript
+// Tag, classes, text content
+$('div.container.active#Hello World');
+
+// Nested elements in single call (each becomes child of previous)
+$('div.wrapper mt:@3 span.icon');
+
+// Attributes/properties via string syntax (preferred)
+$('input placeholder=Name value=initial');
+
+// Dynamic values: end key with `=`, next arg is value
+$('input placeholder="Something containing spaces" value=', userInput);
+$('button text=', `Count: ${state.count}`);
+
+// Event handlers
+$('button#Click click=', () => console.log('clicked'));
+
+// Nested content via function (creates reactive scope)
+$('ul', () => {
+    $('li#Item 1');
+    $('li#Item 2');
+});
+```
+
+**Never concatenate user data into strings.** Use dynamic syntax:
+```typescript
+// WRONG - XSS risk and breaks on special chars
+$(`input value=${userData}`);
+
+// CORRECT
+$('input value=', userData);
+```
+
+### String Syntax Reference
+| Syntax | Meaning |
+|--------|--------|
+| `tag` | Element name (creates child, becomes current element) |
+| `.class` | Add CSS class |
+| `#text` | Text content (rest of string) |
+| `prop:value` | Inline CSS style |
+| `attr=value` | Attribute with static string value |
+| `prop:` or `attr=` | Next argument is CSS prop/attribute/property/event listener |
+
+### Object Syntax (alternative)
+```typescript
+// Equivalent to string syntax, useful for complex cases
+// Note how the '$' prefix is used for CSS properties
+$('input', { placeholder: 'Name', value: userData, $color: 'red' });
+$('button', { click: handler, '.active': isActive });
+```
+
+### CSS Property Shortcuts
+| Short | Full | Short | Full |
+|-------|------|-------|------|
+| `m` | margin | `p` | padding |
+| `mt`,`mb`,`ml`,`mr` | marginTop/Bottom/Left/Right | `pt`,`pb`,`pl`,`pr` | paddingTop/... |
+| `mv` | marginTop + marginBottom | `pv` | paddingTop + paddingBottom |
+| `mh` | marginLeft + marginRight | `ph` | paddingLeft + paddingRight |
+| `w` | width | `h` | height |
+| `bg` | background | `fg` | color |
+| `r` | borderRadius | | |
+
+### CSS Variables (`@`)
+Values starting with `@` reference `cssVars`. Predefined spacing scale:
+| Var | Value | Var | Value |
+|-----|-------|-----|-------|
+| `@1` | 0.25rem | `@4` | 2rem |
+| `@2` | 0.5rem | `@5` | 4rem |
+| `@3` | 1rem | `@n` | 2^(n-3) rem |
+
+**Best practice:** Use `@3` and `@4` for most margins/paddings. For new projects, define color variables:
+```typescript
+cssVars.primary = '#3b82f6';
+cssVars.danger = '#ef4444';
+$('button bg:@primary fg:white#Save');
+```
+
+## Reactive State: `proxy()`
+```typescript
+// Objects (preserves type!)
+const state = proxy({ name: 'Alice', count: 0 });
+
+// Primitives get wrapped in { value: T }
+const flag = proxy(true);
+flag.value = false;
+
+// Class instances work great - use for typed state!
+class Todo {
+    constructor(public text: string, public done = false) {}
+    toggle() { this.done = !this.done; }
+}
+const todo: Todo = proxy(new Todo('Learn Aberdeen'));
+todo.toggle(); // Reactive method call!
+
+// Arrays
+const items = proxy<string[]>([]);
+items.push('new');
+delete items[0];
+```
+
+## Reactive Scopes
+Functions passed to `$` create **scopes**. When proxy data accessed inside changes:
+1. All effects from previous run are **cleaned** (DOM elements removed, `clean()` callbacks run)
+2. Function re-runs
+
+```typescript
+$('div', () => {
+    // Re-runs when state.name changes, replacing the h1
+    $(`h1#Hello ${state.name}`);
+});
+```
+
+### Granular Updates
+Split scopes for minimal DOM updates:
+```typescript
+$('div', () => {
+    $('h1', () => $(`#${state.title}`));  // Only title text re-renders
+    $('p', () => $(`#${state.body}`));    // Only body text re-renders
+    // Or
+    $('p#', ref(state, 'body'));    // Two-way maps {body: x} to {value: x}, which will be read reactively by $
+});
+```
+
+### Passing Observables Directly
+Avoid subscribing in parent scope:
+```typescript
+$('div', () => {
+    // Not great: reruns this scope when state.count changes
+    $('span text=', state.count);  // Subscribes here!
+});
+
+$('div', () => {
+    // Good: only text node updates, this function does not rerun
+    $('span text=', ref(state, 'count'));  // Passes observable, subscribes internally
+});
+```
+
+Or just use a single-value proxy `const count = proxy(0);` and pass it directly `$('span text=', count);`.
+
+### Manual Cleanup with `clean()`
+Register cleanup for non-$ side effects:
+```typescript
+$(() => {
+    if (!reactive.value) return;
+    const timer = setInterval(() => console.log('tick'), 1000);
+    clean(() => clearInterval(timer));  // Runs on scope cleanup
+});
+```
+
+## Lists: `onEach()`
+```typescript
+onEach(items, (item, index) => {
+    $('li', () => $(`#${item.text}`));
+}, item => item.id);  // Optional sort key
+```
+- Renders only changed items efficiently
+- Sort key: `number | string | [number|string, ...]` or `undefined` to hide item
+- Use `invertString(str)` for descending string sort
+- Works on arrays, objects, and Maps
+
+## Two-Way Binding
+```typescript
+$('input bind=', ref(state, 'name'));
+$('input type=checkbox bind=', ref(state, 'active'));
+$('select bind=', ref(state, 'choice'), () => {
+    $('option value=a#Option A');
+    $('option value=b#Option B');
+});
+```
+
+## Derived Values
+
+### `derive()` - Derived primitives
+```typescript
+const doubled: { value: number } = derive(() => state.count * 2);
+$('span text=', doubled);
+```
+
+### Collection functions
+```typescript
+// count() - returns { value: number } proxy
+const total: { value: number } = count(items);
+
+// isEmpty() - returns boolean, re-runs scope only when emptiness changes
+if (isEmpty(items)) $('p#No items');
+
+// map() - returns proxied array/object of same shape
+const names: string[] = map(users, u => u.active ? u.name : undefined);
+
+// multiMap() - each input produces multiple outputs
+const byId: Record<string, User> = multiMap(users, u => ({ [u.id]: u }));
+
+// partition() - sort items into buckets
+const byStatus: Record<string, Record<number, Task>> = partition(tasks, t => t.status);
+```
+
+## Component-Local CSS
+`insertCss` returns a unique class name (e.g., `.AbdStl1`). Call at **module top-level**, not inside render functions:
+```typescript
+// At top of file
+const boxStyle = insertCss({
+    bg: '@primary',
+    r: '@2',
+    button: {
+        m: '@2',
+        '&:hover': { opacity: 0.8 }
+    }
+});
+
+// In render code
+$('div', boxStyle, 'button#Click');
+```
+
+For global styles (no class prefix):
+```typescript
+insertGlobalCss({
+    body: { m: 0, fontFamily: 'system-ui' },
+    'a': { fg: '@primary' }
+});
+```
+
+CSS can be reactive when needed (e.g., theme switching):
+```typescript
+$(() => {
+    insertCss({ bg: theme.dark ? '#222' : '#fff' });
+});
+```
+
+## Transitions
+The `create` and `destroy` properties enable enter/leave animations:
+```typescript
+import { grow, shrink } from 'aberdeen/transitions';
+
+// Built-in grow/shrink for smooth height/width animations
+onEach(items, item => {
+    $('li create=', grow, 'destroy=', shrink, `#${item.text}`);
+});
+
+// CSS class-based transitions
+$('div create=.fade-in destroy=.fade-out#Animated');
+// On create: class added briefly then removed (after layout)
+// On destroy: class added, element removed after 2s delay
+```
+
+Only triggers for **top-level** elements of a (re-)running scope, not deeply nested children.
+
+## HTML Conversion Tool
+Convert HTML to Aberdeen syntax:
+```bash
+echo '<div class="box"><p>Hello</p></div>' | npx html-to-aberdeen
+# Output: $('div.box', () => { $('p#Hello'); });
+```
+
+## Advanced Features
+- **Routing**: [references/routing.md](references/routing.md) - Browser history routing and path dispatching
+- **Transitions**: [references/transitions.md](references/transitions.md) - Detailed animation patterns
+- **Predictions**: [references/prediction.md](references/prediction.md) - Optimistic UI with auto-revert
+
+## Best Practices
+1. **Type everything:** Use TypeScript. `proxy()` preserves types; class instances work great.
+2. **Use CSS variables:** Define `@primary`, `@secondary`, etc. in `cssVars` for colors.
+3. **Use spacing scale:** Prefer `@3`, `@4` for margins/paddings over hardcoded values, for consistency and easy theming/scaling. Don't use when exact pixel values are needed.
+4. **Minimize scope size:** Smaller reactive scopes = fewer DOM updates.
+5. **Use `onEach` for lists:** Never iterate proxied arrays with `for`/`map` in render functions.
+6. **Pass observables directly:** `$('span text=', observable)` not interpolation.
+7. **Components are functions:** Just write functions that call `$`.
+8. **Top-level CSS:** Call `insertCss` at module level, not in render functions.
+9. **Dynamic values:** Always use `attr=', value` syntax for user data.

package/skill/references/prediction.md

@@ -0,0 +1,45 @@
+# 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

@@ -0,0 +1,81 @@
+# 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

@@ -0,0 +1,52 @@
+# 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');
+```