Noosphere Possibilities Maximized

    shiva
    TypeScript icon, indicating that this package has built-in type declarations

    4.1.4 • Public • Published

    shiva

    GitHub license npm version Bitbucket Pipeline Status PRs Welcome javascript front-end declarative ui library

    shiva is a minimal JavaScript library for building user interfaces.

    Aim

    The aim of shiva is to use JavaScript to create HTML elements without templating. It abstracts the DOM JavaScript API for a declarative and easy to use syntax.

    So instead of:

    <div>Hi there 👋</div>

    shiva provides a function called div():

    import { div } from "shiva";
    
    const HTMLDivElement = div("Hi there 👋");

    This will create the same element as the html version.

    Nested

    Nested elements are easy to construct:

    import { div } from "shiva";
    
    const nestedHTMLDivElement = div(
        div("Hi there 👋"),
        div("Hi there 👋"),
    );

    This will produce:

    <div>
        <div>Hi there 👋</div>
        <div>Hi there 👋</div>
    </div>

    shiva will append HTML elements if they are passed as an argument. It will set textContent on the element if a string is passed.

    Attributes

    To pass attributes to an element:

    import { div } from "shiva";
    
    const handler = () => {
        console.log("handled it 👊");
    };
    
    const superDiv = div("Hi there 👋", { 
        onclick: handler,
        class: style,
        id: "Super Div 🦸‍♂️" 
    });

    shiva will apply attributes if an object is passed as one of the arguments.

    Elements

    shiva provides div(), img() and p() to create HTML elements. To create other HTML elements shiva provides a more generic element() function.

    import { element } from "shiva";
    
    const HTMLButtonElement = element("button", "Click me ⬇️");

    Any HTML element, including custom elements, can be created.

    Components

    Element functions like div() or element() take a HTML element as an argument for appending to themselves.

    import { div } from "shiva";
    
    const component = (title) => {
        return div(title); 
        // returns a HTMLDivElement
    };
    
    const divAndComponent = div(
        component("The TITLE")
    );

    This pattern can be used to build an application out of pieces, each component just needs to return a HTML element (or array of HTML elements).

    Of course, component() can be imported from another file.

    Installation

    npm install shiva --save
    

    shiva is distributed as an ES module. Please use a module aware build tool to import. See https://bitbucket.org/gabrielmccallin/shiva-site for an example of how to include shiva in a project.

    Getting started

    Create root element

    To append a root element that all other elements will attach to:

    import { div } from 'shiva';
    
    const app = () => {
        div({ root: true }, 
            componentA(),
            componentB()
        );
    };
    
    app();

    This will append a HTMLElement <div> to the body of the page with componentA and componentB nested inside.

    👉 componentA and componentB must return a HTML element or array of HTML elements to be appended to the parent.

    State

    shiva provides a very simple publish / subscribe utility.

    pubsub() returns an array where the first element is the subscribe function and the second element is the publish function.

    import { pubsub } from "shiva";
    
    const [subscribe, publish] = pubsub([1, 2, 4, 5]);
    
    subscribe(data => {
        console.log(data);
        // logs the value passed to publish()
    });
    
    // some time later
    publish([6,7,9,12]); // logs [6,7,9,12]

    Combined with updateElement(), this pattern can used to declare reactive behaviour. e.g.

    import { div, updateElement } from "shiva";
    
    const [subscribe, publish] = pubsub("starting data");
    
    const list = div();
    
    subscribe(data =>
        updateElement({ 
            element: list,
            textContent: data
        });
    );
    
    const clicker = div("click me!", {
        onclick: () => publish("new data")
    });

    This will update the textContent attribute of the list element with the string "new data" when the clicker element is clicked.

    🙋 Of course, feel free to bring your own state management! Use updateElement() to re-render data at any time.

    import { div, updateElement } from "shiva";
    
    const list = div();
    
    const clicker = div("click me!", {
        onclick: () => updateElement({ 
            element: list,
            textContent: data
        });
    });

    This acheives the same; directly updating the list element when clicking clicker.

    API

    pubsub(
        initial?: any,
        reducer?: (current: any, next: any) => void
    );

    Initialise state with initial.

    Run a function on new state with a reducer function. Can be used for more complex logic or when the next state depends on the previous one.

    const reducer = (state, newState) => return state + newState;
    
    const [subscribe, publish] = pubsub("DOGE", reducer);
    
    subscribe(state => {
        console.log(state);
    });
    
    publish(" to the moon 🚀"); // logs "DOGE to the moon 🚀" 

    Global store

    Extending the publish / subscribe pattern across components creates a global store, useful if you don't want to pass subscribers and publishers through nested components.

    shiva provides a createStore() function to create this global store.

    // global-store.js
    import { createStore } from "shiva";
    
    const globalStore = createStore("🌍");
    
    export default globalStore;

    Now subscribe or publish to this store.

    // another file
    import { globalStore } from "./global-store";
    
    const [subscriberGlobal, publishGlobal] = globalStore;
    
    // Here we can name the subscribe / publish functions, note we don't call the globalStore, it is already a subscribe / publish tuple.

    See https://bitbucket.org/gabrielmccallin/shiva-site for an example of state management.

    License

    MIT license

    Install

    npm i shiva

    DownloadsWeekly Downloads

    20

    Version

    4.1.4

    License

    MIT

    Unpacked Size

    16.6 kB

    Total Files

    14

    Last publish

    Collaborators

    • gabrielmccallin