@tempots/dom 32.0.0 → 33.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/dom",
-  "version": "32.0.0",
+  "version": "33.1.0",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",

package/renderable/attribute.d.ts

@@ -1,5 +1,30 @@
 import { Renderable, SplitNValue } from '../types/domain';
 import { Value } from '../std/value';
+/**
+ * Creates a renderable for an HTML attribute with the specified name and value.
+ *
+ * This is the functional equivalent of using `attr[name](value)` with a dynamic attribute name.
+ *
+ * The `class` attribute is special and can be used multiple times on the same element.
+ * Multiple class values will be merged together.
+ *
+ * @param name - The name of the attribute.
+ * @param value - The value of the attribute (can be a literal or Signal).
+ * @returns A renderable that sets the attribute.
+ * @example
+ * ```ts
+ * const button = html.button(
+ *   Attr('type', 'button'),
+ *   Attr('disabled', disabledSignal),
+ *   // Multiple class attributes
+ *   Attr('class', 'btn btn-primary'),
+ *   Attr('class', 'active'),  // Both classes will be applied
+ *   // ...
+ * )
+ * ```
+ * @public
+ */
+export declare const Attr: (name: string, value: unknown) => Renderable;
 /**
  * The `attr` object allows to create any HTML attribute. Either a literal value
  * or `Signal<?>` can be passed as a value. The type of the value is inferred
@@ -162,9 +187,24 @@ export declare const attr: {
     innerText: (value: SplitNValue<string>) => Renderable;
     innerHTML: (value: SplitNValue<string>) => Renderable;
     outerHTML: (value: SplitNValue<string>) => Renderable;
-} & {
-    set: (name: string, value: SplitNValue<string>) => Renderable;
 };
+/**
+ * Creates a renderable for a data attribute with the specified name and value.
+ *
+ * This is the functional equivalent of using `dataAttr[name](value)` with a dynamic attribute name.
+ *
+ * @param name - The name of the data attribute (without the 'data-' prefix).
+ * @param value - The value of the attribute (can be a literal or Signal).
+ * @returns A renderable that sets the data attribute.
+ * @example
+ * ```ts
+ * const button = html.button(
+ *   DataAttr('myinfo', 'something'), // maps to the `data-myinfo` attribute
+ * )
+ * ```
+ * @public
+ */
+export declare const DataAttr: (name: string, value: unknown) => Renderable;
 /**
  * The `data` object allows to create any `data-` attributes. Either a literal value
  * or `Signal<string>` can be passed as a value.
@@ -179,9 +219,25 @@ export declare const attr: {
  */
 export declare const dataAttr: {
     [x: string]: (value: Value<string>) => Renderable;
-} & {
-    set: (name: string, value: Value<string>) => Renderable;
 };
+/**
+ * Creates a renderable for an ARIA attribute with the specified name and value.
+ *
+ * This is the functional equivalent of using `aria[name](value)` with a dynamic attribute name.
+ *
+ * @param name - The name of the ARIA attribute (without the 'aria-' prefix).
+ * @param value - The value of the attribute (can be a literal or Signal).
+ * @returns A renderable that sets the ARIA attribute.
+ * @example
+ * ```ts
+ * const button = html.button(
+ *   Aria('label', 'Click me!'), // maps to the `aria-label` attribute
+ *   Aria('pressed', pressedSignal), // maps to the `aria-pressed` attribute
+ * )
+ * ```
+ * @public
+ */
+export declare const Aria: (name: string, value: unknown) => Renderable;
 /**
  * An object that provides a convenient way to create mountable attributes for ARIA properties.
  *
@@ -251,9 +307,26 @@ export declare const aria: {
     valuemin: (value: SplitNValue<number>) => Renderable;
     valuenow: (value: SplitNValue<number>) => Renderable;
     valuetext: (value: SplitNValue<string>) => Renderable;
-} & {
-    set: (name: string, value: Value<string>) => Renderable;
 };
+/**
+ * Creates a renderable for an SVG attribute with the specified name and value.
+ *
+ * This is the functional equivalent of using `svgAttr[name](value)` with a dynamic attribute name.
+ *
+ * @param name - The name of the SVG attribute.
+ * @param value - The value of the attribute (can be a literal or Signal).
+ * @returns A renderable that sets the SVG attribute.
+ * @example
+ * ```ts
+ * const circle = svg.circle(
+ *   SVGAttr('cx', 50),
+ *   SVGAttr('cy', 50),
+ *   SVGAttr('r', radiusSignal),
+ * )
+ * ```
+ * @public
+ */
+export declare const SVGAttr: (name: string, value: unknown) => Renderable;
 /**
  * An object that provides a convenient way to create mountable attributes for
  * SVG elements.
@@ -542,9 +615,25 @@ export declare const svgAttr: {
     yChannelSelector: (value: SplitNValue<"R" | "G" | "B" | "A">) => Renderable;
     z: (value: SplitNValue<string | number>) => Renderable;
     zoomAndPan: (value: SplitNValue<"disable" | "magnify">) => Renderable;
-} & {
-    set: (name: string, value: Value<string>) => Renderable;
 };
+/**
+ * Creates a renderable for a MathML attribute with the specified name and value.
+ *
+ * This is the functional equivalent of using `mathAttr[name](value)`.
+ *
+ * @param name - The name of the MathML attribute.
+ * @param value - The value of the attribute (can be a literal or Signal).
+ * @returns A renderable that sets the MathML attribute.
+ * @example
+ * ```ts
+ * const mi = math.mi(
+ *   MathAttr('mathvariant', 'bold'),
+ *   MathAttr('mathsize', sizeSignal),
+ * )
+ * ```
+ * @public
+ */
+export declare const MathAttr: (name: string, value: unknown) => Renderable;
 /**
  * An object that provides attribute functions for MathML tags.
  *

package/renderable/element.d.ts

@@ -183,6 +183,15 @@ export declare const input: {
     week: (...children: TNode[]) => Renderable;
     "datetime-local": (...children: TNode[]) => Renderable;
 };
+/**
+ * Creates a Renderable that represents an SVG element.
+ *
+ * @param tagName - The tag name of the SVG element.
+ * @param children - The child nodes of the SVG element.
+ * @returns A renderable function that creates and appends the SVG element to the DOM.
+ * @public
+ */
+export declare const SVGEl: (tagName: string, ...children: TNode[]) => Renderable;
 /**
  * A convenience object to create Renderables for SVG elements.
  * @public
@@ -252,6 +261,15 @@ export declare const svg: {
     use: (...children: TNode[]) => Renderable;
     view: (...children: TNode[]) => Renderable;
 };
+/**
+ * Creates a Renderable that represents a MathML element.
+ *
+ * @param tagName - The tag name of the MathML element.
+ * @param children - The child nodes of the MathML element.
+ * @returns A renderable function that creates and appends the MathML element to the DOM.
+ * @public
+ */
+export declare const MathEl: (tagName: string, ...children: TNode[]) => Renderable;
 /**
  * A convenience object to create Renderables for MATH elements.
  * @public

package/std/signal.d.ts

@@ -18,6 +18,12 @@ export type ListenerOptions = {
     skipInitial?: boolean;
     once?: boolean;
     abortSignal?: AbortSignal;
+    /**
+     * If true, the listener will not be automatically disposed when the current scope ends.
+     * Use this when you need explicit control over the listener lifecycle.
+     * @internal
+     */
+    noAutoDispose?: boolean;
 };
 /**
  * A reactive signal that holds a value and notifies listeners when the value changes.
@@ -153,8 +159,28 @@ export declare class Signal<T> {
      * The listener function will be immediately called with the current value of the signal.
      * Returns a function that can be called to unregister the listener.
      *
+     * When called within a DisposalScope (e.g., inside a renderable), the listener is
+     * automatically cleaned up when the scope is disposed. This prevents memory leaks
+     * when listening to outer-scope signals from inner scopes.
+     *
      * @param listener - The listener function to be called when the value of the signal changes.
      * @param options - Options for the listener.
+     *
+     * @example
+     * ```typescript
+     * // Automatic cleanup when scope disposes
+     * const MyComponent = () => {
+     *   const outerSignal = prop(0)
+     *
+     *   return html.div(
+     *     When(someCondition, () => {
+     *       // This listener is automatically cleaned up when the When() disposes
+     *       outerSignal.on(value => console.log(value))
+     *       return html.span('Inner content')
+     *     })
+     *   )
+     * }
+     * ```
      */
     readonly on: (listener: (value: T, previousValue: T | undefined) => void, options?: ListenerOptions) => () => void;
     /**
@@ -187,6 +213,7 @@ export declare class Signal<T> {
     readonly onDispose: (listener: () => void) => void;
     /**
      * Disposes the signal, releasing any resources associated with it.
+     * This clears all listeners, derivatives, and disposal callbacks.
      */
     readonly dispose: () => void;
     /**