@tempots/ui 3.0.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/ui",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",

package/renderables/appearance.d.ts

@@ -18,3 +18,14 @@ export type AppearanceType = 'light' | 'dark';
  * @public
  */
 export declare const Appearance: Provider<Signal<AppearanceType>>;
+/**
+ * Creates a signal that represents the current appearance (light or dark) based on the user's system
+ * preferences.
+ *
+ * The appearance is updated whenever the user's system preferences change, and the signal is cleaned
+ * up when it is no longer needed.
+ *
+ * @returns A signal representing the current appearance.
+ * @public
+ */
+export declare function useAppearance(): Signal<AppearanceType>;

package/renderables/autofocus.d.ts

@@ -1,9 +1,63 @@
 import { Renderable } from '@tempots/dom';
 /**
- * Creates a renderable function that focuses on the element after a specified delay.
+ * Automatically focuses an element when it's rendered to the DOM.
  *
- * @param delay - The delay in milliseconds before focusing on the element. Default is 10 milliseconds.
- * @returns A renderable function that focuses on the element.
+ * This utility is commonly used for form inputs, modals, or any interactive element
+ * that should receive focus immediately when it appears. The small default delay
+ * ensures the element is fully rendered before attempting to focus.
+ *
+ * @example
+ * ```typescript
+ * // Auto-focus a text input
+ * html.input(
+ *   AutoFocus(),
+ *   attr.placeholder('Enter your name'),
+ *   attr.type('text')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Auto-focus with custom delay
+ * html.textarea(
+ *   AutoFocus(100), // Wait 100ms before focusing
+ *   attr.placeholder('Enter your message')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in a modal dialog
+ * const showModal = prop(false)
+ *
+ * When(showModal,
+ *   () => html.div(
+ *     attr.class('modal'),
+ *     html.input(
+ *       AutoFocus(), // Focus when modal opens
+ *       attr.placeholder('Search...')
+ *     ),
+ *     html.button(
+ *       on.click(() => showModal.value = false),
+ *       'Close'
+ *     )
+ *   )
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Combine with other input enhancements
+ * html.input(
+ *   AutoFocus(),
+ *   AutoSelect(), // Also select the text
+ *   attr.value(searchTerm),
+ *   on.input(emitValue(value => searchTerm.value = value))
+ * )
+ * ```
+ *
+ * @param delay - Delay in milliseconds before focusing (default: 10ms)
+ * @returns A renderable that focuses the element when rendered
  * @public
  */
 export declare const AutoFocus: (delay?: number) => Renderable;

package/renderables/autoselect.d.ts

@@ -1,8 +1,68 @@
 import { Renderable } from '@tempots/dom';
 /**
- * Creates a renderable function that automatically selects the content of an input element after a specified delay.
- * @param delay - The delay in milliseconds before selecting the content. Default is 10 milliseconds.
- * @returns A renderable function that can be used with a DOMContext.
+ * Automatically selects all text content in an input element when it's rendered.
+ *
+ * This utility is particularly useful for input fields where you want the user to be able
+ * to immediately start typing to replace the existing content, or easily copy the current value.
+ * The small default delay ensures the element is fully rendered before attempting to select.
+ *
+ * @example
+ * ```typescript
+ * // Auto-select text in an input
+ * const username = prop('john_doe')
+ *
+ * html.input(
+ *   AutoSelect(),
+ *   attr.value(username),
+ *   attr.type('text')
+ * )
+ * // When rendered, 'john_doe' will be automatically selected
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Combine with AutoFocus for complete UX
+ * html.input(
+ *   AutoFocus(),   // Focus the input
+ *   AutoSelect(),  // Select all text
+ *   attr.value(editableValue),
+ *   attr.placeholder('Enter value')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in an edit dialog
+ * const editMode = prop(false)
+ * const itemName = prop('Default Name')
+ *
+ * When(editMode,
+ *   () => html.div(
+ *     html.label('Edit name:'),
+ *     html.input(
+ *       AutoFocus(),
+ *       AutoSelect(), // Select existing name for easy editing
+ *       attr.value(itemName),
+ *       on.keydown(e => {
+ *         if (e.key === 'Enter') editMode.value = false
+ *         if (e.key === 'Escape') editMode.value = false
+ *       })
+ *     )
+ *   )
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom delay for specific timing needs
+ * html.input(
+ *   AutoSelect(50), // Wait 50ms before selecting
+ *   attr.value(sensitiveData)
+ * )
+ * ```
+ *
+ * @param delay - Delay in milliseconds before selecting text (default: 10ms)
+ * @returns A renderable that selects all text in the input element when rendered
  * @public
  */
 export declare const AutoSelect: (delay?: number) => Renderable;

package/renderables/hidden-when-empty.d.ts

@@ -2,7 +2,6 @@ import { Renderable } from '@tempots/dom';
 /**
  * Hides the element when it is empty and restores its initial state when necessary.
  *
- * @param ctx - The DOM context.
  * @returns A function that can be used to restore the initial state of the element.
  * @public
  */

package/renderables/inviewport.d.ts

@@ -13,22 +13,128 @@ export type InViewportOptions = {
     once?: boolean;
 };
 /**
- * Creates a renderable component that tracks whether the element is in the viewport.
+ * Creates a component that tracks whether an element is visible in the viewport.
  *
- * @param options - The options for the `InViewport` component.
- * @param fn - A function that returns the renderable component based on the visibility signal.
- * @returns The renderable component that tracks the element's visibility in the viewport.
+ * This component uses the Intersection Observer API to efficiently detect when an element
+ * enters or exits the viewport. It's perfect for implementing lazy loading, infinite scrolling,
+ * animations on scroll, and other viewport-based interactions.
+ *
+ * @example
+ * ```typescript
+ * // Basic viewport detection
+ * InViewport(
+ *   { mode: 'partial' },
+ *   (isVisible) => html.div(
+ *     attr.class(isVisible.map(v => v ? 'visible' : 'hidden')),
+ *     'This element changes class when visible'
+ *   )
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Lazy load images
+ * const imageUrl = 'https://example.com/large-image.jpg'
+ *
+ * InViewport(
+ *   { mode: 'partial', once: true },
+ *   (isVisible) => isVisible.value
+ *     ? html.img(attr.src(imageUrl), attr.alt('Lazy loaded image'))
+ *     : html.div(attr.class('placeholder'), 'Loading...')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Infinite scrolling trigger
+ * const loadMore = () => {
+ *   // Load more data
+ *   console.log('Loading more items...')
+ * }
+ *
+ * html.div(
+ *   ForEach(items, item => ItemComponent(item)),
+ *   InViewport(
+ *     { mode: 'partial' },
+ *     (isVisible) => {
+ *       // Trigger load more when sentinel comes into view
+ *       isVisible.on(visible => {
+ *         if (visible) loadMore()
+ *       })
+ *       return html.div(attr.class('loading-sentinel'), 'Loading more...')
+ *     }
+ *   )
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Animation on scroll
+ * InViewport(
+ *   { mode: 'full' }, // Only trigger when fully visible
+ *   (isVisible) => html.div(
+ *     attr.class(isVisible.map(v =>
+ *       v ? 'animate-fade-in' : 'opacity-0'
+ *     )),
+ *     'This animates when fully in view'
+ *   )
+ * )
+ * ```
+ *
+ * @param options - Configuration options for viewport detection
+ * @param options.mode - 'partial' (any part visible) or 'full' (completely visible)
+ * @param options.once - If true, stops observing after first intersection
+ * @param fn - Function that receives the visibility signal and returns content to render
+ * @returns A renderable component that tracks viewport visibility
  * @public
  */
 export declare const InViewport: ({ mode, once }: InViewportOptions, fn: (value: Signal<boolean>) => TNode) => Renderable;
 /**
- * Executes the provided `then` function when the element is in the viewport.
- * Optionally, executes the `otherwise` function when the element is not in the viewport.
+ * Conditionally renders content based on whether an element is in the viewport.
+ *
+ * This is a convenience wrapper around `InViewport` that provides a simpler API
+ * for cases where you just want to show/hide content based on viewport visibility.
+ * It's perfect for simple lazy loading or reveal animations.
+ *
+ * @example
+ * ```typescript
+ * // Simple lazy loading
+ * WhenInViewport(
+ *   { mode: 'partial', once: true },
+ *   () => html.img(
+ *     attr.src('https://example.com/image.jpg'),
+ *     attr.alt('Lazy loaded image')
+ *   ),
+ *   () => html.div(attr.class('skeleton'), 'Loading...')
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reveal animation
+ * WhenInViewport(
+ *   { mode: 'full' },
+ *   () => html.div(
+ *     attr.class('animate-slide-up'),
+ *     'This content slides up when visible'
+ *   )
+ * )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Load expensive component only when needed
+ * WhenInViewport(
+ *   { mode: 'partial', once: true },
+ *   () => ExpensiveChart({ data: chartData }),
+ *   () => html.div('Chart will load when visible')
+ * )
+ * ```
  *
- * @param options - The options for the `InViewport` component.
- * @param then - The function to execute when the element is in the viewport.
- * @param otherwise - The function to execute when the element is not in the viewport.
- * @returns The result of executing the `then` function or the `otherwise` function.
+ * @param options - Configuration options for viewport detection
+ * @param then - Function that returns content to render when element is in viewport
+ * @param otherwise - Optional function that returns content when element is not in viewport
+ * @returns A renderable component that conditionally shows content based on viewport visibility
  * @public
  */
 export declare const WhenInViewport: (options: InViewportOptions, then: () => TNode, otherwise?: () => TNode) => Renderable;

package/renderables/resource.d.ts

@@ -28,16 +28,123 @@ export interface ResourceDisplayOptions<V, E> {
  */
 export declare const ResourceDisplay: <V, E>(resource: AsyncResource<V, E>, options: ResourceDisplayOptions<V, E>) => Renderable<import('@tempots/dom').DOMContext>;
 /**
- * Creates and displays an asynchronous resource.
+ * Creates a reactive resource component for handling asynchronous data loading.
  *
- * @template R - The type of the request.
- * @template V - The type of the value when the resource is successfully loaded.
- * @template E - The type of the error when the resource fails to load.
+ * This component provides a declarative way to handle async operations with proper
+ * loading, success, and error states. It automatically manages the lifecycle of
+ * async requests and provides reload functionality.
+ *
+ * @example
+ * ```typescript
+ * // Basic API data loading
+ * const userId = prop(1)
+ *
+ * const UserProfile = Resource({
+ *   request: userId,
+ *   load: async ({ request }) => {
+ *     const response = await fetch(`/api/users/${request}`)
+ *     if (!response.ok) throw new Error('Failed to load user')
+ *     return response.json()
+ *   }
+ * })({
+ *   loading: () => html.div('Loading user...'),
+ *   failure: (error, reload) => html.div(
+ *     'Error: ', error,
+ *     html.button(on.click(reload), 'Retry')
+ *   ),
+ *   success: (user) => html.div(
+ *     html.h2(user.map(u => u.name)),
+ *     html.p(user.map(u => u.email))
+ *   )
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Resource with dependencies
+ * const searchQuery = prop('')
+ * const filters = prop({ category: 'all', sort: 'name' })
+ *
+ * const SearchResults = Resource({
+ *   request: computed(() => ({
+ *     query: searchQuery.value,
+ *     ...filters.value
+ *   })),
+ *   load: async ({ request, abortSignal }) => {
+ *     const params = new URLSearchParams(request)
+ *     const response = await fetch(`/api/search?${params}`, {
+ *       signal: abortSignal
+ *     })
+ *     return response.json()
+ *   },
+ *   mapError: (error) => error instanceof Error ? error.message : 'Unknown error'
+ * })({
+ *   loading: (previous) => html.div(
+ *     'Searching...',
+ *     previous.value && html.div('Previous results:', previous.value.length)
+ *   ),
+ *   failure: (error, reload) => html.div(
+ *     attr.class('error'),
+ *     'Search failed: ', error,
+ *     html.button(on.click(reload), 'Try again')
+ *   ),
+ *   success: (results, reload) => html.div(
+ *     html.button(on.click(reload), 'Refresh'),
+ *     ForEach(results, result => SearchResultItem(result))
+ *   )
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // File upload resource
+ * const selectedFile = prop<File | null>(null)
+ *
+ * const FileUpload = Resource({
+ *   request: selectedFile,
+ *   load: async ({ request }) => {
+ *     if (!request) throw new Error('No file selected')
+ *
+ *     const formData = new FormData()
+ *     formData.append('file', request)
+ *
+ *     const response = await fetch('/api/upload', {
+ *       method: 'POST',
+ *       body: formData
+ *     })
+ *
+ *     if (!response.ok) throw new Error('Upload failed')
+ *     return response.json()
+ *   }
+ * })({
+ *   loading: () => html.div(
+ *     attr.class('upload-progress'),
+ *     'Uploading file...'
+ *   ),
+ *   failure: (error, reload) => html.div(
+ *     attr.class('upload-error'),
+ *     'Upload failed: ', error,
+ *     html.button(on.click(reload), 'Retry upload')
+ *   ),
+ *   success: (result) => html.div(
+ *     attr.class('upload-success'),
+ *     'File uploaded successfully!',
+ *     html.a(
+ *       attr.href(result.map(r => r.url)),
+ *       'View file'
+ *     )
+ *   )
+ * })
+ * ```
  *
- * @param request - The request to load the resource.
- * @param load - The function to load the resource.
- * @param convertError - The function to convert an unknown error into a specific error type.
- * @returns A function that takes display options and returns a node representing the current state of the resource.
+ * @template R - The type of the request parameter
+ * @template V - The type of the successful result value
+ * @template E - The type of the error (defaults to unknown)
+ * @param config - Configuration object for the resource
+ * @param config.request - Signal or value representing the request parameters
+ * @param config.load - Async function that loads the resource
+ * @param config.mapError - Optional function to transform errors into a specific type
+ * @returns Function that takes display options and returns a renderable component
  * @public
  */
 export declare const Resource: <R, V, E = unknown>({ request, load, mapError, }: {

package/renderables/router/location.d.ts

@@ -1,9 +1,77 @@
 import { Prop, Provider } from '@tempots/dom';
 import { LocationData } from './location-data';
 /**
- * Provider for the location context.
- * @param child - The child component to be wrapped with the location context.
- * @returns The wrapped component with the location context.
+ * Provider for browser location and navigation functionality.
+ *
+ * The Location provider gives components access to the current URL and provides
+ * methods for programmatic navigation. It automatically detects whether it's
+ * running in a browser or headless environment and provides the appropriate
+ * implementation.
+ *
+ * @example
+ * ```typescript
+ * // Use location in a component
+ * const CurrentPath = () =>
+ *   Use(Location, location => html.div(
+ *     'Current path: ', location.$.pathname,
+ *     html.br(),
+ *     'Search params: ', location.$.search,
+ *     html.br(),
+ *     'Hash: ', location.$.hash
+ *   ))
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Navigation buttons
+ * const Navigation = () =>
+ *   Use(Location, location => html.nav(
+ *     html.button(
+ *       on.click(() => location.navigate('/')),
+ *       'Home'
+ *     ),
+ *     html.button(
+ *       on.click(() => location.navigate('/about')),
+ *       'About'
+ *     ),
+ *     html.button(
+ *       on.click(() => location.back()),
+ *       'Back'
+ *     ),
+ *     html.button(
+ *       on.click(() => location.forward()),
+ *       'Forward'
+ *     )
+ *   ))
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Conditional rendering based on path
+ * const ConditionalContent = () =>
+ *   Use(Location, location =>
+ *     When(location.map(loc => loc.pathname.startsWith('/admin')),
+ *       () => AdminPanel(),
+ *       () => PublicContent()
+ *     )
+ *   )
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // URL parameter extraction
+ * const ProductPage = () =>
+ *   Use(Location, location => {
+ *     const searchParams = location.map(loc => new URLSearchParams(loc.search))
+ *     const productId = searchParams.map(params => params.get('id'))
+ *
+ *     return Ensure(productId,
+ *       (id) => ProductDetail({ id }),
+ *       () => html.div('Product ID required')
+ *     )
+ *   })
+ * ```
+ *
  * @public
  */
 export declare const Location: Provider<Prop<LocationData>>;

package/renderables/router/router.d.ts

@@ -1,11 +1,100 @@
 import { TNode, Renderable, Signal } from '@tempots/dom';
 import { ExtractParams, MakeParams, RouteInfo } from './route-info';
 /**
- * Creates a router that maps routes to corresponding renderable components.
+ * Creates a client-side router that maps URL patterns to renderable components.
  *
- * @typeParam T - The type of the routes object.
- * @param routes - An object containing route handlers.
- * @returns - The router renderable.
+ * The Router component provides declarative routing for single-page applications.
+ * It automatically extracts route parameters from URLs and passes them to the
+ * corresponding route handlers. The router integrates with the browser's history
+ * API and updates the UI when the URL changes.
+ *
+ * @example
+ * ```typescript
+ * // Basic routing setup
+ * const AppRouter = Router({
+ *   '/': () => html.div('Home Page'),
+ *   '/about': () => html.div('About Page'),
+ *   '/contact': () => html.div('Contact Page'),
+ *   '*': () => html.div('404 - Page Not Found')
+ * })
+ *
+ * render(AppRouter, document.body)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Routes with parameters
+ * const BlogRouter = Router({
+ *   '/': () => html.div('Blog Home'),
+ *   '/posts/:id': (info) => {
+ *     const postId = info.$.params.$.id
+ *     return html.div(
+ *       html.h1('Post ID: ', postId),
+ *       html.p('Loading post...')
+ *     )
+ *   },
+ *   '/users/:userId/posts/:postId': (info) => {
+ *     const userId = info.$.params.$.userId
+ *     const postId = info.$.params.$.postId
+ *     return html.div(
+ *       html.h1('User ', userId, ' - Post ', postId),
+ *       UserPost({ userId, postId })
+ *     )
+ *   },
+ *   '*': () => html.div('Page not found')
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using route info for navigation and data
+ * const ProductRouter = Router({
+ *   '/products': () => ProductList(),
+ *   '/products/:id': (info) => {
+ *     const productId = info.$.params.$.id
+ *     const searchParams = info.$.search
+ *
+ *     return html.div(
+ *       html.h1('Product ', productId),
+ *       html.p('Search params: ', searchParams),
+ *       ProductDetail({
+ *         id: productId,
+ *         variant: new URLSearchParams(searchParams.value).get('variant')
+ *       })
+ *     )
+ *   },
+ *   '/products/:id/reviews': (info) => {
+ *     const productId = info.$.params.$.id
+ *     return ProductReviews({ productId })
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Programmatic navigation
+ * import { Location } from '@tempots/ui'
+ *
+ * const Navigation = () => html.nav(
+ *   html.button(
+ *     on.click(() => Location.navigate('/')),
+ *     'Home'
+ *   ),
+ *   html.button(
+ *     on.click(() => Location.navigate('/about')),
+ *     'About'
+ *   ),
+ *   html.button(
+ *     on.click(() => Location.navigate('/products/123')),
+ *     'Product 123'
+ *   )
+ * )
+ * ```
+ *
+ * @template T - The type of the routes configuration object
+ * @param routes - Object mapping route patterns to handler functions
+ * @returns A renderable router component that handles URL routing
+ * @throws {Error} When no matching route is found for the current URL
  * @public
  */
 export declare const Router: <T extends { [K in keyof T]: (info: K extends string ? Signal<RouteInfo<MakeParams<ExtractParams<K>>, K>> : never) => TNode; }>(routes: T) => Renderable;