kirby-types 1.4.7 → 1.4.9

package/src/panel/features.d.ts

@@ -32,6 +32,7 @@ import type {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/timer.js
  * @since 4.0.0
+ * @source panel/src/panel/timer.js
  */
 export interface PanelTimer {
   /** Current interval ID, or null if not running */
@@ -46,9 +47,7 @@ export interface PanelTimer {
    */
   start: (timeout: number | false | null, callback: () => void) => void;
 
-  /**
-   * Stops the timer and clears the interval.
-   */
+  /** Stops the timer and clears the interval. */
   stop: () => void;
 }
 
@@ -58,6 +57,7 @@ export interface PanelTimer {
 
 /**
  * Default state for the activation feature.
+ * @source panel/src/panel/activiation.js
  */
 export interface PanelActivationDefaults {
   /** Whether the activation card is visible */
@@ -72,19 +72,16 @@ export interface PanelActivationDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/activiation.js
  * @since 4.0.0
+ * @source panel/src/panel/activiation.js
  */
 export interface PanelActivation extends PanelState<PanelActivationDefaults> {
   /** Whether the activation card is visible */
   isOpen: boolean;
 
-  /**
-   * Closes the activation card and persists state to session storage.
-   */
+  /** Closes the activation card and persists state to session storage. */
   close: () => void;
 
-  /**
-   * Opens the activation card and clears session storage state.
-   */
+  /** Opens the activation card and clears session storage state. */
   open: () => void;
 }
 
@@ -94,6 +91,7 @@ export interface PanelActivation extends PanelState<PanelActivationDefaults> {
 
 /**
  * Default state for drag operations.
+ * @source panel/src/panel/drag.js
  */
 export interface PanelDragDefaults {
   /** Type of item being dragged */
@@ -107,6 +105,7 @@ export interface PanelDragDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/drag.js
  * @since 4.0.0
+ * @source panel/src/panel/drag.js
  */
 export interface PanelDrag extends PanelState<PanelDragDefaults> {
   /** Type of item being dragged */
@@ -125,9 +124,7 @@ export interface PanelDrag extends PanelState<PanelDragDefaults> {
    */
   start: (type: string, data: string | Record<string, any>) => void;
 
-  /**
-   * Stops the current drag operation and resets state.
-   */
+  /** Stops the current drag operation and resets state. */
   stop: () => void;
 }
 
@@ -137,6 +134,7 @@ export interface PanelDrag extends PanelState<PanelDragDefaults> {
 
 /**
  * Default state for theme management.
+ * @source panel/src/panel/theme.js
  */
 export interface PanelThemeDefaults {
   /** User's theme preference from localStorage */
@@ -147,6 +145,7 @@ export interface PanelThemeDefaults {
 
 /**
  * Theme type values.
+ * @source panel/src/panel/theme.js
  */
 export type PanelThemeValue = "light" | "dark" | "system";
 
@@ -158,6 +157,7 @@ export type PanelThemeValue = "light" | "dark" | "system";
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/theme.js
  * @since 5.0.0
+ * @source panel/src/panel/theme.js
  */
 export interface PanelTheme extends Omit<
   PanelState<PanelThemeDefaults>,
@@ -195,6 +195,7 @@ export interface PanelTheme extends Omit<
 
 /**
  * Default state for content language.
+ * @source panel/src/panel/language.js
  */
 export interface PanelLanguageDefaults {
   /** Language code (e.g., `"en"`, `"de"`) */
@@ -203,6 +204,8 @@ export interface PanelLanguageDefaults {
   default: boolean;
   /** Text direction */
   direction: "ltr" | "rtl";
+  /** Whether the language uses a custom domain. */
+  hasCustomDomain: boolean;
   /** Language name */
   name: string | null;
   /** Slug conversion rules */
@@ -216,6 +219,7 @@ export interface PanelLanguageDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/language.js
  * @since 4.0.0
+ * @source panel/src/panel/language.js
  */
 export interface PanelLanguage extends PanelState<PanelLanguageDefaults> {
   /** Language code (e.g., `"en"`, `"de"`) */
@@ -239,6 +243,7 @@ export interface PanelLanguage extends PanelState<PanelLanguageDefaults> {
 
 /**
  * Menu entry types.
+ * @source panel/src/panel/menu.js
  */
 export interface PanelMenuEntry {
   /** Whether this entry is currently active */
@@ -255,6 +260,7 @@ export interface PanelMenuEntry {
 
 /**
  * Default state for the sidebar menu.
+ * @source panel/src/panel/menu.js
  */
 export interface PanelMenuDefaults {
   /** Menu entries (items or separator strings) */
@@ -273,6 +279,7 @@ export interface PanelMenuDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/menu.js
  * @since 4.0.0
+ * @source panel/src/panel/menu.js
  */
 export interface PanelMenu extends Omit<PanelState<PanelMenuDefaults>, "set"> {
   /** Menu entries (items or separator strings) */
@@ -314,14 +321,10 @@ export interface PanelMenu extends Omit<PanelState<PanelMenuDefaults>, "set"> {
    */
   resize: () => void;
 
-  /**
-   * Sets menu entries and handles initial resize.
-   */
+  /** Sets menu entries and handles initial resize. */
   set: (entries: (PanelMenuEntry | "-")[]) => PanelMenuDefaults;
 
-  /**
-   * Toggles the sidebar menu state.
-   */
+  /** Toggles the sidebar menu state. */
   toggle: () => void;
 }
 
@@ -331,6 +334,7 @@ export interface PanelMenu extends Omit<PanelState<PanelMenuDefaults>, "set"> {
 
 /**
  * Default state for notifications.
+ * @source panel/src/panel/notification.js
  */
 export interface PanelNotificationDefaults {
   /** Context where notification appears */
@@ -353,6 +357,7 @@ export interface PanelNotificationDefaults {
 
 /**
  * Options for opening a notification.
+ * @source panel/src/panel/notification.js
  */
 export interface PanelNotificationOptions {
   /** Context where notification appears */
@@ -373,6 +378,7 @@ export interface PanelNotificationOptions {
 
 /**
  * Error object for notifications.
+ * @source panel/src/panel/notification.js
  */
 export interface PanelErrorObject {
   /** Error message */
@@ -391,6 +397,7 @@ export interface PanelErrorObject {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/notification.js
  * @since 4.0.0
+ * @source panel/src/panel/notification.js
  */
 export interface PanelNotification extends PanelState<PanelNotificationDefaults> {
   /** Context where notification appears */
@@ -416,9 +423,7 @@ export interface PanelNotification extends PanelState<PanelNotificationDefaults>
   /** Whether this is a fatal error notification */
   readonly isFatal: boolean;
 
-  /**
-   * Closes the notification and resets state.
-   */
+  /** Closes the notification and resets state. */
   close: () => PanelNotificationDefaults;
 
   /**
@@ -429,9 +434,7 @@ export interface PanelNotification extends PanelState<PanelNotificationDefaults>
   deprecated: (message: string) => void;
 
   /**
-   * Creates an error notification.
-   * Opens error dialog in view context.
-   * May redirect to logout for auth errors.
+   * Always shows the error notification bar; in view context also opens the `k-error-dialog`. Forwards `JsonRequestError` to `fatal()`, unwraps nested `error`/`details` fields from `RequestError` responses, and redirects authenticated users to logout on `AuthError`.
    *
    * @param error - Error object, string, or Error instance
    * @returns Notification state, or void if redirected
@@ -442,11 +445,14 @@ export interface PanelNotification extends PanelState<PanelNotificationDefaults>
 
   /**
    * Creates a fatal error notification.
-   * Displayed in an isolated iframe.
+   * Displayed in an isolated iframe. Also accepts a plain object with
+   * a `message` field via `error.message ?? "Something went wrong"`.
    *
-   * @param error - Error object, string, or Error instance
+   * @param error - Error object, string, or plain `{ message }` object
    */
-  fatal: (error: Error | string) => PanelNotificationDefaults;
+  fatal: (
+    error: Error | string | PanelErrorObject,
+  ) => PanelNotificationDefaults;
 
   /**
    * Creates an info notification.
@@ -456,7 +462,7 @@ export interface PanelNotification extends PanelState<PanelNotificationDefaults>
   info: (info?: string | PanelNotificationOptions) => PanelNotificationDefaults;
 
   /**
-   * Opens a notification with the given options.
+   * Opens a notification. When passed a string, delegates to `success()`. Otherwise sets the panel context, defaults `timeout` to 4000ms for non-error/non-fatal types, opens the notification, and starts the auto-close timer.
    *
    * @param notification - Message string or options object
    */
@@ -480,6 +486,7 @@ export interface PanelNotification extends PanelState<PanelNotificationDefaults>
 
 /**
  * Default state for system information.
+ * @source panel/src/panel/system.js
  */
 export interface PanelSystemDefaults {
   /** ASCII character replacements for slugs */
@@ -503,6 +510,7 @@ export interface PanelSystemDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/system.js
  * @since 4.0.0
+ * @source panel/src/panel/system.js
  */
 export interface PanelSystem extends PanelState<PanelSystemDefaults> {
   /** ASCII character replacements for slugs */
@@ -525,6 +533,7 @@ export interface PanelSystem extends PanelState<PanelSystemDefaults> {
 
 /**
  * Default state for interface translation.
+ * @source panel/src/panel/translation.js
  */
 export interface PanelTranslationDefaults {
   /** Translation code (e.g., `"en"`, `"de"`) */
@@ -547,6 +556,7 @@ export interface PanelTranslationDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/translation.js
  * @since 4.0.0
+ * @source panel/src/panel/translation.js
  */
 export interface PanelTranslation extends PanelState<PanelTranslationDefaults> {
   /** Translation code (e.g., `"en"`, `"de"`) */
@@ -560,9 +570,7 @@ export interface PanelTranslation extends PanelState<PanelTranslationDefaults> {
   /** First day of week (`0`=Sunday, `1`=Monday) */
   weekday: number;
 
-  /**
-   * Sets translation state and updates document language/direction.
-   */
+  /** Sets translation state and updates document language/direction. */
   set: (state: Partial<PanelTranslationDefaults>) => PanelTranslationDefaults;
 
   /**
@@ -586,6 +594,7 @@ export interface PanelTranslation extends PanelState<PanelTranslationDefaults> {
 
 /**
  * Default state for the current user.
+ * @source panel/src/panel/user.js
  */
 export interface PanelUserDefaults {
   /** User email */
@@ -607,6 +616,7 @@ export interface PanelUserDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/user.js
  * @since 4.0.0
+ * @source panel/src/panel/user.js
  */
 export interface PanelUser extends PanelState<PanelUserDefaults> {
   /** User email */
@@ -627,6 +637,7 @@ export interface PanelUser extends PanelState<PanelUserDefaults> {
 
 /**
  * Breadcrumb item for view navigation.
+ * @source panel/src/panel/view.js
  */
 export interface PanelBreadcrumbItem {
   /** Display label */
@@ -637,6 +648,8 @@ export interface PanelBreadcrumbItem {
 
 /**
  * Default state for the view feature.
+ * @source panel/src/panel/view.js
+ * @source panel/src/panel/feature.js
  */
 export interface PanelViewDefaults extends PanelFeatureDefaults {
   /** Breadcrumb navigation items */
@@ -665,6 +678,8 @@ export interface PanelViewDefaults extends PanelFeatureDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/view.js
  * @since 4.0.0
+ * @source panel/src/panel/view.js
+ * @source panel/src/panel/feature.js
  */
 export interface PanelView extends Omit<
   PanelFeature<PanelViewDefaults>,
@@ -687,17 +702,13 @@ export interface PanelView extends Omit<
   /** View title */
   title: string | null;
 
-  /**
-   * Loads a view, canceling any previous request.
-   */
+  /** Loads a view, canceling any previous request. */
   load: (
     url: string | URL,
     options?: PanelRequestOptions | PanelEventCallback,
   ) => Promise<PanelViewDefaults>;
 
-  /**
-   * Sets view state and updates document title and browser URL.
-   */
+  /** Sets view state and updates document title and browser URL. */
   set: (state: Partial<PanelViewDefaults>) => void;
 
   /**
@@ -713,14 +724,15 @@ export interface PanelView extends Omit<
 
 /**
  * Dropdown option item.
+ * @source panel/src/panel/dropdown.js
  */
 export interface PanelDropdownOption {
   /** Option text */
   text: string;
   /** Icon name */
   icon?: string;
-  /** Click handler or link */
-  click?: () => void | string;
+  /** Click handler, or a link string */
+  click?: (() => void) | string;
   /** Whether option is disabled */
   disabled?: boolean;
   /** Additional properties */
@@ -735,11 +747,11 @@ export interface PanelDropdownOption {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/dropdown.js
  * @since 4.0.0
+ * @source panel/src/panel/dropdown.js
+ * @source panel/src/panel/feature.js
  */
 export interface PanelDropdown extends PanelFeature<PanelFeatureDefaults> {
-  /**
-   * Closes the dropdown and resets state.
-   */
+  /** Closes the dropdown and resets state. */
   close: () => void;
 
   /**
@@ -752,23 +764,20 @@ export interface PanelDropdown extends PanelFeature<PanelFeatureDefaults> {
   ) => Promise<PanelFeatureDefaults>;
 
   /**
-   * Opens a dropdown asynchronously.
+   * Opens a dropdown asynchronously and returns a closure that invokes
+   * `ready(items)` with the resolved option list.
    *
    * @deprecated Since 4.0.0 - Use `open()` instead
    */
   openAsync: (
     dropdown: string | URL | Partial<PanelFeatureDefaults>,
     options?: PanelRequestOptions | PanelEventCallback,
-  ) => (ready?: () => void) => Promise<PanelFeatureDefaults>;
+  ) => (ready: (items: PanelDropdownOption[]) => void) => Promise<void>;
 
-  /**
-   * Returns dropdown options array from props.
-   */
+  /** Returns dropdown options array from props. */
   options: () => PanelDropdownOption[];
 
-  /**
-   * Sets dropdown state, handling deprecated responses.
-   */
+  /** Sets dropdown state, handling deprecated responses. */
   set: (state: Partial<PanelFeatureDefaults>) => PanelFeatureDefaults;
 }
 
@@ -778,6 +787,8 @@ export interface PanelDropdown extends PanelFeature<PanelFeatureDefaults> {
 
 /**
  * Default state for the dialog modal.
+ * @source panel/src/panel/dialog.js
+ * @source panel/src/panel/modal.js
  */
 export interface PanelDialogDefaults extends PanelFeatureDefaults {
   /** Unique dialog ID */
@@ -795,6 +806,8 @@ export interface PanelDialogDefaults extends PanelFeatureDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/dialog.js
  * @since 4.0.0
+ * @source panel/src/panel/dialog.js
+ * @source panel/src/panel/modal.js
  */
 export interface PanelDialog extends PanelModal<PanelDialogDefaults> {
   /** Whether using legacy Vue component */
@@ -802,14 +815,10 @@ export interface PanelDialog extends PanelModal<PanelDialogDefaults> {
   /** Reference to legacy component */
   ref: any;
 
-  /**
-   * Closes the dialog, handling legacy components.
-   */
+  /** Closes the dialog, handling legacy components. */
   close: () => Promise<void>;
 
-  /**
-   * Opens a dialog by URL, state object, or legacy component.
-   */
+  /** Opens a dialog by URL, state object, or legacy component. */
   open: (
     dialog:
       | string
@@ -834,6 +843,8 @@ export interface PanelDialog extends PanelModal<PanelDialogDefaults> {
 
 /**
  * Default state for the drawer modal.
+ * @source panel/src/panel/drawer.js
+ * @source panel/src/panel/modal.js
  */
 export interface PanelDrawerDefaults extends PanelFeatureDefaults {
   /** Unique drawer ID */
@@ -847,6 +858,8 @@ export interface PanelDrawerDefaults extends PanelFeatureDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/drawer.js
  * @since 4.0.0
+ * @source panel/src/panel/drawer.js
+ * @source panel/src/panel/modal.js
  */
 export interface PanelDrawer extends PanelModal<PanelDrawerDefaults> {
   /** Breadcrumb from history milestones */
@@ -855,9 +868,7 @@ export interface PanelDrawer extends PanelModal<PanelDrawerDefaults> {
   /** Drawer icon, defaults to `"box"` */
   readonly icon: string;
 
-  /**
-   * Opens a drawer by URL or state object.
-   */
+  /** Opens a drawer by URL or state object. */
   open: (
     drawer: string | URL | Partial<PanelDrawerDefaults>,
     options?: PanelRequestOptions | PanelEventCallback,
@@ -865,15 +876,14 @@ export interface PanelDrawer extends PanelModal<PanelDrawerDefaults> {
 
   /**
    * Switches drawer tabs.
+   * If `tab` is omitted, falls back to the first key of `props.tabs`.
    *
    * @param tab - Tab name to switch to
    * @returns False if no tabs exist, void otherwise
    */
-  tab: (tab: string) => void | false;
+  tab: (tab?: string) => void | false;
 
-  /**
-   * Returns drawer event listeners for Vue component binding.
-   */
+  /** Returns the modal listeners extended with drawer-specific `crumb` (history navigation) and `tab` handlers. */
   listeners: () => PanelModalListeners;
 }
 
@@ -883,6 +893,7 @@ export interface PanelDrawer extends PanelModal<PanelDrawerDefaults> {
 
 /**
  * Content version representing saved or changed state.
+ * @source panel/src/panel/content.js
  */
 export interface PanelContentVersion {
   [field: string]: any;
@@ -890,6 +901,7 @@ export interface PanelContentVersion {
 
 /**
  * Content versions container.
+ * @source panel/src/panel/content.js
  */
 export interface PanelContentVersions {
   /** Original saved content */
@@ -900,6 +912,7 @@ export interface PanelContentVersions {
 
 /**
  * Lock state for content editing.
+ * @source panel/src/panel/content.js
  */
 export interface PanelContentLock {
   /** Whether content is locked by another user */
@@ -914,6 +927,7 @@ export interface PanelContentLock {
 
 /**
  * Environment context for content operations.
+ * @source panel/src/panel/content.js
  */
 export interface PanelContentEnv {
   /** API endpoint path */
@@ -930,6 +944,7 @@ export interface PanelContentEnv {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/content.js
  * @since 5.0.0
+ * @source panel/src/panel/content.js
  */
 export interface PanelContent {
   /** Reference to lock dialog if open */
@@ -938,18 +953,13 @@ export interface PanelContent {
   /** Whether content is being saved/published/discarded */
   isProcessing: boolean;
 
-  /** AbortController for save requests */
-  saveAbortController: AbortController | null;
-
   /** Throttled save function (1000ms) */
   saveLazy: ((
     values?: Record<string, any>,
     env?: PanelContentEnv,
   ) => Promise<void>) & { cancel: () => void };
 
-  /**
-   * Cancels any ongoing or scheduled save requests.
-   */
+  /** Cancels any ongoing or scheduled save requests. */
   cancelSaving: () => void;
 
   /**
@@ -996,7 +1006,7 @@ export interface PanelContent {
   hasDiff: (env?: PanelContentEnv) => boolean;
 
   /**
-   * Whether the API endpoint belongs to the current view.
+   * Whether the given env's `api` and `language` both match the current view.
    *
    * @param env - Environment context
    */
@@ -1095,9 +1105,7 @@ export interface PanelContent {
    */
   version: (versionId: "latest" | "changes") => PanelContentVersion;
 
-  /**
-   * Returns all content versions.
-   */
+  /** Returns all content versions. */
   versions: () => PanelContentVersions;
 }
 
@@ -1107,6 +1115,7 @@ export interface PanelContent {
 
 /**
  * Search pagination info.
+ * @source panel/src/panel/search.js
  */
 export interface PanelSearchPagination {
   page?: number;
@@ -1116,6 +1125,7 @@ export interface PanelSearchPagination {
 
 /**
  * Search query options.
+ * @source panel/src/panel/search.js
  */
 export interface PanelSearchOptions {
   /** Page number */
@@ -1126,6 +1136,7 @@ export interface PanelSearchOptions {
 
 /**
  * Search result from API.
+ * @source panel/src/panel/search.js
  */
 export interface PanelSearchResult {
   /** Result list (null if query too short) */
@@ -1141,6 +1152,7 @@ export interface PanelSearchResult {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/search.js
  * @since 4.4.0
+ * @source panel/src/panel/search.js
  */
 export interface PanelSearcher {
   /** AbortController for current request */
@@ -1160,8 +1172,7 @@ export interface PanelSearcher {
   open: (type?: string) => void;
 
   /**
-   * Queries the search API.
-   * Returns empty results for queries under 2 characters.
+   * Queries the search API. For queries shorter than 2 characters returns `{ results: null, pagination: {} }` without hitting the server. Resolves to `undefined` when the request was aborted by a subsequent search (the catch falls through with no return).
    *
    * @param type - Search type
    * @param query - Search query
@@ -1171,17 +1182,38 @@ export interface PanelSearcher {
     type: string,
     query: string,
     options?: PanelSearchOptions,
-  ) => Promise<PanelSearchResult>;
+  ) => Promise<PanelSearchResult | undefined>;
 }
 
 // -----------------------------------------------------------------------------
 // Upload
 // -----------------------------------------------------------------------------
 
+/**
+ * Server-side file model passed to `PanelUpload.replace()` and stored in
+ * `PanelUploadDefaults.replacing`. Distinct from `PanelUploadFile` (the
+ * client-side queued upload). Carries the fields read by `replace()` to
+ * configure the upload picker (`url`, `accept`).
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/upload.js
+ * @source panel/src/panel/upload.js
+ */
+export interface PanelUploadReplaceFile {
+  /** API path segment used to build the upload URL */
+  link: string;
+  /** File extension without dot, used for the picker `accept` filter */
+  extension: string;
+  /** MIME type, used for the picker `accept` filter */
+  mime: string;
+  /** Additional server-side fields */
+  [key: string]: any;
+}
+
 /**
  * Upload file state representing a file in the upload queue.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/upload.js
+ * @source panel/src/panel/upload.js
  */
 export interface PanelUploadFile {
   /** Unique file ID */
@@ -1214,6 +1246,7 @@ export interface PanelUploadFile {
 
 /**
  * Default state for upload feature.
+ * @source panel/src/panel/upload.js
  */
 export interface PanelUploadDefaults {
   /** AbortController for current upload */
@@ -1230,8 +1263,8 @@ export interface PanelUploadDefaults {
   multiple: boolean;
   /** File preview data */
   preview: Record<string, any>;
-  /** File being replaced */
-  replacing: PanelUploadFile | null;
+  /** Server file model being replaced (carries `link`, `extension`, `mime`). */
+  replacing: PanelUploadReplaceFile | null;
   /** Upload endpoint URL */
   url: string | null;
 }
@@ -1244,6 +1277,7 @@ export interface PanelUploadDefaults {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/upload.js
  * @since 4.0.0
+ * @source panel/src/panel/upload.js
  */
 export interface PanelUpload
   extends PanelState<PanelUploadDefaults>, PanelEventListeners {
@@ -1261,47 +1295,41 @@ export interface PanelUpload
   multiple: boolean;
   /** File preview data */
   preview: Record<string, any>;
-  /** File being replaced */
-  replacing: PanelUploadFile | null;
+  /** Server file model being replaced (see `PanelUploadDefaults.replacing`) */
+  replacing: PanelUploadReplaceFile | null;
   /** Upload endpoint URL */
   url: string | null;
 
   /** Hidden file input element */
   input: HTMLInputElement | null;
 
-  /** Files that completed uploading */
-  readonly completed: PanelUploadFile[];
+  /** Server file models for files that completed uploading. */
+  readonly completed: any[];
 
-  /**
-   * Shows success notification and emits model.update.
-   */
+  /** Shows success notification and emits model.update. */
   announce: () => void;
 
-  /**
-   * Cancels current upload and resets state.
-   */
+  /** Emits `cancel`, aborts any ongoing upload, and if some files already finished emits `complete` and announces success before resetting state. */
   cancel: () => Promise<void>;
 
-  /**
-   * Called when upload dialog submit clicked.
-   */
+  /** Closes the upload dialog after all remaining files have uploaded; if any files completed, emits `complete` and `done`, announces success, and resets state. */
   done: () => Promise<void>;
 
   /**
-   * Finds duplicate file by comparing properties.
-   * Returns the index of the duplicate file, or false if not found.
+   * Finds the index of an existing file in the queue with the same `src.name`, `src.type`, `src.size`, and `src.lastModified`. Returns the matching index, or `-1` if no duplicate is found.
    *
-   * @param file - File to check
-   * @returns Index of duplicate file or false
+   * @param file - Enriched upload file to check
+   * @returns Index of the duplicate file, or `-1` if none
    */
-  findDuplicate: (file: File) => number | false;
+  findDuplicate: (file: PanelUploadFile) => number;
 
   /**
    * Checks if file has a unique name.
+   * Compares `file.name` and `file.extension` against the upload queue.
    *
-   * @param file - File to check
+   * @param file - Enriched upload file to check
    */
-  hasUniqueName: (file: File) => boolean;
+  hasUniqueName: (file: PanelUploadFile) => boolean;
 
   /**
    * Converts File to enriched upload file object.
@@ -1337,34 +1365,33 @@ export interface PanelUpload
 
   /**
    * Opens picker to replace an existing file.
+   * The `file` argument is a server file model (reads `file.link`,
+   * `file.extension`, `file.mime`), not a queued `PanelUploadFile`.
    *
-   * @param file - File to replace
+   * @param file - Server file model being replaced
    * @param options - Upload options
    */
   replace: (
-    file: PanelUploadFile,
+    file: PanelUploadReplaceFile,
     options?: Partial<PanelUploadDefaults>,
   ) => void;
 
   /**
    * Adds files to upload list with deduplication.
+   * Also accepts an `Event` whose `target.files` is unwrapped to a `FileList`.
    *
-   * @param files - Files to add
+   * @param files - Files to add (or input change Event)
    * @param options - Upload options
    */
   select: (
-    files: File[] | FileList,
+    files: File[] | FileList | Event,
     options?: Partial<PanelUploadDefaults>,
   ) => void;
 
-  /**
-   * Sets state and registers event listeners.
-   */
+  /** Sets state and registers event listeners. */
   set: (state: Partial<PanelUploadDefaults>) => PanelUploadDefaults;
 
-  /**
-   * Submits and uploads all remaining files.
-   */
+  /** Submits and uploads all remaining files. */
   submit: () => Promise<void>;
 
   /**
@@ -1385,6 +1412,7 @@ export interface PanelUpload
 
 /**
  * Event emitter interface (mitt-compatible).
+ * @source panel/src/panel/events.js
  */
 export interface PanelEventEmitter {
   emit: (event: string, ...args: any[]) => void;
@@ -1400,6 +1428,7 @@ export interface PanelEventEmitter {
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/events.js
  * @since 4.0.0
+ * @source panel/src/panel/events.js
  */
 export interface PanelEvents extends PanelEventEmitter {
   /** Element that was entered during drag */
@@ -1535,13 +1564,9 @@ export interface PanelEvents extends PanelEventEmitter {
    */
   prevent: (event: Event) => void;
 
-  /**
-   * Subscribes all global event listeners.
-   */
+  /** Subscribes all global event listeners. */
   subscribe: () => void;
 
-  /**
-   * Unsubscribes all global event listeners.
-   */
+  /** Unsubscribes all global event listeners. */
   unsubscribe: () => void;
 }