@tempots/ui 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/ui",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",
@@ -40,7 +40,7 @@
     "@floating-ui/dom": "^1.6.7"
   },
   "peerDependencies": {
-    "@tempots/dom": "18.0.0",
+    "@tempots/dom": "19.1.0",
     "@tempots/std": "0.10.7"
   }
 }

package/renderables/anchor.d.ts

@@ -1,3 +1,12 @@
 import { TNode, Value } from '@tempots/dom';
 
-export declare function Anchor(href: Value<string>, ...children: TNode[]): import('@tempots/dom').Renderable;
+/**
+ * Creates an anchor element with the specified href and children.
+ * When the anchor element is clicked, the location is updated to the specified href.
+ *
+ * @param href - The href attribute of the anchor element.
+ * @param children - The child elements of the anchor element.
+ * @returns The anchor element.
+ * @public
+ */
+export declare const Anchor: (href: Value<string>, ...children: TNode[]) => import('@tempots/dom').Renderable;

package/renderables/appearance.d.ts

@@ -2,11 +2,13 @@ import { Signal, TNode } from '@tempots/dom';
 
 /**
  * Defines the possible appearance types for the application.
- * @type AppearanceType
+ *
+ * @public
  */
 export type AppearanceType = 'light' | 'dark';
 /**
  * A provider mark for a signal representing the current appearance type.
+ * @public
  */
 export declare const appearanceMarker: import('@tempots/dom').ProviderMark<Signal<AppearanceType>>;
 /**
@@ -19,6 +21,7 @@ export declare const appearanceMarker: import('@tempots/dom').ProviderMark<Signa
  *
  * @param child - The child component to be provided with the appearance context.
  * @returns The child component with the appearance context.
+ * @public
  */
 export declare const ProvideAppearance: (child: TNode) => TNode;
 /**
@@ -27,5 +30,6 @@ export declare const ProvideAppearance: (child: TNode) => TNode;
  *
  * @param fn - A function that accepts the `AppearanceType` signal and returns a `TNode` element.
  * @returns The `TNode` element returned by the provided function.
+ * @public
  */
 export declare const UseAppearance: (fn: (appearance: Signal<AppearanceType>) => TNode) => TNode;

package/renderables/async-result-view.d.ts

@@ -1,9 +1,50 @@
-import { TNode, Signal, Value } from '@tempots/dom';
+import { TNode, Signal, Value, Renderable } from '@tempots/dom';
 import { AsyncResult } from '@tempots/std';
 
-export declare function AsyncResultView<T, E>(result: Value<AsyncResult<T, E>>, options: {
+/**
+ * Represents the options for rendering an asynchronous result view.
+ *
+ * @typeParam T - The type of the success value.
+ * @typeParam E - The type of the error value.
+ * @public
+ */
+export type AsyncResultViewOptions<T, E> = {
+    /**
+     * The function to render the view when the operation succeeds.
+     * @param value - The value of the success result.
+     * @returns The rendered view.
+     * @public
+     */
     success: (value: Signal<T>) => TNode;
+    /**
+     * The function to render the view when the operation fails.
+     * @param error - The error of the failure result.
+     * @returns The rendered view.
+     * @public
+     */
     failure?: (error: Signal<E>) => TNode;
+    /**
+     * The function to render the view when the operation is not requested yet.
+     * @returns The rendered view.
+     * @public
+     */
     notAsked?: () => TNode;
+    /**
+     * The function to render the view when the operation is in progress.
+     * @param previousValue - The previous value.
+     * @returns The rendered view.
+     * @public
+     */
     loading?: (previousValue: Signal<T | undefined>) => TNode;
-} | ((value: Signal<T>) => TNode)): import('@tempots/dom').Renderable;
+};
+/**
+ * Renders the view based on the result of an asynchronous operation.
+ *
+ * @typeParam T - The type of the success value.
+ * @typeParam E - The type of the error value.
+ * @param result - The result of the asynchronous operation.
+ * @param options - The options object or a function that returns a TNode.
+ * @returns The rendered view.
+ * @public
+ */
+export declare const AsyncResultView: <T, E>(result: Value<AsyncResult<T, E>>, options: AsyncResultViewOptions<T, E> | ((value: Signal<T>) => TNode)) => Renderable;

package/renderables/autofocus.d.ts

@@ -1,3 +1,10 @@
 import { Renderable } from '@tempots/dom';
 
+/**
+ * Creates a renderable function that focuses on the element after a specified delay.
+ *
+ * @param delay - The delay in milliseconds before focusing on the element. Default is 10 milliseconds.
+ * @returns A renderable function that focuses on the element.
+ * @public
+ */
 export declare const AutoFocus: (delay?: number) => Renderable;

package/renderables/autoselect.d.ts

@@ -1,3 +1,9 @@
 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.
+ * @public
+ */
 export declare const AutoSelect: (delay?: number) => Renderable;

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

@@ -1,3 +1,10 @@
 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
+ */
 export declare const HiddenWhenEmpty: Renderable;

package/renderables/html-title.d.ts

@@ -1,3 +1,10 @@
 import { Value } from '@tempots/dom';
 
-export declare const HTMLTitle: (title: Value<string>) => (ctx: import('@tempots/dom').DOMContext) => () => void;
+/**
+ * Creates an HTML title element with the specified title.
+ *
+ * @param title - The title to be set for the HTML title element.
+ * @returns The created HTML title element.
+ * @public
+ */
+export declare const HTMLTitle: (title: Value<string>) => import('@tempots/dom').Renderable;

package/renderables/inviewport.d.ts

@@ -1,5 +1,31 @@
 import { Signal, TNode, Renderable } from '@tempots/dom';
 
+/**
+ * Represents the mode for determining if an element is in the viewport.
+ *
+ * - `partial`: Indicates that the element is considered in the viewport if any part of it is visible.
+ * - `full`: Indicates that the element is considered in the viewport only if it is fully visible.
+ *
+ * @public
+ */
 export type InViewportMode = 'partial' | 'full';
-export declare function InViewport(mode: InViewportMode, fn: (value: Signal<boolean>) => TNode): Renderable;
+/**
+ * Creates a renderable component that tracks whether the element is in the viewport.
+ *
+ * @param mode - The mode for tracking the element's visibility in the viewport.
+ * @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.
+ * @public
+ */
+export declare const InViewport: (mode: InViewportMode, 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.
+ *
+ * @param mode - The mode to determine when the element is considered in the viewport.
+ * @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.
+ * @public
+ */
 export declare const WhenInViewport: (mode: InViewportMode, then: TNode, otherwise?: TNode) => Renderable;

package/renderables/pop-over.d.ts

@@ -1,13 +1,51 @@
 import { TNode, DOMContext, Value } from '@tempots/dom';
 
+/**
+ * Represents the placement options for a pop-over.
+ *
+ * @public
+ */
 export type Placement = 'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end';
-export interface PopOverProps {
-    open: Value<boolean>;
-    content: () => TNode;
-    placement?: Placement;
-    offset?: {
-        mainAxis?: number;
-        crossAxis?: number;
+/**
+ * Represents the properties for a PopOver component.
+ *
+ * @public
+ */
+export type PopOverOptions = {
+    /**
+     * Specifies whether the PopOver is open or closed.
+     */
+    readonly open: Value<boolean>;
+    /**
+     * Specifies the content of the PopOver.
+     * This should be a function that returns a TNode.
+     */
+    readonly content: () => TNode;
+    /**
+     * Specifies the placement of the PopOver.
+     * This is an optional property.
+     */
+    readonly placement?: Placement;
+    /**
+     * Specifies the offset of the PopOver.
+     * This is an optional property.
+     */
+    readonly offset?: {
+        /**
+         * Specifies the offset on the main axis.
+         */
+        readonly mainAxis?: number;
+        /**
+         * Specifies the offset on the cross axis.
+         */
+        readonly crossAxis?: number;
     };
-}
-export declare function PopOver({ content, open, placement, offset: { mainAxis, crossAxis }, }: PopOverProps): (ctx: DOMContext) => import('@tempots/dom').Clear;
+};
+/**
+ * Renders a PopOver component.
+ *
+ * @param props - The properties for the PopOver component.
+ * @returns The rendered PopOver component.
+ * @public
+ */
+export declare const PopOver: ({ content, open, placement, offset: { mainAxis, crossAxis }, }: PopOverOptions) => (ctx: DOMContext) => import('@tempots/dom').Clear;

package/renderables/result-view.d.ts

@@ -1,7 +1,35 @@
-import { TNode, Signal, Value } from '@tempots/dom';
+import { TNode, Signal, Value, Renderable } from '@tempots/dom';
 import { Result } from '@tempots/std';
 
-export declare function ResultView<T, E>(result: Value<Result<T, E>>, options: {
+/**
+ * Represents the signal for a result.
+ *
+ * @typeParam T - The type of the success value.
+ * @typeParam E - The type of the error value.
+ * @public
+ */
+export type ResultViewOptions<T, E> = {
+    /**
+     * The function to render the view when the computation succeeds.
+     * @param value - The signal for the success value.
+     * @returns The rendered view.
+     */
     success: (value: Signal<T>) => TNode;
+    /**
+     * The function to render the view when the computation fails.
+     * @param error - The signal for the error value.
+     * @returns The rendered view.
+     */
     failure?: (error: Signal<E>) => TNode;
-} | ((value: Signal<T>) => TNode)): import('@tempots/dom').Renderable;
+};
+/**
+ * Renders a view based on the result of a computation.
+ *
+ * @typeParam T - The type of the success value.
+ * @typeParam E - The type of the error value.
+ * @param result - The result of the computation.
+ * @param options - The options for rendering the view.
+ * @returns The rendered view.
+ * @public
+ */
+export declare const ResultView: <T, E>(result: Value<Result<T, E>>, options: ResultViewOptions<T, E> | ((value: Signal<T>) => TNode)) => Renderable;

package/renderables/router/location.d.ts

@@ -1,16 +1,86 @@
 import { TNode, Prop } from '@tempots/dom';
 
-export interface LocationData {
-    pathname: string;
-    search: Record<string, string>;
-    hash?: string;
-}
+/**
+ * Represents the data for a location.
+ *
+ * @public
+ */
+export type LocationData = {
+    /**
+     * The pathname of the location.
+     */
+    readonly pathname: string;
+    /**
+     * The search parameters of the location.
+     */
+    readonly search: Record<string, string>;
+    /**
+     * The hash of the location.
+     */
+    readonly hash?: string;
+};
+/**
+ * Marker for the LocationProvider.
+ *
+ * @public
+ */
 export declare const LocationProviderMarker: import('@tempots/dom').ProviderMark<Prop<LocationData>>;
-export declare function makeLocation(): LocationData;
-export declare function equalsLocation(a: LocationData, b: LocationData): boolean;
-export declare function locationFromURL(url: string): LocationData;
-export declare function setLocationFromUrl(prop: Prop<LocationData>, url: string): Prop<LocationData>;
-export declare function getFullURL(location: LocationData): string;
-export declare function makeLocationProp(): Prop<LocationData>;
-export declare function ProvideLocation(child: TNode): import('@tempots/dom').Renderable;
-export declare function UseLocation(fn: (location: Prop<LocationData>) => TNode): import('@tempots/dom').Renderable;
+/**
+ * Creates a location object based on the current browser location.
+ * @returns The location object representing the current browser location.
+ * @internal
+ */
+export declare const _makeLocation: () => LocationData;
+/**
+ * Compares two location objects and returns true if they are equal, false otherwise.
+ * @param a - The first location object to compare.
+ * @param b - The second location object to compare.
+ * @returns True if the location objects are equal, false otherwise.
+ * @public
+ */
+export declare const areLocationsEqual: (a: LocationData, b: LocationData) => boolean;
+/**
+ * Converts a URL string into a LocationData object.
+ * @param url - The URL string to convert.
+ * @returns The LocationData object representing the URL.
+ * @public
+ */
+export declare const locationFromURL: (url: string) => LocationData;
+/**
+ * Sets the location from the given URL and updates the specified property.
+ * @param prop - The property to update with the new location.
+ * @param url - The URL from which to extract the location.
+ * @returns The updated property.
+ * @public
+ */
+export declare const setLocationFromUrl: (prop: Prop<LocationData>, url: string) => Prop<LocationData>;
+/**
+ * Returns the full URL based on the provided location data.
+ *
+ * @param location - The location data object.
+ * @returns The full URL string.
+ * @public
+ */
+export declare const urlFromLocation: (location: LocationData) => string;
+/**
+ * Creates a location prop that represents the current browser location.
+ * The location prop is updated whenever the browser location changes.
+ *
+ * @returns The location prop.
+ * @internal
+ */
+export declare const _makeLocationProp: () => Prop<LocationData>;
+/**
+ * Provides the location context to the child component.
+ * @param child - The child component to be wrapped with the location context.
+ * @returns The wrapped component with the location context.
+ * @public
+ */
+export declare const ProvideLocation: (child: TNode) => import('@tempots/dom').Renderable;
+/**
+ * A hook that provides the current location data to the given function.
+ * @param fn - The function that receives the location data.
+ * @returns A function that can be used to clean up the resources when the location changes.
+ * @public
+ */
+export declare const UseLocation: (fn: (location: Prop<LocationData>) => TNode) => import('@tempots/dom').Renderable;

package/renderables/router/match.d.ts

@@ -1,14 +1,46 @@
 import { ExtractParams, Route } from './route-info';
 
+/**
+ * The result of a route match.
+ *
+ * @public
+ */
 export type MatchResult<P extends string> = {
     params: ExtractParams<P>;
     path: P;
 } | null;
+/**
+ * The result of a route match with the matched route.
+ *
+ * @public
+ */
 export type MatchResultWithRoute<P extends string, R extends string> = {
     params: ExtractParams<P>;
     route: R;
     path: P;
 } | null;
-export declare function matchesRoute<P extends string>(route: Route, path: P): MatchResult<P>;
-export declare function parseRouteSegments(route: string): Route;
-export declare function makeRouteMatcher<Routes extends string[]>(routes: Routes): <S extends string>(path: S) => MatchResultWithRoute<S, Routes[number]>;
+/**
+ * Matches a path against a route.
+ *
+ * @param route - The route to match against.
+ * @param path - The path to match.
+ * @returns The match result.
+ * @public
+ */
+export declare const matchesRoute: <P extends string>(route: Route, path: P) => MatchResult<P>;
+/**
+ * Parses a route string into an array of route segments.
+ *
+ * @param route - The route string to parse.
+ * @returns An array of route segments.
+ * @internal
+ */
+export declare const _parseRouteSegments: (route: string) => Route;
+/**
+ * Creates a route matcher function that can be used to match paths against a list of routes.
+ *
+ * @param routes - An array of route strings.
+ * @returns A function that can be used to match paths against the provided routes.
+ * @internal
+ */
+export declare const _makeRouteMatcher: <Routes extends string[]>(routes: Routes) => <S extends string>(path: S) => MatchResultWithRoute<S, Routes[number]>;

package/renderables/router/route-info.d.ts

@@ -1,27 +1,112 @@
 import { SplitLiteral, TupleToUnion } from '@tempots/std';
 
-export interface RouteInfo<P, R = string> {
-    params: P;
-    route: R;
-    path: string;
-    search: Record<string, string>;
-    hash?: string;
-}
+/**
+ * Represents information about a route.
+ *
+ * @typeParam P - The type of the route parameters.
+ * @typeParam R - The type of the route.
+ * @public
+ */
+export type RouteInfo<P, R = string> = {
+    /**
+     * The parameters of the route.
+     */
+    readonly params: P;
+    /**
+     * The route that was matched.
+     */
+    readonly route: R;
+    /**
+     * The path that was matched.
+     */
+    readonly path: string;
+    /**
+     * The search parameters of the route.
+     */
+    readonly search: Record<string, string>;
+    /**
+     * The hash of the route.
+     */
+    readonly hash?: string;
+};
+/**
+ * Represents a route parameter.
+ *
+ * @public
+ */
 export type RouteParam = {
+    /**
+     * The type of the route parameter.
+     */
     type: 'param';
+    /**
+     * The name of the route parameter.
+     */
     name: string;
 };
+/**
+ * Represents a literal route.
+ *
+ * @public
+ */
 export type RouteLiteral = {
+    /**
+     * The type of the route literal.
+     */
     type: 'literal';
+    /**
+     * The value of the route literal
+     */
     value: string;
 };
+/**
+ * Represents a catch-all route.
+ *
+ * @public
+ */
 export type RouteCatchAll = {
+    /**
+     * The type of the catch-all
+     */
     type: 'catch-all';
 };
+/**
+ * Represents a segment of a route.
+ *
+ * @public
+ */
 export type RouteSegment = RouteParam | RouteLiteral | RouteCatchAll;
+/**
+ * Represents a route in the application.
+ *
+ * @public
+ */
 export type Route = RouteSegment[];
+/**
+ * Represents a type that transforms a tuple of strings into an object with string keys.
+ * If the input type is a tuple, each element of the tuple will become a key in the resulting object,
+ * with the corresponding value being a string.
+ * If the input type is not a tuple, the resulting type will be `never`.
+ *
+ * @typeparam P - The input type, which can be a tuple of strings or any other type.
+ * @returns - If `P` is a tuple, an object with string keys. Otherwise, `never`.
+ * @public
+ */
 export type MakeParams<P> = P extends string[] ? {
     [K in TupleToUnion<P>]: string;
 } : never;
+/**
+ * Extracts the parameter names from a tuple type.
+ *
+ * @typeParam S - The tuple type from which to extract the parameter names.
+ * @returns An array of parameter names extracted from the tuple type.
+ * @public
+ */
 export type ExtractParamsFromTuple<S extends unknown[]> = S extends [] ? [] : S extends [infer H, ...infer R] ? H extends `:${infer P}` ? [P, ...ExtractParamsFromTuple<R>] : ExtractParamsFromTuple<R> : never;
+/**
+ * Extracts the parameters from a string literal representing a route path.
+ * @typeParam S - The string literal representing the route path.
+ * @returns The extracted parameters from the route path.
+ * @public
+ */
 export type ExtractParams<S extends string> = SplitLiteral<S, '/'> extends infer T ? T extends unknown[] ? ExtractParamsFromTuple<T> : never : never;

package/renderables/router/router.d.ts

@@ -1,6 +1,12 @@
 import { TNode, Renderable, Signal } from '@tempots/dom';
 import { ExtractParams, MakeParams, RouteInfo } from './route-info';
 
-export declare function Router<T extends {
-    [K in keyof T]: (info: K extends string ? Signal<RouteInfo<MakeParams<ExtractParams<K>>, K>> : never) => TNode;
-}>(routes: T): Renderable;
+/**
+ * Creates a router that maps routes to corresponding renderable components.
+ *
+ * @typeParam T - The type of the routes object.
+ * @param routes - An object containing route handlers.
+ * @returns - The router renderable.
+ * @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;

package/renderables/select-on-focus.d.ts

@@ -1 +1,7 @@
-export declare function SelectOnFocus(): import('@tempots/dom').Renderable;
+/**
+ * Selects the text inside an input element when it receives focus.
+ *
+ * @returns A renderable function that selects the text inside an input element when it receives focus.
+ * @public
+ */
+export declare const SelectOnFocus: () => import('@tempots/dom').Renderable;

package/renderables/size.d.ts

@@ -1,6 +1,17 @@
 import { DOMContext, Signal, TNode, Size } from '@tempots/dom';
 
-export declare const size: {
-    element: (fn: (size: Signal<Size>) => TNode) => (ctx: DOMContext) => (removeTree: boolean) => void;
-    window: (fn: (size: Signal<Size>) => TNode) => (ctx: DOMContext) => (removeTree: boolean) => void;
-};
+/**
+ * Creates a renderable function that monitors the size of an element and provides it as a signal.
+ *
+ * @param fn - The renderable function that receives the size signal and returns a TNode.
+ * @returns A function that takes a DOMContext and returns a renderable function.
+ * @public
+ */
+export declare const ElementSize: (fn: (size: Signal<Size>) => TNode) => (ctx: DOMContext) => (removeTree: boolean) => void;
+/**
+ * Creates a renderable function that monitors the window size and invokes the provided function with the current size.
+ * @param fn - The function to be invoked with the current window size.
+ * @returns A renderable function that monitors the window size.
+ * @public
+ */
+export declare const WindowSize: (fn: (size: Signal<Size>) => TNode) => (ctx: DOMContext) => (removeTree: boolean) => void;