aberdeen 1.18.1 → 1.19.0

package/skill/A.md

@@ -0,0 +1,127 @@
+## A · function
+
+The core function for building reactive user interfaces in Aberdeen. It creates and inserts new DOM elements
+and sets attributes/properties/event listeners on DOM elements. It does so in a reactive way, meaning that
+changes will be (mostly) undone when the current *scope* is destroyed or will be re-execute.
+
+**Signature:** `(...args: any[]) => Element`
+
+**Parameters:**
+
+- `args: any[]` - - Any number of arguments can be given. How they're interpreted depends on their types:
+
+### String arguments
+Strings can be used to create and insert new elements, set classnames for the *current* element, and add text to the current element.
+The format of a string is: (**tag** | `.` **class** | **key**[=:]**val** | **key**[=:]"**val containing spaces**")* ('#' **text** | **key**[=:])?
+
+So a string may consist of any number of...
+- **tag** elements, like `h1` or `div`. These elements are created, added to the *current* element, and become the new *current* element for the rest of this `A` function execution.
+- CSS classes prefixed by `.` characters. These classes will be added to the *current* element. Optionally, CSS classes can be appended to a **tag** without a space. So both `div.myclass` and `div .myclass` are valid and do the same thing.
+- Property key/value pairs, like `type=password`, `placeholder="Your name"` or `data-id=123`. When the value contains spaces, it needs to be quoted with either "double quotes", 'single quotes' or \`backticks\`. Quotes within quoted values cannot be escaped (see the next rule for a solution). Key/value pairs will be handled according to *Property rules* below, but with the caveat that values can only be strings.
+- CSS key/value pairs using two syntaxes:
+- **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 support CSS shortcuts (see below). You can mix them: `m:$3 box-shadow: 0 2px 4px rgba(0,0,0,0.2); bg:$cardBg`
+The elements must be separated by spaces, except before a `.cssClass` if it is preceded by either **tag** or another CSS class.
+
+And a string may end in...
+- A '#' followed by text, which will be added as a `TextNode` to the *current* element. The text ranges til the end of the string, and may contain any characters, including spaces and quotes.
+- A key followed by an '=' character, in which case the value is expected as a separate argument. The key/value pair is set according to the *Property rules* below. This is useful when the value is not a string or contains spaces or user data. Example: `A('button text="Click me" click=', () => alert('Clicked!'))` or `A('input.value=', someUserData, "placeholder=", "Type your stuff")`. In case the value is a proxied object, its `.value` property will be applied reactively without needing to rerender the parent scope.
+- A key followed by a ':' character (with no value), in which case the value is expected as a separate argument. The value is treated as a CSS value to be set inline on the *current* element. Example: `A('div margin-top:', someValueInPx)`. In case the value is a proxied object, its `.value` property will be applied reactively without needing to rerender the parent scope.
+
+### Function arguments
+When a function (without arguments nor a return value) is passed in, it will be reactively executed in its own observer scope, preserving the *current* element. So any `A()` invocations within this function will add child elements to or set properties on that element. If the function reads observable data, and that data is changed later on, the function we re-execute (after side effects, such as DOM modifications through `A`, have been cleaned - see also `clean`).
+
+### Object arguments
+When an object is passed in, its key-value pairs are used to modify the *current* element according to the *Property rules* below, *unless* the key starts with a `$` character, in which case that character is stripped of and the key/value pair is treated as a CSS property, subject to the *CSS shortcuts* below. In case a value is a proxied object, its `.value` property will be applied reactively without needing to rerender the parent scope. In most cases, the string notation (`key=` and `key:`) is preferred over this object notation, for readability.
+
+### DOM node arguments
+When a DOM Node (Element or TextNode) is passed in, it is added as a child to the *current* element. If the Node is an Element, it becomes the new *current* element for the rest of this `A` function execution.
+
+### Property rules
+- **Attribute:** The common case is setting the value as an HTML attribute named key. For example `A('input placeholder=Name')` results in `<input placeholder="Name">`.
+- **Event listener:** If the value is a `function` it is set as an event listener for the event with the name given by the key. For example: A('button text=Press! click=', () => alert('Clicked!'))`. The event listener will be removed when the current scope is destroyed.
+- **DOM property:** When the value is a boolean, or the key is `"value"` or `"selectedIndex"`, it is set on the `current` element as a DOM property instead of an HTML attribute. For example `A('checked=', true)` would do `el.checked = true` for the *current* element.
+- **Conditional CSS class:** If the key starts with a `.` character, its either added to or removed from the *current* element as a CSS class, based on the truthiness of the value. So `A('.hidden=', isHidden)` would toggle the `hidden` CSS class. This only works if the `=` is the last character of the string, and the next argument is the value. Its common for the value to be a proxied object, in which case its `.value` is reactively applied without needing to rerender the parent scope.
+- **Create transition:** When the key is `"create"`, the value will be added as a CSS class to the *current* element immediately, and then removed right after the browser has finished doing a layout pass. This behavior only triggers when the scope setting the `create` is the top-level scope being (re-)run. This allows for creation transitions, without triggering the transitions for deeply nested elements being drawn as part of a larger component. The string may also contain multiple dot-separated CSS classes, such as `.fade.grow`. The initial dot is optional. Alternatively, to allow for more complex transitions, the value may be a function that receives the `HTMLElement` being created as its only argument. It is *only* called if this is the top-level element being created in this scope run. See `transitions.ts` in the Aberdeen source code for some examples.
+- **Destroy transition:** When the key is `"destroy"` the value will be used to apply a CSS transition if the *current* element is later on removed from the DOM and is the top-level element to be removed. This happens as follows: actual removal from the DOM is delayed by 2 seconds, and in the mean-time the value string is added as a CSS class to the element, allowing for a deletion transition. The string may also contain multiple dot-separated CSS classes, such as `.fade.shrink`. The initial dot is optional. Alternatively, to allow for more complex transitions, the value may be a function that receives the `HTMLElement` to be removed from the DOM as its only argument. This function may perform any transitions and is then itself responsible for eventually removing the element from the DOM. See `transitions.ts` in the Aberdeen source code for some examples.
+- **Two-way data binding:** When the key is `"bind"` a two-way binding between the `.value` property of the given proxied object, and the *current* input element (`<input>`, `<select>` or `<textarea>`) is created. This is often used together with `ref`, in order to use properties other than `.value`.
+- **Text:**: If the key is `"text"`, the value will be appended as a `TextNode` to the *current* element. The same can also be done with the `#` syntax in string arguments, though `text=` allows additional properties to come after in the same string: `A('button text=Hello click=', alert)`.
+- **Unsafe HTML:** When the key is `"html"`, the value will be added as HTML to the *current* element. This should only be used in exceptional situations. Beware of XSS! Never use this with untrusted user data.
+- **Rich text:** When the key is `"rich"`, the value is parsed as simple markdown-like syntax and rendered as inline elements. Supports `*italic*`, `**bold**`, `` `code` ``, and `[link text](/path)`. All text content is safely escaped, making it suitable for user data (though links should be validated if untrusted). Example: `A('p rich="Click *here* for **more** info")`.
+
+### CSS shortcuts
+For conciseness, Aberdeen supports some CSS shortcuts when setting CSS properties.
+| Shortcut | Expands to |
+|----------|------------|
+| `m`, `mt`, `mb`, `ml`, `mr` | `margin`, `margin-top`, `margin-bottom`, `margin-left`, `margin-right` |
+| `mv`, `mh` | Vertical (top+bottom) or horizontal (left+right) margins |
+| `p`, `pt`, `pb`, `pl`, `pr` | `padding`, `padding-top`, `padding-bottom`, `padding-left`, `padding-right` |
+| `pv`, `ph` | Vertical or horizontal padding |
+| `w`, `h` | `width`, `height` |
+| `bg` | `background` |
+| `fg` | `color` |
+| `r` | `border-radius` |
+
+Also, when the value is a string starting with `$`, it is treated as a reference to a CSS variable, expanding to `var(--variableName)`. For numeric variable names (which can't be used directly as CSS custom property names), Aberdeen prefixes them with `m`, so `$3` expands to `var(--m3)`. This is primarily intended for use with `setSpacingCssVars`, which initializes spacing variables named `0` through `12` with an exponential spacing scale.
+
+To *set* a CSS custom property inline on an element, use a `--name` or (symmetrically with the `$`-reference syntax above) a `$name` key. For example `A('div --primary:red')` and `A('div $primary:red')` both set `--primary` to `red`.
+
+**Returns:** The most inner DOM element that was created (not counting text nodes nor elements created by content functions), or the current element if no new element was created. You should normally not need to use the return value - use this function's DOM manipulation abilities instead. One valid use case is when integrating with non-Aberdeen code that requires a reference to a DOM element.
+
+**Examples:**
+
+Create Element
+```typescript
+A('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
+`false` as a boolean instead of a string.
+
+Create Nested Elements
+```typescript
+let inputElement: Element = A('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);
+```
+
+Content Functions & Reactive Scope
+```typescript
+const $state = A.proxy({ count: 0 });
+A('div', () => { // Outer element
+// This scope re-renders when $state.count changes
+A(`p#Count is ${$state.count}`);
+A('button text=Increment click=', () => $state.count++);
+});
+```
+
+Two-way Binding
+```typescript
+const $user = A.proxy({ name: '' });
+A('input placeholder=Name bind=', A.ref($user, 'name'));
+A('h3', () => { // Reactive scope
+A(`#Hello ${$user.name || 'stranger'}`);
+});
+```
+
+Conditional Rendering
+```typescript
+const $show = A.proxy(false);
+A('button click=', () => $show.value = !$show.value, () => A($show.value ? '#Hide' : '#Show'));
+A(() => { // Reactive scope
+if ($show.value) {
+A('p#Details are visible!');
+}
+});
+```
+
+Proxied objects as values
+```typescript
+const $myColor = A.proxy('red');
+A('p text="The color is " text=', $myColor, 'click=', () => $myColor.value = 'yellow')
+// Clicking the text will cause it to change color without recreating the <p> itself
+```
+This is often used together with `ref`, in order to use properties other than `.value`.

package/skill/Dispatcher.md

@@ -0,0 +1,51 @@
+## Dispatcher · class
+
+Simple route matcher and dispatcher.
+
+Example usage:
+
+```ts
+import * as route from 'aberdeen/route';
+import { Dispatcher, MATCH_REST } from 'aberdeen/dispatcher';
+
+const dispatcher = new Dispatcher();
+
+dispatcher.addRoute("user", Number, "stream", String, (id, stream) => {
+   console.log(`User ${id}, stream ${stream}`);
+});
+
+dispatcher.dispatch(["user", "42", "stream", "music"]);
+// Logs: User 42, stream music
+
+dispatcher.addRoute("search", MATCH_REST, (terms: string[]) => {
+    console.log("Search terms:", terms);
+});
+
+dispatcher.dispatch(["search", "classical", "piano"]);
+// Logs: Search terms: [ 'classical', 'piano' ]
+```
+
+### dispatcher.addRoute · method
+
+Add a route with matchers and a handler function.
+
+**Signature:** `<T extends Matcher[], H extends (...args: ParamsFromMatchers<T>) => void>(...args: [...T, H]) => void`
+
+**Parameters:**
+
+- `args: [...T, H]` - An array of matchers followed by a handler function. Each matcher can be:
+- A string: matches exactly that string.
+- A function: takes a string segment and returns a value (of any type) if it matches, or `MATCH_FAILED` if it doesn't match. The return value (if not `MATCH_FAILED` and not `NaN`) is passed as a parameter to the handler function. The standard JavaScript functions `Number` and `String` can be used to match numeric and string segments respectively.
+- The special `MATCH_REST` symbol: matches the rest of the segments as an array of strings. Only one `MATCH_REST` is allowed.
+
+### dispatcher.dispatch · method
+
+Dispatches the given segments to the first route handler that matches.
+
+**Signature:** `(segments: string[]) => boolean`
+
+**Parameters:**
+
+- `segments: string[]` - Array of string segments to match against the added routes. When using this class with the Aberdeen `route` module, one would typically pass `route.current.p`.
+
+**Returns:** True if a matching route was found and handled, false otherwise.

package/skill/OPAQUE.md

@@ -0,0 +1,15 @@
+## OPAQUE · constant
+
+A symbol that controls how Aberdeen handles an object in copy operations and proxy wrapping.
+
+The **presence** of this symbol (regardless of its value) prevents deep-copying: the object is
+stored and passed by reference in `clone` and `copy`.
+
+The **value** of the symbol controls proxy wrapping when the object is read from reactive state:
+- **Truthy** (e.g. `true`): the object is fully opaque — it is not wrapped in a proxy, so its
+  properties are not observable. Use this for objects that break when proxied (e.g. class instances
+  with internal slots, Promises) or that must be invisible to Aberdeen's reactive system.
+- **Falsy** (e.g. `false`): the object is still wrapped in a proxy, so reads on its properties
+  create reactive dependencies as normal — only deep-copying is suppressed.
+
+**Value:** `unique symbol`

package/skill/PromiseProxy.md

@@ -0,0 +1,25 @@
+## PromiseProxy · interface
+
+When `proxy` is called with a Promise, the returned object has this shape.
+
+**Type Parameters:**
+
+- `T`
+
+### promiseProxy.busy · member
+
+True if the promise is still pending, false if it has resolved or rejected.
+
+**Type:** `boolean`
+
+### promiseProxy.value · member
+
+If the promise has resolved, this contains the resolved value.
+
+**Type:** `T`
+
+### promiseProxy.error · member
+
+If the promise has rejected, this contains the rejection error.
+
+**Type:** `any`

package/skill/Route.md

@@ -0,0 +1,50 @@
+## Route · interface
+
+The class for the global `route` object.
+
+### route.path · member
+
+The current path of the URL as a string. For instance `"/"` or `"/users/123/feed"`. Paths are normalized to always start with a `/` and never end with a `/` (unless it's the root path).
+
+**Type:** `string`
+
+### route.p · member
+
+An convenience array containing path segments, mapping to `path`. For instance `[]` (for `"/"`) or `['users', '123', 'feed']` (for `"/users/123/feed"`).
+
+**Type:** `string[]`
+
+### route.hash · member
+
+The hash fragment including the leading `#`, or an empty string. For instance `"#my_section"` or `""`.
+
+**Type:** `string`
+
+### route.search · member
+
+The query string interpreted as search parameters. So `"a=x&b=y"` becomes `{a: "x", b: "y"}`.
+
+**Type:** `Record<string, string>`
+
+### route.state · member
+
+An object to be used for any additional data you want to associate with the current page. Data should be JSON-compatible.
+
+**Type:** `Record<string, any>`
+
+### route.depth · member
+
+The navigation depth of the current session. Starts at 1. Writing to this property has no effect.
+
+**Type:** `number`
+
+### route.nav · member
+
+The navigation action that got us to this page. Writing to this property has no effect.
+- `"load"`: An initial page load.
+- `"back"` or `"forward"`: When we navigated backwards or forwards in the stack.
+- `"go"`: When we added a new page on top of the stack.
+- `"push"`: When we added a new page on top of the stack, merging with the current page.
+Mostly useful for page transition animations. Writing to this property has no effect.
+
+**Type:** `NavType`