aberdeen 1.3.2 → 1.4.1

package/README.md

@@ -162,7 +162,7 @@ Some further examples:
 - [Input demo](https://aberdeenjs.org/examples/input/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/input)
 - [Tic Tac Toe demo](https://aberdeenjs.org/examples/tictactoe/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/tictactoe)
 - [List demo](https://aberdeenjs.org/examples/list/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/list)
-- [Routing demo](https://aberdeenjs.org/examples/router/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/router)
+- [Routing demo](https://aberdeenjs.org/examples/route/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/route)
 - [JS Framework Benchmark demo](https://aberdeenjs.org/examples/js-framework-benchmark/) - [Source](https://github.com/vanviegen/aberdeen/tree/master/examples/js-framework-benchmark)
 
 ## Learning Aberdeen
@@ -172,7 +172,42 @@ 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)
+
+**Enhancements:**
+- Shortcuts for common CSS properties. For instance: `$('div mv:10px')` for setting vertical (top and bottom) margins.
+- Variables you can set and use in CSS styles, e.g. `$('div bg:@myColor')` after setting `cssVars.myColor = 'red'`.
+- Default CSS variables are defined for spacing: `@2` is `0.5rem`, `@3` is `1rem`, etc. For example: `$('r:@3')` sets border radius to (a dynamically configurable) `1rem`.
+- All CSS shortcuts and `@` variables are also supported in `insertCss` and `insertGlobalCss`.
+- Added `insertGlobalCss` for adding global styles. The `global` argument to `insertCss` is now deprecated.
+
+**Fixes:**
+- When doing `$('div #first', () => $('#second'))`, *second* now comes after *first*. It used to be the other way around.
 
 ### 1.3.2 (2025-01-07)
 

package/dist/aberdeen.d.ts

@@ -251,6 +251,21 @@ export declare function merge<T extends object>(dst: T, dstKey: keyof T, value:
  * be observed for changes.
  */
 export declare const NO_COPY: unique symbol;
+/**
+ * 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).
+ *
+ * @example
+ * ```typescript
+ * 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
+ * ```
+ */
+export declare const cssVars: Record<string, string>;
 /**
  * Clone an (optionally proxied) object or array.
  *
@@ -392,7 +407,7 @@ export declare function ref<T extends TargetType, K extends keyof T>(target: T,
  */
 export declare function $(...args: any[]): undefined | Element;
 /**
- * Inserts CSS rules into the document, optionally scoping them with a unique class name.
+ * Inserts CSS rules into the document, scoping them with a unique class name.
  *
  * Takes a JavaScript object representation of CSS rules. camelCased property keys are
  * converted to kebab-case (e.g., `fontSize` becomes `font-size`).
@@ -403,11 +418,9 @@ export declare function $(...args: any[]): undefined | Element;
  *   - In case a selector contains a `&`, that character will be replaced by the parent selector.
  *   - Selectors will be split on `,` characters, each combining with the parent selector with *or* semantics.
  *   - Selector starting with `'@'` define at-rules like media queries. They may be nested within regular selectors.
- * @param global - If `true`, styles are inserted globally without prefixing.
- *                 If `false` (default), all selectors are prefixed with a unique generated
- *                 class name (e.g., `.AbdStl1`) to scope the styles.
- * @returns The unique class name prefix used for scoping (e.g., `.AbdStl1`), or an empty string
- *          if `global` was `true`. Use this prefix with {@link $} to apply the styles.
+ * @param global - @deprecated Use {@link insertGlobalCss} instead.
+ * @returns The unique class name prefix used for scoping (e.g., `.AbdStl1`). Use this
+ *          prefix with {@link $} to apply the styles.
  *
  * @example Scoped Styles
  * ```typescript
@@ -432,23 +445,30 @@ export declare function $(...args: any[]): undefined | Element;
  *   $('div.child-element#Child'); // .AbdStl1 .child-element rule applies
  * });
  * ```
+ */
+export declare function insertCss(style: object, global?: boolean): string;
+/**
+ * Inserts CSS rules globally.
+ *
+ * Works exactly like {@link insertCss}, but without prefixing selectors with a unique class name.
  *
  * @example Global Styles
  * ```typescript
- * insertCss({
+ * insertGlobalCss({
  *   '*': {
  *     fontFamily: 'monospace',
+ *     m: 0, // Using shortcut for margin
  *   },
  *   'a': {
  *     textDecoration: 'none',
- *     color: "#107ab0",
+ *     fg: "@primary", // Using foreground shortcut and CSS variable
  *   }
- * }, true); // Pass true for global
+ * });
  *
  * $('a#Styled link');
  * ```
  */
-export declare function insertCss(style: object, global?: boolean): string;
+export declare function insertGlobalCss(style: object): string;
 /**
  * Sets a custom error handler function for errors that occur asynchronously
  * within reactive scopes (e.g., during updates triggered by proxy changes in

package/dist/aberdeen.js

@@ -224,6 +224,8 @@ class ChainedScope extends ContentScope {
     if (el === currentScope.el) {
       this.prevSibling = currentScope.getChildPrevSibling();
       currentScope.lastChild = this;
+    } else {
+      this.prevSibling = el.lastChild || undefined;
     }
     if (!useParentCleaners)
       currentScope.cleaners.push(this);
@@ -1061,6 +1063,10 @@ var COPY_SUBSCRIBE = 32;
 var COPY_EMIT = 64;
 var NO_COPY = Symbol("NO_COPY");
 Promise.prototype[NO_COPY] = true;
+var cssVars = optProxy({});
+for (let i = 1;i <= 12; i++) {
+  cssVars[i] = 2 ** (i - 3) + "rem";
+}
 function clone(src) {
   if (NO_COPY in src)
     return src;
@@ -1260,6 +1266,30 @@ function insertCss(style, global = false) {
     $(`style#${css}`);
   return prefix;
 }
+function insertGlobalCss(style) {
+  return insertCss(style, true);
+}
+var CSS_SHORT = {
+  m: "margin",
+  mt: "marginTop",
+  mb: "marginBottom",
+  ml: "marginLeft",
+  mr: "marginRight",
+  mh: ["marginLeft", "marginRight"],
+  mv: ["marginTop", "marginBottom"],
+  p: "padding",
+  pt: "paddingTop",
+  pb: "paddingBottom",
+  pl: "paddingLeft",
+  pr: "paddingRight",
+  ph: ["paddingLeft", "paddingRight"],
+  pv: ["paddingTop", "paddingBottom"],
+  w: "width",
+  h: "height",
+  bg: "background",
+  fg: "color",
+  r: "borderRadius"
+};
 function styleToCss(style, prefix) {
   let props = "";
   let rules = "";
@@ -1275,7 +1305,11 @@ ${styleToCss(v, prefix)}}
           rules += styleToCss(v, k.includes("&") ? k.replace(/&/g, prefix) : `${prefix} ${k}`);
         }
       } else {
-        props += `${k.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}:${v};`;
+        const val = v == null || v === false ? "" : typeof v === "string" ? v[0] === "@" ? cssVars[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};`;
+        }
       }
     }
   }
@@ -1298,11 +1332,15 @@ function applyArg(el, key, value) {
     else
       el.classList.remove(...classes);
   } else if (key[0] === "$") {
-    const name = key.substring(1);
-    if (value == null || value === false)
-      el.style[name] = "";
-    else
-      el.style[name] = `${value}`;
+    key = key.substring(1);
+    const val = value == null || value === false ? "" : typeof value === "string" ? value[0] === "@" ? cssVars[value.substring(1)] || "" : value : String(value);
+    const expanded = CSS_SHORT[key] || key;
+    if (typeof expanded === "string") {
+      el.style[expanded] = val;
+    } else {
+      for (const prop of expanded)
+        el.style[prop] = val;
+    }
   } else if (value == null) {} else if (key in SPECIAL_PROPS) {
     SPECIAL_PROPS[key](el, value);
   } else if (typeof value === "function") {
@@ -1482,11 +1520,13 @@ export {
   leakScope,
   isEmpty,
   invertString,
+  insertGlobalCss,
   insertCss,
   getParentElement,
   dump,
   derive,
   defaultEmitHandler,
+  cssVars,
   count,
   copy,
   clone,
@@ -1495,5 +1535,5 @@ export {
   $
 };
 
-//# debugId=FE7EA671EAA8B7E164756E2164756E21
+//# debugId=BD37C20F6280CE8164756E2164756E21
 //# sourceMappingURL=aberdeen.js.map