@tempots/dom 17.0.0 → 19.0.0

package/package.json

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

package/renderable/async.d.ts

@@ -1,7 +1,37 @@
-import { TNode } from '../types/domain';
+import { Renderable, TNode } from '../types/domain';
 
-export declare const Async: <T>(promise: Promise<T>, options: {
+/**
+ * Options for the `Async` component.
+ * @typeParam T - The type of the value.
+ * @public
+ */
+export type AsyncOptions<T> = {
+    /**
+     * The node to render while the promise is pending.
+     */
     pending?: TNode;
+    /**
+     * The node to render when the promise is resolved.
+     *
+     * @param value - The value returned by the promise.
+     * @returns The node to render.
+     */
     then: (value: T) => TNode;
+    /**
+     * The node to render when the promise is rejected.
+     *
+     * @param error - The error returned by the promise.
+     * @returns The node to render.
+     */
     error?: (error: unknown) => TNode;
-} | ((value: T) => TNode)) => import('../types/domain').Renderable;
+};
+/**
+ * Creates a renderable asynchronous task that wraps a promise.
+ *
+ * @typeParam T - The type of the value returned by the promise.
+ * @param promise - The promise to wrap.
+ * @param options - The options for the asynchronous task.
+ * @returns The renderable asynchronous task.
+ * @public
+ */
+export declare const Async: <T>(promise: Promise<T>, options: AsyncOptions<T> | ((value: T) => TNode)) => Renderable;

package/renderable/attribute.d.ts

@@ -1,12 +1,11 @@
-import { Renderable } from '../types/domain';
-import { Value, NValue } from '../std/signal';
+import { NValue, Renderable, Value } from '../types/domain';
 
 /**
  * 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
  * from the attribute name.
  *
- * Example
+ * @example
  * ```ts
  * const button = html.button(
  *   attr.type('button'),
@@ -14,6 +13,7 @@ import { Value, NValue } from '../std/signal';
  *   // ...
  * )
  * ```
+ * @public
  */
 export declare const attr: {
     accept: (value: NValue<string>) => Renderable;
@@ -130,20 +130,35 @@ export declare const attr: {
     innerHTML: (value: NValue<string>) => Renderable;
     outerHTML: (value: NValue<string>) => Renderable;
 };
+/**
+ * The `data` object allows to create any `data-` attributes. Either a literal value
+ * or `Signal<string>` can be passed as a value.
+ *
+ * @example
+ * ```ts
+ * const button = html.button(
+ *   dataAttr.myinfo('something'), // maps to the `data-myinfo` attribute
+ * )
+ * ```
+ * @public
+ */
 export declare const dataAttr: {
     [x: string]: (value: Value<string>) => Renderable;
 };
 /**
  * An object that provides a convenient way to create mountable attributes for ARIA properties.
  *
- * Example
+ * The type of the value is inferred from the attribute name.
+ *
+ * @example
  * ```ts
  * const button = html.button(
- *   aria.label('Click me!'),
- *   aria.pressed(pressed), // where pressed is a `Signal<boolean>`
- *   // ...
+ *   aria.label('Click me!'), // maps to the `aria-label` attribute
+ *   // maps to the `aria-pressed` attribute where pressed is a `Signal<boolean>`
+ *   aria.pressed(pressed)
  * )
  * ```
+ * @public
  */
 export declare const aria: {
     activedescendant: (value: NValue<string>) => Renderable;
@@ -199,13 +214,15 @@ export declare const aria: {
  * An object that provides a convenient way to create mountable attributes for
  * SVG elements.
  *
- * Example
+ * @example
  * ```ts
  * const svg = html.svg(
  *  svgAttr.width(100),
  *  svgAttr.height(height), // where height is a `Signal<number>`
  * // ...
  * )
+ * ```
+ * @public
  */
 export declare const svgAttr: {
     accentHeight: (value: NValue<number>) => Renderable;
@@ -453,13 +470,15 @@ export declare const svgAttr: {
 /**
  * An object that provides attribute functions for MathML tags.
  *
- * Example
+ * @example
  * ```ts
  * const math = html.math(
  *  mathAttr.mathvariant('bold'),
  *  mathAttr.mathsize(size), // where size is a `Signal<number>`
  * // ...
  * )
+ * ```
+ * @public
  */
 export declare const mathAttr: {
     maction: (value: NValue<MathMLElement>) => Renderable;

package/renderable/bind.d.ts

@@ -1,16 +1,46 @@
 import { Prop } from '../std/signal';
+import { Renderable } from '../types/domain';
 import { on } from './handler';
 
-declare function bindDate(prop: Prop<Date>, handler?: keyof typeof on): import('..').Renderable;
-declare function bindDateTime(prop: Prop<Date>, handler?: keyof typeof on): import('..').Renderable;
-declare function bindNumber(prop: Prop<number>, handler?: keyof typeof on): import('..').Renderable;
-declare function bindText(prop: Prop<string>, handler?: keyof typeof on): import('..').Renderable;
-declare function bindChecked(prop: Prop<boolean>): import('..').Renderable;
-export declare const bind: {
-    date: typeof bindDate;
-    dateTime: typeof bindDateTime;
-    number: typeof bindNumber;
-    text: typeof bindText;
-    checked: typeof bindChecked;
-};
-export {};
+/**
+ * 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
+ * affected by day changes and ignore time changes.
+ * @param prop - The `Date` property to bind.
+ * @param handler - The event handler to use (default: 'input').
+ * @returns A Renderable.
+ * @public
+ */
+export declare const BindDate: (prop: Prop<Date>, handler?: keyof typeof on) => Renderable;
+/**
+ * Binds a `Date` property to an input element. The binding is two-way.
+ * @param prop - The `Date` property to bind.
+ * @param handler - The event handler to use (default: 'input').
+ * @returns A Renderable.
+ * @public
+ */
+export declare const BindDateTime: (prop: Prop<Date>, handler?: keyof typeof on) => Renderable;
+/**
+ * Binds a `number` property to an input element. The binding is two-way.
+ * @param prop - The `number` property to bind.
+ * @param handler - The event handler to use (default: 'input').
+ * @returns A Renderable.
+ * @public
+ */
+export declare const BindNumber: (prop: Prop<number>, handler?: keyof typeof on) => Renderable;
+/**
+ * Binds a `string` property to an input element. The binding is two-way.
+ * @param prop - The `string` property to bind.
+ * @param handler - The event handler to use (default: 'input').
+ * @returns A Renderable.
+ * @public
+ */
+export declare const BindText: (prop: Prop<string>, handler?: keyof typeof on) => 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.
+ * @param handler - The event handler to use (default: 'input').
+ * @returns A Renderable.
+ * @public
+ */
+export declare const BindChecked: (prop: Prop<boolean>) => Renderable;

package/renderable/conjunction.d.ts

@@ -1,8 +1,27 @@
 import { Signal } from '../std/signal';
-import { TNode } from '../types/domain';
-import { Position } from '../std/position';
+import { Renderable, TNode } from '../types/domain';
+import { ElementPosition } from '../std/position';
 
-export declare const Conjunction: (separator: TNode, options?: {
+/**
+ * Options for configuring a conjunction.
+ * @public
+ */
+export type ConjunctionOptions = {
+    /**
+     * The separator to use for the last element.
+     */
     lastSeparator?: TNode;
+    /**
+     * The separator to use for the first element.
+     */
     firstSeparator?: TNode;
-}) => (pos: Signal<Position>) => import('../types/domain').Renderable;
+};
+/**
+ * Creates a Renderable that returns the appropriate separator based on the element position.
+ *
+ * @param separator - The default separator to use.
+ * @param options - The options for configuring the conjunction.
+ * @returns A function that returns the appropriate separator based on the element position.
+ * @public
+ */
+export declare const Conjunction: (separator: TNode, options?: ConjunctionOptions) => (pos: Signal<ElementPosition>) => Renderable;

package/renderable/consumers.d.ts

@@ -1,12 +1,65 @@
 import { TNode, Renderable, ProviderMark } from '../types/domain';
 
+/**
+ * Converts a tuple type `T` into an array of `ProviderMark` types.
+ * If `T` is an empty tuple, returns an empty array.
+ * If `T` has only one element, returns an array with a single `ProviderMark`.
+ * If `T` has more than one element, recursively converts each element into a `ProviderMark` and returns an array.
+ * @public
+ */
 export type ToArrayOfMarks<T extends unknown[]> = T extends [] ? [] : T extends [infer K] ? [ProviderMark<K>] : T extends [infer K, ...infer R] ? [ProviderMark<K>, ...ToArrayOfMarks<R>] : never;
+/**
+ * Represents a type that transforms a tuple of values into an object where each value is associated with a provider mark.
+ * @typeParam T - The tuple of values.
+ * @returns An object where each value is associated with a provider mark.
+ * @public
+ */
 export type ToProviders<T extends unknown[]> = T extends [] ? object : T extends [infer K] ? {
     [_ in ProviderMark<K>]: K;
 } : T extends [infer K, ...infer R] ? {
     [_ in ProviderMark<K>]: K;
 } & ToProviders<R> : never;
+/**
+ * Represents a consumer function that takes a callback function and returns a renderable object.
+ * The callback function takes a value of type T and returns a TNode.
+ *
+ * @typeParam T - The type of the value passed to the callback function.
+ * @public
+ */
 export type Consumer<T> = (fn: (value: T) => TNode) => Renderable;
-export declare const Use: <C extends Record<string, Consumer<unknown>>>(consumers: C, fn: (data: { [K in keyof C]: C[K] extends Consumer<infer V> ? V : never; }) => Renderable) => Renderable;
+/**
+ * Represents a type that extracts the value types from a record of `Consumer` types.
+ * @typeParam C - The record of `Consumer` types.
+ * @public
+ */
+export type UseMany<C extends Record<string, Consumer<unknown>>> = {
+    [K in keyof C]: C[K] extends Consumer<infer V> ? V : never;
+};
+/**
+ * Creates a renderable function that consumes data from multiple consumers and renders the result.
+ *
+ * @param consumers - An object containing consumer functions.
+ * @param fn - A function that receives the data from the consumers and returns a renderable function.
+ * @returns A renderable function that can be called with a DOMContext and returns a cleanup function.
+ * @public
+ */
+export declare const Use: <C extends Record<string, Consumer<unknown>>>(consumers: C, fn: (data: UseMany<C>) => Renderable) => Renderable;
+/**
+ * Creates a renderable function that consumes a provider value and renders a `TNode`.
+ *
+ * @typeParam T - The type of the provider value.
+ * @param mark - The provider mark.
+ * @param fn - The function that takes the provider value and returns a `TNode`.
+ * @returns A renderable function that consumes the provider value and renders a `TNode`.
+ * @public
+ */
 export declare const UseProvider: <T>(mark: ProviderMark<T>, fn: (value: T) => TNode) => Renderable;
+/**
+ * Creates a renderable function that consumes providers and renders a TNode.
+ *
+ * @param marks - The marks to be converted to an array of marks.
+ * @param fn - The function that takes providers and returns a TNode.
+ * @returns A renderable function that consumes providers and renders a TNode.
+ * @public
+ */
 export declare const UseProviders: <T extends unknown[]>(marks: ToArrayOfMarks<T>, fn: (providers: ToProviders<T>) => TNode) => Renderable;

package/renderable/domnode.d.ts

@@ -1,3 +1,11 @@
-import { DOMContext } from '../dom/dom-context';
+import { Renderable } from '../types/domain';
 
-export declare const DOMNode: (node: Node) => (ctx: DOMContext) => (removeTree: boolean) => void;
+/**
+ * Creates a renderable DOM node.
+ *
+ * @param node - The DOM node to render.
+ * @param ctx - The DOM context to render the node in.
+ * @returns A function that can be called to remove the rendered node from the DOM.
+ * @public
+ */
+export declare const DOMNode: (node: Node) => Renderable;

package/renderable/element.d.ts

@@ -1,8 +1,35 @@
 import { TNode, Renderable } from '../types/domain';
 
-export declare function renderableOfTNode(child: TNode): Renderable;
-export declare function El(tagName: string, ...children: TNode[]): Renderable;
-export declare function ElNS(tagName: string, namespace: string, ...children: TNode[]): Renderable;
+/**
+ * Converts a TNode into a Renderable.
+ * @param child - The TNode to convert.
+ * @returns The corresponding Renderable.
+ * @public
+ */
+export declare const renderableOfTNode: (child: TNode) => Renderable;
+/**
+ * Creates a Renderable that represents an HTML element.
+ *
+ * @param tagName - The tag name of the HTML element.
+ * @param children - The child nodes of the HTML element.
+ * @returns A renderable function that creates and appends the HTML element to the DOM.
+ * @public
+ */
+export declare const El: (tagName: string, ...children: TNode[]) => Renderable;
+/**
+ * Creates a renderable function that represents an element in the DOM with a specified namespace.
+ *
+ * @param tagName - The name of the HTML tag for the element.
+ * @param namespace - The namespace of the element.
+ * @param children - The child nodes of the element.
+ * @returns A renderable function that creates and appends the element to the DOM.
+ * @public
+ */
+export declare const ElNS: (tagName: string, namespace: string, ...children: TNode[]) => Renderable;
+/**
+ * A convenience object to create Renderables for HTML elements.
+ * @public
+ */
 export declare const html: {
     a: (...children: TNode[]) => Renderable;
     abbr: (...children: TNode[]) => Renderable;
@@ -116,6 +143,18 @@ export declare const html: {
     video: (...children: TNode[]) => Renderable;
     wbr: (...children: TNode[]) => Renderable;
 };
+/**
+ * A convenience object to create Renderables for HTMLInput elements.
+ *
+ * It automatically creates an attribute with the specified type
+ *
+ * @example
+ * ```ts
+ * input.text() // equivalent to html.input(attr.type('text'))
+ * ```
+ *
+ * @public
+ */
 export declare const input: {
     number: (...children: TNode[]) => Renderable;
     text: (...children: TNode[]) => Renderable;
@@ -140,6 +179,10 @@ export declare const input: {
     url: (...children: TNode[]) => Renderable;
     "datetime-local": (...children: TNode[]) => Renderable;
 };
+/**
+ * A convenience object to create Renderables for SVG elements.
+ * @public
+ */
 export declare const svg: {
     a: (...children: TNode[]) => Renderable;
     animate: (...children: TNode[]) => Renderable;
@@ -204,6 +247,10 @@ export declare const svg: {
     tspan: (...children: TNode[]) => Renderable;
     use: (...children: TNode[]) => Renderable;
 };
+/**
+ * A convenience object to create Renderables for MATH elements.
+ * @public
+ */
 export declare const math: {
     maction: (...children: TNode[]) => Renderable;
     math: (...children: TNode[]) => Renderable;

package/renderable/empty.d.ts

@@ -1,3 +1,8 @@
 import { Renderable } from '../types/domain';
 
+/**
+ * Represents an empty renderable function.
+ * @returns A renderable function that does nothing.
+ * @public
+ */
 export declare const Empty: Renderable;

package/renderable/ensure.d.ts

@@ -1,4 +1,14 @@
 import { TNode, Renderable } from '../types/domain';
 import { Signal } from '../std/signal';
 
+/**
+ * Represents a function that ensures a signal has a value before rendering a TNode.
+ *
+ * @typeParam T - The type of the signal value.
+ * @param signal - The signal to ensure has a value.
+ * @param then - The function that returns a TNode when the signal has a value. It takes a signal of the non-nullable type of T.
+ * @param otherwise - The function that returns a TNode when the signal does not have a value.
+ * @returns A renderable function that ensures the signal has a value before rendering a TNode.
+ * @public
+ */
 export declare const Ensure: <T>(signal: Signal<T | null> | Signal<T | undefined> | Signal<T | null | undefined>, then: (value: Signal<NonNullable<T>>) => TNode, otherwise?: () => TNode) => Renderable;

package/renderable/foreach.d.ts

@@ -1,5 +1,15 @@
 import { TNode, Renderable } from '../types/domain';
 import { Signal } from '../std/signal';
-import { Position } from '../std/position';
+import { ElementPosition } from '../std/position';
 
-export declare const ForEach: <T>(signal: Signal<T[]>, item: (value: Signal<T>, position: Signal<Position>) => TNode, separator?: (pos: Signal<Position>) => TNode) => Renderable;
+/**
+ * Renders a list of items based on a signal of arrays.
+ *
+ * @typeParam T - The type of items in the array.
+ * @param signal - The signal of arrays to iterate over.
+ * @param item - The function that renders each item in the array.
+ * @param separator - The function that renders the separator between items.
+ * @returns - The renderable function that renders the list of items.
+ * @public
+ */
+export declare const ForEach: <T>(signal: Signal<T[]>, item: (value: Signal<T>, position: Signal<ElementPosition>) => TNode, separator?: (pos: Signal<ElementPosition>) => TNode) => Renderable;

package/renderable/fragment.d.ts

@@ -1,3 +1,14 @@
 import { TNode, Renderable } from '../types/domain';
 
+/**
+ * Creates a fragment renderable that represents a collection of child renderables.
+ *
+ * The Fragment itself does not render any DOM elements. Instead, it renders the child renderables in the given DOM context.
+ *
+ * It can be used any time a single Renderable/TNode is expected, but multiple renderables are needed.
+ *
+ * @param children - The child renderables to include in the fragment.
+ * @returns A renderable function that renders the child renderables in the given DOM context.
+ * @public
+ */
 export declare const Fragment: (...children: TNode[]) => Renderable;

package/renderable/handler.d.ts

@@ -1,6 +1,15 @@
 import { Renderable } from '../types/domain';
 
+/**
+ * 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) => void) => Renderable;
+/**
+ * Represents a collection of HTML event handlers that can be attached to an element.
+ * @public
+ */
 export declare const on: {
     abort: (handler: (event: Event) => void) => Renderable;
     animationcancel: (handler: (event: AnimationEvent) => void) => Renderable;
@@ -90,13 +99,61 @@ export declare const on: {
     volumechange: (handler: (event: Event) => void) => Renderable;
     waiting: (handler: (event: Event) => void) => Renderable;
 };
-export declare const emit: {
-    value: (fn: (text: string) => void) => (event: Event) => void;
-    valueAsNumber: (fn: (num: number) => void) => (event: Event) => void;
-    valueAsDate: (fn: (date: Date) => void) => (event: Event) => void;
-    valueAsDateTime: (fn: (date: Date) => void) => (event: Event) => void;
-    checked: (fn: (checked: boolean) => void) => (event: Event) => void;
-    preventDefault: (fn: () => void) => (event: Event) => void;
-    stopPropagation: (fn: () => void) => (event: Event) => void;
-    stopImmediatePropagation: (fn: () => void) => (event: Event) => void;
-};
+/**
+ * Creates an event handler that emits the value of an HTMLInputElement.
+ *
+ * @param fn - The callback function that will receive the emitted value.
+ * @returns An event handler function that can be attached to an event listener.
+ * @public
+ */
+export declare const EmitValue: (fn: (text: string) => void) => (event: Event) => void;
+/**
+ * Calls the provided function with the value of an HTMLInputElement as a number.
+ *
+ * @param fn - The function to be called with the value as a number.
+ * @returns A function that can be used as an event handler.
+ * @public
+ */
+export declare const EmitValueAsNumber: (fn: (num: number) => void) => (event: Event) => void;
+/**
+ * Converts the value of an HTML input element to a Date object and emits it using the provided callback function.
+ * @param fn - The callback function to be called with the converted Date object.
+ * @returns A function that can be used as an event handler for input events.
+ * @public
+ */
+export declare const EmitValueAsDate: (fn: (date: Date) => void) => (event: Event) => void;
+/**
+ * Emits the value of an HTMLInputElement as a Date object.
+ * @param fn - The callback function to be called with the emitted Date object.
+ * @returns The event handler function.
+ * @public
+ */
+export declare const EmitValueAsDateTime: (fn: (date: Date) => void) => (event: Event) => void;
+/**
+ * Calls the provided function with the checked value of the event target.
+ * @param fn - The function to be called with the checked value.
+ * @returns A function that takes an event and calls the provided function with the checked value of the event target.
+ * @public
+ */
+export declare const EmitChecked: (fn: (checked: boolean) => void) => (event: Event) => void;
+/**
+ * Wraps a function to prevent the default behavior of an event before invoking it.
+ * @param fn - The function to be wrapped.
+ * @returns A new function that prevents the default behavior of the event and then invokes the original function.
+ * @public
+ */
+export declare const EmitPreventDefault: (fn: () => void) => (event: Event) => void;
+/**
+ * Creates a new event handler that stops event propagation and invokes the provided function.
+ * @param fn - The function to be invoked when the event is triggered.
+ * @returns A new event handler function.
+ * @public
+ */
+export declare const EmitStopPropagation: (fn: () => void) => (event: Event) => void;
+/**
+ * Creates an event handler that stops immediate propagation of the event and invokes the provided function.
+ * @param fn - The function to be invoked.
+ * @returns The event handler function.
+ * @public
+ */
+export declare const EmitStopImmediatePropagation: (fn: () => void) => (event: Event) => void;

package/renderable/map-signal.d.ts

@@ -1,4 +1,19 @@
 import { Renderable } from '../types/domain';
 import { Signal } from '../std/signal';
 
+/**
+ * Maps the values emitted by a signal to a renderable function and returns a new renderable function.
+ *
+ * While it is tempting to use MapSignal for its simplicity, it is important to remember that the
+ * renderable function returned by MapSignal will be re-rendered every time the signal emits a new value.
+ *
+ * In other contexts link `Ensure` or `OneOf`, the renderable function is only re-rendered when the signal
+ * changes to a state that requires a different renderable function.
+ *
+ * @typeParam T - The type of values emitted by the signal.
+ * @param signal - The signal to map.
+ * @param fn - The function to map the signal values to renderable functions.
+ * @returns - A new renderable function that represents the mapped signal.
+ * @public
+ */
 export declare const MapSignal: <T>(signal: Signal<T>, fn: (value: T) => Renderable) => Renderable;

package/renderable/not-empty.d.ts

@@ -1,4 +1,16 @@
 import { Signal } from '../std/signal';
 import { Renderable } from '../types/domain';
 
-export declare function NotEmpty<T>(signal: Signal<T[]>, display: Renderable, whenEmpty?: Renderable): Renderable;
+/**
+ * Returns a renderable component that displays the given `display` component
+ * when the `signal` contains a non-empty array, and the `whenEmpty` component
+ * otherwise.
+ *
+ * @typeParam T - The type of elements in the array.
+ * @param signal - The signal containing the array.
+ * @param display - The component to display when the array is non-empty.
+ * @param whenEmpty- The component to display when the array is empty.
+ * @returns - The renderable component.
+ * @public
+ */
+export declare const NotEmpty: <T>(signal: Signal<T[]>, display: Renderable, whenEmpty?: Renderable) => Renderable;

package/renderable/onctx.d.ts

@@ -1,4 +1,11 @@
 import { DOMContext } from '../dom/dom-context';
-import { Clear } from '../types/domain';
+import { Clear, Renderable } from '../types/domain';
 
-export declare const OnCtx: (fn: (ctx: DOMContext) => Clear) => (ctx: DOMContext) => Clear;
+/**
+ * Returns a renderable function that executes the given function with the current DOMContext as argument.
+ *
+ * @param fn - The function to be executed with the DOMContext argument.
+ * @returns A Clear function that can be used to clean up any resources associated with the execution.
+ * @public
+ */
+export declare const OnCtx: (fn: (ctx: DOMContext) => Clear) => Renderable;