DegreeSign UI

A lightweight, dependency-free TypeScript library of frontend essentials for web app UI: DOM controls, instant hCaptcha implementation, on-demand script and stylesheet loading, and preflight-free faster requests.

Table of Contents

• Why DegreeSign UI
• Install
• Quick Start
• CDN Usage
• API Reference
  • selectElement
  • selectAll
  • showElement
  • hideElement
  • repeatElements
  • loadScript
  • createCaptcha
  • FASTER_HEADER
  • Enums and Types
• Error Handling
• FAQ
• Keywords
• Contributing
• License

Why DegreeSign UI

• Zero dependencies. No runtime packages, no bloat, no transitive risk.
• TypeScript-first. Written in TypeScript and ships complete type definitions.
• Tiny and tree-shakeable. Import only the helpers you use.
• Framework-agnostic. Works with React, Vue, Svelte, Angular, plain JavaScript, or no framework at all.
• Browser and CDN ready. Use it as an ES module, a CommonJS module, or a global dsUI UMD bundle.
• Batteries included. DOM selection and visibility, element repetition, lazy script/style loading, hCaptcha setup, and a preflight-free request header in one package.

Install

Install the package via npm:

npm install @degreesign/ui

Or via yarn:

yarn add @degreesign/ui

Or via pnpm:

pnpm add @degreesign/ui

Or use it in the browser through a CDN:

<script src="https://cdn.jsdelivr.net/npm/@degreesign/[email protected]/dist/browser/degreesign.min.js"></script>

Quick Start

Import the functions from @degreesign/ui in your TypeScript or JavaScript project:

import {
    selectElement,
    selectAll,
    showElement,
    hideElement,
    repeatElements,
    createCaptcha,
    loadScript,
    FASTER_HEADER,
} from '@degreesign/ui';

// Select and reveal an element
const panel = selectElement('#panel');
showElement(panel);

// Work with a collection
const rows = selectAll('.row', '#list');

// Make a faster, preflight-free request
await fetch('https://api.example.com/v1/endpoint', {
    method: 'POST',
    headers: FASTER_HEADER,
    body: JSON.stringify({ hello: 'world' }),
});

CDN Usage

Use the package directly in the browser without a build step by loading the UMD bundle from a CDN:

<script src="https://cdn.jsdelivr.net/npm/@degreesign/[email protected]/dist/browser/degreesign.min.js"></script>

The bundle exposes a global dsUI object containing all exported functions, enums, and constants:

<div id="myDiv">Hello</div>
<script>
    const el = dsUI.selectElement('#myDiv');
    dsUI.showElement(el);
    dsUI.hideElement(el);
</script>

API Reference

selectElement

Selects a single DOM element by its CSS selector, optionally within a parent element.

selectElement(id: string, parent?: Element | string): HTMLElement

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | string | Yes | The CSS selector (e.g. #myId, .myClass) of the element to select. | | parent | Element \| string | No | Parent element or selector to search within. Defaults to document. |

Returns: HTMLElement

const myDiv = selectElement('#myDiv');
myDiv.textContent = 'Hello, World!';

const parent = selectElement('.container');
const child = selectElement('.child', parent);
child.style.color = 'blue';

selectAll

Selects all DOM elements matching a CSS selector, optionally within a parent element.

selectAll(id: string, parent?: Element | string): NodeListOf<Element>

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | string | Yes | The CSS selector (e.g. .myClass, div) used to match elements. | | parent | Element \| string | No | Parent element or selector to search within. Defaults to document. |

Returns: NodeListOf<Element>

const items = selectAll('.item');
items.forEach(item => item.style.backgroundColor = 'lightgray');

const parent = selectElement('#parent');
const divs = selectAll('div', parent);
divs.forEach(div => div.classList.add('highlight'));

showElement

Sets an element's display style to flex, making it visible.

showElement(element?: HTMLElement | null): void

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | element | HTMLElement \| null | No | The element to show. Null-safe and a no-op when omitted. |

const myDiv = selectElement('#myDiv');
showElement(myDiv); // Displays the element with flex layout

hideElement

Sets an element's display style to none, hiding it.

hideElement(element?: HTMLElement | null): void

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | element | HTMLElement \| null | No | The element to hide. Null-safe and a no-op when omitted. |

const myDiv = selectElement('#myDiv');
hideElement(myDiv); // Hides the element

repeatElements

Repeats or removes child elements within a parent to match a target count by cloning or removing the first child.

repeatElements(options: { children?: NodeListOf<Element> | HTMLCollection | HTMLElement[]; parent?: Element | HTMLElement | string; targetCount: number }): void

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | children | NodeListOf<Element> \| HTMLCollection \| HTMLElement[] | No | Child elements to repeat or remove. Defaults to the parent's children. | | parent | Element \| HTMLElement \| string | No | Parent element or selector where children are added or removed. | | targetCount | number | Yes | The desired number of child elements. |

<div id="parent">
  <div class="child">Item</div>
</div>

// Repeat child elements to a total of 5
const parent = selectElement('#parent');
const children = selectAll('.child', parent);
repeatElements({ parent, children, targetCount: 5 });
// Result: 5 child divs inside #parent

// Reduce to 2 child elements
repeatElements({ parent, children: selectAll('.child', parent), targetCount: 2 });
// Result: 2 child divs inside #parent

loadScript

Loads an external script or stylesheet once and caches the returned promise, so repeated calls with the same src share a single network request.

loadScript(params: LoadScriptParams): Promise<boolean>

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | src | string | Yes | The resource URL. | | type | ResourceType | No | ResourceType.Script (default) or ResourceType.Stylesheet. | | ready | () => boolean | No | Readiness check polled after load. Defaults to the load event. | | interval | number | No | Readiness poll interval in milliseconds. Defaults to 100. | | timeout | number | No | Maximum wait in milliseconds. Defaults to 30000. | | hideConsoleErrors | boolean | No | Set to true to disable console logging. |

Returns: Promise<boolean> — resolves to true on success and false on failure.

const loaded = await loadScript({ src: 'https://example.com/lib.js', hideConsoleErrors: true });

// Load a stylesheet instead
await loadScript({ src: 'https://example.com/theme.css', type: ResourceType.Stylesheet });

createCaptcha

Creates an hCaptcha form inside a parent element and loads the hCaptcha script on demand.

createCaptcha(params: CreateCaptchaParams): CreateCaptcha

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | parentTag | string \| HTMLElement | Yes | The parent element or CSS selector that will contain the captcha form. | | sitekey | string | Yes | The hCaptcha site key. | | hideConsoleErrors | boolean | No | Set to true to disable console logging. |

Returns: CreateCaptcha

| Member | Type | Description | | --- | --- | --- | | reloadCaptcha | () => Promise<HTMLFormElement \| undefined> | Resets the captcha widget, or creates the form and loads the script, resolving to the HTMLFormElement on success and undefined on failure. | | getCaptchaToken | () => string | Returns the current captcha response token, or an empty string. |

const
    {
        reloadCaptcha,
        getCaptchaToken,
    } = createCaptcha({
        parentTag: '.captcha_wrapper',
        sitekey: 'your-sitekey' // obtain from https://dashboard.hcaptcha.com/sites
    }),
    captchaFrame = await reloadCaptcha(); // HTMLFormElement when loaded

// after user is ready
if (captchaFrame) {
    const token = getCaptchaToken();
    reloadCaptcha(); // optional
};

FASTER_HEADER

A ready-made Content-Type header for requests to a server built with @degreesign/server.

A cross-origin application/json request is not a CORS "simple request", so the browser first sends an OPTIONS (preflight) call. Because text/plain is a simple content type, using FASTER_HEADER skips that preflight and can roughly double request speed, while the trailing type=application/json parameter tells the server to parse the body as JSON.

| Export | Type | Description | | --- | --- | --- | | FASTER_HEADER | HeadersInit | A preflight-free Content-Type header: text/plain;charset=UTF-8;type=application/json. |

import { FASTER_HEADER } from '@degreesign/ui';

await fetch(`https://api.example.com/v1/endpoint`, {
    method: `POST`,
    headers: FASTER_HEADER,
    body: JSON.stringify({ hello: `world` }),
});

Enums and Types

| Export | Kind | Values / Description | | --- | --- | --- | | ResourceType | enum | Script = 'text/javascript', Stylesheet = 'stylesheet'. | | Display | enum | Flex = 'flex', None = 'none'. | | CreateCaptchaParams | type | Options accepted by createCaptcha. | | CreateCaptcha | type | Object returned by createCaptcha. | | LoadScriptParams | type | Options accepted by loadScript. |

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.

createCaptcha and loadScript accept a hideConsoleErrors option to suppress their console logging when a load fails or times out. Pass a fallback-aware call and check the resolved value to handle failures gracefully.

FAQ

What is DegreeSign UI? DegreeSign UI is a lightweight, dependency-free TypeScript library of frontend essentials for web app UI, including DOM controls, instant hCaptcha implementation, on-demand script loading, and preflight-free faster requests.

Is it free? Yes. It is open source and released under the MIT License.

Does it work in Node.js and the browser? It is built for browser environments and relies on the DOM and window. The package provides both a browser bundle and a Node-targeted build, but the DOM features themselves require a browser or a DOM implementation such as jsdom.

Does it have any dependencies? No. It has zero runtime dependencies.

Is it written in TypeScript? Yes. It is written in TypeScript and ships complete type definitions, so you get autocomplete and type checking out of the box.

Which frameworks does it support? It is framework-agnostic and works with React, Vue, Svelte, Angular, plain JavaScript, or no framework at all.

Can I use it without a build step? Yes. Load the UMD bundle from a CDN and use the global dsUI object.

Keywords

DegreeSign, DegreeSign UI, frontend UI library, DOM utilities, DOM manipulation, select element, hCaptcha, captcha, script loader, lazy load scripts, stylesheet loader, preflight, CORS preflight, faster requests, TypeScript, JavaScript, browser, no dependencies, tree-shakeable, framework-agnostic, web app UI.

Contributing

Contributions are welcome! Please open an issue or submit a pull request at https://github.com/DegreeSign/ds_ui.

License

This project is licensed under the MIT License. See the LICENSE file for details.