rasti 4.1.3-alpha.1 → 4.1.4

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.3-alpha.1/docs/logo-dark.svg">
-        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.1.3-alpha.1/docs/logo.svg" height="120">
+        <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.1.4/docs/logo-dark.svg">
+        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.1.4/docs/logo.svg" height="120">
     </picture>
 </p>
 
@@ -253,13 +253,13 @@ type CardComponent = Component<CardProps>;
 
 const Card = Component.create<CardProps>`
     <div class="card">
-        <h2>${(({ props }) => props.title) satisfies RenderExpression<CardComponent>}</h2>
-        ${(({ props }) => props.renderChildren?.()) satisfies RenderExpression<CardComponent>}
+        <h2>${({ props }: CardComponent) => props.title}</h2>
+        ${({ props }: CardComponent) => props.renderChildren?.()}
     </div>
 `;
 ```
 
-The interpolations are typed with `satisfies` (see [Typing template interpolations](#typing-template-interpolations)).
+The interpolations are typed by annotating their parameter with the component type (see [Typing template interpolations](#typing-template-interpolations)).
 
 `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:
 
@@ -347,15 +347,15 @@ type S = ComponentState<Counter>;
 
 ### Typing template interpolations
 
-Functions inside a template are `any` — rasti can't infer them from the surrounding string. Type each one inline with `satisfies` and the helper that matches how rasti treats it. `satisfies` types the function's parameters and `this` from the helper, and checks the function against it.
+Functions inside a template are `any` — rasti can't infer them from the surrounding string. How to type one depends on what rasti calls it with, and that depends on where it sits in the template.
 
 > Under `strict` / `noImplicitAny`, an untyped interpolation callback is an error (TS7031/TS7006), not a silent `any`. In non-strict mode typing is opt-in.
 
-| Interpolation | What it is | Type to use |
+| Interpolation | Called with | Type it with |
 |---|---|---|
-| 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 |
+| Content `${fn}` or quoted attr `attr="${fn}"` | The component, as its argument and as `this` | An arrow annotated with the component type: `({ props }: C) => …` |
+| Unquoted `onX=${fn}` | `(event, component, matched)`, with `this` the component | `satisfies EventHandler<C, E>` |
+| Function passed to a child (`handler=${fn}`) | Whatever the child calls it with | `satisfies ChildProps['handler']` |
 
 The component type `C` is `Component<P, S, M>` with the same generics passed to `create`, aliased next to the component. It is not a copy: it is the exact type of the component's instances.
 
@@ -367,7 +367,7 @@ type ToggleComponent = Component<ToggleProps, ToggleState>;
 
 const Toggle = Component.create<ToggleProps, ToggleState>`
     <button onClick=${(function() { this.state!.active = !this.state!.active; }) satisfies EventHandler<ToggleComponent, MouseEvent>}>
-        ${(({ props, state }) => `${props.label}: ${state!.active ? 'on' : 'off'}`) satisfies RenderExpression<ToggleComponent>}
+        ${({ props, state }: ToggleComponent) => `${props.label}: ${state!.active ? 'on' : 'off'}`}
     </button>
 `.extend({
     onCreate() { this.state = new ToggleState({ active: false }); }
@@ -376,10 +376,16 @@ const Toggle = Component.create<ToggleProps, ToggleState>`
 
 Inside its own template, a component can't use `InstanceType<typeof Toggle>`: the type of `Toggle` depends on the template itself, so TypeScript reports a circular reference (TS7022).
 
-In an arrow function, annotating the parameter is a lighter alternative. It types the argument but not `this`, so a `function` still needs `satisfies`:
+**Content and quoted attributes** receive the component as their argument, so annotating the parameter types everything they read. A `function` that reads `this` instead needs `satisfies RenderExpression<C>`, which types `this` as well.
+
+**Unquoted handlers** receive the event first, not the component. An annotated parameter still compiles there, since the template's expressions are `any`, and fails at runtime. `satisfies` checks the function against what rasti passes it:
 
 ```ts
-${({ props, state }: ToggleComponent) => `${props.label}: ${state!.active ? 'on' : 'off'}`}
+// Compiles, but the argument is the MouseEvent: `props` is undefined at runtime.
+onClick=${({ props }: ToggleComponent) => console.log(props.label)}
+
+// Rejected (TS2339): `props` does not exist on `MouseEvent`.
+onClick=${(({ props }) => console.log(props.label)) satisfies EventHandler<ToggleComponent, MouseEvent>}
 ```
 
 #### Templates that call the component's own methods
@@ -401,7 +407,7 @@ class ListBase extends Component<ListProps> {
 
 const List = ListBase.create`
     <ul onClick=${(function(ev) { this.select(ev); }) satisfies EventHandler<ListBase, MouseEvent>}>
-        ${((self) => self.renderItems()) satisfies RenderExpression<ListBase>}
+        ${(self: ListBase) => self.renderItems()}
     </ul>
 `;
 
@@ -419,7 +425,7 @@ handleChange=${((checked) => model.toggleAll(checked)) satisfies ToggleAllProps[
 
 ### Known limitations
 
-- **Template interpolation callbacks are `any`**. Functions in ``Component.create`...` `` templates can't be inferred from the surrounding string — type them with `satisfies` (see [Typing template interpolations](#typing-template-interpolations)).
+- **Template interpolation callbacks are `any`**. Functions in ``Component.create`...` `` templates can't be inferred from the surrounding string — type them by where they sit in the template (see [Typing template interpolations](#typing-template-interpolations)).
 - **A component can't name its own type in its template**. `InstanceType<typeof X>` is circular there (TS7022). Use `Component<P, S, M>` (see [Typing template interpolations](#typing-template-interpolations)), or the class `create` is called on when the template calls its methods (see [Templates that call the component's own methods](#templates-that-call-the-components-own-methods)).
 - **`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).

package/package.json

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

package/types/Component.d.ts

@@ -1,7 +1,12 @@
 import View, { ViewOptions, Resolvable } from './View.js';
 import Model from './Model.js';
 
-export interface ComponentReservedOptions<S = any, M = any> extends ViewOptions<M, Component<any, S, M>> {
+/** `P` types `this` in the hooks. It goes last so `ComponentReservedOptions<S, M>` keeps state and model first. */
+export interface ComponentReservedOptions<
+    S = any,
+    M = any,
+    P = Record<string, any>,
+> extends ViewOptions<M, Component<P, S, M>> {
     /**
      * A unique key to identify the component.
      * Components with keys are recycled when the same key is found in the previous render.
@@ -14,22 +19,22 @@ export interface ComponentReservedOptions<S = any, M = any> extends ViewOptions<
      */
     state?: S;
     /** Lifecycle hook called at the end of the constructor. */
-    onCreate?: (this: Component<any, S, M>, ...args: any[]) => void;
+    onCreate?: (this: Component<P, S, M>, ...args: any[]) => void;
     /** Lifecycle hook called when `model`, `state` or `props` emits `change`. */
-    onChange?: (this: Component<any, S, M>, ...args: any[]) => void;
+    onChange?: (this: Component<P, S, M>, ...args: any[]) => void;
     /** Lifecycle hook called after the first render (client only). */
-    onHydrate?: (this: Component<any, S, M>) => void;
+    onHydrate?: (this: Component<P, S, M>) => void;
     /** Lifecycle hook called at the start of `recycle`, before any recycling happens. */
-    onBeforeRecycle?: (this: Component<any, S, M>) => void;
+    onBeforeRecycle?: (this: Component<P, S, M>) => void;
     /** Lifecycle hook called after the component is recycled and props are updated. */
-    onRecycle?: (this: Component<any, S, M>) => void;
+    onRecycle?: (this: Component<P, S, M>) => void;
     /** Lifecycle hook called at the start of `render` on update. */
-    onBeforeUpdate?: (this: Component<any, S, M>) => void;
+    onBeforeUpdate?: (this: Component<P, S, M>) => void;
     /** Lifecycle hook called at the end of `render` on update. */
-    onUpdate?: (this: Component<any, S, M>) => void;
+    onUpdate?: (this: Component<P, S, M>) => void;
 }
 
-export type ComponentOptions<P = Record<string, any>, S = any, M = any> = P & ComponentReservedOptions<S, M>;
+export type ComponentOptions<P = Record<string, any>, S = any, M = any> = P & ComponentReservedOptions<S, M, P>;
 
 /** Marker type for strings that are safe to inject as HTML without sanitization. */
 export interface SafeHTML {
@@ -185,7 +190,10 @@ declare class Component<P = Record<string, any>, S = any, M = any> extends View<
      * - DOM event handlers via camelCased attributes (`onClick=${handler}`), delegated to the root.
      * - Returning a component instance (or array of them) adds it as a child.
      * - Use `<${Sub}>…</${Sub}>` syntax for child component tags.
-     * - Called on a subclass, the new component extends it, so the template can use its methods.
+     * - Called on a subclass, the new component extends it and the result is that subclass,
+     *   so the template can use its methods. `P`, `S` and `M` type the result when `create`
+     *   is called on `Component`. A subclass does not take them: declare the arguments on
+     *   the class (`class X extends Component<P, S, M>`) and call `X.create`.
      *
      * @example
      * const Button = Component.create`
@@ -200,11 +208,9 @@ declare class Component<P = Record<string, any>, S = any, M = any> extends View<
         strings: string | TemplateStringsArray | ((...args: any[]) => any),
         ...expressions: any[]
     ): T;
-    /**
-     * Creates a component from a template, typing its props, state and model explicitly.
-     * See the overload above for the template syntax.
-     */
+    /** Types props, state and model. Only `Component.create` takes these arguments; see above. */
     static create<P = Record<string, any>, S = any, M = any>(
+        this: typeof Component,
         strings: string | TemplateStringsArray | ((...args: any[]) => any),
         ...expressions: any[]
     ): typeof Component<P, S, M>;