stagnate 1.0.7 → 1.1.0

package/Component.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Stagnate Component class
+ *
+ * @typeParam REFS - interface describing jsx references stored on this component, see {@link Component.refs}
+ * @typeParam PROPS - interface describing jsx props passed to this component
+ * @typeParam ROOT - type of the html root element
+ */
+export declare class Component<REFS = {}, PROPS = undefined, ROOT extends SVGElement | HTMLElement = SVGElement | HTMLElement> {
+    /** properties received from jsx (or set via constructor) */
+    readonly props: PROPS extends undefined ? {} : PROPS;
+    private _components;
+    private _attached;
+    /** html root element, only accessible after {@link build} was called */
+    protected root: ROOT;
+    /**
+     * parent component, only accessible after {@link bind} was called
+     * for self-bound components `this.parent = this`
+     */
+    protected parent: Component<any, any>;
+    /**
+     * jsx references stored on this component,
+     * the REFS type should be set to a interface describing what references the component will use
+     * see {@link ref} for how to set references
+     */
+    protected refs: REFS;
+    /**
+     * if component is to be used from jsx it has to have one constructor argument being the props,
+     * any other constructor signature will fail when used from jsx
+     */
+    constructor(...props: PROPS extends undefined ? [] : [props: PROPS]);
+    private attach;
+    private detach;
+    /**
+     * component render function, should return the component JSX
+     * if null is returned {@link build} call will fail with an exception
+     */
+    protected render(): Element | null;
+    /** called in {@link build} before render is called */
+    protected onBeforeRender(): void;
+    /** called in {@link build} after render is called and root is set */
+    protected onRender(): void;
+    /**
+     * called when component if fully attached (children are attached and `this.attached = true`),
+     * `onAttach` will be called only if the component is bound to a parent component or the component
+     * is self-bound
+     */
+    protected onAttach(): void;
+    /**
+     * called when component if fully detached (children are detached and `this.attached = false`),
+     * `onDetach` will be called only if the component is bound to a parent component or it {@link destroy} was
+     * called on the component directly
+     */
+    protected onDetach(): void;
+    /**
+     * function meant to be used in jsx for binding references
+     *
+     * the following will bind the div under `this.refs.foo` and requires the `REFS` type to include `{foo: HTMLDivElement}`
+     * ```
+     * <div ref={this.ref("foo")} />
+     * ```
+     *
+     * the following will bind the child component under `this.refs.bar` and requires the `REFS` type to include `{bar: BarComponent}`
+     * ```
+     * <BarComponent ref={this.ref("bar")} />
+     * ```
+     *
+     * the following will bind the child component without adding it to refs
+     * ```
+     * <BarComponent ref={this.ref()} />
+     * ```
+     */
+    protected ref<T extends keyof REFS | undefined = undefined>(key?: T): (x: REFS[NonNullable<T>] extends never ? any : REFS[NonNullable<T>]) => void;
+    /**
+     * calls {@link render} and sets {@link root}
+     * @returns the created DOM element ({@link root})
+     */
+    build(): Element;
+    /**
+     * add component to a parent component,
+     * attach component if parent component is attached
+     *
+     * a component can be self-bound by passing itself as parent (`x.bind(x)`),
+     * self-bound components get automatically attached
+     */
+    bind(parent: Component<any, any>): void;
+    /**
+     * render the component, add it as a child of {@link parent} and insert it into DOM
+     *
+     * calls {@link build} and {@link bind} internally
+     *
+     * @param parent - parent component
+     * @param target - DOM element to add the component to, if unset or null `parent.root` is used, if a component is passed it's root will be used
+     * @param before - add the element before the given DOM child, a number can be used as a child index, if unset adds the element as the last child
+     */
+    create(parent: Component<any, any>, target?: Element | Component<any, any> | null, before?: Element | Component<any, any> | number): void;
+    /**
+     * render the component, add it as a child of {@link parent} and add it to DOM by replacing a existing element or component
+     *
+     * calls {@link build} and {@link bind} internally
+     *
+     * @param parent - parent component
+     * @param target - component or DOM element to replace, if component is passed {@link destroy} will be called on it
+     */
+    replace(parent: Component<any, any>, target: Element | Component<any, any>): void;
+    /**
+     * render the component, add it to DOM and self-bound, meant to be used for creating the root component
+     *
+     * calls {@link build} and {@link bind} internally
+     *
+     * @param target - DOM target to append the component to
+     */
+    createOrphanized(target: Node): void;
+    /** remove this component from DOM and its parent component */
+    destroy(): void;
+    /** true if component is attached */
+    get attached(): boolean;
+    /** public accessor for {@link root} */
+    get htmlRoot(): ROOT;
+    /** child component list accessor */
+    get components(): Readonly<Component<any, any, any>[]>;
+}

package/Component.js

@@ -0,0 +1,206 @@
+/**
+ * Stagnate Component class
+ *
+ * @typeParam REFS - interface describing jsx references stored on this component, see {@link Component.refs}
+ * @typeParam PROPS - interface describing jsx props passed to this component
+ * @typeParam ROOT - type of the html root element
+ */
+export class Component {
+    constructor(props) {
+        this._components = [];
+        this._attached = false;
+        this.refs = {};
+        this.props = props;
+    }
+    attach() {
+        for (let i = 0; i < this._components.length; i += 1) {
+            const component = this._components[i];
+            if (!component._attached) {
+                component.attach();
+            }
+        }
+        this._attached = true;
+        this.onAttach();
+    }
+    detach() {
+        this._components.forEach(x => x.detach());
+        this._components = [];
+        this._attached = false;
+        this.refs = {};
+        this.parent = null;
+        this.root = null;
+        this.onDetach();
+    }
+    /**
+     * component render function, should return the component JSX
+     * if null is returned {@link build} call will fail with an exception
+     */
+    render() {
+        return null;
+    }
+    /** called in {@link build} before render is called */
+    onBeforeRender() {
+    }
+    /** called in {@link build} after render is called and root is set */
+    onRender() {
+    }
+    /**
+     * called when component if fully attached (children are attached and `this.attached = true`),
+     * `onAttach` will be called only if the component is bound to a parent component or the component
+     * is self-bound
+     */
+    onAttach() {
+    }
+    /**
+     * called when component if fully detached (children are detached and `this.attached = false`),
+     * `onDetach` will be called only if the component is bound to a parent component or it {@link destroy} was
+     * called on the component directly
+     */
+    onDetach() {
+    }
+    /**
+     * function meant to be used in jsx for binding references
+     *
+     * the following will bind the div under `this.refs.foo` and requires the `REFS` type to include `{foo: HTMLDivElement}`
+     * ```
+     * <div ref={this.ref("foo")} />
+     * ```
+     *
+     * the following will bind the child component under `this.refs.bar` and requires the `REFS` type to include `{bar: BarComponent}`
+     * ```
+     * <BarComponent ref={this.ref("bar")} />
+     * ```
+     *
+     * the following will bind the child component without adding it to refs
+     * ```
+     * <BarComponent ref={this.ref()} />
+     * ```
+     */
+    ref(key) {
+        return (x) => {
+            if (x instanceof Component) {
+                x.parent = this;
+                this._components.push(x);
+                if (this._attached) {
+                    x.attach();
+                }
+            }
+            if (key) {
+                this.refs[key] = x;
+            }
+        };
+    }
+    /**
+     * calls {@link render} and sets {@link root}
+     * @returns the created DOM element ({@link root})
+     */
+    build() {
+        this.onBeforeRender();
+        const html = this.render();
+        if (!html) {
+            throw new Error("can not render component: render function returned null");
+        }
+        this.root = html;
+        this.onRender();
+        return html;
+    }
+    /**
+     * add component to a parent component,
+     * attach component if parent component is attached
+     *
+     * a component can be self-bound by passing itself as parent (`x.bind(x)`),
+     * self-bound components get automatically attached
+     */
+    bind(parent) {
+        this.parent = parent;
+        if (parent != this) {
+            parent._components.push(this);
+            if (parent._attached) {
+                this.attach();
+            }
+        }
+        else {
+            this.attach();
+        }
+    }
+    /**
+     * render the component, add it as a child of {@link parent} and insert it into DOM
+     *
+     * calls {@link build} and {@link bind} internally
+     *
+     * @param parent - parent component
+     * @param target - DOM element to add the component to, if unset or null `parent.root` is used, if a component is passed it's root will be used
+     * @param before - add the element before the given DOM child, a number can be used as a child index, if unset adds the element as the last child
+     */
+    create(parent, target, before) {
+        if (!target) {
+            target = parent.root;
+        }
+        else if (target instanceof Component) {
+            target = target.root;
+        }
+        if (typeof before === "number") {
+            before = before < target.children.length ? target.children[Math.max(0, before)] : undefined;
+        }
+        else if (before instanceof Component) {
+            before = before.root;
+        }
+        target.insertBefore(this.build(), before === undefined ? null : before);
+        this.bind(parent);
+    }
+    /**
+     * render the component, add it as a child of {@link parent} and add it to DOM by replacing a existing element or component
+     *
+     * calls {@link build} and {@link bind} internally
+     *
+     * @param parent - parent component
+     * @param target - component or DOM element to replace, if component is passed {@link destroy} will be called on it
+     */
+    replace(parent, target) {
+        if (target instanceof Component) {
+            target.root.replaceWith(this.build());
+            target.destroy();
+        }
+        else {
+            target.replaceWith(this.build());
+        }
+        this.bind(parent);
+    }
+    /**
+     * render the component, add it to DOM and self-bound, meant to be used for creating the root component
+     *
+     * calls {@link build} and {@link bind} internally
+     *
+     * @param target - DOM target to append the component to
+     */
+    createOrphanized(target) {
+        target.appendChild(this.build());
+        this.bind(this);
+    }
+    /** remove this component from DOM and its parent component */
+    destroy() {
+        if (this.root) {
+            this.root.remove();
+        }
+        if (this.parent) {
+            const index = this.parent._components.indexOf(this);
+            if (index >= 0) {
+                this.parent._components.splice(index, 1);
+            }
+        }
+        this.detach();
+    }
+    /** true if component is attached */
+    get attached() {
+        return this._attached;
+    }
+    /** public accessor for {@link root} */
+    get htmlRoot() {
+        return this.root;
+    }
+    /** child component list accessor */
+    get components() {
+        return this._components;
+    }
+}
+//# sourceMappingURL=Component.js.map

package/Component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Component.js","sourceRoot":"","sources":["../src/Component.ts"],"names":[],"mappings":"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"}

package/README.md

@@ -99,13 +99,11 @@ Same as `create` but replaces `target` instead of being appended to it.
 #### The `createOrphanized` member function
 
 ```typescript
-createOrphanized(target?: Element | null)
+createOrphanized(target?: Node)
 ```
 
 Same as `create` but intended to create the root component. The component is automatically set as attached after render.
 
-If `target` is `null` then component is appended to `document.body`.
-
 ## JSX attribute handling
 
 ### `ref` attribute
@@ -174,58 +172,137 @@ Primary used to avoid passing nested JSX elements as props.
 
 ### Component class
 ```typescript
-declare class Component<REFS = {}, PROPS = undefined, ROOT extends SVGElement | HTMLElement = SVGElement | HTMLElement> {
-	// props from JSX (set via constructor)
-	readonly props: PROPS extends undefined ? {} : PROPS
-	// HTML root element of this component (can be not set if not attached)
-	protected root: ROOT
-	// parent of this component (can be not set if not attached)
-	protected parent: Component<any, any>
-	// the refs object containing bound elements created during render
-	protected refs: REFS
-	// overcomplicated constructor signature made so props is optional only if component has no props defined
-	constructor(...props: PROPS extends undefined ? [] : [never])
-	// the render function, called to get the component root element, null can be returned if component
-	// has nothing to render but will result with exception if component is being created via create or replace
-	protected render(): Element | null
-	// the ref callback generation function with a overcomplicated signature, used to bind JSX elements to refs
-	protected ref<T extends keyof REFS | undefined = undefined>(key?: T): (x: REFS[NonNullable<T>] extends never ? any : REFS[NonNullable<T>]) => void
-	// create component and replace target element
-	replace(parent: Component<any, any>, target?: Element | Component<any, any> | null): void
-	// create component and insert to target
-	create(parent: Component<any, any>, target?: Element | Component<any, any> | null, before?: Element | Component<any, any> | number): void
-	// crate component as root (attached set on creation)
-	createOrphanized(target?: Element | null): void
-	// bind component to a already existing element (called internally on JSX ref binding)
-	bind(parent: Component<any, any>, target?: Element): void
-	// destroy component and it child components
-	destroy(): void
-	// check if component is attached
-	get attached(): boolean
-	// get the root element of this component
-	get htmlRoot(): ROOT;
-	// get and array of child components
-	protected get components(): Readonly<Component<any, any, any>[]>
-	// called before render is called
-	protected onBeforeRender(): void
-	// called after render is called
-	protected onRender(): void
-	// called when parent becomes attached (or on parent assignment if parent is attached)
-	protected onAttach(): void
-	// called when element is destroyed
-	protected onDetach(): void;
+/**
+ * Stagnate Component class
+ *
+ * @typeParam REFS - interface describing jsx references stored on this component, see {@link Component.refs}
+ * @typeParam PROPS - interface describing jsx props passed to this component
+ * @typeParam ROOT - type of the html root element
+ */
+class Component<REFS = {}, PROPS = undefined, ROOT extends SVGElement | HTMLElement = SVGElement | HTMLElement> {
+    /** properties received from jsx (or set via constructor) */
+    readonly props: PROPS extends undefined ? {} : PROPS
+
+    /** html root element, only accessible after {@link build} was called */
+    protected root: ROOT
+
+    /**
+     * parent component, only accessible after {@link bind} was called
+     * for self-bound components `this.parent = this`
+     */
+    protected parent: Component<any, any>
+
+    /**
+     * jsx references stored on this component,
+     * the REFS type should be set to a interface describing what references the component will use
+     * see {@link ref} for how to set references
+     */
+    protected refs: REFS
+
+    /**
+     * if component is to be used from jsx it has to have one constructor argument being the props,
+     * any other constructor signature will fail when used from jsx
+     */
+    constructor(props: PROPS)
+
+    /**
+     * component render function, should return the component JSX
+     * if null is returned {@link build} call will fail with an exception
+     */
+    protected render(): Element | null
+
+    /** called in {@link build} before render is called */
+    protected onBeforeRender(): void
+
+    /** called in {@link build} after render is called and root is set */
+    protected onRender(): void
+
+    /**
+     * called when component if fully attached (children are attached and `this.attached = true`),
+     * `onAttach` will be called only if the component is bound to a parent component or the component
+     * is self-bound
+     */
+    protected onAttach(): void
+
+    /**
+     * called when component if fully detached (children are detached and `this.attached = false`),
+     * `onDetach` will be called only if the component is bound to a parent component or it {@link destroy} was
+     * called on the component directly
+     */
+    protected onDetach(): void
+
+    /** function meant to be used in jsx for binding references */
+    protected ref<T extends keyof REFS | undefined = undefined>(key?: T): (x: REFS[NonNullable<T>] extends never ? any : REFS[NonNullable<T>]) => void
+
+    /**
+     * calls {@link render} and sets {@link root}
+     * @returns the created DOM element ({@link root})
+     */
+    build(): Element
+
+    /**
+     * add component to a parent component,
+     * attach component if parent component is attached
+     *
+     * a component can be self-bound by passing itself as parent (`x.bind(x)`),
+     * self-bound components get automatically attached
+     */
+    bind(parent: Component<any, any>): void
+
+    /**
+     * render the component, add it as a child of {@link parent} and insert it into DOM
+     *
+     * calls {@link build} and {@link bind} internally
+     *
+     * @param parent - parent component
+     * @param target - DOM element to add the component to, if unset or null `parent.root` is used, if a component is passed it's root will be used
+     * @param before - add the element before the given DOM child, a number can be used as a child index, if unset adds the element as the last child
+     */
+    create(parent: Component<any, any>, target?: Element | Component<any, any> | null, before?: Element | Component<any, any> | number): void
+
+    /**
+     * render the component, add it as a child of {@link parent} and add it to DOM by replacing a existing element or component
+     *
+     * calls {@link build} and {@link bind} internally
+     *
+     * @param parent - parent component
+     * @param target - component or DOM element to replace, if component is passed {@link destroy} will be called on it
+     */
+    replace(parent: Component<any, any>, target: Element | Component<any, any>): void
+
+    /**
+     * render the component, add it to DOM and self-bound, meant to be used for creating the root component
+     *
+     * calls {@link build} and {@link bind} internally
+     *
+     * @param target - DOM target to append the component to
+     */
+    createOrphanized(target: Node): void
+
+    /** remove this component from DOM and its parent component */
+    destroy(): void
+
+    /** true if component is attached */
+    get attached(): boolean
+
+    /** public accessor for {@link root} */
+    get htmlRoot(): ROOT
+
+    /** child component list accessor */
+    get components(): Readonly<Component<any, any, any>[]>
 }
-
 ```
 
 ### Utility Types
 
 ```typescript
-// get props of an JSX element or component function / class
+/** get props of an JSX element or component function / class */
 type ComponentProps<IntrinsicElement | ClassElement | FunctionElement>
-// anything that can be legally used in JSX
+
+/** any value that can be used in JSX */
 type StagnateNode
-// the JSX element css class attribute
+
+/** the JSX element css class attribute */
 type ClassAttribute
 ```
 

package/Slot.d.ts

@@ -0,0 +1,33 @@
+import type { JSX, StagnateNode } from "./types";
+/**
+ * Pseudo component used to create named slots.
+ *
+ * example use:
+ * ```typescript
+ * function Foo(props: {children: StagnateNode}) {
+ *   const slots = Slot.extract<{foo: HTMLElement, bar: HTMLElement}>(props.children)
+ *   return <div>
+ *     <div>{slots.foo}</div>
+ *     <div>{slots.bar}</div>
+ *    </div>
+ * }
+ *
+ * const example = <Foo>
+ *   <Slot name="foo">FOO</Slot>
+ *   <Slot name="bar">BAR</Slot>
+ * </Foo>
+ * ```
+ */
+export declare function Slot(props: {
+    name: string;
+    children: StagnateNode;
+}): JSX.Element;
+export declare namespace Slot {
+    /**
+     * This function extracts slotted children from the child list,
+     * it has to be called if slots are in the child list or render will fail on un-extracted slot data.
+     *
+     * see {@link Slot} for a usage example
+     */
+    function extract<T = Record<string, any>>(input: StagnateNode, slots?: Record<string, any>): T;
+}

package/Slot.js

@@ -0,0 +1,60 @@
+class SlotArray extends Array {
+    constructor(name, elements) {
+        super();
+        this.name = name;
+        this.push(elements);
+    }
+}
+/**
+ * Pseudo component used to create named slots.
+ *
+ * example use:
+ * ```typescript
+ * function Foo(props: {children: StagnateNode}) {
+ *   const slots = Slot.extract<{foo: HTMLElement, bar: HTMLElement}>(props.children)
+ *   return <div>
+ *     <div>{slots.foo}</div>
+ *     <div>{slots.bar}</div>
+ *    </div>
+ * }
+ *
+ * const example = <Foo>
+ *   <Slot name="foo">FOO</Slot>
+ *   <Slot name="bar">BAR</Slot>
+ * </Foo>
+ * ```
+ */
+export function Slot(props) {
+    return new SlotArray(props.name, props.children);
+}
+(function (Slot) {
+    /**
+     * This function extracts slotted children from the child list,
+     * it has to be called if slots are in the child list or render will fail on un-extracted slot data.
+     *
+     * see {@link Slot} for a usage example
+     */
+    function extract(input, slots = {}) {
+        if (input instanceof SlotArray && input.length) {
+            slots[input.name] = input[0];
+            input.pop();
+        }
+        else if (Array.isArray(input)) {
+            for (let i = 0; i < input.length; i += 1) {
+                const item = input[i];
+                if (item instanceof SlotArray) {
+                    if (item.length) {
+                        slots[item.name] = item[0];
+                    }
+                    input[i] = null;
+                }
+                else if (Array.isArray(item)) {
+                    extract(item, slots);
+                }
+            }
+        }
+        return slots;
+    }
+    Slot.extract = extract;
+})(Slot || (Slot = {}));
+//# sourceMappingURL=Slot.js.map

package/Slot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Slot.js","sourceRoot":"","sources":["../src/Slot.ts"],"names":[],"mappings":"AAEA,MAAM,SAAU,SAAQ,KAAmB;IAE1C,YAAa,IAAY,EAAE,QAAsB;QAChD,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACpB,CAAC;CACD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,IAAI,CAAC,KAA6C;IACjE,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAQ,CAAA;AACxD,CAAC;AAED,WAAiB,IAAI;IACpB;;;;;OAKG;IACH,SAAgB,OAAO,CAA0B,KAAmB,EAAE,QAA6B,EAAE;QACpG,IAAI,KAAK,YAAY,SAAS,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YAChD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;YAC5B,KAAK,CAAC,GAAG,EAAE,CAAA;QACZ,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;gBACrB,IAAI,IAAI,YAAY,SAAS,EAAE,CAAC;oBAC/B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;wBACjB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;oBAC3B,CAAC;oBACD,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;gBAChB,CAAC;qBAAM,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBAChC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;gBACrB,CAAC;YACF,CAAC;QACF,CAAC;QACD,OAAO,KAAU,CAAA;IAClB,CAAC;IAlBe,YAAO,UAkBtB,CAAA;AACF,CAAC,EA1BgB,IAAI,KAAJ,IAAI,QA0BpB"}

package/{lib/index.d.ts → index.d.ts}

@@ -1,5 +1,4 @@
-export * from "./types";
+export type * from "./types";
 export * from "./Component";
 export * from "./Slot";
 export { Fragment, createElement } from "./jsx-runtime";
-export * as default from "./index";

package/{lib/index.js → index.js}

@@ -1,6 +1,4 @@
-export * from "./types";
 export * from "./Component";
 export * from "./Slot";
 export { Fragment, createElement } from "./jsx-runtime";
-export * as default from "./index";
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,QAAQ,CAAA;AACtB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA"}

package/{lib/jsx-runtime.d.ts → jsx-runtime.d.ts}

@@ -1,8 +1,9 @@
 import type { JSX, StagnateNode } from "./types";
 export declare function jsx(type: any, props: any): any;
 export declare function createElement(type: any, props: any, ...children: any[]): any;
+/** JSX fragment component, <> can be used as an alias */
 export declare function Fragment(props: {
     children: StagnateNode;
 }): JSX.Element;
 export { jsx as jsxs };
-export { JSX };
+export type { JSX };