core/index.ts

From @weblabsjs/core/index.ts

I am single handedly developing Weblabs, so if you face any problem, or notice any error code in docs which is possibly not working, post an issue on the git repo: https://github.com/weblabsJS/core

WebLabsElement

export declare class WebLabsElement {
    coreElement: HTMLElement;
    constructor(HTMLTag: string, ...children: WebLabsChild[]);
    id(Id: string): this;
    class(...classnames: string[]): this;
    dynamicClass<stateType>(value: () => string, dependency: state<stateType>);
    prop(name: HTMLTagProps, value: string): this;
    dynamicProp<stateType>(name: HTMLTagProps, value: Function, dependency: state<stateType>)
    event(name: WeblabsEvent, callback: Function): this;
    ref(state: state): this;
    onRemove(callback: Function): this;
}

This class is an abstraction over the native HTMLElement which provides utility functions to modify the underlying HTMLElement using pure dom functions to increase efficiency and performance.

It uses a custom type WebLabsChild as it denotes all the possible children to the custom component. The type definition is as follows:

export type WebLabsChild = WebLabsElement | String | string | number;

As we can see it is a circular reference to the WebLabsElement, as well as some other permitted types such as String and number.

Some other custom types we can see are HTMLTagProps and WeblabsEvent which are simply helper types for all the built-in Tag Properties and Events in HTML5.

They can be summarized as such:

export type HTMLTagProps = "accept" | "acceptCharset" | "accessKey" | "action" | "allowFullScreen" | "allowTransparency" | "alt" | "async" | "autocomplete" | "autofocus" | "autoPlay" | "capture" | "cellPadding" | "cellSpacing" | "challenge" | "charSet" | "checked" | "cite" | "class" | "className" | "cols" | "colSpan" | "content" | "contentEditable" | "contextMenu" | "controls" | "coords" | "crossOrigin" | "data" | "dateTime" | "default" | "defer" | "dir" | "disabled" | "download" | "draggable" | "dropzone" | "enctype" | "for" | "form" | "formAction" | "formEncType" | "formMethod" | "formNoValidate" | "formTarget" | "frameBorder" | "headers" | "height" | "hidden" | "high" | "href" | "hrefLang" | "htmlFor" | "httpEquiv" | "icon" | "id" | "inputMode" | "integrity" | "is" | "itemId" | "itemProp" | "itemRef" | "itemScope" | "itemType" | "kind" | "label" | "lang" | "list" | "loop" | "low" | "manifest" | "marginHeight" | "marginWidth" | "max" | "maxLength" | "media" | "mediaGroup" | "method" | "min" | "minLength" | "multiple" | "muted" | "name" | "noValidate" | "nonce" | "open" | "optimum" | "pattern" | "placeholder" | "poster" | "preload" | "profile" | "radioGroup" | "readOnly" | "referrerPolicy" | "rel" | "required" | "reversed" | "role" | "rows" | "rowSpan" | "sandbox" | "scope" | "scoped" | "scrolling" | "seamless" | "selected" | "shape" | "size" | "sizes" | "slot" | "span" | "spellcheck" | "src" | "srcdoc" | "srclang" | "srcSet" | "start" | "step" | "style" | "summary" | "tabIndex" | "target" | "title" | "type" | "useMap" | "value" | "width" | "wmode" | "wrap";
export type WeblabsEvent = "abort" | "animationend" | "animationiteration" | "animationstart" | "auxclick" | "beforeinput" | "blur" | "cancel" | "canplay" | "canplaythrough" | "change" | "click" | "close" | "contextmenu" | "copy" | "cuechange" | "cut" | "dblclick" | "drag" | "dragend" | "dragenter" | "dragexit" | "dragleave" | "dragover" | "dragstart" | "drop" | "durationchange" | "emptied" | "ended" | "error" | "focus" | "focusin" | "focusout" | "fullscreenchange" | "fullscreenerror" | "gotpointercapture" | "input" | "invalid" | "keydown" | "keypress" | "keyup" | "load" | "loadeddata" | "loadedmetadata" | "loadstart" | "lostpointercapture" | "mousedown" | "mouseenter" | "mouseleave" | "mousemove" | "mouseout" | "mouseover" | "mouseup" | "pause" | "play" | "playing" | "pointercancel" | "pointerdown" | "pointerenter" | "pointerleave" | "pointermove" | "pointerout" | "pointerover" | "pointerup" | "progress" | "ratechange" | "reset" | "resize" | "scroll" | "securitypolicyviolation" | "seeked" | "seeking" | "select" | "selectionchange" | "selectstart" | "stalled" | "submit" | "suspend" | "timeupdate" | "toggle" | "touchcancel" | "touchend" | "touchmove" | "touchstart" | "transitioncancel" | "transitionend" | "transitionrun" | "transitionstart" | "volumechange" | "waiting" | "wheel";

State()

export type state<type> = {
    get: (arg?: { filter?: boolean }) => type,
    set: (newstore: type) => void,
    registerEvent: <argType>(eventName: string, callback: (data: argType) => any) => void,
    emitEvent: <argType>(eventName: string, args: argType) => void,
    subscribe: <Event extends subscriptionEvent>(
        event: Event,
        callBack: 
            Event extends "set" ? (prev: type, newv: type) => boolean | StateModify<type> | void :
            Event extends "set:after" ? (value: type) => void :
            Event extends "set:only" ? (value: type) => void :
            Event extends "get"? (value: type) => StateModify<type> | void :
            never
    ) => void
}

export type StateModify<value> = {
    value: value
}

export declare function State<StoreType>(initial: StoreType): state;

Here we can see a State function takes a custom StoreType to store a stateful variable. The function returns a state object as defined above.

The return function and their usage are:

• get() - Returns the value of the state at the instance it was called. Invokes the get event

• set(value: StoreType) - Stores a new value of the state, and calls all the update candidates related to the state. Invokes the set event

• subscribe(...) => void - Subscribes to event as defined in the type subscriptionEvent.

  • get - Whenever the get function is called, the get event is triggered. All the callback function subscribed to this function is called one by one in the order of it's setting.

  • set - Whenever the set function is called, the set event is triggered. All the callback function subscribed to this function is called one by one in the order of it's setting. Each function must return true in order for the set value to actually stored.

  • set:after - This subscription event occurs after the set event has been executed. This might include updating the state dependents that will update if the state was updated.

  • set:only - This subscription event occurs iff the set function stored the default value instead of the mutated value

Here we can see we are using another type, subscriptionEvent. The type can be declared as follows:

export type subscriptionEvent = "set" | "get" | "set:after" | "set:only"

This are the four possible values, any other value will not affect the program in any way.

StateModify<type>()

export function StateModify<type>(value: type): StateModify<type>

This function is used in state.subscribe("set", callback => StateModify<type> | boolean | void) function to tell WebLabs to "mutate" the state value to whatever value was given to this function.

You can check the usage at State subscription chapter.

$()

export function $(callback: Function, ...states: State[]): WebLabsElement

The $() function is used for stateful rendered components, which might depend on a State to display data.

This function surgically updates the DOM with the exact component that needs to be updated, which also excludes any rough algorithm since it replaces and recreates that very component that needs to be updated.

Small bits of components are recommended to be updated to improve performance.

What NOT to do

function App() {
    const text = State("");
    
    return $(() => {
        return div(
            ...components,
            p(text.get())
        )
    }, text)
}

What to DO

function App() {
    const text = State("")
    
    return div(
        ...components,
        $(() => p(text.get()), text)
    )
}

When()

export function When(condition: Boolean, if_true: WebLabsChild, if_false: WebLabsChild): WebLabsChild

The When() function conditionally renders a component depending upon the condition provided. The if_true component is returned when condition is true, otherwise if_false is returned.

Use the When() function with $() function iff the condition depends on a State

onLoad()

export async function onLoad(callback: Function, ...dependency: state[]): void

the onLoad() function is to be used when a component needs to fetch data or to do some activity before it can render the components. onLoad() can also run when dependencies update if we provide some dependent states to the second argument.

Multiple onLoad() function can be used but it is not recommended. Each component by standard should have on onLoad() function.

render()

export function render(id: string, app: WebLabsElement): void

The render() function is the most important function, as it is responsible for attaching the app to a HTML component of which the id will be provided by the developer.

We can have several render() instances of the same app running parallel, and it will still work without interfering with any other render() instances.

Url()

export function Url(base_url: string, callback: Function): WeblabsURL

The Url() function is used to create URL for routing purposes. This function simply creates virtual routes that will only affect internal states and not really reload the page.

It returns a type WeblabsURL

export type WeblabsURL = {
    url: string,
    callBack: Function
}

AppRouter()

export function AppRouter(base_url: string, ...urlNodes: WeblabsURL[]): WebLabsElement

The AppRouter() function takes a bunch of virtual WeblabsURL from the Url() function and attaches it to certain components to create page transition, even with data. Read the Routing tutorial to learn how to use it.

AppNavigator()

export function AppNavigator(base_url, ...data: any[])

The AppNavigator() function helps in transitioning to different routes that were defined using AppRouter() . To learn to use it, visit the Routing section of the documentation.

AppLink()

export function AppLink(url, child: WebLabsElement, ...variables)

Helper component that encapsulates the AppNavigator() function and provides a simple interface to transition to different routes.