rasti 4.1.0-alpha.1 → 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.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">
+        <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>
 
@@ -245,6 +245,17 @@ 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
@@ -261,6 +272,20 @@ const Counter = Component.create<{ initial: number }>`<div>...</div>`.extend({
 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:
@@ -309,12 +334,48 @@ 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
 

package/package.json

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

package/types/Component.d.ts

@@ -263,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;
 }