@tempots/dom 24.0.0-next.1 → 24.0.0-next.10

package/package.json

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

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

@@ -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.
@@ -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) => void, options?: ListenerOptions) => () => void;
     /**
      * @internal
      */
@@ -391,7 +397,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, Signal } from './signal';
 /**
  * Represents a value that can either be a `Signal<T>` or a generic type `T`.
  *
@@ -75,4 +75,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;