@tempots/dom 26.11.0 → 28.0.0

package/renderable/style.d.ts

@@ -101,6 +101,7 @@ export declare const style: {
     borderTopWidth: (value: NValue<string>) => Renderable;
     borderWidth: (value: NValue<string>) => Renderable;
     bottom: (value: NValue<string>) => Renderable;
+    boxDecorationBreak: (value: NValue<string>) => Renderable;
     boxShadow: (value: NValue<string>) => Renderable;
     boxSizing: (value: NValue<string>) => Renderable;
     breakAfter: (value: NValue<string>) => Renderable;
@@ -379,6 +380,9 @@ export declare const style: {
     textAlign: (value: NValue<string>) => Renderable;
     textAlignLast: (value: NValue<string>) => Renderable;
     textAnchor: (value: NValue<string>) => Renderable;
+    textBox: (value: NValue<string>) => Renderable;
+    textBoxEdge: (value: NValue<string>) => Renderable;
+    textBoxTrim: (value: NValue<string>) => Renderable;
     textCombineUpright: (value: NValue<string>) => Renderable;
     textDecoration: (value: NValue<string>) => Renderable;
     textDecorationColor: (value: NValue<string>) => Renderable;
@@ -418,6 +422,7 @@ export declare const style: {
     userSelect: (value: NValue<string>) => Renderable;
     vectorEffect: (value: NValue<string>) => Renderable;
     verticalAlign: (value: NValue<string>) => Renderable;
+    viewTransitionClass: (value: NValue<string>) => Renderable;
     viewTransitionName: (value: NValue<string>) => Renderable;
     visibility: (value: NValue<string>) => Renderable;
     webkitAlignContent: (value: NValue<string>) => Renderable;

package/std/signal.d.ts

@@ -20,21 +20,82 @@ export type ListenerOptions = {
     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.
+ * A reactive signal that holds a value and notifies listeners when the value changes.
+ *
+ * Signals are the foundation of Tempo's reactive system. They provide a way to create
+ * reactive data that automatically updates the UI when changed. Signals can be observed,
+ * transformed, and composed to create complex reactive behaviors.
+ *
+ * @example
+ * ```typescript
+ * // Create a signal with an initial value
+ * const count = new Signal(0, (a, b) => a === b)
+ *
+ * // Listen to changes
+ * const unsubscribe = count.on((newValue, oldValue) => {
+ *   console.log(`Count changed from ${oldValue} to ${newValue}`)
+ * })
+ *
+ * // Transform the signal
+ * const doubled = count.map(n => n * 2)
+ * const isEven = count.map(n => n % 2 === 0)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create a signal from a Promise
+ * const userSignal = Signal.ofPromise(
+ *   fetch('/api/user').then(r => r.json()),
+ *   null, // initial value
+ *   error => ({ error: error.message }) // error recovery
+ * )
+ * ```
+ *
+ * @typeParam T - The type of the value held by the signal
  * @public
  */
 export declare class Signal<T> {
     readonly equals: (a: T, b: T) => boolean;
     /**
-     * Creates a Signal that holds the result of a Promise.
+     * Creates a Signal that holds the result of a Promise, with proper error handling.
+     *
+     * This static method creates a signal that starts with an initial value and updates
+     * when the promise resolves. If the promise rejects, an optional recovery function
+     * can provide a fallback value.
+     *
+     * @example
+     * ```typescript
+     * // Basic usage with API call
+     * const userData = Signal.ofPromise(
+     *   fetch('/api/user').then(r => r.json()),
+     *   { loading: true }, // initial state
+     *   error => ({ error: error.message, loading: false }) // error recovery
+     * )
+     *
+     * // Use in UI
+     * Ensure(userData,
+     *   (user) => html.div('Welcome, ', user.map(u => u.name)),
+     *   () => html.div('Loading...')
+     * )
+     * ```
      *
-     * @typeParam O - The type of the value returned by the Promise.
-     * @param promise - The Promise to use to feed the Signal.
-     * @param init - The initial value of the Signal before the Promise resolves.
-     * @param recover - A function to recover from Promise rejection and provide an alternative value for the Signal.
-     * @param equals - A function to compare two values of type O for equality. Defaults to strict equality (===).
-     * @returns - A Signal that represents the result of the Promise.
+     * @example
+     * ```typescript
+     * // With custom equality function
+     * const config = Signal.ofPromise(
+     *   loadConfig(),
+     *   {},
+     *   () => ({}),
+     *   (a, b) => JSON.stringify(a) === JSON.stringify(b) // deep equality
+     * )
+     * ```
+     *
+     * @typeParam O - The type of the value returned by the Promise
+     * @param promise - The Promise to use to feed the Signal
+     * @param init - The initial value of the Signal before the Promise resolves
+     * @param recover - Optional function to recover from Promise rejection and provide an alternative value
+     * @param equals - Function to compare two values for equality (defaults to strict equality)
+     * @returns A Signal that represents the result of the Promise
      */
     static readonly ofPromise: <O>(promise: Promise<O>, init: O, recover?: (error: unknown) => O, equals?: (a: O, b: O) => boolean) => Signal<O>;
     /**
@@ -120,13 +181,54 @@ export declare class Signal<T> {
      */
     readonly dispose: () => void;
     /**
-     * Returns a new Computed instance that applies the given mapping function to the value of this Signal.
-     * The mapping function is called whenever the value of this Signal changes.
+     * Creates a new computed signal by applying a transformation function to this signal's value.
      *
-     * @typeParam O - The type of the mapped value.
-     * @param fn - The mapping function to apply to the value of this Signal.
-     * @param equals - Optional equality function to determine if two mapped values are equal.
-     * @returns - A new Computed instance with the mapped value.
+     * The `map` method is one of the most commonly used signal operations. It creates a new
+     * computed signal that automatically updates whenever the source signal changes. The
+     * transformation function is called with the current value and should return the new value.
+     *
+     * @example
+     * ```typescript
+     * const count = prop(5)
+     *
+     * // Transform to different types
+     * const doubled = count.map(n => n * 2)
+     * const message = count.map(n => `Count is ${n}`)
+     * const isEven = count.map(n => n % 2 === 0)
+     *
+     * // Use in UI
+     * html.div(
+     *   html.div('Original: ', count.map(String)),
+     *   html.div('Doubled: ', doubled.map(String)),
+     *   html.div('Message: ', message),
+     *   html.div('Is even: ', isEven.map(String))
+     * )
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Chain multiple transformations
+     * const user = prop({ name: 'John', age: 30 })
+     * const greeting = user
+     *   .map(u => u.name)
+     *   .map(name => name.toUpperCase())
+     *   .map(name => `Hello, ${name}!`)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With custom equality function for objects
+     * const items = prop([{ id: 1, name: 'Item 1' }])
+     * const itemNames = items.map(
+     *   items => items.map(item => item.name),
+     *   (a, b) => JSON.stringify(a) === JSON.stringify(b) // deep equality
+     * )
+     * ```
+     *
+     * @typeParam O - The type of the transformed value
+     * @param fn - Function that transforms the signal's value to a new value
+     * @param equals - Optional function to determine if two transformed values are equal (defaults to strict equality)
+     * @returns A new computed signal with the transformed value
      */
     readonly map: <O>(fn: (value: T) => O, equals?: (a: O, b: O) => boolean) => Computed<O>;
     /**

package/types/domain.d.ts

@@ -1,15 +1,113 @@
 import { DOMContext } from '../dom/dom-context';
 import { Value } from '../std/value';
 /**
- * Represents a function that can be rendered in the DOM.
- * @param ctx - The DOM context for rendering.
- * @returns A function that clears the rendered content.
+ * A function that renders content into the DOM and returns a cleanup function.
+ *
+ * Renderables are the fundamental building blocks of Tempo applications. They receive
+ * a DOMContext and use it to create DOM elements, text nodes, or other content.
+ * The returned Clear function is called when the renderable needs to be removed
+ * from the DOM.
+ *
+ * @example
+ * ```typescript
+ * // Simple renderable that creates a div
+ * const MyComponent: Renderable = (ctx) => {
+ *   const divCtx = ctx.makeChildElement('div', undefined)
+ *   divCtx.makeChildText('Hello, World!')
+ *
+ *   // Return cleanup function
+ *   return (removeTree) => {
+ *     if (removeTree) {
+ *       // Cleanup logic here
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Renderable with event listeners
+ * const Button: Renderable = (ctx) => {
+ *   const buttonCtx = ctx.makeChildElement('button', undefined)
+ *   buttonCtx.makeChildText('Click me')
+ *
+ *   const clearClick = buttonCtx.on('click', () => {
+ *     console.log('Button clicked!')
+ *   })
+ *
+ *   return (removeTree) => {
+ *     clearClick(removeTree)
+ *   }
+ * }
+ * ```
+ *
+ * @template CTX - The type of DOMContext (defaults to DOMContext)
+ * @param ctx - The DOM context for rendering
+ * @returns A cleanup function that removes the rendered content when called
  * @public
  */
 export type Renderable<CTX extends DOMContext = DOMContext> = (ctx: CTX) => Clear;
 /**
- * Represents a node in the rendering tree.
- * It can be a renderable element, a string value, undefined, null, or an array of renderable elements.
+ * A flexible type representing any content that can be rendered in Tempo.
+ *
+ * TNode (Template Node) is the union type that encompasses all possible content
+ * that can be rendered in a Tempo application. This includes components, text,
+ * signals, arrays of content, and null/undefined values for conditional rendering.
+ *
+ * @example
+ * ```typescript
+ * // All of these are valid TNode values:
+ *
+ * // Renderable component
+ * const component: TNode = MyComponent()
+ *
+ * // Static text
+ * const text: TNode = 'Hello, World!'
+ *
+ * // Signal text
+ * const dynamicText: TNode = userNameSignal
+ *
+ * // Array of content
+ * const list: TNode = [
+ *   html.div('Item 1'),
+ *   html.div('Item 2'),
+ *   html.div('Item 3')
+ * ]
+ *
+ * // Conditional content
+ * const conditional: TNode = isVisible.value ? html.div('Visible') : null
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Function that accepts any renderable content
+ * function Container(children: TNode): Renderable {
+ *   return html.div(
+ *     attr.class('container'),
+ *     children // Can be any TNode type
+ *   )
+ * }
+ *
+ * // Usage with different TNode types
+ * Container('Simple text')
+ * Container(MyComponent())
+ * Container([html.p('Paragraph 1'), html.p('Paragraph 2')])
+ * Container(isLoading.value ? 'Loading...' : null)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Building complex content with TNode
+ * const buildContent = (items: string[]): TNode => {
+ *   if (items.length === 0) {
+ *     return html.div('No items found')
+ *   }
+ *
+ *   return items.map(item => html.div(item))
+ * }
+ * ```
+ *
+ * @template CTX - The type of DOMContext (defaults to DOMContext)
  * @public
  */
 export type TNode<CTX extends DOMContext = DOMContext> = Renderable<CTX> | Value<string> | undefined | null | Renderable<CTX>[];