So far, every component we’ve seen has worked synchronously, and Crank will respect this as an intentional decision by the developer by keeping the entire process of rendering synchronous from start to finish. However, modern JavaScript includes promises and async/await, which allow you to write concurrently executing code as if it were synchronous. To facilitate these features, Crank allows components to be asynchronous functions as well, and we call these components, async function components.
async function IPAddress () {console.log(document.body.innerHTML); // <div>Your IP Address: 127.0.0.1</div>})();
When Crank renders an async component anywhere in the tree, the entire process becomes asynchronous. Concretely, this means that renderer.render or this.refresh calls return a promise which fulfills when rendering has finished. It also means that no actual DOM updates will be triggered until this moment.
Because async function components can be rerendered while they are still pending, Crank implements a couple rules to make concurrent updates predictable and performant:
console.log(document.body.innerHTML); // "<div>Run 4</div>"
})();In the preceding example, at no point is there more than one simultaneous call to the Delay component, despite the fact that it is rerendered concurrently for its second through fourth renders. And because these renderings are enqueued, only the second and fourth renderings have any effect. This is because the element is busy with the second render by the time the third and fourth renderings are requested, and then, only the fourth rendering is actually executed because third rendering’s props are obsolete by the time the component is ready to update again. This behavior allows async components to always be kept up-to-date without producing excess calls to the function.
console.log(document.body.innerHTML); // "<div><span>Fast</span></div>"
})();As we’ll see later, this ratcheting effect becomes useful for rendering fallback states for async components.
Just as you can write stateful components with sync generator functions, you can also write stateful async components with async generator functions.
console.log(document.body.innerHTML); //<div>The count is now: 2</div>
})();AsyncLabeledCounter is an async version of the LabeledCounter example introduced in the section on props updates. This example demonstrates several key differences between sync and async generator components. Firstly, rather than using while or for…of loops as with sync generator components, we now use a for await…of loop. This is possible because contexts are not just an iterable of props, but also an async iterable of props as well.
Secondly, you’ll notice that the async generator yields multiple times per iteration over this, once to show a loading message and once to show the actual count. While it is possible for sync generators components to yield multiple times per iteration over this, it wouldn’t necessarily make sense to do so because generators suspend at each yield, and upon resuming a second time within the same loop, the props would be stale. In contrast, async generator components are continuously resumed. Rather than suspending at each yield, we rely on the for await…of loop, which suspends at its end until the next update.
The async components we’ve seen so far have been all or nothing, in the sense that Crank can’t show anything until all promises in the tree have fulfilled. This can be a problem when you have an async call which takes longer than expected. It would be nice if parts of the element tree could be shown without waiting, to create responsive user experiences.
However, because loading indicators which show immediately can paradoxically make your app seem less responsive, we use the async rules described previously along with async generator functions to show loading indicators which appear only when certain components take too long.
renderer.render(<RandomDogApp />, document.body);In this example, the RandomDogLoader component is an async generator component which races the LoadingIndicator component with the RandomDog component. Because the async generator component resumes continuously, both components are rendered, and according to the second rule of async components, the loading indicator only shows if the RandomDog component takes longer than the LoadingIndicator component, which fulfills at a fixed interval of one second.
The preceding example hints at how we could abstract this pattern to implement the Suspense component from React.
);
})();No special tags are needed for async loading states, and the functionality to write this logic is implemented using the same element diffing algorithm that governs synchronous components. Additionally, this approach is more flexible in the sense that you can extend it; for instance, you can add another yield to the for await…of loop to show a second fallback state which waits ten seconds, to inform the user that something went wrong or that servers are slow to respond.
No special tags are needed for async loading states, and the functionality to write this logic is implemented using the same element diffing algorithm that governs synchronous components. Additionally, this approach is more flexible in the sense that you can extend it; for instance, you can add another yield to the for await…of loop to show a second fallback state which waits ten seconds, to inform the user that something went wrong or that servers are slow to respond.
TNode is the most important type: it is the type of the node associated with each host element. For instance, for the basic DOM renderer, TNode is the DOM Node interface.
TScope is the type of the scope, a renderer-specific concept for arbitrary data which is passed down the tree between host elements. Scopes are useful for passing contextual information down the tree to be used when nodes are created; for instance, the DOM renderer uses the scope to pass down information about whether we’re currently rendering in an SVG element.
TRoot is the type of the root node. This is the type of the second parameter passed to the Renderer.render method, and the root prop passed to Portal elements. It is usually the same type as TNode but can vary according to renderer requirements.
TResult describes the type of values made visible to renderer consumers. Any time Crank exposes an internal node, for instance, via the crank-ref callback, or as the result of yield expressions in generator components, the renderer can intercept this access and provide something other than the internal nodes, allowing renderers to hide implementation details and provide results which make more sense for a specific environment.
For example, the HTML string renderer has an internal node representation, but converts these nodes to strings before they’re exposed to consumers. This is because the internal nodes must be a referentially unique object which is mutated during rendering, while JavaScript strings are referentially transparent and immutable. Therefore, the TResult type of the HTML renderer is string.
The following is a description of the signatures of internal renderer methods and when they’re executed. When creating a custom renderer, you are expected to override these methods via inheritance.
el: Element<string | symbol>, scope: TScope
): TNode;The create method is called for each host element the first time the element is committed. This method is passed the current host element and scope, and should return the node which will be associated with the host element. This node will remain constant for an element for as long as the element is rendered.
By default, this method will throw a Not Implemented error, so custom renderers should always implement this method.
read(value: Array<TNode | string> | TNode | string | undefined): TResult;
The renderer exposes rendered values in the following places:
render method.refresh method.crank-ref propsschedule and cleanup callbacksvalue getter methodWhen an element or elements are read in this way, we call the read method to give renderers a final chance to manipulate what is exposed, so as to hide internal implementation details and return something which makes sense for the target environment. The parameter passed to the read method can be a node, a string, an array of nodes and strings, or undefined. The return value is what is actually exposed.
This method is optional. By default, read is an identity function which returns the value passed in.
patch(el: Element<string | symbol>, node: TNode): unknown;
The patch method is called for each host element whenever it is committed. This method is passed the current host element and its related node, and its return value is ignored. This method is usually where you would mutate the internal node according to the props of the host element.
Implementation of this method is optional for renderers.
children: Array<TNode | string>,
): unknown;The arrange method is called whenever an element’s children have changed. It is called with the current host element, the host element’s related node, and the rendered values of all the element’s descendants as an array. In addition to when a host element commits, the arrange method may also be called when a child refreshes or otherwise causes a host element’s rendered children to change. Because the arrange method is called for every root/portal element, the parent can be of type TRoot as well as TNode.
This method is where the magic happens, and is where you connect the nodes of your target environment into an internal tree.
scope(el: Element<string | symbol>, scope: TScope | undefined): TScope;
The scope method is called for each host or portal element as elements are mounted or updated. Unlike the other custom renderer methods, the scope method is called during the pre-order traversal of the tree, much as components are. The scope method is passed the current host element and scope as parameters, and the return value becomes the scope argument passed to the create and scope method calls for descendant host elements.
By default, the scope method returns undefined, meaning the scope will be undefined throughout your application.
escape(text: string, scope: TScope): string;
The escape method is called whenever a string is encountered in the element tree. It is mainly useful when creating string-based renderers like an HTML or XML renderer, because most rendering targets like the DOM provide text node interfaces which sanitize inputs by default.
One important detail is that escape should not return text nodes or anything besides a string. We defer this step to the arrange method because this allows the renderer to normalize a host element’s children by concatenating adjacent strings.
By default, the escape method returns the string which was passed in.
parse(text: string, scope: TScope): TNode | string;
When the renderer encounters a Raw element whose value prop is a string, it calls the parse method with that string and the current scope. The return value should be the parsed node, or it can be a string as well, in which case parse will be handled like a string child by parents.
By default, the parse method returns the string which was passed in.
dispose(el: Element<string | symbol>, node: TNode): unknown
The dispose method is called whenever a host element is unmounted. It is called with the host element and its related node. You can use this method to manually release a node or clean up event listeners for garbage collection purposes.
This method is optional and its return value is ignored.
complete(root: TRoot): unknown;
The complete method is called at the end of every render execution, when all elements have been committed and all other renderer methods have been called. It is useful, for instance, if your rendering target needs some final code to execute before any mutations take effect.
This method is optional and its return value is ignored.
The complete method is called at the end of every render execution, when all elements have been committed and all other renderer methods have been called. It is useful, for instance, if your rendering target needs some final code to execute before any mutations take effect.
This method is optional and its return value is ignored.
\ No newline at end of file diff --git a/guides/elements/index.html b/guides/elements/index.html index 91e232f0..7be78027 100644 --- a/guides/elements/index.html +++ b/guides/elements/index.html @@ -1,4 +1,4 @@ -When using this method, you do not have to call the removeEventListener() method if you merely want to remove event listeners when the component is unmounted. This is done automatically.
The context’s addEventListener() method attaches to the top-level node or nodes which each component renders, so if you want to listen to events on a nested node, you must use event delegation.
addEventListener() method attaches to the top-level node or nodes which each component renders, so if you want to listen to events on a nested node, you must use event delegation.While the
removeEventListener()method is implemented, you do not have to call theremoveEventListener()method if you merely want to remove event listeners when the component is unmounted.Because the event listener is attached to the outer
div, we have to filter events byev.target.tagNamein the listener to make sure we’re not incrementingcountbased on clicks which don’t target thebuttonelement.Because the event listener is attached to the outer
div, we have to filter events byev.target.tagNamein the listener to make sure we’re not incrementingcountbased on clicks which don’t target thebuttonelement.Event props vs EventTarget
The props-based event API and the context-based EventTarget API both have their advantages. On the one hand, using event props means you can listen to exactly the element you’d like to listen to.
On the other hand, using the
addEventListenermethod allows you to take full advantage of the EventTarget API, which includes registering passive event listeners, or listeners which are dispatched during the capture phase. Additionally, the EventTarget API can be used without referencing or accessing the child elements which a component renders, meaning you can use it to listen to elements nested in other components.Crank supports both API styles for convenience and flexibility.
Dispatching Events
Crank contexts implement the full EventTarget interface, meaning you can use the
dispatchEventmethod and theCustomEventclass to dispatch custom events to ancestor components:Crank supports both API styles for convenience and flexibility.
Dispatching Events
Crank contexts implement the full EventTarget interface, meaning you can use the
dispatchEventmethod and theCustomEventclass to dispatch custom events to ancestor components:
MyButtonis a function component which wraps abuttonelement. It dispatches aCustomEventwhose type is"mybuttonclick"when it is pressed, and whosedetailproperty contains data about the ID of the clicked button. This event is not triggered on the underlying DOM nodes; instead, it can be listened for by parent component contexts using event capturing and bubbling, and in the example, the event propagates and is handled by theMyAppcomponent. Using custom events and event bubbling allows you to encapsulate state transitions within component hierarchies without the need for complex state management solutions used in other frameworks like Redux or VueX.The preceding example also demonstrates a slight difference in the way the
addEventListenermethod works in function components compared to generator components. With generator components, listeners stick between renders, and will continue to fire until the component is unmounted. However, with function components, because theaddEventListenercall would be invoked every time the component is rerendered, we remove and add listeners for each render. This allows function components to remain stateless while still listening for and dispatching events.Form Elements
Because Crank uses explicit state updates, it doesn’t have a concept of “controlled” vs “uncontrolled” props like
value/defaultValuein React. No refresh means no render.<button>element. It dispatches aCustomEventwhose type is"mybuttonclick"when it is pressed, and whosedetailproperty contains data about the pressed button. This event is not triggered on the underlying DOM nodes; instead, it can be listened for by parent component contexts using event capturing and bubbling, and in the example, the event propagates and is handled by theMyAppcomponent.Using custom events and event bubbling allows you to encapsulate state transitions within component hierarchies without the need for complex state management solutions used in other frameworks like Redux or VueX.
Form Elements
Because Crank uses explicit state updates, it doesn’t have a concept of “controlled” vs “uncontrolled” props like
value/defaultValuein React. No update means the value is uncontrolled.import {renderer} from "@b9g/crank/dom";function *App() {function *Form() {let reset = true;let reset = false;this.addEventListener("click", ev => {const onreset = () => {if (ev.target.tagName === "BUTTON") {reset = true;reset = true;this.refresh();this.refresh();};}});const onsubmit = (ev) => {ev.preventDefault();for ({} of this) {};yield (<div>for ({} of this) {<input type="text" value="" />yield (<p><form onsubmit={onsubmit}><button>Reset</button><input type="text" value="" /></p><p></div><button onclick={onreset}>Reset</button>);</p></form>reset = false;);}renderer.render(<App />, document.body);Loading...You can use the
$staticprop to prevent an element from updating.\ No newline at end of file diff --git a/guides/lifecycles/index.html b/guides/lifecycles/index.html index 330b2e44..053593f3 100644 --- a/guides/lifecycles/index.html +++ b/guides/lifecycles/index.html @@ -1,4 +1,4 @@ -If your component is updating for other reasons, you can use the special property
$staticto prevent the input element from updating.\ No newline at end of file diff --git a/guides/jsx-template-tag/index.html b/guides/jsx-template-tag/index.html index bbcdebd8..84fd00d7 100644 --- a/guides/jsx-template-tag/index.html +++ b/guides/jsx-template-tag/index.html @@ -1,4 +1,4 @@ -import {renderer} from "@b9g/crank/dom";function *Loading...Crank.js | JSX Template Tag A Crank application as a single HTML file. No transpilation required.
Installation
The JSX tag function can be imported from the module
@b9g/crank/standalone. This module exports everything from the root@b9g/crankmodule as well as thejsxtag function, which is defined in the module@b9g/crank/jsx-tag.// console.log(jsx === jsx1);Loading...In the future, we may use environment detection to automatically exports the correct
renderer, which would make thestandalonemodule truly “standalone.”JSX Syntax
The JSX template tag function is designed to replicate as much of JSX syntax and semantics as possible.
Just like JSX syntax, the template version supports components, but they must be explicitly interpolated.
const syntaxEl = <Component />;const templateEl = jsx`<${Component} />`;Component closing tags can be done in one of three styles:
import {jsx} from "@b9g/crank/standalone";Crank.js | Lifecycles You should be careful when writing generator components to make sure that you always place your
yieldoperators in afororwhileloop. If you forget and implicitly return from the generator, it will stop updating and nothing will be rendered ever again.renderer.render(<Numbers />, document.body);console.log(document.body.innerHTML); // ""Cleaning Up
When a generator component is removed from the tree, Crank calls the
returnmethod on the component’s generator object. You can think of it as whateveryieldexpression your component was suspended on being replaced by areturnstatement. This means any loops your component was in when the generator suspended are broken out of, and code after the yield does not execute.You can take advantage of this behavior by wrapping your
yieldloops in atry/finallyblock to release any resources that your component may have used.// "finally block executed"console.log(document.body); // ""The same best practices which apply to
try/finallystatements in regular functions apply to generator components. In short, you should not yield or return anything in thefinallyblock. Crank will not use the yielded or returned values and doing so might cause your components to inadvertently swallow errors or suspend in unexpected locations.Catching Errors
We all make mistakes, and it can be useful to catch errors thrown by our components so that we can show the user something or notify error-logging services. To facilitate this, Crank will catch errors thrown when rendering child elements and throw them back into parent generator components using the
throwmethod on the component’s generator object. You can think of it as whateveryieldexpression your component was suspended on being replaced with athrowstatement with the error set to whatever was thrown by the component’s children.You can take advantage of this behavior by wrapping your
yieldoperations in atry/catchblock to catch errors caused by children.renderer.render(<Catcher />, document.body);console.log(document.body.innerHTML); // "<div>Error: Hmmm</div>"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.
console.log(document.body.innerHTML);// "<div>I’ll be back</div>"Accessing Rendered Values
Sometimes, declarative rendering is not enough, and you’ll want to access the actual DOM nodes you’ve rendered, to make measurements or call imperative methods like the
focusmethod for form elements, or theplaymethod for media elements. To facilitate this, Crank will pass rendered DOM nodes back into the generator using thenextmethod. This means that as a developer, you can readyieldexpressions to access the actual rendered DOM nodes.}}The
FocusingInputcomponent focuses every time it is rerendered. We use an async generator component here because async generators continuously resume, so theinput.focuscall happens directly after the component is rendered. While we also pass rendered nodes into sync generator components as well, attempting to access them directly after theyieldmay lead to surprising results.}}The problem is that sync generator components suspend at the point of yield expressions and only resume when updated by the parent or by a call to the
refreshmethod. This means that if you were to try to access the rendered value via ayieldexpression, your code would not execute until the moment the component rerenders. You can imagine this as the generator function above suspended exactly before theyieldexpression is assigned to theinputvariable.To solve this problem, Crank provides an additional method on the context called
schedule, which takes a callback and calls it with the rendered value after the component executes.}}The
schedulemethod fires the passed in callback synchronously when component finally renders. However, one unfortunate consequence of using a callback is that we lose the sequential execution of code which makes generator components so elegant and easy to understand. We can recover some of this linearity by using theschedulemethod with therefreshmethod.}}The focusing input now focuses before the children are yielded, but because the same input is yielded, the result is mostly the same. The
schedulemethod is designed to work with therefreshmethod so that sync generator components can schedule multiple rendering passes which work synchronously.The focusing input now focuses before the children are yielded, but because the same input is yielded, the result is mostly the same. The
\ No newline at end of file diff --git a/guides/reference-for-react-developers/index.html b/guides/reference-for-react-developers/index.html index 5d333909..9b34adc3 100644 --- a/guides/reference-for-react-developers/index.html +++ b/guides/reference-for-react-developers/index.html @@ -1,4 +1,4 @@ -schedulemethod is designed to work with therefreshmethod so that sync generator components can schedule multiple rendering passes which work synchronously.Crank.js | Reference for React Developers This example is pseudocode which demonstrates where React’s class methods would be called relative to an async generator component. Refer to the guide on lifecycles for more information on using generator functions.
The following are specific equivalents for React methods.
setState and forceUpdate
Crank uses generator functions and local variables for local state. Refer to the section on stateful components.
Crank is not “reactive” in the same sense as React, in that it does not track your component’s local state and rerender when it detects a change. You can either use the context’s
refreshto manually refresh the component, similar to React’sforceUpdatemethod, or you can use async generator components, which refresh automatically whenever the returned async generator yields.defaultProps
Crank doesn’t have a
defaultPropsimplementation. Instead, you can provide default values when destructuring props. See the guide on default props.componentWillMount and componentDidMount
Setup code for components can be written at the top of generator components. It will not execute until the component is mounted in the tree.
shouldComponentUpdate
As an alternative to React’s
shouldComponentUpdatemethod, you can useCopyelements to prevent the rerendering of a specific subtree. Refer to the description ofCopyelements for more information.getDerivedStateFromProps, componentWillUpdate and getSnapshotBeforeUpdate
Code which compares old and new props or state can be written directly in your components. See the section on prop updates for an example of a component which compares old and new props.
componentDidUpdate
To execute code after rendering, you can use async generator components or the
schedulemethod. See the guide on accessing rendered values for more information.componentWillUnmount
You can use a
try/finallyblock to run code when a component is unmounted. You can also use thecleanupmethod if you’re writing extensions which don’t run in the main execution of the component.componentDidCatch
To catch errors which occur in child components, you can use generator components and wrap
yieldoperations in atry/catchblock. Refer to the relevant guide on catching errors.Hooks
Crank does not implement any APIs similar to React Hooks. The main appeal of hooks for library authors is that you can encapsulate entire APIs in one or two hooks. Refer to the guide on reusable logic for a description of strategies you can use to reuse logic and write library wrappers in Crank.
The following are alternatives to specific hooks.
useState and useReducer
Crank uses generator functions and local variables for local state. Refer to the section on stateful components.
useEffect and useLayoutEffect
Crank does not have any requirements that rendering should be “pure.” In other words, you can trigger side-effects directly while rendering because Crank does not execute components more times than you might expect. Refer to the guide on accessing rendered values for more information on code which executes after rendering.
useMemo and useCallback
Because the execution of generator components is preserved, there is no need to “memoize” or “cache” callbacks or other values. You can simply assign them to a constant variable.
useImperativeHandle
Crank does not have a way to access component instances, and parent components should not access child components directly. A web component wrapper for defining custom elements with imperative APIs is planned.
Suspense and Concurrent Mode
Crank uses async functions and promises for scheduling and coordinating async processes. See the guide on async components for an introduction to async components, as well as a demonstration of how you can implement the
Suspensecomponent directly in user space.PropTypes
Crank is written in TypeScript, and you can add type checking to components by typing the props parameter of the component function. See the guide on TypeScript for detailed instructions on how to type components.
Array Children
Crank does not restrict children in JSX elements to just arrays. You can interpolate ES6 maps, sets or any other iterable into your Crank elements. Additionally, Crank does not warn you if elements in the iterable are unkeyed.
Fragments
The
Fragmentelement works almost exactly as it does in React, except that in Crank you can also use a callback ref to access its contents.React.cloneElement
You can clone elements using the
cloneElementfunction.ReactDOM.createPortal
The
createPortalfunction is replaced by the specialPortalelement, whose behavior and expected props varies according to the target rendering environment. Refer to the guide on thePortalelement for more information.React.memo
See the guide on
Copytags for a demonstration of how you can useCopyelements to implementReact.memoin user space.DOM element props
The following are a list of the differences in props APIs for DOM elements.
className and htmlFor
Crank prefers attribute names rather than the JS property DOM equivalents when these names are mismatched.
<label class="my-label" for="my-id">Label</label>In short, Crank is optimized for easy copy-pasting, which using props like
classNameandhtmlFordoes not encourage. See the section on prop naming conventions for more information.style
The
styleprop can be an object of CSS declarations. However, unlike React, CSS property names match the case of their CSS equivalents, and we do not add units to numbers. Additionally, Crank allows the style prop to be a CSS string as well.<div style="color: red"><span style={{"font-size": "16px"}}>Hello</span></div>Refer to the guide on the style prop for more information.
Event props
Host elements can be listened to using
oneventprops, but the prop name will be all lowercase. Crank also provides anEventTargetAPI for components to add and remove event listeners from the top-level node or nodes of each component. In both cases, Crank does not use a synthetic event system or polyfill events in any way. Refer to the guide on event handling for a longer explanation of event handling in Crank.Controlled and Uncontrolled Props
Crank does not have a concept of controlled or uncontrolled props, and does not provide
defaultValue-style props for DOM elements. See the section on form elements for a detailed description of how Crank handles stateful form elements.dangerouslySetInnerHTML
Host DOM elements accept an
innerHTMLprop; Crank does not provide thedangerouslySetInnerHTML={{__html}}API like React. Alternatively, you can use the specialRawtag to insert HTML strings or even DOM nodes directly into an element tree without a parent. Refer to the sections on theinnerHTMLprop and on theRawtag for more information.Keys
Crank provides keyed rendering via the special
crank-keyprop. The prop was renamed because “key” is a common word and because the prop is not erased from the props object passed into components.Keys work similarly to the way they do in React. The main difference is that Crank does not warn about unkeyed elements which appear in arrays or iterables.
Refs
Crank provides the callback-style ref API from React via the
crank-refprop. Unlike React, all elements can be read using thecrank-refprop, including Fragment elements. See the guide on thecrank-refprop.You can also access rendered values in many other ways. Refer to this section for more information.
React Contexts
Because we refer to the
thiskeyword of components as “the component’s context” (“controller” would have been three more characters), we refer to the equivalent concept of React’s Context API as “provisions” instead. We use the context methodsprovideandconsumeto define provisions between ancestor and descendant components. See the guide on provisions for more information.Refer to the guide on the style prop for more information.
Event props
Host elements can be listened to using
oneventprops, but the prop name will be all lowercase. Crank also provides anEventTargetAPI for components to add and remove event listeners from the top-level node or nodes of each component. In both cases, Crank does not use a synthetic event system or polyfill events in any way. Refer to the guide on event handling for a longer explanation of event handling in Crank.Controlled and Uncontrolled Props
Crank does not have a concept of controlled or uncontrolled props, and does not provide
defaultValue-style props for DOM elements. See the section on form elements for a detailed description of how Crank handles stateful form elements.dangerouslySetInnerHTML
Host DOM elements accept an
innerHTMLprop; Crank does not provide thedangerouslySetInnerHTML={{__html}}API like React. Alternatively, you can use the specialRawtag to insert HTML strings or even DOM nodes directly into an element tree without a parent. Refer to the sections on theinnerHTMLprop and on theRawtag for more information.Keys
Crank provides keyed rendering via the special
crank-keyprop. The prop was renamed because “key” is a common word and because the prop is not erased from the props object passed into components.Keys work similarly to the way they do in React. The main difference is that Crank does not warn about unkeyed elements which appear in arrays or iterables.
Refs
Crank provides the callback-style ref API from React via the
crank-refprop. Unlike React, all elements can be read using thecrank-refprop, including Fragment elements. See the guide on thecrank-refprop.You can also access rendered values in many other ways. Refer to this section for more information.
React Contexts
Because we refer to the
\ No newline at end of file diff --git a/guides/reusable-logic/index.html b/guides/reusable-logic/index.html index aed6f5d4..07e93d05 100644 --- a/guides/reusable-logic/index.html +++ b/guides/reusable-logic/index.html @@ -1,4 +1,4 @@ -thiskeyword of components as “the component’s context” (“controller” would have been three more characters), we refer to the equivalent concept of React’s Context API as “provisions” instead. We use the context methodsprovideandconsumeto define provisions between ancestor and descendant components. See the guide on provisions for more information.Crank.js | Reusable Logic Provisions allow libraries to define components which interact with their descendants without rigidly defined component hierarchies or requiring data to be passed manually between components via props. This makes them useful, for instance, when writing multiple components which communicate with each other, like custom
selectandoptionform elements, or drag-and-drop components.Anything can be passed as a key to the
provideandconsumemethods, so you can use a symbol to ensure that the provision you pass between your components are private and do not collide with provisions set by others.Note: Crank does not link “providers” and “consumers” in any way, and doesn’t automatically refresh consumer components when the
providemethod is called. It’s up to you to ensure consumers update when providers update.context.schedule
You can pass a callback to the
schedulemethod to listen for when the component renders. Callbacks passed toschedulefire synchronously after the component commits, with the rendered value of the component as its only argument. Scheduled callbacks fire once per call and callback function (thinkrequestAnimationFrame, notsetInterval). This means you have to continuously call theschedulemethod for each update if you want to execute some code every time your component commits.context.cleanup
Similarly, you can pass a callback to the
cleanupmethod to listen for when the component unmounts. Callbacks passed tocleanupfire synchronously when the component is unmounted. Each registered callback fires only once. The callback is called with the last rendered value of the component as its only argument.Strategies for Reusing Logic
The following are various patterns you can use to write and reuse logic between components, as well as a description of their tradeoffs. We will be wrapping the global
window.setIntervalfunction in examples to demonstrate each design pattern.Global Context Extensions
You can import and extend the Context class’s prototype to globally extend all contexts in your application.
}}In this example, we define the methods
setIntervalandclearIntervaldirectly theContextprototype. ThesetIntervalandclearIntervalmethods will now be available to all components.Pros:
- Methods are available to every component automatically.
Cons:
- Globally scoped.
- No way to write setup logic.
- No way to respond to props updates.
Global context extensions are useful for creating Crank-specific wrappers around already global or otherwise well-known APIs like
setInterval,requestAnimationFrameorfetch.Context Helper Utilities
As an alternative to global context extensions, you can write utility functions which are passed contexts to scope reusable logic per component. In the following example, instead of defining the
setIntervalmethod globally, we define it locally by passing the context of the component into thecreateSetIntervalfunction.}Pros:
- Locally scoped.
- Explicitly imported and referenced.
- Setup logic can be written directly in the function.
Cons:
- Naming these functions can be difficult.
- No way to respond to props updates.
Context helper utilities are useful when you want to write locally-scoped utilities, and are especially well-suited for use-cases which requires setup logic. Possible use-cases include wrappers around stateful APIs like mutation observers or HTML drag and drop.
Higher-order Components
Because Crank components are just functions, we can write functions which both take components as parameters and return wrapped component functions.
const Counter = interval((props) => <div>Seconds: {props.seconds}</div>);The interval function takes a component function and returns a component which passes the number of seconds as a prop. Additionally, it refreshes the returned component whenever the interval is fired.
Pros:
- Locally scoped.
- Explicitly imported and referenced.
- Able to respond to new props within the returned component.
Cons:
- Naming higher-order functions can be difficult.
- JavaScript doesn’t provide an easy syntax for decorating functions.
- Props passed into the component by the wrapper may clash with the component’s own expected props.
The main advantage of higher-order components is that you can respond to props in your utilities just like you would with a component. Higher-order components are most useful when you need reusable logic which responds to prop updates or sets only well-known props. Possible use-cases include styled component or animation libraries.
Async Iterators
Because components can be written as async generator functions, you can integrate utility functions which return async iterators seamlessly with Crank. Async iterators are a great way to model resources because they define a standard way for releasing resources when they’re no longer needed by returning the iterator.
}}Pros:
- Async iterator utilities are framework-agnostic.
- Uniform way to hold and release resources.
Cons:
- Promises and async iterators can cause race conditions and deadlocks, without any language-level features to help you debug them.
If you use async iterators/generators already, Crank is the perfect framework for your application.
Pros:
- Async iterator utilities are framework-agnostic.
- Uniform way to hold and release resources.
Cons:
- Promises and async iterators can cause race conditions and deadlocks, without any language-level features to help you debug them.
If you use async iterators/generators already, Crank is the perfect framework for your application.
\ No newline at end of file diff --git a/guides/special-props-and-tags/index.html b/guides/special-props-and-tags/index.html index 14b8e26d..a6cb89de 100644 --- a/guides/special-props-and-tags/index.html +++ b/guides/special-props-and-tags/index.html @@ -1,4 +1,4 @@ -Crank.js | Special Props and Tags 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.
console.log(document.firstChild.firstChild === span); // trueLoading...All elements in the element tree can be keyed. If the element is a component element, the
crank-keyprop 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-refprop. This callback is called with the rendered value of the element when the element has committed.renderer.render(<MyPlayer />, document.body);Loading...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.
children
The
childrenprop passed to components is special because it is not usually set with JSX’skey="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 from the React community, where a callback is passed as the child of a component, should be avoided.The actual type of the
childrenprop will vary according to the number of children passed in. If a component element has no children (<Component/>), thechildrenprop will be undefined, if it has one child (<Component><Child/></Component>), thechildrenprop will be set to that child, and if it has multiple children (<Component><Child/><Child/></Component>), thechildrenprop 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.Therefore, the
childrenprop 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 or provisions to coordinate ancestor and descendant components.Special DOM Props
The following props are specific to host elements for the HTML and DOM renderers.
style
The style prop can be used to add inline styles to an element. It can either be a CSS string, in which case it works exactly as it does in HTML, or it can also be an object, in which case CSS properties can be set individually.
<div style="color: red"><span style={{"font-size": "16px"}}>Hello</span></div>Note: Unlike other JSX frameworks, Crank does not camel-case style names or add pixel units to numbers.
innerHTML
The
innerHTMLprop can be used to set the element’s children with an HTML string.Be careful when using the
innerHTMLprop, as passing unsanitized text inputs can lead to security vulnerabilities.As an alternative, you can also use the special
Rawelement tag, which allows to inject raw HTML or even actual DOM nodes into the element tree, without requiring a parent host element.Prop Naming Conventions
Crank strives to make copying and pasting HTML into your components as easy as possible, and to this extent it allows you to use
classandforas props in your elements instead ofclassNameandhtmlFor.<label class="my-label" for="my-id">Label</label>You can still use the
classNameandhtmlForprops as well, but using the former names is preferred. This philosophy also extends to SVG elements, and you can use props likeclip-pathandstroke-widthwithout having to camel case them.Special Tags
Crank provides four element tags which have special meaning to the renderer, and affect element diffing and rendering output in various ways.
Fragment
Crank provides a
Fragmenttag, which allows you to render multiple children into a parent without wrapping them in another DOM node. Under the hood, iterables which appear in the element tree are also implicitly wrapped in aFragmentelement by the renderer.console.log(document.body.innerHTML);// "<div>Sibling 1</div><div>Sibling 2</div>"Copy
It‘s often fine to rerender Crank components, because elements are diffed, persistent between renders, and unnecessary mutations usually avoided. However, you might want to prevent a child from updating when the parent rerenders, perhaps because a certain prop hasn’t changed, because you want to batch updates from the parent, or as a performance optimization. To do this, you can use the
Copytag to indicate to Crank that you don’t want to update a previously rendered element in that same position.};}In this example,
memois a higher-order component, a function which takes a component and returns a component. This wrapper component compares old and new props and yields aCopyelement if every prop is shallowly equal. ACopyelement can appear anywhere in an element tree to prevent rerenderings, and the only propsCopyelements take are thecrank-keyandcrank-refprops, 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
Portaltag, passing in a DOM node as itsrootprop. 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.console.log(root2.innerHTML);// "<div>This div is rendered into root2</div>"This tag is useful for creating modals or tooltips, which usually need to be rendered into separate DOM elements at the bottom of the page for visibility reasons. Events dispatched from a
Portalelement‘s child components via thedispatchEventmethod will still bubble into parent components.Raw
Sometimes, you may want to insert raw HTML or actual DOM nodes directly into the element tree. Crank allows you to do this with the
Rawelement. TheRawelement takes avalueprop which is interpreted by the renderer. For the DOM renderer, ifvalueis an HTML string, the renderer will parse and insert the resulting DOM nodes. If the value is already a DOM node, Crank will insert them in place.);}Be careful when using
Rawelements, as passing unsanitized text inputs can lead to security vulnerabilities.
Be careful when using Raw elements, as passing unsanitized text inputs can lead to security vulnerabilities.
You’ll often want to add a return type to your components. Crank exports custom types to help you type the return types of components:
}
}Element is just the type returned by JSX expressions/createElement. As you can see, you still have to modify the return type of functions based on whether the function is async or a generator. You can also use the type Child which represents any valid value in an element tree.
yield <div>Hello world</div>;
}Anything assignable to Child can be part of the element tree, and almost anything can be assigned to Child.
You can type the props object passed to components. This allows JSX elements which use your component as a tag to be type-checked.
const el = <Greeting name="Brian" />; // compiles
const el1 = <Greeting name={1} />; // throws a type errorThe children prop can be typed using the Children type provided by Crank. The Children type is a broad type which can be Child or arbitrarily nested iterables of Child. TypeScript doesn’t really provide a way to prevent functions from being used as the children prop, but such patterns are strongly discouraged. You should typically treat children as an opaque value only to be interpolated into JSX because its value can be almost anything.
);
}If you dispatch custom events, you may want parent event listeners to be typed with the event you bubbled automatically. To do so, you can use module augmentation to extend the EventMap interface from the global Crank module.
);
}When importing the DOM or HTML renderers, the EventMap will be extended with the GlobalEventHandlersMap interface.
By default, calls to the context’s provide and consume methods will be loosely typed. If you want stricter typings of these methods, you can use module augmentation to extend the ProvisionMap interface from the global Crank module.
return <p>{greeting}, {name}</p>;
}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 race components to display loading states.
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.