kirby-types 1.4.7 → 1.4.9

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "kirby-types",
   "type": "module",
-  "version": "1.4.7",
-  "packageManager": "pnpm@10.27.0",
+  "version": "1.4.9",
+  "packageManager": "pnpm@10.33.2",
   "description": "TypeScript types for Kirby Panel plugins and headless CMS usage",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
   "license": "MIT",
@@ -79,12 +79,12 @@
     }
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^6.7.3",
-    "bumpp": "^10.3.2",
-    "dayjs": "^1.11.13",
-    "eslint": "^9.39.2",
-    "prettier": "^3.7.4",
+    "@antfu/eslint-config": "^8.2.0",
+    "bumpp": "^11.0.1",
+    "dayjs": "^1.11.20",
+    "eslint": "^10.2.1",
+    "prettier": "^3.8.3",
     "tsd": "^0.33.0",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   }
 }

package/src/panel/api.d.ts

@@ -15,6 +15,8 @@ import type { PanelRequestOptions } from "./base";
 
 /**
  * API request options.
+ * @source panel/src/api/request.js
+ * @source panel/src/api/index.js
  */
 export interface PanelApiRequestOptions extends PanelRequestOptions {
   /** Whether to skip loading indicator */
@@ -23,6 +25,7 @@ export interface PanelApiRequestOptions extends PanelRequestOptions {
 
 /**
  * Pagination query parameters.
+ * @source panel/src/api/index.js
  */
 export interface PanelApiPagination {
   /** Page number */
@@ -33,6 +36,7 @@ export interface PanelApiPagination {
 
 /**
  * Search query parameters.
+ * @source panel/src/api/index.js
  */
 export interface PanelApiSearchQuery extends PanelApiPagination {
   /** Search query string */
@@ -64,6 +68,7 @@ export interface PanelApiSearchQuery extends PanelApiPagination {
  *   status: "draft" | "unlisted" | "listed";
  * }
  * ```
+ * @source panel/src/api/request.js
  */
 export interface PanelModelData<TContent = Record<string, any>> {
   /** Model identifier (page id, file id, user id; undefined for site) */
@@ -80,6 +85,7 @@ export interface PanelModelData<TContent = Record<string, any>> {
 
 /**
  * User authentication data.
+ * @source panel/src/api/auth.js
  */
 export interface PanelApiLoginData {
   /** User email */
@@ -94,6 +100,7 @@ export interface PanelApiLoginData {
  * Authentication API methods.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/auth.js
+ * @source panel/src/api/auth.js
  */
 export interface PanelApiAuth {
   /**
@@ -104,14 +111,10 @@ export interface PanelApiAuth {
    */
   login: (data: PanelApiLoginData) => Promise<any>;
 
-  /**
-   * Logs out the current user.
-   */
+  /** Logs out the current user. */
   logout: () => Promise<any>;
 
-  /**
-   * Pings the server to keep session alive.
-   */
+  /** Pings the server to keep session alive. */
   ping: () => Promise<any>;
 
   /**
@@ -139,6 +142,7 @@ export interface PanelApiAuth {
  * Files API methods.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/files.js
+ * @source panel/src/api/files.js
  */
 export interface PanelApiFiles {
   /**
@@ -224,9 +228,7 @@ export interface PanelApiFiles {
 // Languages API
 // -----------------------------------------------------------------------------
 
-/**
- * Language data for create/update.
- */
+/** Language data for create/update. */
 export interface PanelApiLanguageData {
   /** Language code */
   code: string;
@@ -246,6 +248,7 @@ export interface PanelApiLanguageData {
  * Languages API methods.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/languages.js
+ * @source panel/src/api/languages.js
  */
 export interface PanelApiLanguages {
   /**
@@ -292,9 +295,7 @@ export interface PanelApiLanguages {
 // Pages API
 // -----------------------------------------------------------------------------
 
-/**
- * Page creation data.
- */
+/** Page creation data. */
 export interface PanelApiPageCreateData {
   /** Page slug */
   slug: string;
@@ -308,9 +309,7 @@ export interface PanelApiPageCreateData {
   status?: "draft" | "unlisted" | "listed";
 }
 
-/**
- * Page duplicate options.
- */
+/** Page duplicate options. */
 export interface PanelApiPageDuplicateOptions {
   /** Copy children pages */
   children?: boolean;
@@ -322,6 +321,7 @@ export interface PanelApiPageDuplicateOptions {
  * Pages API methods.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/pages.js
+ * @source panel/src/api/pages.js
  */
 export interface PanelApiPages {
   /**
@@ -405,6 +405,7 @@ export interface PanelApiPages {
    *
    * @param id - Page ID
    * @param data - Delete options
+   * @param data.force - Force delete even if the page has children or drafts
    */
   delete: (id: string, data?: { force?: boolean }) => Promise<any>;
 
@@ -419,7 +420,7 @@ export interface PanelApiPages {
   duplicate: (
     id: string,
     slug: string,
-    options?: PanelApiPageDuplicateOptions,
+    options: PanelApiPageDuplicateOptions,
   ) => Promise<any>;
 
   /**
@@ -460,12 +461,12 @@ export interface PanelApiPages {
    * Gets a page's preview URL.
    *
    * @param id - Page ID
-   * @returns Preview URL
+   * @returns Preview URL, or `null` when preview is disabled for the page
    */
-  preview: (id: string) => Promise<string>;
+  preview: (id: string) => Promise<string | null>;
 
   /**
-   * Searches pages.
+   * Searches direct children of a parent page (or the site root).
    *
    * @param parent - Parent page ID (null for root)
    * @param query - Search query
@@ -500,6 +501,7 @@ export interface PanelApiPages {
  * Roles API methods.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/roles.js
+ * @source panel/src/api/roles.js
  */
 export interface PanelApiRoles {
   /**
@@ -527,6 +529,7 @@ export interface PanelApiRoles {
  * Site API methods.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/site.js
+ * @source panel/src/api/site.js
  */
 export interface PanelApiSite {
   /**
@@ -580,9 +583,7 @@ export interface PanelApiSite {
 // System API
 // -----------------------------------------------------------------------------
 
-/**
- * System installation data.
- */
+/** System installation data. */
 export interface PanelApiSystemInstallData {
   /** Admin email */
   email: string;
@@ -592,9 +593,7 @@ export interface PanelApiSystemInstallData {
   language?: string;
 }
 
-/**
- * License registration data.
- */
+/** License registration data. */
 export interface PanelApiSystemRegisterData {
   /** License key */
   license: string;
@@ -606,6 +605,7 @@ export interface PanelApiSystemRegisterData {
  * System API methods.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/system.js
+ * @source panel/src/api/system.js
  */
 export interface PanelApiSystem {
   /**
@@ -620,7 +620,7 @@ export interface PanelApiSystem {
    * Installs Kirby with initial user.
    *
    * @param data - Installation data
-   * @returns Installation result
+   * @returns The newly created admin user
    */
   install: (data: PanelApiSystemInstallData) => Promise<any>;
 
@@ -641,6 +641,7 @@ export interface PanelApiSystem {
  * Translations API methods.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/translations.js
+ * @source panel/src/api/translations.js
  */
 export interface PanelApiTranslations {
   /**
@@ -663,9 +664,7 @@ export interface PanelApiTranslations {
 // Users API
 // -----------------------------------------------------------------------------
 
-/**
- * User creation data.
- */
+/** User creation data. */
 export interface PanelApiUserCreateData {
   /** User email */
   email: string;
@@ -683,6 +682,7 @@ export interface PanelApiUserCreateData {
  * Users API methods.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/users.js
+ * @source panel/src/api/users.js
  */
 export interface PanelApiUsers {
   /**
@@ -755,7 +755,7 @@ export interface PanelApiUsers {
   /**
    * Creates a new user.
    *
-   * @param data - User data (including email as identifier)
+   * @param data - User data (email is required; id is generated by Kirby)
    * @returns Created user
    */
   create: (data: PanelApiUserCreateData) => Promise<any>;
@@ -793,7 +793,7 @@ export interface PanelApiUsers {
   link: (id: string, path?: string) => string;
 
   /**
-   * Lists all users.
+   * Queries users via the users/search endpoint.
    *
    * @param query - Query parameters
    * @returns Array of users
@@ -812,13 +812,9 @@ export interface PanelApiUsers {
    * Searches users.
    *
    * @param query - Search query
-   * @param options - Query options
    * @returns Search results
    */
-  search: (
-    query?: PanelApiSearchQuery,
-    options?: Record<string, any>,
-  ) => Promise<any>;
+  search: (query?: PanelApiSearchQuery) => Promise<any>;
 
   /**
    * Updates a user's content.
@@ -862,6 +858,12 @@ export interface PanelApiUsers {
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/api/index.js
+ * @source panel/src/api/index.js
+ * @source panel/src/api/request.js
+ * @source panel/src/api/get.js
+ * @source panel/src/api/post.js
+ * @source panel/src/api/patch.js
+ * @source panel/src/api/delete.js
  */
 export interface PanelApi {
   /** CSRF token for requests */
@@ -882,8 +884,8 @@ export interface PanelApi {
   /** Number of running requests */
   running: number;
 
-  /** Current language code */
-  language: string;
+  /** Current language code (lazily set on first request, or `undefined` before any request has run) */
+  language: string | undefined;
 
   /**
    * Makes a raw API request.
@@ -921,6 +923,7 @@ export interface PanelApi {
    * @param path - API path
    * @param data - Request body
    * @param options - Request options
+   * @param method - HTTP method to send (defaults to `POST`; `patch` and `delete` delegate here to set `PATCH`/`DELETE`)
    * @param silent - Skip loading indicator
    * @returns Response data
    */
@@ -928,6 +931,7 @@ export interface PanelApi {
     path: string,
     data?: any,
     options?: PanelApiRequestOptions,
+    method?: string,
     silent?: boolean,
   ) => Promise<T>;
 

package/src/panel/base.d.ts

@@ -29,6 +29,7 @@
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/state.js
+ * @source panel/src/panel/state.js
  */
 export interface PanelState<TDefaults extends object = Record<string, any>> {
   /**
@@ -76,9 +77,8 @@ export interface PanelState<TDefaults extends object = Record<string, any>> {
 // -----------------------------------------------------------------------------
 
 /**
- * Base interface providing common state methods.
- * Used as an intermediate type for features that extend State.
  * @internal
+ * @source panel/src/panel/state.js
  */
 export interface PanelStateBase {
   key: () => string;
@@ -90,8 +90,8 @@ export interface PanelStateBase {
 }
 
 /**
- * Base interface for Features extending State with event listeners.
  * @internal
+ * @source panel/src/panel/feature.js
  */
 export interface PanelFeatureBase extends PanelStateBase, PanelEventListeners {
   abortController: AbortController | null;
@@ -105,8 +105,8 @@ export interface PanelFeatureBase extends PanelStateBase, PanelEventListeners {
 }
 
 /**
- * Base interface for Modals extending Feature.
  * @internal
+ * @source panel/src/panel/modal.js
  */
 export interface PanelModalBase extends PanelFeatureBase {
   id: string | null;
@@ -115,8 +115,8 @@ export interface PanelModalBase extends PanelFeatureBase {
 }
 
 /**
- * Base interface for History implementations.
  * @internal
+ * @source panel/src/panel/history.js
  */
 export interface PanelHistoryBase {
   milestones: PanelHistoryMilestone[];
@@ -127,12 +127,13 @@ export interface PanelHistoryBase {
 // -----------------------------------------------------------------------------
 
 /**
- * Event callback function type.
+ * @source panel/src/panel/listeners.js
  */
 export type PanelEventCallback<TReturn = any> = (...args: any[]) => TReturn;
 
 /**
  * Map of event names to their callback functions.
+ * @source panel/src/panel/listeners.js
  */
 export type PanelEventListenerMap<TEvents extends string = string> = Partial<
   Record<TEvents, PanelEventCallback>
@@ -157,12 +158,9 @@ export type PanelEventListenerMap<TEvents extends string = string> = Partial<
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/listeners.js
+ * @source panel/src/panel/listeners.js
  */
 export interface PanelEventListeners<TEvents extends string = string> {
-  /**
-   * Map of registered event listeners.
-   * Keys are event names, values are callback functions.
-   */
   on: PanelEventListenerMap<TEvents>;
 
   /**
@@ -202,9 +200,7 @@ export interface PanelEventListeners<TEvents extends string = string> {
    */
   hasEventListener: (event: TEvents) => boolean;
 
-  /**
-   * Returns all registered listeners.
-   */
+  /** Returns all registered listeners. */
   listeners: () => PanelEventListenerMap<TEvents>;
 }
 
@@ -213,7 +209,7 @@ export interface PanelEventListeners<TEvents extends string = string> {
 // -----------------------------------------------------------------------------
 
 /**
- * Default properties for Feature state.
+ * @source panel/src/panel/feature.js
  */
 export interface PanelFeatureDefaults {
   abortController: AbortController | null;
@@ -234,7 +230,7 @@ export interface PanelFeatureDefaults {
  * loading states, API requests, and event handling. They extend
  * State with HTTP request methods and the event listener mixin.
  *
- * Features include: view, dropdown, content
+ * Features include: view, dropdown.
  *
  * @typeParam TDefaults - Shape of the feature's default state
  *
@@ -248,6 +244,7 @@ export interface PanelFeatureDefaults {
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/feature.js
+ * @source panel/src/panel/feature.js
  */
 export interface PanelFeature<TDefaults extends object = PanelFeatureDefaults>
   extends PanelState<TDefaults>, PanelEventListeners {
@@ -281,19 +278,13 @@ export interface PanelFeature<TDefaults extends object = PanelFeatureDefaults>
    */
   props: Record<string, any>;
 
-  /**
-   * URL query parameters from the latest request.
-   */
+  /** URL query parameters from the latest request. */
   query: Record<string, any>;
 
-  /**
-   * Previous path for navigation and redirects.
-   */
+  /** Previous path for navigation and redirects. */
   referrer: string | null;
 
-  /**
-   * Timestamp from the backend for cache invalidation.
-   */
+  /** Timestamp from the backend for cache invalidation. */
   timestamp: number | null;
 
   /**
@@ -363,9 +354,7 @@ export interface PanelFeature<TDefaults extends object = PanelFeatureDefaults>
    */
   reload: (options?: PanelRequestOptions) => Promise<void | false>;
 
-  /**
-   * Creates a full URL object for the current path and query.
-   */
+  /** Creates a full URL object for the current path and query. */
   url: () => URL;
 }
 
@@ -375,6 +364,7 @@ export interface PanelFeature<TDefaults extends object = PanelFeatureDefaults>
 
 /**
  * Modal event types for dialogs and drawers.
+ * @source panel/src/panel/modal.js
  */
 export type PanelModalEvent =
   | "cancel"
@@ -387,6 +377,7 @@ export type PanelModalEvent =
 
 /**
  * Bound listener functions returned by `modal.listeners()`.
+ * @source panel/src/panel/modal.js
  */
 export interface PanelModalListeners {
   cancel: () => Promise<void>;
@@ -394,15 +385,14 @@ export interface PanelModalListeners {
   input: (value: any) => void;
   submit: (value?: any, options?: PanelRequestOptions) => Promise<any>;
   success: (response: PanelSuccessResponse) => void;
-  /** Additional custom event listeners */
   [key: string]: ((...args: any[]) => any) | undefined;
 }
 
 /**
  * Success response from modal submission.
+ * @source panel/src/panel/modal.js
  */
 export interface PanelSuccessResponse {
-  /** Success message to display */
   message?: string;
   /** Events to emit (string or array of strings) */
   event?: string | string[];
@@ -443,6 +433,7 @@ export interface PanelSuccessResponse {
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/modal.js
+ * @source panel/src/panel/modal.js
  */
 export interface PanelModal<
   TDefaults extends object = PanelFeatureDefaults & { id: string | null },
@@ -453,9 +444,6 @@ export interface PanelModal<
    */
   id: string | null;
 
-  /**
-   * Whether the modal is currently visible.
-   */
   isOpen: boolean;
 
   /**
@@ -470,9 +458,7 @@ export interface PanelModal<
    */
   readonly value: any;
 
-  /**
-   * Cancels the modal by emitting 'cancel' and closing.
-   */
+  /** Cancels the modal by emitting 'cancel' and closing. */
   cancel: () => Promise<void>;
 
   /**
@@ -513,7 +499,7 @@ export interface PanelModal<
 
   /**
    * Opens the modal by URL or state object.
-   * Closes any non-matching notifications and blocks document overflow.
+   * Closes the current notification on first open and blocks document overflow.
    *
    * @param modal - URL or state object
    * @param options - Request options
@@ -591,9 +577,9 @@ export interface PanelModal<
 
 /**
  * A history milestone representing a saved modal state.
+ * @source panel/src/panel/history.js
  */
 export interface PanelHistoryMilestone {
-  /** Unique identifier for this milestone */
   id: string;
   /** Additional state properties */
   [key: string]: any;
@@ -616,11 +602,9 @@ export interface PanelHistoryMilestone {
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/history.js
+ * @source panel/src/panel/history.js
  */
 export interface PanelHistory {
-  /**
-   * Array of stored state milestones.
-   */
   milestones: PanelHistoryMilestone[];
 
   /**
@@ -642,9 +626,7 @@ export interface PanelHistory {
    */
   at: (index: number) => PanelHistoryMilestone | undefined;
 
-  /**
-   * Clears all milestones from history.
-   */
+  /** Clears all milestones from history. */
   clear: () => void;
 
   /**
@@ -680,14 +662,10 @@ export interface PanelHistory {
    */
   index: (id: string) => number;
 
-  /**
-   * Checks if history has no milestones.
-   */
+  /** Checks if history has no milestones. */
   isEmpty: () => boolean;
 
-  /**
-   * Gets the last milestone in history.
-   */
+  /** Gets the last milestone in history. */
   last: () => PanelHistoryMilestone | undefined;
 
   /**
@@ -721,29 +699,35 @@ export interface PanelHistory {
 
 /**
  * Options for Panel API requests.
+ * @source panel/src/panel/request.js
+ * @source panel/src/panel/feature.js
  */
 export interface PanelRequestOptions {
-  /** Request headers */
   headers?: Record<string, string>;
   /** Request body for POST/PATCH */
   body?: any;
-  /** Query parameters */
   query?: Record<string, string | number | boolean>;
-  /** AbortSignal for request cancellation */
   signal?: AbortSignal;
   /**
    * If true, skips setting `isLoading` state.
    * Useful for background requests.
    */
   silent?: boolean;
+  on?: PanelEventListenerMap;
+  /** CSRF token sent as the `x-csrf` header. */
+  csrf?: string | false;
   /**
-   * Event listeners to attach to the feature.
+   * Fiber globals sent as the `x-fiber-globals` header.
+   * Arrays are joined with commas; strings are forwarded as-is.
    */
-  on?: PanelEventListenerMap;
+  globals?: string | string[];
+  /** Referrer path sent as the `x-fiber-referrer` header. */
+  referrer?: string | false;
 }
 
 /**
  * Extended options for refresh requests.
+ * @source panel/src/panel/feature.js
  */
 export interface PanelRefreshOptions extends PanelRequestOptions {
   /** URL to refresh from (defaults to current URL) */
@@ -757,12 +741,14 @@ export interface PanelRefreshOptions extends PanelRequestOptions {
 /**
  * Panel context indicating which layer is currently active.
  * Used to determine where notifications appear and which feature has focus.
+ * @source panel/src/panel/panel.js
  */
 export type PanelContext = "view" | "dialog" | "drawer";
 
 /**
  * Context for notifications indicating where they should appear.
  * Matches the active editing layer.
+ * @source panel/src/panel/notification.js
  */
 export type NotificationContext = "view" | "dialog" | "drawer";
 
@@ -772,6 +758,7 @@ export type NotificationContext = "view" | "dialog" | "drawer";
  * - `success`: Operation completed, auto-closes
  * - `error`: Operation failed, persists until dismissed
  * - `fatal`: Critical error, displayed in isolated iframe
+ * @source panel/src/panel/notification.js
  */
 export type NotificationType = "error" | "success" | "fatal" | "info";
 
@@ -780,5 +767,6 @@ export type NotificationType = "error" | "success" | "fatal" | "info";
  * - `positive`: Green, for success
  * - `negative`: Red, for errors
  * - `info`: Blue, for information
+ * @source panel/src/panel/notification.js
  */
 export type NotificationTheme = "positive" | "negative" | "info";