@tempots/ui 16.0.10 → 16.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/ui",
-  "version": "16.0.10",
+  "version": "16.1.1",
   "type": "module",
   "sideEffects": false,
   "main": "./index.cjs",
@@ -40,7 +40,7 @@
   "license": "Apache-2.0",
   "peerDependencies": {
     "@floating-ui/dom": "^1.7.1",
-    "@tempots/dom": "^37.4.3",
+    "@tempots/dom": "^37.5.0",
     "@tempots/std": "^0.29.1"
   }
 }

package/renderables/mutation.d.ts

@@ -1,6 +1,6 @@
 import { Renderable, Signal, TNode } from '@tempots/dom';
 import { AsyncResult, NonLoading } from '@tempots/std';
-import { MutationResource, MutationResourceExecuteOptions } from '../utils/mutation-resource';
+import { MutationResource, MutationResourceLoadOptions } from '../utils/mutation-resource';
 export interface MutationContentOptions<Req, Res, E> {
     previous: Signal<Res | undefined>;
     execute: (request: Req) => void;
@@ -18,7 +18,7 @@ export interface MutationContentOptions<Req, Res, E> {
  * @public
  */
 export interface MutationDisplayOptions<Req, Res, E> {
-    /** Function to render when the query is loading. */
+    /** Function to render the mutation content. */
     content: (options: MutationContentOptions<Req, Res, E>) => TNode;
 }
 /**
@@ -35,23 +35,28 @@ export interface MutationDisplayOptions<Req, Res, E> {
  */
 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.
+ * Creates a reactive mutation component for handling asynchronous write operations.
  *
- * 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.
+ * This component provides a declarative way to handle mutations (POST/PUT/PATCH/DELETE)
+ * with proper loading, success, and error states. Unlike Query, mutations are triggered
+ * explicitly via `execute()` rather than reactively from a request signal.
  *
- * @typeParam Req - The type of the request.
- * @typeParam Res - The type of the value when the resource is successfully loaded.
- * @typeParam E - The type of the error when the resource fails to load.
+ * @typeParam Req - The type of the request payload.
+ * @typeParam Res - The type of the value when the mutation succeeds.
+ * @typeParam E - The type of the error when the mutation fails.
  *
- * @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.
+ * @param options - Configuration object for the mutation
+ * @param options.mutate - Async function that performs the mutation
+ * @param options.convertError - Optional function to transform errors into a specific type
+ * @param options.onSuccess - Optional callback for successful mutations
+ * @param options.onError - Optional callback for failed mutations
+ * @param options.onSettled - Optional callback for both successful and failed mutations
+ * @param options.content - Function to render the mutation UI
+ * @returns A renderable component
  * @public
  */
 export declare const Mutation: <Req, Res, E = unknown>({ mutate, convertError, onSuccess, onError, onSettled, content, }: {
-    mutate: (options: MutationResourceExecuteOptions<Req, Res, E>) => Promise<Res>;
+    mutate: (options: MutationResourceLoadOptions<Req, Res, E>) => Promise<Res>;
     convertError?: (error: unknown) => E;
     onSuccess?: (value: Res, req: Req) => void;
     onError?: (error: E, req: Req) => void;

package/renderables/query.d.ts

@@ -9,6 +9,8 @@ import { AsyncResult, NonLoading } from '@tempots/std';
  * @public
  */
 export interface QueryDisplayOptions<Res, E> {
+    /** Function to render when the query has not been requested yet. */
+    notAsked?: () => TNode;
     /** Function to render when the query is loading. */
     pending?: (options: {
         previous: Signal<Res | undefined>;
@@ -24,7 +26,15 @@ export interface QueryDisplayOptions<Res, E> {
     success: (options: {
         value: Signal<Res>;
         reload: () => void;
+        loading: Signal<boolean>;
     }) => TNode;
+    /**
+     * When true, the success view stays mounted during reloads instead of
+     * switching to the pending view. The `loading` signal passed to `success`
+     * indicates when a reload is in progress. Only applies when the query
+     * was already in a success state before the reload.
+     */
+    keepOnReload?: boolean;
 }
 /**
  * Component to display an asynchronous query based on its current status.
@@ -57,90 +67,43 @@ export declare const QueryDisplay: <Res, E>(query: QueryResource<Res, E>, option
  *     if (!response.ok) throw new Error('Failed to load user')
  *     return response.json()
  *   },
- *   loading: () => html.div('Loading user...'),
- *   failure: (error, reload) => html.div(
+ *   pending: () => 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))
+ *   success: ({ value }) => html.div(
+ *     html.h2(value.map(u => u.name)),
+ *     html.p(value.map(u => u.email))
  *   )
  * })
  * ```
  *
  * @example
  * ```typescript
- * // Query with dependencies
+ * // Query with keepOnReload — success view stays mounted during reloads
  * const searchQuery = prop('')
- * const filters = prop({ category: 'all', sort: 'name' })
  *
  * const SearchResults = Query({
- *   request: computed(() => ({
- *     query: searchQuery.value,
- *     ...filters.value
- *   })),
+ *   request: searchQuery,
+ *   keepOnReload: true,
  *   load: async ({ request, abortSignal }) => {
- *     const params = new URLSearchParams(request)
- *     const response = await fetch(`/api/search?${params}`, {
+ *     const response = await fetch(`/api/search?q=${request}`, {
  *       signal: abortSignal
  *     })
  *     return response.json()
  *   },
  *   convertError: (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(
+ *   pending: () => html.div('Searching...'),
+ *   failure: ({ error, reload }) => html.div(
  *     attr.class('error'),
  *     'Search failed: ', error,
  *     html.button(on.click(reload), 'Try again')
  *   ),
- *   success: (results, reload) => html.div(
+ *   success: ({ value, reload, loading }) => html.div(
  *     html.button(on.click(reload), 'Refresh'),
- *     ForEach(results, result => SearchResultItem(result))
- *   )
- * })
- * ```
- *
- * @example
- * ```typescript
- * // File upload query
- * const selectedFile = prop<File | null>(null)
- *
- * const FileUpload = Query({
- *   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'
- *     )
+ *     loading.map(l => l ? html.div('Refreshing...') : null),
+ *     ForEach(value, result => SearchResultItem(result))
  *   )
  * })
  * ```
@@ -155,13 +118,15 @@ export declare const QueryDisplay: <Res, E>(query: QueryResource<Res, E>, option
  * @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.notAsked - Optional function to render before the first load
  * @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
+ * @param options.keepOnReload - When true, keeps the success view mounted during reloads
+ * @returns A renderable component
  * @public
  */
-export declare const Query: <Req, Res, E = unknown>({ request, load, convertError, onSuccess, onError, onSettled, success, pending, failure, }: {
+export declare const Query: <Req, Res, E = unknown>({ request, load, convertError, onSuccess, onError, onSettled, notAsked, success, pending, failure, keepOnReload, }: {
     request: Value<Req>;
     load: (options: QueryResourceLoadOptions<Req, Res, E>) => Promise<Res>;
     convertError?: (error: unknown) => E;

package/utils/mutation-resource.d.ts

@@ -18,23 +18,39 @@ export interface MutationResource<Req, Res, E> {
     /** Whether a mutation is currently in flight. */
     readonly pending: Signal<boolean>;
     /** Execute the mutation. */
-    readonly execute: (request: Req, options?: MutationResourceExecuteOptions<Req, Res, E>) => void;
+    readonly execute: (request: Req, options?: MutationResourceExecuteOptions<Req, Res>) => 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.
+ * Options passed to the mutate function.
+ *
+ * @typeParam Req - The request payload/type.
+ * @typeParam Res - The response/value type on success.
+ * @typeParam E   - The error type on failure.
+ * @public
  */
-export interface MutationResourceExecuteOptions<Req, Res, E> {
+export interface MutationResourceLoadOptions<Req, Res, E> {
     /** The request to execute the mutation. */
     readonly request: Req;
-    /** External abort signal for this single execution. */
+    /** Abort signal for this execution. */
     readonly abortSignal: AbortSignal;
     /** The previous result of the mutation, if any. */
     readonly previous: AsyncResult<Res, E>;
+    /** Abort the current in-flight request and optionally set a new state. */
+    readonly cancel: (newState?: NonLoading<Res, E>) => void;
+}
+/**
+ * Caller-controlled options for execute().
+ * Useful for optimistic UI.
+ *
+ * @typeParam Req - The request payload/type.
+ * @typeParam Res - The response/value type on success.
+ * @public
+ */
+export interface MutationResourceExecuteOptions<Req, Res> {
     /**
      * Optionally provide an optimistic value to set immediately.
      * This will set status to Loading with value prefilled.
@@ -45,13 +61,9 @@ export interface MutationResourceExecuteOptions<Req, Res, E> {
      * 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>;
+    mutate: (options: MutationResourceLoadOptions<Req, Res, E>) => Promise<Res>;
     convertError: (error: unknown) => E;
     onSuccess?: (value: Res, req: Req) => void;
     onError?: (error: E, req: Req) => void;

package/utils/query-resource.d.ts

@@ -39,10 +39,8 @@ export interface QueryResourceLoadOptions<Req, Res, E> {
     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;
+    /** Abort the current in-flight request and optionally set a new state. */
+    readonly cancel: (newState?: NonLoading<Res, E>) => void;
 }
 /**
  * Creates an asynchronous query that can be loaded, reloaded, and disposed of.