kirby-types 0.7.3 → 1.1.0

package/src/panel/helpers.d.ts

@@ -0,0 +1,1030 @@
+/**
+ * Helper type definitions for Kirby Panel.
+ *
+ * Provides types for the `$helper` utilities available on the Vue prototype.
+ *
+ * @see https://github.com/getkirby/kirby/tree/main/panel/src/helpers
+ * @since 4.0.0
+ */
+
+// -----------------------------------------------------------------------------
+// Array Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Search options for array filtering.
+ */
+export interface PanelArraySearchOptions {
+  /** Minimum query length (default: 0) */
+  min?: number;
+  /** Field to search in (default: `'text'`) */
+  field?: string;
+  /** Maximum results to return */
+  limit?: number;
+}
+
+/**
+ * Array helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/array.js
+ */
+export interface PanelHelpersArray {
+  /**
+   * Creates an array from an object or returns input if already array.
+   *
+   * @param object - Object or array to convert
+   * @returns Array of values
+   */
+  fromObject: <T>(object: T[] | Record<string, T>) => T[];
+
+  /**
+   * Searches through an array by query string.
+   *
+   * @param array - Array to search
+   * @param query - Search query
+   * @param options - Search options
+   * @returns Filtered array
+   */
+  search: <T extends Record<string, unknown>>(
+    array: T[],
+    query: string,
+    options?: PanelArraySearchOptions,
+  ) => T[];
+
+  /**
+   * Sorts array by field and direction.
+   *
+   * @param array - Array to sort
+   * @param sortBy - Sort specification (e.g., `'name asc'`, `'date desc'`)
+   * @returns Sorted array
+   */
+  sortBy: <T extends Record<string, unknown>>(
+    array: T[],
+    sortBy: string,
+  ) => T[];
+
+  /**
+   * Splits array into subarrays using delimiter element.
+   *
+   * @param array - Array to split
+   * @param delimiter - Element to split on
+   * @returns Array of subarrays
+   */
+  split: <T>(array: T[], delimiter: T) => T[][];
+
+  /**
+   * Wraps non-array values in an array.
+   *
+   * @param array - Value to wrap
+   * @returns Original array or wrapped value
+   */
+  wrap: <T>(array: T | T[]) => T[];
+}
+
+// -----------------------------------------------------------------------------
+// String Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Slug conversion rules.
+ */
+export type PanelSlugRules = Record<string, string>[];
+
+/**
+ * String helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/string.js
+ */
+export interface PanelHelpersString {
+  /**
+   * Converts camelCase to kebab-case.
+   *
+   * @param string - String to convert
+   * @returns Kebab-case string
+   */
+  camelToKebab: (string: string) => string;
+
+  /**
+   * Escapes HTML special characters.
+   *
+   * @param string - String to escape
+   * @returns Escaped string
+   */
+  escapeHTML: (string: string) => string;
+
+  /**
+   * Checks if string contains emoji characters.
+   *
+   * @param string - String to check
+   * @returns True if contains emoji
+   */
+  hasEmoji: (string: string) => boolean;
+
+  /**
+   * Checks if string is empty or falsy.
+   *
+   * @param string - String to check
+   * @returns True if empty
+   */
+  isEmpty: (string: string | null | undefined) => boolean;
+
+  /**
+   * Converts first letter to lowercase.
+   *
+   * @param string - String to convert
+   * @returns Converted string
+   */
+  lcfirst: (string: string) => string;
+
+  /**
+   * Trims characters from the beginning (greedy).
+   *
+   * @param string - String to trim
+   * @param replace - Characters to remove
+   * @returns Trimmed string
+   */
+  ltrim: (string: string, replace: string) => string;
+
+  /**
+   * Prefixes string with zeros until length is reached.
+   *
+   * @param value - Value to pad
+   * @param length - Target length (default: 2)
+   * @returns Padded string
+   */
+  pad: (value: string | number, length?: number) => string;
+
+  /**
+   * Generates random alphanumeric string.
+   *
+   * @param length - String length
+   * @returns Random string
+   */
+  random: (length: number) => string;
+
+  /**
+   * Trims characters from the end (greedy).
+   *
+   * @param string - String to trim
+   * @param replace - Characters to remove
+   * @returns Trimmed string
+   */
+  rtrim: (string: string, replace: string) => string;
+
+  /**
+   * Converts string to ASCII slug.
+   *
+   * @param string - String to convert
+   * @param rules - Language/ASCII conversion rules
+   * @param allowed - Allowed characters (default: `'a-z0-9'`)
+   * @param separator - Separator character (default: `'-'`)
+   * @returns Slug string
+   */
+  slug: (
+    string: string,
+    rules?: PanelSlugRules,
+    allowed?: string,
+    separator?: string,
+  ) => string;
+
+  /**
+   * Strips HTML tags from string.
+   *
+   * @param string - String to strip
+   * @returns Plain text string
+   */
+  stripHTML: (string: string) => string;
+
+  /**
+   * Replaces template placeholders with values.
+   * Supports `{{name}}` and `{{nested.prop}}` syntax.
+   *
+   * @param string - Template string
+   * @param values - Replacement values
+   * @returns Interpolated string
+   */
+  template: (string: string, values?: Record<string, unknown>) => string;
+
+  /**
+   * Converts first letter to uppercase.
+   *
+   * @param string - String to convert
+   * @returns Converted string
+   */
+  ucfirst: (string: string) => string;
+
+  /**
+   * Converts first letter of each word to uppercase.
+   *
+   * @param string - String to convert
+   * @returns Converted string
+   */
+  ucwords: (string: string) => string;
+
+  /**
+   * Converts HTML entities back to characters.
+   *
+   * @param string - String to unescape
+   * @returns Unescaped string
+   */
+  unescapeHTML: (string: string) => string;
+
+  /**
+   * Generates a UUID v4 string.
+   *
+   * @returns UUID string
+   */
+  uuid: () => string;
+}
+
+// -----------------------------------------------------------------------------
+// Object Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Object helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/object.js
+ */
+export interface PanelHelpersObject {
+  /**
+   * Deep clones an object or array using structuredClone.
+   *
+   * @param value - Value to clone
+   * @returns Cloned value
+   */
+  clone: <T>(value: T) => T;
+
+  /**
+   * Filters object entries by predicate.
+   *
+   * @param object - Object to filter
+   * @param predicate - Filter function
+   * @returns Filtered object
+   */
+  filter: <T extends Record<string, unknown>>(
+    object: T,
+    predicate: (value: T[keyof T], key: string) => boolean,
+  ) => Partial<T>;
+
+  /**
+   * Checks if value is empty (null, undefined, '', empty object/array).
+   *
+   * @param value - Value to check
+   * @returns True if empty
+   */
+  isEmpty: (value: unknown) => boolean;
+
+  /**
+   * Checks if input is a plain object (not array, null, etc.).
+   *
+   * @param input - Value to check
+   * @returns True if plain object
+   */
+  isObject: (input: unknown) => input is Record<string, unknown>;
+
+  /**
+   * Counts keys in an object.
+   *
+   * @param object - Object to count
+   * @returns Number of keys
+   */
+  length: (object: Record<string, unknown>) => number;
+
+  /**
+   * Recursively merges source into target.
+   *
+   * @param target - Target object
+   * @param source - Source object
+   * @returns Merged object
+   */
+  merge: <T extends Record<string, unknown>>(
+    target: T,
+    source?: Partial<T>,
+  ) => T;
+
+  /**
+   * Compares objects by JSON stringification.
+   *
+   * @param a - First object
+   * @param b - Second object
+   * @returns True if identical
+   */
+  same: (a: unknown, b: unknown) => boolean;
+
+  /**
+   * Converts all object keys to lowercase.
+   *
+   * @param obj - Object to convert
+   * @returns Object with lowercase keys
+   */
+  toLowerKeys: <T>(obj: Record<string, T>) => Record<string, T>;
+}
+
+// -----------------------------------------------------------------------------
+// URL Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * URL helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/url.js
+ */
+export interface PanelHelpersUrl {
+  /**
+   * Returns the base URL from the `<base>` element or window origin.
+   *
+   * @returns Base URL
+   */
+  base: () => URL;
+
+  /**
+   * Builds URLSearchParams from object, merging with origin query.
+   *
+   * @param query - Query parameters
+   * @param origin - Existing URL or query string
+   * @returns URLSearchParams object
+   */
+  buildQuery: (
+    query?: Record<string, string | number | boolean | null>,
+    origin?: string | URL,
+  ) => URLSearchParams;
+
+  /**
+   * Builds a full URL object with query parameters.
+   *
+   * @param url - URL path or object
+   * @param query - Query parameters
+   * @param origin - Base origin URL
+   * @returns Complete URL object
+   */
+  buildUrl: (
+    url?: string | URL,
+    query?: Record<string, string | number | boolean | null>,
+    origin?: string | URL,
+  ) => URL;
+
+  /**
+   * Checks if URL string starts with http:// or https://.
+   *
+   * @param url - URL to check
+   * @returns True if absolute
+   */
+  isAbsolute: (url: string) => boolean;
+
+  /**
+   * Checks if URL is on the same origin as current page.
+   *
+   * @param url - URL to check
+   * @returns True if same origin
+   */
+  isSameOrigin: (url: string | URL) => boolean;
+
+  /**
+   * Validates URL format.
+   *
+   * @param url - URL to validate
+   * @param strict - Use Kirby's URL regex for validation
+   * @returns True if valid URL
+   */
+  isUrl: (url: string | URL, strict?: boolean) => boolean;
+
+  /**
+   * Converts relative path to absolute URL.
+   *
+   * @param path - Path to convert
+   * @param origin - Base origin
+   * @returns Absolute URL string
+   */
+  makeAbsolute: (path: string, origin?: string | URL) => string;
+
+  /**
+   * Converts string to URL object.
+   *
+   * @param url - URL string or object
+   * @param origin - Base origin for relative URLs
+   * @returns URL object
+   */
+  toObject: (url: string | URL, origin?: string | URL) => URL;
+}
+
+// -----------------------------------------------------------------------------
+// Clipboard Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Clipboard helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/clipboard.js
+ */
+export interface PanelHelpersClipboard {
+  /**
+   * Reads from clipboard event or string.
+   *
+   * @param event - ClipboardEvent or string
+   * @param plain - Read as plain text only
+   * @returns Clipboard content
+   */
+  read: (event: ClipboardEvent | string, plain?: boolean) => string;
+
+  /**
+   * Writes to clipboard. Objects are auto-JSONified.
+   *
+   * @param value - Value to write
+   * @param event - ClipboardEvent for event-based writing
+   */
+  write: (value: unknown, event?: ClipboardEvent) => void;
+}
+
+// -----------------------------------------------------------------------------
+// Embed Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Embed helper utilities for video providers.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/embed.js
+ */
+export interface PanelHelpersEmbed {
+  /**
+   * Converts YouTube URL to embed URL.
+   *
+   * @param url - YouTube video URL
+   * @param doNotTrack - Enable privacy-enhanced mode
+   * @returns Embed URL or null
+   */
+  youtube: (url: string, doNotTrack?: boolean) => string | null;
+
+  /**
+   * Converts Vimeo URL to embed URL.
+   *
+   * @param url - Vimeo video URL
+   * @param doNotTrack - Enable do-not-track mode
+   * @returns Embed URL or null
+   */
+  vimeo: (url: string, doNotTrack?: boolean) => string | null;
+
+  /**
+   * Auto-detects provider and converts to embed URL.
+   *
+   * @param url - Video URL
+   * @param doNotTrack - Privacy mode
+   * @returns Embed URL or null
+   */
+  video: (url: string, doNotTrack?: boolean) => string | null;
+}
+
+// -----------------------------------------------------------------------------
+// Field Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Field definition object.
+ */
+export interface PanelFieldDefinition {
+  /** Field type */
+  type?: string;
+  /** Default value */
+  default?: unknown;
+  /** Whether field is disabled */
+  disabled?: boolean;
+  /** Conditional visibility */
+  when?: Record<string, unknown>;
+  /** API endpoint */
+  endpoints?: { field?: string; section?: string };
+  /** Nested fields */
+  fields?: Record<string, PanelFieldDefinition>;
+  /** Additional properties */
+  [key: string]: unknown;
+}
+
+/**
+ * Field helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/field.js
+ */
+export interface PanelHelpersField {
+  /**
+   * Gets default value for a field definition.
+   *
+   * @param field - Field definition
+   * @returns Default value
+   */
+  defaultValue: (field: PanelFieldDefinition) => unknown;
+
+  /**
+   * Creates form values object from field definitions.
+   *
+   * @param fields - Field definitions
+   * @returns Form values object
+   */
+  form: (
+    fields: Record<string, PanelFieldDefinition>,
+  ) => Record<string, unknown>;
+
+  /**
+   * Checks if field is visible based on 'when' conditions.
+   *
+   * @param field - Field definition
+   * @param values - Current form values
+   * @returns True if visible
+   */
+  isVisible: (
+    field: PanelFieldDefinition,
+    values: Record<string, unknown>,
+  ) => boolean;
+
+  /**
+   * Propagates parent field's API endpoints to nested subfield definitions.
+   *
+   * @param field - Parent field
+   * @param fields - Subfield definitions
+   * @returns Enhanced field definitions
+   */
+  subfields: (
+    field: PanelFieldDefinition,
+    fields: Record<string, PanelFieldDefinition>,
+  ) => Record<string, PanelFieldDefinition>;
+}
+
+// -----------------------------------------------------------------------------
+// File Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * File helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/file.js
+ */
+export interface PanelHelpersFile {
+  /**
+   * Extracts file extension from filename.
+   *
+   * @param filename - Filename
+   * @returns Extension without dot
+   */
+  extension: (filename: string) => string;
+
+  /**
+   * Extracts filename without extension.
+   *
+   * @param filename - Filename
+   * @returns Name without extension
+   */
+  name: (filename: string) => string;
+
+  /**
+   * Formats byte size as human-readable string.
+   *
+   * @param size - Size in bytes
+   * @returns Formatted size (e.g., `'1.2 MB'`)
+   */
+  niceSize: (size: number) => string;
+}
+
+// -----------------------------------------------------------------------------
+// Keyboard Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Keyboard helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/keyboard.js
+ */
+export interface PanelHelpersKeyboard {
+  /**
+   * Returns the meta key name for the current OS.
+   *
+   * @returns 'cmd' on Mac, 'ctrl' on other OS
+   */
+  metaKey: () => "cmd" | "ctrl";
+}
+
+// -----------------------------------------------------------------------------
+// Link Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Link type definition.
+ */
+export interface PanelLinkType {
+  /** Detection function */
+  detect: (value: string) => boolean;
+  /** Icon name */
+  icon: string;
+  /** Type identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Extracts link from value */
+  link: (value: string) => string;
+  /** Input placeholder */
+  placeholder?: string;
+  /** Input validation pattern */
+  pattern?: string;
+  /** Input type */
+  input?: string;
+  /** Converts input to stored value */
+  value: (value: string) => string;
+}
+
+/**
+ * Detected link result.
+ */
+export interface PanelLinkDetection {
+  /** Detected type */
+  type: string;
+  /** Extracted link */
+  link: string;
+}
+
+/**
+ * Link preview data.
+ */
+export interface PanelLinkPreview {
+  /** Display label */
+  label: string;
+  /** Preview image */
+  image?: { url: string; [key: string]: unknown };
+}
+
+/**
+ * Link helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/link.js
+ */
+export interface PanelHelpersLink {
+  /**
+   * Detects link type and extracts link value.
+   *
+   * @param value - Link value to detect
+   * @param types - Custom type definitions
+   * @returns Detection result
+   */
+  detect: (
+    value: string,
+    types?: Record<string, PanelLinkType>,
+  ) => PanelLinkDetection;
+
+  /**
+   * Converts file permalink to file:// UUID.
+   *
+   * @param value - Permalink value
+   * @returns File UUID
+   */
+  getFileUUID: (value: string) => string;
+
+  /**
+   * Converts page permalink to page:// UUID.
+   *
+   * @param value - Permalink value
+   * @returns Page UUID
+   */
+  getPageUUID: (value: string) => string;
+
+  /**
+   * Checks if value is a file UUID or permalink.
+   *
+   * @param value - Value to check
+   * @returns True if file reference
+   */
+  isFileUUID: (value: string) => boolean;
+
+  /**
+   * Checks if value is a page UUID or permalink.
+   *
+   * @param value - Value to check
+   * @returns True if page reference
+   */
+  isPageUUID: (value: string) => boolean;
+
+  /**
+   * Fetches preview data for a link.
+   *
+   * @param link - Link detection result
+   * @param fields - Fields to fetch
+   * @returns Preview data or null
+   */
+  preview: (
+    link: PanelLinkDetection,
+    fields?: string[],
+  ) => Promise<PanelLinkPreview | null>;
+
+  /**
+   * Returns available link types.
+   *
+   * @param keys - Filter to specific types
+   * @returns Link type definitions
+   */
+  types: (keys?: string[]) => Record<string, PanelLinkType>;
+}
+
+// -----------------------------------------------------------------------------
+// Page Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Page status button props.
+ */
+export interface PanelPageStatusProps {
+  /** Status text */
+  text: string;
+  /** Status icon */
+  icon: string;
+  /** Status color */
+  theme?: string;
+  /** Whether disabled */
+  disabled?: boolean;
+}
+
+/**
+ * Page helper utilities.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/page.js
+ */
+export interface PanelHelpersPage {
+  /**
+   * Returns props for page status button.
+   *
+   * @param status - Page status ('draft', 'unlisted', 'listed')
+   * @param disabled - Whether to disable
+   * @returns Button props
+   */
+  status: (status: string, disabled?: boolean) => PanelPageStatusProps;
+}
+
+// -----------------------------------------------------------------------------
+// Upload Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Upload progress callback.
+ */
+export type PanelUploadProgressCallback = (
+  xhr: XMLHttpRequest,
+  file: File,
+  percent: number,
+) => void;
+
+/**
+ * Upload complete callback.
+ */
+export type PanelUploadCompleteCallback = (
+  xhr: XMLHttpRequest,
+  file: File,
+  response: unknown,
+) => void;
+
+/**
+ * Upload parameters.
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/upload.js
+ */
+export interface PanelUploadParams {
+  /** Upload endpoint URL */
+  url: string;
+  /** HTTP method (default: `'POST'`) */
+  method?: string;
+  /** Form field name (default: `'file'`) */
+  field?: string;
+  /** Override filename */
+  filename?: string;
+  /** Request headers */
+  headers?: Record<string, string>;
+  /** Additional form attributes */
+  attributes?: Record<string, unknown>;
+  /** AbortSignal for cancellation */
+  abort?: AbortSignal;
+  /** Progress callback */
+  progress?: PanelUploadProgressCallback;
+  /** Complete callback */
+  complete?: PanelUploadCompleteCallback;
+  /** Success callback */
+  success?: PanelUploadCompleteCallback;
+  /** Error callback */
+  error?: PanelUploadCompleteCallback;
+}
+
+// -----------------------------------------------------------------------------
+// Debounce/Throttle Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Debounce options.
+ */
+export interface PanelDebounceOptions {
+  /** Call on leading edge (default: false) */
+  leading?: boolean;
+  /** Call on trailing edge (default: true) */
+  trailing?: boolean;
+}
+
+/**
+ * Throttle options.
+ */
+export interface PanelThrottleOptions {
+  /** Call on leading edge (default: true) */
+  leading?: boolean;
+  /** Call on trailing edge (default: false) */
+  trailing?: boolean;
+}
+
+/**
+ * Debounced/throttled function with cancel method.
+ */
+export interface PanelDebouncedFunction<
+  T extends (...args: unknown[]) => unknown,
+> {
+  (...args: Parameters<T>): ReturnType<T> | undefined;
+  /** Cancels pending invocation */
+  cancel: () => void;
+}
+
+// -----------------------------------------------------------------------------
+// Sort Helper
+// -----------------------------------------------------------------------------
+
+/**
+ * Sort options.
+ */
+export interface PanelSortOptions {
+  /** Sort descending (default: false) */
+  desc?: boolean;
+  /** Case insensitive comparison (default: false) */
+  insensitive?: boolean;
+}
+
+/**
+ * Comparator function for sorting.
+ */
+export type PanelComparator = (a: string, b: string) => number;
+
+// -----------------------------------------------------------------------------
+// Main Helpers Interface
+// -----------------------------------------------------------------------------
+
+/**
+ * Panel helpers available on the Vue prototype as `$helper`.
+ *
+ * Provides utility functions for common operations.
+ *
+ * @example
+ * ```ts
+ * // In a Vue component
+ * this.$helper.string.slug('Hello World');
+ * this.$helper.clone(someObject);
+ * this.$helper.uuid();
+ * ```
+ *
+ * @see https://github.com/getkirby/kirby/blob/main/panel/src/helpers/index.js
+ */
+export interface PanelHelpers {
+  /** Array utilities */
+  array: PanelHelpersArray;
+
+  /** Clipboard utilities */
+  clipboard: PanelHelpersClipboard;
+
+  /**
+   * Deep clones a value.
+   * Shortcut for `object.clone()`.
+   */
+  clone: <T>(value: T) => T;
+
+  /**
+   * Resolves CSS color to CSS variable.
+   *
+   * @param value - Color name or value
+   * @returns CSS variable or original value
+   */
+  color: (value: string) => string;
+
+  /**
+   * Creates a debounced function.
+   *
+   * @param fn - Function to debounce
+   * @param delay - Delay in milliseconds
+   * @param options - Debounce options
+   * @returns Debounced function with cancel method
+   */
+  debounce: <T extends (...args: unknown[]) => unknown>(
+    fn: T,
+    delay: number,
+    options?: PanelDebounceOptions,
+  ) => PanelDebouncedFunction<T>;
+
+  /** Video embed utilities */
+  embed: PanelHelpersEmbed;
+
+  /** Field utilities */
+  field: PanelHelpersField;
+
+  /** File utilities */
+  file: PanelHelpersFile;
+
+  /**
+   * Sets focus to element or first focusable child.
+   *
+   * @param element - Selector or element
+   * @param field - Specific input name to focus
+   */
+  focus: (element: string | HTMLElement, field?: string) => void;
+
+  /**
+   * Checks if component is registered globally.
+   *
+   * @param name - Component name
+   * @returns True if registered
+   */
+  isComponent: (name: string) => boolean;
+
+  /**
+   * Checks if event is a file drag/drop event.
+   *
+   * @param event - Event to check
+   * @returns True if file upload event
+   */
+  isUploadEvent: (event: Event) => boolean;
+
+  /** Keyboard utilities */
+  keyboard: PanelHelpersKeyboard;
+
+  /** Link utilities */
+  link: PanelHelpersLink;
+
+  /** Object utilities */
+  object: PanelHelpersObject;
+
+  /**
+   * Left-pads value with zeros.
+   * Shortcut for `string.pad()`.
+   */
+  pad: (value: string | number, length?: number) => string;
+
+  /** Page utilities */
+  page: PanelHelpersPage;
+
+  /**
+   * Converts aspect ratio to percentage.
+   *
+   * @param fraction - Ratio string (e.g., `'3/2'`)
+   * @param fallback - Fallback value (default: `'100%'`)
+   * @param vertical - Calculate for vertical orientation
+   * @returns Percentage string
+   */
+  ratio: (fraction?: string, fallback?: string, vertical?: boolean) => string;
+
+  /**
+   * Converts string to slug.
+   * Shortcut for `string.slug()`.
+   */
+  slug: (
+    string: string,
+    rules?: PanelSlugRules,
+    allowed?: string,
+    separator?: string,
+  ) => string;
+
+  /**
+   * Creates a sort comparator function.
+   *
+   * @param options - Sort options
+   * @returns Comparator function
+   */
+  sort: (options?: PanelSortOptions) => PanelComparator;
+
+  /** String utilities */
+  string: PanelHelpersString;
+
+  /**
+   * Creates a throttled function.
+   *
+   * @param fn - Function to throttle
+   * @param delay - Delay in milliseconds
+   * @param options - Throttle options
+   * @returns Throttled function with cancel method
+   */
+  throttle: <T extends (...args: unknown[]) => unknown>(
+    fn: T,
+    delay: number,
+    options?: PanelThrottleOptions,
+  ) => PanelDebouncedFunction<T>;
+
+  /**
+   * Uploads a file via XMLHttpRequest.
+   *
+   * @param file - File to upload
+   * @param params - Upload parameters
+   * @returns Promise resolving to response
+   */
+  upload: (file: File, params: PanelUploadParams) => Promise<unknown>;
+
+  /** URL utilities */
+  url: PanelHelpersUrl;
+
+  /**
+   * Generates UUID v4 string.
+   * Shortcut for `string.uuid()`.
+   */
+  uuid: () => string;
+}