rasti 4.1.0-alpha.1 → 4.1.0-alpha.3

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.3/docs/logo-dark.svg">
+        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.1.0-alpha.3/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,9 +272,23 @@ 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:
+Type the attributes with `Model<YourAttrs>`. Use **declaration merging** to surface the auto-generated getters/setters as instance properties:
 
 ```ts
 import { Model } from 'rasti';
@@ -289,32 +314,82 @@ t.on('change:completed', (m, value) => value && /* boolean */ console.log('done'
 import {
     EventHandler,
     RenderExpression,
-    Attrs,
-    Props,
-    State,
+    ModelAttrs,
+    ComponentProps,
+    ComponentState,
     ComponentModel,
 } from 'rasti';
 
+// `Counter` (defined above with Component.create) is a *value*. To use the name in
+// type position, alias it once — now `Counter` is both a value and a type:
+type Counter = InstanceType<typeof Counter>;
+
 // Typed event handler with `this` bound to the component
 const onClick: EventHandler<Counter, MouseEvent> = function(ev) {
-    this.props.label;
+    this.props.initial;
 };
 
 // Typed render expression (`(component) => any`)
-const renderLabel: RenderExpression<Counter> = ({ props }) => props.label;
+const renderLabel: RenderExpression<Counter> = ({ props }) => props.initial;
 
 // Extract types from existing classes
-type T = Attrs<Todo>;    // TodoAttrs
-type P = Props<Counter>; // CounterProps
-type S = State<Counter>; // CounterState
+type A = ModelAttrs<Todo>;        // Todo extends Model → already a type, no alias
+type P = ComponentProps<Counter>; // pass the instance; `ComponentProps<typeof Counter>` is `never`
+type S = ComponentState<Counter>;
+```
+
+> Components made with `Component.create` are **values**, not types. To use one as a type — as with `Counter` above — add `type X = InstanceType<typeof X>` next to the definition, or write `InstanceType<typeof X>` inline. A `Model` subclass needs no alias, since `class` already declares both a value and a type.
+
+### Typing template interpolations
+
+Functions inside a template are `any` — rasti can't infer them from the surrounding string. Which type to use depends on how rasti treats the function (quoted attribute or content → run on render; unquoted attribute → passed as-is):
+
+> Under `strict` / `noImplicitAny`, every interpolation callback **must** be annotated — an untyped parameter is an error (TS7031/TS7006), not a silent `any`. In non-strict mode typing is opt-in: annotate where you want safety and leave trivial ones as `any`.
+
+| 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
+// `Home` is a value (made with Component.create), so alias it to use the name as a type:
+const Home = Component.create<{}, { location: string }>`<div></div>`.extend({
+    close() { /* ... */ },
+});
+type Home = InstanceType<typeof Home>;
+
+// 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.3",
     "description": "Modern MVC for building user interfaces",
     "type": "module",
     "main": "lib/index.cjs",

package/types/Component.d.ts

@@ -71,9 +71,9 @@ export type EventHandler<C, E extends Event = Event> = (
 export type RenderExpression<C> = (this: C, component: C) => any;
 
 /** Extracts the props type `P` from a Component subclass. */
-export type Props<C> = C extends Component<infer P, any, any> ? P : never;
+export type ComponentProps<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;
+export type ComponentState<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 :
@@ -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;
 }

package/types/Model.d.ts

@@ -1,7 +1,7 @@
 import Emitter from './Emitter.js';
 
 /** Extracts the attribute type `A` from a Model subclass. */
-export type Attrs<M> = M extends Model<infer A> ? A : never;
+export type ModelAttrs<M> = M extends Model<infer A> ? A : never;
 
 export type ModelEvents<A> =
     & {

package/types/index.d.ts

@@ -1,5 +1,5 @@
 export { default as Emitter, EventMap } from './Emitter.js';
-export { default as Model, ModelEvents, Attrs } from './Model.js';
+export { default as Model, ModelEvents, ModelAttrs } from './Model.js';
 export { default as View, ViewOptions } from './View.js';
 export {
     default as Component,
@@ -9,8 +9,8 @@ export {
     ComponentPartial,
     EventHandler,
     RenderExpression,
-    Props,
-    State,
+    ComponentProps,
+    ComponentState,
     ComponentModel,
     ComponentLifecycle,
     ExtendedComponent,