@trunkjs/browser-utils 1.0.50 → 1.0.53

package/lib/FormDataAccessor.d.ts

@@ -0,0 +1,28 @@
+export type FormDataAccessorData = Record<string, unknown>;
+export type FormDataValueElement = HTMLElement & {
+    value: unknown;
+    disabled?: boolean;
+    name?: string;
+};
+export interface FormDataAccessorEntry {
+    readonly name: string;
+    readonly element: FormDataValueElement;
+    value: unknown;
+}
+/** Dynamically reads and writes named value elements below a DOM root. */
+export declare class FormDataAccessor {
+    readonly root: ParentNode;
+    constructor(root: ParentNode);
+    get entries(): FormDataAccessorEntry[];
+    get data(): FormDataAccessorData;
+    set data(data: FormDataAccessorData);
+    get formData(): FormData;
+    private get groupedEntries();
+    private getName;
+    private isValueElement;
+    /** A named value element owns its value, so its descendants are not collected twice. */
+    private hasValueElementParent;
+    private isDisabled;
+    private readGroup;
+    private writeGroup;
+}

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@trunkjs/browser-utils",
-    "version": "1.0.50",
+    "version": "1.0.53",
     "main": "./index.js",
     "repository": {
         "directory": "packages/browser-utils",
         "type": "git",
-        "url": "https://github.com/trunkjs/trunkjs-monorepo"
+        "url": "git+https://github.com/trunkjs/trunkjs-monorepo.git"
     },
     "dependencies": {},
     "type": "module",

package/skills/browser-utils-usage/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: browser-utils-usage
+description: Use @trunkjs/browser-utils for browser-side DOM creation, form values, timing, storage, breakpoints, typed event listeners, logging, loader coordination, and Lit/custom-element mixins. Do not use it for server-only code.
+---
+
+# Browser Utils Usage
+
+Prefer the public exports from `@trunkjs/browser-utils` over local copies of equivalent browser helpers. Import from the package root; internal `src/` paths are not public API.
+
+```ts
+import { create_element, local_storage, waitForLoad } from '@trunkjs/browser-utils';
+```
+
+Choose the smallest API that matches the job:
+
+- DOM nodes: `create_element`
+- Named form values: `FormDataAccessor`
+- Burst control: `Debouncer` or `@debounce`
+- Browser lifecycle and events: `waitFor*`, `sleep`
+- JSON-like browser state: `local_storage`, `session_storage`
+- Breakpoint inspection: `breakpoints`, `getCurrentBreakpoint`, `getBreakpointMinWidth`
+- Custom elements: `EventBindingsMixin`, `LoggingMixin`, `BreakPointMixin`
+- Lit elements: `LoaderMixin`, `SlotVisibilityMixin`
+
+Read [references/helpers-and-storage.md](references/helpers-and-storage.md) for DOM, timing, storage, diagnostics, and breakpoint examples. Read [references/custom-elements-and-mixins.md](references/custom-elements-and-mixins.md) when implementing custom elements, Lit components, decorators, loader coordination, or slot handling.
+
+For detailed form-value examples, use the focused `form-data-accessor-usage` package skill.
+
+## Package-specific constraints
+
+- Use these APIs only where browser globals are available. Storage proxies tolerate SSR by remaining in memory, but DOM and lifecycle helpers require the browser.
+- Treat storage values as JSON data. Functions, class instances, symbols, and cyclic objects are not supported.
+- Let the event mixin own listener cleanup; do not add duplicate manual listeners for the same decorator.
+- Use loader-aware waits only for visual startup coordination, not as a replacement for application data loading.
+- Preserve native error behavior: for example, `getBreakpointMinWidth` throws for unknown names and `waitForLoad(image)` rejects when the image fails.

package/skills/browser-utils-usage/references/custom-elements-and-mixins.md

@@ -0,0 +1,175 @@
+# Custom Elements and Mixins
+
+Use these APIs for lifecycle-aware browser components. Preserve each superclass lifecycle call when overriding `connectedCallback`, `disconnectedCallback`, or `firstUpdated`.
+
+## Bind and clean up events
+
+`EventBindingsMixin` registers decorated methods on connection and removes every registered listener through an internal `AbortController` on disconnection.
+
+```ts
+import { EventBindingsMixin, Listen } from '@trunkjs/browser-utils';
+
+class SearchBox extends EventBindingsMixin(HTMLElement) {
+  @Listen('input', { target: 'host' })
+  onInput(event: InputEvent): void {
+    const input = event.target as HTMLInputElement;
+    this.dispatchEvent(new CustomEvent('search', { detail: input.value }));
+  }
+
+  @Listen('resize', { target: 'window', options: { passive: true } })
+  onResize(): void {
+    this.toggleAttribute('compact', window.innerWidth < 768);
+  }
+}
+
+customElements.define('search-box', SearchBox);
+```
+
+Available targets are `host`, `document`, `window`, `shadowRoot`, an `EventTarget`, or a callback receiving the host. `shadowRoot` falls back to the host when no shadow root exists.
+
+```ts
+class ShortcutPanel extends EventBindingsMixin(HTMLElement) {
+  @Listen(['keydown', 'keyup'], { target: 'document' })
+  onKey(event: KeyboardEvent): void {
+    this.toggleAttribute('modifier-active', event.ctrlKey || event.metaKey);
+  }
+
+  @Listen('click', { target: (host) => host.querySelector('button') ?? host })
+  onAction(): void {
+    this.dispatchEvent(new Event('action'));
+  }
+}
+```
+
+Add application-specific events to `DocumentEventMap` to retain decorator inference:
+
+```ts
+declare global {
+  interface DocumentEventMap {
+    'cart:updated': CustomEvent<{ itemCount: number }>;
+  }
+}
+
+class CartBadge extends EventBindingsMixin(HTMLElement) {
+  @Listen('cart:updated', { target: 'document' })
+  onCartUpdated(event: DocumentEventMap['cart:updated']): void {
+    this.textContent = String(event.detail.itemCount);
+  }
+}
+```
+
+Do not use `@Listen` without `EventBindingsMixin`; the decorated method deliberately throws when invoked on an incompatible class.
+
+## Add element-aware logging
+
+`LoggingMixin` prefixes output with the tag and element instance. `debug()` only prints when the element has a truthy `debug` attribute; `log()`, `warn()`, and `error()` remain visible. Values `false`, `0`, `off`, and `no` disable debugging.
+
+```ts
+import { LoggingMixin } from '@trunkjs/browser-utils';
+
+class DataPanel extends LoggingMixin(HTMLElement) {
+  connectedCallback(): void {
+    this.debug('connected', { source: this.dataset.source });
+  }
+
+  attributeChangedCallback(name: string): void {
+    if (name === 'debug') this.invalidateDebugCache();
+  }
+
+  loadFailed(error: unknown): void {
+    this.error('load failed', error);
+  }
+}
+```
+
+```html
+<data-panel debug data-source="orders"></data-panel>
+```
+
+Use `throwError(...)` only when the caller should receive an exception. `getLogger(instanceId)` is cached per element, so choose a custom instance ID on the first call if one is required.
+
+## Map a custom element to responsive modes
+
+`BreakPointMixin` reads `--breakpoint` from the host and sets `mode="mobile|tablet|desktop"` as the window crosses the configured thresholds.
+
+```ts
+import { BreakPointMixin } from '@trunkjs/browser-utils';
+
+class AdaptiveNav extends BreakPointMixin(HTMLElement) {}
+customElements.define('adaptive-nav', AdaptiveNav);
+```
+
+```css
+adaptive-nav {
+  /* mobile below md, tablet from md, desktop from lg */
+  --breakpoint: 'md,lg';
+}
+
+adaptive-nav[mode='mobile'] .labels {
+  display: none;
+}
+```
+
+A single value uses the same threshold for tablet and desktop. Use only breakpoint names exported by the package.
+
+## Coordinate Lit elements with the loader
+
+`LoaderMixin` reports a Lit element as waiting during `connectedCallback`, ready after `firstUpdated`, and no longer blocking after disconnection. Pair it with the loader-aware wait functions where code must align with the visual startup phases.
+
+```ts
+import { LoaderMixin, waitForPreVisual, waitForReady, waitForVisual } from '@trunkjs/browser-utils';
+import { LitElement, css, html } from 'lit';
+
+class HeroCard extends LoaderMixin(LitElement) {
+  static styles = css`:host { opacity: 0; } :host([visible]) { opacity: 1; }`;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+
+  override async firstUpdated(changed: Map<string, unknown>) {
+    super.firstUpdated(changed);
+    await waitForPreVisual();
+    this.toggleAttribute('visible', true);
+  }
+}
+
+await waitForReady();
+prepareFinalLayout();
+await waitForVisual();
+startNonEssentialAnimation();
+```
+
+When no TrunkJS loader sets `window.tj_loader_state`, these waits fall back to the normal window load event.
+
+## Style empty slots in Lit
+
+`SlotVisibilityMixin` adds `slot-empty` directly to an empty `<slot>` and updates it on `slotchange`. Whitespace and Lit comment markers do not count as content; fallback children do.
+
+```ts
+import { SlotVisibilityMixin } from '@trunkjs/browser-utils';
+import { LitElement, css, html } from 'lit';
+
+class OptionalAside extends SlotVisibilityMixin(LitElement) {
+  static styles = css`
+    slot.slot-empty {
+      display: none;
+    }
+  `;
+
+  render() {
+    return html`<aside><slot name="aside"></slot></aside>`;
+  }
+}
+```
+
+Compose mixins only as needed, keeping lifecycle-aware mixins in the inheritance chain:
+
+```ts
+class InteractivePanel extends LoggingMixin(EventBindingsMixin(SlotVisibilityMixin(LitElement))) {
+  @Listen('visibilitychange', { target: 'document' })
+  onVisibilityChange(): void {
+    this.debug('document visibility', document.visibilityState);
+  }
+}
+```

package/skills/browser-utils-usage/references/helpers-and-storage.md

@@ -0,0 +1,159 @@
+# Browser Helpers and Storage
+
+Use these examples for ordinary browser code that does not need a custom-element mixin.
+
+## Create DOM elements
+
+`create_element` accepts string attributes, boolean attributes, and text or `Node` children. `true` creates an empty boolean attribute; `null` and `undefined` omit it.
+
+```ts
+import { create_element } from '@trunkjs/browser-utils';
+
+const icon = create_element('span', { class: 'icon', 'aria-hidden': 'true' }, '✓');
+const button = create_element(
+  'button',
+  { type: 'button', class: 'button primary', disabled: true },
+  [icon, ' Save'],
+);
+
+document.querySelector('#actions')?.append(button);
+```
+
+Use standard DOM APIs when a typed specialized element or property assignment is needed; `create_element` returns `HTMLElement` and sets attributes rather than element properties.
+
+## Debounce repeated work
+
+Use one `Debouncer` instance per independent operation. `max_delay` guarantees progress while calls keep arriving.
+
+```ts
+import { Debouncer } from '@trunkjs/browser-utils';
+
+const input = document.querySelector<HTMLInputElement>('#search')!;
+const debouncer = new Debouncer(250, 1500);
+
+input.addEventListener('input', async () => {
+  await debouncer.wait();
+  updateResults(input.value);
+});
+```
+
+For class methods using standard TypeScript decorators, use `@debounce`. A delayed invocation cannot return the original synchronous result, so use it for `void` methods.
+
+```ts
+import { debounce } from '@trunkjs/browser-utils';
+
+class SearchController {
+  @debounce(250, 1500)
+  update(query: string): void {
+    renderResults(query);
+  }
+}
+```
+
+## Wait for events and browser lifecycle
+
+`waitFor` resolves with the first event and then removes its listener.
+
+```ts
+import { waitFor } from '@trunkjs/browser-utils';
+
+const dialog = document.querySelector<HTMLDialogElement>('dialog')!;
+dialog.showModal();
+
+const event = await waitFor<MouseEvent>(dialog, 'click', { capture: true });
+console.log(event.clientX, event.clientY);
+```
+
+Wait for the DOM, full page, an image, media data, or a generic element load:
+
+```ts
+import { waitForDomContentLoaded, waitForLoad } from '@trunkjs/browser-utils';
+
+await waitForDomContentLoaded();
+await waitForLoad();
+
+const image = document.querySelector<HTMLImageElement>('img.hero')!;
+try {
+  await waitForLoad(image);
+} catch {
+  image.replaceWith(document.createTextNode('Preview unavailable'));
+}
+```
+
+Wait for CSS animation completion or introduce an explicit delay:
+
+```ts
+import { sleep, waitForAnimationEnd } from '@trunkjs/browser-utils';
+
+panel.classList.add('is-closing');
+await waitForAnimationEnd(panel);
+panel.hidden = true;
+
+await sleep(200);
+```
+
+## Persist JSON-like state
+
+Storage helpers return a typed proxy. Reading initializes known keys from the supplied defaults; writing or deleting a property persists the whole object. Stored unknown keys are ignored when the proxy is created.
+
+```ts
+import { local_storage, session_storage } from '@trunkjs/browser-utils';
+
+const preferences = local_storage('dashboard.preferences', {
+  theme: 'system' as 'light' | 'dark' | 'system',
+  compact: false,
+});
+
+preferences.theme = 'dark';
+preferences.compact = true;
+console.log({ ...preferences });
+
+const draft = session_storage('contact.draft', { subject: '', message: '' });
+draft.subject = 'Support request';
+```
+
+Malformed stored JSON falls back to the initial value. Quota and storage-security errors are ignored, leaving the proxy usable in memory. Use a new versioned key or migrate explicitly when the data shape changes substantially.
+
+## Inspect breakpoints
+
+The package uses `xs`, `sm`, `md`, `lg`, `xl`, and `xxl` with Bootstrap-compatible minimum widths.
+
+```ts
+import {
+  breakpoints,
+  getBreakpointMinWidth,
+  getCurrentBreakpoint,
+  getViewportWidth,
+} from '@trunkjs/browser-utils';
+
+console.log(getCurrentBreakpoint());
+console.log(getCurrentBreakpoint(1024)); // "lg"
+console.log(getBreakpointMinWidth('xl')); // 1200
+console.table(breakpoints);
+console.log(getViewportWidth());
+```
+
+Do not pass arbitrary names to `getBreakpointMinWidth`; unknown names throw.
+
+## Diagnostics
+
+Use `Stopwatch` for lightweight browser timing and `getErrorLocation` when presenting the best available file/line information from cross-browser errors.
+
+```ts
+import { getErrorLocation, Stopwatch } from '@trunkjs/browser-utils';
+
+const timing = new Stopwatch('hydrate', import.meta.env.DEV);
+hydratePage();
+timing.lap('DOM hydrated');
+console.debug('Total milliseconds:', timing.stop());
+
+try {
+  runUserScript();
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('User script failed', getErrorLocation(error));
+  }
+}
+```
+
+`Logger` is also public for non-element code. For custom elements, prefer `LoggingMixin` so messages include element identity and debug state.

package/skills/form-data-accessor-usage/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: form-data-accessor-usage
+description: Use @trunkjs/browser-utils FormDataAccessor to read or write named native and custom form controls, inspect element/value pairs, or create FormData from a DOM container.
+---
+
+# FormDataAccessor usage
+
+Use `FormDataAccessor` for a small, framework-independent view of named value elements below a DOM root.
+
+```ts
+import { FormDataAccessor } from '@trunkjs/browser-utils';
+
+const accessor = new FormDataAccessor(container);
+
+accessor.data = { name: 'Erika', topics: ['docs'] };
+console.log(accessor.data);
+console.log(accessor.formData);
+```
+
+The root may be an `HTMLElement`, `Document`, or `DocumentFragment`. Controls are discovered dynamically on every
+access. A control needs a non-empty `name` and a readable/writable `value` property. Native inputs, textareas, selects,
+and compatible custom elements such as `nte-input` follow this contract.
+
+A named value element owns its complete value. Named descendants below it are not returned as additional entries. This
+allows object-valued controls such as a named nested `tj-form` to form a data tree without duplicate flat fields.
+
+## Data behavior
+
+- `name[]` becomes an array under the name without `[]` in `data`.
+- A radio group returns its selected value.
+- One checkbox without `[]` returns a Boolean.
+- Checkbox groups return selected option values.
+- Multi-selects and custom controls may expose arrays.
+- Assigning `data` is a partial update; names absent from the object are unchanged.
+- `formData` omits disabled, unchecked, and non-submit controls.
+
+## Element and value pairs
+
+Use `entries` when code needs both the current value and its original element. Each entry has a dynamic `value`
+getter/setter, so it can update the control without a wrapper API.
+
+```ts
+for (const entry of accessor.entries) {
+  console.log(entry.name, entry.value, entry.element);
+}
+
+accessor.entries.forEach(({ element }) => {
+  element.toggleAttribute('validated', true);
+});
+```
+
+Prefer direct iteration for operations such as disabling, validating, or marking controls invalid. Add specialized
+collection methods only when a concrete repeated requirement cannot be expressed clearly through `entries`.