@jasonshimmy/custom-elements-runtime 2.5.2 → 2.5.6

package/dist/runtime/vdom-patch.d.ts

@@ -0,0 +1,67 @@
+/**
+ * vdom-patch.ts
+ *
+ * Core virtual DOM patching and rendering engine. Provides:
+ * - `cleanupRefs`    — recursively remove event listeners and clear ref entries
+ * - `assignKeysDeep` — recursively assign stable keys to VNode trees
+ * - `patchProps`     — diff and apply prop/attr/directive changes to a DOM element
+ * - `createElement`  — create a new DOM element from a VNode descriptor
+ * - `patchChildren`  — reconcile a list of child VNodes against real DOM children
+ * - `patch`          — top-level diff/patch driver for a single VNode
+ * - `vdomRenderer`   — entry-point renderer for a shadow root or container
+ */
+import type { VNode, VDomRefs } from './types';
+import { type VNodePropBag } from './vdom-helpers';
+export declare function cleanupRefs(node: Node, refs?: VDomRefs): void;
+/**
+ * Assign unique keys to VNodes for efficient rendering
+ * @param nodeOrNodes
+ * @param baseKey
+ * @returns
+ */
+export declare function assignKeysDeep(nodeOrNodes: VNode | VNode[], baseKey: string): VNode | VNode[];
+/**
+ * Patch props on an element.
+ * Only update changed props, remove old, add new.
+ * @param el
+ * @param oldProps
+ * @param newProps
+ * @param context
+ */
+export declare function patchProps(el: HTMLElement, oldProps: VNodePropBag, newProps: VNodePropBag, context?: Record<string, unknown>): void;
+/**
+ * Create a DOM element from a VNode.
+ * @param vnode
+ * @param context
+ * @param refs
+ * @returns
+ */
+export declare function createElement(vnode: VNode | string, context?: Record<string, unknown>, refs?: VDomRefs, parentNamespace?: string | null): Node;
+/**
+ * Patch children using keys for node matching.
+ * @param parent
+ * @param oldChildren
+ * @param newChildren
+ * @param context
+ * @param refs
+ * @returns
+ */
+export declare function patchChildren(parent: HTMLElement, oldChildren: VNode[] | string | undefined, newChildren: VNode[] | string | undefined, context?: Record<string, unknown>, refs?: VDomRefs): void;
+/**
+ * Patch a node using keys for node matching.
+ * @param dom
+ * @param oldVNode
+ * @param newVNode
+ * @param context
+ * @param refs
+ * @returns
+ */
+export declare function patch(dom: Node, oldVNode: VNode | string | null, newVNode: VNode | string | null, context?: Record<string, unknown>, refs?: VDomRefs): Node;
+/**
+ * Virtual DOM renderer.
+ * @param root The root element to render into.
+ * @param vnodeOrArray The virtual node or array of virtual nodes to render.
+ * @param context The context to use for rendering.
+ * @param refs The refs to use for rendering.
+ */
+export declare function vdomRenderer(root: ShadowRoot, vnodeOrArray: VNode | VNode[], context?: Record<string, unknown>, refs?: VDomRefs): void;

package/dist/runtime/vdom.d.ts

@@ -1,142 +1,18 @@
 /**
  * vdom.ts
- * Lightweight, strongly typed, functional virtual DOM renderer for custom elements.
- * Features: keyed diffing, incremental patching, focus/caret preservation, event delegation, SSR-friendly, no dependencies.
- */
-import type { VNode, VDomRefs } from './types';
-type PropsMap = Record<string, unknown>;
-type DirectiveSpec = {
-    value: unknown;
-    modifiers: string[];
-    arg?: string;
-};
-type VNodePropBag = {
-    props?: PropsMap;
-    attrs?: PropsMap;
-    directives?: Record<string, DirectiveSpec>;
-    isCustomElement?: boolean;
-    [k: string]: unknown;
-};
-/**
- * Recursively clean up refs and event listeners for all descendants of a node
- * @param node The node to clean up.
- * @param refs The refs to clean up.
- * @returns
- */
-export declare function cleanupRefs(node: Node, refs?: VDomRefs): void;
-/**
- * Process :model directive for two-way data binding
- * @param value
- * @param modifiers
- * @param props
- * @param attrs
- * @param listeners
- * @param context
- * @param el
- * @returns
- */
-export declare function processModelDirective(value: string | unknown, modifiers: string[], props: Record<string, unknown>, attrs: Record<string, unknown>, listeners: Record<string, EventListener>, context?: Record<string, unknown>, el?: Element, arg?: string): void;
-/**
- * Process :bind directive for attribute/property binding
- * @param value
- * @param props
- * @param attrs
- * @param context
- * @returns
- */
-export declare function processBindDirective(value: unknown, props: PropsMap, attrs: PropsMap, context?: Record<string, unknown>, el?: Element): void;
-/**
- * Process :show directive for conditional display
- * @param value
- * @param attrs
- * @param context
- * @returns
- */
-export declare function processShowDirective(value: unknown, attrs: Record<string, unknown>, context?: Record<string, unknown>): void;
-export declare function processClassDirective(value: unknown, attrs: Record<string, unknown>, context?: Record<string, unknown>, originalVnodeAttrs?: Record<string, unknown>): void;
-/**
- * Process :style directive for dynamic inline styles
- * @param value
- * @param attrs
- * @param context
- * @returns
- */
-export declare function processStyleDirective(value: unknown, attrs: Record<string, unknown>, context?: Record<string, unknown>): void;
-/**
- * Process :ref directive for element references
- * @param value
- * @param props
- * @param context
- * @returns
- */
-export declare function processRefDirective(value: unknown, props: Record<string, unknown>, context?: Record<string, unknown>): void;
-/**
- * Process directives and return merged props, attrs, and event listeners
- * @param directives
- * @param context
- * @param el
- * @param vnodeAttrs
- * @returns
- */
-export declare function processDirectives(directives: Record<string, {
-    value: unknown;
-    modifiers: string[];
-    arg?: string;
-}>, context?: Record<string, unknown>, el?: Element, vnodeAttrs?: PropsMap): {
-    props: Record<string, unknown>;
-    attrs: Record<string, unknown>;
-    listeners: Record<string, EventListener>;
-};
-/**
- * Assign unique keys to VNodes for efficient rendering
- * @param nodeOrNodes
- * @param baseKey
- * @returns
- */
-export declare function assignKeysDeep(nodeOrNodes: VNode | VNode[], baseKey: string): VNode | VNode[];
-/**
- * Patch props on an element.
- * Only update changed props, remove old, add new.
- * @param el
- * @param oldProps
- * @param newProps
- * @param context
- */
-export declare function patchProps(el: HTMLElement, oldProps: VNodePropBag, newProps: VNodePropBag, context?: Record<string, unknown>): void;
-/**
- * Create a DOM element from a VNode.
- * @param vnode
- * @param context
- * @param refs
- * @returns
- */
-export declare function createElement(vnode: VNode | string, context?: Record<string, unknown>, refs?: VDomRefs, parentNamespace?: string | null): Node;
-/**
- * Patch children using keys for node matching.
- * @param parent
- * @param oldChildren
- * @param newChildren
- * @param context
- * @param refs
- * @returns
- */
-export declare function patchChildren(parent: HTMLElement, oldChildren: VNode[] | string | undefined, newChildren: VNode[] | string | undefined, context?: Record<string, unknown>, refs?: VDomRefs): void;
-/**
- * Patch a node using keys for node matching.
- * @param dom
- * @param oldVNode
- * @param newVNode
- * @param context
- * @param refs
- * @returns
- */
-export declare function patch(dom: Node, oldVNode: VNode | string | null, newVNode: VNode | string | null, context?: Record<string, unknown>, refs?: VDomRefs): Node;
-/**
- * Virtual DOM renderer.
- * @param root The root element to render into.
- * @param vnodeOrArray The virtual node or array of virtual nodes to render.
- * @param context The context to use for rendering.
- * @param refs The refs to use for rendering.
- */
-export declare function vdomRenderer(root: ShadowRoot, vnodeOrArray: VNode | VNode[], context?: Record<string, unknown>, refs?: VDomRefs): void;
-export {};
+ *
+ * Barrel re-export module for the virtual DOM implementation.
+ * The actual code lives in the focused sub-modules:
+ *
+ * | Module               | Responsibilities                                       |
+ * |----------------------|--------------------------------------------------------|
+ * | vdom-helpers.ts      | Private utilities and shared internal types            |
+ * | vdom-directives.ts   | processModelDirective and all process*Directive funcs  |
+ * | vdom-patch.ts        | assignKeysDeep, patchProps, createElement, patch, etc. |
+ * | vdom-ssr.ts          | renderToString (server-side rendering)                 |
+ *
+ * Import directly from these focused modules for tree-shaking.
+ * This file is kept for backwards compatibility.
+ */
+export { processModelDirective, processBindDirective, processShowDirective, processClassDirective, processStyleDirective, processRefDirective, processDirectives, } from "./vdom-directives";
+export { cleanupRefs, assignKeysDeep, patchProps, createElement, patchChildren, patch, vdomRenderer, } from "./vdom-patch";

package/dist/ssr.d.ts

@@ -16,7 +16,7 @@
  * Examples
  *
  *   // Default (injects xmlns for <svg> if missing)
- *   import { renderToString } from '@custom-elements/ssr';
+ *   import { renderToString } from '@jasonshimmy/custom-elements-runtime/ssr';
  *   const html = renderToString(vnodeTree);
  *
  *   // Opt-out
@@ -25,3 +25,4 @@
 export { renderToString } from './runtime/vdom-ssr';
 export type { VNode } from './runtime/types';
 export type { RenderOptions } from './runtime/vdom-ssr';
+export { registerEntityMap, loadEntityMap, clearRegisteredEntityMap, } from './runtime/helpers';

package/dist/teleport.d.ts

@@ -0,0 +1,68 @@
+/**
+ * teleport.ts
+ *
+ * Renders virtual DOM content into an arbitrary DOM target located outside
+ * the current component's Shadow Root. Useful for modals, tooltips, popovers,
+ * and any UI that must visually escape the component boundary.
+ *
+ * @example
+ * ```ts
+ * import { component, html, ref, useOnDisconnected, useTeleport } from '@jasonshimmy/custom-elements-runtime';
+ *
+ * component('modal-trigger', () => {
+ *   const isOpen = ref(false);
+ *
+ *   // Render modal content into <body> outside the shadow root
+ *   const { portal, destroy } = useTeleport('#modal-root');
+ *   useOnDisconnected(destroy);
+ *
+ *   // Call portal() to update the teleported content on each render
+ *   if (isOpen.value) {
+ *     portal(html`<div class="modal">
+ *       <h2>Hello</h2>
+ *       <button @click="${() => (isOpen.value = false)}">Close</button>
+ *     </div>`);
+ *   } else {
+ *     portal(null);
+ *   }
+ *
+ *   return html`
+ *     <button @click="${() => (isOpen.value = true)}">Open modal</button>
+ *   `;
+ * });
+ * ```
+ */
+import type { VNode } from './runtime/types';
+/** Handle returned by {@link useTeleport} for managing a portal. */
+export interface TeleportHandle {
+    /**
+     * Render (or clear) content at the teleport target.
+     * Pass `null` or `undefined` to remove previously rendered content.
+     */
+    portal(content: VNode | VNode[] | null | undefined): void;
+    /**
+     * Destroy the teleport container and clean up all rendered content.
+     * Call this in `useOnDisconnected` to prevent memory leaks.
+     */
+    destroy(): void;
+}
+/**
+ * Create a teleport portal that renders content outside the current Shadow Root.
+ *
+ * @param target - A CSS selector string or an `Element` reference to render into.
+ * @returns A {@link TeleportHandle} with `portal()` (update content) and `destroy()` (cleanup).
+ *
+ * @example
+ * ```ts
+ * import { component, html, useOnDisconnected, useTeleport } from '@jasonshimmy/custom-elements-runtime';
+ *
+ * component('my-tooltip', () => {
+ *   const { portal, destroy } = useTeleport('body');
+ *   useOnDisconnected(destroy);
+ *
+ *   portal(html`<div class="tooltip">Tooltip content</div>`);
+ *   return html`<span>Hover me</span>`;
+ * });
+ * ```
+ */
+export declare function useTeleport(target: string | Element): TeleportHandle;