rasti 4.0.1 → 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.1/docs/logo-dark.svg">
-        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.0.1/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
 
@@ -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';
      * 
@@ -1163,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
      */
@@ -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);