@b9g/crank 0.5.0-beta.4 → 0.5.0-beta.5

package/crank.d.ts

@@ -1,481 +1,2 @@
-/**
- * A type which represents all valid values for an element tag.
- */
-export declare 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>;
-/***
- * SPECIAL TAGS
- *
- * Crank provides a couple tags which have special meaning for the renderer.
- ***/
-/**
- * A special tag for grouping multiple children within the same parent.
- *
- * All non-string iterables which appear in the element tree are implicitly
- * wrapped in a fragment element.
- *
- * This tag is just the empty string, and you can use the empty string in
- * createElement calls or transpiler options directly to avoid having to
- * reference this export.
- */
-export declare const Fragment = "";
-export declare type Fragment = typeof Fragment;
-/**
- * A special tag for rendering into a new root node via a root prop.
- *
- * This tag is useful for creating element trees with multiple roots, for
- * things like modals or tooltips.
- *
- * Renderer.prototype.render() will implicitly wrap top-level element trees in
- * a Portal element.
- */
-export declare const Portal: any;
-export declare type Portal = typeof Portal;
-/**
- * A special tag which preserves whatever was previously rendered in the
- * element’s position.
- *
- * Copy elements are useful for when you want to prevent a subtree from
- * rerendering as a performance optimization. Copy elements can also be keyed,
- * in which case the previously rendered keyed element will be copied.
- */
-export declare const Copy: any;
-export declare 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.
- */
-export declare const Raw: any;
-export declare type Raw = typeof Raw;
-/**
- * Describes all valid values of an element tree, excluding iterables.
- *
- * Arbitrary objects can also be safely rendered, but will be converted to a
- * 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;
-/**
- * An arbitrarily nested iterable of Child values.
- *
- * We use a recursive interface here rather than making the Children type
- * directly recursive because recursive type aliases were added in TypeScript
- * 3.7.
- *
- * You should avoid referencing this type directly, as it is mainly exported to
- * prevent TypeScript errors.
- */
-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;
-/**
- * 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>;
-/**
- * A type to keep track of keys. Any value can be a key, though null and
- * undefined are ignored.
- */
-declare type Key = unknown;
-declare const ElementSymbol: unique symbol;
-export interface Element<TTag extends Tag = Tag> {
-    /**
-     * @internal
-     * A unique symbol to identify elements as elements across versions and
-     * realms, and to protect against basic injection attacks.
-     * https://overreacted.io/why-do-react-elements-have-typeof-property/
-     *
-     * This property is defined on the element prototype rather than per
-     * instance, because it is the same for every Element.
-     */
-    $$typeof: typeof ElementSymbol;
-    /**
-     * The tag of the element. Can be a string, symbol or function.
-     */
-    tag: TTag;
-    /**
-     * An object containing the “properties” of an element. These correspond to
-     * the attribute syntax from JSX.
-     */
-    props: TagProps<TTag>;
-    /**
-     * A value which uniquely identifies an element from its siblings so that it
-     * can be added/updated/moved/removed by key rather than position.
-     *
-     * Passed in createElement() as the prop "c-key".
-     */
-    key: Key;
-    /**
-     * A callback which is called with the element’s result when it is committed.
-     *
-     * 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;
-}
-/**
- * Elements are the basic building blocks of Crank applications. They are
- * JavaScript objects which are interpreted by special classes called renderers
- * to produce and manage stateful nodes.
- *
- * @template {Tag} [TTag=Tag] - The type of the tag of the element.
- *
- * @example
- * // specific element types
- * let div: Element<"div">;
- * let portal: Element<Portal>;
- * let myEl: Element<MyComponent>;
- *
- * // general element types
- * let host: Element<string | symbol>;
- * let component: Element<Component>;
- *
- * Typically, you use a helper function like createElement to create elements
- * rather than instatiating this class directly.
- */
-export declare class Element<TTag extends Tag = Tag> {
-    constructor(tag: TTag, props: TagProps<TTag>, key: Key, ref?: ((value: unknown) => unknown) | undefined, static_?: boolean | undefined);
-}
-export declare function isElement(value: any): value is Element;
-/**
- * Creates an element with the specified tag, props and children.
- *
- * This function is usually used as a transpilation target for JSX transpilers,
- * 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.
- */
-export declare function createElement<TTag extends Tag>(tag: TTag, props?: TagProps<TTag> | null | undefined, ...children: Array<unknown>): Element<TTag>;
-/** Clones a given element, shallowly copying the props object. */
-export declare function cloneElement<TTag extends Tag>(el: Element<TTag>): Element<TTag>;
-/**
- * A helper type which repesents all possible rendered values of an element.
- *
- * @template TNode - The node type for the element provided by the renderer.
- *
- * When asking the question, what is the “value” of a specific element, the
- * answer varies depending on the tag:
- *
- * For host elements, the value is the nodes created for the element.
- *
- * For fragments, the value is usually an array of nodes.
- *
- * For portals, the value is undefined, because a Portal element’s root and
- * children are opaque to its parent.
- *
- * For components, the value can be any of the above, because the value of a
- * component is determined by its immediate children.
- *
- * Rendered values can also be strings or arrays of nodes and strings, in the
- * case of component or fragment elements with strings or multiple children.
- *
- * All of these possible values are reflected in this utility type.
- */
-export declare type ElementValue<TNode> = Array<TNode | string> | 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;
-    /**
-     * 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: ElementValue<TNode>;
-    /**
-     * The cached child values of this element. Only host and component elements
-     * will use this property.
-     */
-    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.
-     */
-    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;
-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;
-    /**
-     * Called when an element’s rendered value is exposed via render, schedule,
-     * refresh, refs, or generator yield expressions.
-     *
-     * @param value - The value of the element being read. Can be a node, a
-     * string, undefined, or an array of nodes and strings, depending on the
-     * element.
-     *
-     * @returns Varies according to the specific renderer subclass. By default,
-     * it exposes the element’s value.
-     *
-     * This is useful for renderers which don’t want to expose their internal
-     * nodes. For instance, the HTML renderer will convert all internal nodes to
-     * strings.
-     */
-    read(value: ElementValue<TNode>): TResult;
-    /**
-     * Called for each string in an element tree.
-     *
-     * @param text - The string child.
-     * @param scope - The current scope.
-     *
-     * @returns The escaped string.
-     *
-     * 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.
-     */
-    escape(text: string, scope: TScope | undefined): string;
-    /**
-     * Called for each Raw element whose value prop is a string.
-     *
-     * @param text - The string child.
-     * @param scope - The current scope.
-     *
-     * @returns The parsed node or string.
-     */
-    parse(text: string, scope: TScope | 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;
-/**
- * An abstract class which is subclassed to render to different target
- * environments. This class is responsible for kicking off the rendering
- * process and caching previous trees by root.
- *
- * @template TNode - The type of the node for a rendering environment.
- * @template TScope - Data which is passed down the tree.
- * @template TRoot - The type of the root for a rendering environment.
- * @template TResult - The type of exposed values.
- */
-export declare class Renderer<TNode extends object = object, TScope = unknown, TRoot extends TNode = TNode, TResult = ElementValue<TNode>> {
-    /**
-     * @internal
-     * A weakmap which stores element trees by root.
-     */
-    cache: WeakMap<object, Retainer<TNode>>;
-    [_RendererImpl]: RendererImpl<TNode, TScope, TRoot, TResult>;
-    constructor(impl: Partial<RendererImpl<TNode, TScope, TRoot, TResult>>);
-    /**
-     * Renders an element tree into a specific root.
-     *
-     * @param children - An element tree. You can render null with a previously
-     * 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 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.
-     *
-     * @returns The result of rendering the children, or a possible promise of
-     * the result if the element tree renders asynchronously.
-     */
-    render(children: Children, root?: TRoot | undefined, bridge?: Context | undefined): Promise<TResult> | TResult;
-}
-export interface Context extends Crank.Context {
-}
-/**
- * An interface which can be extended to provide strongly typed provisions.
- * See Context.prototype.consume and Context.prototype.provide.
- */
-export interface ProvisionMap extends Crank.ProvisionMap {
-}
-/**
- * @internal
- * The internal class which holds context data.
- */
-declare class ContextImpl<TNode = unknown, TScope = unknown, TRoot extends TNode = TNode, TResult = unknown> {
-    /** A bitmask. See CONTEXT FLAGS above. */
-    f: number;
-    /** The actual context associated with this impl. */
-    owner: Context<unknown, TResult>;
-    /**
-     * The renderer which created this context.
-     */
-    renderer: RendererImpl<TNode, TScope, TRoot, TResult>;
-    /** The root node as set by the nearest ancestor portal. */
-    root: TRoot | undefined;
-    /**
-     * 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>;
-    /** The parent context impl. */
-    parent: ContextImpl<TNode, TScope, TRoot, TResult> | undefined;
-    /** The value of the scope at the point of element’s creation. */
-    scope: TScope | undefined;
-    /** The internal node associated with this context. */
-    ret: Retainer<TNode>;
-    /**
-     * 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;
-    inflightBlock: Promise<unknown> | undefined;
-    inflightValue: Promise<ElementValue<TNode>> | undefined;
-    enqueuedBlock: Promise<unknown> | undefined;
-    enqueuedValue: Promise<ElementValue<TNode>> | 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 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
- * element tree are connected via contexts. Components can use this tree to
- * communicate data upwards via events and downwards via provisions.
- *
- * @template [TProps=*] - The expected shape of the props passed to the
- * component. Used to strongly type the Context iterator methods.
- * @template [TResult=*] - The readable element value type. It is used in
- * places such as the return value of refresh and the argument passed to
- * schedule and cleanup callbacks.
- */
-export declare class Context<TProps = any, TResult = any> implements EventTarget {
-    /**
-     * @internal
-     */
-    [_ContextImpl]: ContextImpl<unknown, unknown, unknown, TResult>;
-    constructor(impl: ContextImpl<unknown, unknown, unknown, TResult>);
-    /**
-     * The current props of the associated element.
-     *
-     * Typically, you should read props either via the first parameter of the
-     * component or via the context iterator methods. This property is mainly for
-     * plugins or utilities which wrap contexts.
-     */
-    get props(): ComponentProps<TProps>;
-    /**
-     * The current value of the associated element.
-     *
-     * Typically, you should read values via refs, generator yield expressions,
-     * or the refresh, schedule, cleanup, or flush methods. This property is
-     * mainly for plugins or utilities which wrap contexts.
-     */
-    get value(): TResult;
-    [Symbol.iterator](): Generator<ComponentProps<TProps>>;
-    [Symbol.asyncIterator](): AsyncGenerator<ComponentProps<TProps>>;
-    /**
-     * Re-executes a component.
-     *
-     * @returns The rendered value of the component or a promise thereof if the
-     * component or its children execute asynchronously.
-     *
-     * The refresh method works a little differently for async generator
-     * components, in that it will resume the Context’s props async iterator
-     * rather than resuming execution. This is because async generator components
-     * are perpetually resumed independent of updates, and rely on the props
-     * async iterator to suspend.
-     */
-    refresh(): Promise<TResult> | TResult;
-    /**
-     * Registers a callback which fires when the component commits. Will only
-     * fire once per callback and update.
-     */
-    schedule(callback: (value: TResult) => unknown): void;
-    /**
-     * Registers a callback which fires when the component’s children are
-     * rendered into the root. Will only fire once per callback and render.
-     */
-    flush(callback: (value: TResult) => unknown): void;
-    /**
-     * Registers a callback which fires when the component unmounts. Will only
-     * fire once per callback.
-     */
-    cleanup(callback: (value: TResult) => unknown): void;
-    consume<TKey extends keyof ProvisionMap>(key: TKey): ProvisionMap[TKey];
-    consume(key: unknown): any;
-    provide<TKey extends keyof ProvisionMap>(key: TKey, value: ProvisionMap[TKey]): void;
-    provide(key: unknown, value: any): void;
-    addEventListener<T extends string>(type: T, listener: MappedEventListenerOrEventListenerObject<T> | null, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener<T extends string>(type: T, listener: MappedEventListenerOrEventListenerObject<T> | null, options?: EventListenerOptions | boolean): void;
-    dispatchEvent(ev: Event): boolean;
-}
-/**
- * A map of event type strings to Event subclasses. Can be extended via
- * TypeScript module augmentation to have strongly typed event listeners.
- */
-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> | {
-    handleEvent: MappedEventListener<T>;
-};
-declare global {
-    namespace Crank {
-        interface EventMap {
-        }
-        interface ProvisionMap {
-        }
-        interface Context {
-        }
-    }
-    namespace JSX {
-        interface IntrinsicElements {
-            [tag: string]: any;
-        }
-        interface ElementChildrenAttribute {
-            children: {};
-        }
-    }
-}
-declare const _default: {
-    createElement: typeof createElement;
-    Fragment: string;
-};
-export default _default;
+export * from "./core.js";
+export * from "./tags.js";