@@ -151,8 +151,8 @@ async function Fallback({timeout = 1000, children}) {
return children;
}
-async function *Suspense({timeout, fallback, children}) {
- for await ({timeout, fallback, children} of this) {
+async function *Suspense({timeout, fallback, children}, ctx) {
+ for await ({timeout, fallback, children} of ctx) {
yield
{fallback} ;
yield
{children} ;
}
diff --git a/website/documents/guides/06-special-props-and-tags.md b/website/documents/guides/06-special-props-and-tags.md
index 05823e65..459b5263 100644
--- a/website/documents/guides/06-special-props-and-tags.md
+++ b/website/documents/guides/06-special-props-and-tags.md
@@ -5,10 +5,10 @@ title: Special Props and Tags
Crank provides certain APIs in the form of special props or element tags. The following is an overview of these props and tags.
## Special Props
-The following props apply to all elements, regardless of tag or renderer.
+The following prop names have special behavior. They are not passed to host elements and should not be used to define component props.
-### crank-key
-By default, Crank uses an element’s tag and position to determine if it represents an update or a change to the tree. Because elements often represent stateful DOM nodes or components, it can be useful to *key* the children of an element to hint to the renderer that an element has been added, moved or removed from a parent. In Crank, we do this with the special prop `crank-key`:
+### key
+By default, Crank uses an element’s tag and position to determine if it represents an update or a change to the tree. Because elements often represent stateful DOM nodes or components, it can be useful to *key* the children of an element to hint to the renderer that an element has been added, moved or removed from a parent. In Crank, we do this with the special prop `key`:
```jsx live
import {createElement} from "https://unpkg.com/@b9g/crank/crank";
@@ -28,23 +28,24 @@ function *List() {
reversed = !reversed;
this.refresh();
};
+
for ({} of this) {
yield (
{
reversed ? (
<>
-
-
-
-
+
+
+
+
) : (
<>
-
-
-
-
+
+
+
+
)
}
@@ -57,7 +58,7 @@ function *List() {
renderer.render(
, document.body);
```
-Keys are scoped to an element’s children, and can be any JavaScript value. When rendering iterables, it’s useful to key elements of the iterable, because it’s common for the values of rendered iterables to added, moved or removed.
+All elements in the element tree can be keyed. They are scoped to siblings, and can be any JavaScript value. The most common use-case is when rendering iterables, as the iterable can be rearranged.
```jsx live
import {createElement} from "https://unpkg.com/@b9g/crank/crank";
@@ -65,8 +66,8 @@ import {renderer} from "https://unpkg.com/@b9g/crank/dom";
function *Shuffler() {
let nextId = 0;
- const els = Array.from({length: 4}, (_, i) =>
{i} );
- while (true) {
+ const els = Array.from({length: 4}, (_, i) =>
{i} );
+ for ({} of this) {
yield
{els}
;
els.reverse();
}
@@ -90,14 +91,11 @@ console.log(document.body.innerHTML);
console.log(document.firstChild.firstChild === span); // true
```
-All elements in the element tree can be keyed. If the element is a component element, the `crank-key` prop is erased from the props object passed to the component.
-
-### crank-ref
-Sometimes, you may want to access the rendered value of a specific element in the element tree. To do this, you can pass a callback as the `crank-ref` prop. This callback is called with the rendered value of the element when the element has committed.
+### ref
+Sometimes, you may want to access the rendered value of a specific element in the element tree. To do this, you can pass a callback as the `ref` prop. This callback is called with the rendered value of the element when the element has committed.
```jsx live
-import {createElement} from "https://unpkg.com/@b9g/crank/crank";
-import {renderer} from "https://unpkg.com/@b9g/crank/dom";
+import {renderer} from "@b9g/crank";
function *MyPlayer() {
let audio;
@@ -108,7 +106,7 @@ function *MyPlayer() {
(audio = el)}
+ ref={(el) => (audio = el)}
/>
);
@@ -118,14 +116,62 @@ function *MyPlayer() {
renderer.render(
, document.body);
```
-Refs can be attached to any element in the element tree, and the value passed to the callback will vary according the type of the element and the specific renderer.
+Ref callbacks fire once the first time a host element is rendered. They do not work on fragment elements. For component elements, the `ref` prop must be explicitly passed to a component's child. This is useful when writing elements which wrap a host element.
+
+```jsx
+function MyInput({ref, class, ...props}) {
+ return
+}
+```
+
+### copy
+
+The `copy` prop is used to prevent the re-rendering of any element and its children. A truthy value indicates that the element should not re-render. It can be used to prevent rendering, or for performance reasons.
+
+```jsx
+function* List({elements}) {
+ for ({elements} of this) {
+ yield (
+
+ {elements.map((el) => {
+ // The copy prop will prevent non-initial renders from updating the DOM.
+ return (
+
+ {el.value}
+
+ );;
+ })}
+
+ );
+ }
+}
+```
### children
-The `children` prop passed to components is special because it is not usually set with JSX’s `key="value"` prop syntax, but by the contents between the opening and closing tags. Crank places no limitations on the types of values that can be passed into components as children, but patterns like [render props](https://reactjs.org/docs/render-props.html) from the React community, where a callback is passed as the child of a component, should be avoided.
+The `children` prop passed to components is special because it is not usually set with JSX’s `key="value"` prop syntax, but by the contents between the opening and closing tags. It is the responsibility of the component to make sure the `children` passed in are rendered in its yielded or returned element tree.
-The actual type of the `children` prop will vary according to the number of children passed in. If a component element has no children (`
`), the `children` prop will be undefined, if it has one child (`
`), the `children` prop will be set to that child, and if it has multiple children (`
`), the `children` prop will be set to an array of those children. We do this to reduce runtime memory costs. All props have to be retained between renders, and most elements contain only zero or one child, so avoiding the allocation of an extra array for every element in the tree can noticeably reduce memory requirements.
+```jsx
+function Component({children}) {
+ console.log(children);
+ return (
+
{children}
+ );
+}
+
+renderer.render(
Hello world , document.body);
+// logs "Hello world"
+
+renderer.render(
+
+ 1
+ 2
+ 3
+ ,
+ document.body,
+);
+// logs an array of virtual elements representing the child divs.
+```
-Therefore, the `children` prop should be treated as a black box, only to be rendered somewhere within a component’s returned or yielded children. Attempting to iterate over or manipulate the passed in children of a component is an anti-pattern, and you should use [event dispatch](./handling-events#dispatching-events) or [provisions](./reusable-logic#provisions) to coordinate ancestor and descendant components.
## Special DOM Props
@@ -195,7 +241,7 @@ function equals(props, newProps) {
}
function memo(Component) {
- return function *Wrapped({props}) {
+ return function *Wrapped(props) {
yield
;
for (const newProps of this) {
if (equals(props, newProps)) {
@@ -210,7 +256,7 @@ function memo(Component) {
}
```
-In this example, `memo` is a higher-order component, a function which takes a component and returns a component. This wrapper component compares old and new props and yields a `Copy` element if every prop is shallowly equal. A `Copy` element can appear anywhere in an element tree to prevent rerenderings, and the only props `Copy` elements take are the `crank-key` and `crank-ref` props, which work as expected.
+In this example, `memo` is a higher-order component, a function which takes a component and returns a component. This wrapper component compares old and new props and yields a `Copy` element if every prop is shallowly equal. A `Copy` element can appear anywhere in an element tree to prevent rerenderings, and the only props `Copy` elements take are the `key` and `ref` props, which work as expected.
### Portal
Sometimes you may want to render into a DOM node which isn’t the current parent element, or even a part of the currently rendered DOM tree. You can do this with the `Portal` tag, passing in a DOM node as its `root` prop. The Portal’s children will be rendered into the specified root element, just as if Renderer.render was called with the root value as its second argument.
@@ -258,4 +304,4 @@ function MarkdownViewer({markdown=""}) {
}
```
-Be careful when using `Raw` elements, as passing unsanitized text inputs can lead to security vulnerabilities.
+Be careful when using `
` elements, as passing unsanitized text inputs can lead to security vulnerabilities.
diff --git a/website/documents/guides/07-lifecycles.md b/website/documents/guides/07-lifecycles.md
index 7d70dd1c..849c93be 100644
--- a/website/documents/guides/07-lifecycles.md
+++ b/website/documents/guides/07-lifecycles.md
@@ -2,178 +2,232 @@
title: Lifecycles
---
-Crank uses generator functions rather than hooks or classes to define component lifecycles. Internally, this is achieved by calling the `next`, `return` and `throw` methods of the returned generator object as components are mounted, updated and unmounted from the element tree. As a developer, you can use the `yield`, `return`, `try`, `catch`, and `finally` keywords within your generator components to take full advantage of the generator’s natural lifecycle.
+Crank uses generator functions to define component lifecycles. Internally, this is achieved by calling the [`next()`, `return()` and `throw()` methods of generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator#instance_methods) returned from components. As a developer, this means you can use standard JavaScript control flow to execute code during the lifecycle of a component. For parts of the lifecycle which cannot be placed in the generator body itself, Crank provides the lifecycle methods `schedule()`, `flush()` and `cleanup()` on the context.
+
+## Setup, update and teardown logic
+
+The execution of Crank components is well-defined and well-behaved, so there are no restrictions around where you need to place side-effects. This means much of setup, update and teardown logic can be placed directly in components.
+
+```jsx live
+import {renderer} from "@b9g/crank/dom";
+
+function *Blinker({seconds}) {
+ // setup logic can go at the top of the scope
+ let blinking = false;
+ const blink = async () => {
+ blinking = true;
+ this.refresh();
+ await new Promise((r) => setTimeout(r, 100));
+ blinking = false;
+ this.refresh();
+ };
+
+ let interval = setInterval(blink, seconds * 1000);
+ let oldSeconds = seconds;
+
+ for ({seconds} of this) {
+ // update logic can go directly in the loop
+ if (seconds !== oldSeconds) {
+ blinking = false;
+ clearInterval(interval);
+ interval = setInterval(blink, seconds * 1000);
+ oldSeconds = seconds;
+ }
-## Returning Values
+ console.log(blinking);
-In most generator components, you will yield children within a loop so that they can continue to respond to updates. However, you may also want to return a final state. Unlike function components, which are called and returned once for each update, once a generator component returns, its rendered value is final, and the component will never update again.
+ yield (
+
+ {blinking && "!!!"}
+
+ );
+ }
-```jsx
-function *Stuck({message}) {
- return {message}
;
+ // cleanup logic can go at the end of the loop
+ clearInterval(interval);
}
-renderer.render(Hello
"
-renderer.render(Hello
"
-renderer.render(Hello
"
+function *App() {
+ let seconds = 1;
+ const onChange = (ev) => {
+ seconds = ev.target.value;
+ this.refresh();
+ };
+
+ for ({} of this) {
+ yield (
+
+ Seconds: {" "}
+
+ );
+ }
+}
+
+renderer.render(
;
+ // logic which manipulates the div can go here.
+ div.innerHTML = props.innerHTML;
+ }
}
-
-renderer.render(Click me ;
+ // Any code below the yield will not run until the next render.
}
}
-
-renderer.render(Error: {err.message}
;
+function *Component(this, props) {
+ for await (props of this) {
+ this.schedule((div) => {
+ // the div is
+ div.innerHTML = props.innerHTML;
+ });
+ yield
;
}
}
-
-renderer.render(Error: Hmmm
"
-renderer.render(Error: Hmmm
"
```
-As explained previously, this component “sticks” because it uses a return statement, so that the same error message is shown until the component is unmounted. However, you may also want to recover from errors as well, and you can do this by ignoring or handling the error.
+On the other hand, the `flush()` method runs after the result is completely rendered and live in the DOM. This is required for DOM methods like the `focus()` method for auto-focusing after render. The reason for the distinction between `schedule()` and `flush()` is that Crank allows rendering to be async, and coordinates async rendering so that the rendering of multiple async siblings happens together, meaning there might be some time before a created DOM node is added to its intended parent.
-```jsx
-function T1000() {
- throw new Error("Die!!!");
+
+```jsx live
+import {renderer} from "@b9g/crank/dom";
+function *AutoFocusingInput(props) {
+ // this.schedule does not work because it fires before the input element is
+ // added to the DOM
+ // this.schedule((input) => input.focus());
+ this.flush((input) => input.focus());
+ for (props of this) {
+ yield Come with me if you want to live
;
- try {
- yield I’ll be back
;
- }
+function *Component() {
+ let initial = true;
+ for ({} of this) {
+ yield (
+
+
+
+ this.refresh()}>Refresh
+
+
Come with me if you want to live
"
-renderer.render(I’ll be back
"
-renderer.render(Come with me if you want to live
"
-renderer.render(I’ll be back
"
+renderer.render(No errors
;
+}
-```jsx
-function *FocusingInput(props) {
- for (props of this) {
- const input = yield
+ this.refresh()}>Rerender
+
+ );
+ } catch (err) {
+ yield (
+
+
Error: {err.message}
+
this.refresh()}>Retry
+
{seconds} second{seconds !== 1 && "s"}
;
}
@@ -69,7 +67,7 @@ function Greeting({name = "World"}) {
return Hello {name}.
;
}
-function RandomName() {
+function RandomName({}, ctx) {
const names = ["Alice", "Bob", "Carol", "Dave"];
const randomName = names[Math.floor(Math.random() * names.length)];
@@ -78,7 +76,7 @@ function RandomName() {
this.refresh()}>Random name
+ ctx.refresh()}>Random name
*/}
);
@@ -182,14 +180,14 @@ function Greeting({name = "World"}) {
return Hello {name}.
;
}
-function *CyclingName() {
+function *CyclingName({}, ctx) {
const names = ["Alice", "Bob", "Carol", "Dave"];
let i = 0;
while (true) {
yield (
this.refresh()}>Cycle name
+ ctx.refresh()}>Cycle name
)
@@ -207,13 +205,13 @@ Never memoize a callback ever again.
```jsx live
import {renderer} from "@b9g/crank/dom";
-function *Timer() {
+function *Timer({}, ctx) {
let interval = null;
let seconds = 0;
const startInterval = () => {
interval = setInterval(() => {
seconds++;
- this.refresh();
+ ctx.refresh();
}, 1000);
};
@@ -225,18 +223,18 @@ function *Timer() {
interval = null;
}
- this.refresh();
+ ctx.refresh();
};
const resetInterval = () => {
seconds = 0;
clearInterval(interval);
interval = null;
- this.refresh();
+ ctx.refresh();
};
// The this of a Crank component is an iterable of props.
- for ({} of this) {
+ for ({} of ctx) {
// Welcome to the render loop.
// Most generator components should use render loops even if they do not
// use props.
@@ -254,7 +252,7 @@ function *Timer() {
);
}
- // You can even put cleanup code after the loop.
+ // You can place cleanup code after the loop.
clearInterval(interval);
}
@@ -289,7 +287,7 @@ async function Definition({word}) {
);
}
-function *Dictionary() {
+function *Dictionary({}, ctx) {
let word = "";
const onsubmit = (ev) => {
ev.preventDefault();
@@ -297,11 +295,11 @@ function *Dictionary() {
const word1 = formData.get("word");
if (word1.trim()) {
word = word1;
- this.refresh();
+ ctx.refresh();
}
};
- for ({} of this) {
+ for ({} of ctx) {
yield (
<>
, document.body);
```
-Async generator functions let you write components that are both async *and* stateful. Crank uses promises wherever it makes sense, and has a rich async execution model which allows you to do things like racing components to display loading states.
+Async generator functions let you write components that are both async *and* stateful. Crank uses promises wherever they makes sense, and has a rich async execution model which allows you to do things like racing components to display loading states.
```jsx live
import {renderer} from "@b9g/crank/dom";
@@ -366,17 +364,17 @@ function CreditCard({type, expiration, number, owner}) {
);
}
-async function *LoadingCreditCard() {
+async function *LoadingCreditCard({}, ctx) {
await new Promise((r) => setTimeout(r, 1000));
let count = 0;
const interval = setInterval(() => {
count++;
- this.refresh();
+ ctx.refresh();
}, 200);
- this.cleanup(() => clearInterval(interval));
+ ctx.cleanup(() => clearInterval(interval));
- for ({} of this) {
+ for ({} of ctx) {
yield (
this.refresh());
+async function *RandomCreditCard({throttle}, ctx) {
+ setTimeout(() => ctx.refresh());
yield null;
- for await ({throttle} of this) {
+ for await ({throttle} of ctx) {
yield
- this.refresh()}>
+ ctx.refresh()}>
Generate new card
{" "}