dominity v1.0.0

Dominity js

view js docs

Introduction

Dominity is a simple and lightweight JavaScript library designed to help u write html like syntax in js to make reusable reactive componets

its reactive hence allows you to automatically update the elements contents when the state changes its coupled with a client side router as well

usage

u can easily add dominity to your HTML file using a script tag or by our npm package

<script src="https://cdn.jsdelivr.net/gh/atoms19/dominity.js@latest/src/DOMINITY.js"></script>

its minified size is tiny and wont impact your performance at all unlike other bulky frameworks so tiny infact its just little less than 5kib

basics

there are 2 styles to use Dominity

1) pure js style 2) html+js style

pure js style

In this style of programming you'll not be touching the HTML file after u placed the dominity.js script tag in your head

You'll be making all(most) elements using dominity's el() function

el(typ, txt = '', attrs = {}): creates an element and attaches it to the body,

• 1st argument specifies the tagname
• 2nd argument text, its option it can be left as blank string ''
• 3rd is argument accepts an object which takes in attributes of the tag as key value pairs

youllbe making child nodes by chaining ._el() which takes the same set of formal argumants any opened tag can be optionally closed by chaining .$end()

see more on syntax section

html + js style

in this style of programming with Dominity you'll be using your HTML file and make a web page traditionally. you'll use dominity functions when you need to bring interactivity or reactivity to the element here Dominity operates similiar to JQuery a popular js library

you can still use el() to curate reusable parts of your app

• $el(qry): Finds and returns a dominity DOM element matching the specified query.

• $$el(qry): Finds and returns an array of dominity DOM elements matching the specified query.

dominity DOM elemnts are are objects that have special methods and props to make it easy to style ,add events ,change attributes etc list of all methods are given as a table in the end of documentation

Dominity DOM elements support chaining for all methods except for those meant to retrive data or child Dominity DOM elements are capable of being stored in a variable like any other object

Simplified Componentization

Dominity allows us to create componets with ease by encapsulating Dominity code in a function. This approach allows developers to create modular and maintainable code structures with ease, utilizing function parameters as component prop

a simple button component

function Button(text,color='red'){
return el('button',text).style({
backgroundColor:color
})
//returning to allow further chaining
}

//addTo() is used to add the component where u want

Button('click me','blue').addTo($el('#h')).onClick((s)=>{
s.style({
backgroundColor:'red'
   })
})
//here button changes color when u click it

$('#s2').addChild(Button('click me','red'))

//addchild can also be used to attach a component

Chaining DOM Elements

Dominity enables chaining of DOM elements using _el() and $end() methods, allowing developers to efficiently construct complex DOM structures in a concise and readable manner.

el('div')._el('p', "Paragraph 1").$end()._el('p', "Paragraph 2").$end();

once use the el() or $el() you are allowed to chain methods to it n number of times , think of it as opening an HTML tag. when u chain the .$end() it closes the tag according to analogy as long as u dont close it u can chain methods to modify, add events or style whatever

you can create a child elemnt by chainig ._el() which is same as el() but syntactically nicer

we recommend using intendation to make it look nice and legible

el('div').
  _el('p','howdy').$end().
  _el('button','join us').onClick(joinAction).$end()
  _el('div').
    _el('img','',{
      alt:'profile pic',
      src:'https://...'
    }).$end()
  .$end()
.$end()

now that you've opened a child tag using ._el() now methods u chain to it will work on the child to go back to working with parent close the child by chainig $end()

in Dominity unlike HTML its not mandatory to close the tag at all if u dont want to go back to working with the parent element

technically when u chain $end() its returning the parent instance back to u so u can continue working on the parent again so in above example last three $end() chain can be entirely omitted and it will still work

note: if u wish to return the element u are working on dont chain $end() to it as it returns its parent

Reactivity System

Dominity has a unique reactive system which isn't complex nor capable as the ones in other ones but its a neat way to make your dominity elements react to data and its tiny

let opinion = reactable('good').as('op');

el("h1","you are so {{op}}").reactTo(opinion)

function reactable() is used to create any litteral that is reactive it can be a integer,float,string,an object an array whats so ever ,it returns an object whixh stores the actual value in the .value property , you have to chain .as() to this to set up the name you'll be using in the text of elems

in elements text string you can use double moustaches to surround the name u gave to reactable with as() and make that element attached to the reactable by using reactTo(<reactableobject>) pass in reactable stored in variable

it carries over to child element if its on parent element as well

in the above example whenever we change the value of opinion by using .set() method its change is reflected on the h1 tag

opinion.set('bad')

given below is an example of a simple counter using dominity

function Counter() {
  let count = reactable(0).as('count');

  el('div').
    _el('p', "count: {{count}}").$end().
    _el('button', "increment").onClick(() => {
      count.set(count.value + 1);
    }).$end().
    _el('button', 'decrement').onClick(() => {
      count.set(count.value - 1);
    }).
    $end().
    reactTo(count);
}

with mixed style it would look like this

<div>
<p id='disp'>count {{count}}</p>
<button id="b1">increment</button>
<button id="b2">decrement</button>
</div>
<script>
let count=reactable(0).as('count')
$el('#disp').reactTo(count)
$el("#b1").onClick(s=>{count.set(count.value+1)})
$el("#b2").onClick(s=>{count.set(count.value-1)})
 <script> 

as you can see in the html +js style more things need to have id and stuff to be identified

reactables can be derived from other reactables which allows one to depend on others value

let name=reactable('vishal')

let nameAsList=reactable().deriveFrom(name,(value)=>{
return Array.from(value)
})

each time name updates its derived one will also update

examples

a simple dropdown

function Dropdown(op=false){
  let open=reactable(op)
  
  return el('div').
    _el('button','dropdown button').onClick(()=>{
     open.set(!open.value)
    })
    .$end().
    _el('div','some very respectable dropdown content').showIf(open)
  
 
}

showIf() only renders the element if the reactable passed into it is truthy it hides otherwise

it can also take in a condition but it wont be dynamic unless it is a reactable

filtering searchbar

function filterSearch(){
  let search=reactable('')
  let items=["potatoes","chicken","rice","bread"]
  
  let filteredItems=reactable().deriveFrom(search,(val)=>{
    return items.filter(i=>i.startsWith(val))
  })

  return el('div').
    _el('input','',{
      placeHolder:'search in filter'
      ,type:'search'
    }).modal(search)
    .$end().
    _el('ul').loops(filteredItems,(item,parent)=>{
        parent.
          _el('li',item)
      }).$end()
  
}

the above example uses a derived reactable using.deriveFrom() method of a reactable to get a filtered list each time search value updates

an interesting method of dominity search element is .modal() which allows you to actively update a reactable whenever its value changes and vice versa

here you can see the derived reactable filtered items is rendered as a list this is done by using .loops() method it accepts a reactable and a callback from the callback function you can access the value of each item in array and also the parent element for adding child elements

fully functional tasks app

let taskname=reactable('')
let tasks=reactable(JSON.parse(localStorage.tasks))
el('form')
  ._el('fieldset','',{
    role:'group'
  }).
    _el('input','',{
      type:'text'
      ,placeHolder:'enter task'
      ,id:'infield'
    }).modal(taskname).$end().
    _el('input','add task',{
      type:'submit'
    }).$end()
  .$end().
  checkFor('submit',(e)=>{
    e.preventDefault()
    if(taskname.value !=''){
      tasks.value.push({
        name:taskname.get(),
        done:false
      })
      tasks.update()
      $el('#infield').value('')
      
    }
  })
  
el('ul').loops(tasks,(obj,p)=>{
  p.
    _el('li').
      _el('input','',{
        type:'checkbox',
       
      }).attr(obj.done?('checked'):'unchecked','').checkFor('input',()=>{
        obj.done=!obj.done
        tasks.setProp('done',obj.done)
        
      })
      
      .$end().
      _el('span',obj.name).style({
        marginRight:'2rem',
        textDecoration:obj.done?'line-through':'none'
      }).$end().
      _el('button','x').class('outline').onClick((s)=>{
 tasks.set(tasks.value.filter(ob=>{
   return ob!=obj
 }))

      })
    
})
  
tasks.subscribe(()=>{
   
 localStorage.tasks=JSON.stringify(tasks.value)
 
})

/*optional link to styleing cause it actually looks horrible without styling*/
el('link','',{
  href:'https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css'
  ,rel:'stylesheet'
})

normally to make something like this it takes a lot of time and thinking but in dominity its all very simple .subscribe() method allows u to call a function when desired reactable is changed

Utility Functions

Dominity offers a few utility functions for common tasks, including copying text and generating random values.

• copy(txt): Copies the specified text to the clipboard of user

• random(end, start = 0): Generates a random value within the specified range, it can also take just an array as argument and it will automatically chose a random element from that array

• range(s, e, increment = 1): Generates an array of numbers within the specified range. it can also generate an array of alphabets

copy("Hello, world!");
let randomNumber = random(1, 100);
let numberRange = range(1, 10);

list of methods

these are all the methods u can chain with any element retrived or created using Dominty functions view full docs methods included:

you can still access orginal elements methods and props by using <dominityElem>.elem.<orginal method>()