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

aberdeen 1.4.1 → 1.5.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 (9) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "aberdeen",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "author": "Frank van Viegen",
   "main": "dist-min/aberdeen.js",
   "devDependencies": {

package/skill/SKILL.md CHANGED Viewed

@@ -30,7 +30,7 @@ $('input placeholder="Something containing spaces" value=', userInput);
 $('button text=', `Count: ${state.count}`);
 // Event handlers
-$('button#Click click=', () => console.log('clicked'));
+$('button text=Click click=', () => console.log('clicked'));
 // Nested content via function (creates reactive scope)
 $('ul', () => {
@@ -78,18 +78,23 @@ $('button', { click: handler, '.active': isActive });
 | `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 |
+Values starting with `@` expand to native CSS custom properties via `var(--name)`. Numeric keys are prefixed with `m` (e.g., `@3` → `var(--m3)`).
+Predefined spacing scale:
+| Var | CSS Output | Value |
+|-----|------------|-------|
+| `@1` | `var(--m1)` | 0.25rem |
+| `@2` | `var(--m2)` | 0.5rem |
+| `@3` | `var(--m3)` | 1rem |
+| `@4` | `var(--m4)` | 2rem |
+| `@5` | `var(--m5)` | 4rem |
+| `@n` | `var(--mn)` | 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');
+$('button bg:@primary fg:white#Save'); // outputs: background: var(--primary); color: white
 ```
 ## Reactive State: `proxy()`

package/src/aberdeen.ts CHANGED Viewed

@@ -53,7 +53,7 @@ function queue(runner: QueueRunner) {
  * ```typescript
  * const data = proxy("before");
  *
- * $({text: data});
+ * $('#'+data);
  * console.log(1, document.body.innerHTML); // before
  *
  * // Make an update that should cause the DOM to change.
@@ -940,9 +940,9 @@ const EMPTY = Symbol("empty");
  * // Reactively display a message if the items array is empty
  * $('div', () => {
  *     if (isEmpty(items)) {
- *         $('p', 'i#No items yet!');
+ *         $('p i#No items yet!');
  *     } else {
- * 		   onEach(items, item=>$('p#'+item));
+ *         onEach(items, item => $('p#'+item));
  *     }
  * });
  *
@@ -995,7 +995,7 @@ export interface ValueRef<T> {
  * const cnt = count(items);
  *
  * // Create a DOM text node for the count:
- * $('div', {text: cnt});
+ * $('div text=', cnt);
  * // <div>2</div>
  * // Or we can use it in an {@link derive} function:
@@ -1704,17 +1704,20 @@ export const NO_COPY = Symbol("NO_COPY");
 (Promise.prototype as any)[NO_COPY] = true;
 /**
- * CSS variable lookup table for the `@` value prefix.
+ * CSS variables that are output as native CSS custom properties.
  *
- * When a CSS value starts with `@`, the rest is used as a key to look up the actual value.
+ * 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.
+ *
  * @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
+ * $('p color:@primary'); // Sets color to var(--primary)
+ * $('div mt:@3'); // Sets margin-top to var(--m3)
  * ```
  */
 export const cssVars: Record<string, string> = optProxy({});
@@ -1723,6 +1726,13 @@ for (let i = 1; i <= 12; i++) {
 	cssVars[i] = 2 ** (i - 3) + "rem";
 }
+const DIGIT_FIRST = /^\d/;
+function cssVarRef(name: string): string {
+	// Prefix numeric keys with 'm' (CSS custom property names can't start with a digit)
+	const varName = DIGIT_FIRST.test(name) ? `m${name}` : name;
+	return `var(--${varName})`;
+}
 /**
  * Clone an (optionally proxied) object or array.
  *
@@ -1782,17 +1792,10 @@ const refHandler: ProxyHandler<RefTarget> = {
  * const formData = proxy({ color: 'orange', velocity: 42 });
  *
  * // Usage with `bind`
- * $('input', {
- *   type: 'text',
- *   // Creates a two-way binding between the input's value and formData.username
- *   bind: ref(formData, 'color')
- * });
+ * $('input type=text bind=', ref(formData, 'color'));
  *
  * // Usage as a dynamic property, causes a TextNode with just the name to be created and live-updated
- * $('p#Selected color: ', {
- *   text: ref(formData, 'color'),
- *   $color: ref(formData, 'color')
- * });
+ * $('p text="Selected color: " text=', ref(formData, 'color'), 'color:', ref(formData, 'color'));
  *
  * // Changes are actually stored in formData - this causes logs like `{color: "Blue", velocity 42}`
  * $(() => console.log(formData))
@@ -1926,16 +1929,7 @@ const SPECIAL_PROPS: { [key: string]: (el: Element, value: any) => void } = {
  *
  * @example Create Element
  * ```typescript
- * $('button.secondary.outline#Submit', {
- *   disabled: false,
- *   click: () => console.log('Clicked!'),
- *   $color: 'red'
- * });
- * ```
- *
- * Which can also be written as:
- * ```typescript
- * $('button.secondary.outline text=Submit $color=red disabled=', false, 'click=', () => console.log('Clicked!'));
+ * $('button.secondary.outline text=Submit color:red disabled=', false, 'click=', () => console.log('Clicked!'));
  * ```
  *
  * We want to set `disabled` as a property instead of an attribute, so we must use the `key=` syntax in order to provide
@@ -1943,7 +1937,7 @@ const SPECIAL_PROPS: { [key: string]: (el: Element, value: any) => void } = {
  *
  * @example Create Nested Elements
  * ```typescript
- * let inputElement: Element = $('label#Click me', 'input', {type: 'checkbox'});
+ * let inputElement: Element = $('label text="Click me" input type=checkbox');
  * // You should usually not touch raw DOM elements, unless when integrating
  * // with non-Aberdeen code.
  * console.log('DOM element:', inputElement);
@@ -1955,14 +1949,14 @@ const SPECIAL_PROPS: { [key: string]: (el: Element, value: any) => void } = {
  * $('div', () => { // Outer element
  *   // This scope re-renders when state.count changes
  *   $(`p#Count is ${state.count}`);
- *   $('button#Increment', { click: () => state.count++ });
+ *   $('button text=Increment click=', () => state.count++);
  * });
  * ```
  *
  * @example Two-way Binding
  * ```typescript
  * const user = proxy({ name: '' });
- * $('input', { placeholder: 'Name', bind: ref(user, 'name') });
+ * $('input placeholder=Name bind=', ref(user, 'name'));
  * $('h3', () => { // Reactive scope
  *   $(`#Hello ${user.name || 'stranger'}`);
  * });
@@ -1971,7 +1965,7 @@ const SPECIAL_PROPS: { [key: string]: (el: Element, value: any) => void } = {
  * @example Conditional Rendering
  * ```typescript
  * const show = proxy(false);
- * $('button', { click: () => show.value = !show.value }, () => $(show.value ? '#Hide' : '#Show'));
+ * $('button click=', () => show.value = !show.value, () => $(show.value ? '#Hide' : '#Show'));
  * $(() => { // Reactive scope
  *   if (show.value) {
  *     $('p#Details are visible!');
@@ -2095,7 +2089,7 @@ let cssCount = 0;
  *   - 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 - @deprecated Use {@link insertGlobalCss} instead.
+ * @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.
  *
@@ -2194,7 +2188,7 @@ function styleToCss(style: object, prefix: string): string {
 					);
 				}
 			} else {
-				const val = v == null || v === false ? "" : typeof v === 'string' ? (v[0] === '@' ? (cssVars as any)[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};`;
@@ -2223,7 +2217,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] === '@' ? (cssVars as any)[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;
@@ -2374,7 +2368,7 @@ export function getParentElement(): Element {
  * })
  *
  * // Show the sum
- * $('h1', {text: sum});
+ * $('h1 text=', sum);
  *
  * // Make random changes to the array
  * const rnd = () => 0|(Math.random()*20);
@@ -2412,8 +2406,8 @@ export function clean(cleaner: () => void) {
  *     // When data.notifications changes, only this inner scope reruns,
  *     // leaving the `<p>Welcome, ..</p>` untouched.
  *     console.log('Notifications');
- *     $('code.notification-badge#' + data.notifications);
- *     $('a#Notify!', {click: () => data.notifications++});
+ *     $('code.notification-badge text=', data.notifications);
+ *     $('a text=Notify! click=', () => data.notifications++);
  *   });
  * });
  * ```
@@ -2522,7 +2516,7 @@ export function unmountAll() {
  *
  */
-export function peek<T extends object>(target: T, key: keyof T): T[typeof key];
+export function peek<T extends object, K extends keyof T>(target: T, key: K): T[K];
 export function peek<K,V>(target: Map<K,V>, key: K): V | undefined;
 export function peek<T>(target: T[], key: number): T | undefined;
 export function peek<T>(target: () => T): T;
@@ -2919,3 +2913,21 @@ export function withEmitHandler(
 		emit = oldEmitHandler;
 	}
 }
+// 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}`);
+			})
+		});
+	});
+}