kirby-types 1.1.2 → 1.3.0

package/src/panel/index.d.ts

@@ -6,11 +6,13 @@
  * This is the main entry point for all Panel type definitions.
  * Types are organized into modules for better maintainability:
  *
- * - `panel.base.ts` - State, Feature, Modal, History, Event Listeners
- * - `panel.features.ts` - View, Dialog, Drawer, Dropdown, Notification, etc.
- * - `panel.helpers.ts` - $helper.* utilities
- * - `panel.libraries.ts` - $library.* (colors, dayjs, autosize)
- * - `panel.api.ts` - API client methods
+ * - `base.d.ts` - State, Feature, Modal, History, Event Listeners
+ * - `features.d.ts` - View, Dialog, Drawer, Dropdown, Notification, etc.
+ * - `helpers.d.ts` - $helper.* utilities
+ * - `libraries.d.ts` - $library.* (colors, dayjs, autosize)
+ * - `api.d.ts` - API client methods
+ * - `writer.d.ts` - Writer (ProseMirror) editor and extensions
+ * - `textarea.d.ts` - Textarea toolbar buttons
  *
  * @see https://github.com/getkirby/kirby/tree/main/panel/src/panel
  * @since 4.0.0
@@ -26,56 +28,43 @@ import type {
 import type * as PanelFeatures from "./features";
 import type { PanelHelpers } from "./helpers";
 import type { PanelLibrary } from "./libraries";
+import type { TextareaButton } from "./textarea";
+import type { WriterMarkExtension, WriterNodeExtension } from "./writer";
 
 // =============================================================================
-// Re-exports from panel.api.ts
+// Re-exports from api.d.ts
 // =============================================================================
 
 export type {
-  // Request Types
-  PanelApiRequestOptions,
-  PanelApiPagination,
-  PanelApiSearchQuery,
   // Auth
-  PanelApiLoginData,
   PanelApiAuth,
   // Files
   PanelApiFiles,
   // Languages
-  PanelApiLanguageData,
   PanelApiLanguages,
   // Pages
-  PanelApiPageCreateData,
-  PanelApiPageDuplicateOptions,
   PanelApiPages,
   // Roles
   PanelApiRoles,
   // Site
   PanelApiSite,
   // System
-  PanelApiSystemInstallData,
-  PanelApiSystemRegisterData,
   PanelApiSystem,
   // Translations
   PanelApiTranslations,
   // Users
-  PanelApiUserCreateData,
   PanelApiUsers,
   // Main API Interface
   PanelApi,
 } from "./api";
 
 // =============================================================================
-// Re-exports from panel.base.ts
+// Re-exports from base.d.ts
 // =============================================================================
 
 export type {
   // State Management
   PanelState,
-  PanelStateBase,
-  PanelFeatureBase,
-  PanelModalBase,
-  PanelHistoryBase,
   // Event Listeners
   PanelEventCallback,
   PanelEventListenerMap,
@@ -102,55 +91,43 @@ export type {
 } from "./base";
 
 // =============================================================================
-// Re-exports from panel.features.ts
+// Re-exports from features.d.ts
 // =============================================================================
 
 export type {
   // Timer
   PanelTimer,
   // Activation
-  PanelActivationDefaults,
   PanelActivation,
   // Drag
-  PanelDragDefaults,
   PanelDrag,
   // Theme
-  PanelThemeDefaults,
   PanelThemeValue,
   PanelTheme,
   // Language
-  PanelLanguageDefaults,
   PanelLanguage,
   // Menu
   PanelMenuEntry,
-  PanelMenuDefaults,
   PanelMenu,
   // Notification
-  PanelNotificationDefaults,
   PanelNotificationOptions,
   PanelErrorObject,
   PanelNotification,
   // System
-  PanelSystemDefaults,
   PanelSystem,
   // Translation
-  PanelTranslationDefaults,
   PanelTranslation,
   // User
-  PanelUserDefaults,
   PanelUser,
   // View
   PanelBreadcrumbItem,
-  PanelViewDefaults,
   PanelView,
   // Dropdown
   PanelDropdownOption,
   PanelDropdown,
   // Dialog
-  PanelDialogDefaults,
   PanelDialog,
   // Drawer
-  PanelDrawerDefaults,
   PanelDrawer,
   // Content
   PanelContentVersion,
@@ -165,100 +142,61 @@ export type {
   PanelSearcher,
   // Upload
   PanelUploadFile,
-  PanelUploadDefaults,
   PanelUpload,
   // Events
-  PanelKeychain,
   PanelEventEmitter,
   PanelEvents,
 } from "./features";
 
 // =============================================================================
-// Re-exports from panel.helpers.ts
+// Re-exports from helpers.d.ts
 // =============================================================================
 
 export type {
-  // Array
-  PanelArraySearchOptions,
-  PanelHelpersArray,
-  // String
-  PanelSlugRules,
-  PanelHelpersString,
-  // Object
-  PanelHelpersObject,
-  // URL
-  PanelHelpersUrl,
-  // Clipboard
-  PanelHelpersClipboard,
-  // Embed
-  PanelHelpersEmbed,
-  // Field
-  PanelFieldDefinition,
-  PanelHelpersField,
-  // File
-  PanelHelpersFile,
-  // Keyboard
-  PanelHelpersKeyboard,
-  // Link
-  PanelLinkType,
-  PanelLinkDetection,
-  PanelLinkPreview,
-  PanelHelpersLink,
-  // Page
-  PanelPageStatusProps,
-  PanelHelpersPage,
-  // Upload
-  PanelUploadProgressCallback,
-  PanelUploadCompleteCallback,
-  PanelUploadParams,
-  // Utility Types
-  PanelDebounceOptions,
-  PanelThrottleOptions,
-  PanelDebouncedFunction,
-  PanelSortOptions,
-  PanelComparator,
   // Main Helpers Interface
   PanelHelpers,
 } from "./helpers";
 
 // =============================================================================
-// Re-exports from panel.libraries.ts
+// Re-exports from libraries.d.ts
 // =============================================================================
 
 export type {
-  // Color Types
-  PanelColorFormat,
-  PanelColorRGB,
-  PanelColorHSL,
-  PanelColorHSV,
-  PanelColorObject,
-  PanelColorInput,
-  PanelLibraryColors,
-  // Dayjs Types
-  PanelDayjsISOFormat,
-  PanelDayjsPatternPart,
-  PanelDayjsPattern,
-  PanelDayjsInstance,
-  PanelDayjsInput,
-  PanelDayjsUnit,
-  PanelLibraryDayjs,
-  // Autosize
-  PanelLibraryAutosize,
   // Main Library Interface
   PanelLibrary,
 } from "./libraries";
 
 // =============================================================================
-// Re-exports from panel.writer.ts
+// Re-exports from textarea.d.ts
 // =============================================================================
 
 export type {
+  // Textarea Toolbar
+  TextareaButton,
+  TextareaToolbarContext,
+} from "./textarea";
+
+// =============================================================================
+// Re-exports from writer.d.ts
+// =============================================================================
+
+export type {
+  // Writer Editor
+  WriterEditor,
+  // Writer Toolbar
+  WriterToolbarButton,
   // Writer Utilities
   WriterUtils,
   // Writer Contexts
   WriterMarkContext,
   WriterNodeContext,
   WriterExtensionContext,
+  // Writer Schemas
+  WriterMarkSchema,
+  WriterNodeSchema,
+  // Writer Extensions
+  WriterMarkExtension,
+  WriterNodeExtension,
 } from "./writer";
 
 // =============================================================================
@@ -275,27 +213,21 @@ 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;
 };
 
 // =============================================================================
 // Panel Configuration
 // =============================================================================
 
-/**
- * Panel API configuration.
- */
-export interface PanelConfigApi {
-  /** Whether to use method override for PUT/PATCH/DELETE */
-  methodOverride: boolean;
-}
-
 /**
  * Global Panel configuration.
  *
@@ -303,7 +235,10 @@ export interface PanelConfigApi {
  */
 export interface PanelConfig {
   /** API configuration */
-  api: PanelConfigApi;
+  api: {
+    /** Whether to use method override for PUT/PATCH/DELETE */
+    methodOverride: boolean;
+  };
   /** Whether debug mode is enabled */
   debug: boolean;
   /** Whether KirbyText is enabled */
@@ -323,7 +258,7 @@ export interface PanelConfig {
 /**
  * Access permissions for Panel areas.
  */
-export interface PanelPermissionsAccess {
+interface PanelPermissionsAccess {
   account: boolean;
   languages: boolean;
   panel: boolean;
@@ -335,7 +270,7 @@ export interface PanelPermissionsAccess {
 /**
  * File operation permissions.
  */
-export interface PanelPermissionsFiles {
+interface PanelPermissionsFiles {
   access: boolean;
   changeName: boolean;
   changeTemplate: boolean;
@@ -351,7 +286,7 @@ export interface PanelPermissionsFiles {
 /**
  * Language operation permissions.
  */
-export interface PanelPermissionsLanguages {
+interface PanelPermissionsLanguages {
   create: boolean;
   delete: boolean;
   update: boolean;
@@ -360,7 +295,7 @@ export interface PanelPermissionsLanguages {
 /**
  * Page operation permissions.
  */
-export interface PanelPermissionsPages {
+interface PanelPermissionsPages {
   access: boolean;
   changeSlug: boolean;
   changeStatus: boolean;
@@ -380,7 +315,7 @@ export interface PanelPermissionsPages {
 /**
  * Site operation permissions.
  */
-export interface PanelPermissionsSite {
+interface PanelPermissionsSite {
   changeTitle: boolean;
   update: boolean;
 }
@@ -388,7 +323,7 @@ export interface PanelPermissionsSite {
 /**
  * User management permissions (for other users).
  */
-export interface PanelPermissionsUsers {
+interface PanelPermissionsUsers {
   changeEmail: boolean;
   changeLanguage: boolean;
   changeName: boolean;
@@ -402,7 +337,7 @@ export interface PanelPermissionsUsers {
 /**
  * Current user permissions (for own account).
  */
-export interface PanelPermissionsUser {
+interface PanelPermissionsUser {
   changeEmail: boolean;
   changeLanguage: boolean;
   changeName: boolean;
@@ -468,96 +403,117 @@ export interface PanelUrls {
 }
 
 // =============================================================================
-// Panel Plugins
+// Panel Request Response
 // =============================================================================
 
 /**
- * Third-party plugin data.
- */
-export type PanelPluginsThirdParty = Record<string, any>;
-
-/**
- * Custom view button definitions.
- */
-export type PanelPluginsViewButtons = Record<
-  string,
-  ComponentPublicInstance | Record<string, any>
->;
-
-/**
- * Custom writer node definitions.
- */
-export type PanelPluginsWriterNodes = Record<string, Record<string, any>>;
+ * 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;
+  };
+}
 
-/**
- * Custom view definitions.
- */
-export type PanelPluginsViews = Record<string, Record<string, any>>;
+// =============================================================================
+// Panel Plugins
+// =============================================================================
 
 /**
  * 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 */
-  created: Array<() => void>;
+  /** Callbacks to run after Panel creation */
+  created: (() => void)[];
 
   /** Registered SVG icons */
   icons: Record<string, string>;
 
-  /** Custom login component */
+  /** Custom login component (set dynamically by plugins) */
   login: ComponentPublicInstance | null;
 
-  /** Custom textarea buttons */
-  textareaButtons: Record<string, Record<string, any>>;
-
-  /** Third-party plugin data */
-  thirdParty: PanelPluginsThirdParty;
+  /** Registered Panel routes */
+  routes: Record<string, any>[];
 
   /**
-   * Registers plugins with the Panel.
+   * Registered textarea toolbar buttons.
+   * @see https://getkirby.com/docs/reference/plugins/extensions/textarea-buttons
    */
-  use: (plugins: Record<string, any>) => any[];
+  textareaButtons: Record<string, TextareaButton>;
 
-  /** Custom view buttons */
-  viewButtons: PanelPluginsViewButtons;
+  /** Registered third-party plugin data */
+  thirdParty: Record<string, any>;
 
-  /** Custom writer marks */
-  writerMarks: Record<string, Record<string, any>>;
+  /** Installed Vue plugins via `Vue.use()` */
+  use: any[];
 
-  /** Custom writer nodes */
-  writerNodes: PanelPluginsWriterNodes;
+  /** Registered view buttons */
+  viewButtons: Record<string, ComponentPublicInstance | Record<string, any>>;
 
-  /** Custom routes */
-  routes: Array<Record<string, any>>;
+  /** Registered Panel views */
+  views: Record<string, Record<string, any>>;
 
-  /** Custom views */
-  views: PanelPluginsViews;
+  /**
+   * Registered writer marks.
+   * @see https://getkirby.com/docs/reference/plugins/extensions/writer-marks
+   */
+  writerMarks: Record<string, WriterMarkExtension>;
+
+  /**
+   * Registered writer nodes.
+   * @see https://getkirby.com/docs/reference/plugins/extensions/writer-nodes
+   */
+  writerNodes: Record<string, WriterNodeExtension>;
 }
 
 // =============================================================================
@@ -568,7 +524,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 +545,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 +575,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 +730,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 +747,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 +802,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.
    *
-   * @param type - Search type ('pages', 'files', 'users')
-   * @param query - Search query
-   * @param options - Request options
-   * @returns Search results
+   * 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 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.
@@ -904,7 +877,7 @@ export interface Panel {
 /**
  * Lock information for content.
  */
-export interface PanelViewPropsLockUser {
+interface PanelViewPropsLockUser {
   id: string;
   email: string;
 }
@@ -912,7 +885,7 @@ export interface PanelViewPropsLockUser {
 /**
  * Content lock state.
  */
-export interface PanelViewPropsLock {
+interface PanelViewPropsLock {
   isLegacy: boolean;
   isLocked: boolean;
   modified: string | null;
@@ -922,7 +895,7 @@ export interface PanelViewPropsLock {
 /**
  * Content permissions for a view.
  */
-export interface PanelViewPropsPermissions {
+interface PanelViewPropsPermissions {
   access: boolean;
   changeSlug: boolean;
   changeStatus: boolean;
@@ -942,7 +915,7 @@ export interface PanelViewPropsPermissions {
 /**
  * Version information.
  */
-export interface PanelViewPropsVersions {
+interface PanelViewPropsVersions {
   latest: Record<string, any>;
   changes: Record<string, any>;
 }
@@ -950,10 +923,10 @@ export interface PanelViewPropsVersions {
 /**
  * Tab definition.
  */
-export interface PanelViewPropsTab {
+interface PanelViewPropsTab {
   label: string;
   icon: string;
-  columns: Array<Record<string, any>>;
+  columns: Record<string, any>[];
   link: string;
   name: string;
 }
@@ -961,7 +934,7 @@ export interface PanelViewPropsTab {
 /**
  * Navigation link (next/prev).
  */
-export interface PanelViewPropsNavigation {
+interface PanelViewPropsNavigation {
   link: string;
   title: string;
 }
@@ -969,7 +942,7 @@ export interface PanelViewPropsNavigation {
 /**
  * Model information.
  */
-export interface PanelViewPropsModel {
+interface PanelViewPropsModel {
   id: string;
   link: string;
   parent: string;
@@ -982,7 +955,7 @@ export interface PanelViewPropsModel {
 /**
  * Button definition.
  */
-export interface PanelViewPropsButton {
+interface PanelViewPropsButton {
   component: string;
   key: string;
   props: {
@@ -1009,7 +982,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;