@tempots/dom 18.0.0 → 19.1.0

package/renderable/oneof.d.ts

@@ -1,22 +1,144 @@
 import { Signal } from '../std/signal';
 import { Renderable, TNode } from '../types/domain';
 
-export declare const oneof: {
-    bool: (match: Signal<boolean>, cases: {
-        true: () => TNode;
-        false: () => TNode;
-    }) => Renderable;
-    field: <T extends { [_ in K]: string; }, K extends string>(match: Signal<T>, field: K, cases: { [KK in T[K]]: (value: Signal<T extends { [_ in K]: KK; } ? T : never>) => TNode; }) => Renderable;
-    kind: <T extends {
-        kind: string;
-    }>(match: Signal<T>, cases: { [KK in T["kind"]]: (value: Signal<T extends {
+/**
+ * Represents a set of options for a one-of type.
+ * @typeParam T - The type of the options.
+ * @public
+ */
+export type OneOfOptions<T extends Record<string, unknown>> = {
+    [KK in keyof T]: (value: Signal<T[KK]>) => TNode;
+};
+/**
+ * Creates a renderable function that renders different components based on the value of a signal.
+ *
+ * The signal value should be an object with a single key that matches one of the keys in the `cases` object.
+ *
+ * @typeParam T - The type of the signal value.
+ * @param match - The signal to match against.
+ * @param cases - An object containing the different cases to render based on the signal value.
+ * @returns A renderable function that renders the appropriate component based on the signal value.
+ * @public
+ */
+export declare const OneOf: <T extends Record<string, unknown>>(match: Signal<T>, cases: OneOfOptions<T>) => Renderable;
+/**
+ * Represents the options for a one-of field.
+ *
+ * @typeParam T - The type containing the one-of field.
+ * @typeParam K - The key of the one-of field in the type.
+ * @public
+ */
+export type OneOfFieldOptions<T extends {
+    [_ in K]: string;
+}, K extends string> = {
+    [KK in T[K]]: (value: Signal<T extends {
+        [_ in K]: KK;
+    } ? T : never>) => TNode;
+};
+/**
+ * Creates a renderable that renders different components based on the value of the specified field.
+ *
+ * @typeParam T - The type containing the one-of field.
+ * @typeParam K - The type of the one-of field key.
+ * @param match - The signal that emits the object containing the one-of field.
+ * @param field - The key of the one-of field.
+ * @param cases - The options for the different cases of rendering based on the one-of field value.
+ * @returns - The renderable field representing the one-of field.
+ * @public
+ */
+export declare const OneOfField: <T extends { [_ in K]: string; }, K extends string>(match: Signal<T>, field: K, cases: OneOfFieldOptions<T, K>) => Renderable;
+/**
+ * The options for a one-of kind field.
+ *
+ * @typeParam T - The type that contains the `kind` property.
+ * @public
+ */
+export type OneOfKindOptions<T extends {
+    kind: string;
+}> = {
+    [KK in T['kind']]: (value: Signal<T extends {
         kind: KK;
-    } ? T : never>) => TNode; }) => Renderable;
-    tuple: <T extends string, V>(match: Signal<[T, V]>, cases: { [KK in T]: (value: Signal<V>) => TNode; }) => Renderable;
-    type: <T extends {
-        type: string;
-    }>(match: Signal<T>, cases: { [KK in T["type"]]: (value: Signal<T extends {
+    } ? T : never>) => TNode;
+};
+/**
+ * Creates a renderable field that matches the value of the `kind` property in the provided `match` signal.
+ *
+ * It uses the `cases` object to determine the appropriate field to render based on the value of `kind`.
+ *
+ * @typeParam T - The type of the object with a `kind` property.
+ * @param match - The signal containing the object to match against.
+ * @param cases - The object containing the cases to match against.
+ * @returns - The renderable field that matches the value of `kind`.
+ * @public
+ */
+export declare const OneOfKind: <T extends {
+    kind: string;
+}>(match: Signal<T>, cases: OneOfKindOptions<T>) => Renderable;
+/**
+ * Represents a mapping of keys to functions that accept a value of type `Signal<V>`
+ * and return a `TNode`.
+ *
+ * @typeParam T - The union type of keys.
+ * @typeParam V - The type of the value accepted by the functions.
+ * @public
+ */
+export type OneOfTupleOptions<T extends string, V> = {
+    [KK in T]: (value: Signal<V>) => TNode;
+};
+/**
+ * Creates a tuple-based one-of component that matches a signal value with a set of cases.
+ *
+ * The signal value should be a tuple with the first element being the key to match against.
+ *
+ * @param match - The signal containing the value to match.
+ * @param cases - The options for the one-of component.
+ * @returns The result of matching the signal value with the cases.
+ * @public
+ */
+export declare const OneOfTuple: <T extends string, V>(match: Signal<[T, V]>, cases: OneOfTupleOptions<T, V>) => Renderable;
+/**
+ * Represents a mapping of types to rendering functions.
+ * @typeParam T - The type that contains a `type` property.
+ * @public
+ */
+export type OneOfTypeOptions<T extends {
+    type: string;
+}> = {
+    [KK in T['type']]: (value: Signal<T extends {
         type: KK;
-    } ? T : never>) => TNode; }) => Renderable;
-    value: <T extends symbol | number | string>(match: Signal<T>, cases: { [KK in T]: () => TNode; }) => Renderable;
+    } ? T : never>) => TNode;
+};
+/**
+ * Creates a field that renders one of the provided cases based on the value of the `type` property.
+ *
+ * It uses the `cases` object to determine the appropriate field to render based on the value of `type`.
+ *
+ * @typeParam T - The type of the object with a `type` property.
+ * @param match - The signal that contains the object with the `type` property.
+ * @param cases - The options for rendering each case based on the `type` property.
+ * @returns - The rendered field.
+ * @public
+ */
+export declare const OneOfType: <T extends {
+    type: string;
+}>(match: Signal<T>, cases: OneOfTypeOptions<T>) => Renderable;
+/**
+ * Represents a set of options for a one-of value.
+ * @typeParam T - The type of the one-of value.
+ * @public
+ */
+export type OneOfValueOptions<T extends symbol | number | string> = {
+    [KK in T]: () => TNode;
 };
+/**
+ * Creates a renderable value that represents one of the provided cases based on the given match signal.
+ *
+ * The match signal should emit a value that matches one of the keys in the `cases` object.
+ *
+ * @typeParam T - The type of the match signal value.
+ * @param match - The match signal.
+ * @param cases - The options for the one-of value.
+ * @returns - The renderable value representing one of the cases.
+ * @public
+ */
+export declare const OneOfValue: <T extends symbol | number | string>(match: Signal<T>, cases: OneOfValueOptions<T>) => Renderable;

package/renderable/onmount.d.ts

@@ -1,3 +1,11 @@
 import { Clear, Renderable } from '../types/domain';
 
+/**
+ * Executes a callback function when the parent element is mounted in the DOM.
+ *
+ * @typeParam T - The type of the element.
+ * @param fn - The callback function to be executed.
+ * @returns - The renderable function.
+ * @public
+ */
 export declare const OnMount: <T extends Element>(fn: (element: T) => Clear | undefined | void) => Renderable;

package/renderable/onunmount.d.ts

@@ -1,4 +1,10 @@
 import { Renderable } from '../types/domain';
 import { DOMContext } from '../dom/dom-context';
 
+/**
+ * Creates a renderable function that will be called when the component is unmounted.
+ * @param fn - The function to be called when the component is unmounted.
+ * @returns A renderable function that takes a DOMContext and returns a function that takes a boolean indicating whether to remove the tree.
+ * @public
+ */
 export declare const OnUnmount: (fn: (removeTree: boolean, ctx: DOMContext) => void) => Renderable;

package/renderable/portal.d.ts

@@ -1,4 +1,13 @@
-import { DOMContext } from '../dom/dom-context';
-import { TNode } from '../types/domain';
+import { Renderable, TNode } from '../types/domain';
 
-export declare const Portal: (selector: string, node: TNode) => (ctx: DOMContext) => () => void;
+/**
+ * Renders the given `node` into a DOM element selected by the provided `selector`.
+ * Throws an error if the element cannot be found.
+ *
+ * @param selector - The CSS selector for the target DOM element.
+ * @param node - The node to be rendered.
+ * @param ctx - The DOM context.
+ * @returns The result of rendering the `node` into the selected DOM element.
+ * @public
+ */
+export declare const Portal: (selector: string, node: TNode) => Renderable;

package/renderable/providers.d.ts

@@ -1,7 +1,11 @@
 import { TNode, Renderable, ProviderMark } from '../types/domain';
-import { DOMContext } from '../dom/dom-context';
-import { renderableOfTNode } from './element';
 
+/**
+ * Represents a provider function that takes a `TNode` and returns a `Renderable`.
+ * @param node - The node to be rendered.
+ * @returns The rendered output.
+ * @public
+ */
 export type Provider = (node: TNode) => Renderable;
 /**
  * Creates a unique symbol that can be used as a provider mark for a specific type `T`.
@@ -9,8 +13,37 @@ export type Provider = (node: TNode) => Renderable;
  *
  * @param identifier - A string that uniquely identifies the provider.
  * @returns A unique symbol that can be used as a provider mark.
+ * @public
+ */
+export declare const makeProviderMark: <T>(identifier: string) => ProviderMark<T>;
+/**
+ * Higher-order function that composes multiple provider functions into a single provider function.
+ *
+ * @param providerFns - The provider functions to be composed.
+ * @returns A new provider function that applies the composed providers in reverse order.
+ * @public
+ */
+export declare const Provide: <T extends Provider[]>(...providerFns: T) => Provider;
+/**
+ * Creates a renderable with a provider mark and value.
+ *
+ * The value will be available to any consumers that request the provider mark.
+ *
+ * @typeParam T - The type of the provider value.
+ * @param mark - The provider mark.
+ * @param value - The provider value.
+ * @param child - The child TNode.
+ * @returns - The renderable with the provider.
+ * @public
+ */
+export declare const WithProvider: <T>(mark: ProviderMark<T>, value: T, child: TNode) => Renderable;
+/**
+ * Renders the given child with the specified providers.
+ *
+ * @typeParam T - The types of the provider values.
+ * @param providers - An object containing the providers.
+ * @param child - The child to render.
+ * @returns The rendered result.
+ * @public
  */
-export declare function makeProviderMark<T>(identifier: string): ProviderMark<T>;
-export declare const Provide: <T extends Provider[]>(...providerFns: T) => typeof renderableOfTNode;
-export declare const WithProvider: <T>(mark: ProviderMark<T>, value: T, child: TNode) => (ctx: DOMContext) => import('../types/domain').Clear;
-export declare const WithProviders: <T extends unknown[]>(providers: { [K in ProviderMark<T[number]>]: T[number]; }, child: TNode) => (ctx: DOMContext) => import('../types/domain').Clear;
+export declare const WithProviders: <T extends unknown[]>(providers: { [K in ProviderMark<T[number]>]: T[number]; }, child: TNode) => Renderable;

package/renderable/render.d.ts

@@ -1,8 +1,44 @@
 import { Renderable } from '../types/domain';
 import { DOMContext } from '../dom/dom-context';
 
-export declare function renderWithContext(node: Renderable, ctx: DOMContext): () => void;
-export declare function render(node: Renderable, parent: Node | string, { doc, clear }?: {
+/**
+ * Renders the given `renderable` with the provided `ctx` DOM context.
+ *
+ * @param renderable - The renderable node to be rendered.
+ * @param ctx - The DOM context to be used for rendering.
+ * @returns A function that can be called to clear the rendered node.
+ * @public
+ */
+export declare const renderWithContext: (renderable: Renderable, ctx: DOMContext) => () => void;
+/**
+ * Options for rendering.
+ * @public
+ */
+export type RenderOptions = {
+    /**
+     * The document to render to. It is inferred from the parent element if not provided.
+     */
     doc?: Document;
+    /**
+     * Whether to clear the document before rendering. This is useful when the page has been pre-rendered on the server.
+     */
     clear?: boolean;
-}): () => void;
+};
+/**
+ * Renders a `Renderable` node into a specified parent element or selector.
+ *
+ * @param node - The `Renderable` node to render.
+ * @param parent - The parent element or selector where the node should be rendered.
+ * @param options - Optional rendering options.
+ * @returns The result of rendering the `Renderable` node.
+ * @throws Throws a `RenderingError` if the parent element cannot be found by the provided selector.
+ * @public
+ */
+export declare const render: (node: Renderable, parent: Node | string, { doc, clear }?: RenderOptions) => () => void;
+/**
+ * Represents an error that occurs during rendering.
+ * @public
+ */
+export declare class RenderingError extends Error {
+    constructor(message: string);
+}

package/renderable/repeat.d.ts

@@ -1,5 +1,14 @@
-import { Position } from '../std/position';
+import { ElementPosition } from '../std/position';
 import { Signal } from '../std/signal';
 import { TNode, Renderable } from '../types/domain';
 
-export declare const Repeat: (times: Signal<number>, element: (index: Signal<Position>) => TNode, separator?: (pos: Signal<Position>) => TNode) => Renderable;
+/**
+ * Creates a renderable function that repeats a given element a specified number of times.
+ *
+ * @param times - A signal representing the number of times the element should be repeated.
+ * @param element - A function that returns the element to be repeated, based on the current index.
+ * @param separator - (Optional) A function that returns the separator element to be inserted between repeated elements.
+ * @returns A renderable function that renders the repeated elements.
+ * @public
+ */
+export declare const Repeat: (times: Signal<number>, element: (index: Signal<ElementPosition>) => TNode, separator?: (pos: Signal<ElementPosition>) => TNode) => Renderable;

package/renderable/style.d.ts

@@ -1,5 +1,9 @@
 import { NValue, Renderable } from '../types/domain';
 
+/**
+ * A collection of functions to create style renderables.
+ * @public
+ */
 export declare const style: {
     all: (value: NValue<string>) => Renderable;
     [Symbol.iterator]: (value: NValue<string>) => Renderable;

package/renderable/task.d.ts

@@ -1,7 +1,23 @@
 import { TNode, Renderable } from '../types/domain';
 
-export declare const Task: <T>(task: () => Promise<T>, options: {
+/**
+ * Represents the options for a task.
+ *
+ * @typeParam T - The type of the task value.
+ * @public
+ */
+export type TaskOptions<T> = {
     pending?: TNode;
     then: (value: T) => TNode;
     error?: (error: unknown) => TNode;
-} | ((value: T) => TNode)) => Renderable;
+};
+/**
+ * Represents a renderable task that can be executed asynchronously.
+ *
+ * @typeParam T - The type of the value returned by the task.
+ * @param task - The asynchronous task to be executed.
+ * @param options - The options for the task or a function that transforms the task result into a renderable node.
+ * @returns - A function that renders the task and returns a cleanup function.
+ * @public
+ */
+export declare const Task: <T>(task: () => Promise<T>, options: TaskOptions<T> | ((value: T) => TNode)) => Renderable;

package/renderable/text.d.ts

@@ -1,6 +1,19 @@
 import { Renderable, Value } from '../types/domain';
 import { Signal } from '../std/signal';
 
-export declare const staticText: (text: string) => Renderable;
-export declare const signalText: (signal: Signal<string>) => Renderable;
-export declare function Text(value: Value<string>): Renderable;
+/**
+ * @internal
+ */
+export declare const _staticText: (text: string) => Renderable;
+/**
+ * @internal
+ */
+export declare const _signalText: (signal: Signal<string>) => Renderable;
+/**
+ * Creates a renderable text node.
+ *
+ * @param value - The value of the text node.
+ * @returns A renderable text node.
+ * @public
+ */
+export declare const TextNode: (value: Value<string>) => Renderable;

package/renderable/when.d.ts

@@ -1,5 +1,23 @@
-import { TNode } from '../types/domain';
+import { Renderable, TNode } from '../types/domain';
 import { Signal } from '../std/signal';
 
-export declare const When: (condition: Signal<boolean>, then: TNode, otherwise?: TNode) => import('../types/domain').Renderable;
-export declare const Unless: (condition: Signal<boolean>, then: TNode, otherwise?: TNode) => import('../types/domain').Renderable;
+/**
+ * Renders the `then` node if the `condition` is true, otherwise renders the `otherwise` node.
+ *
+ * @param condition - The condition to evaluate.
+ * @param then - The node to render if the condition is true.
+ * @param otherwise - The node to render if the condition is false.
+ * @returns The rendered node.
+ * @public
+ */
+export declare const When: (condition: Signal<boolean>, then: TNode, otherwise?: TNode) => Renderable;
+/**
+ * Executes the `then` TNode if the `condition` Signal evaluates to `false`, otherwise executes the `otherwise` TNode.
+ *
+ * @param condition - The Signal representing the condition to evaluate.
+ * @param then - The TNode to execute if the condition is `false`.
+ * @param otherwise - The optional TNode to execute if the condition is `true`.
+ * @returns The result of executing the `then` or `otherwise` TNode based on the condition.
+ * @public
+ */
+export declare const Unless: (condition: Signal<boolean>, then: TNode, otherwise?: TNode) => Renderable;

package/std/interpolate.d.ts

@@ -1,5 +1,56 @@
-export declare function numberInterpolate(start: number, end: number, delta: number): number;
-export declare function stringInterpolate(start: string, end: string, delta: number): string;
-export declare function dateInterpolate(start: Date, end: Date, delta: number): Date;
-export declare function endInterpolate<T>(_start: T, end: T, _delta: number): T;
-export declare function guessInterpolate<T>(value: T): (start: T, end: T, delta: number) => T;
+/**
+ * Represents a function that interpolates between two values.
+ *
+ * @typeParam T - The type of the values being interpolated.
+ * @param start - The starting value.
+ * @param end - The ending value.
+ * @param delta - The interpolation factor between 0 and 1.
+ * @returns The interpolated value.
+ * @public
+ */
+export type Interpolate<T> = (start: T, end: T, delta: number) => T;
+/**
+ * Interpolates a number between a start and end value based on a delta.
+ *
+ * @param start - The starting value.
+ * @param end - The ending value.
+ * @param delta - The delta value between 0 and 1.
+ * @returns The interpolated number.
+ * @public
+ */
+export declare const interpolateNumber: Interpolate<number>;
+/**
+ * Interpolates between two strings based on a delta value.
+ *
+ * @param start - The starting string.
+ * @param end - The ending string.
+ * @param delta - The delta value between 0 and 1.
+ * @returns The interpolated string.
+ * @public
+ */
+export declare const interpolateString: Interpolate<string>;
+/**
+ * Interpolates between two dates based on a delta value.
+ *
+ * @param start - The starting date.
+ * @param end - The ending date.
+ * @param delta - The delta value between 0 and 1.
+ * @returns The interpolated date.
+ * @public
+ */
+export declare const interpolateDate: Interpolate<Date>;
+/**
+ * A fake interpolate function that always returns the end value.
+ *
+ * @public
+ */
+export declare const endInterpolate: <T>(_start: T, end: T) => T;
+/**
+ * Returns an interpolation function based on the type of the value.
+ *
+ * @typeParam T - The type of the value.
+ * @param value - The value to be interpolated.
+ * @returns An interpolation function that takes a start value, an end value, and a delta, and returns an interpolated value.
+ * @public
+ */
+export declare const guessInterpolate: <T>(value: T) => Interpolate<T>;

package/std/position.d.ts

@@ -1,9 +1,53 @@
-export declare class Position {
+/**
+ * Represents the position of an element in a collection.
+ *
+ * @public
+ */
+export declare class ElementPosition {
+    /**
+     * The index of the element.
+     */
     readonly index: number;
+    /**
+     * The total number of elements in the collection.
+     */
     readonly total: number;
-    constructor(index: number, total: number);
+    /**
+     * Creates a new instance of `ElementPosition`.
+     * @param index - The index of the element.
+     * @param total - The total number of elements in the collection.
+     */
+    constructor(
+    /**
+     * The index of the element.
+     */
+    index: number, 
+    /**
+     * The total number of elements in the collection.
+     */
+    total: number);
+    /**
+     * Gets the counter of the element.
+     */
+    get counter(): number;
+    /**
+     * Checks if the element is the first element in the collection.
+     * @returns `true` if the element is the first element, `false` otherwise.
+     */
     get isFirst(): boolean;
+    /**
+     * Checks if the element is the last element in the collection.
+     * @returns `true` if the element is the last element, `false` otherwise.
+     */
     get isLast(): boolean;
+    /**
+     * Checks if the index of the element is even.
+     * @returns `true` if the index is even, `false` otherwise.
+     */
     get isEven(): boolean;
+    /**
+     * Checks if the index of the element is odd.
+     * @returns `true` if the index is odd, `false` otherwise.
+     */
     get isOdd(): boolean;
 }