@react5/dom-jsx 0.1.6 → 0.1.8

package/README.md

@@ -56,10 +56,14 @@ type instead, call the component directly or call `jsx(Modal, null)` /
 
 Intrinsic JSX tags become DOM elements. `class` sets `className`, `style` accepts a style object, DOM properties are assigned when available, boolean attributes use presence semantics, and `onClick`-style function props become event listeners. Text, nested nodes, arrays, fragments, and function components are supported; `null`, `undefined`, and boolean children are ignored.
 
+Compound event props require camel casing, such as `onMouseEnter`, `onMouseLeave`,
+`onFocusIn`, `onFocusOut`, `onKeyDown`, and `onAnimationEnd`.
+Handlers receive the DOM event with `currentTarget` typed as the element.
+
 The public entry points are:
 
 ```ts
-import { createRef, createContext, useContext, jsx, jsxs, Fragment } from '@react5/dom-jsx'
+import { createRef, createContext, useContext, onCleanup, onDispose, dispose, jsx, jsxs, Fragment } from '@react5/dom-jsx'
 import { jsx, jsxs, jsxDEV, Fragment } from '@react5/dom-jsx/jsx-dev-runtime'
 ```
 
@@ -116,6 +120,52 @@ progress. Call it synchronously in a component body and keep the result.
 Called later, for example from an event handler or a `setTimeout`, it
 returns the context's default value.
 
+### Cleanup
+
+Release subscriptions, timers, and other resources when content is discarded.
+Register cleanups with `onCleanup` in a component body, or with
+`onDispose(node, fn)` anywhere else:
+
+```tsx
+import { dispose, onCleanup, onDispose } from '@react5/dom-jsx'
+
+function Clock() {
+  const el = <time /> as HTMLTimeElement
+  const id = setInterval(() => { el.textContent = new Date().toLocaleTimeString() }, 1000)
+  onCleanup(() => clearInterval(id))
+  return el
+}
+
+const node = <Clock />
+onDispose(node, () => console.log('disposed'))
+
+// Later, where content is swapped:
+old.replaceWith(next)
+dispose(old)
+```
+
+The DOM gives no synchronous signal when a node is removed, so `dispose` must
+be called explicitly. It runs the cleanups of the node and of every node inside
+it, descendants first, each node's cleanups in reverse registration order.
+Disposal follows the DOM tree, so components passed as children are covered
+even though they render before their parent. Each cleanup runs at most once;
+if some throw, the rest still run and the error (or an `AggregateError`) is
+rethrown afterwards.
+
+A component's cleanups are attached to the node it returns. When it returns a
+fragment, they are attached to the fragment's top-level children and run once
+all of them are disposed, so dispose every one of them, or a common ancestor.
+An empty fragment gets an empty comment node to carry its cleanups.
+
+If a component throws while rendering, the cleanups it already registered run
+immediately. So do those of components it rendered and of JSX passed to it in
+props, unless those nodes are already in the document.
+
+`onCleanup` throws when called outside a component render, e.g. from an event
+handler or after an `await`; use `onDispose(node, fn)` there. Moving a node
+never disposes it. A node that is discarded without `dispose` keeps its
+cleanups until it is garbage-collected, and they never run.
+
 ## Development
 
 ```sh

package/dist/index.js

@@ -1 +1 @@
-import{Fragment as r,createContext as m,createRef as o,jsx as t,jsxs as e,useContext as i}from"./jsx-runtime.js";export{r as Fragment,m as createContext,o as createRef,t as jsx,e as jsxs,i as useContext};
+import{Fragment as r,createContext as m,createRef as o,dispose as t,jsx as e,jsxs as i,onCleanup as j,onDispose as p,useContext as s}from"./jsx-runtime.js";export{r as Fragment,m as createContext,o as createRef,t as dispose,e as jsx,i as jsxs,j as onCleanup,p as onDispose,s as useContext};

package/dist/jsx-runtime.d.ts

@@ -6,12 +6,16 @@ export type Component<P = Props, R extends Node = Node> = (props: P) => R;
 export type DOMEventHandler<T extends EventTarget, E extends Event> = (event: E & {
     currentTarget: T;
 }) => void;
+type CompoundEventName = 'AnimationCancel' | 'AnimationEnd' | 'AnimationIteration' | 'AnimationStart' | 'AuxClick' | 'BeforeInput' | 'BeforeMatch' | 'BeforeToggle' | 'CanPlay' | 'CanPlayThrough' | 'CompositionEnd' | 'CompositionStart' | 'CompositionUpdate' | 'ContextLost' | 'ContextMenu' | 'ContextRestored' | 'CueChange' | 'DblClick' | 'DragEnd' | 'DragEnter' | 'DragLeave' | 'DragOver' | 'DragStart' | 'DurationChange' | 'FocusIn' | 'FocusOut' | 'FormData' | 'FullscreenChange' | 'FullscreenError' | 'GotPointerCapture' | 'LostPointerCapture' | 'KeyDown' | 'KeyPress' | 'KeyUp' | 'LoadedData' | 'LoadedMetadata' | 'LoadStart' | 'MouseDown' | 'MouseEnter' | 'MouseLeave' | 'MouseMove' | 'MouseOut' | 'MouseOver' | 'MouseUp' | 'PointerCancel' | 'PointerDown' | 'PointerEnter' | 'PointerLeave' | 'PointerMove' | 'PointerOut' | 'PointerOver' | 'PointerRawUpdate' | 'PointerUp' | 'RateChange' | 'ScrollEnd' | 'SecurityPolicyViolation' | 'SelectionChange' | 'SelectStart' | 'SlotChange' | 'TimeUpdate' | 'TouchCancel' | 'TouchEnd' | 'TouchMove' | 'TouchStart' | 'TransitionCancel' | 'TransitionEnd' | 'TransitionRun' | 'TransitionStart' | 'VolumeChange' | 'WaitingForKey' | 'WebkitAnimationEnd' | 'WebkitAnimationIteration' | 'WebkitAnimationStart' | 'WebkitTransitionEnd';
+type CompoundEventNames = {
+    [K in CompoundEventName as Lowercase<K>]: K;
+};
+type EventPropName<K extends string> = K extends keyof CompoundEventNames ? `on${CompoundEventNames[K]}` : `on${Capitalize<K>}`;
 type MappedEventProps<T extends HTMLElement> = {
-    [K in keyof HTMLElementEventMap as `on${Capitalize<K & string>}`]?: DOMEventHandler<T, HTMLElementEventMap[K]>;
+    [K in keyof HTMLElementEventMap as EventPropName<K & string>]?: DOMEventHandler<T, HTMLElementEventMap[K]>;
 };
-export type EventProps<T extends HTMLElement> = Omit<MappedEventProps<T>, 'onInput' | 'onDblclick'> & {
+export type EventProps<T extends HTMLElement> = Omit<MappedEventProps<T>, 'onInput'> & {
     onInput?: DOMEventHandler<T, InputEvent>;
-    onDblClick?: DOMEventHandler<T, MouseEvent>;
 };
 export type Ref<T> = {
     current: T | null;
@@ -34,6 +38,9 @@ export type Context<T> = {
 };
 export declare function createContext<T>(defaultValue: T): Context<T>;
 export declare function useContext<T>(context: Context<T>): T;
+export declare function onDispose(node: Node, fn: () => void): void;
+export declare function onCleanup(fn: () => void): void;
+export declare function dispose(node: Node): void;
 export declare namespace JSX {
     type Element = Node & {
         api?: Record<string, any>;

package/dist/jsx-runtime.js

@@ -1 +1 @@
-function e(){return{current:null}}var t=/* @__PURE__ */new WeakMap;function n(e){const n=[],r={Provider({value:e,children:t}){if("function"!=typeof t)throw new TypeError("Context Provider expects a single function child: {() => ...}");n.push(e);try{const e=t();if(e instanceof Node)return e;const n=document.createDocumentFragment();return s(n,e),n}finally{n.pop()}}};return t.set(r,{defaultValue:e,stack:n}),r}function r(e){const n=t.get(e);if(!n)throw new TypeError("useContext expects a context created by createContext");const{defaultValue:r,stack:o}=n;return o.length>0?o[o.length-1]:r}function o(e,t,n){return function(e,t){const n=t??{};if("function"==typeof e)return e(n);const r=document.createElement(e);for(const[c,i]of Object.entries(n))if("children"!==c&&"ref"!==c)if(c.startsWith("on")&&"function"==typeof i)r.addEventListener(c.slice(2).toLowerCase(),i);else if("class"!==c){if("style"===c&&i&&"object"==typeof i)Object.assign(r.style,i);else if(null!=i)if(c.includes("-"))r.setAttribute(c,String(i));else{if(c in r){if(!1===i)continue;try{r[c]=i;continue}catch{}}r.setAttribute(c,!0===i?"":String(i))}}else r.className=String(i??"");s(r,n.children);const o=n.ref;"function"==typeof o?o(r):o&&(o.current=r);return r}(e,t)}var c=o;function i(e){const t=document.createDocumentFragment();return s(t,e.children),t}function s(e,t){if(Array.isArray(t))for(const n of t)s(e,n);else t instanceof Node?e.appendChild(t):null!=t&&!1!==t&&!0!==t&&e.appendChild(document.createTextNode(String(t)))}export{i as Fragment,n as createContext,e as createRef,o as jsx,c as jsxs,r as useContext};
+function e(){return{current:null}}var t=/* @__PURE__ */new WeakMap;function n(e){const n=[],o={Provider({value:e,children:t}){if("function"!=typeof t)throw new TypeError("Context Provider expects a single function child: {() => ...}");n.push(e);try{const e=t();if(e instanceof Node)return e;const n=document.createDocumentFragment();return m(n,e),n}finally{n.pop()}}};return t.set(o,{defaultValue:e,stack:n}),o}function o(e){const n=t.get(e);if(!n)throw new TypeError("useContext expects a context created by createContext");const{defaultValue:o,stack:r}=n;return r.length>0?r[r.length-1]:o}var r=/* @__PURE__ */new WeakMap,c=[];function s(e,t){const n=r.get(e);n?n.push(t):r.set(e,[t])}function i(e,t){s(e,()=>t())}function f(e){const t=c[c.length-1];if(!t)throw new Error("onCleanup must be called while a component is rendering; use onDispose(node, fn) instead");t.cleanups.push(e)}function u(e){const t=[];if(l(e,t),1===t.length)throw t[0];if(t.length>1)throw new AggregateError(t,"Multiple cleanups failed during dispose")}function l(e,t){for(const r of Array.from(e.childNodes))l(r,t);const n=r.get(e);if(n){r.delete(e);for(let e=n.length-1;e>=0;e--)try{n[e](t)}catch(o){t.push(o)}}}function a(e,t){for(let o=e.length-1;o>=0;o--)try{e[o]()}catch(n){t.push(n)}}function d(e,t){if(e instanceof Node)t.push(e);else if(Array.isArray(e))for(const n of e)d(n,t)}function p(e,t){const n={cleanups:[],rendered:[]};let o;c.push(n);try{o=e(t)}catch(f){throw c.pop(),function(e,t){const n=[],o=[...e.rendered];for(const r of Object.values(t))d(r,o);for(const r of o)r.isConnected||l(r,n);a(e.cleanups,n)}(n,t),f}c.pop();let r=[o];if(o instanceof DocumentFragment&&(!o.firstChild&&n.cleanups.length>0&&o.appendChild(document.createComment("")),r=Array.from(o.childNodes)),n.cleanups.length>0)if(1===r.length)for(const c of n.cleanups)i(r[0],c);else{let e=r.length;for(const t of r)s(t,t=>{0===--e&&a(n.cleanups,t)})}return c[c.length-1]?.rendered.push(...r),o}function h(e,t,n){return function(e,t){const n=t??{};if("function"==typeof e)return p(e,n);const o=document.createElement(e);for(const[c,s]of Object.entries(n))if("children"!==c&&"ref"!==c)if(c.startsWith("on")&&"function"==typeof s)o.addEventListener(c.slice(2).toLowerCase(),s);else if("class"!==c){if("style"===c&&s&&"object"==typeof s)Object.assign(o.style,s);else if(null!=s)if(c.includes("-"))o.setAttribute(c,String(s));else{if(c in o){if(!1===s)continue;try{o[c]=s;continue}catch{}}o.setAttribute(c,!0===s?"":String(s))}}else o.className=String(s??"");m(o,n.children);const r=n.ref;"function"==typeof r?r(o):r&&(r.current=o);return o}(e,t)}var g=h;function y(e){const t=document.createDocumentFragment();return m(t,e.children),t}function m(e,t){if(Array.isArray(t))for(const n of t)m(e,n);else t instanceof Node?e.appendChild(t):null!=t&&!1!==t&&!0!==t&&e.appendChild(document.createTextNode(String(t)))}export{y as Fragment,n as createContext,e as createRef,u as dispose,h as jsx,g as jsxs,f as onCleanup,i as onDispose,o as useContext};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react5/dom-jsx",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "JSX runtime for vanilla TS/JS projects.",
   "keywords": [
     "JSX"