@tempots/dom 24.0.0-next.2 → 24.0.0-next.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/dom",
-  "version": "24.0.0-next.2",
+  "version": "24.0.0-next.21",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",

package/renderable/consumers.d.ts

@@ -37,12 +37,12 @@ export type UseMany<C extends Record<string, Consumer<unknown>>> = {
 /**
  * Creates a renderable function that consumes data from multiple consumers and renders the result.
  *
- * @param consumers - An object containing consumer functions.
+ * @param providers - 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;
+export declare const Use: <C extends Record<string, Consumer<unknown>>>(providers: C, fn: (data: UseMany<C>) => Renderable) => Renderable;
 /**
  * Creates a renderable function that consumes a provider value and renders a `TNode`.
  *

package/renderable/ensure.d.ts

@@ -1,6 +1,12 @@
 import { TNode, Renderable } from '../types/domain';
 import { Signal } from '../std/signal';
 import { Value } from '../std/value';
+export type NillifyValue<T> = Value<T | null | undefined> | Value<T | undefined> | Value<T | null>;
+export type Id<T> = {} & {
+    [P in keyof T]: T[P];
+};
+export type Merge<A, B> = Id<A & B>;
+export type NonNillable<T> = Merge<T, {}>;
 /**
  * Represents a function that ensures a signal has a value before rendering a TNode.
  *
@@ -11,4 +17,12 @@ import { Value } from '../std/value';
  * @returns A renderable function that ensures the signal has a value before rendering a TNode.
  * @public
  */
-export declare const Ensure: <T>(value: Value<T | null> | Value<T | undefined> | Value<T | null | undefined>, then: (value: Signal<NonNullable<T>>) => TNode, otherwise?: () => TNode) => Renderable;
+export declare const Ensure: <T>(value: NillifyValue<T>, then: (value: Signal<NonNillable<T>>) => TNode, otherwise?: () => TNode) => Renderable;
+/**
+ * Ensures that all signals have a value before rendering a TNode.
+ *
+ * @param signals - The signals to ensure have a value.
+ * @returns A renderable function that ensures all signals have a value before rendering a TNode.
+ * @public
+ */
+export declare const EnsureAll: <T extends readonly Value<any>[]>(...signals: { [K in keyof T]: NillifyValue<T[K]>; }) => (callback: (...values: { [K in keyof T]: Signal<NonNillable<T[K] extends Value<infer U> ? U : never>>; }) => TNode, otherwise?: () => TNode) => Renderable;

package/renderable/map-signal.d.ts

@@ -1,4 +1,4 @@
-import { Renderable } from '../types/domain';
+import { Renderable, TNode } from '../types/domain';
 import { Value } from '../std/value';
 /**
  * Maps the values emitted by a signal to a renderable function and returns a new renderable function.
@@ -11,8 +11,8 @@ import { Value } from '../std/value';
  *
  * @typeParam T - The type of values emitted by the signal.
  * @param vlaue - The signal or value to map.
- * @param fn - The function to map the signal values to renderable functions.
+ * @param fn - The function to map the signal values to a renderable/TNode.
  * @returns - A new renderable function that represents the mapped signal.
  * @public
  */
-export declare const MapSignal: <T>(value: Value<T>, fn: (value: T) => Renderable) => Renderable;
+export declare const MapSignal: <T>(value: Value<T>, fn: (value: T) => TNode) => Renderable;

package/renderable/on-dispose.d.ts

@@ -1,9 +1,10 @@
 import { Renderable } from '../types/domain';
 import { DOMContext } from '../dom/dom-context';
+export type DisposeCallback = (removeTree: boolean, ctx: DOMContext) => void;
 /**
  * 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.
+ * @param fns - The function(s) 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 OnDispose: (fn: (removeTree: boolean, ctx: DOMContext) => void) => Renderable;
+export declare const OnDispose: (...fns: DisposeCallback[]) => Renderable;

package/renderable/oneof.d.ts

@@ -9,6 +9,16 @@ import { Renderable, TNode } from '../types/domain';
 export type OneOfOptions<T extends Record<string, unknown>> = {
     [KK in keyof T]: (value: Signal<T[KK]>) => TNode;
 };
+/**
+ * Converts an object to a union of its keys.
+ * @typeParam T - The type of the object.
+ * @public
+ */
+export type ObjectToUnion<T> = {
+    [K in keyof T]: {
+        [P in K]: T[K];
+    };
+}[keyof T];
 /**
  * Creates a renderable function that renders different components based on the value of a signal.
  *

package/renderable/probe.d.ts

@@ -3,7 +3,8 @@ import { Renderable, TNode } from '../types/domain';
  * A provider mark for a signal representing the current appearance type.
  * @public
  */
-export declare const probeMarker: import('../types/domain').ProviderMark<(identifier: symbol) => void>;
+export declare const probeMarker: import('..').ProviderMark<(identifier: symbol) => void>;
+export type ProbeResolution = 'resolved' | 'timeout';
 /**
  * Provides a child component with a probe, which can be used to trigger a callback when all probes with the same identifier are resolved.
  * To resolve a probe, call the `done` function passed using the `UseProbe` renderable.
@@ -14,7 +15,12 @@ export declare const probeMarker: import('../types/domain').ProviderMark<(identi
  * @returns The child component with the probe.
  * @public
  */
-export declare const ProvideProbe: (identifier: symbol, callback: () => void, child: TNode) => Renderable;
+export declare const ProvideProbe: ({ identifier, callback, child, timeout, }: {
+    identifier: symbol;
+    callback?: (resolution: ProbeResolution) => void;
+    child: TNode;
+    timeout?: number;
+}) => Renderable;
 /**
  * Uses a probe, which can be used to trigger a callback when all probes with the same identifier are resolved.
  * To resolve a probe, call the `done` function.
@@ -34,7 +40,10 @@ export declare const UseProbe: (identifier: symbol, fn: (done: () => void) => TN
  * @returns The child component with the probe.
  * @public
  */
-export declare const ProvideGlobalProbe: (callback: () => void, child: TNode) => Renderable;
+export declare const ProvideGlobalProbe: ({ callback, timeout, }: {
+    callback?: (resolution: ProbeResolution) => void;
+    timeout?: number;
+}, child: TNode) => Renderable;
 /**
  * Uses a global probe, which can be used to trigger a callback when all probes with the same identifier are resolved.
  * To resolve a probe, call the `done` function.

package/renderable/render.d.ts

@@ -36,6 +36,16 @@ export type RenderOptions = {
  * @public
  */
 export declare const render: (node: Renderable, parent: Node | string, { doc, clear }?: RenderOptions) => () => void;
+/**
+ * Runs a renderable function in a headless environment.
+ *
+ * @param makeRenderable - A function that returns a Renderable to be rendered in the headless environment.
+ * @param options - Optional configuration for the headless environment.
+ * @param options.startUrl - The initial URL for the headless environment. Defaults to 'https://example.com'.
+ * @param options.selector - The selector used to find the root element in the headless environment. Defaults to ':root'.
+ * @returns An object containing the clear function, root element, and current URL Signal of the headless environment.
+ * @public
+ */
 export declare const runHeadless: (makeRenderable: () => Renderable, { startUrl, selector, }?: {
     startUrl?: Value<string>;
     selector?: string;
@@ -51,3 +61,173 @@ export declare const runHeadless: (makeRenderable: () => Renderable, { startUrl,
 export declare class RenderingError extends Error {
     constructor(message: string);
 }
+/**
+ * @internal
+ */
+export declare const _NODE_PLACEHOLDER_ATTR = "data-tts-node";
+export declare const CLASS_PLACEHOLDER_ATTR = "data-tts-class";
+/**
+ * Represents an adapter for headless rendering environments.
+ * This class provides methods to interact with elements in a headless context.
+ *
+ * This class is used to adapt the HeadlesContext to whatever you want to use to render your final HTML.
+ * You can use libraries like cheerio to render your HTML.
+ *
+ * For cheerio an adapter could look like this:
+ *
+ * ```ts
+ * const renderWithCheerio = (html: string, root: HeadlessPortal) => {
+ *   const $ = cheerio.load(html)
+ *
+ *   // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ *   const adapter = new HeadlessAdapter<cheerio.Cheerio<any>>({
+ *     // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ *     select: (selector: string): cheerio.Cheerio<any>[] => [$(selector)],
+ *     getAttribute: (el, name: string) => el.attr(name) ?? null,
+ *     setAttribute: (el, name: string, value: string | null) => {
+ *       if (value === null) {
+ *         el.removeAttr(name)
+ *       } else {
+ *         el.attr(name, value)
+ *       }
+ *     },
+ *     getClass: el => el.attr('class') ?? '',
+ *     setClass: (el, value: string | null) => {
+ *       if (value === null) {
+ *         el.removeAttr('class')
+ *       } else {
+ *         el.attr('class', value)
+ *       }
+ *     },
+ *     getStyles: el => el.attr('style') ?? {},
+ *     setStyles: (el, value: Record<string, string>) => {
+ *       if (Object.keys(value).length === 0) {
+ *         el.removeAttr('style')
+ *       } else {
+ *         el.css(value)
+ *       }
+ *     },
+ *     appendHTML: (el, html) => el.append(html),
+ *     getInnerHTML: el => el.html() ?? '',
+ *     setInnerHTML: (el, html) => el.html(html),
+ *     getInnerText: el => el.text() ?? '',
+ *     setInnerText: (el, text) => el.text(text),
+ *   })
+ *
+ *   adapter.setFromRoot(root, true)
+ *
+ *   return $.html()
+ * }
+ * ```
+ *
+ * This function will return the rendered HTML as a string.
+ *
+ * @typeParam EL - The type of elements in the headless environment.
+ * @public
+ */
+export declare class HeadlessAdapter<EL> {
+    /**
+     * Selects elements from the headless environment.
+     * @param selector - The selector to select elements from. The supported selectors are CSS selectors whose complexity depends on the adapter implementation.
+     * @returns An array of elements.
+     */
+    readonly select: (selector: string) => EL[];
+    /**
+     * Gets the value of an attribute from an element.
+     * @param el - The element to get the attribute from.
+     * @param attr - The attribute to get the value from.
+     * @returns The value of the attribute or null if the attribute is not set.
+     */
+    readonly getAttribute: (el: EL, attr: string) => string | null;
+    /**
+     * Sets the value of an attribute on an element.
+     * @param el - The element to set the attribute on.
+     * @param attr - The attribute to set the value of.
+     * @param value - The value to set the attribute to.
+     */
+    readonly setAttribute: (el: EL, attr: string, value: string | null) => void;
+    /**
+     * Gets the class of an element.
+     * @param el - The element to get the class from.
+     * @returns The class of the element or an empty string if the class is not set.
+     */
+    readonly getClass: (el: EL) => string | null;
+    /**
+     * Sets the class of an element.
+     * @param el - The element to set the class on.
+     * @param cls - The class to set.
+     */
+    readonly setClass: (el: EL, cls: string | null) => void;
+    /**
+     * Gets the styles of an element.
+     * @param el - The element to get the styles from.
+     * @returns The styles of the element.
+     */
+    readonly getStyles: (el: EL) => Record<string, string>;
+    /**
+     * Sets the styles of an element.
+     * @param el - The element to set the styles on.
+     */
+    readonly setStyles: (el: EL, styles: Record<string, string>) => void;
+    /**
+     * Appends HTML to an element.
+     * @param el - The element to append the HTML to.
+     * @param html - The HTML to append.
+     */
+    readonly appendHTML: (el: EL, html: string) => void;
+    /**
+     * Gets the inner HTML of an element.
+     * @param el - The element to get the inner HTML from.
+     * @returns The inner HTML of the element or an empty string if the inner HTML is not set.
+     */
+    readonly getInnerHTML: (el: EL) => string | null;
+    /**
+     * Sets the inner HTML of an element.
+     * @param el - The element to set the inner HTML on.
+     * @param html - The inner HTML to set.
+     */
+    readonly setInnerHTML: (el: EL, html: string) => void;
+    /**
+     * Gets the inner text of an element.
+     * @param el - The element to get the inner text from.
+     * @returns The inner text of the element or an empty string if the inner text is not set.
+     */
+    readonly getInnerText: (el: EL) => string | null;
+    /**
+     * Sets the inner text of an element.
+     * @param el - The element to set the inner text on.
+     * @param text - The inner text to set.
+     */
+    readonly setInnerText: (el: EL, text: string) => void;
+    constructor({ select, getAttribute, setAttribute, getClass, setClass, getStyles, setStyles, appendHTML, getInnerHTML, setInnerHTML, getInnerText, setInnerText, }: {
+        select: (selector: string) => EL[];
+        getAttribute: (el: EL, attr: string) => string | null;
+        setAttribute: (el: EL, attr: string, value: string | null) => void;
+        getClass: (el: EL) => string | null;
+        setClass: (el: EL, cls: string | null) => void;
+        getStyles: (el: EL) => Record<string, string>;
+        setStyles: (el: EL, styles: Record<string, string>) => void;
+        appendHTML: (el: EL, html: string) => void;
+        getInnerHTML: (el: EL) => string | null;
+        setInnerHTML: (el: EL, html: string) => void;
+        getInnerText: (el: EL) => string | null;
+        setInnerText: (el: EL, text: string) => void;
+    });
+    /**
+     * Sets the content of the root element from a HeadlessPortal. Generally this will be the same instance that is
+     * returned by `runHeadless`.
+     *
+     * @param root - The HeadlessPortal containing the content to set.
+     * @param setPlaceholders - Whether to set placeholders for the content. This allows you to restore the original content
+     * when you render on the server and then hydrate on the client.
+     */
+    readonly setFromRoot: (root: HeadlessPortal, setPlaceholders: boolean) => void;
+}
+/**
+ * Restores all placeholders in the DOM. This function is useful when the HTML is rendered on the server and then
+ * hydrated on the client. It restores the original content that was replaced with placeholders during the initial
+ * render. When you render on the server side, make sure to call `HeadlessAdapter.setFromRoot` with the result of
+ * `runHeadless` and the second parameter `setPlaceholders` to `true`.
+ * @public
+ */
+export declare const restoreTempoPlaceholders: () => void;

package/renderable/style.d.ts

@@ -5,7 +5,6 @@ import { NValue, Renderable } from '../types/domain';
  */
 export declare const style: {
     all: (value: NValue<string>) => Renderable;
-    [Symbol.iterator]: (value: NValue<string>) => Renderable;
     accentColor: (value: NValue<string>) => Renderable;
     alignContent: (value: NValue<string>) => Renderable;
     alignItems: (value: NValue<string>) => Renderable;
@@ -327,6 +326,7 @@ export declare const style: {
     right: (value: NValue<string>) => Renderable;
     rotate: (value: NValue<string>) => Renderable;
     rowGap: (value: NValue<string>) => Renderable;
+    rubyAlign: (value: NValue<string>) => Renderable;
     rubyPosition: (value: NValue<string>) => Renderable;
     rx: (value: NValue<string>) => Renderable;
     ry: (value: NValue<string>) => Renderable;
@@ -418,6 +418,7 @@ export declare const style: {
     userSelect: (value: NValue<string>) => Renderable;
     vectorEffect: (value: NValue<string>) => Renderable;
     verticalAlign: (value: NValue<string>) => Renderable;
+    viewTransitionName: (value: NValue<string>) => Renderable;
     visibility: (value: NValue<string>) => Renderable;
     webkitAlignContent: (value: NValue<string>) => Renderable;
     webkitAlignItems: (value: NValue<string>) => Renderable;

package/std/signal.d.ts

@@ -14,6 +14,11 @@ export type AnySignal<T = any> = Signal<T> | Prop<T> | Computed<T>;
 export type AtGetter<T> = {
     [K in keyof T]-?: Signal<T[K]>;
 };
+export type ListenerOptions = {
+    skipInitial?: boolean;
+    once?: boolean;
+    abortSignal?: AbortSignal;
+};
 /**
  * Represents a signal that holds a value and notifies its listeners when the value changes.
  * @typeParam T - The type of the value held by the signal.
@@ -54,7 +59,7 @@ export declare class Signal<T> {
     /**
      * @internal
      */
-    protected readonly _onValueListeners: Array<(value: T) => void>;
+    protected readonly _onValueListeners: Array<(value: T, previousValue: T | undefined) => void>;
     /**
      * @internal
      */
@@ -88,8 +93,9 @@ export declare class Signal<T> {
      * Returns a function that can be called to unregister the listener.
      *
      * @param listener - The listener function to be called when the value of the signal changes.
+     * @param options - Options for the listener.
      */
-    readonly on: (listener: (value: T) => void) => () => void;
+    readonly on: (listener: (value: T, previousValue: T | undefined) => void, options?: ListenerOptions) => () => void;
     /**
      * @internal
      */
@@ -205,10 +211,20 @@ export declare class Signal<T> {
     readonly feedProp: (prop: Prop<T>, autoDisposeProp?: boolean) => Prop<T>;
     /**
      * Derives a new property from the current signal.
-     * @param autoDisposeProp - Determines whether the derived property should be automatically disposed.
+     * @param options - The options for the derived property.
+     * @param options.autoDisposeProp - Determines whether the derived property should be automatically disposed.
+     * @param options.equals - A function that determines if two values are equal.
      * @returns The derived property.
      */
-    readonly deriveProp: (autoDisposeProp?: boolean) => Prop<T>;
+    readonly deriveProp: ({ autoDisposeProp, equals, }?: {
+        autoDisposeProp?: boolean;
+        equals?: (a: T, b: T) => boolean;
+    }) => Prop<T>;
+    /**
+     * Derives a new signal from the current signal. Useful to create a new signal that emits the same values as the current signal but can be disposed independently.
+     * @returns A new signal that emits the same values as the current signal.
+     */
+    readonly derive: () => Computed<T>;
     /**
      * Returns a signal that emits the count of values received so far.
      * @returns A signal that emits the count of values received so far.
@@ -391,7 +407,7 @@ export declare const makeComputed: <T>(fn: () => T, dependencies: Array<AnySigna
  * @returns A disposable object that can be used to stop the effect.
  * @public
  */
-export declare const makeEffect: (fn: () => void, signals: Array<AnySignal>) => () => void;
+export declare const makeEffect: (fn: () => void, signals: Array<AnySignal>, options?: ListenerOptions) => () => void;
 /**
  * Creates a new Prop object with the specified value and equality function.
  *

package/std/value.d.ts

@@ -1,5 +1,5 @@
 import { GetValueTypes } from '../types/domain';
-import { Signal } from './signal';
+import { ListenerOptions, Prop, Signal } from './signal';
 /**
  * Represents a value that can either be a `Signal<T>` or a generic type `T`.
  *
@@ -57,6 +57,20 @@ export declare const Value: {
      * @param value - The value or Signal instance to dispose of.
      */
     dispose: <T>(value: Value<T>) => void;
+    /**
+     * Derives a Prop from a Signal.
+     * If the value is a Signal, it returns a new Prop with the derived value.
+     * If the value is not a Signal, it returns a new Prop with the value.
+     * @param value - The value or Signal instance to derive the Prop from.
+     * @param options - The options for the derived Prop.
+     * @param options.autoDisposeProp - Determines whether the derived Prop should be automatically disposed.
+     * @param options.equals - A function that determines if two values are equal.
+     * @returns A Prop instance.
+     */
+    deriveProp: <T>(value: Value<T>, { autoDisposeProp, equals, }?: {
+        autoDisposeProp?: boolean;
+        equals?: (a: T, b: T) => boolean;
+    }) => Prop<T>;
 };
 /**
  * Creates a computed signal that depends on other signals or literal values and updates when any of the dependencies change.
@@ -75,4 +89,4 @@ export declare const makeComputedOf: <T extends Value<unknown>[]>(...args: T) =>
  * @returns A disposable object that can be used to stop the effect.
  * @public
  */
-export declare const makeEffectOf: <T extends Value<unknown>[]>(...args: T) => (fn: (...args: GetValueTypes<T>) => void) => void;
+export declare const makeEffectOf: <T extends Value<unknown>[]>(...args: T) => (fn: (...args: GetValueTypes<T>) => void, options?: ListenerOptions) => () => void;

package/types/css-styles.d.ts

@@ -3,7 +3,7 @@
  *
  * @public
  */
-export type ExcludeFromStyle = 'getPropertyPriority' | 'getPropertyValue' | 'item' | 'removeProperty' | 'setProperty' | 'parentRule' | 'length' | 'name' | number;
+export type ExcludeFromStyle = 'getPropertyPriority' | 'getPropertyValue' | 'item' | 'removeProperty' | 'setProperty' | 'parentRule' | 'length' | 'name' | number | typeof Symbol.iterator;
 /**
  * Represents a subset of CSS styles.
  * It is a type that excludes certain properties from the `CSSStyleDeclaration` type.