rasti 4.1.0-alpha.0 → 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.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.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>
 
@@ -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,22 @@ 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:
@@ -278,14 +320,9 @@ type S = State<Counter>; // CounterState
 
 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.1",
     "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`.

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';