@html_first/simple_signal

NOTIFICATION

this library will be discontinued and moved as per v3.0.0;
use virst instead;

about @html_first/simple_signal v^3.x.x

@html_first/simple_signal is a collections of helper classes/functions to:

create web app that are based on signal paradigm;

reactive;

declarative;

auto subscribed reactivity;

true fine grained DOM reflection (that's right, on v3 there's no catch, it's now truely fine grained);

create declarative library (using our Lifecycle) that are heavily scoped on window.document, use cases likes:

for backend centric HATEOAS paradigm, by assigning attributeName (on the html response from the server) to be monitored right after the response is connected to the DOM;

htmlFirst approach, by assigning attributeName coupled with other attributeName and or attributeValue, to control how an element should behave, directly from html;

how to install

npm i @html_first/simple_signal

// @ts-check
import {
...namedExports
} from '@html_first/simple_signal';

on v^3

we ends the support for prebundled module in the reason of, most of the insteresting parts of this library are need to be typehinted, and that's almost impossible in the prebundled environtment
however it's not that hard if you want to bundle it your self, as we have documented our APIs, so you can import whichever API you want and then expose it in the window object

exported-api-and-type-list

$
Animation
App
Component
CRUD
DefinePageTemplate
DefineQRouter
DefineShortCuts
DefineStorage
Derived
documentScope
Event_
For
Let
Lifecycle
lifecycleHandler
List
OnViewPort
onViewPortHandler
Ping
ShortCut
WorkerMainThread
WorkerThread
_

$

*) _{go to exported list}

generate side effect for signal based reactivity such as for:

const letExample = new Let('')
new $(async(first)=>{
 const value = test.value;
 if(first){
     return;
     // return early if you want to opt out from handling the effect immediately,
     // also by doing this you can make the `$` slightly more performance 1) when dealing with `async await` on hydration,
     // such as data fetching;
 }
     // handle value
})
// 1) and when all of the effects is registered, you can call `letExample.call$` to call for effect in parallel;

Derived

// bassically the same with `Let` but use `new Derived`

*) _{go to exported list}

Animation

*) _{go to exported list}

collections of static methods helper for animation; static method prefixed with animation can be used to generate recuring keyframes, which in turn can be used in the callback to animate stuffs

*) _{go to exported list}

App

*) _{go to exported list}

App starter helper for module environtment; the sole purpose is just to auto import the necessary file in your main js file;

*) _{go to exported list}

Component

*) _{go to exported list}

component creation helper using class initiation; behaviour:

it rendered directly to real DOM;

library like bootstrap css and it's js parts can select your elements for it's functionality;

you have to manually scope your style by

// on Component scope
html`<style>
	[${thisInstance.attr}]{
		...nestedCSSRules
	}
</style>
...
`

also you might need to explicitly use ">" directChildOf selector, as when you try to render childComponent

it could also be accidentally selected;

render method:

you put returned value of thisInstance.attr on an html element, which

it will be rendered as it's innerHTML at the onConnected event, then

it will used MutationObserver to look for changes;

*) _{go to exported list}

CRUD

*) _{go to exported list}

CRUD wrapper class;

signal will be updated from returned value of read;
read will be called after calling thisInstance.create/update/delete_, that have true refreshSignal; /** @template V

*) _{go to exported list}

DefinePageTemplate

*) _{go to exported list}

instantiate this class to opt in page templating, by saving html template string on a html document page;

// main page
<div ${templateName}="${path};${selector}"></div>

// template document
<div ${targetAttribute}="${selector}"></div>

how it works:

the class itself register a Lifecycle for templateName, which then upon connected, it will fetch the path then selects targetAttribute="selector" as template that then replace main page element with selected element from template;

fetched page will be then be cached, along with any [targetAttribute] on that page

*) _{go to exported list}

DefineQRouter

*) _{go to exported list}

allow the usage of search query based router through class instantiation;

*) _{go to exported list}

DefineShortCuts

*) _{go to exported list}

create shortcuts through class instantiation;

*) _{go to exported list}

DefineStorage

*) _{go to exported list}

create named storage (localStorage or sessionStorage) through class instantiation;

*) _{go to exported list}

Derived

*) _{go to exported list}

this class is extended from Let Let -signal based reactivity, wich value are derived from reacting to Let<T>.value effects that are called in the asyncCallback this class instantiation;

// @ts-check
const letSingle = new Let(1);
const doubleExample = new Derived(async()=>{
	const value = letSingle.value; // autoscubscribed to `letSingle` value changes;
return value * 2; // returned value are to be derivedValue
});

dataOnly:

const dataOnlyExample = Derived.dataOnly(asyncCallback);

this will automatically opt you out from domReflector;

make sure to check argument documentation in your IDE typehint;

*) _{go to exported list}

documentScope

*) _{go to exported list}

type helper for documentScope

*) _{go to exported list}

Event_

*) _{go to exported list}

use this instead of normal eventListener declaration for:

creating autoqueued listener;
autoScope _ static methods, inside Component scope;

// @ts-check
someObject.addEventListener('click', Event_.listener( (event) => {
// code
}))

*) _{go to exported list}

For

*) _{go to exported list}

assign element to loop through 'List' as data to render child element using class instantiation;
loped childElement:

must have HTMLElement as first children;

only first children will be used to loop through List, all other children will be deleted from the dom before onConnected event of parentElement;

*) _{go to exported list}

Let

*) _{go to exported list}

signal based reactivity; assigning newValue to Let insance:

const letSingle = new Let(1, ...args);
letSingle.value++; // 2;
letSingle.value = 3 // 3;

dataOnly:

const dataOnlyExample = Let.dataOnly(args0);

methods:

call$: manually triggers effects subscribed to thisInstance;

remove$: unubscribe thisInstance from specific effect;

removeAll$: unubscribe thisInstance from all of its effects;

*) _{go to exported list}

Lifecycle

*) _{go to exported list}

helper class to track connected/disconnected/attributeChanged of an element;
all global signal with dom relector that need to be available for parent scope should be prefixed with g-;

*) _{go to exported list}

lifecycleHandler

*) _{go to exported list}

type helper for lifecycleHandler & attributeChangedLifecycle

*) _{go to exported list}

List

*) _{go to exported list}

helper class to create list that satisfy Array<Record<string, string>>

const listExample = new List([
     {key1: "test", ...keys},
     {key1: "test3", ...keys},
])

usefull for loops;

*) _{go to exported list}

OnViewPort

*) _{go to exported list}

lifecycle wrapper to observe whether element is in viewport

*) _{go to exported list}

onViewPortHandler

*) _{go to exported list}

type helper for onViewPortHandler

*) _{go to exported list}

Ping

*) _{go to exported list}

trigger based callback integrated to the internal library queue handler; can be created using class instantiation;

*) _{go to exported list}

ShortCut

*) _{go to exported list}

helper class to create ShortCut through class instantiation;
call thisInstance.ping to manually trigger action

*) _{go to exported list}

WorkerMainThread

*) _{go to exported list}

helper class for registering and postMessage to webWorker

const worker = new WorkerMainThread(options);
worker.postMessage(message);

*) _{go to exported list}

WorkerThread

*) _{go to exported list}

helper class to define web worker thread;

new WorkerThread({
	onMessage: ({ event, postMessage }) => {
		const message = undefined;
		// code to handle the message
		postMessage(message);
	},
});

*) _{go to exported list}

_

*) _{go to exported list}

scoping helper for signal based reactifity stored in static Method of class _;
if you use our Component class, use this class static method, instead of their respective class, for autoscoping,

which then you can use it's attr returned value to mark the element

// on Component scope
onConnected(async()=>{
	const data = _.let('test');
	html`<div ${data.attr}="innerText"></div>`
})

*) _{go to exported list}