@tempots/ui 7.0.3 → 8.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/ui",
-  "version": "7.0.3",
+  "version": "8.0.1",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",
@@ -40,7 +40,7 @@
     "@floating-ui/dom": "^1.6.7"
   },
   "peerDependencies": {
-    "@tempots/std": "0.22.1",
-    "@tempots/dom": "29.0.3"
+    "@tempots/std": "0.23.0",
+    "@tempots/dom": "30.0.0"
   }
 }

package/renderables/mutation.d.ts

@@ -0,0 +1,69 @@
+import { Renderable, Signal, TNode } from '@tempots/dom';
+import { AsyncResult, NonLoading } from '@tempots/std';
+import { MutationResource, MutationResourceExecuteOptions } from '../utils/mutation-resource';
+/**
+ * Options for displaying the different states of an asynchronous resource.
+ *
+ * @template Res - 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 MutationDisplayOptions<Req, Res, E> {
+    /** Function to render when the query is loading. */
+    pending?: (options: {
+        previous: Signal<Res | undefined>;
+        retry: () => void;
+        execute: (request: Req) => void;
+        cancel: (newState?: NonLoading<Res, E>) => void;
+    }) => TNode;
+    /** Function to render when the query has failed to load. */
+    failure?: (options: {
+        error: Signal<E>;
+        retry: () => void;
+        execute: (request: Req) => void;
+    }) => TNode;
+    /** Function to render when the query has successfully loaded. */
+    success: (options: {
+        value: Signal<Res>;
+        execute: (request: Req) => void;
+    }) => TNode;
+    notAsked: (options: {
+        execute: (request: Req) => void;
+    }) => TNode;
+}
+/**
+ * Component to display an asynchronous mutation based on its current status.
+ *
+ * @template Req - The type of the request.
+ * @template Res - 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 {MutationResource<Req, Res, E>} resource - The asynchronous resource to display.
+ * @param {MutationDisplayOptions<Req, Res, E>} options - The display options for the resource.
+ * @returns {Renderable} A node representing the current state of the resource.
+ * @public
+ */
+export declare const MutationDisplay: <Req, Res, E>(resource: MutationResource<Req, Res, E>, options: MutationDisplayOptions<Req, Res, E>) => Renderable;
+/**
+ * Creates a reactive mutation component for handling asynchronous data loading.
+ *
+ * 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.
+ *
+ * @template Req - The type of the request.
+ * @template Res - 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 {MutationResource<Req, Res, E>} resource - The asynchronous resource to display.
+ * @param {MutationDisplayOptions<Req, Res, E>} options - The display options for the resource.
+ * @returns {Renderable} A node representing the current state of the resource.
+ * @public
+ */
+export declare const Mutation: <Req, Res, E = unknown>({ mutate, convertError, onSuccess, onError, onSettled, pending, failure, success, notAsked, }: {
+    mutate: (options: MutationResourceExecuteOptions<Req, Res, E>) => Promise<Res>;
+    convertError?: (error: unknown) => E;
+    onSuccess?: (value: Res, req: Req) => void;
+    onError?: (error: E, req: Req) => void;
+    onSettled?: (result: AsyncResult<Res, E>, req: Req) => void;
+} & MutationDisplayOptions<Req, Res, E>) => Renderable;

package/renderables/{resource.d.ts → query.d.ts}

@@ -1,34 +1,45 @@
 import { Renderable, Signal, TNode, Value } from '@tempots/dom';
-import { AsyncResource, ResourceLoadOptions } from '../utils/resource';
+import { QueryResource, QueryResourceLoadOptions } from '../utils/query-resource';
+import { AsyncResult, NonLoading } from '@tempots/std';
 /**
- * Options for displaying the different states of an asynchronous resource.
+ * Options for displaying the different states of an asynchronous query.
  *
- * @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.
+ * @template Res - The type of the value when the query is successfully loaded.
+ * @template E - The type of the error when the query fails to load.
  * @public
  */
-export interface ResourceDisplayOptions<V, E> {
-    /** 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. */
-    failure?: (error: Signal<E>, reload: () => void) => TNode;
-    /** Function to render when the resource has successfully loaded. */
-    success: (value: Signal<V>, reload: () => void) => TNode;
+export interface QueryDisplayOptions<Res, E> {
+    /** Function to render when the query is loading. */
+    pending?: (options: {
+        previous: Signal<Res | undefined>;
+        reload: () => void;
+        cancel: (newState?: NonLoading<Res, E>) => void;
+    }) => TNode;
+    /** Function to render when the query has failed to load. */
+    failure?: (options: {
+        error: Signal<E>;
+        reload: () => void;
+    }) => TNode;
+    /** Function to render when the query has successfully loaded. */
+    success: (options: {
+        value: Signal<Res>;
+        reload: () => void;
+    }) => TNode;
 }
 /**
- * Component to display an asynchronous resource based on its current status.
+ * Component to display an asynchronous query 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.
+ * @template Res - The type of the value when the query is successfully loaded.
+ * @template E - The type of the error when the query 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.
+ * @param {QueryResource<Res, E>} query - The asynchronous query to display.
+ * @param {QueryDisplayOptions<Res, E>} options - The display options for the query.
+ * @returns {TNode} A node representing the current state of the query.
  * @public
  */
-export declare const ResourceDisplay: <V, E>(resource: AsyncResource<V, E>, options: ResourceDisplayOptions<V, E>) => Renderable<import('@tempots/dom').DOMContext>;
+export declare const QueryDisplay: <Res, E>(query: QueryResource<Res, E>, options: QueryDisplayOptions<Res, E>) => Renderable;
 /**
- * Creates a reactive resource component for handling asynchronous data loading.
+ * Creates a reactive query component for handling asynchronous data loading.
  *
  * This component provides a declarative way to handle async operations with proper
  * loading, success, and error states. It automatically manages the lifecycle of
@@ -39,14 +50,13 @@ export declare const ResourceDisplay: <V, E>(resource: AsyncResource<V, E>, opti
  * // Basic API data loading
  * const userId = prop(1)
  *
- * const UserProfile = Resource({
+ * const UserProfile = Query({
  *   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,
@@ -61,11 +71,11 @@ export declare const ResourceDisplay: <V, E>(resource: AsyncResource<V, E>, opti
  *
  * @example
  * ```typescript
- * // Resource with dependencies
+ * // Query with dependencies
  * const searchQuery = prop('')
  * const filters = prop({ category: 'all', sort: 'name' })
  *
- * const SearchResults = Resource({
+ * const SearchResults = Query({
  *   request: computed(() => ({
  *     query: searchQuery.value,
  *     ...filters.value
@@ -77,8 +87,7 @@ export declare const ResourceDisplay: <V, E>(resource: AsyncResource<V, E>, opti
  *     })
  *     return response.json()
  *   },
- *   mapError: (error) => error instanceof Error ? error.message : 'Unknown error'
- * })({
+ *   convertError: (error) => error instanceof Error ? error.message : 'Unknown error',
  *   loading: (previous) => html.div(
  *     'Searching...',
  *     previous.value && html.div('Previous results:', previous.value.length)
@@ -97,10 +106,10 @@ export declare const ResourceDisplay: <V, E>(resource: AsyncResource<V, E>, opti
  *
  * @example
  * ```typescript
- * // File upload resource
+ * // File upload query
  * const selectedFile = prop<File | null>(null)
  *
- * const FileUpload = Resource({
+ * const FileUpload = Query({
  *   request: selectedFile,
  *   load: async ({ request }) => {
  *     if (!request) throw new Error('No file selected')
@@ -115,8 +124,7 @@ export declare const ResourceDisplay: <V, E>(resource: AsyncResource<V, E>, opti
  *
  *     if (!response.ok) throw new Error('Upload failed')
  *     return response.json()
- *   }
- * })({
+ *   },
  *   loading: () => html.div(
  *     attr.class('upload-progress'),
  *     'Uploading file...'
@@ -137,18 +145,27 @@ export declare const ResourceDisplay: <V, E>(resource: AsyncResource<V, E>, opti
  * })
  * ```
  *
- * @template R - The type of the request parameter
- * @template V - The type of the successful result value
+ * @template Req - The type of the request parameter
+ * @template Res - 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
+ * @param options - Configuration object for the query
+ * @param options.request - Signal or value representing the request parameters
+ * @param options.load - Async function that loads the query
+ * @param options.convertError - Optional function to transform errors into a specific type
+ * @param options.onSuccess - Optional callback for successful loads
+ * @param options.onError - Optional callback for failed loads
+ * @param options.onSettled - Optional callback for both successful and failed loads
+ * @param options.success - Function to render when the query has successfully loaded
+ * @param options.pending - Optional function to render when the query is loading
+ * @param options.failure - Optional function to render when the query has failed to load
  * @returns Function that takes display options and returns a renderable component
  * @public
  */
-export declare const Resource: <R, V, E = unknown>({ request, load, mapError, }: {
-    request: Value<R>;
-    load: (options: ResourceLoadOptions<R, V, E>) => Promise<V>;
-    mapError?: (error: unknown) => E;
-}) => ((displayOptions: ResourceDisplayOptions<V, E>) => Renderable);
+export declare const Query: <Req, Res, E = unknown>({ request, load, convertError, onSuccess, onError, onSettled, success, pending, failure, }: {
+    request: Value<Req>;
+    load: (options: QueryResourceLoadOptions<Req, Res, E>) => Promise<Res>;
+    convertError?: (error: unknown) => E;
+    onSuccess?: (value: Res, req: Req) => void;
+    onError?: (error: E, req: Req) => void;
+    onSettled?: (result: AsyncResult<Res, E>, req: Req) => void;
+} & QueryDisplayOptions<Res, E>) => Renderable;

package/utils/mutation-resource.d.ts

@@ -0,0 +1,59 @@
+import { Signal } from '@tempots/dom';
+import { AsyncResult, NonLoading } from '@tempots/std';
+/**
+ * A write-side wrapper for async state around POST/PUT/PATCH/DELETE.
+ * Mirrors AsyncResource but the action is explicit (execute), not implicit (reload).
+ *
+ * @template Req - The request payload/type you send.
+ * @template Res - The response/value you get back on success.
+ * @template E   - The error type on failure.
+ */
+export interface MutationResource<Req, Res, E> {
+    /** Current async status (Idle | Loading | Success | Failure). */
+    readonly status: Signal<AsyncResult<Res, E>>;
+    /** Latest successful value (if any). */
+    readonly value: Signal<Res | undefined>;
+    /** Latest error (if any). */
+    readonly error: Signal<E | undefined>;
+    /** Whether a mutation is currently in flight. */
+    readonly pending: Signal<boolean>;
+    /** Execute the mutation. */
+    readonly execute: (request: Req, options?: MutationResourceExecuteOptions<Req, Res, E>) => void;
+    /** Abort the current in-flight request (if any) and clean up. */
+    readonly cancel: (newState?: NonLoading<Res, E>) => void;
+    /** Dispose of resources, aborting any in-flight request. */
+    readonly dispose: () => void;
+}
+/**
+ * Execution-time options for a mutation.
+ * Useful for optimistic UI and side-effects.
+ */
+export interface MutationResourceExecuteOptions<Req, Res, E> {
+    /** The request to execute the mutation. */
+    readonly request: Req;
+    /** External abort signal for this single execution. */
+    readonly abortSignal: AbortSignal;
+    /** The previous result of the mutation, if any. */
+    readonly previous: AsyncResult<Res, E>;
+    /**
+     * Optionally provide an optimistic value to set immediately.
+     * This will set status to Loading with value prefilled.
+     */
+    readonly optimisticValue?: Res;
+    /**
+     * Optionally derive an optimistic value from the request.
+     * Runs only if optimisticValue is not provided.
+     */
+    readonly optimisticFromRequest?: (req: Req) => Res;
+    /** Side-effects */
+    readonly onSuccess?: (value: Res, req: Req) => void;
+    readonly onError?: (error: E, req: Req) => void;
+    readonly onSettled?: (result: AsyncResult<Res, E>, req: Req) => void;
+}
+export declare const makeMutationResource: <Req, Res, E>({ mutate, convertError, onSuccess, onError, onSettled, }: {
+    mutate: (options: MutationResourceExecuteOptions<Req, Res, E>) => Promise<Res>;
+    convertError: (error: unknown) => E;
+    onSuccess?: (value: Res, req: Req) => void;
+    onError?: (error: E, req: Req) => void;
+    onSettled?: (result: AsyncResult<Res, E>, req: Req) => void;
+}) => MutationResource<Req, Res, E>;

package/utils/query-resource.d.ts

@@ -0,0 +1,67 @@
+import { Signal, Value } from '@tempots/dom';
+import { AsyncResult, NonLoading } from '@tempots/std';
+/**
+ * Represents an asynchronous query with its current status, value, error, and loading state.
+ * Provides methods to reload the query and dispose of it.
+ *
+ * @template Res - The type of the value when the query is successfully loaded.
+ * @template E - The type of the error when the query fails to load.
+ * @public
+ */
+export interface QueryResource<Res, E> {
+    /** The current status of the query as an AsyncResult. */
+    readonly status: Signal<AsyncResult<Res, E>>;
+    /** Abort the current in-flight request (if any) and clean up. */
+    readonly cancel: (newState?: NonLoading<Res, E>) => void;
+    /** Disposes of the query, aborting any ongoing requests and cleaning up. */
+    readonly dispose: () => void;
+    /** The current value of the query, or undefined if not loaded or failed. */
+    readonly value: Signal<Res | undefined>;
+    /** The current error of the query, or undefined if not failed. */
+    readonly error: Signal<E | undefined>;
+    /** Whether the query is currently loading. */
+    readonly loading: Signal<boolean>;
+    /** Reloads the query using the current request. */
+    readonly reload: () => void;
+}
+/**
+ * Options for loading a query, including the request, abort signal, and previous result.
+ *
+ * @template Req - The type of the request.
+ * @template Res - The type of the value when the query is successfully loaded.
+ * @template E - The type of the error when the query fails to load.
+ * @public
+ */
+export interface QueryResourceLoadOptions<Req, Res, E> {
+    /** The request to load the query. */
+    readonly request: Req;
+    /** The signal to abort the loading process if needed. */
+    readonly abortSignal: AbortSignal;
+    /** The previous result of the query loading, if any. */
+    readonly previous: AsyncResult<Res, E>;
+    /** Side-effects */
+    readonly onSuccess?: (value: Res, req: Req) => void;
+    readonly onError?: (error: E, req: Req) => void;
+    readonly onSettled?: (result: AsyncResult<Res, E>, req: Req) => void;
+}
+/**
+ * Creates an asynchronous query that can be loaded, reloaded, and disposed of.
+ *
+ * @template R - The type of the request.
+ * @template V - The type of the value when the query is successfully loaded.
+ * @template E - The type of the error when the query fails to load.
+ *
+ * @param request - The request to load the query.
+ * @param load - The function to load the query.
+ * @param convertError - The function to convert an unknown error into a specific error type.
+ * @returns The created asynchronous query.
+ * @public
+ */
+export declare const makeQueryResource: <Req, Res, E>({ request, load, convertError, onSuccess, onError, onSettled, }: {
+    request: Value<Req>;
+    load: (options: QueryResourceLoadOptions<Req, Res, E>) => Promise<Res>;
+    convertError: (error: unknown) => E;
+    onSuccess?: (value: Res, req: Req) => void;
+    onError?: (error: E, req: Req) => void;
+    onSettled?: (result: AsyncResult<Res, E>, req: Req) => void;
+}) => QueryResource<Res, E>;

package/utils/resource.d.ts

@@ -1,54 +0,0 @@
-import { Signal, Value } 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>;
-}
-/**
- * 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 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 The created asynchronous resource.
- * @public
- */
-export declare const makeResource: <R, V, E>(request: Value<R>, load: (options: ResourceLoadOptions<R, V, E>) => Promise<V>, convertError: (error: unknown) => E) => AsyncResource<V, E>;