@tempots/dom 37.3.0 → 37.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/dom",
-  "version": "37.3.0",
+  "version": "37.4.0",
   "type": "module",
   "sideEffects": false,
   "main": "./index.cjs",

package/renderable/bind.d.ts

@@ -1,6 +1,6 @@
 import { Prop } from '@tempots/core';
 import { Renderable } from '../types/domain';
-import { on } from './on';
+import { HTMLEvents } from '../types/html-events';
 /**
  * Binds a `Date` property to an input element. The binding is two-way.
  * Changes to the input element will update the property but will only be
@@ -10,7 +10,7 @@ import { on } from './on';
  * @returns A Renderable.
  * @public
  */
-export declare const BindDate: (prop: Prop<Date>, handler?: keyof typeof on) => Renderable;
+export declare const BindDate: (prop: Prop<Date>, handler?: keyof HTMLEvents) => Renderable;
 /**
  * Binds a `Date` property to an input element. The binding is two-way.
  * @param prop - The `Date` property to bind.
@@ -18,7 +18,7 @@ export declare const BindDate: (prop: Prop<Date>, handler?: keyof typeof on) =>
  * @returns A Renderable.
  * @public
  */
-export declare const BindDateTime: (prop: Prop<Date>, handler?: keyof typeof on) => Renderable;
+export declare const BindDateTime: (prop: Prop<Date>, handler?: keyof HTMLEvents) => Renderable;
 /**
  * Binds a `number` property to an input element. The binding is two-way.
  * @param prop - The `number` property to bind.
@@ -26,7 +26,7 @@ export declare const BindDateTime: (prop: Prop<Date>, handler?: keyof typeof on)
  * @returns A Renderable.
  * @public
  */
-export declare const BindNumber: (prop: Prop<number>, handler?: keyof typeof on) => Renderable;
+export declare const BindNumber: (prop: Prop<number>, handler?: keyof HTMLEvents) => Renderable;
 /**
  * Binds a `string` property to an input element. The binding is two-way.
  * @param prop - The `string` property to bind.
@@ -34,7 +34,7 @@ export declare const BindNumber: (prop: Prop<number>, handler?: keyof typeof on)
  * @returns A Renderable.
  * @public
  */
-export declare const BindText: (prop: Prop<string>, handler?: keyof typeof on) => Renderable;
+export declare const BindText: (prop: Prop<string>, handler?: keyof HTMLEvents) => Renderable;
 /**
  * Binds a `boolean` property to the checked value of an input element. The binding is two-way.
  * @param prop - The `boolean` property to bind.

package/renderable/on.d.ts

@@ -1,17 +1,24 @@
 import { Renderable } from '../types/domain';
-import { DOMContext } from '../dom/dom-context';
+import { HTMLEvents } from '../types/html-events';
+import { DOMContext, HandlerOptions } from '../dom/dom-context';
 /**
  * Attaches an event handler to the 'click' event that triggers when a checkbox is checked or unchecked.
  * @param fn - The callback function to be executed when the checkbox is clicked.
  * @alpha
  */
 export declare const OnChecked: (fn: (event: boolean, ctx: DOMContext) => void) => Renderable;
+type EventHandlerMap = {
+    [EN in keyof HTMLEvents]: (handler: (event: HTMLEvents[EN], ctx: DOMContext) => void, options?: HandlerOptions) => Renderable;
+};
 /**
  * Provides type-safe event handlers for all HTML events.
  *
  * The `on` object is a proxy that provides access to all standard HTML events with proper
  * TypeScript typing. Each event handler receives the native event object and the DOM context.
  *
+ * Use `on.document` to attach listeners to `document` and `on.window` to attach listeners
+ * to `window`. These listeners are automatically removed when the component is disposed.
+ *
  * @example
  * ```typescript
  * // Basic click handler
@@ -60,131 +67,43 @@ export declare const OnChecked: (fn: (event: boolean, ctx: DOMContext) => void)
  * )
  * ```
  *
+ * @example
+ * ```typescript
+ * // Global keyboard shortcut scoped to a component's lifetime
+ * html.div(
+ *   on.document.keydown((event) => {
+ *     if (event.key === 'Escape') {
+ *       console.log('Escape pressed anywhere!')
+ *     }
+ *   }),
+ *   'Press Escape anywhere'
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Window resize listener scoped to a component's lifetime
+ * html.div(
+ *   on.window.resize(() => {
+ *     console.log('Window resized!')
+ *   }),
+ *   'Resize the window'
+ * )
+ * ```
+ *
  * @public
  */
-export declare const on: {
-    abort: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    afterprint: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    animationcancel: (handler: (event: AnimationEvent, ctx: DOMContext) => void) => Renderable;
-    animationend: (handler: (event: AnimationEvent, ctx: DOMContext) => void) => Renderable;
-    animationiteration: (handler: (event: AnimationEvent, ctx: DOMContext) => void) => Renderable;
-    animationstart: (handler: (event: AnimationEvent, ctx: DOMContext) => void) => Renderable;
-    auxclick: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    beforeinput: (handler: (event: InputEvent, ctx: DOMContext) => void) => Renderable;
-    beforeprint: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    beforeunload: (handler: (event: BeforeUnloadEvent, ctx: DOMContext) => void) => Renderable;
-    blur: (handler: (event: FocusEvent, ctx: DOMContext) => void) => Renderable;
-    cancel: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    canplay: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    canplaythrough: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    change: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    click: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    close: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    compositionend: (handler: (event: CompositionEvent, ctx: DOMContext) => void) => Renderable;
-    compositionstart: (handler: (event: CompositionEvent, ctx: DOMContext) => void) => Renderable;
-    compositionupdate: (handler: (event: CompositionEvent, ctx: DOMContext) => void) => Renderable;
-    contextmenu: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    copy: (handler: (event: ClipboardEvent, ctx: DOMContext) => void) => Renderable;
-    cuechange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    cut: (handler: (event: ClipboardEvent, ctx: DOMContext) => void) => Renderable;
-    dblclick: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    drag: (handler: (event: DragEvent, ctx: DOMContext) => void) => Renderable;
-    dragend: (handler: (event: DragEvent, ctx: DOMContext) => void) => Renderable;
-    dragenter: (handler: (event: DragEvent, ctx: DOMContext) => void) => Renderable;
-    dragexit: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    dragleave: (handler: (event: DragEvent, ctx: DOMContext) => void) => Renderable;
-    dragover: (handler: (event: DragEvent, ctx: DOMContext) => void) => Renderable;
-    dragstart: (handler: (event: DragEvent, ctx: DOMContext) => void) => Renderable;
-    drop: (handler: (event: DragEvent, ctx: DOMContext) => void) => Renderable;
-    durationchange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    emptied: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    ended: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    error: (handler: (event: ErrorEvent, ctx: DOMContext) => void) => Renderable;
-    focus: (handler: (event: FocusEvent, ctx: DOMContext) => void) => Renderable;
-    focusin: (handler: (event: FocusEvent, ctx: DOMContext) => void) => Renderable;
-    focusout: (handler: (event: FocusEvent, ctx: DOMContext) => void) => Renderable;
-    formdata: (handler: (event: FormDataEvent, ctx: DOMContext) => void) => Renderable;
-    fullscreenchange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    fullscreenerror: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    gotpointercapture: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    hashchange: (handler: (event: HashChangeEvent, ctx: DOMContext) => void) => Renderable;
-    input: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    invalid: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    keydown: (handler: (event: KeyboardEvent, ctx: DOMContext) => void) => Renderable;
-    keypress: (handler: (event: KeyboardEvent, ctx: DOMContext) => void) => Renderable;
-    keyup: (handler: (event: KeyboardEvent, ctx: DOMContext) => void) => Renderable;
-    languagechange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    load: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    loadeddata: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    loadedmetadata: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    loadend: (handler: (event: ProgressEvent<EventTarget>, ctx: DOMContext) => void) => Renderable;
-    loadstart: (handler: (event: ProgressEvent<EventTarget>, ctx: DOMContext) => void) => Renderable;
-    lostpointercapture: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    message: (handler: (event: MessageEvent<any>, ctx: DOMContext) => void) => Renderable;
-    messageerror: (handler: (event: MessageEvent<any>, ctx: DOMContext) => void) => Renderable;
-    mousedown: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    mouseenter: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    mouseleave: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    mousemove: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    mouseout: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    mouseover: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    mouseup: (handler: (event: MouseEvent, ctx: DOMContext) => void) => Renderable;
-    offline: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    online: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    orientationchange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    pagehide: (handler: (event: PageTransitionEvent, ctx: DOMContext) => void) => Renderable;
-    pageshow: (handler: (event: PageTransitionEvent, ctx: DOMContext) => void) => Renderable;
-    paste: (handler: (event: ClipboardEvent, ctx: DOMContext) => void) => Renderable;
-    pause: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    play: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    playing: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    pointercancel: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    pointerdown: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    pointerenter: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    pointerleave: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    pointerlockchange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    pointerlockerror: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    pointermove: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    pointerout: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    pointerover: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    pointerrawupdate: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    pointerup: (handler: (event: PointerEvent, ctx: DOMContext) => void) => Renderable;
-    popstate: (handler: (event: PopStateEvent, ctx: DOMContext) => void) => Renderable;
-    progress: (handler: (event: ProgressEvent<EventTarget>, ctx: DOMContext) => void) => Renderable;
-    ratechange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    readystatechange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    rejectionhandled: (handler: (event: PromiseRejectionEvent, ctx: DOMContext) => void) => Renderable;
-    reset: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    resize: (handler: (event: UIEvent, ctx: DOMContext) => void) => Renderable;
-    scroll: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    scrollend: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    securitypolicyviolation: (handler: (event: SecurityPolicyViolationEvent, ctx: DOMContext) => void) => Renderable;
-    seeked: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    seeking: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    select: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    selectionchange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    selectstart: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    slotchange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    stalled: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    storage: (handler: (event: StorageEvent, ctx: DOMContext) => void) => Renderable;
-    submit: (handler: (event: SubmitEvent, ctx: DOMContext) => void) => Renderable;
-    suspend: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    timeupdate: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    toggle: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    touchcancel: (handler: (event: TouchEvent, ctx: DOMContext) => void) => Renderable;
-    touchend: (handler: (event: TouchEvent, ctx: DOMContext) => void) => Renderable;
-    touchmove: (handler: (event: TouchEvent, ctx: DOMContext) => void) => Renderable;
-    touchstart: (handler: (event: TouchEvent, ctx: DOMContext) => void) => Renderable;
-    transitioncancel: (handler: (event: TransitionEvent, ctx: DOMContext) => void) => Renderable;
-    transitionend: (handler: (event: TransitionEvent, ctx: DOMContext) => void) => Renderable;
-    transitionrun: (handler: (event: TransitionEvent, ctx: DOMContext) => void) => Renderable;
-    transitionstart: (handler: (event: TransitionEvent, ctx: DOMContext) => void) => Renderable;
-    unhandledrejection: (handler: (event: PromiseRejectionEvent, ctx: DOMContext) => void) => Renderable;
-    unload: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    visibilitychange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    volumechange: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    waiting: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
-    wheel: (handler: (event: WheelEvent, ctx: DOMContext) => void) => Renderable;
+export declare const on: EventHandlerMap & {
+    /**
+     * Attaches event listeners to `document`. The listener is automatically
+     * removed when the component is disposed.
+     */
+    document: EventHandlerMap;
+    /**
+     * Attaches event listeners to `window`. The listener is automatically
+     * removed when the component is disposed.
+     */
+    window: EventHandlerMap;
 };
 /**
  * Options for event handlers.
@@ -377,3 +296,4 @@ export declare const emitValueAsNullableDateTime: (fn: (date: Date | null, event
  * @public
  */
 export declare const emitChecked: (fn: (checked: boolean, event: Event) => void, options?: EmitOptions) => (event: Event) => void;
+export {};