domManager.update

domManager

The domManager module is responsible for creating, updating, reading, and deleting DOM elements.

update()

The update() function is responsible for modifying information and attributes of elements in the DOM. It allows actions such as toggling className, adding a class to classList, updating id, and modifying certain attributes.

Parameters/Inputs:

• instruction: object

The function takes in an object containing instructions on how an element should be modified. The structure of this object is as follows:

{
    selector: ".content > div",
    action: "toggle",
    className: "active"
}

The selector and action properties are required. If either of them is missing, the function should throw an error. Depending on the action, additional properties may be required, and if they are missing, the function should also throw an error.

Here's another example demonstrating the use of update() to replace items:

{
    selector: ".content > div",
    action: "replace",
    newClassName: "active",
    oldClassName: "disabled"
}

The values after the keywords new and old should be valid attributes; otherwise, an error should be thrown.

An action of update should be capable of modifying all valid attributes that the elements might have. For example, you can update innerHTML with the following object:

{
    selector: ".content > div",
    action: "update",
    innerHTML: "<p>New Text</p>"
}

The update() function should be able to update children of the selected element and other properties. Children are expected to be objects and should be created using _createElement(). For example:

{
    selector: ".content > div",
    action: "update",
    children: [
        {
            tagName: "div",
            options: { classList: ["nv-graph", "active"], style: { color: "red" } }
        }
    ]
}

Although this approach is valid, it's advisable for developers to use domManage.create() to create or append new children.

update() should be able to modify all valid attributes of an element such as id, textContent, value, dataset, etc.

Two more accepted action values are add and remove. These should add or remove specific values from attributes or properties of an element. For example, 'add' should add a specified className to the classList, and remove should remove a specified className from the classList.

add should work for other properties as well, like innerHTML, value, and more. The key difference between add and update is that update removes the old content while add doesn't.

remove should remove specified values from properties, but this may not work for all properties. For example, you cannot remove a certain paragraph from innerHTML using remove. The remove action will have more constraints than others, and these constraints should be clearly documented.

The accepted actions are: toggle | replace | update | add | remove. The function should return an error if the action is not one of the accepted actions. Note that certain actions will have more constraints than others, for example, remove and toggle. These constraints should be thoroughly documented in the function's documentation.

Given the complexity and functionality of the function, it's essential to carefully consider how each component will operate. Additionally, creating private helper functions is necessary to achieve all the required and expected functionalities.

domManager.create

domManager

The domManager module is responsible for creating, updating, reading, and deleting DOM elements.

create()

The create() function's responsibility is to generate DOM elements and append them to a designated element.

Parameters/Input:

• element: object
• selector: string (optional)

The create function should accept an element and an optional selector as input. The element parameter should be an object with the following structure:

{
    tagName: "div",
    children: [...],
    options: {
        classList: [...],
        id: "...",
        link: {...},
        attributes: {...},
    },
}

The tagName is a required property, and the function create should throw an error if it's not provided.

The create function should utilize private helper functions. For instance, a function named createElement can be created. This function takes an element object as a parameter, creates an HTMLElement using the tagName and options, and then returns the HTMLElement.

Additionally, if a function has link in the options, create should invoke router.configureLink() with the appropriate parameters. You can read more about it here #6 .

In the case where an element has children, the function should iterate over them, create them using createElement, and append them to the element. Here's an example:

if (element.children) {
    for (const child of element.children) {
        const childEl = _createElement(child);
        htmlElement.appendChild(childEl);
    }
}

The htmlElement should be appended to the specified selector. If no selector is provided, it should default to #root. If the specified selector doesn't exist, the function should throw an error. Here's an example:

const parent = document.querySelector(selector);

if (!parent) {
    // go ahead and throw an error
} else {
    parent.appendChild(htmlElement);
}

store.getState

store

The store will hold variables that are intended to be accessible throughout the app. Users will be able to retrieve and modify these variables from anywhere within the app.

getState

getState() takes a property name as input and returns the value of that property.

Parameter/Input:

• key: string

The function returns the value of the key if it exists, and undefined if it doesn't.

Inside createStyleSheet, we can have something which can toggle styles according to a boolean variable. Kind of button on off kind of action. If it is ok, I can start work on this.

createStyleSheet.configureStateRule

createStyleSheet

The createStyleSheet module facilitates the creation and application of CSS styles to elements. It's important to note that this module isn't intended to replace traditional CSS, but rather to provide an API for efficiently adding CSS rules to elements using JavaScript when it's the most suitable approach.

createStyleSheet.configureStateRule

The createStyleSheet.configureStateRule function is intended to add styles to an element when it is in a certain state, such as changing the color of a paragraph when it is in the hover state. The function is expected to receive inputs structured like this:

{ 
    "button:hover": {
         backgroundColor: "purple",
    }
}

However, it's important to note that this function is not a priority, and achieving this functionality is more effectively done using CSS. This module is not meant to replace CSS, but to assist developers in adding styles when using CSS is not the most appropriate approach.

router.deactivate

router

The router module is responsible for registering routes, linking pages, and configuring URLs.

deactivate

deactivate() is responsible for removing the class name active from specific elements.

Parameters/Inputs:

• name: string

The function should take a name as input and find all links with a name that matches the provided name. It should then remove the class active from their classList.

router.configureLink

router

The router module is responsible for registering routes, linking pages, and configuring URLs.

configureLink

Parameters/Input:

• linkInfo: object

The configureLink() function expects an object containing specific information about the element intended to act as a link, and it adds a click event listener to it. Here's the expected object structure:

{
    name: "navigation",
    to: "home",
    host: ".sidebar",
    element: HTMLElement
}

All the properties mentioned above are required, except for host. host is a selector that determines where to (in this case, 'home') should be rendered. If host is not provided, the function should append the contents inside #root. The to property should be a valid id corresponding to objects stored in a private array within router called pages. If these constraints are not met, the function should throw an error.

The router should maintain a private array to keep track of all the links, and configureLink() should push the linkInfo object into this array after validation.

The function should then create a click event listener that, when triggered, finds a page with an id matching the value of linkInfo.to. It should use domManager(page, host) to create the element. After creating the element, the function should invoke activateLink() and deactivateLinks() with linkInfo.name as a parameter. deactivateLinks() should be invoked first.

domManager.delete

domManager

The domManager module is responsible for creating, updating, reading, and deleting DOM elements.

delete()

The delete() function is responsible for removing an element or elements from the DOM.

Parameters/Inputs:

• selector: string
• all: boolean (optional)

The function accepts two parameters: selector (string) and all (boolean), with a default value of false.

delete() should remove the specified element from the DOM, or if all is set to true, it should remove all elements that match the selector.

domManager.read

domManager

The domManager module is responsible for creating, updating, reading, and deleting DOM elements.

read()

The read() function is responsible for retrieving data from a specific element.

Parameters/Inputs:

• selector: string
• attributeName: string (optional)
• all: boolean (optional)

The function should accept three parameters: selector, attributeName (optional), and all (optional).

The function will utilize querySelector(selector) to retrieve the element. If this returns undefined, the function should throw an error. Subsequently, it should return the value of the requested attribute. If the attributeName is not a qualified name, an error should be thrown. If attributeName is not specified, the function should return the element as is. By default, all is set to false, but if the user sets all to true, the function should use querySelectorAll(selector) instead. If all is true and attributeName is specified, the function should return an array containing the values of that attributeName. For example, if the user invokes domManager.read(".content", "dataset", true), the function should return an array of datasets for elements with a class name of .content. However, if attributeName is not specified and all is set to true, the function should return a NodeList or an array containing all elements with the specified selector.

The current implementation of before and after only works for the first-generation elements and doesn't work for their children which is undesirable.

I would like to have a function addEvent() to add events. By using this function ,user can easily add the events for the required html elements by just passing them as parameters.

It increases code readability .
The user can import the callback functions and re-use them.
The user can just focus on writing the eventHandlers rather than getting the HTML element each time and adding event listeners.

The code should be something like this.
addEvent(selector,event,eventHandler,all); , this should add the event for the HTML element matching the selector. all should be default false , when set to true the function should add the event for the elements matching the selector.

And the function should validate all the parameters.

store.updateState

store

The store will hold variables that are intended to be accessible throughout the app. Users will be able to retrieve and modify these variables from anywhere within the app.

updateState

Parameters/Input:

• key: string
• newValue: any

The updateState() function takes a key and a newValue, and it updates the property associated with that key. If the key doesn't exist, it throws an error.

createStyleSheet.createCSSRule

createStyleSheet

The createStyleSheet module facilitates the creation and application of CSS styles to elements. It's important to note that this module isn't intended to replace traditional CSS, but rather to provide an API for efficiently adding CSS rules to elements using JavaScript when it's the most suitable approach.

createCSSRule

Parameters/Inputs:

• rules: object
• save: boolean (optional)

The createStyleSheet module contains a private array named CSSRule. If save is set to true (which is the default behaviour), the function will push the provided rules to CSSRule. If save is set to false, it will not.

The function should iterate through the keys and values of the rules object. Each key represents a selector, and the corresponding value represents a declaration. For each selector and declaration, the function should invoke addStyle(selector, declaration).

For handling states and media queries, other functions like createMediaQueryRule and configureStateRule should be utilized to handle the job.

Here's an example of how the function should operate:

import { createStyleSheet } from '@dom-manipulation-library/dml'

createStyleSheet.createCSSRule({
   'body': {
       color: '#f8f8f8',
       backgroundColor: '#0fa',
   },

   '#main > .content': {
       overflow: 'hidden',
   },
});

Update actions can differ and can be, addChild, removeChild, and newChildren.

createStyleSheet.addStyle

createStyleSheet

The createStyleSheet module facilitates the creation and application of CSS styles to elements. It's important to note that this module isn't intended to replace traditional CSS, but rather to provide an API for efficiently adding CSS rules to elements using JavaScript when it's the most suitable approach.

addStyle

Parameters/Inputs:

• element: HTMLElement
• declaration: object

The addStyle function accepts two parameters: element and declaration. It iterates over the declaration to extract the property and its corresponding value. The function then applies the style to the element using the following syntax: element.style[property] = value.

router.activate

router

The router module is responsible for registering routes, linking pages, and configuring URLs.

activate

activate() is a private function responsible for adding the active className to a specific element.

Parameters/Inputs:

• element: HTMLElement

The function takes an element as input and adds the active class to its classList.

store.createStore

store

The store will hold variables that are intended to be accessible throughout the app. Users will be able to retrieve and modify these variables from anywhere within the app.

createStore

The createStore() function takes an object and stores it in a private variable within the store. The function should throw an error if invoked for the second time.

'div' is the most used element in web development, it makes sense to make it the default of tagName.

Make 'text' outside of options because it is widely used.

The store throws an error stating a property doesn't exist even though it does.

createStyleSheet.createMediaQueryRule

createStyleSheet

The createStyleSheet module facilitates the creation and application of CSS styles to elements. It's important to note that this module isn't intended to replace traditional CSS, but rather to provide an API for efficiently adding CSS rules to elements using JavaScript when it's the most suitable approach.

createMediaQueryRule

The createMediaQueryRule function is a private function intended to be used by createCSSRule. While I am not sure about the exact implementation details, it is expected to receive an object as input with a structure similar to the one below:

{
    "@media screen and (min-width: 300px)": {
         "body": {
             backgroundColor: "red",
          },
    },
}

Based on this input, the function should appropriately apply styles to elements within the specified media query. However, it's important to note that this function is not a priority, as achieving the same result can be easily done with traditional CSS. This module is not intended to replace CSS but to assist developers in adding styles when using CSS is not the most suitable option.

router.register

router

The router module is responsible for registering routes, linking pages, and configuring URLs.

register

The router module maintains an array to store all the routes, and the register() function will simply push the provided routes into this array.

Parameters/Inputs:

• routes: array

The register() function should accept an array of objects containing information about a route. The array should have this structure:

[
    { id: "home", route: home },
    { id: "about", route: about },
    { id: "contact", route: contact }
]

In this array, route should be an object, and id must be unique. If these constraints are not met, the function should throw an error.

It's important to note that register() should be invoked only once throughout the app. If it is invoked more than once, the function should throw an error.

OPTIONAL:
At this stage, the router module is not expected to handle URLs. However, if you are feeling ambitious and decide to implement this functionality, you should create a separate private function to handle URL changes and update the #root. This function should also set the initial URL to match the id of index. By default router shouldn't handle URLs but you can add an optional parameter that the user can set to true to enable this feature.