rasti 4.1.4 → 4.2.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.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">
+        <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.2.1/docs/logo-dark.svg">
+        <img alt="Rasti.js" src="https://cdn.jsdelivr.net/gh/8tentaculos/rasti@v4.2.1/docs/logo.svg" height="120">
     </picture>
 </p>
 
@@ -115,10 +115,11 @@ const Link = Component.create`
 `;
 
 // Create a Navigation component that renders Link components for each route.
+// `html` builds a partial: a sub-template for lists and conditional blocks.
 const Navigation = Component.create`
     <nav>
-        ${({ props, partial }) => props.routes.map(
-            ({ label, href }) => partial`<${Link} href="${href}">${label}</${Link}>`
+        ${({ props, html }) => props.routes.map(
+            ({ label, href }) => html`<${Link} href="${href}">${label}</${Link}>`
         )}
     </nav>
 `;
@@ -376,7 +377,11 @@ 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).
 
-**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.
+**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:
+
+```ts
+${(function() { return this.props.label; }) satisfies RenderExpression<ToggleComponent>}
+```
 
 **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:
 
@@ -397,7 +402,7 @@ interface ListProps { items: string[]; handleSelect: (item: string) => void; }
 
 class ListBase extends Component<ListProps> {
     renderItems() {
-        return this.props.items.map((item) => this.partial`<li>${item}</li>`);
+        return this.props.items.map((item) => this.html`<li>${item}</li>`);
     }
     select(ev: MouseEvent) {
         const li = (ev.target as HTMLElement).closest('li');
@@ -423,6 +428,15 @@ For a function passed to a child, neither helper fits — its type comes from th
 handleChange=${((checked) => model.toggleAll(checked)) satisfies ToggleAllProps['handleChange']}
 ```
 
+A quoted value is the result of a function the parent runs, so what reaches the child is what that function returns. Annotate its return type with the child's prop: that checks the value, and it types the parameters of a callback returned by a thunk, which would otherwise be an implicit `any` (TS7006):
+
+```ts
+// where the child was created with Component.create<HeaderProps>`...`
+handleAddTodo="${({ model }: AppComponent): HeaderProps['handleAddTodo'] => (title) => model!.addTodo(title)}"
+```
+
+`satisfies` on the returned callback does the same, `({ model }: AppComponent) => ((title) => model!.addTodo(title)) satisfies HeaderProps['handleAddTodo']`; the return type keeps the whole contract in the signature.
+
 ### Known limitations
 
 - **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)).

package/dist/rasti.js

@@ -755,19 +755,28 @@
     Model.attributePrefix = '';
 
     /**
-     * Define `key` on `target` as an own data property. Unlike an assignment, it does not go
-     * through an accessor declared on the prototype, so it shadows a getter with no setter
-     * instead of throwing.
-     * @param {object} target Object to define the property on.
+     * Assign an option to `target`. A getter with no setter on the prototype would make the
+     * assignment throw, so in that case `key` is defined as an own data property, which
+     * shadows the getter. Any other accessor receives the value through its setter.
+     * @param {object} target Object to assign the option to.
      * @param {string} key Property name.
      * @param {any} value Property value.
      * @return {object} The target object.
      * @module
      * @private
      */
-    const defineOwn = (target, key, value) => Object.defineProperty(target, key, {
-        value, writable : true, enumerable : true, configurable : true
-    });
+    const assignOption = (target, key, value) => {
+        try {
+            target[key] = value;
+        } catch (error) {
+            // Assigning to a getter with no setter throws a TypeError; anything else propagates.
+            if (!(error instanceof TypeError)) throw error;
+            Object.defineProperty(target, key, {
+                value, writable : true, enumerable : true, configurable : true
+            });
+        }
+        return target;
+    };
 
     /*
      * These option keys will be extended on the view instance.
@@ -838,11 +847,11 @@
             // Mutable array to store handlers to be called on destroy.
             this.destroyQueue = [];
             this.viewOptions = [];
-            // Extend "this" with options, as own properties so an option overrides
-            // a getter declared by a subclass instead of being assigned through it.
+            // Extend "this" with options. An option overrides a getter declared by a
+            // subclass even when the getter has no setter.
             viewOptions.forEach(key => {
                 if (key in options) {
-                    defineOwn(this, key, options[key]);
+                    assignOption(this, key, options[key]);
                     this.viewOptions.push(key);
                 }
             });
@@ -2424,11 +2433,11 @@
         constructor(options = {}) {
             super(...arguments);
             this.componentOptions = [];
-            // Extend "this" with options, as own properties so an option overrides
-            // a getter declared by a subclass instead of being assigned through it.
+            // Extend "this" with options. An option overrides a getter declared by a
+            // subclass even when the getter has no setter.
             componentOptions.forEach(key => {
                 if (key in options) {
-                    defineOwn(this, key, options[key]);
+                    assignOption(this, key, options[key]);
                     this.componentOptions.push(key);
                 }
             });
@@ -2445,6 +2454,8 @@
             this.options = options;
             // Bind `partial` method to `this`.
             this.partial = this.partial.bind(this);
+            // Expose `partial` as `html`, unless a subclass defines its own `html`.
+            if (!('html' in this)) this.html = this.partial;
             // Bind `onChange` method to `this`.
             this.onChange = this.onChange.bind(this);
             // Call lifecycle method.
@@ -2637,7 +2648,7 @@
          * It will return a Partial object that preserves structure for position-based recycling.
          * Components will be added as children by the parent component. Template strings literals 
          * will be marked as safe HTML to be rendered.
-         * This method is bound to the component instance by default.
+         * This method is bound to the component instance by default, and is also available as `this.html`.
          * @param {TemplateStringsArray} strings - Template strings.
          * @param  {...any} expressions - Template expressions.
          * @return {Partial} Partial object containing strings and expressions.
@@ -3192,8 +3203,8 @@
          *   // Create a navigation component. Add buttons as children. Iterate over items.
          *   const Navigation = Component.create`
          *       <nav>
-         *           ${({ props, partial }) => props.items.map(
-         *               item => partial`<${Button}>${item.label}</${Button}>`
+         *           ${({ props, html }) => props.items.map(
+         *               item => html`<${Button}>${item.label}</${Button}>`
          *           )}
          *       </nav>
          *   `;
@@ -3226,7 +3237,7 @@
          *   ```javascript
          *   class ListBase extends Component {
          *       renderItems() {
-         *           return this.props.items.map(item => this.partial`<li>${item}</li>`);
+         *           return this.props.items.map(item => this.html`<li>${item}</li>`);
          *       }
          *   }
          *   const List = ListBase.create`
@@ -3325,6 +3336,7 @@
      * @property {Model} [model] A `Model` or any emitter object containing data and business logic. The component will listen to `change` events and call `onChange` lifecycle method.
      * @property {Model} [state] A `Model` or any emitter object containing data and business logic, to be used as internal state. The component will listen to `change` events and call `onChange` lifecycle method.
      * @property {Model} [props] Automatically created from any options not merged to the component instance. Contains props passed from parent component as a `Model`. The component will listen to `change` events on props and call `onChange` lifecycle method. When a component with a `key` is recycled during parent re-render, new props are automatically updated and any changes trigger a re-render.
+     * @property {Function} html Alias of {@link #module_component__partial partial}, bound to the component instance. Not set when a subclass defines its own `html`.
      * @see {@link #module_component_create Component.create}
      * @example
      * import { Component, Model } from 'rasti';