@tempots/dom 26.11.0 → 28.0.0

package/package.json

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

package/renderable/ensure.d.ts

@@ -8,21 +8,84 @@ export type Id<T> = {} & {
 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.
+ * Conditionally renders content based on whether a value is non-null/non-undefined.
  *
- * @typeParam T - The type of the signal value.
- * @param value - The signal or literal that may hold a value of type T or null or undefined.
- * @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.
+ * This function provides a type-safe way to handle nullable values in your UI. It only
+ * renders the `then` content when the value is not null or undefined, and optionally
+ * renders alternative content when the value is null/undefined.
+ *
+ * @example
+ * ```typescript
+ * // With a signal that might be null
+ * const user = prop<User | null>(null)
+ *
+ * Ensure(user,
+ *   (userSignal) => html.div('Welcome, ', userSignal.map(u => u.name)),
+ *   () => html.div('Please log in')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With a literal value
+ * const maybeData = getData() // returns string | null
+ *
+ * Ensure(maybeData,
+ *   (dataSignal) => html.div('Data: ', dataSignal),
+ *   () => html.div('No data available')
+ * )
+ * ```
+ *
+ * @typeParam T - The type of the value when it's not null/undefined
+ * @param value - A signal or literal value that may be null or undefined
+ * @param then - Function that receives a signal of the non-nullable value and returns content to render
+ * @param otherwise - Optional function that returns content to render when value is null/undefined
+ * @returns A renderable that conditionally displays content based on the value's nullability
  * @public
  */
 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.
+ * Conditionally renders content only when ALL provided values are non-null/non-undefined.
+ *
+ * This function is useful when you need multiple values to be present before rendering content.
+ * It waits for all values to be non-null/non-undefined before calling the callback function.
+ * If any value becomes null/undefined, it will render the `otherwise` content instead.
+ *
+ * @example
+ * ```typescript
+ * const user = prop<User | null>(null)
+ * const profile = prop<Profile | null>(null)
+ * const settings = prop<Settings | null>(null)
+ *
+ * EnsureAll(user, profile, settings)(
+ *   (userSignal, profileSignal, settingsSignal) => html.div(
+ *     html.h1('Dashboard'),
+ *     html.div('User: ', userSignal.map(u => u.name)),
+ *     html.div('Profile: ', profileSignal.map(p => p.bio)),
+ *     html.div('Theme: ', settingsSignal.map(s => s.theme))
+ *   ),
+ *   () => html.div('Loading user data...')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Mix of signals and literal values
+ * const apiData = prop<Data | null>(null)
+ * const staticConfig = { theme: 'dark' }
+ *
+ * EnsureAll(apiData, staticConfig)(
+ *   (dataSignal, configSignal) => html.div(
+ *     'Data loaded with theme: ',
+ *     configSignal.map(c => c.theme)
+ *   ),
+ *   () => html.div('Waiting for data...')
+ * )
+ * ```
  *
- * @param signals - The signals to ensure have a value.
- * @returns A renderable function that ensures all signals have a value before rendering a TNode.
+ * @typeParam T - Tuple type representing the types of all input values
+ * @param signals - Variable number of values (signals or literals) that may be null/undefined
+ * @returns A function that takes a callback and optional otherwise function, returning a renderable
  * @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/foreach.d.ts

@@ -3,13 +3,63 @@ import { Signal } from '../std/signal';
 import { ElementPosition } from '../std/element-position';
 import { Value } from '../std/value';
 /**
- * Renders a list of items based on a signal of arrays.
+ * Efficiently renders a dynamic list of items from an array signal.
  *
- * @typeParam T - The type of items in the array.
- * @param value - 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.
+ * This function creates a reactive list that automatically updates when the source array changes.
+ * Each item in the array gets its own signal that tracks changes to that specific item.
+ * The list efficiently handles additions, removals, and modifications to the array.
+ *
+ * @example
+ * ```typescript
+ * const todos = prop([
+ *   { id: 1, text: 'Learn Tempo', done: false },
+ *   { id: 2, text: 'Build an app', done: false }
+ * ])
+ *
+ * ForEach(todos,
+ *   (todoSignal, position) => html.div(
+ *     html.input(
+ *       attr.type('checkbox'),
+ *       attr.checked(todoSignal.map(t => t.done))
+ *     ),
+ *     html.span(todoSignal.map(t => t.text)),
+ *     html.small(`Item ${position.index + 1}`)
+ *   )
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With separators between items
+ * const items = prop(['apple', 'banana', 'cherry'])
+ *
+ * ForEach(items,
+ *   (itemSignal) => html.span(itemSignal),
+ *   () => html.span(', ') // Separator between items
+ * )
+ * // Renders: apple, banana, cherry
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using position information
+ * const numbers = prop([10, 20, 30])
+ *
+ * ForEach(numbers,
+ *   (numberSignal, position) => html.div(
+ *     `Position ${position.index}: `,
+ *     numberSignal,
+ *     position.isFirst ? ' (first)' : '',
+ *     position.isLast ? ' (last)' : ''
+ *   )
+ * )
+ * ```
+ *
+ * @typeParam T - The type of items in the array
+ * @param value - A signal or literal array to iterate over
+ * @param item - Function that renders each item, receives the item signal and position info
+ * @param separator - Optional function that renders content between items
+ * @returns A renderable that displays the dynamic list
  * @public
  */
 export declare const ForEach: <T>(value: Value<T[]>, item: (value: Signal<T>, position: ElementPosition) => TNode, separator?: (pos: ElementPosition) => TNode) => Renderable;

package/renderable/not-empty.d.ts

@@ -9,7 +9,7 @@ import { Renderable } from '../types/domain';
  * @typeParam T - The type of elements in the array.
  * @param value - The signal or literal 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.
+ * @param whenEmpty - The component to display when the array is empty.
  * @returns - The renderable component.
  * @public
  */

package/renderable/on.d.ts

@@ -7,7 +7,59 @@ import { DOMContext } from '../dom/dom-context';
  */
 export declare const OnChecked: (fn: (event: boolean, ctx: DOMContext) => void) => Renderable;
 /**
- * Represents a collection of HTML event handlers that can be attached to an element.
+ * Provides type-safe event handlers for all HTML events.
+ *
+ * The `on` object is a proxy that provides access to all standard HTML events with proper
+ * TypeScript typing. Each event handler receives the native event object and the DOM context.
+ *
+ * @example
+ * ```typescript
+ * // Basic click handler
+ * html.button(
+ *   on.click((event, ctx) => {
+ *     console.log('Button clicked!', event.target)
+ *   }),
+ *   'Click me'
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Input event with value extraction
+ * const text = prop('')
+ *
+ * html.input(
+ *   attr.value(text),
+ *   on.input((event) => {
+ *     text.value = (event.target as HTMLInputElement).value
+ *   })
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple event handlers on same element
+ * html.div(
+ *   on.mouseenter(() => console.log('Mouse entered')),
+ *   on.mouseleave(() => console.log('Mouse left')),
+ *   on.click(() => console.log('Clicked')),
+ *   'Hover and click me'
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Keyboard event handling
+ * html.input(
+ *   on.keydown((event) => {
+ *     if (event.key === 'Enter') {
+ *       console.log('Enter pressed!')
+ *       event.preventDefault()
+ *     }
+ *   })
+ * )
+ * ```
+ *
  * @public
  */
 export declare const on: {
@@ -100,18 +152,78 @@ export declare const on: {
     waiting: (handler: (event: Event, ctx: DOMContext) => void) => Renderable;
 };
 /**
- * Creates an event handler that emits the value of an HTMLInputElement.
+ * Creates an event handler that extracts and emits the string value from an input element.
+ *
+ * This utility simplifies handling input events by automatically extracting the value
+ * from the target element and passing it to your callback function.
+ *
+ * @example
+ * ```typescript
+ * const name = prop('')
+ *
+ * html.input(
+ *   attr.value(name),
+ *   on.input(emitValue(value => name.value = value))
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With textarea
+ * const description = prop('')
+ *
+ * html.textarea(
+ *   attr.value(description),
+ *   on.input(emitValue(value => {
+ *     description.value = value
+ *     console.log('Description updated:', value)
+ *   }))
+ * )
+ * ```
  *
- * @param fn - The callback function that will receive the emitted value.
- * @returns An event handler function that can be attached to an event listener.
+ * @param fn - Callback function that receives the input element's string value
+ * @returns Event handler function that can be used with event listeners
  * @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.
+ * Creates an event handler that extracts and emits the numeric value from an input element.
  *
- * @param fn - The function to be called with the value as a number.
- * @returns A function that can be used as an event handler.
+ * This utility automatically converts the input's value to a number using the browser's
+ * built-in `valueAsNumber` property, which handles number inputs correctly and returns
+ * `NaN` for invalid numeric values.
+ *
+ * @example
+ * ```typescript
+ * const age = prop(0)
+ *
+ * html.input(
+ *   attr.type('number'),
+ *   attr.value(age.map(String)),
+ *   on.input(emitValueAsNumber(value => {
+ *     if (!isNaN(value)) {
+ *       age.value = value
+ *     }
+ *   }))
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With range input
+ * const volume = prop(50)
+ *
+ * html.input(
+ *   attr.type('range'),
+ *   attr.min('0'),
+ *   attr.max('100'),
+ *   attr.value(volume.map(String)),
+ *   on.input(emitValueAsNumber(value => volume.value = value))
+ * )
+ * ```
+ *
+ * @param fn - Callback function that receives the input element's numeric value (may be NaN)
+ * @returns Event handler function that can be used with event listeners
  * @public
  */
 export declare const emitValueAsNumber: (fn: (num: number) => void) => (event: Event) => void;
@@ -144,9 +256,55 @@ export declare const emitValueAsDateTime: (fn: (date: Date) => void) => (event:
  */
 export declare const emitValueAsNullableDateTime: (fn: (date: Date | null) => 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.
+ * Creates an event handler that extracts and emits the checked state from a checkbox or radio input.
+ *
+ * This utility simplifies handling checkbox and radio button state changes by automatically
+ * extracting the `checked` property from the target element.
+ *
+ * @example
+ * ```typescript
+ * const isEnabled = prop(false)
+ *
+ * html.input(
+ *   attr.type('checkbox'),
+ *   attr.checked(isEnabled),
+ *   on.change(emitChecked(checked => isEnabled.value = checked))
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With radio buttons
+ * const selectedOption = prop('')
+ *
+ * html.div(
+ *   html.label(
+ *     html.input(
+ *       attr.type('radio'),
+ *       attr.name('option'),
+ *       attr.value('A'),
+ *       on.change(emitChecked(checked => {
+ *         if (checked) selectedOption.value = 'A'
+ *       }))
+ *     ),
+ *     'Option A'
+ *   ),
+ *   html.label(
+ *     html.input(
+ *       attr.type('radio'),
+ *       attr.name('option'),
+ *       attr.value('B'),
+ *       on.change(emitChecked(checked => {
+ *         if (checked) selectedOption.value = 'B'
+ *       }))
+ *     ),
+ *     'Option B'
+ *   )
+ * )
+ * ```
+ *
+ * @param fn - Callback function that receives the input element's checked state
+ * @returns Event handler function that can be used with event listeners
  * @public
  */
 export declare const emitChecked: (fn: (checked: boolean) => void) => (event: Event) => void;

package/renderable/provider.d.ts

@@ -40,26 +40,196 @@ export type ProviderOptions = {
  * @returns A Clear function that can be used to clean up any resources associated with the execution.
  * @public
  */
-export declare const WithProvider: (fn: (ctx: ProviderOptions) => TNode | void) => Renderable;
+export declare const WithProvider: (fn: (opts: ProviderOptions) => TNode | void) => Renderable;
 /**
- * Returns a renderable function that sets a provider for the given provider mark and returns a child renderable.
+ * Makes a provider available to all child components in the component tree.
  *
- * @param provider - The provider to set.
- * @param options - The options to pass to the provider.
- * @param child - The child renderable to return.
+ * This function creates a provider context that child components can access using `Use`.
+ * The provider is automatically disposed when the component is unmounted.
+ *
+ * @example
+ * ```typescript
+ * // Create a theme provider
+ * const ThemeProvider: Provider<Signal<string>> = {
+ *   mark: makeProviderMark<Signal<string>>('Theme'),
+ *   create: () => {
+ *     const theme = prop('light')
+ *     return {
+ *       value: theme,
+ *       dispose: () => theme.dispose()
+ *     }
+ *   }
+ * }
+ *
+ * // Provide the theme to child components
+ * const App = () =>
+ *   Provide(
+ *     ThemeProvider,
+ *     {}, // options
+ *     () => html.div(
+ *       html.h1('My App'),
+ *       ThemeToggle(), // Can access the theme
+ *       MainContent()  // Can also access the theme
+ *     )
+ *   )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Provider with options
+ * const ConfigProvider: Provider<Config, { apiUrl: string }> = {
+ *   mark: makeProviderMark<Config>('Config'),
+ *   create: (options) => {
+ *     const config = new Config(options.apiUrl)
+ *     return {
+ *       value: config,
+ *       dispose: () => config.cleanup()
+ *     }
+ *   }
+ * }
+ *
+ * // Provide with specific options
+ * Provide(
+ *   ConfigProvider,
+ *   { apiUrl: 'https://api.example.com' },
+ *   () => AppContent()
+ * )
+ * ```
+ *
+ * @template T - The type of value provided by the provider
+ * @template O - The type of options passed to the provider
+ * @param provider - The provider definition containing mark and create function
+ * @param options - Options to pass to the provider's create function
+ * @param child - Function that returns the child components that can access the provider
+ * @returns A renderable that provides the value to its children
+ * @public
  */
 export declare const Provide: <T, O>(provider: Provider<T, O>, options: O, child: () => TNode) => Renderable;
 /**
- * Returns a renderable function that uses a provider for the given provider mark and returns a child renderable.
+ * Consumes a provider value and makes it available to a child component.
+ *
+ * This function looks up a provider in the component tree and passes its value
+ * to the child function. The provider must have been made available by a parent
+ * component using `Provide`.
+ *
+ * @example
+ * ```typescript
+ * // Use a theme provider
+ * const ThemeToggle = () =>
+ *   Use(
+ *     ThemeProvider,
+ *     (theme) => html.button(
+ *       on.click(() => {
+ *         theme.value = theme.value === 'light' ? 'dark' : 'light'
+ *       }),
+ *       'Current theme: ', theme
+ *     )
+ *   )
+ * ```
  *
- * @param provider - The provider mark to use the provider for.
- * @param child - The child renderable to return.
+ * @example
+ * ```typescript
+ * // Use multiple properties from a provider
+ * const UserProfile = () =>
+ *   Use(
+ *     UserProvider,
+ *     (user) => html.div(
+ *       html.h2('Welcome, ', user.map(u => u.name)),
+ *       html.p('Email: ', user.map(u => u.email)),
+ *       html.p('Role: ', user.map(u => u.role))
+ *     )
+ *   )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use provider in conditional rendering
+ * const ConditionalContent = () =>
+ *   Use(
+ *     AuthProvider,
+ *     (auth) => auth.map(a => a.isLoggedIn)
+ *       ? html.div('Welcome back!')
+ *       : html.div('Please log in')
+ *   )
+ * ```
+ *
+ * @template T - The type of value provided by the provider
+ * @param provider - The provider to consume (must be available in parent components)
+ * @param child - Function that receives the provider value and returns content to render
+ * @returns A renderable that consumes the provider and renders the child content
+ * @throws {ProviderNotFoundError} When the provider is not found in the component tree
+ * @public
  */
 export declare const Use: <T>(provider: Provider<T>, child: (provider: T) => TNode) => Renderable;
 /**
- * Returns a renderable function that uses a provider for the given provider marks and returns a child renderable.
+ * Consumes multiple providers and makes their values available to a child component.
+ *
+ * This function is a convenience wrapper for consuming multiple providers at once.
+ * It's equivalent to nesting multiple `Use` calls but provides a cleaner API when
+ * you need access to several providers simultaneously.
  *
- * @param providers - The provider marks to use the providers for.
- * @param child - The child renderable to return.
+ * @example
+ * ```typescript
+ * // Use multiple providers together
+ * const Dashboard = () =>
+ *   UseMany(
+ *     UserProvider,
+ *     ThemeProvider,
+ *     ConfigProvider
+ *   )(
+ *     (user, theme, config) => html.div(
+ *       attr.class(theme.map(t => `theme-${t}`)),
+ *       html.h1('Dashboard for ', user.map(u => u.name)),
+ *       html.p('API URL: ', config.map(c => c.apiUrl)),
+ *       html.p('Current theme: ', theme)
+ *     )
+ *   )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Equivalent to nested Use calls
+ * const Dashboard = () =>
+ *   Use(UserProvider, user =>
+ *     Use(ThemeProvider, theme =>
+ *       Use(ConfigProvider, config =>
+ *         html.div(
+ *           // Same content as above
+ *         )
+ *       )
+ *     )
+ *   )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Type-safe access to multiple providers
+ * const SettingsPanel = () =>
+ *   UseMany(
+ *     PreferencesProvider,
+ *     UserProvider
+ *   )(
+ *     (preferences, user) => html.div(
+ *       html.h2('Settings for ', user.map(u => u.name)),
+ *       html.label(
+ *         'Theme: ',
+ *         html.select(
+ *           attr.value(preferences.map(p => p.theme)),
+ *           on.change(emitValue(value => {
+ *             preferences.update(p => ({ ...p, theme: value }))
+ *           })),
+ *           html.option(attr.value('light'), 'Light'),
+ *           html.option(attr.value('dark'), 'Dark')
+ *         )
+ *       )
+ *     )
+ *   )
+ * ```
+ *
+ * @template T - Tuple type representing the types of all providers
+ * @param providers - Variable number of providers to consume
+ * @returns Function that takes a child function and returns a renderable
+ * @throws {ProviderNotFoundError} When any of the providers is not found in the component tree
+ * @public
  */
 export declare const UseMany: <T extends Provider<unknown>[]>(...providers: T) => (child: (...values: ToProviderTypes<T>) => TNode) => Renderable;

package/renderable/repeat.d.ts

@@ -2,12 +2,70 @@ import { ElementPosition } from '../std/element-position';
 import { Value } from '../std/value';
 import { TNode, Renderable } from '../types/domain';
 /**
- * Creates a renderable function that repeats a given element a specified number of times.
+ * Renders content a specified number of times, with each iteration receiving position information.
  *
- * @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.
+ * This function is useful for generating repeated UI elements based on a count rather than an array.
+ * Each iteration receives an `ElementPosition` object that provides the current index and position
+ * information relative to the total count.
+ *
+ * @example
+ * ```typescript
+ * // Create a simple numbered list
+ * const count = prop(5)
+ *
+ * Repeat(count,
+ *   (position) => html.div(
+ *     `Item ${position.index + 1} of ${position.total.value}`,
+ *     position.isFirst ? ' (first)' : '',
+ *     position.isLast ? ' (last)' : ''
+ *   )
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create a star rating component
+ * const rating = prop(3)
+ * const maxStars = 5
+ *
+ * Repeat(maxStars,
+ *   (position) => html.span(
+ *     attr.class(position.index < rating.value ? 'star-filled' : 'star-empty'),
+ *     '★'
+ *   )
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With separators between items
+ * Repeat(3,
+ *   (position) => html.span(`Item ${position.index}`),
+ *   () => html.span(' | ') // Separator
+ * )
+ * // Renders: Item 0 | Item 1 | Item 2
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Dynamic count that updates the UI
+ * const itemCount = prop(2)
+ *
+ * html.div(
+ *   html.button(
+ *     on.click(() => itemCount.value++),
+ *     'Add Item'
+ *   ),
+ *   Repeat(itemCount,
+ *     (position) => html.div(`Dynamic item ${position.index + 1}`)
+ *   )
+ * )
+ * ```
+ *
+ * @param times - A signal or number representing how many times to repeat the content
+ * @param element - Function that returns content for each iteration, receives position information
+ * @param separator - Optional function that returns content to place between iterations
+ * @returns A renderable that displays the repeated content
  * @public
  */
 export declare const Repeat: (times: Value<number>, element: (index: ElementPosition) => TNode, separator?: (pos: ElementPosition) => TNode) => Renderable;