rasti 4.0.0 → 4.1.0-alpha.0

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
     <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.0.0/docs/logo-dark.svg">
-        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.0.0/docs/logo.svg" height="120">
+        <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.1.0-alpha.0/docs/logo-dark.svg">
+        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.1.0-alpha.0/docs/logo.svg" height="120">
     </picture>
 </p>
 
@@ -13,11 +13,12 @@
 It provides declarative, composable **components** for building state-driven UIs.  
 Its low-level MVC core, inspired by **Backbone.js**’s architecture, provides **models**, **views** and **event emitters** as the fundamental building blocks.
 
-[![Travis (.com)](https://img.shields.io/travis/com/8tentaculos/rasti)](https://app.travis-ci.com/8tentaculos/rasti)
+[![CI](https://github.com/8tentaculos/rasti/actions/workflows/ci.yml/badge.svg)](https://github.com/8tentaculos/rasti/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/rasti.svg)](https://www.npmjs.com/package/rasti)
 [![npm package minimized gzipped size](https://img.shields.io/bundlejs/size/rasti)](https://unpkg.com/rasti/dist/rasti.min.js)
 [![npm downloads](https://img.shields.io/npm/dm/rasti.svg)](https://www.npmjs.com/package/rasti)
 [![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/rasti)](https://www.jsdelivr.com/package/npm/rasti)
+[![license](https://img.shields.io/npm/l/rasti.svg)](https://github.com/8tentaculos/rasti/blob/master/LICENSE)
 
 ## Key Features  
 
@@ -35,6 +36,8 @@ Its low-level MVC core, inspired by **Backbone.js**’s architecture, provides *
   Seamlessly integrates into existing **Backbone.js** legacy projects.  
 - **Standards-Based** 📐  
   Built on modern web standards, no tooling required.  
+- **TypeScript Support** 🧩  
+  Ships with type definitions for strict typing of models, views, components, props, and events.  
 
 ## Getting Started
 
@@ -58,8 +61,8 @@ import { Model, Component } from 'https://esm.run/rasti';
 
 Include **Rasti** directly in your HTML using a CDN. Available UMD builds:
 
-- [https://cdn.jsdelivr.net/npm/rasti/dist/rasti.js](https://cdn.jsdelivr.net/npm/rasti/dist/rasti.js)
-- [https://cdn.jsdelivr.net/npm/rasti/dist/rasti.min.js](https://cdn.jsdelivr.net/npm/rasti/dist/rasti.min.js)
+- [rasti.js](https://cdn.jsdelivr.net/npm/rasti/dist/rasti.js)
+- [rasti.min.js](https://cdn.jsdelivr.net/npm/rasti/dist/rasti.min.js)
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/rasti"></script>
@@ -123,7 +126,7 @@ const Navigation = Component.create`
 // Create a Main component that includes the Navigation and displays the current route's label as the title.
 const Main = Component.create`
     <main>
-        <${Navigation} routes=${({ props }) => props.routes} />
+        <${Navigation} routes="${({ props }) => props.routes}" />
         <section>
             <h1>
                 ${({ model, props }) => props.routes.find(
@@ -179,7 +182,7 @@ Counter.mount({ model }, document.body);
 - **Lightweight and Efficient**  
   Minimal footprint with optimized performance, ensuring smooth updates.  
 - **Just the Right Abstraction**  
-  Keeps you close to the DOM with no over-engineering. Fully hackable—if you're curious about how something works, just check the source code.  
+  Keeps you close to the DOM with no over-engineering. Fully hackable — if you're curious about how something works, just check the source code.  
 
 ## Example
 
@@ -189,6 +192,88 @@ You can find a sample **TODO application** in the [example folder](https://githu
 
 For detailed information on how to use **Rasti**, refer to the [API documentation](/docs/api.md).
 
+## TypeScript
+
+**Rasti** ships with TypeScript declarations out of the box. The types are bundled in the package and resolved automatically.
+
+### Components
+
+Pass generics explicitly to type the resulting class:
+
+```ts
+const Header = Component.create<{ handleAddTodo: (title: string) => void }>`
+    <header>...</header>
+`;
+
+new Header({ handleAddTodo: (t) => console.log(t) }); // ✅
+
+// With a typed model:
+const App = Component.create<{}, any, AppModel>`<main>...</main>`;
+App.mount({ model: new AppModel() }, document.body);
+```
+
+Without generics, `Component.create` stays permissive (parity with JS):
+
+```ts
+const Plain = Component.create`<div></div>`;
+new Plain({ anything: 'goes' }); // ✅
+```
+
+### Models
+
+Type the attributes with `Model<Attrs>`. Use **declaration merging** to surface the auto-generated getters/setters as instance properties:
+
+```ts
+import { Model } from 'rasti';
+
+interface TodoAttrs { title: string; completed: boolean; }
+
+class Todo extends Model<TodoAttrs> {
+    preinitialize() {
+        this.defaults = { title: '', completed: false };
+    }
+    toggle() { this.completed = !this.completed; }
+}
+interface Todo extends TodoAttrs {} // Exposes this.title, this.completed
+
+const t = new Todo({ title: 'x' });
+t.title.toUpperCase(); // ✅
+t.on('change:completed', (m, value) => value && /* boolean */ console.log('done'));
+```
+
+### Helper types
+
+```ts
+import {
+    EventHandler,
+    RenderExpression,
+    Attrs,
+    Props,
+    State,
+    ComponentModel,
+} from 'rasti';
+
+// Typed event handler with `this` bound to the component
+const onClick: EventHandler<Counter, MouseEvent> = function(ev) {
+    this.props.label;
+};
+
+// Typed render expression (`(component) => any`)
+const renderLabel: RenderExpression<Counter> = ({ props }) => props.label;
+
+// Extract types from existing classes
+type T = Attrs<Todo>;    // TodoAttrs
+type P = Props<Counter>; // CounterProps
+type S = State<Counter>; // CounterState
+```
+
+### Known limitations
+
+- **Template interpolation callbacks are `any`**. Functions inside `Component.create\`...\`` template literals (`${({ model }) => ...}`, `onClick=${function() { this.x }}`) cannot be inferred from the surrounding template. To type them, annotate explicitly: `function(this: MyComponent, ev) { ... }` or `({ model }: MyComponent) => ...`.
+- **`Model<A>` instance keys require declaration merging**. TypeScript can't add `A`'s keys to a `class extends Model<A>` automatically — see the `interface Todo extends TodoAttrs {}` pattern above.
+- **`this.$()` can return `null`**. It mirrors `querySelector`, so handle the empty case (`?.`) and pass a type argument to narrow the element: `this.$<HTMLInputElement>('input.edit')?.focus()`. `this.$$()` returns a `NodeListOf<HTMLElement>` (also narrowable).
+- **`this.model` / `this.state` are optional**. Both are `undefined` unless provided, so guard (`this.model?.foo`) or assert (`this.model!`) when you know one was passed. Both accept a Rasti `Model` or a model from another library (e.g. Backbone); Components subscribe to `change` events automatically when the object exposes `on`/`off`.
+
 ## Working with LLMs
 
 For those working with LLMs, there is an [AI Agents reference guide](/docs/AGENTS.md) that provides API patterns, lifecycle methods, and best practices, optimized for LLM context. You can share this guide with AI assistants to help them understand **Rasti**'s architecture and component APIs.
@@ -209,4 +294,3 @@ We strive to minimize breaking changes between major versions. However, if you'r
 ## Contributing
 
 Contributions are welcome! Share feature ideas or report bugs on our [GitHub Issues page](https://github.com/8tentaculos/rasti/issues).
-

package/dist/rasti.js

@@ -419,7 +419,6 @@
      * @param {...*} [args] Additional arguments passed to `preinitialize` and `parse` methods
      * @property {object|Function} defaults Default attributes for the model. If a function, it's called bound to the model instance to get defaults.
      * @property {object} previous Object containing previous attributes when a change occurs.
-     * @property {string} attributePrefix Static property that defines a prefix for generated getters/setters. Defaults to empty string.
      * @example
      * import { Model } from 'rasti';
      * 
@@ -733,6 +732,9 @@
      * Static property that defines a prefix for generated getters/setters.
      * When set, all attribute properties will be prefixed (e.g., 'attr_name' instead of 'name').
      * Useful for avoiding naming conflicts or creating a consistent property naming convention.
+     * @static
+     * @memberof module:Model
+     * @name attributePrefix
      * @type {string}
      * @default ''
      * @example
@@ -778,7 +780,7 @@
      * @property {object|Function} events Object in the format `{'event selector' : 'listener'}`. It will be used to bind delegated event listeners to the root element. If it is a function, it will be called to get the events object, bound to the view instance. See {@link module_view_delegateevents View.delegateEvents}.
      * @property {object} model A model or any object containing data and business logic.
      * @property {Function} template A function that returns a string with the view's inner HTML. See {@link module_view__render View.render}. 
-     * @property {number} uid Unique identifier for the view instance. This can be used to generate unique IDs for elements within the view. It is automatically generated and should not be set manually.
+     * @property {string} uid Unique identifier for the view instance. This can be used to generate unique IDs for elements within the view. It is automatically generated and should not be set manually.
      * @example
      * import { View, Model } from 'rasti';
      * 
@@ -1031,12 +1033,17 @@
             if (this.delegatedEventListeners.length) this.undelegateEvents();
 
             // Store events by type i.e.: "click", "submit", etc.
-            let eventTypes = {};
+            const eventTypes = {};
 
             Object.keys(events).forEach(key => {
-                const keyParts = key.split(' ');
-                const type = keyParts.shift();
-                const selector = keyParts.join(' ');
+                const match = key.match(/^(\w+)(?:\s+(.+))*$/);
+
+                if (!match) {
+                    const message = `Invalid event format: ${key}`;
+                    throw new Error(createDevelopmentErrorMessage(message) );
+                }
+                // Extract type and selector from the event key.
+                const [,type, selector] = match;
 
                 let listener = events[key];
                 // Listener may be a string representing a method name on the view, or a function.
@@ -1046,32 +1053,30 @@
 
                 if (!eventTypes[type]) eventTypes[type] = [];
 
-                eventTypes[type].push({ selector, listener });
+                eventTypes[type].push([selector, listener]);
             });
 
             Object.keys(eventTypes).forEach(type => {
                 // Listener for the type of event.
                 const typeListener = (event) => {
-                    // Iterate and run every individual listener if the selector matches.
-                    eventTypes[type].forEach(({ selector, listener }) => {
-                        // No selector provided: invoke listener once with root element.
-                        if (!selector) {
-                            listener.call(this, event, this, this.el);
-                            return;
+                    let node = event.target;
+                    // Traverse ancestors until reaching the view root (`this.el`).
+                    while (node) {
+                        if (node.matches) {
+                            // Iterate and run every individual listener if the selector matches.
+                            eventTypes[type].forEach(([selector, listener]) => {
+                                if ((node === this.el && !selector) || (node !== this.el && node.matches(selector))) {
+                                    listener.call(this, event, this, node);
+                                }
+                            });
                         }
-
-                        let node = event.target;
-                        // Traverse ancestors until reaching the view root (`this.el`).
-                        while (node && node !== this.el) {
-                            if (node.matches && node.matches(selector)) {
-                                listener.call(this, event, this, node);
-                            }
-                            node = node.parentElement;
-                        }
-                    });
+                        // Continue traversing ancestors until reaching the view root (`this.el`) or stopping propagation.
+                        node = node === this.el || event.cancelBubble ? null : node.parentElement;
+                    }
                 };
-
-                this.delegatedEventListeners.push({ type, listener : typeListener });
+                // Store the type and listener in the delegated event listeners array.
+                this.delegatedEventListeners.push([type, typeListener]);
+                // Add the event listener to the element.
                 this.el.addEventListener(type, typeListener);
             });
             // Return `this` for chaining.
@@ -1085,7 +1090,7 @@
          * @return {View} Return `this` for chaining.
          */
         undelegateEvents() {
-            this.delegatedEventListeners.forEach(({ type, listener }) => {
+            this.delegatedEventListeners.forEach(([type, listener]) => {
                 this.el.removeEventListener(type, listener);
             });
 
@@ -1160,6 +1165,8 @@
      * For server-side rendering, this counter should be reset to `0` on every request to ensure that the generated 
      * unique IDs match those on the client, enabling seamless hydration of components.  
      * @static
+     * @memberof module:View
+     * @name uid
      * @type {number}
      * @default 0
      */
@@ -1944,15 +1951,12 @@
     const isComponent = (el) => !!(el && el.dataset && el.dataset[Component.DATASET_ELEMENT] && el.dataset[Component.DATASET_ELEMENT].endsWith('-1'));
 
     /**
-     * Check if an element contains a component.
-     * It checks if the element is a component root element or if it contains a component.
+     * Check if an element contains (or is) a dynamic element.
      * @param {Element} el The element to check.
-     * @return {boolean} True if the element contains a component.
+     * @return {boolean} True if the element contains (or is) a dynamic element.
      * @private
      */
-    const containsElement = (el) => !!(
-        el && ((el.dataset && el.dataset[Component.DATASET_ELEMENT]) || (el.querySelector && el.querySelector(`[${Component.ATTRIBUTE_ELEMENT}]`)))
-    );
+    const containsElement = (el) => !!(el && ((el.dataset && el.dataset[Component.DATASET_ELEMENT]) || (el.querySelector && el.querySelector(`[${Component.ATTRIBUTE_ELEMENT}]`))));
 
     /**
      * Generate string with placeholders for interpolated expressions.
@@ -2525,12 +2529,12 @@
                         element.hydrate(this.el);
                     }
                 });
-                // Delegate events.
-                this.delegateEvents();
                 // Get references for interpolation marker comments
                 this.template.interpolations.forEach(interpolation => interpolation.hydrate(this.el));
                 this.children.forEach(child => child.hydrate(this.el));
             }
+            // Delegate events.
+            this.delegateEvents();
             // Call `onHydrate` lifecycle method.
             this.onHydrate.call(this);
             // Return `this` for chaining.
@@ -2693,7 +2697,7 @@
 
         /**
          * Render the component as a string.
-         * Used internally on the render process.
+         * Used internally on the render process.  
          * Use it for server-side rendering or static site generation.
          * @return {string} The rendered component.
          * @example
@@ -2710,10 +2714,10 @@
          * const app = new App();
          * 
          * console.log(app.toString());
-         * // <div data-rasti-el="r1-1"><!--rasti-s-r1-1--><button class="button" data-rasti-el="r2-1">Click me</button><!--rasti-e-r1-1--></div>
+         * // <div data-rst-el="r1-1"><!--rst-s-r1-1--><button class="button" data-rst-el="r2-1">Click me</button><!--rst-e-r1-1--></div>
          * 
          * console.log(`${app}`);
-         * // <div data-rasti-el="r1-1"><!--rasti-s-r1-1--><button class="button" data-rasti-el="r2-1">Click me</button><!--rasti-e-r1-1--></div>
+         * // <div data-rst-el="r1-1"><!--rst-s-r1-1--><button class="button" data-rst-el="r2-1">Click me</button><!--rst-e-r1-1--></div>
          */
         toString() {
             // Normally there won't be any children, but if there are, destroy them.
@@ -2803,7 +2807,7 @@
                 // In this case, where the component updates, it handles children recycling.
                 const addChild = (component) => {
                     let out = component;
-                    let found = null;
+                    let found;
                     // Check if child already exists by key.
                     if (component.key) {
                         found = previousChildren.find(prev => prev.key === component.key);
@@ -2875,10 +2879,10 @@
             } else {
                 // Update elements attributes.
                 this.template.elements.forEach(element => element.update());
-                // If there are pending event types, delegate events again.
-                if (this.eventsManager.hasPendingTypes()) {
-                    this.delegateEvents();
-                }
+            }
+            // If there are pending event types, delegate events again.
+            if (this.eventsManager.hasPendingTypes()) {
+                this.delegateEvents();
             }
             // Call onUpdate lifecycle method.
             this.onUpdate.call(this);
@@ -3283,9 +3287,9 @@
      * // Increment `model.seconds` every second.
      * setInterval(() => model.seconds++, 1000);
      */
-    var Component$1 = Component.create`<div></div>`;
+    var Component_default = Component.create`<div></div>`;
 
-    exports.Component = Component$1;
+    exports.Component = Component_default;
     exports.Emitter = Emitter;
     exports.Model = Model;
     exports.View = View;