@vicaniddouglas/js_aide 1.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, vicaniddouglas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# @vicaniddouglas/js_aide
+
+A versatile collection of modular JavaScript utility helpers designed to streamline single-page application (SPA) development and general web programming tasks. This library provides a set of independent modules for common functionalities such as routing, input handling, validation, and more.
+
+## Description
+
+`@vicaniddouglas/js_aide` bundles frequently needed JavaScript functionalities into a cohesive, easy-to-use package. Each module is designed to be independent, allowing you to import only what you need, reducing bundle size and improving application performance. From dynamic client-side routing to robust input validation and DOM manipulation, this library aims to accelerate your development workflow.
+
+## Features
+
+### `Router`
+
+A modern, feature-rich client-side router for Single-Page Applications (SPAs).
+
+- History API-based navigation.
+- Supports dynamic route segments (e.g., `/users/:id`).
+- Automatic interception of internal `<a>` tags for seamless SPA navigation.
+- Configurable route guards (`beforeNavigate`) with support for redirects.
+- View lifecycle hooks (`beforeEnter`, `beforeLeave`) directly on DOM elements for managing view transitions and data loading.
+- Parses and exposes URL query parameters and hash fragments.
+- Efficient view toggling, only hiding the previously active view.
+
+### `validator`
+
+A module offering various input validation utilities (e.g., email, number, custom regex).
+
+### `inputHandlers`
+
+Utilities for enhanced DOM element interaction, such as restricting input to numbers, formatting number inputs, or providing custom select options.
+
+### `requests`
+
+Helper functions for making HTTP requests (e.g., `fetch` wrappers for common patterns).
+
+### `dates`
+
+Convenience functions for common date and time manipulation tasks.
+
+### `fileManager`
+
+Utilities for browser-side file handling (e.g., file uploads, local storage, file type checks).
+
+### `camera`
+
+Functions for interacting with device cameras, capturing images or video streams (requires browser API support).
+
+### `figures`
+
+Utilities for number formatting, currency (including UGX defaults), and percentages.
+
+### `dependencyManager`
+
+A robust manager for dynamically loading CDN-based libraries (like SheetJS or jsPDF) with retry logic and dependency tracking.
+
+## Installation
+
+Install the package via npm:
+
+```bash
+npm install @vicaniddouglas/js_aide
+```
+
+Or via yarn:
+
+```bash
+yarn add @vicaniddouglas/js_aide
+```
+
+## Usage
+
+Ensure your project is configured to use ES Modules (e.g., by adding `"type": "module"` to your project's `package.json` or using a bundler).
+
+### Importing Modules
+
+You can import specific modules or all of them:
+
+```javascript
+// Import specific modules
+import { Router, validator } from "@vicaniddouglas/js_aide";
+
+// Or import all, though generally not recommended for tree-shaking
+// import * => JSAide from '@vicaniddouglas/js_aide';
+```
+
+### Example: Using the Router
+
+```javascript
+// main.js
+import { Router } from "@vicaniddouglas/js_aide";
+
+// Define your routes, mapping paths to DOM element IDs
+const appRoutes = {
+  "/": "home-view",
+  "/products": "products-list-view",
+  "/products/:id": "product-detail-view", // Dynamic segment
+  "/profile": "user-profile-view",
+};
+
+const router = new Router(appRoutes, "/");
+
+// --- Optional: Add a route guard ---
+router.beforeNavigate = async (toPath, navigationContext) => {
+  console.log(
+    `Attempting to navigate from ${navigationContext.from} to ${toPath}`,
+  );
+
+  // Example: Protect the profile route
+  if (toPath.startsWith("/profile")) {
+    const isAuthenticated = await checkUserAuthentication(); // Your auth logic
+    if (!isAuthenticated) {
+      console.warn(
+        "Access denied: User not authenticated. Redirecting to login.",
+      );
+      return "/login"; // Redirect to a login page
+    }
+  }
+  return true; // Allow navigation
+};
+
+// --- Optional: Listen for navigation events ---
+window.addEventListener("router:navigated", (event) => {
+  const { path, pathname, params, query, hash } = event.detail;
+  console.log(`Navigated to: ${path}`);
+  console.log("Params:", params); // e.g., { id: '123' } for /products/123
+  console.log("Query:", query); // e.g., { search: 'item' } for /search?search=item
+  console.log("Hash:", hash); // e.g., '#section1' for /page#section1
+});
+
+// --- Example: Define view lifecycle hooks on your DOM elements ---
+// Assuming you have a <div id="product-detail-view"> in your HTML
+const productDetailView = document.getElementById("product-detail-view");
+if (productDetailView) {
+  productDetailView.beforeEnter = async (routeParams) => {
+    console.log(`Entering product detail view for ID: ${routeParams.id}`);
+    // Fetch product data based on routeParams.id
+    const product = await fetchProductData(routeParams.id);
+    // Render product details into the view
+    renderProductDetails(productDetailView, product);
+  };
+
+  productDetailView.beforeLeave = () => {
+    console.log("Leaving product detail view. Cleaning up...");
+    // Dispose of any event listeners or resources specific to this view
+    cleanupProductDetailResources();
+  };
+}
+
+// Manually navigate (or click an <a> tag)
+router.navigate("/products/123?utm_source=email#overview");
+```
+
+## Development
+
+### Running Tests
+
+We use **Vitest** for unit testing. The library has over 80+ verified tests covering all core modules (Routing, Validation, WebSocket, Dates, etc.).
+
+```bash
+npm test
+```
+
+### Building for Production
+
+Generates minified **ESM**, **IIFE**, and **CJS** bundles in the `dist` folder using esbuild.
+
+```bash
+npm run build
+```
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).