nuxt-ui-tools 1.6.5 → 1.8.0

package/dist/runtime/form/fields/array-table/array-table-cell.vue.d.ts

@@ -0,0 +1,15 @@
+import type { FormField } from '../../types/index.js';
+/**
+ * One editable cell of an array table. An invalid cell highlights its control through the Nuxt UI
+ * form field context and shows its message in a tooltip on hover, kept open while the cell has
+ * focus, instead of pushing text under the control. Only invalid cells mount a tooltip, so large
+ * tables stay cheap to render. The cell positions the visually hidden message, which would
+ * otherwise escape the table's scroll containers and stretch the document.
+ */
+type __VLS_Props = {
+    field: FormField;
+    itemPath: readonly string[];
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -2,16 +2,18 @@
 import UButton from "@nuxt/ui/components/Button.vue";
 import UIcon from "@nuxt/ui/components/Icon.vue";
 import { useScrollShadow } from "@nuxt/ui/composables/useScrollShadow";
+import { useElementSize } from "@vueuse/core";
 import { computed, defineAsyncComponent, ref } from "vue";
-import FormFieldError from "../../components/renderer/form-field-error.vue";
-import FormFieldRenderer from "../../components/renderer/form-field-renderer.vue";
 import { useResolvedFieldProps } from "../../composables/use-field-control";
 import { isRecord } from "../../utils/path";
 import { isNumber, isString } from "../../utils/predicate";
 import { resolveFormText } from "../../utils/text";
 import { mergeFormUiClass } from "../../utils/ui";
 import { useFormArrayItems } from "../array-list/use-array-items";
+import ArrayTableCell from "./array-table-cell.vue";
 const DEFAULT_COLUMN_MIN_WIDTH = "140px";
+const ACTION_BUTTON_WIDTH = 24;
+const ACTIONS_CELL_INSET = 14;
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
@@ -49,6 +51,7 @@ const {
 );
 const viewportRef = ref(null);
 const viewportShadow = useScrollShadow(viewportRef, { orientation: "horizontal", size: 20 });
+const { width: viewportWidth } = useElementSize(viewportRef);
 const ui = computed(() => formUi.ui.value.arrayTable?.ui);
 const columns = computed(
   () => props.field.fields.filter((field) => field.type !== "hidden" && field.ignore !== true)
@@ -65,6 +68,19 @@ const showActionsColumn = computed(
     (_item, index) => isDraggable.value || canDelete(index) || hasCustomActions(index)
   )
 );
+const pinnedStyle = computed(
+  () => viewportWidth.value > 0 ? { width: `${viewportWidth.value}px` } : void 0
+);
+const actionsStyle = computed(() => {
+  const buttons = Math.max(0, ...items.value.map((_item, index) => rowActionCount(index)));
+  return buttons ? { width: `${buttons * ACTION_BUTTON_WIDTH + ACTIONS_CELL_INSET}px` } : void 0;
+});
+function rowActionCount(index) {
+  const custom = (props.field.actions?.custom ?? []).filter(
+    (_action, actionIndex) => customActionVisible(index, actionIndex)
+  );
+  return Number(isDraggable.value) + Number(canDelete(index)) + custom.length;
+}
 function columnStyle(field) {
   const layout = Object.getOwnPropertyDescriptor(field, "layout")?.value;
   const width = isRecord(layout) ? layout.width : void 0;
@@ -127,6 +143,7 @@ function fieldLabel(field) {
               <th
                 v-if="showActionsColumn"
                 scope="col"
+                :style="actionsStyle"
                 :class="
   mergeFormUiClass(
     'sticky right-0 w-px border-b border-l border-default bg-elevated px-1.5 py-2 shadow-[-8px_0_12px_-10px_rgba(0,0,0,0.45)]',
@@ -159,15 +176,7 @@ function fieldLabel(field) {
                 :key="column.key"
                 :class="mergeFormUiClass('border-r border-default p-1.5 last:border-r-0', ui?.cell)"
               >
-                <div
-                  :class="mergeFormUiClass('flex w-full items-center [&>*]:w-full', ui?.control)"
-                >
-                  <FormFieldRenderer :field="column" :parent-path="itemPath(index)" bare />
-                </div>
-                <FormFieldError
-                  :path="[...itemPath(index), column.key]"
-                  :class="mergeFormUiClass('mt-1 px-2.5 text-xs text-error', ui?.error)"
-                />
+                <ArrayTableCell :field="column" :item-path="itemPath(index)" />
               </td>
               <td
                 v-if="showActionsColumn"
@@ -218,11 +227,16 @@ function fieldLabel(field) {
               </td>
             </tr>
             <tr v-if="items.length === 0">
-              <td
-                :colspan="columns.length + (showActionsColumn ? 1 : 0)"
-                :class="mergeFormUiClass('px-3 py-10 text-center text-muted', ui?.empty)"
-              >
-                {{ emptyLabel }}
+              <td :colspan="columns.length + (showActionsColumn ? 1 : 0)" class="p-0">
+                <div
+                  :class="
+  mergeFormUiClass('sticky left-0 px-3 py-10 text-center text-muted', ui?.empty)
+"
+                  :style="pinnedStyle"
+                  data-form-array-empty=""
+                >
+                  {{ emptyLabel }}
+                </div>
               </td>
             </tr>
           </component>
@@ -230,22 +244,24 @@ function fieldLabel(field) {
             <tr>
               <td
                 :colspan="columns.length + (showActionsColumn ? 1 : 0)"
-                :class="mergeFormUiClass('border-t border-default p-1.5', ui?.addCell)"
+                :class="mergeFormUiClass('border-t border-default p-0', ui?.addCell)"
               >
-                <button
-                  type="button"
-                  :class="
+                <div class="sticky left-0 p-1.5" :style="pinnedStyle">
+                  <button
+                    type="button"
+                    :class="
   mergeFormUiClass(
     'flex w-full items-center justify-center gap-2 rounded-md border border-dashed border-default px-3 py-2 text-sm text-muted transition-colors hover:border-inverted/40 hover:bg-elevated/50 hover:text-default focus-visible:outline-2 focus-visible:outline-primary',
     ui?.add
   )
 "
-                  :data-form-array-add="path.join('.')"
-                  @click="addItem()"
-                >
-                  <UIcon name="i-lucide-plus" class="size-4" aria-hidden="true" />
-                  <span>{{ addItemLabel }}</span>
-                </button>
+                    :data-form-array-add="path.join('.')"
+                    @click="addItem()"
+                  >
+                    <UIcon name="i-lucide-plus" class="size-4" aria-hidden="true" />
+                    <span>{{ addItemLabel }}</span>
+                  </button>
+                </div>
               </td>
             </tr>
           </tfoot>

package/dist/runtime/form/fields/choice-card/use-choice-card.js

@@ -32,6 +32,9 @@ export function useChoiceCard(params) {
         corner.value ? "relative" : void 0,
         current?.item
       ),
+      // The card label renders the option icon itself (inline or as a tile): Nuxt UI's own copy
+      // would show it twice.
+      icon: mergeFormUiClass("hidden", current?.icon),
       // A tile stacks above the title, and the description below it, with gaps.
       label: mergeFormUiClass(
         tile.value ? "flex flex-col items-start gap-2.5 font-semibold" : void 0,
@@ -39,7 +42,7 @@ export function useChoiceCard(params) {
       ),
       // A hidden indicator centers the text: keep it aligned, and clear of an inline corner check.
       wrapper: mergeFormUiClass(
-        tile.value ? "flex flex-col gap-1.5" : void 0,
+        tile.value ? "flex flex-col items-start gap-1.5" : void 0,
         [
           indicator.value === "hidden" ? "ms-0 text-start" : "",
           corner.value && !tile.value ? "pe-7" : ""

package/dist/runtime/form/fields/date/types.d.ts

@@ -13,4 +13,9 @@ export interface FormDateProps {
     calendar?: FormDateFamilyCalendarOptions;
 }
 export type FormDateField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> = FormStatefulFieldBase<'date', Date | string | null, TContext, TDeps, FormDateProps>;
-export type DateFieldOutput = Date | string | NullableValue;
+/** A date field submits its canonical `YYYY-MM-DD` value, or a `Date` with `outputFormat: 'date'`. */
+export type DateFieldOutput<TField> = TField extends {
+    props: {
+        outputFormat: 'date';
+    };
+} ? Date | NullableValue : string | NullableValue;

package/dist/runtime/form/fields/date-family/component.vue

@@ -102,7 +102,13 @@ const placeholder = computed(() => {
   if (explicitlyConfigured !== void 0) {
     return fieldPlaceholder.value;
   }
-  return manualInput.value.placeholder ?? dateManualPlaceholder(manualFormat.value, isRange.value);
+  return manualInput.value.placeholder ?? dateManualPlaceholder(manualFormat.value, isRange.value, {
+    day: t("form.fields.date.tokens.day"),
+    hour: t("form.fields.date.tokens.hour"),
+    minute: t("form.fields.date.tokens.minute"),
+    month: t("form.fields.date.tokens.month"),
+    year: t("form.fields.date.tokens.year")
+  });
 });
 const previewValue = computed(() => {
   if (!isRange.value) {

package/dist/runtime/form/fields/date-family/utils.d.ts

@@ -13,7 +13,14 @@ export declare function isDateFamilyRange(type: FormDateFamilyType): type is "da
 export declare function hasDateFamilyTime(type: FormDateFamilyType): type is "datetime" | "datetimerange";
 export declare function dateFamilyCalendarType(type: FormDateFamilyType): 'date' | 'month' | 'year';
 export declare function defaultDateManualFormat(type: FormDateFamilyType, locale: string): string;
-export declare function dateManualPlaceholder(format: string, range: boolean): string;
+export interface DateManualPlaceholderTokens {
+    day: string;
+    month: string;
+    year: string;
+    hour: string;
+    minute: string;
+}
+export declare function dateManualPlaceholder(format: string, range: boolean, tokens?: DateManualPlaceholderTokens): string;
 export declare function applyDateManualMask(value: string, format: string, range: boolean): string;
 export declare function parseDateManualValue(value: string, format: string, type: FormDateFamilyType): string | readonly [string, string] | undefined;
 export declare function formatDateManualValue(values: readonly [string, string], format: string, type: FormDateFamilyType): string;

package/dist/runtime/form/fields/date-family/utils.js

@@ -25,8 +25,16 @@ export function defaultDateManualFormat(type, locale) {
   const dateFormat = locale.toLowerCase().startsWith("fr") ? "dd/MM/yyyy" : "MM/dd/yyyy";
   return hasDateFamilyTime(type) ? `${dateFormat} HH:mm` : dateFormat;
 }
-export function dateManualPlaceholder(format, range) {
-  const placeholder = format.toLowerCase();
+const DATE_PLACEHOLDER_TOKEN = /yyyy|MM|dd|HH|mm/gu;
+export function dateManualPlaceholder(format, range, tokens) {
+  const names = {
+    HH: tokens?.hour,
+    MM: tokens?.month,
+    dd: tokens?.day,
+    mm: tokens?.minute,
+    yyyy: tokens?.year
+  };
+  const placeholder = format.replaceAll(DATE_PLACEHOLDER_TOKEN, (token) => names[token] ?? token.toLowerCase()).toLowerCase();
   return range ? `${placeholder} \u2013 ${placeholder}` : placeholder;
 }
 export function applyDateManualMask(value, format, range) {

package/dist/runtime/form/fields/hidden/types.d.ts

@@ -2,4 +2,11 @@ import type { FormValue } from '../../types/index.js';
 import type { FormStatefulFieldBase } from '../../types/field-base.js';
 import type { FieldDefaultValue, FallbackNever } from '../../types/field-output-utils.js';
 export type FormHiddenField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> = Pick<FormStatefulFieldBase<'hidden', FormValue, TContext, TDeps>, 'key' | 'type' | 'default' | 'dependencies' | 'condition' | 'validation' | 'transform' | 'submit' | 'ignore' | 'watch' | 'watchOptions' | 'onDependencyChange' | 'onRendered' | 'stateEffect'>;
-export type HiddenFieldOutput<TField> = FallbackNever<FieldDefaultValue<TField>, FormValue>;
+type TransformInputResult<TField> = TField extends {
+    transform: {
+        input: (...params: never[]) => infer TResult;
+    };
+} ? TResult : never;
+/** A hidden field holds its default, or what its `transform.input` makes of the input. */
+export type HiddenFieldOutput<TField> = FallbackNever<FieldDefaultValue<TField>, FallbackNever<TransformInputResult<TField>, FormValue>>;
+export {};

package/dist/runtime/form/fields/upload/component.vue

@@ -1,209 +1,88 @@
 <script setup>
-import UAlert from "@nuxt/ui/components/Alert.vue";
-import UButton from "@nuxt/ui/components/Button.vue";
 import UFileUpload from "@nuxt/ui/components/FileUpload.vue";
-import UProgress from "@nuxt/ui/components/Progress.vue";
-import { computed, onScopeDispose, ref } from "vue";
+import { computed, onScopeDispose, shallowRef, useTemplateRef, watch } from "vue";
 import { useUiToolsLocale } from "../../../i18n/use-locale";
 import FormFieldShell from "../../components/renderer/form-field-shell.vue";
-import FormFilePreview from "../../components/utils/form-file-preview.vue";
 import { useFieldControl } from "../../composables/use-field-control";
-import { isObject, isString, isUndefined } from "../../utils/predicate";
 import { resolveFormText } from "../../utils/text";
+import UploadItem from "./upload-item.vue";
+import { useUploadItems } from "./use-upload-items";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
 });
 const { t } = useUiToolsLocale();
-const { fieldProps, form, controlProps, disabled, handleBlur, params, validationPending } = useFieldControl(
+const { api, fieldProps, form, controlProps, disabled, handleBlur, validationPending } = useFieldControl(
   () => props.field,
   () => props.path,
-  { omit: ["dropzoneLabel", "dropzoneDescription", "autoUpload"] }
+  { omit: ["dropzoneLabel", "dropzoneDescription", "autoUpload", "max", "preview"] }
 );
-const selectedFiles = ref(null);
-const uploadPending = ref(false);
-const uploadError = ref(null);
-const uploadProgress = ref(null);
-const uploadRun = ref(0);
-const uploadedValue = computed(() => {
-  const value = form.getValue(props.path);
-  if (isString(value) || value === null) {
-    return value;
-  }
-  if (Array.isArray(value) && value.every((item) => isString(item))) {
-    return value;
-  }
-  if (Array.isArray(value) && value.every(isFormObject)) {
-    return value;
-  }
-  return isFormObject(value) ? value : null;
-});
-const files = computed(() => {
-  if (Array.isArray(selectedFiles.value)) {
-    return selectedFiles.value;
-  }
-  return selectedFiles.value ? [selectedFiles.value] : [];
-});
-const openDialog = ref(null);
-const hasSingleFile = computed(() => {
-  const { value } = selectedFiles;
-  return !fieldProps.value.multiple && value !== null && !Array.isArray(value);
-});
-const dropzoneUi = computed(() => ({
-  ...controlProps.value.ui,
-  base: hasSingleFile.value ? "hidden" : controlProps.value.ui?.base,
-  file: hasSingleFile.value ? "relative inset-auto p-0" : controlProps.value.ui?.file,
-  files: hasSingleFile.value ? "w-full" : "mb-2 gap-2"
-}));
-function captureOpen(open) {
-  openDialog.value = open;
-  return "";
-}
-function replaceFile() {
-  openDialog.value?.();
-}
-async function uploadFiles() {
-  const run = uploadRun.value + 1;
-  uploadRun.value = run;
-  uploadError.value = null;
-  if (!files.value.length) {
-    return;
-  }
-  uploadPending.value = true;
-  try {
-    uploadProgress.value = null;
-    const value = await props.field.upload.handler({
-      ...params.value,
-      files: files.value,
-      onProgress: (percent) => {
-        if (uploadRun.value === run) {
-          uploadProgress.value = Math.min(100, Math.max(0, percent));
-        }
-      }
-    });
-    if (uploadRun.value !== run) {
-      return;
-    }
-    form.setValue(props.path, value);
-    selectedFiles.value = null;
-  } catch (error) {
-    if (uploadRun.value !== run) {
-      return;
-    }
-    uploadError.value = error instanceof Error ? error.message : t("form.fields.upload.failed");
-  } finally {
-    if (uploadRun.value === run) {
-      uploadPending.value = false;
-      uploadProgress.value = null;
-    }
-  }
-}
-async function removeUpload(value) {
-  uploadPending.value = true;
-  try {
-    await props.field.upload.onDelete?.({
-      ...params.value,
-      value: isUndefined(value) ? uploadedValue.value : value
-    });
-    form.setValue(props.path, null);
-    selectedFiles.value = null;
-  } finally {
-    uploadPending.value = false;
-  }
-}
-async function cancelUpload() {
-  uploadRun.value += 1;
-  uploadPending.value = false;
-}
-async function retryUpload() {
-  await uploadFiles();
-}
-const unregisterUpload = form.registerFieldUpload(props.path, {
-  cancel: cancelUpload,
-  remove: removeUpload,
-  retry: retryUpload,
-  start: uploadFiles
-});
+const uploads = useUploadItems(
+  () => props.field,
+  () => props.path
+);
+const picker = useTemplateRef("picker");
+const picked = shallowRef(null);
+const compact = computed(
+  () => !uploads.multiple.value && fieldProps.value.variant === "button"
+);
+const unregisterUpload = form.registerFieldUpload(props.path, uploads.runtime);
 onScopeDispose(unregisterUpload);
-function handleFileChange() {
+watch(picked, (value) => {
+  const files = Array.isArray(value) ? value : value ? [value] : [];
+  if (files.length === 0) return;
+  picked.value = uploads.multiple.value ? [] : null;
   void handleBlur();
-  if (fieldProps.value.autoUpload ?? false) {
-    void uploadFiles();
+  uploads.select(files);
+});
+watch(
+  () => uploads.runtime.pending(),
+  (pending) => {
+    if (!pending) api.value.validation.clearError();
   }
-}
-function isFormObject(value) {
-  return isObject(value) && value !== null && !Array.isArray(value);
+);
+function replace() {
+  picker.value?.inputRef?.click();
 }
 </script>
 
 <template>
   <FormFieldShell :field="field" :path="path">
-    <div class="grid gap-3">
+    <div class="grid gap-2" :data-form-upload-busy="uploads.busy.value || void 0">
+      <ul
+        v-if="uploads.items.value.length"
+        class="m-0 grid list-none gap-2 p-0"
+        data-form-upload-list=""
+      >
+        <UploadItem
+          v-for="item in uploads.items.value"
+          :key="item.key"
+          :item="item"
+          :compact="compact"
+          :disabled="disabled"
+          :replaceable="!uploads.multiple.value"
+          @open="uploads.open(item.key)"
+          @start="uploads.start(item.key)"
+          @cancel="uploads.cancel(item.key)"
+          @retry="uploads.retry(item.key)"
+          @remove="uploads.remove(item.key)"
+          @replace="replace"
+        />
+      </ul>
       <UFileUpload
-        v-model="selectedFiles"
+        ref="picker"
+        v-model="picked"
         v-bind="controlProps"
-        class="w-full"
+        :class="uploads.canSelect.value ? 'w-full' : 'hidden'"
         :accept="fieldProps.accept"
-        :multiple="fieldProps.multiple"
-        :disabled="disabled || uploadPending || validationPending"
+        :multiple="uploads.multiple.value"
+        :disabled="disabled || validationPending"
         :label="resolveFormText(fieldProps.dropzoneLabel) ?? t('form.fields.file.drop')"
         :description="resolveFormText(fieldProps.dropzoneDescription)"
         :icon="fieldProps.icon"
         :variant="fieldProps.variant"
         :layout="fieldProps.layout"
-        :preview="fieldProps.preview"
-        position="outside"
-        :ui="dropzoneUi"
-        @change="handleFileChange"
-      >
-        <template #files-top="{ open }">
-          <span hidden>{{ captureOpen(open) }}</span>
-        </template>
-        <template #file="{ file, index, removeFile }">
-          <FormFilePreview
-            :file="file"
-            :index="index"
-            :disabled="disabled"
-            :remove-file="removeFile"
-            :replace="fieldProps.multiple ? void 0 : replaceFile"
-          />
-        </template>
-      </UFileUpload>
-      <UProgress
-        v-if="uploadPending && uploadProgress !== null"
-        :model-value="uploadProgress"
-        size="sm"
-        data-form-upload-progress=""
-      />
-
-      <div class="flex flex-wrap items-center gap-2">
-        <UButton
-          icon="i-lucide-upload"
-          :loading="uploadPending"
-          :disabled="disabled || !files.length"
-          @click="uploadFiles"
-        >
-          {{ t("form.fields.upload.upload") }}
-        </UButton>
-        <UButton
-          v-if="uploadedValue"
-          icon="i-lucide-trash-2"
-          color="neutral"
-          variant="soft"
-          :loading="uploadPending"
-          :disabled="disabled"
-          @click="removeUpload"
-        >
-          {{ t("form.fields.upload.remove") }}
-        </UButton>
-      </div>
-
-      <UAlert
-        v-if="uploadError"
-        color="error"
-        variant="soft"
-        icon="i-lucide-circle-alert"
-        :description="uploadError"
+        :preview="false"
       />
     </div>
   </FormFieldShell>

package/dist/runtime/form/fields/upload/types.d.ts

@@ -2,30 +2,95 @@ import type { FormValue } from '../../types/index.js';
 import type { FormFieldCallbackParams } from '../../types/callbacks.js';
 import type { FormStatefulFieldBase } from '../../types/field-base.js';
 import type { FieldProps, NullableValue } from '../../types/field-output-utils.js';
-import type { FormObject, FormText } from '../../types/utils.js';
+import type { FormMaybePromise, FormObject, FormText } from '../../types/utils.js';
+/**
+ * One stored upload value: the URL string or the object returned by the upload handler.
+ */
+export type FormUploadValue = string | FormObject;
 export interface FormUploadCallbackParams<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> extends FormFieldCallbackParams<TContext, TDeps> {
+    /** Files handled by this call. The field calls the handler once per selected file. */
     files: readonly File[];
+    /** Reports the progress of this upload, from `0` to `100`. */
     onProgress: (percent: number) => void;
+    /** Aborted when the user cancels the upload or removes the file while it uploads. */
+    signal: AbortSignal;
+}
+/**
+ * Uploads the selected file and returns the value stored in the form.
+ * When an array is returned for a single file, its first item is stored.
+ */
+export type FormUploadHandler<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> = (params: FormUploadCallbackParams<TContext, TDeps>) => Promise<FormUploadValue | readonly FormUploadValue[] | null>;
+/**
+ * Display data for a stored upload value, used to render files that are already set.
+ */
+export interface FormUploadResolvedFile {
+    /** File name shown in the list. */
+    name: string;
+    /** Size in bytes, shown next to the file type when provided. */
+    size?: number | null;
+    /** MIME type, used for the file icon and image previews. */
+    type?: string | null;
+    /** Link opened by the open action when no `upload.open` hook is configured. */
+    url?: string | null;
+    /** Image preview source. Defaults to `url` for image types. */
+    thumbnail?: string | null;
+    /** Replaces the file type and size line under the name, for example with an upload date. */
+    description?: string | null;
+    /**
+     * Shows the open action for this file. Defaults to `true` when an `upload.open` hook or a
+     * `url` is available.
+     */
+    openable?: boolean;
+}
+export interface FormUploadValueParams<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> extends FormFieldCallbackParams<TContext, TDeps> {
+    /** The stored value being resolved or opened. */
+    value: FormUploadValue;
+}
+export interface FormUploadOpenParams<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> extends FormUploadValueParams<TContext, TDeps> {
+    /** Display data resolved for the stored value. */
+    file: FormUploadResolvedFile;
 }
-export type FormUploadHandler<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> = (params: FormUploadCallbackParams<TContext, TDeps>) => Promise<string | FormObject | readonly string[] | readonly FormObject[] | null>;
 export interface FormUploadDeleteParams<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> extends FormFieldCallbackParams<TContext, TDeps> {
     value: FormValue;
 }
 export interface FormUploadProps {
     multiple?: boolean;
+    /** Maximum number of stored and pending files when `multiple` is enabled. */
+    max?: number;
     accept?: string;
+    /** Uploads files as soon as they are selected. Defaults to `true`. */
     autoUpload?: boolean;
     dropzoneLabel?: FormText;
     dropzoneDescription?: FormText;
     icon?: string | false;
+    /** `button` renders a compact picker, suited to table cells. Ignored when `multiple` is set. */
     variant?: 'area' | 'button';
     layout?: 'list' | 'grid';
+    /** Shows image thumbnails for image files. Defaults to `true`. */
     preview?: boolean;
 }
-export interface FormUploadField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> extends FormStatefulFieldBase<'upload', string | FormObject | readonly string[] | readonly FormObject[] | null, TContext, TDeps, FormUploadProps> {
+export interface FormUploadField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> extends FormStatefulFieldBase<'upload', FormUploadValue | readonly FormUploadValue[] | null, TContext, TDeps, FormUploadProps> {
     output: 'url' | 'object';
     upload: {
         handler: FormUploadHandler<TContext, TDeps>;
+        /**
+         * Resolves display data for a stored value so files that are already set render with
+         * their name, size, and preview. Without it, string values use their last URL segment as
+         * the name and the value as the link; object values read their `name`, `size`, `type`,
+         * `url`, and `thumbnail` keys.
+         *
+         * @example
+         * resolve: async ({ value }) => {
+         *   const file = await api.files.show(String(value))
+         *   return { name: file.name, size: file.size, type: file.mimeType }
+         * }
+         */
+        resolve?: (params: FormUploadValueParams<TContext, TDeps>) => FormMaybePromise<FormUploadResolvedFile | null>;
+        /**
+         * Opens a stored file, for example through a short-lived download link.
+         * Defaults to opening the resolved `url` in a new tab.
+         */
+        open?: (params: FormUploadOpenParams<TContext, TDeps>) => FormMaybePromise<void>;
         onDelete?: (params: FormUploadDeleteParams<TContext, TDeps>) => Promise<void> | void;
     };
 }

package/dist/runtime/form/fields/upload/upload-item.d.vue.ts

@@ -0,0 +1,24 @@
+import type { FormUploadItem } from './use-upload-items.js';
+type __VLS_Props = {
+    item: FormUploadItem;
+    disabled?: boolean;
+    compact?: boolean;
+    replaceable?: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    replace: () => any;
+    retry: () => any;
+    start: () => any;
+    open: () => any;
+    remove: () => any;
+    cancel: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onReplace?: (() => any) | undefined;
+    onRetry?: (() => any) | undefined;
+    onStart?: (() => any) | undefined;
+    onOpen?: (() => any) | undefined;
+    onRemove?: (() => any) | undefined;
+    onCancel?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;