@etcoder-642/dynamicJS

A lightweight JavaScript UI library providing essential dynamic components like interactive dropdowns and image carousels, designed for easy integration into any web project.

Table of Contents

1. Installation
2. Usage - createDropdown
3. HTML Structure
4. CSS Styling for Dropdown
5. JavaScript Initialization for Dropdown
6. Usage - createImageCarousel
7. HTML Structure for Carousel
8. CSS Styling for Carousel
9. JavaScript Initialization for Carousel
10. Important Notes

Installation

You can install @etcoder-642/dynamicJS using npm or yarn:

npm install @etcoder-642/dynamicJS

#OR

yarn add @etcoder-642/dynamicJS

Usage - createDropdown

The createDropdown function transforms a simple <ul> list into an interactive dropdown menu. It supports showing/hiding content on hover and updating the dropdown's label on item click.

HTML Structure for Dropdown

Your dropdown should be an <ul> element with the class dropdown. The first <li> element will act as the dropdown label/trigger, and subsequent <li> elements will be the hidden menu items.

<ul class="dropdown">
  <li>Select an Option</li> <!-- This is your dropdown label/trigger -->
  <li>Option 1</li>
  <li>Option 2</li>
  <li>Option 3</li>
</ul>

<!-- You can have multiple dropdowns -->
<ul class="dropdown">
  <li>Choose Category</li>
  <li>Category A</li>
  <li>Category B</li>
</ul>

CSS Styling for Dropdown

Example Basic styling for the dropdown container

.dropdown {
  display: inline-block; /* Allows dropdowns to sit side-by-side if needed */
  border: 1px solid #ccc;
  border-radius: 4px;
  background-color: white;
  min-width: 150px;
  list-style: none;
  padding: 0;
  margin: 10px;
  cursor: pointer;
  box-shadow: 0 2px 5px rgba(0,0,0,0.1);
  font-family: sans-serif;
  z-index: 100; /* Ensure dropdown appears above other content */
}

/* Style for the dropdown label (the first li) */
.dropdown li:first-child {
  padding: 10px 15px;
  font-weight: bold;
  background-color: #f0f0f0;
  border-radius: 4px;
}

/* Styling for the hidden menu items (all li except the first) */
.dropdown li:not(:first-child) {
  padding: 10px 15px;
  cursor: pointer;
  /* These will be controlled by JavaScript's display property */
  /* display: none; by default, set to display: block; on hover */
  background-color: white;
  border-top: 1px solid #eee;
}

/* Hover effect for menu items */
.dropdown li:not(:first-child):hover {
  background-color: #e0e0e0;
}

Recommendation for Dropdown Visuals

For a more efficacious visual stacking of dropdown items that are position: absolute, it is advisable to encase all actual menu items (excluding the label) within a discrete div container. This container shall then be subjected to position: absolute, thereby enabling its internal elements to adhere to standard block flow or flexbox/grid layouts for proper vertical alignment.

<ul class="dropdown">
  <li>Select an Option</li>
  <div class="dropdown-menu-items"> <!-- New container -->
    <li>Option 1</li>
    <li>Option 2</li>
    <li>Option 3</li>
  </div>
</ul>

.dropdown-menu-items {
  position: absolute;
  top: 100%; /* Below the label */
  left: 0;
  width: 100%; /* Match parent dropdown width */
  background-color: white;
  border: 1px solid #ccc;
  border-top: none; /* No top border if it's separate from label */
  box-shadow: 0 2px 5px rgba(0,0,0,0.1);
  border-radius: 0 0 4px 4px; /* Rounded bottom corners */
  display: none; /* Hidden by default, toggled by JS */
  z-index: 99; /* Ensure it's below the main dropdown */
}
.dropdown-menu-items li {
  padding: 10px 15px;
  cursor: pointer;
}
/* JS would toggle display on .dropdown-menu-items */

JavaScript Initialization for Dropdown

Import createDropdown and apply it to each dropdown element on your page.

import { createDropdown } from '@etcoder-642/dynamicJS';
document.querySelectorAll(".dropdown").forEach(createDropdown);

Usage - createImageCarousel

The createImageCarousel function transforms a <ul> list of images into a basic image carousel with left/right navigation arrows.

HTML Structure for Carousel

Your carousel should be a container element (e.g., div) with the class image-carousel. Inside it, place a <ul> element containing <li> elements, where each <li> represents a slide (typically containing an <img> tag).

<div class="image-carousel">
  <ul>
    <li><img src="path/to/image1.jpg" alt="Description of image 1"></li>
    <li><img src="path/to/image2.jpg" alt="Description of image 2"></li>
    <li><img src="path/to/image3.jpg" alt="Description of image 3"></li>
  </ul>
  <!-- A container for dots/pagination can go here, will be populated by JS -->
  <div class="carousel-dots"></div>
</div>

<!-- You can have multiple carousels -->
<div class="image-carousel">
  <ul>
    <li><img src="path/to/another-image-a.jpg" alt="Another A"></li>
    <li><img src="path/to/another-image-b.jpg" alt="Another B"></li>
  </ul>
</div>

CSS Styling for Carousel

Essential CSS is required for the carousel layout, including the positioning of slides and navigation arrows. This library applies some necessary styles directly via JavaScript for the arrows' positioning. However, you will need to add base CSS for the carousel container, slides, and arrows' visual appearance.

Container for the entire carousel

.image-carousel {
    position: relative; /* REQUIRED: For positioning arrows and slides */
    width: 100%; /* Or fixed width */
    max-width: 600px; /* Example max width */
    overflow: hidden; /* Hides slides that are off-screen */
    margin: 20px auto; /* Center on page */
    border: 1px solid #ddd;
    border-radius: 8px;
    box-shadow: 0 4px 8px rgba(0,0,0,0.1);
    background-color: white;
    box-sizing: border-box; /* Include padding/border in width */
}

/* The list of slides */
.image-carousel ul {
    list-style: none;
    padding: 0;
    margin: 0;
    display: flex; /* Arranges list items horizontally */
    transition: transform 0.5s ease-in-out; /* Smooth transition for sliding */
    width: 100%; /* Ensure the ul occupies available width */
}

/* Individual slide items */
.image-carousel ul li {
    min-width: 100%; /* Each slide takes up the full width of the viewable area */
    flex-shrink: 0; /* Prevents slides from shrinking */
    box-sizing: border-box;
    display: flex; /* For centering content within li */
    justify-content: center;
    align-items: center;
    height: 300px; /* Fixed height for consistent slide presentation */
    /* background-color: #f0f0f0; (Optional placeholder background) */
    overflow: hidden; /* Ensure image doesn't spill out */
}

.image-carousel ul li img {
    max-width: 100%;
    max-height: 100%;
    object-fit: contain; /* Scales image to fit without cropping */
    display: block; /* Remove extra space below image */
}

/* Styles for arrows (JS adds .arrow, .left, .right classes) */
.arrow {
    background-color: rgba(0, 0, 0, 0.5); /* Semi-transparent background */
    color: white;
    border: none;
    padding: 10px 15px;
    font-size: 1.5rem;
    border-radius: 50%; /* Make them circular */
    display: flex;
    justify-content: center;
    align-items: center;
    line-height: 1; /* Adjust vertical alignment of text */
    transition: background-color 0.3s ease;
    z-index: 10; /* Ensure arrows are above slides */
    /* Positioning (absolute, top, transform, left/right) is set by JS */
}

.arrow:hover {
    background-color: rgba(0, 0, 0, 0.7);
}

JavaScript Initialization for Carousel

Import createImageCarousel and apply it to each carousel element on your page.

import { createImageCarousel } from '@etcoder-642/dynamicJS';

document.querySelectorAll(".image-carousel").forEach(createImageCarousel);

Important Notes

CSS Dependency

For both createDropdown and createImageCarousel, while some critical styles are applied programmatically by the library, it is incumbent upon the implementer to incorporate the recommended CSS into their project's stylesheet. This is indispensable for the proper visual rendition and functional efficacy of the components (e.g., position: relative on containers, base styling for elements).

Dropdown Overlap

The extant implementation of the createDropdown function necessitates the manipulation of the display property for each constituent li item comprising the menu. Should these li elements be concurrently subjected to position: absolute, a superimposition of their graphical representations is liable to occur. In conventional dropdown methodologies where vertical item stacking is desired, the customary practice involves encapsulating all li elements, excluding the initial label element, within a singular div element, upon which position: absolute is then imposed.

The management of this wrapper div's display property would subsequently govern the visibility of its contained elements.

Consequently, if each li element is individually assigned position: absolute along with an identical top: 0 offset (relative to its ul.dropdown containing block), a state of vertical convergence and resultant overlap shall be manifest.

Carousel Transition

The createImageCarousel function effectuates slide transitions by manipulating the display property (none vs. flex). This engenders an immediate change in visibility rather than a smooth animation. For seamless visual progression, a more advanced implementation leveraging CSS transform: translateX() in conjunction with the transition property is typically employed, as has been expounded upon in prior discursive exchanges.

Modular Design

This library facilitates the exportation of individual functions, thereby enabling the selective utilization of only those components requisite for a given implementation, thus contributing to an optimized bundle size.