kirby-types 1.1.2 → 1.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kirby-types",
   "type": "module",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "packageManager": "pnpm@10.27.0",
   "description": "TypeScript types for Kirby Panel plugins and headless CMS usage",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
@@ -43,14 +43,18 @@
     "test": "tsd -f \"test/**/*.test-d.ts\""
   },
   "peerDependencies": {
-    "prosemirror-commands": "^1.0.0",
-    "prosemirror-inputrules": "^1.0.0",
-    "prosemirror-model": "^1.0.0",
-    "prosemirror-schema-list": "^1.0.0",
-    "prosemirror-state": "^1.0.0",
+    "dayjs": "^1.0.0",
+    "prosemirror-commands": "^1.7.1",
+    "prosemirror-inputrules": "^1.5.1",
+    "prosemirror-model": "^1.25.4",
+    "prosemirror-schema-list": "^1.5.1",
+    "prosemirror-state": "^1.4.4",
     "vue": "^2.7.0"
   },
   "peerDependenciesMeta": {
+    "dayjs": {
+      "optional": true
+    },
     "prosemirror-commands": {
       "optional": true
     },
@@ -73,6 +77,7 @@
   "devDependencies": {
     "@antfu/eslint-config": "^6.7.3",
     "bumpp": "^10.3.2",
+    "dayjs": "^1.11.13",
     "eslint": "^9.39.2",
     "prettier": "^3.7.4",
     "tsd": "^0.33.0",

package/src/panel/api.d.ts

@@ -76,33 +76,28 @@ export interface PanelApiAuth {
   /**
    * Logs out the current user.
    */
-  logout: () => Promise<void>;
+  logout: () => Promise<any>;
 
   /**
    * Pings the server to keep session alive.
    */
-  ping: () => Promise<void>;
+  ping: () => Promise<any>;
 
   /**
    * Gets the current user.
    *
    * @param query - Query parameters
-   * @param options - Request options
    * @returns User data
    */
-  user: (
-    query?: Record<string, any>,
-    options?: PanelApiRequestOptions,
-  ) => Promise<any>;
+  user: (query?: Record<string, any>) => Promise<any>;
 
   /**
    * Verifies a 2FA code.
    *
    * @param code - Verification code
-   * @param data - Additional data
    * @returns Verification result
    */
-  verifyCode: (code: string, data?: Record<string, any>) => Promise<any>;
+  verifyCode: (code: string) => Promise<any>;
 }
 
 // -----------------------------------------------------------------------------
@@ -135,7 +130,7 @@ export interface PanelApiFiles {
    * @param parent - Parent page/site path
    * @param filename - Filename to delete
    */
-  delete: (parent: string | null, filename: string) => Promise<void>;
+  delete: (parent: string | null, filename: string) => Promise<any>;
 
   /**
    * Gets a file.
@@ -225,18 +220,17 @@ export interface PanelApiLanguages {
   /**
    * Creates a new language.
    *
-   * @param code - Language code
-   * @param data - Language data
+   * @param data - Language data (including code)
    * @returns Created language
    */
-  create: (code: string, data: PanelApiLanguageData) => Promise<any>;
+  create: (data: PanelApiLanguageData) => Promise<any>;
 
   /**
    * Deletes a language.
    *
    * @param code - Language code
    */
-  delete: (code: string) => Promise<void>;
+  delete: (code: string) => Promise<any>;
 
   /**
    * Gets a language.
@@ -381,7 +375,7 @@ export interface PanelApiPages {
    * @param id - Page ID
    * @param data - Delete options
    */
-  delete: (id: string, data?: { force?: boolean }) => Promise<void>;
+  delete: (id: string, data?: { force?: boolean }) => Promise<any>;
 
   /**
    * Duplicates a page.
@@ -488,11 +482,10 @@ export interface PanelApiRoles {
   /**
    * Lists available roles.
    *
-   * @param user - User ID for context
-   * @param query - Query parameters
+   * @param params - Query parameters
    * @returns Array of roles
    */
-  list: (user?: string, query?: Record<string, any>) => Promise<any[]>;
+  list: (params?: Record<string, any>) => Promise<any[]>;
 }
 
 // -----------------------------------------------------------------------------
@@ -523,22 +516,17 @@ export interface PanelApiSite {
    * Changes the site title.
    *
    * @param title - New title
-   * @param language - Language code
    * @returns Updated site
    */
-  changeTitle: (title: string, language?: string) => Promise<any>;
+  changeTitle: (title: string) => Promise<any>;
 
   /**
    * Searches site children.
    *
    * @param query - Search query
-   * @param options - Query options
    * @returns Search results
    */
-  children: (
-    query?: PanelApiSearchQuery,
-    options?: Record<string, any>,
-  ) => Promise<any>;
+  children: (query?: PanelApiSearchQuery) => Promise<any>;
 
   /**
    * Gets the site.
@@ -552,10 +540,9 @@ export interface PanelApiSite {
    * Updates the site content.
    *
    * @param data - Content data
-   * @param language - Language code
    * @returns Updated site
    */
-  update: (data: Record<string, any>, language?: string) => Promise<any>;
+  update: (data: Record<string, any>) => Promise<any>;
 }
 
 // -----------------------------------------------------------------------------
@@ -602,25 +589,17 @@ export interface PanelApiSystem {
    * Installs Kirby with initial user.
    *
    * @param data - Installation data
-   * @param query - Query parameters
    * @returns Installation result
    */
-  install: (
-    data: PanelApiSystemInstallData,
-    query?: Record<string, any>,
-  ) => Promise<any>;
+  install: (data: PanelApiSystemInstallData) => Promise<any>;
 
   /**
    * Registers a license.
    *
    * @param data - Registration data
-   * @param query - Query parameters
    * @returns Registration result
    */
-  register: (
-    data: PanelApiSystemRegisterData,
-    query?: Record<string, any>,
-  ) => Promise<any>;
+  register: (data: PanelApiSystemRegisterData) => Promise<any>;
 }
 
 // -----------------------------------------------------------------------------
@@ -686,11 +665,11 @@ export interface PanelApiUsers {
   /**
    * Gets available blueprints for users.
    *
-   * @param user - User ID for context
-   * @param query - Query parameters
+   * @param id - User ID for context
+   * @param section - Section name to filter by
    * @returns Array of blueprints
    */
-  blueprints: (user?: string, query?: Record<string, any>) => Promise<any[]>;
+  blueprints: (id: string, section?: string) => Promise<any[]>;
 
   /**
    * Changes a user's email.
@@ -724,13 +703,13 @@ export interface PanelApiUsers {
    *
    * @param id - User ID
    * @param password - New password
-   * @param confirmation - Password confirmation
+   * @param currentPassword - Current password for verification
    * @returns Updated user
    */
   changePassword: (
     id: string,
     password: string,
-    confirmation: string,
+    currentPassword: string,
   ) => Promise<any>;
 
   /**
@@ -745,25 +724,24 @@ export interface PanelApiUsers {
   /**
    * Creates a new user.
    *
-   * @param id - User ID (usually email)
-   * @param data - User data
+   * @param data - User data (including email as identifier)
    * @returns Created user
    */
-  create: (id: string, data: PanelApiUserCreateData) => Promise<any>;
+  create: (data: PanelApiUserCreateData) => Promise<any>;
 
   /**
    * Deletes a user.
    *
    * @param id - User ID
    */
-  delete: (id: string) => Promise<void>;
+  delete: (id: string) => Promise<any>;
 
   /**
    * Deletes a user's avatar.
    *
    * @param id - User ID
    */
-  deleteAvatar: (id: string) => Promise<void>;
+  deleteAvatar: (id: string) => Promise<any>;
 
   /**
    * Gets a user.
@@ -842,13 +820,13 @@ export interface PanelApiUsers {
  * @example
  * ```ts
  * // Get a page
- * const page = await panel.api.pages.get('home');
+ * const page = await panel.api.pages.get("home");
  *
  * // Create a new page
- * await panel.api.pages.create('blog', {
- *   slug: 'new-post',
- *   title: 'New Post',
- *   template: 'article'
+ * await panel.api.pages.create("blog", {
+ *   slug: "new-post",
+ *   title: "New Post",
+ *   template: "article"
  * });
  * ```
  *
@@ -913,7 +891,6 @@ export interface PanelApi {
    * @param data - Request body
    * @param options - Request options
    * @param silent - Skip loading indicator
-   * @param upload - Whether uploading file
    * @returns Response data
    */
   post: (
@@ -921,7 +898,6 @@ export interface PanelApi {
     data?: any,
     options?: PanelApiRequestOptions,
     silent?: boolean,
-    upload?: boolean,
   ) => Promise<any>;
 
   /**

package/src/panel/base.d.ts

@@ -25,7 +25,7 @@
  * ```ts
  * // State is used by: language, menu, notification, system, translation, user, drag, theme
  * const notification: PanelState<PanelNotificationDefaults> = panel.notification;
- * notification.set({ message: 'Saved!' });
+ * notification.set({ message: "Saved!" });
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/state.js
@@ -149,11 +149,11 @@ export type PanelEventListenerMap<TEvents extends string = string> = Partial<
  *
  * @example
  * ```ts
- * panel.dialog.addEventListener('submit', (value) => {
- *   console.log('Dialog submitted:', value);
+ * panel.dialog.addEventListener("submit", (value) => {
+ *   console.log("Dialog submitted:", value);
  * });
  *
- * panel.dialog.emit('submit', formData);
+ * panel.dialog.emit("submit", formData);
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/listeners.js
@@ -241,10 +241,10 @@ export interface PanelFeatureDefaults {
  * @example
  * ```ts
  * // Load a view
- * await panel.view.load('/pages/home');
+ * await panel.view.load("/pages/home");
  *
  * // Open a dropdown with options
- * await panel.dropdown.open('/dropdowns/pages/home/options');
+ * await panel.dropdown.open("/dropdowns/pages/home/options");
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/feature.js
@@ -359,8 +359,9 @@ export interface PanelFeature<TDefaults extends object = PanelFeatureDefaults>
    * Reloads the feature by re-opening its current URL.
    *
    * @param options - Request options
+   * @returns False if no path exists, otherwise void
    */
-  reload: (options?: PanelRequestOptions) => Promise<void>;
+  reload: (options?: PanelRequestOptions) => Promise<void | false>;
 
   /**
    * Creates a full URL object for the current path and query.
@@ -405,7 +406,7 @@ export interface PanelSuccessResponse {
   message?: string;
   /** Events to emit (string or array of strings) */
   event?: string | string[];
-  /** Whether to emit the global 'success' event (default: true) */
+  /** Whether to emit the global `"success"` event (default: true) */
   emit?: boolean;
   /** URL to navigate to */
   route?: string | { url: string; options?: PanelRequestOptions };
@@ -431,14 +432,14 @@ export interface PanelSuccessResponse {
  * @example
  * ```ts
  * // Open a dialog
- * await panel.dialog.open('/dialogs/pages/create', {
+ * await panel.dialog.open("/dialogs/pages/create", {
  *   on: {
- *     submit: (value) => console.log('Created:', value)
+ *     submit: (value) => console.log("Created:", value)
  *   }
  * });
  *
  * // Close with history navigation
- * panel.drawer.goTo('previous-drawer-id');
+ * panel.drawer.goTo("previous-drawer-id");
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/modal.js
@@ -527,8 +528,9 @@ export interface PanelModal<
    * Reloads the modal by closing and reopening at the same URL.
    *
    * @param options - Request options
+   * @returns False if no path exists, otherwise void
    */
-  reload: (options?: PanelRequestOptions) => Promise<void>;
+  reload: (options?: PanelRequestOptions) => Promise<void | false>;
 
   /**
    * Sets modal state, auto-generating an ID if not provided.

package/src/panel/features.d.ts

@@ -13,12 +13,12 @@ import type {
   NotificationTheme,
   NotificationType,
   PanelEventCallback,
-  PanelEventListenerMap,
   PanelEventListeners,
   PanelFeature,
   PanelFeatureDefaults,
   PanelHistory,
   PanelModal,
+  PanelModalListeners,
   PanelRequestOptions,
   PanelState,
 } from "./base";
@@ -120,10 +120,10 @@ export interface PanelDrag extends PanelState<PanelDragDefaults> {
   /**
    * Starts a drag operation with type and data.
    *
-   * @param type - Drag item type (e.g., `'page'`, `'file'`)
-   * @param data - Associated data
+   * @param type - Drag item type (e.g., `"page"`, `"file"`)
+   * @param data - Associated data (string or object)
    */
-  start: (type: string, data: Record<string, any>) => void;
+  start: (type: string, data: string | Record<string, any>) => void;
 
   /**
    * Stops the current drag operation and resets state.
@@ -197,7 +197,7 @@ export interface PanelTheme extends Omit<
  * Default state for content language.
  */
 export interface PanelLanguageDefaults {
-  /** Language code (e.g., `'en'`, `'de'`) */
+  /** Language code (e.g., `"en"`, `"de"`) */
   code: string | null;
   /** Whether this is the default language */
   default: boolean;
@@ -218,7 +218,7 @@ export interface PanelLanguageDefaults {
  * @since 4.0.0
  */
 export interface PanelLanguage extends PanelState<PanelLanguageDefaults> {
-  /** Language code (e.g., `'en'`, `'de'`) */
+  /** Language code (e.g., `"en"`, `"de"`) */
   code: string | null;
   /** Whether this is the default language */
   default: boolean;
@@ -284,9 +284,10 @@ export interface PanelMenu extends Omit<PanelState<PanelMenuDefaults>, "set"> {
 
   /**
    * Handles outside clicks to close mobile menu.
+   * Returns false if not mobile/open, void otherwise.
    * @internal
    */
-  blur: (event: Event) => void;
+  blur: (event: Event) => false | void;
 
   /**
    * Collapses the sidebar menu.
@@ -296,9 +297,10 @@ export interface PanelMenu extends Omit<PanelState<PanelMenuDefaults>, "set"> {
 
   /**
    * Handles escape key to close mobile menu.
+   * Returns false if not mobile/open, void otherwise.
    * @internal
    */
-  escape: () => void;
+  escape: () => false | void;
 
   /**
    * Expands the sidebar menu.
@@ -429,12 +431,14 @@ export interface PanelNotification extends PanelState<PanelNotificationDefaults>
   /**
    * Creates an error notification.
    * Opens error dialog in view context.
+   * May redirect to logout for auth errors.
    *
    * @param error - Error object, string, or Error instance
+   * @returns Notification state, or void if redirected
    */
   error: (
     error: Error | string | PanelErrorObject,
-  ) => PanelNotificationDefaults;
+  ) => PanelNotificationDefaults | void;
 
   /**
    * Creates a fatal error notification.
@@ -523,7 +527,7 @@ export interface PanelSystem extends PanelState<PanelSystemDefaults> {
  * Default state for interface translation.
  */
 export interface PanelTranslationDefaults {
-  /** Translation code (e.g., `'en'`, `'de'`) */
+  /** Translation code (e.g., `"en"`, `"de"`) */
   code: string;
   /** Translation strings by key */
   data: Record<string, string>;
@@ -545,7 +549,7 @@ export interface PanelTranslationDefaults {
  * @since 4.0.0
  */
 export interface PanelTranslation extends PanelState<PanelTranslationDefaults> {
-  /** Translation code (e.g., `'en'`, `'de'`) */
+  /** Translation code (e.g., `"en"`, `"de"`) */
   code: string;
   /** Translation strings by key */
   data: Record<string, string>;
@@ -745,12 +749,13 @@ export interface PanelDropdown extends PanelFeature<PanelFeatureDefaults> {
 
   /**
    * Opens a dropdown asynchronously.
-   * @deprecated Use `open()` instead (since 4.0.0)
+   *
+   * @deprecated Since 4.0.0 - Use `open()` instead
    */
   openAsync: (
     dropdown: string | URL | Partial<PanelFeatureDefaults>,
     options?: PanelRequestOptions | PanelEventCallback,
-  ) => () => Promise<PanelFeatureDefaults>;
+  ) => (ready?: () => void) => Promise<PanelFeatureDefaults>;
 
   /**
    * Returns dropdown options array from props.
@@ -812,13 +817,11 @@ export interface PanelDialog extends PanelModal<PanelDialogDefaults> {
 
   /**
    * Opens a legacy Vue component dialog.
-   * @deprecated Since 4.0.0
+   *
+   * @param dialog - Vue component instance
+   * @deprecated Since 4.0.0 - Use `open()` with component object instead
    */
-  openComponent: (dialog: {
-    component: string;
-    props?: Record<string, any>;
-    on?: PanelEventListenerMap;
-  }) => Promise<void>;
+  openComponent: (dialog: any) => Promise<PanelDialogDefaults>;
 }
 
 // -----------------------------------------------------------------------------
@@ -845,7 +848,7 @@ export interface PanelDrawer extends PanelModal<PanelDrawerDefaults> {
   /** Breadcrumb from history milestones */
   readonly breadcrumb: PanelHistory["milestones"];
 
-  /** Drawer icon, defaults to 'box' */
+  /** Drawer icon, defaults to `"box"` */
   readonly icon: string;
 
   /**
@@ -860,8 +863,14 @@ export interface PanelDrawer extends PanelModal<PanelDrawerDefaults> {
    * Switches drawer tabs.
    *
    * @param tab - Tab name to switch to
+   * @returns False if no tabs exist, void otherwise
    */
-  tab: (tab: string) => void;
+  tab: (tab: string) => void | false;
+
+  /**
+   * Returns drawer event listeners for Vue component binding.
+   */
+  listeners: () => PanelModalListeners;
 }
 
 // -----------------------------------------------------------------------------
@@ -1142,7 +1151,7 @@ export interface PanelSearcher {
   /**
    * Opens the search dialog.
    *
-   * @param type - Search type (e.g., `'pages'`, `'files'`, `'users'`)
+   * @param type - Search type (e.g., `"pages"`, `"files"`, `"users"`)
    */
   open: (type?: string) => void;
 
@@ -1183,7 +1192,7 @@ export interface PanelUploadFile {
   filename: string;
   /** File size in bytes */
   size: number;
-  /** Formatted file size (e.g., `'1.2 MB'`) */
+  /** Formatted file size (e.g., `"1.2 MB"`) */
   niceSize: string;
   /** MIME type */
   type: string;
@@ -1203,8 +1212,8 @@ export interface PanelUploadFile {
  * Default state for upload feature.
  */
 export interface PanelUploadDefaults {
-  /** Abort callback for current upload */
-  abort: (() => void) | null;
+  /** AbortController for current upload */
+  abort: AbortController | null;
   /** Accepted file types */
   accept: string;
   /** Additional file attributes */
@@ -1234,8 +1243,8 @@ export interface PanelUploadDefaults {
  */
 export interface PanelUpload
   extends PanelState<PanelUploadDefaults>, PanelEventListeners {
-  /** Abort callback for current upload */
-  abort: (() => void) | null;
+  /** AbortController for current upload */
+  abort: AbortController | null;
   /** Accepted file types */
   accept: string;
   /** Additional file attributes */
@@ -1276,10 +1285,12 @@ export interface PanelUpload
 
   /**
    * Finds duplicate file by comparing properties.
+   * Returns the index of the duplicate file, or false if not found.
    *
    * @param file - File to check
+   * @returns Index of duplicate file or false
    */
-  findDuplicate: (file: File) => PanelUploadFile | undefined;
+  findDuplicate: (file: File) => number | false;
 
   /**
    * Checks if file has a unique name.
@@ -1392,9 +1403,6 @@ export interface PanelEventEmitter {
  * @since 4.0.0
  */
 export interface PanelEvents extends PanelEventEmitter {
-  /** Internal mitt emitter instance */
-  emitter: PanelEventEmitter;
-
   /** Element that was entered during drag */
   entered: Element | null;