kirby-types 1.4.8 → 1.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kirby-types",
   "type": "module",
-  "version": "1.4.8",
+  "version": "1.5.0",
   "packageManager": "pnpm@10.33.2",
   "description": "TypeScript types for Kirby Panel plugins and headless CMS usage",
   "author": "Johann Schopplich <hello@johannschopplich.com>",

package/src/panel/api.d.ts

@@ -3,7 +3,6 @@
  *
  * Provides types for the Panel API client and its resource modules.
  *
- * @see https://github.com/getkirby/kirby/tree/main/panel/src/api
  * @since 4.0.0
  */
 
@@ -99,7 +98,6 @@ 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 {
@@ -141,7 +139,6 @@ 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 {
@@ -247,7 +244,6 @@ 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 {
@@ -277,9 +273,9 @@ export interface PanelApiLanguages {
   /**
    * Lists all languages.
    *
-   * @returns Array of languages
+   * @returns Wrapped Kirby collection response (`{ data, pagination }`)
    */
-  list: () => Promise<any[]>;
+  list: () => Promise<any>;
 
   /**
    * Updates a language.
@@ -320,7 +316,6 @@ 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 {
@@ -500,7 +495,6 @@ 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 {
@@ -516,9 +510,9 @@ export interface PanelApiRoles {
    * Lists available roles.
    *
    * @param params - Query parameters
-   * @returns Array of roles
+   * @returns Wrapped Kirby collection response (`{ data, pagination }`)
    */
-  list: (params?: Record<string, any>) => Promise<any[]>;
+  list: (params?: Record<string, any>) => Promise<any>;
 }
 
 // -----------------------------------------------------------------------------
@@ -528,7 +522,6 @@ 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 {
@@ -604,7 +597,6 @@ 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 {
@@ -640,7 +632,6 @@ 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 {
@@ -655,9 +646,9 @@ export interface PanelApiTranslations {
   /**
    * Lists all translations.
    *
-   * @returns Array of translations
+   * @returns Wrapped Kirby collection response (`{ data, pagination }`)
    */
-  list: () => Promise<any[]>;
+  list: () => Promise<any>;
 }
 
 // -----------------------------------------------------------------------------
@@ -681,7 +672,6 @@ 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 {
@@ -796,17 +786,19 @@ export interface PanelApiUsers {
    * Queries users via the users/search endpoint.
    *
    * @param query - Query parameters
-   * @returns Array of users
+   * @returns Paginated users response
    */
-  list: (query?: Record<string, any>) => Promise<any[]>;
+  list: (query?: Record<string, any>) => Promise<any>;
 
   /**
    * Gets roles available to a user.
    *
    * @param id - User ID
-   * @returns Array of roles
+   * @returns Array of role options shaped for select inputs
    */
-  roles: (id: string) => Promise<any[]>;
+  roles: (
+    id: string,
+  ) => Promise<{ info: string; text: string; value: string }[]>;
 
   /**
    * Searches users.
@@ -828,11 +820,11 @@ export interface PanelApiUsers {
   /**
    * Gets API URL for a user.
    *
-   * @param id - User ID
+   * @param id - User ID (null for the users collection root)
    * @param path - Additional path
    * @returns API URL
    */
-  url: (id: string, path?: string) => string;
+  url: (id: string | null, path?: string) => string;
 }
 
 // -----------------------------------------------------------------------------
@@ -857,8 +849,8 @@ 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/index.ts
  * @source panel/src/api/request.js
  * @source panel/src/api/get.js
  * @source panel/src/api/post.js
@@ -875,17 +867,20 @@ export interface PanelApi {
   /** Whether to use method override */
   methodOverride: boolean;
 
-  /** Ping interval ID */
-  ping: ReturnType<typeof setInterval> | null;
+  /** Heartbeat interval ID; populated once the auth ping has been scheduled. */
+  pingId: ReturnType<typeof setInterval> | undefined;
+
+  /**
+   * Clears any existing heartbeat and schedules a new auth ping every 5 minutes.
+   * @since 6
+   */
+  ping: () => void;
 
   /** Active request IDs */
   requests: string[];
 
-  /** Number of running requests */
-  running: number;
-
-  /** Current language code (lazily set on first request, or `undefined` before any request has run) */
-  language: string | undefined;
+  /** Current language code (set from the Panel's active language on construction and refreshed on each request) */
+  language: string;
 
   /**
    * Makes a raw API request.

package/src/panel/base.d.ts

@@ -4,7 +4,6 @@
  * This module provides the foundational types for the Panel's
  * state management hierarchy: State → Feature → Modal.
  *
- * @see https://github.com/getkirby/kirby/tree/main/panel/src/panel
  * @since 4.0.0
  */
 
@@ -28,8 +27,8 @@
  * notification.set({ message: "Saved!" });
  * ```
  *
- * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/state.js
  * @source panel/src/panel/state.js
+ * @source panel/src/panel/state.ts
  */
 export interface PanelState<TDefaults extends object = Record<string, any>> {
   /**
@@ -46,9 +45,9 @@ export interface PanelState<TDefaults extends object = Record<string, any>> {
 
   /**
    * Restores the default state by calling `set(defaults())`.
-   * @returns The restored state object
+   * @returns K5 returns the restored state object; K6 narrowed the return to void.
    */
-  reset: () => TDefaults;
+  reset: () => TDefaults | void;
 
   /**
    * Sets a new state, merging with defaults.
@@ -67,73 +66,27 @@ export interface PanelState<TDefaults extends object = Record<string, any>> {
 
   /**
    * Validates that the state is a plain object.
+   *
    * @throws Error if state is not an object
+   * @deprecated K6 inlined the check into `set()` and removed the public method – calls on K6 will throw.
    */
   validateState: (state: unknown) => boolean;
 }
 
-// -----------------------------------------------------------------------------
-// State Base Types
-// -----------------------------------------------------------------------------
-
-/**
- * @internal
- * @source panel/src/panel/state.js
- */
-export interface PanelStateBase {
-  key: () => string;
-  defaults: () => Record<string, any>;
-  reset: () => Record<string, any>;
-  set: (state: Record<string, any>) => Record<string, any>;
-  state: () => Record<string, any>;
-  validateState: (state: unknown) => boolean;
-}
-
-/**
- * @internal
- * @source panel/src/panel/feature.js
- */
-export interface PanelFeatureBase extends PanelStateBase, PanelEventListeners {
-  abortController: AbortController | null;
-  component: string | null;
-  isLoading: boolean;
-  path: string | null;
-  props: Record<string, any>;
-  query: Record<string, any>;
-  referrer: string | null;
-  timestamp: number | null;
-}
-
-/**
- * @internal
- * @source panel/src/panel/modal.js
- */
-export interface PanelModalBase extends PanelFeatureBase {
-  id: string | null;
-  isOpen: boolean;
-  history: PanelHistory;
-}
-
-/**
- * @internal
- * @source panel/src/panel/history.js
- */
-export interface PanelHistoryBase {
-  milestones: PanelHistoryMilestone[];
-}
-
 // -----------------------------------------------------------------------------
 // Event Listeners
 // -----------------------------------------------------------------------------
 
 /**
  * @source panel/src/panel/listeners.js
+ * @source panel/src/panel/listeners.ts
  */
 export type PanelEventCallback<TReturn = any> = (...args: any[]) => TReturn;
 
 /**
  * Map of event names to their callback functions.
  * @source panel/src/panel/listeners.js
+ * @source panel/src/panel/listeners.ts
  */
 export type PanelEventListenerMap<TEvents extends string = string> = Partial<
   Record<TEvents, PanelEventCallback>
@@ -157,8 +110,8 @@ export type PanelEventListenerMap<TEvents extends string = string> = Partial<
  * panel.dialog.emit("submit", formData);
  * ```
  *
- * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/listeners.js
  * @source panel/src/panel/listeners.js
+ * @source panel/src/panel/listeners.ts
  */
 export interface PanelEventListeners<TEvents extends string = string> {
   on: PanelEventListenerMap<TEvents>;
@@ -185,12 +138,10 @@ export interface PanelEventListeners<TEvents extends string = string> {
    *
    * @param event - Event name to emit
    * @param args - Arguments to pass to the listener
-   * @returns Listener result, or a noop function if no listener exists
+   * @returns Listener result, or `undefined` when no listener is registered.
+   *   K5 returned a noop function in that case; K6 dropped the fallback.
    */
-  emit: <TReturn = any>(
-    event: TEvents,
-    ...args: any[]
-  ) => TReturn | (() => void);
+  emit: <TReturn = any>(event: TEvents, ...args: any[]) => TReturn | undefined;
 
   /**
    * Checks if a listener is registered for an event.
@@ -202,6 +153,21 @@ export interface PanelEventListeners<TEvents extends string = string> {
 
   /** Returns all registered listeners. */
   listeners: () => PanelEventListenerMap<TEvents>;
+
+  /**
+   * Removes the listener registered for `event`.
+   *
+   * @param event - Event name whose listener should be removed
+   * @since 6
+   */
+  removeEventListener: (event: TEvents) => void;
+
+  /**
+   * Clears every registered listener. Called automatically when feature
+   * state is replaced.
+   * @since 6
+   */
+  removeEventListeners: () => void;
 }
 
 // -----------------------------------------------------------------------------
@@ -210,6 +176,7 @@ export interface PanelEventListeners<TEvents extends string = string> {
 
 /**
  * @source panel/src/panel/feature.js
+ * @source panel/src/panel/feature.ts
  */
 export interface PanelFeatureDefaults {
   abortController: AbortController | null;
@@ -243,8 +210,8 @@ export interface PanelFeatureDefaults {
  * await panel.dropdown.open("/dropdowns/pages/home/options");
  * ```
  *
- * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/feature.js
  * @source panel/src/panel/feature.js
+ * @source panel/src/panel/feature.ts
  */
 export interface PanelFeature<TDefaults extends object = PanelFeatureDefaults>
   extends PanelState<TDefaults>, PanelEventListeners {
@@ -350,9 +317,9 @@ export interface PanelFeature<TDefaults extends object = PanelFeatureDefaults>
    * Reloads the feature by re-opening its current URL.
    *
    * @param options - Request options
-   * @returns False if no path exists, otherwise void
+   * @returns False if no path exists; K6 forwards the `open()` result, K5 returns void.
    */
-  reload: (options?: PanelRequestOptions) => Promise<void | false>;
+  reload: (options?: PanelRequestOptions) => Promise<TDefaults | false | void>;
 
   /** Creates a full URL object for the current path and query. */
   url: () => URL;
@@ -365,6 +332,7 @@ export interface PanelFeature<TDefaults extends object = PanelFeatureDefaults>
 /**
  * Modal event types for dialogs and drawers.
  * @source panel/src/panel/modal.js
+ * @source panel/src/panel/modal.ts
  */
 export type PanelModalEvent =
   | "cancel"
@@ -378,10 +346,11 @@ export type PanelModalEvent =
 /**
  * Bound listener functions returned by `modal.listeners()`.
  * @source panel/src/panel/modal.js
+ * @source panel/src/panel/modal.ts
  */
 export interface PanelModalListeners {
   cancel: () => Promise<void>;
-  close: (id?: string | boolean) => Promise<void>;
+  close: (id?: string | true) => Promise<void>;
   input: (value: any) => void;
   submit: (value?: any, options?: PanelRequestOptions) => Promise<any>;
   success: (response: PanelSuccessResponse) => void;
@@ -391,6 +360,7 @@ export interface PanelModalListeners {
 /**
  * Success response from modal submission.
  * @source panel/src/panel/modal.js
+ * @source panel/src/panel/modal.ts
  */
 export interface PanelSuccessResponse {
   message?: string;
@@ -432,8 +402,8 @@ export interface PanelSuccessResponse {
  * panel.drawer.goTo("previous-drawer-id");
  * ```
  *
- * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/modal.js
  * @source panel/src/panel/modal.js
+ * @source panel/src/panel/modal.ts
  */
 export interface PanelModal<
   TDefaults extends object = PanelFeatureDefaults & { id: string | null },
@@ -467,7 +437,7 @@ export interface PanelModal<
    * @param id - Specific modal ID, `true` to close all, or undefined for current
    * @returns Promise resolving to the previous modal's state, or void
    */
-  close: (id?: string | boolean) => Promise<TDefaults | void>;
+  close: (id?: string | true) => Promise<TDefaults | void>;
 
   /**
    * Sets focus to the first focusable input or a specific input.
@@ -514,9 +484,9 @@ export interface PanelModal<
    * Reloads the modal by closing and reopening at the same URL.
    *
    * @param options - Request options
-   * @returns False if no path exists, otherwise void
+   * @returns False if no path exists; K6 forwards the `open()` result, K5 returns void.
    */
-  reload: (options?: PanelRequestOptions) => Promise<void | false>;
+  reload: (options?: PanelRequestOptions) => Promise<TDefaults | false | void>;
 
   /**
    * Sets modal state, auto-generating an ID if not provided.
@@ -578,6 +548,7 @@ export interface PanelModal<
 /**
  * A history milestone representing a saved modal state.
  * @source panel/src/panel/history.js
+ * @source panel/src/helpers/history.ts
  */
 export interface PanelHistoryMilestone {
   id: string;
@@ -601,8 +572,8 @@ export interface PanelHistoryMilestone {
  * }
  * ```
  *
- * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/history.js
  * @source panel/src/panel/history.js
+ * @source panel/src/helpers/history.ts
  */
 export interface PanelHistory {
   milestones: PanelHistoryMilestone[];
@@ -654,6 +625,12 @@ export interface PanelHistory {
    */
   has: (id: string) => boolean;
 
+  /**
+   * Returns true when more than one milestone is stored.
+   * @since 6
+   */
+  hasPrevious: () => boolean;
+
   /**
    * Gets the array index of a milestone.
    *
@@ -701,6 +678,8 @@ export interface PanelHistory {
  * Options for Panel API requests.
  * @source panel/src/panel/request.js
  * @source panel/src/panel/feature.js
+ * @source panel/src/panel/request.ts
+ * @source panel/src/panel/feature.ts
  */
 export interface PanelRequestOptions {
   headers?: Record<string, string>;
@@ -717,17 +696,18 @@ export interface PanelRequestOptions {
   /** CSRF token sent as the `x-csrf` header. */
   csrf?: string | false;
   /**
-   * Fiber globals sent as the `x-fiber-globals` header.
+   * Globals sent as the `x-panel-globals` header (was `x-fiber-globals` in K5).
    * Arrays are joined with commas; strings are forwarded as-is.
    */
   globals?: string | string[];
-  /** Referrer path sent as the `x-fiber-referrer` header. */
+  /** Referrer path sent as the `x-panel-referrer` header (was `x-fiber-referrer` in K5). */
   referrer?: string | false;
 }
 
 /**
  * Extended options for refresh requests.
  * @source panel/src/panel/feature.js
+ * @source panel/src/panel/feature.ts
  */
 export interface PanelRefreshOptions extends PanelRequestOptions {
   /** URL to refresh from (defaults to current URL) */
@@ -742,25 +722,21 @@ 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
+ * @source panel/src/panel/notification.ts
  */
-export type NotificationContext = "view" | "dialog" | "drawer";
+export type PanelContext = "view" | "dialog" | "drawer";
 
 /**
  * Type of notification determining behavior and persistence.
- * - `info`: General information, auto-closes
- * - `success`: Operation completed, auto-closes
+ * Only `error` and `fatal` are written to `state.type`; `success()` and
+ * `info()` shortcuts set `theme` (and `icon`) instead of `type`.
  * - `error`: Operation failed, persists until dismissed
  * - `fatal`: Critical error, displayed in isolated iframe
  * @source panel/src/panel/notification.js
+ * @source panel/src/panel/notification.ts
  */
-export type NotificationType = "error" | "success" | "fatal" | "info";
+export type NotificationType = "error" | "fatal";
 
 /**
  * Visual theme for notifications.
@@ -768,5 +744,6 @@ export type NotificationType = "error" | "success" | "fatal" | "info";
  * - `negative`: Red, for errors
  * - `info`: Blue, for information
  * @source panel/src/panel/notification.js
+ * @source panel/src/panel/notification.ts
  */
 export type NotificationTheme = "positive" | "negative" | "info";