@degreesign/ui 1.1.0 → 1.2.0

package/README.md

@@ -1,9 +1,6 @@
 # DegreeSign UI functions
 
-A lightweight TypeScript library for managing UI elements in web applications.
-
-
-
+A lightweight, dependency-free TypeScript library for selecting, showing, hiding, repeating, and dynamically loading UI elements and resources in web applications.
 
 ## Setup
 
@@ -13,25 +10,52 @@ Install the package via npm:
 npm install @degreesign/ui
 ```
 
+OR via yarn:
+
+```bash
+yarn add @degreesign/ui
+```
+
 OR use in browsers through CDN
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@degreesign/ui@1.0.8/dist/browser/degreesign.min.js"></script>
+<script 
+    src="https://cdn.jsdelivr.net/npm/@degreesign/ui@1.2.0/dist/browser/degreesign.min.js"
+></script>
 ```
 
 ## Usage
 
 Import the functions from the `@degreesign/ui` package in your TypeScript or JavaScript project:
 
-```javascript
-import { selectElement, selectAll, showElement, hideElement, repeatElements } from '@degreesign/ui';
+```ts
+import { selectElement, selectAll, showElement, hideElement, repeatElements, loadScript } from '@degreesign/ui';
 ```
 
 Below are the available functions and their usage examples.
 
+## CDN Usage
+
+Use the package directly in the browser without a build step by loading the UMD bundle from a CDN:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@degreesign/ui@1.2.0/dist/browser/degreesign.min.js"></script>
+```
+
+The bundle exposes a global `dsUI` object containing all exported functions and enums:
+
+```html
+<div id="myDiv">Hello</div>
+<script>
+    const el = dsUI.selectElement('#myDiv');
+    dsUI.showElement(el);
+    dsUI.hideElement(el);
+</script>
+```
+
 ## Functions
 
-### `selectElement(id: string, parent?: Element) => HTMLElement`
+### Select Element
 
 Selects a single DOM element by its CSS selector, optionally within a parent element.
 
@@ -42,7 +66,7 @@ Selects a single DOM element by its CSS selector, optionally within a parent ele
 **Returns:** An `HTMLElement`.
 
 **Example:**
-```javascript
+```ts
 // Select an element by ID
 const myDiv = selectElement('#myDiv');
 myDiv.textContent = 'Hello, World!';
@@ -53,7 +77,7 @@ const child = selectElement('.child', parent);
 child.style.color = 'blue';
 ```
 
-### `selectAll(id: string, parent?: Element) => NodeListOf<Element>`
+### Select All
 
 Selects all DOM elements matching a CSS selector, optionally within a parent element.
 
@@ -64,7 +88,7 @@ Selects all DOM elements matching a CSS selector, optionally within a parent ele
 **Returns:** A `NodeListOf<Element>`.
 
 **Example:**
-```javascript
+```ts
 // Select all elements with a class
 const items = selectAll('.item');
 items.forEach(item => item.style.backgroundColor = 'lightgray');
@@ -75,7 +99,7 @@ const divs = selectAll('div', parent);
 divs.forEach(div => div.classList.add('highlight'));
 ```
 
-### `showElement(element: HTMLElement) => void`
+### Show Element
 
 Sets an element's display style to `flex`, making it visible.
 
@@ -83,12 +107,12 @@ Sets an element's display style to `flex`, making it visible.
 - `element`: The `HTMLElement` to show.
 
 **Example:**
-```javascript
+```ts
 const myDiv = selectElement('#myDiv');
 showElement(myDiv); // Displays the element with flex layout
 ```
 
-### `hideElement(element: HTMLElement) => void`
+### Hide Element
 
 Sets an element's display style to `none`, hiding it.
 
@@ -96,12 +120,12 @@ Sets an element's display style to `none`, hiding it.
 - `element`: The `HTMLElement` to hide.
 
 **Example:**
-```javascript
+```ts
 const myDiv = selectElement('#myDiv');
 hideElement(myDiv); // Hides the element
 ```
 
-### `repeatElements({ children?: NodeListOf<Element>, parent: Element, targetCount: number }) => void`
+### Repeat Elements
 
 Repeats or removes child elements within a parent to match a target count by cloning or removing the first child.
 
@@ -111,7 +135,7 @@ Repeats or removes child elements within a parent to match a target count by clo
 - `targetCount`: The desired number of child elements.
 
 **Example:**
-```javascript
+```ts
 // HTML structure:
 // <div id="parent">
 //   <div class="child">Item</div>
@@ -128,6 +152,21 @@ repeatElements({ parent, children: selectAll('.child', parent), targetCount: 2 }
 // Result: 2 child divs inside #parent
 ```
 
+### Load Script
+
+Loads an external script or stylesheet once and caches the returned promise.
+
+**Parameters:**
+- `src`: The resource URL.
+- `hideConsoleErrors` (optional): Set to `true` to disable console logging.
+
+**Returns:** A `Promise<void>`.
+
+**Example:**
+```ts
+loadScript({ src: 'https://example.com/lib.js', hideConsoleErrors: true });
+```
+
 ## Error Handling
 
 The `repeatElements` function includes error handling to catch and log issues when manipulating elements. For example, if the `children` NodeList is invalid or cloning fails, an error will be logged to the console.

package/dist/browser/degreesign.min.js

@@ -1,2 +1,2 @@
 /*! For license information please see degreesign.min.js.LICENSE.txt */
-!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define([],t):"object"==typeof exports?exports.degreesign=t():e.degreesign=t()}(this,(()=>(()=>{"use strict";var e={};return(()=>{var t=e;Object.defineProperty(t,"__esModule",{value:!0}),t.repeatElements=t.hideElement=t.showElement=t.selectAll=t.selectElement=void 0;const o=e=>("string"==typeof e&&(e=document.querySelector(e)),e);t.selectElement=(e,t)=>(o(t)||document)?.querySelector(e),t.selectAll=(e,t)=>(o(t)||document)?.querySelectorAll(e),t.showElement=e=>e&&(e.style.display="flex"),t.hideElement=e=>e&&(e.style.display="none"),t.repeatElements=({children:e,parent:t,targetCount:l})=>{try{const n=o(t);if(e=e||n?.children,e?.length){const t=e?.length||0;if(l>t){const o=e?.[0];if(o)for(let e=t;e<l;e++)n?n.appendChild(o.cloneNode(!0)):o?.after(o.cloneNode(!0))}else if(l<t&&0!=l)for(let o=t-1;o>=l;o--)e[o]?.remove()}}catch(e){console.log("Error repeating elements",l,e)}}})(),e})()));
+!function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t():"function"==typeof define&&define.amd?define([],t):"object"==typeof exports?exports.dsUI=t():e.dsUI=t()}(this,(()=>(()=>{"use strict";var e={516:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.repeatElements=void 0;const n=r(698);t.repeatElements=({children:e,parent:t,targetCount:r})=>{try{const o=(0,n.parentValid)(t);if(e=e||o?.children,e?.length){const t=e?.length||0;if(r>t){const n=e?.[0];if(n)for(let e=t;e<r;e++)o?o.appendChild(n.cloneNode(!0)):n?.after(n.cloneNode(!0))}else if(r<t&&0!=r)for(let n=t-1;n>=r;n--)e[n]?.remove()}}catch(e){console.log("repeatElements failed",r,e)}}},613:(e,t)=>{var r,n,o,c;Object.defineProperty(t,"__esModule",{value:!0}),t.TypeName=t.Display=t.TagName=t.ResourceType=void 0,function(e){e.Script="text/javascript",e.Stylesheet="stylesheet"}(r||(t.ResourceType=r={})),function(e){e.Link="link",e.Script="script"}(n||(t.TagName=n={})),function(e){e.Flex="flex",e.None="none"}(o||(t.Display=o={})),function(e){e.String="string"}(c||(t.TypeName=c={}))},698:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.hideElement=t.showElement=t.selectAll=t.selectElement=t.parentValid=void 0;const n=r(613),o=e=>typeof e==n.TypeName.String?document.querySelector(e):e;t.parentValid=o,t.selectElement=(e,t)=>(o(t)||document)?.querySelector(e),t.selectAll=(e,t)=>(o(t)||document)?.querySelectorAll(e),t.showElement=e=>e&&(e.style.display=n.Display.Flex),t.hideElement=e=>e&&(e.style.display=n.Display.None)},924:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.loadScript=void 0;const n=r(613),o={};t.loadScript=({src:e,type:t=n.ResourceType.Script,ready:r,interval:c=100,timeout:a=3e4,hideConsoleErrors:l})=>{try{const s=o[e];if(s)return s;const i=new Promise(((o,s)=>{let i,p,d=!1;const u=e=>{d||(d=!0,p&&clearTimeout(p),i&&clearTimeout(i),e?s():o())},m=()=>{if(!d)return!r||r()?u():void(i=setTimeout(m,c))};let f;if(p=setTimeout((()=>{l||console.log("loadScript timed out",e),u(!0)}),a),t===n.ResourceType.Stylesheet){const t=document.createElement(n.TagName.Link);t.rel=n.ResourceType.Stylesheet,t.href=e,f=t}else{const t=document.createElement(n.TagName.Script);t.type=n.ResourceType.Script,t.src=e,t.async=!0,f=t}f.onload=m,f.onerror=t=>{l||console.log("loadScript failed onload",e,t),u(t)},document.head.appendChild(f)}));return o[e]=i,i.catch((()=>{o[e]===i&&delete o[e]})),i}catch(e){l||console.log("loadScript failed",e)}}},926:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.createCaptcha=void 0;const n=r(924),o=r(698),c=window;t.createCaptcha=({parentTag:e,sitekey:t,hideConsoleErrors:r})=>{try{const a="https://js.hcaptcha.com/1/api.js",l=(0,o.parentValid)(e),s=document.createElement("form"),i=document.createElement("div"),p=()=>s.elements.namedItem("h-captcha-response")?.value||"",d=()=>{c.hcaptcha?c.hcaptcha.reset():(0,n.loadScript)({src:a,hideConsoleErrors:r})};if(l)return s.name="cap",s.classList.add("captcha_frame"),i.classList.add("h-captcha"),i.dataset.sitekey=t,s.appendChild(i),l.appendChild(s),(0,n.loadScript)({src:a,hideConsoleErrors:r}),{captchaFrame:s,getCaptchaToken:p,resetCaptcha:d}}catch(e){console.log("createCaptcha failed",e)}return{getCaptchaToken:()=>"",resetCaptcha:()=>console.log("createCaptcha load failed")}}}},t={};function r(n){var o=t[n];if(void 0!==o)return o.exports;var c=t[n]={exports:{}};return e[n](c,c.exports,r),c.exports}var n={};return(()=>{var e=n;Object.defineProperty(e,"__esModule",{value:!0}),e.Display=e.ResourceType=e.createCaptcha=e.loadScript=e.repeatElements=e.hideElement=e.showElement=e.selectAll=e.selectElement=void 0;const t=r(698);Object.defineProperty(e,"selectElement",{enumerable:!0,get:function(){return t.selectElement}}),Object.defineProperty(e,"selectAll",{enumerable:!0,get:function(){return t.selectAll}}),Object.defineProperty(e,"showElement",{enumerable:!0,get:function(){return t.showElement}}),Object.defineProperty(e,"hideElement",{enumerable:!0,get:function(){return t.hideElement}});const o=r(516);Object.defineProperty(e,"repeatElements",{enumerable:!0,get:function(){return o.repeatElements}});const c=r(924);Object.defineProperty(e,"loadScript",{enumerable:!0,get:function(){return c.loadScript}});const a=r(926);Object.defineProperty(e,"createCaptcha",{enumerable:!0,get:function(){return a.createCaptcha}});const l=r(613);Object.defineProperty(e,"ResourceType",{enumerable:!0,get:function(){return l.ResourceType}}),Object.defineProperty(e,"Display",{enumerable:!0,get:function(){return l.Display}})})(),n})()));

package/dist/code/captcha.d.ts

@@ -0,0 +1,5 @@
+import { CreateCaptcha, CreateCaptchaParams } from '../types';
+declare const 
+/** Create captcha form */
+createCaptcha: ({ parentTag, sitekey, hideConsoleErrors, }: CreateCaptchaParams) => CreateCaptcha;
+export { createCaptcha, };

package/dist/code/populate.d.ts

@@ -0,0 +1,11 @@
+declare const 
+/** Repeat Elements */
+repeatElements: ({ children, parent, targetCount, }: {
+    /** Child Element Nodes */
+    children?: NodeListOf<Element> | HTMLCollection | HTMLElement[];
+    /** Parent Element */
+    parent?: Element | HTMLElement | string;
+    /** Target Count */
+    targetCount: number;
+}) => void;
+export { repeatElements, };

package/dist/code/scripts.d.ts

@@ -0,0 +1,5 @@
+import type { LoadScriptParams } from '../types';
+declare const 
+/** Load external script once */
+loadScript: ({ src, type, ready, interval, timeout, hideConsoleErrors, }: LoadScriptParams) => Promise<void> | undefined;
+export { loadScript, };

package/dist/code/select.d.ts

@@ -0,0 +1,13 @@
+import { Display } from '../types';
+declare const 
+/** Validate parent element */
+parentValid: (parent?: Element | string) => Element | undefined, 
+/** Select element by selector */
+selectElement: (id: string, parent?: Element | string) => HTMLElement, 
+/** Select all by selector */
+selectAll: (id: string, parent?: Element | string) => NodeListOf<Element>, 
+/** Show element */
+showElement: (element?: HTMLElement | null) => Display.Flex | null | undefined, 
+/** Hide element */
+hideElement: (element?: HTMLElement | null) => Display.None | null | undefined;
+export { parentValid, selectElement, selectAll, showElement, hideElement, };

package/dist/index.d.ts

@@ -1,11 +1,8 @@
-declare const selectElement: (id: string, parent?: Element | string) => HTMLElement, selectAll: (id: string, parent?: Element | string) => NodeListOf<Element>, showElement: (element?: HTMLElement | null) => "flex" | null | undefined, hideElement: (element?: HTMLElement | null) => "none" | null | undefined, 
-/** Repeat Elements */
-repeatElements: ({ children, parent, targetCount, }: {
-    /** Child Element Nodes */
-    children?: NodeListOf<Element> | HTMLCollection | HTMLElement[];
-    /** Parent Element */
-    parent?: Element | HTMLElement | string;
-    /** Target Count */
-    targetCount: number;
-}) => void;
-export { selectElement, selectAll, showElement, hideElement, repeatElements, };
+import { selectElement, selectAll, showElement, hideElement } from './code/select';
+import { repeatElements } from './code/populate';
+import { loadScript } from './code/scripts';
+import { createCaptcha } from './code/captcha';
+import { ResourceType, Display } from './types';
+import type { CreateCaptcha, CreateCaptchaParams, LoadScriptParams } from './types';
+export { selectElement, selectAll, showElement, hideElement, repeatElements, loadScript, createCaptcha, ResourceType, Display, };
+export type { CreateCaptcha, CreateCaptchaParams, LoadScriptParams, };

package/dist/node/degreesign.node.min.js

@@ -1,2 +1,2 @@
 /*! For license information please see degreesign.node.min.js.LICENSE.txt */
-(()=>{"use strict";var e={};(()=>{var t=e;Object.defineProperty(t,"__esModule",{value:!0}),t.repeatElements=t.hideElement=t.showElement=t.selectAll=t.selectElement=void 0;const l=e=>("string"==typeof e&&(e=document.querySelector(e)),e);t.selectElement=(e,t)=>(l(t)||document)?.querySelector(e),t.selectAll=(e,t)=>(l(t)||document)?.querySelectorAll(e),t.showElement=e=>e&&(e.style.display="flex"),t.hideElement=e=>e&&(e.style.display="none"),t.repeatElements=({children:e,parent:t,targetCount:o})=>{try{const n=l(t);if(e=e||n?.children,e?.length){const t=e?.length||0;if(o>t){const l=e?.[0];if(l)for(let e=t;e<o;e++)n?n.appendChild(l.cloneNode(!0)):l?.after(l.cloneNode(!0))}else if(o<t&&0!=o)for(let l=t-1;l>=o;l--)e[l]?.remove()}}catch(e){console.log("Error repeating elements",o,e)}}})();var t=exports;for(var l in e)t[l]=e[l];e.__esModule&&Object.defineProperty(t,"__esModule",{value:!0})})();
+(()=>{"use strict";var e={516:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.repeatElements=void 0;const n=r(698);t.repeatElements=({children:e,parent:t,targetCount:r})=>{try{const o=(0,n.parentValid)(t);if(e=e||o?.children,e?.length){const t=e?.length||0;if(r>t){const n=e?.[0];if(n)for(let e=t;e<r;e++)o?o.appendChild(n.cloneNode(!0)):n?.after(n.cloneNode(!0))}else if(r<t&&0!=r)for(let n=t-1;n>=r;n--)e[n]?.remove()}}catch(e){console.log("repeatElements failed",r,e)}}},613:(e,t)=>{var r,n,o,c;Object.defineProperty(t,"__esModule",{value:!0}),t.TypeName=t.Display=t.TagName=t.ResourceType=void 0,function(e){e.Script="text/javascript",e.Stylesheet="stylesheet"}(r||(t.ResourceType=r={})),function(e){e.Link="link",e.Script="script"}(n||(t.TagName=n={})),function(e){e.Flex="flex",e.None="none"}(o||(t.Display=o={})),function(e){e.String="string"}(c||(t.TypeName=c={}))},698:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.hideElement=t.showElement=t.selectAll=t.selectElement=t.parentValid=void 0;const n=r(613),o=e=>typeof e==n.TypeName.String?document.querySelector(e):e;t.parentValid=o,t.selectElement=(e,t)=>(o(t)||document)?.querySelector(e),t.selectAll=(e,t)=>(o(t)||document)?.querySelectorAll(e),t.showElement=e=>e&&(e.style.display=n.Display.Flex),t.hideElement=e=>e&&(e.style.display=n.Display.None)},924:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.loadScript=void 0;const n=r(613),o={};t.loadScript=({src:e,type:t=n.ResourceType.Script,ready:r,interval:c=100,timeout:a=3e4,hideConsoleErrors:l})=>{try{const s=o[e];if(s)return s;const i=new Promise(((o,s)=>{let i,p,d=!1;const u=e=>{d||(d=!0,p&&clearTimeout(p),i&&clearTimeout(i),e?s():o())},m=()=>{if(!d)return!r||r()?u():void(i=setTimeout(m,c))};let h;if(p=setTimeout((()=>{l||console.log("loadScript timed out",e),u(!0)}),a),t===n.ResourceType.Stylesheet){const t=document.createElement(n.TagName.Link);t.rel=n.ResourceType.Stylesheet,t.href=e,h=t}else{const t=document.createElement(n.TagName.Script);t.type=n.ResourceType.Script,t.src=e,t.async=!0,h=t}h.onload=m,h.onerror=t=>{l||console.log("loadScript failed onload",e,t),u(t)},document.head.appendChild(h)}));return o[e]=i,i.catch((()=>{o[e]===i&&delete o[e]})),i}catch(e){l||console.log("loadScript failed",e)}}},926:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.createCaptcha=void 0;const n=r(924),o=r(698),c=window;t.createCaptcha=({parentTag:e,sitekey:t,hideConsoleErrors:r})=>{try{const a="https://js.hcaptcha.com/1/api.js",l=(0,o.parentValid)(e),s=document.createElement("form"),i=document.createElement("div"),p=()=>s.elements.namedItem("h-captcha-response")?.value||"",d=()=>{c.hcaptcha?c.hcaptcha.reset():(0,n.loadScript)({src:a,hideConsoleErrors:r})};if(l)return s.name="cap",s.classList.add("captcha_frame"),i.classList.add("h-captcha"),i.dataset.sitekey=t,s.appendChild(i),l.appendChild(s),(0,n.loadScript)({src:a,hideConsoleErrors:r}),{captchaFrame:s,getCaptchaToken:p,resetCaptcha:d}}catch(e){console.log("createCaptcha failed",e)}return{getCaptchaToken:()=>"",resetCaptcha:()=>console.log("createCaptcha load failed")}}}},t={};function r(n){var o=t[n];if(void 0!==o)return o.exports;var c=t[n]={exports:{}};return e[n](c,c.exports,r),c.exports}var n={};(()=>{var e=n;Object.defineProperty(e,"__esModule",{value:!0}),e.Display=e.ResourceType=e.createCaptcha=e.loadScript=e.repeatElements=e.hideElement=e.showElement=e.selectAll=e.selectElement=void 0;const t=r(698);Object.defineProperty(e,"selectElement",{enumerable:!0,get:function(){return t.selectElement}}),Object.defineProperty(e,"selectAll",{enumerable:!0,get:function(){return t.selectAll}}),Object.defineProperty(e,"showElement",{enumerable:!0,get:function(){return t.showElement}}),Object.defineProperty(e,"hideElement",{enumerable:!0,get:function(){return t.hideElement}});const o=r(516);Object.defineProperty(e,"repeatElements",{enumerable:!0,get:function(){return o.repeatElements}});const c=r(924);Object.defineProperty(e,"loadScript",{enumerable:!0,get:function(){return c.loadScript}});const a=r(926);Object.defineProperty(e,"createCaptcha",{enumerable:!0,get:function(){return a.createCaptcha}});const l=r(613);Object.defineProperty(e,"ResourceType",{enumerable:!0,get:function(){return l.ResourceType}}),Object.defineProperty(e,"Display",{enumerable:!0,get:function(){return l.Display}})})();var o=exports;for(var c in n)o[c]=n[c];n.__esModule&&Object.defineProperty(o,"__esModule",{value:!0})})();

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export declare enum ResourceType {
+    Script = "text/javascript",
+    Stylesheet = "stylesheet"
+}
+export declare enum TagName {
+    Link = "link",
+    Script = "script"
+}
+export declare enum Display {
+    Flex = "flex",
+    None = "none"
+}
+export declare enum TypeName {
+    String = "string"
+}
+export type LibsWindow = Window & {
+    hcaptcha?: {
+        reset: (id?: string) => void;
+    };
+};
+export interface CreateCaptchaParams {
+    /** Parent element or selector */
+    parentTag: string | HTMLElement;
+    /** hCaptcha site key */
+    sitekey: string;
+    /** Disable console logging */
+    hideConsoleErrors?: boolean;
+}
+export interface CreateCaptcha {
+    captchaFrame?: HTMLFormElement;
+    getCaptchaToken: () => string;
+    resetCaptcha: () => void;
+}
+export type LoadScriptParams = {
+    /** Resource URL */
+    src: string;
+    /** Resource type */
+    type?: ResourceType;
+    /** Defaults to load event */
+    ready?: () => boolean;
+    /** Readiness poll (ms) */
+    interval?: number;
+    /** Max wait (ms) */
+    timeout?: number;
+    /** Disable console logging */
+    hideConsoleErrors?: boolean;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@degreesign/ui",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "DegreeSign UI Controls",
   "main": "dist/node/degreesign.node.min.js",
   "module": "dist/node/degreesign.node.min.js",