kirby-types 1.1.2 → 1.2.0

package/src/panel/helpers.d.ts

@@ -17,7 +17,7 @@
 export interface PanelArraySearchOptions {
   /** Minimum query length (default: 0) */
   min?: number;
-  /** Field to search in (default: `'text'`) */
+  /** Field to search in (default: `"text"`) */
   field?: string;
   /** Maximum results to return */
   limit?: number;
@@ -173,8 +173,8 @@ export interface PanelHelpersString {
    *
    * @param string - String to convert
    * @param rules - Language/ASCII conversion rules
-   * @param allowed - Allowed characters (default: `'a-z0-9'`)
-   * @param separator - Separator character (default: `'-'`)
+   * @param allowed - Allowed characters (default: `"a-z0-9"`)
+   * @param separator - Separator character (default: `"-"`)
    * @returns Slug string
    */
   slug: (
@@ -417,17 +417,18 @@ export interface PanelHelpersClipboard {
    *
    * @param event - ClipboardEvent or string
    * @param plain - Read as plain text only
-   * @returns Clipboard content
+   * @returns Clipboard content or null if empty
    */
-  read: (event: ClipboardEvent | string, plain?: boolean) => string;
+  read: (event: ClipboardEvent | string, plain?: boolean) => string | null;
 
   /**
    * Writes to clipboard. Objects are auto-JSONified.
    *
    * @param value - Value to write
    * @param event - ClipboardEvent for event-based writing
+   * @returns True if successful
    */
-  write: (value: any, event?: ClipboardEvent) => void;
+  write: (value: any, event?: ClipboardEvent) => boolean;
 }
 
 // -----------------------------------------------------------------------------
@@ -445,27 +446,27 @@ export interface PanelHelpersEmbed {
    *
    * @param url - YouTube video URL
    * @param doNotTrack - Enable privacy-enhanced mode
-   * @returns Embed URL or null
+   * @returns Embed URL or false if not valid
    */
-  youtube: (url: string, doNotTrack?: boolean) => string | null;
+  youtube: (url: string, doNotTrack?: boolean) => string | false;
 
   /**
    * Converts Vimeo URL to embed URL.
    *
    * @param url - Vimeo video URL
    * @param doNotTrack - Enable do-not-track mode
-   * @returns Embed URL or null
+   * @returns Embed URL or false if not valid
    */
-  vimeo: (url: string, doNotTrack?: boolean) => string | null;
+  vimeo: (url: string, doNotTrack?: boolean) => string | false;
 
   /**
    * Auto-detects provider and converts to embed URL.
    *
    * @param url - Video URL
    * @param doNotTrack - Privacy mode
-   * @returns Embed URL or null
+   * @returns Embed URL or false if not valid
    */
-  video: (url: string, doNotTrack?: boolean) => string | null;
+  video: (url: string, doNotTrack?: boolean) => string | false;
 }
 
 // -----------------------------------------------------------------------------
@@ -485,7 +486,7 @@ export interface PanelFieldDefinition {
   /** Conditional visibility */
   when?: Record<string, any>;
   /** API endpoint */
-  endpoints?: { field?: string; section?: string };
+  endpoints?: { field?: string; section?: string; model?: string };
   /** Nested fields */
   fields?: Record<string, PanelFieldDefinition>;
   /** Additional properties */
@@ -569,7 +570,7 @@ export interface PanelHelpersFile {
    * Formats byte size as human-readable string.
    *
    * @param size - Size in bytes
-   * @returns Formatted size (e.g., `'1.2 MB'`)
+   * @returns Formatted size (e.g., `"1.2 MB"`)
    */
   niceSize: (size: number) => string;
 }
@@ -587,7 +588,7 @@ export interface PanelHelpersKeyboard {
   /**
    * Returns the meta key name for the current OS.
    *
-   * @returns 'cmd' on Mac, 'ctrl' on other OS
+   * @returns `"cmd"` on Mac, `"ctrl"` on other OS
    */
   metaKey: () => "cmd" | "ctrl";
 }
@@ -651,12 +652,12 @@ export interface PanelHelpersLink {
    *
    * @param value - Link value to detect
    * @param types - Custom type definitions
-   * @returns Detection result
+   * @returns Detection result or undefined if no match
    */
   detect: (
     value: string,
     types?: Record<string, PanelLinkType>,
-  ) => PanelLinkDetection;
+  ) => PanelLinkDetection | undefined;
 
   /**
    * Converts file permalink to file:// UUID.
@@ -719,14 +720,18 @@ export interface PanelHelpersLink {
  * Page status button props.
  */
 export interface PanelPageStatusProps {
-  /** Status text */
-  text: string;
+  /** Status title */
+  title: string;
   /** Status icon */
   icon: string;
   /** Status color */
   theme?: string;
   /** Whether disabled */
   disabled?: boolean;
+  /** Button size */
+  size: string;
+  /** Button style */
+  style: string;
 }
 
 /**
@@ -775,9 +780,9 @@ export type PanelUploadCompleteCallback = (
 export interface PanelUploadParams {
   /** Upload endpoint URL */
   url: string;
-  /** HTTP method (default: `'POST'`) */
+  /** HTTP method (default: `"POST"`) */
   method?: string;
-  /** Form field name (default: `'file'`) */
+  /** Form field name (default: `"file"`) */
   field?: string;
   /** Override filename */
   filename?: string;
@@ -822,10 +827,17 @@ export interface PanelThrottleOptions {
 }
 
 /**
- * Debounced/throttled function with cancel method.
+ * Debounced function (without cancel method).
  */
 export interface PanelDebouncedFunction<T extends (...args: any[]) => any> {
   (...args: Parameters<T>): ReturnType<T> | undefined;
+}
+
+/**
+ * Throttled function with cancel method.
+ */
+export interface PanelThrottledFunction<T extends (...args: any[]) => any> {
+  (...args: Parameters<T>): ReturnType<T> | undefined;
   /** Cancels pending invocation */
   cancel: () => void;
 }
@@ -861,7 +873,7 @@ export type PanelComparator = (a: string, b: string) => number;
  * @example
  * ```ts
  * // In a Vue component
- * this.$helper.string.slug('Hello World');
+ * this.$helper.string.slug("Hello World");
  * this.$helper.clone(someObject);
  * this.$helper.uuid();
  * ```
@@ -885,9 +897,9 @@ export interface PanelHelpers {
    * Resolves CSS color to CSS variable.
    *
    * @param value - Color name or value
-   * @returns CSS variable or original value
+   * @returns CSS variable or original value, undefined if not a string
    */
-  color: (value: string) => string;
+  color: (value: string) => string | undefined;
 
   /**
    * Creates a debounced function.
@@ -917,8 +929,9 @@ export interface PanelHelpers {
    *
    * @param element - Selector or element
    * @param field - Specific input name to focus
+   * @returns The focused element, or false if nothing could be focused
    */
-  focus: (element: string | HTMLElement, field?: string) => void;
+  focus: (element: string | HTMLElement, field?: string) => HTMLElement | false;
 
   /**
    * Checks if component is registered globally.
@@ -957,8 +970,8 @@ export interface PanelHelpers {
   /**
    * Converts aspect ratio to percentage.
    *
-   * @param fraction - Ratio string (e.g., `'3/2'`)
-   * @param fallback - Fallback value (default: `'100%'`)
+   * @param fraction - Ratio string (e.g., `"3/2"`)
+   * @param fallback - Fallback value (default: `"100%"`)
    * @param vertical - Calculate for vertical orientation
    * @returns Percentage string
    */
@@ -998,7 +1011,7 @@ export interface PanelHelpers {
     fn: T,
     delay: number,
     options?: PanelThrottleOptions,
-  ) => PanelDebouncedFunction<T>;
+  ) => PanelThrottledFunction<T>;
 
   /**
    * Uploads a file via XMLHttpRequest.

package/src/panel/index.d.ts

@@ -215,6 +215,7 @@ export type {
   PanelDebounceOptions,
   PanelThrottleOptions,
   PanelDebouncedFunction,
+  PanelThrottledFunction,
   PanelSortOptions,
   PanelComparator,
   // Main Helpers Interface
@@ -236,11 +237,13 @@ export type {
   PanelLibraryColors,
   // Dayjs Types
   PanelDayjsISOFormat,
+  PanelDayjsRoundUnit,
+  PanelDayjsMergeUnit,
   PanelDayjsPatternPart,
   PanelDayjsPattern,
+  PanelDayjsExtensions,
   PanelDayjsInstance,
-  PanelDayjsInput,
-  PanelDayjsUnit,
+  PanelDayjsStaticExtensions,
   PanelLibraryDayjs,
   // Autosize
   PanelLibraryAutosize,
@@ -275,13 +278,15 @@ export type {
  * @example
  * ```ts
  * // In a Vue component
- * const slug = this.$helper.slug('My Page Title');
- * const date = this.$library.dayjs('2024-01-15').format('DD.MM.YYYY');
+ * const slug = this.$helper.slug("My Page Title");
+ * const date = this.$library.dayjs("2024-01-15").format("DD.MM.YYYY");
  * ```
  */
 export type PanelApp = InstanceType<VueConstructor> & {
   $library: PanelLibrary;
   $helper: PanelHelpers;
+  /** Shortcut for escaping HTML (alias for `$helper.string.escapeHTML`) */
+  $esc: (string: string) => string;
 };
 
 // =============================================================================
@@ -467,6 +472,27 @@ export interface PanelUrls {
   site: string;
 }
 
+// =============================================================================
+// Panel Request Response
+// =============================================================================
+
+/**
+ * Response object from Panel requests.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/request.js
+ */
+export interface PanelRequestResponse {
+  /** The original Request object */
+  request: Request;
+  /** The parsed response */
+  response: {
+    /** Parsed JSON data */
+    json: any;
+    /** Raw response text */
+    text: string;
+  };
+}
+
 // =============================================================================
 // Panel Plugins
 // =============================================================================
@@ -498,66 +524,80 @@ export type PanelPluginsViews = Record<string, Record<string, any>>;
  * Panel plugin system.
  *
  * Manages Vue components, icons, and extensions registered by plugins.
+ * Properties are ordered to match `panel/public/js/plugins.js`.
  *
  * @see https://getkirby.com/docs/reference/plugins/extensions
  */
 export interface PanelPlugins {
+  // ---------------------------------------------------------------------------
+  // Helper Functions (from panel/src/panel/plugins.js)
+  // ---------------------------------------------------------------------------
+
   /**
-   * Resolves component extensions by name.
+   * Resolves a component extension if defined as component name.
+   *
+   * @param app - Vue application instance
+   * @param name - Component name being registered
+   * @param component - Component options object
+   * @returns Updated/extended component options
    */
-  resolveComponentExtension: (
-    name: string,
-    extension: string,
-    fallback?: any,
-  ) => any;
+  resolveComponentExtension: (app: any, name: string, component: any) => any;
 
   /**
-   * Resolves all mixins for a component.
+   * Resolves available mixins if they are defined.
+   *
+   * @param component - Component options object
+   * @returns Updated component options with resolved mixins
    */
-  resolveComponentMixins: (name: string) => any[];
+  resolveComponentMixins: (component: any) => any;
 
   /**
-   * Resolves the render function for a component.
+   * Resolves a component's competing template/render options.
+   *
+   * @param component - Component options object
+   * @returns Updated component options
    */
-  resolveComponentRender: (name: string) => any;
+  resolveComponentRender: (component: any) => any;
+
+  // ---------------------------------------------------------------------------
+  // Plugin Data (ordered as in panel/public/js/plugins.js)
+  // ---------------------------------------------------------------------------
 
   /** Registered Vue components */
   components: Record<string, ComponentPublicInstance>;
 
-  /** Hooks to run after Panel creation */
+  /** Callbacks to run after Panel creation */
   created: Array<() => void>;
 
   /** Registered SVG icons */
   icons: Record<string, string>;
 
-  /** Custom login component */
+  /** Custom login component (set dynamically by plugins) */
   login: ComponentPublicInstance | null;
 
-  /** Custom textarea buttons */
+  /** Registered Panel routes */
+  routes: Record<string, any>[];
+
+  /** Registered textarea toolbar buttons */
   textareaButtons: Record<string, Record<string, any>>;
 
-  /** Third-party plugin data */
+  /** Registered third-party plugin data */
   thirdParty: PanelPluginsThirdParty;
 
-  /**
-   * Registers plugins with the Panel.
-   */
-  use: (plugins: Record<string, any>) => any[];
+  /** Installed Vue plugins via `Vue.use()` */
+  use: any[];
 
-  /** Custom view buttons */
+  /** Registered view buttons */
   viewButtons: PanelPluginsViewButtons;
 
-  /** Custom writer marks */
+  /** Registered Panel views */
+  views: PanelPluginsViews;
+
+  /** Registered writer marks */
   writerMarks: Record<string, Record<string, any>>;
 
-  /** Custom writer nodes */
+  /** Registered writer nodes */
   writerNodes: PanelPluginsWriterNodes;
-
-  /** Custom routes */
-  routes: Array<Record<string, any>>;
-
-  /** Custom views */
-  views: PanelPluginsViews;
 }
 
 // =============================================================================
@@ -568,7 +608,7 @@ export interface PanelPlugins {
  * Language information for multi-language sites.
  */
 export interface PanelLanguageInfo {
-  /** Language code (e.g., `'en'`, `'de'`) */
+  /** Language code (e.g., `"en"`, `"de"`) */
   code: string;
   /** Whether this is the default language */
   default: boolean;
@@ -589,7 +629,6 @@ export interface PanelLanguageInfo {
  */
 export interface PanelGlobalState {
   activation: PanelFeatures.PanelActivationDefaults;
-  content: Record<string, any>;
   dialog: PanelFeatures.PanelDialogDefaults;
   drag: PanelFeatures.PanelDragDefaults;
   drawer: PanelFeatures.PanelDrawerDefaults;
@@ -620,13 +659,13 @@ export interface PanelGlobalState {
  * const panel = window.$panel;
  *
  * // Navigate to a page
- * await panel.view.open('/pages/home');
+ * await panel.view.open("/pages/home");
  *
  * // Open a dialog
- * await panel.dialog.open('/dialogs/pages/create');
+ * await panel.dialog.open("/dialogs/pages/create");
  *
  * // Make an API request
- * const data = await panel.get('/api/pages/home');
+ * const data = await panel.get("/api/pages/home");
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/panel.js
@@ -775,8 +814,12 @@ export interface Panel {
    *
    * @param error - Error or message
    * @param openNotification - Whether to show notification (default: true)
+   * @returns Notification state if opened, void otherwise
    */
-  error: (error: Error | string, openNotification?: boolean) => void;
+  error: (
+    error: Error | string,
+    openNotification?: boolean,
+  ) => void | PanelFeatures.PanelNotificationDefaults;
 
   /**
    * Sends a GET request through the Panel router.
@@ -788,26 +831,29 @@ export interface Panel {
   get: (url: string | URL, options?: PanelRequestOptions) => Promise<any>;
 
   /**
-   * Opens a URL through the Panel router.
+   * Opens a URL through the Panel router and sets the state.
+   *
+   * Unlike `get()`, this method also updates the Panel state
+   * based on the response.
    *
-   * @param url - URL to open
+   * @param url - URL to open or state object
    * @param options - Request options
+   * @returns The new Panel state
    */
-  open: (url: string | URL, options?: PanelRequestOptions) => Promise<void>;
+  open: (
+    url: string | URL | Partial<PanelGlobalState>,
+    options?: PanelRequestOptions,
+  ) => Promise<PanelGlobalState>;
 
   /**
-   * Returns all open overlay contexts.
+   * Returns all open overlay types.
    *
-   * @returns Array of contexts ('view', 'dialog', 'drawer')
-   */
-  overlays: () => PanelContext[];
-
-  /**
-   * Registers a plugin or plugin module.
+   * Returns an array of currently open overlays in order.
+   * Only includes "drawer" and "dialog" - the view is not an overlay.
    *
-   * @param args - Plugin arguments
+   * @returns Array of open overlay types
    */
-  plugin: (...args: any[]) => void;
+  overlays: () => ("drawer" | "dialog")[];
 
   /**
    * Sends a POST request through the Panel router.
@@ -840,28 +886,39 @@ export interface Panel {
   /**
    * Sends a request through the Panel router.
    *
+   * Returns an object with both the request and parsed response,
+   * or `false` if the request was redirected externally.
+   *
    * @param url - URL to request
    * @param options - Request options including method
-   * @returns Fetch Response
+   * @returns Request/response object or false on redirect
    */
   request: (
     url: string | URL,
     options?: PanelRequestOptions,
-  ) => Promise<Response>;
+  ) => Promise<PanelRequestResponse | false>;
 
   /**
-   * Performs a search.
+   * Opens the search dialog or performs a search query.
+   *
+   * When called without a query, opens the search dialog
+   * with the specified search type pre-selected.
+   *
+   * When called with a query, performs the search and returns results.
    *
    * @param type - Search type ('pages', 'files', 'users')
-   * @param query - Search query
-   * @param options - Request options
-   * @returns Search results
+   * @param query - Search query string
+   * @param options - Search options (page, limit)
+   * @returns Search results when query provided, void otherwise
    */
-  search: (
-    type: string,
-    query: string,
-    options?: PanelRequestOptions,
-  ) => Promise<any>;
+  search: {
+    (type: string): void;
+    (
+      type: string,
+      query: string,
+      options?: PanelFeatures.PanelSearchOptions,
+    ): Promise<PanelFeatures.PanelSearchResult>;
+  };
 
   /**
    * Sets global Panel state.
@@ -953,7 +1010,7 @@ export interface PanelViewPropsVersions {
 export interface PanelViewPropsTab {
   label: string;
   icon: string;
-  columns: Array<Record<string, any>>;
+  columns: Record<string, any>[];
   link: string;
   name: string;
 }
@@ -1009,7 +1066,7 @@ export interface PanelViewProps {
   link: string;
   lock: PanelViewPropsLock;
   permissions: PanelViewPropsPermissions;
-  tabs: Array<Record<string, any>>;
+  tabs: Record<string, any>[];
   uuid: string;
   versions: PanelViewPropsVersions;
   tab: PanelViewPropsTab;