@trunkjs/browser-utils 1.0.12

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+## 1.0.12 (2025-08-11)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.11 (2025-08-11)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.10 (2025-08-11)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.9 (2025-08-11)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.8 (2025-08-11)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.7 (2025-08-07)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.6 (2025-08-07)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.5 (2025-08-07)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.4 (2025-08-07)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.3 (2025-08-07)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.2 (2025-08-07)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.1 (2025-08-07)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+# 1.0.0 (2025-08-07)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.

package/README.md

@@ -0,0 +1,267 @@
+# @trunkjs/browser-utils
+
+A small collection of browser-focused, framework-agnostic utilities that make common DOM and timing tasks easier. All utilities are written in TypeScript and ship as ES modules.
+
+Exports:
+- create_element: Minimal DOM element factory
+- Debouncer: Debounce helper with optional max-delay
+- Stopwatch: Lightweight performance timer with lap logging
+- waitFor, waitForDomContentLoaded, waitForLoad, sleep, waitForAnimationEnd: Promise-based event and timing helpers
+- LoggingMixin: Lightweight logging mixin for Custom Elements
+
+## Installation
+
+Within this monorepo, the package is consumed via path aliases. If you publish or consume it externally, import from the package name:
+
+```ts
+import {
+  create_element,
+  Debouncer,
+  Stopwatch,
+  waitFor,
+  waitForDomContentLoaded,
+  waitForLoad,
+  sleep,
+  waitForAnimationEnd,
+  LoggingMixin,
+} from '@trunkjs/browser-utils';
+```
+
+Note: Several utilities depend on browser globals (window, document, performance). Use them in browser-like environments.
+
+## Quick start
+
+### Create and append an element
+
+```ts
+import { create_element } from '@trunkjs/browser-utils';
+
+const card = create_element('section', { class: 'card', 'aria-live': 'polite' }, [
+  create_element('h2', {}, 'Title'),
+  create_element('p', {}, 'This is a paragraph.'),
+  create_element('button', { disabled: true }, 'Disabled'),
+]);
+
+document.body.appendChild(card);
+```
+
+Notes:
+- Attributes with value true create boolean attributes (e.g. disabled becomes disabled="").
+- Attributes with null or undefined are omitted.
+
+### Debounce input handling
+
+```ts
+import { Debouncer } from '@trunkjs/browser-utils';
+
+const debouncer = new Debouncer(300, 2000); // 300ms debounce, 2s max delay
+const input = document.querySelector('input[type="search"]')!;
+
+input.addEventListener('input', async () => {
+  await debouncer.wait(); // resets while typing; fires within 2s max
+  // Trigger the expensive operation here
+  console.log('Searching for:', input.value);
+});
+```
+
+Alternatively, execute a function directly:
+
+```ts
+const saveDebouncer = new Debouncer(500);
+window.addEventListener('resize', () => {
+  saveDebouncer.debounce(() => {
+    console.log('Resized!');
+  });
+});
+```
+
+### Measure performance with Stopwatch
+
+```ts
+import { Stopwatch } from '@trunkjs/browser-utils';
+
+const sw = new Stopwatch('Render');
+// ... do stuff
+sw.lap('after step 1');
+// ... do more stuff
+sw.lap('after step 2');
+console.debug('Total ms:', sw.stop());
+```
+
+### Enable conditional logging in custom elements (LoggingMixin)
+
+```ts
+import { LoggingMixin } from '@trunkjs/browser-utils';
+
+class MyEl extends LoggingMixin(HTMLElement) {
+  connectedCallback() {
+    // Only prints if the element has a truthy debug attribute
+    this.log('connected');
+    // Always prints
+    this.warn('Heads up');
+    this.error('Something went wrong?');
+  }
+}
+
+customElements.define('my-el', MyEl);
+
+// <my-el debug></my-el>        // enables debug logging
+// <my-el debug="false"></my-el> // disables debug logging
+// <my-el></my-el>               // debug logging disabled by default
+```
+
+Tip:
+- If you toggle the debug attribute at runtime, call el.invalidateDebugCache() so the mixin re-evaluates the attribute on the next log/warn/error call.
+
+### Promise-based event helpers
+
+```ts
+import { waitFor, waitForDomContentLoaded, waitForLoad, sleep, waitForAnimationEnd } from '@trunkjs/browser-utils';
+
+await waitForDomContentLoaded(); // resolves when DOM is ready
+await waitForLoad(); // resolves when all resources are loaded
+
+// Wait for a specific event
+const clickEvent = await waitFor<MouseEvent>(document.getElementById('btn')!, 'click');
+
+// Pause execution
+await sleep(250);
+
+// Wait for CSS animation to finish
+await waitForAnimationEnd(document.querySelector('.animate')!);
+```
+
+## API Reference
+
+### create_element(tag, attrs?, children?)
+
+- Signature:
+  - create_element(tag: string, attrs?: Record<string, string | true | null | undefined>, children?: (Node | string)[] | string | Node): HTMLElement
+- Behavior:
+  - Creates an element, sets provided attributes, and appends children.
+  - children can be a single Node/string or an array.
+  - Attribute values:
+    - true → renders as a boolean attribute with an empty value (e.g. disabled="")
+    - null/undefined → attribute is omitted
+    - string → sets the attribute to the given string
+
+Example:
+```ts
+create_element('input', { type: 'checkbox', checked: true });
+```
+
+### class Debouncer
+
+- constructor(delay: number, max_delay: number | false = false)
+  - delay: debounce window in ms
+  - max_delay: maximum time a call may be deferred. If false, no max is applied.
+- wait(): Promise<true>
+  - Returns a promise that resolves after delay ms since the last call.
+  - If max_delay is set and exceeded, the pending timer is not cleared and will resolve soon.
+- debounce(callback: () => void): void
+  - Schedules callback to run after delay ms since the last call.
+
+Use cases:
+- User input throttling (search boxes)
+- Resize or scroll handlers
+- Preventing excessive network calls
+
+### class Stopwatch
+
+- constructor(label: string, enabled: boolean = true)
+- lap(msg?: string): void
+  - Logs a lap line to console.debug in format: [label] msg +Xs
+- elapsed(): number
+  - Milliseconds since start
+- reset(): void
+- stop(): number
+  - Stops the stopwatch and returns elapsed ms
+- start(): void
+  - Starts (or restarts) and resets timings
+- isRunning(): boolean
+
+Notes:
+- Uses performance.now() for high-resolution timing
+- If enabled is false, lap is a no-op
+
+### LoggingMixin(Base)
+
+- Signature:
+  - LoggingMixin<TBase extends abstract new (...args: any[]) => object>(Base: TBase): class extends Base
+- Adds methods and properties to your Custom Element base class:
+  - log(...args: any[]): void
+    - Logs to console.log only when debug is enabled.
+  - warn(...args: any[]): void
+    - Always logs to console.warn (independent of debug).
+  - error(...args: any[]): void
+    - Always logs to console.error (independent of debug).
+  - get _debug(): boolean
+    - Indicates whether debug logging is enabled for the instance.
+  - invalidateDebugCache(): void
+    - Clears the cached debug flag. Call this after changing the debug attribute dynamically.
+
+How debug is determined:
+- On first call to log/warn/error, the mixin checks the element’s debug attribute and caches the result.
+- The attribute is considered truthy if present and not one of: "false", "0", "off", "no".
+  - Examples:
+    - <my-el debug></my-el> → debug ON
+    - <my-el debug="true"></my-el> → debug ON
+    - <my-el debug="false"></my-el> → debug OFF
+    - <my-el></my-el> → debug OFF
+- If you toggle the attribute at runtime, call invalidateDebugCache() so the next call re-evaluates it.
+
+Usage:
+```ts
+class MyEl extends LoggingMixin(HTMLElement) {
+  connectedCallback() {
+    this.log('connected');  // prints only if debug is ON
+    this.warn('warning');   // always prints
+    this.error('error');    // always prints
+  }
+}
+```
+
+### waitFor<T>(target, eventName, options?)
+
+- Signature:
+  - waitFor<T>(target: EventTarget, eventName: string, options?: AddEventListenerOptions): Promise<T>
+- Resolves with the event object T upon first occurrence.
+
+### waitForDomContentLoaded()
+
+- Resolves once the DOM is ready (DOMContentLoaded).
+- If the document is already past loading, resolves immediately.
+
+### waitForLoad()
+
+- Resolves once the window load event fires.
+- If the document is already complete, resolves immediately.
+
+### sleep(ms)
+
+- Signature: sleep(ms: number): Promise<void>
+- Resolves after the given delay.
+
+### waitForAnimationEnd(element)
+
+- Signature: waitForAnimationEnd(element: HTMLElement): Promise<AnimationEvent>
+- Resolves when the element fires animationend.
+
+## Building
+
+Run `nx build browser-utils` to build the library.
+
+The library is configured for:
+- ES module output
+- TypeScript declaration generation via vite-plugin-dts
+- Vite rollup bundling
+
+## Running unit tests
+
+Run `nx test browser-utils` to execute the unit tests via Vitest.
+
+## Notes and caveats
+
+- Environment: Some utilities require browser globals (window, document, performance). Use them in a DOM-capable environment (browser or a DOM-enabled test runner).
+- Types: Debouncer uses NodeJS.Timeout type in typings; in browsers, the runtime value is still a timeout handle and works as expected.
+- LoggingMixin: Designed for Custom Elements (HTMLElement or frameworks like Lit’s ReactiveElement). The debug attribute is cached for performance; call invalidateDebugCache() after toggling it dynamically. warn and error always log regardless of debug state.

package/index.d.ts

@@ -0,0 +1,6 @@
+export * from './lib/create-element';
+export * from './lib/Debouncer';
+export * from './lib/get-error-location';
+export * from './lib/Stopwatch';
+export * from './lib/wait-for';
+export * from './mixins/LoggingMixin';

package/index.js

@@ -0,0 +1,162 @@
+var h = Object.defineProperty;
+var l = (e) => {
+  throw TypeError(e);
+};
+var f = (e, t, n) => t in e ? h(e, t, { enumerable: !0, configurable: !0, writable: !0, value: n }) : e[t] = n;
+var r = (e, t, n) => f(e, typeof t != "symbol" ? t + "" : t, n), c = (e, t, n) => t.has(e) || l("Cannot " + n);
+var a = (e, t, n) => (c(e, t, "read from private field"), n ? n.call(e) : t.get(e)), m = (e, t, n) => t.has(e) ? l("Cannot add the same private member more than once") : t instanceof WeakSet ? t.add(e) : t.set(e, n), u = (e, t, n, i) => (c(e, t, "write to private field"), i ? i.call(e, n) : t.set(e, n), n);
+function b(e, t = {}, n = []) {
+  Array.isArray(n) || (n = [n]);
+  const i = document.createElement(e);
+  for (const s in t)
+    t[s] !== null && t[s] !== void 0 && i.setAttribute(s, t[s] !== !0 ? t[s] : "");
+  for (const s of n)
+    i.append(typeof s == "string" ? document.createTextNode(s) : s);
+  return i;
+}
+class w {
+  /**
+   *
+   * @param delay     Debounce delay in milliseconds
+   * @param max_delay Maximum delay in milliseconds, if false then no maximum delay is applied
+   */
+  constructor(t, n = !1) {
+    r(this, "timeout", null);
+    r(this, "startTimeWithMs", 0);
+    this.delay = t, this.max_delay = n;
+  }
+  async wait() {
+    return this.startTimeWithMs === 0 && (this.startTimeWithMs = Date.now()), this.timeout && (this.max_delay === !1 || this.startTimeWithMs + this.max_delay > Date.now()) && clearTimeout(this.timeout), new Promise((t) => {
+      this.timeout = setTimeout(() => {
+        this.startTimeWithMs = 0, t(!0);
+      }, this.delay);
+    });
+  }
+  debounce(t) {
+    this.timeout && clearTimeout(this.timeout), this.timeout = setTimeout(() => {
+      t();
+    }, this.delay);
+  }
+}
+function p(e) {
+  if (typeof e.lineNumber == "number")
+    return {
+      file: e.fileName || e.sourceURL,
+      line: e.lineNumber,
+      column: e.columnNumber ?? void 0
+    };
+  if (typeof e.line == "number")
+    return {
+      file: e.sourceURL,
+      line: e.line,
+      column: e.column
+    };
+  const n = String(e.stack || e.message || "").split(`
+`), i = /(.*?)(?:\(|@)?(.*?):(\d+):(\d+)\)?$/;
+  for (const s of n) {
+    const o = s.match(i);
+    if (o)
+      return { file: o[2], line: +o[3], column: +o[4] };
+  }
+  return { file: e.fileName || e.sourceURL };
+}
+class L {
+  constructor(t, n = !0) {
+    r(this, "label");
+    r(this, "last");
+    r(this, "startTime");
+    r(this, "running", !1);
+    r(this, "enabled");
+    this.label = t, this.enabled = n, this.startTime = this.last = performance.now(), this.running = !0;
+  }
+  lap(t = "") {
+    if (!this.enabled) return;
+    const n = performance.now(), i = (n - this.last) / 1e3;
+    this.last = n, console.debug(`[${this.label}] ${t} +${i.toFixed(3)}s`);
+  }
+  elapsed() {
+    return performance.now() - this.startTime;
+  }
+  reset() {
+    this.startTime = this.last = performance.now();
+  }
+  stop() {
+    return this.running = !1, this.elapsed();
+  }
+  start() {
+    this.running = !0, this.reset();
+  }
+  isRunning() {
+    return this.running;
+  }
+}
+function T(e, t, n) {
+  return new Promise((i, s) => {
+    const o = (d) => {
+      e.removeEventListener(t, o, n), i(d);
+    };
+    e.addEventListener(t, o, n);
+  });
+}
+function y() {
+  return document.readyState === "loading" ? new Promise((e) => {
+    document.addEventListener("DOMContentLoaded", () => e());
+  }) : Promise.resolve();
+}
+function v() {
+  return document.readyState === "complete" ? Promise.resolve() : new Promise((e) => {
+    window.addEventListener("load", () => e());
+  });
+}
+function E(e) {
+  return new Promise((t) => setTimeout(t, e));
+}
+function x(e) {
+  return new Promise((t) => {
+    const n = (i) => {
+      e.removeEventListener("animationend", n), t(i);
+    };
+    e.addEventListener("animationend", n);
+  });
+}
+function M(e) {
+  var n;
+  class t extends e {
+    constructor() {
+      super(...arguments);
+      m(this, n, null);
+    }
+    /**
+     * Clears the cached debug flag so the attribute will be checked again
+     * on the next log/warn/error call.
+     */
+    invalidateDebugCache() {
+      u(this, n, null);
+    }
+    get _debug() {
+      return a(this, n) !== null ? a(this, n) : (this instanceof HTMLElement && u(this, n, this.hasAttribute("debug") && !["false", "0", "off", "no"].includes(this.getAttribute("debug") || "")), a(this, n));
+    }
+    log(...o) {
+      this._debug && console.log("[LOG]", this, ...o);
+    }
+    warn(...o) {
+      console.warn("[WARN]", this, ...o);
+    }
+    error(...o) {
+      console.error("[ERROR]", this, ...o);
+    }
+  }
+  return n = new WeakMap(), t;
+}
+export {
+  w as Debouncer,
+  M as LoggingMixin,
+  L as Stopwatch,
+  b as create_element,
+  p as getErrorLocation,
+  E as sleep,
+  T as waitFor,
+  x as waitForAnimationEnd,
+  y as waitForDomContentLoaded,
+  v as waitForLoad
+};

package/lib/Debouncer.d.ts

@@ -0,0 +1,14 @@
+export declare class Debouncer {
+    private delay;
+    private max_delay;
+    private timeout;
+    private startTimeWithMs;
+    /**
+     *
+     * @param delay     Debounce delay in milliseconds
+     * @param max_delay Maximum delay in milliseconds, if false then no maximum delay is applied
+     */
+    constructor(delay: number, max_delay?: number | false);
+    wait(): Promise<unknown>;
+    debounce(callback: () => void): void;
+}

package/lib/Stopwatch.d.ts

@@ -0,0 +1,14 @@
+export declare class Stopwatch {
+    private label;
+    private last;
+    private startTime;
+    private running;
+    private enabled;
+    constructor(label: string, enabled?: boolean);
+    lap(msg?: string): void;
+    elapsed(): number;
+    reset(): void;
+    stop(): number;
+    start(): void;
+    isRunning(): boolean;
+}

package/lib/create-element.d.ts

@@ -0,0 +1,3 @@
+type Attrs = Record<string, string | true | null | undefined>;
+export declare function create_element(tag: string, attrs?: Attrs, children?: (Node | string)[] | string | Node): HTMLElement;
+export {};

package/lib/get-error-location.d.ts

@@ -0,0 +1,13 @@
+export interface ErrorLocation {
+    file?: string;
+    line?: number;
+    column?: number;
+}
+export declare function getErrorLocation(err: Error & {
+    lineNumber?: number;
+    columnNumber?: number;
+    fileName?: string;
+    sourceURL?: string;
+    line?: number;
+    column?: number;
+}): ErrorLocation;

package/lib/wait-for.d.ts

@@ -0,0 +1,5 @@
+export declare function waitFor<T>(target: EventTarget, eventName: string, options?: AddEventListenerOptions): Promise<T>;
+export declare function waitForDomContentLoaded(): Promise<void>;
+export declare function waitForLoad(): Promise<void>;
+export declare function sleep(ms: number): Promise<void>;
+export declare function waitForAnimationEnd(element: HTMLElement): Promise<AnimationEvent>;

package/mixins/LoggingMixin.d.ts

@@ -0,0 +1,34 @@
+type Constructor<T = object> = abstract new (...args: any[]) => T;
+/**
+ * LoggingMixin
+ *
+ * A lightweight logging mixin that can be applied to any Custom Element base class
+ * (e.g., HTMLElement, LitElement/ReactiveElement, etc.). It provides log, warn,
+ * and error methods that only output when debugging is enabled.
+ *
+ * How it decides whether to log:
+ * - On the first call to any of the logging methods (log/warn/error), the mixin
+ *   checks the 'debug' attribute on the element instance and caches the result
+ *   (ressourcenschonende Attributabfrage mit Caching).
+ * - If the 'debug' attribute is present, it is considered truthy unless explicitly
+ *
+ * Example:
+ *   class MyElement extends LoggingMixin(HTMLElement) {}
+ *   // or with Lit:
+ *   class MyLitEl extends LoggingMixin(ReactiveElement) {}
+ *
+ *   <my-element debug></my-element>       // enables debug logging
+ */
+export declare function LoggingMixin<TBase extends Constructor<object>>(Base: TBase): (abstract new (...args: any[]) => {
+    "__#1700@#debugCached": boolean | null;
+    /**
+     * Clears the cached debug flag so the attribute will be checked again
+     * on the next log/warn/error call.
+     */
+    invalidateDebugCache(): void;
+    readonly _debug: boolean | null;
+    log(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}) & TBase;
+export {};

package/package.json

@@ -0,0 +1,8 @@
+{
+    "name": "@trunkjs/browser-utils",
+    "version": "1.0.12",
+    "main": "./index.js",
+    "dependencies": {},
+    "type": "module",
+    "types": "./index.d.ts"
+}