kirby-types 1.4.7 → 1.4.9

package/src/panel/helpers.d.ts

@@ -11,9 +11,7 @@
 // Array Helpers
 // -----------------------------------------------------------------------------
 
-/**
- * Search options for array filtering.
- */
+/** Search options for array filtering. */
 export interface PanelArraySearchOptions {
   /** Minimum query length (default: 0) */
   min?: number;
@@ -27,6 +25,7 @@ export interface PanelArraySearchOptions {
  * Array helper utilities.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/array.js
+ * @source panel/src/helpers/array.js
  */
 export interface PanelHelpersArray {
   /**
@@ -82,9 +81,7 @@ export interface PanelHelpersArray {
 // String Helpers
 // -----------------------------------------------------------------------------
 
-/**
- * Slug conversion rules.
- */
+/** Slug conversion rules. */
 export type PanelSlugRules = Record<string, string>[];
 
 /**
@@ -193,8 +190,7 @@ export interface PanelHelpersString {
   stripHTML: (string: string) => string;
 
   /**
-   * Replaces template placeholders with values.
-   * Supports `{{name}}` and `{{nested.prop}}` syntax.
+   * Replaces `{name}`, `{{name}}`, and dotted-path placeholders (e.g. `{nested.prop}`) with values from the lookup object.
    *
    * @param string - Template string
    * @param values - Replacement values
@@ -242,10 +238,11 @@ export interface PanelHelpersString {
  * Object helper utilities.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/object.js
+ * @source panel/src/helpers/object.js
  */
 export interface PanelHelpersObject {
   /**
-   * Deep clones an object or array using structuredClone.
+   * Deep clones a value via `structuredClone`. Returns `undefined` unchanged.
    *
    * @param value - Value to clone
    * @returns Cloned value
@@ -417,16 +414,19 @@ export interface PanelHelpersClipboard {
    *
    * @param event - ClipboardEvent or string
    * @param plain - Read as plain text only
-   * @returns Clipboard content or null if empty
+   * @returns Clipboard content, or null if no event/string was provided
    */
-  read: (event: ClipboardEvent | string, plain?: boolean) => string | null;
+  read: (
+    event?: ClipboardEvent | string | null,
+    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
+   * @returns Always `true` (no failure detection)
    */
   write: (value: any, event?: ClipboardEvent) => boolean;
 }
@@ -439,6 +439,7 @@ export interface PanelHelpersClipboard {
  * Embed helper utilities for video providers.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/embed.js
+ * @source panel/src/helpers/embed.js
  */
 export interface PanelHelpersEmbed {
   /**
@@ -473,9 +474,7 @@ export interface PanelHelpersEmbed {
 // Field Helpers
 // -----------------------------------------------------------------------------
 
-/**
- * Field definition object.
- */
+/** Field definition object. */
 export interface PanelFieldDefinition {
   /** Field type */
   type?: string;
@@ -497,6 +496,7 @@ export interface PanelFieldDefinition {
  * Field helper utilities.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/field.js
+ * @source panel/src/helpers/field.js
  */
 export interface PanelHelpersField {
   /**
@@ -516,7 +516,7 @@ export interface PanelHelpersField {
   form: (fields: Record<string, PanelFieldDefinition>) => Record<string, any>;
 
   /**
-   * Checks if field is visible based on 'when' conditions.
+   * Checks if a field or section is visible. Returns false for hidden fields, otherwise evaluates `when` conditions against current form values.
    *
    * @param field - Field definition
    * @param values - Current form values
@@ -528,7 +528,7 @@ export interface PanelHelpersField {
   ) => boolean;
 
   /**
-   * Propagates parent field's API endpoints to nested subfield definitions.
+   * Annotates subfields with the parent's section name and, when present, its API endpoints (suffixing the field endpoint with the subfield name).
    *
    * @param field - Parent field
    * @param fields - Subfield definitions
@@ -548,6 +548,7 @@ export interface PanelHelpersField {
  * File helper utilities.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/file.js
+ * @source panel/src/helpers/file.js
  */
 export interface PanelHelpersFile {
   /**
@@ -597,9 +598,7 @@ export interface PanelHelpersKeyboard {
 // Link Helpers
 // -----------------------------------------------------------------------------
 
-/**
- * Link type definition.
- */
+/** Link type definition. */
 export interface PanelLinkType {
   /** Detection function */
   detect: (value: string) => boolean;
@@ -621,9 +620,7 @@ export interface PanelLinkType {
   value: (value: string) => string;
 }
 
-/**
- * Detected link result.
- */
+/** Detected link result. */
 export interface PanelLinkDetection {
   /** Detected type */
   type: string;
@@ -631,9 +628,7 @@ export interface PanelLinkDetection {
   link: string;
 }
 
-/**
- * Link preview data.
- */
+/** Link preview data. */
 export interface PanelLinkPreview {
   /** Display label */
   label: string;
@@ -684,7 +679,7 @@ export interface PanelHelpersLink {
   isFileUUID: (value: string) => boolean;
 
   /**
-   * Checks if value is a page UUID or permalink.
+   * Checks if value is `site://`, a `page://` UUID, or a page permalink.
    *
    * @param value - Value to check
    * @returns True if page reference
@@ -716,16 +711,14 @@ export interface PanelHelpersLink {
 // Page Helpers
 // -----------------------------------------------------------------------------
 
-/**
- * Page status button props.
- */
+/** Page status button props. */
 export interface PanelPageStatusProps {
   /** Status title */
   title: string;
   /** Status icon */
   icon: string;
   /** Status color */
-  theme?: string;
+  theme: "negative-icon" | "info-icon" | "positive-icon";
   /** Whether disabled */
   disabled?: boolean;
   /** Button size */
@@ -738,6 +731,7 @@ export interface PanelPageStatusProps {
  * Page helper utilities.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/page.js
+ * @source panel/src/helpers/page.js
  */
 export interface PanelHelpersPage {
   /**
@@ -754,18 +748,14 @@ export interface PanelHelpersPage {
 // Upload Helpers
 // -----------------------------------------------------------------------------
 
-/**
- * Upload progress callback.
- */
+/** Upload progress callback. */
 export type PanelUploadProgressCallback = (
   xhr: XMLHttpRequest,
   file: File,
   percent: number,
 ) => void;
 
-/**
- * Upload complete callback.
- */
+/** Upload complete callback. */
 export type PanelUploadCompleteCallback = (
   xhr: XMLHttpRequest,
   file: File,
@@ -806,9 +796,7 @@ export interface PanelUploadParams {
 // Debounce/Throttle Helpers
 // -----------------------------------------------------------------------------
 
-/**
- * Debounce options.
- */
+/** Debounce options. */
 export interface PanelDebounceOptions {
   /** Call on leading edge (default: false) */
   leading?: boolean;
@@ -816,9 +804,7 @@ export interface PanelDebounceOptions {
   trailing?: boolean;
 }
 
-/**
- * Throttle options.
- */
+/** Throttle options. */
 export interface PanelThrottleOptions {
   /** Call on leading edge (default: true) */
   leading?: boolean;
@@ -826,16 +812,12 @@ export interface PanelThrottleOptions {
   trailing?: boolean;
 }
 
-/**
- * Debounced function (without 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.
- */
+/** Throttled function with cancel method. */
 export interface PanelThrottledFunction<T extends (...args: any[]) => any> {
   (...args: Parameters<T>): ReturnType<T> | undefined;
   /** Cancels pending invocation */
@@ -846,9 +828,7 @@ export interface PanelThrottledFunction<T extends (...args: any[]) => any> {
 // Sort Helper
 // -----------------------------------------------------------------------------
 
-/**
- * Sort options.
- */
+/** Sort options. */
 export interface PanelSortOptions {
   /** Sort descending (default: false) */
   desc?: boolean;
@@ -856,9 +836,7 @@ export interface PanelSortOptions {
   insensitive?: boolean;
 }
 
-/**
- * Comparator function for sorting.
- */
+/** Comparator function for sorting. */
 export type PanelComparator = (a: string, b: string) => number;
 
 // -----------------------------------------------------------------------------
@@ -881,15 +859,21 @@ export type PanelComparator = (a: string, b: string) => number;
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/index.js
  */
 export interface PanelHelpers {
-  /** Array utilities */
+  /**
+   * @source panel/src/helpers/array.js
+   */
   array: PanelHelpersArray;
 
-  /** Clipboard utilities */
+  /**
+   * @source panel/src/helpers/clipboard.js
+   */
   clipboard: PanelHelpersClipboard;
 
   /**
    * Deep clones a value.
    * Shortcut for `object.clone()`.
+   * @source panel/src/helpers/object.js
+   * @source panel/src/helpers/index.js
    */
   clone: <T>(value: T) => T;
 
@@ -898,6 +882,7 @@ export interface PanelHelpers {
    *
    * @param value - Color name or value
    * @returns CSS variable or original value, undefined if not a string
+   * @source panel/src/helpers/color.js
    */
   color: (value: string) => string | undefined;
 
@@ -907,7 +892,9 @@ export interface PanelHelpers {
    * @param fn - Function to debounce
    * @param delay - Delay in milliseconds
    * @param options - Debounce options
-   * @returns Debounced function with cancel method
+   * @returns Debounced function
+   * @source panel/src/helpers/debounce.js
+   * @source panel/src/helpers/index.js
    */
   debounce: <T extends (...args: any[]) => any>(
     fn: T,
@@ -915,13 +902,19 @@ export interface PanelHelpers {
     options?: PanelDebounceOptions,
   ) => PanelDebouncedFunction<T>;
 
-  /** Video embed utilities */
+  /**
+   * @source panel/src/helpers/embed.js
+   */
   embed: PanelHelpersEmbed;
 
-  /** Field utilities */
+  /**
+   * @source panel/src/helpers/field.js
+   */
   field: PanelHelpersField;
 
-  /** File utilities */
+  /**
+   * @source panel/src/helpers/file.js
+   */
   file: PanelHelpersFile;
 
   /**
@@ -930,6 +923,7 @@ 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
+   * @source panel/src/helpers/focus.js
    */
   focus: (element: string | HTMLElement, field?: string) => HTMLElement | false;
 
@@ -938,6 +932,8 @@ export interface PanelHelpers {
    *
    * @param name - Component name
    * @returns True if registered
+   * @source panel/src/helpers/isComponent.js
+   * @source panel/src/helpers/index.js
    */
   isComponent: (name: string) => boolean;
 
@@ -946,25 +942,37 @@ export interface PanelHelpers {
    *
    * @param event - Event to check
    * @returns True if file upload event
+   * @source panel/src/helpers/isUploadEvent.js
+   * @source panel/src/helpers/index.js
    */
-  isUploadEvent: (event: Event) => boolean;
+  isUploadEvent: (event: DragEvent) => boolean;
 
-  /** Keyboard utilities */
+  /**
+   * @source panel/src/helpers/keyboard.js
+   */
   keyboard: PanelHelpersKeyboard;
 
-  /** Link utilities */
+  /**
+   * @source panel/src/helpers/link.js
+   */
   link: PanelHelpersLink;
 
-  /** Object utilities */
+  /**
+   * @source panel/src/helpers/object.js
+   */
   object: PanelHelpersObject;
 
   /**
    * Left-pads value with zeros.
    * Shortcut for `string.pad()`.
+   * @source panel/src/helpers/index.js
+   * @source panel/src/helpers/string.js
    */
   pad: (value: string | number, length?: number) => string;
 
-  /** Page utilities */
+  /**
+   * @source panel/src/helpers/page.js
+   */
   page: PanelHelpersPage;
 
   /**
@@ -974,12 +982,15 @@ export interface PanelHelpers {
    * @param fallback - Fallback value (default: `"100%"`)
    * @param vertical - Calculate for vertical orientation
    * @returns Percentage string
+   * @source panel/src/helpers/ratio.js
    */
   ratio: (fraction?: string, fallback?: string, vertical?: boolean) => string;
 
   /**
    * Converts string to slug.
    * Shortcut for `string.slug()`.
+   * @source panel/src/helpers/index.js
+   * @source panel/src/helpers/string.js
    */
   slug: (
     string: string,
@@ -993,10 +1004,13 @@ export interface PanelHelpers {
    *
    * @param options - Sort options
    * @returns Comparator function
+   * @source panel/src/helpers/sort.js
    */
   sort: (options?: PanelSortOptions) => PanelComparator;
 
-  /** String utilities */
+  /**
+   * @source panel/src/helpers/string.js
+   */
   string: PanelHelpersString;
 
   /**
@@ -1006,6 +1020,8 @@ export interface PanelHelpers {
    * @param delay - Delay in milliseconds
    * @param options - Throttle options
    * @returns Throttled function with cancel method
+   * @source panel/src/helpers/throttle.js
+   * @source panel/src/helpers/index.js
    */
   throttle: <T extends (...args: any[]) => any>(
     fn: T,
@@ -1019,15 +1035,21 @@ export interface PanelHelpers {
    * @param file - File to upload
    * @param params - Upload parameters
    * @returns Promise resolving to response
+   * @source panel/src/helpers/upload.js
+   * @source panel/src/helpers/index.js
    */
   upload: (file: File, params: PanelUploadParams) => Promise<any>;
 
-  /** URL utilities */
+  /**
+   * @source panel/src/helpers/url.js
+   */
   url: PanelHelpersUrl;
 
   /**
    * Generates UUID v4 string.
    * Shortcut for `string.uuid()`.
+   * @source panel/src/helpers/index.js
+   * @source panel/src/helpers/string.js
    */
   uuid: () => string;
 }