rasti 4.0.1 → 4.1.0-alpha.1

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.1/docs/logo-dark.svg">
+        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.1.0-alpha.1/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,28 +182,147 @@ 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.  
+
+## Scaffolding a New Project
+
+The fastest way to start a real-world **Rasti** project is [`create-rasti`](https://github.com/8tentaculos/create-rasti), the official scaffolding tool. It generates a ready-to-use **Rasti** + **Vite** setup with optional server-side rendering, routing, styling, and icon components.
+
+```bash
+# Interactive setup
+npm create rasti
+
+# Non-interactive single-page app
+npm create rasti my-app
+
+# Server-side rendering with routing and Tailwind CSS
+npm create rasti my-app --ssr --router --tailwind
+```
+
+Available options include:
+
+- **Rendering** — Single-page app (default), server-side rendering (`--ssr`), or static pre-rendering (`--static`).
+- **Styling** — Plain CSS (default), Tailwind CSS (`--tailwind`), or CSSFUN with light/dark theme support (`--cssfun`).
+- **Routing** (`--router`) — A small universal router built on `path-to-regexp`.
+- **Icons** (`--icons`) — Generate **Rasti** components from popular SVG icon sets (heroicons, akar-icons, feathericon, pixelarticons, and more).
+
+See the [`create-rasti` repository](https://github.com/8tentaculos/create-rasti) for the full list of templates and options.
 
 ## Example
 
-You can find a sample **TODO application** in the [example folder](https://github.com/8tentaculos/rasti/tree/master/example/todo) of the **Rasti** [GitHub repository](https://github.com/8tentaculos/rasti). This example serves as a great starting point for your own projects. Try it live [here](https://rasti.js.org/example/todo/index.html).
+To see how **Rasti**'s API and architecture come together in a small app, explore the sample **TODO application** in the [example folder](https://github.com/8tentaculos/rasti/tree/master/example/todo) of the **Rasti** [GitHub repository](https://github.com/8tentaculos/rasti). It's a concise, self-contained reference for understanding how models, views, and components fit together in a simple application. Try it live [here](https://rasti.js.org/example/todo/index.html).
+
+To scaffold a real-world project, use [`create-rasti`](#scaffolding-a-new-project).
 
 ## API Documentation
 
 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' }); // ✅
+```
+
+`Component.extend` adds the object members to the instance type. Inside its methods, `this` is the extended component, and lifecycle overrides get their parameters typed automatically:
+
+```ts
+const Counter = Component.create<{ initial: number }>`<div>...</div>`.extend({
+    onCreate() {
+        this.state = new Model({ count: this.props.initial }); // `this` is typed
+    },
+    onChange(model, changed) { // parameters typed automatically
+        if ('count' in changed) this.render();
+    },
+    increment() { this.state.count++; },
+});
+
+Counter.mount({ initial: 0 }, document.body).increment(); // ✅ increment is typed
+```
+
+### 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.
 
-## Version History
+## Changelog
 
-We strive to minimize breaking changes between major versions. However, if you're migrating between major versions, please refer to the release notes below for details on any breaking changes and migration tips.
-
-- **[v4.0.0](https://github.com/8tentaculos/rasti/releases/tag/v4.0.0)**
-- **[v3.0.0](https://github.com/8tentaculos/rasti/releases/tag/v3.0.0)**
-- **[v2.0.0](https://github.com/8tentaculos/rasti/releases/tag/v2.0.0)**
-- **[v1.0.0](https://github.com/8tentaculos/rasti/releases/tag/v1.0.0)**
+Release history and migration notes for major versions are in [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
@@ -209,4 +331,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);