@bikeshaving/crank - npm Package Compare versions

Comparing version 0.4.0-beta.3 to 0.4.0

crank.d.ts

@@ -8,3 +8,4 @@ /**
  *
- * @template TTag - The tag of the element.
+ * @template TTag - The tag associated with the props. Can be a string, symbol
+ * or a component function.
  */
@@ -24,4 +25,4 @@ export declare type TagProps<TTag extends Tag> = TTag extends string ? JSX.IntrinsicElements[TTag] : TTag extends Component<infer TProps> ? TProps : Record<string, unknown>;
  * This tag is just the empty string, and you can use the empty string in
- * createElement calls or transpiler options to avoid having to reference this
- * export directly.
+ * createElement calls or transpiler options directly to avoid having to
+ * reference this export.
  */
@@ -55,3 +56,3 @@ export declare const Fragment = "";
  * If the value prop is a string, Renderer.prototype.parse() will be called on
- * the string and the result will be set to the element’s value.
+ * the string and the result will be set as the element’s value.
  */
@@ -121,3 +122,3 @@ export declare const Raw: any;
      *
-     * Passed in createElement() as the prop "crank-key".
+     * Passed in createElement() as the prop "c-key".
      */
@@ -128,5 +129,11 @@ key: Key;
      *
-     * Passed in createElement() as the prop "crank-ref".
+     * Passed in createElement() as the prop "c-ref".
      */
     ref: ((value: unknown) => unknown) | undefined;
+    /**
+     * A possible boolean which indicates that element should NOT be rerendered.
+     * If the element has never been rendered, this property has no effect.
+     *
+     * Passed in createElement() as the prop "c-static".
+     */
     static_: boolean | undefined;
@@ -162,6 +169,5 @@ }
  * This function is usually used as a transpilation target for JSX transpilers,
- * but it can also be called directly. It additionally extracts the crank-key
- * and crank-ref props so they aren’t accessible to renderer methods or
- * components, and assigns the children prop according to any additional
- * arguments passed to the function.
+ * but it can also be called directly. It additionally extracts special props so
+ * they aren’t accessible to renderer methods or components, and assigns the
+ * children prop according to any additional arguments passed to the function.
  */
@@ -197,9 +203,37 @@ export declare function createElement<TTag extends Tag>(tag: TTag, props?: TagProps<TTag> | null | undefined, ...children: Array<unknown>): Element<TTag>;
 export declare type ElementValue<TNode> = Array<TNode | string> | TNode | string | undefined;
-declare type RetainerChild<TNode> = Retainer<TNode> | string | undefined;
+/**
+ * @internal
+ * The internal nodes which are cached and diffed against new elements when
+ * rendering element trees.
+ */
 declare class Retainer<TNode> {
+    /**
+     * The element associated with this retainer.
+     */
     el: Element;
-    ctx: ContextInternals<TNode> | undefined;
+    /**
+     * The context associated with this element. Will only be defined for
+     * component elements.
+     */
+    ctx: ContextImpl<TNode> | undefined;
+    /**
+     * The retainer children of this element. Retainers form a tree which mirrors
+     * elements. Can be a single child or undefined as a memory optimization.
+     */
     children: Array<RetainerChild<TNode>> | RetainerChild<TNode>;
+    /**
+     * The value associated with this element.
+     */
     value: TNode | string | undefined;
+    /**
+     * The cached child values of this element. Only host and component elements
+     * will use this property.
+     */
     cached: ElementValue<TNode>;
+    /**
+     * The child which this retainer replaces. This property is used when an
+     * async retainer tree replaces previously rendered elements, so that the
+     * previously rendered elements can remain visible until the async tree
+     * fulfills. Will be set to undefined once this subtree fully renders.
+     */
     fallback: RetainerChild<TNode>;
@@ -210,2 +244,6 @@ inflight: Promise<ElementValue<TNode>> | undefined;
 }
+/**
+ * The retainer equivalent of ElementValue
+ */
+declare type RetainerChild<TNode> = Retainer<TNode> | string | undefined;
 export interface RendererImpl<TNode, TScope, TRoot extends TNode = TNode, TResult = ElementValue<TNode>> {
@@ -258,2 +296,3 @@ scope<TTag extends string | symbol>(scope: TScope | undefined, tag: TTag, props: TagProps<TTag>): TScope | undefined;
 }
+declare const $RendererImpl: unique symbol;
 /**
@@ -275,3 +314,3 @@ * An abstract class which is subclassed to render to different target
     cache: WeakMap<object, Retainer<TNode>>;
-    impl: RendererImpl<TNode, TScope, TRoot, TResult>;
+    [$RendererImpl]: RendererImpl<TNode, TScope, TRoot, TResult>;
     constructor(impl: Partial<RendererImpl<TNode, TScope, TRoot, TResult>>);
@@ -305,4 +344,5 @@ /**
  * @internal
+ * The internal class which holds all context data.
  */
-declare class ContextInternals<TNode = unknown, TScope = unknown, TRoot extends TNode = TNode, TResult = unknown> {
+declare class ContextImpl<TNode = unknown, TScope = unknown, TRoot extends TNode = TNode, TResult = unknown> {
     /**
@@ -313,5 +353,5 @@ * flags - A bitmask. See CONTEXT FLAGS above.
     /**
-     * facade - The actual object passed as this to components.
+     * ctx - The actual object passed as this to components.
      */
-    facade: Context<unknown, TResult>;
+    ctx: Context<unknown, TResult>;
     /**
@@ -336,3 +376,3 @@ * renderer - The renderer which created this context.
      */
-    parent: ContextInternals<TNode, TScope, TRoot, TResult> | undefined;
+    parent: ContextImpl<TNode, TScope, TRoot, TResult> | undefined;
     /**
@@ -373,5 +413,5 @@ * scope - The value of the scope at the point of element’s creation.
     onAvailable: Function | undefined;
-    constructor(renderer: RendererImpl<TNode, TScope, TRoot, TResult>, root: TRoot | undefined, host: Retainer<TNode>, parent: ContextInternals<TNode, TScope, TRoot, TResult> | undefined, scope: TScope | undefined, ret: Retainer<TNode>);
+    constructor(renderer: RendererImpl<TNode, TScope, TRoot, TResult>, root: TRoot | undefined, host: Retainer<TNode>, parent: ContextImpl<TNode, TScope, TRoot, TResult> | undefined, scope: TScope | undefined, ret: Retainer<TNode>);
 }
-export declare const $ContextInternals: unique symbol;
+declare const $ContextImpl: unique symbol;
 /**
@@ -393,4 +433,4 @@ * A class which is instantiated and passed to every component as its this
      */
-    [$ContextInternals]: ContextInternals<unknown, unknown, unknown, TResult>;
-    constructor(internals: ContextInternals<unknown, unknown, unknown, TResult>);
+    [$ContextImpl]: ContextImpl<unknown, unknown, unknown, TResult>;
+    constructor(impl: ContextImpl<unknown, unknown, unknown, TResult>);
     /**
@@ -470,3 +510,3 @@ * The current props of the associated element.
     }
-    module JSX {
+    namespace JSX {
         interface IntrinsicElements {
@@ -473,0 +513,0 @@ [tag: string]: any;

crank.js

@@ -45,7 +45,7 @@ /// <reference types="crank.d.ts" />
  * This tag is just the empty string, and you can use the empty string in
- * createElement calls or transpiler options to avoid having to reference this
- * export directly.
+ * createElement calls or transpiler options directly to avoid having to
+ * reference this export.
  */
 const Fragment = "";
-// TODO: We assert the following symbol tags as any because typescript support
+// TODO: We assert the following symbol tags as any because TypeScript support
 // for symbol tags in JSX doesn’t exist yet.
@@ -76,3 +76,3 @@ // https://github.com/microsoft/TypeScript/issues/38367
  * If the value prop is a string, Renderer.prototype.parse() will be called on
- * the string and the result will be set to the element’s value.
+ * the string and the result will be set as the element’s value.
  */
@@ -118,6 +118,5 @@ const Raw = Symbol.for("crank.Raw");
  * This function is usually used as a transpilation target for JSX transpilers,
- * but it can also be called directly. It additionally extracts the crank-key
- * and crank-ref props so they aren’t accessible to renderer methods or
- * components, and assigns the children prop according to any additional
- * arguments passed to the function.
+ * but it can also be called directly. It additionally extracts special props so
+ * they aren’t accessible to renderer methods or components, and assigns the
+ * children prop according to any additional arguments passed to the function.
  */
@@ -130,2 +129,3 @@ function createElement(tag, props, ...children) {
     if (props != null) {
+        // TODO: deprecate crank-whatever props
         for (const name in props) {
@@ -234,2 +234,7 @@ switch (name) {
 }
+/**
+ * @internal
+ * The internal nodes which are cached and diffed against new elements when
+ * rendering element trees.
+ */
 class Retainer {
@@ -303,2 +308,3 @@ constructor(el) {
 };
+const $RendererImpl = Symbol.for("crank.RendererImpl");
 /**
@@ -317,3 +323,3 @@ * An abstract class which is subclassed to render to different target
         this.cache = new WeakMap();
-        this.impl = {
+        this[$RendererImpl] = {
             ...defaultRendererImpl,
@@ -340,3 +346,3 @@ ...impl,
         let ret;
-        const ctx = bridge && bridge[$ContextInternals];
+        const ctx = bridge && bridge[$ContextImpl];
         if (typeof root === "object" && root !== null) {
@@ -364,10 +370,10 @@ ret = this.cache.get(root);
         }
-        const scope = this.impl.scope(undefined, Portal, ret.el.props);
-        const childValues = diffChildren(this.impl, root, ret, ctx, scope, ret, children);
+        const impl = this[$RendererImpl];
+        const childValues = diffChildren(impl, root, ret, ctx, impl.scope(undefined, Portal, ret.el.props), ret, children);
         // We return the child values of the portal because portal elements
         // themselves have no readable value.
         if (isPromiseLike(childValues)) {
-            return childValues.then((childValues) => commitRootRender(this.impl, root, ctx, ret, childValues, oldProps));
+            return childValues.then((childValues) => commitRootRender(impl, root, ctx, ret, childValues, oldProps));
         }
-        return commitRootRender(this.impl, root, ctx, ret, childValues, oldProps);
+        return commitRootRender(impl, root, ctx, ret, childValues, oldProps);
     }
@@ -772,7 +778,8 @@ }
  * @internal
+ * The internal class which holds all context data.
  */
-class ContextInternals {
+class ContextImpl {
     constructor(renderer, root, host, parent, scope, ret) {
         this.f = 0;
-        this.facade = new Context(this);
+        this.ctx = new Context(this);
         this.renderer = renderer;
@@ -792,3 +799,3 @@ this.root = root;
 }
-const $ContextInternals = Symbol.for("crank.ContextInternals");
+const $ContextImpl = Symbol.for("crank.ContextImpl");
 /**
@@ -807,4 +814,4 @@ * A class which is instantiated and passed to every component as its this
 class Context {
-    constructor(internals) {
-        this[$ContextInternals] = internals;
+    constructor(impl) {
+        this[$ContextImpl] = impl;
     }
@@ -819,3 +826,3 @@ /**
     get props() {
-        return this[$ContextInternals].ret.el.props;
+        return this[$ContextImpl].ret.el.props;
     }
@@ -831,15 +838,15 @@ // TODO: Should we rename this???
     get value() {
-        return this[$ContextInternals].renderer.read(getValue(this[$ContextInternals].ret));
+        return this[$ContextImpl].renderer.read(getValue(this[$ContextImpl].ret));
     }
     *[Symbol.iterator]() {
-        const internals = this[$ContextInternals];
-        while (!(internals.f & IsDone)) {
-            if (internals.f & IsIterating) {
+        const impl = this[$ContextImpl];
+        while (!(impl.f & IsDone)) {
+            if (impl.f & IsIterating) {
                 throw new Error("Context iterated twice without a yield");
             }
-            else if (internals.f & IsAsyncGen) {
+            else if (impl.f & IsAsyncGen) {
                 throw new Error("Use for await…of in async generator components");
             }
-            internals.f |= IsIterating;
-            yield internals.ret.el.props;
+            impl.f |= IsIterating;
+            yield impl.ret.el.props;
         }
@@ -851,22 +858,22 @@ }
         // therefore “done” before it starts iterating over the context.
-        const internals = this[$ContextInternals];
+        const impl = this[$ContextImpl];
         do {
-            if (internals.f & IsIterating) {
+            if (impl.f & IsIterating) {
                 throw new Error("Context iterated twice without a yield");
             }
-            else if (internals.f & IsSyncGen) {
+            else if (impl.f & IsSyncGen) {
                 throw new Error("Use for…of in sync generator components");
             }
-            internals.f |= IsIterating;
-            if (internals.f & IsAvailable) {
-                internals.f &= ~IsAvailable;
+            impl.f |= IsIterating;
+            if (impl.f & IsAvailable) {
+                impl.f &= ~IsAvailable;
             }
             else {
-                await new Promise((resolve) => (internals.onAvailable = resolve));
-                if (internals.f & IsDone) {
+                await new Promise((resolve) => (impl.onAvailable = resolve));
+                if (impl.f & IsDone) {
                     break;
                 }
             }
-            yield internals.ret.el.props;
-        } while (!(internals.f & IsDone));
+            yield impl.ret.el.props;
+        } while (!(impl.f & IsDone));
     }
@@ -886,17 +893,17 @@ /**
     refresh() {
-        const internals = this[$ContextInternals];
-        if (internals.f & IsUnmounted) {
+        const impl = this[$ContextImpl];
+        if (impl.f & IsUnmounted) {
             console.error("Component is unmounted");
-            return internals.renderer.read(undefined);
+            return impl.renderer.read(undefined);
         }
-        else if (internals.f & IsExecuting) {
+        else if (impl.f & IsExecuting) {
             console.error("Component is already executing");
             return this.value;
         }
-        resumeCtxIterator(internals);
-        const value = runComponent(internals);
+        resumeCtxIterator(impl);
+        const value = runComponent(impl);
         if (isPromiseLike(value)) {
-            return value.then((value) => internals.renderer.read(value));
+            return value.then((value) => impl.renderer.read(value));
         }
-        return internals.renderer.read(value);
+        return impl.renderer.read(value);
     }
@@ -908,7 +915,7 @@ /**
     schedule(callback) {
-        const internals = this[$ContextInternals];
-        let callbacks = scheduleMap.get(internals);
+        const impl = this[$ContextImpl];
+        let callbacks = scheduleMap.get(impl);
         if (!callbacks) {
             callbacks = new Set();
-            scheduleMap.set(internals, callbacks);
+            scheduleMap.set(impl, callbacks);
         }
@@ -922,15 +929,15 @@ callbacks.add(callback);
     flush(callback) {
-        const internals = this[$ContextInternals];
-        if (typeof internals.root !== "object" || internals.root === null) {
+        const impl = this[$ContextImpl];
+        if (typeof impl.root !== "object" || impl.root === null) {
             return;
         }
-        let flushMap = flushMaps.get(internals.root);
+        let flushMap = flushMaps.get(impl.root);
         if (!flushMap) {
             flushMap = new Map();
-            flushMaps.set(internals.root, flushMap);
+            flushMaps.set(impl.root, flushMap);
         }
-        let callbacks = flushMap.get(internals);
+        let callbacks = flushMap.get(impl);
         if (!callbacks) {
             callbacks = new Set();
-            flushMap.set(internals, callbacks);
+            flushMap.set(impl, callbacks);
         }
@@ -944,7 +951,7 @@ callbacks.add(callback);
     cleanup(callback) {
-        const internals = this[$ContextInternals];
-        let callbacks = cleanupMap.get(internals);
+        const impl = this[$ContextImpl];
+        let callbacks = cleanupMap.get(impl);
         if (!callbacks) {
             callbacks = new Set();
-            cleanupMap.set(internals, callbacks);
+            cleanupMap.set(impl, callbacks);
         }
@@ -954,3 +961,3 @@ callbacks.add(callback);
     consume(key) {
-        for (let parent = this[$ContextInternals].parent; parent !== undefined; parent = parent.parent) {
+        for (let parent = this[$ContextImpl].parent; parent !== undefined; parent = parent.parent) {
             const provisions = provisionMaps.get(parent);
@@ -963,7 +970,7 @@ if (provisions && provisions.has(key)) {
     provide(key, value) {
-        const internals = this[$ContextInternals];
-        let provisions = provisionMaps.get(internals);
+        const impl = this[$ContextImpl];
+        let provisions = provisionMaps.get(impl);
         if (!provisions) {
             provisions = new Map();
-            provisionMaps.set(internals, provisions);
+            provisionMaps.set(impl, provisions);
         }
@@ -973,9 +980,9 @@ provisions.set(key, value);
     addEventListener(type, listener, options) {
-        return addEventListener(this[$ContextInternals], type, listener, options);
+        return addEventListener(this[$ContextImpl], type, listener, options);
     }
     removeEventListener(type, listener, options) {
-        return removeEventListener(this[$ContextInternals], type, listener, options);
+        return removeEventListener(this[$ContextImpl], type, listener, options);
     }
     dispatchEvent(ev) {
-        return dispatchEvent(this[$ContextInternals], ev);
+        return dispatchEvent(this[$ContextImpl], ev);
     }
@@ -1002,3 +1009,3 @@ }
     else {
-        ctx = ret.ctx = new ContextInternals(renderer, root, host, parent, scope, ret);
+        ctx = ret.ctx = new ContextImpl(renderer, root, host, parent, scope, ret);
     }
@@ -1215,3 +1222,3 @@ ctx.f |= IsUpdating;
         try {
-            result = ret.el.tag.call(ctx.facade, ret.el.props);
+            result = ret.el.tag.call(ctx.ctx, ret.el.props);
         }
@@ -1464,3 +1471,3 @@ catch (err) {
     });
-    setEventProperty(ev, "target", ctx.facade);
+    setEventProperty(ev, "target", ctx.ctx);
     // The only possible errors in this block are errors thrown by callbacks,
@@ -1482,6 +1489,6 @@ // and dispatchEvent will only log these errors rather than throwing
             if (listeners) {
-                setEventProperty(ev, "currentTarget", target.facade);
+                setEventProperty(ev, "currentTarget", target.ctx);
                 for (const record of listeners) {
                     if (record.type === ev.type && record.options.capture) {
-                        record.callback.call(target.facade, ev);
+                        record.callback.call(target.ctx, ev);
                         if (immediateCancelBubble) {
@@ -1501,6 +1508,6 @@ return true;
                 setEventProperty(ev, "eventPhase", AT_TARGET);
-                setEventProperty(ev, "currentTarget", ctx.facade);
+                setEventProperty(ev, "currentTarget", ctx.ctx);
                 for (const record of listeners) {
                     if (record.type === ev.type) {
-                        record.callback.call(ctx.facade, ev);
+                        record.callback.call(ctx.ctx, ev);
                         if (immediateCancelBubble) {
@@ -1522,6 +1529,6 @@ return true;
                 if (listeners) {
-                    setEventProperty(ev, "currentTarget", target.facade);
+                    setEventProperty(ev, "currentTarget", target.ctx);
                     for (const record of listeners) {
                         if (record.type === ev.type && !record.options.capture) {
-                            record.callback.call(target.facade, ev);
+                            record.callback.call(target.ctx, ev);
                             if (immediateCancelBubble) {
@@ -1657,3 +1664,3 @@ return true;
 
-export { $ContextInternals, Context, Copy, Element, Fragment, Portal, Raw, Renderer, cloneElement, createElement, isElement };
+export { Context, Copy, Element, Fragment, Portal, Raw, Renderer, cloneElement, createElement, isElement };
 //# sourceMappingURL=crank.js.map

dom.d.ts

@@ -1,2 +0,3 @@
-import { Children, Context, ElementValue, Renderer } from "./crank";
+import { Children, Context, ElementValue, Renderer, RendererImpl } from "./crank";
+export declare const impl: Partial<RendererImpl<Node, string>>;
 export declare class DOMRenderer extends Renderer<Node, string> {
@@ -3,0 +4,0 @@ constructor();

dom.js

 /// <reference types="dom.d.ts" />
-import { Renderer, Portal } from './crank.js';
+import { Portal, Renderer } from './crank.js';
 
@@ -215,3 +215,3 @@ const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
 
-export { DOMRenderer, renderer };
+export { DOMRenderer, impl, renderer };
 //# sourceMappingURL=dom.js.map

html.d.ts

@@ -1,5 +0,6 @@
-import { Renderer } from "./crank";
+import { Renderer, RendererImpl } from "./crank";
 interface Node {
     value: string;
 }
+export declare const impl: Partial<RendererImpl<Node, undefined, any, string>>;
 export declare class HTMLRenderer extends Renderer<Node, undefined, any, string> {
@@ -9,6 +10,2 @@ constructor();
 export declare const renderer: HTMLRenderer;
-/**
- * @deprecated
- */
-export declare const StringRenderer: typeof HTMLRenderer;
 declare global {
@@ -15,0 +12,0 @@ module Crank {

html.js

 /// <reference types="html.d.ts" />
-import { Renderer, Portal } from './crank.js';
+import { Portal, Renderer } from './crank.js';
 
@@ -133,8 +133,4 @@ const voidTags = new Set([
 const renderer = new HTMLRenderer();
-/**
- * @deprecated
- */
-const StringRenderer = HTMLRenderer;
 
-export { HTMLRenderer, StringRenderer, renderer };
+export { HTMLRenderer, impl, renderer };
 //# sourceMappingURL=html.js.map

index.js

 /// <reference types="index.d.ts" />
-export { $ContextInternals, Context, Copy, Element, Fragment, Portal, Raw, Renderer, cloneElement, createElement, isElement } from './crank.js';
+export { Context, Copy, Element, Fragment, Portal, Raw, Renderer, cloneElement, createElement, isElement } from './crank.js';
 //# sourceMappingURL=index.js.map

package.json

 {
   "name": "@bikeshaving/crank",
-  "version": "0.4.0-beta.3",
+  "version": "0.4.0",
   "description": "Write JSX-driven components with functions, promises and generators.",
@@ -5,0 +5,0 @@ "homepage": "https://crank.js.org",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

664127

increased by0.45%

Lines of code

6540

increased by0.71%

Number of medium supply chain risk alerts

0

decreased by-100%

No dependency changes