kirby-types 1.4.7 → 1.4.9

package/src/panel/index.d.ts

@@ -224,6 +224,8 @@ export type {
  * const slug = this.$helper.slug("My Page Title");
  * const date = this.$library.dayjs("2024-01-15").format("DD.MM.YYYY");
  * ```
+ * @source panel/src/panel/app.js
+ * @source panel/src/index.js
  */
 export type PanelApp = InstanceType<VueConstructor> & {
   $library: PanelLibrary;
@@ -242,6 +244,7 @@ export type PanelApp = InstanceType<VueConstructor> & {
  * Components can be defined as:
  * - Vue component options object with template or render function
  * - Component that extends another component by name
+ * @source panel/src/panel/plugins.js
  */
 export type PanelComponentExtension =
   | DefineComponent<any, any, any, any, any, any, any, any, any, any, any>
@@ -280,6 +283,8 @@ export type PanelComponentExtension =
  * Global Panel configuration.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/config/config.js
+ * @source panel/src/panel/panel.js
+ * @source src/Panel/View.php
  */
 export interface PanelConfig {
   /** API configuration */
@@ -305,6 +310,8 @@ export interface PanelConfig {
 
 /**
  * Access permissions for Panel areas.
+ * @source src/Cms/Permissions.php
+ * @source src/Cms/UserPermissions.php
  */
 interface PanelPermissionsAccess {
   account: boolean;
@@ -317,6 +324,8 @@ interface PanelPermissionsAccess {
 
 /**
  * File operation permissions.
+ * @source src/Cms/Permissions.php
+ * @source src/Cms/FilePermissions.php
  */
 interface PanelPermissionsFiles {
   access: boolean;
@@ -333,6 +342,8 @@ interface PanelPermissionsFiles {
 
 /**
  * Language operation permissions.
+ * @source src/Cms/Permissions.php
+ * @source src/Cms/LanguagePermissions.php
  */
 interface PanelPermissionsLanguages {
   create: boolean;
@@ -342,6 +353,8 @@ interface PanelPermissionsLanguages {
 
 /**
  * Page operation permissions.
+ * @source src/Cms/Permissions.php
+ * @source src/Cms/PagePermissions.php
  */
 interface PanelPermissionsPages {
   access: boolean;
@@ -362,16 +375,22 @@ interface PanelPermissionsPages {
 
 /**
  * Site operation permissions.
+ * @source src/Cms/Permissions.php
+ * @source src/Cms/SitePermissions.php
  */
 interface PanelPermissionsSite {
+  access: boolean;
   changeTitle: boolean;
   update: boolean;
 }
 
 /**
  * User management permissions (for other users).
+ * @source src/Cms/Permissions.php
+ * @source src/Cms/UserPermissions.php
  */
 interface PanelPermissionsUsers {
+  access: boolean;
   changeEmail: boolean;
   changeLanguage: boolean;
   changeName: boolean;
@@ -379,19 +398,24 @@ interface PanelPermissionsUsers {
   changeRole: boolean;
   create: boolean;
   delete: boolean;
+  list: boolean;
   update: boolean;
 }
 
 /**
  * Current user permissions (for own account).
+ * @source src/Cms/Permissions.php
+ * @source src/Cms/UserPermissions.php
  */
 interface PanelPermissionsUser {
+  access: boolean;
   changeEmail: boolean;
   changeLanguage: boolean;
   changeName: boolean;
   changePassword: boolean;
   changeRole: boolean;
   delete: boolean;
+  list: boolean;
   update: boolean;
 }
 
@@ -399,6 +423,8 @@ interface PanelPermissionsUser {
  * Complete permission set for the current user.
  *
  * @see https://getkirby.com/docs/reference/plugins/extensions/permissions
+ * @source src/Cms/Permissions.php
+ * @source src/Cms/Role.php
  */
 export interface PanelPermissions {
   access: PanelPermissionsAccess;
@@ -416,18 +442,18 @@ export interface PanelPermissions {
 
 /**
  * Search type definition.
+ * @source src/Panel/View.php
  */
 export interface PanelSearchType {
-  /** Icon for the search type */
   icon: string;
-  /** Display label */
   label: string;
-  /** Unique identifier */
   id: string;
 }
 
 /**
  * Available search types in the Panel.
+ * @source panel/src/panel/panel.js
+ * @source src/Panel/View.php
  */
 export interface PanelSearches {
   pages: PanelSearchType;
@@ -442,11 +468,10 @@ export interface PanelSearches {
 
 /**
  * Base URLs for Panel operations.
+ * @source panel/src/panel/panel.js
  */
 export interface PanelUrls {
-  /** API endpoint URL */
   api: string;
-  /** Site URL */
   site: string;
 }
 
@@ -458,12 +483,13 @@ export interface PanelUrls {
  * Response object from Panel requests.
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/request.js
+ * @source panel/src/panel/request.js
  */
 export interface PanelRequestResponse {
   /** The original Request object */
   request: Request;
-  /** The parsed response */
-  response: {
+  /** Native `Response` mutated so that `text` and `json` are pre-resolved properties (not callable methods). */
+  response: Response & {
     /** Parsed JSON data */
     json: any;
     /** Raw response text */
@@ -526,6 +552,7 @@ export interface PanelRequestResponse {
  * ```
  *
  * @see https://getkirby.com/docs/reference/plugins/extensions
+ * @source panel/public/js/plugins.js
  */
 export interface PanelPluginExtensions {
   /**
@@ -651,6 +678,8 @@ export interface PanelPluginExtensions {
  * Properties are ordered to match `panel/public/js/plugins.js`.
  *
  * @see https://getkirby.com/docs/reference/plugins/extensions
+ * @source panel/src/panel/plugins.js
+ * @source panel/public/js/plugins.js
  */
 export interface PanelPlugins {
   // ---------------------------------------------------------------------------
@@ -714,7 +743,7 @@ export interface PanelPlugins {
     any
   > | null;
 
-  /** Registered Panel routes */
+  /** Reserved bucket for plugin-registered routes (initialized empty; not currently written to by `panel.plugin()`). */
   routes: Record<string, any>[];
 
   /**
@@ -729,14 +758,14 @@ export interface PanelPlugins {
   /** Installed Vue plugins via `Vue.use()` */
   use: (PluginObject<any> | PluginFunction<any>)[];
 
-  /** Registered view buttons */
+  /** Reserved bucket for view-button plugins (initialized empty; entries are actually stored under `components` as `k-${name}-view-button`). */
   viewButtons: Record<
     string,
     | DefineComponent<any, any, any, any, any, any, any, any, any, any, any>
     | Record<string, any>
   >;
 
-  /** Registered Panel views */
+  /** Reserved bucket for plugin-registered views (initialized empty; not currently written to by `panel.plugin()`). */
   views: Record<string, Record<string, any>>;
 
   /**
@@ -758,18 +787,21 @@ export interface PanelPlugins {
 
 /**
  * Language information for multi-language sites.
+ * @source src/Cms/Language.php
+ * @source src/Panel/View.php
  */
 export interface PanelLanguageInfo {
   /** Language code (e.g., `"en"`, `"de"`) */
   code: string;
   /** Whether this is the default language */
   default: boolean;
-  /** Text direction */
   direction: "ltr" | "rtl";
-  /** Display name */
+  /** Whether the configured language `url` is an absolute URL (i.e., starts with `http://` or `https://`). */
+  hasCustomDomain: boolean;
   name: string;
-  /** Slug conversion rules */
   rules: Record<string, string>;
+  /** Absolute URL for this language (always resolved against the site URL via `Url::makeAbsolute`). */
+  url: string;
 }
 
 // -----------------------------------------------------------------------------
@@ -778,6 +810,7 @@ export interface PanelLanguageInfo {
 
 /**
  * Global Panel state for `panel.state()`.
+ * @source panel/src/panel/panel.js
  */
 export interface PanelGlobalState {
   activation: PanelFeatures.PanelActivationDefaults;
@@ -821,6 +854,9 @@ export interface PanelGlobalState {
  * ```
  *
  * @see https://github.com/getkirby/kirby/blob/main/panel/src/panel/panel.js
+ * @source panel/src/panel/panel.js
+ * @source panel/src/index.js
+ * @source panel/public/js/plugins.js
  */
 export interface Panel {
   // ---------------------------------------------------------------------------
@@ -839,10 +875,10 @@ export interface Panel {
   /** Text direction */
   readonly direction: "ltr" | "rtl";
 
-  /** Document title */
+  /** Document title getter/setter; on set, the system title is appended as a suffix when present. */
   title: string;
 
-  /** Whether any feature is loading */
+  /** Whether the Panel is currently loading a new view via `open()`. */
   isLoading: boolean;
 
   /** Whether the browser is offline */
@@ -962,7 +998,7 @@ export interface Panel {
   deprecated: (message: string) => void;
 
   /**
-   * Handles an error, optionally opening a notification.
+   * Centralized error handler: ignores `AbortError`, marks the Panel offline on `OfflineError`, logs in debug mode, and optionally opens an error notification.
    *
    * @param error - Error or message
    * @param openNotification - Whether to show notification (default: true)
@@ -1104,7 +1140,7 @@ export interface Panel {
   };
 
   /**
-   * Sets global Panel state.
+   * Applies a new Panel state: updates globals, dispatches per-feature `set()` calls, opens/closes modals and the dropdown, and opens the view when present.
    *
    * @param state - State to merge
    */
@@ -1129,7 +1165,7 @@ export interface Panel {
   /**
    * Creates a URL object for a Panel path.
    *
-   * @param path - Path (default: current path)
+   * @param path - Path or URL to build (default: empty string)
    * @param query - Query parameters
    * @param origin - Base origin
    * @returns URL object
@@ -1143,6 +1179,7 @@ export interface Panel {
 
 /**
  * Lock information for content.
+ * @source src/Content/Lock.php
  */
 interface PanelViewPropsLockUser {
   id: string;
@@ -1151,6 +1188,8 @@ interface PanelViewPropsLockUser {
 
 /**
  * Content lock state.
+ * @source src/Content/Lock.php
+ * @source src/Panel/Model.php
  */
 interface PanelViewPropsLock {
   isLegacy: boolean;
@@ -1161,9 +1200,25 @@ interface PanelViewPropsLock {
 
 /**
  * Content permissions for a view.
+ * @source src/Cms/ModelPermissions.php
+ * @source src/Cms/PageBlueprint.php
+ * @source src/Cms/FileBlueprint.php
+ * @source src/Cms/UserBlueprint.php
+ * @source src/Cms/SiteBlueprint.php
+ * @source src/Panel/Site.php
  */
 interface PanelViewPropsPermissions {
   access: boolean;
+  /** User permission. Present on User views. */
+  changeEmail?: boolean;
+  /** User permission. Present on User views. */
+  changeLanguage?: boolean;
+  /** File / User permission. Present on File and User views. */
+  changeName?: boolean;
+  /** User permission. Present on User views. */
+  changePassword?: boolean;
+  /** User permission. Present on User views. */
+  changeRole?: boolean;
   changeSlug: boolean;
   changeStatus: boolean;
   changeTemplate: boolean;
@@ -1175,12 +1230,15 @@ interface PanelViewPropsPermissions {
   move: boolean;
   preview: boolean;
   read: boolean;
+  /** File permission. Present on File views. */
+  replace?: boolean;
   sort: boolean;
   update: boolean;
 }
 
 /**
  * Version information.
+ * @source src/Panel/Model.php
  */
 interface PanelViewPropsVersions {
   latest: Record<string, any>;
@@ -1189,6 +1247,7 @@ interface PanelViewPropsVersions {
 
 /**
  * Tab definition.
+ * @source src/Cms/Blueprint.php
  */
 interface PanelViewPropsTab {
   label: string;
@@ -1200,6 +1259,10 @@ interface PanelViewPropsTab {
 
 /**
  * Navigation link (next/prev).
+ * @source src/Panel/Model.php
+ * @source src/Panel/Page.php
+ * @source src/Panel/File.php
+ * @source src/Panel/User.php
  */
 interface PanelViewPropsNavigation {
   link: string;
@@ -1207,7 +1270,11 @@ interface PanelViewPropsNavigation {
 }
 
 /**
- * Model information.
+ * Legacy model information (deprecated; use the top-level view props instead).
+ * @source src/Panel/Page.php
+ * @source src/Panel/File.php
+ * @source src/Panel/User.php
+ * @source src/Panel/Site.php
  */
 interface PanelViewPropsModel {
   id: string;
@@ -1221,18 +1288,39 @@ interface PanelViewPropsModel {
 
 /**
  * Button definition.
+ * @source src/Panel/Ui/Buttons/ViewButton.php
+ * @source src/Panel/Ui/Buttons/ViewButtons.php
+ * @source src/Panel/Ui/Component.php
  */
 interface PanelViewPropsButton {
   component: string;
   key: string;
   props: {
+    /** Optional badge label rendered next to the button. */
+    badge?: string;
     class?: string;
+    /** Whether the button represents the current view/route. */
+    current?: boolean;
+    /** Dialog endpoint or config to open on click. */
+    dialog?: string | Record<string, any>;
     disabled?: boolean;
+    /** Drawer endpoint or config to open on click. */
+    drawer?: string | Record<string, any>;
+    /** Dropdown endpoint or config to open on click. */
+    dropdown?: string | Record<string, any>;
     icon?: string;
     link?: string;
+    /** Inline dropdown options. */
+    options?: Record<string, any>[];
     responsive?: boolean;
     size?: string;
+    /** Inline CSS style string. */
+    style?: string;
     target?: string;
+    /** Visible button label. */
+    text?: string;
+    /** Visual theme variant (e.g., `"positive"`, `"negative"`). */
+    theme?: string;
     title?: string;
     type?: string;
     variant?: string;
@@ -1241,10 +1329,19 @@ interface PanelViewPropsButton {
 
 /**
  * Common view props passed from backend.
+ * @source src/Panel/Model.php
+ * @source src/Panel/Page.php
+ * @source src/Panel/File.php
+ * @source src/Panel/User.php
+ * @source src/Panel/Site.php
  */
 export interface PanelViewProps {
   api: string;
-  buttons: PanelViewPropsButton[];
+  /**
+   * View buttons. May contain `'-'` string separators between groups.
+   * @source src/Panel/Ui/Buttons/ViewButtons.php
+   */
+  buttons: (PanelViewPropsButton | "-")[];
   id: string;
   link: string;
   lock: PanelViewPropsLock;
@@ -1252,9 +1349,20 @@ export interface PanelViewProps {
   tabs: Record<string, any>[];
   uuid: string;
   versions: PanelViewPropsVersions;
-  tab: PanelViewPropsTab;
-  next: PanelViewPropsNavigation;
-  prev: PanelViewPropsNavigation;
+  /** Active blueprint tab. Only present when the blueprint defines tabs. */
+  tab?: PanelViewPropsTab;
+  /**
+   * Sibling navigation link to the next model. Present on Page, File and
+   * User views (may be `null` when there is no next sibling); not emitted
+   * for Site.
+   */
+  next?: PanelViewPropsNavigation | null;
+  /**
+   * Sibling navigation link to the previous model. Present on Page, File
+   * and User views (may be `null` when there is no previous sibling); not
+   * emitted for Site.
+   */
+  prev?: PanelViewPropsNavigation | null;
   blueprint: string;
   model: PanelViewPropsModel;
   title: string;