@tempots/ui 1.2.0 → 1.2.1

package/package.json

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

package/renderables/resource.d.ts

@@ -1,12 +1,53 @@
 import { Signal, TNode } from '@tempots/dom';
 import { MakeResourceOptions, AsyncResource } from '../utils/resource';
+/**
+ * Options for displaying the different states of an asynchronous resource.
+ *
+ * @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.
+ * @public
+ */
 export interface ResourceDisplayOptions<V, E> {
+    /** Function to render when the resource has not been requested yet. */
     notAsked?: (reload: () => void) => TNode;
+    /** Function to render when the resource is loading. */
     loading?: (previous: Signal<V | undefined>, reload: () => void) => TNode;
+    /** Function to render when the resource has failed to load. */
     error?: (error: Signal<E>, reload: () => void) => TNode;
+    /** Function to render when the resource has successfully loaded. */
     success: (value: Signal<V>, reload: () => void) => TNode;
 }
+/**
+ * Options for creating and displaying an asynchronous resource.
+ *
+ * @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.
+ * @public
+ */
 export interface ResourceOptions<R, V, E> extends MakeResourceOptions<R, V, E>, ResourceDisplayOptions<V, E> {
 }
+/**
+ * Component to display an asynchronous resource based on its current status.
+ *
+ * @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.
+ *
+ * @param {AsyncResource<V, E>} resource - The asynchronous resource to display.
+ * @param {ResourceDisplayOptions<V, E>} options - The display options for the resource.
+ * @returns {TNode} A node representing the current state of the resource.
+ * @public
+ */
 export declare const ResourceDisplay: <V, E>(resource: AsyncResource<V, E>, options: ResourceDisplayOptions<V, E>) => import('@tempots/dom').Renderable;
+/**
+ * Creates and displays an asynchronous resource.
+ *
+ * @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.
+ *
+ * @param {ResourceOptions<R, V, E>} options - The options for creating and displaying the resource.
+ * @returns {TNode} A node representing the current state of the resource.
+ * @public
+ */
 export declare const Resource: <R, V, E>(options: ResourceOptions<R, V, E>) => import('@tempots/dom').Renderable;

package/utils/resource.d.ts

@@ -1,21 +1,68 @@
 import { Signal } from '@tempots/dom';
 import { AsyncResult } from '@tempots/std';
+/**
+ * Represents an asynchronous resource with its current status, value, error, and loading state.
+ * Provides methods to reload the resource and dispose of it.
+ *
+ * @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.
+ * @public
+ */
 export interface AsyncResource<V, E> {
+    /** The current status of the resource as an AsyncResult. */
     readonly status: Signal<AsyncResult<V, E>>;
+    /** Disposes of the resource, aborting any ongoing requests and cleaning up. */
     readonly dispose: () => void;
+    /** The current value of the resource, or undefined if not loaded or failed. */
     readonly value: Signal<V | undefined>;
+    /** The current error of the resource, or undefined if not failed. */
     readonly error: Signal<E | undefined>;
+    /** Whether the resource is currently loading. */
     readonly loading: Signal<boolean>;
+    /** Reloads the resource using the current request. */
     readonly reload: () => void;
 }
+/**
+ * Options for loading a resource, including the request, abort signal, and previous result.
+ *
+ * @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.
+ * @public
+ */
 export interface ResourceLoadOptions<R, V, E> {
+    /** The request to load the resource. */
     readonly request: R;
+    /** The signal to abort the loading process if needed. */
     readonly abortSignal: AbortSignal;
+    /** The previous result of the resource loading, if any. */
     readonly previous: AsyncResult<V, E>;
 }
+/**
+ * Options for creating a resource, including the request signal, load function, and error converter.
+ *
+ * @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.
+ * @public
+ */
 export interface MakeResourceOptions<R, V, E> {
+    /** A signal representing the request to load the resource. */
     readonly request: Signal<R>;
+    /** A function to load the resource, returning a promise of the value. */
     readonly load: (options: ResourceLoadOptions<R, V, E>) => Promise<V>;
+    /** A function to convert an unknown error into a specific error type. */
     readonly convertError: (error: unknown) => E;
 }
+/**
+ * Creates an asynchronous resource that can be loaded, reloaded, and disposed of.
+ *
+ * @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.
+ *
+ * @param {MakeResourceOptions<R, V, E>} options - The options for creating the resource.
+ * @returns {AsyncResource<V, E>} The created asynchronous resource.
+ * @public
+ */
 export declare const makeResource: <R, V, E>({ request, load, convertError, }: MakeResourceOptions<R, V, E>) => AsyncResource<V, E>;