kirby-types 1.1.1 → 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;
@@ -45,7 +45,7 @@ export interface PanelHelpersArray {
    * @param options - Search options
    * @returns Filtered array
    */
-  search: <T extends Record<string, unknown>>(
+  search: <T extends Record<string, any>>(
     array: T[],
     query: string,
     options?: PanelArraySearchOptions,
@@ -58,10 +58,7 @@ export interface PanelHelpersArray {
    * @param sortBy - Sort specification (e.g., `'name asc'`, `'date desc'`)
    * @returns Sorted array
    */
-  sortBy: <T extends Record<string, unknown>>(
-    array: T[],
-    sortBy: string,
-  ) => T[];
+  sortBy: <T extends Record<string, any>>(array: T[], sortBy: string) => T[];
 
   /**
    * Splits array into subarrays using delimiter element.
@@ -176,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: (
@@ -203,7 +200,7 @@ export interface PanelHelpersString {
    * @param values - Replacement values
    * @returns Interpolated string
    */
-  template: (string: string, values?: Record<string, unknown>) => string;
+  template: (string: string, values?: Record<string, any>) => string;
 
   /**
    * Converts first letter to uppercase.
@@ -262,7 +259,7 @@ export interface PanelHelpersObject {
    * @param predicate - Filter function
    * @returns Filtered object
    */
-  filter: <T extends Record<string, unknown>>(
+  filter: <T extends Record<string, any>>(
     object: T,
     predicate: (value: T[keyof T], key: string) => boolean,
   ) => Partial<T>;
@@ -273,7 +270,7 @@ export interface PanelHelpersObject {
    * @param value - Value to check
    * @returns True if empty
    */
-  isEmpty: (value: unknown) => boolean;
+  isEmpty: (value: any) => boolean;
 
   /**
    * Checks if input is a plain object (not array, null, etc.).
@@ -281,7 +278,7 @@ export interface PanelHelpersObject {
    * @param input - Value to check
    * @returns True if plain object
    */
-  isObject: (input: unknown) => input is Record<string, unknown>;
+  isObject: (input: any) => input is Record<string, any>;
 
   /**
    * Counts keys in an object.
@@ -289,7 +286,7 @@ export interface PanelHelpersObject {
    * @param object - Object to count
    * @returns Number of keys
    */
-  length: (object: Record<string, unknown>) => number;
+  length: (object: Record<string, any>) => number;
 
   /**
    * Recursively merges source into target.
@@ -298,10 +295,7 @@ export interface PanelHelpersObject {
    * @param source - Source object
    * @returns Merged object
    */
-  merge: <T extends Record<string, unknown>>(
-    target: T,
-    source?: Partial<T>,
-  ) => T;
+  merge: <T extends Record<string, any>>(target: T, source?: Partial<T>) => T;
 
   /**
    * Compares objects by JSON stringification.
@@ -310,7 +304,7 @@ export interface PanelHelpersObject {
    * @param b - Second object
    * @returns True if identical
    */
-  same: (a: unknown, b: unknown) => boolean;
+  same: (a: any, b: any) => boolean;
 
   /**
    * Converts all object keys to lowercase.
@@ -423,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: unknown, event?: ClipboardEvent) => void;
+  write: (value: any, event?: ClipboardEvent) => boolean;
 }
 
 // -----------------------------------------------------------------------------
@@ -451,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,17 +480,17 @@ export interface PanelFieldDefinition {
   /** Field type */
   type?: string;
   /** Default value */
-  default?: unknown;
+  default?: any;
   /** Whether field is disabled */
   disabled?: boolean;
   /** Conditional visibility */
-  when?: Record<string, unknown>;
+  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 */
-  [key: string]: unknown;
+  [key: string]: any;
 }
 
 /**
@@ -510,7 +505,7 @@ export interface PanelHelpersField {
    * @param field - Field definition
    * @returns Default value
    */
-  defaultValue: (field: PanelFieldDefinition) => unknown;
+  defaultValue: (field: PanelFieldDefinition) => any;
 
   /**
    * Creates form values object from field definitions.
@@ -518,9 +513,7 @@ export interface PanelHelpersField {
    * @param fields - Field definitions
    * @returns Form values object
    */
-  form: (
-    fields: Record<string, PanelFieldDefinition>,
-  ) => Record<string, unknown>;
+  form: (fields: Record<string, PanelFieldDefinition>) => Record<string, any>;
 
   /**
    * Checks if field is visible based on 'when' conditions.
@@ -531,7 +524,7 @@ export interface PanelHelpersField {
    */
   isVisible: (
     field: PanelFieldDefinition,
-    values: Record<string, unknown>,
+    values: Record<string, any>,
   ) => boolean;
 
   /**
@@ -577,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;
 }
@@ -595,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";
 }
@@ -645,7 +638,7 @@ export interface PanelLinkPreview {
   /** Display label */
   label: string;
   /** Preview image */
-  image?: { url: string; [key: string]: unknown };
+  image?: { url: string; [key: string]: any };
 }
 
 /**
@@ -659,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.
@@ -727,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;
 }
 
 /**
@@ -772,7 +769,7 @@ export type PanelUploadProgressCallback = (
 export type PanelUploadCompleteCallback = (
   xhr: XMLHttpRequest,
   file: File,
-  response: unknown,
+  response: any,
 ) => void;
 
 /**
@@ -783,16 +780,16 @@ 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;
   /** Request headers */
   headers?: Record<string, string>;
   /** Additional form attributes */
-  attributes?: Record<string, unknown>;
+  attributes?: Record<string, any>;
   /** AbortSignal for cancellation */
   abort?: AbortSignal;
   /** Progress callback */
@@ -830,11 +827,16 @@ export interface PanelThrottleOptions {
 }
 
 /**
- * Debounced/throttled function with cancel method.
+ * Debounced function (without cancel method).
  */
-export interface PanelDebouncedFunction<
-  T extends (...args: unknown[]) => unknown,
-> {
+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;
@@ -871,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();
  * ```
@@ -895,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.
@@ -907,7 +909,7 @@ export interface PanelHelpers {
    * @param options - Debounce options
    * @returns Debounced function with cancel method
    */
-  debounce: <T extends (...args: unknown[]) => unknown>(
+  debounce: <T extends (...args: any[]) => any>(
     fn: T,
     delay: number,
     options?: PanelDebounceOptions,
@@ -927,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.
@@ -967,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
    */
@@ -1004,11 +1007,11 @@ export interface PanelHelpers {
    * @param options - Throttle options
    * @returns Throttled function with cancel method
    */
-  throttle: <T extends (...args: unknown[]) => unknown>(
+  throttle: <T extends (...args: any[]) => any>(
     fn: T,
     delay: number,
     options?: PanelThrottleOptions,
-  ) => PanelDebouncedFunction<T>;
+  ) => PanelThrottledFunction<T>;
 
   /**
    * Uploads a file via XMLHttpRequest.
@@ -1017,7 +1020,7 @@ export interface PanelHelpers {
    * @param params - Upload parameters
    * @returns Promise resolving to response
    */
-  upload: (file: File, params: PanelUploadParams) => Promise<unknown>;
+  upload: (file: File, params: PanelUploadParams) => Promise<any>;
 
   /** URL utilities */
   url: PanelHelpersUrl;