nuxt-ui-tools 1.11.1 → 1.12.0

package/dist/module.json

@@ -5,7 +5,7 @@
   "configKey": "nuxtUiTools",
   "docs": "https://ui.nuxt.com/docs/getting-started/installation/nuxt",
   "name": "nuxt-ui-tools",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/runtime/form/components/provider/form-overlay-host.vue

@@ -49,6 +49,7 @@ function resolveSchemaUi(schema) {
   >
     <FormRoot
       :form="overlay.form"
+      :runtime="overlay.runtime"
       shell="drawer"
       :show-close-button="drawerConfig?.showCloseButton !== false"
       :ui="formUi"
@@ -70,6 +71,7 @@ function resolveSchemaUi(schema) {
   >
     <FormRoot
       :form="overlay.form"
+      :runtime="overlay.runtime"
       shell="fullscreen"
       :show-close-button="fullscreenConfig?.showCloseButton !== false"
       :ui="formUi"
@@ -91,6 +93,7 @@ function resolveSchemaUi(schema) {
   >
     <FormRoot
       :form="overlay.form"
+      :runtime="overlay.runtime"
       shell="modal"
       :show-close-button="modalConfig?.showCloseButton !== false"
       :ui="formUi"

package/dist/runtime/form/components/root/form.d.vue.ts

@@ -1,6 +1,7 @@
-import type { FormValue, FormObject, FormRendererController, FormRenderShell, FormUiConfig, FormValidationMode } from '../../types/index.js';
+import type { FormValue, FormObject, FormRendererController, FormRuntime, FormRenderShell, FormUiConfig, FormValidationMode } from '../../types/index.js';
 type __VLS_Props = {
     form?: FormRendererController;
+    runtime?: FormRuntime;
     schema?: FormValue;
     input?: FormObject;
     shell?: FormRenderShell;

package/dist/runtime/form/components/root/form.vue

@@ -20,6 +20,7 @@ import FormFieldRenderer from "../renderer/form-field-renderer.vue";
 import FormDirectionalTransition from "../utils/form-directional-transition.vue";
 const props = defineProps({
   form: { type: Object, required: false },
+  runtime: { type: Object, required: false },
   schema: { type: null, required: false },
   input: { type: null, required: false },
   shell: { type: String, required: false },
@@ -42,6 +43,7 @@ const {
   submit
 } = useFormRoot({
   form: () => props.form,
+  runtime: () => props.runtime,
   input: () => props.input,
   onCancelled: (value) => emit("cancel", value),
   onSubmitted: (value, result) => emit("submit", value, result),

package/dist/runtime/form/components/root/form.vue.d.ts

@@ -1,6 +1,7 @@
-import type { FormValue, FormObject, FormRendererController, FormRenderShell, FormUiConfig, FormValidationMode } from '../../types/index.js';
+import type { FormValue, FormObject, FormRendererController, FormRuntime, FormRenderShell, FormUiConfig, FormValidationMode } from '../../types/index.js';
 type __VLS_Props = {
     form?: FormRendererController;
+    runtime?: FormRuntime;
     schema?: FormValue;
     input?: FormObject;
     shell?: FormRenderShell;

package/dist/runtime/form/composables/use-form-overlay-controller.d.ts

@@ -8,5 +8,6 @@ export declare function useFormOverlayController(instance: FormApiRuntimeInstanc
     handleSubmitted: (formData: FormObject, result: FormSubmitHandlerResult<FormValue>) => void;
     open: import("vue").Ref<boolean, boolean>;
     resolveAfterClose: () => void;
+    runtime: import("../types/index.js").FormRuntime;
     title: import("vue").ComputedRef<string | undefined>;
 };

package/dist/runtime/form/composables/use-form-overlay-controller.js

@@ -3,6 +3,7 @@ import { getFormOverlayDescription, getFormOverlayTitle } from "../utils/overlay
 import { isRecord } from "../utils/path.js";
 import { useForm } from "./use-form.js";
 import { useFormApi } from "./use-form-api.js";
+import { useFormRuntime } from "./use-form-runtime.js";
 export function useFormOverlayController(instance) {
   const formApi = useFormApi();
   const form = useForm({
@@ -17,6 +18,13 @@ export function useFormOverlayController(instance) {
     () => getFormOverlayDescription(instance.schema) ?? getFormOverlayTitle(instance.schema) ?? "Form"
   );
   const dismissible = computed(() => !form.isSubmitting.value);
+  const runtime = useFormRuntime({
+    input: form.input,
+    schema: form.schema,
+    syncInput: form.syncInput,
+    validationMode: form.validationMode
+  });
+  form.bind(runtime);
   formApi.setController(instance.id, form);
   const runtimeControls = {
     close: requestCancel,
@@ -24,6 +32,7 @@ export function useFormOverlayController(instance) {
   };
   formApi.setRuntimeControls(instance.id, runtimeControls);
   onBeforeUnmount(() => {
+    form.unbind(runtime);
     formApi.removeController(instance.id, form);
     formApi.removeRuntimeControls(instance.id, runtimeControls);
   });
@@ -85,6 +94,7 @@ export function useFormOverlayController(instance) {
     handleSubmitted,
     open,
     resolveAfterClose,
+    runtime,
     title
   };
 }

package/dist/runtime/form/composables/use-form-root.d.ts

@@ -1,7 +1,9 @@
-import type { FormObject, FormRendererController, FormSubmitHandlerResult, FormUiConfig, FormValidationMode, FormValue } from '../types/index.js';
+import type { FormObject, FormRendererController, FormRuntime, FormSubmitHandlerResult, FormUiConfig, FormValidationMode, FormValue } from '../types/index.js';
 export interface UseFormRootParams {
     /** Controller from `useForm`. Its schema, input, and policies win over the direct ones. */
     form: () => FormRendererController | undefined;
+    /** Runtime owned by a parent. The root renders it and neither creates, binds nor disposes it. */
+    runtime?: () => FormRuntime | undefined;
     schema: () => FormValue;
     input: () => FormObject | undefined;
     syncInput: () => boolean | readonly string[] | undefined;
@@ -27,7 +29,7 @@ export declare function useFormRoot(params: UseFormRootParams): {
     };
     input: import("vue").ComputedRef<import("../../shared/index.js").GenericObject | undefined>;
     refreshContext: () => Promise<void>;
-    runtime: import("../types/index.js").FormRuntime;
+    runtime: FormRuntime;
     schema: import("vue").ComputedRef<{}>;
     submit: () => Promise<void>;
     validationMode: import("vue").ComputedRef<FormValidationMode>;

package/dist/runtime/form/composables/use-form-root.js

@@ -34,17 +34,20 @@ export function useFormRoot(params) {
   const validationMode = computed(
     () => params.form()?.validationMode.value ?? params.validate() ?? getSchemaValidationMode(schema.value)
   );
-  const runtime = useFormRuntime({ input, schema, syncInput, validationMode });
+  const ownedRuntime = params.runtime?.();
+  const runtime = ownedRuntime ?? useFormRuntime({ input, schema, syncInput, validationMode });
   provideFormRuntime(runtime);
-  watch(
-    params.form,
-    (controller, previousController) => {
-      previousController?.unbind(runtime);
-      controller?.bind(runtime);
-    },
-    { immediate: true }
-  );
-  onBeforeUnmount(() => params.form()?.unbind(runtime));
+  if (!ownedRuntime) {
+    watch(
+      params.form,
+      (controller, previousController) => {
+        previousController?.unbind(runtime);
+        controller?.bind(runtime);
+      },
+      { immediate: true }
+    );
+    onBeforeUnmount(() => params.form()?.unbind(runtime));
+  }
   onMounted(async () => {
     await nextTick();
     const target = getSchemaAutoFocus(schema.value);

package/dist/runtime/form/fields/array-collapse/component.vue

@@ -41,6 +41,7 @@ const {
   itemPath,
   itemRenderKey,
   items,
+  removeItemLabel,
   runCustomAction,
   t,
   title,
@@ -229,7 +230,7 @@ function bodyId(index) {
                 variant="ghost"
                 size="xs"
                 :class="ui?.action"
-                :aria-label="t('form.fields.array.removeItem')"
+                :aria-label="removeItemLabel(item, index)"
                 @click="removeItem(index)"
               />
               <UButton

package/dist/runtime/form/fields/array-list/component.vue

@@ -43,6 +43,7 @@ const {
   itemPath,
   itemRenderKey,
   items,
+  removeItemLabel,
   runCustomAction,
   t,
   title,
@@ -230,7 +231,7 @@ function updateDraggedItems(value) {
                   variant="ghost"
                   size="xs"
                   :class="ui?.action"
-                  :aria-label="t('form.fields.array.removeItem')"
+                  :aria-label="removeItemLabel(item, index)"
                   @click.stop="removeItem(index)"
                 />
               </div>
@@ -291,76 +292,84 @@ function updateDraggedItems(value) {
       handle=".array-drag-handle"
       :animation="150"
     >
-      <div
-        v-for="(item, index) in items"
-        :key="itemRenderKey(item, index)"
-        :class="[
+      <TransitionGroup
+        enter-active-class="transition duration-200 ease-out motion-reduce:transition-none"
+        enter-from-class="translate-y-1 opacity-0"
+        leave-active-class="transition duration-150 ease-in motion-reduce:transition-none"
+        leave-to-class="scale-[0.98] opacity-0"
+      >
+        <div
+          v-for="(item, index) in items"
+          :key="itemRenderKey(item, index)"
+          :class="[
   mergeFormUiClass('grid rounded-lg border border-default bg-default', ui?.item),
   fieldProps.compact ? 'gap-3 p-3' : 'gap-4 p-4'
 ]"
-      >
-        <div :class="mergeFormUiClass('flex items-center justify-between gap-3', ui?.itemHeader)">
-          <span
-            :class="mergeFormUiClass('text-sm font-medium text-highlighted', ui?.itemTitle)"
-            :data-form-array-heading="index"
-          >
-            {{ itemHeading(items[index] ?? {}, index) }}
-          </span>
-          <div :class="mergeFormUiClass('flex items-center gap-1', ui?.itemActions)">
-            <UButton
-              v-if="isDraggable"
-              icon="i-lucide-grip-vertical"
-              color="neutral"
-              variant="ghost"
-              size="xs"
-              :class="mergeFormUiClass('array-drag-handle cursor-grab', ui?.action)"
-              :aria-label="t('form.fields.array.dragItem')"
-            />
-            <UButton
-              v-if="canDelete(index)"
-              icon="i-lucide-trash-2"
-              color="neutral"
-              variant="ghost"
-              size="xs"
-              :class="ui?.action"
-              :aria-label="t('form.fields.array.removeItem')"
-              @click="removeItem(index)"
-            />
-            <UButton
-              v-for="(action, actionIndex) in field.actions?.custom ?? []"
-              v-show="customActionVisible(index, actionIndex)"
-              :key="actionIndex"
-              :icon="action.icon"
-              color="neutral"
-              variant="ghost"
-              size="xs"
-              :class="ui?.action"
-              @click="runCustomAction(index, actionIndex)"
+          :data-form-array-item="index"
+        >
+          <div :class="mergeFormUiClass('flex items-center justify-between gap-3', ui?.itemHeader)">
+            <span
+              :class="mergeFormUiClass('text-sm font-medium text-highlighted', ui?.itemTitle)"
+              :data-form-array-heading="index"
             >
-              {{ resolveFormText(action.label) }}
-            </UButton>
+              {{ itemHeading(items[index] ?? {}, index) }}
+            </span>
+            <div :class="mergeFormUiClass('flex items-center gap-1', ui?.itemActions)">
+              <UButton
+                v-if="isDraggable"
+                icon="i-lucide-grip-vertical"
+                color="neutral"
+                variant="ghost"
+                size="xs"
+                :class="mergeFormUiClass('array-drag-handle cursor-grab', ui?.action)"
+                :aria-label="t('form.fields.array.dragItem')"
+              />
+              <UButton
+                v-if="canDelete(index)"
+                icon="i-lucide-trash-2"
+                color="neutral"
+                variant="ghost"
+                size="xs"
+                :class="ui?.action"
+                :aria-label="removeItemLabel(items[index] ?? {}, index)"
+                @click="removeItem(index)"
+              />
+              <UButton
+                v-for="(action, actionIndex) in field.actions?.custom ?? []"
+                v-show="customActionVisible(index, actionIndex)"
+                :key="actionIndex"
+                :icon="action.icon"
+                color="neutral"
+                variant="ghost"
+                size="xs"
+                :class="ui?.action"
+                @click="runCustomAction(index, actionIndex)"
+              >
+                {{ resolveFormText(action.label) }}
+              </UButton>
+            </div>
           </div>
-        </div>
-
-        <USelect
-          v-if="field.type === 'array-variant'"
-          :model-value="variantValue(items[index])"
-          :items="variantItems"
-          value-key="value"
-          :size="formUi.controlSize.value"
-          :class="mergeFormUiClass('w-full max-w-xs', ui?.variant)"
-          @update:model-value="updateVariant(index, $event)"
-        />
 
-        <div :class="mergeFormUiClass('grid', ui?.fields)" :style="containerLayout.style.value">
-          <FormFieldRenderer
-            v-for="child in fieldsForItem(items[index] ?? {})"
-            :key="child.key"
-            :field="child"
-            :parent-path="itemPath(index)"
+          <USelect
+            v-if="field.type === 'array-variant'"
+            :model-value="variantValue(items[index])"
+            :items="variantItems"
+            value-key="value"
+            :size="formUi.controlSize.value"
+            :class="mergeFormUiClass('w-full max-w-xs', ui?.variant)"
+            @update:model-value="updateVariant(index, $event)"
           />
+
+          <div :class="mergeFormUiClass('grid', ui?.fields)" :style="containerLayout.style.value">
+            <FormFieldRenderer
+              v-for="child in fieldsForItem(items[index] ?? {})"
+              :key="child.key"
+              :field="child"
+              :parent-path="itemPath(index)"
+            />
+          </div>
         </div>
-      </div>
+      </TransitionGroup>
     </component>
 
     <UButton

package/dist/runtime/form/fields/array-list/use-array-items.d.ts

@@ -42,6 +42,7 @@ export declare function useFormArrayItems(field: () => FormArrayItemsField, path
     itemRenderKey: (item: FormObject, index: number) => string;
     items: import("vue").ComputedRef<readonly import("../../../shared/index.js").GenericObject[]>;
     removeItem: (index: number) => boolean;
+    removeItemLabel: (item: FormObject, index: number) => string;
     resolveAction: (action: FormArrayAction | undefined, index: number) => (import("./types.js").FormArrayActionCondition<{}, {}> | undefined) & boolean;
     runCustomAction: (index: number, actionIndex: number) => Promise<void>;
     t: import("../../../i18n/index.js").UiToolsTranslator;

package/dist/runtime/form/fields/array-list/use-array-items.js

@@ -106,6 +106,9 @@ export function useFormArrayItems(field, path) {
   function itemHeading(item, index) {
     return resolveFormText(field().headerTemplate?.(item, index, actionParams(index).deps)) ?? `${itemLabel.value} ${index + 1}`;
   }
+  function removeItemLabel(item, index) {
+    return t("form.fields.array.removeNamedItem", { item: itemHeading(item, index) });
+  }
   function resolveAction(action, index) {
     const condition = isArrayActionConfig(action) ? action.condition : action;
     if (isBoolean(condition)) {
@@ -239,6 +242,7 @@ export function useFormArrayItems(field, path) {
     itemRenderKey,
     items,
     removeItem,
+    removeItemLabel,
     resolveAction,
     runCustomAction,
     t,

package/dist/runtime/form/fields/array-table/component.vue

@@ -41,6 +41,7 @@ const {
   itemRenderKey,
   items,
   removeItem,
+  removeItemLabel,
   runCustomAction,
   t,
   title,
@@ -208,7 +209,7 @@ function fieldLabel(field) {
                   variant="ghost"
                   size="xs"
                   :class="ui?.action"
-                  :aria-label="t('form.fields.array.removeItem')"
+                  :aria-label="removeItemLabel(item, index)"
                   @click="removeItem(index)"
                 />
                 <UButton

package/dist/runtime/form/types/api.d.ts

@@ -1,4 +1,4 @@
-import type { NestedPaths } from '../../shared/types/utils.js';
+import type { DecrementDepth } from '../../shared/types/utils.js';
 import type { FormValue } from './/index.js';
 import type { FormContextData } from './context.js';
 import type { FormMaybePromise, FormObject } from './utils.js';
@@ -170,10 +170,17 @@ export interface FormFieldApi<TValue = FormValue, TOption = FormValue, TContext
     /** Focuses the mounted control for this field when it has a focusable input. */
     focus: () => Promise<boolean>;
 }
+/**
+ * Dot path into submitted output. Array items are addressed by index (`contacts.0.email`); the
+ * unindexed form (`contacts.email`) stays accepted.
+ */
+type FormOutputPath<T, MaxDepth extends number = 10> = [MaxDepth] extends [0] ? never : T extends readonly (infer TItem)[] ? `${number}` | `${number}.${FormOutputPath<TItem, DecrementDepth<MaxDepth>>}` | FormOutputPath<TItem, DecrementDepth<MaxDepth>> : T extends object ? {
+    [K in keyof T & string]: `${K}` | `${K}.${FormOutputPath<T[K], DecrementDepth<MaxDepth>>}`;
+}[keyof T & string] : never;
 /**
  * Public form API available from form-level callbacks.
  */
-export type FormFieldPath<TOutput = FormObject> = TOutput extends FormObject ? FormObject extends TOutput ? string : NestedPaths<TOutput> : string;
+export type FormFieldPath<TOutput = FormObject> = TOutput extends FormObject ? FormObject extends TOutput ? string : FormOutputPath<TOutput> : string;
 export interface FormApi<TOutput = FormObject> {
     /** Reads an internal form value by raw path. */
     get: (path: string) => FormValue;
@@ -212,3 +219,4 @@ export interface FormSubmitHandlerResult<TSubmitData = FormValue> {
     success: boolean;
     data?: TSubmitData;
 }
+export {};

package/dist/runtime/i18n/locales/en.js

@@ -229,6 +229,7 @@ export default defineUiToolsLocale({
           expand: "Expand",
           item: "Item",
           removeItem: "Remove item",
+          removeNamedItem: "Remove {item}",
           unique: "This value is already in the list"
         },
         color: {

package/dist/runtime/i18n/locales/fr.js

@@ -229,6 +229,7 @@ export default defineUiToolsLocale({
           expand: "D\xE9plier",
           item: "\xC9l\xE9ment",
           removeItem: "Supprimer l\u2019\xE9l\xE9ment",
+          removeNamedItem: "Supprimer {item}",
           unique: "Cette valeur est d\xE9j\xE0 dans la liste"
         },
         color: {

package/dist/runtime/i18n/types.d.ts

@@ -355,6 +355,7 @@ export interface UiToolsFormMessages {
         array: {
             addItem: string;
             removeItem: string;
+            removeNamedItem: string;
             dragItem: string;
             editItem: string;
             confirmDelete: string;

package/dist/runtime/shared/types/query.d.ts

@@ -1,4 +1,5 @@
-import type { QueryFunction, QueryKey, QueryOptions, UseQueryOptions } from '@tanstack/vue-query';
+import type { DataTag, QueryFunction, QueryKey, UseQueryOptions } from '@tanstack/vue-query';
+import type { UnwrapRef } from 'vue';
 /**
  * TanStack query definition accepted by runtime domains that own the `useQuery` call themselves
  * (table sources, dashboard queries): an explicit `queryKey`, an optional `queryFn`, and any other
@@ -16,7 +17,16 @@ export interface QueryFnDefinition<TData = unknown> {
     queryKey: QueryKey;
     queryFn: QueryFunction<TData, QueryKey, string | null>;
 }
-/** Data returned by a query function, including generated options whose function may be a ref. */
+type FunctionResult<TFunction> = TFunction extends (...args: never[]) => infer TResult ? TResult : never;
+type QueryFnResult<TQuery> = TQuery extends {
+    queryFn?: infer TQueryFn;
+} ? Awaited<FunctionResult<UnwrapRef<Exclude<TQueryFn, undefined>>>> : never;
+/**
+ * Data returned by a query definition. A tagged `queryKey` (TanStack `queryOptions`, generated
+ * clients such as Tuyau) gives the data even when the options are ref-wrapped; otherwise the
+ * `queryFn` result is used, unwrapping a ref and ignoring `skipToken`.
+ */
 export type QueryFunctionResult<TQuery> = TQuery extends {
-    queryFn: (...args: never[]) => infer TResult;
-} ? Awaited<TResult> : TQuery extends QueryOptions<infer TQueryFnData, infer _TError, infer _TData, infer _TQueryData, infer _TQueryKey> ? Awaited<TQueryFnData> : TQuery extends UseQueryOptions<infer _TQueryFnData, infer _TError, infer TData, infer _TQueryData, infer _TQueryKey> ? Awaited<TData> : never;
+    queryKey: DataTag<QueryKey, infer TTagged, infer _TError>;
+} ? TTagged : QueryFnResult<TQuery>;
+export {};

package/dist/runtime/table/composables/use-table-actions.d.ts

@@ -21,7 +21,7 @@ export declare function useTableActions(options: UseTableActionsParams): {
     actions: ComputedRef<TableActionController[]>;
     bulkActions: ComputedRef<TableActionController[]>;
     definitions: ComputedRef<TableActionDefinition[]>;
-    execute: (definition: TableActionDefinition) => Promise<void>;
+    execute: (definition: TableActionDefinition) => Promise<boolean>;
     runningKeys: import("vue").Ref<string[], string[]>;
     toolbarActions: ComputedRef<TableActionController[]>;
 };

package/dist/runtime/table/composables/use-table-actions.js

@@ -1,4 +1,5 @@
 import { computed, ref } from "vue";
+import { isRecord } from "../../shared/utils/path.js";
 import { isFunction } from "../../shared/utils/predicate.js";
 import { resolveTableActionDefinitions } from "../utils/actions.js";
 export function useTableActions(options) {
@@ -46,10 +47,10 @@ export function useTableActions(options) {
   async function execute(definition) {
     const state = resolveState(definition);
     if (!state.visible || state.disabled || state.loading || state.running) {
-      return;
+      return false;
     }
     if (!definition.action) {
-      return;
+      return false;
     }
     const actionContext = context.value;
     runningKeys.value = [...runningKeys.value, definition.key];
@@ -58,10 +59,14 @@ export function useTableActions(options) {
       selectionApi.clear();
     }
     try {
-      await definition.action(actionContext);
+      const result = await definition.action(actionContext);
+      if (isFailedActionResult(result)) {
+        return false;
+      }
       if (selectionClear === "success") {
         selectionApi.clear();
       }
+      return true;
     } finally {
       runningKeys.value = runningKeys.value.filter((key) => key !== definition.key);
     }
@@ -111,6 +116,9 @@ function resolveFlag(value, context) {
 function isBooleanResolver(value) {
   return isFunction(value);
 }
+function isFailedActionResult(result) {
+  return result === false || isRecord(result) && result.success === false;
+}
 function toPlainRecord(value) {
   return Object.fromEntries(Object.entries(value));
 }

package/dist/runtime/table/composables/use-table-internals.d.ts

@@ -22,7 +22,7 @@ declare function createTableInternals<TSchema>(options: {
             [x: string]: unknown;
         }, {
             [x: string]: unknown;
-        }>) => Promise<void>;
+        }>) => Promise<boolean>;
         runningKeys: import("vue").Ref<string[], string[]>;
         toolbarActions: import("vue").ComputedRef<import("./use-table-actions.js").TableActionController[]>;
     };
@@ -618,7 +618,7 @@ declare function useProvideTableInternals<TSchema>(options: {
             [x: string]: unknown;
         }, {
             [x: string]: unknown;
-        }>) => Promise<void>;
+        }>) => Promise<boolean>;
         runningKeys: import("vue").Ref<string[], string[]>;
         toolbarActions: import("vue").ComputedRef<import("./use-table-actions.js").TableActionController[]>;
     };
@@ -1211,7 +1211,7 @@ declare function useTableInternals(): {
             [x: string]: unknown;
         }, {
             [x: string]: unknown;
-        }>) => Promise<void>;
+        }>) => Promise<boolean>;
         runningKeys: import("vue").Ref<string[], string[]>;
         toolbarActions: import("vue").ComputedRef<import("./use-table-actions.js").TableActionController[]>;
     };

package/dist/runtime/table/types/actions.d.ts

@@ -18,10 +18,16 @@ export interface TableToolbarAction<TRow extends GenericObject = GenericObject,
     condition?: boolean | ((context: TContext) => boolean);
     disabled?: boolean | ((context: TableActionContext<TRow, TContext, TPageContext>) => boolean);
     loading?: boolean | ((context: TableActionContext<TRow, TContext, TPageContext>) => boolean);
+    /**
+     * Runs the action. Returning `false` or `{ success: false }` marks the run as failed without
+     * throwing, like a form submit handler: the selection is kept and `execute()` resolves `false`.
+     * A rejection also keeps the selection and propagates to the caller.
+     */
     action?: (context: TableActionContext<TRow, TContext, TPageContext>) => MaybePromise<unknown>;
 }
 export interface TableBulkAction<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TPageContext extends GenericObject = GenericObject> extends TableToolbarAction<TRow, TContext, TPageContext> {
     requiresSelection?: boolean;
+    /** When the selection clears: before the action runs, after it succeeds, or never. */
     selectionClear?: 'trigger' | 'success' | 'never';
 }
 /** Runtime state exposed for a configured toolbar or bulk action. */
@@ -42,7 +48,8 @@ export interface TableActionSlotProps<TRow extends GenericObject = GenericObject
     state: TableActionState;
     running: boolean;
     selection: TableApi['selection'];
-    execute: () => Promise<void>;
+    /** Runs the action and resolves `true` when it ran and succeeded. */
+    execute: () => Promise<boolean>;
 }
 export interface TableRowActionContext<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TPageContext extends GenericObject = GenericObject> extends TableRowRenderParams<TRow, TContext, TPageContext> {
     layout: TableLayout;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-tools",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "Nuxt module and runtime toolkit for UI-heavy Nuxt applications",
   "homepage": "https://github.com/ChronicStone/nuxt-ui-tools#readme",
   "bugs": "https://github.com/ChronicStone/nuxt-ui-tools/issues",