@trunkjs/browser-utils 1.0.47 → 1.0.49

package/.ai-usage-info.md

@@ -0,0 +1,180 @@
+# @trunkjs/browser-utils
+
+## Purpose
+
+Small browser-side helpers for DOM work, timing, events, storage, and custom-element mixins.
+
+Use this package when you need:
+- small DOM helpers
+- debounce / wait helpers
+- localStorage / sessionStorage state
+- logging in custom elements
+- responsive or loader-related custom-element mixins
+
+Do **not** use it for server-only code.
+
+## Import
+
+```ts
+import { create_element, Debouncer, waitForLoad } from '@trunkjs/browser-utils';
+```
+
+## Common examples
+
+### Create DOM nodes
+
+```ts
+import { create_element } from '@trunkjs/browser-utils';
+
+const el = create_element('button', { class: 'primary', disabled: true }, 'Save');
+document.body.append(el);
+```
+
+### Debounce user input
+
+```ts
+import { Debouncer } from '@trunkjs/browser-utils';
+
+const debouncer = new Debouncer(300, 2000);
+
+input.addEventListener('input', async () => {
+  await debouncer.wait();
+  search(input.value);
+});
+```
+
+### Wait for browser events
+
+```ts
+import { waitFor, waitForLoad, sleep, waitForAnimationEnd } from '@trunkjs/browser-utils';
+
+await waitForLoad();
+await waitFor(button, 'click');
+await sleep(200);
+await waitForAnimationEnd(dialog);
+```
+
+### Persistent state via storage proxy
+
+```ts
+import { local_storage, session_storage } from '@trunkjs/browser-utils';
+
+const prefs = local_storage('prefs', { theme: 'light', debug: false });
+prefs.theme = 'dark';
+
+const draft = session_storage('draft', { text: '' });
+draft.text = 'hello';
+```
+
+### Logging inside custom elements
+
+```ts
+import { LoggingMixin } from '@trunkjs/browser-utils';
+
+class MyEl extends LoggingMixin(HTMLElement) {
+  connectedCallback() {
+    this.log('connected');
+    this.warn('always visible');
+  }
+}
+```
+
+```html
+<my-el debug></my-el>
+```
+
+### Auto-bind events in custom elements
+
+```ts
+import { EventBindingsMixin, Listen } from '@trunkjs/browser-utils';
+
+class MyEl extends EventBindingsMixin(HTMLElement) {
+  @Listen('click', { target: 'host' })
+  onClick() {
+    console.log('clicked');
+  }
+
+  @Listen('resize', { target: 'window' })
+  onResize() {
+    console.log('resized');
+  }
+}
+```
+
+### Responsive custom element mode
+
+```ts
+import { BreakPointMixin } from '@trunkjs/browser-utils';
+
+class MyEl extends BreakPointMixin(HTMLElement) {}
+```
+
+```css
+:host {
+  --breakpoint: 'md,lg';
+}
+```
+
+Result on the host element:
+
+```html
+<my-el mode="mobile"></my-el>
+<!-- or mode="tablet" / mode="desktop" -->
+```
+
+### Loader-aware Lit elements
+
+```ts
+import { LitElement } from 'lit';
+import { LoaderMixin, waitForReady, waitForVisual } from '@trunkjs/browser-utils';
+
+class MyEl extends LoaderMixin(LitElement) {}
+
+await waitForReady();
+await waitForVisual();
+```
+
+### Detect slot content in Lit elements
+
+```ts
+import { LitElement, html } from 'lit';
+import { SlotVisibilityMixin } from '@trunkjs/browser-utils';
+
+class MyEl extends SlotVisibilityMixin(LitElement) {
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+```
+
+Empty slots get the CSS class:
+
+```html
+<slot class="slot-empty"></slot>
+```
+
+## Other exports
+
+```ts
+import {
+  Stopwatch,
+  Logger,
+  getErrorLocation,
+  breakpoints,
+  getCurrentBreakpoint,
+  getBreakpointMinWidth,
+  waitForDomContentLoaded,
+  waitForReady,
+  waitForPreVisual,
+  waitForVisual,
+  debounce,
+} from '@trunkjs/browser-utils';
+```
+
+## Agent hints
+
+- Prefer this package over ad-hoc browser helper code.
+- Prefer examples above over introducing new abstractions.
+- Mixins are mainly for Custom Elements / Lit elements.
+- Storage helpers persist JSON-like objects via property access.
+- `waitForReady` / `waitForPreVisual` / `waitForVisual` integrate with `window.tj_loader_state` when present.

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.0.49 (2026-05-18)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
+## 1.0.48 (2026-05-15)
+
+This was a version bump only for browser-utils to align it with other projects, there were no code changes.
+
 ## 1.0.47 (2026-05-07)
 
 This was a version bump only for browser-utils to align it with other projects, there were no code changes.

package/index.js

@@ -4,7 +4,7 @@ var x = (e) => {
 };
 var R = (e, t, n) => t in e ? D(e, t, { enumerable: !0, configurable: !0, writable: !0, value: n }) : e[t] = n;
 var c = (e, t, n) => R(e, typeof t != "symbol" ? t + "" : t, n), k = (e, t, n) => t.has(e) || x("Cannot " + n);
-var u = (e, t, n) => (k(e, t, "read from private field"), n ? n.call(e) : t.get(e)), h = (e, t, n) => t.has(e) ? x("Cannot add the same private member more than once") : t instanceof WeakSet ? t.add(e) : t.set(e, n), w = (e, t, n, i) => (k(e, t, "write to private field"), i ? i.call(e, n) : t.set(e, n), n), y = (e, t, n) => (k(e, t, "access private method"), n);
+var d = (e, t, n) => (k(e, t, "read from private field"), n ? n.call(e) : t.get(e)), m = (e, t, n) => t.has(e) ? x("Cannot add the same private member more than once") : t instanceof WeakSet ? t.add(e) : t.set(e, n), w = (e, t, n, i) => (k(e, t, "write to private field"), i ? i.call(e, n) : t.set(e, n), n), y = (e, t, n) => (k(e, t, "access private method"), n);
 const v = [
   { name: "xs", minWidth: 0 },
   { name: "sm", minWidth: 576 },
@@ -59,6 +59,10 @@ class P {
       }, this.delay));
     });
   }
+  /**
+   * @deprecated Use wait() instead and handle the callback logic in the caller function for better control and flexibility.
+   * @param callback
+   */
   debounce(t) {
     const n = Date.now();
     this.startTimeWithMs === 0 && (this.startTimeWithMs = n);
@@ -76,11 +80,11 @@ function X(e, t = !1) {
   return function(i, r) {
     if (r.kind !== "method") return i;
     const a = r.name;
-    return function(...d) {
+    return function(...u) {
       let s = n.get(this);
       s || (s = /* @__PURE__ */ new Map(), n.set(this, s));
       let o = s.get(a);
-      o || (o = new P(e, t), s.set(a, o)), o.debounce(() => i.apply(this, d));
+      o || (o = new P(e, t), s.set(a, o)), o.debounce(() => i.apply(this, u));
     };
   };
 }
@@ -211,8 +215,8 @@ class C {
       },
       set: (n, i, r) => {
         if (typeof i != "string") return !1;
-        const d = { ...this.read() };
-        return d[i] = r, this.write(d), !0;
+        const u = { ...this.read() };
+        return u[i] = r, this.write(u), !0;
       },
       deleteProperty: (n, i) => {
         if (typeof i != "string") return !1;
@@ -257,8 +261,8 @@ function tt(e, t) {
 }
 function T(e, t, n) {
   return new Promise((i, r) => {
-    const a = (d) => {
-      e.removeEventListener(t, a, n), i(d);
+    const a = (u) => {
+      e.removeEventListener(t, a, n), i(u);
     };
     e.addEventListener(t, a, n);
   });
@@ -298,30 +302,30 @@ function ot(e) {
   class t extends e {
     constructor() {
       super(...arguments);
-      h(this, n, new P(200, 5e3));
+      m(this, n, new P(200, 5e3));
       c(this, "currentBreakPoint", null);
-      h(this, i, async () => {
+      m(this, i, async () => {
         var b;
-        await u(this, n).wait(), await z();
-        const d = this, s = window.innerWidth;
-        let o = getComputedStyle(d).getPropertyValue("--breakpoint");
+        await d(this, n).wait(), await z();
+        const u = this, s = window.innerWidth;
+        let o = getComputedStyle(u).getPropertyValue("--breakpoint");
         if (!o || o === "")
           return;
         o = o.trim().replace(/^['"]|['"]$/g, "");
-        const l = o.split(","), m = l[0].trim(), f = ((b = l[1]) == null ? void 0 : b.trim()) ?? m, g = U(s);
-        this.currentBreakPoint !== g && (E(f) <= E(g) ? d.setAttribute("mode", "desktop") : E(m) > E(g) ? d.setAttribute("mode", "mobile") : d.setAttribute("mode", "tablet"));
+        const l = o.split(","), h = l[0].trim(), f = ((b = l[1]) == null ? void 0 : b.trim()) ?? h, g = U(s);
+        this.currentBreakPoint !== g && (E(f) <= E(g) ? u.setAttribute("mode", "desktop") : E(h) > E(g) ? u.setAttribute("mode", "mobile") : u.setAttribute("mode", "tablet"));
       });
     }
     connectedCallback() {
       super.connectedCallback();
       try {
-        u(this, i).call(this), window.addEventListener("resize", u(this, i)), u(this, i).call(this);
-      } catch (d) {
-        throw console.error("Error in BreakPointMixin:", d, "in element", this), d;
+        d(this, i).call(this), window.addEventListener("resize", d(this, i)), d(this, i).call(this);
+      } catch (u) {
+        throw console.error("Error in BreakPointMixin:", u, "in element", this), u;
       }
     }
     disconnectedCallback() {
-      super.disconnectedCallback(), window.removeEventListener("resize", u(this, i));
+      super.disconnectedCallback(), window.removeEventListener("resize", d(this, i));
     }
   }
   return n = new WeakMap(), i = new WeakMap(), t;
@@ -349,13 +353,13 @@ function H(e, t) {
   var n;
   return !t || t === "host" ? e : t === "document" ? e.ownerDocument ?? document : t === "window" ? ((n = e.ownerDocument) == null ? void 0 : n.defaultView) ?? window : t === "shadowRoot" ? e.shadowRoot ?? e : typeof t == "function" ? t(e) : t;
 }
-function ut(e) {
+function dt(e) {
   var n, i, $;
   class t extends e {
     constructor(...s) {
       super(...s);
-      h(this, i);
-      h(this, n);
+      m(this, i);
+      m(this, n);
       this[W] = !0;
     }
     connectedCallback() {
@@ -364,29 +368,29 @@ function ut(e) {
     }
     disconnectedCallback() {
       var s, o;
-      (s = u(this, n)) == null || s.abort(), (o = super.disconnectedCallback) == null || o.call(this);
+      (s = d(this, n)) == null || s.abort(), (o = super.disconnectedCallback) == null || o.call(this);
     }
   }
   return n = new WeakMap(), i = new WeakSet(), $ = function() {
-    var o, l, m;
-    (o = u(this, n)) == null || o.abort(), w(this, n, new AbortController());
+    var o, l, h;
+    (o = d(this, n)) == null || o.abort(), w(this, n, new AbortController());
     const s = this[p] || [];
     for (const f of s) {
-      const g = H(this, (l = f.opts) == null ? void 0 : l.target), b = ((m = f.opts) == null ? void 0 : m.options) ?? {}, N = this[f.method].bind(this);
+      const g = H(this, (l = f.opts) == null ? void 0 : l.target), b = ((h = f.opts) == null ? void 0 : h.options) ?? {}, S = this[f.method].bind(this);
       for (const B of f.events)
-        g.addEventListener(B, N, { ...b, signal: u(this, n).signal });
+        g.addEventListener(B, S, { ...b, signal: d(this, n).signal });
     }
   }, t;
 }
 let G = 1;
-function dt(e) {
+function ut(e) {
   var n, i, r;
   class t extends e {
     constructor() {
       super(...arguments);
-      h(this, n, null);
-      h(this, i, G++);
-      h(this, r, null);
+      m(this, n, null);
+      m(this, i, G++);
+      m(this, r, null);
     }
     /**
      * Clears the cached debug flag so the attribute will be checked again
@@ -396,15 +400,15 @@ function dt(e) {
       w(this, n, null);
     }
     get _debug() {
-      return u(this, n) !== null ? u(this, n) : (this instanceof HTMLElement && w(this, n, this.hasAttribute("debug") && !["false", "0", "off", "no"].includes(this.getAttribute("debug") || "")), u(this, n) === !0 && console.info(
+      return d(this, n) !== null ? d(this, n) : (this instanceof HTMLElement && w(this, n, this.hasAttribute("debug") && !["false", "0", "off", "no"].includes(this.getAttribute("debug") || "")), d(this, n) === !0 && console.info(
         // @ts-expect-error - it says tagName is not defined -whatever
-        `[DEBUG][ID:${u(this, i)}] LoggingMixin: Debug mode is enabled for <${this.tagName}>`,
+        `[DEBUG][ID:${d(this, i)}] LoggingMixin: Debug mode is enabled for <${this.tagName}>`,
         this
-      ), u(this, n) ?? !1);
+      ), d(this, n) ?? !1);
     }
     getLogger(s = "main") {
       const o = "<" + (this.tagName || this.constructor.name || "UnknownElement") + ">";
-      return u(this, r) || w(this, r, new j(this._debug, o, `${u(this, i)}`, s)), u(this, r);
+      return d(this, r) || w(this, r, new j(this._debug, o, `${d(this, i)}`, s)), d(this, r);
     }
     debug(...s) {
       this.getLogger().debug(...s);
@@ -427,48 +431,54 @@ function dt(e) {
 function lt(e) {
   class t extends e {
     connectedCallback() {
-      this.dispatchEvent(new CustomEvent("init:child-waitreq", {
-        detail: {
-          element: this,
-          state: "connected"
-        },
-        bubbles: !0,
-        composed: !0
-      })), super.connectedCallback();
+      this.dispatchEvent(
+        new CustomEvent("init:child-waitreq", {
+          detail: {
+            element: this,
+            state: "connected"
+          },
+          bubbles: !0,
+          composed: !0
+        })
+      ), super.connectedCallback();
     }
     firstUpdated(i) {
       var r;
-      (r = super.firstUpdated) == null || r.call(this, i), this.dispatchEvent(new CustomEvent("init:child-ready", {
-        detail: {
-          element: this,
-          state: "ready"
-        },
-        bubbles: !0,
-        composed: !0
-      }));
+      (r = super.firstUpdated) == null || r.call(this, i), this.dispatchEvent(
+        new CustomEvent("init:child-ready", {
+          detail: {
+            element: this,
+            state: "ready"
+          },
+          bubbles: !0,
+          composed: !0
+        })
+      );
     }
     disconnectedCallback() {
-      super.disconnectedCallback(), this.dispatchEvent(new CustomEvent("init:child-ready", {
-        detail: {
-          element: this,
-          state: "disconnected"
-        },
-        bubbles: !0,
-        composed: !0
-      }));
+      super.disconnectedCallback(), this.dispatchEvent(
+        new CustomEvent("init:child-ready", {
+          detail: {
+            element: this,
+            state: "disconnected"
+          },
+          bubbles: !0,
+          composed: !0
+        })
+      );
     }
   }
   return t;
 }
 function ct(e) {
-  var n, I, r, S;
+  var n, I, r, N;
   class t extends e {
     constructor() {
       super(...arguments);
-      h(this, n);
-      h(this, r, (o) => {
+      m(this, n);
+      m(this, r, (o) => {
         const l = o.target;
-        (l.assignedNodes({ flatten: !0 }).filter((g) => y(this, n, S).call(this, g)).length > 0 || l.childNodes.length > 0) && l.classList.remove("slot-empty");
+        l.assignedNodes({ flatten: !0 }).filter((g) => y(this, n, N).call(this, g)).length > 0 || l.childNodes.length > 0 ? l.classList.remove("slot-empty") : l.classList.add("slot-empty");
       });
     }
     firstUpdated(o) {
@@ -479,21 +489,21 @@ function ct(e) {
   return n = new WeakSet(), I = function() {
     var l;
     const o = (l = this.shadowRoot) == null ? void 0 : l.querySelectorAll("slot");
-    o == null || o.forEach((m) => {
-      m.classList.add("slot-empty"), m.addEventListener("slotchange", (f) => u(this, r).call(this, f));
+    o == null || o.forEach((h) => {
+      h.childNodes.length === 0 && h.classList.add("slot-empty"), h.addEventListener("slotchange", (f) => d(this, r).call(this, f));
     });
-  }, r = new WeakMap(), S = function(o) {
+  }, r = new WeakMap(), N = function(o) {
     return o.nodeType === Node.TEXT_NODE ? (o.textContent || "").trim().length > 0 : o.nodeType === Node.ELEMENT_NODE;
   }, t;
 }
 export {
   ot as BreakPointMixin,
   P as Debouncer,
-  ut as EventBindingsMixin,
+  dt as EventBindingsMixin,
   at as Listen,
   lt as LoaderMixin,
   j as Logger,
-  dt as LoggingMixin,
+  ut as LoggingMixin,
   ct as SlotVisibilityMixin,
   Y as Stopwatch,
   _ as breakpointMap,

package/lib/Debouncer.d.ts

@@ -11,6 +11,10 @@ export declare class Debouncer {
      */
     constructor(delay: number, max_delay?: number | false);
     wait(): Promise<unknown>;
+    /**
+     * @deprecated Use wait() instead and handle the callback logic in the caller function for better control and flexibility.
+     * @param callback
+     */
     debounce(callback: () => void): void;
 }
 type MethodCtx = {

package/mixins/LoaderMixin.d.ts

@@ -1,6 +1,6 @@
-import { LitElement } from 'lit';
+import { ReactiveElement } from 'lit';
 type Constructor<T = object> = abstract new (...args: any[]) => T;
 export interface LoaderMixinInterface {
 }
-export declare function LoaderMixin<TBase extends Constructor<LitElement>>(Base: TBase): TBase & Constructor<LoaderMixinInterface>;
+export declare function LoaderMixin<TBase extends Constructor<ReactiveElement>>(Base: TBase): TBase & Constructor<LoaderMixinInterface>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@trunkjs/browser-utils",
-    "version": "1.0.47",
+    "version": "1.0.49",
     "main": "./index.js",
     "repository": {
         "directory": "packages/browser-utils",