@b9g/crank 0.5.0-debug.0 → 0.5.1

package/crank.d.ts

@@ -1,14 +1,14 @@
 /**
  * A type which represents all valid values for an element tag.
  */
-export declare type Tag = string | symbol | Component;
+export type Tag = string | symbol | Component;
 /**
  * A helper type to map the tag of an element to its expected props.
  *
  * @template TTag - The tag associated with the props. Can be a string, symbol
  * or a component function.
  */
-export declare type TagProps<TTag extends Tag> = TTag extends string ? JSX.IntrinsicElements[TTag] : TTag extends Component<infer TProps> ? TProps : Record<string, unknown>;
+export type TagProps<TTag extends Tag> = TTag extends string ? JSX.IntrinsicElements[TTag] : TTag extends Component<infer TProps> ? TProps : Record<string, unknown>;
 /***
  * SPECIAL TAGS
  *
@@ -25,7 +25,7 @@ export declare type TagProps<TTag extends Tag> = TTag extends string ? JSX.Intri
  * reference this export.
  */
 export declare const Fragment = "";
-export declare type Fragment = typeof Fragment;
+export type Fragment = typeof Fragment;
 /**
  * A special tag for rendering into a new root node via a root prop.
  *
@@ -36,7 +36,7 @@ export declare type Fragment = typeof Fragment;
  * a Portal element.
  */
 export declare const Portal: any;
-export declare type Portal = typeof Portal;
+export type Portal = typeof Portal;
 /**
  * A special tag which preserves whatever was previously rendered in the
  * element’s position.
@@ -46,15 +46,14 @@ export declare type Portal = typeof Portal;
  * in which case the previously rendered keyed element will be copied.
  */
 export declare const Copy: any;
-export declare type Copy = typeof Copy;
+export type Copy = typeof Copy;
 /**
  * A special tag for injecting raw nodes or strings via a value prop.
  *
- * If the value prop is a string, Renderer.prototype.parse() will be called on
- * the string and the result will be set as the element’s value.
+ * Renderer.prototype.raw() is called with the value prop.
  */
 export declare const Raw: any;
-export declare type Raw = typeof Raw;
+export type Raw = typeof Raw;
 /**
  * Describes all valid values of an element tree, excluding iterables.
  *
@@ -62,7 +61,7 @@ export declare type Raw = typeof Raw;
  * string using the toString() method. We exclude them from this type to catch
  * potential mistakes.
  */
-export declare type Child = Element | string | number | boolean | null | undefined;
+export type Child = Element | string | number | boolean | null | undefined;
 /**
  * An arbitrarily nested iterable of Child values.
  *
@@ -79,18 +78,18 @@ export interface ChildIterable extends Iterable<Child | ChildIterable> {
  * Describes all valid values of an element tree, including arbitrarily nested
  * iterables of such values.
  */
-export declare type Children = Child | ChildIterable;
+export type Children = Child | ChildIterable;
 /**
  * Represents all functions which can be used as a component.
  *
  * @template [TProps=*] - The expected props for the component.
  */
-export declare type Component<TProps extends Record<string, unknown> = any> = (this: Context<TProps>, props: TProps) => Children | PromiseLike<Children> | Iterator<Children, Children | void, any> | AsyncIterator<Children, Children | void, any>;
+export type Component<TProps extends Record<string, unknown> = any> = (this: Context<TProps>, props: TProps) => Children | PromiseLike<Children> | Iterator<Children, Children | void, any> | AsyncIterator<Children, Children | void, any>;
 /**
  * A type to keep track of keys. Any value can be a key, though null and
  * undefined are ignored.
  */
-declare type Key = unknown;
+type Key = unknown;
 declare const ElementSymbol: unique symbol;
 export interface Element<TTag extends Tag = Tag> {
     /**
@@ -191,7 +190,7 @@ export declare function cloneElement<TTag extends Tag>(el: Element<TTag>): Eleme
  *
  * All of these possible values are reflected in this utility type.
  */
-export declare type ElementValue<TNode> = Array<TNode | string> | TNode | string | undefined;
+export type ElementValue<TNode> = Array<TNode | string> | TNode | string | undefined;
 /**
  * @internal
  * The internal nodes which are cached and diffed against new elements when
@@ -220,25 +219,30 @@ declare class Retainer<TNode> {
      * The cached child values of this element. Only host and component elements
      * will use this property.
      */
-    cached: ElementValue<TNode>;
+    cachedChildValues: 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>;
-    inflight: Promise<ElementValue<TNode>> | undefined;
-    onCommit: Function | undefined;
+    fallbackValue: RetainerChild<TNode>;
+    inflightValue: Promise<ElementValue<TNode>> | undefined;
+    onNextValues: Function | undefined;
     constructor(el: Element);
 }
 /**
  * The retainer equivalent of ElementValue
  */
-declare type RetainerChild<TNode> = Retainer<TNode> | string | undefined;
+type RetainerChild<TNode> = Retainer<TNode> | string | undefined;
+export interface HydrationData<TNode> {
+    props: Record<string, unknown>;
+    children: Array<TNode | string>;
+}
 export interface RendererImpl<TNode, TScope, TRoot extends TNode = TNode, TResult = ElementValue<TNode>> {
     scope<TTag extends string | symbol>(scope: TScope | undefined, tag: TTag, props: TagProps<TTag>): TScope | undefined;
     create<TTag extends string | symbol>(tag: TTag, props: TagProps<TTag>, scope: TScope | undefined): TNode;
+    hydrate<TTag extends string | symbol>(tag: TTag, node: TNode | TRoot, props: TagProps<TTag>): HydrationData<TNode> | undefined;
     /**
      * Called when an element’s rendered value is exposed via render, schedule,
      * refresh, refs, or generator yield expressions.
@@ -261,14 +265,14 @@ export interface RendererImpl<TNode, TScope, TRoot extends TNode = TNode, TResul
      * @param text - The string child.
      * @param scope - The current scope.
      *
-     * @returns The escaped string.
+     * @returns A string to be passed to arrange.
      *
-     * Rather than returning text nodes for whatever environment we’re rendering
-     * to, we defer that step for Renderer.prototype.arrange. We do this so that
-     * adjacent strings can be concatenated and the actual element tree can be
-     * rendered in a normalized form.
+     * Rather than returning Text nodes as we would in the DOM case, for example,
+     * we delay that step for Renderer.prototype.arrange. We do this so that
+     * adjacent strings can be concatenated, and the actual element tree can be
+     * rendered in normalized form.
      */
-    escape(text: string, scope: TScope | undefined): string;
+    text(text: string, scope: TScope | undefined, hydration: HydrationData<TNode> | undefined): string;
     /**
      * Called for each Raw element whose value prop is a string.
      *
@@ -277,13 +281,13 @@ export interface RendererImpl<TNode, TScope, TRoot extends TNode = TNode, TResul
      *
      * @returns The parsed node or string.
      */
-    parse(text: string, scope: TScope | undefined): ElementValue<TNode>;
+    raw(value: string | TNode, scope: TScope | undefined, hydration: HydrationData<TNode> | undefined): ElementValue<TNode>;
     patch<TTag extends string | symbol, TName extends string>(tag: TTag, node: TNode, name: TName, value: TagProps<TTag>[TName], oldValue: TagProps<TTag>[TName] | undefined, scope: TScope): unknown;
     arrange<TTag extends string | symbol>(tag: TTag, node: TNode, props: TagProps<TTag>, children: Array<TNode | string>, oldProps: TagProps<TTag> | undefined, oldChildren: Array<TNode | string> | undefined): unknown;
     dispose<TTag extends string | symbol>(tag: TTag, node: TNode, props: TagProps<TTag>): unknown;
     flush(root: TRoot): unknown;
 }
-declare const $RendererImpl: unique symbol;
+declare const _RendererImpl: unique symbol;
 /**
  * An abstract class which is subclassed to render to different target
  * environments. This class is responsible for kicking off the rendering
@@ -300,7 +304,7 @@ export declare class Renderer<TNode extends object = object, TScope = unknown, T
      * A weakmap which stores element trees by root.
      */
     cache: WeakMap<object, Retainer<TNode>>;
-    [$RendererImpl]: RendererImpl<TNode, TScope, TRoot, TResult>;
+    [_RendererImpl]: RendererImpl<TNode, TScope, TRoot, TResult>;
     constructor(impl: Partial<RendererImpl<TNode, TScope, TRoot, TResult>>);
     /**
      * Renders an element tree into a specific root.
@@ -309,7 +313,7 @@ export declare class Renderer<TNode extends object = object, TScope = unknown, T
      * used root to delete the previously rendered element tree from the cache.
      * @param root - The node to be rendered into. The renderer will cache
      * element trees per root.
-     * @param ctx - An optional context that will be the ancestor context of all
+     * @param bridge - An optional context that will be the ancestor context of all
      * elements in the tree. Useful for connecting different renderers so that
      * events/provisions properly propagate. The context for a given root must be
      * the same or an error will be thrown.
@@ -318,6 +322,7 @@ export declare class Renderer<TNode extends object = object, TScope = unknown, T
      * the result if the element tree renders asynchronously.
      */
     render(children: Children, root?: TRoot | undefined, bridge?: Context | undefined): Promise<TResult> | TResult;
+    hydrate(children: Children, root: TRoot, bridge?: Context | undefined): Promise<TResult> | TResult;
 }
 export interface Context extends Crank.Context {
 }
@@ -329,75 +334,50 @@ export interface ProvisionMap extends Crank.ProvisionMap {
 }
 /**
  * @internal
- * The internal class which holds all context data.
+ * The internal class which holds context data.
  */
 declare class ContextImpl<TNode = unknown, TScope = unknown, TRoot extends TNode = TNode, TResult = unknown> {
-    /**
-     * flags - A bitmask. See CONTEXT FLAGS above.
-     */
+    /** A bitmask. See CONTEXT FLAGS above. */
     f: number;
+    /** The actual context associated with this impl. */
+    owner: Context<unknown, TResult>;
     /**
-     * ctx - The actual object passed as this to components.
-     */
-    ctx: Context<unknown, TResult>;
-    /**
-     * renderer - The renderer which created this context.
+     * The renderer which created this context.
      */
     renderer: RendererImpl<TNode, TScope, TRoot, TResult>;
-    /**
-     * root - The root node as set by the nearest ancestor portal.
-     */
+    /** The root node as set by the nearest ancestor portal. */
     root: TRoot | undefined;
     /**
-     * host - The nearest host or portal retainer.
+     * The nearest ancestor host or portal retainer.
      *
      * When refresh is called, the host element will be arranged as the last step
      * of the commit, to make sure the parent’s children properly reflects the
      * components’s children.
      */
     host: Retainer<TNode>;
-    /**
-     * parent - The parent context.
-     */
+    /** The parent context impl. */
     parent: ContextImpl<TNode, TScope, TRoot, TResult> | undefined;
-    /**
-     * scope - The value of the scope at the point of element’s creation.
-     */
+    /** The value of the scope at the point of element’s creation. */
     scope: TScope | undefined;
-    /**
-     * retainer - The internal node associated with this context.
-     */
+    /** The internal node associated with this context. */
     ret: Retainer<TNode>;
     /**
-     * iterator - The iterator returned by the component function.
+     * The iterator returned by the component function.
+     *
+     * Existence of this property implies that the component is a generator
+     * component. It is deleted when a component is returned.
      */
     iterator: Iterator<Children, Children | void, unknown> | AsyncIterator<Children, Children | void, unknown> | undefined;
-    /*** async properties ***/
-    /**
-     * inflightBlock
-     */
     inflightBlock: Promise<unknown> | undefined;
-    /**
-     * inflightValue
-     */
     inflightValue: Promise<ElementValue<TNode>> | undefined;
-    /**
-     * enqueuedBlock
-     */
     enqueuedBlock: Promise<unknown> | undefined;
-    /**
-     * enqueuedValue
-     */
     enqueuedValue: Promise<ElementValue<TNode>> | undefined;
-    /**
-     * onavailable - A callback used in conjunction with the IsAvailable flag to
-     * implement the props async iterator. See the Symbol.asyncIterator method
-     * and the resumeCtxIterator function.
-     */
-    onAvailable: Function | undefined;
+    onProps: ((props: Record<string, any>) => unknown) | undefined;
+    onPropsRequested: Function | undefined;
     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>);
 }
-declare const $ContextImpl: unique symbol;
+declare const _ContextImpl: unique symbol;
+type ComponentProps<T> = T extends (props: infer U) => any ? U : T;
 /**
  * A class which is instantiated and passed to every component as its this
  * value. Contexts form a tree just like elements and all components in the
@@ -414,7 +394,7 @@ export declare class Context<TProps = any, TResult = any> implements EventTarget
     /**
      * @internal
      */
-    [$ContextImpl]: ContextImpl<unknown, unknown, unknown, TResult>;
+    [_ContextImpl]: ContextImpl<unknown, unknown, unknown, TResult>;
     constructor(impl: ContextImpl<unknown, unknown, unknown, TResult>);
     /**
      * The current props of the associated element.
@@ -423,7 +403,7 @@ export declare class Context<TProps = any, TResult = any> implements EventTarget
      * component or via the context iterator methods. This property is mainly for
      * plugins or utilities which wrap contexts.
      */
-    get props(): TProps;
+    get props(): ComponentProps<TProps>;
     /**
      * The current value of the associated element.
      *
@@ -432,8 +412,8 @@ export declare class Context<TProps = any, TResult = any> implements EventTarget
      * mainly for plugins or utilities which wrap contexts.
      */
     get value(): TResult;
-    [Symbol.iterator](): Generator<TProps>;
-    [Symbol.asyncIterator](): AsyncGenerator<TProps>;
+    [Symbol.iterator](): Generator<ComponentProps<TProps>>;
+    [Symbol.asyncIterator](): AsyncGenerator<ComponentProps<TProps>>;
     /**
      * Re-executes a component.
      *
@@ -477,8 +457,8 @@ export declare class Context<TProps = any, TResult = any> implements EventTarget
 export interface EventMap extends Crank.EventMap {
     [type: string]: Event;
 }
-declare type MappedEventListener<T extends string> = (ev: EventMap[T]) => unknown;
-declare type MappedEventListenerOrEventListenerObject<T extends string> = MappedEventListener<T> | {
+type MappedEventListener<T extends string> = (ev: EventMap[T]) => unknown;
+type MappedEventListenerOrEventListenerObject<T extends string> = MappedEventListener<T> | {
     handleEvent: MappedEventListener<T>;
 };
 declare global {