@trunkjs/browser-utils 1.0.47 → 1.0.48

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,7 @@
+## 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/package.json

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