@b9g/crank 0.4.3 → 0.5.0-beta.0

package/README.md

@@ -1,55 +1,25 @@
 # Crank.js
-Write JSX-driven components with functions, promises and generators.
+### The most “Just JavaScript” web framework.
 
-Documentation is available at [crank.js.org](https://crank.js.org). Crank.js is in a beta phase, and some APIs may change. To read more about the motivations for this library, you can read the [introductory blog post](https://crank.js.org/blog/introducing-crank).
+Crank.js is a framework where components are defined with *Plain Old JavaScript Functions*. But not just regular functions! Components can also be defined with async functions for working with promises, and generator functions for working with local state.
 
-## Features
-### Declarative
-Crank uses the same JSX syntax and diffing algorithm popularized by React, allowing you to write HTML-like code directly in JavaScript.
+Its API aims to be minimal and transparent. By relying on standard JavaScript control flow operators and data structures, and by making the process of rendering explicit, Crank.js helps developers write durable, bug-free applications with the latest and greatest libraries and APIs.
 
-### Just Functions
-All components in Crank are just functions or generator functions. No classes, hooks, proxies or template languages are needed.
+Rather than forcing developers to work with increasingly convoluted reactive solutions and bespoke templating languages, Crank.js uses the platform. It is a dedication to the web, to the promise of an accessible and inclusive medium for self-expression and commerce, built on the thesis that simpler code is how we’ll push the frontier.
 
-### Promise-friendly
-Crank provides first-class support for promises. You can define components as async functions and race renderings to display fallback UIs.
+## Get Started
 
-### Lightweight
-Crank has no dependencies, and its core is a single file. It currently measures at [5KB minified and gzipped](https://bundlephobia.com/result?p=@b9g/crank).
-
-### Performant
-[According to benchmarks](https://github.com/krausest/js-framework-benchmark), Crank beats React in terms of speed and memory usage, and is currently comparable to Preact or Vue.
-
-### Extensible
-The core renderer can be extended to target alternative environments such as WebGL libraries, terminals, smartphones or smart TVs.
-
-## Installation
-Crank is available on [NPM](https://npmjs.org/@b9g/crank) in the ESModule and CommonJS formats.
+The documentation for Crank.js is available at [crank.js.org](https://crank.js.org). Crank.js is published on NPM under the `@b9g` organization (short for “b*ikeshavin*g”).
 
 ```shell
 $ npm install @b9g/crank
 ```
 
-```jsx
-/** @jsx createElement */
-import {createElement} from "@b9g/crank";
-import {renderer} from "@b9g/crank/dom";
-
-renderer.render(<div id="hello">Hello world</div>, document.body);
-```
+### Key Examples
 
-If your environment does not support ESModules (you may see a message like `SyntaxError: Unexpected token export`), you can import the CommonJS versions of the library under the `cjs` directory.
+#### A Simple Component
 
-```jsx
-/** @jsx createElement */
-import {createElement} from "@b9g/crank/cjs";
-import {renderer} from "@b9g/crank/cjs/dom";
-
-renderer.render(<div id="hello">Hello world</div>, document.body);
-```
-
-## Key Examples
-### A Simple Component
-```jsx
+```jsx live
 /** @jsx createElement */
 import {createElement} from "@b9g/crank";
 import {renderer} from "@b9g/crank/dom";
@@ -63,10 +33,9 @@ function Greeting({name = "World"}) {
 renderer.render(<Greeting />, document.body);
 ```
 
-[Try on CodeSandbox](https://codesandbox.io/s/a-simple-crank-component-mhciu)
+#### A Stateful Component
 
-### A Stateful Component
-```jsx
+```jsx live
 /** @jsx createElement */
 import {createElement} from "@b9g/crank";
 import {renderer} from "@b9g/crank/dom";
@@ -89,10 +58,9 @@ function *Timer() {
 renderer.render(<Timer />, document.body);
 ```
 
-[Try on CodeSandbox](https://codesandbox.io/s/a-stateful-crank-component-hh8zx)
+#### An Async Component
 
-### An Async Component
-```jsx
+```jsx live
 /** @jsx createElement */
 import {createElement} from "@b9g/crank";
 import {renderer} from "@b9g/crank/dom";
@@ -110,10 +78,9 @@ async function QuoteOfTheDay() {
 renderer.render(<QuoteOfTheDay />, document.body);
 ```
 
-[Try on CodeSandbox](https://codesandbox.io/s/an-async-crank-component-ru02q)
-
 ### A Loading Component
-```jsx
+
+```jsx live
 /** @jsx createElement */
 import {createElement, Fragment} from "@b9g/crank";
 import {renderer} from "@b9g/crank/dom";
@@ -167,5 +134,3 @@ function *RandomDogApp() {
 
 renderer.render(<RandomDogApp />, document.body);
 ```
-
-[Try on CodeSandbox](https://codesandbox.io/s/a-loading-crank-component-pci9d)

package/crank.cjs

@@ -108,6 +108,7 @@ class Element {
         this.static_ = static_;
     }
 }
+// See Element interface
 Element.prototype.$$typeof = ElementSymbol;
 function isElement(value) {
     return value != null && value.$$typeof === ElementSymbol;
@@ -130,6 +131,7 @@ function createElement(tag, props, ...children) {
             switch (name) {
                 case "crank-key":
                 case "c-key":
+                case "$key":
                     // We have to make sure we don’t assign null to the key because we
                     // don’t check for null keys in the diffing functions.
                     if (props[name] != null) {
@@ -138,12 +140,14 @@ function createElement(tag, props, ...children) {
                     break;
                 case "crank-ref":
                 case "c-ref":
+                case "$ref":
                     if (typeof props[name] === "function") {
                         ref = props[name];
                     }
                     break;
                 case "crank-static":
                 case "c-static":
+                case "$static":
                     static_ = !!props[name];
                     break;
                 default:
@@ -157,11 +161,27 @@ function createElement(tag, props, ...children) {
     else if (children.length === 1) {
         props1.children = children[0];
     }
+    // string aliases for the special tags
+    // TODO: Does this logic belong here, or in the Element constructor
+    switch (tag) {
+        case "$FRAGMENT":
+            tag = Fragment;
+            break;
+        case "$PORTAL":
+            tag = Portal;
+            break;
+        case "$COPY":
+            tag = Copy;
+            break;
+        case "$RAW":
+            tag = Raw;
+            break;
+    }
     return new Element(tag, props1, key, ref, static_);
 }
-/**
- * Clones a given element, shallowly copying the props object.
- */
+/** A single-letter alias for createElement */
+const c = createElement;
+/** Clones a given element, shallowly copying the props object. */
 function cloneElement(el) {
     if (!isElement(el)) {
         throw new TypeError("Cannot clone non-element");
@@ -735,9 +755,9 @@ const IsDone = 1 << 4;
  *
  * NOTE: This is mainly used to prevent some false positives in component
  * yields or returns undefined warnings. The reason we’re using this versus
- * IsUnmounted is a very troubling jest test (cascades sync generator parent
- * and sync generator child) where synchronous code causes a stack overflow
- * error in a non-deterministic way. Deeply disturbing stuff.
+ * IsUnmounted is a very troubling test (cascades sync generator parent and
+ * sync generator child) where synchronous code causes a stack overflow error
+ * in a non-deterministic way. Deeply disturbing stuff.
  */
 const IsErrored = 1 << 5;
 /**
@@ -958,13 +978,170 @@ class Context {
         provisions.set(key, value);
     }
     addEventListener(type, listener, options) {
-        return addEventListener(this[$ContextImpl], type, listener, options);
+        const impl = this[$ContextImpl];
+        let listeners;
+        if (!isListenerOrListenerObject(listener)) {
+            return;
+        }
+        else {
+            const listeners1 = listenersMap.get(impl);
+            if (listeners1) {
+                listeners = listeners1;
+            }
+            else {
+                listeners = [];
+                listenersMap.set(impl, listeners);
+            }
+        }
+        options = normalizeListenerOptions(options);
+        let callback;
+        if (typeof listener === "object") {
+            callback = () => listener.handleEvent.apply(listener, arguments);
+        }
+        else {
+            callback = listener;
+        }
+        const record = { type, callback, listener, options };
+        if (options.once) {
+            record.callback = function () {
+                const i = listeners.indexOf(record);
+                if (i !== -1) {
+                    listeners.splice(i, 1);
+                }
+                return callback.apply(this, arguments);
+            };
+        }
+        if (listeners.some((record1) => record.type === record1.type &&
+            record.listener === record1.listener &&
+            !record.options.capture === !record1.options.capture)) {
+            return;
+        }
+        listeners.push(record);
+        // TODO: is it possible to separate out the EventTarget delegation logic
+        for (const value of getChildValues(impl.ret)) {
+            if (isEventTarget(value)) {
+                value.addEventListener(record.type, record.callback, record.options);
+            }
+        }
     }
     removeEventListener(type, listener, options) {
-        return removeEventListener(this[$ContextImpl], type, listener, options);
+        const impl = this[$ContextImpl];
+        const listeners = listenersMap.get(impl);
+        if (listeners == null || !isListenerOrListenerObject(listener)) {
+            return;
+        }
+        const options1 = normalizeListenerOptions(options);
+        const i = listeners.findIndex((record) => record.type === type &&
+            record.listener === listener &&
+            !record.options.capture === !options1.capture);
+        if (i === -1) {
+            return;
+        }
+        const record = listeners[i];
+        listeners.splice(i, 1);
+        // TODO: is it possible to separate out the EventTarget delegation logic
+        for (const value of getChildValues(impl.ret)) {
+            if (isEventTarget(value)) {
+                value.removeEventListener(record.type, record.callback, record.options);
+            }
+        }
     }
     dispatchEvent(ev) {
-        return dispatchEvent(this[$ContextImpl], ev);
+        const impl = this[$ContextImpl];
+        const path = [];
+        for (let parent = impl.parent; parent !== undefined; parent = parent.parent) {
+            path.push(parent);
+        }
+        // We patch the stopImmediatePropagation method because ev.cancelBubble
+        // only informs us if stopPropagation was called and there are no
+        // properties which inform us if stopImmediatePropagation was called.
+        let immediateCancelBubble = false;
+        const stopImmediatePropagation = ev.stopImmediatePropagation;
+        setEventProperty(ev, "stopImmediatePropagation", () => {
+            immediateCancelBubble = true;
+            return stopImmediatePropagation.call(ev);
+        });
+        setEventProperty(ev, "target", impl.ctx);
+        // The only possible errors in this block are errors thrown by callbacks,
+        // and dispatchEvent will only log these errors rather than throwing
+        // them. Therefore, we place all code in a try block, log errors in the
+        // catch block, and use an unsafe return statement in the finally block.
+        //
+        // Each early return within the try block returns true because while the
+        // return value is overridden in the finally block, TypeScript
+        // (justifiably) does not recognize the unsafe return statement.
+        //
+        // TODO: Run all callbacks even if one of them errors
+        try {
+            setEventProperty(ev, "eventPhase", CAPTURING_PHASE);
+            for (let i = path.length - 1; i >= 0; i--) {
+                const target = path[i];
+                const listeners = listenersMap.get(target);
+                if (listeners) {
+                    setEventProperty(ev, "currentTarget", target.ctx);
+                    for (const record of listeners) {
+                        if (record.type === ev.type && record.options.capture) {
+                            record.callback.call(target.ctx, ev);
+                            if (immediateCancelBubble) {
+                                return true;
+                            }
+                        }
+                    }
+                }
+                if (ev.cancelBubble) {
+                    return true;
+                }
+            }
+            {
+                const listeners = listenersMap.get(impl);
+                if (listeners) {
+                    setEventProperty(ev, "eventPhase", AT_TARGET);
+                    setEventProperty(ev, "currentTarget", impl.ctx);
+                    for (const record of listeners) {
+                        if (record.type === ev.type) {
+                            record.callback.call(impl.ctx, ev);
+                            if (immediateCancelBubble) {
+                                return true;
+                            }
+                        }
+                    }
+                    if (ev.cancelBubble) {
+                        return true;
+                    }
+                }
+            }
+            if (ev.bubbles) {
+                setEventProperty(ev, "eventPhase", BUBBLING_PHASE);
+                for (let i = 0; i < path.length; i++) {
+                    const target = path[i];
+                    const listeners = listenersMap.get(target);
+                    if (listeners) {
+                        setEventProperty(ev, "currentTarget", target.ctx);
+                        for (const record of listeners) {
+                            if (record.type === ev.type && !record.options.capture) {
+                                record.callback.call(target.ctx, ev);
+                                if (immediateCancelBubble) {
+                                    return true;
+                                }
+                            }
+                        }
+                    }
+                    if (ev.cancelBubble) {
+                        return true;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            // TODO: Use setTimeout to rethrow the error.
+            console.error(err);
+        }
+        finally {
+            setEventProperty(ev, "eventPhase", NONE);
+            setEventProperty(ev, "currentTarget", null);
+            // eslint-disable-next-line no-unsafe-finally
+            return !ev.defaultPrevented;
+        }
     }
 }
 /*** PRIVATE CONTEXT FUNCTIONS ***/
@@ -1365,168 +1542,11 @@ const CAPTURING_PHASE = 1;
 const AT_TARGET = 2;
 const BUBBLING_PHASE = 3;
 const listenersMap = new WeakMap();
-function addEventListener(ctx, type, listener, options) {
-    let listeners;
-    if (listener == null) {
-        return;
-    }
-    else {
-        const listeners1 = listenersMap.get(ctx);
-        if (listeners1) {
-            listeners = listeners1;
-        }
-        else {
-            listeners = [];
-            listenersMap.set(ctx, listeners);
-        }
-    }
-    options = normalizeListenerOptions(options);
-    let callback;
-    if (typeof listener === "object") {
-        callback = () => listener.handleEvent.apply(listener, arguments);
-    }
-    else {
-        callback = listener;
-    }
-    const record = { type, callback, listener, options };
-    if (options.once) {
-        record.callback = function () {
-            const i = listeners.indexOf(record);
-            if (i !== -1) {
-                listeners.splice(i, 1);
-            }
-            return callback.apply(this, arguments);
-        };
-    }
-    if (listeners.some((record1) => record.type === record1.type &&
-        record.listener === record1.listener &&
-        !record.options.capture === !record1.options.capture)) {
-        return;
-    }
-    listeners.push(record);
-    // TODO: is it possible to separate out the EventTarget delegation logic
-    for (const value of getChildValues(ctx.ret)) {
-        if (isEventTarget(value)) {
-            value.addEventListener(record.type, record.callback, record.options);
-        }
-    }
-}
-function removeEventListener(ctx, type, listener, options) {
-    const listeners = listenersMap.get(ctx);
-    if (listener == null || listeners == null) {
-        return;
-    }
-    const options1 = normalizeListenerOptions(options);
-    const i = listeners.findIndex((record) => record.type === type &&
-        record.listener === listener &&
-        !record.options.capture === !options1.capture);
-    if (i === -1) {
-        return;
-    }
-    const record = listeners[i];
-    listeners.splice(i, 1);
-    // TODO: is it possible to separate out the EventTarget delegation logic
-    for (const value of getChildValues(ctx.ret)) {
-        if (isEventTarget(value)) {
-            value.removeEventListener(record.type, record.callback, record.options);
-        }
-    }
-}
-function dispatchEvent(ctx, ev) {
-    const path = [];
-    for (let parent = ctx.parent; parent !== undefined; parent = parent.parent) {
-        path.push(parent);
-    }
-    // We patch the stopImmediatePropagation method because ev.cancelBubble
-    // only informs us if stopPropagation was called and there are no
-    // properties which inform us if stopImmediatePropagation was called.
-    let immediateCancelBubble = false;
-    const stopImmediatePropagation = ev.stopImmediatePropagation;
-    setEventProperty(ev, "stopImmediatePropagation", () => {
-        immediateCancelBubble = true;
-        return stopImmediatePropagation.call(ev);
-    });
-    setEventProperty(ev, "target", ctx.ctx);
-    // The only possible errors in this block are errors thrown by callbacks,
-    // and dispatchEvent will only log these errors rather than throwing
-    // them. Therefore, we place all code in a try block, log errors in the
-    // catch block, and use an unsafe return statement in the finally block.
-    //
-    // Each early return within the try block returns true because while the
-    // return value is overridden in the finally block, TypeScript
-    // (justifiably) does not recognize the unsafe return statement.
-    //
-    // TODO: Run all callbacks even if one of them errors
-    try {
-        setEventProperty(ev, "eventPhase", CAPTURING_PHASE);
-        for (let i = path.length - 1; i >= 0; i--) {
-            const target = path[i];
-            const listeners = listenersMap.get(target);
-            if (listeners) {
-                setEventProperty(ev, "currentTarget", target.ctx);
-                for (const record of listeners) {
-                    if (record.type === ev.type && record.options.capture) {
-                        record.callback.call(target.ctx, ev);
-                        if (immediateCancelBubble) {
-                            return true;
-                        }
-                    }
-                }
-            }
-            if (ev.cancelBubble) {
-                return true;
-            }
-        }
-        {
-            const listeners = listenersMap.get(ctx);
-            if (listeners) {
-                setEventProperty(ev, "eventPhase", AT_TARGET);
-                setEventProperty(ev, "currentTarget", ctx.ctx);
-                for (const record of listeners) {
-                    if (record.type === ev.type) {
-                        record.callback.call(ctx.ctx, ev);
-                        if (immediateCancelBubble) {
-                            return true;
-                        }
-                    }
-                }
-                if (ev.cancelBubble) {
-                    return true;
-                }
-            }
-        }
-        if (ev.bubbles) {
-            setEventProperty(ev, "eventPhase", BUBBLING_PHASE);
-            for (let i = 0; i < path.length; i++) {
-                const target = path[i];
-                const listeners = listenersMap.get(target);
-                if (listeners) {
-                    setEventProperty(ev, "currentTarget", target.ctx);
-                    for (const record of listeners) {
-                        if (record.type === ev.type && !record.options.capture) {
-                            record.callback.call(target.ctx, ev);
-                            if (immediateCancelBubble) {
-                                return true;
-                            }
-                        }
-                    }
-                }
-                if (ev.cancelBubble) {
-                    return true;
-                }
-            }
-        }
-    }
-    catch (err) {
-        // TODO: Use setTimeout to rethrow the error.
-        console.error(err);
-    }
-    finally {
-        setEventProperty(ev, "eventPhase", NONE);
-        setEventProperty(ev, "currentTarget", null);
-        // eslint-disable-next-line no-unsafe-finally
-        return !ev.defaultPrevented;
-    }
+function isListenerOrListenerObject(value) {
+    return (typeof value === "function" ||
+        (value !== null &&
+            typeof value === "object" &&
+            typeof value.handleEvent === "function"));
 }
 function normalizeListenerOptions(options) {
     if (typeof options === "boolean") {
@@ -1645,6 +1665,7 @@ exports.Fragment = Fragment;
 exports.Portal = Portal;
 exports.Raw = Raw;
 exports.Renderer = Renderer;
+exports.c = c;
 exports.cloneElement = cloneElement;
 exports.createElement = createElement;
 exports["default"] = crank;