@degreesign/ui 1.1.0 → 1.1.1

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.1.1/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.1.1/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,n)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.repeatElements=void 0;const r=n(698);t.repeatElements=({children:e,parent:t,targetCount:n})=>{try{const o=(0,r.parentValid)(t);if(e=e||o?.children,e?.length){const t=e?.length||0;if(n>t){const r=e?.[0];if(r)for(let e=t;e<n;e++)o?o.appendChild(r.cloneNode(!0)):r?.after(r.cloneNode(!0))}else if(n<t&&0!=n)for(let r=t-1;r>=n;r--)e[r]?.remove()}}catch(e){console.log("repeatElements failed",n,e)}}},613:(e,t)=>{var n,r,o,l;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"}(n||(t.ResourceType=n={})),function(e){e.Link="link",e.Script="script"}(r||(t.TagName=r={})),function(e){e.Flex="flex",e.None="none"}(o||(t.Display=o={})),function(e){e.String="string"}(l||(t.TypeName=l={}))},698:(e,t,n)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.hideElement=t.showElement=t.selectAll=t.selectElement=t.parentValid=void 0;const r=n(613),o=e=>typeof e==r.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=r.Display.Flex),t.hideElement=e=>e&&(e.style.display=r.Display.None)},924:(e,t,n)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.loadScript=void 0;const r=n(613),o={};t.loadScript=({src:e,type:t=r.ResourceType.Script,ready:n,interval:l=100,timeout:c=3e4,hideConsoleErrors:i})=>{try{const s=o[e];if(s)return s;const a=new Promise(((o,s)=>{let a,p,d=!1;const u=e=>{d||(d=!0,p&&clearTimeout(p),a&&clearTimeout(a),e?s():o())},m=()=>{if(!d)return!n||n()?u():void(a=setTimeout(m,l))};let y;if(p=setTimeout((()=>{i||console.log("loadScript timed out",e),u(!0)}),c),t===r.ResourceType.Stylesheet){const t=document.createElement(r.TagName.Link);t.rel=r.ResourceType.Stylesheet,t.href=e,y=t}else{const t=document.createElement(r.TagName.Script);t.type=r.ResourceType.Script,t.src=e,t.async=!0,y=t}y.onload=m,y.onerror=t=>{i||console.log("loadScript failed onload",e,t),u(t)},document.head.appendChild(y)}));return o[e]=a,a.catch((()=>{o[e]===a&&delete o[e]})),a}catch(e){i||console.log("loadScript failed",e)}}}},t={};function n(r){var o=t[r];if(void 0!==o)return o.exports;var l=t[r]={exports:{}};return e[r](l,l.exports,n),l.exports}var r={};return(()=>{var e=r;Object.defineProperty(e,"__esModule",{value:!0}),e.Display=e.ResourceType=e.loadScript=e.repeatElements=e.hideElement=e.showElement=e.selectAll=e.selectElement=void 0;const t=n(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=n(516);Object.defineProperty(e,"repeatElements",{enumerable:!0,get:function(){return o.repeatElements}});const l=n(924);Object.defineProperty(e,"loadScript",{enumerable:!0,get:function(){return l.loadScript}});const c=n(613);Object.defineProperty(e,"ResourceType",{enumerable:!0,get:function(){return c.ResourceType}}),Object.defineProperty(e,"Display",{enumerable:!0,get:function(){return c.Display}})})(),r})()));

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,7 @@
-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 { ResourceType, Display } from './types';
+import type { LoadScriptParams } from './types';
+export { selectElement, selectAll, showElement, hideElement, repeatElements, loadScript, ResourceType, Display, };
+export type { 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,l;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"}(l||(t.TypeName=l={}))},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:l=100,timeout:c=3e4,hideConsoleErrors:i})=>{try{const s=o[e];if(s)return s;const a=new Promise(((o,s)=>{let a,u,p=!1;const d=e=>{p||(p=!0,u&&clearTimeout(u),a&&clearTimeout(a),e?s():o())},m=()=>{if(!p)return!r||r()?d():void(a=setTimeout(m,l))};let y;if(u=setTimeout((()=>{i||console.log("loadScript timed out",e),d(!0)}),c),t===n.ResourceType.Stylesheet){const t=document.createElement(n.TagName.Link);t.rel=n.ResourceType.Stylesheet,t.href=e,y=t}else{const t=document.createElement(n.TagName.Script);t.type=n.ResourceType.Script,t.src=e,t.async=!0,y=t}y.onload=m,y.onerror=t=>{i||console.log("loadScript failed onload",e,t),d(t)},document.head.appendChild(y)}));return o[e]=a,a.catch((()=>{o[e]===a&&delete o[e]})),a}catch(e){i||console.log("loadScript failed",e)}}}},t={};function r(n){var o=t[n];if(void 0!==o)return o.exports;var l=t[n]={exports:{}};return e[n](l,l.exports,r),l.exports}var n={};(()=>{var e=n;Object.defineProperty(e,"__esModule",{value:!0}),e.Display=e.ResourceType=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 l=r(924);Object.defineProperty(e,"loadScript",{enumerable:!0,get:function(){return l.loadScript}});const c=r(613);Object.defineProperty(e,"ResourceType",{enumerable:!0,get:function(){return c.ResourceType}}),Object.defineProperty(e,"Display",{enumerable:!0,get:function(){return c.Display}})})();var o=exports;for(var l in n)o[l]=n[l];n.__esModule&&Object.defineProperty(o,"__esModule",{value:!0})})();

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+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 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.1.1",
   "description": "DegreeSign UI Controls",
   "main": "dist/node/degreesign.node.min.js",
   "module": "dist/node/degreesign.node.min.js",