rasti 4.1.0-alpha.0 → 4.1.0-alpha.2

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.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">
+        <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.1.0-alpha.2/docs/logo-dark.svg">
+        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.1.0-alpha.2/docs/logo.svg" height="120">
     </picture>
 </p>
 
@@ -184,9 +184,35 @@ Counter.mount({ model }, document.body);
 - **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.  
 
+## 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
 
@@ -219,6 +245,47 @@ const Plain = Component.create`<div></div>`;
 new Plain({ anything: 'goes' }); // ✅
 ```
 
+When a component is used with inner content (`<${Card}>...</${Card}>`), rasti injects a `renderChildren` function into its props at runtime. Declare it in `P` to use it:
+
+```ts
+const Card = Component.create<{ title: string; renderChildren?: () => any }>`
+    <div class="card">
+        <h2>${({ props }) => props.title}</h2>
+        ${({ props }) => props.renderChildren?.()}
+    </div>
+`;
+```
+
+`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
+```
+
+To read attributes off a typed `state` (or `model`) directly, define it as a named `Model` subclass with declaration merging and pass it as the `S` (or `M`) generic — then there are no casts anywhere:
+
+```ts
+class ScoreState extends Model<{ points: number }> {}
+interface ScoreState { points: number } // exposes this.points
+
+class Scoreboard extends Component<{}, ScoreState> {
+    onCreate() {
+        this.state = new ScoreState({ points: 0 });
+        this.state.points++; // ✅ typed, no cast
+    }
+}
+```
+
 ### Models
 
 Type the attributes with `Model<Attrs>`. Use **declaration merging** to surface the auto-generated getters/setters as instance properties:
@@ -267,25 +334,56 @@ type P = Props<Counter>; // CounterProps
 type S = State<Counter>; // CounterState
 ```
 
+### Typing template interpolations
+
+Functions inside a template are `any` — rasti can't infer them from the surrounding string. Typing is **opt-in**: annotate where you want safety, leave the rest as `any`. Which type to use depends on how rasti treats the function (quoted attribute or content → run on render; unquoted attribute → passed as-is):
+
+| Interpolation | What it is | Type to use |
+|---|---|---|
+| Content `${fn}` or quoted attr `attr="${fn}"` | Run on render; `this` and the argument are the component | `RenderExpression<C>` |
+| Unquoted `onX=${fn}` | DOM handler, called `(event, component, matched)` | `EventHandler<C, E>` |
+| Function passed to a child (`handler=${fn}`) | Becomes the child's prop; typed by the child, not this component | the child's prop signature |
+
+Three ways to apply them:
+
+```ts
+// 1. Named const — cleanest for non-trivial handlers
+const onClick: EventHandler<Home, MouseEvent> = function(ev, self) {
+    ev.preventDefault();
+    self.close();
+};
+
+// 2. Inline with `satisfies` — checks + types the params without widening
+${(({ state }) => state.location) satisfies RenderExpression<Home>}
+
+// 3. Bare annotation — lightest, just types the argument
+${({ state }: Home) => state.location}
+```
+
+For a function passed to a child, neither helper fits — its type comes from the child's prop. Type it against that prop's declared type (rasti can't connect the attribute to the child, since both live inside the template string):
+
+```ts
+// where the child was created with Component.create<ToggleAllProps>`...`
+handleChange=${((checked) => model.toggleAll(checked)) satisfies ToggleAllProps['handleChange']}
+```
+
 ### 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) => ...`.
+- **Template interpolation callbacks are `any`**. Functions in `Component.create\`...\`` templates can't be inferred from the surrounding string — type them opt-in (see [Typing template interpolations](#typing-template-interpolations)).
 - **`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`.
+- **`state` / `model` are raw generics, `props` is not**. `this.props` is *always* a `Model` built by rasti, so it's typed `Model<P> & P` (direct access to `P`'s keys). But `state` and `model` can be anything you provide — a Rasti `Model`, a Backbone model, a store, or a plain object — so they stay the raw generic. To read a typed `Model` state/model directly, define it as a named subclass with declaration merging and pass it as the `S`/`M` generic (see the `Scoreboard` example above) — no casts needed.
+- **Weak-type error on narrow props**. If a component's `P` has no required keys and you pass only options not declared in it, TypeScript reports *"has no properties in common"* (weak-type check). Fix: declare those options in `P` — non-reserved options become props at runtime.
+- **Instance fields set in `.extend` hooks need predeclaration**. `.extend` infers the instance type from the object's members only, so a field first assigned in `onCreate` (`this.router = ...`) isn't known. Predeclare it in the object: `router: null as unknown as Router`. For components with many instance fields, `class MyComponent extends Component<P, S>` is usually cleaner than `.extend`.
 
 ## 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
-
-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.
+## Changelog
 
-- **[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
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rasti",
-    "version": "4.1.0-alpha.0",
+    "version": "4.1.0-alpha.2",
     "description": "Modern MVC for building user interfaces",
     "type": "module",
     "main": "lib/index.cjs",

package/types/Component.d.ts

@@ -38,7 +38,7 @@ export interface SafeHTML {
 }
 
 /** A partial template produced by `this.partial` — preserves structure for position-based recycling. */
-export interface Partial {
+export interface ComponentPartial {
     strings: TemplateStringsArray;
     expressions: any[];
 }
@@ -75,7 +75,40 @@ export type Props<C> = C extends Component<infer P, any, any> ? P : never;
 /** Extracts the state type `S` from a Component subclass. */
 export type State<C> = C extends Component<any, infer S, any> ? S : never;
 /** Extracts the model type `M` from a Component / View subclass. */
-export type ComponentModel<C> = C extends Component<any, any, infer M> ? M : never;
+export type ComponentModel<C> =
+    C extends Component<any, any, infer M> ? M :
+    C extends View<infer M> ? M :
+    never;
+
+/**
+ * Lifecycle methods, with their real signatures, made available for contextual typing
+ * inside `Component.extend({ ... })` so overrides don't need parameter annotations.
+ */
+export interface ComponentLifecycle {
+    /** Lifecycle. Called at the end of the constructor. Runs on both client and server. */
+    onCreate?(...args: any[]): void;
+    /** Lifecycle. Called when model/state/props emit `change`. Default: triggers `render`. */
+    onChange?(model: object, changed: Record<string, any>, ...args: any[]): void;
+    /** Lifecycle. Called after the first render hydrates the DOM. Client only. */
+    onHydrate?(): void;
+    /** Lifecycle. Called at the start of `recycle`, before any recycling happens. */
+    onBeforeRecycle?(): void;
+    /** Lifecycle. Called when the component is recycled and its props are updated. */
+    onRecycle?(): void;
+    /** Lifecycle. Called at the start of `render` on update. */
+    onBeforeUpdate?(): void;
+    /** Lifecycle. Called at the end of `render` on update. */
+    onUpdate?(): void;
+    /** Lifecycle. Called when the component is destroyed. */
+    onDestroy?(...args: any[]): void;
+}
+
+/**
+ * Class returned by `Component.extend`: keeps the statics and constructor signature of the
+ * parent class `T`, and adds the members of `O` to the instance type.
+ */
+export type ExtendedComponent<T extends new (...args: any[]) => any, O> =
+    Omit<T, never> & (new (...args: ConstructorParameters<T>) => InstanceType<T> & O);
 
 /**
  * Components are a special kind of `View` designed to be easily composable. Unlike views,
@@ -104,14 +137,23 @@ declare class Component<P = {}, S = any, M = any> extends View<M> {
 
     /**
      * Helper method used to extend a `Component`, creating a subclass.
+     *
+     * The members of `object` are added to the resulting instance type, and `this` inside
+     * its methods is typed as the extended component. Lifecycle overrides (`onCreate`,
+     * `onChange`, ...) get their parameters typed automatically.
+     *
      * @param object Object with methods to add to the subclass, or a function that receives
      * the parent prototype and returns such an object.
      * @return The newly created Component subclass.
      */
-    static extend<T extends new (...args: any[]) => Component<any, any, any>>(
+    static extend<T extends new (...args: any[]) => Component<any, any, any>, O extends object>(
+        this: T,
+        object: (proto: InstanceType<T>) => O & ThisType<InstanceType<T> & O>,
+    ): ExtendedComponent<T, O>;
+    static extend<T extends new (...args: any[]) => Component<any, any, any>, O extends object>(
         this: T,
-        object: object | ((proto: InstanceType<T>) => object),
-    ): T;
+        object: O & ComponentLifecycle & ThisType<InstanceType<T> & O>,
+    ): ExtendedComponent<T, O>;
 
     /**
      * Mount the component into the DOM.
@@ -157,6 +199,12 @@ declare class Component<P = {}, S = any, M = any> extends View<M> {
         ...expressions: any[]
     ): typeof Component<P, S, M>;
 
+    /**
+     * A unique key to identify the component, merged from options.
+     * Components with keys are recycled when the same key is found in the previous render.
+     */
+    key?: string;
+
     /**
      * Props passed from the parent component, stored as a `Model` for reactive updates.
      * Accessible directly (`this.props.foo`) or via `Model` API (`this.props.get('foo')`).
@@ -184,7 +232,7 @@ declare class Component<P = {}, S = any, M = any> extends View<M> {
 
     /**
      * Tagged template helper bound to the component instance.
-     * Returns a `Partial` that preserves structure for position-based recycling.
+     * Returns a `ComponentPartial` that preserves structure for position-based recycling.
      * String literals are marked as safe HTML automatically.
      *
      * @example
@@ -192,7 +240,7 @@ declare class Component<P = {}, S = any, M = any> extends View<M> {
      *     return this.partial`<header><${Title}>${this.model.title}</${Title}></header>`;
      * }
      */
-    partial(strings: TemplateStringsArray, ...expressions: any[]): Partial;
+    partial(strings: TemplateStringsArray, ...expressions: any[]): ComponentPartial;
 
     /**
      * Subscribes to a `change` event on a model or emitter and invokes `onChange`.
@@ -215,7 +263,7 @@ declare class Component<P = {}, S = any, M = any> extends View<M> {
     onCreate(...args: any[]): void;
 
     /** Lifecycle. Called when model/state/props emit `change`. Default: triggers `render`. */
-    onChange(model: object, changed: object, ...args: any[]): void;
+    onChange(model: object, changed: Record<string, any>, ...args: any[]): void;
 
     /** Lifecycle. Called after the first render hydrates the DOM. Client only. */
     onHydrate(): void;

package/types/Emitter.d.ts

@@ -87,7 +87,7 @@ export default class Emitter<E extends EventMap = EventMap> {
      * @example
      * this.listenTo(otherModel, 'change', this.render.bind(this));
      */
-    listenTo(emitter: Emitter<any>, type: string, listener: (...args: any[]) => void): () => void;
+    listenTo<E2 extends EventMap, K extends keyof E2>(emitter: Emitter<E2>, type: K, listener: E2[K]): () => void;
 
     /**
      * Listen to an event of another emitter and remove the listener after it is called.
@@ -97,7 +97,7 @@ export default class Emitter<E extends EventMap = EventMap> {
      * @param listener The listener to call when the event is emitted.
      * @return A function to stop listening to the event.
      */
-    listenToOnce(emitter: Emitter<any>, type: string, listener: (...args: any[]) => void): () => void;
+    listenToOnce<E2 extends EventMap, K extends keyof E2>(emitter: Emitter<E2>, type: K, listener: E2[K]): () => void;
 
     /**
      * Stop listening to events from other emitters.
@@ -107,5 +107,6 @@ export default class Emitter<E extends EventMap = EventMap> {
      * - `stopListening(emitter, type)` - Stops listening to the specified event type from the specified emitter
      * - `stopListening(emitter, type, listener)` - Stops the specific listener for the specific event
      */
-    stopListening(emitter?: Emitter<any>, type?: string, listener?: (...args: any[]) => void): void;
+    stopListening(): void;
+    stopListening<E2 extends EventMap, K extends keyof E2>(emitter: Emitter<E2>, type?: K, listener?: E2[K]): void;
 }

package/types/View.d.ts

@@ -37,6 +37,14 @@ export interface ViewOptions<M = any> {
  * }
  */
 export default class View<M = any> extends Emitter {
+    /**
+     * Counter for generating unique IDs for view instances.
+     * For server-side rendering, reset it to `0` on every request (see `resetUid`) so the
+     * generated IDs match those on the client, enabling seamless hydration of components.
+     * @default 0
+     */
+    static uid: number;
+
     /**
      * Escape HTML entities in a string.
      * Use this method to sanitize user-generated content before inserting it into the DOM.
@@ -74,8 +82,8 @@ export default class View<M = any> extends Emitter {
     /** Child views. Destroyed automatically when the parent is destroyed. */
     children: View[];
 
-    /** Whether `destroy()` has been called on this view. */
-    destroyed: boolean;
+    /** Whether `destroy()` has been called on this view. `undefined` until then. */
+    destroyed?: boolean;
 
     /**
      * Functions run on `destroy()`. Push cleanup callbacks here for external subscriptions
@@ -124,7 +132,7 @@ export default class View<M = any> extends Emitter {
      * Add a view as a child. Children are stored in `this.children` and destroyed when the parent is destroyed.
      * @return The child view for chaining.
      */
-    addChild(child: View): View;
+    addChild<C extends View>(child: C): C;
 
     /** Call `destroy()` on children views. */
     destroyChildren(): void;

package/types/index.d.ts

@@ -6,10 +6,12 @@ export {
     ComponentOptions,
     ComponentReservedOptions,
     SafeHTML,
-    Partial,
+    ComponentPartial,
     EventHandler,
     RenderExpression,
     Props,
     State,
     ComponentModel,
+    ComponentLifecycle,
+    ExtendedComponent,
 } from './Component.js';